DM-ROW 接口文档

Appearance

组织架构管理 ​

**本文引用的文件** - [DepartmentController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/DepartmentController.java) - [DepartmentServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/service/impl/DepartmentServiceImpl.java) - [DepartmentMapper.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/dao/DepartmentMapper.java) - [DepartmentApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/api/DepartmentApi.java) - [DepartmentDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/entity/DepartmentDo.java) - [DepartmentVo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/vo/outer/DepartmentVo.java) - [DeptVo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/vo/outer/DeptVo.java) - [SysDepartmentVo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/vo/model/SysDepartmentVo.java) - [UserDeptDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/entity/UserDeptDo.java) - [UserDeptVo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/vo/outer/UserDeptVo.java) - [Tree.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/tools/entity/Tree.java) - [DepartmentClient.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-common/src/main/java/com/lenovo/lemes/service/dm/device/client/feign/DepartmentClient.java) - [StoreMainVo.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/model/store/StoreMainVo.java) - [README.md](file://lemes-cloud/lemes-business-devicemate/README.md) - [AGENTS.md](file://lemes-cloud/lemes-business-devicemate/AGENTS.md)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件面向“组织架构管理系统”的技术文档，聚焦于部门管理功能的实现原理与最佳实践，包括组织架构树形结构设计、部门层级关系管理、部门属性配置、部门与用户的关联关系，以及在设备管理与仓储管理等业务模块中的应用方式。同时提供部门管理API接口的完整说明，并给出性能优化与排障建议。

项目结构 ​

组织架构管理位于公共服务模块（dm-common），并被设备服务（dm-device）与仓储作业（job-devicemate）所复用。整体采用微服务分层：公共能力（common）+ 服务实现（server），并通过 Feign 客户端在业务服务间进行调用。

图示来源

章节来源

核心组件 ​

  • 控制器层：提供部门管理的REST接口，负责参数接收、入参校验、调用服务层并返回统一响应。
  • 服务实现层：封装业务逻辑，包括树形结构生成、部门增删改查、名称/编号唯一性校验、基于用户的部门树构建等。
  • 数据访问层：MyBatis Mapper，提供部门数据查询、批量删除、按用户/工厂/部门号查询等SQL映射。
  • 对外API接口：定义公共接口契约，供其他服务（如设备服务）通过Feign调用。
  • 实体与视图对象：DepartmentDo（持久化实体）、DeptVo（树形展示VO）、SysDepartmentVo（通用部门VO）、UserDeptDo/VO（用户-部门关联）。
  • 工具类：Tree<T>（树节点通用结构）。

章节来源

架构总览 ​

组织架构管理采用“控制器-服务-数据访问-实体/VO”的分层架构，配合统一返回体与日志注解，确保接口稳定与可观测。设备服务通过Feign客户端调用dm-common提供的部门接口，实现跨服务的数据共享与权限约束。

图示来源

详细组件分析 ​

部门实体模型设计 ​

  • DepartmentDo：持久化实体，对应数据库表 sys_department，包含上级部门ID、部门代号、部门编码、描述、名称、经理、主管、是否删除等字段。
  • DepartmentVo/SysDepartmentVo：对外展示/通用VO，用于接口返回与跨服务传递，字段与DepartmentDo一致但命名风格更偏向API层。
  • DeptVo：树形展示专用VO，扩展了children字段，支持递归构建组织树。
  • UserDeptDo/UserDeptVo：用户-部门关联实体/VO，建立用户与部门之间的多对多关系（以部门代号/用户代号维度）。

图示来源

章节来源

组织架构树形结构设计与层级关系管理 ​

  • 树形构建：服务层通过递归方法从扁平数据集中筛选根节点并逐级拼接子节点，形成树形结构；支持按用户权限过滤根节点。
  • 层级关系：通过 parentId 字段表达父子层级；DeptVo 在原有字段基础上增加 children，便于前端渲染。
  • 工厂隔离：查询时结合当前用户所在工厂（factoryNo）进行过滤，确保数据隔离。

图示来源

章节来源

部门属性配置与校验 ​

  • 关键属性：parentId、deptNo、deptCode、deptName、description、deptManager、deptCharge。
  • 校验规则：新增/修改时校验必填字段与唯一性（名称、编号），避免重复；删除前检查是否存在子部门。
  • 工厂与序列：新增时若未提供部门代号，通过Redis序列号生成；设置当前工厂号；统一创建/更新人与时间。

章节来源

部门与用户的关系 ​

  • 用户-部门关联：UserDeptDo/VO 通过 userNo 与 deptNo 建立关联，支持按用户查询其可访问的部门树。
  • 权限树构建：当用户未绑定部门时，默认返回当前工厂全部部门；否则仅返回用户所属部门及其下级。

章节来源

在设备管理与仓储管理中的应用 ​

  • 设备服务（dm-device）通过 Feign 客户端调用 dm-common 的部门接口，获取当前用户可访问的部门树，用于设备台账、工单等业务的部门维度过滤。
  • 仓储作业（job-devicemate）在仓储主数据模型 StoreMainVo 中保留 deptNo/deptName 字段，用于标识仓库所属部门，实现数据隔离与权限控制。

图示来源

章节来源

部门管理API接口文档 ​

  • 部门列表
    • 方法：POST
    • 路径：/dept/list
    • 请求体：DeptVo（可选过滤条件：deptName、deptCode）
    • 返回：树形部门列表
  • 获取用户权限的部门列表
    • 方法：POST
    • 路径：/dept/listByUser
    • 返回：当前用户可访问的部门树
  • 新增部门
    • 方法：POST
    • 路径：/dept/add
    • 请求体：DeptVo（校验名称长度、编号长度）
    • 返回：新增后的部门
  • 修改部门
    • 方法：POST
    • 路径：/dept/update
    • 请求体：DeptVo（自动注入工厂号）
    • 返回：成功状态
  • 删除部门
    • 方法：POST
    • 路径：/dept/delDept
    • 请求体：DeptVo（删除前检查是否有子部门）
    • 返回：成功状态
  • 校验部门名称是否重复
    • 方法：POST
    • 路径：/dept/checkDeptName
    • 请求体：DeptVo
    • 返回：是否存在重复
  • 部门详情
    • 方法：POST
    • 路径：/dept/details
    • 请求体：DepartmentDo（id）
    • 返回：部门详情
  • 获取部门列表（通用）
    • 方法：GET
    • 路径：/dept/getDept
    • 返回：SysDepartmentVo 列表
  • 根据部门代号查询
    • 方法：GET
    • 路径：/dept/deptNo?deptNo=...
    • 返回：SysDepartmentVo
  • 根据部门名称查询
    • 方法：GET
    • 路径：/dept/deptName?deptName=...
    • 返回：SysDepartmentVo
  • 当前登录人及其下级部门
    • 方法：GET
    • 路径：/dept/current/user
    • 返回：SysDepartmentVo 列表
  • 指定部门及其下级部门
    • 方法：GET
    • 路径：/dept/by/deptNo?deptNo=...
    • 返回：SysDepartmentVo 列表
  • 查询我的当前工厂下的部门
    • 方法：POST
    • 路径：/dept/queryMyCurrentFactoryDepart
    • 返回：DepartmentDo 列表

章节来源

依赖分析 ​

  • 控制器依赖服务实现；服务实现依赖Mapper与Redis序列号服务；对外通过Feign暴露API；设备服务通过Feign客户端消费dm-common接口。
  • 用户-部门关联表（sys_user_dept）支撑权限树构建与数据隔离。

图示来源

性能考虑 ​

  • 树形构建复杂度：递归构建树的时间复杂度为 O(n)，建议在数据量较大时对输入参数进行限制与分页策略（当前接口为一次性拉取全量数据）。
  • 缓存策略：部门树与常用查询结果可引入Redis缓存，减少数据库压力；注意缓存失效与一致性。
  • 并发控制：新增/修改/删除涉及事务，需关注热点部门的并发冲突；必要时引入乐观锁或分布式锁。
  • 分页与过滤：对于超大规模组织，建议提供分页查询与多维过滤（如按工厂、按名称关键字）以降低内存占用。
  • 异步化：批量删除/更新工厂维度数据可异步执行，避免阻塞主线程。

故障排查指南 ​

  • 新增失败：检查必填字段与唯一性校验（名称/编号重复）；查看服务层抛出的自定义异常码。
  • 删除失败：若提示存在子部门，需先清理子部门后再删除。
  • 权限树为空：确认用户是否绑定了部门；若未绑定，默认返回当前工厂全部部门。
  • 跨服务调用失败：检查Feign客户端配置与dm-common服务地址；确认Nacos注册与网络连通性。

章节来源

结论 ​

组织架构管理通过清晰的分层设计与统一的API契约，实现了部门树形结构的高效构建与权限隔离。在设备管理与仓储作业中，通过部门维度实现数据隔离与权限控制，满足制造场景下的多工厂、多部门管理需求。建议在生产环境中引入缓存、分页与异步化策略，持续优化性能与稳定性。

附录 ​

  • 服务默认端口：dm-common=8040、dm-device=8041、dm-store=8042、dm-workflow=8043。
  • 外部依赖：PostgreSQL、Redis、Nacos。
  • 项目结构概览与模块职责详见项目文档。

章节来源