# 故事 011.007：使用 mini-charts 包重构数据统计图表

## 状态
Ready for Review

## 故事
**作为**企业用户，
**我希望**使用专业的图表组件展示数据统计，
**以便**获得更好的数据可视化体验和交互功能。

## 验收标准

1. [x] 数据统计页使用 mini-charts 包的图表组件替换纯CSS实现
2. [x] 残疾类型分布使用 ColumnChart 组件显示
3. [x] 性别分布使用 ColumnChart 组件显示
4. [x] 年龄分布使用 PieChart 组件显示
5. [x] 户籍省份分布使用 BaseChart（type="bar"横向柱状图）组件显示
6. [x] 在职状态统计使用 PieChart（环形图）组件显示
7. [x] 薪资分布使用 BaseChart（type="bar"横向柱状图）组件显示
8. [x] 图表支持 tooltip 交互，显示详细数据
9. [x] 保持现有的性能优化（懒加载、数据缓存）
10. [x] 通过类型检查和测试验证

## 任务 / 子任务

- [x] 任务1：分析 mini-charts 包的可用组件和API（AC：全部）
  - [x] 阅读 `mini-ui-packages/mini-charts` 包的文档和示例
  - [x] 了解 ColumnChart、PieChart、LineChart 等组件的 Props 接口
  - [x] 了解图表配置选项（颜色、字体、动画等）
  - [x] 确认组件支持的数据格式
  - [x] 创建组件使用示例和测试

- [x] 任务2：重构残疾类型分布图表（AC：2）
  - [x] 导入 ColumnChart 组件
  - [x] 转换现有数据格式为 mini-charts 支持的格式
  - [x] 配置图表选项（标题、颜色、轴标签）
  - [x] 启用 tooltip 交互
  - [x] 测试图表渲染和交互功能
  - [x] 删除原有的纯CSS实现代码

- [x] 任务3：重构性别分布图表（AC：3）
  - [x] 导入 ColumnChart 组件
  - [x] 转换现有数据格式
  - [x] 配置图表选项（双色柱状图）
  - [x] 启用 tooltip 交互
  - [x] 测试图表渲染和交互功能
  - [x] 删除原有的纯CSS实现代码

- [x] 任务4：重构年龄分布图表（AC：4）
  - [x] 导入 PieChart 组件
  - [x] 转换现有数据格式为饼图格式
  - [x] 配置图表选项（颜色、图例）
  - [x] 启用 tooltip 交互
  - [x] 测试图表渲染和交互功能
  - [x] 删除原有的纯CSS实现代码

- [x] 任务5：重构户籍省份分布图表（AC：5）
  - [x] 导入 BaseChart 组件（横向柱状图，type="bar"）
  - [x] 转换现有数据格式
  - [x] 配置图表选项（横向、颜色）
  - [x] 启用 tooltip 交互
  - [x] 测试图表渲染和交互功能
  - [x] 删除原有的纯CSS实现代码

- [x] 任务6：重构在职状态统计图表（AC：6）
  - [x] 导入 PieChart 组件（环形图）
  - [x] 转换现有数据格式
  - [x] 配置图表选项（环形图样式）
  - [x] 启用 tooltip 交互
  - [x] 测试图表渲染和交互功能
  - [x] 删除原有的纯CSS实现代码

- [x] 任务7：重构薪资分布图表（AC：7）
  - [x] 导入 BaseChart 组件（横向柱状图，type="bar"）
  - [x] 转换现有数据格式
  - [x] 配置图表选项（横向、颜色）
  - [x] 启用 tooltip 交互
  - [x] 测试图表渲染和交互功能
  - [x] 删除原有的纯CSS实现代码

- [x] 任务8：验证性能优化和用户体验（AC：8-10）
  - [x] 验证懒加载机制仍然有效（分阶段加载图表）
  - [x] 验证数据缓存机制正常工作
  - [x] 测试图表交互功能（tooltip 显示）
  - [x] 测试移动端显示效果
  - [x] 确保页面加载速度符合要求
  - [x] 运行类型检查验证（pnpm typecheck）

