《互联网产品的 AI 架构·平台化与治理》13.2 一次跨团队治理评审

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

import { ECHO_BASELINE, evaluateBaseline } from "./baseline.ts";
import type { BaselineItem } from "./baseline.ts";

export type ReviewOutcome = "approve" | "conditional" | "reject";
export type RolloutLevel = "full" | "pilot" | "blocked";
export type ReviewRole = "provider" | "caller" | "platform" | "security" | "compliance" | "sre";

export interface ReviewParticipant {
  team: string;
  role: ReviewRole;
  /** 该参会方必须带来的证据 id；空数组表示只需表决。 */
  brings: readonly string[];
}

export interface ReviewDispute {
  id: string;
  topic: string;
  positions: readonly { team: string; position: string }[];
  resolution: string;
}

export interface ReviewTodo {
  id: string;
  owner: string;
  /** 截止日期统一写 YYYY-MM-DD，便于按日比较而不是按时间戳比较。 */
  due: string;
  /** true 表示未关闭前只能试点，不能全量放量。 */
  blocking: boolean;
  done: boolean;
}

export interface ReviewRecord {
  id: string;
  subject: string;
  baseline: readonly BaselineItem[];
  participants: readonly ReviewParticipant[];
  disputes: readonly ReviewDispute[];
  outcome: ReviewOutcome;
  todos: readonly ReviewTodo[];
}

export type ReviewIssueCode =
  | "missing-role"
  | "duplicate-todo"
  | "invalid-todo-owner"
  | "invalid-todo-due"
  | "blocked-baseline-not-rejected"
  | "approve-with-conditional-baseline"
  | "approve-with-open-blocking-todo";

export interface ReviewIssue {
  code: ReviewIssueCode;
  subject: string;
  detail: string;
}

const DATE = /^\d{4}-\d{2}-\d{2}$/;
const REQUIRED_ROLES: readonly ReviewRole[] = ["provider", "caller", "platform"];

function openBlockingTodos(record: ReviewRecord): ReviewTodo[] {
  return record.todos.filter((todo) => todo.blocking && !todo.done);
}

/**
 * 评审记录先自证一致，再谈结论：角色齐、日期合法、决议与基线不矛盾。
 * 一次返回全部问题，避免修一个报一个。
 */
export function validateReview(record: ReviewRecord): ReviewIssue[] {
  const issues: ReviewIssue[] = [];
  const roles = new Set(record.participants.map((person) => person.role));
  for (const role of REQUIRED_ROLES) {
    if (!roles.has(role)) {
      issues.push({ code: "missing-role", subject: role, detail: "required participant is absent" });
    }
  }
  for (const item of record.baseline) {
    if (item.domain !== "compliance" && item.domain !== "security") continue;
    if (evaluateBaseline([item]).conclusion !== "pass" && !roles.has(item.domain)) {
      issues.push({
        code: "missing-role",
        subject: item.domain,
        detail: `${item.id} is not pass and no ${item.domain} participant`,
      });
    }
  }
  const seen = new Set<string>();
  for (const todo of record.todos) {
    if (seen.has(todo.id)) {
      issues.push({ code: "duplicate-todo", subject: todo.id, detail: "todo id appears twice" });
    }
    seen.add(todo.id);
    if (todo.owner.trim() === "") {
      issues.push({ code: "invalid-todo-owner", subject: todo.id, detail: "owner is empty" });
    }
    if (!DATE.test(todo.due)) {
      issues.push({ code: "invalid-todo-due", subject: todo.id, detail: `bad due ${todo.due}` });
    }
  }
  const baseline = evaluateBaseline(record.baseline);
  if (baseline.conclusion === "blocked" && record.outcome !== "reject") {
    issues.push({
      code: "blocked-baseline-not-rejected",
      subject: record.id,
      detail: `blocking failures: ${baseline.blockingFailures.join(",")}`,
    });
  }
  if (baseline.conclusion === "conditional" && record.outcome === "approve") {
    issues.push({
      code: "approve-with-conditional-baseline",
      subject: record.id,
      detail: `conditions: ${baseline.conditions.join(",")}`,
    });
  }
  if (record.outcome === "approve" && openBlockingTodos(record).length > 0) {
    issues.push({
      code: "approve-with-open-blocking-todo",
      subject: record.id,
      detail: openBlockingTodos(record).map((todo) => todo.id).join(","),
    });
  }
  return issues;
}

