450 lines
16 KiB
Markdown
450 lines
16 KiB
Markdown
# 入库单推送全流程测试指南
|
||
|
||
## 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×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 创建收货单
|
||
|
||
```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 失败 | 同步失败 |
|