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-12）

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

### 风险概览口径

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

### 高风险预警邮件

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

### 两类邮件必须区分

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

## 二、前端功能范围

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

## 三、排版和交互约束

### 必须遵守

- 使用主项目现有页面壳、导航、主题、表单、按钮、弹窗和表格组件。
- 使用主项目现有登录、JWT、请求封装、错误处理、分页和权限控制。
- 页面功能与接口字段一一对应，不自行编造字段。
- 预警队列固定每页 5 条，其他表格固定每页 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 后，根据操作类型显示对应提示：

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

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

### 失败提示

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

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

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

```text
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. 不直接修改风控业务规则和数据库结构。

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

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

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

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