fix(bep-caliber): rebate rate uses YTD actual voucher cumulative (571103 debit / 5001 credit), book+cash card read derived, fail-closed

backend/scripts/kpi_bep_deriver.py

@@ -6,13 +6,20 @@
   F_BEP_GAP          保本缺口(%)         = (保本销售额-月均销售) ÷ 保本销售额 × 100 (反向: <=0绿 <=15黄 >15红)
   F_BEP_REVENUE_CASH 现金保本销售额(万元) = (月均管理费-月均折旧) ÷ 边际贡献率 (现金口径,剔除折旧560213,中性无阈值)
   F_BEP_COVER_CASH   现金保本覆盖率(%)   = 月均销售 ÷ 现金保本销售额 × 100 (正向: >=100绿 >=85黄 <85红)
+  F_BEP_REBATE       实测渠补率(%)       = Σ(571103借方) ÷ Σ(5001贷方) × 100 (YTD累计; 卡面单一事实源,无阈值)
 
 口径（与财务Bot报告一致）：
 - 销售收入: voucher_details.subject_code='5001'(主营业务收入) 贷方合计，当年1月至目标月 YTD 月均
 - 管理费:   subject_code LIKE '5602%'(管理费用，含560213折旧) 借−贷净额合计(carry_forward=0)，YTD 月均 → 账面口径
 - 折旧:     subject_code = '560213'(管理费用-折旧叶子) 借−贷净额合计(carry_forward=0)，YTD 月均 → 现金口径剔除项(eq精确匹配,防5602130误含)
-- 渠补率:   厂家政策定死 84.61% (571103渠补支出/5001销售, 1-7月累计凭证验证≈84.0%~84.6%)
-- 边际贡献率 = 1 - 渠补率 = 15.39%
+- 渠补率:   **实测累计口径**（2026-10-02 财务裁定，任总 11:43 CST 放行「改，这样数据更加真实」）
+            渠补率(实测) = Σ(571103 借方) ÷ Σ(5001 贷方) × 100，期间 = 年初至当期(YTD)，保留 2 位小数。
+            `POLICY_REBATE_RATE_PCT = 84.61` 政策常量**仅作对照展示**（写进返回值 rebate_policy_pct / remark），
+            **不参与任何计算**；`--rebate-rate` 显式传值时视为人工诊断覆盖（正常调用不再使用）。
+- 边际贡献率 = 100 − 渠补率(实测)
+- fail-closed 边界（2026-10-02 裁定）：某期 571103 或 5001 缺数/为 0 ⇒ **该期不出保本值**
+  （六条派生行写 actual_value=NULL + data_status='pending' + remark 注明「渠补率不可得」），
+  **不得静默回落 84.61 常量**；累计口径天然平滑单月波动（8 月单月 571103/5001=134% 不影响累计值）。
 - 目标月:   --period 显式指定；默认自动选最近「已结账」完整月（当月跳过）。
             结账信号优先：DB 损益结转凭证(carry_forward=1 & subject_code='3103') → check.md 文件；
             两者皆无时才退回旧「销售额阈值」兜底（销售低 ≠ 未结账，仅保底用，日志标注依据）
