chengkai3
22 lines
8.7 KiB
JSON
22 lines
8.7 KiB
JSON
{
|
||
"id": "313321162778084067",
|
||
"createDate": "2026-04-24T00:59:36.202455",
|
||
"createUser": "openclaw",
|
||
"createUserName": "小龙虾",
|
||
"updateDate": "2026-04-24T09:14:38.969026",
|
||
"updateUser": "openclaw",
|
||
"updateUserName": "小龙虾",
|
||
"groupName": null,
|
||
"groupLabel": null,
|
||
"tagNames": null,
|
||
"tagLabels": null,
|
||
"title": "fquiz页面Ant Design组件改造：/admin/models",
|
||
"projectName": "fquiz",
|
||
"gitUrl": null,
|
||
"branch": "main",
|
||
"descr": "# 需求分析（313321162778084067）\n\n## 1. 目标\n- 将 `/admin/models` 页面完成 **Ant Design 组件层改造与一致性收敛**，统一视觉与交互规范。\n- 在不改变后端 API 协议与核心业务语义的前提下，提升页面可维护性、可用性和管理效率。\n- 保持模型管理主链路（查询、新建/编辑、状态流转、路由规则、健康检查、测试）行为一致。\n\n## 2. 现状（基于真实代码）\n- 主页面代码集中在：`web/src/app/admin/models/page.tsx`（超大单文件，承载列表、汇总卡片、模型弹窗、路由弹窗、冒烟测试弹窗、对话测试弹窗、全部 mutation 与提示逻辑）。\n- UI 组件使用：`@/components/ui-antd`（AntD 二次封装），但页面仍混用大量 Tailwind/自定义类，存在“AntD + 自定义样式并存”的状态。\n- 该页面被多个后台路由复用：\n - `web/src/app/admin/orchestration/page.tsx`\n - `web/src/app/admin/mcp-server/page.tsx`\n - `web/src/app/admin/agent/page.tsx`\n - `web/src/app/admin/api-tester/page.tsx`\n 均 `export { default } from \"@/app/admin/models/page\";`，说明改造会同时影响多个入口页面体验。\n- 可见 UI/交互问题（代码级证据）：\n 1) 消息区样式重复拼接：`pre` 上存在重复 class（如 `overflow-auto ...` 重复两套）——`page.tsx` 约 657、660、1375 行附近。\n 2) 表格 body 使用 `className=\"divide-y divide-y\"`（重复 token）——`page.tsx` 多处（模型表、路由表、测试记录表）。\n 3) 关键危险/敏感操作仍使用原生 `window.confirm/window.prompt`（删除、轮换密钥），交互不统一且可用性弱——`page.tsx` 约 772、822、923 行附近。\n 4) 列表空态处理不足：模型列表、路由列表无显式 Empty 引导（仅 map 渲染）；仅测试记录有“暂无测试记录”。\n 5) 多弹窗内表单虽可用，但错误反馈聚合在顶部字符串，不够字段级、就近化。\n\n## 3. 范围（In Scope）\n1. `/admin/models` 页面及其复用入口的 **前端组件层改造**（布局、表单、表格、弹窗、按钮、反馈、空态/加载态）。\n2. 将当前页面的主要展示/操作区域逐步收敛为 Ant Design 语义组件能力（如 Alert/Result/Empty/Spin/Modal/Popconfirm/Form/Table 等）。\n3. 交互一致性与可访问性增强（禁用态、确认态、错误提示位置、加载反馈、键盘可操作性）。\n4. 样式体系整理：减少重复 class 与无效 class，统一组件 token 风格。\n\n## 4. 非范围（Out of Scope）\n- 后端接口协议、字段语义、权限模型（`model.read/model.manage`）不调整。\n- 模型路由、健康检查、测试执行的业务规则不改。\n- 不新增全新业务模块（仅做页面组件改造与体验优化）。\n- 不在本需求中拆分/重构后端服务或数据库结构。\n\n## 5. UI/UX 专项评估（按 P0/P1/P2）\n\n### 执行摘要\n- 页面功能完整，但单页承载过重，导致视觉层级与反馈模式不统一。\n- 危险/敏感操作依赖原生浏览器对话框，缺乏品牌一致性与审计友好体验。\n- 列表/状态/错误反馈缺乏“结构化空态+就近错误”设计，增加学习成本。\n- 多路由复用同一页面，任何 UI 改动均是“高影响面”，需采用低风险渐进式改造。\n- 建议以“组件替换优先于业务变更”为主线，先统一交互基线，再做结构拆分。\n\n### P0（必须优先）\n1. **危险操作确认机制统一（删除/轮换密钥）**\n - 现状：`window.confirm/window.prompt`。\n - 影响：体验割裂、移动端/可访问性较差、缺乏一致视觉语义。\n - 改法：替换为 AntD `Popconfirm` + `Modal`（含明确文案、二次确认、loading 态、错误态）。\n - 建议位置：`web/src/app/admin/models/page.tsx` 操作列按钮区域。\n\n2. **错误与成功反馈统一组件化**\n - 现状：顶部 `pre` + 重复 class，信息层级弱。\n - 影响：可读性与可扫描性差，不利于快速定位问题。\n - 改法：统一为 `Alert`（error/success），保留可复制详情；必要时补充 `message`/`notification`。\n - 建议位置：页面顶部反馈区、对话测试结果区。\n\n3. **列表空态与加载态标准化**\n - 现状：模型列表、路由列表无明确 Empty。\n - 影响：用户难区分“无数据 / 过滤无结果 / 请求异常”。\n - 改法：为表格内容区域引入 `Empty`、`Spin`、错误重试入口。\n - 建议位置：模型表、路由表、测试记录表。\n\n### P1（应在本次一并推进）\n1. **表单体验升级为字段级反馈**\n - 现状：主要依赖提交后统一报错。\n - 影响：修复路径长，输入错误定位成本高。\n - 改法：结合 AntD Form 或现封装组件补齐必填校验、格式提示、就近错误文本。\n - 建议位置：模型弹窗、路由弹窗、测试弹窗。\n\n2. **表格可读性与可操作性增强**\n - 现状：操作按钮密集平铺，信息密度偏高。\n - 影响：误触概率高，主次不清。\n - 改法：主操作保留按钮，次级操作收敛到 Dropdown/Menu；状态字段统一 Tag/Badge。\n - 建议位置：模型列表、路由规则列表。\n\n3. **页面结构拆分（仅前端组件层）**\n - 现状：单文件过大，可维护性低。\n - 影响：后续改造与测试成本高。\n - 改法：拆为 `SummaryCards`、`ModelTable`、`RouteTable`、`ModelFormModal`、`RouteFormModal`、`TestModal`、`ChatTestModal`。\n - 建议位置：`web/src/app/admin/models/` 下新增组件目录。\n\n### P2（可后续迭代）\n1. 提升响应式：中小屏优化列展示与操作折叠。\n2. 提升可访问性：操作按钮 aria 标签、焦点顺序与对话框首焦点。\n3. 增强信息架构：汇总卡片增加趋势提示（仅 UI 呈现，不改后端字段）。\n\n## 6. 实现思路\n- Phase 1（低风险替换）：先替换反馈组件、确认弹窗、空态/加载态，确保功能不变。\n- Phase 2（结构收敛）：拆分大文件组件，沉淀可复用表格/表单片段。\n- Phase 3（体验增强）：优化操作密度、字段校验、可访问性细节。\n- 全程保持 API 调用路径与 mutation/query key 不变，避免引入业务回归。\n\n## 7. 影响点\n- 直接影响页面：`web/src/app/admin/models/page.tsx`。\n- 间接影响入口（同页面复用）：\n - `/admin/orchestration`\n - `/admin/mcp-server`\n - `/admin/agent`\n - `/admin/api-tester`\n- 可能涉及封装层：`web/src/components/ui-antd.tsx`（若需补齐 Popconfirm/Empty/Tag 等封装出口）。\n\n## 8. 风险 / 疑问\n1. 复用页面是否允许“按路由场景差异化展示文案/功能”尚未明确（当前是完全复用）。\n2. 如果仅改 `/admin/models` 文案，可能导致其它复用入口语义不匹配。\n3. 表单校验策略（即时校验 vs 提交校验）需产品确认以避免体验突变。\n4. 操作聚合为下拉菜单后，是否影响管理员高频操作效率需评估。\n\n## 9. UI Quick Wins（可快速落地，建议至少先做）\n1. 将删除/轮换密钥从 `window.confirm/prompt` 切到 AntD `Popconfirm/Modal`，统一危险操作风格。\n2. 将顶部 `pre` 错误/成功提示替换为 `Alert`，并清理重复 class。\n3. 为模型列表和路由列表补齐 Empty 态（含“调整筛选/清空筛选”提示按钮）。\n\n## 10. 建议验收标准\n1. 功能一致性：模型 CRUD、状态流转、路由规则维护、健康检查、冒烟测试、对话测试均可正常执行。\n2. 交互一致性：页面不再出现浏览器原生 confirm/prompt；关键操作均有统一确认与加载反馈。\n3. 反馈可读性：错误/成功信息使用统一组件展示，且可快速定位问题。\n4. 空态完整性：模型列表、路由列表、测试记录在无数据时均有明确空态。\n5. 样式质量：删除明显重复/无效 class，页面主视觉与 Ant Design token 风格保持一致。\n6. 复用兼容性：`/admin/models`、`/admin/orchestration`、`/admin/mcp-server`、`/admin/agent`、`/admin/api-tester` 均可正常访问且关键链路可用。",
|
||
"resultMsg": "批量从待评审改为待处理（程凯指令）",
|
||
"progressPercent": 0,
|
||
"status": "OPEN",
|
||
"priority": "MEDIUM"
|
||
} |