# 智慧仓储系统综合业务文档

## 项目概述

### 项目背景
智慧仓储系统包含WCS（Warehouse Control System，仓库控制系统）、WMS（仓库管理系统）、AGV（自动导引车）系统以及Inventory（库存盘点）系统，形成一个完整的自动化仓储解决方案。各系统协同工作，实现货物的自动化入库、出库、移库、盘点等操作。

### 项目目标
- 实现WCS系统与WMS系统的无缝对接
- 实现WCS系统与AGV系统的协调作业
- 实现Inventory系统对库存的精确管理
- 提供标准化接口，确保多系统稳定运行
- 实现出入库、移库、盘点等核心业务流程

## WCS系统核心功能

### 1. 入库/上架功能
- 接收WMS系统的入库任务
- 控制立体库设备执行上架操作
- 实时反馈任务执行状态给WMS系统

### 2. 出库/下架功能
- 接收WMS系统的出库任务
- 控制立体库设备执行下架操作
- 实时反馈任务执行状态给WMS系统

### 3. 库位管理功能
- 管理立体库所有库位状态
- 实时更新库位占用情况
- 提供库位查询接口

### 4. 任务调度功能
- 任务队列管理
- 任务优先级调度
- 设备资源分配

## Inventory系统核心功能

### 1. 盘点任务管理
- 创建盘点任务（设置任务名称、仓库ID、场景ID、执行人、完成时间等）
- 任务类型：手持盘点（0）和自动盘点（1）
- 任务状态：待执行（0）、已完成（1）、已超时（2）

### 2. 自动盘点功能
- 设备连接管理：通过RFID设备IP和端口建立TCP连接
- 标签扫描：启动RFID设备进行标签扫描
- 数据传输：通过WebSocket将扫描到的EPC标签数据发送给前端
- 扫描控制：支持开始、停止、断开连接等操作

### 3. 数据匹配功能
- 将扫描数据与系统库存数据进行匹配
- 生成匹配结果（正常、未扫到、误扫）
- 统计盘点结果并生成图表

### 4. 报告管理功能
- 生成盘点统计图表
- 导出盘点报告
- 提供历史盘点记录查询

## WCS系统对外接口

### 1. 入库/上架接口（/API/Ruku）

#### 接口说明
WMS系统调用此接口创建入库/上架任务

#### 请求方式
POST

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| TaskID | String | 是 | 任务ID |
| TrayNo | String | 否 | 托盘号 |
| Materialstatus | Integer | 是 | 物料状态（0: 空托盘，1: 有货） |
| MaterialCode | String | 否 | 物料编码（Materialstatus为1时必填） |
| Specification | String | 否 | 规格 |
| Quantity | String | 否 | 数量 |
| Mlocation | String | 是 | 目标库位 |
| Tlocation | String | 是 | 来源库位 |

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| result | String | 结果（"success"表示成功） |
| errorMessage | String | 错误消息 |

### 2. 出库/下架接口（/API/Chuku）

#### 接口说明
WMS系统调用此接口创建出库/下架任务

#### 请求方式
POST

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| TaskID | String | 是 | 任务ID |
| TaskType | Integer | 是 | 任务类型（1: 出库） |
| Mlocation | String | 是 | 来源库位 |
| TrayNo | String | 否 | 托盘号 |
| Materialstatus | Integer | 是 | 物料状态（0: 空托盘，1: 有货） |
| outBack | Integer | 是 | 固定值（1） |
| MaterialCode | String | 否 | 物料编码（Materialstatus为1时必填） |
| Specification | String | 否 | 规格 |
| Quantity | String | 否 | 数量 |

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| result | String | 结果（"success"表示成功） |
| errorMessage | String | 错误消息 |

## Inventory系统对外接口

### 1. 设备连接接口（/AutoInventory/connect）

#### 接口说明
建立RFID设备连接

#### 请求方式
POST

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deviceId | String | 是 | 设备ID |
| ip | String | 是 | 设备IP地址 |
| port | Integer | 是 | 设备端口号 |

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码（200表示成功） |
| msg | String | 响应消息 |

### 2. 开始盘点接口（/AutoInventory/scan）

#### 接口说明
启动RFID设备进行标签扫描

