PayrollManagementSystem/backend/README.md

# 后端

> AI摘要：衍水集团营销人员工资管理系统的后端服务。FastAPI + SQLAlchemy（同步）+ MySQL + Redis，Python 3.12 由 uv 锁定。六层结构 `api / services / repositories / models / schemas / core`。已实现登录鉴权、系统管理（用户/角色/操作日志/日志查询）与 M1 参数体系（岗位角色管理、计提参数版本化/留痕/对比/预览/导出，2026-10-13）；业务模块（基础/业务数据、核算、报表）按路线图推进。

## 职责

- 提供 REST 接口（统一前缀 `/api`）
- 登录鉴权：图形验证码、JWT、登录限流、登出黑名单、登录日志
- 系统管理（需求 2.5.1）：用户管理、角色管理、岗位角色（#28 可扩展+公式模板绑定）、操作日志（自动审计）、操作与登录日志查询
- 计提参数体系（需求 #28）：16 项参数目录、按生效日期版本化（回款到账日取值）、变更批次留痕/对比/导出、计算预览
- 后续承担：基础数据、业务数据、绩效核算、报表统计、T+ 数据同步

## 技术栈与版本

| 组件 | 版本 | 说明 |
| --- | --- | --- |
| Python | 3.12 | uv 锁定。系统默认是 3.14，**不要用**——第三方库轮子覆盖不如 3.12 完备 |
| FastAPI / Starlette | 0.143 / 1.7 | `starlette` 显式限定 `<2`：FastAPI 对它的约束无上界，升级时可能漂移 |
| SQLAlchemy | 2.1 | **同步**引擎，路由写 `def` 由 FastAPI 放入线程池 |
| PyMySQL | 1.2 | **必须带 `[rsa]`**：MySQL 8.0 默认 `caching_sha2_password`，缺 `cryptography` 时首次连接抛 `RuntimeError`，且报错在建连阶段、极易误读为「密码错误」 |
| alembic | 1.20 | 迁移；运行期与迁移共用同一份 `mysql+pymysql` 连接串 |
| redis | 8.1 | **同步**客户端 |
| pwdlib | 0.3 | 密码哈希。**不用 passlib**（已停更且与 bcrypt ≥4.1 不兼容）。算法**显式指定** BcryptHasher，不用 `recommended()` |
| captcha | 0.7 | **仅用其内置字体文件**，渲染已自绘（见 `core/captcha_image.py`） |

## 分层结构与红线

```text
app/
├── api/            HTTP 层：路由、依赖注入、参数校验
│   ├── deps.py     公共依赖：get_db、get_current_user、get_raw_token
│   └── v1/         版本化业务路由
├── services/       业务编排 + **唯一事务边界**（commit/rollback 只在此层）
├── repositories/   数据访问，**只 flush 不 commit**
├── models/         ORM 映射，不含业务逻辑
├── schemas/        请求/响应模型，禁止把 ORM 对象直接当 response_model
└── core/           横切基础设施：配置、安全、连接、异常、响应、日志
```

| 层 | 可以做 | **不可做** |
| --- | --- | --- |
| `api/` | 参数绑定、调 service、返回统一响应 | 写业务判断、直接拼 SQL |
| `services/` | 编排多个 repository、提交事务 | — |
| `repositories/` | 读写数据、flush | `commit()`、抛业务异常 |
| `models/` | 表映射 | 业务逻辑 |
| `core/` | 基础设施 | 业务规则 |

## 核心接口

| 方法 | 路径 | 认证 | 说明 |
| --- | --- | :---: | --- |
| GET | `/api/health` | 否 | 探活，上报 app/db/redis 三项状态 |
| GET | `/api/v1/auth/captcha` | 否 | 签发图形验证码，返回 id + 图片 base64 |
| POST | `/api/v1/auth/login` | 否 | 账号 + 密码 + 验证码 → JWT |
| POST | `/api/v1/auth/logout` | 是 | 令牌入黑名单，立即失效 |
| GET | `/api/v1/auth/me` | 是 | 当前用户与角色 |

