# 入库单推送全流程测试指南 ## 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。 ```powershell # 确认端口 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. 服务器重启 修改代码后需完全重启: ```powershell taskkill /F /IM node.exe npm run dev ``` 端口被占用排查: ```powershell netstat -ano | findstr :6060 ``` ### 3f. /system 接口需要 headers ```http platform: web project: wms Authorization: Bearer ``` 测试账号:`liufumingren` / `111111` 获取 token: ```powershell 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 ```powershell $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 创建入库单(奇门推送) ```xml 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 TEST-ENTRY-001 WH001 JYCK SKU001 100 ``` ### 4.3 创建收货单 ```powershell $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 添加收货明细 ```powershell $detailBody = @{ 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 完成收货 + 审核 ```powershell # 完成收货 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`":`"`"}" # 审核收货单 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`":`"`"}" ``` ### 4.6 绑定入库单 + 审核 ```powershell # 绑定收货单 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`":`"`",`"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`":`"`"}" ``` ### 4.7 PDA上架 + 提交 ```powershell # 添加直入记录(绑定模式) $addItemBody = @{ entry_id="" receiving_detail_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`":`"`"}" ``` ### 4.8 虚拟直入(跳过收货单) ```powershell $quickBody = @{ entry_id="" items=@( @{ item_code="SKU001" quantity=50 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 端口被占用 ```powershell # 查找占用进程 netstat -ano | findstr :6060 # 强制结束 taskkill /F /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 失败 | 同步失败 |