Story 016.007: 搬迁遗漏的辅助函数完成模块化

Status

Draft

Story

作为图表库开发者， 我想要 将 u-charts 核心库中遗漏的辅助函数搬迁到独立模块，以便确保所有代码都被正确模块化，避免在核心类中包含大量辅助函数，提高代码的可维护性和可测试性。

背景

在实施故事 016.006（搬迁核心类）时，发现原始 u-charts.ts 中有大量辅助函数没有被之前的模块化故事覆盖。这些函数包括：

索引查找函数：findCurrentIndex, findBarChartCurrentIndex, findLegendIndex, findPieChartCurrentIndex, findRadarChartCurrentIndex, findFunnelChartCurrentIndex, findWordChartCurrentIndex, findMapChartCurrentIndex, findRoseChartCurrentIndex
区域判断函数：isInExactLegendArea, isInExactChartArea, isInExactPieChartArea
数据计算函数：getSeriesDataItem, filterSeries, splitPoints, getMaxTextListLength, getRadarCoordinateSeries
图例数据处理：calLegendData, getPieTextMaxLength
Tooltip 相关：getCandleToolTipData（已存在于 data-processing 但未导出）
坐标转换函数：pointToCoordinate, isPoiWithinPoly（地图相关）
数据修正函数：fixColumeData, fixBarData, fixColumeMeterData, fixColumeStackData, fixBarStackData
其他辅助函数：getXAxisTextList, getYAxisTextList, calTooltipYAxisData, calMarkLineData, contextRotate, normalInt, collisionNew, getWordCloudPoint

Acceptance Criteria

所有遗漏的辅助函数搬迁到合适的模块中
每个函数都有完整的 TypeScript 类型注解
类型检查通过（pnpm typecheck）
包可以成功构建（pnpm build）
模块间依赖关系合理，无循环依赖
代码逻辑与原始 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

TypeScript: 5.4.5
Node.js: 20.18.3
包管理器: pnpm workspace

项目结构指南

来源: 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

技术约束

搬迁原则: 保持代码逻辑完全不变，只改变文件组织方式
类型注解: 为所有函数参数和返回值添加类型注解
类型安全: 避免使用 any 类型（除非必要）
模块依赖: 确保导入所有必要的依赖模块
循环依赖: 避免模块间循环依赖

验证标准

完成本故事后，应该满足:

✅ src/lib/helper-functions/ 目录下所有文件存在
✅ 所有辅助函数都有完整类型注解
✅ src/index.ts 正确导出所有辅助函数
✅ 运行 pnpm typecheck 无类型错误
✅ 运行 pnpm build 成功
✅ 模块间依赖关系合理，无循环依赖
✅ 代码逻辑与原始 u-charts.ts 完全一致

不包含在本故事中的工作

以下工作不在本故事范围内:

❌ React 组件封装（故事 016.008 或后续）
❌ 创建使用示例和文档（后续故事）
❌ 创建测试套件（后续故事）

Testing

测试框架: Jest

测试位置: tests/ 目录

测试要求:

创建基础测试验证辅助函数的正确导入和导出
测试覆盖率目标: 基础测试即可
Mock 相关依赖（如 Canvas 上下文等）

测试命令:

# 运行所有测试
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 代理在审查完成后填写

016.007.story.md 13 KB История Исходник

Story 016.007: 搬迁遗漏的辅助函数完成模块化

Status

Story

背景

Acceptance Criteria

Tasks / Subtasks

Dev Notes

前置故事见解

遗漏函数列表

索引查找函数 (9个)

区域判断函数 (3个)

数据辅助函数 (5个)

图例相关函数 (2个)

坐标转换函数 (7个)

数据修正函数 (5个)

其他辅助函数 (8个)

模块结构规划

技术栈要求

项目结构指南

技术约束

验证标准

不包含在本故事中的工作

Testing

Change Log

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

016.007.story.md 13 KB

История Исходник