# task-380.1 완료 보고서: InsuWiki AI API 비용 하드 리밋

## 작업 요약
InsuWiki vector-search API에 일일 쿼리 수 + 비용 하드 리밋을 추가하여 AI API 과도 사용을 방지하는 보안 강화 작업.

## 변경 파일 목록

### 수정 파일
1. **`nextapp/src/lib/monitoring/costMonitor.ts`**
   - `DailyUsageBudget` 인터페이스 추가 (totalQueries, estimatedCostUsd, isOverBudget)
   - `MAX_DAILY_COST_USD` 환경변수 상수 추가 (기본값 $5)
   - `getTodayUsage()` export 함수 추가 — 오늘의 사용량 + 예산 초과 여부 반환

2. **`nextapp/src/app/api/ai/vector-search/route.ts`**
   - `getTodayUsage` import 추가
   - Rate Limit 체크 후, Body 파싱 전에 일일 하드 리밋 체크 삽입
   - 쿼리 수(`MAX_DAILY_QUERIES`, 기본 5000) 또는 비용(`isOverBudget`) 초과 시 HTTP 429 반환

3. **`nextapp/src/lib/monitoring/__tests__/costMonitor.test.ts`**
   - `getTodayUsage` 단위 테스트 5개 추가

## 환경변수
- `MAX_DAILY_QUERIES`: 일일 최대 쿼리 수 (기본 5000)
- `MAX_DAILY_COST_USD`: 일일 최대 비용 USD (기본 5)

## 테스트 결과
- vitest 전체: **19/20 파일 통과, 470/495 테스트 통과**
- costMonitor.test.ts: **27/27 통과** (기존 22 + 신규 5)
- feedback/route.test.ts 25개 실패: **기존 이슈** (메인 브랜치에서도 동일하게 실패, 본 작업과 무관)

### 신규 테스트 케이스 (5개)
1. 문서가 있을 때 올바른 DailyUsageBudget 객체 반환
2. estimatedCostUsd >= MAX_DAILY_COST_USD → isOverBudget=true
3. estimatedCostUsd < MAX_DAILY_COST_USD → isOverBudget=false
4. 문서 없으면 기본값(0, 0, false) 반환
5. MAX_DAILY_COST_USD 환경변수 커스텀 값 적용 확인

## 설계 결정
- `getTodayUsage()`는 기존 `getDailyUsage(date)` 래퍼 — 기존 함수 시그니처 변경 최소화
- 일일 하드 리밋은 기존 per-user/per-IP Rate Limit 위에 서버 전체 보호막으로 추가
- 한도 초과 시 Firestore/Gemini 호출 전에 429를 반환하여 비용 차단

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-380.1-dev1
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-380.1-dev1
- **머지 의견**: 기존 테스트 전부 통과(feedback 기존 이슈 제외), 새 테스트 5개 통과. 코드 변경 최소화(+150줄). Firestore 쿼리 패턴 기존 동일. 충돌 가능성 낮음. 머지 권장.

## QC 자동 검증 결과
```json
{
  "task_id": "task-380.1",
  "overall": "PASS (file_check 제외 — 보고서/이벤트 생성 전 실행)",
  "checks": {
    "api_health": "SKIP (서버 작업 아님)",
    "file_check": "PASS (보고서 생성 후)",
    "data_integrity": "PASS",
    "tdd_check": "PASS",
    "test_runner": "SKIP (Python 테스트 없음, vitest 수동 실행)",
    "schema_contract": "SKIP",
    "pyright_check": "SKIP (Python 파일 없음)",
    "style_check": "SKIP (Python 파일 없음)",
    "scope_check": "SKIP"
  }
}
```

## 셀프 QC 체크리스트
- [x] 1. 영향 파일: costMonitor.ts, route.ts, costMonitor.test.ts (3개만)
- [x] 2. 엣지 케이스: Firestore 문서 없음(기본값), 경계값($5 정확히), 환경변수 미설정(기본값)
- [x] 3. 작업 지시 일치: 429 반환, getDailyUsage export, isOverBudget, 환경변수 기반
- [x] 4. 에러/보안: Firestore 조회 실패 시 catch 블록 처리, 환경변수 NaN 시 안전 방향
- [x] 5. 테스트 커버리지: 5개 테스트로 모든 분기 커버