PDA 来料检 — 接口说明

模块：ErpInStockController（提交）、MesErpInStockInspectController（查检验记录）
权限：mes:erpInStock:view（登录 MES 即可，不要直连金蝶 ERP）
服务地址示例：http://127.0.0.1:8980

本次变更说明（来料检记录）

下文凡标注 【新增】 的字段/接口，均为「固定检查项 + OK/NG 留痕」改造新增；未标注的为原有能力。

类型	内容	说明
【新增】必填参数	`submitInStock.checkResult`	`OK` / `NG`；不传会失败
【新增】可选参数	`inspectorName` / `inspectorCode` / `inspectTime` / `remarks` / `channel`	检验员、时间、备注、渠道
【新增】返回字段	`data.inspectId` / `checkResult` / `inStockCreated`	提交后带回检验记录信息
【新增】业务规则	仅 `OK` 生成采购入库单；`NG` 只保存检验记录	原流程等价于默认一直 OK 入库
【新增】初始化字段	`inspectInit` 返回检验员/时间/结果选项	便于 PDA 预填
【新增】接口	`mesErpInStockInspect/pda/listData`	查询来料检记录列表
【新增】PC 菜单	生产管理 → ERP来料检记录	需执行 `db/mysql/add_mes_erp_in_stock_inspect.sql`

PDA 适配要点：

提交时必须传 checkResult=OK 或 NG
OK 时仍须传仓库（及仓位，若 required）
NG 时可不传仓库，接口仍返回 result=true，但 inStockCreated=0
用 data.inStockCreated 判断是否生成了 CGRK 入库单

页面流程

① pda/listData（可选）  采购入库历史
        ↓ 新增
② pda/selectOrderData    采购订单列表
        ↓ 点选 billNo
③ pda/selectDetailData   待入分录，勾选 entryId
        ↓ billNo + entryIds
④ inspectInit            来料检页（仓库/数量/批号 + 【新增】固定检查项）
   └ pda/stockLocOptions  选仓库后查仓位（required=true 必选）
   └ pda/lotSearch        搜批号（可选）
        ↓
⑤ submitInStock          提交来料检【新增 checkResult】
   ├ checkResult=OK → 保存检验记录 + 生成采购入库单（CGRK）
   └ checkResult=NG → 仅保存检验记录，不生成入库单
        ↓（可选）
⑥ mesErpInStockInspect/pda/listData  【新增】查来料检记录

PDA 统一返回 CommonResp（result / message / data）；列表类接口 data 为分页结构。提交接口支持 表单 POST 与 JSON Body 两种方式。

固定检查项（【新增】）： 检验员、检验时间、OK/NG、数量、批号、备注。其中 checkResult 必填。

1. 采购订单列表

请求URL： /js/a/mes/erpInStock/pda/selectOrderData

请求方式： POST

参数：

参数名	必选	类型	说明
pageNo	否	int	页码，默认 1
pageSize	否	int	每页条数，默认 20
billNo	否	string	采购订单号（可扫码/模糊查询）
materialNumberQuery	否	string	物料编码模糊
documentStatusQuery	否	string	单据状态：A创建 B审核中 C已审核 D重新审核；建议默认 C

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/pda/selectOrderData?pageNo=1&pageSize=20&documentStatusQuery=C'

带订单号搜索：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/pda/selectOrderData?pageNo=1&pageSize=20&documentStatusQuery=C&billNo=CGDD110260602003'

返回示例：

成功：

{
  "result": "true",
  "message": "成功",
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "count": 1,
    "list": [
      {
        "billNo": "CGDD110260602003",
        "date": "2026-06-02",
        "documentStatus": "C",
        "documentStatusName": "已审核",
        "supplierNumber": "VEN001",
        "supplierName": "某某供应商",
        "purchaseOrgName": "安徽裕洋",
        "entryCount": 3,
        "totalQty": 1500
      }
    ]
  }
}

页面显示： billNo、date、supplierName、documentStatusName、entryCount

下一步： 用户点击某行 → 进入接口 2，传入 billNo

2. 待入分录列表（勾选明细）

请求URL： /js/a/mes/erpInStock/pda/selectDetailData

请求方式： POST

参数：

参数名	必选	类型	说明
billNo	是	string	采购订单号

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/pda/selectDetailData?billNo=CGDD110260602003'

返回示例：

成功（有剩余可入分录）：

