diff --git a/database/migrations/20260410200000-add-status-columns-to-wms-order-delivery-base.js b/database/migrations/20260410200000-add-status-columns-to-wms-order-delivery-base.js new file mode 100644 index 0000000..1e29cdb --- /dev/null +++ b/database/migrations/20260410200000-add-status-columns-to-wms-order-delivery-base.js @@ -0,0 +1,174 @@ +'use strict'; + +const TABLE = 'wms_order_delivery'; + +/** + * 与 `app/model/order_delivery.js`、`order_delivery_factory.js` 中 DDL 一致。 + * `up` 仅对缺失列执行 ADD;`down` 按逆序删除下列列(若存在)——若某列在迁移前已存在且含数据,请勿执行 down。 + * + * 列顺序与工厂建表一致,便于 `AFTER` 链式追加时相对位置稳定。 + */ +const STATUS_MACHINE_COLUMNS = [ + { + name: 'sync_status', + ddl: "enum('padding','fin','error') DEFAULT 'padding'", + comment: '同步状态', + after: 'oaid', + }, + { + name: 'post_status', + ddl: "enum('padding','fin','timeout','error','none') DEFAULT 'none'", + comment: '分配快递号状态机', + after: 'wave_id', + }, + { + name: 'storage_status', + ddl: "enum('padding','fin','error','none') DEFAULT 'none'", + comment: '分配储位状态机', + after: 'post_status', + }, + { + name: 'pick_status', + ddl: "enum('padding','fin','error','none') DEFAULT 'none'", + comment: '拣货状态机', + after: 'storage_status', + }, + { + name: 'pack_status', + ddl: "enum('none','padding','fin','error') DEFAULT 'none'", + comment: '打包状态机', + after: 'pick_status', + }, + { + name: 'inspection_status', + ddl: "enum('none','padding','running','fin','error') DEFAULT 'none'", + comment: '检验状态机', + after: 'pack_status', + }, + { + name: 'print_status', + ddl: "enum('none','padding','fin','error') DEFAULT NULL", + comment: '打印状态机', + after: 'step', + }, + { + name: 'claim_status', + ddl: "enum('none','padding','fin','error') DEFAULT 'none'", + comment: '领取状态机', + after: 'print_status', + }, + { + name: 'outbound_status', + ddl: "enum('none','padding','fin','error') DEFAULT 'none'", + comment: '出库状态机', + after: 'claim_status', + }, + { + name: 'lock_status', + ddl: "enum('none','warehouse','store') DEFAULT NULL", + comment: '锁定状态机', + after: 'outbound_status', + }, + { + name: 'intercept_status', + ddl: + "enum('none','requesting','requested','intercepting','intercepted_in_transit','intercepted_at_warehouse','returning','returned','delivered_by_mistake','timeout','cancelled','failed','exception') DEFAULT NULL", + comment: '拦截状态机', + after: 'lock_status', + }, +]; + +/** + * @param {import('sequelize').QueryInterface} queryInterface + * @param {string} tableName + * @param {string} columnName + * @return {Promise} + */ +async function hasColumn(queryInterface, tableName, columnName) { + const [ columns ] = await queryInterface.sequelize.query( + ` + SELECT COLUMN_NAME + FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = :tableName + AND COLUMN_NAME = :columnName + `, + { replacements: { tableName, columnName } } + ); + return columns.length > 0; +} + +/** + * @param {import('sequelize').QueryInterface} queryInterface + * @param {string} tableName + * @return {Promise} + */ +async function tableExists(queryInterface, tableName) { + const [ rows ] = await queryInterface.sequelize.query( + ` + SELECT COUNT(*) AS cnt + FROM INFORMATION_SCHEMA.TABLES + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = :tableName + `, + { replacements: { tableName } } + ); + return Number(rows[0].cnt) > 0; +} + +/** + * @param {import('sequelize').QueryInterface} queryInterface + * @param {string} tableName + * @param {string} preferredAfter + * @return {Promise} + */ +async function resolveAfterClause(queryInterface, tableName, preferredAfter) { + if (preferredAfter && (await hasColumn(queryInterface, tableName, preferredAfter))) { + return `AFTER \`${preferredAfter}\``; + } + return ''; +} + +module.exports = { + /** + * 仅为基表 `wms_order_delivery` 按需补状态机相关列;已存在则跳过。 + * + * @param {import('sequelize').QueryInterface} queryInterface + * @returns {Promise} + */ + async up(queryInterface) { + if (!(await tableExists(queryInterface, TABLE))) { + return; + } + + for (const col of STATUS_MACHINE_COLUMNS) { + if (await hasColumn(queryInterface, TABLE, col.name)) { + continue; + } + const afterPart = await resolveAfterClause(queryInterface, TABLE, col.after); + await queryInterface.sequelize.query( + `ALTER TABLE \`${TABLE}\` ADD COLUMN \`${col.name}\` ${col.ddl} COMMENT '${col.comment}' ${afterPart}`.trim() + ); + } + }, + + /** + * 逆序删除本文件声明的状态机列(若存在)。见文件头注释。 + * + * @param {import('sequelize').QueryInterface} queryInterface + * @returns {Promise} + */ + async down(queryInterface) { + if (!(await tableExists(queryInterface, TABLE))) { + return; + } + const reversed = [ ...STATUS_MACHINE_COLUMNS ].reverse(); + for (const col of reversed) { + if (await hasColumn(queryInterface, TABLE, col.name)) { + await queryInterface.sequelize.query( + `ALTER TABLE \`${TABLE}\` DROP COLUMN \`${col.name}\`` + ); + } + } + }, +}; diff --git a/docs/order-delivery-migration-impact.md b/docs/order-delivery-migration-impact.md new file mode 100644 index 0000000..d2ebf79 --- /dev/null +++ b/docs/order-delivery-migration-impact.md @@ -0,0 +1,62 @@ +# `wms_order_delivery*` / `wms_order_items*` 库表变更 — 影响面分析(供决策) + +> 目的:回答「改库是否影响当前所有涉及 order 发货单表的逻辑」;**未连真实库**,结论基于代码静态分析。 +> 关联:`order_todo.md` §0.7、§2.3a;核对清单 `docs/order-cancel-db-checklist.md`。 + +--- + +## 1. 结论摘要(是否可直接做迁移) + +| 变更类型 | 对现有逻辑的典型影响 | 建议 | +|----------|----------------------|------| +| **仅核对列已存在、不做 DDL** | 无 | **推荐先做**(清单 `order-cancel-db-checklist.md`) | +| **新增可空列 + 默认值**(`NULL` 默认 / `DEFAULT`) | Sequelize `create`/`update`/`find` 一般 **不崩**;未赋值的 `create` 不写该列则用库默认 | **低面影响**,但仍须 **同步** `app/model/order_delivery.js` + `order_delivery_factory.js` 的 `createPhysicalTable` DDL,且 **所有已存在分表** 需同一 migration 补列 | +| **新增 NOT NULL 无默认** | 旧 `create`/`bulkCreate` 可能 **插入失败** | **高面影响**,**禁止**在未改全链路前做 | +| **改 ENUM 取值 / 删列 / 改列类型** | `order.*` 列表 where、奇门/入库、报表可能 **全链路受影响** | **高面影响**,须单独评审与回归 | +| **仅改索引 / 注释**(不改列语义) | 一般低;大表加索引注意锁表 | 可个案评估 | + +**当前结论(在未跑 §0.7 清单、未选定「取消进 M4」专用列名之前):** +**不在仓库内自动提交新的 `ALTER` migration。** 代码侧已具备 `status.cancel`、`intercept_status.cancelled`、`step`(含 9 关闭)等枚举(见 `order-state-machine-dictionary.md`),**若跑库确认列已齐全,则「取消进 M4」可先不增列,仅做应用筛选逻辑** — 此时 **无需表迁移**。 +若跑库确认 **缺列** 或产品 **强制** 要独立标记列 → **属有面影响变更**,请在你确认 **列名、类型、默认值、是否只加 current 或含 history** 后再做 migration。 + +**(已更新)** 本机 `wms` 库经 **wms-db-agent** 只读抽样结果见 **`docs/order-cancel-db-checklist.md` §5**:两张分表目标列齐全,**可先不增列**;基表缺列、勿作业务筛选;全量仓与 `_history` 须另跑。 + +--- + +## 2. 代码侧「会吃到表结构」的路径 + +### 2.1 动态模型来源(关键) + +- `OrderDeliveryFactory` / `OrderItemsFactory` 使用 **`app.model.OrderDelivery.rawAttributes`**(及 `OrderItems`)**动态 `define` 每张分表**。 +- **新建物理表**时,`createPhysicalTable` 内 **手写 DDL 片段** 与模型字段 **必须长期一致**,否则新仓新表与 ORM 不一致。 + +### 2.2 业务入口(非穷举,均为 `getCurrentModel` 链) + +| 区域 | 文件 | +|------|------| +| System 订单 method | `app/service/systemMethods/order/*.js`(经 `base.js#getOrderModels`) | +| 业务发货单 | `app/service/systems/delivery_order.js`(`create` / `update` / `bulkCreate` 明细等) | +| 奇门 | `app/service/qimenMethods/deliveryorder.js` | +| 测试 / 探针 | `app/service/apiMethods/test.js`(命名 `WmsOrderDeliveryFactory` 需与挂载一致,否则仅测试路径) | + +### 2.3 写入方式 + +- `DeliveryModel.create(orderData)`、`OrderItemsModel.bulkCreate(lineData)`:**对象字段驱动**;新增 **可空** 列且模型已声明时,旧代码路径 **通常无需改** 即可插入。 + +--- + +## 3. 若你决定「要做加列迁移」时的必做清单 + +1. 产品确认:**列名、含义、是否可空、默认值、是否写 history 表**。 +2. Migration:`findOrderDeliveryTables` 风格 **遍历** `wms_order_delivery` / `wms_order_delivery_*`(及若需要则 `wms_order_items_*`)。 +3. `app/model/order_delivery.js` 增加字段定义。 +4. `app/model/order_delivery_factory.js` 中 **`createPhysicalTable`** 同步列定义。 +5. 回归:`npm run test:local` 中与 `delivery_order` / `order` 相关用例;奇门若有联调则单独测。 + +--- + +## 4. 修订 + +| 日期 | 说明 | +|------|------| +| 2026-04-10 | 初版:静态影响面结论;**未提交 migration** |