WMS_MAIN/docs/queryorder-wave-index-optimization-plan.md

10 KiB
Raw Blame History

queryOrder 波次计数性能优化方案(只读评估 + 方案文件,未执行)

状态:待用户风险确认。本方案全程只读评估,未执行任何 DDL / 数据变更。 编制:wms-db-agent|日期:2026-08-30

1. 背景与瓶颈定位

  • 业务链路:工作台 queryOrder → app/service/systems/workbench.js
    • _countWaveOrders():对 current + dispatch 两族分表执行 SELECT COUNT(*) WHERE wave_id=? AND warehouse_id=?
    • _getWaveOrderIds():同谓词取订单 id 列表
  • 现状瓶颈(上一轮 DB agent 已定位 + 用户提供生产数据):
    • 现有索引 idx_{wh}_current_wave 为 (status, wave_id),前导列 status 不在谓词中;
    • 生产 dispatch 分表约 25.38 万行 / 524MB,单次 COUNT 全表扫描约 12.69 万行;生产 MySQL 5.7.44。
  • 关联问题:序列表 wms_order_id_location_{wh} 缺约 12.4 万存量订单 id 记录 → queryOrder 定位回退为分表遍历(见 §5)。

2. 分表索引生成机制

2.1 模型层定义

  • app/model/order_delivery_table_schema.js:
    • buildIndexOptions(warehouseId, type) 生成每张分表的索引列表;
    • current 类型共 8 个索引,其中 idx_{wh}_current_wave = (status, wave_id)(瓶颈索引);
    • dispatch 类型复用 current 的基础索引:baseIndexes[0..2] + idx_dispatch_{wh}_dispatch_lane (dispatch_lane, status) + baseIndexes.slice(3),即 dispatch 分表同样继承 idx_{wh}_current_wave;
    • buildIndexLines() 用于建表 DDL;buildTableOptions() 供动态模型 define。
  • 基表模型 app/model/order_delivery.js 自带索引列表(wave_id = (status, wave_id) 等)——基表 wms_order_delivery 非分表,不在本次范围(可选加,默认不加)。

2.2 运行时 drift 同步(⚠️ 关键风险)

  • app/model/order_delivery_factory.js:getOrCreateModel → ensureManagedTableSchema → needsTableSchemaSync(比对期望索引)→ alterManagedTableSchema(只补缺失索引、不删已有索引)。
  • 每次进程首次使用某分表模型时触发(模型有内存缓存)。
  • 结论:若先改 schema 文件再部署代码,应用会在首个请求时自动对 524MB 大表执行建索引 DDL(无 ALGORITHM/LOCK 控制、无法择时)。
  • 因此正确顺序必须是:先执行迁移(低峰期)→ 再落盘 schema 代码变更 → 再部署;这样应用运行时 drift 检查发现索引已存在,不会重复建。

2.3 现有索引核对(开发环境,只读 SHOW INDEX)

开发环境(config.local.js,客户端 wms)确认 current/dispatch 分表现有索引与模型一致,瓶颈索引为:

表(开发环境示例) 瓶颈索引 列
wms_order_delivery_1000028_dispatch idx_1000028_current_wave status, wave_id
wms_order_delivery_1000028 idx_1000028_current_wave status, wave_id

开发环境分表规模(只读 information_schema):wms_order_delivery_100000 66,976 行 / 41.6MB;wms_order_delivery_100000_dispatch 2,488 行。生产分表规模以用户提供数据为准(dispatch 25.38 万行 / 524MB),执行前需实测。

3. 修改点清单

3.1 模型 schema(本次仅书面标注,未改文件)

为避免与 wms-dev-agent 的修复冲突,本 agent 不直接修改 schema 代码,待用户确认后由 wms-dev-agent 落盘;或在用户授权后由本 agent 改。

  • 文件:app/model/order_delivery_table_schema.js
  • 函数:buildIndexOptions,current 分支共享 indexes 数组内、idx_${prefix}_wave 之前插入:
{
  name: `idx_${prefix}_wave_id`,
  fields: [ 'wave_id' ],
},
  • dispatch 分支无需修改(通过 baseIndexes 自动继承)。
  • 索引名与迁移草案一致:idx_{wh}_current_wave_id(dispatch 表沿用 _current_ 前缀,与既有继承索引命名习惯一致)。

3.2 迁移文件(已创建,未执行)

  • 路径:database/migrations/20260830100000-add-wave-id-index-to-order-delivery-shards.js
  • 要点:
    • 动态枚举 wms_order_delivery_{wh} 与 wms_order_delivery_{wh}_dispatch(information_schema,不写死仓库 id);
    • 幂等:SHOW INDEX 已存在则跳过;
    • 使用原生 ALTER TABLE ... ADD INDEX ..., ALGORITHM=INPLACE, LOCK=NONE(Sequelize addIndex 不支持传算法/锁参数,故用原生 SQL);
    • down 为 DROP INDEX(同样 INPLACE/LOCK=NONE);
    • 语法已通过 node --check;未对任何环境执行。

4. 生产执行风险评估与建议

4.1 MySQL 5.7.44 在线 DDL 支持

  • InnoDB 添加二级索引支持 ALGORITHM=INPLACE, LOCK=NONE(MySQL 5.6+,5.7 完整支持):不重建表、不锁写、并发 DML 允许。
  • 前置检查项:
    1. SHOW VARIABLES LIKE 'old_alter_table' 应为 OFF(默认);
    2. 确认表引擎 InnoDB(本项目分表均为 InnoDB);
    3. 执行前实测各分表行数与大小。

