fix(h2-forecast): 预估区残余读路径 P2 收口（3 类 6 处）

任总 2026-10-02 11:35 直令「对外 /api/cma/** 读 KPIValue 默认只取实测区」同族残余
（ac4bbc6 范围外的 3 类 6 处）。6 处一律引 app.utils.kpi_value_scope.actual_only_clause()，
零新写字面量口径：
- customer_dashboard.py:76    年视图汇总（预估禁与实测相加）
- budget.py:260               按去年实绩加权派生基数（批量 auto-decompose）
- budget.py:333               同上（单 KPI auto-decompose）
- cash_forecast_engine.py:204 get_entity_kpi_history 历史/趋势序列
- cash_forecast_engine.py:259 get_current_cash_balance 最新值
- cash_forecast_engine.py:471 calculate_accuracy 实际值序列（预测输入）

证据：同脚本双树 A/B 15/15（改前 5/15，真库 kpi-forecast history 去掉 2026-H2、
next_target 336.32→250.99）；分类计数 33/41/9/3 → 39 covered/38 period_guarded/9 write/0 unguarded；
pytest 3 failed/1529 passed，失败集与基线逐条同 ID。不 push / 不部署 / 不重启 / 不写库。
Task: project-20261002-h2-forecast-residual-reads-p2-fullstack

backend/app/utils/cash_forecast_engine.py

@@ -4,6 +4,7 @@ import os
 from datetime import datetime, timedelta
 from typing import Optional, TYPE_CHECKING
 from sqlalchemy.orm import Session
+from app.utils.kpi_value_scope import actual_only_clause
 import math
 import random
 
@@ -202,6 +203,7 @@ def get_entity_kpi_history(entity_id: int, kpi_code: str, db: Session, limit_mon
         return []
     values = db.query(KPIValue).filter(
         KPIValue.kpi_id == kpi.id,
+        actual_only_clause(),  # 实测区口径：预估行禁进历史/趋势序列（kpi_value_scope）
         KPIValue.actual_value.isnot(None),
     ).order_by(KPIValue.period.desc()).limit(limit_months).all()
     return values
@@ -256,6 +258,7 @@ def get_current_cash_balance(db: Session, entity_id: int) -> Optional[float]:
     if kpi:
         latest_cash = db.query(KPIValue).filter(
             KPIValue.kpi_id == kpi.id,
+            actual_only_clause(),  # 实测区口径：预估行禁作现金余额依据（kpi_value_scope）
             KPIValue.actual_value.isnot(None),
         ).order_by(KPIValue.period.desc()).first()
         if latest_cash and latest_cash.actual_value is not None:
@@ -467,6 +470,7 @@ def calculate_accuracy(entity_id: int, db: Session) -> list:
 
     actuals = db.query(KPIValue).filter(
         KPIValue.kpi_id == cash_kpi.id,
+        actual_only_clause(),  # 实测区口径：预估行禁进实际值序列（预测输入）（kpi_value_scope）
         KPIValue.actual_value.isnot(None),
     ).order_by(KPIValue.period.desc()).limit(12).all()