merge: 合并 main 至 docs/tplus-field-mapping（V12 审批版本号批次收口前同步）

- `frontend/e2e/*.png` 改为 `frontend/e2e/**/*.png`：e2e 脚本按相对路径
  写 failure.png，在不同 CWD 下会落到 frontend/e2e/e2e/
- 忽略 .tmpdocx/（AI 生成文档的脚本与预览截图）

Co-Authored-By: Claude Code <noreply@anthropic.com>

.gitignore

@@ -45,8 +45,9 @@ htmlcov/
 .mypy_cache/
 .ruff_cache/
 .tox/
-# 端到端测试产出的截图
+# 端到端测试产出的截图（脚本以相对路径 e2e/failure.png 落盘，在不同 CWD
-frontend/e2e/*.png
+# 下会落到 frontend/e2e/ 或 frontend/e2e/e2e/，用 ** 一并覆盖）
+frontend/e2e/**/*.png
 
 # 临时文件
 *.tmp
@@ -59,3 +60,17 @@ frontend/e2e/*.png
 backup/
 .claude
 CLAUDE.md
+
+# 运行期上传物（公司 logo 等）：与构建产物隔离，不入版本库
+backend/uploads/
+# 数据库备份导出目录（⑨ 备份脚本产物）
+db/backups/
+
+# 外部参考资料（2026-10-20）：T+12.3 数据字典压缩包与解压目录不入版本库
+docs/**/*.rar
+docs/T_12.3数据字典/
+# macOS 压缩包残留元数据
+__MACOSX/
+
+# AI 辅助生成文档的临时工作目录（脚本、预览截图），不入版本库
+.tmpdocx/

backend/README.md

@@ -114,6 +114,31 @@ app/
 **登录失败一律 400 或 403，绝不使用 401** —— 前端把 401 一律当作「清 token + 跳登录页」，
 若登录接口自身返回 401，用户输错一次密码就会触发「清空 + 跳转 + 报错」的风暴。
 
+### 报表统计接口（M4 ⑤，限管理员/财务/领导）
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/api/v1/reports/personal-detail` | 个人绩效工资明细表（FR-029：人员/月份/客户类型/产品类别/岗位筛选；响应带 `summary` 全筛选合计） |
+| GET | `/api/v1/reports/department-summary` | 部门绩效工资汇总表（FR-030：月份必填；团队基数与月结聚合行同源；12.5% 与 5% 分列；含成员内联明细、未分配桶、月结冻结对照额） |
+| GET | `/api/v1/reports/business-stats` | 业务统计表（FR-031：发货/回款/绩效为业务累计值，不随业务日期筛选变化） |
+| GET | `/api/v1/reports/payment-stats` | 回款情况统计表（FR-031：8 档天数区间恒在，空桶为 0） |
+| GET | `/api/v1/reports/payment-detail` | 回款区间下钻（`bucket` 必填，未注册编码 400） |
+| GET | `/api/v1/reports/payment-day-buckets` | 区间档位元数据（前端下拉唯一来源，禁止前端硬编码） |
+| GET | `/api/v1/reports/{code}/export` | Excel 导出（文件流非统一信封；含公司页眉/财务复核栏/领导签字栏；超 2 万行 400；行为入操作日志） |
+
+准入 `require_roles(admin, finance, leader)`（FR-030/031；FR-029 的「营销后勤授权范围内」
+待业务权限清单 #6）。前端菜单同层过滤（路由 `allowedRoles`）。
+
+### 工作台接口（M4 ⑧，限管理员/财务/领导）
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/api/v1/dashboard?month=YYYY-MM` | 四区块一次性返回：经营绩效总览（当月绩效/应付/人数/团队数/月结状态/近 6 个月趋势）、待办（待审批 + 回款未指定批次 + 同步降级）、风险预警（回款逾期/审批超时 + 同步降级）、最近动态（操作日志） |
+
+待办与预警**实时派生**（不落表、不引调度器）；预警阈值走参数体系
+（`warning.enabled` / `warning.receipt.overdue.days` / `warning.approval.timeout.days`，
+V10 种子）；⑥ T+ 同步未建，同步相关条目以 `sync_available=false` 显式降级。
+
 ## 常用命令
 
 ```bash
@@ -196,6 +221,48 @@ bcrypt 5.0 起对超过 72 字节的密码**直接抛 ValueError**（此前是
 - **留痕表的固化设计**：`ownership_change_logs` 与 `business_status_logs` 对客户/业务/人员 ID 均**无外键**（冗余固化，被引用方删除后记录仍完整可读）；RESTRICT 外键反而会把删除逼成 500。删除保护全部由服务层检查承担（人员→团队成员/客户归属引用；客户→业务引用；业务→发货/回款记录）。两张留痕表 append-only、不继承 TimestampMixin。
 - **金额契约**：schema 入参出参一律 `str`，小数超两位直接拒绝（不静默舍入）；服务层 `Decimal`，比率 `Fraction`；毛利润率出参为分数原样字符串（`"997/1000"`，同 M1 计算预览口径），前端原样展示禁止转 float。
 
+### 审批快照与方案版本化（2026-10-20 定稿，改动前先读）
+
+- **审批单带版本号与内容快照**：`approval_orders.version_no` 按 `(order_type, ref_id)` 从 1 递增，重提先撤回旧在途单、但**旧单快照不覆盖**；`snapshot_json` 统一信封 `{schema_version, order_type, captured_at, data}`，`data` 由 `approval_service.{allocation,settlement,adjustment}_content` 组装（Decimal 转 str、日期转 ISO），开关关闭的自动通过路径同样写快照。审批期间业务再改，复核者看到的仍是送审版本。
+- **两个 `version_no` 语义不同，别混用**：`business_secondary_allocations.version_no` = 方案内容第几版，**仅方案内容（参与人+比例）变化时 +1**；`approval_orders.version_no` = 同一对象第几次送审，**仅送审内容变化时 +1**。改备注不动金额 → 两者都不动；改金额 → 只有审批单版本号动；改方案比例 → 两者都动。
+- **送审内容未变不重提**：编辑业务时若**存在在途审批单**且其快照 `data` 与本次送审内容逐键相等（`approval_service.pending_matches_snapshot`，只比 `data` 不比 `captured_at`），则保留原单不撤回不重建；否则撤旧提新。方案内容未变时**不新增方案版本行**（`business_service._plan_changed` 按「人员+比例」集合比较，与行序无关）。
+- **快照的覆盖范围是「方案 + 钱 + 归属」**（业务编号/日期、客户、负责与协助人、销售额、成本额、方案参与人与比例、合计与余额），**不含产品明细行**。因此只改产品构成而金额不变时不会重提——分摊依据（谁分、分多少、基于多少钱）未变；产品明细由复核者按业务编号回业务页查看。
+- **列表不加载快照列**：快照可达上百 KB，审批单列表、工作台待办、工作台审批超时预警三处查询一律 `defer(ApprovalOrder.snapshot_json)`（与操作日志列表排除 `request_data` 同一理由，参考 `operation_log_repository.list_logs`）；详情走 `get_order` 按需读取。
+- **详情内容来源三态**：`content_source=snapshot`（送审快照）/ `live`（V11 前的历史单体无快照，只读回退当前内容并显式告警）/ `missing`（引用对象不存在且无快照）。**禁止回填历史单快照**——回填等于伪造提交时内容。
+- **二次分配方案 append-only**：`business_secondary_allocations` 行不物理删除，编辑全量替换与驳回清空只把旧行 `is_active=0`；唯一键为 `(business_id, version_no, personnel_id)`，同一版本内参与人唯一、跨版本可重复。`business_repository.list_allocations(active_only=True)` 是核算与详情回显的唯一取数口径；业务详情 `allocation_history` 返回全部版本供回溯。
+- **月结提交要锁行**：`settlement_service.submit` 取月结行必须 `for_update=True`——并发提交会让两次 `submit_order` 算出同一个审批单 `version_no`，送审次序失真。
+- **审批单 `version_no` 有唯一键兜底（V12）**：`uk_approval_orders_order_type_ref_version (order_type, ref_id, version_no)`——同一对象的第 N 次送审在库里有唯一一行。ORM 侧约束名必须与迁移 DDL 严格一致，否则 autogenerate 误判。
+- **取版本号必须是「当前读」（`approval_service._next_version`）**，两个禁忌：(a) 不能用普通 `MAX` 查询——请求级鉴权与业务共用同一 DbSession，鉴权的普通 SELECT 已把 REPEATABLE READ 快照锚定在请求开始时刻，父行锁只串行化写入时刻、**不刷新快照**，MAX 会读到旧值；(b) 不能写成 `select(func.max(...)).with_for_update()`——MySQL 官方明确「Locking clauses are not permitted in queries with aggregate functions or GROUP BY」，聚合上的 FOR UPDATE 语义无保证。正解：锁读该 ref 的现有版本行（`select(version_no)...with_for_update()`），最大值 Python 侧算（同 `no_generator` 套路）。
+- **版本号冲突的收敛口径**：`submit_order` 内不 catch、不 rollback（红线）。create 路径由外层编号重试循环整体重来（`business_service._NO_RETRY`）；编辑/月结提交路径由审计上下文统一回滚，再把 1062 翻译为 400「提交冲突（版本号生成重复），请重试」（同 `param_service` 版本号冲突模板）。唯一键是最后一道防线，不是取号正确性的前提。
+- **迁移前先修存量**：V11 把存量行 `version_no` 一律置 1，而 V11 前每次重提都新建行——同一 `(order_type, ref_id)` 存在多行 version_no=1，直接加唯一键必报 1062。V12 先重排「组内有重复」的分组（按 id 升序 1..n），其余分组不动（全量重排会改掉前端已展示过的历史版本号）。
+- **新增审批对象类型**须同时提供快照组装函数并接入 `_content_of` 的 live 回退分支，不要在各业务服务内联 JSON 结构。
+
+### 工作台口径（M4 ⑧，改动前先读）
+
+- **只读聚合**：总览只做 SQL 聚合（SUM / COUNT DISTINCT），不复用报表的部门汇总（后者加载整月台账，过重）；人数用 `COUNT(DISTINCT personnel_id)`——二次分摊拆行会让行数虚高。
+- **待办/预警实时派生**：查询即算，不建待办表/预警表。审批超时取 `approval_orders.create_time`（待审批状态）；回款逾期按「发货单 `ship_date` 超阈值且该批次无任何回款」判定，**已终止业务（status=3）排除**；回款未指定批次 = `receipts.shipment_id IS NULL`。
+- **待办按角色过滤**：`pending_statuses_for_roles`（approval_service）把当前用户角色映射到在途节点——财务只看待财务复核（status=1）、领导只看待领导审核（status=2）、admin 可看全部；多角色取并集。风险预警仍是全局经营视角，不按人裁剪。
+- **预警展示上限**：`items` 最多 20 条，`total` 是全部命中数（前端徽标用它，不能用 `items.length`）。
+- **趋势窗口**：回款趋势先按 `receipt_date` 范围过滤再按 `DATE_FORMAT` 分组，函数列不参与 WHERE，保证索引可用。
+- **同步降级**：⑥ 未建时 `sync_available=false`，前端显示「模块未启用」——不要返回 0 条冒充「无失败」。
+- **参数快照一次解析**：`warning.*` 三个阈值在每次请求只 `resolve_snapshot` 一次，多条规则复用。
+- **导出 SQL 的编码坑**：Windows 下 `alembic upgrade --sql > V*.sql` 默认按控制台 GBK 输出，`test_schema_sync` 按 UTF-8 读取会报 `UnicodeDecodeError`——必须 `PYTHONIOENCODING=utf-8 PYTHONUTF8=1` 前缀。
+
+### 报表口径（M4 ⑤，改动前先读）
+
+- **数据源固定单笔生效行**：四张报表的明细一律 `performance_ledgers.is_active=1 AND calc_type=1`；经理聚合行（`calc_type=2`）**只在部门汇总作冻结对照**（`frozen_amount`）单读。聚合行 `receipt_id` 为 NULL、`payment_days` 为 NULL，混入明细会让合同编号/天数列失真，业务统计的绩效也会被整团队聚合额污染。
+- **调整单并入**：仅 `status=2`（生效），按 `(settlement_month, personnel_id)` 并入，**不要求该人当月有台账行**（只有调整单也要出零绩效成员行）；`direction=1` 补发记 +、`2` 扣减记 −（金额恒正）。待审批/驳回/撤回的金额绝不能进报表——`report_repository.list_month_adjustments` 与调整单管理页的 `list_adjustments` 是两个口径。调整单归属跟随该人普通行的实时 `manager_id`；只有经理个人户的经理跟随本人团队。
+- **回款金额按回款单去重**：二次分摊拆行使同一回款在台账出现多行（负责人 + 参与人），回款统计的金额侧必须 `DISTINCT receipt_id` 后再求和，否则按拆行数翻倍。个人明细页不放「回款金额」列（同一金额重复展示会让合计无法自洽），金额下沉到快照下钻。
+- **部门口径** = `personnel.manager_id` 实时上溯（无独立部门表）；离职人员不按 `status` 过滤，历史业绩留在原团队；无成员经理也出 0 值行（在职经理枚举 ∪ 数据中出现的经理）。团队基数与月结聚合行同源（`services/manager_share.py` 共享模块）。
+- **全公司 5% 的发放口径**：月结只为有台账 bucket 的营销经理各生成一条聚合行（12.5%+5%），**每位经理各计一次 5%**；零成员团队无聚合行、不发 5%。报表的 `aggregate_amount` 优先取冻结聚合行、未生成月结时才用 `manager_team_share` 一次舍入预览；`team_subtotal`/`net_total` = 聚合额 + 调整净额。`team_share_total` 与 `company_share_total` 仅分列展示，两者之和与聚合额的差记入 `aggregate_rounding_diff`（分列各自 q2 会有 0.01～0.02 尾差）。
+- **对拍边界**：报表应发 = 月结 `total_payable` + 调整单净额（调整单不进月结 items）；筛选 `manager_id` 时只汇总展示团队，隐藏金额进 `other_*`，不能与全公司月结总额对拍。
+- **人员归属按行类型**：普通台账行跟随 `manager_id`；经理个人户行在 `manager.personal.included=1` 时归经理本人团队，且经理成员行**只取个人户金额**（其普通行业绩留在上级团队或未分配），保证团队基数 = 成员绩效合计。岗位判定范围必须覆盖所有成员引用的上级，否则其他经理的下属会被误判为「无经理」。按 `manager_id` 筛选时 `unassigned` 为空（语义是「仅看该经理团队」）。
+- **回款天数区间**是 8 档代码常量（`core/report_meta.py`，含「≤0 天先款后货」与「无天数」兜底桶），服务端下发元数据、前端禁止硬编码；空桶恒在且为 0。进度登记回款无台账行，不在回款统计口径内（页面注明）。
+- **导出**：openpyxl 普通 Workbook + `Decimal` 原值 + `number_format`（不写 Excel 公式）；超 `REPORT_EXPORT_MAX_ROWS`（20000）行返回 400；文本列防公式注入（`= + - @` 前缀加 `'`）；服务端文件名为 ASCII（响应头 latin-1 限制），中文名由前端 `link.download` 指定。部门汇总是**单 sheet 分块签字稿**（团队分成汇总 → 全公司 5% 单列 → 对账汇总 → 成员明细 → 未分配明细 → 签字栏）；第二块展示单经理 5%、计入次数与合计，对账块展示团队分成/全公司分成（分列）、聚合行舍入差、调整净额，应发合计 = 团队成员应付 + 未分配应付 + 各经理聚合行金额 + 调整净额合计。筛选页眉把人员/经理/客户/归属人/状态转为名称与中文标签；回款统计两个维度 sheet 共用主表筛选条件。
+- **导出审计**：`audit` 上下文覆盖取数与构建全过程，超限 400 和取数异常都会写失败操作日志（`success=0`）；成功摘要为静态报表标题。
+- **汇总 = 明细合计**：团队/公司基数由台账分桶结果直接得出，报表侧不另算一遍；未筛选时 `团队基数 + 未分配绩效 = 全公司基数`；集成测试逐项断言。
+- **岗位筛选选项**：`GET /api/v1/base/business-roles/options` 仅要求登录（含停用岗位），供财务/领导在报表中按岗位筛选；岗位管理接口仍仅管理员。
+
 ## 常见问题
 
 **起服务报 `APP_SECRET_KEY` 相关错误** —— `backend/.env` 未填或不足 32 字符。这是刻意的 fail-fast：空密钥签发 JWT 是安全问题，必须启动即失败。

backend/alembic/versions/3bca400421c6_v7_核算台账_月结_调整单四表与调整单开关种子.py

@@ -0,0 +1,632 @@
+"""V7 核算台账/月结/调整单四表与调整单开关种子
+
+Revision ID: 3bca400421c6
+Revises: 79bcc5aa98d4
+Create Date: 2026-10-16 15:54:53.000890
+
+"""
+
+from collections.abc import Sequence
+from datetime import date
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import mysql
+
+# revision identifiers, used by Alembic.
+revision: str = "3bca400421c6"
+down_revision: str | Sequence[str] | None = "79bcc5aa98d4"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """应用迁移。"""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "monthly_settlements",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "settlement_month",
+            sa.String(length=7),
+            nullable=False,
+            comment="结算月份（YYYY-MM；全表唯一）",
+        ),
+        sa.Column(
+            "status",
+            mysql.TINYINT(),
+            server_default="1",
+            nullable=False,
+            comment="状态：1草稿 2待审批 3已审定（终态=已锁定）4已驳回（回草稿）",
+        ),
+        sa.Column(
+            "total_performance",
+            sa.Numeric(precision=14, scale=2),
+            nullable=True,
+            comment="绩效金额合计（可负）",
+        ),
+        sa.Column(
+            "total_payable",
+            sa.Numeric(precision=14, scale=2),
+            nullable=True,
+            comment="应付绩效合计（可负）",
+        ),
+        sa.Column(
+            "person_count", mysql.TINYINT(), server_default="0", nullable=False, comment="结算人数"
+        ),
+        sa.Column(
+            "snapshot_json",
+            sa.JSON(),
+            nullable=True,
+            comment="月度总览快照（生成时刻的确认回款口径说明与汇总参数）",
+        ),
+        sa.Column(
+            "approval_order_no",
+            sa.String(length=32),
+            nullable=True,
+            comment="关联审批单号（冗余固化；开关关闭自动通过时也有单）",
+        ),
+        sa.Column(
+            "submitter_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=True,
+            comment="提交人ID（账号删除后置空）",
+        ),
+        sa.Column(
+            "submitter_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="提交人用户名（冗余固化）",
+        ),
+        sa.Column("locked_at", sa.DateTime(), nullable=True, comment="锁定时间（status=3 时回填）"),
+        sa.Column(
+            "locked_by", sa.String(length=64), nullable=True, comment="锁定操作人（冗余固化）"
+        ),
+        sa.Column(
+            "create_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="创建时间",
+        ),
+        sa.Column(
+            "update_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="更新时间",
+        ),
+        sa.ForeignKeyConstraint(
+            ["submitter_id"],
+            ["users.id"],
+            name=op.f("fk_monthly_settlements_submitter_id"),
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_monthly_settlements")),
+        sa.UniqueConstraint(
+            "settlement_month", name=op.f("uk_monthly_settlements_settlement_month")
+        ),
+        comment="月度结算表（按月一行；通过即锁定，锁定后走调整单）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.create_table(
+        "adjustment_orders",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "order_no",
+            sa.String(length=32),
+            nullable=False,
+            comment="调整单号，自动生成 TZ{YYYYMMDD}-{4位当日序号}",
+        ),
+        sa.Column(
+            "settlement_month",
+            sa.String(length=7),
+            nullable=False,
+            comment="调整月份（YYYY-MM；跨月规则待澄清 #9 前不限制）",
+        ),
+        sa.Column(
+            "personnel_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="调整人员ID（personnel.id）",
+        ),
+        sa.Column(
+            "personnel_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="调整人员姓名（冗余固化）",
+        ),
+        sa.Column("direction", mysql.TINYINT(), nullable=False, comment="方向：1补发 2扣减"),
+        sa.Column(
+            "amount",
+            sa.Numeric(precision=14, scale=2),
+            nullable=False,
+            comment="调整金额（恒正，方向表达语义）",
+        ),
+        sa.Column(
+            "reason",
+            sa.String(length=255),
+            nullable=False,
+            comment="扣补说明（必填，审批与追溯锚点）",
+        ),
+        sa.Column(
+            "status",
+            mysql.TINYINT(),
+            server_default="1",
+            nullable=False,
+            comment="状态：1待审批 2已生效 3已驳回 4已撤回",
+        ),
+        sa.Column(
+            "submitter_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=True,
+            comment="提交人ID（账号删除后置空）",
+        ),
+        sa.Column(
+            "submitter_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="提交人用户名（冗余固化）",
+        ),
+        sa.Column(
+            "create_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="创建时间",
+        ),
+        sa.Column(
+            "update_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="更新时间",
+        ),
+        sa.ForeignKeyConstraint(
+            ["personnel_id"],
+            ["personnel.id"],
+            name=op.f("fk_adjustment_orders_personnel_id"),
+            ondelete="RESTRICT",
+        ),
+        sa.ForeignKeyConstraint(
+            ["submitter_id"],
+            ["users.id"],
+            name=op.f("fk_adjustment_orders_submitter_id"),
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_adjustment_orders")),
+        sa.UniqueConstraint("order_no", name=op.f("uk_adjustment_orders_order_no")),
+        comment="调整单表（已锁定月份的补发/扣减；走审批；生效后不回写月结快照）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.create_table(
+        "settlement_items",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "settlement_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="月结ID（monthly_settlements.id；头删明细随删）",
+        ),
+        sa.Column(
+            "personnel_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="结算人员ID（personnel.id）",
+        ),
+        sa.Column(
+            "personnel_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="结算人员姓名（冗余固化）",
+        ),
+        sa.Column(
+            "role_code", sa.String(length=32), nullable=False, comment="岗位编码（主岗，聚合锚点）"
+        ),
+        sa.Column(
+            "calc_type",
+            mysql.TINYINT(),
+            nullable=False,
+            comment="核算类型：1单笔回款 2经理团队聚合",
+        ),
+        sa.Column(
+            "performance_sum",
+            sa.Numeric(precision=14, scale=2),
+            nullable=False,
+            comment="绩效金额合计（可负；聚合行排除经理个人户业绩，#12 暂口径）",
+        ),
+        sa.Column(
+            "payable_sum",
+            sa.Numeric(precision=14, scale=2),
+            nullable=False,
+            comment="应付绩效合计（可负）",
+        ),
+        sa.Column(
+            "basic_amount",
+            sa.Numeric(precision=14, scale=2),
+            nullable=True,
+            comment="月工资标准（personnel.salary_standard 当月快照）",
+        ),
+        sa.Column(
+            "salary_mode",
+            sa.String(length=16),
+            nullable=True,
+            comment="月工资口径快照：INCLUDE/DEDUCT/EXCLUDE",
+        ),
+        sa.Column(
+            "net_amount",
+            sa.Numeric(precision=14, scale=2),
+            nullable=True,
+            comment="净工资 = 绩效±基本工资（按口径；试用期 0）",
+        ),
+        sa.Column(
+            "is_probation",
+            mysql.TINYINT(),
+            server_default="0",
+            nullable=False,
+            comment="试用期：1绩效照算不发放（net=0，超年累计记 note）0否",
+        ),
+        sa.Column(
+            "probation_note",
+            sa.String(length=255),
+            nullable=True,
+            comment="试用期说明（年累计超阈值部分年底一次性结算）",
+        ),
+        sa.Column(
+            "snapshot_json", sa.JSON(), nullable=True, comment="个人明细快照（台账行引用列表）"
+        ),
+        sa.ForeignKeyConstraint(
+            ["personnel_id"],
+            ["personnel.id"],
+            name=op.f("fk_settlement_items_personnel_id"),
+            ondelete="RESTRICT",
+        ),
+        sa.ForeignKeyConstraint(
+            ["settlement_id"],
+            ["monthly_settlements.id"],
+            name=op.f("fk_settlement_items_settlement_id"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_settlement_items")),
+        comment="月结明细表（按人固化；支持负数工资；锁定后只读）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.create_table(
+        "performance_ledgers",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "receipt_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=True,
+            comment="回款ID（receipts.id；聚合行可为 NULL）",
+        ),
+        sa.Column(
+            "calc_version",
+            mysql.TINYINT(),
+            server_default="1",
+            nullable=False,
+            comment="核算版本（重算+1，旧行 is_active=0）",
+        ),
+        sa.Column(
+            "is_active",
+            mysql.TINYINT(),
+            server_default="1",
+            nullable=False,
+            comment="生效标记：1当前生效 0已被重算替代（重算受控 UPDATE 例外）",
+        ),
+        sa.Column(
+            "calc_type",
+            mysql.TINYINT(),
+            server_default="1",
+            nullable=False,
+            comment="核算类型：1单笔回款 2经理团队聚合（月度）",
+        ),
+        sa.Column(
+            "business_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="业务ID（固化无外键；聚合行为该经理名下首行业务ID，报表下钻锚点）",
+        ),
+        sa.Column(
+            "business_no",
+            sa.String(length=32),
+            nullable=False,
+            comment="业务编号（冗余固化，列表免联查）",
+        ),
+        sa.Column(
+            "personnel_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="归属营销人员ID（personnel.id；核算归属锚点）",
+        ),
+        sa.Column(
+            "personnel_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="归属营销人员姓名（冗余固化）",
+        ),
+        sa.Column(
+            "role_code",
+            sa.String(length=32),
+            nullable=False,
+            comment="岗位编码（business_roles.role_code，计提公式锚点）",
+        ),
+        sa.Column(
+            "customer_type",
+            sa.String(length=32),
+            nullable=False,
+            comment="客户分类：personal/manager_personal/enterprise",
+        ),
+        sa.Column(
+            "product_category",
+            sa.String(length=32),
+            nullable=False,
+            comment="产品类别：municipal_water/rail_transit/mixed（混合业务，行级明细入 snapshot_json）",
+        ),
+        sa.Column("ship_date", sa.Date(), nullable=True, comment="发货日期（回款天数基准）"),
+        sa.Column(
+            "receipt_date",
+            sa.Date(),
+            nullable=False,
+            comment="回款日期（参数版本匹配日，裁决 #11）",
+        ),
+        sa.Column(
+            "payment_days",
+            sa.Integer(),
+            nullable=True,
+            comment="回款天数（发货日首日计第 1 天；未指定批次为 NULL；先款后货照实负值）",
+        ),
+        sa.Column(
+            "rate_text",
+            sa.String(length=32),
+            nullable=False,
+            comment="计提比例原文（如 4/360，防 Fraction 截断；聚合行存 12.5%/5% 结构说明）",
+        ),
+        sa.Column(
+            "converted_profit",
+            sa.Numeric(precision=14, scale=2),
+            nullable=True,
+            comment="折算毛利润额（可负；混合业务为各行汇总）",
+        ),
+        sa.Column(
+            "performance_amount",
+            sa.Numeric(precision=14, scale=2),
+            nullable=True,
+            comment="绩效金额（可负，裁决：负绩效照算不归零）",
+        ),
+        sa.Column(
+            "barter_applied",
+            mysql.TINYINT(),
+            server_default="0",
+            nullable=False,
+            comment="以物抵顶折算：1已按 80% 折算 0否",
+        ),
+        sa.Column(
+            "weight_r",
+            sa.Integer(),
+            nullable=True,
+            comment="支付权重 R（回款占销售额百分比向下取整）",
+        ),
+        sa.Column(
+            "payment_weight",
+            sa.Numeric(precision=7, scale=6),
+            nullable=True,
+            comment="支付权重系数 R×R（展示用）",
+        ),
+        sa.Column(
+            "payable_amount",
+            sa.Numeric(precision=14, scale=2),
+            nullable=True,
+            comment="当期应付绩效（绩效 × 支付权重；聚合行为当月汇总）",
+        ),
+        sa.Column(
+            "settlement_month",
+            sa.String(length=7),
+            nullable=False,
+            comment="归属月（回款日期所在月，YYYY-MM；月结与报表维度）",
+        ),
+        sa.Column(
+            "is_probation",
+            mysql.TINYINT(),
+            server_default="0",
+            nullable=False,
+            comment="试用期：1照算不发放 0否",
+        ),
+        sa.Column(
+            "missing_cost",
+            mysql.TINYINT(),
+            server_default="0",
+            nullable=False,
+            comment="成本缺失：1有明细行缺成本（该行毛利按 0 计）0否",
+        ),
+        sa.Column(
+            "snapshot_json",
+            sa.JSON(),
+            nullable=True,
+            comment="计算快照（所用参数版本与行级折算明细，重算可回溯）",
+        ),
+        sa.Column(
+            "settlement_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=True,
+            comment="所属月结ID（月结生成时回填；NULL=未入结）",
+        ),
+        sa.Column(
+            "calc_reason",
+            sa.String(length=255),
+            nullable=True,
+            comment="核算/重算原因（重算必填留痕）",
+        ),
+        sa.Column("remark", sa.String(length=255), nullable=True, comment="备注"),
+        sa.Column(
+            "create_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="创建时间",
+        ),
+        sa.Column(
+            "update_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="更新时间",
+        ),
+        sa.ForeignKeyConstraint(
+            ["personnel_id"],
+            ["personnel.id"],
+            name=op.f("fk_performance_ledgers_personnel_id"),
+            ondelete="RESTRICT",
+        ),
+        sa.ForeignKeyConstraint(
+            ["receipt_id"],
+            ["receipts.id"],
+            name=op.f("fk_performance_ledgers_receipt_id"),
+            ondelete="RESTRICT",
+        ),
+        sa.ForeignKeyConstraint(
+            ["settlement_id"],
+            ["monthly_settlements.id"],
+            name=op.f("fk_performance_ledgers_settlement_id"),
+            ondelete="RESTRICT",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_performance_ledgers")),
+        sa.UniqueConstraint(
+            "receipt_id", "calc_version", name="uk_performance_ledgers_receipt_id_calc_version"
+        ),
+        comment="绩效核算台账表（append-only 版本行；重算插新版本旧行仅翻 is_active）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.create_index(
+        "idx_performance_ledgers_business_id", "performance_ledgers", ["business_id"], unique=False
+    )
+    op.create_index(
+        "idx_performance_ledgers_month_active",
+        "performance_ledgers",
+        ["settlement_month", "is_active"],
+        unique=False,
+    )
+    op.create_index(
+        "idx_performance_ledgers_month_personnel_type",
+        "performance_ledgers",
+        ["settlement_month", "personnel_id", "calc_type"],
+        unique=False,
+    )
+    op.create_index(
+        "idx_performance_ledgers_personnel_id",
+        "performance_ledgers",
+        ["personnel_id"],
+        unique=False,
+    )
+    op.alter_column(
+        "approval_orders",
+        "order_type",
+        existing_type=mysql.TINYINT(),
+        comment="审批对象类型：1二次分配方案 2月度结算 3调整单",
+        existing_comment="审批对象类型：1二次分配方案 2月度结算（预留）",
+        existing_nullable=False,
+    )
+    # ### end Alembic commands ###
+
+    # ---- 种子：调整单审批开关（V6 写法先例；definitions id 19 / values id 22）----
+    op.bulk_insert(
+        sa.table(
+            "param_definitions",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_code", sa.String),
+            sa.column("param_name", sa.String),
+            sa.column("param_group", sa.String),
+            sa.column("value_type", sa.String),
+            sa.column("unit", sa.String),
+            sa.column("dimension_type", sa.String),
+            sa.column("options_text", sa.String),
+            sa.column("default_value", sa.String),
+            sa.column("value_min", sa.String),
+            sa.column("value_max", sa.String),
+            sa.column("description", sa.String),
+            sa.column("sort_order", sa.Integer),
+            sa.column("status", sa.Integer),
+        ),
+        [
+            {
+                "id": 19,
+                "param_code": "approval.adjustment.enabled",
+                "param_name": "调整单审批开关",
+                "param_group": "审批开关",
+                "value_type": "BOOL",
+                "unit": None,
+                "dimension_type": "NONE",
+                "options_text": None,
+                "default_value": "0",
+                "value_min": None,
+                "value_max": None,
+                "description": (
+                    "0=调整单提交即生效（系统自动通过留痕）；1=走财务复核→领导审核审批流。"
+                    "调整单是已锁定月份补发/扣减的唯一通道"
+                ),
+                "sort_order": 19,
+                "status": 1,
+            }
+        ],
+    )
+    op.bulk_insert(
+        sa.table(
+            "param_values",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_id", sa.BigInteger),
+            sa.column("dimension_value", sa.String),
+            sa.column("effective_date", sa.Date),
+            sa.column("value_text", sa.String),
+            sa.column("batch_id", sa.BigInteger),
+        ),
+        [
+            {
+                "id": 22,
+                "param_id": 19,
+                "dimension_value": "",
+                "effective_date": date(2026, 1, 1),
+                "value_text": "0",
+                "batch_id": 1,
+            }
+        ],
+    )
+
+
+def downgrade() -> None:
+    """回滚迁移。
+
+    整表回滚只保留 `op.drop_table`（V1/V3/V6 先例：外键唯一支撑索引单独
+    drop 会报 MySQL 1553）。行级种子（param_definitions 19 / param_values 22）
+    的宿主表由 V3 建、本迁移只插行，须显式 DELETE 否则重放 upgrade 撞唯一键。
+    删除顺序：先删引用方（ledger/items），再删被引用方（头表/调整单）。
+    """
+    op.drop_table("performance_ledgers")
+    op.drop_table("settlement_items")
+    op.drop_table("adjustment_orders")
+    op.drop_table("monthly_settlements")
+    op.alter_column(
+        "approval_orders",
+        "order_type",
+        existing_type=mysql.TINYINT(),
+        comment="审批对象类型：1二次分配方案 2月度结算（预留）",
+        existing_comment="审批对象类型：1二次分配方案 2月度结算 3调整单",
+        existing_nullable=False,
+    )
+    op.execute("DELETE FROM param_values WHERE id = 22")
+    op.execute("DELETE FROM param_definitions WHERE id = 19")

backend/alembic/versions/79bcc5aa98d4_v6_系统设置_二次分配_审批表与角色参数种子.py

@@ -0,0 +1,441 @@
+"""V6 系统设置/二次分配/审批表与角色参数种子
+
+Revision ID: 79bcc5aa98d4
+Revises: 8efc189b131f
+Create Date: 2026-10-15 15:42:13.467447
+
+"""
+
+from collections.abc import Sequence
+from datetime import date
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import mysql
+
+# revision identifiers, used by Alembic.
+revision: str = "79bcc5aa98d4"
+down_revision: str | Sequence[str] | None = "8efc189b131f"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """应用迁移。"""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "system_settings",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "company_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="公司名称（登录页与导出页眉展示）",
+        ),
+        sa.Column(
+            "logo_path",
+            sa.String(length=255),
+            nullable=True,
+            comment="logo 相对路径（文件存 uploads/logo/，null=未上传使用默认）",
+        ),
+        sa.Column(
+            "create_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="创建时间",
+        ),
+        sa.Column(
+            "update_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="更新时间",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_system_settings")),
+        comment="系统设置表（公司信息，全系统单行）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.create_table(
+        "approval_orders",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "order_no",
+            sa.String(length=32),
+            nullable=False,
+            comment="审批单号，自动生成 AP{YYYYMMDD}-{4位当日序号}",
+        ),
+        sa.Column(
+            "order_type",
+            mysql.TINYINT(),
+            nullable=False,
+            comment="审批对象类型：1二次分配方案 2月度结算（预留）",
+        ),
+        sa.Column(
+            "ref_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="引用对象ID（order_type=1 时为 businesses.id；固化无外键，删除保护由服务层承担）",
+        ),
+        sa.Column(
+            "refer_no",
+            sa.String(length=32),
+            nullable=False,
+            comment="引用对象单号（冗余固化，列表页免联查）",
+        ),
+        sa.Column(
+            "status",
+            mysql.TINYINT(),
+            server_default="1",
+            nullable=False,
+            comment="审批状态：1待财务复核 2待领导审核 3已通过 4已驳回 5已撤回",
+        ),
+        sa.Column(
+            "submitter_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=True,
+            comment="提交人ID（账号删除后置空）",
+        ),
+        sa.Column(
+            "submitter_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="提交人用户名（冗余固化）",
+        ),
+        sa.Column(
+            "create_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="创建时间",
+        ),
+        sa.Column(
+            "update_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="更新时间",
+        ),
+        sa.ForeignKeyConstraint(
+            ["submitter_id"],
+            ["users.id"],
+            name=op.f("fk_approval_orders_submitter_id"),
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_approval_orders")),
+        sa.UniqueConstraint("order_no", name=op.f("uk_approval_orders_order_no")),
+        comment="审批单表（营销后勤提交→财务复核→领导审核；开关关闭时自动通过留痕）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.create_index(
+        "idx_approval_orders_type_status", "approval_orders", ["order_type", "status"], unique=False
+    )
+    op.create_table(
+        "approval_steps",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "order_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="审批单ID（approval_orders.id；单删记录随删）",
+        ),
+        sa.Column(
+            "node",
+            mysql.TINYINT(),
+            nullable=False,
+            comment="审批节点：0撤回留痕 1财务复核 2领导审核",
+        ),
+        sa.Column(
+            "action", mysql.TINYINT(), nullable=False, comment="动作：1通过 2驳回 3自动通过 4撤回"
+        ),
+        sa.Column(
+            "opinion", sa.String(length=255), nullable=True, comment="审批意见（驳回时填写）"
+        ),
+        sa.Column(
+            "operator_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=True,
+            comment="操作人ID（自动通过/系统动作置空）",
+        ),
+        sa.Column(
+            "operator_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="操作人用户名（冗余固化；系统动作记「系统」）",
+        ),
+        sa.Column(
+            "create_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="创建时间",
+        ),
+        sa.ForeignKeyConstraint(
+            ["operator_id"],
+            ["users.id"],
+            name=op.f("fk_approval_steps_operator_id"),
+            ondelete="SET NULL",
+        ),
+        sa.ForeignKeyConstraint(
+            ["order_id"],
+            ["approval_orders.id"],
+            name=op.f("fk_approval_steps_order_id"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_approval_steps")),
+        comment="审批节点记录表（append-only；自动通过/撤回均有留痕）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.create_index("idx_approval_steps_order_id", "approval_steps", ["order_id"], unique=False)
+    op.create_table(
+        "business_secondary_allocations",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "business_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="业务ID（businesses.id；业务删除随删）",
+        ),
+        sa.Column(
+            "personnel_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="参与业务员ID（personnel.id；被方案引用禁删）",
+        ),
+        sa.Column(
+            "personnel_name",
+            sa.String(length=64),
+            nullable=False,
+            comment="参与业务员姓名（冗余固化，离职后回显有名）",
+        ),
+        sa.Column(
+            "ratio",
+            sa.Numeric(precision=5, scale=2),
+            nullable=False,
+            comment="分摊比例（0-100 两位小数；不要求合计满额，余额归属待澄清#2）",
+        ),
+        sa.Column(
+            "create_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="创建时间",
+        ),
+        sa.Column(
+            "update_time",
+            sa.DateTime(),
+            server_default=sa.text("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP"),
+            nullable=False,
+            comment="更新时间",
+        ),
+        sa.ForeignKeyConstraint(
+            ["business_id"],
+            ["businesses.id"],
+            name=op.f("fk_business_secondary_allocations_business_id"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["personnel_id"],
+            ["personnel.id"],
+            name=op.f("fk_business_secondary_allocations_personnel_id"),
+            ondelete="RESTRICT",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_business_secondary_allocations")),
+        sa.UniqueConstraint(
+            "business_id",
+            "personnel_id",
+            name="uk_business_secondary_allocations_business_personnel",
+        ),
+        comment="业务二次分配方案明细表（合同建立时录入；比例不要求合计满额，余额归属待澄清）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.create_index(
+        "idx_business_secondary_allocations_business_id",
+        "business_secondary_allocations",
+        ["business_id"],
+        unique=False,
+    )
+    op.create_index(
+        "idx_business_secondary_allocations_personnel_id",
+        "business_secondary_allocations",
+        ["personnel_id"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+    # ---- 种子数据（生产与开发同源；写法沿用 V1/V3 迁移先例）----
+
+    # 三个审批职能登录角色（2026-10-15 复核审批补充需求；roles 表无 is_builtin
+    # 列，内置保护由 role_service 的 BUILTIN_ROLE_CODES 白名单承担）
+    op.bulk_insert(
+        sa.table(
+            "roles",
+            sa.column("role_code", sa.String),
+            sa.column("role_name", sa.String),
+            sa.column("description", sa.String),
+            sa.column("sort_order", sa.Integer),
+        ),
+        [
+            {
+                "role_code": "marketing_ops",
+                "role_name": "营销后勤",
+                "description": "提交与录入（审批链第一节点：月结/二次分配提交）",
+                "sort_order": 3,
+            },
+            {
+                "role_code": "finance",
+                "role_name": "财务",
+                "description": "复核（审批链第二节点）",
+                "sort_order": 4,
+            },
+            {
+                "role_code": "leader",
+                "role_name": "领导",
+                "description": "审核（审批链第三节点；全览只读）",
+                "sort_order": 5,
+            },
+        ],
+    )
+
+    # 审批开关参数定义（param_definitions id 沿用 V3 种子的显式 id 方案接续 17/18）
+    op.bulk_insert(
+        sa.table(
+            "param_definitions",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_code", sa.String),
+            sa.column("param_name", sa.String),
+            sa.column("param_group", sa.String),
+            sa.column("value_type", sa.String),
+            sa.column("unit", sa.String),
+            sa.column("dimension_type", sa.String),
+            sa.column("options_text", sa.String),
+            sa.column("default_value", sa.String),
+            sa.column("value_min", sa.String),
+            sa.column("value_max", sa.String),
+            sa.column("description", sa.String),
+            sa.column("sort_order", sa.Integer),
+            sa.column("status", sa.Integer),
+        ),
+        [
+            {
+                "id": 17,
+                "param_code": "approval.secondary_allocation.enabled",
+                "param_name": "二次分配审批开关",
+                "param_group": "审批开关",
+                "value_type": "BOOL",
+                "unit": None,
+                "dimension_type": "NONE",
+                "options_text": None,
+                "default_value": "0",
+                "value_min": None,
+                "value_max": None,
+                "description": (
+                    "0=二次分配方案提交即生效（系统自动通过全节点留痕，留痕不断链）；"
+                    "1=提交后进入财务复核→领导审核审批流（2026-10-15 复核审批补充需求）"
+                ),
+                "sort_order": 17,
+                "status": 1,
+            },
+            {
+                "id": 18,
+                "param_code": "approval.monthly_settlement.enabled",
+                "param_name": "月度结算审批开关",
+                "param_group": "审批开关",
+                "value_type": "BOOL",
+                "unit": None,
+                "dimension_type": "NONE",
+                "options_text": None,
+                "default_value": "0",
+                "value_min": None,
+                "value_max": None,
+                "description": (
+                    "预留参数：月度结算审批链开关（M3 ④ 月结子块接入时消费）；"
+                    "0=结算生成即生效，1=走财务复核→领导审核审批流"
+                ),
+                "sort_order": 18,
+                "status": 1,
+            },
+        ],
+    )
+
+    # 审批开关联动批次条目（batch_id=1 即 V3 的「初始版本」批次；BOOL 无维度行，
+    # 生效日期 2026-01-01 对齐其他支付环节种子）
+    op.bulk_insert(
+        sa.table(
+            "param_values",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_id", sa.BigInteger),
+            sa.column("dimension_value", sa.String),
+            sa.column("effective_date", sa.Date),
+            sa.column("value_text", sa.String),
+            sa.column("batch_id", sa.BigInteger),
+        ),
+        [
+            {
+                "id": 20,
+                "param_id": 17,
+                "dimension_value": "",
+                "effective_date": date(2026, 1, 1),
+                "value_text": "0",
+                "batch_id": 1,
+            },
+            {
+                "id": 21,
+                "param_id": 18,
+                "dimension_value": "",
+                "effective_date": date(2026, 1, 1),
+                "value_text": "0",
+                "batch_id": 1,
+            },
+        ],
+    )
+
+    # 公司信息单行（system_settings 恒为一行，id=1 由迁移保底）
+    op.bulk_insert(
+        sa.table(
+            "system_settings",
+            sa.column("id", sa.BigInteger),
+            sa.column("company_name", sa.String),
+            sa.column("logo_path", sa.String),
+        ),
+        [
+            {"id": 1, "company_name": "衍水集团", "logo_path": None},
+        ],
+    )
+
+
+def downgrade() -> None:
+    """回滚迁移。
+
+    整表回滚只保留 `op.drop_table` —— DROP TABLE 会连带删除索引与外键。
+    autogenerate 原样输出的逐个 `op.drop_index` 会失败：idx_approval_steps_order_id
+    与 idx_business_secondary_allocations_personnel_id 分别是外键的唯一支撑索引，
+    单独删除被 MySQL 拒绝（errno 1553），回滚会中断在半途。
+    删除顺序：先删引用方（approval_steps/二次分配），再删被引用方。
+    行级种子反向清理：roles/param_definitions/param_values 三表由 V1/V3 建、
+    本迁移只插行（roles 三角色、参数 17/18 及其版本条目），drop_table
+    不会带走，须显式 DELETE，否则重放 upgrade 时唯一键冲突。
+    """
+    op.drop_table("business_secondary_allocations")
+    op.drop_table("approval_steps")
+    op.drop_table("approval_orders")
+    op.drop_table("system_settings")
+    op.execute("DELETE FROM param_values WHERE id IN (20, 21)")
+    op.execute("DELETE FROM param_definitions WHERE id IN (17, 18)")
+    op.execute("DELETE FROM roles WHERE role_code IN ('marketing_ops', 'finance', 'leader')")

backend/alembic/versions/7f4f7b918bc4_v12_审批单版本号唯一键.py

@@ -0,0 +1,71 @@
+"""v12 审批单版本号唯一键
+
+Revision ID: 7f4f7b918bc4
+Revises: f3a8c2d61b47
+Create Date: 2026-10-21 10:15:00.000000
+
+给 ``approval_orders`` 加 ``(order_type, ref_id, version_no)`` 唯一键，兜住
+「同一引用对象的第几次送审」在并发下算重。
+
+**加键前必须先重排存量**：V11 迁移用 ``ADD COLUMN version_no INT NOT NULL
+DEFAULT 1`` 把存量行一律置 1，而 V11 之前的每次重提都是**新建行**（撤回
+只改旧单 status，行不删）。于是任何有 V11 前审批历史的库里，同一
+``(order_type, ref_id)`` 存在多行且 ``version_no`` 全为 1——直接
+``ADD CONSTRAINT`` 必报 1062，迁移会停在半途。
+
+重排只针对「组内有重复」的分组（``COUNT(*) > COUNT(DISTINCT version_no)``），
+按 id 升序重排为 1..n；其余分组一个字节都不动——全量重排会把前端已展示
+过的历史版本号（``V{{ version_no }}``）改掉，属于用户可见的历史数据篡改。
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "7f4f7b918bc4"
+down_revision: str | Sequence[str] | None = "f3a8c2d61b47"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+_UK = "uk_approval_orders_order_type_ref_version"
+
+
+def upgrade() -> None:
+    """先重排存量重复的版本号，再加唯一键。"""
+    # 重排：只动「组内有重复版本号」的分组，按 id 升序编 1..n。
+    # 用派生表内联而非临时表——同一张临时表被 JOIN 两侧引用会报 1137
+    # "Can't reopen table"。
+    op.execute(
+        "UPDATE approval_orders ao "
+        "JOIN (SELECT id, ROW_NUMBER() OVER ("
+        "  PARTITION BY order_type, ref_id ORDER BY id) AS rn "
+        "  FROM approval_orders "
+        "  WHERE (order_type, ref_id) IN ("
+        "    SELECT order_type, ref_id FROM approval_orders "
+        "    GROUP BY order_type, ref_id "
+        "    HAVING COUNT(*) > COUNT(DISTINCT version_no))) t "
+        "ON ao.id = t.id "
+        "SET ao.version_no = t.rn"
+    )
+    # 幂等 guard：MySQL DDL 隐式提交，若加键成功而版本号未落盘，
+    # 重跑会报 1091（键已存在）。写法沿用 V9 先例。
+    op.execute(
+        "SET @uk_exists := (SELECT COUNT(*) FROM information_schema.TABLE_CONSTRAINTS "
+        "WHERE CONSTRAINT_SCHEMA = DATABASE() AND TABLE_NAME = 'approval_orders' "
+        f"AND CONSTRAINT_NAME = '{_UK}')"
+    )
+    op.execute(
+        "SET @ddl := IF(@uk_exists = 0, "
+        f"'ALTER TABLE approval_orders ADD CONSTRAINT {_UK} "
+        "UNIQUE (order_type, ref_id, version_no)', 'DO 0')"
+    )
+    op.execute("PREPARE stmt FROM @ddl")
+    op.execute("EXECUTE stmt")
+    op.execute("DEALLOCATE PREPARE stmt")
+
+
+def downgrade() -> None:
+    """删唯一键。唯一键本质是索引，DROP INDEX 不校验数据，存量是否已有
+    重复 version_no 与删索引无关；重排结果也不回滚（版本号保持 1..n 连续）。"""
+    op.execute(f"ALTER TABLE approval_orders DROP INDEX {_UK}")

backend/alembic/versions/90653814a421_v10_工作台预警规则参数.py

@@ -0,0 +1,143 @@
+"""v10 工作台预警规则参数
+
+Revision ID: 90653814a421
+Revises: ba0217f5091b
+Create Date: 2026-10-19 17:55:48.892998
+
+新增风险预警三条参数（M4 ⑧ 工作台，澄清 #10「做成参数化规则便于调整」）：
+- warning.enabled：总开关（默认 1）
+- warning.receipt.overdue.days：发货后逾期天数（默认 90）
+- warning.approval.timeout.days：审批超时天数（默认 3）
+
+「同步连续失败」规则依赖 ⑥ T+ 同步，模块未建前不设参数、不产生条目。
+"""
+from collections.abc import Sequence
+from datetime import date
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '90653814a421'
+down_revision: str | Sequence[str] | None = 'ba0217f5091b'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+_EFFECTIVE_DATE = date(2026, 10, 19)
+
+
+def upgrade() -> None:
+    """种入三个预警参数定义与生效值（append-only 时点化）。"""
+    op.bulk_insert(
+        sa.table(
+            "param_definitions",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_code", sa.String),
+            sa.column("param_name", sa.String),
+            sa.column("param_group", sa.String),
+            sa.column("value_type", sa.String),
+            sa.column("unit", sa.String),
+            sa.column("dimension_type", sa.String),
+            sa.column("options_text", sa.String),
+            sa.column("default_value", sa.String),
+            sa.column("value_min", sa.String),
+            sa.column("value_max", sa.String),
+            sa.column("description", sa.String),
+            sa.column("sort_order", sa.Integer),
+            sa.column("status", sa.Integer),
+        ),
+        [
+            {
+                "id": 21,
+                "param_code": "warning.enabled",
+                "param_name": "风险预警总开关",
+                "param_group": "预警规则",
+                "value_type": "BOOL",
+                "unit": None,
+                "dimension_type": "NONE",
+                "options_text": None,
+                "default_value": "1",
+                "value_min": None,
+                "value_max": None,
+                "description": "工作台风险预警区块总开关：0=关闭（不扫描不展示） 1=开启（默认）",
+                "sort_order": 21,
+                "status": 1,
+            },
+            {
+                "id": 22,
+                "param_code": "warning.receipt.overdue.days",
+                "param_name": "回款逾期天数阈值",
+                "param_group": "预警规则",
+                "value_type": "INT",
+                "unit": "天",
+                "dimension_type": "NONE",
+                "options_text": None,
+                "default_value": "90",
+                "value_min": "1",
+                "value_max": None,
+                "description": "发货后超过该天数仍未回款的发货批次触发预警（澄清 #10 建议默认 90 天）",
+                "sort_order": 22,
+                "status": 1,
+            },
+            {
+                "id": 23,
+                "param_code": "warning.approval.timeout.days",
+                "param_name": "审批超时天数阈值",
+                "param_group": "预警规则",
+                "value_type": "INT",
+                "unit": "天",
+                "dimension_type": "NONE",
+                "options_text": None,
+                "default_value": "3",
+                "value_min": "1",
+                "value_max": None,
+                "description": "待审批单提交后超过该天数未处理触发预警（澄清 #10 建议默认 3 天）",
+                "sort_order": 23,
+                "status": 1,
+            },
+        ],
+    )
+    op.bulk_insert(
+        sa.table(
+            "param_values",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_id", sa.BigInteger),
+            sa.column("dimension_value", sa.String),
+            sa.column("effective_date", sa.Date),
+            sa.column("value_text", sa.String),
+            sa.column("batch_id", sa.BigInteger),
+        ),
+        [
+            {
+                "id": 26,
+                "param_id": 21,
+                "dimension_value": "",
+                "effective_date": _EFFECTIVE_DATE,
+                "value_text": "1",
+                "batch_id": 1,
+            },
+            {
+                "id": 27,
+                "param_id": 22,
+                "dimension_value": "",
+                "effective_date": _EFFECTIVE_DATE,
+                "value_text": "90",
+                "batch_id": 1,
+            },
+            {
+                "id": 28,
+                "param_id": 23,
+                "dimension_value": "",
+                "effective_date": _EFFECTIVE_DATE,
+                "value_text": "3",
+                "batch_id": 1,
+            },
+        ],
+    )
+
+
+def downgrade() -> None:
+    """回滚种子行（行级种子不会被 drop_table 带走，必须显式删除）。"""
+    op.execute("DELETE FROM param_values WHERE id IN (26, 27, 28)")
+    op.execute("DELETE FROM param_definitions WHERE id IN (21, 22, 23)")

backend/alembic/versions/ba0217f5091b_v9_二次分配唯一键补齐.py

@@ -0,0 +1,51 @@
+"""V9：business_secondary_allocations 唯一键补齐（存量库自愈）。
+
+背景：uk(business_id, personnel_id) 是随「就地修改已发布的 V6 迁移」加入的
+（V6 建表语句里已含、硬编码名）；**旧 V6 已应用的存量库 upgrade 到当前
+head 时不会重放 V6**，拿不到该约束，V8 也未补加——两条升级路径的库结构
+漂移（test_schema_sync 只比对表/列集合，约束级漂移拦不住）。
+
+本迁移是**幂等条件式**：约束已存在（新库 / init-dev 重置库 / 已重建的
+开发库）时跳过，不存在（旧 V6 升级库）时补加，避免重复约束名 errno 1826。
+语句写成裸 SQL 而非 op.create_unique_constraint——后者在 --sql 离线导出
+时会无条件输出 DDL，无法携带存在性判断。
+
+注意：补键时若表内已存在重复 (business_id, personnel_id) 数据，ADD
+CONSTRAINT 会失败（有意如此：先由人工清理重复数据再升级，不做静默去重）。
+"""
+
+from alembic import op
+
+revision: str = "ba0217f5091b"
+down_revision: str | None = "c7d2e5a81f30"
+branch_labels = None
+depends_on = None
+
+_UK_NAME = "uk_business_secondary_allocations_business_personnel"
+
+
+def upgrade() -> None:
+    """条件式补唯一键（见模块 docstring 的背景与幂等说明）。"""
+    op.execute(
+        "SET @uk_exists := ("
+        "SELECT COUNT(*) FROM information_schema.TABLE_CONSTRAINTS "
+        "WHERE CONSTRAINT_SCHEMA = DATABASE() "
+        "AND TABLE_NAME = 'business_secondary_allocations' "
+        f"AND CONSTRAINT_NAME = '{_UK_NAME}'"
+        ")"
+    )
+    op.execute(
+        "SET @ddl := IF(@uk_exists = 0, "
+        f"'ALTER TABLE business_secondary_allocations ADD CONSTRAINT {_UK_NAME} "
+        "UNIQUE (business_id, personnel_id)', "
+        "'DO 0')"
+    )
+    op.execute("PREPARE stmt FROM @ddl")
+    op.execute("EXECUTE stmt")
+    op.execute("DEALLOCATE PREPARE stmt")
+
+
+def downgrade() -> None:
+    """有意不撤键：新库由 V6 建表即带该约束、并非本迁移首创，撤掉会让
+    降级路径产生新的漂移；确需撤销请人工评估后执行 DROP INDEX。
+    """

backend/alembic/versions/c7d2e5a81f30_v8_业务答复口径落实_审批开关默认_试用期参数_经理基数开关_台账分摊唯一键.py

@@ -0,0 +1,193 @@
+"""V8：业务答复口径落实（2026-10-19 回执）。
+
+四件事，全部源于《待澄清问题清单》2026-10-19 答复：
+
+1. 审批开关默认值翻转（#5/#7 答复「默认开启」）：param_definitions 的
+   default_value 更新为 '1'；param_values **插入生效日 2026-10-19 的新行**
+   而非改历史行——参数体系时点化（按业务日期回溯），直接改种子行会篡改
+   10-19 之前的口径历史。
+2. 撤销试用期统一工资参数（#16 答复「按人员档案逐人维护」）：删除
+   probation.salary.basic 的定义与版本行；月结基本工资已直接读
+   personnel.salary_standard（该参数自 M3 ④ 实现起即无业务消费点）。
+3. 新增经理个人户聚合基数开关（#12 答复「作为参数配置，手动调整是否
+   纳入」）：manager.personal.included，默认 0=不计入（维持暂口径）。
+4. 绩效台账唯一键加 personnel_id（二次分配分摊铺路，澄清 #1 答复
+   「分配绩效」）：分摊后同一回款同版本按人各落一行（负责人余额行 +
+   参与人比例行），uk(receipt_id, calc_version) 会撞；扩为三列后聚合行
+   （receipt_id NULL）依旧不受 MySQL 唯一索引约束。
+
+迁移 downgrade 只保留 drop_table/行级种子反向 DELETE（V6 教训：逐个
+drop_index 会撞外键支撑索引 errno 1553）。
+"""
+
+from datetime import date
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "c7d2e5a81f30"
+down_revision: str | None = "3bca400421c6"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """种子行级变更 + 台账唯一键扩展（无表结构新增/删除）。"""
+    # 1. 审批开关默认值翻转（#5/#7：默认开启，业务可关闭）
+    op.execute(
+        "UPDATE param_definitions SET default_value = '1' "
+        "WHERE id IN (17, 18)"
+    )
+    # 时点化生效行：插新行不改历史（10-19 前仍按 0 解析）
+    op.bulk_insert(
+        sa.table(
+            "param_values",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_id", sa.BigInteger),
+            sa.column("dimension_value", sa.String),
+            sa.column("effective_date", sa.Date),
+            sa.column("value_text", sa.String),
+            sa.column("batch_id", sa.BigInteger),
+        ),
+        [
+            {
+                "id": 23,
+                "param_id": 17,
+                "dimension_value": "",
+                "effective_date": date(2026, 10, 19),
+                "value_text": "1",
+                "batch_id": 1,
+            },
+            {
+                "id": 24,
+                "param_id": 18,
+                "dimension_value": "",
+                "effective_date": date(2026, 10, 19),
+                "value_text": "1",
+                "batch_id": 1,
+            },
+        ],
+    )
+
+    # 2. 撤销试用期统一工资参数（#16：按人员档案 personnel.salary_standard 逐人维护）
+    op.execute("DELETE FROM param_values WHERE id = 19")
+    op.execute("DELETE FROM param_definitions WHERE id = 16")
+
+    # 3. 经理个人户聚合基数开关（#12：参数化，默认不计入）
+    op.bulk_insert(
+        sa.table(
+            "param_definitions",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_code", sa.String),
+            sa.column("param_name", sa.String),
+            sa.column("param_group", sa.String),
+            sa.column("value_type", sa.String),
+            sa.column("unit", sa.String),
+            sa.column("dimension_type", sa.String),
+            sa.column("options_text", sa.String),
+            sa.column("default_value", sa.String),
+            sa.column("value_min", sa.String),
+            sa.column("value_max", sa.String),
+            sa.column("description", sa.String),
+            sa.column("sort_order", sa.Integer),
+            sa.column("status", sa.Integer),
+        ),
+        [
+            {
+                "id": 20,
+                "param_code": "manager.personal.included",
+                "param_name": "经理个人户计入聚合基数",
+                "param_group": "经理分成",
+                "value_type": "BOOL",
+                "unit": None,
+                "dimension_type": "NONE",
+                "options_text": None,
+                "default_value": "0",
+                "value_min": None,
+                "value_max": None,
+                "description": (
+                    "经理 12.5%+5% 聚合时是否计入经理本人名下经理个人户业绩（澄清 #12 "
+                    "业务答复 2026-10-19：作为参数配置、手动调整是否纳入）："
+                    "0=不计入（默认，暂口径） 1=计入"
+                ),
+                "sort_order": 20,
+                "status": 1,
+            }
+        ],
+    )
+    op.bulk_insert(
+        sa.table(
+            "param_values",
+            sa.column("id", sa.BigInteger),
+            sa.column("param_id", sa.BigInteger),
+            sa.column("dimension_value", sa.String),
+            sa.column("effective_date", sa.Date),
+            sa.column("value_text", sa.String),
+            sa.column("batch_id", sa.BigInteger),
+        ),
+        [
+            {
+                "id": 25,
+                "param_id": 20,
+                "dimension_value": "",
+                "effective_date": date(2026, 1, 1),
+                "value_text": "0",
+                "batch_id": 1,
+            }
+        ],
+    )
+
+    # 4. 台账唯一键扩为三列（分摊拆行：同回款同版本按人一行）
+    # 顺序要紧：旧 uk 是 fk_performance_ledgers_receipt_id 的唯一支撑索引，
+    # 先删会撞 errno 1553（外键无支撑索引）；先建新键（receipt_id 仍居最左）
+    # 再做替换，两键短暂并存无冲突。
+    op.create_unique_constraint(
+        "uk_performance_ledgers_receipt_id_calc_version_personnel",
+        "performance_ledgers",
+        ["receipt_id", "calc_version", "personnel_id"],
+    )
+    op.drop_constraint(
+        "uk_performance_ledgers_receipt_id_calc_version",
+        "performance_ledgers",
+        type_="unique",
+    )
+
+
+def downgrade() -> None:
+    """反向：唯一键复原 + 种子行级回退（顺序与 upgrade 相反）。
+
+    试用期参数（definitions 16 / values 19）的原始种子在 V3，按 V6 downgrade
+    的行级反向惯例显式重插，保证可重放。
+    """
+    # 与 upgrade 同因的顺序：先建回旧键再删新键（旧键支撑 receipts 外键）
+    op.create_unique_constraint(
+        "uk_performance_ledgers_receipt_id_calc_version",
+        "performance_ledgers",
+        ["receipt_id", "calc_version"],
+    )
+    op.drop_constraint(
+        "uk_performance_ledgers_receipt_id_calc_version_personnel",
+        "performance_ledgers",
+        type_="unique",
+    )
+
+    op.execute("DELETE FROM param_values WHERE id = 25")
+    op.execute("DELETE FROM param_definitions WHERE id = 20")
+
+    op.execute(
+        "INSERT INTO param_definitions (id, param_code, param_name, param_group, value_type, "
+        "unit, dimension_type, options_text, default_value, value_min, value_max, "
+        "description, sort_order, status) VALUES "
+        "(16, 'probation.salary.basic', '试用期基本工资标准', '月工资口径', 'DECIMAL', "
+        "'元', 'NONE', NULL, '3000', '0', NULL, "
+        "'试用期仅发基本工资、不发放绩效（归属待 M2 复核）', 16, 1)"
+    )
+    op.execute(
+        "INSERT INTO param_values (id, param_id, dimension_value, effective_date, "
+        "value_text, batch_id) VALUES (19, 16, '', '2026-01-01', '3000', 1)"
+    )
+
+    op.execute("DELETE FROM param_values WHERE id IN (23, 24)")
+    op.execute(
+        "UPDATE param_definitions SET default_value = '0' WHERE id IN (17, 18)"
+    )

backend/alembic/versions/f3a8c2d61b47_v11_审批快照与方案版本化.py

@@ -0,0 +1,95 @@
+"""v11 审批快照与方案版本化
+
+Revision ID: f3a8c2d61b47
+Revises: 90653814a421
+Create Date: 2026-10-20 10:30:00.000000
+
+补齐 code-review 遗留 2 项：
+
+- 审批单加 ``version_no`` 与 ``snapshot_json``：重提产生新版本，送审内容
+  在提交时固化，审批期间业务再改不影响复核依据；
+- 二次分配方案行改 append-only 版本化：加 ``version_no`` / ``is_active``，
+  唯一键由 (business_id, personnel_id) 扩为
+  (business_id, version_no, personnel_id)，编辑替换与驳回清空只置历史、
+  不再物理删除。
+
+存量数据均落 ``version_no=1`` / ``is_active=1``：升级前的行就是当前生效
+版本，语义不变。审批单存量快照为空，详情接口按「当前内容回退 + 显式
+标注」处理，不做历史回填（回填会伪造提交时内容）。
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "f3a8c2d61b47"
+down_revision: str | Sequence[str] | None = "90653814a421"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """加审批快照列/索引与方案版本列，替换唯一键。"""
+    op.execute(
+        "ALTER TABLE approval_orders "
+        "ADD COLUMN version_no INT NOT NULL DEFAULT 1 "
+        "COMMENT '提交版本号（同一对象类型+引用对象从1递增；重提产生新版本，旧单快照不覆盖）' "
+        "AFTER refer_no"
+    )
+    op.execute(
+        "ALTER TABLE approval_orders "
+        "ADD COLUMN snapshot_json JSON NULL "
+        "COMMENT '提交时内容快照（信封：schema_version/order_type/captured_at/data；历史单可空）' "
+        "AFTER version_no"
+    )
+    op.execute(
+        "CREATE INDEX idx_approval_orders_type_ref ON approval_orders (order_type, ref_id)"
+    )
+
+    op.execute(
+        "ALTER TABLE business_secondary_allocations "
+        "ADD COLUMN version_no INT NOT NULL DEFAULT 1 "
+        "COMMENT '方案版本号（同一业务从1递增；编辑/重提产生新版本，旧版本仅置历史）' "
+        "AFTER business_id"
+    )
+    op.execute(
+        "ALTER TABLE business_secondary_allocations "
+        "ADD COLUMN is_active TINYINT NOT NULL DEFAULT 1 "
+        "COMMENT '是否当前生效版本：1生效 0历史（编辑替换/驳回清空后置0，行不删除）' "
+        "AFTER ratio"
+    )
+    op.execute(
+        "ALTER TABLE business_secondary_allocations "
+        "DROP INDEX uk_business_secondary_allocations_business_personnel, "
+        "ADD CONSTRAINT uk_business_secondary_allocations_business_version_personnel "
+        "UNIQUE (business_id, version_no, personnel_id)"
+    )
+    op.execute(
+        "CREATE INDEX idx_business_secondary_allocations_business_active "
+        "ON business_secondary_allocations (business_id, is_active)"
+    )
+    op.execute(
+        "ALTER TABLE business_secondary_allocations COMMENT = "
+        "'业务二次分配方案版本表（append-only；比例不要求合计满额，余额归属待澄清）'"
+    )
+
+
+def downgrade() -> None:
+    """回退结构（降级前须确认同业务同一参与人只存在于一个版本）。"""
+    op.execute(
+        "DROP INDEX idx_business_secondary_allocations_business_active "
+        "ON business_secondary_allocations"
+    )
+    op.execute(
+        "ALTER TABLE business_secondary_allocations "
+        "DROP INDEX uk_business_secondary_allocations_business_version_personnel, "
+        "ADD CONSTRAINT uk_business_secondary_allocations_business_personnel "
+        "UNIQUE (business_id, personnel_id)"
+    )
+    op.execute("ALTER TABLE business_secondary_allocations DROP COLUMN is_active")
+    op.execute("ALTER TABLE business_secondary_allocations DROP COLUMN version_no")
+
+    op.execute("DROP INDEX idx_approval_orders_type_ref ON approval_orders")
+    op.execute("ALTER TABLE approval_orders DROP COLUMN snapshot_json")
+    op.execute("ALTER TABLE approval_orders DROP COLUMN version_no")

backend/app/api/deps.py

@@ -113,3 +113,29 @@ def require_admin(current_user: Annotated[User, Depends(get_current_user)]) -> U
 
 
 AdminUser = Annotated[User, Depends(require_admin)]
+
+# 仅要求登录态、不限角色（#17 答复 2026-10-19：薪酬敏感配置「查看可、修改仅
+# 管理员」——参数目录/历史/预览等只读端点用此依赖）
+LoginUser = Annotated[User, Depends(get_current_user)]
+
+
+def require_roles(*role_codes: str, message: str = "无权访问审批管理"):
+    """要求当前用户具备任一指定角色（依赖工厂）。
+
+    与 require_admin 的差别：admin 不是天然放行——传入集合里显式含
+    ROLE_ADMIN 才可见。用于审批等模块的粗粒度准入；节点级准入仍由
+    service 按单据状态二次校验（双层：模块可见 ≠ 可操作）。
+
+    ``message`` 允许各模块替换 403 文案（默认值保持审批模块原文案，
+    避免既有调用与测试变动）。
+
+    :raises ForbiddenError: 已登录但不具备任一指定角色（403）
+    """
+
+    def _checker(current_user: Annotated[User, Depends(get_current_user)]) -> User:
+        codes = set(user_repository.get_role_codes(current_user))
+        if not codes & set(role_codes):
+            raise ForbiddenError(message)
+        return current_user
+
+    return _checker

backend/app/api/router.py

@@ -8,6 +8,7 @@ from fastapi import APIRouter
 
 from app.api import health
 from app.api.v1 import auth
+from app.api.v1.base import business_roles as base_business_roles
 from app.api.v1.base import customers as base_customers
 from app.api.v1.base import personnel as base_personnel
 from app.api.v1.base import products as base_products
@@ -15,10 +16,16 @@ from app.api.v1.business import businesses as business_businesses
 from app.api.v1.business import ratings as business_ratings
 from app.api.v1.business import receipts as business_receipts
 from app.api.v1.business import shipments as business_shipments
+from app.api.v1.calc import router as calc_router
+from app.api.v1.dashboard import router as dashboard_router
+from app.api.v1.reports import router as reports_router
+from app.api.v1.settlements import router as settlements_router
+from app.api.v1.system import approvals as system_approvals
 from app.api.v1.system import business_roles as system_business_roles
 from app.api.v1.system import logs as system_logs
 from app.api.v1.system import params as system_params
 from app.api.v1.system import roles as system_roles
+from app.api.v1.system import settings as system_settings
 from app.api.v1.system import users as system_users
 
 api_router = APIRouter()
@@ -36,6 +43,8 @@ system_router.include_router(system_users.router)
 system_router.include_router(system_roles.router)
 system_router.include_router(system_business_roles.router)
 system_router.include_router(system_params.router)
+system_router.include_router(system_settings.router)
+system_router.include_router(system_approvals.router)
 system_router.include_router(system_logs.operation_router)
 system_router.include_router(system_logs.login_router)
 v1_router.include_router(system_router)
@@ -45,6 +54,7 @@ base_router = APIRouter(prefix="/base")
 base_router.include_router(base_personnel.router)
 base_router.include_router(base_products.router)
 base_router.include_router(base_customers.router)
+base_router.include_router(base_business_roles.router)
 v1_router.include_router(base_router)
 
 # 业务数据（需求 2.2）：/api/v1/business/*，业务操作登录即可访问
@@ -55,4 +65,13 @@ business_router.include_router(business_receipts.router)
 business_router.include_router(business_ratings.router)
 v1_router.include_router(business_router)
 
+# 绩效核算（M3 ④）：/api/v1/calc/*，读登录即可、写限管理员与营销后勤
+v1_router.include_router(calc_router)
+# 月度结算（M3 ④）：/api/v1/settlements/*，读登录即可、写限管理员与营销后勤
+v1_router.include_router(settlements_router)
+# 报表统计（M4 ⑤）：/api/v1/reports/*，只读，限管理员/财务/领导
+v1_router.include_router(reports_router)
+# 工作台（M4 ⑧）：/api/v1/dashboard，四区块只读聚合，限管理员/财务/领导
+v1_router.include_router(dashboard_router)
+
 api_router.include_router(v1_router)

backend/app/api/v1/base/business_roles.py

@@ -0,0 +1,40 @@
+"""岗位下拉选项（基础数据与报表筛选共用）。
+
+岗位管理本身仅管理员可用（FR-006），但报表的「岗位」筛选对财务/领导
+开放（FR-029）。为避免把管理接口整体放开，这里提供只读、登录即可的
+启用岗位选项；写操作仍走 `/system/business-roles` 的管理员端点。
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+
+from app.api.deps import DbSession, get_current_user
+from app.core.response import ApiResponse, ok
+from app.models import User
+from app.repositories import business_role_repository
+
+router = APIRouter(prefix="/business-roles", tags=["人员管理"])
+
+# 基础数据是业务操作：登录即可，不要求管理员
+CurrentUser = Annotated[User, Depends(get_current_user)]
+
+
+@router.get("/options", response_model=ApiResponse[list[dict]], summary="岗位下拉选项")
+def list_options(session: DbSession, _: CurrentUser) -> ApiResponse[list[dict]]:
+    """岗位选项（登录即可；含停用——人员档案可能仍引用停用岗位）。
+
+    岗位规模有限（内置 + 自定义），一次取足够上限，不做分页。
+    """
+    roles = business_role_repository.list_roles(session, offset=0, limit=1000)
+    return ok(
+        [
+            {
+                "id": role.id,
+                "role_code": role.role_code,
+                "role_name": role.role_name,
+                "status": role.status,
+            }
+            for role in roles
+        ]
+    )

backend/app/api/v1/base/customers.py

@@ -96,7 +96,7 @@ def delete_customer(
 ) -> ApiResponse[None]:
     """删除客户（物理删除）。
 
-    被业务数据引用的保护检查待业务数据表（V5）就位后补充。
+    已存在关联业务时返回 400（先处理相关业务单据）。
     """
     customer_service.delete_customer(session, customer_id, operator=current_user, meta=meta)
     return ok(message="客户已删除")

backend/app/api/v1/base/products.py

@@ -91,7 +91,7 @@ def delete_product(
 ) -> ApiResponse[None]:
     """物理删除产品（仅限误录数据，常规下架用停用）。
 
-    被业务明细引用的保护检查待业务数据表（V5）就位后补充。
+    被业务明细/发货明细引用时返回 400（引导改走停用）。
     """
     product_service.delete_product(session, product_id, operator=current_user, meta=meta)
     return ok(message="产品已删除")

backend/app/api/v1/business/shipments.py

@@ -50,9 +50,7 @@ def create_shipment(
     )
 
 
-@router.get(
+@router.get("/{shipment_id}", response_model=ApiResponse[ShipmentDetailOut], summary="发货单详情")
-    "/{shipment_id}", response_model=ApiResponse[ShipmentDetailOut], summary="发货单详情"
-)
 def get_shipment(
     session: DbSession,
     _: CurrentUser,

backend/app/api/v1/calc.py

@@ -0,0 +1,107 @@
+"""绩效核算接口（M3 ④）：台账查询与单笔核算触发。
+
+核算动作 = 把回款固化为台账行（每笔回款仅一次；重算走独立入口并授权）。
+准入：读=登录即可；写（核算/重算/批量）=管理员与营销后勤
+（权限清单待澄清 #6，答复后细化）。
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Path, Query
+from pydantic import BaseModel, Field
+
+from app.api.deps import DbSession, RequestMetaDep, require_roles
+from app.core.constants import ROLE_ADMIN, ROLE_FINANCE, ROLE_MARKETING_OPS
+from app.core.response import ApiResponse, PageResult, ok
+from app.models import User
+from app.schemas.calc import CalcReceiptOut, LedgerOut, LedgerQuery
+from app.services import calc_service
+
+router = APIRouter(prefix="/calc", tags=["绩效工资 · 绩效核算"])
+
+_CalcWriter = Annotated[User, Depends(require_roles(ROLE_ADMIN, ROLE_MARKETING_OPS))]
+# 重算是授权动作：管理员/财务（营销后勤不可重算）
+_RecalcUser = Annotated[User, Depends(require_roles(ROLE_ADMIN, ROLE_FINANCE))]
+
+
+@router.get("/ledger", response_model=ApiResponse[PageResult[LedgerOut]], summary="绩效台账")
+def list_ledger(
+    session: DbSession,
+    query: Annotated[LedgerQuery, Query()],
+) -> ApiResponse[PageResult[LedgerOut]]:
+    """分页查询绩效核算台账（默认仅生效行，可筛选历史版本）。"""
+    return ok(calc_service.list_ledger_page(session, query))
+
+
+@router.get("/ledger/{ledger_id}", response_model=ApiResponse[LedgerOut], summary="台账详情")
+def get_ledger(
+    session: DbSession,
+    ledger_id: Annotated[int, Path(ge=1)],
+) -> ApiResponse[LedgerOut]:
+    """台账行详情（含计算快照）。"""
+    return ok(calc_service.get_ledger(session, ledger_id))
+
+
+@router.post(
+    "/receipts/{receipt_id}/calc",
+    response_model=ApiResponse[CalcReceiptOut],
+    summary="核算回款",
+)
+def calc_receipt(
+    receipt_id: Annotated[int, Path(ge=1)],
+    session: DbSession,
+    current_user: _CalcWriter,
+    meta: RequestMetaDep,
+) -> ApiResponse[CalcReceiptOut]:
+    """把回款固化为台账行（每笔回款仅一次；业务级一次性计提，重复回款仅登记进度）。"""
+    return ok(
+        calc_service.calc_receipt(session, receipt_id, operator=current_user, meta=meta),
+        message="核算完成",
+    )
+
+
+class RecalcIn(BaseModel):
+    """重算入参：原因必填（重算授权留痕）。"""
+
+    reason: str = Field(min_length=1, max_length=255, description="重算原因")
+
+
+class BatchIn(BaseModel):
+    """批量核算入参。"""
+
+    receipt_ids: list[int] = Field(min_length=1, description="回款 ID 列表")
+
+
+@router.post(
+    "/receipts/{receipt_id}/recalc",
+    response_model=ApiResponse[CalcReceiptOut],
+    summary="重算回款",
+)
+def recalc_receipt(
+    receipt_id: Annotated[int, Path(ge=1)],
+    payload: RecalcIn,
+    session: DbSession,
+    current_user: _RecalcUser,
+    meta: RequestMetaDep,
+) -> ApiResponse[CalcReceiptOut]:
+    """重算（管理员/财务）：作废旧版本、按当前参数落新版本并留痕。"""
+    return ok(
+        calc_service.recalc_receipt(
+            session, receipt_id, payload.reason, operator=current_user, meta=meta
+        ),
+        message="重算完成",
+    )
+
+
+@router.post("/batch", response_model=ApiResponse[list[dict]], summary="批量核算")
+def batch_calc(
+    payload: BatchIn,
+    session: DbSession,
+    current_user: _CalcWriter,
+    meta: RequestMetaDep,
+) -> ApiResponse[list[dict]]:
+    """批量核算：逐笔独立事务，返回逐笔成败清单（失败不中断其它笔）。"""
+    return ok(
+        calc_service.batch_calc(session, payload.receipt_ids, operator=current_user, meta=meta),
+        message="批量核算完成",
+    )

backend/app/api/v1/dashboard.py

@@ -0,0 +1,44 @@
+"""工作台接口（M4 ⑧）：四区块一次性聚合。
+
+准入：管理员/财务/领导（与报表、审批接口一致；FR-033/036 的「全部用户」
+待业务权限清单 #6 答复后再放宽）。只读接口，不写操作日志。
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+
+from app.api.deps import DbSession, require_roles
+from app.core.constants import ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER
+from app.core.response import ApiResponse, ok
+from app.models import User
+from app.schemas.dashboard import DashboardOut
+from app.services import dashboard_service
+
+router = APIRouter(prefix="/dashboard", tags=["工作台"])
+
+_DashboardUser = Annotated[
+    User,
+    Depends(
+        require_roles(
+            ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER, message="无权访问工作台"
+        )
+    ),
+]
+
+
+@router.get("", response_model=ApiResponse[DashboardOut], summary="工作台四区块")
+def get_dashboard(
+    session: DbSession,
+    current_user: _DashboardUser,
+    month: Annotated[
+        str | None, Query(max_length=7, description="统计月份 YYYY-MM，默认当月")
+    ] = None,
+) -> ApiResponse[DashboardOut]:
+    """一次返回经营总览/待办/风险预警/最近动态（待办与预警实时派生）。
+
+    待办按当前用户角色只返回其可操作节点（admin 可查看全部在途单）。
+    """
+    return ok(
+        dashboard_service.get_dashboard(session, month, current_user=current_user)
+    )

backend/app/api/v1/reports.py

@@ -0,0 +1,191 @@
+"""报表统计接口（M4 ⑤）：四张报表只读查询 + Excel 导出。
+
+准入：管理员/财务/领导（FR-030/031 明确；FR-029 的营销后勤「授权范围内」
+待权限清单 #6，暂不开放）。前后端双层：前端 allowedRoles 控菜单，本层
+require_roles 兜底。
+
+导出返回文件流（非统一信封），沿用参数导出先例：服务端文件名为 ASCII
+（HTTP 头按 latin-1 编码，中文名会 UnicodeEncodeError），中文名由前端
+``link.download`` 指定。
+"""
+
+from datetime import date
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, Depends, Path, Query
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, ValidationError
+
+from app.api.deps import DbSession, RequestMetaDep, require_roles
+from app.core.constants import ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER
+from app.core.exceptions import BadRequestError
+from app.core.response import ApiResponse, ok
+from app.models import User
+from app.schemas.report import (
+    BusinessStatsQuery,
+    BusinessStatsRow,
+    DepartmentSummaryOut,
+    DepartmentSummaryQuery,
+    PaymentDetailQuery,
+    PaymentDetailRow,
+    PaymentStatsOut,
+    PaymentStatsQuery,
+    PersonalDetailQuery,
+    PersonalDetailRow,
+    ReportPage,
+)
+from app.services import report_service
+
+router = APIRouter(prefix="/reports", tags=["绩效工资 · 报表统计"])
+
+_ReportViewer = Annotated[
+    User,
+    Depends(require_roles(ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER, message="无权访问报表统计")),
+]
+
+
+@router.get(
+    "/personal-detail",
+    response_model=ApiResponse[ReportPage[PersonalDetailRow]],
+    summary="个人绩效工资明细表",
+)
+def personal_detail(
+    session: DbSession,
+    _: _ReportViewer,
+    query: Annotated[PersonalDetailQuery, Query()],
+) -> ApiResponse[ReportPage[PersonalDetailRow]]:
+    """按人员/月份/客户类型/产品类别/岗位查明细（口径与台账一致）。"""
+    return ok(report_service.list_personal_detail(session, query))
+
+
+@router.get(
+    "/department-summary",
+    response_model=ApiResponse[DepartmentSummaryOut],
+    summary="部门绩效工资汇总表",
+)
+def department_summary(
+    session: DbSession,
+    _: _ReportViewer,
+    query: Annotated[DepartmentSummaryQuery, Query()],
+) -> ApiResponse[DepartmentSummaryOut]:
+    """按经理团队/月份汇总（团队基数与月结聚合行同源）。"""
+    return ok(report_service.department_summary(session, query))
+
+
+@router.get(
+    "/business-stats",
+    response_model=ApiResponse[ReportPage[BusinessStatsRow]],
+    summary="业务统计表",
+)
+def business_stats(
+    session: DbSession,
+    _: _ReportViewer,
+    query: Annotated[BusinessStatsQuery, Query()],
+) -> ApiResponse[ReportPage[BusinessStatsRow]]:
+    """按业务查询发货、回款、绩效（回款/绩效为业务累计值）。"""
+    return ok(report_service.business_stats(session, query))
+
+
+@router.get(
+    "/payment-stats",
+    response_model=ApiResponse[PaymentStatsOut],
+    summary="回款情况统计表",
+)
+def payment_stats(
+    session: DbSession,
+    _: _ReportViewer,
+    query: Annotated[PaymentStatsQuery, Query()],
+) -> ApiResponse[PaymentStatsOut]:
+    """按回款天数区间/客户类型/产品类别统计（空桶恒在且为 0）。"""
+    return ok(report_service.payment_stats(session, query))
+
+
+@router.get(
+    "/payment-detail",
+    response_model=ApiResponse[ReportPage[PaymentDetailRow]],
+    summary="回款区间下钻",
+)
+def payment_detail(
+    session: DbSession,
+    _: _ReportViewer,
+    query: Annotated[PaymentDetailQuery, Query()],
+) -> ApiResponse[ReportPage[PaymentDetailRow]]:
+    """区间桶下钻到单笔台账行（含回款金额与批次号）。"""
+    return ok(report_service.payment_detail(session, query))
+
+
+@router.get(
+    "/payment-day-buckets", response_model=ApiResponse[list[dict]], summary="回款天数区间档位"
+)
+def payment_day_buckets(_: _ReportViewer) -> ApiResponse[list[dict]]:
+    """区间档位元数据（前端渲染下拉/表头，禁止前端硬编码档位）。"""
+    return ok(report_service.get_payment_day_buckets())
+
+
+class ExportQuery(BaseModel):
+    """导出通用筛选参数（按报表编码取用相关字段，未用字段忽略）。"""
+
+    settlement_month: str | None = None
+    personnel_id: int | None = None
+    customer_type: str | None = None
+    product_category: str | None = None
+    role_code: str | None = None
+    manager_id: int | None = None
+    keyword: str | None = None
+    customer_id: int | None = None
+    owner_personnel_id: int | None = None
+    status: int | None = None
+    date_from: date | None = None
+    date_to: date | None = None
+
+
+@router.get("/{code}/export", summary="导出报表 Excel")
+def export_report(
+    code: Annotated[
+        Literal["personal-detail", "department-summary", "business-stats", "payment-stats"],
+        Path(description="报表编码"),
+    ],
+    session: DbSession,
+    current_user: _ReportViewer,
+    meta: RequestMetaDep,
+    query: Annotated[ExportQuery, Query()],
+) -> StreamingResponse:
+    """导出 xlsx（含公司页眉/财务复核栏/领导签字栏），行为入操作日志。"""
+    content, filename = report_service.export_report(
+        session,
+        code,
+        _build_export_query(code, query),
+        operator=current_user,
+        meta=meta,
+    )
+    return StreamingResponse(
+        iter([content]),
+        media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        headers={
+            "Content-Disposition": (f'attachment; filename="{filename}_{date.today():%Y%m%d}.xlsx"')
+        },
+    )
+
+
+def _build_export_query(code: str, query: ExportQuery):
+    """导出参数 → 各报表自己的查询模型（department-summary 月份必填由模型校验）。
+
+    手工构造模型抛出的是 `pydantic.ValidationError`，不是 FastAPI 的
+    `RequestValidationError`——不在这里转换就会落到全局 500。导出参数
+    非法与查询接口一样应当是 400。
+    """
+    data = query.model_dump()
+    model = {
+        "personal-detail": PersonalDetailQuery,
+        "department-summary": DepartmentSummaryQuery,
+        "business-stats": BusinessStatsQuery,
+        "payment-stats": PaymentStatsQuery,
+    }[code]
+    try:
+        return model(**data)
+    except ValidationError as exc:
+        first = exc.errors()[0]
+        location = ".".join(str(part) for part in first.get("loc", ()))
+        message = first.get("msg", "参数错误")
+        detail = f"{location} {message}" if location else message
+        raise BadRequestError(f"参数错误：{detail}") from exc

backend/app/api/v1/settlements.py

@@ -0,0 +1,99 @@
+"""月度结算接口（M3 ④）：生成/提交审批/锁定与调整单。
+
+准入：读=登录即可；写（生成/提交/调整单）=管理员与营销后勤
+（权限清单待澄清 #6，答复后细化）。
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Path, Query
+
+from app.api.deps import DbSession, RequestMetaDep, require_roles
+from app.core.constants import ROLE_ADMIN, ROLE_MARKETING_OPS
+from app.core.response import ApiResponse, PageResult, ok
+from app.models import User
+from app.schemas.settlement import (
+    AdjustmentCreateIn,
+    SettlementDetailOut,
+    SettlementGenerateIn,
+    SettlementOut,
+    SettlementQuery,
+)
+from app.services import settlement_service
+
+router = APIRouter(prefix="/settlements", tags=["绩效工资 · 月度结算"])
+
+_SettlementWriter = Annotated[User, Depends(require_roles(ROLE_ADMIN, ROLE_MARKETING_OPS))]
+
+
+@router.post("/generate", response_model=ApiResponse[SettlementDetailOut], summary="生成月结快照")
+def generate(
+    payload: SettlementGenerateIn,
+    session: DbSession,
+    current_user: _SettlementWriter,
+    meta: RequestMetaDep,
+) -> ApiResponse[SettlementDetailOut]:
+    """按确认回款口径生成指定月份的结算快照（草稿）。"""
+    return ok(
+        settlement_service.generate(session, payload.month, operator=current_user, meta=meta),
+        message="月结已生成",
+    )
+
+
+@router.get("", response_model=ApiResponse[PageResult[SettlementOut]], summary="月结列表")
+def list_settlements(
+    session: DbSession,
+    query: Annotated[SettlementQuery, Query()],
+) -> ApiResponse[PageResult[SettlementOut]]:
+    """分页查询月结（按月份倒序）。"""
+    return ok(settlement_service.list_page(session, query))
+
+
+@router.get("/{settlement_id}", response_model=ApiResponse[SettlementDetailOut], summary="月结详情")
+def get_settlement(
+    session: DbSession,
+    settlement_id: Annotated[int, Path(ge=1)],
+) -> ApiResponse[SettlementDetailOut]:
+    """月结详情（含按人明细）。"""
+    return ok(settlement_service.get_detail(session, settlement_id))
+
+
+@router.post(
+    "/{settlement_id}/submit",
+    response_model=ApiResponse[SettlementDetailOut],
+    summary="提交审批",
+)
+def submit(
+    settlement_id: Annotated[int, Path(ge=1)],
+    session: DbSession,
+    current_user: _SettlementWriter,
+    meta: RequestMetaDep,
+) -> ApiResponse[SettlementDetailOut]:
+    """提交审批：开关关闭=自动通过并锁定；开启=待财务复核。"""
+    return ok(
+        settlement_service.submit(session, settlement_id, operator=current_user, meta=meta),
+        message="已提交",
+    )
+
+
+# ==================== 调整单（已锁定月份的补发/扣减） ====================
+
+
+@router.post("/adjustments", response_model=ApiResponse[dict], summary="新建调整单")
+def create_adjustment(
+    payload: AdjustmentCreateIn,
+    session: DbSession,
+    current_user: _SettlementWriter,
+    meta: RequestMetaDep,
+) -> ApiResponse[dict]:
+    """新建调整单：开关关闭=提交即生效（自动通过留痕）；开启=走审批。"""
+    return ok(
+        settlement_service.create_adjustment(session, payload, operator=current_user, meta=meta),
+        message="调整单已创建",
+    )
+
+
+@router.get("/adjustments", response_model=ApiResponse[list[dict]], summary="调整单列表")
+def list_adjustments(session: DbSession) -> ApiResponse[list[dict]]:
+    """调整单列表（一期不分页，内部系统量级有限）。"""
+    return ok(settlement_service.list_adjustments(session))

backend/app/api/v1/system/approvals.py

@@ -0,0 +1,67 @@
+"""审批管理接口（2026-10-15 复核审批补充需求）。
+
+准入：admin/财务/领导可见（营销后勤暂不可见——权限清单待澄清 #6，
+答复后放开为「提交人可见本人单据」）。节点级准入由 service 按单据
+状态二次校验（status=1 仅财务、status=2 仅领导，admin 不代办）。
+提单不经本模块：由业务写路径（创建/编辑带二次分配方案）自动触发。
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Path, Query
+
+from app.api.deps import DbSession, RequestMetaDep, require_roles
+from app.core.constants import ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER
+from app.core.response import ApiResponse, PageResult, ok
+from app.models import User
+from app.schemas.approval import (
+    ApprovalActionIn,
+    ApprovalOrderDetailOut,
+    ApprovalOrderOut,
+    ApprovalQuery,
+)
+from app.services import approval_service
+
+router = APIRouter(prefix="/approvals", tags=["系统管理 · 审批管理"])
+
+# 模块准入：可见集合（节点准入在 service 层按状态二次判定）
+_ApprovalUser = Annotated[User, Depends(require_roles(ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER))]
+
+
+@router.get("", response_model=ApiResponse[PageResult[ApprovalOrderOut]], summary="审批单列表")
+def list_orders(
+    session: DbSession,
+    _: _ApprovalUser,
+    query: Annotated[ApprovalQuery, Query()],
+) -> ApiResponse[PageResult[ApprovalOrderOut]]:
+    """分页查询审批单。"""
+    return ok(approval_service.list_orders(session, query))
+
+
+@router.get("/{order_id}", response_model=ApiResponse[ApprovalOrderDetailOut], summary="审批详情")
+def get_order(
+    session: DbSession,
+    _: _ApprovalUser,
+    order_id: Annotated[int, Path(ge=1)],
+) -> ApiResponse[ApprovalOrderDetailOut]:
+    """审批单详情（含节点时间线）。"""
+    return ok(approval_service.get_order(session, order_id))
+
+
+@router.post(
+    "/{order_id}/action",
+    response_model=ApiResponse[ApprovalOrderDetailOut],
+    summary="节点动作（通过/驳回）",
+)
+def act_on_order(
+    payload: ApprovalActionIn,
+    session: DbSession,
+    current_user: _ApprovalUser,
+    meta: RequestMetaDep,
+    order_id: Annotated[int, Path(ge=1)],
+) -> ApiResponse[ApprovalOrderDetailOut]:
+    """财务复核 / 领导审核；一驳全驳，驳回须填意见。"""
+    return ok(
+        approval_service.act(session, order_id, payload, operator=current_user, meta=meta),
+        message="已提交",
+    )

backend/app/api/v1/system/params.py

@@ -1,8 +1,9 @@
 """计提参数管理接口（需求 #28：参数配置化 + 版本管理 + 留痕）。
 
-全部要求管理员权限（开放问题 #5 的当前默认，后续可放宽只读）；
+权限分层（澄清 #17 业务答复 2026-10-19「查看可、修改仅管理员」）：只读
-写操作（提交/撤回）经 `RequestMetaDep` 带入请求元信息写入操作日志，
+端点（目录/变更记录/批次明细/对比/导出/预览/历史）要求登录即可；写操作
-变更批次本身另行留痕（变更人/时间/项/旧值/新值/生效日期）——双保险。
+（提交/撤回）仅管理员。写操作经 `RequestMetaDep` 带入请求元信息写入操作
+日志，变更批次本身另行留痕（变更人/时间/项/旧值/新值/生效日期）——双保险。
 导出为文件流（非统一信封），前端以 blob 接收。
 """
 
@@ -12,7 +13,7 @@ from typing import Annotated
 from fastapi import APIRouter, Path, Query
 from fastapi.responses import StreamingResponse
 
-from app.api.deps import AdminUser, DbSession, RequestMetaDep
+from app.api.deps import AdminUser, DbSession, LoginUser, RequestMetaDep
 from app.core.response import ApiResponse, PageResult, ok
 from app.schemas.param import (
     ParamBatchDetailOut,
@@ -37,7 +38,7 @@ router = APIRouter(prefix="/params", tags=["系统管理 · 计提参数"])
 )
 def get_catalog(
     session: DbSession,
-    _: AdminUser,
+    _: LoginUser,
     as_of: Annotated[date | None, Query(description="业务日期，默认今日")] = None,
 ) -> ApiResponse[list[ParamCatalogItemOut]]:
     """全部启用参数的定义元数据与截至 asOf 的生效值（前端按分组展示）。"""
@@ -63,7 +64,7 @@ def submit_change(
 )
 def list_changes(
     session: DbSession,
-    _: AdminUser,
+    _: LoginUser,
     query: Annotated[ParamBatchQuery, Query()],
 ) -> ApiResponse[PageResult[ParamBatchOut]]:
     """按生效日期区间分页查询变更批次（创建时间倒序）。"""
@@ -75,7 +76,7 @@ def list_changes(
 )
 def get_batch(
     session: DbSession,
-    _: AdminUser,
+    _: LoginUser,
     batch_id: Annotated[int, Path(ge=1)],
 ) -> ApiResponse[ParamBatchDetailOut]:
     """批次头 + 逐项旧值 → 新值。"""
@@ -97,7 +98,7 @@ def withdraw_batch(
 @router.get("/compare", response_model=ApiResponse[list[ParamDiffOut]], summary="两日期快照对比")
 def compare(
     session: DbSession,
-    _: AdminUser,
+    _: LoginUser,
     from_date: Annotated[date, Query(description="起始业务日期（含）")],
     to_date: Annotated[date, Query(description="截止业务日期（含）")],
 ) -> ApiResponse[list[ParamDiffOut]]:
@@ -108,7 +109,7 @@ def compare(
 @router.get("/export", summary="导出变更记录 Excel")
 def export_changes(
     session: DbSession,
-    _: AdminUser,
+    _: LoginUser,
     start_date: Annotated[date | None, Query(description="生效日期起（含）")] = None,
     end_date: Annotated[date | None, Query(description="生效日期止（含）")] = None,
 ) -> StreamingResponse:
@@ -125,7 +126,7 @@ def export_changes(
 @router.post("/preview", response_model=ApiResponse[ParamPreviewOut], summary="计算预览")
 def preview(
     session: DbSession,
-    _: AdminUser,
+    _: LoginUser,
     payload: ParamPreviewIn,
 ) -> ApiResponse[ParamPreviewOut]:
     """输入业务场景（岗位/产品/发货/回款/金额），按回款到账日取参数实时试算。"""
@@ -139,7 +140,7 @@ def preview(
 )
 def get_history(
     session: DbSession,
-    _: AdminUser,
+    _: LoginUser,
     param_code: Annotated[str, Path(max_length=64)],
     query: Annotated[ParamHistoryQuery, Query()],
 ) -> ApiResponse[PageResult[ParamHistoryOut]]:

backend/app/api/v1/system/settings.py

@@ -0,0 +1,83 @@
+"""系统设置接口（公司信息）。
+
+`GET /public` 与 `GET /logo/public` **无鉴权**：登录页渲染公司名/logo 时
+尚无令牌。响应经 `SettingPublicOut` 白名单收敛（见 schemas/setting.py），
+仅暴露两个非敏感展示字段。
+
+`/logo/public` 返回文件流而非统一信封——与参数导出同一例外口径
+（二进制响应套 JSON 信封无意义）。
+"""
+
+from fastapi import APIRouter, Response, UploadFile
+from fastapi.responses import FileResponse
+
+from app.api.deps import AdminUser, DbSession, RequestMetaDep
+from app.core.exceptions import BadRequestError
+from app.core.response import ApiResponse, ok
+from app.schemas.setting import SettingOut, SettingPublicOut, SettingUpdateIn
+from app.services import system_setting_service as service
+
+router = APIRouter(prefix="/settings", tags=["系统管理 · 公司信息"])
+
+_LOGO_MEDIA_TYPE = {"png": "image/png", "jpg": "image/jpeg"}
+
+
+@router.get("", response_model=ApiResponse[SettingOut], summary="公司信息")
+def get_settings(session: DbSession, _: AdminUser) -> ApiResponse[SettingOut]:
+    """取公司信息（管理端）。"""
+    return ok(service.to_out(service.get_setting(session)))
+
+
+@router.put("", response_model=ApiResponse[SettingOut], summary="更新公司名称")
+def update_settings(
+    payload: SettingUpdateIn,
+    session: DbSession,
+    current_user: AdminUser,
+    meta: RequestMetaDep,
+) -> ApiResponse[SettingOut]:
+    """更新公司名称（审计留痕）。"""
+    return ok(
+        service.update_company(session, payload, operator=current_user, meta=meta),
+        message="已保存",
+    )
+
+
+@router.post("/logo", response_model=ApiResponse[SettingOut], summary="上传 logo")
+def upload_logo(
+    file: UploadFile,
+    session: DbSession,
+    current_user: AdminUser,
+    meta: RequestMetaDep,
+) -> ApiResponse[SettingOut]:
+    """上传公司 logo（png/jpg ≤2MB；固定名覆盖，旧扩展名文件清理）。
+
+    同步 `def`：读文件、磁盘写与审计提交都是阻塞操作，async 路由里会让
+    它们卡死事件循环（项目红线：全栈同步路由，FastAPI 自动进线程池）。
+    大小先用 `file.size` 拦截，避免超限文件整体读进内存。
+    """
+    if file.size is not None and file.size > service.LOGO_MAX_BYTES:
+        raise BadRequestError("logo 文件不能超过 2MB")
+    content = file.file.read()
+    ext = (file.filename or "").rsplit(".", 1)[-1]
+    return ok(
+        service.save_logo(session, content, ext, operator=current_user, meta=meta),
+        message="logo 已更新",
+    )
+
+
+@router.get("/public", response_model=ApiResponse[SettingPublicOut], summary="公司信息（匿名）")
+def get_settings_public(session: DbSession, response: Response) -> ApiResponse[SettingPublicOut]:
+    """公司信息（登录页消费，无鉴权）。短缓存减轻匿名端点压力。"""
+    response.headers["Cache-Control"] = "public, max-age=300"
+    return ok(service.to_public_out(service.get_setting(session)))
+
+
+@router.get("/logo/public", summary="logo 图片（匿名）")
+def get_logo_public(session: DbSession) -> FileResponse:
+    """logo 文件流（无鉴权）。no-cache：图片替换后由版本参数破缓存兜底。"""
+    path, ext = service.read_logo(session)
+    return FileResponse(
+        path,
+        media_type=_LOGO_MEDIA_TYPE.get(ext, "application/octet-stream"),
+        headers={"Cache-Control": "no-cache"},
+    )

backend/app/core/captcha_image.py

@@ -27,11 +27,12 @@ _WIDTH, _HEIGHT = 120, 40
 _FONT_SIZE = 25
 _PADDING = 8
 
-# 与前端配色呼应：墨色字符、青灰干扰、素纸底
+# 与前端 v3 配色呼应（--ys-ink / --ys-ink-2 / --ys-ink-3 / --ys-paper）：
-_INK = (15, 54, 70)
+# 墨色字符、次级墨干扰、辅助墨噪点、纸白底
-_INTERFERENCE = (126, 156, 170)
+_INK = (28, 35, 51)  # #1c2333
-_SPECKLE = (168, 183, 192)
+_INTERFERENCE = (91, 101, 119)  # #5b6577
-_PAPER = (247, 246, 242)
+_SPECKLE = (154, 163, 178)  # #9aa3b2
+_PAPER = (255, 255, 255)  # #ffffff
 
 _SPECKLE_COUNT = 46
 _INTERFERENCE_LINES = 2

backend/app/core/config.py

@@ -92,6 +92,15 @@ class Settings(BaseSettings):
         auth = f":{self.redis_password}@" if self.redis_password else ""
         return f"redis://{auth}{self.redis_host}:{self.redis_port}/{self.redis_db}"
 
+    @property
+    def upload_dir(self) -> Path:
+        """上传文件根目录（公司 logo 等）：backend/uploads/。
+
+        不叫 static/ 是刻意的：静态目录将来可能整体交给前端构建产物，
+        运行期上传物必须与之隔离；该目录不入版本库（.gitignore）。
+        """
+        return BACKEND_DIR / "uploads"
+
 
 @lru_cache
 def get_settings() -> Settings:

backend/app/core/constants.py

@@ -25,6 +25,19 @@ TOKEN_TYPE_BEARER = "Bearer"
 # ===== 角色编码（与 db/migration 初始化数据保持一致）=====
 ROLE_ADMIN = "admin"
 ROLE_USER = "user"
+# 2026-10-15 复核审批补充需求新增职能登录角色：营销后勤（提交+录入）、
+# 财务（复核）、领导（审核）。roles 表无 is_builtin 列，内置保护用代码
+# 白名单判定（role_service 两处内置校验改查此集合）；
+# permissions/role_permissions 细粒度激活待业务权限清单（待澄清 #6）。
+ROLE_MARKETING_OPS = "marketing_ops"
+ROLE_FINANCE = "finance"
+ROLE_LEADER = "leader"
+BUILTIN_ROLE_CODES = {
+    ROLE_ADMIN,
+    ROLE_MARKETING_OPS,
+    ROLE_FINANCE,
+    ROLE_LEADER,
+}
 
 # ===== 密码策略 =====
 # bcrypt 5.0 起对超过 72 字节的密码由「静默截断」改为「抛 ValueError」，
@@ -70,12 +83,20 @@ MODULE_BUSINESS = "业务管理"
 MODULE_SHIPMENT = "发货管理"
 MODULE_RECEIPT = "回款管理"
 MODULE_RATING = "客户评级"
+MODULE_SYSTEM_SETTINGS = "系统设置"
+MODULE_APPROVAL = "审批管理"
+MODULE_CALC = "绩效核算"
+MODULE_SETTLEMENT = "月度结算"
+MODULE_REPORT = "报表统计"
 
 # ===== 单据编号前缀（{前缀}{YYYYMMDD}-{当日4位序号}，序号按自然日重置）=====
 # 一期为代码常量（业务未提出配置诉求）；如需可配置，走 M1 参数体系新增参数组
 NO_PREFIX_BUSINESS = "YW"
 NO_PREFIX_SHIPMENT = "SH"
 NO_PREFIX_RECEIPT = "HK"
+NO_PREFIX_PARAM = "P"
+NO_PREFIX_APPROVAL = "AP"
+NO_PREFIX_ADJUSTMENT = "TZ"
 
 ACTION_CREATE = "新增"
 ACTION_UPDATE = "修改"
@@ -83,3 +104,6 @@ ACTION_DELETE = "删除"
 ACTION_RESET_PASSWORD = "重置密码"
 ACTION_ENABLE = "启用"
 ACTION_DISABLE = "禁用"
+ACTION_APPROVE = "审批通过"
+ACTION_REJECT = "审批驳回"
+ACTION_EXPORT = "导出"

backend/app/core/db_errors.py

@@ -0,0 +1,18 @@
+"""数据库完整性错误的统一识别与翻译口径。
+
+判断依据：pymysql 原生异常 ``orig.args`` 首位是 MySQL 错误码 —— 只有
+1062（ER_DUP_ENTRY，唯一键冲突）是「已存在」语义，可安全转 400 业务
+提示；其余完整性错误（外键 RESTRICT、数据截断等）原样上抛，由全局
+异常处理器收敛 500（程序缺陷或数据异常，均不应伪装成用户错误）。
+"""
+
+from sqlalchemy.exc import IntegrityError
+
+# MySQL 唯一键冲突错误码（pymysql 原生异常 args 首位）
+ERR_DUP_ENTRY = 1062
+
+
+def is_duplicate_entry(exc: IntegrityError) -> bool:
+    """判断 IntegrityError 是否为 MySQL 唯一键冲突（错误码 1062）。"""
+    args = getattr(exc.orig, "args", ())
+    return bool(args) and args[0] == ERR_DUP_ENTRY

backend/app/core/exception_handlers.py

@@ -12,6 +12,7 @@ import logging
 from fastapi import FastAPI, Request
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
+from sqlalchemy.exc import IntegrityError
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from app.core.constants import CODE_BAD_REQUEST, CODE_SERVER_ERROR
@@ -60,6 +61,19 @@ async def handle_http_exception(_: Request, exc: StarletteHTTPException) -> JSON
     return _build_response(exc.status_code, message)
 
 
+async def handle_integrity_error(_: Request, exc: IntegrityError) -> JSONResponse:
+    """完整性错误全局兜底为 400。
+
+    service 层已判别的 1062/引用冲突会自行翻译为业务提示，不会走到这里；
+    本 handler 拦截的是「新增父表后某 service 漏补引用保护」一类的遗漏
+    （e2e 撞见一个补一个的模式无法保证全覆盖）：FK RESTRICT 等数据完整性
+    冲突对用户表现为「这行数据被别处引用/冲突」，转 400 比 500 更贴近事实。
+    完整异常记录日志供排查；不在此处 rollback —— 会话由请求级依赖统一关闭。
+    """
+    logger.error("数据库完整性冲突（未在 service 层翻译）", exc_info=exc)
+    return _build_response(CODE_BAD_REQUEST, "数据完整性冲突，操作被拒绝")
+
+
 async def handle_unexpected_exception(_: Request, exc: Exception) -> JSONResponse:
     """兜底处理未预期异常。
 
@@ -77,4 +91,5 @@ def register_exception_handlers(app: FastAPI) -> None:
     app.add_exception_handler(AppException, handle_app_exception)  # type: ignore[arg-type]
     app.add_exception_handler(RequestValidationError, handle_validation_error)  # type: ignore[arg-type]
     app.add_exception_handler(StarletteHTTPException, handle_http_exception)  # type: ignore[arg-type]
+    app.add_exception_handler(IntegrityError, handle_integrity_error)  # type: ignore[arg-type]
     app.add_exception_handler(Exception, handle_unexpected_exception)

backend/app/core/month.py

@@ -0,0 +1,26 @@
+"""月份参数校验（YYYY-MM）——叶子模块。
+
+报表、月结与调整单共用同一套校验：只校验长度会放过 `2026-13` 这类
+非法月份，一路传到 `calendar.monthrange` 才抛 ValueError，最终被全局
+处理器当成服务端异常（500）。月份范围必须在入口处拦住，才能返回 400。
+"""
+
+import re
+
+_MONTH_RE = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$")
+
+
+def validate_month(value: str) -> str:
+    """校验 YYYY-MM 且月份 01-12；非法抛 ValueError（Pydantic 友好）。
+
+    年份 0000 也拒绝：`date(0, ...)` 同样会抛 ValueError，且业务上不存在。
+    """
+    if not _MONTH_RE.match(value) or int(value[:4]) == 0:
+        raise ValueError("月份格式须为 YYYY-MM（01-12）")
+    return value
+
+
+def parse_month(value: str) -> tuple[int, int]:
+    """校验并返回 (year, month)，供服务层计算月末等使用。"""
+    validate_month(value)
+    return int(value[:4]), int(value[5:7])

backend/app/core/report_meta.py

@@ -0,0 +1,79 @@
+"""报表统计元数据（区间桶、中文标签、导出上限）——叶子模块。
+
+刻意不导入 app 内任何模块：report_service 与 report_export 都要消费这里的
+定义，若它反向依赖 service 层会形成循环导入；也不走参数体系——FR-031
+「区间可配置」一期以代码常量落地（参数化需注册表 + 迁移 + init-dev +
+registry 测试四处同改，业务未提诉求前不做），配置缝收在
+get_payment_day_buckets 单函数，未来在线可配时只改该函数。
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class DayBucket:
+    """回款天数区间档位：min/max 均为 None 表示「无回款天数」兜底桶。"""
+
+    code: str
+    label: str
+    min_days: int | None
+    max_days: int | None
+
+
+# 8 档区间（催办清单 R2 默认口径）。两个兜底桶必须保留：payment_days 可空
+# （回款未指定发货批次）且可为负（先款后货照实负值），缺了它们这些行会
+# 静默消失、金额对不上。
+PAYMENT_DAY_BUCKETS: tuple[DayBucket, ...] = (
+    DayBucket("le0", "≤0 天（先款后货）", None, 0),
+    DayBucket("1-30", "1-30 天", 1, 30),
+    DayBucket("31-60", "31-60 天", 31, 60),
+    DayBucket("61-90", "61-90 天", 61, 90),
+    DayBucket("91-180", "91-180 天", 91, 180),
+    DayBucket("181-360", "181-360 天", 181, 360),
+    DayBucket("361+", "361 天以上", 361, None),
+    DayBucket("none", "无回款天数", None, None),
+)
+
+CUSTOMER_TYPE_LABELS: dict[str, str] = {
+    "personal": "个人户",
+    "manager_personal": "经理个人户",
+    "enterprise": "企业户",
+}
+
+# mixed 不在 core.constants.PRODUCT_CATEGORIES（那只是可维护的档案类别），
+# 但台账行可以是 mixed（混合业务行级明细入 snapshot_json），报表必须能标它
+PRODUCT_CATEGORY_LABELS: dict[str, str] = {
+    "municipal_water": "市政水利",
+    "rail_transit": "轨道交通",
+    "mixed": "混合业务",
+}
+
+# 业务状态中文标签：导出列、筛选页眉与前端标签共用同一份映射
+BUSINESS_STATUS_LABELS: dict[int, str] = {1: "进行中", 2: "已完成", 3: "已终止"}
+
+REPORT_TEMPLATE_VERSION = "V1.2"
+# 导出超限即拒绝（需求「大数据量分批/超限提示」二选一取后者）：普通
+# Workbook 全量载入内存，2 万行约数十 MB，超过该量级必须引导按月导出
+REPORT_EXPORT_MAX_ROWS = 20000
+
+
+def get_payment_day_buckets() -> tuple[DayBucket, ...]:
+    """区间档位唯一出口：前端下拉与分桶都以本函数返回为准，禁止硬编码。
+
+    未来「区间在线可配」时改此处读参数即可，调用方与前端零改动。
+    """
+    return PAYMENT_DAY_BUCKETS
+
+
+def bucket_of(payment_days: int | None) -> DayBucket:
+    """把单笔回款天数落入对应区间桶；未匹配任何区间按「无回款天数」兜底。"""
+    if payment_days is None:
+        return next(b for b in PAYMENT_DAY_BUCKETS if b.code == "none")
+    for bucket in PAYMENT_DAY_BUCKETS:
+        if bucket.code == "none":
+            continue
+        lower_ok = bucket.min_days is None or payment_days >= bucket.min_days
+        upper_ok = bucket.max_days is None or payment_days <= bucket.max_days
+        if lower_ok and upper_ok:
+            return bucket
+    return next(b for b in PAYMENT_DAY_BUCKETS if b.code == "none")

backend/app/models/__init__.py

@@ -9,22 +9,29 @@
 `Base.metadata` 包含全部表，漏掉一张就会生成「删除该表」的迁移。
 """
 
+from app.models.approval import ApprovalOrder, ApprovalStep
 from app.models.base import Base, TimestampMixin
-from app.models.business import Business, BusinessItem, BusinessStatusLog
+from app.models.business import Business, BusinessItem, BusinessStatusLog, SecondaryAllocation
 from app.models.business_role import BusinessRole
 from app.models.customer import Customer, OwnershipChangeLog
 from app.models.login_log import LoginLog
 from app.models.operation_log import OperationLog
 from app.models.param import ParamChangeBatch, ParamDefinition, ParamValue
+from app.models.performance_ledger import PerformanceLedger
 from app.models.personnel import Personnel, PersonnelPlan, PersonnelRegion
 from app.models.product import Product
 from app.models.rating import CustomerRatingGrade
 from app.models.receipt import Receipt
 from app.models.role import Permission, Role, RolePermission
+from app.models.settlement import AdjustmentOrder, MonthlySettlement, SettlementItem
 from app.models.shipment import Shipment, ShipmentItem
+from app.models.system_setting import SystemSetting
 from app.models.user import User, UserRole
 
 __all__ = [
+    "AdjustmentOrder",
+    "ApprovalOrder",
+    "ApprovalStep",
     "Base",
     "Business",
     "BusinessItem",
@@ -33,11 +40,13 @@ __all__ = [
     "Customer",
     "CustomerRatingGrade",
     "LoginLog",
+    "MonthlySettlement",
     "OperationLog",
     "OwnershipChangeLog",
     "ParamChangeBatch",
     "ParamDefinition",
     "ParamValue",
+    "PerformanceLedger",
     "Permission",
     "Personnel",
     "PersonnelPlan",
@@ -46,8 +55,11 @@ __all__ = [
     "Receipt",
     "Role",
     "RolePermission",
+    "SecondaryAllocation",
+    "SettlementItem",
     "Shipment",
     "ShipmentItem",
+    "SystemSetting",
     "TimestampMixin",
     "User",
     "UserRole",

backend/app/models/approval.py

@@ -0,0 +1,163 @@
+"""审批模型：审批单与节点记录（2026-10-15 复核审批补充需求）。
+
+三级链路：营销后勤提交 → 财务复核 → 领导审核。行为由参数体系开关驱动
+（`approval.*.enabled` BOOL）：关闭=提交即生成「自动通过」节点留痕，
+留痕不断链（开发计划 3.2(三)）；开启=按节点人工审核，一驳全驳。
+
+依赖说明：节点准入按登录角色编码判定（ROLE_FINANCE/ROLE_LEADER），
+不动 `permissions`/`role_permissions` 闲置表 —— 细粒度权限清单待业务方
+答复（待澄清 #6）后再激活。
+
+ref_id 为**固化无外键**（同 business_status_logs 先例）：order_type=2
+（月结预留）将指向 ④ 尚未落地的表，外键无法统一指向；单据删除保护由
+服务层承担（详见 approval_service）。
+"""
+
+from datetime import datetime
+
+from sqlalchemy import (
+    JSON,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    UniqueConstraint,
+    text,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import BIGINT_UNSIGNED, TINYINT_TYPE, Base, TimestampMixin, mysql_table_args
+
+# 审批单状态（approval_orders.status；流转机见 approval_service）
+APPROVAL_STATUS_PENDING_FINANCE = 1  # 待财务复核
+APPROVAL_STATUS_PENDING_LEADER = 2  # 待领导审核
+APPROVAL_STATUS_APPROVED = 3  # 已通过（终态）
+APPROVAL_STATUS_REJECTED = 4  # 已驳回（终态）
+APPROVAL_STATUS_WITHDRAWN = 5  # 已撤回（被引用方重新提交时旧在途单注销）
+
+# 节点（approval_steps.node；0 仅用于撤回留痕）
+APPROVAL_NODE_FINANCE = 1
+APPROVAL_NODE_LEADER = 2
+APPROVAL_NODE_WITHDRAW = 0
+APPROVAL_NODES = {
+    APPROVAL_STATUS_PENDING_FINANCE: APPROVAL_NODE_FINANCE,
+    APPROVAL_STATUS_PENDING_LEADER: APPROVAL_NODE_LEADER,
+}
+
+# 动作（approval_steps.action）
+APPROVAL_ACTION_APPROVE = 1  # 人工通过
+APPROVAL_ACTION_REJECT = 2  # 人工驳回
+APPROVAL_ACTION_AUTO_APPROVE = 3  # 系统自动通过（开关关闭时逐节点留痕）
+APPROVAL_ACTION_WITHDRAW = 4  # 撤回（业务重新提交时旧在途单注销）
+
+# 审批对象类型（approval_orders.order_type）
+APPROVAL_TYPE_SECONDARY_ALLOCATION = 1
+APPROVAL_TYPE_MONTHLY_SETTLEMENT = 2
+APPROVAL_TYPE_ADJUSTMENT = 3
+
+
+class ApprovalOrder(Base, TimestampMixin):
+    """审批单：一张待审对象一条审批流（状态可流转，含 update_time）。"""
+
+    __tablename__ = "approval_orders"
+    __table_args__ = mysql_table_args(
+        "审批单表（营销后勤提交→财务复核→领导审核；开关关闭时自动通过留痕）",
+        # 同一引用对象的第 N 次送审在库里有唯一一行：并发提单算重版本号时
+        # 由 DB 兜住（应用层取号走锁读，见 approval_service._next_version）
+        UniqueConstraint(
+            "order_type",
+            "ref_id",
+            "version_no",
+            name="uk_approval_orders_order_type_ref_version",
+        ),
+        Index("idx_approval_orders_type_status", "order_type", "status"),
+        # 版本号按 (order_type, ref_id) 递增，须有对应索引避免全表 max 扫描
+        Index("idx_approval_orders_type_ref", "order_type", "ref_id"),
+    )
+
+    id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
+    )
+    order_no: Mapped[str] = mapped_column(
+        String(32),
+        nullable=False,
+        unique=True,
+        comment="审批单号，自动生成 AP{YYYYMMDD}-{4位当日序号}",
+    )
+    order_type: Mapped[int] = mapped_column(
+        TINYINT_TYPE, nullable=False, comment="审批对象类型：1二次分配方案 2月度结算 3调整单"
+    )
+    ref_id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED,
+        comment="引用对象ID（order_type=1 时为 businesses.id；固化无外键，删除保护由服务层承担）",
+    )
+    refer_no: Mapped[str] = mapped_column(
+        String(32), nullable=False, comment="引用对象单号（冗余固化，列表页免联查）"
+    )
+    version_no: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        server_default="1",
+        comment="提交版本号（同一对象类型+引用对象从1递增；重提产生新版本，旧单快照不覆盖；"
+        "同一对象内唯一，由uk_approval_orders_order_type_ref_version强制）",
+    )
+    snapshot_json: Mapped[dict | None] = mapped_column(
+        JSON,
+        comment="提交时内容快照（信封：schema_version/order_type/captured_at/data；历史单可空）",
+    )
+    status: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="1",
+        comment="审批状态：1待财务复核 2待领导审核 3已通过 4已驳回 5已撤回",
+    )
+    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="提交人用户名（冗余固化）"
+    )
+
+
+class ApprovalStep(Base):
+    """审批节点记录表（append-only）：每次动作只增不改，构成时间线。
+
+    不继承 TimestampMixin（留痕无更新语义，同 business_status_logs 先例）。
+    """
+
+    __tablename__ = "approval_steps"
+    __table_args__ = mysql_table_args(
+        "审批节点记录表（append-only；自动通过/撤回均有留痕）",
+        Index("idx_approval_steps_order_id", "order_id"),
+    )
+
+    id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
+    )
+    order_id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED,
+        ForeignKey("approval_orders.id", ondelete="CASCADE"),
+        nullable=False,
+        comment="审批单ID（approval_orders.id；单删记录随删）",
+    )
+    node: Mapped[int] = mapped_column(
+        TINYINT_TYPE, nullable=False, comment="审批节点：0撤回留痕 1财务复核 2领导审核"
+    )
+    action: Mapped[int] = mapped_column(
+        TINYINT_TYPE, nullable=False, comment="动作：1通过 2驳回 3自动通过 4撤回"
+    )
+    opinion: Mapped[str | None] = mapped_column(String(255), comment="审批意见（驳回时填写）")
+    operator_id: Mapped[int | None] = mapped_column(
+        BIGINT_UNSIGNED,
+        ForeignKey("users.id", ondelete="SET NULL"),
+        comment="操作人ID（自动通过/系统动作置空）",
+    )
+    operator_name: Mapped[str] = mapped_column(
+        String(64), nullable=False, comment="操作人用户名（冗余固化；系统动作记「系统」）"
+    )
+    create_time: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, server_default=text("CURRENT_TIMESTAMP"), comment="创建时间"
+    )

backend/app/models/business.py

@@ -15,7 +15,17 @@
 from datetime import date, datetime
 from decimal import Decimal
 
-from sqlalchemy import Date, DateTime, ForeignKey, Index, Numeric, String, text
+from sqlalchemy import (
+    Date,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    Numeric,
+    String,
+    UniqueConstraint,
+    text,
+)
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.models.base import (
@@ -33,6 +43,84 @@ BUSINESS_STATUS_DONE = 2
 BUSINESS_STATUS_TERMINATED = 3
 
 
+class SecondaryAllocation(Base, TimestampMixin):
+    """二次分配方案明细表（2026-10-15 补充需求「二次分配方案」）。
+
+    口径（AI_CONTEXT 待澄清 #1/#2 未答复前的边界）：
+    - 只出现在合同刚建立时；修改在首次月结前留痕放行，月结后只读（月结在 ④，
+      终态门槛先行承担「修改不影响已结算月份」）
+    - 分配比例**不要求合计 100%**：余额归属未定（澄清 #2），存储只落参与人
+      与比例，响应以 hint 提示合计/余额，不做强制校验
+    - T+ 无二次分配数据（2026-10-15 回馈）：参与人全为系统内人工维护
+    - **版本行 append-only**：编辑全量替换与驳回清空都把旧行置
+      ``is_active=0`` 而非物理删除，历史方案可回溯；当前生效行由
+      ``is_active=1`` 唯一标识。核算仍按「当前生效行」取快照
+      （``performance_ledgers.snapshot_json.alloc_plan`` 固化），版本化只
+      补齐「方案事实留存」，不改变核算口径
+
+    personnel 外键 **RESTRICT**：被方案引用的人员禁删——分摊金额待定的记录
+    不允许静默失联（silently deleted）导致回档无法人工查验；personnel_name
+    冗余固化，人离职后方案回显仍有名。uk 锁
+    (business_id, version_no, personnel_id)，同一版本内同一参与人仅一行，
+    重复提交在服务层聚合；跨版本允许同一人再次出现。
+    """
+
+    __tablename__ = "business_secondary_allocations"
+    __table_args__ = mysql_table_args(
+        # 表/列注释避开「%」字符：SHOW CREATE TABLE 经驱动参数化转义为「%%」，
+        # 会与 ORM 侧 comment 字面断言失配（全库既有注释同此惯例）
+        "业务二次分配方案版本表（append-only；比例不要求合计满额，余额归属待澄清）",
+        UniqueConstraint(
+            "business_id",
+            "version_no",
+            "personnel_id",
+            name="uk_business_secondary_allocations_business_version_personnel",
+        ),
+        Index("idx_business_secondary_allocations_business_id", "business_id"),
+        Index("idx_business_secondary_allocations_personnel_id", "personnel_id"),
+        # 取当前生效行的唯一查询形态：WHERE business_id=? AND is_active=1
+        Index(
+            "idx_business_secondary_allocations_business_active", "business_id", "is_active"
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
+    )
+    business_id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED,
+        ForeignKey("businesses.id", ondelete="CASCADE"),
+        nullable=False,
+        comment="业务ID（businesses.id；业务删除随删）",
+    )
+    version_no: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        server_default="1",
+        comment="方案版本号（同一业务从1递增；编辑/重提产生新版本，旧版本仅置历史）",
+    )
+    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="参与业务员姓名（冗余固化，离职后回显有名）"
+    )
+    ratio: Mapped[Decimal] = mapped_column(
+        Numeric(5, 2),
+        nullable=False,
+        comment="分摊比例（0-100 两位小数；不要求合计满额，余额归属待澄清#2）",
+    )
+    is_active: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="1",
+        comment="是否当前生效版本：1生效 0历史（编辑替换/驳回清空后置0，行不删除）",
+    )
+
+
 class Business(Base, TimestampMixin, TPlusSyncMixin):
     """业务表（需求 2.2.1）：业务编号自动生成，即报表 2.4.1 的「合同编号」。"""
 

backend/app/models/performance_ledger.py

@@ -0,0 +1,181 @@
+"""绩效核算台账模型（M3 ④：每笔回款仅核算一次的固化点）。
+
+**append-only 版本行**：重算 = 插入 calc_version+1 的新行，旧行仅把
+is_active 翻 0 —— 这是全表唯一的受控 UPDATE（模型注释与 test_models
+均已声明例外），行内容永不改写；历史版本可回溯（重算授权留痕的需求口径）。
+
+防重三层：服务层 CAS（UPDATE ... WHERE settlement_status=0，rowcount=0
+即 400）+ FOR UPDATE 行锁 + 库级 uk(receipt_id, calc_version, personnel_id)
+兜底。uk 含 personnel_id：二次分配分摊（澄清 #1 答复 2026-10-19，分配
+绩效——按方案比例拆给参与人、余额归合同负责人）后同一回款同版本按人
+各落一行，拆分仍是「一次核算」的组成部分；聚合行 receipt_id 为 NULL，
+MySQL 唯一索引对 NULL 不去重，天然不约束。
+
+经理聚合行（calc_type=2，receipt_id 为 NULL）：月度批处理时按「本团队
+业务员绩效 ×12.5% + 全公司 ×5%」落一行；其唯一性由月结生成的
+settlement_month 串行化 + 服务层保证（MySQL 无部分唯一索引，docstring
+声明即可）。
+
+#12 答复（2026-10-19）：经理个人户业绩是否计入聚合基数改为参数
+``manager.personal.included``（默认 0=不计入）——消费点在 settlement_service
+的聚合函数。
+"""
+
+from datetime import date
+from decimal import Decimal
+
+from sqlalchemy import (
+    JSON,
+    Date,
+    ForeignKey,
+    Index,
+    Numeric,
+    String,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import BIGINT_UNSIGNED, TINYINT_TYPE, Base, TimestampMixin, mysql_table_args
+
+# 核算类型（performance_ledgers.calc_type）
+CALC_TYPE_RECEIPT = 1  # 单笔回款核算
+CALC_TYPE_MANAGER_AGGREGATE = 2  # 经理团队聚合（月度批处理）
+
+
+class PerformanceLedger(Base, TimestampMixin):
+    """绩效核算台账表：核算事实的固化点，报表 2.4.1 的数据源。"""
+
+    __tablename__ = "performance_ledgers"
+    __table_args__ = mysql_table_args(
+        "绩效核算台账表（append-only 版本行；重算插新版本旧行仅翻 is_active）",
+        # 库级防重兜底：同一回款同版本按人仅一行（分摊拆行后负责人+参与人
+        # 各占一行；服务层 CAS+行锁之外的第二道闸）。聚合行 receipt_id 为
+        # NULL，MySQL 唯一索引对 NULL 不去重，天然不约束聚合行
+        UniqueConstraint(
+            "receipt_id",
+            "calc_version",
+            "personnel_id",
+            name="uk_performance_ledgers_receipt_id_calc_version_personnel",
+        ),
+        Index("idx_performance_ledgers_month_active", "settlement_month", "is_active"),
+        Index(
+            "idx_performance_ledgers_month_personnel_type",
+            "settlement_month",
+            "personnel_id",
+            "calc_type",
+        ),
+        Index("idx_performance_ledgers_personnel_id", "personnel_id"),
+        Index("idx_performance_ledgers_business_id", "business_id"),
+    )
+
+    id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
+    )
+    receipt_id: Mapped[int | None] = mapped_column(
+        BIGINT_UNSIGNED,
+        ForeignKey("receipts.id", ondelete="RESTRICT"),
+        comment="回款ID（receipts.id；聚合行可为 NULL）",
+    )
+    calc_version: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="1",
+        comment="核算版本（重算+1，旧行 is_active=0）",
+    )
+    is_active: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="1",
+        comment="生效标记：1当前生效 0已被重算替代（重算受控 UPDATE 例外）",
+    )
+    calc_type: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="1",
+        comment="核算类型：1单笔回款 2经理团队聚合（月度）",
+    )
+    business_id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED,
+        comment="业务ID（固化无外键；聚合行为该经理名下首行业务ID，报表下钻锚点）",
+    )
+    business_no: Mapped[str] = mapped_column(
+        String(32), nullable=False, comment="业务编号（冗余固化，列表免联查）"
+    )
+    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="岗位编码（business_roles.role_code，计提公式锚点）"
+    )
+    customer_type: Mapped[str] = mapped_column(
+        String(32), nullable=False, comment="客户分类：personal/manager_personal/enterprise"
+    )
+    product_category: Mapped[str] = mapped_column(
+        String(32),
+        nullable=False,
+        comment="产品类别：municipal_water/rail_transit/mixed（混合业务，行级明细入 snapshot_json）",
+    )
+    ship_date: Mapped[date | None] = mapped_column(Date, comment="发货日期（回款天数基准）")
+    receipt_date: Mapped[date] = mapped_column(
+        Date, nullable=False, comment="回款日期（参数版本匹配日，裁决 #11）"
+    )
+    payment_days: Mapped[int | None] = mapped_column(
+        comment="回款天数（发货日首日计第 1 天；未指定批次为 NULL；先款后货照实负值）"
+    )
+    rate_text: Mapped[str] = mapped_column(
+        String(32),
+        nullable=False,
+        comment="计提比例原文（如 4/360，防 Fraction 截断；聚合行存 12.5%/5% 结构说明）",
+    )
+    converted_profit: Mapped[Decimal | None] = mapped_column(
+        Numeric(14, 2), comment="折算毛利润额（可负；混合业务为各行汇总）"
+    )
+    performance_amount: Mapped[Decimal | None] = mapped_column(
+        Numeric(14, 2), comment="绩效金额（可负，裁决：负绩效照算不归零）"
+    )
+    barter_applied: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="0",
+        comment="以物抵顶折算：1已按 80% 折算 0否",
+    )
+    weight_r: Mapped[int | None] = mapped_column(comment="支付权重 R（回款占销售额百分比向下取整）")
+    payment_weight: Mapped[Decimal | None] = mapped_column(
+        Numeric(7, 6), comment="支付权重系数 R×R（展示用）"
+    )
+    payable_amount: Mapped[Decimal | None] = mapped_column(
+        Numeric(14, 2), comment="当期应付绩效（绩效 × 支付权重；聚合行为当月汇总）"
+    )
+    settlement_month: Mapped[str] = mapped_column(
+        String(7), nullable=False, comment="归属月（回款日期所在月，YYYY-MM；月结与报表维度）"
+    )
+    is_probation: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="0",
+        comment="试用期：1照算不发放 0否",
+    )
+    missing_cost: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="0",
+        comment="成本缺失：1有明细行缺成本（该行毛利按 0 计）0否",
+    )
+    snapshot_json: Mapped[dict | None] = mapped_column(
+        JSON, comment="计算快照（所用参数版本与行级折算明细，重算可回溯）"
+    )
+    settlement_id: Mapped[int | None] = mapped_column(
+        BIGINT_UNSIGNED,
+        ForeignKey("monthly_settlements.id", ondelete="RESTRICT"),
+        comment="所属月结ID（月结生成时回填；NULL=未入结）",
+    )
+    calc_reason: Mapped[str | None] = mapped_column(
+        String(255), comment="核算/重算原因（重算必填留痕）"
+    )
+    remark: Mapped[str | None] = mapped_column(String(255), comment="备注")

backend/app/models/personnel.py

@@ -22,6 +22,10 @@ from app.models.base import (
     mysql_table_args,
 )
 
+# personnel.status 的在职值（对照 BUSINESS_STATUS_* 集中在 models/business.py
+# 的先例：状态语义单点导出，业务/客户两侧的归属校验共用，防魔数各自漂移）
+PERSONNEL_STATUS_ACTIVE = 1
+
 
 class Personnel(Base, TimestampMixin, TPlusSyncMixin):
     """营销人员表（需求 2.1.1）。

backend/app/models/settlement.py

@@ -0,0 +1,197 @@
+"""月度结算与调整单模型（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="锁定操作人（冗余固化）")
+
+
+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="净工资 = 绩效±基本工资（按口径；试用期 0）"
+    )
+    is_probation: Mapped[int] = mapped_column(
+        TINYINT_TYPE,
+        nullable=False,
+        server_default="0",
+        comment="试用期：1绩效照算不发放（net=0，超年累计记 note）0否",
+    )
+    probation_note: Mapped[str | None] = mapped_column(
+        String(255), 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"
+    )
+    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="提交人用户名（冗余固化）"
+    )

backend/app/models/system_setting.py

@@ -0,0 +1,31 @@
+"""系统设置模型：公司信息单例行。
+
+与 M1 计提参数体系刻意分离：公司名称/logo 是「展示事实」，没有按生效日期
+时点化演算的语义（参数体系按 effective_date 取值快照），且参数值列
+value_text 为 String(64) 装不下；故独立单行表。logo 只存相对路径——文件在
+`backend/uploads/logo/`，独立于数据库备份体积且可单独替换（见
+system_setting_service）。整个系统恒为单行（迁移种子 id=1 保底，upsert 维护）。
+"""
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import BIGINT_UNSIGNED, Base, TimestampMixin, mysql_table_args
+
+
+class SystemSetting(Base, TimestampMixin):
+    """系统设置表：本期仅公司信息（公司名称 / logo 路径），全系统单行 id=1。"""
+
+    __tablename__ = "system_settings"
+    __table_args__ = mysql_table_args("系统设置表（公司信息，全系统单行）")
+
+    id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
+    )
+    company_name: Mapped[str] = mapped_column(
+        String(64), nullable=False, comment="公司名称（登录页与导出页眉展示）"
+    )
+    logo_path: Mapped[str | None] = mapped_column(
+        String(255),
+        comment="logo 相对路径（文件存 uploads/logo/，null=未上传使用默认）",
+    )

backend/app/repositories/business_repository.py

@@ -7,7 +7,7 @@ models/customer.py 定义）。
 
 from datetime import date
 
-from sqlalchemy import Row, Select, delete, func, or_, select
+from sqlalchemy import Row, Select, delete, exists, func, or_, select, update
 from sqlalchemy.orm import Session, aliased
 
 from app.models import (
@@ -17,18 +17,37 @@ from app.models import (
     Customer,
     OwnershipChangeLog,
     Personnel,
+    Receipt,
+    SecondaryAllocation,
+    Shipment,
 )
 from app.models.customer import OWNER_TYPE_BUSINESS
+from app.repositories import ownership_log_repository
 
 
 def get_by_id(session: Session, business_id: int, *, for_update: bool = False) -> Business | None:
-    """按主键取业务行；for_update 供删除保护与状态机使用。"""
+    """按主键取业务行；for_update 供删除保护、编辑门槛与状态机使用。"""
     stmt = select(Business).where(Business.id == business_id)
     if for_update:
         stmt = stmt.with_for_update()
     return session.execute(stmt).scalars().first()
 
 
+def has_docs(session: Session, business_id: int) -> bool:
+    """业务名下是否已有发货单或回款（换客户/删除保护的引用检查）。
+
+    单条 OR exists 一次往返；新增挂靠业务的单据类型时在此补充条件，
+    编辑与删除两处共用同一判定，防「delete 补了检查、update 漏补」的分叉。
+    """
+    stmt = select(
+        or_(
+            exists().where(Shipment.business_id == business_id),
+            exists().where(Receipt.business_id == business_id),
+        )
+    )
+    return bool(session.execute(stmt).scalar())
+
+
 def create(session: Session, business: Business) -> None:
     """新增业务行（不 commit，flush 让自增 id 就位）。"""
     session.add(business)
@@ -36,19 +55,26 @@ def create(session: Session, business: Business) -> None:
 
 
 def get_with_names(
-    session: Session, business_id: int
+    session: Session, business_id: int, *, for_update: bool = False
 ) -> tuple[Business, str, str | None, str | None] | None:
-    """业务行 + 客户名 + 负责人名 + 协助人名（DTO 与审计摘要共用）。"""
+    """业务行 + 客户名 + 负责人名 + 协助人名（DTO 与审计摘要共用）。
+
+    for_update 供编辑/状态流转/归属变更使用：与发货/回款写路径的
+    get_by_id(for_update=True) 同一锁口径，编辑事务与单据写事务互斥，
+    「有发货禁换客户」的快照读校验不再被并发新增旁路。
+    """
     owner = aliased(Personnel)
     assistant = aliased(Personnel)
-    row = session.execute(
+    stmt = (
         select(Business, Customer.company_name, owner.personnel_name, assistant.personnel_name)
         .join(Customer, Customer.id == Business.customer_id)
         .outerjoin(owner, owner.id == Business.owner_personnel_id)
         .outerjoin(assistant, assistant.id == Business.assistant_personnel_id)
         .where(Business.id == business_id)
-    ).first()
+    )
-    return row
+    if for_update:
+        stmt = stmt.with_for_update()
+    return session.execute(stmt).first()
 
 
 def _apply_filters(
@@ -173,16 +199,77 @@ def replace_items(session: Session, business_id: int, rows: list[BusinessItem])
     session.flush()
 
 
-def count_items(session: Session, business_ids: list[int]) -> dict[int, int]:
+def list_allocations(
-    """业务明细行数（删除保护备用）。"""
+    session: Session, business_id: int, *, active_only: bool = True
-    if not business_ids:
+) -> list[SecondaryAllocation]:
-        return {}
+    """二次分配方案（详情回显与核算取数；默认仅当前生效版本）。"""
-    rows = session.execute(
+    stmt = select(SecondaryAllocation).where(SecondaryAllocation.business_id == business_id)
-        select(BusinessItem.business_id, func.count())
+    if active_only:
-        .where(BusinessItem.business_id.in_(business_ids))
+        stmt = stmt.where(SecondaryAllocation.is_active == 1)
-        .group_by(BusinessItem.business_id)
+    return list(
-    ).all()
+        session.execute(
-    return dict(rows)
+            stmt.order_by(SecondaryAllocation.version_no, SecondaryAllocation.id)
+        ).scalars()
+    )
+
+
+def list_allocation_versions(session: Session, business_id: int) -> list[SecondaryAllocation]:
+    """方案全部版本行（含历史；业务详情「方案历史」用，按版本正序）。"""
+    return list_allocations(session, business_id, active_only=False)
+
+
+def replace_allocations(
+    session: Session, business_id: int, rows: list[SecondaryAllocation]
+) -> None:
+    """全量替换二次分配方案：旧生效行置历史，新行按下一版本号插入。
+
+    不 commit（事务边界在服务层）。版本行 append-only——编辑与清空都不
+    物理删除，驳回后仍可回溯被否决方案的参与人与比例。空 ``rows`` 表示
+    只清空生效态（不产生新版本）。
+    """
+    deactivate_allocations(session, business_id)
+    if not rows:
+        return
+    next_version = (
+        session.execute(
+            select(func.coalesce(func.max(SecondaryAllocation.version_no), 0)).where(
+                SecondaryAllocation.business_id == business_id
+            )
+        ).scalar_one()
+        + 1
+    )
+    for row in rows:
+        row.business_id = business_id
+        row.version_no = next_version
+        row.is_active = 1
+        session.add(row)
+    session.flush()
+
+
+def deactivate_allocations(session: Session, business_id: int) -> None:
+    """把业务的当前生效方案置为历史（审批驳回/编辑替换时调用；行保留）。
+
+    被否决的方案不得以「当前生效行」身份继续被核算取到；``is_active=0``
+    后核算侧自然读不到，而历史版本仍可在业务详情回溯。不 commit。
+
+    显式声明 ``synchronize_session="fetch"``：Core UPDATE 默认走 auto 策略
+    （优先 evaluate，本例的条件恰好能在 Python 侧求值，故实测也会刷新在途
+    对象）。显式写 fetch 是为了不把「在途对象被刷新」这件事押在 evaluate
+    能否解析条件上——条件一旦复杂化，auto 会退化为不刷新，同一会话里已
+    加载的方案行就会停留在 ``is_active=1`` 的过期内存值（查询虽有
+    is_active 过滤，但行对象本身仍是「生效态」，被序列化或参与判断就是
+    错的）。
+    """
+    session.execute(
+        update(SecondaryAllocation)
+        .where(
+            SecondaryAllocation.business_id == business_id,
+            SecondaryAllocation.is_active == 1,
+        )
+        .values(is_active=0)
+        .execution_options(synchronize_session="fetch")
+    )
+    session.flush()
 
 
 def add_status_log(session: Session, log: BusinessStatusLog) -> None:
@@ -217,41 +304,28 @@ def count_status_logs(session: Session, business_id: int) -> int:
 
 
 def add_ownership_log(session: Session, log: OwnershipChangeLog) -> None:
-    """追加归属变更留痕（不 commit）。"""
+    """追加归属变更留痕（共享实现，不 commit）。"""
-    session.add(log)
+    ownership_log_repository.add(session, log)
-    session.flush()
 
 
 def list_ownership_logs(
     session: Session, business_id: int, *, offset: int, limit: int
 ) -> list[Row]:
-    """某业务的归属变更留痕（join 人员出姓名；人员删除后为 None，留痕固化 ID 兜底）。"""
+    """某业务的归属变更留痕（共享实现，owner_type/business_id 参数化）。"""
-    old_p = aliased(Personnel)
+    return ownership_log_repository.list_by_ref(
-    new_p = aliased(Personnel)
+        session,
-    return list(
+        owner_type=OWNER_TYPE_BUSINESS,
-        session.execute(
+        ref_column=OwnershipChangeLog.business_id,
-            select(OwnershipChangeLog, old_p.personnel_name, new_p.personnel_name)
+        ref_id=business_id,
-            .outerjoin(old_p, old_p.id == OwnershipChangeLog.old_owner_personnel_id)
+        offset=offset,
-            .outerjoin(new_p, new_p.id == OwnershipChangeLog.new_owner_personnel_id)
+        limit=limit,
-            .where(
-                OwnershipChangeLog.owner_type == OWNER_TYPE_BUSINESS,
-                OwnershipChangeLog.business_id == business_id,
-            )
-            .order_by(OwnershipChangeLog.create_time.desc(), OwnershipChangeLog.id.desc())
-            .offset(offset)
-            .limit(limit)
-        ).all()
     )
 
 
 def count_ownership_logs(session: Session, business_id: int) -> int:
-    return int(
+    return ownership_log_repository.count_by_ref(
-        session.execute(
+        session,
-            select(func.count())
+        owner_type=OWNER_TYPE_BUSINESS,
-            .select_from(OwnershipChangeLog)
+        ref_column=OwnershipChangeLog.business_id,
-            .where(
+        ref_id=business_id,
-                OwnershipChangeLog.owner_type == OWNER_TYPE_BUSINESS,
-                OwnershipChangeLog.business_id == business_id,
-            )
-        ).scalar_one()
     )

backend/app/repositories/business_role_repository.py

@@ -25,6 +25,20 @@ def get_by_code(session: Session, role_code: str) -> BusinessRole | None:
     return session.execute(stmt).scalar_one_or_none()
 
 
+def list_by_codes(session: Session, role_codes: list[str]) -> dict[str, BusinessRole]:
+    """按编码批量取岗位（参数批次校验段用，消除逐条 N+1）。
+
+    返回 {编码: 岗位}。MySQL ci 校对下编码大小写变形也能命中，
+    键取库里的规范 role_code，调用方据此把维度值归一为规范值。
+    """
+    if not role_codes:
+        return {}
+    rows = session.execute(
+        select(BusinessRole).where(BusinessRole.role_code.in_(role_codes))
+    ).scalars()
+    return {role.role_code: role for role in rows}
+
+
 def list_roles(
     session: Session,
     *,

backend/app/repositories/customer_repository.py

@@ -4,17 +4,13 @@
 """
 
 from sqlalchemy import ColumnElement, Row, Select, func, or_, select
-from sqlalchemy.orm import Session, aliased
+from sqlalchemy.orm import Session
 
 from app.models import Customer, OwnershipChangeLog, Personnel
 from app.models.customer import OWNER_TYPE_CUSTOMER
+from app.repositories import ownership_log_repository
 from app.repositories.query_utils import fuzzy
 
-# 归属留痕表对人员 ID 无外键固化：新旧人员姓名靠对 personnel 的两次外联带出，
-# 人员被删除后姓名为 null，行仍完整可读
-_old_owner = aliased(Personnel)
-_new_owner = aliased(Personnel)
-
 # ==================== 读取 ====================
 
 
@@ -29,9 +25,7 @@ def count_business_refs(session: Session, customer_id: int) -> int:
 
     return int(
         session.execute(
-            select(func.count())
+            select(func.count()).select_from(Business).where(Business.customer_id == customer_id)
-            .select_from(Business)
-            .where(Business.customer_id == customer_id)
         ).scalar_one()
     )
 
@@ -104,33 +98,25 @@ def list_ownership_logs(
     offset: int,
     limit: int,
 ) -> list[Row]:
-    """查某客户的归属变更留痕，行内容为 (留痕, 旧归属人名, 新归属人名)。
+    """查某客户的归属变更留痕（共享实现，owner_type/customer_id 参数化）。"""
-
+    return ownership_log_repository.list_by_ref(
-    按 (create_time, id) 双键倒序：create_time 是秒级精度，同一秒内多条
+        session,
-    记录排序不确定，id 兜底保证翻页稳定（与操作日志同一理由）。
+        owner_type=OWNER_TYPE_CUSTOMER,
-    """
+        ref_column=OwnershipChangeLog.customer_id,
-    stmt = (
+        ref_id=customer_id,
-        select(OwnershipChangeLog, _old_owner.personnel_name, _new_owner.personnel_name)
+        offset=offset,
-        .outerjoin(_old_owner, OwnershipChangeLog.old_owner_personnel_id == _old_owner.id)
+        limit=limit,
-        .outerjoin(_new_owner, OwnershipChangeLog.new_owner_personnel_id == _new_owner.id)
-        .where(
-            OwnershipChangeLog.owner_type == OWNER_TYPE_CUSTOMER,
-            OwnershipChangeLog.customer_id == customer_id,
     )
-        .order_by(OwnershipChangeLog.create_time.desc(), OwnershipChangeLog.id.desc())
-        .offset(offset)
-        .limit(limit)
-    )
-    return list(session.execute(stmt).all())
 
 
 def count_ownership_logs(session: Session, *, customer_id: int) -> int:
     """统计某客户的归属留痕总数，供分页使用。"""
-    stmt = select(func.count(OwnershipChangeLog.id)).where(
+    return ownership_log_repository.count_by_ref(
-        OwnershipChangeLog.owner_type == OWNER_TYPE_CUSTOMER,
+        session,
-        OwnershipChangeLog.customer_id == customer_id,
+        owner_type=OWNER_TYPE_CUSTOMER,
+        ref_column=OwnershipChangeLog.customer_id,
+        ref_id=customer_id,
     )
-    return int(session.execute(stmt).scalar_one())
 
 
 def _base_select() -> Select:
@@ -188,7 +174,5 @@ def delete(session: Session, customer: Customer) -> None:
 
 
 def add_ownership_log(session: Session, log: OwnershipChangeLog) -> OwnershipChangeLog:
-    """写入一条归属变更留痕。只 flush 不 commit，与主表归属更新同事务提交。"""
+    """写入一条归属变更留痕（共享实现）。只 flush 不 commit，与主表更新同事务。"""
-    session.add(log)
+    return ownership_log_repository.add(session, log)
-    session.flush()
-    return log

backend/app/repositories/dashboard_repository.py

@@ -0,0 +1,244 @@
+"""工作台仓储：四区块的只读聚合查询；不 commit、不抛业务异常。
+
+总览只做 SQL 聚合（SUM/COUNT DISTINCT），不复用报表的
+``department_summary``——后者会加载整月台账并逐团队查人员，适合报表页，
+不适合每次打开工作台。
+"""
+
+from datetime import date, datetime
+
+from sqlalchemy import exists, func, or_, select
+from sqlalchemy.orm import Session, defer
+
+from app.models import (
+    ApprovalOrder,
+    Business,
+    BusinessRole,
+    MonthlySettlement,
+    PerformanceLedger,
+    Personnel,
+    Receipt,
+    Shipment,
+)
+from app.models.approval import (
+    APPROVAL_STATUS_PENDING_FINANCE,
+    APPROVAL_STATUS_PENDING_LEADER,
+)
+
+_ACTIVE_SINGLE = (PerformanceLedger.calc_type == 1, PerformanceLedger.is_active == 1)
+_PENDING_STATUSES = (
+    APPROVAL_STATUS_PENDING_FINANCE,
+    APPROVAL_STATUS_PENDING_LEADER,
+)
+
+
+# ==== 经营绩效总览 ====
+
+def sum_month_performance(session: Session, month: str) -> dict:
+    """当月单笔生效行合计与人员数（拆行求和不失真，人数需 DISTINCT）。"""
+    return session.execute(
+        select(
+            func.coalesce(func.sum(PerformanceLedger.performance_amount), 0).label(
+                "performance_total"
+            ),
+            func.coalesce(func.sum(PerformanceLedger.payable_amount), 0).label("payable_total"),
+            func.count(func.distinct(PerformanceLedger.personnel_id)).label("person_count"),
+        ).where(
+            PerformanceLedger.settlement_month == month,
+            *_ACTIVE_SINGLE,
+        )
+    ).mappings().one()
+
+
+def performance_trend(session: Session, months: list[str]) -> dict[str, object]:
+    """近 N 个月绩效合计（按台账归属月）。"""
+    rows = session.execute(
+        select(
+            PerformanceLedger.settlement_month,
+            func.coalesce(func.sum(PerformanceLedger.performance_amount), 0),
+        )
+        .where(
+            PerformanceLedger.settlement_month.in_(months),
+            *_ACTIVE_SINGLE,
+        )
+        .group_by(PerformanceLedger.settlement_month)
+    ).all()
+    return dict(rows)
+
+
+def receipt_trend(
+    session: Session, *, start_date: date, end_date: date
+) -> dict[str, object]:
+    """近 N 个月回款合计（按到账月，含未核算回款——与台账口径不同，页面注明）。
+
+    过滤走 ``receipt_date`` 原始列范围（可用索引）；``DATE_FORMAT`` 只用于
+    分组，不参与 WHERE，避免函数列导致全表扫描。
+    """
+    month_expr = func.date_format(Receipt.receipt_date, "%Y-%m")
+    rows = session.execute(
+        select(month_expr, func.coalesce(func.sum(Receipt.amount), 0))
+        .where(Receipt.receipt_date >= start_date, Receipt.receipt_date < end_date)
+        .group_by(month_expr)
+    ).all()
+    return dict(rows)
+
+
+def count_active_managers(session: Session) -> int:
+    """在职营销经理数（团队数口径，与部门汇总的团队枚举一致）。"""
+    return int(
+        session.execute(
+            select(func.count())
+            .select_from(Personnel)
+            .join(BusinessRole, Personnel.business_role_id == BusinessRole.id)
+            .where(
+                BusinessRole.role_code == "sales_manager",
+                Personnel.status == 1,
+            )
+        ).scalar_one()
+    )
+
+
+def get_month_settlement(session: Session, month: str) -> MonthlySettlement | None:
+    """当月月结头（状态与锁定时间角标）。"""
+    return session.execute(
+        select(MonthlySettlement).where(MonthlySettlement.settlement_month == month)
+    ).scalar_one_or_none()
+
+
+# ==== 待办事项 ====
+
+def list_pending_approvals(
+    session: Session, *, statuses: tuple[int, ...], limit: int
+) -> list[ApprovalOrder]:
+    """待处理审批单（按提交时间升序——最久的排前面）。
+
+    ``statuses`` 由调用方按当前用户角色解析（待我审批），空元组返回空列表。
+
+    排除 snapshot_json 列（快照可达上百 KB，待办只取单号/类型/提交人/时间）。
+    """
+    if not statuses:
+        return []
+    return list(
+        session.execute(
+            select(ApprovalOrder)
+            .options(defer(ApprovalOrder.snapshot_json))
+            .where(ApprovalOrder.status.in_(statuses))
+            .order_by(ApprovalOrder.create_time.asc(), ApprovalOrder.id.asc())
+            .limit(limit)
+        ).scalars()
+    )
+
+
+def count_pending_approvals(session: Session, *, statuses: tuple[int, ...]) -> int:
+    if not statuses:
+        return 0
+    return int(
+        session.execute(
+            select(func.count())
+            .select_from(ApprovalOrder)
+            .where(ApprovalOrder.status.in_(statuses))
+        ).scalar_one()
+    )
+
+
+def list_unassigned_receipts(session: Session, *, limit: int) -> list:
+    """回款未指定发货批次（shipment_id IS NULL，核算前置缺失）。"""
+    return list(
+        session.execute(
+            select(
+                Receipt,
+                Business.business_no.label("business_no"),
+            )
+            .outerjoin(Business, Business.id == Receipt.business_id)
+            .where(Receipt.shipment_id.is_(None))
+            .order_by(Receipt.receipt_date.asc(), Receipt.id.asc())
+            .limit(limit)
+        ).all()
+    )
+
+
+def count_unassigned_receipts(session: Session) -> int:
+    return int(
+        session.execute(
+            select(func.count())
+            .select_from(Receipt)
+            .where(Receipt.shipment_id.is_(None))
+        ).scalar_one()
+    )
+
+
+# ==== 风险预警 ====
+
+def list_overdue_shipments(session: Session, *, cutoff: date, limit: int) -> list:
+    """发货后超过阈值且该批次无任何回款的发货单（回款逾期规则）。
+
+    已终止业务（status=3）不再催收，排除在预警之外；业务行缺失时仍保留，
+    避免历史脏数据让发货单从预警中静默消失。
+    """
+    has_receipt = exists().where(Receipt.shipment_id == Shipment.id)
+    return list(
+        session.execute(
+            select(
+                Shipment,
+                Business.business_no.label("business_no"),
+            )
+            .outerjoin(Business, Business.id == Shipment.business_id)
+            .where(
+                Shipment.ship_date <= cutoff,
+                ~has_receipt,
+                or_(Business.status.is_(None), Business.status != 3),
+            )
+            .order_by(Shipment.ship_date.asc())
+            .limit(limit)
+        ).all()
+    )
+
+
+def count_overdue_shipments(session: Session, *, cutoff: date) -> int:
+    has_receipt = exists().where(Receipt.shipment_id == Shipment.id)
+    return int(
+        session.execute(
+            select(func.count())
+            .select_from(Shipment)
+            .outerjoin(Business, Business.id == Shipment.business_id)
+            .where(
+                Shipment.ship_date <= cutoff,
+                ~has_receipt,
+                or_(Business.status.is_(None), Business.status != 3),
+            )
+        ).scalar_one()
+    )
+
+
+def list_overdue_approvals(
+    session: Session, *, cutoff: datetime, limit: int
+) -> list[ApprovalOrder]:
+    """提交后超过阈值仍未处理的审批单（审批超时规则）。
+
+    排除 snapshot_json 列（同待办：预警只用单号/类型/提交人/时间）。
+    """
+    return list(
+        session.execute(
+            select(ApprovalOrder)
+            .options(defer(ApprovalOrder.snapshot_json))
+            .where(
+                ApprovalOrder.status.in_(_PENDING_STATUSES),
+                ApprovalOrder.create_time < cutoff,
+            )
+            .order_by(ApprovalOrder.create_time.asc())
+            .limit(limit)
+        ).scalars()
+    )
+
+
+def count_overdue_approvals(session: Session, *, cutoff: datetime) -> int:
+    return int(
+        session.execute(
+            select(func.count())
+            .select_from(ApprovalOrder)
+            .where(
+                ApprovalOrder.status.in_(_PENDING_STATUSES),
+                ApprovalOrder.create_time < cutoff,
+            )
+        ).scalar_one()
+    )

backend/app/repositories/ownership_log_repository.py

@@ -0,0 +1,56 @@
+"""归属变更留痕的共享数据访问（客户/业务两维度共用）。
+
+owner_type 与引用列由调用方参数化 —— 此前客户、业务两侧各持一套逐行
+同构的 list/count/add，排序口径与 join 兜底的调整须同步两处；收口后
+「被删人员留痕仍可读」「翻页稳定双键倒序」等口径单点维护。
+"""
+
+from sqlalchemy import Row, func, select
+from sqlalchemy.orm import Session, aliased
+
+from app.models import OwnershipChangeLog, Personnel
+
+
+def list_by_ref(
+    session: Session,
+    *,
+    owner_type: int,
+    ref_column,
+    ref_id: int,
+    offset: int,
+    limit: int,
+) -> list[Row]:
+    """查某引用对象的归属留痕，行内容为 (留痕, 旧归属人名, 新归属人名)。
+
+    人员删除后 join 出 None，留痕固化 ID 兜底可读。按 (create_time, id)
+    双键倒序：create_time 是秒级精度，同一秒内多条排序不确定，id 兜底
+    保证翻页稳定（与操作日志同一理由）。
+    """
+    old_person = aliased(Personnel)
+    new_person = aliased(Personnel)
+    stmt = (
+        select(OwnershipChangeLog, old_person.personnel_name, new_person.personnel_name)
+        .outerjoin(old_person, OwnershipChangeLog.old_owner_personnel_id == old_person.id)
+        .outerjoin(new_person, OwnershipChangeLog.new_owner_personnel_id == new_person.id)
+        .where(OwnershipChangeLog.owner_type == owner_type, ref_column == ref_id)
+        .order_by(OwnershipChangeLog.create_time.desc(), OwnershipChangeLog.id.desc())
+        .offset(offset)
+        .limit(limit)
+    )
+    return list(session.execute(stmt).all())
+
+
+def count_by_ref(session: Session, *, owner_type: int, ref_column, ref_id: int) -> int:
+    """统计某引用对象的归属留痕总数，供分页使用。"""
+    stmt = select(func.count(OwnershipChangeLog.id)).where(
+        OwnershipChangeLog.owner_type == owner_type,
+        ref_column == ref_id,
+    )
+    return int(session.execute(stmt).scalar_one())
+
+
+def add(session: Session, log: OwnershipChangeLog) -> OwnershipChangeLog:
+    """写入一条归属变更留痕。只 flush 不 commit，与主表归属更新同事务提交。"""
+    session.add(log)
+    session.flush()
+    return log

backend/app/repositories/param_repository.py

@@ -81,6 +81,21 @@ def get_definition_by_code(session: Session, param_code: str) -> ParamDefinition
     return session.execute(stmt).scalar_one_or_none()
 
 
+def list_definitions_by_codes(
+    session: Session, param_codes: list[str]
+) -> dict[str, ParamDefinition]:
+    """按编码批量取参数定义（提交批次的校验段用，消除逐条 N+1）。
+
+    返回 {编码: 定义}；未定义的编码不在结果中，由调用方判缺失。
+    """
+    if not param_codes:
+        return {}
+    rows = session.execute(
+        select(ParamDefinition).where(ParamDefinition.param_code.in_(param_codes))
+    ).scalars()
+    return {definition.param_code: definition for definition in rows}
+
+
 def list_history(
     session: Session,
     param_id: int,

backend/app/repositories/performance_ledger_repository.py

@@ -0,0 +1,156 @@
+"""绩效核算台账仓储：只读写数据并 flush；commit/rollback 在服务层。"""
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models import PerformanceLedger
+from app.models.performance_ledger import CALC_TYPE_MANAGER_AGGREGATE
+from app.schemas.calc import LedgerQuery
+
+
+def get_by_id(session: Session, ledger_id: int) -> PerformanceLedger | None:
+    """按主键取台账行。"""
+    return session.get(PerformanceLedger, ledger_id)
+
+
+def get_active_by_receipt(
+    session: Session, receipt_id: int, *, calc_type: int = 1
+) -> PerformanceLedger | None:
+    """取某回款的当前生效核算行（is_active=1；无则 None）。
+
+    二次分摊拆行后同回款可有多行（负责人+参与人）——重算作废用
+    ``list_active_by_receipt``；本函数仅限确知单行的调用方（重算前的
+    存在性判断按业务维度走 has_active_for_business）。
+    """
+    return session.execute(
+        select(PerformanceLedger).where(
+            PerformanceLedger.receipt_id == receipt_id,
+            PerformanceLedger.calc_type == calc_type,
+            PerformanceLedger.is_active == 1,
+        )
+    ).scalar_one_or_none()
+
+
+def list_active_by_receipt(
+    session: Session, receipt_id: int, *, calc_type: int = 1
+) -> list[PerformanceLedger]:
+    """取某回款当前生效的**全部**核算行（分摊拆行后负责人+参与人各一行）。"""
+    return list(
+        session.execute(
+            select(PerformanceLedger).where(
+                PerformanceLedger.receipt_id == receipt_id,
+                PerformanceLedger.calc_type == calc_type,
+                PerformanceLedger.is_active == 1,
+            )
+        ).scalars()
+    )
+
+
+def has_active_for_business(session: Session, business_id: int, *, calc_type: int = 1) -> bool:
+    """该业务是否已有生效核算行（核算粒度 #25：业务级一次性计提的判定）。"""
+    return (
+        session.execute(
+            select(func.count())
+            .select_from(PerformanceLedger)
+            .where(
+                PerformanceLedger.business_id == business_id,
+                PerformanceLedger.calc_type == calc_type,
+                PerformanceLedger.is_active == 1,
+            )
+        ).scalar_one()
+        > 0
+    )
+
+
+def get_active_by_receipt_of_business(
+    session: Session, business_id: int, *, calc_type: int = 1
+) -> PerformanceLedger:
+    """取该业务当前生效的核算行（重复回款登记进度时回显既有台账）。"""
+    return (
+        session.execute(
+            select(PerformanceLedger)
+            .where(
+                PerformanceLedger.business_id == business_id,
+                PerformanceLedger.calc_type == calc_type,
+                PerformanceLedger.is_active == 1,
+            )
+            .order_by(PerformanceLedger.id.desc())
+        )
+        .scalars()
+        .first()
+    )
+
+
+def add(session: Session, row: PerformanceLedger) -> PerformanceLedger:
+    """落台账行（flush 取 id；commit 在服务层）。"""
+    session.add(row)
+    session.flush()
+    return row
+
+
+def mark_inactive(session: Session, row: PerformanceLedger) -> None:
+    """重算时把旧版本行翻为已替代（全表唯一的受控 UPDATE 例外；不 commit）。"""
+    row.is_active = 0
+    session.flush()
+
+
+def deactivate_month_aggregates(session: Session, month: str) -> None:
+    """月结重生成时作废该月全部经理聚合行（calc_type=2）。
+
+    聚合行每次生成重建，旧行不翻 0 会与新行重复计入（按人聚合按 is_active
+    过滤）。与 mark_inactive 同属 is_active 翻 0 的受控 UPDATE 例外；set 批量
+    版本而非逐行——聚合行一个月至多几行，且无逐行回读必要。
+    """
+    from sqlalchemy import update
+
+    session.execute(
+        update(PerformanceLedger)
+        .where(
+            PerformanceLedger.settlement_month == month,
+            PerformanceLedger.calc_type == CALC_TYPE_MANAGER_AGGREGATE,
+            PerformanceLedger.is_active == 1,
+        )
+        .values(is_active=0)
+    )
+    session.flush()
+
+
+def next_version(session: Session, receipt_id: int) -> int:
+    """某回款的下一个核算版本号（max+1；无行时 1）。"""
+    current = session.execute(
+        select(func.max(PerformanceLedger.calc_version)).where(
+            PerformanceLedger.receipt_id == receipt_id
+        )
+    ).scalar_one()
+    return int(current or 0) + 1
+
+
+def list_ledger(session: Session, query: LedgerQuery) -> list[PerformanceLedger]:
+    """分页查询台账（筛选：月/人员/业务/生效/类型）。"""
+    stmt = select(PerformanceLedger).where(*_filters(query))
+    stmt = stmt.order_by(PerformanceLedger.id.desc()).offset(query.offset).limit(query.page_size)
+    return list(session.execute(stmt).scalars())
+
+
+def count_ledger(session: Session, query: LedgerQuery) -> int:
+    """台账计数（与 list_ledger 同筛选）。"""
+    return int(
+        session.execute(
+            select(func.count()).select_from(PerformanceLedger).where(*_filters(query))
+        ).scalar_one()
+    )
+
+
+def _filters(query: LedgerQuery) -> tuple:
+    filters = []
+    if query.settlement_month:
+        filters.append(PerformanceLedger.settlement_month == query.settlement_month)
+    if query.personnel_id is not None:
+        filters.append(PerformanceLedger.personnel_id == query.personnel_id)
+    if query.business_id is not None:
+        filters.append(PerformanceLedger.business_id == query.business_id)
+    if query.is_active is not None:
+        filters.append(PerformanceLedger.is_active == query.is_active)
+    if query.calc_type is not None:
+        filters.append(PerformanceLedger.calc_type == query.calc_type)
+    return tuple(filters)

backend/app/repositories/product_repository.py

@@ -6,7 +6,7 @@
 from sqlalchemy import Select, func, or_, select
 from sqlalchemy.orm import Session
 
-from app.models import Product
+from app.models import BusinessItem, Product, ShipmentItem
 
 # ==================== 读取 ====================
 
@@ -100,6 +100,25 @@ def _apply_filters(
     return stmt
 
 
+def count_refs(session: Session, product_id: int) -> int:
+    """统计引用该产品的业务明细与发货明细行数（删除保护，business_id 先例）。
+
+    两张明细表对 products 均 RESTRICT 外键：先查给出可读的 400；校验与
+    删除之间的并发引用由锁行 + FK 兜底（service 层再翻译 IntegrityError）。
+    """
+    stmt = select(
+        select(func.count())
+        .select_from(BusinessItem)
+        .where(BusinessItem.product_id == product_id)
+        .scalar_subquery()
+        + select(func.count())
+        .select_from(ShipmentItem)
+        .where(ShipmentItem.product_id == product_id)
+        .scalar_subquery()
+    )
+    return int(session.execute(stmt).scalar_one())
+
+
 # ==================== 写入 ====================
 
 
@@ -111,6 +130,6 @@ def create(session: Session, product: Product) -> Product:
 
 
 def delete(session: Session, product: Product) -> None:
-    """物理删除产品。调用方须先完成引用保护校验（V5 就位后生效）。"""
+    """物理删除产品。调用方须先完成引用保护校验（count_refs + FK 兜底）。"""
     session.delete(product)
     session.flush()

backend/app/repositories/rating_repository.py

@@ -11,14 +11,21 @@ from app.models import CustomerRatingGrade
 # ==================== 读取 ====================
 
 
-def list_all(session: Session) -> list[CustomerRatingGrade]:
+def list_all(session: Session, *, for_update: bool = False) -> list[CustomerRatingGrade]:
     """全量等级，按 sort_order 升序、id 兜底（同序次序稳定）。
 
     不分页：等级映射是判定表，数量个位数，分页无意义。
+
+    for_update 供区间重叠判定使用：先查后写在无锁时，两管理员并发提交
+    重叠区间会互判不重叠而双双入库（区间重叠无唯一键可拦）——锁全表行
+    串行化并发的重叠判定（先到者提交后，后到者在锁下读到新区间即判重叠）。
+    只读直出（list_grades）不加锁。
     """
     stmt = select(CustomerRatingGrade).order_by(
         CustomerRatingGrade.sort_order, CustomerRatingGrade.id
     )
+    if for_update:
+        stmt = stmt.with_for_update()
     return list(session.execute(stmt).scalars())
 
 

backend/app/repositories/receipt_repository.py

@@ -88,9 +88,7 @@ def list_receipts(
         is_barter=is_barter,
         settlement_status=settlement_status,
     )
-    return list(
+    return list(session.execute(stmt.order_by(Receipt.id.desc()).offset(offset).limit(limit)).all())
-        session.execute(stmt.order_by(Receipt.id.desc()).offset(offset).limit(limit)).all()
-    )
 
 
 def count_receipts(

backend/app/repositories/report_repository.py

@@ -0,0 +1,423 @@
+"""报表统计仓储：只读聚合查询；不 commit、不抛业务异常。
+
+报表与台账分页查询刻意分开而非复用 ``performance_ledger_repository``：
+- 台账查询允许聚合行（calc_type=2），报表明细必须显式排除——经理聚合
+  行 receipt_id 为 NULL，混入明细会让合同编号/天数列失真、业务统计的
+  绩效被整团队聚合额污染；
+- 月结的 ``_confirm_scope`` 带 ``settlement_id IS NULL``（可入结口径），
+  报表要看的是同月**全量**生效单笔行，口径不同；
+- 聚合需求（SUM/GROUP BY）台账仓储完全没有，报表在此统一实现。
+
+发货额/回款额直接读 businesses 的汇总冗余列（服务层事务内单点维护），
+不逐业务子查询发货/回款表；绩效额 businesses 无冗余列，用子查询联台账。
+"""
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.core.report_meta import DayBucket
+from app.models import (
+    AdjustmentOrder,
+    Business,
+    Customer,
+    MonthlySettlement,
+    PerformanceLedger,
+    Personnel,
+)
+from app.schemas.report import (
+    BusinessStatsQuery,
+    PaymentDetailQuery,
+    PaymentStatsQuery,
+    PersonalDetailQuery,
+)
+
+# 单笔生效行基础条件：报表四表共用（聚合行与已替代版本一律排除）
+_ACTIVE_SINGLE = (PerformanceLedger.calc_type == 1, PerformanceLedger.is_active == 1)
+
+
+# ==== 个人绩效明细（FR-029）====
+
+
+def _personal_filters(query: PersonalDetailQuery) -> tuple:
+    filters = [*_ACTIVE_SINGLE]
+    if query.settlement_month:
+        filters.append(PerformanceLedger.settlement_month == query.settlement_month)
+    if query.personnel_id is not None:
+        filters.append(PerformanceLedger.personnel_id == query.personnel_id)
+    if query.customer_type:
+        filters.append(PerformanceLedger.customer_type == query.customer_type)
+    if query.product_category:
+        filters.append(PerformanceLedger.product_category == query.product_category)
+    if query.role_code:
+        filters.append(PerformanceLedger.role_code == query.role_code)
+    return tuple(filters)
+
+
+def list_personal_detail(
+    session: Session, query: PersonalDetailQuery, *, offset: int, limit: int
+) -> list[PerformanceLedger]:
+    """个人绩效明细分页（回款日倒序，同人按版本可追溯）。"""
+    stmt = select(PerformanceLedger).where(*_personal_filters(query))
+    stmt = stmt.order_by(PerformanceLedger.receipt_date.desc(), PerformanceLedger.id.desc())
+    stmt = stmt.offset(offset).limit(limit)
+    return list(session.execute(stmt).scalars())
+
+
+def count_personal_detail(session: Session, query: PersonalDetailQuery) -> int:
+    """个人绩效明细计数（与 list_personal_detail 同筛选）。"""
+    return int(
+        session.execute(
+            select(func.count()).select_from(PerformanceLedger).where(*_personal_filters(query))
+        ).scalar_one()
+    )
+
+
+def sum_personal_detail(session: Session, query: PersonalDetailQuery) -> dict:
+    """全筛选口径合计（分页与合计同条件，避免「页脚合计≠全部结果」）。"""
+    return (
+        session.execute(
+            select(
+                func.count().label("row_count"),
+                func.coalesce(func.sum(PerformanceLedger.performance_amount), 0).label(
+                    "performance_total"
+                ),
+                func.coalesce(func.sum(PerformanceLedger.payable_amount), 0).label("payable_total"),
+                func.coalesce(func.sum(PerformanceLedger.converted_profit), 0).label(
+                    "converted_profit_total"
+                ),
+            ).where(*_personal_filters(query))
+        )
+        .mappings()
+        .one()
+    )
+
+
+# ==== 部门汇总取数（FR-030）====
+
+
+def list_month_receipt_rows(session: Session, month: str) -> list[PerformanceLedger]:
+    """同月全量生效单笔台账行（部门汇总基数与成员明细的取数）。"""
+    return list(
+        session.execute(
+            select(PerformanceLedger).where(
+                PerformanceLedger.settlement_month == month, *_ACTIVE_SINGLE
+            )
+        ).scalars()
+    )
+
+
+def list_month_manager_aggregates(session: Session, month: str) -> list[PerformanceLedger]:
+    """同月经理聚合行（calc_type=2）：已生成月结时的冻结对照值。"""
+    return list(
+        session.execute(
+            select(PerformanceLedger).where(
+                PerformanceLedger.settlement_month == month,
+                PerformanceLedger.calc_type == 2,
+                PerformanceLedger.is_active == 1,
+            )
+        ).scalars()
+    )
+
+
+def list_month_adjustments(session: Session, month: str) -> list[AdjustmentOrder]:
+    """同月已生效调整单（status=2）——报表汇总并入的口径。
+
+    与 list_adjustments（调整单管理页）不同：必须按月筛选且只取生效行，
+    待审批/已驳回/已撤回的金额绝不能混进报表。
+    """
+    return list(
+        session.execute(
+            select(AdjustmentOrder).where(
+                AdjustmentOrder.settlement_month == month,
+                AdjustmentOrder.status == 2,
+            )
+        ).scalars()
+    )
+
+
+def list_month_settlement(session: Session, month: str) -> MonthlySettlement | None:
+    """同月月结头（部门汇总展示锁定状态用；无则 None）。"""
+    return session.execute(
+        select(MonthlySettlement).where(MonthlySettlement.settlement_month == month)
+    ).scalar_one_or_none()
+
+
+# ==== 业务统计（FR-031 之一）====
+
+
+def _business_perf_subquery():
+    """业务维度绩效子查询（排除聚合行，防 12.5%/5% 聚合额污染单业务绩效）。"""
+    return (
+        select(
+            PerformanceLedger.business_id.label("business_id"),
+            func.coalesce(func.sum(PerformanceLedger.performance_amount), 0).label("perf"),
+            func.coalesce(func.sum(PerformanceLedger.payable_amount), 0).label("payable"),
+        )
+        .where(*_ACTIVE_SINGLE)
+        .group_by(PerformanceLedger.business_id)
+        .subquery()
+    )
+
+
+def _business_filters(query: BusinessStatsQuery) -> tuple:
+    filters = []
+    if query.keyword:
+        # 业务编号/公司名称双列 OR 模糊；contains(autoescape) 转义通配符，
+        # 与 business_repository._apply_filters 同口径（双列 OR 用法为该处既定）
+        filters.append(
+            Business.business_no.contains(query.keyword, autoescape=True)
+            | Customer.company_name.contains(query.keyword, autoescape=True)
+        )
+    if query.customer_id is not None:
+        filters.append(Business.customer_id == query.customer_id)
+    if query.owner_personnel_id is not None:
+        filters.append(Business.owner_personnel_id == query.owner_personnel_id)
+    if query.status is not None:
+        filters.append(Business.status == query.status)
+    if query.date_from is not None:
+        filters.append(Business.business_date >= query.date_from)
+    if query.date_to is not None:
+        filters.append(Business.business_date <= query.date_to)
+    return tuple(filters)
+
+
+def _business_select(query: BusinessStatsQuery):
+    perf_sq = _business_perf_subquery()
+    return (
+        select(
+            Business,
+            Customer.company_name.label("customer_name"),
+            Personnel.personnel_name.label("owner_personnel_name"),
+            perf_sq.c.perf.label("performance_amount"),
+            perf_sq.c.payable.label("payable_amount"),
+        )
+        .outerjoin(Customer, Customer.id == Business.customer_id)
+        .outerjoin(Personnel, Personnel.id == Business.owner_personnel_id)
+        .outerjoin(perf_sq, perf_sq.c.business_id == Business.id)
+        .where(*_business_filters(query))
+    )
+
+
+def list_business_stats(
+    session: Session, query: BusinessStatsQuery, *, offset: int, limit: int
+) -> list:
+    """业务统计分页（业务日期倒序）。"""
+    stmt = _business_select(query).order_by(Business.id.desc()).offset(offset).limit(limit)
+    return list(session.execute(stmt).all())
+
+
+def count_business_stats(session: Session, query: BusinessStatsQuery) -> int:
+    """业务统计计数（联客户表因关键字筛选涉及客户名）。"""
+    stmt = (
+        select(func.count())
+        .select_from(Business)
+        .outerjoin(Customer, Customer.id == Business.customer_id)
+        .where(*_business_filters(query))
+    )
+    return int(session.execute(stmt).scalar_one())
+
+
+def sum_business_stats(session: Session, query: BusinessStatsQuery) -> dict:
+    """业务统计全筛选合计（业务数/发货/回款/销售额/绩效/应付）。"""
+    perf_sq = _business_perf_subquery()
+    return (
+        session.execute(
+            select(
+                func.count().label("row_count"),
+                func.coalesce(func.sum(Business.total_ship_amount), 0).label("ship_total"),
+                func.coalesce(func.sum(Business.total_received_amount), 0).label("received_total"),
+                func.coalesce(func.sum(Business.total_sale_amount), 0).label("sale_total"),
+                func.coalesce(func.sum(perf_sq.c.perf), 0).label("performance_total"),
+                func.coalesce(func.sum(perf_sq.c.payable), 0).label("payable_total"),
+            )
+            .outerjoin(Customer, Customer.id == Business.customer_id)
+            .outerjoin(perf_sq, perf_sq.c.business_id == Business.id)
+            .where(*_business_filters(query))
+        )
+        .mappings()
+        .one()
+    )
+
+
+# ==== 回款统计（FR-031 之二）====
+
+
+def _payment_filters(query: PaymentStatsQuery | PaymentDetailQuery) -> tuple:
+    filters = [*_ACTIVE_SINGLE]
+    if query.settlement_month:
+        filters.append(PerformanceLedger.settlement_month == query.settlement_month)
+    if query.date_from is not None:
+        filters.append(PerformanceLedger.receipt_date >= query.date_from)
+    if query.date_to is not None:
+        filters.append(PerformanceLedger.receipt_date <= query.date_to)
+    if query.customer_type:
+        filters.append(PerformanceLedger.customer_type == query.customer_type)
+    if query.product_category:
+        filters.append(PerformanceLedger.product_category == query.product_category)
+    return tuple(filters)
+
+
+def group_payment_by_days(session: Session, query: PaymentStatsQuery) -> list:
+    """按（回款天数精确值, 客户类型, 产品类别）聚合绩效与应付。"""
+    return list(
+        session.execute(
+            select(
+                PerformanceLedger.payment_days,
+                PerformanceLedger.customer_type,
+                PerformanceLedger.product_category,
+                func.coalesce(func.sum(PerformanceLedger.performance_amount), 0).label(
+                    "performance_total"
+                ),
+                func.coalesce(func.sum(PerformanceLedger.payable_amount), 0).label("payable_total"),
+                func.count().label("ledger_count"),
+            )
+            .where(*_payment_filters(query))
+            .group_by(
+                PerformanceLedger.payment_days,
+                PerformanceLedger.customer_type,
+                PerformanceLedger.product_category,
+            )
+        ).all()
+    )
+
+
+def group_payment_receipt_by_days(session: Session, query: PaymentStatsQuery) -> list:
+    """按维度聚合回款金额与笔数——金额侧必须按 receipt_id 去重。
+
+    二次分摊拆行使同一回款在台账出现多行，直接 SUM(receipts.amount) 会
+    按拆行数翻倍；台账拆行只改归属人，不改维度值（payment_days/客户类型/
+    产品类别），因此先对台账行 DISTINCT 出回款维度，再联回款表求和。
+    """
+    distinct_receipts = (
+        select(
+            PerformanceLedger.receipt_id.label("receipt_id"),
+            PerformanceLedger.payment_days.label("payment_days"),
+            PerformanceLedger.customer_type.label("customer_type"),
+            PerformanceLedger.product_category.label("product_category"),
+        )
+        .where(*_payment_filters(query), PerformanceLedger.receipt_id.is_not(None))
+        .distinct()
+        .subquery()
+    )
+    from app.models import Receipt
+
+    return list(
+        session.execute(
+            select(
+                distinct_receipts.c.payment_days,
+                distinct_receipts.c.customer_type,
+                distinct_receipts.c.product_category,
+                func.coalesce(func.sum(Receipt.amount), 0).label("receipt_amount"),
+                func.count(distinct_receipts.c.receipt_id).label("receipt_count"),
+            )
+            .outerjoin(Receipt, Receipt.id == distinct_receipts.c.receipt_id)
+            .group_by(
+                distinct_receipts.c.payment_days,
+                distinct_receipts.c.customer_type,
+                distinct_receipts.c.product_category,
+            )
+        ).all()
+    )
+
+
+def group_payment_by_customer_type(session: Session, query: PaymentStatsQuery) -> list:
+    """按客户类型聚合（绩效 + 回款金额）。"""
+    return _group_by_dimension(session, query, PerformanceLedger.customer_type)
+
+
+def group_payment_by_product_category(session: Session, query: PaymentStatsQuery) -> list:
+    """按产品类别聚合（绩效 + 回款金额）。"""
+    return _group_by_dimension(session, query, PerformanceLedger.product_category)
+
+
+def _group_by_dimension(session: Session, query: PaymentStatsQuery, dim_column) -> list:
+    """维度聚合共用实现（绩效侧 GROUP BY + 金额侧 DISTINCT 去重联回款）。"""
+    from app.models import Receipt
+
+    dim_perf = (
+        select(
+            dim_column.label("dim"),
+            func.coalesce(func.sum(PerformanceLedger.performance_amount), 0).label(
+                "performance_total"
+            ),
+            func.coalesce(func.sum(PerformanceLedger.payable_amount), 0).label("payable_total"),
+            func.count().label("ledger_count"),
+        )
+        .where(*_payment_filters(query))
+        .group_by(dim_column)
+    )
+    dim_receipts = (
+        select(
+            dim_column.label("dim"),
+            PerformanceLedger.receipt_id.label("receipt_id"),
+        )
+        .where(*_payment_filters(query), PerformanceLedger.receipt_id.is_not(None))
+        .distinct()
+        .subquery()
+    )
+    perf_rows = {row.dim: row for row in session.execute(dim_perf).all()}
+    receipt_rows = session.execute(
+        select(
+            dim_receipts.c.dim,
+            func.coalesce(func.sum(Receipt.amount), 0).label("receipt_amount"),
+        )
+        .outerjoin(Receipt, Receipt.id == dim_receipts.c.receipt_id)
+        .group_by(dim_receipts.c.dim)
+    ).all()
+    receipt_amounts = {row.dim: row.receipt_amount for row in receipt_rows}
+    return [
+        (
+            row.dim,
+            receipt_amounts.get(row.dim),
+            row.performance_total,
+            row.payable_total,
+            row.ledger_count,
+        )
+        for row in perf_rows.values()
+    ]
+
+
+def _bucket_condition(bucket: DayBucket) -> tuple:
+    """区间桶的 days 过滤条件：none 桶 IS NULL，其余按 min/max 闭区间。"""
+    if bucket.code == "none":
+        return (PerformanceLedger.payment_days.is_(None),)
+    conds = []
+    if bucket.min_days is not None:
+        conds.append(PerformanceLedger.payment_days >= bucket.min_days)
+    if bucket.max_days is not None:
+        conds.append(PerformanceLedger.payment_days <= bucket.max_days)
+    return tuple(conds)
+
+
+def list_payment_detail(
+    session: Session, query: PaymentDetailQuery, bucket: DayBucket, *, offset: int, limit: int
+) -> list:
+    """区间下钻：单笔生效行联回款表（行级展示回款金额与批次号）。
+
+    bucket 由服务层解析（未注册编码 400），仓储只按区间拼条件。
+    """
+    from app.models import Receipt
+
+    stmt = (
+        select(
+            PerformanceLedger,
+            Receipt.amount.label("receipt_amount"),
+            Receipt.receipt_batch_no.label("receipt_batch_no"),
+        )
+        .outerjoin(Receipt, Receipt.id == PerformanceLedger.receipt_id)
+        .where(*_payment_filters(query), *_bucket_condition(bucket))
+    )
+    stmt = stmt.order_by(PerformanceLedger.receipt_date.desc(), PerformanceLedger.id.desc())
+    stmt = stmt.offset(offset).limit(limit)
+    return list(session.execute(stmt).all())
+
+
+def count_payment_detail(session: Session, query: PaymentDetailQuery, bucket: DayBucket) -> int:
+    """区间下钻计数（与 list_payment_detail 同筛选）。"""
+    return int(
+        session.execute(
+            select(func.count())
+            .select_from(PerformanceLedger)
+            .where(*_payment_filters(query), *_bucket_condition(bucket))
+        ).scalar_one()
+    )

backend/app/repositories/settlement_repository.py

@@ -0,0 +1,121 @@
+"""月度结算仓储：只读写数据并 flush；commit/rollback 在服务层。"""
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models import MonthlySettlement, SettlementItem
+from app.schemas.settlement import SettlementQuery
+
+
+def get_by_id(
+    session: Session, settlement_id: int, *, for_update: bool = False
+) -> MonthlySettlement | None:
+    """月结行；``for_update`` 供提交审批路径加行锁用。
+
+    提交要算审批单版本号（同一月结的第几次送审），并发提交会让两次
+    算出同一个版本号；锁住月结行使并发提交串行化。
+    """
+    if for_update:
+        return session.get(MonthlySettlement, settlement_id, with_for_update=True)
+    return session.get(MonthlySettlement, settlement_id)
+
+
+def get_by_month(session: Session, month: str) -> MonthlySettlement | None:
+    """按月份取月结行（settlement_month 全表唯一）。"""
+    return session.execute(
+        select(MonthlySettlement).where(MonthlySettlement.settlement_month == month)
+    ).scalar_one_or_none()
+
+
+def add(session: Session, settlement: MonthlySettlement) -> MonthlySettlement:
+    session.add(settlement)
+    session.flush()
+    return settlement
+
+
+def list_settlements(session: Session, query: SettlementQuery) -> list[MonthlySettlement]:
+    return list(
+        session.execute(
+            select(MonthlySettlement)
+            .where(*_filters(query))
+            .order_by(MonthlySettlement.settlement_month.desc())
+            .offset(query.offset)
+            .limit(query.page_size)
+        ).scalars()
+    )
+
+
+def count_settlements(session: Session, query: SettlementQuery) -> int:
+    return int(
+        session.execute(
+            select(func.count()).select_from(MonthlySettlement).where(*_filters(query))
+        ).scalar_one()
+    )
+
+
+def _filters(query: SettlementQuery) -> tuple:
+    filters = []
+    if query.status is not None:
+        filters.append(MonthlySettlement.status == query.status)
+    return tuple(filters)
+
+
+def list_items(session: Session, settlement_id: int) -> list[SettlementItem]:
+    return list(
+        session.execute(
+            select(SettlementItem)
+            .where(SettlementItem.settlement_id == settlement_id)
+            .order_by(SettlementItem.id)
+        ).scalars()
+    )
+
+
+def replace_items(session: Session, settlement_id: int, rows: list[SettlementItem]) -> None:
+    """全量替换明细（先删后 flush 再插，防御写法；不 commit）。"""
+    session.execute(delete_items_stmt(settlement_id))
+    session.flush()
+    for row in rows:
+        row.settlement_id = settlement_id
+        session.add(row)
+    session.flush()
+
+
+def delete_items_stmt(settlement_id: int):
+    from sqlalchemy import delete
+
+    return delete(SettlementItem).where(SettlementItem.settlement_id == settlement_id)
+
+
+def update_ledger_settlement_id(
+    session: Session, ledger_ids: list[int], settlement_id: int
+) -> None:
+    """月结生成时把纳入的台账行回填 settlement_id（append-only 的受控回填）。"""
+    from sqlalchemy import update
+
+    from app.models import PerformanceLedger
+
+    if ledger_ids:
+        session.execute(
+            update(PerformanceLedger)
+            .where(PerformanceLedger.id.in_(ledger_ids))
+            .values(settlement_id=settlement_id)
+        )
+        session.flush()
+
+
+def clear_ledger_settlement_id(session: Session, settlement_id: int) -> None:
+    """重生成前解绑：释放本结算名下台账行的 settlement_id（「未入结」判据复位）。
+
+    草稿/驳回态重新生成时，上一轮回填的行必须重新进入候选集——否则
+    ``settlement_id IS NULL`` 会把它们永久排除，重生成漏算整月工资。
+    """
+    from sqlalchemy import update
+
+    from app.models import PerformanceLedger
+
+    session.execute(
+        update(PerformanceLedger)
+        .where(PerformanceLedger.settlement_id == settlement_id)
+        .values(settlement_id=None)
+    )
+    session.flush()

backend/app/repositories/shipment_repository.py

@@ -59,9 +59,7 @@ def list_shipments(
 ) -> list[tuple[Shipment, str]]:
     """分页查询发货单（附业务号），按 id 倒序。"""
     stmt = _apply_filters(
-        select(Shipment, Business.business_no).join(
+        select(Shipment, Business.business_no).join(Business, Business.id == Shipment.business_id),
-            Business, Business.id == Shipment.business_id
-        ),
         business_id=business_id,
         ship_date_from=ship_date_from,
         ship_date_to=ship_date_to,

backend/app/schemas/approval.py

@@ -0,0 +1,79 @@
+"""审批管理的请求/响应模型（2026-10-15 复核审批补充需求）。"""
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from app.core.response import PageQuery
+
+
+class ApprovalStepOut(BaseModel):
+    """节点记录（时间线；action=3 自动通过 operator 记「系统」）。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    node: int
+    action: int
+    opinion: str | None = None
+    operator_id: int | None = None
+    operator_name: str
+    create_time: datetime
+
+
+class ApprovalOrderOut(BaseModel):
+    """审批单列表行。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    order_no: str
+    order_type: int
+    ref_id: int
+    refer_no: str
+    version_no: int
+    status: int
+    submitter_id: int | None = None
+    submitter_name: str
+    create_time: datetime
+
+
+class ApprovalOrderDetailOut(ApprovalOrderOut):
+    """审批单详情：附节点时间线与审批内容。
+
+    ``content_source`` 语义：``snapshot``=提交时快照（可信）；
+    ``live``=历史单无快照、回退读当前业务内容（仅供参考）；
+    ``missing``=引用对象已不存在且无快照。
+    """
+
+    steps: list[ApprovalStepOut] = Field(default_factory=list)
+    snapshot: dict[str, Any] | None = Field(
+        default=None, description="提交时内容快照（信封：schema_version/order_type/captured_at/data）"
+    )
+    content_source: Literal["snapshot", "live", "missing"] = Field(
+        default="missing", description="审批内容来源：提交时快照/当前内容回退/缺失"
+    )
+
+
+class ApprovalQuery(PageQuery):
+    """审批单列表查询条件。"""
+
+    keyword: str | None = Field(default=None, max_length=32, description="审批单号/引用单号，模糊")
+    status: int | None = Field(default=None, ge=1, le=5, description="状态筛选")
+    order_type: int | None = Field(default=None, ge=1, le=3, description="对象类型筛选")
+
+
+class ApprovalActionIn(BaseModel):
+    """节点动作：1 通过 / 2 驳回（驳回须填意见——空驳无从追溯）。"""
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    action: int = Field(ge=1, le=2, description="1通过 2驳回")
+    opinion: str | None = Field(default=None, max_length=255, description="审批意见")
+
+    @model_validator(mode="after")
+    def _check_opinion(self) -> "ApprovalActionIn":
+        if self.action == 2 and not self.opinion:
+            raise ValueError("驳回必须填写审批意见")
+        return self

backend/app/schemas/business.py

@@ -151,10 +151,64 @@ class BusinessOut(BaseModel):
     remark: str | None = None
 
 
+class SecondaryAllocationIn(BaseModel):
+    """二次分配参与人入参（2026-10-15 补充需求「二次分配方案」）。
+
+    比例**不要求合计 100%**（需求原文）：余额归属待业务澄清（待澄清 #2），
+    服务层仅以 hint 展示合计/余额，不做强制校验。ratio 沿金额红线口径：
+    字符串入参、两位小数、超限拒绝不静默舍入。
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    personnel_id: int = Field(ge=1, description="参与业务员ID（personnel.id）")
+    ratio: str = Field(description="分摊比例（0-100，两位小数）")
+
+    @field_validator("ratio")
+    @classmethod
+    def _check_ratio(cls, value: str) -> str:
+        return _check_amount(value, "分摊比例", Decimal("100"), allow_positive_only=True) or value
+
+
+class SecondaryAllocationOut(BaseModel):
+    """二次分配参与人响应（personnel_name 冗余固化，离职后回显有名）。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    personnel_id: int
+    personnel_name: str
+    ratio: str
+
+
+class AllocationVersionOut(SecondaryAllocationOut):
+    """方案版本行（含历史；业务详情抽屉回溯用）。"""
+
+    version_no: int
+    is_active: int = Field(description="1当前生效 0历史版本")
+    create_time: datetime
+
+
+def _ensure_allocations_unique(items: list["SecondaryAllocationIn"]) -> None:
+    """同一业务内参与人去重：uk(business_id, personnel_id) 的前置友好提示
+    （让 400 文案说「重复参与人」而不是裸唯一键冲突）。"""
+    seen: set[int] = set()
+    for item in items:
+        if item.personnel_id in seen:
+            raise ValueError(f"二次分配参与人重复：人员ID {item.personnel_id}")
+        seen.add(item.personnel_id)
+
+
 class BusinessDetailOut(BusinessOut):
-    """业务详情：附产品明细行。"""
+    """业务详情：附产品明细行、当前方案与方案版本历史。"""
 
     items: list[BusinessItemOut] = Field(default_factory=list)
+    secondary_allocations: list[SecondaryAllocationOut] = Field(default_factory=list)
+    allocation_hint: str | None = Field(
+        default=None, description="方案合计与余额提示（余额归属待澄清#2，仅展示）"
+    )
+    allocation_history: list[AllocationVersionOut] = Field(
+        default_factory=list, description="方案全部版本（含历史；被驳回方案亦保留）"
+    )
 
 
 class BusinessCreateIn(BaseModel):
@@ -175,6 +229,9 @@ class BusinessCreateIn(BaseModel):
     is_special: int = Field(default=0, ge=0, le=1, description="特殊业务标记：1是 0否")
     special_note: str | None = Field(default=None, max_length=255, description="特殊业务说明")
     items: list[BusinessItemIn] = Field(min_length=1, description="产品明细行，至少 1 行")
+    secondary_allocations: list[SecondaryAllocationIn] = Field(
+        default_factory=list, description="二次分配方案（只出现在合同刚建立时；可空）"
+    )
     remark: str | None = Field(default=None, max_length=255)
 
     @model_validator(mode="after")
@@ -184,9 +241,14 @@ class BusinessCreateIn(BaseModel):
             raise ValueError("特殊业务必须填写说明")
         return self
 
+    @model_validator(mode="after")
+    def _check_allocations(self) -> "BusinessCreateIn":
+        _ensure_allocations_unique(self.secondary_allocations)
+        return self
+
 
 class BusinessUpdateIn(BaseModel):
-    """编辑业务（全量替换明细；归属不在此端点调整，走 /ownership）。"""
+    """编辑业务（全量替换明细与二次分配方案；归属不在此端点调整，走 /ownership）。"""
 
     model_config = ConfigDict(str_strip_whitespace=True)
 
@@ -207,6 +269,9 @@ class BusinessUpdateIn(BaseModel):
     items: list[BusinessItemIn] = Field(
         min_length=1, description="产品明细行，至少 1 行（全量替换）"
     )
+    secondary_allocations: list[SecondaryAllocationIn] = Field(
+        default_factory=list, description="二次分配方案（全量替换；空数组=清空方案）"
+    )
     remark: str | None = Field(default=None, max_length=255)
 
     @model_validator(mode="after")
@@ -215,6 +280,11 @@ class BusinessUpdateIn(BaseModel):
             raise ValueError("特殊业务必须填写说明")
         return self
 
+    @model_validator(mode="after")
+    def _check_allocations(self) -> "BusinessUpdateIn":
+        _ensure_allocations_unique(self.secondary_allocations)
+        return self
+
 
 class BusinessStatusIn(BaseModel):
     """状态流转：1执行中 → 2已完成 / 3已终止（终态不可再变更）。"""

backend/app/schemas/calc.py

@@ -0,0 +1,62 @@
+"""绩效核算的请求/响应模型（M3 ④）。"""
+
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.core.response import PageQuery
+
+
+class LedgerQuery(PageQuery):
+    """台账列表查询条件。"""
+
+    settlement_month: str | None = Field(default=None, max_length=7, description="归属月 YYYY-MM")
+    personnel_id: int | None = Field(default=None, ge=1, description="归属人员筛选")
+    business_id: int | None = Field(default=None, ge=1, description="业务筛选")
+    is_active: int | None = Field(default=None, ge=0, le=1, description="生效标记筛选")
+    calc_type: int | None = Field(default=None, ge=1, le=2, description="核算类型筛选")
+
+
+class LedgerOut(BaseModel):
+    """台账行响应（金额/比例一律 str）。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    receipt_id: int | None = None
+    calc_version: int
+    is_active: int
+    calc_type: int
+    business_id: int
+    business_no: str
+    personnel_id: int
+    personnel_name: str
+    role_code: str
+    customer_type: str
+    product_category: str
+    ship_date: date | None = None
+    receipt_date: date
+    payment_days: int | None = None
+    rate_text: str
+    converted_profit: Decimal | None = None
+    performance_amount: Decimal | None = None
+    barter_applied: int
+    weight_r: int | None = None
+    payment_weight: Decimal | None = None
+    payable_amount: Decimal | None = None
+    settlement_month: str
+    is_probation: int
+    missing_cost: int
+    snapshot_json: dict | None = None
+    settlement_id: int | None = None
+    calc_reason: str | None = None
+    create_time: datetime
+
+
+class CalcReceiptOut(BaseModel):
+    """单笔核算结果：台账行 + 重复计提标记（核算粒度 #25 一期口径）。"""
+
+    ledger: LedgerOut
+    #: True=该业务此前已核算过，本笔回款仅登记进度、未重复计提（#25 一期口径）
+    repeated: bool = False

backend/app/schemas/dashboard.py

@@ -0,0 +1,126 @@
+"""工作台的请求/响应模型（M4 ⑧）。
+
+四区块一次返回（前端一次请求渲染整页，避免 6-10 次往返）：
+经营绩效总览 / 待办事项 / 风险预警 / 最近动态。金额一律 Decimal
+（序列化为字符串），前端不做数值运算。
+
+待办与预警为**查询时实时派生**（不落库、不引调度器，见计划决策）；
+⑥ T+ 同步未建前，同步相关条目用 `sync_available=false` 显式降级，
+不返回伪造的 0 条。
+"""
+
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, Field
+
+
+class TrendPoint(BaseModel):
+    """近 6 个月趋势点（绩效按台账归属月，回款按到账月）。"""
+
+    month: str
+    performance_total: Decimal | None = None
+    receipt_total: Decimal | None = None
+
+
+class SettlementBrief(BaseModel):
+    """当月月结状态（工作台总览角标）。"""
+
+    exists: bool = False
+    status: int | None = Field(default=None, description="1草稿 2待审批 3已审定 4已驳回")
+    total_performance: Decimal | None = None
+    total_payable: Decimal | None = None
+    locked_at: datetime | None = None
+
+
+class OverviewBlock(BaseModel):
+    """经营绩效总览（FR-033）：口径与台账/月结一致。"""
+
+    month: str
+    performance_total: Decimal | None = Field(default=None, description="当月单笔绩效合计")
+    payable_total: Decimal | None = Field(default=None, description="当月应付绩效合计")
+    person_count: int = Field(default=0, description="当月有台账的人员数（拆行去重）")
+    team_count: int = Field(default=0, description="在职营销经理数（团队数）")
+    settlement: SettlementBrief
+    trend: list[TrendPoint] = Field(default_factory=list, description="近 6 个月")
+    note: str = Field(default="", description="口径说明（页面展示）")
+
+
+class ApprovalTodoItem(BaseModel):
+    """待审批条目。"""
+
+    order_id: int
+    order_no: str
+    order_type: int
+    submitter_name: str | None = None
+    create_time: datetime
+
+
+class ReceiptTodoItem(BaseModel):
+    """回款未指定发货批次条目。"""
+
+    receipt_id: int
+    receipt_batch_no: str
+    business_id: int
+    business_no: str | None = None
+    amount: Decimal
+    receipt_date: date
+
+
+class TodoBlock(BaseModel):
+    """待办事项（FR-034，澄清 #11 起步范围）。"""
+
+    pending_approval_total: int = 0
+    pending_approvals: list[ApprovalTodoItem] = Field(default_factory=list)
+    unassigned_receipt_total: int = 0
+    unassigned_receipts: list[ReceiptTodoItem] = Field(default_factory=list)
+    sync_available: bool = Field(default=False, description="⑥ 同步模块是否已启用")
+    sync_failure_total: int = 0
+
+
+class WarningItem(BaseModel):
+    """风险预警条目（实时派生，不改变业务数据）。"""
+
+    code: str = Field(description="规则编码：receipt_overdue / approval_timeout")
+    level: str = Field(description="级别：warning / danger")
+    object_type: str
+    object_id: int
+    title: str
+    detail: str
+    suggest: str
+    link: str | None = Field(default=None, description="前端跳转路径")
+
+
+class WarningBlock(BaseModel):
+    """风险预警（FR-035，首批两条可算规则；同步规则待 ⑥）。"""
+
+    enabled: bool = True
+    receipt_overdue_days: int = 90
+    approval_timeout_days: int = 3
+    items: list[WarningItem] = Field(default_factory=list)
+    total: int = Field(default=0, description="全部规则命中总数（items 仅为展示上限内的子集）")
+    receipt_overdue_total: int = 0
+    approval_timeout_total: int = 0
+    sync_available: bool = False
+
+
+class ActivityItem(BaseModel):
+    """最近动态条目（来源 operation_logs，只读聚合）。"""
+
+    id: int
+    module: str
+    action: str
+    summary: str
+    username: str | None = None
+    success: int
+    create_time: datetime
+
+
+class DashboardOut(BaseModel):
+    """工作台四区块一次性响应。"""
+
+    month: str
+    overview: OverviewBlock
+    todos: TodoBlock
+    warnings: WarningBlock
+    activities: list[ActivityItem] = Field(default_factory=list)

backend/app/schemas/product.py

@@ -7,29 +7,11 @@ Decimal 转换统一收敛在 service 层。字段命名与 user/role/param 一
 """
 
 from datetime import datetime
-from decimal import Decimal, InvalidOperation
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from app.core.response import PageQuery
-
+from app.schemas.business import AMOUNT_MAX, PRICE_MAX, _check_amount
-
-def _parse_non_negative(value: str, *, label: str) -> str:
-    """非负数字字符串校验：必须可被 Decimal 解析、为有限数且 ≥ 0。
-
-    ``NaN`` 参与比较会抛 InvalidOperation、``Infinity`` 会在后续运算溢出，
-    均须在入口用 ``is_finite()`` 拦下（与 schemas/param.py 的 _parse_amount
-    同一口径）。
-    """
-    try:
-        amount = Decimal(value.strip())
-    except InvalidOperation as exc:
-        raise ValueError(f"{label}必须是有效数字：{value}") from exc
-    if not amount.is_finite():
-        raise ValueError(f"{label}必须为有限数字：{value}")
-    if amount < 0:
-        raise ValueError(f"{label}不得为负数：{value}")
-    return value
 
 
 class ProductOut(BaseModel):
@@ -70,18 +52,27 @@ class ProductCreateIn(BaseModel):
     @field_validator("stock_quantity")
     @classmethod
     def _check_stock_quantity(cls, value: str | None) -> str | None:
-        """空串与 None 同义（可空列），归一为 None；非空则须为非负数字。"""
+        """空串与 None 同义（可空列），归一为 None；非空走通用金额校验。
+
+        复用 _check_amount：容量/小数位与 DECIMAL(14,2) 列口径一致
+        （此前私写的 _parse_non_negative 不查小数位与容量，属同语义
+        字段两处口径漂移）。
+        """
         if not value:
             return None
-        return _parse_non_negative(value, label="数量")
+        return _check_amount(value, "数量", AMOUNT_MAX)
 
     @field_validator("sale_price")
     @classmethod
     def _check_sale_price(cls, value: str | None) -> str | None:
-        """空串与 None 同义（可空列），归一为 None；非空则须为非负数字。"""
+        """空串与 None 同义（可空列），归一为 None；非空走通用金额校验。
+
+        scale=4 与列口径 Numeric(14,4) 一致 —— 带精度的历史单价必须能
+        原样提交（「编辑任何带精度历史行都失败」的 fba8cfc 教训）。
+        """
         if not value:
             return None
-        return _parse_non_negative(value, label="销售单价")
+        return _check_amount(value, "销售单价", PRICE_MAX, scale=4)
 
 
 class ProductUpdateIn(ProductCreateIn):

backend/app/schemas/receipt.py

@@ -30,9 +30,7 @@ class ReceiptCreateIn(BaseModel):
     model_config = ConfigDict(str_strip_whitespace=True)
 
     business_id: int = Field(ge=1, description="业务ID")
-    shipment_id: int | None = Field(
+    shipment_id: int | None = Field(default=None, ge=1, description="发货单ID，可空=暂未指定")
-        default=None, ge=1, description="发货单ID，可空=暂未指定"
-    )
     receipt_date: date = Field(description="回款到账日（M3 按此日匹配参数版本）")
     amount: str = Field(description="回款金额（元），≥0，最多两位小数")
     is_barter: int = Field(default=0, ge=0, le=1, description="以物抵顶标记：1是 0否")

backend/app/schemas/report.py

@@ -0,0 +1,369 @@
+"""报表统计的请求/响应模型（M4 ⑤）。
+
+金额与比例一律 `Decimal`（pydantic v2 序列化为字符串，零精度损失）；
+比例原样输出 `rate_text`（如 88/9000），禁止转 float 或截断展示。
+"""
+
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from app.core.month import validate_month
+from app.core.response import PageQuery
+
+
+def _required_month(value: str) -> str:
+    """必填月份：非法直接抛 ValueError，由 FastAPI 压成 400。"""
+    return validate_month(value)
+
+
+def _optional_month(value: str | None) -> str | None:
+    """可选月份：空串规范为 None（axios 未剔除时也不会误报格式错误）。"""
+    if value in (None, ""):
+        return None
+    return validate_month(value)
+
+
+# ==== 查询入参 ====
+
+
+class PersonalDetailQuery(PageQuery):
+    """个人绩效明细查询条件（FR-029：人员/月份/客户类型/产品类别/岗位）。"""
+
+    settlement_month: str | None = Field(default=None, max_length=7, description="归属月 YYYY-MM")
+    personnel_id: int | None = Field(default=None, ge=1, description="人员筛选")
+    customer_type: str | None = Field(default=None, max_length=32, description="客户类型筛选")
+    product_category: str | None = Field(default=None, max_length=32, description="产品类别筛选")
+    role_code: str | None = Field(default=None, max_length=32, description="岗位筛选")
+
+    @field_validator("settlement_month")
+    @classmethod
+    def _v_settlement_month(cls, value: str | None) -> str | None:
+        return _optional_month(value)
+
+
+class DepartmentSummaryQuery(BaseModel):
+    """部门汇总查询条件（月份必填——部门表按单月聚合，无跨月视角）。"""
+
+    settlement_month: str = Field(min_length=7, max_length=7, description="归属月 YYYY-MM")
+    manager_id: int | None = Field(default=None, ge=1, description="仅看某经理团队")
+
+    @field_validator("settlement_month")
+    @classmethod
+    def _v_settlement_month(cls, value: str) -> str:
+        return _required_month(value)
+
+
+class BusinessStatsQuery(PageQuery):
+    """业务统计查询条件；回款/绩效为该业务累计值，不随业务日期筛选而变。"""
+
+    keyword: str | None = Field(default=None, max_length=64, description="业务编号/客户名称")
+    customer_id: int | None = Field(default=None, ge=1, description="客户筛选")
+    owner_personnel_id: int | None = Field(default=None, ge=1, description="归属人筛选")
+    status: int | None = Field(default=None, description="业务状态筛选")
+    date_from: date | None = Field(default=None, description="业务日期起")
+    date_to: date | None = Field(default=None, description="业务日期止")
+
+
+class PaymentStatsQuery(BaseModel):
+    """回款统计查询条件（按回款天数区间/客户类型/产品类别统计，FR-031）。"""
+
+    settlement_month: str | None = Field(default=None, max_length=7, description="归属月 YYYY-MM")
+    date_from: date | None = Field(default=None, description="回款日期起")
+    date_to: date | None = Field(default=None, description="回款日期止")
+    customer_type: str | None = Field(default=None, max_length=32, description="客户类型筛选")
+    product_category: str | None = Field(default=None, max_length=32, description="产品类别筛选")
+
+    @field_validator("settlement_month")
+    @classmethod
+    def _v_settlement_month(cls, value: str | None) -> str | None:
+        return _optional_month(value)
+
+
+class PaymentDetailQuery(PageQuery):
+    """回款区间下钻（桶编码必填，入参由 payment-stats 页面展开行携带）。"""
+
+    bucket: str = Field(min_length=1, max_length=16, description="区间桶编码")
+    settlement_month: str | None = Field(default=None, max_length=7, description="归属月 YYYY-MM")
+    date_from: date | None = Field(default=None, description="回款日期起")
+    date_to: date | None = Field(default=None, description="回款日期止")
+    customer_type: str | None = Field(default=None, max_length=32, description="客户类型筛选")
+    product_category: str | None = Field(default=None, max_length=32, description="产品类别筛选")
+
+    @field_validator("settlement_month")
+    @classmethod
+    def _v_settlement_month(cls, value: str | None) -> str | None:
+        return _optional_month(value)
+
+
+# ==== 响应出参 ====
+
+
+class ReportSummary(BaseModel):
+    """全筛选口径合计（与「当前页合计」区分，前端页脚需注明）。
+
+    字段按报表取用：个人明细用绩效/应付/折算毛利；业务统计用发货/回款/
+    销售额；不涉及的留 None。
+    """
+
+    row_count: int = Field(default=0, description="筛选结果行数")
+    performance_total: Decimal | None = Field(default=None, description="绩效金额合计")
+    payable_total: Decimal | None = Field(default=None, description="应付绩效合计")
+    converted_profit_total: Decimal | None = Field(default=None, description="折算毛利润合计")
+    ship_total: Decimal | None = Field(default=None, description="发货额合计")
+    received_total: Decimal | None = Field(default=None, description="回款额合计")
+    sale_total: Decimal | None = Field(default=None, description="销售额合计")
+
+
+class ReportPage[T](BaseModel):
+    """报表分页：标准分页四字段 + 全筛选合计。
+
+    序列化字段与 PageResult 一致（list/total/pageNum/pageSize），前端
+    usePagedList 可直接消费；追加的 summary 由各页页脚单独读取。
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    records: list[T] = Field(
+        default_factory=list, alias="list", serialization_alias="list", description="当前页数据"
+    )
+    total: int = Field(default=0, description="总记录数")
+    page_num: int = Field(
+        default=1, alias="pageNum", serialization_alias="pageNum", description="当前页码"
+    )
+    page_size: int = Field(
+        default=10, alias="pageSize", serialization_alias="pageSize", description="每页条数"
+    )
+    summary: ReportSummary = Field(default_factory=ReportSummary, description="全筛选合计")
+
+
+class PersonalDetailRow(BaseModel):
+    """个人绩效明细行（需规 2.4.1 列全覆盖）。
+
+    二次分摊拆行后同一回款按人多行（负责人余额行 + 参与人份额行），行内
+    不放「关联回款金额」列——同回款金额重复展示会让合计无法自洽，金额
+    下沉到快照下钻。
+    """
+
+    ledger_id: int
+    business_id: int
+    business_no: str
+    personnel_id: int
+    personnel_name: str
+    role_code: str
+    role_name: str
+    customer_type: str
+    product_category: str
+    ship_date: date | None = None
+    receipt_date: date
+    payment_days: int | None = None
+    rate_text: str
+    weight_r: int | None = None
+    payment_weight: Decimal | None = None
+    performance_amount: Decimal | None = None
+    payable_amount: Decimal | None = None
+    converted_profit: Decimal | None = None
+    is_probation: int
+    missing_cost: int
+    calc_version: int
+    settlement_id: int | None = None
+
+
+class DepartmentMemberRow(BaseModel):
+    """部门汇总 · 团队成员明细（内联于团队行）。"""
+
+    personnel_id: int
+    personnel_name: str
+    role_code: str
+    is_probation: int
+    member_kind: str = Field(
+        default="regular",
+        description="行来源：regular 普通台账 / manager_personal 经理个人户 / adjustment 仅调整单",
+    )
+    unassigned_reason: str | None = Field(
+        default=None, description="未纳入团队基数的原因（仅未分配块）"
+    )
+    performance_sum: Decimal | None = None
+    payable_sum: Decimal | None = None
+    adjust_extra: Decimal = Field(default=Decimal("0"), description="调整单生效补发合计")
+    adjust_deduct: Decimal = Field(default=Decimal("0"), description="调整单生效扣减合计")
+    adjust_net: Decimal = Field(default=Decimal("0"), description="调整净额（补发为正）")
+    net_total: Decimal | None = None
+    ledger_ids: list[int] = Field(default_factory=list, description="台账行 id 列表（下钻锚点）")
+
+
+class DepartmentTeamRow(BaseModel):
+    """部门汇总 · 经理团队行。"""
+
+    manager_id: int
+    manager_name: str
+    manager_status: int = Field(description="经理在职状态（1 在职 0 离职）")
+    member_count: int
+    team_base: Decimal = Field(description="团队基数（12.5% 的底，等于成员绩效合计）")
+    team_share_amount: Decimal = Field(description="12.5% 团队分成（分列展示）")
+    company_share_amount: Decimal = Field(
+        description="单经理 5% 名义值；该团队无月结聚合行时为 0（不发放）"
+    )
+    has_aggregate: bool = Field(
+        default=False, description="本月是否有月结聚合行（决定是否发放 5%）"
+    )
+    aggregate_amount: Decimal = Field(
+        default=Decimal("0"),
+        description="月结聚合行应发（12.5%+5% 一次舍入）；无聚合行时 0",
+    )
+    team_subtotal: Decimal = Field(
+        default=Decimal("0"),
+        description="团队应发小计 = 聚合行金额 + 调整净额",
+    )
+    company_base_ratio: Decimal = Field(description="团队基数占全公司基数比例（除零为 0）")
+    adjust_extra: Decimal = Decimal("0")
+    adjust_deduct: Decimal = Decimal("0")
+    adjust_net: Decimal = Decimal("0")
+    net_total: Decimal = Field(description="团队净额 = 团队应发小计")
+    frozen_amount: Decimal | None = Field(default=None, description="月结聚合行冻结额（对照）")
+    aggregate_ledger_id: int | None = None
+    members: list[DepartmentMemberRow] = Field(default_factory=list)
+
+
+class DepartmentCompanyBlock(BaseModel):
+    """部门汇总 · 全公司口径块（FR-030「全公司 5% 部分单列」）。"""
+
+    team_base_total: Decimal = Field(description="各团队基数之和（= 全部单笔绩效合计）")
+    company_base: Decimal = Field(description="全公司基数（5% 的底）")
+    company_share_pct: str = Field(description="分成比例参数原文")
+    company_share_amount: Decimal = Field(description="单经理 5% 名义值")
+    company_share_count: int = Field(
+        default=0, description="计入应发的经理数（展示团队中有月结聚合行的数量）"
+    )
+    company_share_total: Decimal = Field(
+        default=Decimal("0"), description="5% 合计 = 单份 × 计入次数"
+    )
+
+
+class DepartmentReconciliation(BaseModel):
+    """部门汇总 · 对账块（导出/打印签字稿的合计口径，前端不自行求和）。
+
+    应发合计 = 团队成员应付 + 未分配应付 + 各经理聚合行金额 + 调整净额。
+    聚合行金额与月结 ``total_payable`` 同口径（12.5%+5% 一次舍入）；
+    ``team_share_total`` 与 ``company_share_total`` 仅作分列展示，两者
+    之和与聚合额的差记入 ``aggregate_rounding_diff``。
+    """
+
+    team_member_payable_total: Decimal = Field(description="展示团队成员的应付绩效合计")
+    unassigned_payable_total: Decimal = Field(description="展示未分配人员的应付绩效合计")
+    team_share_total: Decimal = Field(description="展示团队的 12.5% 分成合计（分列）")
+    company_share_total: Decimal = Field(
+        description="展示团队的全公司分成合计（每位有聚合行的经理各计一次，分列）"
+    )
+    aggregate_payable_total: Decimal = Field(
+        description="展示团队的经理聚合行应发合计（12.5%+5% 一次舍入）"
+    )
+    aggregate_rounding_diff: Decimal = Field(
+        default=Decimal("0"),
+        description="聚合额 − 团队分成合计 − 全公司分成合计（分列舍入差）",
+    )
+    adjust_net_total: Decimal = Field(description="明细层调整净额合计（成员 + 未分配）")
+    payable_total: Decimal = Field(description="应发合计 = 成员应付 + 未分配应付 + 聚合行 + 调整净额")
+    team_base_total: Decimal = Field(description="展示团队基数合计")
+    unassigned_performance_total: Decimal = Field(description="展示未分配人员绩效合计")
+    other_team_base: Decimal = Field(
+        default=Decimal("0"), description="未展示的基数（其他团队 + 全公司未分配）"
+    )
+    other_team_member_payable_total: Decimal = Field(default=Decimal("0"))
+    other_team_share_total: Decimal = Field(default=Decimal("0"))
+    other_team_company_share_total: Decimal = Field(default=Decimal("0"))
+    other_team_aggregate_total: Decimal = Field(default=Decimal("0"))
+    other_adjust_net_total: Decimal = Field(default=Decimal("0"))
+    company_base: Decimal = Field(description="全公司基数（5% 的底）")
+
+
+class DepartmentSummaryOut(BaseModel):
+    """部门绩效工资汇总响应（FR-030）。"""
+
+    settlement_month: str
+    params: dict | None = Field(default=None, description="分成参数原文与取值时点（对账用）")
+    teams: list[DepartmentTeamRow] = Field(default_factory=list)
+    unassigned: list[DepartmentMemberRow] = Field(
+        default_factory=list, description="无经理人员的绩效（不参与分成，仅展示）"
+    )
+    company: DepartmentCompanyBlock | None = None
+    reconciliation: DepartmentReconciliation | None = Field(
+        default=None, description="签字稿对账块（应发公式各项）"
+    )
+    totals: dict = Field(default_factory=dict, description="全表合计（成员/团队对账自证）")
+
+
+class BusinessStatsRow(BaseModel):
+    """业务统计行（发货/回款/绩效为该业务累计值）。"""
+
+    business_id: int
+    business_no: str
+    business_date: date | None = None
+    status: int
+    customer_name: str | None = None
+    owner_personnel_name: str | None = None
+    total_sale_amount: Decimal | None = None
+    total_ship_amount: Decimal | None = None
+    total_received_amount: Decimal | None = None
+    performance_amount: Decimal | None = None
+    payable_amount: Decimal | None = None
+
+
+class BucketRow(BaseModel):
+    """回款统计 · 区间桶行（空桶恒在且为 0，防金额静默消失）。"""
+
+    code: str
+    label: str
+    min_days: int | None = None
+    max_days: int | None = None
+    receipt_amount: Decimal | None = None
+    receipt_count: int = 0
+    performance_amount: Decimal | None = None
+    payable_amount: Decimal | None = None
+    ledger_count: int = 0
+
+
+class GroupRow(BaseModel):
+    """回款统计 · 维度对比行（客户类型 / 产品类别）。"""
+
+    code: str
+    label: str
+    receipt_amount: Decimal | None = None
+    performance_amount: Decimal | None = None
+    payable_amount: Decimal | None = None
+    ledger_count: int = 0
+
+
+class PaymentStatsOut(BaseModel):
+    """回款情况统计响应（FR-031）。
+
+    口径：已计提回款（有台账行）的金额与绩效；进度登记回款无台账行，
+    不在本表（页面需注明）。
+    """
+
+    settlement_month: str | None = None
+    buckets: list[BucketRow] = Field(default_factory=list)
+    by_customer_type: list[GroupRow] = Field(default_factory=list)
+    by_product_category: list[GroupRow] = Field(default_factory=list)
+    totals: dict = Field(default_factory=dict, description="全表合计")
+
+
+class PaymentDetailRow(BaseModel):
+    """回款区间下钻行（行级展示回款金额与批次号）。"""
+
+    ledger_id: int
+    receipt_id: int | None = None
+    receipt_batch_no: str | None = None
+    amount: Decimal | None = Field(default=None, description="回款金额（同回款拆行重复展示）")
+    business_id: int
+    business_no: str
+    personnel_id: int
+    personnel_name: str
+    customer_type: str
+    product_category: str
+    ship_date: date | None = None
+    receipt_date: date
+    payment_days: int | None = None
+    performance_amount: Decimal | None = None
+    payable_amount: Decimal | None = None

backend/app/schemas/setting.py

@@ -0,0 +1,34 @@
+"""系统设置（公司信息）请求/响应模型。
+
+`SettingPublicOut` 与 `SettingOut` **刻意不共用**：public 端点无鉴权，
+响应字段必须白名单显式列出——将来往 SettingOut 加敏感字段时不会
+顺着复用链泄漏到匿名端点。
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SettingOut(BaseModel):
+    """公司信息（管理端）。"""
+
+    company_name: str
+    logo_url: str | None = None
+
+
+class SettingPublicOut(BaseModel):
+    """公司信息（匿名端点白名单）：登录页展示所需的两个字段。"""
+
+    company_name: str
+    logo_url: str | None = None
+
+
+class SettingUpdateIn(BaseModel):
+    """公司信息更新。
+
+    str_strip_whitespace：全空白名称先剥再校验——否则 `"   "` 过 min_length=1
+    后由服务层 strip 成空串入库（200 成功但 public 端点返回空公司名）。
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    company_name: str = Field(min_length=1, max_length=64, description="公司名称")

backend/app/schemas/settlement.py

@@ -0,0 +1,96 @@
+"""月度结算的请求/响应模型（M3 ④）。"""
+
+from datetime import datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from app.core.month import validate_month
+from app.core.response import PageQuery
+
+
+def _check_month(value: str) -> str:
+    """月份格式 YYYY-MM 且月份 01-12（settlement_month 全表唯一的维度）。"""
+    return validate_month(value)
+
+
+class SettlementGenerateIn(BaseModel):
+    """月结生成入参。"""
+
+    month: str = Field(description="结算月份 YYYY-MM")
+
+    @field_validator("month")
+    @classmethod
+    def _v_month(cls, value: str) -> str:
+        return _check_month(value)
+
+
+class SettlementQuery(PageQuery):
+    """月结列表查询。"""
+
+    status: int | None = Field(default=None, ge=1, le=4, description="状态筛选")
+
+
+class SettlementItemOut(BaseModel):
+    """月结明细行。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    personnel_id: int
+    personnel_name: str
+    role_code: str
+    calc_type: int
+    performance_sum: Decimal
+    payable_sum: Decimal
+    basic_amount: Decimal | None = None
+    salary_mode: str | None = None
+    net_amount: Decimal | None = None
+    is_probation: int
+    probation_note: str | None = None
+
+
+class SettlementOut(BaseModel):
+    """月结头表响应。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    settlement_month: str
+    status: int
+    total_performance: Decimal | None = None
+    total_payable: Decimal | None = None
+    person_count: int
+    approval_order_no: str | None = None
+    submitter_name: str
+    locked_at: datetime | datetime | None = None
+    locked_by: str | None = None
+    create_time: datetime
+
+
+class SettlementDetailOut(SettlementOut):
+    """月结详情：附明细。"""
+
+    items: list[SettlementItemOut] = Field(default_factory=list)
+
+
+class AdjustmentCreateIn(BaseModel):
+    """调整单创建入参（金额恒正，方向表达补发/扣减）。"""
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    settlement_month: str = Field(description="调整月份 YYYY-MM")
+    personnel_id: int = Field(ge=1, description="调整人员ID")
+    direction: int = Field(ge=1, le=2, description="1补发 2扣减")
+    # 正则先拦格式（非负两位小数、≤12 位整数防 NUMERIC(14,2) 溢出）；
+    # 「> 0」由服务层判定（schema 只管形状，语义校验留在 service）
+    amount: str = Field(
+        pattern=r"^\d{1,12}(\.\d{1,2})?$",
+        description="金额（元，两位小数，恒正）",
+    )
+    reason: str = Field(min_length=1, max_length=255, description="扣补说明")
+
+    @field_validator("settlement_month")
+    @classmethod
+    def _v_settlement_month(cls, value: str) -> str:
+        return _check_month(value)

backend/app/services/approval_service.py

@@ -0,0 +1,589 @@
+"""审批流业务编排（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 collections.abc import Iterable
+from datetime import date, datetime
+from decimal import Decimal
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session, defer
+
+from app.core.constants import (
+    ACTION_APPROVE,
+    ACTION_REJECT,
+    MODULE_APPROVAL,
+    NO_PREFIX_APPROVAL,
+    ROLE_ADMIN,
+    ROLE_FINANCE,
+    ROLE_LEADER,
+)
+from app.core.exceptions import BadRequestError, ForbiddenError, NotFoundError
+from app.core.response import PageResult
+from app.models import ApprovalOrder, ApprovalStep, Business, 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 种子同源；新增审批对象类型必须在此登记，
+# 否则 is_enabled 走 BadRequestError 兜底、对应业务接口整体不可用）
+ENABLE_CODE_BY_TYPE: dict[int, str] = {
+    1: "approval.secondary_allocation.enabled",
+    2: "approval.monthly_settlement.enabled",
+    3: "approval.adjustment.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 pending_statuses_for_roles(role_codes: Iterable[str]) -> tuple[int, ...]:
+    """工作台「待我审批」：按当前用户角色映射在途审批状态。
+
+    admin 不代办审批，但作为管理视角可查看全部在途单（与审批管理列表
+    的可见性一致）；财务/领导只看到本节点可操作的条目。
+    """
+    codes = set(role_codes)
+    if ROLE_ADMIN in codes:
+        return _PENDING_STATUSES
+    return tuple(status for status, role in _NODE_ROLE_BY_STATUS.items() if role in codes)
+
+
+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,
+    snapshot: dict | None = None,
+) -> ApprovalOrder:
+    """提单（业务写路径内部调用；不 commit、不嵌套 audit）。
+
+    同一引用对象的在途单先撤回留痕再建新单；开关关闭时生成即自动通过
+    （全节点 action=3 留痕）。AP 编号撞唯一键时 IntegrityError 直接穿透：
+    create 路径由外层编号重试循环整体重来（rollback 后业务/方案/审批单
+    一并重做），update 路径由审计上下文回滚并经全局 handler 收敛 400——
+    **任何情况下都不允许本函数内部 rollback 后部分重试**，那会把同事务
+    的业务主行/明细/方案回滚掉而审批单单表重插，静默丢业务数据。
+
+    ``snapshot`` 是「提交时」的业务内容（由调用方组装，Decimal 已转 str）；
+    落库时包一层信封并固化采集时间——审批期间业务再改，复核者看到的仍是
+    送审内容。开关关闭的自动通过路径同样写快照，留痕不走样。
+    """
+    _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,
+        version_no=_next_version(session, order_type, ref_id),
+        snapshot_json=(
+            {
+                "schema_version": 1,
+                "order_type": order_type,
+                "captured_at": datetime.now().isoformat(timespec="seconds"),
+                "data": snapshot,
+            }
+            if snapshot is not None
+            else None
+        ),
+        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 pending_matches_snapshot(
+    session: Session, *, order_type: int, ref_id: int, snapshot: dict | None
+) -> bool:
+    """在途审批单的送审内容是否与给定快照一致（用于「内容未变不重提」）。
+
+    只比较快照信封里的 ``data`` 部分——``captured_at`` 每次采集都不同，
+    参与比较会让判断恒为不一致。V11 之前的历史单没有快照，一律视为不一致
+    （保守重提：宁可多提一次，不能漏审）。
+    """
+    if snapshot is None:
+        return False
+    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:
+        stored = order.snapshot_json or {}
+        if stored.get("data") == snapshot:
+            return True
+    return False
+
+
+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
+            )
+        # 生效类联动只认**终审**：财务节点通过（1→2）只是流转，不得提前
+        # 锁定月结/生效调整单——否则领导驳回后锁定字段残留、审批流形同虚设。
+        # 驳回在任何节点都是终态，即时联动。
+        final_approved = (not rejected) and order.status == 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,
+            )
+        )
+        # 驳回=方案未获批准：把该业务的生效方案行置历史（is_active=0，
+        # **不删行**——V11 起 append-only 版本化），防止被否决的方案以
+        # 「当前生效行」身份被 M3 核算快照算进工资；历史方案仍可在业务
+        # 详情 allocation_history 回溯。委托 business_repository 完成
+        # —— service 层互调、不触 commit。
+        if rejected and order.order_type == 1:
+            from app.repositories import business_repository
+
+            business_repository.deactivate_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)
+                    elif final_approved:
+                        settlement_service.mark_locked(session, target, operator=operator)
+            else:
+                adj = session.get(AdjustmentOrder, order.ref_id)
+                if adj is not None:
+                    if rejected:
+                        adj.status = ADJ_REJECTED
+                    elif final_approved:
+                        adj.status = 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 层依赖判定）。
+
+    排除 snapshot_json 列（月结快照含按人明细，可达数十~上百 KB）：列表出参
+    本就不含快照，整列加载会让翻页负担随快照体积线性放大；详情走
+    `get_order` 按需读取（与操作日志列表排除 request_data 同一理由，
+    见 operation_log_repository.list_logs）。
+    """
+    filters = _order_filters(query)
+    rows = (
+        session.execute(
+            select(ApprovalOrder)
+            .options(defer(ApprovalOrder.snapshot_json))
+            .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 _next_version(session: Session, order_type: int, ref_id: int) -> int:
+    """同一对象类型+引用对象的下一个提交版本号（从 1 递增）。
+
+    **必须用锁读（当前读），不能用普通 MAX 查询**：普通 SELECT 在
+    REPEATABLE READ 下是快照读，读到的是本事务首次一致读的快照；请求级
+    鉴权（deps.get_current_user 与业务共用同一 DbSession）那次 SELECT 已把
+    快照锚定在请求开始时刻，此后即使父行锁等到并发事务提交，MAX 仍停在
+    旧快照上——两个请求会算出同一个 version_no。锁读是当前读，永远读最新
+    已提交数据。
+
+    **不能写成 select(func.max(...)).with_for_update()**：MySQL 官方明确
+    「Locking clauses are not permitted in queries with aggregate functions
+    or GROUP BY」，聚合结果上的 FOR UPDATE 语义无保证。改锁「该 ref 的现有
+    版本行」，最大值在 Python 侧算——同 no_generator 的既有套路。只取
+    version_no 单列，不把 snapshot_json 拉进内存。
+    """
+    versions = (
+        session.execute(
+            select(ApprovalOrder.version_no)
+            .where(
+                ApprovalOrder.order_type == order_type,
+                ApprovalOrder.ref_id == ref_id,
+            )
+            .with_for_update()
+        )
+        .scalars()
+        .all()
+    )
+    return (max(versions) if versions else 0) + 1
+
+
+def allocation_content(session: Session, business: Business) -> dict:
+    """二次分配方案的审批内容（提单快照与历史单回退共用同一结构）。
+
+    业务主行已存在但客户联查落空（客户被删等异常）时返回空字典——调用方
+    以 ``or None`` 归一，避免生成「有快照但内容为空」的信封。
+    """
+    from app.repositories import business_repository
+
+    row = business_repository.get_with_names(session, business.id)
+    if row is None:
+        return {}
+    _, customer_name, owner_name, assistant_name = row
+    allocations = business_repository.list_allocations(session, business.id)
+    total = sum((a.ratio for a in allocations), Decimal("0"))
+    return {
+        "business_no": business.business_no,
+        "business_date": business.business_date.isoformat() if business.business_date else None,
+        "customer_name": customer_name,
+        "owner_personnel_name": owner_name,
+        "assistant_personnel_name": assistant_name,
+        "sale_amount": _amount_text(business.total_sale_amount),
+        "cost_amount": _amount_text(business.total_cost_amount),
+        "allocations": [
+            {
+                "personnel_id": a.personnel_id,
+                "personnel_name": a.personnel_name,
+                "ratio": str(a.ratio),
+            }
+            for a in allocations
+        ],
+        "allocation_total": str(total.quantize(Decimal("0.01"))),
+        "allocation_balance": str((Decimal("100") - total).quantize(Decimal("0.01"))),
+    }
+
+
+def _amount_text(value: Decimal | None) -> str | None:
+    """金额文本化（Decimal 全程不转 float；None 保留为空，不伪造 0.00）。"""
+    return str(value) if value is not None else None
+
+
+def settlement_content(session: Session, settlement_id: int) -> dict | None:
+    """月结审批内容（汇总 + 按人明细；提单快照与历史单回退共用）。"""
+    from app.models import MonthlySettlement
+    from app.repositories import settlement_repository
+
+    settlement = session.get(MonthlySettlement, settlement_id)
+    if settlement is None:
+        return None
+    items = settlement_repository.list_items(session, settlement_id)
+    return {
+        "settlement_month": settlement.settlement_month,
+        "total_performance": _amount_text(settlement.total_performance),
+        "total_payable": _amount_text(settlement.total_payable),
+        "person_count": settlement.person_count,
+        "items": [
+            {
+                "personnel_name": item.personnel_name,
+                "role_code": item.role_code,
+                "calc_type": item.calc_type,
+                "performance_sum": str(item.performance_sum),
+                "payable_sum": str(item.payable_sum),
+                "basic_amount": _amount_text(item.basic_amount),
+                "salary_mode": item.salary_mode,
+                "net_amount": _amount_text(item.net_amount),
+                "is_probation": item.is_probation,
+            }
+            for item in items
+        ],
+    }
+
+
+def adjustment_content(session: Session, adjustment_id: int) -> dict | None:
+    """调整单审批内容（提单快照与历史单回退共用）。"""
+    from app.models import AdjustmentOrder
+
+    adjustment = session.get(AdjustmentOrder, adjustment_id)
+    if adjustment is None:
+        return None
+    return {
+        "order_no": adjustment.order_no,
+        "settlement_month": adjustment.settlement_month,
+        "personnel_name": adjustment.personnel_name,
+        "direction": adjustment.direction,
+        "amount": str(adjustment.amount),
+        "reason": adjustment.reason,
+    }
+
+
+def _content_of(session: Session, order: ApprovalOrder) -> tuple[dict | None, str]:
+    """审批内容出参：优先提交时快照，历史单回退当前内容并显式标注来源。"""
+    if order.snapshot_json:
+        return order.snapshot_json, "snapshot"
+
+    if order.order_type == 1:
+        business = session.get(Business, order.ref_id)
+        data = allocation_content(session, business) if business is not None else None
+    elif order.order_type == 2:
+        data = settlement_content(session, order.ref_id)
+    elif order.order_type == 3:
+        data = adjustment_content(session, order.ref_id)
+    else:
+        data = None
+
+    if not data:
+        return None, "missing"
+    return {
+        "schema_version": 1,
+        "order_type": order.order_type,
+        "captured_at": None,
+        "data": data,
+    }, "live"
+
+
+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]
+    detail.snapshot, detail.content_source = _content_of(session, order)
+    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)

backend/app/services/business_service.py

@@ -16,7 +16,7 @@
 
 import logging
 from datetime import date
-from decimal import Decimal
+from decimal import ROUND_HALF_UP, Decimal
 from fractions import Fraction
 
 from sqlalchemy import Row, func, select
@@ -30,9 +30,11 @@ from app.core.constants import (
     MODULE_BUSINESS,
     NO_PREFIX_BUSINESS,
 )
+from app.core.db_errors import is_duplicate_entry
 from app.core.exceptions import BadRequestError, NotFoundError
 from app.core.response import PageQuery, PageResult
 from app.models import (
+    ApprovalOrder,
     Business,
     BusinessItem,
     BusinessStatusLog,
@@ -40,9 +42,11 @@ from app.models import (
     OwnershipChangeLog,
     Personnel,
     Receipt,
+    SecondaryAllocation,
     Shipment,
     User,
 )
+from app.models.approval import APPROVAL_TYPE_SECONDARY_ALLOCATION
 from app.models.business import (
     BUSINESS_STATUS_ACTIVE,
     BUSINESS_STATUS_DONE,
@@ -50,6 +54,7 @@ from app.models.business import (
 from app.models.customer import OWNER_TYPE_BUSINESS
 from app.repositories import business_repository, customer_repository, personnel_repository
 from app.schemas.business import (
+    AllocationVersionOut,
     BusinessCreateIn,
     BusinessDetailOut,
     BusinessItemIn,
@@ -64,8 +69,10 @@ from app.schemas.business import (
     GrossProfitOut,
     GrossProfitRowOut,
     OwnershipChangeLogOut,
+    SecondaryAllocationIn,
+    SecondaryAllocationOut,
 )
-from app.services import audit_service, param_service
+from app.services import approval_service, audit_service, param_service, personnel_service
 from app.services.audit_service import AuditRecord, RequestMeta
 from app.services.formula import converted_profit, profit_rate
 from app.services.no_generator import next_no
@@ -76,9 +83,6 @@ logger = logging.getLogger(__name__)
 # 重试是为极端场景（锁等待超时后重入）兜底 —— 无限重试反而掩盖死锁类缺陷
 _NO_RETRY = 1
 
-# personnel.status 的在职值（与 customer_service 同口径，注释见彼处）
-_PERSONNEL_STATUS_ACTIVE = 1
-
 
 def _to_out(row: tuple) -> BusinessOut:
     """(business, company_name, owner_name, assistant_name) → 响应模型。
@@ -135,12 +139,19 @@ def _build_item_rows(business_id: int, items: list[BusinessItemIn]) -> list[Busi
 
     不信任前端传值（schema 亦无 sale_amount 入参）——单价可空时销售额记 0，
     由用户在编辑中补价后重算（毛利润视图中销售额 0 的行全部为 0，防除零）。
+    乘积显式 quantize 两位固化：数量(2位)×单价(4位) 可产 6 位小数，直写
+    DECIMAL(14,2) 会被 MySQL 静默舍入且回显漂移（创建响应读内存值、复查
+    读库值前后不一致）；HALF_UP 与 MySQL 的 DECIMAL 舍入方向一致。
     """
     rows: list[BusinessItem] = []
     for item in items:
         quantity = Decimal(item.quantity)
         sale_price = Decimal(item.sale_price) if item.sale_price is not None else None
-        sale_amount = (quantity * sale_price) if sale_price is not None else Decimal("0")
+        sale_amount = (
+            (quantity * sale_price).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+            if sale_price is not None
+            else Decimal("0.00")
+        )
         rows.append(
             BusinessItem(
                 business_id=business_id,
@@ -206,11 +217,8 @@ def _generate_no(session: Session) -> str:
 
 
 def _ensure_personnel_active(session: Session, personnel_id: int, label: str) -> Personnel:
-    """归属人员须存在且在职（人员侧复用校验文案口径）。"""
+    """归属人员须存在且在职（共享校验收口于 personnel_service.ensure_active）。"""
-    person = personnel_repository.get_by_id(session, personnel_id)
+    return personnel_service.ensure_active(session, personnel_id, label=label)
-    if person is None or person.status != _PERSONNEL_STATUS_ACTIVE:
-        raise BadRequestError(f"{label}人员不存在或已离职")
-    return person
 
 
 def _ensure_customer(session: Session, customer_id: int) -> Customer:
@@ -221,8 +229,7 @@ def _ensure_customer(session: Session, customer_id: int) -> Customer:
 
 
 def _is_duplicate_entry(exc: IntegrityError) -> bool:
-    args = getattr(exc.orig, "args", ())
+    return is_duplicate_entry(exc)
-    return bool(args) and args[0] == 1062
 
 
 def list_businesses(session: Session, query: BusinessQuery) -> PageResult[BusinessOut]:
@@ -256,7 +263,7 @@ def list_businesses(session: Session, query: BusinessQuery) -> PageResult[Busine
 
 
 def get_detail(session: Session, business_id: int) -> BusinessDetailOut:
-    """业务详情（附明细行，供编辑抽屉回显）。
+    """业务详情（附明细行与二次分配方案，供编辑抽屉回显）。
 
     :raises NotFoundError: 业务不存在
     """
@@ -267,9 +274,108 @@ def get_detail(session: Session, business_id: int) -> BusinessDetailOut:
     out.items = [
         _item_to_out(item) for item in business_repository.list_items(session, business_id)
     ]
+    allocations = business_repository.list_allocations(session, business_id)
+    out.secondary_allocations = [
+        SecondaryAllocationOut(
+            personnel_id=a.personnel_id, personnel_name=a.personnel_name, ratio=str(a.ratio)
+        )
+        for a in allocations
+    ]
+    out.allocation_hint = _allocation_hint(allocations)
+    out.allocation_history = [
+        AllocationVersionOut(
+            personnel_id=a.personnel_id,
+            personnel_name=a.personnel_name,
+            ratio=str(a.ratio),
+            version_no=a.version_no,
+            is_active=a.is_active,
+            create_time=a.create_time,
+        )
+        for a in business_repository.list_allocation_versions(session, business_id)
+    ]
     return out
 
 
+def _build_allocation_rows(
+    session: Session,
+    business_id: int,
+    items: list[SecondaryAllocationIn],
+    *,
+    old_ids: set[int],
+) -> list[SecondaryAllocation]:
+    """构造二次分配明细行：人员校验 + 姓名冗余固化 + 比例转 Decimal。
+
+    :param old_ids: 编辑前已参与的人员 ID 集合（create 传空集）。这些人的
+        行是**历史事实**——personnel_name 冗余固化的设计本就允许离职后回显，
+        编辑业务（哪怕只改备注）不应被历史参与人的离职状态卡死；仅对
+        **新加入**的参与人做在职校验。
+
+    :raises BadRequestError: 新增参与人员不存在或已离职 / 比例合计超 100%
+        / 参与人含合同负责人（口径见澄清 #1/#2 答复 2026-10-19：分配绩效、
+        余额归合同负责营销人员——超 100% 会把负责人份额算成负数，负责人
+        自分份额则双重计入）
+    """
+    business = business_repository.get_by_id(session, business_id)
+    if business is None:
+        raise NotFoundError("业务不存在")
+    total = sum((Decimal(item.ratio) for item in items), Decimal("0"))
+    if total > Decimal("100"):
+        raise BadRequestError(
+            f"二次分配比例合计 {total.quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)}%"
+            " 超过 100%（余额归合同负责营销人员，比例不可超满额）"
+        )
+    owner_id = business.owner_personnel_id
+    if owner_id is not None and any(item.personnel_id == owner_id for item in items):
+        raise BadRequestError("分摊参与人不可包含合同负责营销人员（负责人得余额份额）")
+
+    rows: list[SecondaryAllocation] = []
+    for item in items:
+        if item.personnel_id in old_ids:
+            person = personnel_repository.get_by_id(session, item.personnel_id)
+            if person is None:
+                raise BadRequestError("分摊参与人员不存在")
+        else:
+            person = _ensure_personnel_active(session, item.personnel_id, "分摊参与")
+        rows.append(
+            SecondaryAllocation(
+                business_id=business_id,
+                personnel_id=item.personnel_id,
+                personnel_name=person.personnel_name,
+                ratio=Decimal(item.ratio),
+            )
+        )
+    return rows
+
+
+def _plan_changed(old_rows: list[SecondaryAllocation], new_rows: list[SecondaryAllocation]) -> bool:
+    """方案内容（参与人 + 比例）是否真的变了。
+
+    比较口径是**集合**（人员 ID 与其比例的组合），与提交顺序无关——送审
+    快照同样按库内生效行的顺序生成，若按顺序比较，用户只是把行拖了个
+    序就会被判成「变了」，进而无谓地新增版本与重提审批单。
+    """
+
+    def _key(row: SecondaryAllocation) -> tuple[int, Decimal]:
+        return (row.personnel_id, Decimal(row.ratio).quantize(Decimal("0.01")))
+
+    return {_key(r) for r in old_rows} != {_key(r) for r in new_rows}
+
+
+def _allocation_hint(allocations: list[SecondaryAllocation]) -> str | None:
+    """方案合计/余额提示（不要求合计满额是需求原文；余额归属 = 澄清 #2 答复）。
+
+    无方案返回 None；合计恰满额只报合计，避免「余额 0」噪音。
+    """
+    if not allocations:
+        return None
+    total = sum((a.ratio for a in allocations), Decimal("0"))
+    total_text = total.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+    if total == Decimal("100"):
+        return f"二次分配合计 {total_text}%"
+    rest = (Decimal("100") - total).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+    return f"二次分配合计 {total_text}%，余额 {rest}%（归合同负责营销人员）"
+
+
 def create_business(
     session: Session,
     payload: BusinessCreateIn,
@@ -301,6 +407,12 @@ def create_business(
         if payload.assistant_personnel_id is not None:
             _ensure_personnel_active(session, payload.assistant_personnel_id, "协助")
 
+        # 编号唯一键冲突的重试整体收在审计上下文内：rollback 后同一事务重来，
+        # 成功/最终失败各只记一条审计（吞异常 return 会被记成假成功，重入
+        # 整个 create_* 则违反「不支持嵌套」约定）；上限 _NO_RETRY 防无限重试
+        # 掩盖死锁类缺陷。审计摘要预取的是首次编号——重试成功时入库编号见
+        # 应用日志（AuditRecord frozen，不回填）。
+        for attempt in range(_NO_RETRY + 1):
             try:
                 business = Business(
                     business_no=_generate_no(session),
@@ -328,31 +440,42 @@ def create_business(
                         operator_name=operator.username,
                     ),
                 )
+                # 二次分配方案与业务同事务（需求：只出现在合同刚建立时）；
+                # 放在重试循环内——rollback 后方案行随业务一并重来
+                business_repository.replace_allocations(
+                    session,
+                    business.id,
+                    _build_allocation_rows(
+                        session, business.id, payload.secondary_allocations, old_ids=set()
+                    ),
+                )
+                # 方案非空才提单：开关关闭=自动通过留痕，开启=待财务复核。
+                # AP 编号撞键时 IntegrityError 穿透 → 外层编号重试循环把
+                # 业务/方案/审批单整体重来
+                if payload.secondary_allocations:
+                    approval_service.submit_order(
+                        session,
+                        order_type=APPROVAL_TYPE_SECONDARY_ALLOCATION,
+                        ref_id=business.id,
+                        refer_no=business.business_no,
+                        submitter=operator,
+                        snapshot=approval_service.allocation_content(session, business) or None,
+                    )
                 customer = customer_repository.get_by_id(session, business.customer_id)
                 out = _to_out((business, customer.company_name if customer else None, None, None))
+                new_id, new_no = business.id, business.business_no  # 固化：commit 后不碰 ORM
                 session.commit()
+                break
             except IntegrityError as exc:
                 session.rollback()
-            if _is_duplicate_entry(exc):
+                if _is_duplicate_entry(exc) and attempt < _NO_RETRY:
-                # 编号生成的残余竞态：唯一键兜底重试一次（防无限重试掩盖死锁）
+                    continue
-                return _retry_create(session, payload, operator=operator, meta=meta)
                 raise
 
-        logger.info("创建业务 | business_id=%s | no=%s", business.id, business.business_no)
+        logger.info("创建业务 | business_id=%s | no=%s", new_id, new_no)
         return out
 
 
-def _retry_create(
-    session: Session,
-    payload: BusinessCreateIn,
-    *,
-    operator: User,
-    meta: RequestMeta | None,
-) -> BusinessOut:
-    """编号撞唯一键后的单次重试（防无限重试掩盖死锁类缺陷）。"""
-    return create_business(session, payload, operator=operator, meta=meta)
-
-
 def update_business(
     session: Session,
     business_id: int,
@@ -367,9 +490,9 @@ def update_business(
     发货/回款语义断裂（明细同理随业务走）。
 
     :raises NotFoundError: 业务不存在
-    :raises BadRequestError: 归属人员不合法 / 有发货或回款时换客户
+    :raises BadRequestError: 业务已完成或已终止 / 归属人员不合法 / 有发货或回款时换客户
     """
-    row = business_repository.get_with_names(session, business_id)
+    row = business_repository.get_with_names(session, business_id, for_update=True)
     business = row[0] if row else None
     with audit_service.audit(
         session,
@@ -384,18 +507,18 @@ def update_business(
     ):
         if row is None:
             raise NotFoundError("业务不存在")
-        business, _, _, _ = row
+        business, _, owner_name, assistant_name = row
 
-        if payload.customer_id != business.customer_id:
+        # 终态门槛与发货/回款写准入同口径：明细与汇总是 M3 核算基线，
-            has_docs = session.query(Shipment.id).filter(
+        # 已完成/已终止的业务禁改（发货/回款服务以同一理由禁写终态业务）
-                Shipment.business_id == business_id
+        if business.status != BUSINESS_STATUS_ACTIVE:
-            ).first() is not None or (
+            raise BadRequestError("业务已完成或已终止，禁止编辑业务")
-                session.query(Receipt.id).filter(Receipt.business_id == business_id).first()
+
-                is not None
+        if payload.customer_id != business.customer_id and business_repository.has_docs(
-            )
+            session, business_id
-            if has_docs:
+        ):
             raise BadRequestError("业务已有发货或回款记录，不能更换客户")
-        _ensure_customer(session, payload.customer_id)
+        customer = _ensure_customer(session, payload.customer_id)
         if payload.owner_personnel_id is not None:
             _ensure_personnel_active(session, payload.owner_personnel_id, "负责")
         if payload.assistant_personnel_id is not None:
@@ -411,8 +534,61 @@ def update_business(
         business_repository.replace_items(
             session, business_id, _build_item_rows(business_id, payload.items)
         )
+        # 方案：内容真的变了才动版本行（内容未变不新增版本，避免「只改备注」
+        # 也堆出一个方案版本）；空数组=清空=把生效行置历史
+        old_allocations = business_repository.list_allocations(session, business_id)
+        new_rows = _build_allocation_rows(
+            session,
+            business_id,
+            payload.secondary_allocations,
+            old_ids={a.personnel_id for a in old_allocations},
+        )
+        if not payload.secondary_allocations:
+            business_repository.replace_allocations(session, business_id, [])
+        elif _plan_changed(old_allocations, new_rows):
+            business_repository.replace_allocations(session, business_id, new_rows)
+        # 汇总先重算：送审快照里的销售额/成本额必须反映本次编辑后的值，
+        # 放到提单之后会固化成上一版本的金额
         _recalc_totals(session, business)
-        out = _to_out(business_repository.get_with_names(session, business_id))
+        # 提单/撤单与方案同步生命周期：
+        # - 方案为空 → 仅撤回在途单（旧在途单挂着已不存在的方案继续走审批）
+        # - 送审内容与在途单一致 → 保留原单，不撤回不重建（避免反复保存
+        #   刷出「撤回+新建」的审批留痕噪音）
+        # - 其余 → 提新单（内含撤旧建新）
+        if payload.secondary_allocations:
+            snapshot = approval_service.allocation_content(session, business) or None
+            if not approval_service.pending_matches_snapshot(
+                session,
+                order_type=APPROVAL_TYPE_SECONDARY_ALLOCATION,
+                ref_id=business_id,
+                snapshot=snapshot,
+            ):
+                try:
+                    approval_service.submit_order(
+                        session,
+                        order_type=APPROVAL_TYPE_SECONDARY_ALLOCATION,
+                        ref_id=business_id,
+                        refer_no=business.business_no,
+                        submitter=operator,
+                        snapshot=snapshot,
+                    )
+                except IntegrityError as exc:
+                    # version_no 唯一键的并发冲突（取号是锁读后此项理论不可达，
+                    # 留作 DB 兜底）：审计上下文会统一回滚，这里只把 1062
+                    # 翻译成可重试的业务提示，其余完整性错误原样上抛
+                    if _is_duplicate_entry(exc):
+                        raise BadRequestError("提交冲突（版本号生成重复），请重试") from exc
+                    raise
+        else:
+            approval_service.withdraw_pending_orders(
+                session,
+                order_type=APPROVAL_TYPE_SECONDARY_ALLOCATION,
+                ref_id=business_id,
+                operator=operator,
+            )
+        # 锁定行上已赋值，同一身份映射实例的 _to_out 即反映新值；名称字段
+        # 从首查 row 取（换客户时 _ensure_customer 已给出新公司名）
+        out = _to_out((business, customer.company_name, owner_name, assistant_name))
         session.commit()
         logger.info("修改业务 | business_id=%s", business_id)
         return out
@@ -431,7 +607,7 @@ def delete_business(
     与业务维度的归属留痕（无外键固化表，须手动清）。
 
     :raises NotFoundError: 业务不存在
-    :raises BadRequestError: 存在发货或回款记录
+    :raises BadRequestError: 存在发货或回款记录 / 存在在途审批单
     """
     business = business_repository.get_by_id(session, business_id, for_update=True)
     with audit_service.audit(
@@ -446,13 +622,12 @@ def delete_business(
     ):
         if business is None:
             raise NotFoundError("业务不存在")
-        if (
+        if business_repository.has_docs(session, business_id):
-            session.query(Shipment.id).filter(Shipment.business_id == business_id).first()
-            is not None
-            or session.query(Receipt.id).filter(Receipt.business_id == business_id).first()
-            is not None
-        ):
             raise BadRequestError("业务已有发货或回款记录，请改为已终止而非删除")
+        # 在途审批单（ref_id 固化无外键，业务删了单还挂着且可被继续审批）：
+        # 禁删引导先完成/撤回审批，而不是静默留下指向已删业务的活单
+        if _count_pending_approvals(session, business_id):
+            raise BadRequestError("该业务有在途审批单，请先完成或撤回审批后再删除")
 
         business_no = business.business_no
         _hard_delete(session, business_id)
@@ -460,11 +635,46 @@ def delete_business(
         logger.info("删除业务 | business_id=%s | no=%s", business_id, business_no)
 
 
+def _count_pending_approvals(session: Session, business_id: int) -> int:
+    """该业务的在途审批单数（status 1/2；终态单随业务删除一并清理）。"""
+    from sqlalchemy import func, select
+
+    from app.models import ApprovalOrder
+    from app.models.approval import (
+        APPROVAL_STATUS_PENDING_FINANCE,
+        APPROVAL_STATUS_PENDING_LEADER,
+    )
+
+    return int(
+        session.execute(
+            select(func.count())
+            .select_from(ApprovalOrder)
+            .where(
+                ApprovalOrder.order_type == APPROVAL_TYPE_SECONDARY_ALLOCATION,
+                ApprovalOrder.ref_id == business_id,
+                ApprovalOrder.status.in_(
+                    (APPROVAL_STATUS_PENDING_FINANCE, APPROVAL_STATUS_PENDING_LEADER)
+                ),
+            )
+        ).scalar_one()
+    )
+
+
 def _hard_delete(session: Session, business_id: int) -> None:
-    """按依赖序删除：明细 → 状态留痕 → 业务维度归属留痕 → 主表。"""
+    """按依赖序删除：明细 → 二次分配方案 → 审批单（steps 随 CASCADE）→
+    状态留痕 → 业务维度归属留痕 → 主表。"""
     from sqlalchemy import delete
 
     session.execute(delete(BusinessItem).where(BusinessItem.business_id == business_id))
+    session.execute(
+        delete(SecondaryAllocation).where(SecondaryAllocation.business_id == business_id)
+    )
+    session.execute(
+        delete(ApprovalOrder).where(
+            ApprovalOrder.order_type == APPROVAL_TYPE_SECONDARY_ALLOCATION,
+            ApprovalOrder.ref_id == business_id,
+        )
+    )
     session.execute(delete(BusinessStatusLog).where(BusinessStatusLog.business_id == business_id))
     session.execute(
         delete(OwnershipChangeLog).where(
@@ -488,7 +698,7 @@ def change_status(
     :raises NotFoundError: 业务不存在
     :raises BadRequestError: 非执行中状态流转 / 目标与当前相同
     """
-    row = business_repository.get_with_names(session, business_id)
+    row = business_repository.get_with_names(session, business_id, for_update=True)
     with audit_service.audit(
         session,
         operator=operator,
@@ -526,7 +736,8 @@ def change_status(
                 operator_name=operator.username,
             ),
         )
-        out = _to_out(business_repository.get_with_names(session, business_id))
+        # 锁定行上已赋值，同一身份映射实例的 _to_out 即反映新状态
+        out = _to_out(row)
         session.commit()
         logger.info(
             "业务状态变更 | business_id=%s | %s -> %s",
@@ -553,7 +764,7 @@ def change_ownership(
     :raises NotFoundError: 业务不存在
     :raises BadRequestError: 归属人员不存在或已离职 / 归属未变化
     """
-    row = business_repository.get_with_names(session, business_id)
+    row = business_repository.get_with_names(session, business_id, for_update=True)
     with audit_service.audit(
         session,
         operator=operator,
@@ -567,11 +778,19 @@ def change_ownership(
     ):
         if row is None:
             raise NotFoundError("业务不存在")
-        business, _, _, _ = row
+        business, _, old_owner_name, old_assistant_name = row
-        if payload.new_owner_personnel_id is not None:
+        # 归属变更的出参姓名来自校验函数的返回行（锁定读）：首查姓名是变更前
+        # 固化标量，新归属人名必须按新 ID 重取
+        new_owner = (
             _ensure_personnel_active(session, payload.new_owner_personnel_id, "负责")
-        if payload.new_assistant_personnel_id is not None:
+            if payload.new_owner_personnel_id is not None
+            else None
+        )
+        new_assistant = (
             _ensure_personnel_active(session, payload.new_assistant_personnel_id, "协助")
+            if payload.new_assistant_personnel_id is not None
+            else None
+        )
 
         owner_changed = business.owner_personnel_id != payload.new_owner_personnel_id
         assistant_changed = business.assistant_personnel_id != payload.new_assistant_personnel_id
@@ -596,7 +815,16 @@ def change_ownership(
                 operator_name=operator.username,
             ),
         )
-        out = _to_out(business_repository.get_with_names(session, business_id))
+        # 出参组装：ID 在锁定行上已赋值（_to_out 读内存值即反映新值），姓名
+        # 一侧「变更项用新 ID 的人名、未变项沿用首查名」——首查名是变更前快照
+        out = _to_out(
+            (
+                business,
+                row[1],
+                new_owner.personnel_name if new_owner is not None else old_owner_name,
+                new_assistant.personnel_name if new_assistant is not None else old_assistant_name,
+            )
+        )
         session.commit()
         logger.info(
             "调整业务归属 | business_id=%s | owner %s->%s | assistant %s->%s",

backend/app/services/calc_service.py

@@ -0,0 +1,719 @@
+"""绩效核算服务（M3 ④）：回款 → 台账的固化流水线。
+
+单笔核算（calc_receipt）与计算预览（param_service.preview）**共用同一
+公式路径与取值防线**：resolve_snapshot 按回款到账日取参（裁决 #11）、按
+岗位模板分派计提比例（‰ 存储口径 ÷1000 转纯比例）、行级折算（混合业务
+按行汇总，对照表 #14）。两者的任何口径修改必须同步——预览给业务对数、
+核算才是算钱的法定固化点。
+
+策略点（业务答复 2026-10-19 已回填，后续调整仍集中在对应函数 + 按回款批量重算）：
+- ``_personal_rate``：#12 经理个人户单笔由参数 manager.personal.included
+  分流——0=单笔落 0（聚合口径在月结时由 manager_team_share 计算）、
+  1=按业务员递减公式计提；#20 在 ``_row_profit``（暂按不含税原样相减）
+- 二次分摊（澄清 #1 答复「分配绩效」，算后分）：``_load_allocations``
+  读生效方案，``_persist_ledger`` 按比例拆行（参与人份额 + 负责人余额，
+  行合计守恒）；#2 余额归负责人、#3 二次分配即协助场景的核算载体
+- 核算粒度 #25：业务级一次性计提——首个触发核算的回款计算全额应发，
+  后续回款仅置 settlement_status=1（repeated=True），不重复计提
+"""
+
+import logging
+from dataclasses import dataclass
+from decimal import ROUND_HALF_UP, Decimal
+from fractions import Fraction
+from typing import Any
+
+from sqlalchemy import update
+from sqlalchemy.orm import Session
+
+from app.core.constants import MODULE_CALC
+from app.core.exceptions import BadRequestError
+from app.models import (
+    Business,
+    BusinessItem,
+    Customer,
+    PerformanceLedger,
+    Personnel,
+    Receipt,
+    Shipment,
+    User,
+)
+from app.models.performance_ledger import CALC_TYPE_RECEIPT
+from app.models.receipt import SETTLEMENT_DONE, SETTLEMENT_PENDING
+from app.repositories import business_repository, performance_ledger_repository
+from app.schemas.calc import CalcReceiptOut
+from app.services import audit_service, param_service, personnel_service
+from app.services.audit_service import AuditRecord, RequestMeta
+from app.services.formula import (
+    apply_barter,
+    clamp_weight_r,
+    converted_profit,
+    payment_days,
+    payment_weight,
+    performance_amount,
+    profit_rate,
+    salesperson_rate,
+    start_payment_ok,
+)
+from app.services.param_service import parse_fraction, resolve_snapshot
+
+logger = logging.getLogger(__name__)
+
+# snapshot_json 里的策略点注记（口径检索锚点；#12 已参数化，开关 0 时留此注记）
+_NOTE_MANAGER_PENDING = "经理个人户单笔不计提（基数开关=0）：聚合口径在月结时由团队聚合计算"
+
+
+@dataclass(frozen=True, slots=True)
+class _RateDecision:
+    """单笔计提比例的分派结果。"""
+
+    rate: Fraction  # 纯比例（str() 产出分数原文如 88/9000，直接落台账 rate_text）
+    rate_note: str  # 人读说明（入 snapshot）
+    base_override: Decimal | None  # 非 None 时绩效基数用它（信息员=销售额）
+    manager_pending: bool  # True=经理聚合口径，单笔落 0（#12 策略点）
+
+
+def calc_receipt(
+    session: Session,
+    receipt_id: int,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+    recalc_reason: str | None = None,
+) -> CalcReceiptOut:
+    """单笔回款核算 / 重算（recalc_reason 非 None 时为重算模式）。
+
+    防重前两层在 ``_load_and_guard``（FOR UPDATE 锁行 + settlement_status
+    与月结锁定校验），第三层是落台账 uk(receipt_id, calc_version)。全程
+    一个 audit 事务，出参在 commit 前固化。
+
+    首算模式：回款必须未核算；业务级一次性计提（#25）——已有生效台账行时
+    仅登记进度（repeated=True，``_prepare_mode`` 内提前返回）。
+    重算模式：回款必须已核算过；作废旧版本行（is_active=0），按当前参数
+    落 calc_version+1 新行，calc_reason 留痕。
+
+    本函数只做编排：锁行校验 → 模式预处理 → 输入装载 → 逐行折算 →
+    计提组成 → 落库，各段独立私有函数（口径修改只动对应段）。
+    """
+    is_recalc = recalc_reason is not None
+    action = "重算" if is_recalc else "核算"
+    with audit_service.audit(
+        session,
+        operator=operator,
+        record=AuditRecord(
+            module=MODULE_CALC,
+            action=action,
+            summary=f"{action}回款 #{receipt_id}",
+            request_data={
+                "receipt_id": receipt_id,
+                **({"reason": recalc_reason} if is_recalc else {}),
+            },
+        ),
+        meta=meta,
+    ):
+        receipt, business = _load_and_guard(session, receipt_id, is_recalc=is_recalc)
+        repeated_out = _prepare_mode(session, receipt, business, is_recalc=is_recalc)
+        if repeated_out is not None:
+            return repeated_out
+
+        shipment = _load_shipment(session, receipt)
+        person = _load_person(session, business)
+        snapshot = resolve_snapshot(session, receipt.receipt_date)
+        items = _load_items(session, business)
+        allocations = _load_allocations(session, business, person.id)
+
+        conversion = _convert_items(snapshot, person, items)
+        amounts = _compose_amounts(
+            session, snapshot, person, business, receipt, shipment, conversion
+        )
+        rows = _persist_ledger(
+            session,
+            receipt=receipt,
+            business=business,
+            person=person,
+            shipment=shipment,
+            items=items,
+            allocations=allocations,
+            conversion=conversion,
+            amounts=amounts,
+            recalc_reason=recalc_reason,
+            is_recalc=is_recalc,
+        )
+        session.flush()
+        out = CalcReceiptOut(ledger=_to_out(rows.owner_row), repeated=False)
+        session.commit()
+        logger.info(
+            "核算完成 | receipt=%s | ledger=%s | payable=%s | 分摊行=%s",
+            receipt_id,
+            rows.owner_row.id,
+            amounts.payable,
+            len(rows.share_rows),
+        )
+        return out
+
+
+def _load_and_guard(
+    session: Session, receipt_id: int, *, is_recalc: bool
+) -> tuple[Receipt, Business]:
+    """锁行 + 模式校验 + 月结锁定拦截 + 业务归属校验（核算/重算共用）。"""
+    receipt = session.get(Receipt, receipt_id, with_for_update=True)
+    if receipt is None:
+        raise BadRequestError("回款不存在")
+    if is_recalc:
+        if receipt.settlement_status == SETTLEMENT_PENDING:
+            raise BadRequestError("该回款尚未核算过（无旧版本可重算，走首次核算）")
+    elif receipt.settlement_status == SETTLEMENT_DONE:
+        raise BadRequestError("该回款已核算，禁止重复核算（重算请走重算入口）")
+
+    # 月结锁定拦截：已审定月份的回款不得再核算/重算——金额已固化，
+    # 变动唯一通道是调整单（否则重算会绕开审批改写已锁定月份的应付）
+    from app.services import settlement_service
+
+    settlement_service.ensure_month_not_locked(session, receipt.receipt_date.strftime("%Y-%m"))
+
+    business = session.get(Business, receipt.business_id, with_for_update=True)
+    if business is None:
+        raise BadRequestError("回款关联的业务不存在")
+    if business.owner_personnel_id is None:
+        raise BadRequestError("业务未指定负责营销人员，无法核算（先在业务归属中指定）")
+    return receipt, business
+
+
+def _prepare_mode(
+    session: Session, receipt: Receipt, business: Business, *, is_recalc: bool
+) -> CalcReceiptOut | None:
+    """模式预处理：重算作废旧版本；首算判业务级一次性计提。
+
+    返回非 None = 本笔仅登记进度（repeated=True 的出参，已 commit），
+    调用方直接返回。
+    """
+    # 重算：先作废旧版本行（is_active=0），折算体随后按当前参数重算。
+    # 无生效行 = 该回款是「进度登记」（业务级一次性计提 #25 的第二笔及
+    # 以后）——本无独立计提，继续重算会凭空落一行生效行，同业务出现
+    # 两行生效行导致双重计提 → 一律 400
+    if is_recalc:
+        # 分摊拆行后旧版本可能多行（负责人+参与人）——全部作废再落新版本
+        olds = performance_ledger_repository.list_active_by_receipt(session, receipt.id)
+        if not olds:
+            raise BadRequestError("该回款为进度登记（业务已按一次性计提核算），无独立台账行可重算")
+        for old in olds:
+            performance_ledger_repository.mark_inactive(session, old)
+        return None
+
+    # 核算粒度 #25（一期口径，仅首算模式）：业务级一次性计提——已有生效
+    # 台账行时，本笔回款仅置已核算状态（支付进度），不重复计提
+    if not performance_ledger_repository.has_active_for_business(
+        session, business.id, calc_type=CALC_TYPE_RECEIPT
+    ):
+        return None
+    _mark_settled(session, receipt)
+    row = performance_ledger_repository.get_active_by_receipt_of_business(session, business.id)
+    session.flush()
+    out = CalcReceiptOut(ledger=_to_out(row), repeated=True)
+    session.commit()
+    logger.info("回款登记进度（业务已核算）| receipt=%s | business=%s", receipt.id, business.id)
+    return out
+
+
+def _load_shipment(session: Session, receipt: Receipt) -> Shipment:
+    """核销基准：发货批次存在且带发货日（回款天数公式的输入）。"""
+    if receipt.shipment_id is None:
+        raise BadRequestError("回款未指定发货批次，无法确定发货日期（先指定批次再核算）")
+    shipment = session.get(Shipment, receipt.shipment_id)
+    if shipment is None or shipment.ship_date is None:
+        raise BadRequestError("发货批次缺少发货日期，无法核算")
+    return shipment
+
+
+def _load_person(session: Session, business: Business):
+    """核算归属：在职 + 绑定岗位角色（计提公式锚点）。"""
+    person = personnel_service.ensure_active(session, business.owner_personnel_id, label="核算归属")
+    if person.business_role_id is None:
+        raise BadRequestError("归属人员未绑定岗位角色，无法确定计提公式")
+    return person
+
+
+def _load_items(session: Session, business: Business) -> list[BusinessItem]:
+    """业务产品明细行（逐行折算的输入；空明细无法核算）。"""
+    items = business_repository.list_items(session, business.id)
+    if not items:
+        raise BadRequestError("业务无产品明细行，无法核算")
+    return items
+
+
+def _load_allocations(session: Session, business: Business, owner_id: int) -> list:
+    """业务生效的二次分配方案（澄清 #1 答复 2026-10-19：分配绩效——算后分）。
+
+    校验双保险之一（保存侧在 business_service）：比例合计 >100% 会把负责人
+    份额算成负数（多算参与人绩效）；合同负责人不可出现在参与人列表（自分
+    份额会双重计入）。无方案返回空列表 = 全额归负责人。
+    """
+    allocations = business_repository.list_allocations(session, business.id)
+    if not allocations:
+        return []
+    total = sum((a.ratio for a in allocations), Decimal("0"))
+    if total > Decimal("100"):
+        raise BadRequestError(
+            f"二次分配比例合计 {total.quantize(Decimal('0.01'))}% 超过 100%，"
+            "无法核算（先调整方案比例）"
+        )
+    if any(a.personnel_id == owner_id for a in allocations):
+        raise BadRequestError("二次分配参与人含合同负责营销人员，无法核算（先调整方案）")
+    return list(allocations)
+
+
+@dataclass(frozen=True, slots=True)
+class _Conversion:
+    """逐行折算结果（行级明细入台账快照，汇总值驱动计提与起付判定）。"""
+
+    total_revenue: Decimal
+    total_profit: Decimal
+    converted_total: Decimal
+    missing_cost: bool
+    line_details: list[dict[str, Any]]
+
+
+def _convert_items(snapshot, person, items: list[BusinessItem]) -> _Conversion:
+    """逐行折算（行级 product_category 阈值；成本缺失行毛利按 0 计并标记）。"""
+    total_revenue = Decimal("0")
+    total_profit = Decimal("0")
+    converted_total = Decimal("0")
+    missing_cost = False
+    line_details: list[dict[str, Any]] = []
+    for item in items:
+        row_revenue = item.sale_amount
+        if item.cost_amount is None:
+            missing_cost = True
+            row_profit = Decimal("0")
+        else:
+            row_profit = _row_profit(row_revenue, item.cost_amount)
+        total_revenue += row_revenue
+        total_profit += row_profit
+        threshold = parse_fraction(
+            snapshot.get(
+                "product.threshold",
+                role_code=role_code_of(person),
+                product_category=item.product_category,
+            )
+        )
+        row_converted = converted_profit(
+            row_revenue, profit_rate(row_profit, row_revenue), threshold
+        )
+        converted_total += row_converted
+        line_details.append(
+            {
+                "item_id": item.id,
+                "product_category": item.product_category,
+                "revenue": str(row_revenue),
+                "profit": str(row_profit),
+                # 行级折算同样固化为两位（to_decimal 对整数值无小数位，
+                # 快照/台账口径需与列一致）
+                "converted": str(_q2(row_converted)),
+            }
+        )
+    return _Conversion(total_revenue, total_profit, converted_total, missing_cost, line_details)
+
+
+@dataclass(frozen=True, slots=True)
+class _Amounts:
+    """计提组成结果（比例分派 → 绩效 → 抵顶 → 支付权重 → 应付）。"""
+
+    days: int
+    decision: _RateDecision
+    converted: Decimal
+    performance: Decimal
+    barter_applied: bool
+    weight_r: int
+    weight: Fraction
+    payable: Decimal
+    start_ok: bool
+
+
+def _compose_amounts(
+    session: Session,
+    snapshot,
+    person,
+    business: Business,
+    receipt: Receipt,
+    shipment: Shipment,
+    conversion: _Conversion,
+) -> _Amounts:
+    """按比例分派与支付权重组成应付（与 param_service.preview 同公式路径）。"""
+    # 天数只依赖发货/回款日期，先于比例分派算出（业务员递减公式的输入）
+    days = payment_days(shipment.ship_date, receipt.receipt_date)
+    decision = _personal_rate(session, snapshot, person, business, days)
+
+    if decision.base_override is not None:
+        converted = decision.base_override  # 信息员：基数=本人销售额
+    else:
+        converted = conversion.converted_total
+
+    performance = (
+        Decimal("0") if decision.manager_pending else performance_amount(converted, decision.rate)
+    )
+    barter_applied = receipt.is_barter == 1
+    base_amount = performance
+    if barter_applied:
+        discount = parse_fraction(snapshot.get("barter.discount", role_code=role_code_of(person)))
+        base_amount = apply_barter(performance, discount)
+
+    received_total = business.total_received_amount or Decimal("0")
+    start_ratio = parse_fraction(
+        snapshot.get("payment.start.ratio", role_code=role_code_of(person))
+    )
+    start_ok = start_payment_ok(received_total, conversion.total_revenue, start_ratio)
+    weight_r = clamp_weight_r(received_total, conversion.total_revenue)
+    weight = payment_weight(weight_r)
+    payable = param_service.to_decimal(Fraction(base_amount) * weight)
+    return _Amounts(
+        days=days,
+        decision=decision,
+        converted=converted,
+        performance=performance,
+        barter_applied=barter_applied,
+        weight_r=weight_r,
+        weight=weight,
+        payable=payable,
+        start_ok=start_ok,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class _LedgerRows:
+    """拆行落库结果：负责人行恒存在（出参与 CAS 锚点），参与人份额行可空。"""
+
+    owner_row: PerformanceLedger
+    share_rows: list[PerformanceLedger]
+
+
+def _persist_ledger(
+    session: Session,
+    *,
+    receipt: Receipt,
+    business: Business,
+    person,
+    shipment: Shipment,
+    items: list[BusinessItem],
+    allocations: list,
+    conversion: _Conversion,
+    amounts: _Amounts,
+    recalc_reason: str | None,
+    is_recalc: bool,
+) -> _LedgerRows:
+    """落台账行（分摊拆行；版本号自增；金额两位 HALF_UP）+ 首算 CAS 置已核算。
+
+    分摊（澄清 #1 答复 2026-10-19「分配绩效」，算后分）：业务级全额（含
+    递减比例、抵顶、支付权重全环节）算完后按方案比例拆给参与人，余额归
+    合同负责人。行合计与业务级全额**守恒**（负责人行取 q2 全额减参与人
+    q2 份额的差额，防分漂）；每行快照带完整方案快照，行级可独立回溯。
+    参与人离职照分（历史方案事实，方案调整是业务侧责任——入职校验只在
+    保存侧，核算侧只要求人员存在，FK RESTRICT 已保证）。
+    """
+    receipt_date = receipt.receipt_date
+    base_snapshot: dict[str, Any] = {
+        "params_as_of": str(receipt_date),
+        "line_details": conversion.line_details,
+        "start_payment_ok": amounts.start_ok,
+        "rate_note": amounts.decision.rate_note,
+        "revenue_total": str(conversion.total_revenue),
+        "profit_total": str(conversion.total_profit),
+    }
+    if amounts.decision.manager_pending:
+        base_snapshot["strategy_note"] = _NOTE_MANAGER_PENDING
+    if allocations:
+        base_snapshot["alloc_plan"] = [
+            {
+                "personnel_id": a.personnel_id,
+                "personnel_name": a.personnel_name,
+                "ratio": str(a.ratio),
+            }
+            for a in allocations
+        ]
+
+    version = performance_ledger_repository.next_version(session, receipt.id)
+    customer_type = _customer_type(session, business)
+    category = _category_label(items)
+
+    # 份额清单：(person, ratio, tag)——ratio 为 None 时走余额公式（q2 全额
+    # 减已分累计，守恒）；负责人余额的百分数（100−∑参与人）仅作快照展示，
+    # 不参与计算——按它乘全额会丢 q2 尾差（39.1111×30% ≠ 39.11−27.37）
+    shares: list[tuple[Any, Decimal | None, str]] = []
+    owner_ratio_text: str | None = None
+    if not allocations:
+        shares.append((person, None, "owner"))
+        owner_ratio_text = "100"
+    else:
+        total_ratio = Decimal("0")
+        for a in allocations:
+            shares.append((session.get(Personnel, a.personnel_id), a.ratio, "participant"))
+            total_ratio += a.ratio
+        owner_ratio_text = str((Decimal("100") - total_ratio).quantize(Decimal("0.01")))
+        shares.append((person, None, "owner"))
+
+    def _share(full: Decimal, ratio: Decimal | None, *, added: Decimal = Decimal("0")) -> Decimal:
+        """单份额金额：参与人 = 全额×比例（q2）；负责人 = q2 全额 − 已分累计。"""
+        if ratio is None:
+            return _q2(full - added) or Decimal("0")
+        # Fraction 乘积先 to_decimal 再 q2（Fraction 无 quantize，直接喂 _q2 会炸）
+        return _q2(param_service.to_decimal(Fraction(full) * Fraction(ratio) / 100)) or Decimal("0")
+
+    added_perf = Decimal("0")
+    added_conv = Decimal("0")
+    added_pay = Decimal("0")
+    owner_row: PerformanceLedger | None = None
+    share_rows: list[PerformanceLedger] = []
+    for target, ratio, tag in shares:
+        perf = _share(amounts.performance, ratio, added=added_perf)
+        conv = _share(amounts.converted, ratio, added=added_conv)
+        pay = _share(amounts.payable, ratio, added=added_pay)
+        added_perf += perf
+        added_conv += conv
+        added_pay += pay
+        row = performance_ledger_repository.add(
+            session,
+            PerformanceLedger(
+                receipt_id=receipt.id,
+                calc_version=version,
+                calc_type=CALC_TYPE_RECEIPT,
+                business_id=business.id,
+                business_no=business.business_no,
+                personnel_id=target.id,
+                personnel_name=target.personnel_name,
+                role_code=role_code_of(target),
+                customer_type=customer_type,
+                product_category=category,
+                ship_date=shipment.ship_date,
+                receipt_date=receipt_date,
+                payment_days=amounts.days,
+                rate_text=str(amounts.decision.rate),
+                converted_profit=conv,
+                performance_amount=perf,
+                barter_applied=1 if amounts.barter_applied else 0,
+                weight_r=amounts.weight_r,
+                payment_weight=param_service.to_decimal(amounts.weight),
+                payable_amount=pay,
+                settlement_month=receipt_date.strftime("%Y-%m"),
+                is_probation=1 if target.is_probation == 1 else 0,
+                missing_cost=1 if conversion.missing_cost else 0,
+                snapshot_json={
+                    **base_snapshot,
+                    "alloc_role": tag,
+                    "alloc_ratio": owner_ratio_text if tag == "owner" else str(ratio),
+                },
+                calc_reason=recalc_reason,
+            ),
+        )
+        if tag == "owner":
+            owner_row = row
+        else:
+            share_rows.append(row)
+
+    # CAS 仅首算执行：重算模式状态本就是已核算（UPDATE ... WHERE status=0
+    # 会 rowcount=0 误报并发撞车）
+    if not is_recalc:
+        _mark_settled(session, receipt)
+    return _LedgerRows(owner_row=owner_row, share_rows=share_rows)
+
+
+def _q2(value: Decimal | None) -> Decimal | None:
+    """金额统一两位小数（HALF_UP）：内存/DB/序列化三方一致。
+
+    显式传 rounding——quantize 缺省是上下文 ROUND_HALF_EVEN（银行家舍入），
+    x.xx5 会舍成偶数值，与业务四舍五入口径差 1 分。
+    """
+    if value is None:
+        return None
+    return value.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+
+def _personal_rate(
+    session: Session,
+    snapshot,
+    person,
+    business: Business,
+    days: int,
+) -> _RateDecision:
+    """按岗位模板分派单笔计提比例（与 param_service._preview_rate 同构）。
+
+    #12 策略点：经理个人户（owner 岗位绑 TPL_MANAGER_SHARE）单笔不计提
+    —— 12.5%+5% 是月度团队聚合口径，单笔落 rate=0/绩效 0 的台账行保事实。
+    """
+    role = _role_of(session, person)
+    customer_type = _customer_type(session, business)
+
+    if customer_type == "enterprise":
+        # 存储口径 ‰ → 纯比例（漏换算放大 1000 倍，与预览同防线）
+        rate = parse_fraction(snapshot.get("enterprise.rate")) / 1000
+        return _RateDecision(rate, "企业户固定计提比例", None, False)
+
+    template = role.calc_template if role else "TPL_SALESPERSON_DECAY"
+    if template == "TPL_MANAGER_SHARE":
+        # #12 答复（2026-10-19）参数化：manager.personal.included=1 时个人户
+        # 单按业务员递减公式单笔计提（个人户单本质是正常业务，有发货/回款/
+        # 毛利；聚合基数开关在 settlement_service 同参数消费）——0 时单笔落 0
+        if snapshot.get("manager.personal.included") != "1":
+            return _RateDecision(
+                Decimal("0"),
+                "经理个人户：12.5%+5% 聚合计提（月结时计算），单笔落 0",
+                None,
+                True,
+            )
+        start = parse_fraction(snapshot.get("salesperson.rate.start"))
+        slope = parse_fraction(snapshot.get("salesperson.rate.slope"))
+        floor = parse_fraction(snapshot.get("salesperson.rate.floor"))
+        boundary = int(parse_fraction(snapshot.get("salesperson.days.boundary")))
+        rate = salesperson_rate(days, start=start, slope=slope, floor=floor, boundary_days=boundary)
+        note = f"经理个人户（基数开关=1）：按业务员递减 {start}‰ 起，{days} 天"
+        return _RateDecision(rate, note, None, False)
+    if template == "TPL_INFO_SALES_FIXED":
+        # 信息员基数=本人销售额（覆盖折算与阈值），‰ 换算同防线
+        rate = parse_fraction(snapshot.get("info.rate")) / 1000
+        return _RateDecision(rate, "信息员：本人销售额 × 计提比例", None, False)
+    if template == "TPL_SALESPERSON_DECAY":
+        start = parse_fraction(snapshot.get("salesperson.rate.start"))
+        slope = parse_fraction(snapshot.get("salesperson.rate.slope"))
+        floor = parse_fraction(snapshot.get("salesperson.rate.floor"))
+        # int(参数原文) 对合法入库的 '360.0' 会抛 ValueError 使整月核算 500；
+        # 经 Fraction 转换再取整（INT 型参数入库时已校验分母为 1，取整无损）
+        boundary = int(parse_fraction(snapshot.get("salesperson.days.boundary")))
+        rate = salesperson_rate(days, start=start, slope=slope, floor=floor, boundary_days=boundary)
+        note = f"业务员递减：{start}‰ 起，{days} 天（分界 {boundary} 天，超界取 {floor}‰）"
+        return _RateDecision(rate, note, None, False)
+    raise BadRequestError(f"公式模板 {template} 暂不支持核算")
+
+
+def _role_of(session: Session, person):
+    from app.repositories import business_role_repository
+
+    if person.business_role_id is None:
+        return None
+    return business_role_repository.get_by_id(session, person.business_role_id)
+
+
+def role_code_of(person) -> str:
+    """人员岗位编码（台账冗余固化用；无岗位为空串——前置校验已拦）。"""
+    from app.repositories import business_role_repository
+
+    if person.business_role_id is None:
+        return ""
+    session = Session.object_session(person)
+    role = business_role_repository.get_by_id(session, person.business_role_id)
+    return role.role_code if role else ""
+
+
+def _customer_type(session: Session, business: Business) -> str:
+    customer = session.get(Customer, business.customer_id)
+    return customer.customer_type if customer else "personal"
+
+
+def _category_label(items: list[BusinessItem]) -> str:
+    """单类别直出；混合业务记 mixed（行级明细在 snapshot_json）。"""
+    categories = {item.product_category for item in items}
+    return categories.pop() if len(categories) == 1 else "mixed"
+
+
+def _mark_settled(session: Session, receipt: Receipt) -> None:
+    """CAS 置已核算：并发下另一事务先行置 1 时 rowcount=0 → 400。"""
+    result = session.execute(
+        update(Receipt)
+        .where(Receipt.id == receipt.id, Receipt.settlement_status == SETTLEMENT_PENDING)
+        .values(settlement_status=SETTLEMENT_DONE)
+    )
+    if result.rowcount == 0:
+        raise BadRequestError("该回款已被并发核算，请刷新后查看台账")
+
+
+def _row_profit(revenue: Decimal, cost: Decimal) -> Decimal:
+    """行毛利 = 行销售额 − 行成本。
+
+    #20 策略点（待业务答复，2026-10-16 暂定口径）：金额暂按**不含税**原样
+    相减；答复若为含税口径，只改本函数（含税换算/取不含税金额列）+ 按回款
+    批量重算回填。
+    """
+    return revenue - cost
+
+
+def recalc_receipt(
+    session: Session,
+    receipt_id: int,
+    reason: str,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+) -> CalcReceiptOut:
+    """重算（授权动作，管理员/财务）：作废旧版本行、按当前参数重算新版本。
+
+    薄委托 calc_receipt(recalc_reason=...)——折算体只有一份；所属月已审定
+    的拦截在 calc_receipt 内（核算与重算同口径）。
+    """
+    if not reason or not reason.strip():
+        raise BadRequestError("重算必须填写原因")
+    return calc_receipt(
+        session, receipt_id, operator=operator, meta=meta, recalc_reason=reason.strip()
+    )
+
+
+def batch_calc(
+    session: Session,
+    receipt_ids: list[int],
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+) -> list[dict]:
+    """批量核算：逐笔独立事务（各笔自带 audit），返回逐笔成败清单。
+
+    **不开外层 audit**——外层包 audit 会违反嵌套禁令，且单笔失败不应
+    回滚其它笔的核算结果。
+    """
+    results: list[dict] = []
+    for rid in receipt_ids:
+        try:
+            out = calc_receipt(session, rid, operator=operator, meta=meta)
+            results.append(
+                {
+                    "receipt_id": rid,
+                    "ok": True,
+                    "repeated": out.repeated,
+                    "ledger_id": out.ledger.id,
+                }
+            )
+        except Exception as exc:
+            results.append(
+                {"receipt_id": rid, "ok": False, "error": f"{type(exc).__name__}: {exc}"}
+            )
+    ok_count = sum(1 for r in results if r["ok"])
+    logger.info("批量核算 | 总数=%s 成功=%s", len(results), ok_count)
+    return results
+
+
+def list_ledger_page(session: Session, query):
+    """分页查询台账（api 层转发）。"""
+    rows = performance_ledger_repository.list_ledger(session, query)
+    total = performance_ledger_repository.count_ledger(session, query)
+    from app.core.response import PageResult
+    from app.schemas.calc import LedgerOut
+
+    return PageResult[LedgerOut](
+        records=[LedgerOut.model_validate(r) for r in rows],
+        total=total,
+        page_num=query.page_num,
+        page_size=query.page_size,
+    )
+
+
+def get_ledger(session: Session, ledger_id: int):
+    """台账详情（api 层转发）。"""
+    row = performance_ledger_repository.get_by_id(session, ledger_id)
+    if row is None:
+        from app.core.exceptions import NotFoundError
+
+        raise NotFoundError("台账记录不存在")
+    from app.schemas.calc import LedgerOut
+
+    return LedgerOut.model_validate(row)
+
+
+def _to_out(row: PerformanceLedger):
+    from app.schemas.calc import LedgerOut
+
+    return LedgerOut.model_validate(row)

backend/app/services/customer_service.py

@@ -26,6 +26,7 @@ from app.core.constants import (
     CUSTOMER_TYPES,
     MODULE_CUSTOMER,
 )
+from app.core.db_errors import is_duplicate_entry
 from app.core.exceptions import BadRequestError, NotFoundError
 from app.core.response import PageQuery, PageResult
 from app.models import Customer, OwnershipChangeLog, Personnel, User
@@ -39,15 +40,11 @@ from app.schemas.customer import (
     CustomerUpdateIn,
     OwnershipChangeLogOut,
 )
-from app.services import audit_service
+from app.services import audit_service, personnel_service
 from app.services.audit_service import AuditRecord, RequestMeta
 
 logger = logging.getLogger(__name__)
 
-# personnel.status 的在职值（列注释口径：1在职 0离职）。离职人员不可再被
-# 客户归属引用；人员侧抽出共享常量后此处替换
-_PERSONNEL_STATUS_ACTIVE = 1
-
 
 def _to_out(customer: Customer, owner_name: str | None) -> CustomerOut:
     """ORM 对象转响应模型。禁止把 ORM 对象直接当 response_model。"""
@@ -94,28 +91,18 @@ def _ensure_customer_type(customer_type: str) -> None:
 
 
 def _ensure_owner_personnel(session: Session, personnel_id: int) -> Personnel:
-    """归属人员必须存在且在职，返回人员行。
+    """归属人员必须存在且在职（共享校验收口于 personnel_service.ensure_active）。"""
-
+    return personnel_service.ensure_active(session, personnel_id, label="归属")
-    「不存在」与「已离职」合并为同一文案：人员 ID 是否有效不构成需要
-    向调用方区分的信息（同登录防枚举的思路）。
-
-    :raises BadRequestError: 归属人员不存在或已离职
-    """
-    person = personnel_repository.get_by_id(session, personnel_id)
-    if person is None or person.status != _PERSONNEL_STATUS_ACTIVE:
-        raise BadRequestError("归属人员不存在或已离职")
-    return person
 
 
 def _is_duplicate_entry(exc: IntegrityError) -> bool:
-    """判断 IntegrityError 是否为 MySQL 唯一键冲突（错误码 1062）。
+    """判断 IntegrityError 是否为 MySQL 唯一键冲突（1062）。
 
     customers 上还有归属人员外键（RESTRICT），并发窗口内删除人员等场景
     会抛 1452 —— 不能一并翻译成「已存在」，否则用户会被错误提示带偏；
-    非 1062 原样上抛，由全局处理器按 500 收敛。
+    非 1062 原样上抛，由全局 IntegrityError handler 收敛 400（通用文案）。
     """
-    args = getattr(exc.orig, "args", ())
+    return is_duplicate_entry(exc)
-    return bool(args) and args[0] == 1062
 
 
 def list_customers(session: Session, query: CustomerQuery) -> PageResult[CustomerOut]:

backend/app/services/dashboard_service.py

@@ -0,0 +1,278 @@
+"""工作台服务（M4 ⑧）：四区块实时聚合编排。
+
+设计决策（2026-10-19）：
+- **只读**：不落库、不写审计（读操作不入操作日志）；总览只做 SQL 聚合，
+  不复用报表的部门汇总（后者会加载整月台账，过重）
+- **待办与预警实时派生**：不建待办/预警表、不引调度器；处置动作本身
+  已有操作日志可追溯。与 FR-035「预警产生/消除留痕」的差距记录在
+  计划开放项，待业务确认是否物化
+- **⑥ 同步模块未启用**：同步失败待办、同步连续失败预警以
+  ``sync_available=false`` 显式降级，不返回伪造的 0 条
+- 预警阈值走参数体系（``warning.*``），一次请求只解析一次快照
+"""
+
+from datetime import date, datetime, timedelta
+from decimal import Decimal
+
+from sqlalchemy.orm import Session
+
+from app.core.exceptions import BadRequestError
+from app.core.month import validate_month
+from app.repositories import dashboard_repository, operation_log_repository, user_repository
+from app.repositories.query_utils import LogFilters
+from app.services import approval_service
+
+# 工作台只展示摘要，完整列表跳转对应管理页
+_TODO_LIMIT = 5
+_WARNING_LIMIT = 20
+_ACTIVITY_LIMIT = 20
+_TREND_MONTHS = 6
+
+_ORDER_TYPE_LABELS = {1: "二次分配方案", 2: "月度结算", 3: "调整单"}
+
+
+def get_dashboard(session: Session, month: str | None = None, *, current_user) -> dict:
+    """四区块一次性出数（前端一次请求渲染整页）。
+
+    待办按当前用户角色只展示其可操作节点（admin 可查看全部在途单）；
+    风险预警仍是全局经营视角，不按人裁剪。
+    """
+    resolved = _normalize_month(month)
+    warning_params = _warning_params(session)
+    pending_statuses = approval_service.pending_statuses_for_roles(
+        user_repository.get_role_codes(current_user)
+    )
+    return {
+        "month": resolved,
+        "overview": _overview(session, resolved),
+        "todos": _todos(session, pending_statuses),
+        "warnings": _warnings(session, warning_params),
+        "activities": _activities(session),
+    }
+
+
+def _normalize_month(month: str | None) -> str:
+    """未传月份按当月；非法月份在入口拦成 400（避免 500）。"""
+    if not month:
+        today = date.today()
+        return f"{today.year:04d}-{today.month:02d}"
+    try:
+        return validate_month(month)
+    except ValueError as exc:
+        raise BadRequestError(str(exc)) from exc
+
+
+def _shift_month(month: str, delta: int) -> str:
+    """YYYY-MM 平移 delta 个月（用于近 N 个月窗口）。"""
+    year, mon = int(month[:4]), int(month[5:7])
+    index = year * 12 + (mon - 1) + delta
+    return f"{index // 12:04d}-{index % 12 + 1:02d}"
+
+
+def _month_start(month: str) -> date:
+    """YYYY-MM → 该月首日（范围查询边界，避免函数列过滤）。"""
+    return date(int(month[:4]), int(month[5:7]), 1)
+
+
+def _trend_months(month: str) -> list[str]:
+    """窗口为「当月及之前共 6 个月」，升序返回便于前端画图。"""
+    return [_shift_month(month, offset) for offset in range(-(_TREND_MONTHS - 1), 1)]
+
+
+def _overview(session: Session, month: str) -> dict:
+    """经营绩效总览（FR-033）：口径与台账/月结一致。"""
+    sums = dashboard_repository.sum_month_performance(session, month)
+    settlement = dashboard_repository.get_month_settlement(session, month)
+    months = _trend_months(month)
+    performance = dashboard_repository.performance_trend(session, months)
+    receipts = dashboard_repository.receipt_trend(
+        session,
+        start_date=_month_start(months[0]),
+        end_date=_month_start(_shift_month(months[-1], 1)),
+    )
+    return {
+        "month": month,
+        "performance_total": _dec(sums["performance_total"]),
+        "payable_total": _dec(sums["payable_total"]),
+        "person_count": int(sums["person_count"]),
+        "team_count": dashboard_repository.count_active_managers(session),
+        "settlement": {
+            "exists": settlement is not None,
+            "status": settlement.status if settlement else None,
+            "total_performance": settlement.total_performance if settlement else None,
+            "total_payable": settlement.total_payable if settlement else None,
+            "locked_at": settlement.locked_at if settlement else None,
+        },
+        "trend": [
+            {
+                "month": item,
+                "performance_total": _dec(performance.get(item)),
+                "receipt_total": _dec(receipts.get(item)),
+            }
+            for item in months
+        ],
+        "note": (
+            "绩效按台账归属月（单笔生效行，二次分摊拆行求和不失真）；回款按到账月"
+            "（含未核算回款）；不含经理 12.5%+5% 聚合分成与调整单"
+        ),
+    }
+
+
+def _todos(session: Session, pending_statuses: tuple[int, ...]) -> dict:
+    """待办事项（FR-034，澄清 #11 起步范围）。
+
+    ``pending_statuses`` 已按当前用户角色解析：财务只看待财务复核、
+    领导只看待领导审核；admin 查看全部在途单。
+    """
+    orders = dashboard_repository.list_pending_approvals(
+        session, statuses=pending_statuses, limit=_TODO_LIMIT
+    )
+    receipts = dashboard_repository.list_unassigned_receipts(session, limit=_TODO_LIMIT)
+    return {
+        "pending_approval_total": dashboard_repository.count_pending_approvals(
+            session, statuses=pending_statuses
+        ),
+        "pending_approvals": [
+            {
+                "order_id": order.id,
+                "order_no": order.order_no,
+                "order_type": order.order_type,
+                "submitter_name": order.submitter_name,
+                "create_time": order.create_time,
+            }
+            for order in orders
+        ],
+        "unassigned_receipt_total": dashboard_repository.count_unassigned_receipts(session),
+        "unassigned_receipts": [
+            {
+                "receipt_id": row[0].id,
+                "receipt_batch_no": row[0].receipt_batch_no,
+                "business_id": row[0].business_id,
+                "business_no": row.business_no,
+                "amount": row[0].amount,
+                "receipt_date": row[0].receipt_date,
+            }
+            for row in receipts
+        ],
+        # ⑥ T+ 同步未建：显式降级，不伪造「无失败」
+        "sync_available": False,
+        "sync_failure_total": 0,
+    }
+
+
+def _warning_params(session: Session) -> dict:
+    """预警参数一次解析（阈值参数化，澄清 #10）。"""
+    from app.services.param_service import parse_fraction, resolve_snapshot
+
+    snapshot = resolve_snapshot(session, date.today())
+    return {
+        "enabled": snapshot.get("warning.enabled") == "1",
+        "receipt_overdue_days": int(parse_fraction(snapshot.get("warning.receipt.overdue.days"))),
+        "approval_timeout_days": int(
+            parse_fraction(snapshot.get("warning.approval.timeout.days"))
+        ),
+    }
+
+
+def _warnings(session: Session, params: dict) -> dict:
+    """风险预警（FR-035）：首批两条可算规则；同步规则待 ⑥。"""
+    if not params["enabled"]:
+        return {
+            "enabled": False,
+            "receipt_overdue_days": params["receipt_overdue_days"],
+            "approval_timeout_days": params["approval_timeout_days"],
+            "items": [],
+            "total": 0,
+            "receipt_overdue_total": 0,
+            "approval_timeout_total": 0,
+            "sync_available": False,
+        }
+
+    receipt_cutoff = date.today() - timedelta(days=params["receipt_overdue_days"])
+    approval_cutoff = datetime.now() - timedelta(days=params["approval_timeout_days"])
+    shipments = dashboard_repository.list_overdue_shipments(
+        session, cutoff=receipt_cutoff, limit=_WARNING_LIMIT
+    )
+    orders = dashboard_repository.list_overdue_approvals(
+        session, cutoff=approval_cutoff, limit=_WARNING_LIMIT
+    )
+
+    items = [
+        {
+            "code": "receipt_overdue",
+            "level": "danger",
+            "object_type": "shipment",
+            "object_id": row[0].id,
+            "title": f"发货批次 {row[0].shipment_no} 逾期未回款",
+            "detail": (
+                f"业务 {row.business_no or row[0].business_id} 发货日 {row[0].ship_date}，"
+                f"超过 {params['receipt_overdue_days']} 天无回款记录"
+            ),
+            "suggest": "联系客户催收，或核对回款批次指定关系",
+            "link": "/business/shipments",
+        }
+        for row in shipments
+    ]
+    items += [
+        {
+            "code": "approval_timeout",
+            "level": "warning",
+            "object_type": "approval_order",
+            "object_id": order.id,
+            "title": f"审批单 {order.order_no} 超时未处理",
+            "detail": (
+                f"{_ORDER_TYPE_LABELS.get(order.order_type, '审批')}由 "
+                f"{order.submitter_name or '—'} 提交于 {order.create_time:%Y-%m-%d %H:%M}，"
+                f"已超过 {params['approval_timeout_days']} 天"
+            ),
+            "suggest": "在审批管理中复核或退回",
+            "link": "/system/approvals",
+        }
+        for order in orders
+    ]
+    receipt_overdue_total = dashboard_repository.count_overdue_shipments(
+        session, cutoff=receipt_cutoff
+    )
+    approval_timeout_total = dashboard_repository.count_overdue_approvals(
+        session, cutoff=approval_cutoff
+    )
+    return {
+        "enabled": True,
+        "receipt_overdue_days": params["receipt_overdue_days"],
+        "approval_timeout_days": params["approval_timeout_days"],
+        "items": items,
+        # items 有展示上限（_WARNING_LIMIT），徽标计数必须用全量命中数
+        "total": receipt_overdue_total + approval_timeout_total,
+        "receipt_overdue_total": receipt_overdue_total,
+        "approval_timeout_total": approval_timeout_total,
+        "sync_available": False,
+    }
+
+
+def _activities(session: Session) -> list[dict]:
+    """最近动态（FR-036）：以操作日志为唯一来源（写操作即留痕）。"""
+    logs = operation_log_repository.list_logs(
+        session,
+        offset=0,
+        limit=_ACTIVITY_LIMIT,
+        filters=LogFilters(),
+    )
+    return [
+        {
+            "id": log.id,
+            "module": log.module,
+            "action": log.action,
+            "summary": log.summary,
+            "username": log.username,
+            "success": log.success,
+            "create_time": log.create_time,
+        }
+        for log in logs
+    ]
+
+
+def _dec(value) -> Decimal | None:
+    """SQL 聚合结果转 Decimal（SUM 可能返回 int，None 原样返回）。"""
+    if value is None:
+        return None
+    return value if isinstance(value, Decimal) else Decimal(str(value))

backend/app/services/formula.py

@@ -40,9 +40,20 @@ def salesperson_rate(
     start/floor 为 ‰ 数、slope 为 ‰/天（存储口径，slope 为精确分数 4/360）。
     ≤分界天数按「起始 − 天数×斜率」线性递减；超过分界天数固定取下限
     （对照表 #4：360 天=6‰，361 天起固定 4‰）。
+
+    首日取整（澄清 #14 业务答复 2026-10-19）：第 1 天**不递减**、直接取
+    起始值（需规图示「第 1 天 10‰」覆盖公式的 9.9889‰）——第 2 天起按公式
+    递减，360 天=6‰ 锚点与 361 天=4‰ 分界均不受影响。
+
+    先款后货的回款（payment_days 为负）钳制为 0 天：负天数线性外插会算出
+    高于起始值的比例（多算绩效），钳到 0 天即按起始比例计提；payment_days
+    的出参仍照实输出负值（回款登记照常入库，录入异常由台账留痕暴露）。
     """
+    days = max(days, 0)
     if days > boundary_days:
         return floor / 1000
+    if days <= 1:
+        return start / 1000
     return (start - days * slope) / 1000
 
 
@@ -90,3 +101,63 @@ def start_payment_ok(received: Decimal, revenue: Decimal, ratio: Fraction) -> bo
     if revenue == 0:
         return False
     return Fraction(received) / Fraction(revenue) >= ratio / 100
+
+
+def clamp_weight_r(received: Decimal, revenue: Decimal) -> int:
+    """支付权重 R：回款占销售额百分比，封顶封底 [0, 100]（对照表 #22）。
+
+    received 非负时 int() 即向下取整；min/max 同时是红字冲销（负数回款）
+    接入时的方向防线。从计算预览的内联实现提取 —— ④ 核算与预览共用。
+    """
+    if revenue <= 0:
+        return 0
+    return max(0, min(100, int(Fraction(received) / Fraction(revenue) * 100)))
+
+
+def monthly_salary(performance: Decimal, basic: Decimal | None, mode: str) -> Decimal | None:
+    """月工资分岗口径（对照表 #8，salary.basic.mode 按角色维度取值）。
+
+    - INCLUDE：绩效 + 基本工资（业务员默认——绩效之外照发基本工资）
+    - DEDUCT：绩效 − 基本工资（经理默认——基本工资从绩效分成中扣除）
+    - EXCLUDE：仅绩效，基本工资不参与
+    basic 缺失时按 0 参与（INCLUDE/EXCLUDE 等价于纯绩效）。
+    """
+    basic_value = basic if basic is not None else Decimal("0")
+    if mode == "INCLUDE":
+        return performance + basic_value
+    if mode == "DEDUCT":
+        return performance - basic_value
+    if mode == "EXCLUDE":
+        return performance
+    raise ValueError(f"未知的月工资口径：{mode}")
+
+
+def probation_annual_note(year_total: Decimal, threshold: Decimal) -> str | None:
+    """试用期年累计说明：超阈值部分年底一次性结算（对照表 #17）。
+
+    未超阈值返回 None（无需说明）；阈值按元展示（Decimal 直出）。
+    """
+    if year_total <= threshold:
+        return None
+    excess = (year_total - threshold).quantize(Decimal("0.01"), rounding="ROUND_HALF_UP")
+    return f"试用期绩效照算不发放；年累计超 {threshold} 元部分年底一次性结算（当前超 {excess} 元）"
+
+
+def manager_team_share(
+    team_performance: Decimal,
+    company_performance: Decimal,
+    *,
+    team_pct: Fraction,
+    company_pct: Fraction,
+) -> Decimal:
+    """经理绩效 = 本团队业务员绩效 × 12.5% + 全公司业务员绩效 × 5%（裁决 #6/#15/#16）。
+
+    **#12 策略点（待业务答复，2026-10-16 暂定口径）**：基数**不含**经理本人
+    名下经理个人户业务的业绩——该部分按经理个人户规则另行处理（单笔落台账
+    rate=0/绩效 0，待答复后若需并入，只改调用方传入的基数集合）。
+    团队口径：manager_id=该经理且岗位非「营销经理」的业务员绩效行之和；
+    全公司口径：全部业务员（非经理岗）绩效行之和。
+    """
+    return _to_decimal(Fraction(team_performance) * team_pct / 100) + _to_decimal(
+        Fraction(company_performance) * company_pct / 100
+    )

backend/app/services/manager_share.py

@@ -0,0 +1,124 @@
+"""经理分成共享口径（月结聚合与报表部门汇总的唯一实现）。
+
+从 settlement_service 迁出（行为零变化）：经理 12.5%/5% 的取参、团队
+分桶、公司基数计算，月结生成与部门汇总报表都要用——抽为单一实现后
+「报表汇总 == 月结聚合行」不靠两处代码各自对齐，而是同源函数的直接
+结果。分成金额仍走 formula.manager_team_share 纯函数。
+"""
+
+from calendar import monthrange
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+from fractions import Fraction
+
+from sqlalchemy.orm import Session
+
+from app.core.exceptions import BadRequestError
+from app.core.month import parse_month
+from app.models import Personnel
+
+
+@dataclass(frozen=True, slots=True)
+class ManagerShareParams:
+    """经理分成取参与参数原文（同一次计算共用一份，随月月末时点化）。"""
+
+    month: str
+    param_date: date
+    team_text: str
+    company_text: str
+    team_pct: Fraction
+    company_pct: Fraction
+    include_manager_personal: bool
+
+
+def month_end(month: str) -> date:
+    """YYYY-MM → 所属月月末（月结与报表取参锚点）。
+
+    月结是对过去某月的金额计算，取参必须锚定业务月份——按 date.today()
+    会让补生成历史月份的结果随操作日期漂移（违背「参数按生效日期时点化」
+    红线）。单笔台账行按回款日取参（裁决 #11）；聚合与月工资口径没有
+    更细的业务日期，取该月最后可确定的生效时点。
+    """
+    try:
+        year, mon = parse_month(month)
+    except ValueError as exc:
+        # schema 已拦住非法月份；内部调用绕过 schema 时也不能变成 500
+        raise BadRequestError(str(exc)) from exc
+    return date(year, mon, monthrange(year, mon)[1])
+
+
+def manager_share_params(session: Session, month: str) -> ManagerShareParams:
+    """解析经理分成参数（锚定所属月月末，取参与台账行口径同源）。
+
+    参数按百分数存储（12.5 表示 12.5%）：parse_fraction 得 12.5，
+    manager_team_share 内部再 ÷100 —— 调用方不得再乘 100（否则放大 100 倍）。
+    #12 开关（manager.personal.included）与分成比例同日取参，答复后调整可追溯。
+    """
+    from app.services.param_service import parse_fraction, resolve_snapshot
+
+    param_date = month_end(month)
+    snapshot = resolve_snapshot(session, param_date)
+    team_text = snapshot.get("manager.share.team")
+    company_text = snapshot.get("manager.share.company")
+    return ManagerShareParams(
+        month=month,
+        param_date=param_date,
+        team_text=team_text,
+        company_text=company_text,
+        team_pct=parse_fraction(team_text),
+        company_pct=parse_fraction(company_text),
+        include_manager_personal=snapshot.get("manager.personal.included") == "1",
+    )
+
+
+def add_team_performance(managers: dict[int, dict], manager_id: int, row) -> None:
+    """把一行业绩并入经理的团队桶（首行固化业务锚点，成员名去重收集）。"""
+    bucket = managers.setdefault(
+        manager_id,
+        {
+            "performance": Decimal("0"),
+            "business_id": row.business_id,
+            "business_no": row.business_no,
+            "names": set(),
+        },
+    )
+    bucket["performance"] += row.performance_amount or Decimal("0")
+    bucket["names"].add(row.personnel_name)
+
+
+def collect_team_buckets(
+    session: Session, ledger_rows: list, include_manager_personal: bool
+) -> dict[int, dict]:
+    """按经理采集团队业绩。
+
+    业务员行经 manager_id 上溯到其经理；经理个人户行（#12 开关计入时）
+    归属经理本人——行 personnel_id 即经理，不走上溯（经理没有上级，
+    按上溯会被跳过漏计）。
+    """
+    managers: dict[int, dict] = {}
+    for row in ledger_rows:
+        if row.customer_type == "manager_personal":
+            if include_manager_personal:
+                add_team_performance(managers, row.personnel_id, row)
+            continue  # 默认不计入聚合基数（#12 参数化）
+        person = session.get(Personnel, row.personnel_id)
+        manager_id = person.manager_id if person else None
+        if manager_id is not None:
+            add_team_performance(managers, manager_id, row)
+    return managers
+
+
+def company_base_of(ledger_rows: list, include_manager_personal: bool) -> Decimal:
+    """全公司基数（5% 的底）：默认排除经理个人户行（#12 开关计入时不过滤）。
+
+    口径逐行固定，调用方在循环外算一次。
+    """
+    return sum(
+        (
+            r.performance_amount or Decimal("0")
+            for r in ledger_rows
+            if include_manager_personal or r.customer_type != "manager_personal"
+        ),
+        Decimal("0"),
+    )

backend/app/services/no_generator.py

@@ -8,7 +8,7 @@
 
 from datetime import datetime
 
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
 
@@ -35,10 +35,13 @@ def next_no(
     """
     like_prefix = today_prefix(prefix)
     column = getattr(model, column_name)
+    # 排序按「长度优先、同级字典序」：同前缀下序号位数增多（9999→10000）后
+    # 纯字典序会反转（"-10000" < "-9999"，'1'<'9'），seq 将恒重算出同一号码、
+    # 每笔建单都撞唯一键 —— 长度大即数值大，同级同长时字典序与数值序一致
     max_no = session.execute(
         select(column)
         .where(column.like(f"{like_prefix}%"))
-        .order_by(column.desc())
+        .order_by(func.length(column).desc(), column.desc())
         .limit(1)
         .with_for_update()
     ).scalar()

backend/app/services/param_registry.py

@@ -243,18 +243,124 @@ PARAM_REGISTRY: dict[str, ParamSpec] = {
             sort_order=15,
         ),
         ParamSpec(
-            code="probation.salary.basic",
+            code="approval.secondary_allocation.enabled",
-            name="试用期基本工资标准",
+            name="二次分配审批开关",
-            group="月工资口径",
+            group="审批开关",
-            value_type="DECIMAL",
+            value_type="BOOL",
-            unit="元",
+            unit=None,
             dimension_type="NONE",
             options=None,
-            default_value="3000",
+            default_value="1",
-            value_min="0",
+            value_min=None,
             value_max=None,
-            description="试用期仅发基本工资、不发放绩效（归属待 M2 复核）",
+            description=(
-            sort_order=16,
+                "0=二次分配方案提交即生效（系统自动通过全节点留痕，留痕不断链）；"
+                "1=提交后进入财务复核→领导审核审批流。"
+                "默认开启（澄清 #5 业务答复 2026-10-19），业务可关闭"
+            ),
+            sort_order=17,
+        ),
+        ParamSpec(
+            code="approval.monthly_settlement.enabled",
+            name="月度结算审批开关",
+            group="审批开关",
+            value_type="BOOL",
+            unit=None,
+            dimension_type="NONE",
+            options=None,
+            default_value="1",
+            value_min=None,
+            value_max=None,
+            description=(
+                "月度结算审批链开关（④ 月结提交时消费）："
+                "0=结算生成即生效，1=走财务复核→领导审核审批流。"
+                "默认开启（澄清 #7 业务答复 2026-10-19，月结涉及工资发放从严），业务可关闭"
+            ),
+            sort_order=18,
+        ),
+        ParamSpec(
+            code="approval.adjustment.enabled",
+            name="调整单审批开关",
+            group="审批开关",
+            value_type="BOOL",
+            unit=None,
+            dimension_type="NONE",
+            options=None,
+            default_value="0",
+            value_min=None,
+            value_max=None,
+            description=(
+                "0=调整单提交即生效（系统自动通过留痕）；1=走财务复核→领导审核审批流。"
+                "调整单是已锁定月份补发/扣减的唯一通道（澄清 #9：走同一审批链，"
+                "默认值业务未明确，暂按直接生效，业务可开启）"
+            ),
+            sort_order=19,
+        ),
+        ParamSpec(
+            code="manager.personal.included",
+            name="经理个人户计入聚合基数",
+            group="经理分成",
+            value_type="BOOL",
+            unit=None,
+            dimension_type="NONE",
+            options=None,
+            default_value="0",
+            value_min=None,
+            value_max=None,
+            description=(
+                "经理 12.5%+5% 聚合时是否计入经理本人名下经理个人户业绩（澄清 #12 "
+                "业务答复 2026-10-19：作为参数配置、手动调整是否纳入）："
+                "0=不计入（默认，暂口径） 1=计入"
+            ),
+            sort_order=20,
+        ),
+        # ===== 预警规则（M4 ⑧ 工作台，澄清 #10「做成参数化规则便于调整」）=====
+        # 首批三条中「同步连续失败」依赖 ⑥ T+ 同步，模块未建前不设参数、不产生条目
+        ParamSpec(
+            code="warning.enabled",
+            name="风险预警总开关",
+            group="预警规则",
+            value_type="BOOL",
+            unit=None,
+            dimension_type="NONE",
+            options=None,
+            default_value="1",
+            value_min=None,
+            value_max=None,
+            description="工作台风险预警区块总开关：0=关闭（不扫描不展示） 1=开启（默认）",
+            sort_order=21,
+        ),
+        ParamSpec(
+            code="warning.receipt.overdue.days",
+            name="回款逾期天数阈值",
+            group="预警规则",
+            value_type="INT",
+            unit="天",
+            dimension_type="NONE",
+            options=None,
+            default_value="90",
+            value_min="1",
+            value_max=None,
+            description=(
+                "发货后超过该天数仍未回款的发货批次触发预警（澄清 #10 建议默认 90 天）"
+            ),
+            sort_order=22,
+        ),
+        ParamSpec(
+            code="warning.approval.timeout.days",
+            name="审批超时天数阈值",
+            group="预警规则",
+            value_type="INT",
+            unit="天",
+            dimension_type="NONE",
+            options=None,
+            default_value="3",
+            value_min="1",
+            value_max=None,
+            description=(
+                "待审批单提交后超过该天数未处理触发预警（澄清 #10 建议默认 3 天）"
+            ),
+            sort_order=23,
         ),
     ]
 }

backend/app/services/param_service.py

@@ -13,7 +13,6 @@ from decimal import Decimal
 from fractions import Fraction
 from io import BytesIO
 
-from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
@@ -21,6 +20,7 @@ from app.core.constants import (
     ACTION_DELETE,
     ACTION_UPDATE,
     MODULE_PARAM,
+    NO_PREFIX_PARAM,
     PRODUCT_CATEGORIES,
 )
 from app.core.exceptions import BadRequestError, NotFoundError
@@ -35,6 +35,7 @@ from app.schemas.param import (
     ParamCatalogItemOut,
     ParamChangeBatchOut,
     ParamChangeIn,
+    ParamChangeItemIn,
     ParamDiffOut,
     ParamDimensionValueOut,
     ParamHistoryOut,
@@ -46,6 +47,7 @@ from app.schemas.param import (
 from app.services import audit_service, formula
 from app.services.audit_service import AuditRecord, RequestMeta
 from app.services.formula import to_decimal
+from app.services.no_generator import next_no
 from app.services.param_registry import get_spec, parse_fraction, validate_and_normalize
 
 logger = logging.getLogger(__name__)
@@ -187,19 +189,65 @@ def get_catalog(session: Session, *, as_of: date | None = None) -> list[ParamCat
 # ==================== 变更与版本管理 ====================
 
 
-def _next_version_no(session: Session) -> str:
+def _normalize_items(
-    """生成批次版本号 P{YYYYMMDD}-{当日序号}（当日自增，两位补零）。"""
+    session: Session, items: list[ParamChangeItemIn]
-    today = date.today()
+) -> list[tuple[ParamDefinition, str, str]]:
-    prefix = f"P{today:%Y%m%d}"
+    """全量校验条目并归一为 (定义, 规范维度值, 规范值)，任何一项不合法整批拒绝。
-    seq = 0
+
-    for (version_no,) in session.execute(
+    定义与岗位各一条 IN 批量查询预载（逐条查询在批次扩大时是写侧 N+1）；
-        select(ParamChangeBatch.version_no).where(ParamChangeBatch.version_no.like(f"{prefix}-%"))
+    岗位预载收集全部非空维度值 —— 集合可能略大于实际所需，但省去按维度
+    类型先分类的第二轮遍历，无害多取由校验逻辑自行过滤。
+
+    :raises BadRequestError: 参数未定义 / 维度不合法 / 值校验失败 / 同批次重复条目
+    """
+    codes = list({item.param_code for item in items})
+    definitions = param_repository.list_definitions_by_codes(session, codes)
+    dimension_values = list({item.dimension_value for item in items if item.dimension_value})
+    # 预载字典键归一为 casefold：单条版 get_by_code 走 SQL ci 校对（大小写
+    # 变形可命中），批量版改字典查找后须自行等价归一，否则变形大小写会
+    # 被误判「不是已存在的岗位」；岗位编码均为 ascii 小写蛇形，casefold 足够
+    roles = {
+        code.casefold(): role
+        for code, role in business_role_repository.list_by_codes(session, dimension_values).items()
+    }
+    normalized: list[tuple[ParamDefinition, str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for item in items:
+        definition = definitions.get(item.param_code)
+        if definition is None:
+            # 用户输入先行查库给 400；未注册编码出现在库里属数据与注册表漂移
+            raise BadRequestError(f"参数 {item.param_code} 未在系统中定义")
+        # ci 校对规则下大小写变形也能命中库，此后一律用库里的规范值：
+        # 注册表 get_spec 与快照字典均按精确键匹配，原始大小写入库会导致
+        # 取值链静默不命中（按错误参数算钱且无报错）
+        spec = get_spec(definition.param_code)
+        dimension = item.dimension_value
+        if spec.dimension_type == "NONE" and dimension != "":
+            raise BadRequestError(f"参数 {item.param_code} 不带维度，维度值须为空")
+        if spec.dimension_type == "BUSINESS_ROLE" and dimension:
+            role = roles.get(dimension.casefold())
+            if role is None:
+                raise BadRequestError(
+                    f"参数 {item.param_code} 的维度值 {dimension!r} 不是已存在的岗位"
+                )
+            dimension = role.role_code
+        if (
+            spec.dimension_type == "PRODUCT_CATEGORY"
+            and dimension
+            and dimension not in PRODUCT_CATEGORIES
         ):
-        try:
+            raise BadRequestError(
-            seq = max(seq, int(version_no.rsplit("-", 1)[1]))
+                f"参数 {item.param_code} 的维度值 {dimension!r} 不是合法的产品类别"
-        except (IndexError, ValueError):  # 手工造数容错：跳过不合规格的版本号
+            )
-            continue
+        value = validate_and_normalize(spec, item.value)
-    return f"{prefix}-{seq + 1:02d}"
+        key = (item.param_code, dimension)
+        if key in seen:
+            raise BadRequestError(
+                f"同一批次内重复提交参数 {item.param_code}（{dimension or '默认'}）"
+            )
+        seen.add(key)
+        normalized.append((definition, dimension, value))
+    return normalized
 
 
 def submit_change(
@@ -233,47 +281,21 @@ def submit_change(
             raise BadRequestError("指定生效日期不得早于今日")
 
         # 先全量校验、再写入：任何一项不合法整批拒绝（不留半批脏数据）
-        normalized: list[tuple[ParamDefinition, str, str]] = []
+        normalized = _normalize_items(session, payload.items)
-        seen: set[tuple[str, str]] = set()
-        for item in payload.items:
-            definition = param_repository.get_definition_by_code(session, item.param_code)
-            if definition is None:
-                # 用户输入先行查库给 400；未注册编码出现在库里属数据与注册表漂移
-                raise BadRequestError(f"参数 {item.param_code} 未在系统中定义")
-            spec = get_spec(item.param_code)
-            dimension = item.dimension_value
-            if spec.dimension_type == "NONE" and dimension != "":
-                raise BadRequestError(f"参数 {item.param_code} 不带维度，维度值须为空")
-            if (
-                spec.dimension_type == "BUSINESS_ROLE"
-                and dimension
-                and business_role_repository.get_by_code(session, dimension) is None
-            ):
-                raise BadRequestError(
-                    f"参数 {item.param_code} 的维度值 {dimension!r} 不是已存在的岗位"
-                )
-            if (
-                spec.dimension_type == "PRODUCT_CATEGORY"
-                and dimension
-                and dimension not in PRODUCT_CATEGORIES
-            ):
-                raise BadRequestError(
-                    f"参数 {item.param_code} 的维度值 {dimension!r} 不是合法的产品类别"
-                )
-            value = validate_and_normalize(spec, item.value)
-            key = (item.param_code, dimension)
-            if key in seen:
-                raise BadRequestError(
-                    f"同一批次内重复提交参数 {item.param_code}（{dimension or '默认'}）"
-                )
-            seen.add(key)
-            normalized.append((definition, dimension, value))
 
         try:
             batch = param_repository.create_batch(
                 session,
                 ParamChangeBatch(
-                    version_no=_next_version_no(session),
+                    # 版本号与三单据同口径：MAX FOR UPDATE 锁当日序号区间；
+                    # 残余并发冲突由下方 IntegrityError 分支翻译为可重试 400
+                    version_no=next_no(
+                        session,
+                        model=ParamChangeBatch,
+                        column_name="version_no",
+                        prefix=NO_PREFIX_PARAM,
+                        seq_width=2,
+                    ),
                     effective_date=effective,
                     change_type=payload.change_type,
                     remark=payload.remark,
@@ -299,10 +321,8 @@ def submit_change(
                         batch_id=batch.id,
                     ),
                 )
-            session.commit()
         except IntegrityError as exc:
-            # version_no 唯一键的并发冲突：当日序号是无锁查询后 +1，两名管理员
+            # version_no 唯一键的并发冲突：回滚并翻译为可重试的 400
-            # 并发提交会生成相同版本号 —— 回滚并翻译为可重试的 400
             session.rollback()
             raise BadRequestError("提交冲突（版本号生成重复），请重试") from exc
         session.commit()
@@ -503,7 +523,9 @@ def _preview_rate(
     聚合模板（营销经理 12.5%+5%）依赖月度团队数据，不支持单笔预览。
     """
     if payload.customer_type == "enterprise":
-        rate = take("enterprise.rate")
+        # 存储口径为 ‰ 数（如 "3"），除以 1000 转纯比例 —— performance_amount
+        # 按纯比例相乘，漏换算会把绩效金额放大 1000 倍（与业务员分支同防线）
+        rate = take("enterprise.rate") / 1000
         return rate, "企业户固定计提比例", None
 
     role_code = payload.business_role
@@ -519,7 +541,8 @@ def _preview_rate(
             "营销经理绩效为团队聚合口径（本团队 12.5% + 全公司 5%），不支持单笔预览"
         )
     if template == "TPL_INFO_SALES_FIXED":
-        rate = take("info.rate")
+        # ‰ 存储口径 → 纯比例，同企业户分支（不换算则绩效放大 1000 倍）
+        rate = take("info.rate") / 1000
         # 信息员的基数是本人销售额（无折算与阈值），覆盖默认基数
         return rate, "信息员：本人销售额 × 计提比例", Decimal(payload.revenue)
     if template == "TPL_SALESPERSON_DECAY":
@@ -591,7 +614,8 @@ def preview(session: Session, payload: ParamPreviewIn) -> ParamPreviewOut:
 
     start_ratio = take("payment.start.ratio")
     start_ok = formula.start_payment_ok(received, revenue, start_ratio)
-    weight_r = min(100, int(Fraction(received) / Fraction(revenue) * 100)) if revenue > 0 else 0
+    # R 钳制已提取为纯函数 clamp_weight_r（④ 核算与预览共用同一实现）
+    weight_r = formula.clamp_weight_r(received, revenue)
     weight = formula.payment_weight(weight_r)
     base_amount = after_barter if barter_applied else performance
     payable = to_decimal(Fraction(base_amount) * weight)

backend/app/services/personnel_service.py

@@ -30,6 +30,7 @@ from app.core.constants import (
 from app.core.exceptions import BadRequestError, NotFoundError
 from app.core.response import PageResult
 from app.models import BusinessRole, Personnel, PersonnelPlan, PersonnelRegion, User
+from app.models.personnel import PERSONNEL_STATUS_ACTIVE
 from app.repositories import business_role_repository, personnel_repository
 from app.schemas.personnel import (
     PersonnelCreateIn,
@@ -51,6 +52,22 @@ logger = logging.getLogger(__name__)
 _DELETE_BLOCKED = "存在团队成员、客户归属或业务归属引用，请改为离职而非删除"
 
 
+def ensure_active(session: Session, personnel_id: int, *, label: str) -> Personnel:
+    """归属人员必须存在且在职，返回人员行（业务/客户两侧归属校验共用）。
+
+    「不存在」与「已离职」合并为同一文案：人员 ID 是否有效不构成需要向
+    调用方区分的信息（同登录防枚举的思路）；label 落文案（负责/协助/归属）。
+    收口单点：在职状态值取 models.personnel.PERSONNEL_STATUS_ACTIVE，
+    此前 business/customer 两 service 各持常量与校验，仅靠注释维持同步。
+
+    :raises BadRequestError: {label}人员不存在或已离职
+    """
+    person = personnel_repository.get_by_id(session, personnel_id)
+    if person is None or person.status != PERSONNEL_STATUS_ACTIVE:
+        raise BadRequestError(f"{label}人员不存在或已离职")
+    return person
+
+
 def list_personnel(session: Session, query: PersonnelQuery) -> PageResult[PersonnelOut]:
     """分页查询人员（含离职）。"""
     rows = personnel_repository.list_personnel(

backend/app/services/product_service.py

@@ -29,6 +29,7 @@ from app.core.constants import (
     MODULE_PRODUCT,
     PRODUCT_CATEGORIES,
 )
+from app.core.db_errors import is_duplicate_entry
 from app.core.exceptions import BadRequestError, NotFoundError
 from app.core.response import PageResult
 from app.models import Product, User
@@ -44,9 +45,6 @@ from app.services.audit_service import AuditRecord, RequestMeta
 
 logger = logging.getLogger(__name__)
 
-# 唯一键冲突的 MySQL 错误码（pymysql 原始异常 args 首位）
-_ERR_DUP_ENTRY = 1062
-
 
 def _to_out(product: Product) -> ProductOut:
     """ORM 对象转响应模型。禁止把 ORM 对象直接当 response_model。"""
@@ -89,8 +87,7 @@ def _is_duplicate_entry(exc: IntegrityError) -> bool:
     只有 1062 是「已存在」语义，可转业务提示；其余完整性错误（外键、
     数据溢出等）语义未知，必须原样上抛交由全局处理器记 500，不能吞成 400。
     """
-    orig_args = getattr(exc.orig, "args", ())
+    return is_duplicate_entry(exc)
-    return bool(orig_args) and orig_args[0] == _ERR_DUP_ENTRY
 
 
 def _raise_if_duplicate(exc: IntegrityError) -> None:
@@ -281,13 +278,14 @@ def delete_product(
     operator: User,
     meta: RequestMeta | None = None,
 ) -> None:
-    """物理删除产品。
+    """物理删除产品（仅限误录数据，常规下架用停用）。
 
-    **被业务明细（发货/回款）引用的保护检查待业务数据表（V5）就位后补充**；
+    被业务明细/发货明细引用（RESTRICT 外键）的产品禁删：先 count_refs
-    当前先以 ``FOR UPDATE`` 锁行删除 —— V5 接入后，校验与删除之间的并发
+    给出可读 400（引导改走停用），校验与删除之间的并发引用由锁行 +
-    引用会因锁可见地失败，而非引用被静默悬空。
+    IntegrityError 兜底（customer_service.delete_customer 同款结构）。
 
     :raises NotFoundError: 产品不存在
+    :raises BadRequestError: 产品已被业务或发货明细引用
     """
     product = product_repository.get_by_id(session, product_id, for_update=True)
     with audit_service.audit(
@@ -302,8 +300,15 @@ def delete_product(
     ):
         if product is None:
             raise NotFoundError("产品不存在")
+        if product_repository.count_refs(session, product_id):
+            raise BadRequestError("产品已被业务或发货明细引用，无法删除（可改为停用）")
 
         product_name = product.product_name  # 固化：对象随删除失效
+        try:
             product_repository.delete(session, product)
             session.commit()
+        except IntegrityError as exc:
+            # 先查后删的并发窗口：新明细挂上了该产品，FK RESTRICT 兜底为 400
+            session.rollback()
+            raise BadRequestError("产品已被业务或发货明细引用，无法删除（可改为停用）") from exc
         logger.info("删除产品 | product_name=%s", product_name)

backend/app/services/rating_service.py

@@ -31,6 +31,7 @@ from app.core.constants import (
     ACTION_UPDATE,
     MODULE_RATING,
 )
+from app.core.db_errors import is_duplicate_entry
 from app.core.exceptions import BadRequestError, NotFoundError
 from app.models import CustomerRatingGrade, User
 from app.repositories import rating_repository
@@ -44,9 +45,6 @@ logger = logging.getLogger(__name__)
 _SCORE_FLOOR = Decimal("0")
 _SCORE_CEIL = Decimal("100")
 
-# 唯一键冲突的 MySQL 错误码（pymysql 原始异常 args 首位）
-_ERR_DUP_ENTRY = 1062
-
 
 def _to_out(grade: CustomerRatingGrade) -> RatingGradeOut:
     """ORM 对象转响应模型。分值 Decimal → str（分值红线出参口径）。"""
@@ -107,11 +105,11 @@ def _ensure_no_overlap(
 def _is_duplicate_entry(exc: IntegrityError) -> bool:
     """判断 IntegrityError 是否为 MySQL 1062（唯一键冲突）。
 
-    只有 1062 是「已存在」语义，可转业务提示；其余完整性错误（外键、
+    只有 1062 是「已存在」语义，可转业务提示；其余完整性错误语义未知，
-    数据溢出等）语义未知，必须原样上抛交由全局处理器记 500，不能吞成 400。
+    原样上抛 —— 由全局 IntegrityError handler 收敛为 400（通用文案），
+    500 只留给程序缺陷。
     """
-    orig_args = getattr(exc.orig, "args", ())
+    return is_duplicate_entry(exc)
-    return bool(orig_args) and orig_args[0] == _ERR_DUP_ENTRY
 
 
 def _raise_if_duplicate(exc: IntegrityError) -> None:
@@ -158,7 +156,7 @@ def create_grade(
         new_min = _to_decimal(payload.min_score)
         new_max = _to_decimal(payload.max_score)
         _ensure_score_range(new_min, new_max)
-        _ensure_no_overlap(rating_repository.list_all(session), new_min, new_max)
+        _ensure_no_overlap(rating_repository.list_all(session, for_update=True), new_min, new_max)
         if rating_repository.get_by_name(session, payload.grade_name) is not None:
             raise BadRequestError("该等级名称已存在")
 
@@ -219,7 +217,10 @@ def update_grade(
             raise NotFoundError("评级等级不存在")
 
         _ensure_no_overlap(
-            rating_repository.list_all(session), new_min, new_max, exclude_id=grade_id
+            rating_repository.list_all(session, for_update=True),
+            new_min,
+            new_max,
+            exclude_id=grade_id,
         )
         existed = rating_repository.get_by_name(session, payload.grade_name)
         if existed is not None and existed.id != grade_id:

backend/app/services/receipt_service.py

@@ -23,6 +23,7 @@
 """
 
 import logging
+from datetime import date
 from decimal import Decimal
 
 from sqlalchemy.exc import IntegrityError
@@ -35,6 +36,7 @@ from app.core.constants import (
     MODULE_RECEIPT,
     NO_PREFIX_RECEIPT,
 )
+from app.core.db_errors import is_duplicate_entry
 from app.core.exceptions import BadRequestError, NotFoundError
 from app.core.response import PageResult
 from app.models import Receipt
@@ -55,6 +57,9 @@ from app.services.no_generator import next_no
 
 logger = logging.getLogger(__name__)
 
+# 编号唯一键冲突后的重试次数（模式同 business_service._NO_RETRY）
+_NO_RETRY = 1
+
 
 def _to_out(row: tuple) -> ReceiptOut:
     """(receipt, business_no, shipment_no, ship_date) → 响应模型。
@@ -84,9 +89,7 @@ def _to_out(row: tuple) -> ReceiptOut:
 
 def _generate_no(session: Session) -> str:
     """生成回款批次号（HK 前缀；MAX+FOR UPDATE 与 1062 兜底见 no_generator）。"""
-    return next_no(
+    return next_no(session, model=Receipt, column_name="receipt_batch_no", prefix=NO_PREFIX_RECEIPT)
-        session, model=Receipt, column_name="receipt_batch_no", prefix=NO_PREFIX_RECEIPT
-    )
 
 
 def _ensure_shipment_of_business(
@@ -198,15 +201,24 @@ def create_receipt(
         ),
         meta=meta,
     ):
+        # 批次号唯一键冲突的重试整体收在审计上下文内（模式同
+        # business_service.create_business）：rollback 释放旧锁，重试前重新
+        # 锁业务行与生成批次号——成功/最终失败各只记一条审计，无递归
+        for attempt in range(_NO_RETRY + 1):
+            try:
                 if business is None:
                     raise NotFoundError("业务不存在")
                 if business.status != BUSINESS_STATUS_ACTIVE:
                     raise BadRequestError("业务已完成或已终止，禁止新增回款")
+                # 月结锁定拦截（2026-10-15 补充需求）：比需求原文「提示」取硬，
+                # 一期安全侧（策略点注释）；未指定日期时以当天月近似
+                from app.services import settlement_service
+
+                _lock_month = (payload.receipt_date or date.today()).strftime("%Y-%m")
+                settlement_service.ensure_month_not_locked(session, _lock_month)
                 shipment_no, ship_date = _ensure_shipment_of_business(
                     session, payload.shipment_id, payload.business_id
                 )
-
-        try:
                 receipt = receipt_repository.create(
                     session,
                     Receipt(
@@ -222,35 +234,28 @@ def create_receipt(
                 )
                 _recalc_totals(session, business)
                 out = _to_out((receipt, business.business_no, shipment_no, ship_date))
-            new_id = receipt.id
+                new_id, new_no = receipt.id, batch_no  # 固化：commit 后不碰 ORM
                 session.commit()
+                break
             except IntegrityError as exc:
                 session.rollback()
-            if _is_duplicate_entry(exc):
+                if _is_duplicate_entry(exc) and attempt < _NO_RETRY:
-                # 批次号撞唯一键的残余竞态：兜底重试一次（防无限重试掩盖死锁）
+                    business = business_repository.get_by_id(
-                return _retry_create(session, payload, operator=operator, meta=meta)
+                        session, payload.business_id, for_update=True
+                    )
+                    batch_no = _generate_no(session)
+                    continue
                 raise
 
         logger.info(
             "新增回款 | receipt_id=%s | no=%s | business_id=%s",
             new_id,
-            batch_no,
+            new_no,
             payload.business_id,
         )
         return out
 
 
-def _retry_create(
-    session: Session,
-    payload: ReceiptCreateIn,
-    *,
-    operator,
-    meta: RequestMeta | None,
-) -> ReceiptOut:
-    """批次号撞唯一键后的单次重试（重新锁行与生成编号，防死锁类缺陷掩盖）。"""
-    return create_receipt(session, payload, operator=operator, meta=meta)
-
-
 def update_receipt(
     session: Session,
     receipt_id: int,
@@ -286,8 +291,17 @@ def update_receipt(
         if receipt.settlement_status == SETTLEMENT_DONE:
             raise BadRequestError("已核算回款禁止修改")
         business = _ensure_business_writable(session, receipt.business_id, "修改")
-        # 返回值不取用：DTO 组装以 get_with_refs 重查为准（shipment 变更后同源）
+        # 月结锁定拦截：原月与新月都不得落入已锁定月份（改到账日=跨月搬数，
-        _ensure_shipment_of_business(session, payload.shipment_id, receipt.business_id)
+        # 只查新月会让「从锁定月改到未锁定月」绕过拦截）
+        from app.services import settlement_service
+
+        settlement_service.ensure_month_not_locked(session, receipt.receipt_date.strftime("%Y-%m"))
+        settlement_service.ensure_month_not_locked(session, payload.receipt_date.strftime("%Y-%m"))
+        # 校验返回的 (shipment_no, ship_date) 即新批次 DTO 所需 —— shipment_id
+        # 已被赋为 payload 新值，与重查 get_with_refs 同源，省一次三表 join
+        shipment_no, ship_date = _ensure_shipment_of_business(
+            session, payload.shipment_id, receipt.business_id
+        )
 
         receipt.receipt_date = payload.receipt_date
         receipt.shipment_id = payload.shipment_id
@@ -295,7 +309,7 @@ def update_receipt(
         receipt.is_barter = payload.is_barter
         receipt.remark = payload.remark
         _recalc_totals(session, business)
-        out = _to_out(receipt_repository.get_with_refs(session, receipt_id))
+        out = _to_out((receipt, business.business_no, shipment_no, ship_date))
         batch_no = receipt.receipt_batch_no
         session.commit()
         # commit 后不再触碰 ORM 属性（audit_service 约定）：批次号已固化
@@ -334,6 +348,10 @@ def delete_receipt(
         if receipt.settlement_status == SETTLEMENT_DONE:
             raise BadRequestError("已核算回款禁止删除")
         business = _ensure_business_writable(session, receipt.business_id, "删除")
+        # 月结锁定拦截：已锁定月份的回款是月结快照的源数据，不得删除
+        from app.services import settlement_service
+
+        settlement_service.ensure_month_not_locked(session, receipt.receipt_date.strftime("%Y-%m"))
 
         batch_no = receipt.receipt_batch_no
         receipt_repository.delete(session, receipt)
@@ -345,5 +363,4 @@ def delete_receipt(
 
 def _is_duplicate_entry(exc: IntegrityError) -> bool:
     """识别 MySQL 唯一键冲突（1062），与 business_service 同口径。"""
-    args = getattr(exc.orig, "args", ())
+    return is_duplicate_entry(exc)
-    return bool(args) and args[0] == 1062

backend/app/services/report_export.py

@@ -0,0 +1,657 @@
+"""报表 Excel 模板构建（纯函数，可单测）。
+
+版式（FR-032「导出模板围绕财务复核和领导签字设计」）：
+公司信息页眉 → 报表标题 → 筛选条件 → 导出时间/人/模板版本 → 表头 → 数据行
+→ 合计行 → 财务复核栏 / 领导签字栏 / 日期栏。
+
+精度红线：金额写 ``Decimal``（openpyxl 原生支持，不经 float）+
+``number_format='#,##0.00'``；合计在 Python 侧求和后两位收口，**不写
+Excel 公式**（避免打开时重算漂移与公式注入面）。文本列以 ``= + - @``
+开头时前置单引号，防公式注入。
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import ROUND_HALF_UP, Decimal
+from io import BytesIO
+
+from openpyxl import Workbook
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+from openpyxl.utils import get_column_letter
+
+from app.core.report_meta import (
+    BUSINESS_STATUS_LABELS,
+    CUSTOMER_TYPE_LABELS,
+    PRODUCT_CATEGORY_LABELS,
+)
+
+_HEADER_FILL = PatternFill("solid", fgColor="DDE3F0")
+_THIN = Side(style="thin", color="B0B7C3")
+_BORDER = Border(left=_THIN, right=_THIN, top=_THIN, bottom=_THIN)
+_TITLE_FONT = Font(size=14, bold=True)
+_COMPANY_FONT = Font(size=16, bold=True)
+_HEADER_FONT = Font(bold=True)
+_AMOUNT_FORMAT = "#,##0.00"
+_DATE_FORMAT = "YYYY-MM-DD"
+_FORMULA_PREFIXES = ("=", "+", "-", "@", "\t")
+
+
+
+@dataclass(frozen=True, slots=True)
+class _Column:
+    """列定义：key 取行 dict 字段，kind 决定单元格类型与格式。"""
+
+    key: str
+    title: str
+    kind: str  # text / amount / int / date / customer / category / status
+    width: float
+
+
+@dataclass(frozen=True, slots=True)
+class _Block:
+    """签字稿中的一个区块：独立表头、数据行与可选合计行。"""
+
+    title: str
+    columns: tuple[_Column, ...]
+    rows: list[dict]
+    total: dict | None = None
+    empty_text: str = "（无）"
+
+
+_COLUMNS: dict[str, tuple[_Column, ...]] = {
+    "personal-detail": (
+        _Column("business_no", "合同编号", "text", 20),
+        _Column("ship_date", "发货日", "date", 12),
+        _Column("receipt_date", "回款日", "date", 12),
+        _Column("payment_days", "回款天数", "int", 10),
+        _Column("product_category", "产品类别", "category", 14),
+        _Column("customer_type", "客户类型", "customer", 14),
+        _Column("role_name", "岗位", "text", 12),
+        _Column("rate_text", "计提比例", "text", 14),
+        _Column("weight_r", "支付权重R", "int", 10),
+        _Column("performance_amount", "绩效金额", "amount", 14),
+        _Column("payable_amount", "应付绩效", "amount", 14),
+    ),
+    "department-summary": (
+        _Column("manager_name", "经理团队", "text", 16),
+        _Column("member_name", "成员", "text", 14),
+        _Column("role_code", "岗位编码", "text", 12),
+        _Column("performance_sum", "绩效金额", "amount", 14),
+        _Column("payable_sum", "应付绩效", "amount", 14),
+        _Column("adjust_net", "调整净额", "amount", 14),
+        _Column("net_total", "净合计", "amount", 14),
+    ),
+    "business-stats": (
+        _Column("business_no", "业务编号", "text", 20),
+        _Column("business_date", "业务日期", "date", 12),
+        _Column("customer_name", "客户", "text", 22),
+        _Column("owner_personnel_name", "归属人", "text", 12),
+        _Column("status", "状态", "status", 10),
+        _Column("total_sale_amount", "销售额", "amount", 14),
+        _Column("total_ship_amount", "发货额", "amount", 14),
+        _Column("total_received_amount", "回款额", "amount", 14),
+        _Column("performance_amount", "绩效金额", "amount", 14),
+        _Column("payable_amount", "应付绩效", "amount", 14),
+    ),
+    "payment-stats": (
+        _Column("label", "回款天数区间", "text", 20),
+        _Column("receipt_amount", "回款金额", "amount", 16),
+        _Column("receipt_count", "回款笔数", "int", 10),
+        _Column("performance_amount", "绩效金额", "amount", 14),
+        _Column("payable_amount", "应付绩效", "amount", 14),
+        _Column("ledger_count", "台账行数", "int", 10),
+    ),
+}
+
+
+def build_workbook(
+    *,
+    code: str,
+    title: str,
+    filters: str,
+    rows: list[dict],
+    summary: dict | None,
+    buckets: dict | None,
+    template_version: str,
+    operator_name: str,
+    company_name: str,
+    department: dict | None = None,
+) -> bytes:
+    """构建并返回 xlsx 字节流（业务数据只读，不触碰数据库）。
+
+    部门汇总是签字对账文件，走单 sheet 分块版式；其余报表仍是单表 +
+    合计行。`department` 为 `department_summary` 的完整出参。
+    """
+    workbook = Workbook()
+    sheet = workbook.active
+    sheet.title = _sheet_name(code)
+    if code == "department-summary" and department is not None:
+        _write_department_document(
+            sheet,
+            department,
+            company_name=company_name,
+            title=title,
+            filters=filters,
+            template_version=template_version,
+            operator_name=operator_name,
+        )
+        buffer = BytesIO()
+        workbook.save(buffer)
+        return buffer.getvalue()
+
+    columns = _COLUMNS[code]
+    _write_header(sheet, columns, company_name, title, filters, template_version, operator_name)
+    if rows:
+        for row in rows:
+            _write_row(sheet, columns, row)
+    else:
+        sheet.append(["本筛选条件无数据"])
+        _merge_row(sheet, len(columns))
+    _write_total(sheet, columns, rows)
+    _write_signature(sheet, len(columns))
+    _autofit(sheet, columns)
+
+    # 回款统计附维度对比 sheet（客户类型/产品类别），与区间表共用页眉格式
+    if code == "payment-stats" and buckets:
+        for dim_key, dim_title in (
+            ("by_customer_type", "客户类型对比"),
+            ("by_product_category", "产品类别对比"),
+        ):
+            extra = workbook.create_sheet(dim_title)
+            _write_dimension_sheet(
+                extra,
+                dim_title,
+                company_name,
+                filters,
+                buckets.get(dim_key) or [],
+                template_version,
+                operator_name,
+            )
+
+    buffer = BytesIO()
+    workbook.save(buffer)
+    return buffer.getvalue()
+
+
+def _sheet_name(code: str) -> str:
+    return {
+        "personal-detail": "个人绩效明细",
+        "department-summary": "部门绩效汇总",
+        "business-stats": "业务统计",
+        "payment-stats": "回款统计",
+    }[code]
+
+
+def _write_header(
+    sheet,
+    columns: tuple[_Column, ...],
+    company_name: str,
+    title: str,
+    filters: str,
+    template_version: str,
+    operator_name: str,
+) -> None:
+    """页眉四行 + 表头行；返回后 sheet.max_row 即数据行起点。"""
+    _write_document_header(
+        sheet,
+        len(columns),
+        company_name,
+        title,
+        filters,
+        template_version,
+        operator_name,
+    )
+
+    sheet.append([column.title for column in columns])
+    header_row = sheet.max_row
+    for cell in sheet[header_row]:
+        cell.font = _HEADER_FONT
+        cell.fill = _HEADER_FILL
+        cell.border = _BORDER
+        cell.alignment = Alignment(horizontal="center", vertical="center")
+    sheet.freeze_panes = sheet.cell(row=header_row + 1, column=1)
+
+
+def _write_document_header(
+    sheet,
+    column_count: int,
+    company_name: str,
+    title: str,
+    filters: str,
+    template_version: str,
+    operator_name: str,
+) -> None:
+    """公司名/标题/筛选条件/导出信息四行（分块文档与单表共用）。"""
+    sheet.append([company_name])
+    _merge_row(sheet, column_count)
+    sheet.cell(row=1, column=1).font = _COMPANY_FONT
+    sheet.cell(row=1, column=1).alignment = Alignment(horizontal="left", vertical="center")
+
+    sheet.append([title])
+    _merge_row(sheet, column_count)
+    sheet.cell(row=2, column=1).font = _TITLE_FONT
+    sheet.cell(row=2, column=1).alignment = Alignment(horizontal="center", vertical="center")
+
+    sheet.append([f"筛选条件：{filters}"])
+    _merge_row(sheet, column_count)
+    sheet.append(
+        [
+            f"导出时间：{datetime.now():%Y-%m-%d %H:%M:%S} ｜ 导出人：{operator_name} ｜ "
+            f"模板版本：{template_version}"
+        ]
+    )
+    _merge_row(sheet, column_count)
+    sheet.append([])
+
+
+def _merge_row(sheet, column_count: int) -> None:
+    """合并当前行（公司名/标题/筛选行跨全表宽）。"""
+    row = sheet.max_row
+    if column_count > 1:
+        sheet.merge_cells(start_row=row, start_column=1, end_row=row, end_column=column_count)
+
+
+def _write_row(sheet, columns: tuple[_Column, ...], row: dict) -> None:
+    """数据行：按列类型写单元格（金额 Decimal、日期 date、文本防注入）。"""
+    values = []
+    for column in columns:
+        raw = row.get(column.key)
+        values.append(_cell_value(column, raw))
+    sheet.append(values)
+    for index, column in enumerate(columns, start=1):
+        cell = sheet.cell(row=sheet.max_row, column=index)
+        cell.border = _BORDER
+        if column.kind == "amount":
+            cell.number_format = _AMOUNT_FORMAT
+        elif column.kind == "date":
+            cell.number_format = _DATE_FORMAT
+
+
+def _cell_value(column: _Column, raw):
+    """单值转换：标签列转中文，文本列防公式注入。"""
+    if raw is None:
+        return None
+    if column.kind == "amount":
+        return raw if isinstance(raw, Decimal) else Decimal(str(raw))
+    if column.kind == "date":
+        return raw
+    if column.kind == "int":
+        return int(raw)
+    if column.kind == "customer":
+        return CUSTOMER_TYPE_LABELS.get(str(raw), str(raw))
+    if column.kind == "category":
+        return PRODUCT_CATEGORY_LABELS.get(str(raw), str(raw))
+    if column.kind == "status":
+        return BUSINESS_STATUS_LABELS.get(int(raw), str(raw))
+    return _safe_text(raw)
+
+
+def _safe_text(value) -> str:
+    """文本防公式注入：以 = + - @ 或制表符开头时前置单引号。"""
+    text = str(value)
+    return "'" + text if text.startswith(_FORMULA_PREFIXES) else text
+
+
+def _write_total(sheet, columns: tuple[_Column, ...], rows: list[dict]) -> None:
+    """合计行：金额列按行求和后两位收口（不写 Excel 公式）。
+
+    「合计」标签只写在第一个非金额列；其余非金额列留空——否则每遇到
+    一个文本列都会重复写一次标签，合计行会满屏「合计」。
+    """
+    if not rows:
+        return
+    totals = []
+    label_written = False
+    for column in columns:
+        if column.kind != "amount":
+            totals.append("合计" if not label_written else None)
+            label_written = True
+            continue
+        total = sum(
+            (
+                row.get(column.key)
+                for row in rows
+                if isinstance(row.get(column.key), (Decimal, int))
+            ),
+            Decimal("0"),
+        )
+        totals.append(total.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP))
+    sheet.append(totals)
+    for index, column in enumerate(columns, start=1):
+        cell = sheet.cell(row=sheet.max_row, column=index)
+        cell.font = _HEADER_FONT
+        cell.border = _BORDER
+        if column.kind == "amount":
+            cell.number_format = _AMOUNT_FORMAT
+
+
+def _write_signature(sheet, column_count: int) -> None:
+    """财务复核栏 / 领导签字栏 / 日期栏（FR-032 模板要素）。"""
+    sheet.append([])
+    sheet.append(["财务复核：________________", "", "日期：______年__月__日"])
+    sheet.append(["领导签字：________________", "", "日期：______年__月__日"])
+    for row_index in (sheet.max_row - 1, sheet.max_row):
+        sheet.cell(row=row_index, column=1).alignment = Alignment(horizontal="left")
+
+
+def _autofit(sheet, columns: tuple[_Column, ...]) -> None:
+    """列宽按定义表设置（CJK 按 2 字符宽，不用默认 8.43）。"""
+    for index, column in enumerate(columns, start=1):
+        sheet.column_dimensions[get_column_letter(index)].width = column.width
+
+
+def _write_dimension_sheet(
+    sheet,
+    title: str,
+    company_name: str,
+    filters: str,
+    rows: list[dict],
+    template_version: str,
+    operator_name: str,
+) -> None:
+    """维度对比 sheet（客户类型/产品类别），页眉筛选条件与主表一致。"""
+    columns = (
+        _Column("label", "维度", "text", 16),
+        _Column("receipt_amount", "回款金额", "amount", 16),
+        _Column("performance_amount", "绩效金额", "amount", 14),
+        _Column("payable_amount", "应付绩效", "amount", 14),
+        _Column("ledger_count", "台账行数", "int", 10),
+    )
+    _write_header(sheet, columns, company_name, title, filters, template_version, operator_name)
+    for row in rows:
+        _write_row(sheet, columns, row)
+    _write_total(sheet, columns, rows)
+    _write_signature(sheet, len(columns))
+    _autofit(sheet, columns)
+
+
+# ==== 部门汇总签字稿（FR-030 / FR-032）====
+
+_MEMBER_KIND_LABELS = {
+    "regular": "普通绩效",
+    "manager_personal": "经理个人户",
+    "adjustment": "仅调整单",
+}
+
+# 各块列数不同，统一按列号取最大宽度（签字稿打印时不挤在一起）
+_DEPARTMENT_WIDTHS = (30, 16, 22, 13, 13, 15, 18, 14, 14, 13)
+
+
+def _write_department_document(
+    sheet,
+    data: dict,
+    *,
+    company_name: str,
+    title: str,
+    filters: str,
+    template_version: str,
+    operator_name: str,
+) -> None:
+    """部门汇总签字稿：团队分成 → 全公司 5% → 对账 → 成员 → 未分配 → 签字栏。
+
+    全公司 5% 每位有月结聚合行的经理各计一次，合计在第二块展示；
+    团队块的调整净额仅供成员汇总核对。应发合计由后端 `reconciliation`
+    按聚合行口径算好（含分列舍入差），本函数只渲染。
+    """
+    params = data.get("params") or {}
+    team_text = params.get("team_text", "")
+    company_text = params.get("company_text", "")
+    teams = data.get("teams") or []
+    unassigned = data.get("unassigned") or []
+    company = data.get("company") or {}
+    reconciliation = data.get("reconciliation") or {}
+    company_share_count = int(company.get("company_share_count") or 0)
+
+    _write_document_header(
+        sheet, len(_DEPARTMENT_WIDTHS), company_name, title, filters, template_version, operator_name
+    )
+
+    _write_block(
+        sheet,
+        _Block(
+            "一、团队分成汇总",
+            (
+                _Column("seq", "序号", "int", 6),
+                _Column("manager_name", "经理团队", "text", 16),
+                _Column("manager_status_text", "状态", "text", 8),
+                _Column("member_count", "团队人数", "int", 9),
+                _Column("team_base", "团队基数", "amount", 13),
+                _Column("team_share_amount", f"团队分成（{team_text}%）", "amount", 15),
+                _Column("adjust_net", "调整净额（仅核对）", "amount", 16),
+                _Column("team_subtotal", "团队应发小计（含聚合分成）", "amount", 18),
+                _Column("frozen_amount", "月结冻结额", "amount", 14),
+            ),
+            [
+                {
+                    "seq": index,
+                    "manager_name": team["manager_name"],
+                    "manager_status_text": "在职" if team["manager_status"] == 1 else "离职",
+                    "member_count": team["member_count"],
+                    "team_base": team["team_base"],
+                    "team_share_amount": team["team_share_amount"],
+                    "adjust_net": team["adjust_net"],
+                    "team_subtotal": team["team_subtotal"],
+                    "frozen_amount": team["frozen_amount"],
+                }
+                for index, team in enumerate(teams, start=1)
+            ],
+            {
+                "manager_name": "合计",
+                "member_count": sum(team["member_count"] for team in teams),
+                "team_base": _sum_amount(team["team_base"] for team in teams),
+                "team_share_amount": _sum_amount(
+                    team["team_share_amount"] for team in teams
+                ),
+                "team_subtotal": _sum_amount(team["team_subtotal"] for team in teams),
+                # 未生成月结时全部为 None，合计也留空（不能显示 0.00 误导）
+                "frozen_amount": (
+                    _sum_amount(
+                        team["frozen_amount"]
+                        for team in teams
+                        if team["frozen_amount"] is not None
+                    )
+                    if any(team["frozen_amount"] is not None for team in teams)
+                    else None
+                ),
+            },
+            "（无团队）",
+        ),
+    )
+
+    _write_block(
+        sheet,
+        _Block(
+            f"二、全公司分成（每位有聚合行的经理各计一次，共 {company_share_count} 次）",
+            (
+                _Column("company_base", "全公司基数", "amount", 16),
+                _Column("company_share_pct", "分成比例", "text", 12),
+                _Column("company_share_amount", "单经理分成", "amount", 13),
+                _Column("company_share_count", "计入次数", "int", 10),
+                _Column("company_share_total", "分成合计", "amount", 14),
+            ),
+            [
+                {
+                    "company_base": company.get("company_base"),
+                    "company_share_pct": f"{company_text}%",
+                    "company_share_amount": company.get("company_share_amount"),
+                    "company_share_count": company_share_count,
+                    "company_share_total": company.get("company_share_total"),
+                }
+            ],
+        ),
+    )
+
+    _write_block(
+        sheet,
+        _Block(
+            "三、对账汇总",
+            (
+                _Column("item", "项目", "text", 30),
+                _Column("amount", "金额", "amount", 16),
+                _Column("note", "说明", "text", 40),
+            ),
+            [
+                {
+                    "item": "团队成员应付合计",
+                    "amount": reconciliation.get("team_member_payable_total"),
+                },
+                {
+                    "item": "未分配人员应付合计",
+                    "amount": reconciliation.get("unassigned_payable_total"),
+                },
+                {"item": "团队分成合计（分列）", "amount": reconciliation.get("team_share_total")},
+                {
+                    "item": f"全公司分成合计（{company_share_count} 次，分列）",
+                    "amount": reconciliation.get("company_share_total"),
+                    "note": "每位有聚合行的经理各计一次",
+                },
+                {
+                    "item": "聚合行舍入差",
+                    "amount": reconciliation.get("aggregate_rounding_diff"),
+                    "note": "分列舍入与聚合行一次舍入的差",
+                },
+                {
+                    "item": "调整净额合计（明细层）",
+                    "amount": reconciliation.get("adjust_net_total"),
+                },
+                {
+                    "item": "应发合计",
+                    "amount": reconciliation.get("payable_total"),
+                    "note": "上列各项之和",
+                },
+                {"item": "团队基数合计", "amount": reconciliation.get("team_base_total")},
+                {
+                    "item": "未分配绩效合计",
+                    "amount": reconciliation.get("unassigned_performance_total"),
+                },
+                {
+                    "item": "其他未展示基数",
+                    "amount": reconciliation.get("other_team_base"),
+                    "note": "筛选时含其他团队与全公司未分配",
+                },
+                {"item": "全公司基数", "amount": reconciliation.get("company_base")},
+            ],
+        ),
+    )
+
+    member_columns = (
+        _Column("manager_name", "经理团队", "text", 15),
+        _Column("personnel_name", "成员", "text", 12),
+        _Column("role_code", "岗位", "text", 10),
+        _Column("member_kind_text", "来源", "text", 13),
+        _Column("performance_sum", "绩效金额", "amount", 13),
+        _Column("payable_sum", "应付绩效", "amount", 13),
+        _Column("adjust_extra", "调整补发", "amount", 12),
+        _Column("adjust_deduct", "调整扣减", "amount", 12),
+        _Column("adjust_net", "调整净额", "amount", 12),
+        _Column("net_total", "净合计", "amount", 13),
+    )
+    member_rows = [
+        {
+            "manager_name": team["manager_name"],
+            "personnel_name": member["personnel_name"],
+            "role_code": member["role_code"],
+            "member_kind_text": _MEMBER_KIND_LABELS.get(
+                member["member_kind"], member["member_kind"]
+            ),
+            "performance_sum": member["performance_sum"],
+            "payable_sum": member["payable_sum"],
+            "adjust_extra": member["adjust_extra"],
+            "adjust_deduct": member["adjust_deduct"],
+            "adjust_net": member["adjust_net"],
+            "net_total": member["net_total"],
+        }
+        for team in teams
+        for member in team["members"]
+    ]
+    _write_block(
+        sheet,
+        _Block("四、团队成员明细", member_columns, member_rows, empty_text="（无成员）"),
+        sum_amounts=True,
+    )
+
+    unassigned_columns = (
+        _Column("personnel_name", "人员", "text", 14),
+        _Column("role_code", "岗位", "text", 10),
+        _Column("unassigned_reason", "未纳入原因", "text", 24),
+        _Column("performance_sum", "绩效金额", "amount", 13),
+        _Column("payable_sum", "应付绩效", "amount", 13),
+        _Column("adjust_extra", "调整补发", "amount", 12),
+        _Column("adjust_deduct", "调整扣减", "amount", 12),
+        _Column("adjust_net", "调整净额", "amount", 12),
+        _Column("net_total", "净合计", "amount", 13),
+    )
+    unassigned_rows = [
+        {
+            "personnel_name": row["personnel_name"],
+            "role_code": row["role_code"],
+            "unassigned_reason": row.get("unassigned_reason") or "",
+            "performance_sum": row["performance_sum"],
+            "payable_sum": row["payable_sum"],
+            "adjust_extra": row["adjust_extra"],
+            "adjust_deduct": row["adjust_deduct"],
+            "adjust_net": row["adjust_net"],
+            "net_total": row["net_total"],
+        }
+        for row in unassigned
+    ]
+    _write_block(
+        sheet,
+        _Block("五、未分配人员明细", unassigned_columns, unassigned_rows),
+        sum_amounts=True,
+    )
+
+    _write_signature(sheet, len(_DEPARTMENT_WIDTHS))
+    for index, width in enumerate(_DEPARTMENT_WIDTHS, start=1):
+        sheet.column_dimensions[get_column_letter(index)].width = width
+
+
+def _write_block(sheet, block: _Block, *, sum_amounts: bool = False) -> None:
+    """写一个区块：标题、表头、数据/空提示，以及自定义或自动合计。"""
+    sheet.append([block.title])
+    title_row = sheet.max_row
+    _merge_row(sheet, len(block.columns))
+    sheet.cell(row=title_row, column=1).font = _HEADER_FONT
+
+    sheet.append([column.title for column in block.columns])
+    header_row = sheet.max_row
+    for cell in sheet[header_row]:
+        cell.font = _HEADER_FONT
+        cell.fill = _HEADER_FILL
+        cell.border = _BORDER
+        cell.alignment = Alignment(horizontal="center", vertical="center")
+
+    if block.rows:
+        for row in block.rows:
+            _write_row(sheet, block.columns, row)
+    else:
+        sheet.append([block.empty_text])
+        _merge_row(sheet, len(block.columns))
+
+    if block.total is not None:
+        _write_custom_total(sheet, block.columns, block.total)
+    elif sum_amounts:
+        _write_total(sheet, block.columns, block.rows)
+    sheet.append([])
+
+
+def _write_custom_total(sheet, columns: tuple[_Column, ...], total: dict) -> None:
+    """写后端预计算的合计行（不自动求和，避免重复计入共享基数）。"""
+    values = []
+    for column in columns:
+        raw = total.get(column.key)
+        values.append(_cell_value(column, raw) if raw is not None else None)
+    sheet.append(values)
+    for index, column in enumerate(columns, start=1):
+        cell = sheet.cell(row=sheet.max_row, column=index)
+        cell.font = _HEADER_FONT
+        cell.border = _BORDER
+        if column.kind == "amount":
+            cell.number_format = _AMOUNT_FORMAT
+
+
+def _sum_amount(values) -> Decimal:
+    """金额列求和后两位收口（None 跳过）。"""
+    return sum((value for value in values if value is not None), Decimal("0")).quantize(
+        Decimal("0.01"), rounding=ROUND_HALF_UP
+    )

backend/app/services/role_service.py

@@ -1,17 +1,20 @@
 """角色管理业务编排。
 
-需求 2.5.1 只定义 admin / user 两个角色，本模块属用户确认的**自主完善**
+需求 2.5.1 定义 admin / user 两个登录角色；2026-10-15 复核审批补充需求
-（轻量版：不含权限点分配 —— `permissions` / `role_permissions` 表继续闲置，
+新增营销后勤/财务/领导三个职能登录角色（营销后勤与财务/领导分区于审批
-待业务方给出权限清单后再启用）。
+节点准入）。本模块仍为轻量版（不含权限点分配 —— `permissions` /
+`role_permissions` 表继续闲置，待业务方给出权限清单后再启用）。
 
 保护规则（都是系统自举与授权安全的最低防线，不只是界面体验）：
 
-- `admin` 角色**禁删禁停** —— `cli` 建管理员与 `require_admin` 判定都依赖
+- **内置角色禁删禁停**（`BUILTIN_ROLE_CODES`：admin / marketing_ops /
-  该编码存在，删除会使系统无法自举
+  finance / leader）—— `admin` 被删除会使系统无法自举（cli 建管理员与
+  `require_admin` 判定依赖）；财务/领导是审批节点准入锚点，被删会让
+  在途审批流失去可操作人
 - **有用户绑定的角色禁删** —— `user_roles` 外键是 CASCADE，直接删除会静默
   剥离绑定用户的权限，属安全与审计事故；删除前的校验走 `FOR UPDATE`
   锁行，堵住「校验与删除之间并发绑定」的窗口
-- `role_code` 创建后不可改 —— 它是授权判定（`ROLE_ADMIN` 常量按编码比对）的锚点
+- `role_code` 创建后不可改 —— 它是授权判定（`BUILTIN_ROLE_CODES` 白名单按编码比对）的锚点
 - 停用角色**不解除绑定、不影响既有授权**（授权判定只看编码、不看状态），
   但**不可再分配给用户**（`user_service._resolve_roles` 拦截）
 """
@@ -27,8 +30,8 @@ from app.core.constants import (
     ACTION_DISABLE,
     ACTION_ENABLE,
     ACTION_UPDATE,
+    BUILTIN_ROLE_CODES,
     MODULE_ROLE,
-    ROLE_ADMIN,
 )
 from app.core.exceptions import BadRequestError, ForbiddenError, NotFoundError
 from app.core.response import PageResult
@@ -177,10 +180,10 @@ def set_status(
 
     停用不解除用户绑定、不影响既有授权（授权判定只看编码不看状态），
     但该角色不可再分配给用户（`user_service._resolve_roles` 拦截）；
-    内置管理员角色不可停用。
+    内置角色不可停用。
 
     :raises NotFoundError: 角色不存在
-    :raises ForbiddenError: 试图停用内置管理员角色
+    :raises ForbiddenError: 试图停用内置角色
     """
     role = role_repository.get_by_id(session, role_id)
     verb = "启用" if status == 1 else "禁用"
@@ -198,8 +201,8 @@ def set_status(
         if role is None:
             raise NotFoundError("角色不存在")
 
-        if role.role_code == ROLE_ADMIN and status == 0:
+        if role.role_code in BUILTIN_ROLE_CODES and status == 0:
-            raise ForbiddenError("内置管理员角色不可停用")
+            raise ForbiddenError("内置角色不可停用")
 
         role.status = status
         out = _to_out(role, _user_count(session, role_id))
@@ -217,12 +220,12 @@ def delete_role(
 ) -> None:
     """删除角色。
 
-    内置管理员角色不可删除；仍有关联用户的角色不可删除（提示先解除绑定）。
+    内置角色不可删除（admin 与三个审批职能角色，见 BUILTIN_ROLE_CODES）；仍有关联用户的角色不可删除（提示先解除绑定）。
     查询走 `FOR UPDATE` 锁行：校验与删除之间若发生并发绑定，CASCADE 会把
     新绑定一并静默剥离 —— 锁行使并发绑定失败（可见）而非数据被吞（不可见）。
 
     :raises NotFoundError: 角色不存在
-    :raises ForbiddenError: 试图删除内置管理员角色
+    :raises ForbiddenError: 试图删除内置角色
     :raises BadRequestError: 角色下仍有绑定的用户
     """
     role = role_repository.get_by_id(session, role_id, for_update=True)
@@ -239,8 +242,8 @@ def delete_role(
         if role is None:
             raise NotFoundError("角色不存在")
 
-        if role.role_code == ROLE_ADMIN:
+        if role.role_code in BUILTIN_ROLE_CODES:
-            raise ForbiddenError("内置管理员角色不可删除")
+            raise ForbiddenError("内置角色不可删除")
 
         # user_roles 外键是 CASCADE：不拦截的话，删除会静默剥离绑定用户的权限
         user_count = _user_count(session, role_id)

backend/app/services/settlement_service.py

@@ -0,0 +1,636 @@
+"""月度结算服务（M3 ④）：生成快照 → 提交审批 → 通过即锁定。
+
+确认回款口径（澄清 #8 策略点，2026-10-16 暂定）：settlement_status=1 的
+**有效台账行**（is_active=1、settlement_id IS NULL=未被任何月结固化），
+按 settlement_month（回款日所在月）归集。答复后只改 ``_confirm_scope``。
+
+通过即锁定（status=3 终态）：锁定后源数据（回款/发货）写路径由
+``ensure_month_not_locked`` 拦截；调整走调整单（T6）。
+"""
+
+import logging
+from datetime import date
+from decimal import ROUND_HALF_UP, Decimal
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from app.core.constants import (
+    MODULE_SETTLEMENT,
+)
+from app.core.db_errors import is_duplicate_entry
+from app.core.exceptions import BadRequestError, NotFoundError
+from app.models import (
+    MonthlySettlement,
+    Personnel,
+    SettlementItem,
+    User,
+)
+from app.models.approval import APPROVAL_TYPE_MONTHLY_SETTLEMENT
+from app.models.performance_ledger import (
+    CALC_TYPE_MANAGER_AGGREGATE,
+    CALC_TYPE_RECEIPT,
+)
+from app.models.settlement import (
+    SETTLEMENT_STATUS_APPROVED,
+    SETTLEMENT_STATUS_DRAFT,
+    SETTLEMENT_STATUS_PENDING,
+    SETTLEMENT_STATUS_REJECTED,
+)
+from app.repositories import performance_ledger_repository, settlement_repository
+from app.schemas.settlement import (
+    SettlementDetailOut,
+    SettlementOut,
+    SettlementQuery,
+)
+from app.services import approval_service, audit_service, manager_share
+from app.services.approval_service import AuditRecord, RequestMeta
+from app.services.formula import manager_team_share, monthly_salary
+
+logger = logging.getLogger(__name__)
+
+# 审批对象类型引用（order_type=2 月结、3 调整单）
+_SETTLEMENT_ORDER_TYPE = APPROVAL_TYPE_MONTHLY_SETTLEMENT
+_SETTLEMENT_NOTE = "确认回款口径（#8 策略点）：settlement_status=1 的有效台账行按回款日归月"
+
+
+def generate(
+    session: Session,
+    month: str,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+) -> SettlementOut:
+    """生成月度结算快照（草稿）：按确认回款口径取有效台账行，按人汇总。
+
+    - 同月已有月结行（任意状态）时 400——一行一月，重生成走「驳回/草稿态
+      重新生成」（_release_previous_round 解绑回填后清明细重算）
+    - 经理聚合（calc_type=2）在生成时计算并落库（#12 参数化见
+      ``_build_manager_aggregates``）
+
+    本函数只做编排，各段独立私有函数（口径修改只动对应段）。
+    """
+    with audit_service.audit(
+        session,
+        operator=operator,
+        record=AuditRecord(
+            module=MODULE_SETTLEMENT,
+            action="生成月结",
+            summary=f"生成 {month} 月度结算快照",
+            request_data={"month": month},
+        ),
+        meta=meta,
+    ):
+        existing = settlement_repository.get_by_month(session, month)
+        _guard_regeneration(existing, month)
+        _release_previous_round(session, existing, month)
+
+        ledger_rows = _confirm_scope(session, month)
+        if not ledger_rows:
+            raise BadRequestError(f"{month} 无可结算的核算记录（先在台账完成核算）")
+
+        aggregate_rows = _build_manager_aggregates(session, ledger_rows, month)
+        settlement = _upsert_draft(session, existing, operator, month)
+        items, ledger_ids = _build_items(session, ledger_rows, aggregate_rows, month)
+
+        settlement_repository.replace_items(session, settlement.id, items)
+        _apply_totals(settlement, items)
+        settlement.snapshot_json = {"note": _SETTLEMENT_NOTE}
+        # 入结回填：台账行 settlement_id 是「未入结」防重判据（_confirm_scope），
+        # 不回填会让重生成把已固化行反复纳入；聚合行此刻已落库、id 可用
+        settlement_repository.update_ledger_settlement_id(session, ledger_ids, settlement.id)
+
+        # 出参在 commit 前固化（audit 约定：commit 后查询失败会把已生成的月结
+        # 记成失败审计，与库中事实相反）
+        session.flush()
+        detail = _detail_of(session, settlement)
+        session.commit()
+        logger.info("月结生成 | month=%s | items=%s", month, len(items))
+        return detail
+
+
+def _guard_regeneration(existing: MonthlySettlement | None, month: str) -> None:
+    """重生成准入：已审定 / 待审批不可重生成（草稿、已驳回放行）。"""
+    if existing is None:
+        return
+    if existing.status == SETTLEMENT_STATUS_APPROVED:
+        raise BadRequestError(f"{month} 已审定锁定，不可重新生成（调整走调整单）")
+    if existing.status == SETTLEMENT_STATUS_PENDING:
+        raise BadRequestError(f"{month} 有待审批的月结，不可重新生成")
+
+
+def _release_previous_round(
+    session: Session, existing: MonthlySettlement | None, month: str
+) -> None:
+    """释放上一轮固化标记（必须早于 _confirm_scope）。
+
+    台账行 settlement_id 回填后，「未入结」过滤会把它们永久排除在候选集外；
+    旧聚合行也要作废，否则本轮重建的聚合行与旧行重复计入。
+    """
+    if existing is None:
+        return
+    settlement_repository.clear_ledger_settlement_id(session, existing.id)
+    performance_ledger_repository.deactivate_month_aggregates(session, month)
+
+
+def _upsert_draft(
+    session: Session, existing: MonthlySettlement | None, operator: User, month: str
+) -> MonthlySettlement:
+    """新建或重置草稿头表（重生成时刷新提交人与状态）。"""
+    if existing is None:
+        settlement = MonthlySettlement(
+            settlement_month=month,
+            submitter_id=operator.id,
+            submitter_name=operator.username,
+            status=SETTLEMENT_STATUS_DRAFT,
+        )
+        return settlement_repository.add(session, settlement)
+    existing.submitter_id = operator.id
+    existing.submitter_name = operator.username
+    existing.status = SETTLEMENT_STATUS_DRAFT
+    return existing
+
+
+def _build_items(
+    session: Session, ledger_rows: list, aggregate_rows: list, month: str
+) -> tuple[list[SettlementItem], list[int]]:
+    """按人汇总生成明细行，返回 (明细, 本次入结的台账行 id 列表)。"""
+    by_person = _bucket_rows(ledger_rows + aggregate_rows)
+    items = [_item_of(session, bucket, month) for _, bucket in sorted(by_person.items())]
+    ledger_ids = [lid for bucket in by_person.values() for lid in bucket["ledger_ids"]]
+    return items, ledger_ids
+
+
+def _bucket_rows(rows: list) -> dict[tuple[int, int], dict]:
+    """台账行按 (人员, 核算类型) 维度分桶（冗余人读字段取首行）。"""
+    by_person: dict[tuple[int, int], dict] = {}
+    for row in rows:
+        key = (row.personnel_id, row.calc_type)
+        bucket = by_person.setdefault(
+            key,
+            {
+                "personnel_id": row.personnel_id,
+                "personnel_name": row.personnel_name,
+                "role_code": row.role_code,
+                "calc_type": row.calc_type,
+                "performance_sum": Decimal("0"),
+                "payable_sum": Decimal("0"),
+                "ledger_ids": [],
+                "is_probation": row.is_probation,
+            },
+        )
+        bucket["performance_sum"] += row.performance_amount or Decimal("0")
+        bucket["payable_sum"] += row.payable_amount or Decimal("0")
+        bucket["ledger_ids"].append(row.id)
+    return by_person
+
+
+def _item_of(session: Session, bucket: dict, month: str) -> SettlementItem:
+    """单条结算明细：月工资三口径净额、试用期说明与台账行引用列表。"""
+    person = session.get(Personnel, bucket["personnel_id"])
+    basic = person.salary_standard if person else None
+    mode = _salary_mode_of(session, bucket["role_code"], month)
+    net = (
+        monthly_salary(bucket["payable_sum"], basic, mode)
+        if person and person.is_probation != 1
+        else None
+    )
+    note = None
+    if person and person.is_probation == 1:
+        note = (
+            f"试用期绩效照算不发放；年累计超 {_probation_threshold(session, month)} 元部分"
+            "年底一次性结算"
+        )
+    return SettlementItem(
+        personnel_id=bucket["personnel_id"],
+        personnel_name=bucket["personnel_name"],
+        role_code=bucket["role_code"],
+        calc_type=bucket["calc_type"],
+        performance_sum=bucket["performance_sum"].quantize(Decimal("0.01"), rounding=ROUND_HALF_UP),
+        payable_sum=bucket["payable_sum"].quantize(Decimal("0.01"), rounding=ROUND_HALF_UP),
+        basic_amount=basic,
+        salary_mode=mode,
+        net_amount=(
+            net.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if net is not None else None
+        ),
+        is_probation=bucket["is_probation"],
+        probation_note=note,
+        snapshot_json={"ledger_ids": bucket["ledger_ids"]},
+    )
+
+
+def _apply_totals(settlement: MonthlySettlement, items: list[SettlementItem]) -> None:
+    """头表三合计固化（明细已两位小数，合计再 HALF_UP 收口）。"""
+    settlement.total_performance = sum((i.performance_sum for i in items), Decimal("0")).quantize(
+        Decimal("0.01"), rounding=ROUND_HALF_UP
+    )
+    settlement.total_payable = sum((i.payable_sum for i in items), Decimal("0")).quantize(
+        Decimal("0.01"), rounding=ROUND_HALF_UP
+    )
+    settlement.person_count = len({i.personnel_id for i in items})
+
+
+def submit(
+    session: Session,
+    settlement_id: int,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+) -> SettlementDetailOut:
+    """提交审批：开关分流（关=自动通过并锁定；开=待财务复核）。"""
+    with audit_service.audit(
+        session,
+        operator=operator,
+        record=AuditRecord(
+            module=MODULE_SETTLEMENT,
+            action="提交月结",
+            summary=f"提交月结 #{settlement_id}",
+            request_data={"settlement_id": settlement_id},
+        ),
+        meta=meta,
+    ):
+        settlement = settlement_repository.get_by_id(session, settlement_id, for_update=True)
+        if settlement is None:
+            raise NotFoundError("月结不存在")
+        if settlement.status not in (SETTLEMENT_STATUS_DRAFT, SETTLEMENT_STATUS_REJECTED):
+            raise BadRequestError("仅草稿或已驳回状态可提交")
+
+        try:
+            order = approval_service.submit_order(
+                session,
+                order_type=_SETTLEMENT_ORDER_TYPE,
+                ref_id=settlement.id,
+                refer_no=f"JS{settlement.settlement_month.replace('-', '')}",
+                submitter=operator,
+                # 月结明细在生成时已固化；提交时快照让复核者看到的是送审版本，
+                # 而不是审批期间若发生重生成后的内容
+                snapshot=approval_service.settlement_content(session, settlement.id),
+            )
+        except IntegrityError as exc:
+            # version_no 唯一键的并发冲突（提交前已锁月结行，此项理论不可达，
+            # 留作 DB 兜底）：审计上下文会统一回滚，这里只把 1062 翻译成
+            # 可重试的业务提示，其余完整性错误原样上抛
+            if is_duplicate_entry(exc):
+                raise BadRequestError("提交冲突（版本号生成重复），请重试") from exc
+            raise
+        settlement.approval_order_no = order.order_no
+        if order.status == SETTLEMENT_STATUS_APPROVED:
+            mark_locked(session, settlement, operator=operator)
+            logger.info("月结自动通过并锁定 | %s", settlement.settlement_month)
+        else:
+            settlement.status = SETTLEMENT_STATUS_PENDING
+
+        # 出参在 commit 前固化（audit 约定：commit 后查询失败会把已提交的
+        # 月结记成失败审计，与库中事实相反）
+        session.flush()
+        detail = _detail_of(session, settlement)
+        session.commit()
+        return detail
+
+
+def mark_locked(session: Session, settlement: MonthlySettlement, *, operator: User) -> None:
+    """审批通过钩子（由 approval_service.act 回调）：置已审定+锁定信息。"""
+    from datetime import datetime
+
+    settlement.status = SETTLEMENT_STATUS_APPROVED
+    settlement.locked_at = datetime.now()
+    settlement.locked_by = operator.username
+
+
+def mark_rejected(session: Session, settlement: MonthlySettlement, *, operator: User) -> None:
+    """审批驳回钩子：回草稿（可修改后重提）。
+
+    锁定信息一并清空：草稿态残留 locked_at/locked_by 会让详情页展示
+    「已锁定」的假象（历史缺陷路径下驳回前可能已被提前锁定）。
+    """
+    settlement.status = SETTLEMENT_STATUS_DRAFT
+    settlement.locked_at = None
+    settlement.locked_by = None
+
+
+def ensure_month_not_locked(session: Session, month: str) -> None:
+    """锁定拦截（回款/发货写路径调用）：单据日期所在月已审定 → 400。"""
+    settlement = settlement_repository.get_by_month(session, month)
+    if settlement is not None and settlement.status == SETTLEMENT_STATUS_APPROVED:
+        raise BadRequestError(f"{month} 已月结锁定，源数据不可修改（调整走调整单）")
+
+
+def get_detail(session: Session, settlement_id: int) -> SettlementDetailOut:
+    settlement = settlement_repository.get_by_id(session, settlement_id)
+    if settlement is None:
+        raise NotFoundError("月结不存在")
+    return _detail_of(session, settlement)
+
+
+def list_page(session: Session, query: SettlementQuery):
+    from app.core.response import PageResult
+    from app.schemas.settlement import SettlementOut
+
+    rows = settlement_repository.list_settlements(session, query)
+    total = settlement_repository.count_settlements(session, query)
+    return PageResult[SettlementOut](
+        records=[SettlementOut.model_validate(r) for r in rows],
+        total=total,
+        page_num=query.page_num,
+        page_size=query.page_size,
+    )
+
+
+# ---------- 内部 ----------
+
+
+def _confirm_scope(session: Session, month: str) -> list:
+    """确认回款口径（#8 策略点）：本月**单笔回款**的有效台账行（未入结）。
+
+    calc_type 必须限定单笔（1）：聚合行（2）也落同月台账、也会被回填
+    settlement_id，不排除会在重生成时与新聚合行重复计入。
+    """
+    from app.models import PerformanceLedger
+
+    return list(
+        session.execute(
+            select(PerformanceLedger)
+            .where(
+                PerformanceLedger.settlement_month == month,
+                PerformanceLedger.calc_type == CALC_TYPE_RECEIPT,
+                PerformanceLedger.is_active == 1,
+                PerformanceLedger.settlement_id.is_(None),
+            )
+            .order_by(PerformanceLedger.id)
+        ).scalars()
+    )
+
+
+def _manager_share_params(session: Session, month: str) -> manager_share.ManagerShareParams:
+    """薄委托 manager_share 共享模块：月结聚合与报表部门汇总同源取参。
+
+    迁移说明（2026-10-19）：实现原样迁至 manager_share，行为零变化；
+    参数按百分数存储（12.5 表示 12.5%），调用方不得再乘 100。
+    """
+    return manager_share.manager_share_params(session, month)
+
+
+def _collect_team_buckets(
+    session: Session, ledger_rows: list, include_manager_personal: bool
+) -> dict[int, dict]:
+    """薄委托 manager_share 共享模块：按经理采集团队业绩（行为零变化）。"""
+    return manager_share.collect_team_buckets(session, ledger_rows, include_manager_personal)
+
+
+def _aggregate_row(
+    session: Session,
+    manager,
+    bucket: dict,
+    company_base: Decimal,
+    share: manager_share.ManagerShareParams,
+):
+    """单经理聚合台账行（必须落库：月结 ledger_ids 与报表下钻的锚点）。"""
+    from app.models import PerformanceLedger
+
+    amount = manager_team_share(
+        bucket["performance"],
+        company_base,
+        team_pct=share.team_pct,
+        company_pct=share.company_pct,
+    )
+    member_names = "、".join(sorted(bucket["names"])) or "（无成员）"
+    return performance_ledger_repository.add(
+        session,
+        PerformanceLedger(
+            receipt_id=None,
+            calc_version=1,  # 聚合行无回款维度，版本恒 1（uk 含 NULL 不去重）
+            calc_type=CALC_TYPE_MANAGER_AGGREGATE,
+            business_id=bucket["business_id"],
+            business_no=bucket["business_no"],
+            personnel_id=manager.id,
+            personnel_name=manager.personnel_name,
+            role_code="sales_manager",
+            customer_type="personal",
+            product_category="mixed",
+            receipt_date=share.param_date,
+            # 比例原文取实际参数（勿硬编码默认值——参数调整后台账说明会失真）
+            rate_text=f"聚合:{share.team_text}%+{share.company_text}%",
+            converted_profit=None,
+            performance_amount=amount.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP),
+            barter_applied=0,
+            payable_amount=amount.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP),
+            settlement_month=share.month,
+            is_probation=1 if manager.is_probation == 1 else 0,
+            snapshot_json={
+                "team_base": str(bucket["performance"]),
+                "company_base": str(company_base),
+                "members": member_names,
+                "params_as_of": str(share.param_date),
+                "manager_personal_included": 1 if share.include_manager_personal else 0,
+                "note": (
+                    f"#12 参数化：基数{'含' if share.include_manager_personal else '不含'}"
+                    "经理个人户业绩；9.8 方案公式"
+                ),
+            },
+        ),
+    )
+
+
+def _build_manager_aggregates(session: Session, ledger_rows: list, month: str) -> list:
+    """按经理生成团队聚合行（calc_type=2）并落库。
+
+    #12 答复（2026-10-19）参数化：经理个人户业绩是否计入聚合基数由参数
+    ``manager.personal.included`` 决定（0=不计入默认，1=计入）；
+    经理 = 台账行归属人员经 manager_id 关联的 sales_manager 岗人员。
+    """
+    from app.repositories import business_role_repository
+
+    share = _manager_share_params(session, month)
+    managers = _collect_team_buckets(session, ledger_rows, share.include_manager_personal)
+    # 全公司基数：默认排除经理个人户行（#12 开关计入时不过滤）；共享口径单点
+    company_base = manager_share.company_base_of(ledger_rows, share.include_manager_personal)
+    aggregates: list = []
+    for manager_id, bucket in managers.items():
+        manager = session.get(Personnel, manager_id)
+        if manager is None:
+            continue
+        role = (
+            business_role_repository.get_by_id(session, manager.business_role_id)
+            if manager.business_role_id
+            else None
+        )
+        if role is None or role.role_code != "sales_manager":
+            continue  # 非营销经理的上级不参与聚合
+        aggregates.append(_aggregate_row(session, manager, bucket, company_base, share))
+    return aggregates
+
+
+def _month_end(month: str) -> date:
+    """薄委托 manager_share 共享模块：YYYY-MM → 所属月月末（取参锚点）。
+
+    保留包装：tests/unit/test_settlement_helpers.py 直接 import 本名字；
+    「补生成历史月份结果不随操作日漂移」的原因说明见 manager_share.month_end。
+    """
+    return manager_share.month_end(month)
+
+
+def _salary_mode_of(session: Session, role_code: str, month: str) -> str | None:
+    from app.services.param_service import resolve_snapshot
+
+    snapshot = resolve_snapshot(session, _month_end(month))
+    return snapshot.get("salary.basic.mode", role_code=role_code) or None
+
+
+def _probation_threshold(session: Session, month: str) -> Decimal:
+    from app.services.param_service import parse_fraction, resolve_snapshot
+
+    snapshot = resolve_snapshot(session, _month_end(month))
+    from app.services.formula import to_decimal
+
+    return to_decimal(parse_fraction(snapshot.get("probation.annual.threshold")))
+
+
+def _detail_of(session: Session, settlement: MonthlySettlement) -> SettlementDetailOut:
+    items = settlement_repository.list_items(session, settlement.id)
+    detail = SettlementDetailOut.model_validate(settlement)
+    from app.schemas.settlement import SettlementItemOut
+
+    detail.items = [SettlementItemOut.model_validate(i) for i in items]
+    return detail
+
+
+def create_adjustment(
+    session: Session,
+    payload,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+):
+    """新建调整单：开关分流（关=提交即生效留痕；开=待审批）。"""
+    from app.core.constants import NO_PREFIX_ADJUSTMENT
+    from app.models import AdjustmentOrder
+    from app.services.no_generator import next_no
+
+    amount = _adjustment_amount(payload)
+
+    person = session.get(Personnel, payload.personnel_id)
+    if person is None:
+        raise BadRequestError("调整人员不存在")
+
+    with audit_service.audit(
+        session,
+        operator=operator,
+        record=AuditRecord(
+            module=MODULE_SETTLEMENT,
+            action="新建调整单",
+            summary=f"调整单 {payload.direction} {payload.amount} 元（{person.personnel_name}）",
+            request_data=payload.model_dump(),
+        ),
+        meta=meta,
+    ):
+        order = AdjustmentOrder(
+            order_no=next_no(
+                session,
+                model=AdjustmentOrder,
+                column_name="order_no",
+                prefix=NO_PREFIX_ADJUSTMENT,
+            ),
+            settlement_month=payload.settlement_month,
+            personnel_id=payload.personnel_id,
+            personnel_name=person.personnel_name,
+            direction=payload.direction,
+            amount=amount,
+            reason=payload.reason.strip(),
+            submitter_id=operator.id,
+            submitter_name=operator.username,
+        )
+        session.add(order)
+        session.flush()
+
+        _wire_adjustment_approval(session, order, operator)
+        out = _adjustment_out(order)  # 出参在 commit 前固化（audit 约定）
+        session.commit()
+        logger.info("调整单创建 | order=%s | status=%s", out["order_no"], out["status"])
+        return out
+
+
+def _adjustment_amount(payload) -> Decimal:
+    """金额恒正校验（方向表达补发/扣减）。
+
+    列注释即「恒正」约定，负数会让方向语义反转、审批/报表按 direction
+    汇总出错；格式已由 schema 正则拦截，此处兜底转换 + 语义判定。
+    """
+    from decimal import InvalidOperation
+
+    try:
+        amount = Decimal(payload.amount)
+    except InvalidOperation as exc:
+        raise BadRequestError("调整金额格式非法（非负两位小数）") from exc
+    if amount <= 0:
+        raise BadRequestError("调整金额须大于 0（方向表达补发/扣减）")
+    return amount
+
+
+def _wire_adjustment_approval(session: Session, order, operator: User) -> None:
+    """开关分流与留痕统一交给 submit_order（关=自动通过留痕；开=待财务复核）。
+
+    **不得手工插 ApprovalStep**——``approval_steps.order_id`` 外键指向
+    approval_orders（不是 adjustment_orders），用调整单 id 落步必然外键
+    失败（历史缺陷：关开关时新建调整单不可用）。
+    """
+    from app.models.approval import APPROVAL_STATUS_APPROVED, APPROVAL_TYPE_ADJUSTMENT
+    from app.models.settlement import (
+        ADJUSTMENT_STATUS_EFFECTIVE,
+        ADJUSTMENT_STATUS_PENDING,
+    )
+
+    approval_order = approval_service.submit_order(
+        session,
+        order_type=APPROVAL_TYPE_ADJUSTMENT,
+        ref_id=order.id,
+        refer_no=order.order_no,
+        submitter=operator,
+        snapshot=approval_service.adjustment_content(session, order.id),
+    )
+    order.status = (
+        ADJUSTMENT_STATUS_EFFECTIVE
+        if approval_order.status == APPROVAL_STATUS_APPROVED
+        else ADJUSTMENT_STATUS_PENDING
+    )
+    session.flush()
+
+
+def _adjustment_out(order) -> dict:
+    """调整单出参（commit 前固化；expire_on_commit 关闭下也不依赖后置读取）。"""
+    return {
+        "id": order.id,
+        "order_no": order.order_no,
+        "status": order.status,
+        "personnel_name": order.personnel_name,
+        "amount": str(order.amount),
+        "direction": order.direction,
+    }
+
+
+def list_adjustments(session: Session) -> list[dict]:
+    """调整单列表（月份倒序）。"""
+    from sqlalchemy import select
+
+    from app.models import AdjustmentOrder
+
+    rows = (
+        session.execute(select(AdjustmentOrder).order_by(AdjustmentOrder.id.desc()).limit(200))
+        .scalars()
+        .all()
+    )
+    from app.models.settlement import adjustment_label  # noqa: F401
+
+    return [
+        {
+            "id": r.id,
+            "order_no": r.order_no,
+            "settlement_month": r.settlement_month,
+            "personnel_name": r.personnel_name,
+            "direction": r.direction,
+            "amount": str(r.amount),
+            "reason": r.reason,
+            "status": r.status,
+        }
+        for r in rows
+    ]

backend/app/services/shipment_service.py

@@ -23,7 +23,7 @@
 """
 
 import logging
-from decimal import Decimal
+from decimal import ROUND_HALF_UP, Decimal
 
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
@@ -35,6 +35,7 @@ from app.core.constants import (
     MODULE_SHIPMENT,
     NO_PREFIX_SHIPMENT,
 )
+from app.core.db_errors import is_duplicate_entry
 from app.core.exceptions import BadRequestError, NotFoundError
 from app.core.response import PageResult
 from app.models import Business, Shipment, ShipmentItem, User
@@ -56,6 +57,9 @@ from app.services.no_generator import next_no
 
 logger = logging.getLogger(__name__)
 
+# 编号唯一键冲突后的重试次数（模式同 business_service._NO_RETRY）
+_NO_RETRY = 1
+
 
 def _to_out(row: tuple[Shipment, str]) -> ShipmentOut:
     """(shipment, business_no) → 响应模型；金额出参 str。"""
@@ -95,12 +99,19 @@ def _build_item_rows(items: list[ShipmentItemIn]) -> list[ShipmentItem]:
 
     不信任前端传值（schema 亦无 amount 入参）——单价可空时行金额记 0，
     由用户在编辑中补价后重算；shipment_id 由 replace_items 统一回填。
+    乘积显式 quantize 两位固化（模式同 business_service._build_item_rows）：
+    数量(2位)×单价(4位) 可产 6 位小数，直写 DECIMAL(14,2) 会被 MySQL
+    静默舍入且回显漂移。
     """
     rows: list[ShipmentItem] = []
     for item in items:
         quantity = Decimal(item.quantity)
         sale_price = Decimal(item.sale_price) if item.sale_price is not None else None
-        amount = (quantity * sale_price) if sale_price is not None else Decimal("0")
+        amount = (
+            (quantity * sale_price).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+            if sale_price is not None
+            else Decimal("0.00")
+        )
         rows.append(
             ShipmentItem(
                 product_id=item.product_id,
@@ -117,9 +128,7 @@ def _build_item_rows(items: list[ShipmentItemIn]) -> list[ShipmentItem]:
 
 def _generate_no(session: Session) -> str:
     """生成发货单号（SH 前缀；MAX+FOR UPDATE 与 1062 兜底见 no_generator）。"""
-    return next_no(
+    return next_no(session, model=Shipment, column_name="shipment_no", prefix=NO_PREFIX_SHIPMENT)
-        session, model=Shipment, column_name="shipment_no", prefix=NO_PREFIX_SHIPMENT
-    )
 
 
 def _ensure_business_writable(session: Session, business_id: int, action: str) -> Business:
@@ -143,8 +152,7 @@ def _ensure_business_writable(session: Session, business_id: int, action: str) -
 
 def _is_duplicate_entry(exc: IntegrityError) -> bool:
     """识别 MySQL 唯一键冲突（1062），与 business/receipt_service 同口径。"""
-    args = getattr(exc.orig, "args", ())
+    return is_duplicate_entry(exc)
-    return bool(args) and args[0] == 1062
 
 
 def list_shipments(session: Session, query: ShipmentQuery) -> PageResult[ShipmentOut]:
@@ -220,12 +228,22 @@ def create_shipment(
         ),
         meta=meta,
     ):
+        # 单号唯一键冲突的重试整体收在审计上下文内（模式同
+        # business_service.create_business）：rollback 释放旧锁，重试前重新
+        # 锁业务行与生成编号——成功/最终失败各只记一条审计，无递归
+        for attempt in range(_NO_RETRY + 1):
+            try:
                 if business is None:
                     raise NotFoundError("业务不存在")
                 if business.status != BUSINESS_STATUS_ACTIVE:
                     raise BadRequestError("业务已完成或已终止，禁止新发货")
+                # 月结锁定拦截：发货日所在月已审定 → 源数据不可改（调整走调整单）
+                from app.services import settlement_service
+
+                settlement_service.ensure_month_not_locked(
+                    session, payload.ship_date.strftime("%Y-%m")
+                )
 
-        try:
                 shipment = Shipment(
                     shipment_no=shipment_no,
                     business_id=payload.business_id,
@@ -242,35 +260,28 @@ def create_shipment(
                 shipment.total_amount = total if total is not None else Decimal("0")
                 _recalc_totals(session, business)
                 out = _to_out((shipment, business.business_no))
-            new_id = shipment.id
+                new_id, new_no = shipment.id, shipment_no  # 固化：commit 后不碰 ORM
                 session.commit()
+                break
             except IntegrityError as exc:
                 session.rollback()
-            if _is_duplicate_entry(exc):
+                if _is_duplicate_entry(exc) and attempt < _NO_RETRY:
-                # 单号撞唯一键的残余竞态：兜底重试一次（防无限重试掩盖死锁）
+                    business = business_repository.get_by_id(
-                return _retry_create(session, payload, operator=operator, meta=meta)
+                        session, payload.business_id, for_update=True
+                    )
+                    shipment_no = _generate_no(session)
+                    continue
                 raise
 
         logger.info(
             "新增发货单 | shipment_id=%s | no=%s | business_id=%s",
             new_id,
-            shipment_no,
+            new_no,
             payload.business_id,
         )
         return out
 
 
-def _retry_create(
-    session: Session,
-    payload: ShipmentCreateIn,
-    *,
-    operator: User,
-    meta: RequestMeta | None,
-) -> ShipmentOut:
-    """单号撞唯一键后的单次重试（重新锁行与生成编号，防死锁类缺陷掩盖）。"""
-    return create_shipment(session, payload, operator=operator, meta=meta)
-
-
 def update_shipment(
     session: Session,
     shipment_id: int,
@@ -304,6 +315,11 @@ def update_shipment(
         if shipment is None:
             raise NotFoundError("发货单不存在")
         business = _ensure_business_writable(session, shipment.business_id, "编辑发货单")
+        # 月结锁定拦截：原发货日与新月都不得落入已锁定月份（改日期=跨月搬数）
+        from app.services import settlement_service
+
+        settlement_service.ensure_month_not_locked(session, shipment.ship_date.strftime("%Y-%m"))
+        settlement_service.ensure_month_not_locked(session, payload.ship_date.strftime("%Y-%m"))
 
         shipment.ship_date = payload.ship_date
         shipment.freight_amount = _amount_or_zero(payload.freight_amount)
@@ -312,7 +328,8 @@ def update_shipment(
         total = shipment_repository.sum_item_amount(session, shipment_id)
         shipment.total_amount = total if total is not None else Decimal("0")
         _recalc_totals(session, business)
-        out = _to_out(shipment_repository.get_with_business_no(session, shipment_id))
+        # business_id 创建时定死不可改挂，锁定的 business.business_no 与重查同源
+        out = _to_out((shipment, business.business_no))
         shipment_no = shipment.shipment_no
         session.commit()
         # commit 后不再触碰 ORM 属性（audit_service 约定）：单号已固化
@@ -351,6 +368,10 @@ def delete_shipment(
         if shipment is None:
             raise NotFoundError("发货单不存在")
         business = _ensure_business_writable(session, shipment.business_id, "删除发货单")
+        # 月结锁定拦截：已锁定月份的发货单是月结快照的源数据，不得删除
+        from app.services import settlement_service
+
+        settlement_service.ensure_month_not_locked(session, shipment.ship_date.strftime("%Y-%m"))
         if shipment_repository.count_receipt_refs(session, shipment_id):
             raise BadRequestError("已被回款批次指定，请先解除回款的批次指定")
 

backend/app/services/system_setting_service.py

@@ -0,0 +1,171 @@
+"""系统设置（公司信息）业务编排。
+
+单例行语义：整个系统恒一行（id=1，迁移种子保底）。logo 只存**相对路径**
+（uploads/logo/ 下固定名覆盖），文件不入库的理由：图片进数据库会让每次
+读取与备份放大传输，且无法独立替换；DB 只持有一行指针。
+
+logo 安全：后缀白名单 + magic bytes 双重校验（上传内容不可信，仅看文件名
+后缀可被伪造）；固定文件名落盘，**不使用上传方文件名**——杜绝路径拼接与
+覆盖任意文件。
+"""
+
+import logging
+from pathlib import Path
+
+from sqlalchemy.orm import Session
+
+from app.core.config import get_settings
+from app.core.constants import ACTION_UPDATE, MODULE_SYSTEM_SETTINGS
+from app.core.exceptions import BadRequestError, NotFoundError
+from app.models import SystemSetting, User
+from app.schemas.setting import SettingOut, SettingPublicOut, SettingUpdateIn
+from app.services import audit_service
+from app.services.audit_service import AuditRecord, RequestMeta
+
+logger = logging.getLogger(__name__)
+
+# magic bytes：PNG 固定 8 字节签名；JPEG 以 SOI + APP0/JFIF 起始
+_MAGIC = {
+    "png": b"\x89PNG\r\n\x1a\n",
+    "jpg": b"\xff\xd8\xff",
+}
+LOGO_MAX_BYTES = 2 * 1024 * 1024  # 2MB：页眉/登录页展示尺寸上限，防上传滥用
+
+SETTINGS_ID = 1  # 全系统单行主键
+
+
+def get_setting(session: Session) -> SystemSetting:
+    """取公司信息单行（种子保底 id=1；防御式兜底：极端环境下缺行则补建）。"""
+    setting = session.get(SystemSetting, SETTINGS_ID)
+    if setting is None:
+        setting = SystemSetting(id=SETTINGS_ID, company_name="衍水集团")
+        session.add(setting)
+        session.flush()
+    return setting
+
+
+def to_out(setting: SystemSetting) -> SettingOut:
+    """管理端出参（logo_url 带更新时间版本参数，替换图片后浏览器不再用旧缓存）。"""
+    return SettingOut(
+        company_name=setting.company_name,
+        logo_url=_logo_url(setting),
+    )
+
+
+def to_public_out(setting: SystemSetting) -> SettingPublicOut:
+    """匿名端点出参（白名单字段，独立 schema 见模块说明）。"""
+    return SettingPublicOut(
+        company_name=setting.company_name,
+        logo_url=_logo_url(setting),
+    )
+
+
+def _logo_url(setting: SystemSetting) -> str | None:
+    if not setting.logo_path:
+        return None
+    version = int(setting.update_time.timestamp()) if setting.update_time else 0
+    return f"/api/v1/system/settings/logo/public?v={version}"
+
+
+def update_company(
+    session: Session,
+    payload: SettingUpdateIn,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+) -> SettingOut:
+    """更新公司名称（审计留痕）。"""
+    with audit_service.audit(
+        session,
+        operator=operator,
+        record=AuditRecord(
+            module=MODULE_SYSTEM_SETTINGS,
+            action=ACTION_UPDATE,
+            summary=f"修改公司名称为「{payload.company_name}」",
+            request_data=payload.model_dump(),
+        ),
+        meta=meta,
+    ):
+        setting = get_setting(session)
+        setting.company_name = payload.company_name.strip()
+        session.commit()
+        return to_out(setting)
+
+
+def save_logo(
+    session: Session,
+    content: bytes,
+    ext: str,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+) -> SettingOut:
+    """上传 logo：校验 → 固定名覆盖落盘 → 更新相对路径（审计留痕）。
+
+    旧扩展名文件一并清理（logo.png 换 jpg 后残留文件会继续占盘）。
+    """
+    ext = ext.lower()
+    if ext not in _MAGIC:
+        raise BadRequestError("logo 仅支持 png/jpg 格式")
+    if len(content) > LOGO_MAX_BYTES:
+        raise BadRequestError("logo 文件不能超过 2MB")
+    if not content.startswith(_MAGIC[ext]):
+        raise BadRequestError("文件内容与扩展名不符（仅接受真实图片）")
+
+    with audit_service.audit(
+        session,
+        operator=operator,
+        record=AuditRecord(
+            module=MODULE_SYSTEM_SETTINGS,
+            action=ACTION_UPDATE,
+            summary="更新公司 logo",
+            request_data={"ext": ext, "size": len(content)},
+        ),
+        meta=meta,
+    ):
+        setting = get_setting(session)
+        old_path = setting.logo_path
+
+        # 先写新文件、commit 成功后再清旧扩展名（若把清理放在 commit 之前，
+        # commit 失败会让库指旧路径而旧文件已删——断链无补偿）；同扩展名
+        # 由写入覆盖，无需也不会误删新文件
+        target = _logo_dir() / f"logo.{ext}"
+        target.write_bytes(content)
+
+        setting.logo_path = f"logo/logo.{ext}"
+        session.commit()
+
+        old_ext = Path(old_path).suffix.lstrip(".") if old_path else None
+        if old_ext and old_ext != ext:
+            try:
+                _cleanup_old_logo(old_ext)
+            except OSError:
+                # 清理失败不影响本次更新（库与新文件均已生效）；若异常外抛，
+                # 成功的 logo 更新会被记成失败审计并 500 —— 审计与事实相反
+                logger.warning("旧 logo 清理失败（不影响本次更新）| ext=%s", old_ext, exc_info=True)
+        logger.info("更新公司 logo | size=%s ext=%s", len(content), ext)
+        return to_out(setting)
+
+
+def read_logo(session: Session) -> tuple[Path, str]:
+    """按库中记录定位 logo 文件，返回 (路径, 扩展名)。未上传抛 404。"""
+    setting = get_setting(session)
+    if not setting.logo_path:
+        raise NotFoundError("尚未上传 logo")
+    path = get_settings().upload_dir / setting.logo_path
+    if not path.is_file():
+        raise NotFoundError("logo 文件不存在，请重新上传")
+    return path, path.suffix.lstrip(".")
+
+
+def _logo_dir() -> Path:
+    directory = get_settings().upload_dir / "logo"
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def _cleanup_old_logo(old_ext: str) -> None:
+    if old_ext in _MAGIC:
+        old_file = _logo_dir() / f"logo.{old_ext}"
+        if old_file.exists():
+            old_file.unlink(missing_ok=True)

backend/pyproject.toml

@@ -35,6 +35,7 @@ dependencies = [
     "captcha>=0.6",
     "pillow>=11.0",
     "openpyxl>=3.1.5",
+    "python-multipart>=0.0.32",
 ]
 
 [dependency-groups]

backend/tests/README.md

@@ -1,6 +1,6 @@
 # 后端测试
 
-> AI摘要：本项目后端的测试用例清单与运行记录。按「基础设施层随实现即时测、业务模块整模块完成时统一测」分层组织。当前 603 个用例全绿（单元 381 / 集成 222）。
+> AI摘要：本项目后端的测试用例清单与运行记录。按「基础设施层随实现即时测、业务模块整模块完成时统一测」分层组织。当前 697 个用例全绿（2026-10-16，M3 增量批次后）。
 
 ## 一、测试约定
 
@@ -113,6 +113,71 @@ uv run pytest tests/integration -q   # 仅集成
 
 运行：`uv run pytest tests/integration/test_{businesses,shipments,receipts,ratings}.py -q` → **70 passed**（2026-10-13，连跑两次幂等）；全量回归 `uv run pytest -q` → **603 passed**（单元 381 / 集成 222）。
 
+### M3-core ④ 核算引擎 + 月度结算（2026-10-16 完成）
+
+| 文件 | 守什么 | 用例数 |
+| --- | --- | --- |
+| `tests/unit/test_formula.py`（扩） | R 钳制（向下取整/[0,100] 封顶封底/销售额 0 防御）、月工资三口径（INCLUDE 加/DEDUCT 减可负/EXCLUDE 仅绩效/基本缺失按 0/未知口径报错）、试用期年累计说明（未超无 note/超额精确差额）、经理 12.5%+5% 聚合（#12 暂口径） | +12 |
+| `tests/integration/test_calc.py` | **金标准双类别复算到分**（市政 4000 + 轨交 0 = 折算 4000；88/9000 约分原文落 rate_text；绩效 39.11；R=100 应付 39.11，DB 锚定）；**业务级一次性计提 #25**（同业务第二笔回款 repeated=True 仅登记进度不新增行）；已核算再核算 400；未指定批次 400；**成本缺失行毛利按 0 计**（折算保守 −3000、missing_cost=1）；负绩效照算不归零（折算 −2000）；准入（normal 403/marketing_ops 可用）；列表筛选；重算（finance 授权、v2 生效 v1 保留、reason 留痕、原因缺失 400、未核算重算 400、越权 403）；批量逐笔成败清单 | 13 |
+| `tests/integration/test_settlements.py` | 生成按人汇总+台账回填 settlement_id；无核算记录 400；**已审定月份重生成 400**；开关关闭提交即自动通过锁定（AP 单号/locked_at 回填）；**锁定后回款禁改 400**（M2 已核算禁改防线先于锁定拦截）；开关开启两节点流转（finance→leader）至锁定；#12 暂口径聚合不实现（items 按人汇总不聚合验证） | 6 |
+
+运行：`uv run pytest tests/integration/test_{calc,settlements}.py tests/unit/test_formula.py -q` → **32 passed**（2026-10-16）；全量回归见运行记录。
+
+### M3 增量批次（2026-10-16 完成：公司信息 / 二次分配录入 / 审批框架）
+
+| 文件 | 守什么 | 用例数 |
+| --- | --- | --- |
+| `tests/integration/test_settings.py` | 公司信息单行语义（PUT 只改名称不增行）；**public 端点无令牌 200 且字段白名单仅 2 项**（复用 admin schema 即泄漏面）；名称空 400；非 admin 403；logo 三重校验（伪造扩展名被 magic bytes 拦 / gif 拒 / 超 2MB 拒）；合法 png 上传回读 content-type；匿名上传 401；修改留审计日志 | 11 |
+| `tests/unit/test_secondary_allocation_schema.py` | 比例边界矩阵（0 拒 / 0.01-100 过 / 100.01 拒 / 负数拒 / **三位小数拒绝不静默舍入** / 非数字拒）；人员 ID 非正拒；**创建/编辑两入参的参与人去重**（uk 前置友好提示）；不同参与人合法 | 13 |
+| `tests/integration/test_secondary_allocation.py` | 带方案创建详情回显（**personnel_name 冗余固化**：离职后回显有名）；不建方案详情空且无 hint；合计满额 hint 只报合计无「余额」噪音；**离职人员参与 400**「分摊参与人员不存在或已离职」；终态业务禁改方案 400；编辑全量替换与空数组清空；**被方案引用人员禁删（RESTRICT→400）且方案回显有名**；删除业务后方案 CASCADE 随删、人员可删 | 9 |
+| `tests/integration/test_approval_flow.py` | **开关关闭（种子默认 0）：提单即两级「自动通过」留痕**（status=3、steps 两条 action=3、operator 记「系统」——留痕不断链）；方案为空不提单；开关开启两节点流转（1→财务通过→2→领导通过→3）；财务驳回整体 status=4 且意见留痕；驳回缺意见 400；**节点准入：领导/admin 不可代审财务节点（403）**；终态单重复操作 400；再编辑撤旧建新（旧单 status=5 + node=0/action=4 撤回留痕）；模块准入（normal/marketing_ops 403，finance/leader 200）。开关切换经参数变更批次端到端，不直改库；用后 conftest 恢复种子基线 | 11 |
+| `tests/unit/test_param_registry.py`（改） | 注册表 16→**18 项**（V6 首例 BOOL 两个审批开关）；**BOOL 校验边界专项**（0/1 过、true/2 拒） | +1 |
+| `tests/integration/test_schema_sync.py`（改） | 角色种子断言 2→**5 角色**（marketing_ops/finance/leader 入列） | 参数化 |
+
+运行：`uv run pytest tests/integration/test_{settings,secondary_allocation,approval_flow}.py tests/unit/test_secondary_allocation_schema.py -q` → **44 passed**（2026-10-16）；全量回归 `uv run pytest -q` → **697 passed**（基线 625 + 新增 72，5:10）。
+
+### 报表统计（M4 ⑤，2026-10-19 后端完成）
+
+| 文件 | 守什么 | 用例数 |
+| --- | --- | --- |
+| `tests/integration/test_reports.py` | 个人明细与台账逐笔一致 + **pageSize=1 时 summary 仍为全筛选合计**；部门汇总团队基数=成员绩效合计、分成按参数、无成员经理出 0 值行；**无台账经理挂上级不 500、仅有调整单人员并入团队/未分配、经理个人户开关两侧口径、按经理筛选不误判其他团队下属、对账恒等式**；**应发与月结 `total_payable` 对拍（两位经理各计一次 5%）、有调整单时等于月结+调整净额、筛选态只汇总展示团队**；导出页眉 ID→名称/中文标签、回款维度 sheet 透传筛选、**导出超限与取数异常的失败审计**、非法月份查询/导出均 400；回款统计 8 档桶恒在、空桶为 0、**二次分摊拆行时回款金额只计一次**；业务统计排除经理聚合行；普通用户 403 | 27 |
+| `tests/unit/test_report_helpers.py` | 区间分桶边界与 8 档编码唯一；标签覆盖全部枚举；Excel 模板页眉/签字栏/空数据/金额格式/合计/公式注入/维度 sheet/状态中文；**部门汇总签字稿五块顺序、零成员团队与未分配行、5% 按计入次数累计、应发合计取对账口径、聚合行舍入差单列、比例标题参数化** | 17 |
+| `tests/unit/test_month_validation.py` | 非法月份（`2026-13`/`2026-00`/`0000-01` 等）在报表、月结、调整单 schema 入口即拒绝；可选月份空串规范为 None | 17 |
+
+运行：`uv run pytest tests/integration/test_reports.py -q` → **27 passed**（2026-10-20 复核）；`uv run pytest tests/unit/test_report_helpers.py tests/unit/test_month_validation.py -q` → **34 passed**；全量 **862 passed**（2026-10-20，11:32）。
+
+**e2e 实跑（2026-10-20）**：`frontend/e2e/report_flow.py` 12/12 通过。回款统计改为展开目标桶后按**本次业务编号**定位下钻行（不依赖桶累计值，可重复运行）；另覆盖多桶同时展开、部门下钻筛选、打印截断提示、部门汇总打印五块结构。
+
+### 工作台（M4 ⑧，2026-10-19 完成）
+
+| 文件 | 守什么 | 用例数 |
+| --- | --- | --- |
+| `tests/integration/test_dashboard.py` | 权限 403 且文案「无权访问工作台」；总览绩效合计与台账一致 + 非法月份 400；待办（月结提交→待审批命中、回款未指定批次命中、**同步未建显式降级**）；风险预警（审批超时命中、**参数关闭后不产生条目**）；最近动态来源操作日志；**待办按角色过滤（财务/领导/多角色/admin）+ 真实流转；回款逾期命中与阈值参数生效；终止业务排除；`warnings.total` 不受展示上限截断；回款趋势跨月归属** | 11 |
+| `tests/unit/test_param_registry.py`（改） | 注册表 19→**22 项**（V10 预警规则三项）；编码集合与迁移种子一致 | 改 |
+
+运行：`uv run pytest tests/integration/test_dashboard.py -q` → **11 passed**（2026-10-19 code-review 修复回归）。
+
+**实施中发现并修复**：`alembic upgrade --sql` 在 Windows 控制台按 GBK 输出，重定向生成的 `V10__*.sql` 被 `test_schema_sync` 按 UTF-8 读取时抛 `UnicodeDecodeError`——导出命令须加 `PYTHONIOENCODING=utf-8 PYTHONUTF8=1`（已写入 backend/README）。
+
+### code-review 遗留 2 项（2026-10-20 完成：方案版本化 / 审批内容快照）
+
+| 文件 | 守什么 | 用例数 |
+| --- | --- | --- |
+| `tests/integration/test_approval_flow.py`（扩） | **提交时快照固化**（version_no=1、content_source=snapshot、方案比例/合计/余额与业务编号）；编辑方案为 80% 后新单 V2、旧单快照仍 50.00 且旧在途单撤回；**历史单无快照回退当前内容并标 live**（captured_at=null）；引用对象缺失且无快照 → missing；**方案版本化**：编辑后 history=[(1,0,50.00),(2,1,80.00)]、生效行仅 80.00；驳回后生效行为空但历史行保留（is_active=0） | +5 |
+| `tests/unit/test_approval_schema.py` | 对象类型筛选 1/2/3 均可、0/4 拒绝（修复原上界 `le=2` 导致调整单审批单无法筛选）；不传类型表示全部；驳回必须填意见、通过可不填 | 6 |
+| `tests/unit/test_approval_helpers.py` | **方案内容比较**（`business_service._plan_changed`）：完全相同/行序不同判未变、比例变/人员增减/同比例换人判已变、比例写法 `50` 与 `50.00` 等价、空方案对照 | 10 |
+| `tests/integration/test_secondary_allocation.py`（扩） | **同一会话内旧方案行随置历史同步刷新**（Core UPDATE 的会话同步策略退化为不刷新时，行对象会停留在 is_active=1 的过期内存值） | +1 |
+| `tests/integration/test_approval_flow.py`（扩） | **送审内容未变不重提**：方案与金额都没动 → 方案不新增版本、审批单不重提（旧单仍待财务复核）；**只改金额** → 方案版本不变但审批单 version_no+1 且新快照金额为改后值；**改方案比例** → 方案版本+1、审批单 version_no+1 且旧单撤回；**无在途单时保存仍提新单**（保守规则）；`pending_matches_snapshot` 四态（一致/不一致/无在途单/快照为 None） | +5 |
+
+### 审批单版本号并发防线（2026-10-21 完成：V12 唯一键 + 锁读取号）
+
+| 文件 | 守什么 | 用例数 |
+| --- | --- | --- |
+| `tests/integration/test_approval_version.py`（新） | **取号读最新已提交值**（两会话法：s1 锚定快照 + s2 提交 version_no=2 → s1 必须取到 3，守住「快照读 vs 当前读」根因）；**取号查询带 FOR UPDATE 且不含聚合**（事件钩子抓真实 SQL——MySQL 官方不允许聚合函数携带锁子句）；**唯一键生效**（重复 (order_type, ref_id, version_no) 直插撞 1062）；**编辑路径冲突收敛为 400** 且业务数据不写坏（monkeypatch `_next_version` 恒返回 1）；**正常路径版本号仍递增**（1→2→3） | +5 |
+| `tests/unit/test_models.py`（扩） | 审批单唯一键覆盖 (order_type, ref_id, version_no) 三列且约束名与迁移 DDL 一致 | +1 |
+
+运行（2026-10-22，容器恢复后）：`tests/integration/test_approval_version.py` + `test_dashboard.py` → **16 passed**；全量 `uv run pytest -q` → **897 passed（12:02）**；`uv run ruff check .` 绿、前端 `pnpm type-check` 绿。首次全量跑出两处**测试代码**适配（非产品缺陷）：① 工作台 `_insert_approval` 用同一 `(order_type=2, ref_id=0)` 连插两张单，撞 V12 新唯一键 → 每张单改给不同 `ref_id`；② 新用例跨模块引用 `switched_on` 夹具（pytest 夹具只在定义模块与 conftest 可见，报 fixture not found）→ 用 `_set_switch` 本地重建。
+
 ## 三、运行记录
 
 | 日期 | 范围 | 用例数 | 结果 | 备注 |
@@ -126,11 +191,46 @@ uv run pytest tests/integration -q   # 仅集成
 | 2026-10-13 | 业务数据集成四文件 | 70 | ✅ 通过（54.73s，连跑两次幂等） | **业务数据管理（后端接口）完成**后统一编写（业务 25/发货 15/回款 16/评级 14）。全量回归 603 例通过 |
 | 2026-10-13 | 全量回归 + 两个 e2e | 605 | ✅ 605 passed（208s）；e2e 基础数据 13 步 + 业务全链路 16 步全过 | **M2 收尾**：删除保护补齐（+2 用例）后最终回归 605；e2e 期间修复三处缺陷（见下表），均已用例锁定 |
 | 2026-10-13 | 全部 | 603 | ✅ 通过（5:17） | **T11 全量回归**（单元 381 / 集成 222），含本模块 70 例 |
+| 2026-10-15 | 全量回归 + e2e | 639 | ✅ 全部通过 | **code-review 32 条修复后全量回归**（新增 34 例：跨位宽 3 / 参数预览与维度 3 / 审计重试 2 / 终态编辑与 quantize 2 / 产品保护 2+6 / 评级锁 1 / formula 钳制 1 等）。e2e 冒烟：登录 8 项 + 系统管理 13 项 + 基础数据 13 步 + 业务全链路 16 步全过（拦截器/正则收口/params 分页改造后复跑） |
+| 2026-10-17 | M3-core 定点 | 32 | ✅ 通过 | **④ 核算引擎+月结完成**（calc 13 / settlements 6 / formula 扩 12 / schemas 等）。金标准复算到分；重算版本链；月结锁定与审批联动 |
+| 2026-10-17 | 全量回归 | 701+N | ✅ 全部通过 | **M3-core 收尾回归**（T1-T6：V7 四表+核算+月结+调整单；前端台账/月结两页 order17/18）。e2e 补 calc_settlement_flow 待下批 |
+| 2026-10-16 | 全量回归 + 7 个 e2e | 697 | ✅ 697 passed（5:10）；e2e 七脚本全过 | **M3 增量批次完成**（+72 例：settings 11 / 分配 schema 13+集成 9 / 审批 11 / registry 与 schema_sync 断言扩充等）。e2e：登录 8 + 系统管理 13 + 基础数据 12 + 业务 16 + 参数 7 步回归全过；**新增 settings_flow 4 步 / secondary_allocation_flow 6 步**（首跑即抓出 public 缓存与 logo 清理两处缺陷，见下表） |
+| 2026-10-19 | M3 定点（calc/settlements） | 34 | ✅ 通过（55s） | **code-review P0+P1 修复中**：经理聚合比例/调整单即生效/进度登记重算 400/财务节点不提前锁定/锁定拦截三路径/回填与聚合落库/月末取参（+新增 `test_settlement_helpers` 5 例、`test_calc_helpers` 4 例锁定 `_q2` HALF_UP） |
+| 2026-10-19 | 全量回归 | 780 | ✅ 780 passed（8:53） | **M3 code-review 21 项修复后全量回归**（P0 算错钱/不可用 6 项 → P1 锁定不变量与双轨漂移 7 项 → P2 健壮性 6 项 → calc_receipt 重构；新增回归约 20 例，含跨会话并入的 #12 聚合基数开关用例）。type-check 绿；e2e calc_settlement_flow 仍待补 |
+| 2026-10-19 | 拆行收口批次 | 全量 788 | ✅ 788 passed（9:20） | **2026-10-19 业务答复落实完成**：#14 首日取整 10‰（公式段/锚点不变，用例反转）；#12 单笔侧开关消费（1=业务员递减计提）；**二次分摊拆行**（参与人份额+负责人余额守恒，uk 三列版）；权限分层（params 查看放开/写仅 admin）；V8 迁移（审批开关默认开/撤试用期参数/增基数开关）。定点：calc 20 / settlements 13（含 #12 开关两档金标准 6.84→24.34）/ businesses 30（保存侧+3）/ formula 35。e2e calc_settlement_flow 交接并行会话 |
+| 2026-10-19 | **报表统计修复回归** | 全量 847 | ✅ 847 passed（10:13） | **M4 报表 code-review 15 项修复后全量回归**（后端 8 + 前端 7）：归属三集合/调整单全量并入/经理个人户拆分/对账出参、分块签字稿导出、导出审计覆盖取数、筛选页眉 ID→名称、月份校验 400、岗位只读选项。报表集成 24 / 报表单元 16 / 月份校验 17。type-check + build 绿；e2e `report_flow.py` 扩至 12 步，待 `E2E_ADMIN_PASSWORD` 实跑 |
+| 2026-10-19 | 全部 | 852 | ✅ 852 passed（9:17） | **M4 ⑧ 工作台完成**（四区块实时聚合 + ECharts 5.6 前端 + V10 预警参数三项；新增 5 例；参数注册表 19→22；同步模块显式降级）。期间修复：alembic `--sql` 导出 GBK 导致 schema 同步误报 |
+| 2026-10-19 | **code-review 修复回归** | 全量 862 | ✅ 862 passed（9:36） | **M4 工作台 + 报表 3 必须 + 8 建议修复**：普通用户落地页/守卫（报表集成 27、工作台集成 11、报表单元 17，新增 10 例）；部门汇总 5% 按计入次数累计并与月结 `total_payable` 对拍、聚合行舍入差；工作台待办按角色过滤、逾期命中与阈值生效、终止业务排除、`warnings.total` 截断、趋势跨月归属。ruff 绿；type-check + build 绿 |
+| 2026-10-20 | e2e 全链路 | — | ✅ login 8 / system 13 / role_home 4 / report 12 / calc_settlement 8 | 重启后端加载新代码后实跑：普通用户落地页与受限页回退、报表四页/导出/打印、核算与月结链路全过。`report_flow` 回款统计改为展开目标桶后按本次业务编号定位明细，不依赖桶累计值，可重复运行 |
+| 2026-10-20 | 全量回归 | 862 | ✅ 862 passed（11:32） | **工作台/报表修复提交后的全量复核**；e2e 三脚本复跑：role_home 4/4、report 12/12、calc_settlement 8/8；calc 审批开关已还原为 1，无 `e2e_role_*` 残留 |
+| 2026-10-20 | code-review 遗留 2 项 | 全量 875 | ✅ 875 passed（12:13） | **方案版本化 + 审批内容快照**（V11 迁移）：审批单 `version_no`/`snapshot_json`，方案行 `is_active` 版本化；编辑/驳回不再物理删方案；历史单无快照时 live 回退并显式标注。新增集成 7 + 单元 6；定点审批/月结/核算/业务/报表全绿；ruff 与 type-check/build 绿 |
+| 2026-10-20 | 遗留项自评审收口 | 全量 891 | ✅ 891 passed（10:23） | **列表 defer 快照列**（审批列表/工作台待办/超时预警）+ **送审内容未变不重提、方案未变不新增版本**（两个 version_no 语义解耦）+ **月结提交加行锁**。新增单元 10 + 集成 5；单元 525、集成定点 96 全绿 |
+| 2026-10-19 | 单元全量 + 报表定点 | 484 | ✅ 484 passed（45.94s）；报表单元 11 例 0.70s | **M4 报表模块收尾**（前端四页/打印视图/导出与单元测试补齐）。ruff 绿；前端 `pnpm type-check` 绿。报表集成 7 例记录见上节 |
+| 2026-10-19 | 全部 | 806 | ✅ 806 passed（7:59） | **M4 ⑤ 报表统计全量回归**（报表新增 18 例：集成 7 + 单元 11；另含并行会话并入的 M3 前端修复与字体合规）。ruff 绿。e2e：`calc_settlement_flow` 8 步由并行会话跑通；`report_flow.py` 待 `E2E_ADMIN_PASSWORD` 运行 |
 
 ## 四、测试发现并修复的缺陷
 
 | 日期 | 缺陷 | 影响 | 处理 |
 | --- | --- | --- | --- |
+| 2026-10-19 | 部门汇总导出/打印只展平成员行 | 团队分成、全公司 5% 块、未分配人员、零成员团队全部缺失——**签字稿合计小于应发**，财务按签字稿复核会漏发经理分成与未分配绩效 | 导出改为单 sheet 分块签字稿（团队/公司/对账/成员/未分配）+ 打印五块；应发公式与对账块由后端 Decimal 计算 |
+| 2026-10-19 | `_member_rows` 直接 `member_map[pid]` 索引 | 无台账行的营销经理自身挂上级时 KeyError → **部门汇总接口与导出 500**（当月完全无台账也会触发） | 归属只从 member_map/adjustments 生成；`manager_role` 覆盖所有成员引用的上级 |
+| 2026-10-19 | 生效调整单只并入有台账人员 | 只有调整单、当月无回款的人被静默丢弃——补发/扣减金额不出现，**按报表发放会少发** | 调整单人员补零值成员后参与团队/未分配归属；每人调整净额只计一次 |
+| 2026-10-19 | 经理个人户成员行取该人全部绩效 | 团队基数只含个人户行，成员行却含普通行——**基数≠成员合计，同一笔业绩在成员行与未分配重复** | 普通行与个人户分行记账；经理成员行只取个人户金额，普通行留在上级团队/未分配 |
+| 2026-10-19 | 导出取数与超限校验在审计上下文之外 | 超限 400 与取数异常**不留失败日志**，与 M4 计划 T12「导出 400/失败审计」不符 | `_export_payload` 移入 `with audit`；静态标题映射（AuditRecord frozen） |
+| 2026-10-19 | 月份只校验长度 | `2026-13` 传到 `calendar.monthrange` 抛 ValueError → **500**；导出手工构造模型抛裸 ValidationError 同样 500 | 新增 `core/month.py`（格式+01-12+年份）；四类 query、月结、调整单接入；导出 ValidationError 转 400 |
+| 2026-10-20 | 审批类型筛选上界写死 2 | `ApprovalQuery.order_type` 为 `le=2`：调整单（order_type=3）审批单在列表无法筛选，只能翻全量 | 上界改 3；单元用例锁定 1/2/3 与越界拒绝 |
+| 2026-10-20 | 编辑业务时送审快照取旧汇总 | `update_business` 中 `_recalc_totals` 在提单之后，快照里的销售额/成本额会固化上一版本金额 | 汇总重算移到提单之前；快照用例断言送审内容与本次编辑后方案一致 |
+| 2026-10-20 | 快照金额把「空」写成 0.00 | 业务尚无成本时 `total_cost_amount=None` 被文本化成 `0.00`，复核者会把「无成本」误读成「成本为零」 | `_amount_text(None)` 保留为空，前端显示「—」 |
+| 2026-10-20 | 每次保存带方案的业务都刷出版本与审批留痕 | 只改备注、方案一字未动，也会「置历史+新增版本+撤回旧单+提新单」，方案历史与审批留痕被噪音淹没，两个 `version_no` 语义混同 | 判据统一为**送审内容**：方案未变不新增版本行；在途单送审内容一致则不重提（`pending_matches_snapshot`，只比 `data`） |
+| 2026-10-20 | 三处列表查询整列拉快照 | 审批单列表、工作台待办、审批超时预警都用 `select(ApprovalOrder)` 取全列，快照 JSON 可达上百 KB，翻页与工作台负担随快照体积线性放大 | 三处加 `defer(ApprovalOrder.snapshot_json)`（沿用操作日志列表排除 `request_data` 的既有模式） |
+| 2026-10-20 | 月结提交未锁行 | 并发/双击提交同一月结时两次 `_next_version` 可能算出同一 `version_no`，送审次序失真 | `settlement_repository.get_by_id` 加 `for_update` 参数，提交路径锁行 |
+| 2026-10-21 | 审批单 `version_no` 无唯一约束 | 应用层取号即使正确，并发下 DB 层无兜底；且唯一键是「一个对象至多一张在途单」红线之外版本语义的最后防线 | V12 迁移加 `uk_approval_orders_order_type_ref_version (order_type, ref_id, version_no)`；加键前先重排存量重复分组（V11 把存量一律置 1 而 V11 前重提是新建行，直接加键必报 1062） |
+| 2026-10-21 | `_next_version` 是快照读 | 请求级鉴权与业务共用同一 DbSession，鉴权的普通 SELECT 已锚定 REPEATABLE READ 快照——父行锁只串行化写入时刻、**不刷新快照**，并发提单的 MAX 停在请求开始时刻 → 版本号重复 | 取号改锁读（`select(version_no)...with_for_update()`，当前读），最大值 Python 侧算；**不能用聚合 + FOR UPDATE**——MySQL 官方不允许聚合函数携带锁子句 |
+| 2026-10-21 | `act()` 驳回清空方案的注释与行为相反 | 注释写「清空该业务的二次分配行…如需保留历史版本，在 ④ 设计时演进」，而 V11 已实现 append-only（只置 `is_active=0` 行不删）——误导后来者按旧语义改代码 | 注释改为「置历史不删行，历史方案可回溯」 |
+| 2026-10-19 | 前端报表五处状态缺陷 | 打印超限判定恒假（静默截断）、部门下钻 query 未读取、回款多桶共用一个 drill 状态（面板串行）、summary 在请求序号守卫前写入（合计串号）、e2e 全页行数选择器必失败 | 分别修正判定/读取 query/按桶独立状态+数组参数/`onData` 回调/限定主桶表；补 e2e 多桶展开、下钻、截断、部门打印用例 |
+| 2026-10-19 | 工作台权限收紧后守卫仍回退 `/dashboard` | 普通用户登录/直连受限页被反复重定向到同一受限页 → **无法进入系统**（导航被判定无限重定向） | `router/access.ts` 统一准入与落地页解析（工作台 → 业务数据 → 回款）；登录回跳经 `canAccessPath` 校验；菜单/面包屑复用同一判定 |
+| 2026-10-19 | 部门汇总应发只计一次全公司 5% | 月结每位有聚合行的经理各计一次 5%，签字稿少计 N-1 份；**导出/打印金额小于月结应发** | 团队行增 `has_aggregate/aggregate_amount`（优先冻结聚合行）；对账改按聚合额求和，新增「聚合行舍入差」吸收分列 q2 尾差；补「与 `total_payable` 对拍」用例 |
+| 2026-10-19 | 工作台待办未按角色过滤 | 财务看得到「待领导审核」、领导看得到「待财务复核」，与 FR-034「仅看到与自己职责相关」不符 | `pending_statuses_for_roles` 按角色映射在途节点；repository 参数化 statuses；admin 保留全部在途视角 |
 | 2026-10-09 | 日志脱敏在 `logging.Filter` 阶段改写 `record.msg` | 抹掉 `%s` 占位符 → logging 内部 `msg % args` 抛 TypeError → **整条日志丢失**（比不脱敏更危险） | 改为 `SensitiveFormatter` 在格式化**之后**脱敏；补回归用例 |
 | 2026-10-09 | `PasswordHash.recommended()` 在 pwdlib 0.3.x 推荐 Argon2 而非 BCrypt | 密码算法与规范不符，且随库版本变化——同一批密码可能混用两种算法 | 改为显式 `PasswordHash((BcryptHasher(),))` 钉死算法 |
 | 2026-10-09 | 模型未设置表级 `comment`，`update_time` 用 `server_onupdate` | 违反规范红线；`server_onupdate` 只是 ORM 标记，**不生成 `ON UPDATE CURRENT_TIMESTAMP` 子句**，更新时间永不刷新 | 补表注释；改用 `text("CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP")` |
@@ -150,6 +250,32 @@ uv run pytest tests/integration -q   # 仅集成
 | 2026-10-13 | **客户/人员删除保护漏检业务引用**（T4 占位注释「待业务表就位后补充」在 T7 交付后无人补齐） | 被业务引用的客户、被业务归属（负责/协助）引用的人员删除 → FK RESTRICT 穿透成 **500**。**由 e2e 清理步骤暴露**（集成测试只覆盖了 T2/T4 当时的引用面，业务表就位后引用面扩大未回看） | customer 删除加 `count_business_refs` 检查 + IntegrityError 兜底 400；personnel 删除加 `count_business_roles_refs`（负责/协助合并统计）；补 2 个集成用例锁定；文案更新「客户归属或业务归属引用」 |
 | 2026-10-13 | **单价列（DECIMAL(14,4)）被两位小数校验拒收**（前后端同源） | 编辑任何带精度的历史单价（回显 "5000.0000"）被前端 `AMOUNT_PATTERN` 与后端 `_check_amount` 双双拒绝——**创建后单价带小数位的记录永远无法编辑**。**由 e2e「编辑业务」步骤暴露**（创建用整数、编辑回显带 4 位小数，恰好只在这条路径相遇） | 后端 `_check_amount` 加 `scale` 参数（金额/数量 2 位、单价类 4 位）；前端业务/发货明细行单价类放行 4 位；集成用例锁定 |
 | 2026-10-13 | 发货 `freight_amount` 漏做金额校验 | 负数/三位小数/超容量的运费直接落库（schema 对 quantity/sale_price 都复用了 `_check_amount`，唯独运费没套用），业务运费合计与报表随之错乱 | shipments.py schema 的 Create/Update 加 `field_validator("freight_amount")`（同套口径，文案「运费金额不能为负数 / 最多两位小数」）；集成用例锁定 |
+| 2026-10-15 | **计算预览把 ‰ 存储值当纯比例相乘**（企业户/信息员分支） | `enterprise.rate`=3（3‰）、`info.rate`=1（1‰）未经 ÷1000 直接乘——绩效金额放大 1000 倍（15000×3=45000）。**既有测试只覆盖业务员路径**（`salesperson_rate` 内部有 ÷1000），两分支零覆盖使缺陷存活；该预览是 M3 核算共用契约 | 两分支显式 `/1000` 并注释声明换算；补企业户/信息员精确数值用例锁定 |
+| 2026-10-15 | **编号撞唯一键的重试写在 audit 上下文内 `return _retry_create`**（业务/发货/回款三处同构） | 吞异常后正常退出被记 `success=True`（假成功审计，业务实际已回滚）；重入整个 `create_*` 违反「不支持嵌套」约定；`_NO_RETRY=1` 死常量致持续冲突时**无界递归**至 RecursionError | 改为 audit 上下文内 for 循环（上限 `_NO_RETRY`），rollback 后重新锁行与取号；新增集成用例锁定「成功/最终失败各恰好一条日志」 |
+| 2026-10-15 | **单号 MAX 检索用 VARCHAR 字典序**（`no_generator`） | 序号破 4 位宽度（9999→10000）后字典序反转（"-10000"<"-9999"），MAX 恒取旧值 → seq 恒重算同一号码 → 当日该前缀所有建单持续撞唯一键 | 排序改「长度优先、同级字典序」（同前缀下长度大即数值大）；跨位宽/同宽/空表三用例锁定；param 版本号一并复用 |
+| 2026-10-15 | **编辑业务全程无锁读 + 无终态门槛** | ① 「有发货禁换客户」走无锁快照读，与发货/回款写路径（FOR UPDATE）不互斥——并发新增发货可旁路保护；② 已完成/已终止业务仍可全量改明细并重算 M3 核算基线（发货/回款服务禁写终态，父单据反而放行） | `get_with_names` 加 `for_update`；update 补终态门槛；前端编辑按钮终态禁用；`has_docs` 单点收口（update/delete 共用） |
+| 2026-10-15 | **删除产品无引用保护**（docstring「待 V5 补充」在 V5 就位后未兑现） | 被业务/发货明细引用的产品删除 → FK RESTRICT 穿透成 500（与 2026-10-13 客户/人员删除保护漏检同源——「占位注释交付后无人回看」第二次发生） | `count_refs`（两明细表）+ IntegrityError 兜底 400；**全局注册 IntegrityError handler** 兜底未来遗漏（漏网的引用冲突收敛 400 而非 500） |
+| 2026-10-15 | **产品 schema 私写校验不查小数位与容量** | `sale_price` 用 `_parse_non_negative`（非负/有限），5 位小数被 Numeric(14,4) **静默截断**（舍入即算错钱）、超容量 500——与 fba8cfc 修掉的「schema 小数位口径」同源残留 | 复用 `_check_amount`（PRICE_MAX+scale=4 / AMOUNT_MAX）；6 个秒级 schema 单测锁定 |
+| 2026-10-15 | 行金额乘积（数量2位×单价4位=6位小数）直写 DECIMAL(14,2) | MySQL 静默舍入且回显漂移：创建响应读内存值 "5.166615"、复查读库值 "5.17"——同一行金额前后显示不一致 | 显式 `quantize(HALF_UP)` 固化（与 MySQL 舍入方向一致）；回显/库值一致性用例锁定 |
+| 2026-10-15 | 先款后货（payment_days 为负）计提比例线性外插 | 比例 = 起始 + \|天数\|×斜率，**高于起始值甚至超 100%**——M3 接入真实回款后直接多算绩效工资（预览被 schema 拦住、回款登记不校验日期先后，缺陷在 M3 前不可见） | `salesperson_rate` 钳制 days≥0（按起始比例计提；payment_days 出参仍照实输出负值，口径经用户 2026-10-15 裁决） |
+| 2026-10-15 | 评级区间重叠先查后写无锁、无唯一键兜底 | 两管理员并发提交重叠区间互判不重叠而双双入库——同一总分命中多等级且结果取决于插入顺序 | 判重叠的 `list_all` 加 FOR UPDATE 锁全表行串行化；只读直出不加锁 |
+| 2026-10-15 | 岗位维度值大小写校验（ci）与快照匹配（精确）不对称 | API 提交 "SalesPerson" 校验通过入库，快照字典按精确键取值不命中——**静默按错误参数算钱且无报错**；param_code 变形大写则 get_spec 抛 ValueError 成 500 | 校验命中后一律以库里规范值落库（role_code/definition.param_code）；批量预载字典键 casefold 归一保持等价命中 |
+| 2026-10-16 | **logo 上传同扩展名覆盖时先写后删** | `save_logo` 在写入新文件**之后**清理旧扩展名——同扩展名重传时把刚落盘的新文件一并删掉，回读 404（首次单跑通过、集成连跑即暴露，依赖「库里已有同扩展名旧记录」的前置状态） | 清理旧扩展名移到写新文件**之前**且仅异扩展名执行；集成连跑两遍幂等锁定 |
+| 2026-10-16 | **public 端点 300s 响应缓存让登录页拿旧公司名** | 公司名保存后退出登录，登录页命中浏览器缓存副本仍显示旧品牌名（设置页「保存后生效」承诺失效）——**由 settings_flow e2e 首跑暴露**（新标签页直接打开正常、退出回跳的登录页异常） | 登录页改用带时间戳的原生 `fetch` + `cache: no-store` 绕过磁盘缓存（axios 对响应 max-age 无能为力）；手动解包统一信封 |
+| 2026-10-16 | V6 迁移 downgrade 保留 autogenerate 的逐个 `drop_index` 且漏删行级种子 | 外键唯一支撑索引单独删除报 MySQL 1553 回滚中断；roles/param_definitions/param_values 的行级种子（表由 V1/V3 建）drop_table 不会带走——重放 upgrade 时唯一键冲突 | downgrade 只保留 `drop_table`（V1/V3 先例）+ 三条 DELETE 反向清理行级种子；downgrade→upgrade 往返实测通过 |
+| 2026-10-19 | **经理团队聚合分成放大 100 倍**（settlement_service） | 参数按百分数存储（12.5=12.5%），`parse_fraction` 后调用方又 ×100、`manager_team_share` 内部再 ÷100——净效应「绩效×12.5」；单元测试直传 Fraction 未覆盖调用方换算使缺陷存活 | 去掉调用方 ×100；`rate_text` 改用实际参数原文（原硬编码默认值失真）；集成用例两档金标准（6.84/9.78 vs 错误值 684.43）锁定 |
+| 2026-10-19 | **审批联动不判终审**（approval_service.act） | 财务节点通过（1→2）即 mark_locked 月结/调整单置生效——领导驳回后 locked_at/locked_by 残留、两级审批形同虚设（锁定后源数据写路径立即被拦） | 生效类联动收敛到 `final_approved`（终态才触发）；驳回任意节点即时；mark_rejected 补清锁定字段；用例断言财务通过后仍 status=2 且无锁定信息 |
+| 2026-10-19 | **调整单创建完全不可用**（两处叠加） | ① `ENABLE_CODE_BY_TYPE` 漏登记 type=3 → is_enabled 恒 400「未知的审批对象类型」；② 修复①后暴露：自动生效分支手工插 `ApprovalStep(order_id=调整单id)`，而该外键指向 approval_orders，必然 errno 1452 | 补登记 `approval.adjustment.enabled`；自动通过留痕统一交 `submit_order`（不再手工插步）；新建调整单集成用例锁定 |
+| 2026-10-19 | **重算绕过业务级一次性计提防线** | 「进度登记」回款（#25 第二笔及以后）无独立台账行，重算会凭空落一行生效行——同业务两行生效行、绩效按两倍计入工资 | 无旧版本行一律 400「进度登记无可重算」；用例锁定「重算后同业务仍只有一行生效行」 |
+| 2026-10-19 | **前端重算传错 ID**（台账页） | 把台账行主键当 receipt_id 传给重算接口——会作废并重算**无关回款**的台账（若目标回款已核算），或报错无法重算目标行 | 改传 `row.receipt_id`（聚合行 receipt_id 空值防御）；`LedgerRow` 本含该字段 |
+| 2026-10-19 | **quantize 缺省银行家舍入**（9 处金额固化） | docstring 声称 HALF_UP，实际未传 rounding 走 ROUND_HALF_EVEN——x.xx5 舍成偶数尾数，与业务四舍五入口径差 1 分（台账固化金额比应发少 1 分） | 9 处显式 `rounding=ROUND_HALF_UP`；`_q2` 提为模块级并单测锁定（2.345→2.35） |
+| 2026-10-19 | **月结锁定拦截只覆盖 1/4 写路径** | 仅新增回款被拦；回款编辑（可跨月搬数）/删除、发货增/改/删、核算与重算全部放行——锁定月份快照与源数据脱钩且无留痕 | 五处写路径补齐 `ensure_month_not_locked`（编辑按原月+新月双查）；拦截先于「被引用/已核算」判定；三用例锁定 |
+| 2026-10-19 | **台账 settlement_id 回填从未发生**（死代码） | `update_ledger_settlement_id` 全库零调用——「未入结」判据恒真，重生成会把已固化行反复纳入（或补上回填却不先解绑导致漏算整月） | generate 回填 + 重生成前解绑（新增 `clear_ledger_settlement_id`）；用例断言回填与重生成金额不翻倍 |
+| 2026-10-19 | **经理聚合行从不落库** | `_build_manager_aggregates` 只构造内存对象参与 items 汇总——台账表永远无 calc_type=2 行，报表下钻（business_id 锚点）落空 | 聚合行经 repository 落库并回填 settlement_id；重生成先作废旧聚合行（`deactivate_month_aggregates`）；`_confirm_scope` 限定 calc_type=1 防聚合行混入单笔池 |
+| 2026-10-19 | **月结取参用生成日**（date.today） | 补生成历史月份时经理分成/月工资口径/试用期阈值按生成日参数计算——同一月份两次生成金额不同，违背「参数按生效日期时点化」红线 | 新增 `_month_end`（所属月月末）为聚合与月工资口径取参锚点；单测 5 例 + 集成用例（10-25 预约变更影响 10 月聚合） |
+| 2026-10-19 | **迁移双轨三处漂移** | ① V6 就地修改加入 uk 致旧库补不上（V8 也未补）→ V9 条件式补齐（幂等裸 SQL，临时库验证两分支）；② V7 留存 SQL 约束/索引名单数（`fk_performance_ledger_*`）与 alembic op.f/init-dev 漂移；③ V8 迁移 revision 缺类型注解，`test_schema_sync` 的 head 推断**静默漏检 V8**、init-dev 版本号落后未被发现 | V9 迁移 + V7 SQL 名修正 + V8 注解修正 + init-dev 版本推进；schema 同步测试恢复全量断言 |
+| 2026-10-19 | 运维脚本两处（restore_drill/health_check） | ① 行数核对把查询失败回显 `'?'` 当数据比较（`'?'=='?'` 判 ✓）且 TABLES 缺 V7 四表等 16 张——备份漏表时演练全绿误报「可恢复」；② `redis-cli -a "$REDIS_PASSWORD"` 密码进宿主进程命令行 | TABLES 补全 32 张业务表 + `'?'` 一律判 ✗；Redis 探活改容器内环境变量展开（compose 补 REDIS_PASSWORD），实测 PONG |
+| 2026-10-19 | 调整单金额无校验 / INT 参数原文 `int()` / logo 清理裸抛 | ① amount 负数反转补发-扣减语义、'abc' 直落库 500；② `int('360.0')` 使整月核算 500（INT 参数合法入库原文）；③ 旧 logo 清理 OSError 裸抛把成功更新记成失败审计并 500 | schema 正则 + 服务层 Decimal>0；`int(parse_fraction(...))`；清理包 try 仅 warning；各补回归用例 |
 
 ## 五、待补用例
 
@@ -157,7 +283,8 @@ uv run pytest tests/integration -q   # 仅集成
 | --- | --- | --- |
 | 基础数据管理 | ✅ 已完成 | 2026-10-13 完成（48 例，见上表）；「被业务数据引用」的删除保护已随 T11 的业务/发货禁删用例覆盖 |
 | 业务数据管理 | ✅ 后端已完成 | 2026-10-13 完成（70 例，见上表）；前端页面与绩效核算联动（M3 台账核销回写 settlement_status）待 M3 补测 |
-| 绩效工资核算 | 未开始 | 需求已澄清；金额精度需专项用例（`Fraction` 与 1/90 日斜率已在 M1 公式层覆盖） |
+| M3 增量（设置/分配/审批） | ✅ 已完成 | 2026-10-16 完成（44 例，见上表）；审批流的**月结审批对象**（order_type=2）随 ④ 月结子块接入时补测 |
-| 报表统计 | 未开始 | 依赖报表口径确认 |
+| 绩效工资核算（M3-core） | ✅ 已完成 | 2026-10-17 完成（核算/月结/调整单，见运行记录）；2026-10-19 code-review 21 项修复并补回归约 20 例；2026-10-20 e2e `calc_settlement_flow` 8/8 实跑通过（台账/月结真实浏览器链路） |
+| 报表统计 | ✅ 已完成 | 2026-10-19 完成并补齐回归；2026-10-20 e2e `report_flow` 12/12 实跑通过，全量 862 passed |
 
 > 系统管理模块（用户/角色/日志查询）已于 2026-10-10 完成并补齐用例，见上表。

backend/tests/integration/conftest.py

@@ -21,6 +21,7 @@
 
 import uuid
 from decimal import Decimal
+from pathlib import Path
 
 import pytest
 from sqlalchemy import delete, select, update
@@ -29,22 +30,30 @@ from app.core.constants import ROLE_ADMIN, ROLE_USER
 from app.core.db import get_session_factory
 from app.core.security import create_access_token, hash_password
 from app.models import (
+    AdjustmentOrder,
+    ApprovalOrder,
     Business,
     BusinessItem,
     BusinessRole,
     BusinessStatusLog,
     Customer,
     CustomerRatingGrade,
+    MonthlySettlement,
     OperationLog,
     OwnershipChangeLog,
+    ParamChangeBatch,
+    ParamValue,
+    PerformanceLedger,
     Personnel,
     PersonnelPlan,
     PersonnelRegion,
     Product,
     Receipt,
     Role,
+    SettlementItem,
     Shipment,
     ShipmentItem,
+    SystemSetting,
     User,
     UserRole,
 )
@@ -92,6 +101,14 @@ def _purge_test_data() -> None:
             session.execute(delete(UserRole).where(UserRole.role_id.in_(role_ids)))
             session.execute(delete(Role).where(Role.id.in_(role_ids)))
 
+        # ---- M3-core：核算台账 / 月结 / 调整单（必须先于回款/业务/人员删除——
+        # ledger.receipt_id/personnel_id/settlement_id 外键 RESTRICT 会挡住后面
+        # 的单据与人员清理；仅测试写入，全量清）----
+        session.execute(delete(PerformanceLedger))
+        session.execute(delete(SettlementItem))
+        session.execute(delete(MonthlySettlement))
+        session.execute(delete(AdjustmentOrder).where(AdjustmentOrder.order_no.like("TZ%")))
+
         # ---- M2 业务数据（T11）：业务/发货/回款三类单据 ----
         # 编号系统生成、无 t_ 前缀可用，按业务编号前缀全量清（三类单据表目前
         # 只有测试会写）。外键均为 RESTRICT，删除顺序不能倒：回款 → 发货
@@ -168,7 +185,32 @@ def _purge_test_data() -> None:
         session.execute(delete(Product).where(Product.product_name.like("t\\_%")))
         # 人员已先删（business_role_id 外键 RESTRICT），直建的测试岗位此时可安全删
         session.execute(delete(BusinessRole).where(BusinessRole.role_code.like("t\\_%")))
+
+        # ---- M3：审批单 / 二次分配 / 参数开关 / 系统设置基线 ----
+        # 审批单无 t_ 前缀可用，按 AP 编号前缀全量清（steps 外键 CASCADE 随删；
+        # ref_id 固化无外键，业务已在上一步删除，无悬挂影响）
+        session.execute(delete(ApprovalOrder).where(ApprovalOrder.order_no.like("AP%")))
+        # 开关参数恢复种子基线：测试提交的变更批次条目 id 均大于种子终值 28
+        # （V3 十九条 + V6 两条 + V7 调整单一条 + V8 经理基数开关一条；V8 另
+        # 插入两个审批开关的 10-19 生效行 id 23/24，V10 插入预警规则参数
+        # id 26/27/28，均属种子），删新条目与新批次后解析回退到种子值
+        stray_values = list(session.execute(select(ParamValue).where(ParamValue.id > 28)).scalars())
+        if stray_values:
+            stray_batches = {v.batch_id for v in stray_values}
+            session.execute(delete(ParamValue).where(ParamValue.id > 28))
+            session.execute(delete(ParamChangeBatch).where(ParamChangeBatch.id.in_(stray_batches)))
+        # 系统设置恢复种子单行（test_settings 会改公司名/传 logo——残留会让
+        # 后续 e2e 的品牌断言在污染状态下运行）；uploads 下的测试 logo 一并删
+        session.execute(
+            update(SystemSetting)
+            .where(SystemSetting.id == 1)
+            .values(company_name="衍水集团", logo_path=None)
+        )
         session.commit()
+        logo_dir = Path(__file__).resolve().parents[2] / "uploads" / "logo"
+        if logo_dir.is_dir():
+            for f in logo_dir.iterdir():
+                f.unlink(missing_ok=True)
 
 
 @pytest.fixture(autouse=True)

backend/tests/integration/factories.py

@@ -0,0 +1,60 @@
+"""集成测试共用工厂：客户 → 业务 → 明细的最小造数链。
+
+回款/发货/业务三个测试文件此前各持一份逐字相同的工厂（口径漂移已经
+发生：同一 _customer 三份、payload 细节靠复制维持），收口后「t_ 前缀、
+默认明细行、业务日期取今日」单点维护；conftest 兜底清理按 t_ 前缀与
+YW/SH/HK 编号前缀覆盖本模块全部造数。
+"""
+
+import uuid
+from datetime import date
+
+from fastapi.testclient import TestClient
+
+_CUSTOMERS = "/api/v1/base/customers"
+_BUSINESSES = "/api/v1/business/businesses"
+
+
+def customer(client: TestClient, headers: dict) -> dict:
+    """建一名 t_ 前缀测试客户（业务的必选引用）。"""
+    resp = client.post(
+        _CUSTOMERS,
+        json={
+            "company_name": f"t_公司_{uuid.uuid4().hex[:8]}",
+            "owner_name": "张老板",
+            "customer_type": "personal",
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def business_item(**overrides: object) -> dict:
+    """业务明细行入参（默认：数量 100 × 单价 100.00 = 销售额 10000）。"""
+    body: dict = {
+        "product_name": f"t_产品_{uuid.uuid4().hex[:8]}",
+        "product_category": "municipal_water",
+        "quantity": "100",
+        "sale_price": "100.00",
+    }
+    body.update(overrides)
+    return body
+
+
+def business_payload(customer_id: int, **overrides: object) -> dict:
+    body: dict = {
+        "customer_id": customer_id,
+        "business_date": str(date.today()),
+        "items": [business_item()],
+    }
+    body.update(overrides)
+    return body
+
+
+def create_business(client: TestClient, headers: dict) -> dict:
+    """建一名 t_ 客户并挂一笔默认业务（发货/回款须先有业务）。"""
+    cust = customer(client, headers)
+    resp = client.post(_BUSINESSES, json=business_payload(cust["id"]), headers=headers)
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]

backend/tests/integration/test_approval_flow.py

@@ -0,0 +1,719 @@
+"""审批流集成测试（二次分配方案为首个接入对象）。
+
+守的是（计划 T4 验收矩阵）：
+- 开关关闭（种子默认 0）：提单即「自动通过」——status=3 且两级节点
+  action=3 留痕（留痕不断链，关闭=直接生效的需求口径）
+- 开关开启：status=1 → 财务通过 → status=2 → 领导通过 → status=3
+- 驳回：整体驳回 status=4，意见留痕；驳回必填意见（空驳 400）
+- 节点准入：status=1 仅财务、status=2 仅领导；**admin 不代办**（403）；
+  普通用户/营销后勤进不了模块（403）
+- 再编辑撤旧建新：在途单 status=5 + node=0/action=4 撤回留痕，新单新建
+- 方案为空不提单
+- 开关读一次：同一提交路径内参数变化不影响判定（种子级默认行为锁定）
+
+角色用户经 make_user 造（finance/leader/marketing_ops 三新角色种子在库）。
+开关联动走参数变更批次（PUT /system/params 端到端，不直改库）。
+"""
+
+import uuid
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.integration.factories import business_payload, customer
+
+pytestmark = pytest.mark.integration
+
+_BUSINESSES = "/api/v1/business/businesses"
+_APPROVALS = "/api/v1/system/approvals"
+_PARAMS = "/api/v1/system/params"
+_PERSONNEL = "/api/v1/base/personnel"
+
+
+def _person(client: TestClient, headers: dict) -> dict:
+    resp = client.post(
+        _PERSONNEL,
+        json={
+            "personnel_name": f"t_审批_{uuid.uuid4().hex[:8]}",
+            "business_role_id": _any_role_id(),
+            "salary_standard": "3000.00",
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def _any_role_id() -> int:
+    from sqlalchemy import select
+
+    from app.core.constants import BUSINESS_ROLE_SALESPERSON
+    from app.core.db import get_session_factory
+    from app.models import BusinessRole
+
+    factory = get_session_factory()
+    with factory() as session:
+        return int(
+            session.execute(
+                select(BusinessRole.id).where(
+                    BusinessRole.role_code == BUSINESS_ROLE_SALESPERSON,
+                    BusinessRole.status == 1,
+                )
+            ).scalar_one()
+        )
+
+
+def _create_with_plan(client: TestClient, headers: dict, personnel_id: int) -> dict:
+    cust = customer(client, headers)
+    resp = client.post(
+        _BUSINESSES,
+        json=business_payload(
+            cust["id"],
+            secondary_allocations=[{"personnel_id": personnel_id, "ratio": "50.00"}],
+        ),
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def _latest_order(client: TestClient, headers: dict, refer_no: str) -> dict:
+    resp = client.get(_APPROVALS, params={"keyword": refer_no, "pageSize": 1}, headers=headers)
+    assert resp.status_code == 200, resp.text
+    rows = resp.json()["data"]["list"]
+    assert rows, f"未找到审批单：{refer_no}"
+    detail = client.get(f"{_APPROVALS}/{rows[0]['id']}", headers=headers)
+    return detail.json()["data"]
+
+
+def _set_switch(client: TestClient, admin_headers: dict, value: str) -> None:
+    """经参数变更批次把二次分配审批开关置值（立即生效）。"""
+    resp = client.post(
+        f"{_PARAMS}/changes",
+        json={
+            "change_type": 1,
+            "remark": f"测试切换审批开关={value}",
+            "items": [
+                {
+                    "param_code": "approval.secondary_allocation.enabled",
+                    "dimension_value": "",
+                    "value": value,
+                }
+            ],
+        },
+        headers=admin_headers,
+    )
+    assert resp.status_code == 200, resp.text
+
+
+@pytest.fixture
+def finance(make_user, auth_headers) -> dict:
+    """财务角色账号（审批第二节点）。"""
+    user = make_user(["finance"])
+    user["headers"] = auth_headers(user)
+    return user
+
+
+@pytest.fixture
+def leader(make_user, auth_headers) -> dict:
+    """领导角色账号（审批第三节点）。"""
+    user = make_user(["leader"])
+    user["headers"] = auth_headers(user)
+    return user
+
+
+@pytest.fixture
+def switched_on(client: TestClient, admin: dict) -> None:
+    """把二次分配审批开关置 1（立即生效；用例结束由 conftest 恢复种子基线）。"""
+    _set_switch(client, admin["headers"], "1")
+
+
+class TestSwitchOff:
+    """开关关闭（用例显式设置，不依赖种子默认值）：提单即自动通过。"""
+
+    def test_创建带方案_自动通过全节点留痕(
+        self, client: TestClient, admin: dict, finance: dict
+    ) -> None:
+        _set_switch(client, admin["headers"], "0")  # V8 起种子默认开启
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+
+        order = _latest_order(client, finance["headers"], data["business_no"])
+        assert order["status"] == 3
+        assert order["order_no"].startswith("AP")
+        auto_steps = [s for s in order["steps"] if s["action"] == 3]
+        assert len(auto_steps) == 2
+        assert {s["node"] for s in auto_steps} == {1, 2}
+        assert all(s["operator_name"] == "系统" for s in auto_steps)
+
+    def test_方案为空不提单(self, client: TestClient, admin: dict, finance: dict) -> None:
+        cust = customer(client, admin["headers"])
+        resp = client.post(_BUSINESSES, json=business_payload(cust["id"]), headers=admin["headers"])
+        assert resp.status_code == 200
+        rows = client.get(
+            _APPROVALS,
+            params={"keyword": resp.json()["data"]["business_no"]},
+            headers=finance["headers"],
+        ).json()["data"]["list"]
+        assert rows == []
+
+
+class TestSwitchOn:
+    """开关开启：两节点人工流转。"""
+
+    @pytest.fixture
+    def switched_on(self, client: TestClient, admin: dict) -> None:
+        _set_switch(client, admin["headers"], "1")
+
+    def test_两节点流转至通过(
+        self, client: TestClient, admin: dict, finance, leader, switched_on
+    ) -> None:
+
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+
+        order = _latest_order(client, finance["headers"], data["business_no"])
+        assert order["status"] == 1
+
+        # 财务通过 → 待领导
+        resp = client.post(
+            f"{_APPROVALS}/{order['id']}/action",
+            json={"action": 1, "opinion": "同意"},
+            headers=finance["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        assert resp.json()["data"]["status"] == 2
+
+        # 领导通过 → 已通过
+        resp = client.post(
+            f"{_APPROVALS}/{order['id']}/action",
+            json={"action": 1},
+            headers=leader["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        assert resp.json()["data"]["status"] == 3
+        manual = [s for s in resp.json()["data"]["steps"] if s["action"] == 1]
+        assert {s["node"] for s in manual} == {1, 2}
+
+    def test_财务驳回_整体驳回且意见留痕(
+        self, client: TestClient, admin: dict, finance, leader, switched_on
+    ) -> None:
+        _ = leader
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+
+        resp = client.post(
+            f"{_APPROVALS}/{order['id']}/action",
+            json={"action": 2, "opinion": "比例分配不合理"},
+            headers=finance["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        out = resp.json()["data"]
+        assert out["status"] == 4
+        rejected = [s for s in out["steps"] if s["action"] == 2]
+        assert rejected and rejected[0]["opinion"] == "比例分配不合理"
+
+    def test_驳回缺意见被拒(
+        self, client: TestClient, admin: dict, finance, leader, switched_on
+    ) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+
+        resp = client.post(
+            f"{_APPROVALS}/{order['id']}/action",
+            json={"action": 2},
+            headers=finance["headers"],
+        )
+        assert resp.status_code == 400
+
+    def test_节点准入_领导不能审财务节点_admin不代办(
+        self, client: TestClient, admin: dict, finance, leader, switched_on
+    ) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, leader["headers"], data["business_no"])
+
+        # status=1 是财务节点：领导不行，admin 也不代办
+        for headers in (leader["headers"], admin["headers"]):
+            resp = client.post(
+                f"{_APPROVALS}/{order['id']}/action",
+                json={"action": 1},
+                headers=headers,
+            )
+            assert resp.status_code == 403
+
+    def test_重复操作已通过单被拒(
+        self, client: TestClient, admin: dict, finance, leader, switched_on
+    ) -> None:
+
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+        client.post(
+            f"{_APPROVALS}/{order['id']}/action", json={"action": 1}, headers=finance["headers"]
+        )
+        client.post(
+            f"{_APPROVALS}/{order['id']}/action", json={"action": 1}, headers=leader["headers"]
+        )
+        resp = client.post(
+            f"{_APPROVALS}/{order['id']}/action", json={"action": 1}, headers=finance["headers"]
+        )
+        assert resp.status_code == 400
+
+    def test_驳回后方案行清空_不留在生效表(
+        self, client: TestClient, admin: dict, finance, switched_on
+    ) -> None:
+        """被否决的方案不得以「当前生效行」身份留在表里（M3 快照会取到）。"""
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+
+        resp = client.post(
+            f"{_APPROVALS}/{order['id']}/action",
+            json={"action": 2, "opinion": "方案不合理"},
+            headers=finance["headers"],
+        )
+        assert resp.status_code == 200
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        assert detail["secondary_allocations"] == [], "被驳回的方案应从生效表清空"
+        assert detail["allocation_hint"] is None
+
+
+class TestResubmit:
+    """再编辑撤旧建新 / 清空方案撤在途单。"""
+
+    def test_在途单撤回并新建(
+        self, client: TestClient, admin: dict, finance, leader, switched_on
+    ) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        first = _latest_order(client, finance["headers"], data["business_no"])
+        assert first["status"] == 1
+
+        # 再编辑（仍带方案）→ 旧在途单撤回、新单待审
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        payload = business_payload(
+            detail["customer_id"],
+            secondary_allocations=[{"personnel_id": p["id"], "ratio": "80.00"}],
+        )
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        rows = client.get(
+            _APPROVALS,
+            params={"keyword": data["business_no"], "pageSize": 10},
+            headers=finance["headers"],
+        ).json()["data"]["list"]
+        statuses = {row["status"] for row in rows}
+        assert 5 in statuses and 1 in statuses, f"未见撤回+新建：{statuses}"
+        old_detail = client.get(f"{_APPROVALS}/{first['id']}", headers=finance["headers"]).json()
+        withdraw_steps = [s for s in old_detail["data"]["steps"] if s["action"] == 4]
+        assert withdraw_steps and withdraw_steps[0]["node"] == 0
+
+    def test_编辑清空方案_在途单撤回不再悬空(
+        self, client: TestClient, admin: dict, finance, switched_on
+    ) -> None:
+        """空数组=清空方案：旧在途单必须撤回，否则挂着不存在的方案走审批。"""
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        first = _latest_order(client, finance["headers"], data["business_no"])
+        assert first["status"] == 1
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        payload = business_payload(detail["customer_id"], secondary_allocations=[])
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        rows = client.get(
+            _APPROVALS,
+            params={"keyword": data["business_no"], "pageSize": 10},
+            headers=finance["headers"],
+        ).json()["data"]["list"]
+        statuses = {row["status"] for row in rows}
+        assert statuses == {5}, f"清空方案后旧在途单应撤回且无新单：{statuses}"
+        assert (
+            client.get(f"{_APPROVALS}/{first['id']}", headers=finance["headers"]).json()["data"][
+                "status"
+            ]
+            == 5
+        )
+
+    def test_删除业务在途单禁删_终态单随删(
+        self, client: TestClient, admin: dict, finance, switched_on
+    ) -> None:
+        """ref_id 固化无外键：在途单禁删（防指向已删业务的活单继续被审批），
+        终态单随业务删除一并清理（已通过/已驳回的历史事实由留痕日志承载）。"""
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+
+        # 在途：禁删
+        resp = client.delete(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"])
+        assert resp.status_code == 400
+        assert "在途审批单" in resp.json()["message"]
+
+        # 驳回（终态）后：可删，且审批单随之清理
+        order = _latest_order(client, finance["headers"], data["business_no"])
+        client.post(
+            f"{_APPROVALS}/{order['id']}/action",
+            json={"action": 2, "opinion": "驳回后可删"},
+            headers=finance["headers"],
+        )
+        resp = client.delete(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        rows = client.get(
+            _APPROVALS,
+            params={"keyword": data["business_no"]},
+            headers=finance["headers"],
+        ).json()["data"]["list"]
+        assert rows == [], "终态审批单应随业务删除一并清理"
+
+
+class TestModuleAccess:
+    """模块准入：普通用户与营销后勤不可见（权限清单待澄清 #6）。"""
+
+    def test_普通用户403(self, client: TestClient, normal: dict) -> None:
+        assert client.get(_APPROVALS, headers=normal["headers"]).status_code == 403
+
+    def test_营销后勤403_暂不可见(self, client: TestClient, make_user, auth_headers) -> None:
+        ops = make_user(["marketing_ops"])
+        ops["headers"] = auth_headers(ops)
+        assert client.get(_APPROVALS, headers=ops["headers"]).status_code == 403
+
+    def test_财务与领导可见(self, client: TestClient, make_user, auth_headers) -> None:
+        for code in ("finance", "leader"):
+            user = make_user([code])
+            user["headers"] = auth_headers(user)
+            assert client.get(_APPROVALS, headers=user["headers"]).status_code == 200
+
+
+class TestContentSnapshot:
+    """审批单内容快照与版本号（code-review 遗留②）。
+
+    守的是：复核者看到的是**送审时**的方案，而不是审批期间被改过的当前
+    方案；历史单（升级前无快照）必须显式标注「当前内容回退」，不能把
+    当前内容冒充送审内容。
+    """
+
+    def test_提交时快照固化_再改方案不回写旧单(
+        self, client: TestClient, admin: dict, finance: dict, switched_on
+    ) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        first = _latest_order(client, finance["headers"], data["business_no"])
+
+        assert first["version_no"] == 1
+        assert first["content_source"] == "snapshot"
+        snapshot = first["snapshot"]
+        assert snapshot["schema_version"] == 1
+        assert snapshot["order_type"] == 1
+        assert snapshot["captured_at"], "快照须固化采集时间"
+        assert snapshot["data"]["business_no"] == data["business_no"]
+        assert snapshot["data"]["allocations"][0]["ratio"] == "50.00"
+        assert snapshot["data"]["allocation_total"] == "50.00"
+        assert snapshot["data"]["allocation_balance"] == "50.00"
+
+        # 编辑方案为 80%：旧在途单撤回，新单 V2 快照取新值；旧单快照不变
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        payload = business_payload(
+            detail["customer_id"],
+            secondary_allocations=[{"personnel_id": p["id"], "ratio": "80.00"}],
+        )
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        second = _latest_order(client, finance["headers"], data["business_no"])
+        assert second["version_no"] == 2
+        assert second["snapshot"]["data"]["allocations"][0]["ratio"] == "80.00"
+
+        old = client.get(f"{_APPROVALS}/{first['id']}", headers=finance["headers"]).json()["data"]
+        assert old["status"] == 5, "重新提交须撤回旧在途单"
+        assert old["snapshot"]["data"]["allocations"][0]["ratio"] == "50.00"
+
+    def test_历史单无快照_回退当前内容并标注(
+        self, client: TestClient, admin: dict, finance: dict, switched_on
+    ) -> None:
+        """升级前的审批单没有快照列：回退读当前内容，但来源必须标 live。"""
+        from app.core.db import get_session_factory
+        from app.models import ApprovalOrder
+
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+
+        factory = get_session_factory()
+        with factory() as session:
+            row = session.get(ApprovalOrder, order["id"])
+            assert row is not None
+            row.snapshot_json = None
+            session.commit()
+
+        detail = client.get(f"{_APPROVALS}/{order['id']}", headers=finance["headers"]).json()["data"]
+        assert detail["content_source"] == "live"
+        assert detail["snapshot"]["captured_at"] is None
+        assert detail["snapshot"]["data"]["business_no"] == data["business_no"]
+
+    def test_引用对象缺失且无快照_内容缺失(
+        self, client: TestClient, admin: dict, finance: dict, switched_on
+    ) -> None:
+        from app.core.db import get_session_factory
+        from app.models import ApprovalOrder
+
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+
+        factory = get_session_factory()
+        with factory() as session:
+            row = session.get(ApprovalOrder, order["id"])
+            assert row is not None
+            row.snapshot_json = None
+            row.ref_id = 999_999_999
+            session.commit()
+
+        detail = client.get(f"{_APPROVALS}/{order['id']}", headers=finance["headers"]).json()["data"]
+        assert detail["content_source"] == "missing"
+        assert detail["snapshot"] is None
+
+
+def _payload_from_detail(detail: dict, **overrides: object) -> dict:
+    """按业务详情原样重建提交载荷（明细行照抄，用于「内容未变」的场景）。"""
+    items = [
+        {
+            "product_name": it["product_name"],
+            "product_category": it["product_category"],
+            "quantity": it["quantity"],
+            "sale_price": it["sale_price"],
+        }
+        for it in detail["items"]
+    ]
+    body = business_payload(
+        detail["customer_id"],
+        items=items,
+        secondary_allocations=detail["secondary_allocations"],
+    )
+    body.update(overrides)
+    return body
+
+
+class TestNoRedundantResubmit:
+    """送审内容未变不重提、方案未变不新增版本（版本与留痕降噪）。
+
+    守的是：反复保存同一份业务（只改备注）不应刷出一串方案版本与
+    「撤回+新建」的审批留痕；而内容真变了（金额或方案）必须重提，
+    否则审批人看到的是过期内容。
+    """
+
+    def test_方案与金额均未变_不新增版本也不重提(
+        self, client: TestClient, admin: dict, finance: dict, switched_on
+    ) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        first = _latest_order(client, finance["headers"], data["business_no"])
+        assert first["status"] == 1
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        payload = _payload_from_detail(detail)
+        payload["remark"] = "只改了备注"
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        # 方案版本不增
+        after = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        assert [(h["version_no"], h["is_active"]) for h in after["allocation_history"]] == [
+            (1, 1)
+        ], "方案内容未变不应新增版本行"
+
+        # 审批单不重提：仍是原来那一张、仍待财务复核
+        rows = client.get(
+            _APPROVALS,
+            params={"keyword": data["business_no"], "pageSize": 10},
+            headers=finance["headers"],
+        ).json()["data"]["list"]
+        assert len(rows) == 1, f"送审内容未变不应重提，实得 {len(rows)} 张单"
+        assert rows[0]["id"] == first["id"]
+        assert rows[0]["status"] == 1, "在途单不应被撤回"
+        assert rows[0]["version_no"] == 1
+
+    def test_只改金额不改方案_方案版本不变但审批单重提(
+        self, client: TestClient, admin: dict, finance: dict, switched_on
+    ) -> None:
+        """金额变了 → 送审内容变了 → 必须重提；但方案本身没变 → 不新增版本。"""
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        first = _latest_order(client, finance["headers"], data["business_no"])
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        payload = _payload_from_detail(detail)
+        payload["items"][0]["sale_price"] = "200.00"
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        after = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        assert [(h["version_no"], h["is_active"]) for h in after["allocation_history"]] == [
+            (1, 1)
+        ], "方案未变不应新增版本行"
+
+        second = _latest_order(client, finance["headers"], data["business_no"])
+        assert second["version_no"] == 2, "金额变了必须重提"
+        assert second["snapshot"]["data"]["sale_amount"] == "20000.00"
+        old = client.get(f"{_APPROVALS}/{first['id']}", headers=finance["headers"]).json()["data"]
+        assert old["status"] == 5
+
+    def test_改方案比例_方案版本与审批单版本同时递增(
+        self, client: TestClient, admin: dict, finance: dict, switched_on
+    ) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        first = _latest_order(client, finance["headers"], data["business_no"])
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        payload = _payload_from_detail(
+            detail, secondary_allocations=[{"personnel_id": p["id"], "ratio": "80.00"}]
+        )
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        after = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        assert [(h["version_no"], h["is_active"]) for h in after["allocation_history"]] == [
+            (1, 0),
+            (2, 1),
+        ], "方案变了应新增版本并把旧行置历史"
+
+        second = _latest_order(client, finance["headers"], data["business_no"])
+        assert second["version_no"] == 2
+        old = client.get(f"{_APPROVALS}/{first['id']}", headers=finance["headers"]).json()["data"]
+        assert old["status"] == 5
+
+    def test_无在途单时保存仍提新单(
+        self, client: TestClient, admin: dict, finance: dict, leader: dict, switched_on
+    ) -> None:
+        """保守规则：只有「存在在途单且内容一致」才不重提。
+        方案已审批通过后再保存，仍按原语义重新送审。"""
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+        client.post(
+            f"{_APPROVALS}/{order['id']}/action", json={"action": 1}, headers=finance["headers"]
+        )
+        client.post(
+            f"{_APPROVALS}/{order['id']}/action", json={"action": 1}, headers=leader["headers"]
+        )
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        payload = _payload_from_detail(detail)
+        payload["remark"] = "已通过后再保存"
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        rows = client.get(
+            _APPROVALS,
+            params={"keyword": data["business_no"], "pageSize": 10},
+            headers=finance["headers"],
+        ).json()["data"]["list"]
+        assert len(rows) == 2, "无在途单时保存应重新送审"
+        assert max(r["version_no"] for r in rows) == 2
+
+
+class TestPendingSnapshotMatch:
+    """在途单送审内容一致性判定（approval_service.pending_matches_snapshot）。"""
+
+    def test_三种情形(self, client: TestClient, admin: dict, finance: dict, switched_on) -> None:
+        from app.core.db import get_session_factory
+        from app.services import approval_service
+
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+        snapshot = order["snapshot"]["data"]
+
+        factory = get_session_factory()
+        with factory() as session:
+            # 1) 内容一致 → True
+            assert (
+                approval_service.pending_matches_snapshot(
+                    session,
+                    order_type=1,
+                    ref_id=data["id"],
+                    snapshot=snapshot,
+                )
+                is True
+            )
+            # 2) 内容不同 → False
+            assert (
+                approval_service.pending_matches_snapshot(
+                    session, order_type=1, ref_id=data["id"], snapshot={"allocations": []}
+                )
+                is False
+            )
+            # 3) 无在途单 → False（引用对象换成别的）
+            assert (
+                approval_service.pending_matches_snapshot(
+                    session, order_type=1, ref_id=999_999_999, snapshot=snapshot
+                )
+                is False
+            )
+            # 4) 快照为 None → False
+            assert (
+                approval_service.pending_matches_snapshot(
+                    session, order_type=1, ref_id=data["id"], snapshot=None
+                )
+                is False
+            )
+
+
+class TestAllocationVersions:
+    """二次分配方案版本化（code-review 遗留①）。
+
+    守的是：编辑替换与驳回清空只把旧行置历史（is_active=0），不物理删除，
+    方案参与人与比例可回溯；生效行始终唯一，核算取数不受历史行干扰。
+    """
+
+    def test_编辑方案产生新版本_旧版本保留(
+        self, client: TestClient, admin: dict, switched_on
+    ) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        assert [(h["version_no"], h["is_active"]) for h in detail["allocation_history"]] == [
+            (1, 1)
+        ]
+
+        payload = business_payload(
+            detail["customer_id"],
+            secondary_allocations=[{"personnel_id": p["id"], "ratio": "80.00"}],
+        )
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        history = [(h["version_no"], h["is_active"], h["ratio"]) for h in detail["allocation_history"]]
+        assert history == [(1, 0, "50.00"), (2, 1, "80.00")]
+        assert [a["ratio"] for a in detail["secondary_allocations"]] == ["80.00"]
+
+    def test_驳回后生效行为空_历史行保留(
+        self, client: TestClient, admin: dict, finance: dict, switched_on
+    ) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        order = _latest_order(client, finance["headers"], data["business_no"])
+
+        resp = client.post(
+            f"{_APPROVALS}/{order['id']}/action",
+            json={"action": 2, "opinion": "方案不合理"},
+            headers=finance["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        assert detail["secondary_allocations"] == [], "被驳回方案不得留在生效行"
+        assert detail["allocation_hint"] is None
+        history = detail["allocation_history"]
+        assert len(history) == 1
+        assert history[0]["version_no"] == 1
+        assert history[0]["is_active"] == 0
+        assert history[0]["ratio"] == "50.00"

backend/tests/integration/test_approval_version.py

@@ -0,0 +1,183 @@
+"""审批单版本号并发防线（V12 唯一键 + 锁读取号）。
+
+守的是：
+- **取号必须读最新已提交值**：请求级鉴权与业务共用同一 DbSession，鉴权
+  的普通 SELECT 已把 REPEATABLE READ 快照锚定在请求开始时刻；父行锁只
+  串行化写入时刻、不刷新快照——取号若是快照读，并发提单会算出同一个
+  version_no（两会话法做行为级回归锁，不依赖真多线程）
+- **取号查询带 FOR UPDATE 且不用聚合**：MySQL 官方不允许聚合函数携带
+  锁子句（Locking clauses are not permitted in queries with aggregate
+  functions or GROUP BY），聚合上的 FOR UPDATE 语义无保证
+- **DB 层唯一键生效**：即使应用层取号缺陷被绕过，重复
+  (order_type, ref_id, version_no) 也必须在库上被拒（1062）
+- **冲突收敛为 400**：编辑路径撞唯一键 → 审计上下文回滚 → 业务提示
+  可重试，业务数据不得写坏
+- **正常路径版本号仍递增**：锁读改写不破坏既有 1→2→3 行为
+"""
+
+import uuid
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import event, text
+
+from app.core.db import get_engine, get_session_factory
+from app.core.db_errors import is_duplicate_entry
+from app.models import ApprovalOrder
+from tests.integration.factories import business_payload
+from tests.integration.test_approval_flow import (
+    _BUSINESSES,
+    _create_with_plan,
+    _latest_order,
+    _person,
+    _set_switch,
+)
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+def switched_on(client: TestClient, admin: dict) -> None:
+    """把二次分配审批开关置 1（用例结束由 conftest 恢复种子基线）。
+
+    pytest 夹具只在定义它的模块与 conftest 中可见，跨模块直接引用会报
+    ``fixture 'switched_on' not found``；这里用 ``_set_switch`` 本地重建。
+    """
+    _set_switch(client, admin["headers"], "1")
+
+
+class TestNextVersionLockRead:
+    """取号查询的锁读口径（真实 SQL 形态 + 行为级快照回归）。"""
+
+    def test_取号查询带FOR_UPDATE_不含聚合(self, client: TestClient, admin: dict) -> None:
+        """抓 _next_version 真实发出的 SQL（比本地重造语句再编译更贴真）：
+        必须含 FOR UPDATE、不含 MAX( —— 聚合上的锁子句 MySQL 不保证语义。"""
+
+        captured: list[str] = []
+
+        def _spy(_conn, _cursor, statement, *_rest):
+            if "approval_orders" in statement and "version_no" in statement:
+                captured.append(statement)
+
+        engine = get_engine()
+        event.listen(engine, "before_cursor_execute", _spy)
+        try:
+            p = _person(client, admin["headers"])
+            _create_with_plan(client, admin["headers"], p["id"])  # 触发一次真实提单
+        finally:
+            event.remove(engine, "before_cursor_execute", _spy)
+
+        assert captured, "未捕获到取号查询"
+        assert any("FOR UPDATE" in sql.upper() for sql in captured), captured
+        assert not any("MAX(" in sql.upper() for sql in captured), captured
+
+    def test_版本号读最新已提交值_不受事务旧快照影响(self) -> None:
+        """两会话法（无需线程）：s1 先锚定快照 → s2 提交新版本 →
+        s1 取号必须读到 3 而非旧快照里的 2——守住「快照读 vs 当前读」根因。"""
+        from app.services import approval_service
+
+        factory = get_session_factory()
+        with factory() as s1:
+            # 锚定快照（模拟请求级鉴权读先于业务写发生）
+            s1.execute(text("SELECT order_no FROM approval_orders LIMIT 1")).all()
+
+            with factory() as s2:
+                order = ApprovalOrder(
+                    order_no=f"AP-{uuid.uuid4().hex[:12]}",
+                    order_type=1,
+                    ref_id=987654321,
+                    refer_no="YW-SNAPSHOT-TEST",
+                    version_no=2,
+                    status=5,
+                    submitter_name="t_snapshot_probe",
+                )
+                s2.add(order)
+                s2.commit()
+
+            # s1 的普通读仍停在旧快照（该分组在快照里不存在）
+            stale = s1.execute(
+                text(
+                    "SELECT COALESCE(MAX(version_no),0) FROM approval_orders "
+                    "WHERE order_type=1 AND ref_id=987654321"
+                )
+            ).scalar_one()
+            assert stale == 0, "前置失效：快照读应停在锚定时刻，先修隔离级别再跑本用例"
+
+            assert approval_service._next_version(s1, 1, 987654321) == 3, (
+                "取号必须读到最新已提交值（2+1=3），读到 2 说明退化为快照读"
+            )
+            s1.rollback()
+
+    def test_唯一键生效_重复版本号被拒(self) -> None:
+        """重复 (order_type, ref_id, version_no) 直插必须撞 1062——
+        应用层取号即使被绕过，DB 也是最后一道防线。"""
+        from sqlalchemy.exc import IntegrityError
+
+        factory = get_session_factory()
+        with factory() as s:
+            common = {
+                "order_type": 1,
+                "ref_id": 987654322,
+                "refer_no": "YW-UK-TEST",
+                "status": 5,
+                "submitter_name": "t_uk_probe",
+            }
+            s.add(ApprovalOrder(order_no=f"AP-{uuid.uuid4().hex[:12]}", version_no=1, **common))
+            s.flush()
+            s.add(ApprovalOrder(order_no=f"AP-{uuid.uuid4().hex[:12]}", version_no=1, **common))
+            with pytest.raises(IntegrityError) as exc_info:
+                s.flush()
+            assert is_duplicate_entry(exc_info.value), "应为唯一键冲突（1062）而非其他完整性错误"
+            s.rollback()
+
+    def test_正常路径版本号仍递增(self, client: TestClient, admin: dict, switched_on) -> None:
+        """常规编辑两次：送审版本号 1→2→3——锁读改写不得破坏既有行为。"""
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+
+        first = _latest_order(client, admin["headers"], data["business_no"])
+        assert first["version_no"] == 1
+
+        for ratio in ("60.00", "70.00"):
+            detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()[
+                "data"
+            ]
+            payload = business_payload(
+                detail["customer_id"],
+                secondary_allocations=[{"personnel_id": p["id"], "ratio": ratio}],
+            )
+            resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+            assert resp.status_code == 200, resp.text
+
+        third = _latest_order(client, admin["headers"], data["business_no"])
+        assert third["version_no"] == 3
+
+
+class TestConflictConvergence:
+    """编辑路径撞版本号唯一键 → 收敛为可重试的 400，业务数据不写坏。"""
+
+    def test_编辑路径版本号冲突_收敛为400(
+        self, client: TestClient, admin: dict, switched_on, monkeypatch
+    ) -> None:
+        from app.services import approval_service
+
+        p = _person(client, admin["headers"])
+        data = _create_with_plan(client, admin["headers"], p["id"])
+        before = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+
+        # 模拟取号读到过期快照：恒返回 1（库中 V1 已存在）→ 撞唯一键
+        monkeypatch.setattr(approval_service, "_next_version", lambda *a, **k: 1)
+
+        payload = business_payload(
+            before["customer_id"],
+            secondary_allocations=[{"personnel_id": p["id"], "ratio": "80.00"}],
+        )
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 400, resp.text
+        assert "版本号生成重复" in resp.json()["message"]
+
+        monkeypatch.undo()
+        # 业务数据不得写坏：整个事务回滚，方案仍是 50.00（V1 生效行）
+        after = client.get(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"]).json()["data"]
+        assert [a["ratio"] for a in after["secondary_allocations"]] == ["50.00"]
+        assert [h["version_no"] for h in after["allocation_history"]] == [1]

backend/tests/integration/test_audit_retry.py

@@ -0,0 +1,162 @@
+"""单据编号唯一键冲突重试的行为锁定（audit 上下文内循环重试）。
+
+守：1062 兜底重试若以「吞异常后 return 重入整个 create_*」实现，会产生
+三重缺陷 —— 外层审计把已回滚的首次尝试记成 success=True（假成功，与
+audit_service.py「上下文内不得吞掉异常后正常退出」的约定相反）、重试再
+开一层审计（违反「不支持嵌套」）、持续冲突时递归至 RecursionError。
+修复口径：审计上下文内 for 循环重试（上限 _NO_RETRY），成功/最终失败
+各恰好一条操作日志（以 POST 前的日志条数为基线断言增量）。
+
+制造冲突的手段：monkeypatch ``business_service._generate_no`` 首次返回
+库内已存在编号 → flush 撞唯一键 → 走重试分支。审计按 username 冗余溯
+源（账号删除后 user_id 被 SET NULL），断言以基线增量免受既有数据干扰。
+"""
+
+import uuid
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import func, select
+
+from app.core.constants import ACTION_CREATE, MODULE_BUSINESS
+from app.core.db import get_session_factory
+from app.main import app
+from app.models import OperationLog
+from app.services import business_service
+
+pytestmark = pytest.mark.integration
+
+_BUSINESSES = "/api/v1/business/businesses"
+_CUSTOMERS = "/api/v1/base/customers"
+
+
+@pytest.fixture
+def quiet_client():
+    """持续冲突用例依赖全局异常处理器产出 500 信封。
+
+    TestClient 默认对 ServerErrorMiddleware 的响应直接 re-raise
+    （raise_server_exceptions=True），会掩盖「原子处理器已正确收敛 500」
+    的行为本身 —— 审计断言反而无从谈起。
+    """
+    return TestClient(app, raise_server_exceptions=False)
+
+
+def _customer(client: TestClient, headers: dict) -> int:
+    resp = client.post(
+        _CUSTOMERS,
+        json={
+            "company_name": f"t_retry公司_{uuid.uuid4().hex[:8]}",
+            "owner_name": "张老板",
+            "customer_type": "personal",
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return int(resp.json()["data"]["id"])
+
+
+def _business_payload(customer_id: int) -> dict:
+    return {
+        "customer_id": customer_id,
+        "business_date": "2026-01-01",
+        "items": [
+            {
+                "product_name": f"t_产品_{uuid.uuid4().hex[:8]}",
+                "product_category": "municipal_water",
+                "quantity": "1.00",
+                "sale_price": "10.00",
+            }
+        ],
+    }
+
+
+def _log_count(username: str, *, success: bool) -> int:
+    """按操作人统计「创建业务」操作日志条数（日志按 username 冗余追溯）。"""
+    factory = get_session_factory()
+    with factory() as session:
+        stmt = (
+            select(func.count())
+            .select_from(OperationLog)
+            .where(
+                OperationLog.username == username,
+                OperationLog.module == MODULE_BUSINESS,
+                OperationLog.action == ACTION_CREATE,
+                OperationLog.summary.like("创建业务%"),
+                OperationLog.success == int(success),
+            )
+        )
+        return int(session.execute(stmt).scalar_one())
+
+
+def _baseline(normal: dict) -> tuple[int, int]:
+    """POST 前的「创建业务」成功/失败日志条数基线（免受既有数据干扰）。"""
+    return (
+        _log_count(normal["username"], success=True),
+        _log_count(normal["username"], success=False),
+    )
+
+
+class TestAuditRetry:
+    """重试成功与持续失败两条路径的审计记录数。"""
+
+    def test_首次撞号重试成功_审计恰一条真成功(
+        self, quiet_client: TestClient, normal: dict, monkeypatch
+    ) -> None:
+        client = quiet_client
+        customer_id = _customer(client, normal["headers"])
+        first = client.post(
+            _BUSINESSES, json=_business_payload(customer_id), headers=normal["headers"]
+        )
+        assert first.status_code == 200, first.text
+        existing_no = first.json()["data"]["business_no"]
+
+        real_generate = business_service._generate_no
+        calls = {"n": 0}
+
+        def flaky_generate(session):
+            calls["n"] += 1
+            if calls["n"] == 1:
+                return existing_no  # 首次返回库内已存在编号 → flush 撞 1062
+            return real_generate(session)
+
+        monkeypatch.setattr(business_service, "_generate_no", flaky_generate)
+        base_ok, base_fail = _baseline(normal)
+
+        second = client.post(
+            _BUSINESSES, json=_business_payload(customer_id), headers=normal["headers"]
+        )
+        assert second.status_code == 200, second.text
+        assert calls["n"] == 2, "重试应恰好再取一次号"
+        # 修复前的症状：外层审计正常退出记 success=True（假成功），重试成功
+        # 又记一条 —— 成功日志增量为 2；修复后成功恰 +1、失败 +0
+        assert _log_count(normal["username"], success=True) == base_ok + 1
+        assert _log_count(normal["username"], success=False) == base_fail
+
+    def test_持续冲突_最终失败且审计恰一条失败(
+        self, quiet_client: TestClient, normal: dict, monkeypatch
+    ) -> None:
+        client = quiet_client
+        customer_id = _customer(client, normal["headers"])
+        first = client.post(
+            _BUSINESSES, json=_business_payload(customer_id), headers=normal["headers"]
+        )
+        assert first.status_code == 200, first.text
+        existing_no = first.json()["data"]["business_no"]
+
+        def always_conflict(session):
+            return existing_no
+
+        monkeypatch.setattr(business_service, "_generate_no", always_conflict)
+        base_ok, base_fail = _baseline(normal)
+
+        second = client.post(
+            _BUSINESSES, json=_business_payload(customer_id), headers=normal["headers"]
+        )
+        # 未捕获 IntegrityError 由全局 handler 收敛 400（数据完整性冲突）——
+        # 完整性冲突对用户是「操作被拒绝」而非「服务端异常」，400 更贴近事实
+        assert second.status_code == 400, second.text
+        assert "完整性冲突" in second.json()["message"]
+        # 修复前的症状:return _retry_create 无界递归直至 RecursionError,
+        # 每层各写一条记录；修复后重试有上限,最终失败仅一条失败日志
+        assert _log_count(normal["username"], success=False) == base_fail + 1
+        assert _log_count(normal["username"], success=True) == base_ok

backend/tests/integration/test_business_roles.py

@@ -147,9 +147,18 @@ class TestBuiltinProtection:
 
 
 class TestPermission:
-    """权限：普通用户全部 403（当前默认管理员专用）。"""
+    """权限：管理接口普通用户 403；只读选项登录即可（报表筛选依赖）。"""
 
     def test_普通用户访问岗位列表_403(self, client: TestClient, make_user, auth_headers) -> None:
         user = make_user([ROLE_USER])
         headers = auth_headers(user)
         assert client.get(_ROLES, headers=headers).status_code == 403
+
+    def test_普通用户可读取岗位选项(self, client: TestClient, make_user, auth_headers) -> None:
+        """财务/领导做报表岗位筛选时不能因管理员接口 403 而失去筛选能力。"""
+        user = make_user([ROLE_USER])
+        headers = auth_headers(user)
+        resp = client.get("/api/v1/base/business-roles/options", headers=headers)
+        assert resp.status_code == 200, resp.text
+        codes = {row["role_code"] for row in resp.json()["data"]}
+        assert {"salesperson", "sales_manager", "info_officer"} <= codes

backend/tests/integration/test_businesses.py

@@ -225,6 +225,31 @@ class TestCreate:
         )
         assert resp.status_code == 400, resp.text
 
+    def test_行金额乘积显式两位固化_回显与库值一致(self, client: TestClient, normal: dict) -> None:
+        """数量(2位)×单价(4位) 可产 6 位小数：显式 HALF_UP 固化，与 MySQL 的
+        DECIMAL(14,2) 舍入方向一致 —— 直写不 quantize 会被库端静默舍入，
+        创建响应（读内存值）与复查（读库值）前后显示不一致。"""
+        headers = normal["headers"]
+        customer = _customer(client, headers)
+        data = _create(
+            client,
+            headers,
+            customer["id"],
+            items=[_item(quantity="1.55", sale_price="3.3333", cost_amount=None)],
+        )
+        # 1.55 × 3.3333 = 5.166615 → 5.17（HALF_UP；MySQL 同值同向）
+        item = client.get(f"{_BUSINESSES}/{data['id']}", headers=headers).json()["data"]["items"][0]
+        assert item["sale_amount"] == "5.17"
+        assert Decimal(data["total_sale_amount"]) == Decimal("5.17")
+
+        # 库值与回显一致（无「内存 5.166615 / 库里 5.17」的漂移）
+        factory = get_session_factory()
+        with factory() as session:
+            db_amount = session.execute(
+                select(BusinessItem.sale_amount).where(BusinessItem.business_id == data["id"])
+            ).scalar_one()
+        assert db_amount == Decimal("5.17")
+
     def test_明细行数量为0_400(self, client: TestClient, normal: dict) -> None:
         customer = _customer(client, normal["headers"])
         resp = client.post(
@@ -362,6 +387,96 @@ class TestEdit:
         ]
         assert logs["total"] == 0, "编辑端点改归属却无留痕"
 
+    def test_终态业务编辑_400且明细未动(self, client: TestClient, normal: dict) -> None:
+        """终态门槛与发货/回款写准入同口径：明细/汇总是 M3 核算基线，终态
+        业务禁改 —— 父单据若放行，发货/回款服务「禁写终态」的防线就被绕过。"""
+        headers = normal["headers"]
+        customer = _customer(client, headers)
+        data = _create(client, headers, customer["id"])
+        _terminate(client, headers, data["id"])
+
+        resp = client.put(
+            f"{_BUSINESSES}/{data['id']}",
+            json=_payload(
+                customer["id"],
+                items=[_item(quantity="999", sale_price="999.00")],
+            ),
+            headers=headers,
+        )
+        assert resp.status_code == 400, resp.text
+        assert "已完成或已终止" in resp.json()["message"]
+
+        # 明细与汇总未被改写（护栏：校验在 replace_items 之前生效）
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=headers).json()["data"]
+        assert Decimal(detail["total_sale_amount"]) == Decimal("10000")
+        assert len(detail["items"]) == 1
+        assert Decimal(detail["items"][0]["quantity"]) == Decimal("100")
+
+    def test_二次分配方案合计超100_保存400(self, client: TestClient, normal: dict) -> None:
+        """口径（澄清 #1/#2 答复 2026-10-19）：分配绩效、余额归合同负责人——
+        超 100% 会把负责人份额算成负数，保存侧先拦（核算侧另有防御）。"""
+        headers = normal["headers"]
+        customer = _customer(client, headers)
+        owner = _personnel(client, headers)
+        part = _personnel(client, headers)
+        data = _create(client, headers, customer["id"], owner_personnel_id=owner["id"])
+
+        resp = client.put(
+            f"{_BUSINESSES}/{data['id']}",
+            json=_payload(
+                customer["id"],
+                secondary_allocations=[
+                    {"personnel_id": part["id"], "ratio": "60"},
+                    {"personnel_id": _personnel(client, headers)["id"], "ratio": "50"},
+                ],
+            ),
+            headers=headers,
+        )
+        assert resp.status_code == 400, resp.text
+        assert "超过 100%" in resp.json()["message"]
+
+    def test_二次分配参与人含负责人_保存400(self, client: TestClient, normal: dict) -> None:
+        headers = normal["headers"]
+        customer = _customer(client, headers)
+        owner = _personnel(client, headers)
+        data = _create(client, headers, customer["id"], owner_personnel_id=owner["id"])
+
+        resp = client.put(
+            f"{_BUSINESSES}/{data['id']}",
+            json=_payload(
+                customer["id"],
+                secondary_allocations=[{"personnel_id": owner["id"], "ratio": "30"}],
+            ),
+            headers=headers,
+        )
+        assert resp.status_code == 400, resp.text
+        assert "含合同负责营销人员" in resp.json()["message"]
+
+    def test_二次分配方案合法比例_保存成功且回显(
+        self, client: TestClient, normal: dict
+    ) -> None:
+        headers = normal["headers"]
+        customer = _customer(client, headers)
+        owner = _personnel(client, headers)
+        part = _personnel(client, headers)
+        data = _create(client, headers, customer["id"], owner_personnel_id=owner["id"])
+
+        resp = client.put(
+            f"{_BUSINESSES}/{data['id']}",
+            json=_payload(
+                customer["id"],
+                secondary_allocations=[{"personnel_id": part["id"], "ratio": "40"}],
+            ),
+            headers=headers,
+        )
+        assert resp.status_code == 200, resp.text
+        # 方案在详情回包（更新回包为简版 Out，不含方案区）
+        detail = client.get(f"{_BUSINESSES}/{data['id']}", headers=headers).json()["data"]
+        assert len(detail["secondary_allocations"]) == 1
+        assert Decimal(detail["secondary_allocations"][0]["ratio"]) == Decimal("40")
+        # 余额 60% 归合同负责人（hint 文案 = #2 答复口径）
+        assert detail["allocation_hint"] is not None and "60" in detail["allocation_hint"]
+
 
 class TestStatus:
     """状态机：终态不可逆是终态单据禁写的前提；留痕从创建首条记起。"""

backend/tests/integration/test_calc.py

@@ -0,0 +1,790 @@
+"""单笔回款核算集成测试（M3 ④：金标准复算到分）。
+
+金标准场景（双类别混合业务，覆盖行级折算与汇总）：
+- 行1 市政水利：100×100.00 = 销售 10000，成本 3000 → 毛利率 0.7，阈值 30%
+  → 折算 10000×(0.7−0.3) = 4000
+- 行2 轨道交通：50×200.00 = 销售 10000，成本 8000 → 毛利率 0.2，阈值 20%
+  → 折算 10000×(0.2−0.2) = 0
+- 折算合计 4000；发货 10-01 → 回款 10-20，days=20
+- 率 = (10 − 20×4/360)‰ = 88/9000；绩效 = 4000×88/9000 ≈ 39.11
+- 回款 20000（=销售额 100%）→ R=100、权重 1 → 应付 = 39.11
+
+守的还有：核算粒度 #25（业务级一次性计提——第二笔回款仅登记进度）、
+已核算再核算 400、未指定批次 400、成本缺失行毛利按 0 计、负绩效照算、
+准入（normal 403 / marketing_ops 可用）。
+"""
+
+import uuid
+from decimal import Decimal
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import select
+
+from app.core.db import get_session_factory
+from app.models import PerformanceLedger, Personnel, Receipt, SecondaryAllocation
+from app.models.receipt import SETTLEMENT_DONE
+from tests.integration.factories import business_payload, customer
+
+pytestmark = pytest.mark.integration
+
+_CALC = "/api/v1/calc"
+_BUSINESSES = "/api/v1/business/businesses"
+_SHIPMENTS = "/api/v1/business/shipments"
+_RECEIPTS = "/api/v1/business/receipts"
+_PERSONNEL = "/api/v1/base/personnel"
+
+
+def _person(client: TestClient, headers: dict) -> dict:
+    resp = client.post(
+        _PERSONNEL,
+        json={
+            "personnel_name": f"t_核算_{uuid.uuid4().hex[:8]}",
+            "business_role_id": _role_id("salesperson"),
+            "salary_standard": "3000.00",
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def _role_id(code: str) -> int:
+    from sqlalchemy import select
+
+    from app.core.constants import BUSINESS_ROLE_SALESPERSON
+    from app.core.db import get_session_factory
+    from app.models import BusinessRole
+
+    factory = get_session_factory()
+    with factory() as session:
+        role_code = BUSINESS_ROLE_SALESPERSON if code == "salesperson" else code
+        return int(
+            session.execute(
+                select(BusinessRole.id).where(
+                    BusinessRole.role_code == role_code, BusinessRole.status == 1
+                )
+            ).scalar_one()
+        )
+
+
+def _create_full_chain(
+    client: TestClient,
+    headers: dict,
+    *,
+    items: list[dict],
+    ship_date: str,
+    receipt_date: str,
+    amount: str,
+) -> tuple[dict, dict]:
+    """客户 → 人员 → 业务（双行明细+归属）→ 发货 → 回款（指定批次）。"""
+    cust = customer(client, headers)
+    person = _person(client, headers)
+    resp = client.post(
+        _BUSINESSES,
+        json=business_payload(cust["id"], owner_personnel_id=person["id"], items=items),
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    biz = resp.json()["data"]
+
+    resp = client.post(
+        _SHIPMENTS,
+        json={
+            "business_id": biz["id"],
+            "ship_date": ship_date,
+            "items": [{"product_name": "t_发货物", "quantity": "1", "sale_price": "1.00"}],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    shipment = resp.json()["data"]
+
+    resp = client.post(
+        _RECEIPTS,
+        json={
+            "business_id": biz["id"],
+            "receipt_date": receipt_date,
+            "amount": amount,
+            "shipment_id": shipment["id"],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    receipt = resp.json()["data"]
+    return biz, receipt
+
+
+def _calc(client: TestClient, headers: dict, receipt_id: int):
+    return client.post(f"{_CALC}/receipts/{receipt_id}/calc", headers=headers)
+
+
+@pytest.fixture
+def finance(make_user, auth_headers) -> dict:
+    """财务角色账号（重算授权角色之一）。"""
+    user = make_user(["finance"])
+    user["headers"] = auth_headers(user)
+    return user
+
+
+_GOLD_ITEMS = [
+    {
+        "product_name": "t_市政_金标",
+        "product_category": "municipal_water",
+        "quantity": "100",
+        "sale_price": "100.00",
+        "cost_amount": "3000.00",
+    },
+    {
+        "product_name": "t_轨交_金标",
+        "product_category": "rail_transit",
+        "quantity": "50",
+        "sale_price": "200.00",
+        "cost_amount": "8000.00",
+    },
+]
+
+
+class TestGoldenStandard:
+    """金标准：双类别混合业务复算到分（Decimal 精确断言）。"""
+
+    def test_复算到分_全字段固化(self, client: TestClient, admin: dict) -> None:
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="20000.00",
+        )
+
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 200, resp.text
+        out = resp.json()["data"]
+        assert out["repeated"] is False
+
+        ledger = out["ledger"]
+        assert ledger["payment_days"] == 20
+        assert ledger["settlement_month"] == "2026-10"
+        # 率 = (10 − 20×4/360)‰ = 88/9000，Fraction 约分原文 11/1125
+        assert ledger["rate_text"] == "11/1125"
+        assert ledger["weight_r"] == 100
+        assert ledger["missing_cost"] == 0
+        assert ledger["snapshot_json"]["line_details"][0]["converted"] == "4000.00"
+
+        # 金额锚定 DB 事实源（NUMERIC(14,2) 读回恒两位；响应 JSON 的 Decimal
+        # 序列化 scale 不作断言——归前端展示问题）
+        factory = get_session_factory()
+        with factory() as session:
+            row = session.execute(
+                select(PerformanceLedger).where(
+                    PerformanceLedger.receipt_id == receipt["id"],
+                    PerformanceLedger.is_active == 1,
+                )
+            ).scalar_one()
+        assert row.converted_profit == Decimal("4000.00")
+        # 绩效 = 4000 × 88/9000 = 39.111… → 落库两位 39.11
+        assert row.performance_amount == Decimal("39.11")
+        # 应付 = 绩效 × 权重 1 = 39.11
+        assert row.payable_amount == Decimal("39.11")
+
+        # 回款状态被 CAS 置已核算
+        detail = client.get(f"{_RECEIPTS}/{receipt['id']}", headers=admin["headers"]).json()["data"]
+        assert detail["settlement_status"] == 1
+
+    def test_已核算回款再核算400(self, client: TestClient, admin: dict) -> None:
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="100.00",
+        )
+        assert _calc(client, admin["headers"], receipt["id"]).status_code == 200
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 400
+        assert "已核算" in resp.json()["message"]
+
+    def test_业务级一次性计提_第二笔仅登记进度(self, client: TestClient, admin: dict) -> None:
+        """核算粒度 #25 一期口径：同业务第二笔回款不重复计提。"""
+        biz, first = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="10000.00",
+        )
+        assert _calc(client, admin["headers"], first["id"]).status_code == 200
+
+        resp = client.post(
+            _RECEIPTS,
+            json={
+                "business_id": biz["id"],
+                "receipt_date": "2026-10-25",
+                "amount": "5000.00",
+                "shipment_id": None,
+            },
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        second = resp.json()["data"]
+
+        resp = _calc(client, admin["headers"], second["id"])
+        assert resp.status_code == 200, resp.text
+        out = resp.json()["data"]
+        assert out["repeated"] is True
+
+        factory = get_session_factory()
+        with factory() as session:
+            rows = (
+                session.execute(
+                    select(PerformanceLedger).where(
+                        PerformanceLedger.business_id == biz["id"],
+                        PerformanceLedger.is_active == 1,
+                    )
+                )
+                .scalars()
+                .all()
+            )
+            assert len(rows) == 1, "第二笔回款不得新增台账行（一次性计提）"
+            receipts = (
+                session.execute(select(Receipt).where(Receipt.business_id == biz["id"]))
+                .scalars()
+                .all()
+            )
+            assert all(r.settlement_status == SETTLEMENT_DONE for r in receipts)
+
+
+class TestGuards:
+    """校验链与策略点。"""
+
+    def test_未指定批次400(self, client: TestClient, admin: dict) -> None:
+        cust = customer(client, admin["headers"])
+        person = _person(client, admin["headers"])
+        resp = client.post(
+            _BUSINESSES,
+            json=business_payload(cust["id"], owner_personnel_id=person["id"]),
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200
+        biz = resp.json()["data"]
+        resp = client.post(
+            _RECEIPTS,
+            json={
+                "business_id": biz["id"],
+                "receipt_date": "2026-10-20",
+                "amount": "100.00",
+            },
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200
+        receipt = resp.json()["data"]
+
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 400
+        assert "发货批次" in resp.json()["message"]
+
+    def test_成本缺失行_毛利按0计并标记(self, client: TestClient, admin: dict) -> None:
+        items = [
+            {
+                "product_name": "t_无成本_市政",
+                "product_category": "municipal_water",
+                "quantity": "100",
+                "sale_price": "100.00",
+                "cost_amount": None,
+            }
+        ]
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=items,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="10000.00",
+        )
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 200, resp.text
+        ledger = resp.json()["data"]["ledger"]
+        # 成本缺失 → 毛利按 0 → 折算 = 销售额×(0−30%) = **−3000**（保守少算
+        # 方向：缺成本的行宁少算不多发），missing_cost=1
+        assert ledger["missing_cost"] == 1
+        assert float(ledger["converted_profit"]) == -3000.0
+        assert float(ledger["performance_amount"]) == pytest.approx(-29.33, abs=0.01)
+
+    def test_负绩效照算不归零(self, client: TestClient, admin: dict) -> None:
+        items = [
+            {
+                "product_name": "t_亏损_市政",
+                "product_category": "municipal_water",
+                "quantity": "100",
+                "sale_price": "100.00",
+                "cost_amount": "9000.00",
+            }
+        ]
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=items,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="10000.00",
+        )
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 200, resp.text
+        ledger = resp.json()["data"]["ledger"]
+        # 毛利 1000、率 0.1 < 阈值 30% → 折算 10000×(0.1−0.3) = −2000 → 负绩效
+        assert float(ledger["converted_profit"]) == -2000.0
+        assert float(ledger["performance_amount"]) < 0
+
+    def test_准入_normal403_marketing_ops可用(
+        self, client: TestClient, admin: dict, normal: dict, make_user, auth_headers
+    ) -> None:
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="100.00",
+        )
+        resp = _calc(client, normal["headers"], receipt["id"])
+        assert resp.status_code == 403
+
+        ops = make_user(["marketing_ops"])
+        ops["headers"] = auth_headers(ops)
+        resp = _calc(client, ops["headers"], receipt["id"])
+        assert resp.status_code == 200, resp.text
+
+    def test_分界天数参数小数原文_核算不500(self, client: TestClient, admin: dict) -> None:
+        """守 int(参数原文) 缺陷：INT 参数入库允许 '360.0'（Fraction 分母为 1），
+        直接 int(str) 抛 ValueError 会让整月核算 500。"""
+        resp = client.post(
+            "/api/v1/system/params/changes",
+            json={
+                "change_type": 1,
+                "remark": "用例：INT 参数小数原文",
+                "items": [
+                    {
+                        "param_code": "salesperson.days.boundary",
+                        "dimension_value": "salesperson",
+                        "value": "360.0",
+                    }
+                ],
+            },
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="20000.00",
+        )
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 200, resp.text
+        # 分界取整无损：20 天 < 360 天 → 同一递减公式
+        assert resp.json()["data"]["ledger"]["rate_text"] == "11/1125"
+
+    def test_台账列表与筛选(self, client: TestClient, admin: dict) -> None:
+        biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="100.00",
+        )
+        _calc(client, admin["headers"], receipt["id"])
+
+        resp = client.get(
+            f"{_CALC}/ledger",
+            params={"settlement_month": "2026-10", "is_active": 1},
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200
+        rows = resp.json()["data"]["list"]
+        assert rows and rows[0]["business_no"] == biz["business_no"]
+
+
+class TestRecalc:
+    """重算：授权动作，作废旧版本、落新版本并留痕。"""
+
+    def test_重算_新版本生效_旧版本保留(
+        self, client: TestClient, admin: dict, finance: dict
+    ) -> None:
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="20000.00",
+        )
+        assert _calc(client, admin["headers"], receipt["id"]).status_code == 200
+
+        fin = finance
+        resp = client.post(
+            f"{_CALC}/receipts/{receipt['id']}/recalc",
+            json={"reason": "成本录入修正"},
+            headers=fin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+
+        factory = get_session_factory()
+        with factory() as session:
+            rows = (
+                session.execute(
+                    select(PerformanceLedger)
+                    .where(PerformanceLedger.receipt_id == receipt["id"])
+                    .order_by(PerformanceLedger.calc_version)
+                )
+                .scalars()
+                .all()
+            )
+            assert [(r.calc_version, r.is_active) for r in rows] == [(1, 0), (2, 1)]
+            assert rows[1].calc_reason == "成本录入修正"
+        # 详情回显的是新版本
+        assert (
+            client.get(
+                f"{_CALC}/ledger",
+                params={"receipt_id": receipt["id"], "is_active": 1},
+                headers=admin["headers"],
+            ).json()["data"]["list"][0]["calc_version"]
+            == 2
+        )
+
+    def test_重算_原因缺失400(self, client: TestClient, admin: dict) -> None:
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="100.00",
+        )
+        assert _calc(client, admin["headers"], receipt["id"]).status_code == 200
+        resp = client.post(
+            f"{_CALC}/receipts/{receipt['id']}/recalc",
+            json={"reason": "  "},
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 400
+
+    def test_未核算过_重算400(self, client: TestClient, admin: dict) -> None:
+        _biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="100.00",
+        )
+        resp = client.post(
+            f"{_CALC}/receipts/{receipt['id']}/recalc",
+            json={"reason": "无旧版本"},
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 400
+        assert "尚未核算" in resp.json()["message"]
+
+    def test_进度登记回款重算400_不得凭空落行(self, client: TestClient, admin: dict) -> None:
+        """业务级一次性计提的第二笔回款无台账行；重算若落新行会双重计提。"""
+        biz, first = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="20000.00",
+        )
+        assert _calc(client, admin["headers"], first["id"]).status_code == 200
+        resp = client.post(
+            _RECEIPTS,
+            json={
+                "business_id": biz["id"],
+                "receipt_date": "2026-10-25",
+                "amount": "100.00",
+            },
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        second = resp.json()["data"]
+        assert _calc(client, admin["headers"], second["id"]).json()["data"]["repeated"] is True
+
+        resp = client.post(
+            f"{_CALC}/receipts/{second['id']}/recalc",
+            json={"reason": "尝试重算进度登记"},
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 400, resp.text
+        assert "进度登记" in resp.json()["message"]
+
+        # 同业务仍只有一行生效台账（未凭空新增）
+        factory = get_session_factory()
+        with factory() as session:
+            rows = (
+                session.execute(
+                    select(PerformanceLedger).where(
+                        PerformanceLedger.business_id == biz["id"],
+                        PerformanceLedger.is_active == 1,
+                    )
+                )
+                .scalars()
+                .all()
+            )
+            assert len(rows) == 1
+
+    def test_重算_普通用户与营销后勤403(
+        self, client: TestClient, normal: dict, make_user, auth_headers
+    ) -> None:
+        ops = make_user(["marketing_ops"])
+        ops["headers"] = auth_headers(ops)
+        for headers in (normal["headers"], ops["headers"]):
+            resp = client.post(f"{_CALC}/receipts/1/recalc", json={"reason": "x"}, headers=headers)
+            assert resp.status_code == 403
+
+
+class TestBatch:
+    """批量核算：逐笔独立事务，失败不中断。"""
+
+    def test_批量_逐笔成败清单(self, client: TestClient, admin: dict) -> None:
+        biz, r1 = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="20000.00",
+        )
+        # 同业务第二笔回款：核算走 #25 重复分支（ok=True、repeated=True）
+        resp = client.post(
+            _RECEIPTS,
+            json={
+                "business_id": biz["id"],
+                "receipt_date": "2026-10-25",
+                "amount": "100.00",
+            },
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        r2 = resp.json()["data"]
+
+        resp = client.post(
+            f"{_CALC}/batch",
+            json={"receipt_ids": [r1["id"], r2["id"], 999999]},
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        results = resp.json()["data"]
+        by_id = {r["receipt_id"]: r for r in results}
+        assert by_id[r1["id"]]["ok"] is True and by_id[r1["id"]]["repeated"] is False
+        assert by_id[r2["id"]]["ok"] is True and by_id[r2["id"]]["repeated"] is True
+        assert by_id[999999]["ok"] is False
+
+
+class TestSecondaryAllocation:
+    """二次分摊拆行（澄清 #1 答复 2026-10-19：分配绩效——算后分）。
+
+    方案行直插入库（跳过保存侧校验，聚焦核算引擎；保存侧校验用例在
+    test_businesses）。金标准：双类别混合业务绩效 39.11 / 折算 4000.00，
+    拆 30%+40% 后参与人 11.73/15.64、负责人余额 11.74，行合计守恒。
+    """
+
+    def _add_plan(self, business_id: int, rows: list[tuple[int, str]]) -> None:
+        """直插方案行（测试隔离造数；核算引擎按「当前落库方案」消费）。"""
+        factory = get_session_factory()
+        with factory() as session:
+            for pid, ratio in rows:
+                person = session.get(Personnel, pid)
+                session.add(
+                    SecondaryAllocation(
+                        business_id=business_id,
+                        personnel_id=pid,
+                        personnel_name=person.personnel_name,
+                        ratio=Decimal(ratio),
+                    )
+                )
+            session.commit()
+
+    def test_分摊拆行_参与人比例与负责人余额守恒(self, client: TestClient, admin: dict) -> None:
+        biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="20000.00",
+        )
+        parts = [_person(client, admin["headers"]) for _ in range(2)]
+        self._add_plan(biz["id"], [(parts[0]["id"], "30"), (parts[1]["id"], "40")])
+
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 200, resp.text
+
+        factory = get_session_factory()
+        with factory() as session:
+            rows = (
+                session.execute(
+                    select(PerformanceLedger).where(
+                        PerformanceLedger.receipt_id == receipt["id"],
+                        PerformanceLedger.is_active == 1,
+                    )
+                )
+                .scalars()
+                .all()
+            )
+            assert len(rows) == 3, "负责人+两参与人各一行"
+            by_pid = {r.personnel_id: r for r in rows}
+            a, b, o = (
+                by_pid[parts[0]["id"]],
+                by_pid[parts[1]["id"]],
+                by_pid[biz["owner_personnel_id"]],
+            )
+            # 绩效份额：A=39.11×30%=11.73、B=39.11×40%=15.64、负责人=守恒余额 11.74
+            assert (a.performance_amount, b.performance_amount, o.performance_amount) == (
+                Decimal("11.73"),
+                Decimal("15.64"),
+                Decimal("11.74"),
+            )
+            # 行合计 == 业务级全额（守恒是分摊红线：多一分少一分都是错账）
+            assert a.payable_amount + b.payable_amount + o.payable_amount == Decimal("39.11")
+            # 折算额同比例拆分：4000 的 30%/40%/余额
+            assert (a.converted_profit, b.converted_profit, o.converted_profit) == (
+                Decimal("1200.00"),
+                Decimal("1600.00"),
+                Decimal("1200.00"),
+            )
+            # 行级身份固化：参与人各自岗位；快照带方案与角色标签
+            # （ratio 为 NUMERIC(5,2) 读回两位 scale，断言用数值比较）
+            assert a.role_code == b.role_code == "salesperson"
+            assert a.snapshot_json["alloc_role"] == "participant"
+            assert Decimal(a.snapshot_json["alloc_ratio"]) == Decimal("30")
+            assert o.snapshot_json["alloc_role"] == "owner"
+            assert Decimal(o.snapshot_json["alloc_plan"][0]["ratio"]) == Decimal("30")
+
+    def test_分摊后第二笔回款仅登记进度(self, client: TestClient, admin: dict) -> None:
+        """一次性计提（#25）与分摊叠加：第二笔不新增行、不重复拆分。"""
+        biz, first = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="10000.00",
+        )
+        part = _person(client, admin["headers"])
+        self._add_plan(biz["id"], [(part["id"], "50")])
+        assert _calc(client, admin["headers"], first["id"]).status_code == 200
+
+        resp = client.post(
+            _RECEIPTS,
+            json={
+                "business_id": biz["id"],
+                "receipt_date": "2026-10-25",
+                "amount": "5000.00",
+            },
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        second = resp.json()["data"]
+        out = _calc(client, admin["headers"], second["id"]).json()["data"]
+        assert out["repeated"] is True
+
+        factory = get_session_factory()
+        with factory() as session:
+            rows = (
+                session.execute(
+                    select(PerformanceLedger).where(
+                        PerformanceLedger.business_id == biz["id"],
+                        PerformanceLedger.is_active == 1,
+                    )
+                )
+                .scalars()
+                .all()
+            )
+            assert len(rows) == 2, "第二笔回款不得新增拆分行（一次性计提）"
+
+    def test_重算作废全部拆分行并落新版本(
+        self, client: TestClient, admin: dict, finance: dict
+    ) -> None:
+        biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="20000.00",
+        )
+        parts = [_person(client, admin["headers"]) for _ in range(2)]
+        self._add_plan(biz["id"], [(parts[0]["id"], "30"), (parts[1]["id"], "40")])
+        assert _calc(client, admin["headers"], receipt["id"]).status_code == 200
+
+        resp = client.post(
+            f"{_CALC}/receipts/{receipt['id']}/recalc",
+            json={"reason": "用例：分摊重算"},
+            headers=finance["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+
+        factory = get_session_factory()
+        with factory() as session:
+            rows = (
+                session.execute(
+                    select(PerformanceLedger).where(PerformanceLedger.receipt_id == receipt["id"])
+                )
+                .scalars()
+                .all()
+            )
+            active = [r for r in rows if r.is_active == 1]
+            inactive = [r for r in rows if r.is_active == 0]
+            assert len(active) == 3 and len(inactive) == 3
+            assert {r.calc_version for r in active} == {2}, "新版本三行"
+            assert {r.calc_version for r in inactive} == {1}, "旧版本三行全部作废"
+
+    def test_合计超100核算侧拦截(self, client: TestClient, admin: dict) -> None:
+        biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="100.00",
+        )
+        part = _person(client, admin["headers"])
+        self._add_plan(biz["id"], [(part["id"], "60")])
+        # 再直插另一行绕过保存校验（合计 110），核算侧防御必须拦
+        other = _person(client, admin["headers"])
+        factory = get_session_factory()
+        with factory() as session:
+            person = session.get(Personnel, other["id"])
+            session.add(
+                SecondaryAllocation(
+                    business_id=biz["id"],
+                    personnel_id=other["id"],
+                    personnel_name=person.personnel_name,
+                    ratio=Decimal("50"),
+                )
+            )
+            session.commit()
+
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 400
+        assert "超过 100%" in resp.json()["message"]
+
+    def test_参与人含负责人核算侧拦截(self, client: TestClient, admin: dict) -> None:
+        biz, receipt = _create_full_chain(
+            client,
+            admin["headers"],
+            items=_GOLD_ITEMS,
+            ship_date="2026-10-01",
+            receipt_date="2026-10-20",
+            amount="100.00",
+        )
+        self._add_plan(biz["id"], [(biz["owner_personnel_id"], "30")])
+        resp = _calc(client, admin["headers"], receipt["id"])
+        assert resp.status_code == 400
+        assert "含合同负责营销人员" in resp.json()["message"]

backend/tests/integration/test_customers.py

@@ -151,9 +151,7 @@ class TestCrudFlow:
         assert dup.status_code == 400, dup.text
         assert "该公司名称与负责人的客户已存在" in dup.json()["message"]
 
-    def test_删除被业务引用的客户_400引导处理单据(
+    def test_删除被业务引用的客户_400引导处理单据(self, client: TestClient, normal: dict) -> None:
-        self, client: TestClient, normal: dict
-    ) -> None:
         """业务表就位后删除保护补齐：FK RESTRICT 不能以 500 暴露。"""
         headers = normal["headers"]
         customer = _create_customer(client, headers)

backend/tests/integration/test_dashboard.py

@@ -0,0 +1,459 @@
+"""工作台集成测试（M4 ⑧）。
+
+守的口径：
+- 权限：普通用户 403 且文案「无权访问工作台」
+- 总览：绩效合计/人数与台账一致；月份参数非法 400
+- 待办：月结提交后出现待审批；回款未指定批次可命中；同步未建时显式降级
+- 风险预警：审批超时命中、参数关闭后不产生条目、阈值参数化生效
+- 最近动态：来源操作日志（写操作可见）
+
+待办与预警为实时派生（不落表），测试只验证查询结果，不清理派生数据。
+"""
+
+import uuid
+from datetime import date, datetime, timedelta
+from decimal import Decimal
+
+import pytest
+from fastapi.testclient import TestClient
+
+pytestmark = pytest.mark.integration
+
+_DASHBOARD = "/api/v1/dashboard"
+_PERSONNEL = "/api/v1/base/personnel"
+_BUSINESSES = "/api/v1/business/businesses"
+_SHIPMENTS = "/api/v1/business/shipments"
+_RECEIPTS = "/api/v1/business/receipts"
+_CALC = "/api/v1/calc"
+_SETTLEMENTS = "/api/v1/settlements"
+_PARAMS = "/api/v1/system/params"
+
+
+def _role_id(code: str) -> int:
+    from sqlalchemy import select
+
+    from app.core.db import get_session_factory
+    from app.models import BusinessRole
+
+    factory = get_session_factory()
+    with factory() as session:
+        return int(
+            session.execute(
+                select(BusinessRole.id).where(
+                    BusinessRole.role_code == code, BusinessRole.status == 1
+                )
+            ).scalar_one()
+        )
+
+
+def _person(client: TestClient, headers: dict) -> dict:
+    resp = client.post(
+        _PERSONNEL,
+        json={
+            "personnel_name": f"t_工作台_{uuid.uuid4().hex[:8]}",
+            "business_role_id": _role_id("salesperson"),
+            "salary_standard": "3000.00",
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def _chain(client: TestClient, headers: dict, *, assign_shipment: bool = True) -> dict:
+    """客户/业务（100×100，成本 3000）→ 发货（60 天前）→ 回款 → 核算。"""
+    from tests.integration.factories import business_item, business_payload, customer
+
+    cust = customer(client, headers)
+    person = _person(client, headers)
+    resp = client.post(
+        _BUSINESSES,
+        json=business_payload(
+            cust["id"],
+            owner_personnel_id=person["id"],
+            items=[business_item(cost_amount="3000.00")],
+        ),
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    business = resp.json()["data"]
+
+    ship_date = (date.today() - timedelta(days=60)).isoformat()
+    resp = client.post(
+        _SHIPMENTS,
+        json={
+            "business_id": business["id"],
+            "ship_date": ship_date,
+            "items": [{"product_name": "t_工作台发货", "quantity": "1", "sale_price": "1.00"}],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    shipment = resp.json()["data"]
+
+    payload = {
+        "business_id": business["id"],
+        "receipt_date": date.today().isoformat(),
+        "amount": "10000.00",
+    }
+    if assign_shipment:
+        payload["shipment_id"] = shipment["id"]
+    resp = client.post(_RECEIPTS, json=payload, headers=headers)
+    assert resp.status_code == 200, resp.text
+    receipt = resp.json()["data"]
+    if assign_shipment:
+        resp = client.post(f"{_CALC}/receipts/{receipt['id']}/calc", headers=headers)
+        assert resp.status_code == 200, resp.text
+    return {"business": business, "person": person, "receipt": receipt}
+
+
+def _month() -> str:
+    return date.today().strftime("%Y-%m")
+
+
+def _dashboard(client: TestClient, headers: dict, month: str | None = None) -> dict:
+    params = {"month": month} if month else {}
+    resp = client.get(_DASHBOARD, params=params, headers=headers)
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def test_权限_普通用户403文案(client: TestClient, normal: dict):
+    resp = client.get(_DASHBOARD, headers=normal["headers"])
+    assert resp.status_code == 403
+    assert resp.json()["message"] == "无权访问工作台"
+
+
+def test_总览_绩效合计与台账一致且非法月份400(client: TestClient, admin: dict):
+    _chain(client, admin["headers"])
+    data = _dashboard(client, admin["headers"], _month())
+
+    from sqlalchemy import func, select
+
+    from app.core.db import get_session_factory
+    from app.models import PerformanceLedger
+
+    factory = get_session_factory()
+    with factory() as session:
+        expected = Decimal(
+            str(
+                session.execute(
+                    select(
+                        func.coalesce(func.sum(PerformanceLedger.performance_amount), 0)
+                    ).where(
+                        PerformanceLedger.settlement_month == _month(),
+                        PerformanceLedger.calc_type == 1,
+                        PerformanceLedger.is_active == 1,
+                    )
+                ).scalar_one()
+            )
+        )
+    assert Decimal(str(data["overview"]["performance_total"])) == expected
+    assert data["overview"]["person_count"] >= 1
+    assert len(data["overview"]["trend"]) == 6
+
+    resp = client.get(_DASHBOARD, params={"month": "2026-13"}, headers=admin["headers"])
+    assert resp.status_code == 400
+
+
+def test_待办_待审批与未指定批次与同步降级(client: TestClient, admin: dict):
+    # 先造一笔已核算业务（月结生成要求有可结算记录），再补一笔未指定批次的回款
+    _chain(client, admin["headers"], assign_shipment=True)
+    ctx = _chain(client, admin["headers"], assign_shipment=False)
+    # 月结提交 → 产生待审批单
+    resp = client.post(
+        f"{_SETTLEMENTS}/generate", json={"month": _month()}, headers=admin["headers"]
+    )
+    assert resp.status_code == 200, resp.text
+    settlement_id = resp.json()["data"]["id"]
+    resp = client.post(
+        f"{_SETTLEMENTS}/{settlement_id}/submit", headers=admin["headers"]
+    )
+    assert resp.status_code == 200, resp.text
+
+    data = _dashboard(client, admin["headers"])
+    assert data["todos"]["pending_approval_total"] >= 1
+    assert any(
+        item["order_type"] == 2 for item in data["todos"]["pending_approvals"]
+    )
+    assert data["todos"]["unassigned_receipt_total"] >= 1
+    assert data["todos"]["unassigned_receipts"][0]["receipt_id"] == ctx["receipt"]["id"]
+    # ⑥ 未建：显式降级
+    assert data["todos"]["sync_available"] is False
+
+
+def test_预警_审批超时命中且参数关闭后不产生(client: TestClient, admin: dict):
+    _chain(client, admin["headers"])
+    resp = client.post(
+        f"{_SETTLEMENTS}/generate", json={"month": _month()}, headers=admin["headers"]
+    )
+    settlement_id = resp.json()["data"]["id"]
+    client.post(f"{_SETTLEMENTS}/{settlement_id}/submit", headers=admin["headers"])
+
+    # 把待审批单提交时间改到 4 天前（阈值默认 3 天）
+    from sqlalchemy import update
+
+    from app.core.db import get_session_factory
+    from app.models import ApprovalOrder
+
+    factory = get_session_factory()
+    with factory() as session:
+        session.execute(
+            update(ApprovalOrder)
+            .where(ApprovalOrder.status.in_((1, 2)))
+            .values(create_time=datetime.now() - timedelta(days=4))
+        )
+        session.commit()
+
+    data = _dashboard(client, admin["headers"])
+    assert data["warnings"]["enabled"] is True
+    assert any(item["code"] == "approval_timeout" for item in data["warnings"]["items"])
+
+    # 关闭预警开关 → 不产生条目
+    resp = client.post(
+        f"{_PARAMS}/changes",
+        json={
+            "change_type": 1,
+            "remark": "e2e 工作台测试：关闭风险预警",
+            "items": [{"param_code": "warning.enabled", "dimension_value": "", "value": "0"}],
+        },
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = _dashboard(client, admin["headers"])
+    assert data["warnings"]["enabled"] is False
+    assert data["warnings"]["items"] == []
+
+
+def test_动态_来源操作日志(client: TestClient, admin: dict):
+    _chain(client, admin["headers"])
+    data = _dashboard(client, admin["headers"])
+    assert data["activities"], "工作台动态为空：写操作应产生操作日志"
+    assert {"module", "action", "summary", "create_time"} <= set(data["activities"][0])
+
+
+# ==== 角色待办 / 预警阈值 / 趋势（2026-10-19 code-review 修复回归）====
+
+
+@pytest.fixture
+def finance(make_user, auth_headers) -> dict:
+    user = make_user(["finance"])
+    user["headers"] = auth_headers(user)
+    return user
+
+
+@pytest.fixture
+def leader(make_user, auth_headers) -> dict:
+    user = make_user(["leader"])
+    user["headers"] = auth_headers(user)
+    return user
+
+
+def _insert_approval(status: int) -> None:
+    """直插在途审批单（避免依赖两次流转，专注工作台过滤口径）。
+
+    ``ref_id`` 仅作对象分组锚点、本用例不校验：**每张单必须给不同的
+    ref_id**——V12 的 ``uk_approval_orders_order_type_ref_version`` 要求
+    (order_type, ref_id, version_no) 唯一，同一假对象连插两张 version_no=1
+    会撞 1062。
+    """
+    from app.core.db import get_session_factory
+    from app.models import ApprovalOrder
+
+    factory = get_session_factory()
+    with factory() as session:
+        session.add(
+            ApprovalOrder(
+                order_no=f"AP{uuid.uuid4().hex[:12]}",
+                order_type=2,
+                ref_id=status,
+                refer_no="t_工作台",
+                status=status,
+                submitter_name="t_admin",
+            )
+        )
+        session.commit()
+
+
+def _set_param(client: TestClient, headers: dict, code: str, value: str) -> None:
+    resp = client.post(
+        f"{_PARAMS}/changes",
+        json={
+            "change_type": 1,
+            "remark": f"t_工作台：{code}",
+            "items": [{"param_code": code, "dimension_value": "", "value": value}],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+
+
+def _shipment_scene(client: TestClient, headers: dict, *, days_ago: int) -> tuple[dict, dict]:
+    """造一笔无回款的发货（用于回款逾期预警）。"""
+    from tests.integration.factories import business_item, business_payload, customer
+
+    person = _person(client, headers)
+    cust = customer(client, headers)
+    resp = client.post(
+        _BUSINESSES,
+        json=business_payload(
+            cust["id"],
+            owner_personnel_id=person["id"],
+            items=[business_item(cost_amount="3000.00")],
+        ),
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    business = resp.json()["data"]
+    ship_date = (date.today() - timedelta(days=days_ago)).isoformat()
+    resp = client.post(
+        _SHIPMENTS,
+        json={
+            "business_id": business["id"],
+            "ship_date": ship_date,
+            "items": [{"product_name": "t_工作台逾期", "quantity": "1", "sale_price": "1.00"}],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return business, resp.json()["data"]
+
+
+def test_待办_按角色仅显示可操作节点(
+    client: TestClient, admin: dict, finance: dict, leader: dict, make_user, auth_headers
+):
+    """财务只看到待财务复核、领导只看到待领导审核；admin 与多角色看并集。"""
+    _insert_approval(1)
+    _insert_approval(2)
+
+    assert _dashboard(client, finance["headers"])["todos"]["pending_approval_total"] == 1
+    assert _dashboard(client, leader["headers"])["todos"]["pending_approval_total"] == 1
+    assert _dashboard(client, admin["headers"])["todos"]["pending_approval_total"] == 2
+
+    both = make_user(["finance", "leader"])
+    both["headers"] = auth_headers(both)
+    assert _dashboard(client, both["headers"])["todos"]["pending_approval_total"] == 2
+
+    finance_orders = {
+        item["order_no"] for item in _dashboard(client, finance["headers"])["todos"]["pending_approvals"]
+    }
+    leader_orders = {
+        item["order_no"] for item in _dashboard(client, leader["headers"])["todos"]["pending_approvals"]
+    }
+    assert finance_orders.isdisjoint(leader_orders)
+
+
+def test_待办_财务通过后领导出现待办(
+    client: TestClient, admin: dict, finance: dict, leader: dict
+):
+    """真实流转：财务节点通过后，条目从财务待办消失并进入领导待办。"""
+    _chain(client, admin["headers"])
+    resp = client.post(
+        f"{_SETTLEMENTS}/generate", json={"month": _month()}, headers=admin["headers"]
+    )
+    assert resp.status_code == 200, resp.text
+    settlement_id = resp.json()["data"]["id"]
+    resp = client.post(
+        f"{_SETTLEMENTS}/{settlement_id}/submit", headers=admin["headers"]
+    )
+    assert resp.status_code == 200, resp.text
+
+    order = _dashboard(client, admin["headers"])["todos"]["pending_approvals"][0]
+    assert _dashboard(client, finance["headers"])["todos"]["pending_approval_total"] == 1
+    assert _dashboard(client, leader["headers"])["todos"]["pending_approval_total"] == 0
+
+    resp = client.post(
+        f"/api/v1/system/approvals/{order['order_id']}/action",
+        json={"action": 1},
+        headers=finance["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    assert _dashboard(client, finance["headers"])["todos"]["pending_approval_total"] == 0
+    assert _dashboard(client, leader["headers"])["todos"]["pending_approval_total"] == 1
+
+
+def test_预警_回款逾期命中且阈值参数生效(client: TestClient, admin: dict):
+    """发货超阈值且无任何回款 → 命中；调大阈值后不再命中。"""
+    _, shipment = _shipment_scene(client, admin["headers"], days_ago=120)
+
+    data = _dashboard(client, admin["headers"])
+    assert any(
+        item["code"] == "receipt_overdue" and item["object_id"] == shipment["id"]
+        for item in data["warnings"]["items"]
+    ), "120 天未回款的发货批次未命中预警"
+
+    _set_param(client, admin["headers"], "warning.receipt.overdue.days", "200")
+    data = _dashboard(client, admin["headers"])
+    assert not any(
+        item["code"] == "receipt_overdue" and item["object_id"] == shipment["id"]
+        for item in data["warnings"]["items"]
+    ), "阈值调大后仍命中，说明参数未生效"
+
+
+def test_预警_终止业务不再产生回款逾期(client: TestClient, admin: dict):
+    """已终止业务不再催收，其未回款发货单不得留在预警列表。"""
+    business, shipment = _shipment_scene(client, admin["headers"], days_ago=120)
+    resp = client.put(
+        f"{_BUSINESSES}/{business['id']}/status",
+        json={"status": 3, "reason": "t_工作台终止"},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+
+    data = _dashboard(client, admin["headers"])
+    assert not any(item["object_id"] == shipment["id"] for item in data["warnings"]["items"])
+    assert data["warnings"]["receipt_overdue_total"] == 0
+
+
+def test_预警_总数不受展示上限截断(client: TestClient, admin: dict, monkeypatch):
+    """items 只展示前 N 条，徽标 total 必须仍是全量命中数。"""
+    from app.services import dashboard_service
+
+    _shipment_scene(client, admin["headers"], days_ago=120)
+    _shipment_scene(client, admin["headers"], days_ago=120)
+    monkeypatch.setattr(dashboard_service, "_WARNING_LIMIT", 1)
+
+    data = _dashboard(client, admin["headers"])
+    assert data["warnings"]["total"] == 2
+    assert len(data["warnings"]["items"]) == 1
+    assert data["warnings"]["total"] == data["warnings"]["receipt_overdue_total"]
+
+
+def test_总览_回款趋势按到账月跨月归属(client: TestClient, admin: dict):
+    """趋势窗口按 receipt_date 范围过滤，月初/月末不得串月。"""
+    from tests.integration.factories import business_item, business_payload, customer
+
+    person = _person(client, admin["headers"])
+    cust = customer(client, admin["headers"])
+    resp = client.post(
+        _BUSINESSES,
+        json=business_payload(
+            cust["id"],
+            owner_personnel_id=person["id"],
+            items=[business_item(cost_amount="3000.00")],
+        ),
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    business = resp.json()["data"]
+
+    first_of_month = date.today().replace(day=1)
+    previous_last = first_of_month - timedelta(days=1)
+    for receipt_date in (previous_last, first_of_month):
+        resp = client.post(
+            _RECEIPTS,
+            json={
+                "business_id": business["id"],
+                "receipt_date": receipt_date.isoformat(),
+                "amount": "1000.00",
+            },
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+
+    trend = {
+        item["month"]: Decimal(str(item["receipt_total"] or 0))
+        for item in _dashboard(client, admin["headers"])["overview"]["trend"]
+    }
+    assert trend[previous_last.strftime("%Y-%m")] == Decimal("1000.00")
+    assert trend[first_of_month.strftime("%Y-%m")] == Decimal("1000.00")

backend/tests/integration/test_no_generator.py

@@ -0,0 +1,82 @@
+"""单据编号生成器的跨位宽正确性（no_generator）。
+
+守：当日序号超过 4 位宽度（9999→10000）后，VARCHAR 字典序排序会失效
+（"-10000" < "-9999"，'1'<'9'）——MAX 检索若按纯字典序，seq 会恒重算出
+同一号码，每笔建单都撞唯一键。修复口径：长度优先、同级按字典序
+（同前缀下长度大即数值大；同长时字典序与数值序一致）。
+"""
+
+import pytest
+from sqlalchemy import select
+
+from app.core.constants import NO_PREFIX_BUSINESS
+from app.core.db import get_session_factory
+from app.models import Business, Customer
+from app.services.no_generator import next_no, today_prefix
+
+pytestmark = pytest.mark.integration
+
+
+def _insert_business_nos(nos: list[str]) -> None:
+    """直插同日前缀的业务编号行（仅编号用于 MAX 检索；其余列取默认/可空）。
+
+    直插绕过服务层（服务层走完整创建链太重），业务行为挂在 t_ 客户名下，
+    由 integration/conftest 兜底清理（YW% 单据 + t\\_% 客户）。
+    """
+    factory = get_session_factory()
+    with factory() as session:
+        customer = Customer(
+            company_name="t_no_generator_client",
+            owner_name="t_no_generator_owner",
+            customer_type="enterprise",
+        )
+        session.add(customer)
+        session.flush()
+        session.add_all(Business(business_no=no, customer_id=customer.id) for no in nos)
+        session.commit()
+
+
+class TestMaxCrossWidth:
+    """MAX 检索在同日前缀下跨位宽取最大序号。"""
+
+    def test_序号破四位宽后仍按数值取最大(self) -> None:
+        """4 位与 5 位并存："-9999" 字典序大于 "-10000"，纯字典序会取错。"""
+        prefix = today_prefix(NO_PREFIX_BUSINESS)
+        _insert_business_nos([f"{prefix}9999", f"{prefix}10000"])
+        factory = get_session_factory()
+        with factory() as session:
+            no = next_no(
+                session, model=Business, column_name="business_no", prefix=NO_PREFIX_BUSINESS
+            )
+        assert no == f"{prefix}10001"
+
+    def test_同位宽内字典序与数值序一致仍取最大(self) -> None:
+        """同宽多行（修复的排序不破坏原行为）：是长度优先而非只按长度取首行。"""
+        prefix = today_prefix(NO_PREFIX_BUSINESS)
+        _insert_business_nos([f"{prefix}0099", f"{prefix}8499", f"{prefix}8500"])
+        factory = get_session_factory()
+        with factory() as session:
+            no = next_no(
+                session, model=Business, column_name="business_no", prefix=NO_PREFIX_BUSINESS
+            )
+        assert no == f"{prefix}8501"
+
+    def test_无当日编号时从1起编(self) -> None:
+        """当日无同前缀行（昨日编号不被 like 命中）：从 0001 起，不受历史天数影响。
+
+        当日若已有其他用例留下的同前缀编号（用例间无隔离库），跳过——
+        空表场景由每次 `down -v` 重建后的首个用例覆盖。
+        """
+        prefix = today_prefix(NO_PREFIX_BUSINESS)
+        factory = get_session_factory()
+        with factory() as session:
+            existing = session.execute(
+                select(Business.id).where(Business.business_no.like(f"{prefix}%")).limit(1)
+            ).scalar()
+        if existing is not None:
+            pytest.skip(f"当日已有同前缀编号 {existing}，空表场景跳过")
+        with factory() as session:
+            no = next_no(
+                session, model=Business, column_name="business_no", prefix=NO_PREFIX_BUSINESS
+            )
+        assert no == f"{prefix}0001"

backend/tests/integration/test_param_management.py

@@ -11,6 +11,7 @@
 运行前置：``docker compose -f docker/docker-compose.dev.yml up -d``
 """
 
+import uuid
 from datetime import date, timedelta
 from fractions import Fraction
 
@@ -49,6 +50,31 @@ def track_batches():
         session.commit()
 
 
+@pytest.fixture
+def make_role_info(client: TestClient, admin: dict):
+    """造一个信息员模板岗位（t_ 前缀），返回 role_code，用例结束删除。
+
+    信息员分支的预览需要 TPL_INFO_SALES_FIXED 模板的非内置岗位；
+    内置 info_officer 的模板即为此模板，自定义岗位用于隔离造数。
+    """
+    code = f"t_info_{uuid.uuid4().hex[:6]}"
+    resp = client.post(
+        "/api/v1/system/business-roles",
+        json={
+            "role_code": code,
+            "role_name": "集成信息员",
+            "calc_template": "TPL_INFO_SALES_FIXED",
+        },
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    role_id = resp.json()["data"]["id"]
+    try:
+        yield code
+    finally:
+        client.delete(f"/api/v1/system/business-roles/{role_id}", headers=admin["headers"])
+
+
 def _snapshot_value(client: TestClient, admin: dict, param_code: str, *, as_of: str) -> str | None:
     """从目录接口取某参数默认维度的当前生效值。"""
     items = client.get(_PARAMS, params={"as_of": as_of}, headers=admin["headers"]).json()["data"]
@@ -60,9 +86,10 @@ def _snapshot_value(client: TestClient, admin: dict, param_code: str, *, as_of:
 class TestCatalog:
     """参数目录：种子完整性与时点化回溯。"""
 
-    def test_目录共16项且覆盖七个分组(self, client: TestClient, admin: dict) -> None:
+    def test_目录共22项且覆盖九个分组(self, client: TestClient, admin: dict) -> None:
+        """V10 起含工作台预警规则三项（16 计提项 + 3 BOOL 开关 + 3 预警项）。"""
         items = client.get(_PARAMS, headers=admin["headers"]).json()["data"]
-        assert len(items) == 16
+        assert len(items) == 22
         groups = {item["param_group"] for item in items}
         assert groups == {
             "业务员个人户",
@@ -72,6 +99,8 @@ class TestCatalog:
             "支付环节",
             "产品阈值",
             "月工资口径",
+            "审批开关",
+            "预警规则",
         }
 
     def test_企业户比例按到账日回溯_2千分3千分双种子(self, client: TestClient, admin: dict) -> None:
@@ -328,14 +357,104 @@ class TestPreview:
             == 400
         )
 
+    def test_企业户_千分比换算后金额精确(self, client: TestClient, admin: dict) -> None:
+        """企业户分支：enterprise.rate 存储 "3"（3‰），须换算为 3/1000 再相乘。
+
+        修复前把存储值当纯比例直接乘，performance_amount 会放大 1000 倍
+        （15000 × 3 = 45000）；既有用例只覆盖业务员路径，缺陷因此存活。
+        """
+        payload = {
+            "customer_type": "enterprise",
+            "product_category": "municipal_water",
+            "ship_date": "2025-12-15",
+            "receipt_date": "2026-01-10",
+            "revenue": "100000",
+            "profit": "45000",
+            "received_amount": "100000",
+        }
+        data = client.post(f"{_PARAMS}/preview", json=payload, headers=admin["headers"]).json()[
+            "data"
+        ]
+        assert Fraction(data["rate"]) == Fraction(3, 1000)
+        # 折算毛利润额 15000 × 3‰ = 45（修复前误返回 45000）
+        assert Fraction(data["performance_amount"]) == Fraction(45)
+        # 全额回款 R=100 → 权重 1，可付 == 绩效
+        assert data["payment_weight_r"] == 100
+        assert Fraction(data["payable_amount"]) == Fraction(45)
+
+    def test_信息员_销售额基数乘千分比例(
+        self, client: TestClient, admin: dict, make_role_info
+    ) -> None:
+        """信息员模板：基数覆盖为本人销售额（不走折算与阈值），比例 1‰。
+
+        修复前 take("info.rate")（存储 "1"）直接当纯比例乘出本人销售额原额。
+        """
+        payload = {
+            "business_role": make_role_info,
+            "customer_type": "personal",
+            "ship_date": "2025-12-15",
+            "receipt_date": "2026-01-10",
+            "revenue": "100000",
+            "profit": "45000",
+            "received_amount": "100000",
+        }
+        data = client.post(f"{_PARAMS}/preview", json=payload, headers=admin["headers"]).json()[
+            "data"
+        ]
+        # 基数覆盖为本人销售额：converted_profit == revenue（不扣阈值）
+        assert Fraction(data["converted_profit"]) == Fraction(100000)
+        assert Fraction(data["rate"]) == Fraction(1, 1000)
+        # 100000 × 1‰ = 100
+        assert Fraction(data["performance_amount"]) == Fraction(100)
+
+    def test_提交后维度取库里规范值(self, client: TestClient, admin: dict, track_batches) -> None:
+        """岗位维度大小写归一：ci 校对下变形大小写可提交成功，但须落库规范值。
+
+        快照与注册表按精确键取值，原始大小写入库会让覆盖链静默不命中
+        （按错误参数算钱且无报错）。business_roles.role_code 唯一键的 ci
+        等价冲突由 IntegrityError 分支翻译 400 兜底。
+        """
+        resp = client.post(
+            f"{_PARAMS}/changes",
+            json={
+                "change_type": 1,
+                "items": [
+                    {"param_code": "info.rate", "dimension_value": "SALESPERSON", "value": "2"}
+                ],
+            },
+            headers=admin["headers"],
+        )
+        assert resp.status_code in (200, 400), resp.text
+        if resp.status_code == 400:
+            pytest.skip("种子岗位未命中（见断言），规范值回读由造岗位链路覆盖")
+        batch = resp.json()["data"]
+        track_batches(batch["id"])
+        detail = client.get(f"{_PARAMS}/changes/{batch['id']}", headers=admin["headers"]).json()[
+            "data"
+        ]
+        dims = [item["dimension_value"] for item in detail["items"]]
+        assert "salesperson" in dims
+        assert "SALESPERSON" not in dims
+
 
 class TestPermission:
-    """权限：普通用户全部 403。"""
+    """权限分层（澄清 #17 答复 2026-10-19）：查看可（登录即可）、修改仅管理员。"""
 
-    def test_普通用户访问目录与提交_403(self, client: TestClient, make_user, auth_headers) -> None:
+    def test_普通用户查看目录_200(self, client: TestClient, make_user, auth_headers) -> None:
+        user = make_user([ROLE_USER])
+        headers = auth_headers(user)
+        resp = client.get(_PARAMS, headers=headers)
+        assert resp.status_code == 200
+        assert len(resp.json()["data"]) == 22
+
+    def test_未登录访问目录_403(self, client: TestClient) -> None:
+        # LoginUser 依赖无令牌即拒（401 语义归登录态失效，此处由依赖抛 403/401
+        # 均属拦截；显式断言不泄露数据即可）
+        assert client.get(_PARAMS).status_code in (401, 403)
+
+    def test_普通用户提交变更_403(self, client: TestClient, make_user, auth_headers) -> None:
         user = make_user([ROLE_USER])
         headers = auth_headers(user)
-        assert client.get(_PARAMS, headers=headers).status_code == 403
         resp = client.post(
             f"{_PARAMS}/changes",
             json={
@@ -345,3 +464,8 @@ class TestPermission:
             headers=headers,
         )
         assert resp.status_code == 403
+
+    def test_普通用户撤回批次_403(self, client: TestClient, make_user, auth_headers) -> None:
+        user = make_user([ROLE_USER])
+        headers = auth_headers(user)
+        assert client.delete(f"{_PARAMS}/changes/1", headers=headers).status_code == 403

backend/tests/integration/test_personnel.py

@@ -235,7 +235,9 @@ class TestDeleteProtection:
         member = _create(client, headers, manager_id=manager["id"])  # 团队成员占用
         blocked = client.delete(f"{_PERSONNEL}/{manager['id']}", headers=headers)
         assert blocked.status_code == 400, blocked.text
-        assert "存在团队成员、客户归属或业务归属引用，请改为离职而非删除" in blocked.json()["message"]
+        assert (
+            "存在团队成员、客户归属或业务归属引用，请改为离职而非删除" in blocked.json()["message"]
+        )
 
         client.delete(f"{_PERSONNEL}/{member['id']}", headers=headers)
         freed = client.delete(f"{_PERSONNEL}/{manager['id']}", headers=headers)
@@ -261,7 +263,9 @@ class TestDeleteProtection:
 
         blocked = client.delete(f"{_PERSONNEL}/{owner['id']}", headers=headers)
         assert blocked.status_code == 400, blocked.text
-        assert "存在团队成员、客户归属或业务归属引用，请改为离职而非删除" in blocked.json()["message"]
+        assert (
+            "存在团队成员、客户归属或业务归属引用，请改为离职而非删除" in blocked.json()["message"]
+        )
 
         # 保护与在职状态无关：离职并不能让物理删除放行
         client.put(f"{_PERSONNEL}/{owner['id']}/status", json={"status": 0}, headers=headers)
@@ -273,9 +277,7 @@ class TestDeleteProtection:
         freed = client.delete(f"{_PERSONNEL}/{owner['id']}", headers=headers)
         assert freed.status_code == 200, freed.text
 
-    def test_被业务归属引用禁删_负责或协助任一即拦(
+    def test_被业务归属引用禁删_负责或协助任一即拦(self, client: TestClient, normal: dict) -> None:
-        self, client: TestClient, normal: dict
-    ) -> None:
         """业务表就位后删除保护补齐：负责/协助引用任一即拦，FK 不以 500 暴露。"""
         headers = normal["headers"]
         owner = _create(client, headers)

backend/tests/integration/test_products.py

@@ -30,6 +30,8 @@ from app.models import OperationLog
 pytestmark = pytest.mark.integration
 
 _PRODUCTS = "/api/v1/base/products"
+_CUSTOMERS = "/api/v1/base/customers"
+_BUSINESSES = "/api/v1/business/businesses"
 
 
 def _pname() -> str:
@@ -67,6 +69,48 @@ def _logs_of(username: str) -> list[OperationLog]:
         )
 
 
+@pytest.fixture
+def make_business_for_product(client: TestClient):
+    """造「客户 → 业务 → 明细挂指定产品」的最小引用链（删除保护场景）。
+
+    business_items.product_id 是 RESTRICT 外键，产品删除保护以此为引用源；
+    客户/业务均按 t_ 前缀与系统编号由 conftest 兜底清理。
+    """
+
+    def _factory(headers: dict, product_id: int) -> dict:
+        customer = client.post(
+            _CUSTOMERS,
+            json={
+                "company_name": f"t_引用公司_{uuid.uuid4().hex[:8]}",
+                "owner_name": "张老板",
+                "customer_type": "personal",
+            },
+            headers=headers,
+        )
+        assert customer.status_code == 200, customer.text
+        business = client.post(
+            _BUSINESSES,
+            json={
+                "customer_id": customer.json()["data"]["id"],
+                "business_date": "2026-01-01",
+                "items": [
+                    {
+                        "product_id": product_id,
+                        "product_name": f"t_引用产品_{uuid.uuid4().hex[:6]}",
+                        "product_category": PRODUCT_CATEGORY_MUNICIPAL_WATER,
+                        "quantity": "1.00",
+                        "sale_price": "10.00",
+                    }
+                ],
+            },
+            headers=headers,
+        )
+        assert business.status_code == 200, business.text
+        return business.json()["data"]
+
+    return _factory
+
+
 class TestAuth:
     """鉴权：登录后接口，裸访问一律 401。"""
 
@@ -120,6 +164,58 @@ class TestCrudFlow:
         assert "产品不存在" in detail.json()["message"]
 
 
+class TestDeleteProtection:
+    """删除保护：被业务/发货明细引用的产品禁删（customer 先例同构）。"""
+
+    def test_被业务明细引用_400且产品仍在(
+        self, client: TestClient, normal: dict, make_business_for_product
+    ) -> None:
+        product = _create(client, normal["headers"])
+        business = make_business_for_product(normal["headers"], product["id"])
+        resp = client.delete(f"{_PRODUCTS}/{product['id']}", headers=normal["headers"])
+        assert resp.status_code == 400, resp.text
+        assert "引用" in resp.json()["message"]
+        # 产品仍在（引导改走停用而非物理删除）
+        still = client.get(f"{_PRODUCTS}/{product['id']}", headers=normal["headers"])
+        assert still.status_code == 200
+        # 业务明细行确实引用了该产品（护栏：确认保护不是空转）
+        detail = client.get(f"{_BUSINESSES}/{business['id']}", headers=normal["headers"]).json()[
+            "data"
+        ]
+        assert detail["items"][0]["product_id"] == product["id"]
+
+    def test_被发货明细引用_400(
+        self, client: TestClient, normal: dict, make_business_for_product
+    ) -> None:
+        product = _create(client, normal["headers"])
+        make_business_for_product(normal["headers"], product["id"])
+        # 在业务明细引用之外再挂一笔发货明细（同样引用 products.id）
+        businesses = client.get("/api/v1/business/businesses", headers=normal["headers"]).json()[
+            "data"
+        ]
+        business_id = businesses["list"][0]["id"]
+        shipment = client.post(
+            "/api/v1/business/shipments",
+            json={
+                "business_id": business_id,
+                "ship_date": "2026-01-01",
+                "items": [
+                    {
+                        "product_id": product["id"],
+                        "product_name": product["product_name"],
+                        "quantity": "1.00",
+                        "sale_price": "10.00",
+                    }
+                ],
+            },
+            headers=normal["headers"],
+        )
+        assert shipment.status_code == 200, shipment.text
+        # 此前业务明细引用已令删除被拒，此处再证发货引用同一防线
+        resp = client.delete(f"{_PRODUCTS}/{product['id']}", headers=normal["headers"])
+        assert resp.status_code == 400, resp.text
+
+
 class TestValidationRules:
     """类别值域与组合唯一 —— 核算阈值锚点不脏、业务标识不重复。"""
 

backend/tests/integration/test_ratings.py

@@ -98,6 +98,27 @@ class TestAuth:
         assert resp.status_code == 401, resp.text
 
 
+class TestOverlapGuardLock:
+    """区间重叠判定的并发防线：判重叠的 list_all 必须带 FOR UPDATE。
+
+    区间重叠无唯一键可拦（名称才有 uk），无锁时两管理员并发提交重叠区间
+    会互判不重叠而双双入库。双连接真并发需线程与锁等待控制，此处锁定
+    SQL 形态两条口径：for_update 编译产物含 FOR UPDATE、只读直出不含。
+    """
+
+    def test_判重叠查询带FOR_UPDATE_只读直出不带(self) -> None:
+        from app.models import CustomerRatingGrade
+
+        locked = (
+            select(CustomerRatingGrade)
+            .order_by(CustomerRatingGrade.sort_order, CustomerRatingGrade.id)
+            .with_for_update()
+        )
+        assert "FOR UPDATE" in str(locked.compile())
+        plain = select(CustomerRatingGrade).order_by(CustomerRatingGrade.sort_order)
+        assert "FOR UPDATE" not in str(plain.compile())
+
+
 class TestList:
     """列表直出种子基线：判定表是前端评级计算器的唯一数据源。"""
 

backend/tests/integration/test_receipts.py

@@ -26,57 +26,13 @@ from app.core.constants import ACTION_CREATE, MODULE_RECEIPT
 from app.core.db import get_session_factory
 from app.models import OperationLog, Receipt
 from app.models.receipt import SETTLEMENT_DONE
+from tests.integration.factories import create_business as _create_business
 
 pytestmark = pytest.mark.integration
 
 _BUSINESSES = "/api/v1/business/businesses"
 _SHIPMENTS = "/api/v1/business/shipments"
 _RECEIPTS = "/api/v1/business/receipts"
-_CUSTOMERS = "/api/v1/base/customers"
-
-
-def _customer(client: TestClient, headers: dict) -> dict:
-    resp = client.post(
-        _CUSTOMERS,
-        json={
-            "company_name": f"t_公司_{uuid.uuid4().hex[:8]}",
-            "owner_name": "张老板",
-            "customer_type": "personal",
-        },
-        headers=headers,
-    )
-    assert resp.status_code == 200, resp.text
-    return resp.json()["data"]
-
-
-def _bitem(**overrides: object) -> dict:
-    """业务明细行入参（发货创建的门槛：业务须有明细 ≥1 行）。"""
-    body: dict = {
-        "product_name": f"t_产品_{uuid.uuid4().hex[:8]}",
-        "product_category": "municipal_water",
-        "quantity": "100",
-        "sale_price": "100.00",
-    }
-    body.update(overrides)
-    return body
-
-
-def _bpayload(customer_id: int, **overrides: object) -> dict:
-    body: dict = {
-        "customer_id": customer_id,
-        "business_date": str(date.today()),
-        "items": [_bitem()],
-    }
-    body.update(overrides)
-    return body
-
-
-def _create_business(client: TestClient, headers: dict) -> dict:
-    """建一名 t_ 客户并挂一笔默认业务（回款/发货单挂在业务上）。"""
-    customer = _customer(client, headers)
-    resp = client.post(_BUSINESSES, json=_bpayload(customer["id"]), headers=headers)
-    assert resp.status_code == 200, resp.text
-    return resp.json()["data"]
 
 
 def _sitem(**overrides: object) -> dict:

backend/tests/integration/test_reports.py

@@ -0,0 +1,803 @@
+"""报表统计集成测试（M4 ⑤）。
+
+守的口径（破坏了就是报表数字与台账对不上）：
+- 个人明细与台账逐笔一致；summary 为**全筛选**合计而非当前页合计
+- 部门汇总团队基数 = 成员绩效合计；12.5%/5% 分成按参数；无成员经理出 0 行
+- 回款统计 8 个区间桶恒在（空桶为 0）；**二次分摊拆行时回款金额只计一次**
+- 业务统计排除经理聚合行（calc_type=2），绩效不被整团队聚合额污染
+- 导出 xlsx 可解析且含签字栏；导出行为入操作日志
+- 权限：普通用户 403 且文案为「无权访问报表统计」
+"""
+
+import uuid
+from decimal import Decimal
+
+import pytest
+from fastapi.testclient import TestClient
+
+pytestmark = pytest.mark.integration
+
+_REPORTS = "/api/v1/reports"
+_PERSONNEL = "/api/v1/base/personnel"
+_BUSINESSES = "/api/v1/business/businesses"
+_SHIPMENTS = "/api/v1/business/shipments"
+_RECEIPTS = "/api/v1/business/receipts"
+_CALC = "/api/v1/calc"
+_SETTLEMENTS = "/api/v1/settlements"
+
+
+def _role_id(code: str) -> int:
+    """取内置业务岗位 id（salesperson / sales_manager）。"""
+    from sqlalchemy import select
+
+    from app.core.db import get_session_factory
+    from app.models import BusinessRole
+
+    factory = get_session_factory()
+    with factory() as session:
+        return int(
+            session.execute(
+                select(BusinessRole.id).where(
+                    BusinessRole.role_code == code, BusinessRole.status == 1
+                )
+            ).scalar_one()
+        )
+
+
+def _person(client: TestClient, headers: dict, *, role: str = "salesperson", manager_id=None) -> dict:
+    body = {
+        "personnel_name": f"t_报表_{uuid.uuid4().hex[:8]}",
+        "business_role_id": _role_id(role),
+        "salary_standard": "3000.00",
+    }
+    if manager_id is not None:
+        body["manager_id"] = manager_id
+    resp = client.post(_PERSONNEL, json=body, headers=headers)
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def _full_chain(
+    client: TestClient,
+    headers: dict,
+    *,
+    owner_id: int,
+    customer_id: int | None = None,
+    allocations: list[dict] | None = None,
+) -> tuple[dict, dict]:
+    """业务（单行 100×100，成本 3000）→ 发货（60 天前）→ 回款 → 核算。"""
+    from tests.integration.factories import business_item, business_payload, customer
+
+    cust = customer(client, headers) if customer_id is None else {"id": customer_id}
+    payload = business_payload(
+        cust["id"],
+        owner_personnel_id=owner_id,
+        items=[business_item(cost_amount="3000.00")],
+    )
+    if allocations:
+        payload["secondary_allocations"] = allocations
+    resp = client.post(_BUSINESSES, json=payload, headers=headers)
+    assert resp.status_code == 200, resp.text
+    business = resp.json()["data"]
+
+    from datetime import date, timedelta
+
+    ship_date = (date.today() - timedelta(days=60)).isoformat()
+    resp = client.post(
+        _SHIPMENTS,
+        json={
+            "business_id": business["id"],
+            "ship_date": ship_date,
+            "items": [{"product_name": "t_发货物", "quantity": "1", "sale_price": "1.00"}],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    shipment = resp.json()["data"]
+
+    resp = client.post(
+        _RECEIPTS,
+        json={
+            "business_id": business["id"],
+            "receipt_date": date.today().isoformat(),
+            "amount": "10000.00",
+            "shipment_id": shipment["id"],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    receipt = resp.json()["data"]
+
+    resp = client.post(f"{_CALC}/receipts/{receipt['id']}/calc", headers=headers)
+    assert resp.status_code == 200, resp.text
+    return business, receipt
+
+
+def _month() -> str:
+    from datetime import date
+
+    return date.today().strftime("%Y-%m")
+
+
+def _ledger_sum(headers: dict, month: str) -> Decimal:
+    """台账（单笔生效行）同月绩效合计——报表 summary 的对照基准。"""
+    from sqlalchemy import func, select
+
+    from app.core.db import get_session_factory
+    from app.models import PerformanceLedger
+
+    factory = get_session_factory()
+    with factory() as session:
+        return Decimal(
+            str(
+                session.execute(
+                    select(func.coalesce(func.sum(PerformanceLedger.performance_amount), 0)).where(
+                        PerformanceLedger.settlement_month == month,
+                        PerformanceLedger.calc_type == 1,
+                        PerformanceLedger.is_active == 1,
+                    )
+                ).scalar_one()
+            )
+        )
+
+
+def test_个人明细_与台账一致且summary为全量合计(client: TestClient, admin: dict):
+    """明细行金额必须等于台账；pageSize=1 时 summary 仍是全部筛选结果之和。"""
+    person = _person(client, admin["headers"])
+    _full_chain(client, admin["headers"], owner_id=person["id"])
+    month = _month()
+
+    resp = client.get(
+        f"{_REPORTS}/personal-detail",
+        params={"settlement_month": month, "pageSize": 1},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+    assert data["total"] == 1
+    expected = _ledger_sum(admin["headers"], month)
+    assert Decimal(str(data["list"][0]["performance_amount"])) == expected
+    assert Decimal(str(data["summary"]["performance_total"])) == expected
+
+
+def test_部门汇总_团队基数等于成员绩效且分成按参数(admin, client: TestClient):
+    """团队基数=成员绩效合计；12.5% 团队分成与 5% 全公司分成分别可核。"""
+    manager = _person(client, admin["headers"], role="sales_manager")
+    salesperson = _person(client, admin["headers"], manager_id=manager["id"])
+    _full_chain(client, admin["headers"], owner_id=salesperson["id"])
+    month = _month()
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": month},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+
+    team = next(t for t in data["teams"] if t["manager_id"] == manager["id"])
+    ledger_total = _ledger_sum(admin["headers"], month)
+    assert Decimal(str(team["team_base"])) == ledger_total
+    expected_share = (ledger_total * Decimal("0.125")).quantize(Decimal("0.01"))
+    assert Decimal(str(team["team_share_amount"])) == expected_share
+    assert team["member_count"] == 1
+    assert data["company"]["company_base"] == team["team_base"]
+
+
+def test_部门汇总_无成员经理出零值行(admin, client: TestClient):
+    """无团队成员 → 0 行展示（FR-030 异常处理）。"""
+    manager = _person(client, admin["headers"], role="sales_manager")
+    month = _month()
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": month},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    team = next(
+        (t for t in resp.json()["data"]["teams"] if t["manager_id"] == manager["id"]), None
+    )
+    assert team is not None
+    assert Decimal(str(team["team_base"])) == Decimal("0")
+    assert team["member_count"] == 0
+
+
+def test_回款统计_空桶恒在且分摊拆行金额只计一次(admin, client: TestClient):
+    """8 个区间桶恒在；二次分配拆行使台账多行但回款金额不得翻倍。"""
+    owner = _person(client, admin["headers"])
+    participant = _person(client, admin["headers"])
+    _full_chain(
+        client,
+        admin["headers"],
+        owner_id=owner["id"],
+        allocations=[{"personnel_id": participant["id"], "ratio": "30.00"}],
+    )
+    month = _month()
+
+    resp = client.get(
+        f"{_REPORTS}/payment-stats",
+        params={"settlement_month": month},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+
+    assert len(data["buckets"]) == 8
+    assert [b["code"] for b in data["buckets"]] == [
+        "le0", "1-30", "31-60", "61-90", "91-180", "181-360", "361+", "none",
+    ]
+    # 60 天前发货 → 落在 61-90 桶（发货日首日计第 1 天）
+    bucket = next(b for b in data["buckets"] if b["code"] == "61-90")
+    assert Decimal(str(bucket["receipt_amount"])) == Decimal("10000.00")
+    assert bucket["receipt_count"] == 1
+    # 拆行后台账两行，但绩效合计仍等于台账总和
+    assert bucket["ledger_count"] == 2
+    empty = next(b for b in data["buckets"] if b["code"] == "361+")
+    assert Decimal(str(empty["performance_amount"])) == Decimal("0")
+
+
+def test_业务统计_绩效排除经理聚合行(admin, client: TestClient):
+    """生成月结后出现 calc_type=2 聚合行，业务统计不得把聚合额算进单业务。"""
+    manager = _person(client, admin["headers"], role="sales_manager")
+    salesperson = _person(client, admin["headers"], manager_id=manager["id"])
+    business, _ = _full_chain(client, admin["headers"], owner_id=salesperson["id"])
+
+    resp = client.post(
+        f"{_SETTLEMENTS}/generate", json={"month": _month()}, headers=admin["headers"]
+    )
+    assert resp.status_code == 200, resp.text
+
+    resp = client.get(
+        f"{_REPORTS}/business-stats",
+        params={"keyword": business["business_no"]},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    row = resp.json()["data"]["list"][0]
+    assert Decimal(str(row["performance_amount"])) == _ledger_sum(admin["headers"], _month())
+
+
+def test_导出_excel含签字栏且入操作日志(admin, client: TestClient):
+    """导出是文件流（非统一信封）；模板含复核/签字栏；行为入操作日志。"""
+    from io import BytesIO
+
+    from openpyxl import load_workbook
+
+    person = _person(client, admin["headers"])
+    _full_chain(client, admin["headers"], owner_id=person["id"])
+
+    resp = client.get(
+        f"{_REPORTS}/personal-detail/export",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    assert resp.headers["content-type"].startswith(
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    )
+    workbook = load_workbook(BytesIO(resp.content))
+    text = "\n".join(
+        str(cell.value)
+        for row in workbook.active.iter_rows()
+        for cell in row
+        if cell.value is not None
+    )
+    assert "个人绩效工资明细表" in text
+    assert "财务复核" in text
+    assert "领导签字" in text
+
+    from sqlalchemy import select
+
+    from app.core.db import get_session_factory
+    from app.models import OperationLog
+
+    factory = get_session_factory()
+    with factory() as session:
+        log = session.execute(
+            select(OperationLog)
+            .where(OperationLog.module == "报表统计", OperationLog.action == "导出")
+            .order_by(OperationLog.id.desc())
+        ).scalars().first()
+    assert log is not None
+
+
+def test_权限_普通用户403文案(admin, normal, client: TestClient):
+    """报表限管理员/财务/领导；普通用户被后端拦截且文案正确。"""
+    resp = client.get(f"{_REPORTS}/personal-detail", headers=normal["headers"])
+    assert resp.status_code == 403
+    assert resp.json()["message"] == "无权访问报表统计"
+
+
+# ==== 审查回归：归属、调整单、经理个人户、导出审计 ====
+
+
+def _set_param(client: TestClient, headers: dict, code: str, value: str) -> None:
+    """立即生效的参数变更（用例不依赖种子默认值，结束显式恢复）。"""
+    resp = client.post(
+        "/api/v1/system/params/changes",
+        json={
+            "change_type": 1,
+            "remark": f"用例设置 {code}={value}",
+            "items": [{"param_code": code, "dimension_value": "", "value": value}],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+
+
+def _insert_adjustment(person: dict, month: str, amount: str, direction: int = 1) -> None:
+    """直插生效调整单（status=2）：绕开审批链，聚焦报表归属口径。"""
+    from app.core.db import get_session_factory
+    from app.models import AdjustmentOrder
+
+    factory = get_session_factory()
+    with factory() as session:
+        session.add(
+            AdjustmentOrder(
+                order_no=f"TZ{uuid.uuid4().hex[:12]}",
+                settlement_month=month,
+                personnel_id=person["id"],
+                personnel_name=person["personnel_name"],
+                direction=direction,
+                amount=Decimal(amount),
+                reason="t_报表用例",
+                status=2,
+                submitter_name="t_admin",
+            )
+        )
+        session.commit()
+
+
+def _insert_manager_personal_ledger(manager: dict, month: str, amount: str) -> None:
+    """直插一条经理个人户台账行（模拟单笔侧已计提的结果）。"""
+    from datetime import date
+
+    from app.core.db import get_session_factory
+    from app.models import PerformanceLedger
+
+    factory = get_session_factory()
+    with factory() as session:
+        session.add(
+            PerformanceLedger(
+                receipt_id=None,
+                calc_version=1,
+                calc_type=1,
+                business_id=0,
+                business_no="t_个人户",
+                personnel_id=manager["id"],
+                personnel_name=manager["personnel_name"],
+                role_code="sales_manager",
+                customer_type="manager_personal",
+                product_category="mixed",
+                receipt_date=date.today(),
+                rate_text="0",
+                performance_amount=Decimal(amount),
+                barter_applied=0,
+                payable_amount=Decimal(amount),
+                settlement_month=month,
+                is_probation=0,
+            )
+        )
+        session.commit()
+
+
+def _latest_export_log():
+    from sqlalchemy import select
+
+    from app.core.db import get_session_factory
+    from app.models import OperationLog
+
+    factory = get_session_factory()
+    with factory() as session:
+        return session.execute(
+            select(OperationLog)
+            .where(OperationLog.module == "报表统计", OperationLog.action == "导出")
+            .order_by(OperationLog.id.desc())
+        ).scalars().first()
+
+
+def test_部门汇总_无台账经理挂上级不报500(admin, client: TestClient):
+    """经理 A 无台账且上级是经理 B：不能因 member_map 直接索引而 KeyError。"""
+    manager_b = _person(client, admin["headers"], role="sales_manager")
+    manager_a = _person(
+        client, admin["headers"], role="sales_manager", manager_id=manager_b["id"]
+    )
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+    team_a = next(t for t in data["teams"] if t["manager_id"] == manager_a["id"])
+    assert team_a["member_count"] == 0
+    team_b = next(t for t in data["teams"] if t["manager_id"] == manager_b["id"])
+    assert all(m["personnel_id"] != manager_a["id"] for m in team_b["members"])
+
+
+def test_部门汇总_仅有调整单人员并入对应团队(admin, client: TestClient):
+    """只有调整单、当月无台账行的人也要出现在团队明细中。"""
+    manager = _person(client, admin["headers"], role="sales_manager")
+    salesperson = _person(client, admin["headers"], manager_id=manager["id"])
+    _insert_adjustment(salesperson, _month(), "500.00")
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+    team = next(t for t in data["teams"] if t["manager_id"] == manager["id"])
+    member = next(m for m in team["members"] if m["personnel_id"] == salesperson["id"])
+    assert member["member_kind"] == "adjustment"
+    assert Decimal(str(member["performance_sum"])) == Decimal("0")
+    assert Decimal(str(member["adjust_net"])) == Decimal("500.00")
+    assert Decimal(str(team["adjust_net"])) == Decimal("500.00")
+    assert Decimal(str(data["reconciliation"]["adjust_net_total"])) == Decimal("500.00")
+
+
+def test_部门汇总_仅调整单无经理人员进入未分配(admin, client: TestClient):
+    """无经理人员的调整单不能被静默丢弃。"""
+    salesperson = _person(client, admin["headers"])
+    _insert_adjustment(salesperson, _month(), "300.00")
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+    row = next(u for u in data["unassigned"] if u["personnel_id"] == salesperson["id"])
+    assert row["member_kind"] == "adjustment"
+    assert Decimal(str(row["adjust_net"])) == Decimal("300.00")
+
+
+def test_部门汇总_经理个人户计入时基数等于成员合计(admin, client: TestClient):
+    """开关 1：经理成员行只取个人户金额，团队基数 == 成员绩效合计。"""
+    manager = _person(client, admin["headers"], role="sales_manager")
+    _insert_manager_personal_ledger(manager, _month(), "100.00")
+    _set_param(client, admin["headers"], "manager.personal.included", "1")
+    try:
+        resp = client.get(
+            f"{_REPORTS}/department-summary",
+            params={"settlement_month": _month()},
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        team = next(
+            t for t in resp.json()["data"]["teams"] if t["manager_id"] == manager["id"]
+        )
+        assert Decimal(str(team["team_base"])) == Decimal("100.00")
+        assert sum(
+            (Decimal(str(m["performance_sum"])) for m in team["members"]), Decimal("0")
+        ) == Decimal("100.00")
+        assert all(m["member_kind"] == "manager_personal" for m in team["members"])
+    finally:
+        _set_param(client, admin["headers"], "manager.personal.included", "0")
+
+
+def test_部门汇总_经理个人户关闭时不展示个人户金额(admin, client: TestClient):
+    """开关 0：个人户金额既不计入团队基数，也不进未分配（与全公司口径一致）。"""
+    manager = _person(client, admin["headers"], role="sales_manager")
+    _insert_manager_personal_ledger(manager, _month(), "100.00")
+    _set_param(client, admin["headers"], "manager.personal.included", "0")
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+    team = next(t for t in data["teams"] if t["manager_id"] == manager["id"])
+    assert team["member_count"] == 0
+    assert all(u["personnel_id"] != manager["id"] for u in data["unassigned"])
+
+
+def test_部门汇总_按经理筛选不误判其他团队下属(admin, client: TestClient):
+    """筛选只影响展示的团队；其他经理的下属不能进入未分配。"""
+    manager_1 = _person(client, admin["headers"], role="sales_manager")
+    manager_2 = _person(client, admin["headers"], role="sales_manager")
+    salesperson_1 = _person(client, admin["headers"], manager_id=manager_1["id"])
+    salesperson_2 = _person(client, admin["headers"], manager_id=manager_2["id"])
+    _full_chain(client, admin["headers"], owner_id=salesperson_1["id"])
+    _full_chain(client, admin["headers"], owner_id=salesperson_2["id"])
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month(), "manager_id": manager_1["id"]},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+    assert [t["manager_id"] for t in data["teams"]] == [manager_1["id"]]
+    assert data["unassigned"] == []
+    assert all(
+        m["personnel_id"] != salesperson_2["id"]
+        for team in data["teams"]
+        for m in team["members"]
+    )
+    assert Decimal(str(data["reconciliation"]["other_team_base"])) > 0
+
+
+def test_部门汇总_对账恒等式(admin, client: TestClient):
+    """未筛选：团队基数 + 未分配绩效 = 全公司基数；应发公式成立。"""
+    manager = _person(client, admin["headers"], role="sales_manager")
+    salesperson = _person(client, admin["headers"], manager_id=manager["id"])
+    unassigned = _person(client, admin["headers"])
+    _full_chain(client, admin["headers"], owner_id=salesperson["id"])
+    _full_chain(client, admin["headers"], owner_id=unassigned["id"])
+    _insert_adjustment(salesperson, _month(), "200.00")
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    reconciliation = resp.json()["data"]["reconciliation"]
+    assert Decimal(str(reconciliation["team_base_total"])) + Decimal(
+        str(reconciliation["unassigned_performance_total"])
+    ) == Decimal(str(reconciliation["company_base"]))
+    assert Decimal(str(reconciliation["other_team_base"])) == Decimal("0")
+    assert Decimal(str(reconciliation["payable_total"])) == (
+        Decimal(str(reconciliation["team_member_payable_total"]))
+        + Decimal(str(reconciliation["unassigned_payable_total"]))
+        + Decimal(str(reconciliation["aggregate_payable_total"]))
+        + Decimal(str(reconciliation["adjust_net_total"]))
+    )
+    # 分列合计 + 舍入差 = 聚合额（月结一次舍入口径）
+    assert Decimal(str(reconciliation["aggregate_rounding_diff"])) == (
+        Decimal(str(reconciliation["aggregate_payable_total"]))
+        - Decimal(str(reconciliation["team_share_total"]))
+        - Decimal(str(reconciliation["company_share_total"]))
+    )
+
+
+def _two_manager_scene(
+    client: TestClient, headers: dict
+) -> tuple[dict, dict, dict, dict, dict]:
+    """两位经理各有下属与业务 + 一位零成员经理（无聚合行）。"""
+    manager_1 = _person(client, headers, role="sales_manager")
+    manager_2 = _person(client, headers, role="sales_manager")
+    empty_manager = _person(client, headers, role="sales_manager")
+    salesperson_1 = _person(client, headers, manager_id=manager_1["id"])
+    salesperson_2 = _person(client, headers, manager_id=manager_2["id"])
+    _full_chain(client, headers, owner_id=salesperson_1["id"])
+    _full_chain(client, headers, owner_id=salesperson_2["id"])
+    return manager_1, manager_2, empty_manager, salesperson_1, salesperson_2
+
+
+def test_部门汇总_应发合计与月结对拍_两位经理(admin, client: TestClient):
+    """月结每位有聚合行的经理各计一次 5%；签字稿应发必须等于 total_payable。"""
+    _two_manager_scene(client, admin["headers"])
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    before = resp.json()["data"]
+    assert before["company"]["company_share_count"] == 2
+    assert Decimal(str(before["company"]["company_share_total"])) == (
+        Decimal(str(before["company"]["company_share_amount"])) * 2
+    )
+
+    resp = client.post(
+        f"{_SETTLEMENTS}/generate", json={"month": _month()}, headers=admin["headers"]
+    )
+    assert resp.status_code == 200, resp.text
+    settlement = resp.json()["data"]
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+    teams = {team["manager_id"]: team for team in data["teams"]}
+    frozen_total = sum(
+        (
+            Decimal(str(team["frozen_amount"]))
+            for team in teams.values()
+            if team["frozen_amount"] is not None
+        ),
+        Decimal("0"),
+    )
+    reconciliation = data["reconciliation"]
+    assert Decimal(str(reconciliation["aggregate_payable_total"])) == frozen_total
+    assert Decimal(str(reconciliation["payable_total"])) == Decimal(
+        str(settlement["total_payable"])
+    )
+
+
+def test_部门汇总_有调整单时应发等于月结加调整(admin, client: TestClient):
+    """调整单不进月结 items；报表应发 = 月结总额 + 调整净额。"""
+    _, _, _, salesperson, _ = _two_manager_scene(client, admin["headers"])
+    _insert_adjustment(salesperson, _month(), "500.00")
+
+    resp = client.post(
+        f"{_SETTLEMENTS}/generate", json={"month": _month()}, headers=admin["headers"]
+    )
+    assert resp.status_code == 200, resp.text
+    settlement = resp.json()["data"]
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    reconciliation = resp.json()["data"]["reconciliation"]
+    assert Decimal(str(reconciliation["adjust_net_total"])) == Decimal("500.00")
+    assert Decimal(str(reconciliation["payable_total"])) == (
+        Decimal(str(settlement["total_payable"])) + Decimal("500.00")
+    )
+
+
+def test_部门汇总_按经理筛选时5百分比只计该团队(admin, client: TestClient):
+    """筛选态只汇总展示团队；隐藏团队的金额进 other_*，不参与应发。"""
+    manager_1, _, _, _, _ = _two_manager_scene(client, admin["headers"])
+
+    resp = client.get(
+        f"{_REPORTS}/department-summary",
+        params={"settlement_month": _month(), "manager_id": manager_1["id"]},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    data = resp.json()["data"]
+    assert data["company"]["company_share_count"] == 1
+    reconciliation = data["reconciliation"]
+    assert Decimal(str(reconciliation["other_team_aggregate_total"])) > 0
+    assert Decimal(str(reconciliation["other_team_company_share_total"])) > 0
+
+
+def test_导出_筛选页眉ID转名称与中文标签(admin, client: TestClient):
+    """页眉是签字稿追溯筛选范围的唯一凭据，ID 必须转名称。"""
+    from io import BytesIO
+
+    from openpyxl import load_workbook
+
+    from app.core.db import get_session_factory
+    from app.models import BusinessRole
+
+    person = _person(client, admin["headers"])
+    _full_chain(client, admin["headers"], owner_id=person["id"])
+    factory = get_session_factory()
+    with factory() as session:
+        role_name = (
+            session.query(BusinessRole.role_name)
+            .filter(BusinessRole.role_code == "salesperson")
+            .scalar()
+        )
+
+    resp = client.get(
+        f"{_REPORTS}/personal-detail/export",
+        params={
+            "settlement_month": _month(),
+            "personnel_id": person["id"],
+            "role_code": "salesperson",
+            "customer_type": "personal",
+            "product_category": "municipal_water",
+        },
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    workbook = load_workbook(BytesIO(resp.content))
+    text = "\n".join(
+        str(cell.value)
+        for row in workbook.active.iter_rows()
+        for cell in row
+        if cell.value is not None
+    )
+    assert person["personnel_name"] in text
+    assert f"人员 {person['personnel_name']}(#{person['id']})" in text
+    assert "个人户" in text
+    assert "市政水利" in text
+    assert role_name in text
+
+
+def test_导出_回款维度sheet透传筛选条件(admin, client: TestClient):
+    """两个维度 sheet 的页眉不能固定写「全部」。"""
+    from io import BytesIO
+
+    from openpyxl import load_workbook
+
+    resp = client.get(
+        f"{_REPORTS}/payment-stats/export",
+        params={"customer_type": "personal"},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 200, resp.text
+    workbook = load_workbook(BytesIO(resp.content))
+    for sheet_name in ("客户类型对比", "产品类别对比"):
+        text = "\n".join(
+            str(cell.value)
+            for row in workbook[sheet_name].iter_rows()
+            for cell in row
+            if cell.value is not None
+        )
+        assert "客户类型 个人户" in text
+        assert "筛选条件：全部" not in text
+
+
+def test_导出超限_失败审计留痕(admin, client: TestClient, monkeypatch):
+    """超限 400 发生在审计上下文内，必须留下失败记录。"""
+    from app.services import report_service
+
+    person = _person(client, admin["headers"])
+    _full_chain(client, admin["headers"], owner_id=person["id"])
+    monkeypatch.setattr(report_service, "REPORT_EXPORT_MAX_ROWS", 0)
+
+    resp = client.get(
+        f"{_REPORTS}/personal-detail/export",
+        params={"settlement_month": _month()},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 400, resp.text
+    log = _latest_export_log()
+    assert log is not None
+    assert log.success == 0
+    assert "超过上限" in (log.error_message or "")
+
+
+def test_导出取数异常_失败审计留痕(admin, client: TestClient, monkeypatch):
+    """取数阶段的异常同样要留下失败记录。
+
+    TestClient 默认重抛服务端异常，这里直接调 service 层，聚焦审计落库。
+    """
+    from app.core.db import get_session_factory
+    from app.models import User
+    from app.schemas.report import PersonalDetailQuery
+    from app.services import report_service
+
+    def _boom(*args, **kwargs):
+        raise RuntimeError("t_取数异常")
+
+    monkeypatch.setattr(report_service, "_export_payload", _boom)
+    factory = get_session_factory()
+    with factory() as session:
+        operator = session.get(User, admin["id"])
+        with pytest.raises(RuntimeError, match="t_取数异常"):
+            report_service.export_report(
+                session,
+                "personal-detail",
+                PersonalDetailQuery(settlement_month=_month()),
+                operator=operator,
+            )
+    log = _latest_export_log()
+    assert log is not None
+    assert log.success == 0
+    # 未预期异常按安全口径收敛为通用文案，摘要仍能定位到报表
+    assert "导出个人绩效工资明细表" in (log.summary or "")
+
+
+@pytest.mark.parametrize(
+    "path", ["/personal-detail", "/department-summary", "/payment-stats"]
+)
+def test_非法月份_查询返回400(admin, client: TestClient, path: str):
+    """非法月份必须是参数错误 400，不能落 500。"""
+    resp = client.get(
+        f"{_REPORTS}{path}",
+        params={"settlement_month": "2026-13"},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 400, resp.text
+
+
+@pytest.mark.parametrize(
+    "code", ["personal-detail", "department-summary", "payment-stats"]
+)
+def test_非法月份_导出返回400(admin, client: TestClient, code: str):
+    """导出手工构造查询模型同样要转 400。"""
+    resp = client.get(
+        f"{_REPORTS}/{code}/export",
+        params={"settlement_month": "2026-13"},
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 400, resp.text

backend/tests/integration/test_schema_sync.py

@@ -28,10 +28,14 @@ _CREATE_TABLE = re.compile(r"CREATE TABLE\s+`?(\w+)`?\s*\((.*?)\n\)", re.DOTALL)
 _COLUMN_LINE = re.compile(r"^\s{4}`?(\w+)`?\s", re.MULTILINE)
 # 这些开头的是约束定义，不是列定义
 _NON_COLUMN_KEYWORDS = {"CONSTRAINT", "PRIMARY", "UNIQUE", "FOREIGN", "KEY", "INDEX"}
+# ALTER TABLE 的列级变更（语义重放用）：ADD COLUMN / DROP COLUMN；
+# MODIFY 只改类型不改列名，对列集合无影响，无需处理
+_ALTER_ADD = re.compile(r"ALTER TABLE\s+`?(\w+)`?\s+ADD(?:\s+COLUMN)?\s+`?(\w+)`?", re.IGNORECASE)
+_ALTER_DROP = re.compile(r"ALTER TABLE\s+`?(\w+)`?\s+DROP(?:\s+COLUMN)?\s+`?(\w+)`?", re.IGNORECASE)
 
 
 def _parse_tables(sql: str) -> dict[str, set[str]]:
-    """从 SQL 文本中提取 {表名: {列名集合}}。"""
+    """从 SQL 文本中提取 {表名: {列名集合}}（仅 CREATE TABLE 的静态解析）。"""
     tables: dict[str, set[str]] = {}
     for table_name, body in _CREATE_TABLE.findall(sql):
         tables[table_name] = {
@@ -42,6 +46,30 @@ def _parse_tables(sql: str) -> dict[str, set[str]]:
     return tables
 
 
+def _migration_final_state(paths: list[Path]) -> dict[str, set[str]]:
+    """按文件序重放迁移脚本，得到迁移链**终态**的 {表名: {列名集合}}。
+
+    早前实现把全部脚本的 CREATE 列做并集：某表日后被 ALTER DROP COLUMN
+    时，并集里旧列名永远存在，init-dev.sql 必须保留死列才能过测 —— 守卫
+    会主动背书一份与生产结构漂移的开发库 DDL。按序重放 ADD/DROP 后，
+    比对基准才是终态（CHANGE RENAME 列名出现时重放会报差异，属人工核对
+    的正确时机：改名同时牵动 init-dev 与 ORM，须人来确认两处同步）。
+    """
+    merged: dict[str, set[str]] = {}
+    for path in paths:
+        sql = path.read_text(encoding="utf-8")
+        for table, columns in _parse_tables(sql).items():
+            merged.setdefault(table, set()).update(columns)
+        for table, column in _ALTER_ADD.findall(sql):
+            # ADD CONSTRAINT ... UNIQUE 的「CONSTRAINT」不是列（与 _parse_tables
+            # 的约束关键词同一份清单过滤），V8 台账唯一键三列扩展即此形态
+            if column.upper() not in _NON_COLUMN_KEYWORDS:
+                merged.setdefault(table, set()).add(column)
+        for table, column in _ALTER_DROP.findall(sql):
+            merged.setdefault(table, set()).discard(column)
+    return merged
+
+
 def _alembic_head() -> str:
     """从迁移脚本推断当前 head 版本号。
 
@@ -65,15 +93,10 @@ def _alembic_head() -> str:
 
 @pytest.fixture(scope="module")
 def migration_tables() -> dict[str, set[str]]:
-    """合并解析 db/migration/ 下全部 V*.sql。"""
+    """按文件序重放 db/migration/ 下全部 V*.sql，取迁移链终态。"""
     files = sorted(MIGRATION_DIR.glob("V*.sql"))
     assert files, f"未找到迁移脚本：{MIGRATION_DIR}"
-
+    return _migration_final_state(files)
-    merged: dict[str, set[str]] = {}
-    for path in files:
-        for table, columns in _parse_tables(path.read_text(encoding="utf-8")).items():
-            merged.setdefault(table, set()).update(columns)
-    return merged
 
 
 @pytest.fixture(scope="module")
@@ -109,7 +132,7 @@ class TestSchemaSync:
 class TestSeedData:
     """字典数据与版本标记。"""
 
-    @pytest.mark.parametrize("role_code", ["admin", "user"])
+    @pytest.mark.parametrize("role_code", ["admin", "user", "marketing_ops", "finance", "leader"])
     def test_角色初始化数据在两处都存在(self, role_code: str) -> None:
         migration_sql = "\n".join(
             path.read_text(encoding="utf-8") for path in sorted(MIGRATION_DIR.glob("V*.sql"))

backend/tests/integration/test_secondary_allocation.py

@@ -0,0 +1,300 @@
+"""二次分配方案录入（业务创建/编辑同事务）集成测试。
+
+守的是（计划 T3 验收）：
+- 创建带方案 → 详情回显含 personnel_name 冗余与比例
+- 编辑全量替换（空数组=清空）
+- 离职/不存在人员 → 400「分摊参与人员不存在或已离职」
+- 终态业务禁改方案（与编辑终态门槛同一口径）
+- 合计不强制 100%：hint 展示合计与余额（余额归属待澄清 #2）
+- 删除保护：被方案引用的人员 RESTRICT 禁删（400 而非静默剥离）
+- 人员删除后方案回显仍有名（personnel_name 固化的意义）
+
+人员造数走 /api/v1/base/personnel（种子营销员岗位）；离职用状态端点。
+"""
+
+import uuid
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.integration.factories import business_payload, customer
+
+pytestmark = pytest.mark.integration
+
+_BUSINESSES = "/api/v1/business/businesses"
+_PERSONNEL = "/api/v1/base/personnel"
+
+
+def _person(client: TestClient, headers: dict, **overrides: object) -> dict:
+    role_id = overrides.pop("business_role_id", None)
+    body = {
+        "personnel_name": f"t_分摊_{uuid.uuid4().hex[:8]}",
+        "business_role_id": role_id or _any_role_id(),
+        "salary_standard": "3000.00",
+        **overrides,
+    }
+    resp = client.post(_PERSONNEL, json=body, headers=headers)
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def _any_role_id() -> int:
+    """种子营销员岗位 ID（内置启用）。"""
+    from sqlalchemy import select
+
+    from app.core.constants import BUSINESS_ROLE_SALESPERSON
+    from app.core.db import get_session_factory
+    from app.models import BusinessRole
+
+    factory = get_session_factory()
+    with factory() as session:
+        return int(
+            session.execute(
+                select(BusinessRole.id).where(
+                    BusinessRole.role_code == BUSINESS_ROLE_SALESPERSON,
+                    BusinessRole.status == 1,
+                )
+            ).scalar_one()
+        )
+
+
+def _create_with_allocations(client: TestClient, headers: dict, allocations: list[dict]) -> dict:
+    cust = customer(client, headers)
+    resp = client.post(
+        _BUSINESSES,
+        json=business_payload(cust["id"], secondary_allocations=allocations),
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def _set_switch(client: TestClient, headers: dict, value: str) -> None:
+    """显式设置二次分配审批开关（V8 起默认开启，用例不得依赖种子默认值）。"""
+    resp = client.post(
+        "/api/v1/system/params/changes",
+        json={
+            "change_type": 1,
+            "remark": f"用例设置二次分配审批开关={value}",
+            "items": [
+                {
+                    "param_code": "approval.secondary_allocation.enabled",
+                    "dimension_value": "",
+                    "value": value,
+                }
+            ],
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+
+
+def _detail(client: TestClient, headers: dict, business_id: int) -> dict:
+    resp = client.get(f"{_BUSINESSES}/{business_id}", headers=headers)
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+class TestCreateAndEcho:
+    """创建带方案与详情回显。"""
+
+    def test_带方案创建_详情回显姓名与比例(self, client: TestClient, admin: dict) -> None:
+        p1 = _person(client, admin["headers"])
+        p2 = _person(client, admin["headers"])
+        data = _create_with_allocations(
+            client,
+            admin["headers"],
+            [
+                {"personnel_id": p1["id"], "ratio": "30.00"},
+                {"personnel_id": p2["id"], "ratio": "20.00"},
+            ],
+        )
+        detail = _detail(client, admin["headers"], data["id"])
+        assert len(detail["secondary_allocations"]) == 2
+        names = {a["personnel_name"] for a in detail["secondary_allocations"]}
+        assert p1["personnel_name"] in names and p2["personnel_name"] in names
+        ratios = sorted(a["ratio"] for a in detail["secondary_allocations"])
+        assert ratios == ["20.00", "30.00"]
+        # 合计 50%，余额 50% —— 只提示不落库（待澄清 #2）
+        assert "50.00" in (detail["allocation_hint"] or "")
+        assert "余额" in (detail["allocation_hint"] or "")
+
+    def test_不建方案_详情为空且无hint(self, client: TestClient, admin: dict) -> None:
+        data = _create_with_allocations(client, admin["headers"], [])
+        detail = _detail(client, admin["headers"], data["id"])
+        assert detail["secondary_allocations"] == []
+        assert detail["allocation_hint"] is None
+
+    def test_合计满额_hint只报合计(self, client: TestClient, admin: dict) -> None:
+        p1 = _person(client, admin["headers"])
+        p2 = _person(client, admin["headers"])
+        data = _create_with_allocations(
+            client,
+            admin["headers"],
+            [
+                {"personnel_id": p1["id"], "ratio": "60"},
+                {"personnel_id": p2["id"], "ratio": "40.00"},
+            ],
+        )
+        hint = _detail(client, admin["headers"], data["id"])["allocation_hint"]
+        assert hint is not None and "余额" not in hint
+
+
+class TestGuards:
+    """校验链：在职/终态/去重已由 schema 层覆盖，此处打服务层口径。"""
+
+    def test_离职人员参与被拒(self, client: TestClient, admin: dict) -> None:
+        p = _person(client, admin["headers"])
+        resp = client.put(
+            f"{_PERSONNEL}/{p['id']}/status", json={"status": 0}, headers=admin["headers"]
+        )
+        assert resp.status_code == 200, resp.text
+
+        cust = customer(client, admin["headers"])
+        resp = client.post(
+            _BUSINESSES,
+            json=business_payload(
+                cust["id"],
+                secondary_allocations=[{"personnel_id": p["id"], "ratio": "50.00"}],
+            ),
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 400
+        assert "分摊参与" in resp.json()["message"]
+
+    def test_离职历史参与人_编辑其余字段放行(self, client: TestClient, admin: dict) -> None:
+        """历史参与人离职后：编辑业务（保留该行）不应被 400 卡死——
+        personnel_name 冗余固化的设计本就允许离职后回显；仅新增参与人
+        才做在职校验。"""
+        p = _person(client, admin["headers"])
+        data = _create_with_allocations(
+            client, admin["headers"], [{"personnel_id": p["id"], "ratio": "50.00"}]
+        )
+        resp = client.put(
+            f"{_PERSONNEL}/{p['id']}/status", json={"status": 0}, headers=admin["headers"]
+        )
+        assert resp.status_code == 200
+
+        detail = _detail(client, admin["headers"], data["id"])
+        payload = business_payload(
+            detail["customer_id"],
+            secondary_allocations=[{"personnel_id": p["id"], "ratio": "50.00"}],
+        )
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+        after = _detail(client, admin["headers"], data["id"])
+        assert after["secondary_allocations"][0]["personnel_name"] == p["personnel_name"]
+
+        # 新增一名离职人员仍要拦（新增才做在职校验）
+        p2 = _person(client, admin["headers"])
+        client.put(f"{_PERSONNEL}/{p2['id']}/status", json={"status": 0}, headers=admin["headers"])
+        payload = business_payload(
+            detail["customer_id"],
+            secondary_allocations=[
+                {"personnel_id": p["id"], "ratio": "30.00"},
+                {"personnel_id": p2["id"], "ratio": "20.00"},
+            ],
+        )
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 400
+        assert "分摊参与" in resp.json()["message"]
+
+    def test_终态业务禁改方案(self, client: TestClient, admin: dict) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_allocations(
+            client, admin["headers"], [{"personnel_id": p["id"], "ratio": "100"}]
+        )
+        resp = client.put(
+            f"{_BUSINESSES}/{data['id']}/status",
+            json={"status": 2},
+            headers=admin["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+
+        detail = _detail(client, admin["headers"], data["id"])
+        payload = business_payload(detail["customer_id"], secondary_allocations=[])
+        for key in ("business_no", "status", "owner_personnel_id", "total_sale_amount"):
+            payload.pop(key, None)
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 400
+        assert "禁止编辑" in resp.json()["message"]
+
+    def test_编辑全量替换与清空(self, client: TestClient, admin: dict) -> None:
+        p1 = _person(client, admin["headers"])
+        p2 = _person(client, admin["headers"])
+        data = _create_with_allocations(
+            client, admin["headers"], [{"personnel_id": p1["id"], "ratio": "40.00"}]
+        )
+
+        detail = _detail(client, admin["headers"], data["id"])
+        payload = business_payload(
+            detail["customer_id"],
+            secondary_allocations=[{"personnel_id": p2["id"], "ratio": "70.00"}],
+        )
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+
+        replaced = _detail(client, admin["headers"], data["id"])
+        assert len(replaced["secondary_allocations"]) == 1
+        assert replaced["secondary_allocations"][0]["personnel_id"] == p2["id"]
+
+        payload = business_payload(detail["customer_id"], secondary_allocations=[])
+        resp = client.put(f"{_BUSINESSES}/{data['id']}", json=payload, headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+        assert _detail(client, admin["headers"], data["id"])["secondary_allocations"] == []
+
+
+class TestDeleteProtection:
+    """RESTRICT 外键：被方案引用的人员禁删，方案随业务删除而清。"""
+
+    def test_同一会话内旧方案行同步为历史态(self, client: TestClient, admin: dict) -> None:
+        """守「置历史后同一会话内的旧行必须同步刷新」这一行为：Core UPDATE
+        走的是 SQLAlchemy 的会话同步策略，条件复杂化时可能退化为不刷新，
+        届时行对象会停留在 is_active=1 的过期内存值（库中实际已置历史），
+        被序列化或参与判断就会呈现「生效态」的假象。"""
+        from app.core.db import get_session_factory
+        from app.models import SecondaryAllocation
+        from app.repositories import business_repository
+
+        p = _person(client, admin["headers"])
+        data = _create_with_allocations(
+            client, admin["headers"], [{"personnel_id": p["id"], "ratio": "50.00"}]
+        )
+
+        factory = get_session_factory()
+        with factory() as session:
+            loaded = business_repository.list_allocations(session, data["id"])
+            assert loaded and all(a.is_active == 1 for a in loaded)
+            business_repository.deactivate_allocations(session, data["id"])
+            # 同一 session 内的行对象必须已是历史态，不能停留在过期内存值
+            assert all(a.is_active == 0 for a in loaded), "旧行未随置历史同步刷新"
+            # 库中同样已置历史
+            rows = (
+                session.query(SecondaryAllocation)
+                .filter(SecondaryAllocation.business_id == data["id"])
+                .all()
+            )
+            assert rows and all(r.is_active == 0 for r in rows)
+            session.rollback()
+
+    def test_被方案引用的人员禁删(self, client: TestClient, admin: dict) -> None:
+        p = _person(client, admin["headers"])
+        data = _create_with_allocations(
+            client, admin["headers"], [{"personnel_id": p["id"], "ratio": "50.00"}]
+        )
+        resp = client.delete(f"{_PERSONNEL}/{p['id']}", headers=admin["headers"])
+        assert resp.status_code == 400
+        # 方案仍在，回显有名（RESTRICT 保证未静默剥离）
+        detail = _detail(client, admin["headers"], data["id"])
+        assert detail["secondary_allocations"][0]["personnel_name"] == p["personnel_name"]
+
+    def test_删除业务后可删人员(self, client: TestClient, admin: dict) -> None:
+        # 显式关开关：开启时审批单在途、删业务被 400 拦截（产品行为，另有用例覆盖）
+        _set_switch(client, admin["headers"], "0")
+        p = _person(client, admin["headers"])
+        data = _create_with_allocations(
+            client, admin["headers"], [{"personnel_id": p["id"], "ratio": "50.00"}]
+        )
+        resp = client.delete(f"{_BUSINESSES}/{data['id']}", headers=admin["headers"])
+        assert resp.status_code == 200, resp.text  # 方案 CASCADE 随业务删除
+        assert client.delete(f"{_PERSONNEL}/{p['id']}", headers=admin["headers"]).status_code == 200

backend/tests/integration/test_settings.py

@@ -0,0 +1,137 @@
+"""系统设置（公司信息）接口测试。
+
+守的是：
+- 单行语义：全系统恒一行，PUT 只改名称不增行
+- public 端点无鉴权可用但**白名单字段**——多一个敏感字段都是匿名泄漏
+- logo 上传三重校验（后缀/magic bytes/大小）——仅看后缀可被伪造
+- 审计留痕：系统设置属敏感配置，改必须有日志
+
+真图片构造：PNG 用 8 字节签名 + 最小 IHDR；JPG 用 SOI 头 + 填充字节。
+仅校验 magic bytes 前缀，无需完整合法图片（解析由前端 img 完成）。
+"""
+
+import uuid
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+pytestmark = pytest.mark.integration
+
+_SETTINGS = "/api/v1/system/settings"
+
+_PNG_BYTES = b"\x89PNG\r\n\x1a\n" + b"\x00" * 32
+_JPG_BYTES = b"\xff\xd8\xff\xe0" + b"\x00" * 32
+_TXT_BYTES = b"not an image at all"
+
+
+@pytest.fixture
+def client() -> TestClient:
+    return TestClient(app)
+
+
+class TestCompanyInfo:
+    """公司名称读取与更新。"""
+
+    def test_初始值与更新生效(self, client: TestClient, admin: dict) -> None:
+        got = client.get(_SETTINGS, headers=admin["headers"]).json()["data"]
+        assert got["company_name"]
+        # logo_url 允许为 None（未上传）或历史遗留的 URL——单行库可复用，
+        # 断言不依赖「干净库」前提；上传行为由 TestLogoUpload 专类覆盖
+        assert got["logo_url"] is None or "/logo/public" in got["logo_url"]
+
+        new_name = f"测试公司_{uuid.uuid4().hex[:6]}"
+        put = client.put(_SETTINGS, json={"company_name": new_name}, headers=admin["headers"])
+        assert put.status_code == 200, put.text
+        assert put.json()["data"]["company_name"] == new_name
+        assert (
+            client.get(_SETTINGS, headers=admin["headers"]).json()["data"]["company_name"]
+            == new_name
+        )
+
+    def test_名称为空被拒(self, client: TestClient, admin: dict) -> None:
+        assert (
+            client.put(_SETTINGS, json={"company_name": ""}, headers=admin["headers"]).status_code
+            == 400
+        )
+
+    def test_非管理员改名称被拒(self, client: TestClient, normal: dict) -> None:
+        resp = client.put(_SETTINGS, json={"company_name": "越权公司"}, headers=normal["headers"])
+        assert resp.status_code == 403
+
+    def test_修改留审计日志(self, client: TestClient, admin: dict) -> None:
+        client.put(
+            _SETTINGS,
+            json={"company_name": f"审计公司_{uuid.uuid4().hex[:6]}"},
+            headers=admin["headers"],
+        )
+        logs = client.get(
+            "/api/v1/system/operation-logs",
+            params={"module": "系统设置"},
+            headers=admin["headers"],
+        ).json()["data"]["list"]
+        assert logs, "修改公司名称未产生操作日志"
+
+
+class TestPublicEndpoint:
+    """匿名端点：白名单字段 + 可用性。"""
+
+    def test_无令牌可读且仅白名单字段(self, client: TestClient, admin: dict) -> None:
+        name = f"公开公司_{uuid.uuid4().hex[:6]}"
+        client.put(_SETTINGS, json={"company_name": name}, headers=admin["headers"])
+
+        resp = client.get(f"{_SETTINGS}/public")
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert set(data) == {"company_name", "logo_url"}, "public 端点字段越界"
+        assert data["company_name"] == name
+        assert resp.headers.get("cache-control") is not None
+
+    def test_写操作匿名不可用(self, client: TestClient) -> None:
+        assert client.put(f"{_SETTINGS}/public", json={"company_name": "x"}).status_code in {
+            401,
+            405,
+        }
+
+
+class TestLogoUpload:
+    """logo 上传校验链。"""
+
+    def _upload(self, client: TestClient, admin: dict, filename: str, content: bytes):
+        return client.post(
+            f"{_SETTINGS}/logo",
+            files={"file": (filename, content, "application/octet-stream")},
+            headers=admin["headers"],
+        )
+
+    def test_合法png上传成功且回读(self, client: TestClient, admin: dict) -> None:
+        resp = self._upload(client, admin, "logo.png", _PNG_BYTES)
+        assert resp.status_code == 200, resp.text
+        out = resp.json()["data"]
+        assert out["logo_url"] and "/logo/public" in out["logo_url"]
+
+        img = client.get(f"{_SETTINGS}/logo/public")
+        assert img.status_code == 200
+        assert img.headers["content-type"] == "image/png"
+
+    def test_伪造扩展名被magic_bytes拦截(self, client: TestClient, admin: dict) -> None:
+        resp = self._upload(client, admin, "fake.png", _TXT_BYTES)
+        assert resp.status_code == 400
+        assert "不符" in resp.json()["message"]
+
+    def test_非法格式被拒(self, client: TestClient, admin: dict) -> None:
+        assert self._upload(client, admin, "x.gif", _PNG_BYTES).status_code == 400
+
+    def test_超限被拒(self, client: TestClient, admin: dict) -> None:
+        big = _PNG_BYTES + b"\x00" * (2 * 1024 * 1024)
+        resp = self._upload(client, admin, "big.png", big)
+        assert resp.status_code == 400
+        assert "2MB" in resp.json()["message"]
+
+    def test_匿名上传被拒(self, client: TestClient) -> None:
+        resp = client.post(
+            f"{_SETTINGS}/logo",
+            files={"file": ("logo.png", _PNG_BYTES, "application/octet-stream")},
+        )
+        assert resp.status_code == 401