《互联网产品的 AI 架构·平台化与治理》11.3 培训、文档与知识传递

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

import { daysBetween, isIsoDate } from "./review.ts";

/** 四层文档：入门讲为什么，操作讲怎么做，参考讲是什么，决策讲为什么这样定。 */
export type DocLayer = "onboarding" | "how-to" | "reference" | "decision";

const MAX_AGE_DAYS: Record<DocLayer, number> = {
  onboarding: 365, "how-to": 180, reference: 365, decision: 365,
};
const REGULATED_MAX_AGE_DAYS: Partial<Record<DocLayer, number>> = { "how-to": 90, reference: 90 };

/** 平台级入门文档用 "*" 作为能力标识，全站只有一份。 */
export const PLATFORM_SCOPE = "*";

export interface DocProfile { capability: string; currentMajor: number; regulated: boolean }

export interface CapabilityDoc {
  capability: string;
  layer: DocLayer;
  path: string;
  owner: string;
  reviewedAt: string;
  /** 参考文档必须钉住当前主版本；其余层可留空。 */
  pinnedMajor?: number;
}

export type DocGapCode =
  | "missing-doc" | "duplicate-doc" | "empty-owner" | "invalid-date"
  | "stale-doc" | "missing-version-pin" | "stale-version-pin";

export interface DocGap { capability: string; layer: DocLayer; code: DocGapCode; detail: string }

export interface DocsCoverage {
  totalSlots: number;
  coveredSlots: number;
  /** 向下取整的百分比，分母是必需文档槽位总数。 */
  coveragePercent: number;
  gaps: readonly DocGap[];
}

function maxAge(profile: DocProfile | undefined, layer: DocLayer): number {
  return profile?.regulated === true
    ? REGULATED_MAX_AGE_DAYS[layer] ?? MAX_AGE_DAYS[layer]
    : MAX_AGE_DAYS[layer];
}

/** 覆盖度按槽位算，不按文档篇数算：同一层写十篇也补不上缺的那一层。 */
export function assessDocs(
  profiles: readonly DocProfile[],
  docs: readonly CapabilityDoc[],
  asOf: string,
): DocsCoverage {
  const gaps: DocGap[] = [];
  const slots: { capability: string; layer: DocLayer; profile?: DocProfile }[] = [
    { capability: PLATFORM_SCOPE, layer: "onboarding" },
  ];
  for (const profile of profiles) {
    for (const layer of ["how-to", "reference", "decision"] as const) {
      slots.push({ capability: profile.capability, layer, profile });
    }
  }
  const gap = (capability: string, layer: DocLayer, code: DocGapCode, detail: string): void => {
    gaps.push({ capability, layer, code, detail });
  };
  const known = new Set(profiles.map((profile) => profile.capability));
  for (const doc of docs) {
    if (doc.capability !== PLATFORM_SCOPE && !known.has(doc.capability)) {
      gap(doc.capability, doc.layer, "missing-doc", "unknown capability");
    }
  }
  let covered = 0;
  for (const slot of slots) {
    const matches = docs.filter(
      (doc) => doc.capability === slot.capability && doc.layer === slot.layer,
    );
    if (matches.length !== 1) {
      gap(slot.capability, slot.layer, matches.length === 0 ? "missing-doc" : "duplicate-doc",
        `${matches.length} documents`);
      continue;
    }
    const doc = matches[0];
    let ok = true;
    if (doc.owner.trim() === "") { gap(slot.capability, slot.layer, "empty-owner", doc.path); ok = false; }
    if (!isIsoDate(doc.reviewedAt)) {
      gap(slot.capability, slot.layer, "invalid-date", `${doc.path} ${doc.reviewedAt}`);
      ok = false;
    } else {
      const age = daysBetween(doc.reviewedAt, asOf);
      const limit = maxAge(slot.profile, slot.layer);
      if (age > limit) {
        gap(slot.capability, slot.layer, "stale-doc", `${doc.path} is ${age} days, limit ${limit}`);
        ok = false;
      }
    }
    if (slot.layer === "reference") {
      const expected = slot.profile?.currentMajor;
      if (doc.pinnedMajor === undefined) {
        gap(slot.capability, slot.layer, "missing-version-pin", doc.path);
        ok = false;
      } else if (doc.pinnedMajor !== expected) {
        gap(slot.capability, slot.layer, "stale-version-pin",
          `${doc.path} pins v${doc.pinnedMajor}, current is v${expected}`);
        ok = false;
      }
    }
    if (ok) covered += 1;
  }
  return {
    totalSlots: slots.length,
    coveredSlots: covered,
    coveragePercent: Math.floor((covered / slots.length) * 100),
    gaps,
  };
}

export type TrainingStage = "read" | "shadow" | "supervised" | "solo";
const STAGE_RANK: Record<TrainingStage, number> = { read: 0, shadow: 1, supervised: 2, solo: 3 };

export interface TrainingStep {
  id: string;
  stage: TrainingStage;
  hours: number;
  /** 前置步骤 id，必须出现在当前步骤之前。 */
  requires?: string;
  /** 独立上线前的考核方式，例如 "盲评 20 条 + 回滚演练"。 */
  assessment?: string;
}

