《移动游戏产品的架构·客户端与移动运行时》5.3 策划工作流：从表格到线上

// file: src/config/version-migrate.ts
// tier: L1
// verify: node --test test/config/version-migrate.test.ts

import type { Clock } from "../core/clock.ts";
import { fail, ok, type Result } from "../core/result.ts";
import type { ConfigTableName } from "./schema.ts";
import { CONFIG_TABLES, type ConfigRow, type ConfigSet, type ValidationReport } from "./table.ts";

export interface Migration {
  readonly from: number;
  readonly to: number;
  readonly migrate: (table: ConfigTableName, row: ConfigRow) => ConfigRow;
}

function renamed(row: ConfigRow, from: string, to: string): ConfigRow {
  const next: Record<string, unknown> = { ...row };
  if (!(from in next)) return next;
  next[to] = next[from];
  delete next[from];
  return next;
}

export const ARK_MIGRATIONS: readonly Migration[] = [
  {
    from: 1,
    to: 2,
    migrate(table, row) {
      if (table === "level") return renamed(row, "enemies", "enemyCardIds");
      if (table === "card") return renamed(row, "power", "attack");
      return { ...row };
    },
  },
  {
    from: 2,
    to: 3,
    migrate(table, row) {
      const next: Record<string, unknown> = { ...row };
      if (table === "card" && next.rarity === "normal") next.rarity = "common";
      if (table === "activity" && typeof next.enabled === "boolean") {
        next.status = next.enabled ? "live" : "draft";
        delete next.enabled;
      }
      return next;
    },
  },
];

export function migrationPath(from: number, to: number, migrations: readonly Migration[] = ARK_MIGRATIONS): Result<readonly Migration[], string> {
  if (!Number.isInteger(from) || !Number.isInteger(to) || from < 1 || to < 1) {
    return fail("invalid-version", `versions must be positive integers: v${from} -> v${to}`);
  }
  if (to < from) {
    return fail("no-downgrade", `cannot migrate v${from} down to v${to}; restore the previous artifact instead`);
  }
  const path: Migration[] = [];
  let current = from;
  while (current < to) {
    const step = migrations.find((candidate) => candidate.from === current && candidate.to <= to);
    if (step === undefined) return fail("missing-migration", `no migration step from v${current} toward v${to}`);
    path.push(step);
    current = step.to;
    if (path.length > migrations.length) return fail("migration-loop", "migration graph does not terminate");
  }
  return ok(path);
}

export function migrateSet(set: ConfigSet, targetVersion: number, migrations: readonly Migration[] = ARK_MIGRATIONS): Result<ConfigSet, string> {
  const path = migrationPath(set.schemaVersion, targetVersion, migrations);
  if (!path.ok) return fail(path.error, path.reason);
  let tables: Readonly<Record<ConfigTableName, readonly ConfigRow[]>> = set.tables;
  for (const step of path.value) {
    const next: Record<ConfigTableName, readonly ConfigRow[]> = { level: [], card: [], activity: [] };
    for (const table of CONFIG_TABLES) next[table] = tables[table].map((row) => step.migrate(table, row));
    tables = next;
  }
  return ok({ ...set, schemaVersion: targetVersion, tables });
}

export type DiffRisk = "low" | "high";
export interface TableDiff { readonly table: ConfigTableName; readonly added: readonly string[]; readonly removed: readonly string[]; readonly changed: readonly string[]; }
export interface BundleDiff { readonly tables: readonly TableDiff[]; readonly risk: DiffRisk; readonly changedRows: number; }
export interface DiffPolicy { readonly highRiskTables: readonly ConfigTableName[]; }

export const ARK_DIFF_POLICY: DiffPolicy = { highRiskTables: ["card", "activity"] };

function rowKey(row: ConfigRow): string {
  return typeof row.id === "string" ? row.id : "<missing-id>";
}

function canonical(row: ConfigRow): string {
  const keys = Object.keys(row).sort();
  return JSON.stringify(keys.map((key) => [key, row[key]]));
}