{
  "result": "true",
  "message": "成功",
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "count": 2,
    "list": [
    {
      "entryId": "123456",
      "seq": "1",
      "materialNumber": "3.01.001",
      "materialName": "某原材料",
      "unitName": "千克",
      "qty": 1000,
      "instockQty": 200,
      "remainQty": 800,
      "deliveryDate": "2026-06-15"
    }
  ]
  }
}

成功（已全部入库，list 为空）：

{
  "result": "true",
  "message": "成功",
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "count": 0,
    "list": []
  }
}

页面显示： seq、materialNumber、materialName、qty（订单量）、instockQty（已入）、remainQty（剩余可入）、unitName

下一步： 勾选 1~N 行 → 收集 entryId，逗号拼接 → 进入接口 3

3. 来料检页初始化

请求URL： /js/a/mes/erpInStock/inspectInit

请求方式： GET 或 POST（PDA 常用 POST + form 表单参数）

参数：

参数名	必选	类型	说明
billNo	是	string	采购订单号
entryIds	是	string / array	分录内码；多条逗号分隔，或 JSON 数组；仅一条时也传此字段

参数示例：

# 多条
curl --location --request GET 'http://127.0.0.1:8980/js/a/mes/erpInStock/inspectInit?billNo=CGDD110260602003&entryIds=123456,123457'
# 单条
curl --location --request GET 'http://127.0.0.1:8980/js/a/mes/erpInStock/inspectInit?billNo=CGDD110260602003&entryIds=123456'

返回示例：

成功：

{
  "result": "true",
  "message": "",
  "data": {
    "billNo": "CGDD110260602003",
    "defaultStockNumber": "1100105",
    "inspectorCode": "zhangsan",
    "inspectorName": "张三",
    "inspectTime": "2026-09-11 13:30:00",
    "checkResultOptions": ["OK", "NG"],
    "stockList": [
      {
        "stockNumber": "1100105",
        "stockName": "五金库",
        "displayLabel": "1100105 五金库"
      }
    ],
    "stockLoc": {
      "required": true,
      "defaultLocNumber": "A11",
      "locKey": "F100002",
      "locHint": "共 278 个仓位，数据来自 ERP 仓位值集",
      "locations": [
        { "locNumber": "A11", "locName": "A11区", "locKey": "F100002", "displayLabel": "A11 A11区" }
      ]
    },
    "lines": [
      {
        "entryId": "123456",
        "seq": "1",
        "materialNumber": "3.01.001",
        "materialName": "某原材料",
        "unitName": "千克",
        "remainQty": 800,
        "batchManage": true,
        "suggestedLotNumber": "LOT202606001",
        "lotHint": "共 3 条批号档案，已推荐第一条",
        "availableLots": [
          { "lotNumber": "LOT202606001", "qtyText": "0" }
        ]
      }
    ]
  }
}

返回字段说明（inspectInit data）：

字段	类型	说明	变更
billNo	string	采购订单号	原有
defaultStockNumber	string	默认仓库	原有
stockList	array	仓库列表	原有
stockLoc	object	默认仓库仓位	原有
lines	array	待检分录	原有
inspectorCode	string	默认检验员账号	【新增】
inspectorName	string	默认检验员姓名	【新增】
inspectTime	string	默认检验时间 `yyyy-MM-dd HH:mm:ss`	【新增】
checkResultOptions	array	结果选项，固定 `["OK","NG"]`	【新增】

失败（分录已无剩余）：

{
  "result": "false",
  "message": "所选分录已无剩余可入数量",
  "billNo": "CGDD110260602003",
  "lines": [],
  "stockList": [],
  "defaultStockNumber": "1100105"
}

页面显示：

顶部：data.billNo
【新增】 固定检查项：检验员默认 inspectorName，时间默认 inspectTime，结果选 OK/NG
仓库下拉：data.stockList，默认 data.defaultStockNumber（选 OK 时必填）
仓位：data.stockLoc（默认仓库）；required=true 时必选仓位，切换仓库后调接口 4
每行：seq、materialNumber、materialName、remainQty
数量输入框：默认值 = remainQty，可改小，不能超过 remainQty
批号：batchManage=true 时必填，默认 suggestedLotNumber，可点搜批号（接口 6）或手工输入

下一步： 用户选 OK/NG →（OK 时选仓库/仓位）→ 填数量/批号/备注 → 调接口 8 提交

4. 仓位选项（选仓库后调用）

请求URL： /js/a/mes/erpInStock/pda/stockLocOptions

请求方式： POST（也兼容 GET）

参数：

参数名	必选	类型	说明
stockNumber	是	string	仓库编码（来自 inspectInit 的 stockList）

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/pda/stockLocOptions?stockNumber=1100105'

返回示例：

