AI260626/group_fqcd_jr
13
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
NL_develop
group_fqcd_jr/docs/41-客户权益功能说明.md
T
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

7.8 KiB
Raw Permalink Blame History

客户权益功能说明与数据表登记

日期：2026-09-12｜分支：NL_develop｜端点：T010｜权限码：benefit:read:self

1. 一句话

客户可以查到自己属于哪一层级、享有哪些权益、还差多少升级。

GET /api/v1/users/me/entitlements     （T010，已登录 + benefit:read:self）

响应（docs/05 §3.3 信封，data 内）：

{
  "tier": "platinum",
  "tier_label": "白金",
  "min_total_asset": "2000000.00",
  "total_asset": "3000000.00",
  "next_tier": {"tier": "diamond", "tier_label": "钻石", "min_total_asset": "6000000.00"},
  "benefits": [
    {"benefit_code": "tier:gold:01", "tier": "gold", "tier_label": "金卡",
     "category": "financial", "name": "专属理财经理服务", "description": "..."}
  ]
}

2. 数据表登记（新增 1 张）

fin_customer_benefit 客户权益目录

列 类型 说明
id BIGINT UNSIGNED 主键
benefit_code VARCHAR(64) 权益编号（唯一），种子按 tier:<层级>:<序号> 生成
customer_tier VARCHAR(16) 适用层级：gold / platinum / diamond / private
category VARCHAR(16) financial / non_financial
name VARCHAR(128) 权益名称
description VARCHAR(512) 权益说明
display_order INT 展示顺序（按文档出现次序）
status VARCHAR(16) active / inactive
created_at / updated_at DATETIME(6) 审计时间
  • 唯一键 uk_fin_customer_benefit_code；索引 idx_fin_customer_benefit_tier
  • 三个 CHECK：层级、类别、状态取值受限
  • 迁移：alembic/versions/20260912_customer_benefit.py（down_revision = 20260911_merge_adv_risk_heads）

基线合规证明（规则 1/3/4）

  • 只新增这一张表；未重命名/删除任何已有表（规则 3）；
  • 未重命名/删除/复用任何已有字段，未改任何已有字段类型、可空性或业务含义（规则 4）；
  • 未改 docs/00 基线文档；
  • 复核命令：python -X utf8 tools/audit_schema.py → 应显示业务表数 +1、且无 missing/unexpected。

3. 为什么不落"某客户享有哪些权益"

层级由资产实时判定，权益由层级推出 —— 两者都不落库。理由与 docs/00 L159 （不保留 net_worth_flag，因为"可由 customer_tier 或 total_asset 计算，冗余存储会造成不一致"） 完全一致：能算的不要存。

落库会立刻带来两个问题：资产变化后等级与已存权益脱节；以及同一事实两处可写（谁改都算对）。

需要"客户被人工特别授权某项权益"这类留痕需求时，再加一张例外表 （customer_id + benefit_code + 生效期 + 授权人），而不是把全量权益快照落库。

4. 分层口径

来源：knowledge/product/高净值客户服务规范.md（公司内部服务标准）。

层级 名称 可投资资产门槛
gold 金卡 50 万 - 200 万
platinum 白金 200 万 - 600 万
diamond 钻石 600 万 - 1000 万
private 私行 1000 万以上
  • 低于 50 万为"普通客户"（tier: null，tier_label: "普通客户"），权益为空但仍返回升级提示；
  • 门槛含等号：恰好 50 万即金卡（有边界测试守着，防 off-by-one）；
  • 资产取 fin_customer_profile.total_asset —— 基线（docs/00 L213/L220）把它定为 「风控研判所用资产快照」且「按统一口径计算」，是系统里唯一的资产口径，不另造口径； 文档写的是"可投资金融资产（不含自住房产）"，与 total_asset 的口径差异由该字段的维护方负责， 权益模块不自行调整。

权益按层级累积

文档每层都写"含全部下级权益，新增以下"。表里只存该层新增条目， 累积展开由 CustomerBenefitService.tier_chain() 完成：

