《互联网产品的 AI 架构·平台化与治理》10.1 平台的自助服务边界

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

/** 平台请求分两类：能自助完成的，和必须有人拍板的。 */
export type RequestKind =
  | "enable-capability"
  | "set-team-quota"
  | "view-billing"
  | "run-evaluation"
  | "launch-capability"
  | "cross-tenant-borrow"
  | "compliance-exception";

export type ServiceRoute = "self-service" | "manual";
export type CorpusPrivacy = "public" | "tenant" | "restricted";

export interface PlatformPolicy {
  /** 已通过准入、允许业务方自助开通的能力。 */
  approvedCapabilities: readonly string[];
  /** 自助开通允许选择的档位；frontier 默认不进自助。 */
  selfServiceTiers: readonly string[];
  /** 团队可自助调整的份额上限；超过即转人工。 */
  maxSelfServiceQuotaMicros: number;
  /** 单次评测的预算上限，防止评测把生产预算跑穿。 */
  evalBudgetMicros: number;
}

export interface ServiceRequest {
  kind: RequestKind;
  capability?: string;
  tier?: string;
  requestedQuotaMicros?: number;
  tenantRemainingMicros?: number;
  corpusPrivacy?: CorpusPrivacy;
  evalCostMicros?: number;
}

export interface RouteDecision {
  kind: RequestKind;
  route: ServiceRoute;
  /** 自助为 0；人工为首次响应的时限，单位小时。 */
  slaHours: number;
  dueAtMs: number;
  reason: string;
  escalation: string;
}

/** 人工请求的首次响应时限；时限是承诺，不是审批必然通过的保证。 */
export const MANUAL_SLA_HOURS: Record<RequestKind, number> = {
  "enable-capability": 240,
  "set-team-quota": 24,
  "view-billing": 0,
  "run-evaluation": 24,
  "launch-capability": 240,
  "cross-tenant-borrow": 24,
  "compliance-exception": 120,
};

const HOUR_MS = 3_600_000;

function isNonNegativeInteger(value: number | undefined): value is number {
  return value !== undefined && Number.isInteger(value) && value >= 0;
}

function decide(
  request: ServiceRequest,
  route: ServiceRoute,
  reason: string,
  nowMs: number,
): RouteDecision {
  const slaHours = route === "self-service" ? 0 : MANUAL_SLA_HOURS[request.kind];
  return {
    kind: request.kind,
    route,
    slaHours,
    dueAtMs: nowMs + slaHours * HOUR_MS,
    reason,
    escalation: route === "self-service" ? "无需审批" : "超时升级至平台值班与对应负责人",
  };
}

/**
 * 路由只看四件事：动作是否在准入目录内、档位是否开放、额度是否在自助上限内、
 * 语料是否允许跨团队可见。任何一项越界就转人工，不在自助界面里做例外。
 */
export function routeRequest(
  policy: PlatformPolicy,
  request: ServiceRequest,
  nowMs: number,
): RouteDecision {
  switch (request.kind) {
    case "view-billing":
      return decide(request, "self-service", "read-only", nowMs);

    case "enable-capability": {
      const capability = request.capability ?? "";
      if (!policy.approvedCapabilities.includes(capability)) {
        return decide(request, "manual", "capability-not-approved", nowMs);
      }
      if (!policy.selfServiceTiers.includes(request.tier ?? "")) {
        return decide(request, "manual", "tier-requires-review", nowMs);
      }
      return decide(request, "self-service", "approved-catalog", nowMs);
    }

    case "set-team-quota": {
      const requested = request.requestedQuotaMicros;
      const remaining = request.tenantRemainingMicros;
      if (!isNonNegativeInteger(requested) || !isNonNegativeInteger(remaining)) {
        return decide(request, "manual", "invalid-quota", nowMs);
      }
      if (requested > policy.maxSelfServiceQuotaMicros) {
        return decide(request, "manual", "above-self-service-ceiling", nowMs);
      }
      if (requested > remaining) {
        return decide(request, "manual", "tenant-capacity", nowMs);
      }
      return decide(request, "self-service", "within-ceiling", nowMs);
    }

    case "run-evaluation": {
      if (request.corpusPrivacy === "restricted") {
        return decide(request, "manual", "restricted-corpus", nowMs);
      }
      if (!isNonNegativeInteger(request.evalCostMicros)) {
        return decide(request, "manual", "invalid-eval-cost", nowMs);
      }
      if (request.evalCostMicros > policy.evalBudgetMicros) {
        return decide(request, "manual", "above-eval-budget", nowMs);
      }
      return decide(request, "self-service", "public-or-tenant-corpus", nowMs);
    }

    case "launch-capability":
      return decide(request, "manual", "new-capability-onboarding", nowMs);

    case "cross-tenant-borrow":
      return decide(request, "manual", "cross-tenant-transfer", nowMs);

    case "compliance-exception":
      return decide(request, "manual", "compliance-exception", nowMs);
  }
}

/** 超时只改变升级对象，不自动批准；自助请求的时限恒为 0。 */
export function overdueRequests(
  decisions: readonly RouteDecision[],
  nowMs: number,
): RouteDecision[] {
  return decisions.filter(
    (decision) => decision.route === "manual" && decision.dueAtMs <= nowMs,
  );
}

/** 自助覆盖率的分母是全部请求，不是人工请求；它衡量的是边界是否划得够宽。 */
export function selfServiceRatio(decisions: readonly RouteDecision[]): number {
  if (decisions.length === 0) return 0;
  return decisions.filter((decision) => decision.route === "self-service").length / decisions.length;
}