fquiz/tmp/requirement-313321162778084135-analysis.md

# 需求分析（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. **权限正确**：无管理权限用户不可执行写操作，读权限用户可查看数据。