WMS_MAIN/order_todo.md
2026-04-17 19:21:57 +08:00

24 KiB
Raw Blame History

订单工作台模块 — 规划草案(order_todo)

状态:计划,供评审与补充;实现前需与产品、DBA、前端对齐。
关联:OrderDeliveryFactory / OrderItemsFactory(current / history 物理表)、order_delivery / order_items 基模型、现有 order.* system method。


0. 当前订单表、模型、工厂与关联(代码现状分析)

0.1 物理表与工厂命名

概念 物理表名模式 说明
发货单 current wms_order_delivery_{warehouseId} 按仓动态建表,OrderDeliveryFactory.generateTableName(wh, 'current')
发货单 history wms_order_delivery_{warehouseId}_history 多 archive_time 字段与索引;业务代码尚未写入/迁移
订单明细 current wms_order_items_{warehouseId} OrderItemsFactory.generateTableName(wh, 'current')
订单明细 history wms_order_items_{warehouseId}_history 同上,待迁移任务

基模型 tableName 为模板:wms_order_delivery、wms_order_items(用于 rawAttributes 复制到动态表)。

0.2 基模型 OrderDelivery(app/model/order_delivery.js)

  • 主键与业务键:id,delivery_order_code + store_id + warehouse_id 唯一索引(动态表工厂内复刻)。
  • 货主 / 仓库:store_id(货主)、warehouse_id(仓库);创建时落 M1/M2 可依据货主(store)侧配置(配置表/字段待产品定义,当前模型无显式「进审开关」字段)。
  • 状态机字段(枚举在模型内):status,sync_status,post_status,storage_status,pick_status,pack_status,inspection_status,print_status,claim_status,outbound_status,lock_status,intercept_status。
  • 业务辅助:step(注释:0 未审核 / 1 已审核 / 2 处理中 / 3 驳回异常 / 4 配送中 / 5 已完成 / 9 已关闭)、wave_id、金额与地址收件人、items(TEXT JSON 字符串)、items_hash / items_crc / items_count 等。
  • 物流展示相关(主表冗余):logistics_code、logistics_name、express_code、delivery_time 等;细粒度快递轨迹见下文物理表 wms_order_express。

0.3 基模型 OrderItems(app/model/order_items.js)

  • 关联键:order_id → 发货单 id;item_code、item_id、stock_id、owner_code、plan_qty、价格字段、extend_props(JSON)。
  • 索引:order_id、item_id、source_order_code、stock_id 等。

动态明细表由工厂 define 时复制 OrderItems.rawAttributes,并 copyAssociations 自基模型。

0.4 工厂类职责

工厂 文件 职责摘要
OrderDeliveryFactory app/model/order_delivery_factory.js getCurrentModel / getHistoryModel / getModelByTableName;不存在则 createPhysicalTable;setupAssociations 将动态发货单与 同仓同类型 动态 OrderItems 做 hasMany / belongsTo;可选 belongsTo Store(货主/仓库别名)
OrderItemsFactory app/model/order_items_factory.js 同上;并发建表锁 creatingTables;动态表带 timestamps: true

现状:全仓业务查询路径普遍只调用 getCurrentModel;getHistoryModel 无业务引用。

0.5 其它订单相关物理表(非按仓工厂)

模型 表名 与订单关系
OrderExpress wms_order_express order_id 关联订单主键;运单、物流接口、星河签收/退回/拦截等标记。未纳入 OrderDeliveryFactory 动态表;若配送域拆分需定义 order_id 与仓、自然月分区 的一致性(否则跨表 JOIN 成本高)。

0.6 System 层与工厂衔接

  • app/service/systemMethods/order/base.js 中 getOrderModels(warehouseId) 仅 getCurrentModel 取发货单 + 明细。
  • 列表类:reviewOrder、pendingOrder、expectionOrder、deliveryOrder、archiveOrder 等均基于上述 current 模型。

0.7 取消相关状态机(代码已有 vs 库表须核对)

