@viccydev/pi-fpa 0.7.2 → 0.8.0

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

@@ -0,0 +1,390 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+import { stableJson } from "../fpa-artifacts/store.ts";
+import type { DashboardWidget } from "./projector.ts";
+import { validateDatasetForWidget } from "./schema.ts";
+
+export type DashboardModuleId = "period-review" | "next-strategy" | "next-forecast" | "execution-evidence";
+export type DashboardModuleStatus = "published" | "awaiting_decision" | "approved" | "changes_requested" | "generating" | "superseded";
+
+export interface DashboardModuleInteraction {
+	kind: "strategy-decision";
+	action_id: string;
+}
+
+export interface DashboardModuleBuild {
+	id: DashboardModuleId;
+	title: string;
+	status: DashboardModuleStatus;
+	source: Record<string, unknown>;
+	widgets: DashboardWidget[];
+	interaction?: DashboardModuleInteraction;
+}
+
+export interface PublishDashboardModuleOptions {
+	cwd: string;
+	module: DashboardModuleBuild;
+	dashboardTitle?: string;
+	expectedDashboardRevision?: string | null;
+	publishedAt?: string;
+}
+
+export interface PublishDashboardModuleResult {
+	dashboardDir: string;
+	dashboardRevision: string;
+	moduleRevision: string;
+	publishedDatasets: number;
+}
+
+export interface TransitionStrategyModuleResult {
+	dashboardRevision: string;
+	moduleRevision: string;
+}
+
+interface DashboardModuleManifestEntry {
+	id: DashboardModuleId;
+	title: string;
+	status: DashboardModuleStatus;
+	updatedAt: string;
+	revision: string;
+	buildReceipt: string;
+	widgets: Array<{ id: string; type: DashboardWidget["type"]; span: DashboardWidget["span"]; dataset: string }>;
+	interaction?: DashboardModuleInteraction;
+}
+
+export interface DashboardManifestV2 {
+	kind: "fpa.dashboard";
+	schemaVersion: 2;
+	title: string;
+	updatedAt: string;
+	dashboardRevision: string;
+	moduleOrder: DashboardModuleId[];
+	modules: Partial<Record<DashboardModuleId, DashboardModuleManifestEntry>>;
+}
+
+const MODULE_IDS: DashboardModuleId[] = ["period-review", "next-strategy", "next-forecast", "execution-evidence"];
+const MODULE_ID_SET = new Set<string>(MODULE_IDS);
+const DATASET_FILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,191}\.json$/;
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+async function pathKind(path: string): Promise<"missing" | "directory" | "symlink" | "other"> {
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink()) return "symlink";
+		if (stat.isDirectory()) return "directory";
+		return "other";
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
+		throw error;
+	}
+}
+
+async function ensureOwnedDirectory(path: string, label: string): Promise<void> {
+	const kind = await pathKind(path);
+	if (kind === "symlink") throw new Error(`${label} must not be a symlink.`);
+	if (kind === "other") throw new Error(`${label} must be a directory.`);
+	if (kind === "missing") await mkdir(path, { recursive: true, mode: 0o700 });
+}
+
+async function atomicWrite(destination: string, contents: string): Promise<void> {
+	const temporary = join(dirname(destination), `.${basename(destination)}.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	let closed = false;
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		closed = true;
+		await rename(temporary, destination);
+	} catch (error) {
+		if (!closed) await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+		throw error;
+	}
+}
+
+async function appendOnlyWrite(directory: string, destination: string, contents: string): Promise<void> {
+	const temporary = join(directory, `.${basename(destination)}.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	try {
+		await link(temporary, destination);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		if (await readFile(destination, "utf8") !== contents) throw new Error(`Append-only dashboard object ${basename(destination)} already exists with different content.`);
+	} finally {
+		await unlink(temporary).catch(() => undefined);
+	}
+}
+
+async function resolveDashboardDir(cwd: string): Promise<string> {
+	const projectRoot = await realpath(cwd);
+	return join(dirname(projectRoot), ".fpa-dashboard");
+}
+
+function assertModule(module: DashboardModuleBuild): void {
+	if (!MODULE_ID_SET.has(module.id)) throw new Error(`Unsupported dashboard module id "${module.id}".`);
+	if (!module.title?.trim()) throw new Error("Dashboard module title is required.");
+	if (!Array.isArray(module.widgets) || module.widgets.length === 0 || module.widgets.length > 64) throw new Error("Dashboard module must contain between 1 and 64 widgets.");
+	if (module.interaction && (module.id !== "next-strategy" || module.status !== "awaiting_decision")) {
+		throw new Error("Strategy decisions are available only on an awaiting next-strategy module.");
+	}
+	const widgetIds = new Set<string>();
+	for (const widget of module.widgets) {
+		if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(widget.id) || widgetIds.has(widget.id)) throw new Error(`Invalid or duplicate dashboard widget id "${widget.id}".`);
+		widgetIds.add(widget.id);
+		if (!DATASET_FILE_RE.test(widget.dataset)) throw new Error(`Invalid logical dataset name "${widget.dataset}".`);
+		validateDatasetForWidget(widget.type, widget.data);
+	}
+}
+
+export function dashboardModuleBuildFingerprint(module: DashboardModuleBuild): string {
+	assertModule(module);
+	return sha256(stableJson(module));
+}
+
+function dashboardRevision(title: string, moduleOrder: DashboardModuleId[], modules: DashboardManifestV2["modules"]): string {
+	return sha256(stableJson({ title, moduleOrder, modules }));
+}
+
+async function readManifest(path: string): Promise<DashboardManifestV2 | null> {
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;
+		if (parsed.kind !== "fpa.dashboard") throw new Error("Existing dashboard manifest kind is invalid.");
+		if (parsed.schemaVersion === 1) {
+			if (!Array.isArray(parsed.widgets) || typeof parsed.generationId !== "string" || typeof parsed.buildReceipt !== "string") {
+				throw new Error("Legacy dashboard manifest is invalid.");
+			}
+			const updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date(0).toISOString();
+			const legacyEntry: DashboardModuleManifestEntry = {
+				id: "execution-evidence",
+				title: "历史经营闭环",
+				status: "published",
+				updatedAt,
+				revision: parsed.generationId,
+				buildReceipt: parsed.buildReceipt,
+				widgets: parsed.widgets as DashboardModuleManifestEntry["widgets"],
+			};
+			const title = typeof parsed.title === "string" ? parsed.title : "FP&A Dashboard";
+			const modules = { "execution-evidence": legacyEntry };
+			const moduleOrder: DashboardModuleId[] = ["execution-evidence"];
+			return {
+				kind: "fpa.dashboard",
+				schemaVersion: 2,
+				title,
+				updatedAt,
+				dashboardRevision: dashboardRevision(title, moduleOrder, modules),
+				moduleOrder,
+				modules,
+			};
+		}
+		if (parsed.schemaVersion !== 2 || !parsed.modules || !Array.isArray(parsed.moduleOrder)) throw new Error("Dashboard manifest schema is unsupported.");
+		return parsed as unknown as DashboardManifestV2;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+async function normalizeLegacyModuleReceipt(
+	dashboardDir: string,
+	modulesDir: string,
+	current: DashboardManifestV2 | null,
+): Promise<DashboardManifestV2 | null> {
+	const legacy = current?.modules["execution-evidence"];
+	if (!current || !legacy || legacy.buildReceipt.startsWith("modules/")) return current;
+	if (!DATASET_FILE_RE.test(legacy.buildReceipt)) throw new Error("Legacy dashboard build receipt path is invalid.");
+	const sourcePath = join(dashboardDir, legacy.buildReceipt);
+	const stat = await lstat(sourcePath);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Legacy dashboard build receipt must be a regular file.");
+	const old = JSON.parse(await readFile(sourcePath, "utf8")) as { source?: unknown; warnings?: unknown; datasets?: unknown };
+	if (!Array.isArray(old.datasets)) throw new Error("Legacy dashboard build receipt datasets are invalid.");
+	const receipt = {
+		kind: "fpa.dashboard.module.build",
+		schema_version: 1,
+		module_id: "execution-evidence",
+		module_revision: legacy.revision,
+		published_at: legacy.updatedAt,
+		status: legacy.status,
+		source: { ...(old.source && typeof old.source === "object" ? old.source : {}), warnings: old.warnings ?? [], legacy_generation_id: legacy.revision },
+		datasets: old.datasets,
+	};
+	const contents = `${JSON.stringify(receipt, null, 2)}\n`;
+	const filename = `modules/execution-evidence.${legacy.revision}.${sha256(stableJson(receipt))}.json`;
+	await appendOnlyWrite(modulesDir, join(dashboardDir, filename), contents);
+	return { ...current, modules: { ...current.modules, "execution-evidence": { ...legacy, buildReceipt: filename } } };
+}
+
+export async function readDashboardModuleManifest(cwd: string): Promise<DashboardManifestV2 | null> {
+	return readManifest(join(await resolveDashboardDir(cwd), "manifest.json"));
+}
+
+export async function readDashboardModuleSource(cwd: string, moduleId: DashboardModuleId): Promise<Record<string, unknown> | null> {
+	const dashboardDir = await resolveDashboardDir(cwd);
+	const entry = (await readManifest(join(dashboardDir, "manifest.json")))?.modules[moduleId];
+	if (!entry) return null;
+	if (!entry.buildReceipt.startsWith("modules/") || !DATASET_FILE_RE.test(basename(entry.buildReceipt))) throw new Error("Dashboard module build receipt path is invalid.");
+	const path = join(dashboardDir, entry.buildReceipt);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Dashboard module build receipt must be a regular file.");
+	const receipt = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;
+	if (receipt.kind !== "fpa.dashboard.module.build" || receipt.module_id !== moduleId || receipt.module_revision !== entry.revision || receipt.status !== entry.status) {
+		throw new Error("Dashboard module build receipt does not match its manifest entry.");
+	}
+	return receipt.source && typeof receipt.source === "object" ? receipt.source as Record<string, unknown> : {};
+}
+
+export async function publishDashboardModule(options: PublishDashboardModuleOptions): Promise<PublishDashboardModuleResult> {
+	assertModule(options.module);
+	const dashboardDir = await resolveDashboardDir(options.cwd);
+	await ensureOwnedDirectory(dashboardDir, "Dashboard directory");
+	const datasetsDir = join(dashboardDir, "datasets");
+	await ensureOwnedDirectory(datasetsDir, "Dashboard datasets directory");
+	const modulesDir = join(dashboardDir, "modules");
+	await ensureOwnedDirectory(modulesDir, "Dashboard modules directory");
+
+	const lockPath = join(dashboardDir, ".module-publish.lock");
+	let lock;
+	try {
+		lock = await open(lockPath, "wx", 0o600);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("Another dashboard module publication is in progress; retry after reading the current dashboard revision.");
+		throw error;
+	}
+
+	try {
+		const manifestPath = join(dashboardDir, "manifest.json");
+		const current = await normalizeLegacyModuleReceipt(dashboardDir, modulesDir, await readManifest(manifestPath));
+		const currentRevision = current?.dashboardRevision;
+		if (options.expectedDashboardRevision !== undefined && (options.expectedDashboardRevision ?? undefined) !== currentRevision) {
+			throw new Error(`Dashboard revision changed: expected ${options.expectedDashboardRevision}, current ${currentRevision ?? "none"}.`);
+		}
+
+		const publishedAt = options.publishedAt ?? new Date().toISOString();
+		const revision = dashboardModuleBuildFingerprint(options.module);
+		const datasets = options.module.widgets.map((widget) => {
+			const contents = `${JSON.stringify(widget.data, null, 2)}\n`;
+			const digest = sha256(stableJson(widget.data));
+			const logicalBase = widget.dataset.slice(0, -".json".length);
+			const filename = `${options.module.id}.${logicalBase}.${digest}.json`;
+			if (!DATASET_FILE_RE.test(filename)) throw new Error(`Content-addressed dataset name "${filename}" exceeds the dashboard contract.`);
+			return { widget, filename, digest, contents };
+		});
+		for (const dataset of datasets) await appendOnlyWrite(datasetsDir, join(datasetsDir, dataset.filename), dataset.contents);
+
+		const receipt = {
+			kind: "fpa.dashboard.module.build",
+			schema_version: 1,
+			module_id: options.module.id,
+			module_revision: revision,
+			published_at: publishedAt,
+			status: options.module.status,
+			source: options.module.source,
+			datasets: datasets.map(({ widget, filename, digest }) => ({ logical: widget.dataset, filename, sha256: digest })),
+		};
+		const receiptContents = `${JSON.stringify(receipt, null, 2)}\n`;
+		const receiptDigest = sha256(stableJson(receipt));
+		const receiptFilename = `modules/${options.module.id}.${revision}.${receiptDigest}.json`;
+		await appendOnlyWrite(modulesDir, join(dashboardDir, receiptFilename), receiptContents);
+
+		const entry: DashboardModuleManifestEntry = {
+			id: options.module.id,
+			title: options.module.title,
+			status: options.module.status,
+			updatedAt: publishedAt,
+			revision,
+			buildReceipt: receiptFilename,
+			widgets: datasets.map(({ widget, filename }) => ({ id: widget.id, type: widget.type, span: widget.span, dataset: filename })),
+			...(options.module.interaction ? { interaction: options.module.interaction } : {}),
+		};
+		const title = options.dashboardTitle ?? current?.title ?? "FP&A Dashboard";
+		const modules = { ...(current?.modules ?? {}), [options.module.id]: entry };
+		const moduleOrder = current?.moduleOrder.includes(options.module.id)
+			? current.moduleOrder
+			: [...(current?.moduleOrder ?? []), options.module.id];
+		const nextRevision = dashboardRevision(title, moduleOrder, modules);
+		const nextManifest: DashboardManifestV2 = {
+			kind: "fpa.dashboard",
+			schemaVersion: 2,
+			title,
+			updatedAt: publishedAt,
+			dashboardRevision: nextRevision,
+			moduleOrder,
+			modules,
+		};
+		await atomicWrite(manifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`);
+		return { dashboardDir, dashboardRevision: nextRevision, moduleRevision: revision, publishedDatasets: datasets.length };
+	} finally {
+		await lock.close().catch(() => undefined);
+		await unlink(lockPath).catch(() => undefined);
+	}
+}
+
+export async function transitionStrategyModule(
+	cwd: string,
+	input: { actionId: string; status: "approved" | "changes_requested"; transitionedAt?: string },
+): Promise<TransitionStrategyModuleResult> {
+	const dashboardDir = await resolveDashboardDir(cwd);
+	const lockPath = join(dashboardDir, ".module-publish.lock");
+	let lock;
+	try {
+		lock = await open(lockPath, "wx", 0o600);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("Another dashboard module publication is in progress; retry the strategy decision transition.");
+		throw error;
+	}
+	try {
+		const manifestPath = join(dashboardDir, "manifest.json");
+		const current = await readManifest(manifestPath);
+		if (!current) throw new Error("Dashboard manifest does not exist.");
+		const strategy = current.modules["next-strategy"];
+		if (!strategy || strategy.interaction?.kind !== "strategy-decision" || strategy.interaction.action_id !== input.actionId) {
+			if (strategy?.status === input.status && !strategy.interaction) return { dashboardRevision: current.dashboardRevision, moduleRevision: strategy.revision };
+			throw new Error("Dashboard strategy module does not match this decision action.");
+		}
+		const transitionedAt = input.transitionedAt ?? new Date().toISOString();
+		const revision = sha256(stableJson({ previous_revision: strategy.revision, status: input.status }));
+		if (!strategy.buildReceipt.startsWith("modules/") || !DATASET_FILE_RE.test(basename(strategy.buildReceipt))) throw new Error("Strategy module build receipt path is invalid.");
+		const oldReceiptPath = join(dashboardDir, strategy.buildReceipt);
+		const oldReceiptStat = await lstat(oldReceiptPath);
+		if (oldReceiptStat.isSymbolicLink() || !oldReceiptStat.isFile()) throw new Error("Strategy module build receipt must be a regular file.");
+		const oldReceipt = JSON.parse(await readFile(oldReceiptPath, "utf8")) as Record<string, unknown>;
+		if (oldReceipt.kind !== "fpa.dashboard.module.build" || oldReceipt.module_id !== "next-strategy") throw new Error("Strategy module build receipt is invalid.");
+		const transitionedReceipt = { ...oldReceipt, module_revision: revision, published_at: transitionedAt, status: input.status };
+		const receiptContents = `${JSON.stringify(transitionedReceipt, null, 2)}\n`;
+		const receiptFilename = `modules/next-strategy.${revision}.${sha256(stableJson(transitionedReceipt))}.json`;
+		const modulesDir = join(dashboardDir, "modules");
+		await appendOnlyWrite(modulesDir, join(dashboardDir, receiptFilename), receiptContents);
+		const nextStrategy: DashboardModuleManifestEntry = {
+			...strategy,
+			status: input.status,
+			updatedAt: transitionedAt,
+			revision,
+			buildReceipt: receiptFilename,
+		};
+		delete nextStrategy.interaction;
+		const modules = { ...current.modules, "next-strategy": nextStrategy };
+		const nextDashboardRevision = dashboardRevision(current.title, current.moduleOrder, modules);
+		const next: DashboardManifestV2 = {
+			...current,
+			updatedAt: transitionedAt,
+			dashboardRevision: nextDashboardRevision,
+			modules,
+		};
+		await atomicWrite(manifestPath, `${JSON.stringify(next, null, 2)}\n`);
+		return { dashboardRevision: nextDashboardRevision, moduleRevision: revision };
+	} finally {
+		await lock.close().catch(() => undefined);
+		await unlink(lockPath).catch(() => undefined);
+	}
+}

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

@@ -0,0 +1,241 @@
+import { createHash } from "node:crypto";
+
+import { stableJson } from "../fpa-artifacts/store.ts";
+import type { DashboardModuleBuild } from "./module-publisher.ts";
+import type { TableCell } from "./projector.ts";
+import type { ApprovedCycleForecast } from "../fpa-artifacts/contracts.ts";
+import type { ArtifactRefV2 } from "../fpa-artifacts/store.ts";
+
+function record(value: unknown, label: string): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+	return value as Record<string, unknown>;
+}
+
+function requiredString(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${label} must be a non-empty string.`);
+	return value;
+}
+
+function array(value: unknown, label: string): unknown[] {
+	if (!Array.isArray(value)) throw new Error(`${label} must be an array.`);
+	return value;
+}
+
+function fingerprint(value: unknown): string {
+	return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function cell(value: unknown): TableCell {
+	if (value === null || value === undefined) return null;
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return JSON.stringify(value);
+}
+
+function lines(value: unknown): string {
+	if (!Array.isArray(value) || value.length === 0) return "—";
+	return value.map((item) => typeof item === "string" ? item : JSON.stringify(item)).join("\n");
+}
+
+export function projectReviewModule(input: unknown): DashboardModuleBuild {
+	const analysis = record(input, "driver_analysis");
+	if (analysis.artifact_type !== "driver_analysis") throw new Error("Review publication requires artifact_type=driver_analysis.");
+	const headline = record(analysis.headline_results ?? {}, "driver_analysis.headline_results");
+	const drivers = array(analysis.drivers ?? [], "driver_analysis.drivers");
+	return {
+		id: "period-review",
+		title: "上周期复盘",
+		status: "published",
+		source: {
+			artifact_type: "driver_analysis",
+			artifact_fingerprint: fingerprint(analysis),
+			...(typeof analysis.analysis_version === "string" ? { analysis_version: analysis.analysis_version } : {}),
+			...(typeof analysis.status === "string" ? { artifact_status: analysis.status } : {}),
+		},
+		widgets: [
+			{
+				id: "review-headline",
+				type: "table",
+				span: "half",
+				dataset: "review-headline.json",
+				data: {
+					label: "核心结果",
+					columns: [{ key: "metric", label: "指标" }, { key: "value", label: "结果", align: "right" }],
+					rows: Object.entries(headline).map(([metric, value]) => ({ metric, value: cell(value) })),
+				},
+			},
+			{
+				id: "review-drivers",
+				type: "table",
+				span: "half",
+				dataset: "review-drivers.json",
+				data: {
+					label: "关键驱动",
+					columns: [{ key: "driver", label: "驱动" }, { key: "impact", label: "影响" }, { key: "evidence", label: "证据" }],
+					rows: drivers.map((item, index) => {
+						const driver = record(item, `driver_analysis.drivers[${index}]`);
+						return { driver: cell(driver.driver ?? driver.name ?? `Driver ${index + 1}`), impact: cell(driver.impact ?? driver.effect), evidence: cell(driver.evidence ?? driver.evidence_ids) };
+					}),
+				},
+			},
+			{
+				id: "review-limitations",
+				type: "table",
+				span: "full",
+				dataset: "review-limitations.json",
+				data: {
+					label: "限制与风险",
+					columns: [{ key: "item", label: "说明" }],
+					rows: array(analysis.limitations ?? analysis.risks ?? [], "driver_analysis.limitations").map((item) => ({ item: cell(item) })),
+				},
+			},
+		],
+	};
+}
+
+export function projectStrategyModule(proposalInput: unknown, handoffInput: unknown): DashboardModuleBuild {
+	const proposal = record(proposalInput, "strategy_proposal");
+	const handoff = record(handoffInput, "reviewed_strategy_handoff");
+	if (proposal.artifact_type !== "strategy_proposal") throw new Error("Strategy publication requires artifact_type=strategy_proposal.");
+	if (handoff.kind !== "fpa.reviewed-strategy-handoff") throw new Error("Strategy publication requires kind=fpa.reviewed-strategy-handoff.");
+	const strategyVersion = requiredString(proposal.strategy_version, "strategy_proposal.strategy_version");
+	if (handoff.strategy_version !== strategyVersion || handoff.reviewed_strategy_version !== strategyVersion) {
+		throw new Error("Reviewed handoff version does not match the strategy proposal version.");
+	}
+	if (handoff.status !== "ready") throw new Error("Reviewed strategy handoff is not ready for a human decision.");
+	const allocations = array(proposal.allocation, "strategy_proposal.allocation");
+	const outcomes = record(proposal.expected_outcomes, "strategy_proposal.expected_outcomes");
+	const base = record(outcomes.base ?? {}, "strategy_proposal.expected_outcomes.base");
+	const totalSpend = allocations.reduce((sum, item, index) => {
+		const allocation = record(item, `strategy_proposal.allocation[${index}]`);
+		if (typeof allocation.spend !== "number" || !Number.isFinite(allocation.spend)) throw new Error(`strategy_proposal.allocation[${index}].spend must be a finite number.`);
+		return sum + allocation.spend;
+	}, 0);
+	return {
+		id: "next-strategy",
+		title: "下周期执行策略",
+		status: "awaiting_decision",
+		source: {
+			artifact_type: "reviewed_strategy",
+			artifact_fingerprint: fingerprint({ proposal, handoff }),
+			proposal_fingerprint: fingerprint(proposal),
+			handoff_fingerprint: fingerprint(handoff),
+			strategy_version: strategyVersion,
+			review_opinion: handoff.review_opinion,
+		},
+		widgets: [
+			{
+				id: "strategy-summary",
+				type: "table",
+				span: "full",
+				dataset: "strategy-summary.json",
+				data: {
+					label: "策略摘要",
+					columns: [{ key: "metric", label: "项目" }, { key: "value", label: "值" }],
+					rows: [
+						{ metric: "策略版本", value: strategyVersion },
+						{ metric: "总预算", value: totalSpend.toFixed(2) },
+						{ metric: "Base 收入", value: cell(base.revenue) },
+						{ metric: "Base ROAS", value: cell(base.roas) },
+						{ metric: "决策理由", value: lines(proposal.decision_rationale) },
+					],
+				},
+			},
+			{
+				id: "strategy-allocation",
+				type: "table",
+				span: "full",
+				dataset: "strategy-allocation.json",
+				data: {
+					label: "预算分配",
+					columns: [
+						{ key: "app", label: "App" }, { key: "store", label: "商店" }, { key: "channel", label: "渠道" },
+						{ key: "spend", label: "预算", align: "right" }, { key: "change", label: "较基线变化", align: "right" },
+					],
+					rows: allocations.map((item, index) => {
+						const allocation = record(item, `strategy_proposal.allocation[${index}]`);
+						return {
+							app: cell(allocation.app_id), store: cell(allocation.store), channel: cell(allocation.channel_group),
+							spend: (allocation.spend as number).toFixed(2), change: cell(allocation.change_from_baseline),
+						};
+					}),
+				},
+			},
+			{
+				id: "strategy-governance",
+				type: "table",
+				span: "full",
+				dataset: "strategy-governance.json",
+				data: {
+					label: "审批条件与风险",
+					columns: [{ key: "category", label: "类别" }, { key: "details", label: "内容" }],
+					rows: [
+						{ category: "审批条件", details: lines(handoff.review_conditions) },
+						{ category: "剩余风险", details: lines(handoff.review_residual_risks ?? proposal.risks) },
+						{ category: "待确认事项", details: lines(proposal.required_human_decisions) },
+					],
+				},
+			},
+		],
+	};
+}
+
+export function projectForecastModule(forecast: ApprovedCycleForecast, artifactRef: ArtifactRefV2): DashboardModuleBuild {
+	const allocationByKey = new Map(forecast.approved_allocation.map((item) => [`${item.app_id}\u0000${item.store}\u0000${item.channel_group}`, item]));
+	return {
+		id: "next-forecast",
+		title: "下周期数据预测",
+		status: "published",
+		source: {
+			artifact_type: "approved_cycle_forecast",
+			artifact_ref: artifactRef,
+			artifact_fingerprint: forecast.immutable_fingerprint,
+			forecast_version: forecast.forecast_version,
+			strategy_version: forecast.strategy_version,
+			target_period: forecast.target_period,
+			data_as_of: forecast.data_as_of,
+		},
+		widgets: [
+			{
+				id: "forecast-summary",
+				type: "table",
+				span: "full",
+				dataset: "forecast-summary.json",
+				data: {
+					label: "预测摘要",
+					columns: [{ key: "metric", label: "指标" }, { key: "downside", label: "Downside", align: "right" }, { key: "base", label: "Base", align: "right" }, { key: "upside", label: "Upside", align: "right" }],
+					rows: Object.entries(forecast.consolidated_forecast).map(([metric, scenario]) => ({
+						metric,
+						downside: cell(scenario.downside),
+						base: cell(scenario.base),
+						upside: cell(scenario.upside),
+					})),
+					description: `${forecast.target_period.start_inclusive} → ${forecast.target_period.end_exclusive}`,
+				},
+			},
+			{
+				id: "forecast-by-slice",
+				type: "table",
+				span: "full",
+				dataset: "forecast-by-slice.json",
+				data: {
+					label: "分片预测",
+					columns: [
+						{ key: "slice", label: "App / 商店 / 渠道" }, { key: "spend", label: "预算", align: "right" },
+						{ key: "revenue", label: "Base 收入", align: "right" }, { key: "roas", label: "Base ROAS", align: "right" },
+					],
+					rows: forecast.forecast_by_slice.map((slice) => {
+						const key = `${slice.app_id}\u0000${slice.store}\u0000${slice.channel_group}`;
+						const allocation = allocationByKey.get(key);
+						return {
+							slice: `${slice.app_id} · ${slice.store} · ${slice.channel_group}`,
+							spend: cell(allocation?.approved_spend),
+							revenue: cell(slice.metrics.revenue?.base),
+							roas: cell(slice.metrics.roas?.base),
+						};
+					}),
+				},
+			},
+		],
+	};
+}