成功（需选仓位）：

{
  "result": "true",
  "message": "成功",
  "data": {
    "required": true,
    "defaultLocNumber": "A",
    "locKey": "F100004",
    "locHint": "共 12 个仓位，数据来自 ERP 仓位值集",
    "locations": [
      {
        "locNumber": "A",
        "locName": "A区",
        "displayLabel": "A A区"
      }
    ]
  }
}

成功（不需选仓位）：

{
  "result": "true",
  "message": "成功",
  "data": {
    "required": false,
    "defaultLocNumber": "",
    "locHint": "该仓库未启用仓位或未配置仓位值集",
    "locations": []
  }
}

页面显示： 仓位下拉/选择列表；required=true 时仓位为必填

下一步： 选完仓位 → 继续填写数量/批号 → 接口 7 提交

5. 仓库列表（可选，inspectInit 已含可不调）

请求URL： /js/a/mes/erpInStock/stockList

请求方式： POST（也兼容 GET）

参数：

参数名	必选	类型	说明
无	—	—	—

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/stockList'

返回示例：

成功：

{
  "result": "true",
  "message": "成功",
  "data": {
    "defaultStockNumber": "1100105",
    "stockHint": "共 5 个可用仓库",
    "stockList": [
      {
        "stockNumber": "1100105",
        "stockName": "五金库",
        "displayLabel": "1100105 五金库"
      }
    ]
  }
}

6. 批号搜索（可选）

请求URL： /js/a/mes/erpInStock/pda/lotSearch

请求方式： POST（也兼容 GET）

参数：

参数名	必选	类型	说明
materialNumber	是	string	物料编码
lotKeyword	否	string	批号关键字（模糊）

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/pda/lotSearch?materialNumber=3.01.001&lotKeyword=LOT'

返回示例：

成功：

{
  "result": "true",
  "message": "成功",
  "data": {
    "lots": [
      {
        "lotNumber": "LOT202606001",
        "qtyText": "0"
      }
    ],
    "lotHint": "共查到 1 条批号档案"
  }
}

无结果（可手工录入新批号）：

{
  "result": "true",
  "message": "成功",
  "data": {
    "lots": [],
    "lotHint": "未查到符合条件的 ERP 批号档案，可手工录入新批号"
  }
}

7. 批号列表（可选，inspectInit 已含 availableLots 可不调）

请求URL： /js/a/mes/erpInStock/pda/lotOptions

请求方式： POST（也兼容 GET）

参数：

参数名	必选	类型	说明
materialNumber	是	string	物料编码

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/pda/lotOptions?materialNumber=3.01.001'

返回示例：

成功：

{
  "result": "true",
  "message": "成功",
  "data": {
    "lots": [
      {
        "lotNumber": "LOT202606001",
        "qtyText": "0"
      }
    ],
    "suggestedLotNumber": "LOT202606001",
    "lotHint": "共 3 条批号档案，已推荐第一条"
  }
}

8. 提交来料检（【新增】OK/NG + 检验记录）

破坏性变更： 旧版可不传检验结果、直接入库；现版 必须传 checkResult，否则返回失败。

请求URL： /js/a/mes/erpInStock/submitInStock

请求方式： POST

Content-Type（二选一）：

方式	Content-Type	说明
PDA 推荐	`application/x-www-form-urlencoded`	表单参数，`lines` 传 JSON 数组字符串
调试/脚本	`application/json;charset=UTF-8`	整包 JSON Body

参数：

参数名	必选	类型	说明	变更
billNo	是	string	采购订单号	原有
checkResult	是	string	检验结果：`OK` / `NG`（也可用 1/0、合格/不合格）	【新增】必填
inspectorName	否	string	检验员姓名，默认当前登录用户	【新增】
inspectorCode	否	string	检验员账号，默认当前登录用户	【新增】
inspectTime	否	string	检验时间，默认当前时间；格式 `yyyy-MM-dd HH:mm:ss`	【新增】
remarks	否	string	备注	【新增】
channel	否	string	`PC` / `PDA`，建议 PDA 传 `PDA`	【新增】
stockNumber	条件	string	入库仓库编码；checkResult=OK 时必填；NG 可不传	原有（规则收紧）
stockLocNumber	条件	string	入库仓位；`stockLoc.required=true` 且 OK 时必填	原有
stockLocKey	条件	string	仓位维度键，与 `locations[].locKey` 一致	原有
entryIds	条件	string / array	分录内码；与 lines 二选一或组合	原有
lines	条件	array / string	明细 JSON 数组；表单方式时为 URL 编码后的 JSON 字符串	原有
lines[].entryId	条件	string	可与顶层 entryIds 按顺序对应	原有
lines[].inspectQty	条件	number	检验数量，缺省取 remainQty	原有
lines[].lotNumber	条件	string	批号管理物料必填	原有
lines[].materialName	否	string	物料名称（展示用）	原有

