《互联网产品的 AI 架构·平台化与治理》4.2 公平性与优先级

score = valueWeight[value] + basePriority + min(waitTicks, maxAgingTicks) * agingPerTick
        + (waitTicks >= starvationTicks ? 10000 : 0)

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

/** 任务价值分类是公平判据的第一层，不直接用「谁先到」。 */
export type ValueClass = "critical" | "standard" | "batch";

export interface FairTask {
  taskId: string;
  tenantId: string;
  teamId: string;
  value: ValueClass;
  /** 业务声明的基础优先级，0..100；它不能越过价值分类。 */
  basePriority: number;
  waitTicks: number;
  costMicros: number;
}

export interface FairnessPolicy {
  valueWeight: Readonly<Record<ValueClass, number>>;
  agingPerTick: number;
  maxAgingTicks: number;
  /** 单轮中每个租户、每个团队最多被选中的任务数。 */
  perTenantWindow: number;
  perTeamWindow: number;
  /** 等待超过该 tick 数的任务强制进入候选。 */
  starvationTicks: number;
  /** 单轮每租户最多强制几个任务，防止饥饿防护变成新的插队。 */
  maxForced: number;
}

export const DEFAULT_FAIRNESS: FairnessPolicy = {
  valueWeight: { critical: 1000, standard: 300, batch: 100 },
  agingPerTick: 40,
  maxAgingTicks: 10,
  perTenantWindow: 2,
  perTeamWindow: 2,
  starvationTicks: 12,
  maxForced: 1,
};

export interface RankedTask {
  task: FairTask;
  score: number;
  forced: boolean;
}

/**
 * 分数 = 价值权重 + 基础优先级 + 有上限的老化 + 强制位。
 * 价值权重量级远大于优先级，保证 critical 不会被 batch 的高 basePriority 反转。
 */
export function scoreTask(task: FairTask, policy: FairnessPolicy): RankedTask {
  const aged = Math.min(task.waitTicks, policy.maxAgingTicks) * policy.agingPerTick;
  const forced = task.waitTicks >= policy.starvationTicks;
  const score = policy.valueWeight[task.value] + task.basePriority + aged + (forced ? 10_000 : 0);
  return { task, score, forced };
}

export function rankTasks(tasks: readonly FairTask[], policy: FairnessPolicy): RankedTask[] {
  return tasks
    .map((task) => scoreTask(task, policy))
    .sort((left, right) => {
      if (right.score !== left.score) return right.score - left.score;
      return left.task.taskId.localeCompare(right.task.taskId);
    });
}

export interface ScheduleResult {
  admitted: FairTask[];
  deferred: FairTask[];
  order: string[];
  spentMicros: number;
  byTenant: Record<string, { count: number; micros: number }>;
  byTeam: Record<string, { count: number; micros: number }>;
}

function bump(
  table: Record<string, { count: number; micros: number }>,
  key: string,
  micros: number,
): void {
  const bucket = table[key] ?? { count: 0, micros: 0 };
  bucket.count += 1;
  bucket.micros += micros;
  table[key] = bucket;
}

/**
 * 单轮调度：按分数选任务，租户与团队各有一个窗口上限。
 * 容量不够时跳过当前任务继续看后面的小任务，而不是整轮结束。
 */
export function scheduleRound(
  tasks: readonly FairTask[],
  capacityMicros: number,
  policy: FairnessPolicy = DEFAULT_FAIRNESS,
): ScheduleResult {
  const ranked = rankTasks(tasks, policy);
  const admitted: FairTask[] = [];
  const deferred: FairTask[] = [];
  const byTenant: ScheduleResult["byTenant"] = {};
  const byTeam: ScheduleResult["byTeam"] = {};
  const forcedByTenant: Record<string, number> = {};
  let spent = 0;
  for (const entry of ranked) {
    const task = entry.task;
    const tenant = byTenant[task.tenantId] ?? { count: 0, micros: 0 };
    const team = byTeam[task.teamId] ?? { count: 0, micros: 0 };
    const forcedUsed = forcedByTenant[task.tenantId] ?? 0;
    const forcedBlocked = entry.forced && forcedUsed >= policy.maxForced;
    if (
      forcedBlocked ||
      tenant.count >= policy.perTenantWindow ||
      team.count >= policy.perTeamWindow ||
      task.costMicros > capacityMicros - spent
    ) {
      deferred.push(task);
      continue;
    }
    admitted.push(task);
    if (entry.forced) forcedByTenant[task.tenantId] = forcedUsed + 1;
    spent += task.costMicros;
    bump(byTenant, task.tenantId, task.costMicros);
    bump(byTeam, task.teamId, task.costMicros);
  }
  return {
    admitted,
    deferred,
    order: admitted.map((task) => task.taskId),
    spentMicros: spent,
    byTenant,
    byTeam,
  };
}

/** 公平性验收：单租户占用不超过「均分 + 一个任务」视为通过。 */
export function maxTenantDeviation(result: ScheduleResult): number {
  const values = Object.values(result.byTenant).map((item) => item.micros);
  if (values.length === 0) return 0;
  const max = Math.max(...values);
  const min = Math.min(...values);
  return max - min;
}