@viccydev/pi-fpa 0.7.2 → 0.8.1

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

@@ -0,0 +1,304 @@
+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";
+
+const STRATEGY_ACTION_LABELS = {
+	grow: "增长",
+	hold: "保持",
+	cut: "削减",
+	stop: "止损",
+} as const;
+type StrategyAction = keyof typeof STRATEGY_ACTION_LABELS;
+
+export interface StrategyModuleContext {
+	scope_id: string;
+	cycle_id: string;
+	forecast_role: string;
+}
+
+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");
+}
+
+function strategyAction(value: unknown, label: string): StrategyAction {
+	if (typeof value === "string" && value in STRATEGY_ACTION_LABELS) return value as StrategyAction;
+	throw new Error(`${label} must be one of grow, hold, cut, stop.`);
+}
+
+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,
+	reviewInput: unknown,
+	expectedContext: StrategyModuleContext,
+): DashboardModuleBuild {
+	const proposal = record(proposalInput, "strategy_proposal");
+	const handoff = record(handoffInput, "reviewed_strategy_handoff");
+	const review = record(reviewInput, "strategy_review");
+	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.");
+	if (review.artifact_type !== "strategy_review") throw new Error("Strategy publication requires artifact_type=strategy_review.");
+	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.");
+	if (review.reviewed_strategy_version !== strategyVersion) throw new Error("Strategy review version does not match the strategy proposal version.");
+	if (review.status !== "complete" && review.status !== "complete_with_limits") throw new Error("Strategy review is not complete.");
+	if (review.independence_confirmed !== true || handoff.independence_confirmed !== true) throw new Error("Strategy publication requires an independently reviewed proposal.");
+	const reviewerIdentity = requiredString(review.reviewer_identity, "strategy_review.reviewer_identity");
+	if (handoff.reviewer_identity !== reviewerIdentity) throw new Error("Reviewed handoff reviewer identity does not match the strategy review.");
+	if (review.opinion !== "support" && review.opinion !== "support_with_conditions") throw new Error("Strategy review opinion does not support human approval.");
+	if (handoff.review_opinion !== review.opinion) throw new Error("Reviewed handoff opinion does not match the strategy review.");
+	if (handoff.next_graph !== "fpa-forecast-freeze") throw new Error("Reviewed handoff next_graph must be fpa-forecast-freeze.");
+	for (const key of ["scope_id", "cycle_id", "forecast_role"] as const) {
+		const expected = requiredString(expectedContext[key], `strategy publication ${key}`);
+		if (handoff[key] !== expected) throw new Error(`Reviewed handoff ${key} does not match the publication context.`);
+	}
+	if (handoff.proposal_fingerprint !== fingerprint(proposal)) throw new Error("Reviewed handoff proposal_fingerprint does not match the strategy proposal.");
+	if (handoff.review_fingerprint !== fingerprint(review)) throw new Error("Reviewed handoff review_fingerprint does not match the strategy review.");
+	const reviewConditions = array(review.conditions_for_human_approval ?? [], "strategy_review.conditions_for_human_approval");
+	const residualRisks = array(review.residual_risks ?? [], "strategy_review.residual_risks");
+	if (stableJson(handoff.review_conditions ?? []) !== stableJson(reviewConditions)) throw new Error("Reviewed handoff conditions do not match the strategy review.");
+	if (stableJson(handoff.review_residual_risks ?? []) !== stableJson(residualRisks)) throw new Error("Reviewed handoff residual risks do not match the strategy review.");
+	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 parsedAllocations = allocations.map((item, index) => {
+		const allocation = record(item, `strategy_proposal.allocation[${index}]`);
+		if (typeof allocation.spend !== "number" || !Number.isFinite(allocation.spend) || allocation.spend < 0) throw new Error(`strategy_proposal.allocation[${index}].spend must be a finite non-negative number.`);
+		if (typeof allocation.change_from_baseline !== "number" || !Number.isFinite(allocation.change_from_baseline)) throw new Error(`strategy_proposal.allocation[${index}].change_from_baseline must be a finite number.`);
+		const action = strategyAction(allocation.action, `strategy_proposal.allocation[${index}].action`);
+		const consistent = action === "grow"
+			? allocation.change_from_baseline > 0
+			: action === "hold"
+				? allocation.change_from_baseline === 0
+				: action === "cut"
+					? allocation.change_from_baseline < 0 && allocation.spend > 0
+					: allocation.change_from_baseline <= 0 && allocation.spend === 0;
+		if (!consistent) throw new Error(`strategy_proposal.allocation[${index}].action ${action} conflicts with spend and change_from_baseline.`);
+		return { allocation, action };
+	});
+	const totalSpend = parsedAllocations.reduce((sum, { allocation }) => sum + (allocation.spend as number), 0);
+	const actionCounts = Object.fromEntries(Object.keys(STRATEGY_ACTION_LABELS).map((action) => [action, 0])) as Record<StrategyAction, number>;
+	for (const { action } of parsedAllocations) actionCounts[action] += 1;
+	const actionHeadline = (Object.entries(STRATEGY_ACTION_LABELS) as [StrategyAction, string][])
+		.map(([action, label]) => `${label} ${actionCounts[action]} 项`)
+		.join("；");
+	return {
+		id: "next-strategy",
+		title: "下周期执行策略",
+		status: "awaiting_decision",
+		source: {
+			artifact_type: "reviewed_strategy",
+			artifact_fingerprint: fingerprint({ proposal, review, handoff }),
+			proposal_fingerprint: fingerprint(proposal),
+			review_fingerprint: fingerprint(review),
+			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: actionHeadline },
+						{ 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: "action", label: "动作" },
+						{ key: "spend", label: "预算", align: "right" }, { key: "change", label: "较基线变化", align: "right" },
+					],
+					rows: parsedAllocations.map(({ allocation, action }) => {
+						return {
+							app: cell(allocation.app_id), store: cell(allocation.store), channel: cell(allocation.channel_group),
+							action: STRATEGY_ACTION_LABELS[action],
+							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),
+						};
+					}),
+				},
+			},
+		],
+	};
+}

