# 채권현황 동적월 지원 및 year=0 파라미터 버그 수정

## 작업 일시
2026-01-02

## 문제 상황
"최근 1년" 필터가 제대로 동작하지 않는 3가지 버그:
1. 2026년 조회 후 "최근 1년" 선택 시 2026년 기준 데이터 표시
2. 2025년 조회 후 "최근 1년" 선택 시 2025년 기준 데이터 표시
3. 초기 페이지 로드 시 "최근 1년" 기본값인데 데이터 없음

## 원인 분석

### 프론트엔드 (이전 세션에서 수정됨)
- JavaScript에서 `year === 0` 체크가 falsy 값 문제로 제대로 동작하지 않음
- `if (year)` 같은 조건문에서 0이 false로 처리됨

### 백엔드 (이번 세션에서 수정)
- Laravel의 `'nullable|boolean'` 검증이 쿼리 파라미터로 전달된 문자열 "true"를 거부
- HTTP 쿼리 파라미터는 항상 문자열로 전달됨

## 수정 내용

### 1. ReceivablesController.php
```php
// 변경 전
'recent_year' => 'nullable|boolean',

// 변경 후
'recent_year' => 'nullable|string|in:true,false,1,0',

// 검증 후 boolean 변환
if (isset($params['recent_year'])) {
    $params['recent_year'] = filter_var($params['recent_year'], FILTER_VALIDATE_BOOLEAN);
}

\Log::info('[Receivables] index params', $params);
```

### 2. actions.ts (이전 세션 수정, 검증됨)
```typescript
const yearValue = params?.year;
if (typeof yearValue === 'number') {
  if (yearValue === 0) {
    searchParams.set('recent_year', 'true');
  } else {
    searchParams.set('year', String(yearValue));
  }
}
```

## 핵심 포인트
1. **명시적 타입 체크**: `typeof yearValue === 'number'`로 undefined와 0을 구분
2. **문자열 boolean 검증**: Laravel에서 `'in:true,false,1,0'` 사용 후 `filter_var()` 변환
3. **디버그 로깅**: 개발 중 파라미터 확인을 위한 로그 추가 (테스트 후 제거 필요)

## Git 커밋
- API: `4fa38e3` - feat(API): 채권현황 동적월 지원 및 year=0 파라미터 버그 수정
- React: `672b1b4` - feat(WEB): 채권현황 동적월 지원 및 year=0 파라미터 버그 수정
- React: `1f32b04` - docs: 채권현황 동적월 지원 작업 현황 업데이트

## 관련 파일
- `/api/app/Http/Controllers/Api/V1/ReceivablesController.php`
- `/api/app/Services/ReceivablesService.php`
- `/react/src/components/accounting/ReceivablesStatus/actions.ts`
- `/react/src/components/accounting/ReceivablesStatus/index.tsx`

## 후속 작업
- [ ] 테스트 완료 후 디버그 로그 제거
- [ ] 추가 UI 개선 (사용자 확인 필요)
