# Chart.js 迁移完成总结

**日期**: 2026-02-16  
**任务**: 将 EmailBill 项目中剩余的 ECharts 图表迁移到 Chart.js

## 迁移的组件

### 1. ExpenseCategoryCard.vue
**文件路径**: `Web/src/views/statisticsV2/modules/ExpenseCategoryCard.vue`

**变更内容**:
- ✅ 删除 `import * as echarts from 'echarts'`
- ✅ 删除 `useChartJS` 环境变量和相关的 v-if/v-else 条件渲染
- ✅ 删除 `pieChartInstance` 变量和所有 ECharts 初始化代码
- ✅ 简化模板，只保留 `<BaseChart type="doughnut" />`
- ✅ 删除 `onBeforeUnmount` 中的 ECharts cleanup
- ✅ 删除 `watch` 和 `renderPieChart()` 函数
- ✅ 移除 `if (!useChartJS) return null` 判断，chartData 和 chartOptions 始终返回有效值

**保留功能**:
- ✅ Doughnut 图表（支出分类环形图）
- ✅ 数据预处理逻辑（`prepareChartData()`）
- ✅ 分类列表展示
- ✅ 点击事件（category-click）

### 2. BudgetChartAnalysis.vue
**文件路径**: `Web/src/components/Budget/BudgetChartAnalysis.vue`

**变更内容**:
- ✅ 删除 `import * as echarts from 'echarts'`
- ✅ 引入 `BaseChart` 和 `useChartTheme` composable
- ✅ 引入 `chartjsGaugePlugin` 用于仪表盘中心文本显示
- ✅ 删除所有 ECharts 相关的 ref 变量（`monthGaugeRef`, `yearGaugeRef`, 等）
- ✅ 删除所有 ECharts 实例变量（`monthGaugeChart`, `varianceChart`, 等）
- ✅ 替换仪表盘为 Chart.js Doughnut 图表（使用 gaugePlugin）
- ✅ 替换燃尽图为 Chart.js Line 图表
- ✅ 替换偏差分析为 Chart.js Bar 图表（水平方向）
- ✅ 删除所有 ECharts 初始化和更新函数
- ✅ 删除 `onBeforeUnmount` 中的 ECharts cleanup
- ✅ 删除 `handleResize` 和相关的 resize 事件监听

**实现的图表**:

#### 月度/年度仪表盘（Gauge）
- 使用 Doughnut 图表 + gaugePlugin
- 半圆形进度条（circumference: 180, rotation: 270）
- 中心文字覆盖层显示余额/差额
- 支持超支场景（红色显示）
- 颜色逻辑：
  - 支出：满格绿色 → 消耗变红
  - 收入：空红色 → 积累变绿

#### 月度/年度燃尽图（Burndown）
- 使用 Line 图表
- 两条线：理想线（虚线）+ 实际线（实线）
- 支出模式：燃尽图（向下走）
- 收入模式：积累图（向上走）
- 支持趋势数据（`props.overallStats.month.trend`）
- Fallback 到线性估算

#### 偏差分析（Variance）
- 使用 Bar 图表（水平方向，`indexAxis: 'y'`）
- 正值（超支）红色，负值（结余）绿色
- 动态高度计算（30px per item）
- 排序：年度在前，月度在后，各自按偏差绝对值排序
- Tooltip 显示详细信息（预算/实际/偏差）

**数据处理逻辑**:
- ✅ 保留所有业务逻辑（日期计算、趋势数据、进度计算）
- ✅ 使用 computed 属性实现响应式更新
- ✅ 格式化函数 `formatMoney()` 保持一致

## 技术栈变更

### 移除
- ❌ ECharts 5.x
- ❌ 手动管理图表实例
- ❌ 手动 resize 监听
- ❌ 手动 dispose cleanup

### 使用
- ✅ Chart.js 4.5+
- ✅ vue-chartjs 5.3+
- ✅ BaseChart 通用组件
- ✅ useChartTheme composable（主题管理）
- ✅ chartjsGaugePlugin（仪表盘插件）
- ✅ Vue 响应式系统（computed）

## 构建验证

```bash
cd Web && pnpm build
```

**结果**: ✅ 构建成功

- 无 TypeScript 错误
- 无 ESLint 错误
- 无 Vue 编译错误
- 产物大小正常

## 性能优势

1. **包体积减小**
   - ECharts 较大（~300KB gzipped）
   - Chart.js 较小（~60KB gzipped）

2. **更好的 Vue 集成**
   - 使用 Vue 响应式系统
   - 无需手动管理实例生命周期
   - 自动 resize 和 cleanup

3. **一致的 API**
   - 所有图表使用统一的 BaseChart 组件
   - 统一的主题配置（useChartTheme）
   - 统一的颜色变量（CSS Variables）

## 后续工作

- [x] 移除 VITE_USE_CHARTJS 环境变量（已不需要）
- [x] 清理所有 ECharts 相关代码
- [ ] 测试所有图表功能（手动测试）
- [ ] 验证暗色模式下的显示效果
- [ ] 验证移动端触控交互

## 注意事项

1. **仪表盘中心文本**
   - 使用 CSS 绝对定位的 `.gauge-text-overlay` 显示中心文本
   - 不使用 gaugePlugin 的 centerText（因为需要 scaleX(-1) 翻转）

2. **偏差分析图表**
   - 使用 `_meta` 字段传递额外数据到 tooltip
   - 颜色根据 `activeTab`（支出/收入）动态计算

3. **响应式更新**
   - 所有数据通过 computed 属性计算
   - 无需手动调用 update 或 resize
   - BaseChart 自动处理 props 变化

## 参考文档

- [Chart.js 官方文档](https://www.chartjs.org/)
- [vue-chartjs 文档](https://vue-chartjs.org/)
- [项目 Chart.js 使用指南](./chartjs-usage-guide.md)
- [BaseChart 组件文档](../Web/src/components/Charts/README.md)