# 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 可对外返回