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

This commit is contained in:
2026-09-13 23:38:57 +08:00
6 changed files with 1207 additions and 65 deletions
@@ -0,0 +1,530 @@
# 主项目风控前端改造 TODO
## 文档信息
| 项目 | 内容 |
|---|---|
| 文档版本 | v1.0 |
| 编制日期 | 2026-09-13 |
| 对比对象 | 原项目单页风控工作台与主项目 `/portal/employee-risk/dashboard/` |
| 改造原则 | 保留主项目增强能力,补齐原项目缺失能力,破坏性交互调整先讨论 |
## 1. 改造边界
### 1.1 必须保留
以下能力属于主项目统一前端增强,不得因对齐原项目而回退:
- 统一登录、JWT、RBAC、数据范围和服务端权限校验。
- 统一门户、员工登录页和角色分流。
- 统一 `api-client.js`、错误码、trace ID、重试和 401 会话失效处理。
- 风险概览“未闭环预警”正确口径。
- 预警队列按风险等级排序,每页 5 条。
- 预警筛选、证据筛选和游标分页。
- 通知记录展示发送状态和失败原因。
- 手动扫描 `RK006` 60 秒独立超时。
- 响应式布局、统一主题、组件和移动端基础适配。
- 证据上传大小限制、文件类型校验和归档唯一约束。
### 1.2 不在本次前端改造范围
- 修改风控 REST 接口路径、权限码和数据范围逻辑。
- 修改预警状态机、行为分和规则扫描算法。
- 将高风险邮件扩展为多收件人。
- 自动确认、自动关闭或自动升级预警。
- 将定时扫描并入 Web 进程。
## 2. TODO 总览
| 编号 | 事项 | 类型 | 优先级 | 是否需先讨论 | 预计影响 |
|---|---|---|---|---|---|
| FE-01 | 保留主项目统一前端增强能力 | 约束 | P0 | 否 | 防止功能回退 |
| FE-02 | 日报展示数据来源、生成时间和结构化九段内容 | 修改 | P0 | 否 | 前端 |
| FE-03 | Agent 连续会话与会话归属 | 修改 | P0 | 是 | 前端,可能涉及会话策略 |
| FE-04 | Agent 绑定当前预警上下文 | 修改 | P0 | 是 | 前端,可能涉及 Agent 输入约定 |
| FE-05 | 恢复研判、话术、工单摘要快捷指令 | 修改 | P1 | 是 | 前端提示词 |
| FE-06 | 增加 Agent 能力边界和免责声明 | 修改 | P1 | 否 | 前端 |
| FE-07 | 恢复证据表关键字段 | 修改 | P1 | 是 | 前端 |
| FE-08 | 政策解读入口和数据来源 | 缺失 | P1 | 是 | 前端,可能需后端接口 |
| FE-09 | 系统提示入口 | 缺失 | P2 | 是 | 前端,可能复用通知 |
| FE-10 | 预警处置交互是否恢复原分步流程 | 交互 | P2 | 是 | 前端 |
| FE-11 | 主项目统一前端专项验收 | 验证 | P0 | 否 | 测试 |
## 3. 直接修改项
### FE-02 日报展示数据来源、生成时间和结构化九段内容
现状:
- 日报弹窗主要展示一个可编辑文本区。
- 模型成功生成时,接口返回 `source=模型`,但页面没有明确展示。
- `generated_at` 和结构化九段数据没有完整呈现。
目标:
- 生成完成后展示 `日报日期`、`生成时间` 和 `source`。
- `source=模型` 显示为“大模型生成”,`source=规则模板` 显示为“规则降级”。
- 保留可编辑正文和邮件发送。
- 增加九段式结构化预览,至少展示重点风险、未闭环、误报原因、类型分布和规则效果。
- `data_truncated=true` 时必须持续显示数据截断提示。
接口字段已存在,预计只需修改前端。
### FE-06 增加 Agent 能力边界和免责声明
目标:
- 明确说明 Agent 只能读取概览、预警和证据。
- 明确不能确认、调查、关闭、升级预警。
- 明确结论只是研判草案,不能替代人工复核。
- 文案遵循主项目品牌和统一组件样式。
不涉及接口和权限变化。
## 4. 先讨论后实现
### FE-03 Agent 连续会话与会话归属
当前问题:
- 每条消息都创建新的随机 `session_id`。
- 没有连续上下文。
- 切换页面或刷新后无法恢复会话。
需要讨论:
1. 会话是否按“当前用户 + 预警编号”归属。
2. 通用风控问答是否使用独立会话。
3. 会话历史和消息是否只保存在 Redis,还是继续写 MySQL。
4. 页面刷新后是否需要恢复上下文。
5. 是否保留多预警并行会话。
推荐方向:
- 每个预警一个会话。
- 通用问答一个会话。
- 会话 ID 在页面状态中复用,不再每条消息重新生成。
- 会话历史遵循主项目现有会话和记忆策略。
### FE-04 Agent 绑定当前预警上下文
原项目行为:
- 打开某条预警后,聊天上下文自动切换到该预警。
- 研判、话术和工单摘要预设自动携带当前预警。
- 可以主动退出当前预警上下文。
主项目当前行为:
- Agent 面板与预警详情没有上下文绑定。
- 快捷问题始终是通用问题。
需要讨论:
- 前端把 `alert_no` 拼入提问文本,还是扩展 Agent 请求上下文。
- 打开预警弹窗是否自动切换 Agent 上下文。
- Agent 标签页如何显示当前绑定的预警编号。
- 从预警详情切到通用问答时如何明确提示。
### FE-05 恢复研判、话术、工单摘要快捷指令
目标快捷指令:
- 生成研判:命中规则、核心证据、风险判断和人工复核建议。
- 生成话术:中性审慎的客户回访话术,不预设客户违规。
- 工单摘要:工单标题、命中规则、关键证据、建议动作和处理时限。
讨论项:
- 是否只在绑定预警后启用。
- 是否由前端拼提示词,还是由后端提供场景化任务模板。
- 是否分别映射 `task_type`,以便模型路由和评测。
### FE-07 恢复证据表关键字段
原项目比主项目多展示的字段:
- 客户:年龄、职业、总资产、风险等级、测评分数、测评是否过期、行为分。
- 产品:风险揭示、二次确认、双录要求。
- 交易:渠道、交易状态、风险揭示、二次确认、确认时间。
- 预警:优先级、处理时限、证据归档状态。
需要讨论:
- 在当前宽表布局中恢复全部字段,还是使用“主要列 + 详情展开”。
- 移动端隐藏哪些次要列。
- 是否通过列配置统一定义,避免每张表重复代码。
推荐方向:
- 桌面端保留核心列,增加“更多字段”展开。
- 移动端使用卡片详情,不强行展示宽表。
- 字段配置集中维护。
### FE-08 政策解读入口和数据来源
原项目包含“政策解读”弹窗,主项目风控工作台没有该入口。
需要讨论:
1. 政策内容来自知识库、独立风控接口还是静态配置。
2. 是否只允许风控角色查看。
3. 内容更新是否走知识发布流程。
4. 是否需要显示来源、版本、生效时间和引用链接。
5. 是否复用客服 Agent 的政策知识,而不是新增重复数据源。
当前主项目没有对应的风控政策 REST 端点,因此该事项可能需要先确定后端来源。
### FE-09 系统提示入口
原项目通过“系统提示”弹窗查看通知,主项目已把通知记录放进独立标签页。
需要讨论:
- 是否还需要全局系统提示图标。
- 是否只提示未读通知、系统公告和操作风险。
- 系统提示与通知记录是否合并。
- 已读状态当前没有后端能力,是否需要新增。
推荐方向:
- 不复制通知列表,只在统一门户提供未读通知入口。
- 没有已读能力前,不引入“已读”视觉状态。
### FE-10 预警处置交互是否恢复原分步流程
现状:
- 主项目使用统一操作弹窗。
- 误报理由、结案结论和升级理由通过通用字段提交。
- 证据上传独立放在预警详情中。
原项目:
- 确认接收有二次确认。
- 关闭误报、结案和升级使用独立面板。
- 证据上传附在结案面板中。
需要讨论:
- 统一弹窗是否已足够清晰。
- 是否恢复确认接收二次确认。
- 是否把证据上传重新放入结案流程。
- 是否保持主项目统一交互规范优先。
后端接口不变,改造只影响前端交互。
## 5. 实施顺序建议
### 第一阶段:低风险前端补齐
1. 日报展示 `source`、生成时间、截断提示和结构化内容。
2. Agent 能力边界和免责声明。
3. 证据表字段配置化。
### 第二阶段:Agent 体验改造
1. 确定会话归属策略。
2. 恢复连续会话。
3. 绑定当前预警上下文。
4. 恢复研判、话术和工单摘要快捷指令。
### 第三阶段:待确认功能
1. 政策解读数据源和接口方案。
2. 系统提示与通知的关系。
3. 预警处置交互是否恢复分步流程。
## 6. 验收清单
- 主项目登录、RBAC、数据范围、错误码和会话失效能力不回退。
- 风险概览显示未闭环口径。
- 预警队列、证据、通知和 Agent 均使用统一 `api-client`。
- 日报能直观看出模型生成或规则降级。
- Agent 能绑定当前预警并连续对话。
- 研判、话术和工单摘要三个场景可用。
- 证据关键字段可查询且移动端不溢出。
- 政策解读和系统提示若实现,必须有明确数据源。
- 所有按钮权限与后端权限码一致。
- 关键写操作保留幂等键和成功失败提示。
- 主项目统一前端专项测试通过。
## 7. 已确认决策
1. Agent 会话按“用户 + 预警”归属,通用问答和预警问答分开。
2. 政策解读本期只保留前端入口和说明,不接入具体内容。
3. 系统提示独立于通知记录,在账号信息旁提供按钮和弹窗列表。
4. 证据表使用“核心列 + 展开详情”。
5. 预警处置暂不恢复原分步交互,继续使用主项目统一操作弹窗。
6. 所有改造必须遵循主项目前端风格,不能影响其他业务前端。
## 8. 本轮前端实现状态
已完成:
- Agent 按通用和预警分别维护会话状态。
- Agent 在同一会话内复用 `session_id`。
- 打开预警后自动切换预警会话,并支持退出上下文。
- 增加研判、话术和工单摘要三个预警场景指令。
- 增加 Agent 能力边界和免责声明。
- 增加账号信息旁的系统提示按钮和弹窗通知列表。
- 增加政策解读预留按钮和未开放说明。
- 证据表改为核心列加展开详情。
- 日报增加结构化摘要、生成时间和模型来源展示。
待联调:
- 使用主项目统一前端完成桌面端、移动端和权限状态验收。
- 验证 Agent 连续会话与预警上下文在真实模型下的表现。
- 政策解读数据源接入属于后续独立事项。
## 9. 前端问题记录、解答与处理状态(2026-09-13)
### BUG-01 证据表展开按钮位于最右侧
问题:
- 当前只能点击表格最右侧“展开”按钮。
- 宽表需要横向滚动后才能看到按钮,操作不方便。
当前实现:
- `tableMarkup()` 在最右侧增加 `data-expand-row` 按钮。
- `bindExpandableRows()` 只监听该按钮。
结论与方案:
- 可以改为点击整行任意数据单元格展开或缩回。
- 建议保留操作列点击行为,其他数据单元格均切换详情。
- 需要增加键盘可访问性和 `aria-expanded` 状态。
- 只涉及前端,不修改接口。
### BUG-02 展开详情显示数据库原生字段
问题:
- 展开后字段名使用数据库列名。
- 业务人员无法直接理解字段含义。
当前实现:
- `detailMarkup()` 直接遍历 `Object.entries(item)`。
结论与方案:
- 需要为八类证据分别建立业务字段标签和格式化规则。
- 金额、比率、时间、布尔值和数组要使用统一格式。
- 未登记的新字段可以回退显示原名,但必须标记为技术字段。
- 只涉及前端字段映射。
### BUG-03 Agent 缺少手动输入或选择预警编号的入口
问题:
- 当前只有打开预警详情后才会自动进入该预警上下文。
- 直接进入智能助手时只能进行通用问答。
- 没有手动填写或选择预警编号的控件。
当前实现:
- `openAlert()` 成功后调用 `switchChatContext(alert.alert_no)`。
- Agent 请求会附带“当前预警编号:xxx”。
- 用户主动退出后回到通用会话。
结论与方案:
- 自动绑定可以保留。
- 建议在智能助手中增加预警编号输入框和“绑定”按钮。
- 绑定前可调用预警详情接口校验编号是否存在及是否有权限。
- 也可提供当前预警列表的搜索选择,但首版输入框最直接。
- 需要明确绑定失败、无权限和编号不存在时的提示。
- 只涉及前端;现有详情接口足够完成校验。
### BUG-04 报错信息持续展示
问题:
- 部分错误提示出现后不会自动消失。
- 影响表单继续操作。
当前实现:
- Toast 默认 3.6 秒后移除。
- 操作弹窗和邮件表单使用 `form-alert--visible`,只在下次打开或再次提交时才清除。
- 内容区 `renderError()` 会持续显示到重试或刷新。
结论与方案:
- 表单内错误应在以下时机清除:
- 用户修改输入。
- 用户关闭弹窗。
- 请求重新开始。
- 操作成功。
- 内容区错误应保留到重试成功,否则用户会丢失状态说明。
- 不建议所有错误统一自动消失,需区分“表单错误”和“页面加载错误”。
### BUG-05 弹窗打开时 Toast 被遮挡
问题:
- 预警告警操作成功或失败后,通知看不到。
- 原生 `dialog` 位于浏览器顶层,普通页面 Toast 的 `z-index` 无法超过它。
当前实现:
- `showToast()` 把 Toast 挂在 `document.body`。
- 操作结果同时通过 Toast 展示。
结论与方案:
- 弹窗内操作结果应优先使用弹窗内部状态区展示。
- 推荐流程:
- 失败:在弹窗内展示错误,弹窗保持打开。
- 成功:弹窗内短暂展示成功状态,再关闭并刷新。
- 关闭后的 Toast 只作为补充提示,不能作为唯一反馈。
- 不修改后端。
### BUG-06 证据时间筛选是否有效
问题:
- 所有证据类型都展示开始时间和结束时间。
- 用户无法判断时间筛选是否真的生效。
当前实现:
- 时间条件已传给后端。
- 后端只在以下证据类型应用时间:
- `transactions`
- `capital_flows`
- `login_records`
- `notifications`
- 以下类型当前不应用时间:
- `customers`
- `products`
- `holdings`
- `alerts`
结论与方案:
- 时间筛选不是摆设,但对部分证据类型无效。
- 前端应根据证据类型动态显示或禁用时间筛选。
- 在 `alerts` 类型下如果要按预警创建时间筛选,需要后端补充参数透传,属于后续后端事项。
- 当前阶段至少应隐藏无效输入,避免误导业务人员。
### 本轮处理结果
- BUG-01 已处理:证据表主行可直接点击或使用键盘展开、缩回。
- BUG-02 已处理:展开详情使用业务字段标签,未知字段明确标记为技术字段。
- BUG-03 已处理:智能助手增加预警编号输入和绑定入口,并保留打开预警详情后的自动绑定。
- BUG-04 已处理:表单错误在输入、关闭和成功提交时清理;页面加载错误保留到重试。
- BUG-05 已处理:成功操作自动关闭相关弹窗后在页面层展示 Toast;失败保留弹窗并显示错误。
- BUG-06 已处理:删除证据时间筛选框;行为关注度只在客户证据类型显示。
- BUG-07 已处理:证据快照改用业务字段标签,支持归档信息和合并证据嵌套展示,原始 JSON 改为折叠入口。
- BUG-08 已处理:证据上传成功自动关闭详情弹窗并显示结果 Toast;失败保留弹窗并定位错误。
- BUG-09 已处理:预警详情头部展示证据归档状态和归档文件名。
- BUG-10 已处理:表单错误统一 5 秒自动消失;页面级错误保留到重试。
## 10. 新增前端问题记录与解答(2026-09-13)
### BUG-07 预警详情中的证据快照显示数据库原生字段
当前实现:
- 预警详情通过 `detailSection('证据快照', detail.evidence_snapshot)` 显示。
- `detailSection()` 对对象直接执行 `JSON.stringify()`。
- 因此会看到 `product_id`、`ratio`、`device_id`、`merged_alerts` 等技术字段。
结论与方案:
- 需要把证据快照改成业务化展示。
- 建议按快照类型建立字段映射,例如:
- `product_id` -> 产品记录编号,同时优先展示产品名称。
- `ratio` -> 命中比例或赎回比例。
- `amount` -> 交易金额。
- `average_amount` -> 历史平均金额。
- `device_id` -> 登录设备。
- `merged_alerts` -> 多规则合并证据列表。
- 保留“查看原始 JSON”作为专家模式入口,不默认展示。
- 只涉及前端,不修改接口。
本次修复范围扩展:
- 客户画像、关联交易、关联产品、关联工单、资金流水、持仓证据、登录证据全部改为业务字段展示。
- 证据快照中的普通字段、归档信息、合并证据继续单独业务化渲染。
- 各区块默认不再显示原生 JSON。
- 原始 JSON 统一移动到“查看原始数据”折叠入口。
### BUG-08 上传证据结果位于详情底部,反馈不直观
当前实现:
- 证据上传表单位于预警详情最底部。
- 成功和失败提示仍靠近表单显示。
- 页面较长时,用户需要滚动到底部才能看到结果。
结论与方案:
- 成功时自动关闭预警详情弹窗,再在普通页面层显示 Toast,避免被原生 `dialog` 遮挡。
- 失败时保留详情弹窗,显示明确原因并滚动到错误位置。
- 成功后刷新预警列表即可看到最新归档状态。
- 只涉及前端交互和布局。
### BUG-09 预警详情缺少证据归档状态
当前实现:
- 列表预警对象已有 `evidence_archived`。
- 预警详情主体也包含该字段。
- 前端详情头部没有单独展示。
结论与方案:
- 在预警详情头部增加“证据归档”字段。
- 建议展示:
- 已归档
- 未归档
- 已归档时如果能从 `evidence_snapshot.evidence_archive` 取得文件名,可继续展示。
- 只涉及前端展示。
### BUG-10 错误信息仍持续展示
当前实现:
- 表单错误已在输入、关闭和成功提交时清除。
- 但没有统一的 5 秒自动消失机制。
- 页面加载错误和权限错误仍会持续展示到重试或刷新。
结论与方案:
- 表单级错误统一在 5 秒后自动消失。
- 新错误出现时取消旧错误计时器,避免旧计时器误清新错误。
- 成功提示也可以统一使用 5 秒自动消失。
- 页面级错误建议保留:
- 登录失效
- 无权限
- 页面数据加载失败
这些错误不能自动消失,否则用户会不知道页面为空的原因。
### BUG-11 重点预警的展示逻辑
当前实现:
- 数据来自风险概览接口的 `high_priority`。
- 查询条件为:
- `risk_level=高`
- `open_only=true`
- 最多返回 3 条
- 排序为先高等级、再按创建时间倒序。
- 点击“查看详情”打开对应预警弹窗。
是否为新前端功能:
- 是。
- 原项目单页前端重点展示统一指标和预警队列。
- 主项目统一风控前端新增了独立的“重点预警”侧栏,用于快速查看最多 3 条高风险未闭环预警。
结论:
- 展示逻辑符合当前后端口径,不需要修改。
- 如果后续希望调整数量、排序或展示字段,只需修改前端或新增概览参数。
+2
View File
@@ -44,6 +44,7 @@
| 21 | 主项目合并后后端必改清单 | 列出合并后必须处理的后端事项 |
| 22 | 风控模块需求说明书 | 统一业务需求、规则、边界和验收口径 |
| 23 | 风控模块接口文档 | 提供 REST、SSE、字段和联调约定 |
| 24 | 主项目风控前端改造TODO | 记录前端保留项、修改项和待讨论方案 |
## 推荐阅读顺序
@@ -58,3 +59,4 @@
9. 20:主项目方导入 Agent 工具白名单和意图配置。
10. 21:主项目代码合并后的后端整改与验收。
11. 22、23:分别作为需求交付和接口联调的统一入口。
12. 24:主项目风控前端改造的事项、决策项和实施顺序。