IMJIN 스마트폰 설치·운용 안내

# IMJIN FIELD v0.2 — 스마트폰만으로 설치/사용

## 먼저 확인할 범위

이 파일은 전체 MASTER SPEC을 완성한 상용 앱이 아니라 **PC에 프로그램을 설치하지 않고 사용하는 현장 테스트판**입니다. APK가 아니며 HTTPS 웹앱(PWA)입니다. 공개 배포를 아직 수행하지 않았습니다. 개인 계정 생성/승인은 사용자가 해야 합니다.

- 배포가 끝나면 PC는 꺼져 있어도 됩니다. 앱의 지도/GPS/활동 기록은 스마트폰에서 실행됩니다.
- 공식 API 비밀키가 필요한 요청만 클라우드 함수가 처리합니다.
- 개인 KML, STAND, TARGET, GPS, 조과는 서버에 보내지 않고 휴대폰 IndexedDB에 AES-GCM으로 암호화 저장합니다.
- 클라우드 날씨 조회에는 약 0.02도 격자로 반올림한 선택 포인트 주변 좌표와 일시적인 요청 ID만 전달합니다. 이동 궤적은 전송하지 않습니다.
- 외부 지도를 켜면 IP/지도 표시 영역이 지도 업체에 전달됩니다. 지도는 기본 OFF입니다.
- **방류량·수온·탁도·조위 실시간 조회는 현재 연결 완료가 아닙니다.** 인증키/실제 관측소/현재 API 명세를 확보하고 검증해야 합니다. 표시만 그럴듯하게 채우지 않았습니다.

## A. 앱을 HTTPS로 게시 — PC 없이

준비물: `imjin-smartphone-deploy.zip` 하나. 원본 KML 파일은 여기에 넣지 마세요.

1. 스마트폰에서 ZIP을 다운로드합니다. 압축을 풀 필요가 없습니다.
2. 브라우저에서 https://dash.cloudflare.com/ 을 열고 본인 계정으로 로그인/가입합니다. Free 범위를 사용하고 유료 업그레이드/추가 상품은 선택하지 마세요.
3. **Workers & Pages → Create application → Pages → Get started / Upload assets / Drag and drop your files**에 해당하는 메뉴를 엽니다. Cloudflare UI에 따라 문구가 조금 다를 수 있습니다. 메뉴가 잘리지 않도록 필요하면 브라우저의 ‘데스크톱 사이트’를 사용합니다.
4. 프로젝트 이름을 입력하고, 파일 선택에서 **imjin-smartphone-deploy.zip**을 선택합니다. 이 ZIP은 `index.html`, `sw.js`, `_worker.js`가 ZIP의 최상위에 들어 있습니다.
5. **Deploy site / Save and Deploy**를 누릅니다. 완료 후 실제로 표시된 `https://<프로젝트>.pages.dev` 주소를 엽니다. 이 문서의 예시 주소를 앱 주소로 사용하면 안 됩니다.
6. 첫 화면이 비밀번호 설정 화면인지 확인합니다. `guide.html` 또는 다른 파일 목록만 보이면 ZIP 구조/배포 유형을 확인하세요. Workers 단독 생성 대신 **Pages Direct Upload**를 사용합니다.

공식 문서상 Dashboard는 ZIP을 받고 `_worker.js`도 지원합니다. 반면 일반 `functions/` 폴더는 Dashboard에서 컴파일되지 않습니다. 그래서 업로드 ZIP에 번들된 `_worker.js`를 넣었습니다.

스마트폰에서의 Cloudflare 가입/업로드와 실제 배포 실행은 이 제작 환경에서 검증하지 못했습니다. 계정 제한/모바일 파일선택 문제가 있으면 실제 오류 화면을 기준으로 해결해야 하며, 배포 성공을 미리 보장하지 않습니다.

### 비용

