merge: 集成客户评级弹窗、公司信息精简与参数中文化

将 feat/settings-rating-brand（基于 927592b）合并到最新 main（d03ddad）：
- 冲突收口：系统设置服务/契约、集成测试夹具、布局/路由/登录页、客户列表
- 迁移重编号：本分支未发布的三个迁移压成 V11（客户评级 + 站点信息 + 版本号），
  down_revision 接到 main 的 90653814a421，db/migration 相应改为 V11
- 站点图标上传与 logo 上传统一为同步 def，超限先按 file.size 拦截

.gitignore

@@ -64,3 +64,9 @@ CLAUDE.md
 backend/uploads/
 # 数据库备份导出目录（⑨ 备份脚本产物）
 db/backups/
+
+# 外部参考资料（2026-10-20）：T+12.3 数据字典压缩包与解压目录不入版本库
+docs/**/*.rar
+docs/T_12.3数据字典/
+# macOS 压缩包残留元数据
+__MACOSX/

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,32 @@ 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。
 
+### 工作台口径（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/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/c4e2a86f9b13_v11_客户评级落库与站点信息.py

@@ -0,0 +1,212 @@
+"""V11 客户评级落库与站点信息
+
+Revision ID: c4e2a86f9b13
+Revises: 90653814a421
+Create Date: 2026-10-19 10:00:00.000000
+
+与上游 V7–V10（台账/月结/调整单/口径/唯一键/预警参数）合并时重编号为 V11：
+本分支三个迁移（原 V7 客户评级 + V8 公司档案精简 + V9 图片版本号）从未发布，
+压成单条，最终结构 = 评级表 + 最终版站点/公司信息字段（不含中途增删的
+副标题/信用代码/地址/电话/邮箱）。
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import mysql
+
+# revision identifiers, used by Alembic.
+revision: str = "c4e2a86f9b13"
+down_revision: str | Sequence[str] | None = "90653814a421"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """应用迁移（双主题一次交付）。
+
+    - 客户评级弹窗化：评分每客户落库（customer_ratings，一行一客户快照）
+    - 公司信息补充与精简：标语/页脚/备案号/站点标题/站点图标 + 图片版本号
+    """
+    op.create_table(
+        "customer_ratings",
+        sa.Column(
+            "id", mysql.BIGINT(unsigned=True), autoincrement=True, nullable=False, comment="主键ID"
+        ),
+        sa.Column(
+            "customer_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=False,
+            comment="客户ID（唯一：一客户一份当前评级）",
+        ),
+        sa.Column(
+            "score_ship_amount",
+            sa.Numeric(precision=5, scale=1),
+            server_default="0",
+            nullable=False,
+            comment="发货额评分（0-20）",
+        ),
+        sa.Column(
+            "score_receipt_rate",
+            sa.Numeric(precision=5, scale=1),
+            server_default="0",
+            nullable=False,
+            comment="回款率评分（0-20）",
+        ),
+        sa.Column(
+            "score_profit_rate",
+            sa.Numeric(precision=5, scale=1),
+            server_default="0",
+            nullable=False,
+            comment="毛利率评分（0-20）",
+        ),
+        sa.Column(
+            "score_contract_cooperation",
+            sa.Numeric(precision=5, scale=1),
+            server_default="0",
+            nullable=False,
+            comment="合同履约配合能力评分（0-20）",
+        ),
+        sa.Column(
+            "score_site_construction",
+            sa.Numeric(precision=5, scale=1),
+            server_default="0",
+            nullable=False,
+            comment="现场规范施工能力评分（0-20）",
+        ),
+        sa.Column(
+            "total_score",
+            sa.Numeric(precision=5, scale=1),
+            nullable=False,
+            comment="总分（服务端重算，五项之和 0-100）",
+        ),
+        sa.Column(
+            "grade_name",
+            sa.String(length=32),
+            nullable=True,
+            comment="评级等级（保存时按等级映射快照固化，无外键；未命中/等级表空为 NULL）",
+        ),
+        sa.Column("remark", sa.String(length=255), nullable=True, comment="备注"),
+        sa.Column(
+            "scorer_id",
+            mysql.BIGINT(unsigned=True),
+            nullable=True,
+            comment="评级操作人ID（账号删除后置空）",
+        ),
+        sa.Column(
+            "scorer_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(
+            ["customer_id"],
+            ["customers.id"],
+            name=op.f("fk_customer_ratings_customer_id"),
+            ondelete="RESTRICT",
+        ),
+        sa.ForeignKeyConstraint(
+            ["scorer_id"],
+            ["users.id"],
+            name=op.f("fk_customer_ratings_scorer_id"),
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_customer_ratings")),
+        sa.UniqueConstraint("customer_id", name=op.f("uk_customer_ratings_customer_id")),
+        comment="客户评级表（每客户一行；等级名为快照固化无外键，删等级不伤已评级记录）",
+        mysql_charset="utf8mb4",
+        mysql_collate="utf8mb4_general_ci",
+        mysql_engine="InnoDB",
+    )
+    op.add_column(
+        "system_settings",
+        sa.Column(
+            "site_title",
+            sa.String(length=64),
+            nullable=True,
+            comment="站点标题（浏览器标签页与侧边栏副标题；null=内置默认）",
+        ),
+    )
+    op.add_column(
+        "system_settings",
+        sa.Column(
+            "brand_slogan",
+            sa.String(length=64),
+            nullable=True,
+            comment="品牌标语（登录页与品牌预览；null=内置默认）",
+        ),
+    )
+    op.add_column(
+        "system_settings",
+        sa.Column(
+            "footer_text",
+            sa.String(length=64),
+            nullable=True,
+            comment="页脚版权文本（登录页；null=自动生成 © 公司名 · 内部系统）",
+        ),
+    )
+    op.add_column(
+        "system_settings",
+        sa.Column(
+            "icp_no",
+            sa.String(length=32),
+            nullable=True,
+            comment="ICP 备案号（登录页页脚，空=不显示）",
+        ),
+    )
+    op.add_column(
+        "system_settings",
+        sa.Column(
+            "favicon_path",
+            sa.String(length=255),
+            nullable=True,
+            comment="站点图标相对路径（文件存 uploads/favicon/，null=使用内置 favicon.svg）",
+        ),
+    )
+    op.add_column(
+        "system_settings",
+        sa.Column(
+            "logo_version",
+            sa.Integer(),
+            server_default="0",
+            nullable=False,
+            comment="logo 版本号（每次上传 +1；图片 URL 用它破缓存——同扩展名覆盖时路径不变，update_time 也不变）",
+        ),
+    )
+    op.add_column(
+        "system_settings",
+        sa.Column(
+            "favicon_version",
+            sa.Integer(),
+            server_default="0",
+            nullable=False,
+            comment="站点图标版本号（每次上传 +1；图片 URL 用它破缓存）",
+        ),
+    )
+
+
+def downgrade() -> None:
+    """回滚迁移：先删评级表（引用 customers/users），再逆序移除站点信息列。"""
+    op.drop_table("customer_ratings")
+    op.drop_column("system_settings", "favicon_version")
+    op.drop_column("system_settings", "logo_version")
+    op.drop_column("system_settings", "favicon_path")
+    op.drop_column("system_settings", "icp_no")
+    op.drop_column("system_settings", "footer_text")
+    op.drop_column("system_settings", "brand_slogan")
+    op.drop_column("system_settings", "site_title")

backend/app/api/deps.py

@@ -119,20 +119,23 @@ AdminUser = Annotated[User, Depends(require_admin)]
 LoginUser = Annotated[User, Depends(get_current_user)]
 
 
-def require_roles(*role_codes: str):
+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("无权访问审批管理")
+            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
@@ -16,6 +17,8 @@ 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
@@ -51,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/*，业务操作登录即可访问
@@ -65,5 +69,9 @@ v1_router.include_router(business_router)
 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

@@ -24,7 +24,8 @@ from app.schemas.customer import (
     CustomerUpdateIn,
     OwnershipChangeLogOut,
 )
-from app.services import customer_service
+from app.schemas.rating import CustomerRatingOut, CustomerRatingSaveIn
+from app.services import customer_service, rating_service
 
 router = APIRouter(prefix="/customers", tags=["客户管理"])
 
@@ -140,3 +141,45 @@ def list_ownership_logs(
 ) -> ApiResponse[PageResult[OwnershipChangeLogOut]]:
     """查某客户的归属变更留痕（分页，按变更时间倒序，附新旧归属人员姓名）。"""
     return ok(customer_service.list_ownership_logs(session, customer_id, query))
+
+
+@router.get(
+    "/{customer_id}/rating",
+    response_model=ApiResponse[CustomerRatingOut],
+    summary="客户当前评级",
+)
+def get_customer_rating(
+    session: DbSession,
+    _: CurrentUser,
+    customer_id: Annotated[int, Path(ge=1)],
+) -> ApiResponse[CustomerRatingOut]:
+    """查某客户当前评级。
+
+    未评级返回 ``data: null``（这是正常态而非错误）；客户不存在才 404。
+    """
+    return ok(rating_service.get_customer_rating(session, customer_id))
+
+
+@router.put(
+    "/{customer_id}/rating",
+    response_model=ApiResponse[CustomerRatingOut],
+    summary="保存客户评级",
+)
+def save_customer_rating(
+    session: DbSession,
+    current_user: CurrentUser,
+    customer_id: Annotated[int, Path(ge=1)],
+    payload: CustomerRatingSaveIn,
+    meta: RequestMetaDep,
+) -> ApiResponse[CustomerRatingOut]:
+    """保存客户评级（首次创建、再次保存整体覆盖）。
+
+    五项分值 0-20 由服务层在审计上下文内校验，总分与等级由服务端重算；
+    等级按保存时点的映射快照固化，等级表后续增删改不影响该客户结论。
+    """
+    return ok(
+        rating_service.save_customer_rating(
+            session, customer_id, payload, 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/system/settings.py

@@ -1,11 +1,11 @@
-"""系统设置接口（公司信息）。
+"""系统设置接口（公司信息 + 站点信息）。
 
-`GET /public` 与 `GET /logo/public` **无鉴权**：登录页渲染公司名/logo 时
+`GET /public`、`GET /logo/public`、`GET /favicon/public` **无鉴权**：登录页
-尚无令牌。响应经 `SettingPublicOut` 白名单收敛（见 schemas/setting.py），
+渲染公司名/logo、浏览器加载标签页图标时尚无令牌。响应经
-仅暴露两个非敏感展示字段。
+`SettingPublicOut` 白名单收敛（见 schemas/setting.py），仅暴露展示必需字段。
 
-`/logo/public` 返回文件流而非统一信封——与参数导出同一例外口径
+`/logo/public` 与 `/favicon/public` 返回文件流而非统一信封——与参数导出
-（二进制响应套 JSON 信封无意义）。
+同一例外口径（二进制响应套 JSON 信封无意义）。
 """
 
 from fastapi import APIRouter, Response, UploadFile
@@ -20,6 +20,7 @@ from app.services import system_setting_service as service
 router = APIRouter(prefix="/settings", tags=["系统管理 · 公司信息"])
 
 _LOGO_MEDIA_TYPE = {"png": "image/png", "jpg": "image/jpeg"}
+_FAVICON_MEDIA_TYPE = {"png": "image/png", "jpg": "image/jpeg", "ico": "image/x-icon"}
 
 
 @router.get("", response_model=ApiResponse[SettingOut], summary="公司信息")
@@ -28,14 +29,14 @@ def get_settings(session: DbSession, _: AdminUser) -> ApiResponse[SettingOut]:
     return ok(service.to_out(service.get_setting(session)))
 
 
-@router.put("", response_model=ApiResponse[SettingOut], summary="更新公司名称")
+@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="已保存",
@@ -55,7 +56,7 @@ def upload_logo(
     它们卡死事件循环（项目红线：全栈同步路由，FastAPI 自动进线程池）。
     大小先用 `file.size` 拦截，避免超限文件整体读进内存。
     """
-    if file.size is not None and file.size > service.LOGO_MAX_BYTES:
+    if file.size is not None and file.size > service.ASSET_MAX_BYTES:
         raise BadRequestError("logo 文件不能超过 2MB")
     content = file.file.read()
     ext = (file.filename or "").rsplit(".", 1)[-1]
@@ -65,6 +66,27 @@ def upload_logo(
     )
 
 
+@router.post("/favicon", response_model=ApiResponse[SettingOut], summary="上传站点图标")
+def upload_favicon(
+    file: UploadFile,
+    session: DbSession,
+    current_user: AdminUser,
+    meta: RequestMetaDep,
+) -> ApiResponse[SettingOut]:
+    """上传站点图标（png/jpg/ico ≤2MB；固定名覆盖，旧扩展名文件清理）。
+
+    同步 `def` 与 logo 上传同口径：磁盘写与审计提交均为阻塞操作。
+    """
+    if file.size is not None and file.size > service.ASSET_MAX_BYTES:
+        raise BadRequestError("站点图标文件不能超过 2MB")
+    content = file.file.read()
+    ext = (file.filename or "").rsplit(".", 1)[-1]
+    return ok(
+        service.save_favicon(session, content, ext, operator=current_user, meta=meta),
+        message="站点图标已更新",
+    )
+
+
 @router.get("/public", response_model=ApiResponse[SettingPublicOut], summary="公司信息（匿名）")
 def get_settings_public(session: DbSession, response: Response) -> ApiResponse[SettingPublicOut]:
     """公司信息（登录页消费，无鉴权）。短缓存减轻匿名端点压力。"""
@@ -81,3 +103,14 @@ def get_logo_public(session: DbSession) -> FileResponse:
         media_type=_LOGO_MEDIA_TYPE.get(ext, "application/octet-stream"),
         headers={"Cache-Control": "no-cache"},
     )
+
+
+@router.get("/favicon/public", summary="站点图标（匿名）")
+def get_favicon_public(session: DbSession) -> FileResponse:
+    """站点图标文件流（无鉴权）。no-cache：图标替换后由版本参数破缓存兜底。"""
+    path, ext = service.read_favicon(session)
+    return FileResponse(
+        path,
+        media_type=_FAVICON_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/constants.py

@@ -87,6 +87,7 @@ MODULE_SYSTEM_SETTINGS = "系统设置"
 MODULE_APPROVAL = "审批管理"
 MODULE_CALC = "绩效核算"
 MODULE_SETTLEMENT = "月度结算"
+MODULE_REPORT = "报表统计"
 
 # ===== 单据编号前缀（{前缀}{YYYYMMDD}-{当日4位序号}，序号按自然日重置）=====
 # 一期为代码常量（业务未提出配置诉求）；如需可配置，走 M1 参数体系新增参数组
@@ -105,3 +106,4 @@ ACTION_ENABLE = "启用"
 ACTION_DISABLE = "禁用"
 ACTION_APPROVE = "审批通过"
 ACTION_REJECT = "审批驳回"
+ACTION_EXPORT = "导出"

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

@@ -14,6 +14,7 @@ from app.models.base import Base, TimestampMixin
 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.customer_rating import CustomerRating
 from app.models.login_log import LoginLog
 from app.models.operation_log import OperationLog
 from app.models.param import ParamChangeBatch, ParamDefinition, ParamValue
@@ -38,6 +39,7 @@ __all__ = [
     "BusinessRole",
     "BusinessStatusLog",
     "Customer",
+    "CustomerRating",
     "CustomerRatingGrade",
     "LoginLog",
     "MonthlySettlement",

backend/app/models/customer_rating.py

@@ -0,0 +1,77 @@
+"""客户评级模型（需求 2.2.5）。
+
+评级从「纯计算器不落库」升级为**每客户一行落库**（2026-10-19 确认）：
+客户管理页要罗列评级列并按其排序，评分必须可回溯。设计要点：
+
+- ``customer_id`` 唯一键 + RESTRICT 外键：一客户一份当前评级（快照语义，
+  非流水），删除客户由服务层先删评级行再删主行（RESTRICT 兜底并发窗口）
+- ``grade_name`` 为**快照固化、无外键**：等级映射表仍允许自由增删清空
+  （rating_service 的既有前提），删等级不能伤及已评级客户的历史结论 ——
+  与归属留痕「ID/人名固化、不回溯」同一论证口径；等级未命中时为 NULL
+- ``scorer_id`` 外键 SET NULL + ``scorer_name`` 冗余固化：账号删除后
+  记录仍可读（同 ownership_change_logs 的操作人口径）
+- 分值列 DECIMAL(5,1)：UI 整数 0-20，DECIMAL 留十进制余地；总分由
+  **服务端重算**，不采信前端回传
+"""
+
+from decimal import Decimal
+
+from sqlalchemy import ForeignKey, Numeric, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import BIGINT_UNSIGNED, Base, TimestampMixin, mysql_table_args
+
+
+class CustomerRating(Base, TimestampMixin):
+    """客户评级表：每客户一行（uk_customer_ratings_customer_id）。
+
+    五项各 0-20 分、总分 = 五项之和（0-100），判定规则同等级映射表
+    （按 sort_order 升序首个 min_score ≤ 总分，见 rating_service.resolve_grade）。
+    """
+
+    __tablename__ = "customer_ratings"
+    __table_args__ = mysql_table_args(
+        "客户评级表（每客户一行；等级名为快照固化无外键，删等级不伤已评级记录）",
+        UniqueConstraint("customer_id", name="uk_customer_ratings_customer_id"),
+    )
+
+    id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED, primary_key=True, autoincrement=True, comment="主键ID"
+    )
+    customer_id: Mapped[int] = mapped_column(
+        BIGINT_UNSIGNED,
+        ForeignKey("customers.id", ondelete="RESTRICT"),
+        nullable=False,
+        comment="客户ID（唯一：一客户一份当前评级）",
+    )
+    score_ship_amount: Mapped[Decimal] = mapped_column(
+        Numeric(5, 1), nullable=False, server_default="0", comment="发货额评分（0-20）"
+    )
+    score_receipt_rate: Mapped[Decimal] = mapped_column(
+        Numeric(5, 1), nullable=False, server_default="0", comment="回款率评分（0-20）"
+    )
+    score_profit_rate: Mapped[Decimal] = mapped_column(
+        Numeric(5, 1), nullable=False, server_default="0", comment="毛利率评分（0-20）"
+    )
+    score_contract_cooperation: Mapped[Decimal] = mapped_column(
+        Numeric(5, 1), nullable=False, server_default="0", comment="合同履约配合能力评分（0-20）"
+    )
+    score_site_construction: Mapped[Decimal] = mapped_column(
+        Numeric(5, 1), nullable=False, server_default="0", comment="现场规范施工能力评分（0-20）"
+    )
+    total_score: Mapped[Decimal] = mapped_column(
+        Numeric(5, 1), nullable=False, comment="总分（服务端重算，五项之和 0-100）"
+    )
+    grade_name: Mapped[str | None] = mapped_column(
+        String(32),
+        comment="评级等级（保存时按等级映射快照固化，无外键；未命中/等级表空为 NULL）",
+    )
+    remark: Mapped[str | None] = mapped_column(String(255), comment="备注")
+    scorer_id: Mapped[int | None] = mapped_column(
+        BIGINT_UNSIGNED,
+        ForeignKey("users.id", ondelete="SET NULL"),
+        comment="评级操作人ID（账号删除后置空）",
+    )
+    scorer_name: Mapped[str] = mapped_column(
+        String(64), nullable=False, comment="评级操作人用户名（冗余固化）"
+    )

backend/app/models/rating.py

@@ -1,9 +1,10 @@
 """客户评级等级配置模型（需求 2.2.5）。
 
-评级计算器定位为「仅打分工具，不影响绩效金额」（对照表 #25）：评分记录
+评级定位为「仅打分工具，不影响绩效金额」（对照表 #25）：评分自 2026-10-19
-不落库，等级**映射关系**可配置由本表承载。判定规则：按 sort_order 升序取
+起每客户落库于 customer_ratings（快照固化等级名），本表承载可配置的等级
-第一个 min_score ≤ 总分的等级 —— 单边判定避免区间边界（如 75 分）在
+**映射关系**。判定规则：按 sort_order 升序取第一个 min_score ≤ 总分的
-「≥75 且 ≤89」与「>74 且 <75」两套写法间的重叠/遗漏歧义；max_score 仅展示。
+等级 —— 单边判定避免区间边界（如 75 分）在「≥75 且 ≤89」与「>74 且 <75」
+两套写法间的重叠/遗漏歧义；max_score 仅展示。
 """
 
 from decimal import Decimal

backend/app/models/system_setting.py

@@ -1,31 +1,67 @@
-"""系统设置模型：公司信息单例行。
+"""系统设置模型：公司信息 + 站点信息单例行。
 
 与 M1 计提参数体系刻意分离：公司名称/logo 是「展示事实」，没有按生效日期
 时点化演算的语义（参数体系按 effective_date 取值快照），且参数值列
-value_text 为 String(64) 装不下；故独立单行表。logo 只存相对路径——文件在
+value_text 为 String(64) 装不下；故独立单行表。logo/favicon 只存相对路径——
-`backend/uploads/logo/`，独立于数据库备份体积且可单独替换（见
+文件在 `backend/uploads/{logo,favicon}/`，独立于数据库备份体积且可单独替换
-system_setting_service）。整个系统恒为单行（迁移种子 id=1 保底，upsert 维护）。
+（见 system_setting_service）。整个系统恒为单行（迁移种子 id=1 保底）。
+
+2026-10-20 精简（用户确认）：企业档案字段（信用代码/地址/电话/邮箱）与
+系统副标题删除，新增**站点标题**（浏览器标签页/侧边栏副标题）与**站点图标**
+（浏览器标签页 favicon，独立于登录页 logo）。
 """
 
-from sqlalchemy import String
+from sqlalchemy import Integer, 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。"""
+    """系统设置表：公司信息 + 站点信息，全系统单行 id=1。
+
+    brand_slogan/footer_text/icp_no/site_title 均可空：null 表示前端回退
+    内置默认值，存量行为零变化。
+    """
 
     __tablename__ = "system_settings"
-    __table_args__ = mysql_table_args("系统设置表（公司信息，全系统单行）")
+    __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="公司名称（登录页与导出页眉展示）"
+        String(64), nullable=False, comment="公司名称（登录页/侧边栏/浏览器标题展示）"
     )
     logo_path: Mapped[str | None] = mapped_column(
         String(255),
-        comment="logo 相对路径（文件存 uploads/logo/，null=未上传使用默认）",
+        comment="公司 logo 相对路径（文件存 uploads/logo/，null=未上传使用默认）",
+    )
+    logo_version: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        server_default="0",
+        comment="logo 版本号（每次上传 +1；图片 URL 用它破缓存——同扩展名覆盖时路径不变，update_time 也不变）",
+    )
+    site_title: Mapped[str | None] = mapped_column(
+        String(64), comment="站点标题（浏览器标签页与侧边栏副标题；null=内置默认）"
+    )
+    brand_slogan: Mapped[str | None] = mapped_column(
+        String(64), comment="品牌标语（登录页与品牌预览；null=内置默认）"
+    )
+    footer_text: Mapped[str | None] = mapped_column(
+        String(64), comment="页脚版权文本（登录页；null=自动生成 © 公司名 · 内部系统）"
+    )
+    icp_no: Mapped[str | None] = mapped_column(
+        String(32), comment="ICP 备案号（登录页页脚，空=不显示）"
+    )
+    favicon_path: Mapped[str | None] = mapped_column(
+        String(255),
+        comment="站点图标相对路径（文件存 uploads/favicon/，null=跟随公司 logo / 内置 favicon.svg）",
+    )
+    favicon_version: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        server_default="0",
+        comment="站点图标版本号（每次上传 +1；图片 URL 用它破缓存）",
     )

backend/app/repositories/customer_rating_repository.py

@@ -0,0 +1,33 @@
+"""客户评级数据访问（每客户一行）。
+
+本层只 flush 不 commit —— 事务边界由 services 层控制。
+"""
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.models import CustomerRating
+
+# ==================== 读取 ====================
+
+
+def get_by_customer_id(session: Session, customer_id: int) -> CustomerRating | None:
+    """查某客户的当前评级（uk_customer_ratings_customer_id 保证至多一行）。"""
+    stmt = select(CustomerRating).where(CustomerRating.customer_id == customer_id)
+    return session.execute(stmt).scalar_one_or_none()
+
+
+# ==================== 写入 ====================
+
+
+def create(session: Session, rating: CustomerRating) -> CustomerRating:
+    """新增评级行。只 flush 以取得自增 id。"""
+    session.add(rating)
+    session.flush()
+    return rating
+
+
+def delete(session: Session, rating: CustomerRating) -> None:
+    """删除评级行（客户物理删除前的联动清理，调用方先校验业务引用）。"""
+    session.delete(rating)
+    session.flush()

backend/app/repositories/customer_repository.py

@@ -6,7 +6,7 @@
 from sqlalchemy import ColumnElement, Row, Select, func, or_, select
 from sqlalchemy.orm import Session
 
-from app.models import Customer, OwnershipChangeLog, Personnel
+from app.models import Customer, CustomerRating, OwnershipChangeLog, Personnel
 from app.models.customer import OWNER_TYPE_CUSTOMER
 from app.repositories import ownership_log_repository
 from app.repositories.query_utils import fuzzy
@@ -31,7 +31,7 @@ def count_business_refs(session: Session, customer_id: int) -> int:
 
 
 def get_with_owner_name(session: Session, customer_id: int) -> Row | None:
-    """查单个客户并带出归属人员姓名（详情、编辑回显与归属变更共用）。"""
+    """查单个客户并带出归属人员姓名与评级快照（详情/编辑回显/归属变更共用）。"""
     stmt = _base_select().where(Customer.id == customer_id)
     return session.execute(stmt).first()
 
@@ -53,12 +53,14 @@ def list_customers(
     keyword: str | None = None,
     customer_type: str | None = None,
     owner_personnel_id: int | None = None,
+    order_field: str | None = None,
+    order_type: str | None = None,
 ) -> list[Row]:
-    """分页查询客户，行内容为 (客户, 归属人员姓名)。
+    """分页查询客户，行内容为 (客户, 归属人员姓名, 评级总分, 评级等级)。
 
-    归属人员外键非空但统一用 outerjoin：人员行不可考（被物理删除的脏数据）
+    归属人员/评级行均用 outerjoin：关联行不可考（人员被物理删除、客户
-    不应让客户行整个查不出来（同 personnel_repository 的韧性口径）。
+    未评级）不应让客户行整个查不出来（同 personnel_repository 韧性口径）。
-    排序按 id 倒序：客户无排序字段，新增的靠前符合列表页习惯。
+    默认排序按 id 倒序：新增的靠前符合列表页习惯；评级排序见 ``_apply_order``。
     """
     stmt = _apply_filters(
         _base_select(),
@@ -66,7 +68,8 @@ def list_customers(
         customer_type=customer_type,
         owner_personnel_id=owner_personnel_id,
     )
-    stmt = stmt.order_by(Customer.id.desc()).offset(offset).limit(limit)
+    stmt = _apply_order(stmt, order_field=order_field, order_type=order_type)
+    stmt = stmt.offset(offset).limit(limit)
     return list(session.execute(stmt).all())
 
 
@@ -120,12 +123,38 @@ def count_ownership_logs(session: Session, *, customer_id: int) -> int:
 
 
 def _base_select() -> Select:
-    """客户主表外联归属人员姓名。"""
+    """客户主表外联归属人员姓名与评级快照（等级名/总分，列表评级列免 N+1）。"""
-    return select(Customer, Personnel.personnel_name).outerjoin(
+    return (
-        Personnel, Customer.owner_personnel_id == Personnel.id
+        select(
+            Customer,
+            Personnel.personnel_name,
+            CustomerRating.total_score,
+            CustomerRating.grade_name,
+        )
+        .outerjoin(Personnel, Customer.owner_personnel_id == Personnel.id)
+        .outerjoin(CustomerRating, CustomerRating.customer_id == Customer.id)
     )
 
 
+def _apply_order(stmt: Select, *, order_field: str | None, order_type: str | None) -> Select:
+    """应用列表排序。默认 id 倒序；order_field=rating 按评级总分排序。
+
+    等级由总分判定、与总分同向，故按总分即等价按等级排序。MySQL 没有
+    ``NULLS LAST`` 语法，用布尔键 ``total_score IS NULL`` 升序模拟 ——
+    未评级行恒在末尾，正序/倒序一致；同分以 id 倒序兜底保证次序稳定。
+    非法字段/方向不落到 SQL（schema Literal 已在入口拦 400），此处静默
+    回退默认排序作为纵深防御。
+    """
+    if order_field == "rating" and order_type in ("asc", "desc"):
+        score_order = (
+            CustomerRating.total_score.asc()
+            if order_type == "asc"
+            else CustomerRating.total_score.desc()
+        )
+        return stmt.order_by(CustomerRating.total_score.is_(None), score_order, Customer.id.desc())
+    return stmt.order_by(Customer.id.desc())
+
+
 def _apply_filters(
     stmt: Select,
     *,

backend/app/repositories/dashboard_repository.py

@@ -0,0 +1,237 @@
+"""工作台仓储：四区块的只读聚合查询；不 commit、不抛业务异常。
+
+总览只做 SQL 聚合（SUM/COUNT DISTINCT），不复用报表的
+``department_summary``——后者会加载整月台账并逐团队查人员，适合报表页，
+不适合每次打开工作台。
+"""
+
+from datetime import date, datetime
+
+from sqlalchemy import exists, func, or_, select
+from sqlalchemy.orm import Session
+
+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`` 由调用方按当前用户角色解析（待我审批），空元组返回空列表。
+    """
+    if not statuses:
+        return []
+    return list(
+        session.execute(
+            select(ApprovalOrder)
+            .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]:
+    """提交后超过阈值仍未处理的审批单（审批超时规则）。"""
+    return list(
+        session.execute(
+            select(ApprovalOrder)
+            .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/performance_ledger_repository.py

@@ -16,7 +16,12 @@ def get_by_id(session: Session, ledger_id: int) -> PerformanceLedger | None:
 def get_active_by_receipt(
     session: Session, receipt_id: int, *, calc_type: int = 1
 ) -> PerformanceLedger | None:
-    """取某回款的当前生效核算行（is_active=1；无则 None）。"""
+    """取某回款的当前生效核算行（is_active=1；无则 None）。
+
+    二次分摊拆行后同回款可有多行（负责人+参与人）——重算作废用
+    ``list_active_by_receipt``；本函数仅限确知单行的调用方（重算前的
+    存在性判断按业务维度走 has_active_for_business）。
+    """
     return session.execute(
         select(PerformanceLedger).where(
             PerformanceLedger.receipt_id == receipt_id,
@@ -26,6 +31,21 @@ def get_active_by_receipt(
     ).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 (

backend/app/repositories/rating_repository.py

@@ -32,8 +32,9 @@ def list_all(session: Session, *, for_update: bool = False) -> list[CustomerRati
 def get_by_id(session: Session, grade_id: int) -> CustomerRatingGrade | None:
     """按主键查询。
 
-    等级表无下游引用（评级是纯计算器不落评分记录），无需 ``for_update``
+    等级表对客户评级无**外键**引用（评级行快照固化等级名），无需
-    锁行 —— product_repository 锁行防的是并发引用悬空，此处不存在该风险。
+    ``for_update`` 锁行 —— product_repository 锁行防的是并发引用悬空，
+    此处不存在该风险。
     """
     return session.get(CustomerRatingGrade, grade_id)
 
@@ -60,6 +61,6 @@ def create(session: Session, grade: CustomerRatingGrade) -> CustomerRatingGrade:
 
 
 def delete(session: Session, grade: CustomerRatingGrade) -> None:
-    """物理删除等级。等级表无下游引用，调用方无需引用保护校验。"""
+    """物理删除等级。等级表对客户评级无外键引用，调用方无需引用保护校验。"""
     session.delete(grade)
     session.flush()

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/schemas/customer.py

@@ -1,6 +1,7 @@
 """客户管理的请求/响应模型（需求 2.1.3）。"""
 
 from datetime import datetime
+from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -13,6 +14,10 @@ class CustomerOut(BaseModel):
     owner_personnel_name 由 LEFT JOIN 带出：归属人员不可考（被物理删除的
     脏数据）时为 null，owner_personnel_id 仍返回原值供追溯 —— 与归属留痕
     「ID 固化、姓名随联表」同一口径。
+
+    rating_total / rating_grade_name 由 LEFT JOIN customer_ratings 带出
+    （列表评级列免 N+1）：未评级时均为 null；总分按分值红线以字符串出参，
+    等级为保存时点的快照固化值（见 models/customer_rating.py）。
     """
 
     model_config = ConfigDict(from_attributes=True)
@@ -28,6 +33,8 @@ class CustomerOut(BaseModel):
     owner_personnel_id: int | None = None
     owner_personnel_name: str | None = None
     remark: str | None = None
+    rating_total: str | None = None
+    rating_grade_name: str | None = None
 
 
 class CustomerCreateIn(BaseModel):
@@ -97,6 +104,14 @@ class CustomerQuery(PageQuery):
     )
     customer_type: str | None = Field(default=None, max_length=32, description="客户分类筛选")
     owner_personnel_id: int | None = Field(default=None, ge=1, description="归属人员ID筛选")
+    # 排序白名单（全项目首个列表排序参数）：非法值由 Literal 拦下、经全局
+    # 异常处理器转 400 —— 不把排序字段透传给 SQL，避免注入面
+    order_field: Literal["rating"] | None = Field(
+        default=None, description="排序字段白名单：rating=客户评级总分（等级由总分判定、同向）"
+    )
+    order_type: Literal["asc", "desc"] | None = Field(
+        default=None, description="排序方向：asc 正序 / desc 倒序（未评级恒在末尾）"
+    )
 
 
 class CustomerOwnershipIn(BaseModel):

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/rating.py

@@ -77,3 +77,55 @@ class RatingGradeUpdateIn(RatingGradeCreateIn):
 
     前端表单全量提交，故为全量替换语义；等级表无启停状态列，字段与新增一致。
     """
+
+
+class CustomerRatingOut(BaseModel):
+    """客户评级响应（每客户一行；总分与分值按红线以字符串出参）。
+
+    grade_name 是保存时点按等级映射**快照固化**的值（无外键）：等级表后续
+    增删改不影响已保存的评级结论；为 NULL 表示保存时未命中任何等级
+    （总分低于全部下限或等级表被清空）。
+    """
+
+    customer_id: int
+    score_ship_amount: str
+    score_receipt_rate: str
+    score_profit_rate: str
+    score_contract_cooperation: str
+    score_site_construction: str
+    total_score: str
+    grade_name: str | None = None
+    remark: str | None = None
+    scorer_name: str
+    create_time: datetime
+    update_time: datetime
+
+
+class CustomerRatingSaveIn(BaseModel):
+    """保存客户评级（每客户一行，整体替换语义）。
+
+    五项分值为 0-20 的数字字符串（schema 只拦格式；0≤分≤20 与总分等级
+    判定在 service 层审计上下文内完成 —— 失败的 400 同样留痕）。总分由
+    服务端按五项重算，**不采信前端回传的总分**。
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    score_ship_amount: str = Field(description="发货额评分（0-20 数字字符串）")
+    score_receipt_rate: str = Field(description="回款率评分（0-20 数字字符串）")
+    score_profit_rate: str = Field(description="毛利率评分（0-20 数字字符串）")
+    score_contract_cooperation: str = Field(description="合同履约配合能力评分（0-20 数字字符串）")
+    score_site_construction: str = Field(description="现场规范施工能力评分（0-20 数字字符串）")
+    remark: str | None = Field(default=None, max_length=255, description="备注")
+
+    @field_validator(
+        "score_ship_amount",
+        "score_receipt_rate",
+        "score_profit_rate",
+        "score_contract_cooperation",
+        "score_site_construction",
+    )
+    @classmethod
+    def _check_score(cls, value: str) -> str:
+        """单项分值须为有限数字（值域 0-20 由 service 层判定）。"""
+        return _parse_score(value, label="评分")

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

@@ -1,34 +1,59 @@
-"""系统设置（公司信息）请求/响应模型。
+"""系统设置（公司信息 + 站点信息）请求/响应模型。
 
 `SettingPublicOut` 与 `SettingOut` **刻意不共用**：public 端点无鉴权，
 响应字段必须白名单显式列出——将来往 SettingOut 加敏感字段时不会
 顺着复用链泄漏到匿名端点。
+
+2026-10-20 精简（用户确认）：删除系统副标题与企业档案字段（信用代码/
+地址/电话/邮箱）；新增站点标题（浏览器标签页/侧边栏副标题）与站点图标
+（浏览器标签页 favicon）。public 端点只需登录页/标签页展示字段，两者
+恰好同集合，但仍保留独立 schema 作为白名单防线。
 """
 
 from pydantic import BaseModel, ConfigDict, Field
 
 
 class SettingOut(BaseModel):
-    """公司信息（管理端）。"""
+    """公司信息与站点信息（管理端）。"""
 
     company_name: str
     logo_url: str | None = None
+    site_title: str | None = None
+    brand_slogan: str | None = None
+    footer_text: str | None = None
+    icp_no: str | None = None
+    favicon_url: str | None = None
 
 
 class SettingPublicOut(BaseModel):
-    """公司信息（匿名端点白名单）：登录页展示所需的两个字段。"""
+    """公司信息与站点信息（匿名端点白名单）：登录页/浏览器标签页展示所需字段。"""
 
     company_name: str
     logo_url: str | None = None
+    site_title: str | None = None
+    brand_slogan: str | None = None
+    footer_text: str | None = None
+    icp_no: str | None = None
+    favicon_url: str | None = None
 
 
 class SettingUpdateIn(BaseModel):
-    """公司信息更新。
+    """公司信息与站点信息更新（**部分更新**语义）。
 
     str_strip_whitespace：全空白名称先剥再校验——否则 `"   "` 过 min_length=1
     后由服务层 strip 成空串入库（200 成功但 public 端点返回空公司名）。
+
+    仅提交的字段生效（``exclude_unset``），未提交或显式 null 的字段保持
+    不变；可选文本传空串等价清空（落库为 null、前端回退内置默认）。
+    company_name 若提交必须非空（DB 非空约束）。
     """
 
     model_config = ConfigDict(str_strip_whitespace=True)
 
-    company_name: str = Field(min_length=1, max_length=64, description="公司名称")
+    company_name: str | None = Field(
+        default=None, min_length=1, max_length=64, description="公司名称（提交则须非空）"
+    )
+    site_title: str | None = Field(default=None, max_length=64, description="站点标题")
+    brand_slogan: str | None = Field(default=None, max_length=64, description="品牌标语")
+    footer_text: str | None = Field(default=None, max_length=64, description="页脚版权文本")
+    icp_no: str | None = Field(default=None, max_length=32, description="ICP 备案号")

backend/app/schemas/settlement.py

@@ -1,21 +1,17 @@
 """月度结算的请求/响应模型（M3 ④）。"""
 
-import re
 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
 
-_MONTH_RE = re.compile(r"^\d{4}-\d{2}$")
-
 
 def _check_month(value: str) -> str:
-    """月份格式 YYYY-MM（settlement_month 全表唯一的维度）。"""
+    """月份格式 YYYY-MM 且月份 01-12（settlement_month 全表唯一的维度）。"""
-    if not _MONTH_RE.match(value):
+    return validate_month(value)
-        raise ValueError("月份格式须为 YYYY-MM")
-    return value
 
 
 class SettlementGenerateIn(BaseModel):
@@ -93,3 +89,8 @@ class AdjustmentCreateIn(BaseModel):
         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

@@ -19,6 +19,7 @@
 """
 
 import logging
+from collections.abc import Iterable
 from datetime import date
 
 from sqlalchemy import func, select
@@ -29,6 +30,7 @@ from app.core.constants import (
     ACTION_REJECT,
     MODULE_APPROVAL,
     NO_PREFIX_APPROVAL,
+    ROLE_ADMIN,
     ROLE_FINANCE,
     ROLE_LEADER,
 )
@@ -84,6 +86,18 @@ _NODE_ROLE_BY_STATUS = {
 _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)

backend/app/services/business_service.py

@@ -298,8 +298,24 @@ def _build_allocation_rows(
         编辑业务（哪怕只改备注）不应被历史参与人的离职状态卡死；仅对
         **新加入**的参与人做在职校验。
 
-    :raises BadRequestError: 新增参与人员不存在或已离职
+    :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:
@@ -320,7 +336,7 @@ def _build_allocation_rows(
 
 
 def _allocation_hint(allocations: list[SecondaryAllocation]) -> str | None:
-    """方案合计/余额提示（不强制合计满额是需求原文；余额归属待澄清 #2）。
+    """方案合计/余额提示（不要求合计满额是需求原文；余额归属 = 澄清 #2 答复）。
 
     无方案返回 None；合计恰满额只报合计，避免「余额 0」噪音。
     """
@@ -331,7 +347,7 @@ def _allocation_hint(allocations: list[SecondaryAllocation]) -> str | None:
     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}%（归属待业务确认）"
+    return f"二次分配合计 {total_text}%，余额 {rest}%（归合同负责营销人员）"
 
 
 def create_business(

backend/app/services/calc_service.py

@@ -6,9 +6,13 @@
 按行汇总，对照表 #14）。两者的任何口径修改必须同步——预览给业务对数、
 核算才是算钱的法定固化点。
 
-策略点（待业务答复，全部集中为单函数，答复后只改函数 + 按回款批量重算）：
+策略点（业务答复 2026-10-19 已回填，后续调整仍集中在对应函数 + 按回款批量重算）：
-- ``_personal_rate``：#12 经理个人户单笔落台账 rate=0/绩效 0（12.5%+5%
+- ``_personal_rate``：#12 经理个人户单笔由参数 manager.personal.included
-  聚合口径在月结时由 manager_team_share 计算）；#20 在 ``_row_profit``
+  分流——0=单笔落 0（聚合口径在月结时由 manager_team_share 计算）、
+  1=按业务员递减公式计提；#20 在 ``_row_profit``（暂按不含税原样相减）
+- 二次分摊（澄清 #1 答复「分配绩效」，算后分）：``_load_allocations``
+  读生效方案，``_persist_ledger`` 按比例拆行（参与人份额 + 负责人余额，
+  行合计守恒）；#2 余额归负责人、#3 二次分配即协助场景的核算载体
 - 核算粒度 #25：业务级一次性计提——首个触发核算的回款计算全额应发，
   后续回款仅置 settlement_status=1（repeated=True），不重复计提
 """
@@ -29,6 +33,7 @@ from app.models import (
     BusinessItem,
     Customer,
     PerformanceLedger,
+    Personnel,
     Receipt,
     Shipment,
     User,
@@ -54,8 +59,8 @@ from app.services.param_service import parse_fraction, resolve_snapshot
 
 logger = logging.getLogger(__name__)
 
-# snapshot_json 里的策略点注记（答复回填时的检索锚点）
+# snapshot_json 里的策略点注记（口径检索锚点；#12 已参数化，开关 0 时留此注记）
-_NOTE_MANAGER_PENDING = "经理个人户单笔不计提（#12 待答复）：聚合口径在月结时由团队聚合计算"
+_NOTE_MANAGER_PENDING = "经理个人户单笔不计提（基数开关=0）：聚合口径在月结时由团队聚合计算"
 
 
 @dataclass(frozen=True, slots=True)
@@ -115,31 +120,34 @@ def calc_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
         )
-        row = _persist_ledger(
+        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(row), repeated=False)
+        out = CalcReceiptOut(ledger=_to_out(rows.owner_row), repeated=False)
         session.commit()
         logger.info(
-            "核算完成 | receipt=%s | ledger=%s | payable=%s",
+            "核算完成 | receipt=%s | ledger=%s | payable=%s | 分摊行=%s",
             receipt_id,
-            row.id,
+            rows.owner_row.id,
             amounts.payable,
+            len(rows.share_rows),
         )
         return out
 
@@ -184,10 +192,12 @@ def _prepare_mode(
     # 以后）——本无独立计提，继续重算会凭空落一行生效行，同业务出现
     # 两行生效行导致双重计提 → 一律 400
     if is_recalc:
-        old = performance_ledger_repository.get_active_by_receipt(session, receipt.id)
+        # 分摊拆行后旧版本可能多行（负责人+参与人）——全部作废再落新版本
-        if old is None:
+        olds = performance_ledger_repository.list_active_by_receipt(session, receipt.id)
+        if not olds:
             raise BadRequestError("该回款为进度登记（业务已按一次性计提核算），无独立台账行可重算")
-        performance_ledger_repository.mark_inactive(session, old)
+        for old in olds:
+            performance_ledger_repository.mark_inactive(session, old)
         return None
 
     # 核算粒度 #25（一期口径，仅首算模式）：业务级一次性计提——已有生效
@@ -231,6 +241,27 @@ def _load_items(session: Session, business: Business) -> list[BusinessItem]:
     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:
     """逐行折算结果（行级明细入台账快照，汇总值驱动计提与起付判定）。"""
@@ -347,6 +378,14 @@ def _compose_amounts(
     )
 
 
+@dataclass(frozen=True, slots=True)
+class _LedgerRows:
+    """拆行落库结果：负责人行恒存在（出参与 CAS 锚点），参与人份额行可空。"""
+
+    owner_row: PerformanceLedger
+    share_rows: list[PerformanceLedger]
+
+
 def _persist_ledger(
     session: Session,
     *,
@@ -355,14 +394,23 @@ def _persist_ledger(
     person,
     shipment: Shipment,
     items: list[BusinessItem],
+    allocations: list,
     conversion: _Conversion,
     amounts: _Amounts,
     recalc_reason: str | None,
     is_recalc: bool,
-) -> PerformanceLedger:
+) -> _LedgerRows:
-    """落台账行（版本号自增；金额两位 HALF_UP）+ 首算 CAS 置已核算。"""
+    """落台账行（分摊拆行；版本号自增；金额两位 HALF_UP）+ 首算 CAS 置已核算。
+
+    分摊（澄清 #1 答复 2026-10-19「分配绩效」，算后分）：业务级全额（含
+    递减比例、抵顶、支付权重全环节）算完后按方案比例拆给参与人，余额归
+    合同负责人。行合计与业务级全额**守恒**（负责人行取 q2 全额减参与人
+    q2 份额的差额，防分漂）；每行快照带完整方案快照，行级可独立回溯。
+    参与人离职照分（历史方案事实，方案调整是业务侧责任——入职校验只在
+    保存侧，核算侧只要求人员存在，FK RESTRICT 已保证）。
+    """
     receipt_date = receipt.receipt_date
-    snapshot_json: dict[str, Any] = {
+    base_snapshot: dict[str, Any] = {
         "params_as_of": str(receipt_date),
         "line_details": conversion.line_details,
         "start_payment_ok": amounts.start_ok,
@@ -371,43 +419,100 @@ def _persist_ledger(
         "profit_total": str(conversion.total_profit),
     }
     if amounts.decision.manager_pending:
-        snapshot_json["strategy_note"] = _NOTE_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)
 
-    row = performance_ledger_repository.add(
-        session,
-        PerformanceLedger(
-            receipt_id=receipt.id,
-            calc_version=performance_ledger_repository.next_version(session, receipt.id),
-            calc_type=CALC_TYPE_RECEIPT,
-            business_id=business.id,
-            business_no=business.business_no,
-            personnel_id=person.id,
-            personnel_name=person.personnel_name,
-            role_code=role_code_of(person),
-            customer_type=_customer_type(session, business),
-            product_category=_category_label(items),
-            ship_date=shipment.ship_date,
-            receipt_date=receipt_date,
-            payment_days=amounts.days,
-            rate_text=str(amounts.decision.rate),
-            converted_profit=_q2(amounts.converted),
-            performance_amount=_q2(amounts.performance),
-            barter_applied=1 if amounts.barter_applied else 0,
-            weight_r=amounts.weight_r,
-            payment_weight=param_service.to_decimal(amounts.weight),
-            payable_amount=_q2(amounts.payable),
-            settlement_month=receipt_date.strftime("%Y-%m"),
-            is_probation=1 if person.is_probation == 1 else 0,
-            missing_cost=1 if conversion.missing_cost else 0,
-            snapshot_json=snapshot_json,
-            calc_reason=recalc_reason,
-        ),
-    )
     # CAS 仅首算执行：重算模式状态本就是已核算（UPDATE ... WHERE status=0
     # 会 rowcount=0 误报并发撞车）
     if not is_recalc:
         _mark_settled(session, receipt)
-    return row
+    return _LedgerRows(owner_row=owner_row, share_rows=share_rows)
 
 
 def _q2(value: Decimal | None) -> Decimal | None:
@@ -443,12 +548,23 @@ def _personal_rate(
 
     template = role.calc_template if role else "TPL_SALESPERSON_DECAY"
     if template == "TPL_MANAGER_SHARE":
-        return _RateDecision(
+        # #12 答复（2026-10-19）参数化：manager.personal.included=1 时个人户
-            Decimal("0"),
+        # 单按业务员递减公式单笔计提（个人户单本质是正常业务，有发货/回款/
-            "经理个人户：12.5%+5% 聚合计提（月结时计算），单笔落 0",
+        # 毛利；聚合基数开关在 settlement_service 同参数消费）——0 时单笔落 0
-            None,
+        if snapshot.get("manager.personal.included") != "1":
-            True,
+            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

backend/app/services/customer_service.py

@@ -31,7 +31,7 @@ from app.core.exceptions import BadRequestError, NotFoundError
 from app.core.response import PageQuery, PageResult
 from app.models import Customer, OwnershipChangeLog, Personnel, User
 from app.models.customer import OWNER_TYPE_CUSTOMER
-from app.repositories import customer_repository, personnel_repository
+from app.repositories import customer_rating_repository, customer_repository, personnel_repository
 from app.schemas.customer import (
     CustomerCreateIn,
     CustomerOut,
@@ -46,8 +46,17 @@ from app.services.audit_service import AuditRecord, RequestMeta
 logger = logging.getLogger(__name__)
 
 
-def _to_out(customer: Customer, owner_name: str | None) -> CustomerOut:
+def _to_out(
-    """ORM 对象转响应模型。禁止把 ORM 对象直接当 response_model。"""
+    customer: Customer,
+    owner_name: str | None,
+    rating_total: object | None = None,
+    rating_grade: str | None = None,
+) -> CustomerOut:
+    """ORM 对象转响应模型。禁止把 ORM 对象直接当 response_model。
+
+    rating_total 由 LEFT JOIN 带出（Decimal 或 None），按分值红线转字符串
+    出参；新建客户/未评级客户不传，保持 null。
+    """
     return CustomerOut(
         id=customer.id,
         company_name=customer.company_name,
@@ -60,6 +69,8 @@ def _to_out(customer: Customer, owner_name: str | None) -> CustomerOut:
         owner_personnel_id=customer.owner_personnel_id,
         owner_personnel_name=owner_name,
         remark=customer.remark,
+        rating_total=str(rating_total) if rating_total is not None else None,
+        rating_grade_name=rating_grade,
     )
 
 
@@ -106,7 +117,7 @@ def _is_duplicate_entry(exc: IntegrityError) -> bool:
 
 
 def list_customers(session: Session, query: CustomerQuery) -> PageResult[CustomerOut]:
-    """分页查询客户（附归属人员姓名）。"""
+    """分页查询客户（附归属人员姓名与评级快照；支持评级列排序）。"""
     rows = customer_repository.list_customers(
         session,
         offset=query.offset,
@@ -114,6 +125,8 @@ def list_customers(session: Session, query: CustomerQuery) -> PageResult[Custome
         keyword=query.keyword,
         customer_type=query.customer_type,
         owner_personnel_id=query.owner_personnel_id,
+        order_field=query.order_field,
+        order_type=query.order_type,
     )
     total = customer_repository.count_customers(
         session,
@@ -121,8 +134,12 @@ def list_customers(session: Session, query: CustomerQuery) -> PageResult[Custome
         customer_type=query.customer_type,
         owner_personnel_id=query.owner_personnel_id,
     )
+    records = [
+        _to_out(customer, owner_name, rating_total, rating_grade)
+        for customer, owner_name, rating_total, rating_grade in rows
+    ]
     return PageResult[CustomerOut](
-        records=[_to_out(customer, owner_name) for customer, owner_name in rows],
+        records=records,
         total=total,
         page_num=query.page_num,
         page_size=query.page_size,
@@ -137,8 +154,8 @@ def get_customer(session: Session, customer_id: int) -> CustomerOut:
     row = customer_repository.get_with_owner_name(session, customer_id)
     if row is None:
         raise NotFoundError("客户不存在")
-    customer, owner_name = row
+    customer, owner_name, rating_total, rating_grade = row
-    return _to_out(customer, owner_name)
+    return _to_out(customer, owner_name, rating_total, rating_grade)
 
 
 def create_customer(
@@ -241,7 +258,7 @@ def update_customer(
         _ensure_customer_type(payload.customer_type)
         if row is None:
             raise NotFoundError("客户不存在")
-        customer, owner_name = row
+        customer, owner_name, rating_total, rating_grade = row
 
         duplicate = customer_repository.get_by_company_owner(
             session, payload.company_name, payload.owner_name
@@ -260,7 +277,7 @@ def update_customer(
 
         try:
             # 响应在 commit 之前构造（同 user_service 顶部说明）
-            out = _to_out(customer, owner_name)
+            out = _to_out(customer, owner_name, rating_total, rating_grade)
             session.commit()
         except IntegrityError as exc:
             # 把自身以外的组合改成已存在的「公司名称+负责人」时，先查后写
@@ -308,6 +325,11 @@ def delete_customer(
 
         company_name = customer.company_name  # 固化：对象随删除失效
         try:
+            # 评级行 FK RESTRICT：先删评级行再删客户主行（同事务一次 commit；
+            # 评级是附属快照，不构成「有关联业务」的删除阻碍）
+            rating = customer_rating_repository.get_by_customer_id(session, customer_id)
+            if rating is not None:
+                customer_rating_repository.delete(session, rating)
             customer_repository.delete(session, customer)
             session.commit()
         except IntegrityError as exc:
@@ -362,7 +384,7 @@ def change_ownership(
     ):
         if row is None:
             raise NotFoundError("客户不存在")
-        customer, _ = row
+        customer, _, rating_total, rating_grade = row
 
         if payload.new_owner_personnel_id is not None:
             _ensure_owner_personnel(session, payload.new_owner_personnel_id)
@@ -385,7 +407,12 @@ def change_ownership(
             ),
         )
         # 响应在 commit 之前构造（同 user_service 顶部说明）；归属人名以新值为准
-        out = _to_out(customer, new_person.personnel_name if new_person else None)
+        out = _to_out(
+            customer,
+            new_person.personnel_name if new_person else None,
+            rating_total,
+            rating_grade,
+        )
         session.commit()
         logger.info(
             "调整客户归属 | customer_id=%s | old=%s | new=%s",

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/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/param_registry.py

@@ -314,6 +314,54 @@ PARAM_REGISTRY: dict[str, ParamSpec] = {
             ),
             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/rating_service.py

@@ -1,12 +1,14 @@
-"""客户评级等级配置业务编排。
+"""客户评级业务编排（等级映射配置 + 每客户评级落库）。
 
-评级计算器定位（对照表 #25）：仅打分工具、不影响绩效金额，评分记录不落库
+评级定位（对照表 #25）：**不影响绩效金额**。自 2026-10-19 起评分每客户
-——本表承载的等级映射是**判定表**，判定规则为按 sort_order 升序取首个
+落库（customer_ratings，一行一客户快照），等级映射仍是本服务承载的
-min_score ≤ 总分的等级，max_score 仅展示。两条硬约束（违反会算错等级）：
+**判定表**，判定规则为按 sort_order 升序取首个 min_score ≤ 总分的等级，
+max_score 仅展示。两条硬约束（违反会算错等级）：
 
 - 分值全程 ``Decimal``：入参出参 str、schema 拦格式，service 层负责字符串
-  到 Decimal 的转换与落库；0≤min≤max≤100 的区间校验在**审计上下文内**
+  到 Decimal 的转换与落库；值域校验（等级区间 0≤min≤max≤100、单项评分
-  完成，失败的 400 同样留痕（2026-10-13 定稿口径）
+  0≤分≤20）在**审计上下文内**完成，失败的 400 同样留痕（2026-10-13 定稿
+  口径）
 - 区间互不重叠：重叠会让同一总分命中多个等级（或两段都跳过），判定表
   失效。判定为**闭区间两两相交**：任一其他等级满足
   ``other.min_score <= 新 max 且 新 min <= other.max_score`` 即重叠。
@@ -14,9 +16,9 @@ min_score ≤ 总分的等级，max_score 仅展示。两条硬约束（违反
   相邻铺满 0-100，且判定本身是单边 min_score ≤ 总分，边界归 sort_order
   靠前的等级，相邻无歧义
 
-删除允许清空：等级表无下游引用（评分记录不落库，判定只读本表现值、不
+删除允许清空：等级表对客户评级**无外键引用**（评级快照固化等级名、不
-回溯历史快照），物理删除无悬空风险；全部删空后计算器只显示总分、不出
+回指本表），物理删除无悬空风险，也不伤及已评级客户的历史结论；全部删空
-等级（前端已对应提示），故不强制保留任何一条。
+后新评级只记总分、等级为 NULL（前端已对应提示），故不强制保留任何一条。
 """
 
 import logging
@@ -33,9 +35,15 @@ from app.core.constants import (
 )
 from app.core.db_errors import is_duplicate_entry
 from app.core.exceptions import BadRequestError, NotFoundError
-from app.models import CustomerRatingGrade, User
+from app.models import CustomerRating, CustomerRatingGrade, User
-from app.repositories import rating_repository
+from app.repositories import customer_rating_repository, customer_repository, rating_repository
-from app.schemas.rating import RatingGradeCreateIn, RatingGradeOut, RatingGradeUpdateIn
+from app.schemas.rating import (
+    CustomerRatingOut,
+    CustomerRatingSaveIn,
+    RatingGradeCreateIn,
+    RatingGradeOut,
+    RatingGradeUpdateIn,
+)
 from app.services import audit_service
 from app.services.audit_service import AuditRecord, RequestMeta
 
@@ -44,6 +52,8 @@ logger = logging.getLogger(__name__)
 # 分值域上下界（Decimal 常量，禁用 float 参与比较）
 _SCORE_FLOOR = Decimal("0")
 _SCORE_CEIL = Decimal("100")
+# 单项评分上界（五项各 0-20，总分 0-100）
+_ITEM_SCORE_CEIL = Decimal("20")
 
 
 def _to_out(grade: CustomerRatingGrade) -> RatingGradeOut:
@@ -252,10 +262,11 @@ def delete_grade(
 ) -> None:
     """物理删除评级等级。
 
-    等级表无下游引用 —— 评级是纯计算器不落评分记录（对照表 #25），判定
+    等级表对客户评级**无外键引用** —— 评级行快照固化等级名（见
-    只读本表现值、不回溯历史快照，故可物理删除且无需锁行防并发引用。
+    ``models/customer_rating.py`` 的论证），判定只读本表现值，故可物理删除
+    且无需锁行防并发引用；删除等级不改变已评级客户的历史结论。
 
-    **允许清空**：全部删空后计算器只显示总分、不出等级（前端已对应提示），
+    **允许清空**：全部删空后新评级只记总分、等级为 NULL（前端已对应提示），
     不强制保留任何一条。
 
     :raises NotFoundError: 评级等级不存在
@@ -278,3 +289,164 @@ def delete_grade(
         rating_repository.delete(session, grade)
         session.commit()
         logger.info("删除评级等级 | grade_name=%s", grade_name)
+
+
+# ==================== 客户评级（每客户一行，落库） ====================
+
+
+def resolve_grade(
+    grades: list[CustomerRatingGrade], total_score: Decimal
+) -> CustomerRatingGrade | None:
+    """等级判定纯函数：按 sort_order 升序取首个 min_score ≤ 总分的等级。
+
+    与前端打分卡的实时判定同规则同序（前端按数值比较，此处 Decimal 比较
+    ——同一规则的两端实现，测试锁定边界行为一致）。无命中（总分低于全部
+    下限或等级表为空）返回 None，由调用方决定展示与落库（快照记 NULL）。
+    """
+    # id 兜底让同序等级次序稳定（纯函数也接受未持久化对象：id 可能为 None）
+    for grade in sorted(grades, key=lambda g: (g.sort_order, g.id or 0)):
+        if grade.min_score <= total_score:
+            return grade
+    return None
+
+
+def _to_rating_out(rating: CustomerRating) -> CustomerRatingOut:
+    """客户评级行转响应模型。分值 Decimal → str（分值红线出参口径）。"""
+    return CustomerRatingOut(
+        customer_id=rating.customer_id,
+        score_ship_amount=str(rating.score_ship_amount),
+        score_receipt_rate=str(rating.score_receipt_rate),
+        score_profit_rate=str(rating.score_profit_rate),
+        score_contract_cooperation=str(rating.score_contract_cooperation),
+        score_site_construction=str(rating.score_site_construction),
+        total_score=str(rating.total_score),
+        grade_name=rating.grade_name,
+        remark=rating.remark,
+        scorer_name=rating.scorer_name,
+        create_time=rating.create_time,
+        update_time=rating.update_time,
+    )
+
+
+def _ensure_item_scores(scores: list[Decimal]) -> None:
+    """单项评分值域：0 ≤ 分 ≤ 20（总分由五项求和自然落在 0-100）。
+
+    须在审计上下文内调用，失败也要留痕（同 _ensure_score_range 口径）。
+    """
+    for score in scores:
+        if not (_SCORE_FLOOR <= score <= _ITEM_SCORE_CEIL):
+            raise BadRequestError("单项评分须在 0~20 之间")
+
+
+def get_customer_rating(session: Session, customer_id: int) -> CustomerRatingOut | None:
+    """查某客户当前评级；未评级返回 None（接口信封 data 为 null）。
+
+    「未评级」是正常态而非错误，不用 404 表达；客户不存在才是 NotFound。
+
+    :raises NotFoundError: 客户不存在
+    """
+    customer = customer_repository.get_by_id(session, customer_id)
+    if customer is None:
+        raise NotFoundError("客户不存在")
+    rating = customer_rating_repository.get_by_customer_id(session, customer_id)
+    return _to_rating_out(rating) if rating is not None else None
+
+
+def save_customer_rating(
+    session: Session,
+    customer_id: int,
+    payload: CustomerRatingSaveIn,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+) -> CustomerRatingOut:
+    """保存客户评级（upsert：首次创建，再次保存整体覆盖）。
+
+    总分与等级**服务端重算**：总分按五项求和（不采信前端回传），等级按
+    保存时点的等级映射判定后**快照固化**进评级行 —— 等级表后续增删改
+    不影响该行（见 ``models/customer_rating.py``）。
+
+    :raises NotFoundError: 客户不存在
+    :raises BadRequestError: 单项评分须在 0~20 之间（审计上下文内校验，留痕）
+    """
+    # 只读预取在审计上下文之前：客户不存在（NotFound 失败）也能留下可读记录，
+    # 摘要需要客户名
+    customer = customer_repository.get_by_id(session, customer_id)
+    existing = customer_rating_repository.get_by_customer_id(session, customer_id)
+    with audit_service.audit(
+        session,
+        operator=operator,
+        record=AuditRecord(
+            module=MODULE_RATING,
+            action=ACTION_CREATE if existing is None else ACTION_UPDATE,
+            summary=f"评定客户「{customer.company_name if customer else f'#{customer_id}'}」评级",
+            request_data=payload.model_dump(exclude_none=True),
+        ),
+        meta=meta,
+    ):
+        # 值域校验在审计上下文内：分值非法的 400 也要留痕（同等级配置口径）
+        item_scores = [
+            _to_decimal(payload.score_ship_amount),
+            _to_decimal(payload.score_receipt_rate),
+            _to_decimal(payload.score_profit_rate),
+            _to_decimal(payload.score_contract_cooperation),
+            _to_decimal(payload.score_site_construction),
+        ]
+        _ensure_item_scores(item_scores)
+        if customer is None:
+            raise NotFoundError("客户不存在")
+
+        total_score = sum(item_scores, _SCORE_FLOOR)
+        grade = resolve_grade(rating_repository.list_all(session), total_score)
+
+        def _apply(row: CustomerRating) -> None:
+            """把五项分值/总分/等级快照写入评级行（创建与并发兜底共用）。"""
+            (
+                row.score_ship_amount,
+                row.score_receipt_rate,
+                row.score_profit_rate,
+                row.score_contract_cooperation,
+                row.score_site_construction,
+            ) = item_scores
+            row.total_score = total_score
+            row.grade_name = grade.grade_name if grade is not None else None
+            row.remark = payload.remark
+            row.scorer_id = operator.id
+            row.scorer_name = operator.username
+
+        try:
+            if existing is None:
+                rating = CustomerRating(
+                    customer_id=customer_id,
+                    scorer_id=operator.id,
+                    scorer_name=operator.username,
+                )
+                _apply(rating)
+                customer_rating_repository.create(session, rating)
+            else:
+                _apply(existing)
+                rating = existing
+            out = _to_rating_out(rating)
+            session.commit()
+        except IntegrityError as exc:
+            # 先查后写不是原子操作：并发为同一客户首次评级会撞
+            # uk_customer_ratings_customer_id，回滚后转为更新兜底
+            session.rollback()
+            if not is_duplicate_entry(exc):
+                raise
+            raced = customer_rating_repository.get_by_customer_id(session, customer_id)
+            if raced is None:
+                # 1062 但行不在：数据态异常，交全局 IntegrityError 兜底
+                raise
+            _apply(raced)
+            rating = raced
+            out = _to_rating_out(rating)
+            session.commit()
+
+        logger.info(
+            "保存客户评级 | customer_id=%s | total=%s | grade=%s",
+            customer_id,
+            out.total_score,
+            out.grade_name,
+        )
+        return out

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/settlement_service.py

@@ -9,11 +9,8 @@
 """
 
 import logging
-from calendar import monthrange
-from dataclasses import dataclass
 from datetime import date
 from decimal import ROUND_HALF_UP, Decimal
-from fractions import Fraction
 
 from sqlalchemy import select
 from sqlalchemy.orm import Session
@@ -45,7 +42,7 @@ from app.schemas.settlement import (
     SettlementOut,
     SettlementQuery,
 )
-from app.services import approval_service, audit_service
+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
 
@@ -352,82 +349,28 @@ def _confirm_scope(session: Session, month: str) -> list:
     )
 
 
-@dataclass(frozen=True, slots=True)
+def _manager_share_params(session: Session, month: str) -> manager_share.ManagerShareParams:
-class _ShareParams:
+    """薄委托 manager_share 共享模块：月结聚合与报表部门汇总同源取参。
-    """经理分成取参与参数原文（同一次生成共用一份，随月月末时点化）。"""
 
-    month: str
+    迁移说明（2026-10-19）：实现原样迁至 manager_share，行为零变化；
-    param_date: date
+    参数按百分数存储（12.5 表示 12.5%），调用方不得再乘 100。
-    team_text: str
-    company_text: str
-    team_pct: Fraction
-    company_pct: Fraction
-    include_manager_personal: bool
-
-
-def _manager_share_params(session: Session, month: str) -> _ShareParams:
-    """解析经理分成参数（锚定所属月月末，取参与台账行口径同源）。
-
-    参数按百分数存储（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
+    return manager_share.manager_share_params(session, month)
-
-    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 _ShareParams(
-        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_share 共享模块：按经理采集团队业绩（行为零变化）。"""
-
+    return manager_share.collect_team_buckets(session, ledger_rows, include_manager_personal)
-    业务员行经 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 _aggregate_row(
-    session: Session, manager, bucket: dict, company_base: Decimal, share: _ShareParams
+    session: Session,
+    manager,
+    bucket: dict,
+    company_base: Decimal,
+    share: manager_share.ManagerShareParams,
 ):
     """单经理聚合台账行（必须落库：月结 ledger_ids 与报表下钻的锚点）。"""
     from app.models import PerformanceLedger
@@ -487,16 +430,8 @@ def _build_manager_aggregates(session: Session, ledger_rows: list, month: str) -
 
     share = _manager_share_params(session, month)
     managers = _collect_team_buckets(session, ledger_rows, share.include_manager_personal)
-    # 全公司基数：默认排除经理个人户行（#12 开关计入时不过滤）；
+    # 全公司基数：默认排除经理个人户行（#12 开关计入时不过滤）；共享口径单点
-    # 口径逐行固定，循环外算一次
+    company_base = manager_share.company_base_of(ledger_rows, share.include_manager_personal)
-    company_base = sum(
-        (
-            r.performance_amount or Decimal("0")
-            for r in ledger_rows
-            if share.include_manager_personal or r.customer_type != "manager_personal"
-        ),
-        Decimal("0"),
-    )
     aggregates: list = []
     for manager_id, bucket in managers.items():
         manager = session.get(Personnel, manager_id)
@@ -514,15 +449,12 @@ def _build_manager_aggregates(session: Session, ledger_rows: list, month: str) -
 
 
 def _month_end(month: str) -> date:
-    """YYYY-MM → 所属月月末（月结取参锚点）。
+    """薄委托 manager_share 共享模块：YYYY-MM → 所属月月末（取参锚点）。
 
-    月结是对过去某月的金额计算，取参必须锚定业务月份——按 date.today()
+    保留包装：tests/unit/test_settlement_helpers.py 直接 import 本名字；
-    会让补生成历史月份的结果随操作日期漂移（违背「参数按生效日期时点化」
+    「补生成历史月份结果不随操作日漂移」的原因说明见 manager_share.month_end。
-    红线）。单笔台账行按回款日取参（裁决 #11）；聚合与月工资口径没有
-    更细的业务日期，取该月最后可确定的生效时点。
     """
-    year, mon = int(month[:4]), int(month[5:7])
+    return manager_share.month_end(month)
-    return date(year, mon, monthrange(year, mon)[1])
 
 
 def _salary_mode_of(session: Session, role_code: str, month: str) -> str | None:

backend/app/services/system_setting_service.py

@@ -1,12 +1,17 @@
-"""系统设置（公司信息）业务编排。
+"""系统设置（公司信息 + 站点信息）业务编排。
 
-单例行语义：整个系统恒一行（id=1，迁移种子保底）。logo 只存**相对路径**
+单例行语义：整个系统恒一行（id=1，迁移种子保底）。logo/favicon 只存**相对
-（uploads/logo/ 下固定名覆盖），文件不入库的理由：图片进数据库会让每次
+路径**（uploads/logo、uploads/favicon 下固定名覆盖），文件不入库的理由：
-读取与备份放大传输，且无法独立替换；DB 只持有一行指针。
+图片进数据库会让每次读取与备份放大传输，且无法独立替换；DB 只持有指针。
 
-logo 安全：后缀白名单 + magic bytes 双重校验（上传内容不可信，仅看文件名
+图像安全：后缀白名单 + magic bytes 双重校验（上传内容不可信，仅看文件名
 后缀可被伪造）；固定文件名落盘，**不使用上传方文件名**——杜绝路径拼接与
 覆盖任意文件。
+
+logo 与 favicon 相互独立（2026-10-20）：
+- logo 用于登录页品牌位；
+- favicon 用于浏览器标签页图标，未上传时前端使用内置 favicon.svg
+  （不再跟随 logo——公司 logo 是横版，作标签页图标常被裁切）。
 """
 
 import logging
@@ -24,15 +29,26 @@ from app.services.audit_service import AuditRecord, RequestMeta
 
 logger = logging.getLogger(__name__)
 
-# magic bytes：PNG 固定 8 字节签名；JPEG 以 SOI + APP0/JFIF 起始
+# magic bytes：PNG 8 字节签名；JPEG 以 SOI 起始；ICO 以 00 00 01 00 起始
 _MAGIC = {
     "png": b"\x89PNG\r\n\x1a\n",
     "jpg": b"\xff\xd8\xff",
+    "ico": b"\x00\x00\x01\x00",
 }
-LOGO_MAX_BYTES = 2 * 1024 * 1024  # 2MB：页眉/登录页展示尺寸上限，防上传滥用
+# 允许的后缀集合：logo 沿用 png/jpg（页眉/登录页展示）；favicon 额外接受 ico
+LOGO_EXTS = ("png", "jpg")
+FAVICON_EXTS = ("png", "jpg", "ico")
+ASSET_MAX_BYTES = 2 * 1024 * 1024  # 2MB：展示尺寸上限，防上传滥用
 
 SETTINGS_ID = 1  # 全系统单行主键
 
+# 公司档案中的可选文本字段：提交空串等价清空（落库 null，前端回退内置默认）
+_OPTIONAL_TEXT_FIELDS = ("site_title", "brand_slogan", "footer_text", "icp_no")
+
+# 资源种类 → 中文名（错误提示与审计摘要用）
+_ASSET_LABELS = {"logo": "logo", "favicon": "站点图标"}
+_ASSET_EXTS = {"logo": LOGO_EXTS, "favicon": FAVICON_EXTS}
+
 
 def get_setting(session: Session) -> SystemSetting:
     """取公司信息单行（种子保底 id=1；防御式兜底：极端环境下缺行则补建）。"""
@@ -45,10 +61,15 @@ def get_setting(session: Session) -> SystemSetting:
 
 
 def to_out(setting: SystemSetting) -> SettingOut:
-    """管理端出参（logo_url 带更新时间版本参数，替换图片后浏览器不再用旧缓存）。"""
+    """管理端出参（图片地址带更新时间版本参数，替换后浏览器不再用旧缓存）。"""
     return SettingOut(
         company_name=setting.company_name,
-        logo_url=_logo_url(setting),
+        logo_url=_asset_url(setting, "logo"),
+        site_title=setting.site_title,
+        brand_slogan=setting.brand_slogan,
+        footer_text=setting.footer_text,
+        icp_no=setting.icp_no,
+        favicon_url=_asset_url(setting, "favicon"),
     )
 
 
@@ -56,15 +77,26 @@ def to_public_out(setting: SystemSetting) -> SettingPublicOut:
     """匿名端点出参（白名单字段，独立 schema 见模块说明）。"""
     return SettingPublicOut(
         company_name=setting.company_name,
-        logo_url=_logo_url(setting),
+        logo_url=_asset_url(setting, "logo"),
+        site_title=setting.site_title,
+        brand_slogan=setting.brand_slogan,
+        footer_text=setting.footer_text,
+        icp_no=setting.icp_no,
+        favicon_url=_asset_url(setting, "favicon"),
     )
 
 
-def _logo_url(setting: SystemSetting) -> str | None:
+def _asset_url(setting: SystemSetting, kind: str) -> str | None:
-    if not setting.logo_path:
+    """资源 URL（kind=logo/favicon）；未上传返回 None。
+
+    版本号取**上传计数器**而非 update_time：同扩展名替换时固定文件名不变
+    （logo_path 值不变），MySQL 的 ON UPDATE 不会刷新 update_time，用它做
+    ?v= 会导致浏览器一直用旧图（2026-10-20 用户反馈的换图不刷新问题）。
+    """
+    if not getattr(setting, f"{kind}_path"):
         return None
-    version = int(setting.update_time.timestamp()) if setting.update_time else 0
+    version = getattr(setting, f"{kind}_version") or 0
-    return f"/api/v1/system/settings/logo/public?v={version}"
+    return f"/api/v1/system/settings/{kind}/public?v={version}"
 
 
 def update_company(
@@ -74,20 +106,34 @@ def update_company(
     operator: User,
     meta: RequestMeta | None = None,
 ) -> SettingOut:
-    """更新公司名称（审计留痕）。"""
+    """更新公司信息与站点信息（部分更新 + 审计留痕）。
+
+    仅提交的字段生效（``exclude_unset``：未提交/显式 null 保持原值），
+    便于「只改名称」「只改站点标题」等场景不覆盖其他字段；可选文本传
+    空串等价清空（落库 null）。
+    """
+    changes = payload.model_dump(exclude_unset=True, exclude_none=True)
+    summary = "修改公司信息"
+    if "company_name" in changes:
+        summary = f"修改公司信息（公司名称「{changes['company_name']}」）"
     with audit_service.audit(
         session,
         operator=operator,
         record=AuditRecord(
             module=MODULE_SYSTEM_SETTINGS,
             action=ACTION_UPDATE,
-            summary=f"修改公司名称为「{payload.company_name}」",
+            summary=summary,
-            request_data=payload.model_dump(),
+            request_data=changes or None,
         ),
         meta=meta,
     ):
         setting = get_setting(session)
-        setting.company_name = payload.company_name.strip()
+        if "company_name" in changes:
+            # schema 已保证提交值非空（min_length=1）
+            setting.company_name = changes["company_name"]
+        for field in _OPTIONAL_TEXT_FIELDS:
+            if field in changes:
+                setattr(setting, field, changes[field].strip() or None)
         session.commit()
         return to_out(setting)
 
@@ -100,17 +146,39 @@ def save_logo(
     operator: User,
     meta: RequestMeta | None = None,
 ) -> SettingOut:
-    """上传 logo：校验 → 固定名覆盖落盘 → 更新相对路径（审计留痕）。
+    """上传公司 logo（登录页品牌位；png/jpg ≤2MB）。"""
+    return _save_asset(session, content, ext, kind="logo", operator=operator, meta=meta)
+
+
+def save_favicon(
+    session: Session,
+    content: bytes,
+    ext: str,
+    *,
+    operator: User,
+    meta: RequestMeta | None = None,
+) -> SettingOut:
+    """上传站点图标（浏览器标签页；png/jpg/ico ≤2MB）。"""
+    return _save_asset(session, content, ext, kind="favicon", operator=operator, meta=meta)
+
+
+def _save_asset(
+    session: Session,
+    content: bytes,
+    ext: str,
+    *,
+    kind: str,
+    operator: User,
+    meta: RequestMeta | None,
+) -> SettingOut:
+    """校验 → 固定名覆盖落盘 → 更新相对路径（审计留痕）。
 
     旧扩展名文件一并清理（logo.png 换 jpg 后残留文件会继续占盘）。
     """
+    label = _ASSET_LABELS[kind]
+    allowed = _ASSET_EXTS[kind]
     ext = ext.lower()
-    if ext not in _MAGIC:
+    _validate_upload(content, ext, allowed=allowed, label=label)
-        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,
@@ -118,54 +186,79 @@ def save_logo(
         record=AuditRecord(
             module=MODULE_SYSTEM_SETTINGS,
             action=ACTION_UPDATE,
-            summary="更新公司 logo",
+            summary=f"更新{label}",
             request_data={"ext": ext, "size": len(content)},
         ),
         meta=meta,
     ):
         setting = get_setting(session)
-        old_path = setting.logo_path
+        old_path = getattr(setting, f"{kind}_path")
 
         # 先写新文件、commit 成功后再清旧扩展名（若把清理放在 commit 之前，
         # commit 失败会让库指旧路径而旧文件已删——断链无补偿）；同扩展名
         # 由写入覆盖，无需也不会误删新文件
-        target = _logo_dir() / f"logo.{ext}"
+        target = _asset_dir(kind) / f"{kind}.{ext}"
         target.write_bytes(content)
 
-        setting.logo_path = f"logo/logo.{ext}"
+        setattr(setting, f"{kind}_path", f"{kind}/{kind}.{ext}")
+        # 版本号每次上传必增：即使同扩展名覆盖（路径不变）也能破浏览器缓存
+        setattr(setting, f"{kind}_version", (getattr(setting, f"{kind}_version") or 0) + 1)
         session.commit()
 
         old_ext = Path(old_path).suffix.lstrip(".") if old_path else None
-        if old_ext and old_ext != ext:
+        if old_ext and old_ext != ext and old_ext in allowed:
             try:
-                _cleanup_old_logo(old_ext)
+                _cleanup_old_asset(kind, old_ext)
             except OSError:
                 # 清理失败不影响本次更新（库与新文件均已生效）；若异常外抛，
-                # 成功的 logo 更新会被记成失败审计并 500 —— 审计与事实相反
+                # 成功的更新会被记成失败审计并 500 —— 审计与事实相反
-                logger.warning("旧 logo 清理失败（不影响本次更新）| ext=%s", old_ext, exc_info=True)
+                logger.warning(
-        logger.info("更新公司 logo | size=%s ext=%s", len(content), ext)
+                    "旧%s清理失败（不影响本次更新）| ext=%s", label, old_ext, exc_info=True
+                )
+        logger.info("更新%s | size=%s ext=%s", label, len(content), ext)
         return to_out(setting)
 
 
 def read_logo(session: Session) -> tuple[Path, str]:
     """按库中记录定位 logo 文件，返回 (路径, 扩展名)。未上传抛 404。"""
+    return _read_asset(session, "logo")
+
+
+def read_favicon(session: Session) -> tuple[Path, str]:
+    """按库中记录定位站点图标文件，返回 (路径, 扩展名)。未上传抛 404。"""
+    return _read_asset(session, "favicon")
+
+
+def _read_asset(session: Session, kind: str) -> tuple[Path, str]:
+    label = _ASSET_LABELS[kind]
     setting = get_setting(session)
-    if not setting.logo_path:
+    path_str = getattr(setting, f"{kind}_path")
-        raise NotFoundError("尚未上传 logo")
+    if not path_str:
-    path = get_settings().upload_dir / setting.logo_path
+        raise NotFoundError(f"尚未上传{label}")
+    path = get_settings().upload_dir / path_str
     if not path.is_file():
-        raise NotFoundError("logo 文件不存在，请重新上传")
+        raise NotFoundError(f"{label}文件不存在，请重新上传")
     return path, path.suffix.lstrip(".")
 
 
-def _logo_dir() -> Path:
+def _validate_upload(content: bytes, ext: str, *, allowed: tuple[str, ...], label: str) -> None:
-    directory = get_settings().upload_dir / "logo"
+    """后缀白名单 + magic bytes + 大小三重校验（同口径供 logo/favicon 复用）。"""
+    if ext not in allowed:
+        raise BadRequestError(f"{label}仅支持 {'/'.join(allowed)} 格式")
+    if len(content) > ASSET_MAX_BYTES:
+        raise BadRequestError(f"{label}文件不能超过 2MB")
+    if not content.startswith(_MAGIC[ext]):
+        raise BadRequestError("文件内容与扩展名不符（仅接受真实图片）")
+
+
+def _asset_dir(kind: str) -> Path:
+    directory = get_settings().upload_dir / kind
     directory.mkdir(parents=True, exist_ok=True)
     return directory
 
 
-def _cleanup_old_logo(old_ext: str) -> None:
+def _cleanup_old_asset(kind: str, old_ext: str) -> None:
-    if old_ext in _MAGIC:
+    if old_ext in _ASSET_EXTS[kind]:
-        old_file = _logo_dir() / f"logo.{old_ext}"
+        old_file = _asset_dir(kind) / f"{kind}.{old_ext}"
         if old_file.exists():
             old_file.unlink(missing_ok=True)

backend/tests/README.md

@@ -136,6 +136,29 @@ uv run pytest tests/integration -q   # 仅集成
 
 运行：`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）。
+
 ## 三、运行记录
 
 | 日期 | 范围 | 用例数 | 结果 | 备注 |
@@ -155,11 +178,29 @@ uv run pytest tests/integration -q   # 仅集成
 | 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-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-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")` |
@@ -213,7 +254,7 @@ uv run pytest tests/integration -q   # 仅集成
 | 基础数据管理 | ✅ 已完成 | 2026-10-13 完成（48 例，见上表）；「被业务数据引用」的删除保护已随 T11 的业务/发货禁删用例覆盖 |
 | 业务数据管理 | ✅ 后端已完成 | 2026-10-13 完成（70 例，见上表）；前端页面与绩效核算联动（M3 台账核销回写 settlement_status）待 M3 补测 |
 | M3 增量（设置/分配/审批） | ✅ 已完成 | 2026-10-16 完成（44 例，见上表）；审批流的**月结审批对象**（order_type=2）随 ④ 月结子块接入时补测 |
-| 绩效工资核算（M3-core） | ✅ 已完成 | 2026-10-17 完成（核算/月结/调整单，见运行记录）；2026-10-19 code-review 21 项修复并补回归约 20 例。**待补**：e2e `calc_settlement_flow`（台账/月结两页真实浏览器链路）；业务答复回填批次（88 会话：首日 10‰/聚合基数开关/二次分摊拆行）落地后按同粒度补测 |
+| 绩效工资核算（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,7 +21,6 @@
 
 import uuid
 from decimal import Decimal
-from pathlib import Path
 
 import pytest
 from sqlalchemy import delete, select, update
@@ -37,6 +36,7 @@ from app.models import (
     BusinessRole,
     BusinessStatusLog,
     Customer,
+    CustomerRating,
     CustomerRatingGrade,
     MonthlySettlement,
     OperationLog,
@@ -164,6 +164,10 @@ def _purge_test_data() -> None:
             session.execute(
                 delete(OwnershipChangeLog).where(OwnershipChangeLog.customer_id.in_(customer_ids))
             )
+            # 评级行 FK RESTRICT：必须先于客户删除（V7 起客户评级每客户一行）
+            session.execute(
+                delete(CustomerRating).where(CustomerRating.customer_id.in_(customer_ids))
+            )
             session.execute(delete(Customer).where(Customer.id.in_(customer_ids)))
         # 客户被物理删除后其 customer_id 已无从收集，按操作人用户名兜底一条
         session.execute(
@@ -190,32 +194,103 @@ def _purge_test_data() -> None:
         # 审批单无 t_ 前缀可用，按 AP 编号前缀全量清（steps 外键 CASCADE 随删；
         # ref_id 固化无外键，业务已在上一步删除，无悬挂影响）
         session.execute(delete(ApprovalOrder).where(ApprovalOrder.order_no.like("AP%")))
-        # 开关参数恢复种子基线：测试提交的变更批次条目 id 均大于种子终值 25
+        # 开关参数恢复种子基线：测试提交的变更批次由 t_ 前缀测试账号创建，
-        # （V3 十九条 + V6 两条 + V7 调整单一条 + V8 经理基数开关一条；V8 另
+        # 按**批次操作人**删除本轮的参数条目与批次，解析后回退到种子值（开关=0）。
-        # 插入两个审批开关的 10-19 生效行 id 23/24，均属种子），删新条目与
+        # 不用 id 阈值：种子条目的主键在不同环境的漂移库中并不相同（历史库
-        # 新批次后解析回退到种子值
+        # 可能补过种子行），按操作人识别测试产物与环境数据分布无关。
-        stray_values = list(session.execute(select(ParamValue).where(ParamValue.id > 25)).scalars())
+        test_batch_ids = list(
-        if stray_values:
+            session.execute(
-            stray_batches = {v.batch_id for v in stray_values}
+                select(ParamChangeBatch.id).where(ParamChangeBatch.operator_name.like("t\\_%"))
-            session.execute(delete(ParamValue).where(ParamValue.id > 25))
+            ).scalars()
-            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)
         )
+        if test_batch_ids:
+            session.execute(delete(ParamValue).where(ParamValue.batch_id.in_(test_batch_ids)))
+            session.execute(delete(ParamChangeBatch).where(ParamChangeBatch.id.in_(test_batch_ids)))
         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)
+#
+# 系统设置是**真实单行数据**，logo/favicon 是真实上传文件，没有 t_ 前缀可供
+# 兜底清理。测试（尤其 logo 上传用例）会改公司名、覆盖/删除真实图片 ——
+# 必须在用例结束后还原，否则跑一次测试就会破坏开发环境的品牌与 logo。
+
+_ASSET_KINDS = ("logo", "favicon")
+
+
+def _snapshot_company_info() -> dict | None:
+    """快照系统设置单行（无行时返回 None）。"""
+    factory = get_session_factory()
+    with factory() as session:
+        row = session.get(SystemSetting, 1)
+        if row is None:
+            return None
+        return {column.name: getattr(row, column.name) for column in SystemSetting.__table__.columns}
+
+
+def _restore_company_info(snapshot: dict | None) -> None:
+    if snapshot is None:
+        return
+    factory = get_session_factory()
+    with factory() as session:
+        row = session.get(SystemSetting, 1)
+        if row is None:
+            return
+        for key, value in snapshot.items():
+            if key != "update_time":  # 更新时间由数据库 ON UPDATE 维护
+                setattr(row, key, value)
+        session.commit()
+
+
+def _snapshot_assets() -> dict[str, dict[str, bytes]]:
+    """快照上传目录里的真实图片（logo/favicon）。"""
+    from app.core.config import get_settings
+
+    root = get_settings().upload_dir
+    snapshot: dict[str, dict[str, bytes]] = {}
+    for kind in _ASSET_KINDS:
+        directory = root / kind
+        snapshot[kind] = (
+            {path.name: path.read_bytes() for path in directory.glob("*") if path.is_file()}
+            if directory.is_dir()
+            else {}
+        )
+    return snapshot
+
+
+def _restore_assets(snapshot: dict[str, dict[str, bytes]]) -> None:
+    """还原上传目录：删除测试新增文件、回写被测试覆盖的原文件。"""
+    from app.core.config import get_settings
+
+    root = get_settings().upload_dir
+    for kind, files in snapshot.items():
+        directory = root / kind
+        directory.mkdir(parents=True, exist_ok=True)
+        for path in directory.glob("*"):
+            if path.is_file() and path.name not in files:
+                path.unlink(missing_ok=True)
+        for name, content in files.items():
+            (directory / name).write_bytes(content)
 
 
 @pytest.fixture(autouse=True)
-def _purge_after_each_test():
+def _preserve_company_info():
-    """每个集成用例结束后兜底清理，避免残留影响后续用例的计数断言。"""
+    """每个用例前快照系统设置与上传图片，结束后还原（见上方说明）。"""
+    info = _snapshot_company_info()
+    assets = _snapshot_assets()
+    yield
+    # 先还原文件：数据库路径随后回指同一批文件
+    _restore_assets(assets)
+    _restore_company_info(info)
+
+
+@pytest.fixture(autouse=True)
+def _purge_after_each_test(_preserve_company_info):
+    """每个集成用例结束后兜底清理，避免残留影响后续用例的计数断言。
+
+    依赖 ``_preserve_company_info``：保证快照在该夹具之前建立、在该夹具
+    清理**之后**还原（夹具 teardown 为逆序）。
+    """
     yield
     _purge_test_data()
 

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

@@ -412,6 +412,71 @@ class TestEdit:
         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

@@ -22,7 +22,7 @@ from fastapi.testclient import TestClient
 from sqlalchemy import select
 
 from app.core.db import get_session_factory
-from app.models import PerformanceLedger, Receipt
+from app.models import PerformanceLedger, Personnel, Receipt, SecondaryAllocation
 from app.models.receipt import SETTLEMENT_DONE
 from tests.integration.factories import business_payload, customer
 
@@ -584,3 +584,207 @@ class TestBatch:
         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

@@ -11,6 +11,7 @@ append-only 完整性；「公司名称+负责人」组合唯一缺失会放行
 """
 
 import uuid
+from decimal import Decimal
 
 import pytest
 from fastapi.testclient import TestClient
@@ -376,3 +377,104 @@ class TestAudit:
         latest = logs[0]
         assert customer["company_name"] in latest.summary, "摘要应含客户名"
         assert "→" in latest.summary, "摘要应体现新旧归属走向"
+
+
+# ==================== 客户评级列（V11） ====================
+
+_RATING_KEYS = (
+    "score_ship_amount",
+    "score_receipt_rate",
+    "score_profit_rate",
+    "score_contract_cooperation",
+    "score_site_construction",
+)
+
+
+def _rate(client: TestClient, headers: dict, customer_id: int, scores: list[str]) -> dict:
+    """保存客户评级（五项 0-20），返回响应 data。"""
+    resp = client.put(
+        f"{_CUSTOMERS}/{customer_id}/rating",
+        json=dict(zip(_RATING_KEYS, scores, strict=True)),
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+def _list_by_keyword(client: TestClient, headers: dict, keyword: str, **params) -> list[dict]:
+    query: dict = {"keyword": keyword, "pageNum": 1, "pageSize": 50, **params}
+    resp = client.get(_CUSTOMERS, params=query, headers=headers)
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]["list"]
+
+
+class TestRatingColumn:
+    """客户评级列：列表带出评级快照，列头排序走服务端（未评级恒在末尾）。
+
+    列表是服务端分页，排序必须在 SQL 层完成 —— 前端只传
+    ``order_field=rating`` + ``order_type``；MySQL 无 NULLS LAST，
+    未评级行用布尔键模拟，正序/倒序都在末尾。
+    """
+
+    def _seed_three(self, client: TestClient, headers: dict) -> tuple[str, dict, dict, dict]:
+        """建三名同批次客户：90 分（A）、0 分（D）、未评级。"""
+        token = uuid.uuid4().hex[:8]
+        keyword = f"t_公司_{token}"
+        high = _create_customer(client, headers, company_name=f"{keyword}_甲")
+        low = _create_customer(client, headers, company_name=f"{keyword}_乙")
+        none = _create_customer(client, headers, company_name=f"{keyword}_丙")
+        _rate(client, headers, high["id"], ["18"] * 5)
+        _rate(client, headers, low["id"], ["0"] * 5)
+        return keyword, high, low, none
+
+    def test_列表带出评级字段(self, client: TestClient, normal: dict) -> None:
+        headers = normal["headers"]
+        keyword, high, low, none = self._seed_three(client, headers)
+        rows = _list_by_keyword(client, headers, keyword)
+        by_id = {row["id"]: row for row in rows}
+
+        assert Decimal(by_id[high["id"]]["rating_total"]) == Decimal("90")
+        assert by_id[high["id"]]["rating_grade_name"] == "A"
+        assert Decimal(by_id[low["id"]]["rating_total"]) == Decimal("0")
+        assert by_id[low["id"]]["rating_grade_name"] == "D"
+        assert by_id[none["id"]]["rating_total"] is None
+        assert by_id[none["id"]]["rating_grade_name"] is None
+
+    def test_评级列正序倒序_未评级恒末尾(self, client: TestClient, normal: dict) -> None:
+        headers = normal["headers"]
+        keyword, high, low, none = self._seed_three(client, headers)
+
+        desc = _list_by_keyword(client, headers, keyword, order_field="rating", order_type="desc")
+        assert [row["id"] for row in desc] == [high["id"], low["id"], none["id"]]
+
+        asc = _list_by_keyword(client, headers, keyword, order_field="rating", order_type="asc")
+        assert [row["id"] for row in asc] == [low["id"], high["id"], none["id"]]
+
+    def test_非法排序字段_400(self, client: TestClient, normal: dict) -> None:
+        """排序字段是白名单（Literal）：不透传给 SQL，非法值 400。"""
+        resp = client.get(
+            _CUSTOMERS,
+            params={"order_field": "company_name", "order_type": "asc"},
+            headers=normal["headers"],
+        )
+        assert resp.status_code == 400, resp.text
+
+    def test_非法排序方向_400(self, client: TestClient, normal: dict) -> None:
+        resp = client.get(
+            _CUSTOMERS,
+            params={"order_field": "rating", "order_type": "sideways"},
+            headers=normal["headers"],
+        )
+        assert resp.status_code == 400, resp.text
+
+    def test_删除客户联动删评级行(self, client: TestClient, normal: dict) -> None:
+        """评级行 FK RESTRICT：删除客户须先清评级行，否则 500。"""
+        headers = normal["headers"]
+        customer = _create_customer(client, headers)
+        _rate(client, headers, customer["id"], ["20"] * 5)
+
+        resp = client.delete(f"{_CUSTOMERS}/{customer['id']}", headers=headers)
+        assert resp.status_code == 200, resp.text
+        assert (
+            client.get(f"{_CUSTOMERS}/{customer['id']}/rating", headers=headers).status_code == 404
+        )

backend/tests/integration/test_dashboard.py

@@ -0,0 +1,453 @@
+"""工作台集成测试（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:
+    """直插在途审批单（避免依赖两次流转，专注工作台过滤口径）。"""
+    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=0,
+                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_param_management.py

@@ -86,10 +86,10 @@ def _snapshot_value(client: TestClient, admin: dict, param_code: str, *, as_of:
 class TestCatalog:
     """参数目录：种子完整性与时点化回溯。"""
 
-    def test_目录共19项且覆盖八个分组(self, client: TestClient, admin: dict) -> None:
+    def test_目录共22项且覆盖九个分组(self, client: TestClient, admin: dict) -> None:
-        """V7 起含调整单审批开关（16 计提项 + 3 BOOL 开关）。"""
+        """V10 起含工作台预警规则三项（16 计提项 + 3 BOOL 开关 + 3 预警项）。"""
         items = client.get(_PARAMS, headers=admin["headers"]).json()["data"]
-        assert len(items) == 19
+        assert len(items) == 22
         groups = {item["param_group"] for item in items}
         assert groups == {
             "业务员个人户",
@@ -100,6 +100,7 @@ class TestCatalog:
             "产品阈值",
             "月工资口径",
             "审批开关",
+            "预警规则",
         }
 
     def test_企业户比例按到账日回溯_2千分3千分双种子(self, client: TestClient, admin: dict) -> None:
@@ -444,7 +445,7 @@ class TestPermission:
         headers = auth_headers(user)
         resp = client.get(_PARAMS, headers=headers)
         assert resp.status_code == 200
-        assert len(resp.json()["data"]) == 19
+        assert len(resp.json()["data"]) == 22
 
     def test_未登录访问目录_403(self, client: TestClient) -> None:
         # LoginUser 依赖无令牌即拒（401 语义归登录态失效，此处由依赖抛 403/401

backend/tests/integration/test_ratings.py

@@ -21,15 +21,17 @@ from decimal import Decimal
 
 import pytest
 from fastapi.testclient import TestClient
-from sqlalchemy import select
+from sqlalchemy import func, select
 
 from app.core.constants import ACTION_CREATE, MODULE_RATING
 from app.core.db import get_session_factory
-from app.models import OperationLog
+from app.models import CustomerRating, CustomerRatingGrade, OperationLog
+from app.services.rating_service import resolve_grade
 
 pytestmark = pytest.mark.integration
 
 _GRADES = "/api/v1/business/rating-grades"
+_CUSTOMERS = "/api/v1/base/customers"
 
 # 种子基线（与 V5 迁移一致）：分数字符串经 DB round-trip 后一位小数（Numeric(5,1)）
 _SEED = [
@@ -77,6 +79,41 @@ def _names(client: TestClient, headers: dict) -> list[str]:
     return [row["grade_name"] for row in client.get(_GRADES, headers=headers).json()["data"]]
 
 
+def _create_customer(client: TestClient, headers: dict) -> dict:
+    """建一名 t_ 前缀测试客户（评级落库的被引用方，conftest 兜底清理）。"""
+    resp = client.post(
+        _CUSTOMERS,
+        json={
+            "company_name": f"t_评级客户_{uuid.uuid4().hex[:8]}",
+            "owner_name": "t_老板",
+            "customer_type": "personal",
+        },
+        headers=headers,
+    )
+    assert resp.status_code == 200, resp.text
+    return resp.json()["data"]
+
+
+_RATING_KEYS = (
+    "score_ship_amount",
+    "score_receipt_rate",
+    "score_profit_rate",
+    "score_contract_cooperation",
+    "score_site_construction",
+)
+
+
+def _rating_url(customer_id: int) -> str:
+    return f"{_CUSTOMERS}/{customer_id}/rating"
+
+
+def _rating_payload(scores: list[str], remark: str | None = None) -> dict:
+    body: dict = dict(zip(_RATING_KEYS, scores, strict=True))
+    if remark is not None:
+        body["remark"] = remark
+    return body
+
+
 def _logs_of(username: str) -> list[OperationLog]:
     """取某操作人的审计行（按 id 倒序，最新在前）。"""
     factory = get_session_factory()
@@ -258,8 +295,8 @@ class TestEdit:
 
 
 class TestDelete:
-    """删除允许清空（评级是纯计算器、评分记录不落库）—— 删除后判定表
+    """删除允许清空（客户评级快照固化等级名、无外键引用）—— 删除后判定表
-    立即反映，二次删除 404。"""
+    立即反映，二次删除 404，已评级客户的历史等级快照不受影响。"""
 
     def test_删除等级后判定表更新_二次删除404(self, client: TestClient, normal: dict) -> None:
         headers = normal["headers"]
@@ -313,3 +350,146 @@ class TestAudit:
         ]
         assert failed, "失败操作未留痕"
         assert "分值区间与等级 A 重叠" in (failed[0].error_message or ""), failed[0]
+
+
+class TestResolveGrade:
+    """判定纯函数边界：与前端打分卡同规则（sort_order 升序首个 min_score ≤ 总分）。
+
+    单边判定让边界分归 sort_order 靠前的等级：90→A、75→B、60→C、59.9→D；
+    等级表为空或总分低于全部下限时返回 None（落库等级为 NULL）。
+    """
+
+    @staticmethod
+    def _seed_grades() -> list[CustomerRatingGrade]:
+        return [
+            CustomerRatingGrade(
+                grade_name=name,
+                min_score=Decimal(min_score),
+                max_score=Decimal(max_score),
+                sort_order=order,
+            )
+            for name, min_score, max_score, order in _SEED
+        ]
+
+    def test_边界分归高档(self) -> None:
+        grades = self._seed_grades()
+        assert resolve_grade(grades, Decimal("90")).grade_name == "A"
+        assert resolve_grade(grades, Decimal("75")).grade_name == "B"
+        assert resolve_grade(grades, Decimal("60")).grade_name == "C"
+
+    def test_下限下方归最低档(self) -> None:
+        assert resolve_grade(self._seed_grades(), Decimal("59.9")).grade_name == "D"
+
+    def test_等级表为空_未命中(self) -> None:
+        assert resolve_grade([], Decimal("80")) is None
+
+    def test_低于全部下限_未命中(self) -> None:
+        grades = [
+            CustomerRatingGrade(
+                grade_name="A",
+                min_score=Decimal("90"),
+                max_score=Decimal("100"),
+                sort_order=1,
+            )
+        ]
+        assert resolve_grade(grades, Decimal("50")) is None
+
+
+class TestCustomerRating:
+    """客户评级落库（V11）：每客户一行、服务端重算总分与等级、等级快照固化。
+
+    五项各 0-20 → 总分 0-100；等级按保存时点判定并写入 grade_name（无外键）。
+    未评级返回 data=null（正常态）；分数越界 400 且审计留痕。
+    """
+
+    def test_未评级返回null(self, client: TestClient, normal: dict) -> None:
+        customer = _create_customer(client, normal["headers"])
+        resp = client.get(_rating_url(customer["id"]), headers=normal["headers"])
+        assert resp.status_code == 200, resp.text
+        assert resp.json()["data"] is None
+
+    def test_保存评级_服务端重算总分等级并留审计(self, client: TestClient, normal: dict) -> None:
+        headers = normal["headers"]
+        customer = _create_customer(client, headers)
+        put = client.put(
+            _rating_url(customer["id"]),
+            json=_rating_payload(["18", "20", "19", "17", "16"], remark="t_评级依据"),
+            headers=headers,
+        )
+        assert put.status_code == 200, put.text
+        data = put.json()["data"]
+        assert Decimal(data["total_score"]) == Decimal("90")
+        assert data["grade_name"] == "A"
+        assert data["remark"] == "t_评级依据"
+        assert data["scorer_name"] == normal["username"]
+
+        # 回读一致（列表评级列与弹窗回显同源）
+        got = client.get(_rating_url(customer["id"]), headers=headers).json()["data"]
+        assert Decimal(got["total_score"]) == Decimal("90")
+        assert got["grade_name"] == "A"
+        assert Decimal(got["score_ship_amount"]) == Decimal("18")
+
+        logs = [log for log in _logs_of(normal["username"]) if log.module == MODULE_RATING]
+        assert logs, "保存客户评级未留操作日志"
+        assert logs[0].success == 1
+        assert customer["company_name"] in logs[0].summary
+        assert "评级" in logs[0].summary
+
+    def test_重复保存覆盖同一客户仅一行(self, client: TestClient, normal: dict) -> None:
+        headers = normal["headers"]
+        customer = _create_customer(client, headers)
+        first = client.put(
+            _rating_url(customer["id"]), json=_rating_payload(["0"] * 5), headers=headers
+        )
+        assert first.status_code == 200, first.text
+        assert first.json()["data"]["grade_name"] == "D"
+
+        second = client.put(
+            _rating_url(customer["id"]), json=_rating_payload(["20"] * 5), headers=headers
+        )
+        assert second.status_code == 200, second.text
+        assert Decimal(second.json()["data"]["total_score"]) == Decimal("100")
+        assert second.json()["data"]["grade_name"] == "A"
+
+        factory = get_session_factory()
+        with factory() as session:
+            count = session.execute(
+                select(func.count())
+                .select_from(CustomerRating)
+                .where(CustomerRating.customer_id == customer["id"])
+            ).scalar_one()
+        assert count == 1, "同一客户出现多行评级（upsert 失效）"
+
+    def test_单项分数越界_400(self, client: TestClient, normal: dict) -> None:
+        headers = normal["headers"]
+        customer = _create_customer(client, headers)
+        for bad in (["21", "0", "0", "0", "0"], ["0", "-1", "0", "0", "0"]):
+            resp = client.put(
+                _rating_url(customer["id"]), json=_rating_payload(bad), headers=headers
+            )
+            assert resp.status_code == 400, resp.text
+            assert "0~20" in resp.json()["message"], resp.text
+
+    def test_客户不存在_404(self, client: TestClient, normal: dict) -> None:
+        headers = normal["headers"]
+        assert client.get(_rating_url(999_999_999), headers=headers).status_code == 404
+        put = client.put(_rating_url(999_999_999), json=_rating_payload(["0"] * 5), headers=headers)
+        assert put.status_code == 404, put.text
+
+    def test_等级表清空后保存_等级为null(self, client: TestClient, normal: dict) -> None:
+        """等级映射允许清空（快照设计前提）：清空后评分照常保存，仅等级为 NULL。"""
+        headers = normal["headers"]
+        for name in ("A", "B", "C", "D"):
+            assert (
+                client.delete(
+                    f"{_GRADES}/{_seed_id(client, headers, name)}", headers=headers
+                ).status_code
+                == 200
+            )
+
+        customer = _create_customer(client, headers)
+        data = client.put(
+            _rating_url(customer["id"]), json=_rating_payload(["20"] * 5), headers=headers
+        ).json()["data"]
+        assert Decimal(data["total_score"]) == Decimal("100")
+        assert data["grade_name"] is None

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_settings.py

@@ -23,6 +23,7 @@ _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
+_ICO_BYTES = b"\x00\x00\x01\x00" + b"\x00" * 32
 _TXT_BYTES = b"not an image at all"
 
 
@@ -31,6 +32,10 @@ def client() -> TestClient:
     return TestClient(app)
 
 
+# 系统设置单行与上传文件的快照/还原已上移到 integration/conftest.py，
+# 对所有集成用例生效（不再只保护本模块）。
+
+
 class TestCompanyInfo:
     """公司名称读取与更新。"""
 
@@ -84,10 +89,30 @@ class TestPublicEndpoint:
         resp = client.get(f"{_SETTINGS}/public")
         assert resp.status_code == 200
         data = resp.json()["data"]
-        assert set(data) == {"company_name", "logo_url"}, "public 端点字段越界"
+        assert set(data) == {
+            "company_name",
+            "logo_url",
+            "site_title",
+            "brand_slogan",
+            "footer_text",
+            "icp_no",
+            "favicon_url",
+        }, "public 端点字段越界"
         assert data["company_name"] == name
         assert resp.headers.get("cache-control") is not None
 
+    def test_已删除的档案字段不再返回(self, client: TestClient) -> None:
+        """V11 精简：副标题/信用代码/地址/电话/邮箱已从模型与契约中删除。"""
+        data = client.get(f"{_SETTINGS}/public").json()["data"]
+        for field in (
+            "system_subtitle",
+            "credit_code",
+            "company_address",
+            "contact_phone",
+            "contact_email",
+        ):
+            assert field not in data, f"已删除字段仍出现在匿名端点：{field}"
+
     def test_写操作匿名不可用(self, client: TestClient) -> None:
         assert client.put(f"{_SETTINGS}/public", json={"company_name": "x"}).status_code in {
             401,
@@ -95,6 +120,41 @@ class TestPublicEndpoint:
         }
 
 
+class TestCompanyProfile:
+    """站点标题/品牌信息（V11）：部分更新语义与空串清空。"""
+
+    def test_部分更新_未提交字段保持不变(self, client: TestClient, admin: dict) -> None:
+        name = f"站点公司_{uuid.uuid4().hex[:6]}"
+        client.put(_SETTINGS, json={"company_name": name}, headers=admin["headers"])
+
+        put = client.put(_SETTINGS, json={"site_title": "测试站点标题"}, headers=admin["headers"])
+        assert put.status_code == 200, put.text
+        assert put.json()["data"]["site_title"] == "测试站点标题"
+        # 未提交的 company_name 保持不变（部分更新语义）
+        assert put.json()["data"]["company_name"] == name
+
+        got = client.get(_SETTINGS, headers=admin["headers"]).json()["data"]
+        assert got["company_name"] == name
+        assert got["site_title"] == "测试站点标题"
+
+    def test_可选文本传空串_清空为null(self, client: TestClient, admin: dict) -> None:
+        client.put(
+            _SETTINGS,
+            json={"brand_slogan": "t_临时标语", "icp_no": "t_备案号"},
+            headers=admin["headers"],
+        )
+        put = client.put(
+            _SETTINGS, json={"brand_slogan": "", "icp_no": ""}, headers=admin["headers"]
+        )
+        assert put.status_code == 200, put.text
+        assert put.json()["data"]["brand_slogan"] is None
+        assert put.json()["data"]["icp_no"] is None
+
+    def test_超长字段被拒(self, client: TestClient, admin: dict) -> None:
+        resp = client.put(_SETTINGS, json={"site_title": "x" * 65}, headers=admin["headers"])
+        assert resp.status_code == 400, resp.text
+
+
 class TestLogoUpload:
     """logo 上传校验链。"""
 
@@ -135,3 +195,65 @@ class TestLogoUpload:
             files={"file": ("logo.png", _PNG_BYTES, "application/octet-stream")},
         )
         assert resp.status_code == 401
+
+    def test_同扩展名替换_url版本号变化(self, client: TestClient, admin: dict) -> None:
+        """同扩展名覆盖时路径与 update_time 都不变 —— 版本号必须递增，否则浏览器用旧图。"""
+        first = self._upload(client, admin, "logo.png", _PNG_BYTES).json()["data"]["logo_url"]
+        second = self._upload(client, admin, "logo.png", _PNG_BYTES).json()["data"]["logo_url"]
+        assert first and second
+        assert first != second, "同扩展名替换后图片 URL 未变化，浏览器会继续使用旧缓存"
+
+
+class TestFaviconUpload:
+    """站点图标上传校验链（独立于 logo；favicon 额外接受 ico）。"""
+
+    def _upload(self, client: TestClient, admin: dict, filename: str, content: bytes):
+        return client.post(
+            f"{_SETTINGS}/favicon",
+            files={"file": (filename, content, "application/octet-stream")},
+            headers=admin["headers"],
+        )
+
+    def test_合法ico上传成功且回读(self, client: TestClient, admin: dict) -> None:
+        resp = self._upload(client, admin, "favicon.ico", _ICO_BYTES)
+        assert resp.status_code == 200, resp.text
+        out = resp.json()["data"]
+        assert out["favicon_url"] and "/favicon/public" in out["favicon_url"]
+
+        img = client.get(f"{_SETTINGS}/favicon/public")
+        assert img.status_code == 200
+        assert img.headers["content-type"] == "image/x-icon"
+
+    def test_合法png上传成功(self, client: TestClient, admin: dict) -> None:
+        resp = self._upload(client, admin, "favicon.png", _PNG_BYTES)
+        assert resp.status_code == 200, resp.text
+        assert "/favicon/public" in resp.json()["data"]["favicon_url"]
+
+    def test_伪造扩展名被magic_bytes拦截(self, client: TestClient, admin: dict) -> None:
+        resp = self._upload(client, admin, "fake.ico", _TXT_BYTES)
+        assert resp.status_code == 400, resp.text
+        assert "不符" in resp.json()["message"]
+
+    def test_同扩展名替换_url版本号变化(self, client: TestClient, admin: dict) -> None:
+        first = self._upload(client, admin, "favicon.png", _PNG_BYTES).json()["data"]["favicon_url"]
+        second = self._upload(client, admin, "favicon.png", _PNG_BYTES).json()["data"][
+            "favicon_url"
+        ]
+        assert first and second
+        assert first != second, "同扩展名替换后站点图标 URL 未变化"
+
+    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}/favicon",
+            files={"file": ("favicon.png", _PNG_BYTES, "application/octet-stream")},
+        )
+        assert resp.status_code == 401

backend/tests/integration/test_settlements.py

@@ -749,3 +749,24 @@ class TestLockInterception:
         resp = client.post(f"{_CALC}/receipts/{unsettled['id']}/calc", headers=admin["headers"])
         assert resp.status_code == 400, resp.text
         assert "锁定" in resp.json()["message"]
+
+
+def test_非法月份_月结生成与调整单均返回400(client: TestClient, admin: dict) -> None:
+    """月份范围必须在 schema 拦住：`2026-13` 不能传到 monthrange 变成 500。"""
+    resp = client.post(
+        f"{_SETTLEMENTS}/generate", json={"month": "2026-13"}, headers=admin["headers"]
+    )
+    assert resp.status_code == 400, resp.text
+
+    resp = client.post(
+        f"{_SETTLEMENTS}/adjustments",
+        json={
+            "settlement_month": "2026-13",
+            "personnel_id": 1,
+            "direction": 1,
+            "amount": "100.00",
+            "reason": "t_非法月份",
+        },
+        headers=admin["headers"],
+    )
+    assert resp.status_code == 400, resp.text

backend/tests/unit/test_models.py

@@ -40,6 +40,7 @@ EXPECTED_TABLES = {
     "shipment_items",
     "receipts",
     "customer_rating_grades",
+    "customer_ratings",
     "performance_ledgers",
     "monthly_settlements",
     "settlement_items",

backend/tests/unit/test_month_validation.py

@@ -0,0 +1,55 @@
+"""月份校验单元测试。
+
+守的口径：报表、月结、调整单入口都必须拦住 `2026-13`、`0000-01` 这类
+非法月份。只校验长度会让 ValueError 一路传到 `calendar.monthrange`，
+最终变成 500 而不是参数错误 400。
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from app.core.month import parse_month, validate_month
+from app.schemas.report import DepartmentSummaryQuery, PersonalDetailQuery
+from app.schemas.settlement import AdjustmentCreateIn, SettlementGenerateIn
+
+
+class Test月份校验:
+    """合法月份通过，非法月份在入口即拒绝。"""
+
+    @pytest.mark.parametrize("month", ["2026-01", "2026-12", "2000-06"])
+    def test_合法月份_通过(self, month: str):
+        assert validate_month(month) == month
+        year, mon = parse_month(month)
+        assert (year, mon) == (int(month[:4]), int(month[5:7]))
+
+    @pytest.mark.parametrize(
+        "month",
+        ["2026-13", "2026-00", "2026-1", "2026-1a", "0000-01", "abc", "2026/10"],
+    )
+    def test_非法月份_抛ValueError(self, month: str):
+        with pytest.raises(ValueError):
+            validate_month(month)
+
+    @pytest.mark.parametrize("month", ["2026-13", "2026-00", "0000-01"])
+    def test_月结与调整单_schema拒绝非法月份(self, month: str):
+        with pytest.raises(ValidationError):
+            SettlementGenerateIn(month=month)
+        with pytest.raises(ValidationError):
+            AdjustmentCreateIn(
+                settlement_month=month,
+                personnel_id=1,
+                direction=1,
+                amount="100.00",
+                reason="测试",
+            )
+
+    @pytest.mark.parametrize("month", ["2026-13", "2026-00", "0000-01"])
+    def test_报表查询_schema拒绝非法月份(self, month: str):
+        with pytest.raises(ValidationError):
+            DepartmentSummaryQuery(settlement_month=month)
+        with pytest.raises(ValidationError):
+            PersonalDetailQuery(settlement_month=month)
+
+    def test_报表可选月份_空串规范为None(self):
+        """axios 未剔除空串时不能误报格式错误。"""
+        assert PersonalDetailQuery(settlement_month="").settlement_month is None

backend/tests/unit/test_param_registry.py

@@ -18,8 +18,9 @@ from app.services.param_registry import (
     validate_and_normalize,
 )
 
-# 与 db/migration 迁移种子保持一致的 19 项编码（V3 十六项 + V6 审批开关两项
+# 与 db/migration 迁移种子保持一致的 22 项编码（V3 十六项 + V6 审批开关两项
-# + V7 调整单开关；V8 撤试用期统一工资参数 #16、增经理个人户基数开关 #12）
+# + V7 调整单开关；V8 撤试用期统一工资参数 #16、增经理个人户基数开关 #12；
+# V10 增工作台预警规则三项 #10）
 EXPECTED_CODES = {
     "salesperson.rate.start",
     "salesperson.rate.slope",
@@ -40,14 +41,17 @@ EXPECTED_CODES = {
     "approval.monthly_settlement.enabled",
     "approval.adjustment.enabled",
     "manager.personal.included",
+    "warning.enabled",
+    "warning.receipt.overdue.days",
+    "warning.approval.timeout.days",
 }
 
 
 class TestRegistry:
     """注册表元数据完整性（与迁移种子同源）。"""
 
-    def test_注册表共19项(self) -> None:
+    def test_注册表共22项(self) -> None:
-        assert len(PARAM_REGISTRY) == 19
+        assert len(PARAM_REGISTRY) == 22
 
     def test_编码集合与迁移种子一致(self) -> None:
         assert set(PARAM_REGISTRY) == EXPECTED_CODES

backend/tests/unit/test_report_helpers.py

@@ -0,0 +1,422 @@
+"""报表辅助纯函数与 Excel 模板构建单元测试（M4 ⑤）。
+
+这组用例守的是「不测会静默出错」的三类点：
+- 区间分桶边界错一档 → 金额进错桶，但报表仍然「能打开」，没人会发现
+- 标签映射漏一个枚举值 → 报表少一类数据或显示英文编码
+- 导出模板缺签字栏 / 金额被转 float / 文本公式注入 → 交给财务的签字稿失真
+"""
+
+import io
+from datetime import date
+from decimal import Decimal
+
+from openpyxl import load_workbook
+
+from app.core import report_meta
+from app.core.constants import CUSTOMER_TYPES, PRODUCT_CATEGORIES
+from app.services import report_export
+
+
+class Test区间分桶:
+    """回款天数 → 8 档区间（含 ≤0 与无天数两个兜底桶）。"""
+
+    def test_边界值全部落入正确区间(self):
+        cases = [
+            (None, "none"),
+            (-5, "le0"),
+            (0, "le0"),
+            (1, "1-30"),
+            (30, "1-30"),
+            (31, "31-60"),
+            (60, "31-60"),
+            (61, "61-90"),
+            (90, "61-90"),
+            (91, "91-180"),
+            (180, "91-180"),
+            (181, "181-360"),
+            (360, "181-360"),
+            (361, "361+"),
+            (1000, "361+"),
+        ]
+        for days, code in cases:
+            assert report_meta.bucket_of(days).code == code, f"days={days}"
+
+    def test_八档且编码唯一(self):
+        buckets = report_meta.get_payment_day_buckets()
+        assert len(buckets) == 8
+        assert len({b.code for b in buckets}) == 8
+
+
+class Test标签覆盖:
+    """标签键集合必须覆盖业务常量——防常量新增后报表静默少算/显示编码。"""
+
+    def test_客户类型标签覆盖全部类型(self):
+        assert set(report_meta.CUSTOMER_TYPE_LABELS) >= CUSTOMER_TYPES
+
+    def test_产品类别标签覆盖常量与混合业务(self):
+        assert set(report_meta.PRODUCT_CATEGORY_LABELS) >= PRODUCT_CATEGORIES
+        assert "mixed" in report_meta.PRODUCT_CATEGORY_LABELS
+
+
+def _build(code: str, rows: list[dict], buckets: dict | None = None) -> bytes:
+    return report_export.build_workbook(
+        code=code,
+        title="测试报表",
+        filters="统计月份 2026-10",
+        rows=rows,
+        summary=None,
+        buckets=buckets,
+        template_version="V1.0",
+        operator_name="admin",
+        company_name="衍水集团",
+    )
+
+
+def _sheet_text(content: bytes) -> str:
+    workbook = load_workbook(io.BytesIO(content))
+    return "\n".join(
+        str(cell.value)
+        for row in workbook.active.iter_rows()
+        for cell in row
+        if cell.value is not None
+    )
+
+
+def _personal_row(**overrides) -> dict:
+    row = {
+        "business_no": "YW001",
+        "ship_date": date(2026, 10, 1),
+        "receipt_date": date(2026, 10, 20),
+        "payment_days": 20,
+        "product_category": "municipal_water",
+        "customer_type": "personal",
+        "role_name": "营销员",
+        "rate_text": "88/9000",
+        "weight_r": 100,
+        "performance_amount": Decimal("39.11"),
+        "payable_amount": Decimal("39.11"),
+    }
+    row.update(overrides)
+    return row
+
+
+class TestExcel模板:
+    """导出稿是交给财务复核与领导签字的，结构缺失等同于没有模板。"""
+
+    def test_页眉标题签字栏齐全(self):
+        text = _sheet_text(_build("personal-detail", [_personal_row()]))
+        assert "衍水集团" in text
+        assert "测试报表" in text
+        assert "统计月份 2026-10" in text
+        assert "模板版本：V1.0" in text
+        assert "财务复核" in text
+        assert "领导签字" in text
+
+    def test_空数据不炸且给提示行(self):
+        text = _sheet_text(_build("personal-detail", []))
+        assert "本筛选条件无数据" in text
+        assert "财务复核" in text
+
+    def test_金额为数值单元格且两位格式(self):
+        # openpyxl 写入 Decimal 后读回为 int/float（Excel 单元格本身是数值），
+        # 这里断言「是数值而非文本」+ 显示格式；计算精度在服务层 Decimal 侧保证
+        content = _build("personal-detail", [_personal_row()])
+        workbook = load_workbook(io.BytesIO(content))
+        sheet = workbook.active
+        amount_cells = [
+            cell
+            for row in sheet.iter_rows()
+            for cell in row
+            if isinstance(cell.value, (int, float))
+            and Decimal(str(cell.value)) == Decimal("39.11")
+        ]
+        assert amount_cells, "未找到金额数值单元格（Decimal 被转成了文本？）"
+        assert amount_cells[0].number_format == "#,##0.00"
+
+    def test_合计行等于明细之和且标签只出现一次(self):
+        rows = [
+            _personal_row(performance_amount=Decimal("10.00"), payable_amount=Decimal("10.00")),
+            _personal_row(performance_amount=Decimal("5.50"), payable_amount=Decimal("5.50")),
+        ]
+        content = _build("personal-detail", rows)
+        workbook = load_workbook(io.BytesIO(content))
+        cells = [cell for row in workbook.active.iter_rows() for cell in row]
+        values = [
+            Decimal(str(cell.value))
+            for cell in cells
+            if isinstance(cell.value, (int, float))
+        ]
+        assert Decimal("15.50") in values
+        # 「合计」标签只写一次（写满每个文本列是回归缺陷）
+        assert sum(1 for cell in cells if cell.value == "合计") == 1
+
+    def test_文本公式注入被前置单引号(self):
+        evil = "=HYPERLINK(\"http://evil\")"
+        content = _build("personal-detail", [_personal_row(business_no=evil)])
+        workbook = load_workbook(io.BytesIO(content))
+        values = [
+            cell.value
+            for row in workbook.active.iter_rows()
+            for cell in row
+            if isinstance(cell.value, str)
+        ]
+        assert any(value.startswith("'=") for value in values), "公式注入未转义"
+
+    def test_回款统计附两个维度对比sheet(self):
+        buckets = {
+            "by_customer_type": [
+                {
+                    "label": "个人户",
+                    "receipt_amount": Decimal("100.00"),
+                    "performance_amount": Decimal("1.00"),
+                    "payable_amount": Decimal("1.00"),
+                    "ledger_count": 1,
+                }
+            ],
+            "by_product_category": [],
+        }
+        content = _build(
+            "payment-stats",
+            [
+                {
+                    "label": "1-30 天",
+                    "receipt_amount": Decimal("100.00"),
+                    "receipt_count": 1,
+                    "performance_amount": Decimal("1.00"),
+                    "payable_amount": Decimal("1.00"),
+                    "ledger_count": 1,
+                }
+            ],
+            buckets=buckets,
+        )
+        workbook = load_workbook(io.BytesIO(content))
+        assert workbook.sheetnames == ["回款统计", "客户类型对比", "产品类别对比"]
+
+    def test_业务统计状态转中文(self):
+        rows = [
+            {
+                "business_no": "YW001",
+                "business_date": date(2026, 10, 1),
+                "customer_name": "测试客户",
+                "owner_personnel_name": "张三",
+                "status": 2,
+                "total_sale_amount": Decimal("100.00"),
+                "total_ship_amount": Decimal("100.00"),
+                "total_received_amount": Decimal("100.00"),
+                "performance_amount": Decimal("1.00"),
+                "payable_amount": Decimal("1.00"),
+            }
+        ]
+        text = _sheet_text(_build("business-stats", rows))
+        assert "已完成" in text
+
+
+def _member(
+    personnel_id: int,
+    name: str,
+    *,
+    kind: str = "regular",
+    performance: str = "0.00",
+    payable: str = "0.00",
+    adjust: str = "0.00",
+    reason: str | None = None,
+) -> dict:
+    return {
+        "personnel_id": personnel_id,
+        "personnel_name": name,
+        "role_code": "salesperson",
+        "is_probation": 0,
+        "member_kind": kind,
+        "unassigned_reason": reason,
+        "performance_sum": Decimal(performance),
+        "payable_sum": Decimal(payable),
+        "adjust_extra": Decimal(adjust),
+        "adjust_deduct": Decimal("0"),
+        "adjust_net": Decimal(adjust),
+        "net_total": Decimal(payable) + Decimal(adjust),
+        "ledger_ids": [],
+    }
+
+
+def _department_data(
+    team_text: str = "12.5",
+    company_text: str = "5",
+    *,
+    second_has_aggregate: bool = False,
+) -> dict:
+    """一份含成员、零成员团队与未分配人员的部门汇总出参。
+
+    ``second_has_aggregate`` 打开后两位经理都有月结聚合行，用于验证
+    全公司 5% 按人数累计（零成员团队默认不发 5%）。
+    """
+    second_aggregate = Decimal("600.00") if second_has_aggregate else Decimal("0")
+    share_count = 2 if second_has_aggregate else 1
+    aggregate_total = Decimal("1850.00") + second_aggregate
+    payable_total = Decimal("10000.00") + Decimal("2000.00") + aggregate_total
+    return {
+        "settlement_month": "2026-10",
+        "params": {
+            "team_text": team_text,
+            "company_text": company_text,
+            "manager_personal_included": 0,
+            "params_as_of": "2026-10-31",
+        },
+        "teams": [
+            {
+                "manager_id": 1,
+                "manager_name": "张经理",
+                "manager_status": 1,
+                "member_count": 1,
+                "team_base": Decimal("10000.00"),
+                "team_share_amount": Decimal("1250.00"),
+                "company_share_amount": Decimal("600.00"),
+                "has_aggregate": True,
+                "aggregate_amount": Decimal("1850.00"),
+                "team_subtotal": Decimal("1850.00"),
+                "company_base_ratio": Decimal("0.8333"),
+                "adjust_extra": Decimal("0"),
+                "adjust_deduct": Decimal("0"),
+                "adjust_net": Decimal("0"),
+                "net_total": Decimal("1850.00"),
+                "frozen_amount": None,
+                "aggregate_ledger_id": None,
+                "members": [
+                    _member(
+                        2,
+                        "李业务",
+                        performance="10000.00",
+                        payable="10000.00",
+                    )
+                ],
+            },
+            {
+                "manager_id": 3,
+                "manager_name": "王经理",
+                "manager_status": 1,
+                "member_count": 0,
+                "team_base": Decimal("0"),
+                "team_share_amount": Decimal("0"),
+                "company_share_amount": second_aggregate,
+                "has_aggregate": second_has_aggregate,
+                "aggregate_amount": second_aggregate,
+                "team_subtotal": second_aggregate,
+                "company_base_ratio": Decimal("0"),
+                "adjust_extra": Decimal("0"),
+                "adjust_deduct": Decimal("0"),
+                "adjust_net": Decimal("0"),
+                "net_total": second_aggregate,
+                "frozen_amount": None,
+                "aggregate_ledger_id": None,
+                "members": [],
+            },
+        ],
+        "unassigned": [
+            _member(
+                4,
+                "赵未分配",
+                performance="2000.00",
+                payable="2000.00",
+                reason="无经理或上级非营销经理",
+            )
+        ],
+        "company": {
+            "team_base_total": Decimal("10000.00"),
+            "company_base": Decimal("12000.00"),
+            "company_share_pct": company_text,
+            "company_share_amount": Decimal("600.00"),
+            "company_share_count": share_count,
+            "company_share_total": Decimal("600.00") * share_count,
+        },
+        "reconciliation": {
+            "team_member_payable_total": Decimal("10000.00"),
+            "unassigned_payable_total": Decimal("2000.00"),
+            "team_share_total": Decimal("1250.00"),
+            "company_share_total": Decimal("600.00") * share_count,
+            "aggregate_payable_total": aggregate_total,
+            "aggregate_rounding_diff": Decimal("0"),
+            "adjust_net_total": Decimal("0"),
+            "payable_total": payable_total,
+            "team_base_total": Decimal("10000.00"),
+            "unassigned_performance_total": Decimal("2000.00"),
+            "other_team_base": Decimal("0"),
+            "other_team_member_payable_total": Decimal("0"),
+            "other_team_share_total": Decimal("0"),
+            "other_team_company_share_total": Decimal("0"),
+            "other_team_aggregate_total": Decimal("0"),
+            "other_adjust_net_total": Decimal("0"),
+            "company_base": Decimal("12000.00"),
+        },
+        "totals": {},
+    }
+
+
+def _build_department(data: dict) -> bytes:
+    return report_export.build_workbook(
+        code="department-summary",
+        title="部门绩效工资汇总表",
+        filters="统计月份 2026-10",
+        rows=[],
+        summary=None,
+        buckets=None,
+        department=data,
+        template_version="V1.2",
+        operator_name="admin",
+        company_name="衍水集团",
+    )
+
+
+class Test部门汇总签字稿:
+    """签字稿少了团队分成/5% 块/未分配/零成员团队，合计就会小于应发。"""
+
+    def test_五块顺序完整(self):
+        text = _sheet_text(_build_department(_department_data()))
+        titles = [
+            "一、团队分成汇总",
+            "二、全公司分成（每位有聚合行",
+            "三、对账汇总",
+            "四、团队成员明细",
+            "五、未分配人员明细",
+        ]
+        positions = [text.index(title) for title in titles]
+        assert positions == sorted(positions), "签字稿块顺序错乱"
+        assert "财务复核" in text and "领导签字" in text
+
+    def test_零成员团队与未分配行存在(self):
+        text = _sheet_text(_build_department(_department_data()))
+        assert "王经理" in text
+        assert "赵未分配" in text
+        assert "无经理或上级非营销经理" in text
+
+    def test_全公司分成按计入次数累计(self):
+        """两位有聚合行的经理各计一次 5%；零成员团队不产生分成。"""
+        one = _department_data()
+        text = _sheet_text(_build_department(one))
+        assert text.count("全公司分成（每位有聚合行") == 1
+        assert "共 1 次" in text
+        assert "13850" in text
+
+        two = _department_data(second_has_aggregate=True)
+        text = _sheet_text(_build_department(two))
+        assert "共 2 次" in text
+        # 团队成员应付 10000 + 未分配 2000 + 聚合 2450
+        assert "14450" in text
+
+    def test_应发合计取对账口径(self):
+        text = _sheet_text(_build_department(_department_data()))
+        assert "应发合计" in text
+        # Excel 数值单元格读回为 int/float，金额断言只看数值本身
+        assert "13850" in text
+
+    def test_聚合行舍入差单列(self):
+        data = _department_data()
+        data["reconciliation"]["aggregate_rounding_diff"] = Decimal("-0.02")
+        text = _sheet_text(_build_department(data))
+        assert "聚合行舍入差" in text
+        assert "-0.02" in text
+
+    def test_比例标题参数化(self):
+        text = _sheet_text(_build_department(_department_data("20", "6")))
+        assert "团队分成（20%）" in text
+        assert "6%" in text
+        assert "12.5%" not in text
+        assert "5%" not in text.replace("6%", "")

db/init/init-dev.sql

@@ -23,6 +23,7 @@ DROP TABLE IF EXISTS `monthly_settlements`;
 DROP TABLE IF EXISTS `approval_steps`;
 DROP TABLE IF EXISTS `approval_orders`;
 DROP TABLE IF EXISTS `business_secondary_allocations`;
+DROP TABLE IF EXISTS `customer_ratings`;
 DROP TABLE IF EXISTS `system_settings`;
 DROP TABLE IF EXISTS `param_values`;
 DROP TABLE IF EXISTS `param_change_batches`;
@@ -455,7 +456,11 @@ INSERT INTO param_definitions (id, param_code, param_name, param_group, value_ty
 (17, 'approval.secondary_allocation.enabled', '二次分配审批开关', '审批开关', 'BOOL', NULL, 'NONE', NULL, '1', NULL, NULL, '0=二次分配方案提交即生效（系统自动通过全节点留痕，留痕不断链）；1=提交后进入财务复核→领导审核审批流。默认开启（澄清 #5 业务答复 2026-10-19），业务可关闭', 17),
 (18, 'approval.monthly_settlement.enabled', '月度结算审批开关', '审批开关', 'BOOL', NULL, 'NONE', NULL, '1', NULL, NULL, '月度结算审批链开关（④ 月结提交时消费）：0=结算生成即生效，1=走财务复核→领导审核审批流。默认开启（澄清 #7 业务答复 2026-10-19，月结涉及工资发放从严），业务可关闭', 18),
 (19, 'approval.adjustment.enabled', '调整单审批开关', '审批开关', 'BOOL', NULL, 'NONE', NULL, '0', NULL, NULL, '0=调整单提交即生效（系统自动通过留痕）；1=走财务复核→领导审核审批流。调整单是已锁定月份补发/扣减的唯一通道（澄清 #9：走同一审批链，默认值业务未明确，暂按直接生效，业务可开启）', 19),
-(20, 'manager.personal.included', '经理个人户计入聚合基数', '经理分成', 'BOOL', NULL, 'NONE', NULL, '0', NULL, NULL, '经理 12.5%+5% 聚合时是否计入经理本人名下经理个人户业绩（澄清 #12 业务答复 2026-10-19：作为参数配置、手动调整是否纳入）：0=不计入（默认，暂口径） 1=计入', 20);
+(20, 'manager.personal.included', '经理个人户计入聚合基数', '经理分成', 'BOOL', NULL, 'NONE', NULL, '0', NULL, NULL, '经理 12.5%+5% 聚合时是否计入经理本人名下经理个人户业绩（澄清 #12 业务答复 2026-10-19：作为参数配置、手动调整是否纳入）：0=不计入（默认，暂口径） 1=计入', 20),
+-- 预警规则参数（M4 ⑧ 工作台，澄清 #10「做成参数化规则便于调整」）
+(21, 'warning.enabled', '风险预警总开关', '预警规则', 'BOOL', NULL, 'NONE', NULL, '1', NULL, NULL, '工作台风险预警区块总开关：0=关闭（不扫描不展示） 1=开启（默认）', 21),
+(22, 'warning.receipt.overdue.days', '回款逾期天数阈值', '预警规则', 'INT', '天', 'NONE', NULL, '90', '1', NULL, '发货后超过该天数仍未回款的发货批次触发预警（澄清 #10 建议默认 90 天）', 22),
+(23, 'warning.approval.timeout.days', '审批超时天数阈值', '预警规则', 'INT', '天', 'NONE', NULL, '3', '1', NULL, '待审批单提交后超过该天数未处理触发预警（澄清 #10 建议默认 3 天）', 23);
 
 INSERT INTO param_values (id, param_id, dimension_value, effective_date, value_text, batch_id) VALUES
 (1, 1, 'salesperson', '2026-02-17', '10', 1),
@@ -481,7 +486,11 @@ INSERT INTO param_values (id, param_id, dimension_value, effective_date, value_t
 (20, 17, '', '2026-01-01', '1', 1),
 (21, 18, '', '2026-01-01', '1', 1),
 (22, 19, '', '2026-01-01', '0', 1),
-(25, 20, '', '2026-01-01', '0', 1);
+(25, 20, '', '2026-01-01', '0', 1),
+-- 预警规则参数生效值（M4 ⑧）
+(26, 21, '', '2026-10-19', '1', 1),
+(27, 22, '', '2026-10-19', '90', 1),
+(28, 23, '', '2026-10-19', '3', 1);
 
 -- ---------------------------------------------------------------------------
 -- 业务表（V5 迁移；业务编号自动生成，五项汇总冗余列由服务层事务内维护）
@@ -687,17 +696,50 @@ INSERT INTO customer_rating_grades (grade_name, min_score, max_score, sort_order
 ('C', 60, 74, 3, '合格'),
 ('D', 0, 59, 4, '待改进');
 
+-- ---------------------------------------------------------------------------
+-- 客户评级落库（V11 迁移；每客户一行，等级名为快照固化无外键）
+-- ---------------------------------------------------------------------------
+CREATE TABLE customer_ratings (
+    id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT,
+    customer_id BIGINT UNSIGNED NOT NULL COMMENT '客户ID（唯一：一客户一份当前评级）',
+    score_ship_amount NUMERIC(5, 1) NOT NULL COMMENT '发货额评分（0-20）' DEFAULT '0',
+    score_receipt_rate NUMERIC(5, 1) NOT NULL COMMENT '回款率评分（0-20）' DEFAULT '0',
+    score_profit_rate NUMERIC(5, 1) NOT NULL COMMENT '毛利率评分（0-20）' DEFAULT '0',
+    score_contract_cooperation NUMERIC(5, 1) NOT NULL COMMENT '合同履约配合能力评分（0-20）' DEFAULT '0',
+    score_site_construction NUMERIC(5, 1) NOT NULL COMMENT '现场规范施工能力评分（0-20）' DEFAULT '0',
+    total_score NUMERIC(5, 1) NOT NULL COMMENT '总分（服务端重算，五项之和 0-100）',
+    grade_name VARCHAR(32) COMMENT '评级等级（保存时按等级映射快照固化，无外键；未命中/等级表空为 NULL）',
+    remark VARCHAR(255) COMMENT '备注',
+    scorer_id BIGINT UNSIGNED COMMENT '评级操作人ID（账号删除后置空）',
+    scorer_name VARCHAR(64) NOT NULL COMMENT '评级操作人用户名（冗余固化）',
+    create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP,
+    update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    CONSTRAINT pk_customer_ratings PRIMARY KEY (id),
+    CONSTRAINT fk_customer_ratings_customer_id FOREIGN KEY(customer_id) REFERENCES customers (id) ON DELETE RESTRICT,
+    CONSTRAINT fk_customer_ratings_scorer_id FOREIGN KEY(scorer_id) REFERENCES users (id) ON DELETE SET NULL,
+    CONSTRAINT uk_customer_ratings_customer_id UNIQUE (customer_id)
+)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='客户评级表（每客户一行；等级名为快照固化无外键，删等级不伤已评级记录）' COLLATE utf8mb4_general_ci;
+
 -- ---------------------------------------------------------------------------
 -- 系统设置/二次分配/审批（V6 迁移；公司信息单行；分摊计算待澄清另批）
+-- V11 迁移：增加品牌标语/页脚/备案号/站点标题/站点图标与图片版本号
+-- （公司名称/logo/标语/页脚/备案号 + 站点信息，企业档案字段方案已废弃未发布）
 -- ---------------------------------------------------------------------------
 CREATE TABLE system_settings (
     id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT,
-    company_name VARCHAR(64) NOT NULL COMMENT '公司名称（登录页与导出页眉展示）',
+    company_name VARCHAR(64) NOT NULL COMMENT '公司名称（登录页/侧边栏/浏览器标题展示）',
-    logo_path VARCHAR(255) COMMENT 'logo 相对路径（文件存 uploads/logo/，null=未上传使用默认）',
+    logo_path VARCHAR(255) COMMENT '公司 logo 相对路径（文件存 uploads/logo/，null=未上传使用默认）',
+    logo_version INT NOT NULL COMMENT 'logo 版本号（每次上传 +1；图片 URL 用它破缓存——同扩展名覆盖时路径不变，update_time 也不变）' DEFAULT '0',
+    site_title VARCHAR(64) COMMENT '站点标题（浏览器标签页与侧边栏副标题；null=内置默认）',
+    brand_slogan VARCHAR(64) COMMENT '品牌标语（登录页与品牌预览；null=内置默认）',
+    footer_text VARCHAR(64) COMMENT '页脚版权文本（登录页；null=自动生成 © 公司名 · 内部系统）',
+    icp_no VARCHAR(32) COMMENT 'ICP 备案号（登录页页脚，空=不显示）',
+    favicon_path VARCHAR(255) COMMENT '站点图标相对路径（文件存 uploads/favicon/，null=跟随公司 logo / 内置 favicon.svg）',
+    favicon_version INT NOT NULL COMMENT '站点图标版本号（每次上传 +1；图片 URL 用它破缓存）' DEFAULT '0',
     create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP,
     update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
     CONSTRAINT pk_system_settings PRIMARY KEY (id)
-)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='系统设置表（公司信息，全系统单行）' COLLATE utf8mb4_general_ci;
+)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='系统设置表（公司信息与站点信息，全系统单行）' COLLATE utf8mb4_general_ci;
 
 CREATE TABLE approval_orders (
     id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT,
@@ -874,4 +916,4 @@ CREATE TABLE alembic_version (
     CONSTRAINT alembic_version_pkc PRIMARY KEY (version_num)
 )CHARSET=utf8mb4 ENGINE=InnoDB COLLATE utf8mb4_general_ci;
 
-INSERT INTO alembic_version (version_num) VALUES ('ba0217f5091b');
+INSERT INTO alembic_version (version_num) VALUES ('c4e2a86f9b13');

db/migration/V10__warning_rule_params.sql

@@ -0,0 +1,16 @@
+-- Running upgrade ba0217f5091b -> 90653814a421
+
+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 (21, 'warning.enabled', '风险预警总开关', '预警规则', 'BOOL', NULL, 'NONE', NULL, '1', NULL, NULL, '工作台风险预警区块总开关：0=关闭（不扫描不展示） 1=开启（默认）', 21, 1);
+
+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 (22, 'warning.receipt.overdue.days', '回款逾期天数阈值', '预警规则', 'INT', '天', 'NONE', NULL, '90', '1', NULL, '发货后超过该天数仍未回款的发货批次触发预警（澄清 #10 建议默认 90 天）', 22, 1);
+
+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 (23, 'warning.approval.timeout.days', '审批超时天数阈值', '预警规则', 'INT', '天', 'NONE', NULL, '3', '1', NULL, '待审批单提交后超过该天数未处理触发预警（澄清 #10 建议默认 3 天）', 23, 1);
+
+INSERT INTO param_values (id, param_id, dimension_value, effective_date, value_text, batch_id) VALUES (26, 21, '', '2026-10-19', '1', 1);
+
+INSERT INTO param_values (id, param_id, dimension_value, effective_date, value_text, batch_id) VALUES (27, 22, '', '2026-10-19', '90', 1);
+
+INSERT INTO param_values (id, param_id, dimension_value, effective_date, value_text, batch_id) VALUES (28, 23, '', '2026-10-19', '3', 1);
+
+UPDATE alembic_version SET version_num='90653814a421' WHERE alembic_version.version_num = 'ba0217f5091b';
+

db/migration/V11__add_customer_ratings_and_site_info.sql

@@ -0,0 +1,38 @@
+-- Running upgrade 90653814a421 -> c4e2a86f9b13
+
+CREATE TABLE customer_ratings (
+    id BIGINT UNSIGNED NOT NULL COMMENT '主键ID' AUTO_INCREMENT,
+    customer_id BIGINT UNSIGNED NOT NULL COMMENT '客户ID（唯一：一客户一份当前评级）',
+    score_ship_amount NUMERIC(5, 1) NOT NULL COMMENT '发货额评分（0-20）' DEFAULT '0',
+    score_receipt_rate NUMERIC(5, 1) NOT NULL COMMENT '回款率评分（0-20）' DEFAULT '0',
+    score_profit_rate NUMERIC(5, 1) NOT NULL COMMENT '毛利率评分（0-20）' DEFAULT '0',
+    score_contract_cooperation NUMERIC(5, 1) NOT NULL COMMENT '合同履约配合能力评分（0-20）' DEFAULT '0',
+    score_site_construction NUMERIC(5, 1) NOT NULL COMMENT '现场规范施工能力评分（0-20）' DEFAULT '0',
+    total_score NUMERIC(5, 1) NOT NULL COMMENT '总分（服务端重算，五项之和 0-100）',
+    grade_name VARCHAR(32) COMMENT '评级等级（保存时按等级映射快照固化，无外键；未命中/等级表空为 NULL）',
+    remark VARCHAR(255) COMMENT '备注',
+    scorer_id BIGINT UNSIGNED COMMENT '评级操作人ID（账号删除后置空）',
+    scorer_name VARCHAR(64) NOT NULL COMMENT '评级操作人用户名（冗余固化）',
+    create_time DATETIME NOT NULL COMMENT '创建时间' DEFAULT CURRENT_TIMESTAMP,
+    update_time DATETIME NOT NULL COMMENT '更新时间' DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    CONSTRAINT pk_customer_ratings PRIMARY KEY (id),
+    CONSTRAINT fk_customer_ratings_customer_id FOREIGN KEY(customer_id) REFERENCES customers (id) ON DELETE RESTRICT,
+    CONSTRAINT fk_customer_ratings_scorer_id FOREIGN KEY(scorer_id) REFERENCES users (id) ON DELETE SET NULL,
+    CONSTRAINT uk_customer_ratings_customer_id UNIQUE (customer_id)
+)CHARSET=utf8mb4 ENGINE=InnoDB COMMENT='客户评级表（每客户一行；等级名为快照固化无外键，删等级不伤已评级记录）' COLLATE utf8mb4_general_ci;
+
+ALTER TABLE system_settings ADD COLUMN site_title VARCHAR(64) COMMENT '站点标题（浏览器标签页与侧边栏副标题；null=内置默认）';
+
+ALTER TABLE system_settings ADD COLUMN brand_slogan VARCHAR(64) COMMENT '品牌标语（登录页与品牌预览；null=内置默认）';
+
+ALTER TABLE system_settings ADD COLUMN footer_text VARCHAR(64) COMMENT '页脚版权文本（登录页；null=自动生成 © 公司名 · 内部系统）';
+
+ALTER TABLE system_settings ADD COLUMN icp_no VARCHAR(32) COMMENT 'ICP 备案号（登录页页脚，空=不显示）';
+
+ALTER TABLE system_settings ADD COLUMN favicon_path VARCHAR(255) COMMENT '站点图标相对路径（文件存 uploads/favicon/，null=使用内置 favicon.svg）';
+
+ALTER TABLE system_settings ADD COLUMN logo_version INT NOT NULL COMMENT 'logo 版本号（每次上传 +1；图片 URL 用它破缓存——同扩展名覆盖时路径不变，update_time 也不变）' DEFAULT '0';
+
+ALTER TABLE system_settings ADD COLUMN favicon_version INT NOT NULL COMMENT '站点图标版本号（每次上传 +1；图片 URL 用它破缓存）' DEFAULT '0';
+
+UPDATE alembic_version SET version_num='c4e2a86f9b13' WHERE alembic_version.version_num = '90653814a421';

docs/T+字段映射草案_v0.1_2026-10-20.md

@@ -0,0 +1,289 @@
+# T+ 12.3 字段映射草案（v0.1，2026-10-20）
+
+> 本文仅记录字段级事实与页面索引，不复制厂商文档正文。
+> 基线：`docs/T+对接数据需求清单_v1.4_2026-10-19.xlsx`（75 项）+ v1.3 IT 18 项 + 《T+12.3数据字典》。
+
+## 0. 结论摘要
+
+- 覆盖：清单 **75/75** 项均已给出 T+ 侧候选字段与系统目标列；
+- 状态分布：候选待确认 42 / 字典明确 23 / 未检出 9 / 需 IT 1；
+- 数据字典无法让 IT 18 项中的任何一项完全闭环；但 9 项可改写为「候选字段选择题」，6 项部分可答，2 项纯 IT，1 项转业务。
+- 收敛后：**13 项 IT 待确认 + 1 组业务裁决**（见第 12 节）。
+- 关键缺口：人员工号/入职日期/试用期无字段、客户 status 缺失、回款 payment_method/confirm_status 待补、明细行无显式行号、无源端更新时间与负向事件模型。
+
+## 1. 编制说明与证据等级
+
+| 标记 | 含义 |
+| --- | --- |
+| `D` | 字典明确 |
+| `D?` | 候选待确认 |
+| `IT` | 需 IT |
+| `B` | 需业务 |
+| `S` | 系统自维护 |
+| `N` | 未检出 |
+
+- `D` 仅用于字段存在、类型明确且语义直接匹配的项；涉及「取哪个字段 / 业务口径」一律标 `D?` 或 `IT`。
+- 字典来源为 T+ 12.3 SchemaDoc；同一字段可能标注 `T+12.1/12.2/12.3` 版本，映射按 12.3 可用为准。
+
+## 2. 公共字段与同步元数据
+
+| 序号 | 数据项 | T+ 表.字段（字典） | T+ 类型/长度 | 枚举/取值 | 系统目标表.字段 | 转换/清洗规则 | 必要性 | 确认状态 | 来源/字典页 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | T+ 原始单据号 / 档案编码 | 各表 code（人员/存货/客户/订单/出库/收付款单均有） | nvarchar(30~64) | — | personnel/products/customers/businesses/shipments/receipts.source_no | TRIM；作废重开是否换号待 IT（#4） | 必须 | D? | AA_Person.code、AA_Inventory.code、AA_Partner.code、SA_SaleOrder.code、SA_SaleDelivery.code、ARAP_ReceivePayment.code |
+| 2 | T+ 系统内部标识 | 各表 id（整型主键） | int(4) | — | 六表 t_plus_id | int → 字符串存储；辅助对账/改名追溯 | 建议 | D | 各表 id（主键） |
+
+系统侧六张主表已预留 `source_no / t_plus_id / sync_batch_no / synced_at`；`source_no` 当前为普通索引，IT 确认幂等键后升级唯一约束。
+
+## 3. 人员档案
+
+人员主档；隶属关系需经部门树/部门负责人推断，T+ 无直属上级字段。
+
+| 序号 | 数据项 | T+ 表.字段（字典） | T+ 类型/长度 | 枚举/取值 | 系统目标表.字段 | 转换/清洗规则 | 必要性 | 确认状态 | 来源/字典页 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | 人员唯一编码（工号）★ | AA_Person.code | nvarchar(32) | — | personnel.source_no（建议补 personnel_code） | TRIM；编码优先、姓名辅助核对；是否即工号待 IT（#19） | 必须 | D? | AA_Person.code（编号） |
+| 2 | 姓名 | AA_Person.name | nvarchar(200) | — | personnel.personnel_name | TRIM；仅辅助核对，不作唯一键 | 必须 | D | AA_Person.name（名称） |
+| 3 | 在职状态 | AA_Person.disabled | tinyint(1) | 0 启用 / 1 停用（候选） | personnel.status（1 在职 / 0 离职） | disabled=1 → 0；无离职日期字段，离职时间需 IT 确认 | 必须 | D? | AA_Person.disabled（停用） |
+| 4 | 是否试用期 | 未检出 | — | — | personnel.is_probation | T+ 人员档案无试用期字段；系统内人工维护或按入职日期规则推导 | 必须 | N | AA_Person 全表检索无 probation/试用 字段 |
+| 5 | 入职日期 | 未检出（仅 madeDate 制单日期、birthday 出生日期） | — | — | personnel.hire_date | T+ 无入职日期字段；确认是否有自定义项承载，否则人工维护 | 必须 | N | AA_Person 全表检索无 hire/entry/入职 字段 |
+| 6 | 联系电话 | AA_Person.mobilePhoneNo / officePhoneNo | nvarchar(20) / nvarchar(100) | — | personnel.phone | 优先 mobilePhoneNo，空则 officePhoneNo；日志脱敏 | 建议 | D | AA_Person.mobilePhoneNo（手机）、officePhoneNo（办公电话） |
+| 7 | 业务员 ↔ 营销经理隶属关系 | AA_Person.iddepartment → AA_Department.idparent / iddirector | int(4) | — | personnel.manager_id | T+ 人员档案无直属上级字段；可经部门树/部门负责人推断，规则待确认；否则系统人工指定 | 必须 | D? | AA_Person.iddepartment（部门id）；AA_Department.idparent（上级id）、iddirector（部门负责人） |
+| 8 | 人员负责区域 / 产品辐射范围 | 未检出（可用 priuserdefnvc* 自定义项承载，需 IT 确认） | — | — | personnel_regions.region_name | 无专门字段则系统内人工维护 | 建议 | N | AA_Person 无区域/辐射范围字段 |
+| 9 | 银行账户名 / 账号 / 开户行 | 未检出（AA_Partner 有银行账号字段，人员档案无） | — | — | 暂不落库 | 一期不采集；如后续代发工资再扩展 | 可选 | N | AA_Person 无银行账户字段 |
+
+## 4. 产品档案
+
+产品主档不含库存量与售价，数量取现存量表、价格取价目表/订单明细。
+
+| 序号 | 数据项 | T+ 表.字段（字典） | T+ 类型/长度 | 枚举/取值 | 系统目标表.字段 | 转换/清洗规则 | 必要性 | 确认状态 | 来源/字典页 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | 产品名称 | AA_Inventory.name | nvarchar(200) | — | products.product_name | TRIM；与规格型号组成系统组合唯一键 | 必须 | D | AA_Inventory.name（名称） |
+| 2 | 规格型号 | AA_Inventory.specification | nvarchar(200) | — | products.spec_model | 空值归一为空串 | 必须 | D | AA_Inventory.specification（规格型号） |
+| 3 | 计量单位 | AA_Inventory.idunit → 计量单位表 | int(4) | — | products.unit | 按 idunit join 单位表取名称；单位表名待索引确认 | 建议 | D? | AA_Inventory.idunit（计量单位id）、idunitgroup |
+| 4 | 数量 | ST_CurrentStock.baseQuantity（现存量） | decimal(13) | — | products.stock_quantity | 按存货+仓库汇总；语义（现存量/在途/累计销量）待 IT（#12） | 必须 | D? | ST_CurrentStock.baseQuantity（主计量数量）；AA_Inventory 无库存量字段 |
+| 5 | 销售单价 | AA_InventoryPrice（零售价/批发价）、AA_InventoryUnitPrice.retailPrice；订单明细实际成交价 | decimal(13~17) / nvarchar(1000) 公式 | — | products.sale_price | 产品档案参考价取价目表；绩效以订单/发货明细实际单价为准 | 必须 | D? | AA_InventoryPrice、AA_InventoryUnitPrice；AA_Inventory 无销售单价字段 |
+| 6 | 产品分类（类目） | AA_Inventory.idinventoryclass → AA_InventoryClass.name | int(4) | — | products.product_category | T+ 分类仅辅助判定市政水利/轨交；系统分类人工维护不覆盖 | 必须 | D? | AA_Inventory.idinventoryclass（存货分类id）、AA_InventoryClass.name |
+| 7 | 计量单位换算关系（如存在） | AA_Inventory_MultiUnit / AA_InventoryUnitPrice.rateOfExchange | decimal(13) | — | 暂不实现（系统单单位存储） | 如业务有多单位换算需求，另行设计 | 可选 | D? | AA_Inventory_MultiUnit、AA_InventoryUnitPrice.rateOfExchange（换算率） |
+
+## 5. 业务单据（销售订单）
+
+成本额在订单明细仅有最新成本，出库明细才有成本金额；销售额需按数量×单价计算。
+
+| 序号 | 数据项 | T+ 表.字段（字典） | T+ 类型/长度 | 枚举/取值 | 系统目标表.字段 | 转换/清洗规则 | 必要性 | 确认状态 | 来源/字典页 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | 订单单号 | SA_SaleOrder.code | nvarchar(30) | — | businesses.source_no | TRIM；不得写入内部 business_no | 必须 | D | SA_SaleOrder.code（编号） |
+| 2 | 业务（订单）日期 | SA_SaleOrder.voucherdate | datetime(8) | — | businesses.business_date | 截断为 DATE | 必须 | D | SA_SaleOrder.voucherdate（单据日期） |
+| 3 | 客户标识 | SA_SaleOrder.idcustomer → AA_Partner.code | int(4) | — | businesses.customer_id | 按客户编码解析；回退公司名称+负责人 | 必须 | D? | SA_SaleOrder.idcustomer（客户id）、idsettlecustomer（结算客户id） |
+| 4 | 负责营销人员 | SA_SaleOrder.idclerk → AA_Person.code | int(4) | — | businesses.owner_personnel_id | 按人员编码解析；新插入写 T+ 负责人、更新是否覆盖人工归属待裁决 | 必须 | D? | SA_SaleOrder.idclerk（业务员id） |
+| 5 | 协助营销人员 | 未检出独立协助人字段 | — | — | businesses.assistant_personnel_id | 业务已回馈 T+ 合同只挂单一负责人；协助人系统内记录 | 建议 | N | SA_SaleOrder 无 assist/协助 字段 |
+| 6 | 特殊业务标记 | SA_SaleOrder.idbusinesstype → 业务类型表 | int(4) | 业务类型枚举待字典/IT 提供 | businesses.is_special | 业务类型是否等同特殊业务待确认；无则人工标记 | 必须 | D? | SA_SaleOrder.idbusinesstype（业务类型id） |
+| 7 | 明细行 · 产品名称 + 规格 | SA_SaleOrder_b.idinventory → AA_Inventory.name/specification | int(4) | — | business_items.product_name / spec_model | 冗余固化名称与规格；未建档产品允许自由录入 | 必须 | D | SA_SaleOrder_b.idinventory（存货id） |
+| 8 | 明细行 · 数量 | SA_SaleOrder_b.quantity | decimal(13) | — | business_items.quantity | 主计量数量；需 >0 校验 | 必须 | D | SA_SaleOrder_b.quantity（数量）、baseQuantity（主计量数量） |
+| 9 | 明细行 · 销售单价 | SA_SaleOrder_b.price / taxPrice | decimal(13) | — | business_items.sale_price | price 为不含税单价、taxPrice 为含税单价；取哪个待确认 | 必须 | D? | SA_SaleOrder_b.price（单价）、taxPrice（含税单价） |
+| 10 | 明细行 · 销售额 | SA_SaleOrder_b 无「销售额」字段；由数量×单价计算，或 taxAmount−tax | decimal(13) | — | business_items.sale_amount | 系统按数量×单价固化；T+ 用于对账 | 必须 | D? | SA_SaleOrder_b.quantity、price、taxAmount、tax |
+| 11 | 明细行 · 成本额 ★ | SA_SaleOrder_b.LatestCost（最新成本）；SA_SaleDelivery_b.costPrice/costAmount | decimal(13) | — | business_items.cost_amount | 取订单最新成本还是出库成本、成本类型/时点待 IT（#1） | 必须 | D? | SA_SaleOrder_b.LatestCost；SA_SaleDelivery_b.costPrice/costAmount/CostPriceGetType |
+| 12 | 项目 / 工程编号或名称（如存在） | SA_SaleOrder.idproject → 项目表 | int(4) | — | 建议预留 project_code（当前不落库） | 按项目查询与报表归集；是否建列待业务 | 可选 | D? | SA_SaleOrder.idproject（项目id）、SA_SaleOrder_b.idproject |
+| 13 | 服务类 / 维修类及其他收入单据（如存在） | 未检索到服务/维修类独立单据表 | — | — | 暂人工录入 | 业务规则未定前不纳入自动同步 | 可选 | N | SA_* 表索引未发现服务/维修类主表 |
+
+## 6. 发货单据（销售出库/发货）
+
+发货日期有四个候选字段；运费未在发货单据检出。
+
+| 序号 | 数据项 | T+ 表.字段（字典） | T+ 类型/长度 | 枚举/取值 | 系统目标表.字段 | 转换/清洗规则 | 必要性 | 确认状态 | 来源/字典页 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | 发货单号 | SA_SaleDelivery.code | nvarchar(30) | — | shipments.source_no | TRIM；不得写入内部 shipment_no | 必须 | D | SA_SaleDelivery.code（编号） |
+| 2 | 发货日期 ★ | SA_SaleDelivery.voucherdate / SendDate / deliveryDate / auditeddate | datetime(8) | — | shipments.ship_date | 四个日期候选：单据日期/送货日期(T+12.3)/交货日期/审核日期；取哪个待 IT（#2） | 必须 | D? | SA_SaleDelivery.voucherdate、SendDate、deliveryDate、auditeddate |
+| 3 | 关联订单号 | SA_SaleDelivery.SourceVoucherCode / idsourcevouchertype；明细 saleOrderCode/saleOrderId | nvarchar(50) / int(4) | — | shipments.business_id | 按订单号解析；主关联路径待 IT（#5） | 必须 | D? | SA_SaleDelivery.SourceVoucherCode、SA_SaleDelivery_b.saleOrderCode/saleOrderId/saleOrderDetailId |
+| 4 | 运费金额 | 未检出运费字段（明细有 origExpenseAmount 费用分摊金额） | decimal(13) | — | shipments.freight_amount | T+ 运费可能在费用单/其他单据，需 IT 确认；系统暂人工 | 必须 | N | SA_SaleDelivery/SA_SaleDelivery_b 无 freight/运费字段 |
+| 5 | 发货总金额 | SA_SaleDelivery.amount / taxAmount | decimal(13) | — | shipments.total_amount | 系统按明细汇总，不直写；T+ 金额用于对账 | 必须 | D | SA_SaleDelivery.amount（金额）、taxAmount（含税金额） |
+| 6 | 明细行 · 产品/规格/数量/单价/行金额 | SA_SaleDelivery_b.idinventory / quantity / price / taxPrice / taxAmount | decimal(13) | — | shipment_items.product_name/spec_model/quantity/sale_price/amount | 行金额由系统按数量×单价固化；T+ 用于对账 | 必须 | D | SA_SaleDelivery_b.quantity、price、taxPrice、taxAmount |
+| 7 | 发货单状态 | SA_SaleDelivery.voucherState / isCancel / auditeddate | int(4) / tinyint(1) | 单据状态枚举待 IT 提供 | 不落库（v1.4 统一） | 仅推已生效单据；状态随行供同步校验 | 必须 | D | SA_SaleDelivery.voucherState（单据状态）、isCancel（状态） |
+| 8 | 承运商 / 物流单号 | SA_SaleDelivery.deliveryMode（运输方式 id） | int(4) | 运输方式枚举表待确认 | 暂不落库 | 承运商/物流单号无独立字段；如需建列再扩展 | 可选 | D? | SA_SaleDelivery.deliveryMode（运输方式） |
+
+## 7. 回款单据（收款/核销）
+
+到账日期无银行到账日字段；收款方式取结算方式表；确认/核销状态字段存在但枚举待 IT。
+
+| 序号 | 数据项 | T+ 表.字段（字典） | T+ 类型/长度 | 枚举/取值 | 系统目标表.字段 | 转换/清洗规则 | 必要性 | 确认状态 | 来源/字典页 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | 回款单号 | ARAP_ReceivePayment.code | nvarchar(30) | — | receipts.source_no | TRIM；不得写入内部 receipt_batch_no | 必须 | D | ARAP_ReceivePayment.code（编号） |
+| 2 | 到账日期 ★ | ARAP_ReceivePayment.voucherDate / auditedDate / createdTime | datetime(8) | — | receipts.receipt_date | 无银行到账日字段；取单据日期/审核日期/创建时间哪个待 IT（#3） | 必须 | D? | ARAP_ReceivePayment.voucherDate、auditedDate、createdTime |
+| 3 | 回款金额 | ARAP_ReceivePayment.amount（本币）/ origAmount（原币） | decimal(13) | — | receipts.amount | 取本币金额；一期禁负数，红字规则待 #8 | 必须 | D | ARAP_ReceivePayment.amount、origAmount |
+| 4 | 关联订单号 | ARAP_ReceivePayment.SaleOrderCode/SaleOrderID；明细 saleordercode/saleorderid/sourceordercode | nvarchar(50) / int(4) | — | receipts.business_id | 回款↔订单按订单号解析；回款↔发货批次系统人工指定 | 必须 | D? | ARAP_ReceivePayment.SaleOrderCode/SaleOrderID；ARAP_ReceivePayment_b.saleordercode/sourceordercode |
+| 5 | 收款方式 | ARAP_ReceivePayment.IdSettleStyle → AA_SettleStyle.code/name | int(4) | 结算方式枚举表（AA_SettleStyle：code/name/停用） | receipts.payment_method（待补列） | 枚举映射；完整枚举清单需 IT 提供 | 必须 | D? | ARAP_ReceivePayment.IdSettleStyle；AA_SettleStyle |
+| 6 | 以物抵顶物说明 | 收款方式（以物抵顶枚举值）+ ARAP_ReceivePayment.memo | int(4) / nvarchar(200) | 以物抵顶对应结算方式代码待 IT 提供 | receipts.is_barter / remark | 按结算方式识别；抵顶物说明暂入备注 | 建议 | D? | ARAP_ReceivePayment.IdSettleStyle、memo |
+| 7 | 回款确认 / 核销状态 | ARAP_ReceivePayment.cancelState / voucherstate / auditedDate | int(4) / datetime(8) | 核销/单据状态枚举待 IT 提供 | receipts.confirm_status（待补列） | 字段存在；哪个可作为人工确认依据待 IT（#16） | 必须 | D? | ARAP_ReceivePayment.cancelState（核销状态）、voucherstate（单据状态） |
+| 8 | 银行流水号 / 回单参考号 | 未检出银行流水号/回单号字段（MultiSettle.documentCode 为票据号） | — | — | 建议预留 bank_serial_no | 需 IT 确认是否有对应字段 | 建议 | N | ARAP_ReceivePayment/ARAP_ReceivePayment_MultiSettle 仅票据号 |
+| 9 | 票据信息（票号 / 到期日 / 贴现说明） | ARAP_ReceivePayment_MultiSettle.documentCode / amount / idsettlestyle | nvarchar(30) / decimal(13) | 票据类型枚举待 IT | 系统暂以备注承载 | 无票据到期日字段；承兑到期核销信息需 IT 确认 | 建议 | D? | ARAP_ReceivePayment_MultiSettle.documentCode（票据号） |
+| 10 | 币种 / 汇率（如存在外币业务） | ARAP_ReceivePayment.idcurrency / exchangeRate | int(4) / decimal(13) | 币种表待索引 | 一期不落库（人民币记账） | 如存在外币业务再扩展 | 可选 | D | ARAP_ReceivePayment.idcurrency、exchangeRate |
+
+## 8. 客户档案
+
+采用往来单位表 AA_Partner；客户编码/停用字段存在，status 列需系统补。
+
+| 序号 | 数据项 | T+ 表.字段（字典） | T+ 类型/长度 | 枚举/取值 | 系统目标表.字段 | 转换/清洗规则 | 必要性 | 确认状态 | 来源/字典页 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | 公司名称 | AA_Partner.name | nvarchar(200) | — | customers.company_name | TRIM；与负责人组成系统唯一键 | 必须 | D | AA_Partner.name（名称） |
+| 2 | 负责人姓名 | AA_Partner.Contact（联系人）/ representative（法人代表） | nvarchar(50) | — | customers.owner_name | 「负责人」对应 Contact 还是 representative 待 IT/业务确认 | 必须 | D? | AA_Partner.Contact、representative |
+| 3 | 客户编码 / 状态 / 启用停用时间 | AA_Partner.code / disabled / madeDate / updated | nvarchar(32) / tinyint(1) | disabled 0 启用 / 1 停用（候选） | customers.source_no / status（待补列） | 启停时间无独立列，可用 updated 近似（需 IT 确认） | 必须 | D? | AA_Partner.code、disabled、madeDate、updated |
+| 4 | 联系人 / 电话 / 地址 / 行业 | AA_Partner.Contact / TelephoneNo / MobilePhone / CustomerAddress / iddistrict | nvarchar(30~200) | — | customers.contact_person / contact_phone / address / industry | 行业无直接字段；地区按 iddistrict 关联 | 可选 | D? | AA_Partner.Contact、TelephoneNo、MobilePhone、CustomerAddress、iddistrict |
+| 5 | 开票信息（税号 / 开票名称 / 开票地址电话） | AA_Partner.taxRegcode / name / CustomerAddress | nvarchar(50~200) | — | 系统暂仅供展示，不落库 | 税号存在；开票地址电话需 IT 确认字段 | 可选 | D? | AA_Partner.taxRegcode（纳税号）、CustomerAddress |
+
+## 9. 同步完整性与补充字段
+
+时间戳与负向字段部分存在；无统一事件表、无明细行号、无手续费字段。
+
+| 序号 | 数据项 | T+ 表.字段（字典） | T+ 类型/长度 | 枚举/取值 | 系统目标表.字段 | 转换/清洗规则 | 必要性 | 确认状态 | 来源/字典页 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | 数据最后更新时间 / 单据创建时间 / 修改时间 | 各表 createdTime/createdtime、updated、madeDate、auditedDate、ts | datetime(8) / timestamp(8) | — | 建议新增 source_created_at / source_updated_at（当前无） | 本地 update_time 不可作为源端水位；增量水位字段待 IT（#9） | 必须 | D? | 各表 updated/createdTime；ts（分布时间戳） |
+| 2 | 变更类型 / 单据事件：新增、修改、删除、作废、红冲、退货、冲销 | 各表 isCancel（状态）、isCounteractDelivery（冲抵销货）、returnQuntity（退货数量） | int(4) / tinyint(1) / decimal(13) | 状态/事件枚举待 IT 提供 | 建议事件表（当前无） | 无统一变更事件表；负向事实需事件模型，规则待 #8 | 必须 | D? | SA_SaleOrder.isCancel、SA_SaleDelivery.isCounteractDelivery、SA_SaleDelivery_b.returnQuntity |
+| 3 | 单据状态 / 财务审核状态 / 状态变更时间 | voucherState / auditedDate / auditor / auditorid | int(4) / datetime(8) / nvarchar(50) | 单据状态枚举待 IT | 不落库（仅同步校验） | 仅推已生效单据；状态随行校验 | 必须 | D | SA_SaleOrder/SA_SaleDelivery/ARAP_ReceivePayment 的 voucherState、auditedDate |
+| 4 | 明细行行号 / 行状态 / 行级变更事件 | 明细表主键 ID、code（明细编号）；无显式行号字段 | int(4) / nvarchar(30) | — | 建议补 source_line_no / source_item_id | 确认 code 是否即行号；否则用 T+ 明细 ID 作行级幂等键（待 IT） | 必须 | D? | SA_SaleOrder_b.id/code、SA_SaleDelivery_b.ID/code、ARAP_ReceivePayment_b.id/detailCode |
+| 5 | 税率 / 税额 / 价税合计 / 折扣或折让 | 明细表 taxRate、tax、taxAmount、origTaxAmount、discount、discountRate、discountAmount | decimal(13) | — | 待业务 #20 答复后决定是否建列 | 字段齐全；金额是否含税、折扣关联方式待业务 | 必须 | D? | SA_SaleOrder_b/SA_SaleDelivery_b 税额与折扣字段 |
+| 6 | 发货客户 / 收货人 / 收货地址 / 联系电话 | SA_SaleDelivery.idcustomer / address / contactPhone / idSendPerson / idConsignor | int(4) / nvarchar(100~200) | — | 建议预留（当前无列） | 用于核对发货对象与代发情形 | 必须 | D | SA_SaleDelivery.idcustomer、address、contactPhone、idSendPerson、idConsignor |
+| 7 | 发货业务员 / 发货组织 / 仓库 | SA_SaleDelivery.idclerk / iddepartment / idwarehouse | int(4) | — | 建议预留（当前无列） | 识别代发、调拨与多组织差异 | 必须 | D | SA_SaleDelivery.idclerk、iddepartment、idwarehouse |
+| 8 | 发货退回 / 红字发货 / 退回数量 / 退回金额 / 原发货单关联 | SA_SaleDelivery.isCounteractDelivery、_b.returnQuntity/returnQuntity2/backSentQuantity、sourceVoucher* | tinyint(1) / decimal(13) / nvarchar(50) | 冲抵/退货枚举待 IT | 待业务 #21 答复后决定是否建列 | 原单关联字段存在；是否冲减绩效待业务 | 必须 | D? | SA_SaleDelivery.isCounteractDelivery、SA_SaleDelivery_b.returnQuntity、backSentQuantity |
+| 9 | 收款客户 / 经手人 / 财务审核状态 | ARAP_ReceivePayment.idpartner / idHandler / auditor / voucherstate | int(4) / nvarchar(50) / int(4) | — | 建议预留（当前无列） | 核对实际付款主体与经办责任 | 必须 | D | ARAP_ReceivePayment.idpartner、idHandler、auditor、voucherstate |
+| 10 | 收款分配明细 / 分配金额 / 未分配金额 / 分配对象 | ARAP_ReceivePayment_b（源单/订单/金额/未结算）、ARAP_StrikeBalance（核销） | decimal(13) / int(4) | — | 人工指定发货批次的辅助参考 | 分配关系仅参考；系统仍人工指定（对照表 #18） | 必须 | D? | ARAP_ReceivePayment_b.saleordercode/amount/origNoSettleAmount；ARAP_StrikeBalance |
+| 11 | 预收款 / 保证金 / 代收款 / 折让 / 抵扣 | ARAP_ReceivePayment.paymentAmount/origPaymentAmount（预收/预付）、overPayment（超收转预收）、allowances（折让） | decimal(13) | — | 待业务 #22 答复后决定是否建列 | 字段存在；是否计入绩效回款待业务 | 必须 | D? | ARAP_ReceivePayment.paymentAmount、overPayment、allowances |
+| 12 | 手续费 / 交易费用 / 收款净额 | 未检出手续费/交易费用字段 | — | — | 待业务 #23 答复后决定 | 需 IT 确认手续费是否在其他单据/字段 | 必须 | N | ARAP_ReceivePayment 无 fee/charge 字段 |
+| 13 | 红字收款 / 收款作废 / 收款退回 / 冲销及原单关联 | ARAP_ReceivePayment.voucherstate / isReceiveFlag；ARAP_StrikeBalance 冲销 | int(4) / tinyint(1) | 作废/红字状态枚举待 IT | 待业务 #24 答复后决定 | 无红字收款专用字段；负向事实需事件模型 | 必须 | D? | ARAP_ReceivePayment.voucherstate、isReceiveFlag；ARAP_StrikeBalance |
+| 14 | 客户编码 / 客户状态 / 启用停用时间 | AA_Partner.code / disabled | nvarchar(32) / tinyint(1) | disabled 0 启用 / 1 停用 | customers.source_no / status（待补列） | 同六-3；客户编码唯一性待 IT | 必须 | D | AA_Partner.code、disabled |
+| 15 | 客户分类 / 渠道 / 区域 / 所属组织 | AA_Partner.idpartnerclass / customerType / iddistrict / idMarketingOrgan | int(4) | 分类/客商类型枚举待 IT | customers.customer_type（不覆盖）；渠道无列 | 系统客户分类人工维护；渠道/区域作备考 | 必须 | D? | AA_Partner.idpartnerclass、customerType、iddistrict、idMarketingOrgan |
+| 16 | 客户名称变更 / 编码停用合并前后的对应关系 | AA_Partner.code（终身不变）+ updated；无变更历史表（待确认） | nvarchar(32) | — | 靠 source_no 追溯同一主体 | 改名/换负责人/合并靠 code 串同一主体；变更历史需 IT 确认 | 必须 | D? | AA_Partner.code、updated、HasEverChanged |
+| 17 | 人员部门 / 岗位 / 调岗时间 / 离职和组织变更时间 | AA_Person.iddepartment / position / updated；调岗历史表待确认 | int(4) / datetime(8) | — | 不落库（备考/排查） | 字段部分存在；调岗/离职时间需 IT 确认 | 必须 | D? | AA_Person.iddepartment、position、updated |
+| 18 | 产品编码 / 产品状态 / 启用停用时间 | AA_Inventory.code / disabled / madeDate | nvarchar(32) / tinyint(1) | disabled 0 启用 / 1 停用 | products.source_no / status | 稳定匹配；停用后历史明细仍可回溯 | 必须 | D | AA_Inventory.code、disabled、MadeRecordDate |
+| 19 | 字典和枚举取值范围 / 编码与名称对照说明 | 枚举表：AA_SettleStyle、业务类型表、状态字典（需随数据导出） | — | 枚举字典随数据提供 | 同步映射表 | 不能只给代码；需编码与名称对照 | 必须 | D? | AA_SettleStyle、AA_BusinessType 等枚举表 |
+| 20 | 对账汇总信息 / 数据记录数 / 数量合计 / 金额合计 / 抽取时间 | 由 IT 提供抽取汇总（接口/视图层） | — | — | 同步日志/对账表 | 记录明细条数、金额合计、抽取时间 | 必须 | IT | 字典不提供；需对接方式确定 |
+| 21 | 单据历史版本 / 修改留痕（如 T+ 提供） | 未检索到统一单据历史版本表（待 IT 确认） | — | — | 系统同步快照可比对 | 无此数据不阻塞 | 可选 | D? | 表索引未见 history 类表 |
+
+## 10. 跨表关联与键
+
+| 关系 | T+ 字段（字典） | 系统目标 | 状态 |
+| --- | --- | --- | --- |
+| 人员唯一键 | AA_Person.code | personnel.source_no（建议补 personnel_code） | D? |
+| 客户唯一键 | AA_Partner.code；名称+联系人 | customers.source_no；company_name+owner_name | D? |
+| 订单→发货 | SA_SaleDelivery.SourceVoucherCode / _b.saleOrderCode/saleOrderId | shipments.business_id | D? |
+| 订单/发货→回款 | ARAP_ReceivePayment.SaleOrderCode/SaleOrderID；_b.saleordercode | receipts.business_id | D? |
+| 回款→发货批次 | 系统人工指定（对照表 #18） | receipts.shipment_id | S |
+| 明细行幂等 | 明细表 ID/code；无显式行号 | 建议补 source_line_no | D? |
+
+## 11. 枚举与状态
+
+| 枚举 | T+ 来源 | 备注 |
+| --- | --- | --- |
+| 收款/结算方式 | AA_SettleStyle（code/name/disabled） | 完整枚举需随数据导出 |
+| 单据状态 | 各单据 voucherState / isCancel | 仅同步校验，不落库 |
+| 核销状态 | ARAP_ReceivePayment.cancelState | 含义待 IT |
+| 业务类型 | SA_SaleOrder.idbusinesstype → 业务类型表 | 是否等同特殊业务待确认 |
+| 产品分类 | AA_InventoryClass | 仅辅助系统分类人工维护 |
+
+## 12. 系统侧目标表缺口
+
+| 缺口 | 说明 | 建议 |
+| --- | --- | --- |
+| `personnel.personnel_code` | T+ 工号/编码是否即 `source_no` 未定 | 若不等则补唯一列 |
+| `customers.status` / 启停时间 | T+ 有 disabled，系统无列 | 补 status 与停用时间 |
+| `receipts.payment_method` / `confirm_status` | T+ 有结算方式与核销状态 | 补两列并接枚举 |
+| `source_created_at` / `source_updated_at` | 本地 update_time 不可作源端水位 | 补列或建 staging 表 |
+| `source_line_no` / `source_item_id` | 明细表无行号 | 补列支持行级幂等 |
+| 负向事件模型 | 无删除/作废/红冲/退货事件表 | 设计事件表或冲销单 |
+| `sync_log` / 失败明细表 | 完全缺失 | 同步模块前置 |
+| T+ 配置项 | `.env` 有 `T_PLUS_*`，`Settings` 未定义 | 补配置字段与校验 |
+
+## 13. IT 待确认事项收敛（18 → 13 + 1 组业务）
+
+| 新# | 原# | 事项 | 字典证据 | 字典可答 | 仍需确认 | 优先级 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | 1 | 成本额字段与成本口径 | SA_SaleOrder_b.LatestCost；SA_SaleDelivery_b.costPrice/costAmount/CostPriceGetType；AA_Inventory.invSCost/latestCost/avagCost | 字段存在性、类型精度、挂在订单还是出库单 | 请确认绩效成本取哪个字段（订单最新成本 / 出库成本 / 其他），取数时点与精度 | 高（阻塞核算） |
+| 2 | 2+3 | 发货日与到账日口径 | 发货：SA_SaleDelivery.voucherdate/SendDate/deliveryDate/auditeddate；到账：ARAP_ReceivePayment.voucherDate/auditedDate/createdTime | 各日期字段存在性与类型 | 请分别确认发货日、到账日取哪个字段；签收日/银行到账日能否从 T+ 获取 | 高 |
+| 3 | 4 | 幂等键与作废重开 | 各表 code + id 主键；SA_SaleOrder.ismodifiedcode、HasEverChanged | 编码字段与主键关系 | 各单据 code 是否唯一终身不变；作废重开是否换号；建议以 code 作 source_no | 高 |
+| 4 | 5 | 三单关联与核销路径 | SA_SaleDelivery.SourceVoucherCode/idsourcevouchertype；SA_SaleDelivery_b.saleOrderCode/saleOrderId；ARAP_ReceivePayment.SaleOrderCode/SaleOrderID；ARAP_ReceivePayment_b；ARAP_StrikeBalance | 关联字段与核销表存在性 | 请确认订单→发货→回款的主关联路径（按单号还是 ID），以及分批发货/部分核销如何取 | 高 |
+| 5 | 6 | 人员编码/工号与经理隶属 | AA_Person.code/name/iddepartment/isSalesman；AA_Department.idparent/iddirector | 编码/部门/负责人字段存在；无直属上级字段 | AA_Person.code 是否即工号；业务员→营销经理隶属在 T+ 如何维护（部门负责人？自定义项？） | 高 |
+| 6 | 7 | 对接方式与安全 | 字典不涉及 | 无 | REST/视图/中间表/文件；只读账号与凭据、接口文档、样例数据 | 高 |
+| 7 | 8 | 负数/红字/退货/冲销规则 | SA_SaleDelivery.isCounteractDelivery；SA_SaleDelivery_b.returnQuntity/backSentQuantity；ARAP_ReceivePayment.voucherstate；ARAP_StrikeBalance | 负向字段/单据形式存在性 | 负向单据的实际使用形式、原单关联字段、是否推送；绩效影响转业务 | 高 |
+| 8 | 9 | 存量起始与增量水位 | 各表 updated/createdTime/madeDate/auditedDate/ts | 时间戳字段存在性 | 存量起始日期；增量用哪个时间戳（updated? ts?）；时区 | 中 |
+| 9 | 10+v1.4#18 | 客户主数据匹配与变更 | AA_Partner.code/name/Contact/representative/disabled/updated | 编码/名称/负责人/停用字段 | 客户唯一键；改名/换负责人/合并如何映射同一主体；负责人取 Contact 还是 representative | 中 |
+| 10 | 11+16 | 收款方式与确认/核销枚举 | ARAP_ReceivePayment.IdSettleStyle；AA_SettleStyle.code/name；ARAP_ReceivePayment.cancelState/voucherstate | 枚举表与状态字段存在性 | 收款方式完整枚举与以物抵顶对应代码；核销/确认状态枚举含义及可否作为人工确认依据 | 高 |
+| 11 | 12+13 | 产品数量语义与发货单价 | ST_CurrentStock.baseQuantity；AA_InventoryPrice/AA_InventoryUnitPrice；SA_SaleDelivery_b.price/taxPrice | 数量/价格字段存在性 | 产品「数量」取现存量/在途/累计销量；发货单价取订单价还是发货时价、含税与否 | 中 |
+| 12 | 14+17 | 低频字段存在性：特殊业务标记/市场拓展计划 | SA_SaleOrder.idbusinesstype；AA_Person 自定义项；未检出市场拓展计划表 | 字段/表存在性 | 特殊业务是否有可识别字段；市场拓展计划 T+ 是否有表可提供；无则人工维护 | 低 |
+| 13 | 15 | 同步窗口 | 字典不涉及 | 无 | 每周同步时间点，避开结账/备份；失败重试策略 | 低 |
+| B1 | 18 | 业务裁决 5 项 | 税额/折扣/退货/预收/手续费字段已定位（待答复后决定是否建列） | 字段存在性 | 含税口径、退货红字冲减、预收/保证金/代收、手续费净额、负绩效表述 | 业务裁决 |
+
+### 原 18 项对照
+
+| 原# | 事项 | 原优先级 | 收敛去向 |
+| --- | --- | --- | --- |
+| 1 | 成本额取数口径 | 高（阻塞核算） | 1 |
+| 2 | 发货日期口径 | 高 | 2 |
+| 3 | 到账日期口径 | 高 | 2 |
+| 4 | 幂等唯一键 | 高 | 3 |
+| 5 | 三单关联键 | 高 | 4 |
+| 6 | 人员匹配键与经理隶属（v1.2 更新） | 高 | 5 |
+| 7 | 对接方式与安全 | 高 | 6 |
+| 8 | 负数 / 红字 / 退货 / 冲销处理规则 | 高 | 7 |
+| 9 | 存量范围与增量口径 | 中 | 8 |
+| 10 | 客户档案匹配与唯一键 | 中 | 9 |
+| 11 | 收款方式枚举 | 中 | 10 |
+| 12 | 产品「数量」语义 | 中 | 11 |
+| 13 | 发货单价口径 | 中 | 11 |
+| 14 | 特殊业务标记 | 低 | 12 |
+| 15 | 同步窗口 | 低 | 13 |
+| 16 | 回款确认 / 核销状态 | 高 | 10 |
+| 17 | 市场拓展计划数据 | 低 | 12 |
+| 18 | 口径裁决 5 项（移交业务方） | 业务裁决 | B1 |
+
+## 14. 待确认清单
+
+**IT（13 项）**：见第 13 节新# 1–13。
+
+**业务（1 组）**：含税口径、退货红字冲减、预收/保证金/代收、手续费净额、负绩效表述（原 #18 / 待澄清 #20–#24）。
+
+**系统侧（不阻塞 IT）**：补 `personnel_code`、`customers.status`、`receipts.payment_method/confirm_status`、`source_updated_at`、`source_line_no`、`sync_log` 与 T+ 配置项。
+
+## 15. 验证记录
+
+- 解包：1,457 个 HTML、`.hhc/.hhk` 齐全、零字节 0；
+- 全量解析：1,457 页、938 个 Table 类型页、**931 张表、21,019 个字段、0 失败页**；
+- 编码：逐页检测，GB18030（无替换字符）；
+- 抽样核验：六类主表结构一致（6 列字段表），关键字段逐项比对通过；
+- 输入 SHA-256：`3e8cd3146e22bdebe8bacda56b5dafbbd8be744c4279d7b2bbf3d7ecdc7e2726`；
+
+## 附录 A：六类主表索引
+
+| 类别 | T+ 表 | 字典页 GUID |
+| --- | --- | --- |
+| 人员 | AA_Person | `fcd00c17-6778-4c6a-90ae-3f0dbaf2c102` |
+| 产品 | AA_Inventory | `93b57dfa-4ca4-411d-a883-6d26c8e01787` |
+| 客户 | AA_Partner | `871e93dd-c2cf-4bd2-af91-cbeb5951ac5e` |
+| 业务 | SA_SaleOrder | `9a51f8a9-658a-4f7c-9372-8af2257511ee` |
+| 发货 | SA_SaleDelivery | `bef98b52-c9f0-4d80-8e62-8968cced5b52` |
+| 回款 | ARAP_ReceivePayment | `709de6e4-3b3d-4cf8-b5ed-5f657d42599a` |
+
+## 附录 B：75 项覆盖矩阵
+
+| 节 | 项数 | 已映射 |
+| --- | --- | --- |
+| 公共要求 | 2 | 2 |
+| 人员 | 9 | 9 |
+| 产品 | 7 | 7 |
+| 业务 | 13 | 13 |
+| 发货 | 8 | 8 |
+| 回款 | 10 | 10 |
+| 客户 | 5 | 5 |
+| 同步完整性 | 21 | 21 |
+
+## 附录 C：失败页
+
+无（`failures.csv` 为空）。
+
+## 附录 D：复现方法
+
+```text
+1. C:/Windows/hh.exe -decompile <out> <TPlus123.chm>
+2. py -3.14 -I 03_extract_fields.py --extracted <out> --out <out>
+3. py -3.14 -I 08_build_md.py --out <out> --target <md>
+```
+
+---
+
+*本文档由数据字典解析与人工核验生成，字段候选未经 IT 确认前不得视为同步契约。*

docs/design/视觉方向预览.html

@@ -35,7 +35,7 @@
 
     --ys-radius: 10px;
     --ys-radius-sm: 7px;
-    --ys-font: 'PingFang SC', 'Microsoft YaHei', 'Noto Sans SC', -apple-system,
+    --ys-font: 'Noto Sans SC', 'PingFang SC', -apple-system,
       'Segoe UI', 'Helvetica Neue', Arial, sans-serif;
     --ys-ease: cubic-bezier(0.25, 0.1, 0.25, 1);
 
@@ -46,8 +46,8 @@
     /* 极微噪点：去除大色块的塑料感（内联 SVG，无外部依赖） */
     --ys-noise: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.8' numOctaves='2' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='160' height='160' filter='url(%23n)'/%3E%3C/svg%3E");
 
-    /* 品牌字：思源黑体（现代几何黑体；实施时自托管 4 字子集，内网可用） */
+    /* 品牌字：思源黑体（现代几何黑体；实施时自托管 4 字子集，内网可用）；栈内禁用微软雅黑等需授权字体 */
-    --ys-font-brand: 'Noto Sans SC', 'PingFang SC', 'Microsoft YaHei', sans-serif;
+    --ys-font-brand: 'Noto Sans SC', 'Source Han Sans SC', 'HarmonyOS Sans SC', 'PingFang SC', sans-serif;
   }
 
   * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -556,8 +556,8 @@
         <div class="bc-cap">B · 思源黑体 300 细体 · 0.42em</div>
       </div>
       <div class="bc">
-        <div style="font-family:'Microsoft YaHei',sans-serif;font-weight:600;letter-spacing:.25em;font-size:16px">衍水集团</div>
+        <div style="font-weight:600;letter-spacing:.25em;font-size:16px">衍水集团</div>
-        <div class="bc-cap">C · 微软雅黑 600 · 0.25em</div>
+        <div class="bc-cap">C · 系统默认 600（不指定字体，展示回退效果）· 0.25em</div>
       </div>
     </div>
   </section>
@@ -936,7 +936,7 @@
 <script src="echarts.min.js"></script>
 <script>
   /* 仪表盘图表：ECharts 定制主题（圆角柱 / 无网格线 / 浅灰轴标签）——实施时前端引入 echarts 依赖 */
-  const chartFont = "'PingFang SC','Microsoft YaHei','Noto Sans SC',sans-serif";
+  const chartFont = "'Noto Sans SC','PingFang SC',sans-serif";
   const rev = echarts.init(document.getElementById('chartRev'), null, { renderer: 'svg' });
   rev.setOption({
     grid: { left: 0, right: 0, top: 6, bottom: 20, containLabel: true },

docs/superpowers/plans/2026-10-12-剩余开发计划.md

@@ -45,12 +45,12 @@
 ② 基础数据管理 ✅                  ← 人员引用 ① 岗位角色（外键上游）
 ③ 业务数据管理 ✅                  ← 引用 ② 人员/产品/客户
 │                                    增量（2026-10-15）：二次分配方案（合同刚建立时录入）
-④ 绩效工资核算                     ← 消费 ① 参数快照（按回款到账日）+ ②③ 数据
+④ 绩效工资核算 ✅                  ← 消费 ① 参数快照（按回款到账日）+ ②③ 数据
-│                                    增量（2026-10-15）：月度结算/调整单/负数工资；二次分配分摊（语义待澄清）
+│                                    增量（2026-10-15）：月度结算/调整单/负数工资；二次分配分摊（#1–#3 答复空白，开发侧暂定口径已实现，见 3.3.1）
-⑦ 复核审批流（新）                 ← 月结/二次分配的审批链（营销后勤→财务→领导）；登录角色体系扩展
+⑦ 复核审批流（新）✅               ← 月结/二次分配的审批链（营销后勤→财务→领导）；登录角色体系扩展
-⑤ 报表统计（∥ ⑥ T+ 同步）         ← ⑤ 只读消费 ③④；签字导出模板依赖 ⑦ 与公司信息；⑥ 受 IT 字段映射制约
+⑤ 报表统计 ✅（∥ ⑥ T+ 同步）       ← ⑤ 只读消费 ③④；签字导出模板依赖 ⑦ 与公司信息；⑥ 受 IT 字段映射制约（待 IT 18 项答复）
-⑧ 工作台（新）                     ← 消费 ④⑤⑥⑦ 数据的聚合展示层
+⑧ 工作台（新）✅                   ← 消费 ④⑤⑥⑦ 数据的聚合展示层
-⑨ 备份恢复与运维检查（新）         ← 独立于业务块，可与任一批次并行，建议尽早
+⑨ 备份恢复与运维检查（新）✅       ← 独立于业务块，可与任一批次并行，建议尽早
 ```
 
 ### 1.2 顺序论证（要点）
@@ -68,12 +68,12 @@
 | ① 系统设置与参数体系 | 岗位角色 CRUD + 模板绑定；参数目录/版本化存储/按日期取值/变更留痕/对比/导出；公式纯函数；计算预览。**✅ 已完成**。增量（2026-10-15）：公司信息配置（公司名称、logo 等基本信息）；审批开关配置走参数体系；新增参数一律进参数注册表（用户重申：参数配置尽量灵活） | （原验收已达成）增量：公司信息可配置并用于登录页与导出页眉；审批开关参数化，关闭直接生效、开启走审批 |
 | ② 基础数据管理 | 人员（岗位/工资标准/团队/辐射区域/拓展计划）、产品类型与目录、业务(客户)与归属变更。**✅ 已完成** | 三类数据可维护并留痕；人员岗位引用 ① 岗位表；表含 T+ 预留列；客户分类（个人户/经理个人户/企业户）与归属修改不回溯历史 |
 | ③ 业务数据管理 | 业务明细+指导价、发货（批次/运费/发货日）、回款（批次号/到账日/以物抵顶/手动指定发货批次）、毛利润（不含运费）、客户评级计算器。**✅ 已完成**。增量（2026-10-15）：二次分配方案 —— 只出现在合同刚建立时；合同建立时可手动选择参与二次分配的业务员；分配比例不要求合计 100%；审批开关开启时走审批 | （原验收已达成）增量：合同建立时可录入参与业务员与比例（不强制合计 100%）；开关关闭直接生效；方案修改不影响已结算月份 |
-| ④ 绩效工资核算 | 核算引擎（按回款到账日取参数）、单笔台账+核销防重、经理 12.5%+5%、试用期/年累计 18000、起付 60% 与 R×R、预付款/以物抵顶、月工资（分岗口径）、重算授权留痕。增量（2026-10-15）：月度结算（按确认回款和计算快照生成）；支持负数工资、扣补说明和调整单；结算后锁定 —— 修改源数据不影响已结算结果，只产生提示、历史记录和后续调整；二次分配分摊（语义待澄清，见 3.3） | 任一笔回款可复算到分（零误差）；同笔回款不重复核算；08-13 前后企业户 2‰/3‰ 回溯正确；月工资表可生成。增量：任一月份可出月结快照并锁定；已锁月份源数据变更只产生提示与历史，金额不变；调整单留痕可追溯 |
+| ④ 绩效工资核算 | 核算引擎（按回款到账日取参数）、单笔台账+核销防重、经理 12.5%+5%、试用期/年累计 18000、起付 60% 与 R×R、预付款/以物抵顶、月工资（分岗口径）、重算授权留痕。增量（2026-10-15）：月度结算（按确认回款和计算快照生成）；支持负数工资、扣补说明和调整单；结算后锁定 —— 修改源数据不影响已结算结果，只产生提示、历史记录和后续调整；二次分配分摊（#1–#3 答复空白，开发侧暂定口径已实现，见 3.3.1） | 任一笔回款可复算到分（零误差）；同笔回款不重复核算；08-13 前后企业户 2‰/3‰ 回溯正确；月工资表可生成。增量：任一月份可出月结快照并锁定；已锁月份源数据变更只产生提示与历史，金额不变；调整单留痕可追溯 |
-| ⑤ 报表统计 | 个人绩效明细、部门汇总、业务统计、回款区间统计、Excel 导出与打印。增量（2026-10-15）：导出模板围绕财务复核和领导签字设计 | 四表口径与台账一致且可下钻单笔；导出精度与页面一致。增量：导出模板含复核/签字栏与公司信息页眉 |
+| ⑤ 报表统计 | 个人绩效明细、部门汇总、业务统计、回款区间统计、Excel 导出与打印。增量（2026-10-15）：导出模板围绕财务复核和领导签字设计。**✅ 已完成（2026-10-19）** | 四表口径与台账一致且可下钻单笔；导出精度与页面一致。增量：导出模板含复核/签字栏与公司信息页眉 |
-| ⑥ T+ 数据同步 | 五类数据抓取/清洗/入库、唯一键去重、失败重试、同步日志、周定时+手动触发 | 手动同步幂等（重跑不重复入库）；失败有日志与重试；不覆盖人工字段 |
+| ⑥ T+ 数据同步 | 五类数据抓取/清洗/入库、唯一键去重、失败重试、同步日志、周定时+手动触发。**⏳ 阻塞（IT 18 项未答复）** | 手动同步幂等（重跑不重复入库）；失败有日志与重试；不覆盖人工字段 |
-| ⑦ 复核审批流（新） | 月结与二次分配的审批链：营销后勤提交 → 财务复核 → 领导审核；审批开关配置（参数化，关闭直接生效）；审批意见与版本；登录角色体系扩展（营销后勤/财务/领导为系统新登录角色，激活闲置的 permissions/role_permissions） | 开关关闭时提交即生效；开启时三级流转全程留痕；每级意见与版本可追溯；重算/改单产生新版本，不覆盖既有审批记录 |
+| ⑦ 复核审批流（新） | 月结与二次分配的审批链：营销后勤提交 → 财务复核 → 领导审核；审批开关配置（参数化，关闭直接生效）；审批意见与版本；登录角色体系扩展（营销后勤/财务/领导为系统新登录角色，激活闲置的 permissions/role_permissions）。**✅ 已完成（2026-10-19；权限细目待业务清单）** | 开关关闭时提交即生效；开启时三级流转全程留痕；每级意见与版本可追溯；重算/改单产生新版本，不覆盖既有审批记录 |
-| ⑧ 工作台（新） | 经营绩效总览、待办事项、风险预警、最近同步/计算/审批动态 | 四区块出数口径与台账/审批/同步日志一致可下钻；预警规则参数化可配置 |
+| ⑧ 工作台（新） | 经营绩效总览、待办事项、风险预警、最近同步/计算/审批动态。**✅ 已完成（2026-10-19）** | 四区块出数口径与台账/审批/同步日志一致可下钻；预警规则参数化可配置 |
-| ⑨ 备份恢复与运维检查（新） | MySQL 定时备份与恢复演练、运维检查（容器/磁盘/日志/Redis/同步状态）、检查清单与脚本 | 任一备份可按文档恢复成功；检查项脚本化输出健康报告 |
+| ⑨ 备份恢复与运维检查（新） | MySQL 定时备份与恢复演练、运维检查（容器/磁盘/日志/Redis/同步状态）、检查清单与脚本。**✅ 已完成（2026-10-16）** | 任一备份可按文档恢复成功；检查项脚本化输出健康报告 |
 
 ### 1.4 里程碑（交付批次）
 
@@ -81,9 +81,9 @@
 | --- | --- | --- |
 | **M1** | ① 系统设置与参数体系 | ✅ 已完成（2026-10-13 推送 feat/system-params） |
 | **M2** | ② + ③ | ✅ 已完成（2026-10-13 分支 feat/base-business-data） |
-| **M3** | ① 增量（公司信息/审批开关）+ ③ 增量（二次分配录入）+ ④ 绩效工资核算（含月结/调整单/负数工资）+ ⑦ 复核审批流 | 核心闭环「核算 → 提交 → 财务复核 → 领导审核 → 锁定」；开工前必须澄清：二次分配分摊语义（3.3-1）、经理个人户基数（开放问题 #7）；内部建议顺序 ①增量 → ③增量 → ⑦ 审批框架 → ④ 核算 → 月结与审批串联 |
+| **M3** | ① 增量（公司信息/审批开关）+ ③ 增量（二次分配录入）+ ④ 绩效工资核算（含月结/调整单/负数工资）+ ⑦ 复核审批流。**✅ 已完成（2026-10-19，feat/m3-increments）** | 核心闭环「核算 → 提交 → 财务复核 → 领导审核 → 锁定」已交付；余 3.3-1 答复与审批权限细目。开工前澄清项：二次分配分摊语义（3.3-1）、经理个人户基数（开放问题 #7，已参数化） |
-| **M4** | ⑤ 报表（含财务复核/领导签字导出模板）+ ⑥ T+ 同步（并行）+ ⑧ 工作台 | ⑥ 受 IT 制约，谁先就绪谁先交；⑧ 消费 ④⑤⑥⑦ 出数，排其后 |
+| **M4** | ⑤ 报表（含财务复核/领导签字导出模板）+ ⑥ T+ 同步（并行）+ ⑧ 工作台。**✅ ⑤⑧ 已完成（2026-10-19）；⑥ 待 IT 18 项答复** | ⑥ 受 IT 制约，谁先就绪谁先交；⑧ 消费 ④⑤⑥⑦ 出数，排其后 |
-| **⑨ 备份恢复与运维检查** | 不占独立批次，随任一批次并行（建议 M3 期间并行交付） | 数据持续积累，备份先行；不依赖业务模块进度 |
+| **⑨ 备份恢复与运维检查** | 不占独立批次，随任一批次并行（建议 M3 期间并行交付）。**✅ 已完成（2026-10-16）** | 数据持续积累，备份先行；不依赖业务模块进度 |
 
 ### 1.5 需求依据对照
 
@@ -95,7 +95,7 @@
 | ④ | 需规 2.3.1–2.3.3；对照表 #3/#4/#6/#7/#11/#15/#16/#17/#20–#24；增量见 3.1(一)(四) | 协助 25%；经理 8‰；26 天示例；含运费公式 |
 | ⑤ | 需规 2.4.1–2.4.3；对照表 #22（明细展示 R）；增量见 3.1(四) | — |
 | ⑥ | 需规各「同步 T+」条；对照表 #10/#26/#27 | — |
-| ⑦⑧⑨ 及各块增量 | **2026-10-15 功能清单核查补充（本文第三章，原文照录）**——尚未回填需规与对照表，引用以第三章原文为准 | 二次分配 ≠ 协助 25%：#15 作废的是「协助 25% 分成」条款，二次分配是合同建立时的新机制，关系待业务澄清（3.3-1） |
+| ⑦⑧⑨ 及各块增量 | **2026-10-15 功能清单核查补充（本文第三章，原文照录）**——已随 SRS V2.1（2026-10-19）回填；《问题与解决方案对照表》是否回填由用户决定 | 二次分配 ≠ 协助 25%：#15 作废的是「协助 25% 分成」条款，二次分配是合同建立时的新机制；#1–#3 答复仍空白，开发侧暂定口径已实现（3.3.1） |
 
 ---
 
@@ -610,11 +610,13 @@ git commit -m "test(system): 参数体系模块用例与测试记录"
 | 6 | 导出格式与列集合（是否含批次说明/操作人） | 以需规 2.3.1(四) 字段为准，导出前与业务对一次列 |
 | 7 | 经理个人户业绩如何进入 12.5%+5%（裁决 #7 的具体衔接：该业绩是否计入「本人带领业务员」基数） | ④ 开工前必须确认（影响台账归属字段设计） |
 
+> **2026-10-20 回填**：上述开放问题均已有结论，原表保留为 2026-10-12 设计时快照。#1 → 澄清 #14（首日整 10‰，A 口径）；#2 → #18（按 2‰ 回溯，双种子保留）；#3 → #15（一期仅 FULL，BALANCE 留参数位）；#4 → #16（撤 `probation.salary.basic`，读 `personnel.salary_standard`）；#5 → #17（查看放开登录用户、修改仅管理员）；#6 → 催办清单三、R3；#7 → #12（`manager.personal.included` 参数，默认 0=不计入）。
+
 ---
 
 ## 第三章 2026-10-15 功能清单核查补充（新增需求）
 
-> **来源与地位：** 用户以现有功能清单核查后补充的需求（2026-10-15）。本章 3.1 为**原文照录**（未做任何改写），3.2 起为开发侧归属与推演，**两者严格区分**；引用新需求一律以 3.1 原文为准。本批内容尚未回填需规文档与《问题与解决方案对照表》，是否回填由用户决定。任务级实施计划在对应里程碑开工前按第二章同粒度补齐。
+> **来源与地位：** 用户以现有功能清单核查后补充的需求（2026-10-15）。本章 3.1 为**原文照录**（未做任何改写），3.2 起为开发侧归属与推演，**两者严格区分**；引用新需求一律以 3.1 原文为准。本批内容已随《需求规格说明书》V2.1（2026-10-19）回填；《问题与解决方案对照表》是否回填由用户决定。任务级实施计划在对应里程碑开工前按第二章同粒度补齐。
 
 ### 3.1 需求原文（照录）
 
@@ -656,6 +658,7 @@ git commit -m "test(system): 参数体系模块用例与测试记录"
 #### （六）系统设置
 
 - 公司信息配置：公司名称、logo 等基本信息
+- **2026-10-20 回填**：参数注册表已扩至 22 项（V8/V10 增补审批开关、试用期迁移、预警阈值等）
 
 #### （七）参数配置强调
 
@@ -666,7 +669,7 @@ git commit -m "test(system): 参数体系模块用例与测试记录"
 #### (一) 二次分配方案 → ③ 录入 + ④ 分摊消费 + ⑦ 审批联动 + ④ 调整单衔接
 
 - 「只出现在合同刚建立时」→ 录入入口放业务创建流程（与 `businesses` 创建同事务或紧随其后）；合同建立后是否允许补录/修改未明说，方案修改的留痕方式待设计；
-- 「分配比例不要求合计 100%」→ 余额归属规则需求未说明（3.3-1），存储上只存各参与人比例、不强制校验合计；
+- 「分配比例不要求合计 100%」→ 余额归属规则需求未说明（3.3-1）；存储上只存各参与人比例、不强制校验合计。**2026-10-20 回填**：#1–#3 答复仍空白，开发侧已按暂定口径实现分摊拆行（余额归负责人、行合计守恒，见 3.3.1），答复后如有变更走口径调整；
 - 「修改不影响已结算月份」→ 月结快照天然隔离（快照固化当月结果），方案表需支持编辑 + 修改留痕；
 - 「已结算月份调整只能通过调整单或后续月份扣补」→ 调整单为统一承载机制，见 (四)。
 
@@ -676,7 +679,7 @@ git commit -m "test(system): 参数体系模块用例与测试记录"
 | --- | --- |
 | 经营绩效总览 | ④ 台账/月结（按人/团队/月份汇总） |
 | 待办事项 | ⑦ 待审批单、⑥ 同步失败、回款未指定批次（M2 已有该状态可复用） |
-| 风险预警 | 规则未定义（3.3-5），先落参数化规则容器 |
+| 风险预警 | 规则未定义（3.3-5），先落参数化规则容器。**2026-10-20 回填**：方向已答复参数化（#10），首批三条按默认落 V10 参数（逾期 90 天/审批超时 3 天/同步失败待 ⑥） |
 | 最近同步/计算/审批动态 | ⑥ 同步日志 + ④ 核算/月结记录 + ⑦ 审批记录 |
 
 #### (三) 复核审批 → ⑦ 新模块
@@ -687,9 +690,11 @@ git commit -m "test(system): 参数体系模块用例与测试记录"
 - 「审批意见与版本」→ 审批单带版本号：重算/改单产生新版本，旧版本与意见留痕不覆盖；
 - **登录角色体系扩展**：营销后勤/财务/领导是系统新登录角色（`roles` 表基础设施已有；`permissions`/`role_permissions` 自 M1 起闲置待权限清单，此处激活）——打破一期「营销人员不登录」的前提，但与该原则不矛盾（营销人员仍不登录，后勤/财务/领导是职能角色）。
 
+> **2026-10-20 回填**：审批框架与月结审批对象已交付（2026-10-19）；权限点清单仍待业务方给出（澄清 #6，催办 B-6），当前按 role_code 粗粒度运行，营销后勤暂不可见审批列表。
+
 #### (四) 月结、审批、报表 → ④ 月结子块 + ⑦ 审批 + ⑤ 导出模板
 
-- 月度结算 = 台账之上的月度汇总快照（按月生成、含状态机：草稿/待审/已审定/已锁定）；「确认回款」定义待澄清（3.3-3）；
+- 月度结算 = 台账之上的月度汇总快照（按月生成、含状态机：草稿/待审/已审定/已锁定）；「确认回款」已答复为人工确认、可手动关闭（3.3-3），月结按已确认回款取数；
 - 「支持负数工资」与既有裁决「负绩效按公式正常计算（不归零）」一致，无需改公式口径；
 - 调整单：新单据类型（补发/扣减方向、关联月份、扣补说明、审批状态）；
 - 「结算后锁定」：已锁月份的快照金额不可变；源数据修改只产生提示、历史记录和后续调整 —— 与 #19「归属变更不回溯历史」同一哲学，扩展到全部源数据；
@@ -708,6 +713,8 @@ git commit -m "test(system): 参数体系模块用例与测试记录"
 
 ### 3.3 待澄清问题（不阻塞收录，对应模块开工前须澄清）
 
+> **回填状态（2026-10-20）：** 下表保留 2026-10-15 原始问题与建议默认（历史快照）；业务答复与落实情况见 3.3.1。3.3-1 仍无业务答复，开发侧已按暂定口径实现分摊拆行，答复后如有变更按口径调整。
+
 | # | 事项 | 影响模块 | 建议默认处理 |
 | --- | --- | --- | --- |
 | 1 | 二次分配的**分配标的**（绩效金额？折算毛利润？业绩额？）与**余额归属**（合计 ≠100% 时差额归谁）；与已作废的「协助 25%」（#15）是何关系 | ④ 分摊逻辑与台账归属字段 | 未确认前 ④ 只落录入与存储，不实现分摊 |
@@ -718,13 +725,41 @@ git commit -m "test(system): 参数体系模块用例与测试记录"
 | 6 | 调整单是否走同一审批链；能否跨月调整已锁定月份 | ④⑦ | 建议走同一审批链；「后续月份扣补」为默认路径，跨月调整需授权留痕 —— 待确认 |
 | 7 | 待办事项的范围（除审批/同步失败外还含哪些，回款未指定批次是否算待办） | ⑧ | 按 3.2(二) 默认清单起步，业务确认后扩充 |
 
+### 3.3.1 答复回填（2026-10-19，2026-10-20 修订）
+
+> **修订说明（2026-10-20）：** 2026-10-19 版本把 24 项统一写成「全部落实并实现」，与 3.3-1 答复空白、开发侧暂定分摊的事实不符。本次按「业务答复 / 落实状态 / 关联项」重写；3.3-1 明确标注为开发侧暂定口径，不视为业务确认。
+>
+> 业务方 24 项答复于 2026-10-16 到达（回执见《待澄清问题清单_2026-10-15(1)(2).xlsx》H 列）。分组：确认按建议默认 13 项（#7/#8/#9/#10/#11/#13/#15/#17/#18/#21/#22/#23/#24，其中 #22 为模糊确认按不计入）；与默认不同、已按答复落实 4 项（#5/#14/#16/#19）；部分答复 3 项（#4/#6/#12）；仍开放 4 项（#1/#2/#3/#20）。未答复项对外跟催见 `docs/待答复催办清单_2026-10-19.md`。
+
+| 3.3# | 事项 | 业务答复（2026-10-16） | 落实状态（2026-10-20） | 关联项 / 证据 |
+| --- | --- | --- | --- | --- |
+| 1 | 二次分配标的与余额归属（含与 #15 协助 25% 的关系） | **未答复**（澄清 #1–#3 空白） | **开发侧暂定口径已实现**（非业务答复）：分配标的=绩效金额份额；参与人=份额×比例，负责人=全额−已分累计（余额归负责人）；行合计守恒；合计>100% 与负责人自分 400 拦截；重算作废全部拆行。协助 25% 维持仅记录不核算。**答复后校准** | 澄清 #1/#2/#3；催办一、A-1 至 A-3；实现 ccfd206 |
+| 2 | 二次分配审批开关默认值 | 默认开启，可手动关闭 | 已落实：V8 参数种子默认开启；关闭时提交即生效（自动通过留痕） | 澄清 #5；`approval.secondary_allocation.enabled` |
+| 3 | 「确认回款」定义 | 需人工确认动作，可手动关闭 | 已落实：月结按已确认回款取数；回款确认状态可手动关闭 | 澄清 #8 |
+| 4 | 审批角色权限清单 | 部分答复：先预设角色，名称与职权待客户确认 | 按最小授权运行：后勤=提交录入，财务=复核+导出，领导=审核只读；营销后勤暂不可见审批列表；permissions/role_permissions 细目待清单 | 澄清 #6；催办一、B-6 |
+| 5 | 风险预警规则 | 方向确认参数化；首批三条未点名 | 已按默认三条实现：`warning.enabled`、`warning.receipt.overdue.days=90`、`warning.approval.timeout.days=3`（V10）；同步失败类待 ⑥ | 澄清 #10 |
+| 6 | 调整单是否走同一审批链；能否跨月调整已锁月份 | 同一审批链；跨月需管理员授权并留痕 | 已落实：调整单走同一审批链；跨月调整需管理员授权并留痕 | 澄清 #9 |
+| 7 | 待办事项范围 | 待审批 + 同步失败 + 回款未指定批次起步 | 已落实：工作台待办三项；⑥ 未建时同步项显式降级为「模块未启用」；待办按角色过滤 | 澄清 #11 |
+
+#### 关联项表（与《待确认事项汇总_2026-10-16》及催办清单的对应）
+
+| 3.3# | 澄清清单编号 | 催办清单位置 | 实现落点 |
+| --- | --- | --- | --- |
+| 1 | #1/#2/#3（#15 为作废条款关系） | 一、A-1 至 A-3 | 二次分摊拆行（ccfd206） |
+| 2 | #5 | 已按答复执行（供核阅） | V8 迁移参数种子 |
+| 3 | #8 | 已按答复执行（供核阅） | 月结取数（settlement_service） |
+| 4 | #6 | 一、B-6 | permissions/role_permissions 待清单；当前按 role_code 粗粒度 |
+| 5 | #10 | 已按答复执行（供核阅） | V10 参数 + dashboard_service |
+| 6 | #9 | 已按答复执行（供核阅） | 调整单审批链与跨月授权 |
+| 7 | #11 | 已按答复执行（供核阅） | dashboard_service 待办三源 |
+
 ### 3.4 对路线图的影响（本次已修订）
 
-1.1 依赖图、1.3 范围与验收、1.4 里程碑、1.5 依据对照均已并入本批内容；第三章待 3.3 各项澄清后，按第二章同粒度补齐 M3 各增量块的任务级实施计划。
+1.1 依赖图、1.3 范围与验收、1.4 里程碑、1.5 依据对照均已并入本批内容。M3 各增量块已于 2026-10-19 交付；3.3-1 仍无业务答复，二次分摊当前按开发侧暂定口径运行，答复后补口径变更计划；3.3-4 的权限细目与 3.3-5 的预警规则仍待业务确认。⑥ T+ 同步在 IT 答复前不排任务级计划。
 
 ## 验证方式
 
 1. 计划内容与 `ai-aux/AI_CONTEXT.md` 需求裁决节逐条核对（口径无冲突、无遗漏作废条款）；
 2. 计划中的命令与项目现有命令体系一致（uv / pnpm / docker compose）；
 3. 首块每个任务有独立可测交付物；测试要点符合「模块整体完成时统一编写」约定（纯函数与 core 级随实现即时测）；
-4. 执行阶段验证：T1 后 `test_schema_sync.py` 通过；T2/T3 后纯单元全绿；T5 后冒烟链路完整；T8 后全量 301+ 用例与 e2e 全绿。
+4. 执行阶段验证：T1 后 `test_schema_sync.py` 通过；T2/T3 后纯单元全绿；T5 后冒烟链路完整；T8 后全量后端用例与 e2e 全绿（以 `backend/tests/README.md` 最新运行记录为准）。

docs/superpowers/plans/2026-10-19-M4-报表统计.md

@@ -0,0 +1,160 @@
+# M4 ⑤ 报表统计 · 任务级实施计划
+
+> 立项日期 2026-10-19；分支 feat/m3-increments。依据：需规 2.4 /《需求规格说明书》FR-029~FR-032 / 开发计划第五章 1.3 验收行 / 2026-10-15 补充（四）「导出模板围绕财务复核和领导签字设计」。
+> 前置已满足：④ 台账/月结/调整单全部交付（台账即「报表 2.4.1 的数据源」，`performance_ledger.py` 注释锚点）。
+> **纯只读模块，无数据库迁移**。
+
+## 〇、代码核实结论（实施时按此避坑）
+
+| # | 结论 | 影响 |
+| --- | --- | --- |
+| 1 | `require_roles` 403 文案硬编码「无权访问审批管理」（`api/deps.py:135`） | 给 `require_roles` 增可选 `message` 参数（默认值不变），报表传「无权访问报表统计」 |
+| 2 | `PageQuery.page_size` 上限 200（`core/response.py:57`） | 打印视图循环翻页取全量；导出走专用无分页查询 |
+| 3 | `settlement_service._confirm_scope` 带 `settlement_id IS NULL`（可入结口径） | 报表取数**不复用**，新增同月全量生效单笔行查询 |
+| 4 | `list_adjustments` 无月份筛选、limit 200、含全部状态 | 调整单并入需新写仓储查询（月份 + status=2） |
+| 5 | `GET /system/settings` 是 AdminUser，`/public` 才无角色限制 | 打印视图页眉必须走 `getPublicSettings()` |
+| 6 | 台账 `payment_days` 可空可负（先款后货）；进度登记回款无台账行（#25） | 区间桶含「≤0 天」「无天数」兜底；回款统计注明「不含进度登记回款」 |
+| 7 | 二次分摊拆行使同一回款多行（负责人+参与人，business_id 相同） | 回款金额按 receipt_id 去重；个人明细不放「关联回款金额」列 |
+| 8 | 经理聚合行 calc_type=2 的 business_id 是锚点、receipt_id=NULL、payment_days=NULL | 业务统计/个人明细/回款统计一律 `calc_type=1 AND is_active=1`，防聚合额污染 |
+| 9 | openpyxl `NUMERIC_TYPES` 含 Decimal，原样落数值不转 float | 精度红线导出侧成立；`number_format='#,##0.00'` 控显示 |
+| 10 | `test_param_registry.py` 锁 registry 19 项 | 新增参数需四处同改（本计划不新增参数，规避） |
+| 11 | `PRODUCT_CATEGORIES` 常量不含 `mixed`，台账行有 `mixed` | 标签映射额外覆盖 mixed，单测防漂移 |
+| 12 | `audit_service.audit` 可用于只读导出留痕（独立 commit） | 直接复用；上下文内 bytes 在 commit 前固化 |
+| 13 | `test_settlement_helpers.py` 直接 import `settlement_service._month_end` | 抽共享模块时保留薄委托包装 |
+| 14 | 前端无任何打印/PDF/xlsx 代码 | 打印从零建：独立顶层路由 + `@media print` |
+| 15 | Starlette 响应头 latin-1，中文文件名会 UnicodeEncodeError | 导出文件名服务端 ASCII、中文名前端 `link.download` 赋 |
+
+## 一、全局口径（写进 report_service docstring）
+
+1. 数据源 `performance_ledgers` 固定 `is_active=1 AND calc_type=1`；聚合行只在部门汇总作冻结对照单读；月份维度 `settlement_month`。
+2. 金额全程 `Decimal` 出参字符串；比例原样 `rate_text`，禁 float/截断。
+3. 调整单并入：仅 `status=2`，按 `(settlement_month, personnel_id)` 并入，`direction=1` 记 +、`2` 记 −；归属按实时 `manager_id`。
+4. 离职人员不按 `status` 过滤（历史业绩留在原团队）；零行经理枚举仅在职经理。
+5. 汇总 = 明细合计（团队/公司基数 == 成员明细绩效合计，测试逐项断言）。
+
+### 已定设计决策
+
+- 部门口径 = `personnel.manager_id` 实时上溯（无独立部门表，人员模型 docstring 已声明；已入催办清单 R1 向业务确认）
+- 导出 = 后端 openpyxl + StreamingResponse（ASCII 文件名）；打印 = 前端独立打印视图 + `@media print`，PDF 走浏览器另存为；不引前端 PDF/xlsx 依赖
+- 不做图表（需求无要求，不引 ECharts）
+- 区间桶 = 代码常量 + 服务端下发元数据（前端零硬编码）；不进参数体系避免迁移；配置缝收在 `get_payment_day_buckets()` 单函数，升级路径：`report.payment_days.buckets` 参数 → V10 迁移种子 → init-dev → registry 测试 19→20
+- 权限 `require_roles(ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER)` 粗粒度，前后端双层（admin 显式列入）
+
+## 二、后端任务
+
+### T1 常量与元数据（`core/constants.py` 改 + `core/report_meta.py` 新）
+
+> 实施修订（2026-10-19）：`report_meta` 放在 `core/` 而非 `services/`——仓储层
+> 的区间下钻需要 `DayBucket` 类型，放 services 会让 repository 反向依赖
+> service 层（违反六层红线）。
+
+- `MODULE_REPORT = "报表统计"`、`ACTION_EXPORT = "导出"`
+- `report_meta.py`（叶子模块，禁 app 内导入防循环依赖）：`DayBucket` frozen dataclass + `PAYMENT_DAY_BUCKETS` 8 档（≤0 天（先款后货）/1-30/31-60/61-90/91-180/181-360/361+/无天数）、`CUSTOMER_TYPE_LABELS`、`PRODUCT_CATEGORY_LABELS`（含 mixed）、`REPORT_TEMPLATE_VERSION = "V1.0"`、`REPORT_EXPORT_MAX_ROWS = 20000`
+
+### T2 仓储 `repositories/report_repository.py`（新）
+
+| 函数 | 说明 |
+| --- | --- |
+| `list_personal_detail / count_personal_detail` | 单笔生效行分页（month/personnel/customer_type/product_category/role_code 筛选，id desc） |
+| `sum_personal_detail` | 全筛选口径 SUM（分页合计与页内合计分开，禁内存当前页求和） |
+| `list_month_receipt_rows` | 同月全量生效单笔行（部门汇总取数，不复用 _confirm_scope） |
+| `list_month_manager_aggregates` | 同月 calc_type=2 生效行（冻结对照） |
+| `list_month_adjustments` | status=2 + 月份 |
+| `list_business_stats / count / sum` | Business×Customer×Personnel 左联 + 三个 scalar_subquery（发货额 SUM(shipments.total_amount)、回款额 SUM(receipts.amount)、绩效 SUM(台账 performance_amount WHERE calc_type=1 AND is_active=1)）；keyword 双列 OR contains(autoescape=True) |
+| `list_payment_group_by_days` | GROUP BY (payment_days, customer_type, product_category) 出 SUM 绩效/应付/COUNT |
+| `list_payment_receipt_group_by_days` | 先 DISTINCT receipt_id 再 JOIN receipts 求和（拆行防翻倍） |
+| `list_payment_detail / count` | 区间下钻分页（闭区间 between、开区间 >=、none 桶 IS NULL），JOIN receipts 取金额与批次号 |
+
+### T3 经理分成共享口径（`services/manager_share.py` 新 + `settlement_service.py` 改薄委托）
+
+- 迁出（复制实现 + 薄委托，行为零变化）：`month_end`、`ManagerShareParams`（含 `manager_share_params(session, month)`，锚定月末 resolve_snapshot）、`collect_team_buckets`、`company_base_of`
+- 报表侧分成额调用 `formula.manager_team_share(...)`——月结聚合行与报表汇总同源，杜绝口径漂移
+- **协调点**：84 会话已拆 settlement_service（028a94a）；本任务在其基础上做，验证 `test_settlement_helpers.py` 全绿
+
+### T4 服务与 schemas（`services/report_service.py` + `schemas/report.py` 新）
+
+1. **个人明细**：`ReportPage[T]` = 标准分页四字段 + `summary`（全筛选合计）；行含 ledger_id/business_id/business_no/人员/岗位/客户类型/产品类别/ship_date/receipt_date/payment_days/rate_text/weight_r/payment_weight/performance_amount/payable_amount；**不含回款金额列**
+2. **部门汇总**（月份必填）：`collect_team_buckets` 分团队 → 团队基数/成员内联明细（personnel_id 聚合 + 台账 id 列表 + 调整 extra/deduct/net）；`company` 块 5% 单列（team_base_total/company_base/company_share_amount；各团队 5% 之和 ≠ 全局 5%，UI 注明）；零行经理并集枚举（在职 sales_manager JOIN business_roles + 数据中出现的 manager_id）；对比 `company_base_ratio` 除零→0；冻结对照 `aggregate_ledger_id + frozen_amount`；出参 `params`（team_pct/company_pct/manager_personal_included/params_as_of）
+3. **业务统计**：分页 + summary；回款/绩效为该业务累计值（不随日期筛选变，页面 hint）
+4. **回款统计**：SQL 精确值聚合 → Python 按 `PAYMENT_DAY_BUCKETS` 分桶（恒含全桶、空桶 0）；正负绩效直接求和不 ABS；出参 buckets/by_customer_type/by_product_category/totals
+5. **区间下钻**：`GET /reports/payment-detail`（bucket 必填，分页）
+6. **导出编排** `export_report(session, code, q, *, operator, meta)`：先 count 判上限（超限 400 中文提示按月缩小）；`audit_service.audit(MODULE_REPORT, ACTION_EXPORT, ...)` 包取数+构建；出参 `(bytes, filename)` 在 commit 语义闭合前固化
+
+### T5 Excel 模板（`services/report_export.py` 新，纯函数）
+
+- 普通 `Workbook`（上限封顶 2 万行内存可承受）；版式：公司页眉行（logo `read_logo` try/except 降级纯文本）→ 标题（合并居中）→ 筛选条件行 → 导出时间/人/模板版本 → 表头（加粗底纹边框 + freeze_panes）→ 数据行 → 合计行（service 侧 Decimal SUM quantize HALF_UP，**不写 Excel 公式**）→ 空两行 → 财务复核栏 / 领导签字栏 / 日期栏
+- 精度：金额 Decimal 直接写 + `#,##0.00`；比例 `'0.00"%"'`；`rate_text` 原样文本；日期 `date` + `YYYY-MM-DD`
+- 防公式注入：文本以 `= + - @ \t` 开头前置 `'`；CJK 列宽；部门汇总/回款统计多 sheet（各带页眉与签字栏）；空数据允许（表头 + 提示行 + 签字栏）
+
+### T6 API 与路由（`api/v1/reports.py` 新 + `router.py` 改 + `deps.py` 改）
+
+| 方法 | 路径 | 入参（Query 蛇形） |
+| --- | --- | --- |
+| GET | `/api/v1/reports/personal-detail` | pageNum/pageSize + settlement_month, personnel_id, customer_type, product_category, role_code |
+| GET | `/api/v1/reports/department-summary` | settlement_month(必填), manager_id |
+| GET | `/api/v1/reports/business-stats` | pageNum/pageSize + keyword, customer_id, owner_personnel_id, status, date_from, date_to |
+| GET | `/api/v1/reports/payment-stats` | settlement_month, date_from, date_to, customer_type, product_category |
+| GET | `/api/v1/reports/payment-detail` | pageNum/pageSize + bucket(必填) + 同上 |
+| GET | `/api/v1/reports/{code}/export` | code ∈ 四表，参数同对应页 → StreamingResponse xlsx |
+
+- 全部 `def` 同步路由 + `Annotated[User, Depends(require_roles(ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER, message="无权访问报表统计"))]`
+- Content-Disposition 文件名 ASCII（`personal_detail_20261019.xlsx`），沿用 `system/params.py` 导出先例
+
+### T7 后端文档（`backend/README.md` 改）
+
+报表接口表 + 「报表口径」小节（生效行/调整单并入/回款去重/不含进度登记回款/区间桶常量与升级路径）。
+
+## 三、前端任务
+
+### T8 API 与常量（`api/reports.ts` 新 + `utils/constants.ts` 改）
+
+类型逐字段对齐（金额 string）；`exportReport(code, params)` 裸 axios `responseType:'blob'`；MODULE_OPTIONS 与后端 `core/constants.py` 全量对齐
+
+### T9 四个页面（`views/reports/{personal-detail,department-summary,business-stats,payment-stats}/index.vue` 新）
+
+统一骨架：`filters(reactive)` + `usePagedList`（非分页表 ref+手动 load）+ `el-table stripe` + `AppPagination` + 工具条「导出 Excel」「打印」+ `handledError`；日期区间 `el-date-picker value-format="YYYY-MM-DD"`（必写）；下拉复用 `useDropdownOptions`
+
+| 页面 | 路由 order | 关键列与下钻 |
+| --- | --- | --- |
+| 个人绩效明细表 | `/reports/personal-detail` 19 | 需规 10 列 + 页脚全筛选合计（注明非当前页）；expand 懒加载 `getLedger(ledger_id)` 快照下钻 |
+| 部门绩效汇总表 | `/reports/department-summary` 20 | 团队表 + 全公司 5% 卡片 + 参数取值提示；展开成员 → 跨页下钻个人明细（router.push query）→ 台账下钻复用 `listLedger` |
+| 业务统计表 | `/reports/business-stats` 21 | 发货额/回款额/绩效三列；expand 两小表（复用 `listReceipts`/`listLedger`）；hint「累计值」 |
+| 回款统计表 | `/reports/payment-stats` 22 | buckets 元数据渲染（空桶 0）+ 桶展开下钻 `payment-detail` + 客户类型/产品类别对比小表 |
+
+路由 meta：`{ title, group: '报表统计', order: 19..22, allowedRoles: [ROLE_ADMIN, 'finance', 'leader'] }`（admin 显式列入）
+
+### T10 打印视图（`views/reports/print/index.vue` 新 + `router/index.ts` 改）
+
+- 顶层路由 `/reports/print/:code`（不挂 BasicLayout），`menu:false` + allowedRoles 同上
+- 循环翻页取全量（pageSize 200、上限 2000 截断提示）；页眉 `getPublicSettings()`（非管理员拿不到 `/system/settings`）
+- `window.print()`（按钮区 `@media print { display:none }`）；`@page A4 landscape`；`thead { display: table-header-group }` 每页带表头；打印态白底黑字沿用 `--ys-*`
+
+### T11 前端文档（`frontend/README.md` 改）
+
+报表页与打印视图小节 + 权限矩阵
+
+## 四、测试（模块整体完成时统一编写）
+
+### T12 后端（`tests/unit/test_report_helpers.py` + `tests/integration/test_reports.py` 新）
+
+- 单元：分桶边界（0/1/30/31/60/61/180/181/360/361/负值/NULL）；标签键集合 ⊇ CUSTOMER_TYPES ∪ PRODUCT_CATEGORIES ∪ {"mixed"}；Excel 结构断言（load_workbook 读回：页眉/合计/签字栏/number_format/注入前缀/空数据）；占比除零→0
+- 集成（factories 造数）：① 个人明细对拍 `/calc/ledger`、summary==全量和；② 部门汇总成员合计==团队基数==公司基数、`aggregate_amount==manager_team_share` 预期、生成月结后 computed==frozen；③ 无团队成员经理 0 行、离职成员计入原团队；④ 调整单生效行并入（status≠2 不计）；⑤ 回款统计空桶恒在、负绩效计入、**分摊拆行金额只计一次**；⑥ 业务统计排除 calc_type=2；⑦ 导出 200/400/审计留痕（成功与失败）；⑧ 普通 user 403（文案「无权访问报表统计」）
+
+### T13 e2e（`frontend/e2e/report_flow.py` 新）
+
+菜单可见 → 四页筛选与数字 → `page.expect_download()` 断言导出 → 打印视图注入 `window.print` 桩断言 → console 无错；造数用 API + 登录 token（远未来月份隔离，参照 calc_settlement_flow.py）
+
+### T14 收尾
+
+回归（pytest 全量 + ruff + type-check + build + e2e report_flow 与复跑两条既有脚本）；三 README 更新；提交拆分 `feat(report): 报表统计后端取数与导出` → `feat(report): 报表统计前端四页与打印视图` → `test(report): 报表模块用例与测试记录`
+
+## 五、开放项（不阻塞，随催办确认）
+
+| 事项 | 默认 |
+| --- | --- |
+| 部门口径（R1） | manager_id 实时上溯 |
+| 区间档位（R2） | 8 档代码常量 |
+| 签字栏要素（R3） | 页眉/标题/筛选/时间人/版本/复核/签字/日期 |
+| 导出上限 | 20000 行超限 400 |
+| 打印上限 | 2000 行截断提示 |
+| Excel logo | 有则嵌、无则纯文本 |

docs/待确认事项汇总_2026-10-16.md

@@ -4,26 +4,27 @@
 > 来源：《待澄清问题清单_2026-10-15.xlsx》（业务方 24 项）、《T+对接数据需求清单》v1.2.1（IT 18 项）、AI_CONTEXT 待办。
 > 答复到齐前，各模块按清单内「建议默认」执行；答复与默认不同时以答复为准。
 > **2026-10-19 更新**：业务答复落实批次与 M3 code-review 修复已落地（见各节标注）；T+ 清单已升 v1.4。
+> **2026-10-20 更新**：开发计划 3.3 已回填（3.3.1），SRS V2.1 已交付；二次分摊已按开发侧暂定口径实现（#1–#3 答复仍空白）。
 
 ## 一、立即待办（需项目内处理）
 
 | # | 事项 | 状态 | 下一步动作 |
 | --- | --- | --- | --- |
-| 1 | **推送 feat/m3-increments** | 🔄 远端已恢复 | 2026-10-19 实测 `git ls-remote` 连通；远端已推进至 35fe37f（V8/权限/增量备份），**本地领先 8 提交**（code-review 修复 4 提交 + #14 首日口径 + 相关测试/文档）——推送前与并行会话对账，避免重复推送 |
+| 1 | **推送 feat/m3-increments** | ✅ 已完成（2026-10-19） | 远端 Git 服务恢复后已推送，远端现为 e48cfb7（含 code-review 修复 4 提交 + #14 首日口径 + V8 系列 + 测试/文档）；并行会话（88：calc_service 分摊拆行）收口后继续推送其后提交 |
 | 2 | **M2 分支合并 main** | 未开始 | feat/base-business-data（M2 全部 + code-review 32 条修复）尚未合入 main；与 #1 一并处理（PR 评审或本地合并） |
 
 ## 二、业务方澄清（24 项，**2026-10-16 答复已到**，回执见《待澄清问题清单_2026-10-15(1)(2).xlsx》H 列）
 
-> 答复汇总：**12 项确认按默认执行**（#7/#8/#9/#10/#11/#13/#15/#17/#18/#21/#23/#24）；**4 项答复与默认不同，以答复为准**——#5 二次分配审批开关**默认开启**、#14 **首日整 10‰**、#16 试用期基本工资**按人员档案逐人维护**、#19 备份**加增量补充**；仍未落定见下表「答复状态」列。答复后待回填开发计划 3.3 与需求记录。
+> 答复汇总：**13 项确认按默认执行**（#7/#8/#9/#10/#11/#13/#15/#17/#18/#21/#22/#23/#24，其中 #22 为模糊确认、按不计入）；**4 项答复与默认不同，以答复为准**——#5 二次分配审批开关**默认开启**、#14 **首日整 10‰**、#16 试用期基本工资**按人员档案逐人维护**、#19 备份**加增量补充**；部分答复 3 项（#4/#6/#12），仍开放 4 项（#1–#3/#20）。开发计划 3.3 已于 2026-10-20 回填（3.3.1），未答复项仍按催办清单跟进。
 
 ### 高优先级（阻塞对应模块开工，8 项）
 
 | 清单编号 | 问题 | 建议默认（未答复时执行） | 阻塞模块 | 答复状态 |
 | --- | --- | --- | --- | --- |
-| 1 | 二次分配的分配标的：绩效金额、折算毛利润还是业绩额？ | 未答复前只做方案录入，不实现分摊（已按此交付） | ④ 分摊计算 | ❌ 未答复 |
+| 1 | 二次分配的分配标的：绩效金额、折算毛利润还是业绩额？ | 方案录入已交付；2026-10-19 已按开发侧暂定口径实现分摊拆行（非业务答复，答复后校准） | ④ 分摊计算 | ❌ 未答复 |
 | 2 | 分配比例合计不足 100% 时余额归谁？ | 余额归合同负责营销人员（仅展示不落库） | ④ 分摊计算 | ❌ 未答复 |
 | 3 | 二次分配与已作废的「协助 25% 分成」是什么关系？ | 独立新机制；协助仍仅记录不核算 | ④ | ❌ 未答复 |
-| 4 | 二次分配方案的修改窗口与权限？ | 首次月结前可改（留痕），月结后只读走调整单 | ③/④ | ⚠️ 部分：「暂定可改走调整单」，窗口/权限未定；分摊实现（88 批次）进行中 |
+| 4 | 二次分配方案的修改窗口与权限？ | 首次月结前可改（留痕），月结后只读走调整单 | ③/④ | ⚠️ 部分：「暂定可改走调整单」，窗口/权限未定；分摊已于 2026-10-19 实现（ccfd206） |
 | 6 | 营销后勤/财务/领导的角色权限清单（可见菜单/可操作点）？ | 最小授权：后勤=提交录入，财务=复核+导出，领导=审核只读 | ⑦ / permissions 激活 | ⚠️ 部分：「先预设角色」，名称与职权待客户确认；**#17 参数查看放开已落实（2026-10-19）** |
 | 8 | 回款何时算「确认回款」？ | 需人工确认动作（系统已按此预留） | ④ 月结取数 | ✅ 确认：人工确认，可手动关闭 |
 | 9 | 调整单是否走同一审批链？能否跨月调整已锁月份？ | 同一审批链；后续月份扣补为默认路径 | ④/⑦ | ✅ 确认默认；跨月需管理员授权并留痕 |
@@ -41,7 +42,7 @@
 | 15 | 支付权重「余额模式」是否需要？ | ✅ 一期只用 FULL |
 | 16 | 试用期基本工资（3000 元）是统一参数还是逐人维护？ | ✅ 已落实（2026-10-19，V8）：撤销 `probation.salary.basic` 参数，基本工资读 `personnel.salary_standard` |
 | 20 | 含税口径：毛利/运费/价税合计是否含税？ | ❌ 未答复：「需与客户再次确认具体计算方式」 |
-| 22 | 预收款/保证金/代收款是否计入绩效回款？ | ❌ 未答复：「当前未提到预收款情况」，暂按不计入 |
+| 22 | 预收款/保证金/代收款是否计入绩效回款？ | ⚠️ 模糊答复：「当前未提到预收款情况」，暂按不计入 |
 
 ### 低优先级（已有默认口径，顺手确认，7 项）
 
@@ -55,8 +56,9 @@
 | 23 | 回款按到账金额还是扣手续费净额？ | ✅ 按到账金额 |
 | 24 | 「首期不生成负绩效」与裁决「负绩效不归零」冲突，以哪个为准？ | ✅ 维持裁决：负数照算不归零、月结支持扣补（业务补注：按当前算法首期不会出现负绩效） |
 
-## 三、待 IT / T+ 侧答复（18 项，见《T+对接数据需求清单》v1.3「待IT确认事项」表）
+## 三、待 IT / T+ 侧答复（18 项 → 收敛为 13 项 + 1 组业务裁决）
 
+> **2026-10-20 更新**：T+12.3 数据字典已解析（1,457 页 / 931 张表 / 21,019 个字段），字段级映射已产出：`docs/T+字段映射草案_v0.1_2026-10-20.md`、`docs/T+对接数据需求清单_v1.5_2026-10-20.xlsx`。原 18 项收敛为 13 项 IT 待确认（每项附字典候选字段）+ 1 组业务裁决，详见催办清单第二节与 v1.5「待IT确认事项」sheet。以下原表保留为 2026-10-19 基线。
 > **2026-10-19 清单已升 v1.4**（`docs/T+对接数据需求清单_v1.4_2026-10-19.xlsx`，七节：人员/产品/业务单据/发货单/回款单/客户档案/同步完整性与补充字段）——本节口径待收编到 v1.4 后再对外；待 IT 逐项确认的状态以最新版文件为准。
 > **2026-10-16 业务方已对「口径与用途说明」修订，已收编清单升 v1.3**：#18 回款↔发货批次定稿**人工指定**（T+ 核销关系仅作辅助，`shipment_id` 保持「同步不覆盖」，v1.2.1「T+ 主源」修订作废，M2 回款页现状不动）；「确认回款」两处 #8 开放引用收敛；特殊业务标记待确认降为低优。
 > **新增追问 2 条**（随下一轮回执发业务方）：① 「负责营销人员」口径被改为「人员编码**以姓名**为唯一识别」，与「编码是业绩归属唯一锚点（防重名错钱）」矛盾，疑笔误；② 数据清单回款「关联订单号」仍写「由 T+ 收款分配关系指定，人工辅助」，与不覆盖表「人工指定」主次相反，疑漏改。
@@ -83,7 +85,7 @@
 
 | 里程碑 | 内容 | 前置条件 |
 | --- | --- | --- |
-| M3 剩余 | ✅ ④ 核算引擎 + 月结/调整单 + ⑦ 月结审批对象已完成（2026-10-17 M3-core）；**2026-10-19** 业务答复落实批次（首日 10‰/审批开关默认/试用期参数/增量备份/参数查看放开/经理基数开关）与 code-review 21 项修复已落地；**余**：二次分摊实现（#1–#3 答复空白）、业务答复回填批次收口（88 会话） | #20（含税口径）、#1–#3 答复后按同粒度推进 |
+| M3 剩余 | ✅ ④ 核算引擎 + 月结/调整单 + ⑦ 月结审批对象已完成（2026-10-17 M3-core）；**2026-10-19** 业务答复落实批次（首日 10‰/审批开关默认/试用期参数/增量备份/参数查看放开/经理基数开关）与 code-review 21 项修复已落地；二次分摊已按开发侧暂定口径实现（ccfd206），业务答复回填已完成（计划 3.3.1，2026-10-20）；**余**：#1–#3/#20 答复与 #4/#6/#12 补值 | #20（含税口径）、#1–#3 答复后按同粒度推进 |
 | M4 | ⑤ 报表（签字导出模板）+ ⑧ 工作台 | ④ 已交付；报表口径确认后启动 |
 | M4（并行） | ⑥ T+ 数据同步 | IT 答复字段映射后 |
 | code-review 遗留 2 项 | 方案生效版本承载、审批单内容快照 | ④ 分摊语义落定时一并设计 |
@@ -92,6 +94,6 @@
 ## 五、文档待办（低优）
 
 - 需规过时条款未修订（26 天示例、含运费公式、协助 25%）；2026-10-15 补充需求未回填需规——对外引用需规前须先修订或注明以对照表/计划第三章为准
-- 澄清答复已到（2026-10-16）：待回填开发计划 3.3、AI_CONTEXT、《需求规格说明书》升 V2.1；《T+对接数据需求清单》已升 **v1.4**（2026-10-19，本节口径待收编；生成脚本 build_tplus_xlsx.py 已对齐 v1.3、待对齐 v1.4）
+- 澄清答复已到（2026-10-16）：开发计划 3.3 已回填（3.3.1，2026-10-20）、SRS V2.1 已交付（2026-10-19）；《T+对接数据需求清单》已升 **v1.5**（2026-10-20，含 75 项映射 + 13 项 IT 收敛 + 不覆盖 12 条），映射草案 v0.1 已产出
 - ~~新口径待落实（业务答复与默认不同的 4 项）~~ ✅ **已全部落实（2026-10-19，见第二节标注）**
 - **修复批次引入口径记录（2026-10-19，供业务知会）**：月结的经理聚合与月工资口径按**所属月月末**取参（单笔台账行仍按回款日取参，裁决 #11）——补生成历史月份时结果不随生成日漂移；如业务对月末时点有异议，改 `settlement_service._month_end` 单点即可

docs/待答复催办清单_2026-10-19.md

@@ -0,0 +1,86 @@
+# 待答复事项催办清单（2026-10-19）
+
+> **用途**：对外跟催材料，分三块可直接拆分发送——一、业务方；二、IT/T+ 侧；三、报表口径补充确认（本轮新增）。
+> **基线**：《待澄清问题清单_2026-10-15(1)(2).xlsx》（业务 24 项，2026-10-16 已答复 19 项，其中部分答复 3 项；#1–#3/#20 仍空白）、《T+对接数据需求清单》v1.3「待IT确认事项」18 项 + v1.4（2026-10-19 勘误）、《问题与解决方案对照表_v2》（28 项已裁决口径）。
+> **原则**：已答复项不重复询问；未答复项按清单内「建议默认」执行中，答复后以答复为准并回填文档。
+
+## 一、业务方（建议回复期限：____）
+
+### A. 仍未答复 —— 阻塞对应模块开工（4 项）
+
+| # | 问题（原文口径） | 当前执行默认 | 阻塞 |
+| --- | --- | --- | --- |
+| 1 | 二次分配的分配标的是什么——绩效工资金额、折算毛利润额，还是销售额（业绩额）？ | 方案录入已交付；**分摊已按开发侧暂定口径实现**（非业务答复，答复后校准） | ④ 分摊计算 |
+| 2 | 分配比例合计不足 100% 时，剩余部分归属谁？ | 余额归合同负责营销人员（仅展示不落库） | ④ 分摊计算 |
+| 3 | 二次分配与已作废的「协助 25% 分成」是什么关系？ | 独立新机制；协助仍仅记录不核算 | ④ 分摊 |
+| 20 | 含税口径：销售/成本/毛利润/运费各项是否含税？价税合计与折扣折让如何处理？ | 按不含税口径实现中 | ④ 核算口径终验、⑥ 同步建列（是否建税率/税额列） |
+
+> 说明：#1–#3 未答复期间，二次分配方案可正常录入与审批；开发侧已按暂定口径把分摊拆行计入绩效（参与人份额×比例、负责人余额），**标的与余额归属仍待业务答复，答复后可能调整**；#20 影响历史算出的绩效是否需要按含税口径重算，越早答复返工面越小。
+
+### B. 已有答复但需补具体值 / 勾选（4 项）
+
+| # | 事项 | 需补充 |
+| --- | --- | --- |
+| 12 | 经理个人户业绩是否计入其 12.5% 团队基数 | 答复为「做参数可调」，**请给出初始值**：计入 / 不计入（系统已实现为开关参数，当前默认不计入） |
+| 14 | 「第 1 天 10‰」实现口径 | 请勾选：**A 仅首日覆盖**（推荐，保「360 天 = 6‰」锚点）或 B 整体平移（破坏锚点）。系统当前按 A 实现（首日 10‰、其余按公式 10 − 天数 × 4/360） |
+| 4 | 二次分配方案修改窗口与权限 | 答复「暂定允许修改，走调整单」——请定：首次月结前可改（留痕）？月结后只读、仅走调整单？谁有权改（管理员 / 营销后勤）？ |
+| 6 | 营销后勤/财务/领导三类角色的账号归属、可见菜单、可操作点 | 答复「先预设角色，需与客户确认」——请给权限清单（三类角色各能看什么、能操作什么）。系统已按最小授权运行：后勤=提交录入，财务=复核+导出，领导=审核只读，营销后勤暂不可见审批列表 |
+
+### C. 请确认两处勘误（已按勘误实施，需业务回执存档）（2 项）
+
+| 项 | 原表述 | 现行勘误（v1.4） |
+| --- | --- | --- |
+| 人员识别 | 「负责营销人员以姓名为唯一识别」 | 改为「以人员编码（工号）为唯一识别、姓名辅助核对」——原表述与「编码为业绩归属唯一锚点（防重名错钱）」矛盾，疑笔误，请确认 |
+| 回款↔发货批次 | 「由 T+ 收款分配关系指定，人工辅助」 | 改为「**系统人工指定**（对照表 #18 定稿），T+ 收款分配关系仅作辅助」——主次相反疑漏改，请确认 |
+
+### 已按默认执行、无需回复的项（供核阅）
+
+\#7 月结审批链默认开启、#8 人工确认回款可手动关闭、#9 调整单同链且跨月需授权、#10 风险预警参数化、#11 待办范围（待审批+同步失败+回款未指定批次）、#13 支付环节 5 默认值、#15 一期仅 FULL 模式、#17 参数查看放开/修改限管理员、#18 企业户 2‰ 回溯、#21 退货当期冲减已结算走调整单、#22 预收/保证金/代收款暂不计入、#23 按到账金额、#24 负绩效照算不归零。
+
+## 二、IT / T+ 侧（建议回复期限：____）
+
+> **2026-10-20 更新**：已用 T+12.3 数据字典完成字段级核对（1,457 页 / 931 张表 / 21,019 个字段），下列问题由 18 项收敛为 **13 项 IT 待确认 + 1 组业务裁决**，每项附字典候选字段。字段级证据与来源页见《T+字段映射草案_v0.1_2026-10-20.md》，完整清单见《T+对接数据需求清单_v1.5_2026-10-20.xlsx》。
+
+### A. 待确认（按优先级）
+
+| 新# | 原# | 事项 | 字典候选（已定位） | 仍需答复 |
+| --- | --- | --- | --- | --- |
+| 1 | 1 | 成本额字段与成本口径 | SA_SaleOrder_b.LatestCost；SA_SaleDelivery_b.costPrice/costAmount/CostPriceGetType | 取订单最新成本还是出库成本；取数时点与精度 |
+| 2 | 2+3 | 发货日与到账日口径 | 发货：voucherdate/SendDate/deliveryDate/auditeddate；到账：voucherDate/auditedDate/createdTime | 分别取哪个字段；签收日/银行到账日能否提供 |
+| 3 | 4 | 幂等键与作废重开 | 各表 code + id 主键 | code 是否终身唯一；作废重开是否换号 |
+| 4 | 5 | 三单关联与核销路径 | SA_SaleDelivery.SourceVoucherCode、_b.saleOrderCode/saleOrderId；ARAP_ReceivePayment.SaleOrderCode/SaleOrderID；ARAP_StrikeBalance | 主关联路径；分批发货/部分核销如何取 |
+| 5 | 6 | 人员编码/工号与经理隶属 | AA_Person.code/name/iddepartment；AA_Department.idparent/iddirector（无直属上级字段） | code 是否即工号；业务员→经理隶属如何维护 |
+| 6 | 7 | 对接方式与安全 | 字典不涉及 | REST/视图/中间表/文件；只读账号、接口文档、样例数据 |
+| 7 | 8 | 负数/红字/退货/冲销规则 | isCounteractDelivery、returnQuntity/backSentQuantity、voucherstate、ARAP_StrikeBalance | 实际使用形式、原单关联、是否推送 |
+| 8 | 9 | 存量起始与增量水位 | updated/createdTime/madeDate/auditedDate/ts | 存量起始日；增量用哪个时间戳；时区 |
+| 9 | 10+v1.4#18 | 客户主数据匹配与变更 | AA_Partner.code/name/Contact/representative/disabled/updated | 唯一键；改名/换负责人/合并；负责人取 Contact 还是 representative |
+| 10 | 11+16 | 收款方式与确认/核销枚举 | AA_SettleStyle；ARAP_ReceivePayment.IdSettleStyle/cancelState/voucherstate | 完整枚举与以物抵顶代码；核销状态含义与人工确认依据 |
+| 11 | 12+13 | 产品数量语义与发货单价 | ST_CurrentStock.baseQuantity；AA_InventoryPrice/AA_InventoryUnitPrice；SA_SaleDelivery_b.price/taxPrice | 数量取现存量/在途/累计销量；发货单价口径与含税 |
+| 12 | 14+17 | 低频字段存在性：特殊业务标记/市场拓展计划 | SA_SaleOrder.idbusinesstype；AA_Person 自定义项；未检出市场拓展计划表 | 有无可识别字段/表；无则人工维护 |
+| 13 | 15 | 同步窗口 | 字典不涉及 | 每周时间点，避结账/备份；失败重试策略 |
+
+### B. 口径裁决（1 组，转业务方）
+
+含税口径、退货红字冲减、预收/保证金/代收、手续费净额、负绩效表述（原 #18，对应《待澄清问题清单》#20–#24）。
+
+### C. 已由字典补齐、仅需确认可用性
+
+1. **人员编码**：字典已定位 `AA_Person.code`，请确认是否即工号；若为自动内部编码，请指明工号字段。
+2. **客户档案**：字典已定位 `AA_Partner` 主表（编码/名称/联系人/停用/地区等），请确认可提供。
+3. **映射列**：v1.5 清单已回填「T+ 表.字段 / 类型 / 枚举 / 系统目标列」，请按实际环境核对并修正。
+
+## 三、报表口径补充确认（2026-10-19 新增，随本轮开发一并排）
+
+> 报表统计模块（需规 2.4 / FR-029~FR-032）开工在即，以下三项请确认；未答复按「建议默认」实现，后续可调。
+
+| # | 事项 | 建议默认（将按此实现） |
+| --- | --- | --- |
+| R1 | 部门绩效汇总表的「部门」口径 | 部门 = 经理团队（经理 + 其直属业务员），按人员档案的隶属关系展开；离职人员历史业绩留在原团队；经理的 5% 全公司部分单独一列 |
+| R2 | 回款统计的「回款天数区间」档位 | ≤0 天（先款后货）｜1-30｜31-60｜61-90｜91-180｜181-360｜361 以上｜无回款天数，共 8 档；未命中区间显示 0 |
+| R3 | 导出/打印模板要素 | 公司信息页眉（名称+logo）、报表标题、筛选条件、导出时间与导出人、模板版本号、财务复核栏、领导签字栏、日期栏 |
+
+另：报表查看权限（FR-029 参与者含「营销后勤（授权范围内）」）——请随第一部分 B-6 权限清单一并明确营销后勤是否需要查看报表、可见哪些列。
+
+---
+
+**发送建议**：第一部分发业务方（含 C 两项勘误确认）；第二部分发 IT/T+（v1.4 附表一并）；第三部分随开发进度与业务方顺带确认。

docs/项目阶段报告_2026-10-20.md

@@ -0,0 +1,80 @@
+# 衍水集团营销人员工资管理系统项目阶段报告
+
+- **报告日期**：2026-10-20
+- **报告范围**：M4 ⑤ 报表统计、⑧ 工作台完成情况与 M4 收尾结论
+- **项目分支**：`feat/m3-increments`（已合并 `main`，merge commit `3611474`）
+- **阶段结论**：除 ⑥ T+ 数据同步受外部答复阻塞外，十大功能块全部交付；后端全量 **862 用例通过**，报表、工作台、核算月结三条 e2e 链路实跑通过。
+
+## 一、3P 阶段摘要
+
+### Progress（进展）
+
+M4 两块（⑤ 报表统计、⑧ 工作台）已完成并通过 code-review 修复。报表侧交付个人绩效明细、部门汇总、业务统计、回款统计四张报表、Excel 签字导出与独立打印视图；工作台侧交付经营总览、待办事项、风险预警、最近动态四区块，待办与预警实时派生并参数化。本阶段同时完成 M4 修复批次的提交、全量回归与 e2e 实跑，开发计划 3.3 答复状态已回填。
+
+### Plans（计划）
+
+下一步优先解析 T+12.3 数据字典，形成六类单据字段映射草案并自答 IT 清单中可自答部分；其次补齐 code-review 遗留的方案版本承载与审批单快照；需规 V2.2 修订与对照表回填择期进行。
+
+### Problems（问题）
+
+⑥ T+ 数据同步仍受 IT 18 项答复阻塞，同步失败类待办/预警暂以「模块未启用」显式降级。业务方仍有 #1–#3 二次分摊、#20 含税口径、#4/#6/#12 补值与两处勘误待确认；审批角色权限细目未给出，当前按 `role_code` 粗粒度运行。需规仍含已作废条款，对外引用需注明以对照表/计划第三章为准。
+
+## 二、阶段定位与完成度
+
+| 维度 | 当前状态 | 说明 |
+| --- | --- | --- |
+| 项目阶段 | 开发收尾期 | M1–M3 与 M4 ⑤⑧ 已交付，仅 ⑥ 待外部输入 |
+| 整体完成度 | 90% | 十大功能块交付；⑥ 按 0% 计入 |
+| 交付主线 | M4 报表统计 + 工作台 | 前后端闭环，已合并 main |
+| 质量状态 | 全绿 | 后端 862 passed（11:32）；e2e role_home 4/4、report 12/12、calc_settlement 8/8 |
+| 主要风险 | 外部对接与口径变更 | T+ 映射未定；含税口径未答复可能触发历史绩效重算 |
+
+## 三、已完成成果
+
+### 1. 报表统计（M4 ⑤）
+
+- 四表接口 `/api/v1/reports/*`：个人绩效明细、部门绩效汇总、业务统计、回款区间统计。
+- 部门归属按 `personnel.manager_id` 实时上溯；回款区间 8 档（≤0 / 1-30 / 31-60 / 61-90 / 91-180 / 181-360 / 361+ / 无天数）。
+- 全公司 5% 按「有聚合行经理各计一次」计算，并与月结 `total_payable` 对拍；对账块单列聚合行舍入差。
+- Excel 签字导出（openpyxl + StreamingResponse，ASCII 文件名）与独立打印视图（五块结构、每页表头、签字栏）。
+- 权限 `admin/finance/leader` 前后端双层。
+
+### 2. 工作台（M4 ⑧）
+
+- 单端点 `/api/v1/dashboard` 一次返回四区块：经营总览、待办事项、风险预警、最近动态。
+- 待办与预警**实时派生**（不落表、不引调度器）；待办按角色过滤；逾期预警排除已终止业务。
+- 预警阈值参数化：`warning.enabled`、`warning.receipt.overdue.days=90`、`warning.approval.timeout.days=3`（V10，参数注册表 22 项）。
+- 前端 `/dashboard` 四区块 + ECharts 5.6 按需引入（SVG，显式思源黑体，规避 Windows 默认雅黑）。
+- 普通用户落地页统一由 `router/access.ts` 解析（工作台 → 业务数据 → 回款），修复无限重定向。
+
+### 3. 质量与收尾
+
+- 后端全量 `uv run pytest -q` → **862 passed（11:32）**；`pnpm type-check` 与 `pnpm build` 通过。
+- e2e 实跑：`role_home_flow` 4/4、`report_flow` 12/12、`calc_settlement_flow` 8/8；`report_flow` 回款统计改为按本次业务编号下钻断言，脚本可重复运行。
+- 运行后核对：月结审批开关恢复为 1，无 `e2e_role_*` 残留账号。
+- 开发计划 3.3.1 与《待确认事项汇总》已按 24 项答复分组回填（13 默认 / 4 按答复 / 3 部分 / 4 开放）。
+
+## 四、当前进行中工作
+
+无。M4 代码与文档已提交并合并 `main`（`3611474`）。
+
+## 五、下一步计划
+
+1. **T+ 同步前置**：解析 `docs/T_12.3数据字典/`，产出人员/产品/业务/发货/回款/客户六类字段映射草案，自答 IT 18 项中可从数据字典确认的部分。
+2. **code-review 遗留 2 项**：方案生效版本承载、审批单内容快照（orders 加方案 JSON 快照列 + 前端详情展示）。
+3. **需规 V2.2**：修订 26 天示例、含运费公式、协助 25% 等过时条款，回填 2026-10-15 补充需求；对照表 v2 收编 24 项答复。
+4. **清理类**：5 处超长函数、散参数 DTO、`useDropdownOptions` 余两页、前端菜单图标。
+5. **待外部输入**：业务方催办、审批权限清单、IT 18 项答复。
+
+## 六、风险与应对
+
+| 风险 | 影响 | 应对 |
+| --- | --- | --- |
+| IT 答复持续缺失 | ⑥ 无法开工，同步类待办/预警无法真实展示 | 先做数据字典映射草案；催办清单已含高优 9 项与三缺口 |
+| 含税口径（#20）改变 | 历史绩效可能需要重算 | 当前按不含税实现；答复后评估重算范围并授权留痕 |
+| 二次分摊口径（#1–#3）改变 | 已生成台账/月结可能需要调整 | 暂定口径已标注；变更走口径调整，重算需授权留痕 |
+| 需规含作废条款 | 对外交付物误导 | 引用以对照表/计划第三章为准；V2.2 修订前排期 |
+
+## 七、报告结论
+
+M4 报表统计与工作台已完成交付并合并 `main`，系统除 ⑥ T+ 数据同步外具备完整业务闭环。质量证据充分（全量测试与三条 e2e 链路），剩余工作以外部输入与审计性技术债为主，可按计划推进。

frontend/README.md

@@ -79,38 +79,42 @@ pnpm build        # 类型检查 + 生产构建
 
 ## 视觉设计
 
-**设计立意**：公司名「衍水」是水，而中文「流水账」字面就是**流水之账**——系统的全部工作正是记录回款怎么流、绩效怎么算。视觉方向由此而生：深水面板 + 流动的层理线，即公司名的意象，也是业务的隐喻。
+**设计立意**：公司名「衍水」是水，而中文「流水账」字面就是**流水之账**——系统的全部工作正是记录回款怎么流、绩效怎么算。视觉方向由此而生：中性灰白的水面纸感 + 靛蓝点缀，安静、克制，长时间核数不累眼。完整规范见 `docs/design/视觉方向预览.html`（2026-10-12 起为 v3「质感版」）。
 
-**配色**（金色分两档是有意的：亮金只用于深色底、深金只用于浅色底，两处对比度都达标）
+**配色**（靛蓝只作重点点缀——主按钮 / 链接 / 焦点 / 当前菜单，大面积用中性灰白）
 
 | 名 | 值 | 用途 |
 | --- | --- | --- |
-| 深渊 | `#061A22` | 品牌面板底色 |
+| 靛蓝 | `#2e4ba8` | 主按钮、链接、焦点、当前菜单（配白字约 7.5:1） |
-| 沉碧 | `#0F3646` | 面板渐变、水纹线 |
+| 深靛 | `#223a85` | 主色深阶（按压态） |
-| 青金 | `#C9A227` | **深色底上**的细线与边框 |
+| 淡靛 | `#edf1fa` | 选中底色、浅色强调底 |
-| 赭金 | `#8F6520` | **浅色底上**的主按钮（配白字约 6.2:1） |
+| 纸白 | `#ffffff` | 卡片与面板底色 |
-| 素纸 | `#FAFAF7` | 表单侧底色 |
+| 雾灰 | `#f4f5f8` | 页面底色 |
-| 墨 | `#16262D` | 正文 |
+| 墨 | `#1c2333` | 正文 |
+| 墨灰 | `#5b6577` / `#9aa3b2` | 次级文本 / 辅助文本 |
 
-**字体**：品牌名用**宋体**（衬线，拟正式、拟账册），正文用系统无衬线，数字与验证码用等宽。
+**字体**：品牌名用**思源黑体**（`Noto Sans SC` / `Source Han Sans SC`，开源可商用），正文用同一无衬线栈，数字与验证码用等宽。**禁止引入微软雅黑、宋体等需商业授权的字体**——CSS 字体栈、设计稿、导出物一律只用开源或免费商用字体（如阿里巴巴普惠体、HarmonyOS Sans）。
 **界面不引入网络字体**——内网环境字体加载不可靠，靠字重、字距与留白做层次更稳妥。新页面请沿用这套字号节奏。
 
-**落地方式**：品牌色已提升为全局 CSS 变量（`src/assets/styles/index.css` 的 `:root`，`--ys-*` 前缀），登录页与布局、系统管理页面共用；全局还把 `--el-color-primary` 指向赭金，Element Plus 组件默认走品牌色。登录页 scoped 里的同名局部变量只是全局 token 的别名。
+**质感来源**（而非装饰）：表面 1–2% 明度差的微渐变、半透明描边、近距 + 远距分层阴影、内高光 / 内阴影、极微噪点（内联 SVG）、精确排版（字距 / 等宽数字 / 行高节律）。
 
-**签名元素**：品牌面板的水纹层理线，越往下越密（如潜向深处），载入时用 `stroke-dashoffset` 逐条画出——**一个统一的入场动作，而不是散落的特效**。
+**落地方式**：品牌色已提升为全局 CSS 变量（`src/assets/styles/index.css` 的 `:root`，`--ys-*` 前缀），登录页、布局与各业务页面共用；全局把 `--el-color-primary` 指向靛蓝，并按 Element Plus 公式预计算了 light-3/5/7/8/9 与 dark-2 色阶（不用 `color-mix()`，避免依赖较新浏览器特性）。旧 token 名（深水青 / 金色系列）在 `:root` 中保留映射，存量页面迁移完成后移除。
 
-**构图**：品牌内容（名称 / 金线 / 系统名 / 主标语 / 环节行）**垂直居中聚成一块**，配一层柔和径向光晕作落点。
+**签名元素**：**渐隐靛蓝水线**——仪表盘等页面标题下的细线（56px，左实右虚）与登录页品牌名下的短线（40px），「衍水」之水的提纯，全站唯一的装饰性元素；登录页右上角另有涟漪同心圆与顶部靛蓝天光作背景（低透明度）。与早期深色面板 + 水纹层理同一意象，品牌连续而非推倒重来。
+
+**构图**：登录页品牌内容（名称 / 标语 / 水线）**垂直居中聚成一块**，配一层柔和径向光晕作落点。
 早期版本用 `space-between` 把品牌与标语顶到两端，中间空出大半屏，两处都成了孤岛——超宽屏会把这种疏离放大得更明显。**内容块要限宽**（`max-width`），否则宽屏下文字会被拉散。
 
-### 写代码时的三条约定
+### 写代码时的四条约定
 
 - 覆盖 Element Plus 主题请改 **CSS 变量**（`--el-button-bg-color` 等），不要直接写 `background-color` —— 后者与 `.el-button--primary` 同权重，会受样式注入顺序影响而不稳定
 - 中文可在任意字间断行，**关键文案的断行位置要显式控制**（如主标语拆成两个 `<span>`），交给浏览器自动换行会出现单字独占一行的难看结果
 - 新页面需响应式到移动端、保留键盘焦点可见、并尊重 `prefers-reduced-motion`
+- **确认框统一加 `customClass: 'ys-confirm-box'`，不要再传 `type: 'warning'`** —— Element Plus 的默认 warning 图标会渲染在正文左侧独立成列（多行正文时图标悬在文字块中间），与 v3 靛蓝体系也冲突。全局样式（`src/assets/styles/index.css`）已把图标改为 18px 描边样式并放在标题行左侧，正文与标题文字对齐
 
 ## 验证码图片
 
-后端自绘渲染（`backend/app/core/captcha_image.py`），**不再使用 `captcha` 库的默认输出**——那是随机彩色字符 + 重噪点，与界面视觉体系冲突。自绘后字符为墨蓝、底为素纸、干扰线与噪点取自同一套配色。
+后端自绘渲染（`backend/app/core/captcha_image.py`），**不再使用 `captcha` 库的默认输出**——那是随机彩色字符 + 重噪点，与界面视觉体系冲突。自绘后字符为深青色、底为暖白、干扰线与噪点取自同一套配色。
 
 识别难度由**逐字随机旋转（±14°）+ 垂直抖动（±2px）+ 正弦干扰曲线 + 双层噪点**共同保证，与原实现相当；笔画加了 1px 描边——本系统用户是营销人员，屏幕与年龄跨度大，验证码过难会直接变成支持负担。
 
@@ -178,3 +182,51 @@ E2E_ADMIN_PASSWORD=<开发库admin密码> python e2e/system_management.py
 
 运行前置同上（需 `E2E_ADMIN_PASSWORD`）。**期间修复的缺陷**：public 端点 300s 响应缓存让登录页拿旧公司名（改 `fetch cache: no-store` + 时间戳绕过磁盘缓存）；业务弹窗分配表与产品明细共用 `items-table` 类导致选择器错位（分配表加专属 `alloc-table` 类）。
 **回归**：既有五脚本（登录 8 / 系统管理 13 / 基础数据 12 / 业务 16 / 参数 7 步）在 allowedRoles 路由扩展与品牌名动态化后全部复跑通过。
+
+## 前端页面（2026-10-19 追加 · M4 ⑤ 报表统计）
+
+| 页面 | 说明 |
+| --- | --- |
+| `/reports/personal-detail` 个人绩效明细（新组「报表统计」order19） | 人员/月份/客户类型/产品类别/岗位筛选；需规 2.4.1 全部列；行展开懒加载台账快照；页脚**全筛选合计**（注明非当前页）；导出/打印 |
+| `/reports/department-summary` 部门绩效汇总（order20） | 月份必填；全公司分成独立卡片（单经理 5% × 计入人数 = 合计，每位有聚合行的经理各计一次）；团队表（基数/团队分成/全公司分成/占比/调整/净合计/月结冻结额），净合计与月结聚合行同口径，比例列头随在线参数变化；展开成员 → 跨页下钻个人明细（人员与月份带入筛选）；未分配桶（按经理筛选时为空） |
+| `/reports/business-stats` 业务统计（order21） | 关键字/客户/归属人/状态/业务日期；发货额/回款额/绩效（累计口径提示）；展开下钻回款与台账明细 |
+| `/reports/payment-stats` 回款统计（order22） | 月份/回款日期/客户类型/产品类别；8 档区间表（空桶 0，档位由后端下发）；展开桶下钻分页明细；客户类型/产品类别对比表 |
+| `/reports/print/:code` 报表打印（顶层路由，`menu:false`） | 不挂 BasicLayout（打印不带侧栏/顶栏）；页眉公司信息走 public 端点；循环翻页取全量（以接口 total 判定超过 2000 行并提示截断）；部门汇总按「团队分成 → 全公司 5% → 对账 → 成员明细 → 未分配」五块渲染；`@media print` A4 横版 + 每页表头；签字栏；PDF 由浏览器「另存为」覆盖 |
+
+- 路由组「报表统计」四页 `allowedRoles: [admin, finance, leader]`（前端菜单 + 后端 `require_roles` 双层；admin 须显式列入）。
+- api 封装 `src/api/reports.ts`（类型 + 查询 + `exportReport` 裸 axios blob；产品类别标签额外覆盖 `mixed`）。
+- 权限：营销后勤「授权范围内」待业务权限清单 #6，当前不开放报表。
+- type-check 与 build 通过（2026-10-19）。e2e `report_flow.py` 已补 12 步：登录 → API 造数 → 四表筛选/导出下载 → 部门下钻筛选生效 → 回款多桶同时展开互不串行 → 打印视图 → 打印截断提示 → 部门汇总打印五块结构；需 `E2E_ADMIN_PASSWORD` 且前后端在跑。
+- **e2e 实跑（2026-10-20）**：`login_flow` 8/8、`system_management` 13/13、`role_home_flow` 4/4、`report_flow` 12/12、`calc_settlement_flow` 8/8 全过。`report_flow` 的回款统计改为展开目标桶后按**本次业务编号**定位明细行，不依赖桶累计值，脚本可重复运行（历史 e2e 数据累计不再造成假失败）。
+
+## 端到端测试（2026-10-19 追加 · M3 台账与月结）
+
+| 脚本 | 覆盖 | 结果 |
+| --- | --- | --- |
+| `e2e/calc_settlement_flow.py` | 绩效核算与月度结算 8 步：登录进台账页 → API 预置（客户/人员/业务/发货/回款/核算，随机远未来月份防碰撞）→ 按归属月筛选见 v1 行 → 重算对话框（原因必填）→ v2 生效 → 版本三态筛选（仅历史 / 仅当前 / 清空=全部）→ 生成月结草稿 → 提交审批（开关显式关闭=自动通过锁定）→ 详情抽屉（按人明细/净工资/锁定状态） | ✓ 全通过（2026-10-19 首跑，修复下述缺陷后） |
+
+运行前置同上（需 `E2E_ADMIN_PASSWORD`）；数据 `e2e_` 前缀 + 随机远未来月份（209x），核算/月结按设计不可删，行数据留档开发库。
+**首跑即抓出三处真实前端缺陷**（M3 台账/月结两页自 2026-10-17 交付起一直「暂无数据」）：
+① `src/api/{calc,settlements,approvals}.ts` 误用默认导出 `request`（axios 实例，返回 AxiosResponse 未解包），列表 `list` 恒为 undefined → 三页永远「暂无数据」；改为具名导入 `{ request }`（信封解包版）。
+② 三页均无 `onMounted` 初始加载 → 进页不取数；补 `onMounted(() => void load())`。
+③ 三页 `AppPagination` 用 `v-model:page-num` + `@change`（组件无该事件、也未实现 `update:*`）→ 翻页失效；统一为 `:page-num/:page-size` + `@page-change/@size-change`（usePagedList 的 onPageChange/onSizeChange）。
+**注意**：e2e 与 `pytest tests/integration` **不可并发**——conftest 每用例整体清空开发库，会清掉 e2e 造的数据造成假失败（本次排查耗时即源于此，两次假失败的报错均为「台账行消失 / 401 登录失效」）。
+
+## 前端页面（2026-10-19 追加 · M4 ⑧ 工作台）
+
+`/dashboard` 由 Bento 占位升级为工作台四区块（**一次聚合请求** `/api/v1/dashboard`）：
+
+| 区块 | 展示 |
+| --- | --- |
+| 经营绩效总览 | KPI 四卡（本月绩效/应付/核算人数/团队数 + 月结状态）；近 6 个月绩效折线 + 回款柱状（ECharts） |
+| 待办事项 | 待审批（跳审批管理）、回款未指定批次（跳回款管理）、T+ 同步失败（未启用显式占位） |
+| 风险预警 | 回款逾期（danger）/ 审批超时（warning），点击跳处理页；总开关关闭时显示参数提示 |
+| 最近动态 | 操作日志时间线，按模块本地筛选 |
+
+- **ECharts 5.6 按需引入**：`echarts/core` + `BarChart/LineChart/Grid/Tooltip` + `SVGRenderer`（与设计预览一致），只注册用到的模块。
+- **字体红线**：图表 `textStyle.fontFamily` 必须显式设为思源黑体栈——ECharts 在 Windows 默认微软雅黑（字体商用合规要求）。
+- 权限：路由 `allowedRoles: [admin, finance, leader]`，与后端 `require_roles` 双层；营销后勤待权限清单 #6。
+- **普通用户落地页**：守卫不再硬编码回 `/dashboard`，统一走 `src/router/access.ts` 的 `firstAccessiblePath`（工作台 → 业务数据 → 回款），普通用户登录/刷新/直连受限页均落 `/business/businesses`，不会无限重定向；登录回跳也经 `canAccessPath` 校验。菜单与面包屑复用同一份准入判定。
+- 预警徽标用后端 `warnings.total`（全部命中数），`items` 仅为展示上限内的子集。
+- `package.json` 新增依赖 `echarts@5.6.0`（MIT）；type-check 与 build 通过（2026-10-19）。
+- e2e `e2e/role_home_flow.py`：普通用户登录落地、菜单隐藏、刷新保持、直连 `/dashboard` 与报表页回退；需 `E2E_ADMIN_PASSWORD`。

frontend/e2e/calc_settlement_flow.py

@@ -0,0 +1,353 @@
+"""绩效核算与月度结算端到端验证（M3 ④：台账/月结两页）。
+
+覆盖真实浏览器链路（重点守 code-review 修复过的两处前端缺陷）：
+- 台账页「重算」对话框按**回款 ID** 发起重算（修复前传台账行主键，会
+  作废并重算无关回款的台账）；重算后新版本生效、旧版本翻「已替代」
+- 版本筛选三态：仅当前生效（1）/ 仅历史版本（0）/ 清空=全部（不过滤）
+  （修复前「含历史版本」传 0 只回历史行）
+- 月结页：生成快照（草稿）→ 提交审批（自动通过并锁定）→ 详情抽屉展示
+  按人明细（净工资/试用期），锁定人回显
+
+前置（API 预置；前端无「核算」入口——核算为批量动作走接口）：
+客户/人员/业务/发货/回款经 HTTP API 直建（与集成测试同形入参），核算经
+API 触发；浏览器只负责台账/月结两页的真实交互。
+
+数据说明：核算后的回款与已生成月结按设计不可删（变更只走调整单），
+本流程按 `e2e_` 前缀 + **随机远未来月份（209x）**造数——每次运行独占
+一个月份，重复运行互不碰撞；行数据留档开发库（与 business_data.py 同）。
+
+运行前置（缺一不可）：
+    docker compose up -d
+    cd backend && uv run uvicorn app.main:app --port 8000
+    cd frontend && pnpm dev
+    cd frontend && E2E_ADMIN_PASSWORD=<开发库admin密码> python e2e/calc_settlement_flow.py
+"""
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.request
+
+from playwright.sync_api import Page, sync_playwright
+
+from common import (
+    BASE_URL,
+    E2EFailure,
+    collect_console_errors,
+    current_path,
+    expect_toast,
+    fail,
+    login,
+)
+
+ADMIN = "admin"
+API_BASE = "http://127.0.0.1:8000"
+SUFFIX = f"{int(time.time())}"
+console_errors: list[str] = []
+
+_SETTLEMENT_SWITCH = "approval.monthly_settlement.enabled"
+
+
+def _api(method: str, path: str, token: str, body: dict | None = None) -> dict:
+    """直连后端接口（仅用于 API 预置；浏览器交互一律走页面）。"""
+    request = urllib.request.Request(
+        f"{API_BASE}{path}",
+        method=method,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        data=json.dumps(body).encode() if body is not None else None,
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=20) as response:
+            payload = json.loads(response.read().decode())
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode()[:200]
+        raise E2EFailure(f"API {method} {path} HTTP {exc.code}：{detail}") from exc
+    if payload.get("code") != 200:
+        raise E2EFailure(f"API {method} {path} 业务失败：{payload.get('message')}")
+    return payload["data"]
+
+
+def _set_settlement_switch(token: str, value: str) -> None:
+    """显式控制月结审批开关（用例不依赖种子默认值；结束还原默认 1）。"""
+    _api(
+        "POST",
+        "/api/v1/system/params/changes",
+        token,
+        {
+            "change_type": 1,
+            "remark": f"e2e calc_settlement_flow 设置月结审批开关={value}",
+            "items": [
+                {"param_code": _SETTLEMENT_SWITCH, "dimension_value": "", "value": value}
+            ],
+        },
+    )
+
+
+def _filter_item(page: Page, label: str):
+    """可见筛选表单中指定标签的表单项（select 带 :visible 避开隐藏实例）。"""
+    return page.locator(
+        f'.filters:visible .el-form-item:has(.el-form-item__label:text-is("{label}"))'
+    ).first
+
+
+def _query(page: Page) -> None:
+    page.locator(".filters:visible button:has-text('查询')").first.click()
+    page.wait_for_timeout(800)
+
+
+def _select_filter(page: Page, label: str, option: str) -> None:
+    item = _filter_item(page, label)
+    item.locator(".el-select").click()
+    page.wait_for_timeout(300)
+    page.locator(
+        ".el-select-dropdown:visible .el-select-dropdown__item", has_text=option
+    ).first.click()
+    page.wait_for_timeout(200)
+
+
+def step_login_and_open_ledger(page: Page, admin_password: str) -> None:
+    login(page, ADMIN, admin_password)
+    page.goto(f"{BASE_URL}/calc/ledger", wait_until="networkidle")
+    page.wait_for_timeout(600)
+    if current_path(page) != "/calc/ledger":
+        fail("导航", f"未进入绩效台账页，当前 {page.url}")
+    print("✓ 1. 登录与导航    进入绩效台账页")
+
+
+def step_setup_via_api(page: Page, month: str) -> dict:
+    """API 预置完整链路：角色 → 客户/人员 → 业务 → 发货 → 回款 → 核算。"""
+    token = page.evaluate("localStorage.getItem('ys_token')")
+    if not token:
+        fail("API 预置", "localStorage 中未取到 ys_token")
+
+    roles = _api("GET", "/api/v1/system/business-roles?pageNum=1&pageSize=50", token)["list"]
+    role_id = next((r["id"] for r in roles if r["role_code"] == "salesperson"), None)
+    if role_id is None:
+        fail("API 预置", "未找到 salesperson 岗位种子")
+
+    customer = _api(
+        "POST",
+        "/api/v1/base/customers",
+        token,
+        {
+            "company_name": f"e2e_月结客户_{SUFFIX}",
+            "owner_name": "张老板",
+            "customer_type": "personal",
+        },
+    )
+    person = _api(
+        "POST",
+        "/api/v1/base/personnel",
+        token,
+        {
+            "personnel_name": f"e2e_月结人员_{SUFFIX}",
+            "business_role_id": role_id,
+            "salary_standard": "3000.00",
+        },
+    )
+    business = _api(
+        "POST",
+        "/api/v1/business/businesses",
+        token,
+        {
+            "customer_id": customer["id"],
+            "business_date": f"{month}-01",
+            "owner_personnel_id": person["id"],
+            "items": [
+                {
+                    "product_name": f"e2e_月结产品_{SUFFIX}",
+                    "product_category": "municipal_water",
+                    "quantity": "100",
+                    "sale_price": "100.00",
+                    "cost_amount": "3000.00",
+                }
+            ],
+        },
+    )
+    shipment = _api(
+        "POST",
+        "/api/v1/business/shipments",
+        token,
+        {
+            "business_id": business["id"],
+            "ship_date": f"{month}-02",
+            "items": [{"product_name": "e2e_月结发货", "quantity": "1", "sale_price": "1.00"}],
+        },
+    )
+    receipt = _api(
+        "POST",
+        "/api/v1/business/receipts",
+        token,
+        {
+            "business_id": business["id"],
+            "receipt_date": f"{month}-15",
+            "amount": "20000.00",
+            "shipment_id": shipment["id"],
+        },
+    )
+    calc = _api("POST", f"/api/v1/calc/receipts/{receipt['id']}/calc", token)
+    if calc.get("repeated") is not False:
+        fail("API 预置", f"核算应为首算，实际 repeated={calc.get('repeated')}")
+    print(f"✓ 2. API 预置      业务 {business['business_no']} 已核算（{month}）")
+    return {
+        "token": token,
+        "month": month,
+        "business_no": business["business_no"],
+        "personnel_name": person["personnel_name"],
+    }
+
+
+def step_ledger_row_visible(page: Page, ctx: dict) -> None:
+    _filter_item(page, "归属月").locator("input").first.fill(ctx["month"])
+    _query(page)
+    row = page.locator(".el-table__row", has_text=ctx["business_no"]).first
+    if row.count() == 0:
+        fail("台账列表", f"筛选 {ctx['month']} 未见业务 {ctx['business_no']} 的台账行")
+    text = row.text_content()
+    if "v1" not in text or "已替代" in text:
+        fail("台账列表", f"首算行应为当前生效 v1，实际：「{text.strip()[:80]}」")
+    print("✓ 3. 台账筛选      首算 v1 行可见且为当前生效")
+
+
+def step_recalc_via_dialog(page: Page, ctx: dict) -> None:
+    """重算对话框：修复前按台账行主键发起，会作废无关回款的台账。"""
+    row = page.locator(".el-table__row", has_text=ctx["business_no"]).first
+    row.locator("button:has-text('重算')").click()
+    dialog = page.locator(".el-dialog:visible").last
+    dialog.wait_for(state="visible")
+    dialog.locator("textarea").fill(f"e2e 重算验证 {SUFFIX}")
+    dialog.locator("button:has-text('确认重算')").click()
+    expect_toast(page, "重算完成", "重算")
+    page.wait_for_timeout(600)
+
+    row = page.locator(".el-table__row", has_text=ctx["business_no"]).first
+    text = row.text_content()
+    if "v2" not in text:
+        fail("重算", f"重算后应显示 v2，实际：「{text.strip()[:80]}」")
+    print("✓ 4. 重算对话框    按回款 ID 重算成功，v2 生效")
+
+
+def step_version_filter(page: Page, ctx: dict) -> None:
+    # 仅历史版本：0 必须精确命中历史行（修复前「含历史版本」即传 0，语义相反）
+    _select_filter(page, "版本", "仅历史版本")
+    _query(page)
+    rows = page.locator(".el-table__row", has_text=ctx["business_no"])
+    if rows.count() != 1 or "已替代" not in rows.first.text_content():
+        fail("版本筛选", "「仅历史版本」应只剩一条带「已替代」的 v1 行")
+
+    # 清空 = 不过滤（全部版本）：v1+v2 双版本可见
+    item = _filter_item(page, "版本")
+    item.hover()
+    clear = item.locator(".el-select__clear").first
+    if clear.count() == 0:
+        fail("版本筛选", "未找到下拉清空按钮")
+    clear.click()
+    page.wait_for_timeout(200)
+    _query(page)
+    rows = page.locator(".el-table__row", has_text=ctx["business_no"])
+    texts = [rows.nth(i).text_content() for i in range(rows.count())]
+    if rows.count() != 2 or not any("已替代" in t for t in texts):
+        fail("版本筛选", f"清空后应见 v1+v2 两行，实际 {rows.count()} 行：{texts}")
+    print("✓ 5. 版本筛选      仅历史/全部三态正确（v1 已替代 + v2 生效）")
+
+
+def step_generate_settlement(page: Page, ctx: dict) -> None:
+    page.goto(f"{BASE_URL}/settlements", wait_until="networkidle")
+    page.wait_for_timeout(600)
+    page.locator('input[placeholder="结算月份 YYYY-MM"]').fill(ctx["month"])
+    page.click("button:has-text('生成月结快照')")
+    expect_toast(page, "月结已生成", "生成月结")
+
+    row = page.locator(".el-table__row", has_text=ctx["month"]).first
+    row.wait_for(state="visible")
+    text = row.text_content()
+    if "草稿" not in text:
+        fail("月结生成", f"生成后应为草稿状态，实际：「{text.strip()[:80]}」")
+    print("✓ 6. 月结生成      快照生成，草稿状态")
+
+
+def step_submit_and_locked(page: Page, ctx: dict) -> None:
+    row = page.locator(".el-table__row", has_text=ctx["month"]).first
+    row.locator("button:has-text('提交审批')").click()
+    # 开关已显式关闭（见 run 的 finally 还原）→ 自动通过并锁定
+    expect_toast(page, "月结已锁定", "提交审批")
+    page.wait_for_timeout(600)
+    row = page.locator(".el-table__row", has_text=ctx["month"]).first
+    if "已审定" not in row.text_content():
+        fail("提交审批", "提交后应显示已审定（锁定）")
+    print("✓ 7. 提交审批      自动通过并锁定（已审定）")
+
+
+def step_detail_drawer(page: Page, ctx: dict) -> None:
+    row = page.locator(".el-table__row", has_text=ctx["month"]).first
+    row.locator("button:has-text('详情')").click()
+    drawer = page.locator(".el-drawer:visible").last
+    drawer.wait_for(state="visible")
+    page.wait_for_timeout(500)
+    text = drawer.text_content()
+    if ctx["month"] not in text or "已审定" not in text:
+        fail("月结详情", f"抽屉应含月份与已审定状态，实际：「{text.strip()[:120]}」")
+    if ctx["personnel_name"] not in text:
+        fail("月结详情", f"明细应含本次人员 {ctx['personnel_name']}")
+    if "净工资" not in text:
+        fail("月结详情", "明细应含净工资列")
+    print("✓ 8. 月结详情      抽屉明细含人员/净工资/锁定状态")
+
+
+def run(page: Page) -> None:
+    collect_console_errors(page, console_errors)
+    admin_password = os.environ.get("E2E_ADMIN_PASSWORD", "")
+    if not admin_password:
+        fail("环境变量", "未设置 E2E_ADMIN_PASSWORD（开发库 admin 密码）")
+
+    # 随机远未来月份：每次运行独占一月，重复运行互不碰撞（数据留档）
+    month = f"20{random.randint(90, 99)}-{random.randint(1, 12):02d}"
+
+    step_login_and_open_ledger(page, admin_password)
+    ctx = step_setup_via_api(page, month)
+    _set_settlement_switch(ctx["token"], "0")
+    try:
+        step_ledger_row_visible(page, ctx)
+        step_recalc_via_dialog(page, ctx)
+        step_version_filter(page, ctx)
+        step_generate_settlement(page, ctx)
+        step_submit_and_locked(page, ctx)
+        step_detail_drawer(page, ctx)
+    finally:
+        # 还原审批开关默认（V8 起默认开启），中断也不遗留
+        _set_settlement_switch(ctx["token"], "1")
+
+    print(f"  （本次数据留档：{month} 已锁月结 + 客户/人员/业务 e2e_ 前缀，不可删）")
+    if console_errors:
+        fail("控制台", f"存在 {len(console_errors)} 条 JS 错误：{console_errors[:2]}")
+
+
+def main() -> int:
+    with sync_playwright() as playwright:
+        browser = playwright.chromium.launch(headless=True)
+        page = browser.new_page(viewport={"width": 1600, "height": 1000})
+        page.set_default_timeout(15000)
+        try:
+            run(page)
+        except E2EFailure as exc:
+            page.screenshot(path="e2e/failure.png", full_page=True)
+            print(f"\n  ✗ {exc}")
+            print("  已保存截图 e2e/failure.png")
+            return 1
+        except Exception as exc:  # noqa: BLE001 — 测试脚本需打印完整失败原因
+            page.screenshot(path="e2e/failure.png", full_page=True)
+            print(f"\n  ✗ 执行中断：{type(exc).__name__}: {exc}")
+            return 1
+        finally:
+            browser.close()
+    print("\n全部通过。")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

frontend/e2e/common.py

@@ -112,10 +112,12 @@ def expect_toast(page: Page, expected: str, step: str, timeout_ms: int = 5000) -
         fail(step, f"未出现提示「{expected}」，当前提示：{text or '（无）'}")
 
 
-def login(page: Page, username: str, password: str) -> None:
+def login(page: Page, username: str, password: str, expected_path: str = "/dashboard") -> None:
-    """完整登录：打开登录页 → 从 Redis 取验证码答案 → 提交 → 等待进入首页。
+    """完整登录：打开登录页 → 从 Redis 取验证码答案 → 提交 → 等待进入落地页。
 
     验证码 id 经响应监听捕获（前端把它内联在响应体里，不是 URL 参数）。
+    ``expected_path`` 按角色传入：管理员/财务/领导默认工作台，普通用户
+    落业务数据页（工作台权限收紧后守卫按角色解析首页）。
     """
     captcha_ids: list[str] = []
 
@@ -148,8 +150,8 @@ def login(page: Page, username: str, password: str) -> None:
         page.fill('input[autocomplete="off"]', answer)
         page.click("button:has-text('登 录')")
         page.wait_for_timeout(2000)
-        if current_path(page) != "/dashboard":
+        if current_path(page) != expected_path:
-            detail = f"未跳转到首页，当前 {page.url}"
+            detail = f"未跳转到 {expected_path}，当前 {page.url}"
             if message := toast_text(page):
                 detail += f"，提示：{message}"
             fail("登录", detail)

frontend/e2e/report_flow.py

@@ -0,0 +1,432 @@
+"""报表统计端到端验证（M4 ⑤：四张报表 + 打印视图）。
+
+覆盖真实浏览器链路（接口测试守不住的部分）：
+- 「报表统计」组四页菜单可见、可进入
+- 个人明细：API 预置的已核算业务出现在列表；导出触发真实下载
+- 部门汇总：经理团队行出现且团队基数非 0；全公司 5% 卡片可见
+- 业务统计：关键字筛选命中；三列统计非空
+- 回款统计：8 档区间表；目标桶（61-90 天）有金额；空桶显示 0
+- 打印视图：独立路由带出报表与签字栏；window.print 被调用
+
+前置（缺一不可）：
+    docker compose up -d
+    cd backend && uv run uvicorn app.main:app --port 8000
+    cd frontend && pnpm dev
+    cd frontend && E2E_ADMIN_PASSWORD=<开发库admin密码> python e2e/report_flow.py
+
+数据说明：核算后数据不可删（业务规则），按 `e2e_` 前缀留档开发库；
+每次运行用随机后缀隔离，断言以本次业务编号定位。
+"""
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+
+from playwright.sync_api import Page, sync_playwright
+
+from common import (
+    BASE_URL,
+    E2EFailure,
+    collect_console_errors,
+    current_path,
+    fail,
+    login,
+)
+
+ADMIN = "admin"
+SUFFIX = f"{int(time.time())}"
+console_errors: list[str] = []
+MONTH = time.strftime("%Y-%m")
+
+
+def _api(method: str, path: str, token: str, body: dict | None = None) -> dict:
+    """带令牌的轻量 API 调用（urllib，避免额外依赖）。"""
+    request = urllib.request.Request(
+        f"{BASE_URL}{path}",
+        method=method,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        data=json.dumps(body).encode() if body is not None else None,
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=20) as response:
+            payload = json.loads(response.read().decode())
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode()[:200]
+        raise E2EFailure(f"API {method} {path} HTTP {exc.code}：{detail}") from exc
+    if payload.get("code") != 200:
+        raise E2EFailure(f"API {method} {path} 业务失败：{payload.get('message')}")
+    return payload["data"]
+
+
+def step_login(page: Page, admin_password: str) -> None:
+    login(page, ADMIN, admin_password)
+    print("✓ 1. 登录")
+
+
+def step_setup_via_api(page: Page) -> dict:
+    """预置：经理 + 业务员 → 客户/业务 → 发货（60 天前）→ 回款 → 核算。"""
+    token = page.evaluate("localStorage.getItem('ys_token')")
+    if not token:
+        fail("API 预置", "localStorage 中未取到 ys_token")
+
+    roles = _api("GET", "/api/v1/system/business-roles?pageNum=1&pageSize=50", token)["list"]
+    salesperson_role = next((r["id"] for r in roles if r["role_code"] == "salesperson"), None)
+    manager_role = next((r["id"] for r in roles if r["role_code"] == "sales_manager"), None)
+    if salesperson_role is None or manager_role is None:
+        fail("API 预置", "未找到 salesperson / sales_manager 岗位种子")
+
+    manager = _api(
+        "POST",
+        "/api/v1/base/personnel",
+        token,
+        {
+            "personnel_name": f"e2e_报表现经理_{SUFFIX}",
+            "business_role_id": manager_role,
+            "salary_standard": "3000.00",
+        },
+    )
+    person = _api(
+        "POST",
+        "/api/v1/base/personnel",
+        token,
+        {
+            "personnel_name": f"e2e_报表现业务员_{SUFFIX}",
+            "business_role_id": salesperson_role,
+            "salary_standard": "3000.00",
+            "manager_id": manager["id"],
+        },
+    )
+    customer = _api(
+        "POST",
+        "/api/v1/base/customers",
+        token,
+        {
+            "company_name": f"e2e_报表客户_{SUFFIX}",
+            "owner_name": "张老板",
+            "customer_type": "personal",
+        },
+    )
+    business = _api(
+        "POST",
+        "/api/v1/business/businesses",
+        token,
+        {
+            "customer_id": customer["id"],
+            "business_date": f"{MONTH}-01",
+            "owner_personnel_id": person["id"],
+            "items": [
+                {
+                    "product_name": f"e2e_报表产品_{SUFFIX}",
+                    "product_category": "municipal_water",
+                    "quantity": "100",
+                    "sale_price": "100.00",
+                    "cost_amount": "3000.00",
+                }
+            ],
+        },
+    )
+    from datetime import date, timedelta
+
+    ship_date = (date.today() - timedelta(days=60)).isoformat()
+    shipment = _api(
+        "POST",
+        "/api/v1/business/shipments",
+        token,
+        {
+            "business_id": business["id"],
+            "ship_date": ship_date,
+            "items": [{"product_name": "e2e_报表发货", "quantity": "1", "sale_price": "1.00"}],
+        },
+    )
+    receipt = _api(
+        "POST",
+        "/api/v1/business/receipts",
+        token,
+        {
+            "business_id": business["id"],
+            "receipt_date": date.today().isoformat(),
+            "amount": "10000.00",
+            "shipment_id": shipment["id"],
+        },
+    )
+    _api("POST", f"/api/v1/calc/receipts/{receipt['id']}/calc", token)
+    print(f"✓ 2. API 预置      业务 {business['business_no']} 已核算")
+    return {
+        "month": MONTH,
+        "business_no": business["business_no"],
+        "personnel_id": person["id"],
+        "personnel_name": person["personnel_name"],
+        "manager_name": manager["personnel_name"],
+    }
+
+
+def step_personal_detail(page: Page, ctx: dict) -> None:
+    page.goto(f"{BASE_URL}/reports/personal-detail", wait_until="networkidle")
+    page.wait_for_timeout(800)
+    if current_path(page) != "/reports/personal-detail":
+        fail("导航", f"未进入个人绩效明细页，当前 {page.url}")
+
+    # 月份筛选：Element Plus 月份选择器可直接键入 YYYY-MM
+    month_input = page.locator(".filters input").first
+    month_input.fill(ctx["month"])
+    month_input.press("Enter")
+    page.locator(".filters button:has-text('查询')").first.click()
+    page.wait_for_timeout(900)
+
+    row = page.locator(".el-table__row", has_text=ctx["business_no"]).first
+    if row.count() == 0:
+        fail("个人明细", f"未找到业务 {ctx['business_no']} 的明细行")
+    print("✓ 3. 个人明细      列表命中本次核算业务")
+
+    with page.expect_download(timeout=20000) as download_info:
+        page.locator("button:has-text('导出 Excel')").first.click()
+    download = download_info.value
+    if not download.suggested_filename.endswith(".xlsx"):
+        fail("导出", f"下载文件名非 xlsx：{download.suggested_filename}")
+    print(f"✓ 4. 导出下载      {download.suggested_filename}")
+
+
+def step_department_summary(page: Page, ctx: dict) -> None:
+    page.goto(f"{BASE_URL}/reports/department-summary", wait_until="networkidle")
+    page.wait_for_timeout(900)
+    page.locator(".filters button:has-text('查询')").first.click()
+    page.wait_for_timeout(900)
+
+    row = page.locator(".el-table__row", has_text=ctx["manager_name"]).first
+    if row.count() == 0:
+        fail("部门汇总", f"未找到经理 {ctx['manager_name']} 的团队行")
+    if page.locator(".company-card").count() == 0:
+        fail("部门汇总", "全公司 5% 卡片未渲染")
+    print("✓ 5. 部门汇总      团队行与全公司卡片可见")
+
+
+def step_business_stats(page: Page, ctx: dict) -> None:
+    page.goto(f"{BASE_URL}/reports/business-stats", wait_until="networkidle")
+    page.wait_for_timeout(800)
+    keyword = page.locator(".filters input").first
+    keyword.fill(ctx["business_no"])
+    keyword.press("Enter")
+    page.locator(".filters button:has-text('查询')").first.click()
+    page.wait_for_timeout(800)
+
+    row = page.locator(".el-table__row", has_text=ctx["business_no"]).first
+    if row.count() == 0:
+        fail("业务统计", f"未找到业务 {ctx['business_no']}")
+    print("✓ 7. 业务统计      关键字筛选命中")
+
+
+def step_payment_stats(page: Page, ctx: dict) -> None:
+    page.goto(f"{BASE_URL}/reports/payment-stats", wait_until="networkidle")
+    page.wait_for_timeout(900)
+    page.locator(".filters button:has-text('查询')").first.click()
+    page.wait_for_timeout(900)
+
+    # 页面同时有区间表与两个维度对比表，必须限定主区间表
+    rows = page.locator('[data-testid="payment-bucket-table"] .el-table__row')
+    if rows.count() != 8:
+        fail("回款统计", f"区间表应为 8 行，实际 {rows.count()}")
+    bucket = page.locator(
+        '[data-testid="payment-bucket-table"] .el-table__row', has_text="61-90 天"
+    ).first
+    if bucket.count() == 0:
+        fail("回款统计", "未找到 61-90 天区间行")
+    # 按本次业务编号在下钻明细中定位，不依赖桶聚合值（历史 e2e 数据会累计到同桶）
+    bucket.locator(".el-table__expand-icon").click()
+    page.wait_for_timeout(1000)
+    drill_row = page.locator(
+        ".drill-wrap .el-table__row", has_text=ctx["business_no"]
+    ).first
+    if drill_row.count() == 0:
+        fail("回款统计", f"61-90 天桶下钻未找到本次业务 {ctx['business_no']}")
+    drill_text = drill_row.inner_text()
+    if "10000.00" not in drill_text:
+        fail("回款统计", f"本次业务下钻行金额不符：{drill_text[:120]}")
+    print("✓ 8. 回款统计      8 档区间与本次业务下钻金额正确")
+
+
+def step_payment_multi_expand(page: Page, ctx: dict) -> None:
+    """多个区间同时展开时，各自的下钻面板不能串行显示同一批明细。"""
+    page.goto(f"{BASE_URL}/reports/payment-stats", wait_until="networkidle")
+    page.wait_for_timeout(900)
+    page.locator(".filters button:has-text('查询')").first.click()
+    page.wait_for_timeout(900)
+
+    for label in ("61-90 天", "1-30 天"):
+        row = page.locator(
+            '[data-testid="payment-bucket-table"] .el-table__row', has_text=label
+        ).first
+        row.locator(".el-table__expand-icon").click()
+        page.wait_for_timeout(700)
+
+    drills = page.locator(".drill-wrap")
+    if drills.count() != 2:
+        fail("回款多桶展开", f"应展开 2 个下钻面板，实际 {drills.count()}")
+    texts = [drills.nth(index).inner_text() for index in range(2)]
+    # 面板是明细行（每笔 10000），不是桶合计；串行时两个面板文本会完全相同
+    if texts[0] == texts[1] or "10000.00" not in "".join(texts):
+        fail("回款多桶展开", "两个桶面板显示了同一批明细（drill 状态串行）")
+    print("✓ 9. 回款多桶展开  两个下钻面板互不串行")
+
+
+def step_department_drill(page: Page, ctx: dict) -> None:
+    """部门汇总「查看明细」必须把人员与月份带到个人明细页。"""
+    page.goto(f"{BASE_URL}/reports/department-summary", wait_until="networkidle")
+    page.wait_for_timeout(900)
+    page.locator(".filters button:has-text('查询')").first.click()
+    page.wait_for_timeout(900)
+
+    row = page.locator(".el-table__row", has_text=ctx["manager_name"]).first
+    row.locator(".el-table__expand-icon").click()
+    page.wait_for_timeout(500)
+    page.locator("button:has-text('查看明细')").first.click()
+    page.wait_for_timeout(900)
+
+    if f"personnel_id={ctx['personnel_id']}" not in page.url:
+        fail("部门下钻", f"URL 未携带人员筛选：{page.url}")
+    if ctx["personnel_name"] not in page.locator(".filters").inner_text():
+        fail("部门下钻", "个人明细页未应用人员筛选")
+    print("✓ 6. 部门下钻      人员与月份筛选已生效")
+
+
+def step_print_truncated(page: Page, ctx: dict) -> None:
+    """超过打印上限时必须给出截断提示（修复前提示永不出现）。"""
+
+    def handler(route) -> None:
+        rows = [
+            {
+                "ledger_id": index,
+                "business_no": f"E2E-{index}",
+                "ship_date": None,
+                "receipt_date": f"{ctx['month']}-01",
+                "payment_days": 10,
+                "product_category": "municipal_water",
+                "customer_type": "personal",
+                "role_name": "业务员",
+                "rate_text": "1",
+                "weight_r": 1,
+                "performance_amount": "1.00",
+                "payable_amount": "1.00",
+            }
+            for index in range(200)
+        ]
+        route.fulfill(
+            json={
+                "code": 200,
+                "message": "ok",
+                "data": {
+                    "list": rows,
+                    "total": 2500,
+                    "pageNum": 1,
+                    "pageSize": 200,
+                    "summary": {"row_count": 2500},
+                },
+            }
+        )
+
+    page.route("**/api/v1/reports/personal-detail*", handler)
+    try:
+        page.goto(
+            f"{BASE_URL}/reports/print/personal-detail?settlement_month={ctx['month']}",
+            wait_until="networkidle",
+        )
+        page.wait_for_timeout(1200)
+        if page.locator(".truncated").count() == 0:
+            fail("打印截断", "超过 2000 行未显示截断提示")
+        if "2000" not in page.locator(".truncated").inner_text():
+            fail("打印截断", "截断提示未说明上限行数")
+    finally:
+        page.unroute("**/api/v1/reports/personal-detail*", handler)
+    print("✓ 11. 打印截断      超限提示可见")
+
+
+def step_print_department(page: Page, ctx: dict) -> None:
+    """部门汇总打印稿必须含团队分成、5% 块、对账、成员与未分配五块。"""
+    page.goto(
+        f"{BASE_URL}/reports/print/department-summary?settlement_month={ctx['month']}",
+        wait_until="networkidle",
+    )
+    page.wait_for_timeout(1200)
+    for testid in (
+        "print-department-teams",
+        "print-company-block",
+        "print-reconciliation",
+        "print-department-members",
+        "print-unassigned",
+    ):
+        if page.locator(f'[data-testid="{testid}"]').count() == 0:
+            fail("部门打印", f"缺少区块 {testid}")
+    if "财务复核" not in page.locator(".print-page").inner_text():
+        fail("部门打印", "签字栏缺失")
+    print("✓ 12. 部门打印      五块结构与签字栏完整")
+
+
+def step_print_view(page: Page, ctx: dict) -> None:
+    page.add_init_script("window.print = () => { window.__printed = true }")
+    page.goto(
+        f"{BASE_URL}/reports/print/personal-detail?settlement_month={ctx['month']}",
+        wait_until="networkidle",
+    )
+    page.wait_for_timeout(1200)
+    if page.locator(".sheet-table").count() == 0:
+        fail("打印视图", "报表表格未渲染")
+    text = page.locator(".print-page").inner_text()
+    if "财务复核" not in text or "领导签字" not in text:
+        fail("打印视图", "签字栏缺失")
+    page.locator("button:has-text('打印')").first.click()
+    page.wait_for_timeout(400)
+    if page.evaluate("window.__printed") is not True:
+        fail("打印视图", "window.print 未被调用")
+    print("✓ 10. 打印视图      表格/签字栏/打印调用均正常")
+
+
+def run(page: Page) -> None:
+    collect_console_errors(page, console_errors)
+    admin_password = os.environ.get("E2E_ADMIN_PASSWORD", "")
+    if not admin_password:
+        fail("环境变量", "未设置 E2E_ADMIN_PASSWORD（开发库 admin 密码）")
+
+    step_login(page, admin_password)
+    ctx = step_setup_via_api(page)
+    step_personal_detail(page, ctx)
+    step_department_summary(page, ctx)
+    step_department_drill(page, ctx)
+    step_business_stats(page, ctx)
+    step_payment_stats(page, ctx)
+    step_payment_multi_expand(page, ctx)
+    step_print_view(page, ctx)
+    step_print_truncated(page, ctx)
+    step_print_department(page, ctx)
+
+    if console_errors:
+        print(f"  （控制台错误 {len(console_errors)} 条：{console_errors[:2]}）")
+
+
+def main() -> int:
+    with sync_playwright() as playwright:
+        browser = playwright.chromium.launch(headless=True)
+        page = browser.new_page(viewport={"width": 1600, "height": 1000})
+        page.set_default_timeout(15000)
+        try:
+            run(page)
+        except E2EFailure as exc:
+            page.screenshot(path="e2e/failure.png", full_page=True)
+            print(f"\n  ✗ {exc}")
+            print("  已保存截图 e2e/failure.png")
+            return 1
+        except Exception as exc:  # noqa: BLE001 — 测试脚本需打印完整失败原因
+            page.screenshot(path="e2e/failure.png", full_page=True)
+            print(f"\n  ✗ 执行中断：{type(exc).__name__}: {exc}")
+            return 1
+        finally:
+            browser.close()
+    print("\n全部通过。")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

frontend/e2e/role_home_flow.py

@@ -0,0 +1,141 @@
+"""浏览器端到端验证：普通用户落地页与路由守卫回退。
+
+工作台收紧为 admin/finance/leader 后，登录默认页不能硬编码 `/dashboard`
+（普通用户会被无限重定向）。本脚本验证：
+
+- 普通用户登录后落业务数据页，不出现「无权访问」提示
+- 侧边菜单不出现首页/系统管理/报表统计
+- 刷新后仍保持登录态与落地页
+- 直连 `/dashboard` 或报表页时回退业务数据页并给出权限提示
+
+运行前置：容器、后端 8000、前端 5173 均在运行；设置 ``E2E_ADMIN_PASSWORD``。
+
+运行::
+
+    cd frontend && E2E_ADMIN_PASSWORD=<密码> python e2e/role_home_flow.py
+"""
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+import uuid
+
+from playwright.sync_api import Page, sync_playwright
+
+from common import BASE_URL, E2EFailure, current_path, fail, login, toast_text
+
+ADMIN = "admin"
+USERNAME = f"e2e_role_{int(time.time())}_{uuid.uuid4().hex[:4]}"
+PASSWORD = "E2eRole@2026"
+HOME_PATH = "/business/businesses"
+
+
+def _api(method: str, path: str, token: str, body: dict | None = None) -> dict:
+    """带令牌的轻量 API 调用（urllib，避免额外依赖）。"""
+    request = urllib.request.Request(
+        f"{BASE_URL}{path}",
+        method=method,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        data=json.dumps(body).encode() if body is not None else None,
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=20) as response:
+            payload = json.loads(response.read().decode())
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode()[:200]
+        raise E2EFailure(f"API {method} {path} HTTP {exc.code}：{detail}") from exc
+    if payload.get("code") != 200:
+        raise E2EFailure(f"API {method} {path} 业务失败：{payload.get('message')}")
+    return payload["data"]
+
+
+def _token(page: Page) -> str:
+    token = page.evaluate("localStorage.getItem('ys_token')")
+    if not token:
+        fail("API", "未取到登录令牌")
+    return token
+
+
+def _create_user(page: Page) -> dict:
+    return _api(
+        "POST",
+        "/api/v1/system/users",
+        _token(page),
+        {
+            "username": USERNAME,
+            "password": PASSWORD,
+            "real_name": "E2E普通用户",
+            "roles": ["user"],
+        },
+    )
+
+
+def run(page: Page) -> None:
+    admin_password = os.environ.get("E2E_ADMIN_PASSWORD", "")
+    if not admin_password:
+        fail("环境变量", "未设置 E2E_ADMIN_PASSWORD（开发库 admin 密码）")
+
+    login(page, ADMIN, admin_password)
+    user = _create_user(page)
+    try:
+        page.evaluate("localStorage.clear()")
+        login(page, USERNAME, PASSWORD, expected_path=HOME_PATH)
+        page.wait_for_timeout(500)
+        print("✓ 1. 普通用户登录 落地业务数据页")
+
+        menu_text = page.locator(".app-menu").inner_text()
+        for forbidden in ("首页", "系统管理", "报表统计"):
+            if forbidden in menu_text:
+                fail("菜单权限", f"普通用户看到了「{forbidden}」菜单")
+        print("✓ 2. 菜单权限     首页/系统管理/报表统计均不可见")
+
+        page.reload(wait_until="networkidle")
+        page.wait_for_timeout(600)
+        if current_path(page) != HOME_PATH:
+            fail("刷新恢复", f"刷新后未保持落地页，当前 {page.url}")
+        print("✓ 3. 刷新恢复     登录态与落地页保持")
+
+        for path in ("/dashboard", "/reports/personal-detail"):
+            page.goto(f"{BASE_URL}{path}", wait_until="networkidle")
+            page.wait_for_timeout(800)
+            if current_path(page) != HOME_PATH:
+                fail("路由守卫", f"直连 {path} 未回退业务数据页，当前 {page.url}")
+            if "无权访问该页面" not in toast_text(page):
+                fail("路由守卫", f"直连 {path} 未给出权限提示")
+        print("✓ 4. 路由守卫     受限页均回退业务数据页并提示")
+    finally:
+        # 无论用例是否失败都清理测试账号（重新以 admin 登录取令牌）
+        page.evaluate("localStorage.clear()")
+        login(page, ADMIN, admin_password)
+        _api("DELETE", f"/api/v1/system/users/{user['id']}", _token(page))
+
+
+def main() -> int:
+    with sync_playwright() as playwright:
+        browser = playwright.chromium.launch(headless=True)
+        page = browser.new_page(viewport={"width": 1440, "height": 900})
+        page.set_default_timeout(15000)
+        try:
+            run(page)
+        except E2EFailure as exc:
+            page.screenshot(path="e2e/failure.png", full_page=True)
+            print(f"\n  ✗ {exc}")
+            print("  已保存截图 e2e/failure.png")
+            return 1
+        except Exception as exc:  # noqa: BLE001 — 测试脚本需打印完整失败原因
+            page.screenshot(path="e2e/failure.png", full_page=True)
+            print(f"\n  ✗ 执行中断：{type(exc).__name__}: {exc}")
+            return 1
+        finally:
+            browser.close()
+    print("\n全部通过。")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

frontend/e2e/system_management.py

@@ -249,18 +249,18 @@ def step_permission_check(page: Page, admin_password: str) -> None:
     page.click("text=退出登录")
     page.wait_for_url("**/login**", timeout=10_000)
 
-    login(page, VIEWER_USERNAME, E2E_PASSWORD)
+    login(page, VIEWER_USERNAME, E2E_PASSWORD, expected_path="/business/businesses")
     if page.locator(".app-menu").get_by_text("系统管理", exact=True).count() != 0:
         fail("菜单权限", "普通用户看到了「系统管理」菜单")
     print("✓ 11. 菜单权限   普通用户看不到「系统管理」分组")
 
     page.goto(f"{BASE_URL}/system/users", wait_until="networkidle")
     page.wait_for_timeout(800)
-    if current_path(page) != "/dashboard":
+    if current_path(page) != "/business/businesses":
         fail("路由守卫", f"普通用户直连管理页未被弹回，当前 {page.url}")
     if "需要管理员权限" not in toast_text(page):
         fail("路由守卫", "直连管理页未给出权限提示")
-    print("✓ 12. 路由守卫   直连 /system/users 被弹回首页")
+    print("✓ 12. 路由守卫   直连 /system/users 被弹回业务数据页")
 
     page.click("text=退出登录")
     page.wait_for_url("**/login**", timeout=10_000)

frontend/index.html

@@ -3,6 +3,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!-- 默认站点图标：未配置公司 logo 时使用（配置后由 settings store 动态替换） -->
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>衍水集团营销人员工资管理系统</title>
   </head>
   <body>

frontend/package.json

@@ -13,6 +13,7 @@
   "dependencies": {
     "@vue/devtools-api": "^8.1.5",
     "axios": "^1.20.0",
+    "echarts": "^5.6.0",
     "element-plus": "^2.14.7",
     "pinia": "^4.0.3",
     "vue": "^3.5.43",

frontend/pnpm-lock.yaml

@@ -14,6 +14,9 @@ importers:
       axios:
         specifier: ^1.20.0
         version: 1.20.0(debug@4.4.3)
+      echarts:
+        specifier: ^5.6.0
+        version: 5.6.0
       element-plus:
         specifier: ^2.14.7
         version: 2.14.7(vue@3.5.43(typescript@5.9.3))
@@ -399,6 +402,9 @@ packages:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
     engines: {node: '>= 0.4'}
 
+  echarts@5.6.0:
+    resolution: {integrity: sha512-oTbVTsXfKuEhxftHqL5xprgLoc0k7uScAwtryCgWF6hPYFLRwOUHiFmHGCBKP5NPFNkDVopOieyUqYGH8Fa3kA==}
+
   element-plus@2.14.7:
     resolution: {integrity: sha512-lrG7pZyCS+mpCNVpzxxyu5r35+T6V0hzkAeIwn7HA6to772XSTHKuYCZG51OfzlqaxGbNegLxs650zAF1j43gA==}
     peerDependencies:
@@ -693,6 +699,9 @@ packages:
     resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
     engines: {node: '>=12.0.0'}
 
+  tslib@2.3.0:
+    resolution: {integrity: sha512-N82ooyxVNm6h1riLCoyS9e3fuJ3AMG2zIZs2Gd1ATcSFjSA23Q0fzjjZeh0jbJvWVDZ0cJT8yaNNaaXHzueNjg==}
+
   typescript@5.9.3:
     resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
     engines: {node: '>=14.17'}
@@ -828,6 +837,9 @@ packages:
   webpack-virtual-modules@0.6.2:
     resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
 
+  zrender@5.6.1:
+    resolution: {integrity: sha512-OFXkDJKcrlx5su2XbzJvj/34Q3m6PvyCZkVPHGYpcCJ52ek4U/ymZyfuV1nKE23AyBJ51E/6Yr0mhZ7xGTO4ag==}
+
 snapshots:
 
   '@babel/helper-string-parser@7.29.7': {}
@@ -1155,6 +1167,11 @@ snapshots:
       es-errors: 1.3.0
       gopd: 1.2.0
 
+  echarts@5.6.0:
+    dependencies:
+      tslib: 2.3.0
+      zrender: 5.6.1
+
   element-plus@2.14.7(vue@3.5.43(typescript@5.9.3)):
     dependencies:
       '@ctrl/tinycolor': 4.2.1
@@ -1435,6 +1452,8 @@ snapshots:
       fdir: 6.5.0(picomatch@4.0.7)
       picomatch: 4.0.7
 
+  tslib@2.3.0: {}
+
   typescript@5.9.3: {}
 
   ufo@1.6.4: {}
@@ -1521,3 +1540,7 @@ snapshots:
       typescript: 5.9.3
 
   webpack-virtual-modules@0.6.2: {}
+
+  zrender@5.6.1:
+    dependencies:
+      tslib: 2.3.0

frontend/public/favicon.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <defs>
+    <linearGradient id="brand" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4a66c4" />
+      <stop offset="1" stop-color="#2e4ba8" />
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="url(#brand)" />
+  <text
+    x="32"
+    y="43"
+    text-anchor="middle"
+    font-family="'Noto Sans SC', 'Microsoft YaHei', 'PingFang SC', sans-serif"
+    font-size="32"
+    font-weight="600"
+    fill="#ffffff"
+  >衍</text>
+</svg>

frontend/src/App.vue

@@ -1,5 +1,31 @@
 <script setup lang="ts">
+import { watch } from 'vue'
+import { useRoute } from 'vue-router'
+
+import { useSettingsStore } from '@/store/settings'
+
 // 根组件只承载路由出口；布局由各页面自行决定
+const route = useRoute()
+const settingsStore = useSettingsStore()
+
+/**
+ * 浏览器标题 =「页面名 - 公司名 系统副标题」，跟随公司信息设置动态变化。
+ *
+ * 用 watch 而非 router.afterEach：品牌信息是异步载入的（匿名端点），
+ * afterEach 执行时只能取到当时的旧值；watch 在公司信息载入/设置页保存
+ * 后自动重算标题，无需等下一次路由跳转。
+ */
+watch(
+  () => [route.meta.title, settingsStore.brandTitle] as const,
+  () => {
+    const title = route.meta.title as string | undefined
+    document.title = title ? `${title} - ${settingsStore.brandTitle}` : settingsStore.brandTitle
+  },
+  { immediate: true },
+)
+
+// 品牌信息全局只载入一次（登录页/布局另有调用，内部去重）
+void settingsStore.ensureLoaded()
 </script>
 
 <template>

frontend/src/api/approvals.ts

@@ -1,4 +1,4 @@
-import request from './request'
+import { request } from './request'
 import type { PageData } from './types'
 
 /** 审批单状态：1待财务复核 2待领导审核 3已通过 4已驳回 5已撤回 */

frontend/src/api/businessRoles.ts

@@ -45,13 +45,26 @@ export interface BusinessRoleUpdateParams {
   sort_order?: number
 }
 
-/** 分页查询岗位角色（含停用） */
+/** 岗位下拉选项（登录即可；基础数据与报表筛选用，含停用） */
+export interface BusinessRoleOption {
+  id: number
+  role_code: string
+  role_name: string
+  status: number
+}
+
+/** 分页查询岗位角色（含停用，仅管理员） */
 export function listBusinessRoles(
   params: BusinessRoleQueryParams,
 ): Promise<PageData<BusinessRoleItem>> {
   return request({ url: '/v1/system/business-roles', method: 'get', params })
 }
 
+/** 只读岗位选项：财务/领导做报表筛选时不走管理员接口 */
+export function listBusinessRoleOptions(): Promise<BusinessRoleOption[]> {
+  return request({ url: '/v1/base/business-roles/options', method: 'get' })
+}
+
 /** 新增岗位 */
 export function createBusinessRole(
   data: BusinessRoleCreateParams,

frontend/src/api/calc.ts

@@ -1,4 +1,4 @@
-import request from './request'
+import { request } from './request'
 import type { PageData } from './types'
 
 /** 绩效台账行（金额/比例一律 str） */

frontend/src/api/customers.ts

@@ -21,6 +21,10 @@ export interface CustomerItem {
   owner_personnel_id: number | null
   owner_personnel_name: string | null
   remark: string | null
+  /** 评级总分（字符串直出，未评级为 null；等级由总分判定、同向） */
+  rating_total: string | null
+  /** 评级等级快照（保存时点固化；未评级/未命中为 null） */
+  rating_grade_name: string | null
 }
 
 export interface CustomerQueryParams {
@@ -30,6 +34,10 @@ export interface CustomerQueryParams {
   keyword?: string
   customer_type?: string
   owner_personnel_id?: number
+  /** 排序字段白名单：rating = 客户评级总分（后端校验，非法值 400） */
+  order_field?: 'rating'
+  /** 排序方向；未评级恒在末尾（后端 NULLS LAST 模拟） */
+  order_type?: 'asc' | 'desc'
 }
 
 /** 新增客户（owner_personnel_id 为初始归属，可空：先建档后派归属也合法） */

frontend/src/api/dashboard.ts

@@ -0,0 +1,99 @@
+import { request } from './request'
+
+/** 近 6 个月趋势点（绩效按台账归属月，回款按到账月） */
+export interface TrendPoint {
+  month: string
+  performance_total: string | null
+  receipt_total: string | null
+}
+
+export interface SettlementBrief {
+  exists: boolean
+  status: number | null
+  total_performance: string | null
+  total_payable: string | null
+  locked_at: string | null
+}
+
+export interface OverviewBlock {
+  month: string
+  performance_total: string | null
+  payable_total: string | null
+  person_count: number
+  team_count: number
+  settlement: SettlementBrief
+  trend: TrendPoint[]
+  note: string
+}
+
+export interface ApprovalTodoItem {
+  order_id: number
+  order_no: string
+  order_type: number
+  submitter_name: string | null
+  create_time: string
+}
+
+export interface ReceiptTodoItem {
+  receipt_id: number
+  receipt_batch_no: string
+  business_id: number
+  business_no: string | null
+  amount: string
+  receipt_date: string
+}
+
+export interface TodoBlock {
+  pending_approval_total: number
+  pending_approvals: ApprovalTodoItem[]
+  unassigned_receipt_total: number
+  unassigned_receipts: ReceiptTodoItem[]
+  sync_available: boolean
+  sync_failure_total: number
+}
+
+export interface WarningItem {
+  code: string
+  level: 'warning' | 'danger'
+  object_type: string
+  object_id: number
+  title: string
+  detail: string
+  suggest: string
+  link: string | null
+}
+
+export interface WarningBlock {
+  enabled: boolean
+  receipt_overdue_days: number
+  approval_timeout_days: number
+  /** 当前返回的条目（受展示上限约束） */
+  items: WarningItem[]
+  /** 全部规则命中总数；徽标计数用它，不能用 items.length */
+  total: number
+  receipt_overdue_total: number
+  approval_timeout_total: number
+  sync_available: boolean
+}
+
+export interface ActivityItem {
+  id: number
+  module: string
+  action: string
+  summary: string
+  username: string | null
+  success: number
+  create_time: string
+}
+
+export interface DashboardData {
+  month: string
+  overview: OverviewBlock
+  todos: TodoBlock
+  warnings: WarningBlock
+  activities: ActivityItem[]
+}
+
+export function getDashboard(params: { month?: string }): Promise<DashboardData> {
+  return request({ url: '/v1/dashboard', method: 'get', params })
+}

frontend/src/api/params.ts

@@ -23,6 +23,26 @@ export interface ParamCatalogItem {
   values: ParamDimensionValue[]
 }
 
+/**
+ * 枚举参数值 → 中文（展示层翻译；库与接口仍存英文码，审计口径不变）。
+ *
+ * 业界惯例（RuoYi 字典标签同款）：映射单一出处，避免页内复制漂移；
+ * 未知码原样回显 —— 后端新增枚举项而前端未跟上时不会显示成空。
+ */
+export const PARAM_ENUM_LABELS: Record<string, string> = {
+  FULL: '当月全额',
+  BALANCE: '余额',
+  INCLUDE: '含基本工资',
+  DEDUCT: '扣除基本工资',
+  EXCLUDE: '不计基本工资',
+  '0': '关',
+  '1': '开',
+}
+
+export function paramEnumLabel(code: string): string {
+  return PARAM_ENUM_LABELS[code] ?? code
+}
+
 /** 参数目录（asOf 缺省为今日） */
 export function getCatalog(asOf?: string): Promise<ParamCatalogItem[]> {
   return request({ url: '/v1/system/params', method: 'get', params: asOf ? { as_of: asOf } : {} })

frontend/src/api/ratings.ts

@@ -54,7 +54,57 @@ export function updateRatingGrade(
   return request({ url: `/v1/business/rating-grades/${gradeId}`, method: 'put', data })
 }
 
-/** 删除评级等级（物理删除，等级表无下游引用，允许清空后由列表空态提示） */
+/**
+ * 删除评级等级（物理删除；客户评级行快照固化等级名、无外键引用，删等级
+ * 不伤已评级客户的历史结论；允许清空，新评级等级记为 null）。
+ */
 export function deleteRatingGrade(gradeId: number): Promise<null> {
   return request({ url: `/v1/business/rating-grades/${gradeId}`, method: 'delete' })
 }
+
+// ==================== 客户评级（每客户一行，落库） ====================
+
+/**
+ * 客户当前评级（对应后端 `CustomerRatingOut`）。
+ *
+ * 分值按红线以字符串直出（比较前显式 parseFloat）；total_score 由服务端
+ * 按五项重算。grade_name 是保存时点的等级**快照**（无外键），可能为 null
+ * （总分未命中任何等级 / 当时等级表为空）。
+ */
+export interface CustomerRatingItem {
+  customer_id: number
+  score_ship_amount: string
+  score_receipt_rate: string
+  score_profit_rate: string
+  score_contract_cooperation: string
+  score_site_construction: string
+  total_score: string
+  grade_name: string | null
+  remark: string | null
+  scorer_name: string
+  create_time: string
+  update_time: string
+}
+
+/** 保存评级入参：五项 0-20 数字字符串；总分与等级由服务端重算 */
+export interface CustomerRatingParams {
+  score_ship_amount: string
+  score_receipt_rate: string
+  score_profit_rate: string
+  score_contract_cooperation: string
+  score_site_construction: string
+  remark?: string
+}
+
+/** 查某客户当前评级；未评级时 data 为 null（正常态，不是错误） */
+export function getCustomerRating(customerId: number): Promise<CustomerRatingItem | null> {
+  return request({ url: `/v1/base/customers/${customerId}/rating`, method: 'get' })
+}
+
+/** 保存客户评级（upsert：首次创建、再次保存整体覆盖） */
+export function saveCustomerRating(
+  customerId: number,
+  data: CustomerRatingParams,
+): Promise<CustomerRatingItem> {
+  return request({ url: `/v1/base/customers/${customerId}/rating`, method: 'put', data })
+}

frontend/src/api/reports.ts

@@ -0,0 +1,265 @@
+import service, { request } from './request'
+import type { PageData } from './types'
+
+/** 报表分页：标准分页四字段 + 全筛选合计（summary 非当前页合计） */
+export interface ReportSummary {
+  row_count: number
+  performance_total?: string | null
+  payable_total?: string | null
+  converted_profit_total?: string | null
+  ship_total?: string | null
+  received_total?: string | null
+  sale_total?: string | null
+}
+
+export interface ReportPage<T> extends PageData<T> {
+  summary: ReportSummary
+}
+
+/** 个人绩效明细行（金额/比例一律字符串，前端不做数值运算） */
+export interface PersonalDetailRow {
+  ledger_id: number
+  business_id: number
+  business_no: string
+  personnel_id: number
+  personnel_name: string
+  role_code: string
+  role_name: string
+  customer_type: string
+  product_category: string
+  ship_date: string | null
+  receipt_date: string
+  payment_days: number | null
+  rate_text: string
+  weight_r: number | null
+  payment_weight: string | null
+  performance_amount: string | null
+  payable_amount: string | null
+  converted_profit: string | null
+  is_probation: number
+  missing_cost: number
+  calc_version: number
+  settlement_id: number | null
+}
+
+export interface DepartmentMemberRow {
+  personnel_id: number
+  personnel_name: string
+  role_code: string
+  is_probation: number
+  /** regular 普通台账 / manager_personal 经理个人户 / adjustment 仅调整单 */
+  member_kind: string
+  unassigned_reason: string | null
+  performance_sum: string | null
+  payable_sum: string | null
+  adjust_extra: string
+  adjust_deduct: string
+  adjust_net: string
+  net_total: string | null
+  ledger_ids: number[]
+}
+
+export interface DepartmentTeamRow {
+  manager_id: number
+  manager_name: string
+  manager_status: number
+  member_count: number
+  team_base: string
+  team_share_amount: string
+  /** 单经理 5% 名义值；无月结聚合行时为 0（不发放） */
+  company_share_amount: string
+  /** 本月是否有月结聚合行（决定是否发放 5%） */
+  has_aggregate: boolean
+  /** 月结聚合行应发（12.5%+5% 一次舍入）；无聚合行时 0 */
+  aggregate_amount: string
+  /** 团队应发小计 = 聚合行金额 + 调整净额 */
+  team_subtotal: string
+  company_base_ratio: string
+  adjust_extra: string
+  adjust_deduct: string
+  adjust_net: string
+  net_total: string
+  frozen_amount: string | null
+  aggregate_ledger_id: number | null
+  members: DepartmentMemberRow[]
+}
+
+/** 签字稿对账块：应发 = 成员应付 + 未分配应付 + 聚合行金额 + 调整净额 */
+export interface DepartmentReconciliation {
+  team_member_payable_total: string
+  unassigned_payable_total: string
+  team_share_total: string
+  company_share_total: string
+  aggregate_payable_total: string
+  aggregate_rounding_diff: string
+  adjust_net_total: string
+  payable_total: string
+  team_base_total: string
+  unassigned_performance_total: string
+  other_team_base: string
+  other_team_member_payable_total: string
+  other_team_share_total: string
+  other_team_company_share_total: string
+  other_team_aggregate_total: string
+  other_adjust_net_total: string
+  company_base: string
+}
+
+export interface DepartmentSummary {
+  settlement_month: string
+  params: {
+    team_text: string
+    company_text: string
+    manager_personal_included: number
+    params_as_of: string
+  } | null
+  teams: DepartmentTeamRow[]
+  unassigned: DepartmentMemberRow[]
+  company: {
+    team_base_total: string
+    company_base: string
+    company_share_pct: string
+    /** 单经理 5% 名义值 */
+    company_share_amount: string
+    /** 计入应发的经理数（有聚合行） */
+    company_share_count: number
+    /** 5% 合计 = 单份 × 计入次数 */
+    company_share_total: string
+  } | null
+  reconciliation: DepartmentReconciliation | null
+  totals: Record<string, string>
+}
+
+export interface BusinessStatsRow {
+  business_id: number
+  business_no: string
+  business_date: string | null
+  status: number
+  customer_name: string | null
+  owner_personnel_name: string | null
+  total_sale_amount: string | null
+  total_ship_amount: string | null
+  total_received_amount: string | null
+  performance_amount: string | null
+  payable_amount: string | null
+}
+
+export interface BucketRow {
+  code: string
+  label: string
+  min_days: number | null
+  max_days: number | null
+  receipt_amount: string | null
+  receipt_count: number
+  performance_amount: string | null
+  payable_amount: string | null
+  ledger_count: number
+}
+
+export interface GroupRow {
+  code: string
+  label: string
+  receipt_amount: string | null
+  performance_amount: string | null
+  payable_amount: string | null
+  ledger_count: number
+}
+
+export interface PaymentStats {
+  settlement_month: string | null
+  buckets: BucketRow[]
+  by_customer_type: GroupRow[]
+  by_product_category: GroupRow[]
+  totals: Record<string, string | number>
+}
+
+export interface PaymentDetailRow {
+  ledger_id: number
+  receipt_id: number | null
+  receipt_batch_no: string | null
+  amount: string | null
+  business_id: number
+  business_no: string
+  personnel_id: number
+  personnel_name: string
+  customer_type: string
+  product_category: string
+  ship_date: string | null
+  receipt_date: string
+  payment_days: number | null
+  performance_amount: string | null
+  payable_amount: string | null
+}
+
+/** 报表查询通用筛选（各页按需取用） */
+export interface ReportFilterParams {
+  pageNum?: number
+  pageSize?: number
+  settlement_month?: string
+  personnel_id?: number
+  customer_type?: string
+  product_category?: string
+  role_code?: string
+  manager_id?: number
+  keyword?: string
+  customer_id?: number
+  owner_personnel_id?: number
+  status?: number
+  date_from?: string
+  date_to?: string
+  bucket?: string
+}
+
+export function listPersonalDetail(
+  params: ReportFilterParams,
+): Promise<ReportPage<PersonalDetailRow>> {
+  return request({ url: '/v1/reports/personal-detail', method: 'get', params })
+}
+
+export function getDepartmentSummary(params: ReportFilterParams): Promise<DepartmentSummary> {
+  return request({ url: '/v1/reports/department-summary', method: 'get', params })
+}
+
+export function listBusinessStats(
+  params: ReportFilterParams,
+): Promise<ReportPage<BusinessStatsRow>> {
+  return request({ url: '/v1/reports/business-stats', method: 'get', params })
+}
+
+export function getPaymentStats(params: ReportFilterParams): Promise<PaymentStats> {
+  return request({ url: '/v1/reports/payment-stats', method: 'get', params })
+}
+
+export function listPaymentDetail(
+  params: ReportFilterParams,
+): Promise<ReportPage<PaymentDetailRow>> {
+  return request({ url: '/v1/reports/payment-detail', method: 'get', params })
+}
+
+export function getPaymentDayBuckets(): Promise<
+  { code: string; label: string; min_days: number | null; max_days: number | null }[]
+> {
+  return request({ url: '/v1/reports/payment-day-buckets', method: 'get' })
+}
+
+/**
+ * 导出报表（文件流）。走 axios 实例（带令牌）而非 request 封装：响应是
+ * xlsx 文件流，不是统一信封，拦截器已对 responseType=blob 直通。
+ * 服务端文件名是 ASCII（HTTP 头 latin-1 限制），中文名由调用方 link.download 指定。
+ */
+export async function exportReport(
+  code: 'personal-detail' | 'department-summary' | 'business-stats' | 'payment-stats',
+  params: ReportFilterParams,
+): Promise<Blob> {
+  const response = await service.get(`/v1/reports/${code}/export`, {
+    params,
+    responseType: 'blob',
+  })
+  return response.data as Blob
+}
+
+/** 产品类别展示名：报表需额外覆盖「混合业务」（台账行可为 mixed） */
+export function reportCategoryLabel(code: string): string {
+  if (code === 'mixed') return '混合业务'
+  return { municipal_water: '市政水利', rail_transit: '轨道交通' }[code] ?? code
+}

frontend/src/api/settings.ts

@@ -1,37 +1,64 @@
-import service, { request } from './request'
+import { request } from './request'
 
-/** 公司信息（管理端） */
+/**
+ * 公司信息与站点信息（管理端）。
+ *
+ * 2026-10-20 精简：删除系统副标题与企业档案字段（信用代码/地址/电话/邮箱），
+ * 新增站点标题（浏览器标签页/侧边栏副标题）与站点图标（标签页 favicon）。
+ * 展示字段全部可空：null 表示未配置，前端回退内置默认值。
+ */
 export interface CompanySettings {
   company_name: string
-  /** 未上传时为 null */
+  /** 登录页品牌位 logo；未上传时为 null */
   logo_url: string | null
+  site_title: string | null
+  brand_slogan: string | null
+  footer_text: string | null
+  icp_no: string | null
+  /** 浏览器标签页图标；未上传时为 null（前端用内置 favicon.svg） */
+  favicon_url: string | null
 }
 
-/** 匿名端点出参（登录页消费；与后端 SettingPublicOut 白名单一致） */
+/** 匿名端点出参（登录页/浏览器标签页消费；与后端 SettingPublicOut 白名单一致） */
-export interface PublicSettings {
+export type PublicSettings = CompanySettings
-  company_name: string
+
-  logo_url: string | null
+/**
+ * 更新入参：**部分更新**语义 —— 仅携带的字段生效，未携带字段保持不变。
+ * 可选文本传空串等价清空（后端落库 null、前端回退默认）。
+ */
+export interface SettingsUpdatePayload {
+  company_name?: string
+  site_title?: string
+  brand_slogan?: string
+  footer_text?: string
+  icp_no?: string
 }
 
 export function getSettings(): Promise<CompanySettings> {
   return request({ url: '/v1/system/settings', method: 'get' })
 }
 
-export function updateSettings(companyName: string): Promise<CompanySettings> {
+export function updateSettings(payload: SettingsUpdatePayload): Promise<CompanySettings> {
-  return request({
+  return request({ url: '/v1/system/settings', method: 'put', data: payload })
-    url: '/v1/system/settings',
-    method: 'put',
-    data: { company_name: companyName },
-  })
 }
 
-/** logo 上传走独立的 FormData（multipart，非 JSON） */
+/**
+ * 图片上传走独立的 FormData（multipart，非 JSON）。
+ *
+ * 经统一 request 封装解包信封（响应形如 {code,message,data}）；Content-Type
+ * 交给浏览器/axios 为 FormData 自动生成（含 boundary），不手工设置。
+ */
 export function uploadLogo(file: File): Promise<CompanySettings> {
   const form = new FormData()
   form.append('file', file)
-  return service.post('/v1/system/settings/logo', form, {
+  return request({ url: '/v1/system/settings/logo', method: 'post', data: form })
-    headers: { 'Content-Type': 'multipart/form-data' },
+}
-  })
+
+/** 站点图标上传（浏览器标签页；png/jpg/ico ≤2MB） */
+export function uploadFavicon(file: File): Promise<CompanySettings> {
+  const form = new FormData()
+  form.append('file', file)
+  return request({ url: '/v1/system/settings/favicon', method: 'post', data: form })
 }
 
 /** 登录页消费：无令牌也可调用（后端白名单端点）。

frontend/src/api/settlements.ts

@@ -1,4 +1,4 @@
-import request from './request'
+import { request } from './request'
 import type { PageData } from './types'
 
 /** 月结状态：1草稿 2待审批 3已审定（=已锁定）4已驳回 */

frontend/src/assets/styles/index.css

@@ -30,8 +30,12 @@
   --ys-text: #1c2333;
   --ys-muted: #5b6577;
 
-  /* 品牌字：思源黑体（实施时自托管 4 字子集，内网可用） */
+  /*
-  --ys-font-brand: 'Noto Sans SC', 'PingFang SC', 'Microsoft YaHei', sans-serif;
+   * 品牌字：思源黑体（实施时自托管 4 字子集，内网可用）。
+   * 栈内只用开源/免费商用字体 —— 微软雅黑、宋体等需商业授权的系统字体不得入栈。
+   */
+  --ys-font-brand: 'Noto Sans SC', 'Source Han Sans SC', 'HarmonyOS Sans SC', 'PingFang SC',
+    sans-serif;
 
   /*
    * Element Plus 主色 = 靛蓝（白字对比约 7.5:1）。
@@ -60,8 +64,9 @@ body,
 }
 
 body {
-  font-family: 'Helvetica Neue', Helvetica, 'PingFang SC', 'Hiragino Sans GB',
+  /* 与品牌栈同源：开源字体优先；Helvetica/Arial 仅为西文回退（系统自带，不涉字体文件分发） */
-    'Microsoft YaHei', Arial, sans-serif;
+  font-family: 'Noto Sans SC', 'Source Han Sans SC', 'HarmonyOS Sans SC', 'PingFang SC',
+    'Helvetica Neue', Arial, sans-serif;
   font-size: 14px;
   color: var(--ys-ink);
   background-color: var(--ys-mist);
@@ -76,3 +81,38 @@ body {
 .toolbar {
   margin-bottom: 12px;
 }
+
+/*
+ * 确认框（ElMessageBox）统一视觉
+ *
+ * Element Plus 默认把 warning 图标渲染在正文左侧、与正文并排成两列：
+ * 多行正文时图标悬在文字块中间，左侧留出一列空白，标题行反而是空的；
+ * 实心黄圆也与本站「中性灰白 + 靛蓝点缀」体系冲突。
+ * 这里去掉调用处的 type，把图标改画在标题行左侧：18px 描边样式，
+ * 深琥珀 #b7791f + 浅琥珀底 #fbf3e4（警示语义，饱和度压到与靛蓝同级）；
+ * 正文与标题文字左对齐，图标单独悬挂在左侧。图标为 CSS 伪元素，天然不进无障碍树，
+ * 属于装饰元素，语义由标题文字承载。
+ * MessageBox 挂载在 body 下，scoped 样式够不到，因此放在全局文件。
+ */
+.ys-confirm-box .el-message-box__title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+  color: var(--ys-ink);
+}
+
+.ys-confirm-box .el-message-box__title::before {
+  content: '';
+  flex: none;
+  width: 18px;
+  height: 18px;
+  background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='18' height='18' viewBox='0 0 18 18' fill='none'%3E%3Ccircle cx='9' cy='9' r='8.25' fill='%23FBF3E4'/%3E%3Ccircle cx='9' cy='9' r='7.4' stroke='%23B7791F' stroke-width='1.3'/%3E%3Cpath d='M9 5.3V9.8' stroke='%23B7791F' stroke-width='1.5' stroke-linecap='round'/%3E%3Ccircle cx='9' cy='12.4' r='0.95' fill='%23B7791F'/%3E%3C/svg%3E")
+    center / 18px 18px no-repeat;
+}
+
+.ys-confirm-box .el-message-box__message {
+  /* 与标题文字对齐，让图标单独悬挂在左侧：18px 图标 + 8px gap */
+  padding-left: 26px;
+  color: var(--ys-ink-2);
+}

frontend/src/assets/styles/table-actions.css

@@ -0,0 +1,57 @@
+/*
+ * 表格操作列统一样式。
+ *
+ * 用法：用 <div class="table-actions"> 包住该行的操作按钮；破坏性动作
+ * （删除/禁用等）前插入 <span class="table-actions__divider"></span> 分组。
+ * 列宽须容纳整行动作的自然宽度，否则 Element Plus 会把末尾按钮折到第二行。
+ */
+.table-actions {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+  white-space: nowrap;
+}
+
+/* 间距统一交给 gap，抵消相邻按钮默认的 12px 外边距 */
+.table-actions .el-button + .el-button {
+  margin-left: 0;
+}
+
+/*
+ * 带 title 提示或 tooltip 的按钮常包在 span 里。行内盒的基线留白会让包装
+ * 按钮比直接子按钮低约 1.7px，改为 flex 后与整行严格垂直对齐。
+ */
+.table-actions > span:not(.table-actions__divider) {
+  display: flex;
+  align-items: center;
+}
+
+/* 悬停加深并加下划线：Element 默认悬停变浅，浅靛蓝在表格底色上对比度不足 */
+.table-actions .el-button.is-link:hover {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+.table-actions .el-button.is-link.el-button--primary:hover {
+  color: var(--el-color-primary-dark-2);
+}
+
+.table-actions .el-button.is-link.el-button--success:hover {
+  color: var(--el-color-success-dark-2);
+}
+
+.table-actions .el-button.is-link.el-button--warning:hover {
+  color: var(--el-color-warning-dark-2);
+}
+
+.table-actions .el-button.is-link.el-button--danger:hover {
+  color: var(--el-color-danger-dark-2);
+}
+
+.table-actions__divider {
+  flex: none;
+  width: 1px;
+  height: 12px;
+  background-color: var(--ys-line);
+}

frontend/src/components/layout/BasicLayout.vue

@@ -1,23 +1,34 @@
 <script setup lang="ts">
-import { computed, ref, watch } from 'vue'
+import { computed, onMounted, ref, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { ElMessage } from 'element-plus'
 
 import AppMenu from '@/components/layout/AppMenu.vue'
+import { firstAccessiblePath } from '@/router/access'
+import { useSettingsStore } from '@/store/settings'
 import { useUserStore } from '@/store/user'
 
 /** 基础布局：左侧品牌导航（窄屏收为抽屉）+ 顶栏（面包屑/用户/退出）+ 内容区。 */
 const route = useRoute()
 const router = useRouter()
 const userStore = useUserStore()
+const settingsStore = useSettingsStore()
+
+// 品牌区（名称/副标题/logo）来自公司信息设置；App 已全局载入一次，这里兜底
+onMounted(() => {
+  void settingsStore.ensureLoaded()
+})
 
 const drawerVisible = ref(false)
 
+/** 「首页」按角色解析：普通用户没有工作台权限，固定链到业务数据页 */
+const homePath = computed(() => firstAccessiblePath(router, userStore.roles))
+
 /** 面包屑：首页 + 分组（如有）+ 当前页标题（首页自身不重复） */
 const breadcrumbs = computed<string[]>(() => {
   const items: string[] = []
   if (route.meta.group) items.push(route.meta.group)
-  if (route.meta.title && route.path !== '/dashboard') items.push(route.meta.title)
+  if (route.meta.title && route.path !== homePath.value) items.push(route.meta.title)
   return items
 })
 
@@ -40,8 +51,8 @@ async function handleLogout(): Promise<void> {
   <el-container class="app-layout">
     <el-aside class="app-aside" width="220px">
       <div class="app-brand">
-        <span class="app-brand__name">衍水集团</span>
+        <span class="app-brand__name">{{ settingsStore.companyName }}</span>
-        <span class="app-brand__sub">营销人员工资管理系统</span>
+        <span class="app-brand__sub">{{ settingsStore.siteTitle }}</span>
         <span class="app-brand__line"></span>
       </div>
       <AppMenu class="app-aside__menu" />
@@ -66,7 +77,7 @@ async function handleLogout(): Promise<void> {
             </svg>
           </button>
           <el-breadcrumb separator="/">
-            <el-breadcrumb-item :to="{ path: '/dashboard' }">首页</el-breadcrumb-item>
+            <el-breadcrumb-item :to="{ path: homePath }">首页</el-breadcrumb-item>
             <el-breadcrumb-item v-for="item in breadcrumbs" :key="item">
               {{ item }}
             </el-breadcrumb-item>
@@ -95,8 +106,8 @@ async function handleLogout(): Promise<void> {
       :with-header="false"
     >
       <div class="app-brand">
-        <span class="app-brand__name">衍水集团</span>
+        <span class="app-brand__name">{{ settingsStore.companyName }}</span>
-        <span class="app-brand__sub">营销人员工资管理系统</span>
+        <span class="app-brand__sub">{{ settingsStore.siteTitle }}</span>
         <span class="app-brand__line"></span>
       </div>
       <AppMenu />

frontend/src/composables/useAppMenu.ts

@@ -1,8 +1,8 @@
 import { computed } from 'vue'
 import { useRouter } from 'vue-router'
 
+import { canAccessRoute, isMenuRecord } from '@/router/access'
 import { useUserStore } from '@/store/user'
-import { ROLE_ADMIN } from '@/utils/constants'
 
 /** 菜单节点：从路由表派生，避免菜单标题与页面标题两处维护漂移。 */
 export interface MenuNode {
@@ -30,19 +30,13 @@ export function useAppMenu() {
   const router = useRouter()
   const userStore = useUserStore()
 
-  const isAdmin = computed(() => userStore.roles.includes(ROLE_ADMIN))
   const userRoles = computed(() => userStore.roles)
 
   const menuNodes = computed<MenuNode[]>(() =>
     router
       .getRoutes()
-      .filter((record) => Boolean(record.meta.title) && record.meta.menu !== false)
+      // 准入规则与路由守卫、落地页解析共用，避免三处漂移
-      .filter((record) => !record.meta.requiresAdmin || isAdmin.value)
+      .filter((record) => isMenuRecord(record) && canAccessRoute(record, userRoles.value))
-      // 职能页面（审批等）：任一列入角色命中即可见（admin 须显式列入集合）
-      .filter(
-        (record) =>
-          !record.meta.allowedRoles || record.meta.allowedRoles.some((role) => userRoles.value.includes(role)),
-      )
       .map((record) => ({
         path: record.path,
         title: record.meta.title ?? '',