From c85c3bd6f1caaa809f3f8ab349ced857311c0472 Mon Sep 17 00:00:00 2001 From: SunYF <123@hard_man.com> Date: Thu, 27 Aug 2026 15:46:15 +0800 Subject: [PATCH] docs: update project docs and add new reference documents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 修正项目说明文档中关于项目D、E的技术栈与部署描述 2. 新增完整的需求规格与开发规划文档 3. 新增海康RCS-2000 V4.2接口协议文档 --- AGV海康.md | 474 ++++++++++++++++++++++++++++++++++++++++++ 头脑风暴.md | 12 +- 需求规格与开发规划.md | 283 +++++++++++++++++++++++++ 项目说明.md | 6 +- 4 files changed, 766 insertions(+), 9 deletions(-) create mode 100644 AGV海康.md create mode 100644 需求规格与开发规划.md diff --git a/AGV海康.md b/AGV海康.md new file mode 100644 index 0000000..6f9d1f7 --- /dev/null +++ b/AGV海康.md @@ -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极简对接清单（字段清单+时序）**。 \ No newline at end of file diff --git a/头脑风暴.md b/头脑风暴.md index e7bfa61..c468356 100644 --- a/头脑风暴.md +++ b/头脑风暴.md @@ -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前端 │ diff --git a/需求规格与开发规划.md b/需求规格与开发规划.md new file mode 100644 index 0000000..59363db --- /dev/null +++ b/需求规格与开发规划.md @@ -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 ✅　⑤ 半成品流转记录已完成工序 ✅ + diff --git a/项目说明.md b/项目说明.md index 5484892..81e42a2 100644 --- a/项目说明.md +++ b/项目说明.md @@ -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系统。