# 史诗016 - mini小程序图表组件包（mini-charts）

## 史诗目标
将 `docs/小程序图表库示例/` 目录下的 u-charts 图表库（约7700行代码）迁移为独立的 mini-ui-packages 共享包 `mini-charts`，为 Taro 小程序提供完整的图表解决方案，支持柱状图、折线图、K线图等多种图表类型。

## 史诗描述

### 现有系统上下文

**当前相关功能：**
- **u-charts 图表库**：位于 `docs/小程序图表库示例/u-charts小程序图表库.js`，是一个高性能跨平台图表库
- **支持平台**：H5、APP、小程序（微信/支付宝/百度/头条/QQ/360/快手）、Vue、Taro等支持canvas的框架平台
- **示例代码**：`docs/小程序图表库示例/使用示例.md` 提供了完整的 React + Taro 使用示例
- **版本信息**：v2.5.0-20230101

**技术特性：**
- 支持多种图表类型：柱状图(column)、折线图(line)、K线图(candle)、饼图、雷达图等
- 支持Canvas绘制，高性能渲染
- 支持触摸交互：tooltip显示、拖拽滚动
- 支持数据标签、图例、动画效果
- 高度可配置：颜色、字体、网格、坐标轴等
- 响应式设计，支持多种屏幕尺寸和像素比

**集成点：**
- Taro Canvas API
- React 18组件系统
- 小程序平台适配（微信小程序为主）
- 与现有 mini-ui-packages 包结构保持一致
- 与现有测试框架（Jest）集成

**当前架构分析：**
1. **图表库未模块化**：u-charts 库文件位于文档目录下，未形成可复用的包
2. **缺少类型定义**：原库为纯JavaScript，缺少TypeScript类型支持
3. **缺少React组件封装**：示例代码展示的是类组件使用方式，需要现代函数式组件封装
4. **缺少测试**：没有针对图表组件的测试套件
5. **缺少文档**：只有使用示例，缺少完整的API文档

### 增强详情

**改造范围：**
本次史诗将完成以下工作：

**阶段1：创建 mini-charts 包基础结构（故事016.001）**
1. 创建新的包 `mini-ui-packages/mini-charts`
2. 配置 package.json，依赖 Taro 相关包
3. 设置 TypeScript 配置和类型定义
4. 配置构建和测试脚本
5. 迁移 u-charts 核心库文件

**阶段2：搬迁 u-charts 核心库到模块化结构并添加类型定义（故事016.002-016.006）**
1. 分析当前 u-charts.ts 文件结构（7719行）
2. 按功能模块**搬迁**代码到多个文件（分5个子故事完成），并在搬迁过程中添加 TypeScript 类型注解
3. **重要**：搬迁时保持代码逻辑完全不变，只改变文件组织方式
4. 确保搬迁后功能完整性

**阶段3：创建 React 图表组件封装（故事016.007）**
1. 创建现代函数式图表组件：
   - ColumnChart（柱状图）
   - LineChart（折线图）
   - CandleChart（K线图）
   - PieChart（饼图）
   - RadarChart（雷达图）
2. 使用 Taro Canvas API 封装底层绘图逻辑
3. 支持触摸事件处理（tooltip、拖拽）
4. 支持响应式尺寸计算

**阶段4：创建使用示例和文档（故事016.008）**
1. 在包内创建 examples 目录
2. 提供完整的示例代码
3. 创建 API 文档
4. 更新使用示例.md

**阶段5：创建测试套件（故事016.009）**
1. 设置 Jest 测试环境
2. 创建图表组件单元测试
3. 创建 Canvas mock 用于测试
4. 验证组件渲染和交互

**迁移策略：**
1. **保留原始逻辑**：保持 u-charts 核心绘制逻辑不变
2. **渐进式封装**：先迁移核心库，再模块化并添加类型定义，最后创建 React 组件
3. **类型定义自动化**：TypeScript 会自动生成 .d.ts 声明文件，在模块化拆分时添加类型注解即可
4. **向后兼容**：提供直接使用 u-charts 类的接口
5. **测试驱动**：为每个组件编写测试

**成功标准：**
1. `mini-charts` 包创建成功，可通过 workspace 引用
2. u-charts 核心库成功迁移，功能完整
3. u-charts 核心库完成模块化重构，并添加完整的类型注解
4. TypeScript 类型定义完整，自动生成 .d.ts 声明文件，无 any 类型（除非必要）
5. 提供至少5种常用图表组件（柱状图、折线图、K线图、饼图、雷达图）
6. 组件可以独立测试（类型检查和 Jest 测试通过）
7. 提供完整的示例和文档
8. 可以被 mini 项目或其他 mini-ui-packages 引用