### 系统管理接口（需求 2.5.1，全部要求管理员权限）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET / POST | `/api/v1/system/users` | 用户列表（分页/筛选）/ 新增用户 |
| GET / PUT / DELETE | `/api/v1/system/users/{id}` | 用户详情 / 编辑（含角色分配）/ 删除（物理删除） |
| PUT | `/api/v1/system/users/{id}/password` | 重置密码（提升令牌版本，旧令牌立即失效） |
| PUT | `/api/v1/system/users/{id}/status` | 启用 / 禁用（禁用同样提升令牌版本） |
| GET | `/api/v1/system/users/meta/roles` | 角色下拉选项（仅启用角色） |
| GET / POST | `/api/v1/system/roles` | 角色列表（含停用与绑定用户数）/ 新增角色 |
| PUT / DELETE | `/api/v1/system/roles/{id}` | 编辑（不含编码）/ 删除（内置与有绑定的角色受保护） |
| PUT | `/api/v1/system/roles/{id}/status` | 启用 / 禁用（内置 admin 禁停） |
| GET | `/api/v1/system/operation-logs` | 操作日志查询（操作人/模块/操作/结果/时间范围；**不含 request_data** 大字段） |
| GET | `/api/v1/system/operation-logs/{id}` | 操作日志详情（含已脱敏的请求参数，展开行懒加载） |
| GET | `/api/v1/system/login-logs` | 登录日志查询（用户名/IP/结果/时间范围） |

### 基础数据接口（需求 2.1，登录即可 —— 业务操作不要求管理员）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET / POST | `/api/v1/base/personnel` | 人员列表（姓名模糊/状态/岗位筛选，附岗位与经理名）/ 新增（岗位须启用；经理非自己且在职） |
| GET / PUT / DELETE | `/api/v1/base/personnel/{id}` | 详情（附区域与计划）/ 编辑 / 删除（被团队成员或客户归属引用 → 400 引导改离职） |
| PUT | `/api/v1/base/personnel/{id}/status` | 在职 / 离职切换 |
| PUT | `/api/v1/base/personnel/{id}/regions` | 辐射区域全量替换（空列表即清空） |
| PUT | `/api/v1/base/personnel/{id}/plans` | 市场拓展计划全量替换 |
| GET / POST | `/api/v1/base/products` | 产品列表（名称/规格模糊、类别/状态筛选）/ 新增（类别值域校验；名称+规格组合唯一） |
| GET / PUT / DELETE | `/api/v1/base/products/{id}` | 详情 / 编辑 / 删除（被业务明细引用保护在业务表就位后生效） |
| PUT | `/api/v1/base/products/{id}/status` | 启用 / 停用 |
| GET / POST | `/api/v1/base/customers` | 客户列表（公司/负责人模糊、分类/归属筛选；`order_by=rating_score` 按评分排序，未评分垫底）/ 新增（分类值域；公司名+负责人唯一） |
| GET / PUT / DELETE | `/api/v1/base/customers/{id}` | 详情 / 编辑（**不触归属**）/ 删除 |
| PUT | `/api/v1/base/customers/{id}/rating` | 保存评级（评级计算器「保存评分」；只写 `rating_score`/`rating_time`，五项明细不落库 #25） |
| PUT | `/api/v1/base/customers/{id}/ownership` | 归属变更（同事务写留痕；只影响变更后核算，不回溯历史 #19） |
| GET | `/api/v1/base/customers/{id}/ownership-logs` | 归属变更留痕分页（join 人员出姓名） |

