新增 ErrorListDialog 组件用于统一展示结构化校验错误信息,实现报错一次收全;新增工位报警语音播报功能,通过浏览器 SpeechSynthesis 播放本工位相关报警;调整物料类别及序列号字段文案,移除「其他」类别;新增工单实际开始字段及采集方式配置;优化 AGV 及 PlcSend 页签刷新逻辑;新增看板物料追溯及工位报警接口;删除 PLC 强制写 M 位及相关测试代码;同步数据库字段注释及补丁。
57 KiB
北京哈德曼产线控制系统接口协议
文档类别:产线控制系统(WMS 仓储管理 / MES 产线控制 / 工位终端) 文档编号:BJP-API-V1.0
目录
- 协议概述
- 1.1 系统组成与服务端口
- 1.2 鉴权方式
- 1.3 请求首部字段
- 1.4 请求报文消息体
- 1.5 响应首部字段
- 1.6 响应报文消息体(统一响应体)
- 1.7 响应状态码
- 1.8 业务错误码
- 1.9 通用约定(时间、分页、导出)
- 业务接口说明
- 2.1 WMS 仓储管理系统接口
- 2.2 MES 产线控制系统接口
- 2.3 工位终端接口
- 2.4 系统对接接口
- 调用示例
- 典型业务场景
- 更新说明
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 侧对接边界。
对接边界
- 调用方:MES 是唯一真源,持有 RCS 客户端;WMS「AGV配送」页经 MES 内部接口代理(见 2.4.3),不直接调用 RCS。
- 下发内容:按目标接驳台聚合的单段搬运任务(rows[] 见 2.2.6),由 MES 转换为 RCS-Lite V1.5 协议的任务下发接口报文(taskTyp=F01,全字符串参数,无签名鉴权)。
- 回调接收: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 物料档案两库同步
- WMS 新建物料 → 推送 MES
POST /api/internal/materials(按编码幂等 upsert)。 - MES 新建物料 → 推送 WMS
POST /api/internal/materials/upsert。 - 一端停用 → 推送停用,两端同步退出新建下拉。
- 推送失败 → 置同步待重推标记,恢复后重推;冷启动全量拉取兜底。
4.2 叫料 → 备料 → AGV 配送 → 工位签收
- 工位终端
POST /api/call/create发起叫料(落 MES 叫料池)。 - MES 叫料单进入 WMS 待备料:
GET /api/call/pending。 - WMS 库管
POST /api/call/complete:WMS 扣库存(仅合格品)→ 通知 MES。 - MES 自动派车:聚合 rows[] →
POST /api/internal/agv/submit→ 调海康 RCS 下发。 - RCS 执行中 / 完成 → 回调 MES
POST /api/spi/agv/agvCallbackService/agvCallback(taskCode / method)。 - 工位终端看配送进度,到货
POST /api/call/sign签收。 - 异常分支:WMS
POST /api/call/reject驳回(必填理由);工位POST /api/call/return退库申请 → WMS 确认收回。
4.3 工件上线 → 报工 → 拧紧 → 完工下线
POST /api/workpiece/online建档(sn + 工单;无 SN 由系统兜底生成)。- 工位任务
GET /api/task/current;装配绑定POST /api/bind/record。 - 拧紧枪实时数据
GET /api/tightening/live→POST /api/tightening/record。 - 工序报工
POST /api/report/process-done(steps + 检测确认)。 POST /api/workpiece/done完工;完工检合格 → MES 回流 WMSPOST /api/internal/finished/inbound入成品库。- 全链路追溯
GET /api/v1/trace(SN 维度:装机绑定 + 检验记录 + 拧紧记录)。
4.4 PLC 工艺流程下发与对账
- 工单带工艺路线组合码 →
POST /api/v1/plc/send-process下发(串行:上一条未完成不下发下一条)。 - PLC 执行 → 事件驱动触发
/api/internal/plc/mismatch/check对账(禁止定时轮询)。 - 不一致 → 落预警中心,终端弹两项对话框(新工件建档 / 绑定已知工件)。
- 管理员可
POST /api/v1/plc/mismatch/override静默 30 分钟。
4.5 来料检验与不合格处置
- 入库质量状态「未检」→
GET /api/inspection/pending待检清单。 - 检验合格 →
POST /api/inspection/batch-flip置「合格」,计入可用量。 - 不合格 →
POST /api/inspection/dispose/inventory-dispose处置;MES 过程检 / 完工检判不合格可经/api/internal/inventory/dispose联动 WMS 在库处置。 - 换修闭环 →
POST /api/inspection/reinspect复检。
5 更新说明
| 更新时间 | 更新人员 | 更新内容 |
|---|---|---|
| 2026-10-16 | 孙彦飞 | 1. 编制 V1.0:覆盖 WMS / MES / 工位终端全量接口与海康 RCS-Lite V1.5 对接段 |
说明:本 Markdown 为接口文档结构化编写,超长请求样例已做精简;实际开发请以服务端代码与联调环境为准。 核心关键点总结(开发提示)
- 三系统端口:WMS 8890 / MES 8888 / 工位终端 8892;接口前缀分别为 /api、/api/v1、/api。
- 鉴权三档:JWT(Bearer)/ X-API-TOKEN(服务间)/ 免鉴权(健康检查、登录、大屏、RCS 回调)。
- MES 业务失败返回 HTTP 200 + body.code≠0,与 WMS / 工位终端不同,必须先判 code。
- 物料档案两库双向同步,按物料编码幂等 upsert,删除=停用。
- AGV 调度唯一真源在 MES:WMS 经服务间接口代理,RCS 回调落 MES /api/spi/agv/agvCallbackService/agvCallback(网络层隔离)。
- 海康 RCS-Lite V1.5 完整协议见随附《AGV海康litev1.5.md》,本文档 2.4.5 仅述对接边界。