《互联网产品的 AI 架构·平台化与治理》7.3 优化优先级与投资回报

期望月节省 = 月节省额 × 置信度
回本期（月×100） = 实施成本 × 100 ÷ 期望月节省
分数（基点） = 期望月节省 × 12 × 10,000 × 100 ÷ (实施成本 × 风险因子)

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

import { AiError } from "../core/errors.ts";

/** 质量风险不是扣分项，而是准入门槛与折现因子。 */
export type RiskBand = "low" | "medium" | "high";

export const RISK_ORDER: Record<RiskBand, number> = { low: 0, medium: 1, high: 2 };

/** 风险折现：高风险项目的预期收益按 3 倍实施成本计入分母。 */
export const RISK_FACTOR_PCT: Record<RiskBand, number> = { low: 100, medium: 150, high: 300 };

export interface OptimizationItem {
  id: string;
  title: string;
  ownerTeam: string;
  savingsMicrosPerMonth: number;
  implementationCostMicros: number;
  /** 收益置信度，单位基点；80% 记为 8000。 */
  confidenceBps: number;
  qualityRisk: RiskBand;
}

export interface PortfolioPolicy {
  budgetMicros: number;
  /** 回本期上限，单位“月 × 100”；6 个月记为 600。 */
  maxPaybackMonthsX100: number;
  allowedRisk: RiskBand;
  minConfidenceBps: number;
}

export type RejectReason = "no-saving" | "low-confidence" | "quality-risk" | "payback-too-long";

export interface ScoredItem {
  item: OptimizationItem;
  /** 按置信度折算后的月节省额。 */
  expectedSavingMicros: number;
  /** 回本期，单位“月 × 100”；收益为 0 时没有回本期。 */
  paybackMonthsX100: number | null;
  /** 年化风险调整收益 / 实施成本，单位基点。 */
  scoreBps: number;
  rejection: RejectReason | null;
  /** 非低风险项目必须先过评测门禁。 */
  requiresEval: boolean;
}

export interface PortfolioTotals {
  fundedCount: number;
  plannedCostMicros: number;
  expectedMonthlySavingMicros: number;
  paybackMonthsX100: number | null;
  deferredMonthlySavingMicros: number;
  rejectedMonthlySavingMicros: number;
}

export interface PortfolioPlan {
  ranked: ScoredItem[];
  funded: ScoredItem[];
  deferred: ScoredItem[];
  rejected: ScoredItem[];
  totals: PortfolioTotals;
}

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

function text(value: string, field: string): string {
  if (typeof value !== "string" || value.trim() === "") fail(`${field} is required`);
  return value;
}

function integer(value: number, field: string, min = 0): number {
  if (!Number.isSafeInteger(value) || value < min) fail(`${field} must be an integer >= ${min}`);
  return value;
}

function checkPolicy(policy: PortfolioPolicy): void {
  integer(policy.budgetMicros, "policy.budgetMicros", 1);
  integer(policy.maxPaybackMonthsX100, "policy.maxPaybackMonthsX100", 1);
  integer(policy.minConfidenceBps, "policy.minConfidenceBps", 0);
  if (policy.minConfidenceBps > 10_000) fail("policy.minConfidenceBps must not exceed 10000");
  if (RISK_ORDER[policy.allowedRisk] === undefined) fail(`unknown risk ${String(policy.allowedRisk)}`);
}

/**
 * 先过门槛，再算分数。门槛回答“能不能做”，分数回答“先做哪个”。
 * 分数 = 年化风险调整节省额 / 实施成本，避免“省得最多”直接等于“最该先做”。
 */
