# task-2261 완료 보고서: InsuRo PWA 캐시 근본 해결

## SCQA

**S**: InsuRo PWA가 `registerType: "autoUpdate"` 설정만 있고, 클라이언트 측 SW 업데이트 감지/적용 코드가 없어 배포 후 구버전이 캐시되는 문제가 빈번 발생.

**C**: Cloudflare Pages 캐시 헤더도 미설정 상태여서 `index.html`과 `sw.js`까지 브라우저 캐시에 걸려, 사용자가 수동 새로고침하지 않으면 최신 버전을 받을 수 없었다.

**Q**: SW 업데이트 즉시 감지 + 사용자 알림 + 캐시 정책 최적화로 배포 후 즉시 반영되도록 할 수 있는가?

**A**: 4가지 변경으로 해결: (1) `registerSW` + 토스트 알림으로 사용자에게 업데이트 안내 (prompt 모드), (2) workbox `cleanupOutdatedCaches` + `skipWaiting: false`/`clientsClaim: false` 설정, (3) Cloudflare `_headers`로 `index.html`/`sw.js`/`manifest.webmanifest` no-cache 설정, (4) Gemini High 2건 즉시 수정. 빌드 성공 2회, sw.js 정상 생성 확인.

## 수정 파일

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| src/main.tsx | registerSW import + onNeedRefresh 토스트 + onOfflineReady | grep "registerSW" OK (2건) | verified |
| vite.config.ts:27 | registerType: "autoUpdate" → "prompt" | grep "prompt" OK | verified |
| vite.config.ts:45-47 | skipWaiting: false, clientsClaim: false, cleanupOutdatedCaches: true | grep "skipWaiting: false" OK | verified |
| public/_headers (신규) | Cloudflare Cache-Control (index.html, manifest, sw.js = no-cache / JS,CSS = immutable) | grep "manifest.webmanifest" OK | verified |
| src/vite-env.d.ts:2 | vite-plugin-pwa/client 타입 참조 추가 | grep "vite-plugin-pwa" OK | verified |

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **TypeScript 빌드 오류: `virtual:pwa-register` 모듈 미인식** — `src/vite-env.d.ts`에 `/// <reference types="vite-plugin-pwa/client" />` 추가
   - 원인: vite-plugin-pwa의 가상 모듈 타입 선언이 프로젝트에 등록되지 않음
   - 수정: `src/vite-env.d.ts:2`에 reference 추가

2. **[Gemini High] registerType "autoUpdate"에서 onNeedRefresh 미트리거** — `registerType: "prompt"`로 변경
   - 원인: autoUpdate 모드는 SW를 자동 활성화하여 onNeedRefresh 콜백을 건너뜀
   - 수정: `vite.config.ts:27` autoUpdate → prompt

3. **[Gemini High] skipWaiting/clientsClaim이 prompt 모드와 충돌** — `false`로 변경
   - 원인: skipWaiting: true가 SW waiting 상태를 건너뛰어 onNeedRefresh 미발동
   - 수정: `vite.config.ts:45-46` true → false

### 범위 외 미해결 (0건)

## Gemini PR 리뷰 대응

- PR: https://github.com/JonghyukJeon/InsuRo/pull/53
- High severity 2건: 모두 수용(Accept) → 코드 수정 후 재push
- Medium severity 1건: 수용 → manifest.webmanifest 캐시 헤더 추가
- 미수정 High: 0건 → PASS → 머지 완료

## L1 스모크테스트 결과

- 서버 재시작: 성공 (`npx serve dist -l 3847`)
- API 응답 확인:
  - `GET /` → HTTP 200 OK
  - `HEAD /sw.js` → HTTP 200 OK (10,156 bytes)
- 스크린샷: 해당없음 (정적 서빙 테스트, PWA SW 등록은 HTTPS 필요)

## 빌드 결과

- 빌드 성공 2회 (초기 + Gemini 수정 후 재빌드)
- PWA v1.2.0, mode: generateSW, precache: 158 entries (5,609 KiB)
- 생성 파일: `dist/sw.js`, `dist/workbox-b973423a.js`
- 최종 빌드 시각: 2026-04-28 08:02 UTC

## 머지 판단

- **머지 필요**: Yes → **완료**
- **브랜치**: task/task-2261-dev1 (머지 후 삭제됨)
- **PR**: https://github.com/JonghyukJeon/InsuRo/pull/53
- **Gemini PR 리뷰 완료**: High 2건 수용, Medium 1건 수용, 미수정 High 0건

## 모델 사용 기록

- 이리스 / SW register + 토스트 알림 구현 + Gemini 수정 / sonnet / -
- 불칸 / workbox 설정 강화 + _headers 생성 / sonnet / -
- 헤르메스(직접) / TS 타입 선언 수정 / opus / Sonnet 실패가 아닌 진단 즉시 수정 (1줄)

## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회