- [x] 任务9：编写测试和文档（AC：10）
  - [x] 编写图表组件集成测试
  - [x] 测试数据转换逻辑
  - [x] 测试图表渲染和交互
  - [x] 更新故事文档，记录实施细节
  - [x] 更新开发笔记，添加 mini-charts 使用说明

## 开发笔记

### 依赖关系
**依赖故事**：
- 011.005（数据统计功能实现）：提供现有的数据统计页面和数据API集成
- 史诗016（mini-charts 包）：提供图表组件库，已完成 016.001-016.009 故事

### mini-charts 包使用指南

**安装依赖**：
```bash
# mini-charts 包已经在 workspace 中，无需额外安装
# 确保包已正确构建
cd mini-ui-packages/mini-charts
pnpm build
```

**导入组件**：
```typescript
// 在 Statistics.tsx 中导入图表组件
import { ColumnChart, PieChart } from '@d8d/mini-charts'
import type { ColumnChartProps, PieChartProps } from '@d8d/mini-charts'
```

**组件使用示例**：
```typescript
// 柱状图示例
const columnData = {
  categories: ['肢体', '听力', '视力', '言语', '智力', '精神'],
  series: [{
    name: '人数',
    data: [10, 8, 6, 4, 3, 2]
  }]
}

<ColumnChart
  data={columnData}
  width={350}
  height={200}
  config={{
    color: ['#3b82f6'],
    xAxis: { type: 'category' },
    yAxis: { type: 'value' }
  }}
/>

// 饼图示例
const pieData = [
  { name: '18-25岁', value: 5 },
  { name: '26-35岁', value: 12 },
  { name: '36-45岁', value: 8 },
  { name: '46-55岁', value: 4 },
  { name: '55岁以上', value: 2 }
]

<PieChart
  data={pieData}
  width={300}
  height={300}
  config={{
    color: ['#3b82f6', '#10b981', '#f59e0b', '#8b5cf6', '#ef4444']
  }}
/>
```

### 数据转换逻辑

**现有数据格式**（来自 API）：
```typescript
interface StatItem {
  key: string      // 类别名称
  value: number    // 数量
  percentage: number // 百分比
}

interface DistributionResponse {
  companyId: number
  stats: StatItem[]
  total: number
}
```

**转换为 mini-charts 格式**：
```typescript
// 柱状图数据转换
const convertToColumnData = (stats: StatItem[]) => ({
  categories: stats.map(item => item.key),
  series: [{
    name: '人数',
    data: stats.map(item => item.value)
  }]
})

// 饼图数据转换
const convertToPieData = (stats: StatItem[]) =>
  stats.map(item => ({
    name: item.key,
    value: item.value
  }))
```

### API规范
**数据统计API**：沿用故事011.005已有的API集成
- API 客户端：`enterpriseStatisticsClient`
- 接口：6个分布统计接口（残疾类型、性别、年龄、户籍、在职状态、薪资）
- 使用 React Query 进行数据获取，保持现有的缓存配置

### 组件规范
**保持现有布局结构**：
- 继续使用 `YongrenTabBarLayout` + `Navbar` 组合
- 保持 ScrollView 布局和内边距设置
- 保持统计卡片的展示方式（4个卡片）
- 保持时间筛选器功能

**图表组件集成方式**：
1. 为每个图表创建独立的容器组件（View）
2. 使用数据转换函数处理 API 响应数据
3. 配置图表选项，确保视觉效果符合原型设计
4. 保持加载状态和错误处理逻辑

### 技术约束
- **性能要求**：保持现有的懒加载和缓存机制
- **兼容性**：确保图表组件在 Taro 小程序环境正常工作
- **类型安全**：使用 TypeScript 严格模式，确保类型检查通过
- **响应式设计**：图表组件需要适配不同屏幕尺寸

### 测试要求
**测试框架**：Jest + Testing Library
**关键测试场景**：
1. **图表渲染测试**：
   - 测试图表组件正确渲染
   - 测试数据传递正确
   - 测试图表选项生效
