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

7.1 KiB
Raw Blame History

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