EmailBill/openspec/changes/saving-detail-calculation/specs/budget-savings/spec.md

Spec: 预算存款服务重构

MODIFIED Requirements

Requirement: GetForMonthAsync 返回明细数据

BudgetSavingsService.GetForMonthAsync 方法 SHALL 返回包含明细数据的 BudgetResult 对象，除了原有的 HTML 描述外，还包括结构化的明细数据。

返回对象应包含：

• Limit: 计划存款金额（使用新公式计算）
• Current: 实际存款金额（从配置的存款分类中累加）
• Description: HTML 格式的详细说明（保留兼容性）
• Details: 新增的结构化明细数据（SavingsDetail 对象）

Scenario: 月度查询返回明细

• WHEN 调用 GetForMonthAsync(BudgetPeriodType.Month, new DateTime(2026, 2, 1))
• THEN 返回的 BudgetResult 对象包含 Details 字段，其中 IncomeItems 和 ExpenseItems 包含所有月度预算项和本月发生的年度预算项

Scenario: 向后兼容 HTML 描述

• WHEN 调用 GetForMonthAsync 方法
• THEN 返回的 Description 字段仍包含原有的 HTML 表格格式说明，确保旧版前端不受影响

Requirement: GetForYearAsync 返回明细数据

BudgetSavingsService.GetForYearAsync 方法 SHALL 返回包含归档月份和未来月份明细的完整数据结构。

归档月份明细应标注：

• IsArchived: true
• ArchivedMonths: 归档月份列表（如 [1, 2]）

Scenario: 年度查询包含归档明细

• WHEN 调用 GetForYearAsync(BudgetPeriodType.Year, new DateTime(2026, 3, 1))，且1月、2月已归档
• THEN 返回的 Details.IncomeItems 和 Details.ExpenseItems 中，归档月份的项目标记为 IsArchived = true

Scenario: 年初无归档数据

• WHEN 调用 GetForYearAsync(BudgetPeriodType.Year, new DateTime(2026, 1, 1))，无归档数据
• THEN 返回的明细中所有项目 IsArchived = false，未来月份数 = 12

ADDED Requirements

Requirement: BudgetItemCalculator 辅助类

系统 SHALL 提供 BudgetItemCalculator 静态类，用于计算单个预算项的计算用金额。

方法签名：

public static decimal CalculateEffectiveAmount(
    BudgetCategory category,
    decimal budgetLimit,
    decimal actualAmount,
    bool isMandatory,
    bool isArchived,
    DateTime referenceDate,
    BudgetPeriodType periodType)

Scenario: 调用计算器计算收入项

• WHEN 调用 CalculateEffectiveAmount(BudgetCategory.Income, 10000, 9500, false, false, date, Month)
• THEN 返回 9500（使用实际值）

Scenario: 调用计算器计算硬性支出

• WHEN 调用 CalculateEffectiveAmount(BudgetCategory.Expense, 3000, 0, true, false, new DateTime(2026, 2, 15), Month)
• THEN 返回 ≈ 1607.14（按天数折算）

Requirement: SavingsDetail 数据结构定义

系统 SHALL 定义以下 record 类型用于存储明细数据：

public record SavingsDetail
{
    public List<BudgetDetailItem> IncomeItems { get; init; } = new();
    public List<BudgetDetailItem> ExpenseItems { get; init; } = new();
    public SavingsCalculationSummary Summary { get; init; } = new();
}

public record BudgetDetailItem
{
    public long Id { get; init; }
    public string Name { get; init; } = string.Empty;
    public BudgetPeriodType Type { get; init; }
    public decimal BudgetLimit { get; init; }
    public decimal ActualAmount { get; init; }
    public decimal EffectiveAmount { get; init; }
    public string CalculationNote { get; init; } = string.Empty;
    public bool IsOverBudget { get; init; }
    public bool IsArchived { get; init; }
    public int[]? ArchivedMonths { get; init; }
}

public record SavingsCalculationSummary
{
    public decimal TotalIncomeBudget { get; init; }
    public decimal TotalExpenseBudget { get; init; }
    public decimal PlannedSavings { get; init; }
    public string CalculationFormula { get; init; } = string.Empty;
}

Scenario: 创建明细对象

• WHEN 系统计算完月度存款明细
• THEN 创建 SavingsDetail 对象，填充 IncomeItems、ExpenseItems 和 Summary

Requirement: 核心计算公式方法提取

系统 SHALL 将核心计算公式提取为独立的私有方法：

• CalculateMonthlyPlannedSavings: 月度计划存款计算
• CalculateYearlyPlannedSavings: 年度计划存款计算

Scenario: 单元测试可测试性

• WHEN 开发人员编写单元测试
• THEN 可以通过反射或测试友好的设计（如 internal 可见性）测试核心计算公式

Requirement: 计算说明生成

系统 SHALL 为每个明细项生成 CalculationNote 字段，说明使用了哪种计算规则：

• "使用预算"
• "使用实际"
• "使用实际（超支）"
• "按天折算"
• "归档实际"

Scenario: 生成计算说明

• WHEN 餐饮预算2000，实际2500
• THEN CalculationNote = "使用实际（超支）"，IsOverBudget = true

Requirement: 年度归档月份标注

对于年度查询中的归档月份数据，系统 SHALL 标注 IsArchived = true 和 ArchivedMonths 字段。

Scenario: 标注归档月份

• WHEN 工资预算在1月和2月都有归档数据
• THEN 返回的明细项中 IsArchived = true，ArchivedMonths = [1, 2]