fdb2 1.0.37 → 1.0.39

package/dist/server/core/schema/__tests__/diff.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it } from 'vitest';
+import { canonicalizeTableEntity, canonicalizeTableSpec } from '../canonical';
+import { diffTable } from '../diff';
+import { isEmptyChangeSet } from '../../../model/ddl-spec';
+import type { TableSpec } from '../../../model/ddl-spec';
+
+const baseEntity = () => ({
+  name: 'users',
+  comment: '用户表',
+  columns: [
+    { name: 'id', type: 'int', nullable: false, isPrimary: true, isAutoIncrement: true },
+    { name: 'name', type: 'varchar(64)', nullable: false },
+    { name: 'age', type: 'int', nullable: true, defaultValue: 0 }
+  ]
+});
+
+/** 由实体镜像出的目标 spec（等价回显，测试的"未修改"基线） */
+function mirrorSpec(
+  entity: ReturnType<typeof baseEntity>,
+  overrides?: { pk?: string[]; specColumns?: TableSpec['columns'] }
+): TableSpec {
+  const pk = overrides?.pk ?? entity.columns.filter((c) => c.isPrimary).map((c) => c.name);
+  return {
+    name: entity.name,
+    comment: entity.comment,
+    columns:
+      overrides?.specColumns ??
+      entity.columns.map((c) => ({
+        name: c.name,
+        type: c.type.replace(/\(\d+(,\d+)?\)/, ''),
+        length: c.type.includes('varchar') ? '64' : undefined,
+        nullable: c.nullable,
+        hasDefault: c.defaultValue !== undefined,
+        defaultValue: c.defaultValue !== undefined ? String(c.defaultValue) : undefined,
+        autoIncrement: c.isAutoIncrement
+      })),
+    primaryKey: pk
+  };
+}
+
+function diffBoth(entity: ReturnType<typeof baseEntity>, spec: TableSpec) {
+  return diffTable(canonicalizeTableEntity(entity), canonicalizeTableSpec(spec));
+}
+
+describe('主键（用户报修的 bug）', () => {
+  it('勾选某列为主键又取消：零 diff，不产生任何语句', () => {
+    const entity = baseEntity();
+    // 勾 name 为主键（同时顶掉 id）再取消 —— 终态与初态一致
+    const spec = mirrorSpec(entity, { pk: ['id'] });
+    const cs = diffBoth(entity, spec);
+    expect(isEmptyChangeSet(cs)).toBe(true);
+  });
+
+  it('主键 A→B：只动 primaryKey 桶，绝不产生列级 modified（旧实现的双重记账）', () => {
+    const entity = baseEntity();
+    const spec = mirrorSpec(entity, { pk: ['name'] });
+    const cs = diffBoth(entity, spec);
+    expect(cs.primaryKey).toEqual({ from: ['id'], to: ['name'] });
+    // 唯一允许的列级联动：id 失去主键身份 → 自增失效（emit 层需要这个信息）
+    const pkChangedCols = ['id', 'name'];
+    cs.modified.forEach((m) => {
+      expect(pkChangedCols).toContain(m.name);
+      expect(m.fields).toEqual(['autoIncrement']);
+    });
+    expect(cs.renamed).toEqual([]);
+    expect(cs.added).toEqual([]);
+    expect(cs.dropped).toEqual([]);
+  });
+
+  it('主键 A→无：from=[id], to=[]（旧前端会生成非法的 ADD PRIMARY KEY ()）', () => {
+    const entity = baseEntity();
+    const cs = diffBoth(entity, mirrorSpec(entity, { pk: [] }));
+    expect(cs.primaryKey).toEqual({ from: ['id'], to: [] });
+  });
+
+  it('无→有：to=[name]（旧前端会多生成一条多余的 DROP PRIMARY KEY）', () => {
+    const entity = {
+      name: 'users',
+      comment: '',
+      columns: [
+        { name: 'name', type: 'varchar(64)', nullable: false }
+      ]
+    };
+    const spec = mirrorSpec(entity as any, { pk: ['name'] });
+    const cs = diffBoth(entity as any, spec);
+    expect(cs.primaryKey).toEqual({ from: [], to: ['name'] });
+  });
+
+  it('复合主键顺序敏感：(a,b) 与 (b,a) 是变更', () => {
+    const entity = {
+      name: 't',
+      comment: '',
+      columns: [
+        { name: 'a', type: 'int', nullable: false, isPrimary: true },
+        { name: 'b', type: 'int', nullable: false, isPrimary: true }
+      ]
+    };
+    const cs = diffBoth(entity as any, mirrorSpec(entity as any, { pk: ['b', 'a'] }));
+    expect(cs.primaryKey).toEqual({ from: ['a', 'b'], to: ['b', 'a'] });
+  });
+});
+
+describe('重命名检测（防 DROP+ADD 数据丢失）', () => {
+  const entityWith = (name: string) => ({
+    name: 't',
+    comment: '',
+    columns: [{ name, type: 'int', nullable: false }]
+  });
+
+  it('usr_nme → user_name：进 renamed 桶，不进 added/dropped', () => {
+    const entity = entityWith('usr_nme');
+    const spec: TableSpec = {
+      name: 't',
+      comment: '',
+      primaryKey: [],
+      columns: [{ name: 'user_name', type: 'INT', nullable: false, hasDefault: false }]
+    };
+    const cs = diffBoth(entity as any, spec);
+    expect(cs.renamed).toEqual([
+      { from: 'usr_nme', to: 'user_name', definitionChanged: false, modifiedFields: [] }
+    ]);
+    expect(cs.added).toEqual([]);
+    expect(cs.dropped).toEqual([]);
+    expect(cs.modified).toEqual([]);
+  });
+
+  it('改名 + 改定义：renamed.definitionChanged，不重复进 modified', () => {
+    const entity = entityWith('usr_nme');
+    const spec: TableSpec = {
+      name: 't',
+      comment: '',
+      primaryKey: [],
+      columns: [{ name: 'user_name', type: 'BIGINT', nullable: false, hasDefault: false }]
+    };
+    const cs = diffBoth(entity as any, spec);
+    expect(cs.renamed[0]!.definitionChanged).toBe(true);
+    expect(cs.renamed[0]!.modifiedFields).toEqual(['type']);
+    expect(cs.modified).toEqual([]); // 单归属：不在 renamed 之外重复记账
+  });
+
+  it('完全无关的名称不构成改名', () => {
+    const entity = {
+      name: 't',
+      comment: '',
+      columns: [{ name: 'aaa', type: 'int', nullable: false }]
+    };
+    const spec: TableSpec = {
+      name: 't',
+      comment: '',
+      primaryKey: [],
+      columns: [{ name: 'zzz', type: 'INT', nullable: false, hasDefault: false }]
+    };
+    const cs = diffBoth(entity as any, spec);
+    expect(cs.renamed).toEqual([]);
+    expect(cs.added.map((c) => c.name)).toEqual(['zzz']);
+    expect(cs.dropped).toEqual(['aaa']);
+  });
+});
+
+describe('列级与表级', () => {
+  it('类型参数变化：fields 恰为 [type]', () => {
+    const entity = baseEntity();
+    const spec = mirrorSpec(entity);
+    spec.columns[1] = { ...spec.columns[1]!, length: 128 } as TableSpec['columns'][number];
+    const cs = diffBoth(entity, spec);
+    expect(cs.modified).toHaveLength(1);
+    expect(cs.modified[0]!.name).toBe('name');
+    expect(cs.modified[0]!.fields).toEqual(['type']);
+  });
+
+  it('DEFAULT 0 → 无默认：是真实变更，必须检出（旧代码会因空值兜底漏检）', () => {
+    const entity = baseEntity();
+    const spec = mirrorSpec(entity);
+    spec.columns[2] = {
+      ...spec.columns[2]!, hasDefault: false
+    } as TableSpec['columns'][number];
+    const cs = diffBoth(entity, spec);
+    expect(cs.modified[0]!.fields).toEqual(['default']);
+  });
+
+  it('改表名 / 改表注释', () => {
+    const entity = baseEntity();
+    const spec = mirrorSpec(entity);
+    spec.name = 'users_v2';
+    spec.comment = '新注释';
+    const cs = diffBoth(entity, spec);
+    expect(cs.rename).toEqual({ from: 'users', to: 'users_v2' });
+    expect(cs.comment).toEqual({ from: '用户表', to: '新注释' });
+    expect(cs.modified).toEqual([]);
+  });
+
+  it('增列 / 删列', () => {
+    const entity = baseEntity();
+    const spec = mirrorSpec(entity);
+    spec.columns.push({
+      name: 'email', type: 'VARCHAR', length: 128, nullable: true, hasDefault: false
+    } as TableSpec['columns'][number]);
+    let cs = diffBoth(entity, spec);
+    expect(cs.added.map((c) => c.name)).toEqual(['email']);
+
+    const spec2 = mirrorSpec(entity);
+    spec2.columns = spec2.columns.filter((c) => c.name !== 'age');
+    cs = diffBoth(entity, spec2);
+    expect(cs.dropped).toEqual(['age']);
+  });
+
+  it('幸存列顺序变化：orderChanged=true 且不产生列级变更', () => {
+    const entity = {
+      name: 't',
+      comment: '',
+      columns: [
+        { name: 'a', type: 'int', nullable: true },
+        { name: 'b', type: 'int', nullable: true },
+        { name: 'c', type: 'int', nullable: true }
+      ]
+    };
+    const spec: TableSpec = {
+      name: 't',
+      comment: '',
+      primaryKey: [],
+      columns: [
+        { name: 'a', type: 'INT', nullable: true, hasDefault: false },
+        { name: 'c', type: 'INT', nullable: true, hasDefault: false },
+        { name: 'b', type: 'INT', nullable: true, hasDefault: false }
+      ]
+    };
+    const cs = diffBoth(entity as any, spec);
+    expect(cs.orderChanged).toBe(true);
+    expect(cs.columnOrder).toEqual(['a', 'c', 'b']);
+    expect(cs.modified).toEqual([]);
+    expect(cs.added).toEqual([]);
+    expect(cs.dropped).toEqual([]);
+  });
+});
+
+describe('幂等', () => {
+  it('diffTable(x, x) 为空', () => {
+    const entity = baseEntity();
+    const c = canonicalizeTableEntity(entity);
+    expect(isEmptyChangeSet(diffTable(c, c))).toBe(true);
+  });
+});

