|
@@ -0,0 +1,338 @@
|
|
|
|
|
+# <!-- Powered by BMAD™ Core -->
|
|
|
|
|
+
|
|
|
|
|
+# Story 016.007: 搬迁遗漏的辅助函数完成模块化
|
|
|
|
|
+
|
|
|
|
|
+## Status
|
|
|
|
|
+
|
|
|
|
|
+Draft
|
|
|
|
|
+
|
|
|
|
|
+## Story
|
|
|
|
|
+
|
|
|
|
|
+**作为** 图表库开发者,
|
|
|
|
|
+**我想要** 将 u-charts 核心库中遗漏的辅助函数**搬迁**到独立模块,
|
|
|
|
|
+**以便** 确保所有代码都被正确模块化,避免在核心类中包含大量辅助函数,提高代码的可维护性和可测试性。
|
|
|
|
|
+
|
|
|
|
|
+## 背景
|
|
|
|
|
+
|
|
|
|
|
+在实施故事 016.006(搬迁核心类)时,发现原始 u-charts.ts 中有大量辅助函数没有被之前的模块化故事覆盖。这些函数包括:
|
|
|
|
|
+
|
|
|
|
|
+1. **索引查找函数**:`findCurrentIndex`, `findBarChartCurrentIndex`, `findLegendIndex`, `findPieChartCurrentIndex`, `findRadarChartCurrentIndex`, `findFunnelChartCurrentIndex`, `findWordChartCurrentIndex`, `findMapChartCurrentIndex`, `findRoseChartCurrentIndex`
|
|
|
|
|
+
|
|
|
|
|
+2. **区域判断函数**:`isInExactLegendArea`, `isInExactChartArea`, `isInExactPieChartArea`
|
|
|
|
|
+
|
|
|
|
|
+3. **数据计算函数**:`getSeriesDataItem`, `filterSeries`, `splitPoints`, `getMaxTextListLength`, `getRadarCoordinateSeries`
|
|
|
|
|
+
|
|
|
|
|
+4. **图例数据处理**:`calLegendData`, `getPieTextMaxLength`
|
|
|
|
|
+
|
|
|
|
|
+5. **Tooltip 相关**:`getCandleToolTipData`(已存在于 data-processing 但未导出)
|
|
|
|
|
+
|
|
|
|
|
+6. **坐标转换函数**:`pointToCoordinate`, `isPoiWithinPoly`(地图相关)
|
|
|
|
|
+
|
|
|
|
|
+7. **数据修正函数**:`fixColumeData`, `fixBarData`, `fixColumeMeterData`, `fixColumeStackData`, `fixBarStackData`
|
|
|
|
|
+
|
|
|
|
|
+8. **其他辅助函数**:`getXAxisTextList`, `getYAxisTextList`, `calTooltipYAxisData`, `calMarkLineData`, `contextRotate`, `normalInt`, `collisionNew`, `getWordCloudPoint`
|
|
|
|
|
+
|
|
|
|
|
+## Acceptance Criteria
|
|
|
|
|
+
|
|
|
|
|
+1. 所有遗漏的辅助函数搬迁到合适的模块中
|
|
|
|
|
+2. 每个函数都有完整的 TypeScript 类型注解
|
|
|
|
|
+3. 类型检查通过(`pnpm typecheck`)
|
|
|
|
|
+4. 包可以成功构建(`pnpm build`)
|
|
|
|
|
+5. 模块间依赖关系合理,无循环依赖
|
|
|
|
|
+6. 代码逻辑与原始 u-charts.ts 完全一致
|
|
|
|
|
+
|
|
|
|
|
+## Tasks / Subtasks
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 1: 分析并分类遗漏的辅助函数 (AC: 1)
|
|
|
|
|
+ - [ ] 1.1 列出所有遗漏的辅助函数
|
|
|
|
|
+ - [ ] 1.2 按功能分类(索引查找、区域判断、数据计算等)
|
|
|
|
|
+ - [ ] 1.3 确定每个函数应该归属的模块
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 2: 创建/扩展 helper-functions 模块 (AC: 1)
|
|
|
|
|
+ - [ ] 2.1 创建 `src/lib/helper-functions/` 目录
|
|
|
|
|
+ - [ ] 2.2 创建 `index-finders.ts` - 索引查找函数
|
|
|
|
|
+ - [ ] 2.3 创建 `area-checkers.ts` - 区域判断函数
|
|
|
|
|
+ - [ ] 2.4 创建 `data-helpers.ts` - 数据辅助函数
|
|
|
|
|
+ - [ ] 2.5 创建 `legend-helpers.ts` - 图例相关函数
|
|
|
|
|
+ - [ ] 2.6 创建 `coordinate-helpers.ts` - 坐标转换函数
|
|
|
|
|
+ - [ ] 2.7 创建 `data-fixers.ts` - 数据修正函数
|
|
|
|
|
+ - [ ] 2.8 创建 `misc-helpers.ts` - 其他辅助函数
|
|
|
|
|
+ - [ ] 2.9 创建 `index.ts` - 统一导出
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 3: 搬迁索引查找函数 (AC: 2, 3, 6)
|
|
|
|
|
+ - [ ] 3.1 搬迁 `findCurrentIndex` 并添加类型注解
|
|
|
|
|
+ - [ ] 3.2 搬迁 `findBarChartCurrentIndex` 并添加类型注解
|
|
|
|
|
+ - [ ] 3.3 搬迁 `findLegendIndex` 并添加类型注解
|
|
|
|
|
+ - [ ] 3.4 搬迁 `findPieChartCurrentIndex` 并添加类型注解
|
|
|
|
|
+ - [ ] 3.5 搬迁 `findRadarChartCurrentIndex` 并添加类型注解
|
|
|
|
|
+ - [ ] 3.6 搬迁 `findFunnelChartCurrentIndex` 并添加类型注解
|
|
|
|
|
+ - [ ] 3.7 搬迁 `findWordChartCurrentIndex` 并添加类型注解
|
|
|
|
|
+ - [ ] 3.8 搬迁 `findMapChartCurrentIndex` 并添加类型注解
|
|
|
|
|
+ - [ ] 3.9 搬迁 `findRoseChartCurrentIndex` 并添加类型注解
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 4: 搬迁区域判断函数 (AC: 2, 3, 6)
|
|
|
|
|
+ - [ ] 4.1 搬迁 `isInExactLegendArea` 并添加类型注解
|
|
|
|
|
+ - [ ] 4.2 搬迁 `isInExactChartArea` 并添加类型注解
|
|
|
|
|
+ - [ ] 4.3 搬迁 `isInExactPieChartArea` 并添加类型注解
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 5: 搬迁数据辅助函数 (AC: 2, 3, 6)
|
|
|
|
|
+ - [ ] 5.1 搬迁 `getSeriesDataItem` 并添加类型注解
|
|
|
|
|
+ - [ ] 5.2 搬迁 `filterSeries` 并添加类型注解
|
|
|
|
|
+ - [ ] 5.3 搬迁 `splitPoints` 并添加类型注解
|
|
|
|
|
+ - [ ] 5.4 搬迁 `getMaxTextListLength` 并添加类型注解
|
|
|
|
|
+ - [ ] 5.5 搬迁 `getRadarCoordinateSeries` 并添加类型注解
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 6: 搬迁图例相关函数 (AC: 2, 3, 6)
|
|
|
|
|
+ - [ ] 6.1 搬迁 `calLegendData` 并添加类型注解
|
|
|
|
|
+ - [ ] 6.2 搬迁 `getPieTextMaxLength` 并添加类型注解
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 7: 搬迁坐标转换函数 (AC: 2, 3, 6)
|
|
|
|
|
+ - [ ] 7.1 搬迁 `pointToCoordinate` 并添加类型注解
|
|
|
|
|
+ - [ ] 7.2 搬迁 `isPoiWithinPoly` 并添加类型注解
|
|
|
|
|
+ - [ ] 7.3 搬迁 `lonlat2mercator` 并添加类型注解
|
|
|
|
|
+ - [ ] 7.4 搬迁 `mercator2lonlat` 并添加类型注解
|
|
|
|
|
+ - [ ] 7.5 搬迁 `getBoundingBox` 并添加类型注解
|
|
|
|
|
+ - [ ] 7.6 搬迁 `coordinateToPoint` 并添加类型注解
|
|
|
|
|
+ - [ ] 7.7 搬迁 `isRayIntersectsSegment` 并添加类型注解
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 8: 搬迁数据修正函数 (AC: 2, 3, 6)
|
|
|
|
|
+ - [ ] 8.1 搬迁 `fixColumeData` 并添加类型注解
|
|
|
|
|
+ - [ ] 8.2 搬迁 `fixBarData` 并添加类型注解
|
|
|
|
|
+ - [ ] 8.3 搬迁 `fixColumeMeterData` 并添加类型注解
|
|
|
|
|
+ - [ ] 8.4 搬迁 `fixColumeStackData` 并添加类型注解
|
|
|
|
|
+ - [ ] 8.5 搬迁 `fixBarStackData` 并添加类型注解
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 9: 搬迁其他辅助函数 (AC: 2, 3, 6)
|
|
|
|
|
+ - [ ] 9.1 搬迁 `getXAxisTextList` 并添加类型注解
|
|
|
|
|
+ - [ ] 9.2 搬迁 `getYAxisTextList` 并添加类型注解
|
|
|
|
|
+ - [ ] 9.3 搬迁 `calTooltipYAxisData` 并添加类型注解
|
|
|
|
|
+ - [ ] 9.4 搬迁 `calMarkLineData` 并添加类型注解
|
|
|
|
|
+ - [ ] 9.5 搬迁 `contextRotate` 并添加类型注解
|
|
|
|
|
+ - [ ] 9.6 搬迁 `normalInt` 并添加类型注解
|
|
|
|
|
+ - [ ] 9.7 搬迁 `collisionNew` 并添加类型注解
|
|
|
|
|
+ - [ ] 9.8 搬迁 `getWordCloudPoint` 并添加类型注解
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 10: 更新 src/index.ts 导出配置 (AC: 3, 4)
|
|
|
|
|
+ - [ ] 10.1 导出所有新的辅助函数
|
|
|
|
|
+ - [ ] 10.2 导出相关的类型定义
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Task 11: 验证搬迁结果 (AC: 3, 4, 5)
|
|
|
|
|
+ - [ ] 11.1 确保所有导出正确
|
|
|
|
|
+ - [ ] 11.2 运行类型检查验证类型注解正确(`pnpm typecheck`)
|
|
|
|
|
+ - [ ] 11.3 运行构建验证生成 .d.ts 文件(`pnpm build`)
|
|
|
|
|
+ - [ ] 11.4 验证模块间无循环依赖
|
|
|
|
|
+
|
|
|
|
|
+## Dev Notes
|
|
|
|
|
+
|
|
|
|
|
+### 前置故事见解
|
|
|
|
|
+
|
|
|
|
|
+**故事 016.001 完成状态**:
|
|
|
|
|
+- ✅ 已创建 `mini-charts` 包基础结构
|
|
|
|
|
+- ✅ 已迁移 u-charts 核心库到 `src/lib/u-charts.ts`(7680行代码)
|
|
|
|
|
+
|
|
|
|
|
+**故事 016.002 完成状态**:
|
|
|
|
|
+- ✅ 已创建 `config.ts` 和 `utils/` 目录及所有子模块文件
|
|
|
|
|
+- ✅ 搬迁了基础工具函数(color, math, coordinate, text, collision, misc)
|
|
|
|
|
+
|
|
|
|
|
+**故事 016.003 完成状态**:
|
|
|
|
|
+- ✅ 已创建 `data-processing/` 目录
|
|
|
|
|
+- ✅ 搬迁了数据处理函数(series-calculator, axis-calculator, categories-calculator, tooltip-calculator)
|
|
|
|
|
+
|
|
|
|
|
+**故事 016.004 完成状态**:
|
|
|
|
|
+- ✅ 已创建 `charts-data/` 目录
|
|
|
|
|
+- ✅ 搬迁了图表数据点计算函数
|
|
|
|
|
+
|
|
|
|
|
+**故事 016.005 完成状态**:
|
|
|
|
|
+- ✅ 已创建 `renderers/` 目录
|
|
|
|
|
+- ✅ 搬迁了绘制函数
|
|
|
|
|
+
|
|
|
|
|
+**故事 016.006 进行中**:
|
|
|
|
|
+- ⚠️ 发现大量辅助函数未被搬迁
|
|
|
|
|
+- ⚠️ 这些函数是 uCharts 主类正常工作所必需的依赖
|
|
|
|
|
+
|
|
|
|
|
+### 遗漏函数列表
|
|
|
|
|
+
|
|
|
|
|
+根据分析,以下函数需要搬迁:
|
|
|
|
|
+
|
|
|
|
|
+#### 索引查找函数 (9个)
|
|
|
|
|
+- `findCurrentIndex` - 查找当前数据索引
|
|
|
|
|
+- `findBarChartCurrentIndex` - 查找柱状图当前索引
|
|
|
|
|
+- `findLegendIndex` - 查找图例索引
|
|
|
|
|
+- `findPieChartCurrentIndex` - 查找饼图当前索引
|
|
|
|
|
+- `findRadarChartCurrentIndex` - 查找雷达图当前索引
|
|
|
|
|
+- `findFunnelChartCurrentIndex` - 查找漏斗图当前索引
|
|
|
|
|
+- `findWordChartCurrentIndex` - 查找词云图当前索引
|
|
|
|
|
+- `findMapChartCurrentIndex` - 查找地图当前索引
|
|
|
|
|
+- `findRoseChartCurrentIndex` - 查找玫瑰图当前索引
|
|
|
|
|
+
|
|
|
|
|
+#### 区域判断函数 (3个)
|
|
|
|
|
+- `isInExactLegendArea` - 判断是否在图例区域
|
|
|
|
|
+- `isInExactChartArea` - 判断是否在图表区域
|
|
|
|
|
+- `isInExactPieChartArea` - 判断是否在饼图区域
|
|
|
|
|
+
|
|
|
|
|
+#### 数据辅助函数 (5个)
|
|
|
|
|
+- `getSeriesDataItem` - 获取系列数据项
|
|
|
|
|
+- `filterSeries` - 过滤系列数据
|
|
|
|
|
+- `splitPoints` - 分割点
|
|
|
|
|
+- `getMaxTextListLength` - 获取最大文本列表长度
|
|
|
|
|
+- `getRadarCoordinateSeries` - 获取雷达坐标系列
|
|
|
|
|
+
|
|
|
|
|
+#### 图例相关函数 (2个)
|
|
|
|
|
+- `calLegendData` - 计算图例数据
|
|
|
|
|
+- `getPieTextMaxLength` - 获取饼图文本最大长度
|
|
|
|
|
+
|
|
|
|
|
+#### 坐标转换函数 (7个)
|
|
|
|
|
+- `pointToCoordinate` - 点转坐标
|
|
|
|
|
+- `isPoiWithinPoly` - 判断点是否在多边形内
|
|
|
|
|
+- `lonlat2mercator` - 经纬度转墨卡托
|
|
|
|
|
+- `mercator2lonlat` - 墨卡托转经纬度
|
|
|
|
|
+- `getBoundingBox` - 获取边界框
|
|
|
|
|
+- `coordinateToPoint` - 坐标转点
|
|
|
|
|
+- `isRayIntersectsSegment` - 判断射线是否与线段相交
|
|
|
|
|
+
|
|
|
|
|
+#### 数据修正函数 (5个)
|
|
|
|
|
+- `fixColumeData` - 修正柱状图数据
|
|
|
|
|
+- `fixBarData` - 修正条形图数据
|
|
|
|
|
+- `fixColumeMeterData` - 修正仪表柱状图数据
|
|
|
|
|
+- `fixColumeStackData` - 修正堆叠柱状图数据
|
|
|
|
|
+- `fixBarStackData` - 修正堆叠条形图数据
|
|
|
|
|
+
|
|
|
|
|
+#### 其他辅助函数 (8个)
|
|
|
|
|
+- `getXAxisTextList` - 获取X轴文本列表
|
|
|
|
|
+- `getYAxisTextList` - 获取Y轴文本列表
|
|
|
|
|
+- `calTooltipYAxisData` - 计算提示框Y轴数据
|
|
|
|
|
+- `calMarkLineData` - 计算标记线数据
|
|
|
|
|
+- `contextRotate` - 上下文旋转
|
|
|
|
|
+- `normalInt` - 标准化整数
|
|
|
|
|
+- `collisionNew` - 新碰撞检测
|
|
|
|
|
+- `getWordCloudPoint` - 获取词云点
|
|
|
|
|
+
|
|
|
|
|
+### 模块结构规划
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+src/lib/helper-functions/
|
|
|
|
|
+├── index-finders.ts # 索引查找函数
|
|
|
|
|
+├── area-checkers.ts # 区域判断函数
|
|
|
|
|
+├── data-helpers.ts # 数据辅助函数
|
|
|
|
|
+├── legend-helpers.ts # 图例相关函数
|
|
|
|
|
+├── coordinate-helpers.ts # 坐标转换函数
|
|
|
|
|
+├── data-fixers.ts # 数据修正函数
|
|
|
|
|
+├── misc-helpers.ts # 其他辅助函数
|
|
|
|
|
+└── index.ts # 统一导出
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 技术栈要求
|
|
|
|
|
+
|
|
|
|
|
+**来源**: [tech-stack.md](../../architecture/tech-stack.md)
|
|
|
|
|
+
|
|
|
|
|
+- **TypeScript**: 5.4.5
|
|
|
|
|
+- **Node.js**: 20.18.3
|
|
|
|
|
+- **包管理器**: pnpm workspace
|
|
|
|
|
+
|
|
|
|
|
+### 项目结构指南
|
|
|
|
|
+
|
|
|
|
|
+**来源**: [source-tree.md](../../architecture/source-tree.md)
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+mini-ui-packages/
|
|
|
|
|
+└── mini-charts/ # mini-charts 包
|
|
|
|
|
+ ├── src/
|
|
|
|
|
+ │ ├── index.ts # 主入口文件(需要更新)
|
|
|
|
|
+ │ └── lib/
|
|
|
|
|
+ │ ├── u-charts.ts # u-charts 核心库(搬迁后删除)
|
|
|
|
|
+ │ ├── config.ts # [已完成] 配置对象
|
|
|
|
|
+ │ ├── utils/ # [已完成] 工具函数目录
|
|
|
|
|
+ │ ├── data-processing/ # [已完成] 数据处理模块
|
|
|
|
|
+ │ ├── charts-data/ # [已完成] 图表数据点计算模块
|
|
|
|
|
+ │ ├── renderers/ # [已完成] 绘制函数模块
|
|
|
|
|
+ │ ├── charts/ # [进行中] 核心类模块
|
|
|
|
|
+ │ └── helper-functions/ # [本故事创建] 辅助函数模块
|
|
|
|
|
+ │ ├── index-finders.ts
|
|
|
|
|
+ │ ├── area-checkers.ts
|
|
|
|
|
+ │ ├── data-helpers.ts
|
|
|
|
|
+ │ ├── legend-helpers.ts
|
|
|
|
|
+ │ ├── coordinate-helpers.ts
|
|
|
|
|
+ │ ├── data-fixers.ts
|
|
|
|
|
+ │ ├── misc-helpers.ts
|
|
|
|
|
+ │ └── index.ts
|
|
|
|
|
+ ├── tests/
|
|
|
|
|
+ ├── package.json
|
|
|
|
|
+ ├── tsconfig.json
|
|
|
|
|
+ └── jest.config.cjs
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 技术约束
|
|
|
|
|
+
|
|
|
|
|
+1. **搬迁原则**: 保持代码逻辑完全不变,只改变文件组织方式
|
|
|
|
|
+2. **类型注解**: 为所有函数参数和返回值添加类型注解
|
|
|
|
|
+3. **类型安全**: 避免使用 `any` 类型(除非必要)
|
|
|
|
|
+4. **模块依赖**: 确保导入所有必要的依赖模块
|
|
|
|
|
+5. **循环依赖**: 避免模块间循环依赖
|
|
|
|
|
+
|
|
|
|
|
+### 验证标准
|
|
|
|
|
+
|
|
|
|
|
+完成本故事后,应该满足:
|
|
|
|
|
+1. ✅ `src/lib/helper-functions/` 目录下所有文件存在
|
|
|
|
|
+2. ✅ 所有辅助函数都有完整类型注解
|
|
|
|
|
+3. ✅ `src/index.ts` 正确导出所有辅助函数
|
|
|
|
|
+4. ✅ 运行 `pnpm typecheck` 无类型错误
|
|
|
|
|
+5. ✅ 运行 `pnpm build` 成功
|
|
|
|
|
+6. ✅ 模块间依赖关系合理,无循环依赖
|
|
|
|
|
+7. ✅ 代码逻辑与原始 u-charts.ts 完全一致
|
|
|
|
|
+
|
|
|
|
|
+### 不包含在本故事中的工作
|
|
|
|
|
+
|
|
|
|
|
+以下工作**不在**本故事范围内:
|
|
|
|
|
+- ❌ React 组件封装(故事 016.008 或后续)
|
|
|
|
|
+- ❌ 创建使用示例和文档(后续故事)
|
|
|
|
|
+- ❌ 创建测试套件(后续故事)
|
|
|
|
|
+
|
|
|
|
|
+## Testing
|
|
|
|
|
+
|
|
|
|
|
+**测试框架**: Jest
|
|
|
|
|
+
|
|
|
|
|
+**测试位置**: `tests/` 目录
|
|
|
|
|
+
|
|
|
|
|
+**测试要求**:
|
|
|
|
|
+1. 创建基础测试验证辅助函数的正确导入和导出
|
|
|
|
|
+2. 测试覆盖率目标: 基础测试即可
|
|
|
|
|
+3. Mock 相关依赖(如 Canvas 上下文等)
|
|
|
|
|
+
|
|
|
|
|
+**测试命令**:
|
|
|
|
|
+```bash
|
|
|
|
|
+# 运行所有测试
|
|
|
|
|
+pnpm test
|
|
|
|
|
+
|
|
|
|
|
+# 运行特定测试
|
|
|
|
|
+pnpm test --testNamePattern "辅助函数测试"
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## Change Log
|
|
|
|
|
+
|
|
|
|
|
+| Date | Version | Description | Author |
|
|
|
|
|
+|------|---------|-------------|--------|
|
|
|
|
|
+| 2025-12-24 | 1.0 | 创建故事文档 | James (Dev Agent) |
|
|
|
|
|
+
|
|
|
|
|
+## Dev Agent Record
|
|
|
|
|
+
|
|
|
|
|
+*此部分由开发代理在实施过程中填写*
|
|
|
|
|
+
|
|
|
|
|
+### Agent Model Used
|
|
|
|
|
+
|
|
|
|
|
+*待开发代理填写*
|
|
|
|
|
+
|
|
|
|
|
+### Debug Log References
|
|
|
|
|
+
|
|
|
|
|
+*待开发代理填写*
|
|
|
|
|
+
|
|
|
|
|
+### Completion Notes List
|
|
|
|
|
+
|
|
|
|
|
+*待开发代理填写*
|
|
|
|
|
+
|
|
|
|
|
+### File List
|
|
|
|
|
+
|
|
|
|
|
+*待开发代理填写*
|
|
|
|
|
+
|
|
|
|
|
+## QA Results
|
|
|
|
|
+
|
|
|
|
|
+*此部分由 QA 代理在审查完成后填写*
|