# 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` 轮询流程 |