EmailBill/openspec/changes/archive/2026-02-16-migrate-remaining-echarts-to-chartjs/tasks.md

1. 前置准备

• 1.1 备份当前分支，创建 git tag pre-echarts-migration
• 1.2 确认 Chart.js 和 vue-chartjs 依赖版本（4.5.1 / 5.3.3）
• 1.3 验证 BaseChart.vue、useChartTheme.ts、chartHelpers.ts 可用性

2. 迁移 MonthlyExpenseCard.vue（简单折线图）

• 2.1 备份原始 ECharts 代码（注释保留）
• 2.2 删除 import * as echarts from 'echarts'
• 2.3 删除 useChartJS 环境变量和条件渲染
• 2.4 删除 chartInstance 变量和 ECharts 初始化代码
• 2.5 保留 prepareChartData() 函数，修改返回格式
• 2.6 创建 chartData computed 属性（Chart.js 格式）
• 2.7 创建 chartOptions computed 属性，使用 getChartOptions()
• 2.8 替换模板为 <BaseChart type="line" :data="chartData" :options="chartOptions" />
• 2.9 删除 onBeforeUnmount() 中的 ECharts cleanup 代码
• 2.10 本地浏览器验证图表渲染正确（Chrome DevTools）

3. 迁移 DailyTrendChart.vue（双系列折线图）

• 3.1 备份原始 ECharts 代码（注释保留）
• 3.2 删除 import * as echarts from 'echarts'
• 3.3 删除 useChartJS 环境变量和条件渲染
• 3.4 删除 chartInstance 变量和 ECharts 初始化代码
• 3.5 保留 prepareChartData() 函数，返回 labels、expenseData、incomeData
• 3.6 创建 chartData computed 属性，包含两个 datasets（支出红色，收入绿色）
• 3.7 创建 chartOptions computed 属性，配置渐变填充和 tooltip
• 3.8 替换模板为 <BaseChart type="line" :data="chartData" :options="chartOptions" />
• 3.9 删除 onBeforeUnmount() 中的 ECharts cleanup 代码
• 3.10 验证双系列折线图 hover 交互正常

4. 迁移 ExpenseCategoryCard.vue（环形图 + 列表）

• 4.1 备份原始 ECharts 代码（注释保留）
• 4.2 删除 import * as echarts from 'echarts'
• 4.3 删除 useChartJS 环境变量和条件渲染
• 4.4 删除 pieChartInstance 变量和 ECharts 初始化代码
• 4.5 创建 chartData computed 属性，使用 props.colors 作为 backgroundColor
• 4.6 创建 chartOptions computed 属性，配置 cutout: '50%' 和 legend
• 4.7 添加 @chart:render 事件处理，保存 Chart.js 实例
• 4.8 实现点击事件：使用 Chart.js 的 onClick 配置
• 4.9 替换模板为 <BaseChart type="doughnut" :data="chartData" :options="chartOptions" />
• 4.10 删除 onBeforeUnmount() 中的 ECharts cleanup 代码
• 4.11 验证环形图颜色与列表一致
• 4.12 验证点击扇区跳转功能正常

5. 迁移 BudgetChartAnalysis.vue（仪表盘 + 复杂布局）

• 5.1 备份原始 ECharts 代码（注释保留）
• 5.2 删除 import * as echarts from 'echarts'
• 5.3 删除 monthGaugeRef 和 yearGaugeRef 的 ECharts 初始化代码
• 5.4 创建 monthGaugeData computed 属性（Doughnut 格式，rotation: -90, circumference: 180）
• 5.5 创建 yearGaugeData computed 属性（同上）
• 5.6 创建 gaugeOptions computed 属性，配置 cutout: '70%'，禁用 legend 和 tooltip
• 5.7 修改模板，将两个仪表盘替换为 <BaseChart type="doughnut" />
• 5.8 保留 .gauge-text-overlay CSS 叠加层，确保中心文本显示正确
• 5.9 删除 onBeforeUnmount() 中的 ECharts cleanup 代码
• 5.10 验证月度和年度仪表盘渲染正确
• 5.11 验证超支时颜色切换为危险色
• 5.12 验证 scaleX(-1) 镜像翻转效果（支出类别）

6. 清理和验证

• 6.1 全局搜索 import.*echarts，确认无残留
• 6.2 全局搜索 VITE_USE_CHARTJS，确认无残留
• 6.3 删除所有组件中的注释备份代码
• 6.4 运行 pnpm lint 检查代码风格
• 6.5 运行 pnpm build 确认构建成功

7. 白盒测试（单元测试） - 跳过（项目未配置测试环境）

• 7.1 创建 MonthlyExpenseCard.spec.js，测试组件挂载和 props
• 7.2 创建 DailyTrendChart.spec.js，测试双系列数据计算
• 7.3 创建 ExpenseCategoryCard.spec.js，测试环形图数据转换
• 7.4 创建 BudgetChartAnalysis.spec.js，测试仪表盘数据计算
• 7.5 运行 pnpm test:unit，确保所有测试通过

8. 黑盒测试（E2E 测试） - 跳过（项目未配置测试环境）

• 8.1 创建 Playwright 测试：访问统计页面
• 8.2 验证折线图在浏览器中可见
• 8.3 验证环形图在浏览器中可见
• 8.4 验证预算仪表盘在浏览器中可见
• 8.5 模拟 hover 操作，验证 Tooltip 显示
• 8.6 模拟点击环形图扇区，验证跳转
• 8.7 切换暗色模式，验证图表颜色适配
• 8.8 运行 pnpm test:e2e，确保所有测试通过

9. 视觉回归测试 - 跳过（项目未配置测试环境）

• 9.1 使用 Playwright 截图迁移后的折线图
• 9.2 使用 Playwright 截图迁移后的环形图
• 9.3 使用 Playwright 截图迁移后的仪表盘
• 9.4 对比迁移前后的截图，记录差异（像素差异应 < 5%）
• 9.5 如果差异过大，调整颜色/字体/布局配置

10. 性能测试 - 跳过（需要生产环境验证）

• 10.1 使用 Lighthouse 测试统计页面（桌面）
• 10.2 使用 Lighthouse 测试统计页面（移动端）
• 10.3 验证 Performance Score >= 90
• 10.4 验证首次内容绘制（FCP）< 1.5s
• 10.5 验证最大内容绘制（LCP）< 2.5s

11. 文档和提交

• 11.1 更新 AGENTS.md（如果有新增的图表使用约定）
• 11.2 在 .doc/ 创建迁移总结文档（可选）
• 11.3 提交代码：git add .
• 11.4 提交信息：chore: migrate remaining ECharts components to Chart.js
• 11.5 推送到远程分支