group_fqcd_jr/docs/风控业务演示文档/24-主项目风控前端改造TODO.md

主项目风控前端改造 TODO

文档信息

项目	内容
文档版本	v1.0
编制日期	2026-09-14
对比对象	原项目单页风控工作台与主项目 /portal/employee-risk/dashboard/
改造原则	保留主项目增强能力，补齐原项目缺失能力，破坏性交互调整先讨论

1. 改造边界

1.1 必须保留

以下能力属于主项目统一前端增强，不得因对齐原项目而回退：

• 统一登录、JWT、RBAC、数据范围和服务端权限校验。
• 统一门户、员工登录页和角色分流。
• 统一 api-client.js、错误码、trace ID、重试和 401 会话失效处理。
• 风险概览“未闭环预警”正确口径。
• 预警队列按风险等级排序，每页 10 条。
• 预警筛选、证据筛选和游标分页。
• 通知记录展示发送状态和失败原因。
• 手动扫描 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。
• Worker 会读取同一会话最近 10 轮消息并传给风险 Agent。
• 通用风险问答与预警上下文分别维护。
• 刷新页面后仍会创建新会话，当前不承诺跨刷新恢复。

剩余讨论：

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 已使用同一会话最近 10 轮历史。
• 打开预警后自动切换预警会话，并支持退出上下文。
• 增加研判、话术和工单摘要三个预警场景指令。
• 增加 Agent 能力边界和免责声明。
• 增加账号信息旁的系统提示按钮和弹窗通知列表。
• 增加政策解读预留按钮和未开放说明。
• 证据表改为核心列加展开详情。
• 日报增加结构化摘要、生成时间和模型来源展示。

待联调：

• 使用主项目统一前端完成桌面端、移动端和权限状态验收。
• 验证 Agent 连续会话与预警上下文在真实模型下的表现。
• 评估是否将 session_id 持久化，以支持刷新页面后的会话恢复。
• 政策解读数据源接入属于后续独立事项。

9. 前端问题记录、解答与处理状态（2026-09-14）

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 秒自动消失；页面级错误保留到重试。
• 站内提醒入口已优化：改为带铃铛图标和数量的明确按钮，弹窗只展示站内提醒，支持直接打开预警和跳转通知记录。
• 风控列表分页已增加总条数和总页数：接口补齐 meta.total、meta.page_size，前端显示“第 x / y 页，共 n 条”。

10. 新增前端问题记录与解答（2026-09-14）

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 条高风险未闭环预警。

结论：

• 展示逻辑符合当前后端口径，不需要修改。
• 如果后续希望调整数量、排序或展示字段，只需修改前端或新增概览参数。