## 故事列表

### 故事016-001：创建 mini-charts 包基础结构
**背景：** u-charts 图表库目前位于文档目录下，需要迁移为独立的共享包，以便在多个小程序项目中复用。

**任务列表：**
1. 创建新的包 `mini-ui-packages/mini-charts`
   - 配置 package.json，依赖 Taro 相关包
   - 设置 TypeScript 配置（tsconfig.json）
   - 配置构建和测试脚本
2. 迁移 u-charts 核心库文件：
   - 将 `docs/小程序图表库示例/u-charts小程序图表库.js` 迁移到 `src/lib/u-charts.ts`
   - 保持原始逻辑不变
   - 将文件转换为 TypeScript 格式（添加基础类型）
3. 创建包的导出配置：
   - 建立 src/index.ts 主入口
   - 导出 u-charts 核心类
   - 配置 package.json 的 exports 字段

**验收标准：**
- [x] `mini-charts` 包目录结构创建完成
- [x] package.json 配置正确，包含所有必需依赖
- [x] tsconfig.json 配置正确
- [x] u-charts 核心库迁移成功，无语法错误
- [x] 包可以成功构建（tsc 编译通过）
- [x] 类型检查通过（pnpm typecheck）

### 故事016-002：搬迁配置和工具函数到独立模块并添加类型定义
**背景：** u-charts.ts 文件包含约60个工具/数据处理函数。首先将低依赖的配置常量和工具函数**搬迁**到独立模块，为后续模块化搬迁打好基础。

**重要原则**：
- **搬迁**而非重构：保持代码逻辑完全不变，只改变文件组织方式
- 只在搬迁过程中添加 TypeScript 类型注解
- 不修改代码的实现逻辑

**任务列表：**
1. 分析配置和工具函数：
   - 识别 config、assign、util 等配置对象
   - 识别颜色工具（hexToRgb等）
   - 识别数学工具（findRange、normalInt等）
   - 识别坐标转换工具（convertCoordinateOrigin等）
   - 识别文本测量工具（measureText等）
   - 识别碰撞检测工具（avoidCollision等）
2. 创建模块化目录结构：
   - 创建 `src/lib/config.ts`
   - 创建 `src/lib/utils/` 目录及子模块
3. **搬迁**配置和工具函数：
   - 将 config、assign、util 搬迁到 config.ts，添加类型注解
   - 将颜色工具函数搬迁到 utils/color.ts，添加类型注解
   - 将数学工具函数搬迁到 utils/math.ts，添加类型注解
   - 将坐标转换工具函数搬迁到 utils/coordinate.ts，添加类型注解
   - 将文本测量工具函数搬迁到 utils/text.ts，添加类型注解
   - 将碰撞检测工具函数搬迁到 utils/collision.ts，添加类型注解
   - 创建 utils/index.ts 统一导出
4. 验证搬迁结果：
   - 确保所有工具函数正确导出
   - 运行类型检查验证类型注解正确
   - 确认代码逻辑与原始文件完全一致

**验收标准：**
- [x] config.ts 创建完成，包含 config、assign、util 并有完整类型注解
- [x] utils/ 目录下所有文件创建完成，每个函数都有类型注解
- [x] 类型检查通过（pnpm typecheck），无 any 类型（除非必要）
- [x] 每个文件控制在500行以内
- [x] 代码逻辑与原始 u-charts.ts 完全一致

**完成状态：** ✅ Ready for Review (2025-12-24)

### 故事016-003：搬迁数据处理函数到独立模块并添加类型定义
**背景：** 配置和工具函数模块化完成后，继续**搬迁**数据处理相关函数，包括系列数据处理、坐标轴计算、分类数据处理和提示框数据计算。

**重要原则**：
- **搬迁**而非重构：保持代码逻辑完全不变，只改变文件组织方式
- 只在搬迁过程中添加 TypeScript 类型注解
- 不修改代码的实现逻辑

**任务列表：**
1. 分析数据处理函数：
   - 识别系列数据处理函数（fillSeries、fixPieSeries等）
   - 识别坐标轴计算函数（calXAxisData、calYAxisData等）
   - 识别分类数据处理函数（calCategoriesData等）
   - 识别提示框数据计算函数（getToolTipData等）
