《互联网产品的 AI 架构·平台化与治理》11.2 评审委员会与决策记录

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

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;

export function isIsoDate(value: string): boolean {
  if (!ISO_DATE.test(value)) return false;
  const parsed = new Date(`${value}T00:00:00Z`);
  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
}

export function addDays(date: string, days: number): string {
  const parsed = new Date(`${date}T00:00:00Z`);
  parsed.setUTCDate(parsed.getUTCDate() + days);
  return parsed.toISOString().slice(0, 10);
}

export function daysBetween(from: string, to: string): number {
  const start = new Date(`${from}T00:00:00Z`).getTime();
  const end = new Date(`${to}T00:00:00Z`).getTime();
  return Math.round((end - start) / 86_400_000);
}

/** 评审委员会只有这七个席位；席位是职责，不是部门名称。 */
export type BoardRole =
  | "platform-architect" | "security" | "compliance" | "finance"
  | "sre" | "business-rep" | "eval-owner";

export const BOARD_ROLES: readonly BoardRole[] = [
  "platform-architect", "security", "compliance", "finance",
  "sre", "business-rep", "eval-owner",
];

export type TopicKind =
  | "new-capability" | "major-version" | "cross-tenant-quota" | "model-change"
  | "retirement" | "incident-postmortem" | "exception";

export interface TopicRule {
  /** 到会人数不足即流会，不允许用邮件补签替代。 */
  requiredRoles: readonly BoardRole[];
  /** 否决席：任一人反对即拒绝；弃权视为尚未同意。 */
  vetoRoles: readonly BoardRole[];
  minApprovals: number;
  /** 批准后多久必须复查，天。 */
  reviewWindowDays: number;
  agendaOwner: BoardRole;
}

export const TOPIC_RULES: Record<TopicKind, TopicRule> = {
  "new-capability": { requiredRoles: ["platform-architect", "security", "business-rep", "eval-owner"],
    vetoRoles: ["platform-architect", "security"], minApprovals: 3, reviewWindowDays: 90,
    agendaOwner: "platform-architect" },
  "major-version": { requiredRoles: ["platform-architect", "sre", "business-rep"],
    vetoRoles: ["platform-architect"], minApprovals: 2, reviewWindowDays: 90,
    agendaOwner: "platform-architect" },
  "cross-tenant-quota": { requiredRoles: ["platform-architect", "finance", "business-rep"],
    vetoRoles: ["finance"], minApprovals: 2, reviewWindowDays: 30, agendaOwner: "finance" },
  "model-change": { requiredRoles: ["platform-architect", "security", "eval-owner", "finance"],
    vetoRoles: ["security", "eval-owner"], minApprovals: 3, reviewWindowDays: 30,
    agendaOwner: "eval-owner" },
  retirement: { requiredRoles: ["platform-architect", "business-rep", "sre"],
    vetoRoles: ["business-rep"], minApprovals: 2, reviewWindowDays: 90, agendaOwner: "sre" },
  "incident-postmortem": { requiredRoles: ["sre", "security", "business-rep"],
    vetoRoles: ["sre"], minApprovals: 2, reviewWindowDays: 30, agendaOwner: "sre" },
  exception: { requiredRoles: ["platform-architect", "security", "compliance"],
    vetoRoles: ["security", "compliance"], minApprovals: 3, reviewWindowDays: 14,
    agendaOwner: "platform-architect" },
};

export type Vote = "approve" | "reject" | "abstain" | "absent";
export type BallotBox = Partial<Record<BoardRole, Vote>>;
export type ReviewOutcome = "approved" | "rejected" | "deferred";

export interface ReviewResult {
  topic: TopicKind;
  outcome: ReviewOutcome;
  approvals: number;
  rejects: number;
  abstentions: number;
  missingRoles: readonly BoardRole[];
  vetoRejects: readonly BoardRole[];
  vetoPending: readonly BoardRole[];
  reasons: readonly string[];
}

export interface AgendaRoute {
  topic: TopicKind;
  rule: TopicRule;
  quorum: number;
  decisionRule: string;
}

/** 议题先路由到固定席位与固定规则，避免每次开会临时决定谁有否决权。 */
export function routeTopic(topic: TopicKind): AgendaRoute {
  const rule = TOPIC_RULES[topic];
  return {
    topic, rule, quorum: rule.requiredRoles.length,
    decisionRule: `至少 ${rule.minApprovals} 票同意且同意票多于反对票；`
      + `否决席 ${rule.vetoRoles.join(" / ")} 弃权视为未通过`,
  };
}

/**
 * 判定顺序：先看流会，再看否决，再看否决席是否表态，最后看票数。
 * 流会与弃权都返回 deferred，只有明确反对或票数劣势才返回 rejected。
 */