资产 层级 权益条数
¥60 万 金卡 9
¥300 万 白金 20（9+11）
¥800 万 钻石 33（9+11+13）
¥2000 万 私行 54（9+11+13+21）

若把父级条目在每层重复存一遍，改一条权益要改四处、漏一处就出现"白金没有金卡权益"。

5. 权益数据的来源与一处刻意省略

逐条照抄《高净值客户服务规范》第二章，不新增文档里没有的权益。种子： tools/seed_customer_benefits.py（54 条，按 benefit_code 幂等、已存在不覆盖）。

刻意省略的一处：文档私行条目原文是

7×24小时私人银行专线：400-XXX-XXXX 转 8

号码是占位符。项目已有明确口径：对客号码的唯一来源是 app/core/customer_service_rules.py 的 CONTACT_PHONE（本线此前修过 "同一客服给客户两个不同号码"的缺陷，见 docs/37）。把占位符抄进库等于又造一份假号码， 故库里只写权益名「7×24 小时私人银行专线」，号码一律走客服热线配置。

6. 权限

新权限码 benefit:read:self（种子 id 9066，续 §T 的 9060-9065）。

  • 定义源：tools/seed_test_rbac.py 的 PERMISSIONS（唯一定义源）；
  • 已挂入 CUSTOMER_PERMISSIONS（customer 角色自带）；
  • 一致性由 python -X utf8 tools/check_rbac_seed_consistency.py 守着；
  • ⚠️ config_release 是环境数据：本权限走 RBAC（sys_permission）， 不经 agent_tools 白名单，故换环境重跑种子即可，无需重新发布配置。

7. 与仪表盘的关系

T001 /users/me/account/dashboard 已返回账户、组合汇总与持仓（接口完整）。 本接口是独立的只读端点，前端可在仪表盘上以"我的等级 + 权益卡片"呈现：

  • 仪表盘负责资产与持仓（T001）→ 本接口负责等级与权益（T010）；
  • 两者都归属"用户端（客户视角）"，权限数据范围均为 self。

若后续希望一次请求拿全，可在 T001 响应里内联权益字段；当前不这么做， 因为权益数据的更新频率远低于资产（改权益是运营动作），内联会让每次刷新多查两表。

8. 已知缺口（不在本次改动范围，供架构师评估）

app/api/controllers/trading.py 的 T001–T009 未调用 AuthorizationService.require —— docs/05 §19 为它们登记了权限码（account:read:self / trade:order:* / holding:read:self 等）， 但代码只做了认证 + 开户测评门槛，没有执行 RBAC 权限检查。

对照：仓库里 26 个 service 都调了 AuthorizationService.require，trade_service 不在其中。

本线的 T010 按正确做法实现（在 CustomerBenefitService.entitlements_for 里先鉴权再读数据， 且鉴权在读取客户资产之前，有测试守着）。T001–T009 的补法需架构师定： 是补 require 调用，还是明确"用户自助端点只靠认证 + 测评门槛"这一口径并同步 §19 的权限列。

9. 相关文件

新增

  • alembic/versions/20260912_customer_benefit.py（建表）
  • app/model/benefit.py（ORM）
  • app/service/customer_benefit_service.py（分层 + 累积展开 + 鉴权）
  • app/api/controllers/benefit.py（T010）
  • tools/seed_customer_benefits.py（54 条权益种子）
  • tests/unit/service/test_customer_benefit_service.py（20 例）

修改

  • app/main.py（注册 benefit_router）
  • tools/seed_test_rbac.py（加权限码 9066 + 挂 customer 角色）
  • docs/05-接口文档.md（§19 登记 T010 并注明它引入新表）
  • AGENTS.md（业务表数 89 → 90）

验证

  • pytest tests/unit/service/test_customer_benefit_service.py → 20 passed
  • 真机：GET /users/me/entitlements → 200；各档分层与累积条数逐档实测通过
Reference in New Issue View Git Blame Copy Permalink