@longzai-intelligence-issues/ledger 0.0.1 → 0.0.2

package/src/migrate/migrate-legacy.core.ts

@@ -0,0 +1,812 @@
+/**
+ * migrate-legacy 纯变换核（无 IO，可测性单一来源）
+ *
+ * 五方言解析（含表格）→ 字段别名 → pre-emoji 状态词规范化 → H1 编号规范 →
+ * 处置段标题链对齐 → 必填元信息回填。全部变换可幂等重放，变换台账逐条记录，
+ * 供命令层零丢失守卫与人工复核消费。
+ */
+
+import { parseHeaderDialect } from '@/normalize/normalize-header.commands';
+import {
+  CANONICAL_STATUS_LABELS,
+  classifyStatusLine,
+  DISPOSITION_PLACEHOLDER_PATTERN,
+  DISPOSITION_PLACEHOLDER_WINDOW_LINES,
+  LEGACY_STATUS_VOCABULARY,
+} from '@/parser/format.utils';
+
+/**
+ * 单文件迁移变换台账条目
+ */
+export type MigrationTransformation = {
+  /**
+   * 变换类别（人工复核消费的稳定标识）
+   */
+  kind:
+    | 'status-canonicalized'
+    | 'status-downgraded-placeholder'
+    | 'field-alias'
+    | 'priority-mapped'
+    | 'priority-backfilled'
+    | 'h1-numbered'
+    | 'disposition-renamed'
+    | 'disposition-appended'
+    | 'required-backfilled';
+
+  /**
+   * 变换说明（原值 → 新值）
+   */
+  detail: string;
+};
+
+/**
+ * 纯变换产物
+ */
+export type MigrateCoreResult = {
+  /**
+   * 迁移形态
+   */
+  outcome: 'rewritten' | 'unchanged' | 'skipped';
+
+  /**
+   * 产物全文（skipped 时为原文）
+   */
+  content: string;
+
+  /**
+   * skip/unchanged 说明
+   */
+  message: string;
+
+  /**
+   * 变换台账（rewritten 时非空）
+   */
+  transformations: MigrationTransformation[];
+};
+
+/**
+ * 迁移选项（引擎零仓库知识——仓库特有缺省值全部经入参注入）
+ */
+export type MigrateCoreOptions = {
+  /**
+   * 编号（文件名前缀，H1 规范化用）
+   */
+  number: string;
+
+  /**
+   * 所属域回填值（scope title）
+   */
+  scopeTitle: string;
+
+  /**
+   * 优先级缺省（原案无优先级与严重程度时回填）
+   */
+  defaultPriority?: 'P1' | 'P2' | 'P3';
+
+  /**
+   * 来源回填缺省文案
+   */
+  defaultSource?: string;
+
+  /**
+   * 立案日期回填缺省（原案无日期字段时；未给则 skipped 交人工）
+   */
+  defaultFilingDate?: string;
+
+  /**
+   * 无状态行历史文档的显式灯位注入（--status；灯位属语义判断由操作者定档，
+   * 引擎仅承接机械迁移。红/绿两态——黄灯须 ≥4 字挂起原因不适用固定文案注入，
+   * 冻结唯一合法路径是 freeze 命令）
+   */
+  status?: 'red' | 'green';
+};
+
+/**
+ * 状态词匹配产物
+ */
+type StatusWordMatch = {
+  /**
+   * 词表档位
+   */
+  tier: 'green' | 'red' | 'deferred' | 'canceled' | 'inProgress' | 'frozen';
+
+  /**
+   * 命中词
+   */
+  word: string;
+};
+
+/**
+ * 状态值规范化产物
+ */
+type CanonicalStatusValue = {
+  /**
+   * 规范状态值（五态灯位 + 溯源括注）
+   */
+  value: string;
+
+  /**
+   * 词表档位
+   */
+  tier: StatusWordMatch['tier'];
+
+  /**
+   * 命中词（原词溯源）
+   */
+  word: string;
+};
+
+/**
+ * 清理字段值（去首尾空白与粗体星号——覆盖三种历史形态：整体包裹 `**值**`、
+ * 前导无尾随 `**值`、词中包裹 `**词**（括注）`）
+ *
+ * @param value - 原值
+ * @returns 清理后值
+ */
+export function cleanValue(value: string): string {
+  return value
+    .trim()
+    .replace(/^\*\*/, '')
+    .replace(/\*\*$/, '')
+    .replace(/\*\*(?=[（(])/, '')
+    .trim();
+}
+
+/**
+ * 在状态值中匹配 pre-emoji 词表
+ *
+ * @param value - 清理后的状态值
+ * @returns 命中档位与词；未命中为 null
+ */
+function matchStatusWord(value: string): StatusWordMatch | null {
+  /**
+   * 档位遍历序（frozen 最先——冻结态优先识别并拒绝迁移）
+   */
+  const tiers: StatusWordMatch['tier'][] = [
+    'frozen',
+    'green',
+    'deferred',
+    'canceled',
+    'inProgress',
+    'red',
+  ];
+
+  for (const tier of tiers) {
+    for (const word of LEGACY_STATUS_VOCABULARY[tier]) {
+      if (value.startsWith(word)) {
+        return { tier, word };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 状态值切分产物（首个括注内容与词后剩余文本）
+ */
+type StatusValueSplit = {
+  /**
+   * 首个括注内容（无括注为空串）
+   */
+  paren: string;
+
+  /**
+   * 括注后的剩余文本
+   */
+  rest: string;
+};
+
+/**
+ * 提取状态值中的首个括注与其余文本
+ *
+ * @param value - 清理后的状态值
+ * @param word - 命中词
+ * @returns 括注内容与词后剩余文本
+ */
+function splitStatusValue(value: string, word: string): StatusValueSplit {
+  /**
+   * 词后文本
+   */
+  const afterWord = value.slice(word.length).trim();
+
+  /**
+   * 首个括注匹配
+   */
+  const parenMatch = /^[（(]([^）)]*)[）)]/.exec(afterWord);
+
+  if (parenMatch === null) {
+    return { paren: '', rest: afterWord };
+  }
+
+  return {
+    paren: (parenMatch[1] ?? '').trim(),
+    rest: afterWord.slice((parenMatch[0] ?? '').length).trim(),
+  };
+}
+
+/**
+ * 规范化状态值（pre-emoji 词 → 五态灯位；原词与括注零丢失保留）
+ *
+ * @param value - 清理后的状态值
+ * @returns 规范值与档位；不可机械迁移为 null（须人工）
+ */
+export function canonicalizeStatusValue(value: string): CanonicalStatusValue | null {
+  /**
+   * 词表命中
+   */
+  const match = matchStatusWord(value);
+
+  if (match === null) {
+    return null;
+  }
+
+  /**
+   * 括注与剩余文本
+   */
+  const { paren, rest } = splitStatusValue(value, match.word);
+
+  /**
+   * 括注段收集器（顺序：括注 → 剩余 → 原词溯源）
+   */
+  const parts = [paren, rest, `原「${match.word}」`].filter((part) => part !== '');
+
+  switch (match.tier) {
+    case 'frozen':
+      return null;
+
+    case 'green':
+      return { value: `🟢 已处置（${parts.join('；')}）`, tier: match.tier, word: match.word };
+
+    case 'red':
+      return { value: `🔴 待处理（${parts.join('；')}）`, tier: match.tier, word: match.word };
+
+    case 'deferred':
+      return {
+        value: `🔴 待处理（${[paren === '' ? '延期' : paren, `原「${match.word}」`].join('；')}）`,
+        tier: match.tier,
+        word: match.word,
+      };
+
+    case 'canceled':
+      return paren === '' || paren.length < 4
+        ? null
+        : { value: `⚫ 已取消（${parts.join('；')}）`, tier: match.tier, word: match.word };
+
+    case 'inProgress':
+      return paren.length < 4
+        ? null
+        : { value: `🟡 处理中（${paren}）`, tier: match.tier, word: match.word };
+  }
+}
+
+/**
+ * 严重程度/中文优先级 → P 档位映射
+ *
+ * @param value - 原值（高/中/低或 P1/P2/P3）
+ * @returns P 档位；不可映射为 null
+ */
+export function mapPriorityValue(value: string): 'P1' | 'P2' | 'P3' | null {
+  /**
+   * 严重程度中文档位与 P 档位的等价映射表（P 档位原样透传）
+   */
+  const table: Record<string, 'P1' | 'P2' | 'P3'> = {
+    高: 'P1',
+    中: 'P2',
+    低: 'P3',
+    P1: 'P1',
+    P2: 'P2',
+    P3: 'P3',
+  };
+
+  return table[cleanValue(value)] ?? null;
+}
+
+/**
+ * H1 规范化产物
+ */
+type CanonicalH1 = {
+  /**
+   * 规范标题行（`# NNNN - 标题核心`）
+   */
+  line: string;
+
+  /**
+   * 标题核心（剥离既有编号与分隔符变体后的标题文本）
+   */
+  titleCore: string;
+};
+
+/**
+ * H1 标题规范化：`# NNNN - 标题`（剥离既有编号与分隔符变体）
+ *
+ * @param h1 - 原一级标题行
+ * @param number - 文件名编号
+ * @returns 规范标题行与标题核心
+ */
+export function canonicalizeH1(h1: string, number: string): CanonicalH1 {
+  /**
+   * 标题核心（去行首 `# ` 与既有编号 + 分隔符变体）
+   */
+  const titleCore = h1
+    .replace(/^#\s+/, '')
+    .replace(new RegExp(`^${number}\\s*(?:[-·.．：:]\\s*|\\s*)`), '')
+    .trim();
+
+  return { line: `# ${number} - ${titleCore}`, titleCore };
+}
+
+/**
+ * 处置段候选标题链（apex-energy-ktv 全量段名词频盘点驱动；验证族 > 治理记录族 >
+ * 变更/修复族。计划性段名（治理方案/治理方向/修复方向/处置方向）不属处置记录，排除）
+ */
+export const DISPOSITION_CANDIDATES: ReadonlyArray<{ pattern: RegExp; title: string }> = [
+  { pattern: /^验证(结果)?(?!口径)/, title: '处置结果/验证口径' },
+  {
+    pattern: /^(治理记录|治理落地记录|治理落地|落地治理|治理（落地）|治理动作|治理$)/,
+    title: '处置结果/治理记录',
+  },
+  {
+    pattern: /^(修复(?!方向)|解决方案|变更内容|处理报告|处置(?!方向))/,
+    title: '处置结果/变更记录',
+  },
+];
+
+/**
+ * 处置段对齐产物
+ */
+type DispositionAlignment = {
+  /**
+   * 对齐后正文行
+   */
+  lines: string[];
+
+  /**
+   * 对齐变换台账
+   */
+  transformations: MigrationTransformation[];
+
+  /**
+   * 是否探测到处置段占位（触发黄灯降级）
+   */
+  placeholder: boolean;
+};
+
+/**
+ * 对齐处置段（绿灯族专属）：候选标题改名 + 无候选段时追加验证口径段 + 占位降级探测
+ *
+ * @param bodyLines - 正文行（自 bodyStartIndex 起）
+ * @returns 对齐产物（正文行 + 台账 + 是否占位降级）
+ */
+function alignDisposition(bodyLines: string[]): DispositionAlignment {
+  /**
+   * 台账收集器
+   */
+  const transformations: MigrationTransformation[] = [];
+
+  /**
+   * 候选命中下标与目标标题
+   */
+  let hitIndex = -1;
+
+  /**
+   * 命中候选的改名目标标题（如「处置结果/验证口径」）
+   */
+  let hitTitle = '';
+
+  for (const candidate of DISPOSITION_CANDIDATES) {
+    /**
+     * 候选标题行下标（精确行首匹配 `## ` + 模式）
+     */
+    const index = bodyLines.findIndex(
+      (line) => line.startsWith('## ') && candidate.pattern.test(line.slice(3).trim()),
+    );
+
+    if (index !== -1) {
+      hitIndex = index;
+
+      hitTitle = candidate.title;
+
+      break;
+    }
+  }
+
+  /**
+   * 已有含「处置结果」标题（前次迁移或原生）——不重复改名，不追加
+   */
+  const alreadyDisposition = bodyLines.some(
+    (line) => line.startsWith('## ') && line.includes('处置结果'),
+  );
+
+  /**
+   * 产物行
+   */
+  const lines = [...bodyLines];
+
+  /**
+   * 占位降级标记
+   */
+  let placeholder = false;
+
+  if (!alreadyDisposition && hitIndex !== -1) {
+    /**
+     * 原标题行
+     */
+    const original = lines[hitIndex] ?? '';
+
+    lines[hitIndex] = `## ${hitTitle}`;
+
+    transformations.push({
+      kind: 'disposition-renamed',
+      detail: `${original} → ## ${hitTitle}`,
+    });
+
+    /**
+     * 改名段起 8 行内占位探测
+     */
+    const window = lines.slice(hitIndex + 1, hitIndex + 1 + DISPOSITION_PLACEHOLDER_WINDOW_LINES);
+
+    placeholder = window.some((line) => DISPOSITION_PLACEHOLDER_PATTERN.test(line));
+  }
+
+  /**
+   * 追加条件：无任何处置段且改名来源非验证语义（变更记录族——缺独立验证段）
+   */
+  const appendedNeeded =
+    !alreadyDisposition && (hitIndex === -1 || hitTitle === '处置结果/变更记录');
+
+  if (appendedNeeded && !placeholder) {
+    lines.push(
+      '',
+      '## 处置结果/验证口径',
+      '',
+      '（原案无独立验证段；处置证据见上文各节——格式清偿迁移回填）',
+    );
+
+    transformations.push({
+      kind: 'disposition-appended',
+      detail: '追加 ## 处置结果/验证口径（无独立验证段的事实回填说明）',
+    });
+  }
+
+  return { lines, transformations, placeholder };
+}
+
+/**
+ * 头部字段渲染序（模板 §八 规范序；未入表字段按首现序殿后）
+ */
+const HEADER_FIELD_ORDER: readonly string[] = [
+  '优先级',
+  '状态',
+  '立案日期',
+  '所属域',
+  '来源',
+  '沿革',
+  '阻塞',
+];
+
+/**
+ * 执行单文档纯变换
+ *
+ * @param raw - 文档全文
+ * @param options - 迁移选项
+ * @returns 纯变换产物
+ */
+export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): MigrateCoreResult {
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  /**
+   * 头部解析产物（五方言）
+   */
+  const parsed = parseHeaderDialect(lines);
+
+  /**
+   * 状态字段定位
+   */
+  const statusIndex = parsed.fields.findIndex((field) => field.key === '状态');
+
+  /**
+   * 显式灯位注入标记（--status：无状态行历史文档的人工定档通道）
+   */
+  const injected = statusIndex === -1 && (options.status === 'red' || options.status === 'green');
+
+  if (statusIndex === -1 && !injected) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: '无可识别状态行——灯位属语义判断，交人工（--status red|green 显式定档）',
+      transformations: [],
+    };
+  }
+
+  /**
+   * 原状态值（清理粗体包裹；注入通道为规范标签本身）
+   */
+  const originalStatus = injected
+    ? `${CANONICAL_STATUS_LABELS[options.status ?? 'red']}（存量清偿定档：原案无状态行，依结案内容人工定档）`
+    : cleanValue(parsed.fields[statusIndex ?? 0]?.value ?? '');
+
+  /**
+   * 已规范形态幂等判定（规范五态或 emoji 旧变体均不再迁移；注入通道不适用）
+   */
+  if (!injected && classifyStatusLine(`状态: ${originalStatus}`) !== 'unknown') {
+    return {
+      outcome: 'unchanged',
+      content: raw,
+      message: '状态行已是规范五态形态',
+      transformations: [],
+    };
+  }
+
+  /**
+   * 变换台账
+   */
+  const transformations: MigrationTransformation[] = [];
+
+  /**
+   * 字段工作副本（键值清理粗体包裹；注入通道补入状态字段）
+   */
+  const fields = parsed.fields.map((field) => ({ key: field.key, value: cleanValue(field.value) }));
+
+  if (injected) {
+    fields.push({ key: '状态', value: originalStatus });
+
+    transformations.push({
+      kind: 'status-canonicalized',
+      detail: `<无状态行> → ${originalStatus}（--status 注入，人工定档）`,
+    });
+  }
+
+  /**
+   * 字段别名：日期 → 立案日期（已有立案日期则保留原字段不动）
+   */
+  const filingIndex = fields.findIndex((field) => field.key === '立案日期');
+
+  /**
+   * 旧字段名「日期」下标（方言主流的立案日期载体）
+   */
+  const dateIndex = fields.findIndex((field) => field.key === '日期');
+
+  if (filingIndex === -1 && dateIndex !== -1) {
+    /**
+     * 待改名的日期字段
+     */
+    const dateField = fields[dateIndex];
+
+    if (dateField !== undefined) {
+      fields[dateIndex] = { key: '立案日期', value: dateField.value };
+
+      transformations.push({
+        kind: 'field-alias',
+        detail: `日期 → 立案日期（${dateField.value}）`,
+      });
+    }
+  }
+
+  /**
+   * 立案日期缺省回填（未给缺省则 skipped 交人工）
+   */
+  if (!fields.some((field) => field.key === '立案日期')) {
+    if (options.defaultFilingDate === undefined) {
+      return {
+        outcome: 'skipped',
+        content: raw,
+        message: '缺立案日期且未给回填缺省——交人工',
+        transformations: [],
+      };
+    }
+
+    fields.push({ key: '立案日期', value: options.defaultFilingDate });
+
+    transformations.push({
+      kind: 'required-backfilled',
+      detail: `立案日期 ← ${options.defaultFilingDate}`,
+    });
+  }
+
+  /**
+   * 优先级：既有值映射 / 严重程度映射 / 缺省回填
+   */
+  const priorityIndex = fields.findIndex((field) => field.key === '优先级');
+
+  if (priorityIndex !== -1) {
+    /**
+     * 既有优先级值
+     */
+    const existing = fields[priorityIndex]?.value ?? '';
+
+    /**
+     * 映射产物（中文档位 → P 档位）
+     */
+    const mapped = mapPriorityValue(existing);
+
+    if (mapped !== null && mapped !== existing) {
+      fields[priorityIndex] = { key: '优先级', value: mapped };
+
+      transformations.push({ kind: 'priority-mapped', detail: `优先级 ${existing} → ${mapped}` });
+    }
+  } else {
+    /**
+     * 严重程度映射或缺省回填
+     */
+    const severityField = fields.find((field) => field.key === '严重程度');
+
+    /**
+     * 回填值
+     */
+    const backfill =
+      (severityField !== undefined ? mapPriorityValue(severityField.value) : null) ??
+      options.defaultPriority ??
+      null;
+
+    if (backfill === null) {
+      return {
+        outcome: 'skipped',
+        content: raw,
+        message: '缺优先级且未给回填缺省——交人工',
+        transformations: [],
+      };
+    }
+
+    fields.push({ key: '优先级', value: backfill });
+
+    transformations.push({
+      kind: severityField !== undefined ? 'priority-mapped' : 'priority-backfilled',
+      detail: `优先级 ← ${backfill}${severityField !== undefined ? `（严重程度 ${severityField.value}）` : '（缺省回填）'}`,
+    });
+  }
+
+  /**
+   * 注入通道档位（红/绿直取；声明式注解替代断言窄化）
+   */
+  const injectedTier: 'green' | 'red' = options.status === 'green' ? 'green' : 'red';
+
+  /**
+   * 状态词规范化（注入通道状态已是规范形态，跳过词表判定）
+   */
+  const canonicalStatus = injected
+    ? {
+        value: originalStatus,
+        tier: injectedTier,
+        word: '<无状态行>',
+      }
+    : canonicalizeStatusValue(originalStatus);
+
+  if (canonicalStatus === null) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: `状态值「${originalStatus}」不可机械迁移（冻结/取消无据/黄灯无因/词表未识别）——交人工`,
+      transformations: [],
+    };
+  }
+
+  /**
+   * 处置段对齐（绿灯族；黄灯降级案同样需要对齐后的段供回填）
+   */
+  const isGreenFamily = canonicalStatus.tier === 'green';
+
+  /**
+   * 正文行
+   */
+  let bodyLines = lines.slice(parsed.bodyStartIndex);
+
+  /**
+   * 处置段对齐产物（非绿灯族不触发）
+   */
+  const alignment = isGreenFamily
+    ? alignDisposition(bodyLines)
+    : { lines: bodyLines, transformations: [], placeholder: false };
+
+  bodyLines = alignment.lines;
+
+  transformations.push(...alignment.transformations);
+
+  /**
+   * 最终状态值（占位降级：历史绿词但验证口径为占位——诚实黄灯；注入通道定档为人工语义不降级）
+   */
+  const finalStatus =
+    !injected && alignment.placeholder
+      ? `🟡 处理中（历史标记已处置但验证口径为占位，清偿时待核实；原「${canonicalStatus.word}」）`
+      : canonicalStatus.value;
+
+  if (!injected) {
+    if (alignment.placeholder) {
+      transformations.push({
+        kind: 'status-downgraded-placeholder',
+        detail: `${originalStatus} → 🟡 处理中（处置段占位降级）`,
+      });
+    } else {
+      transformations.push({
+        kind: 'status-canonicalized',
+        detail: `${originalStatus} → ${canonicalStatus.value}`,
+      });
+    }
+  }
+
+  /**
+   * 状态字段写回
+   */
+  const statusWriteIndex = fields.findIndex((field) => field.key === '状态');
+
+  if (statusWriteIndex !== -1) {
+    fields[statusWriteIndex] = { key: '状态', value: finalStatus };
+  }
+
+  /**
+   * 来源回填
+   */
+  if (!fields.some((field) => field.key === '来源')) {
+    if (options.defaultSource === undefined) {
+      return {
+        outcome: 'skipped',
+        content: raw,
+        message: '缺来源且未给回填缺省——交人工',
+        transformations: [],
+      };
+    }
+
+    fields.push({ key: '来源', value: options.defaultSource });
+
+    transformations.push({ kind: 'required-backfilled', detail: '来源 ← 缺省回填' });
+  }
+
+  /**
+   * 所属域回填（scope title）
+   */
+  if (!fields.some((field) => field.key === '所属域')) {
+    fields.push({ key: '所属域', value: options.scopeTitle });
+
+    transformations.push({ kind: 'required-backfilled', detail: `所属域 ← ${options.scopeTitle}` });
+  }
+
+  /**
+   * H1 规范化
+   */
+  const h1Index = lines.findIndex((line) => line.startsWith('# '));
+
+  if (h1Index === -1) {
+    return { outcome: 'skipped', content: raw, message: '无一级标题——交人工', transformations: [] };
+  }
+
+  /**
+   * 规范 H1
+   */
+  const canonicalH1 = canonicalizeH1(lines[h1Index] ?? '', options.number);
+
+  if (canonicalH1.line !== (lines[h1Index] ?? '')) {
+    transformations.push({
+      kind: 'h1-numbered',
+      detail: `${lines[h1Index]} → ${canonicalH1.line}`,
+    });
+  }
+
+  /**
+   * 头部渲染序（规范序在前，未入表字段按首现序殿后）
+   */
+  const orderedFields = [
+    ...HEADER_FIELD_ORDER.flatMap((key) => fields.filter((field) => field.key === key)),
+    ...fields.filter((field) => !HEADER_FIELD_ORDER.includes(field.key)),
+  ];
+
+  /**
+   * 产物全文
+   */
+  const content = [
+    canonicalH1.line,
+    '',
+    ...orderedFields.map((field) => `**${field.key}**: ${field.value}`),
+    ...(parsed.residuals.length > 0 ? ['', ...parsed.residuals] : []),
+    '',
+    ...bodyLines,
+  ].join('\n');
+
+  if (content === raw) {
+    return { outcome: 'unchanged', content: raw, message: '已是规范形态', transformations: [] };
+  }
+
+  return { outcome: 'rewritten', content, message: '存量头部已清偿为规范形态', transformations };
+}