Cloudflare Pages의 정적 파일 요청과 Functions의 무료 범위가 존재합니다. 무료 플랜에서 시작하고 한도/요금은 계정 화면에서 확인하세요. 지도 및 공식 데이터 공급자에는 별도 이용조건이 적용됩니다. 코드가 카드 등록, 결제, 플랜 업그레이드를 실행하지 않습니다.

## B. 스마트폰에 앱 아이콘 만들기

1. 생성된 **HTTPS 앱 주소**를 ChatGPT 내부 웹뷰가 아니라 Chrome(Android) 또는 Safari(iPhone)에서 엽니다.
2. Android: 브라우저 메뉴에서 **홈 화면에 추가 / 앱 설치**를 선택합니다.
3. iPhone: Safari 공유 메뉴에서 **홈 화면에 추가**를 선택합니다.
4. 만들어진 홈 화면 아이콘으로 열고 8자 이상의 저장소 비밀번호를 설정합니다. 비밀번호는 외부에 전송하지 않습니다. 잊으면 복구할 수 없습니다.
5. 같은 주소를 계속 사용하세요. 새 배포 프로젝트/새 도메인은 별도 저장소입니다. 브라우저와 홈 화면 앱이 저장소를 다르게 취급하는 기기가 있으므로 **앞으로 사용할 홈 화면 앱에서 원본을 불러오세요.**

ZIP 안의 `index.html`을 ‘파일’ 앱에서 바로 여는 방식은 사용하지 마세요. HTTPS/Service Worker/GPS 권한이 충족되지 않습니다.

## C. 기존 쏘가리 포인트 넣기

1. 별도 제공된 `ssogari-private-points.kml`을 스마트폰에 다운로드합니다.
2. 앱 **설정 → 원본 포인트 → KML/KMZ/XML 불러오기**에서 해당 파일을 선택합니다.
3. 원본 포인트 **23개**가 보이는지 확인합니다. 동일 이름도 원본대로 남습니다.
4. 파일의 ‘주차위치’ 좌표는 실제 낚시 위치가 아닙니다. STAND/TARGET은 현장에서 별도로 확인/등록하세요.
5. 별도 원본 파일을 바꾸고 싶으면 기존 파일을 고치기보다 새 KML을 가져오세요. 같은 SHA의 재수입은 중복 방지합니다.

원본 KML을 Cloudflare 배포 ZIP이나 공개 웹 폴더에 넣으면 안 됩니다.

## D. 지도와 낚시 기록

1. **설정 → 배경지도 → OpenStreetMap → 적용**. 지도 업체에 표시 영역이 전송되는 데 동의한 뒤 사용합니다.
2. 위성은 본인 Mapbox 공개 토큰(`pk.`)과 사용권이 있을 때만 선택 가능합니다. 토큰의 사용 도메인을 제한하세요. 유료 전환/영상 화질은 보장하지 않으며 자동 오프라인 저장하지 않습니다. 기본 일반지도가 Garmin/Google Earth 수준 위성영상으로 바뀌는 것은 아닙니다.
3. 상단에서 원본 포인트 선택 → **현장 → 위치 사용 시작** → 브라우저 위치 권한 허용.
4. **자리·공략구간**에서 ACCESS/STAND/TARGET을 입력합니다. 원본 참고 좌표까지의 직선 방향을 도보 경로로 해석하지 마세요.
5. **낚시 시작** 또는 **진입 기록** → 안전 미확인/위치 저장 안내 확인. 진입 기록은 이동시간으로, 낚시는 실제 낚시시간으로 구분합니다.
6. **입질 + / 잡음 + / 위치 저장**을 사용합니다. 잡음 좌표는 낚시꾼의 GPS이며 물고기가 물속에서 있었던 좌표가 아닙니다. GPS가 없거나 오래되면 위치 없음으로 기록합니다.
7. 이동/일시정지를 적절히 사용합니다. 원본 포인트를 바꿀 때는 현재 활동을 종료하고 새 활동을 시작해야 포인트별 CPUE가 섞이지 않습니다.
8. **종료·저장 → 기록**에서 경로, 실제 낚시시간, 입질/조과, CPUE, GPX를 확인합니다.

