第16章 - 存档-进度与报告导入导出

export interface SaveData {
  schemaVersion: number;
  updatedAt: number;
  profile: {
    id: string;
    nickname: string;
    startBand: string;
    createdAt: number;
  };
  levels: Record<LevelId, LevelProgress>;
  tools: Record<ToolId, ToolUsage>;
  badges: Partial<Record<BadgeId, BadgeAward>>;
  journal: JournalEntry[];
}

// packages/progress/src/save.ts（节选）
/**
 * 读档迁移：任何旧版本（含没有版本号的历史档）都只补字段、不清空；
 * 只有 schemaVersion 大于当前版本（来自未来）才回空档。
 * 永不抛错：无法识别的输入一律回空档。
 */
export function migrate(raw: unknown, now: number): SaveData {
  const fallback = emptySave(now);
  const parsed = parseRaw(raw);
  if (!isRecord(parsed)) return fallback;

  const rawVersion = isFiniteNumber(parsed.schemaVersion)
    ? Math.trunc(parsed.schemaVersion)
    : null;
  if (rawVersion !== null && rawVersion > SAVE_SCHEMA_VERSION) return fallback;

  const rawLevels = isRecord(parsed.levels) ? parsed.levels : {};
  const levels = {} as Record<LevelId, LevelProgress>;
  for (const levelId of LEVEL_IDS) {
    levels[levelId] = sanitizeLevelProgress(levelId, rawLevels[levelId]);
  }
  // ……tools / badges / journal / profile 同样逐个 sanitize
}

// packages/platform/src/web.ts（节选）
export const MMF_DB_NAME = 'mmf';
export const MMF_KV_STORE = 'kv';
export const SAVE_KEY = 'save:local-default';
export const EVIDENCE_KEY = 'evidence:local-default';
export const AGGREGATE_KEY = 'evagg:local-default';
export const MAX_EVIDENCE_EVENTS = 3000;
const OPEN_TIMEOUT_MS = 3000;

// packages/platform/src/web.ts（节选）
/** kv 后端：IndexedDB 优先，读写失败或打不开时用内存副本兜底。 */
function createKvBackend(): KvBackend {
  const memory = new Map<string, unknown>();
  let dbPromise: Promise<IDBDatabase | null> | null = null;

  function openDb(): Promise<IDBDatabase | null> {
    dbPromise ??= new Promise<IDBDatabase | null>((resolve) => {
      if (typeof indexedDB === 'undefined') { resolve(null); return; }
      // 3 秒超时：开不起来就当没有 IndexedDB
      // ……
    });
    return dbPromise;
  }

  return {
    async read(key: string): Promise<unknown> {
      // 内存副本永远比 IndexedDB 新：本会话写过就以此为准，避免写盘失败后读回旧值。
      if (memory.has(key)) return memory.get(key);
      // ……读 IndexedDB，任何异常返回 null
    },
    async write(key: string, value: unknown): Promise<void> {
      memory.set(key, value);
      const db = await openDb();
      if (!db) return;
      // ……事务写入，失败只吞错：内存副本已生效，本会话继续可用
    },
    // remove 同构
  };
}

// packages/platform/src/web.ts（节选）
append(events: EvidenceEvent[]): Promise<void> {
  return enqueue(async () => {
    const record = await readRecord();
    const existing = record?.events ?? [];
    // id 判重：失败重试不会把仍在记录里的同一事件写两遍。
    const known = new Set(existing.map((event) => event.id));
    // ……过滤坏事件与重复 id，得到 fresh

    // 先按时间排好再裁剪，时钟抖动导致的乱序写入也不会把"最新"当"最旧"删掉。
    const merged = sortByTime([...existing, ...fresh]);
    const overflow = Math.max(0, merged.length - MAX_EVIDENCE_EVENTS);
    const removed = overflow > 0 ? merged.slice(0, overflow) : [];
    const kept = overflow > 0 ? merged.slice(-MAX_EVIDENCE_EVENTS) : merged;
    await kv.write(EVIDENCE_KEY, { version: 1, events: kept } satisfies EvidenceRecord);

    if (removed.length > 0) {
      // 先写明细再写聚合：万一中途掉电，最坏是丢计数，而不是重复计数。
      const aggregate = await readAggregate();
      await kv.write(AGGREGATE_KEY, accumulateAggregate(aggregate, removed));
    }
  });
}

// packages/platform/src/web.ts（节选）
/**
 * 把被裁掉的事件计数并入聚合（docs/02 §8.3、§8.4）：
 * 清理日志只影响能回看的明细，不影响历史计数，报告/徽章不会倒退。
 * 平台包不能依赖 evidence（依赖图见 docs/02 §3.1），所以这里保留一份最小实现。
 */
