wangjianlong_0626
4766e3bd98
feat(benefit): 客户权益功能（T010）+ 修投顾迁移契约里写死 head 的脆弱断言
## 1. 新增客户权益（用户端）
`GET /api/v1/users/me/entitlements`（T010，权限 `benefit:read:self`）：
- **层级**由 `fin_customer_profile.total_asset` **实时判定**
（门槛来自 `knowledge/product/高净值客户服务规范.md`：
金卡 50 万 / 白金 200 万 / 钻石 600 万 / 私行 1000 万；低于 50 万为普通客户）；
- **权益按层级累积展开**（文档原文"含全部下级权益，新增以下"）：
金卡 9 条 / 白金 20 / 钻石 33 / 私行 54，各档已逐档实测；
- 返回**升级提示**（`next_tier`：下一层级与门槛），前端可直接渲染"再投 X 元升级"。
### 新增表 `fin_customer_benefit`（1 张）
层级 → 权益目录，54 条种子数据（`tools/seed_customer_benefits.py`，按 `benefit_code` 幂等）。
**基线合规证明**（规则 1/3/4）：只新增这一张表；**未**重命名/删除任何已有表；
**未**重命名/删除/复用任何已有字段，**未**改任何已有字段的类型、可空性或业务含义；
未改 `docs/00`。
复核：`tools/audit_schema.py` → `90 business tables, no missing or unexpected tables`。
### 两条设计取舍
1. **不落"某客户享有哪些权益"**：层级可算，权益由层级推出，两者都不落库。
与 `docs/00` L159（不保留 `net_worth_flag`，因为可算）同一取向。
2. **权益只存各层新增条目**，累积由服务层 `tier_chain()` 展开 ——
否则改一条权益要改四处，漏一处就出现"白金没有金卡权益"。
### 数据来源与一处刻意省略
逐条照抄知识文档，不新增文档里没有的权益。**私行那条
「7×24小时私人银行专线：400-XXX-XXXX 转 8」不写号码** ——
文档里是占位符，而对客号码的唯一来源是 `customer_service_rules.CONTACT_PHONE`
（本线此前修过"同一客服给客户两个不同号码"的缺陷）。把占位符抄进库等于再造一份假号码。
## 2. 修投顾迁移契约里写死的断言
`tests/unit/test_advisor_migration_contract.py` 原先断言
```python
assert script.get_heads()[0] == "20260911_merge_adv_risk_heads"
```
那是"投顾迁移刚加完那一刻"的快照 —— 本 PR 一新增迁移（`20260912_customer_benefit`）
它就变红，**而红的原因与投顾链的对错无关**：断言测到的是时间，不是契约。
原意是"投顾链接在这条主链上、没另起分支"。改为断言**投顾链尾是当前 head 的祖先**
（链尾从 `ADVISOR_FILES[-1]` 派生，不写死），既保住原意又不受后续迁移影响。
`len(script.get_heads()) == 1`（链不分叉）与"投顾文件首尾相接"两条原样保留。
## 3. 顺带发现的既有缺口（**不在本次改动范围**）
`app/api/controllers/trading.py` 的 **T001–T009 未调用 `AuthorizationService.require`**：
`docs/05` §19 为它们登记了权限码（`account:read:self` / `trade:order:*` / `holding:read:self`），
但代码只做认证 + 开户测评门槛，**没有执行 RBAC 权限检查**。
对照：仓库里 **26 个 service** 都调了 `require`，`trade_service` 不在其中。
本线的 T010 **按正确做法实现**：`CustomerBenefitService.entitlements_for` 先鉴权再读数据，
且**鉴权在读取客户资产之前**（有测试断言"拒绝时未查库"）。
T001–T009 如何补，需架构师定口径后另行处理。
## 4. 文档
- 新增 `docs/41-客户权益功能说明.md`：表登记 + 基线合规证明 + 分层口径 + 累积规则 +
数据来源 + 权限 + 与仪表盘的关系 + 上述缺口
- `docs/05` §19 登记 T010，并**单独注明它引入了新表**（避免被误读为
"T 段数据库零变更"的一部分）
- `AGENTS.md` 表数 89 → **90** 张业务表
## 验证
- `pytest tests/unit/service/test_customer_benefit_service.py` → **20 passed**
（含边界：499999.99 不是金卡、500000 整是金卡、1000 万整是私行；累积条数；升级提示；
鉴权先于读数据）
- 全量 `pytest tests` → `2 failed, 1469 passed, 1 skipped`
（2 个失败为既有环境项：httpx 把中文序列化成 `\uXXXX`，非本次引入）
- `ruff check app tests tools alembic` → `All checks passed`
- `mypy app` → **0 错 / 252 文件**
- 真机：`GET /users/me/entitlements` → `200`；各档分层与累积条数逐档实测通过
- `audit_schema.py` → 90 张业务表无缺失/意外；文档守卫 55 份无编号冲突；
端点编号无重复；RBAC 种子一致性通过
2026-09-12 17:24:37 +08:00
..
2026-09-11 16:57:47 +08:00
2026-09-11 14:44:29 +08:00
2026-09-11 19:20:32 +08:00
2026-09-11 20:28:21 +08:00
2026-09-09 21:55:37 +08:00
2026-09-09 21:55:37 +08:00
2026-09-09 21:55:37 +08:00
2026-09-11 22:31:51 +08:00
2026-09-11 20:22:59 +08:00
2026-09-11 17:16:43 +08:00
2026-09-11 15:08:37 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 16:57:47 +08:00
2026-09-10 18:42:44 +08:00
2026-09-11 13:25:00 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 16:57:47 +08:00
2026-09-12 17:24:37 +08:00
2026-09-11 19:37:18 +08:00
2026-09-11 14:46:40 +08:00
2026-09-11 16:11:30 +08:00
2026-09-11 16:11:30 +08:00
2026-09-11 16:11:30 +08:00
2026-09-11 16:11:30 +08:00
2026-09-10 22:53:29 +08:00
2026-09-11 16:11:30 +08:00
2026-09-11 14:47:08 +08:00
2026-09-11 15:27:16 +08:00
2026-09-11 14:14:50 +08:00
2026-09-11 14:46:40 +08:00
2026-09-11 14:44:29 +08:00
2026-09-10 09:23:22 +08:00
2026-09-10 09:23:22 +08:00
2026-09-10 09:23:22 +08:00
2026-09-09 23:40:35 +08:00
2026-09-09 23:40:35 +08:00
2026-09-09 23:40:35 +08:00
2026-09-09 23:40:35 +08:00
2026-09-11 16:12:38 +08:00
2026-09-11 15:06:44 +08:00
2026-09-10 15:55:54 +08:00
2026-09-10 17:36:39 +08:00
2026-09-09 21:55:37 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 13:11:58 +08:00
2026-09-10 18:42:44 +08:00
2026-09-10 22:29:23 +08:00
2026-09-11 14:46:40 +08:00
2026-09-11 18:42:42 +08:00
2026-09-11 14:46:40 +08:00
2026-09-10 22:08:15 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 14:46:40 +08:00
2026-09-11 19:47:14 +08:00
2026-09-12 14:11:42 +08:00
2026-09-11 16:57:47 +08:00
2026-09-10 15:55:54 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 17:16:43 +08:00
2026-09-11 16:57:47 +08:00
2026-09-09 21:55:37 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 14:46:40 +08:00
2026-09-09 21:55:37 +08:00
2026-09-11 16:57:47 +08:00
2026-09-12 12:20:01 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 16:57:47 +08:00
2026-09-12 12:20:01 +08:00
2026-09-11 13:20:09 +08:00
2026-09-11 19:20:32 +08:00
2026-09-11 18:39:57 +08:00
2026-09-11 12:47:01 +08:00
2026-09-11 15:33:27 +08:00
2026-09-12 10:45:40 +08:00
2026-09-11 16:42:31 +08:00
2026-09-11 16:57:47 +08:00
2026-09-12 12:20:01 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 16:57:47 +08:00
2026-09-10 21:03:44 +08:00
2026-09-10 21:03:44 +08:00
2026-09-10 21:03:44 +08:00
2026-09-11 14:16:07 +08:00
2026-09-11 11:42:53 +08:00
2026-09-11 13:49:57 +08:00
2026-09-11 14:24:45 +08:00
2026-09-11 13:48:08 +08:00
2026-09-11 13:45:51 +08:00
2026-09-10 21:03:44 +08:00
2026-09-10 21:03:44 +08:00
2026-09-11 15:25:45 +08:00
2026-09-11 16:40:15 +08:00
2026-09-11 12:57:07 +08:00
2026-09-12 15:56:50 +08:00
2026-09-12 15:56:50 +08:00
2026-09-11 13:35:58 +08:00
2026-09-11 09:49:21 +08:00
2026-09-11 14:24:45 +08:00
2026-09-11 19:37:26 +08:00
2026-09-12 15:56:50 +08:00
2026-09-11 16:57:47 +08:00
2026-09-11 21:17:47 +08:00
2026-09-12 12:50:14 +08:00
2026-09-09 21:55:37 +08:00
2026-09-11 13:10:04 +08:00
2026-09-09 21:55:37 +08:00
2026-09-12 15:50:37 +08:00
2026-09-09 21:55:37 +08:00
2026-09-09 21:55:37 +08:00