Admin/fquiz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a8307bfd2de3b7fb06e8dd4fc8153e6e87fa844a
fquiz/tmp/requirement-313321162778084135-analysis.md
T
chengkai3 3fd15fbd21 前端框架修改
2026-04-24 15:50:52 +08:00

10 KiB
Raw Blame History

需求分析（ID: 313321162778084135）

1) 目标

对 /admin/mindmap（含列表页与编辑页）进行 Ant Design 组件层改造与统一，在不改变后端接口协议与业务语义的前提下：

  • 统一页面视觉层级、间距、反馈与交互语义；
  • 提升表单/表格/弹窗/加载态/空态的一致性与可用性；
  • 保持现有功能链路（查询、新建、编辑、删除、保存、导出、AI 生成）不回归。

2) 现状（基于真实代码）

2.1 页面与前端实现

  • 列表页：web/src/app/admin/mindmap/page.tsx
    • 已使用部分 Ant Design：Form/Input/Table/Modal/Popconfirm/Tag/Tooltip/Button。
    • 仍混用较多 Tailwind 容器样式（section + rounded-xl + border...），组件层级与 admin 其他页面风格并不完全一致。
    • 错误反馈为自定义红色 section 文案块，不是标准 Alert/Result 语义。
    • 表格未设置移动端横向滚动参数，窄屏下列宽存在拥挤风险。
  • 编辑页：web/src/app/admin/mindmap/_components/mindmap-editor.tsx
    • 使用 Card(Row/Col/Input/Tree/Modal/Button)；基础结构可用。
    • JSON 编辑区为 Input.TextArea，缺少更明确的校验反馈层级（当前以 panelError + message 为主）。
    • AI 流式生成已实现（SSE 读取 + [MINDMAP] 解析），但交互上“进行中状态、可中断性、异常提示粒度”可进一步产品化。
  • 路由封装：
    • web/src/app/admin/mindmap/page.tsx
    • web/src/app/admin/mindmap/edit/page.tsx
    • web/src/app/admin/mindmap/edit/[id]/page.tsx

2.2 后端接口与约束（无需协议变更）

  • 路由：api/app/api/v1/mind_map.py
    • POST /mindmap/search
    • GET /mindmap/get/{id}
    • POST /mindmap/create
    • PUT /mindmap/update-basic-info
    • PUT /mindmap/update-data
    • DELETE /mindmap/delete/{id}
    • GET /mindmap/generate/stream
  • 服务：api/app/services/mind_map_service.py
    • 已具备 map_data 归一化、权限校验（按创建人）、AI 结果结构规整。
  • DTO：api/app/schemas/mind_map.py
    • 字段边界清晰，支持本次“仅前端组件改造”目标。

3) UI/UX 专项评估摘要（按 ui-ux-pro-max 要求）

  1. 反馈语义可统一为 Ant Design 体系：错误/空态/加载态目前分散在自定义块与 message，建议标准化为 Alert + Empty + Skeleton/Spin，降低理解成本。
  2. 表格与操作区在窄屏可用性一般：列表操作为多个 link 按钮，点击热区偏小，且表格未声明 scroll.x，移动端体验有风险。
  3. 表单反馈链路基本完整但可增强：已有 confirmLoading 与 message，建议补强字段级校验提示、首错聚焦、禁用态一致性。
  4. 编辑页信息密度较高：左侧 JSON + 右侧树预览是正确方向，但可用更清晰的信息分区与状态提示降低认知负担。
  5. AI 生成流程可读性需加强：当前技术上可用，但用户对“正在生成/已解析/失败原因”的阶段感知可提升。

4) 范围（In Scope）

  1. /admin/mindmap 列表页的 Ant Design 组件化收敛：
    • 页面头部/筛选区/数据区/反馈区统一为 AntD 语义组件组合；
    • 表格、按钮、弹窗、空态、加载态、错误态统一交互规范。
  2. /admin/mindmap/edit 与 /admin/mindmap/edit/[id] 对应编辑器页组件层优化：
    • 信息分区、状态反馈、AI 生成弹窗交互体验优化；
    • 保持现有 JSON 编辑与树预览能力。
  3. 与现有权限逻辑对齐：
    • question_bank.read / question_bank.manage 的显示与可编辑态一致性。

5) 非范围（Out of Scope）

  1. 不修改后端 API 协议、鉴权模型、数据库结构（mind_map 表）。
  2. 不改变核心业务语义（数据归属、保存策略、AI 生成业务入口）。
  3. 不引入与本需求无关的大规模重构（如全站主题体系重写、跨模块菜单重排）。

6) 实现思路（建议分步）

Step A：列表页组件语义统一（P0）

  • 将当前自定义容器块收敛为一致的 AntD 容器模式（如 Card + Space/Flex + Typography）。
  • 错误反馈改为 Alert（可关闭/可重试扩展），空列表时配置 Table.locale.emptyText=<Empty .../>。
  • 表格增加 scroll={{ x: ... }} 与列宽策略，保障小屏可读性。
  • 操作区保留功能不变，但按钮层级与危险操作文案统一（删除二次确认语义强化）。

Step B：编辑页交互分层优化（P0/P1）

  • 维持双栏布局，但增强“当前状态”可视化：
    • 加载中：Card loading + 必要 Skeleton 文案；
    • 校验失败：字段附近提示 + 顶部 Alert；
    • 保存成功/失败：message 与页面局部反馈并存。
  • 对 JSON 结构异常提供更可定位提示（例如说明错误来源：格式非法/结构不支持）。