export function diffSets(before: ConfigSet, after: ConfigSet, policy: DiffPolicy = ARK_DIFF_POLICY): BundleDiff {
  const tables = CONFIG_TABLES.map((table) => {
    const beforeRows = new Map(before.tables[table].map((row) => [rowKey(row), row]));
    const afterRows = new Map(after.tables[table].map((row) => [rowKey(row), row]));
    const added: string[] = [];
    const removed: string[] = [];
    const changed: string[] = [];
    for (const [id, row] of afterRows) {
      const previous = beforeRows.get(id);
      if (previous === undefined) added.push(id);
      else if (canonical(previous) !== canonical(row)) changed.push(id);
    }
    for (const id of beforeRows.keys()) if (!afterRows.has(id)) removed.push(id);
    return { table, added: added.sort(), removed: removed.sort(), changed: changed.sort() };
  });
  const changedRows = tables.reduce((sum, table) => sum + table.added.length + table.removed.length + table.changed.length, 0);
  const highRisk = tables.some(
    (table) => table.removed.length > 0 || (policy.highRiskTables.includes(table.table) && table.added.length + table.changed.length > 0),
  );
  return { tables, risk: highRisk ? "high" : "low", changedRows };
}

export type ReleaseState = "imported" | "validated" | "reviewed" | "canary" | "live" | "rolled-back";
export interface AuditEntry { readonly state: ReleaseState; readonly atMs: number; readonly actor: string; readonly note: string; }

export class ReleasePipeline {
  readonly #clock: Clock;
  readonly #version: number;
  readonly #previousLiveVersion: number | null;
  readonly #history: AuditEntry[] = [];
  readonly #reviewers = new Set<string>();
  #state: ReleaseState = "imported";

  constructor(clock: Clock, version: number, previousLiveVersion: number | null = null) {
    if (!Number.isInteger(version) || version < 1) throw new RangeError(`config version must be a positive integer: ${version}`);
    this.#clock = clock;
    this.#version = version;
    this.#previousLiveVersion = previousLiveVersion;
    this.#history.push({ state: "imported", atMs: clock.nowMs(), actor: "import", note: `config v${version} imported` });
  }

  get state(): ReleaseState { return this.#state; }
  get version(): number { return this.#version; }
  get previousLiveVersion(): number | null { return this.#previousLiveVersion; }
  get history(): readonly AuditEntry[] { return [...this.#history]; }

  #record(state: ReleaseState, actor: string, note: string): void {
    this.#state = state;
    this.#history.push({ state, atMs: this.#clock.nowMs(), actor, note });
  }

  #note(actor: string, note: string): void {
    this.#history.push({ state: this.#state, atMs: this.#clock.nowMs(), actor, note });
  }

  validate(report: ValidationReport, actor = "ci"): Result<ReleaseState, string> {
    if (this.#state !== "imported") return fail("illegal-transition", `validate requires imported, got ${this.#state}`);
    if (!report.ok) return fail("validation-failed", `refusing a report with ${report.errorCount} errors`);
    this.#record("validated", actor, `${report.errorCount} errors`);
    return ok(this.#state);
  }

  review(reviewer: string, diff: BundleDiff): Result<ReleaseState, string> {
    if (this.#state !== "validated") return fail("illegal-transition", `review requires validated, got ${this.#state}`);
    const name = reviewer.trim();
    if (name.length === 0) return fail("reviewer-required", "reviewer must not be empty");
    if (this.#reviewers.has(name)) return fail("duplicate-reviewer", `${name} has already reviewed this release`);
    this.#reviewers.add(name);
    const required = diff.risk === "high" ? 2 : 1;
    if (this.#reviewers.size < required) {
      this.#note(name, `review ${this.#reviewers.size}/${required}; risk=${diff.risk}`);
      return ok(this.#state);
    }
    this.#record("reviewed", name, `${this.#reviewers.size} reviewers; risk=${diff.risk}; ${diff.changedRows} changed rows`);
    return ok(this.#state);
  }

  startCanary(actor = "release"): Result<ReleaseState, string> {
    if (this.#state !== "reviewed") return fail("illegal-transition", `canary requires reviewed, got ${this.#state}`);
    this.#record("canary", actor, "canary started");
    return ok(this.#state);
  }

  promote(actor = "release"): Result<ReleaseState, string> {
    if (this.#state !== "canary") return fail("illegal-transition", `promote requires canary, got ${this.#state}`);
    this.#record("live", actor, `config v${this.#version} is live`);
    return ok(this.#state);
  }

  rollback(actor: string, reason: string): Result<number, string> {
    if (this.#state !== "canary" && this.#state !== "live") {
      return fail("illegal-transition", `rollback requires canary or live, got ${this.#state}`);
    }
    if (reason.trim().length === 0) return fail("reason-required", "rollback needs a recorded reason");
    if (this.#previousLiveVersion === null) return fail("no-previous-release", "no previous live version to roll back to");
    this.#record("rolled-back", actor, `rollback to v${this.#previousLiveVersion}: ${reason}`);
    return ok(this.#previousLiveVersion);
  }
}