# WMS 微服务架构设计文档 ## 1. 架构概述 ### 1.1 架构目标 - 将单体 WMS 系统拆分为独立的微服务 - 实现业务解耦，提高系统可维护性 - 支持独立部署和扩展 - 保留原有业务代码作为参考 ### 1.2 架构原则 - **单一职责**: 每个服务只负责一个业务领域 - **自治性**: 服务可独立开发、部署、扩展 - **轻量级通信**: 使用 RESTful API 进行服务间通信 - **数据一致性**: 保证最终一致性，支持补偿机制 ## 2. 服务拆分 ### 2.1 服务划分 ``` ┌─────────────────────────────────────────────────────────┐ │ WMS 微服务架构 │ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 基础服务 │ │ 入库服务 │ │ 出库服务 │ │ │ │ (8001) │ │ (8002) │ │ (8003) │ │ │ │ - 物品管理 │ │ - ASN 管理 │ │ - 拣货管理 │ │ │ │ - 区域管理 │ │ - 收货管理 │ │ - 拣货任务 │ │ │ │ - 点位管理 │ │ - 上架管理 │ │ - 下架管理 │ │ │ │ │ │ - MOM 对接 │ │ - MOM 对接 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ 库存服务 │ │ 调度服务 │ │ │ │ (8004) │ │ (8005) │ │ │ │ - 库存管理 │ │ - AGV 调度 │ │ │ │ - 库存流水 │ │ - 海康 AGV │ │ │ │ - 盘点管理 │ │ - 特斯 AGV │ │ │ │ - 统计分析 │ │ - 输送线 │ │ │ │ - 序列号 │ │ - 定时任务 │ │ │ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘ ``` ### 2.2 服务职责 #### 2.2.1 基础服务 (cpte-wms-basic-service) **核心职责**: - 管理 WMS 系统的基础数据 **主要功能**: 1. 物品信息管理（Item） 2. 仓库区域管理（Area） 3. 库位点位管理（Point） **对外接口**: - `/api/wms/basic/item/**` - 物品管理 - `/api/wms/basic/area/**` - 区域管理 - `/api/wms/basic/point/**` - 点位管理 --- #### 2.2.2 调度服务 (cpte-wms-schedule-service) **核心职责**: - 提供 AGV 和输送线调度能力 - 管理定时任务 **主要功能**: 1. AGV 任务调度（AgvTask） 2. 海康 AGV 对接（HikAgv） 3. 特斯 AGV 对接（TesAgv） 4. 输送线管理（ConveyorLine） 5. 数据同步定时任务 **对外接口**: - `/api/wms/schedule/agv-task/**` - AGV 任务 - `/api/wms/schedule/hik-agv/**` - 海康 AGV - `/api/wms/schedule/tes-agv/**` - 特斯 AGV - `/api/wms/schedule/conveyor/**` - 输送线 **依赖服务**: - 基础服务：获取物品、库位信息 - 库存服务：获取库存信息 --- #### 2.2.3 入库服务 (cpte-wms-inbound-service) **核心职责**: - 处理所有入库业务流程 - 对接 MOM 系统入库接口 **主要功能**: 1. ASN 单管理（Asn） 2. ASN 明细管理（AsnDetail） 3. 收货登记（Receive） 4. 上架作业 5. 收货记录（ReceiveRecord） 6. MOM 入库对接 **对外接口**: - `/api/wms/inbound/asn/**` - ASN 管理 - `/api/wms/inbound/receive/**` - 收货管理 - `/api/wms/inbound/sai-wms/**` - MOM 对接 **依赖服务**: - 基础服务：获取物品、库位信息 - 调度服务：生成 AGV 上架任务 - 库存服务：更新库存 --- #### 2.2.4 出库服务 (cpte-wms-outbound-service) **核心职责**: - 处理所有出库业务流程 - 对接 MOM 系统出库接口 **主要功能**: 1. 拣货单管理（Pick） 2. 拣货明细管理（PickDetail） 3. 拣货任务管理（Task） 4. 任务分配 5. 下架作业 6. MOM 出库对接 **对外接口**: - `/api/wms/outbound/pick/**` - 拣货管理 - `/api/wms/outbound/task/**` - 任务管理 - `/api/wms/outbound/sai-wms/**` - MOM 对接 **依赖服务**: - 基础服务：获取物品、库位信息 - 调度服务：生成 AGV 搬运任务 - 库存服务：扣减库存 --- #### 2.2.5 库存服务 (cpte-wms-inventory-service) **核心职责**: - 管理库存核心业务 - 记录库存流水 - 提供库存查询和统计 **主要功能**: 1. 库存管理（Inventory） 2. 库存流水（InventoryLog） 3. 盘点计划（CountPlan） 4. 盘点明细（CountDetail） 5. 数据看板（Dashboard） 6. 序列号管理 **对外接口**: - `/api/wms/inventory/**` - 库存管理 - `/api/wms/inventory/log/**` - 库存流水 - `/api/wms/inventory/count/**` - 盘点管理 - `/api/wms/inventory/dashboard/**` - 数据看板 **依赖服务**: - 调度服务：调用 AGV 任务 --- ## 3. 服务间调用关系 ### 3.1 调用矩阵 ``` │ 基础 │ 调度 │ 入库 │ 出库 │ 库存 │ ──────────────┼──────┼──────┼──────┼──────┼──────┤ 基础服务 │ - │ │ → │ → │ → │ ──────────────┼──────┼──────┼──────┼──────┼──────┤ 调度服务 │ ← │ - │ ← │ ← │ ← │ ──────────────┼──────┼──────┼──────┼──────┼──────┤ 入库服务 │ ← │ → │ - │ │ → │ ──────────────┼──────┼──────┼──────┼──────┼──────┤ 出库服务 │ ← │ → │ │ - │ → │ ──────────────┼──────┼──────┼──────┼──────┼──────┤ 库存服务 │ ← │ → │ ← │ ← │ - │ ──────────────┴──────┴──────┴──────┴──────┴──────┘ 图例: → 调用其他服务 ← 被其他服务调用 ``` ### 3.2 典型业务流程 #### 3.2.1 入库流程 ``` 1. 入库服务创建 ASN 单 2. 入库服务执行收货 3. 入库服务调用库存服务 → 增加库存 4. 库存服务记录库存流水 5. 入库服务调用调度服务 → 生成 AGV 上架任务 ``` #### 3.2.2 出库流程 ``` 1. 出库服务创建拣货单 2. 出库服务生成拣货任务 3. 出库服务调用库存服务 → 预占库存 4. 出库服务调用调度服务 → 生成 AGV 搬运任务 5. 拣货完成后调用库存服务 → 扣减库存 6. 库存服务记录库存流水 ``` #### 3.2.3 盘点流程 ``` 1. 库存服务创建盘点计划 2. 库存服务执行盘点 3. 库存服务生成盘点差异 4. 库存服务调整库存 5. 库存服务记录库存流水 ``` #### 3.2.4 AGV 调度流程 ``` 1. 入库/出库服务调用调度服务 → 请求 AGV 任务 2. 调度服务调用基础服务 → 获取库位信息 3. 调度服务生成 AGV 任务 4. 调度服务对接 AGV 设备（海康/特斯） 5. AGV 执行任务并返回结果 ``` --- ## 4. 数据设计 ### 4.1 数据库表归属 #### 基础服务表 ```sql wms_basic_item -- 物品信息 wms_basic_item_key -- 物品关键信息 wms_basic_area -- 区域信息 wms_basic_point -- 点位信息 wms_basic_stock -- 库存（基础数据） ``` #### 调度服务表 ```sql wms_agv_task -- AGV 任务 wms_hik_agv -- 海康 AGV wms_tes_agv -- 特斯 AGV wms_conveyor_line -- 输送线 ``` #### 入库服务表 ```sql wms_inbound_asn -- ASN 单 wms_inbound_asn_detail -- ASN 明细 wms_inbound_receive -- 收货记录 ``` #### 出库服务表 ```sql wms_outbound_pick -- 拣货单 wms_outbound_pick_detail -- 拣货明细 wms_outbound_task -- 拣货任务 ``` #### 库存服务表 ```sql wms_inventory -- 库存 wms_inventory_log -- 库存流水 wms_count_plan -- 盘点计划 wms_count_detail -- 盘点明细 ``` ### 4.2 数据一致性方案 #### 方案一：本地事务（推荐初期） - 所有服务共享数据库 - 使用本地事务保证一致性 - 优点：简单、可靠 - 缺点：数据库耦合 #### 方案二：分布式事务（推荐后期） - 每个服务独立数据库 - 使用 Seata 管理分布式事务 - 优点：服务解耦 - 缺点：复杂度高 #### 方案三：最终一致性 - 使用消息队列 - 补偿机制保证最终一致性 - 优点：高性能、高可用 - 缺点：实现复杂 --- ## 5. 接口设计 ### 5.1 接口规范 #### 统一响应格式 ```java { "code": 200, "message": "success", "data": {}, "timestamp": 1234567890 } ``` #### 统一错误码 ``` 200 - 成功 400 - 参数错误 401 - 未授权 403 - 禁止访问 404 - 资源不存在 500 - 服务器内部错误 ``` ### 5.2 核心接口 #### 基础服务接口 ``` GET /api/wms/basic/item/{id} # 获取物品信息 POST /api/wms/basic/item/list # 分页查询物品 GET /api/wms/basic/area/{id} # 获取区域信息 GET /api/wms/basic/point/{id} # 获取点位信息 POST /api/wms/basic/agv-task/submit # 提交 AGV 任务 ``` #### 入库服务接口 ``` POST /api/wms/inbound/asn/create # 创建 ASN 单 GET /api/wms/inbound/asn/{id} # 获取 ASN 详情 POST /api/wms/inbound/receive # 收货登记 ``` #### 出库服务接口 ``` POST /api/wms/outbound/pick/create # 创建拣货单 GET /api/wms/outbound/pick/{id} # 获取拣货详情 POST /api/wms/outbound/task/allocate # 分配拣货任务 ``` #### 库存服务接口 ``` GET /api/wms/inventory/query # 查询库存 POST /api/wms/inventory/increase # 增加库存 POST /api/wms/inventory/decrease # 扣减库存 GET /api/wms/inventory/log/list # 库存流水 POST /api/wms/inventory/count/execute # 执行盘点 ``` --- ## 6. 部署架构 ### 6.1 开发环境 ``` ┌──────────────┐ │ Nginx │ (可选，统一入口) └──────────────┘ │ ┌──────┴──────┬──────────┬──────────┬──────────┬──────────┐ │ │ │ │ │ │ │ 基础服务 │ 调度服务 │ 入库服务 │ 出库服务 │ 库存服务 │ │ :8001 │ :8005 │ :8002 │ :8003 │ :8004 │ │ │ │ │ │ │ └─────────────┴──────────┴──────────┴──────────┴──────────┘ │ ┌───────┴───────┐ │ │ MySQL Redis ``` ### 6.2 生产环境（推荐） ``` ┌──────────┐ │ Gateway │ └──────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ┌────┴────┐ ┌─────┴────┐ ┌─────┴────┐ │ 负载均衡 │ │ 负载均衡 │ │ 负载均衡 │ └────┬────┘ └─────┬────┘ └─────┬────┘ │ │ │ ┌────┴────┐ ┌─────┴────┐ ┌─────┴────┐ │基础服务 1│ │入库服务 1│ │出库服务 1│ │基础服务 2│ │入库服务 2│ │出库服务 2│ └─────────┘ └──────────┘ └──────────┘ │ ┌────┴────┐ │库存服务 1│ │库存服务 2│ └─────────┘ ``` --- ## 7. 监控和日志 ### 7.1 健康检查 每个服务提供健康检查端点： ``` GET /actuator/health ``` ### 7.2 指标监控 ``` GET /actuator/metrics ``` ### 7.3 日志规范 - 使用 SLF4J + Logback - 按日期滚动保存 - 包含 traceId 便于链路追踪 --- ## 8. 开发计划 ### 阶段一：架构搭建（已完成） - [x] 设计微服务架构 - [x] 创建项目结构 - [x] 配置 pom.xml - [x] 创建配置文件 - [x] 创建启动类 ### 阶段二：代码迁移 - [ ] 迁移基础服务代码 - [ ] 迁移入库服务代码 - [ ] 迁移出库服务代码 - [ ] 迁移库存服务代码 ### 阶段三：服务间接口 - [ ] 定义服务间接口 - [ ] 实现服务间调用 - [ ] 测试接口连通性 ### 阶段四：集成测试 - [ ] 单元测试 - [ ] 集成测试 - [ ] 性能测试 ### 阶段五：部署上线 - [ ] 编写部署文档 - [ ] 配置生产环境 - [ ] 灰度发布 - [ ] 正式上线 --- ## 9. 风险管理 ### 技术风险 1. **服务间调用延迟**: 优化网络调用，使用连接池 2. **数据不一致**: 实现补偿机制，保证最终一致性 3. **单点故障**: 服务集群部署，使用负载均衡 ### 业务风险 1. **业务中断**: 灰度发布，逐步迁移流量 2. **数据丢失**: 完善备份机制，定期演练恢复 --- ## 10. 总结 本架构设计将 WMS 系统拆分为四个独立的微服务，实现了： - ✅ 业务解耦，职责清晰 - ✅ 独立部署，灵活扩展 - ✅ 保留原代码，便于参考 - ✅ 平滑迁移，降低风险 后续可根据业务发展，逐步引入服务治理、API 网关、链路追踪等能力。