export type TrainingIssueCode =
  | "duplicate-step" | "empty-id" | "invalid-hours" | "stage-regression"
  | "unknown-prerequisite" | "forward-prerequisite" | "solo-missing-assessment"
  | "path-too-short" | "path-too-long";

export interface TrainingIssue { stepId: string; code: TrainingIssueCode; detail: string }
export interface TrainingPathResult { totalHours: number; steps: number; issues: readonly TrainingIssue[] }

/** 培训路径必须单调推进：读完再跟岗，跟岗后再受控独立，最后才独立。 */
export function validateTrainingPath(steps: readonly TrainingStep[]): TrainingPathResult {
  const issues: TrainingIssue[] = [];
  const seen = new Set<string>();
  let totalHours = 0;
  let previousRank = -1;
  for (const [index, step] of steps.entries()) {
    const push = (code: TrainingIssueCode, detail: string): void => {
      issues.push({ stepId: step.id, code, detail });
    };
    if (step.id.trim() === "") push("empty-id", "step id is empty");
    if (seen.has(step.id)) push("duplicate-step", "duplicate step id");
    seen.add(step.id);
    if (!Number.isInteger(step.hours) || step.hours <= 0) push("invalid-hours", `${step.hours}`);
    else totalHours += step.hours;
    const rank = STAGE_RANK[step.stage];
    if (rank < previousRank) push("stage-regression", `${step.stage} after a later stage`);
    previousRank = Math.max(previousRank, rank);
    if (step.stage === "solo" && (step.assessment ?? "").trim() === "") {
      push("solo-missing-assessment", "solo step needs an assessment");
    }
    if (step.requires !== undefined) {
      const prerequisite = steps.findIndex((item) => item.id === step.requires);
      if (prerequisite === -1) push("unknown-prerequisite", step.requires);
      else if (prerequisite >= index) push("forward-prerequisite", step.requires);
    }
  }
  if (totalHours < 8) issues.push({ stepId: "", code: "path-too-short", detail: `${totalHours}h` });
  if (totalHours > 60) issues.push({ stepId: "", code: "path-too-long", detail: `${totalHours}h` });
  return { totalHours, steps: steps.length, issues };
}

export interface OnboardingRecord {
  engineer: string;
  capability: string;
  startedAt: string;
  /** 第一次独立上线并通过复核的日期；未独立则留空。 */
  firstIndependentAt?: string;
  reviewPassed: boolean;
  /** 上线过程中需要他人接手的次数；超过 1 次不算独立。 */
  interventions: number;
  docsUpdated: boolean;
}

export interface LiveReadiness {
  engineer: string;
  ready: boolean;
  reasons: readonly string[];
  days?: number;
}

/** 独立上线的判定是四个条件的合取，不是主管的一句「差不多了」。 */
export function liveReadiness(record: OnboardingRecord): LiveReadiness {
  const reasons: string[] = [];
  let days: number | undefined;
  if (record.firstIndependentAt === undefined) {
    reasons.push("no independent change");
  } else if (!isIsoDate(record.startedAt) || !isIsoDate(record.firstIndependentAt)) {
    reasons.push("invalid dates");
  } else {
    days = daysBetween(record.startedAt, record.firstIndependentAt);
    if (days < 0) reasons.push("independent date precedes start");
  }
  if (!record.reviewPassed) reasons.push("review not passed");
  if (record.interventions > 1) reasons.push(`interventions ${record.interventions} > 1`);
  if (!record.docsUpdated) reasons.push("docs not updated");
  return {
    engineer: record.engineer, ready: reasons.length === 0, reasons,
    ...(days !== undefined && days >= 0 ? { days } : {}),
  };
}

export interface OnboardingStats {
  cohort: number;
  independent: number;
  pending: number;
  /** 偶数样本取中间两天的平均值，因此可能是 .5 天。 */
  medianDays: number | null;
  p90Days: number | null;
  targetDays: number;
  verdict: "on-target" | "over-target" | "insufficient-sample";
}

export function onboardingStats(
  records: readonly OnboardingRecord[],
  targetDays = 30,
): OnboardingStats {
  const days = records.map(liveReadiness)
    .filter((item) => item.ready && item.days !== undefined)
    .map((item) => item.days as number)
    .sort((a, b) => a - b);
  const independent = days.length;
  const pending = records.length - independent;
  if (independent === 0) {
    return { cohort: records.length, independent, pending, medianDays: null, p90Days: null,
      targetDays, verdict: records.length < 3 ? "insufficient-sample" : "over-target" };
  }
  const mid = Math.floor(independent / 2);
  const medianDays = independent % 2 === 1 ? days[mid] : (days[mid - 1] + days[mid]) / 2;
  const p90Days = days[Math.min(independent - 1, Math.ceil(independent * 0.9) - 1)];
  return {
    cohort: records.length, independent, pending, medianDays, p90Days, targetDays,
    verdict: records.length < 3 ? "insufficient-sample"
      : medianDays <= targetDays ? "on-target" : "over-target",
  };
}