e7e47d88bc
- settlement_service：generate（确认回款口径 #8 策略点=有效台账行按回款日 归月、经理聚合 #12 暂口径基数不含经理个人户、月结 uk 一行一月、草稿/ 驳回可重生成、已审定/待审 400）→ submit（审批开关分流，关=自动通过即 锁定、开=待财务复核）→ approval_service.act 扩 order_type=2/3 钩子 （通过=mark_locked/调整单生效；驳回=回草稿/作废，延迟导入防循环） - 锁定拦截：回款新增写路径校验回款月已审定 400（比需求「提示」取硬， 一期安全侧；M2 已核算禁改防线先于其生效） - 调整单：新建（TZ 单号，开关分流自动通过留痕/走审批）+ 列表 - schemas settlement：金额 Decimal 声明（str 声明遇 Decimal 入参拒绝） - 测试 6 例：生成回填/无记录 400/已审定重生成 400/关自动锁定/锁定后回款 禁改/开两节点流转至锁定（finance→leader） Co-Authored-By: Claude Code <noreply@anthropic.com>
369 lines
14 KiB
Python
369 lines
14 KiB
Python
"""审批流业务编排（2026-10-15 复核审批补充需求）。
|
||
|
||
三级链路：营销后勤提交 → 财务复核 → 领导审核。行为由参数开关驱动
|
||
（`approval.secondary_allocation.enabled` / `approval.monthly_settlement.enabled`）：
|
||
|
||
- **关闭（默认）**：提交即生成审批单并「自动通过」全节点留痕（action=3，
|
||
operator 记「系统」）——留痕不断链，与「关闭=直接生效」的需求口径一致；
|
||
- **开启**：status=1 待财务复核 → 2 待领导审核 → 3 已通过；任一节点驳回
|
||
即整体驳回（status=4），一期不做退回重走（简单状态机）。
|
||
|
||
红线：
|
||
- `submit_order` **不 commit、不嵌套 audit** —— 由业务写路径（business_service
|
||
的 create/update）既有 audit 上下文统一收口，违反嵌套禁令会让失败路径
|
||
回滚不完整（见 audit_service 模块 docstring）；
|
||
- 节点准入**严格按角色编码**：status=1 仅财务、status=2 仅领导，admin 不
|
||
代办 —— 放行 admin 会让双人复核流退化成管理员单点审批；
|
||
- 同一引用对象的在途单（status 1/2）在重新提交前先撤回（status=5 +
|
||
node=0/action=4 留痕），保证「一个对象至多一张在途单」。
|
||
"""
|
||
|
||
import logging
|
||
from datetime import date
|
||
|
||
from sqlalchemy import func, select
|
||
from sqlalchemy.orm import Session
|
||
|
||
from app.core.constants import (
|
||
ACTION_APPROVE,
|
||
ACTION_REJECT,
|
||
MODULE_APPROVAL,
|
||
NO_PREFIX_APPROVAL,
|
||
ROLE_FINANCE,
|
||
ROLE_LEADER,
|
||
)
|
||
from app.core.exceptions import BadRequestError, ForbiddenError, NotFoundError
|
||
from app.core.response import PageResult
|
||
from app.models import ApprovalOrder, ApprovalStep, User
|
||
from app.models.approval import (
|
||
APPROVAL_ACTION_APPROVE,
|
||
APPROVAL_ACTION_AUTO_APPROVE,
|
||
APPROVAL_ACTION_REJECT,
|
||
APPROVAL_ACTION_WITHDRAW,
|
||
APPROVAL_NODE_FINANCE,
|
||
APPROVAL_NODE_LEADER,
|
||
APPROVAL_NODE_WITHDRAW,
|
||
APPROVAL_NODES,
|
||
APPROVAL_STATUS_APPROVED,
|
||
APPROVAL_STATUS_PENDING_FINANCE,
|
||
APPROVAL_STATUS_PENDING_LEADER,
|
||
APPROVAL_STATUS_REJECTED,
|
||
APPROVAL_STATUS_WITHDRAWN,
|
||
)
|
||
from app.repositories import user_repository
|
||
from app.schemas.approval import (
|
||
ApprovalActionIn,
|
||
ApprovalOrderDetailOut,
|
||
ApprovalOrderOut,
|
||
ApprovalQuery,
|
||
ApprovalStepOut,
|
||
)
|
||
from app.services import audit_service, param_service
|
||
from app.services.audit_service import AuditRecord, RequestMeta
|
||
from app.services.no_generator import next_no
|
||
|
||
logger = logging.getLogger(__name__)
|
||
|
||
# 开关参数编码（与 param_registry 种子同源）
|
||
ENABLE_CODE_BY_TYPE: dict[int, str] = {
|
||
1: "approval.secondary_allocation.enabled",
|
||
2: "approval.monthly_settlement.enabled",
|
||
}
|
||
|
||
# 在途状态集合（同一引用对象至多一张在途单）
|
||
_PENDING_STATUSES = (APPROVAL_STATUS_PENDING_FINANCE, APPROVAL_STATUS_PENDING_LEADER)
|
||
|
||
# 在途状态 → 当前节点应操作的角色（admin 不代办：单人审批绕过双人复核）
|
||
_NODE_ROLE_BY_STATUS = {
|
||
APPROVAL_STATUS_PENDING_FINANCE: ROLE_FINANCE,
|
||
APPROVAL_STATUS_PENDING_LEADER: ROLE_LEADER,
|
||
}
|
||
|
||
_ROLE_LABEL = {ROLE_FINANCE: "财务", ROLE_LEADER: "领导"}
|
||
|
||
|
||
def is_enabled(session: Session, order_type: int) -> bool:
|
||
"""读当日参数快照判定审批开关（一次提交路径内只读一次，调用方勿重读）。"""
|
||
code = ENABLE_CODE_BY_TYPE.get(order_type)
|
||
if code is None:
|
||
raise BadRequestError("未知的审批对象类型")
|
||
return param_service.resolve_snapshot(session, date.today()).boolean(code)
|
||
|
||
|
||
def submit_order(
|
||
session: Session,
|
||
*,
|
||
order_type: int,
|
||
ref_id: int,
|
||
refer_no: str,
|
||
submitter: User,
|
||
) -> ApprovalOrder:
|
||
"""提单（业务写路径内部调用；不 commit、不嵌套 audit）。
|
||
|
||
同一引用对象的在途单先撤回留痕再建新单；开关关闭时生成即自动通过
|
||
（全节点 action=3 留痕）。AP 编号撞唯一键时 IntegrityError 直接穿透：
|
||
create 路径由外层编号重试循环整体重来（rollback 后业务/方案/审批单
|
||
一并重做），update 路径由审计上下文回滚并经全局 handler 收敛 400——
|
||
**任何情况下都不允许本函数内部 rollback 后部分重试**，那会把同事务
|
||
的业务主行/明细/方案回滚掉而审批单单表重插，静默丢业务数据。
|
||
"""
|
||
_withdraw_pending(session, order_type=order_type, ref_id=ref_id, operator=submitter)
|
||
|
||
order = ApprovalOrder(
|
||
order_no=next_no(
|
||
session,
|
||
model=ApprovalOrder,
|
||
column_name="order_no",
|
||
prefix=NO_PREFIX_APPROVAL,
|
||
),
|
||
order_type=order_type,
|
||
ref_id=ref_id,
|
||
refer_no=refer_no,
|
||
submitter_id=submitter.id,
|
||
submitter_name=submitter.username,
|
||
)
|
||
session.add(order)
|
||
|
||
if is_enabled(session, order_type):
|
||
order.status = APPROVAL_STATUS_PENDING_FINANCE
|
||
session.flush()
|
||
logger.info("审批单待审 | order=%s", order.order_no)
|
||
return order
|
||
|
||
# 开关关闭=直接生效：两级节点各记一条「自动通过」，留痕不断链
|
||
order.status = APPROVAL_STATUS_APPROVED
|
||
session.flush()
|
||
session.add_all(
|
||
[
|
||
ApprovalStep(
|
||
order_id=order.id,
|
||
node=node,
|
||
action=APPROVAL_ACTION_AUTO_APPROVE,
|
||
operator_name="系统",
|
||
)
|
||
for node in (APPROVAL_NODE_FINANCE, APPROVAL_NODE_LEADER)
|
||
]
|
||
)
|
||
session.flush()
|
||
logger.info("审批单自动通过 | order=%s（开关关闭）", order.order_no)
|
||
return order
|
||
|
||
|
||
def withdraw_pending_orders(
|
||
session: Session, *, order_type: int, ref_id: int, operator: User
|
||
) -> int:
|
||
"""撤回引用对象的全部在途单（供业务清空方案等场景显式调用；不 commit）。
|
||
|
||
返回撤回张数（0 = 本就无在途单）。
|
||
"""
|
||
before = len(
|
||
session.execute(
|
||
select(ApprovalOrder.id).where(
|
||
ApprovalOrder.order_type == order_type,
|
||
ApprovalOrder.ref_id == ref_id,
|
||
ApprovalOrder.status.in_(_PENDING_STATUSES),
|
||
)
|
||
)
|
||
.scalars()
|
||
.all()
|
||
)
|
||
if before:
|
||
_withdraw_pending(session, order_type=order_type, ref_id=ref_id, operator=operator)
|
||
return before
|
||
|
||
|
||
def act(
|
||
session: Session,
|
||
order_id: int,
|
||
payload: ApprovalActionIn,
|
||
*,
|
||
operator: User,
|
||
meta: RequestMeta | None = None,
|
||
) -> ApprovalOrderDetailOut:
|
||
"""节点动作（财务复核/领导审核）：状态机流转 + 节点留痕（审计上下文）。
|
||
|
||
通过：status=1 → 2（下一步领导）；status=2 → 3（终态已通过）。
|
||
驳回：任一在途状态 → 4（整体驳回，一期不退回重走）。
|
||
节点留痕的 node 取**动作发生时的当前节点**（通过/驳回都记在操作节点上）。
|
||
"""
|
||
codes = set(user_repository.get_role_codes(operator))
|
||
verb = ACTION_APPROVE if payload.action == APPROVAL_ACTION_APPROVE else ACTION_REJECT
|
||
with audit_service.audit(
|
||
session,
|
||
operator=operator,
|
||
record=AuditRecord(
|
||
module=MODULE_APPROVAL,
|
||
action=verb,
|
||
summary=f"审批单 #{order_id} {verb}",
|
||
request_data=payload.model_dump(),
|
||
),
|
||
meta=meta,
|
||
):
|
||
order = session.get(ApprovalOrder, order_id, with_for_update=True)
|
||
if order is None:
|
||
raise NotFoundError("审批单不存在")
|
||
if order.status not in _PENDING_STATUSES:
|
||
raise BadRequestError("审批单已结束，不可重复操作")
|
||
|
||
required_role = _NODE_ROLE_BY_STATUS[order.status]
|
||
if required_role not in codes:
|
||
raise ForbiddenError(f"当前节点须{_ROLE_LABEL[required_role]}角色操作")
|
||
|
||
node_now = APPROVAL_NODES[order.status]
|
||
rejected = payload.action == APPROVAL_ACTION_REJECT
|
||
if rejected:
|
||
order.status = APPROVAL_STATUS_REJECTED
|
||
else:
|
||
order.status = (
|
||
APPROVAL_STATUS_PENDING_LEADER
|
||
if order.status == APPROVAL_STATUS_PENDING_FINANCE
|
||
else APPROVAL_STATUS_APPROVED
|
||
)
|
||
|
||
session.add(
|
||
ApprovalStep(
|
||
order_id=order.id,
|
||
node=node_now,
|
||
action=payload.action,
|
||
opinion=payload.opinion,
|
||
operator_id=operator.id,
|
||
operator_name=operator.username,
|
||
)
|
||
)
|
||
# 驳回=方案未获批准：清空该业务的二次分配行，防止被否决的方案以
|
||
# 「当前生效行」身份留在表里、被 M3 核算快照算进工资；方案事实由
|
||
# 审批单留痕与操作日志 request_data 承载（分摊语义落定后如需保留
|
||
# 历史版本，在 ④ 设计时演进）。审批单的清理由调用方（act 内联）
|
||
# 委托 business_repository 完成 —— service 层互调、不触 commit。
|
||
if rejected and order.order_type == 1:
|
||
from app.repositories import business_repository
|
||
|
||
business_repository.delete_allocations(session, order.ref_id)
|
||
|
||
# 审批结果联动（服务层回调，不 commit）：月结 通过=锁定/驳回=回草稿；
|
||
# 调整单 通过=生效/驳回=作废。函数内延迟导入防循环依赖。
|
||
if order.order_type == 2 or order.order_type == 3:
|
||
from app.models import AdjustmentOrder
|
||
from app.models.settlement import (
|
||
ADJUSTMENT_STATUS_EFFECTIVE,
|
||
)
|
||
from app.models.settlement import (
|
||
ADJUSTMENT_STATUS_REJECTED as ADJ_REJECTED,
|
||
)
|
||
from app.services import settlement_service
|
||
|
||
if order.order_type == 2:
|
||
from app.models.settlement import MonthlySettlement
|
||
|
||
target = session.get(MonthlySettlement, order.ref_id)
|
||
if target is not None:
|
||
if rejected:
|
||
settlement_service.mark_rejected(session, target, operator=operator)
|
||
else:
|
||
settlement_service.mark_locked(session, target, operator=operator)
|
||
else:
|
||
adj = session.get(AdjustmentOrder, order.ref_id)
|
||
if adj is not None:
|
||
adj.status = ADJ_REJECTED if rejected else ADJUSTMENT_STATUS_EFFECTIVE
|
||
|
||
# 出参（含 steps）在 **commit 之前** 固化：audit 禁止 commit 后再碰
|
||
# ORM/查询——commit 后的任何 SELECT 失败都会让「已通过的审批」被记
|
||
# 成失败审计，与库中事实相反（全 services 层唯一例外不许再犯）
|
||
session.flush()
|
||
detail = _detail_of(session, order)
|
||
session.commit()
|
||
return detail
|
||
|
||
|
||
def list_orders(session: Session, query: ApprovalQuery) -> PageResult[ApprovalOrderOut]:
|
||
"""分页查询审批单（准入由 api 层依赖判定）。"""
|
||
filters = _order_filters(query)
|
||
rows = (
|
||
session.execute(
|
||
select(ApprovalOrder)
|
||
.where(*filters)
|
||
.order_by(ApprovalOrder.id.desc())
|
||
.offset(query.offset)
|
||
.limit(query.page_size)
|
||
)
|
||
.scalars()
|
||
.all()
|
||
)
|
||
total = session.execute(
|
||
select(func.count()).select_from(ApprovalOrder).where(*filters)
|
||
).scalar_one()
|
||
return PageResult[ApprovalOrderOut](
|
||
records=[ApprovalOrderOut.model_validate(r) for r in rows],
|
||
total=int(total),
|
||
page_num=query.page_num,
|
||
page_size=query.page_size,
|
||
)
|
||
|
||
|
||
def get_order(session: Session, order_id: int) -> ApprovalOrderDetailOut:
|
||
"""审批单详情（附节点时间线）。"""
|
||
order = session.get(ApprovalOrder, order_id)
|
||
if order is None:
|
||
raise NotFoundError("审批单不存在")
|
||
return _detail_of(session, order)
|
||
|
||
|
||
def _withdraw_pending(session: Session, *, order_type: int, ref_id: int, operator: User) -> None:
|
||
"""撤回引用对象的在途单（重新提交前调用；不 commit）。"""
|
||
pending = (
|
||
session.execute(
|
||
select(ApprovalOrder).where(
|
||
ApprovalOrder.order_type == order_type,
|
||
ApprovalOrder.ref_id == ref_id,
|
||
ApprovalOrder.status.in_(_PENDING_STATUSES),
|
||
)
|
||
)
|
||
.scalars()
|
||
.all()
|
||
)
|
||
for order in pending:
|
||
order.status = APPROVAL_STATUS_WITHDRAWN
|
||
session.add(
|
||
ApprovalStep(
|
||
order_id=order.id,
|
||
node=APPROVAL_NODE_WITHDRAW,
|
||
action=APPROVAL_ACTION_WITHDRAW,
|
||
operator_id=operator.id,
|
||
operator_name=operator.username,
|
||
)
|
||
)
|
||
if pending:
|
||
session.flush()
|
||
logger.info("撤回在途审批单 %s 张 | ref=%s", len(pending), ref_id)
|
||
|
||
|
||
def _detail_of(session: Session, order: ApprovalOrder) -> ApprovalOrderDetailOut:
|
||
"""出参组装（含 steps 时间线）。调用方须保证处于 commit 之前。"""
|
||
steps = (
|
||
session.execute(
|
||
select(ApprovalStep).where(ApprovalStep.order_id == order.id).order_by(ApprovalStep.id)
|
||
)
|
||
.scalars()
|
||
.all()
|
||
)
|
||
detail = ApprovalOrderDetailOut.model_validate(order)
|
||
detail.steps = [ApprovalStepOut.model_validate(s) for s in steps]
|
||
return detail
|
||
|
||
|
||
def _order_filters(query: ApprovalQuery) -> tuple:
|
||
filters = []
|
||
if query.keyword:
|
||
# autoescape：用户输入里的 %/_ 按 URL 片段字面匹配（全库统一口径，
|
||
# 见 customer_repository.contains 用法）——否则 "AP2026_10" 会把
|
||
# 下划线当单字符通配，搜出无关单据
|
||
filters.append(
|
||
ApprovalOrder.order_no.contains(query.keyword, autoescape=True)
|
||
| ApprovalOrder.refer_no.contains(query.keyword, autoescape=True)
|
||
)
|
||
if query.status is not None:
|
||
filters.append(ApprovalOrder.status == query.status)
|
||
if query.order_type is not None:
|
||
filters.append(ApprovalOrder.order_type == query.order_type)
|
||
return tuple(filters)
|