export function decideReview(topic: TopicKind, ballots: BallotBox): ReviewResult {
  const rule = TOPIC_RULES[topic];
  const missingRoles = rule.requiredRoles.filter((role) => (ballots[role] ?? "absent") === "absent");
  const vetoRejects = rule.vetoRoles.filter((role) => ballots[role] === "reject");
  const vetoPending = rule.vetoRoles.filter((role) => ballots[role] === "abstain");
  const count = (vote: Vote): number => BOARD_ROLES.filter((role) => ballots[role] === vote).length;
  const result = (outcome: ReviewOutcome, reason: string): ReviewResult => ({
    topic, outcome, approvals: count("approve"), rejects: count("reject"),
    abstentions: count("abstain"), missingRoles, vetoRejects, vetoPending, reasons: [reason],
  });
  if (missingRoles.length > 0) return result("deferred", `quorum missing: ${missingRoles.join(", ")}`);
  if (vetoRejects.length > 0) return result("rejected", `vetoed by ${vetoRejects.join(", ")}`);
  if (vetoPending.length > 0) {
    return result("deferred", `veto seat has not approved: ${vetoPending.join(", ")}`);
  }
  const approvals = count("approve");
  const rejects = count("reject");
  if (approvals >= rule.minApprovals && approvals > rejects) {
    return result("approved", `${approvals} approvals, threshold ${rule.minApprovals}`);
  }
  return result(rejects >= approvals ? "rejected" : "deferred",
    `${approvals} approvals against ${rejects} rejects, threshold ${rule.minApprovals}`);
}

export interface DecisionRecord {
  /** 固定格式 RB-年份-三位序号，例如 RB-2026-011。 */
  id: string;
  topic: TopicKind;
  capability: string;
  decidedAt: string;
  chair: BoardRole;
  ballots: BallotBox;
  outcome: ReviewOutcome;
  rationale: string;
  /** 批准附带条件；退役与例外议题必须至少写一条。 */
  conditions: readonly string[];
  /** 复查日期；批准的记录必填。 */
  reviewAt?: string;
}

export type DecisionIssueCode =
  | "invalid-id" | "unknown-topic" | "empty-capability" | "invalid-date"
  | "chair-not-required" | "missing-rationale" | "outcome-mismatch"
  | "missing-conditions" | "missing-review-date" | "review-not-after-decision"
  | "review-too-late";

export interface DecisionIssue {
  id: string;
  code: DecisionIssueCode;
  field: string;
  detail: string;
}

const RECORD_ID = /^RB-\d{4}-\d{3}$/;

/** 决策记录不是会议纪要：outcome 必须能由 ballots 重算出来。 */
export function validateDecision(record: DecisionRecord): DecisionIssue[] {
  const issues: DecisionIssue[] = [];
  const add = (code: DecisionIssueCode, field: string, detail: string): void => {
    issues.push({ id: record.id, code, field, detail });
  };
  const rule = TOPIC_RULES[record.topic];
  if (!RECORD_ID.test(record.id)) add("invalid-id", "id", "expected RB-YYYY-NNN");
  if (rule === undefined) {
    add("unknown-topic", "topic", `unknown ${record.topic}`);
    return issues;
  }
  if (record.capability.trim() === "") add("empty-capability", "capability", "empty");
  if (!isIsoDate(record.decidedAt)) add("invalid-date", "decidedAt", record.decidedAt);
  if (!rule.requiredRoles.includes(record.chair)) add("chair-not-required", "chair", record.chair);
  if (record.rationale.trim() === "") add("missing-rationale", "rationale", "empty");
  const recomputed = decideReview(record.topic, record.ballots);
  if (recomputed.outcome !== record.outcome) {
    add("outcome-mismatch", "outcome", `ballots give ${recomputed.outcome}`);
  }
  if (record.outcome !== "approved") return issues;
  if ((record.topic === "retirement" || record.topic === "exception")
    && record.conditions.length === 0) {
    add("missing-conditions", "conditions", `${record.topic} approval needs a condition`);
  }
  if (record.reviewAt === undefined) {
    add("missing-review-date", "reviewAt", "approved decisions must set reviewAt");
  } else if (!isIsoDate(record.reviewAt)) {
    add("invalid-date", "reviewAt", record.reviewAt);
  } else if (isIsoDate(record.decidedAt)) {
    const gap = daysBetween(record.decidedAt, record.reviewAt);
    if (gap <= 0) add("review-not-after-decision", "reviewAt", record.reviewAt);
    else if (gap > rule.reviewWindowDays) {
      add("review-too-late", "reviewAt", `${gap} days exceeds ${rule.reviewWindowDays}`);
    }
  }
  return issues;
}

/** 按议题规则计算默认复查日，避免每份记录手填一个随意日期。 */
export function nextReviewDate(topic: TopicKind, decidedAt: string): string {
  return addDays(decidedAt, TOPIC_RULES[topic].reviewWindowDays);
}

/** 批量校验；同一记录号出现两次会让复查队列静默丢一条。 */
export function validateDecisions(records: readonly DecisionRecord[]): DecisionIssue[] {
  const issues: DecisionIssue[] = [];
  const seen = new Set<string>();
  for (const record of records) {
    if (seen.has(record.id)) issues.push({
      id: record.id, code: "invalid-id", field: "id", detail: "duplicate decision id",
    });
    seen.add(record.id);
    issues.push(...validateDecision(record));
  }
  return issues;
}