DM-ROW 接口文档

Appearance

后端服务详解 ​

**本文引用的文件** - [lemes-business-devicemate/README.md](file://lemes-business-devicemate/README.md) - [lemes-business-devicemate/pom.xml](file://lemes-business-devicemate/pom.xml) - [lemes-business-devicemate/AGENTS.md](file://lemes-business-devicemate/AGENTS.md) - [lemes-business-devicemate/lemes-service-dm-common/readme.md](file://lemes-business-devicemate/lemes-service-dm-common/readme.md) - [lemes-business-devicemate/lemes-service-dm-device/readme.md](file://lemes-business-devicemate/lemes-service-dm-device/readme.md) - [lemes-business-devicemate/lemes-service-dm-store/readme.md](file://lemes-business-devicemate/lemes-service-dm-store/readme.md) - [lemes-business-devicemate/lemes-service-dm-workflow/readme.md](file://lemes-business-devicemate/lemes-service-dm-workflow/readme.md) - [lemes-business-devicemate/lemes-service-dm-workflow/pom.xml](file://lemes-business-devicemate/lemes-service-dm-workflow/pom.xml) - [lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/pom.xml](file://lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/pom.xml) - [docs/ddl/device.sql](file://docs/ddl/device.sql) - [docs/ddl/store.sql](file://docs/ddl/store.sql) - [docs/ddl/workflow.sql](file://docs/ddl/workflow.sql) - [lemes-cloud/lemes-gateway/pom.xml](file://lemes-cloud/lemes-gateway/pom.xml) - [lemes-cloud/AGENTS.md](file://lemes-cloud/AGENTS.md) - [dm/lemes-web/src/components/bpmnModeler/flowable/init.js](file://dm/lemes-web/src/components/bpmnModeler/flowable/init.js) - [dm/lemes-web/src/components/bpmnModeler/flowable/flowable.json](file://dm/lemes-web/src/components/bpmnModeler/flowable/flowable.json)

目录 ​

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

引言 ​

本文件面向 DeviceMate 后端微服务，系统化梳理公共服务（dm-common）、设备服务（dm-device）、仓储服务（dm-store）、工作流服务（dm-workflow）四大核心域的职责边界、数据模型、服务间通信与集成方式，并结合部署与监控实践给出可操作的建议与最佳实践。文档同时提供架构图与流程图，帮助读者快速建立对系统的整体认知。

项目结构 ​

DeviceMate 后端位于 lemes-cloud 聚合工程之下，采用多模块 + Spring Cloud 的微服务体系。业务域以 lemes-business-devicemate 为聚合根，内部进一步拆分为 dm-common、dm-device、dm-store、dm-workflow 四个子模块，每个子模块均包含公共层（-common）与服务层（-server）两个子模块，形成“公共能力沉淀 + 服务边界清晰”的分层组织。

  • 聚合与版本：顶层 lemes-cloud 聚合工程统一管理版本与依赖，lemes-business-devicemate 作为业务域聚合，定义四大服务模块。
  • 网关与注册中心：lemes-gateway 提供路由与重试能力；各服务通过 Nacos 进行服务发现与配置管理。
  • 默认端口：dm-common=8040、dm-device=8041、dm-store=8042、dm-workflow=8043。
  • Swagger 文档：各服务启动后可通过 /swagger-ui.html 访问接口文档。

图表来源

章节来源

核心组件 ​

  • 公共服务（dm-common）
    • 职责：用户/角色/权限、组织架构、系统配置、字典、文件、附件等通用能力下沉，供其他服务复用。
    • 通信：通过 Feign 客户端在服务间调用；常见接口包括用户查询、部门树、字典项、文件上传等。
    • 数据：基于 PostgreSQL 的通用表结构，配合 Redis 缓存热点配置与字典。
  • 设备服务（dm-device）
    • 职责：设备台账、点检/巡检、维修工单、维护计划、过程与胶水相关数据。
    • 数据：设备主数据、线体/产线、制造商、物料主数据、胶水入库/使用记录、报废单据等。
  • 仓储服务（dm-store）
    • 职责：库存管理、出入库、借还、调拨转移、盘点、成本统计。
    • 数据：库存主表、明细表、出入库单据、调拨单据、安全库存、成本统计等。
  • 工作流服务（dm-workflow）
    • 职责：基于 Flowable 的流程引擎集成，提供流程定义、任务、审批日志、用户与角色映射、节点配置等。
    • 集成：通过 Flowable Engine 与业务单据联动，支持流程回退、参数校验、节点配置等。

章节来源

架构总览 ​

DeviceMate 微服务采用“领域服务 + 公共能力 + 网关 + 注册中心”的分层架构。服务间通过 Feign 进行声明式调用，统一接入网关进行路由与限流/重试；配置与注册通过 Nacos 管理。工作流域独立于业务域之上，提供流程编排能力并与业务单据解耦。

图表来源

详细组件分析 ​

公共服务（dm-common） ​

  • 能力边界
    • 用户与组织：用户查询、部门树、角色/权限映射。
    • 配置与字典：系统配置、数据字典、国际化资源。
    • 文件与附件：文件上传、下载、元数据管理。
  • 通信机制
    • 服务内通过 Feign 客户端暴露 API，供其他服务调用。
    • 常见调用链：业务服务 -> dm-common -> 数据库/缓存。
  • 数据一致性
    • 对高频读取的数据（如字典、配置）采用 Redis 缓存，降低数据库压力。
    • 写操作采用幂等设计与唯一索引约束，避免并发冲突。
  • 性能优化
    • 合理设置缓存 TTL 与失效策略，结合异步刷新保障一致性。
    • 对热点接口开启限流与熔断（Hystrix）保护。

图表来源

章节来源

设备服务（dm-device） ​

  • 能力边界
    • 设备台账：设备主数据、线体/产线、制造商、物料主数据。
    • 维护与工单：点检/巡检、维修工单、维护计划、胶水相关流程。
  • 数据模型
    • 关键表：line（线体）、manufacturer（制造商）、part_main（物料主数据）、paste_*（胶水相关）等。
  • 事务与一致性
    • 设备与胶水出入库涉及库存与工单状态联动，建议采用本地消息表或事件驱动确保最终一致。
    • 对关键写操作（如报废、入库）增加幂等校验与唯一约束。
  • 性能优化
    • 对设备检索与工单列表采用分页与索引优化。
    • 对高频统计（如成本统计）采用定时任务预计算并落库。

图表来源

章节来源

仓储服务（dm-store） ​

  • 能力边界
    • 库存管理：主表/明细、安全库存、成本统计。
    • 出入库与调拨：入库单、出库单、借还、调拨转移、盘点。
  • 数据模型
    • 关键表：stock_main（库存主表）、stock_detail（明细）、store_in_orders（入库单）、store_transfer_orders（调拨单）等。
  • 事务与一致性
    • 入出库与库存变动需保证原子性，建议使用数据库事务包裹。
    • 对高并发场景采用乐观锁或分布式锁，避免超卖/重复记账。
  • 性能优化
    • 对库存查询加索引（工厂+仓库+物料组合），减少全表扫描。
    • 成本统计采用批量计算与缓存，降低实时计算压力。

图表来源

章节来源

工作流服务（dm-workflow） ​

  • 能力边界
    • 流程引擎：流程定义、任务、审批日志、节点配置、用户与角色映射。
    • 业务集成：与设备/仓储单据联动，支持流程回退、参数校验与节点控制。
  • 技术栈
    • Flowable 7.0.0 引擎，提供 BPMN 2.0 支持与扩展属性。
  • 集成方式
    • 通过 Flowable Engine 启动流程实例，绑定业务单据与表单参数。
    • 审批日志与节点配置持久化，便于审计与追溯。
  • 流程建模
    • 前端提供 BPMN 编辑器，支持动态生成最小流程定义并注入到引擎。

图表来源

章节来源

依赖分析 ​

  • 模块聚合
    • lemes-business-devicemate 作为业务域聚合，包含 dm-common、dm-device、dm-store、dm-workflow 四个子模块。
  • 外部依赖
    • Spring Cloud Gateway：统一路由与重试。
    • Nacos：服务发现与配置中心。
    • Flowable：流程引擎。
    • Swagger/EasyPOI/Redisson/Hystrix/Validation：业务层常用能力。
  • 服务间依赖
    • dm-device/dm-store 可能依赖 dm-common 的用户/字典/文件能力。
    • dm-workflow 依赖 dm-common 的用户/角色/组织能力用于审批。

图表来源

章节来源

性能考虑 ​

  • 数据库层面
    • 为高频查询字段建立复合索引（如工厂+仓库+物料、单号唯一索引）。
    • 对大表进行分表分库或冷热分离，降低热点压力。
  • 缓存层面
    • 对字典、配置、用户信息等读多写少数据使用 Redis 缓存，设置合理过期策略。
    • 对热点统计（如成本统计）采用定时任务预计算并落库。
  • 接口与限流
    • 对易被刷的接口开启限流与熔断（Hystrix），防止雪崩。
    • 分页查询与懒加载，避免一次性返回过多数据。
  • 并发与一致性
    • 对库存/工单等关键写操作采用分布式锁或乐观锁，避免并发冲突。
    • 采用本地消息表或事件驱动实现最终一致。

故障排查指南 ​

  • 启动失败
    • 检查 Nacos 地址、命名空间、分组是否正确替换，确认 shared-configs 中存在 application-default.yml。
    • 确认各服务端口未被占用（8040~8043）。
  • 接口不可用
    • 确认服务已注册到 Nacos，网关路由配置正确。
    • 访问 /swagger-ui.html 校验接口文档是否可打开。
  • 数据不一致
    • 核对数据库索引与唯一约束是否生效。
    • 对库存/工单等关键流程增加幂等校验与日志追踪。
  • 流程异常
    • 检查流程 XML 是否正确部署，节点配置与参数校验是否匹配。
    • 查看审批日志表，定位审批状态与节点推进问题。

章节来源

结论 ​

DeviceMate 后端通过“业务域 + 公共能力 + 网关 + 注册中心”的架构实现了设备、仓储与流程的协同治理。四大服务职责清晰、边界明确，配合 Nacos 与 Flowable 形成了可扩展、可演进的微服务体系。建议在后续迭代中持续完善监控与告警、强化事件驱动与异步化改造，并加强跨域事务的一致性保障与性能优化。

附录 ​

  • 部署与运行
    • 聚合构建：mvn clean install -DskipTests=false -DtestFailureIgnore=false
    • 单模块构建：mvn -pl lemes-service-dm-device -am clean install
    • 单服务运行：在各 server 模块内执行 mvn spring-boot:run
  • 默认端口
    • dm-common=8040、dm-device=8041、dm-store=8042、dm-workflow=8043
  • 常用依赖
    • Spring Cloud Gateway、Nacos、Flowable、Swagger、EasyPOI、Redisson、Hystrix、Validation

章节来源