fix(alerts): enforce caliber rulings R1-R4 for alert generation

R1: exclude status=demo entities from alert traversal (alert_generator / deviation_engine / kpi_bep_deriver / alert_rules / cash engine) R2: only generate alerts within the last 6 calendar months (incl. current) R3: only regular month periods (YYYY-MM) participate R4: decouple generation from push - empty notification_channels never blocks Single source of truth: app/utils/alert_entity_scope.py
2026-09-19 10:05:11 +08:00
parent d785a22efd
commit 3beec14d96
7 changed files with 641 additions and 21 deletions
@@ -20,6 +20,11 @@ from app.utils.threshold_parser import eval_threshold, LEVEL_PRIORITY
 # 裁定2a（2026-09-17 财务口径）：比率类指标统一「百分比(%)」口径（取数×100），
 # 未核对/疑似单位错配的项降级待核（不落预警、不推送）
 from app.utils.caliber_units import resolve_caliber
+# 裁定 R1/R2/R3（2026-09-19 财务口径）：账套范围（demo 排除）/ 期间窗口 / 规整月期间
+from app.utils.alert_entity_scope import (
+    ALERT_WINDOW_MONTHS, excluded_entity_ids, is_month_period, kpi_excluded,
+    period_in_window, window_lower_period,
+)

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

@@ -86,7 +91,7 @@ def _check_threshold(actual: float, threshold_expr: str, level: str) -> tuple:


 def run_alert_check(db_session, period: Optional[str] = None, dry_run: bool = False,
-                    stats: Optional[dict] = None) -> int:
+                    stats: Optional[dict] = None, now: Optional[datetime] = None) -> int:
    """检查所有KPI的实际值是否触发预警，返回（将）新生成的预警数

    2026-09-17 财务口径裁定 2a/2b：
@@ -95,12 +100,29 @@ def run_alert_check(db_session, period: Optional[str] = None, dry_run: bool = Fa
      · **单位（2a）**：判定前经 resolve_caliber() 归一到「百分比(%)」口径（取数×100，
        与阈值 150/80 同量纲）；**未核对/疑似单位错配**的项降级待核 → 不落预警、不推送；
      · dry_run=True → 只计算不写库（抽查复核与放行前证据用）。
+
+    2026-09-19 财务口径裁定 R1/R2/R3（`alert_entity_scope` 单一事实源）：
+      · **R1 账套**：`status='demo'` 的账套（演示账套）不参与遍历 → 跳过并计
+        `skipped_demo_kpis`；
+      · **R2 期间窗口**：仅生成「当月往前 6 个自然月（含当月）」内的预警；更早期间跳过
+        （`out_of_window`），与 2b 叠加 = max(各 KPI 最近可用期间, 当月-6月)；
+      · **R3 伪期间**：仅规整月期间 YYYY-MM 参与，H1/H2/FY 跳过（`skipped_pseudo_period`）。
+      · now 参数仅用于口径复算/测试（缺省=系统当前时间）。
    """
    st = stats if stats is not None else {}
