docs: 补充文案约定与侧栏层级说明

- backend/README 新增「面向业务人员的文案」约定：param_registry 的
  description 是唯一显示源、枚举值在页面上必须翻译、报错要给下一步、
  init-dev.sql 种子必须与 registry 同源、模板层禁止出现开发者语汇
- frontend/README 增补侧栏层级口径、最近动态独立分页端点，以及分页的
  两个坑（v-loading 不要罩到分页条上、翻页失败必须退回实际显示页）
- backend/tests/README 记录本轮运行结果

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

backend/README.md

@@ -264,6 +264,17 @@ bcrypt 5.0 起对超过 72 字节的密码**直接抛 ValueError**（此前是
 - **汇总 = 明细合计**：团队/公司基数由台账分桶结果直接得出，报表侧不另算一遍；未筛选时 `团队基数 + 未分配绩效 = 全公司基数`；集成测试逐项断言。
 - **岗位筛选选项**：`GET /api/v1/base/business-roles/options` 仅要求登录（含停用岗位），供财务/领导在报表中按岗位筛选；岗位管理接口仍仅管理员。
 
+### 面向业务人员的文案（2026-10-23 定稿，改文案前先读）
+
+系统由财务与营销人员日常使用，**不是给开发者看的**。凡是会渲染到页面的文本（参数说明、错误提示、口径注释）一律按业务语言写：
+
+- **`param_registry.py` 的 `description` 是唯一显示源**，会直出到「计提参数」页参数名下方。写清「这个参数管什么、钱怎么变、什么时候该调它」，不写英文枚举名（`FULL`/`BALANCE`）、需求编号（`澄清 #10`）、内部阶段号（`M3`/`M4 ⑧`）、实现层精度约束（「禁止按 0.011111 截断存储」留在代码注释与测试里）。
+- **枚举值在页面上必须翻译**：前端 `params/index.vue` 的 `ENUM_VALUE_LABELS`（`FULL` 当月全额 / `BALANCE` 余额 / `INCLUDE` 含基本工资 / `DEDUCT` 扣除基本工资 / `EXCLUDE` 不计基本工资 / `1` 开 / `0` 关）与 `DIMENSION_LABELS`（`municipal_water` 市政水利 / `rail_transit` 轨道交通）。后端报错也不许把原始枚举值甩给用户 —— `param_service._preview_rate` 的产品类别校验用 `「市政水利、轨道交通」` 而不是 `municipal_water / rail_transit`。
+- **公式模板报错用中文模板名**：`calc_templates.TEMPLATES[code].name`，取不到才回退 code；文案要给出下一步（「请在岗位角色里改用业务员递减或信息员固定计提」），而不是只说「不支持」。
+- **`db/init/init-dev.sql` 的种子 description 必须与 registry 同源**：它只在数据卷为空时首次启动执行，已有库要跑 `ai-aux/preview/sync_param_desc.py`（读 `PARAM_REGISTRY` 逐条 UPDATE）才看得到新文案。`db/migration/V*.sql` 里的旧描述是历史记录，**不要回头改** —— 改了会让已部署库与脚本不一致。
+- **前端模板层禁止出现开发者语汇**：`澄清 / 待业务 / M3 / M4 / 一期 / 二阶段 / 暂口径 / 待确认 / 待接 / 暂不 / 待补` 只允许出现在代码注释里。改完用 grep 扫一遍 `frontend/src/views`。
+- **台账与预览里落库的说明文字（`rate_text` / `rate_note` / 聚合行 `snapshot_json.note`）同样受管**：这些会出现在绩效台账、个人明细、打印稿与计算预览上。写成「这笔为什么是这个比例、什么时候不再降」（如「回款 20 天，从起始 10‰ 按日递减（满 360 天后固定按 4‰ 计算）」），不写 `基数开关=1`、`#12 参数化`、`9.8 方案公式` 这类需求编号。**分数原文（`11/1125`）与百分比拼装（`聚合:20%+5%`）不算说明文字**，那是金额口径的可复核原文，不要为了「口语化」把它改成四舍五入的小数。
+
 ## 常见问题
 
 **起服务报 `APP_SECRET_KEY` 相关错误** —— `backend/.env` 未填或不足 32 字符。这是刻意的 fail-fast：空密钥签发 JWT 是安全问题，必须启动即失败。

