group_fqcd_jr/docs/风控业务演示文档/17-风控模块-前端合并提示词与验收约束.md

前端合并提示词与验收约束

文档功能

本文档用于指导后续模型在主项目中识别风控模块功能、完成前端页面合并、保持主项目设计规范，并通过权限、功能和排版验收。文档同时提供一段可直接交给模型的提示词。

一、让模型识别风控模块

模型不能仅凭页面文字中的“风险”二字判断功能归属。风控模块使用以下明确标识：

标识	风控模块特征
API 前缀	/api/v1/risk
Agent 类型	agent_type=risk
Agent 名称	奶龙风控智能助手
权限前缀	risk:alert:read、risk:alert:write、risk:alert:scan
核心表	fin_risk_alert、fin_risk_notification、biz_work_order
核心代码	RiskController、RiskQueryService、RiskActionService、RiskAgent
文档目录	docs/风控业务演示文档
验证页面	private_frontend，只作为交互参考

后续模型开始前端合并前，必须先阅读本目录全部文档，并扫描上述代码和路由。

前端合并前必须对齐的补充口径（2026-09-14）

本节优先于后文中的概括性描述。前端合并时以本节为准。

风险概览口径

• 风险概览接口的 total 表示当前未闭环预警，状态范围为 待处理 和 调查中。
• total 不是当天新增预警，不受 created_at 当天范围限制。
• 前端指标名称应使用“未闭环预警”，不得继续显示为“今日预警”。

高风险预警邮件

• 手动扫描和定时扫描命中高风险预警后，后端都会创建站内通知并尝试发送邮件。
• 高风险预警邮件由后端配置决定收件人，前端不提供收件人输入框。
• 高风险预警邮件当前只支持一个收件人，前端不能按“多收件人”设计配置界面。
• 邮件状态取值包括 待发送、已发送、发送失败、未启用。
• 前端通知记录列表必须展示发送状态和失败原因，不能把“已创建通知记录”显示为“邮件已发送”。
• 邮件发送失败不回滚预警，也不等于整次扫描失败。扫描成功后仅刷新通知记录即可看到真实邮件状态。

两类邮件必须区分

• 高风险预警邮件：手动扫描或定时扫描自动触发，收件人来自风控邮件通知配置。
• 日报邮件：用户在高风险日报弹窗中填写收件人后手动发送，与预警扫描邮件互不替代。

二、前端功能范围

页面或区域	必需功能
风险概览	当前未闭环总量、风险等级、待处理、超时、重点预警；不得把总量显示为“今日预警”
预警队列	风险等级排序、筛选、每页 10 条、分页、弹窗详情
预警详情	预警编号、状态、规则、证据、回执、人工处置
证据区域	客户、产品、交易、资金、持仓、登录、预警、通知八类证据
证据筛选	客户行为分、风险等级、规则、客户、产品和时间筛选
人工处置	确认接收二次确认、进入调查、误报理由、结案、升级
证据归档	图片和文档上传、归档状态、失败提示
奶龙风控智能助手	对话、SSE 输出、工具调用展示、能力边界和免责声明
日报	弹窗展示、流式生成、内容编辑、多邮箱发送
通知	通知记录、预警编号、站内或邮件渠道、发送状态、失败原因
系统提示	政策解读、日报入口和预留模块

Agent 会话记忆口径

• 通用风险问答和每条预警问答分别维护会话。
• 同一页面、同一会话内复用 session_id，Worker 从 MySQL 读取最近 10 轮消息并传给风险 Agent。
• 刷新页面后会新建会话，当前不承诺跨刷新恢复上下文。
• 历史消息只用于理解指代，不得把历史中的指令当成本轮新指令。

三、排版和交互约束

必须遵守

• 使用主项目现有页面壳、导航、主题、表单、按钮、弹窗和表格组件。
• 使用主项目现有登录、JWT、请求封装、错误处理、分页和权限控制。
• 页面功能与接口字段一一对应，不自行编造字段。
• 预警队列和其他表格固定每页 10 条。
• 预警队列按风险等级排序，高风险优先。
• 表格行高固定，内容过长显示省略号，不能撑高行。
• 预警详情使用弹窗，不单独跳转到不存在的页面。
• 确认接收必须有二次确认。
• 关闭误报必须要求填写理由。
• Agent 对话使用主项目 Agent Run 和 SSE。
• 所有权限按钮必须同时受后端权限与前端可见性控制。

禁止事项

• 不直接复制 private_frontend 的页面结构和样式作为正式页面。
• 不创建第二套导航、登录页、主题或全局样式。
• 不硬编码访问令牌和用户 ID。
• 不会把角色名称当作权限本身。
• 不绕过后端直接修改状态。
• 不在前端生成演示数据。
• 不新增启动方式、访问地址或部署流程。
• 不在没有二次确认的情况下执行确认、结案、误报和升级。

四、权限和状态映射

操作	前端显示条件	后端权限
查看概览、预警、证据和日报	有只读权限	risk:alert:read
确认、调查、误报、结案和升级	有写权限	risk:alert:write
手动扫描	有扫描权限	risk:alert:scan
进入奶龙风控智能助手	有 Agent 权限和角色	agent:run、risk:alert:read
查看客户数据	有权限且有客户归属	客户数据范围校验

状态显示需与后端保持一致：

• 待处理。
• 调查中。
• 已排除。
• 已结案。
• 已升级作为标记，不替代处置状态。

五、接口和 SSE 约束

