chore: minor updates and improvements

This commit is contained in:
liufumingren 2026-04-11 17:30:15 +08:00
parent aba81d497a
commit b0700c6629
2 changed files with 236 additions and 0 deletions

View File

@ -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<boolean>}
*/
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<boolean>}
*/
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<string|null>}
*/
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<void>}
*/
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<void>}
*/
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}\``
);
}
}
},
};

View File

@ -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** |