모기제로

모기제로는 날씨와 지역 샘플 데이터를 바탕으로 오늘의 모기지수를 보여주는 웹앱입니다.

실행 방법

1. index.html을 브라우저에서 엽니다.
2. 로컬 JSON 파일을 읽기 위해 VS Code의 Live Server 같은 정적 서버를 사용하면 더 안정적입니다.

실제 날씨와 GPS

• 현재 위치 버튼을 누르면 브라우저 GPS로 현재 위치를 가져옵니다.
• 날씨는 Open-Meteo 공개 API를 사용합니다.
• API 요청이 실패하면 샘플 데이터로 자동 전환합니다.

Vercel 배포 방법

1. Vercel에 로그인합니다.
2. 이 폴더를 Git 저장소에 연결하거나 Vercel CLI로 배포합니다.
3. 루트 디렉터리를 그대로 사용하면 됩니다.
4. 이 프로젝트는 빌드 단계가 없는 정적 사이트라서 별도의 build command가 필요하지 않습니다.

CLI를 사용할 경우 예시는 다음과 같습니다.

vercel

안드로이드 앱 (Capacitor) — 2026-10-12

웹사이트를 그대로 안드로이드 앱 안에서 연다. 앱은 실제 사이트(https://mosquito-zero.vercel.app)를 불러오므로 사이트를 고치면 앱도 자동으로 최신이 된다.

• capacitor.config.json: 앱 이름·패키지 이름(com.mosquitozero.app)·여는 주소
• app-shell/index.html: 인터넷이 끊겨 사이트를 못 열 때 보여 주는 화면
• android/: 안드로이드 스튜디오 프로젝트. 위치·카메라 권한은 android/app/src/main/AndroidManifest.xml
• Node.js 는 앱을 만들 때만 쓰고(npx cap ...), 사이트에는 들어가지 않는다. .vercelignore 로 android/ 는 사이트에 올리지 않는다.

처음 받았을 때(저장소에 없는 파일을 만든다): 저장소 폴더에서 npm install → npx cap sync android. 실행: 안드로이드 스튜디오 → Open → android 폴더 → 위쪽 기기 선택 → ▶ Run. 설정을 바꾼 뒤에는 npx cap sync android 를 한 번 실행한다. 뒤로 가기 버튼은 @capacitor/app 플러그인이 처리한다(이전 화면으로, 첫 화면이면 앱 종료). 명령줄 빌드: cd android && ./gradlew assembleDebug (결과: android/app/build/outputs/apk/debug/app-debug.apk).

화면 디자인 v17 "토스 + 애플" (2026-09-29, 현재)

• toss.im 과 apple.com/kr 을 실제로 스크롤하며 캡처해 비교한 뒤 만들었습니다. 참고 캡처는 docs/reference/ 에 있습니다.
• 첫 화면: 토스처럼 화면을 채운 둥근 김해 사진 카드 위에 큰 흰 숫자·표정 얼굴·단계·한 줄 결론.
• 본문: 왼쪽 정렬 큰 제목 + 회색 설명 한 줄. 준비물·도감은 상자 없이 그림 아래 글. "오늘 하루"는 애플식 검정 판, "왜 이 점수일까"는 회색 판으로 명암 리듬을 만듭니다.
• 왼쪽 끝 섹션 눈금(motion.js 의 setupTicks), 24시간 띠는 칸 높이가 지수에 비례합니다.

(이전) 화면 디자인 v16 "애플 웹사이트 방식"

• v15의 날씨 따라 바뀌는 하늘 배경은 폐기했습니다(사용자 결정). 밝은 회색 바탕 + 흰 타일, 가운데 큰 제목, 파란 텍스트 링크, 얇은 반투명 상단 바를 씁니다.
• 김해 사진은 히어로 아래 큰 둥근 카드 하나에 고정으로 두고, 그 위에 24시간 띠를 흰 유리판으로 얹었습니다. weather-bg.js 는 body 의 data-time·data-weather 값만 적고 화면에는 배경을 붙이지 않습니다.
• 단계마다 표정 얼굴(활짝 웃음→크게 찡그림)을 숫자 옆과 5일 전망 칩에 넣었습니다(IQAir·미세미세 참고).

(이전) 화면 디자인 v15 "하늘" (2026-09-29)

• 첫 화면이 지금 하늘입니다. 시각(동틀녘·낮·해질녘·밤)과 날씨(맑음·흐림·비·안개·눈)에 따라 하늘색이 바뀌고, 김해 풍경 사진이 그 아래 녹아듭니다. 색은 design.css 맨 위 body[data-time] · body[data-weather] 토큰에서 바꿉니다.
• 큰 숫자 하나(모기지수) + 단계 칩 + 한 줄 결론 + 오늘 24시간 띠(지금부터 24시간을 색 칸으로) 순서로 보여 줍니다. 띠와 "언제부터 늘어나는지" 한 줄은 app-ui.js 의 renderDayRibbon · renderFlowLine 이 그립니다.
• 정보 묶음은 6개입니다: 오늘 챙길 것 → 오늘 하루(시간대별·나들이·5일) → 우리 동네(지도·순위·공원) → 왜 이 점수일까 → 모기 도감 → 한 마디·제보.
• 가독성 기준: 본문 17px, 보조 글자 15px 이상, 흰 글자 85% 이상, 색 칩은 밝은 바탕에 어두운 글자. 글꼴은 Pretendard(본문) · Geist(숫자) · Baloo 2(워드마크).
• 움직임은 motion.js 한 파일에만 있습니다: 스크롤 등장, 숫자 카운트업, 막대·띠가 자라나는 효과. 시스템의 '움직임 줄이기' 설정을 따릅니다. 2.5초가 지나면 등장 효과와 상관없이 모든 글이 보이도록 안전장치가 있습니다.
• 피그마 파일 "모기제로 홈 v14" 안의 페이지 "홈 v15 (하늘)" 에 데스크톱(1440) 시안과 색 변수 컬렉션 "모기제로 v15 하늘"이 있습니다. 모바일 프레임은 피그마 MCP 호출 한도로 만들지 못했고, 모바일은 CSS(design.css 반응형 구간)에서 직접 설계했습니다.

화면 구성 (2026-09-28 개편)

• 홈(index.html) 한 화면에 거의 모든 정보를 모았습니다: 모기지수, 오늘 챙길 것(준비물), 나들이 지수와 시간대별·5일 예보, 시간대별 모기, 동네 순위, 지도, 가기 좋은 공원, 왜 이 점수인지, 모기 도감, 오늘의 한 마디, 제보 버튼(준비 중).
• forecast.html, guide.html, guide.js는 홈에 합쳐져 삭제했습니다. 메뉴는 홈 · 나들이 · 모기 도감 · 자세히 보기(gimhae.html)입니다. 직원용 전문가 화면은 expert.html(메뉴에 없음).
• 배경은 김해 풍경 사진 두 장(낮·밤)을 실제 일출·일몰 시각에 맞춰 자동으로 바꾸고, 비·안개·구름 등은 사진 위 효과로만 표시합니다. 사진 출처와 라이선스는 assets/bg/CREDITS.md와 홈 하단에 표기했습니다.
• 준비물 기준: 기피제(모기지수 41 이상 또는 12시간 내 61 이상), 선크림(자외선 3 이상), 우산(비 오는 중 또는 강수확률 40% 이상), 물(체감 28도 이상), 마스크(초미세먼지 36 이상 또는 미세먼지 81 이상).
• 사진 판별과 제보 기능은 화면만 있고 아직 동작하지 않습니다(준비 중으로 표시).

포함된 기능

• 기본 화면
• 지역 선택
• 현재 위치 기반 지역 이동
• 모기지수 계산과 단계 표시
• Leaflet 지도와 지역별 마커
• 샘플 날씨 및 지역 데이터 표시
• 사이트 소개 페이지와 모기 정보 페이지 분리
• 실제 날씨와 GPS 위치 연결
• 시간대별 모기지수 예보 차트 (Chart.js, 앞으로 24시간)
• 오늘 하루 중 가장 위험한 시간대와 안전한 시간대 안내
• 김해시 모기 위험 모델 페이지(gimhae.html): 행정 데이터(발생원 시설·방역민원)와 실시간 날씨를 결합해 읍·면·동별 모기지수·발생원 분석·방제 우선순위 제공
• 나들이 지수의 '오늘 조건'(index.html): 식중독지수 · 미세먼지 · 초미세먼지를 함께 표시하고, 미세먼지는 점수 상한에도 반영 (2026-10-07, 이전의 별도 카드 3장은 9/16 개편 때 빠졌음)
• 오늘의 나들이 추천(gimhae.html): 구역에서 가장 쾌적한 공원 1곳 + 김해 관광지·박물관·도서관 중 가장 쾌적한 1곳 안내
• 자세히 보기(gimhae.html, 시민)와 전문가용(expert.html, 직원)은 별도 페이지. 같은 gimhae.js·expert.css 를 쓰고, 전문가용은 body 의 data-audience="expert" 로 방제 약품·발생원 통계 등 직원용 구역까지 펼침. 전문가용은 메뉴·검색에 없고(robots noindex), 직원 로그인이 생기면 직원 계정만 열리게 할 예정
• 모기 정보 페이지 시각 자료: 국내 매개모기 4종 실제 사진, 유충 사진, 발생원·활동시간대 일러스트

모기 잡기 게임 · 회원 · 랭킹 (2026-10-07)

• 첫 화면 모기 잡기에 도전 모드(스테이지 3→10→30→100→300→1,000마리, 제한 시간, 실패해도 누적 유지)와 배지 9개(알→장구벌레→번데기→모기→종류별 모기, 누적 기준)를 넣었습니다. 숫자는 전부 game-config.js 에 있습니다. 게임 코드는 game.js(motion.js 에서 분리).
• 내 배지(me.html): 회원가입·로그인·로그아웃, 내 기록, 배지, 연말 보상 표. 랭킹(ranking.html): 닉네임 랭킹 100위.
• 서버는 Supabase. 표·검증 함수·랭킹 표는 supabase/game-schema.sql, 브라우저 쪽은 auth.js, 주소·공개 키는 api/public-config.js 가 Vercel 환경변수(NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY)에서 내려 줍니다. 서버를 켜기 전에는 계정·랭킹 칸이 "준비 중"으로 보이고 게임·배지는 기기 안에서 그대로 됩니다.
• 켜는 순서, 어뷰징 방지 규칙(하루 30회, 분당 150마리, 마리당 200ms 등), 인제대 서버로 바꿀 때의 API 규격은 docs/게임-서버-규격.md 에 있습니다.
• 직원 계정(profiles.role = 'staff')으로 로그인하면 expert.html 이 열립니다. 서버를 켜기 전에는 주소만 알면 열립니다.

경남 시·군 대표 공원 (2026-10-07)

• 김해 밖 시·군을 고르면 그 시·군 대표 공원 2~3곳을 보여 줍니다(data/gyeongnam-parks.json, 17곳 37개). 공원별 모기 자료가 없어 오늘 나들이 지수와 공원 유형으로만 줄 세우고 화면에 "날씨 기준"이라고 적습니다. 좌표는 OpenStreetMap(Nominatim) 검색값이고 approx: true 는 읍·면 중심 좌표(거리 미표시). 이름은 담당자 확인 전.
• 사진 8장은 위키미디어 공용 CC 사진(assets/parks/CREDITS.md). 나머지는 유형 그림 카드. 한국관광공사 TourAPI(공공데이터포털, 공공누리 1·3유형) 키를 받으면 채울 예정.

김해시 모델 안내

mosquito_model_portable.py(원본 Python 모델)를 브라우저용 mosquito-model.js로 그대로 포팅했습니다. 두 구현의 출력이 동일함을 119개 케이스로 검증했습니다. 페이지(gimhae.html)는 김해시 대표 지점의 실시간 날씨를 입력값으로 사용하며, 실패 시 모델에 내장된 월별 평년값으로 자동 대체합니다.

데이터 안내

실제 모기 관측 API는 아직 연결하지 않았고, 현재는 data/mosquito-sample.json과 data/regions.json의 샘플 데이터를 사용합니다.

나들이 지수의 데이터 출처 (연동 여부)

지수	연동 여부	출처 · 사유
미세먼지(PM10)·초미세먼지(PM2.5)	연동 (예보 모델값)	Open-Meteo 대기질 공개 API(인증키 불필요). 관측소 실측이 아니라 대기질 예보 모델(CAMS) 값이라 화면에 예보로 표시합니다. 지금 값과 시간별 값(2일)을 함께 받습니다. 등급은 환경부 대기환경기준 4단계를 적용
식중독지수	연동하지 않음 (자체 산출)	식약처 식중독예측지도 공공 API는 인증키 발급이 필요해 이 저장소에서 바로 연동할 수 없습니다. 대신 오늘 기온·습도로 자체 산출한 참고값을 쓰고, 화면에 자체 산출로 명시합니다. 단계 이름(관심·주의·경고·위험)만 식약처의 공개 기준을 따랐습니다. 식약처 값을 그대로 가져온 것처럼 표시하지 않습니다

나들이 지수에 반영하는 방식 (2026-10-07)

• 미세먼지는 점수에 상한으로 반영합니다(outing-index.js의 CAPS). 초미세먼지 36 이상 또는 미세먼지 81 이상(환경부 '나쁨')이면 최대 55점('보통'), 초미세먼지 76 이상 또는 미세먼지 151 이상('매우 나쁨')이면 최대 35점('나쁨'). 상한이 걸리면 "초미세먼지 나쁨이라 점수를 낮췄어요"처럼 이유를 보여 줍니다. 시간대별 막대에도 그 시각의 예보값으로 똑같이 적용합니다. 기준은 준비물 '마스크'와 같습니다.
• 식중독지수는 점수에 넣지 않고 '오늘 조건'에 안내 한 줄로만 보여 줍니다. 외출 자체와 관계가 없고, 기온이 이미 점수에 들어가 있어 같은 날씨를 두 번 깎게 되며, 실측이 아닌 자체 산출값이기 때문입니다.
• '오늘 조건'은 기온 · 비 · 자외선 · 모기 · 미세먼지 · 초미세먼지 · 식중독 7줄입니다.

인증키를 발급받아 실제 식약처 값으로 바꾸려면 script.js의 computeFoodPoisoningIndex()를 API 호출로 교체하고, outing-index.js의 식중독 줄 표시를 자체 산출 → 실측으로 바꾸면 됩니다.

관광지 좌표

data/gimhae-attractions.json의 위경도는 OpenStreetMap(Nominatim) 공개 지오코딩 결과입니다. 임의로 추정한 좌표가 아닙니다. 각 장소가 속한 읍·면·동은 모델의 nearestDistrict()로 실행 시점에 배정합니다.

모기 사진 · 일러스트

• assets/mosquito/ — 국내 매개모기 4종과 유충의 실제 사진. 출처와 라이선스는 assets/mosquito/credits.json과 모기 정보 페이지 하단에 표기했습니다. 흰줄숲모기·얼룩날개모기·유충은 미국 질병통제예방센터(CDC, James Gathany) 퍼블릭 도메인, 작은빨간집모기·빨간집모기는 위키미디어 커먼즈 CC BY-SA 4.0입니다.
• assets/illustrations/ — 직접 제작한 SVG 일러스트(발생원 4종, 하루 활동 시간대 그래프, 계산 흐름도).

API 키 안내

날씨 API를 붙일 때는 config.example.js를 복사해 config.js를 만들고 키를 넣으세요.

config.js에는 실제 키가 들어가므로 Git 저장소에 포함하지 않아야 합니다.

AI 도우미(선택) 설정 — api/ask.js

화면 우측 아래 "🦟 모기 도우미"는 사이트 정보로만 답하는 AI 챗봇입니다. 무료로 동작하며, 설정하지 않으면 안내 메시지만 표시됩니다(사이트는 정상 작동).

1. Google AI Studio에서 무료 Gemini API 키를 발급받습니다(카드 등록 불필요).
2. Vercel 프로젝트 → Settings → Environment Variables에 다음을 추가합니다.
   • Name: GEMINI_API_KEY, Value: 발급받은 키
3. 다시 배포(Redeploy)하면 도우미가 켜집니다.

• 키는 서버리스 함수(api/ask.js)에서만 읽혀 브라우저에 노출되지 않습니다.
• 구역 점수 등 숫자는 브라우저가 모델로 계산해 함께 보내므로 AI가 수치를 지어내지 않습니다(환각 방지). 사이트 범위를 벗어난 질문은 정중히 거절합니다.
• 무료 티어에는 하루 요청 한도가 있습니다. 한도를 넘으면 잠시 후 다시 안내 메시지가 나올 수 있습니다.

시민 제보 저장 (Supabase) — 2026-10-05

"여기 모기 있어요" 제보(모기 봤어요 · 물렸어요 · 고인 물 발견)를 Supabase 에 저장하는 서버 함수가 api/report.js 에 있습니다. 기본은 꺼져 있고, 켜기 전에는 아무것도 저장하지 않습니다.

1. Supabase 대시보드 → SQL Editor 에서 supabase/schema.sql 을 실행해 reports 표, 공개용 reports_public 보기, 오래된 제보 삭제 함수를 만듭니다.
2. Vercel 환경변수에 SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY 가 있는지 확인합니다 (Vercel–Supabase 연동 시 자동으로 들어갑니다). service role 키는 서버 함수에서만 쓰고 브라우저로 보내지 않습니다.
3. 위치정보법 절차(위치기반서비스사업 신고, 개인위치정보 이용약관·동의)와 privacy.html 의 빈칸(보관 기간·담당 부서)을 마친 뒤 REPORT_STORE_ENABLED=1 을 넣고 다시 배포합니다.
4. Supabase → Database → Cron 에 select public.purge_old_reports(); 를 매일 실행하도록 등록합니다 (기본 1년 보관).

저장 원칙: 누가 보냈는지(IP·기기)는 저장하지 않고, 위치는 서버에서 약 100m 로 반올림해 저장하며, 공개 지도에는 동 단위 개수만 내보냅니다. 보건소는 review 칸에 확실(confirmed) · 아마도(probable) · 모르겠음(unsure) · 반려(rejected)를 적어 확인합니다 (Mosquito Alert 의 전문가 확인 방식 참고).

모델 v5 서버 함수 — api/model.py (2026-10-06)

저장소 주인이 만든 파이썬 모델 mosquito_model_portable.py(v5, 실측 채집수 학습 모형)를 Vercel 파이썬 서버 함수로 그대로 돌립니다.

• 주소: /api/model (GET). 김해 17개 구역의 오늘 결과를 JSON 으로 돌려줍니다. 날씨는 모델이 Open-Meteo 에서 직접 받습니다(최근 31일 일별).
• 에지 캐시 30분(s-maxage=1800)이라 방문자가 많아도 모델·날씨 호출은 30분에 한 번꼴입니다.
• 브라우저의 model-v5.js 가 이 결과를 받아 화면이 쓰는 자바스크립트 모델(mosquito-model.js, v4)의 답을 v5 기준으로 바꿔 끼웁니다. '지금 조건' 계산은 v5 값을 그대로, 시간별·일별 예보는 v4 의 하루 안 흐름(모양)에 v5 수준을 맞춥니다.
• 서버가 실패하거나 느리면 v4 로 계속 동작하고, v5 가 도착하면 화면을 한 번 더 그립니다. 전문가 화면에 "실측 학습 모형 v5" 배지가 보이면 v5 가 적용된 상태입니다.
• 모델 파일을 갱신하면 그대로 반영됩니다. 로컬 시험: py -3 api/model.py (파이썬 3.9 이상, 표준 라이브러리만 사용).
• 별도 설정 없음. Vercel 이 api/*.py 를 파이썬 함수로 자동 인식합니다.

행정경계 자료 (2026-10-06)

첫 화면 지도의 시·도시 경계와 김해 읍면동 경계는 통계청(KOSTAT) 2013 행정경계(southkorea/southkorea-maps 저장소, "Free to share or remix")를 단순화해 data/city-boundaries.json, data/gimhae-boundary.json 에 넣었습니다. 2013년 당시 장유면은 모델의 '장유'로, 삼안동은 활천동에 합쳤습니다. 화목동은 법정동이라 경계가 없고 점만 찍습니다. 만드는 스크립트는 작업 폴더(scratchpad)의 build-boundaries.js 입니다.