# 风控模块需求说明书

## 文档信息

| 项目 | 内容 |
|---|---|
| 文档版本 | v1.0 |
| 编制日期 | 2026-09-14 |
| 适用对象 | 主项目架构、前端、后端、测试、运维和风控业务人员 |
| 实现基线 | 当前 `RM2_develop` 风控模块代码 |
| 文档定位 | 主项目合并和联调时的风控模块统一需求口径 |

## 1. 背景与目标

本模块面向公募基金模拟交易场景，基于客户、产品、交易、资金、持仓、登录、工单等数据执行确定性风险扫描，生成风险预警，并提供证据查询、人工处置、通知、日报和只读 Agent 研判能力。

模块目标：

- 对异常交易和适当性风险形成可解释、可追溯的结构化预警。
- 支持风控人员确认、调查、关闭误报、完成结案和升级处理。
- 提供客户、产品、交易、资金、持仓、登录、预警和通知八类证据。
- 对高风险预警提供站内通知和邮件通知。
- 提供九段式风险日报和日报邮件。
- 提供“奶龙风控智能助手”只读查询和研判草案能力。
- 所有关键动作写入审计，支持按预警和客户追溯。

## 2. 范围

### 2.1 本期范围

- 风险概览。
- 预警队列、筛选、排序、分页和详情。
- 手动规则扫描。
- 定时规则扫描。
- 适当性错配、异常交易和频率筛查规则。
- 预警确认、调查、误报关闭、完成结案、升级和证据归档。
- 客户行为分更新。
- 八类证据只读查询。
- 通知记录查询。
- 高风险预警邮件通知。
- 九段式日报、流式生成和日报邮件发送。
- 奶龙风控智能助手只读工具调用。
- 风控操作审计。

### 2.2 不在本期范围

- 用户登录、JWT 签发和通用 RBAC 底座。
- 客户账户开户、充值、提现和真实资金操作。
- 修改交易、资金、持仓和产品事实。
- 自动确认、自动关闭或自动升级预警。
- 演示数据由演示机按 `26-演示机数据插入规则.md` 准备，风控模块不负责初始化。
- 正式前端页面由主项目统一前端实现，风控模块只提供接口和合并约束。
- 高风险预警邮件多收件人扩展。
- 将定时扫描自动注册到主项目统一 Worker。

## 3. 用户、角色与权限

### 3.1 角色

| 角色 | 使用范围 |
|---|---|
| 风控专员 `risk_operator` | 查询风控数据、执行规则扫描、人工处置和日报操作 |
| 管理员 `admin` | 具备风控业务权限，并负责配置和运维 |

### 3.2 权限

| 权限码 | 用途 |
|---|---|
| `risk:alert:read` | 风险概览、预警、证据、通知、日报和 Agent 只读查询 |
| `risk:alert:write` | 确认、调查、误报关闭、完成结案、升级和证据归档 |
| `risk:alert:scan` | 手动规则扫描 |
| `risk:report:mail` | 发送日报邮件 |
| `agent:run` | 运行奶龙风控智能助手 |

### 3.3 数据范围

- 风控查询必须执行服务端客户数据范围过滤。
- `data_scope=all` 可访问全部客户；受控范围只能访问归属客户。
- 没有有效客户归属时必须失败关闭，不能默认放开。
- 列表、详情、证据、通知、日报和 Agent 工具使用同一数据范围。

## 4. 预警状态与人工处置

### 4.1 状态

| 状态 | 含义 | 是否未闭环 |
|---|---|---|
| 待处理 | 预警已生成，尚未确认接收 | 是 |
| 调查中 | 已确认接收并进入人工调查 | 是 |
| 已排除 | 人工认定为误报并关闭 | 否 |
| 已结案 | 人工调查完成并形成处置结论 | 否 |

“升级处理”通过 `is_escalated`、`escalated_at` 和 `escalation_reason` 标记，不改变上述状态。

### 4.2 状态流转

```text
待处理
  -> 确认接收
  -> 进入调查
  -> 关闭误报

待处理
  -> 确认接收
  -> 进入调查
  -> 完成结案

待处理或调查中
  -> 升级处理
  -> 保持原未闭环状态
```

### 4.3 处置规则