参数示例：

PDA 表单（OK 入库）【新增 checkResult 等】：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/submitInStock' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'billNo=CGDD110260602003' \
--data-urlencode 'checkResult=OK' \
--data-urlencode 'inspectorName=张三' \
--data-urlencode 'remarks=外观正常' \
--data-urlencode 'channel=PDA' \
--data-urlencode 'stockNumber=1100101' \
--data-urlencode 'stockLocNumber=A11' \
--data-urlencode 'lines=[{"entryId":"194383","inspectQty":1.0,"lotNumber":"11020260603"},{"entryId":"194384","inspectQty":1.0,"lotNumber":"20250101"}]'

JSON Body（NG 仅留痕）【新增】：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/submitInStock' \
--header 'Content-Type: application/json;charset=UTF-8' \
--data '{
  "billNo": "CGDD110260602003",
  "checkResult": "NG",
  "inspectorName": "张三",
  "remarks": "尺寸超差",
  "channel": "PDA",
  "entryIds": "123456",
  "lines": [{"entryId":"123456","inspectQty":1.0,"lotNumber":"11020260603"}]
}'

返回示例：

OK 成功入库：

{
  "result": "true",
  "message": "来料检合格，采购入库单保存成功，单号：CGRK110260624001",
  "data": {
    "inspectId": "xxx",
    "checkResult": "OK",
    "inStockCreated": "1",
    "inStockBillNo": "CGRK110260624001"
  }
}

NG 仅保存检验记录：

{
  "result": "true",
  "message": "来料检不合格，已保存检验记录，未生成采购入库单",
  "data": {
    "inspectId": "xxx",
    "checkResult": "NG",
    "inStockCreated": "0",
    "inStockBillNo": ""
  }
}

失败（参数缺失示例）【新增】：

{
  "result": "false",
  "message": "请选择来料检结果（OK/NG）"
}

失败（仓位等，会记入 ERP 下推日志；若已写入检验记录会带 inspectId）：

{
  "result": "false",
  "message": "仓位维度【五金库货架仓位】不能为空",
  "data": {
    "inspectId": "xxx",
    "checkResult": "OK",
    "inStockCreated": "0"
  }
}

返回 data 字段：

字段	类型	说明	变更
inspectId	string	MES 来料检记录 id	【新增】
checkResult	string	`OK` / `NG`	【新增】
inStockCreated	string	`1` 已生成入库单 / `0` 未生成	【新增】
inStockBillNo	string	采购入库单号 CGRK…；未生成时为空	原有（仍保留）

页面显示： 成功弹 message；用 data.inStockCreated 判断是否生成了入库单。

查记录： PC 菜单「ERP来料检记录」；PDA 用接口 10。

下一步： 完成；可返回订单列表、查检验记录（接口 10）或查入库历史（接口 9）

9. 采购入库历史（可选）

PDA 请用 pda/listData（CommonResp）；PC 后台仍用 listData（直接返回 Page）。

请求URL： /js/a/mes/erpInStock/pda/listData

请求方式： POST

参数：

参数名	必选	类型	说明
pageNo	否	int	页码
pageSize	否	int	每页条数
poOrderNoQuery	否	string	按采购订单号查
billNoQuery	否	string	按入库单号 CGRK 查
materialNumberQuery	否	string	物料编码模糊
documentStatusQuery	否	string	C=已审核

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/pda/listData?pageNo=1&pageSize=20&poOrderNoQuery=CGDD110260602003'

返回示例：

成功：

{
  "result": "true",
  "message": "成功",
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "count": 1,
    "list": [
      {
        "billNo": "CGRK110260624001",
        "date": "2026-06-24",
        "documentStatusName": "已审核",
        "poOrderNo": "CGDD110260602003",
        "supplierName": "某某供应商",
        "materialNumber": "3.01.001",
        "materialName": "某原材料",
        "realQty": 800,
        "unitName": "千克",
        "lotNumber": "LOT202606001",
        "stockName": "五金库"
      }
    ]
  }
}

失败：

{
  "result": "false",
  "message": "查询失败原因",
  "data": null
}

10. 来料检记录列表（【新增】整节）

