폭염이나 비 오는 날 가까운 쉼터와 편의시설을 찾는 지도 서비스입니다. 전국 공공데이터 15만여 곳을 PostGIS로 검색하고, 최근 제보를 반영한 survival_score로 현재 상태를 함께 보여줍니다.
운영 상태(2026-09-03): Vercel 프론트/BFF는 유지하고 AWS의 백엔드와 운영 데이터를 OCI Ampere A1로 이전했다. 출발·도착 인프라 사양, PITR 데이터 구조, 무결성 검증과 컷오버 절차는 AWS → OCI 무손실 마이그레이션 기록에 공개한다.
지도에서 현재 위치 주변의 쉼터·화장실·카페를 찾고, 목록과 마커를 함께 보며 장소를 고를 수 있습니다.
선택한 장소의 상태·시설·최근 제보를 확인하고, 출발지와 목적지 사이에 그늘 또는 화장실을 경유하는 경로를 찾습니다.
모바일에서는 지도와 바텀시트로 주변 장소를 탐색하고, 상황별 추천으로 바로 갈 곳을 찾습니다. 브라우저로 바로 열거나 PWA와 Android 앱으로 설치해 사용할 수 있습니다. 시나리오 추천을 포함한 다른 화면은 아키텍처 문서에 정리했습니다.
- 공간 검색은 DB 레이어에서 — 반경
ST_DWithin· 최근접 kNN<->· bounds 조회를 PostGIS GiST 인덱스로 처리한다. 프로덕션 저부하 k6(4 VU)에서 반경 p95는 2.68s였고, 태스크 CPU를 0.25→0.5 vCPU로 올린 뒤 ~1.4s가 됐다. 인덱스 경로는 그대로였고 병목은 CPU였다(측정 기록, ADR-0012). 현재 코드는 fingerprint를 고정한 로컬 30만 places에서 p95 1.35s·실패율 0%를 재검증했다(조건이 달라 개선률은 직접 비교하지 않음, ADR-0030). - 멱등 ETL + 지오코딩 —
source + source_external_id자연키로 재실행해도 중복 없는 배치 upsert. 무더위쉼터 60,297 · 공중화장실 52,334 · 도서관 3,551 · 상권 카페/스터디카페 등 전국 표준데이터를 그대로 적재하고, WGS84 결측 좌표는 카카오 지오코딩으로 보완한다. V20 실행 원장은 retry/dead-letter/backfill/freshness를 원본 payload 없이 추적하며, API 부분 응답과 원격 CSV digest 불일치는 DB 변경 전에 실패시킨다(ADR-0030). - 실시간 UGC 시공간 스코어링 — 제보(휘발성 상태)/후기(영구 평판) 2단 UGC를 신뢰도 가중으로
survival_score에 집계. 제보 급증은 PostgresLISTEN/NOTIFY→ 멀티 인스턴스 팬아웃 → SSE로, 관심 장소 알림은INSERT … RETURNING으로 정확히 1회 푸시한다(ADR-0016·0026). - 서버 검증 보안 경계 — private Object Storage 사진은 조건부 PUT과 일회성 claim으로 소유자·용도·실제 object metadata를 확인한 뒤에만 저장하고, 만료 미사용 object는 bounded cleanup한다. JWT login/logout은 같은 user row에서 직렬화하며 DB token version으로 기존 토큰 사본까지 폐기한다. Redis 레이트리밋은 app instance 간 공유한다(ADR-0031).
review와 photo claim은 하나의 transaction으로 commit/rollback하고, 후기에서 제거된 detached 사진은 현재 참조를 재확인한 뒤 cleanup합니다. V21 이전 claim 없는 사진은 기존 후기에서 제거할 수 있지만 자동 cleanup 대상은 아닙니다. 동시 첫 OAuth login·report cache stale reader·cleanup clock skew는 PostgreSQL lock·generation·DB clock을 각 일관성 경계로 삼습니다. 보안 취약점은 공개 issue 대신 GitHub private vulnerability reporting으로 제보해 주세요.
스택: Spring Boot 4 · Java 21 · PostgreSQL+PostGIS · Redis · OCI Ampere A1 · OCI Object Storage · Terraform · Next.js(PWA)
- 웹: 데스크톱과 모바일 브라우저에서 같은 주소로 이용할 수 있습니다. 데스크톱은 지도와 목록을 나란히, 모바일은 지도와 바텀시트 중심으로 구성했습니다.
- 설치: 서비스 워커와 Web App Manifest를 적용한 PWA입니다. Android에서는 브라우저 설치와 서명 APK를, iOS에서는 홈 화면 추가를 지원합니다.
- 구현: 웹과 설치형 앱은 같은 Next.js 클라이언트와 BFF를 사용합니다. 화면 크기에 맞는 UI와 설치 환경에 필요한 서비스 워커·TWA 패키지만 따로 처리했습니다.
브라우저의 애플리케이션 API는 동일 오리진 /api/* 서버 프록시(BFF)만 호출합니다. 사진 바이너리 PUT만 짧게 서명된 URL로 고정 Object Storage gateway에 전달하며, 그 외 공간 검색과 시공간 집계는 DB의 GiST 인덱스와 SQL 뷰에서 처리합니다(ADR-0004, ADR-0032).
상세 다이어그램과 데모는 docs/architecture.md, 현재 서버·서비스·용량은 docs/OCI-RUNTIME.md, 배포는 DEPLOY.md, 이전 증거는 docs/OCI-MIGRATION.md에 있다.
survival_score는 현재 장소 상태를 0~100점과 3색 등급(초록 좋음 / 노랑 보통 / 회색 정보 부족)으로 정리한 값입니다.
survival_score = 0.25·distance + 0.20·comfort + 0.20·freshness − 0.15·risk (+ open_now: 데이터 붙으면 복원)
freshness 버킷: 0~1h=1.0 | 1~3h=0.8 | 오늘=0.6 | 이번주=0.3 | 그 외=0.1
- 시공간 집계는 SQL 뷰(
place_report_signals)가, 가중치 조립·등급은 순수 함수가 담당한다 — 무거운 집계는 DB, 자주 튜닝하는 정책은 테스트 가능한 Java로 분리(ADR-0007). - 제보는 신뢰도(trust) 가중, 만료(휘발성) 제외, 후기(영구 평판)와 분리.
- 없는 성분(운영시간
open_now)은 지어내지 않고 재정규화 — 데이터가 붙으면 가중치 복원만으로 additive 확장. - 추천은 같은 함수를 시나리오 가중치로 재사용한다(ADR-0008).
전국 공공 표준데이터를 멱등(idempotent) 하게 적재한다 — 같은 소스를 두 번 넣어도 source + source_external_id 자연키 upsert라 중복이 없고, 스냅샷에서 사라진 행은 soft-delete로 비활성화된다. 공중화장실은 2025-02 이후 WGS84 좌표 미제공 → 카카오 로컬 API로 주소→좌표를 보완하고 결과를 저장한다(멱등·rate limit 회피). one-off 실행 결과는 DB 원장에 남아 상시 API의 로컬 Prometheus/Grafana 대시보드에서 freshness·부분 실패·재실행 계보를 확인할 수 있다. 상세 흐름은 docs/architecture.md.
| 데이터 | 갱신 정책 |
|---|---|
| 도서관 | 운영 DB에 보존. AWS 월간 scheduler를 폐기한 뒤 OCI 대체 timer가 아직 없어 자동 갱신은 중단 상태 |
| 날씨 | 요청 시 자동. Redis TTL 30분이 지나면 다시 조회 |
| 사용자 제보 | 제출 즉시 반영. 급증은 SSE로 전달 |
| 무더위쉼터·공중화장실 | 수동. 새 CSV 스냅샷을 검증한 뒤 OCI one-off ingestion으로 적재 |
| 카페·스터디카페 | 수동. 원천 데이터 제공 여부와 수집 범위를 확인한 뒤 적재 |
# 1) 인프라 — PostGIS + Redis
docker compose up -d
# 2) 백엔드 — API 문서는 로컬에서만 명시적으로 활성화
cd backend && SPRINGDOC_ENABLED=true ./gradlew bootRun
# 3) 프론트 — http://localhost:3000 (Kakao JS 키 없으면 지도는 placeholder, 데이터는 정상)
cd frontend && pnpm install && pnpm dev공공데이터 적재는 멱등(재실행해도 중복 없음):
cd backend
./gradlew bootRun --args='--ingest.source=cooling_shelter --ingest.file=/path/무더위쉼터.csv --ingest.charset=MS949'# 반경 검색 — 가까운 순 + 거리(m) + survival 배지
GET /places?lat=37.4963&lng=126.9575&radius=1000
# 뷰포트(bounds) 마커 — 무더위쉼터
GET /places?bounds=126.93,37.49,126.97,37.52&category=COOLING_SHELTER
# 최근접(kNN) — 서울 밖 어디서나 동작 (예: 부산)
GET /places/nearest?lat=35.2133&lng=129.0157&category=COOLING_SHELTER&limit=3
# 시나리오 추천 — 거리+실시간 상태로 "지금 갈만한 순" (scenario: rest30|restroom|rain|focus|longstay)
GET /recommendations?lat=37.4963&lng=126.9575&scenario=restroom
# → 각 결과 = 장소(survival 배지) + matchScore(적합도) + reason(제보 요약)
# 휘발성 제보 (익명, 타입별 TTL로 자동 만료 · 분당 3·시간당 10 레이트리밋)
# lat/lng를 함께 보내면 장소 100m 이내일 때 "방문 인증"(verified)
POST /reports {"placeId":1,"reportType":"COOL","comment":"에어컨 빵빵","lat":37.4963,"lng":126.9575}
GET /places/1/reports
# 그늘/화장실 경유 경로 — 현재 위치→도착 사이 우회 최소 쿨링쉼터·화장실 1곳 경유 (ADR-0027)
GET /routes/shade?fromLat=37.50&fromLng=126.95&toLat=37.51&toLng=126.96
# 실시간 제보 급증 알림 — 뷰포트 스냅샷 + SSE 스트림 (ADR-0016)
GET /alerts/surge?bounds=126.93,37.49,126.97,37.52
GET /alerts/stream # text/event-stream (SSE)| Backend | Spring Boot 4 · Java 21 · PostgreSQL + PostGIS(Hibernate Spatial + JTS) · Flyway · Redis |
| Frontend | Next.js 16(App Router) · TypeScript · Tailwind v4 · TanStack Query · Kakao Maps · Serwist(PWA) — frontend/ (README) |
| Infra | Vercel frontend/BFF · OCI Ampere A1 ARM64 rootless Compose · OCI Object Storage · Terraform(infra/oci/) · 폐기된 AWS 구성은 infra/archive/aws/에 보관 |
| Test/Ops | Testcontainers 2(실 PostGIS) · JaCoCo(게이트 70% · 2026-11-09 ./gradlew test jacocoTestReport 로컬 측정 라인 87.33%, 541 tests) · DB/요청 seed 고정 k6+JSON summary · Prometheus/Grafana · gitleaks · CodeQL · Dependabot · 로컬 전용 Swagger |
- 프로젝트 스펙(목표·범위·ERD·API):
docs/SPEC.md - 전체 기능·구현 방식·기술 스택:
docs/FEATURES.md - 아키텍처·데모:
docs/architecture.md· 의사결정 기록(ADR):docs/adr/(0001–0032, 색인) - 트러블슈팅: 브라우저 위치 좌표 지속 저장 제거
- 배포(OCI):
DEPLOY.md· 서버 구조·용량:docs/OCI-RUNTIME.md - AWS → OCI 무손실 이전 사양·실행 기록:
docs/OCI-MIGRATION.md· ADR-0032 - 디자인·API 계약 레퍼런스:
docs/design-brief.md· 프론트엔드:frontend/README.md
구현 이력 (W0 → P5, AWS 항목은 2026-09-03 이전 운영 이력)
- W0 — Spring Boot 4 + PostGIS/Flyway + Testcontainers CI + AWS(ECS Fargate·RDS·Terraform·OIDC) 배포 파이프라인.
- P1 — 반경/kNN/bounds 공간검색 API 라이브 + 공공데이터 멱등 인제스천(쉼터 100건 + 공중화장실 59,768행 파서 → 카카오 지오코딩으로 52,334건 좌표 보완 + 전국 도서관 3,551건).
- P2 · UGC+인증 — 휘발성 제보(11타입·타입별 TTL, 레이트리밋 XFF/OOM 하드닝 TS-008) · 소셜 로그인(카카오/구글 OAuth2+JWT, BFF code 교환) · 후기(review) 영구 평판(로그인, 장소당 1건 upsert) · 사진 presign(S3 SigV4, image 화이트리스트) · trust_score 실배선(로그인 제보 user_id 가중, V6) · 모더레이션(신고 + ADMIN 검수 큐, V7).
- P3 · 스코어·추천·AI·데이터 —
survival_score(SQL 뷰 + 순수 함수, 마커 3색, ADR-0007) · 시나리오 추천 ADR-0008 · 날씨(기상청 초단기실황 + Redis TTL 캐시) + comfort 복원(ADR-0009) · AI 한줄요약(프로바이더 중립 OpenAI 호환 클라이언트, graceful degradation, ADR-0010) · 공부공간 데이터 확장(CAFE/STUDY_CAFE·soft-delete, V5, ADR-0006) · AWS 운영 당시 주기동기화(EventBridge→ECS RunTask + advisory lock, ADR-0011; OCI 대체 timer는 후속). - P4 · 성능·관측성 — k6 부하테스트 + EXPLAIN 인덱스 튜닝(반경/kNN/bounds GiST 사용 실증, V8 만료제보 인덱스, ADR-0012) · AWS 운영 당시 ECS Service Auto Scaling(CPU target-tracking, ADR-0013)과 CloudFront 무료 HTTPS(ADR-0015) · 관측성(Micrometer/Prometheus + OTel 트레이싱 + 로컬 Grafana/Tempo, ADR-0014).
- P4 · 실시간·커뮤니티 — 실시간 제보 급증 알림(Postgres LISTEN/NOTIFY→SSE, 멀티 인스턴스 팬아웃, V9, ADR-0016) · 시간대별 혼잡 파생(자체 popular-times) · GPS 방문 인증(
verified, ST_DWithin 100m, V10) · 추천 시나리오 focus/longstay · 후기 커뮤니티(댓글·리액션, V11) · 모더레이션 확장(신고 RESOLVED→콘텐츠 숨김, V12) · JaCoCo 0.70 게이트. - 데이터 커버리지(2026-07) — 화장실 52,334 · 무더위쉼터 60,297 · 상권 카페/스터디카페(서울 + 6대 광역시 + 9개 도시) · 도서관 3,551. 총 15만+곳.
- 기능 확장(PR #61~#99) — 시설 comfort SQL 통합(V13, ADR-0017) · 쉼터 냉방 백필 · 급증 SSE 프론트 · popular-times 히트맵 · bookmarks(V14) · 알림(V15, ADR-0018) · 화장실/그늘 경유 경로(ADR-0019·0027, 도로 폴리라인 ADR-0021) · Web Push(ADR-0022) · 팔로우(V17·ADR-0023) · 그늘/비 corridor(ADR-0024) · 부하 기반 튜닝(V18·ADR-0025) · 데스크톱 3분할 · 신고/모더레이션 프론트 · a11y 포커스 트랩 · 관심장소 상태변화 알림(ADR-0026).
- P5 · 배포 — PWA 설치(/install) — 안드로이드 WebAPK 원탭 + 다운로드 서명 APK(
/geuneul.apk, Bubblewrap TWA +assetlinks.json도메인 검증) + iOS 홈 화면 추가. 개인정보처리방침.
MIT © 2026 ghdtjdwn


