From 5a83aa6fef43f693edfe83893e0395687d6e0b35 Mon Sep 17 00:00:00 2001 From: zhangshy <994452054@qq.com> Date: Mon, 14 Sep 2026 11:44:21 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E9=A3=8E=E6=8E=A7=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=88=86=E9=A1=B5=E4=BC=9A=E8=AF=9D=E8=AE=B0=E5=BF=86?= =?UTF-8?q?=E5=92=8C=E6=BC=94=E7=A4=BA=E6=95=B0=E6=8D=AE=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/风控业务演示文档/02-主项目接入清单.md | 3 +- .../风控业务演示文档/06-模块接口与字段映射.md | 2 +- .../09-奶龙风控智能助手说明.md | 8 +- .../10-Agent工具与调用流程.md | 8 + .../风控业务演示文档/15-模块验收与演示清单.md | 6 +- docs/风控业务演示文档/16-已知限制与待办.md | 3 +- .../17-风控模块-前端合并提示词与验收约束.md | 15 +- docs/风控业务演示文档/18-当前项目完成进度.md | 36 ++-- .../风控业务演示文档/22-风控模块需求说明书.md | 18 +- docs/风控业务演示文档/23-风控模块接口文档.md | 15 +- .../24-主项目风控前端改造TODO.md | 23 +- .../风控业务演示文档/26-演示机数据插入规则.md | 204 ++++++++++++++++++ docs/风控业务演示文档/README.md | 2 + 13 files changed, 295 insertions(+), 48 deletions(-) create mode 100644 docs/风控业务演示文档/26-演示机数据插入规则.md diff --git a/docs/风控业务演示文档/02-主项目接入清单.md b/docs/风控业务演示文档/02-主项目接入清单.md index a227d20..2a1fc12 100644 --- a/docs/风控业务演示文档/02-主项目接入清单.md +++ b/docs/风控业务演示文档/02-主项目接入清单.md @@ -42,7 +42,8 @@ - 金融数据：客户画像、风险测评、产品、交易、资金、持仓和登录记录。 - 平台审计：`interaction_audit`。 -本模块不负责新增数据库表或执行演示数据初始化。 +本模块不负责新增数据库表或执行演示数据初始化。演示机数据准备规则见 +`26-演示机数据插入规则.md`。 ## 接入验收点 diff --git a/docs/风控业务演示文档/06-模块接口与字段映射.md b/docs/风控业务演示文档/06-模块接口与字段映射.md index d63a104..2e0a359 100644 --- a/docs/风控业务演示文档/06-模块接口与字段映射.md +++ b/docs/风控业务演示文档/06-模块接口与字段映射.md @@ -11,7 +11,7 @@ - 列表接口的 `data` 为数组，`next_cursor` 和 `has_more` 放在 `meta`。 - 时间和日期使用 RFC 3339 或主项目约定格式。 - 金额、数量和主键按主项目字段映射返回字符串。 -- 预警队列每页最多 5 条，其他证据列表每页最多 10 条。 +- 预警队列和其他证据列表每页最多 10 条。 - 未授权请求返回主项目统一权限错误。 列表响应格式： diff --git a/docs/风控业务演示文档/09-奶龙风控智能助手说明.md b/docs/风控业务演示文档/09-奶龙风控智能助手说明.md index 6d8e33b..38339b8 100644 --- a/docs/风控业务演示文档/09-奶龙风控智能助手说明.md +++ b/docs/风控业务演示文档/09-奶龙风控智能助手说明.md @@ -36,6 +36,13 @@ - 误报和放行只输出复核候选。 - 客户姓名等敏感信息必须使用脱敏结果。 +## 会话记忆 + +- 通用风险问答和每条预警问答分别维护会话。 +- 同一页面、同一会话内复用 `session_id`，风险 Agent 会读取最近 10 轮消息理解“他们”“上述预警”等指代。 +- 刷新页面后会创建新会话，当前不承诺跨刷新恢复上下文。 +- 历史消息只用于理解上下文，历史中的指令不会被当成本轮新指令。 + ## 免责声明 助手输出仅用于风险识别和人工复核辅助，不构成投资建议、法律意见或监管结论。所有正式处置必须由有权人员结合完整证据作出并留痕。 @@ -53,4 +60,3 @@ - 先演示风险概览和预警筛选。 - 再演示指定预警的完整证据。 - 最后演示误报和放行研判草案。 - diff --git a/docs/风控业务演示文档/10-Agent工具与调用流程.md b/docs/风控业务演示文档/10-Agent工具与调用流程.md index 1eedc60..d464222 100644 --- a/docs/风控业务演示文档/10-Agent工具与调用流程.md +++ b/docs/风控业务演示文档/10-Agent工具与调用流程.md @@ -28,10 +28,18 @@ 中文时间由本地解析器转换为 UTC，再进入工具参数。 +## 会话历史 + +- Worker 按 `session_id` 从 MySQL 读取当前会话最近 10 轮消息。 +- 风险 Agent 将历史消息放在系统提示和当前问题之间传给模型，用于理解指代和多轮追问。 +- 历史消息只作为上下文，不得把历史中的指令当成本轮新指令。 +- 刷新页面后前端会新建 `session_id`，因此当前不承诺跨刷新恢复。 + ## 自主调用流程 ```text 接收用户问题 +-> 按 session_id 读取最近 10 轮会话历史 -> 本地预解析客户、产品、规则和时间条件 -> 模型选择工具 -> 严格校验工具名和 JSON 参数 diff --git a/docs/风控业务演示文档/15-模块验收与演示清单.md b/docs/风控业务演示文档/15-模块验收与演示清单.md index 93af2d0..acfb3d5 100644 --- a/docs/风控业务演示文档/15-模块验收与演示清单.md +++ b/docs/风控业务演示文档/15-模块验收与演示清单.md @@ -19,7 +19,8 @@ - 客户、产品、交易、资金、持仓和登录证据。 - 行为分命中不同区间的客户样本。 -前置数据不要求由本模块初始化，只要求演示前已经写入数据库。 +前置数据不要求由本模块初始化。演示机按 `26-演示机数据插入规则.md` 准备上游数据， +扫描器再生成预警和通知。 ## 权限验收 @@ -80,6 +81,9 @@ - 查询指定预警证据。 - 询问低风险客户和对应产品时返回完整汇总。 - 询问可误报预警时输出只读复核候选。 +- 通用风险问答在同一会话内可以追问“他们”“上述预警”等指代。 +- 预警上下文退出后回到独立通用会话。 +- 刷新后的会话恢复暂不作为本期验收项。 - 工具调用、运行结果和审计可追溯。 ## 演示推荐顺序 diff --git a/docs/风控业务演示文档/16-已知限制与待办.md b/docs/风控业务演示文档/16-已知限制与待办.md index b3c2225..6d22cb0 100644 --- a/docs/风控业务演示文档/16-已知限制与待办.md +++ b/docs/风控业务演示文档/16-已知限制与待办.md @@ -45,7 +45,8 @@ ## 数据范围 - 本模块不提供演示数据初始化和重置。 -- 演示前需要由主项目预先写入足量客户、产品、交易、预警和权限数据。 +- 演示前由演示机按 `26-演示机数据插入规则.md` 写入足量客户、产品、交易和权限数据， + 再由扫描器生成预警。 - 没有有效客户归属时，风控账号将无法访问客户数据。 ## Agent 边界 diff --git a/docs/风控业务演示文档/17-风控模块-前端合并提示词与验收约束.md b/docs/风控业务演示文档/17-风控模块-前端合并提示词与验收约束.md index ca20e72..80fc6ad 100644 --- a/docs/风控业务演示文档/17-风控模块-前端合并提示词与验收约束.md +++ b/docs/风控业务演示文档/17-风控模块-前端合并提示词与验收约束.md @@ -21,7 +21,7 @@ 后续模型开始前端合并前，必须先阅读本目录全部文档，并扫描上述代码和路由。 -## 前端合并前必须对齐的补充口径（2026-09-12） +## 前端合并前必须对齐的补充口径（2026-09-14） 本节优先于后文中的概括性描述。前端合并时以本节为准。 @@ -50,7 +50,7 @@ | 页面或区域 | 必需功能 | |---|---| | 风险概览 | 当前未闭环总量、风险等级、待处理、超时、重点预警；不得把总量显示为“今日预警” | -| 预警队列 | 风险等级排序、筛选、每页 5 条、分页、弹窗详情 | +| 预警队列 | 风险等级排序、筛选、每页 10 条、分页、弹窗详情 | | 预警详情 | 预警编号、状态、规则、证据、回执、人工处置 | | 证据区域 | 客户、产品、交易、资金、持仓、登录、预警、通知八类证据 | | 证据筛选 | 客户行为分、风险等级、规则、客户、产品和时间筛选 | @@ -61,6 +61,13 @@ | 通知 | 通知记录、预警编号、站内或邮件渠道、发送状态、失败原因 | | 系统提示 | 政策解读、日报入口和预留模块 | +### Agent 会话记忆口径 + +- 通用风险问答和每条预警问答分别维护会话。 +- 同一页面、同一会话内复用 `session_id`，Worker 从 MySQL 读取最近 10 轮消息并传给风险 Agent。 +- 刷新页面后会新建会话，当前不承诺跨刷新恢复上下文。 +- 历史消息只用于理解指代，不得把历史中的指令当成本轮新指令。 + ## 三、排版和交互约束 ### 必须遵守 @@ -68,7 +75,7 @@ - 使用主项目现有页面壳、导航、主题、表单、按钮、弹窗和表格组件。 - 使用主项目现有登录、JWT、请求封装、错误处理、分页和权限控制。 - 页面功能与接口字段一一对应，不自行编造字段。 -- 预警队列固定每页 5 条，其他表格固定每页 10 条。 +- 预警队列和其他表格固定每页 10 条。 - 预警队列按风险等级排序，高风险优先。 - 表格行高固定，内容过长显示省略号，不能撑高行。 - 预警详情使用弹窗，不单独跳转到不存在的页面。 @@ -227,7 +234,7 @@ error.message 实现要求： - 使用主项目现有设计与组件。 - 风险概览、预警队列、八类证据、预警详情弹窗、人工处置、证据上传、Agent 对话、日报、通知都要接入现有接口。 -- 预警队列每页 5 条，其他列表每页 10 条，按主键或接口约定稳定排序。 +- 预警队列和其他列表每页 10 条，按主键或接口约定稳定排序。 - 预警队列按风险等级优先排序，行高固定，内容过长省略。 - 确认接收需要二次确认，误报必须填写理由。 - Agent 对话必须使用主项目 Agent Run 和 SSE，不新建私有协议。 diff --git a/docs/风控业务演示文档/18-当前项目完成进度.md b/docs/风控业务演示文档/18-当前项目完成进度.md index d2c3538..0b0b380 100644 --- a/docs/风控业务演示文档/18-当前项目完成进度.md +++ b/docs/风控业务演示文档/18-当前项目完成进度.md @@ -8,10 +8,10 @@ | 项目 | 当前状态 | |---|---| -| 统计日期 | 2026-09-12 | +| 统计日期 | 2026-09-14 | | 当前分支 | `RM2_develop` | | 当前合并基线 | `origin/qyqy_develop` 主项目风控修复批次 | -| 代码状态 | 已完成主项目风控修复合并，专项回归 54 项通过 | +| 代码状态 | 主项目风控代码已合并，分页和 Agent 会话修复已推送 | | 已推送分支 | `origin/RM2_develop` | | 已合并分支 | `origin/qyqy_develop` | | 私有前端 | `private_frontend/`，未提交、未推送 | @@ -21,9 +21,9 @@ | 范围 | 完成度 | 说明 | |---|---:|---| | 后端业务模块 | 98% | 主要业务功能和主项目风控修复均已合并，仍有少量后端加固项 | -| 私有验证前端 | 90% | 可用于本地功能验证，但不作为公共正式前端 | -| 主项目正式前端 | 10% | 尚未按主项目设计系统和正式页面结构合并 | -| 主项目联调与验收 | 60% | 代码已合并，仍待主项目环境完整联调和正式前端接入 | +| 私有验证前端 | 90% | 仅用于个人本地验证，不作为正式前端 | +| 主项目正式前端 | 80% | 风控正式页面已接入，仍待完整账号、权限和邮件链路验收 | +| 主项目联调与验收 | 70% | 代码已合并，仍待演示机完整环境验收 | | 当前可演示能力 | 90% | 使用现有测试环境可演示完整后端业务和 Agent 流程 | 整体判断： @@ -89,14 +89,15 @@ - Agent 工具和调用流程。 - 证据、日报、行为分和审计说明。 - 前端合并提示词与验收约束。 +- 演示机数据插入规则。 ## 验证结果 | 检查项 | 结果 | |---|---| -| 全量测试 | `697 passed, 1 skipped` | +| 风控专项回归 | `232 passed` | | Ruff 静态检查 | 通过 | -| 风控专项测试 | 通过 | +| Portal 前端契约 | `41 passed` | | 真实 Agent Run 验收 | 三类业务对话通过 | | 数据库结构审计 | 51 张业务表通过 | | 约束审计 | 通过 | @@ -137,11 +138,11 @@ ### 主项目正式前端 -状态：未开始。 +状态：已接入，待完整联调。 -- 正式页面需要使用主项目现有导航、主题、组件、请求封装和权限模型。 -- `private_frontend` 只作为交互参考。 -- 需要补充桌面、移动端和权限场景验收。 +- 风控正式页面已使用主项目现有导航、主题、组件、请求封装和权限模型。 +- `private_frontend` 只作为交互参考，不作为正式页面。 +- 需要补充桌面、移动端、权限、分页和 Agent 会话场景验收。 ### 公共底座质量例外 @@ -162,7 +163,7 @@ | 阻塞项 | 影响 | 处理方式 | |---|---|---| -| 正式前端未合并 | 无法按主项目正式界面演示 | 按前端提示词文档执行合并 | +| 正式前端端到端验收未完成 | 账号、权限、分页、Agent 和邮件链路仍可能暴露联调问题 | 使用主项目正式前端执行完整验收 | | 私有前端尚未适配新信封和幂等请求头 | 预警列表、分页和写操作会失败 | 后端处理完成后统一改造 | | 主项目完整联调未完成 | 跨模块权限、导航和接口仍需验证 | 在 qyqy_develop 环境联调 | | 对话历史暂缓 | 跨轮长期记忆能力有限 | 迁移完成后单独实施 | @@ -174,16 +175,17 @@ 1. 将 `RM2_develop` 与最新 `qyqy_develop` 保持同步。 2. 将定时规则扫描和高风险预警邮件配置纳入主项目部署配置。 3. 将定时规则扫描接入主项目统一 Worker 或部署编排，取消业务人员手工启动独立进程。 -4. 按 `17-风控模块-前端合并提示词与验收约束.md` 合并正式前端。 -5. 使用主项目真实登录、账号、角色和客户归属完成联调。 -6. 执行桌面端、移动端、权限、降级和完整业务链路验收。 -7. 主项目稳定后再实施对话历史、Redis 缓存和长期留存。 +4. 按 `26-演示机数据插入规则.md` 准备演示机上游数据。 +5. 使用主项目正式前端执行完整验收，重点覆盖分页、权限和 Agent 连续会话。 +6. 使用主项目真实登录、账号、角色和客户归属完成联调。 +7. 执行桌面端、移动端、权限、降级和完整业务链路验收。 +8. 主项目稳定后再实施对话历史、Redis 缓存和长期留存。 ## 完成判定 风控模块可以认为完成，需要同时满足： -- 正式前端接入主项目。 +- 正式前端已接入主项目，并完成端到端验收。 - 真实账号和 RBAC 验证通过。 - 风控接口、页面和 Agent 完整可用。 - 关键处置流程和审计可追溯。 diff --git a/docs/风控业务演示文档/22-风控模块需求说明书.md b/docs/风控业务演示文档/22-风控模块需求说明书.md index 51ade1a..8a9f7d1 100644 --- a/docs/风控业务演示文档/22-风控模块需求说明书.md +++ b/docs/风控业务演示文档/22-风控模块需求说明书.md @@ -5,7 +5,7 @@ | 项目 | 内容 | |---|---| | 文档版本 | v1.0 | -| 编制日期 | 2026-09-13 | +| 编制日期 | 2026-09-14 | | 适用对象 | 主项目架构、前端、后端、测试、运维和风控业务人员 | | 实现基线 | 当前 `RM2_develop` 风控模块代码 | | 文档定位 | 主项目合并和联调时的风控模块统一需求口径 | @@ -48,8 +48,8 @@ - 客户账户开户、充值、提现和真实资金操作。 - 修改交易、资金、持仓和产品事实。 - 自动确认、自动关闭或自动升级预警。 -- 由风控模块提供演示数据初始化。 -- 正式前端页面实现。 +- 演示数据由演示机按 `26-演示机数据插入规则.md` 准备，风控模块不负责初始化。 +- 正式前端页面由主项目统一前端实现，风控模块只提供接口和合并约束。 - 高风险预警邮件多收件人扩展。 - 将定时扫描自动注册到主项目统一 Worker。 @@ -217,7 +217,7 @@ - 默认只查询未闭环预警。 - 支持按关键词、客户编号、产品、风险等级、规则和创建时间筛选。 - 按高风险、中风险、低风险排序，同等级按创建时间倒序。 -- 预警队列每页固定最多 5 条。 +- 预警队列每页固定最多 10 条。 ### FR-03 预警详情 @@ -301,6 +301,9 @@ - 使用主项目 `agent_type=risk`。 - 只允许查询风险概览、预警列表和指定预警证据。 - 支持生成研判草案、沟通话术和工单摘要。 +- 同一 `session_id` 内使用最近 10 轮会话历史，支持连续追问。 +- 通用风险问答和预警上下文分别维护会话。 +- 刷新页面后当前不承诺跨刷新恢复。 - Agent 不能确认、调查、关闭、升级预警，不能修改客户和交易事实。 - 客户姓名和敏感信息必须脱敏。 @@ -358,8 +361,7 @@ ### 8.3 分页 -- 预警列表每页最多 5 条。 -- 其他列表每页最多 10 条。 +- 预警列表和其他列表每页最多 10 条。 - 使用游标分页，游标绑定用户、筛选条件和数据范围。 - 不允许只把页码或 offset 暴露给客户端。 @@ -413,7 +415,7 @@ ## 10. 验收标准 - 未闭环预警、等级分布、待处理和超时统计正确。 -- 预警队列按风险等级排序，每页最多 5 条。 +- 预警队列按风险等级排序，每页最多 10 条。 - 五类规则按条件正确触发，不重复生成同一交易同规则预警。 - 多规则命中同一交易时正确合并。 - 人工处置状态机不允许非法跳转。 @@ -430,5 +432,5 @@ - 高风险预警邮件当前只支持一个收件人。 - 定时扫描当前仍需独立进程，主项目需提供统一 Worker 注册或部署编排。 - 本期不支持对话历史长期归档和 Redis-only 会话方案。 -- 正式前端需要遵循 `17-风控模块-前端合并提示词与验收约束.md`。 +- 正式前端已接入主项目，后续变更继续遵循 `17-风控模块-前端合并提示词与验收约束.md`。 - 主项目合并前需要按 `21-主项目合并后后端必改清单.md` 完成接入。 diff --git a/docs/风控业务演示文档/23-风控模块接口文档.md b/docs/风控业务演示文档/23-风控模块接口文档.md index c574f03..91d8bc6 100644 --- a/docs/风控业务演示文档/23-风控模块接口文档.md +++ b/docs/风控业务演示文档/23-风控模块接口文档.md @@ -5,7 +5,7 @@ | 项目 | 内容 | |---|---| | 文档版本 | v1.0 | -| 编制日期 | 2026-09-13 | +| 编制日期 | 2026-09-14 | | 接口前缀 | `/api/v1/risk` | | Agent 接口 | `/api/v1/agent-runs` | | 适用对象 | 主项目后端、前端、联调和测试人员 | @@ -96,8 +96,7 @@ user_id + method + normalized_path + idempotency_key ### 1.5 分页 -- 预警队列：每页最多 5 条。 -- 其他列表：每页最多 10 条。 +- 预警队列和其他列表：每页最多 10 条。 - 游标绑定用户、筛选条件和数据范围。 - 客户端应原样回传 `meta.next_cursor`。 - 风控列表接口在 `meta` 中返回 `total` 和 `page_size`，用于展示总条数和总页数。 @@ -197,7 +196,7 @@ user_id + method + normalized_path + idempotency_key | `start_time` | datetime | 否 | 创建时间起 | | `end_time` | datetime | 否 | 创建时间止 | | `cursor` | string | 否 | 分页游标 | -| `limit` | integer | 否 | 1-5，默认 5 | +| `limit` | integer | 否 | 1-10，默认 10 | 默认只返回未闭环预警，排序为高风险、中风险、低风险，同等级按创建时间倒序。 @@ -802,6 +801,14 @@ Accept: text/event-stream - 绕过权限和数据范围。 - 在未取得完整数据时声称已经覆盖全部数据。 +### 13.5 会话历史 + +- 同一个 `session_id` 表示同一场对话。 +- Worker 会从 MySQL 读取该会话最近 10 轮消息，并在系统提示和当前问题之间传给风险 Agent。 +- 通用风险问答与预警上下文使用不同 `session_id`。 +- 刷新页面后前端会创建新 `session_id`，当前不承诺跨刷新恢复上下文。 +- 历史消息只用于理解指代，不能作为本轮工具调用或处置指令的依据。 + ## 14. 状态和枚举 ### 14.1 预警等级 diff --git a/docs/风控业务演示文档/24-主项目风控前端改造TODO.md b/docs/风控业务演示文档/24-主项目风控前端改造TODO.md index 75754ed..dbf6ec1 100644 --- a/docs/风控业务演示文档/24-主项目风控前端改造TODO.md +++ b/docs/风控业务演示文档/24-主项目风控前端改造TODO.md @@ -5,7 +5,7 @@ | 项目 | 内容 | |---|---| | 文档版本 | v1.0 | -| 编制日期 | 2026-09-13 | +| 编制日期 | 2026-09-14 | | 对比对象 | 原项目单页风控工作台与主项目 `/portal/employee-risk/dashboard/` | | 改造原则 | 保留主项目增强能力，补齐原项目缺失能力，破坏性交互调整先讨论 | @@ -19,7 +19,7 @@ - 统一门户、员工登录页和角色分流。 - 统一 `api-client.js`、错误码、trace ID、重试和 401 会话失效处理。 - 风险概览“未闭环预警”正确口径。 -- 预警队列按风险等级排序，每页 5 条。 +- 预警队列按风险等级排序，每页 10 条。 - 预警筛选、证据筛选和游标分页。 - 通知记录展示发送状态和失败原因。 - 手动扫描 `RK006` 60 秒独立超时。 @@ -40,7 +40,7 @@ |---|---|---|---|---|---| | FE-01 | 保留主项目统一前端增强能力 | 约束 | P0 | 否 | 防止功能回退 | | FE-02 | 日报展示数据来源、生成时间和结构化九段内容 | 修改 | P0 | 否 | 前端 | -| FE-03 | Agent 连续会话与会话归属 | 修改 | P0 | 是 | 前端，可能涉及会话策略 | +| FE-03 | Agent 连续会话与会话归属 | 部分完成 | P0 | 否 | 同页连续会话已完成，刷新恢复待后续讨论 | | FE-04 | Agent 绑定当前预警上下文 | 修改 | P0 | 是 | 前端，可能涉及 Agent 输入约定 | | FE-05 | 恢复研判、话术、工单摘要快捷指令 | 修改 | P1 | 是 | 前端提示词 | | FE-06 | 增加 Agent 能力边界和免责声明 | 修改 | P1 | 否 | 前端 | @@ -85,13 +85,14 @@ ### FE-03 Agent 连续会话与会话归属 -当前问题： +当前状态： -- 每条消息都创建新的随机 `session_id`。 -- 没有连续上下文。 -- 切换页面或刷新后无法恢复会话。 +- 同一页面、同一会话内已复用 `session_id`。 +- Worker 会读取同一会话最近 10 轮消息并传给风险 Agent。 +- 通用风险问答与预警上下文分别维护。 +- 刷新页面后仍会创建新会话，当前不承诺跨刷新恢复。 -需要讨论： +剩余讨论： 1. 会话是否按“当前用户 + 预警编号”归属。 2. 通用风控问答是否使用独立会话。 @@ -264,6 +265,7 @@ - Agent 按通用和预警分别维护会话状态。 - Agent 在同一会话内复用 `session_id`。 +- 风险 Agent 已使用同一会话最近 10 轮历史。 - 打开预警后自动切换预警会话，并支持退出上下文。 - 增加研判、话术和工单摘要三个预警场景指令。 - 增加 Agent 能力边界和免责声明。 @@ -276,9 +278,10 @@ - 使用主项目统一前端完成桌面端、移动端和权限状态验收。 - 验证 Agent 连续会话与预警上下文在真实模型下的表现。 +- 评估是否将 `session_id` 持久化，以支持刷新页面后的会话恢复。 - 政策解读数据源接入属于后续独立事项。 -## 9. 前端问题记录、解答与处理状态（2026-09-13） +## 9. 前端问题记录、解答与处理状态（2026-09-14） ### BUG-01 证据表展开按钮位于最右侧 @@ -427,7 +430,7 @@ - 站内提醒入口已优化：改为带铃铛图标和数量的明确按钮，弹窗只展示站内提醒，支持直接打开预警和跳转通知记录。 - 风控列表分页已增加总条数和总页数：接口补齐 `meta.total`、`meta.page_size`，前端显示“第 x / y 页，共 n 条”。 -## 10. 新增前端问题记录与解答（2026-09-13） +## 10. 新增前端问题记录与解答（2026-09-14） ### BUG-07 预警详情中的证据快照显示数据库原生字段 diff --git a/docs/风控业务演示文档/26-演示机数据插入规则.md b/docs/风控业务演示文档/26-演示机数据插入规则.md new file mode 100644 index 0000000..e02f222 --- /dev/null +++ b/docs/风控业务演示文档/26-演示机数据插入规则.md @@ -0,0 +1,204 @@ +# 演示机数据插入规则 + +## 文档定位 + +本文交给演示机实施人员使用，用于准备风控模块演示所需的上游业务数据。 +风控预警和通知是派生数据，必须由扫描器生成，不允许为了让页面“有数据”而直接插入。 + +适用前置条件： + +1. 演示机已完成最新 Alembic 迁移。 +2. 风控角色、权限和数据范围已经初始化。 +3. 演示环境时间口径为北京时间，数据库时间字段使用 UTC naive。 +4. 风控页面使用正式主项目前端。 + +## 一、固定原则 + +- 可以写入 `sys_user`、`fin_customer_profile`、`fin_product`、`fin_sim_account`、 + `fin_holding`、`fin_sim_order`、`fin_transaction`、`fin_capital_flow`、 + `sys_login_record`、`biz_work_order`、`fin_risk_assessment`。 +- 禁止直接写入 `fin_risk_alert` 和 `fin_risk_notification`。 +- 演示客户和产品使用独立号段，不覆盖真实或已有演示数据。 +- 所有业务编号必须唯一，重复执行时按业务编号做幂等更新。 +- 时间字段必须是 UTC naive。业务判断中的凌晨、当日、日期范围按北京时间换算。 +- 客户风险等级在 `sys_user.investor_type` 和 `fin_customer_profile.investor_type` + 中必须一致。 +- 预警扫描产生的结果由系统负责生成证据快照、合并规则和通知记录。 + +## 二、建议插入顺序 + +1. `fin_product`，并确认产品风险等级和风险揭示要求。 +2. `sys_user` 和 `sys_user_role`，客户绑定 `customer` 角色。 +3. `fin_customer_profile`，同步客户风险等级、年龄、总资产和行为分。 +4. `fin_risk_assessment`，保证客户画像和适当性链路完整。 +5. `fin_sim_account`，保证客户有模拟账户。 +6. `fin_holding`，保证持仓和豁免额度证据存在。 +7. `biz_work_order`，先建工单，再让交易引用。 +8. `fin_sim_order`，为每笔交易建立模拟委托。 +9. `fin_transaction`，写入申购或赎回成交记录。 +10. `fin_capital_flow`，补入金、出金和资金到账时间。 +11. `sys_login_record`，补交易前的成功登录和非固定设备证据。 +12. 回到风控页面执行手动扫描，生成预警和通知。 + +## 三、字段和取值规则 + +### `sys_user` + +必须满足： + +- `user_type = 'customer'`。 +- `status = '正常'`。 +- `fund_account_status = '已开户'`。 +- `investor_type` 必须为 `C1`、`C2`、`C3`、`C4` 或 `C5`。 +- `is_professional_investor = 0`，除非该演示场景需要专业投资者身份。 +- `professional_investor_status = 'none'`，除非有单独的合规依据。 +- `sys_user_role` 必须关联 `customer` 角色，不能只建用户不建角色。 + +### `fin_customer_profile` + +- `customer_id` 必须与 `sys_user.id` 一致。 +- `trade_account` 必须与模拟账户号一致。 +- `investor_type` 必须与 `sys_user.investor_type` 一致。 +- `birth_date` 必须可计算年龄，RW-012 年龄要求不小于 65 岁。 +- `total_asset` 必须为正数，豁免比例场景需要它。 +- `behavior_score` 使用 0 至 20 分制。 +- `preferred_asset_class` 建议写 JSON 数组，例如 `["固定收益类", "权益类"]`。 + +### `fin_product` + +- `product_code` 使用独立演示编码，不能与正式产品重复。 +- `status = '上市'`。 +- `risk_level` 必须为 `R1`、`R2`、`R3`、`R4` 或 `R5`。 +- `risk_disclosure_required`、`second_confirmation_required`、`recording_required` + 只能为 0 或 1。 +- 要触发 RW-007 缺失留痕场景，相关要求字段必须为 1，且对应工单字段为空。 +- C3 配置 R4、C4 配置 R5 时，还要保证 `total_asset` 和 `fin_holding.current_value` + 口径一致，才能测试豁免额度。 + +### `fin_sim_account` + +- `customer_id` 必须存在。 +- `currency = 'CNY'`。 +- `status = '正常'`。 +- `cash_balance`、`available_cash`、`initial_balance` 必须为合理正数。 +- `account_no` 建议使用稳定编号，例如 `FSA{客户ID}`。 + +### `fin_holding` + +- `customer_id`、`trade_account`、`product_id` 必须有效。 +- `shares`、`total_quantity`、`available_quantity`、`current_value` 必须为正。 +- `current_value` 应与持仓数量和最新净值口径一致。 +- RW-007 豁免场景中，`current_value / fin_customer_profile.total_asset` + 必须能够超过 20% 或 10% 的豁免上限。 + +### `fin_sim_order` + +- 每笔 `fin_transaction` 必须关联一个有效 `order_id`。 +- `order_side` 使用交易接口实际口径 `buy` 或 `sell`。 +- `status` 使用 `已成交`。 +- `quote_source` 可以使用演示来源，但必须能让页面识别。 +- `quote_at`、`submitted_at`、`created_at`、`updated_at` 使用 UTC naive 时间。 + +### `fin_transaction` + +- `transaction_type` 必须使用 `申购` 或 `赎回`，风控扫描按这两个值识别。 +- `order_side` 使用 `buy` 或 `sell`，规则不依赖该字段判断方向。 +- `customer_id`、`account_id`、`product_id` 必须有效。 +- `amount` 必须为正数，且与 `gross_amount`、`net_amount` 的口径保持一致。 +- `confirmed_at` 必须非空，风控扫描按该时间计算时间窗口。 +- 同一笔风险场景不要生成多笔近似重复交易，以免影响历史均值。 +- 需要触发工单规则时，`work_order_id` 必须指向有效工单。 + +### `fin_capital_flow` + +- `flow_type` 使用 `入金` 或对应真实业务类型。 +- RW-003 必须使用 `flow_type = '入金'`。 +- RW-003 的 `status` 必须为 `成功`。 +- RW-003 的 `settled_at` 必须不晚于赎回交易 `confirmed_at`。 +- RW-003 的 `settled_at` 必须处于赎回时间前 3 天内。 +- `customer_id`、`account_id` 必须与交易一致。 + +### `sys_login_record` + +- `user_id` 必须为目标客户。 +- `login_result = '成功'`。 +- `login_at` 必须早于或等于风险交易 `confirmed_at`。 +- RW-012 需要 `is_common_device = 0`。 +- 设备编号不能为空，建议使用可识别的演示设备号。 + +### `biz_work_order` + +- `work_order_no` 必须唯一。 +- `customer_id`、`product_id` 必须有效。 +- `channel` 是 RW-018 的关键字段： + - `定投` + - `自动定投` +- 要触发 RW-007 缺失留痕，按产品要求留空对应字段： + - `risk_disclosure_ack_at` + - `second_confirmation_at` + - `recording_reference` +- 要测试正常放行场景，则应把产品要求的字段全部补齐。 + +### `fin_risk_assessment` + +- `customer_id` 必须存在。 +- `questionnaire_version` 使用独立演示版本。 +- `investor_type` 必须与客户画像一致。 +- `assessed_at`、`valid_until` 必须有效。 +- 风控扫描本身不依赖该表，但客户证据和画像页面需要它。 + +## 四、规则场景矩阵 + +| 规则 | 客户准备 | 产品准备 | 交易准备 | 其他证据 | 预期 | +|---|---|---|---|---|---| +| RW-003 | C3 或 C4 客户 | R3 产品 | 赎回金额达到 50 万，赎回比例达到 80% | 3 天内有成功入金流水 | 高风险 | +| RW-007 | C1 客户 | R4 或 R5 产品，风险揭示或二次确认要求为 1 | 申购记录 | 工单对应留痕缺失 | 高风险 | +| RW-007 | C3 客户 | R4 产品，风险揭示要求为 1 | 申购记录 | 工单缺少风险揭示 | 中风险 | +| RW-012 | 65 岁以上客户 | 任意可赎回产品 | 赎回金额达到 30 万，且达到历史均值 3 倍 | 交易前成功登录，非固定设备 | 高风险 | +| RW-015 | 任意客户 | 任意产品 | 北京时间 00:00 至 05:59，金额不超过 1 万 | 无需额外证据 | 低风险 | +| RW-018 | 任意客户 | 任意产品 | 交易关联工单 | 工单渠道为 `定投` 或 `自动定投` | 低风险 | +| 合并 | 任意客户 | 任意产品 | 同一交易同时满足 RW-015 和 RW-018 | 凌晨小额自动定投 | 一条合并预警 | + +## 五、时间生成规则 + +演示机不要写死日期，建议按当前时间动态生成： + +| 字段 | 时间关系 | +|---|---| +| RW-003 入金 `settled_at` | 当前时间减 1 天 | +| RW-003 赎回 `confirmed_at` | 当前时间 | +| RW-012 历史交易 `confirmed_at` | 当前时间减 30 至 60 天 | +| RW-012 登录 `login_at` | 当前时间减 2 小时 | +| RW-012 当前赎回 `confirmed_at` | 当前时间 | +| RW-015 交易 `confirmed_at` | 北京时间当天或前一天 02:00 至 05:59 | + +数据库写入前必须将北京时间转换为 UTC naive。 + +## 六、插入后检查 + +至少执行以下检查： + +1. `sys_user.investor_type` 与 `fin_customer_profile.investor_type` 完全一致。 +2. 每个客户都有有效模拟账户和至少一笔持仓。 +3. 每笔交易都有对应的 `order_id`。 +4. 需要触发 RW-003 的客户都有成功入金流水，且入金时间处于赎回前 3 天内。 +5. 需要触发 RW-012 的客户都有交易前成功登录记录，且 `is_common_device = 0`。 +6. 需要触发 RW-007 的工单留痕字段确实缺失，或豁免比例确实超过上限。 +7. 每个演示客户的交易数量足以支持历史均值计算，至少应有一笔历史对比交易。 +8. 扫描后检查 `fin_risk_alert.trigger_rule_codes`、`alert_level` 和 + `related_transaction_id` 是否符合预期。 + +## 七、扫描后的验收 + +数据插入完成后，由演示机执行风控扫描，再检查： + +- 预警数量是否新增。 +- 每笔交易命中的规则是否正确。 +- 风险等级是否正确。 +- 证据详情是否能关联到客户、产品、交易、资金、登录和工单。 +- 同一交易命中多条规则时是否合并为一条预警。 +- 高风险预警是否产生通知记录。 +- 邮件开关和收件人配置是否符合演示要求。 + +如果扫描没有产生预警，首先检查源数据字段、枚举值、时间和关联关系，不要通过直接修改 +`fin_risk_alert` 来掩盖问题。 diff --git a/docs/风控业务演示文档/README.md b/docs/风控业务演示文档/README.md index 918d2a3..e5f0852 100644 --- a/docs/风控业务演示文档/README.md +++ b/docs/风控业务演示文档/README.md @@ -45,6 +45,7 @@ | 22 | 风控模块需求说明书 | 统一业务需求、规则、边界和验收口径 | | 23 | 风控模块接口文档 | 提供 REST、SSE、字段和联调约定 | | 24 | 主项目风控前端改造TODO | 记录前端保留项、修改项和待讨论方案 | +| 26 | 演示机数据插入规则 | 说明演示机准备上游数据的表、字段、场景和检查规则 | ## 推荐阅读顺序 @@ -60,3 +61,4 @@ 10. 21：主项目代码合并后的后端整改与验收。 11. 22、23：分别作为需求交付和接口联调的统一入口。 12. 24：主项目风控前端改造的事项、决策项和实施顺序。 +13. 26：演示机准备上游数据时按表、字段、场景和检查规则执行。