package/dist/server/core/schema/__tests__/roundtrip.property.test.ts

@@ -0,0 +1,403 @@
+import { describe, expect, it } from 'vitest';
+import { canonicalizeTableEntity, canonicalizeTableSpec } from '../canonical';
+import { diffTable } from '../diff';
+import { isEmptyChangeSet } from '../../../model/ddl-spec';
+import type { CanonicalTable, TableSpec } from '../../../model/ddl-spec';
+
+/**
+ * 属性测试：任何「改了又改回」的操作序列，diff 必须为空（幂等由纯函数保证）。
+ * 使用固定种子的确定性 PRNG（mulberry32），失败时输出种子与操作序列，可精确复现。
+ */
+
+function mulberry32(seed: number): () => number {
+  return function () {
+    seed |= 0;
+    seed = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const SEED = 0xc0ffee;
+const NAME_POOL = ['id', 'name', 'created_at', 'amount', 'status', 'user_id', 'remark'];
+const TYPE_ENTRIES = [
+  { entity: 'varchar(255)', spec: { type: 'VARCHAR', length: 255 } },
+  { entity: 'int', spec: { type: 'INT' } },
+  { entity: 'decimal(10,0)', spec: { type: 'DECIMAL', precision: 10, scale: 0 } },
+  { entity: 'text', spec: { type: 'TEXT' } },
+  { entity: 'date', spec: { type: 'DATE' } },
+  { entity: "enum('x','y')", spec: { type: 'ENUM', customType: "enum('x','y')" } }
+] as const;
+const DEFAULT_POOL: Array<undefined | 0 | '' | 'NULL' | 'abc' | 'CURRENT_TIMESTAMP' | '0.50'> = [
+  undefined, 0, '', 'NULL', 'abc', 'CURRENT_TIMESTAMP', '0.50'
+];
+
+interface EntityCol {
+  name: string;
+  type: string;
+  nullable: boolean;
+  isPrimary?: boolean;
+  isAutoIncrement?: boolean;
+  defaultValue?: unknown;
+  comment?: string;
+}
+
+function genEntity(rand: () => number) {
+  const n = 2 + Math.floor(rand() * 4);
+  const names = NAME_POOL.slice(0, n);
+  const pkCount = rand() < 0.2 ? 0 : 1 + Math.floor(rand() * 2);
+  const pkNames = new Set(names.slice(0, Math.min(pkCount, n)));
+  const columns: EntityCol[] = names.map((name, i) => {
+    const entry = TYPE_ENTRIES[Math.floor(rand() * TYPE_ENTRIES.length)]!;
+    const def = DEFAULT_POOL[Math.floor(rand() * DEFAULT_POOL.length)];
+    return {
+      name,
+      type: entry.entity,
+      nullable: !pkNames.has(name),
+      isPrimary: pkNames.has(name),
+      isAutoIncrement: pkNames.has(name) && i === 0 && rand() < 0.5,
+      defaultValue: def,
+      comment: rand() < 0.5 ? `备注${i}` : `  备注${i}  `
+    };
+  });
+  return { name: 'rnd_table', comment: ' 随机表 ', columns };
+}
+
+/** canonical → TableSpec：Phase E 前端要做的「等价回显」 */
+function toSpec(t: CanonicalTable): TableSpec {
+  return {
+    name: t.name,
+    comment: t.comment,
+    columns: t.columns.map((c) => {
+      const full = c.baseType.includes('(');
+      return {
+        name: c.name,
+        ...(full
+          ? { type: c.baseType, customType: c.baseType }
+          : { type: c.baseType, length: c.length, precision: c.precision, scale: c.scale }),
+        nullable: c.nullable,
+        hasDefault: c.defaultKind !== 'none',
+        defaultValue:
+          c.defaultKind === 'none' ? undefined : c.defaultKind === 'null' ? 'NULL' : c.defaultText,
+        autoIncrement: c.rawAutoIncrement,
+        comment: c.comment
+      };
+    }),
+    primaryKey: t.primaryKey.slice()
+  };
+}
+
+interface Mutation {
+  label: string;
+  revert: (spec: TableSpec) => void;
+}
+
+function replaceCol(spec: TableSpec, name: string, next: TableSpec['columns'][number]): void {
+  const i = spec.columns.findIndex((c) => c.name === name);
+  if (i >= 0) spec.columns[i] = next;
+}
+
+function mutate(spec: TableSpec, rand: () => number, counter: { n: number }): Mutation {
+  const kind = Math.floor(rand() * 9);
+  const cols = () => spec.columns;
+  const pick = () => cols()[Math.floor(rand() * cols().length)]!;
+
+  switch (kind) {
+    case 0: {
+      // 勾选/取消主键
+      const col = pick();
+      const wasIn = spec.primaryKey.includes(col.name);
+      const prevPk = spec.primaryKey.slice();
+      spec.primaryKey = wasIn
+        ? spec.primaryKey.filter((n) => n !== col.name)
+        : [...spec.primaryKey, col.name];
+      return { label: `togglePk(${col.name})`, revert: (s) => (s.primaryKey = prevPk.slice()) };
+    }
+    case 1: {
+      const col = pick();
+      const prev = col.nullable;
+      replaceCol(spec, col.name, { ...col, nullable: !prev });
+      return {
+        label: `flipNullable(${col.name})`,
+        revert: (s) => replaceCol(s, col.name, { ...col })
+      };
+    }
+    case 2: {
+      const col = pick();
+      const entry = TYPE_ENTRIES[Math.floor(rand() * TYPE_ENTRIES.length)]!;
+      const next = { ...col, ...entry.spec } as TableSpec['columns'][number];
+      replaceCol(spec, col.name, next);
+      return {
+        label: `changeType(${col.name} -> ${JSON.stringify(entry.spec)})`,
+        revert: (s) => replaceCol(s, col.name, { ...col })
+      };
+    }
+    case 3: {
+      const col = pick();
+      const prev = { hasDefault: col.hasDefault, defaultValue: col.defaultValue };
+      const raw = DEFAULT_POOL[Math.floor(rand() * DEFAULT_POOL.length)]!;
+      const next =
+        raw === undefined
+          ? { ...col, hasDefault: false, defaultValue: undefined }
+          : { ...col, hasDefault: true, defaultValue: raw };
+      replaceCol(spec, col.name, next as TableSpec['columns'][number]);
+      return {
+        label: `setDefault(${col.name}, ${String(raw)})`,
+        revert: (s) => replaceCol(s, col.name, { ...col, ...prev } as TableSpec['columns'][number])
+      };
+    }
+    case 4: {
+      const col = pick();
+      const prev = col.comment;
+      const next = rand() < 0.5 ? '  新注释  ' : '';
+      replaceCol(spec, col.name, { ...col, comment: next } as TableSpec['columns'][number]);
+      return {
+        label: `setComment(${col.name})`,
+        revert: (s) => replaceCol(s, col.name, { ...col, comment: prev } as TableSpec['columns'][number])
+      };
+    }
+    case 5: {
+      const name = `zz_new_${counter.n++}`;
+      spec.columns.push({
+        name,
+        type: 'VARCHAR',
+        length: 64,
+        nullable: true,
+        hasDefault: false,
+        comment: ''
+      });
+      return {
+        label: `addCol(${name})`,
+        revert: (s) => {
+          s.columns = s.columns.filter((c) => c.name !== name);
+        }
+      };
+    }
+    case 6: {
+      const candidates = spec.columns.filter(
+        (c) => !spec.primaryKey.includes(c.name) && !c.name.startsWith('zz_new_')
+      );
+      if (candidates.length === 0) return mutate(spec, rand, counter);
+      const col = candidates[Math.floor(rand() * candidates.length)]!;
+      const idx = spec.columns.findIndex((c) => c.name === col.name);
+      spec.columns.splice(idx, 1);
+      return {
+        label: `removeCol(${col.name})`,
+        revert: (s) => {
+          s.columns.splice(Math.min(idx, s.columns.length), 0, col);
+        }
+      };
+    }
+    case 7: {
+      const col = pick();
+      const wasInPk = spec.primaryKey.includes(col.name);
+      const prevPk = spec.primaryKey.slice();
+      const newName = `${col.name}_v2`;
+      replaceCol(spec, col.name, { ...col, name: newName });
+      spec.primaryKey = spec.primaryKey.map((n) => (n === col.name ? newName : n));
+      return {
+        label: `renameCol(${col.name} -> ${newName})`,
+        revert: (s) => {
+          replaceCol(s, newName, { ...col });
+          s.primaryKey = prevPk.slice();
+        }
+      };
+    }
+    default: {
+      const col = pick();
+      const next = { ...col, autoIncrement: !col.autoIncrement };
+      replaceCol(spec, col.name, next);
+      return {
+        label: `toggleAutoIncrement(${col.name})`,
+        revert: (s) => replaceCol(s, col.name, { ...col })
+      };
+    }
+  }
+}
+
+describe('属性：往返幂等', () => {
+  it('任意随机 UI 操作序列全部撤销后，diff 必须为空（200 组）', () => {
+    for (let i = 0; i < 200; i++) {
+      const rand = mulberry32(SEED + i);
+      const entity = genEntity(rand);
+      const canon = canonicalizeTableEntity(entity);
+      const spec = toSpec(canon);
+      const counter = { n: 0 };
+      const mutations: Mutation[] = [];
+      const k = 1 + Math.floor(rand() * 8);
+      for (let j = 0; j < k; j++) mutations.push(mutate(spec, rand, counter));
+
+      const cs = diffTable(canon, canonicalizeTableSpec(spec));
+      if (!isEmptyChangeSet(cs)) {
+        // 有变更属正常；继续撤销后再验证
+      }
+      for (let j = mutations.length - 1; j >= 0; j--) mutations[j]!.revert(spec);
+
+      const csFinal = diffTable(canon, canonicalizeTableSpec(spec));
+      if (!isEmptyChangeSet(csFinal)) {
+        throw new Error(
+          `往返后 diff 非空 [seed=${SEED + i}] ops=${mutations.map((m) => m.label).join(' -> ')} :: ${JSON.stringify(csFinal)}`
+        );
+      }
+    }
+  });
+
+  it('「实体 → canonical → 回显」零 diff（Phase E 前端回显的契约，200 组）', () => {
+    for (let i = 0; i < 200; i++) {
+      const rand = mutaberryOf(SEED * 31 + i);
+      const entity = genEntity(rand);
+      const canon = canonicalizeTableEntity(entity);
+      const cs = diffTable(canon, canonicalizeTableSpec(toSpec(canon)));
+      if (!isEmptyChangeSet(cs)) {
+        throw new Error(
+          `回显产生假 diff [seed=${SEED * 31 + i}] :: ${JSON.stringify(entity)} :: ${JSON.stringify(cs)}`
+        );
+      }
+    }
+  });
+});
+
+function mutaberryOf(seed: number): () => number {
+  return mulberry32(seed);
+}
+
+describe('属性：单维度记账（每处变更恰好出现一次）', () => {
+  const cases = [1, 2, 3, 42, 777, 2026];
+
+  it('每个单点变更只落在它唯一的桶里', () => {
+    for (const i of cases) {
+      const rand = mulberry32(SEED * 7 + i);
+      const entity = genEntity(rand);
+      const canon = canonicalizeTableEntity(entity);
+      const spec = toSpec(canon);
+
+      let s: TableSpec;
+      const check = (cs: ReturnType<typeof diffTable>, expect_: (cs: ReturnType<typeof diffTable>) => void, label: string) => {
+        try {
+          expect_(cs);
+        } catch (e) {
+          throw new Error(`[seed=${SEED * 7 + i}] ${label} :: ${JSON.stringify(cs)}\n${(e as Error).message}`);
+        }
+      };
+
+      // -- togglePk：primaryKey 桶；若有列级联动，仅允许 autoIncrement 字段且列为主键成员变化者
+      s = { ...spec, columns: spec.columns.slice(), primaryKey: spec.primaryKey.slice() };
+      const target = s.columns[0]!;
+      const wasIn = s.primaryKey.includes(target.name);
+      s.primaryKey = wasIn
+        ? s.primaryKey.filter((n) => n !== target.name)
+        : [...s.primaryKey, target.name];
+      check(
+        diffTable(canon, canonicalizeTableSpec(s)),
+        (cs) => {
+          expect(cs.added).toEqual([]);
+          expect(cs.dropped).toEqual([]);
+          expect(cs.renamed).toEqual([]);
+          expect(cs.comment).toBeNull();
+          expect(cs.rename).toBeNull();
+          expect(cs.modified.every((mm) => mm.fields.every((f) => f === 'autoIncrement'))).toBe(true);
+        },
+        `togglePk(${target.name})`
+      );
+
+      // -- flipNullable：仅 modified.fields 含 'nullable'
+      s = { ...spec, columns: spec.columns.slice(), primaryKey: spec.primaryKey.slice() };
+      replaceCol(s, s.columns[0]!.name, { ...s.columns[0]!, nullable: !s.columns[0]!.nullable });
+      check(
+        diffTable(canon, canonicalizeTableSpec(s)),
+        (cs) => {
+          expect(cs.added).toEqual([]);
+          expect(cs.dropped).toEqual([]);
+          expect(cs.renamed).toEqual([]);
+          expect(cs.primaryKey).toBeNull();
+          cs.modified.forEach((mm) =>
+            expect(mm.fields.every((f) => f === 'nullable')).toBe(true)
+          );
+        },
+        'flipNullable'
+      );
+
+      // -- changeType：仅 modified.fields 含 'type'（可联动 autoIncrement）；选一个必然不同的类型
+      s = { ...spec, columns: spec.columns.slice(), primaryKey: spec.primaryKey.slice() };
+      {
+        const c0 = s.columns[0]!;
+        const nextType = c0.type === 'TEXT' && !c0.customType ? 'BIGINT' : 'TEXT';
+        replaceCol(s, c0.name, {
+          ...c0,
+          type: nextType,
+          length: undefined,
+          precision: undefined,
+          scale: undefined,
+          customType: undefined
+        } as TableSpec['columns'][number]);
+      }
+      check(
+        diffTable(canon, canonicalizeTableSpec(s)),
+        (cs) => {
+          expect(cs.added).toEqual([]);
+          expect(cs.dropped).toEqual([]);
+          expect(cs.renamed).toEqual([]);
+          expect(cs.primaryKey).toBeNull();
+          expect(cs.modified.length).toBe(1);
+          expect(cs.modified[0]!.fields[0]).toBe('type');
+          expect(cs.modified[0]!.fields.every((f) => f === 'type' || f === 'autoIncrement')).toBe(true);
+        },
+        'changeType'
+      );
+
+      // -- rename：仅 renamed 桶
+      s = { ...spec, columns: spec.columns.slice(), primaryKey: spec.primaryKey.slice() };
+      const r0 = s.columns[0]!;
+      const r0InPk = s.primaryKey.includes(r0.name);
+      const r0New = `${r0.name}_v2`;
+      replaceCol(s, r0.name, { ...r0, name: r0New });
+      if (r0InPk) s.primaryKey = s.primaryKey.map((n) => (n === r0.name ? r0New : n));
+      check(
+        diffTable(canon, canonicalizeTableSpec(s)),
+        (cs) => {
+          expect(cs.added).toEqual([]);
+          expect(cs.dropped).toEqual([]);
+          expect(cs.modified).toEqual([]);
+          expect(cs.primaryKey).toBeNull();
+          expect(cs.renamed).toEqual([
+            { from: r0.name, to: r0New, definitionChanged: false, modifiedFields: [] }
+          ]);
+        },
+        `renameCol(${r0.name})`
+      );
+
+      // -- addCol / removeCol：仅 added / dropped
+      s = { ...spec, columns: spec.columns.slice(), primaryKey: spec.primaryKey.slice() };
+      s.columns.push({
+        name: 'zz_chk_add', type: 'VARCHAR', length: 8, nullable: true, hasDefault: false, comment: ''
+      });
+      check(
+        diffTable(canon, canonicalizeTableSpec(s)),
+        (cs) => {
+          expect(cs.added.map((c) => c.name)).toEqual(['zz_chk_add']);
+          expect(cs.dropped).toEqual([]);
+          expect(cs.modified).toEqual([]);
+        },
+        'addCol'
+      );
+
+      s = { ...spec, columns: spec.columns.slice(), primaryKey: spec.primaryKey.slice() };
+      const removable = s.columns.find(
+        (c) => !s.primaryKey.includes(c.name) && !c.name.startsWith('zz_')
+      );
+      if (removable) {
+        s.columns = s.columns.filter((c) => c.name !== removable.name);
+        check(
+          diffTable(canon, canonicalizeTableSpec(s)),
+          (cs) => {
+            expect(cs.dropped).toEqual([removable.name]);
+            expect(cs.added).toEqual([]);
+            expect(cs.renamed).toEqual([]);
+          },
+          `removeCol(${removable.name})`
+        );
+      }
+    }
+  });
+});

package/dist/server/core/schema/canonical.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 归一化投影：把「数据库实体形状」和「前端表单形状」投影到同一个 CanonicalTable。
+ *
+ * 目标：表示差异不产生假 diff——
+ *   'varchar(255)' 与 { type:'VARCHAR', length:'255' } 等价；
+ *   0 / '0'、'' / DEFAULT ''、'NULL' / DEFAULT NULL / 无默认值 三态可区分且各自恒等；
+ *   注释前后空格、数值字面量的 '007'/'0.50' 等书写差异被消除。
+ *
+ * 不变式：canonicalize 是纯函数且幂等（对已是 canonical 形状的对象无副作用）。
+ * rawAutoIncrement 不做 clamp（保留原始意图，供"加主键时恢复自增"），
+ * effectiveAutoIncrement 按「自增必须依附主键」派生——两侧同一规则，比较恒稳。
+ */
+import type { CanonicalColumn, CanonicalTable, DefaultKind, TableSpec } from '../../model/ddl-spec';
+/** 数值字面量归一：'007'→'7'，'0.50'→'0.5'，'-0'→'0'（字符串实现，避免大数精度损失） */
+export declare function normalizeNumericLiteral(s: string): string;
+/**
+ * 默认值三态+表达式分类。
+ * @param raw      原始值（实体侧：driver 原样，可能是 0/''/'NULL'/null；表单侧：文本）
+ * @param hasDefault 表单侧显式标记；实体侧不传（undefined 表示未知，按 raw 推断）
+ */
+export declare function classifyDefault(raw: unknown, hasDefault?: boolean): {
+    kind: DefaultKind;
+    text: string;
+};
+/** 类型归一：接受 { type:'varchar(255)', length:255 } 或 { type:'VARCHAR', length:'255' } 或 customType 全串 */
+export declare function canonicalizeType(input: {
+    type?: string;
+    customType?: string;
+    length?: number | string | null;
+    precision?: number | string | null;
+    scale?: number | string | null;
+}): {
+    baseType: string;
+    length?: number;
+    precision?: number;
+    scale?: number;
+};
+type LooseColumn = Record<string, any>;
+/** 数据库实体侧（live 结构 / getColumns 结果）→ CanonicalTable */
+export declare function canonicalizeTableEntity(table: {
+    name?: string;
+    comment?: string;
+    columns?: LooseColumn[];
+}): CanonicalTable;
+/** 前端目标侧（TableSpec）→ CanonicalTable */
+export declare function canonicalizeTableSpec(spec: TableSpec): CanonicalTable;
+/** 列定义（不含列名、不含主键）是否等价；返回发生变化的维度集合 */
+export declare function diffColumnFields(before: CanonicalColumn, after: CanonicalColumn): Array<'type' | 'nullable' | 'default' | 'comment' | 'autoIncrement'>;
+export {};
+//# sourceMappingURL=canonical.d.ts.map