模块 11 · 数据迁移实战

开发的风险是可见的：写不通就报错，跑不起来就崩溃。而数据迁移的风险是沉默的——它不报错，它只是安静地把错数据搬进新系统，然后你在三个月后才发现报价算错了。

这一节是整个知识库里最能说明问题的一段。它解释了为什么「直接上引擎」是一个会失败的决策。

2.1 全域真实资产

德莉玛这条线的全域真实数据是：33,176 笔订单 / 387 家经销商 / 2,799 个型号。规模不小，看起来数据基础应该不错。用这批数据跑一遍覆盖率校验，结果是：

2.2 抽样 400 单看到什么

我抽样跑了 400 单，结果是：97% 的订单 spec 为空，也就是根本没有尺寸。有尺寸的只有 3 单——而这 3 单还属于 K / Y 系列，不是主流的 H / S / M 系列。

2.3 这页的结论

顺序不能乱。跳步的代价：跳过盘点直接清洗，你会按错误的假设写清洗规则；跳过清洗直接装载，脏数据进了新库；跳过对账，你根本不知道有没有丢。

这六种是我在真实项目里反复遇到的。分类的价值在于：每种形态有固定的对治套路，不用重新想。

下面是门店订购系统 v2.5.0 的建表配方。技术栈是 Express + better-sqlite3 + SQLite（开启 WAL）：单文件库、零部署、同步API 适合单进程服务，WAL 模式下读写不互斥，门店端写单和技术端读单可以并发。

-- ① 订单主表：一单一行
CREATE TABLE orders (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  order_no      TEXTNOT NULL UNIQUE,      -- 业务唯一键：幂等与去重都靠它
  dealer_id     INTEGER NOT NULL,          -- 经销商，对照表外键
  status        TEXT    NOT NULL,          -- 状态机：dispatched / store_signed / tech_confirmed / voided
  signed_at     INTEGER,                    -- 门店签认时间戳（UTC，存整数）
  tech_confirmed_at INTEGER,
  total_qty     INTEGER NOT NULL DEFAULT 0,-- 冗余合计，便于对账
  created_at    INTEGER NOT NULL,
  FOREIGN KEY (dealer_id) REFERENCES dealers(id)
);
CREATE INDEX idx_orders_status  ON orders(status);
CREATE INDEX idx_orders_dealer  ON orders(dealer_id);
CREATE INDEX idx_orders_created  ON orders(created_at);

-- ② 订单明细：一单多行
--为什么拆开：规格是列表，必须能按型号/厚度查询与统计，
--    塞成 JSON 就只能全表扫描（德莉玛踩过的坑）
CREATE TABLE order_items (
  id           INTEGER PRIMARY KEY AUTOINCREMENT,
  order_id     INTEGER NOT NULL,
  model_id     INTEGER NOT NULL,          -- 型号字典外键，不存型号字符串
  thickness_mm INTEGER NOT NULL,          -- 单位入库存：毫米。只存整数，不存 '8mm' 这类字符串
  spec_json    TEXT,-- 仅留不可查询的扩展属性，规格主体在上面三列
  qty          INTEGER NOT NULL DEFAULT 0,
  FOREIGN KEY (order_id)    REFERENCES orders(id),
  FOREIGN KEY (model_id)    REFERENCES models(id)
);
CREATE INDEX idx_items_order ON order_items(order_id);
CREATE INDEX idx_items_model ON order_items(model_id);
CREATE INDEX idx_items_thick ON order_items(thickness_mm);

-- ③ 型号字典：2,799 个型号，型号覆盖 96.6%
--    关键点：型号是「字典」不是「文本」；thickness 单列成整数列才能建索引
CREATE TABLE models (
  id           INTEGER PRIMARY KEY AUTOINCREMENT,
  model_code   TEXT    NOT NULL UNIQUE,    -- 归一化后的大写编码
  series       TEXT    NOT NULL,           -- H / S / M / K / Y 系列
  thickness_mm INTEGER NOT NULL,
  is_active    INTEGER NOT NULL DEFAULT 1  -- 有效/停用/废弃三态靠这个位隔离
);
CREATE INDEX idx_models_series ON models(series, is_active);

-- ④ 经销商对照表：387 家，客户匹配原本是 0%，靠这张表补上
CREATE TABLE dealers (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  dealer_code TEXT    NOT NULL UNIQUE,     -- 订单里的历史编码，靠它做映射
  name       TEXT    NOT NULL,
  short_name TEXT,-- 门店口语简称，用于对账时的模糊匹配
  is_active  INTEGER NOT NULL DEFAULT 1
);
CREATE UNIQUE INDEX idx_dealers_code ON dealers(dealer_code);

-- ⑤ 迁移执行记录：对账的凭据
CREATE TABLE migration_batches (
  batch_id     TEXT PRIMARY KEY,           -- 批次号，也用作幂等键
  source_count INTEGER NOT NULL,
  loaded_count INTEGER NOT NULL,
  ok_count     INTEGER NOT NULL,
  failed_count INTEGER NOT NULL,
  checksum_md5 TEXT    NOT NULL,           -- 源文件 MD5，验证没动过源数据
  created_at   INTEGER NOT NULL
);

为什么这么拆：三条判断依据

对账是唯一可信的验证方式。日志说成功只证明你写了，不证明写对了、没漏、没重。五层对账，从便宜到严格依次做：

• ✓我知道迁移失败几乎都不是技术问题，是数据问题；排期时按数据现状估，不按代码量估
• ✓我背得出德莉玛的数据画像：33,176 单/ 387 经销商 / 2,799 型号，型号 96.6%、厚度 95.2%、尺寸 29%、客户 0%
• ✓我知道 400 单抽样里 97% 的 spec 为空，仅 3 单有尺寸且属 K/Y 系列，不是主流 H/S/M 系列
• ✓我能用这组数据解释「为什么不能直接上报价引擎」，以及它如何改变了整个项目排期
• ✓我按盘点 → 清洗 → 转换 → 装载对账四步走，不跳步
• ✓我能说出脏数据的六种形态，并知道每种的对治手段，特别是 JSON blob 必须拆表加索引
• ✓我建表时会拆订单主表/明细/型号字典/经销商对照表，并说清每张表为什么这么拆
• ✓厚度用整数毫米单列存，不存字符串、不存不同单位的混合值
• ✓我会做五层对账：行数 / 求和 / 抽样 / 孤儿记录 / 反向验证
• ✓我坚持上线后每日对账，并把三个数字进监控告警
• ✓我动源数据前会先备份并留 md5 校验；迁移脚本分批 + 幂等可重入
• ✓我知道「日志说成功」不等于「数据迁移对了」