2. 创建 data-processing 模块：
   - 创建 data-processing/series-calculator.ts
   - 创建 data-processing/axis-calculator.ts
   - 创建 data-processing/categories-calculator.ts
   - 创建 data-processing/tooltip-calculator.ts
   - 创建 data-processing/index.ts 统一导出
3. **搬迁**数据处理函数并添加类型注解：
   - 将系列数据处理函数搬迁到 series-calculator.ts，添加类型注解
   - 将坐标轴计算函数搬迁到 axis-calculator.ts，添加类型注解
   - 将分类数据处理函数搬迁到 categories-calculator.ts，添加类型注解
   - 将提示框数据计算函数搬迁到 tooltip-calculator.ts，添加类型注解
4. 验证搬迁结果：
   - 确保所有数据处理函数正确导出
   - 运行类型检查验证类型注解正确
   - 确认代码逻辑与原始文件完全一致

**验收标准：**
- [ ] data-processing/ 目录下所有文件创建完成
- [ ] 所有数据处理函数都有完整类型注解
- [ ] 类型检查通过（pnpm typecheck），无 any 类型（除非必要）
- [ ] 每个文件控制在500行以内
- [ ] 代码逻辑与原始 u-charts.ts 完全一致

### 故事016-004：搬迁图表数据点计算函数到独立模块并添加类型定义
**背景：** 数据处理模块化完成后，继续**搬迁**各种图表类型的数据点计算函数，包括基础图表、饼图、雷达图、地图和其他图表的数据点计算。

**重要原则**：
- **搬迁**而非重构：保持代码逻辑完全不变，只改变文件组织方式
- 只在搬迁过程中添加 TypeScript 类型注解
- 不修改代码的实现逻辑

**任务列表：**
1. 分析图表数据点计算函数：
   - 识别基础图表数据点函数（getColumnDataPoints、getDataPoints等）
   - 识别饼图数据点函数（getPieDataPoints、getRoseDataPoints等）
   - 识别雷达图数据点函数（getRadarDataPoints等）
   - 识别地图数据点函数（getMapDataPoints等）
   - 识别其他图表数据点函数（getGaugeDataPoints、getFunnelDataPoints等）
2. 创建 charts-data 模块：
   - 创建 charts-data/basic-charts.ts
   - 创建 charts-data/pie-charts.ts
   - 创建 charts-data/radar-charts.ts
   - 创建 charts-data/map-charts.ts
   - 创建 charts-data/other-charts.ts
   - 创建 charts-data/index.ts 统一导出
3. **搬迁**数据点计算函数并添加类型注解：
   - 将基础图表数据点函数搬迁到 basic-charts.ts，添加类型注解
   - 将饼图数据点函数搬迁到 pie-charts.ts，添加类型注解
   - 将雷达图数据点函数搬迁到 radar-charts.ts，添加类型注解
   - 将地图数据点函数搬迁到 map-charts.ts，添加类型注解
   - 将其他图表数据点函数搬迁到 other-charts.ts，添加类型注解
4. 验证搬迁结果：
   - 确保所有数据点计算函数正确导出
   - 运行类型检查验证类型注解正确
   - 确认代码逻辑与原始文件完全一致

**验收标准：**
- [ ] charts-data/ 目录下所有文件创建完成
- [ ] 所有数据点计算函数都有完整类型注解
- [ ] 类型检查通过（pnpm typecheck），无 any 类型（除非必要）
- [ ] 每个文件控制在500行以内
- [ ] 代码逻辑与原始 u-charts.ts 完全一致

### 故事016-005：搬迁绘制函数到独立模块并添加类型定义
**背景：** 图表数据点计算模块化完成后，继续**搬迁**所有绘制相关函数，包括通用绘制、坐标轴绘制、各种图表类型的绘制函数。

**重要原则**：
- **搬迁**而非重构：保持代码逻辑完全不变，只改变文件组织方式
- 只在搬迁过程中添加 TypeScript 类型注解
- 不修改代码的实现逻辑