| 操作 | 前置条件 | 结果 |
|---|---|---|
| 确认接收 | 状态为待处理且尚未确认 | 写确认状态、确认时间和处理人 |
| 进入调查 | 已确认且状态为待处理 | 状态改为调查中 |
| 关闭误报 | 已确认且未闭环 | 状态改为已排除，记录误报理由和关闭时间 |
| 完成结案 | 已确认且状态为调查中 | 状态改为已结案，写处置结论并更新行为分 |
| 升级处理 | 已确认、未闭环且尚未升级 | 写明升级理由，不改变闭环状态 |
| 上传证据 | 已确认且状态为调查中 | 每笔预警最多归档一个文件，归档后不可覆盖 |

### 4.4 行为分

- 初始行为分为 20 分。
- 完成结案时按预警等级扣分：
  - 低风险扣 3 分。
  - 中风险扣 5 分。
  - 高风险扣 20 分。
- 最低扣至 0 分。
- 关闭误报和未闭环预警不扣分。
- 行为分变化必须写入审计。

行为分关注等级：

| 等级 | 分数范围 | 筛选值 |
|---|---|---|
| 正常 | 16-20 | `normal` |
| 轻微关注 | 11-15 | `slight` |
| 需要关注 | 6-10 | `attention` |
| 高度关注 | 1-5 | `high` |
| 立即关注 | 0 | `immediate` |

## 5. 风控规则

### 5.1 通用扫描规则

- 扫描只读取交易、资金、持仓、客户、产品、工单和登录数据。
- 同一交易和同一规则组合不能重复生成预警。
- 同一交易命中多个规则时合并为一条预警，保留最高风险等级并汇总规则和证据。
- 扫描结果写入 `fin_risk_alert` 和审计。
- 手动扫描和定时扫描共用同一扫描服务。

### 5.2 RW-003 大额快进快出

| 项目 | 要求 |
|---|---|
| 触发对象 | 赎回交易 |
| 条件 | 3 天内存在成功入金，且赎回比例不低于 80% |
| 金额要求 | 赎回金额不低于 500000 元 |
| 风险等级 | 高 |
| 核心证据 | 入金流水、赎回交易、金额、时间、赎回比例 |

### 5.3 RW-007 适当性错配

| 项目 | 要求 |
|---|---|
| 触发对象 | 申购交易 |
| 条件 | 产品风险等级高于客户风险承受等级 |
| 风险留痕 | 缺少风险揭示、二次确认或双录任一项即认为留痕不完整 |
| 豁免额度 | C3 买 R4 的单只持仓占比超过 20%，或 C4 买 R5 超过 10% |
| 风险等级 | 等级差不少于 2 时为高；等级差为 1 时为中 |
| 核心证据 | 客户等级、产品等级、等级差、留痕、豁免比例和工单 |

### 5.4 RW-012 老年客户异常赎回

| 项目 | 要求 |
|---|---|
| 触发对象 | 赎回交易 |
| 年龄要求 | 不低于 65 岁 |
| 金额要求 | 赎回金额不低于 300000 元 |
| 均值要求 | 赎回金额不低于近一年历史平均金额的 3 倍 |
| 设备要求 | 交易前最近一次成功登录使用非常用设备 |
| 风险等级 | 高 |
| 核心证据 | 年龄、金额、历史均值、倍数、登录时间和设备 |

### 5.5 RW-015 夜间小额交易

| 项目 | 要求 |
|---|---|
| 触发时间 | 北京时间 00:00-05:59 |
| 金额要求 | 不超过 10000 元 |
| 风险等级 | 低 |
| 定位 | 夜间小额行为筛查，不直接认定异常 |

### 5.6 RW-018 自动定投频繁交易筛查

| 项目 | 要求 |
|---|---|
| 触发对象 | 存在工单关联的交易 |
| 条件 | 工单渠道为“定投”或“自动定投” |
| 风险等级 | 低 |
| 定位 | 识别可能由有效定投产生的误报候选 |

## 6. 功能需求

### FR-01 风险概览

- 展示当前未闭环预警总数，不是当天新增数量。
- 展示高风险、中风险和低风险数量。
- 展示待处理数量和已超时数量。
- 返回最多 3 条重点高风险预警。

### FR-02 预警队列