@@ -48,6 +55,8 @@ logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(me
 logger = logging.getLogger("cma.bep_deriver")
 
 # 厂家政策渠补率（定死不可谈判，财务Bot报告权威值 2026-09-08）
+# ⚠️ 2026-10-02 起**仅作对照展示**（返回值 rebate_policy_pct / remark），不参与任何计算。
+#    参与计算的渠补率 = 逐期实测累计（见 compute_rebate_rate / 文件头「渠补率」条）。
 POLICY_REBATE_RATE_PCT = 84.61
 
 # 派生KPI 编码 → (kpi_code, 名称)
@@ -57,8 +66,15 @@ TARGET_KPIS = [
     ("F_BEP_GAP", "保本缺口"),
     ("F_BEP_REVENUE_CASH", "现金口径保本销售额"),
     ("F_BEP_COVER_CASH", "现金口径保本覆盖率"),
+    ("F_BEP_REBATE", "实测渠补率"),
 ]
 
+# 实测渠补率 KPI 编码（卡面单一事实源；无阈值，不参与预警级别判定）
+REBATE_KPI = "F_BEP_REBATE"
+
+# 保本口径 KPI（缺 F_BEP_REBATE 定义时不阻断派生主流程，仅跳过渠补率落库并告警）
+CORE_KPI_CODES = [c for c, _ in TARGET_KPIS if c != REBATE_KPI]
+
 # 现金口径 KPI 编码（计算路径独立于账面，remark 文案用现金口径）
 CASH_CODES = {"F_BEP_REVENUE_CASH", "F_BEP_COVER_CASH"}
 
@@ -161,6 +177,40 @@ def _sum_field(db, entity_id: int, period_from: str, period_to: str,
     return float(val or 0.0)
 
 
+def compute_rebate_rate(db, entity_id: int, period_from: str, period_to: str) -> dict:
+    """实测累计渠补率（2026-10-02 财务裁定口径）。
+
+    渠补率(实测) = Σ(571103 借方) ÷ Σ(5001 贷方) × 100，期间 = 年初至当期（YTD），保留 2 位小数。
+      · 571103 = 渠补/捐赠支出（损益类费用科目）⇒ 本期发生额落**借方**；
+      · 5001   = 主营业务收入 ⇒ 本期发生额落**贷方**；
+      · 行域 = carry_forward=0（与 _sum_field 一致，排除期间损益结转腿）。
+
+    返回 {'available', 'rebate_pct', 'rebate_sum_w', 'sales_sum_w', 'reason'}；
+    **fail-closed**：分子或分母缺数/为 0 ⇒ available=False, rebate_pct=None
+    （调用方不得回落政策常量，须按「渠补率不可得」处理）。
+    """
+    rebate_sum_w = _sum_field(db, entity_id, period_from, period_to,
+                              "debit_amount", ("eq", REBATE_CODE)) / 10000.0
+    sales_sum_w = _sum_field(db, entity_id, period_from, period_to,
+                             "credit_amount", ("eq", SALES_CODE)) / 10000.0
+    info = {
+        "rebate_sum_w": round(rebate_sum_w, 2),
+        "sales_sum_w": round(sales_sum_w, 2),
+        "available": False,
+        "rebate_pct": None,
+        "reason": "",
+    }
+    if sales_sum_w <= 0:
+        info["reason"] = "渠补率不可得：5001 贷方累计缺数或为 0"
+        return info
+    if rebate_sum_w <= 0:
+        info["reason"] = "渠补率不可得：571103 借方累计缺数或为 0"
+        return info
+    info["available"] = True
+    info["rebate_pct"] = round(rebate_sum_w / sales_sum_w * 100.0, 2)
+    return info
+
+
 def _month_sales(db, entity_id: int, period: str) -> float:
     """单月销售收入（万元）——用于目标月完整度判断"""
     return _sum_field(db, entity_id, period, period, "credit_amount",
@@ -287,17 +337,28 @@ def _eval_static_threshold(value: float, kpi) -> tuple:
     return None, None
 
 
-def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
+def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float = None,
                write_kpi: bool = True) -> dict:
-    """计算并落库五个派生KPI（账面3条+现金2条）。返回结果摘要。"""
+    """计算并落库六个派生KPI（账面3条+现金2条+实测渠补率1条）。返回结果摘要。
+
+    渠补率（2026-10-02 裁定）：默认按 YTD 从 voucher_details **现算**
+    （Σ571103借方 ÷ Σ5001贷方），政策常量 84.61% 仅作对照返回（rebate_policy_pct）。
+    显式传 rebate_rate_pct（`--rebate-rate`）时视为人工诊断覆盖。
+    fail-closed：实测渠补率不可得且无人工覆盖 ⇒ 该期不出保本值（六行 pending/NULL）。
+    """
     kpis = {k.kpi_code: k for k in db.query(KPIDefinition).filter(
         KPIDefinition.entity_id == entity_id,
         KPIDefinition.kpi_code.in_([c for c, _ in TARGET_KPIS]),
         KPIDefinition.status == "active",
     ).all()}
-    missing = [c for c, _ in TARGET_KPIS if c not in kpis]
+    missing = [c for c in CORE_KPI_CODES if c not in kpis]
     if missing:
         raise RuntimeError(f"entity={entity_id} 缺少派生KPI定义: {missing}")
+    if REBATE_KPI not in kpis:
+        # 渠补率定义缺失不阻断保本主流程（部署顺序容错），但必须显式告警：
+        # 卡面此时取不到 rebate_pct（单一事实源缺失），需尽快补 bep_kpi_defs_rebate SQL。
+        logger.error("entity=%s 缺少 %s 定义（见 scripts/sql/bep_kpi_defs_rebate_20261002.sql）；"
+                     "本期跳过实测渠补率落库，卡面将判「渠补率不可得」", entity_id, REBATE_KPI)
 
     year = period[:4]
     period_from = f"{year}-01"
@@ -307,7 +368,6 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
     # 1. 取数（元 → 万元）
     sales_sum_w = _sum_field(db, entity_id, period_from, period_to, "credit_amount", ("eq", SALES_CODE)) / 10000.0
     admin_sum_w = _sum_field(db, entity_id, period_from, period_to, "net", ("like", ADMIN_PREFIX)) / 10000.0
-    rebate_sum_w = _sum_field(db, entity_id, period_from, period_to, "net", ("eq", REBATE_CODE)) / 10000.0
     dep_sum_w = _sum_field(db, entity_id, period_from, period_to, "net", ("eq", DEP_SUBJECT)) / 10000.0
 
     sales_avg = sales_sum_w / months
@@ -315,11 +375,22 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
     dep_avg = dep_sum_w / months
     cash_admin_avg = admin_avg - dep_avg  # 现金口径固定成本（剔除折旧纸面费用）
 
-    # 2. 渠补率：厂家政策值优先，日志附凭证累计校验
-    calc_rebate = (rebate_sum_w / sales_sum_w * 100.0) if sales_sum_w > 0 else 0.0
-    if rebate_rate_pct is None:
-        rebate_rate_pct = POLICY_REBATE_RATE_PCT
-    cm_pct = 100.0 - rebate_rate_pct  # 边际贡献率(%)
+    # 2. 渠补率：默认逐期实测累计（不再取政策常量；常量仅对照）
+    rebate_info = compute_rebate_rate(db, entity_id, period_from, period_to)
+    calc_pct = rebate_info["rebate_pct"]
+    if rebate_rate_pct is not None:
+        rebate_info = dict(rebate_info, available=True, rebate_pct=round(float(rebate_rate_pct), 2),
+                           reason="人工覆盖（--rebate-rate）")
+        logger.warning("渠补率使用人工覆盖值 %.2f%%（YTD 实算值 %s）", rebate_rate_pct,
+                       ("%.2f%%" % calc_pct) if calc_pct is not None else "不可得")
+    elif not rebate_info["available"]:
+        # fail-closed：不出保本值，绝不静默回落政策常量 84.61
+        logger.error("period=%s %s ⇒ 本期不出保本值（fail-closed，不回落政策常量）",
+                     period, rebate_info["reason"])
+        return _fail_closed_rebate_unavailable(db, entity_id, period, months, rebate_info, kpis, write_kpi)
+
+    rebate_pct = rebate_info["rebate_pct"]
+    cm_pct = 100.0 - rebate_pct  # 边际贡献率(%) = 100 − 实测渠补率
 
     # 3. 派生计算（万元 / %）——账面3条路径不变；现金口径在账面基础上剔除折旧
     bep = admin_avg / (cm_pct / 100.0) if cm_pct > 0 else 0.0
@@ -334,6 +405,7 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
         "F_BEP_GAP": round(gap, 1),
         "F_BEP_REVENUE_CASH": round(cash_bep, 1),
         "F_BEP_COVER_CASH": round(cash_cover, 1),
+        "F_BEP_REBATE": round(rebate_pct, 2),
     }
 
     # 4. upsert kpi_values (source_type='derived'，幂等)
@@ -342,12 +414,21 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
     value_rows = {}
     changed = []
     for code, _ in TARGET_KPIS:
-        kpi = kpis[code]
-        if code in CASH_CODES:
+        kpi = kpis.get(code)
+        if kpi is None:  # 定义缺失（仅可能为 F_BEP_REBATE，见上方告警）
+            written[code] = "no-definition"
+            continue
+        if code == REBATE_KPI:
+            remark = (f"实测渠补率(YTD累计): Σ571103借方 {rebate_info['rebate_sum_w']:.2f}万 ÷ "
+                      f"Σ5001贷方 {rebate_info['sales_sum_w']:.2f}万 × 100 = {rebate_pct:.2f}%"
+                      f"（政策常量 {POLICY_REBATE_RATE_PCT:.2f}% 仅供对照，不参与计算）")
+        elif code in CASH_CODES:
             remark = (f"现金口径: 管理费月均{admin_avg:.2f}万-折旧月均{dep_avg:.2f}万"
-                      f"=固定现金{cash_admin_avg:.2f}万 ÷ 边际贡献率{cm_pct:.2f}% → 保本{cash_bep:.2f}万")
+                      f"=固定现金{cash_admin_avg:.2f}万 ÷ 边际贡献率{cm_pct:.2f}% → 保本{cash_bep:.2f}万"
+                      f"（实测渠补率{rebate_pct:.2f}%）")
         else:
