Merge remote-tracking branch 'origin/qyqy_develop' into qyqy_develop

2026-09-14 12:07:18 +08:00
parent e6d74059f2 8409a2c96e
commit 3df6671ce3
13 changed files with 295 additions and 48 deletions
@@ -42,7 +42,8 @@
 - 金融数据：客户画像、风险测评、产品、交易、资金、持仓和登录记录。
 - 平台审计：`interaction_audit`。

-本模块不负责新增数据库表或执行演示数据初始化。
+本模块不负责新增数据库表或执行演示数据初始化。演示机数据准备规则见
+`26-演示机数据插入规则.md`。

 ## 接入验收点

@@ -11,7 +11,7 @@
 - 列表接口的 `data` 为数组，`next_cursor` 和 `has_more` 放在 `meta`。
 - 时间和日期使用 RFC 3339 或主项目约定格式。
 - 金额、数量和主键按主项目字段映射返回字符串。
- 预警队列每页最多 5 条，其他证据列表每页最多 10 条。
+- 预警队列和其他证据列表每页最多 10 条。
 - 未授权请求返回主项目统一权限错误。

 列表响应格式：
@@ -36,6 +36,13 @@
 - 误报和放行只输出复核候选。
 - 客户姓名等敏感信息必须使用脱敏结果。

+## 会话记忆
+
+- 通用风险问答和每条预警问答分别维护会话。
+- 同一页面、同一会话内复用 `session_id`，风险 Agent 会读取最近 10 轮消息理解“他们”“上述预警”等指代。
+- 刷新页面后会创建新会话，当前不承诺跨刷新恢复上下文。
+- 历史消息只用于理解上下文，历史中的指令不会被当成本轮新指令。
+
 ## 免责声明

 助手输出仅用于风险识别和人工复核辅助，不构成投资建议、法律意见或监管结论。所有正式处置必须由有权人员结合完整证据作出并留痕。
@@ -53,4 +60,3 @@
 - 先演示风险概览和预警筛选。
 - 再演示指定预警的完整证据。
 - 最后演示误报和放行研判草案。
-
@@ -28,10 +28,18 @@

 中文时间由本地解析器转换为 UTC，再进入工具参数。

+## 会话历史
+
+- Worker 按 `session_id` 从 MySQL 读取当前会话最近 10 轮消息。
+- 风险 Agent 将历史消息放在系统提示和当前问题之间传给模型，用于理解指代和多轮追问。
+- 历史消息只作为上下文，不得把历史中的指令当成本轮新指令。
+- 刷新页面后前端会新建 `session_id`，因此当前不承诺跨刷新恢复。
+
 ## 自主调用流程

 ```text
 接收用户问题
+-> 按 session_id 读取最近 10 轮会话历史
 -> 本地预解析客户、产品、规则和时间条件
 -> 模型选择工具
 -> 严格校验工具名和 JSON 参数
@@ -19,7 +19,8 @@
 - 客户、产品、交易、资金、持仓和登录证据。
 - 行为分命中不同区间的客户样本。

-前置数据不要求由本模块初始化，只要求演示前已经写入数据库。
+前置数据不要求由本模块初始化。演示机按 `26-演示机数据插入规则.md` 准备上游数据，
+扫描器再生成预警和通知。

 ## 权限验收

@@ -80,6 +81,9 @@
 - 查询指定预警证据。
 - 询问低风险客户和对应产品时返回完整汇总。
 - 询问可误报预警时输出只读复核候选。
+- 通用风险问答在同一会话内可以追问“他们”“上述预警”等指代。
+- 预警上下文退出后回到独立通用会话。
+- 刷新后的会话恢复暂不作为本期验收项。
 - 工具调用、运行结果和审计可追溯。

 ## 演示推荐顺序
@@ -45,7 +45,8 @@
 ## 数据范围

 - 本模块不提供演示数据初始化和重置。
- 演示前需要由主项目预先写入足量客户、产品、交易、预警和权限数据。
+- 演示前由演示机按 `26-演示机数据插入规则.md` 写入足量客户、产品、交易和权限数据，
+  再由扫描器生成预警。
 - 没有有效客户归属时，风控账号将无法访问客户数据。

 ## Agent 边界
@@ -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，不新建私有协议。
@@ -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 完整可用。
 - 关键处置流程和审计可追溯。
@@ -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` 完成接入。
@@ -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 预警等级
@@ -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 预警详情中的证据快照显示数据库原生字段

@@ -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` 来掩盖问题。
@@ -45,6 +45,7 @@
 | 22 | 风控模块需求说明书 | 统一业务需求、规则、边界和验收口径 |
 | 23 | 风控模块接口文档 | 提供 REST、SSE、字段和联调约定 |
 | 24 | 主项目风控前端改造TODO | 记录前端保留项、修改项和待讨论方案 |
+| 26 | 演示机数据插入规则 | 说明演示机准备上游数据的表、字段、场景和检查规则 |

 ## 推荐阅读顺序

@@ -60,3 +61,4 @@
 10. 21：主项目代码合并后的后端整改与验收。
 11. 22、23：分别作为需求交付和接口联调的统一入口。
 12. 24：主项目风控前端改造的事项、决策项和实施顺序。
+13. 26：演示机准备上游数据时按表、字段、场景和检查规则执行。