EmailBill/openspec/changes/archive/2026-02-21-saving-detail-calculation/specs/saving-detail-calculation/spec.md

Spec: 存款明细计算核心算法

ADDED Requirements

Requirement: 月度计划存款计算公式

系统 SHALL 使用以下公式计算月度计划存款：

月度计划存款 = 收入预算 + 发生在本月的年度收入 - 支出预算 - 发生在本月的年度支出

其中：

• 收入预算：所有月度收入预算项的预算金额之和
• 发生在本月的年度收入：年度收入预算项在本月实际发生的金额（actual > 0）
• 支出预算：所有月度支出预算项的预算金额之和
• 发生在本月的年度支出：年度支出预算项在本月实际发生的金额（actual > 0）

Scenario: 纯月度预算计算

• WHEN 用户查询 2026年2月的月度存款，且只有月度预算（工资10000、奖金5000、房租3000、餐饮2000）
• THEN 系统返回计划存款 = 10000 + 5000 - 3000 - 2000 = 10000

Scenario: 月度预算 + 本月发生的年度预算

• WHEN 用户查询 2026年2月的月度存款，月度预算（工资10000、房租3000），且年度旅游支出在本月实际发生3000元
• THEN 系统返回计划存款 = 10000 - 3000 - 3000 = 4000

Scenario: 年度预算未在本月发生

• WHEN 用户查询 2026年2月的月度存款，月度预算（工资10000、房租3000），年度年终奖预算50000但本月实际为0
• THEN 系统返回计划存款 = 10000 - 3000 = 7000（年终奖不计入）

Requirement: 年度计划存款计算公式

系统 SHALL 使用以下公式计算年度计划存款：

年度计划存款 = 归档月已实收 + 未来月（包含本月）收入预算 - 归档月已实支 - 未来月（包含本月）支出预算

其中：

• 归档月已实收：已归档月份（1月~当前月-1）的实际收入金额之和，从 BudgetArchive 读取
• 未来月收入预算：当前月及未来月份的月度收入预算 × 剩余月数
• 归档月已实支：已归档月份的实际支出金额之和，从 BudgetArchive 读取
• 未来月支出预算：当前月及未来月份的月度支出预算 × 剩余月数

Scenario: 年初无归档数据

• WHEN 用户在 2026年1月查询年度存款，月度预算（工资10000/月、房租3000/月），无归档数据
• THEN 系统返回计划存款 = (10000 - 3000) × 12 = 84000

Scenario: 年中有归档数据

• WHEN 用户在 2026年3月查询年度存款，1月归档已实收15000、已实支4800，2月归档已实收14000、已实支5200，3~12月月度预算（工资10000、房租3000）
• THEN 系统返回计划存款 = (15000 + 14000) + (10000 × 10) - (4800 + 5200) - (3000 × 10) = 129000

Scenario: 归档数据包含年度预算

• WHEN 归档数据中包含年度预算的实际发生金额（如1月旅游支出3000）
• THEN 系统将其计入"归档月已实支"，不重复计算

Requirement: 明细项计算用金额 - 收入规则

对于收入类预算项，系统 SHALL 根据以下规则计算"计算用金额"：

• 如果实际金额 > 0，计算用金额 = 实际金额
• 如果实际金额 = 0，计算用金额 = 预算金额

Scenario: 收入已发生

• WHEN 工资预算10000，实际发生9500
• THEN 计算用金额 = 9500，标注为"使用实际"

Scenario: 收入未发生

• WHEN 奖金预算5000，实际发生0
• THEN 计算用金额 = 5000，标注为"使用预算"

Requirement: 明细项计算用金额 - 支出规则（普通）

对于非硬性支出类预算项，系统 SHALL 计算用金额 = MAX(预算金额, 实际金额)

Scenario: 支出未超预算

• WHEN 餐饮预算2000，实际发生1800
• THEN 计算用金额 = 2000，标注为"使用预算"

Scenario: 支出超预算

• WHEN 餐饮预算2000，实际发生2500
• THEN 计算用金额 = 2500，标注为"使用实际（超支）"，高亮显示

Requirement: 明细项计算用金额 - 支出规则（硬性）

对于硬性支出（IsMandatoryExpense = true）且实际金额 = 0 的预算项，系统 SHALL 按天数折算计算用金额，不进行 MAX 比较。

月度折算公式：计算用金额 = 预算金额 / 当月天数 × 当前日期

年度折算公式：计算用金额 = 预算金额 / 当年天数 × 当前天数

Scenario: 硬性支出未发生（月度）

• WHEN 房租预算3000（硬性），实际为0，当前日期为2月15日，2月共28天
• THEN 计算用金额 = 3000 / 28 × 15 ≈ 1607.14，标注为"按天折算"

Scenario: 硬性支出已发生

• WHEN 房租预算3000（硬性），实际发生3000
• THEN 计算用金额 = MAX(3000, 3000) = 3000，标注为"使用实际"

Scenario: 硬性支出超预算

• WHEN 水电预算500（硬性），实际发生600
• THEN 计算用金额 = MAX(500, 600) = 600，标注为"使用实际（超支）"

Scenario: 硬性支出按天折算可能超预算

• WHEN 房租预算3000（硬性），实际为0，当前日期为2月29日，2月共28天
• THEN 计算用金额 = 3000 / 28 × 29 ≈ 3107.14（大于预算），标注为"按天折算"

Requirement: 归档月份数据处理

对于已归档月份的预算数据，系统 SHALL 直接使用归档中的实际金额（BudgetArchive.Content[].Actual），不重新计算。

Scenario: 读取归档数据

• WHEN 用户在3月查询年度存款，1月归档中工资实际10000、房租实际3000
• THEN 系统使用归档实际值10000和3000，不根据当前预算重新计算

Scenario: 归档后预算调整

• WHEN 1月归档时工资预算10000，实际10000；2月将工资预算调整为12000；用户在3月查询年度存款
• THEN 1月仍使用归档的实际10000，2月及以后使用新预算12000

Requirement: 闰年和月末边界处理

系统 SHALL 正确处理闰年和月末边界情况：

• 闰年判断：使用 DateTime.IsLeapYear(year) 判断，闰年366天，平年365天
• 月末天数：使用 DateTime.DaysInMonth(year, month) 获取

Scenario: 闰年2月硬性支出折算

• WHEN 2024年2月29日（闰年），房租预算3000（硬性），实际为0
• THEN 计算用金额 = 3000 / 29 × 29 = 3000

Scenario: 平年2月硬性支出折算

• WHEN 2026年2月28日（平年），房租预算3000（硬性），实际为0
• THEN 计算用金额 = 3000 / 28 × 28 = 3000

Scenario: 年度硬性支出闰年折算

• WHEN 2024年（闰年）第100天，年度保险预算12000（硬性），实际为0
• THEN 计算用金额 = 12000 / 366 × 100 ≈ 3278.69

Requirement: 不记额预算处理

对于不记额预算（NoLimit = true）的预算项，系统 SHALL 排除在计划存款计算之外，但在明细中显示为"不限额"。

Scenario: 不记额收入

• WHEN 存在不记额收入预算项（如意外收入），实际发生1000
• THEN 该项不计入"收入预算"，明细中显示预算为"不限额"，实际为1000