《互联网产品的 AI 架构·平台化与治理》1.3 平台与业务的职责边界

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

export type OwnerSide = "platform" | "business" | "shared";

export type TaskArtifact =
  | "prompt"
  | "contract"
  | "quota"
  | "version"
  | "model"
  | "evaluation"
  | "incident"
  | "tenant"
  | "tooling";

export type TaskScope =
  | "single-caller"
  | "multiple-callers"
  | "single-tenant"
  | "multiple-tenants"
  | "platform";

export interface OwnershipTask {
  id: string;
  artifact: TaskArtifact;
  scope: TaskScope;
  /** 是否改变对外契约；改契约必须平台评审，不能由单方决定。 */
  changesExternalContract: boolean;
  /** 是否波及其他租户；波及即升级为共同决策。 */
  affectsOtherTenants: boolean;
  /** 是否需要跨团队预算或配额借用。 */
  requiresCrossTeamBudget: boolean;
}

export type OwnershipBasis =
  | "platform-wide"
  | "cross-tenant"
  | "external-contract"
  | "cross-team-budget"
  | "multi-caller-shared-artifact"
  | "single-caller-local"
  | "tenant-lifecycle";

export interface OwnershipDecision {
  taskId: string;
  side: OwnerSide;
  artifact: TaskArtifact;
  basis: readonly OwnershipBasis[];
}

const SHARED_ARTIFACTS: readonly TaskArtifact[] = [
  "contract",
  "version",
  "model",
  "quota",
  "evaluation",
];

/**
 * 判定顺序本身就是优先级：
 * 租户生命周期与对外契约先归共同决策，再看影响范围，
 * 最后才允许落到单调用方的业务自治。
 */
export function decideOwner(task: OwnershipTask): OwnershipDecision {
  const basis: OwnershipBasis[] = [];

  if (task.artifact === "tooling") {
    basis.push("platform-wide");
    return { taskId: task.id, side: "platform", artifact: task.artifact, basis };
  }
  if (task.artifact === "tenant") {
    basis.push("tenant-lifecycle");
    return { taskId: task.id, side: "shared", artifact: task.artifact, basis };
  }
  if (task.changesExternalContract) basis.push("external-contract");
  if (task.scope === "platform") basis.push("platform-wide");
  if (task.scope === "multiple-tenants") basis.push("cross-tenant");
  if (task.affectsOtherTenants && !basis.includes("cross-tenant")) basis.push("cross-tenant");
  if (task.requiresCrossTeamBudget) basis.push("cross-team-budget");
  if (
    task.scope === "multiple-callers"
    && SHARED_ARTIFACTS.includes(task.artifact)
    && !basis.includes("multi-caller-shared-artifact")
  ) {
    basis.push("multi-caller-shared-artifact");
  }

  if (basis.length > 0) {
    return { taskId: task.id, side: "shared", artifact: task.artifact, basis };
  }
  basis.push("single-caller-local");
  return { taskId: task.id, side: "business", artifact: task.artifact, basis };
}

/** 批量判定，顺序与输入一致；重复 id 直接拒绝，避免报告被同名任务覆盖。 */
export function decideOwners(tasks: readonly OwnershipTask[]): OwnershipDecision[] {
  const seen = new Set<string>();
  for (const task of tasks) {
    if (seen.has(task.id)) throw new Error(`duplicate task id: ${task.id}`);
    seen.add(task.id);
  }
  return tasks.map((task) => decideOwner(task));
}

/**
 * 职责表只分三列：平台负责、业务负责、共同决策。
 * artifact 是这张表的索引，同一 artifact 在不同 scope 下可以换列。
 */
