@viccydev/pi-fpa 0.3.0 → 0.3.1

package/extensions/fpa-dashboard/actuals.ts

@@ -4,7 +4,8 @@ import type { Period } from "../fpa-artifacts/contracts.ts";
 import { toNumber, type NumericLike } from "../fpa-data/calc.ts";
 import { runStructuredQuery } from "../fpa-data/runtime.ts";
 import type { SqlRow } from "../fpa-data/supabase.ts";
-import type { DashboardActualsSnapshot, DashboardDailyPoint, QueryReceipt } from "./source.ts";
+import type { DashboardActualsSnapshot, DashboardDailyPoint, DashboardScopeMode, QueryReceipt } from "./source.ts";
+import { ACTUALS_DATA_AS_OF_UNAVAILABLE } from "./source.ts";
 
 function dateInTimezone(timestamp: string, timezone: string, label: string): string {
 	const instant = new Date(timestamp);
@@ -96,11 +97,16 @@ export interface DashboardActualsScope {
 	slices: Array<{ app_id: string; store: string; channel_group: string }>;
 }
 
-export function mapDashboardSlices(rows: SqlRow[]) {
+/**
+ * Rows carry app_code only in "app" scope mode. In "portfolio" mode the App axis was
+ * collapsed onto a placeholder before the query ran, so the caller supplies it back.
+ */
+export function mapDashboardSlices(rows: SqlRow[], portfolioAppId?: string) {
 	return rows
-		.filter((row) => row.app_code != null && row.platform != null && row.media_source != null)
+		.filter((row) => row.platform != null && row.media_source != null)
+		.filter((row) => portfolioAppId !== undefined || row.app_code != null)
 		.map((row) => ({
-			app_id: String(row.app_code),
+			app_id: portfolioAppId ?? String(row.app_code),
 			store: String(row.platform),
 			channel_group: String(row.media_source),
 			spend: value(row, "spend"),
@@ -109,6 +115,35 @@ export function mapDashboardSlices(rows: SqlRow[]) {
 		}));
 }
 
+/**
+ * The App axis carries no information when every approved slice shares one app_id.
+ * That is the only case where dropping the app_code predicate can be considered.
+ */
+export function collapsedAppId(slices: DashboardActualsScope["slices"]): string | null {
+	const appIds = new Set(slices.map((slice) => slice.app_id));
+	return appIds.size === 1 ? (slices[0]?.app_id ?? null) : null;
+}
+
+/** True when the value is never used as an app_code in ua_spend, i.e. it is a placeholder. */
+async function isPlaceholderAppId(appId: string, signal?: AbortSignal): Promise<boolean> {
+	const probe = await runStructuredQuery(
+		{ dataset: "ua_spend", metrics: ["spend"], dimensions: ["app_code"], filters: { app_code: appId }, limit: 1 },
+		signal,
+	);
+	return probe.rows.length === 0;
+}
+
+export async function resolveScopeMode(
+	slices: DashboardActualsScope["slices"],
+	signal?: AbortSignal,
+): Promise<{ mode: DashboardScopeMode; portfolioAppId: string | null }> {
+	const collapsed = collapsedAppId(slices);
+	if (collapsed === null) return { mode: "app", portfolioAppId: null };
+	// A single real app still scopes on app_code; only a value absent from the mart is a placeholder.
+	if (!(await isPlaceholderAppId(collapsed, signal))) return { mode: "app", portfolioAppId: null };
+	return { mode: "portfolio", portfolioAppId: collapsed };
+}
+
 export async function loadDashboardActuals(
 	period: Period,
 	scope: DashboardActualsScope,
@@ -123,30 +158,41 @@ export async function loadDashboardActuals(
 	};
 	const exactUaScope = uniqueSlices.map((slice) => ({ app_code: slice.app_id, platform: slice.store, media_source: slice.channel_group }));
 	const exactUaPortfolioScope = [...new Map(uniqueSlices.map((slice) => [`${slice.app_id}\u0000${slice.store}`, { app_code: slice.app_id, platform: slice.store }])).values()];
-	const current = await runStructuredQuery({ ...common, exactUaScope, dateFrom: dates.currentFrom, dateTo: dates.currentTo, limit: 1 }, signal);
+	const { mode, portfolioAppId } = await resolveScopeMode(uniqueSlices, signal);
+	const portfolio = mode === "portfolio";
+	// In portfolio mode the App axis is a placeholder absent from ua_spend, so scoping on
+	// app_code would match nothing. Drop it and aggregate every app at platform x media_source.
+	const sliceScope = portfolio
+		? { exactUaChannelScope: [...new Map(uniqueSlices.map((slice) => [`${slice.store}\u0000${slice.channel_group}`, { platform: slice.store, media_source: slice.channel_group }])).values()] }
+		: { exactUaScope };
+	const discoveryScope = portfolio
+		? { filters: { platform: [...new Set(uniqueSlices.map((slice) => slice.store))] } }
+		: { exactUaPortfolioScope };
+	const sliceDimensions = portfolio ? ["platform", "media_source"] : ["app_code", "platform", "media_source"];
+	const current = await runStructuredQuery({ ...common, ...sliceScope, dateFrom: dates.currentFrom, dateTo: dates.currentTo, limit: 1 }, signal);
 	const currentRow = current.rows[0];
 	const coverageMin = currentRow?.date_min == null ? null : String(currentRow.date_min);
 	const coverageMax = currentRow?.date_max == null ? null : String(currentRow.date_max);
 	const comparisonDates = coverageMax ? comparisonDatesForCoverage(dates.currentFrom, coverageMax) : null;
 	const [comparison, daily, approvedSlices, discoveredSlices] = await Promise.all([
 		comparisonDates
-			? runStructuredQuery({ ...common, exactUaScope, dateFrom: comparisonDates.comparisonFrom, dateTo: comparisonDates.comparisonTo, limit: 1 }, signal)
+			? runStructuredQuery({ ...common, ...sliceScope, dateFrom: comparisonDates.comparisonFrom, dateTo: comparisonDates.comparisonTo, limit: 1 }, signal)
 			: Promise.resolve(null),
-		runStructuredQuery({ ...common, exactUaScope, dateFrom: dates.currentFrom, dateTo: dates.currentTo, timeGrain: "day", limit: 1000 }, signal),
+		runStructuredQuery({ ...common, ...sliceScope, dateFrom: dates.currentFrom, dateTo: dates.currentTo, timeGrain: "day", limit: 1000 }, signal),
 		runStructuredQuery({
 			...common,
 			dateFrom: dates.currentFrom,
 			dateTo: dates.currentTo,
-			exactUaScope,
-			dimensions: ["app_code", "platform", "media_source"],
+			...sliceScope,
+			dimensions: sliceDimensions,
 			limit: 500,
 		}, signal),
 		runStructuredQuery({
 			...common,
 			dateFrom: dates.currentFrom,
 			dateTo: dates.currentTo,
-			exactUaPortfolioScope,
-			dimensions: ["app_code", "platform", "media_source"],
+			...discoveryScope,
+			dimensions: sliceDimensions,
 			limit: 1000,
 		}, signal),
 	]);
@@ -159,16 +205,23 @@ export async function loadDashboardActuals(
 		receipt("ua_spend.slices.approved", approvedSlices.built.sql, approvedSlices.rows.length),
 		receipt("ua_spend.slices.discovery", discoveredSlices.built.sql, discoveredSlices.rows.length),
 	];
-	const approvedKeys = new Set(exactUaScope.map((scope) => `${scope.app_code}\u0000${scope.platform}\u0000${scope.media_source}`));
+	const approvedKeys = new Set(
+		portfolio
+			? uniqueSlices.map((slice) => `${slice.store}\u0000${slice.channel_group}`)
+			: exactUaScope.map((scope) => `${scope.app_code}\u0000${scope.platform}\u0000${scope.media_source}`),
+	);
+	const rowKey = (row: SqlRow): string =>
+		portfolio ? `${row.platform}\u0000${row.media_source}` : `${row.app_code}\u0000${row.platform}\u0000${row.media_source}`;
 	const sliceRows = [
 		...approvedSlices.rows,
-		...discoveredSlices.rows.filter((row) => !approvedKeys.has(`${row.app_code}\u0000${row.platform}\u0000${row.media_source}`)),
+		...discoveredSlices.rows.filter((row) => !approvedKeys.has(rowKey(row))),
 	];
 
 	return {
 		period,
-		data_as_of: coverageMax ?? "unavailable",
+		data_as_of: coverageMax ?? ACTUALS_DATA_AS_OF_UNAVAILABLE,
 		reporting_currency: "USD",
+		scope_mode: mode,
 		coverage: {
 			date_min: coverageMin,
 			date_max: coverageMax,
@@ -179,7 +232,7 @@ export async function loadDashboardActuals(
 			? { spend: value(comparisonRow, "spend"), revenue: value(comparisonRow, "revenue") }
 			: null,
 		daily: completeDailySeries(daily.rows, dates.currentFrom, coverageMax),
-		slices: mapDashboardSlices(sliceRows),
+		slices: mapDashboardSlices(sliceRows, portfolioAppId ?? undefined),
 		query_receipts: queryReceipts,
 	};
 }

package/extensions/fpa-dashboard/projector.ts

@@ -7,7 +7,7 @@ import {
 	type ForecastAllocation,
 	type ForecastSlice,
 } from "../fpa-artifacts/contracts.ts";
-import { validateActualsSnapshot, type DashboardActualsSnapshot, type DashboardActualSlice } from "./source.ts";
+import { validateActualsSnapshot, ACTUALS_DATA_AS_OF_UNAVAILABLE, type DashboardActualsSnapshot, type DashboardActualSlice } from "./source.ts";
 
 export type Tone = "positive" | "negative" | "warning" | "neutral";
 export type TableCell = string | null | { value: string | null; tone?: Tone };
@@ -123,6 +123,29 @@ function formatRoas(value: number | null): string | null {
 	return value === null ? null : value.toFixed(2);
 }
 
+/** Shown when a ratio is undefined by construction rather than missing from the data. */
+const NOT_APPLICABLE = "—";
+
+/**
+ * ROAS over a zero budget is undefined, not missing. Rendering it as "no data" makes a
+ * deliberately stopped channel look like a broken join, so the two are kept distinct.
+ */
+function roasCell(roas: number | null, spend: number | null, tone?: Tone): TableCell {
+	if (roas === null && spend === 0) return NOT_APPLICABLE;
+	return numericCell(formatRoas(roas), tone);
+}
+
+/** A slice with no planned budget has nothing to deviate from. */
+function deviationCell(deviation: number | null, forecastSpend: number | null, tone?: Tone): TableCell {
+	if (deviation === null && forecastSpend === 0) return NOT_APPLICABLE;
+	return numericCell(formatSignedPercent(deviation), tone);
+}
+
+/** Rows are channel × store; the store is what disambiguates a channel run on both platforms. */
+function sliceUnitLabel(allocation: ForecastAllocation): string {
+	return `${allocation.channel_group} · ${allocation.store}`;
+}
+
 function formatSignedPercent(value: number | null, suffix = ""): string | null {
 	if (value === null) return null;
 	const sign = value > 0 ? "+" : "";
@@ -211,8 +234,9 @@ function buildStrategyTable(
 ): GroupedTableDataset {
 	const grouped = new Map<string, JoinedSlice[]>();
 	for (const slice of joined) grouped.set(slice.allocation.app_id, [...(grouped.get(slice.allocation.app_id) ?? []), slice]);
+	const appAxisIsInformative = grouped.size > 1;
 	const columns = [
-		{ key: "unit", label: "App / 渠道" },
+		{ key: "unit", label: appAxisIsInformative ? "App / 渠道 · 平台" : "渠道 · 平台" },
 		{ key: "forecast", label: "预测 ROAS", align: "right" as const },
 		{ key: "actual", label: "实际 ROAS", align: "right" as const },
 		{ key: "deviation", label: "偏差", align: "right" as const },
@@ -220,7 +244,7 @@ function buildStrategyTable(
 		{ key: "exec", label: "执行状态" },
 	];
 	return {
-		label: "预测 vs 实际 · 执行策略（按 App）",
+		label: `预测 vs 实际 · 执行策略（按${appAxisIsInformative ? " App × 渠道" : "渠道 · 平台"}）`,
 		description:
 			`同周期付费 ROAS；偏差绝对值 ≥ ${(forecast.calibration_policy.deviation_warning_abs_gte * 100).toFixed(0)}% 标黄，` +
 			`> ${(forecast.calibration_policy.deviation_trigger_abs_gt * 100).toFixed(0)}% 触发校准。`,
@@ -249,20 +273,21 @@ function buildStrategyTable(
 				key: appId,
 				label: appId,
 				summary: {
-					forecast: formatRoas(appForecast),
-					actual: formatRoas(appActual),
-					deviation: numericCell(formatSignedPercent(appDeviation), appDeviation !== null && Math.abs(appDeviation) >= forecast.calibration_policy.deviation_warning_abs_gte ? "warning" : undefined),
+					forecast: roasCell(appForecast, forecastSpend),
+					actual: roasCell(appActual, actualSpend),
+					deviation: deviationCell(appDeviation, forecastSpend, appDeviation !== null && Math.abs(appDeviation) >= forecast.calibration_policy.deviation_warning_abs_gte ? "warning" : undefined),
 					decision: summaryTone ? { value: summaryAction, tone: summaryTone } : summaryAction,
 					exec: executionGroupLabel(executionReceipt, slices),
 				},
 				rows: slices.map((slice) => {
 					const stop = slice.actualRoas !== null && slice.actualRoas < forecast.calibration_policy.stop_loss_roas_lt;
 					const warn = slice.deviation !== null && Math.abs(slice.deviation) >= forecast.calibration_policy.deviation_warning_abs_gte;
+					const plannedSpend = slice.forecast.metrics.spend?.base ?? null;
 					return {
-						unit: slice.allocation.channel_group,
-						forecast: formatRoas(slice.forecastRoas),
-						actual: numericCell(formatRoas(slice.actualRoas), stop ? "negative" : undefined),
-						deviation: numericCell(formatSignedPercent(slice.deviation), stop ? "negative" : warn ? "warning" : undefined),
+						unit: sliceUnitLabel(slice.allocation),
+						forecast: roasCell(slice.forecastRoas, plannedSpend),
+						actual: roasCell(slice.actualRoas, slice.actual?.spend ?? null, stop ? "negative" : undefined),
+						deviation: deviationCell(slice.deviation, plannedSpend, stop ? "negative" : warn ? "warning" : undefined),
 						decision: actionCell(slice.allocation.action),
 						exec: executionLabel(executionReceipt, slice.execution),
 					};
@@ -276,7 +301,7 @@ function buildAlerts(joined: JoinedSlice[], forecast: ApprovedCycleForecastInput
 	const rows: Array<Record<string, TableCell>> = [];
 	for (const slice of joined) {
 		if (slice.actualRoas === null) continue;
-		const unit = `${slice.allocation.app_id} × ${slice.allocation.channel_group}`;
+		const unit = `${slice.allocation.app_id} × ${sliceUnitLabel(slice.allocation)}`;
 		if (slice.actualRoas < forecast.calibration_policy.stop_loss_roas_lt) {
 			rows.push({
 				level: { value: "严重", tone: "negative" },
@@ -344,6 +369,7 @@ export function projectDashboard(input: ProjectionInput): DashboardBuild {
 	const stopCount = joined.filter((slice) => slice.actualRoas !== null && slice.actualRoas < forecast.calibration_policy.stop_loss_roas_lt).length;
 	const deviationCount = alerts.rows.length - stopCount;
 	const window = `${formatPeriodDate(forecast.target_period.start_inclusive, forecast.target_period.timezone, locale)} → ${formatPeriodDate(forecast.target_period.end_exclusive, forecast.target_period.timezone, locale)}（end exclusive）`;
+	const asOfNote = actuals.data_as_of === ACTUALS_DATA_AS_OF_UNAVAILABLE ? "本周期暂无 Actuals" : `Actuals 截至 ${actuals.data_as_of}`;
 
 	const widgets: DashboardWidget[] = [
 		{
@@ -366,7 +392,7 @@ export function projectDashboard(input: ProjectionInput): DashboardBuild {
 					progress: { fraction: clampFraction(revenueAttainment), label: formatSignedPercent(revenueAttainment)?.replace(/^\+/, "") ?? "无数据", tone: progressTone(revenueAttainment) },
 					description: `冻结预测 ${formatCurrency(forecastRevenue, forecast.reporting_currency, locale)}`,
 				}),
-				footnote: `${window}；Actuals as of ${actuals.data_as_of}`,
+				footnote: `${window}；${asOfNote}`,
 			},
 		},
 		{
@@ -474,6 +500,13 @@ export function projectDashboard(input: ProjectionInput): DashboardBuild {
 		warnings: [
 			...(forecast.status !== "complete" ? [`Approved forecast status is ${forecast.status}.`] : []),
 			...(!forecast.approval_conditions_satisfied ? ["Approved forecast conditions are not satisfied."] : []),
+			...(actuals.scope_mode === "portfolio"
+				? [
+					`App axis "${forecast.approved_allocation[0]?.app_id}" is not an app_code in ua_spend; ` +
+						"Actuals were aggregated across every app at the store × channel grain. " +
+						"Verify this matches the declared forecast scope before reading App-level conclusions into it.",
+				]
+				: []),
 			...(execution?.verification_status === "reported" ? ["Execution is reported and not externally verified."] : []),
 			...(missingExecutionSlices > 0 ? [`Execution receipt is missing ${missingExecutionSlices} approved slices.`] : []),
 			...(extraExecutionSlices > 0 ? [`Execution receipt contains ${extraExecutionSlices} slices outside the approved allocation.`] : []),

package/extensions/fpa-dashboard/source.ts

@@ -15,6 +15,19 @@ export interface DashboardActualSlice {
 	source_rows: number;
 }
 
+/** Sentinel used when no Actuals row exists yet, so no calendar date can be reported. */
+export const ACTUALS_DATA_AS_OF_UNAVAILABLE = "unavailable";
+
+/**
+ * How Actuals were scoped against the frozen forecast.
+ *
+ * "app"       - every slice matched ua_spend on app_code × platform × media_source.
+ * "portfolio" - the forecast collapsed the App axis onto a placeholder that does not
+ *               exist in ua_spend, so Actuals were aggregated across every app at the
+ *               platform × media_source grain.
+ */
+export type DashboardScopeMode = "app" | "portfolio";
+
 export interface DashboardDailyPoint {
 	date: string;
 	spend: number | null;
@@ -25,6 +38,7 @@ export interface DashboardActualsSnapshot {
 	period: Period;
 	data_as_of: string;
 	reporting_currency: string;
+	scope_mode: DashboardScopeMode;
 	coverage: {
 		date_min: string | null;
 		date_max: string | null;
@@ -127,10 +141,13 @@ export function validateActualsSnapshot(value: unknown): DashboardActualsSnapsho
 
 	const reportingCurrency = string(source.reporting_currency, "actuals.reporting_currency").toUpperCase();
 	if (!/^[A-Z]{3}$/.test(reportingCurrency)) throw new Error("actuals.reporting_currency must be an ISO-4217 currency code.");
+	const scopeMode = source.scope_mode === undefined ? "app" : string(source.scope_mode, "actuals.scope_mode");
+	if (scopeMode !== "app" && scopeMode !== "portfolio") throw new Error('actuals.scope_mode must be "app" or "portfolio".');
 	return {
 		period: period(source.period, "actuals.period"),
 		data_as_of: string(source.data_as_of, "actuals.data_as_of"),
 		reporting_currency: reportingCurrency,
+		scope_mode: scopeMode,
 		coverage: {
 			date_min: coverage.date_min === null ? null : string(coverage.date_min, "actuals.coverage.date_min"),
 			date_max: coverage.date_max === null ? null : string(coverage.date_max, "actuals.coverage.date_max"),

package/extensions/fpa-data/sql.ts

@@ -27,6 +27,12 @@ export interface QuerySpec {
 	exactUaScope?: Array<{ app_code: string; platform: string; media_source: string }>;
 	/** Internal exact App + Store portfolio scope used to discover unplanned paid channels. */
 	exactUaPortfolioScope?: Array<{ app_code: string; platform: string }>;
+	/**
+	 * Internal exact Store + Channel scope for forecasts whose App axis is a portfolio
+	 * placeholder. The placeholder never matches ua_spend.app_code, so the App predicate
+	 * is dropped and Actuals are aggregated across every app.
+	 */
+	exactUaChannelScope?: Array<{ platform: string; media_source: string }>;
 	sort?: { by: string; direction?: "asc" | "desc" };
 	limit?: number;
 }
@@ -233,6 +239,20 @@ export function buildQuery(spec: QuerySpec): BuiltQuery {
 		filterKeys.push("app_code", "platform");
 		notes.push("Applied exact App + Store portfolio scope.");
 	}
+	if (spec.exactUaChannelScope !== undefined) {
+		if (dataset.id !== "ua_spend") throw new Error("exactUaChannelScope is supported only for ua_spend.");
+		if (spec.exactUaChannelScope.length === 0 || spec.exactUaChannelScope.length > 500) throw new Error("exactUaChannelScope must contain between 1 and 500 Store + Channel pairs.");
+		const dimensionSql = Object.fromEntries(dataset.dimensions.map((dimension) => [dimension.name, dimension.sql]));
+		const predicates = spec.exactUaChannelScope.map((scope, index) => {
+			for (const [name, value] of Object.entries(scope)) {
+				if (typeof value !== "string" || value.trim() === "") throw new Error(`exactUaChannelScope[${index}].${name} must be a non-empty string.`);
+			}
+			return `(${dimensionSql.platform} = ${escapeLiteral(scope.platform)} and ${dimensionSql.media_source} = ${escapeLiteral(scope.media_source)})`;
+		});
+		where.push(`(${predicates.join(" or ")})`);
+		filterKeys.push("platform", "media_source");
+		notes.push("Applied exact Store + Channel scope across every app (portfolio-placeholder forecast).");
+	}
 
 	const breakdown = resolveBreakdown(dataset, dimensionNames, filterKeys);
 	if (breakdown.predicate) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viccydev/pi-fpa",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Full-cycle FP&A planning, strategy, forecast, and review prompts, skills, and data tools for Pi",
   "license": "UNLICENSED",