EmailBill/.sisyphus/notepads/statistics-year-selection/decisions.md

Decisions - Statistics Year Selection Enhancement

[2026-01-28] Architecture Decisions

Frontend Implementation Strategy

1. Date Picker Mode Toggle

• Add a toggle switch in the date picker popup to switch between "按月" (month) and "按年" (year) modes
• When "按年" selected: use columns-type="['year']"
• When "按月" selected: use columns-type="['year', 'month'] (current behavior)

2. State Management

• Add dateSelectionMode ref: 'month' | 'year'
• When year-only mode: set currentMonth = 0 to indicate full year
• Keep currentYear as integer (unchanged)
• Update selectedDate array dynamically based on mode:
  • Year mode: ['YYYY']
  • Month mode: ['YYYY', 'MM']

3. Display Logic

• Nav bar title: currentYear年 when currentMonth === 0, else currentYear年currentMonth月
• Chart titles: Update to reflect year or year-month scope

4. API Calls

• Pass month: currentMonth.value || 0 to all API calls
• Backend will handle month=0 as year-only query

Backend Implementation Strategy

1. Repository Layer Change

File: Repository/TransactionRecordRepository.cs Method: BuildQuery() lines 81-86

if (year.HasValue)
{
    if (month.HasValue && month.Value > 0)
    {
        // Specific month
        var dateStart = new DateTime(year.Value, month.Value, 1);
        var dateEnd = dateStart.AddMonths(1);
        query = query.Where(t => t.OccurredAt >= dateStart && t.OccurredAt < dateEnd);
    }
    else
    {
        // Entire year
        var dateStart = new DateTime(year.Value, 1, 1);
        var dateEnd = new DateTime(year.Value + 1, 1, 1);
        query = query.Where(t => t.OccurredAt >= dateStart && t.OccurredAt < dateEnd);
    }
}

2. Service Layer

• No changes needed - services already pass month parameter to repository
• Services will receive month=0 for year-only queries

3. API Controller

• No changes needed - already accepts year/month parameters

Testing Strategy

Backend Tests

• Test year-only query returns all transactions for that year
• Test month-specific query still works
• Test edge cases: year boundaries, leap years

Frontend Tests

• Test toggle switches picker mode correctly
• Test year selection updates state and fetches data
• Test display updates correctly for year vs year-month

User Experience Flow

1. User clicks date picker in nav bar
2. Popup opens with toggle: "按月 | 按年"
3. User selects mode (default: 按月 for backward compatibility)
4. User selects date(s) and confirms
5. Statistics refresh with new scope
6. Display updates to show scope (year or year-month)