# 史诗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）**
1. 分析当前 u-charts.ts 文件结构（7719行）
2. 按功能模块拆分为多个文件，并在拆分过程中添加 TypeScript 类型定义
3. 保持向后兼容性
4. 确保拆分后功能完整性

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

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

**阶段5：创建测试套件（故事016.005）**
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 核心库模块化并添加类型定义
**背景：** 当前 u-charts.ts 文件包含7719行代码，所有功能都在一个文件中，包括42个绘制函数、约60个工具/数据处理函数以及2个类。这种结构不利于代码维护、测试和后续的开发。同时，原始库为纯JavaScript，缺少TypeScript类型支持。

**重要说明**：本故事将模块化拆分与类型定义合并进行。TypeScript 编译器会自动生成 .d.ts 声明文件（已在 tsconfig.json 中配置 `declaration: true`），因此只需在拆分模块时添加适当的类型注解即可，无需单独创建类型定义文件。

**任务列表：**
1. 分析当前 u-charts.ts 文件结构：
   - 识别所有函数和类的职责
   - 分析函数之间的依赖关系
   - 确定模块划分方案
   - 识别需要添加类型注解的关键位置
2. 创建模块化目录结构：
   ```
   src/lib/
   ├── index.ts                    # 统一导出，保持向后兼容
   ├── config.ts                   # 配置常量（config、assign等）
   ├── utils/                      # 工具函数模块
   │   ├── index.ts
   │   ├── color.ts                # 颜色工具（hexToRgb等）
   │   ├── math.ts                 # 数学工具（findRange、normalInt等）
   │   ├── coordinate.ts           # 坐标转换（convertCoordinateOrigin等）
   │   ├── text.ts                 # 文本测量（measureText等）
   │   └── collision.ts            # 碰撞检测（avoidCollision等）
   ├── data-processing/            # 数据处理模块
   │   ├── index.ts
   │   ├── series-calculator.ts    # 系列数据处理
   │   ├── axis-calculator.ts      # 坐标轴计算
   │   ├── categories-calculator.ts # 分类数据处理
   │   └── tooltip-calculator.ts   # 提示框数据计算
   ├── charts-data/                # 图表数据点计算
   │   ├── index.ts
   │   ├── basic-charts.ts         # 基础图表数据点
   │   ├── pie-charts.ts           # 饼图数据点
   │   ├── radar-charts.ts         # 雷达图数据点
   │   ├── map-charts.ts           # 地图数据点
   │   └── other-charts.ts         # 其他图表数据点
   ├── renderers/                  # 绘制函数模块
   │   ├── index.ts
   │   ├── common-renderer.ts      # 通用绘制（drawPointShape、drawToolTip等）
   │   ├── axis-renderer.ts        # 坐标轴绘制
   │   ├── column-renderer.ts      # 柱状图绘制
   │   ├── line-renderer.ts        # 折线图绘制
   │   ├── candle-renderer.ts      # K线图绘制
   │   ├── pie-renderer.ts         # 饼图绘制
   │   ├── radar-renderer.ts       # 雷达图绘制
   │   ├── map-renderer.ts         # 地图绘制
   │   └── special-renderer.ts     # 特殊图表绘制（词云、漏斗等）
   └── charts/                     # 核心类模块
       ├── index.ts
       ├── u-charts-event.ts       # 事件类
       └── u-charts.ts             # 主类（重构后）
   ```
3. 拆分文件并添加类型注解（按优先级）：
   - **第一批**：配置和工具函数（低依赖）
     - 创建 config.ts，导出 config、assign、util，添加类型注解
     - 创建 utils/ 目录下的文件，为工具函数添加参数和返回值类型
   - **第二批**：数据处理函数（中依赖）
     - 创建 data-processing/ 目录，添加数据流类型
     - 创建 charts-data/ 目录，添加数据点类型
   - **第三批**：绘制函数（高依赖）
     - 创建 renderers/ 目录，添加 Canvas 上下文和配置类型
   - **第四批**：核心类重构
     - 重构 u-charts.ts，导入所有模块，添加类方法类型
     - 移动 uChartsEvent 类到独立文件，添加事件类型
4. 更新 src/index.ts：
   - 导出所有公共API
   - 保持向后兼容性（默认导出 uCharts 类）
   - 导出各个模块供高级用户使用
5. 验证拆分结果：
   - 确保所有导出正确
   - 运行类型检查，验证类型注解正确
   - 如果有现有测试，确保测试通过
   - 验证生成的 .d.ts 文件正确导出类型

**验收标准：**
- [ ] u-charts.ts 成功拆分为多个模块文件
- [ ] 每个模块职责单一、边界清晰
- [ ] 所有函数和类正确导出
- [ ] src/index.ts 保持向后兼容，默认导出 uCharts 类
- [ ] 所有公共函数和类都有完整的类型注解
- [ ] 类型检查通过（pnpm typecheck），无 any 类型（除非必要）
- [ ] 包可以成功构建，自动生成 .d.ts 声明文件
- [ ] 代码组织清晰，易于维护和测试
- [ ] 模块间依赖关系合理，无循环依赖

**技术注意事项：**
- 拆分时保持函数逻辑完全不变，只改变文件组织
- 使用相对导入确保模块间正确引用
- 在拆分时同步添加类型注解，利用 TypeScript 自动生成 .d.ts 文件
- 公共 API 添加完整类型注解，内部实现可适当使用 any
- 保持原有的代码风格
- 拆分后每个文件控制在500行以内
- 移除 `@ts-nocheck` 注解，使用正确的类型替代

**风险缓解：**
- 在拆分前备份原始文件
- 分批拆分，每批完成后进行验证
- 使用 Git 版本控制，便于回滚
- 拆分过程中保持构建可运行状态

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

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

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

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

**任务列表：**
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 核心库完成模块化重构，并添加完整的类型注解
- [ ] 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)