- 默认只查询未闭环预警。
- 支持按关键词、客户编号、产品、风险等级、规则和创建时间筛选。
- 按高风险、中风险、低风险排序，同等级按创建时间倒序。
- 预警队列每页固定最多 10 条。

### FR-03 预警详情

- 返回预警编号、客户编号、脱敏姓名、产品、规则、等级、状态和证据摘要。
- 返回客户、交易、产品、工单、资金流水、持仓、登录记录和证据快照。
- 资金流水、持仓和登录记录各有详情上限，超过时通过 `evidence_truncated` 标识。

### FR-04 手动规则扫描

- 需要 `risk:alert:scan` 权限。
- 需要 `Idempotency-Key`。
- 与定时扫描互斥，不能同时执行。
- 返回新增预警数、高风险数、通知记录数和通知创建失败原因。

### FR-05 定时规则扫描

- 默认关闭。
- 开启后按配置间隔扫描。
- 多个进程同时运行时通过分布式锁避免并发重复扫描。
- 当前使用独立进程 `python -m app.worker.risk_scan_scheduler`。
- 正式接入主项目时，应注册到统一 Worker 或由部署编排统一启动。

### FR-06 人工处置

- 支持确认接收、进入调查、关闭误报、完成结案和升级处理。
- 所有写操作需要 `risk:alert:write`。
- 写操作需要幂等键，重复请求回放首次响应。
- 状态不允许跳步，重复操作返回冲突错误。

### FR-07 行为分

- 结案时更新客户行为分。
- 行为分与预警状态更新在同一事务内提交。
- 审计记录应包含变更前分数、扣分和变更后分数。

### FR-08 证据归档

- 支持 JPG、JPEG、PNG、WEBP、PDF、DOC、DOCX、XLS、XLSX、PPT、PPTX 和 TXT。
- 单个文件默认最大 10 MB。
- 文件保存到 `RISK_EVIDENCE_DIR`。
- 文件重命名为预警编号并增加原扩展名。
- 一笔预警只能归档一个文件，成功或重复归档均需有明确结果。
- 归档状态写入预警证据快照。

### FR-09 通知与预警邮件

- 高风险预警同时创建站内通知和邮件通知。
- 手动扫描和定时扫描均自动触发高风险预警邮件。
- 邮件发送成功写 `已发送`，失败写 `发送失败` 和失败原因。
- 邮件发送失败不回滚预警和站内通知。
- 当前高风险预警邮件只支持一个收件人。
- 日报邮件支持最多 10 个收件人，与预警邮件配置独立。

### FR-10 风险日报

日报按北京时间和固定九段式模板生成：

1. 当日预警数量。
2. 等级分布。
3. 重点风险事件。
4. 未闭环事项，包含全部历史未闭环预警。
5. 误报统计。
6. 类型分布。
7. 处置结果。
8. 规则效果。
9. 建议优化方向。

- 日报统计数据来自数据库，模型只生成建议。
- 模型不可用、返回空内容或输出不合规时使用规则化建议。
- 日报生成写入审计。

### FR-11 日报流式生成与邮件

- 流式接口使用 SSE。
- 事件类型包括 `start`、`progress`、`replace` 和 `done`。
- 日报邮件需要 `risk:report:mail` 权限。
- 日报邮件支持多个收件人和 dry-run。

### FR-12 奶龙风控智能助手

- 使用主项目 `agent_type=risk`。
- 只允许查询风险概览、预警列表和指定预警证据。
- 支持生成研判草案、沟通话术和工单摘要。
- 同一 `session_id` 内使用最近 10 轮会话历史，支持连续追问。
- 通用风险问答和预警上下文分别维护会话。
- 刷新页面后当前不承诺跨刷新恢复。
- Agent 不能确认、调查、关闭、升级预警，不能修改客户和交易事实。
- 客户姓名和敏感信息必须脱敏。

### FR-13 审计

以下动作必须写审计：

- 规则扫描生成预警。
- 定时扫描成功或失败。
- 确认、调查、误报关闭、完成结案和升级。
- 证据归档。
- 日报生成。
- 权限拒绝和安全操作。

## 7. 数据读写边界

### 7.1 主要写入表

