From a03d5e33c3f51bf285f2a682141704e9c92a86a0 Mon Sep 17 00:00:00 2001 From: zhangshy <994452054@qq.com> Date: Sat, 12 Sep 2026 16:30:01 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E9=A3=8E=E6=8E=A7=E9=82=AE?= =?UTF-8?q?=E4=BB=B6=E9=80=9A=E7=9F=A5=E4=B8=8E=E5=AE=9A=E6=97=B6=E6=89=AB?= =?UTF-8?q?=E6=8F=8F=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/21-风控业务第二版迁移清单.md | 7 ++-- .../风控业务演示文档/06-模块接口与字段映射.md | 10 ++++++ .../风控业务演示文档/12-日报通知与邮件规则.md | 29 ++++++++++++++++- .../风控业务演示文档/15-模块验收与演示清单.md | 5 ++- docs/风控业务演示文档/16-已知限制与待办.md | 10 +++++- .../17-前端合并提示词与验收约束.md | 32 +++++++++++++++++-- docs/风控业务演示文档/18-当前项目完成进度.md | 25 ++++++++------- .../风控业务演示文档/19-风控模块配置项清单.md | 16 ++++++++-- .../21-主项目合并后后端必改清单.md | 21 ++++++++++-- 9 files changed, 131 insertions(+), 24 deletions(-) diff --git a/docs/21-风控业务第二版迁移清单.md b/docs/21-风控业务第二版迁移清单.md index bd6803b..7619b12 100644 --- a/docs/21-风控业务第二版迁移清单.md +++ b/docs/21-风控业务第二版迁移清单.md @@ -539,12 +539,14 @@ tests/unit/api/test_risk_controller.py 已实现： - 站内通知记录创建。 -- 邮件通知记录创建，本阶段不外发 SMTP。 +- 邮件通知记录创建；迁移阶段当时尚未接入 SMTP。 - 通知主键和通知编号显式生成。 - 通知内容自动包含“预警编号：xxx”。 - 高风险批量通知记录。 - 通知分页复用 `RiskQueryService` 和 `RiskRepository`。 +> 2026-09-12 更新：本节“本阶段不外发 SMTP”只描述 R6.1 当时状态。当前手动扫描和定时扫描命中高风险后已恢复真实邮件发送，通知状态会回写 `已发送` 或 `发送失败`。当前高风险预警邮件只支持一个收件人。 + 验证结果：当前全部风控专项测试共 `58 passed`。 下一步：R6.2 将高风险通知创建接入扫描事务，并验证通知失败不破坏预警主事务。等待确认后执行。 @@ -556,7 +558,8 @@ tests/unit/api/test_risk_controller.py 已实现： - 扫描生成高风险预警后自动创建站内通知记录。 -- 可选邮件通知记录，默认不发送 SMTP。 +- 高风险邮件通知记录和真实 SMTP 外发，发送失败不回滚预警。 +- 高风险预警邮件当前只支持一个收件人，多个邮箱值只取第一个。 - 通知创建使用嵌套保存点隔离。 - 通知创建失败只记录日志，不回滚预警扫描主事务。 - 扫描结果增加 `notification_count`。 diff --git a/docs/风控业务演示文档/06-模块接口与字段映射.md b/docs/风控业务演示文档/06-模块接口与字段映射.md index 53d22a2..d63a104 100644 --- a/docs/风控业务演示文档/06-模块接口与字段映射.md +++ b/docs/风控业务演示文档/06-模块接口与字段映射.md @@ -79,6 +79,16 @@ 同一用户、同一路径、同一键的重复请求直接回放首次响应；同一键换了请求正文返回 `409 IDEMPOTENCY_CONFLICT`。证据上传靠"同一预警只能归档一次"的冲突保护去重。 +## 扫描通知与高风险邮件 + +- `POST /alerts/scan` 同时用于手动扫描，定时扫描复用同一 `RiskScanService`。 +- 高风险预警会创建站内通知和邮件通知。 +- 邮件发送成功时通知状态为 `已发送`；发送失败时为 `发送失败` 并返回失败原因。 +- 邮件发送失败不会改变扫描接口的成功状态，也不会回滚预警和站内通知。 +- `notification_count` 统计站内通知和邮件通知记录总数。 +- `notification_failure` 只表示通知记录创建失败，不表示 SMTP 邮件发送失败。 +- `RISK_ALERT_MAIL_RECIPIENTS` 当前只支持一个收件人，多个邮箱只取第一个。 + ## 日报和邮件 | 方法 | 路径 | 功能 | 权限 | diff --git a/docs/风控业务演示文档/12-日报通知与邮件规则.md b/docs/风控业务演示文档/12-日报通知与邮件规则.md index 8189d5f..116a3d9 100644 --- a/docs/风控业务演示文档/12-日报通知与邮件规则.md +++ b/docs/风控业务演示文档/12-日报通知与邮件规则.md @@ -48,7 +48,33 @@ - 数据库保留 `read_at`、`acknowledged_at` 基线字段，但当前未实现写入逻辑。 - 通知接口和前端不返回或展示阅读时间、确认时间。 -## 邮件开关 +### 高风险预警邮件 + +- 手动扫描和定时扫描共用同一套高风险预警邮件发送逻辑。 +- 高风险预警生成后，后端创建站内通知和邮件通知，并尝试调用真实 SMTP。 +- 邮件发送成功时，通知状态更新为 `已发送` 并写入发送时间。 +- 邮件发送失败时，通知状态更新为 `发送失败` 并写入安全失败原因。 +- 邮件发送失败不回滚预警，也不回滚站内通知。 +- 当前 `RISK_ALERT_MAIL_RECIPIENTS` 只支持一个收件人。即使配置多个邮箱，也只有第一个邮箱生效。 +- 高风险预警邮件收件人由后端配置，前端不提供收件人输入框。 + +高风险预警邮件配置： + +- `RISK_ALERT_MAIL_ENABLED` +- `RISK_ALERT_MAIL_DRY_RUN` +- `RISK_ALERT_MAIL_RECIPIENTS` + +高风险预警邮件复用以下 SMTP 配置： + +- `RISK_SMTP_HOST` +- `RISK_SMTP_PORT` +- `RISK_SMTP_USERNAME` +- `RISK_SMTP_PASSWORD` +- `RISK_SMTP_SENDER` +- `RISK_SMTP_USE_SSL` +- `RISK_SMTP_TIMEOUT_SECONDS` + +## 日报邮件开关 发送日报邮件需要 `risk:report:mail` 权限。 @@ -72,6 +98,7 @@ ## 收件人 +- 本节多个收件人规则只适用于日报邮件；高风险预警邮件当前只支持一个收件人。 - 支持多个收件人。 - 收件人去重并校验格式。 - 单次最多 10 个收件人。 diff --git a/docs/风控业务演示文档/15-模块验收与演示清单.md b/docs/风控业务演示文档/15-模块验收与演示清单.md index 641e0d4..93af2d0 100644 --- a/docs/风控业务演示文档/15-模块验收与演示清单.md +++ b/docs/风控业务演示文档/15-模块验收与演示清单.md @@ -40,6 +40,8 @@ - 定时扫描默认关闭，多个 Worker 同时运行时不重复执行。 - 定时扫描成功和失败写入系统审计。 - 扫描返回 `notification_failure` 时，页面必须区分成功与通知失败。 +- 手动扫描和定时扫描命中高风险后，高风险预警邮件按后端配置自动发送；当前只支持一个收件人。 +- 高风险邮件发送成功后通知状态为 `已发送`，失败时为 `发送失败`，且不影响预警落库。 - 重复扫描不重复生成同一交易和规则的预警。 - 多规则命中时正确合并。 @@ -69,6 +71,7 @@ - `data_truncated=true` 时不得把计数当作全量。 - 误报、处置结果和规则效果正确统计。 - 邮件接口要求 `risk:report:mail`，开关关闭时不发送真实邮件。 +- 日报邮件支持多个收件人；高风险预警邮件只支持一个收件人，两类邮件互不替代。 ## Agent 验收 @@ -88,7 +91,7 @@ 5. 展示行为分变化。 6. 使用奶龙风控智能助手查询和研判。 7. 生成并查看日报。 -8. 查看通知或邮件 dry-run 结果。 +8. 查看高风险预警邮件状态，并单独演示日报邮件 dry-run 或真实发送。 ## 通过标准 diff --git a/docs/风控业务演示文档/16-已知限制与待办.md b/docs/风控业务演示文档/16-已知限制与待办.md index e7f03c1..b3c2225 100644 --- a/docs/风控业务演示文档/16-已知限制与待办.md +++ b/docs/风控业务演示文档/16-已知限制与待办.md @@ -27,7 +27,14 @@ - Redis 不可用时，缓存和限流可能降级，不影响结构化业务主流程。 - Milvus 不可用时，语义记忆关闭，结构化查询继续运行。 - 模型服务不可用时，使用模板或规则化降级。 -- SMTP 未开启时，邮件接口返回禁用或 dry-run。 +- 日报邮件在 SMTP 未开启或 dry-run 时不会发送真实邮件。 +- 高风险预警邮件在 SMTP 发送失败时只更新通知状态，不回滚预警。 + +## 邮件通知限制 + +- `RISK_ALERT_MAIL_RECIPIENTS` 当前只支持一个收件人，多个邮箱配置只取第一个。 +- 高风险预警邮件和日报邮件是两条独立链路，收件人配置和开关互不替代。 +- 正式使用不能要求业务人员手工启动 `python -m app.worker.risk_scan_scheduler`。 ## 前端范围 @@ -52,6 +59,7 @@ - 主项目合并完成后对齐统一 RBAC 和客户数据范围。 - 修复公共 `data_scope` 最高权限跨资源扩散问题。 +- 将风控定时扫描接入主项目统一 Worker 或统一部署编排，并补充一个收件人以外的多收件人能力评估。 - 确认幂等回执与业务 Action 内部提交的事务边界。 - 私有前端最后再适配 `data/meta` 列表信封和写接口 `Idempotency-Key`。 - 根据合规要求确定会话保留期、脱敏和归档策略。 diff --git a/docs/风控业务演示文档/17-前端合并提示词与验收约束.md b/docs/风控业务演示文档/17-前端合并提示词与验收约束.md index 744bede..ca20e72 100644 --- a/docs/风控业务演示文档/17-前端合并提示词与验收约束.md +++ b/docs/风控业务演示文档/17-前端合并提示词与验收约束.md @@ -21,11 +21,35 @@ 后续模型开始前端合并前，必须先阅读本目录全部文档，并扫描上述代码和路由。 +## 前端合并前必须对齐的补充口径（2026-09-12） + +本节优先于后文中的概括性描述。前端合并时以本节为准。 + +### 风险概览口径 + +- 风险概览接口的 `total` 表示当前未闭环预警，状态范围为 `待处理` 和 `调查中`。 +- `total` 不是当天新增预警，不受 `created_at` 当天范围限制。 +- 前端指标名称应使用“未闭环预警”，不得继续显示为“今日预警”。 + +### 高风险预警邮件 + +- 手动扫描和定时扫描命中高风险预警后，后端都会创建站内通知并尝试发送邮件。 +- 高风险预警邮件由后端配置决定收件人，前端不提供收件人输入框。 +- 高风险预警邮件当前只支持一个收件人，前端不能按“多收件人”设计配置界面。 +- 邮件状态取值包括 `待发送`、`已发送`、`发送失败`、`未启用`。 +- 前端通知记录列表必须展示发送状态和失败原因，不能把“已创建通知记录”显示为“邮件已发送”。 +- 邮件发送失败不回滚预警，也不等于整次扫描失败。扫描成功后仅刷新通知记录即可看到真实邮件状态。 + +### 两类邮件必须区分 + +- 高风险预警邮件：手动扫描或定时扫描自动触发，收件人来自风控邮件通知配置。 +- 日报邮件：用户在高风险日报弹窗中填写收件人后手动发送，与预警扫描邮件互不替代。 + ## 二、前端功能范围 | 页面或区域 | 必需功能 | |---|---| -| 风险概览 | 总量、风险等级、待处理、超时、重点预警 | +| 风险概览 | 当前未闭环总量、风险等级、待处理、超时、重点预警；不得把总量显示为“今日预警” | | 预警队列 | 风险等级排序、筛选、每页 5 条、分页、弹窗详情 | | 预警详情 | 预警编号、状态、规则、证据、回执、人工处置 | | 证据区域 | 客户、产品、交易、资金、持仓、登录、预警、通知八类证据 | @@ -34,7 +58,7 @@ | 证据归档 | 图片和文档上传、归档状态、失败提示 | | 奶龙风控智能助手 | 对话、SSE 输出、工具调用展示、能力边界和免责声明 | | 日报 | 弹窗展示、流式生成、内容编辑、多邮箱发送 | -| 通知 | 通知记录、预警编号、发送状态 | +| 通知 | 通知记录、预警编号、站内或邮件渠道、发送状态、失败原因 | | 系统提示 | 政策解读、日报入口和预留模块 | ## 三、排版和交互约束 @@ -112,7 +136,9 @@ | 上传证据 | 证据上传成功 | | 手动扫描 | 预警扫描完成 | | 生成日报 | 日报生成完成 | -| 邮件发送 | 日报发送成功 | +| 日报邮件发送 | 日报邮件发送成功 | + +手动扫描成功只表示预警扫描完成。高风险预警邮件发送失败不会让扫描接口返回失败，前端应刷新通知记录，并通过通知的发送状态和失败原因展示真实结果。 ### 失败提示 diff --git a/docs/风控业务演示文档/18-当前项目完成进度.md b/docs/风控业务演示文档/18-当前项目完成进度.md index 4f8d256..9d16b80 100644 --- a/docs/风控业务演示文档/18-当前项目完成进度.md +++ b/docs/风控业务演示文档/18-当前项目完成进度.md @@ -8,10 +8,10 @@ | 项目 | 当前状态 | |---|---| -| 统计日期 | 2026-09-11 | +| 统计日期 | 2026-09-12 | | 当前分支 | `RM2_develop` | | 当前合并基线 | `origin/qyqy_develop` 主项目风控修复批次 | -| 代码状态 | 已完成主项目风控修复合并，全量测试通过 | +| 代码状态 | 已完成主项目风控修复合并，专项回归 54 项通过 | | 已推送分支 | `origin/RM2_develop` | | 已合并分支 | `origin/qyqy_develop` | | 私有前端 | `private_frontend/`，未提交、未推送 | @@ -63,11 +63,12 @@ ### 证据、通知和日报 - 图片和文档证据归档。 -- 高风险通知记录。 +- 高风险站内通知和邮件通知，邮件成功或失败状态可回查。 - 九段式日报。 - 历史未闭环完整统计。 - 日报流式生成。 -- 多邮箱校验和 dry-run 邮件发送。 +- 日报多邮箱校验和 dry-run 邮件发送。 +- 高风险预警邮件真实 SMTP 外发，当前只支持一个收件人。 ### 奶龙风控智能助手 @@ -124,14 +125,15 @@ ### 定时规则扫描 -状态：已完成。 +状态：功能已完成，主项目 Worker 接入待办。 - 新增独立 `RiskScanSchedulerWorker`，不在 Web 进程启动后台线程。 -- 扫描开关、周期、是否立即执行和重试次数由 `.env` 环境变量控制。 +- 扫描开关、间隔、轮询频率和重试次数由 `.env` 环境变量控制。 - 使用 MySQL 咨询锁防止多个 Worker 重复执行。 - 手动扫描和定时扫描共用同一个 `RiskScanService`。 - 扫描成功和失败写入系统审计。 - 默认关闭，配置开启后才执行。 +- 当前仍需独立启动 `python -m app.worker.risk_scan_scheduler`；主项目需要改为统一 Worker 注册或统一部署编排。 ### 主项目正式前端 @@ -170,11 +172,12 @@ ## 下一阶段建议 1. 将 `RM2_develop` 与最新 `qyqy_develop` 保持同步。 -2. 将定时规则扫描的环境变量配置纳入主项目部署配置。 -3. 按 `17-前端合并提示词与验收约束.md` 合并正式前端。 -4. 使用主项目真实登录、账号、角色和客户归属完成联调。 -5. 执行桌面端、移动端、权限、降级和完整业务链路验收。 -6. 主项目稳定后再实施对话历史、Redis 缓存和长期留存。 +2. 将定时规则扫描和高风险预警邮件配置纳入主项目部署配置。 +3. 将定时规则扫描接入主项目统一 Worker 或部署编排，取消业务人员手工启动独立进程。 +4. 按 `17-前端合并提示词与验收约束.md` 合并正式前端。 +5. 使用主项目真实登录、账号、角色和客户归属完成联调。 +6. 执行桌面端、移动端、权限、降级和完整业务链路验收。 +7. 主项目稳定后再实施对话历史、Redis 缓存和长期留存。 ## 完成判定 diff --git a/docs/风控业务演示文档/19-风控模块配置项清单.md b/docs/风控业务演示文档/19-风控模块配置项清单.md index 4a07738..cc0e374 100644 --- a/docs/风控业务演示文档/19-风控模块配置项清单.md +++ b/docs/风控业务演示文档/19-风控模块配置项清单.md @@ -20,9 +20,9 @@ |---|---:|---| | `RISK_SCAN_SCHEDULE_ENABLED` | `false` | 是否开启定时扫描 | | `RISK_SCAN_INTERVAL_MINUTES` | `5` | 扫描间隔，单位分钟 | -| `RISK_SCAN_RUN_IMMEDIATELY` | `false` | Worker 启动后是否立即执行 | +| `RISK_SCAN_RUN_IMMEDIATELY` | `false` | 仅保留兼容字段，当前不控制启动后的首次执行 | | `RISK_SCAN_RETRY_LIMIT` | `2` | 单轮失败后的重试次数 | -| `RISK_SCAN_POLL_SECONDS` | `30` | Worker 轮询配置和到期时间的间隔 | +| `RISK_SCAN_POLL_SECONDS` | `30` | Worker 检查扫描是否到期的频率，不是实际扫描间隔 | ### 证据归档 @@ -31,6 +31,14 @@ | `RISK_EVIDENCE_DIR` | `storage/risk_evidence` | 证据文件归档根目录 | | `RISK_EVIDENCE_MAX_FILE_SIZE_MB` | `10` | 单个证据文件最大大小，单位 MB | +### 高风险预警邮件 + +| 配置项 | 默认值 | 说明 | +|---|---:|---| +| `RISK_ALERT_MAIL_ENABLED` | `false` | 是否允许手动扫描和定时扫描发送高风险预警邮件 | +| `RISK_ALERT_MAIL_DRY_RUN` | `true` | 为真时只记录 dry-run 结果，不连接 SMTP | +| `RISK_ALERT_MAIL_RECIPIENTS` | 空 | 高风险预警邮件收件人；当前只支持一个，多个值只取第一个 | + ### 日报邮件 | 配置项 | 默认值 | 说明 | @@ -87,7 +95,9 @@ - 联调初期保持 `RISK_SCAN_SCHEDULE_ENABLED=false`。 - 确认扫描规则和演示数据后，再按需改为 `true`。 -- 邮件先保持 `RISK_DAILY_REPORT_MAIL_DRY_RUN=true`。 +- 高风险预警邮件先保持 `RISK_ALERT_MAIL_DRY_RUN=true`，确认预警落库和通知记录无误后再关闭 dry-run。 +- 当前高风险预警邮件只支持一个收件人，多邮箱配置只会有第一个生效。 +- 日报邮件先保持 `RISK_DAILY_REPORT_MAIL_DRY_RUN=true`。 - 正式发送前配置 SMTP，并将 `RISK_DAILY_REPORT_MAIL_ENABLED=true`。 - 证据目录应挂载到持久化存储，不能只保存在临时容器目录。 diff --git a/docs/风控业务演示文档/21-主项目合并后后端必改清单.md b/docs/风控业务演示文档/21-主项目合并后后端必改清单.md index 2b21b50..5b180d4 100644 --- a/docs/风控业务演示文档/21-主项目合并后后端必改清单.md +++ b/docs/风控业务演示文档/21-主项目合并后后端必改清单.md @@ -7,7 +7,7 @@ 公共底座、公共事务能力、公共数据范围、公共鉴权基座和公共 SSE 协商等问题不纳入本文， 由主项目统一修复和发布。 -## 本轮已完成 +## 已处理事项 ### 1. 证据查询时间口径统一 @@ -53,6 +53,23 @@ Agent 不能把截断结果表述成覆盖全部数据，也不能据此给出 `tools/grant_risk_permissions.py` 的文档字符串已改为实际文件名， 避免执行人员按错误路径操作。 +## 主项目仍需完成 + +### 6. 高风险预警邮件通知接入 + +- 主项目部署配置需要接入 `RISK_ALERT_MAIL_ENABLED`、`RISK_ALERT_MAIL_DRY_RUN` 和 `RISK_ALERT_MAIL_RECIPIENTS`。 +- 手动扫描和定时扫描必须继续共用同一套高风险邮件发送逻辑。 +- 高风险预警邮件当前只支持一个收件人，多个邮箱配置只有第一个生效。 +- 邮件发送成功写 `已发送`，失败写 `发送失败`；失败不得回滚预警和站内通知。 +- 日报邮件仍由用户在日报弹窗中填写多个收件人，和预警邮件配置相互独立。 + +### 7. 定时扫描接入主 Worker + +- 当前 `python -m app.worker` 不包含风控定时扫描，独立调度进程只适合本地联调。 +- 主项目需要提供通用后台任务注册入口，或在部署编排中统一拉起风控调度进程。 +- 正式使用不能要求业务人员额外手工执行 `python -m app.worker.risk_scan_scheduler`。 +- 无论采用哪种方式，都必须保留扫描互斥锁和幂等去重。 + ## 联调前需要执行的动作 以下内容属于环境准备或数据初始化，不是代码缺陷： @@ -68,7 +85,7 @@ Agent 不能把截断结果表述成覆盖全部数据，也不能据此给出 3. 执行 `python tools/publish_risk_agent_config.py`，确认奶龙风控智能助手的工具白名单和意图配置已发布。 4. 按主项目发布的迁移流程执行 Alembic 升级，确认 `trigger_rule_codes` 多值索引已生效。 5. 演示前准备足够的客户、交易、资金、持仓、登录和预警数据。 -6. 使用前确认日报邮件开关、SMTP 配置和收件人范围符合演示要求。 +6. 使用前确认高风险预警邮件开关、日报邮件开关、SMTP 配置和收件人范围符合演示要求。 ## 当前保留限制