backend/tests/README.md

@@ -209,6 +209,9 @@ uv run pytest tests/integration -q   # 仅集成
 | 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-23 | 参数文案中文化 | 单元 526 + 参数集成 24 | ✅ 526 passed（45.15s）/ 24 passed（10.60s） | **计提参数页全面中文化**：`param_registry` 22 条 `description` 改写为业务语言（去掉「澄清 #10」「M3」「禁止按 0.011111 截断」等开发者语汇），`db/init/init-dev.sql` 种子同源同步；`param_service` 模板报错改中文模板名、产品类别报错去掉英文枚举；`dashboard_service` 概览口径说明重写。**这些文案无测试断言**（`rate_text` 断言 `11/1125`、`聚合:20%+5%` 未动），故用例数不变、全绿即口径未被破坏。ruff 绿；前端 `pnpm type-check` 绿 |
+| 2026-10-23 | 台账/预览的计提说明口语化 | 单元 526 + 集成 87（calc/settlements/param/reports） | ✅ 526 passed（47.29s）/ 87 passed（7:41） | **`rate_text`/`rate_note`/聚合行 `note` 改业务话**：`企业户固定计提比例`→「企业户：不按回款天数，统一按固定比例计提」、`业务员递减：10‰ 起，20 天（分界 360 天…）`→「回款 20 天，从起始 10‰ 按日递减（满 360 天后固定按 4‰ 计算）」、`信息员：本人销售额 × 计提比例`→「信息员：按本人销售额乘计提比例，不随回款天数递减」、聚合行 `#12 参数化：基数不含经理个人户业绩；9.8 方案公式`→「团队分成：基数不含经理本人名下业绩，按本团队与全公司两级比例合计计提」。**用例同步**：`test_经理聚合口径_预览拒绝` 原断言消息含「聚合」，改为断言含「营销经理」+「月度结算」（守「拒绝且给下一步」，不再绑定措辞）；`rate_text` 的 `11/1125`、`聚合:20%+5%` 断言未动（那是分数原文与百分比拼装，非说明文案） |
+
 ## 四、测试发现并修复的缺陷
 
 | 日期 | 缺陷 | 影响 | 处理 |

frontend/README.md

@@ -141,6 +141,8 @@ pnpm build        # 类型检查 + 生产构建
 
 **菜单图标**（2026-10-22 落地，M1 遗留项）：路由 `meta.icon` 只写**语义 key**，图标实现集中在 `src/components/layout/menuIcons.ts` 的注册表（`@element-plus/icons-vue` 具名导入，可摇树）。换图标库或换风格只改注册表，路由表不动。视觉口径沿用设计稿：16px、透明度 0.7（激活项 1）、右间距 9px；分组标题**不加图标**，只有菜单项有。**新增页面必须补 `meta.icon`**，否则菜单项只有文字。注册表是 **UTF-8** 文件——批量转码脚本会把中文注释转成乱码（2026-10-23 已在该文件踩过一次，已修回），改这个文件不要过任何编码转换。
 
