EmailBill/openspec/specs/statistics-api/spec.md

REMOVED Requirements

Requirement: Get Balance Statistics

Reason: 该接口仅被 V1 统计页面使用，用于绘制"余额变化折线图"。V2 统计页面使用不同的图表渲染逻辑，不依赖此接口。
Migration: V2 统计页面使用 GetDailyStatistics 接口获取数据，并在前端计算累积余额。无需后端专用接口。

原有功能:

• 接口: GET /api/TransactionStatistics/GetBalanceStatistics
• Controller: TransactionStatisticsController.GetBalanceStatisticsAsync
• 参数: year (int), month (int)
• 返回: BalanceStatisticsDto (包含每日的累积余额数据)
• 业务逻辑:
  1. 查询指定月份的所有交易记录，按日期排序
  2. 计算每日的累积余额 (前一日余额 + 当日收入 - 当日支出)
  3. 返回包含日期和余额的时间序列数据

被以下代码调用:

• Web/src/views/statisticsV1/Index.vue 中的 fetchBalanceData 方法
• Web/src/api/statistics.js 中的 getBalanceStatistics 函数

图表渲染逻辑:

• V1 使用 ECharts 折线图渲染余额曲线
• 数据源: 后端计算好的累积余额
• 渲染方法: renderBalanceChart()

---

Context

本规范定义了 EmailBill 后端 TransactionStatisticsController 中 V1 专用接口的移除操作。

接口背景

该接口是 V1 统计页面的核心功能之一，用于支持"余额变化趋势图"：

• 设计理念: 后端负责累积余额计算，前端只负责渲染
• 性能考虑: 避免前端处理大量交易记录数据
• 适用场景: V1 统计页面需要独立的余额统计视图

V2 设计变更

V2 统计页面重新设计了数据获取和渲染逻辑：

• 数据获取: 使用 GetDailyStatistics 一次性获取日度支出/收入数据
• 余额计算: 在前端 Vue 组件中计算累积余额 (computed property)
• 性能优化: 前端缓存计算结果，减少重复请求
• 代码简化: 后端不需要维护专用的余额统计接口

技术对比

维度	V1 实现	V2 实现
数据获取	专用接口 GetBalanceStatistics	通用接口 GetDailyStatistics
余额计算	后端计算	前端计算
网络请求	2 次 (日度统计 + 余额统计)	1 次 (日度统计)
前端逻辑	简单渲染	计算 + 渲染
后端复杂度	高 (多个接口)	低 (统一接口)

依赖关系

该接口依赖以下 Service 和 Repository：

• TransactionStatisticsService.GetBalanceStatisticsAsync
• TransactionStatisticsApplication.GetBalanceStatisticsAsync
• TransactionRecordRepository (查询交易记录)

移除接口后，相关 Service 方法也将被移除。

---

Validation

验证标准

1. 代码搜索验证:

   • 全局搜索 GetBalanceStatistics，确认仅在以下位置出现:
     • TransactionStatisticsController.GetBalanceStatisticsAsync (待删除)
     • TransactionStatisticsApplication.GetBalanceStatisticsAsync (待删除)
     • TransactionStatisticsService.GetBalanceStatisticsAsync (待删除)
     • statisticsV1/Index.vue (已删除)
     • statistics.js (已清理)

2. 编译验证:

   • 删除 TransactionStatisticsController 中的方法后，后端项目编译通过
   • 删除 TransactionStatisticsApplication 和 TransactionStatisticsService 中的对应方法后，编译通过

3. API 文档验证:

   • Swagger/Scalar 文档中不再显示 /api/TransactionStatistics/GetBalanceStatistics 端点

4. 运行时验证:

   • 前端调用 /api/TransactionStatistics/GetBalanceStatistics 返回 404
   • V2 统计页面 (/statistics-v2) 正常加载，余额曲线正常渲染

5. 功能验证 (V2 统计页面):

   • 打开 /statistics-v2
   • 切换到"月度视图"
   • 确认余额折线图正常显示
   • 确认数据与 V1 保持一致 (基于相同的 GetDailyStatistics 数据)

---

Dependencies

移除此接口的前置条件:

1. statisticsV1/Index.vue (V1 统计页面) 已删除
2. Web/src/api/statistics.js 中的 getBalanceStatistics 方法已清理
3. V2 统计页面已验证可以通过前端计算实现相同功能

移除后连带删除:

• TransactionStatisticsApplication.GetBalanceStatisticsAsync
• TransactionStatisticsService.GetBalanceStatisticsAsync

移除后不影响:

• 其他统计接口 (GetMonthlyStatistics, GetCategoryStatistics, GetDailyStatistics)
• TransactionRecordRepository 的查询逻辑 (仍被其他接口使用)
• V2 统计页面的任何功能 (余额计算逻辑已在前端实现)

---

Implementation Notes

V2 前端余额计算示例 (参考)

// Web/src/views/statisticsV2/Index.vue
computed: {
  balanceData() {
    let cumulativeBalance = 0
    return this.dailyData.map(day => {
      cumulativeBalance += day.income - day.expense
      return {
        date: day.date,
        balance: cumulativeBalance
      }
    })
  }
}

性能分析

• V1 方案: 后端查询 + 计算 + 序列化 → 前端接收 + 渲染 (总时间: ~200ms)
• V2 方案: 后端查询 + 序列化 → 前端接收 + 计算 + 渲染 (总时间: ~180ms)
• 结论: V2 方案性能略优，且减少了后端复杂度

回归测试建议

删除接口后，应手动验证 V2 统计页面的以下场景：

1. 正常月份: 选择有交易的月份，确认余额曲线正常
2. 无交易月份: 选择无交易的月份，确认显示"暂无数据"
3. 跨年场景: 验证 1 月份的余额计算是否正确 (初始余额为 0)
4. 性能测试: 加载包含大量交易 (>1000 笔) 的月份，确认渲染流畅