zhanghongyu_0626/XingHuo
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance suitability assessment and documentation

Browse Source 
- Implemented `check_suitability` method in `CoreReadOnlyRepository` for suitability determination based on customer and product risk levels.
- Added `build_suitability_log_row` function in `suitability.py` for mapping suitability check results to `risk_suitability_log`.
- Updated `AGENTS.md`, `ENVIRONMENT.md`, and `FLOW.md` to reflect changes in suitability assessment processes and documentation.
- Revised `FRAMEWORK.md` and `MEMORY.md` to clarify project structure and data flow related to suitability checks.
- Expanded `TODO.md` with tasks related to logging and auditing suitability assessments.
This commit is contained in:
zhanghongyu_0626
2026-09-07 11:15:30 +08:00
parent 1ddd44a6cb
commit 3fb0ceb334
44 changed files with 7479 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/项目框架设计/Core模拟底座/00-方案总览.md
+1 -1
View File
@@ -252,7 +252,7 @@ core_customer / core_advisor / core_product / core_holding
## 12. 待你确认的点
~~已确认：28 客户、RBAC 多角色、Neo4j P0、静态净值。~~
~~已确认：33 客户 / 14 产品、RBAC 多角色、Neo4j P0、静态净值、KYC/C×R 矩阵对齐客户手册。~~
---
docs/项目框架设计/Core模拟底座/01-表结构与种子说明.md
+157 -22
View File
@@ -1,66 +1,201 @@
# Core 模拟底座 · 表结构与种子说明
> 状态：**已落地** · 库名 `jinrong_core`
> 方案：[00-方案总览.md](./00-方案总览.md)
> 状态：**已落地** · 库名 `jinrong_core` · **2026-09-07 对齐客户资料手册**
> 方案：[00-方案总览.md](./00-方案总览.md)
> 客户规则来源：`docs/来自客户的项目资料/金融/`
---
## 1. 已确认决策
| 项 | 决定 |
| --- | --- |
| 库名 | `jinrong_core` |
| 访问方式 | `CoreReadOnlyRepository` 只读 SQL，无 HTTP API |
| 种子规模 | 28 客户、13 员工（含 RBAC 多角色）、12 产品 |
| 种子规模 | **33 客户**（28 通用 + 5 手册示范 `CUST-DEMO-*`）、13 员工、**14 产品** |
| 适当性 | `core_suitability_rule` C×R 矩阵（《适当性管理指南》第十二条） |
| Neo4j | **P0 必做** · `scripts/sync/sync_neo4j.py` |
| 行情 | 静态 `core_product_nav` seed |
---
## 2. 表清单
## 2. 表清单（对齐客户手册）
见 [scripts/core/01-ddl.sql](../../../scripts/core/01-ddl.sql)
| 表 | 说明 |
| --- | --- |
| `core_risk_grade` | C1~C5 / R1~R5 字典 |
| `core_staff` | 内部员工 + **roles JSON**（RBAC 种子） |
| `core_customer` | 客户主档 |
| `core_customer_risk` | L0 正式测评 |
| `core_customer_advisor` | 归属 → sync 到 agent 库 |
| `core_product` | 产品 + 最低风险等级 |
| `core_holding` | 持仓快照 |
| `core_trade` / `core_cash_flow` | 流水 |
| `core_product_nav` | 净值 C-05 |
| `core_industry` | 行业（Neo4j BELONGS_TO） |
| 表 | 说明 | 对齐文档 |
| --- | --- | --- |
| `core_risk_grade` | C1~C5 / R1~R5 字典 | 适当性指南 §6、§11 |
| `core_suitability_rule` | C×R 匹配矩阵 | 适当性指南 §12 |
| `core_staff` | 内部员工 + roles JSON | JWT/RBAC 联调 |
| `core_customer` | L0 KYC：性别/学历/收入/资产/高净值/PEP/AML 等 | 用户信息数据示例 §1 |
| `core_customer_risk` | L0 风评：问卷得分/目标/期限/过期/专业投资者 | 适当性指南 §8–10、FM-03 |
| `core_customer_advisor` | 归属 → sync agent 库 | F-01 |
| `core_product` | 产品 + **起购金额/期限/风险揭示书** | C-11、适当性指南 §11 |
| `core_holding` / `core_trade` / `core_cash_flow` | 持仓/流水 + **AML 渠道/对手方/代付** | 反洗钱规则 RW-001~020 |
| `core_product_nav` | 净值 C-05 | — |
| `core_industry` | 行业（Neo4j BELONGS_TO） | — |
---
## 3. 脚本与代码
## 3. 手册示范客户（联调推荐）
| customer_id | 原型 | C 等级 | 用途 |
| --- | --- | --- | --- |
| `CUST-DEMO-A` | 张晓明·年轻白领 | C2 | 定投/购房/C-07 |
| `CUST-DEMO-B` | 王建国·高净值企业主 | C4 | 私募/专业投资者认定 |
| `CUST-DEMO-C` | 陈秀兰·退休保守 | C1 | 适老化/银行理财/大额存单 |
| `CUST-DEMO-D` | 李伟·医生均衡 | C3 | 子女教育/养老规划 |
| `CUST-DEMO-E` | 赵鹏·科技激进 | C5 | 集中度/AML 代付样例 |
特殊联调客户（原有种子）：
| customer_id | 用途 |
| --- | --- |
| `CUST-4001` | 70 岁 + C5 + 买 R5（FM-01 年龄限制） |
| `CUST-4002` | C1 持有 R4 产品（适当性冲突） |
| `CUST-3001` | 大额交易 R-01 |
| `CUST-1003` | 风评已过期（FM-03） |
---
## 4. Repository 能力
`app/repository/core_ro.py`：
| 方法 | 说明 |
| --- | --- |
| `get_customer_l0` | 完整 KYC + 风评 |
| `check_suitability` | R-02：矩阵 + 风评过期 + 专业投资者豁免 + FM-01 年龄 |
| `list_products_for_customer` | C-11 匹配列表 |
| `list_holdings` / `list_trades` | 事实查询 |
---
## 5. 脚本与代码
| 路径 | 作用 |
| --- | --- |
| `scripts/core/00~06-*.sql` | 建库 + 种子 |
| `scripts/core/reset.ps1` | 一键重置 |
| `scripts/sync/sync_advisor_rel.py` | → `customer_advisor_rel` |
| `scripts/sync/sync_neo4j.py` | → Neo4j 图 |
| `app/repository/core_ro.py` | 只读 Repository |
| `scripts/dev/rbac-seed-reference.md` | RBAC 验收对照 |
---
## 4. 环境变量
## 6. 环境变量
```env
MYSQL_CORE_DATABASE=jinrong_core
NEO4J_URI=bolt://localhost:7687
NEO4J_PASSWORD=...
```
---
## 5. 关联文档
## 7. 关联文档
- [RBAC 手册](../技术选型和版本/02-JWT-RBAC鉴权手册.md)
- [Neo4j 模型](../表设计/04-neo4j-model.md)
- [业务记忆管理手册](../../业务记忆管理/业务记忆管理手册.md)
- [画像 L1/L2/L3](../表设计/06-用户画像L1-L3设计.md)
- [适当性 log 契约](../表设计/07-risk_suitability_log说明.md)
- 客户资料：`docs/来自客户的项目资料/金融/`
docs/项目框架设计/表设计/00-架构总览.md
+7 -3
View File
@@ -46,7 +46,7 @@
| **正式档案柜** | MySQL | 必须长期保存、能审计的记录 | 聊天记录归档、客户画像、预警单、合规审计 | **不能丢**，监管和纠纷都要查 |
| **产品说明书索引** | Milvus | 按意思搜文档（向量检索） | 基金产品手册、交易规则、内部办事流程 | 更新了重新导入即可 |
| **关系图谱** | Neo4j | 「谁持有啥、谁管谁」的关系图 | 客户↔产品↔持仓、客户↔代理人、产品风险等级 | 从原有业务系统同步重建 |
| **原有业务系统** | Core（只读） | 公司本来就有的一套账 | 真实持仓、流水、正式风险测评 C1~C5 | Agent **不复制一份**，只读 |
| **原有业务系统** | Core（只读） | 公司本来就有的一套账 | 真实持仓、流水、正式 KYC、C1~C5、C×R 矩阵 | Agent **不复制一份**，只读 |
**记忆分层（和 Agent 文档里的说法对应）**
@@ -109,7 +109,8 @@
| L2 | 代理人助手 Agent | 代理人、风控、数据分析（客户不看） |
| L3 | 风控监测 Agent | 风控、代理人（只看）、数据分析 |
对应 MySQL 表名（给开发对照）：`customer_profile_l1` / `l2` / `l3`
对应 MySQL 表名（给开发对照）：`customer_profile_l1` / `l2` / `l3`
**详细 JSON 约定与 L0 边界：** [06-用户画像L1-L3设计.md](./06-用户画像L1-L3设计.md)
---
@@ -170,7 +171,8 @@
| `compliance_hit_log` | 代理人 | 违规话术检测 |
| `analytics_query_log` | 分析 | 查数 SQL 留痕 |
> 完整字段见 [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) + [02-mysql-agent专用.sql](./02-mysql-agent专用.sql)
> 完整 DDL 见 [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) + [02-mysql-agent专用.sql](./02-mysql-agent专用.sql)
> 适当性 log 字段契约：[07-risk_suitability_log说明.md](./07-risk_suitability_log说明.md)
---
@@ -269,6 +271,8 @@
| **[05-多Agent共用底座清单.md](./05-多Agent共用底座清单.md)** | **先搭底座：哪些表多 Agent 共用** |
| [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) | 执行建库：共用 11 张 |
| [02-mysql-agent专用.sql](./02-mysql-agent专用.sql) | 各 Agent 专用 5 张 |
| [06-用户画像L1-L3设计.md](./06-用户画像L1-L3设计.md) | L0/L1/L2/L3 边界、JSON schema、适当性分工 |
| [07-risk_suitability_log说明.md](./07-risk_suitability_log说明.md) | R-02 落库字段契约 |
| [02-redis-keys.md](./02-redis-keys.md) | 做会话缓存、画像缓存 |
| [03-milvus-collections.md](./03-milvus-collections.md) | 做产品/制度文档检索 |
| [04-neo4j-model.md](./04-neo4j-model.md) | 做持仓关系、适当性关系查询 |
docs/项目框架设计/表设计/01-mysql-共用底座.sql
+26 -6
View File
@@ -180,15 +180,35 @@ CREATE TABLE risk_suitability_log (
trace_id VARCHAR(64) NOT NULL,
customer_id VARCHAR(64) NOT NULL,
product_id VARCHAR(64) NOT NULL,
customer_risk_level CHAR(2) NOT NULL,
product_risk_level CHAR(2) NOT NULL,
product_name VARCHAR(128) NULL COMMENT '判定时产品名快照',
customer_risk_level CHAR(2) NOT NULL COMMENT 'L0 C1~C5',
product_risk_level CHAR(2) NOT NULL COMMENT '产品最低 R1~R5',
investor_category ENUM('ordinary','professional','professional_pending') NOT NULL DEFAULT 'ordinary',
match_result ENUM(
'allowed','allowed_with_disclosure','forbidden',
'risk_expired','professional_exempt'
) NOT NULL COMMENT '与 Core check_suitability 输出一致',
mismatch_type ENUM(
'none','risk_level','risk_expired','age_branch_confirm',
'min_subscribe','not_found','professional_exempt'
) NOT NULL DEFAULT 'none' COMMENT '阻断/特殊处理原因分类',
is_matched TINYINT(1) NOT NULL,
is_blocked TINYINT(1) NOT NULL DEFAULT 0,
block_reason VARCHAR(512) NULL,
request_ref VARCHAR(64) NULL,
requires_disclosure TINYINT(1) NOT NULL DEFAULT 0,
needs_branch_confirm TINYINT(1) NOT NULL DEFAULT 0 COMMENT 'FM-01 年龄≥70 买 R3+',
risk_was_expired TINYINT(1) NOT NULL DEFAULT 0 COMMENT '判定时风评是否已过期',
block_reason VARCHAR(512) NULL COMMENT '对人可读原因',
block_response_code VARCHAR(32) NULL COMMENT 'API 机器码，如 SUIT_RISK_MISMATCH',
check_source ENUM('r02_trade','r02_chat','c11_inquiry','manual') NOT NULL DEFAULT 'r02_trade',
actor_id VARCHAR(64) NOT NULL COMMENT '发起者 customer_id / staff_id / svc-trade-suitability',
request_ref VARCHAR(64) NULL COMMENT '交易单号 / session_id',
profile_l1_version INT UNSIGNED NULL,
rule_refs JSON NULL COMMENT '依据规则，如 ["JR-AST-012","FM-03"]',
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
KEY idx_trace (trace_id),
KEY idx_customer (customer_id, created_at),
KEY idx_product (product_id, created_at),
KEY idx_blocked (is_blocked, created_at)
) ENGINE=InnoDB COMMENT='【交换】适当性记录 · 风控写 / 客户+代理人读';
KEY idx_blocked (is_blocked, created_at),
KEY idx_match (match_result, created_at),
KEY idx_mismatch (mismatch_type, created_at)
) ENGINE=InnoDB COMMENT='【交换】适当性记录 · 风控写 / 客户+代理人读 · 字段契约见 07-risk_suitability_log说明.md';
docs/项目框架设计/表设计/05-多Agent共用底座清单.md
+2 -2
View File
@@ -67,7 +67,7 @@
| `customer_profile_l2` | **3** | **代理人** Agent | 代理人、风控、分析 | 服务侧记录：诉求、待办、服务标签 |
| `customer_profile_l3` | **4** | **风控** Agent | 客户(只读)、代理人、分析 | 监测标签：正常/关注/高风险 |
| `risk_alert` | **2~3** | **风控** Agent | 风控、**分析**、合规 | 预警单；分析统计「还有多少没审」 |
| `risk_suitability_log` | **3** | **风控** Agent | **客户**、**代理人**、交易钩子 | 买的产品是否匹配；可否拦截购买 |
| `risk_suitability_log` | **3** | **风控** Agent | **客户**、**代理人**、交易钩子 | 适当性判定落库；字段契约 [07-risk_suitability_log说明.md](./07-risk_suitability_log说明.md) |
### ⚪ 第三批 — 单 Agent 专用（5 张，各组自建）
@@ -208,7 +208,7 @@
## 十一、和总览文档的关系
- 画像 L0/L1/L2/L3 含义 → [00-架构总览.md](./00-架构总览.md) 第四节
- 画像 L0/L1/L2/L3 含义 → [00-架构总览.md](./00-架构总览.md) 第四节 · JSON 约定 → [06-用户画像L1-L3设计.md](./06-用户画像L1-L3设计.md)
- Redis / Milvus / Neo4j 字段细节 → `02`~`04` 号文档
- JWT + RBAC 统一鉴权 → [02-JWT-RBAC鉴权手册.md](../../技术选型和版本/02-JWT-RBAC鉴权手册.md)
- 技术栈与版本 → [01-技术栈与版本.md](../../技术选型和版本/01-技术栈与版本.md)
docs/项目框架设计/表设计/06-用户画像L1-L3设计.md
+166
View File
@@ -0,0 +1,166 @@
# 用户画像 L0～L3 设计框架
> **用途：** 说明画像四层分工、表结构、JSON 字段约定、与 Core / 适当性 / 客户资料的对齐关系。
> **DDL：** [01-mysql-共用底座.sql](./01-mysql-共用底座.sql) · **L0：** [Core模拟底座/01-表结构与种子说明.md](../Core模拟底座/01-表结构与种子说明.md)
> **记忆分层：** [业务记忆管理手册.md](../../业务记忆管理/业务记忆管理手册.md) · **适当性落库：** [07-risk_suitability_log说明.md](./07-risk_suitability_log说明.md)
---
## 1. 四层一句话
| 层 | 存什么 | 权威库/表 | 谁写 | 谁读 |
| --- | --- | --- | --- | --- |
| **L0** | 官方 KYC、正式 C1~C5、持仓/流水 | `jinrong_core` | 非 Agent | 四 Agent 只读 |
| **L1** | 客户侧偏好、规划、行为（**不能改 L0 等级**） | `customer_profile_l1` | 客户 Agent | 客户本人、代理人、风控、分析 |
| **L2** | 代理人服务记录、诉求、待办（**客户不可见**） | `customer_profile_l2` | 代理人 Agent | 代理人、风控、分析 |
| **L3** | 监测分层、评分维度（**不改 L0 等级**） | `customer_profile_l3` | 风控 Agent | 风控、代理人/分析只读 |
```text
L0（Core）──── 正式风评、收入、资产、产品事实
↑ 只读，禁止覆盖
L1（Agent）── 客户说的偏好、规划、阈值摘要
L2（Agent）── 代理人服务过程 enrich
L3（Agent）── 风控监测 enrich
```
---
## 2. L0 与 Agent 画像的边界（2026-09-07 对齐客户手册）
**L0 已在 Core 扩展**（`core_customer` + `core_customer_risk` + `core_product`），对应客户资料《用户信息数据示例》中的 **基础信息 / 投资档案 / 产品属性**：
| 客户资料章节 | L0 表/字段 | Agent 画像能否写 |
| --- | --- | --- |
| 基础信息（性别、学历、收入…） | `core_customer.*` | ❌ 只读 |
| 正式风评 C1~C5、问卷得分、过期日 | `core_customer_risk.*` | ❌ 只读 |
| 产品 R 等级、起购、期限 | `core_product.*` | ❌ 只读 |
| C×R 匹配规则 | `core_suitability_rule` | ❌ 只读 |
| 产品偏好、口头风格、服务诉求 | L1 / L2 JSON | ✅ Agent enrich |
| 监测评分、异常行为标签 | L3 JSON | ✅ 风控 enrich |
**铁律：** L1 里客户说「我比较激进」**不能**把 L0 的 C2 改成 C5；适当性买卖仍以 L0 + R-02 为准。
---
## 3. MySQL 画像表结构
### 3.1 `customer_profile_l1`（一客户一行）
| 列 | 类型 | 含义 |
| --- | --- | --- |
| `customer_id` | PK | 与 Core 一致 |
| `style_tags` | JSON | 风格/财务/生命周期标签（见 §4.1） |
| `style_questionnaire` | JSON | C-07 问卷答卷与得分摘要（**非** L0 正式风评） |
| `allocation_plan` | JSON | C-08 资金比例规划 |
| `behavior_tags` | JSON | 行为标签（活跃度、咨询频率等） |
| `attribution_pref` | VARCHAR | 复盘归因偏好（日/周/月） |
| `version` | INT | 乐观锁；写入 `risk_suitability_log.profile_l1_version` 可选 |
### 3.2 `customer_profile_l2`（客户 × 代理人 一行）
| 列 | 类型 | 含义 |
| --- | --- | --- |
| `customer_id` + `advisor_id` | UK | 归属维度 |
| `asset_snapshot` | JSON | A-01 查 Core 后的概况快照（非权威账） |
| `demands` | JSON | 沟通诉求、关注点 |
| `follow_up_todos` | JSON | 待跟进事项 |
| `service_tags` | JSON | 服务标签（VIP 诉求、适老化等） |
| `source_session_id` | VARCHAR | 来源会话 |
### 3.3 `customer_profile_l3`（一客户一行）
| 列 | 类型 | 含义 |
| --- | --- | --- |
| `monitor_tier` | ENUM | normal / watch / high |
| `risk_score` | SMALLINT | 监测分（**≠** L0 正式 C 档） |
| `score_dimensions` | JSON | 四维/六维评分快照（见 §4.3） |
| `monitor_tags` | JSON | AML/行为异常等标签 |
| `last_alert_id` | VARCHAR | 关联最近预警 |
---
## 4. JSON 字段约定（对齐客户资料标签体系）
> P0：**列名已定**；JSON **键名约定**在实现 L1/L2 写入前按下列 schema 填充，无需改表。
### 4.1 L1 `style_tags` 推荐结构
对照《用户信息数据示例》§1.5 画像标签：
```json
{
"basic": { "age_band": "25-30", "city": "上海", "education": "本科" },
"financial": { "income_band": "10-20万", "monthly_investable": "3000-5000" },
"investment": {
"goal": "购房储蓄",
"horizon": "1-3年",
"product_preferences": ["指数基金", "货币基金"],
"excluded_products": ["私募", "期货"]
},
"lifecycle": { "stage": "单身奋斗期", "near_term_goal": "购房" },
"threshold_pref_summary": "亏损10%提醒"
}
```
- `threshold_pref_summary`：C-04 阈值偏好的 **摘要**；明细在 `customer_threshold_config`。
- **禁止**在 L1 存「正式 C 等级」——以 L0 为准。
### 4.2 L2 `demands` / `service_tags` 示例
```json
{
"demands": ["了解赎回规则", "子女教育金规划"],
"service_tags": { "tier": "vip", "prefer_channel": "counter", "elderly_care": true }
}
```
### 4.3 L3 `score_dimensions` 示例
对照《投资者风险画像研判规则》四维（监测用，**不写入 L0**）：
```json
{
"basic_attr": 17.5,
"invest_experience": 17.5,
"risk_preference": 8.0,
"behavior_anomaly": 20.0,
"computed_at": "2026-09-07T00:00:00Z",
"model_ref": "JR-RULE-2024-001"
}
```
---
## 5. 适当性：L1 与 R-02 的边界
**L1 仅辅助** R-02 判断（如规划、偏好），**不能替代** L0 风评。
计算/落库流程见 [07-risk_suitability_log说明.md](./07-risk_suitability_log说明.md)。
---
## 6. Redis 缓存
画像 L1/L2/L3 有热缓存（MySQL 为权威，UPDATE 后 DEL）。Key 明细见 [02-redis-keys.md](./02-redis-keys.md)。
---
## 7. 读写权限速查
| 角色 | L0 | L1 | L2 | L3 | suitability_log |
| --- | --- | --- | --- | --- | --- |
| 客户本人 | R | W/R 本人 | — | — | R 本人 |
| 代理人 | R | R 名下 | W/R 名下 | R 名下 | R 名下 |
| 风控 | R | R | R | W | **W** |
| 数据分析 | R | R 脱敏 | R 脱敏 | R 脱敏 | — |
JWT 细则见 [02-JWT-RBAC鉴权手册.md](../技术选型和版本/02-JWT-RBAC鉴权手册.md) §7。
---
## 8. P0 验收
- [ ] L0 事实只来自 Core RO；画像 Tool 无 UPDATE Core
- [ ] L1 写入后 version 递增；不写入正式 `risk_code`
- [ ] L2 按 `customer_advisor_rel` 隔离；客户 API 不可见 L2
- [ ] L3 不写 L0；监测分与正式 C 档文档区分
- [ ] R-02 写入 `risk_suitability_log` 与 `check_suitability` 字段一致
docs/项目框架设计/表设计/07-risk_suitability_log说明.md
+114
View File
@@ -0,0 +1,114 @@
# risk_suitability_log · P0 字段契约
> **用途：** 风控 Agent（R-02）写入；客户 / 代理人 Agent **只读**。
> **原则：** 一行记录 = 一次 `CoreReadOnlyRepository.check_suitability()` 判定 + 审计上下文。
> **SQL：** [01-mysql-共用底座.sql](./01-mysql-共用底座.sql)
> **映射代码：** `app/model/suitability.py` → `build_suitability_log_row()`
---
## 1. 与 Core 计算器的关系
```text
Core.check_suitability(customer_id, product_id)
↓ 返回 dict（match_result / mismatch_type / blocked …）
build_suitability_log_row(check, trace_id, actor_id, …)
↓
INSERT risk_suitability_log ← jinrong_agent 库
↓ 只读
客户 Agent（本人）· 代理人 Agent（名下客户）
```
**不在此表存：** C×R 规则本身（在 `jinrong_core.core_suitability_rule`）。
---
## 2. 字段 ↔ check_suitability 映射
| 表字段 | 来源 | 说明 |
| --- | --- | --- |
| `customer_risk_level` | `customer_risk_code` | L0 正式 C 档 |
| `product_risk_level` | `product_risk_code` | 产品最低 R 档 |
| `product_name` | `product_name` | 快照，避免日后改名 |
| `investor_category` | `investor_category` | 判定时投资者类别 |
| `match_result` | `match_result` | 见下表枚举 |
| `mismatch_type` | `mismatch_type` | 见下表枚举 |
| `is_matched` | `matched` | 是否视为可匹配 |
| `is_blocked` | `blocked` | 是否阻断请求 |
| `requires_disclosure` | `requires_disclosure` | 是否需风险揭示书 |
| `needs_branch_confirm` | `needs_branch_confirm` | FM-01 网点确认 |
| `risk_was_expired` | `risk_is_expired` | FM-03 风评过期 |
| `block_reason` | `reason` | 对人可读 |
| `block_response_code` | `block_response_code` | API 机器码 |
---
## 3. match_result 枚举
| 值 | 含义 | 典型场景 |
| --- | --- | --- |
| `allowed` | 完全匹配 | C2 买 R2 |
| `allowed_with_disclosure` | 可买但需揭示书 | C3 买 R4 |
| `forbidden` | 等级不配 | C1 买 R4 |
| `risk_expired` | 风评过期 | FM-03 |
| `professional_exempt` | 专业投资者豁免 | 已认定 professional |
---
## 4. mismatch_type 枚举
| 值 | 含义 | is_blocked 常见 |
| --- | --- | --- |
| `none` | 无特殊问题 | 0 |
| `risk_level` | C/R 矩阵禁止 | 1 |
| `risk_expired` | 风评过期 | 1 |
| `age_branch_confirm` | 高龄买 R3+ 需网点 | 1 |
| `min_subscribe` | 起购金额不足（P0 预留） | 1 |
| `not_found` | 客户或产品不存在 | 1 |
| `professional_exempt` | 豁免路径 | 0 |
---
## 5. block_response_code（P0）
| 代码 | 条件 |
| --- | --- |
| `SUIT_OK` | 匹配且可继续 |
| `SUIT_NEED_DISCLOSURE` | 需签署风险揭示书 |
| `SUIT_RISK_MISMATCH` | C/R 不配 |
| `SUIT_RISK_EXPIRED` | 风评过期 |
| `SUIT_AGE_CONFIRM` | 需网点确认（FM-01） |
| `SUIT_PROFESSIONAL_EXEMPT` | 专业投资者豁免 |
| `SUIT_NOT_FOUND` | 客户或产品不存在 |
| `SUIT_MIN_SUBSCRIBE` | 起购不足（预留） |
---
## 6. check_source / actor_id
| check_source | 触发场景 | actor_id 示例 |
| --- | --- | --- |
| `r02_trade` | 交易前钩子 | `svc-trade-suitability` |
| `r02_chat` | 风控 Agent 对话判定 | `STAFF-30001` |
| `c11_inquiry` | 客户问「能否买」 | `CUST-DEMO-A` |
| `manual` | 人工补录 | 员工 staff_id |
---
## 7. 读写权限（不变）
| Agent | 权限 |
| --- | --- |
| 风控 | **写** |
| 客户 | **读**（仅本人） |
| 代理人 | **读**（仅名下客户） |
| 数据分析 | 不用 |
---
## 8. P0 验收
- [ ] R-02 写入行与 `check_suitability` 返回值逐项一致
- [ ] 阻断时同时写 `audit_log`（同 `trace_id`）
- [ ] 客户 Agent 只读本人；代理人只读 `customer_advisor_rel` 名下
- [ ] `blocked=true` 仅 R-02 / 交易钩子 API 可对外返回