订单工作台模块 — 规划草案(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 前必须执行:
- 核对清单(已产出,小阶段):只读 SQL 与步骤见
docs/order-cancel-db-checklist.md(不在仓库内自动连库执行)。库表 DDL 变更影响面见 docs/order-delivery-migration-impact.md。
- 对库:对
wms_order_delivery 及 wms_order_delivery_% 分表 跑字段清单(INFORMATION_SCHEMA),确认 status / intercept_status / step / outbound_status 等与「取消后进 M4」筛选用例是否够用。
- 若产品要求独立可辨的「取消进 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 — 文档与规则冻结
阶段 B — 配送域工厂(3 自然月 + 强分区事务)
阶段 C — 归档 M6 + 时间消除
阶段 D — 补发副本与目标更新
阶段 E — API / 测试
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 勾选与表述同步 |