WMS_MAIN/skills/entry-order-test-guide.md
liufumingren 5ef99e3bed 1
2026-07-01 14:00:59 +08:00

16 KiB
Raw Blame History

入库单推送全流程测试指南

1. 全流程概述

奇门推送 entryorder.create → 创建入库单(CREATED)
  → bindReceiving(绑定收货单)
  → reviewEntry(CREATED→PENDING)
  → addItem(PDA上架,传 receiving_detail_id + space_id)
  → commit(提交入库+奇门同步→COMPLETED)

或 quickInbound(虚拟直入,跳过收货单,CREATED→COMPLETED)

流程说明

阶段 method 状态变化 说明
奇门创建 qimen.entryorder.create (无)→CREATED 奇门 XML 推送,创建入库单及明细
绑定收货单 storage.entry.bindReceiving CREATED→CREATED 将入库单与收货单关联
审核 storage.entry.reviewEntry CREATED→PENDING 审核通过,允许上架,必须已绑定收货单
PDA上架 storage.directInbound.addItem PENDING→PENDING PDA扫码上架,传 receiving_detail_id + space_id
提交入库 storage.directInbound.commit PENDING→COMPLETED 先奇门同步,再写库存
虚拟直入 storage.entry.quickInbound CREATED→COMPLETED 跳过收货单,一键完成入库

2. 关键接口列表

步骤 method 说明 入口
创建 qimen.entryorder.create 奇门推送 XML 创建入库单 /qimen
绑定 storage.entry.bindReceiving 绑定收货单到入库单 /system
审核 storage.entry.reviewEntry CREATED→PENDING,需已绑定 /system
上架 storage.directInbound.addItem PDA添加,可选绑定收货明细 /system
提交 storage.directInbound.commit 同步奇门+写库存→COMPLETED /system
虚拟 storage.entry.quickInbound 一键虚拟入库 /system
对照 storage.entry.receivingCompare 入库单 vs 收货单明细对照 /system
查询 storage.directInbound.getItems 查询直入记录 /system
日志 storage.entry.queryEntryLogs 查询入库单操作日志 /system

3. 踩坑点

3a. 端口

配置文件(config/config.local.js)中端口是 6060,不是 Egg.js 默认的 7001。

# 确认端口
Select-String -Path "config/config.local.js" -Pattern "port"

3b. app_key 双重角色

  • 签名用:config.qimen.appKey(如 23535631),用于奇门请求的 MD5 签名计算
  • validateApi 查询匹配用:请求参数中的 app_key(如 23060081),用于匹配 wms_api_app 表记录
  • 两个值不同,签名的 app_key 不参与 wms_api_app 绑定查询

3c. 奇门签名

  • 签名算法:secret + sortedParams + xmlBody + secret → MD5 → 大写
  • 签名不验证入站请求:qimen 入口无 verifyTopRequest 校验
  • 使用已有合约配置:从 wms_api_app 表读取,不要无中生有创建新配置

3d. itemId 必传

  • itemId 为空时,按 item_code + app_key + warehouse_id + store_id 查询 StockStore
  • app_key 不匹配会导致找不到商品
  • 建议一律传 itemId 以避免匹配问题

3e. 服务器重启

修改代码后需完全重启:

taskkill /F /IM node.exe
npm run dev

端口被占用排查:

netstat -ano | findstr :6060

3f. /system 接口需要 headers

platform: web
project: wms
Authorization: Bearer <JWT_TOKEN>

测试账号:liufumingren / 111111

获取 token:

curl -X POST http://localhost:6060/system?method=user.login `
  -H "platform: web" `
  -H "project: wms" `
  -H "Content-Type: application/json" `
  -d '{"username":"liufumingren","password":"111111"}'

3g. 先同步后写库

quickInbound 和 commit 的执行顺序已改为:

  1. 先调用 qimenEntrySync 同步到奇门/ERP
  2. 同步成功后才写库存
  3. 同步失败不写库存,只标记为 FAILED

3h. 绑定模式

addItem 传 receiving_detail_id 时进入绑定模式:

  • 忽略 quantity 字段,实际数量从 ReceivingDetail.actual_quantity 取值
  • 必须传 space_id(库位ID)
  • 允许超过入库单 planQty,不受计划数量限制

4. 快速测试脚本示例

4.1 准备工作:获取 Token

$loginBody = @{username="liufumingren";password="111111"} | ConvertTo-Json
$loginResp = curl -s -X POST "http://localhost:6060/system?method=user.login" `
  -H "platform: web" -H "project: wms" `
  -H "Content-Type: application/json" `
  -d $loginBody
$token = ($loginResp | ConvertFrom-Json).data.token
Write-Host "Token: $token"

4.2 创建入库单(奇门推送)

POST /qimen?method=entryorder.create&app_key=23060081&customerId=4&v=1.0&format=xml&sign_method=md5&timestamp=2026-06-27+10:00:00&sign=XXX

<request>
  <entryOrder>
    <entryOrderCode>TEST-ENTRY-001</entryOrderCode>
    <warehouseCode>WH001</warehouseCode>
    <orderType>JYCK</orderType>
  </entryOrder>
  <orderLines>
    <orderLine>
      <itemCode>SKU001</itemCode>
      <planQty>100</planQty>
    </orderLine>
  </orderLines>
</request>

4.3 创建收货单

$rcvBody = @{
  delivery_method="truck"
  loading_method="without_pallet"
  store_id=1000000
} | ConvertTo-Json

curl -s -X POST "http://localhost:6060/system?method=storage.receiving.create" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d $rcvBody

4.4 添加收货明细

$detailBody = @{
  receiving_id="<RECEIVING_ID>"
  item=@{
    product_name="测试商品"
    actual_quantity=86
  }
} | ConvertTo-Json

curl -s -X POST "http://localhost:6060/system?method=storage.receiving.addDetail" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d $detailBody

4.5 完成收货 + 审核

# 完成收货
curl -s -X POST "http://localhost:6060/system?method=storage.receiving.completeReceiving" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d "{`"receiving_id`":`"<RECEIVING_ID>`"}"

# 审核收货单
curl -s -X POST "http://localhost:6060/system?method=storage.receiving.reviewReceiving" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d "{`"receiving_id`":`"<RECEIVING_ID>`"}"

4.6 绑定入库单 + 审核

# 绑定收货单
curl -s -X POST "http://localhost:6060/system?method=storage.entry.bindReceiving" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d "{`"entry_id`":`"<ENTRY_ID>`",`"receiving_id`":`"<RECEIVING_ID>`"}"

# 审核入库单
curl -s -X POST "http://localhost:6060/system?method=storage.entry.reviewEntry" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d "{`"entry_id`":`"<ENTRY_ID>`"}"

4.7 PDA上架 + 提交

# 添加直入记录(绑定模式)
$addItemBody = @{
  entry_id="<ENTRY_ID>"
  receiving_detail_id="<RECEIVING_DETAIL_ID>"
  space_id="<SPACE_ID>"
  item_code="SKU001"
} | ConvertTo-Json

curl -s -X POST "http://localhost:6060/system?method=storage.directInbound.addItem" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d $addItemBody

# 提交入库
curl -s -X POST "http://localhost:6060/system?method=storage.directInbound.commit" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d "{`"entry_id`":`"<ENTRY_ID>`"}"

4.8 虚拟直入(跳过收货单)

$quickBody = @{
  entry_id="<ENTRY_ID>"
  items=@(
    @{
      item_code="SKU001"
      quantity=50
      space_id="<SPACE_ID>"
    }
  )
} | ConvertTo-Json

curl -s -X POST "http://localhost:6060/system?method=storage.entry.quickInbound" `
  -H "platform: web" -H "project: wms" `
  -H "Authorization: Bearer $token" `
  -H "Content-Type: application/json" `
  -d $quickBody

5. 数据库关键表