代码侧(app/model/order_delivery.js)已具备、可用于「取消」语义的枚举取值包括:

位置 取值/说明
status 枚举含 cancel(订单状态)
intercept_status 枚举含 cancelled 等拦截/关闭链路
step 整型步骤,注释含 9 = 已关闭;近期迁移为各分表补 step(见 database/migrations/20260410150000-replace-audit-status-with-step-on-order-delivery-tables.js)

实施 §2.3a 前必须执行:

  1. 核对清单(已产出,小阶段):只读 SQL 与步骤见 docs/order-cancel-db-checklist.md(不在仓库内自动连库执行)。库表 DDL 变更影响面见 docs/order-delivery-migration-impact.md。
  2. 对库:对 wms_order_delivery 及 wms_order_delivery_% 分表 跑字段清单(INFORMATION_SCHEMA),确认 status / intercept_status / step / outbound_status 等与「取消后进 M4」筛选用例是否够用。
  3. 若产品要求独立可辨的「取消进 M4」标记(例如与 status=cancel 但尚未占配送域行的组合区分):库中无字段则新增(如 close_channel、cancelled_at、m4_reason_code 等,名称待定),并同步:
    • app/model/order_delivery.js;
    • OrderDeliveryFactory.createPhysicalTable 生成的 DDL 模板;
    • 已有物理分表的 补列 migration(循环 wms_order_delivery_*)。

1. 目标与范围(含 outsourced)

1.1 工作台模块一览

模块 说明(产品语义) 规划数据域
M1 待审核 需审核后进入后续履约 仅 current
M2 待处理 仓内/出库前正常队列 仅 current
M3 待处理异常 出库前各环节异常 仅 current
M4 配送订单 配送链路正常态 配送域工厂(首期已落地):单表 wms_order_delivery_dispatch_{wh} + 列 dispatch_lane=m4;不按自然月拆物理表
M5 配送异常 配送链路异常(M4 子集) 同上表,dispatch_lane=m5 筛选;归档/近三月策略走 查询与任务,不必多分表
M6 归档订单 冷数据 history(>3 月等策略)
outsourced 外仓发货 本仓不履约、推送外仓/三方履约;已纳入 OrderDeliveryFactory 管理的 managed table / schema self-check 体系 由工厂统一管理,启动自检自动对齐结构;仍可结合 current 扩展标记 + 外仓任务表落地

1.2 数据分层(与 §0 对齐)

层级 表 / 模型 时间 / 策略
热区 M1~M3 / outsourced(规划) wms_order_delivery_{wh}、wms_order_items_{wh}(current) 当日或未闭环;创建时分流 M1 vs M2 由货主配置决定;到期仅克隆续单,不进 M6(§2.4)
配送区 M4/M5 wms_order_delivery_dispatch_{wh}(OrderDeliveryFactory 的 dispatch 模式) 单物理表;M4/M5 用 dispatch_lane;不按自然月拆表;「约 3 个月」保留为 列表/归档任务的时间条件(见 §2.5 落地说明)
冷数据 M6 *_history(仅承接 M4/M5 迁入) 超过 3 个月等策略;仅允许 M4/M5 进入 M6;M1/M2/M3/outsourced 不走 M6 物理归档路径(见 §2.4)

2. 模块规则与状态流转(补充)

2.1 订单创建:进入 M1 或 M2

  • 规则:创建时读取 货主(store)配置,决定初始进入 M1(待审核) 或 M2(待处理)。
  • M1 → M2:必须通过 仓内库存校验(满足可履约)或 选择 推送 outsourced(外仓发货) 路径之一;具体字段与接口待定义。
  • M2 ⊥ outsourced(强制互斥):同一订单 不得 同时处于本仓待处理与外仓履约;进入或退出 M2/outsourced 的切换 必须在单条(或可串行化的)数据库事务内完成(状态位 + 外仓任务表等一并提交),失败 整体回滚,禁止半开状态。
  • outsourced:当前 无完整状态机;与 M4 的衔接仍遵守 §2.2 单向规则。

