mini-starter/docs/prd/epic-016-mini-charts-package.md

史诗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 字段

验收标准：

• mini-charts 包目录结构创建完成
• package.json 配置正确，包含所有必需依赖
• tsconfig.json 配置正确
• u-charts 核心库迁移成功，无语法错误
• 包可以成功构建（tsc 编译通过）
• 类型检查通过（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. 验证搬迁结果：
   • 确保所有工具函数正确导出
   • 运行类型检查验证类型注解正确
   • 确认代码逻辑与原始文件完全一致

验收标准：

• config.ts 创建完成，包含 config、assign、util 并有完整类型注解
• utils/ 目录下所有文件创建完成，每个函数都有类型注解
• 类型检查通过（pnpm typecheck），无 any 类型（除非必要）
• 每个文件控制在500行以内
• 代码逻辑与原始 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 官方网站
• 开源地址
• uni-app插件市场地址
• 本项目中的 u-charts 文件：docs/小程序图表库示例/u-charts小程序图表库.js
• 本项目中的使用示例：docs/小程序图表库示例/使用示例.md