| 表 | 用途 |
|---|---|
| `fin_risk_alert` | 预警、状态、人工处置和证据快照 |
| `fin_risk_notification` | 站内通知和邮件通知状态 |
| `biz_work_order` | 风险处置和关联工单兼容 |
| `interaction_audit` | 风控操作审计 |

### 7.2 只读数据源

| 数据 | 表 |
|---|---|
| 客户 | `sys_user`、`fin_customer_profile`、`fin_risk_assessment` |
| 产品 | `fin_product` |
| 交易 | `fin_transaction` |
| 资金 | `fin_capital_flow` |
| 持仓 | `fin_holding` |
| 登录 | `sys_login_record` |
| 工单 | `biz_work_order` |

风控模块不得修改交易、资金、持仓和产品事实。

## 8. 非功能要求

### 8.1 安全

- 所有接口必须经过主项目鉴权。
- 所有业务查询必须执行数据范围校验。
- Agent 工具必须执行工具白名单和权限校验。
- 日志、错误和响应不得泄露密码、密钥和完整敏感信息。

### 8.2 幂等

- 扫描、确认、调查、关闭、结案、升级等写接口必须携带 `Idempotency-Key`。
- 幂等键长度为 16-128 位 ASCII。
- 同一键重复提交返回首次结果。
- 同一键对应不同请求返回 `409 IDEMPOTENCY_CONFLICT`。

### 8.3 分页

- 预警列表和其他列表每页最多 10 条。
- 使用游标分页，游标绑定用户、筛选条件和数据范围。
- 不允许只把页码或 offset 暴露给客户端。

### 8.4 时区

- 数据库保存 UTC naive 时间。
- 对外时间统一转换为 ISO 8601。
- 日内判断、日报日期和夜间规则统一按 `Asia/Shanghai`。

### 8.5 降级

- 模型不可用时使用规则化建议。
- 邮件失败只影响通知状态。
- Redis 等外部依赖失败不得破坏核心预警查询和处置链路。

## 9. 配置要求

### 9.1 扫描

- `RISK_SCAN_SCHEDULE_ENABLED`
- `RISK_SCAN_INTERVAL_MINUTES`
- `RISK_SCAN_RUN_IMMEDIATELY`
- `RISK_SCAN_RETRY_LIMIT`
- `RISK_SCAN_POLL_SECONDS`

`RISK_SCAN_RUN_IMMEDIATELY` 当前仅保留兼容，不控制首次执行。

### 9.2 高风险预警邮件

- `RISK_ALERT_MAIL_ENABLED`
- `RISK_ALERT_MAIL_DRY_RUN`
- `RISK_ALERT_MAIL_RECIPIENTS`

当前只支持一个收件人。

### 9.3 SMTP

- `RISK_SMTP_HOST`
- `RISK_SMTP_PORT`
- `RISK_SMTP_USERNAME`
- `RISK_SMTP_PASSWORD`
- `RISK_SMTP_SENDER`
- `RISK_SMTP_USE_SSL`
- `RISK_SMTP_TIMEOUT_SECONDS`

### 9.4 证据

- `RISK_EVIDENCE_DIR`
- `RISK_EVIDENCE_MAX_FILE_SIZE_MB`

## 10. 验收标准

- 未闭环预警、等级分布、待处理和超时统计正确。
- 预警队列按风险等级排序，每页最多 10 条。
- 五类规则按条件正确触发，不重复生成同一交易同规则预警。
- 多规则命中同一交易时正确合并。
- 人工处置状态机不允许非法跳转。
- 结案后行为分正确扣减。
- 八类证据可按数据范围查询。
- 证据归档格式、大小和重复归档规则正确。
- 高风险预警邮件状态能体现真实发送结果。
- 日报九段式内容完整，历史未闭环预警不被分页截断。
- Agent 只读边界和脱敏规则有效。
- 关键操作均可在审计中追溯。

## 11. 当前限制与后续事项

- 高风险预警邮件当前只支持一个收件人。
- 定时扫描当前仍需独立进程，主项目需提供统一 Worker 注册或部署编排。
- 本期不支持对话历史长期归档和 Redis-only 会话方案。
- 正式前端已接入主项目，后续变更继续遵循 `17-风控模块-前端合并提示词与验收约束.md`。
- 主项目合并前需要按 `21-主项目合并后后端必改清单.md` 完成接入。