# -*- coding: utf-8 -*- """比率类 KPI 单位口径归一（取数层） —— 口径裁定 20260917(2a) + 20260924(v2.1 取代两项) 依据（唯一有效出处）：`wecom-finance/reports/CMA_口径裁定_20260924_比率类单位口径_取代2a两指标.md` —— 口径标识 `CMA-CALIBER-v2.1/kpi-unit@2026-09-24`（任总 2026-09-24 16:38 放行 ASK-20260924-11） · **取代范围仅两项**：`F_CURRENT_RATIO` / `F_QUICK_RATIO` → 统一「倍」（无量纲），**判定层不再 ×100** （同量纲直判）、`kpi_definitions` 的 unit/阈值/target_value 同步改倍口径；历史 `kpi_values` **不重算**； · **其余比率类指标仍按 20260917 裁定2a（百分比 %）执行**：毛利率、净利率、资产负债率、渠补率、返利率、 收入增长率等；本表内 `F_GROSS_MARGIN` 那行**保持 ×100 不动**； · **不得类推扩用**：再发现第三个「比率类单位/量纲矛盾」指标须**另行裁定**，不得以 v2.1 件为据类推改倍数； · 被取代件 `wecom-finance/reports/CMA_口径裁定_20260917.md`：其 2a 对其余比率类仍有效、2b 仍有效， **原件保留、一字节不改**。 · 2a 的过渡纪律（单位未核对前的「疑似错配」预警不推送）继续生效。 问题实证（2026-09-17 只读侦查 / 2026-09-24 v2.1 复核，entity 1 酣客）： `kpi_definitions` 原声明单位 = %，但**取数**以比率（倍）存储：流动比率 1.29 / 速动比率 0.54 / 毛利率 0.38， 而阈值按百分数书写（>=200 / >=100 / <15）→ 跨 2 个数量级比较，判定不可信（09-09 的 586/587 即此形态）。 **v2.1 处置**：流动/速动两项按**倍**口径落地（unit='倍'；绿>=2.0 / 黄>=1.0 / 红<1.0 与 绿>=1.0 / 黄>=0.5 / 红<0.5）⇒ 2026-08 的 1.29 → **黄**、0.54 → **黄**； 本模块对这两项**不再 ×100**（旧写法 `1.29×100=129` 去比 `>=2.0` 会**恒绿**，比原「恒红」更坏）。 其余百分数类（返利率 48.44、收入增长率 -82.2、资产负债率 39.9、费用率 30.0、渠补率 75.0 …） **取数已是百分数**，不得再 ×100（反过来会成为量级越界）。 实现约定（唯一事实源）： · 归一因子表 `RATIO_CALIBER_TABLE`（kpi_code → 口径/因子/证据/是否已核对）； · 判定侧只调 `resolve_caliber(actual, kpi)`，**不自行做字符串/量级判断**； · 表外且命中「疑似错配形态」的 KPI → status='dimension_suspect' → 调用方**不落预警、不推送**； · `norm_factor` 只影响**判定/推送口径**：2a 项不改 `kpi_values` 存储值、不改 `kpi_definitions` 阈值 （统一取数）；v2.1 取代的两项反之——**DB 的 unit/阈值已同步改倍口径**，故此处必须同量纲直判（factor=1）： **两侧只改一侧 ⇒ 恒红（未改本表）或恒绿（未改 DB）**。 """ from __future__ import annotations from typing import Optional, Sequence from app.utils.threshold_parser import parse_clauses #: 百分比口径的归一因子 FACTOR_PERCENT = 100 FACTOR_IDENTITY = 1 #: 比率类 KPI 单位对照表（裁定2a「逐个核对定义与单位」的落地产物；2026-09-24 v2.1 取代其中两项） #: norm_factor=1 → 取数已是百分数/同量纲，直接判定（含 v2.1 两项「倍」口径：取数与阈值同量纲） #: norm_factor=100 → 取数为比率（倍），判定前 ×100 归一到百分数口径（裁定2a；**本表仅毛利率仍用**） RATIO_CALIBER_TABLE = { # ---- 倍口径（v2.1 @2026-09-24 取代 2a 之两项；取数与 DB 阈值同量纲 ⇒ 不再归一）---- "F_CURRENT_RATIO": { "name": "流动比率", "declared_unit": "倍", "caliber": "倍（无量纲）", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "口径 `CMA-CALIBER-v2.1/kpi-unit@2026-09-24`（取代 2a 之 F_CURRENT_RATIO）：unit=倍 / 绿>=2.0 / 黄>=1.0 / 红<1.0；2026-08 实测 1.29（倍）→ 同量纲直判 = 黄；不再 ×100（旧 129% 判红已作废）", }, "F_QUICK_RATIO": { "name": "速动比率", "declared_unit": "倍", "caliber": "倍（无量纲）", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "口径 `CMA-CALIBER-v2.1/kpi-unit@2026-09-24`（取代 2a 之 F_QUICK_RATIO）：unit=倍 / 绿>=1.0 / 黄>=0.5 / 红<0.5；2026-08 实测 0.54（倍）→ 同量纲直判 = 黄；经验值 1:1 = 1.0 倍", }, # ---- 需归一（取数=倍，阈值=百分数写法；裁定2a 对其余比率类仍有效，不得顺手改）---- "F_GROSS_MARGIN": { "name": "毛利率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_PERCENT, "verified": True, "evidence": "2026-08 实测 0.38（同期另有 0.3766 行，源不同）→ ×100 = 38%；阈值 >=20|>=18|<15 为百分数写法（38% 合理，原口径 0.38<15 属假红）", }, # ---- 无需归一（取数已是百分数/同量纲，×100 会造成反向越界）---- "F_OP_PROFIT_MARGIN": { "name": "经营利润率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 -161.45 已是百分数（×100 得 -16145，量级越界）；阈值 >=10|>=8|<5 同量纲", }, "F_REBATE_RATE": { "name": "返利率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 48.44 已是百分数；量纲一致、判定有效（裁定 §4.4：不改阈值，48.44% 口径本身待财务确认 → 保留并标注）", }, "F_FACTORY_REBATE_RATE": { "name": "上游厂补率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 278.7 已是百分数（厂补/进货口径 >100% 属正常）", }, "F_REVENUE_GROWTH": { "name": "收入增长率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 -82.2 已是百分数", }, "F_ROE": { "name": "净资产收益率(ROE)", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 -0.95 已是百分数（小体量亏损月，-0.95% 量级合理）", }, "F_ROA": { "name": "总资产报酬率(ROA)", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 -0.57 已是百分数（kpi_code 2026-10-03 由 F_ROI 正名为 F_ROA，" "kpi_id/历史值不变；真 ROI 另立 F_ROI）", }, "F_ROI": { "name": "投入资本回报率(ROI)", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 派生实测 -6.74（YTD 营业利润÷投入资本，已是百分数；口径见 " "wecom-finance 2026-10-02 裁定）", }, "F_DEBT_RATIO": { "name": "资产负债率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 39.9 已是百分数", }, "F_COST_RATIO": { "name": "费用率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 30.0 已是百分数（阈值 <=25|<=30|>30）", }, "C_REBATE_RATE": { "name": "渠补率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 75.0 已是百分数（阈值含区间子句 52.33~107.67）", }, "F_BEP_COVER": { "name": "保本覆盖率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 60.4 已是百分数（阈值 >=100|>=85|<85）", }, "F_BEP_COVER_CASH": { "name": "现金口径保本覆盖率", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 85.2 已是百分数", }, "F_BEP_GAP": { "name": "保本缺口", "declared_unit": "%", "caliber": "百分比(%)", "norm_factor": FACTOR_IDENTITY, "verified": True, "evidence": "2026-08 实测 39.6 已是百分数", }, } #: 疑似错配形态的参数：阈值按百分数书写（子句量级 ≥ 100）而实测为比率量级（0 < |v| < 10） SUSPECT_THRESHOLD_ORDERS = 100.0 SUSPECT_ACTUAL_ABS_MAX = 10.0 #: 参与「疑似错配」判定的声明单位（比率/百分数类） SUSPECT_UNITS = ("%", "倍", "", "百分比", None) def _exprs_of(kpi) -> list: """取 KPI 三档阈值表达式（ORM 对象或同名 duck type 均可）""" return [getattr(kpi, "threshold_green", None), getattr(kpi, "threshold_yellow", None), getattr(kpi, "threshold_red", None)] def _clause_values(expr: str) -> list: """阈值表达式 → 比较值列表（区间取两端；解析失败返回空表）""" try: clauses = parse_clauses(expr) except Exception: return [] vals = [] for _op, val in clauses or []: if isinstance(val, tuple): vals.extend([v for v in val if isinstance(v, (int, float))]) elif isinstance(val, (int, float)): vals.append(val) return vals def suspected_unit_mismatch(actual, exprs: Sequence, unit=None) -> dict: """「疑似单位错配」形态检测（裁定2a 的降级门）。 形态：**所有**可解析阈值子句的量级都 ≥ 100（百分数写法），而实测值量级 < 10（比率写法） 且声明单位属比率/百分数类 → 跨量级比较，判定不可信。 为什么不用通用的「量级差 ≥1 个数量级」守卫：那会把**真实的小值告警**误伤 （实证：总资产周转率 2026-08 = 0.008 次 vs 阈值 1.0 次，量级差 2.1——那是真红，不是错配）。 """ if actual is None: return {"suspect": False, "reason": "无实测值"} try: a = abs(float(actual)) except (TypeError, ValueError): return {"suspect": False, "reason": "实测值非数值"} if a == 0: return {"suspect": False, "reason": "实测值为 0，量级不可判"} vals = [] for e in exprs or []: if e: vals.extend(_clause_values(e)) if not vals: return {"suspect": False, "reason": "阈值不可解析"} all_percent_written = all(abs(float(v)) >= SUSPECT_THRESHOLD_ORDERS for v in vals) ratio_magnitude = a < SUSPECT_ACTUAL_ABS_MAX unit_ok = unit in SUSPECT_UNITS if all_percent_written and ratio_magnitude and unit_ok: return {"suspect": True, "nearest": min(vals, key=lambda v: abs(a - abs(float(v)))), "reason": ("疑似单位错配：阈值按百分数书写（子句量级 ≥%g）而实测 %s 为比率量级（|v|<%g）" "，声明单位 %r → 判定不可信，降级待核（不推送）" % (SUSPECT_THRESHOLD_ORDERS, actual, SUSPECT_ACTUAL_ABS_MAX, unit))} return {"suspect": False, "reason": "形态不匹配（阈值量级/实测量级/单位 至少一项不符）"} def resolve_caliber(actual, kpi) -> dict: """判定侧唯一入口：返回取数归一结果与可信度状态。 return: { status: 'ok' | 'normalized' | 'dimension_suspect', value: 归一后用于判定/展示的数值, factor: 归一因子（1/100）, verified: 对照表核对状态（表外=False）, kpi_code, note, reason } · status='dimension_suspect' → 调用方**不落预警、不推送**（裁定2a 过渡纪律） """ code = getattr(kpi, "kpi_code", None) unit = getattr(kpi, "unit", None) row = RATIO_CALIBER_TABLE.get(code) if code else None if row: factor = row["norm_factor"] if row.get("verified") else FACTOR_IDENTITY if factor != FACTOR_IDENTITY and actual is not None: try: value = float(actual) * factor except (TypeError, ValueError): value = actual else: value = actual note = None if factor != FACTOR_IDENTITY: note = "口径归一 ×%d（原值 %s %s → %s%%）" % (factor, actual, row["declared_unit"], _fmt(value)) return {"status": "normalized" if factor != FACTOR_IDENTITY else "ok", "value": value, "factor": factor, "verified": bool(row.get("verified")), "kpi_code": code, "caliber": row.get("caliber"), "note": note, "reason": row.get("evidence")} sus = suspected_unit_mismatch(actual, _exprs_of(kpi), unit) if sus["suspect"]: return {"status": "dimension_suspect", "value": actual, "factor": FACTOR_IDENTITY, "verified": False, "kpi_code": code, "note": None, "reason": sus["reason"]} return {"status": "ok", "value": actual, "factor": FACTOR_IDENTITY, "verified": False, "kpi_code": code, "note": None, "reason": sus["reason"]} def _fmt(v) -> str: try: return ("%.2f" % float(v)).rstrip("0").rstrip(".") except (TypeError, ValueError): return str(v) class _K: """self-test 用的最小 KPI 载体""" def __init__(self, kpi_code, unit, green=None, yellow=None, red=None): self.kpi_code, self.unit = kpi_code, unit self.threshold_green, self.threshold_yellow, self.threshold_red = green, yellow, red def _self_test() -> int: """零库自证（裁定2a + 2026-09-24 v2.1）：倍口径直判、2a 归一、疑似错配降级、真实小值不误伤""" from app.utils.threshold_parser import eval_threshold, LEVEL_PRIORITY def level(actual, kpi): cal = resolve_caliber(actual, kpi) if cal["status"] == "dimension_suspect": return "dimension_suspect" v = cal["value"] exprs = {"green": kpi.threshold_green, "yellow": kpi.threshold_yellow, "red": kpi.threshold_red} for lv in LEVEL_PRIORITY: if exprs.get(lv) and eval_threshold(v, exprs[lv]): return lv return "info" cases = ( # (说明, 实测, KPI, 期望) ("倍口径(v2.1) 流动比率 1.29 → 直判 1.29 ∈ [1.0,2.0) 黄", 1.29, _K("F_CURRENT_RATIO", "倍", ">=2.0", ">=1.0", "<1.0"), "yellow"), ("倍口径(v2.1) 速动比率 0.54 → 直判 0.54 ∈ [0.5,1.0) 黄", 0.54, _K("F_QUICK_RATIO", "倍", ">=1.0", ">=0.5", "<0.5"), "yellow"), ("毛利率 0.38 → 归一 38% vs 绿>=20", 0.38, _K("F_GROSS_MARGIN", "%", ">=20", ">=18", "<15"), "green"), ("返利率 48.44 已百分数 → 红>12（不 ×100）", 48.44, _K("F_REBATE_RATE", "%", "<=10", ">10", ">12"), "red"), ("收入增长率 -82.2 已百分数 → 红<15", -82.2, _K("F_REVENUE_GROWTH", "%", ">=20", ">=15", "<15"), "red"), ("总资产周转率 0.008 次 vs 阈值 1.0（真实小值，不误伤）", 0.008, _K("F_ASSET_TURNOVER", "次", ">=1.0", ">=0.8", "<0.8"), "red"), ("表外比率 KPI（阈值百分数写法）→ 降级待核不推送", 1.29, _K("X_UNKNOWN_RATIO", "%", ">=200", ">=150", "<150"), "dimension_suspect"), ("高值不误判：营业收入 14.45 万 vs 阈值 97.33（非比率量级）", 14.45, _K("F_REVENUE", "万元", ">=97.33", ">=77.87", "<58.4"), "red"), ) ok = 0 print("=== 比率类单位口径归一 self-test ===") for desc, actual, kpi, expect in cases: got = level(actual, kpi) flag = "PASS" if got == expect else "FAIL" ok += (got == expect) cal = resolve_caliber(actual, kpi) print(" [%s] %-46s → %-18s (期望 %s) value=%s factor=%s" % (flag, desc, got, expect, cal["value"], cal["factor"])) print("=== %d/%d PASS | 对照表 %d 项（归一 %d 项 / 同量纲 %d 项）===" % ( ok, len(cases), len(RATIO_CALIBER_TABLE), sum(1 for v in RATIO_CALIBER_TABLE.values() if v["norm_factor"] != FACTOR_IDENTITY), sum(1 for v in RATIO_CALIBER_TABLE.values() if v["norm_factor"] == FACTOR_IDENTITY))) return 0 if ok == len(cases) else 1 if __name__ == "__main__": raise SystemExit(_self_test())