smart_management_dev/盘点系统业务对接文档.md

# 盘点系统业务对接文档

## 项目概述

### 项目背景
盘点系统是用于实现仓库库存自动盘点的系统，通过RFID设备自动采集货品信息，并与系统库存数据进行比对，以实现库存的精确管理。

### 项目目标
- 实现盘点任务的创建和管理
- 通过RFID设备自动采集货品标签信息
- 与系统库存数据进行比对分析
- 生成盘点结果报告

## 盘点系统业务流程

### 1. 任务创建阶段
- **业务内容**：在系统中创建盘点任务，指定盘点范围（仓库、区域、货品类别等）
- **数据准备**：系统获取当前库存数据作为基准数据
- **任务分配**：将盘点任务分配给指定的RFID设备

### 2. 设备执行阶段
- **设备连接**：RFID设备连接到系统
- **任务下发**：系统将盘点任务下发到RFID设备
- **标签采集**：RFID设备在指定区域扫描，采集货品标签信息
- **数据传输**：将采集到的标签数据实时传输回系统

### 3. 结果采集阶段
- **数据收集**：系统收集从RFID设备传回的标签数据
- **数据验证**：验证数据完整性和准确性
- **暂存处理**：将采集到的数据暂存到临时表

### 4. 结果匹配阶段
- **数据比对**：将采集到的标签数据与系统库存数据进行比对
- **状态标识**：
  - 正常：系统中有记录，且实物存在（标签被扫描到）
  - 盘亏：系统中有记录，但实物不存在（标签未被扫描到）
  - 盘盈：系统中无记录，但实物存在（标签被扫描到但无对应库存）
- **差异分析**：统计盘点差异情况

### 5. 结果输出阶段
- **报告生成**：生成盘点结果报告，包括正常、盘亏、盘盈等统计
- **结果展示**：通过图表和列表展示盘点结果
- **异常处理**：对盘点异常情况进行标注和处理
- **任务完成**：标记盘点任务为完成状态

## 合作方需要提供的信息

### 1. RFID设备技术信息
- 设备型号和规格
- 网络连接方式（IP地址、端口）
- 通信协议类型
- 设备API接口文档
- 设备认证和安全机制

### 2. 设备集成接口
- 设备连接接口（TCP/UDP/HTTP等）
- 标签数据获取接口
- 设备状态查询接口
- 设备控制接口（开始/停止扫描等）

### 3. 数据格式规范
- 标签数据格式
- 数据传输格式（JSON/XML等）
- 字符编码方式
- 数据字段定义

## 我方执行流程

### 1. 接口对接阶段
- **技术对接**：根据合作方提供的API文档，开发与RFID设备的接口
- **连接测试**：测试设备连接功能，确保能够正常建立连接
- **数据传输测试**：测试标签数据的获取和传输功能

### 2. 任务管理实现
- **任务创建**：开发盘点任务管理模块，支持任务的创建、分配、状态管理
- **设备绑定**：实现盘点任务与RFID设备的绑定关系
- **权限控制**：确保任务的安全性和完整性

### 3. 数据处理实现
- **实时接收**：实现标签数据的实时接收和处理机制
- **WebSocket通信**：通过WebSocket将采集到的标签数据实时推送到前端
- **数据存储**：将采集到的数据存储到系统中

### 4. 匹配算法实现
- **数据比对**：开发扫描数据与库存数据的匹配算法
- **差异计算**：计算盘点差异，标识盘盈、盘亏、正常等状态
- **统计分析**：生成盘点统计报告和图表

### 5. 结果展示实现
- **结果展示**：开发盘点结果的展示界面
- **报表生成**：实现盘点报告的生成和导出功能
- **异常处理**：处理盘点过程中的异常情况

## 对外接口规范

### 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

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

## 系统工作流程

```mermaid
graph TD
    A[创建盘点任务] --> B[RFID设备连接]
    B --> C[下发盘点任务到设备]
    C --> D[设备开始标签扫描]
    D --> E[实时收集标签数据]
    E --> F{是否完成扫描?}
    F -->|是| G[停止扫描]
    F -->|否| D
    G --> H[数据比对分析]
    H --> I[生成盘点结果]
    I --> J[输出盘点报告]
    J --> K[任务完成]
```

## 系统开发工作内容

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

## 项目交付物

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

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

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

## 服务收费标准

### 盘点系统开发服务

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

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

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

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

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