2.2 进入 M4 的约束(核心)

从 → 到 是否允许 说明
M2 → M4 允许(单向) M2、outsourced 仅允许单向落入 M4
outsourced → M4 允许(单向) 外仓发货完成后,依赖 外部通知 与出库状态机推进
M1 → M4 禁止 须先 切到 M2 且 状态机到达出库 后,再经 外部通知发货完成 落入 M4
M3 → M4 禁止 须先 消除异常并回到 M2,再走与 M2 相同路径进入 M4
取消订单 → M4 允许(专用) 见 §2.3a:标记取消态后 直进 M4,不可逆、零例外

2.3 M4 / M5 与外部机制

  • M4 ↔ M5 切换:由 外部机制 驱动(承运商回传、网关、人工标记等),不在此文档展开协议。
  • M4/M5 与 M1~M3:除下节「补发副本」外,同一订单在 M1/M2/M3/outsourced 与 M4/M5 不重复占位:M1~M3(及 outsourced)为唯一工作台态;M4/M5 为配送域单独态(可理解为 配送域一条影子/主数据,与 current 热行通过 order_id / delivery_order_code / 快照关联)。

2.3a 订单取消(特殊路径:标记后进 M4)

  • 规则:发生 订单取消 时,须在热区/配送衔接层 写入取消类状态标记(状态机字段组合或专用列,见 §0.7),并 直接进入 M4(配送域占位,用于闭环展示与后续「仅 M4/M5 可进 M6」链路);不可逆,不允许任何业务或技术例外(含回滚接口、静默改回热区)。
  • 与 §2.2 的关系:本条为 取消专用例外;非取消场景下 M1/M3 仍禁止直落 M4(见 §2.2 表)。
  • 库表:上线前按 §0.7 核对;缺字段则 migration 补充,禁止仅靠应用层内存状态表达取消进 M4。

2.4 时间驱动的 M6(不可逆 + 准入白名单)

  • 时间策略:所有订单类型均受时间维度约束,不另开例外;进入 M6(物理归档)后不可逆,不允许任何例外(不设司法解冻、不设未归档回退通道)。
  • 谁可以进 M6(物理):仅 M4、M5 对应的配送域数据(及与其绑定的明细快照)允许在满足保留期后 迁入 history / 冷存储。
  • 谁不可以进 M6:M1、M2、M3、outsourced 热区行 不允许 走与 M4/M5 相同的 M6(history)迁入通道;到期后仅允许「克隆续单」:通过 新行(新主键) 承接后续履约,原行 仅改标记(§2.7),不得删/软删、不得将原行迁入 M6。
  • 克隆续单 / 补单(首期):不与奇门等平台同步;定位为 补单,由 人工在仓内/运营侧处理;系统可提供列表与标记能力,接口与对账范围以本仓 WMS 为准。
  • M4/M5 → M6:以 出库时间(如 delivery_time / 出库确认时间)为主键条件之一,满足 >3 个月(与 §1.2 口径对齐)后迁入 history;过程 不可逆。

2.5 配送域工厂(首期落地 + 后续)

  • 已实现:app/model/order_delivery_factory.js 的 dispatch 模式;物理表 wms_order_delivery_dispatch_{warehouseId}(与热区 wms_order_delivery_{wh} 命名同族,中间段 dispatch);M4/M5 同表,列 dispatch_lane ENUM('m4','m5') 区分;不按自然月拆物理表。getDispatchModel(wh) 为主入口;getM4Model/getM5Model 复用同一 dispatch 模式返回 同一模型。outsourced 也已经纳入同一工厂管理,应用启动时会通过自检自动对齐 managed table 结构。
  • 单测:test/app/model/order_delivery_dispatch_factory.test.js;需连库时 DISPATCH_FACTORY_TEST_MYSQL=1(见 config/plugin.js);留表排查 KEEP_DISPATCH_FACTORY_TABLES=1。
  • 仍待:与 current 的 副本同步 / 事件驱动;强分区事务 口径改为「单事务内同一 warehouse_id + 配送域表」即可(不再绑定 yyyyMM 表名);wms_order_express 与配送域行关联方案;M6 迁入仍以 出库时间 + 保留期 驱动(§2.4)。