**任务列表：**
1. 分析绘制函数：
   - 识别通用绘制函数（drawPointShape、drawToolTip、drawLegend等）
   - 识别坐标轴绘制函数（drawXAxis、drawYAxis等）
   - 识别柱状图绘制函数（drawColumnDataPoints等）
   - 识别折线图/面积图绘制函数（drawLineDataPoints、drawAreaDataPoints等）
   - 识别K线图绘制函数（drawCandleDataPoints等）
   - 识别饼图绘制函数（drawPieDataPoints、drawRoseDataPoints等）
   - 识别雷达图绘制函数（drawRadarDataPoints等）
   - 识别地图绘制函数（drawMapDataPoints等）
   - 识别特殊图表绘制函数（drawWordCloudDataPoints、drawFunnelDataPoints等）
2. 创建 renderers 模块：
   - 创建 renderers/common-renderer.ts
   - 创建 renderers/axis-renderer.ts
   - 创建 renderers/column-renderer.ts
   - 创建 renderers/line-renderer.ts
   - 创建 renderers/candle-renderer.ts
   - 创建 renderers/pie-renderer.ts
   - 创建 renderers/radar-renderer.ts
   - 创建 renderers/map-renderer.ts
   - 创建 renderers/special-renderer.ts
   - 创建 renderers/index.ts 统一导出
3. **搬迁**绘制函数并添加类型注解：
   - 将通用绘制函数搬迁到 common-renderer.ts，添加类型注解
   - 将坐标轴绘制函数搬迁到 axis-renderer.ts，添加类型注解
   - 将各图表类型绘制函数搬迁到对应的 renderer 文件，添加类型注解
4. 验证搬迁结果：
   - 确保所有绘制函数正确导出
   - 运行类型检查验证类型注解正确
   - 确认代码逻辑与原始文件完全一致

**验收标准：**
- [ ] renderers/ 目录下所有文件创建完成
- [ ] 所有绘制函数都有完整类型注解
- [ ] 类型检查通过（pnpm typecheck），无 any 类型（除非必要）
- [ ] 每个文件控制在500行以内
- [ ] 代码逻辑与原始 u-charts.ts 完全一致

### 故事016-006：搬迁核心类并完成模块化
**背景：** 所有功能模块化完成后，最后**搬迁** uCharts 主类和 uChartsEvent 事件类，导入所有模块，完成整个 u-charts 核心库的模块化**搬迁**。

**重要原则**：
- **搬迁**而非重构：保持代码逻辑完全不变，只改变文件组织方式
- 只在搬迁过程中添加 TypeScript 类型注解
- 不修改代码的实现逻辑

**任务列表：**
1. 分析核心类：
   - 分析 uChartsEvent 事件类
   - 分析 uCharts 主类的所有方法
   - 识别类方法与各模块的依赖关系
2. 创建 charts 模块：
   - 创建 charts/u-charts-event.ts，**搬迁** uChartsEvent 类，添加完整事件类型注解
   - 创建 charts/u-charts.ts，**搬迁** uCharts 主类，导入所有模块，添加类型注解
   - 创建 charts/index.ts 统一导出
3. 更新 src/index.ts：
   - 导出所有公共API
   - 保持向后兼容性（默认导出 uCharts 类）
   - 导出各个模块供高级用户使用
4. 更新 package.json：
   - 更新 exports 字段支持模块导出
5. 验证搬迁结果：
   - 确保所有导出正确
   - 运行类型检查验证类型注解正确
   - 运行 pnpm build 验证构建成功，生成 .d.ts 文件
   - 检查生成的 .d.ts 文件正确导出类型
   - 验证模块间无循环依赖
   - 确认代码逻辑与原始文件完全一致
6. 删除或备份原始 u-charts.ts 文件

**验收标准：**
- [ ] charts/ 目录下所有文件创建完成
- [ ] uChartsEvent 和 uCharts 类有完整类型注解
- [ ] src/index.ts 保持向后兼容，默认导出 uCharts 类
- [ ] 类型检查通过（pnpm typecheck），无 any 类型（除非必要）
- [ ] 包可以成功构建（pnpm build），自动生成 .d.ts 声明文件
- [ ] 代码组织清晰，易于维护和测试
- [ ] 模块间依赖关系合理，无循环依赖
- [ ] 代码逻辑与原始 u-charts.ts 完全一致

### 故事016-007：创建 React 图表组件封装
**背景：** u-charts 原库需要手动管理 Canvas 上下文和事件处理。需要创建现代 React 函数式组件，简化使用方式。

**任务列表：**
1. 创建基础图表组件 BaseChart：
   - 封装 Canvas 创建和销毁逻辑
   - 处理响应式尺寸计算
   - 处理像素比适配
   - 封装事件处理（触摸、点击）