+**侧栏层级**（2026-10-23 改版）：组标题与菜单项**同字号 13px**——层级靠「折叠箭头 + 组间留白 + 子项缩进 12px」表达，不靠字号/字重压过父级。前两版都不采用：11px 弱墨「目录行」让父级弱于子项，14px/600 加靛蓝竖标又让父级刻意压过子项、像一排小标题在喊叫。激活态只保留**白底浮起 + 靛蓝字**，不再叠左侧 2px 竖条——竖条只能落在侧栏内边缘、与白底悬空，是重复的第二个信号。菜单横向 10px 留白由 `AppMenu.vue` 的 `.app-menu` 提供，`BasicLayout.vue` 的 `.app-aside__menu` 只写上下内距：两处都用 `padding` 简写会同权重靠注入顺序决胜，横向留白会被整条抹掉、条目贴到侧栏边缘。
+
 **签名元素**：**渐隐靛蓝水线**——各页面标题下的细线（56px，左实右虚）与登录页品牌名下的短线（40px），「衍水」之水的提纯，全站唯一的装饰性元素；登录页右上角另有涟漪同心圆与顶部靛蓝天光作背景（低透明度）。与早期深色面板 + 水纹层理同一意象，品牌连续而非推倒重来。
 
 **打印视图**（`views/reports/print/`）：纸面产物与屏幕稿不同源——独立顶层路由、不挂侧栏顶栏，白灰画布上一张定宽白稿纸，表格 11px 细实线、表头浅底左对齐（数值列表头右对齐）、章节编号、三栏签字（制表 / 复核 / 审批），无圆角无阴影。屏幕上的操作条带 `.no-print`，打印时整块消失。超出打印行数上限时只打前 N 行并在稿面明确提示，不静默截断。
@@ -148,7 +150,7 @@ pnpm build        # 类型检查 + 生产构建
 **构图**：登录页品牌内容（名称 / 标语 / 水线）**垂直居中聚成一块**，配一层柔和径向光晕作落点。
 早期版本用 `space-between` 把品牌与标语顶到两端，中间空出大半屏，两处都成了孤岛——超宽屏会把这种疏离放大得更明显。**内容块要限宽**（`max-width`），否则宽屏下文字会被拉散。
 
-### 写代码时的五条约定
+### 写代码时的六条约定
 
 - 覆盖 Element Plus 主题请改 **CSS 变量**（`--el-button-bg-color` 等），不要直接写 `background-color` —— 后者与 `.el-button--primary` 同权重，会受样式注入顺序影响而不稳定
 - 中文可在任意字间断行，**关键文案的断行位置要显式控制**（如主标语拆成两个 `<span>`），交给浏览器自动换行会出现单字独占一行的难看结果
@@ -156,6 +158,7 @@ pnpm build        # 类型检查 + 生产构建
 - **确认框统一加 `customClass: 'ys-confirm-box'`，不要再传 `type: 'warning'`** —— Element Plus 的默认 warning 图标会渲染在正文左侧独立成列（多行正文时图标悬在文字块中间），与 v3 靛蓝体系也冲突。全局样式（`src/assets/styles/index.css`）已把图标改为 18px 描边样式并放在标题行左侧，正文与标题文字对齐
 - **页面 scoped 里只写本页特有的东西**：表格 / 按钮 / 输入框 / 表头 / 分页的皮肤已经全局覆盖，页面再写一遍与组件库同权重，会受样式注入顺序影响而不稳定；结构用全局类（见上一节表格），样式只补本页独有的块（如展开区、抽屉内的键值表）
 - **状态 / 结果列的固定宽度要按胶囊内容给足**：`.cell` 左右各 16px 内距（共 32px），2 字胶囊约 55px、3 字约 67px、4 字约 79px，宽度不够时 Element Plus 会在胶囊右侧画一个省略号（看起来像多了个小点）。口径：2 字列 ≥96px（如 启用/禁用、成功/失败）、3 字列 ≥108px（如 已核算/已替代/执行中）、4 字列 ≥120px（如 以物抵顶）
+- **`v-loading` 只罩数据区，不要罩到分页条上**：遮罩会拦截指针事件，盖住分页器后用户点翻页其实点在遮罩上被吞掉，得再点一次，观感就是「数据反复变化」。详见下文「分页与「数据反复变化」的两个坑」
 
 ## 验证码图片
 
@@ -259,14 +262,20 @@ E2E_ADMIN_PASSWORD=<开发库admin密码> python e2e/system_management.py
 
 ## 前端页面（2026-10-19 追加 · M4 ⑧ 工作台）
 