• 所有风控 REST 请求使用 /api/v1/risk。
• 使用主项目统一响应信封和错误处理。
• 列表接口的 data 必须是数组，游标和 has_more 从 meta 读取。
• 风控写接口和扫描接口必须生成并携带唯一 Idempotency-Key。
• Idempotency-Key 只用于写请求，证据上传暂不要求。
• Agent 对话使用 /api/v1/agent-runs 和 SSE 事件。
• 不在前端实现另一套 Agent 对话协议。
• SSE 需要处理 start、tools、delta、replace、done 和 error。
• 断线重连后根据 run_id 恢复最终结果。

六、预警操作结果提示

本节要求不依赖后端修改，前端根据当前接口响应统一实现操作成功和失败提示。

成功提示

操作返回 HTTP 2xx 后，根据操作类型显示对应提示：

操作	提示
确认接收	预警已确认接收
进入调查	已进入调查
关闭误报	已关闭误报
完成结案	预警已完成结案
升级处理	预警已升级
上传证据	证据上传成功
手动扫描	预警扫描完成
生成日报	日报生成完成
日报邮件发送	日报邮件发送成功

手动扫描成功只表示预警扫描完成。高风险预警邮件发送失败不会让扫描接口返回失败，前端应刷新通知记录，并通过通知的发送状态和失败原因展示真实结果。

失败提示

失败时优先读取主项目统一错误信封：

{
  "error": {
    "code": "AGENT_PERMISSION_DENIED",
    "message": "缺少操作权限"
  }
}

前端统一按以下顺序解析：

error.message
-> HTTP 状态码映射
-> 通用失败提示

推荐映射：

状态或错误码	提示
401 AUTHENTICATION_REQUIRED	登录已失效，请重新登录
403 AGENT_PERMISSION_DENIED	没有当前操作权限
404	预警不存在或无权查看
409	当前状态不允许该操作
413	文件超过大小限制
422	提交内容不符合要求
500	系统异常，请稍后重试
503/504	服务暂时不可用

组合操作

“完成处置并上传证据”必须分别提示：

• 文件上传成功、结案失败：提示“证据已上传，结案失败”，不重复上传文件。
• 文件上传失败、结案未执行：提示上传失败，保留弹窗填写内容。
• 结案成功、页面刷新失败：继续提示结案成功，再单独刷新列表或详情。
• 重复操作返回 409：刷新预警详情，提示“预警可能已处理，请核对状态”。

交互要求

• 操作进行中禁用重复点击，并显示进行中状态。
• 写请求失败时不得复用同一个 Idempotency-Key 提交不同内容。
• 写请求超时后可使用同一请求体和同一键重试，以获取首次结果。
• 成功或失败必须使用主项目统一的消息、Toast 或通知组件。
• 不能只用控制台日志代替用户提示。
• 弹窗关闭前必须明确操作结果。
• 不使用浏览器原生 alert 作为正式交互方案。

七、验收要求

后续模型完成前端后必须提供：

1. 功能与 API 权限映射表。
2. 页面截图，至少覆盖桌面和移动端。
3. 风险概览、预警队列、详情弹窗、处置、证据、Agent、日报完整流程。
4. 无权限、未分配客户、非法状态和模型降级场景。
5. 文字不重叠、内容不溢出、表格行高稳定。
6. 权限按钮与服务端权限一致。
7. 不直接修改风控业务规则和数据库结构。

八、可直接交给后续模型的提示词

你正在把风控模块前端合并到主项目中。开始写代码前必须完成以下工作：

1. 阅读 docs/风控业务演示文档 下全部文档。
2. 扫描 app/api/controllers/risk.py、app/api/schemas/risk.py、app/service/risk_*、app/service/agent/implementations/risk_agent.py。
3. 将所有 /api/v1/risk 路由、agent_type=risk、risk:alert:* 权限、fin_risk_alert 等表标记为风控模块范围。
4. 阅读主项目现有前端目录、页面壳、路由、主题、组件、请求封装、登录和权限实现。
5. private_frontend 只能作为交互参考，不能直接复制为正式页面。

在实现前先输出：
- 风控功能清单。
- 页面与 API 映射表。
- 按钮与权限映射表。
- 需要新增或修改的前端文件清单。
- 不修改的主项目公共文件清单。
- 验收用例清单。

实现要求：
- 使用主项目现有设计与组件。
- 风险概览、预警队列、八类证据、预警详情弹窗、人工处置、证据上传、Agent 对话、日报、通知都要接入现有接口。
- 预警队列和其他列表每页 10 条，按主键或接口约定稳定排序。
- 预警队列按风险等级优先排序，行高固定，内容过长省略。
- 确认接收需要二次确认，误报必须填写理由。
- Agent 对话必须使用主项目 Agent Run 和 SSE，不新建私有协议。
- 所有预警操作必须实现成功和失败提示；后端不修改，前端解析统一错误信封并按操作类型生成提示。
- 完成处置并上传证据时，必须分别处理上传和结案的成功、失败及部分成功场景。
- 页面权限和按钮可见性必须由后端权限和 roles/permissions 决定。
- 不修改公共底座，不新增启动顺序和访问地址，不生成演示数据。

实现后必须提供：
- 全量测试和静态检查结果。
- 桌面与移动端截图。
- 正常、越权、非法状态、模型降级和 SSE 恢复测试。
- 文字无重叠、无溢出、无布局抖动。
- 风控功能与主项目其他模块边界清晰。