2. 创建具体图表组件：
   - ColumnChart（柱状图）
   - LineChart（折线图）
   - CandleChart（K线图）
   - PieChart（饼图）
   - RadarChart（雷达图）
3. 每个组件包含：
   - Props 接口定义
   - 默认配置
   - Canvas 绘制逻辑
   - 事件处理（tooltip、拖拽等）
4. 从 `docs/小程序图表库示例/使用示例.md` 迁移示例代码作为参考

**验收标准：**
- [ ] BaseChart 基础组件创建完成
- [ ] 至少5种图表组件实现完成
- [ ] 组件支持 Props 配置
- [ ] 组件支持触摸事件（tooltip）
- [ ] 组件支持响应式尺寸
- [ ] 类型定义完整，无类型错误

### 故事016-008：创建使用示例和文档
**背景：** 需要提供完整的使用示例和 API 文档，帮助开发者快速上手使用 mini-charts 包。

**任务列表：**
1. 创建 examples 目录：
   - 迁移并更新 `docs/小程序图表库示例/使用示例.md` 中的示例
   - 为每种图表类型创建独立示例
   - 创建复杂场景示例（混合图表、多轴图表等）
2. 创建 README.md：
   - 包简介和特性
   - 安装说明
   - 快速开始指南
   - API 文档
   - 配置选项说明
   - 常见问题解答
3. 更新原使用示例文档，指向新包的使用方式

**验收标准：**
- [ ] examples 目录创建完成，包含至少3个示例
- [ ] README.md 文档完整，包含所有必需章节
- [ ] API 文档详细，覆盖所有公共接口
- [ ] 配置选项说明清晰，包含示例
- [ ] 原使用示例文档已更新

### 故事016-009：创建测试套件
**背景：** 需要为图表组件创建完整的测试套件，确保组件质量和稳定性。

**任务列表：**
1. 设置 Jest 测试环境：
   - 配置 jest.config.js
   - 创建 Taro 和 Canvas 的 mock
2. 创建工具函数：
   - createMockCanvasContext：创建模拟 Canvas 上下文
   - waitForChartRender：等待图表渲染完成
3. 编写组件测试：
   - 测试组件渲染
   - 测试 Props 传递
   - 测试事件处理
   - 测试响应式尺寸
4. 编写集成测试：
   - 测试图表数据更新
   - 测试图表交互

**验收标准：**
- [ ] Jest 测试环境配置完成
- [ ] Canvas mock 创建完成
- [ ] 每个图表组件都有单元测试
- [ ] 测试覆盖率达到 60% 以上
- [ ] 所有测试通过

## 兼容性要求

- [ ] 保持 u-charts 原库功能完整性
- [ ] 支持微信小程序平台
- [ ] 支持 Taro 4.1.4 框架
- [ ] 支持 React 18
- [ ] 向后兼容，支持直接使用 u-charts 类

## 风险缓解

- **主要风险**：u-charts 库文件较大（约7700行），迁移过程中可能遗漏功能
- **缓解措施**：保留原始文件，迁移后进行功能对比测试
- **回滚计划**：如果迁移导致问题，可以从文档目录重新使用原文件
- **类型定义风险**：原库没有类型，可能存在类型定义不准确的问题
- **缓解措施**：在模块化重构时同步添加类型注解，利用 TypeScript 自动生成 .d.ts 文件

## 完成定义

- [ ] 所有故事完成，验收标准满足
- [ ] u-charts 核心库完成模块化**搬迁**（故事016.002-016.006），并添加完整的类型注解
- [ ] TypeScript 自动生成的 .d.ts 声明文件正确导出所有公共 API
- [ ] 类型检查通过，无 TypeScript 错误
- [ ] 所有测试通过，包括单元测试和集成测试
- [ ] 代码审查通过，符合项目编码标准
- [ ] 文档完整，包含使用示例和 API 文档
- [ ] 包可以被其他 mini-ui-packages 或 mini 项目引用

## 附件

- [u-charts 官方网站](https://www.uCharts.cn)
- [开源地址](https://gitee.com/uCharts/uCharts)
- [uni-app插件市场地址](http://ext.dcloud.net.cn/plugin?id=271)
- 本项目中的 u-charts 文件：[docs/小程序图表库示例/u-charts小程序图表库.js](docs/小程序图表库示例/u-charts小程序图表库.js)
- 本项目中的使用示例：[docs/小程序图表库示例/使用示例.md](docs/小程序图表库示例/使用示例.md)