+    window_lower = window_lower_period(now)
+    excluded_eids = excluded_entity_ids(db_session)
    for k, v in (("period_source", "fixed" if period else "per_kpi_latest"), ("period_fixed", period),
                 ("periods_used", {}), ("normalized", 0), ("normalized_kpis", []),
                 ("dimension_suspect", 0), ("suspect_kpis", []), ("no_period", 0),
-                 ("no_value", 0), ("planned", []), ("skipped_existing", 0)):
+                 ("no_value", 0), ("planned", []), ("skipped_existing", 0),
+                 # R1/R2/R3 口径证据
+                 ("excluded_demo_entities", sorted(excluded_eids)),
+                 ("window_lower_period", window_lower),
+                 ("window_months", ALERT_WINDOW_MONTHS),
+                 ("skipped_demo_kpis", 0), ("demo_kpis", []),
+                 ("skipped_pseudo_period", 0), ("pseudo_period_kpis", []),
+                 ("out_of_window", 0), ("out_of_window_kpis", [])):
        st.setdefault(k, v)

    kpis = db_session.query(KPIDefinition).filter(
@@ -109,6 +131,12 @@ def run_alert_check(db_session, period: Optional[str] = None, dry_run: bool = Fa

    new_count = 0
    for kpi in kpis:
+        # R1（裁定 2026-09-19）：demo 演示账套不参与预警遍历
+        if kpi_excluded(db_session, kpi, excluded_eids):
+            st["skipped_demo_kpis"] += 1
+            st["demo_kpis"].append("%s/e%s" % (kpi.kpi_code, kpi.entity_id or 1))
+            continue
+
        # 跳过无阈值的KPI
        thr = {
            "red": kpi.threshold_red,
@@ -125,6 +153,21 @@ def run_alert_check(db_session, period: Optional[str] = None, dry_run: bool = Fa
            logger.warning(f"  跳过（无可用期间）: {kpi.kpi_name} 无任何 YYYY-MM 实测值")
            continue

+        # R3（裁定 2026-09-19）：仅规整月期间 YYYY-MM 参与，伪期间一律不参与
+        if not is_month_period(p):
+            st["skipped_pseudo_period"] += 1
+            st["pseudo_period_kpis"].append("%s[%s]" % (kpi.kpi_code, p))
+            logger.warning("  跳过（伪期间 R3）: %s 期间=%s 非 YYYY-MM" % (kpi.kpi_name, p))
+            continue
+
+        # R2（裁定 2026-09-19）：期间窗口 = 当月往前 6 个自然月（含当月），更早不新生成
+        if str(p) < window_lower:
+            st["out_of_window"] += 1
+            st["out_of_window_kpis"].append("%s[%s]" % (kpi.kpi_code, p))
+            logger.info("  跳过（期间超出窗口 R2，窗口下限 %s）: %s[%s]" % (
+                window_lower, kpi.kpi_name, p))
+            continue
+
        # 获取该KPI该期间的最新值
        latest = db_session.query(KPIValue).filter(
            KPIValue.kpi_id == kpi.id,
@@ -261,7 +304,8 @@ def run_rule_engine_checks(db_session) -> dict:
        AlertRule, run_forecast_deviation_check, run_customer_concentration_check,
    )

-    stats = {"forecast_deviation": 0, "customer_concentration": 0}
+    stats = {"forecast_deviation": 0, "customer_concentration": 0,
+             "skipped_demo_entities": 0, "excluded_entities": sorted(excluded_entity_ids(db_session))}
    try:
        rows = db_session.query(AlertRule.entity_id).filter(
            AlertRule.enabled == 1,
@@ -272,6 +316,11 @@ def run_rule_engine_checks(db_session) -> dict:
        return stats

    for (eid,) in rows:
+        # R1（裁定 2026-09-19）：demo 演示账套不参与预警遍历
+        if int(eid or 1) in set(stats["excluded_entities"]):
+            stats["skipped_demo_entities"] += 1
+            logger.info(f"  规则引擎跳过（demo 账套 R1）: entity={eid}")
+            continue
        for key, fn in (("forecast_deviation", run_forecast_deviation_check),
                        ("customer_concentration", run_customer_concentration_check)):
            try:
@@ -285,24 +334,42 @@ def run_rule_engine_checks(db_session) -> dict:
    return stats


-def generate_and_push(db_session, period: Optional[str] = None, dry_run: bool = False) -> dict:
+def _enabled_channel_count(db_session) -> int:
+    """R4（裁定 2026-09-19）：推送出口计数 —— 生成/推送解耦，空通道只记录不报错。"""
+    from app.models import NotificationChannel
+    try:
+        return int(db_session.query(NotificationChannel).filter(
+            NotificationChannel.enabled == True  # noqa: E712 - 与其他调用点一致
+        ).count())
+    except Exception as e:  # pragma: no cover - 防御分支
+        logger.warning(f"读取通知渠道失败（按无渠道处理）: {e}")
+        return 0
+
+
+def generate_and_push(db_session, period: Optional[str] = None, dry_run: bool = False,
+                      now: Optional[datetime] = None) -> dict:
    """生成预警并推送，返回统计

    2026-09-17 财务口径裁定 2a/2b：
      · **period=None** → 判定期间 = 各 KPI「最近可用期间」（裁定2b，不再硬编码当月）；
        显式给出 period → 固定该期间（抽查复核用）；
      · **dry_run=True** → 零写入、零推送：返回将生成的预警清单与口径证据（放行前抽查复核）。
+
+    2026-09-19 裁定 R1–R4：
+      · R1/R2/R3 在 run_alert_check 内落地（demo 账套排除 / 期间窗口 / 规整月期间）；
+      · **R4 生成与推送解耦**：`notification_channels` 为空时仅入库、不报错、不阻断；
    """
-    cur_month = datetime.now().strftime("%Y-%m")
+    cur_month = (now or datetime.now()).strftime("%Y-%m")
    st = {}
-    logger.info("开始预警检查（当月=%s；判定期间=%s）..." % (
-        cur_month, ("固定 %s" % period) if period else "各 KPI 最近可用期间（裁定2b）"))
+    logger.info("开始预警检查（当月=%s；判定期间=%s；窗口下限=%s；排除账套=%s）..." % (
+        cur_month, ("固定 %s" % period) if period else "各 KPI 最近可用期间（裁定2b）",
+        window_lower_period(now), sorted(excluded_entity_ids(db_session))))

    # 0. Bug1修复: 先清理历史green预警（dry-run 不写）
    cleaned = 0 if dry_run else cleanup_green_alerts(db_session)

    # 1. 生成预警（期间口径 + 单位口径均在此落地）
-    new_count = run_alert_check(db_session, period=period, dry_run=dry_run, stats=st)
+    new_count = run_alert_check(db_session, period=period, dry_run=dry_run, stats=st, now=now)
    logger.info(f"预警检查完成: {'将新增' if dry_run else '新增'} {new_count} 条")

    # 1a. 覆盖度自检（2026-09-16 项3；2026-09-17 裁定2b 过渡期保留并扩展「期间回落」明细）：
@@ -338,19 +405,29 @@ def generate_and_push(db_session, period: Optional[str] = None, dry_run: bool =
        else run_rule_engine_checks(db_session)

    # 2. 推送（dry-run 零推送）
+    #    R4（裁定 2026-09-19）：生成与推送解耦 —— notification_channels 为空时
+    #    **仅入库、不报错、不阻断**（推送出口缺失只是"未触达"，不等于"未生成"）。
+    channels_enabled = _enabled_channel_count(db_session)
+    push_skipped_no_channel = channels_enabled == 0
    pushed = 0
    if new_count > 0 and not dry_run:
-        try:
-            from app.utils.notifier import push_pending_alerts
-            pushed = push_pending_alerts(db_session)
-            logger.info(f"推送完成: {pushed} 条")
-        except Exception as e:
-            logger.error(f"推送失败: {e}")
+        if push_skipped_no_channel:
+            logger.info("推送出口缺失（notification_channels 启用数=0）→ 仅入库、不推送、不阻断（裁定 R4）")
+        else:
+            try:
+                from app.utils.notifier import push_pending_alerts
+                pushed = push_pending_alerts(db_session)
+                logger.info(f"推送完成: {pushed} 条")
+            except Exception as e:
+                logger.error(f"推送失败（不影响已入库预警，生成/推送解耦 R4）: {e}")

    return {"period": cur_month, "dry_run": dry_run,
            "period_source": st.get("period_source"), "period_fixed": st.get("period_fixed"),
            "periods_used": st.get("periods_used", {}),
            "new_alerts": new_count, "pushed": pushed,
+            # R4：推送出口（生成/推送解耦证据）
+            "channels_enabled": channels_enabled,
+            "push_skipped_no_channel": push_skipped_no_channel,
            "cleaned_green": cleaned, "rule_engine": rule_stats,
            "coverage": coverage,
            # 裁定2a 口径证据
@@ -358,7 +435,14 @@ def generate_and_push(db_session, period: Optional[str] = None, dry_run: bool =
            "dimension_suspect": st.get("dimension_suspect", 0), "suspect_kpis": st.get("suspect_kpis", []),
            # 期间/取值覆盖明细
            "no_period": st.get("no_period", 0), "no_value": st.get("no_value", 0),
-            "skipped_existing": st.get("skipped_existing", 0), "planned": st.get("planned", [])}
+            "skipped_existing": st.get("skipped_existing", 0), "planned": st.get("planned", []),
+            # 裁定 R1/R2/R3 口径证据
+            "excluded_demo_entities": st.get("excluded_demo_entities", []),
+            "skipped_demo_kpis": st.get("skipped_demo_kpis", 0),
+            "window_lower_period": st.get("window_lower_period"), "window_months": st.get("window_months"),
+            "out_of_window": st.get("out_of_window", 0), "out_of_window_kpis": st.get("out_of_window_kpis", []),
+            "skipped_pseudo_period": st.get("skipped_pseudo_period", 0),
+            "pseudo_period_kpis": st.get("pseudo_period_kpis", [])}


 def coverage_note(result: dict) -> str:
@@ -380,6 +464,18 @@ def coverage_note(result: dict) -> str:
                     % (result["dimension_suspect"], (result.get("suspect_kpis") or [])[:3]))
    if result.get("normalized"):
        parts.append(" | 口径归一 ×100 %s 项" % result["normalized"])
+    # 裁定 R1/R2/R3/R4（2026-09-19）证据
+    if result.get("skipped_demo_kpis"):
+        parts.append(" | R1 排除 demo 账套 %s（跳过 KPI %s 项）"
+                     % (result.get("excluded_demo_entities"), result["skipped_demo_kpis"]))
+    if result.get("out_of_window"):
+        parts.append(" | R2 窗口(下限 %s)外不新生成 %s 项"
+                     % (result.get("window_lower_period"), result["out_of_window"]))
+    if result.get("skipped_pseudo_period"):
+        parts.append(" | R3 伪期间跳过 %s 项" % result["skipped_pseudo_period"])
+    if result.get("push_skipped_no_channel"):
+        parts.append(" | R4 推送出口缺失(启用渠道 %s) → 仅入库、不阻断"
+                     % result.get("channels_enabled"))
    return "".join(parts)


@@ -38,6 +38,8 @@ import re
 from sqlalchemy import func
 from app.database import get_session_local
 from app.models import KPIValue, KPIDefinition, VoucherDetail, KPIAlert
+# 裁定 R1（2026-09-19 财务口径）：demo 账套不产生业务预警（派生值仍落库，仅跳过预警同步）
+from app.utils.alert_entity_scope import is_excluded_entity

 logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
 logger = logging.getLogger("cma.bep_deriver")
@@ -320,7 +322,11 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
        # 5. 同步预警: 仅对本派生KPI评估 threshold（green=正常不落 pending，yellow/red 落 pending）。
        #    幂等规则：同一 KPIValue 已有同级别 pending → 保持不动（值未变不重建）；
        #    其它/旧级别 pending → resolve；最新派生行永远只留一条当前级别。
-        for code, _ in TARGET_KPIS:
+        #    R1（裁定 2026-09-19）：demo 账套不产生业务预警 → 整段预警同步跳过（派生值照落库）。
+        target_sync = [] if is_excluded_entity(db, entity_id) else TARGET_KPIS
+        if not target_sync:
+            logger.info("demo 账套（entity=%s）跳过预警同步（R1，裁定 2026-09-19）", entity_id)
+        for code, _ in target_sync:
            kpi = kpis[code]
            kpi_value = value_rows.get(kpi.id)
            if not kpi_value: