fourcal-pms/backend/app/api/control.py

399 lines
17 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""预算控制:立项基线 vs 预算现值、超支拦截规则、成本台账与仪表盘。
一句话口径:**基线是立项审批通过那一刻的数**,之后不论预算怎么改,基线都不动。
只有立项本身重新送审并批准,基线才跟着换版。这条是整个模块的地基——基线如果跟着
预算走,编制预算的人就能自己把拦截线抬上去,那还拦什么。
"预算执行实时对比 / 超支拦截"里真正的"执行"需要**实际成本**(合同收付款、总账凭证),
那两块数据源还没接(见 docs/模块规划.md)。当前这一层比的是"预算 vs 立项批准",
它是实际成本接进来之后第二层对比的对照物,不是它的替身。
"""
from __future__ import annotations
from datetime import datetime
from typing import Any
from fastapi import APIRouter, Query
from pydantic import BaseModel, Field
from sqlalchemy import func, or_, select
from ..deps import DbSession, PrincipalOf
from ..envelope import bad_request, forbidden, ok
from ..models import (
ApprovalInstance,
ApprovalTask,
CalcSnapshot,
InstanceStatus,
Project,
Revision,
RevisionModule,
RevisionStatus,
SystemConfig,
TaskStatus,
)
from ..service import biz
from ..service.calc.money import ZERO, money_str, to_dec
router = APIRouter(prefix="/control", tags=["control"])
CODE_VIEW = "budget:control:view"
CODE_EDIT = "budget:control:edit"
#: 状态色:ok 正常 / near 接近阈值 / over 已超 / none 没有基线
STATUS_LABELS = {"none": "无基线", "ok": "未超", "near": "接近阈值", "over": "已超基线",
"noBudget": "未编预算"}
def _t(value: datetime | None) -> str:
return value.isoformat(sep=" ", timespec="seconds") if value else ""
def _ratio(current, baseline) -> str:
base = to_dec(baseline)
if base <= 0:
return ""
return f"{(to_dec(current) / base - 1) * 100:.2f}"
def _status(current, baseline, rate: float) -> str:
base = to_dec(baseline)
if base <= 0:
return "none"
value = to_dec(current)
if value > base * (1 + rate / 100):
return "over"
if rate > 0 and value > base * (1 + max(rate - 2, rate * 0.6) / 100):
return "near"
return "ok"
@router.get("/rules")
def get_rules(db: DbSession, current: PrincipalOf) -> dict[str, Any]:
if not current.permission.can_any((CODE_VIEW, CODE_EDIT)):
raise forbidden(f"缺少权限:{CODE_VIEW}")
rate, action = biz.budget_control_settings(db)
return ok({
"rate": f"{rate}",
"action": action,
"actionLabels": {"block": "拦截送审", "warn": "仅告警"},
"baselineNote": "基线取立项审批通过那一版的口径,重新批准立项才会换基线",
})
class RulesBody(BaseModel):
rate: str = ""
action: str = ""
@router.put("/rules")
def update_rules(body: RulesBody, db: DbSession, current: PrincipalOf) -> dict[str, Any]:
if not current.permission.can(CODE_EDIT):
raise forbidden(f"缺少权限:{CODE_EDIT}")
if body.action and body.action not in ("block", "warn"):
raise bad_request("bad_action", "动作只能是 block 或 warn")
rate = to_dec(body.rate or 0)
if rate < 0 or rate > 100:
raise bad_request("bad_rate", "阈值要落在 0~100 之间(0 表示不检查)")
wanted = {biz.BUDGET_CONTROL_RATE_CODE: f"{rate}", biz.BUDGET_CONTROL_ACTION_CODE: body.action}
rows = {row.code: row for row in db.execute(
select(SystemConfig).where(SystemConfig.code.in_(list(wanted)))).scalars().all()}
for code, value in wanted.items():
if value == "":
continue
row = rows.get(code)
if row is None:
db.add(SystemConfig(code=code, name=code, value=value, value_type="number",
group="budget", editable=True, remark="预算控制参数"))
else:
row.value = value
db.commit()
rate_now, action_now = biz.budget_control_settings(db)
return ok({"rate": f"{rate_now}", "action": action_now})
@router.get("/compare")
def compare(db: DbSession, current: PrincipalOf, keyword: str = "", status: str = "",
onlyMine: bool = False, pageNo: int = 1, pageSize: int = Query(20, ge=1, le=100)
) -> dict[str, Any]:
"""预算 vs 立项基线。给「预算执行对比」页与仪表盘共用。"""
if not current.permission.can(CODE_VIEW):
raise forbidden(f"缺少权限:{CODE_VIEW}")
from ..service.data_scope import evaluate
decision = evaluate(db, "project", current.scope)
statement = select(Project).where(Project.is_deleted.is_(False))
statement = decision.apply_to(statement)
if keyword:
like = f"%{keyword}%"
statement = statement.where(or_(Project.name.like(like), Project.project_no.like(like),
Project.customer.like(like)))
if onlyMine:
from ..models import ProjectMember
statement = statement.where(or_(
Project.creator_id == current.account.id,
Project.principal_id == current.account.id,
Project.id.in_(select(ProjectMember.project_id).where(
ProjectMember.account_id == current.account.id)),
))
projects = db.execute(statement.order_by(Project.updated_at.desc())).scalars().all()
rate, action = biz.budget_control_settings(db)
rate_value = float(rate or 0)
budget_heads = _latest_revisions(db, [row.id for row in projects], RevisionModule.BUDGET)
items: list[dict[str, Any]] = []
for project in projects:
budget = budget_heads.get(project.id)
baseline = biz.initiation_baseline(db, project.id)
current_values = _budget_totals(db, budget)
row_state = _status(current_values.get("contractAmount"), baseline.get("contractAmount"),
rate_value) if budget else "noBudget"
purchase_state = _status(current_values.get("purchaseAmount"), baseline.get("purchaseInclude"),
rate_value) if budget else "noBudget"
worst = _worst(row_state, purchase_state)
items.append({
"id": project.id, "name": project.name, "projectNo": project.project_no,
"orgUnitName": project.org_unit_name, "principal": project.principal,
"budgetStatus": budget.status if budget else "",
"budgetVersion": budget.version if budget else 0,
"initiationApprovedAt": baseline.get("approvedAt", ""),
"initiationVersion": baseline.get("version", 0),
"baseline": {
"contractAmount": money_str(baseline.get("contractAmount")),
"purchaseAmount": money_str(baseline.get("purchaseInclude")),
"grossProfit": money_str(baseline.get("grossProfit")),
},
"budget": {
"contractAmount": money_str(current_values.get("contractAmount")),
"purchaseAmount": money_str(current_values.get("purchaseAmount")),
"grossProfit": money_str(current_values.get("grossProfit")),
},
"diff": {
"contractRate": _ratio(current_values.get("contractAmount"),
baseline.get("contractAmount")),
"purchaseRate": _ratio(current_values.get("purchaseAmount"),
baseline.get("purchaseInclude")),
},
"status": worst,
"statusLabel": STATUS_LABELS.get(worst, worst),
})
if status:
items = [item for item in items if item["status"] == status]
# 已超基线的排最前:这一页是给人来处理超支的,不是给人看报表的
order = {"over": 0, "near": 1, "noBudget": 2, "ok": 3, "none": 4}
items.sort(key=lambda item: (order.get(item["status"], 9), item["projectNo"] or item["name"]))
total = len(items)
start = (max(pageNo, 1) - 1) * pageSize
counts: dict[str, int] = {}
for item in items:
counts[item["status"]] = counts.get(item["status"], 0) + 1
return ok({
"items": items[start:start + pageSize], "total": total, "pageNo": pageNo,
"pageSize": pageSize,
"summary": {"rate": f"{rate}", "action": action, "counts": counts,
"checked": len(projects)},
"scope": decision.to_dict(),
})
def _worst(*statuses: str) -> str:
order = ["over", "near", "noBudget", "none", "ok"]
for candidate in order:
if candidate in statuses:
return candidate
return "ok"
def _latest_revisions(db, project_ids: list[int], module: str) -> dict[int, Revision]:
if not project_ids:
return {}
rows = db.execute(
select(Revision).where(Revision.project_id.in_(project_ids), Revision.module == module,
Revision.is_deleted.is_(False)).order_by(Revision.version.desc())
).scalars().all()
out: dict[int, Revision] = {}
for row in rows:
out.setdefault(row.project_id, row)
return out
def _budget_totals(db, budget: Revision | None) -> dict[str, Any]:
"""预算侧现值:读那一版最近的计算快照,不在这儿重算第二遍。"""
empty = {"contractAmount": ZERO, "purchaseAmount": ZERO, "grossProfit": ZERO}
if budget is None:
return empty
snapshot = None
if budget.snapshot_id:
snapshot = db.get(CalcSnapshot, budget.snapshot_id)
if snapshot is None:
snapshot = db.execute(
select(CalcSnapshot).where(CalcSnapshot.revision_id == budget.id)
.order_by(CalcSnapshot.id.desc()).limit(1)
).scalars().first()
payload = biz.snapshot_payload(snapshot)
if not payload:
return empty
profit = payload.get("profit") or {}
groups = payload.get("groups") or {}
purchase_include = sum((to_dec((bucket or {}).get("include"))
for bucket in (groups.get("purchase") or {}).values()), ZERO)
return {
"contractAmount": to_dec(payload.get("contract_amount") or profit.get("income_total")),
"purchaseAmount": purchase_include,
"grossProfit": to_dec(profit.get("gross_b")),
}
@router.get("/cost-ledger")
def cost_ledger(db: DbSession, current: PrincipalOf, keyword: str = "",
pageNo: int = 1, pageSize: int = 20) -> dict[str, Any]:
"""项目成本台账:每个项目最新预算版本的收入、采购、管理费、毛利。
数据只从计算快照读,跟工作台、审批看的是同一份口径,不在这里重算。
"""
if not current.permission.can(CODE_VIEW):
raise forbidden(f"缺少权限:{CODE_VIEW}")
from ..service.data_scope import evaluate
decision = evaluate(db, "project", current.scope)
statement = select(Project).where(Project.is_deleted.is_(False))
statement = decision.apply_to(statement)
if keyword:
like = f"%{keyword}%"
statement = statement.where(or_(Project.name.like(like), Project.project_no.like(like)))
total = db.execute(select(func.count()).select_from(statement.subquery())).scalar() or 0
rows = db.execute(statement.order_by(Project.contract_amount.desc())
.offset((max(pageNo, 1) - 1) * pageSize).limit(pageSize)).scalars().all()
heads = _latest_revisions(db, [row.id for row in rows], RevisionModule.BUDGET)
items = []
for project in rows:
budget = heads.get(project.id)
payload = {}
if budget is not None:
snapshot = db.get(CalcSnapshot, budget.snapshot_id) if budget.snapshot_id else None
payload = biz.snapshot_payload(snapshot)
profit = payload.get("profit") or {}
manage = payload.get("manage") or {}
fund = payload.get("fund_plan") or {}
items.append({
"id": project.id, "name": project.name, "projectNo": project.project_no,
"principal": project.principal, "orgUnitName": project.org_unit_name,
"budgetVersion": budget.version if budget else 0,
"budgetStatus": budget.status if budget else "",
"incomeTotal": money_str(profit.get("income_total")),
"purchaseTotal": money_str(profit.get("purchase_total")),
"manageTotal": money_str(manage.get("total")),
"grossProfit": money_str(profit.get("gross_b")),
"grossProfitRate": _rate_text(profit.get("gross_b_rate")),
"contributionRate": _rate_text(profit.get("contribution_rate")),
"advancePeak": money_str(fund.get("peak_value")),
"capitalInterest": money_str(fund.get("interest_total")),
"snapshotAt": _t(budget.updated_at) if budget else "",
})
return ok({"items": items, "total": total, "pageNo": pageNo, "pageSize": pageSize,
"scope": decision.to_dict()})
def _rate_text(block: Any) -> str:
if not isinstance(block, dict):
return ""
if block.get("defined") is False:
return "未定义"
value = block.get("value")
return "" if value is None else f"{value}"
@router.get("/dashboard")
def dashboard(db: DbSession, current: PrincipalOf) -> dict[str, Any]:
"""仪表盘:立项漏斗 + 预算覆盖 + 超基线数 + 我的待办。
刻意只数"能数得准的":合同额、毛利、垫资这些来自计算快照,立项/预算状态来自
版本表。实际支出(预算执行率)要等合同收付款与总账接进来,这里不猜。
"""
if not current.permission.can(CODE_VIEW):
raise forbidden(f"缺少权限:{CODE_VIEW}")
from ..service.data_scope import evaluate
from ..models import ProjectStage
decision = evaluate(db, "project", current.scope)
base = decision.apply_to(select(Project.id).where(Project.is_deleted.is_(False)))
project_ids = [row[0] for row in db.execute(base).all()]
def count_by(module: str, statuses: tuple[str, ...] = ()) -> int:
statement = select(func.count(Revision.id)).where(
Revision.module == module, Revision.is_deleted.is_(False),
Revision.project_id.in_(project_ids or [-1]))
if statuses:
statement = statement.where(Revision.status.in_(statuses))
return db.execute(statement).scalar() or 0
approved_projects = db.execute(
select(func.count(func.distinct(Revision.project_id))).where(
Revision.module == RevisionModule.ESTIMATE,
Revision.status == RevisionStatus.APPROVED,
Revision.is_deleted.is_(False),
Revision.project_id.in_(project_ids or [-1]))
).scalar() or 0
budget_projects = db.execute(
select(func.count(func.distinct(Revision.project_id))).where(
Revision.module == RevisionModule.BUDGET, Revision.is_deleted.is_(False),
Revision.project_id.in_(project_ids or [-1]))
).scalar() or 0
totals = db.execute(
select(func.coalesce(func.sum(Project.contract_amount), 0),
func.coalesce(func.sum(Project.gross_profit), 0),
func.coalesce(func.sum(Project.advance_peak_value), 0))
.where(Project.id.in_(project_ids or [-1]), Project.is_deleted.is_(False))
).one()
compare_page = compare(db, current, status="over", pageNo=1, pageSize=10)
over = compare_page["data"]
todo = 0
if _has_todo_permission(current):
todo = db.execute(
select(func.count(ApprovalTask.id))
.join(ApprovalInstance, ApprovalTask.instance_id == ApprovalInstance.id)
.where(ApprovalTask.assignee_id == current.account.id,
ApprovalTask.status == TaskStatus.PENDING,
ApprovalInstance.status == InstanceStatus.REVIEWING)
).scalar() or 0
stages = db.execute(
select(Project.stage, func.count(Project.id))
.where(Project.id.in_(project_ids or [-1]), Project.is_deleted.is_(False))
.group_by(Project.stage)
).all()
return ok({
"projects": len(project_ids),
"initiation": {
"reviewing": count_by(RevisionModule.ESTIMATE, (RevisionStatus.REVIEWING,)),
"approved": int(approved_projects),
"approvedRate": f"{(approved_projects / len(project_ids) * 100):.1f}" if project_ids else "0",
},
"budget": {
"draft": count_by(RevisionModule.BUDGET, (RevisionStatus.DRAFT,)),
"reviewing": count_by(RevisionModule.BUDGET, (RevisionStatus.REVIEWING,)),
"approved": count_by(RevisionModule.BUDGET, (RevisionStatus.APPROVED,)),
"covered": int(budget_projects),
"coverageRate": f"{(budget_projects / approved_projects * 100):.1f}" if approved_projects else "0",
},
"amounts": {
"contractTotal": money_str(totals[0]), "grossProfitTotal": money_str(totals[1]),
"advancePeakTotal": money_str(totals[2]),
},
"overBudget": {"total": over["total"], "items": over["items"]},
"todo": int(todo),
"stageFlow": [{"stage": stage, "label": ProjectStage.LABELS.get(stage, str(stage)),
"count": count} for stage, count in sorted(stages)],
"scope": decision.to_dict(),
})
def _has_todo_permission(current: PrincipalOf) -> bool:
return current.permission.can_any(("workbench:todo", "approval:monitor:view"))