hwistlezz · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026
diff --git a/.env.dev.example b/.env.dev.example
@@ -11,6 +11,19 @@ REDIS_PORT=6379
 
 JWT_SECRET=
 
+# 키 준비와 공개 활성화는 별개다. ingress·정상 트래픽 용량·후보 규모/byte 예산 검증 전 비활성화한다 (#252).
+HASHI_RESTAURANT_MAP_SESSION_ENABLED=false
+HASHI_RESTAURANT_MAP_SESSION_SIGNINGKEY=
+# 지도 전용 Redis. 기존 REDIS_HOST/PORT(인증용)와 별도 인스턴스여야 한다.
+# 로컬 격리 검증용 컨테이너: docker/docker-compose.map-redis.local.yml
+HASHI_RESTAURANT_MAP_REDIS_HOST=
+HASHI_RESTAURANT_MAP_REDIS_PORT=6379
+HASHI_RESTAURANT_MAP_REDIS_SSL=false
+HASHI_RESTAURANT_MAP_REDIS_USERNAME=
+HASHI_RESTAURANT_MAP_REDIS_PASSWORD=
+HASHI_RESTAURANT_MAP_REDIS_CONNECTTIMEOUT=2s
+HASHI_RESTAURANT_MAP_REDIS_TIMEOUT=3s
+
 KAKAO_CLIENT_ID=
 KAKAO_CLIENT_SECRET=
 KAKAO_REDIRECT_URI=
@@ -30,5 +43,12 @@ CLOUDFRONT_DOMAIN=
 CORS_ALLOWED_ORIGINS=http://localhost:5173
 CORS_ALLOWED_ORIGIN_PATTERNS=
 
+# Google Places 관리자 위치 검토는 기본 비활성화다. 실제 비밀값은 이 예시 파일에 기록하지 않는다.
+HASHI_MAP_GOOGLE_PLACES_ENABLED=false
+HASHI_MAP_GOOGLE_PLACES_API_KEY=
+HASHI_MAP_PLACES_SELECTION_ENABLED=false
+HASHI_MAP_PLACES_SELECTION_SIGNING_KEY=
+HASHI_MAP_PLACES_SELECTION_TOKEN_TTL=10m
+
 GRAFANA_ADMIN_USER=admin
 GRAFANA_ADMIN_PASSWORD=''
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -134,14 +134,52 @@ jobs:
         run: ./gradlew clean build --no-daemon
 
       - name: Verify test execution
+        if: ${{ always() }}
         run: |
           python3 - <<'PY'
           from pathlib import Path
+          import re
           import xml.etree.ElementTree as ET
 
           report_root = Path("build/test-results/test")
           reports = sorted(report_root.glob("TEST-*.xml"))
           assert reports, "Test reports are missing"
+
+          java_identifier = r"[A-Za-z_$][A-Za-z0-9_$]*"
+          qualified_identifier = rf"{java_identifier}(?:\.{java_identifier})+"
+          exception_pattern = re.compile(
+              rf"^(?:Caused by:\s+)?({qualified_identifier})(?::|$)"
+          )
+          failed_tests = set()
+          failure_types = []
+          for report in reports:
+              suite = ET.parse(report).getroot()
+              for testcase in suite.findall("testcase"):
+                  outcome = testcase.find("failure")
+                  if outcome is None:
+                      outcome = testcase.find("error")
+                  if outcome is None:
+                      continue
+
+                  class_name = testcase.attrib.get("classname", "<unknown-class>")
+                  stack = outcome.text or ""
+                  frame = re.search(
+                      rf"\bat\s+{re.escape(class_name)}\.([^\s.(]+)\(",
+                      stack,
+                  )
+                  method_name = frame.group(1) if frame else "<unknown-method>"
+                  failed_tests.add(f"{class_name}#{method_name}")
+                  for line in stack.splitlines():
+                      sanitized = line.strip()
+                      exception = exception_pattern.match(sanitized)
+                      if exception and exception.group(1) not in failure_types:
+                          failure_types.append(exception.group(1))
+
+          for failed_test in sorted(failed_tests):
+              print(f"Failed test: {failed_test}")
+          for failure_type in failure_types[:8]:
+              print(f"Failure type: {failure_type}")
+
           assert (report_root / "TEST-org.sopt.hashi.ModularityTests.xml").is_file(), \
               "Module verification did not produce a test report"
 
