Files
bj_power/产线API.md
T
SunYF b0c048d9aa feat: 新增收集式校验错误弹窗及工位报警语音播报
新增 ErrorListDialog 组件用于统一展示结构化校验错误信息,实现报错一次收全;新增工位报警语音播报功能,通过浏览器 SpeechSynthesis 播放本工位相关报警;调整物料类别及序列号字段文案,移除「其他」类别;新增工单实际开始字段及采集方式配置;优化 AGV 及 PlcSend 页签刷新逻辑;新增看板物料追溯及工位报警接口;删除 PLC 强制写 M 位及相关测试代码;同步数据库字段注释及补丁。
2026-10-20 16:36:26 +08:00

57 KiB
Raw Blame History

北京哈德曼产线控制系统接口协议

文档类别:产线控制系统(WMS 仓储管理 / MES 产线控制 / 工位终端) 文档编号:BJP-API-V1.0

目录

  1. 协议概述
    • 1.1 系统组成与服务端口
    • 1.2 鉴权方式
    • 1.3 请求首部字段
    • 1.4 请求报文消息体
    • 1.5 响应首部字段
    • 1.6 响应报文消息体(统一响应体)
    • 1.7 响应状态码
    • 1.8 业务错误码
    • 1.9 通用约定(时间、分页、导出)
  2. 业务接口说明
    • 2.1 WMS 仓储管理系统接口
    • 2.2 MES 产线控制系统接口
    • 2.3 工位终端接口
    • 2.4 系统对接接口
  3. 调用示例
  4. 典型业务场景
  5. 更新说明

1 协议概述

本文档描述北京哈德曼产线控制系统自有的全部 HTTP 接口,覆盖 WMS 仓储管理系统、MES 产线控制系统、工位终端三套服务,以及与海康 RCS-Lite V1.5 机器人调度系统的对接段。海康 RCS-Lite V1.5 的协议细节以随附的《AGV海康litev1.5.md》为准,本文档 2.4.5 节仅描述对接边界与 bj_power 侧接口。 三套服务默认超时:连接 30 秒,数据返回 60 秒,超时返回连接失败。

1.1 系统组成与服务端口

系统 服务端口 职责 接口前缀
WMS 仓储管理系统 8890 物料档案、入库、出库、库存、来料检验、盘点、叫料仓库端、AGV 配送仓库端 /api
MES 产线控制系统 8888 工单排产、工艺流程、叫料真源、AGV 调度真源、报工、拧紧、质量检验、预警中心 /api/v1、/api/internal
工位终端 8892 产线工位触屏终端:登录、任务、报工、拧紧、叫料、离线队列补报 /api
海康 RCS-Lite V1.5 8182(由海康提供) 机器人调度(详见《AGV海康litev1.5.md》) /rCMS/services/rest/hikRpcService

调用基址示例:http://<服务器IP>:8890(WMS)、http://<服务器IP>:8888(MES)、http://<工位终端IP>:8892(工位终端)。完整请求路径 = 基址 + 接口前缀 + 路径。

1.2 鉴权方式

系统提供三档鉴权,按接口分组应用:

档位 适用接口 说明
① JWT 各系统业务接口 登录后获取访问令牌,请求头携带 Authorization: Bearer <token>;HS256 签名,默认有效期 1 小时;支持滑动续签(见 1.5)
② X-API-TOKEN 服务间内部接口 /api/internal/* 项目内部服务(工位终端、看板、WMS↔MES)互调专用;令牌取值由部署配置项约定,由双方运维交接时确认,本文档不明文给出
③ 免鉴权 健康检查、登录、大屏展示、工艺文件直链、海康 RCS 回调 见各接口单独标注;海康回调端点生产环境必须以防火墙 / IP 白名单隔离

注意:MES 的工位终端接口在 X-API-TOKEN 之上再叠加工位登录 Bearer(双重校验);工位号与操作人由服务端从登录态可信注入,不接受客户端伪造,防止冒名上报。

1.3 请求首部字段

字段名 数据类型 是否必需 说明
Authorization 字符串 否(JWT 接口必需) 固定格式:Bearer <accessToken>
Content-Type 字符串 是(携带消息体时) 固定取值:application/json;charset=UTF-8
X-API-TOKEN 字符串 否(内部接口必需) 服务间调用令牌
X-Username 字符串 否 服务间调用时透传操作人姓名,服务端据此落库操作人;不传按接口默认值处理

1.4 请求报文消息体

只能使用 JSON 格式(UTF-8 编码) 或空字符串(无字符),不能使用 JSON 对象数组作为根格式或其他格式。业务请求的参数信息放在请求报文消息体当中;文件上传使用 multipart/form-data。

请求体大小上限:普通接口默认 1MB;文件上传接口按服务器配置(工艺 PDF / 检验照片最大 50MB),超限返回 413。

1.5 响应首部字段

字段名 是否必需 说明
Content-Type 否 固定取值:application/json;charset=UTF-8
X-Renewed-Token 否 滑动续签:当前令牌临近有效期时,WMS 在响应头返回续签后的新令牌,客户端应就地替换并继续使用

1.6 响应报文消息体(统一响应体)

所有接口返回统一 JSON 对象:

中文名称 字段名 数据类型 是否必须 说明
消息码 code 整数 是 0=成功;非 0=失败(各系统失败码取值不同,见 1.6.1)
提示消息 message 字符串 否 异常描述(中文)
业务数据 data JSON 对象/数组 否 返回的业务数据,失败时为 null

正常响应报文样例

{
    "code": 0,
    "message": "ok",
    "data": {"id": 1}
}

业务异常响应报文样例

{
    "code": -1,
    "message": "区域必填,请先选择入库区域",
    "data": null
}

1.6.1 三系统响应体差异(对接方必须注意)

系统 成功 业务失败 HTTP 状态码
WMS code=0,message="ok" code=-1,message 为中文错误描述 失败时携带真实 HTTP 状态(400/401/403/404/409/500)
MES code=0,message="success" code=业务错误码(如 3002/3202/3301),message 为中文错误描述 业务失败同样返回 HTTP 200,必须解析 body.code 判断成败;仅参数错误、未授权等返回 400/401
工位终端 code=0,message="ok" code=-1 失败时携带真实 HTTP 状态

MES 业务失败走「HTTP 200 + body.code≠0」,是与 WMS / 工位终端最大的行为差异。调用 MES 接口的一方不能只判断 HTTP 状态码,必须先解析响应体的 code。

1.7 响应状态码

状态码 说明
200 协议层处理成功(MES 业务失败也可能是 200,见 1.6.1)
400 请求参数错误 / 报文解析失败
401 未登录、令牌无效或过期
403 权限不足(按钮级权限未授权)
404 资源不存在
409 业务冲突(如单号重复、库存不足)
413 请求体超过大小上限
500 服务端内部错误,可重试

1.8 业务错误码

1.8.1 WMS / 工位终端

Code 含义
0 成功
-1 业务失败,具体原因见 message

1.8.2 MES(HTTP 200 + body.code)

Code 含义
0 成功
3002 业务数据校验 / 状态错误(如工单状态不允许当前操作)
3202 工位终端业务错误(如工位未登录、任务不存在)
3301 AGV 调度业务错误(如任务不存在、RCS 不可达)
3304 AGV 任务取消失败
3307 AGV 回调处理失败

完整错误码以各接口 message 描述为准,本文档不逐一列举内部错误码。

1.9 通用约定

约定 说明
时间格式 全部使用 Unix 秒(整数),如 createdAt、expireAt、lastLoginAt、recordedAt
分页参数 page(页码,默认 1)、pageSize(每页条数,默认 20,明细类默认 50)
排序 列表默认按创建时间倒序(最新记录在前)
导出日期 起止日期参数格式 YYYY-MM-DD,须成对传递;默认导出最近 3 个月,跨度不超过 1 年
导出文件 流式返回二进制 Excel,中文文件名经 filename*=UTF-8'' 编码
枚举取值 一律使用字符串或整数编码,见各接口字段表

2 业务接口说明

接口地址格式:基址 + 完整路径。凡标注「JWT」需登录令牌;标注「X-API-TOKEN」为服务间接口;标注「免鉴权」无需任何令牌。 详写分级:对接 / 对外接口给出完整字段表与示例;纯后台管理类接口给出路径清单与用途。

2.1 WMS 仓储管理系统接口

基址 http://<服务器IP>:8890,接口前缀 /api。

2.1.1 登录认证

健康检查:GET /api/health(免鉴权),返回服务状态,供运维探活。

POST /api/auth/login(免鉴权)

用户名 + 密码登录,返回 JWT 令牌。

请求体字段

参数名 数据类型 是否必须 说明
username 字符串 是 用户名
password 字符串 是 密码

响应 data 字段

字段名 类型 说明
token 字符串 JWT 访问令牌,后续请求放入 Authorization: Bearer <token>
expireAt 整数 令牌过期时间(Unix 秒)
weakPassword 布尔 是否弱密码(纯数字),仅提示,不影响登录
user 对象 当前用户:id / username / realName / role / roleId / dept

请求示例

{"username": "admin", "password": "******"}

2.1.2 用户与权限(RBAC)

方法 路径 用途
POST /api/user/change-password 修改本人密码(oldPassword / newPassword,新密码至少 6 位)
POST /api/user/logout 退出登录
GET /api/user/info 当前登录用户信息
GET /api/user/list 用户列表
POST /api/user/create 新建用户
POST /api/user/update 编辑用户
POST /api/user/delete 删除用户
GET /api/roles 角色列表
GET /api/roles/options 角色下拉选项
POST /api/roles 新建角色
POST /api/roles/update 编辑角色(含按钮级权限勾选)
POST /api/roles/delete 删除角色
GET /api/permissions 权限清单(菜单 + 按钮)
POST /api/rbac/seed RBAC 数据初始化(运维 / 初始化专用,带管理员密码门,不对登录用户开放)
GET /api/event/logs 操作日志

权限模型:角色 → 权限码集合;接口与按钮均按权限码校验,未授权返回 403。

2.1.3 物料档案

方法 路径 用途
GET /api/material/query 物料分页查询(支持编码 / 名称模糊搜索)
GET /api/material/list 物料全量列表(下拉拾取器)
GET /api/material/detail 物料详情
POST /api/material/create 新增物料(权限 material:create)
POST /api/material/update 编辑物料(权限 material:edit)
POST /api/material/toggle-status 启用 / 停用物料(权限 material:edit)
GET /api/material/export 导出物料档案(权限 material:export)
POST /api/material/import Excel 批量导入物料(权限 material:import)

物料档案为 WMS / MES 两库双向同步的主数据,同步接口见 2.4.4。

2.1.4 入库

POST /api/inbound/create(JWT)

创建入库单,落入统一库存主表。按序列号入库还是按数量入库,由物料档案的「序列号(是/否)」(sn_mode)驱动分叉。

请求体字段

参数名 数据类型 是否必须 说明
inboundNo 字符串 否 入库单号,留空自动生成;填写必须全局唯一
inboundType 字符串 是 入库类型:purchase 采购 / semi 半成品 / finished 成品 / return 退料 / other 其他
manageMode 整数 否 类型防呆校验:1 结构件 / 2 电气件 / 3 其他(0=不校验)
materialCode 字符串 是 物料编码(图号)
batchNo 字符串 条件必填 批次号(批次管理物料必填)
quantity 整数 条件必填 入库数量(批次管理物料必填)
snList 字符串数组 条件必填 序列号清单(序列号=是 的物料必填)
zoneCode 字符串 是 目标区域编号
shelfNo 字符串 是 货架号
layerNo 字符串 是 层号
positionNo 字符串 是 位置号
operator 字符串 是 操作人
productionDate 字符串 否 生产日期
supplier 字符串 否 供应商
remark 字符串 否 备注
inspectionNo 字符串 否 关联检验单号
ownershipType 字符串 是 归属类型:workorder 工单 / project 项目 / other 其他
ownershipNo 字符串 条件必填 归属编号(other 可不填,其余必填)
productWorkNo 字符串 否 产品工号(归属下手填二级编号)

请求示例

{
    "inboundType": "purchase",
    "materialCode": "M-1001",
    "batchNo": "B20261016",
    "quantity": 100,
    "zoneCode": "A",
    "shelfNo": "01",
    "layerNo": "2",
    "positionNo": "03",
    "operator": "张三",
    "supplier": "某某轴承有限公司",
    "ownershipType": "project",
    "ownershipNo": "PRJ-2026-018"
}

质量门禁:仅质量状态「合格」的库存行计入可用量、可出库 / 备料。来料检验流程见 2.1.8。

其他入库接口

方法 路径 用途
GET /api/inbound/query 入库单分页查询
GET /api/inbound/details 入库单明细分页(懒加载)
GET /api/inbound/export 导出入库单
POST /api/inbound/batch-excel Excel 批量入库
GET /api/inbound/last-location 该物料最近一次入库库位(选物料后自动回填)
POST /api/inbound/void 入库作废(填原因 + 回滚库存,权限 inbound:void)

2.1.5 出库与叫料

POST /api/outbound/general(JWT)

通用出库:扣减库存主表,覆盖退料 / 退货 / 样品 / 报废 / 发货等场景。

请求体字段

参数名 数据类型 是否必须 说明
materialCode 字符串 是 物料编码
batchNo 字符串 条件必填 批次号(批次管理物料)
snList 字符串数组 条件必填 序列号清单(序列号=是 的物料)
qty 整数 条件必填 出库数量(批次管理物料)
operator 字符串 是 操作人
zoneCode 字符串 是 出库区域编号
shelfNo 字符串 是 货架号
layerNo 字符串 是 层号
positionNo 字符串 是 位置号
boxNo 字符串 否 箱号
contractNo 字符串 否 合同号
remark 字符串 否 备注
outboundNo 字符串 否 出库单号,留空自动生成;填写必须唯一
outboundCategory 字符串 是 出库类别:return 退料 / supplier_return 退货退供应商 / sample 样品 / scrap 报废 / deliver 发货 / other 其他

请求示例

{
    "materialCode": "M-1001",
    "batchNo": "B20261016",
    "qty": 20,
    "operator": "李四",
    "zoneCode": "A",
    "shelfNo": "01",
    "layerNo": "2",
    "positionNo": "03",
    "outboundCategory": "deliver",
    "contractNo": "HT-2026-088"
}

出库库位联动:GET /api/outbound/location-hint 返回优先「批次在库库位」,其次该物料最近一次入库库位。

其他出库接口

方法 路径 用途
GET /api/outbound/query 出库单分页查询
GET /api/outbound/export 导出出库单
GET /api/outbound/stations 目标工位下拉选项(来自 MES 工位列表,不允许手输)

叫料队列(仓库端)

方法 路径 用途
GET /api/call/pending 待备料叫料单列表(权限 call:view)
POST /api/call/complete 完成备料:WMS 扣库存并通知 MES 派车(权限 call:manage)
POST /api/call/reject 驳回叫料单,必须填理由(权限 call:manage)

请求体:完成 {"requestNo":"叫料单号"};驳回 {"requestNo":"叫料单号","reason":"驳回理由"}。

2.1.6 AGV 配送(仓库端,透明代理 MES)

MES 是 AGV 任务与海康 RCS 客户端的唯一真源。WMS「AGV配送」页经服务间接口透明代理到 MES,接口形态与 MES 2.2.6 完全一致。

方法 路径 用途
POST /api/agv/submit 手动下发 AGV 配送任务(权限 agv:manage)
GET /api/agv/tasks AGV 任务列表
POST /api/agv/refresh 刷新任务状态(向 RCS 拉取最新)
POST /api/agv/cancel 取消 AGV 任务
GET /api/agv/docks 接驳台列表(读 MES)
GET /api/agv/materials 可配送物料列表
GET /api/agv/mode 当前调度模式

2.1.7 库存

方法 路径 用途
GET /api/stock/query 库存分页查询(物料 / 批次 / 序列号 / 库位 / 质量状态)
GET /api/stock/material-summary 按物料汇总(可用量 = 合格数量合计 − 锁定量)
GET /api/stock/details 库存明细分页(懒加载)
GET /api/stock/export 导出库存
GET /api/stock/zone-summary 按区域汇总
POST /api/stock/lock 库存锁定(备料联动机制)
POST /api/stock/unlock 库存解锁
POST /api/stock/check 库存校验(出库 / 备料前校验可用量)
GET /api/stock/shortage 缺货预警列表
GET /api/stock/material-demand 物料需求量(排产支撑)

2.1.8 来料检验

方法 路径 用途
POST /api/inspection/batch-flip 批次质量状态翻转
POST /api/inspection/dispose 不合格处置
POST /api/inspection/inventory-dispose 在库库存行直接发起不合格处置
POST /api/inspection/reinspect 复检(换修闭环)
GET /api/inspection/query 检验记录查询
GET /api/inspection/export 导出检验记录
GET /api/inspection/stats 检验统计
GET /api/inspection/pending 待检清单
GET /api/inspection/pending/details 待检清单明细分页

质量状态仅四值:合格 / 未检 / 不合格 / 待退。

2.1.9 区域货位

方法 路径 用途
GET /api/zone/list 区域树列表(区域 / 货架 / 层 / 位置号)(权限 zone:view)
POST /api/zone/node/create 新增区域节点(权限 zone:create)
POST /api/zone/node/update 编辑区域节点(权限 zone:edit)
POST /api/zone/batch-generate 批量生成货位(权限 zone:create)
GET /api/zone/picker 区域级联下拉
GET /api/zone/vacant 同区空位推荐

2.1.10 盘点

方法 路径 用途
POST /api/stocktake/start 发起盘点(权限 stocktake:start)
POST /api/stocktake/record 盘点扫码记录
POST /api/stocktake/finish 完成盘点
POST /api/stocktake/cancel 取消盘点
GET /api/stocktake/query 盘点记录查询(权限 stocktake:view)
GET /api/stocktake/active 当前进行中的盘点
GET /api/stocktake/export 导出盘点结果

盘点差异处理文案统一为「冻结 / 解冻」。

2.1.11 半成品 / 成品

方法 路径 用途
POST /api/semi/inbound 半成品入库(继承产线工单,凭工单号带出合同号)
POST /api/semi/outbound 半成品出库
GET /api/semi/query 半成品库存查询
GET /api/workorder/contract 凭工单号取合同号 / 工程编号(读 MES)
POST /api/finished/inbound 手工成品入库(权限 wms.finished:edit,须完工检合格)
GET /api/finished/inbound/today 今日成品入库记录

POST /api/semi/inbound 关键字段

参数名 数据类型 是否必须 说明
orderNo 字符串 是 产线工单号
materialCode 字符串 是 物料编码
sn 字符串 否 序列号(序列号=是 的物料)
completedText 字符串 否 已完成至工位(展示快照)
zoneCode 字符串 是 目标区域编号
productWorkNo 字符串 否 产品工号
operator 字符串 是 操作人
category 整数 否 2 半成品 / 3 成品(默认 2)
ownershipType 字符串 是 归属类型:workorder / project / other
ownershipNo 字符串 条件必填 归属编号
productStatus 字符串 否 成品用:已通过 / 部分通过 / 返修
relatedStandard 字符串 否 相关标准(试验方案号)
testRecordNo 字符串 否 试验记录单号
recordedBy 字符串 否 记录员
recordedAt 整数 否 记录日期(Unix 秒)

2.1.12 退库单 / 生产退不良

方法 路径 用途
POST /api/return-order/confirm 库管确认收货,库存加回
GET /api/return-order/query 退库单查询
GET /api/return-order/suggest-location 推荐退库库位
POST /api/production-return 生产退不良登记(权限 prodreturn:manage)
GET /api/production-return/query 生产退不良查询
GET /api/production-return/export 导出生产退不良

2.1.13 工单台账 / 附件 / 大屏

方法 路径 用途
GET /api/orders 工单物料台账
POST /api/attachments/upload 附件上传(流式 + MD5 秒传)
GET /api/attachments 业务附件列表
POST /api/attachments/delete 附件逻辑删除
GET /api/attachments/all 附件中心全量列表(权限 attachment:view)
GET /api/attachments/disk-status 磁盘状态
POST /api/attachments/archive 附件归档(权限 attachment:manage)
POST /api/attachments/purge-deleted 物理清理已删附件
POST /api/attachments/clean-logs 清理日志(仅管理员)
GET /uploads/:name 附件静态文件直链(免鉴权)
GET /api/display/overview 大屏总览数据(免鉴权)

2.2 MES 产线控制系统接口

基址 http://<服务器IP>:8888。JWT 业务接口前缀 /api/v1;服务间内部接口前缀 /api/internal(见 2.4.3)。

再次提醒:MES 业务失败返回 HTTP 200 + body.code≠0(见 1.6.1),调用方必须先解析 body.code。

2.2.1 登录认证

POST /api/v1/login(免鉴权)

请求体字段

参数名 数据类型 是否必须 说明
username 字符串 是 用户名
password 字符串 是 密码

响应 data 字段

字段名 类型 说明
accessToken 字符串 JWT 访问令牌
accessExpire 整数 有效期(秒,默认 3600)

2.2.2 用户与权限

方法 路径 用途
GET /api/v1/userinfo 当前登录用户
POST /api/v1/user/change-password 修改密码
POST /api/v1/logout 退出登录
GET / POST /api/v1/users 用户列表 / 新建用户
PUT / DELETE /api/v1/users、/api/v1/users/:id 编辑 / 删除用户
GET / POST /api/v1/roles 角色列表 / 新建角色
PUT / DELETE /api/v1/roles、/api/v1/roles/:id 编辑 / 删除角色
GET / POST / PUT / DELETE /api/v1/permissions(/:id) 权限维护

2.2.3 产品型号

方法 路径 用途
GET /api/v1/product-types 型号列表
GET /api/v1/product-types/page 型号分页
GET /api/v1/product-types/export 导出型号
POST /api/v1/product-types 新建型号
PUT /api/v1/product-types 编辑型号
POST /api/v1/product-types/status 启用 / 停用型号(body {id,isActive},同步 WMS)
DELETE /api/v1/product-types/:id 删除型号

2.2.4 工单与排产

工单(POST/PUT /api/v1/work-orders)

请求体关键字段

参数名 数据类型 是否必须 说明
workOrderNo 字符串 是 工单号
productTypeId 整数 是 产品型号 ID
productCode / productName 字符串 是 型号编码 / 名称
quantity 整数 是 计划数量
planStart / planEnd 字符串 否 计划开工 / 完工日期
dueDate 字符串 是 完成日期(yyyy-MM-dd,前端强制)
status 字符串 否 工单状态(新建恒为 CREATED,后续用状态接口推进)
ownershipType 字符串 是 归属类型:workorder 合同号 / project 科技项目号 / other 其他
contractNo 字符串 条件必填 归属编号(随 ownershipType 二选一填写)
productSerial 字符串 否 产品序号
flowCombination 对象数组 是 工艺组合(唯一路线源头):[{flowId,stationNo}],工位号即顺序号,按工位号升序执行、可跳过未选工位
productProcessId 整数 否 来源产品工艺 ID(0=无来源,历史工单)

其他工单接口

方法 路径 用途
GET /api/v1/work-orders 工单列表
POST /api/v1/work-orders/status 工单状态变更
GET /api/v1/work-orders/:id 工单详情
DELETE /api/v1/work-orders/:id 删除工单

自动排产

方法 路径 用途
POST /api/v1/work-orders/auto-schedule/preview 排产预览:逐日可调,Σ == 应排总数才能确认
POST /api/v1/work-orders/auto-schedule/apply 应用排产结果

入参:工单号、排产日期段(起止)、每段数量;预览返回逐日分配明细。

日计划

方法 路径 用途
POST / PUT /api/v1/daily-plans 保存日计划
GET /api/v1/daily-plans 日计划列表
GET /api/v1/daily-plans/unplanned 未排产工单
DELETE /api/v1/daily-plans/:id 删除日计划
POST /api/v1/daily-plans/:id/status 日计划启用 / 停用(body `{"status":"PENDING"
GET /api/v1/daily-plans/suggest-docks 推荐接驳台

接驳台主数据

方法 路径 用途
GET /api/v1/docks 接驳台列表
GET /api/v1/docks/maint 接驳台维护列表

排产支撑视图

方法 路径 用途
GET /api/v1/production/producible-support 可生产套数 / 支撑天数 / 最先告罄短板物料

2.2.5 叫料(管理视图)

方法 路径 用途
GET /api/v1/material-requests 叫料单列表(只读)

叫料的发起 / 签收 / 退库 / 取消在工位终端(见 2.3.6),完成 / 驳回 / 收回到仓库端(见 2.1.5);真源与处理逻辑均在 MES(服务间接口见 2.4.3)。

2.2.6 AGV 调度(MES 为唯一真源)

POST /api/v1/agv/submit(JWT)

手动下发 AGV 配送任务:按目标接驳台聚合生成任务,调用海康 RCS-Lite V1.5 下发。

请求体字段

参数名 数据类型 是否必须 说明
rows 对象数组 是 待发料行集合,至少 1 行
rows[].requestNo 字符串 是 叫料单号
rows[].materialCode 字符串 是 物料编码
rows[].materialName 字符串 是 物料名称
rows[].unit 字符串 是 单位
rows[].qty 数值 是 配送数量
rows[].targetDock 字符串 是 目标接驳台编号
sourceDock 字符串 否 来源接驳台,默认 DOCK21

请求示例

{
    "sourceDock": "DOCK21",
    "rows": [
        {"requestNo": "CL20261016-001", "materialCode": "M-1001", "materialName": "轴承座", "unit": "个", "qty": 20, "targetDock": "R1"}
    ]
}

其他 AGV 接口

方法 路径 用途
GET /api/v1/agv/tasks AGV 任务列表
POST /api/v1/agv/refresh 刷新任务状态
POST /api/v1/agv/cancel 取消任务(body {taskNo,reason})
GET /api/v1/agv/mode 当前调度模式

下发到海康 RCS 的报文格式以《AGV海康litev1.5.md》为准;RCS 回调接收见 2.4.5。

2.2.7 PLC 工艺下发与对账

方法 路径 用途
POST /api/v1/plc/send-process 下发整条工艺路线组合码给 PLC(串行:上一条未完成不下发下一条)
GET /api/v1/plc/send-logs 下发日志
POST /api/v1/plc/mismatch/check PLC↔MES 对账检查(单工位或全量 11 位)
POST /api/v1/plc/mismatch/override 管理员 override:关闭某工位对账告警(静默 30 分钟,权限 produce.plc.mismatch:override)

POST /api/v1/plc/send-process 请求体字段

参数名 数据类型 是否必须 说明
orderNo 字符串 是 工单号
sn 字符串 是 工件序列号
stationNo 整数 是 工位号(11 / 12 为下料检测位,走人工确认分支)

2.2.8 拧紧工艺

POST /api/v1/torque/report

拧紧结果上报,字段与工位终端 2.3.4 同构。

方法 路径 用途
GET /api/v1/torque/records 拧紧记录查询
POST /api/v1/torque/dispose 拧紧不合格人工处置放行(权限 produce.torque:dispose)

2.2.9 签字机制

方法 路径 用途
POST /api/v1/signs/inspector 检验员签字
GET /api/v1/signs/pending 待签字列表
POST /api/v1/signs/auditor 审核签字
GET /api/v1/signs/audit-pending 待审核列表

操作工报工签字随报工接口落库;检验员 / 审核签字为独立动作,双签闭环。

2.2.10 工件上下线与追溯

方法 路径 用途
POST /api/v1/workpiece/online 工件上线建档(body {sn,orderNo,operator})
POST /api/v1/workpiece/done 工件完工下线(body {sn,operator})
GET /api/v1/workpieces 工件列表
GET /api/v1/workpieces/in-process 在制品列表
GET /api/v1/trace SN 维度全链路追溯
GET /api/v1/process-steps 工艺步骤清单

成品无 SN 时由系统兜底随机生成,确保追溯完整。

2.2.11 半成品流向

方法 路径 用途
POST /api/v1/semi/flow 半成品流向记录
GET /api/v1/semi/flows 半成品流向列表

2.2.12 数量不符处理

方法 路径 用途
GET /api/v1/qty-reports 数量不符上报列表
GET /api/v1/qty-reports/stats 统计
POST /api/v1/qty-reports/handle 处理:补发 REFILL / 退库(生成退库单)/ 调整关闭

上报入口在工位终端 /api/qty-report(经服务间接口落 MES);MES 是唯一真源与处理侧。

上报字段(服务间接口同构):stationNo、orderNo、sn、materialCode、materialName、planQty、actualQty、cause、operator。

2.2.13 质量检验(过程检 / 完工检)

POST /api/v1/inspections

请求体关键字段

参数名 数据类型 是否必须 说明
category 字符串 是 检验类别:CHECKIN 签到 / POINT 点检 / PROCESS 过程检 / DONE 完工检 / ALARM 异常
stationNo 字符串 是 工位号
shift 字符串 否 班次:早 / 中 / 晚
orderNo 字符串 否 工单号
sn 字符串 否 工件 SN
result 字符串 是 结果:OK / NG
items 字符串数组 否 点检项 / 异常类型
photo 字符串 否 拍照文件名
remark 字符串 否 文字描述 / 签字
operator 字符串 是 操作人
processCode 整数 否 过程巡检:所属工位号
stepId / stepName 整数 / 字符串 否 过程巡检:工艺步骤 ID / 名称
measuredValue 字符串 否 实测值
reportNo 字符串 否 报检单号
materialCode / materialName 字符串 否 物料编码 / 名称
manufacturer 字符串 否 生产厂家
inspectionNo 字符串 否 检验单号
attachmentIds 字符串 否 附件 ID,逗号分隔
disposalType 字符串 否 处置类型:退货 / 返修 / 退换 / 报废
disposalRemark 字符串 否 处置说明
batchSn 字符串 否 判不合格联动 WMS 在库处置的定位字段(序列号=是 填 SN、序列号=否 填批次号)
returnTrackingNo 字符串 否 退货运单号(退货 / 退换处置必填)
relatedStandard 字符串 否 相关标准 / 试验方案号(完工检扩展)
testRecordNo 字符串 否 试验记录单号(完工检扩展)

其他检验接口

方法 路径 用途
GET /api/v1/inspections 检验列表
GET /api/v1/inspections/binds 检验绑定明细
POST /api/v1/inspections/upload 检验照片上传
POST /api/v1/inspections/generate-inter-process 一键生成《工序间检验记录》
GET /api/v1/quality/finished-pending 待完工检列表
POST /api/v1/quality/disposal 不合格处置
GET /api/v1/quality/unqualified-report 不合格报表

来料检验在 WMS(见 2.1.8),过程检 / 完工检在 MES;MES 判不合格可经服务间接口联动 WMS 在库处置(见 2.4.3)。

2.2.14 工艺流程 / 工位 / 产品工艺

方法 路径 用途
GET /api/v1/process-flows 工艺流程列表
POST /api/v1/process-flows 保存工艺流程
POST /api/v1/process-flows/status 流程状态
DELETE /api/v1/process-flows/:id 删除流程
POST /api/v1/process-flows/upload 上传流程 PDF
GET / POST /api/v1/process-flows/:id/materials 工艺物料清单查询 / 保存
GET /api/v1/stations 工位列表
POST /api/v1/stations 保存工位
POST /api/v1/stations/status 工位状态
DELETE /api/v1/stations/:id 删除工位
GET /api/v1/product-processes 产品工艺列表(有序工艺定义,不绑工位)
GET /api/v1/product-processes/derive 产品工艺推导(建单时推导工位)
GET /api/v1/product-processes/card 产品工艺卡
POST / PUT /api/v1/product-processes 保存产品工艺
POST /api/v1/product-processes/status 状态
DELETE /api/v1/product-processes/:id 删除
GET /api/v1/line/points 产线点位列表

2.2.15 预警中心

方法 路径 用途
POST / PUT / DELETE /api/v1/alert/rule 预警规则维护
GET /api/v1/alert/rules、/api/v1/alert-rules 规则列表(规范别名)
PUT /api/v1/alert-rules/:id 规则编辑(路径参数版)
GET /api/v1/alerts 预警列表
POST /api/v1/alerts/:id/resolve 处置预警(记录处置人 / 处置时间)
POST /api/v1/alert/read 标记已读
POST /api/v1/alert/emergency 应急呼叫

2.2.16 附件 / 文件

方法 路径 用途
POST /api/v1/attachment/upload 附件上传
GET /api/v1/attachments 附件列表
GET /api/v1/attachment/all 附件中心
GET /api/v1/attachment/file/:id 附件下载
GET /api/v1/attachment/disk-status 磁盘状态
POST /api/v1/attachment/archive 归档
POST /api/v1/attachment/delete 删除
GET /api/v1/files、/api/v1/files/:date/:name、/api/v1/files/:y/:m/:d/:t/:f 文件访问(免 JWT,图片直链)

2.2.17 生产流程卡 / 绩效 / 虚拟工位 / 系统设置

方法 路径 用途
GET /api/v1/process-card/workorder 工单维度生产流程卡
GET /api/v1/process-card/by-sn 成品 SN 追溯卡
GET /api/v1/process-card/by-model 型号筛选
GET /api/v1/process-card/list 流程卡列表
GET /api/v1/performance 工作量 / 绩效报表
GET /api/v1/performance/export 导出绩效报表
GET /api/v1/station/task 虚拟工位任务(管理后台,与终端同逻辑)
POST /api/v1/station/report 虚拟工位报工
GET /api/v1/workpiece/bind-panel 绑定面板
GET / PUT /api/v1/settings 系统基础设置读 / 写(保存即生效)
GET /api/v1/settings/wms-test WMS 连通性测试
GET /api/v1/event-logs 事件日志

2.3 工位终端接口

基址 http://<工位终端IP>:8892。除登录 / 配置 / 工艺文件直链外均需工位登录 JWT。

工位终端是 MES 的透明代理 + 离线队列:在线时请求转发 MES 内部接口;断网时入本地 SQLite 队列,恢复后由 syncer 按操作人身份补报。操作人取自工位登录态可信身份,防冒名上报。

2.3.1 登录 / 续签 / 退出

POST /api/auth/login(免鉴权)

请求体字段

参数名 数据类型 是否必须 说明
username 字符串 是 操作员工号(MES 用户)
password 字符串 是 工位终端密码
stationNo 整数 是 工位号(1~12)

响应 data 字段:token(JWT)、expireAt(Unix 秒)、user(用户信息)、stations(可登录工位号集合)、stationNo(本次登录工位号)。

其他认证接口

方法 路径 用途
POST /api/auth/touch 触屏心跳:刷本地空闲计时
POST /api/auth/refresh-token 滑动续签(节流 30 秒):换新 MES Bearer,作业中令牌不因固定有效期过期
POST /api/station/logout 退出(提示本人未上报数据条数)
GET /api/config 工位终端配置(免鉴权)
GET /api/health 健康检查(免鉴权)
GET /、GET /assets/:file 前端静态托管(免鉴权)

2.3.2 任务与作业

方法 路径 用途
GET /api/task/current 当前工位任务
GET /api/workload 工作量
GET /api/stations 工位列表
POST /api/station/pause 工位停单 / 恢复(只认当天,工人自主)
GET /api/station/state 工位状态
GET /api/bind/panel 装配绑定面板
POST /api/bind/record 绑定记录
POST /api/bind/remove 解除绑定
GET /api/wip 在制品
GET /api/bom 工单用料清单查询
GET /api/order/query 工单查询
GET /api/trace SN 维度全链路追溯

2.3.3 报工

POST /api/report/process-done

工序报工完成。

请求体字段

参数名 数据类型 是否必须 说明
sn 字符串 是 工件序列号
orderNo 字符串 是 工单号
flowId 整数 是 工艺流程 ID
stationNo 整数 是 工位号
steps 对象数组 是 工序数据集合
steps[].stepId 整数 是 步骤 ID
steps[].name 字符串 是 步骤名称
steps[].value 数值 否 采集值
steps[].text 字符串 否 文本值
steps[].checked 布尔 否 检测确认步骤的确认结果(服务端强校验)

请求示例

{
    "sn": "SN20261016-0001",
    "orderNo": "WO-2026-0108",
    "flowId": 3,
    "stationNo": 2,
    "steps": [
        {"stepId": 12, "name": "外观检查", "text": "无划伤", "checked": true},
        {"stepId": 13, "name": "压装压力", "value": 12.5}
    ]
}
方法 路径 用途
POST /api/report/temp-store 暂存报工数据

2.3.4 拧紧

POST /api/tightening/record

请求体字段

参数名 数据类型 是否必须 说明
sn 字符串 是 工件序列号
workOrderNo 字符串 是 工单号
stepId 字符串 是 步骤 ID
stepName 字符串 是 步骤名称
screwNo 字符串 是 螺丝点号
torque 数值 是 拧紧扭矩
angle 数值 是 拧紧角度
result 字符串 是 结果:OK / NG
operator 字符串 是 操作人

请求示例

{"sn": "SN20261016-0001", "workOrderNo": "WO-2026-0108", "stepId": "21", "stepName": "主轴拧紧", "screwNo": "3", "torque": 45.2, "angle": 90, "result": "OK", "operator": "王五"}
方法 路径 用途
GET /api/tightening/list 拧紧缓冲结果列表
GET /api/tightening/live 拧紧枪实时数据
POST /api/tightening/consume 确认消费缓冲结果(body {id})

2.3.5 工件上下线

方法 路径 用途
POST /api/workpiece/online 工件上线建档(body {sn,orderNo,operator})
POST /api/workpiece/done 工件完工(body {sn,operator})

2.3.6 叫料(代理 MES)

方法 路径 用途
GET /api/call/pool 叫料池(可叫物料 + 线边余量)
POST /api/call/create 发起叫料(materialCode / qty / dock)
GET /api/call/list 叫料单列表
POST /api/call/sign 到货签收
POST /api/call/cancel 取消叫料
POST /api/call/return 退库申请
GET /api/line/points 产线点位
POST /api/line/occupy 占用点位
GET /api/docks 接驳台列表

2.3.7 巡检 / 应急 / 数量不符 / 退料

方法 路径 用途
POST /api/inspection/submit 提交巡检 / 检验
POST /api/inspection/upload 检验照片上传
POST /api/emergency/call 应急呼叫
POST /api/qty-report 数量不符上报
POST /api/return-material 退料申请

2.3.8 离线同步

方法 路径 用途
POST /api/sync/flush 立即尝试补报离线队列
GET /api/sync/stats 队列积压统计

离线队列按操作人隔离:补报使用录入时快照的操作人身份,不用当前登录人,避免跨会话身份错乱。

2.3.9 工艺文件

方法 路径 用途
GET /api/pdf 工艺文件查询(本地预缓存自 MES)
GET /pdfopen/:name 工艺文件打开(免鉴权直链)
GET /pdfview 工艺文件预览(免鉴权,query 传名)

2.3.10 PLC 对账

方法 路径 用途
POST /api/plc/mismatch/check 事件驱动对账检查(MES 不可达静默跳过,不拦截作业)

2.4 系统对接接口

2.4.1 服务间调用总览

服务间接口统一请求头:X-API-TOKEN: <服务间令牌> + X-Username: <操作人>。令牌取值由部署配置项(Internal.Token)约定,本文档不明文给出,由双方运维交接时确认。

调用关系

方向 路径 说明
工位终端 → MES /api/internal/* 工位登录态 Bearer + X-API-TOKEN 双重校验
WMS → MES /api/internal/* 工位选项、工单合同号、物料需求、AGV 代理、完工回流
MES → WMS /api/internal/* 物料同步、库存校验 / 锁定、半成品 / 成品入库、退库单、在库处置
MES → 海康 RCS RCS-Lite V1.5 API AGV 任务下发 / 取消 / 查询(协议见《AGV海康litev1.5.md》)
海康 RCS → MES /api/spi/agv/agvCallbackService/agvCallback 任务状态回调(见 2.4.5)
大屏 → WMS / MES /api/display/overview、/api/internal/dashboard/* 免登录 / 服务间

2.4.2 WMS 内部接口(X-API-TOKEN)

方法 路径 用途
POST /api/internal/stock/check 库存校验
POST /api/internal/stock/lock 库存锁定
POST /api/internal/stock/unlock 库存解锁
GET /api/internal/stock/query 库存查询
GET /api/internal/stock/batches 可用批次 / 序列号查询
POST /api/internal/semi/inbound 半成品入库(MES 完工回流)
POST /api/internal/semi/outbound 半成品出库
POST /api/internal/finished/inbound 成品入库(MES 完工回流)
GET /api/internal/product-types/export 型号导出
POST /api/internal/materials/upsert 物料同步落点(按编码幂等 upsert,删除=停用)
POST /api/internal/material/exists 物料存在性校验
POST /api/internal/material/types 物料类型下拉
POST /api/internal/material/manage-modes 类型下拉
GET /api/internal/materials 物料分页查询
GET /api/internal/material/list-all 物料全量(冷启动拉取)
POST /api/internal/return-order 创建退库单
POST /api/internal/inventory/dispose 在库不合格处置(MES 判不合格联动)

2.4.3 MES 内部接口(X-API-TOKEN)

工位终端作业类

方法 路径 用途
POST /api/internal/station/login 工位登录
POST /api/internal/station/logout 工位退出
POST /api/internal/station/refresh-token 工位令牌续签
POST /api/internal/station/change-password 工位改密
GET /api/internal/station/task 当前任务
POST /api/internal/station/report 报工
POST /api/internal/station/checkin 签到
POST /api/internal/station/emergency 应急呼叫
POST /api/internal/station/qty-report 数量不符上报
POST /api/internal/station/return-material 退料申请
POST /api/internal/station/inspection 巡检提交
POST /api/internal/station/inspection-upload 巡检照片上传
GET /api/internal/station/workload 工作量
GET /api/internal/files 工艺文件下载
POST /api/internal/station/pause 停单 / 恢复
GET /api/internal/station/state 工位状态

工件 / 追溯 / 主数据类

方法 路径 用途
POST /api/internal/workpiece/report 工件报工
GET /api/internal/workpiece/trace SN 追溯
POST /api/internal/torque/report 拧紧上报
GET /api/internal/order/query 工单查询
GET /api/internal/work-orders/:no 工单归属解析(凭工单号取合同号)
POST / PUT /api/internal/materials 物料同步落点(按编码幂等 upsert)
GET /api/internal/dashboard/snapshot 大屏快照数据
GET /api/internal/dashboard/stream 大屏 SSE 实时推送(长连接)
GET /api/internal/workpieces/in-process 在制品
POST /api/internal/workpiece/online 工件上线
POST /api/internal/workpiece/done 工件完工
GET /api/internal/order-usage 工单用料
GET /api/internal/material-requests 叫料单列表
GET /api/internal/dock/pallet 接驳台托盘
GET /api/internal/docks 接驳台列表
GET /api/internal/workpiece/bind-panel 绑定面板
POST /api/internal/workpiece/binds 绑定记录
POST /api/internal/workpiece/binds/remove 解除绑定
POST /api/internal/dock/pallet/set 设置接驳台托盘
GET /api/internal/material-demand 排产物料需求
GET /api/internal/line/points 产线点位
POST /api/internal/line/occupy 占用点位
POST /api/internal/plc/mismatch/check PLC 对账检查

叫料类(工位端点带工位登录态;仓库端点由 WMS 以 X-API-TOKEN 调用)

方法 路径 用途
GET /api/internal/call/pool 叫料池
POST /api/internal/call/create 发起叫料
POST /api/internal/call/cancel 取消叫料
POST /api/internal/call/sign 到货签收
POST /api/internal/call/return 退库申请
POST /api/internal/call/complete 完成备料(WMS 调用,触发自动派车)
POST /api/internal/call/reject 驳回(WMS 调用)
POST /api/internal/call/return-confirm 确认收回
POST /api/internal/call/pool-adjust 叫料池调整

AGV 类

方法 路径 用途
POST /api/internal/agv/submit 下发 AGV
GET /api/internal/agv/tasks 任务列表
POST /api/internal/agv/refresh 刷新状态
POST /api/internal/agv/cancel 取消任务
GET /api/internal/agv/mode 调度模式
POST /api/internal/agv/dispatch 手动补派 / 重试

2.4.4 物料档案两库同步

WMS 与 MES 各持一份物料档案副本,按物料编码(code)幂等 upsert 互推:一端创建 / 修改即推送另一端;删除 = 停用(isActive=false)。推送失败置同步待重推标记,恢复后重推;冷启动全量拉取兜底。

方向 落点
MES → WMS POST /api/internal/materials/upsert(WMS)
WMS → MES POST / PUT /api/internal/materials(MES)
冷启动全量拉取 GET /api/internal/material/list-all(WMS)

同步报文关键字段

参数名 数据类型 是否必须 说明
code 字符串 是 物料编码(幂等键)
name 字符串 是 物料名称
spec 字符串 否 规格型号
unit 字符串 是 计量单位
description 字符串 否 说明
itemType 整数 否 物料类别:1 原材料 / 3 成品 / 4 其他
manageMode 整数 是 类型:1 结构件 / 2 电气件 / 3 其他
snMode 整数 是 序列号方式:0 未选 / 1 序列号=是 / 2 序列号=否(0 按类型联动默认:电气件→1,其余→2)
templateCode 字符串 否 模板编码
safetyStock 整数 否 安全库存
isActive 布尔 是 是否启用(false=停用,退出新建下拉)

同步示例

{"code": "M-1001", "name": "轴承座", "spec": "6205-2RS", "unit": "个", "manageMode": 1, "snMode": 2, "itemType": 1, "safetyStock": 50, "isActive": true}

2.4.5 海康 RCS-Lite V1.5 对接段

海康 RCS-Lite V1.5 的完整协议(任务下发 / 取消 / 查询、无签名鉴权、状态码与通用 code)以随附的《AGV海康litev1.5.md》为准,本文档不重复。本节只描述 bj_power 侧对接边界。

对接边界

  1. 调用方:MES 是唯一真源,持有 RCS 客户端;WMS「AGV配送」页经 MES 内部接口代理(见 2.4.3),不直接调用 RCS。
  2. 下发内容:按目标接驳台聚合的单段搬运任务(rows[] 见 2.2.6),由 MES 转换为 RCS-Lite V1.5 协议的任务下发接口报文(taskTyp=F01,全字符串参数,无签名鉴权)。
  3. 回调接收:RCS-Lite 主动回调 MES:

POST /api/spi/agv/agvCallbackService/agvCallback(免鉴权,生产环境须防火墙 / IP 白名单)

请求体字段

参数名 数据类型 是否必须 说明
taskCode 字符串 是 bj_power 任务单号(下发时透传为 RCS-Lite taskCode,全局唯一,用于回查任务)
method 字符串 是 事件方法:start 任务开始 / outbin 走出储位 / end 任务完成 / cancel 任务取消

请求示例

{"taskCode": "AGV-20261016-0001", "method": "end"}

响应:{"code":0,"message":"ok","data":null};处理失败返回业务错误码 3307。

状态映射(MES 内部态 ↔ RCS-Lite 数字态)

MES 内部态 含义 来源
PENDING 待派车 MES 创建任务后、下发前
FAILED 派车失败 MES 调用 RCS-Lite 下发接口失败
1 已创建 RCS-Lite 返回(任务已创建)
2 执行中 RCS-Lite 返回(start / outbin 回调触发)
5 已取消 RCS-Lite 返回(cancel 回调)或 MES 主动取消
9 已结束 RCS-Lite 返回(end 回调,到位)

MES 收到回调后按 method 驱动状态:start / outbin → 2,end → 9(置到位时间),cancel → 5;taskCode 用于定位任务,不再依赖 RCS 任务号。

该端点不携带我方鉴权头,必须在网络层隔离(防火墙 / IP 白名单),鉴权方式待与 RCS 方最终确认。

2.4.6 大屏数据接口

方法 路径 系统 鉴权 用途
GET /api/display/overview WMS 免鉴权 大屏总览
GET /api/internal/dashboard/snapshot MES X-API-TOKEN 大屏快照
GET /api/internal/dashboard/stream MES X-API-TOKEN 大屏 SSE 实时推送(长连接)

3 调用示例

3.1 登录获取令牌(WMS)

curl -X POST http://10.10.10.10:8890/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"******"}'

响应:

{
    "code": 0,
    "message": "ok",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expireAt": 1780000000,
        "user": {"id": 1, "username": "admin", "realName": "管理员"}
    }
}

3.2 携带令牌调用业务接口

curl -X GET "http://10.10.10.10:8890/api/stock/query?page=1&pageSize=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

3.3 MES 登录与 AGV 下发(注意 code 判读)

TOKEN=$(curl -s -X POST http://10.10.10.10:8888/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"******"}' | jq -r '.data.accessToken')

curl -s -X POST http://10.10.10.10:8888/api/v1/agv/submit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceDock":"DOCK21","rows":[{"requestNo":"CL20261016-001","materialCode":"M-1001","materialName":"轴承座","unit":"个","qty":20,"targetDock":"R1"}]}'

判读顺序:先解析 body.code,再判 HTTP 状态码。

3.4 物料档案同步(MES → WMS,服务间)

curl -X POST http://10.10.10.10:8890/api/internal/materials/upsert \
  -H "Content-Type: application/json" \
  -H "X-API-TOKEN: <服务间令牌>" \
  -H "X-Username: 张三" \
  -d '{"code":"M-1001","name":"轴承座","spec":"6205-2RS","unit":"个","manageMode":1,"snMode":2,"itemType":1,"safetyStock":50,"isActive":true}'

3.5 接收海康 RCS-Lite 回调

curl -X POST http://10.10.10.10:8888/api/spi/agv/agvCallbackService/agvCallback \
  -H "Content-Type: application/json" \
  -d '{"taskCode":"AGV-20261016-0001","method":"end"}'

3.6 工位终端报工

curl -X POST http://10.10.10.10:8892/api/report/process-done \
  -H "Authorization: Bearer <工位登录令牌>" \
  -H "Content-Type: application/json" \
  -d '{"sn":"SN20261016-0001","orderNo":"WO-2026-0108","flowId":3,"stationNo":2,"steps":[{"stepId":12,"name":"外观检查","text":"无划伤","checked":true}]}'

4 典型业务场景

4.1 物料档案两库同步

  1. WMS 新建物料 → 推送 MES POST /api/internal/materials(按编码幂等 upsert)。
  2. MES 新建物料 → 推送 WMS POST /api/internal/materials/upsert。
  3. 一端停用 → 推送停用,两端同步退出新建下拉。
  4. 推送失败 → 置同步待重推标记,恢复后重推;冷启动全量拉取兜底。

4.2 叫料 → 备料 → AGV 配送 → 工位签收

  1. 工位终端 POST /api/call/create 发起叫料(落 MES 叫料池)。
  2. MES 叫料单进入 WMS 待备料:GET /api/call/pending。
  3. WMS 库管 POST /api/call/complete:WMS 扣库存(仅合格品)→ 通知 MES。
  4. MES 自动派车:聚合 rows[] → POST /api/internal/agv/submit → 调海康 RCS 下发。
  5. RCS 执行中 / 完成 → 回调 MES POST /api/spi/agv/agvCallbackService/agvCallback(taskCode / method)。
  6. 工位终端看配送进度,到货 POST /api/call/sign 签收。
  7. 异常分支:WMS POST /api/call/reject 驳回(必填理由);工位 POST /api/call/return 退库申请 → WMS 确认收回。

4.3 工件上线 → 报工 → 拧紧 → 完工下线

  1. POST /api/workpiece/online 建档(sn + 工单;无 SN 由系统兜底生成)。
  2. 工位任务 GET /api/task/current;装配绑定 POST /api/bind/record。
  3. 拧紧枪实时数据 GET /api/tightening/live → POST /api/tightening/record。
  4. 工序报工 POST /api/report/process-done(steps + 检测确认)。
  5. POST /api/workpiece/done 完工;完工检合格 → MES 回流 WMS POST /api/internal/finished/inbound 入成品库。
  6. 全链路追溯 GET /api/v1/trace(SN 维度:装机绑定 + 检验记录 + 拧紧记录)。

4.4 PLC 工艺流程下发与对账

  1. 工单带工艺路线组合码 → POST /api/v1/plc/send-process 下发(串行:上一条未完成不下发下一条)。
  2. PLC 执行 → 事件驱动触发 /api/internal/plc/mismatch/check 对账(禁止定时轮询)。
  3. 不一致 → 落预警中心,终端弹两项对话框(新工件建档 / 绑定已知工件)。
  4. 管理员可 POST /api/v1/plc/mismatch/override 静默 30 分钟。

4.5 来料检验与不合格处置

  1. 入库质量状态「未检」→ GET /api/inspection/pending 待检清单。
  2. 检验合格 → POST /api/inspection/batch-flip 置「合格」,计入可用量。
  3. 不合格 → POST /api/inspection/dispose / inventory-dispose 处置;MES 过程检 / 完工检判不合格可经 /api/internal/inventory/dispose 联动 WMS 在库处置。
  4. 换修闭环 → POST /api/inspection/reinspect 复检。

5 更新说明

更新时间 更新人员 更新内容
2026-10-16 孙彦飞 1. 编制 V1.0:覆盖 WMS / MES / 工位终端全量接口与海康 RCS-Lite V1.5 对接段

说明:本 Markdown 为接口文档结构化编写,超长请求样例已做精简;实际开发请以服务端代码与联调环境为准。 核心关键点总结(开发提示)

  1. 三系统端口:WMS 8890 / MES 8888 / 工位终端 8892;接口前缀分别为 /api、/api/v1、/api。
  2. 鉴权三档:JWT(Bearer)/ X-API-TOKEN(服务间)/ 免鉴权(健康检查、登录、大屏、RCS 回调)。
  3. MES 业务失败返回 HTTP 200 + body.code≠0,与 WMS / 工位终端不同,必须先判 code。
  4. 物料档案两库双向同步,按物料编码幂等 upsert,删除=停用。
  5. AGV 调度唯一真源在 MES:WMS 经服务间接口代理,RCS 回调落 MES /api/spi/agv/agvCallbackService/agvCallback(网络层隔离)。
  6. 海康 RCS-Lite V1.5 完整协议见随附《AGV海康litev1.5.md》,本文档 2.4.5 仅述对接边界。