-            remark = f"保本派生器: 销售月均{sales_avg:.1f}万/管理费月均{admin_avg:.1f}万/渠补率{rebate_rate_pct:.2f}%"
+            remark = (f"保本派生器: 销售月均{sales_avg:.1f}万/管理费月均{admin_avg:.1f}万/"
+                      f"实测渠补率{rebate_pct:.2f}%(政策{POLICY_REBATE_RATE_PCT:.2f}%仅对照)")
         existing = db.query(KPIValue).filter(
             KPIValue.kpi_id == kpi.id,
             KPIValue.period == period,
@@ -437,6 +518,7 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
         "entity_id": entity_id,
         "period": period,
         "months": months,
+        "data_status": "ok",
         "sales_sum_w": round(sales_sum_w, 2),
         "sales_avg": round(sales_avg, 2),
         "admin_sum_w": round(admin_sum_w, 2),
@@ -444,9 +526,12 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
         "dep_sum_w": round(dep_sum_w, 2),
         "dep_avg": round(dep_avg, 2),
         "cash_admin_avg": round(cash_admin_avg, 2),
-        "rebate_sum_w": round(rebate_sum_w, 2),
-        "rebate_policy_pct": rebate_rate_pct,
-        "rebate_calc_pct": round(calc_rebate, 2),
+        "rebate_sum_w": rebate_info["rebate_sum_w"],
+        "rebate_sales_base_w": rebate_info["sales_sum_w"],
+        "rebate_actual_pct": rebate_pct,
+        "rebate_policy_pct": POLICY_REBATE_RATE_PCT,
+        "rebate_source": rebate_info.get("reason") or "YTD实测累计(Σ571103借方/Σ5001贷方)",
+        "rebate_calc_pct": round(calc_pct, 2) if calc_pct is not None else None,
         "cm_pct": round(cm_pct, 2),
         "values": values,
         "written": written,
@@ -454,12 +539,77 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float,
     }
 
 
