@viccydev/pi-fpa 0.9.4 → 0.9.6

package/extensions/fpa-dashboard/decision-ledger-projector.ts

@@ -0,0 +1,323 @@
+import type { DashboardModuleBuild } from "./module-publisher.ts";
+import type { DashboardWidget, TableCell, TableDataset } from "./projector.ts";
+import type { DecisionEvent, DecisionPackage } from "./decision-package.ts";
+
+// ============================================================================
+// The decision ledger module.
+//
+// Answers "where did the approved decisions get to" — the question the
+// dashboard could not answer at all before, because confirming a strategy left
+// nothing behind to track.
+//
+// Spend is not computed here. It arrives measured, from the execution receipt
+// or the actuals source, and stays null when nothing has measured it yet. A
+// decision showing $0 spent looks like a decision nobody acted on, which is a
+// very different thing from one nobody has reported on.
+// ============================================================================
+
+const EVENT_TYPE_LABELS = {
+	approved: "批准",
+	parameters_locked: "参数锁定",
+	task_accepted: "任务接受",
+	task_completed: "任务完成",
+	parameter_adjusted: "参数调整",
+	threshold_breached: "阈值触发",
+	closed: "关闭",
+} as const;
+
+const TASK_STATUS_LABELS = {
+	not_started: "未开始",
+	in_progress: "进行中",
+	completed: "已完成",
+	adjusted: "已调整",
+	synced: "已同步",
+	configured: "已配置",
+	not_completed: "未完成",
+} as const;
+
+export interface DecisionSpend {
+	decision_id: string;
+	/** Measured spend to date, or null when nothing has measured it. */
+	actual_spend_usd: number | null;
+	/** 0..1 execution progress, or null when unknown. */
+	progress?: number | null;
+	/** Where the measurement came from, shown as evidence. */
+	source?: string;
+}
+
+export interface DecisionLedgerInput {
+	packages: DecisionPackage[];
+	events: Record<string, DecisionEvent[]>;
+	spend?: DecisionSpend[];
+	locale?: string;
+}
+
+export interface DecisionLedgerProjection {
+	module: DashboardModuleBuild;
+	/** Decisions whose measured spend has passed their approved threshold. */
+	breaches: Array<{ decision_id: string; title: string; over_pct: number }>;
+}
+
+function currency(value: number | null, code: string, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "currency", currency: code, maximumFractionDigits: 0 }).format(value);
+}
+
+function percent(value: number | null, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 }).format(value);
+}
+
+function toned(value: string | null, tone?: "positive" | "negative" | "warning" | "neutral"): TableCell {
+	return tone ? { value, tone } : value;
+}
+
+/**
+ * Over-budget fraction, or null when it cannot be computed.
+ *
+ * Returns null rather than 0 when the budget is missing or zero: "we cannot
+ * tell whether this is over budget" must not render as "this is exactly on
+ * budget", which is what a 0 here would claim.
+ */
+function overBudgetFraction(pkg: DecisionPackage, spend: number | null): number | null {
+	if (spend === null || pkg.approved_budget_usd === null || pkg.approved_budget_usd <= 0) return null;
+	return spend / pkg.approved_budget_usd - 1;
+}
+
+function summaryTable(
+	packages: DecisionPackage[],
+	spendById: Map<string, DecisionSpend>,
+	locale: string,
+): TableDataset {
+	return {
+		label: "决策归档包",
+		description: "已批准决策的批准预算、实际支出与执行进度",
+		columns: [
+			{ key: "decision", label: "决策包" },
+			{ key: "version", label: "版本" },
+			{ key: "approver", label: "批准人" },
+			{ key: "owner", label: "负责人" },
+			{ key: "budget", label: "批准预算", align: "right" },
+			{ key: "actual", label: "实际支出", align: "right" },
+			{ key: "variance", label: "偏差", align: "right" },
+			{ key: "progress", label: "执行进度", align: "right" },
+			{ key: "status", label: "状态" },
+		],
+		rows: packages.map((pkg) => {
+			const spend = spendById.get(pkg.decision_id);
+			const actual = spend?.actual_spend_usd ?? null;
+			const over = overBudgetFraction(pkg, actual);
+			const breached = over !== null && over > pkg.budget_threshold_pct;
+			return {
+				decision: `${pkg.decision_id} · ${pkg.title}`,
+				version: pkg.version,
+				approver: pkg.approver_role,
+				owner: pkg.owner,
+				budget: currency(pkg.approved_budget_usd, pkg.reporting_currency, locale),
+				actual: currency(actual, pkg.reporting_currency, locale),
+				variance: toned(
+					over === null ? null : `${over > 0 ? "+" : ""}${percent(over, locale)}`,
+					over === null ? undefined : breached ? "negative" : over > 0 ? "warning" : "positive",
+				),
+				progress: spend?.progress === null || spend?.progress === undefined ? null : percent(spend.progress, locale),
+				status: toned(
+					breached ? "超阈值" : spend?.progress === 1 ? "已完成" : "执行中",
+					breached ? "negative" : spend?.progress === 1 ? "positive" : "neutral",
+				),
+			};
+		}),
+	};
+}
+
+function approvalsTable(packages: DecisionPackage[]): TableDataset {
+	return {
+		label: "审批留痕",
+		description: "每个决策包的审批链与时间戳",
+		columns: [
+			{ key: "decision", label: "决策包" },
+			{ key: "step", label: "步骤", align: "right" },
+			{ key: "role", label: "角色" },
+			{ key: "approver", label: "审批人" },
+			{ key: "action", label: "动作" },
+			{ key: "at", label: "时间" },
+			{ key: "comment", label: "备注" },
+		],
+		rows: packages.flatMap((pkg) =>
+			pkg.approvals.map((approval) => ({
+				decision: pkg.decision_id,
+				step: String(approval.step_order),
+				role: approval.role,
+				approver: approval.approver,
+				action: approval.action === "approved" ? "批准" : approval.action === "acknowledged" ? "确认" : "驳回",
+				at: approval.decided_at,
+				comment: approval.comment ?? null,
+			})),
+		),
+	};
+}
+
+function tasksTable(packages: DecisionPackage[]): TableDataset {
+	return {
+		label: "执行任务清单",
+		columns: [
+			{ key: "decision", label: "决策包" },
+			{ key: "task", label: "任务" },
+			{ key: "owner", label: "负责人" },
+			{ key: "due", label: "截止" },
+			{ key: "status", label: "状态" },
+		],
+		rows: packages.flatMap((pkg) =>
+			pkg.tasks.map((task) => ({
+				decision: pkg.decision_id,
+				task: task.task_name,
+				owner: task.owner,
+				due: task.due_date,
+				status: toned(
+					TASK_STATUS_LABELS[task.status],
+					task.status === "completed" ? "positive" : task.status === "not_completed" ? "negative" : "neutral",
+				),
+			})),
+		),
+	};
+}
+
+function auditTable(packages: DecisionPackage[], events: Record<string, DecisionEvent[]>): TableDataset {
+	const rows = packages.flatMap((pkg) =>
+		(events[pkg.decision_id] ?? []).map((event) => ({
+			at: event.event_at,
+			decision: pkg.decision_id,
+			actor: `${event.actor}${event.actor_type === "system" ? " (系统)" : ""}`,
+			type: toned(
+				EVENT_TYPE_LABELS[event.event_type],
+				event.event_type === "threshold_breached" ? "negative" : event.event_type === "approved" ? "positive" : "neutral",
+			),
+			summary: event.summary,
+			reason: event.reason ?? null,
+			detail: event.change_detail ?? null,
+		})),
+	);
+	return {
+		label: "审计日志",
+		description: "谁在什么时候、因为什么、改了什么",
+		columns: [
+			{ key: "at", label: "时间" },
+			{ key: "decision", label: "决策包" },
+			{ key: "actor", label: "操作者" },
+			{ key: "type", label: "事件" },
+			{ key: "summary", label: "说明" },
+			{ key: "reason", label: "原因" },
+			{ key: "detail", label: "变更" },
+		],
+		// Newest first: the audit log is read to answer "what just happened".
+		rows: rows.sort((left, right) => String(right.at).localeCompare(String(left.at))),
+	};
+}
+
+export function projectDecisionLedger(input: DecisionLedgerInput): DecisionLedgerProjection {
+	const locale = input.locale ?? "zh-CN";
+	const packages = input.packages;
+	const spendById = new Map((input.spend ?? []).map((entry) => [entry.decision_id, entry]));
+	const warnings: string[] = [];
+
+	const breaches: DecisionLedgerProjection["breaches"] = [];
+	let unmeasured = 0;
+	for (const pkg of packages) {
+		const actual = spendById.get(pkg.decision_id)?.actual_spend_usd ?? null;
+		if (actual === null) {
+			unmeasured += 1;
+			continue;
+		}
+		const over = overBudgetFraction(pkg, actual);
+		if (over !== null && over > pkg.budget_threshold_pct) {
+			breaches.push({ decision_id: pkg.decision_id, title: pkg.title, over_pct: over });
+		}
+	}
+
+	// The limits belong to this module, next to the numbers they qualify.
+	if (unmeasured > 0) {
+		warnings.push(`${unmeasured} 个决策包尚无实际支出计量，其偏差与状态显示为缺失而非零。`);
+	}
+	for (const breach of breaches) {
+		warnings.push(`${breach.decision_id}「${breach.title}」实际支出超批准预算 ${(breach.over_pct * 100).toFixed(1)}%，已超过其阈值。`);
+	}
+	const missingBudget = packages.filter((pkg) => pkg.approved_budget_usd === null);
+	if (missingBudget.length > 0) {
+		warnings.push(`${missingBudget.length} 个决策包没有可追踪的批准预算，无法判断是否超支。`);
+	}
+
+	const measured = packages.length - unmeasured;
+	const widgets: DashboardWidget[] = [
+		{
+			id: "decision-active-count",
+			type: "stat",
+			span: "quarter",
+			dataset: "decision-active-count.json",
+			data: {
+				label: "进行中决策",
+				value: String(packages.filter((pkg) => (spendById.get(pkg.decision_id)?.progress ?? 0) < 1).length),
+				description: `共 ${packages.length} 个已批准决策包`,
+			},
+		},
+		{
+			id: "decision-breach-count",
+			type: "stat",
+			span: "quarter",
+			dataset: "decision-breach-count.json",
+			data: {
+				label: "需关注",
+				value: String(breaches.length),
+				...(breaches.length > 0
+					? { description: breaches.map((breach) => breach.decision_id).join("、") }
+					: {}),
+				...(measured === 0
+					? { footnote: "尚无实际支出计量，此计数仅覆盖已计量的决策包。" }
+					: {}),
+				delta: breaches.length > 0
+					? { direction: "up", label: `${breaches.length} 个超阈值`, sentiment: "negative" }
+					: { direction: "flat", label: "无超阈值", sentiment: "positive" },
+			},
+		},
+		{
+			id: "decision-measured-coverage",
+			type: "stat",
+			span: "quarter",
+			dataset: "decision-measured-coverage.json",
+			data: {
+				label: "支出计量覆盖",
+				value: packages.length === 0 ? null : `${measured}/${packages.length}`,
+				...(packages.length === 0 ? { missingReason: "还没有已批准的决策包。" } : {}),
+				...(packages.length > 0
+					? {
+						progress: {
+							fraction: measured / packages.length,
+							label: percent(measured / packages.length, locale) ?? "—",
+							tone: measured === packages.length ? "positive" : "warning",
+						},
+					}
+					: {}),
+			},
+		},
+		{ id: "decision-summary", type: "table", span: "full", dataset: "decision-summary.json", data: summaryTable(packages, spendById, locale) },
+		{ id: "decision-tasks", type: "table", span: "full", dataset: "decision-tasks.json", data: tasksTable(packages) },
+		{ id: "decision-approvals", type: "table", span: "full", dataset: "decision-approvals.json", data: approvalsTable(packages) },
+		{ id: "decision-audit", type: "table", span: "full", dataset: "decision-audit.json", data: auditTable(packages, input.events) },
+	];
+
+	return {
+		module: {
+			id: "decision-ledger",
+			title: "决策履约与审计",
+			status: "published",
+			source: {
+				artifact_type: "decision_package",
+				package_count: packages.length,
+				decision_ids: packages.map((pkg) => pkg.decision_id),
+				package_fingerprints: packages.map((pkg) => pkg.package_fingerprint),
+				measured_spend_count: measured,
+			},
+			warnings,
+			widgets,
+		},
+		breaches,
+	};
+}