feat: 预算系统6项技术改进（告警归因/实际值自动归集/真零基/派生规则/告警路径统一/现金流分类）
P1-③ 告警归因: budget_deviation_alerts+alert_type/attribution/scenario_id, 归因引擎alert_attribution.py(子KPI/科目/量价差/趋势), deviation-check统一写归因+场景, GET /deviation-alerts/{id}/attribution详情(旧告警现场组装)
P1-④ 实际值自动归集: kpi_value_sources/kpi_value_collect_logs表+CRUD+试跑+覆盖率, 采集器kpi_value_collector.py(voucher_details/进销存/cash_plans按entity+period汇总, 幂等upsert不覆盖人工), crontab每日06:30
P2-① 真零基: budget_zero_based_items逐项论证表+generate, method-comparison有论证项逐项求和is_demo=false否则fallback
P2-② 派生规则: budget_derivation_rules配置表, apply-method优先读规则rule_source=configured
P2-⑤ 告警双路径合并: deviation_engine.build_deviation_alert统一函数, 方向列表配置化kpi_alert_higher_better+alert-direction接口
P2-⑥ 现金流分类: cash_plan_classify_rules规则表+cash_plan_unclassified待分类队列, sync-cash-plans未命中进队列不静默跳过
新增: GET /kpis/{kpi_id}/values + 前端kpiApi.values(归集标签页数据源), scenario_suggestions幂等seed(init_db)
测试: test_budget_tech_improve.py 15用例, 预算相关96 passed, 全量646 passed
This commit is contained in:
Hermes CI Fix
@@ -8,15 +8,40 @@
|
||||
4. 差异预警触发（集成到现有预警系统）
|
||||
"""
|
||||
import logging
|
||||
import json
|
||||
from datetime import datetime
|
||||
from typing import Optional
|
||||
|
||||
from app.database import get_session_local
|
||||
from app.models import KPIDefinition, KPIValue, KPIAlert, BudgetPlan
|
||||
from app.models import KPIDefinition, KPIValue, KPIAlert, BudgetPlan, SystemConfig
|
||||
|
||||
logger = logging.getLogger("cma.deviation")
|
||||
|
||||
|
||||
# 越高越好型KPI默认列表（P2-⑤ 2026-08-28: 提为 system_configs 可配置）
|
||||
DEFAULT_HIGHER_BETTER = [
|
||||
"SALES_TOTAL", "CUSTOMER_COUNT", "SALES_PROFIT_RATE",
|
||||
"RECEIVABLE_TURNOVER", "TURNOVER_RATE",
|
||||
"CUSTOMER_SATISFACTION", "ORDER_DELIVERY_RATE",
|
||||
]
|
||||
CONFIG_KEY_HIGHER_BETTER = "kpi_alert_higher_better"
|
||||
|
||||
|
||||
def get_higher_better_codes(db, entity_id: int = None) -> list:
|
||||
"""读取越高越好型KPI编码列表（system_configs 可维护，无配置回落默认）"""
|
||||
cfg = db.query(SystemConfig).filter(
|
||||
SystemConfig.config_key == CONFIG_KEY_HIGHER_BETTER
|
||||
).first()
|
||||
if cfg and cfg.config_value:
|
||||
try:
|
||||
codes = json.loads(cfg.config_value)
|
||||
if isinstance(codes, list):
|
||||
return [str(c) for c in codes]
|
||||
except Exception:
|
||||
logger.warning("system_configs[%s] 解析失败, 回落默认", CONFIG_KEY_HIGHER_BETTER)
|
||||
return list(DEFAULT_HIGHER_BETTER)
|
||||
|
||||
|
||||
# ============================================================
|
||||
# 差异计算
|
||||
# ============================================================
|
||||
@@ -210,8 +235,83 @@ def check_trend_anomaly(db, kpi_id: int, period: str, consecutive: int = 3) -> d
|
||||
# 差异预警触发
|
||||
# ============================================================
|
||||
|
||||
def build_deviation_alert(db, kpi, period: str, entity_id: int = 1, min_rate: float = 10.0) -> dict:
|
||||
"""统一告警构建 — 双出口共享一套逻辑 (P2-⑤ 2026-08-28)
|
||||
|
||||
预算告警(budget_deviation_alerts) 与 KPIAlert 都调用本函数，差异仅级别映射：
|
||||
- budget 出口: warning/critical @ 20/50
|
||||
- KPIAlert 出口: yellow/red @ 10/30
|
||||
归因(P1-③): attribution 拆解 + 场景建议 由 alert_attribution 组装。
|
||||
|
||||
返回:
|
||||
triggered: bool 是否触发
|
||||
level: budget出口级别 warning/critical
|
||||
kpi_alert_level: KPIAlert出口级别 yellow/red
|
||||
deviation: calc_period_deviation 结果
|
||||
suggestion: 模板建议文案
|
||||
alert_type: 归因场景类型
|
||||
attribution: 归因JSON dict
|
||||
scenario_id: 场景建议ID
|
||||
"""
|
||||
from app.utils.alert_attribution import build_attribution, match_scenario
|
||||
|
||||
deviation = calc_period_deviation(db, kpi.id, period)
|
||||
if deviation.get("deviation_rate") is None:
|
||||
return {"triggered": False}
|
||||
|
||||
rate = abs(deviation["deviation_rate"])
|
||||
actual = deviation.get("actual_value")
|
||||
budget = deviation.get("budget_value")
|
||||
|
||||
# 方向性：越高越好型（配置化，system_configs.kpi_alert_higher_better）
|
||||
higher_better = kpi.kpi_code in get_higher_better_codes(db, entity_id)
|
||||
|
||||
if higher_better:
|
||||
# 实际低于预算才是问题
|
||||
if not (actual is not None and budget is not None and actual < budget and rate >= min_rate):
|
||||
return {"triggered": False}
|
||||
suggestion = (
|
||||
f"实际值低于预算 {rate}%，建议分析业务量未达预期的原因（子KPI拆解见归因），"
|
||||
f"制定增量获客或转化提升计划"
|
||||
)
|
||||
else:
|
||||
# 实际高于预算才是问题（成本型）
|
||||
if not (actual is not None and budget is not None and actual > budget and rate >= min_rate):
|
||||
return {"triggered": False}
|
||||
suggestion = (
|
||||
f"实际值超出预算 {rate}%，建议核查超支原因（科目明细拆解见归因）并采取控制措施"
|
||||
)
|
||||
|
||||
# 级别映射（双出口）
|
||||
budget_level = "critical" if rate > 50 else "warning"
|
||||
kpi_alert_level = "red" if rate >= 30 else "yellow"
|
||||
|
||||
# 归因组装 (P1-③)
|
||||
alert_type = None
|
||||
attribution = None
|
||||
scenario_id = None
|
||||
try:
|
||||
attribution, alert_type = build_attribution(db, kpi.id, period)
|
||||
scenario = match_scenario(db, alert_type)
|
||||
if scenario:
|
||||
scenario_id = scenario["scenario_id"]
|
||||
except Exception as e: # 归因失败不阻断告警主流程
|
||||
logger.warning("归因组装失败 kpi=%s: %s", kpi.kpi_code, e)
|
||||
|
||||
return {
|
||||
"triggered": True,
|
||||
"level": budget_level,
|
||||
"kpi_alert_level": kpi_alert_level,
|
||||
"deviation": deviation,
|
||||
"suggestion": suggestion,
|
||||
"alert_type": alert_type,
|
||||
"attribution": attribution,
|
||||
"scenario_id": scenario_id,
|
||||
}
|
||||
|
||||
|
||||
def run_deviation_check(db_session, period: str = None) -> int:
|
||||
"""运行差异预警检查，返回新增预警数"""
|
||||
"""运行差异预警检查，返回新增预警数（统一走 build_deviation_alert，P2-⑤）"""
|
||||
if period is None:
|
||||
period = datetime.now().strftime("%Y-%m")
|
||||
|
||||
@@ -221,33 +321,10 @@ def run_deviation_check(db_session, period: str = None) -> int:
|
||||
|
||||
new_count = 0
|
||||
for kpi in kpis:
|
||||
# 1. 差异预警：实际 vs 预算
|
||||
deviation = calc_period_deviation(db_session, kpi.id, period)
|
||||
if deviation.get("deviation_rate") is not None:
|
||||
rate = abs(deviation["deviation_rate"])
|
||||
|
||||
# 差异化阈值：越高越好型 vs 越低越好型
|
||||
higher_better = kpi.kpi_code in [
|
||||
"SALES_TOTAL", "CUSTOMER_COUNT", "SALES_PROFIT_RATE",
|
||||
"RECEIVABLE_TURNOVER", "TURNOVER_RATE",
|
||||
"CUSTOMER_SATISFACTION", "ORDER_DELIVERY_RATE",
|
||||
]
|
||||
|
||||
if higher_better:
|
||||
# 实际低于预算才是问题
|
||||
if deviation["actual_value"] < deviation["budget_value"] and rate >= 10:
|
||||
level = "yellow" if rate >= 10 else "green"
|
||||
level = "red" if rate >= 30 else level
|
||||
else:
|
||||
continue
|
||||
else:
|
||||
# 实际高于预算才是问题（成本型）
|
||||
if deviation["actual_value"] > deviation["budget_value"] and rate >= 10:
|
||||
level = "yellow" if rate >= 10 else "green"
|
||||
level = "red" if rate >= 30 else level
|
||||
else:
|
||||
continue
|
||||
|
||||
# 1. 差异预警：实际 vs 预算（统一逻辑）
|
||||
result = build_deviation_alert(db_session, kpi, period)
|
||||
if result["triggered"]:
|
||||
deviation = result["deviation"]
|
||||
alert_msg = (
|
||||
f"{kpi.kpi_name}[{period}] 差异预警: 实际{deviation['actual_value']} "
|
||||
f"vs 预算{deviation['budget_value']}，"
|
||||
@@ -265,13 +342,15 @@ def run_deviation_check(db_session, period: str = None) -> int:
|
||||
if not existing:
|
||||
alert = KPIAlert(
|
||||
kpi_id=kpi.id,
|
||||
alert_level=level,
|
||||
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" 新增差异预警 [{level}] {kpi.kpi_name}: 差异率{deviation['deviation_rate']}%")
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user