#### 请求方式
GET

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deviceId | String | 是 | 设备ID |

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码（200表示成功） |
| msg | String | 响应消息 |

### 3. 停止盘点接口（/AutoInventory/stop）

#### 接口说明
停止RFID设备扫描

#### 请求方式
GET

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deviceId | String | 是 | 设备ID |

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码（200表示成功） |
| msg | String | 响应消息 |

### 4. 断开连接接口（/AutoInventory/disconnect）

#### 接口说明
断开RFID设备连接

#### 请求方式
GET

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deviceId | String | 是 | 设备ID |

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码（200表示成功） |
| msg | String | 响应消息 |

### 5. 设备状态查询接口（/AutoInventory/status）

#### 接口说明
查询RFID设备连接状态

#### 请求方式
GET

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deviceId | String | 是 | 设备ID |

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码（200表示成功） |
| msg | String | 响应消息（包含设备连接状态） |

### 6. 开始匹配接口（/AutoInventory/match）

#### 接口说明
将扫描数据与系统库存数据进行匹配

#### 请求方式
POST

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| taskId | String | 是 | 盘点任务ID |
| deviceId | String | 是 | 设备ID |
| scanType | Integer | 是 | 扫描类型（0=手动盘点，1=自动盘点） |

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码（200表示成功） |
| msg | String | 响应消息 |

### 7. 盘点任务管理接口（/Inventory/task）

#### 接口说明
管理盘点任务的增删改查

#### 请求方式
POST/GET/PUT/DELETE

#### 主要功能
- 新增盘点任务
- 查询盘点任务列表
- 修改盘点任务
- 删除盘点任务
- 导出盘点任务

## WCS系统开发工作内容

### 1. 接口开发工作

#### 1.1 入库/上架接口开发
- **工作内容**：开发 `/API/Ruku` 接口，处理WMS入库任务请求
- **技术实现**：
  - HTTP POST接口开发
  - JSON数据解析
  - 业务参数验证
  - 任务创建与调度
  - 响应格式化
- **预计工时**：16小时

#### 1.2 出库/下架接口开发
- **工作内容**：开发 `/API/Chuku` 接口，处理WMS出库任务请求
- **技术实现**：
  - HTTP POST接口开发
  - JSON数据解析
  - 业务参数验证
  - 任务创建与调度
  - 响应格式化
- **预计工时**：16小时

#### 1.3 任务状态回调接口开发
- **工作内容**：实现WCS任务状态回调机制
- **技术实现**：
  - 状态变更触发器
  - HTTP回调请求
  - 状态同步机制
- **预计工时**：24小时

### 2. 业务逻辑开发工作

#### 2.1 货物上架逻辑实现
- **工作内容**：实现完整的货物上架业务流程
- **技术实现**：
  - 库位分配算法
  - 设备控制指令生成
  - 执行状态跟踪
  - 异常处理机制
- **预计工时**：32小时

#### 2.2 货物下架逻辑实现
- **工作内容**：实现完整的货物下架业务流程
- **技术实现**：
  - 货物定位算法
  - 设备控制指令生成
  - 执行状态跟踪
  - 异常处理机制
- **预计工时**：32小时

#### 2.3 任务调度与排队机制
- **工作内容**：实现多任务排队调度算法
- **技术实现**：
  - 任务队列管理
  - 优先级调度算法
  - 设备资源分配
  - 任务冲突解决
- **预计工时**：24小时

### 3. 系统集成开发工作

#### 3.1 与WMS系统接口对接
- **工作内容**：确保WCS与WMS系统稳定通信
- **技术实现**：
  - 接口协议实现
  - 数据格式转换
  - 通信安全机制
  - 错误重试机制
- **预计工时**：20小时

#### 3.2 与AGV系统协调机制
- **工作内容**：实现WCS与AGV系统的任务协调
- **技术实现**：
  - 协调接口开发
  - 状态同步机制
  - 任务交接处理
- **预计工时**：16小时

### 4. 数据管理开发工作

#### 4.1 任务数据存储与管理
- **工作内容**：开发任务数据的存储和管理功能
- **技术实现**：
  - 数据库表设计
  - 数据访问层开发
  - 数据一致性保证
  - 数据清理机制
