## Context

EmailBill 是一个预算跟踪应用，包含 .NET 10 后端和 Vue 3 前端。预算模块负责计算和展示预算执行情况，包括收入、支出和存款计划。

**当前问题**：
1. 预算收入的实际金额计算错误，`BudgetRepository.GetCurrentAmountAsync` 方法查询交易记录时可能存在过滤条件问题
2. 存款计划卡片缺少透明度，用户无法了解"计划存款"金额的计算依据
3. 预算页面的卡片样式与统计页面不一致，影响视觉统一性

**技术栈**：
- 后端：.NET 10, FreeSql ORM, xUnit 测试
- 前端：Vue 3 Composition API, Vant UI, SCSS
- 数据库：SQLite

**约束**：
- 保持向后兼容，不破坏现有 API 契约
- 遵循项目现有的代码风格（中文注释、文件作用域命名空间）
- 样式修改需保持暗色主题兼容性

## Goals / Non-Goals

**Goals:**
- 修复收入预算实际金额的计算错误，确保数据准确性
- 为存款计划添加明细展示功能，提升透明度
- 统一预算页面与统计页面的卡片样式，提升 UI 一致性
- 添加单元测试覆盖修复的逻辑

**Non-Goals:**
- 不重构整个预算计算系统
- 不改变预算数据模型结构
- 不修改其他页面的卡片样式
- 不改变存款计划的计算算法本身

## Decisions

### 决策 1：问题 1 的修复策略

**决定**：采用 TDD（测试驱动开发）方式修复计算错误

**方案对比**：
- **方案 A（选择）**：先编写失败的单元测试复现 bug，然后修复代码，最后验证测试通过
  - ✅ 确保 bug 被正确理解和修复
  - ✅ 防止回归
  - ⏱️ 需要额外编写测试
- **方案 B**：直接修复代码，手动验证
  - ❌ 无法保证不引入新问题
  - ❌ 缺少回归保护

**实施细节**：
1. 在 `WebApi.Test/` 中创建测试用例，使用实际数据复现"家庭年终奖金"的计算错误
2. 诊断 `BudgetRepository.GetCurrentAmountAsync` 的查询条件：
   - 检查 `SelectedCategories` 的 `Contains` 匹配逻辑
   - 验证日期范围过滤是否正确（`>=` 和 `<=`）
   - 确认 `TransactionType` 过滤条件
3. 修复后运行测试验证

### 决策 2：存款计划明细的数据来源

**决定**：前端计算明细，不新增后端 API

**方案对比**：
- **方案 A（选择）**：前端基于现有数据计算明细
  - ✅ 不增加后端复杂度
  - ✅ 响应速度快
  - ⚠️ 前端需要理解计算逻辑
- **方案 B**：新增后端 API 返回计算明细
  - ⏱️ 需要设计新的 DTO 和 API
  - 🔄 增加网络往返

**实施细节**：
1. 明细弹窗展示内容：
   - **收入预算总计**：所有收入预算的限额和实际值
   - **支出预算总计**：所有支出预算的限额和实际值
   - **计划存款公式**：`收入预算 - 支出预算 = 计划存款`
   - **实际存款**：从 budget 对象获取
   - **差额**：`计划存款 - 实际存款`
2. 使用 Vant 的 Popup 组件实现弹窗
3. 在 `BudgetCard.vue` 的 `header-actions` slot 添加"明细"图标按钮（`icon="info"`）

### 决策 3：样式统一的方案

**决定**：直接修改 `.chart-card` 样式，使其继承或匹配 `.common-card`

**方案对比**：
- **方案 A（选择）**：修改 `BudgetChartAnalysis.vue` 中的 `.chart-card` 样式
  - ✅ 改动最小，影响范围可控
  - ✅ 立即见效
- **方案 B**：将所有预算卡片改为使用 `.common-card` 类
  - ⏱️ 需要大量 HTML 结构修改
  - ⚠️ 可能影响现有布局逻辑
- **方案 C**：创建新的统一卡片组件
  - 🔄 过度设计
  - ⏱️ 需要重构多个页面

**实施细节**：
1. 修改 `Web/src/components/Budget/BudgetChartAnalysis.vue` 的 `.chart-card` 样式：
   ```scss
   .chart-card {
     background: var(--van-background-2);
     border-radius: 16px;  // 改为 16px
     padding: 16px;
     box-shadow: 0 2px 12px rgba(0, 0, 0, 0.08);  // 统一阴影
     border: 1px solid var(--van-border-color);  // 添加边框
     margin: 0 12px 16px;  // 添加边距
   }
   ```
2. 检查 `.gauge-card` 的特殊样式是否需要保留
3. 验证暗色主题下的效果

## Risks / Trade-offs

**风险 1：问题 1 的修复可能影响其他预算类型**
- **缓解**：编写覆盖支出、收入、存款三种类型的测试用例
- **回退**：保留 git 历史，可快速回滚

**风险 2：明细弹窗的计算逻辑可能与后端不一致**
- **缓解**：参考 `BudgetSavingsService.cs` 的计算逻辑，确保前端实现一致
- **验证**：与后端计算结果进行对比测试

**风险 3：样式修改可能在某些设备或浏览器上显示异常**
- **缓解**：修改后在浏览器中测试深色/浅色主题
- **回退**：样式改动独立 commit，可快速回滚

**权衡：前端计算 vs 后端计算**
- 选择前端计算明细可以减少 API 开销，但增加了前端复杂度
- 如果未来计算逻辑变得更复杂，可能需要迁移到后端

## Migration Plan

**部署步骤**：
1. 后端修复和测试：
   - 运行 `dotnet test` 确保所有测试通过
   - 构建后端：`dotnet build`
2. 前端修改：
   - 运行 `pnpm lint` 检查代码风格
   - 构建前端：`pnpm build`
3. 浏览器验证：
   - 测试收入预算的实际金额显示
   - 测试存款计划明细弹窗
   - 验证卡片样式一致性

**回滚策略**：
- 所有改动都在独立分支，可快速回滚
- 数据库无结构变更，无需数据迁移

**验证清单**：
- [ ] 收入预算的"家庭年终奖金"实际金额正确显示
- [ ] 存款计划卡片有明细按钮，点击显示计算详情
- [ ] 预算页面的卡片样式与统计页面一致
- [ ] 所有单元测试通过
- [ ] 前端 ESLint 无错误

## Open Questions

1. **问题 1 的具体原因**：`SelectedCategories` 匹配问题还是日期范围问题？
   - 需要查看实际数据库中的 `TransactionRecord` 和 `BudgetRecord` 数据
   - 建议在修复前添加详细的日志输出

2. **明细弹窗是否需要支持历史月份查询？**
   - 当前设计仅展示当前周期的明细
   - 如果需要历史查询，可能需要后端 API 支持

3. **样式修改是否需要同步到其他使用 `.chart-card` 的组件？**
   - 需要检查是否有其他页面使用了相同的类名
   - 建议全局搜索 `.chart-card` 确认影响范围