# 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

```csharp
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)