### 业务数据接口（需求 2.2，登录即可）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET / POST | `/api/v1/business/businesses` | 业务列表（编号/公司名模糊、状态/客户/归属/日期筛选）/ 创建（编号 `YW{日期}-{序号}` 自动生成；明细 ≥1 行；销售额服务层固化） |
| GET / PUT / DELETE | `/api/v1/business/businesses/{id}` | 详情（附明细）/ 编辑（明细全量替换 + 五项汇总重算；**归属不在此端点**）/ 删除（有发货或回款 → 400 引导改已终止） |
| PUT | `/api/v1/business/businesses/{id}/status` | 状态流转（1→2/3；终态不可再变更；终止必填原因；写状态留痕） |
| PUT | `/api/v1/business/businesses/{id}/ownership` | 负责/协助归属变更（同事务写留痕，owner_type=2） |
| GET | `/api/v1/business/businesses/{id}/ownership-logs` | 业务归属变更留痕分页 |
| GET | `/api/v1/business/businesses/{id}/status-logs` | 状态流转时间线（创建写首条 old=new=1） |
| GET | `/api/v1/business/businesses/{id}/gross-profit` | **毛利润数据视图**（只读实时计算，不落库：行级率/折算额 + 类别汇总；不含运费 #2；阈值按 `as_of` 取参数快照；成本缺失行标注无法计算） |
| GET / POST | `/api/v1/business/shipments` | 发货单列表 / 创建（编号 `SH…`；业务须执行中；行金额服务层固化；业务级发货/运费汇总回写） |
| GET / PUT / DELETE | `/api/v1/business/shipments/{id}` | 详情 / 编辑（终态业务禁改）/ 删除（被回款批次指定 → 400） |
| GET / POST | `/api/v1/business/receipts` | 回款列表（含 **payment_days 派生**：发货日首日=第 1 天 #1）/ 新增（编号 `HK…`；**shipment_id 同业务强校验**；业务须执行中） |
| GET / PUT / DELETE | `/api/v1/business/receipts/{id}` | 详情 / 编辑 / 删除（**已核算回款禁改禁删**——M3 防重锚点） |
| GET / POST | `/api/v1/business/rating-grades` | 评级等级全量列表（sort_order 升序）/ 新增（区间值域 + **与既有等级重叠 → 400**） |
| PUT / DELETE | `/api/v1/business/rating-grades/{id}` | 编辑（重叠判定）/ 删除（无下游引用，允许清空） |

全部写操作自动写入操作日志（成功与失败都记，机制见下）。

统一响应 `{code, message, data}`，分页为 `list/total/pageNum/pageSize`。
状态码：400 参数错误 / 401 未登录 / 403 无权限 / 404 不存在 / 500 服务端异常。