表 用途 关键字段
wms_entry_order 入库单主表 id, entry_order_code, order_status, sync_status
wms_entry_items 入库单明细 id, entry_id, item_id, item_code, plan_quantity, actual_quantity
wms_receiving 收货单主表 id, receiving_code, status, store_id
wms_receiving_detail 收货单明细 id, receiving_id, product_name, actual_quantity
wms_entry_order_receiving 入库单↔收货单主表绑定 id, entry_id, receiving_id
wms_entry_receiving_binding 入库明细↔收货明细绑定 id, entry_item_id, receiving_detail_id, quantity
wms_inbound_direct_log PDA直入记录 id, entry_id, item_code, quantity, space_id, receiving_detail_id
wms_api_app 奇门应用绑定配置 id, app_key, app_secret, warehouse_id, store_id
wms_operation_log 操作日志 id, target_type, target_id, action, operator, created_at

6. 状态机速查

状态 含义 可执行操作
CREATED 已创建,待绑定/审核 bindReceiving, reviewEntry, quickInbound, cancel
PENDING 已审核,待上架 addItem, commit, cancel
COMPLETED 已完成 不可操作
CANCELLED 已取消 不可操作
FAILED 同步失败 重试或取消

7. 常见问题排查

7.1 找不到入库单

  • 检查奇门 XML 中 warehouseCode 是否匹配 wms_api_app 中的 warehouse_id
  • 检查 app_key 是否已在 wms_api_app 表中配置

7.2 reviewEntry 报错"未绑定收货单"

  • CREATED 状态且未调用 bindReceiving 时,审核会被拒绝
  • 先调用 bindReceiving 绑定收货单

7.3 addItem 报错"缺少 space_id"

  • 绑定模式下(传了 receiving_detail_id)必须同时传 space_id
  • space_id 对应库位表主键

7.4 commit 后库存未变化

  • 检查 qimenEntrySync 是否返回成功
  • 同步失败时标记为 FAILED 状态,库存不会写入
  • 查看 wms_operation_log 中的错误信息

7.5 端口被占用

# 查找占用进程
netstat -ano | findstr :6060
# 强制结束
taskkill /F /PID <PID>

8. 变更历史

日期 版本 变更内容
2026-06-27 v1.0 初始版本,覆盖入库单全流程测试指南

8. 问题清单与修复基准(来自 issues.txt)

问题 1:缺失收货单直接转入库单的快捷入口

  • 现状:收货单创建后,必须先手动创建入库单(走奇门或 OpenAPI),再通过 bindReceiving 绑定
  • 修复后应支持:storage.receiving.createEntryOrder(receiving_id) → 自动创建入库单并绑定主表关系

问题 2:addItem 状态机校验不完整

  • 2a:CREATED + 已绑定收货单 → 应拒绝(当前只强制要求传 receiving_detail_id)
  • 2b:PENDING + 已绑定 + 无明细ID → 应拒绝(当前未区分 CREATED/PENDING)
  • 2c:PENDING + 无绑定 → 应拒绝(PENDING 只能走 PDA 上架,必须已绑定收货单)
  • 2d:CREATED 人工导入 → 应允许超过 planQty(当前非绑定模式不允许超量)

修复后校验矩阵:

状态 有绑定 携带明细ID 应允许 超 planQty
CREATED 否 否 ✅ 人工后台导入 ✅ 允许
CREATED 是 - ❌ 拒绝 -
PENDING 否 - ❌ 拒绝 -
PENDING 是 否 ❌ 拒绝 -
PENDING 是 是 ✅ PDA上架 ✅ 允许

问题 3:状态机定义

CREATING → CREATED → PENDING → COMPLETED ↑ ↓ ↑ └── 重试推送 ────────┘ │ CANCELLED ←────────┘

  • CREATED:等待人工绑定和审核,可走人工后台导入(不限制 planQty),可走虚拟直入
  • PENDING:已审核,待上架/上架中,必须已绑定收货单,必须携带 receiving_detail_id
  • COMPLETED:已完成,不可操作

问题 4:entryorderConfirm 增量回传应移除

  • 统一走 qimenEntrySync 全量同步,actualQty = item.count
  • 移除 entry_order.js 的 entryorderConfirm 方法