- **预计工时**：20小时

#### 4.2 库位状态数据维护
- **工作内容**：实现库位状态的实时维护
- **技术实现**：
  - 库位状态表设计
  - 状态变更处理
  - 数据同步机制
  - 状态查询接口
- **预计工时**：16小时

### 5. 监控与维护开发工作

#### 5.1 系统运行状态监控
- **工作内容**：开发系统运行状态监控功能
- **技术实现**：
  - 监控指标定义
  - 监控接口开发
  - 异常告警机制
- **预计工时**：12小时

#### 5.2 异常处理与恢复机制
- **工作内容**：开发完善的异常处理和任务恢复机制
- **技术实现**：
  - 异常类型定义
  - 异常处理策略
  - 任务恢复机制
  - 日志记录系统
- **预计工时**：20小时

## Inventory系统开发工作内容

### 1. 设备接口开发工作

#### 1.1 RFID设备连接接口开发
- **工作内容**：开发RFID设备连接、断开、状态查询接口
- **技术实现**：
  - TCP连接管理
  - 设备状态跟踪
  - 连接池管理
  - 异常处理机制
- **预计工时**：24小时

#### 1.2 盘点控制接口开发
- **工作内容**：开发开始盘点、停止盘点等控制接口
- **技术实现**：
  - 设备控制指令发送
  - 扫描状态管理
  - 线程安全控制
- **预计工时**：16小时

### 2. 数据处理开发工作

#### 2.1 扫描数据处理开发
- **工作内容**：处理RFID设备扫描的标签数据
- **技术实现**：
  - 实时数据接收
  - WebSocket通信
  - 数据格式化处理
  - 数据存储
- **预计工时**：28小时

#### 2.2 数据匹配算法开发
- **工作内容**：开发扫描数据与库存数据的匹配算法
- **技术实现**：
  - 匹配算法设计
  - 数据对比逻辑
  - 状态标识处理
  - 统计计算
- **预计工时**：32小时

### 3. 任务管理开发工作

#### 3.1 盘点任务管理开发
- **工作内容**：开发盘点任务的增删改查功能
- **技术实现**：
  - 任务数据模型设计
  - 任务状态管理
  - 任务分配逻辑
  - 任务进度跟踪
- **预计工时**：24小时

#### 3.2 报告生成开发
- **工作内容**：开发盘点报告生成和统计功能
- **技术实现**：
  - 数据统计算法
  - 图表生成
  - 报告导出功能
  - 历史数据查询
- **预计工时**：20小时

### 4. 系统集成开发工作

#### 4.1 与WMS系统集成
- **工作内容**：实现Inventory系统与WMS系统的数据同步
- **技术实现**：
  - 库存数据接口
  - 数据同步机制
  - 冲突处理策略
- **预计工时**：16小时

#### 4.2 WebSocket通信开发
- **工作内容**：实现实时数据传输功能
- **技术实现**：
  - WebSocket服务端开发
  - 设备标识管理
  - 消息推送机制
- **预计工时**：20小时

## 系统对接流程图

### WCS系统对接流程

```mermaid
graph TD
    A[WMS创建任务] --> B{判断任务类型}
    B -->|入库/上架| C[WMS调用WCS /API/Ruku接口]
    B -->|出库/下架| D[WMS调用WCS /API/Chuku接口]
    
    C --> E[WCS接收任务请求]
    D --> E
    
    E --> F[WCS验证任务参数]
    F --> G{参数验证结果}
    G -->|验证失败| H[WCS返回错误信息给WMS]
    G -->|验证成功| I[WCS创建内部任务]
    
    I --> J[WCS控制立体库设备执行任务]
    J --> K[设备执行中...]
    K --> L{任务执行结果}
    L -->|执行成功| M[WCS更新任务状态]
    L -->|执行失败| N[WCS记录异常并重试]
    
    M --> O[WCS回调WMS状态更新]
    N --> P{重试次数达到上限}
    P -->|是| Q[WCS回调WMS失败状态]
    P -->|否| J
    
    O --> R[WMS接收状态更新]
    Q --> R
    H --> R
    
    R --> S{是否需要AGV配合}
    S -->|是| T[WMS调度AGV]
    S -->|否| U[任务完成]
    T --> U
```