@@ -156,3 +194,15 @@ jobs:
 
           print(f"Test suites: {len(reports)}, tests: {total}, failures/errors/skips: 0")
           PY
+
+      - name: Upload test diagnostics
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: test-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            build/test-results/test
+            build/reports/tests/test
+            build/reports/problems
+          if-no-files-found: warn
+          retention-days: 7
diff --git a/build.gradle b/build.gradle
@@ -26,6 +26,8 @@ ext {
 dependencies {
     // web / docs
     implementation 'org.springframework.boot:spring-boot-starter-web'
+    // Geocoding: RestClient transport with explicit retry/redirect disabling (Boot-managed version).
+    implementation 'org.apache.httpcomponents.client5:httpclient5'
     implementation 'org.springframework.boot:spring-boot-starter-actuator'
     runtimeOnly 'io.micrometer:micrometer-registry-prometheus'
     // 로그 JSON 인코딩(Loki 수집용) — logback-spring.xml에서 사용
@@ -94,14 +96,23 @@ dependencyManagement {
 
 tasks.named('bootJar') {
     archiveFileName = 'app.jar'
+    mainClass = 'org.sopt.hashi.HashiApplication'
 }
 
 tasks.named('jar') {
     enabled = false
 }
 
 tasks.named('test') {
-    useJUnitPlatform()
+    // The maintenance smoke test launches the same artifact shipped by the existing build.
+    dependsOn tasks.named('bootJar')
+    systemProperty 'location.maintenance.jar', tasks.named('bootJar').get().archiveFile.get().asFile.absolutePath
+    useJUnitPlatform {
+        excludeTags 'map-load', 'map-live'
+    }
+    // Limit retained Spring contexts during the full suite.
+    maxParallelForks = 1
+    systemProperty 'spring.test.context.cache.maxSize', '8'
     testLogging {
         exceptionFormat = 'full'
     }
@@ -116,8 +127,46 @@ tasks.named('test') {
     ).withPropertyName('mediaBackfillInfrastructure')
 }
 
+// Explicit local capacity experiment; ordinary CI remains deterministic and does not require k6.
+tasks.register('mapLoadTest', Test) {
+    description = 'Runs the isolated MySQL/Redis HTTP map workload using a local k6 binary.'
+    group = 'verification'
+    testClassesDirs = sourceSets.test.output.classesDirs
+    classpath = sourceSets.test.runtimeClasspath
+    useJUnitPlatform { includeTags 'map-load' }
+    systemProperty 'map.k6.executable', providers.gradleProperty('k6Executable').getOrElse('k6')
+    systemProperty 'map.k6.script', file('scripts/load/map-query.js').absolutePath
+    systemProperty 'map.k6.output', layout.buildDirectory.dir('reports/map-load').get().asFile.absolutePath
+    systemProperty 'map.k6.profile', providers.gradleProperty('mapLoadProfile').getOrElse('smoke')
+    systemProperty 'map.k6.traffic', providers.gradleProperty('mapLoadTraffic').getOrElse('shared')
+    systemProperty 'map.k6.restaurants', providers.gradleProperty('mapLoadRestaurants').getOrElse('620')
+    systemProperty 'map.k6.budget-mib', providers.gradleProperty('mapLoadBudgetMiB').getOrElse('16')
+    systemProperty 'hashi.restaurant.map.session.limits.concurrent-requests',
+            providers.gradleProperty('mapLoadConcurrentRequests').getOrElse('4')
+    outputs.upToDateWhen { false }
+    maxParallelForks = 1
+    testLogging { exceptionFormat = 'full' }
+}
+
 tasks.named('processResources') {
     from('media-specs') {
         into 'media-specs'
     }
 }
+
+// Real Google is excluded from ordinary CI and requires explicit opt-in plus an environment-only key.
+tasks.register('mapLiveTest', Test) {
+    group = 'verification'
+    testClassesDirs = sourceSets.test.output.classesDirs
+    classpath = sourceSets.test.runtimeClasspath
+    useJUnitPlatform { includeTags 'map-live' }
+    systemProperty 'map.live.enabled', providers.gradleProperty('mapLive').getOrElse('false')
+    outputs.upToDateWhen { false }
+    maxParallelForks = 1
+    doFirst {
+        if (providers.gradleProperty('mapLive').getOrElse('false') != 'true'
+                || !System.getenv('HASHI_MAP_GOOGLEGEOCODING_APIKEY')) {
+            throw new GradleException('mapLiveTest requires -PmapLive=true and an environment API key')
+        }
+    }
+}
diff --git a/docker/docker-compose.dev.yml b/docker/docker-compose.dev.yml
@@ -37,6 +37,17 @@ services:
 
       JWT_SECRET: ${JWT_SECRET}
 
+      HASHI_RESTAURANT_MAP_SESSION_ENABLED: ${HASHI_RESTAURANT_MAP_SESSION_ENABLED:-false}
+      HASHI_RESTAURANT_MAP_SESSION_SIGNINGKEY: ${HASHI_RESTAURANT_MAP_SESSION_SIGNINGKEY:-}
+      # 인증용 REDIS_HOST로 대체하지 않는다. 전용 Redis 준비 전에는 지도 세션을 비활성화한다.
+      HASHI_RESTAURANT_MAP_REDIS_HOST: ${HASHI_RESTAURANT_MAP_REDIS_HOST:-}
+      HASHI_RESTAURANT_MAP_REDIS_PORT: ${HASHI_RESTAURANT_MAP_REDIS_PORT:-6379}
+      HASHI_RESTAURANT_MAP_REDIS_SSL: ${HASHI_RESTAURANT_MAP_REDIS_SSL:-false}
+      HASHI_RESTAURANT_MAP_REDIS_USERNAME: ${HASHI_RESTAURANT_MAP_REDIS_USERNAME:-}
+      HASHI_RESTAURANT_MAP_REDIS_PASSWORD: ${HASHI_RESTAURANT_MAP_REDIS_PASSWORD:-}
+      HASHI_RESTAURANT_MAP_REDIS_CONNECTTIMEOUT: ${HASHI_RESTAURANT_MAP_REDIS_CONNECTTIMEOUT:-2s}
+      HASHI_RESTAURANT_MAP_REDIS_TIMEOUT: ${HASHI_RESTAURANT_MAP_REDIS_TIMEOUT:-3s}
+
       KAKAO_CLIENT_ID: ${KAKAO_CLIENT_ID}
       KAKAO_CLIENT_SECRET: ${KAKAO_CLIENT_SECRET}
       KAKAO_REDIRECT_URI: ${KAKAO_REDIRECT_URI}
@@ -47,6 +58,12 @@ services:
       CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS}
       CORS_ALLOWED_ORIGIN_PATTERNS: ${CORS_ALLOWED_ORIGIN_PATTERNS:-}
 
+      HASHI_MAP_GOOGLE_PLACES_ENABLED: ${HASHI_MAP_GOOGLE_PLACES_ENABLED:-false}
+      HASHI_MAP_GOOGLE_PLACES_API_KEY: ${HASHI_MAP_GOOGLE_PLACES_API_KEY:-}
+      HASHI_MAP_PLACES_SELECTION_ENABLED: ${HASHI_MAP_PLACES_SELECTION_ENABLED:-false}
+      HASHI_MAP_PLACES_SELECTION_SIGNING_KEY: ${HASHI_MAP_PLACES_SELECTION_SIGNING_KEY:-}
+      HASHI_MAP_PLACES_SELECTION_TOKEN_TTL: ${HASHI_MAP_PLACES_SELECTION_TOKEN_TTL:-10m}
+
   prometheus:
     image: prom/prometheus:v2.53.1
     container_name: hashi-dev-prometheus

diff --git a/docker/docker-compose.map-redis.local.yml b/docker/docker-compose.map-redis.local.yml
@@ -0,0 +1,20 @@
+# 로컬 연결 검증 전용. dev/prod compose에 자동으로 추가하지 않는다.
+services:
+  map-redis:
+    image: redis@sha256:858f009f9709ce576febc734aa78b8f6d624b82571f9ddb6bda4377c833b3499
+    command: [redis-server, --maxmemory, 64mb, --maxmemory-policy, noeviction, --appendonly, "no", --save, ""]
+    ports:
+      - "127.0.0.1:16379:6379"
+    mem_limit: 128m
+    memswap_limit: 128m
+    cpus: 0.5
+    healthcheck:
+      test: [CMD, redis-cli, ping]
+      interval: 5s
+      timeout: 2s
+      retries: 3
+    logging:
+      driver: json-file
+      options:
+        max-size: "5m"
+        max-file: "2"
diff --git a/docker/docker-compose.prod.yml b/docker/docker-compose.prod.yml
@@ -40,6 +40,17 @@ services:
 
       JWT_SECRET: ${JWT_SECRET}
 
+      HASHI_RESTAURANT_MAP_SESSION_ENABLED: ${HASHI_RESTAURANT_MAP_SESSION_ENABLED:-false}
+      HASHI_RESTAURANT_MAP_SESSION_SIGNINGKEY: ${HASHI_RESTAURANT_MAP_SESSION_SIGNINGKEY:-}
+      # 인증용 REDIS_HOST로 대체하지 않는다. 전용 Redis 준비 전에는 지도 세션을 비활성화한다.
+      HASHI_RESTAURANT_MAP_REDIS_HOST: ${HASHI_RESTAURANT_MAP_REDIS_HOST:-}
+      HASHI_RESTAURANT_MAP_REDIS_PORT: ${HASHI_RESTAURANT_MAP_REDIS_PORT:-6379}
+      HASHI_RESTAURANT_MAP_REDIS_SSL: ${HASHI_RESTAURANT_MAP_REDIS_SSL:-false}
+      HASHI_RESTAURANT_MAP_REDIS_USERNAME: ${HASHI_RESTAURANT_MAP_REDIS_USERNAME:-}
+      HASHI_RESTAURANT_MAP_REDIS_PASSWORD: ${HASHI_RESTAURANT_MAP_REDIS_PASSWORD:-}
+      HASHI_RESTAURANT_MAP_REDIS_CONNECTTIMEOUT: ${HASHI_RESTAURANT_MAP_REDIS_CONNECTTIMEOUT:-2s}
+      HASHI_RESTAURANT_MAP_REDIS_TIMEOUT: ${HASHI_RESTAURANT_MAP_REDIS_TIMEOUT:-3s}
+
       KAKAO_CLIENT_ID: ${KAKAO_CLIENT_ID}
       KAKAO_CLIENT_SECRET: ${KAKAO_CLIENT_SECRET}
       KAKAO_REDIRECT_URI: ${KAKAO_REDIRECT_URI}
@@ -50,6 +61,12 @@ services:
       CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS}
       CORS_ALLOWED_ORIGIN_PATTERNS: ${CORS_ALLOWED_ORIGIN_PATTERNS:-}
 
+      HASHI_MAP_GOOGLE_PLACES_ENABLED: ${HASHI_MAP_GOOGLE_PLACES_ENABLED:-false}
+      HASHI_MAP_GOOGLE_PLACES_API_KEY: ${HASHI_MAP_GOOGLE_PLACES_API_KEY:-}
+      HASHI_MAP_PLACES_SELECTION_ENABLED: ${HASHI_MAP_PLACES_SELECTION_ENABLED:-false}
+      HASHI_MAP_PLACES_SELECTION_SIGNING_KEY: ${HASHI_MAP_PLACES_SELECTION_SIGNING_KEY:-}
+      HASHI_MAP_PLACES_SELECTION_TOKEN_TTL: ${HASHI_MAP_PLACES_SELECTION_TOKEN_TTL:-10m}
+
       # 운영은 API 문서를 노출하지 않는다 (springdoc.api-docs.enabled / springdoc.swagger-ui.enabled)
       SPRINGDOC_API_DOCS_ENABLED: "false"
       SPRINGDOC_SWAGGER_UI_ENABLED: "false"

diff --git a/docs/adr/0002-restaurant-map-query-and-location.md b/docs/adr/0002-restaurant-map-query-and-location.md
@@ -2,6 +2,7 @@
 
 - 상태: #219에서 채택한 후속 구현 기준. 이 문서의 병합은 기능 구현·운영 활성화를 뜻하지 않는다.
 - 결정일: 2026-09-26
+- 갱신: 2026-10-06, #225에서 좌표 유지와 조회 세션 수명 정책 보완
 - 관련 이슈: [#219](https://github.com/TEAM-HASHI/HASHI-SERVER/issues/219), [#216](https://github.com/TEAM-HASHI/HASHI-SERVER/issues/216)
 - 외부 계약: [Map Contract v1](../map/map-contract-v1.md)
 - 구현·인수 계획: [Implementation Plan](../map/implementation-plan.md)
@@ -65,15 +66,28 @@ M1에서는 새 공개 이벤트를 도입하지 않는다. 같은 모듈 안의
 
 - MySQL: 식당·위치·관광 지역·변환 작업·저장 관계의 원본, BBOX·필터 후보 검색.
 - Redis: 조회 조건, 후보 ID, 추천 순서, 별점·리뷰 수 기준값의 일시적인 조회 세션.
-  생성 후 절대 TTL 15분을 초기 설정으로 채택한다. 읽기·정렬 변경으로 연장하지 않는다.
+  조회 ID별 키 하나와 TTL부터 검증한다. 유휴 5분·최대 수명 30분을 초기값으로 두고,
+  정상적인 다음 페이지 조회·재정렬 때 `min(현재 시각 + 유휴 시간, 최초 생성 + 최대 수명)`으로 갱신한다.
+  유휴 시간은 사용 간격·만료 비율·메모리 측정으로 우선 5~10분 안에서 조정한다. 최적값으로 단정하지 않는다.
 - 세션에 식당 사진·Google 좌표/원본 응답·개인 저장 여부를 복제하지 않는다.
 - 현재 DB의 삭제·위치 수명·필터를 매 페이지 다시 확인한다. 신규 후보·최신 순위는 새 조회부터 반영한다.
+  작은 묶음으로 유효한 10개와 다음 1개를 확보하면 멈추며, 확인한 11번째는 다음 페이지에 남긴다.
 - 유실·만료는 전용 410, Redis 접근 장애는 503으로 구분한다. 새 순서를 기존 cursor에 연결하지 않는다.
 - 세션을 전부 저장할 수 없으면 명시적으로 실패한다. 일부 후보만 성공처럼 저장하지 않는다.
 
 현재 Redis 설정이 있다는 사실은 지도 용량 확보의 증거가 아니다. 인증 토큰과 같은 인스턴스를
 쓴다면 memory·eviction 영향을 확인하고 세션별/전체 admission 한도를 측정한다.
 키 prefix는 메모리 격리 수단이 아니다. 이 결정은 성능 향상이 검증됐다는 뜻이 아니다.
+여러 키로 후보를 나누거나 정렬별 자료구조를 중복 보관하는 최적화는 측정상 필요할 때 검토한다.
+갱신 실패·동시 요청·만료 직후 요청의 규칙과 용량 인수 기준은 [구현 계획](../map/implementation-plan.md)에 둔다.
+
+### 2.4 좌표와 갱신 작업 상태
+
+같은 주소의 갱신은 현재 작업 상태만 바꾸고 기존 검증 좌표·출처·취득/만료 시각을 유지한다.
+유효한 기존 좌표는 갱신 대기·재시도·실패 중에도 사용할 수 있다. 주소 변경 시에는 바로 제거하며,
+새 결과가 검증을 통과했을 때만 교체한다. 만료 시각을 넘겨 사용하거나 실패만으로 수명을 연장하지 않는다.
+정리 작업은 갱신 상태와 관계없이 보관 기한을 지키되 진행 중 작업을 취소하지 않아야 한다.
+이 모델 전이는 #225에서 구현하며, 조회 SQL·worker·수명 정리의 연결은 후속 PR의 공개 전 조건이다.
 
 ## 3. 대안과 영향