问题 5:completeEntry 应作废

  • commit 已包含所有实质性工作(写库存、同步奇门、推进 COMPLETED)
  • completeEntry 无独立存在意义

问题 6:入库单取消

  • 6a:取消时调用 qimenEntrySync,orderLines 全部 actualQty=0,通知 ERP 关闭
  • 6b:sync_status=SUCCESS 的入库单不允许取消(已通知 ERP 入库完成)
  • 允许取消的状态:sync_status != 'SUCCESS' 且 order_status NOT IN ('COMPLETED','CANCELLED')

9. 完整测试场景

场景 A:奇门创建 + 收货单 + PDA上架(完整链路)

`

  1. qimen.entryorder.create → CREATED
  2. storage.receiving.create → 收货单
  3. storage.receiving.addDetail → 收货明细
  4. storage.receiving.completeReceiving → 完成收货
  5. storage.receiving.reviewReceiving → 审核收货单
  6. storage.entry.bindReceiving → 绑定入库单↔收货单
  7. storage.entry.receivingCompare → 对照预览
  8. storage.entry.reviewEntry → CREATED→PENDING
  9. storage.directInbound.addItem(receiving_detail_id) → PDA上架+明细绑定
  10. storage.directInbound.commit → 奇门同步+写库存→COMPLETED `

场景 B:人工后台导入(无收货单)

`

  1. qimen.entryorder.create → CREATED
  2. storage.directInbound.addItem(无 receiving_detail_id) → 人工导入
  3. storage.directInbound.commit → 奇门同步+写库存→COMPLETED `

场景 C:虚拟直入

`

  1. qimen.entryorder.create → CREATED
  2. storage.entry.quickInbound → 奇门同步+写库存→COMPLETED(一步完成) `

场景 D:取消入库单

`

  1. 入库单 CREATED/PENDING 且 sync_status != SUCCESS
  2. storage.entry.cancel → ①发送 qimenEntrySync(all actualQty=0) → ②更新 order_status=CANCELLED `

10. 数据库校验检查点

修复完成后,以下 SQL 可用于验证各场景正确性:

\\sql -- 验证入库单状态 SELECT id, entry_order_code, order_status, sync_status, sync_message FROM wms_entry_order WHERE id = ?;

-- 验证入库明细收货量 SELECT id, item_code, count, received_quantity, confirm_quantity FROM wms_entry_items WHERE order_id = ?;

-- 验证主表绑定 SELECT * FROM wms_entry_order_receiving WHERE entry_order_id = ?;

-- 验证明细绑定 SELECT id, entry_item_id, receiving_detail_id, allocated_quantity, status FROM wms_entry_receiving_binding WHERE entry_item_id IN (SELECT id FROM wms_entry_items WHERE order_id = ?);

-- 验证直入记录 SELECT id, stock_id, quantity, space_id FROM wms_inbound_direct_log WHERE entry_order_id = ?;

-- 验证库存写入 SELECT id, stock_id, batch_no, quantity, receiving_id, production_date, expiry_date FROM wms_storage WHERE entry_order_id = ?;

-- 验证操作日志 SELECT id, business_type, business_id, operation_code, message FROM wms_operation_log WHERE business_id = ? AND business_type = 'entry_order' ORDER BY created_at DESC; \\

11. 已知操作码清单

operationCode 触发接口 说明
ENTRY_ORDER_CREATE qimen/OpenAPI entryorder.create 入库单创建
ENTRY_ORDER_REVIEW storage.entry.reviewEntry 审核通过 CREATED→PENDING
DIRECT_INBOUND_ADD storage.directInbound.addItem 直入记录添加
DIRECT_INBOUND_COMMIT storage.directInbound.commit 提交入库 COMPLETED
DIRECT_INBOUND_REMOVE storage.directInbound.removeItem 移除直入记录
QUICK_INBOUND storage.entry.quickInbound 虚拟直入完成
QUICK_INBOUND_FAILED quickInbound/commit 失败 同步失败