WMS_MAIN/methods/changes/syncOrderIds-async-review-feedback-20260704.md
liufumingren 2817d17fc7 1
2026-07-06 00:33:12 +08:00

155 lines
7.1 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.

# syncOrderIds 异步化改造 — 风险评估修正反馈
**日期**:2026-07-04
**评审来源**:`wms-review-agent` 风险评估报告(11 项风险点)
**修正执行**:`wms-db-agent`
**改造分支**:`ming`(尚未提交)
---
## 评审结论总览
| 风险点总数 | 确认为真风险 | 已修复 | 可接受妥协 | 不成立 |
|-----------|-------------|--------|-----------|--------|
| 11 + 1(深度排查) | 5 | 4 | 5 | 2 |
---
## 一、已修复项
### 🔴 P0 — #2 操作日志双重写入
**问题**:`order_storage_allocation.syncOrderIds` 中存在旧的 `ORDER_SYNC` 操作日志写入代码(约 50 行),`pendingOrder.syncOrderIds` 层又有新增的日志写入,导致每条订单产生 **2 条** `ORDER_SYNC` 日志。
**修法**:删除 `order_storage_allocation.js` 中旧的操作日志写入块,替换为一行注释 `// 操作日志已移至 pendingOrder.syncOrderIds 层统一写入,避免重复`。
**影响文件**:`app/service/systems/order_storage_allocation.js`(-50 行)
---
### 🟡 P1 — #3 Promise.all 无容错
**问题**:`Promise.all` 并行派发各渠道分组(QM / MANUAL / API),若任一渠道 handler 抛异常(如 `syncQmOrders` reject),按 `Promise.all` 语义会中断所有渠道。
**实际风险评估**:经核实,下游 handler(`syncQmOrders` / `syncManualOrders` / `syncApiOrders`)内部均使用 `Promise.all` + `processXxxOrderInternal` 模式,**所有方法返回 `{ status: 'failed' }` 而非 throw**,因此实际抛异常的概率极低。但作为防御性编程,仍加 `try/catch` 兜底。
**修法**:每个 `map(async groupedOrder => { ... })` 回调包裹 `try/catch`:
- `catch` 中记录 `ctx.logger.error`(含 createChannel / warehouseId / orderCount)
- 返回标准化 `{ status: 'failed', message, ... }` 结构
- 仍调用 `reportProgress(groupOrderCount)` 确保进度不丢失
**影响文件**:`app/service/systems/order_storage_allocation.js`(+20 行)
---
### 🔴 P0(深度排查)— catch 分支缺操作日志
**来源**:`wms-review-agent` 二次深度排查,对比 `allocateStorage` 发现遗漏。
**问题**:`syncOrderIds` 的 `setImmediate` catch 块中只写了缓存进度 + error log,**没有写操作日志**。而 `allocateStorage` 的 catch 块写了 `ORDER_STORAGE_ALLOCATE_FAILED`。如果服务崩溃、DB 断连等,`syncOrderIds` 的操作日志表里完全没有记录。
**修法**:在 `setImmediate` catch 块中新增操作日志写入,参考 `allocateStorage` 使用 `this.ctx.model.OperationLog.bulkCreate` 直写(崩溃场景下 service 层可能也不可用):
- 操作码:`ORDER_SYNC_FAILED`
- 内容:`订单同步失败:{errorMsg}`
- 双层 `try/catch`:外层写入缓存进度,内层写入操作日志
**影响文件**:`app/service/systemMethods/order/pendingOrder.js`(+35 行)
**测试覆盖**:新增 `should write ORDER_SYNC_FAILED operation log when entire sync task throws`
---
### 📋 P2 — #10 测试覆盖不足
**问题**:原报告指出"syncOrderIds 本身的异步流程没有对应测试用例"。
**实际核实**:`pendingOrder.syncOrderIds.test.js` 已存在(11 个测试),但确实缺少 2 个场景。
**修法**:新增 2 个测试用例:
- **渠道级异常隔离**:模拟 MANUAL 成功 + QM 失败,验证 `dispatch_results` 正确反映两渠道状态
- **多状态混合**:模拟 success / skipped / fast-failed 四类结果共存,验证 `result.data` 各字段正确
**最终覆盖**:14 个测试用例,覆盖以下场景:
| 场景 | 测试用例 |
|------|---------|
| 基础异步:立即返回 request_id | ✅ |
| 进度查询:success 后查到完整 result | ✅ |
| 进度查询:not_found | ✅ |
| 进度查询:request_id 为空 | ✅ |
| 中间态:submitted → running | ✅ |
| 单订单失败:整批仍 success | ✅ |
| 整体失败:报告 failed 状态 | ✅ |
| **catch 分支操作日志:ORDER_SYNC_FAILED** | ✅ 新增 |
| 进度递增:running → success | ✅ |
| 入参兼容:orderIds/ids/order_id | ✅ |
| 缓存故障:写入失败不崩溃 | ✅ |
| 进度回调异常:不崩溃 | ✅ |
| 渠道隔离:单渠道失败不阻塞 | ✅ |
| 多状态混合:四种结果共存 | ✅ |
---
## 二、不成立的风险点
### #6 — `warehouse_id` 优先级变更无校验
**核实**:`warehouse_id` 由 `pendingOrder.syncOrderIds` 在 `setImmediate` 之前通过 `this.getWarehouseId()` 快照提取,与原来 `ctx.user.store_id` **完全同源**。不存在调用方误传的通道。
**结论**:❌ 不成立,无风险。
---
### #7 — `sync_status` 过滤遗漏 `error` 状态
**核实**:model 定义 `sync_status` 枚举为 `['padding', 'fin', 'error']`。当前过滤条件为 `NOT IN ('fin', 'padding')`。
- `fin`(已完成):排除 ✅ — 无需重复同步
- `padding`(处理中):排除 ✅ — 防止并发重复提交
- `error`(失败):**不应排除** ✅ — 用户应能修复问题后重试
如果排除 `error`,会导致同步失败的订单**永远无法重试**,这反而是 bug。
**结论**:❌ 不成立,当前过滤条件是正确的业务设计。
---
## 三、可接受的妥协项
| # | 风险点 | 妥协理由 |
|---|--------|---------|
| 1 | Breaking API 变更 | 异步化必须付出的代价,changes JSON 已标记 `breaking: true`,调用方需适配 |
| 4 | `setImmediate` 中 ctx 生命周期 | 与 `allocateStorage` / `batchIntercept` / `batchLock` / `batchUnlock` / `batchUnintercept` **共 5 处现有模式**完全一致,框架已验证可行 |
| 5 | 异步任务无超时 | 与 `allocateStorage` 一致,缓存 TTL 2 小时自然过期兜底 |
| 8 | `syncOrderIdsProgress` 无权限隔离 | 与 `allocateStorageProgress` 一致,`request_id` 含随机 token 不可猜测 |
| 9 | 操作日志 `ctx.user` 可能为空 | 随 #2 修复一并解决(旧日志代码已删除,新日志用快照 operator) |
| 11 | `progress_callback` 函数注入 | 链路中无 JSON 序列化操作,与 `allocateStorage` 一致 |
---
## 四、当前状态
```
变更文件:6 个
├── app/service/systemMethods/order/pendingOrder.js (修改)
├── app/service/systems/order_storage_allocation.js (修改)
├── methods/system.json (修改)
├── methods/changes/syncOrderIds-async-20260704.json (新增)
├── methods/changes/syncOrderIds-async-review-feedback-20260704.md (新增)
├── test/.../pendingOrder.syncOrderIds.test.js (新增)
└── test/.../pendingOrder.allocateStorage.test.js (修改)
ESLint: 0 errors ✅
单测: 27 passing ✅ (13 allocateStorage + 14 syncOrderIds)
```
---
## 五、遗留建议(非阻塞)
| 优先级 | 建议 | 说明 |
|--------|------|------|
| P3 | 增加任务心跳 + 超时自动标记 failed | 可后续迭代,与 `allocateStorage` 统一处理 |
| P3 | `syncOrderIdsProgress` 增加 `warehouse_id` 校验 | 防止跨仓库查询他人任务(当前依赖随机 token 安全性) |
| P3 | 确认前端调用方已适配新返回格式 | 需产品/前端确认 `request_id` 轮询流程 |