fix(alerts): enforce caliber ruling R5-supp (period linkage)

deviation_engine: link kpi_value_id on deviation/trend alert rows; skip when period not attributable or kpi_values row missing; dedupe key now (entity_id,kpi_id,kpi_value_id,alert_type) deviation_push: same-source R1/R5 guards, no-period request writes nothing tests: add test_alert_caliber_r5_residual_20260919 (13 cases incl. negative controls); adapt r1r4/r5 fixtures to the supplemental ruling
2026-09-19 11:12:31 +08:00
parent 5a99ed87e0
commit 8c5853f64b
5 changed files with 497 additions and 91 deletions
@@ -8,9 +8,10 @@ from app.database import get_db
 from app.auth_middleware import require_auth, require_role
 from app.deps import get_entity_id
 from app.models import StrategicMap, KPIDefinition, KPIValue, KPIAlert, OperationLog, ActionPlan, BudgetPlan
+# 裁定 R5-补1（2026-09-19 财务口径）：差异反打路径同源接入 R1/R5 守卫
+from app.utils.alert_entity_scope import entity_alert_guard, guard_alert_period
 import json
 import logging
-from datetime import datetime

 logger = logging.getLogger("cma.deviation_push")

@@ -49,6 +50,22 @@ def push_deviation_to_map(
    if new_value is None:
        raise HTTPException(400, "缺少 newValue")

+    # R5-补1（财务裁定 2026-09-19）：「请求体无 period 一律不落库」
+    # 旧码在缺 period 时用当月冒充期间再落库（预警 + kpi_values 双写）——
+    # 该兜底正好绕过 R5「可归期」判据，故此处直接整请求零业务写入返回。
+    if not period:
+        logger.info(
+            "R5-补1 期间守卫：deviation_push 请求无 period，整请求零业务写入"
+            " entity_id=%s map_id=%s node_id=%s", entity_id, map_id, node_id)
+        return {
+            "success": False,
+            "message": "缺少 period：按 R5-补1（期间不可归期）未落库任何数据",
+            "alert_created": False,
+            "alert_skipped_reason": "no_period",
+            "zero_write": True,
+            "review_topic_created": False,
+        }
+
    # 1. 查找战略地图（2026-09-18 派生单: 地图须归属会话账套，NULL 归属按 e1 兼容）
    m = db.query(StrategicMap).filter(StrategicMap.id == map_id).first()
    if not m or (m.entity_id or 1) != entity_id:
@@ -95,9 +112,8 @@ def push_deviation_to_map(
        raise HTTPException(404, f"KPI {kpi_code} 不存在")

    # 3. 更新实际值到 KPIValue 表
-    if not period:
-        period = datetime.now().strftime("%Y-%m")
-
+    #（R5-补1：period 已在上方强制校验，原「缺 period 用当月兜底」分支已删除——
+    #  该兜底会伪造期间，正是 R5「不可归期」的成因之一）
    existing_value = db.query(KPIValue).filter(
        KPIValue.kpi_id == kpi.id,
        KPIValue.period == period,
@@ -106,20 +122,22 @@ def push_deviation_to_map(
    if existing_value:
        existing_value.actual_value = new_value
        existing_value.source_type = "manual"
+        kv_row = existing_value
    else:
-        kv = KPIValue(
+        kv_row = KPIValue(
            kpi_id=kpi.id,
            period=period,
            actual_value=new_value,
            source_type="manual",
        )
-        db.add(kv)
+        db.add(kv_row)

    db.flush()

    # 4. 检查是否触发预警
    alert_created = False
    alert_id = None
+    alert_skipped_reason = None
    if kpi.target_value and kpi.target_value > 0:
        ratio = new_value / kpi.target_value
        if ratio < 0.7:
@@ -132,17 +150,28 @@ def push_deviation_to_map(
            alert_level = None

        if alert_level:
-            alert = KPIAlert(
-                entity_id=kpi.entity_id or 1,   # 2026-09-13 F1: 显式写归属
-                kpi_id=kpi.id,
-                alert_level=alert_level,
-                alert_message=alert_msg,
-                status="pending",
-            )
-            db.add(alert)
-            db.flush()
-            alert_created = True
-            alert_id = alert.id
+            # R1/R5 双守卫（裁定 R5-补1）：demo 账套 / 非规整月期间 → 该 kpi_alerts 行不入库，
+            # 返回体登记跳过原因（KPI 值照写，与 bot_bridge 同口径：裁定只约束预警行）
+            if not entity_alert_guard(db, entity_id, source="deviation_push.push_deviation_to_map",
+                                      detail="kpi=%s" % kpi_code):
+                alert_skipped_reason = "R1_demo_entity_excluded"
+            elif not guard_alert_period(period, source="deviation_push.push_deviation_to_map",
+                                        detail="kpi=%s" % kpi_code):
+                alert_skipped_reason = "R5_non_attributable_period"
+
+            if alert_skipped_reason is None:
+                alert = KPIAlert(
+                    entity_id=kpi.entity_id or 1,   # 2026-09-13 F1: 显式写归属
+                    kpi_id=kpi.id,
+                    kpi_value_id=kv_row.id,         # R5-补1: 期间关联（同 kpi 同期间行 → 可派生）
+                    alert_level=alert_level,
+                    alert_message=alert_msg,
+                    status="pending",
+                )
+                db.add(alert)
+                db.flush()
+                alert_created = True
+                alert_id = alert.id

    # 5. 生成战略回顾会议题
    review_topic_created = False
@@ -180,6 +209,7 @@ def push_deviation_to_map(
            "new_value": new_value,
            "period": period,
            "alert_created": alert_created,
+            "alert_skipped_reason": alert_skipped_reason,
            "review_topic_created": review_topic_created,
        }, ensure_ascii=False),
    )
@@ -194,6 +224,7 @@ def push_deviation_to_map(
        "new_value": new_value,
        "alert_created": alert_created,
        "alert_id": alert_id,
+        "alert_skipped_reason": alert_skipped_reason,
        "review_topic_created": review_topic_created,
    }

@@ -17,6 +17,7 @@ from app.models import KPIDefinition, KPIValue, KPIAlert, BudgetPlan, SystemConf
 # 裁定 R1/R2/R3（2026-09-19 财务口径）：demo 账套排除 / 期间窗口 / 规整月期间
 from app.utils.alert_entity_scope import (
    excluded_entity_ids, kpi_excluded, period_in_window, window_lower_period,
+    guard_alert_period,  # R5-补1（2026-09-19）：期间可归期 + 关联 kpi_values
 )

 logger = logging.getLogger("cma.deviation")
@@ -80,13 +81,46 @@ def get_budget_for_kpi(db, kpi_id: int, period: str, version: str = None) -> Opt
    return plan.budget_value if plan else None


-def get_actual_for_kpi(db, kpi_id: int, period: str) -> Optional[float]:
-    """获取指定KPI在指定期间的实际值"""
-    val = db.query(KPIValue).filter(
+def get_kpi_value_row(db, kpi_id: int, period: str):
+    """取 (kpi_id, period) 的 KPIValue 行（取行口径唯一来源）。
+
+    与 get_actual_for_kpi 同源：预警行关联的 kpi_values 行 = 数值来源那一行。
+    """
+    return db.query(KPIValue).filter(
        KPIValue.kpi_id == kpi_id,
        KPIValue.period == period,
    ).order_by(KPIValue.calculated_at.desc()).first()
-    return val.actual_value if val else None
+
+
+def get_actual_for_kpi(db, kpi_id: int, period: str) -> Optional[float]:
+    """获取指定KPI在指定期间的实际值"""
+    row = get_kpi_value_row(db, kpi_id, period)
+    return row.actual_value if row else None
+
+
+def resolve_alert_kpi_value(db, kpi, period: str):
+    """R5-补1（财务裁定 2026-09-19）：解析差异/趋势预警行必须关联的 `kpi_values` 行。
+
+    裁定原文：「此类预警行必须在落库时写入 `kpi_value_id`，指向 **同 `entity_id` +
+    同 `kpi_id` + 文案所示规整月期间** 的 `kpi_values` 行。文案期间不可解析为 `YYYY-MM`，
+    或该 (kpi_id, period) 无 `kpi_values` 行 → 按 R5 `guard_alert_period` 跳过不入库
+    （不得以 `kpi_value_id=NULL` 落行——『文案里有期间』不构成可归期）。」
+
+    - 账套约束由 `kpi_id` 传递：KPIDefinition 归属单一账套，故 kpi_id 已唯一确定 entity_id；
+      取行口径与 `get_kpi_value_row`（= `get_actual_for_kpi` 的来源行）完全一致，
+      保证「预警关联的那一行」就是该预警数值的来源行，不会关联到别的账套/别的期间。
+    - 返回 `(kpi_value_row | None, skip_reason | None)`；跳过原因供调用点计数与日志。
+    """
+    if not guard_alert_period(period, source="deviation_engine.resolve_alert_kpi_value",
+                              detail="kpi=%s" % getattr(kpi, "kpi_code", "")):
+        return None, "R5_non_attributable_period"
+    row = get_kpi_value_row(db, kpi.id, period)
+    if row is None:
+        logger.info(
+            "R5-补1 期间关联：跳过不入库（该 (kpi, period) 无 kpi_values 行，期间不可派生）"
+            " kpi=%s period=%s", getattr(kpi, "kpi_code", ""), period)
+        return None, "no_kpi_value_row"
+    return row, None


 def calc_period_deviation(db, kpi_id: int, period: str) -> dict:
@@ -320,6 +354,10 @@ def run_deviation_check(db_session, period: str = None) -> int:
    2026-09-19 财务口径裁定 R1/R2/R3（`alert_entity_scope`）：
      · R1 —— `status='demo'` 的账套不参与遍历（demo 仅演示，不产生业务预警）；
      · R2/R3 —— 期间须为规整月 `YYYY-MM` 且落在窗口（当月往前 6 个自然月，含当月）内。
+      · R5-补1 —— 差异/趋势分支**必须落 `kpi_value_id` 关联**（同 kpi 同期间的 `kpi_values` 行）；
+        文案期间不可解析为 `YYYY-MM` 或该 (kpi, period) 无 `kpi_values` 行 → 跳过不入库；
+        趋势类以「计算基准期（趋势末端当期）」为关联期间；差异类去重键
+        = `(entity_id, kpi_id, kpi_value_id, alert_type)`。
    """
    if period is None:
        period = datetime.now().strftime("%Y-%m")
@@ -335,6 +373,8 @@ def run_deviation_check(db_session, period: str = None) -> int:

    new_count = 0
    skipped_demo = 0
+    skipped_period_linkage = 0
+    skipped_linkage_kpis = []
    for kpi in kpis:
        # R1（裁定 2026-09-19）：demo 演示账套不参与预警遍历
        if kpi_excluded(db_session, kpi, excluded):
@@ -349,53 +389,76 @@ def run_deviation_check(db_session, period: str = None) -> int:
                f"vs 预算{deviation['budget_value']}，"
                f"差异率{deviation['deviation_rate']}%"
            )
+            alert_type = result["alert_type"] or "actual"

-            # 检查是否已有同KPI同期间的差异预警
-            existing = db_session.query(KPIAlert).filter(
-                KPIAlert.kpi_id == kpi.id,
-                KPIAlert.alert_message.contains("[差异预警]"),
-                KPIAlert.alert_message.contains(period),
-                KPIAlert.status.in_(["pending", "processing"]),
-            ).first()
+            # R5-补1（裁定 2026-09-19）：期间可归期 + 必须落 kpi_value_id 关联
+            #（文案里的期间不构成可归期；无 kpi_values 行 → 跳过不入库）
+            linked_kv, _skip_reason = resolve_alert_kpi_value(db_session, kpi, period)
+            if linked_kv is None:
+                skipped_period_linkage += 1
+                skipped_linkage_kpis.append("%s[%s]" % (kpi.kpi_code, period))
+            else:
+                # 去重键（R5-补1 变更）：(entity_id, kpi_id, kpi_value_id, alert_type)
+                #（原按 `alert_message contains period` 判断，改关联后按可归期目标去重）
+                existing = db_session.query(KPIAlert).filter(
+                    KPIAlert.entity_id == (kpi.entity_id or 1),
+                    KPIAlert.kpi_id == kpi.id,
+                    KPIAlert.kpi_value_id == linked_kv.id,
+                    KPIAlert.alert_type == alert_type,
+                    KPIAlert.status.in_(["pending", "processing"]),
+                ).first()

-            if not existing:
-                alert = KPIAlert(
-                    entity_id=kpi.entity_id or 1,   # 2026-09-13 F1: 显式写归属（原缺省=1 串账套）
-                    kpi_id=kpi.id,
-                    alert_level=result["kpi_alert_level"],
-                    alert_message=f"[差异预警] {alert_msg}",
-                    alert_type=result["alert_type"] or "actual",
-                    suggestion=result["suggestion"],
-                    status="pending",
-                )
-                db_session.add(alert)
-                new_count += 1
-                logger.info(f"  新增差异预警 [{result['kpi_alert_level']}] {kpi.kpi_name}: 差异率{deviation['deviation_rate']}%")
+                if not existing:
+                    alert = KPIAlert(
+                        entity_id=kpi.entity_id or 1,   # 2026-09-13 F1: 显式写归属（原缺省=1 串账套）
+                        kpi_id=kpi.id,
+                        kpi_value_id=linked_kv.id,      # R5-补1: 期间经该行可派生（可归期）
+                        alert_level=result["kpi_alert_level"],
+                        alert_message=f"[差异预警] {alert_msg}",
+                        alert_type=alert_type,
+                        suggestion=result["suggestion"],
+                        status="pending",
+                    )
+                    db_session.add(alert)
+                    new_count += 1
+                    logger.info(f"  新增差异预警 [{result['kpi_alert_level']}] {kpi.kpi_name}: 差异率{deviation['deviation_rate']}%")

        # 2. 趋势异常检测（每期检查连续3期）
        trend = check_trend_anomaly(db_session, kpi.id, period, consecutive=3)
        if trend.get("anomaly") and trend.get("level") in ("yellow", "red"):
            trend_alert_msg = trend["message"]
-            existing_trend = db_session.query(KPIAlert).filter(
-                KPIAlert.kpi_id == kpi.id,
-                KPIAlert.alert_message.contains("[趋势预警]"),
-                KPIAlert.status.in_(["pending", "processing"]),
-            ).first()
+            # R5-补1：趋势类以「计算基准期（趋势末端当期）」为关联期间；该期无行 → 跳过
+            trend_periods = trend.get("periods") or []
+            base_period = trend_periods[-1] if trend_periods else period
+            linked_kv, _skip_reason = resolve_alert_kpi_value(db_session, kpi, base_period)
+            if linked_kv is None:
+                skipped_period_linkage += 1
+                skipped_linkage_kpis.append("%s[%s]" % (kpi.kpi_code, base_period))
+            else:
+                existing_trend = db_session.query(KPIAlert).filter(
+                    KPIAlert.kpi_id == kpi.id,
+                    KPIAlert.alert_message.contains("[趋势预警]"),
+                    KPIAlert.status.in_(["pending", "processing"]),
+                ).first()

-            if not existing_trend:
-                alert = KPIAlert(
-                    entity_id=kpi.entity_id or 1,   # 2026-09-13 F1: 显式写归属
-                    kpi_id=kpi.id,
-                    alert_level=trend["level"],
-                    alert_message=f"[趋势预警] {trend_alert_msg}",
-                    status="pending",
-                )
-                db_session.add(alert)
-                new_count += 1
-                logger.info(f"  新增趋势预警 [{trend['level']}] {trend_alert_msg}")
+                if not existing_trend:
+                    alert = KPIAlert(
+                        entity_id=kpi.entity_id or 1,   # 2026-09-13 F1: 显式写归属
+                        kpi_id=kpi.id,
+                        kpi_value_id=linked_kv.id,      # R5-补1: 趋势末端当期关联
+                        alert_level=trend["level"],
+                        alert_message=f"[趋势预警] {trend_alert_msg}",
+                        status="pending",
+                    )
+                    db_session.add(alert)
+                    new_count += 1
+                    logger.info(f"  新增趋势预警 [{trend['level']}] {trend_alert_msg}")

    if skipped_demo:
        logger.info("  差异预警跳过 demo 账套 KPI %s 项（R1，裁定 2026-09-19）", skipped_demo)
+    if skipped_period_linkage:
+        logger.info("  差异/趋势预警跳过（R5-补1 期间不可归期或无 kpi_values 行）KPI %s 项: %s",
+                    skipped_period_linkage, skipped_linkage_kpis)
    db_session.commit()
    return new_count