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极简对接清单（字段清单+时序）**。