chengkai3
1 line
10 KiB
JSON
1 line
10 KiB
JSON
[{"requirementId": "313321162778084135", "descr": "# 需求分析（ID: 313321162778084135）\n\n## 1) 目标\n对 `/admin/mindmap`（含列表页与编辑页）进行 **Ant Design 组件层改造与统一**，在不改变后端接口协议与业务语义的前提下：\n- 统一页面视觉层级、间距、反馈与交互语义；\n- 提升表单/表格/弹窗/加载态/空态的一致性与可用性；\n- 保持现有功能链路（查询、新建、编辑、删除、保存、导出、AI 生成）不回归。\n\n---\n\n## 2) 现状（基于真实代码）\n\n### 2.1 页面与前端实现\n- 列表页：`web/src/app/admin/mindmap/page.tsx`\n - 已使用部分 Ant Design：`Form/Input/Table/Modal/Popconfirm/Tag/Tooltip/Button`。\n - 仍混用较多 Tailwind 容器样式（`section + rounded-xl + border...`），组件层级与 admin 其他页面风格并不完全一致。\n - 错误反馈为自定义红色 `section` 文案块，不是标准 `Alert/Result` 语义。\n - 表格未设置移动端横向滚动参数，窄屏下列宽存在拥挤风险。\n- 编辑页：`web/src/app/admin/mindmap/_components/mindmap-editor.tsx`\n - 使用 `Card(Row/Col/Input/Tree/Modal/Button)`；基础结构可用。\n - JSON 编辑区为 `Input.TextArea`，缺少更明确的校验反馈层级（当前以 `panelError + message` 为主）。\n - AI 流式生成已实现（SSE 读取 + `[MINDMAP]` 解析），但交互上“进行中状态、可中断性、异常提示粒度”可进一步产品化。\n- 路由封装：\n - `web/src/app/admin/mindmap/page.tsx`\n - `web/src/app/admin/mindmap/edit/page.tsx`\n - `web/src/app/admin/mindmap/edit/[id]/page.tsx`\n\n### 2.2 后端接口与约束（无需协议变更）\n- 路由：`api/app/api/v1/mind_map.py`\n - `POST /mindmap/search`\n - `GET /mindmap/get/{id}`\n - `POST /mindmap/create`\n - `PUT /mindmap/update-basic-info`\n - `PUT /mindmap/update-data`\n - `DELETE /mindmap/delete/{id}`\n - `GET /mindmap/generate/stream`\n- 服务：`api/app/services/mind_map_service.py`\n - 已具备 map_data 归一化、权限校验（按创建人）、AI 结果结构规整。\n- DTO：`api/app/schemas/mind_map.py`\n - 字段边界清晰，支持本次“仅前端组件改造”目标。\n\n---\n\n## 3) UI/UX 专项评估摘要（按 ui-ux-pro-max 要求）\n1. **反馈语义可统一为 Ant Design 体系**：错误/空态/加载态目前分散在自定义块与 message，建议标准化为 `Alert + Empty + Skeleton/Spin`，降低理解成本。 \n2. **表格与操作区在窄屏可用性一般**：列表操作为多个 link 按钮，点击热区偏小，且表格未声明 `scroll.x`，移动端体验有风险。 \n3. **表单反馈链路基本完整但可增强**：已有 `confirmLoading` 与 `message`，建议补强字段级校验提示、首错聚焦、禁用态一致性。 \n4. **编辑页信息密度较高**：左侧 JSON + 右侧树预览是正确方向，但可用更清晰的信息分区与状态提示降低认知负担。 \n5. **AI 生成流程可读性需加强**：当前技术上可用，但用户对“正在生成/已解析/失败原因”的阶段感知可提升。\n\n---\n\n## 4) 范围（In Scope）\n1. `/admin/mindmap` 列表页的 Ant Design 组件化收敛：\n - 页面头部/筛选区/数据区/反馈区统一为 AntD 语义组件组合；\n - 表格、按钮、弹窗、空态、加载态、错误态统一交互规范。\n2. `/admin/mindmap/edit` 与 `/admin/mindmap/edit/[id]` 对应编辑器页组件层优化：\n - 信息分区、状态反馈、AI 生成弹窗交互体验优化；\n - 保持现有 JSON 编辑与树预览能力。\n3. 与现有权限逻辑对齐：\n - `question_bank.read` / `question_bank.manage` 的显示与可编辑态一致性。\n\n---\n\n## 5) 非范围（Out of Scope）\n1. 不修改后端 API 协议、鉴权模型、数据库结构（`mind_map` 表）。\n2. 不改变核心业务语义（数据归属、保存策略、AI 生成业务入口）。\n3. 不引入与本需求无关的大规模重构（如全站主题体系重写、跨模块菜单重排）。\n\n---\n\n## 6) 实现思路（建议分步）\n\n### Step A：列表页组件语义统一（P0）\n- 将当前自定义容器块收敛为一致的 AntD 容器模式（如 `Card + Space/Flex + Typography`）。\n- 错误反馈改为 `Alert`（可关闭/可重试扩展），空列表时配置 `Table.locale.emptyText=<Empty .../>`。\n- 表格增加 `scroll={{ x: ... }}` 与列宽策略，保障小屏可读性。\n- 操作区保留功能不变，但按钮层级与危险操作文案统一（删除二次确认语义强化）。\n\n### Step B：编辑页交互分层优化（P0/P1）\n- 维持双栏布局，但增强“当前状态”可视化：\n - 加载中：`Card loading` + 必要 Skeleton 文案；\n - 校验失败：字段附近提示 + 顶部 `Alert`；\n - 保存成功/失败：`message` 与页面局部反馈并存。\n- 对 JSON 结构异常提供更可定位提示（例如说明错误来源：格式非法/结构不支持）。\n\n### Step C：AI 生成弹窗体验优化（P1）\n- 将“生成中/解析中/完成/失败”拆成明确阶段文案。\n- 生成期间关键按钮禁用策略更清晰，避免误操作。\n- 流式输出区支持更好的可读性（分段、滚动定位、错误信息高亮）。\n\n### Step D：一致性收尾（P2）\n- 统一间距、字号、状态色，减少页面内 Tailwind 局部样式分叉。\n- 文案统一（加载、空态、权限不足、失败提示）并与 admin 其他页面保持同风格。\n\n---\n\n## 7) P0 / P1 / P2 改造建议（含现状、影响、改法、建议位置）\n\n### P0-1：反馈语义标准化（错误/空态/加载）\n- 现状：错误主要用自定义红色块；空态依赖表格默认；加载提示分散。 \n- 影响：状态感知不一致，用户难以快速判断“可恢复动作”。 \n- 改法：统一 `Alert + Empty + Skeleton/Spin + message` 组合，并在关键区域固定展示。 \n- 建议位置：\n - `web/src/app/admin/mindmap/page.tsx`（`panelError`、Table 空态、首屏加载）\n - `web/src/app/admin/mindmap/_components/mindmap-editor.tsx`（`panelError`、加载与校验反馈）\n\n### P0-2：列表表格移动端可用性\n- 现状：表格列较多，未配置横向滚动，操作列在窄屏可点击性下降。 \n- 影响：移动端浏览与操作效率低，误触概率上升。 \n- 改法：补充 `scroll.x`、收敛列宽、必要时将次要操作收纳为下拉菜单。 \n- 建议位置：`web/src/app/admin/mindmap/page.tsx`（Table columns + pagination + operation render）\n\n### P0-3：表单提交流程防重复与禁用态一致\n- 现状：已有 `saving`/`confirmLoading`，但页面级操作与弹窗内操作禁用态一致性可加强。 \n- 影响：并发点击风险与状态混淆仍存在。 \n- 改法：细分 action loading（create/edit/save/ai），并统一按钮禁用策略。 \n- 建议位置：\n - `web/src/app/admin/mindmap/page.tsx`\n - `web/src/app/admin/mindmap/_components/mindmap-editor.tsx`\n\n### P1-1：编辑页信息层级优化\n- 现状：JSON 输入与预览并列，但“主操作路径（编辑→校验→保存）”引导较弱。 \n- 影响：新用户理解成本偏高。 \n- 改法：增强区块标题、副标题与步骤提示；对错误给出可执行下一步。 \n- 建议位置：`web/src/app/admin/mindmap/_components/mindmap-editor.tsx`\n\n### P1-2：AI 生成流程可读性增强\n- 现状：可生成，但流式反馈偏技术化。 \n- 影响：用户不易判断当前阶段与失败原因。 \n- 改法：阶段化提示（生成中/解析中/应用结果），失败时给出重试建议。 \n- 建议位置：`web/src/app/admin/mindmap/_components/mindmap-editor.tsx`（`startAiGenerate` 与 Modal 展示区）\n\n### P2-1：样式与文案一致性治理\n- 现状：AntD 与 Tailwind 混搭，可维护性受限。 \n- 影响：后续页面迭代容易继续分叉。 \n- 改法：沉淀 mindmap 页面的“统一容器与反馈模式”，减少自定义样式块。 \n- 建议位置：\n - `web/src/app/admin/mindmap/page.tsx`\n - `web/src/app/admin/mindmap/_components/mindmap-editor.tsx`\n\n---\n\n## 8) UI Quick Wins（可快速落地，至少 3 条）\n1. **列表 Table 增加 `scroll.x` + `locale.emptyText`**，当天可交付，立竿见影提升窄屏与空态体验。 \n2. **`panelError` 统一替换为 `Alert` 组件**，保留 message 但增强上下文提示与视觉一致性。 \n3. **操作列收敛为“主按钮 + 更多操作”**（或至少增大点击热区），降低误触。 \n4. **AI Modal 增加阶段文案与失败重试按钮**，提升可理解性。 \n5. **编辑页保存按钮在非法 JSON 时前置禁用/提示**，减少无效提交。\n\n---\n\n## 9) 影响点\n\n### 前端\n- 主要改动文件：\n - `web/src/app/admin/mindmap/page.tsx`\n - `web/src/app/admin/mindmap/_components/mindmap-editor.tsx`\n- 可选新增：`web/src/app/admin/mindmap/_components/*`（若需要抽离工具栏/状态提示子组件）。\n\n### 后端\n- **无接口协议变更**；沿用现有 `/api/v1/mindmap/*`。\n\n### 权限与安全\n- 继续复用：\n - 读权限：`question_bank.read` 或 `question_bank.manage`\n - 管理权限：`question_bank.manage`\n\n---\n\n## 10) 风险 / 疑问\n1. **组件选型边界**：是“纯 AntD 原生组件”优先，还是允许继续使用 `ui-antd` 包装层混用？需明确。 \n2. **移动端目标级别**：本次是否要求完整移动端优化（操作重排）还是仅保证可用不破版。 \n3. **AI 流程期望**：是否需要“取消生成”能力（当前未设计后端中断语义）。 \n4. **JSON 编辑体验上限**：是否允许引入更专业编辑器（如 Monaco）；若不允许则仅做 TextArea 级优化。\n\n---\n\n## 11) 建议验收标准\n1. **功能回归**：查询、新建、编辑信息、删除、保存导图数据、导出 JSON/Markdown、AI 生成全链路可用。 \n2. **协议稳定**：前后端接口入参与出参不变，后端无需新增接口。 \n3. **视觉一致性**：列表页与编辑页反馈组件、间距、按钮语义与 admin 其他页保持一致。 \n4. **状态可感知**：加载、空态、错误、成功均有明确可见反馈，不出现“无响应”状态。 \n5. **可用性**：在常见窄屏（如 375px）下无关键内容遮挡或无法操作；表格可滚动/可访问。 \n6. **权限正确**：无管理权限用户不可执行写操作，读权限用户可查看数据。"}] |