-`/dashboard` 由 Bento 占位升级为工作台四区块（**一次聚合请求** `/api/v1/dashboard`）：
+`/dashboard` 由 Bento 占位升级为工作台（**总览/待办/预警一次聚合请求** `/api/v1/dashboard`；最近动态是分页列表，走独立端点）：
 
 | 区块 | 展示 |
 | --- | --- |
 | 经营绩效总览 | KPI 四卡（本月绩效/应付/核算人数/团队数 + 月结状态）；近 6 个月绩效折线 + 回款柱状（ECharts） |
 | 待办事项 | 待审批（跳审批管理）、回款未指定批次（跳回款管理）、T+ 同步失败（未启用显式占位） |
 | 风险预警 | 回款逾期（danger）/ 审批超时（warning），点击跳处理页；总开关关闭时显示参数提示 |
-| 最近动态 | 操作日志时间线，按模块本地筛选 |
+| 最近动态 | 操作日志列表，**服务端分页**（每页 10/20/50）+ 按模块筛选 |
+
+- **最近动态独立分页端点**（2026-10-23）：`GET /api/v1/dashboard/activities?pageNum&pageSize&module`，返回 `list/total/pageNum/pageSize/modules`（`modules` 是全量模块名，供下拉用，不随翻页变化）。与聚合端点拆开的原因：操作日志可能很长，塞进聚合响应只能截断前 20 条；拆开后**翻页只重取这张列表**，不必重算总览/待办/预警。分页字段沿用全站规范（`pageNum`/`pageSize`/`total`），组件用统一的 `AppPagination` + `usePagedList`（含请求序号防竞态）。
+- **分页与「数据反复变化」的两个坑（2026-10-23 实测定位并修复，改分页相关代码前先读）**：
+  1. **`v-loading` 不能挂在包含分页条的容器上**。Element Plus 的遮罩会拦截指针事件：遮罩一出现，用户点的「上一页 / 下一页」其实点在遮罩上被吞掉，必须再点一次才生效，观感就是「页码和数据对不上、来回跳」。工作台最近动态原先 `v-loading` 挂在 `.activity-body`（同时包住列表与分页条），已改为只罩列表的 `.activity-list-wrap`；其余列表页的 `v-loading` 都挂在 `el-table` 上，分页条在表格之外，天然没有这个问题——**新增页面请照此办理**。
+  2. **翻页失败必须把分页器退回「屏幕上正在显示的那一页」**。`records` 只在请求成功时更新，而分页器高亮绑的是 `pageNum`；失败不回滚就会出现「高亮第 1 页、列表是第 2 页的数据」的永久错位（用户来回点才恢复）。`usePagedList` 里用 `shownPageNum` / `shownPageSize` 记录实际显示的页，失败时 `restoreShownPage(seq)` 退回；**回滚本身也要防竞态**——只有本次请求仍是最新请求（`seq === requestSeq`）才回滚，否则连点时旧请求失败会把用户刚点出的新页码覆盖掉，表现为「页码自己跳回去」。页码与条数在 `await` 之前取快照，避免等待期间被别的点击改动后记错「显示的页」。
+  - 两个缺陷都用 Playwright 探针实测过：`ai-aux/preview/probe_pager7.py`（8/8：正常连点、请求在飞时命中分页器而非遮罩、失败回滚、解除注入后恢复）、`probe_pager13.py`（旧请求失败不拉回页码）、`probe_pager14.py`（点第 3 页失败退回第 1 页、连续两次失败仍停在当前页、解除注入后可正常翻页）、`probe_pager8.py`（其它 `usePagedList` 列表页回归）。
 
 - **ECharts 5.6 按需引入**：`echarts/core` + `BarChart/LineChart/Grid/Tooltip` + `SVGRenderer`（与设计预览一致），只注册用到的模块。
 - **字体红线**：图表 `textStyle.fontFamily` 必须显式设为思源黑体栈——ECharts 在 Windows 默认微软雅黑（字体商用合规要求）。