# PWA (Progressive Web App) 가이드

## 개요

tkfb.technicalkorea.net에 PWA를 적용하여 모바일에서 홈 화면 앱처럼 사용 가능합니다.

- **전략**: network-first (항상 네트워크 우선, 실패 시 캐시)
- **목적**: 앱 느낌 제공 (주소창 없음, 스플래시 화면, 홈 아이콘)
- **오프라인**: 제한적 (이전 방문 페이지만 캐시에서 제공)

## 파일 구조

```
web/
├── manifest.json          # PWA 매니페스트 (앱 이름, 아이콘, 테마)
├── sw.js                  # 서비스 워커 (network-first 캐시)
├── js/app-init.js         # SW 등록 + manifest 동적 삽입 (setupPWA 함수)
└── img/
    ├── icon-192x192.png   # PWA 아이콘 (192px)
    └── icon-512x512.png   # PWA 아이콘 (512px)
```

## 주의사항

### sw.js 수정 시 반드시 지킬 것

1. **CACHE_VERSION을 반드시 올릴 것** (예: `tkfb-v1` → `tkfb-v2`)
   - 버전을 안 올리면 사용자가 이전 캐시를 계속 사용
2. **network-first 전략을 유지할 것**
   - `cache-first`로 바꾸면 배포해도 사용자에게 반영 안 됨
3. **API 요청은 절대 캐시하지 말 것**
   - `if (request.url.includes('/api/')) return;` 라인 유지
4. **가능하면 sw.js를 건드리지 말 것**
   - 잘못된 sw.js가 배포되면 최대 24시간 동안 사용자 브라우저에 캐시됨
   - 일반 HTML/CSS/JS 수정은 sw.js와 무관하게 정상 반영됨

### 비상 복구 (킬스위치)

sw.js에 문제가 생겼을 때 사용자 브라우저에서 서비스 워커를 해제하는 방법:

```
https://tkfb.technicalkorea.net/pages/dashboard.html?sw-kill
```

이 URL로 접속하면:
- 등록된 서비스 워커 모두 해제
- 캐시 스토리지 전체 삭제
- 페이지 자동 새로고침

### 일반 배포 시

- HTML/CSS/JS 파일 수정 → **sw.js 수정 불필요** (network-first라 항상 최신 파일 가져옴)
- Cloudflare 캐시 제거 → 정상 반영됨
- 버전 파라미터 변경 (`?v=5` → `?v=6`) → 브라우저 캐시도 우회

### Cloudflare 캐시와 관계

| 상황 | 동작 |
|------|------|
| CF 캐시 제거 + 일반 파일 수정 | 즉시 반영 (network-first) |
| CF 캐시 제거 + sw.js 수정 | 최대 24시간 후 반영 (브라우저 SW 갱신 주기) |
| 네트워크 끊김 | 이전 방문 페이지만 캐시에서 제공 |
| ?sw-kill 사용 | SW + 캐시 전체 삭제, 원래 웹사이트로 동작 |

## 홈 화면 추가 방법

### iPhone (iOS Safari)
1. Safari에서 tkfb.technicalkorea.net 접속
2. 하단 공유 버튼 (□↑) 탭
3. "홈 화면에 추가" 선택
4. "추가" 탭

### Android (Chrome)
1. Chrome에서 tkfb.technicalkorea.net 접속
2. 자동으로 "홈 화면에 추가" 배너 표시 (또는 메뉴 → "앱 설치")
3. "설치" 탭

## 알려진 제한사항

- **iOS**: tkreport, tkqc 외부 링크 클릭 시 Safari가 별도로 열림 (PWA 한계)
- **iOS**: 백그라운드 동기화 미지원
- **전체**: 완전한 오프라인 지원은 아님 (network-first 전략)