group_fqcd_jr/docs/风控业务演示文档/22-风控模块需求说明书.md

风控模块需求说明书

文档信息

项目	内容
文档版本	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 状态流转

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

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

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

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 完成接入。