docs: update project docs and add new reference documents

1. 修正项目说明文档中关于项目D、E的技术栈与部署描述 2. 新增完整的需求规格与开发规划文档 3. 新增海康RCS-2000 V4.2接口协议文档
2026-08-27 15:46:15 +08:00
parent 371b494c54
commit c85c3bd6f1
4 changed files with 766 additions and 9 deletions
@@ -0,0 +1,474 @@
+# 海康机器人 RCS‑2000 V4.2 接口协议（对外发布）
+>文档类别：厂内物流机器人控制系统
+>文档编号：RCS‑2000 V4.2
+>版权所有 ©杭州海康机器人股份有限公司
+
+## 版权声明
+本文档由海康机器人公司开发，其版权受中华人民共和国版权法保护。海康机器人拥有本文的全部版权，未经本公司许可，任何单位及个人不得对本文中的任何部分进行转印、影印或复印。
+
+## 信息反馈
+海康机器人尽最大的努力保证本手册的准确性和完整性。如果您在使用中发现问题，希望及时将情况反馈给我们以完善产品，我们将非常感谢您的支持。
+
+### 总公司联系方式
+- 公司总机：0571‑88967998
+- 技术支持电话：0571‑86611880(工作日9:30‑17:30)
+- 传真：0571‑88805843
+- 地址：中国杭州市滨江区东流路700号
+- 邮编：310052
+- 公司E‑mail：hikrobot@hikrobotics.com
+- 公司网站：www.hikrobotics.com
+
+## 目录
+1. [协议概述](#1‑协议概述)
+    - 1.1 请求首部字段
+    - 1.2 请求报文消息体
+    - 1.3 加密签名
+    - 1.4 响应首部字段
+    - 1.5 响应报文消息体
+    - 1.6 响应状态码
+    - 1.7 响应报文消息体通用code
+2. [业务接口说明](#2‑业务接口说明)
+    - 2.1 机器人调度API 接口说明
+    - 2.2 反馈接收SPI 接口说明
+3. [任务下发接口调用示例](#3‑任务下发接口调用示例)
+4. [典型调度场景](#4‑典型调度场景)
+5. [更新说明](#5‑更新说明)
+
+---
+
+# 1 协议概述
+>海康调度系统调用上层系统的接口，获取连接超时时间默认为30 秒，数据返回超时时间默认为60 秒，超时情况下，调度系统会返回连接失败。
+
+## 1.1 请求首部字段
+|字段名|数据类型|最大字节数|是否必需|说明|
+|---|---|---|---|---|
+|Authorization|字符串|N/A|否|固定格式：`nonce="wab1tkh",method="HMAC‑SHA256",timestamp="2021‑01‑01T00:00:00+08:00"`|
+|Content‑Type|字符串|N/A|否|固定取值：`application/json;charset=UTF‑8`|
+|X‑lr‑appkey|字符串|32|否|由调度系统颁发给业务系统的唯一标识|
+|X‑lr‑request‑id|字符串|16|是|业务请求的唯一标识|
+|X‑lr‑version|字符串|12|否|API 接口版本，为了保证接口的向下兼容，同样的 API 接口可能存在多个版本实现|
+|X‑lr‑trace‑id|字符串|32|否|全链路追踪标识，用于协查上下游故障，需要在响应中原样返回。建议使用 UUID|
+|X‑lr‑source|字符串|32|否|指令的来源，便于调试和故障定位|
+
+## 1.2 请求报文消息体
+只能使用**JSON格式(UTF‑8编码方式)**或空字符串(无字符)。不能使用JSON对象数组或其他格式。业务请求的参数信息应当放在请求报文消息体当中。
+
+**请求报文样例**
+```http
+POST /api/robot/controller/tasks HTTP/1.1 
+Host: 10.10.10.10:1010
+Authorization: nonce="wab1tkh",method="HMAC‑SHA256",timestamp="2021‑01‑01T00:00:00+08:00"
+X‑lr‑appkey: a4f********b324
+X‑lr‑version: v1.0 
+X‑lr‑trace‑id: 605****8a0b
+X‑lr‑request‑id: 393****a6c1 
+Content‑Type: application/json;charset=UTF‑8 
+Content‑Length: 512 
+Date: Fri, 26 Mar 2021 06:46:14 GMT 
+
+{"warehouseId":"371****b108",……,"zoneCode":"c7a6****371b"}
+```
+
+## 1.3 加密签名
+应用注册中的第三方应用，如开启加密，请求时需带上签名。`appSecret`为应用注册中的私钥。
+>请求完整示例如上所示，其中只有请求行、特定的首部字段、空行、报文消息体参与签名，即需要从请求报文原文中去除不参与签名的首部字段，将参与签名的首部字段名按下表编号的顺序排序，同时首部字段名改为大写。
+
+**参与签名的首部字段**
+|编号|参与签名的首部字段|是否必填|
+|---|---|---|
+|1|AUTHORIZATION|是|
+|2|HOST|是|
+|3|X‑LR‑APPKEY|是|
+|4|X‑LR‑REQUEST‑ID|是|
+|5|X‑LR‑SOURCE|否|
+|6|X‑LR‑TRACE‑ID|否|
+|7|X‑LR‑VERSION|是|
+
+签名生成逻辑：
+> 签名 = MD5( 加盐哈希算法(appSecret,请求报文拼接后的原串) )
+> 加盐哈希算法可选：
+> 1）HMAC‑SHA256（推荐）
+> 2）HMAC‑SHA512
+> 使用MD5对加盐哈希算法的散列值再次哈希，产生128(16字节)的散列值。
+
+>请求的签名应当携带在**查询参数**的最后，参数名为`sign`。
+
+**Authorization头部参数说明**
+|参数名|数据类型|字节数|是否必须|说明|
+|---|---|---|---|---|
+|nonce|字符串|8|是|随机数。建议每次请求都不同，以便于更有效的抵御彩虹表攻击；也可以定时更换|
+|method|字符串|N/A|是|加盐哈希算法，固定枚举值：`HMAC‑SHA256`、`HMAC‑SHA512`|
+|timestamp|字符串|N/A|是|请求发出的时间，遵循本文档关于时间格式秒精度的定义|
+
+>重放攻击验证：服务端取出timestamp，加上业务允许合法请求时间，建议不超过**120秒**，判断请求是否超时。
+
+## 1.4 响应首部字段
+|字段名|数据类型|最大字节数|是否必须|说明|
+|---|---|---|---|---|
+|Content‑Type|字符串|N/A|否|固定取值：`application/json;charset=UTF‑8`|
+|X‑lr‑request‑id|字符串|16|是|业务请求的唯一标识|
+|X‑lr‑version|字符串|12|否|API接口版本|
+|X‑lr‑trace‑id|字符串|32|否|全链路追踪标识，原样返回请求入参|
+
+## 1.5 响应报文消息体
+当HTTP 响应状态码为`200`时，响应报文消息体JSON对象格式：
+
+|中文名称|字段名|数据类型|最大字节数|是否必须|说明|
+|---|---|---|---|---|---|
+|消息码|code|字符串|32|是|参见 1.6 章节通用响应 code 定义和各接口的消息码定义|
+|提示消息|message|字符串|256|否|异常描述|
+|业务数据|data|JSON 对象|10MB|否|返回的业务属性对象|
+
+**正常响应报文样例**
+```json
+{
+    "code":"SUCCESS",
+    "message":"成功",
+    "data": {
+        "robotTaskCode": "abc**13"
+    }
+}
+```
+
+**业务异常响应报文样例**
+```json
+{
+    "code":"Err_Internal",
+    "message":"内部未知错误",
+    "data":null
+}
+```
+
+## 1.6 响应状态码
+|状态码|说明|
+|---|---|
+|200|HTTP协议层面处理成功，但是仍可能出现业务异常，需要根据响应报文消息体的消息码判断|
+|401|签名认证失败。原因可能是签名无效、签名过期、appKey和appSecret失效，需要重新更新请求时间后加签，或需要调度系统重新颁发appKey和appSecret|
+|403|权限不足。例如业务系统试图取消不由其创建的任务|
+|406|请求的Content‑Type不符合要求|
+|400|其他由于客户端请求错误导致的异常，无法通过重试解决，需要检查请求的格式是否符合要求|
+|500|服务端的异常，可以通过重试请求解决，重试次数与间隔需要根据业务实际情况设定|
+
+>其余未列出状态码均按照标准HTTP协议处理即可。
+
+## 1.7 响应报文消息体通用code
+|Code|message|
+|---|---|
+|SUCCESS|成功|
+|Err_Internal|内部未知错误|
+|Err_DataValidationFailed|数据格式验证失败|
+|Err_RequestDuplicate|请求重复|
+|Err_InvalidVersion|请求版本不合法|
+
+---
+
+# 2 业务接口说明
+服务前缀统一：`/rcs/rtas`，完整请求路径 = 服务前缀 + 路径。
+
+## 2.1 机器人调度API 接口说明
+> WMS/MES作为**调用方**，主动调用RCS‑2000这一组API。
+
+### 2.1.1【国标】任务组接口
+- 接口路径：`/api/robot/controller/task/group`
+- 请求方式：`POST`
+- 幂等性：**是**
+
+>接口说明
+1. 任务组是任务的集合，当任务间有相互关系时，需要先调用任务组接口，描述任务组的策略，任务间的关系组合，再调用任务下发接口。
+2. 任务策略包括按组顺序出库策略、按组分配策略。
+3. 顺序出库下发规则：上层系统将 `groupSeq` 从小到大下发给 RCS‑2000，**上层系统需要控制下发顺序**，不支持先调接口发 groupSeq 大的，再调接口发 groupSeq 小的执行顺序出库。
+
+**请求体字段**
+|参数名|数据类型|最大字节数|是否必须|说明|
+|---|---|---|---|---|
+|groupCode|字符串|32|是|任务组编号，全局唯一|
+|strategy|字符串|16|是|执行策略。枚举：`GROUP_SEQ`按组顺序出库；`GROUP_ASSIGN`按组分配任务(CTU专用)；`GROUP_CARRIER_ADJUST`载具整理(CTU理库)|
+|strategyValue|字符串|32|否|GROUP_SEQ时必填：0组间无序组内无序；1组间及组内都有序；2组间有序组内无序；3组间无序组内有序；GROUP_CARRIER_ADJUST理库时必填|
+|groupSeq|整数|8|否|组顺序(数字)，从1~9999999999|
+|data|JSON对象数组|N/A|是|子任务集合，每个元素：`robotTaskCode`(任务号),`sequence`(组内顺序)|
+
+**响应公共字段**：`code`/`message`/`data`，data内返回任务组信息。
+专用消息码：`Err_TaskNotStart`上一组任务未下发；`Err_DataValidationFailed`任务序列号有误。
+
+**请求示例**
+```json
+{
+    "groupCode": "2e0d1ae0481f48b78b6a217ac2b54eb4",
+    "strategy": "GROUP_SEQ",
+    "strategyValue": "1",
+    "groupSeq": 10,
+    "targetRoute": {
+        "type": "ZONE",
+        "code": "A2"
+    },
+    "data": [
+        {"robotTaskCode": "0a17e361eb5248bfab0508e4709f085e","sequence": 1},
+        {"robotTaskCode": "1b30143f32914155ab194d55a95d54da","sequence": 2},
+        {"robotTaskCode": "6541e925d1de4c448188068fcee75de5","sequence": 3}
+    ]
+}
+```
+
+### 2.1.2【国标】 任务下发接口
+- 接口路径：`/api/robot/controller/task/submit`
+- 请求方式：`POST`
+- 幂等性：**是**
+
+>接口说明：业务系统发送任务请求，物流机器人调度系统生成任务执行单，并下发执行。
+
+**请求体字段**
+|参数名|数据类型|最大字节数|是否必须|说明|
+|---|---|---|---|---|
+|taskType|字符串|16|是|任务类型，预制枚举：`PF‑LMR‑COMMON`普通搬运|
+|targetRoute|对象数组|N/A|是|执行步骤集合，机器人关键路径（起点、终点）|
+|initPriority|整数|8|否|初始优先级1‑120，数值越大优先级越高；调度会动态修正实际优先级|
+|deadline|时间|N/A|否|任务截止时间，秒精度，优先级修正条件之一|
+|robotType|字符串|N/A|否|`GROUPS`资源组 / `ROBOTS`机器人编号|
+|robotCode|字符串数组|N/A|否|机器人编号集合|
+|robotTaskCode|字符串|64|否|外部任务唯一编号；不传则调度系统生成返回|
+|extra|JSON对象|N/A|否|自定义扩展透传字段|
+
+>targetRoute子对象：
+> - `type`：`SITE`站点；`ZONE`区域；`STORAGE`仓位；`CARRIER`载具等
+> - `code`：对应编号
+> - `operation`：`COLLECT`取货，`DELIVERY`送货，`ROTATE`旋转
+> - `carrierInfo[]`：载具信息（载具类型、编号、层号）
+> - `angleInfo`：角度信息
+
+**响应data字段**：`robotTaskCode`（全局唯一任务号）
+专用错误码：`Err_TaskTypeNotSupport`任务类型不支持；`Err_RobotGroupsNotMatch`机器人资源组不匹配；`Err_TargetRouteError`路径参数错误。
+
+### 2.1.3 任务继续执行接口
+- 路径：`/api/robot/controller/task/extend/continue`
+- POST，幂等：是
+
+>说明：一个任务包含多个步骤，每个步骤完成后，上层调用本接口驱动下一步骤；第一个步骤也需要调用此接口启动。若步骤设置autoStart自动开始，则可不调用；重复调用做幂等处理。
+
+请求入参：
+- triggerType：`SITE`站点 / `ROBOT`车号 / `TASK`任务链编号
+- triggerCode：对应编号
+- targetRoute：下一步目标路径对象
+- extra：扩展字段
+
+错误码：`Err_TaskNotStart`任务尚未开始；`Err_TaskFinished`任务已结束；`Err_TaskNotFound`任务找不到。
+
+### 2.1.4【国标】任务取消接口
+- 路径：`/api/robot/controller/task/cancel`
+- POST，幂等：是
+
+>说明：取消任务；软取消可下发回库任务；支持按任务号、机器人编号、载具编号批量取消。
+
+请求体关键字段
+|参数|说明|
+|---|---|
+|robotTaskCode|任务号，可选|
+|cancelType|`CANCEL`软取消；`DROP`人工介入硬取消|
+|carrierCode|载具编号，批量取消用|
+|robotCode|机器人编号，批量取消用|
+|reason|取消原因|
+|returnTaskType|软取消回库流程类型，默认`PF‑TASK‑CANCEL‑RETURN`|
+|targetRoute|取消后机器人目标位置|
+
+### 2.1.5【国标】任务优先级设置接口
+- 路径：`/api/robot/controller/task/priority`
+- POST，幂等：是
+
+>说明：任务创建后，修改初始优先级、截止时间；调度系统会综合工况动态调整实际执行优先级。
+
+入参：
+- robotTaskCode：任务编号（必填）
+- initPriority：1‑120
+- deadline：截止时间（可选）
+- extra：扩展
+
+### 2.1.6【国标】区域暂停与恢复机器人接口
+- 路径：`/api/robot/controller/zone/pause`
+- POST，幂等：是
+
+入参：
+- zoneCode：管控区域编号
+- invoke：`FREEZE`急停暂停；`RUN`恢复运行
+
+### 2.1.7【国标】区域归巢机器人接口
+- 路径：`/api/robot/controller/zone/homing`
+- POST，幂等：是
+
+>让指定区域机器人前往归巢点位，支持归巢后关机、定时开机。
+
+入参关键字段
+- zoneCodes：区域编号集合
+- autoShutdown：`YES`关机 / `NO`不关机
+- bootTime：预设开机时间（autoShutdown=YES生效）
+- expireTime：归巢超时时间
+
+返回data：`homingCode`归巢指令编号；`robotCount`接收到指令的机器人数量。
+
+### 2.1.8【国标】 区域驱离机器人接口
+- 路径：`/api/robot/controller/zone/banish`
+- POST，幂等：是
+
+>将区域内机器人驱离，禁止进入该区域。
+返回`banishCode`驱离指令编号。
+
+### 2.1.9【国标】区域封锁与恢复接口
+- 路径：`/api/robot/controller/zone/blockade`
+- POST，幂等：是
+
+>封锁：禁止机器人进入该区域；不强制区内机器人离开。
+invoke枚举：`BLOCKADE`封锁；`OPENUP`解封。
+
+### 2.1.10【国标】载具与站点绑定接口
+- 路径：`/api/robot/controller/carrier/bind`
+- POST，幂等：是
+
+>代表载具放置在该站点；前提：载具、站点无占用任务。
+入参：`carrierCode`载具编号，`siteCode`站点编号，`carrierDir`载具角度。
+
+### 2.1.11【国标】载具与站点解绑接口
+- 路径：`/api/robot/controller/carrier/unbind`
+- POST，幂等：是
+
+>解绑载具‑站点；carrierCode/siteCode至少传一个。
+
+### 2.1.12 存储对象与搬运对象绑定解绑接口
+- 路径：`/api/robot/controller/site/bind`
+- POST，幂等：是
+
+>slot：仓位/站点；invoke=`BIND`绑定 / `UNBIND`解绑；支持料箱、载具绑定解绑。
+
+### 2.1.13【国标】 载具禁用与启用
+- 路径：`/api/robot/controller/carrier/lock`
+- POST，幂等：是
+
+invoke：`LOCK`禁用；`UNLOCK`启用；传入`carrierCode`。
+
+### 2.1.14【国标】站点禁用与启用
+- 路径：`/api/robot/controller/site/lock`
+- POST，幂等：是
+
+invoke：`LOCK`禁用；`UNLOCK`启用；传入`siteCode`站点编号。
+
+### 2.1.15 外设执行通知接口【返回0】
+- 路径：`/rcs/rtas/spi/wcs/robot/eqpt/notify`
+- POST，幂等：是
+
+>上层通知调度：电梯、自动门等外设动作完成。
+>旧版本返回code=0；V4.2.8使用`notifyGbt`接口返回`SUCCESS`。
+
+### 2.1.16【国标】预调度任务下发接口
+- 路径：`/api/robot/controller/task/pretask`
+- POST，幂等：是
+
+>提前调度机器人到达点位等待业务任务。
+入参：`siteCode`站点；`nextTaskTime`预计多久后执行真实任务，单位秒。
+
+### 2.1.17【国标】查询任务状态接口
+- 路径：`/api/robot/controller/task/query`
+- POST，幂等：是
+
+>根据`robotTaskCode`查询单条任务状态。
+返回taskStatus枚举：`QUEUE`队列中；`WAIT`等待；`EXECUTING`执行；`MANUALED`人工完成；`FINISHED`已完成；`CANCELLED`已取消。
+
+### 2.1.18【国标】查询机器人状态接口
+- 路径：`/api/robot/controller/robot/query`
+- POST，幂等：是
+
+传入`singleRobotCode`机器人编号，返回：电量、坐标、速度、在线状态、任务状态、携带载具编号、告警信息。
+
+### 2.1.19【国标】查询载具状态接口
+- 路径：`/api/robot/controller/carrier/query`
+- POST，幂等：是
+
+传入`carrierCode`，返回：所在站点、绑定任务号、坐标、载具状态、仓位编号、所属机器人编号。
+
+### 2.1.20 物料绑定接口
+- 路径：`/api/robot/controller/matlabel/bind`
+- POST，幂等：是
+
+>载具绑定物料标签。入参：carrierCode，matLabel物料标签。
+
+### 2.1.21 物料解绑接口
+- 路径：`/api/robot/controller/matlabel/unbind`
+- POST，幂等：是
+
+### 2.1.22 外设执行通知接口【V4.2.8 返回SUCCESS】
+- 路径：`/rcs/rtas/spi/wcs/robot/eqpt/notifyGbt`
+- POST，幂等：是
+>新版本国标外设通知，返回code=SUCCESS，兼容电梯、自动门。
+
+## 2.2 反馈接收SPI 接口说明
+>**SPI：RCS‑2000作为调用方，主动回调上层WMS/MES服务地址，推送事件、告警、状态。需要在RCS后台配置上层回调地址。**
+
+### 2.2.1【国标】任务执行过程回馈接口
+- 回调路径示例：`/api/robot/reporter/task`
+>任务事件上报：任务开始、离开储位、任务完成等事件。
+values.method：`start`任务开始；`outbin`走出储位；`end`任务完成。
+
+### 2.2.2 请求资源接口
+- 回调路径：`/api/robot/reporter/resource`
+>RCS向上层申请资源：申请站点、仓位、载具。applyType：`APPLY_SITE`申请站点、`APPLY_BIN`申请仓位。上层返回目标点位信息。
+
+### 2.2.3 请求外设接口
+- 回调路径：`/api/robot/reporter/eqpt`
+>RCS向上层请求电梯、自动门外设资源。
+
+### 2.2.4【国标】 机器人归巢完成回馈接口
+- 回调路径示例：`/api/robot/reporter/zone/homing`
+>归巢全部完成/超时回调通知上层。后台需要开启业务通知开关`ZONE_HOMING`。
+
+### 2.2.5【国标】区域驱离机器人完成回馈接口
+- 回调路径示例：`/api/robot/reporter/zone/banish`
+驱离全部完成或超时通知；后台开启开关`ZONE_BANISH`。
+
+### 2.2.6【国标】机器人异常告警上报接口
+- 回调路径示例：`/api/robot/reporter/robot/warning`
+>机器人严重故障告警上报，仅推送一次；后台开启开关`AMR_ALARM`。
+
+### 2.2.7【国标】任务异常告警上报接口
+- 回调路径示例：`/api/robot/reporter/task/warning`
+>任务执行异常告警上报，仅推送一次；后台开启开关`TASK_ALARM`。
+
+### 2.2.8 绑定解绑通知
+- 回调路径示例：`/api/robot/reporter/bind`
+>载具/仓位发生绑定、解绑动作时RCS回调上层；后台开启开关`BIND`。
+invoke=`BIND`绑定 / `UNBIND`解绑。
+
+# 3 任务下发接口调用示例
+>文档包含潜伏车、CTU、叉车、滚筒车等各类机器人`task/submit`完整http+json请求样例，详见原始PDF文档3章节。
+
+# 4 典型调度场景
+1. 场景一：背货架AMR 在货架底下待命任务调度场景
+2. 场景二：普通背货架任务调度场景
+3. 场景三：辊筒AMR 任务调度场景
+4. 场景四：CTU 输送线预调度+入库
+5. 场景五：CTU 梳齿式工作站入库
+6. 场景六：潜伏车顺序出库场景（任务组GROUP_SEQ典型用法）
+7. 场景七：潜伏车搬运与外设交互场景
+
+>每个场景给出：上层系统 ↔ HIK调度系统交互步骤、对应接口编号。
+
+**潜伏车顺序出库重点说明**
+>方式一（推荐）
+>1）先调用**任务组接口2.1.1**，定义groupCode、策略、顺序；
+>2）多次调用**任务下发2.1.2**，传入groupCode下发子任务。
+>
+>方式二（不推荐）：任务下发接口直接携带groupCode、sequence、seqType。
+
+# 5 更新说明
+|更新时间|更新人员|更新内容|
+|---|---|---|
+|2024/8/30|王勇52|1.编写4.2 接口文档|
+|2024/9/3|王勇52|1.增加典型调度场景|
+|2025/8/11|王勇52|1.修改预调度接口任务数字段描述|
+
+---
+
+>说明：本Markdown为文档结构化转写，部分超长http请求样例做简化；实际开发请以PDF原始报文样例复制使用。
+>核心关键点总结（开发提示）
+>1. API（WMS调用RCS）：2.1开头；SPI回调（RCS调用WMS）：2.2开头，需要RCS后台配置上层回调地址。
+>2. 全部POST，JSON；签名使用HMAC‑SHA256，签名放url query参数sign。
+>3. 任务顺序出库：优先使用任务组接口2.1.1。
+>4. 外设交互两套通知接口：旧版notify（code=0）；新版notifyGbt（code=SUCCESS）V4.2.8+。
+>5. 告警、归巢、驱离、绑定解绑回调，需要在RCS后台业务通知开启对应开关，否则不会推送SPI。
+
+如果你需要，我可以进一步输出一份：**WMS对接海康RCS‑2000V4.2极简对接清单（字段清单+时序）**。
@@ -2900,7 +2900,7 @@ PAD：3台iDATA P1，浏览器访问服务器B，检验、拍照、签字
 项目A：bj_power_dashboard  项目a是一个看板系统,是一段H5的前端代码,它的数据来源于项目B,来源于MES系统。
 项目B：bj_power_mes  项目B,MES系统是一个智能产线的控制系统。Go语言加vue代码。
 项目C：bj_power_wms  项目C,WMS仓库系统。Go语言加vue代码。
-项目D：bj_power_workstation  项目D，govcl实现的工位终端软件，因为要采集拧紧枪数据。
+项目D：bj_power_workstation  项目D，Go语言加vue代码实现的工位终端软件，因为要采集拧紧枪数据。


 整个厂房构成：
@@ -2956,7 +2956,7 @@ PAD：3台iDATA P1，浏览器访问服务器B，检验、拍照、签字

 "能够实时采集拧紧扭矩、角度、时间、拧紧结果、操作人员、工单号等数据。"

-文档已明确要求。 项目D用govcl实现工位终端软件，采集拧紧枪数据，数据回传项目B。这条没问题。
+文档已明确要求。 项目D用Go语言加vue代码实现工位终端软件，采集拧紧枪数据，数据回传项目B。这条没问题。

 总结修正表
 您的描述	文档依据	结论
@@ -2970,10 +2970,10 @@ WMS有显示器可控制	第(七)节3.(8)条：55寸电视展示库存	修正：
 A	bj_power_dashboard	看板H5前端	看板主机（联想ECI-521）
 B	bj_power_mes	MES后端+前端（Go+Vue）	服务器（联想ECI-521）
 C	bj_power_wms	WMS后端+前端（Go+Vue）	服务器（联想ECI-521）
-D	bj_power_workstation	工位终端（govcl）	12台工位一体机
+D	bj_power_workstation	工位终端（Go+Vue）	12台工位一体机
 服务器B上跑： 项目B后端 + 项目C后端 + MySQL + Redis。项目B/C的前端通过浏览器访问。

-12台工位机跑： 项目D（govcl桌面程序），数据读写走项目B API。
+12台工位机跑： 项目D（Go+Vue Web应用），数据读写走项目B API。

 看板主机跑： 项目A（H5），数据走项目B API（读缓存）。

@@ -2987,7 +2987,7 @@ D	bj_power_workstation	工位终端（govcl）	12台工位一体机
 A 看板	H5前端	展示产线/仓储/AGV数据
 B MES	Go+Vue	产线控制、工单、工序下发PLC、AGV调度
 C WMS	Go+Vue	入库、出库、库存、追溯
-D 工位终端	govcl桌面程序	工位交互、拧紧枪数据采集、工艺PDF预览
+D 工位终端	Go+Vue Web应用	工位交互、拧紧枪数据采集、工艺PDF预览
 二、交互有没有问题
 交互拓扑：

@@ -3088,7 +3088,7 @@ text
          │
          ├──► 看板主机：看板A(H5) ──► 读Redis缓存
          │
-          ├──► 12台工位终端D(govcl) ──► 调MES API + 本地缓存
+          ├──► 12台工位终端D(Go+Vue) ──► 调MES API + 本地缓存
          │
          ├──► 3台PAD ──► 浏览器访问MES/WMS前端
          │
@@ -0,0 +1,283 @@
+# 北京电力智能产线系统 — 需求规格与开发规划
+
+> 本文档综合《项目说明.md》《头脑风暴.md》及甲方（孙工/韩总）通话录音纪要整理，作为 5 个软件项目的开发总纲。逻辑闭环，尽量不遗漏文档/录音中提到的需求点。
+
+***
+
+## 一、项目背景
+
+为北京电力设备总厂建设一条自动化智能产线（传送带流水线，12 道工序）。软件侧规划：
+
+- 精确对接西门子 S7-1214 PLC：下发工序组合（如 `135` → 只做 1、3、5 序；`234` → 做 2、3、4 序）。
+- 对接海康 AGV 调度系统（RCS-2000）：指挥 2 台 AGV 在 21 个接驳台之间搬运物料。
+- 库房记账与追溯（WMS）：管到区域 + 数量 / 序列号，无智能立库、无传感器货架坐标。
+- 产线控制 (MES) + 库房 (WMS) + 看板 (Dashboard) + 工位终端 + 库房客户端。
+
+**结论性判断**：无需独立 MIS 系统。甲方 5 个系统，我方开发 3 类后台（MES/WMS/工位终端）与 2 类前端（看板/库房客户端），AGV 调度系统与拧紧工具系统为外部既有系统（仅对接）。
+
+**业务可追溯**：入库、出库、加工、页面操作、触发agv ，等等，都需要记录清楚，在工件、工单、审核、等场景标记清楚。所以，登录权限必须完善、菜单权限，token失效时间要短。
+
+***
+
+## 二、业务全貌与核心流程
+
+### 2.1 生产模式
+
+- **工单驱动、按日批量备料**：一个合同 = 一个工单（如 100 台设备），按日排产（今天 20 台）。开工前用 AGV 将当日所需全部物料（芯片=器件、螺丝=结构件、屏幕等）一次性配送到各工位（新建工单时，可以选择都是哪个工位送料，分别是什么料。仓库管理后台可以把多个料打包成一个概念，即套件。工单支持混合选择【工件（独立物料）】与【套件（虚拟物料组合）】），软件层面中途没有停线补料逻辑（返修/报废才走补料申请，主管审批）。
+- **出库强约束**：累计出库 ≤ 工单 BOM 需求量，超发需补料流程。
+
+### 2.2 两类物料差异化管理
+
+| 类型  | 例        | 管理粒度      | 入库方式                                                       | 出库方式 |
+| --- | -------- | --------- | ---------------------------------------------------------- | :--- |
+| 精密件 | 芯片/器件/成品 | 序列号 SN，逐件 | 扫码逐件录入，单件追溯，支持连续扫码。（先选择模版，再扫描，否则大量其他信息需要填入）。可人工修改工件，再保存提交。 | 同入库  |
+| 结构件 | 机加工件/螺丝  | 图号+批次     | 按批次/图号录入，支持 Excel 批量导入，分多批到货                               | 同入库  |
+
+- 物料总状态：原材料 / 半成品（记录已完成工序）/ 成品。
+- 检验三状态：未检 → 合格 / 不合格，需**批量翻转**；分来料检、过程检、成品检；部分检验项需录实测值。
+- 为保证通用性，两种物料，都用同样的表结构，结构件不写 sn即可，也可以手动选择物料类型。
+- 物料，必须有 code唯一码（物料模版里面有，新建物料时必须选择物料模版，也是物料种类，比例螺丝、剪刀，等分类），真实名称、简称、描述、等等，包含不限于上面字段。
+
+### 2.3 完整业务流程（闭环）
+
+```
+1. 库房入库     WMS 记账（精密件逐扫 SN / 结构件 Excel 批次）。为保证一致性，不做特殊区分，都可以批量、或者扫码、或者手动输入sn。功能越全越好，仅仅类型区分，和sn码有或无。
+2. 创建工单     MES：工单 + BOM + 日排产
+3. 锁库存       MES 调 WMS：按 BOM 校验并锁定库存（批次/SN）
+4. 生成备料单   系统按日排产自动算料 → 备料单 。
+5. AGV 配送     MES 调海康 RCS：库房接驳台 DOCK21 → 产线 DOCK01~20
+6. 到货上料     主线扫码枪识别托盘 → 分流决策 → 送往目标支线
+7. 支线装配     12 工位，拧紧枪采集数据，工位终端实时显示
+8. 工序报工     支线扫码枪扫码报工 → MES 更新工单进度
+9. 完工         全部工序完成 → 半成品/成品回库 WMS
+10. 追溯/打印    流程卡：工序操作人/检验人/检验结果汇总 PDF
+```
+
+补充
+
+```
+# 整体业务方案 补充
+1、日排产：可编排当日以及未来多天的生产计划，作为仓库的前瞻参考信息；日排产仅做计划预告，**不直接触发出库、不下发领料指令**。
+2、MES向下游WMS下发生产工单，工单为仓库出库唯一挂靠载体；工单携带产品、BOM、物料总需求量。
+3、工单只管控物料总的需求数量，**不管理出库节奏，不做拉动式叫料控制**；每次出库何时出、出多少、分几趟AGV送货，决策权交由仓库/WMS自主决定。
+4、仓库配送拥有两种自由选择：可早上一次性将工单所需物料全部出库配送完毕；也可拆分为多批次，分次出库、分批AGV送货。
+5、WMS实时维护工单物料台账：物料总需求数量、累计已出库数量、剩余待出库数量；系统强制校验，累计出库数量不可超过工单总需求量；当累计出库等于总需求，工单领料完结，禁止再出库。
+6、后期如需升级为MES拉动叫料补料模式，现有工单‑出库架构可无缝叠加，无需推翻改造。
+```
+
+***
+
+## 三、五个项目职责、技术栈与页面
+
+项目构成以《项目说明.md》为准，共 5 个，均可单独编译、单独部署。
+
+### 项目 A：bj\_power\_dashboard（看板，H5 前端）
+
+- 技术栈：Vue/React + ECharts + SSE。只展示，不读写业务。数据来源于项目 B(MES)，经 Redis 缓存。
+- 部署：厂房大门口大显示器（联想 ECI-521 主机 + 100 吋屏）。
+- 页面：
+  1. 生产数据看板（产线运行状态、产量、进度、合格率）
+  2. 仓储数据看板（库存总量、物料种类、出入库动态）
+  3. 物流设备看板（AGV 位置/状态/电量/任务执行）
+  4. 异常报警（设备故障、物料短缺、AGV 异常）
+  5. 三维产线模型（可选，展示各工位/AGV 状态，数据须准确）【录音：面子+里子】
+
+### 项目 B：bj\_power\_mes（MES 产线控制，Go + Vue）
+
+- 技术栈：Go 后端（go-zero 或 gin）+ Vue 前端；**前端需自适应 平板/iPad/手机/台式机**。
+- 部署：库房/业务服务器（联想 ECI-521），`MySQL`（MES 独立库）。
+- 职责：工单/排产/BOM/备料、调 WMS 锁库扣库、调海康 RCS 下发 AGV、写 PLC 工序码+读完成信号、收拧紧数据、工序扫码报工、半成品流转、追溯、看板缓存接口。
+- 页面：
+  1. 登录/个人中心（自适应）
+  2. 工单管理（创建/查询/排产）/ BOM / 备料单
+  3. 工位监控（12 工位状态实时）
+  4. PLC / AGV 状态页
+  5. 半成品流转
+  6. 工序扫码报工记录 / 进度
+  7. 拧紧数据查询 / 追溯报表 / 流程卡生成打印
+  8. 看板数据接口（Redis 缓存，供项目 A）
+
+### 项目 C：bj\_power\_wms（WMS 仓库，纯 Go，无前端）
+
+- 技术栈：Go 后端。**不包含前端代码**。
+- 部署：库房/业务服务器，`MySQL`（WMS 独立库）。
+- 职责：物料/批次/SN、出入库、库存锁定/扣减、检验、半成品/成品、包装追溯；对外提供 API。
+- 无页面（前端由项目 E 提供）。
+
+### 项目 D：bj\_power\_workstation（12 个工位终端，Go + Vue）
+
+- 技术栈：**Go + Vue Web 应用**（独立项目，因为有扫码枪和拧紧枪）。运行于 12 台触控一体机（浏览器访问）。
+- 数据来源：项目 B(MES) API。本地 SQLite 缓存待上报的拧紧数据，**点"完成"才上报 MES**，失败保留重试（断点续传）；不存储历史数据，历史数据来自 MES。
+- 页面/功能：
+  1. 登录（账号自动记录操作人）
+  2. 当前工单 + 当前工序导航（完成一步点"下一步"）
+  3. 工艺文件 PDF 预览（预缓存，工位配置"工序文件"上传）
+  4. 拧紧结果实时显示（扭矩/角度/OK·NG，进度如 8/10 颗，NG 红色闪烁）
+  5. 扫码报工（主线/支线）
+  6. 完成上报 / 返修重置（记录历史操作日志）/ 暂存退回库房（半成品）
+
+### 项目 E：bj\_power\_wms\_client（库房客户端，Go + Vue）
+
+- 技术栈：**Go + Vue Web 应用**（独立项目，因为有扫码枪）。
+- 部署：库房 2 台台式机（各一显示屏，分出入库），浏览器输入 WMS(项目 C) 地址。
+- 页面/功能：
+  1. 登录
+  2. 入库：精密件逐件扫码（连续扫码、实时已扫数量）、结构件 Excel 批量导入 / 手动单条，多批到货追加
+  3. 出库：按备料单/工单领料、扫码复核（校验物料+批次）、先进先出、异常出库实时报警、自动扣减库存
+  4. 库存查询、盘点（动态/静态/抽盘、扫码快速盘点）
+  5. 质量检验：未检/合格/不合格管理、批量翻转、实测值录入
+  6. 半成品/成品入库、包装绑定（箱号 ↔ SN）
+
+***
+
+## 四、系统交互与 API 契约（跨项目）
+
+### 4.1 拓扑
+
+```
+工位终端D ──HTTP──► MES(B) API ──┬──► [MES库 MySQL]
+PAD ───浏览器──► MES(B) 前端     ├──► Redis（看板缓存）
+看板A ───SSE/HTTP──► MES 读缓存   │
+库房客户端E ──HTTP──► WMS(C) API ─┴──► [WMS库 MySQL]
+     WMS(C) ◄══API══► MES(B)     （独立库，联动）
+外部：海康RCS(AGV)、西门子PLC、丹尼科尔拧紧工具
+```
+
+### 4.2 关键 API（B ↔ C，独立数据库通过 API 互通）
+
+| 方向   | 接口                                    | 说明                               |
+| ---- | ------------------------------------- | -------------------------------- |
+| C 提供 | `POST /api/stock/lock`                | 工单锁定库存（批次/SN），带 `order_no`       |
+| C 提供 | `POST /api/stock/deduct`              | 出库扣减，`order_no`+qty，WMS 校验累计≤BOM |
+| C 提供 | `GET /api/stock/query`                | 库存查询（MES 查料）                     |
+| C 提供 | `POST /api/semi/inbound` / `outbound` | 半成品入库/出库，携带"已完成工序"               |
+| B 提供 | `GET /api/order/query`                | 工单/工序进度（WMS 取工单）                 |
+
+### 4.3 对接外部
+
+- **海康 RCS**：HTTP，HMAC-SHA256 签名 + `X-LR-REQUEST-ID` 防重放。封装独立 `HikRcsClient`：`SubmitTask(fromDock,toDock,carrier)`、`QueryTask`。DOCK01\~20 产线，DOCK21 库房；路径规划 RCS 自理。
+- **西门子 PLC (S7-1214)**：用整型寄存器写工序码（如 MW100=135），读完成信号位（M100.0）；**未收到完成信号不下发下一条**。
+- **拧紧工具（丹尼科尔）**：实时采集扭矩/角度/时间/结果/操作人/工单号，异常报警；数据对接 MES 质量追溯。
+
+### 4.4 看板缓存方案（已采纳）
+
+- 看板读 Redis，不直查 MES 业务库。TTL=60s；业务变更主动刷新/删 key，未刷新也会过期回源 DB 重查。
+- **防击穿**：同一 key 同一时刻仅允许一个查询打到 DB（SETNX 加锁），其他等待后重试读缓存。
+- 看板局部刷新用 SSE 推送；工位/库房客户端走普通 HTTP（强一致性）。
+
+### 4.5 拧紧数据两段式（已采纳）
+
+- 工位终端 D：实时显示 + SQLite 缓存每把数据 → 点"完成"才上报 MES → 成功后标记同步；失败保留本地重试。历史数据只存 MES。
+
+### 4.6 半成品流转（已采纳）
+
+- 工位"暂存/退回库房" → D 上报 MES 记录已完成工序 → MES 调 WMS 半成品入库 → 重上线 WMS 出库 → MES 从下一工序继续。
+
+***
+
+## 五、数据模型（核心表，逻辑闭环）
+
+### 5.1 WMS(C) 库
+
+| 表                                    | 关键字段                                                                                               | 说明             |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------- | -------------- |
+| `material`                           | code,name,spec,unit,manage\_mode(1批次/2序列号),is\_batch\_managed,is\_serial\_managed                  | 物料档案           |
+| `zone`                               | zone\_code,zone\_name                                                                              | 待检/合格/不合格/退货区  |
+| `inventory_batch`                    | material\_code,batch\_no,quantity,locked\_qty,production\_date,supplier,quality\_status,zone\_code | 结构件批次台账        |
+| `serial_number`                      | sn\_code,material\_code,batch\_no,status(在库/锁定/出库/使用/报废),current\_zone,last\_in/out                | 精密件/成品单件       |
+| `inventory_lock`                     | batch\_id,order\_no,locked\_qty,status,expired\_at                                                 | 批量锁定、防超卖       |
+| `inbound_order` / `inbound_detail`   | 类型、批次/SN、数量、操作人、台账                                                                                 | 入库（含半成品/成品）    |
+| `outbound_order` / `outbound_detail` | order\_no,qty,批次/SN、复核人                                                                            | 出库，关联工单，BOM 校验 |
+| `inspection_record`                  | target(批次/SN),status(未检/合格/不合格),inspector,time,result\_value                                       | 来料/过程/成品检      |
+| `semi_finished`                      | sn,completed\_process,quantity,zone                                                                | 半成品库存          |
+| `package_box`                        | box\_no,sn\_list                                                                                   | 包装箱 ↔ SN 关联    |
+
+### 5.2 MES(B) 库
+
+| 表                                     | 关键字段                                                             | 说明      |
+| ------------------------------------- | ---------------------------------------------------------------- | ------- |
+| `work_order`                          | order\_no,product\_code,total\_qty,daily\_qty,plan\_start,status | 工单      |
+| `work_order_bom`                      | product\_code,material\_code,unit\_qty,loss\_rate                | BOM     |
+| `daily_plan`                          | order\_no,plan\_date,qty                                         | 日排产     |
+| `material_request`                    | order\_no,material\_code,qty,status,target\_dock                 | 备料单     |
+| `dock_station`                        | dock\_code(DOCK01\~21),dock\_type                                | 21 接驳台  |
+| `plan_process` / `work_order_process` | order\_no,process\_code(135),status                              | 工序 / 流转 |
+| `torque_result`                       | sn,strain,angle,result,operator,work\_order,time                 | 拧紧数据    |
+| `scan_record`                         | station,sn,order\_no,type,operator,time                          | 扫码报工    |
+| `association_trace`                   | sn → 工序/检验/物料批次 关联链                                              | 追溯      |
+| RBAC                                  | user/role/permission/dept                                        | 登录与权限   |
+
+> 字段以开发时逐表 DDL 为准，此表为设计基线。
+
+***
+
+## 六、设备/硬件部署对应
+
+| 设备            | 数量          | 运行           | 数据来源       |
+| ------------- | ----------- | ------------ | ---------- |
+| 库房台式机         | 2           | 项目 E（出入库）    | WMS(C)     |
+| 看板大屏 + 主机     | 1           | 项目 A         | MES 缓存     |
+| 工位触控一体机       | 12          | 项目 D         | MES(B)     |
+| PAD(iData P1) | 3           | 浏览器访问 B/C 前端 | MES/WMS    |
+| WMS 显示器(55 吋) | 1           | 展示库存总览       | WMS        |
+| 扫码枪           | 主线2+支线12+库房 | /            | 上报 MES/WMS |
+| AGV           | 2           | 海康 RCS（对接）   | /          |
+| PLC           | 1           | 西门子          | MES 写工序    |
+| 拧紧工具          | /           | 丹尼科尔（对接）     | MES 收数据    |
+
+***
+
+## 七、分阶段开发路线（先怎么开始，再怎么开始）
+
+**阶段 0 — 工程地基**
+
+- 建 5 个工程骨架（Go 后端 + Vue 前端），改 module/包名，各自 `go build` / `pnpm build` 可运行；统一配置、日志、鉴权骨架。
+
+**阶段 1 — C WMS 核心 + E 库房客户端**
+
+- WMS 建表（物料/批次/SN/锁定/检验）→ 入库（扫码+Excel）→ 出库（锁定→扣减→BOM 校验）→ 检验批量翻转 → 追溯查询。
+- E 库房客户端界面对接，最快出可演示成果。
+
+**阶段 2 — B MES 工单/排产/备料 + 联动**
+
+- MES 建表 → 工单+BOM+日排产 → 备料单生成 → 调 WMS 查库/锁库/扣库；前端自适应页面（web/pad）。
+
+**阶段 3 — 外部对接**
+
+- 海康 RCS 客户端（签名+下发+查状态）→ AGV 闭环；PLC 工序码下发+完成信号轮询；丹尼科尔拧紧工具对接。
+
+**阶段 4 — D 工位终端 + E 深化**
+
+- D：工序导航/工艺PDF/拧紧实时/SQLite缓存/完成上报/扫码报工/暂存；E：出库复核、盘点、批量翻转、包装绑定。
+
+**阶段 5 — A 看板 + SSE + Redis**
+
+- 看板页 + MES dashboard 缓存接口（Redis1 分钟+防击穿）+ SSE 局部刷新 + 3D 模型（可选）。
+
+**阶段 6 — 闭环与验收**
+
+- 全链路联调（创建工单→备料→AGV→装配→拧紧→报工→完工入库）、流程卡打印、半成品流转、容错/断点续传、数据备份（保留≥1 年）。
+
+***
+
+## 八、验收相关指标（软件需支撑，不越硬件职责）
+
+- 扫码识别率一次成功率 ≥92%（记录扫码成功/失败，为验收提供数据证据）。
+- 看板刷新延迟 ≤4s（99%），WMS↔MES 同步 ≤2s，AGV 任务成功率 ≥99%（软件侧记录与重试）。
+- 数据保留 ≥1 年，每日自动备份。
+- 知识产权归甲方，支持二次开发（模块解耦、独立升级）。
+
+***
+
+## 九、待甲方确认清单（遗留）
+
+1. 结构件批次号规则：甲方定义 or 系统自动生成？   答：自动生产，按日期 + 自增数量
+2. 拧紧工具对接数据字段与协议（丹尼科尔是否提供 API）。 答：暂放
+3. AGV 位置/电量实时推送 or 轮询。 答：见文档：AGV海康.md
+4. PAD 网络与离线需求。  答：什么需求，离线不可工作，因为要登录授权
+5. 看板 3D 模型精度需求。 答：暂放
+
+> 已采纳的甲方明确结论（来自对话/录音）：
+> ① 库房 2 台台式机 ✅　② 看板走 Redis、1 分钟过期、防击穿 ✅
+> ③ WMS 与 MES 独立库、API 互通 ✅　④ 拧紧数据本地缓存、点完成上报 MES ✅　⑤ 半成品流转记录已完成工序 ✅
+
@@ -5,11 +5,11 @@
 项目A：bj_power_dashboard  项目a是一个看板系统,是一段H5的前端代码,它的数据来源于项目B,来源于MES系统。
 项目B：bj_power_mes  项目B,MES系统是一个智能产线的控制系统。Go语言加vue代码。
 项目C：bj_power_wms  项目C,WMS仓库系统。Go语言不包含前端代码。
-项目D：bj_power_workstation  项目D，govcl实现的工位终端软件，因为要采集拧紧枪数据。
-项目E：bj_power_wms_client  项目E,WMS仓库系统。Go语言加vue代码。（单独项目因为有扫码枪））
+项目D：bj_power_workstation  项目D，12个工位终端软件，Go语言加vue代码。（单独项目因为有扫码枪）。
+项目E：bj_power_wms_client  项目E,WMS仓库系统。Go语言加vue代码。（单独项目因为有扫码枪）


-注意，5个项目，每个都单独部署。我把5个项目放到一个git，一个文件夹了。
+注意，5个项目，每个都可以单独编译、单独部署。我把5个项目放到一个git，一个文件夹了。

 整个厂房构成：
 1、仓库，库房。有两台台式机，每个台式机一个显示屏。这两个工位分为出库和入库。（因为有扫码枪所以有go服务器代码+前端代码）两台电脑数据来源，来源于wms系统。