## E. 실시간 데이터 설정 — 숨기지 않은 현재 상태

### E1. 기상청 관측자료 (공식 API)

실제 어댑터 코드가 있습니다. 그러나 사용자 키로 실제 Cloudflare에서 호출하는 통합 검증은 아직 하지 못했습니다.

1. 공공데이터포털의 ‘기상청_단기예보 ((구)_동네예보) 조회서비스’ 이용 신청 후 키를 발급합니다.
https://www.data.go.kr/data/15084084/openapi.do
2. Cloudflare에서 **본인 Pages 프로젝트 → Settings → Variables and Secrets → Add**에 다음을 **Encrypt/Secret**으로 넣습니다.
- `APP_ACCESS_TOKEN`: 본인이 새로 만든 32자 이상 무작위 문자열. 앱 잠금 비밀번호와 다르게 만드세요. 앱 설정의 ‘토큰 생성’ 기능도 사용할 수 있습니다.
- `KMA_SERVICE_KEY`: 공공데이터포털의 **Decoding 인증키**. 코드에서 URL 인코딩을 수행합니다.
3. 값을 저장한 뒤 **Create a new deployment**에서 같은 앱 ZIP을 다시 올립니다. 이미 설정한 Secrets가 반영되는 배포가 필요합니다.
4. 앱 **설정 → 개인 클라우드 연결 토큰**에 동일 `APP_ACCESS_TOKEN`만 입력합니다. `KMA_SERVICE_KEY` 자체를 앱에 입력하지 마세요.
5. **클라우드 상태 확인 → 환경 → 지금 조회**를 누릅니다. 실제 응답, 관측시각, 격자명, 실패 사유를 확인합니다.
6. `NEEDS_KEY`이면 서버 키 설정/재배포를 확인합니다. `UNAUTHORIZED`이면 앱 연결 토큰을 확인합니다. `UNAVAILABLE`이면 실제 제공자 응답/키 권한/발표 주기를 확인해야 합니다.

반환 대상은 기온·습도·풍속·풍향·시간강수입니다. 이 관측 API가 해면기압·수온·방류량을 제공한다고 가정하지 않습니다.

### E2. Open-Meteo 모델 날씨 (선택)

개인 비상업용 이용조건에 해당하는 경우에만 설정의 해당 체크박스를 켜세요. 기온·강수·바람·기압 예측 시간표를 요청합니다. ‘실측’이나 ‘기상청 관측’으로 표시하지 않습니다. 개발 환경에서는 실제 외부 응답을 검증하지 못했습니다. 통신 오류 시 UNAVAILABLE로 남깁니다.

상용 서비스 또는 상업 연구로 이용하기 전 이용조건을 재검토하세요. 이 프로젝트의 향후 상업 목적을 이유로 무료 이용권을 자동으로 인정하지 않습니다.

### E3. 군남댐 방류량 / 하천 수위

**현재 자동 실시간 연결 미완료입니다.** 해당 공식 서비스 이용권, 현재 API 주소·필드·시간대, 군남댐/하류 관측소 식별을 확인해야 합니다. 키만 입력하면 무조건 되는 상태가 아닙니다.

서버에 공식 피드 매핑을 넣는 확장 어댑터를 작성해두었습니다. 전문가/개발자가 현재 문서를 확인해 `OFFICIAL_FEEDS_JSON`을 등록해야 합니다. 앱에는 등록되지 않은 경우 `NEEDS_VERIFIED_CONFIGURATION`이 표시됩니다. 공식 원문 바로가기도 있습니다.

### E4. 수온 / 탁도

**선택한 임진강 포인트에 유효한 실시간 관측소/API를 아직 확보하지 못했습니다.** 기온이나 바다 수온으로 대신하지 않습니다. ‘현장 실측 추가’에서 실제 수온계/탁도계 값, 측정시각, 출처를 기록할 수 있습니다. 장비 없이 추측한 수치를 실측으로 저장하지 마세요.

