《互联网产品的 AI 架构·平台化与治理》8.1 数据分级与出域

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

export type DataClass = "public" | "internal" | "sensitive" | "restricted";
export type EgressMode = "public-api" | "private-endpoint" | "in-region-vpc" | "self-hosted";
export type TrainingUse = "no-train" | "aggregate-only" | "allowed";

export const DATA_CLASS_RANK: Record<DataClass, number> = { public: 0, internal: 1, sensitive: 2, restricted: 3 };
export const TRAINING_RANK: Record<TrainingUse, number> = { "no-train": 0, "aggregate-only": 1, allowed: 2 };

export interface EgressPolicy {
  allowedEgress: readonly EgressMode[];
  allowedRegions: readonly string[];
  maxRetentionDays: number;
  allowedTraining: readonly TrainingUse[];
}

/** 示例策略，不是法律意见；生产值由合规评审确认后写入配置。 */
export const EGRESS_POLICY: Record<DataClass, EgressPolicy> = {
  public: {
    allowedEgress: ["public-api", "private-endpoint", "in-region-vpc", "self-hosted"],
    allowedRegions: ["*"], maxRetentionDays: 365,
    allowedTraining: ["no-train", "aggregate-only", "allowed"],
  },
  internal: {
    allowedEgress: ["private-endpoint", "in-region-vpc", "self-hosted"],
    allowedRegions: ["*"], maxRetentionDays: 180,
    allowedTraining: ["no-train", "aggregate-only"],
  },
  sensitive: {
    allowedEgress: ["private-endpoint", "in-region-vpc", "self-hosted"],
    allowedRegions: ["cn", "sg"], maxRetentionDays: 30, allowedTraining: ["no-train"],
  },
  restricted: {
    allowedEgress: ["in-region-vpc", "self-hosted"],
    allowedRegions: ["cn"], maxRetentionDays: 7, allowedTraining: ["no-train"],
  },
};

export interface FieldClass { field: string; dataClass: DataClass }

export interface PayloadClass { dataClass: DataClass; highest: readonly FieldClass[] }

/** 载荷按字段逐项标注，整包级别取最高项；空载荷没有证据，按 internal 处理。 */
export function classifyPayload(fields: readonly FieldClass[]): PayloadClass {
  if (fields.length === 0) return { dataClass: "internal", highest: [] };
  const top = Math.max(...fields.map((item) => DATA_CLASS_RANK[item.dataClass]));
  const dataClass = (Object.keys(DATA_CLASS_RANK) as DataClass[]).find((item) => DATA_CLASS_RANK[item] === top)!;
  return { dataClass, highest: fields.filter((item) => DATA_CLASS_RANK[item.dataClass] === top) };
}

export interface CapabilityDataProfile {
  capability: string;
  maxDataClass: DataClass;
  declaredEgress: readonly EgressMode[];
  declaredRegions: readonly string[];
  retentionDays: number;
  trainingUse: TrainingUse;
}

export interface RouteRequest {
  capability: string;
  dataClass: DataClass;
  region: string;
  egress: EgressMode;
  providerRegion: string;
  retentionDays: number;
  trainingUse: TrainingUse;
}

export type RouteIssueCode =
  | "unknown-capability" | "data-class-exceeds-capability" | "egress-forbidden"
  | "egress-undeclared" | "region-forbidden" | "region-undeclared"
  | "provider-region-mismatch" | "retention-too-long" | "retention-exceeds-declaration"
  | "training-not-allowed" | "training-exceeds-declaration";

export interface RouteIssue { capability: string; code: RouteIssueCode; detail: string }

export interface RouteDecision {
  capability: string;
  dataClass: DataClass;
  allowed: boolean;
  requiredEgress: readonly EgressMode[];
  issues: RouteIssue[];
}

function coversRegion(regions: readonly string[], region: string): boolean {
  return regions.includes("*") || regions.includes(region);
}

/** 路由前校验：数据级别、出域方式、区域、留存与训练用途五项必须同时成立。 */
export function checkRoute(profiles: readonly CapabilityDataProfile[], request: RouteRequest): RouteDecision {
  const policy = EGRESS_POLICY[request.dataClass];
  const issues: RouteIssue[] = [];
  const push = (code: RouteIssueCode, detail: string): void => { issues.push({ capability: request.capability, code, detail }); };
  const profile = profiles.find((item) => item.capability === request.capability);
  if (profile === undefined) {
    push("unknown-capability", `${request.capability} is not declared in the catalog`);
    return { capability: request.capability, dataClass: request.dataClass, allowed: false, requiredEgress: policy.allowedEgress, issues };
  }
  if (DATA_CLASS_RANK[request.dataClass] > DATA_CLASS_RANK[profile.maxDataClass]) {
    push("data-class-exceeds-capability", `${request.dataClass} exceeds declared ${profile.maxDataClass}`);
  }
  if (!policy.allowedEgress.includes(request.egress)) push("egress-forbidden", `${request.egress} is not allowed for ${request.dataClass}`);
  if (!profile.declaredEgress.includes(request.egress)) push("egress-undeclared", `${request.egress} is not declared by ${request.capability}`);
  if (!coversRegion(policy.allowedRegions, request.region)) push("region-forbidden", `${request.region} is outside the ${request.dataClass} region set`);
  if (!coversRegion(profile.declaredRegions, request.region)) push("region-undeclared", `${request.region} is not declared by ${request.capability}`);
  if (request.providerRegion !== request.region) push("provider-region-mismatch", `provider serves ${request.providerRegion}, request requires ${request.region}`);
  if (request.retentionDays > policy.maxRetentionDays) push("retention-too-long", `${request.retentionDays}d exceeds the ${policy.maxRetentionDays}d cap`);
  if (request.retentionDays > profile.retentionDays) push("retention-exceeds-declaration", `${request.retentionDays}d exceeds the ${profile.retentionDays}d declaration`);
  if (!policy.allowedTraining.includes(request.trainingUse)) push("training-not-allowed", `${request.trainingUse} is not allowed for ${request.dataClass}`);
  if (TRAINING_RANK[request.trainingUse] > TRAINING_RANK[profile.trainingUse]) push("training-exceeds-declaration", `${request.trainingUse} is looser than ${profile.trainingUse}`);
  return { capability: request.capability, dataClass: request.dataClass, allowed: issues.length === 0, requiredEgress: policy.allowedEgress, issues };
}

/** 在给定数据级别下，哪些能力仍有资格承接。用于降级与替代路由。 */
export function eligibleCapabilities(profiles: readonly CapabilityDataProfile[], dataClass: DataClass): CapabilityDataProfile[] {
  return profiles.filter((item) => DATA_CLASS_RANK[item.maxDataClass] >= DATA_CLASS_RANK[dataClass]);
}

export interface RouteSummary { total: number; allowed: number; blocked: number; byCode: Record<string, number> }

export function summarizeRoutes(decisions: readonly RouteDecision[]): RouteSummary {
  const byCode: Record<string, number> = {};
  for (const decision of decisions) for (const issue of decision.issues) byCode[issue.code] = (byCode[issue.code] ?? 0) + 1;
  const allowed = decisions.filter((decision) => decision.allowed).length;
  return { total: decisions.length, allowed, blocked: decisions.length - allowed, byCode };
}