# 主项目风控前端改造 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 条高风险未闭环预警。 结论： - 展示逻辑符合当前后端口径，不需要修改。 - 如果后续希望调整数量、排序或展示字段，只需修改前端或新增概览参数。