16 KiB
入库单推送全流程测试指南
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查询StockStoreapp_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 的执行顺序已改为:
- 先调用
qimenEntrySync同步到奇门/ERP - 同步成功后才写库存
- 同步失败不写库存,只标记为
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×tamp=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上架(完整链路)
`
- qimen.entryorder.create → CREATED
- storage.receiving.create → 收货单
- storage.receiving.addDetail → 收货明细
- storage.receiving.completeReceiving → 完成收货
- storage.receiving.reviewReceiving → 审核收货单
- storage.entry.bindReceiving → 绑定入库单↔收货单
- storage.entry.receivingCompare → 对照预览
- storage.entry.reviewEntry → CREATED→PENDING
- storage.directInbound.addItem(receiving_detail_id) → PDA上架+明细绑定
- storage.directInbound.commit → 奇门同步+写库存→COMPLETED `
场景 B:人工后台导入(无收货单)
`
- qimen.entryorder.create → CREATED
- storage.directInbound.addItem(无 receiving_detail_id) → 人工导入
- storage.directInbound.commit → 奇门同步+写库存→COMPLETED `
场景 C:虚拟直入
`
- qimen.entryorder.create → CREATED
- storage.entry.quickInbound → 奇门同步+写库存→COMPLETED(一步完成) `
场景 D:取消入库单
`
- 入库单 CREATED/PENDING 且 sync_status != SUCCESS
- 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 失败 | 同步失败 |