package/extensions/fpa-dashboard/strategy-decision.ts

@@ -0,0 +1,192 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, realpath, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import { stableJson } from "../fpa-artifacts/store.ts";
+import { resolveDashboardDir } from "./publisher.ts";
+
+const SHA256_RE = /^[a-f0-9]{64}$/;
+
+export interface StrategyDecisionRequestInput {
+	sessionId: string;
+	strategyVersion: string;
+	handoffFingerprint: string;
+	createdAt?: string;
+}
+
+export interface StrategyDecisionRequest {
+	kind: "fpa.strategy.decision.request";
+	schema_version: 1;
+	action_id: string;
+	session_id: string;
+	strategy_version: string;
+	handoff_fingerprint: string;
+	created_at: string;
+}
+
+export interface CommitStrategyDecisionInput {
+	actionId: string;
+	sessionId: string;
+	decision: "confirm" | "request_changes";
+	feedback?: string;
+	decidedAt?: string;
+}
+
+export interface CommitStrategyDecisionResult {
+	decisionFingerprint: string;
+	path: string;
+	decision: "confirm" | "request_changes";
+	strategyVersion: string;
+	handoffFingerprint: string;
+}
+
+export interface CommittedStrategyDecision {
+	kind: "fpa.strategy.decision";
+	schema_version: 1;
+	action_id: string;
+	strategy_version: string;
+	handoff_fingerprint: string;
+	decision: "confirm" | "request_changes";
+	feedback?: string;
+	decision_fingerprint: string;
+	decided_at: string;
+}
+
+function sha256(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function requiredString(value: string, label: string): string {
+	if (typeof value !== "string" || value.trim() === "" || value.length > 512 || /[\u0000-\u001f\u007f]/.test(value)) {
+		throw new Error(`${label} must be a non-empty bounded string without control characters.`);
+	}
+	return value;
+}
+
+async function ensureDirectory(parent: string, name: string): Promise<string> {
+	const path = join(parent, name);
+	try {
+		const stat = await lstat(path);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${name} must be a regular directory, not a symlink.`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(path, { mode: 0o700 });
+	}
+	return path;
+}
+
+async function appendOnlyWrite(directory: string, destination: string, contents: string): Promise<"created" | "exists"> {
+	const temporary = join(directory, `.${randomUUID()}.tmp`);
+	const handle = await open(temporary, "wx", 0o600);
+	try {
+		await handle.writeFile(contents, "utf8");
+		await handle.sync();
+		await handle.close();
+		try {
+			await link(temporary, destination);
+			return "created";
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") return "exists";
+			throw error;
+		}
+	} finally {
+		await handle.close().catch(() => undefined);
+		await unlink(temporary).catch(() => undefined);
+	}
+}
+
+export async function createStrategyDecisionRequest(cwd: string, input: StrategyDecisionRequestInput): Promise<{ actionId: string; path: string }> {
+	const sessionId = requiredString(input.sessionId, "sessionId");
+	const strategyVersion = requiredString(input.strategyVersion, "strategyVersion");
+	if (!SHA256_RE.test(input.handoffFingerprint)) throw new Error("handoffFingerprint must be a SHA-256 digest.");
+	const dashboardDir = await resolveDashboardDir(cwd);
+	try {
+		const stat = await lstat(dashboardDir);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Dashboard directory must be a regular directory, not a symlink.");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		await mkdir(dashboardDir, { mode: 0o700 });
+	}
+	const actionsDir = await ensureDirectory(dashboardDir, "actions");
+	const createdAt = input.createdAt ?? new Date().toISOString();
+	const actionId = sha256(stableJson({ sessionId, strategyVersion, handoffFingerprint: input.handoffFingerprint, createdAt, nonce: randomUUID() }));
+	const request: StrategyDecisionRequest = {
+		kind: "fpa.strategy.decision.request",
+		schema_version: 1,
+		action_id: actionId,
+		session_id: sessionId,
+		strategy_version: strategyVersion,
+		handoff_fingerprint: input.handoffFingerprint,
+		created_at: createdAt,
+	};
+	const path = join(actionsDir, `${actionId}.json`);
+	await appendOnlyWrite(actionsDir, path, `${JSON.stringify(request, null, 2)}\n`);
+	return { actionId, path };
+}
+
+export async function readStrategyDecisionRequest(cwd: string, actionId: string): Promise<StrategyDecisionRequest> {
+	if (!SHA256_RE.test(actionId)) throw new Error("actionId must be a SHA-256 digest.");
+	const dashboardDir = await resolveDashboardDir(cwd);
+	const path = join(dashboardDir, "actions", `${actionId}.json`);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Strategy decision request must be a regular file.");
+	const request = JSON.parse(await readFile(path, "utf8")) as StrategyDecisionRequest;
+	if (request.kind !== "fpa.strategy.decision.request" || request.schema_version !== 1 || request.action_id !== actionId) throw new Error("Strategy decision request is invalid.");
+	return request;
+}
+
+export async function commitStrategyDecision(cwd: string, input: CommitStrategyDecisionInput): Promise<CommitStrategyDecisionResult> {
+	const sessionId = requiredString(input.sessionId, "sessionId");
+	const request = await readStrategyDecisionRequest(cwd, input.actionId);
+	if (request.session_id !== sessionId) throw new Error("Strategy decision must be committed from the originating session.");
+	const feedback = input.feedback?.trim();
+	if (input.decision === "request_changes" && !feedback) throw new Error("request_changes requires non-empty feedback.");
+	if (input.decision === "confirm" && feedback) throw new Error("confirm must not include feedback.");
+
+	const projectRoot = await realpath(cwd);
+	const artifactsDir = await ensureDirectory(projectRoot, "artifacts");
+	const decisionsDir = await ensureDirectory(artifactsDir, "strategy-decisions");
+	const identity = {
+		action_id: request.action_id,
+		strategy_version: request.strategy_version,
+		handoff_fingerprint: request.handoff_fingerprint,
+		decision: input.decision,
+		...(feedback ? { feedback } : {}),
+	};
+	const decisionFingerprint = sha256(stableJson(identity));
+	const decision = {
+		kind: "fpa.strategy.decision",
+		schema_version: 1,
+		...identity,
+		decision_fingerprint: decisionFingerprint,
+		decided_at: input.decidedAt ?? new Date().toISOString(),
+	};
+	const path = join(decisionsDir, `${request.action_id}.json`);
+	const contents = `${JSON.stringify(decision, null, 2)}\n`;
+	const write = await appendOnlyWrite(decisionsDir, path, contents);
+	if (write === "exists") {
+		const existing = JSON.parse(await readFile(path, "utf8")) as typeof decision;
+		if (existing.decision_fingerprint !== decisionFingerprint) throw new Error("A different strategy decision is already committed for this action.");
+		return {
+			decisionFingerprint: existing.decision_fingerprint,
+			path,
+			decision: existing.decision,
+			strategyVersion: request.strategy_version,
+			handoffFingerprint: request.handoff_fingerprint,
+		};
+	}
+	return { decisionFingerprint, path, decision: input.decision, strategyVersion: request.strategy_version, handoffFingerprint: request.handoff_fingerprint };
+}
+
+export async function readCommittedStrategyDecision(cwd: string, actionId: string, decisionFingerprint: string): Promise<CommittedStrategyDecision> {
+	if (!SHA256_RE.test(actionId) || !SHA256_RE.test(decisionFingerprint)) throw new Error("Strategy decision identity must use SHA-256 digests.");
+	const projectRoot = await realpath(cwd);
+	const path = join(projectRoot, "artifacts", "strategy-decisions", `${actionId}.json`);
+	const stat = await lstat(path);
+	if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Committed strategy decision must be a regular file.");
+	const decision = JSON.parse(await readFile(path, "utf8")) as CommittedStrategyDecision;
+	if (decision.kind !== "fpa.strategy.decision" || decision.schema_version !== 1 || decision.action_id !== actionId || decision.decision_fingerprint !== decisionFingerprint) {
+		throw new Error("Committed strategy decision identity does not match the requested decision.");
+	}
+	return decision;
+}