"""差异预警引擎 — 管理会计OS 实际 vs 预算/目标对比,超阈值自动推送预警 功能: 1. 实际 vs 预算差异计算(差异额/差异率) 2. 同比/环比差异计算 3. 趋势异常检测(连续N期下滑/上升) 4. 差异预警触发(集成到现有预警系统) """ import logging from datetime import datetime from typing import Optional from app.database import get_session_local from app.models import KPIDefinition, KPIValue, KPIAlert, BudgetPlan logger = logging.getLogger("cma.deviation") # ============================================================ # 差异计算 # ============================================================ def calc_deviation(actual: float, budget: float) -> dict: """计算差异额和差异率""" if budget is None or budget == 0: return { "deviation_amount": None, "deviation_rate": None, "is_over_budget": None, } amount = round(actual - budget, 2) rate = round(amount / budget * 100, 2) return { "deviation_amount": amount, "deviation_rate": rate, "is_over_budget": amount > 0, } def get_budget_for_kpi(db, kpi_id: int, period: str, version: str = None) -> Optional[float]: """获取指定KPI在指定期间的预算值""" query = db.query(BudgetPlan).filter( BudgetPlan.kpi_id == kpi_id, BudgetPlan.period == period, BudgetPlan.status == "active", ) if version: query = query.filter(BudgetPlan.version == version) plan = query.order_by(BudgetPlan.updated_at.desc()).first() return plan.budget_value if plan else None def get_actual_for_kpi(db, kpi_id: int, period: str) -> Optional[float]: """获取指定KPI在指定期间的实际值""" val = db.query(KPIValue).filter( KPIValue.kpi_id == kpi_id, KPIValue.period == period, ).order_by(KPIValue.calculated_at.desc()).first() return val.actual_value if val else None def calc_period_deviation(db, kpi_id: int, period: str) -> dict: """单KPI单期的差异计算""" actual = get_actual_for_kpi(db, kpi_id, period) budget = get_budget_for_kpi(db, kpi_id, period) kpi = db.query(KPIDefinition).filter(KPIDefinition.id == kpi_id).first() kpi_code = kpi.kpi_code if kpi else "unknown" # 如果没预算值,用 target_value 作为替代 if budget is None and kpi: # 尝试把年度目标按月均分 month = int(period.split("-")[1]) target = kpi.target_value if target and target > 0 and kpi.frequency == "monthly": budget = round(target / 12, 2) deviation = calc_deviation(actual, budget) if actual is not None else None result = { "kpi_id": kpi_id, "kpi_code": kpi_code, "period": period, "actual_value": actual, "budget_value": budget, } if deviation: result.update(deviation) return result # ============================================================ # 同比/环比差异 # ============================================================ def calc_period_diff(db, kpi_id: int, current_period: str, diff_type: str = "yoy") -> dict: """计算同比(上年同期)或环比(上期)差异""" year, month = current_period.split("-") y, m = int(year), int(month) if diff_type == "yoy": # 同比:上年同期 prev_period = f"{y-1}-{m:02d}" label = "同比" elif diff_type == "mom": # 环比:上个月 prev_m = m - 1 prev_y = y if prev_m <= 0: prev_m += 12 prev_y -= 1 prev_period = f"{prev_y}-{prev_m:02d}" label = "环比" else: return {"error": f"未知比较类型: {diff_type}"} current = get_actual_for_kpi(db, kpi_id, current_period) previous = get_actual_for_kpi(db, kpi_id, prev_period) kpi = db.query(KPIDefinition).filter(KPIDefinition.id == kpi_id).first() kpi_code = kpi.kpi_code if kpi else "unknown" if current is None or previous is None or previous == 0: return { "kpi_id": kpi_id, "kpi_code": kpi_code, "type": diff_type, "label": label, "current_period": current_period, "prev_period": prev_period, "current_value": current, "prev_value": previous, "diff_amount": None, "diff_rate": None, } diff_amount = round(current - previous, 2) diff_rate = round(diff_amount / previous * 100, 2) return { "kpi_id": kpi_id, "kpi_code": kpi_code, "type": diff_type, "label": label, "current_period": current_period, "prev_period": prev_period, "current_value": current, "prev_value": previous, "diff_amount": diff_amount, "diff_rate": diff_rate, } # ============================================================ # 趋势检测 # ============================================================ def check_trend_anomaly(db, kpi_id: int, period: str, consecutive: int = 3) -> dict: """检测连续N期下滑或上升的趋势异常""" kpi = db.query(KPIDefinition).filter(KPIDefinition.id == kpi_id).first() if not kpi: return {"anomaly": False} # 获取包括当前期在内的近期数据 year, month = period.split("-") y, m = int(year), int(month) values = [] for i in range(consecutive + 2): # 多取2期做参考 p = f"{y}-{m:02d}" v = get_actual_for_kpi(db, kpi_id, p) if v is not None: values.append({"period": p, "value": v}) m -= 1 if m <= 0: m += 12 y -= 1 values.reverse() # 按时间正序 if len(values) < consecutive: return {"anomaly": False, "reason": "数据不足"} last_n = values[-consecutive:] all_decreasing = all(last_n[i]["value"] > last_n[i + 1]["value"] for i in range(len(last_n) - 1)) all_increasing = all(last_n[i]["value"] < last_n[i + 1]["value"] for i in range(len(last_n) - 1)) if all_decreasing: return { "anomaly": True, "type": "continuous_decline", "level": "yellow" if consecutive >= 3 else "green", "periods": [v["period"] for v in last_n], "values": [v["value"] for v in last_n], "message": f"{kpi.kpi_name} 连续{consecutive}期下滑", } if all_increasing: return { "anomaly": True, "type": "continuous_rise", "level": "yellow" if consecutive >= 3 else "green", "periods": [v["period"] for v in last_n], "values": [v["value"] for v in last_n], "message": f"{kpi.kpi_name} 连续{consecutive}期上升(可能过热)", } return {"anomaly": False} # ============================================================ # 差异预警触发 # ============================================================ def run_deviation_check(db_session, period: str = None) -> int: """运行差异预警检查,返回新增预警数""" if period is None: period = datetime.now().strftime("%Y-%m") kpis = db_session.query(KPIDefinition).filter( KPIDefinition.status == "active" ).all() 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 alert_msg = ( f"{kpi.kpi_name}[{period}] 差异预警: 实际{deviation['actual_value']} " f"vs 预算{deviation['budget_value']}," f"差异率{deviation['deviation_rate']}%" ) # 检查是否已有同KPI同期间的差异预警 existing = db_session.query(KPIAlert).filter( KPIAlert.kpi_id == kpi.id, KPIAlert.alert_message.contains("[差异预警]"), KPIAlert.alert_message.contains(period), KPIAlert.status.in_(["pending", "processing"]), ).first() if not existing: alert = KPIAlert( kpi_id=kpi.id, alert_level=level, alert_message=f"[差异预警] {alert_msg}", status="pending", ) db_session.add(alert) new_count += 1 logger.info(f" 新增差异预警 [{level}] {kpi.kpi_name}: 差异率{deviation['deviation_rate']}%") # 2. 趋势异常检测(每期检查连续3期) trend = check_trend_anomaly(db_session, kpi.id, period, consecutive=3) if trend.get("anomaly") and trend.get("level") in ("yellow", "red"): trend_alert_msg = trend["message"] existing_trend = db_session.query(KPIAlert).filter( KPIAlert.kpi_id == kpi.id, KPIAlert.alert_message.contains("[趋势预警]"), KPIAlert.status.in_(["pending", "processing"]), ).first() if not existing_trend: alert = KPIAlert( kpi_id=kpi.id, alert_level=trend["level"], alert_message=f"[趋势预警] {trend_alert_msg}", status="pending", ) db_session.add(alert) new_count += 1 logger.info(f" 新增趋势预警 [{trend['level']}] {trend_alert_msg}") db_session.commit() return new_count if __name__ == "__main__": logging.basicConfig( level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", ) db = get_session_local()() try: n = run_deviation_check(db) print(f"差异预警检查完成: 新增 {n} 条") finally: db.close()