export function scoreItem(item: OptimizationItem, policy: PortfolioPolicy): ScoredItem {
  checkPolicy(policy);
  text(item.id, "item.id");
  text(item.title, "item.title");
  text(item.ownerTeam, "item.ownerTeam");
  integer(item.savingsMicrosPerMonth, "item.savingsMicrosPerMonth");
  integer(item.implementationCostMicros, "item.implementationCostMicros", 1);
  integer(item.confidenceBps, "item.confidenceBps");
  if (item.confidenceBps > 10_000) fail("item.confidenceBps must not exceed 10000");
  if (RISK_ORDER[item.qualityRisk] === undefined) fail(`unknown risk ${String(item.qualityRisk)}`);

  const expectedSavingMicros = Math.floor(
    (item.savingsMicrosPerMonth * item.confidenceBps) / 10_000,
  );
  const paybackMonthsX100 = expectedSavingMicros === 0
    ? null
    : Math.ceil((item.implementationCostMicros * 100) / expectedSavingMicros);
  const scoreBps = expectedSavingMicros === 0
    ? 0
    : Math.floor(
      (expectedSavingMicros * 12 * 10_000 * 100) /
      (item.implementationCostMicros * RISK_FACTOR_PCT[item.qualityRisk]),
    );

  let rejection: RejectReason | null = null;
  if (expectedSavingMicros === 0) rejection = "no-saving";
  else if (item.confidenceBps < policy.minConfidenceBps) rejection = "low-confidence";
  else if (RISK_ORDER[item.qualityRisk] > RISK_ORDER[policy.allowedRisk]) rejection = "quality-risk";
  else if (paybackMonthsX100 !== null && paybackMonthsX100 > policy.maxPaybackMonthsX100) {
    rejection = "payback-too-long";
  }

  return {
    item: { ...item },
    expectedSavingMicros,
    paybackMonthsX100,
    scoreBps,
    rejection,
    requiresEval: item.qualityRisk !== "low",
  };
}

function compareEligible(left: ScoredItem, right: ScoredItem): number {
  if (right.scoreBps !== left.scoreBps) return right.scoreBps - left.scoreBps;
  const leftPayback = left.paybackMonthsX100 ?? Number.MAX_SAFE_INTEGER;
  const rightPayback = right.paybackMonthsX100 ?? Number.MAX_SAFE_INTEGER;
  if (leftPayback !== rightPayback) return leftPayback - rightPayback;
  const byRisk = RISK_ORDER[left.item.qualityRisk] - RISK_ORDER[right.item.qualityRisk];
  return byRisk !== 0 ? byRisk : left.item.id.localeCompare(right.item.id);
}

/**
 * 预算内按分数贪心选择。贪心不保证组合最优，
 * 但它可解释、可复算，适合按季度公开评审；最优解留到预算更紧时再引入。
 */
export function planPortfolio(
  items: readonly OptimizationItem[],
  policy: PortfolioPolicy,
): PortfolioPlan {
  checkPolicy(policy);
  const seen = new Set<string>();
  const scored = items.map((item) => {
    if (seen.has(item.id)) fail(`duplicate item ${item.id}`);
    seen.add(item.id);
    return scoreItem(item, policy);
  });

  const eligible = scored.filter((item) => item.rejection === null).sort(compareEligible);
  const rejected = scored
    .filter((item) => item.rejection !== null)
    .sort((left, right) => right.item.savingsMicrosPerMonth - left.item.savingsMicrosPerMonth);

  let remaining = policy.budgetMicros;
  const funded: ScoredItem[] = [];
  const deferred: ScoredItem[] = [];
  for (const item of eligible) {
    if (item.item.implementationCostMicros <= remaining) {
      funded.push(item);
      remaining -= item.item.implementationCostMicros;
    } else {
      deferred.push(item);
    }
  }

  const plannedCostMicros = funded.reduce((sum, item) => sum + item.item.implementationCostMicros, 0);
  const expectedMonthlySavingMicros = funded.reduce((sum, item) => sum + item.expectedSavingMicros, 0);
  const totals: PortfolioTotals = {
    fundedCount: funded.length,
    plannedCostMicros,
    expectedMonthlySavingMicros,
    paybackMonthsX100: expectedMonthlySavingMicros === 0
      ? null
      : Math.ceil((plannedCostMicros * 100) / expectedMonthlySavingMicros),
    deferredMonthlySavingMicros: deferred.reduce((sum, item) => sum + item.expectedSavingMicros, 0),
    rejectedMonthlySavingMicros: rejected.reduce((sum, item) => sum + item.expectedSavingMicros, 0),
  };

  return {
    ranked: [...funded, ...deferred, ...rejected],
    funded,
    deferred,
    rejected,
    totals,
  };
}