2.6 M4/M5 副本回归 M1 / M2 / M3(补发 / 部分履约)

  • 场景:配送域需 重新创建副本 回到 M1 或 M2 或 M3(目标态由业务定)。
  • 强制携带:补发标记/补发单;或 引用原资料 + 部分商品行 的 补发语义,并 更新履约目标(新 delivery_order_code 或子单号、关联原单 ID 等,待表设计)。
  • 约束:回归后重新遵守 §2.1~2.2 的互斥与单向规则;原配送域行 不得删除/软删,仅 改标记 或保留为 只读关联(§2.7)。

2.7 副本、主单与删除策略(硬约束)

  • 禁止物理删除;禁止软删除(不使用 delete_at / paranoid 等表达「行消失」)。
  • 仅允许:改标记(如 lifecycle_state、superseded_by_id、closed_reason、is_supplement 等,具体字段待表设计)或 克隆 新行(新主键)承载补发/续履约。
  • 适用范围:所有副本(配送域副本、热区补发单、回归产生的克隆行、引用链上的历史快照)一律同上。
  • 运维级「克隆」语义:在本规划中特指 对状态机字段的合法变更(含批量修正、step / 各 *_status / 取消标记等),等价于「把行修正到合规状态」;不是对 §2.3a「取消进 M4」或 §2.4「M6 不可逆」的 豁免回滚。若技术上采用「插入新行再改关联」实现修正,仍须满足 不删旧行、仅标记(§2.7 首条)。审批角色与留痕 见 §5a 预留,本期不落地。

2.8 互斥与唯一性(更新)

关系 说明
M1 ⊥ (M2 ∪ M3) 不变
M2 ⊥ M3 不变
M2 ⊥ outsourced 强制互斥;切换须 事务(§2.1)
M5 ⊆ M4 不变
M1~M3 / outsourced(热区) 同一订单唯一展示态(互斥集合内择一)
M4 / M5 配送域内可与热区并存为 影子数据;列表层需约定「主工作台只显示一侧」避免重复操作
M6 仅 M4/M5 可物理迁入;不可逆、零例外;热区到期 不进 M6,仅允许克隆续单(§2.4)

3. 查询设计任务(列表 + 明细)

3.1 列表查询(各模块)

目标:最小可用字段集 + 足够前端判断订单状态(含 outsourced 外仓标记若存在)。

原则:

  • 列表不返回大体积 items TEXT;仅标识、各 *_status、outbound_status、inspection_status、step、updated_at / delivery_time、货主/仓编码等。
  • 实现:按模块常量 LIST_FIELDS;M4/M5/outsourced 在配送域或扩展表就绪后各自维护一份。

3.2 明细查询

  • 主单:可对前端公开的全部字段(排除密钥、内部调试字段)。
  • 明细行:OrderItems 动态表全量可公开字段。
  • 关联:Store/仓库等(以 Sequelize setupAssociations / copyAssociations 为准,文档列出 别名 + 字段子集)。
  • 快递:暂不接订阅/路由逻辑;列表/明细仅展示;DTO 硬编码字段表 + 中文标签注释(主表 logistics_* + 若联查 wms_order_express 则增加运单等字段)。

3.3 快递展示字段清单(示例)

字段 key 前端标签 说明
logistics_name 承运商 仅展示
logistics_code 物流编码 仅展示
waybill_code(express 表) 运单号 仅展示
… … 不接路由、不订阅

4. 执行任务(分阶段,可微调)

执行进度(小阶段 A-0,最小影响)