/**
 * 放量级别只由三件事决定：基线是否 blocked、决议是否 reject、是否还有未关闭的
 * blocking 待办。三者都清才允许 full，否则最多 pilot。
 */
export function releaseLevel(record: ReviewRecord): RolloutLevel {
  const baseline = evaluateBaseline(record.baseline);
  if (record.outcome === "reject" || baseline.conclusion === "blocked") return "blocked";
  if (record.outcome === "approve" && baseline.conclusion === "pass" && openBlockingTodos(record).length === 0) {
    return "full";
  }
  return "pilot";
}

export type TodoState = "done" | "open" | "overdue";

export interface TodoReport {
  total: number;
  done: number;
  open: number;
  overdue: number;
  openBlocking: number;
  overdueBlocking: number;
}

export function trackTodos(record: ReviewRecord, asOf: string): TodoReport {
  if (!DATE.test(asOf)) throw new Error(`review: invalid as-of date ${asOf}`);
  const states = record.todos.map((todo): TodoState => {
    if (todo.done) return "done";
    return todo.due < asOf ? "overdue" : "open";
  });
  const count = (predicate: (todo: ReviewTodo, index: number) => boolean): number =>
    record.todos.filter((todo, index) => predicate(todo, index)).length;
  return {
    total: record.todos.length,
    done: count((_, index) => states[index] === "done"),
    open: count((_, index) => states[index] === "open"),
    overdue: count((_, index) => states[index] === "overdue"),
    openBlocking: count((todo) => todo.blocking && !todo.done),
    overdueBlocking: count((todo, index) => todo.blocking && states[index] === "overdue"),
  };
}

/** 2026-11-05 的内容团队放量评审，示例记录，不是生产会议纪要。 */
export const ECHO_REVIEW: ReviewRecord = {
  id: "gov-review-2026-11-05",
  subject: "内容团队把摘要与审核能力开放给创作者工具",
  baseline: ECHO_BASELINE,
  participants: [
    { team: "content", role: "provider", brings: ["capability-contract", "pilot-plan"] },
    { team: "creator-tools", role: "caller", brings: ["traffic-forecast"] },
    { team: "transaction", role: "caller", brings: ["quota-ledger"] },
    { team: "platform", role: "platform", brings: ["baseline-report"] },
    { team: "security", role: "security", brings: ["risk-register-2026-10"] },
    { team: "compliance", role: "compliance", brings: ["retention-policy"] },
    { team: "sre", role: "sre", brings: ["slo-dashboard"] },
  ],
  disputes: [
    {
      id: "D1",
      topic: "是否为创作者工具新建 reply.chat",
      positions: [
        { team: "content", position: "新建能力可以按草稿场景调提示与档位" },
        { team: "platform", position: "同一功能键不允许第二个在役能力" },
      ],
      resolution: "复用 chat.reply 2.1.0，只开放契约内的提示后缀与 economy 档位覆盖",
    },
    {
      id: "D2",
      topic: "内容团队借用交易团队 1,500 万微元额度",
      positions: [
        { team: "content", position: "大促期间需要临时扩容" },
        { team: "transaction", position: "借用必须在 12 月 15 日前归还" },
      ],
      resolution: "借用 1,500 万微元，单次上限不变，2026-12-15 前归还，逾期自动回收",
    },
    {
      id: "D3",
      topic: "创作者草稿能否进入跨团队评测集",
      positions: [
        { team: "content", position: "真实草稿最能覆盖边界" },
        { team: "compliance", position: "草稿含未发布内容，不能跨租户共享" },
      ],
      resolution: "跨团队只用合成样本与脱敏样本，租户样本留在租户域内",
    },
    {
      id: "D4",
      topic: "首日放量到 100% 还是先试点",
      positions: [
        { team: "content", position: "首日 100% 才能覆盖大促峰值" },
        { team: "sre", position: "基线与配额条件未关闭前只能试点" },
      ],
      resolution: "先 10% 试点两周，条件关闭后再评审全量",
    },
  ],
  outcome: "conditional",
  todos: [
    { id: "T1", owner: "eval-platform", due: "2026-11-12", blocking: true, done: false },
    { id: "T2", owner: "compliance", due: "2026-11-19", blocking: true, done: false },
    { id: "T3", owner: "platform-governance", due: "2026-11-30", blocking: false, done: false },
    { id: "T4", owner: "content", due: "2026-11-08", blocking: false, done: true },
  ],
};