EmailBill/openspec/changes/archive/2026-02-17-remove-v1-calendar-stats-budget/specs/budget-api/spec.md

REMOVED Requirements

Requirement: Get Uncovered Categories

Reason: 该接口仅被 V1 预算页面使用，用于展示"未设置预算的分类"。V2 预算页面不包含此功能。
Migration: 如需在 V2 中实现类似功能,应重新设计并创建新接口。当前无直接迁移路径。

原有功能:

• 接口: GET /api/Budget/GetUncoveredCategories
• Controller: BudgetController.GetUncoveredCategoriesAsync
• 参数: category (enum: Expense/Income/Saving), date (DateTime)
• 返回: List<string> (未设置预算的分类名称列表)
• 业务逻辑:
  1. 查询指定月份的所有交易记录，提取所有出现的分类
  2. 查询指定月份已设置预算的分类
  3. 计算差集，返回"有交易但未设置预算"的分类列表

被以下代码调用:

• Web/src/views/BudgetView.vue 中的 fetchUncoveredCategories 方法
• Web/src/api/budget.js 中的 getUncoveredCategories 函数

---

Requirement: Get Archive Summary

Reason: 该接口仅被 V1 预算页面使用，用于展示"历史预算归档总结"。V2 预算页面不包含此功能。
Migration: 如需在 V2 中实现类似功能，应重新设计并创建新接口。当前无直接迁移路径。

原有功能:

• 接口: GET /api/Budget/GetArchiveSummary
• Controller: BudgetController.GetArchiveSummaryAsync
• 参数: date (DateTime, 用于指定查询的年月)
• 返回: ArchiveSummaryDto (包含归档总结数据)
• 业务逻辑:
  1. 查询 BudgetArchive 表中指定月份的归档记录
  2. 汇总支出、收入、存款的预算执行情况
  3. 返回总结数据（如预算达成率、超支分类等）

被以下代码调用:

• Web/src/views/BudgetView.vue 中的 showArchiveSummary 方法
• Web/src/api/budget.js 中的 getArchiveSummary 函数

---

Context

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

接口背景

这两个接口是 V1 预算页面的特色功能：

1. 未覆盖分类提示: 帮助用户发现"有交易但未设置预算"的分类，提醒用户完善预算设置
2. 归档总结: 展示历史月份的预算执行总结，帮助用户回顾过去的财务状况

V2 设计变更

V2 预算页面重新设计了用户体验，移除了上述两个功能：

• 未覆盖分类: V2 采用"按需创建预算"模式，不主动提示未覆盖分类
• 归档总结: V2 使用实时统计替代归档总结，用户可随时查看任意月份的预算执行情况

技术依赖

这两个接口依赖以下 Service 和 Repository：

• BudgetService.GetUncoveredCategoriesAsync
• BudgetService.GetArchiveSummaryAsync
• BudgetRepository
• BudgetArchiveRepository
• TransactionRecordRepository

移除接口后，相关 Service 方法也将被移除（见 budget-service 规范）。

---

Validation

验证标准

1. 代码搜索验证:

   • 全局搜索 GetUncoveredCategories，确认仅在以下位置出现:
     • BudgetController.GetUncoveredCategoriesAsync (待删除)
     • BudgetApplication.GetUncoveredCategoriesAsync (待删除)
     • BudgetService.GetUncoveredCategoriesAsync (待删除)
     • BudgetView.vue (已删除)
     • budget.js (已清理)
   • 全局搜索 GetArchiveSummary，确认仅在 V1 相关代码中出现

2. 编译验证:

   • 删除 BudgetController 中的两个方法后，后端项目编译通过
   • 删除 BudgetApplication 和 BudgetService 中的对应方法后，编译通过

3. API 文档验证:

   • Swagger/Scalar 文档中不再显示以下端点:
     • /api/Budget/GetUncoveredCategories
     • /api/Budget/GetArchiveSummary

4. 运行时验证:

   • 前端调用上述端点返回 404
   • V2 预算页面 (/budget-v2) 正常加载和操作，不受影响

---

Dependencies

移除这两个接口的前置条件:

1. BudgetView.vue (V1 预算页面) 已删除
2. Web/src/api/budget.js 中的 getUncoveredCategories 和 getArchiveSummary 方法已清理
3. V2 预算页面已验证不依赖这两个接口

移除后连带删除:

• BudgetApplication.GetUncoveredCategoriesAsync
• BudgetApplication.GetArchiveSummaryAsync
• BudgetService.GetUncoveredCategoriesAsync
• BudgetService.GetArchiveSummaryAsync

移除后不影响:

• 其他预算相关接口 (GetList, GetCategoryStats, Create, Update, Delete 等)
• BudgetRepository 和 BudgetArchiveRepository 的查询逻辑 (仍被其他接口使用)
• V2 预算页面的任何功能

---

Notes

功能对比表

功能	V1 实现	V2 实现
未覆盖分类提示	专用接口 GetUncoveredCategories	无（按需创建预算）
归档总结	专用接口 GetArchiveSummary	实时统计 GetCategoryStats
预算列表	GetList	GetList (共用)
分类统计	GetCategoryStats	GetCategoryStats (共用)

潜在影响

如果未来需要在 V2 中恢复"未覆盖分类"或"归档总结"功能：

1. 不能直接恢复删除的代码，因为业务逻辑可能已过时
2. 应重新设计接口，考虑 V2 的数据模型和用户体验
3. 建议先调研用户需求，确认是否真的需要这些功能