查询 MES 本地保存的来料检记录（含 OK/NG、检验员、时间、备注、是否已生成入库单）。
与接口 9「采购入库历史」不同：接口 9 查的是金蝶已生成的 CGRK；本接口查的是 MES 检验留痕（NG 也能查到）。

请求URL： /js/a/mes/mesErpInStockInspect/pda/listData

请求方式： POST

权限： mes:erpInStock:view（与来料检相同，便于 PDA 复用）

参数：

参数名	必选	类型	说明	变更
pageNo	否	int	页码，默认 1	【新增】接口
pageSize	否	int	每页条数	【新增】接口
poBillNo	否	string	采购订单号（模糊）	【新增】接口
checkResult	否	string	`OK` / `NG`	【新增】接口
inStockBillNo	否	string	采购入库单号（模糊）	【新增】接口
inspectorName	否	string	检验员（模糊）	【新增】接口
inspectTime_gte	否	datetime	检验时间起	【新增】接口
inspectTime_lte	否	datetime	检验时间止	【新增】接口

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/mesErpInStockInspect/pda/listData?pageNo=1&pageSize=20&checkResult=NG&poBillNo=CGDD110260602003'

返回示例：

{
  "result": "true",
  "message": "成功",
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "count": 1,
    "list": [
      {
        "id": "xxx",
        "poBillNo": "CGDD110260602003",
        "checkResult": "NG",
        "checkResultLabel": "不合格",
        "inspectorName": "张三",
        "inspectTime": "2026-09-11 13:35:00",
        "remarks": "尺寸超差",
        "lineCount": 1,
        "totalQty": 1.0,
        "inStockStatus": "NONE",
        "inStockStatusLabel": "未入库",
        "inStockBillNo": "",
        "inStockMessage": "来料检不合格，未生成采购入库单",
        "channel": "PDA"
      }
    ]
  }
}

list[] 主要字段：

字段	说明	变更
id	检验记录 id（= submit 返回的 inspectId）	【新增】
poBillNo	采购订单号	【新增】
checkResult	OK / NG	【新增】
inspectorName / inspectTime / remarks	检验员、时间、备注	【新增】
lineCount / totalQty	行数、合计数量	【新增】
inStockStatus	`NONE` 未入库 / `SUCCESS` 已入库 / `FAIL` 入库失败	【新增】
inStockBillNo	生成的 CGRK 单号	【新增】
channel	PC / PDA	【新增】

PC 详情页： /js/a/mes/mesErpInStockInspect/detail?id=xxx（含明细行：物料、数量、批号）

11. 查看入库单明细（可选）

请求URL： /js/a/mes/erpInStock/pda/detailData

请求方式： POST

参数：

参数名	必选	类型	说明
billNo	是	string	采购入库单号 CGRK

参数示例：

curl --location --request POST 'http://127.0.0.1:8980/js/a/mes/erpInStock/pda/detailData?billNo=CGRK110260624001'

返回示例：

成功：

{
  "result": "true",
  "message": "成功",
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "count": 2,
    "list": [
      {
        "seq": "1",
        "materialNumber": "3.01.001",
        "materialName": "某原材料",
        "realQty": 400,
        "unitName": "千克",
        "lotNumber": "LOT202606001",
        "stockName": "五金库"
      }
    ]
  }
}

附录：单据状态对照

代码	含义
A	创建
B	审核中
C	已审核
D	重新审核

附录：常见失败 message

message	原因
请选择来料检结果（OK/NG）	【新增】未传或非法 `checkResult`
所选分录已无剩余可入数量	PO 行已入满，返回重新选单
检验数量不能超过剩余可入数量	inspectQty 大于 remainQty
启用批号管理，请从 ERP 选择或手工录入批号	batchManage=true 但未传 lotNumber
请选择入库仓库	checkResult=OK 但未传 stockNumber
所选仓库需要选择仓位	五金库等需仓位但未传 stockLocNumber

PDA来料检接口说明.md 23 KB Historique Raw

PDA 来料检 — 接口说明

本次变更说明（来料检记录）

页面流程

1. 采购订单列表

2. 待入分录列表（勾选明细）

3. 来料检页初始化

4. 仓位选项（选仓库后调用）

5. 仓库列表（可选，inspectInit 已含可不调）

6. 批号搜索（可选）

7. 批号列表（可选，inspectInit 已含 availableLots 可不调）

8. 提交来料检（【新增】OK/NG + 检验记录）

9. 采购入库历史（可选）

10. 来料检记录列表（【新增】整节）

11. 查看入库单明细（可选）

附录：单据状态对照

附录：常见失败 message

PDA来料检接口说明.md 23 KB

Historique Raw