Bladeren bron

docs(prd): 史诗016新增故事016-006用于u-charts核心库模块化重构

主要变更:
- 新增故事016-006:重构 u-charts 核心库模块化
  - 将7719行的u-charts.ts拆分为多个模块文件
  - 按功能划分为:utils、data-processing、charts-data、renderers、charts
  - 采用分批拆分策略,降低风险
  - 保持向后兼容性

- 调整史诗阶段编号:
  - 阶段2:重构 u-charts 核心库模块化(故事016.006)
  - 阶段3:添加 TypeScript 类型定义(故事016.002)
  - 阶段4:创建 React 组件封装(故事016.003)
  - 阶段5:创建使用示例和文档(故事016.004)
  - 阶段6:创建测试套件(故事016.005)

- 更新故事016-002背景说明:
  - 说明在模块化重构后进行类型定义
  - 模块化结构更易于添加类型
  - 为各模块分别添加类型定义

模块化结构:
```
src/lib/
├── config.ts              # 配置常量
├── utils/                 # 工具函数
├── data-processing/       # 数据处理
├── charts-data/          # 图表数据点计算
├── renderers/            # 绘制函数
└── charts/               # 核心类
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
yourname 3 weken geleden
bovenliggende
commit
b84583bdf2
1 gewijzigde bestanden met toevoegingen van 115 en 11 verwijderingen
  1. 115 11
      docs/prd/epic-016-mini-charts-package.md

+ 115 - 11
docs/prd/epic-016-mini-charts-package.md

@@ -47,13 +47,19 @@
 4. 配置构建和测试脚本
 5. 迁移 u-charts 核心库文件
 
-**阶段2:添加 TypeScript 类型定义(故事016.002)**
-1. 为 u-charts 库添加完整的 TypeScript 类型定义
+**阶段2:重构 u-charts 核心库模块化(故事016.006)**
+1. 分析当前 u-charts.ts 文件结构(7719行)
+2. 按功能模块拆分为多个文件
+3. 保持向后兼容性
+4. 确保拆分后功能完整性
+
+**阶段3:添加 TypeScript 类型定义(故事016.002)**
+1. 为重构后的 u-charts 库添加完整的 TypeScript 类型定义
 2. 定义图表配置接口(ChartConfig、SeriesConfig、AxisConfig等)
 3. 定义图表类型枚举(ChartType)
 4. 导出类型供使用者使用
 
-**阶段3:创建 React 组件封装(故事016.003)**
+**阶段4:创建 React 组件封装(故事016.003)**
 1. 创建现代函数式图表组件:
    - ColumnChart(柱状图)
    - LineChart(折线图)
@@ -64,13 +70,13 @@
 3. 支持触摸事件处理(tooltip、拖拽)
 4. 支持响应式尺寸计算
 
-**阶段4:创建使用示例和文档(故事016.004)**
+**阶段5:创建使用示例和文档(故事016.004)**
 1. 在包内创建 examples 目录
 2. 提供完整的示例代码
 3. 创建 API 文档
 4. 更新使用示例.md
 
-**阶段5:创建测试套件(故事016.005)**
+**阶段6:创建测试套件(故事016.005)**
 1. 设置 Jest 测试环境
 2. 创建图表组件单元测试
 3. 创建 Canvas mock 用于测试
@@ -118,23 +124,121 @@
 - [ ] 包可以成功构建(tsc 编译通过)
 - [ ] 类型检查通过(pnpm typecheck)
 
+### 故事016-006:重构 u-charts 核心库模块化
+**背景:** 当前 u-charts.ts 文件包含7719行代码,所有功能都在一个文件中,包括42个绘制函数、约60个工具/数据处理函数以及2个类。这种结构不利于代码维护、测试和后续的类型定义添加。
+
+**任务列表:**
+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/ 目录
+   - **第四批**:核心类重构
+     - 重构 u-charts.ts,导入所有模块
+     - 移动 uChartsEvent 类到独立文件
+4. 更新 src/index.ts:
+   - 导出所有公共API
+   - 保持向后兼容性(默认导出 uCharts 类)
+   - 导出各个模块供高级用户使用
+5. 验证拆分结果:
+   - 确保所有导出正确
+   - 运行类型检查
+   - 如果有现有测试,确保测试通过
+
+**验收标准:**
+- [ ] u-charts.ts 成功拆分为多个模块文件
+- [ ] 每个模块职责单一、边界清晰
+- [ ] 所有函数和类正确导出
+- [ ] src/index.ts 保持向后兼容,默认导出 uCharts 类
+- [ ] 类型检查通过(pnpm typecheck)
+- [ ] 包可以成功构建
+- [ ] 代码组织清晰,易于维护和测试
+- [ ] 模块间依赖关系合理,无循环依赖
+
+**技术注意事项:**
+- 拆分时保持函数逻辑完全不变,只改变文件组织
+- 使用相对导入确保模块间正确引用
+- 注意 TypeScript 的类型导出
+- 保持原有的代码风格
+- 拆分后每个文件控制在500行以内
+
+**风险缓解:**
+- 在拆分前备份原始文件
+- 分批拆分,每批完成后进行验证
+- 使用 Git 版本控制,便于回滚
+- 拆分过程中保持构建可运行状态
+
 ### 故事016-002:添加 TypeScript 类型定义
-**背景:** u-charts 原库为纯JavaScript,缺少类型支持。需要添加完整的 TypeScript 类型定义,提高开发体验和代码安全性。
+**背景:** 在故事016.006完成模块化重构后,需要为重构后的 u-charts 库添加完整的 TypeScript 类型定义。原库为纯JavaScript,缺少类型支持。模块化后的结构更容易添加类型,提高开发体验和代码安全性。
 
 **任务列表:**
-1. 分析 u-charts 库的配置选项
-   - 阅读源代码,理解各种配置参数
+1. 分析重构后的 u-charts 库结构:
+   - 理解各模块的导出内容
+   - 识别公共 API 和内部 API
    - 参考使用示例.md 中的配置
-   - 识别所有公共 API
-2. 定义 TypeScript 接口:
+2. 定义核心 TypeScript 接口(types/ 目录):
    - ChartConfig:图表总配置接口
    - ChartType:图表类型枚举('column' | 'line' | 'candle' | 'pie' | 'radar' 等)
    - SeriesConfig:数据系列配置
    - AxisConfig:坐标轴配置(X轴、Y轴)
    - ExtraConfig:各种图表的额外配置
    - ColorConfig:颜色配置
-3. 为 u-charts 类添加类型定义
+3. 为各模块添加类型定义:
+   - utils/ 模块的函数类型
+   - data-processing/ 模块的函数类型
+   - renderers/ 模块的函数类型
+   - uCharts 和 uChartsEvent 类的类型
 4. 导出所有类型供使用者使用
+5. 创建 types/index.ts 统一导出所有类型
 
 **验收标准:**
 - [ ] 所有配置选项都有对应的类型定义