+def _fail_closed_rebate_unavailable(db, entity_id: int, period: str, months: int,
+                                    rebate_info: dict, kpis: dict,
+                                    write_kpi: bool) -> dict:
+    """fail-closed 落库：实测渠补率不可得 ⇒ 该期不出保本值。
+
+    六条派生行写 actual_value=NULL + data_status='pending' + remark 注明「渠补率不可得」，
+    **不回落**政策常量 84.61（2026-10-02 财务裁定 / 任总 11:43 CST 放行）。
+    不评估阈值、不产生/解除预警（无值 ⇒ 无级别可评）。
+    """
+    reason = rebate_info["reason"] or "渠补率不可得"
+    detail = (f"{reason}；Σ571103借方 {rebate_info['rebate_sum_w']:.2f}万 / "
+              f"Σ5001贷方 {rebate_info['sales_sum_w']:.2f}万 ⇒ 本期不出保本值（fail-closed，"
+              f"不回落政策常量 {POLICY_REBATE_RATE_PCT:.2f}%）")
+    batch = f"bep-{datetime.now().strftime('%Y%m%d%H%M%S')}"
+    written = {}
+    if write_kpi:
+        for code, _ in TARGET_KPIS:
+            kpi = kpis.get(code)
+            if kpi is None:
+                written[code] = "no-definition"
+                continue
+            existing = db.query(KPIValue).filter(
+                KPIValue.kpi_id == kpi.id,
+                KPIValue.period == period,
+                KPIValue.source_type == "derived",
+            ).first()
+            if existing is None:
+                db.add(KPIValue(
+                    entity_id=entity_id,
+                    kpi_id=kpi.id,
+                    period=period,
+                    actual_value=None,
+                    source_type="derived",
+                    source_batch=batch,
+                    data_status="pending",
+                    remark=detail,
+                ))
+                written[code] = "insert"
+            else:
+                existing.actual_value = None
+                existing.source_batch = batch
+                existing.data_status = "pending"
+                existing.remark = detail
+                written[code] = "upsert"
+        db.commit()
+    else:
+        written = {c: "dry-run" for c, _ in TARGET_KPIS}
+    return {
+        "entity_id": entity_id,
+        "period": period,
+        "months": months,
+        "data_status": "pending",
+        "rebate_unavailable": True,
+        "reason": detail,
+        "sales_sum_w": rebate_info["sales_sum_w"],
+        "rebate_sum_w": rebate_info["rebate_sum_w"],
+        "rebate_actual_pct": None,
+        "rebate_policy_pct": POLICY_REBATE_RATE_PCT,
+        "rebate_source": reason,
+        "values": {},
+        "written": written,
+        "value_changed": [],
+    }
+
+
 def main():
     ap = argparse.ArgumentParser(description="保本点派生KPI执行器")
     ap.add_argument("--period", default=None, help="目标期间 YYYY-MM（默认自动选最近完整月）")
     ap.add_argument("--entity", type=int, default=1, help="entity_id（默认1=陕西酣客）")
     ap.add_argument("--rebate-rate", type=float, default=None,
-                    help="渠补率%覆盖（默认厂家政策84.61）")
+                    help="渠补率%%人工覆盖（诊断用；**默认按 YTD 从 voucher_details 实测现算**，不再取政策常量）")
     ap.add_argument("--dry-run", action="store_true", help="只计算不落库")
     args = ap.parse_args()
 