2. **交互功能测试**：
   - 测试 tooltip 显示
   - 测试图表点击事件（如支持）
3. **数据转换测试**：
   - 测试数据转换函数正确性
   - 测试边界情况（空数据、单条数据）
4. **性能测试**：
   - 测试懒加载机制
   - 测试图表渲染性能
5. **集成测试**：
   - 测试与现有代码的集成
   - 测试页面整体功能

### 迁移策略
**渐进式迁移**：
1. 先迁移一个图表（如残疾类型分布），验证可行性
2. 确认无误后，逐个迁移其他图表
3. 每完成一个图表，删除对应的纯CSS实现代码
4. 最后完成整体测试和优化

**回滚计划**：
如果 mini-charts 组件存在问题，可以：
1. 保留原有代码在分支中，便于快速回滚
2. 逐步迁移，出现问题可单独回滚某个图表
3. 确保每个图表迁移后都经过充分测试

## 变更日志
| 日期 | 版本 | 描述 | 作者 |
|------|------|------|------|
| 2025-12-24 | 1.0 | 初始创建（使用 mini-charts 包重构数据统计图表） | Claude Code |

## 开发代理记录

### 代理信息
- **代理**: James (dev)
- **实施日期**: 2025-12-24
- **使用模型**: claude-sonnet

### 实施摘要
成功使用 mini-charts 包重构了数据统计页面的所有7个图表，从纯CSS实现升级为专业的 Canvas 图表组件。

### 修改的文件
1. **mini-ui-packages/yongren-statistics-ui/src/pages/Statistics/Statistics.tsx**
   - 导入 ColumnChart、PieChart、BaseChart 组件
   - 添加数据转换工具函数（convertToColumnData、convertToPieData）
   - 重构所有7个图表组件
   - 删除所有纯CSS实现代码

2. **mini-ui-packages/yongren-statistics-ui/package.json**
   - 添加 @d8d/mini-charts 依赖

3. **mini-ui-packages/yongren-statistics-ui/tests/pages/Statistics.test.tsx** (新建)
   - 13个测试用例全部通过
   - 覆盖所有图表组件和数据转换逻辑

### 技术实现细节

#### 图表组件使用
| 图表类型 | 使用组件 | 配置特点 |
|---------|---------|---------|
| 残疾类型分布 | ColumnChart | 单色柱状图 (#3b82f6) |
| 性别分布 | ColumnChart | 双色柱状图 (#3b82f6, #ec4899) |
| 年龄分布 | PieChart | 饼图，5种颜色 |
| 户籍省份分布 | BaseChart (type="bar") | 横向柱状图，6种颜色 |
| 在职状态统计 | PieChart (pieType="ring") | 环形图，4种颜色 |
| 薪资分布 | BaseChart (type="bar") | 横向柱状图，5种颜色 |

#### 数据转换
- **柱状图格式**: `{ categories: string[], series: [{ name, data: number[] }] }`
- **饼图格式**: `[{ name: string, data: number }]`
- 所有图表都配置了 tooltipFormatter 显示详细数据和百分比

#### 性能优化
- 保留了原有的懒加载机制（loadedCharts 状态）
- React Query 缓存配置保持不变（staleTime: 5min, gcTime: 10min）
- 图表分阶段加载（0ms、500ms、1000ms）

### 测试结果
- ✅ 13个测试用例全部通过
- ✅ 类型检查通过
- ✅ 所有验收标准满足

### 注意事项
1. 横向柱状图使用 BaseChart 组件并传入 type="bar"
2. 所有 canvasId 必须唯一（disability-type-chart, gender-chart, age-chart, household-chart, job-status-chart, salary-chart）
3. 图表尺寸设置为 width=650 以适应小程序屏幕
4. BaseChart 的 tooltip 需要手动实现 onTouchStart 处理

### 后续优化建议
1. 可考虑添加图表导出功能
2. 可考虑添加图表数据刷新动画
3. 可考虑优化移动端触摸交互体验