**登录失败一律 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` 显式降级。

### T+ 本地只读同步与管理

T+ 数据库是 SQL Server 只读源库，业务库仍为 MySQL。Docker 恢复 PoC、备份检查和 D 盘目录约定见 `docs/T+本地恢复与同步开发手册.md`。

- 连接配置在 `backend/.env` 的 `T_PLUS_*` 变量中，默认关闭，不配置时不影响主业务启动。
- `uv run python -m app.cli tplus-stage --entity personnel` 按主键分页，将源行写入 `tplus_sync_records` staging，并记录批次和失败信息。水位表已预留，时间增量未启用，`--watermark` 会明确拒绝。
- T+ 驱动通过 `uv sync --extra tplus` 安装到应用环境，ODBC 驱动名称必须显式配置；交付兼容目标为 SQL Server 2008 R2，2022 副本不能代替同版本验收。
- 查询目录 `db/queries/tplus/` 随部署交付，或使用 `T_PLUS_QUERY_DIR` 指定受控位置；支持六类主表和三类明细。
- T+ 字典中的候选字段在实际备份核验和客户确认前，不得直接覆盖岗位、工资标准、归属、业务状态或核算状态。
- 管理 API `/api/v1/system/tplus` 全部限管理员：概况、批次/异常分页、按需报告、创建与失败重试。HTTP 只创建 QUEUED 任务；`uv run python -m app.cli tplus-worker --watch --connection-file <项目外JSON路径>` 独立处理。
- 核心文件：`services/tplus/task_service.py`（幂等/重试）、`worker.py`（执行）、`relationship_audit.py`（字典与关联）、`query_service.py`（安全输出）、`core/tplus_lock.py`（跨提交执行锁）。原 CLI 读取与 worker 共用执行锁。
- V15 / Alembic `e5f607a8b9c0` 增加范围、跳过数、请求键、父批次、请求人和核验结果。未启用时间增量与工资业务导入；完整运行步骤和异常处理见本地恢复手册。

## 常用命令

```bash
uv sync                                  # 安装依赖
uv run uvicorn app.main:app --reload --port 8000   # 起服务（开发务必加 --reload）
uv run alembic upgrade head              # 应用迁移
uv run alembic revision --autogenerate -m "说明"   # 生成迁移
uv run python -m app.cli create-admin    # 建管理员（幂等，已存在不覆盖）
uv run pytest tests/unit -q              # 纯单元测试，无需容器
uv run pytest -q                         # 全部测试
uv run ruff check .                      # 代码检查
uv run ruff check --fix .                # 代码检查并自动修复可修项
uv run ruff format .                     # 格式化代码
```

Python 版本由 `.python-version` 与 `pyproject.toml` 的 `requires-python` 双重锁定。

### 代码检查与格式化

配置在 `pyproject.toml` 的 `[tool.ruff]`。三处**刻意关闭**的规则，不要误以为是漏配：

| 规则 | 关闭原因 |
| --- | --- |
| `E501` 行宽 | 已由 formatter 控制，lint 重复报无意义；长中文注释极易触发 |
| `B008` 参数默认值调用 | FastAPI 依赖注入要求在参数默认值处写 `Depends()`，是框架约定而非缺陷 |
| `RUF001/002/003` 易混淆 Unicode | 该规则默认针对英文文本，会把中文的全角逗号、句号、括号全部误报（本项目实测 800+ 条）。中文里全角标点正是规范写法 |

另有 `known-first-party = ["app", "tests"]`：本项目 `[tool.uv] package = false`（不作为包安装），不显式声明的话 ruff 无法识别 `app` 是第一方包，会把第三方依赖排到它后面。

## 关键实现约定

### JWT 时间一律用 UTC

`exp` 是 UTC 时间戳，而库列存本地时间（容器 `TZ=Asia/Shanghai`）。混算会产生 8 小时偏差，
表现为「刚登录就过期」或「过期了还能用」。库列用 `datetime.now()`，JWT 用 `datetime.now(timezone.utc)`。

### 「离职即失效」用 `users.token_version`，不依赖 Redis

禁用 / 改密 / 强制下线只需 `UPDATE users SET token_version = token_version + 1`。
鉴权时比对 JWT 的 `ver` 声明与库中值，Redis 故障时依然生效。
Redis 黑名单只负责「用户主动登出」。

### Redis 键 TTL 由业务语义决定，不要套用固定值

| 键 | TTL | 依据 |
| --- | --- | --- |
| `ys:captcha:{id}` | 300s | 规范要求 |
| `ys:login:fail:{username}` | 900s | = 锁定时长，写死会导致锁定提前失效 |
| `ys:token:blacklist:{jti}` | 令牌剩余有效期 | 写死会导致「登出 N 分钟后令牌又可用」 |

### 验证码用 `GETDEL` 原子取出即删

写成「先 GET 再 DEL」存在竞态窗口，并发请求可用同一验证码重复提交。

### 密码按字节数校验，不按字符数

bcrypt 5.0 起对超过 72 字节的密码**直接抛 ValueError**（此前是静默截断）。
中文一个字符占 3 字节，24 个汉字即到顶——`max_length=20` 这类字符数校验拦不住。

### 操作日志：审计上下文 + 独立提交

写操作统一经 `services/audit_service.py` 的 `audit()` 上下文管理器留痕（用法见 `api/v1/system/users.py`）：

- 调用形态为 DTO：`audit(session, operator=..., record=AuditRecord(module, action, summary, request_data), meta=...)`；落库条目为 `OperationLogEntry`
- 正常退出记成功；抛异常**先 `session.rollback()` 再**记失败（success=0 + 中文错误原因），随后原异常继续传播
- 日志**独立 commit**，整体兜底不外抛 —— 方向是「审计可丢，业务不可断」；反向理解：业务失败回滚不会带走失败记录，而那正是审计最需要的
- **操作人标量在进入上下文时固化**：失败路径先 rollback 会使 ORM 对象过期，之后再读 id/username 会触发额外查询（账号并发被删时 ObjectDeletedError 还会被兜底吞掉）
- 请求元信息（ip / user-agent / method / path）经路由层的 `RequestMetaDep` 传入 service
- **commit 之后的任何查询/ORM 读取都要前置**（提到 commit 前或用已固化的局部变量）：业务已提交却因后置查询抛错会被记成「失败」，产生与事实相反的审计
- 文本列按 `models/operation_log.py` 的长度常量截断；`request_data` 先经**结构化脱敏**（递归按键名整值抹除 password/token 等，不依赖文本模式匹配）再经 `core.logging.scrub` 文本兜底，最后按 **UTF-8 字节边界**截断（encode 带 `errors="replace"` 兜底孤立代理字符）—— 超长/编码异常都会在 MySQL 或 encode 处抛出，被兜底吞掉后表现为「日志莫名消失」
- **日志列表与详情两段式**：`operation-logs` 列表排除 `request_data`（TEXT 大字段，随列表返回会让翻页负担随表增长），展开详情走 `GET /operation-logs/{id}` 懒加载
- 模块/操作词表在 `core/constants.py`（`MODULE_*` / `ACTION_*`），前端 `utils/constants.ts` 与其对齐

**角色管理保护规则**（后端是唯一防线，前端按钮禁用只是体验）：admin 角色禁删禁停；有用户绑定的角色禁删（`user_roles` 外键是 CASCADE；删除前走 `SELECT ... FOR UPDATE` 锁行，堵住并发绑定窗口）；`role_code` 创建后不可改；**停用角色不可再分配**（`_resolve_roles` 校验 status，停用只影响新分配、不影响既有授权）。

### M2 业务数据的四个关键约定（2026-10-13 定稿，改动前先读）

- **单据编号**（`services/no_generator.py`）：`{前缀}{YYYYMMDD}-{当日4位序号}`，业务 YW / 发货 SH / 回款 HK（`core/constants.py` 的 `NO_PREFIX_*`）。`SELECT MAX ... FOR UPDATE` 锁当日区间防并发重号；残余竞态以唯一键 1062 冲突**重试一次**兜底（无限重试会掩盖死锁）。序号超 4 位按实际位数输出（VARCHAR(32) 余量足够）。
- **五项汇总冗余**（`businesses.total_*`）：明细/发货/回款的任何写路径统一收口到 `business_service._recalc_totals` 单点重算，禁止各处手写 SUM 回写；发货与回款服务写操作前**必须 `get_by_id(for_update=True)` 锁业务行**（防两模块并发写同一业务的丢失更新）。毛利润率/折算额**不落库**——它们是明细金额 + 时点化阈值的派生值，落库会在成本调整或参数改版后漂移；视图接口（`/gross-profit`）实时算，M3 核算台账才是法定固化点。
- **留痕表的固化设计**：`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` 仅要求登录（含停用岗位），供财务/领导在报表中按岗位筛选；岗位管理接口仍仅管理员。

### 面向业务人员的文案（2026-10-23 定稿，改文案前先读）

系统由财务与营销人员日常使用，**不是给开发者看的**。凡是会渲染到页面的文本（参数说明、错误提示、口径注释）一律按业务语言写：

- **`param_registry.py` 的 `description` 是唯一显示源**，会直出到「计提参数」页参数名下方。写清「这个参数管什么、钱怎么变、什么时候该调它」，不写英文枚举名（`FULL`/`BALANCE`）、需求编号（`澄清 #10`）、内部阶段号（`M3`/`M4 ⑧`）、实现层精度约束（「禁止按 0.011111 截断存储」留在代码注释与测试里）。
- **枚举值在页面上必须翻译**：前端 `params/index.vue` 的 `ENUM_VALUE_LABELS`（`FULL` 当月全额 / `BALANCE` 余额 / `INCLUDE` 含基本工资 / `DEDUCT` 扣除基本工资 / `EXCLUDE` 不计基本工资 / `1` 开 / `0` 关）与 `DIMENSION_LABELS`（`municipal_water` 市政水利 / `rail_transit` 轨道交通）。后端报错也不许把原始枚举值甩给用户 —— `param_service._preview_rate` 的产品类别校验用 `「市政水利、轨道交通」` 而不是 `municipal_water / rail_transit`。
- **公式模板报错用中文模板名**：`calc_templates.TEMPLATES[code].name`，取不到才回退 code；文案要给出下一步（「请在岗位角色里改用业务员递减或信息员固定计提」），而不是只说「不支持」。
- **`db/init/init-dev.sql` 的种子 description 必须与 registry 同源**：它只在数据卷为空时首次启动执行，已有库要跑 `ai-aux/preview/sync_param_desc.py`（读 `PARAM_REGISTRY` 逐条 UPDATE）才看得到新文案。`db/migration/V*.sql` 里的旧描述是历史记录，**不要回头改** —— 改了会让已部署库与脚本不一致。
- **前端模板层禁止出现开发者语汇**：`澄清 / 待业务 / M3 / M4 / 一期 / 二阶段 / 暂口径 / 待确认 / 待接 / 暂不 / 待补` 只允许出现在代码注释里。改完用 grep 扫一遍 `frontend/src/views`。
- **台账与预览里落库的说明文字（`rate_text` / `rate_note` / 聚合行 `snapshot_json.note`）同样受管**：这些会出现在绩效台账、个人明细、打印稿与计算预览上。写成「这笔为什么是这个比例、什么时候不再降」（如「回款 20 天，从起始 10‰ 按日递减（满 360 天后固定按 4‰ 计算）」），不写 `基数开关=1`、`#12 参数化`、`9.8 方案公式` 这类需求编号。**分数原文（`11/1125`）与百分比拼装（`聚合:20%+5%`）不算说明文字**，那是金额口径的可复核原文，不要为了「口语化」把它改成四舍五入的小数。

