@viccydev/pi-fpa 0.9.4 → 0.9.6

package/README.md

@@ -159,12 +159,12 @@ pi list
 团队分发建议使用固定 Git tag：
 
 ```bash
-pi install git:github.com/linyqh/pi-fpa@v0.9.4
+pi install git:github.com/linyqh/pi-fpa@v0.9.6
 ```
 
 ## 发布到 npm
 
-发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.4` 对应 `v0.9.4`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
+发布动作由 GitHub Release 触发。Release 标签必须严格使用 `v<package.json version>`，例如版本 `0.9.6` 对应 `v0.9.6`。工作流会检出该标签，执行 `npm ci`、`npm test` 和包内容预检，全部通过后发布公开包 `@viccydev/pi-fpa`。普通 Release 发布到 `latest`，Prerelease 发布到 `next`。
 
 发布认证使用 npm Trusted Publishing / OIDC，不使用长期 npm Token。npm 包后台的 Trusted Publisher 配置为：
 

package/extensions/fpa-dashboard/calibration-projector.ts

@@ -0,0 +1,359 @@
+import { realpath } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import { runStructuredQuery } from "../fpa-data/runtime.ts";
+import type { DashboardModuleBuild } from "./module-publisher.ts";
+import type { DashboardWidget, TableCell, WaterfallDataset } from "./projector.ts";
+
+// ============================================================================
+// The calibration module.
+//
+// The system already computed MAPE and then did nothing with it. A model
+// accuracy figure that does not lead anywhere is decoration; the point of
+// measuring error is to correct the assumption that produced it. So this
+// module ends in a proposal — which baseline to move, by how much, worth how
+// much over a year, and who has to approve it.
+//
+// Two things it must not do:
+//
+//   * Treat a pending correction as applied. A proposal is a claim awaiting
+//     an approver, and showing it as fact would let the model silently
+//     re-baseline itself.
+//
+//   * Present a partial decomposition as complete. When named factors do not
+//     account for the whole variance, the remainder is shown as unexplained.
+//     Dropping it makes the attribution look total when it is not.
+// ============================================================================
+
+/** Horizons are different claims about the same month; never pooled. */
+const DEFAULT_HORIZON = 3;
+
+export interface CalibrationOptions {
+	metric?: string;
+	horizonMonths?: number;
+	/** Which month to decompose. Defaults to the latest one with actuals. */
+	month?: string;
+	locale?: string;
+	signal?: AbortSignal;
+	cwd?: string;
+}
+
+export interface CalibrationProjection {
+	module: DashboardModuleBuild;
+	mape: number | null;
+	/** Consecutive months the forecast erred in the same direction. */
+	biasRun: { direction: "over" | "under" | "none"; months: number };
+	pendingCorrections: number;
+}
+
+function currency(value: number | null, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "currency", currency: "USD", maximumFractionDigits: 0 }).format(value);
+}
+
+function percent(value: number | null, locale: string, digits = 1): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: digits }).format(value);
+}
+
+function toned(value: string | null, tone?: "positive" | "negative" | "warning" | "neutral"): TableCell {
+	return tone ? { value, tone } : value;
+}
+
+function num(row: Record<string, unknown> | undefined, key: string): number | null {
+	const value = row?.[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function str(row: Record<string, unknown> | undefined, key: string): string | null {
+	const value = row?.[key];
+	return typeof value === "string" && value !== "" ? value : null;
+}
+
+/**
+ * How many consecutive recent months erred the same way.
+ *
+ * A single bad month is noise; a run in one direction is a model that is
+ * wrong in a fixable way. That distinction is the whole trigger for proposing
+ * a baseline change, so it is computed rather than eyeballed.
+ */
+function biasRun(rows: Array<Record<string, unknown>>): { direction: "over" | "under" | "none"; months: number } {
+	const ordered = rows.slice().sort((left, right) => String(right.month).localeCompare(String(left.month)));
+	let direction: "over" | "under" | "none" = "none";
+	let months = 0;
+	for (const row of ordered) {
+		const variance = num(row, "variance");
+		if (variance === null || variance === 0) break;
+		// Actual below forecast means the forecast was optimistic.
+		const step = variance < 0 ? "over" : "under";
+		if (direction === "none") direction = step;
+		else if (direction !== step) break;
+		months += 1;
+	}
+	return months === 0 ? { direction: "none", months: 0 } : { direction, months };
+}
+
+function attributionWaterfall(
+	rows: Array<Record<string, unknown>>,
+	month: string,
+	forecast: number | null,
+	actual: number | null,
+	locale: string,
+): WaterfallDataset {
+	const factors = rows
+		.slice()
+		.sort((left, right) => Math.abs(num(right, "impact_usd") ?? 0) - Math.abs(num(left, "impact_usd") ?? 0));
+	return {
+		label: "偏差归因",
+		description: "从预测到实际，逐项拆解差在哪里",
+		coverage: month,
+		steps: [
+			{ label: "预测", value: forecast, display: currency(forecast, locale), kind: "total" },
+			...factors.map((row) => {
+				const impact = num(row, "impact_usd");
+				const unexplained = str(row, "category") === "unexplained";
+				return {
+					label: str(row, "factor") ?? "(未命名)",
+					value: impact,
+					display: currency(impact, locale),
+					kind: "delta" as const,
+					// The residual is called out rather than blending in with
+					// the causes someone actually identified.
+					...(unexplained ? { tone: "warning" as const } : {}),
+				};
+			}),
+			{ label: "实际", value: actual, display: currency(actual, locale), kind: "total" },
+		],
+	};
+}
+
+export async function projectCalibration(options: CalibrationOptions = {}): Promise<CalibrationProjection> {
+	const locale = options.locale ?? "zh-CN";
+	const metric = options.metric ?? "net_fcf";
+	const horizon = options.horizonMonths ?? DEFAULT_HORIZON;
+	const workspaceRoot = options.cwd ? dirname(await realpath(options.cwd)) : undefined;
+	const warnings: string[] = [];
+
+	const accuracy = await runStructuredQuery({
+		dataset: "forecast_vs_actual",
+		metrics: ["forecast_value", "actual_value", "variance", "variance_pct", "abs_pct_error"],
+		dimensions: ["month"],
+		filters: { metric, forecast_age_months: String(horizon) },
+		limit: 60,
+	}, options.signal, workspaceRoot);
+	const months = accuracy.rows.slice().sort((left, right) => String(left.month).localeCompare(String(right.month)));
+	if (months.length === 0) throw new Error(`No forecast-versus-actual rows for ${metric} at a ${horizon}-month horizon.`);
+
+	const errors = months.map((row) => num(row, "abs_pct_error")).filter((value): value is number => value !== null);
+	const mape = errors.length === 0 ? null : errors.reduce((sum, value) => sum + value, 0) / errors.length;
+	const run = biasRun(months);
+	const requested = options.month ? months.find((row) => String(row.month) === options.month) : undefined;
+	if (options.month && !requested) {
+		throw new Error(`No forecast-versus-actual row for ${options.month} at a ${horizon}-month horizon.`);
+	}
+	const latest = requested ?? months.at(-1)!;
+	const latestMonth = String(latest.month);
+
+	const attribution = await runStructuredQuery({
+		dataset: "variance_attribution",
+		metrics: ["impact_usd", "impact_share", "confidence"],
+		dimensions: ["factor", "category", "confidence_band"],
+		filters: { month: latestMonth, metric },
+		limit: 32,
+	}, options.signal, workspaceRoot);
+
+	const explained = attribution.rows
+		.filter((row) => str(row, "category") !== "unexplained")
+		.reduce((sum, row) => sum + (num(row, "impact_usd") ?? 0), 0);
+	const totalVariance = num(latest, "variance");
+	const coverage = totalVariance === null || totalVariance === 0 ? null : explained / totalVariance;
+	if (coverage !== null && coverage < 0.99) {
+		warnings.push(`${latestMonth} 的偏差仅 ${percent(coverage, locale)} 被具名因子解释，其余为未归因残差。`);
+	}
+
+	if (run.months >= 3) {
+		warnings.push(
+			`预测在最近 ${run.months} 个月连续${run.direction === "over" ? "高估" : "低估"}，属于系统性偏差而非噪声，应校准基准假设。`,
+		);
+	}
+
+	const assumptions = await runStructuredQuery({
+		dataset: "baseline_assumptions",
+		metrics: ["current_value", "suggested_value", "estimated_impact_usd_12m"],
+		dimensions: ["assumption_id", "assumption_name", "scope", "unit", "detection_basis", "affected_models", "approval_status", "approver_role"],
+		limit: 64,
+	}, options.signal, workspaceRoot);
+	const pending = assumptions.rows.filter((row) => str(row, "approval_status") === "pending");
+	if (pending.length > 0) {
+		warnings.push(`${pending.length} 项基准修正待审批，尚未生效——当前预测仍使用旧基准。`);
+	}
+
+	const widgets: DashboardWidget[] = [
+		{
+			id: "calibration-mape",
+			type: "stat",
+			span: "quarter",
+			dataset: "calibration-mape.json",
+			data: {
+				label: "模型准确率",
+				value: mape === null ? null : percent(1 - mape, locale),
+				...(mape === null ? { missingReason: "尚无可比的已结账周期。" } : {}),
+				description: `MAPE ${percent(mape, locale) ?? "—"} · ${horizon} 个月前预测 · ${errors.length} 个样本`,
+				...(mape !== null
+					? { progress: { fraction: Math.max(0, Math.min(1, 1 - mape)), label: percent(1 - mape, locale) ?? "—", tone: (mape <= 0.05 ? "positive" : "warning") as "positive" | "warning" } }
+					: {}),
+			},
+		},
+		{
+			id: "calibration-bias",
+			type: "stat",
+			span: "quarter",
+			dataset: "calibration-bias.json",
+			data: {
+				label: "偏差方向",
+				value: run.direction === "none" ? "无连续偏差" : run.direction === "over" ? "连续高估" : "连续低估",
+				description: run.months > 0 ? `最近 ${run.months} 个月同向` : "最近一期与预测同向或持平",
+				delta: run.months >= 3
+					? { direction: "up" as const, label: `${run.months} 个月`, sentiment: "negative" as const }
+					: { direction: "flat" as const, label: `${run.months} 个月`, sentiment: "neutral" as const },
+				// A run is what separates a fixable model from a noisy month.
+				footnote: "连续 3 个月及以上同向即视为系统性偏差",
+			},
+		},
+		{
+			id: "calibration-variance",
+			type: "stat",
+			span: "quarter",
+			dataset: "calibration-variance.json",
+			data: {
+				label: `${latestMonth} 偏差`,
+				value: currency(totalVariance, locale),
+				description: `实际 ${currency(num(latest, "actual_value"), locale) ?? "—"} vs 预测 ${currency(num(latest, "forecast_value"), locale) ?? "—"}`,
+				...(num(latest, "variance_pct") !== null
+					? { delta: { direction: (num(latest, "variance_pct")! >= 0 ? "up" : "down") as "up" | "down", label: percent(num(latest, "variance_pct"), locale) ?? "", sentiment: (num(latest, "variance_pct")! >= 0 ? "positive" : "negative") as "positive" | "negative" } }
+					: {}),
+			},
+		},
+		{
+			id: "calibration-coverage",
+			type: "stat",
+			span: "quarter",
+			dataset: "calibration-coverage.json",
+			data: {
+				label: "归因覆盖率",
+				value: percent(coverage, locale),
+				...(coverage === null ? { missingReason: "该月偏差为零或不可计算。" } : {}),
+				...(coverage !== null
+					? { progress: { fraction: Math.max(0, Math.min(1, coverage)), label: percent(coverage, locale) ?? "—", tone: (coverage >= 0.99 ? "positive" : "warning") as "positive" | "warning" } }
+					: {}),
+				footnote: coverage !== null && coverage < 0.99 ? "其余为未归因残差，已在瀑布图中单列" : undefined,
+			},
+		},
+		{
+			id: "calibration-attribution",
+			type: "waterfall",
+			span: "full",
+			dataset: "calibration-attribution.json",
+			data: attributionWaterfall(attribution.rows, latestMonth, num(latest, "forecast_value"), num(latest, "actual_value"), locale),
+		},
+		{
+			id: "calibration-accuracy-trend",
+			type: "timeseries",
+			span: "full",
+			dataset: "calibration-accuracy-trend.json",
+			data: {
+				label: "预测与实际走势",
+				description: `${horizon} 个月前的预测 vs 最终实际`,
+				coverage: `${String(months[0].month)} → ${latestMonth}`,
+				series: [
+					{ name: "预测", points: months.map((row) => ({ x: String(row.month), y: num(row, "forecast_value") })) },
+					{ name: "实际", points: months.map((row) => ({ x: String(row.month), y: num(row, "actual_value") })) },
+				],
+			},
+		},
+		{
+			id: "calibration-factors",
+			type: "table",
+			span: "half",
+			dataset: "calibration-factors.json",
+			data: {
+				label: "归因因子",
+				description: `${latestMonth}，按影响绝对值排序`,
+				columns: [
+					{ key: "factor", label: "因子" },
+					{ key: "impact", label: "影响", align: "right" },
+					{ key: "share", label: "占比", align: "right" },
+					{ key: "confidence", label: "置信" },
+				],
+				rows: attribution.rows
+					.slice()
+					.sort((left, right) => Math.abs(num(right, "impact_usd") ?? 0) - Math.abs(num(left, "impact_usd") ?? 0))
+					.map((row) => ({
+						factor: str(row, "factor"),
+						impact: currency(num(row, "impact_usd"), locale),
+						share: percent(num(row, "impact_share"), locale),
+						confidence: toned(
+							str(row, "category") === "unexplained" ? "未归因" : str(row, "confidence_band"),
+							str(row, "category") === "unexplained" ? "warning" : undefined,
+						),
+					})),
+			},
+		},
+		{
+			id: "calibration-assumptions",
+			type: "table",
+			span: "half",
+			dataset: "calibration-assumptions.json",
+			data: {
+				label: "基准假设与校准建议",
+				description: "待审批的修正尚未生效；当前预测仍使用现行基准",
+				columns: [
+					{ key: "name", label: "假设" },
+					{ key: "current", label: "现行", align: "right" },
+					{ key: "suggested", label: "建议", align: "right" },
+					{ key: "impact", label: "12 个月影响", align: "right" },
+					{ key: "basis", label: "依据" },
+					{ key: "status", label: "状态" },
+				],
+				rows: assumptions.rows.map((row) => {
+					const status = str(row, "approval_status");
+					return {
+						name: `${str(row, "assumption_name")}（${str(row, "scope")}）`,
+						current: num(row, "current_value") === null ? null : String(num(row, "current_value")),
+						// No proposal is a null, not a repeat of the current value:
+						// echoing it would read as "we checked and it is fine".
+						suggested: num(row, "suggested_value") === null ? null : String(num(row, "suggested_value")),
+						impact: currency(num(row, "estimated_impact_usd_12m"), locale),
+						basis: str(row, "detection_basis"),
+						status: toned(
+							status === "pending" ? `待 ${str(row, "approver_role") ?? "审批人"} 审批` : status === "approved" ? "已批准" : "现行",
+							status === "pending" ? "warning" : status === "approved" ? "positive" : "neutral",
+						),
+					};
+				}),
+			},
+		},
+	];
+
+	return {
+		module: {
+			id: "forecast-accuracy",
+			title: "偏差校准",
+			status: "published",
+			source: {
+				artifact_type: "finance_csv",
+				metric,
+				horizon_months: horizon,
+				sample_months: months.length,
+				latest_month: latestMonth,
+				datasets: ["forecast_vs_actual", "variance_attribution", "baseline_assumptions"],
+				data_as_of: latestMonth,
+			},
+			warnings,
+			widgets,
+		},
+		mape,
+		biasRun: run,
+		pendingCorrections: pending.length,
+	};
+}

package/extensions/fpa-dashboard/compat-publisher.ts

@@ -7,6 +7,61 @@ import { publishDashboard, resolveDashboardDir } from "./publisher.ts";
 import { publishDashboardModule, readDashboardModuleManifest } from "./module-publisher.ts";
 import type { DashboardActualsSnapshot } from "./source.ts";
 
+// ============================================================================
+// Publishing the legacy closed-loop build into the modular dashboard.
+//
+// This build predates the modular split and computes everything at once:
+// execution results, next-cycle allocation, forward outlook, forecast
+// accuracy. Publishing all of it into one module made `execution-evidence` a
+// container rather than a subject — and now that dedicated modules own most of
+// those topics, it would also mean two producers writing the same content into
+// the same dashboard.
+//
+// Re-homing the extra widgets into `next-forecast` and `forecast-accuracy` is
+// not an option either: those modules have their own publishers, and this path
+// would overwrite whatever they last wrote.
+//
+// So this publishes only what execution evidence actually is — was the
+// approved plan carried out, and what did it produce — and names the tool that
+// owns each topic it dropped. The build still computes them and they stay in
+// the receipt's source, so nothing becomes unprovable; they simply stop being
+// shown twice.
+// ============================================================================
+
+/**
+ * The widgets whose subject is "the plan was executed, and here is the result".
+ * Anything else the legacy build produces belongs to a module with its own
+ * publisher.
+ */
+const EXECUTION_EVIDENCE_WIDGETS = new Set([
+	"current-cycle-execution-evidence",
+	"revenue-vs-forecast",
+	"cycle-roas",
+	"paid-spend-exec",
+	"daily-trend",
+]);
+
+/** Which tool now owns each topic the legacy build also computes. */
+const SUPERSEDED_BY: Array<{ match: (id: string) => boolean; module: string; tool: string }> = [
+	{
+		match: (id) => id.startsWith("forecast-accuracy-") || id === "calibration-alerts" || id === "alerts-count" || id === "closed-cycle-revenue-variance",
+		module: "forecast-accuracy",
+		tool: "fpa_dashboard_publish_calibration",
+	},
+	{
+		match: (id) => id.startsWith("next-cycle-") || id.startsWith("forward-outlook-") || id.startsWith("forecast-data-") || id === "forecast-limitations" || id === "app-strategy",
+		module: "next-forecast",
+		tool: "fpa_dashboard_publish_forecast",
+	},
+];
+
+function ownerOf(widgetId: string): { module: string; tool: string } | null {
+	const entry = SUPERSEDED_BY.find((candidate) => candidate.match(widgetId));
+	// Return only the serialisable half: the whole entry carries a predicate,
+	// and this lands in the build receipt, which must stay plain JSON.
+	return entry ? { module: entry.module, tool: entry.tool } : null;
+}
+
 interface Options {
 	cwd: string;
 	build: DashboardBuild;
@@ -28,6 +83,31 @@ export async function publishDashboardProjection(options: Options): Promise<{ da
 	if (options.build.source.forecast_role === "backtest" && options.allowBacktestDisplay !== true) {
 		throw new Error("A backtest cannot replace dashboard execution evidence without explicit user authorization.");
 	}
+
+	const owned = options.build.widgets.filter((widget) => EXECUTION_EVIDENCE_WIDGETS.has(widget.id));
+	if (owned.length === 0) {
+		throw new Error("The closed-loop build produced no execution-evidence widgets; there is nothing for this module to publish.");
+	}
+	const superseded = options.build.widgets
+		.filter((widget) => !EXECUTION_EVIDENCE_WIDGETS.has(widget.id))
+		.map((widget) => ({ id: widget.id, ...(ownerOf(widget.id) ?? { module: "unassigned", tool: "(none)" }) }));
+
+	const warnings = [...options.build.warnings];
+	const byTool = new Map<string, string[]>();
+	for (const entry of superseded) {
+		if (entry.tool === "(none)") continue;
+		byTool.set(entry.tool, [...(byTool.get(entry.tool) ?? []), entry.id]);
+	}
+	for (const [tool, ids] of byTool) {
+		warnings.push(`${ids.length} 项内容已由专用模块承载，本模块不再重复展示；请改用 ${tool} 发布：${ids.join("、")}。`);
+	}
+	const unassigned = superseded.filter((entry) => entry.tool === "(none)");
+	if (unassigned.length > 0) {
+		// A widget with no owner is a gap in the map above, not something to
+		// quietly swallow.
+		warnings.push(`${unassigned.length} 项内容没有归属模块，未被展示：${unassigned.map((entry) => entry.id).join("、")}。`);
+	}
+
 	const current = await readDashboardModuleManifest(options.cwd);
 	const published = await publishDashboardModule({
 		cwd: options.cwd,
@@ -35,10 +115,16 @@ export async function publishDashboardProjection(options: Options): Promise<{ da
 		expectedDashboardRevision: current?.dashboardRevision ?? null,
 		module: {
 			id: "execution-evidence",
-			title: "经营执行与校准证据",
+			title: "执行证据",
 			status: "published",
-			source: { ...options.build.source, warnings: options.build.warnings, projector: options.projector, runtime: options.runtime },
-			widgets: options.build.widgets,
+			source: {
+				...options.build.source,
+				projector: options.projector,
+				runtime: options.runtime,
+				superseded_widgets: superseded,
+			},
+			warnings,
+			widgets: owned,
 		},
 	});
 	return { dashboardDir: published.dashboardDir, fingerprint: published.moduleRevision, publishedDatasets: published.publishedDatasets };