init: 管理会计OS初始代码
包含前后端完整代码： - 前端：Vue3+Vite+ElementPlus - 后端：FastAPI+SQLAlchemy - 模块：驾驶舱/KPI/战略地图/预警/预算/成本/预测/改善行动 - 当前版本：v1.0.0
This commit is contained in:
Hermes CI Fix
@@ -0,0 +1,311 @@
|
||||
"""差异预警引擎 — 管理会计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()
|
||||
Reference in New Issue
Block a user