@viccydev/pi-fpa 0.5.0 → 0.6.0

package/extensions/fpa-dashboard/cycle-operating-projection.ts

@@ -0,0 +1,559 @@
+import {
+	validateArtifact,
+	validateExecutionAgainstForecast,
+	type ApprovedCycleForecastInput,
+	type ExecutionReceiptInput,
+	type ScenarioMetric,
+} from "../fpa-artifacts/contracts.ts";
+import {
+	ACTUALS_DATA_AS_OF_UNAVAILABLE,
+	validateActualsSnapshot,
+	type DashboardActualsSnapshot,
+} from "./source.ts";
+import type { DashboardWidget, TableCell } from "./projector.ts";
+
+export interface CycleOperatingProjectionInput {
+	scope_id: string;
+	cycle_id: string;
+	current_forecast: unknown;
+	current_forecast_role?: "original" | "eac" | "next_plan";
+	actuals: unknown;
+	execution?: unknown;
+	next_forecast?: unknown;
+	next_forecast_role?: "original" | "eac" | "next_plan";
+}
+
+interface ScenarioValues {
+	downside: number | null;
+	base: number | null;
+	upside: number | null;
+	unit: string;
+}
+
+export interface CycleOperatingProjection {
+	kind: "fpa.cycle-operating-projection";
+	schema_version: 1;
+	scope_id: string;
+	cycle_id: string;
+	data_as_of: string;
+	reporting_currency: string;
+	current_cycle: {
+		forecast_version: string;
+		target_period: ApprovedCycleForecastInput["target_period"];
+		forecast: { spend: ScenarioValues; revenue: ScenarioValues; roas: ScenarioValues };
+		actual_to_date: { spend: number | null; revenue: number | null; roas: number | null };
+		variance: {
+			status: "closed_comparable" | "not_comparable_partial_period" | "not_comparable_missing_actuals" | "not_comparable_unverified_snapshot" | "not_comparable_non_original_forecast";
+			revenue_delta: number | null;
+			revenue_delta_pct: number | null;
+			spend_delta: number | null;
+			spend_delta_pct: number | null;
+		};
+		execution: {
+			status: "not_recorded" | ExecutionReceiptInput["status"];
+			verification_status: "not_recorded" | ExecutionReceiptInput["verification_status"];
+			execution_mode: "not_recorded" | ExecutionReceiptInput["execution_mode"];
+			reconciliation_result: "not_recorded" | ExecutionReceiptInput["reconciliation"]["result"];
+			external_evidence_count: number;
+		};
+	};
+	next_cycle:
+		| { status: "unavailable"; reason: string }
+		| {
+			status: "ready" | "ready_with_limits";
+			forecast_version: string;
+			target_period: ApprovedCycleForecastInput["target_period"];
+			expected_spend: ScenarioValues;
+			expected_revenue: ScenarioValues;
+			expected_roas: ScenarioValues;
+			strategy: Array<{
+				app_id: string;
+				store: string;
+				channel_group: string;
+				action: ApprovedCycleForecastInput["approved_allocation"][number]["action"];
+				baseline_spend: number | null;
+				approved_spend: number;
+				spend_change: number | null;
+				spend_change_pct: number | null;
+				expected_revenue: number | null;
+				approval_id: string;
+				strategy_review_id: string;
+				stop_loss_roas_lt: number;
+				owner: string | null;
+			}>;
+		};
+	warnings: string[];
+}
+
+function identity(value: unknown, path: string): string {
+	if (typeof value !== "string" || value.trim() === "" || value.length > 256 || /[\u0000-\u001f\u007f]/.test(value)) {
+		throw new Error(`${path} must be a non-empty string of at most 256 characters without control characters.`);
+	}
+	return value;
+}
+
+function forecast(value: unknown, path: string): ApprovedCycleForecastInput {
+	const artifact = validateArtifact(value);
+	if (artifact.artifact_type !== "approved_cycle_forecast") throw new Error(`${path} must be an approved_cycle_forecast.`);
+	return artifact;
+}
+
+function execution(value: unknown, current: ApprovedCycleForecastInput): ExecutionReceiptInput {
+	const artifact = validateArtifact(value);
+	if (artifact.artifact_type !== "execution_receipt") throw new Error("execution must be an execution_receipt.");
+	validateExecutionAgainstForecast(artifact, current);
+	return artifact;
+}
+
+function scenario(metric: ScenarioMetric | undefined, path: string): ScenarioValues {
+	if (!metric) throw new Error(`${path} is required.`);
+	return {
+		downside: metric.downside,
+		base: metric.base,
+		upside: metric.upside,
+		unit: metric.unit,
+	};
+}
+
+function round(value: number): number {
+	return Math.round(value * 1_000_000) / 1_000_000;
+}
+
+function safeRatio(numerator: number | null, denominator: number | null): number | null {
+	if (numerator === null || denominator === null || denominator === 0) return null;
+	return round(numerator / denominator);
+}
+
+function periodFinalDate(forecast: ApprovedCycleForecastInput): string {
+	const lastInstant = new Date(Date.parse(forecast.target_period.end_exclusive) - 1);
+	const parts = new Intl.DateTimeFormat("en-CA", {
+		timeZone: forecast.target_period.timezone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).formatToParts(lastInstant);
+	const values = Object.fromEntries(parts.map((part) => [part.type, part.value]));
+	return `${values.year}-${values.month}-${values.day}`;
+}
+
+function periodStartDate(forecast: ApprovedCycleForecastInput): string {
+	const parts = new Intl.DateTimeFormat("en-CA", {
+		timeZone: forecast.target_period.timezone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).formatToParts(new Date(forecast.target_period.start_inclusive));
+	const values = Object.fromEntries(parts.map((part) => [part.type, part.value]));
+	return `${values.year}-${values.month}-${values.day}`;
+}
+
+function addDay(date: string): string {
+	const value = new Date(`${date}T00:00:00Z`);
+	value.setUTCDate(value.getUTCDate() + 1);
+	return value.toISOString().slice(0, 10);
+}
+
+function approximatelyEqual(left: number, right: number): boolean {
+	return Math.abs(left - right) <= Math.max(0.000001, Math.max(Math.abs(left), Math.abs(right)) * 0.000001);
+}
+
+function actualsReconcile(actuals: DashboardActualsSnapshot, current: ApprovedCycleForecastInput): boolean {
+	if (actuals.snapshot_evidence.consistency !== "single_statement"
+		|| !actuals.snapshot_evidence.snapshot_id
+		|| !actuals.snapshot_evidence.available_at
+		|| !actuals.snapshot_evidence.source_close_signal_id
+		|| !actuals.snapshot_evidence.source_closed_through
+		|| !actuals.snapshot_evidence.source_close_emitted_at
+		|| !actuals.snapshot_evidence.source_close_signal_sha256
+		|| !actuals.snapshot_evidence.period_complete
+		|| !actuals.snapshot_evidence.reconciled) return false;
+	const start = periodStartDate(current);
+	const end = periodFinalDate(current);
+	if (actuals.coverage.date_min !== start || actuals.coverage.date_max !== end || actuals.coverage.source_rows <= 0) return false;
+	const byDate = new Map(actuals.daily.map((point) => [point.date, point]));
+	let dailySpend = 0;
+	let dailyRevenue = 0;
+	for (let date = start; date <= end; date = addDay(date)) {
+		const point = byDate.get(date);
+		if (!point || point.spend === null || point.revenue === null) return false;
+		dailySpend += point.spend;
+		dailyRevenue += point.revenue;
+	}
+	if (byDate.size !== actuals.daily.length || actuals.current.spend === null || actuals.current.revenue === null) return false;
+	const approvedKeys = new Set(current.approved_allocation.map((item) => `${item.app_id}\u0000${item.store}\u0000${item.channel_group}`));
+	const approvedSlices = actuals.slices.filter((item) => approvedKeys.has(`${item.app_id}\u0000${item.store}\u0000${item.channel_group}`));
+	const sliceSpend = approvedSlices.reduce<number | null>((sum, item) => sum === null || item.spend === null ? null : sum + item.spend, 0);
+	const sliceRevenue = approvedSlices.reduce<number | null>((sum, item) => sum === null || item.revenue === null ? null : sum + item.revenue, 0);
+	return sliceSpend !== null && sliceRevenue !== null
+		&& approximatelyEqual(dailySpend, actuals.current.spend)
+		&& approximatelyEqual(dailyRevenue, actuals.current.revenue)
+		&& approximatelyEqual(sliceSpend, actuals.current.spend)
+		&& approximatelyEqual(sliceRevenue, actuals.current.revenue);
+}
+
+function assertActualsMatchForecast(actuals: DashboardActualsSnapshot, current: ApprovedCycleForecastInput): void {
+	if (actuals.reporting_currency !== current.reporting_currency) throw new Error("actuals reporting_currency does not match current_forecast.");
+	if (actuals.period.start_inclusive !== current.target_period.start_inclusive
+		|| actuals.period.end_exclusive !== current.target_period.end_exclusive
+		|| actuals.period.timezone !== current.target_period.timezone) {
+		throw new Error("actuals period does not match current_forecast target_period.");
+	}
+}
+
+export function projectCycleOperatingProjection(input: CycleOperatingProjectionInput): CycleOperatingProjection {
+	const scopeId = identity(input.scope_id, "scope_id");
+	const cycleId = identity(input.cycle_id, "cycle_id");
+	const current = forecast(input.current_forecast, "current_forecast");
+	const actuals = validateActualsSnapshot(input.actuals);
+	assertActualsMatchForecast(actuals, current);
+	const receipt = input.execution === undefined ? undefined : execution(input.execution, current);
+	const next = input.next_forecast === undefined ? undefined : forecast(input.next_forecast, "next_forecast");
+	if (next && (Date.parse(next.target_period.start_inclusive) !== Date.parse(current.target_period.end_exclusive)
+		|| next.target_period.timezone !== current.target_period.timezone)) {
+		throw new Error("next_forecast target period must be the exact successor of the current cycle in the same timezone.");
+	}
+	if (next && next.reporting_currency !== current.reporting_currency) throw new Error("next_forecast reporting_currency must match current_forecast.");
+	if (next && (next.status !== "complete" || !next.approval_conditions_satisfied)) {
+		throw new Error("next_forecast must be complete with approval conditions satisfied.");
+	}
+
+	const forecastSpend = scenario(current.consolidated_forecast.spend, "current_forecast.consolidated_forecast.spend");
+	const forecastRevenue = scenario(current.consolidated_forecast.revenue, "current_forecast.consolidated_forecast.revenue");
+	const forecastRoas = scenario(current.consolidated_forecast.roas, "current_forecast.consolidated_forecast.roas");
+	const actualSpend = actuals.current.spend;
+	const actualRevenue = actuals.current.revenue;
+	const reachesPeriodEnd = actuals.data_as_of !== ACTUALS_DATA_AS_OF_UNAVAILABLE
+		&& actuals.coverage.date_max !== null
+		&& actuals.coverage.date_max >= periodFinalDate(current);
+	const originalForecast = input.current_forecast_role === "original"
+		&& Date.parse(current.frozen_at) <= Date.parse(current.target_period.start_inclusive);
+	const reconciledSnapshot = actualsReconcile(actuals, current);
+	const actualsMissing = actualSpend === null || actualRevenue === null;
+	const varianceStatus = actualsMissing
+		? "not_comparable_missing_actuals" as const
+		: !reachesPeriodEnd ? "not_comparable_partial_period" as const
+			: !reconciledSnapshot ? "not_comparable_unverified_snapshot" as const
+				: !originalForecast ? "not_comparable_non_original_forecast" as const
+					: "closed_comparable" as const;
+	const revenueDelta = varianceStatus === "closed_comparable" && forecastRevenue.base !== null ? round(actualRevenue - forecastRevenue.base) : null;
+	const spendDelta = varianceStatus === "closed_comparable" && forecastSpend.base !== null ? round(actualSpend - forecastSpend.base) : null;
+	const warnings: string[] = [];
+	if (varianceStatus === "not_comparable_partial_period") warnings.push("Current Actuals are partial-period; full-cycle forecast variance is intentionally unavailable.");
+	if (varianceStatus === "not_comparable_missing_actuals") warnings.push("Current Actuals are incomplete; forecast variance is unavailable.");
+	if (varianceStatus === "not_comparable_unverified_snapshot") warnings.push("Actuals have not supplied a complete, reconciled single-statement snapshot; closed-cycle variance is unavailable.");
+	if (varianceStatus === "not_comparable_non_original_forecast") warnings.push("The linked forecast is not a pre-period original forecast; it cannot be used as the closed-cycle accuracy baseline.");
+	if (!receipt) warnings.push("No execution receipt is linked to the current forecast.");
+	else if (receipt.verification_status !== "verified") warnings.push(`Execution is ${receipt.verification_status}, not externally verified.`);
+	if (!next) warnings.push("No approved next-cycle forecast is available; next-cycle strategy and expected revenue are unavailable.");
+	const nextSpend = next ? scenario(next.consolidated_forecast.spend, "next_forecast.consolidated_forecast.spend") : null;
+	const nextRevenue = next ? scenario(next.consolidated_forecast.revenue, "next_forecast.consolidated_forecast.revenue") : null;
+	const nextRoas = next ? scenario(next.consolidated_forecast.roas, "next_forecast.consolidated_forecast.roas") : null;
+	const nextHasLimits = !!next && (nextSpend?.base === null || nextRevenue?.base === null || nextRoas?.base === null
+		|| next.approved_allocation.some((item) => !item.owner));
+	if (nextHasLimits) warnings.push("The next-cycle forecast is approved with unsupported base metrics; unavailable expectations remain null.");
+	if (next?.approved_allocation.some((item) => !item.owner)) warnings.push("At least one next-cycle allocation has no accountable owner; strategy readiness is limited.");
+
+	return {
+		kind: "fpa.cycle-operating-projection",
+		schema_version: 1,
+		scope_id: scopeId,
+		cycle_id: cycleId,
+		data_as_of: actuals.data_as_of,
+		reporting_currency: current.reporting_currency,
+		current_cycle: {
+			forecast_version: current.forecast_version,
+			target_period: current.target_period,
+			forecast: { spend: forecastSpend, revenue: forecastRevenue, roas: forecastRoas },
+			actual_to_date: { spend: actualSpend, revenue: actualRevenue, roas: safeRatio(actualRevenue, actualSpend) },
+			variance: {
+				status: varianceStatus,
+				revenue_delta: revenueDelta,
+				revenue_delta_pct: safeRatio(revenueDelta, forecastRevenue.base),
+				spend_delta: spendDelta,
+				spend_delta_pct: safeRatio(spendDelta, forecastSpend.base),
+			},
+			execution: receipt ? {
+				status: receipt.status,
+				verification_status: receipt.verification_status,
+				execution_mode: receipt.execution_mode,
+				reconciliation_result: receipt.reconciliation.result,
+				external_evidence_count: receipt.external_receipt_ids.length,
+			} : { status: "not_recorded", verification_status: "not_recorded", execution_mode: "not_recorded", reconciliation_result: "not_recorded", external_evidence_count: 0 },
+		},
+		next_cycle: next ? {
+			status: nextHasLimits ? "ready_with_limits" : "ready",
+			forecast_version: next.forecast_version,
+			target_period: next.target_period,
+			expected_spend: nextSpend as ScenarioValues,
+			expected_revenue: nextRevenue as ScenarioValues,
+			expected_roas: nextRoas as ScenarioValues,
+			strategy: next.approved_allocation.map((item) => {
+				const slice = next.forecast_by_slice.find((candidate) => candidate.app_id === item.app_id && candidate.store === item.store && candidate.channel_group === item.channel_group);
+				const spendChange = item.baseline_spend === null ? null : round(item.approved_spend - item.baseline_spend);
+				return {
+					app_id: item.app_id,
+					store: item.store,
+					channel_group: item.channel_group,
+					action: item.action,
+					baseline_spend: item.baseline_spend,
+					approved_spend: item.approved_spend,
+					spend_change: spendChange,
+					spend_change_pct: safeRatio(spendChange, item.baseline_spend),
+					expected_revenue: slice?.metrics.revenue?.base ?? null,
+					approval_id: next.human_approval_id,
+					strategy_review_id: next.strategy_review_id,
+					stop_loss_roas_lt: next.calibration_policy.stop_loss_roas_lt,
+					owner: item.owner ?? null,
+				};
+			}),
+		} : {
+			status: "unavailable",
+			reason: "No approved next-cycle forecast is linked.",
+		},
+		warnings,
+	};
+}
+
+function formatCurrency(value: number | null, currency: string, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, {
+		style: "currency",
+		currency,
+		currencyDisplay: "narrowSymbol",
+		minimumFractionDigits: 0,
+		maximumFractionDigits: 2,
+	}).format(value);
+}
+
+function formatPercent(value: number | null, locale: string): string | null {
+	if (value === null) return null;
+	return new Intl.NumberFormat(locale, { style: "percent", minimumFractionDigits: 1, maximumFractionDigits: 1, signDisplay: "always" }).format(value);
+}
+
+function toned(value: string | null, tone?: "positive" | "negative" | "warning" | "neutral"): TableCell {
+	return { value, ...(tone ? { tone } : {}) };
+}
+
+export function projectCycleDecisionWidgets(
+	projection: CycleOperatingProjection,
+	locale = "zh-CN",
+): DashboardWidget[] {
+	const zh = locale.toLowerCase().startsWith("zh");
+	const variance = projection.current_cycle.variance;
+	const varianceTone = variance.revenue_delta === null
+		? "neutral" as const
+		: variance.revenue_delta >= 0 ? "positive" as const : "negative" as const;
+	const varianceWidget: DashboardWidget = {
+		id: "closed-cycle-revenue-variance",
+		type: "stat",
+		span: "quarter",
+		dataset: "closed-cycle-revenue-variance.json",
+		data: {
+			label: zh ? "上周期收入预测差异" : "Closed-cycle revenue variance",
+			value: formatCurrency(variance.revenue_delta, projection.reporting_currency, locale),
+			...(variance.revenue_delta === null ? {
+				missingReason: variance.status === "not_comparable_partial_period"
+					? zh ? "周期尚未结束，不能拿累计实际值与整周期预测比较" : "The period is still open; partial Actuals are not compared with a full-cycle forecast."
+					: variance.status === "not_comparable_non_original_forecast"
+						? zh ? "当前版本不是周期开始前冻结的原始预测" : "The linked version is not the pre-period original forecast."
+						: variance.status === "not_comparable_unverified_snapshot"
+							? zh ? "Actual 尚无完整且可勾稽的统一快照" : "Actuals do not yet have a complete reconciled snapshot."
+							: zh ? "实际收入数据不完整" : "Actual revenue is incomplete.",
+			} : {
+				delta: {
+					direction: variance.revenue_delta > 0 ? "up" as const : variance.revenue_delta < 0 ? "down" as const : "flat" as const,
+					label: formatPercent(variance.revenue_delta_pct, locale) ?? "",
+					sentiment: varianceTone,
+				},
+			}),
+			description: zh ? "仅在周期关闭且 Actual 完整时显示" : "Shown only when the cycle is closed and Actuals are complete.",
+		},
+	};
+	const execution = projection.current_cycle.execution;
+	const executionWidget: DashboardWidget = {
+		id: "current-cycle-execution-evidence",
+		type: "stat",
+		span: "quarter",
+		dataset: "current-cycle-execution-evidence.json",
+		data: execution.verification_status === "verified" ? {
+			label: zh ? "本周期执行证据" : "Current-cycle execution evidence",
+			value: zh ? "外部已核验" : "Externally verified",
+			description: zh
+				? `${execution.external_evidence_count} 条外部回执 · 勾稽 ${execution.reconciliation_result}`
+				: `${execution.external_evidence_count} external receipt(s) · reconciliation ${execution.reconciliation_result}`,
+		} : {
+			label: zh ? "本周期执行证据" : "Current-cycle execution evidence",
+			value: null,
+			missingReason: execution.verification_status === "not_recorded"
+				? zh ? "尚无执行回执" : "No execution receipt is linked."
+				: execution.verification_status === "reported"
+					? zh ? "仅人工报告，尚无外部只读核验证据" : "Reported only; no external read-only verification evidence is linked."
+					: zh ? "执行核验失败" : "Execution verification failed.",
+			description: zh ? "观察到 Actual 花费不等于广告账户变更已核验" : "Observed Actual spend is not proof that an ad-account mutation was verified.",
+		},
+	};
+
+	if (projection.next_cycle.status === "unavailable") {
+		return [{
+			id: "next-cycle-readiness",
+			type: "stat",
+			span: "quarter",
+			dataset: "next-cycle-readiness.json",
+			data: {
+				label: zh ? "下一周期投放策略" : "Next-cycle strategy",
+				value: null,
+				missingReason: zh ? "尚无已批准的下一周期预测" : "No approved next-cycle forecast is available.",
+				description: zh ? "不会用当前周期策略冒充下一周期建议" : "The current-cycle allocation is never relabeled as a next-cycle recommendation.",
+			},
+		}, executionWidget, varianceWidget];
+	}
+
+	const next = projection.next_cycle;
+	const nextSpend = next.expected_spend.base;
+	const nextRevenue = next.expected_revenue.base;
+	const channelRows = [...next.strategy.reduce((groups, item) => {
+		const current = groups.get(item.channel_group) ?? { baseline: 0, baselineComplete: true, spend: 0, revenue: 0, revenueComplete: true, actions: new Set<string>(), owners: new Set<string>(), stopLoss: item.stop_loss_roas_lt };
+		if (item.baseline_spend === null) current.baselineComplete = false;
+		else current.baseline += item.baseline_spend;
+		current.spend += item.approved_spend;
+		if (item.expected_revenue === null) current.revenueComplete = false;
+		else current.revenue += item.expected_revenue;
+		current.actions.add(item.action);
+		if (item.owner) current.owners.add(item.owner);
+		current.stopLoss = Math.max(current.stopLoss, item.stop_loss_roas_lt);
+		groups.set(item.channel_group, current);
+		return groups;
+	}, new Map<string, { baseline: number; baselineComplete: boolean; spend: number; revenue: number; revenueComplete: boolean; actions: Set<string>; owners: Set<string>; stopLoss: number }>()).entries()]
+		.map(([channel, values]) => ({ channel, ...values, expectedRoas: values.revenueComplete ? safeRatio(values.revenue, values.spend) : null }))
+		.sort((left, right) => right.spend - left.spend);
+	const riskUnit = next.strategy
+		.map((item) => ({ item, expectedRoas: safeRatio(item.expected_revenue, item.approved_spend) }))
+		.filter((candidate) => candidate.expectedRoas !== null)
+		.sort((left, right) => ((left.expectedRoas as number) - left.item.stop_loss_roas_lt) - ((right.expectedRoas as number) - right.item.stop_loss_roas_lt))[0];
+	const strategyWidget: DashboardWidget = {
+		id: "next-cycle-strategy",
+		type: "table",
+		span: "full",
+		dataset: "next-cycle-strategy.json",
+		data: {
+			label: zh ? "下一周期投放动作" : "Next-cycle allocation actions",
+			description: zh ? "基线→批准预算→收入影响均来自同一不可变 Forecast；缺失责任人会降低策略就绪状态。" : "Baseline, approved budget and revenue impact share one immutable Forecast; missing ownership limits readiness.",
+			columns: [
+				{ key: "unit", label: zh ? "投放单元" : "Unit" },
+				{ key: "action", label: zh ? "动作" : "Action" },
+				{ key: "baseline", label: zh ? "当前基线" : "Baseline", align: "right" },
+				{ key: "spend", label: zh ? "批准预算" : "Approved spend", align: "right" },
+				{ key: "change", label: zh ? "预算变化" : "Budget change", align: "right" },
+				{ key: "revenue", label: zh ? "预期收入" : "Expected revenue", align: "right" },
+				{ key: "guardrail", label: zh ? "止损/责任" : "Guardrail / owner" },
+			],
+			rows: next.strategy.map((item) => ({
+				unit: `${item.app_id} · ${item.channel_group} · ${item.store}`,
+				action: toned(zh ? ({ stop: "停止", decrease: "减量", hold: "维持", increase: "加量", explore: "探索" } as const)[item.action] : item.action, "neutral"),
+				baseline: formatCurrency(item.baseline_spend, projection.reporting_currency, locale),
+				spend: formatCurrency(item.approved_spend, projection.reporting_currency, locale),
+				change: item.spend_change === null
+					? null
+					: `${formatCurrency(item.spend_change, projection.reporting_currency, locale)} (${formatPercent(item.spend_change_pct, locale)})`,
+				revenue: formatCurrency(item.expected_revenue, projection.reporting_currency, locale),
+				guardrail: zh
+					? `ROAS < ${item.stop_loss_roas_lt} 止损 · ${item.owner ? `责任人 ${item.owner}` : "责任人未记录"} · 审批 ${item.approval_id} · 复核 ${item.strategy_review_id}`
+					: `Stop if ROAS < ${item.stop_loss_roas_lt} · ${item.owner ? `owner ${item.owner}` : "owner not captured"} · approval ${item.approval_id} · review ${item.strategy_review_id}`,
+			})),
+		},
+	};
+	const channelSummaryWidget: DashboardWidget = {
+		id: "next-cycle-channel-summary",
+		type: "table",
+		span: "full",
+		dataset: "next-cycle-channel-summary.json",
+		data: {
+			label: zh ? "下一周期渠道汇总" : "Next-cycle channel summary",
+			description: zh ? "先按渠道判断预算、收入、ROAS 与责任，再下钻到投放单元。" : "Review budget, revenue, ROAS and ownership by channel before drilling into units.",
+			columns: [
+				{ key: "channel", label: zh ? "渠道" : "Channel" },
+				{ key: "action", label: zh ? "动作组合" : "Actions" },
+				{ key: "baseline", label: zh ? "当前基线" : "Baseline", align: "right" },
+				{ key: "spend", label: zh ? "批准预算" : "Approved spend", align: "right" },
+				{ key: "revenue", label: zh ? "预期收入" : "Expected revenue", align: "right" },
+				{ key: "roas", label: "ROAS", align: "right" },
+				{ key: "owner", label: zh ? "责任人" : "Owner" },
+			],
+			rows: channelRows.map((row) => ({
+				channel: row.channel,
+				action: [...row.actions].map((action) => zh ? ({ stop: "停止", decrease: "减量", hold: "维持", increase: "加量", explore: "探索" } as Record<string, string>)[action] ?? action : action).join(" / "),
+				baseline: row.baselineComplete ? formatCurrency(row.baseline, projection.reporting_currency, locale) : null,
+				spend: formatCurrency(row.spend, projection.reporting_currency, locale),
+				revenue: row.revenueComplete ? formatCurrency(row.revenue, projection.reporting_currency, locale) : null,
+				roas: row.expectedRoas === null ? null : toned(row.expectedRoas.toFixed(2), row.expectedRoas < row.stopLoss ? "warning" : "neutral"),
+				owner: row.owners.size > 0 ? [...row.owners].join(" / ") : null,
+			})),
+		},
+	};
+	return [
+		{
+			id: "next-cycle-readiness",
+			type: "stat",
+			span: "quarter",
+			dataset: "next-cycle-readiness.json",
+			data: {
+				label: zh ? "下一周期投放策略" : "Next-cycle strategy",
+				value: next.status === "ready_with_limits" ? (zh ? "已批准·有限" : "Ready with limits") : (zh ? "已批准" : "Ready"),
+				description: `${next.forecast_version} · ${next.target_period.start_inclusive} → ${next.target_period.end_exclusive}`,
+			},
+		},
+		{
+			id: "next-cycle-expected-revenue",
+			type: "stat",
+			span: "quarter",
+			dataset: "next-cycle-expected-revenue.json",
+			data: {
+				label: zh ? "下一周期预期收入" : "Next-cycle expected revenue",
+				value: formatCurrency(nextRevenue, projection.reporting_currency, locale),
+				...(nextRevenue === null ? { missingReason: zh ? "该批准预测未提供可支持的收入基准情景" : "The approved forecast does not support a base revenue expectation." } : {}),
+				footnote: `${zh ? "下行" : "Downside"} ${formatCurrency(next.expected_revenue.downside, projection.reporting_currency, locale) ?? "—"} · ${zh ? "上行" : "Upside"} ${formatCurrency(next.expected_revenue.upside, projection.reporting_currency, locale) ?? "—"}`,
+			},
+		},
+		{
+			id: "next-cycle-approved-spend",
+			type: "stat",
+			span: "quarter",
+			dataset: "next-cycle-approved-spend.json",
+			data: {
+				label: zh ? "下一周期批准预算" : "Next-cycle approved spend",
+				value: formatCurrency(nextSpend, projection.reporting_currency, locale),
+				description: zh ? "与预期收入使用同一批准预测版本" : "Uses the same approved forecast version as expected revenue.",
+			},
+		},
+		{
+			id: "next-cycle-expected-roas",
+			type: "stat",
+			span: "quarter",
+			dataset: "next-cycle-expected-roas.json",
+			data: {
+				label: zh ? "下一周期预期 ROAS" : "Next-cycle expected ROAS",
+				value: next.expected_roas.base === null ? null : next.expected_roas.base.toFixed(2),
+				...(next.expected_roas.base === null ? { missingReason: zh ? "该批准预测未提供可支持的 ROAS 基准情景" : "The approved forecast does not support a base ROAS expectation." } : {}),
+			},
+		},
+		{
+			id: "next-cycle-max-guardrail-risk",
+			type: "stat",
+			span: "quarter",
+			dataset: "next-cycle-max-guardrail-risk.json",
+			data: riskUnit ? {
+				label: zh ? "离止损线最近" : "Closest to stop-loss",
+				value: `${riskUnit.item.app_id} · ${riskUnit.item.channel_group} · ${riskUnit.item.store}`,
+				description: `${zh ? "预期 ROAS" : "Expected ROAS"} ${(riskUnit.expectedRoas as number).toFixed(2)} · ${zh ? "止损线" : "stop-loss"} ${riskUnit.item.stop_loss_roas_lt.toFixed(2)} · ${zh ? "余量" : "margin"} ${((riskUnit.expectedRoas as number) - riskUnit.item.stop_loss_roas_lt).toFixed(2)} · ${riskUnit.item.owner ?? (zh ? "责任人未记录" : "owner not captured")}`,
+			} : {
+				label: zh ? "离止损线最近" : "Closest to stop-loss",
+				value: null,
+				missingReason: zh ? "投放单元缺少可比较的预期收入" : "Units lack comparable expected revenue.",
+			},
+		},
+		channelSummaryWidget,
+		strategyWidget,
+		executionWidget,
+		varianceWidget,
+	];
+}