WMS_MAIN/skills/entry-order-test-guide.md
liufumingren 478ad2ab0d 1
2026-07-03 16:10:46 +08:00

450 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 入库单推送全流程测试指南
## 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 <JWT_TOKEN>
```
测试账号:`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&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 创建收货单
```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="<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`":`"<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 绑定入库单 + 审核
```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`":`"<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上架 + 提交
```powershell
# 添加直入记录(绑定模式)
$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 虚拟直入(跳过收货单)
```powershell
$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` | [已弃用] 入库明细↔收货明细绑定(已迁至 InboundDirectLog) | id, entry_item_id, receiving_detail_id, quantity |
| `wms_inbound_direct_log` | PDA直入记录 + 入库明细↔收货明细绑定 | id, entry_id, entry_item_id, item_code, quantity, space_id, receiving_detail_id, status, updated_at, deleted_at |
| `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 <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 失败 | 同步失败 |