Files
bj_power/产线API.md
T
SunYF 46fcb59079 feat: 退料闭环定稿(损耗台账/备料清单/退料AGV自动派车/剩余量参考)+ 工位托盘守卫
- MES 新增损耗台账 loss_ledger,差异确认损耗接口 ConfirmReceiveLoss(按工单归集)
- 备料清单 preparation:MES 按 日计划×工单×工位×物料 实时计算,WMS 只读展示 PreparationList
- 退料闭环:N5 工位托盘守卫(未完成禁止退料)、退料 AGV 自动派车(JBT21 空位判定 + 托盘回收链路)、退料参考剩余量接口(应剩余=实备-已耗-已退-已损)
- 新增 AGV 车辆状态表 agv_vehicle_state 及查询
- 整合接驳台/叫料池/库存锁既有闭环,清理 sql 目录注释生成脚本与 catalog,更新文档
2026-11-04 19:06:03 +08:00

1354 lines
56 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 北京哈德曼产线控制系统接口协议
>文档类别:产线控制系统(WMS 仓储管理 / MES 产线控制 / 工位终端)
>文档编号:BJP-API-V1.0
## 目录
1. [协议概述](#1-协议概述)
- 1.1 系统组成与服务端口
- 1.2 鉴权方式
- 1.3 请求首部字段
- 1.4 请求报文消息体
- 1.5 响应首部字段
- 1.6 响应报文消息体(统一响应体)
- 1.7 响应状态码
- 1.8 业务错误码
- 1.9 通用约定(时间、分页、导出)
2. [业务接口说明](#2-业务接口说明)
- 2.1 WMS 仓储管理系统接口
- 2.2 MES 产线控制系统接口
- 2.3 工位终端接口
- 2.4 系统对接接口
3. [调用示例](#3-调用示例)
4. [典型业务场景](#4-典型业务场景)
5. [更新说明](#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` |
**正常响应报文样例**
```json
{
"code": 0,
"message": "ok",
"data": {"id": 1}
}
```
**业务异常响应报文样例**
```json
{
"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 |
**请求示例**
```json
{"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 | 字符串 | 否 | 产品工号(归属下手填二级编号) |
**请求示例**
```json
{
"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` 其他 |
**请求示例**
```json
{
"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 | 字符串 | 否 | 计划开工 / 完工日期 |
| 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"|"CONFIRMED"}`) |
| 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 | 字符串 | 否 | 来源接驳台,默认 JBT21 |
**请求示例**
```json
{
"sourceDock": "JBT21",
"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 | 布尔 | 否 | 检测确认步骤的确认结果(服务端强校验) |
**请求示例**
```json
{
"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 | 字符串 | 是 | 操作人 |
**请求示例**
```json
{"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=停用,退出新建下拉) |
**同步示例**
```json
{"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` 任务取消 |
**请求示例**
```json
{"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)
```bash
curl -X POST http://10.10.10.10:8890/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"******"}'
```
响应:
```json
{
"code": 0,
"message": "ok",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expireAt": 1780000000,
"user": {"id": 1, "username": "admin", "realName": "管理员"}
}
}
```
## 3.2 携带令牌调用业务接口
```bash
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 判读)
```bash
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":"JBT21","rows":[{"requestNo":"CL20261016-001","materialCode":"M-1001","materialName":"轴承座","unit":"个","qty":20,"targetDock":"R1"}]}'
```
>判读顺序:先解析 body.code,再判 HTTP 状态码。
## 3.4 物料档案同步(MES → WMS,服务间)
```bash
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 回调
```bash
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 工位终端报工
```bash
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 仅述对接边界。