export const RESPONSIBILITY_TABLE: Record<TaskArtifact, { platform: string; business: string; shared: string }> = {
  prompt: {
    platform: "提供提示版本登记、回放与回滚接口",
    business: "编写与调优本团队提示，记录版本与评测结果",
    shared: "跨能力共享提示模板的变更评审",
  },
  contract: {
    platform: "定义契约格式、兼容性检查与目录发布流程",
    business: "声明输入输出与失败语义，承担契约内容正确性",
    shared: "契约字段变更、主版本升级与弃用窗口",
  },
  quota: {
    platform: "维护三层配额、借用规则与耗尽行为",
    business: "在份额内分配调用方额度并监控用量",
    shared: "跨团队借用、总额调整与旺季保供排序",
  },
  version: {
    platform: "维护版本矩阵、弃用窗口与迁移清单",
    business: "决定升级节奏，完成本团队链路回归",
    shared: "跨所有者主版本迁移与强制下线",
  },
  model: {
    platform: "维护模型档案、选型基线与路由默认值",
    business: "在允许范围内选择档位并承担质量成本",
    shared: "默认模型变更、供应商切换与区域调整",
  },
  evaluation: {
    platform: "提供评测集目录、污染检查与回归门禁",
    business: "维护本链路样本与验收阈值",
    shared: "跨团队共享评测集与统一发布门禁",
  },
  incident: {
    platform: "提供事故分级、值班与跨租户影响面工具",
    business: "处置本链路事故，提交复盘与修复证据",
    shared: "跨租户事故定级、对外通告与联合复盘",
  },
  tenant: {
    platform: "提供租户开通、计量与级联删除能力",
    business: "确认业务范围与验收场景",
    shared: "租户开通、合同配额与数据保留条款",
  },
  tooling: {
    platform: "维护网关、配额、评测与审计等共享基础设施",
    business: "提交需求与集成问题，不直接改平台实现",
    shared: "平台 SLO 目标、重大工具选型与自助边界",
  },
};

export type BoundarySignalCode =
  | "business-edits-shared-default"
  | "platform-edits-business-prompt"
  | "business-bypasses-quota"
  | "platform-owns-business-kpi"
  | "shared-decision-without-record"
  | "active-capability-without-owner"
  | "version-contract-mismatch";

export interface BoundarySignal {
  code: BoundarySignalCode;
  /** 证据位置，例如评审单号、目录条目或告警 id。 */
  detail?: string;
}

export interface BoundaryAssessment {
  score: number;
  level: "clear" | "watch" | "violation";
  signals: readonly BoundarySignalCode[];
  reasons: readonly string[];
}

/**
 * 权重表达的是「越界后修复成本」，不是概率。
 * 绕过配额与私改共享默认值会直接破坏他人链路，权重最高。
 */
export const SIGNAL_WEIGHTS: Record<BoundarySignalCode, number> = {
  "business-bypasses-quota": 40,
  "business-edits-shared-default": 35,
  "platform-edits-business-prompt": 30,
  "version-contract-mismatch": 30,
  "platform-owns-business-kpi": 25,
  "active-capability-without-owner": 25,
  "shared-decision-without-record": 20,
};

const SIGNAL_TEXT: Record<BoundarySignalCode, string> = {
  "business-bypasses-quota": "业务绕过配额直接调用，平台失去限流与计量",
  "business-edits-shared-default": "业务私改共享默认值，其他调用方的基线被改写",
  "platform-edits-business-prompt": "平台直接改业务提示，业务失去质量责任主体",
  "version-contract-mismatch": "版本与契约不一致，调用方无法判断兼容性",
  "platform-owns-business-kpi": "平台替业务背 KPI，业务不再为结果负责",
  "active-capability-without-owner": "在役能力没有责任人，事故与退役无人承接",
  "shared-decision-without-record": "共同决策没有记录，事后无法追责与复现",
};

/**
 * 评分只做三档判定：0 为 clear，1–29 为 watch，30 及以上为 violation。
 * 同一信号重复出现只计一次，避免告警风暴把分数推满。
 */
export function assessBoundary(signals: readonly BoundarySignal[]): BoundaryAssessment {
  const seen = new Set<BoundarySignalCode>();
  const normalized: BoundarySignalCode[] = [];
  for (const signal of signals) {
    if (seen.has(signal.code)) continue;
    seen.add(signal.code);
    normalized.push(signal.code);
  }
  const ordered = normalized
    .slice()
    .sort((left, right) => SIGNAL_WEIGHTS[right] - SIGNAL_WEIGHTS[left] || left.localeCompare(right));
  const raw = ordered.reduce((sum, code) => sum + SIGNAL_WEIGHTS[code], 0);
  const score = Math.min(100, raw);
  const level = score === 0 ? "clear" : score < 30 ? "watch" : "violation";
  return {
    score,
    level,
    signals: ordered,
    reasons: ordered.map((code) => SIGNAL_TEXT[code]),
  };
}

/** 把评分结果压成一行，便于写进评审记录或告警正文。 */
export function describeBoundary(assessment: BoundaryAssessment): string {
  if (assessment.level === "clear") return "boundary=clear score=0";
  return `boundary=${assessment.level} score=${assessment.score} signals=${assessment.signals.join(",")}`;
}