"""资金管理API — 资金缺口预测 + 收付款计划 + 预警 (资金管理智能体)""" import logging from datetime import datetime, timedelta from fastapi import APIRouter, HTTPException, Depends, Query from sqlalchemy.orm import Session from app.database import get_db from app.auth_middleware import require_role from app.models import CashPlan from app.utils.cash_forecast_engine import ( forecast_cash_flow_with_plans, check_cash_alerts, DEFAULT_CASH_WARNING, DEFAULT_CASH_CRITICAL, ) logger = logging.getLogger("cma.cash") router = APIRouter( prefix="/api/cma/cash", tags=["资金管理"], dependencies=[Depends(require_role("ceo", "finance", "business", "it"))], ) def _plan_dict(p: CashPlan) -> dict: return { "id": p.id, "entity_id": p.entity_id, "plan_type": p.plan_type, "plan_type_label": "收款" if p.plan_type == "receive" else "付款", "amount": round(p.amount or 0, 2), "plan_date": p.plan_date.strftime("%Y-%m-%d") if p.plan_date else "", "counterparty": p.counterparty or "", "description": p.description or "", "status": p.status, "status_label": {"pending": "待执行", "completed": "已完成", "cancelled": "已取消"}.get(p.status, p.status), "completed_at": p.completed_at.strftime("%Y-%m-%d %H:%M") if p.completed_at else None, "created_at": p.created_at.strftime("%Y-%m-%d %H:%M") if p.created_at else None, } # ══════════════════════════════════════════════════════════ # 1. 资金缺口预测 # ══════════════════════════════════════════════════════════ @router.get("/gap-forecast") def api_gap_forecast( entity_id: int = Query(1, description="企业ID"), days: int = Query(30, ge=1, le=90, description="预测天数"), current_cash: float = Query(None, description="当前现金余额(万元),不传则自动获取"), db: Session = Depends(get_db), ): """资金缺口预测 — 趋势引擎 + 收付款计划,识别余额<警戒线的缺口日期""" try: return forecast_cash_flow_with_plans(entity_id, db, days=days, current_cash=current_cash) except Exception as e: logger.error(f"资金缺口预测失败: {e}", exc_info=True) raise HTTPException(400, f"资金缺口预测失败: {str(e)}") @router.get("/balance") def api_get_balance( entity_id: int = Query(1), db: Session = Depends(get_db), ): """获取当前现金余额(预测基线)""" from app.utils.cash_forecast_engine import get_current_cash_balance value = get_current_cash_balance(db, entity_id) return {"entity_id": entity_id, "current_cash": value} @router.post("/balance") def api_set_balance( data: dict, db: Session = Depends(get_db), ): """设置当前现金余额(万元),作为预测基线""" from app.utils.cash_forecast_engine import set_current_cash_balance value = float(data.get("current_cash", 0)) if value < 0: raise HTTPException(400, "现金余额不能为负") set_current_cash_balance(db, value) return {"message": "当前现金余额已更新", "current_cash": value} # ══════════════════════════════════════════════════════════ # 2. 收付款计划 CRUD # ══════════════════════════════════════════════════════════ @router.get("/plans") def api_list_plans( entity_id: int = Query(1), plan_type: str = Query(None, description="receive/pay"), status: str = Query(None, description="pending/completed/cancelled"), month: str = Query(None, description="YYYY-MM 按计划月份过滤"), page: int = Query(1, ge=1), page_size: int = Query(100, ge=1, le=500), db: Session = Depends(get_db), ): """收付款计划列表""" query = db.query(CashPlan).filter(CashPlan.entity_id == entity_id) if plan_type: query = query.filter(CashPlan.plan_type == plan_type) if status: query = query.filter(CashPlan.status == status) if month: try: y, m = int(month[:4]), int(month[5:7]) start = datetime(y, m, 1) end = (start + timedelta(days=32)).replace(day=1) query = query.filter(CashPlan.plan_date >= start, CashPlan.plan_date < end) except Exception: raise HTTPException(400, "month格式应为YYYY-MM") total = query.count() plans = query.order_by(CashPlan.plan_date.asc(), CashPlan.id.desc()) \ .offset((page - 1) * page_size).limit(page_size).all() return {"total": total, "data": [_plan_dict(p) for p in plans]} @router.post("/plans") def api_create_plan(data: dict, db: Session = Depends(get_db)): """新建收付款计划""" plan_type = data.get("plan_type") if plan_type not in ("receive", "pay"): raise HTTPException(400, "plan_type必须为receive(收)或pay(付)") amount = float(data.get("amount", 0)) if amount <= 0: raise HTTPException(400, "金额必须大于0") date_str = data.get("plan_date") if not date_str: raise HTTPException(400, "缺少计划日期") try: plan_date = datetime.strptime(str(date_str)[:10], "%Y-%m-%d") except Exception: raise HTTPException(400, "plan_date格式应为YYYY-MM-DD") plan = CashPlan( entity_id=int(data.get("entity_id", 1)), plan_type=plan_type, amount=amount, plan_date=plan_date, counterparty=(data.get("counterparty") or "").strip(), description=(data.get("description") or "").strip(), status=data.get("status", "pending"), ) db.add(plan) db.commit() db.refresh(plan) logger.info(f"新建收付款计划 #{plan.id} [{plan_type}] {amount}万 {date_str}") return {"message": "收付款计划已创建", "data": _plan_dict(plan)} @router.put("/plans/{plan_id}") def api_update_plan(plan_id: int, data: dict, db: Session = Depends(get_db)): """更新收付款计划""" plan = db.query(CashPlan).filter(CashPlan.id == plan_id).first() if not plan: raise HTTPException(404, "计划不存在") if "plan_type" in data: if data["plan_type"] not in ("receive", "pay"): raise HTTPException(400, "plan_type必须为receive或pay") plan.plan_type = data["plan_type"] if "amount" in data: amount = float(data["amount"]) if amount <= 0: raise HTTPException(400, "金额必须大于0") plan.amount = amount if "plan_date" in data and data["plan_date"]: try: plan.plan_date = datetime.strptime(str(data["plan_date"])[:10], "%Y-%m-%d") except Exception: raise HTTPException(400, "plan_date格式应为YYYY-MM-DD") if "counterparty" in data: plan.counterparty = (data["counterparty"] or "").strip() if "description" in data: plan.description = (data["description"] or "").strip() if "status" in data: plan.status = data["status"] if data["status"] == "completed" and not plan.completed_at: plan.completed_at = datetime.now() elif data["status"] in ("pending", "cancelled"): plan.completed_at = None db.commit() db.refresh(plan) return {"message": "计划已更新", "data": _plan_dict(plan)} @router.delete("/plans/{plan_id}") def api_delete_plan(plan_id: int, db: Session = Depends(get_db)): """删除收付款计划""" plan = db.query(CashPlan).filter(CashPlan.id == plan_id).first() if not plan: raise HTTPException(404, "计划不存在") db.delete(plan) db.commit() return {"message": "计划已删除"} @router.post("/plans/{plan_id}/complete") def api_complete_plan(plan_id: int, db: Session = Depends(get_db)): """标记计划为已完成(收款到账/付款完成)""" plan = db.query(CashPlan).filter(CashPlan.id == plan_id).first() if not plan: raise HTTPException(404, "计划不存在") plan.status = "completed" plan.completed_at = datetime.now() db.commit() db.refresh(plan) return {"message": "已标记完成", "data": _plan_dict(plan)} # ══════════════════════════════════════════════════════════ # 3. 到期提醒 + 页面看板 # ══════════════════════════════════════════════════════════ @router.get("/upcoming") def api_upcoming( entity_id: int = Query(1), days: int = Query(7, ge=1, le=30), db: Session = Depends(get_db), ): """未来N天到期提醒 + 已逾期未收/未付""" today = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0) upcoming = db.query(CashPlan).filter( CashPlan.entity_id == entity_id, CashPlan.status == "pending", CashPlan.plan_date >= today, CashPlan.plan_date <= today + timedelta(days=days), ).order_by(CashPlan.plan_date.asc()).all() overdue = db.query(CashPlan).filter( CashPlan.entity_id == entity_id, CashPlan.status == "pending", CashPlan.plan_date < today, ).order_by(CashPlan.plan_date.asc()).all() return { "days": days, "upcoming": [_plan_dict(p) for p in upcoming], "overdue": [_plan_dict(p) for p in overdue], "overdue_receive_amount": round(sum(p.amount for p in overdue if p.plan_type == "receive"), 2), "overdue_pay_amount": round(sum(p.amount for p in overdue if p.plan_type == "pay"), 2), } @router.get("/dashboard") def api_cash_dashboard( entity_id: int = Query(1), month: str = Query(None, description="YYYY-MM 默认本月"), days: int = Query(30), current_cash: float = Query(None, description="当前现金余额(万元)"), db: Session = Depends(get_db), ): """收付款计划页面看板 — 日历汇总 + 预测 + 到期提醒""" today = datetime.now() if month: try: y, m = int(month[:4]), int(month[5:7]) except Exception: raise HTTPException(400, "month格式应为YYYY-MM") else: y, m = today.year, today.month start = datetime(y, m, 1) end = (start + timedelta(days=32)).replace(day=1) plans = db.query(CashPlan).filter( CashPlan.entity_id == entity_id, CashPlan.status == "pending", CashPlan.plan_date >= start, CashPlan.plan_date < end, ).all() # 日历:按天汇总 应收/应付 calendar = {} for p in plans: dkey = p.plan_date.strftime("%Y-%m-%d") cell = calendar.setdefault(dkey, {"receive": 0.0, "pay": 0.0, "items": []}) if p.plan_type == "receive": cell["receive"] += p.amount else: cell["pay"] += p.amount cell["items"].append(_plan_dict(p)) # 本月合计 month_receive = round(sum(p.amount for p in plans if p.plan_type == "receive"), 2) month_pay = round(sum(p.amount for p in plans if p.plan_type == "pay"), 2) forecast = forecast_cash_flow_with_plans(entity_id, db, days=days, current_cash=current_cash) upcoming = api_upcoming(entity_id, 7, db) return { "entity_id": entity_id, "month": f"{y:04d}-{m:02d}", "month_receive": month_receive, "month_pay": month_pay, "month_net": round(month_receive - month_pay, 2), "calendar": calendar, "forecast": forecast, "upcoming": upcoming, } # ══════════════════════════════════════════════════════════ # 4. 资金预警 — 缺口前3天预警 + 到期未收款提醒 # ══════════════════════════════════════════════════════════ @router.post("/check-alerts") def api_check_cash_alerts(entity_id: int = 1, db: Session = Depends(get_db)): """手动触发资金预警检查(写入预警中心kpi_alerts)""" try: return check_cash_alerts(db, entity_id=entity_id) except Exception as e: logger.error(f"资金预警检查失败: {e}", exc_info=True) raise HTTPException(400, f"资金预警检查失败: {str(e)}") @router.get("/alerts/status") def api_cash_alert_status(entity_id: int = Query(1), db: Session = Depends(get_db)): """资金预警状态概览 — 当前缺口/逾期情况(不写库,只读)""" result = forecast_cash_flow_with_plans(entity_id, db, days=30) return { "entity_id": entity_id, "warning_line": result["warning_line"], "critical_line": result["critical_line"], "gap_dates": result["gap_dates"], "pre_alerts": result["pre_alerts"], "min_cash": result["min_cash"], "min_cash_date": result["min_cash_date"], "summary": result["summary"], }