### Inventory系统工作流程

```mermaid
graph TD
    A[创建盘点任务] --> B[选择盘点方式]
    B -->|自动盘点| C[连接RFID设备]
    B -->|手持盘点| D[手动扫描]
    
    C --> E[开始标签扫描]
    E --> F[实时接收EPC数据]
    F --> G[WebSocket推送数据到前端]
    D --> G
    
    G --> H[停止扫描]
    H --> I[数据匹配处理]
    I --> J[生成匹配结果]
    J --> K[统计分析]
    K --> L[生成盘点报告]
    L --> M[任务完成]
```

## 项目实施计划

### 第一阶段：接口开发（预计3周）
- 完成WCS入库/上架接口开发
- 完成WCS出库/下架接口开发
- 完成Inventory设备管理接口开发
- 完成基础数据模型设计

### 第二阶段：业务逻辑开发（预计4周）
- 完成WCS货物上架逻辑开发
- 完成WCS货物下架逻辑开发
- 完成WCS任务调度机制开发
- 完成Inventory数据处理逻辑开发
- 完成盘点匹配算法开发

### 第三阶段：系统集成（预计3周）
- 完成WCS与WMS系统对接
- 完成WCS与AGV系统协调
- 完成Inventory与WMS系统集成
- 完成WebSocket通信功能
- 完成监控功能开发

### 第四阶段：测试与优化（预计2周）
- 系统集成测试
- 性能优化
- 异常处理完善
- 用户验收测试

## 项目交付物

1. **技术文档**
   - WCS系统接口规范文档
   - Inventory系统接口规范文档
   - 部署手册
   - 运维手册
   - 用户操作手册

2. **软件系统**
   - WCS系统核心程序
   - Inventory系统核心程序
   - 数据库脚本
   - 配置文件

3. **测试报告**
   - 单元测试报告
   - 集成测试报告
   - 性能测试报告
   - 用户验收测试报告

## 项目价值体现

### 1. 技术价值
- 提供标准化接口，实现多系统间无缝对接
- 实现复杂的任务调度算法
- 确保系统高可用性和稳定性
- 实现自动化的盘点功能

### 2. 业务价值
- 实现仓库作业自动化
- 提高仓储效率和准确性
- 降低人工成本
- 实现库存精确管理

### 3. 服务价值
- 专业的技术开发服务
- 完善的系统集成方案
- 持续的技术支持服务
- 完整的仓储解决方案

## 风险与应对

### 1. 技术风险
- **风险**：接口兼容性问题
- **应对**：提前进行接口规范确认

### 2. 集成风险
- **风险**：多系统集成复杂度高
- **应对**：分阶段集成测试

### 3. 性能风险
- **风险**：高并发场景下系统性能
- **应对**：性能测试与优化

### 4. 设备风险
- **风险**：RFID设备连接稳定性
- **应对**：设备连接监控和异常处理

## 服务收费标准

### WCS系统开发服务

#### 1. 接口开发服务（40小时）
- 入库/上架接口：16小时
- 出库/下架接口：16小时
- 任务状态回调接口：8小时

#### 2. 业务逻辑开发（88小时）
- 货物上架逻辑：32小时
- 货物下架逻辑：32小时
- 任务调度机制：24小时

#### 3. 系统集成服务（36小时）
- 与WMS系统对接：20小时
- 与AGV系统协调：16小时

#### 4. 数据管理开发（36小时）
- 任务数据管理：20小时
- 库位状态维护：16小时

#### 5. 监控维护开发（32小时）
- 系统监控：12小时
- 异常处理机制：20小时

### Inventory系统开发服务

#### 1. 设备接口开发（40小时）
- RFID设备连接接口：24小时
- 盘点控制接口：16小时

#### 2. 数据处理开发（60小时）
- 扫描数据处理：28小时
- 数据匹配算法：32小时

#### 3. 任务管理开发（44小时）
- 盘点任务管理：24小时
- 报告生成：20小时

#### 4. 系统集成开发（36小时）
- 与WMS系统集成：16小时
- WebSocket通信：20小时

**总计开发工时：392小时**