function accumulateAggregate(
  base: EvidenceAggregate,
  events: readonly EvidenceEvent[],
): EvidenceAggregate {
  const next: EvidenceAggregate = {
    total: base.total,
    byLevel: { ...base.byLevel },
    byTool: { ...base.byTool },
    byPhase: { ...base.byPhase },
    byFailure: { ...base.byFailure },
    lastAggregatedAt: base.lastAggregatedAt,
  };
  for (const event of events) {
    next.total += 1;
    // ……按关卡 / 工具 / 阶段 / 失败类累计，并更新 lastAggregatedAt
  }
  return next;
}

// packages/progress/src/manager.ts（节选）
/**
 * 串行写盘：并发 completeLevel 时后一次写入一定排在前一次之后，磁盘不会回退到旧存档。
 * 写失败只吞掉错误——调用方（关卡反馈）不该因为存储不可用而中断（docs/02 §8.3）。
 */
private persist(next: SaveData): Promise<void> {
  const task = this.writeChain.then(() => this.store.save(next));
  this.writeChain = task.then(
    () => undefined,
    () => undefined,
  );
  return task.catch(() => undefined);
}

// packages/progress/src/manager.ts（节选）
async completeLevel(input: CompletionInput): Promise<SaveData> {
  await this.init();
  if (!input || typeof input !== 'object' || !isKnownLevelId(input.levelId)) {
    // 未知关卡（老内容/写错的 id）不写存档：读档时它本来就会被 migrate 丢掉。
    return this.snapshot();
  }
  // ……
}

// packages/evidence/src/report.ts（节选）
/** 导出包：只保留可公开的短字段，工具 / 关卡 / 维度都收敛成字符串数组。 */
export function toReportPack(report: ReportModel): ReportPack {
  const pack: ReportPack = {
    version: 1,
    generatedAt: report.generatedAt,
    tools: report.tools.map((entry) => ({ tool: entry.tool, uses: entry.uses })),
    levels: report.levels.map((row) => ({
      id: row.levelId,
      title: row.title,
      completed: row.completed,
      stamps: [...row.stamps],
    })),
    dimensions: report.dimensions.map((dimension) => ({
      id: dimension.id,
      band: dimension.band,
      summary: dimension.summary,
    })),
    recommendations: report.recommendations.map((recommendation) => ({
      title: recommendation.title,
      reason: recommendation.reason,
    })),
  };
  if (report.nickname) pack.nickname = report.nickname;
  return pack;
}

// apps/site/src/views/ReportView.vue（节选）
function exportReport(): void {
  if (!report.value) return;
  const pack = toReportPack(report.value);
  platform.files.download('mmf-report.json', 'application/json', JSON.stringify(pack, null, 2));
}

// apps/site/src/views/ReportView.vue（节选）
async function importReport(): Promise<void> {
  importError.value = null;
  try {
    const text = await platform.files.pickText('application/json,.json', 512 * 1024);
    if (!text) return;
    const pack = parseReportPack(JSON.parse(text));
    if (!pack) {
      importError.value = '这个文件不是本机的证据包，或版本不符。';
      return;
    }
    imported.value = pack;
  } catch {
    importError.value = '读取失败：请选择导出的 .json 证据包。';
  }
}

// packages/evidence/src/report.ts（节选）
/** 导入包大小上限（docs/02 §16.2：512 KB）。 */
const MAX_REPORT_PACK_BYTES = 512 * 1024;
/**
 * 禁止 HTML 片段与脚本 URL：渲染层不 v-html，导入层也不接受（docs/02 §16.2）。
 * 只匹配"像标签"或脚本协议的内容；数学里的 "a < b" 不会被误杀。
 */
const MARKUP_PATTERN = /<\s*\/?\s*[a-z][^<>]*>|<!--|javascript:|vbscript:|data:text\/html/i;

// packages/progress/src/manager.ts（节选）
/** 清档：存档回空档、证据与聚合一并清空。 */
async clear(): Promise<SaveData> {
  await this.init();
  const at = this.clock();
  const empty = emptySave(at);
  this.current = empty;
  await this.persist(empty);
  await this.evidence.clear();
  this.revisionBatches.clear();
  return this.snapshot();
}

// packages/platform/src/web.ts（节选）
clear(): Promise<void> {
  return enqueue(async () => {
    await kv.remove(EVIDENCE_KEY);
    await kv.remove(AGGREGATE_KEY);
  });
}