# Ant Design 风格组件总览改造计划

## 当前状态

### 技术栈
- **框架**: React 19 + TypeScript 6
- **文档**: dumi v2 (^2.4.28)
- **构建**: father v4 (组件库) + dumi build (文档站)
- **测试**: Vitest + @testing-library/react

### 构建状态
- `pnpm docs:build` ✅ 构建成功 (Webpack compiled successfully)
- `pnpm tsc --noEmit` ✅ 无类型错误 (仅 config 文件 rootDir 警告，不影响运行)
- `pnpm lint` ❌ 1 个 lint 错误: `Notification.tsx` 未使用的 `ReactElement` 导入
- `pnpm test` ⚠️ 超时 (部分测试可能挂起或循环)

### 文档站点现状

**`.dumirc.ts` 配置**:
```typescript
sidebar: {
  '/components': [{ title: '组件总览', children: [] }],
},
```
当前 sidebar 被硬编码覆盖，dumi 无法根据 `atomDirs` + frontmatter 自动生成层级导航。

**组件 frontmatter 格式** (已正确配置):
```markdown
---
nav: 组件
group:
  title: 通用    # 分类名
  order: 1       # 排序
title: Button 按钮
description: 用于触发操作的按钮组件。
---
```

**6 个分类 (order 已定义)**:
| 分类 | order | 组件数 |
|------|-------|--------|
| 通用 | 1 | 10 |
| 布局 | 2 | 8 |
| 导航 | 3 | 6 |
| 数据录入 | 4 | 19 |
| 数据展示 | 5 | 20 |
| 反馈 | 6 | 10 |

---

## 目标状态

### Ant Design 风格布局
1. **左侧边栏**: 层级导航，分类可展开，显示该分类下所有组件
2. **组件总览页**: 按分类展示卡片网格，每张卡片包含图标/预览 + 组件名 + 简介
3. **组件详情页**: 代码演示 + API 文档

---

## 全部组件清单

### 通用 Common (10)

| 组件 | 路由 | 说明 | Demo 演示内容 |
|------|------|------|--------------|
| Button 按钮 | `/components/common/button` | 触发操作的按钮组件 | 6 种变体(solid/outline/dashed/filled/text/link)、6 种颜色、5 种尺寸、3 种形状、图标、加载、全宽、危险、幽灵、禁用、链接 |
| FloatButton 悬浮按钮 | `/components/common/float-button` | 悬浮在页面边缘的操作按钮 | - |
| Icon 图标 | `/components/common/icon` | 语义化的矢量图形 | - |
| Typography 排版 | `/components/common/typography` | 标题、段落、文本组件 | - |
| Affix 固钉 | `/components/common/affix` | 将元素固定在可视范围 | - |
| Anchor 锚点 | `/components/common/anchor` | 页面内锚点导航 | - |
| App 包裹组件 | `/components/common/app` | 提供全局化配置的包裹组件 | - |
| BackTop 回到顶部 | `/components/common/back-top` | 返回页面顶部的快捷按钮 | - |
| ConfigProvider 全局配置 | `/components/common/config-provider` | 全局化配置 | - |
| Watermark 水印 | `/components/common/watermark` | 页面水印 | - |

### 布局 Layout (8)

| 组件 | 路由 | 说明 | Demo 演示内容 |
|------|------|------|--------------|
| Divider 分割线 | `/components/layout/divider` | 区隔内容的分割线 | 水平/垂直分割线、带文字 |
| Flex 弹性布局 | `/components/layout/flex` | 弹性布局容器 | - |
| Grid 栅格 | `/components/layout/grid` | 24 栅格系统 | - |
| Layout 布局 | `/components/layout/layout` | 页面级布局 | - |
| Masonry 瀑布流 | `/components/layout/masonry` | 瀑布流布局 | - |
| Space 间距 | `/components/layout/space` | 组件间距 | - |
| Splitter 分割面板 | `/components/layout/splitter` | 可拖拽的面板分割 | - |
| Stack 堆栈布局 | `/components/layout/stack` | 堆栈式布局 | - |

### 导航 Navigation (6)

| 组件 | 路由 | 说明 | Demo 演示内容 |
|------|------|------|--------------|
| Breadcrumb 面包屑 | `/components/nav/breadcrumb` | 页面路径导航 | - |
| Dropdown 下拉菜单 | `/components/nav/dropdown` | 下拉菜单 | - |
| Menu 导航菜单 | `/components/nav/menu` | 侧边/顶部导航菜单 | 基本使用、垂直菜单(含子菜单) |
| Pagination 分页 | `/components/nav/pagination` | 数据分页 | - |
| Steps 步骤条 | `/components/nav/steps` | 步骤指示器 | - |
| Tabs 标签页 | `/components/nav/tabs` | 选项卡切换 | - |

### 数据录入 Data Entry (19)

| 组件 | 路由 | 说明 | Demo 演示内容 |
|------|------|------|--------------|
| AutoComplete 自动完成 | `/components/data-entry/auto-complete` | 自动补全输入 | - |
| Cascader 级联选择 | `/components/data-entry/cascader` | 级联选择器 | - |
| Checkbox 多选框 | `/components/data-entry/choice` | 多选选择框 | - |
| Radio 单选框 | `/components/data-entry/choice` | 单选选择框 | - |
| Switch 开关 | `/components/data-entry/choice` | 开关切换 | - |
| DatePicker 日期选择器 | `/components/data-entry/date-picker` | 日期选择 | - |
| Form 表单 | `/components/data-entry/form` | 表单组件 | - |
| Input 输入框 | `/components/data-entry/input` | 文本输入框 | 基本使用、3 种尺寸、禁用、前缀 |
| InputNumber 数字输入框 | `/components/data-entry/input-number` | 数字输入 | - |
| Mention 提及 | `/components/data-entry/mention` | @提及 | - |
| RangePicker 范围选择器 | `/components/data-entry/range-picker` | 日期范围选择 | - |
| Rate 评分 | `/components/data-entry/rate` | 评分组件 | - |
| Select 选择器 | `/components/data-entry/select` | 下拉选择器 | - |
| Slider 滑动输入条 | `/components/data-entry/slider` | 滑动输入 | - |
| TextArea 文本域 | `/components/data-entry/textarea` | 多行文本输入 | - |
| TimePicker 时间选择器 | `/components/data-entry/time-picker` | 时间选择 | - |
| Transfer 穿梭框 | `/components/data-entry/transfer` | 双栏穿梭选择 | - |
| TreeSelect 树选择 | `/components/data-entry/tree-select` | 树形选择 | - |
| Upload 上传 | `/components/data-entry/upload` | 文件上传 | - |

### 数据展示 Data Display (20)

| 组件 | 路由 | 说明 | Demo 演示内容 |
|------|------|------|--------------|
| Avatar 头像 | `/components/data-display/avatar` | 用户头像 | 4 种尺寸、3 种类型(图标/文字/图片)、AvatarGroup |
| Badge 徽标 | `/components/data-display/badge` | 徽标数/小红点 | - |
| Calendar 日历 | `/components/data-display/calendar` | 日历 | - |
| Card 卡片 | `/components/data-display/card` | 内容容器 | - |
| Carousel 走马灯 | `/components/data-display/carousel` | 轮播 | - |
| Collapse 折叠面板 | `/components/data-display/collapse` | 可折叠内容 | - |
| Descriptions 描述列表 | `/components/data-display/descriptions` | 描述列表 | - |
| Empty 空状态 | `/components/data-display/empty` | 空状态占位 | - |
| Image 图片 | `/components/data-display/image` | 图片展示 | - |
| List 列表 | `/components/data-display/list` | 列表 | - |
| Popover 气泡卡片 | `/components/data-display/popover` | 气泡弹出 | - |
| QRCode 二维码 | `/components/data-display/qrcode` | 二维码生成 | - |
| Segmented 分段控制器 | `/components/data-display/segmented` | 分段选择 | - |
| Statistic 统计数值 | `/components/data-display/statistic` | 统计数值展示 | - |
| Table 表格 | `/components/data-display/table` | 数据表格 | - |
| Tag 标签 | `/components/data-display/tag` | 标签 | - |
| Timeline 时间轴 | `/components/data-display/timeline` | 时间轴 | - |
| Tooltip 文字提示 | `/components/data-display/tooltip` | 文字提示 | - |
| Tour 漫游式引导 | `/components/data-display/tour` | 分步引导 | - |
| Tree 树形控件 | `/components/data-display/tree` | 树形结构 | - |

### 反馈 Feedback (10)

| 组件 | 路由 | 说明 | Demo 演示内容 |
|------|------|------|--------------|
| Alert 警告提示 | `/components/feedback/alert` | 警告提示 | 4 种类型(success/info/warning/error)、可关闭 |
| Drawer 抽屉 | `/components/feedback/drawer` | 侧边抽屉 | - |
| Message 全局提示 | `/components/feedback/message` | 全局消息提示 | - |
| Modal 对话框 | `/components/feedback/modal` | 模态对话框 | - |
| Notification 通知提醒框 | `/components/feedback/notification` | 通知提醒 | - |
| Popconfirm 气泡确认框 | `/components/feedback/popconfirm` | 气泡确认 | - |
| Progress 进度条 | `/components/feedback/progress` | 进度展示 | - |
| Result 结果 | `/components/feedback/result` | 操作结果反馈 | - |
| Skeleton 骨架屏 | `/components/feedback/skeleton` | 加载占位 | - |
| Spin 加载中 | `/components/feedback/spin` | 加载状态 | - |

---

## 当前问题 & 修复项

### 1. Sidebar 未自动生成
**问题**: `.dumirc.ts` 中的 `sidebar` 配置覆盖了 dumi 的自动生成逻辑。
**修复**: 删除或调整 sidebar 配置，让 dumi 根据 frontmatter 的 `group.title` + `group.order` 自动生成层级导航。

### 2. Lint 错误
**文件**: `src/components/feedback/notification/Notification.tsx:2`
**问题**: `ReactElement` 导入未使用
**修复**: 移除未使用的 `ReactElement` 类型导入

### 3. 部分 Demo 可能报错
一些组件的 demo 代码可能引用了尚未导出的子组件或类型。需要逐一验证每个组件的 dumi demo 是否能正常渲染。

### 4. 测试超时
`pnpm test` 执行超时（>120s），可能存在问题：
- 某测试文件中有 await 未正确处理
- 测试使用了实际定时器（如 Notification 的 setTimeout）未 mock
- 组件渲染循环

---

## 改造步骤

### Phase 1: Sidebar 导航修复
1. 修改 `.dumirc.ts`，移除 `sidebar` 硬编码或让 dumi 自动生成
2. 可选：手动配置完整的 sidebar 结构（如需精确控制顺序）
3. 验证自动生成的 sidebar 包含 6 个分类，每个分类下列出其组件

### Phase 2: 组件总览页优化
1. 保留 `docs/components/index.md` 的卡片网格布局
2. 为每个组件卡片添加小预览图/示意图
3. 优化卡片样式以匹配 Ant Design 设计语言

### Phase 3: 错误修复
1. 修复 lint 错误（未使用的导入）
2. 验证每个组件 demo 的渲染
3. 修复测试超时问题

### Phase 4: 详情页 Demo 补全
1. 为缺少 demo 的组件添加代码演示（标记为 "-" 的）
2. 确保每个组件至少有一个基本用法 demo
3. 确保 `<API id="ComponentName" />` 正确引用类型定义

---

## 样式覆盖

`src/theme/dumi.css` 已有部分 Ant Design 风格覆盖（第 77-100 行左右），包含 sidebar 样式定义。但需要确保：

1. `.dumi-default-sidebar` 的宽度 (280px) 与 Ant Design 一致
2. 分类标题样式与 Ant Design 一致（小号、灰色、大写字母间距）
3. 组件链接样式（hover、active 状态）
4. 侧边栏滚动条样式