日期 内容
2026-04-10 无业务代码 / 无 migration 变更。新增只读交付物:docs/order-cancel-db-checklist.md(§0.7 跑库步骤)、docs/order-state-machine-dictionary.md(状态机字典 v0 骨架,与 app/model/order_delivery.js 摘录一致)。数仓映射、实际跑库结果 仍待下一小阶段。
2026-04-10 小阶段 A-1(影响面):新增 docs/order-delivery-migration-impact.md。结论:在未跑库确认缺列、且未敲定「取消进 M4」专用列前,不自动提交 ALTER migration;若清单验证列已齐,可先 零表变更 做应用筛选。详见该文档 §1。
2026-04-10 小阶段 A-2(wms-db-agent 只读诊断):已对 wms 库跑清单;结果写入 docs/order-cancel-db-checklist.md §5。要点:分表 100000/1000028 目标列齐全,可先不增列做筛选;基表缺三列、勿当业务表用;无 _history 样本;chcp 65001 防 JSON 解析失败。
2026-04-11 基表状态列:migration 20260410200000-add-status-columns-to-wms-order-delivery-base.js(按需补列,与热区分表对齐)。配送域:OrderDeliveryFactory 的 dispatch 模式单表 wms_order_delivery_dispatch_{wh} + dispatch_lane;当前按单表落地,不再保留「m4/m5 分表 + 自然月表名」方案;单测与 DISPATCH_FACTORY_TEST_MYSQL 见上文 §2.5。
2026-04-11 outsourced 收敛:outsourced 纳入 OrderDeliveryFactory 的 managed table / schema self-check 体系,沿用启动自检自动对齐结构;旧兼容 shim 已移除,文档与代码统一收口到工厂管理。

阶段 A — 文档与规则冻结

  • 货主配置:「创建进 M1 / M2」的配置项落库位置与变更流程。
  • M1→M2:库存校验 API、outsourced 推送接口与回写字段。
  • 外部「发货完成」通知与状态机字段的映射表(落到 outbound_status / step 等)。
  • §0.7 清单文档:docs/order-cancel-db-checklist.md(各环境人工执行)。
  • §0.7 跑库(本机 wms 一次):见 docs/order-cancel-db-checklist.md §5;分表列齐;其它仓/生产须复跑。
  • §0.7 基表状态列 migration(与分表枚举对齐):database/migrations/20260410200000-add-status-columns-to-wms-order-delivery-base.js(已合并进仓库;其它环境须自行 db:migrate)。独立「取消进 M4」业务列 仍待产品定名后再 migration。
  • 状态机字典 v0 骨架:docs/order-state-machine-dictionary.md(与数仓/报表的 字段映射表 仍待补)。
  • 订单表 DDL 影响面分析:docs/order-delivery-migration-impact.md(初版静态结论;2026-04-11 起基表状态列以已合并 migration 为准,文档全文若与现网不一致须择机修订)。

阶段 B — 配送域工厂(3 自然月 + 强分区事务)

  • 配送域建表能力(OrderDeliveryFactory 的 dispatch 模式):表 wms_order_delivery_dispatch_{warehouseId},dispatch_lane 区分 M4/M5。
  • M4/M5 单表 DDL 与动态模型(首期)。
  • 与 current 的 副本同步 或 事件驱动 方案(未做)。
  • wms_order_express 与配送域 order_id(及仓)一致性方案。

阶段 C — 归档 M6 + 时间消除

  • 仅 M4/M5:配送域 → history 的 出库时间 驱动任务;不可逆 校验与审计(零例外)。
  • M1/M2/M3/outsourced:到期 仅克隆续单 流程(新行 + 原行标记);禁止 迁入 M6;前端 空态/引导续单 文案。
  • 取消进 M4:状态机字段字典、事务边界、与常规 M4 列表的 展示分区(避免与正常配送混淆)。
  • 全库 禁止 DELETE/软删 副本与主单的 ORM/脚本审计;运维修正走 状态机变更(§2.7);审批流 见 §5a 预留。

