# 北京哈德曼产线控制系统接口协议 >文档类别:产线控制系统(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 `;HS256 签名,默认有效期 1 小时;支持滑动续签(见 1.5) | | ② X-API-TOKEN | 服务间内部接口 `/api/internal/*` | 项目内部服务(工位终端、看板、WMS↔MES)互调专用;令牌取值由部署配置项约定,由双方运维交接时确认,本文档不明文给出 | | ③ 免鉴权 | 健康检查、登录、大屏展示、工艺文件直链、海康 RCS 回调 | 见各接口单独标注;海康回调端点生产环境必须以防火墙 / IP 白名单隔离 | >注意:MES 的工位终端接口在 X-API-TOKEN 之上再叠加工位登录 Bearer(双重校验);工位号与操作人由服务端从登录态可信注入,不接受客户端伪造,防止冒名上报。 ## 1.3 请求首部字段 | 字段名 | 数据类型 | 是否必需 | 说明 | |---|---|---|---| | Authorization | 字符串 | 否(JWT 接口必需) | 固定格式:`Bearer ` | | 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 ` | | 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 仅述对接边界。