feat(cvp): CM≤0 fail-closed 禁写0.0 + 博海BEP扩面(新口径) + 影子CVP标注is_mock + 前端NULL守卫/不适用
ci/woodpecker/push/main Pipeline failed

- kpi_bep_deriver.py: 实体口径注册表(app/utils/bep_caliber.py 单一事实源);博海(6001/6401/6601-03/1602);
  fail-closed② 边际贡献非正/固定成本退化 ⇒ 五条保本值 NULL+pending+remark'不适用'(禁回落0.0)
- dashboard.py /bep-card: 多实体口径 + not_applicable 态返回 label/reason
- predict.py /cvp-detailed: 显式 source=scenario_simulation + is_mock=true(影子CVP标注)
- 前端 BEPBreakEvenCard.vue: 全量数值判空 + '不适用'态;PredictDashboard.vue: 情景模拟·非实测标签

验收 accept-bep-cvp-20261003.py: BEFORE 2/11 → AFTER 11/11 PASS
任务 finance-20261003-cvp-fix-and-bohai-coverage-fullstack
This commit is contained in:
Hermes CI Fix
2026-10-03 16:03:12 +08:00
parent 8631ce718f
commit 1f1385ebbf
7 changed files with 662 additions and 147 deletions
+83 -21
View File
@@ -12,6 +12,8 @@ from app.utils.cache import get as cache_get, set as cache_set
from app.utils.voucher_guard import apply_voucher_guard
from app.utils.threshold_parser import eval_threshold
from app.utils.alert_entity_scope import month_period_clause
# BEP 实体口径单一事实源(2026-10-03 扩面:酣客 entity1 / 博海 entity2 同表驱动派生器与卡面)
from app.utils.bep_caliber import CLOSING_SUMMARY_LIKE, caliber_or_none
# 「实测区 / 预估区」分区口径单一事实源(财务裁定 2026-10-02,任总「把 H2 预测行与实际分离」)
# —— 预估行(data_status='estimated' 或 source_type='forecast')禁进实测汇总 / 趋势序列 /
# 预警依据;仅 include_forecast=true 时以独立字段(forecast_value / is_forecast)单列返回。
@@ -47,21 +49,27 @@ BEP_CODES = ("F_BEP_REVENUE", "F_BEP_COVER", "F_BEP_GAP",
"F_BEP_REVENUE_CASH", "F_BEP_COVER_CASH", "F_BEP_REBATE")
BEP_BOOK_CODES = ("F_BEP_REVENUE", "F_BEP_COVER", "F_BEP_GAP") # 账面3条必须齐全才 available
BEP_CASH_CODES = ("F_BEP_REVENUE_CASH", "F_BEP_COVER_CASH")
BEP_REBATE_CODE = "F_BEP_REBATE" # 实测渠补率派生KPI编码(卡面单一事实源)
BEP_REBATE_CODE = "F_BEP_REBATE" # 变动/渠补率派生KPI编码(卡面单一事实源)
# 展示用输入口径常量(**仅酣客(entity1)**;多实体一律走 app/utils/bep_caliber.py 的 ENTITY_CALIBERS,
# 2026-10-03 扩面:博海 entity2 为 6001/6401/6601+6602+6603/1602)
BEP_SALES_SUBJECT = "5001"
BEP_ADMIN_PREFIX = "5602"
BEP_DEP_SUBJECT = "560213"
# 政策常量:仅作对照展示(2026-10-02 起不参与任何计算)
# 政策常量:仅作对照展示(2026-10-02 起不参与任何计算;博海无渠补科目 ⇒ None)
BEP_REBATE_POLICY_PCT = 84.61
def _bep_sum_field(db, entity_id: int, period_from: str, period_to: str,
field: str, subject_filter=None) -> float:
field: str, subject_filter=None, *, exclude_closing: bool = False,
subject_filters=None) -> float:
"""聚合 voucher_details 金额(元),subject_filter: ('eq', code) / ('like', prefix)
field="net" = 借−贷 净额(口径4:费用/损益一律净额)。
⚠️ 净额只在 carry_forward==0 行域成立(含结转腿时损益类净额恒 0)
—— 见 /srv/hermes/wisdom/_decisions/cma-expense-profit-net-caliber-20261002.md。
exclude_closing(2026-10-03):该账套结转腿未标 carry_forward 时(博海:全账套 cf 恒 0),
须按 summary NOT LIKE '%结转%' 显式剔除,否则已结账期间净额恒 0。
subject_filters:多条 OR(固定成本 6601+6602+6603)。
作废/撤单标记过滤(2026-09-14 收口): 已作废凭证不参与 BEP 均值。
"""
expr = (VoucherDetail.debit_amount - VoucherDetail.credit_amount
@@ -72,8 +80,18 @@ def _bep_sum_field(db, entity_id: int, period_from: str, period_to: str,
VoucherDetail.period >= period_from,
VoucherDetail.period <= period_to,
)
if subject_filter:
kind, code = subject_filter
if exclude_closing:
q = q.filter(or_(VoucherDetail.summary.is_(None),
~VoucherDetail.summary.like(CLOSING_SUMMARY_LIKE)))
filt = subject_filter
if subject_filters:
clauses = []
for kind, code in subject_filters:
clauses.append(VoucherDetail.subject_code == code if kind == "eq"
else VoucherDetail.subject_code.like(code + "%"))
q = q.filter(or_(*clauses))
elif filt:
kind, code = filt
if kind == "eq":
q = q.filter(VoucherDetail.subject_code == code)
elif kind == "like":
@@ -83,6 +101,24 @@ def _bep_sum_field(db, entity_id: int, period_from: str, period_to: str,
return float(val or 0.0)
def _bep_inputs(db, entity_id: int, cal: dict, period_from: str, period: str, months: int) -> dict:
"""卡面展示用输入(万元/百分比)——按实体口径现算,与派生器同源同式。"""
sales = _bep_sum_field(db, entity_id, period_from, period, cal["revenue_field"],
cal["revenue_filter"], exclude_closing=cal["exclude_closing"]) / 10000.0
admin = _bep_sum_field(db, entity_id, period_from, period, "net",
subject_filters=cal["fixed_filters"],
exclude_closing=cal["exclude_closing"]) / 10000.0
dep = _bep_sum_field(db, entity_id, period_from, period, cal["dep_field"],
cal["dep_filter"], exclude_closing=cal["exclude_closing"]) / 10000.0
return {
"sales_avg": round(sales / months, 2),
"admin_avg": round(admin / months, 2),
"dep_avg": round(dep / months, 2),
"cash_admin_avg": round((admin - dep) / months, 2),
}
def _bep_level(value, kpi) -> str:
"""按 KPI 静态阈值文本判定级别(绿→黄→红,命中即止),无阈值返回 none。
与 alert_generator / kpis._static_threshold_level 语义一致。"""
@@ -118,6 +154,12 @@ def get_bep_card(
· 账面 / 现金两条路径**统一读派生落库值**(不再实时复算 voucher);
· fail-closed:六条派生值同期不齐(尤其缺渠补率)⇒ available=False,不出保本值、不回落常量。
"""
cal = caliber_or_none(entity_id)
if cal is None:
return {"available": False, "entity_id": entity_id,
"message": f"entity={entity_id} 未注册 BEP 口径(见 app/utils/bep_caliber.py)",
"rebate_policy_pct": BEP_REBATE_POLICY_PCT, "readonly": True}
kpis = {k.kpi_code: k for k in db.query(KPIDefinition).filter(
KPIDefinition.entity_id == entity_id,
KPIDefinition.status == "active",
@@ -140,9 +182,11 @@ def get_bep_card(
month_period_clause(KPIValue.period),
).order_by(KPIValue.period.desc(), KPIValue.id.desc()).all()
by_code = {} # {code: {period: value|None}}
by_code = {} # {code: {period: value|None}}
remark_map = {} # {(code, period): remark} —— 用于区分「不适用」与「缺数」
for v, code in rows:
by_code.setdefault(code, {}).setdefault(v.period, v.actual_value)
remark_map.setdefault((code, v.period), v.remark or "")
# 卡面期 = 账面三条派生行的**最新期间**(与派生器目标期一致)
book_periods = sorted({p for c in BEP_BOOK_CODES for p in by_code.get(c, {})}, reverse=True)
@@ -151,25 +195,44 @@ def get_bep_card(
"message": "尚无派生值,请先运行 kpi_bep_deriver.py",
"rebate_policy_pct": BEP_REBATE_POLICY_PCT, "readonly": True}
period = book_periods[0]
year = period[:4]
months = int(period[5:7])
period_from = f"{year}-01"
# fail-closed:六条派生值(含实测渠补率)本期必须齐全,缺一条即不出保本值
# fail-closed:六条派生值(含变动成本率)本期必须齐全,缺一条即不出保本值
missing_at_period = [c for c in BEP_CODES if by_code.get(c, {}).get(period) is None]
if missing_at_period:
# ① 不适用(派生器 fail-closed 落库:remark 已注明「保本点不适用」)
# —— 与「缺数」区分:卡面显示「不适用」而非「数据不齐」,且不得显示 0。
na_remarks = [remark_map.get((c, period), "") for c in missing_at_period]
na_hit = [r for r in na_remarks if "不适用" in r]
if na_hit and BEP_REBATE_CODE not in missing_at_period:
reason = na_hit[0]
label = ("边际贡献为负 · 保本点不适用" if "边际贡献非正" in reason
else "固定成本退化 · 保本点不适用")
return {"available": False, "not_applicable": True, "entity_id": entity_id,
"period": period, "months": months,
"label": label, "reason": reason,
"rebate_pct": by_code.get(BEP_REBATE_CODE, {}).get(period),
"rebate_policy_pct": (cal.get("policy_pct")
if cal.get("policy_pct") is not None else BEP_REBATE_POLICY_PCT),
"entity_name": cal["name"],
"missing_codes": missing_at_period,
"derived_periods": book_periods[:6],
"data_source": "derived", "readonly": True}
# ② 缺数(真不齐)
if BEP_REBATE_CODE in missing_at_period:
msg = ("渠补率(实测)不可得:本期未落 F_BEP_REBATE 派生值 ⇒ 不出保本值"
msg = (f"{cal['margin_label']}不可得:本期未落 F_BEP_REBATE 派生值 ⇒ 不出保本值"
"(fail-closed,不回落政策常量、不跨期回落)")
else:
msg = ("本期派生值不齐 %s ⇒ 不出保本值(fail-closed,不跨期回落)"
% ",".join(missing_at_period))
return {"available": False, "entity_id": entity_id, "period": period,
"message": msg, "missing_codes": missing_at_period,
"rebate_policy_pct": BEP_REBATE_POLICY_PCT,
"rebate_policy_pct": (cal.get("policy_pct") if cal.get("policy_pct") is not None
else BEP_REBATE_POLICY_PCT),
"derived_periods": book_periods[:6], "readonly": True}
year = period[:4]
months = int(period[5:7])
period_from = f"{year}-01"
# 六条派生落库值(同期)—— 账面 / 现金两条路径同一来源,卡面不做实时复算
d = {c: by_code[c][period] for c in BEP_CODES}
book_bep = float(d["F_BEP_REVENUE"])
@@ -181,14 +244,13 @@ def get_bep_card(
rebate_pct = float(d[BEP_REBATE_CODE]) # 实测累计渠补率(单一事实源)
cm_pct = round(100.0 - rebate_pct, 2)
# 输入口径(万元,展示用;数值口径一律以派生落库值为准)
sales_avg = _bep_sum_field(db, entity_id, period_from, period,
"credit_amount", ("eq", BEP_SALES_SUBJECT)) / 10000.0 / months
admin_avg = _bep_sum_field(db, entity_id, period_from, period,
"net", ("like", BEP_ADMIN_PREFIX)) / 10000.0 / months
dep_avg = _bep_sum_field(db, entity_id, period_from, period,
"net", ("eq", BEP_DEP_SUBJECT)) / 10000.0 / months
cash_admin = admin_avg - dep_avg
# 输入口径(万元,展示用;数值口径一律以派生落库值为准)——按实体口径现算
inp = _bep_inputs(db, entity_id, cal, period_from, period, months)
sales_avg = inp["sales_avg"]
admin_avg = inp["admin_avg"]
dep_avg = inp["dep_avg"]
cash_admin = inp["cash_admin_avg"]
policy_pct = cal.get("policy_pct") # 博海无渠补政策常量 ⇒ None(前端不显示对照)
# 回显六条派生落库值(同期)
derived = {c: {"period": period, "value": d[c]} for c in BEP_CODES}
+9 -1
View File
@@ -114,7 +114,12 @@ def api_scenario_analysis(data: dict):
@router.post("/cvp-detailed")
def api_cvp_detailed(data: dict):
"""CVP本量利详细分析 — 含改善方案推演和保本图数据 (CMA P2)"""
"""CVP本量利详细分析 — 含改善方案推演和保本图数据 (CMA P2)
⚠️ 情景模拟器(scenario simulation):入参为**假设值**推演(前端滑杆),
非 CMA 实测口径。真实实测口径见派生 KPI `F_BEP_*`(kpi_bep_deriver.py,单一事实源);
响应显式带 source='scenario_simulation' + is_mock=True,前端据此标注「情景模拟·非实测」。
"""
try:
fixed_cost = float(data.get("fixed_cost", 617))
variable_cost_rate = float(data.get("variable_cost_rate", 0.4862))
@@ -151,6 +156,9 @@ def api_cvp_detailed(data: dict):
chart_data.append({"volume": vol, "revenue": rev, "total_cost": tc, "profit": round(rev - tc, 2)})
return {
"source": "scenario_simulation",
"is_mock": True,
"basis": "user_input_scenario",
"fixed_cost": fixed_cost,
"variable_cost_rate": round(variable_cost_rate * 100, 2),
"unit_price": unit_price,
+78
View File
@@ -0,0 +1,78 @@
# -*- coding: utf-8 -*-
"""BEP(本量利·保本点)实体口径注册表 —— **单一事实源**。
被两侧共用,避免口径漂移:
· 派生落库写入面:`backend/scripts/kpi_bep_deriver.py`
· 卡面读取面 :`backend/app/api/dashboard.py::/bep-card`
口径(2026-10-03 财务裁定,任务 finance-20261003-cvp-fix-and-bohai-coverage-fullstack):
| 项 | entity 1 陕西酣客 | entity 2 博海 |
|---|---|---|
| 变动成本(分子) | Σ571103 借方(渠补/捐赠支出) | Σ6401 借方(主营业务成本) |
| 收入基数(分母) | Σ5001 贷方(主营业务收入) | Σ6001 贷方(主营业务收入) |
| 变动成本率 | Σ571103借 ÷ Σ5001贷(实测渠补率) | Σ6401借 ÷ Σ6001贷(主营业务成本率) |
| 固定成本 | `5602%`(管理费用,含折旧)借−贷净额 | `6601+6602+6603`(销售/管理/财务费用)借−贷净额 |
| 折旧剔除(现金口径) | `560213`(管理费用-折旧叶子) | `1602` 累计折旧**当期贷方发生额**(见下) |
| 本期利润结转科目 | `3103` 本年利润 | `4103` 本年利润 |
| 结账信号次选(落盘) | `/root/WB_WS/_data/zxt-hanke/{YYYY.MM}/check.md` | 无(只用 DB 信号) |
博海折旧口径说明:博海科目表只到 4 位一级科目(无费用类折旧叶子,**不存在** 酣客式 `560213`),
唯一含「折旧」的是资产类 `1602 累计折旧`;其**当期贷方发生额** = 当期计提折旧额(对方科目
计入 `6602 管理费用`),故取它作现金口径剔除项。实测 2026-01..07 每月 1,468.83 元,
2026-08 起无计提行 ⇒ 2026-08 剔除额为 0(已在回报件列明)。
⚠️ 博海账套的「期间损益结转腿」(`summary='结转期间损溢'`,凭证如 `记-705/记-706`)
**未**标 `carry_forward=1`(全账套 17343 行 carry_forward 恒 0)⇒ 若不显式剔除,
损益类科目「借−贷」净额在已结账月份恒为 0,会把指标静默清零
(口径见 `/srv/hermes/wisdom/_decisions/cma-expense-profit-net-caliber-20261002.md`)。
故博海口径 `exclude_closing=True`。
"""
CLOSING_SUMMARY_LIKE = "%结转%"
# 酣客结账信号次选来源(智享通落盘 check.md;与 app/api/data.py 的 ZXT_LANDING_DIR 同源)
ZXT_LANDING_DIR_HANKE = "/root/WB_WS/_data/zxt-hanke"
ENTITY_CALIBERS = {
1: dict(
name="陕西酣客",
margin_label="实测渠补率",
margin_desc="Σ571103借方 ÷ Σ5001贷方",
revenue_field="credit_amount", revenue_filter=("eq", "5001"),
varcost_field="debit_amount", varcost_filter=("eq", "571103"),
fixed_filters=[("like", "5602")],
fixed_label="管理费",
dep_field="net", dep_filter=("eq", "560213"),
closing_subject="3103",
landing_dir=ZXT_LANDING_DIR_HANKE,
exclude_closing=False,
policy_pct=84.61, # 政策常量:仅对照展示,不参与计算(仅酣客有)
),
2: dict(
name="博海",
margin_label="变动成本率(主营业务成本率)",
margin_desc="Σ6401借方 ÷ Σ6001贷方",
revenue_field="credit_amount", revenue_filter=("eq", "6001"),
varcost_field="debit_amount", varcost_filter=("eq", "6401"),
fixed_filters=[("like", "6601"), ("like", "6602"), ("like", "6603")],
fixed_label="固定成本(6601+6602+6603)",
dep_field="credit_amount", dep_filter=("eq", "1602"),
closing_subject="4103",
landing_dir=None,
exclude_closing=True,
policy_pct=None, # 博海无渠补政策常量
),
}
def caliber_or_none(entity_id: int):
"""取实体口径;未注册返回 None(调用方自行决定放行/拒答)。"""
return ENTITY_CALIBERS.get(entity_id)
def caliber_for(entity_id: int) -> dict:
"""取实体口径;未注册抛 KeyError(写入面用,fail-closed)。"""
cal = ENTITY_CALIBERS.get(entity_id)
if cal is None:
raise KeyError(f"entity={entity_id} 未注册 BEP 口径(见 app/utils/bep_caliber.py)")
return cal
+346 -109
View File
@@ -1,38 +1,57 @@
"""保本点(盈亏平衡)派生KPI执行器 — 管理会计OS (cma-bep-kpi 2026-09-08)
按财务Bot权威口径(陕西酣客_保本点分析_2026年1-7月.md)自动计算并落库五个派生KPI:
F_BEP_REVENUE 保本销售额(万元) = 月均管理费 ÷ 边际贡献率 (账面口径,含折旧)
按财务Bot权威口径(陕西酣客_保本点分析_2026年1-7月.md)自动计算并落库六个派生KPI:
F_BEP_REVENUE 保本销售额(万元) = 月均固定成本 ÷ 边际贡献率 (账面口径,含折旧)
F_BEP_COVER 保本覆盖率(%) = 月均销售 ÷ 保本销售额 × 100 (正向: >=100绿 >=85黄 <85红)
F_BEP_GAP 保本缺口(%) = (保本销售额-月均销售) ÷ 保本销售额 × 100 (反向: <=0绿 <=15黄 >15红)
F_BEP_REVENUE_CASH 现金保本销售额(万元) = (月均管理费-月均折旧) ÷ 边际贡献率 (现金口径,剔除折旧560213,中性无阈值)
F_BEP_REVENUE_CASH 现金保本销售额(万元) = (月均固定成本-月均折旧) ÷ 边际贡献率 (现金口径,中性无阈值)
F_BEP_COVER_CASH 现金保本覆盖率(%) = 月均销售 ÷ 现金保本销售额 × 100 (正向: >=100绿 >=85黄 <85红)
F_BEP_REBATE 实测渠补率(%) = Σ(571103借方) ÷ Σ(5001贷方) × 100 (YTD累计; 卡面单一事实源,无阈值)
F_BEP_REBATE 变动/渠补率(%) = 见下方「实体口径注册表」 (YTD累计; 卡面单一事实源,无阈值)
实体口径注册表(2026-10-03 新增,任务 finance-20261003-cvp-fix-and-bohai-coverage-fullstack):
· entity 1 陕西酣客:变动成本率 = Σ571103借方 ÷ Σ5001贷方(实测渠补率);固定成本 = 5602% 净额;
折旧剔除 = 560213(管理费用-折旧叶子)。
· entity 2 博海:**无渠补科目(571103)**,变动成本 = Σ6401借(主营业务成本),
变动成本率 = Σ6401借 ÷ Σ6001贷;固定成本 = (6601 销售费用 + 6602 管理费用 + 6603 财务费用) 净额;
折旧剔除 = 1602 累计折旧「当期贷方发生额」(博海科目表只到 4 位一级,无费用类折旧叶子;
2026-08 起博海 1602 无计提行,剔除额为 0 —— 见回报件)。
博海明细账的期间损益结转腿(summary='结转期间损溢',账套内 **未** 标 carry_forward=1)
必须显式剔除,否则净额恒 0 会把已结账期间清零(口径见
/srv/hermes/wisdom/_decisions/cma-expense-profit-net-caliber-20261002.md)。
口径(与财务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误含)
- 渠补率: **实测累计口径**(2026-10-02 财务裁定,任总 11:43 CST 放行「改,这样数据更加真实」)
渠补率(实测) = Σ(571103 借方) ÷ Σ(5001 贷方) × 100,期间 = 年初至当期(YTD),保留 2 位小数。
- 销售收入: entity1 = subject_code='5001'(主营业务收入) 贷方合计;entity2 = '6001' 贷方合计。当年1月至目标月 YTD 月均
- 固定成本: entity1 = subject_code LIKE '5602%'(管理费用,含560213折旧) 借−贷净额合计(carry_forward=0),YTD 月均
entity2 = 6601/6602/6603 借−贷净额合计(同上,但另需剔除结转腿)
- 折旧: entity1 = '560213' 借−贷净额;entity2 = '1602' 贷方发生额(现金口径剔除项)
- 变动成本率: **实测累计口径**(2026-10-02 财务裁定,任总 11:43 CST 放行「改,这样数据更加真实」)
酣客 渠补率(实测) = Σ(571103 借方) ÷ Σ(5001 贷方) × 100,期间 = 年初至当期(YTD),保留 2 位小数。
`POLICY_REBATE_RATE_PCT = 84.61` 政策常量**仅作对照展示**(写进返回值 rebate_policy_pct / remark),
**不参与任何计算**;`--rebate-rate` 显式传值时视为人工诊断覆盖(正常调用不再使用)。
- 边际贡献率 = 100 − 渠补率(实测)
- 边际贡献率 = 100 − 变动成本率
- fail-closed 边界(2026-10-02 裁定):某期 571103 或 5001 缺数/为 0 ⇒ **该期不出保本值**
(六条派生行写 actual_value=NULL + data_status='pending' + remark 注明「渠补率不可得」),
(六条派生行写 actual_value=NULL + data_status='pending' + remark 注明「变动成本率不可得」),
**不得静默回落 84.61 常量**;累计口径天然平滑单月波动(8 月单月 571103/5001=134% 不影响累计值)。
- fail-closed 边界 ②(2026-10-03 裁定,本单):**变动成本率 ≥ 100% ⇔ 边际贡献率 ≤ 0 ⇒ 保本点不适用**。
该期 五条保本派生值(REVENUE/COVER/GAP/REVENUE_CASH/COVER_CASH)写 actual_value=NULL +
data_status='pending' + remark 含「边际贡献非正,保本点不适用」,**禁止回落 0.0**
(0.0 会被前端显示成「月保本 0 万、覆盖率 0%」,语义完全错误);变动成本率本身照常落库。
与既有 fail-closed(缺数/为 0)**同一处理路径风格**,仅文案与触发条件不同。
- 目标月: --period 显式指定;默认自动选最近「已结账」完整月(当月跳过)。
结账信号优先:DB 损益结转凭证(carry_forward=1 & subject_code='3103') → check.md 文件;
结账信号优先:DB 损益结转凭证(carry_forward=1 & 本年利润科目 3103(酣客)/4103(博海)) → check.md 文件;
两者皆无时才退回旧「销售额阈值」兜底(销售低 ≠ 未结账,仅保底用,日志标注依据)
- 单位: voucher 金额为元,聚合后 /10000 → 万元
- 幂等: 同 kpi_id+period+source_type='derived' 存在则更新,可安全重跑;
**不降级**(ASK-20260924-10 / 2026-09-24):值未变或值变都不回写 data_status,
保留既有状态(含人工/任总放行的 verified),避免「人工转正 → 次日派生静默打回 pending」。
值变时 remark 留痕并落复核提示件(见 _reports/fullstack-<YYYYMMDD>-bep-value-changed-review.md)。
**例外**:fail-closed 两条路径(不可得 / 边际贡献非正)按裁定显式写 data_status='pending'。
- 只写 source_type='derived' 行;不触碰 auto_collect/manual/excel/ledger 行;不改 collector 逻辑
用法:
venv/bin/python3 scripts/kpi_bep_deriver.py # 自动选目标月
venv/bin/python3 scripts/kpi_bep_deriver.py --period 2026-07 # 指定期间(实跑验证用)
venv/bin/python3 scripts/kpi_bep_deriver.py --entity 2 --period 2026-08 # 博海(新口径)
venv/bin/python3 scripts/kpi_bep_deriver.py --entity 1 --rebate-rate 84.61
venv/bin/python3 scripts/kpi_bep_deriver.py --dry-run # 只计算不落库
"""
@@ -45,7 +64,7 @@ from datetime import datetime, date
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import re
from sqlalchemy import func
from sqlalchemy import func, or_
from app.database import get_session_local
from app.models import KPIValue, KPIDefinition, VoucherDetail, KPIAlert
# 裁定 R1(2026-09-19 财务口径):demo 账套不产生业务预警(派生值仍落库,仅跳过预警同步)
@@ -78,12 +97,23 @@ 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"}
SALES_CODE = "5001" # 主营业务收入
SALES_CODE = "5001" # 主营业务收入(酣客)
ADMIN_PREFIX = "5602" # 管理费用(含折旧叶子560213)
DEP_SUBJECT = "560213" # 管理费用-折旧(现金口径剔除项,eq 精确匹配防 5602130 误含)
REBATE_CODE = "571103" # 渠补/捐赠支出(校验用,不直接进公式)
CARRY_SUBJECT = "3103" # 本年利润(carry_forward=1 且该科目 = 该期损益结转凭证)
# ── 实体口径注册表(2026-10-03)——单一事实源见 app/utils/bep_caliber.py ─────────
# 变动成本率(rate)= numerator ÷ denominator(YTD 累计):
# · 酣客:Σ571103借方(渠补) ÷ Σ5001贷方(收入) —— 2026-10-02 财务裁定;结转账腿已由 carry_forward=1 标识
# · 博海:Σ6401借方(主营业务成本) ÷ Σ6001贷方(收入) —— 2026-10-03 财务裁定「新口径,勿套酣客渠补公式」
# exclude_closing:该账套的「期间损益结转腿」是否需要用 summary 显式剔除
# (博海账套的结转行 carry_forward 仍是 0,不剔除则已结账期间净额恒 0 ⇒ 指标被清零)
# 同表被 backend/app/api/dashboard.py::/bep-card 共用(口径不漂移)。
from app.utils.bep_caliber import ( # noqa: E402 (紧随 sys.path 之后导入)
CLOSING_SUMMARY_LIKE, ENTITY_CALIBERS, caliber_for,
)
# 智享通落盘目录(与 app/api/data.py 的 ZXT_LANDING_DIR 一致)——结账信号次选来源
ZXT_LANDING_DIR = "/root/WB_WS/_data/zxt-hanke"
@@ -152,12 +182,16 @@ def _month_range(period: str):
def _sum_field(db, entity_id: int, period_from: str, period_to: str,
field: str, subject_filter=None) -> float:
field: str, subject_filter=None, *, exclude_closing: bool = False,
subject_filters=None) -> float:
"""聚合 voucher_details 金额(元)。subject_filter: ('eq', code) / ('like', prefix)
field="net" = 借−贷 净额(口径4:费用/损益一律净额)。
⚠️ 净额只在 carry_forward==0 行域成立(含结转腿时损益类净额恒 0)
—— 见 /srv/hermes/wisdom/_decisions/cma-expense-profit-net-caliber-20261002.md。
exclude_closing=True 时再显式剔除「期间损益结转腿」(summary 含「结转」)——
用于结转行未被标 carry_forward=1 的账套(博海),否则净额恒 0 会把已结账期间清零。
subject_filters: [('like','6601'), ('like','6602'), ...] 多科目 OR(与 subject_filter 二选一)
"""
expr = (VoucherDetail.debit_amount - VoucherDetail.credit_amount
if field == "net" else getattr(VoucherDetail, field))
@@ -167,70 +201,105 @@ def _sum_field(db, entity_id: int, period_from: str, period_to: str,
VoucherDetail.period >= period_from,
VoucherDetail.period <= period_to,
)
if explicit := subject_filters:
q = q.filter(or_(*[_subject_clause(k, c) for k, c in explicit]))
if subject_filter:
kind, code = subject_filter
if kind == "eq":
q = q.filter(VoucherDetail.subject_code == code)
elif kind == "like":
q = q.filter(VoucherDetail.subject_code.like(code + "%"))
q = q.filter(_subject_clause(kind, code))
if exclude_closing:
q = q.filter(or_(VoucherDetail.summary.is_(None),
~VoucherDetail.summary.like(CLOSING_SUMMARY_LIKE)))
val = q.scalar()
return float(val or 0.0)
def _subject_clause(kind: str, code: str):
"""科目过滤谓词:('eq', code) 精确 / ('like', prefix) 前缀"""
if kind == "eq":
return VoucherDetail.subject_code == code
if kind == "like":
return VoucherDetail.subject_code.like(code + "%")
raise ValueError(f"未知科目过滤类型: {kind}")
def compute_margin_rate(db, entity_id: int, period_from: str, period_to: str,
caliber: dict = None) -> dict:
"""变动成本率(YTD 累计,2 位小数)—— 按实体口径现算。
· 酣客(entity1):Σ571103借方 ÷ Σ5001贷方(实测渠补率)
· 博海(entity2):Σ6401借方 ÷ Σ6001贷方(主营业务成本率)
返回兼容既有键名:{'available', 'rebate_pct', 'rebate_sum_w', 'sales_sum_w', 'reason'}
(rebate_sum_w = 分子/变动成本,sales_sum_w = 分母/收入基数;供卡面/报告沿用)。
**fail-closed**:分子或分母缺数/为 0 ⇒ available=False, rebate_pct=None
(调用方不得回落政策常量,须按「不可得」处理)。
"""
cal = caliber or ENTITY_CALIBERS[entity_id]
num_raw = _sum_field(db, entity_id, period_from, period_to,
cal["varcost_field"], cal["varcost_filter"],
exclude_closing=cal["exclude_closing"])
den_raw = _sum_field(db, entity_id, period_from, period_to,
cal["revenue_field"], cal["revenue_filter"],
exclude_closing=cal["exclude_closing"])
num_w, den_w = num_raw / 10000.0, den_raw / 10000.0
info = {
"rebate_sum_w": round(num_w, 2),
"sales_sum_w": round(den_w, 2),
"rebate_pct": None,
"available": False,
"reason": "",
"label": cal["margin_label"],
"desc": cal["margin_desc"],
}
if den_w <= 0:
info["reason"] = f"{cal['margin_label']}不可得:{cal['revenue_filter'][1]} 累计缺数或为 0"
return info
if num_w <= 0:
info["reason"] = f"{cal['margin_label']}不可得:{cal['varcost_filter'][1]} 累计缺数或为 0"
return info
info["available"] = True
info["rebate_pct"] = round(num_w / den_w * 100.0, 2)
return info
def compute_rebate_rate(db, entity_id: int, period_from: str, period_to: str) -> dict:
"""实测累计渠补率(2026-10-02 财务裁定口径)。
"""实测累计渠补率(2026-10-02 财务裁定口径)—— 酣客(entity1) 专用薄封装。
渠补率(实测) = Σ(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
(调用方不得回落政策常量,须按「渠补率不可得」处理)。
保留本函数名/键名以兼容既有调用方与单测;通用实现见 compute_margin_rate。
"""
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
return compute_margin_rate(db, entity_id, period_from, period_to,
ENTITY_CALIBERS.get(entity_id))
def _month_sales(db, entity_id: int, period: str) -> float:
"""单月销售收入(万元)——用于目标月完整度判断"""
return _sum_field(db, entity_id, period, period, "credit_amount",
("eq", SALES_CODE)) / 10000.0
def _month_sales(db, entity_id: int, period: str, caliber: dict = None) -> float:
"""单月销售收入(万元)——用于目标月完整度判断(按实体口径的收入科目)"""
cal = caliber or ENTITY_CALIBERS.get(entity_id) or ENTITY_CALIBERS[1]
return _sum_field(db, entity_id, period, period, cal["revenue_field"],
cal["revenue_filter"], exclude_closing=cal["exclude_closing"]) / 10000.0
def _is_period_closed(db, entity_id: int, period: str) -> tuple:
def _is_period_closed(db, entity_id: int, period: str, caliber: dict = None) -> tuple:
"""判断该期间是否已结账(损益结转已完成)。返回 (bool, 依据说明)。
主信号(DB): voucher_details 存在 carry_forward=1 且 subject_code='3103'(本年利润) 的行
= 该期损益结转凭证已生成
次信号(文件): ZXT_LANDING_DIR/{YYYY.MM}/check.md 同时含「本期: PASS」与「损益结转: PASS」
主信号(DB): voucher_details 存在 carry_forward=1 且 subject_code=该账套本年利润科目
(酣客 3103 / 博海 4103)= 该期损益结转凭证已生成
次信号(文件): {landing_dir}/{YYYY.MM}/check.md 同时含「本期: PASS」与「损益结转: PASS」
(仅酣客有智享通落盘目录;博海 landing_dir=None ⇒ 跳过该信号)
均不成立 → (False, "")。任何读取异常均吞掉,不影响主流程。
"""
cal = caliber or ENTITY_CALIBERS.get(entity_id) or ENTITY_CALIBERS[1]
# 主信号:DB 损益结转凭证
try:
hit = db.query(VoucherDetail.id).filter(
VoucherDetail.entity_id == entity_id,
VoucherDetail.carry_forward == 1,
VoucherDetail.subject_code == CARRY_SUBJECT,
VoucherDetail.subject_code == cal["closing_subject"],
VoucherDetail.period == period,
).first()
if hit:
@@ -238,21 +307,23 @@ def _is_period_closed(db, entity_id: int, period: str) -> tuple:
except Exception as e: # 查询异常不阻断,降级到文件信号
logger.warning("结账信号(DB)查询失败 period=%s: %s", period, e)
# 次信号:智享通落盘 check.md
# 次信号:智享通落盘 check.md(仅酣客)
landing = cal.get("landing_dir")
try:
path = os.path.join(ZXT_LANDING_DIR, period.replace("-", "."), "check.md")
if os.path.exists(path):
with open(path, "r", encoding="utf-8") as f:
txt = f.read()
if "本期: PASS" in txt and "损益结转: PASS" in txt:
return True, "check.md"
if landing:
path = os.path.join(landing, period.replace("-", "."), "check.md")
if os.path.exists(path):
with open(path, "r", encoding="utf-8") as f:
txt = f.read()
if "本期: PASS" in txt and "损益结转: PASS" in txt:
return True, "check.md"
except Exception:
pass # 文件缺失/读取失败一律忽略
return False, ""
def _pick_target_period(db, entity_id: int, now: date) -> str:
def _pick_target_period(db, entity_id: int, now: date, caliber: dict = None) -> str:
"""自动选择目标月:跳过当月。
判定顺序(2026-09-12 修订):
@@ -260,6 +331,7 @@ def _pick_target_period(db, entity_id: int, now: date) -> str:
结账成立时不再用销售额做任何筛选(销售低 ≠ 未结账,历史缺陷根因)
2. 所有候选月均无结账信号 → 退回旧「销售额 < 近6月均×30%」兜底(日志标注『依据销售额兜底』)
"""
cal = caliber or ENTITY_CALIBERS.get(entity_id) or ENTITY_CALIBERS[1]
# 收集已有数据月份(5001 贷方)
rows = db.query(VoucherDetail.period).filter(
VoucherDetail.entity_id == entity_id,
@@ -280,7 +352,7 @@ def _pick_target_period(db, entity_id: int, now: date) -> str:
# 1) 结账信号优先(DB损益结转 → check.md),命中即采用
for p in candidates:
closed, reason = _is_period_closed(db, entity_id, p)
closed, reason = _is_period_closed(db, entity_id, p, cal)
if closed:
logger.info("目标月 %s 判定已结账(依据:%s),采用", p, reason)
return p
@@ -294,14 +366,14 @@ def _pick_target_period(db, entity_id: int, now: date) -> str:
for p in periods:
if p >= cur:
continue
s = _month_sales(db, entity_id, p)
s = _month_sales(db, entity_id, p, cal)
ref_months.append((p, s))
if len(ref_months) >= 6:
break
ref_avg = (sum(s for _, s in ref_months) / len(ref_months)) if ref_months else None
for p in candidates:
s = _month_sales(db, entity_id, p)
s = _month_sales(db, entity_id, p, cal)
if s <= 0:
continue # 该月无销售,往前找
if ref_avg and s < ref_avg * 0.3:
@@ -339,13 +411,20 @@ def _eval_static_threshold(value: float, kpi) -> tuple:
def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float = None,
write_kpi: bool = True) -> dict:
"""计算并落库六个派生KPI(账面3条+现金2条+实测渠补率1条)。返回结果摘要。
"""计算并落库六个派生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)。
实体口径见 ENTITY_CALIBERS(entity1 酣客=渠补率;entity2 博海=主营业务成本率)。
变动成本率(2026-10-02 裁定):默认按 YTD 从 voucher_details **现算**,
政策常量 84.61% 仅作对照返回(rebate_policy_pct,仅 entity1 有对照物)。
显式传 rebate_rate_pct(`--rebate-rate`)时视为人工诊断覆盖(仅 entity1 语境)。
fail-closed ①:变动成本率不可得且无人工覆盖 ⇒ 该期不出保本值(六行 pending/NULL)。
fail-closed ②(2026-10-03):变动成本率 ≥100%(边际贡献率 ≤0)⇒ 五条保本值 NULL +
remark「边际贡献非正,保本点不适用」,**禁写 0.0**。
"""
cal = ENTITY_CALIBERS.get(entity_id)
if cal is None:
raise RuntimeError(f"entity={entity_id} 未注册 BEP 口径(见 ENTITY_CALIBERS)")
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]),
@@ -355,48 +434,77 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float = None,
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)
# 变动成本率定义缺失不阻断保本主流程(部署顺序容错),但必须显式告警:
# 卡面此时取不到 rebate_pct(单一事实源缺失),需尽快补 bep_kpi_defs*/rebate 种子 SQL。
logger.error("entity=%s 缺少 %s 定义(见 scripts/sql/bep_kpi_defs*.sql);"
"本期跳过变动成本率落库,卡面将判「不可得」", entity_id, REBATE_KPI)
year = period[:4]
period_from = f"{year}-01"
period_to = period
months = int(period[5:7]) # YTD 月数(1月=1 ... 7月=7)
# 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
dep_sum_w = _sum_field(db, entity_id, period_from, period_to, "net", ("eq", DEP_SUBJECT)) / 10000.0
# 1. 取数(元 → 万元)——按实体口径
sales_sum_w = _sum_field(db, entity_id, period_from, period_to,
cal["revenue_field"], cal["revenue_filter"],
exclude_closing=cal["exclude_closing"]) / 10000.0
admin_sum_w = _sum_field(db, entity_id, period_from, period_to, "net",
subject_filters=cal["fixed_filters"],
exclude_closing=cal["exclude_closing"]) / 10000.0
dep_sum_w = _sum_field(db, entity_id, period_from, period_to,
cal["dep_field"], cal["dep_filter"],
exclude_closing=cal["exclude_closing"]) / 10000.0
sales_avg = sales_sum_w / months
admin_avg = admin_sum_w / months
dep_avg = dep_sum_w / months
cash_admin_avg = admin_avg - dep_avg # 现金口径固定成本(剔除折旧纸面费用)
# 2. 渠补率:默认逐期实测累计(不再取政策常量;常量仅对照)
rebate_info = compute_rebate_rate(db, entity_id, period_from, period_to)
# 2. 变动成本率:默认逐期实测累计(不再取政策常量;常量仅对照,仅 entity1 有)
rebate_info = compute_margin_rate(db, entity_id, period_from, period_to, cal)
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,
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)
return _fail_closed_rebate_unavailable(db, entity_id, period, months, rebate_info, cal,
kpis, write_kpi)
rebate_pct = rebate_info["rebate_pct"]
cm_pct = 100.0 - rebate_pct # 边际贡献率(%) = 100 − 实测渠补率
cm_pct = 100.0 - rebate_pct # 边际贡献率(%) = 100 − 变动成本率
# 2b. fail-closed ②(2026-10-03):边际贡献率 ≤ 0 ⇒ 保本点不适用(禁写 0.0)
if cm_pct <= 0:
logger.error("period=%s %s=%.2f%% ≥100%% ⇒ 边际贡献非正,保本点不适用(fail-closed,禁写 0.0)",
period, cal["margin_label"], rebate_pct)
return _fail_closed_cm_non_positive(db, entity_id, period, months, rebate_info, cal,
kpis, write_kpi, sales_avg=sales_avg,
admin_avg=admin_avg, dep_avg=dep_avg)
# 2c. fail-closed ③(2026-10-03,同族补充):固定成本退化 ⇒ 保本点不适用
# 边际贡献率 > 0 但分子(固定成本)退化时,公式给出 保本额≈0 / 覆盖率趋于无穷,
# 与 0.0 兜底同属「语义崩溃」类(实测:博海 2026-01 账面净固定成本月均 0.01万≈0、
# 现金固定成本月均 −0.14万 ⇒ 公式值 保本 0.1万 / 覆盖率 175981% / 现金保本 −2.3万)。
# 判据(同族、无新增经验常量):月均账面固定成本 ≤ 0 **或** 月均现金固定成本 ≤ 0。
if admin_avg <= 0 or cash_admin_avg <= 0:
logger.error("period=%s %s月均=%.2f万、现金固定成本月均=%.2f万(含折旧月均%.2f万)"
"⇒ 固定成本退化,保本点不适用(fail-closed)",
period, cal["fixed_label"], admin_avg, cash_admin_avg, dep_avg)
return _fail_closed_cm_non_positive(db, entity_id, period, months, rebate_info, cal,
kpis, write_kpi, sales_avg=sales_avg,
admin_avg=admin_avg, dep_avg=dep_avg, guard="fixed",
cash_admin_avg=cash_admin_avg)
# 3. 派生计算(万元 / %)——账面3条路径不变;现金口径在账面基础上剔除折旧
bep = admin_avg / (cm_pct / 100.0) if cm_pct > 0 else 0.0
bep = admin_avg / (cm_pct / 100.0)
cover = (sales_avg / bep * 100.0) if bep > 0 else 0.0
gap = ((bep - sales_avg) / bep * 100.0) if bep > 0 else 0.0
cash_bep = cash_admin_avg / (cm_pct / 100.0) if cm_pct > 0 else 0.0
cash_bep = cash_admin_avg / (cm_pct / 100.0)
cash_cover = (sales_avg / cash_bep * 100.0) if cash_bep > 0 else 0.0
values = {
@@ -419,16 +527,30 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float = None,
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}% 仅供对照,不参与计算)")
if entity_id == 1:
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}% 仅供对照,不参与计算)")
else:
remark = (f"{cal['margin_label']}(YTD累计): {cal['margin_desc']} = "
f"{rebate_info['rebate_sum_w']:.2f}万 ÷ {rebate_info['sales_sum_w']:.2f}万 "
f"× 100 = {rebate_pct:.2f}%({cal['name']}口径,无渠补科目)")
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"(实测渠补率{rebate_pct:.2f}%)")
if entity_id == 1:
remark = (f"现金口径: 管理费月均{admin_avg:.2f}万-折旧月均{dep_avg:.2f}万"
f"=固定现金{cash_admin_avg:.2f}万 ÷ 边际贡献率{cm_pct:.2f}% → 保本{cash_bep:.2f}万"
f"(实测渠补率{rebate_pct:.2f}%)")
else:
remark = (f"现金口径: {cal['fixed_label']}月均{admin_avg:.2f}万-折旧月均{dep_avg:.2f}万"
f"=固定现金{cash_admin_avg:.2f}万 ÷ 边际贡献率{cm_pct:.2f}% → 保本{cash_bep:.2f}万"
f"({cal['margin_label']}{rebate_pct:.2f}%)")
else:
remark = (f"保本派生器: 销售月均{sales_avg:.1f}万/管理费月均{admin_avg:.1f}万/"
f"实测渠补率{rebate_pct:.2f}%(政策{POLICY_REBATE_RATE_PCT:.2f}%仅对照)")
if entity_id == 1:
remark = (f"保本派生器: 销售月均{sales_avg:.1f}万/管理费月均{admin_avg:.1f}万/"
f"实测渠补率{rebate_pct:.2f}%(政策{POLICY_REBATE_RATE_PCT:.2f}%仅对照)")
else:
remark = (f"保本派生器: 销售月均{sales_avg:.1f}万/{cal['fixed_label']}月均{admin_avg:.1f}万/"
f"{cal['margin_label']}{rebate_pct:.2f}%")
existing = db.query(KPIValue).filter(
KPIValue.kpi_id == kpi.id,
KPIValue.period == period,
@@ -540,18 +662,22 @@ def run_derive(db, entity_id: int, period: str, rebate_rate_pct: float = None,
def _fail_closed_rebate_unavailable(db, entity_id: int, period: str, months: int,
rebate_info: dict, kpis: dict,
rebate_info: dict, cal: dict, kpis: dict,
write_kpi: bool) -> dict:
"""fail-closed 落库:实测渠补率不可得 ⇒ 该期不出保本值。
"""fail-closed 落库:变动成本率不可得 ⇒ 该期不出保本值。
六条派生行写 actual_value=NULL + data_status='pending' + remark 注明「渠补率不可得」,
六条派生行写 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}%)")
reason = rebate_info["reason"] or f"{cal['margin_label']}不可得"
if entity_id == 1:
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}%)")
else:
detail = (f"{reason};{cal['margin_desc']} = {rebate_info['rebate_sum_w']:.2f}万 / "
f"{rebate_info['sales_sum_w']:.2f}万 ⇒ 本期不出保本值(fail-closed,禁回落、禁跨期)")
batch = f"bep-{datetime.now().strftime('%Y%m%d%H%M%S')}"
written = {}
if write_kpi:
@@ -604,39 +730,150 @@ def _fail_closed_rebate_unavailable(db, entity_id: int, period: str, months: int
}
def _fail_closed_cm_non_positive(db, entity_id: int, period: str, months: int,
rebate_info: dict, cal: dict, kpis: dict, write_kpi: bool,
sales_avg: float = None, admin_avg: float = None,
dep_avg: float = None, guard: str = "cm",
cash_admin_avg: float = None) -> dict:
"""fail-closed ② 落库:保本点**不适用**(2026-10-03 财务裁定)。
五条保本派生值(REVENUE/COVER/GAP/REVENUE_CASH/COVER_CASH)写
actual_value=NULL + data_status='pending' + remark 含「保本点不适用」,
**禁止回落 0.0**(0.0 会被前端显示成「月保本 0 万、覆盖率 0%」,语义完全错误)。
变动成本率本身是可测量的 ⇒ 该 KPI 照常落库(值 + YTD 累计 remark)。
不评估阈值、不产生/解除预警(保本值无值 ⇒ 无级别可评)。
guard 触发条件(同族,均属「公式退化」):
· 'cm' 边际贡献率 ≤ 0(变动成本率 ≥ 100%)——本单裁定 ①
· 'fixed' 月均账面固定成本 ≤ 0 ——同族补充③(分子非正 ⇒ 保本额≈0、覆盖率趋于无穷)
"""
rebate_pct = rebate_info["rebate_pct"]
cm_pct = round(100.0 - float(rebate_pct), 2)
if guard == "fixed":
detail = (f"保本点不适用(固定成本退化:{cal['fixed_label']}月均 {admin_avg:.2f}万 ≤ 0 或 "
f"现金固定成本月均 {cash_admin_avg:.2f}万 ≤ 0 ⇒ 分子退化,保本额≈0、覆盖率无意义;"
f"{cal['margin_label']} {rebate_pct:.2f}%、边际贡献率 {cm_pct:.2f}%;"
f"fail-closed,禁写 0.0)")
else:
detail = (f"边际贡献非正,保本点不适用({cal['margin_label']} {rebate_pct:.2f}% ≥ 100%,"
f"边际贡献率 {cm_pct:.2f}% ⇒ 每增一元销售不产生正贡献,保本点无经济意义;"
f"fail-closed,禁写 0.0)")
if entity_id == 1:
rebate_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}% 仅供对照,不参与计算)")
else:
rebate_remark = (f"{cal['margin_label']}(YTD累计): {cal['margin_desc']} = "
f"{rebate_info['rebate_sum_w']:.2f}万 ÷ {rebate_info['sales_sum_w']:.2f}万 "
f"× 100 = {rebate_pct:.2f}%({cal['name']}口径,无渠补科目)")
batch = f"bep-{datetime.now().strftime('%Y%m%d%H%M%S')}"
written = {}
changed = []
if write_kpi:
for code, _ in TARGET_KPIS:
kpi = kpis.get(code)
if kpi is None:
written[code] = "no-definition"
continue
is_rebate = (code == REBATE_KPI)
new_val = round(float(rebate_pct), 2) if is_rebate else None
rm = rebate_remark if is_rebate else detail
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=new_val,
source_type="derived",
source_batch=batch,
data_status="pending",
remark=rm,
))
written[code] = "insert"
else:
old_value = float(existing.actual_value) if existing.actual_value is not None else None
value_changed = ((old_value is None) != (new_val is None)
or (old_value is not None and abs(old_value - float(new_val)) > 1e-9))
existing.actual_value = new_val
existing.source_batch = batch
existing.data_status = "pending" # 裁定:fail-closed 路径显式 pending
existing.remark = rm
if value_changed:
changed.append({"code": code, "old": old_value, "new": new_val,
"status": "pending"})
written[code] = "upsert"
db.commit()
_write_value_changed_note(entity_id, period, batch, changed)
else:
written = {c: "dry-run" for c, _ in TARGET_KPIS}
return {
"entity_id": entity_id,
"period": period,
"months": months,
"data_status": "pending",
"cm_non_positive": True,
"reason": detail,
"rebate_sum_w": rebate_info["rebate_sum_w"],
"sales_sum_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 cal["margin_desc"],
"cm_pct": cm_pct,
"sales_avg": round(sales_avg, 2) if sales_avg is not None else None,
"admin_avg": round(admin_avg, 2) if admin_avg is not None else None,
"dep_avg": round(dep_avg, 2) if dep_avg is not None else None,
"values": {},
"written": written,
"value_changed": 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("--entity", type=int, default=1, help="entity_id(1=陕西酣客 2=博海)")
ap.add_argument("--rebate-rate", type=float, default=None,
help="渠补率%%人工覆盖(诊断用;**默认按 YTD 从 voucher_details 实测现算**,不再取政策常量)")
help="变动成本率%%人工覆盖(诊断用;**默认按 YTD 从 voucher_details 实测现算**,不再取政策常量)")
ap.add_argument("--dry-run", action="store_true", help="只计算不落库")
args = ap.parse_args()
db = get_session_local()()
try:
period = args.period or _pick_target_period(db, args.entity, date.today())
cal = ENTITY_CALIBERS.get(args.entity)
if cal is None:
print(f"❌ entity={args.entity} 未注册 BEP 口径(见 ENTITY_CALIBERS)")
return 2
period = args.period or _pick_target_period(db, args.entity, date.today(), cal)
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']} "
print(f"保本点派生计算完成 entity={r['entity_id']}({cal['name']}) period={r['period']} "
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']}")
kind = "边际贡献非正 ⇒ 保本点不适用" if r.get("cm_non_positive") else "不可得"
print(f" ⚠ fail-closed({kind}):{r['reason']}")
if r.get("rebate_actual_pct") is not None:
print(f" {cal['margin_label']}(YTD) = {r['rebate_actual_pct']:.2f}% "
f"| 边际贡献率 {r.get('cm_pct')}% ⇒ 仅落变动成本率,五条保本值 NULL")
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}万 | 实测渠补率(YTD) {r['rebate_actual_pct']:.2f}% "
f"| 政策常量 {r['rebate_policy_pct']:.2f}% (仅对照) | 边际贡献率 {r['cm_pct']:.2f}%")
print(f" 固定成本累计 {r['admin_sum_w']:.2f}万 月均 {r['admin_avg']:.2f}万 ({cal['fixed_label']},账面口径)")
print(f" 折旧累计 {r['dep_sum_w']:.2f}万 月均 {r['dep_avg']:.2f}万 ({cal['dep_filter'][1]}) | "
f"现金固定成本月均 {r['cash_admin_avg']:.2f}万 (固定成本-折旧)")
print(f" 变动成本累计 {r['rebate_sum_w']:.2f}万 | {cal['margin_label']}(YTD) {r['rebate_actual_pct']:.2f}% "
f"({cal['margin_desc']}) | 边际贡献率 {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" F_BEP_REBATE {cal['margin_label']} = {r['values']['F_BEP_REBATE']} %")
print(f" 落库: {r['written']}")
finally:
db.close()
@@ -0,0 +1,86 @@
-- CMA BEP(保本点) 派生KPI定义 — 博海 entity_id=2 — cma-bep-kpi-20261003
-- 任务: finance-20261003-cvp-fix-and-bohai-coverage-fullstack.md(放行出处 任总 2026-10-03 11:07/11:13 CST DM)
-- 口径(博海新口径,勿套酣客渠补公式):
-- 变动成本率 = Σ6401借方 ÷ Σ6001贷方(主营业务成本率;博海无渠补科目571103)
-- 固定成本 = (6601销售费用 + 6602管理费用 + 6603财务费用) 借−贷净额月均
-- 折旧剔除 = 1602 累计折旧「当期贷方发生额」(现金口径;博海科目表只到4位一级,无费用类折旧叶子)
-- 剔除期间损益结转腿(summary LIKE '%结转%'):博海该账套 carry_forward 恒 0,不剔除则已结账月份净额恒 0
-- 单位/阈值与 entity 1 保持一致;仅新增,幂等(NOT EXISTS 守卫),不触碰 entity 1 定义
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 2, 'F_BEP_REVENUE', '保本销售额', 'finance', 'profitability',
'round(月固定成本(万元) / (1 - 变动成本率), 1)',
'账面口径=月固定成本((6601+6602+6603)借−贷净额月均, 剔除结转账腿)÷边际贡献率(1-变动成本率); 中性参考值, 越高需更多销售覆盖',
'derived', 'BEP派生器 kpi_bep_deriver.py(voucher_details 6601/6602/6603 月均)', '财务部', 'monthly', '万元', 0,
'ratio', NULL, NULL, NULL,
'strategic', 'active', 'finance-bot', 'Epic2', 1
WHERE NOT EXISTS (SELECT 1 FROM kpi_definitions WHERE entity_id=2 AND kpi_code='F_BEP_REVENUE');
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 2, 'F_BEP_COVER', '保本覆盖率', 'finance', 'profitability',
'round(实际月销/保本销售额*100,1)',
'实际月销(6001贷方月均,剔除结转账腿)÷保本销售额; 正向指标: >=100绿 >=85黄 <85红',
'derived', 'BEP派生器 kpi_bep_deriver.py(voucher_details 6001月均)', '财务部', 'monthly', '%', 100,
'ratio', '>=100', '>=85', '<85',
'strategic', 'active', 'finance-bot', 'Epic2', 1
WHERE NOT EXISTS (SELECT 1 FROM kpi_definitions WHERE entity_id=2 AND kpi_code='F_BEP_COVER');
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 2, 'F_BEP_GAP', '保本缺口', 'finance', 'profitability',
'round((保本销售额-实际月销)/保本销售额*100,1)',
'反向指标(缺口越小越好): <=0绿(已保本) <=15黄 >15红',
'derived', 'BEP派生器 kpi_bep_deriver.py(voucher_details 6001月均)', '财务部', 'monthly', '%', 0,
'ratio', '<=0', '<=15', '>15',
'strategic', 'active', 'finance-bot', 'Epic2', 1
WHERE NOT EXISTS (SELECT 1 FROM kpi_definitions WHERE entity_id=2 AND kpi_code='F_BEP_GAP');
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 2, 'F_BEP_REVENUE_CASH', '现金口径保本销售额', 'finance', 'profitability',
'round((月固定成本月均-月折旧月均)/(1-变动成本率),1)',
'现金口径=月固定成本(6601+6602+6603 净额月均, 剔除折旧1602当期贷方发生额)÷边际贡献率; 中性参考值, 无阈值',
'derived', 'BEP派生器 kpi_bep_deriver.py(voucher_details 6601/6602/6603/1602月均)', '财务部', 'monthly', '万元', 0,
'ratio', NULL, NULL, NULL,
'strategic', 'active', 'finance-bot', 'Epic2', 1
WHERE NOT EXISTS (SELECT 1 FROM kpi_definitions WHERE entity_id=2 AND kpi_code='F_BEP_REVENUE_CASH');
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 2, 'F_BEP_COVER_CASH', '现金口径保本覆盖率', 'finance', 'profitability',
'round(实际月销/现金口径保本额*100,1)',
'实际月销(6001贷方月均)÷现金口径保本额; 正向指标: >=100绿 >=85黄 <85红',
'derived', 'BEP派生器 kpi_bep_deriver.py(voucher_details 6001/6601/6602/6603/1602月均)', '财务部', 'monthly', '%', 100,
'ratio', '>=100', '>=85', '<85',
'strategic', 'active', 'finance-bot', 'Epic2', 1
WHERE NOT EXISTS (SELECT 1 FROM kpi_definitions WHERE entity_id=2 AND kpi_code='F_BEP_COVER_CASH');
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 2, 'F_BEP_REBATE', '变动成本率(主营业务成本率)', 'finance', 'profitability',
'round(sum(6401借方)/sum(6001贷方)*100,2)',
'变动成本率(实测,YTD累计)=Σ6401借方÷Σ6001贷方(剔结转账腿); 博海无渠补科目571103, 故不套酣客渠补公式; 供保本点卡面单一事实源, 无阈值',
'derived', 'BEP派生器 kpi_bep_deriver.py(voucher_details 6401/6001 累计)', '财务部', 'monthly', '%', 0,
'ratio', NULL, NULL, NULL,
'strategic', 'active', 'finance-bot', 'Epic2', 1
WHERE NOT EXISTS (SELECT 1 FROM kpi_definitions WHERE entity_id=2 AND kpi_code='F_BEP_REBATE');