阶段 D — 补发副本与目标更新

  • 补发单模型、原单引用、部分行、目标更新字段;原行仅标记,禁止删/软删。
  • 事务:副本创建 + 热区插入 + 配送域标记 同一强分区键内 或可补偿 Saga;与 M2↔outsourced 事务切换 共用事务规范文档。

阶段 E — API / 测试

  • methods/system.json + changes;互斥与单向集成测试用例。

5. 待补充项 — 满足情况说明(已更新)

结论:原「待补充项」中的 业务原则 / 边界 多数已在正文(§0.7、§2.3a、§2.4、§5a)闭合,不再属于「方向未定的拍板」;但 可交付的设计稿与成文资产 仍未完成,须在 §4 各阶段 跟踪直至产出。

5.1 规则层 — 视为已满足(已写入本文档)

原议题 满足方式
克隆续单是否与奇门同步 已决策:不同步;首期 人工补单 — 见 §2.4
运维审批、留痕格式 已决策:本期不做,仅预留 — 见 §5a
取消状态机是否依赖库表 已决策:以 DB 为准,缺列则 migration — 见 §0.7、§2.3a

5.2 交付层 — 尚未满足(须产出成果物,不等同于「原则未拍板」)

事项 当前状态 建议产出 / 跟踪位置
取消进 M4 的配送域 子类型 / 展示标签(与正常 M4 区分色、筛选项) 未完成 产品/UI 说明 + 接口 where 约定;§4 阶段 C
克隆续单 的 主键关联、单号规则、权限 未完成 表设计 + 人工补单 SOP;§4 阶段 D(原则「不奇门」已 §2.4)
改标记 / 状态机 的 字段字典 及与 数仓、报表 同步 骨架已完成(v0) 成稿:docs/order-state-machine-dictionary.md;数仓/报表映射与变更登记 仍未完成 — §4 阶段 A/C

5a. 预留(本期不实现)

  • 运维审批 角色、工单模板与 留痕格式:本期不做,仅在技术方案中 预留扩展点(配置键、审计表占位名、接口 hook 注释),避免后续硬改核心表结构。

6. 修订记录

日期 说明
(首版) 根据讨论整理计划草案
补充 增加 §0 当前表/模型/工厂/关联分析;outsourced、创建分流、进入 M4 约束、外部驱动 M4/M5、时间进 M6、配送域独立工厂与强分区事务、M4/M5 按出库时间进 M6、补发副本回归 M1/2/3
补充 M2⊥outsourced 且事务进出;M6 仅 M4/M5 可物理迁入、不可逆;热区到期不进 M6;全副本禁止删/软删、仅标记或克隆;§2.7 硬约束、§1.2/阶段 C/待补充项同步
补充 热区到期 仅克隆续单;§2.3a 取消→标记→直进 M4、不可逆零例外;运维「克隆」= 状态机合法变更 写入 §2.2/§2.7/阶段 C
补充 §0.7 取消状态机与分表核对/缺列 migration;克隆续单不奇门同步、首期人工补单;字段字典与数仓报表同步;§5a 运维审批预留
补充 §5 重写:区分 规则层已满足 vs 交付层未完成;原 checklist 拆入 §5.1 / §5.2 并指向 §4
2026-04-10 小阶段 A-0:新增 docs/order-cancel-db-checklist.md、docs/order-state-machine-dictionary.md;§0.7 / §4 阶段 A / §5.2 同步;无代码变更
2026-04-10 小阶段 A-1:docs/order-delivery-migration-impact.md;未提交 migration(待你根据跑库 + 列名决策)
2026-04-10 小阶段 A-2:wms-db-agent 只读诊断;order-cancel-db-checklist.md §5;未提交 migration
2026-04-11 配送域单表工厂 + 基表 migration;§1.2 / §2.5 / §4 阶段 B 勾选与表述同步