**task-1647.1 완료 보고**
**완료 보고서**

**핵심 결과**
13개 파일(수정 8 + 생성 5) 변경으로 전체 구현 완료. SEC-02 3건 즉시 패치, UserRole 단일 소스화(reviewer 추가), syncCustomClaims CF(Firestore 트리거), backfillCustomClaims CF(Callable), Security Rules 불변식(민감 필드 보호 + role 필드 보호 + reviews/auditLogs 서브컬렉션). 테스트 17건 전체 통과.

## 작업 내용

### SEC-02 즉시 패치 (CRITICAL)
- `/api/ai/search-wiki`: `verifyMember` 미들웨어 추가
- `/api/ai/index-wiki`: `verifyAdmin` 미들웨어 추가
- `/api/ai/invalidate-cache`: Bearer 존재 확인 → `verifyAuth()`(verifyIdToken) 교체
- `auth-middleware.ts`에 `verifyAdmin()` 함수 신규 추가

### UserRole 확장 + 타입 단일 소스화
- `shared/types/roles.ts` 생성: `UserRole = 'admin' | 'reviewer' | 'member' | 'guest'`
- `ROLE_HIERARCHY` (admin=3, reviewer=2, member=1, guest=0)
- `hasMinRole()` 함수, `ROLE_PERMISSIONS` 상수
- `firestore.ts`: 기존 UserRole 정의 제거 → shared import + re-export
- `AuthContext.tsx`: 기

**발견/해결 이슈 5건**
1. **firestore.ts UserRole 로컬 사용 불가** — `export type { UserRole }` re-export만으로는 같은 파일 내 사용 불가. `import type + export type` 패턴으로 수정.
2. **Document 인터페이스 중복 필드 선언** — question, answer, subcategory, sourceType 등 8개 필드가 라인 122-132와 163-171에 중복 선언. 후자 블록 삭제.
3. **isMemberOrAdmin()에 reviewer 역할 누락** — Security Rules에서 reviewer 사용자가 문서 접근 차단되는 치명적 버그. `['member', 'admin']` → `['member', 'reviewer', 'admin']` 수정.
4. **Claims 기반 함수와 DB 조회 기반 함수 혼용** — 미해결: reviews/auditLogs 서브컬렉션이 Claims 기반 함수를 사용하므로, backfillCustomClaims 실행 전에는 기존 유저가 접근 불가. 단, reviews는 Week 2에서 생성되므로 현재 데이터 없어 실제 영향 없음. 배포 순서: CF 배포 → backfill 실행 → Rules 배포.
5. **admin/users/page.tsx reviewer UI 미반영** — 미해결: 범위 외 (Phase 2b 검토 UI 작업에서 처리). reviewer 배지 색상 및 셀렉트박스 옵션 추가 필요.