@viccydev/pi-fpa 0.8.1 → 0.9.0

package/README.md

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

package/extensions/fpa-artifacts/compose.ts

@@ -6,10 +6,16 @@ import {
 	type AllocationAction,
 	type ApprovedCycleForecastInput,
 	type ForecastAllocation,
+	type ForecastConclusion,
 	type ForecastSlice,
 	type Period,
 	type ScenarioMetric,
 } from "./contracts.ts";
+import {
+	assessForecastQuality,
+	type ForecastDimensionSnapshot,
+	type ForecastQualityAssessment,
+} from "./forecast-quality.ts";
 
 // ============================================================================
 // Composing an approved forecast from a compact plan.
@@ -36,11 +42,7 @@ import {
 // ============================================================================
 
 /** Distinct dimension values a plan's slice keys must be drawn from. */
-export interface UaDimensionValues {
-	app_code: Set<string>;
-	platform: Set<string>;
-	media_source: Set<string>;
-}
+export interface UaDimensionValues extends ForecastDimensionSnapshot {}
 
 export interface PlanSliceRoas {
 	downside: number | null;
@@ -172,7 +174,10 @@ function sumScenario(values: Array<number | null>): number | null {
 export interface ComposeDiagnostics {
 	slice_count: number;
 	stopped_slice_count: number;
+	limited_slice_count: number;
 	total_approved_spend: number;
+	calculable_approved_spend: number;
+	calculable_spend_pct: number;
 	validated_dimensions: boolean;
 	portfolio_placeholder_app_id: string | null;
 }
@@ -192,21 +197,78 @@ export interface ComposeResult {
  */
 export async function loadUaDimensionValues(signal?: AbortSignal): Promise<UaDimensionValues> {
 	const result = await runStructuredQuery(
-		{ dataset: "ua_spend", metrics: ["spend"], dimensions: ["app_code", "platform", "media_source"], limit: 5000 },
+		{ dataset: "ua_spend", metrics: ["spend"], dimensions: ["app_code", "platform", "media_source"], limit: 1000 },
 		signal,
 	);
-	const values: UaDimensionValues = { app_code: new Set(), platform: new Set(), media_source: new Set() };
+	const values: UaDimensionValues = { app_code: new Set(), platform: new Set(), media_source: new Set(), tuples: new Set() };
 	for (const row of result.rows) {
 		if (row.app_code != null) values.app_code.add(String(row.app_code));
 		if (row.platform != null) values.platform.add(String(row.platform));
 		if (row.media_source != null) values.media_source.add(String(row.media_source));
+		if (row.app_code != null && row.platform != null && row.media_source != null) {
+			values.tuples?.add(sliceKey({
+				app_id: String(row.app_code),
+				store: String(row.platform),
+				channel_group: String(row.media_source),
+			}));
+		}
 	}
 	return values;
 }
 
-function sample(values: Set<string>, limit = 8): string {
-	const list = [...values].sort();
-	return list.length <= limit ? list.join(", ") : `${list.slice(0, limit).join(", ")}, … (${list.length} total)`;
+/**
+ * Read only the candidate tuples named by the plan. This avoids treating the
+ * structured query's 1000-row safety cap as a complete dimension catalog.
+ */
+async function loadUaDimensionValuesForSlices(slices: PlanSlice[], signal?: AbortSignal): Promise<UaDimensionValues> {
+	const appIds = new Set(slices.map((slice) => slice.app_id));
+	const collapsedAppId = appIds.size === 1 ? [...appIds][0] : null;
+	let portfolioMode = false;
+	if (collapsedAppId !== null) {
+		const appProbe = await runStructuredQuery({
+			dataset: "ua_spend",
+			metrics: ["spend"],
+			dimensions: ["app_code"],
+			filters: { app_code: collapsedAppId },
+			limit: 1,
+		}, signal);
+		portfolioMode = appProbe.rows.length === 0;
+	}
+
+	const uniqueSlices = [...new Map(slices.map((slice) => [sliceKey(slice), slice])).values()];
+	const result = portfolioMode
+		? await runStructuredQuery({
+			dataset: "ua_spend",
+			metrics: ["spend"],
+			dimensions: ["platform", "media_source"],
+			exactUaChannelScope: uniqueSlices.map((slice) => ({ platform: slice.store, media_source: slice.channel_group })),
+			limit: uniqueSlices.length,
+		}, signal)
+		: await runStructuredQuery({
+			dataset: "ua_spend",
+			metrics: ["spend"],
+			dimensions: ["app_code", "platform", "media_source"],
+			exactUaScope: uniqueSlices.map((slice) => ({
+				app_code: slice.app_id,
+				platform: slice.store,
+				media_source: slice.channel_group,
+			})),
+			limit: uniqueSlices.length,
+		}, signal);
+	const values: UaDimensionValues = { app_code: new Set(), platform: new Set(), media_source: new Set(), tuples: new Set() };
+	for (const row of result.rows) {
+		if (row.app_code != null) values.app_code.add(String(row.app_code));
+		if (row.platform != null) values.platform.add(String(row.platform));
+		if (row.media_source != null) values.media_source.add(String(row.media_source));
+		if (row.platform != null && row.media_source != null) {
+			values.tuples?.add(sliceKey({
+				app_id: row.app_code == null ? "" : String(row.app_code),
+				store: String(row.platform),
+				channel_group: String(row.media_source),
+			}));
+		}
+	}
+	return values;
 }
 
 /**
@@ -218,33 +280,8 @@ function sample(values: Set<string>, limit = 8): string {
  * test the dashboard applies, so the two agree on what "portfolio mode" means.
  * Store and channel have no such mode — a value the mart never uses is an error.
  */
-export function validateSliceKeys(slices: PlanSlice[], values: UaDimensionValues): { portfolioAppId: string | null } {
-	const appIds = new Set(slices.map((slice) => slice.app_id));
-	const collapsed = appIds.size === 1 ? [...appIds][0] : null;
-	const portfolioAppId = collapsed !== null && !values.app_code.has(collapsed) ? collapsed : null;
-
-	const problems: string[] = [];
-	const badStores = [...new Set(slices.map((slice) => slice.store).filter((store) => !values.platform.has(store)))];
-	if (badStores.length > 0) {
-		problems.push(`store ${badStores.map((value) => JSON.stringify(value)).join(", ")} is not a ua_spend.platform value. Valid values: ${sample(values.platform)}.`);
-	}
-	const badChannels = [...new Set(slices.map((slice) => slice.channel_group).filter((channel) => !values.media_source.has(channel)))];
-	if (badChannels.length > 0) {
-		problems.push(`channel_group ${badChannels.map((value) => JSON.stringify(value)).join(", ")} is not a ua_spend.media_source value. Valid values: ${sample(values.media_source)}.`);
-	}
-	if (portfolioAppId === null) {
-		const badApps = [...new Set(slices.map((slice) => slice.app_id).filter((appId) => !values.app_code.has(appId)))];
-		if (badApps.length > 0) {
-			problems.push(`app_id ${badApps.map((value) => JSON.stringify(value)).join(", ")} is not a ua_spend.app_code value. Valid values: ${sample(values.app_code)}.`);
-		}
-	}
-	if (problems.length > 0) {
-		throw new Error(
-			`Plan slice keys do not exist in ua_spend, so every Actuals lookup for this forecast would match nothing:\n`
-				+ problems.map((problem) => `- ${problem}`).join("\n"),
-		);
-	}
-	return { portfolioAppId };
+export function validateSliceKeys(slices: PlanSlice[], values: UaDimensionValues): ForecastQualityAssessment {
+	return assessForecastQuality(slices, values);
 }
 
 export interface ComposeOptions {
@@ -263,6 +300,7 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 	}
 	if (!Array.isArray(source.slices) || source.slices.length === 0) throw new Error("plan.slices must be a non-empty array.");
 	const slices = source.slices.map((value, index) => planSlice(value, index));
+	if (slices.length > 500) throw new Error("plan.slices cannot exceed 500 slices.");
 
 	const seen = new Set<string>();
 	for (const slice of slices) {
@@ -289,9 +327,28 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 				+ "Scope deliberately excluded upstream is not a limit — if nothing in scope is missing, the status is complete.",
 		);
 	}
+	if (status === "complete_with_limits") {
+		for (const [index, value] of unsupported.entries()) {
+			const item = record(value, `plan.unsupported_metrics[${index}]`);
+			text(item.metric, `plan.unsupported_metrics[${index}].metric`);
+			text(item.reason, `plan.unsupported_metrics[${index}].reason`);
+			if (!Array.isArray(item.affected_scope) || item.affected_scope.length === 0) {
+				throw new Error(`plan.unsupported_metrics[${index}].affected_scope must be a non-empty array.`);
+			}
+			for (const [scopeIndex, scope] of item.affected_scope.entries()) text(scope, `plan.unsupported_metrics[${index}].affected_scope[${scopeIndex}]`);
+			const evidence = Array.isArray(item.evidence) ? item.evidence : [item.evidence];
+			if (evidence.length === 0) throw new Error(`plan.unsupported_metrics[${index}].evidence must not be empty.`);
+			for (const [evidenceIndex, entry] of evidence.entries()) text(entry, `plan.unsupported_metrics[${index}].evidence[${evidenceIndex}]`);
+			text(item.remediation, `plan.unsupported_metrics[${index}].remediation`);
+			text(item.owner_role, `plan.unsupported_metrics[${index}].owner_role`);
+		}
+	}
 
-	const loadValues = options.loadDimensionValues ?? loadUaDimensionValues;
-	const { portfolioAppId } = validateSliceKeys(slices, await loadValues(options.signal));
+	const dimensionValues = options.loadDimensionValues
+		? await options.loadDimensionValues(options.signal)
+		: await loadUaDimensionValuesForSlices(slices, options.signal);
+	const quality = validateSliceKeys(slices, dimensionValues);
+	const { portfolioAppId } = quality;
 
 	const period = record(source.target_period, "plan.target_period") as unknown as Period;
 	const currency = text(source.reporting_currency, "plan.reporting_currency").toUpperCase();
@@ -310,8 +367,11 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 	// Spend is the decision, not a prediction: an approved allocation is the same
 	// number in every scenario. Only revenue moves, through the ROAS assumption.
 	const forecastBySlice: ForecastSlice[] = slices.map((slice) => {
+		const eligible = quality.eligibleSliceKeys.has(sliceKey(slice));
 		const derived = Object.fromEntries(
-			SCENARIOS.map((scenario) => [scenario, sliceScenario(slice.approved_spend, slice.roas[scenario])]),
+			SCENARIOS.map((scenario) => [scenario, eligible
+				? sliceScenario(slice.approved_spend, slice.roas[scenario])
+				: { revenue: null, roas: null }]),
 		) as Record<Scenario, { revenue: number | null; roas: number | null }>;
 		return {
 			app_id: slice.app_id,
@@ -357,6 +417,45 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		roas: scenarioMetric(consolidatedRoas, "ratio", window),
 	};
 
+	const eligibleForecastSlices = forecastBySlice.filter((slice) => quality.eligibleSliceKeys.has(sliceKey(slice)));
+	const conclusionStatus: ForecastConclusion["status"] = quality.dataQuality.status === "complete"
+		? "available"
+		: quality.dataQuality.status === "partial"
+			? "available_with_limits"
+			: "unavailable";
+	const conclusionScope: ForecastConclusion["scope"] = quality.dataQuality.status === "complete"
+		? "portfolio"
+		: quality.dataQuality.status === "partial"
+			? "calculable_slices"
+			: "none";
+	const conclusionScenario = (metric: "spend" | "revenue"): Record<Scenario, number | null> => Object.fromEntries(
+		SCENARIOS.map((scenario) => {
+			if (conclusionStatus === "unavailable") return [scenario, null];
+			return [scenario, sumScenario(eligibleForecastSlices.map((slice) => slice.metrics[metric][scenario]))];
+		}),
+	) as Record<Scenario, number | null>;
+	const conclusionSpend = conclusionScenario("spend");
+	const conclusionRevenue = conclusionScenario("revenue");
+	const conclusionRoas = Object.fromEntries(SCENARIOS.map((scenario) => {
+		const spend = conclusionSpend[scenario];
+		const revenue = conclusionRevenue[scenario];
+		return [scenario, spend === null || revenue === null || spend === 0 ? null : revenue / spend];
+	})) as Record<Scenario, number | null>;
+	const conclusion: ForecastConclusion = {
+		status: conclusionStatus,
+		scope: conclusionScope,
+		metrics: {
+			spend: scenarioMetric(conclusionSpend, currency, window),
+			revenue: scenarioMetric(conclusionRevenue, currency, window),
+			roas: scenarioMetric(conclusionRoas, "ratio", window),
+		},
+		warning: quality.dataQuality.status === "complete"
+			? null
+			: quality.dataQuality.status === "partial"
+				? `结论仅覆盖可计算切片，占计划支出的 ${(quality.dataQuality.calculable_spend_pct * 100).toFixed(2)}%；未覆盖切片未参与收入和 ROAS 计算。`
+				: "没有可计算切片；已保留全部批准预算，但不提供收入或 ROAS 数值结论。",
+	};
+
 	// Portfolio-level series the model measured rather than derived — organic
 	// revenue and the like. They pass through untouched apart from the window,
 	// which is the artifact's to define, not the plan's.
@@ -379,9 +478,19 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		}
 	}
 
+	const artifactStatus = status === "blocked"
+		? "blocked"
+		: quality.dataQuality.status === "complete"
+			? status
+			: "complete_with_limits";
+	const qualityUnsupported = quality.dataQuality.issues.length === 0 ? [] : [{
+		metric: "revenue_roas_by_affected_slice",
+		reason: "slice_key_not_in_actuals",
+		affected_slice_count: quality.dataQuality.issue_count,
+	}];
 	const artifact = {
 		artifact_type: "approved_cycle_forecast",
-		status,
+		status: artifactStatus,
 		forecast_version: text(source.forecast_version, "plan.forecast_version"),
 		strategy_version: text(source.strategy_version, "plan.strategy_version"),
 		strategy_review_id: text(source.strategy_review_id, "plan.strategy_review_id"),
@@ -397,8 +506,10 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		forecast_by_slice: forecastBySlice,
 		consolidated_forecast: consolidated,
 		calibration_policy: source.calibration_policy,
-		unsupported_metrics: unsupported,
+		unsupported_metrics: [...unsupported, ...qualityUnsupported],
 		reconciliation_checks: source.reconciliation_checks,
+		data_quality: quality.dataQuality,
+		conclusion,
 		frozen_at: typeof source.frozen_at === "string" && source.frozen_at.trim()
 			? source.frozen_at
 			: (options.now?.() ?? new Date()).toISOString().replace(/\.\d{3}Z$/, "Z"),
@@ -409,7 +520,10 @@ export async function composeApprovedForecast(plan: unknown, options: ComposeOpt
 		diagnostics: {
 			slice_count: slices.length,
 			stopped_slice_count: slices.filter((slice) => slice.approved_spend === 0).length,
+			limited_slice_count: quality.limitedSliceKeys.size,
 			total_approved_spend: slices.reduce((total, slice) => total + slice.approved_spend, 0),
+			calculable_approved_spend: quality.dataQuality.calculable_spend,
+			calculable_spend_pct: quality.dataQuality.calculable_spend_pct,
 			validated_dimensions: true,
 			portfolio_placeholder_app_id: portfolioAppId,
 		},

package/extensions/fpa-artifacts/contracts.ts

@@ -35,6 +35,35 @@ export interface ForecastSlice {
 	metrics: Record<string, ScenarioMetric>;
 }
 
+export interface ForecastDataQualityIssue {
+	issue_id: string;
+	code: "slice_key_not_in_actuals";
+	severity: "warning";
+	slice: Pick<ForecastSlice, "app_id" | "store" | "channel_group">;
+	affected_metrics: string[];
+	disposition: "excluded_from_calculation";
+	evidence: string[];
+	remediation: string;
+	owner_role: "data_steward";
+}
+
+export interface ForecastDataQuality {
+	status: "complete" | "partial" | "unavailable";
+	planned_spend: number;
+	calculable_spend: number;
+	calculable_spend_pct: number;
+	excluded_spend: number;
+	issue_count: number;
+	issues: ForecastDataQualityIssue[];
+}
+
+export interface ForecastConclusion {
+	status: "available" | "available_with_limits" | "unavailable";
+	scope: "portfolio" | "calculable_slices" | "none";
+	metrics: Record<string, ScenarioMetric>;
+	warning: string | null;
+}
+
 export interface CalibrationPolicy {
 	stop_loss_roas_lt: number;
 	deviation_warning_abs_gte: number;
@@ -62,6 +91,8 @@ export interface ApprovedCycleForecastInput {
 	calibration_policy: CalibrationPolicy;
 	unsupported_metrics: unknown[];
 	reconciliation_checks: unknown[];
+	data_quality?: ForecastDataQuality;
+	conclusion?: ForecastConclusion;
 	frozen_at: string;
 }
 
@@ -235,6 +266,26 @@ function jsonArray(value: unknown, path: string): unknown[] {
 	return array(value, path).map((item, index) => jsonValue(item, `${path}[${index}]`));
 }
 
+function actionableUnsupportedMetrics(value: unknown, path: string): unknown[] {
+	const items = jsonArray(value, path);
+	for (const [index, raw] of items.entries()) {
+		const itemPath = `${path}[${index}]`;
+		const item = record(raw, itemPath);
+		string(item.metric, `${itemPath}.metric`);
+		const reason = string(item.reason, `${itemPath}.reason`);
+		if (reason === "slice_key_not_in_actuals") continue;
+		const scopes = strings(item.affected_scope, `${itemPath}.affected_scope`);
+		if (scopes.length === 0) throw new Error(`${itemPath}.affected_scope must not be empty.`);
+		const evidence = Array.isArray(item.evidence)
+			? strings(item.evidence, `${itemPath}.evidence`)
+			: [string(item.evidence, `${itemPath}.evidence`)];
+		if (evidence.length === 0) throw new Error(`${itemPath}.evidence must not be empty.`);
+		string(item.remediation, `${itemPath}.remediation`);
+		string(item.owner_role, `${itemPath}.owner_role`);
+	}
+	return items;
+}
+
 function strings(value: unknown, path: string): string[] {
 	return array(value, path).map((item, index) => string(item, `${path}[${index}]`));
 }
@@ -316,6 +367,70 @@ function scenarioMetrics(value: unknown, path: string): Record<string, ScenarioM
 	return Object.fromEntries(entries.map(([name, metric]) => [string(name, `${path} key`), scenarioMetric(metric, `${path}.${name}`)]));
 }
 
+function forecastDataQuality(value: unknown, path: string): ForecastDataQuality {
+	const source = record(value, path);
+	exactKeys(source, ["status", "planned_spend", "calculable_spend", "calculable_spend_pct", "excluded_spend", "issue_count", "issues"], path);
+	const issues = array(source.issues, `${path}.issues`).map((raw, index) => {
+		const issuePath = `${path}.issues[${index}]`;
+		const issue = record(raw, issuePath);
+		exactKeys(issue, ["issue_id", "code", "severity", "slice", "affected_metrics", "disposition", "evidence", "remediation", "owner_role"], issuePath);
+		const slice = record(issue.slice, `${issuePath}.slice`);
+		exactKeys(slice, ["app_id", "store", "channel_group"], `${issuePath}.slice`);
+		return {
+			issue_id: string(issue.issue_id, `${issuePath}.issue_id`),
+			code: enumValue(issue.code, ["slice_key_not_in_actuals"] as const, `${issuePath}.code`),
+			severity: enumValue(issue.severity, ["warning"] as const, `${issuePath}.severity`),
+			slice: {
+				app_id: string(slice.app_id, `${issuePath}.slice.app_id`),
+				store: string(slice.store, `${issuePath}.slice.store`),
+				channel_group: string(slice.channel_group, `${issuePath}.slice.channel_group`),
+			},
+			affected_metrics: strings(issue.affected_metrics, `${issuePath}.affected_metrics`),
+			disposition: enumValue(issue.disposition, ["excluded_from_calculation"] as const, `${issuePath}.disposition`),
+			evidence: strings(issue.evidence, `${issuePath}.evidence`),
+			remediation: string(issue.remediation, `${issuePath}.remediation`),
+			owner_role: enumValue(issue.owner_role, ["data_steward"] as const, `${issuePath}.owner_role`),
+		};
+	});
+	for (const [index, issue] of issues.entries()) {
+		const allowedAffectedMetrics = new Set(["actuals_comparison", "revenue", "roas", "execution"]);
+		const actualAffectedMetrics = new Set(issue.affected_metrics);
+		if (actualAffectedMetrics.size !== issue.affected_metrics.length
+			|| actualAffectedMetrics.size !== allowedAffectedMetrics.size
+			|| [...allowedAffectedMetrics].some((metric) => !actualAffectedMetrics.has(metric))) {
+			throw new Error(`${path}.issues[${index}].affected_metrics must contain actuals_comparison, revenue, roas, and execution exactly once.`);
+		}
+	}
+	const plannedSpend = nonNegative(source.planned_spend, `${path}.planned_spend`) as number;
+	const calculableSpend = nonNegative(source.calculable_spend, `${path}.calculable_spend`) as number;
+	const excludedSpend = nonNegative(source.excluded_spend, `${path}.excluded_spend`) as number;
+	const calculableSpendPct = nonNegative(source.calculable_spend_pct, `${path}.calculable_spend_pct`) as number;
+	const issueCount = nonNegative(source.issue_count, `${path}.issue_count`) as number;
+	if (!Number.isInteger(issueCount) || issueCount !== issues.length) throw new Error(`${path}.issue_count must equal issues.length.`);
+	if (calculableSpendPct > 1) throw new Error(`${path}.calculable_spend_pct cannot exceed 1.`);
+	if (Math.abs(plannedSpend - calculableSpend - excludedSpend) > 0.01) throw new Error(`${path} spend coverage does not reconcile.`);
+	return {
+		status: enumValue(source.status, ["complete", "partial", "unavailable"] as const, `${path}.status`),
+		planned_spend: plannedSpend,
+		calculable_spend: calculableSpend,
+		calculable_spend_pct: calculableSpendPct,
+		excluded_spend: excludedSpend,
+		issue_count: issueCount,
+		issues,
+	};
+}
+
+function forecastConclusion(value: unknown, path: string): ForecastConclusion {
+	const source = record(value, path);
+	exactKeys(source, ["status", "scope", "metrics", "warning"], path);
+	return {
+		status: enumValue(source.status, ["available", "available_with_limits", "unavailable"] as const, `${path}.status`),
+		scope: enumValue(source.scope, ["portfolio", "calculable_slices", "none"] as const, `${path}.scope`),
+		metrics: scenarioMetrics(source.metrics, `${path}.metrics`),
+		warning: source.warning === null ? null : string(source.warning, `${path}.warning`),
+	};
+}
+
 export function sliceKey(value: { app_id: string; store: string; channel_group: string }): string {
 	return `${value.app_id}\u0000${value.store}\u0000${value.channel_group}`;
 }
@@ -366,7 +481,7 @@ function validateFinancialMetricSemantics(
 }
 
 function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycleForecastInput {
-	exactKeys(source, TOP_LEVEL_KEYS.approved_cycle_forecast, "artifact");
+	requiredAndOptionalKeys(source, TOP_LEVEL_KEYS.approved_cycle_forecast, ["data_quality", "conclusion"], "artifact");
 	const targetPeriod = period(source.target_period, "artifact.target_period");
 	const allocations = array(source.approved_allocation, "artifact.approved_allocation").map((value, index) => {
 		const path = `artifact.approved_allocation[${index}]`;
@@ -460,6 +575,85 @@ function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycl
 	}
 
 	const status = enumValue(source.status, ["complete", "complete_with_limits", "blocked"] as const, "artifact.status");
+	const unsupportedMetrics = actionableUnsupportedMetrics(source.unsupported_metrics, "artifact.unsupported_metrics");
+	if (status === "complete" && unsupportedMetrics.length > 0) {
+		throw new Error("A complete forecast cannot carry unsupported_metrics; use complete_with_limits.");
+	}
+	if (status === "complete_with_limits" && unsupportedMetrics.length === 0) {
+		throw new Error("A complete_with_limits forecast must describe at least one unsupported metric or data limit.");
+	}
+	const dataQuality = source.data_quality === undefined ? undefined : forecastDataQuality(source.data_quality, "artifact.data_quality");
+	const conclusion = source.conclusion === undefined ? undefined : forecastConclusion(source.conclusion, "artifact.conclusion");
+	if ((dataQuality === undefined) !== (conclusion === undefined)) {
+		throw new Error("artifact.data_quality and artifact.conclusion must be supplied together.");
+	}
+	const declaresSliceKeyLimit = unsupportedMetrics.some((item) => item !== null
+		&& typeof item === "object"
+		&& !Array.isArray(item)
+		&& (item as Record<string, unknown>).reason === "slice_key_not_in_actuals");
+	if (declaresSliceKeyLimit && (!dataQuality || dataQuality.issues.length === 0)) {
+		throw new Error("A slice_key_not_in_actuals limit requires data_quality issues and a partial conclusion.");
+	}
+	if (status === "complete" && dataQuality && dataQuality.status !== "complete") {
+		throw new Error("A complete forecast cannot carry partial or unavailable data quality.");
+	}
+	if (dataQuality && conclusion) {
+		const issueKeys = new Set<string>();
+		for (const issue of dataQuality.issues) {
+			const key = sliceKey(issue.slice);
+			if (!allocationKeys.has(key)) throw new Error(`artifact.data_quality issue slice is not in approved_allocation: ${key.replaceAll("\u0000", " / ")}.`);
+			if (issueKeys.has(key)) throw new Error(`artifact.data_quality contains duplicate issue slice ${key.replaceAll("\u0000", " / ")}.`);
+			issueKeys.add(key);
+			const affectedForecast = forecastSlices.find((slice) => sliceKey(slice) === key) as ForecastSlice;
+			for (const scenario of SCENARIOS) {
+				if (affectedForecast.metrics.revenue[scenario] !== null || affectedForecast.metrics.roas?.[scenario] !== null) {
+					throw new Error(`artifact.data_quality affected slice ${key.replaceAll("\u0000", " / ")} must keep revenue and ROAS null.`);
+				}
+			}
+		}
+		const expectedExcludedSpend = allocations
+			.filter((allocation) => issueKeys.has(sliceKey(allocation)))
+			.reduce((total, allocation) => total + allocation.approved_spend, 0);
+		const expectedCalculableSpend = allocationTotal - expectedExcludedSpend;
+		reconcileNumber(dataQuality.planned_spend, allocationTotal, "artifact.data_quality.planned_spend vs approved allocation");
+		reconcileNumber(dataQuality.excluded_spend, expectedExcludedSpend, "artifact.data_quality.excluded_spend vs affected allocation");
+		reconcileNumber(dataQuality.calculable_spend, expectedCalculableSpend, "artifact.data_quality.calculable_spend vs eligible allocation");
+		const expectedPct = allocationTotal === 0 ? (issueKeys.size === 0 ? 1 : 0) : expectedCalculableSpend / allocationTotal;
+		reconcileNumber(dataQuality.calculable_spend_pct, expectedPct, "artifact.data_quality.calculable_spend_pct coverage");
+		const expectedQualityStatus: ForecastDataQuality["status"] = issueKeys.size === 0
+			? "complete"
+			: expectedCalculableSpend === 0
+				? "unavailable"
+				: "partial";
+		if (dataQuality.status !== expectedQualityStatus) throw new Error(`artifact.data_quality.status must be ${expectedQualityStatus}.`);
+		const expectedConclusionStatus: ForecastConclusion["status"] = expectedQualityStatus === "complete"
+			? "available"
+			: expectedQualityStatus === "partial"
+				? "available_with_limits"
+				: "unavailable";
+		const expectedConclusionScope: ForecastConclusion["scope"] = expectedQualityStatus === "complete"
+			? "portfolio"
+			: expectedQualityStatus === "partial"
+				? "calculable_slices"
+				: "none";
+		if (conclusion.status !== expectedConclusionStatus || conclusion.scope !== expectedConclusionScope) {
+			throw new Error(`artifact.conclusion must use ${expectedConclusionStatus} / ${expectedConclusionScope} for its data coverage.`);
+		}
+		validateFinancialMetricSemantics(conclusion.metrics, reportingCurrency, expectedWindow, "artifact.conclusion.metrics");
+		reconcileRoas(conclusion.metrics, "artifact.conclusion.metrics");
+		const eligibleForecastSlices = forecastSlices.filter((slice) => !issueKeys.has(sliceKey(slice)));
+		for (const metricName of ["spend", "revenue"] as const) {
+			for (const scenario of SCENARIOS) {
+				const values = eligibleForecastSlices.map((slice) => slice.metrics[metricName][scenario]);
+				const expected = expectedQualityStatus === "unavailable"
+					? null
+					: values.every((value) => value !== null)
+						? values.reduce<number>((total, value) => total + (value as number), 0)
+						: null;
+				reconcileNumber(conclusion.metrics[metricName][scenario], expected, `artifact.conclusion.metrics.${metricName}.${scenario}`);
+			}
+		}
+	}
 	const approvalConditionsSatisfied = boolean(source.approval_conditions_satisfied, "artifact.approval_conditions_satisfied");
 	if (status !== "blocked" && !approvalConditionsSatisfied) {
 		throw new Error("A non-blocked approved forecast requires all approval conditions to be satisfied.");
@@ -482,8 +676,10 @@ function validateApprovedForecast(source: Record<string, unknown>): ApprovedCycl
 		forecast_by_slice: forecastSlices,
 		consolidated_forecast: consolidated,
 		calibration_policy: policy,
-		unsupported_metrics: jsonArray(source.unsupported_metrics, "artifact.unsupported_metrics"),
+		unsupported_metrics: unsupportedMetrics,
 		reconciliation_checks: jsonArray(source.reconciliation_checks, "artifact.reconciliation_checks"),
+		...(dataQuality ? { data_quality: dataQuality } : {}),
+		...(conclusion ? { conclusion } : {}),
 		frozen_at: isoTimestamp(source.frozen_at, "artifact.frozen_at"),
 	};
 }
@@ -617,9 +813,13 @@ export function validateExecutionAgainstForecast(
 	if (execution.strategy_version !== forecast.strategy_version) throw new Error("Execution receipt strategy_version does not match the approved forecast.");
 	if (execution.human_approval_id !== forecast.human_approval_id) throw new Error("Execution receipt human_approval_id does not match the approved forecast.");
 	const allocationByKey = new Map(forecast.approved_allocation.map((allocation) => [sliceKey(allocation), allocation]));
+	const isolatedExecutionKeys = new Set((forecast.data_quality?.issues ?? []).map((issue) => sliceKey(issue.slice)));
 	const executionKeys = new Set<string>();
 	for (const slice of execution.slices) {
 		const key = sliceKey(slice);
+		if (isolatedExecutionKeys.has(key)) {
+			throw new Error(`Execution receipt contains a slice isolated by forecast data quality: ${key.replaceAll("\u0000", " / ")}.`);
+		}
 		executionKeys.add(key);
 		const allocation = allocationByKey.get(key);
 		if (!allocation) throw new Error(`Execution receipt contains an unapproved slice ${key.replaceAll("\u0000", " / ")}.`);

package/extensions/fpa-artifacts/forecast-quality.ts

@@ -0,0 +1,138 @@
+import {
+	sliceKey,
+	type ForecastDataQuality,
+	type ForecastDataQualityIssue,
+} from "./contracts.ts";
+
+export interface ForecastQualitySlice {
+	app_id: string;
+	store: string;
+	channel_group: string;
+	approved_spend: number;
+}
+
+export interface ForecastDimensionSnapshot {
+	app_code: Set<string>;
+	platform: Set<string>;
+	media_source: Set<string>;
+	/** Canonical app_code / platform / media_source combinations observed in ua_spend. */
+	tuples?: Set<string>;
+}
+
+export interface ForecastQualityAssessment {
+	portfolioAppId: string | null;
+	eligibleSliceKeys: Set<string>;
+	limitedSliceKeys: Set<string>;
+	dataQuality: ForecastDataQuality;
+}
+
+function sample(values: Set<string>, limit = 8): string {
+	const list = [...values].sort();
+	return list.length <= limit ? list.join(", ") : `${list.slice(0, limit).join(", ")}, … (${list.length} total)`;
+}
+
+function issueForSlice(
+	slice: ForecastQualitySlice,
+	index: number,
+	evidence: string[],
+): ForecastDataQualityIssue {
+	return {
+		issue_id: `DQ-SLICE-${String(index + 1).padStart(3, "0")}`,
+		code: "slice_key_not_in_actuals",
+		severity: "warning",
+		slice: {
+			app_id: slice.app_id,
+			store: slice.store,
+			channel_group: slice.channel_group,
+		},
+		affected_metrics: ["actuals_comparison", "revenue", "roas", "execution"],
+		disposition: "excluded_from_calculation",
+		evidence,
+		remediation:
+			"请由数据工作人员修正 ua_spend 的 app_code/platform/media_source 映射，或更新计划切片为数据集中真实存在的组合。",
+		owner_role: "data_steward",
+	};
+}
+
+/**
+ * Classify slice identity problems as data-quality limits, not governance
+ * failures. The allocation remains intact; callers use eligibleSliceKeys to
+ * decide which derived metrics may be calculated and which slices may execute.
+ */
+export function assessForecastQuality(
+	slices: ForecastQualitySlice[],
+	values: ForecastDimensionSnapshot,
+): ForecastQualityAssessment {
+	const appIds = new Set(slices.map((slice) => slice.app_id));
+	const collapsed = appIds.size === 1 ? [...appIds][0] : null;
+	const portfolioAppId = collapsed !== null && !values.app_code.has(collapsed) ? collapsed : null;
+	const eligibleSliceKeys = new Set<string>();
+	const limitedSliceKeys = new Set<string>();
+	const issues: ForecastDataQualityIssue[] = [];
+
+	for (const [index, slice] of slices.entries()) {
+		const evidence: string[] = [];
+		if (portfolioAppId === null && !values.app_code.has(slice.app_id)) {
+			evidence.push(`app_id ${JSON.stringify(slice.app_id)} is not a ua_spend.app_code value. Valid values: ${sample(values.app_code)}.`);
+		}
+		if (!values.platform.has(slice.store)) {
+			evidence.push(`store ${JSON.stringify(slice.store)} is not a ua_spend.platform value. Valid values: ${sample(values.platform)}.`);
+		}
+		if (!values.media_source.has(slice.channel_group)) {
+			evidence.push(`channel_group ${JSON.stringify(slice.channel_group)} is not a ua_spend.media_source value. Valid values: ${sample(values.media_source)}.`);
+		}
+		if (
+			evidence.length === 0
+			&& portfolioAppId === null
+			&& values.tuples
+			&& !values.tuples.has(sliceKey(slice))
+		) {
+			evidence.push(
+				`The app_code/platform/media_source combination ${slice.app_id} / ${slice.store} / ${slice.channel_group} does not occur in ua_spend.`,
+			);
+		}
+		if (
+			evidence.length === 0
+			&& portfolioAppId !== null
+			&& values.tuples
+			&& ![...values.tuples].some((tuple) => tuple.endsWith(`\u0000${slice.store}\u0000${slice.channel_group}`))
+		) {
+			evidence.push(
+				`The platform/media_source combination ${slice.store} / ${slice.channel_group} does not occur in ua_spend portfolio data.`,
+			);
+		}
+
+		const key = sliceKey(slice);
+		if (evidence.length === 0) eligibleSliceKeys.add(key);
+		else {
+			limitedSliceKeys.add(key);
+			issues.push(issueForSlice(slice, index, evidence));
+		}
+	}
+
+	const plannedSpend = slices.reduce((total, slice) => total + slice.approved_spend, 0);
+	const calculableSpend = slices
+		.filter((slice) => eligibleSliceKeys.has(sliceKey(slice)))
+		.reduce((total, slice) => total + slice.approved_spend, 0);
+	const excludedSpend = plannedSpend - calculableSpend;
+	const status = issues.length === 0
+		? "complete"
+		: calculableSpend === 0
+			? "unavailable"
+			: "partial";
+
+	return {
+		portfolioAppId,
+		eligibleSliceKeys,
+		limitedSliceKeys,
+		dataQuality: {
+			status,
+			planned_spend: plannedSpend,
+			calculable_spend: calculableSpend,
+			calculable_spend_pct: plannedSpend === 0 ? (issues.length === 0 ? 1 : 0) : calculableSpend / plannedSpend,
+			excluded_spend: excludedSpend,
+			issue_count: issues.length,
+			issues,
+		},
+	};
+}

package/extensions/fpa-artifacts/index.ts

@@ -142,7 +142,8 @@ export default function fpaArtifactsExtension(pi: ExtensionAPI): void {
 		label: "Compose Approved Forecast",
 		description:
 			"Derive a complete, self-consistent approved_cycle_forecast from a compact plan file holding only the approved allocation and its per-slice ROAS assumptions. " +
-			"Computes every scenario metric, the consolidated roll-up, units, windows, and frozen_at, and checks the plan's slice keys against the dimension values ua_spend actually uses. " +
+			"Computes every scenario metric, the consolidated roll-up, units, windows, and frozen_at, and checks plan slice keys against the exact dimension combinations ua_spend actually uses. " +
+			"Data-quality mismatches are isolated into complete_with_limits with coverage and repair diagnostics; approved allocation is never dropped or renormalized. " +
 			"Returns the artifact for fpa_artifact_commit to freeze; writes nothing.",
 		promptSnippet: "Derive a complete approved forecast from a compact plan",
 		promptGuidelines: [

package/extensions/fpa-dashboard/coordinator.ts

@@ -717,8 +717,8 @@ async function defaultWorker(event: DashboardRefreshEvent, projectRoot: string,
 		...(event.forward_forecast_refs ? { forwardForecastRefs: event.forward_forecast_refs } : {}),
 	}, signal);
 	if (result.sliceKeyMismatch) throw new Error(`Dashboard publish refused. ${result.sliceKeyMismatch}`);
-	if (result.forecast.status !== "complete" || !result.forecast.approval_conditions_satisfied) {
-		throw new Error("Dashboard publish requires a complete approved forecast with all approval conditions satisfied.");
+	if (result.forecast.status === "blocked" || !result.forecast.approval_conditions_satisfied) {
+		throw new Error("Dashboard publish requires a completed approved forecast with all approval conditions satisfied.");
 	}
 	const generationId = dashboardBuildFingerprint(result.build, result.projector);
 	if (event.desired_generation_id && generationId !== event.desired_generation_id) {

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

@@ -218,8 +218,8 @@ export function projectCycleOperatingProjection(input: CycleOperatingProjectionI
 		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.");
+	if (next && (next.status === "blocked" || !next.approval_conditions_satisfied)) {
+		throw new Error("next_forecast must be completed with approval conditions satisfied.");
 	}
 
 	const forecastSpend = scenario(current.consolidated_forecast.spend, "current_forecast.consolidated_forecast.spend");
@@ -253,9 +253,10 @@ export function projectCycleOperatingProjection(input: CycleOperatingProjectionI
 	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
+	const nextHasLimits = !!next && (next.status === "complete_with_limits"
+		|| 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 (nextHasLimits) warnings.push("The next-cycle forecast is approved with limits; unsupported expectations remain null and documented data issues still require remediation.");
 	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 {

package/extensions/fpa-dashboard/forward-outlook.ts

@@ -26,7 +26,7 @@ export interface ForwardOutlookProjection {
 function approvedForecast(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.`);
-	if (artifact.status !== "complete" || !artifact.approval_conditions_satisfied) throw new Error(`${path} must be complete and approved.`);
+	if (artifact.status === "blocked" || !artifact.approval_conditions_satisfied) throw new Error(`${path} must be completed and approved.`);
 	return artifact;
 }
 
@@ -46,6 +46,7 @@ export function projectForwardOutlook(input: {
 	const current = approvedForecast(input.current_forecast, "current_forecast");
 	if (!Array.isArray(input.forward_forecasts) || input.forward_forecasts.length > 6) throw new Error("forward_forecasts must contain at most six approved forecasts.");
 	const months: ForwardOutlookProjection["months"] = [];
+	const warnings: string[] = [];
 	let expectedStart = current.target_period.end_exclusive;
 	for (const [index, item] of input.forward_forecasts.entries()) {
 		const forecast = approvedForecast(item.forecast, `forward_forecasts[${index}].forecast`);
@@ -63,8 +64,10 @@ export function projectForwardOutlook(input: {
 			expected_revenue: values(forecast.consolidated_forecast.revenue, `forward_forecasts[${index}].revenue`),
 			expected_roas: values(forecast.consolidated_forecast.roas, `forward_forecasts[${index}].roas`),
 		});
+		if (forecast.status === "complete_with_limits") {
+			warnings.push(`${forecast.forecast_version} has data limits; unsupported expectations remain null.`);
+		}
 	}
-	const warnings: string[] = [];
 	if (months.length < 6) warnings.push(`Only ${months.length} of 6 forward monthly forecasts are approved and linked.`);
 	if (months.some((month) => month.expected_revenue.base === null || month.expected_spend.base === null || month.expected_roas.base === null)) {
 		warnings.push("At least one forward month has unsupported base metrics; its expectation remains unavailable.");

package/extensions/fpa-dashboard/index.ts

@@ -384,8 +384,8 @@ export default function fpaDashboardExtension(pi: ExtensionAPI): void {
 			}
 
 			if (sliceKeyMismatch) throw new Error(`Dashboard publish refused. ${sliceKeyMismatch}`);
-			if (forecast.status !== "complete" || !forecast.approval_conditions_satisfied) {
-				throw new Error("Dashboard publish requires a complete approved forecast with all approval conditions satisfied.");
+			if (forecast.status === "blocked" || !forecast.approval_conditions_satisfied) {
+				throw new Error("Dashboard publish requires a completed approved forecast with all approval conditions satisfied.");
 			}
 			if (!params.expected_preview_fingerprint) throw new Error("Publish requires expected_preview_fingerprint from a preceding preview.");
 			if (params.expected_preview_fingerprint !== previewFingerprint) {

package/extensions/fpa-dashboard/projector.ts

@@ -226,10 +226,11 @@ function joinSlices(
 	const forecastByKey = new Map(forecast.forecast_by_slice.map((slice) => [sliceKey(slice), slice]));
 	const actualByKey = new Map(actuals.slices.map((slice) => [sliceKey(slice), slice]));
 	const executionByKey = new Map((execution?.slices ?? []).map((slice) => [sliceKey(slice), slice]));
+	const isolatedKeys = new Set((forecast.data_quality?.issues ?? []).map((issue) => sliceKey(issue.slice)));
 	return forecast.approved_allocation.map((allocation) => {
 		const forecastSlice = forecastByKey.get(sliceKey(allocation));
 		if (!forecastSlice) throw new Error(`Forecast slice is missing for ${allocation.app_id} / ${allocation.store} / ${allocation.channel_group}.`);
-		const actual = actualByKey.get(sliceKey(allocation)) ?? null;
+		const actual = isolatedKeys.has(sliceKey(allocation)) ? null : actualByKey.get(sliceKey(allocation)) ?? null;
 		const forecastRoas = safeDiv(
 			forecastSlice.metrics.revenue?.base ?? null,
 			forecastSlice.metrics.spend?.base ?? null,
@@ -390,8 +391,64 @@ export function projectDashboard(input: ProjectionInput): DashboardBuild {
 	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 quality = forecast.data_quality;
+	const qualityWidgets: DashboardWidget[] = !quality || quality.status === "complete" ? [] : [
+		{
+			id: "forecast-data-coverage",
+			type: "stat",
+			span: "full",
+			dataset: "forecast-data-coverage.json",
+			data: {
+				label: "预测数据覆盖率",
+				value: `${(quality.calculable_spend_pct * 100).toFixed(2)}%`,
+				description: `可计算预算 ${formatCurrency(quality.calculable_spend, forecast.reporting_currency, locale)} / 计划预算 ${formatCurrency(quality.planned_spend, forecast.reporting_currency, locale)}`,
+				footnote: forecast.conclusion?.warning ?? "异常切片未参与收入与 ROAS 计算，批准预算未被删除或重分配。",
+				progress: { fraction: quality.calculable_spend_pct, label: `${quality.issue_count} 个待修复切片`, tone: "warning" },
+			},
+		},
+		{
+			id: "forecast-data-issues",
+			type: "table",
+			span: "full",
+			dataset: "forecast-data-issues.json",
+			data: {
+				label: "数据待修复项",
+				description: "问题切片保持在批准计划中，但不参与预测计算、Actuals 比较或执行。",
+				columns: [
+					{ key: "slice", label: "App / 商店 / 渠道" },
+					{ key: "problem", label: "数据问题" },
+					{ key: "remediation", label: "修复建议" },
+					{ key: "owner", label: "负责人" },
+				],
+				rows: quality.issues.map((issue) => ({
+					slice: `${issue.slice.app_id} · ${issue.slice.store} · ${issue.slice.channel_group}`,
+					problem: issue.evidence.join("\n"),
+					remediation: issue.remediation,
+					owner: issue.owner_role,
+				})),
+			},
+		},
+	];
+	const generalLimits = forecast.unsupported_metrics.filter((item) => {
+		return !(item && typeof item === "object" && !Array.isArray(item)
+			&& (item as Record<string, unknown>).reason === "slice_key_not_in_actuals");
+	});
+	const limitWidgets: DashboardWidget[] = generalLimits.length === 0 ? [] : [{
+		id: "forecast-limitations",
+		type: "table",
+		span: "full",
+		dataset: "forecast-limitations.json",
+		data: {
+			label: "预测限制提醒",
+			description: "以下上游数据或指标限制未阻断预测；不支持的值保持为空，待数据工作人员修复。",
+			columns: [{ key: "item", label: "限制与修复信息" }],
+			rows: generalLimits.map((item) => ({ item: typeof item === "string" ? item : JSON.stringify(item) })),
+		},
+	}];
 
 	const widgets: DashboardWidget[] = [
+		...qualityWidgets,
+		...limitWidgets,
 		{
 			id: "revenue-vs-forecast",
 			type: "stat",

package/extensions/fpa-dashboard/service.ts

@@ -173,7 +173,18 @@ export async function buildDashboardProjection(
 	if (actuals.query_receipts.some((receipt) => receipt.dataset === "ua_spend.slices.discovery" && receipt.row_count >= 1000)) build.warnings.push("Unplanned-slice discovery reached its 1000-row safety limit; approved slices and like-for-like totals remain complete, but additional warnings may be omitted.");
 	if (actuals.data_as_of === "unavailable") build.warnings.push("No current-period UA Actuals are available.");
 
-	const sliceKeyMismatch = detectSliceKeyMismatch(forecast.approved_allocation, actuals);
-	if (sliceKeyMismatch) build.warnings.push(sliceKeyMismatch);
+	const detectedSliceKeyMismatch = detectSliceKeyMismatch(forecast.approved_allocation, actuals);
+	const qualityIssueKeys = new Set((forecast.data_quality?.issues ?? []).map((issue) => sliceKey(issue.slice)));
+	const qualityAcknowledgesMismatch = forecast.data_quality !== undefined
+		&& forecast.data_quality.status !== "complete"
+		&& forecast.approved_allocation
+			.filter((allocation) => allocation.approved_spend > 0)
+			.every((allocation) => qualityIssueKeys.has(sliceKey(allocation)));
+	const sliceKeyMismatch = detectedSliceKeyMismatch && !qualityAcknowledgesMismatch ? detectedSliceKeyMismatch : null;
+	if (detectedSliceKeyMismatch) {
+		build.warnings.push(qualityAcknowledgesMismatch
+			? `${detectedSliceKeyMismatch} The affected slices are already isolated by forecast data quality, so dashboard publication continues with limits.`
+			: detectedSliceKeyMismatch);
+	}
 	return { build, forecast, forecastRead, executionRead, actuals, sliceKeyMismatch, ...provenance };
 }

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

@@ -245,6 +245,61 @@ export function projectStrategyModule(
 
 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]));
+	const quality = forecast.data_quality;
+	const summary = quality?.status !== "complete" && forecast.conclusion
+		? forecast.conclusion.metrics
+		: forecast.consolidated_forecast;
+	const qualityWidgets: DashboardModuleBuild["widgets"] = !quality || quality.status === "complete" ? [] : [{
+		id: "forecast-data-coverage",
+		type: "stat",
+		span: "full",
+		dataset: "forecast-data-coverage.json",
+		data: {
+			label: "预测数据覆盖率",
+			value: `${(quality.calculable_spend_pct * 100).toFixed(2)}%`,
+			description: `可计算预算 ${quality.calculable_spend.toFixed(2)} / 计划预算 ${quality.planned_spend.toFixed(2)}；异常切片 ${quality.issue_count} 个。`,
+			footnote: forecast.conclusion?.warning ?? "异常切片未参与收入与 ROAS 计算，批准预算未被删除或重分配。",
+			progress: { fraction: quality.calculable_spend_pct, label: `${(quality.calculable_spend_pct * 100).toFixed(2)}%`, tone: "warning" },
+		},
+	}];
+	const issueWidgets: DashboardModuleBuild["widgets"] = !quality || quality.issues.length === 0 ? [] : [{
+		id: "forecast-data-issues",
+		type: "table",
+		span: "full",
+		dataset: "forecast-data-issues.json",
+		data: {
+			label: "数据待修复项",
+			description: "这些问题不阻断预测结论，但对应切片不参与计算且不可执行。",
+			columns: [
+				{ key: "slice", label: "App / 商店 / 渠道" },
+				{ key: "problem", label: "问题" },
+				{ key: "remediation", label: "修复建议" },
+				{ key: "owner", label: "负责人" },
+			],
+			rows: quality.issues.map((issue) => ({
+				slice: `${issue.slice.app_id} · ${issue.slice.store} · ${issue.slice.channel_group}`,
+				problem: issue.evidence.join("\n"),
+				remediation: issue.remediation,
+				owner: issue.owner_role,
+			})),
+		},
+	}];
+	const generalLimits = forecast.unsupported_metrics.filter((item) => {
+		return !(item && typeof item === "object" && !Array.isArray(item)
+			&& (item as Record<string, unknown>).reason === "slice_key_not_in_actuals");
+	});
+	const limitWidgets: DashboardModuleBuild["widgets"] = generalLimits.length === 0 ? [] : [{
+		id: "forecast-limitations",
+		type: "table",
+		span: "full",
+		dataset: "forecast-limitations.json",
+		data: {
+			label: "预测限制提醒",
+			description: "以下上游数据或指标限制未阻断预测；不支持的值保持为空，待数据工作人员修复。",
+			columns: [{ key: "item", label: "限制与修复信息" }],
+			rows: generalLimits.map((item) => ({ item: typeof item === "string" ? item : JSON.stringify(item) })),
+		},
+	}];
 	return {
 		id: "next-forecast",
 		title: "下周期数据预测",
@@ -259,6 +314,7 @@ export function projectForecastModule(forecast: ApprovedCycleForecast, artifactR
 			data_as_of: forecast.data_as_of,
 		},
 		widgets: [
+			...qualityWidgets,
 			{
 				id: "forecast-summary",
 				type: "table",
@@ -267,13 +323,13 @@ export function projectForecastModule(forecast: ApprovedCycleForecast, artifactR
 				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]) => ({
+					rows: Object.entries(summary).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}`,
+					description: `${forecast.target_period.start_inclusive} → ${forecast.target_period.end_exclusive}${quality?.status !== "complete" ? " · 部分口径" : ""}`,
 				},
 			},
 			{
@@ -299,6 +355,8 @@ export function projectForecastModule(forecast: ApprovedCycleForecast, artifactR
 					}),
 				},
 			},
+			...issueWidgets,
+			...limitWidgets,
 		],
 	};
 }

package/graphs/fpa-forecast-freeze.json

@@ -33,7 +33,7 @@
       "label": "报告预测阻断",
       "outputKey": "forecast_blocked",
       "parseJson": true,
-      "prompt": "核验结果：{{data.confirmed_strategy}}\n\n只输出 JSON：{\"kind\":\"fpa.graph-handoff\",\"status\":\"blocked\",\"graph\":\"fpa-forecast-freeze\",\"blockers\":[],\"required_action\":\"由原主会话提交与当前 handoff 精确匹配的策略确认\"}",
+      "prompt": "策略核验结果：{{data.confirmed_strategy}}\n预测计划修复结果：{{data.repair_forecast_plan}}\n\n汇总实际阻断原因。只输出 JSON：{\"kind\":\"fpa.graph-handoff\",\"status\":\"blocked\",\"graph\":\"fpa-forecast-freeze\",\"blockers\":[],\"required_action\":\"需要主会话处理的治理或策略动作\"}",
       "systemPrompt": "用中文简洁报告预测阻断，只输出约定 JSON。",
       "type": "prompt"
     },
@@ -43,7 +43,7 @@
       "label": "正式预测决策计划",
       "next": "compose_forecast",
       "outputKey": "draft_forecast",
-      "prompt": "操作备注：{{goal}}\n\n已核验策略与决策：{{data.confirmed_strategy}}\n\n读取 reviewed_strategy_handoff、strategy_proposal、strategy_review 和精确 strategy_decision，按 fpa-forecast-approved-strategy 写 artifacts/forecast_plan.json。不得重新优化策略；业务分配、范围、假设或审核条件需变化时必须 blocked 并回到策略规划。只写 allocation 与每个切片的 ROAS assumptions；revenue、汇总、单位和 frozen_at 由下游 fpa_forecast_compose 推导。切片键必须使用 ua_spend 的 app_code/platform/media_source 合法值。不得调用任何 fpa_dashboard_* 工具。",
+      "prompt": "操作备注：{{goal}}\n\n已核验策略与决策：{{data.confirmed_strategy}}\n\n读取 reviewed_strategy_handoff、strategy_proposal、strategy_review 和精确 strategy_decision，按 fpa-forecast-approved-strategy 写 artifacts/forecast_plan.json。不得重新优化策略；业务分配、范围、假设或审核条件需变化时必须 blocked 并回到策略规划。只写 allocation 与每个切片的 ROAS assumptions；revenue、汇总、单位和 frozen_at 由下游 fpa_forecast_compose 推导。优先使用 ua_spend 的 app_code/platform/media_source 真实组合；若已确认分配中的部分切片与当前上游映射不一致，不得擅自删除、置零、重分配或伪造映射，保留原切片交给 compose 自动产出 complete_with_limits、覆盖率和数据修复项。不得调用任何 fpa_dashboard_* 工具。",
       "skills": ["fpa-apply-core-rules", "fpa-forecast-approved-strategy"],
       "systemPrompt": "你是 FP&A 正式预测 Agent。只按已确认策略写预测计划，不请求审批、不发布仪表盘、不手算派生值。",
       "tools": ["read", "write", "fpa_calc"],
@@ -63,14 +63,26 @@
       "agentName": "repair_forecast_plan",
       "id": "repair_forecast_plan",
       "label": "定点修正预测计划",
-      "next": "compose_forecast",
+      "next": "route_repair_forecast_plan",
       "outputKey": "repair_forecast_plan",
-      "prompt": "合成失败：{{data.__graphError}}\n\n读取 artifacts/forecast_plan.json、planning_brief 和 reviewed_strategy_handoff，只定点修正格式、合法切片键或 forecast plan 契约问题。不得改变已确认策略的业务分配、范围、假设或条件；若错误要求此类变化，报告 blocked。不得调用任何 fpa_dashboard_* 工具。",
+      "parseJson": true,
+      "prompt": "合成失败：{{data.__graphError}}\n\n读取 artifacts/forecast_plan.json、planning_brief 和 reviewed_strategy_handoff，只定点修正格式或 forecast plan 契约问题。不得通过删除、置零、重分配或伪造映射来修正数据质量问题；这类问题应由 compose 降级为 complete_with_limits。不得改变已确认策略的业务分配、范围、假设或条件；若错误要求此类变化，返回 blocked。不得调用任何 fpa_dashboard_* 工具。只输出 JSON：{\"status\":\"repaired|blocked\",\"changes\":[],\"blockers\":[]}",
       "skills": ["fpa-forecast-approved-strategy"],
       "systemPrompt": "你是预测计划修复 Agent，只按确定性合成报错做最小修正。",
       "tools": ["read", "write", "edit"],
       "type": "subagent"
     },
+    {
+      "cases": [
+        { "equals": "repaired", "label": "已修正契约", "to": "compose_forecast" },
+        { "equals": "blocked", "label": "需要治理处理", "to": "report_blocked" }
+      ],
+      "default": { "label": "其他结果", "to": "report_blocked" },
+      "id": "route_repair_forecast_plan",
+      "label": "判断能否重新合成",
+      "path": "data.repair_forecast_plan.status",
+      "type": "router"
+    },
     {
       "args": {
         "artifact": "{{data.compose_forecast.details.artifact}}",
@@ -91,5 +103,5 @@
   "schemaVersion": 1,
   "start": "load_confirmed_strategy",
   "transitionLabels": { "default": "其他情况", "error": "失败", "next": "继续" },
-  "version": "2.1.0"
+  "version": "2.2.0"
 }

package/package.json

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

package/skills/fpa-diagnose-actuals/references/artifact-contract.md

@@ -31,6 +31,8 @@ checks:
     affected_scope: []
     evidence: string
     remediation: string
+    owner_role: data_steward
+    disposition: excluded_from_calculation | warning_only | blocking
 blocking_issues: []
 non_blocking_limits: []
 ```

package/skills/fpa-forecast-approved-strategy/SKILL.md

@@ -84,11 +84,23 @@ tool. `complete_with_limits` remains publishable when its limitations are
 explicit, while `blocked` is not. Do not hide a real defect to get through the
 gate.
 
+Upstream identity or coverage defects are non-blocking data limits. Preserve
+the full approved allocation, leave affected revenue and ROAS values `NULL`,
+and let `fpa_forecast_compose` emit `data_quality`, a coverage-labelled partial
+`conclusion`, and actionable repair items. Never delete a bad slice, turn it
+into zero spend, or renormalize the remaining allocation. The affected slice
+remains ineligible for Actuals comparison and execution until its mapping is
+fixed. Approval mismatch, duplicate or negative allocation, budget mismatch,
+invalid period/currency/role, and unauthorized execution remain blocking
+governance failures.
+
 ## Boundaries
 
 - Do not optimize, revise, or substitute the approved strategy while forecasting.
 - A required change invalidates the current approval and routes back to recommendation and review.
 - Unsupported KPIs remain `NULL` with a reason.
+- A partial conclusion must say it covers only calculable slices and must show
+  `calculable_spend_pct`; it must never be labelled portfolio ROAS.
 - Do not execute the strategy and do not start continuous monitoring.
 
 ## Completion

package/skills/fpa-forecast-approved-strategy/references/artifact-contract.md

@@ -41,6 +41,28 @@ calibration_policy:
   policy_version: string
 unsupported_metrics: []
 reconciliation_checks: []
+data_quality:
+  status: complete | partial | unavailable
+  planned_spend: number
+  calculable_spend: number
+  calculable_spend_pct: number  # 0..1; never renormalized
+  excluded_spend: number
+  issue_count: number
+  issues:
+    - issue_id: string
+      code: slice_key_not_in_actuals
+      severity: warning
+      slice: {app_id: string, store: string, channel_group: string}
+      affected_metrics: [actuals_comparison, revenue, roas, execution]
+      disposition: excluded_from_calculation
+      evidence: []
+      remediation: string
+      owner_role: data_steward
+conclusion:
+  status: available | available_with_limits | unavailable
+  scope: portfolio | calculable_slices | none
+  metrics: {spend: scenario_metric, revenue: scenario_metric, roas: scenario_metric}
+  warning: string | null
 frozen_at: timestamp
 ```
 
@@ -97,7 +119,10 @@ Rules the plan has to respect, because compose enforces them:
 
 - **Spend is a decision, not a prediction.** It is identical in all three scenarios, so a slice carries one `approved_spend`. Only revenue moves, through `roas`.
 - **A stopped slice has no ROAS.** `approved_spend: 0` means revenue 0 and `roas` null in all three scenarios — the contract derives ROAS as revenue/spend and calls a zero denominator null.
-- **Slice keys must be values `ua_spend` actually uses.** A plan naming `google_play` where the mart says `android` is rejected with the valid values listed. The single-placeholder App axis for a scoped-out portfolio is the one permitted exception.
+- **Slice keys are checked as real triples.** `app_code`, `platform`, and `media_source` must occur together in `ua_spend`; validating three independent value lists is insufficient. A mismatch is isolated as a data-quality limit: approved spend remains in the allocation and consolidated spend, while affected revenue/ROAS are `NULL`. The single-placeholder App axis for a scoped-out portfolio remains permitted.
+- **Do not hide partiality.** Compose reports planned, calculable, and excluded spend. Its partial conclusion covers only calculable slices; remaining spend is never scaled to 100%, and partial ROAS is never labelled portfolio ROAS.
+- **Data quality does not weaken governance.** Missing/mismatched approval, duplicate or negative allocation, invalid period/currency/forecast role, and budget reconciliation failures still block.
+- **Describe other upstream limits actionably.** For non-identity defects, each `unsupported_metrics` item should name the affected metric/scope, evidence, remediation, and data owner. Dashboard publication keeps these items visible even when `data_quality.status` is otherwise complete.
 - **`status` and `unsupported_metrics` must agree.** `complete` requires an empty list; `complete_with_limits` requires a non-empty one. Scope excluded upstream is neither.
 - **Do not hand-compute anything derived.** A ROAS rounded to four decimals misses the commit tolerance and costs a re-draft.