## 常见问题

**起服务报 `APP_SECRET_KEY` 相关错误** —— `backend/.env` 未填或不足 32 字符。这是刻意的 fail-fast：空密钥签发 JWT 是安全问题，必须启动即失败。

**连数据库抛 `RuntimeError: 'cryptography' package is required`** —— 依赖被改回不带 `[rsa]` 的 `pymysql`。装回 `pymysql[rsa]`。

**`alembic upgrade head` 报表已存在** —— 开发库是 `init-dev.sql` 建的、`alembic_version` 未写入。手工补版本记录，或 `down -v` 重建。

**改了代码不生效** —— 启动时没加 `--reload`。

## 系统监控（2026-11-02）

新增管理员只读接口 `/api/v1/system/monitor/{overview,trends,interfaces,events,diagnostic}`，事件详情为 `/events/{id}`。后台独立线程每 15 秒采集，分钟聚合保留 7 天；配置见 `.env.example` 的 `MONITOR_*`，新增依赖 `psutil`。部署限单个后端应用进程，按项目流程应用 V23 迁移后启动。异常通过 `X-Request-ID` 与脱敏服务端日志关联，`/api/health` 原契约保持不变。

详细采集口径、故障边界、排查步骤和接口见 [系统监控运维说明](../docs/系统监控运维说明.md)。

## 角色授权（2026-11-02）

系统权限统一为“角色配置权限 → 用户分配角色 → 用户继承权限”。V26（`26e7f8a9b0c1`）停用旧个人覆盖和全局制作人入口；工资核算、生成、调整分别检查角色权限，月份实际经办人、生成锁和历史留痕继续保留。接口与迁移边界见 [角色授权使用说明](../docs/角色授权使用说明.md)。