《互联网产品的 AI 架构·多能力编排与任务闭环》13.2 一次编排方案评审

// file: src/orch/review.ts
// tier: L2
// verify: node --test test/orch/baseline.test.ts

import { AiError } from "../core/errors.ts";
import type { ChainId, Verdict } from "./baseline.ts";
import type { BaselineReport } from "./report.ts";

export interface ReviewChange {
  id: string;
  /** 改什么，必须指向具体节点或字段。 */
  target: string;
  baseline: string;
  expected: string;
}

export interface RejectedItem {
  id: string;
  proposal: string;
  reason: string;
}

export interface ReviewInput {
  id: string;
  date: string;
  owner: string;
  proposal: string;
  baseline: BaselineReport;
  chains: readonly ChainId[];
  changes: readonly ReviewChange[];
  expected: readonly string[];
  conditions: readonly string[];
  recheckDate: string;
  rejected: readonly RejectedItem[];
}

export interface ReviewRecord {
  id: string;
  date: string;
  owner: string;
  proposal: string;
  baselineVersion: string;
  baselineVerdict: Verdict;
  chains: readonly ChainId[];
  changes: readonly ReviewChange[];
  expected: readonly string[];
  conditions: readonly string[];
  recheckDate: string;
  rejected: readonly RejectedItem[];
  status: "accepted" | "conditional" | "rejected";
}

function fail(message: string): never {
  throw new AiError("invalid-request", `review: ${message}`);
}

/** 评审记录必须能回答六个问题：方案、基线、改动、预期、条件、复查。 */
export function buildReviewRecord(input: ReviewInput): ReviewRecord {
  for (const field of ["id", "date", "owner", "proposal", "recheckDate"] as const) {
    if (input[field].trim() === "") fail(`${field} 不能为空`);
  }
  if (input.chains.length === 0) fail("至少指定一条受影响链路");
  if (input.changes.length === 0) fail("改动清单不能为空");
  if (input.expected.length === 0) fail("预期结果不能为空");
  if (input.recheckDate <= input.date) fail("复查日期必须晚于评审日期");
  const changed = new Set(input.chains);
  for (const change of input.changes) {
    if (!/^[ABC]$/.test(change.target.slice(0, 1))) fail(`改动 ${change.id} 未指向 A/B/C 链路`);
    if (!changed.has(change.target.slice(0, 1) as ChainId)) fail(`改动 ${change.id} 指向未受影响链路`);
  }
  const status = input.conditions.length > 0 ? "conditional" : "accepted";
  return {
    id: input.id,
    date: input.date,
    owner: input.owner,
    proposal: input.proposal,
    baselineVersion: input.baseline.sampleVersion,
    baselineVerdict: input.baseline.overall.verdict,
    chains: input.chains,
    changes: input.changes,
    expected: input.expected,
    conditions: input.conditions,
    recheckDate: input.recheckDate,
    rejected: input.rejected,
    status,
  };
}

/** 渲染成可归档的评审文本；字段顺序固定，空条件显式写「无」。 */
export function renderReviewRecord(record: ReviewRecord): string {
  const lines: string[] = [];
  lines.push(`# 编排方案评审 ${record.id}`);
  lines.push("");
  lines.push(`- 日期：${record.date}`);
  lines.push(`- 负责人：${record.owner}`);
  lines.push(`- 方案：${record.proposal}`);
  lines.push(`- 基线：${record.baselineVersion}（${record.baselineVerdict}）`);
  lines.push(`- 影响链路：${record.chains.join("、")}`);
  lines.push(`- 状态：${record.status}`);
  lines.push("");
  lines.push("## 改动");
  for (const change of record.changes) {
    lines.push(`- ${change.id} ${change.target}：${change.baseline} -> ${change.expected}`);
  }
  lines.push("");
  lines.push("## 预期");
  for (const item of record.expected) lines.push(`- ${item}`);
  lines.push("");
  lines.push("## 条件");
  if (record.conditions.length === 0) lines.push("- 无");
  for (const item of record.conditions) lines.push(`- ${item}`);
  lines.push("");
  lines.push(`## 复查日期`);
  lines.push(record.recheckDate);
  lines.push("");
  lines.push("## 驳回项");
  if (record.rejected.length === 0) lines.push("- 无");
  for (const item of record.rejected) lines.push(`- ${item.id} ${item.proposal}：${item.reason}`);
  return `${lines.join("\n")}\n`;
}

/** 归档前的最小校验：缺字段的记录不能进入发布流程。 */
export function assertReviewComplete(record: ReviewRecord): void {
  if (record.changes.length === 0) fail("评审记录缺少改动");
  if (record.expected.length === 0) fail("评审记录缺少预期");
  if (record.recheckDate <= record.date) fail("评审记录缺少有效的复查日期");
  if (record.owner.trim() === "") fail("评审记录缺少负责人");
}