Step C：AI 生成弹窗体验优化（P1）

  • 将“生成中/解析中/完成/失败”拆成明确阶段文案。
  • 生成期间关键按钮禁用策略更清晰，避免误操作。
  • 流式输出区支持更好的可读性（分段、滚动定位、错误信息高亮）。

Step D：一致性收尾（P2）

  • 统一间距、字号、状态色，减少页面内 Tailwind 局部样式分叉。
  • 文案统一（加载、空态、权限不足、失败提示）并与 admin 其他页面保持同风格。

7) P0 / P1 / P2 改造建议（含现状、影响、改法、建议位置）

P0-1：反馈语义标准化（错误/空态/加载）

  • 现状：错误主要用自定义红色块；空态依赖表格默认；加载提示分散。
  • 影响：状态感知不一致，用户难以快速判断“可恢复动作”。
  • 改法：统一 Alert + Empty + Skeleton/Spin + message 组合，并在关键区域固定展示。
  • 建议位置：
    • web/src/app/admin/mindmap/page.tsx（panelError、Table 空态、首屏加载）
    • web/src/app/admin/mindmap/_components/mindmap-editor.tsx（panelError、加载与校验反馈）

P0-2：列表表格移动端可用性

  • 现状：表格列较多，未配置横向滚动，操作列在窄屏可点击性下降。
  • 影响：移动端浏览与操作效率低，误触概率上升。
  • 改法：补充 scroll.x、收敛列宽、必要时将次要操作收纳为下拉菜单。
  • 建议位置：web/src/app/admin/mindmap/page.tsx（Table columns + pagination + operation render）

P0-3：表单提交流程防重复与禁用态一致

  • 现状：已有 saving/confirmLoading，但页面级操作与弹窗内操作禁用态一致性可加强。
  • 影响：并发点击风险与状态混淆仍存在。
  • 改法：细分 action loading（create/edit/save/ai），并统一按钮禁用策略。
  • 建议位置：
    • web/src/app/admin/mindmap/page.tsx
    • web/src/app/admin/mindmap/_components/mindmap-editor.tsx

P1-1：编辑页信息层级优化

  • 现状：JSON 输入与预览并列，但“主操作路径（编辑→校验→保存）”引导较弱。
  • 影响：新用户理解成本偏高。
  • 改法：增强区块标题、副标题与步骤提示；对错误给出可执行下一步。
  • 建议位置：web/src/app/admin/mindmap/_components/mindmap-editor.tsx

P1-2：AI 生成流程可读性增强

  • 现状：可生成，但流式反馈偏技术化。
  • 影响：用户不易判断当前阶段与失败原因。
  • 改法：阶段化提示（生成中/解析中/应用结果），失败时给出重试建议。
  • 建议位置：web/src/app/admin/mindmap/_components/mindmap-editor.tsx（startAiGenerate 与 Modal 展示区）

P2-1：样式与文案一致性治理

  • 现状：AntD 与 Tailwind 混搭，可维护性受限。
  • 影响：后续页面迭代容易继续分叉。
  • 改法：沉淀 mindmap 页面的“统一容器与反馈模式”，减少自定义样式块。
  • 建议位置：
    • web/src/app/admin/mindmap/page.tsx
    • web/src/app/admin/mindmap/_components/mindmap-editor.tsx

8) UI Quick Wins（可快速落地，至少 3 条）

  1. 列表 Table 增加 scroll.x + locale.emptyText，当天可交付，立竿见影提升窄屏与空态体验。
  2. panelError 统一替换为 Alert 组件，保留 message 但增强上下文提示与视觉一致性。
  3. 操作列收敛为“主按钮 + 更多操作”（或至少增大点击热区），降低误触。
  4. AI Modal 增加阶段文案与失败重试按钮，提升可理解性。
  5. 编辑页保存按钮在非法 JSON 时前置禁用/提示，减少无效提交。

9) 影响点

前端

  • 主要改动文件：
    • web/src/app/admin/mindmap/page.tsx
    • web/src/app/admin/mindmap/_components/mindmap-editor.tsx
  • 可选新增：web/src/app/admin/mindmap/_components/*（若需要抽离工具栏/状态提示子组件）。

后端

  • 无接口协议变更；沿用现有 /api/v1/mindmap/*。

权限与安全

  • 继续复用：
    • 读权限：question_bank.read 或 question_bank.manage
    • 管理权限：question_bank.manage

10) 风险 / 疑问

  1. 组件选型边界：是“纯 AntD 原生组件”优先，还是允许继续使用 ui-antd 包装层混用？需明确。
  2. 移动端目标级别：本次是否要求完整移动端优化（操作重排）还是仅保证可用不破版。
  3. AI 流程期望：是否需要“取消生成”能力（当前未设计后端中断语义）。
  4. JSON 编辑体验上限：是否允许引入更专业编辑器（如 Monaco）；若不允许则仅做 TextArea 级优化。

11) 建议验收标准

  1. 功能回归：查询、新建、编辑信息、删除、保存导图数据、导出 JSON/Markdown、AI 生成全链路可用。
  2. 协议稳定：前后端接口入参与出参不变，后端无需新增接口。
  3. 视觉一致性：列表页与编辑页反馈组件、间距、按钮语义与 admin 其他页保持一致。
  4. 状态可感知：加载、空态、错误、成功均有明确可见反馈，不出现“无响应”状态。
  5. 可用性：在常见窄屏（如 375px）下无关键内容遮挡或无法操作；表格可滚动/可访问。
  6. 权限正确：无管理权限用户不可执行写操作，读权限用户可查看数据。
Reference in New Issue View Git Blame Copy Permalink