@@ -469,18 +619,24 @@ def main():
         r = run_derive(db, args.entity, period, args.rebate_rate,
                        write_kpi=not args.dry_run)
         print(f"保本点派生计算完成 entity={r['entity_id']} period={r['period']} "
-              f"(YTD {r['months']}个月) mode={'dry-run' if args.dry_run else 'write'}")
+              f"(YTD {r['months']}个月) mode={'dry-run' if args.dry_run else 'write'} "
+              f"data_status={r['data_status']}")
+        if r["data_status"] == "pending":
+            print(f"  ⚠ fail-closed：{r['reason']}")
+            print(f"  落库: {r['written']}")
+            return
         print(f"  销售收入累计 {r['sales_sum_w']:.2f}万 月均 {r['sales_avg']:.2f}万")
         print(f"  管理费累计 {r['admin_sum_w']:.2f}万 月均 {r['admin_avg']:.2f}万 (含折旧,账面口径)")
         print(f"  折旧累计 {r['dep_sum_w']:.2f}万 月均 {r['dep_avg']:.2f}万 (560213) | "
               f"现金固定成本月均 {r['cash_admin_avg']:.2f}万 (管理费-折旧)")
-        print(f"  渠补支出累计 {r['rebate_sum_w']:.2f}万 | 渠补率: 政策{r['rebate_policy_pct']:.2f}% "
-              f"(凭证累计校验 {r['rebate_calc_pct']:.2f}%) | 边际贡献率 {r['cm_pct']:.2f}%")
+        print(f"  渠补支出累计 {r['rebate_sum_w']:.2f}万 | 实测渠补率(YTD) {r['rebate_actual_pct']:.2f}% "
+              f"| 政策常量 {r['rebate_policy_pct']:.2f}% (仅对照) | 边际贡献率 {r['cm_pct']:.2f}%")
         print(f"  F_BEP_REVENUE 保本销售额 = {r['values']['F_BEP_REVENUE']} 万元")
         print(f"  F_BEP_COVER   保本覆盖率 = {r['values']['F_BEP_COVER']} %")
         print(f"  F_BEP_GAP     保本缺口   = {r['values']['F_BEP_GAP']} %")
         print(f"  F_BEP_REVENUE_CASH 现金保本销售额 = {r['values']['F_BEP_REVENUE_CASH']} 万元")
         print(f"  F_BEP_COVER_CASH   现金保本覆盖率 = {r['values']['F_BEP_COVER_CASH']} %")