### E5. 만조 / 간조

공식 조석 API 실시간 연동은 미완료입니다. ‘공식 조석표 수동 기록’에서 본인이 확인한 관측소명·시각·원문 URL을 입력하면 다음 만조/간조와 접근 알림에 사용합니다. **사용자 전사 기록**으로 표시됩니다. 바다 조위관측소의 만조시각이 임진강 해당 자리의 만조/침수시각이라는 뜻이 아닙니다.

## F. 비교와 안전 화면

- 활성화된 검증 규칙이 없으므로 최초 포인트 평가는 **평가 보류**입니다. 임의의 ‘좋음 86점’을 제공하지 않습니다.
- 직접 입력하고 켠 실험 범위 규칙만 점수화합니다. 별도로 ‘사용자 가설 / 미검증’ 표시하며 잡힐 확률이 아닙니다.
- 출입/금어기/군 통제/실시간 수문 경보/침수 예측은 완료되지 않았습니다. ‘경고 없음=안전’이 아닙니다.
- 사용자 통제·폐쇄 기록이 있으면 해당 원본 포인트의 출조 시작/추천 검토를 중단합니다.
- 복귀 알림은 **ACCESS 도착 목표 − 사용자 입력 도보시간 − 사용자 여유시간**입니다. 현장 침수로부터 안전한 최종 시각을 예측한 것이 아닙니다.
- 앱이 켜져 있을 때만 개인 알림을 확인합니다. 화면 꺼짐/다른 앱/통신 끊김 중 실시간 안전감시는 보장하지 않습니다.

## G. 백업·오프라인·전력

- 매 출조 후 **기록 → 암호화 전체 백업**. 파일과 비밀번호를 별도로 보관하세요.
- GPX/KML export는 평문 좌표 파일입니다. 타인에게 공유하면 위치가 공개됩니다.
- 앱을 온라인에서 한 번 정상 로딩한 뒤, 비행기모드에서 아이콘 재실행/비밀번호 해제/기록 열기가 되는지 **출조 전 휴대폰에서 확인**하세요.
- 배경지도 및 실시간 API는 오프라인에서 새로 받을 수 없습니다.
- 화면이 가려지면 기록을 PAUSED/GAP으로 처리하며, 돌아와서 직접 재개합니다. 백그라운드 네이티브 앱 동작을 흉내내지 않습니다.
- 개인정보 저장 키는 메모리에만 있습니다. 브라우저 데이터 삭제/기기 분실/비밀번호 분실 시 복구 불가합니다. 암호화 백업이 필요합니다.
- 장시간 고정밀 GPS/화면 켜짐은 배터리를 사용합니다. 보조배터리를 준비하고 실제 단말에서 확인하세요.

## H. 앱만 배포되었다고 전체 계획이 완성된 것은 아님

React/TypeScript/FastAPI/SQLite 기반 전체 본개발과 다중 사용자/공식 경보/법규/고급 모델/유료서비스/웨어러블은 이 테스트판의 완료 범위가 아닙니다. 이 패키지는 의존성 없는 JavaScript PWA + 경량 클라우드 중계입니다. 원본과 관측/이벤트를 export할 수 있어 후속 본개발에 데이터를 이관할 수 있습니다.

## 공식 참고문서 (2026-09-17 확인)

- Cloudflare ZIP Direct Upload / `_worker.js` 지원: https://developers.cloudflare.com/pages/get-started/direct-upload/
- Cloudflare Secrets와 배포: https://developers.cloudflare.com/pages/functions/bindings/
- Pages Functions 요금: https://developers.cloudflare.com/pages/functions/pricing/
- KMA API: https://www.data.go.kr/data/15084084/openapi.do
- HRFCO 공식 데이터: https://www.data.go.kr/data/3040409/openapi.do
- Open-Meteo 모델/사용조건: https://open-meteo.com/en/docs / https://open-meteo.com/en/terms
- GPS secure context: https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API
- OSM tile policy: https://operations.osmfoundation.org/policies/tiles/