4.2 预估耗时与索引体积

  • 索引体积:wave_id BIGINT(20)(8 字节)+ 主键 8 字节,25.38 万行约 4–6 MB,几乎不增加磁盘压力;
  • 建索引耗时:全表扫描 524MB + 排序 25 万行键值,低负载 SSD 上单个 dispatch 分表约 数十秒–5 分钟;current 分表按行数同比。多仓多表总窗口建议预留 15–30 分钟。
  • 副作用:每个分表多一个二级索引,INSERT 时多写约 20 字节/行,可忽略。

4.3 建议执行窗口

  • 低峰期:凌晨 02:00–05:00 或周末低峰;避开波次扫描定时任务(app/schedule/sync_finished_wave_batch.js)、批量导入与大促。
  • 逐表执行并监控:SHOW PROCESSLIST、INFORMATION_SCHEMA.INNODB_TRX(确认无长事务)。

4.4 执行方式(红线)

  • ❌ 禁止对生产库直接执行裸 ALTER TABLE;❌ 禁止用 script/db-query.ps1 查/改生产(它永远是开发环境)。
  • ✅ 生产必须走迁移流程:
    • 全量:$env:NODE_ENV='production'; npx sequelize-cli db:migrate --migrations-path database/migrations --env production
    • 或单条:node script/run-single-migration.cjs 20260830100000-add-wave-id-index-to-order-delivery-shards.js(内部连 database/config.js 的 production)
  • ⚠️ 生产当前有 4 条 pending 迁移(只读 db:migrate:status --env production 结果):20260829120000 / 20260829160000 / 20260829170000 / 20260829180000(report-delivery 相关)。run-single-migration.cjs 会拒绝跨序执行 → 先跑完这 4 条再跑本条;用 db:migrate 则按序自动全部执行。
  • 开发环境基线:迁移全部 up(最新 20260829180000);本条迁移在开发/生产两边均显示 down(未执行,符合"草案"状态)。

4.5 回滚

  • down:DROP INDEX(INPLACE/LOCK=NONE,秒级完成),不重建表、不影响数据。

5. 存量回填评估(script/backfill-order-id-location.cjs)

5.1 适用性

  • 目标:将分表存量 id 补入 wms_order_id_location_{wh}(id → location 映射),修复 queryOrder 定位回退(约 12.4 万行缺失)。
  • 脚本能力:--dry-run、--warehouse-id=、--batch-size=(100–50000,默认 1000)、--db-client=、--config-path=。
  • ⚠️ 默认连开发库(config.local.js);生产必须 --config-path=script/db-query-prod-config.js --db-client=wms。
  • 流程:枚举分表 → 确保序列表存在(缺失时 CREATE TABLE)→ 分批 LEFT JOIN(PK 序)找缺失 id → 多行 INSERT ... ON DUPLICATE KEY UPDATE → 每仓结束抬 AUTO_INCREMENT = MAX(id)+50。

5.2 数据量与分批建议

  • 约 12.4 万行;默认 batch=1000 约 124 批。每批重新执行 LEFT JOIN(无物化),最大分表 25 万行 × 124 批 ≈ 3 千万次 PK 探测,低峰可接受;建议 --batch-size=5000 减少轮次。
  • 建议顺序:--dry-run 全量预演 → 核对输出 → 按仓库逐个 --warehouse-id= 执行 → 前后核对 COUNT(*)。

5.3 风险点

  1. id 碰撞(最高风险):回填期间若序列表 AUTO_INCREMENT 仍低于缺失 id 区间,新订单可能分配到相同 id,ON DUPLICATE KEY UPDATE 会把新订单的 location 覆盖为来源表 location。执行前必须核对:AUTO_INCREMENT vs 缺失 id 最大值;务必在最低写入时段执行。
  2. DDL:ensureSequenceTable 可能 CREATE TABLE;结束会 ALTER TABLE ... AUTO_INCREMENT(小表、秒级)——均属 DDL/写操作,需用户确认。
  3. location 覆盖:id 已存在于序列表时会被覆盖(脚本语义如此)。
  4. 无断点续跑:中断后重跑安全(幂等 upsert),但需重新扫描。
  5. 与加索引互补:索引修波次计数,回填修订单定位,两者独立、可分开执行。

6. 需要用户确认的风险问题清单(交 Dispatcher 转达)

  1. 是否允许在生产执行加索引 DDL?(未确认前不执行)
  2. 执行方式:全量 db:migrate(会自动先执行生产 pending 的 4 条 20260829* 迁移)还是单条 run-single-migration.cjs(需先补跑那 4 条)?是否同意先执行那 4 条?
  3. 执行窗口:请指定具体时间(建议凌晨 02:00–05:00);期间可接受轻微 I/O 压力?
  4. 索引范围:确认 current + dispatch 两族分表、全部仓库都加?
  5. 是否允许对 wms_order_id_location_{wh} 回填写数据(约 12.4 万行)?是否先 --dry-run 预演?
  6. 回填窗口与 id 碰撞:是否可安排在最低写入时段?是否同意先核对序列表 AUTO_INCREMENT 区间?
  7. schema 代码变更(buildIndexOptions 新增 idx_{prefix}_wave_id):是否由 wms-dev-agent 落盘?确认部署顺序 = 先迁移、后代码。
  8. 回滚授权:若上线后异常,是否允许执行 down(DROP INDEX)?

7. 建议执行顺序

  1. 用户完成 §6 风险确认;
  2. 生产低峰期执行迁移(含前置 4 条 pending);
  3. 生产 SHOW INDEX + EXPLAIN 验证新索引生效;
  4. wms-dev-agent 落盘 buildIndexOptions 变更并部署(避免运行时 drift 重复建索引);
  5. (可选)序列表回填(先 dry-run);
  6. 观察 queryOrder 链路耗时与错误率。