+        print(f"  F_BEP_REBATE       实测渠补率     = {r['values']['F_BEP_REBATE']} %")
         print(f"  落库: {r['written']}")
     finally:
         db.close()

backend/scripts/sql/bep_kpi_defs_rebate_20261002.sql

@@ -0,0 +1,20 @@
+-- CMA BEP 实测渠补率派生KPI定义 — F_BEP_REBATE（2026-10-02）
+-- 口径: 渠补率(实测) = Σ(571103 借方) ÷ Σ(5001 贷方) × 100，期间 = 年初至当期(YTD)，2位小数
+--   依据: 财务Bot 2026-10-02 裁定（任总 11:43 CST 放行「改，这样数据更加真实」）
+--   政策常量 84.61% 自本日起仅作对照展示，不再参与计算
+-- 幂等: NOT EXISTS 守卫，可安全重跑
+INSERT INTO kpi_definitions
+(entity_id, kpi_code, kpi_name, dimension, category, formula, formula_desc,
+ data_source_type, data_source, data_owner, frequency, unit, target_value,
+ target_calc_type, threshold_green, threshold_yellow, threshold_red,
+ kpi_level, status, bot_source, epic, created_by)
+SELECT 1, 'F_BEP_REBATE', '实测渠补率', 'finance', 'profitability',
+ 'round(sum(571103借方)/sum(5001贷方)*100,2)',
+ '渠补率(实测,YTD累计)=Σ571103借方÷Σ5001贷方; 供保本点卡面单一事实源; 政策常量84.61%仅对照; 缺数期不出值(fail-closed)',
+ 'derived', 'BEP派生器 kpi_bep_deriver.py(voucher_details 571103/5001 累计)', '财务部', 'monthly', '%', NULL,
+ 'ratio', NULL, NULL, NULL,
+ 'strategic', 'active', 'finance-bot', 'Epic2', 1
+FROM DUAL
+WHERE NOT EXISTS (
+  SELECT 1 FROM kpi_definitions WHERE entity_id = 1 AND kpi_code = 'F_BEP_REBATE'
+);