|
|
@@ -0,0 +1,261 @@
|
|
|
+# 故事 011.007：使用 mini-charts 包重构数据统计图表
|
|
|
+
|
|
|
+## 状态
|
|
|
+Draft
|
|
|
+
|
|
|
+## 故事
|
|
|
+**作为**企业用户，
|
|
|
+**我希望**使用专业的图表组件展示数据统计，
|
|
|
+**以便**获得更好的数据可视化体验和交互功能。
|
|
|
+
|
|
|
+## 验收标准
|
|
|
+
|
|
|
+1. [ ] 数据统计页使用 mini-charts 包的图表组件替换纯CSS实现
|
|
|
+2. [ ] 残疾类型分布使用 ColumnChart 组件显示
|
|
|
+3. [ ] 性别分布使用 ColumnChart 组件显示
|
|
|
+4. [ ] 年龄分布使用 PieChart 组件显示
|
|
|
+5. [ ] 户籍省份分布使用 ColumnChart（横向）组件显示
|
|
|
+6. [ ] 在职状态统计使用 PieChart 组件显示
|
|
|
+7. [ ] 薪资分布使用 ColumnChart（横向）组件显示
|
|
|
+8. [ ] 图表支持 tooltip 交互，显示详细数据
|
|
|
+9. [ ] 保持现有的性能优化（懒加载、数据缓存）
|
|
|
+10. [ ] 通过类型检查和测试验证
|
|
|
+
|
|
|
+## 任务 / 子任务
|
|
|
+
|
|
|
+- [ ] 任务1：分析 mini-charts 包的可用组件和API（AC：全部）
|
|
|
+ - [ ] 阅读 `mini-ui-packages/mini-charts` 包的文档和示例
|
|
|
+ - [ ] 了解 ColumnChart、PieChart、LineChart 等组件的 Props 接口
|
|
|
+ - [ ] 了解图表配置选项（颜色、字体、动画等）
|
|
|
+ - [ ] 确认组件支持的数据格式
|
|
|
+ - [ ] 创建组件使用示例和测试
|
|
|
+
|
|
|
+- [ ] 任务2：重构残疾类型分布图表（AC：2）
|
|
|
+ - [ ] 导入 ColumnChart 组件
|
|
|
+ - [ ] 转换现有数据格式为 mini-charts 支持的格式
|
|
|
+ - [ ] 配置图表选项（标题、颜色、轴标签）
|
|
|
+ - [ ] 启用 tooltip 交互
|
|
|
+ - [ ] 测试图表渲染和交互功能
|
|
|
+ - [ ] 删除原有的纯CSS实现代码
|
|
|
+
|
|
|
+- [ ] 任务3：重构性别分布图表（AC：3）
|
|
|
+ - [ ] 导入 ColumnChart 组件
|
|
|
+ - [ ] 转换现有数据格式
|
|
|
+ - [ ] 配置图表选项（双色柱状图）
|
|
|
+ - [ ] 启用 tooltip 交互
|
|
|
+ - [ ] 测试图表渲染和交互功能
|
|
|
+ - [ ] 删除原有的纯CSS实现代码
|
|
|
+
|
|
|
+- [ ] 任务4：重构年龄分布图表（AC：4）
|
|
|
+ - [ ] 导入 PieChart 组件
|
|
|
+ - [ ] 转换现有数据格式为饼图格式
|
|
|
+ - [ ] 配置图表选项（颜色、图例）
|
|
|
+ - [ ] 启用 tooltip 交互
|
|
|
+ - [ ] 测试图表渲染和交互功能
|
|
|
+ - [ ] 删除原有的纯CSS实现代码
|
|
|
+
|
|
|
+- [ ] 任务5：重构户籍省份分布图表（AC：5）
|
|
|
+ - [ ] 导入 ColumnChart 组件（横向柱状图）
|
|
|
+ - [ ] 转换现有数据格式
|
|
|
+ - [ ] 配置图表选项（横向、颜色）
|
|
|
+ - [ ] 启用 tooltip 交互
|
|
|
+ - [ ] 测试图表渲染和交互功能
|
|
|
+ - [ ] 删除原有的纯CSS实现代码
|
|
|
+
|
|
|
+- [ ] 任务6：重构在职状态统计图表（AC：6）
|
|
|
+ - [ ] 导入 PieChart 组件（环形图）
|
|
|
+ - [ ] 转换现有数据格式
|
|
|
+ - [ ] 配置图表选项（环形图样式）
|
|
|
+ - [ ] 启用 tooltip 交互
|
|
|
+ - [ ] 测试图表渲染和交互功能
|
|
|
+ - [ ] 删除原有的纯CSS实现代码
|
|
|
+
|
|
|
+- [ ] 任务7：重构薪资分布图表（AC：7）
|
|
|
+ - [ ] 导入 ColumnChart 组件（横向柱状图）
|
|
|
+ - [ ] 转换现有数据格式
|
|
|
+ - [ ] 配置图表选项（横向、颜色）
|
|
|
+ - [ ] 启用 tooltip 交互
|
|
|
+ - [ ] 测试图表渲染和交互功能
|
|
|
+ - [ ] 删除原有的纯CSS实现代码
|
|
|
+
|
|
|
+- [ ] 任务8：验证性能优化和用户体验（AC：8-10）
|
|
|
+ - [ ] 验证懒加载机制仍然有效（分阶段加载图表）
|
|
|
+ - [ ] 验证数据缓存机制正常工作
|
|
|
+ - [ ] 测试图表交互功能（tooltip 显示）
|
|
|
+ - [ ] 测试移动端显示效果
|
|
|
+ - [ ] 确保页面加载速度符合要求
|
|
|
+ - [ ] 运行类型检查验证（pnpm typecheck）
|
|
|
+
|
|
|
+- [ ] 任务9：编写测试和文档（AC：10）
|
|
|
+ - [ ] 编写图表组件集成测试
|
|
|
+ - [ ] 测试数据转换逻辑
|
|
|
+ - [ ] 测试图表渲染和交互
|
|
|
+ - [ ] 更新故事文档，记录实施细节
|
|
|
+ - [ ] 更新开发笔记，添加 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 |
|
|
|
+
|
|
|
+## 开发代理记录
|
|
|
+*此部分由开发代理在实施过程中填充*
|
yourname