huojin
/
Cpte-Boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Cpte-Boot/cpte-wms-service/ARCHITECTURE.md

474 lines
15 KiB
Markdown
Raw Normal View History

no message
2026-03-06 15:19:25 +08:00
# 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 网关、链路追踪等能力。