1461a8d113
按 2026-11-02 需求补齐计划交付后端能力： - 角色授权：权限目录化，接口统一准入校验，未登记默认拒绝； 管理员判断改为按数据库角色重新判定，防止权限码持有者绕过 - 系统监控：单进程采集资源、请求与异常指标，分钟级聚合， 阈值配置化；敏感配置增加 repr 保护，Redis 密码 URL 转义 - 试用期计提：按回款日判定并写入快照，年度结清与调整单联动； 人员模型补试用期、离职日期与工资版本历史字段 - 计提模板：公式骨架受控，页面维护名称与参数绑定 - T+ 采集：自动化配置表与进度查询 内置角色禁停用保护对齐模块注释；核算规则版本提为常量并 补充批量核算失败堆栈日志。 影响范围：后端全部模块、数据库迁移 V22-V28 验证：uv run ruff check 通过；922 个单元测试全部通过； 集成测试因本机 MySQL 数据卷被其他容器锁定暂未运行
215 lines
9.3 KiB
Python
215 lines
9.3 KiB
Python
"""月度结算与调整单模型（M3 ④：月结审批报表补充需求）。
|
||
|
||
- 月度结算按「确认回款」和计算快照生成；**通过即锁定**（status=3 已审定
|
||
即终态，锁定后源数据改动只产生提示与后续调整）
|
||
- settlement_items 明细按人固化（可负=负数工资），锁定后无 UPDATE 路径
|
||
（重生成 = 草稿/驳回态删旧插新）
|
||
- 调整单是已锁定月份的唯一调整通道（补发/扣减，走审批；生效后不回写
|
||
已锁定月结——append-only，报表汇总并入）
|
||
"""
|
||
|
||
from datetime import datetime
|
||
from decimal import Decimal
|
||
|
||
from sqlalchemy import JSON, DateTime, ForeignKey, Numeric, String
|
||
from sqlalchemy.orm import Mapped, mapped_column
|
||
|
||
from app.models.base import BIGINT_UNSIGNED, TINYINT_TYPE, Base, TimestampMixin, mysql_table_args
|
||
|
||
# 月结状态（monthly_settlements.status；通过即锁定——两态合一）
|
||
SETTLEMENT_STATUS_DRAFT = 1 # 草稿（可重新生成/提交）
|
||
SETTLEMENT_STATUS_PENDING = 2 # 待审批（提交后）
|
||
SETTLEMENT_STATUS_APPROVED = 3 # 已审定（终态=已锁定）
|
||
SETTLEMENT_STATUS_REJECTED = 4 # 已驳回（回草稿可重提）
|
||
|
||
# 调整单状态（adjustment_orders.status）
|
||
ADJUSTMENT_STATUS_PENDING = 1 # 待审批
|
||
ADJUSTMENT_STATUS_EFFECTIVE = 2 # 已生效
|
||
ADJUSTMENT_STATUS_REJECTED = 3 # 已驳回
|
||
ADJUSTMENT_STATUS_WITHDRAWN = 4 # 已撤回
|
||
|
||
# 调整方向（adjustment_orders.direction）
|
||
ADJUSTMENT_DIRECTION_EXTRA = 1 # 补发
|
||
ADJUSTMENT_DIRECTION_DEDUCT = 2 # 扣减
|
||
|
||
|
||
class MonthlySettlement(Base, TimestampMixin):
|
||
"""月度结算表：按月一行（settlement_month 唯一），快照 + 审批 + 锁定。"""
|
||
|
||
__tablename__ = "monthly_settlements"
|
||
__table_args__ = mysql_table_args("月度结算表（按月一行；通过即锁定，锁定后走调整单）")
|
||
|
||
id: Mapped[int] = mapped_column(
|
||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||
)
|
||
settlement_month: Mapped[str] = mapped_column(
|
||
String(7), nullable=False, unique=True, comment="结算月份（YYYY-MM；全表唯一）"
|
||
)
|
||
status: Mapped[int] = mapped_column(
|
||
TINYINT_TYPE,
|
||
nullable=False,
|
||
server_default="1",
|
||
comment="状态：1草稿 2待审批 3已审定（终态=已锁定）4已驳回（回草稿）",
|
||
)
|
||
total_performance: Mapped[Decimal | None] = mapped_column(
|
||
Numeric(14, 2), comment="绩效金额合计（可负）"
|
||
)
|
||
total_payable: Mapped[Decimal | None] = mapped_column(
|
||
Numeric(14, 2), comment="应付绩效合计（可负）"
|
||
)
|
||
person_count: Mapped[int] = mapped_column(
|
||
TINYINT_TYPE, nullable=False, server_default="0", comment="结算人数"
|
||
)
|
||
snapshot_json: Mapped[dict | None] = mapped_column(
|
||
JSON, comment="月度总览快照（生成时刻的确认回款口径说明与汇总参数）"
|
||
)
|
||
approval_order_no: Mapped[str | None] = mapped_column(
|
||
String(32), comment="关联审批单号（冗余固化；开关关闭自动通过时也有单）"
|
||
)
|
||
submitter_id: Mapped[int | None] = mapped_column(
|
||
BIGINT_UNSIGNED,
|
||
ForeignKey("users.id", ondelete="SET NULL"),
|
||
comment="提交人ID（账号删除后置空）",
|
||
)
|
||
submitter_name: Mapped[str] = mapped_column(
|
||
String(64), nullable=False, comment="提交人用户名（冗余固化）"
|
||
)
|
||
locked_at: Mapped[datetime | None] = mapped_column(
|
||
DateTime, comment="锁定时间（status=3 时回填）"
|
||
)
|
||
locked_by: Mapped[str | None] = mapped_column(String(64), comment="锁定操作人（冗余固化）")
|
||
|
||
@property
|
||
def approval_required(self) -> bool:
|
||
return bool((self.snapshot_json or {}).get("approval_required", True))
|
||
|
||
|
||
class SettlementItem(Base):
|
||
"""月结明细表：按人按核算类型固化金额（锁定后只读；重生成=草稿态删旧插新）。"""
|
||
|
||
__tablename__ = "settlement_items"
|
||
__table_args__ = mysql_table_args(
|
||
"月结明细表（按人固化；支持负数工资；锁定后只读）",
|
||
)
|
||
|
||
id: Mapped[int] = mapped_column(
|
||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||
)
|
||
settlement_id: Mapped[int] = mapped_column(
|
||
BIGINT_UNSIGNED,
|
||
ForeignKey("monthly_settlements.id", ondelete="CASCADE"),
|
||
nullable=False,
|
||
comment="月结ID（monthly_settlements.id；头删明细随删）",
|
||
)
|
||
personnel_id: Mapped[int] = mapped_column(
|
||
BIGINT_UNSIGNED,
|
||
ForeignKey("personnel.id", ondelete="RESTRICT"),
|
||
nullable=False,
|
||
comment="结算人员ID（personnel.id）",
|
||
)
|
||
personnel_name: Mapped[str] = mapped_column(
|
||
String(64), nullable=False, comment="结算人员姓名（冗余固化）"
|
||
)
|
||
role_code: Mapped[str] = mapped_column(
|
||
String(32), nullable=False, comment="岗位编码（主岗，聚合锚点）"
|
||
)
|
||
calc_type: Mapped[int] = mapped_column(
|
||
TINYINT_TYPE, nullable=False, comment="核算类型：1单笔回款 2经理团队聚合"
|
||
)
|
||
performance_sum: Mapped[Decimal] = mapped_column(
|
||
Numeric(14, 2),
|
||
nullable=False,
|
||
comment="绩效金额合计（可负；聚合行排除经理个人户业绩，#12 暂口径）",
|
||
)
|
||
payable_sum: Mapped[Decimal] = mapped_column(
|
||
Numeric(14, 2), nullable=False, comment="应付绩效合计（可负）"
|
||
)
|
||
basic_amount: Mapped[Decimal | None] = mapped_column(
|
||
Numeric(14, 2), comment="月工资标准（personnel.salary_standard 当月快照）"
|
||
)
|
||
salary_mode: Mapped[str | None] = mapped_column(
|
||
String(16), comment="月工资口径快照：INCLUDE/DEDUCT/EXCLUDE"
|
||
)
|
||
net_amount: Mapped[Decimal | None] = mapped_column(
|
||
Numeric(14, 2),
|
||
comment="净工资 = 绩效±基本工资（按口径；试用期为基本工资+正常应付+年度差额，缓发部分不发）"
|
||
)
|
||
is_probation: Mapped[int] = mapped_column(
|
||
TINYINT_TYPE,
|
||
nullable=False,
|
||
server_default="0",
|
||
comment="试用期：1缓发绩效不发（基本工资正常发，超年累计记 note）0否",
|
||
)
|
||
probation_note: Mapped[str | None] = mapped_column(
|
||
String(255), comment="试用期说明（年累计超阈值部分年底一次性结算）"
|
||
)
|
||
normal_payable_sum: Mapped[Decimal] = mapped_column(
|
||
Numeric(14, 2), nullable=False, server_default="0", comment="当月正常实付绩效"
|
||
)
|
||
deferred_sum: Mapped[Decimal] = mapped_column(
|
||
Numeric(14, 2), nullable=False, server_default="0", comment="当月试用期缓发变化"
|
||
)
|
||
probation_payment_sum: Mapped[Decimal] = mapped_column(
|
||
Numeric(14, 2), nullable=False, server_default="0", comment="本月年度补发或扣回"
|
||
)
|
||
snapshot_json: Mapped[dict | None] = mapped_column(
|
||
JSON, comment="个人明细快照（台账行引用列表）"
|
||
)
|
||
|
||
|
||
class AdjustmentOrder(Base, TimestampMixin):
|
||
"""调整单：已锁定月份的唯一调整通道（补发/扣减，走审批；不回写月结）。"""
|
||
|
||
__tablename__ = "adjustment_orders"
|
||
__table_args__ = mysql_table_args(
|
||
"调整单表（已锁定月份的补发/扣减；走审批；生效后不回写月结快照）",
|
||
)
|
||
|
||
id: Mapped[int] = mapped_column(
|
||
BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
|
||
)
|
||
adjustment_type: Mapped[str] = mapped_column(String(32), nullable=False, server_default="'GENERAL'", comment="调整类型：GENERAL普通 ALLOCATION分配差额")
|
||
source_ledger_id: Mapped[int | None] = mapped_column(BIGINT_UNSIGNED, comment="分配差额对应的原台账ID")
|
||
attribution_json: Mapped[dict | None] = mapped_column(JSON, comment="原台账业务与分管归属快照")
|
||
order_no: Mapped[str] = mapped_column(
|
||
String(32),
|
||
nullable=False,
|
||
unique=True,
|
||
comment="调整单号，自动生成 TZ{YYYYMMDD}-{4位当日序号}",
|
||
)
|
||
settlement_month: Mapped[str] = mapped_column(
|
||
String(7), nullable=False, comment="调整月份（YYYY-MM；跨月规则待澄清 #9 前不限制）"
|
||
)
|
||
personnel_id: Mapped[int] = mapped_column(
|
||
BIGINT_UNSIGNED,
|
||
ForeignKey("personnel.id", ondelete="RESTRICT"),
|
||
nullable=False,
|
||
comment="调整人员ID（personnel.id）",
|
||
)
|
||
personnel_name: Mapped[str] = mapped_column(
|
||
String(64), nullable=False, comment="调整人员姓名（冗余固化）"
|
||
)
|
||
direction: Mapped[int] = mapped_column(
|
||
TINYINT_TYPE, nullable=False, comment="方向：1补发 2扣减"
|
||
)
|
||
amount: Mapped[Decimal] = mapped_column(
|
||
Numeric(14, 2), nullable=False, comment="调整金额（恒正，方向表达语义）"
|
||
)
|
||
reason: Mapped[str] = mapped_column(
|
||
String(255), nullable=False, comment="扣补说明（必填，审批与追溯锚点）"
|
||
)
|
||
status: Mapped[int] = mapped_column(
|
||
TINYINT_TYPE,
|
||
nullable=False,
|
||
server_default="1",
|
||
comment="状态：1待审批 2已生效 3已驳回 4已撤回",
|
||
)
|
||
submitter_id: Mapped[int | None] = mapped_column(
|
||
BIGINT_UNSIGNED,
|
||
ForeignKey("users.id", ondelete="SET NULL"),
|
||
comment="提交人ID（账号删除后置空）",
|
||
)
|
||
submitter_name: Mapped[str] = mapped_column(
|
||
String(64), nullable=False, comment="提交人用户名（冗余固化）"
|
||
)
|