group_xinghuo_jinrong/docs/项目框架设计/表设计/07-risk_suitability_log说明.md

risk_suitability_log · P0 字段契约

用途： 风控 Agent（R-02）写入；客户 / 代理人 Agent 只读。
原则： 一行记录 = 一次 CoreReadOnlyRepository.check_suitability() 判定 + 审计上下文。
SQL： 01-mysql-共用底座.sql
映射代码： app/model/suitability.py → build_suitability_log_row()

---

1. 与 Core 计算器的关系

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	人工补录 / 旧 API 直调	员工 staff_id
platform	代销平台 POST /api/compliance/suitability-check	登录用户 actor_id

---

7. 读写权限（不变）

Agent	权限
风控	写
客户	读（仅本人）
代理人	读（仅名下客户）
数据分析	不用

---

8. P0 验收

• R-02 写入行与 check_suitability 返回值逐项一致
• 阻断时同时写 audit_log（同 trace_id）
• 客户 Agent 只读本人；代理人只读 customer_advisor_rel 名下
• blocked=true 仅 R-02 / 交易钩子 API 可对外返回