feat(admin): #356 후속 — verifyAllAsync로 즉시 응답

- 1244 링크 백필 동기 호출 시 HTTP 25~30분 hang (ingress 5분 timeout 초과)
- @Async verifyAllAsync 추가, controller는 started/pending 즉시 응답
- 진행은 /api/admin/video-relevance/pending 폴링으로 확인

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CHANGELOG.md

@@ -4,8 +4,123 @@
 
 ---
 
+## 2026-06-16
+
+### 🗺️ NaverMapView 안정화 + 재활성 (v0.1.57)
+- divRef 항상 마운트 (이전: ready 가드로 첫 렌더 ref 누락 가능)
+- 명시적 width/height + 회색 배경(시각적 로딩 표시)
+- ResizeObserver + requestAnimationFrame으로 컨테이너 0×0 → 정상 크기 시 refresh
+- try/catch + initError state로 init 실패 가시화
+- Naver 키 재활성
+
+### ⏪ NaverMap 임시 비활성, 한국도 GoogleMap fallback (v0.1.55)
+- NaverMapView 골격이 실 운영에서 지도/마커 렌더 실패 (정확한 원인 추후 진단)
+- NEXT_PUBLIC_NAVER_MAP_CLIENT_ID 빈 값으로 dispatcher가 GoogleMap fallback (회귀 0)
+- NaverMapView 코드는 유지 — 안정화 후 환경변수 채우면 재활성
+
+### 🐛 /api/stats/visits 500 — StatsMapper resultType int → long (v0.1.54)
+- StatsMapper interface는 `long` 반환인데 XML resultType이 `int` → Integer를 long에 cast 실패
+- ClassCastException: Integer → Long. resultType만 long으로 교정
+
+### 🐛 NaverMap 인증 파라미터 ncpClientId → ncpKeyId (v0.1.53)
+- NCLOUD 신 정책: `ncpKeyId` 사용 (옛 `ncpClientId`는 NAVER Developers용)
+- 인증 200/Failed의 진짜 원인 — 도메인 등록은 정확했으나 파라미터 이름 차이로 키 인식 실패
+- 새 NCLOUD Maps Client ID(`fg01bipxbo`)로 prod 재빌드
+- 참고: https://github.com/navermaps/maps.js.ncp/blob/master/index.html
+
+### 🗺️ #363 메인 지도 SDK 국내(네이버)/해외(구글) 분기 (v0.1.52)
+- MapView를 dispatcher로 전환: 좌표가 KR bbox + NAVER_MAP_CLIENT_ID 설정 시 NaverMapView, 그 외 GoogleMapView
+- NaverMapView 신규 (네이버 v3 직접 wrapper, Supercluster 재사용, 마커/클러스터/flyTo)
+- GoogleMapView 신규 (기존 MapView 내용 rename)
+- MapView.types.ts 공용 (MapBounds/FlyTo/MapViewProps + isKoreaCoord)
+- Dockerfile + deploy.sh: NEXT_PUBLIC_NAVER_MAP_CLIENT_ID build-arg 추가
+- 키 미설정 시 GoogleMap fallback (회귀 0)
+- 설계서: docs/design/363-map-sdk-branch/README.md
+- Refs: #363
+
+### 🗺️ 식당 상세 지도 링크 국내/해외 분기 (v0.1.51)
+- 좌표 기반 한국 판정 (WGS84 KR bbox 33~38.7°N, 124~132°E)
+- 국내: 네이버 지도 primary + Google Maps 보조 (네이버 URL은 신 도메인 /p/search/)
+- 해외: Google Maps 단독
+- 좌표 없으면 region 첫 토큰 fallback (구 데이터 호환)
+- frontend-only 배포
+
 ## 2026-06-15
 
+### 🐛 캐치테이블 URL 패턴 수정 (v0.1.50)
+- 실제 catchtable URL은 `app.catchtable.co.kr/ct/shop/...` 형식 (옛 `/shop/`, `/dining/`은 매칭 실패)
+- 첫 회차(v0.1.49) 캐치테이블 벌크 결과 1044건 전부 미발견(매핑 0%)의 원인
+- 패턴을 `catchtable.co.kr/ct/shop/`, `catchtable.co.kr/ct/dining/`로 교정 후 NONE 해제 + 재실행
+
+### 🐛 WebSearchService HTTP timeout 추가 (v0.1.49)
+- 벌크 백필 중 특정 검색에서 무한 hang → backend executor virtual thread 점유로 후속 작업 중단 (90건 처리 후 멈춤)
+- connectTimeout=5s + request timeout=15s (Naver/DDG 둘 다)
+- 해당 식당은 HttpTimeoutException → notfound로 안전 처리
+
+### ⏱️ bulk-tabling/catchtable SSE timeout 10분 → 3시간 (v0.1.48)
+- 대량 백필(724건 ≈ 100분) 시 10분 SSE timeout으로 중간 끊김 → 3시간으로 확장
+- 백엔드 작업은 virtual thread로 별도 진행됐지만 emit() 예외로 마지막 cache.flush + complete 누락이슈 해소
+
+### 🐛 #357 후속 — tabling-url validation에 www. 호스트 허용 (v0.1.47)
+- Naver/DDG 결과가 `https://www.tabling.co.kr/...` 형태인데 #290 validation은 `tabling.co.kr/`만 허용 → 단건 매핑 PUT 거부
+- bulk-tabling SSE는 validation 없이 service.update 직접 호출이라 통과 → 단일/벌크 불일치
+- `www.tabling.co.kr` prefix도 허용 (catchtable은 이미 app/www 둘 다 허용)
+- 시연 등록: bbq 부천은하마을점 → BBQ 치킨 부천은하마을점
+
+### 🔍 #359 1단계 — google_place_id 중복 조회 API (v0.1.46)
+- GET /api/admin/restaurants/duplicates/place-id (어드민 전용)
+- 응답: 그룹별 식당 + video/review/memo 카운트 (병합 의사결정 자료)
+- 정리/병합 + UNIQUE 제약은 별도 PR (데이터 위험 분리)
+- 설계서: docs/design/359a-duplicate-place-id-view/README.md
+- Refs: #359 (조회 단계 완료, 후속 분리 유지)
+
+### 📋 #358 RestaurantUpdateDTO + @Valid 표준화 (v0.1.45)
+- dto/RestaurantUpdateDTO record 신규 (15 필드, 모두 nullable)
+- Bean Validation: @Size/@Pattern(URL or NONE)/@DecimalMin·Max/@Min·Max
+- RestaurantController.update 시그니처 Map → @Valid DTO 교체
+- toFieldMap()으로 null 제외 후 기존 Service.update 호출 (회귀 0)
+- #332 ALLOWED_UPDATE_FIELDS Set 제거 (DTO 필드 자체가 화이트리스트)
+- 설계서: docs/design/358-restaurant-update-dto/README.md
+- Refs: #358 (close)
+
+### 🔎 #357 DDG → Naver Search 정식 API + DDG 폴백 (v0.1.44)
+- WebSearchService 신규 (Naver webkr.json 우선, 키 미설정/실패 시 DDG 폴백)
+- RestaurantController.searchTabling/searchCatchtable 내부 호출 교체, DDG 인라인 80줄 제거
+- application.yml: app.naver.client-id/secret (NAVER_CLIENT_ID/SECRET 환경변수)
+- k8s/secrets.yaml.template에 NAVER_CLIENT_ID/SECRET 항목 추가
+- 미사용 import 정리 (HttpClient/URI/URLEncoder/Pattern 등 RestaurantController에서)
+- 설계서: docs/design/357-web-search-api/README.md
+- Refs: #357 (close)
+
+### 🎯 #356 영상-식당 관련도 LLM 평가 (v0.1.43)
+- DB: video_restaurants 컬럼 추가 (relevance/relevance_reason/relevance_evaluated_at) + idx_vr_relevance
+- VideoRelevanceService 신규 (#322 RestaurantVerifyService 패턴 모방, @Async verifyAsync/verify/verifyAll)
+- PipelineService.processExtract — linkVideoRestaurant 후 verifyAsync(linkId) 자동 트리거
+- GET /api/restaurants/{id}/videos: 기본 strong/unknown만 응답 (안전 기본값), ?include_weak=true 시 모두
+- AdminVideoRelevanceController 신규 (pending/all/{id}/evaluate/{id} PATCH)
+- 응답 매핑: relevance, relevance_reason 필드 동봉
+- 기존 1244 링크는 'unknown' 시작 → 어드민 백필로 점진 평가
+- 설계서: docs/design/356-video-relevance-llm/README.md
+- Refs: #356 (close)
+
+### 🧹 #351 admin SSE 6곳 consumeSseStream 통일 (v0.1.42)
+- VideosPanel 4곳(bulkTranscript/Extract, rebuildVectors, remapCuisine, remapFoods)
+- RestaurantsPanel 2곳(bulkTabling, bulkCatchtable)
+- response.body?.getReader 직접 호출 0건 (lib/admin-utils.ts의 consumeSseStream 활용)
+- 149줄 삭제 → 74줄 압축, npm test 13/13 통과
+- Refs: #351 (close)
+
+### 🧪 #343 Jest+RTL 인프라 + ARIA Tabs + remotePatterns (v0.1.40)
+- Jest 30 + jest-environment-jsdom + RTL + jest-dom matchers 도입
+- next/jest 자동 SWC 통합, jest.config.ts + jest.setup.ts (setupFilesAfterEnv)
+- npm scripts: test, test:watch
+- 샘플 테스트 3개 13/13 통과: i18n/config(5), Stars(5), admin-utils(4)
+- MyReviewsList: role=tablist/tab/aria-selected/aria-controls/tabIndex + tabpanel
+- next.config.ts remotePatterns: Google avatar + YouTube thumbnail/avatar
+- 후속: 전체 컴포넌트 테스트 확장, 백엔드 JUnit, E2E(Playwright), CI 통합
+- 설계서: docs/design/343-frontend-test-infra/README.md
+- Refs: #343 (close)
+
 ### 🔤 #348 isNameSimilar 한국어 자모 + Sørensen-Dice (v0.1.38)
 - HangulSimilarity 유틸 신규 (Unicode NFD 분해 + bigram Sørensen-Dice)
 - RestaurantController.isNameSimilar 교체, 임계값 0.45

backend-java/src/main/java/com/tasteby/controller/AdminRestaurantController.java

@@ -62,6 +62,15 @@ public class AdminRestaurantController {
         return Map.of("success", true, "id", id);
     }
 
+    // #359 1단계 — google_place_id 중복 조회 (정리/UNIQUE는 후속).
+    @GetMapping("/duplicates/place-id")
+    public Map<String, Object> duplicatePlaceIds() {
+        var admin = AuthUtil.requireAdmin();
+        var groups = restaurantService.findDuplicatePlaceIdGroups();
+        log.info("[ADMIN] {} duplicate place_id groups: {}", admin.getSubject(), groups.size());
+        return Map.of("groups", groups, "group_count", groups.size());
+    }
+
     /**
      * 어드민용 hidden 토글.
      */

backend-java/src/main/java/com/tasteby/controller/AdminVideoRelevanceController.java

@@ -0,0 +1,70 @@
+package com.tasteby.controller;
+
+import com.tasteby.security.AuthUtil;
+import com.tasteby.service.RestaurantService;
+import com.tasteby.service.VideoRelevanceService;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * #356 영상-식당 관련도 LLM 평가 어드민 API.
+ * - 미평가 카운트 / 일괄 백필 / 단건 재평가 / 수동 토글
+ */
+@RestController
+@RequestMapping("/api/admin/video-relevance")
+public class AdminVideoRelevanceController {
+
+    private static final Logger log = LoggerFactory.getLogger(AdminVideoRelevanceController.class);
+    private static final Set<String> VALID = Set.of("strong", "weak", "incidental", "unknown");
+
+    private final RestaurantService restaurantService;
+    private final VideoRelevanceService relevanceService;
+
+    public AdminVideoRelevanceController(RestaurantService restaurantService, VideoRelevanceService relevanceService) {
+        this.restaurantService = restaurantService;
+        this.relevanceService = relevanceService;
+    }
+
+    @GetMapping("/pending")
+    public Map<String, Object> pendingCount() {
+        var admin = AuthUtil.requireAdmin();
+        int n = restaurantService.countUnevaluatedLinks();
+        log.info("[ADMIN] {} video-relevance pending: {}", admin.getSubject(), n);
+        return Map.of("pending", n);
+    }
+
+    @PostMapping("/all")
+    public Map<String, Object> verifyAll(@RequestParam(defaultValue = "10") int batchSize) {
+        var admin = AuthUtil.requireAdmin();
+        int pending = restaurantService.countUnevaluatedLinks();
+        log.info("[ADMIN] {} triggered video-relevance verifyAllAsync (batchSize={}, pending={})", admin.getSubject(), batchSize, pending);
+        // 비동기 트리거 — HTTP request는 즉시 응답. 진행은 /pending 폴링으로 확인.
+        relevanceService.verifyAllAsync(batchSize);
+        return Map.of("started", true, "pending", pending);
+    }
+
+    @PostMapping("/{linkId}/evaluate")
+    public Map<String, Object> evaluateOne(@PathVariable String linkId) {
+        var admin = AuthUtil.requireAdmin();
+        log.info("[ADMIN] {} video-relevance evaluate({})", admin.getSubject(), linkId);
+        relevanceService.verify(linkId);
+        return Map.of("success", true, "linkId", linkId);
+    }
+
+    @PatchMapping("/{linkId}")
+    public Map<String, Object> setRelevance(@PathVariable String linkId, @RequestBody Map<String, Object> body) {
+        var admin = AuthUtil.requireAdmin();
+        Object relObj = body.get("relevance");
+        if (!(relObj instanceof String relevance) || !VALID.contains(relevance)) {
+            return Map.of("success", false, "error", "relevance must be one of strong|weak|incidental|unknown");
+        }
+        String reason = body.get("reason") instanceof String s ? s : "manual";
+        restaurantService.updateLinkRelevance(linkId, relevance, reason);
+        log.info("[ADMIN] {} manual relevance={} for link {}", admin.getSubject(), relevance, linkId);
+        return Map.of("success", true, "linkId", linkId, "relevance", relevance);
+    }
+}

backend-java/src/main/java/com/tasteby/controller/RestaurantController.java

@@ -4,9 +4,12 @@ import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.tasteby.domain.Restaurant;
 import com.tasteby.security.AuthUtil;
+import com.tasteby.dto.RestaurantUpdateDTO;
 import com.tasteby.service.CacheService;
 import com.tasteby.service.GeocodingService;
 import com.tasteby.service.RestaurantService;
+import com.tasteby.service.WebSearchService;
+import jakarta.validation.Valid;
 import jakarta.annotation.PreDestroy;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -15,19 +18,10 @@ import org.springframework.web.bind.annotation.*;
 import org.springframework.web.server.ResponseStatusException;
 import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
 
-import java.net.URI;
-import java.net.URLDecoder;
-import java.net.URLEncoder;
-import java.net.http.HttpClient;
-import java.net.http.HttpRequest;
-import java.net.http.HttpResponse;
-import java.nio.charset.StandardCharsets;
 import java.util.*;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 import java.util.concurrent.ThreadLocalRandom;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
 
 @RestController
 @RequestMapping("/api/restaurants")
@@ -39,13 +33,15 @@ public class RestaurantController {
     private final GeocodingService geocodingService;
     private final CacheService cache;
     private final ObjectMapper objectMapper;
+    private final WebSearchService webSearch;
     private final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
 
-    public RestaurantController(RestaurantService restaurantService, GeocodingService geocodingService, CacheService cache, ObjectMapper objectMapper) {
+    public RestaurantController(RestaurantService restaurantService, GeocodingService geocodingService, CacheService cache, ObjectMapper objectMapper, WebSearchService webSearch) {
         this.restaurantService = restaurantService;
         this.geocodingService = geocodingService;
         this.cache = cache;
         this.objectMapper = objectMapper;
+        this.webSearch = webSearch;
     }
 
     // #290 — Bean 종료 시 virtual thread executor를 정리하여 리소스 누수 방지.
@@ -90,30 +86,14 @@ public class RestaurantController {
         return r;
     }
 
-    // #332 — Restaurant 업데이트 화이트리스트 (SQL updateFields의 컬럼 가드와 1:1).
-    // 허용되지 않은 키는 무시(silent drop). DTO 도입은 후속 작업.
-    private static final java.util.Set<String> ALLOWED_UPDATE_FIELDS = java.util.Set.of(
-            "name", "address", "region", "cuisine_type", "price_range",
-            "phone", "website", "tabling_url", "catchtable_url",
-            "latitude", "longitude", "google_place_id",
-            "business_status", "rating", "rating_count"
-    );
-
     @PutMapping("/{id}")
-    public Map<String, Object> update(@PathVariable String id, @RequestBody Map<String, Object> body) {
+    public Map<String, Object> update(@PathVariable String id, @Valid @RequestBody RestaurantUpdateDTO dto) {
         AuthUtil.requireAdmin();
         var r = restaurantService.findById(id);
         if (r == null) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Restaurant not found");
 
-        // #332 — 입력 body를 허용 키만 통과시킨 가변 Map으로 정규화
-        Map<String, Object> sanitized = new java.util.LinkedHashMap<>();
-        for (var e : body.entrySet()) {
-            if (ALLOWED_UPDATE_FIELDS.contains(e.getKey())) {
-                sanitized.put(e.getKey(), e.getValue());
-            } else {
-                log.debug("Ignoring non-whitelisted update field: {}", e.getKey());
-            }
-        }
+        // #358 — DTO → Map (null 제외). 화이트리스트는 DTO 필드 자체로 표현.
+        Map<String, Object> sanitized = dto.toFieldMap();
 
         // Re-geocode if name or address changed
         String newName = (String) sanitized.get("name");
@@ -195,7 +175,7 @@ public class RestaurantController {
     @PostMapping("/bulk-tabling")
     public SseEmitter bulkTabling() {
         AuthUtil.requireAdmin();
-        SseEmitter emitter = new SseEmitter(600_000L);
+        SseEmitter emitter = new SseEmitter(10_800_000L); // 3h — 대량 백필 대응
 
         executor.execute(() -> {
             try {
@@ -272,8 +252,11 @@ public class RestaurantController {
         if (r == null) throw new ResponseStatusException(HttpStatus.NOT_FOUND);
         String url = body.get("tabling_url");
         // #290 — javascript:/외부 악성 URL 차단. 빈 문자열은 매핑 해제로 허용.
-        if (url != null && !url.isBlank() && !url.startsWith("https://tabling.co.kr/")) {
-            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "테이블링 URL은 https://tabling.co.kr/ 만 허용");
+        // Naver/DDG 결과가 www.tabling.co.kr 형태로도 옴.
+        if (url != null && !url.isBlank()
+                && !url.startsWith("https://tabling.co.kr/")
+                && !url.startsWith("https://www.tabling.co.kr/")) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "테이블링 URL은 https://(www.)tabling.co.kr/ 만 허용");
         }
         restaurantService.update(id, Map.of("tabling_url", url != null ? url : ""));
         cache.flush();
@@ -326,7 +309,7 @@ public class RestaurantController {
     @PostMapping("/bulk-catchtable")
     public SseEmitter bulkCatchtable() {
         AuthUtil.requireAdmin();
-        SseEmitter emitter = new SseEmitter(600_000L);
+        SseEmitter emitter = new SseEmitter(10_800_000L); // 3h — 대량 백필 대응
 
         executor.execute(() -> {
             try {
@@ -413,8 +396,10 @@ public class RestaurantController {
     }
 
     @GetMapping("/{id}/videos")
-    public List<Map<String, Object>> videos(@PathVariable String id) {
-        String key = cache.makeKey("restaurant_videos", id);
+    public List<Map<String, Object>> videos(
+            @PathVariable String id,
+            @RequestParam(name = "include_weak", defaultValue = "false") boolean includeWeak) {
+        String key = cache.makeKey("restaurant_videos", id, includeWeak ? "all" : "strong");
         String cached = cache.getRaw(key);
         if (cached != null) {
             try {
@@ -423,100 +408,25 @@ public class RestaurantController {
         }
         var r = restaurantService.findById(id);
         if (r == null) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Restaurant not found");
-        var result = restaurantService.findVideoLinks(id);
+        var result = restaurantService.findVideoLinks(id, includeWeak);
         cache.set(key, result);
         return result;
     }
 
-    // ─── DuckDuckGo HTML search helpers ─────────────────────────────────
+    // ─── 예약 사이트 URL 검색 (#357 WebSearchService: Naver primary + DDG fallback) ───
 
-    private static final HttpClient httpClient = HttpClient.newBuilder()
-            .followRedirects(HttpClient.Redirect.NORMAL)
-            .build();
-
-    private static final Pattern DDG_RESULT_PATTERN = Pattern.compile(
-            "<a[^>]+class=\"result__a\"[^>]+href=\"([^\"]+)\"[^>]*>(.*?)</a>",
-            Pattern.DOTALL
-    );
-
-    /**
-     * DuckDuckGo HTML 검색을 통해 특정 사이트의 URL을 찾는다.
-     * html.duckduckgo.com은 서버사이드 렌더링이라 봇 판정 없이 HTTP 요청만으로 결과를 파싱할 수 있다.
-     */
-    private List<Map<String, Object>> searchDuckDuckGo(String query, String... urlPatterns) throws Exception {
-        String encoded = URLEncoder.encode(query, StandardCharsets.UTF_8);
-        String searchUrl = "https://html.duckduckgo.com/html/?q=" + encoded;
-        log.info("[DDG] Searching: {}", query);
-
-        HttpRequest request = HttpRequest.newBuilder()
-                .uri(URI.create(searchUrl))
-                .header("User-Agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36")
-                .header("Accept", "text/html,application/xhtml+xml")
-                .header("Accept-Language", "ko-KR,ko;q=0.9")
-                .GET()
-                .build();
-
-        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
-        String html = response.body();
-
-        List<Map<String, Object>> results = new ArrayList<>();
-        Set<String> seen = new HashSet<>();
-        Matcher matcher = DDG_RESULT_PATTERN.matcher(html);
-
-        while (matcher.find() && results.size() < 5) {
-            String href = matcher.group(1);
-            String title = matcher.group(2).replaceAll("<[^>]+>", "").trim();
-
-            // DDG 링크에서 실제 URL 추출 (uddg 파라미터)
-            String actualUrl = extractDdgUrl(href);
-            if (actualUrl == null) continue;
-
-            boolean matches = false;
-            for (String pattern : urlPatterns) {
-                if (actualUrl.contains(pattern)) {
-                    matches = true;
-                    break;
-                }
-            }
-            if (matches && !seen.contains(actualUrl)) {
-                seen.add(actualUrl);
-                results.add(Map.of("title", title, "url", actualUrl));
-            }
-        }
-
-        log.info("[DDG] Found {} results for '{}'", results.size(), query);
-        return results;
-    }
-
-    /** DDG 리다이렉트 URL에서 실제 URL 추출 */
-    private String extractDdgUrl(String ddgHref) {
-        try {
-            // //duckduckgo.com/l/?uddg=ENCODED_URL&rut=...
-            if (ddgHref.contains("uddg=")) {
-                String uddgParam = ddgHref.substring(ddgHref.indexOf("uddg=") + 5);
-                int ampIdx = uddgParam.indexOf('&');
-                if (ampIdx > 0) uddgParam = uddgParam.substring(0, ampIdx);
-                return URLDecoder.decode(uddgParam, StandardCharsets.UTF_8);
-            }
-            // 직접 URL인 경우
-            if (ddgHref.startsWith("http")) return ddgHref;
-        } catch (Exception e) {
-            log.debug("[DDG] Failed to extract URL from: {}", ddgHref);
-        }
-        return null;
-    }
-
-    private List<Map<String, Object>> searchTabling(String restaurantName) throws Exception {
-        return searchDuckDuckGo(
+    private List<Map<String, Object>> searchTabling(String restaurantName) {
+        return webSearch.search(
                 "site:tabling.co.kr " + restaurantName,
                 "tabling.co.kr/restaurant/", "tabling.co.kr/place/"
         );
     }
 
-    private List<Map<String, Object>> searchCatchtable(String restaurantName) throws Exception {
-        return searchDuckDuckGo(
+    private List<Map<String, Object>> searchCatchtable(String restaurantName) {
+        // 실제 캐치테이블 URL은 /ct/shop/ 형식. 옛 /dining/ /shop/ 패턴은 매칭 실패.
+        return webSearch.search(
                 "site:app.catchtable.co.kr " + restaurantName,
-                "catchtable.co.kr/dining/", "catchtable.co.kr/shop/"
+                "catchtable.co.kr/ct/shop/", "catchtable.co.kr/ct/dining/"
         );
     }
 

backend-java/src/main/java/com/tasteby/dto/RestaurantUpdateDTO.java

@@ -0,0 +1,94 @@
+package com.tasteby.dto;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import jakarta.validation.constraints.DecimalMax;
+import jakarta.validation.constraints.DecimalMin;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+
+import java.math.BigDecimal;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * #358 식당 부분 업데이트 DTO.
+ * - null = 변경 없음 (toFieldMap에서 제외).
+ * - 화이트리스트는 record 필드로 표현 — Jackson SNAKE_CASE 매핑 유지.
+ * - URL: http(s) / "NONE" / 빈 문자열만 허용 ("NONE"은 DDG/Naver 매칭 실패 마킹).
+ */
+public record RestaurantUpdateDTO(
+        @Size(min = 1, max = 200)
+        String name,
+
+        @Size(max = 500)
+        String address,
+
+        @Size(max = 100)
+        String region,
+
+        @JsonProperty("cuisine_type")
+        @Size(max = 50)
+        String cuisineType,
+
+        @JsonProperty("price_range")
+        @Min(1) @Max(5)
+        Integer priceRange,
+
+        @Size(max = 50)
+        String phone,
+
+        @Pattern(regexp = "^(https?://.*|NONE|)$")
+        String website,
+
+        @JsonProperty("tabling_url")
+        @Pattern(regexp = "^(https?://.*|NONE|)$")
+        String tablingUrl,
+
+        @JsonProperty("catchtable_url")
+        @Pattern(regexp = "^(https?://.*|NONE|)$")
+        String catchtableUrl,
+
+        @DecimalMin("-90.0") @DecimalMax("90.0")
+        BigDecimal latitude,
+
+        @DecimalMin("-180.0") @DecimalMax("180.0")
+        BigDecimal longitude,
+
+        @JsonProperty("google_place_id")
+        @Size(max = 200)
+        String googlePlaceId,
+
+        @JsonProperty("business_status")
+        @Size(max = 50)
+        String businessStatus,
+
+        @DecimalMin("0.0") @DecimalMax("5.0")
+        BigDecimal rating,
+
+        @JsonProperty("rating_count")
+        @Min(0)
+        Integer ratingCount
+) {
+    /** null이 아닌 필드만 DB 컬럼명 키로 변환. */
+    public Map<String, Object> toFieldMap() {
+        Map<String, Object> m = new LinkedHashMap<>();
+        if (name != null) m.put("name", name);
+        if (address != null) m.put("address", address);
+        if (region != null) m.put("region", region);
+        if (cuisineType != null) m.put("cuisine_type", cuisineType);
+        if (priceRange != null) m.put("price_range", priceRange);
+        if (phone != null) m.put("phone", phone);
+        if (website != null) m.put("website", website);
+        if (tablingUrl != null) m.put("tabling_url", tablingUrl);
+        if (catchtableUrl != null) m.put("catchtable_url", catchtableUrl);
+        if (latitude != null) m.put("latitude", latitude);
+        if (longitude != null) m.put("longitude", longitude);
+        if (googlePlaceId != null) m.put("google_place_id", googlePlaceId);
+        if (businessStatus != null) m.put("business_status", businessStatus);
+        if (rating != null) m.put("rating", rating);
+        if (ratingCount != null) m.put("rating_count", ratingCount);
+        return m;
+    }
+}

backend-java/src/main/java/com/tasteby/mapper/RestaurantMapper.java

@@ -28,9 +28,24 @@ public interface RestaurantMapper {
 
     int countUnverified();
 
+    // #356 영상-식당 관련도
+    void updateLinkRelevance(@Param("linkId") String linkId,
+                             @Param("relevance") String relevance,
+                             @Param("reason") String reason);
+
+    Map<String, Object> findLinkContext(@Param("linkId") String linkId);
+
+    List<Map<String, Object>> findUnevaluatedLinks(@Param("limit") int limit);
+
+    int countUnevaluatedLinks();
+
+    // #359 1단계 — google_place_id 중복 조회
+    List<Map<String, Object>> findDuplicatePlaceIdRows();
+
     Restaurant findById(@Param("id") String id);
 
-    List<Map<String, Object>> findVideoLinks(@Param("restaurantId") String restaurantId);
+    List<Map<String, Object>> findVideoLinks(@Param("restaurantId") String restaurantId,
+                                              @Param("includeWeak") boolean includeWeak);
 
     void insertRestaurant(Restaurant r);
 

backend-java/src/main/java/com/tasteby/service/PipelineService.java

@@ -29,6 +29,7 @@ public class PipelineService {
     private final VectorService vectorService;
     private final CacheService cacheService;
     private final RestaurantVerifyService verifyService;
+    private final VideoRelevanceService relevanceService;
 
     public PipelineService(YouTubeService youTubeService,
                             ExtractorService extractorService,
@@ -37,7 +38,8 @@ public class PipelineService {
                             VideoService videoService,
                             VectorService vectorService,
                             CacheService cacheService,
-                            RestaurantVerifyService verifyService) {
+                            RestaurantVerifyService verifyService,
+                            VideoRelevanceService relevanceService) {
         this.youTubeService = youTubeService;
         this.extractorService = extractorService;
         this.geocodingService = geocodingService;
@@ -46,6 +48,7 @@ public class PipelineService {
         this.vectorService = vectorService;
         this.cacheService = cacheService;
         this.verifyService = verifyService;
+        this.relevanceService = relevanceService;
     }
 
     /**
@@ -145,13 +148,16 @@ public class PipelineService {
                 evaluationJson = JsonUtil.toJson(s);
             }
 
-            restaurantService.linkVideoRestaurant(
+            String linkId = restaurantService.linkVideoRestaurant(
                     videoDbId, restId,
                     foods instanceof List<?> ? (List<String>) foods : null,
                     evaluationJson,
                     guests instanceof List<?> ? (List<String>) guests : null
             );
 
+            // #356 — 신규 등록 직후 비동기 관련도 평가
+            relevanceService.verifyAsync(linkId);
+
             // Vector embeddings
             var chunks = VectorService.buildChunks(name, restData, title);
             if (!chunks.isEmpty()) {

backend-java/src/main/java/com/tasteby/service/RestaurantService.java

@@ -77,7 +77,11 @@ public class RestaurantService {
     }
 
     public List<Map<String, Object>> findVideoLinks(String restaurantId) {
-        var rows = mapper.findVideoLinks(restaurantId);
+        return findVideoLinks(restaurantId, false);
+    }
+
+    public List<Map<String, Object>> findVideoLinks(String restaurantId, boolean includeWeak) {
+        var rows = mapper.findVideoLinks(restaurantId, includeWeak);
         return rows.stream().map(row -> {
             var m = JsonUtil.lowerKeys(row);
             m.put("foods_mentioned", JsonUtil.parseStringList(m.get("foods_mentioned")));
@@ -87,6 +91,43 @@ public class RestaurantService {
         }).toList();
     }
 
+    // #356 영상-식당 관련도
+    public void updateLinkRelevance(String linkId, String relevance, String reason) {
+        mapper.updateLinkRelevance(linkId, relevance, reason);
+    }
+
+    public Map<String, Object> findLinkContext(String linkId) {
+        var row = mapper.findLinkContext(linkId);
+        return row != null ? JsonUtil.lowerKeys(row) : null;
+    }
+
+    public List<Map<String, Object>> findUnevaluatedLinks(int limit) {
+        return mapper.findUnevaluatedLinks(limit).stream()
+                .map(JsonUtil::lowerKeys)
+                .toList();
+    }
+
+    public int countUnevaluatedLinks() {
+        return mapper.countUnevaluatedLinks();
+    }
+
+    // #359 1단계 — google_place_id 중복 그룹 (참조 카운트 동봉)
+    public List<Map<String, Object>> findDuplicatePlaceIdGroups() {
+        var rows = mapper.findDuplicatePlaceIdRows().stream()
+                .map(JsonUtil::lowerKeys)
+                .toList();
+        Map<String, List<Map<String, Object>>> grouped = new LinkedHashMap<>();
+        for (var r : rows) {
+            String key = (String) r.get("google_place_id");
+            grouped.computeIfAbsent(key, k -> new ArrayList<>()).add(r);
+        }
+        List<Map<String, Object>> out = new ArrayList<>(grouped.size());
+        for (var e : grouped.entrySet()) {
+            out.add(Map.of("google_place_id", e.getKey(), "items", e.getValue()));
+        }
+        return out;
+    }
+
     public void update(String id, Map<String, Object> fields) {
         mapper.updateFields(id, fields);
     }
@@ -138,12 +179,13 @@ public class RestaurantService {
         }
     }
 
-    public void linkVideoRestaurant(String videoId, String restaurantId, List<String> foods, String evaluation, List<String> guests) {
+    public String linkVideoRestaurant(String videoId, String restaurantId, List<String> foods, String evaluation, List<String> guests) {
         String id = IdGenerator.newId();
         String foodsJson = foods != null ? JsonUtil.toJson(foods) : null;
         String guestsJson = guests != null ? JsonUtil.toJson(guests) : null;
         String evalJson = JsonUtil.normalizeEvaluation(evaluation);
         mapper.linkVideoRestaurant(id, videoId, restaurantId, foodsJson, evalJson, guestsJson);
+        return id;
     }
 
     public void updateCuisineType(String id, String cuisineType) {

backend-java/src/main/java/com/tasteby/service/VideoRelevanceService.java

@@ -0,0 +1,154 @@
+package com.tasteby.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * #356 영상-식당 관련도 LLM 평가.
+ * 설계서: docs/design/356-video-relevance-llm/README.md
+ *
+ * 신규 등록 시 자동 평가 + 어드민 백필. 결과는 video_restaurants.relevance에 저장.
+ * - strong: 본격 다룸 (방문 리뷰, 메뉴 평가)
+ * - weak: 잠깐 언급, 비교 대상
+ * - incidental: 일반 토픽 중 단순 언급, 입점 전
+ * - unknown: 미평가 or LLM 실패 (안전 기본값으로 표시 유지)
+ */
+@Service
+public class VideoRelevanceService {
+
+    private static final Logger log = LoggerFactory.getLogger(VideoRelevanceService.class);
+    private static final Set<String> VALID = Set.of("strong", "weak", "incidental", "unknown");
+    private static final long BACKFILL_SLEEP_MS = 200;
+
+    private final RestaurantService restaurantService;
+    private final OciGenAiService genAi;
+    private final ObjectMapper jsonMapper = new ObjectMapper();
+
+    public VideoRelevanceService(RestaurantService restaurantService, OciGenAiService genAi) {
+        this.restaurantService = restaurantService;
+        this.genAi = genAi;
+    }
+
+    @Async
+    public void verifyAsync(String linkId) {
+        try {
+            verify(linkId);
+        } catch (Exception e) {
+            log.warn("verifyAsync failed for link {}: {}", linkId, e.getMessage());
+        }
+    }
+
+    public void verify(String linkId) {
+        Map<String, Object> ctx = restaurantService.findLinkContext(linkId);
+        if (ctx == null) return;
+        VerifyResult result;
+        try {
+            String prompt = buildPrompt(ctx);
+            String response = genAi.chat(prompt, 120);
+            result = parseRelevance(response);
+        } catch (Exception e) {
+            log.warn("verify({}) LLM failed: {} — keeping unknown", linkId, e.getMessage());
+            return;
+        }
+        restaurantService.updateLinkRelevance(linkId, result.relevance(), truncate(result.reason(), 120));
+    }
+
+    @Async
+    public void verifyAllAsync(int batchSize) {
+        try {
+            int n = verifyAll(batchSize);
+            log.info("[VideoRelevance] backfill done: {} processed", n);
+        } catch (Exception e) {
+            log.warn("verifyAllAsync failed: {}", e.getMessage());
+        }
+    }
+
+    public int verifyAll(int batchSize) {
+        int total = 0;
+        List<Map<String, Object>> batch;
+        while (!(batch = restaurantService.findUnevaluatedLinks(batchSize)).isEmpty()) {
+            for (Map<String, Object> row : batch) {
+                String linkId = (String) row.get("link_id");
+                if (linkId == null) continue;
+                try {
+                    verify(linkId);
+                } catch (Exception e) {
+                    log.warn("verifyAll({}) failed: {}", linkId, e.getMessage());
+                }
+                total++;
+                try { Thread.sleep(BACKFILL_SLEEP_MS); } catch (InterruptedException ie) {
+                    Thread.currentThread().interrupt();
+                    return total;
+                }
+            }
+            if (batch.size() < batchSize) break;
+        }
+        return total;
+    }
+
+    // ---- pure helpers ----
+
+    String buildPrompt(Map<String, Object> ctx) {
+        String foods = safeStr(ctx.get("foods_mentioned"));
+        String evaluation = safeStr(ctx.get("evaluation"));
+        return "다음 YouTube 영상이 이 식당을 어떻게 다루는지 판정하라.\n\n" +
+               "식당명: " + safeStr(ctx.get("restaurant_name")) + "\n" +
+               "주소: " + safeStr(ctx.get("address")) + "\n" +
+               "음식 분류: " + safeStr(ctx.get("cuisine_type")) + "\n" +
+               "언급된 음식: " + (foods.isEmpty() ? "(없음)" : foods) + "\n\n" +
+               "영상 제목: " + safeStr(ctx.get("video_title")) + "\n" +
+               "영상 채널: " + safeStr(ctx.get("channel_name")) + "\n" +
+               "영상에 등장한 평가: " + (evaluation.isEmpty() ? "(없음)" : evaluation) + "\n\n" +
+               "응답 형식(JSON만, 다른 텍스트 없이):\n" +
+               "{\"relevance\": \"strong\"|\"weak\"|\"incidental\", \"reason\": \"20자 이내 한국어\"}\n\n" +
+               "가이드:\n" +
+               "- strong: 영상이 이 식당을 본격 다룸 (방문 리뷰, 메뉴 평가).\n" +
+               "- weak: 잠깐 언급, 다른 식당과 비교 대상으로 등장.\n" +
+               "- incidental: 일반 토픽 중 단순 언급, 식당 입점 전 영상.\n" +
+               "- 판단 모호 시 strong (보수적 — 사용자에게 표시 유지).";
+    }
+
+    private static final Pattern JSON_BLOCK = Pattern.compile("\\{[^{}]*\\}", Pattern.DOTALL);
+
+    VerifyResult parseRelevance(String raw) {
+        if (raw == null) return VerifyResult.unknown();
+        String trimmed = raw.trim();
+        String json = (trimmed.startsWith("{") && trimmed.endsWith("}")) ? trimmed : null;
+        if (json == null) {
+            Matcher m = JSON_BLOCK.matcher(raw);
+            if (m.find()) json = m.group();
+        }
+        if (json == null) return VerifyResult.unknown();
+        try {
+            JsonNode node = jsonMapper.readTree(json);
+            String rel = node.path("relevance").asText("unknown").toLowerCase();
+            if (!VALID.contains(rel)) rel = "unknown";
+            String reason = node.path("reason").asText("");
+            return new VerifyResult(rel, reason);
+        } catch (Exception e) {
+            return VerifyResult.unknown();
+        }
+    }
+
+    private static String safeStr(Object o) {
+        return o == null ? "" : o.toString();
+    }
+
+    private static String truncate(String s, int max) {
+        return s == null ? null : (s.length() <= max ? s : s.substring(0, max));
+    }
+
+    public record VerifyResult(String relevance, String reason) {
+        public static VerifyResult unknown() { return new VerifyResult("unknown", "parse_failed"); }
+    }
+}

backend-java/src/main/java/com/tasteby/service/WebSearchService.java

@@ -0,0 +1,159 @@
+package com.tasteby.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+import java.net.URI;
+import java.net.URLDecoder;
+import java.net.URLEncoder;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.*;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * #357 웹 검색 추상화.
+ * - Naver Search webkr.json 우선 (한국 식당 정확도 높음, 무료 일 25k).
+ * - 키 미설정 또는 5xx/timeout 시 DDG HTML 파싱으로 폴백.
+ * - 결과는 urlPatterns로 필터링 (기존 searchDuckDuckGo와 동일 인터페이스).
+ */
+@Service
+public class WebSearchService {
+
+    private static final Logger log = LoggerFactory.getLogger(WebSearchService.class);
+    private static final int MAX_RESULTS = 5;
+
+    private static final Duration REQ_TIMEOUT = Duration.ofSeconds(15);
+    private static final HttpClient HTTP = HttpClient.newBuilder()
+            .followRedirects(HttpClient.Redirect.NORMAL)
+            .connectTimeout(Duration.ofSeconds(5))
+            .build();
+
+    private static final Pattern DDG_RESULT = Pattern.compile(
+            "<a[^>]+class=\"result__a\"[^>]+href=\"([^\"]+)\"[^>]*>(.*?)</a>",
+            Pattern.DOTALL);
+
+    private final ObjectMapper json = new ObjectMapper();
+    private final String naverClientId;
+    private final String naverClientSecret;
+
+    public WebSearchService(
+            @Value("${app.naver.client-id:}") String naverClientId,
+            @Value("${app.naver.client-secret:}") String naverClientSecret) {
+        this.naverClientId = naverClientId == null ? "" : naverClientId.trim();
+        this.naverClientSecret = naverClientSecret == null ? "" : naverClientSecret.trim();
+        log.info("WebSearchService init — Naver={}", naverClientId.isEmpty() ? "off" : "on");
+    }
+
+    public List<Map<String, Object>> search(String query, String... urlPatterns) {
+        if (!naverClientId.isEmpty() && !naverClientSecret.isEmpty()) {
+            try {
+                List<Map<String, Object>> n = searchNaver(query, urlPatterns);
+                if (!n.isEmpty()) return n;
+            } catch (Exception e) {
+                log.warn("[NaverSearch] failed, falling back to DDG: {}", e.getMessage());
+            }
+        }
+        try {
+            return searchDdg(query, urlPatterns);
+        } catch (Exception e) {
+            log.warn("[DDG] failed: {}", e.getMessage());
+            return List.of();
+        }
+    }
+
+    // ─── Naver ───
+
+    List<Map<String, Object>> searchNaver(String query, String... urlPatterns) throws Exception {
+        String encoded = URLEncoder.encode(query, StandardCharsets.UTF_8);
+        String url = "https://openapi.naver.com/v1/search/webkr.json?query=" + encoded + "&display=30";
+        HttpRequest req = HttpRequest.newBuilder()
+                .uri(URI.create(url))
+                .timeout(REQ_TIMEOUT)
+                .header("X-Naver-Client-Id", naverClientId)
+                .header("X-Naver-Client-Secret", naverClientSecret)
+                .GET()
+                .build();
+        HttpResponse<String> resp = HTTP.send(req, HttpResponse.BodyHandlers.ofString());
+        if (resp.statusCode() >= 400) {
+            throw new RuntimeException("Naver " + resp.statusCode());
+        }
+        JsonNode root = json.readTree(resp.body());
+        JsonNode items = root.path("items");
+        List<Map<String, Object>> out = new ArrayList<>();
+        Set<String> seen = new HashSet<>();
+        for (JsonNode it : items) {
+            if (out.size() >= MAX_RESULTS) break;
+            String link = it.path("link").asText("");
+            String title = stripTags(it.path("title").asText(""));
+            if (link.isEmpty() || !matchesPattern(link, urlPatterns)) continue;
+            if (seen.add(link)) out.add(Map.of("title", title, "url", link));
+        }
+        log.info("[NaverSearch] '{}' → {}", query, out.size());
+        return out;
+    }
+
+    // ─── DDG ───
+
+    List<Map<String, Object>> searchDdg(String query, String... urlPatterns) throws Exception {
+        String encoded = URLEncoder.encode(query, StandardCharsets.UTF_8);
+        String url = "https://html.duckduckgo.com/html/?q=" + encoded;
+        HttpRequest req = HttpRequest.newBuilder()
+                .uri(URI.create(url))
+                .timeout(REQ_TIMEOUT)
+                .header("User-Agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36")
+                .header("Accept", "text/html,application/xhtml+xml")
+                .header("Accept-Language", "ko-KR,ko;q=0.9")
+                .GET()
+                .build();
+        HttpResponse<String> resp = HTTP.send(req, HttpResponse.BodyHandlers.ofString());
+        String html = resp.body();
+        Matcher m = DDG_RESULT.matcher(html);
+        List<Map<String, Object>> out = new ArrayList<>();
+        Set<String> seen = new HashSet<>();
+        while (m.find() && out.size() < MAX_RESULTS) {
+            String href = m.group(1);
+            String title = m.group(2).replaceAll("<[^>]+>", "").trim();
+            String actual = extractDdgUrl(href);
+            if (actual == null || !matchesPattern(actual, urlPatterns)) continue;
+            if (seen.add(actual)) out.add(Map.of("title", title, "url", actual));
+        }
+        log.info("[DDG] '{}' → {}", query, out.size());
+        return out;
+    }
+
+    private String extractDdgUrl(String ddgHref) {
+        try {
+            if (ddgHref.contains("uddg=")) {
+                String p = ddgHref.substring(ddgHref.indexOf("uddg=") + 5);
+                int amp = p.indexOf('&');
+                if (amp > 0) p = p.substring(0, amp);
+                return URLDecoder.decode(p, StandardCharsets.UTF_8);
+            }
+            if (ddgHref.startsWith("http")) return ddgHref;
+        } catch (Exception e) {
+            log.debug("[DDG] url extract failed: {}", ddgHref);
+        }
+        return null;
+    }
+
+    static String stripTags(String s) {
+        return s == null ? "" : s.replaceAll("<[^>]+>", "").trim();
+    }
+
+    static boolean matchesPattern(String url, String[] patterns) {
+        if (patterns == null || patterns.length == 0) return true;
+        for (String p : patterns) {
+            if (url.contains(p)) return true;
+        }
+        return false;
+    }
+}

backend-java/src/main/resources/application.yml

@@ -56,6 +56,11 @@ app:
     youtube-api-key: ${YOUTUBE_DATA_API_KEY}
     client-id: ${GOOGLE_CLIENT_ID:635551099330-2l003d3ernjmkqavd4f6s78r8r405iml.apps.googleusercontent.com}
 
+  # #357 — Naver Search API (Tabling/Catchtable URL 매칭). 미설정 시 DDG 폴백.
+  naver:
+    client-id: ${NAVER_CLIENT_ID:}
+    client-secret: ${NAVER_CLIENT_SECRET:}
+
   cache:
     ttl-seconds: 600
 

backend-java/src/main/resources/db/migration/V20260615b__video_relevance.sql

@@ -0,0 +1,7 @@
+-- #356 영상-식당 관련도 LLM 평가
+ALTER TABLE video_restaurants ADD (
+  relevance VARCHAR2(16) DEFAULT 'unknown' NOT NULL,
+  relevance_reason VARCHAR2(120),
+  relevance_evaluated_at TIMESTAMP
+);
+CREATE INDEX idx_vr_relevance ON video_restaurants(relevance);

backend-java/src/main/resources/mybatis/mapper/RestaurantMapper.xml

@@ -69,14 +69,20 @@
     </select>
 
     <select id="findVideoLinks" resultType="map">
-        SELECT v.video_id, v.title, v.url,
+        <!-- #356 — relevance 컬럼 SELECT + includeWeak 가드 -->
+        SELECT vr.id AS link_id,
+               v.video_id, v.title, v.url,
                TO_CHAR(v.published_at, 'YYYY-MM-DD"T"HH24:MI:SS') AS published_at,
                vr.foods_mentioned, vr.evaluation, vr.guests,
+               vr.relevance, vr.relevance_reason,
                c.channel_name, c.channel_id
         FROM video_restaurants vr
         JOIN videos v ON v.id = vr.video_id
         JOIN channels c ON c.id = v.channel_id
         WHERE vr.restaurant_id = #{restaurantId}
+        <if test="includeWeak == null or !includeWeak">
+            AND vr.relevance IN ('strong', 'unknown')
+        </if>
         ORDER BY v.published_at DESC
     </select>
 
@@ -315,4 +321,53 @@
         SELECT COUNT(*) FROM restaurants WHERE verified_at IS NULL
     </select>
 
+    <!-- ===== #356 영상-식당 관련도 ===== -->
+
+    <update id="updateLinkRelevance">
+        UPDATE video_restaurants
+        SET relevance = #{relevance},
+            relevance_reason = #{reason,jdbcType=VARCHAR},
+            relevance_evaluated_at = CURRENT_TIMESTAMP
+        WHERE id = #{linkId}
+    </update>
+
+    <select id="findLinkContext" resultType="map">
+        <!-- LLM 평가에 필요한 정보 -->
+        SELECT vr.id AS link_id, vr.foods_mentioned, vr.evaluation,
+               r.id AS restaurant_id, r.name AS restaurant_name, r.address, r.cuisine_type,
+               v.title AS video_title, c.channel_name
+        FROM video_restaurants vr
+        JOIN restaurants r ON r.id = vr.restaurant_id
+        JOIN videos v ON v.id = vr.video_id
+        JOIN channels c ON c.id = v.channel_id
+        WHERE vr.id = #{linkId}
+    </select>
+
+    <select id="findUnevaluatedLinks" resultType="map">
+        SELECT id AS link_id FROM video_restaurants
+        WHERE relevance_evaluated_at IS NULL
+        FETCH FIRST #{limit} ROWS ONLY
+    </select>
+
+    <select id="countUnevaluatedLinks" resultType="int">
+        SELECT COUNT(*) FROM video_restaurants WHERE relevance_evaluated_at IS NULL
+    </select>
+
+    <!-- #359 1단계 — google_place_id 중복 조회 (그룹 식당 + 참조 카운트) -->
+    <select id="findDuplicatePlaceIdRows" resultType="map">
+        SELECT r.id, r.google_place_id, r.name, r.address,
+               TO_CHAR(r.created_at, 'YYYY-MM-DD"T"HH24:MI:SS') AS created_at,
+               r.hidden,
+               (SELECT COUNT(*) FROM video_restaurants vr WHERE vr.restaurant_id = r.id) AS video_count,
+               (SELECT COUNT(*) FROM user_reviews rv WHERE rv.restaurant_id = r.id) AS review_count,
+               (SELECT COUNT(*) FROM user_memos mm WHERE mm.restaurant_id = r.id) AS memo_count
+        FROM restaurants r
+        WHERE r.google_place_id IN (
+            SELECT google_place_id FROM restaurants
+            WHERE google_place_id IS NOT NULL
+            GROUP BY google_place_id HAVING COUNT(*) > 1
+        )
+        ORDER BY r.google_place_id, r.created_at
+    </select>
+
 </mapper>

backend-java/src/main/resources/mybatis/mapper/StatsMapper.xml

@@ -10,13 +10,13 @@
         WHEN NOT MATCHED THEN INSERT (visit_date, visit_count) VALUES (src.d, 1)
     </update>
 
-    <select id="getTodayVisits" resultType="int">
+    <select id="getTodayVisits" resultType="long">
         SELECT NVL(visit_count, 0)
         FROM site_visits
         WHERE visit_date = TRUNC(SYSDATE)
     </select>
 
-    <select id="getTotalVisits" resultType="int">
+    <select id="getTotalVisits" resultType="long">
         SELECT NVL(SUM(visit_count), 0)
         FROM site_visits
     </select>

deploy.sh

@@ -62,15 +62,18 @@ if [[ "$TARGET" == "all" || "$TARGET" == "frontend" ]]; then
   # Read build args from env or .env file
   MAPS_KEY="${NEXT_PUBLIC_GOOGLE_MAPS_API_KEY:-}"
   CLIENT_ID="${NEXT_PUBLIC_GOOGLE_CLIENT_ID:-}"
+  NAVER_MAP_ID="${NEXT_PUBLIC_NAVER_MAP_CLIENT_ID:-}"
 
   if [[ -f frontend/.env.local ]]; then
     MAPS_KEY="${MAPS_KEY:-$(grep NEXT_PUBLIC_GOOGLE_MAPS_API_KEY frontend/.env.local 2>/dev/null | cut -d= -f2)}"
     CLIENT_ID="${CLIENT_ID:-$(grep NEXT_PUBLIC_GOOGLE_CLIENT_ID frontend/.env.local 2>/dev/null | cut -d= -f2)}"
+    NAVER_MAP_ID="${NAVER_MAP_ID:-$(grep NEXT_PUBLIC_NAVER_MAP_CLIENT_ID frontend/.env.local 2>/dev/null | cut -d= -f2)}"
   fi
 
   docker build --platform "$PLATFORM" \
     --build-arg NEXT_PUBLIC_GOOGLE_MAPS_API_KEY="$MAPS_KEY" \
     --build-arg NEXT_PUBLIC_GOOGLE_CLIENT_ID="$CLIENT_ID" \
+    --build-arg NEXT_PUBLIC_NAVER_MAP_CLIENT_ID="$NAVER_MAP_ID" \
     -t "$REGISTRY/frontend:$TAG" \
     -t "$REGISTRY/frontend:latest" \
     frontend/

docs/design/343-frontend-test-infra/README.md

@@ -0,0 +1,117 @@
+# 설계서: RTL/Jest 인프라 + next/image + ARIA Tabs (#343)
+
+> **상태**: Approved
+> **작성**: [AI] Architect · **최종수정**: 2026-06-15
+> **추적성** — Redmine: #343 · 부모: #281 (현행화 frontend-review-memo, 09-Done)
+> · 구현 파일: `frontend/package.json`, `frontend/jest.config.ts` (신규), `frontend/jest.setup.ts` (신규), `frontend/next.config.ts`, `frontend/__tests__/*` (신규), `frontend/src/components/MyReviewsList.tsx`, `frontend/src/components/ReviewSection.tsx`
+> · 테스트: 본 이슈가 테스트 인프라 자체를 도입
+
+## 1. 목적 (Why)
+
+본 프로젝트는 지금까지 자동화된 단위 테스트가 0건. 누적된 "후속 테스트" 항목이 12+개(StatsService/CacheService/SearchService/Stars/HangulSimilarity 등)이며, 그동안 분리된 후속 이슈를 처리할 인프라가 없어 모두 보류 상태. 본 이슈에서 Jest + RTL 인프라 도입 + next/image 적용 + ARIA Tabs 보강.
+
+## 2. 범위 (Scope)
+
+- **포함**
+  - Jest 30 + `next/jest` 자동 설정 + `@testing-library/react` + `@testing-library/jest-dom`.
+  - `jest.config.ts`, `jest.setup.ts`, `package.json scripts: test, test:watch`.
+  - 샘플 테스트 3개 — 가장 안전한 순수 함수/단순 컴포넌트로 인프라 검증:
+    - `Stars` 컴포넌트 렌더 + 별점 표시
+    - 기존 `HangulSimilarity` (#348) — 자모/유사도
+    - `BotDetector` (#337) — 봇 UA 패턴
+  - `next.config.ts` `images.remotePatterns`에 Google avatar 도메인(`lh3.googleusercontent.com`) + YouTube thumbnail(`i.ytimg.com`).
+  - `ReviewSection`/`MyReviewsList`의 `<img>` 일부를 `next/image` 또는 명시적 eslint-disable로 정리.
+  - `MyReviewsList` 탭에 WAI-ARIA Tabs 패턴(role=tablist/tab/aria-selected/aria-controls).
+- **제외 (후속)**
+  - 백엔드 JUnit 테스트 인프라 (별도 큰 작업).
+  - E2E (Playwright) 도입.
+  - CI 통합 (GitHub Actions 또는 OCI DevOps).
+  - 모든 컴포넌트 테스트 — 점진적으로 추가.
+  - 모든 `<img>` → `next/image` 전수 교체 — 점진적.
+
+## 3. 인수조건
+
+- [ ] `npm test`가 단일 명령으로 동작 (0건 → 샘플 3개 통과).
+- [ ] `npm run build`가 회귀 없이 통과.
+- [ ] `next.config.ts`에 `remotePatterns` 설정.
+- [ ] `ReviewSection`의 user_avatar_url `<img>`에 `next/image` 또는 eslint-disable 주석.
+- [ ] `MyReviewsList` 탭이 `role="tablist"`/`role="tab"`/`aria-selected`/`aria-controls`/`tabIndex` 설정.
+
+## 4. 컨텍스트 & 제약
+
+- Next.js 16.1.6 + Turbopack.
+- `next/jest`는 SWC/Babel 자동 통합. Turbopack 빌드와는 분리(테스트만 Jest 별도).
+- Pretendard/Geist 폰트는 `next/font/local` 사용 → 테스트에선 mock 불필요.
+- 패널 분리(#329)로 admin 영역은 단위 테스트 도입 더 쉬워짐.
+
+## 5. 아키텍처 개요
+
+```
+frontend/
+├── package.json
+│   └── scripts: test, test:watch
+├── jest.config.ts            (next/jest createNextJestConfig 사용)
+├── jest.setup.ts             (@testing-library/jest-dom 확장 matchers)
+├── __tests__/
+│   ├── Stars.test.tsx
+│   ├── HangulSimilarity.test.ts   (자체 구현은 backend Java, TS 포팅은 미적용 → 다른 순수 함수로 대체)
+│   └── BotDetector.test.ts        (마찬가지 — backend → TS 동등 포팅 불가)
+└── (대안) 프론트 측 순수 함수:
+    ├── lib/cuisine-icons.ts 의 getPhosphorCuisineIcon
+    ├── components/Stars 의 0.5 단위 렌더
+    └── i18n/config.ts 의 isLocale/detectBrowserLocale
+```
+
+→ 백엔드 Java 코드는 TS 테스트로 검증 불가. 프론트 측 순수 함수 3개로 대체:
+- `Stars` 렌더 (RTL component test)
+- `i18n/config.ts` `isLocale` (pure)
+- `i18n/config.ts` `detectBrowserLocale` (navigator mock)
+
+## 6. 데이터 모델
+
+`__tests__/*.test.{tsx,ts}` — Jest 표준 컨벤션.
+
+## 7. 함수 명세
+
+| 단위 | 책임 | 비고 |
+|------|------|------|
+| `jest.config.ts` | `createJestConfig(customConfig)` + moduleNameMapper `@/*` | next/jest |
+| `jest.setup.ts` | `import "@testing-library/jest-dom"` | 확장 matchers |
+| `Stars.test.tsx` | 별점 0/2.5/5 렌더, aria-label 확인 | RTL |
+| `i18n/config.test.ts` | isLocale/detectBrowserLocale | navigator mock |
+| `MyReviewsList` Tabs 패치 | tablist/tab/aria-selected | role + aria |
+| `ReviewSection` img → eslint-disable | 최소 변경 | next/image는 후속 |
+
+## 8. 흐름
+
+1. `npm i -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event @types/jest`.
+2. `jest.config.ts` + `jest.setup.ts` 작성.
+3. `package.json`에 `"test": "jest"` + `"test:watch": "jest --watch"` 추가.
+4. `__tests__/`에 3개 샘플 테스트.
+5. `next.config.ts`에 `remotePatterns` 추가.
+6. `MyReviewsList` Tabs ARIA 보강.
+7. `ReviewSection`의 `<img>` 라인에 `// eslint-disable-next-line @next/next/no-img-element` (next/image 전환은 후속).
+8. `npm test` 통과 → `npm run build` 통과.
+
+## 9. 엣지케이스
+
+- **Turbopack vs Jest**: 무관 (테스트는 별도 SWC 컴파일).
+- **CSS modules / globals.css import**: jest.config.ts의 moduleNameMapper로 `\\.(css|scss)$` → `identity-obj-proxy` 대신 next/jest가 자동 처리.
+- **Next.js Server Components**: 본 프로젝트는 모두 `"use client"` 컴포넌트라 RTL이 통상 동작.
+
+## 10. 테스트
+
+자기 자신 — `npm test`가 통과해야 본 이슈 완료.
+
+## 11. 리스크 & 대안
+
+- **선택**: `next/jest` + RTL. Next.js 공식 권장.
+- **대안 A**: Vitest — 더 빠르지만 Next.js 공식 가이드 부재, 본 프로젝트 규모에서 차이 작음.
+- **대안 B**: Playwright Component Testing — 더 무겁고 E2E 통합 안 됨.
+- **트레이드오프**: Jest 30 + RTL은 React 19에 호환. 의존성 부담은 dev-only.
+
+## 12. 미해결 질문
+
+- CI(테스트 자동 실행) — 본 이슈 범위 밖. OCI DevOps Build Pipeline은 ARM64 미지원 → GitHub Actions 또는 Gitea Actions 후속.
+- 백엔드 JUnit 테스트 인프라 — 별도 큰 이슈.
+- E2E (Playwright) — 별도.

docs/design/356-video-relevance-llm/README.md

@@ -0,0 +1,172 @@
+# 설계서: 영상-식당 관련도 LLM 평가로 약한 매칭 자동 숨김 (#356)
+
+> **상태**: Approved
+> **작성**: [AI] Architect · **최종수정**: 2026-06-15
+> **추적성** — Redmine: #356 · 유사 패턴: #322(식당 LLM 검증, 09-Done) · 부모 영역: #270(영상→식당 추출 파이프라인 현행화, 09-Done)
+> · 구현 파일: `backend-java/src/main/java/com/tasteby/service/VideoRelevanceService.java`(신규), `backend-java/src/main/resources/mybatis/mapper/RestaurantMapper.xml`, `backend-java/src/main/java/com/tasteby/service/RestaurantService.java`, `backend-java/src/main/java/com/tasteby/controller/AdminVideoRelevanceController.java`(신규), DB 마이그레이션 SQL
+> · 테스트: 본 범위 밖 (테스트 인프라 #343 도입됨, 후속에서 점진 확장)
+
+## 1. 목적 (Why)
+
+식당 상세에 연결된 영상 중 식당과 **본격적으로 관련 없는 약한 언급**(비교 대상, 일반 토픽 중 잠깐 언급, 식당 입점 전 영상 등)이 노이즈로 표시. 실제 케이스 — 파이브가이즈 강남의 영상 7개 중 3건이 약한 매칭(쉐이크쉑 비교 / 미국 비만율 일반 토픽 / 한국 입점 전 미국 여행). LLM 평가로 약한 매칭 자동 숨김.
+
+## 2. 범위 (Scope)
+
+- **포함**
+  - `video_restaurants` 테이블에 `relevance`, `relevance_reason`, `relevance_evaluated_at` 컬럼 추가.
+  - `VideoRelevanceService` 신규 — LLM 판정 + DB 반영 (`#322` 패턴 모방).
+  - `PipelineService.processExtract` 완료 후 `verifyAsync(linkId)` 호출 — 신규 등록 자동 평가.
+  - `GET /api/restaurants/{id}/videos`: 기본 `relevance = 'strong'`만 응답. `?include_weak=true` 시 모두 포함.
+  - 어드민 API: 단건 재평가 / 일괄 백필 / 수동 토글.
+- **제외 (별도 후속)**
+  - 어드민 UI(검증 칼럼 / 토글) — `#322`의 RestaurantsPanel UI와 같은 패턴으로 별도 후속.
+  - 프론트 사용자 옵션 UI("약한 매칭도 보기" 토글) — 별도 후속.
+  - LLM 비용 모니터링/메트릭 — 별도.
+
+## 3. 인수조건
+
+- [ ] `video_restaurants` 테이블에 `relevance VARCHAR2(16) DEFAULT 'unknown'`, `relevance_reason VARCHAR2(120)`, `relevance_evaluated_at TIMESTAMP` 컬럼 + `idx_vr_relevance` 인덱스.
+- [ ] 가능한 값: `strong | weak | incidental | unknown` (unknown = 미평가).
+- [ ] 신규 등록 시 60초 안에 `relevance_evaluated_at` 설정.
+- [ ] `GET /api/restaurants/{id}/videos` 기본 응답: `relevance IN ('strong','unknown')` (안전한 기본값 = 평가 실패 시 표시).
+- [ ] `?include_weak=true`: 모두 포함 + `relevance`, `relevance_reason` 필드 동봉.
+- [ ] 어드민 API:
+  - `GET /api/admin/video-relevance/pending` → 미평가(unknown) 카운트
+  - `POST /api/admin/video-relevance/all?batchSize=10` → 백필
+  - `POST /api/admin/video-relevance/{linkId}/evaluate` → 단건 재평가
+  - `PATCH /api/admin/video-relevance/{linkId}` → 수동 강제 토글 `{relevance, reason}`
+- [ ] LLM 호출 실패 시 `unknown` 유지 + 로그 (`#322`와 같은 안전 기본값).
+- [ ] 빌드/배포 회귀 없음.
+
+## 4. 컨텍스트 & 제약
+
+- 기존 `OciGenAiService.chat(prompt, maxTokens)` 재사용.
+- LLM 비용: 영상-식당 페어당 1회 단발. 현재 1,244건 → 백필 시 약 1,244 호출.
+- `video_restaurants`는 한 영상에 여러 식당, 한 식당에 여러 영상이 m:n 관계.
+- 같은 페어는 `relevance_evaluated_at`이 NULL 아니면 재평가 안 함 (캐시).
+
+## 5. 아키텍처 개요
+
+```
+PipelineService.processExtract (기존)
+   │
+   ▼
+RestaurantService.linkVideoRestaurant (video_restaurants INSERT)
+   │
+   ▼
+VideoRelevanceService.verifyAsync(linkId)  ← #356 신규
+   │ (비동기)
+   ▼
+OciGenAiService.chat(prompt, 120)
+   │
+   ▼
+parseRelevance → { relevance: strong|weak|incidental, reason: string }
+   │
+   ▼
+RestaurantMapper.updateRelevance(linkId, relevance, reason)
+   │
+   ▼ (조회 시)
+RestaurantMapper.findVideoLinks(restaurantId, includeWeak)
+   ├ includeWeak=false (기본): WHERE relevance IN ('strong','unknown')
+   └ includeWeak=true:  모두 + relevance/reason 필드 노출
+```
+
+## 6. 데이터 모델
+
+### DB 마이그레이션
+```sql
+ALTER TABLE video_restaurants ADD (
+  relevance VARCHAR2(16) DEFAULT 'unknown' NOT NULL,
+  relevance_reason VARCHAR2(120),
+  relevance_evaluated_at TIMESTAMP
+);
+CREATE INDEX idx_vr_relevance ON video_restaurants(relevance);
+```
+
+### 도메인 (`VideoRestaurantLink` 확장은 본 범위 밖 — findVideoLinks는 `resultType="map"`)
+응답 Map에 키 추가:
+- `relevance`: `"strong" | "weak" | "incidental" | "unknown"`
+- `relevance_reason`: `string | null`
+
+### LLM 응답 스키마
+```json
+{
+  "relevance": "strong" | "weak" | "incidental",
+  "reason": "20자 이내"
+}
+```
+
+## 7. 함수 명세
+
+| 함수 | 책임 | 비고 |
+|---|---|---|
+| `VideoRelevanceService.verifyAsync(linkId)` | 비동기 트리거 | `#322`의 `RestaurantVerifyService.verifyAsync` 유사 |
+| `VideoRelevanceService.verify(linkId)` | 단건 검증 + DB 반영 | LLM 실패 시 unknown 유지 |
+| `VideoRelevanceService.verifyAll(batchSize)` | 백필 (식당당 200ms sleep) | |
+| `VideoRelevanceService.buildPrompt(...)` | 프롬프트 생성 | 식당명·주소·음식·영상 제목·평가 |
+| `VideoRelevanceService.parseRelevance(raw)` | LLM 응답 → DTO | 파싱 실패 시 unknown 안전 기본값 |
+| `RestaurantMapper.updateRelevance(linkId, rel, reason)` | DB 갱신 | |
+| `RestaurantMapper.findVideoLinks(restaurantId, includeWeak)` | 기존 SQL에 WHERE 조건 추가 | |
+| `AdminVideoRelevanceController` 신규 | 4개 admin endpoint | requireAdmin |
+
+## 8. 흐름
+
+### 신규 등록 자동 평가
+1. `PipelineService.processExtract` → `linkVideoRestaurant` → linkId 획득.
+2. `VideoRelevanceService.verifyAsync(linkId)` 호출(@Async).
+3. 별도 스레드: 영상/식당/평가 데이터 조회 → buildPrompt → LLM → parse → DB.
+
+### 백필
+1. 어드민 `POST /api/admin/video-relevance/all` 호출.
+2. `WHERE relevance_evaluated_at IS NULL` 인 link 10개씩 조회 → 순차 검증.
+3. 식당당 200ms sleep (LLM rate 보호).
+
+### 프롬프트 예시
+```
+다음 YouTube 영상이 이 식당을 어떻게 다루는지 판정하라.
+
+식당명: {restaurantName}
+주소: {address}
+음식: {foodsMentioned}
+
+영상 제목: {videoTitle}
+영상 채널: {channelName}
+영상에 등장한 평가 내용: {evaluation}
+
+응답 형식(JSON만, 다른 텍스트 없이):
+{"relevance": "strong"|"weak"|"incidental", "reason": "20자 이내 한국어"}
+
+가이드:
+- strong: 영상 본편이 이 식당을 본격 다룸. 방문 리뷰, 메뉴 평가 등.
+- weak: 영상에서 잠깐 언급, 비교 대상으로만 등장, 다른 식당의 일부로.
+- incidental: 식당 입점 전 영상에서 단순 언급, 일반 토픽(미국 비만, 환율 등)에서 잠깐.
+- 판단 모호 시 strong (보수적 — 사용자에게 표시 유지).
+```
+
+## 9. 엣지케이스
+
+- **LLM 응답 비-JSON**: parseRelevance → unknown 기본값.
+- **LLM 호출 실패**: unknown 유지 → 다음 백필 재시도.
+- **영상 데이터 누락(transcript 없음, evaluation 비어있음)**: 프롬프트에 "(미상)" 표기. LLM이 판정 어려우면 strong 보수적.
+- **동시성**: 같은 linkId verifyAsync 두 번 호출 → idempotent.
+- **삭제된 영상**: linkId 조회 결과 없으면 no-op.
+
+## 10. 테스트 (수동)
+
+- 파이브가이즈 강남 케이스 백필 → 7건 중 3건이 weak/incidental로 마킹되는지 확인.
+- 공개 API `/api/restaurants/{id}/videos` → 약한 매칭 제외 확인.
+- `?include_weak=true` → 모두 포함 확인.
+
+## 11. 리스크 & 대안
+
+- **선택**: `#322` 동일 패턴 + DB 마이그레이션.
+- **대안 A**: 사용자가 직접 "약한 매칭도 보기" 토글 → 사용자 결정 부담.
+- **대안 B**: 추출 단계에서 한 번에 판정 → 비용 ↓이지만 ExtractorService 비대.
+- **트레이드오프**: 단발 LLM 평가는 비용 합리적. false positive는 어드민 수동 토글 + `unknown` 안전 기본값으로 보완.
+
+## 12. 미해결 질문
+
+- 임계값(weak/incidental 둘 다 숨김 vs incidental만 숨김) — 현재는 둘 다 숨김.
+- 영상 자막 전체를 LLM에 보낼지 vs 평가 텍스트만 → 비용/정확도 트레이드오프. 현재는 evaluation만(짧음).
+- 사용자에게 "약한 매칭도 보기" UI → 별도 후속.
+- 어드민 UI — 별도 후속 (#322 패턴 모방).

docs/design/357-web-search-api/README.md

@@ -0,0 +1,114 @@
+# 설계서: DDG HTML 파싱 → 정식 검색 API 전환 (#357)
+
+> **상태**: Approved
+> **작성**: [AI] Architect · **최종수정**: 2026-06-15
+> **추적성** — Redmine: #357 · 부모: #348(이름 유사도, 09-Done) · 관련: searchTabling/searchCatchtable
+> · 구현 파일: `backend-java/src/main/java/com/tasteby/service/WebSearchService.java`(신규), `backend-java/src/main/java/com/tasteby/controller/RestaurantController.java`, `backend-java/src/main/resources/application.yml`, `k8s/secrets.yaml.template`
+> · 테스트: 본 범위 밖 (수동 — Tabling/Catchtable 매핑 SSE에서 확인)
+
+## 1. 목적 (Why)
+
+`searchDuckDuckGo`는 html.duckduckgo.com을 정규식으로 긁어 Tabling/Catchtable URL을 추출. 봇 차단/HTML 구조 변경 시 대량 `NONE` 마킹 위험. 정식 검색 API로 교체해 안정성/정확도 확보.
+
+## 2. 범위 (Scope)
+
+- **포함**
+  - `WebSearchService` 신규 — Naver Search webkr.json 우선, 미설정/실패 시 DDG 폴백.
+  - `RestaurantController.searchTabling/searchCatchtable` 내부 호출을 새 서비스로 교체.
+  - `application.yml` + `k8s/secrets.yaml.template`에 `NAVER_CLIENT_ID/SECRET` 항목 추가.
+- **제외 (별도 후속)**
+  - Kakao Local API 검색 (식당 검색 전용이라 사이트 URL 매칭 부적합).
+  - Google Custom Search Engine (비용 + 무료 100/day 제약).
+  - 결과 캐시/메트릭 — 후속.
+
+## 3. 인수조건
+
+- [ ] `NAVER_CLIENT_ID/SECRET` 환경변수 등록 시 Naver Search webkr.json 호출.
+- [ ] 미설정 또는 5xx/timeout 시 DDG로 자동 폴백 — 회귀 없음.
+- [ ] 응답 형식: 기존 `List<Map<String, Object>>` 유지 — `{title, url}` 키.
+- [ ] URL 패턴 필터 동일 동작 (예: `tabling.co.kr/restaurant/`, `tabling.co.kr/place/`).
+- [ ] 빌드/배포 회귀 없음.
+
+## 4. 컨텍스트 & 제약
+
+- Naver Search 무료 한도: 일 25,000건. Tabling/Catchtable 매핑 백필이 1,200 식당 × 2회 ≈ 2,400건 1회성 → 한도 내.
+- Naver는 `site:` 연산자 미지원 — 결과 URL 패턴 필터링으로 대체.
+- `WebClient` 또는 `HttpClient` — 기존 `HttpClient`(static) 재사용.
+- 키 미설정 환경(dev local 일부)에서도 DDG 폴백으로 동작 보장.
+
+## 5. 아키텍처 개요
+
+```
+RestaurantController.searchTabling(name)
+   │
+   ▼
+WebSearchService.search(query, urlPatterns)
+   │
+   ├─ NAVER_CLIENT_ID 설정 시
+   │     └─ Naver webkr.json → URL 패턴 필터 → 결과
+   │             (실패/0건 시 ▼)
+   └─ DDG html.duckduckgo.com → 정규식 파싱 → URL 패턴 필터
+```
+
+## 6. 데이터 모델
+
+### 응답 (기존 유지)
+```json
+[ { "title": "스타벅스 강남대로점", "url": "https://app.catchtable.co.kr/dining/12345" } ]
+```
+
+### Naver 응답 → 변환
+```json
+{ "items": [ { "title": "<b>스타벅스</b> 강남점", "link": "https://..." } ] }
+```
+- `title`은 `<b>` 태그 제거 후 사용.
+- `link`가 urlPatterns 중 하나에 매칭되면 결과에 포함.
+
+## 7. 함수 명세
+
+| 함수 | 책임 | 비고 |
+|---|---|---|
+| `WebSearchService.search(query, urlPatterns)` | 외부 진입점 | Naver 우선 → DDG 폴백 |
+| `WebSearchService.searchNaver(...)` | Naver Search webkr.json 호출 + 필터 | 키 미설정 시 즉시 빈 결과 |
+| `WebSearchService.searchDdg(...)` | 기존 DDG 로직 이관 | RestaurantController에서 옮김 |
+| `WebSearchService.stripTags(s)` | `<b>...</b>` 제거 | |
+| `WebSearchService.matchesPattern(url, patterns)` | URL 패턴 매칭 | `urlPatterns.length == 0` 면 모두 통과 |
+
+## 8. 흐름
+
+### 정상
+1. `searchTabling(name)` → `webSearchService.search("스타벅스", ["tabling.co.kr/restaurant/", "tabling.co.kr/place/"])`.
+2. Naver 호출 → 200, items 30 → URL 패턴 매칭 0~N건 추출.
+3. 0건이면 DDG 폴백, 그래도 0건이면 빈 리스트.
+
+### 폴백
+- Naver 5xx / IOException / 키 미설정 → DDG.
+
+### 키 등록 (운영자 작업)
+1. https://developers.naver.com/apps/#/list 검색 앱 등록.
+2. `NAVER_CLIENT_ID`, `NAVER_CLIENT_SECRET` 발급.
+3. dev: `.env`에 추가, prod: `k8s/secrets.yaml`에 추가 + `kubectl apply`.
+
+## 9. 엣지케이스
+
+- **키 미설정**: searchNaver 즉시 빈 리스트 → DDG 폴백 (회귀 없음).
+- **Naver rate limit (429)**: DDG 폴백.
+- **DDG도 막힘**: 빈 리스트 반환 → 호출자(매핑 SSE)에서 `NONE` 처리 — 기존 동작 동일.
+- **URL 패턴 빈 배열**: 패턴 매칭 스킵, 모든 결과 반환 (API 일반화 대비).
+
+## 10. 테스트 (수동)
+
+- Dev: `NAVER_CLIENT_ID/SECRET` 등록 → 어드민 `bulkTabling` SSE 실행 → 매칭율 비교 (이전 DDG 대비 ≥).
+- 키 일부 제거 → DDG 폴백 동작 확인.
+
+## 11. 리스크 & 대안
+
+- **선택**: Naver primary + DDG fallback. 한국 식당 정확도 + 무료 한도 + 폴백 안정성.
+- **대안 A**: Kakao Local Search — 식당 정보 직접 검색은 가능하지만 Tabling/Catchtable URL 매핑 부적합.
+- **대안 B**: Google CSE — 비용/한도 제약.
+- **트레이드오프**: Naver 응답 정확도가 압도적이지만 키 발급 운영자 작업 필요. 폴백으로 회귀 0 보장.
+
+## 12. 미해결 질문
+
+- Naver의 인덱스 신선도 vs Tabling/Catchtable 최신 입점 식당 미반영 가능성 — 백필 주기 후속.
+- 결과 캐시(같은 식당 재호출) — 후속.

docs/design/358-restaurant-update-dto/README.md

@@ -0,0 +1,75 @@
+# 설계서: RestaurantUpdateDTO + @Valid 표준화 (#358)
+
+> **상태**: Approved
+> **작성**: [AI] Architect · **최종수정**: 2026-06-15
+> **추적성** — Redmine: #358 · 부모: #348(09-Done) · 관련: #332(화이트리스트 1차)
+> · 구현 파일: `backend-java/src/main/java/com/tasteby/dto/RestaurantUpdateDTO.java`(신규), `backend-java/src/main/java/com/tasteby/controller/RestaurantController.java`
+> · 테스트: 본 범위 밖 (수동 — 어드민 식당 편집 동작 확인)
+
+## 1. 목적 (Why)
+
+`#332`에서 Set 화이트리스트로 1차 가드 적용했지만, 타입 안전성·validation·API 명세는 여전히 `Map<String, Object>`로 흐릿함. 본격 DTO 표준화로 잘못된 입력 자동 거부 + 명세 명확화.
+
+## 2. 범위 (Scope)
+
+- **포함**
+  - `RestaurantUpdateDTO` record — 화이트리스트 14필드 모두 Optional(null 시 미변경).
+  - `@Valid` + Bean Validation 어노테이션 적용 (`@Size`, `@Pattern`, `@DecimalMin/Max`, `@Min`).
+  - Controller `PUT /api/restaurants/{id}` 시그니처: `Map → RestaurantUpdateDTO`.
+  - DTO → Map 변환(`toFieldMap()`) — Service 계층은 그대로 (재작업 0).
+  - 잘못된 입력 시 400 자동 응답 (Spring 기본 `MethodArgumentNotValidException`).
+- **제외 (별도 후속)**
+  - `tabling-url` / `catchtable-url` PUT 엔드포인트 — 단일 필드라 현행 유지.
+  - PATCH 시멘틱 (부분 업데이트) — 현재 PUT이 부분 업데이트 의미로 사용 중.
+
+## 3. 인수조건
+
+- [ ] 모든 화이트리스트 필드 record에 등재 + null 가능.
+- [ ] `name`: `@Size(min=1, max=200)`.
+- [ ] `website`/`tabling_url`/`catchtable_url`: `@Pattern(http(s)://... | "NONE" | "")`.
+- [ ] `latitude`: `@DecimalMin("-90.0") @DecimalMax("90.0")`.
+- [ ] `longitude`: `@DecimalMin("-180.0") @DecimalMax("180.0")`.
+- [ ] `rating`: `@DecimalMin("0.0") @DecimalMax("5.0")`.
+- [ ] `rating_count`: `@Min(0)`.
+- [ ] `price_range`: `@Min(1) @Max(5)`.
+- [ ] 잘못된 입력 → HTTP 400 자동 응답.
+- [ ] 기존 동작 회귀 없음 (geocode/cache flush 흐름 동일).
+
+## 4. 컨텍스트 & 제약
+
+- `spring-boot-starter-validation` 이미 의존성 등록됨.
+- record + Bean Validation: 컴파일 시 어노테이션 인식 OK.
+- Jackson SNAKE_CASE 매핑 유지: `cuisine_type`, `tabling_url` 등.
+- `null`은 "변경 없음" 시그널 — `toFieldMap()`에서 제외.
+
+## 5. 함수 명세
+
+| 함수 | 책임 | 비고 |
+|---|---|---|
+| `RestaurantUpdateDTO` (record) | 입력 표면 | 14 필드, 모두 nullable |
+| `RestaurantUpdateDTO.toFieldMap()` | null 제외 Map 변환 | Service `update` 시그니처 유지 |
+| `RestaurantController.update(...)` | DTO 받음 + geocode 분기 | `@Valid @RequestBody RestaurantUpdateDTO` |
+
+## 6. 흐름
+
+1. 클라이언트 → `PUT /api/restaurants/{id}` JSON.
+2. Spring 역직렬화 + Bean Validation. 실패 시 400 자동.
+3. `dto.toFieldMap()` → null 제외.
+4. 기존 geocode 분기 + `restaurantService.update(id, fieldMap)`.
+
+## 7. 엣지케이스
+
+- **모든 필드 null**: `toFieldMap()` 빈 Map → no-op (현행 유지).
+- **`tabling_url = "NONE"` / 빈 문자열**: Pattern에 포함 → 통과.
+- **숫자 범위 위반**: 400.
+- **알 수 없는 필드 (예: `xxx`)**: Jackson 기본은 무시 (mapper 설정 유지) → 안전.
+
+## 8. 리스크 & 대안
+
+- **선택**: record + Bean Validation. 코드 최소.
+- **대안 A**: class + setter. 보일러플레이트 다수.
+- **대안 B**: 개별 PATCH endpoint per 필드. 표면 폭증.
+
+## 9. 미해결 질문
+
+- bulkUpdate (batch) 도입 시 별도 DTO — 후속.

docs/design/359a-duplicate-place-id-view/README.md

@@ -0,0 +1,47 @@
+# 설계서: google_place_id 중복 조회 API (#359 1단계)
+
+> **상태**: Approved
+> **작성**: [AI] Architect · **최종수정**: 2026-06-15
+> **추적성** — Redmine: #359 · 1단계(조회 전용, 위험 0). 2단계(자동 병합) / 3단계(UNIQUE)는 별도 PR.
+> · 구현 파일: `backend-java/src/main/resources/mybatis/mapper/RestaurantMapper.xml`, `backend-java/src/main/java/com/tasteby/mapper/RestaurantMapper.java`, `backend-java/src/main/java/com/tasteby/service/RestaurantService.java`, `backend-java/src/main/java/com/tasteby/controller/AdminRestaurantController.java`
+> · 테스트: 본 범위 밖 (수동 — admin token으로 호출).
+
+## 1. 목적 (Why)
+
+같은 `google_place_id`에 다중 식당이 매핑된 경우 운영자가 어떤 것을 유지/병합할지 결정 필요. 본 단계는 **조회만** — 그룹과 후보 식당을 메타데이터(연결된 영상/리뷰/메모 수)와 함께 보여줘 의사결정 자료 제공.
+
+## 2. 범위
+
+- 포함: `GET /api/admin/restaurants/duplicates/place-id` — 운영자만, 그룹별 식당 + 카운트 동봉.
+- 제외 (별도 PR): 병합/삭제, UNIQUE constraint.
+
+## 3. 인수조건
+
+- [ ] requireAdmin 보호.
+- [ ] 응답 구조: `[{ google_place_id, items: [{ id, name, address, created_at, video_count, review_count, memo_count, hidden }] }]`.
+- [ ] 그룹은 `COUNT(*) > 1` 만 반환.
+
+## 4. SQL
+
+```sql
+SELECT r.id, r.google_place_id, r.name, r.address,
+       TO_CHAR(r.created_at, 'YYYY-MM-DD"T"HH24:MI:SS') AS created_at,
+       r.hidden,
+       (SELECT COUNT(*) FROM video_restaurants vr WHERE vr.restaurant_id = r.id) AS video_count,
+       (SELECT COUNT(*) FROM reviews rv WHERE rv.restaurant_id = r.id) AS review_count,
+       (SELECT COUNT(*) FROM memos mm WHERE mm.restaurant_id = r.id) AS memo_count
+FROM restaurants r
+WHERE r.google_place_id IN (
+    SELECT google_place_id FROM restaurants
+    WHERE google_place_id IS NOT NULL
+    GROUP BY google_place_id HAVING COUNT(*) > 1
+)
+ORDER BY r.google_place_id, r.created_at
+```
+
+Service 계층에서 google_place_id로 그룹핑하여 응답 구조 변환.
+
+## 5. 엣지케이스
+
+- 중복 0건 → 빈 배열.
+- 누군가가 google_place_id를 동시에 변경 중 → 다음 호출에서 반영 (캐시 X).

docs/design/363-map-sdk-branch/README.md

@@ -0,0 +1,112 @@
+# 설계서: 메인 지도 탭 SDK 국내/해외 분기 (#363)
+
+> **상태**: Approved
+> **작성**: [AI] Architect · **최종수정**: 2026-06-16
+> **추적성** — Redmine: #363 · 부모: v0.1.51 1단계(외부 링크 분기) · 관련: MapView.tsx, mobile nearby
+> · 구현 파일: `frontend/src/components/MapView.tsx`(dispatcher), `frontend/src/components/GoogleMapView.tsx`(rename from 기존 MapView 내용), `frontend/src/components/NaverMapView.tsx`(신규), `frontend/src/lib/map-utils.ts`(공용 헬퍼)
+> · 테스트: 본 범위 밖 (수동 — dev 브라우저 검증)
+
+## 1. 목적 (Why)
+
+현재 MapView는 `@vis.gl/react-google-maps` 단일 사용. 한국 식당은 네이버 지도가 지번/도로명/상호/길찾기에서 압도적으로 정확. 메인 지도 탭 자체를 국내/해외 분기.
+
+## 2. 범위
+
+- 포함: MapView를 dispatcher로 전환, 좌표 기반 자동 분기(KR bbox), 네이버 키 미설정 시 GoogleMap fallback.
+- 제외 (별도 후속): 사용자 강제 토글 UI, mixed 화면(한국+해외 동시) 최적화, 모바일 nearby도 동일 분기는 1차 적용 후 검토.
+
+## 3. 인수조건
+
+- [ ] `NEXT_PUBLIC_NAVER_MAP_CLIENT_ID` 환경변수 설정 + 화면 중심이 KR bbox 안이면 NaverMap 렌더.
+- [ ] 키 미설정 또는 화면이 KR 밖이면 GoogleMap 렌더 (현행 동일).
+- [ ] Supercluster + 클러스터/단일 마커 표시, 클릭 → onSelectRestaurant 콜백 동일.
+- [ ] flyTo, onBoundsChanged, 내 위치, 채널 색상 동일하게 동작.
+- [ ] 빌드/타입 회귀 없음.
+
+## 4. 컨텍스트 & 제약
+
+- 네이버 지도 v3: `https://oapi.map.naver.com/openapi/v3/maps.js?ncpClientId=<ID>` 스크립트 로드.
+- 네이버 좌표계: 기본 WGS84 (`naver.maps.LatLng(lat, lng)`).
+- 직접 wrapper 채택 (react-naver-maps 의존성 제거 — 메인터넌스 리스크).
+- Supercluster는 SDK 독립이라 재사용.
+- KR bbox: 위도 33~38.7, 경도 124~132. 화면 중심좌표가 안에 있으면 한국.
+
+## 5. 아키텍처 개요
+
+```
+MapView (dispatcher)
+   │
+   ├─ 화면 중심 좌표가 KR bbox AND 네이버 키 있음 → NaverMapView
+   │     ├─ <script src=naver maps v3> 동적 로드
+   │     ├─ useEffect: new naver.maps.Map(div, ...)
+   │     ├─ Supercluster로 cluster 계산 → markers div overlay
+   │     └─ flyTo: map.setCenter + setZoom
+   │
+   └─ 그 외 → GoogleMapView (기존 MapView 내용 그대로 이전)
+```
+
+## 6. 함수 명세
+
+| 함수 | 책임 | 비고 |
+|---|---|---|
+| `MapView` (dispatcher) | 좌표 기반 분기 | flyTo 또는 첫 마운트 좌표로 판정 |
+| `GoogleMapView` | 기존 MapView 내용 | rename만, 로직 변경 X |
+| `NaverMapView` | 신규 — 네이버 지도 + Supercluster + markers | wrapper 직접 |
+| `useNaverMaps(clientId)` | 스크립트 로드 + ready boolean | 한 번만 로드 |
+| `isKoreaBounds(lat, lng)` | KR bbox 판정 | map-utils 공용 |
+
+## 7. 흐름
+
+1. MapView 마운트 → flyTo or 첫 식당 평균 좌표로 초기 중심 계산.
+2. KR bbox + 키 있음 → NaverMapView 마운트.
+3. NaverMapView: `useNaverMaps` 훅으로 v3 스크립트 로드, ready되면 `new naver.maps.Map(divRef, options)` 생성.
+4. Supercluster로 cluster 계산 → 마커는 absolute positioned div overlay (네이버 OverlayView 또는 자체 좌표 변환).
+5. 사용자 줌/팬 → bounds_changed 이벤트 → 클러스터 재계산 + onBoundsChanged 콜백.
+
+## 8. 엣지케이스
+
+- **네이버 스크립트 로드 실패**: ready=false 유지, dispatcher가 다음 렌더 사이클에서 GoogleMap fallback.
+- **flyTo가 해외 좌표인데 현재 NaverMap 중**: dispatcher 재판정 → GoogleMap로 교체 (remount).
+- **mixed 화면(한국+해외 식당)**: 화면 중심 기준 SDK 선택 → 다른 나라 식당은 화면 밖에 있어 무관.
+- **키 미설정**: 항상 GoogleMap (회귀 0).
+
+## 9. 리스크 & 대안
+
+- **선택**: 직접 wrapper. 의존성 최소, 유지보수 자유.
+- **대안 A**: `react-naver-maps` npm — 빠른 시작이지만 메인터넌스 상태 불확실.
+- **대안 B**: 단일 SDK(Maplibre + 네이버 타일) — 타일 권리 이슈.
+- **트레이드오프**: 직접 wrapper는 초기 코드 양 ↑이지만 한 번 만들면 안정.
+
+## 10. 미해결 질문
+
+- 한 화면 mixed(국가 경계 근처) 동시 마커 — 후속.
+- 사용자 토글 UI — 후속.
+- 모바일 nearby 동일 분기 — 1차 적용 후 결정.
+
+## 11. 실제 구현 기록 (2026-06-16)
+
+### 배포 흐름
+| 버전 | 내용 |
+|---|---|
+| v0.1.51 | **1단계** — 식당 상세 외부 링크 좌표 기반 분기 (`RestaurantDetail.tsx`) |
+| v0.1.52 | **2단계** — MapView dispatcher + NaverMapView/GoogleMapView 분리 + Dockerfile/deploy.sh build-arg |
+| v0.1.53 | **fix**: 인증 파라미터 `ncpClientId` → `ncpKeyId` (NCLOUD 신 정책, 옛 NAVER Developers와 다름) |
+| v0.1.55–56 | 임시 fallback (운영 일시 GoogleMap, 디버그) |
+| v0.1.57 | **안정화 + 재활성** — divRef 첫 렌더 누락 fix, ResizeObserver/rAF, try/catch |
+
+### 운영 진단에서 확인된 사항
+- NCLOUD Maps Application의 Web 서비스 URL은 **스킴 포함**(`https://...`).
+- 옛 NAVER Developers와 NCLOUD는 다른 시스템 — Search Application과 Maps Application은 도메인 중복 충돌 없음.
+- NCLOUD 콘솔의 신규 경로: `Services > Application Services > Maps > Application`.
+
+### NaverMapView 안정화 핵심 결정사항
+- **`divRef` 항상 마운트** (early return 제거) — `ready=false` 동안에도 div를 두고 로딩 메시지는 overlay로 표시.
+- **명시적 `width:100%; height:100%`** + 회색 배경 — 컨테이너 영역이 시각적으로 확인 가능.
+- **ResizeObserver + requestAnimationFrame**으로 컨테이너 0×0 → 정상 크기 변경 시 `m.refresh(true)`.
+- **try/catch + `initError` state** — init 실패 시 화면 가시화.
+
+### 후속 (별도 PR)
+- 사용자 토글 (네이버/구글 강제 선택) UI.
+- mixed 화면(국경 근처) 동시 마커.
+- 모바일 nearby 탭 동일 분기 검토.
+- 채널 색상/InfoWindow 등 GoogleMapView 수준의 디테일을 NaverMapView에 도입.

frontend/Dockerfile

@@ -6,6 +6,7 @@ RUN npm ci
 COPY . .
 ARG NEXT_PUBLIC_GOOGLE_MAPS_API_KEY
 ARG NEXT_PUBLIC_GOOGLE_CLIENT_ID
+ARG NEXT_PUBLIC_NAVER_MAP_CLIENT_ID
 RUN npm run build
 
 # ── Runtime stage ──

frontend/__tests__/Stars.test.tsx

@@ -0,0 +1,36 @@
+/**
+ * #343 — Stars 컴포넌트 렌더 테스트.
+ */
+import { render, screen } from "@testing-library/react";
+import Stars from "@/components/Stars";
+
+describe("Stars", () => {
+  it("renders 5 star slots", () => {
+    const { container } = render(<Stars rating={3} />);
+    // 빈 별 5개 (text-gray-300 클래스 갖는 span)
+    const emptyStars = container.querySelectorAll("span.text-gray-300");
+    expect(emptyStars.length).toBe(5);
+  });
+
+  it("shows aria-label with rating", () => {
+    render(<Stars rating={4.5} />);
+    expect(screen.getByLabelText("4.5점")).toBeInTheDocument();
+  });
+
+  it("clamps rating to 0~5", () => {
+    render(<Stars rating={-1} />);
+    expect(screen.getByLabelText("0점")).toBeInTheDocument();
+    render(<Stars rating={10} />);
+    expect(screen.getByLabelText("5점")).toBeInTheDocument();
+  });
+
+  it("shows number when showNumber + rating > 0", () => {
+    const { container } = render(<Stars rating={3.5} showNumber />);
+    expect(container.textContent).toContain("3.5");
+  });
+
+  it("does not show number when rating is 0 even with showNumber", () => {
+    const { container } = render(<Stars rating={0} showNumber />);
+    expect(container.textContent).not.toContain("0");
+  });
+});

frontend/__tests__/admin-utils.test.ts

@@ -0,0 +1,28 @@
+/**
+ * #343 — admin-utils 순수 함수 단위 테스트.
+ */
+import { getAdminToken, authHeaders } from "@/lib/admin-utils";
+
+describe("admin-utils", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it("getAdminToken returns null when not set", () => {
+    expect(getAdminToken()).toBeNull();
+  });
+
+  it("getAdminToken returns stored token", () => {
+    localStorage.setItem("tasteby_token", "abc123");
+    expect(getAdminToken()).toBe("abc123");
+  });
+
+  it("authHeaders is empty when no token", () => {
+    expect(authHeaders()).toEqual({});
+  });
+
+  it("authHeaders includes Bearer when token set", () => {
+    localStorage.setItem("tasteby_token", "xyz");
+    expect(authHeaders()).toEqual({ Authorization: "Bearer xyz" });
+  });
+});

frontend/__tests__/i18n-config.test.ts

@@ -0,0 +1,42 @@
+/**
+ * #343 — i18n/config 순수 함수 단위 테스트.
+ */
+import { isLocale, detectBrowserLocale, DEFAULT_LOCALE } from "@/i18n/config";
+
+describe("i18n/config.isLocale", () => {
+  it("returns true for supported locales", () => {
+    expect(isLocale("ko")).toBe(true);
+    expect(isLocale("en")).toBe(true);
+    expect(isLocale("ja")).toBe(true);
+    expect(isLocale("es")).toBe(true);
+  });
+
+  it("returns false for unsupported / null / undefined", () => {
+    expect(isLocale("fr")).toBe(false);
+    expect(isLocale("zh")).toBe(false);
+    expect(isLocale(null)).toBe(false);
+    expect(isLocale(undefined)).toBe(false);
+    expect(isLocale("")).toBe(false);
+  });
+});
+
+describe("i18n/config.detectBrowserLocale", () => {
+  // jsdom의 navigator.language는 기본 'en-US'
+  it("returns supported locale from navigator.language", () => {
+    Object.defineProperty(navigator, "language", { value: "en-US", configurable: true });
+    expect(detectBrowserLocale()).toBe("en");
+    Object.defineProperty(navigator, "language", { value: "ko-KR", configurable: true });
+    expect(detectBrowserLocale()).toBe("ko");
+    Object.defineProperty(navigator, "language", { value: "ja", configurable: true });
+    expect(detectBrowserLocale()).toBe("ja");
+    Object.defineProperty(navigator, "language", { value: "es-MX", configurable: true });
+    expect(detectBrowserLocale()).toBe("es");
+  });
+
+  it("falls back to DEFAULT_LOCALE for unsupported", () => {
+    Object.defineProperty(navigator, "language", { value: "fr-FR", configurable: true });
+    expect(detectBrowserLocale()).toBe(DEFAULT_LOCALE);
+    Object.defineProperty(navigator, "language", { value: "zh-CN", configurable: true });
+    expect(detectBrowserLocale()).toBe(DEFAULT_LOCALE);
+  });
+});

frontend/jest.config.ts

@@ -0,0 +1,21 @@
+// #343 — Jest 설정. next/jest로 SWC 자동 통합.
+
+import type { Config } from "jest";
+import nextJest from "next/jest.js";
+
+const createJestConfig = nextJest({
+  // 테스트 환경의 Next.js 앱 루트
+  dir: "./",
+});
+
+const customConfig: Config = {
+  // jest-dom matchers는 setupFilesAfterEnv로 등록 (Jest framework 로드 후)
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
+  testEnvironment: "jsdom",
+  moduleNameMapper: {
+    "^@/(.*)$": "<rootDir>/src/$1",
+  },
+  testPathIgnorePatterns: ["<rootDir>/.next/", "<rootDir>/node_modules/"],
+};
+
+export default createJestConfig(customConfig);

frontend/jest.setup.ts

@@ -0,0 +1,2 @@
+// #343 — Jest setup. @testing-library/jest-dom matchers 확장.
+import "@testing-library/jest-dom";

frontend/next.config.ts

@@ -2,6 +2,14 @@ import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   output: "standalone",
+  // #343 — 외부 이미지 도메인 허용 (next/image)
+  images: {
+    remotePatterns: [
+      { protocol: "https", hostname: "lh3.googleusercontent.com" }, // Google avatar
+      { protocol: "https", hostname: "i.ytimg.com" },               // YouTube thumbnail
+      { protocol: "https", hostname: "yt3.ggpht.com" },             // YouTube channel avatar
+    ],
+  },
 };
 
 export default nextConfig;

frontend/package.json

@@ -6,7 +6,9 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "eslint"
+    "lint": "eslint",
+    "test": "jest",
+    "test:watch": "jest --watch"
   },
   "dependencies": {
     "@phosphor-icons/react": "^2.1.10",
@@ -22,11 +24,17 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jest": "^30.0.0",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "eslint": "^9",
     "eslint-config-next": "16.1.6",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
     "tailwindcss": "^4",
     "typescript": "^5"
   }

frontend/src/app/admin/_panels/RestaurantsPanel.tsx

@@ -1,5 +1,5 @@
 "use client";
-import { getAdminToken } from "@/lib/admin-utils";
+import { getAdminToken, consumeSseStream } from "@/lib/admin-utils";
 
 import { useCallback, useEffect, useState } from "react";
 import { api } from "@/lib/api";
@@ -209,30 +209,19 @@ export function RestaurantsPanel({ isAdmin }: { isAdmin: boolean }) {
                   method: "POST",
                   headers: { Authorization: `Bearer ${getAdminToken()}` },
                 });
-                const reader = res.body!.getReader();
-                const decoder = new TextDecoder();
-                let buf = "";
-                while (true) {
-                  const { done, value } = await reader.read();
-                  if (done) break;
-                  buf += decoder.decode(value, { stream: true });
-                  const lines = buf.split("\n");
-                  buf = lines.pop() || "";
-                  for (const line of lines) {
-                    const m = line.match(/^data:(.+)$/);
-                    if (!m) continue;
-                    const evt = JSON.parse(m[1]);
+                // #351 — consumeSseStream으로 통일
+                await consumeSseStream(res, (raw) => {
+                  const evt = raw as { type: string; [k: string]: unknown };
                   if (evt.type === "processing" || evt.type === "done" || evt.type === "notfound" || evt.type === "error") {
                     setBulkTablingProgress(p => ({
-                        ...p, current: evt.current, total: evt.total || p.total, name: evt.name,
+                      ...p, current: evt.current as number, total: (evt.total as number) || p.total, name: evt.name as string,
                       linked: evt.type === "done" ? p.linked + 1 : p.linked,
                       notFound: (evt.type === "notfound" || evt.type === "error") ? p.notFound + 1 : p.notFound,
                     }));
                   } else if (evt.type === "complete") {
                     alert(`완료! 연결: ${evt.linked}개, 미발견: ${evt.notFound}개`);
                   }
-                  }
-                }
+                });
               } catch (e) { alert("벌크 테이블링 실패: " + (e instanceof Error ? e.message : String(e))); }
               finally { setBulkTabling(false); load(); }
             }}
@@ -287,30 +276,19 @@ export function RestaurantsPanel({ isAdmin }: { isAdmin: boolean }) {
                   method: "POST",
                   headers: { Authorization: `Bearer ${getAdminToken()}` },
                 });
-                const reader = res.body!.getReader();
-                const decoder = new TextDecoder();
-                let buf = "";
-                while (true) {
-                  const { done, value } = await reader.read();
-                  if (done) break;
-                  buf += decoder.decode(value, { stream: true });
-                  const lines = buf.split("\n");
-                  buf = lines.pop() || "";
-                  for (const line of lines) {
-                    const m = line.match(/^data:(.+)$/);
-                    if (!m) continue;
-                    const evt = JSON.parse(m[1]);
+                // #351 — consumeSseStream으로 통일
+                await consumeSseStream(res, (raw) => {
+                  const evt = raw as { type: string; [k: string]: unknown };
                   if (evt.type === "processing" || evt.type === "done" || evt.type === "notfound" || evt.type === "error") {
                     setBulkCatchtableProgress(p => ({
-                        ...p, current: evt.current, total: evt.total || p.total, name: evt.name,
+                      ...p, current: evt.current as number, total: (evt.total as number) || p.total, name: evt.name as string,
                       linked: evt.type === "done" ? p.linked + 1 : p.linked,
                       notFound: (evt.type === "notfound" || evt.type === "error") ? p.notFound + 1 : p.notFound,
                     }));
                   } else if (evt.type === "complete") {
                     alert(`완료! 연결: ${evt.linked}개, 미발견: ${evt.notFound}개`);
                   }
-                  }
-                }
+                });
               } catch (e) { alert("벌크 캐치테이블 실패: " + (e instanceof Error ? e.message : String(e))); }
               finally { setBulkCatchtable(false); load(); }
             }}

frontend/src/app/admin/_panels/VideosPanel.tsx

@@ -1,5 +1,5 @@
 "use client";
-import { getAdminToken } from "@/lib/admin-utils";
+import { getAdminToken, consumeSseStream } from "@/lib/admin-utils";
 
 import { useCallback, useEffect, useState } from "react";
 import { api } from "@/lib/api";
@@ -209,39 +209,25 @@ export function VideosPanel({ isAdmin }: { isAdmin: boolean }) {
         setBulkProgress(null);
         return;
       }
-      const reader = resp.body?.getReader();
-      const decoder = new TextDecoder();
-      if (!reader) { setRunning(false); return; }
-
-      let buf = "";
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buf += decoder.decode(value, { stream: true });
-        const lines = buf.split("\n");
-        buf = lines.pop() || "";
-        for (const line of lines) {
-          if (!line.startsWith("data: ")) continue;
-          try {
-            const ev = JSON.parse(line.slice(6));
+      // #351 — consumeSseStream으로 통일
+      await consumeSseStream(resp, (raw) => {
+        const ev = raw as { type: string; [k: string]: unknown };
         if (ev.type === "processing") {
-              setBulkProgress((p) => p ? { ...p, current: ev.index + 1, currentTitle: ev.title, waiting: undefined } : p);
+          setBulkProgress((p) => p ? { ...p, current: (ev.index as number) + 1, currentTitle: ev.title as string, waiting: undefined } : p);
         } else if (ev.type === "wait") {
-              setBulkProgress((p) => p ? { ...p, waiting: ev.delay } : p);
+          setBulkProgress((p) => p ? { ...p, waiting: ev.delay as number } : p);
         } else if (ev.type === "done") {
           const detail = isTranscript
-                ? `${ev.source} / ${ev.length?.toLocaleString()}자`
+            ? `${ev.source} / ${(ev.length as number)?.toLocaleString()}자`
             : `${ev.restaurants}개 식당`;
-              setBulkProgress((p) => p ? { ...p, results: [...p.results, { title: ev.title, detail }] } : p);
+          setBulkProgress((p) => p ? { ...p, results: [...p.results, { title: ev.title as string, detail }] } : p);
         } else if (ev.type === "error") {
-              setBulkProgress((p) => p ? { ...p, results: [...p.results, { title: ev.title, detail: ev.message, error: true }] } : p);
+          setBulkProgress((p) => p ? { ...p, results: [...p.results, { title: ev.title as string, detail: ev.message as string, error: true }] } : p);
         } else if (ev.type === "complete") {
           setRunning(false);
           load();
         }
-          } catch { /* ignore */ }
-        }
-      }
+      });
       setRunning(false);
       load();
     } catch {
@@ -264,30 +250,17 @@ export function VideosPanel({ isAdmin }: { isAdmin: boolean }) {
         setRebuildingVectors(false);
         return;
       }
-      const reader = resp.body?.getReader();
-      const decoder = new TextDecoder();
-      if (!reader) { setRebuildingVectors(false); return; }
-      let buf = "";
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buf += decoder.decode(value, { stream: true });
-        const lines = buf.split("\n");
-        buf = lines.pop() || "";
-        for (const line of lines) {
-          if (!line.startsWith("data: ")) continue;
-          try {
-            const ev = JSON.parse(line.slice(6));
+      // #351 — consumeSseStream으로 통일
+      await consumeSseStream(resp, (raw) => {
+        const ev = raw as { status?: string; type?: string; [k: string]: unknown };
         if (ev.status === "progress" || ev.type === "progress") {
-              setVectorProgress({ phase: ev.phase, current: ev.current, total: ev.total, name: ev.name });
+          setVectorProgress({ phase: ev.phase as string, current: ev.current as number, total: ev.total as number, name: ev.name as string });
         } else if (ev.status === "done" || ev.type === "done") {
-              setVectorProgress({ phase: "done", current: ev.total, total: ev.total });
+          setVectorProgress({ phase: "done", current: ev.total as number, total: ev.total as number });
         } else if (ev.type === "error") {
           alert(`벡터 재생성 오류: ${ev.message}`);
         }
-          } catch { /* ignore */ }
-        }
-      }
+      });
       setRebuildingVectors(false);
     } catch {
       setRebuildingVectors(false);
@@ -309,30 +282,17 @@ export function VideosPanel({ isAdmin }: { isAdmin: boolean }) {
         setRemappingCuisine(false);
         return;
       }
-      const reader = resp.body?.getReader();
-      const decoder = new TextDecoder();
-      if (!reader) { setRemappingCuisine(false); return; }
-      let buf = "";
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buf += decoder.decode(value, { stream: true });
-        const lines = buf.split("\n");
-        buf = lines.pop() || "";
-        for (const line of lines) {
-          if (!line.startsWith("data: ")) continue;
-          try {
-            const ev = JSON.parse(line.slice(6));
+      // #351 — consumeSseStream으로 통일
+      await consumeSseStream(resp, (raw) => {
+        const ev = raw as { type: string; [k: string]: unknown };
         if (ev.type === "processing" || ev.type === "batch_done") {
-              setRemapProgress({ current: ev.current, total: ev.total, updated: ev.updated || 0 });
+          setRemapProgress({ current: ev.current as number, total: ev.total as number, updated: (ev.updated as number) || 0 });
         } else if (ev.type === "complete") {
-              setRemapProgress({ current: ev.total, total: ev.total, updated: ev.updated });
+          setRemapProgress({ current: ev.total as number, total: ev.total as number, updated: ev.updated as number });
         } else if (ev.type === "error") {
           alert(`재분류 오류: ${ev.message}`);
         }
-          } catch { /* ignore */ }
-        }
-      }
+      });
       setRemappingCuisine(false);
     } catch {
       setRemappingCuisine(false);
@@ -354,30 +314,17 @@ export function VideosPanel({ isAdmin }: { isAdmin: boolean }) {
         setRemappingFoods(false);
         return;
       }
-      const reader = resp.body?.getReader();
-      const decoder = new TextDecoder();
-      if (!reader) { setRemappingFoods(false); return; }
-      let buf = "";
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buf += decoder.decode(value, { stream: true });
-        const lines = buf.split("\n");
-        buf = lines.pop() || "";
-        for (const line of lines) {
-          if (!line.startsWith("data: ")) continue;
-          try {
-            const ev = JSON.parse(line.slice(6));
+      // #351 — consumeSseStream으로 통일
+      await consumeSseStream(resp, (raw) => {
+        const ev = raw as { type: string; [k: string]: unknown };
         if (ev.type === "processing" || ev.type === "batch_done") {
-              setFoodsProgress({ current: ev.current, total: ev.total, updated: ev.updated || 0 });
+          setFoodsProgress({ current: ev.current as number, total: ev.total as number, updated: (ev.updated as number) || 0 });
         } else if (ev.type === "complete") {
-              setFoodsProgress({ current: ev.total, total: ev.total, updated: ev.updated });
+          setFoodsProgress({ current: ev.total as number, total: ev.total as number, updated: ev.updated as number });
         } else if (ev.type === "error") {
           alert(`메뉴 태그 재생성 오류: ${ev.message}`);
         }
-          } catch { /* ignore */ }
-        }
-      }
+      });
       setRemappingFoods(false);
     } catch {
       setRemappingFoods(false);

frontend/src/components/GoogleMapView.tsx

@@ -0,0 +1,395 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  APIProvider,
+  Map,
+  AdvancedMarker,
+  InfoWindow,
+  useMap,
+} from "@vis.gl/react-google-maps";
+import Supercluster from "supercluster";
+import type { Restaurant } from "@/lib/api";
+import { getCuisineIcon } from "@/lib/cuisine-icons";
+import Icon from "@/components/Icon";
+
+const SEOUL_CENTER = { lat: 37.5665, lng: 126.978 };
+const API_KEY = process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY || "";
+
+// Channel color palette
+const CHANNEL_COLORS = [
+  { bg: "#fff7ed", text: "#78350f", border: "#f59e0b", arrow: "#f59e0b" }, // amber (default)
+  { bg: "#eff6ff", text: "#1e3a5f", border: "#3b82f6", arrow: "#3b82f6" }, // blue
+  { bg: "#f0fdf4", text: "#14532d", border: "#22c55e", arrow: "#22c55e" }, // green
+  { bg: "#fdf2f8", text: "#831843", border: "#ec4899", arrow: "#ec4899" }, // pink
+  { bg: "#faf5ff", text: "#581c87", border: "#a855f7", arrow: "#a855f7" }, // purple
+  { bg: "#fff1f2", text: "#7f1d1d", border: "#ef4444", arrow: "#ef4444" }, // red
+  { bg: "#f0fdfa", text: "#134e4a", border: "#14b8a6", arrow: "#14b8a6" }, // teal
+  { bg: "#fefce8", text: "#713f12", border: "#eab308", arrow: "#eab308" }, // yellow
+];
+
+function getChannelColorMap(restaurants: Restaurant[]) {
+  const channels = new Set<string>();
+  restaurants.forEach((r) => r.channels?.forEach((ch) => channels.add(ch)));
+  const map: Record<string, typeof CHANNEL_COLORS[0]> = {};
+  let i = 0;
+  for (const ch of channels) {
+    map[ch] = CHANNEL_COLORS[i % CHANNEL_COLORS.length];
+    i++;
+  }
+  return map;
+}
+
+import type { MapBounds, FlyTo, MapViewProps } from "@/components/MapView.types";
+
+type RestaurantProps = { restaurant: Restaurant };
+type RestaurantFeature = Supercluster.PointFeature<RestaurantProps>;
+
+function useSupercluster(restaurants: Restaurant[]) {
+  // #278 — indexRef 제거 (set만 되고 read 없는 dead code)
+  const points: RestaurantFeature[] = useMemo(
+    () =>
+      restaurants.map((r) => ({
+        type: "Feature" as const,
+        geometry: { type: "Point" as const, coordinates: [r.longitude, r.latitude] },
+        properties: { restaurant: r },
+      })),
+    [restaurants]
+  );
+
+  const index = useMemo(() => {
+    const sc = new Supercluster<{ restaurant: Restaurant }>({
+      radius: 60,
+      maxZoom: 16,
+      minPoints: 2,
+    });
+    sc.load(points);
+    return sc;
+  }, [points]);
+
+  const getClusters = useCallback(
+    (bounds: MapBounds, zoom: number) => {
+      return index.getClusters(
+        [bounds.west, bounds.south, bounds.east, bounds.north],
+        Math.floor(zoom)
+      );
+    },
+    [index]
+  );
+
+  const getExpansionZoom = useCallback(
+    (clusterId: number): number => {
+      try {
+        return index.getClusterExpansionZoom(clusterId);
+      } catch {
+        return 17;
+      }
+    },
+    [index]
+  );
+
+  return { getClusters, getExpansionZoom, index };
+}
+
+function getClusterSize(count: number): number {
+  if (count < 10) return 36;
+  if (count < 50) return 42;
+  if (count < 100) return 48;
+  return 54;
+}
+
+function MapContent({ restaurants, selected, onSelectRestaurant, flyTo, activeChannel }: Omit<MapViewProps, "onMyLocation" | "onBoundsChanged">) {
+  const map = useMap();
+  const [infoTarget, setInfoTarget] = useState<Restaurant | null>(null);
+  const [zoom, setZoom] = useState(13);
+  const [bounds, setBounds] = useState<MapBounds | null>(null);
+  const channelColors = useMemo(() => getChannelColorMap(restaurants), [restaurants]);
+  const { getClusters, getExpansionZoom } = useSupercluster(restaurants);
+
+  // #278 — restaurantMap 제거 (빌드만 되고 렌더에서 사용 안 됨, dead code)
+
+  const clusters = useMemo(() => {
+    if (!bounds) return [];
+    return getClusters(bounds, zoom);
+  }, [bounds, zoom, getClusters]);
+
+  const handleMarkerClick = useCallback(
+    (r: Restaurant) => {
+      setInfoTarget(r);
+      onSelectRestaurant?.(r);
+    },
+    [onSelectRestaurant]
+  );
+
+  const handleClusterClick = useCallback(
+    (clusterId: number, lng: number, lat: number) => {
+      if (!map) return;
+      const expansionZoom = Math.min(getExpansionZoom(clusterId), 18);
+      map.panTo({ lat, lng });
+      map.setZoom(expansionZoom);
+    },
+    [map, getExpansionZoom]
+  );
+
+  // Track camera changes for clustering
+  useEffect(() => {
+    if (!map) return;
+    const listener = map.addListener("idle", () => {
+      const b = map.getBounds();
+      const z = map.getZoom();
+      if (b && z != null) {
+        const ne = b.getNorthEast();
+        const sw = b.getSouthWest();
+        setBounds({ north: ne.lat(), south: sw.lat(), east: ne.lng(), west: sw.lng() });
+        setZoom(z);
+      }
+    });
+    // Trigger initial bounds
+    const b = map.getBounds();
+    const z = map.getZoom();
+    if (b && z != null) {
+      const ne = b.getNorthEast();
+      const sw = b.getSouthWest();
+      setBounds({ north: ne.lat(), south: sw.lat(), east: ne.lng(), west: sw.lng() });
+      setZoom(z);
+    }
+    return () => google.maps.event.removeListener(listener);
+  }, [map]);
+
+  // Fly to a specific location (region filter)
+  useEffect(() => {
+    if (!map || !flyTo) return;
+    map.panTo({ lat: flyTo.lat, lng: flyTo.lng });
+    if (flyTo.zoom) map.setZoom(flyTo.zoom);
+  }, [map, flyTo]);
+
+  // Pan and zoom to selected restaurant
+  useEffect(() => {
+    if (!map || !selected) return;
+    map.panTo({ lat: selected.latitude, lng: selected.longitude });
+    map.setZoom(16);
+    setInfoTarget(selected);
+  }, [map, selected]);
+
+  return (
+    <>
+      {clusters.map((feature) => {
+        const [lng, lat] = feature.geometry.coordinates;
+        const isCluster = feature.properties && "cluster" in feature.properties && feature.properties.cluster;
+
+        if (isCluster) {
+          const { cluster_id, point_count } = feature.properties as Supercluster.ClusterProperties;
+          const size = getClusterSize(point_count);
+          return (
+            <AdvancedMarker
+              key={`cluster-${cluster_id}`}
+              position={{ lat, lng }}
+              onClick={() => handleClusterClick(cluster_id, lng, lat)}
+              zIndex={100}
+            >
+              <div
+                role="button"
+                aria-label={`${point_count}개 식당이 모인 클러스터, 클릭하면 확대됩니다`}
+                style={{
+                  width: size,
+                  height: size,
+                  borderRadius: "50%",
+                  background: "linear-gradient(135deg, #E8720C 0%, #f59e0b 100%)",
+                  border: "3px solid #fff",
+                  boxShadow: "0 2px 8px rgba(0,0,0,0.25)",
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  color: "#fff",
+                  fontSize: size > 42 ? 15 : 13,
+                  fontWeight: 700,
+                  cursor: "pointer",
+                  transition: "transform 0.2s ease",
+                }}
+              >
+                {point_count}
+              </div>
+            </AdvancedMarker>
+          );
+        }
+
+        // Individual marker
+        const r = (feature.properties as { restaurant: Restaurant }).restaurant;
+        const isSelected = selected?.id === r.id;
+        const isClosed = r.business_status === "CLOSED_PERMANENTLY";
+        const chKey = activeChannel && r.channels?.includes(activeChannel) ? activeChannel : r.channels?.[0];
+        const chColor = chKey ? channelColors[chKey] : CHANNEL_COLORS[0];
+        const c = chColor || CHANNEL_COLORS[0];
+        return (
+          <AdvancedMarker
+            key={r.id}
+            position={{ lat: r.latitude, lng: r.longitude }}
+            onClick={() => handleMarkerClick(r)}
+            zIndex={isSelected ? 1000 : 1}
+          >
+            <div
+              role="button"
+              aria-label={`${r.name}${isClosed ? ' (폐업)' : ''}, 클릭하면 상세 정보가 표시됩니다`}
+              style={{ display: "flex", flexDirection: "column", alignItems: "center", transition: "transform 0.2s ease", transform: isSelected ? "scale(1.15)" : "scale(1)", opacity: isClosed ? 0.5 : 1 }}>
+              <div
+                style={{
+                  padding: "4px 8px",
+                  backgroundColor: isSelected ? "#2563eb" : isClosed ? "#f3f4f6" : c.bg,
+                  color: isSelected ? "#fff" : isClosed ? "#9ca3af" : c.text,
+                  fontSize: 12,
+                  fontWeight: 600,
+                  borderRadius: 6,
+                  border: isSelected ? "2px solid #1d4ed8" : `1.5px solid ${c.border}`,
+                  boxShadow: isSelected
+                    ? "0 2px 8px rgba(37,99,235,0.4)"
+                    : `0 1px 4px ${c.border}40`,
+                  whiteSpace: "nowrap",
+                  maxWidth: 120,
+                  overflow: "hidden",
+                  textOverflow: "ellipsis",
+                  textDecoration: isClosed ? "line-through" : "none",
+                }}
+              >
+                <span className="material-symbols-rounded" style={{ fontSize: 14, width: 14, height: 14, overflow: "hidden", display: "inline-flex", alignItems: "center", justifyContent: "center", marginRight: 3, verticalAlign: "middle", color: "#E8720C" }}>{getCuisineIcon(r.cuisine_type)}</span>
+                {r.name}
+              </div>
+              <div
+                style={{
+                  width: 0,
+                  height: 0,
+                  borderLeft: "6px solid transparent",
+                  borderRight: "6px solid transparent",
+                  borderTop: isSelected ? "6px solid #1d4ed8" : `6px solid ${c.arrow}`,
+                  marginTop: -1,
+                }}
+              />
+            </div>
+          </AdvancedMarker>
+        );
+      })}
+
+      {infoTarget && (
+        <InfoWindow
+          position={{ lat: infoTarget.latitude, lng: infoTarget.longitude }}
+          onCloseClick={() => setInfoTarget(null)}
+        >
+          <div style={{ backgroundColor: "#ffffff", color: "#171717", colorScheme: "light" }} className="max-w-xs p-1">
+            <div className="flex items-center gap-2">
+              <h3 className="font-bold text-base" style={{ color: "#171717" }}><span className="material-symbols-rounded" style={{ fontSize: 18, width: 18, height: 18, overflow: "hidden", display: "inline-flex", alignItems: "center", justifyContent: "center", verticalAlign: "middle", color: "#E8720C", marginRight: 4 }}>{getCuisineIcon(infoTarget.cuisine_type)}</span>{infoTarget.name}</h3>
+              {infoTarget.business_status === "CLOSED_PERMANENTLY" && (
+                <span className="px-1.5 py-0.5 bg-red-100 text-red-700 rounded text-[10px] font-semibold">폐업</span>
+              )}
+              {infoTarget.business_status === "CLOSED_TEMPORARILY" && (
+                <span className="px-1.5 py-0.5 bg-yellow-100 text-yellow-700 rounded text-[10px] font-semibold">임시휴업</span>
+              )}
+            </div>
+            {infoTarget.rating && (
+              <p className="text-xs mt-0.5">
+                <span className="text-yellow-500">★</span> {infoTarget.rating}
+                {infoTarget.rating_count && (
+                  <span className="text-gray-400 ml-1">({infoTarget.rating_count.toLocaleString()})</span>
+                )}
+              </p>
+            )}
+            {infoTarget.cuisine_type && (
+              <p className="text-xs text-gray-500">{infoTarget.cuisine_type}</p>
+            )}
+            {infoTarget.address && (
+              <p className="text-[11px] text-gray-400 mt-1">{infoTarget.address}</p>
+            )}
+            {infoTarget.price_range && (
+              <p className="text-[11px] text-gray-400">{infoTarget.price_range}</p>
+            )}
+            {infoTarget.phone && (
+              <p className="text-[11px] text-gray-400">{infoTarget.phone}</p>
+            )}
+            <button
+              onClick={() => onSelectRestaurant?.(infoTarget)}
+              className="mt-2 text-sm text-blue-600 hover:underline"
+            >
+              상세 보기
+            </button>
+          </div>
+        </InfoWindow>
+      )}
+    </>
+  );
+}
+
+export default function GoogleMapView({ restaurants, selected, onSelectRestaurant, onBoundsChanged, flyTo, onMyLocation, activeChannel }: MapViewProps) {
+  const channelColors = useMemo(() => getChannelColorMap(restaurants), [restaurants]);
+  const channelNames = useMemo(() => {
+    const names = Object.keys(channelColors);
+    if (activeChannel) return names.filter((n) => n === activeChannel);
+    return names;
+  }, [channelColors, activeChannel]);
+  const boundsTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const handleCameraChanged = useCallback((ev: { detail: { bounds: { north: number; south: number; east: number; west: number } } }) => {
+    if (!onBoundsChanged) return;
+    if (boundsTimerRef.current) clearTimeout(boundsTimerRef.current);
+    boundsTimerRef.current = setTimeout(() => {
+      const { north, south, east, west } = ev.detail.bounds;
+      onBoundsChanged({ north, south, east, west });
+    }, 150);
+  }, [onBoundsChanged]);
+
+  // #278 — 언마운트 시 디바운스 타이머 정리 (메모리 누수 + unmounted setState 경고 방지)
+  useEffect(() => {
+    return () => {
+      if (boundsTimerRef.current) clearTimeout(boundsTimerRef.current);
+    };
+  }, []);
+
+  return (
+    <APIProvider apiKey={API_KEY}>
+      <Map
+        defaultCenter={SEOUL_CENTER}
+        defaultZoom={13}
+        mapId="tasteby-map"
+        className="h-full w-full"
+        colorScheme="LIGHT"
+        mapTypeControl={false}
+        fullscreenControl={false}
+        onCameraChanged={handleCameraChanged}
+      >
+        <MapContent
+          restaurants={restaurants}
+          selected={selected}
+          onSelectRestaurant={onSelectRestaurant}
+          flyTo={flyTo}
+          activeChannel={activeChannel}
+        />
+      </Map>
+      {onMyLocation && (
+        <button
+          onClick={onMyLocation}
+          aria-label="내 위치로 이동"
+          // #278 — 44×44px 터치 영역 확보 (이전 36px)
+          className="absolute top-2 right-2 w-11 h-11 bg-surface rounded-lg shadow-md flex items-center justify-center text-gray-600 dark:text-gray-300 hover:text-brand-500 dark:hover:text-brand-400 transition-colors z-10 touch-manipulation"
+          title="내 위치"
+        >
+          <Icon name="my_location" size={22} />
+        </button>
+      )}
+      {channelNames.length > 0 && (
+        <div
+          role="region"
+          aria-label="채널 범례"
+          className="absolute bottom-2 left-2 bg-surface/90 backdrop-blur-sm rounded-lg shadow px-2.5 py-1.5 flex flex-wrap gap-x-3 gap-y-1 text-[11px] z-10"
+        >
+          {channelNames.map((ch) => (
+            <div key={ch} className="flex items-center gap-1">
+              <span
+                aria-hidden="true"
+                className="inline-block w-2.5 h-2.5 rounded-full border"
+                style={{ backgroundColor: channelColors[ch].border, borderColor: channelColors[ch].border }}
+              />
+              <span className="text-gray-700 dark:text-gray-300">{ch}</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </APIProvider>
+  );
+}

frontend/src/components/MapView.tsx

@@ -1,416 +1,37 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import {
-  APIProvider,
-  Map,
-  AdvancedMarker,
-  InfoWindow,
-  useMap,
-} from "@vis.gl/react-google-maps";
-import Supercluster from "supercluster";
-import type { Restaurant } from "@/lib/api";
-import { getCuisineIcon } from "@/lib/cuisine-icons";
-import Icon from "@/components/Icon";
+import GoogleMapView from "@/components/GoogleMapView";
+import NaverMapView from "@/components/NaverMapView";
+import { isKoreaCoord, type MapBounds, type FlyTo, type MapViewProps } from "@/components/MapView.types";
 
-const SEOUL_CENTER = { lat: 37.5665, lng: 126.978 };
-const API_KEY = process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY || "";
+export type { MapBounds, FlyTo };
 
-// Channel color palette
-const CHANNEL_COLORS = [
-  { bg: "#fff7ed", text: "#78350f", border: "#f59e0b", arrow: "#f59e0b" }, // amber (default)
-  { bg: "#eff6ff", text: "#1e3a5f", border: "#3b82f6", arrow: "#3b82f6" }, // blue
-  { bg: "#f0fdf4", text: "#14532d", border: "#22c55e", arrow: "#22c55e" }, // green
-  { bg: "#fdf2f8", text: "#831843", border: "#ec4899", arrow: "#ec4899" }, // pink
-  { bg: "#faf5ff", text: "#581c87", border: "#a855f7", arrow: "#a855f7" }, // purple
-  { bg: "#fff1f2", text: "#7f1d1d", border: "#ef4444", arrow: "#ef4444" }, // red
-  { bg: "#f0fdfa", text: "#134e4a", border: "#14b8a6", arrow: "#14b8a6" }, // teal
-  { bg: "#fefce8", text: "#713f12", border: "#eab308", arrow: "#eab308" }, // yellow
-];
+const NAVER_KEY = process.env.NEXT_PUBLIC_NAVER_MAP_CLIENT_ID || "";
 
-function getChannelColorMap(restaurants: Restaurant[]) {
-  const channels = new Set<string>();
-  restaurants.forEach((r) => r.channels?.forEach((ch) => channels.add(ch)));
-  const map: Record<string, typeof CHANNEL_COLORS[0]> = {};
-  let i = 0;
-  for (const ch of channels) {
-    map[ch] = CHANNEL_COLORS[i % CHANNEL_COLORS.length];
-    i++;
+/**
+ * #363 — 메인 지도 dispatcher.
+ * - 키 미설정: GoogleMap (회귀 0)
+ * - flyTo 또는 selected 좌표가 KR bbox: NaverMap
+ * - 그 외 (해외 + 좌표 추정): GoogleMap
+ * - 초기 마운트 시 화면 중심을 추정할 수 없으면 식당 평균 좌표로.
+ */
+export default function MapView(props: MapViewProps) {
+  if (!NAVER_KEY) return <GoogleMapView {...props} />;
+
+  const targetLat = props.flyTo?.lat ?? props.selected?.latitude ?? avgLat(props.restaurants);
+  const targetLng = props.flyTo?.lng ?? props.selected?.longitude ?? avgLng(props.restaurants);
+
+  if (targetLat != null && targetLng != null && isKoreaCoord(targetLat, targetLng)) {
+    return <NaverMapView {...props} />;
   }
-  return map;
+  return <GoogleMapView {...props} />;
 }
 
-export interface MapBounds {
-  north: number;
-  south: number;
-  east: number;
-  west: number;
+function avgLat(rs: MapViewProps["restaurants"]): number | null {
+  if (!rs.length) return null;
+  return rs.reduce((s, r) => s + r.latitude, 0) / rs.length;
 }
-
-export interface FlyTo {
-  lat: number;
-  lng: number;
-  zoom?: number;
-}
-
-interface MapViewProps {
-  restaurants: Restaurant[];
-  selected?: Restaurant | null;
-  onSelectRestaurant?: (r: Restaurant) => void;
-  onBoundsChanged?: (bounds: MapBounds) => void;
-  flyTo?: FlyTo | null;
-  onMyLocation?: () => void;
-  activeChannel?: string;
-}
-
-type RestaurantProps = { restaurant: Restaurant };
-type RestaurantFeature = Supercluster.PointFeature<RestaurantProps>;
-
-function useSupercluster(restaurants: Restaurant[]) {
-  // #278 — indexRef 제거 (set만 되고 read 없는 dead code)
-  const points: RestaurantFeature[] = useMemo(
-    () =>
-      restaurants.map((r) => ({
-        type: "Feature" as const,
-        geometry: { type: "Point" as const, coordinates: [r.longitude, r.latitude] },
-        properties: { restaurant: r },
-      })),
-    [restaurants]
-  );
-
-  const index = useMemo(() => {
-    const sc = new Supercluster<{ restaurant: Restaurant }>({
-      radius: 60,
-      maxZoom: 16,
-      minPoints: 2,
-    });
-    sc.load(points);
-    return sc;
-  }, [points]);
-
-  const getClusters = useCallback(
-    (bounds: MapBounds, zoom: number) => {
-      return index.getClusters(
-        [bounds.west, bounds.south, bounds.east, bounds.north],
-        Math.floor(zoom)
-      );
-    },
-    [index]
-  );
-
-  const getExpansionZoom = useCallback(
-    (clusterId: number): number => {
-      try {
-        return index.getClusterExpansionZoom(clusterId);
-      } catch {
-        return 17;
-      }
-    },
-    [index]
-  );
-
-  return { getClusters, getExpansionZoom, index };
-}
-
-function getClusterSize(count: number): number {
-  if (count < 10) return 36;
-  if (count < 50) return 42;
-  if (count < 100) return 48;
-  return 54;
-}
-
-function MapContent({ restaurants, selected, onSelectRestaurant, flyTo, activeChannel }: Omit<MapViewProps, "onMyLocation" | "onBoundsChanged">) {
-  const map = useMap();
-  const [infoTarget, setInfoTarget] = useState<Restaurant | null>(null);
-  const [zoom, setZoom] = useState(13);
-  const [bounds, setBounds] = useState<MapBounds | null>(null);
-  const channelColors = useMemo(() => getChannelColorMap(restaurants), [restaurants]);
-  const { getClusters, getExpansionZoom } = useSupercluster(restaurants);
-
-  // #278 — restaurantMap 제거 (빌드만 되고 렌더에서 사용 안 됨, dead code)
-
-  const clusters = useMemo(() => {
-    if (!bounds) return [];
-    return getClusters(bounds, zoom);
-  }, [bounds, zoom, getClusters]);
-
-  const handleMarkerClick = useCallback(
-    (r: Restaurant) => {
-      setInfoTarget(r);
-      onSelectRestaurant?.(r);
-    },
-    [onSelectRestaurant]
-  );
-
-  const handleClusterClick = useCallback(
-    (clusterId: number, lng: number, lat: number) => {
-      if (!map) return;
-      const expansionZoom = Math.min(getExpansionZoom(clusterId), 18);
-      map.panTo({ lat, lng });
-      map.setZoom(expansionZoom);
-    },
-    [map, getExpansionZoom]
-  );
-
-  // Track camera changes for clustering
-  useEffect(() => {
-    if (!map) return;
-    const listener = map.addListener("idle", () => {
-      const b = map.getBounds();
-      const z = map.getZoom();
-      if (b && z != null) {
-        const ne = b.getNorthEast();
-        const sw = b.getSouthWest();
-        setBounds({ north: ne.lat(), south: sw.lat(), east: ne.lng(), west: sw.lng() });
-        setZoom(z);
-      }
-    });
-    // Trigger initial bounds
-    const b = map.getBounds();
-    const z = map.getZoom();
-    if (b && z != null) {
-      const ne = b.getNorthEast();
-      const sw = b.getSouthWest();
-      setBounds({ north: ne.lat(), south: sw.lat(), east: ne.lng(), west: sw.lng() });
-      setZoom(z);
-    }
-    return () => google.maps.event.removeListener(listener);
-  }, [map]);
-
-  // Fly to a specific location (region filter)
-  useEffect(() => {
-    if (!map || !flyTo) return;
-    map.panTo({ lat: flyTo.lat, lng: flyTo.lng });
-    if (flyTo.zoom) map.setZoom(flyTo.zoom);
-  }, [map, flyTo]);
-
-  // Pan and zoom to selected restaurant
-  useEffect(() => {
-    if (!map || !selected) return;
-    map.panTo({ lat: selected.latitude, lng: selected.longitude });
-    map.setZoom(16);
-    setInfoTarget(selected);
-  }, [map, selected]);
-
-  return (
-    <>
-      {clusters.map((feature) => {
-        const [lng, lat] = feature.geometry.coordinates;
-        const isCluster = feature.properties && "cluster" in feature.properties && feature.properties.cluster;
-
-        if (isCluster) {
-          const { cluster_id, point_count } = feature.properties as Supercluster.ClusterProperties;
-          const size = getClusterSize(point_count);
-          return (
-            <AdvancedMarker
-              key={`cluster-${cluster_id}`}
-              position={{ lat, lng }}
-              onClick={() => handleClusterClick(cluster_id, lng, lat)}
-              zIndex={100}
-            >
-              <div
-                role="button"
-                aria-label={`${point_count}개 식당이 모인 클러스터, 클릭하면 확대됩니다`}
-                style={{
-                  width: size,
-                  height: size,
-                  borderRadius: "50%",
-                  background: "linear-gradient(135deg, #E8720C 0%, #f59e0b 100%)",
-                  border: "3px solid #fff",
-                  boxShadow: "0 2px 8px rgba(0,0,0,0.25)",
-                  display: "flex",
-                  alignItems: "center",
-                  justifyContent: "center",
-                  color: "#fff",
-                  fontSize: size > 42 ? 15 : 13,
-                  fontWeight: 700,
-                  cursor: "pointer",
-                  transition: "transform 0.2s ease",
-                }}
-              >
-                {point_count}
-              </div>
-            </AdvancedMarker>
-          );
-        }
-
-        // Individual marker
-        const r = (feature.properties as { restaurant: Restaurant }).restaurant;
-        const isSelected = selected?.id === r.id;
-        const isClosed = r.business_status === "CLOSED_PERMANENTLY";
-        const chKey = activeChannel && r.channels?.includes(activeChannel) ? activeChannel : r.channels?.[0];
-        const chColor = chKey ? channelColors[chKey] : CHANNEL_COLORS[0];
-        const c = chColor || CHANNEL_COLORS[0];
-        return (
-          <AdvancedMarker
-            key={r.id}
-            position={{ lat: r.latitude, lng: r.longitude }}
-            onClick={() => handleMarkerClick(r)}
-            zIndex={isSelected ? 1000 : 1}
-          >
-            <div
-              role="button"
-              aria-label={`${r.name}${isClosed ? ' (폐업)' : ''}, 클릭하면 상세 정보가 표시됩니다`}
-              style={{ display: "flex", flexDirection: "column", alignItems: "center", transition: "transform 0.2s ease", transform: isSelected ? "scale(1.15)" : "scale(1)", opacity: isClosed ? 0.5 : 1 }}>
-              <div
-                style={{
-                  padding: "4px 8px",
-                  backgroundColor: isSelected ? "#2563eb" : isClosed ? "#f3f4f6" : c.bg,
-                  color: isSelected ? "#fff" : isClosed ? "#9ca3af" : c.text,
-                  fontSize: 12,
-                  fontWeight: 600,
-                  borderRadius: 6,
-                  border: isSelected ? "2px solid #1d4ed8" : `1.5px solid ${c.border}`,
-                  boxShadow: isSelected
-                    ? "0 2px 8px rgba(37,99,235,0.4)"
-                    : `0 1px 4px ${c.border}40`,
-                  whiteSpace: "nowrap",
-                  maxWidth: 120,
-                  overflow: "hidden",
-                  textOverflow: "ellipsis",
-                  textDecoration: isClosed ? "line-through" : "none",
-                }}
-              >
-                <span className="material-symbols-rounded" style={{ fontSize: 14, width: 14, height: 14, overflow: "hidden", display: "inline-flex", alignItems: "center", justifyContent: "center", marginRight: 3, verticalAlign: "middle", color: "#E8720C" }}>{getCuisineIcon(r.cuisine_type)}</span>
-                {r.name}
-              </div>
-              <div
-                style={{
-                  width: 0,
-                  height: 0,
-                  borderLeft: "6px solid transparent",
-                  borderRight: "6px solid transparent",
-                  borderTop: isSelected ? "6px solid #1d4ed8" : `6px solid ${c.arrow}`,
-                  marginTop: -1,
-                }}
-              />
-            </div>
-          </AdvancedMarker>
-        );
-      })}
-
-      {infoTarget && (
-        <InfoWindow
-          position={{ lat: infoTarget.latitude, lng: infoTarget.longitude }}
-          onCloseClick={() => setInfoTarget(null)}
-        >
-          <div style={{ backgroundColor: "#ffffff", color: "#171717", colorScheme: "light" }} className="max-w-xs p-1">
-            <div className="flex items-center gap-2">
-              <h3 className="font-bold text-base" style={{ color: "#171717" }}><span className="material-symbols-rounded" style={{ fontSize: 18, width: 18, height: 18, overflow: "hidden", display: "inline-flex", alignItems: "center", justifyContent: "center", verticalAlign: "middle", color: "#E8720C", marginRight: 4 }}>{getCuisineIcon(infoTarget.cuisine_type)}</span>{infoTarget.name}</h3>
-              {infoTarget.business_status === "CLOSED_PERMANENTLY" && (
-                <span className="px-1.5 py-0.5 bg-red-100 text-red-700 rounded text-[10px] font-semibold">폐업</span>
-              )}
-              {infoTarget.business_status === "CLOSED_TEMPORARILY" && (
-                <span className="px-1.5 py-0.5 bg-yellow-100 text-yellow-700 rounded text-[10px] font-semibold">임시휴업</span>
-              )}
-            </div>
-            {infoTarget.rating && (
-              <p className="text-xs mt-0.5">
-                <span className="text-yellow-500">★</span> {infoTarget.rating}
-                {infoTarget.rating_count && (
-                  <span className="text-gray-400 ml-1">({infoTarget.rating_count.toLocaleString()})</span>
-                )}
-              </p>
-            )}
-            {infoTarget.cuisine_type && (
-              <p className="text-xs text-gray-500">{infoTarget.cuisine_type}</p>
-            )}
-            {infoTarget.address && (
-              <p className="text-[11px] text-gray-400 mt-1">{infoTarget.address}</p>
-            )}
-            {infoTarget.price_range && (
-              <p className="text-[11px] text-gray-400">{infoTarget.price_range}</p>
-            )}
-            {infoTarget.phone && (
-              <p className="text-[11px] text-gray-400">{infoTarget.phone}</p>
-            )}
-            <button
-              onClick={() => onSelectRestaurant?.(infoTarget)}
-              className="mt-2 text-sm text-blue-600 hover:underline"
-            >
-              상세 보기
-            </button>
-          </div>
-        </InfoWindow>
-      )}
-    </>
-  );
-}
-
-export default function MapView({ restaurants, selected, onSelectRestaurant, onBoundsChanged, flyTo, onMyLocation, activeChannel }: MapViewProps) {
-  const channelColors = useMemo(() => getChannelColorMap(restaurants), [restaurants]);
-  const channelNames = useMemo(() => {
-    const names = Object.keys(channelColors);
-    if (activeChannel) return names.filter((n) => n === activeChannel);
-    return names;
-  }, [channelColors, activeChannel]);
-  const boundsTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const handleCameraChanged = useCallback((ev: { detail: { bounds: { north: number; south: number; east: number; west: number } } }) => {
-    if (!onBoundsChanged) return;
-    if (boundsTimerRef.current) clearTimeout(boundsTimerRef.current);
-    boundsTimerRef.current = setTimeout(() => {
-      const { north, south, east, west } = ev.detail.bounds;
-      onBoundsChanged({ north, south, east, west });
-    }, 150);
-  }, [onBoundsChanged]);
-
-  // #278 — 언마운트 시 디바운스 타이머 정리 (메모리 누수 + unmounted setState 경고 방지)
-  useEffect(() => {
-    return () => {
-      if (boundsTimerRef.current) clearTimeout(boundsTimerRef.current);
-    };
-  }, []);
-
-  return (
-    <APIProvider apiKey={API_KEY}>
-      <Map
-        defaultCenter={SEOUL_CENTER}
-        defaultZoom={13}
-        mapId="tasteby-map"
-        className="h-full w-full"
-        colorScheme="LIGHT"
-        mapTypeControl={false}
-        fullscreenControl={false}
-        onCameraChanged={handleCameraChanged}
-      >
-        <MapContent
-          restaurants={restaurants}
-          selected={selected}
-          onSelectRestaurant={onSelectRestaurant}
-          flyTo={flyTo}
-          activeChannel={activeChannel}
-        />
-      </Map>
-      {onMyLocation && (
-        <button
-          onClick={onMyLocation}
-          aria-label="내 위치로 이동"
-          // #278 — 44×44px 터치 영역 확보 (이전 36px)
-          className="absolute top-2 right-2 w-11 h-11 bg-surface rounded-lg shadow-md flex items-center justify-center text-gray-600 dark:text-gray-300 hover:text-brand-500 dark:hover:text-brand-400 transition-colors z-10 touch-manipulation"
-          title="내 위치"
-        >
-          <Icon name="my_location" size={22} />
-        </button>
-      )}
-      {channelNames.length > 0 && (
-        <div
-          role="region"
-          aria-label="채널 범례"
-          className="absolute bottom-2 left-2 bg-surface/90 backdrop-blur-sm rounded-lg shadow px-2.5 py-1.5 flex flex-wrap gap-x-3 gap-y-1 text-[11px] z-10"
-        >
-          {channelNames.map((ch) => (
-            <div key={ch} className="flex items-center gap-1">
-              <span
-                aria-hidden="true"
-                className="inline-block w-2.5 h-2.5 rounded-full border"
-                style={{ backgroundColor: channelColors[ch].border, borderColor: channelColors[ch].border }}
-              />
-              <span className="text-gray-700 dark:text-gray-300">{ch}</span>
-            </div>
-          ))}
-        </div>
-      )}
-    </APIProvider>
-  );
+function avgLng(rs: MapViewProps["restaurants"]): number | null {
+  if (!rs.length) return null;
+  return rs.reduce((s, r) => s + r.longitude, 0) / rs.length;
 }

frontend/src/components/MapView.types.ts

@@ -0,0 +1,29 @@
+import type { Restaurant } from "@/lib/api";
+
+export interface MapBounds {
+  north: number;
+  south: number;
+  east: number;
+  west: number;
+}
+
+export interface FlyTo {
+  lat: number;
+  lng: number;
+  zoom?: number;
+}
+
+export interface MapViewProps {
+  restaurants: Restaurant[];
+  selected?: Restaurant | null;
+  onSelectRestaurant?: (r: Restaurant) => void;
+  onBoundsChanged?: (bounds: MapBounds) => void;
+  flyTo?: FlyTo | null;
+  onMyLocation?: () => void;
+  activeChannel?: string;
+}
+
+// 좌표가 한국 영토 bbox 안인지 (WGS84).
+export function isKoreaCoord(lat: number, lng: number): boolean {
+  return lat >= 33 && lat <= 38.7 && lng >= 124 && lng <= 132;
+}

frontend/src/components/MyReviewsList.tsx

@@ -41,8 +41,14 @@ export default function MyReviewsList({
         </button>
       </div>
 
-      <div className="flex gap-1 border-b">
+      {/* #343 — WAI-ARIA Tabs 패턴 */}
+      <div role="tablist" aria-label="내 활동" className="flex gap-1 border-b">
         <button
+          role="tab"
+          id="tab-reviews"
+          aria-selected={tab === "reviews"}
+          aria-controls="panel-reviews"
+          tabIndex={tab === "reviews" ? 0 : -1}
           onClick={() => setTab("reviews")}
           className={`px-3 py-1.5 text-sm font-medium border-b-2 transition-colors ${
             tab === "reviews"
@@ -54,6 +60,11 @@ export default function MyReviewsList({
           리뷰 ({reviews.length})
         </button>
         <button
+          role="tab"
+          id="tab-memos"
+          aria-selected={tab === "memos"}
+          aria-controls="panel-memos"
+          tabIndex={tab === "memos" ? 0 : -1}
           onClick={() => setTab("memos")}
           className={`px-3 py-1.5 text-sm font-medium border-b-2 transition-colors ${
             tab === "memos"
@@ -67,7 +78,8 @@ export default function MyReviewsList({
       </div>
 
       {tab === "reviews" ? (
-        reviews.length === 0 ? (
+        <div role="tabpanel" id="panel-reviews" aria-labelledby="tab-reviews">
+        {reviews.length === 0 ? (
           <p className="text-sm text-gray-500 py-8 text-center">
             아직 작성한 리뷰가 없습니다.
           </p>
@@ -100,9 +112,11 @@ export default function MyReviewsList({
               </button>
             ))}
           </div>
-        )
+        )}
+        </div>
       ) : (
-        memos.length === 0 ? (
+        <div role="tabpanel" id="panel-memos" aria-labelledby="tab-memos">
+        {memos.length === 0 ? (
           <p className="text-sm text-gray-500 py-8 text-center">
             아직 작성한 메모가 없습니다.
           </p>
@@ -137,7 +151,8 @@ export default function MyReviewsList({
               </button>
             ))}
           </div>
-        )
+        )}
+        </div>
       )}
     </div>
   );

frontend/src/components/NaverMapView.tsx

@@ -0,0 +1,255 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import Supercluster from "supercluster";
+import type { Restaurant } from "@/lib/api";
+import { getCuisineIcon } from "@/lib/cuisine-icons";
+import Icon from "@/components/Icon";
+import type { MapBounds, MapViewProps } from "@/components/MapView.types";
+
+declare global {
+  interface Window {
+    naver?: { maps: NaverMaps };
+  }
+}
+type NaverMaps = {
+  LatLng: new (lat: number, lng: number) => unknown;
+  Map: new (el: HTMLElement, opts: Record<string, unknown>) => NaverMapInstance;
+  Event: { addListener: (target: unknown, type: string, fn: (...args: unknown[]) => void) => unknown };
+  Size: new (w: number, h: number) => unknown;
+};
+type NaverMapInstance = {
+  setCenter: (latlng: unknown) => void;
+  setZoom: (zoom: number, useEffect?: boolean) => void;
+  getCenter: () => { lat: () => number; lng: () => number };
+  getZoom: () => number;
+  getBounds: () => { getNE: () => { lat: () => number; lng: () => number }; getSW: () => { lat: () => number; lng: () => number } };
+  getProjection: () => { fromCoordToOffset: (latlng: unknown) => { x: number; y: number } };
+  panTo: (latlng: unknown, opts?: Record<string, unknown>) => void;
+  refresh: (noEffect?: boolean) => void;
+  setSize?: (size: unknown) => void;
+};
+
+const NAVER_CLIENT_ID = process.env.NEXT_PUBLIC_NAVER_MAP_CLIENT_ID || "";
+
+function useNaverMaps(): { ready: boolean; error: string | null } {
+  const [ready, setReady] = useState(typeof window !== "undefined" && !!window.naver?.maps);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!NAVER_CLIENT_ID) { setError("NEXT_PUBLIC_NAVER_MAP_CLIENT_ID 미설정"); return; }
+    if (window.naver?.maps) { setReady(true); return; }
+    const existing = document.querySelector<HTMLScriptElement>(`script[data-naver-maps]`);
+    if (existing) {
+      existing.addEventListener("load", () => setReady(true), { once: true });
+      return;
+    }
+    const s = document.createElement("script");
+    s.src = `https://oapi.map.naver.com/openapi/v3/maps.js?ncpKeyId=${NAVER_CLIENT_ID}`;
+    s.async = true;
+    s.dataset.naverMaps = "1";
+    s.onload = () => setReady(true);
+    s.onerror = () => setError("naver maps v3 스크립트 로드 실패");
+    document.head.appendChild(s);
+  }, []);
+
+  return { ready, error };
+}
+
+type RestaurantProps = { restaurant: Restaurant };
+type RestaurantFeature = Supercluster.PointFeature<RestaurantProps>;
+
+function useSupercluster(restaurants: Restaurant[]) {
+  const points: RestaurantFeature[] = useMemo(
+    () => restaurants.map((r) => ({
+      type: "Feature" as const,
+      geometry: { type: "Point" as const, coordinates: [r.longitude, r.latitude] },
+      properties: { restaurant: r },
+    })),
+    [restaurants]
+  );
+  const index = useMemo(() => {
+    const sc = new Supercluster<{ restaurant: Restaurant }>({ radius: 60, maxZoom: 16, minPoints: 2 });
+    sc.load(points);
+    return sc;
+  }, [points]);
+  const getClusters = useCallback((bounds: MapBounds, zoom: number) =>
+    index.getClusters([bounds.west, bounds.south, bounds.east, bounds.north], Math.floor(zoom))
+  , [index]);
+  const getExpansionZoom = useCallback((clusterId: number) => {
+    try { return index.getClusterExpansionZoom(clusterId); } catch { return 17; }
+  }, [index]);
+  return { getClusters, getExpansionZoom };
+}
+
+function getClusterSize(count: number): number {
+  if (count < 10) return 36;
+  if (count < 50) return 42;
+  if (count < 100) return 48;
+  return 54;
+}
+
+export default function NaverMapView({
+  restaurants,
+  selected,
+  onSelectRestaurant,
+  onBoundsChanged,
+  flyTo,
+  onMyLocation,
+}: MapViewProps) {
+  const { ready, error } = useNaverMaps();
+  const divRef = useRef<HTMLDivElement | null>(null);
+  const mapRef = useRef<NaverMapInstance | null>(null);
+  const [bounds, setBounds] = useState<MapBounds | null>(null);
+  const [zoom, setZoom] = useState(13);
+  const [initError, setInitError] = useState<string | null>(null);
+  const { getClusters, getExpansionZoom } = useSupercluster(restaurants);
+
+  // 지도 1회 생성 — divRef 항상 마운트되므로 ready 시점에 안정적으로 잡힘
+  useEffect(() => {
+    if (!ready || !divRef.current || mapRef.current) return;
+    try {
+      const n = window.naver!.maps;
+      const initLat = flyTo?.lat ?? selected?.latitude ?? 37.5665;
+      const initLng = flyTo?.lng ?? selected?.longitude ?? 126.978;
+      const initZoom = flyTo?.zoom ?? 13;
+      const m = new n.Map(divRef.current, {
+        center: new n.LatLng(initLat, initLng),
+        zoom: initZoom,
+        logoControl: false,
+        mapDataControl: false,
+        scaleControl: false,
+        zoomControl: false,
+      });
+      mapRef.current = m;
+
+      // 컨테이너 크기 변경(예: flex layout 안에서 첫 마운트 시 0×0 → 실제 크기) → refresh
+      const ro = new ResizeObserver(() => {
+        try { m.refresh(true); } catch { /* noop */ }
+      });
+      ro.observe(divRef.current);
+
+      const sync = () => {
+        try {
+          const b = m.getBounds();
+          const ne = b.getNE(), sw = b.getSW();
+          const nb: MapBounds = { north: ne.lat(), south: sw.lat(), east: ne.lng(), west: sw.lng() };
+          setBounds(nb);
+          setZoom(m.getZoom());
+          onBoundsChanged?.(nb);
+        } catch (e) {
+          console.warn("[NaverMap] sync failed", e);
+        }
+      };
+      // 컨테이너 크기가 정해진 다음 sync (rAF로 다음 프레임)
+      requestAnimationFrame(() => {
+        try { m.refresh(true); } catch { /* noop */ }
+        sync();
+      });
+      n.Event.addListener(m, "bounds_changed", sync);
+      n.Event.addListener(m, "zoom_changed", sync);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.error("[NaverMap] init failed", e);
+      setInitError(msg);
+    }
+  }, [ready, flyTo, selected, onBoundsChanged]);
+
+  // flyTo 변경 반영
+  useEffect(() => {
+    const m = mapRef.current;
+    if (!m || !flyTo || !window.naver?.maps) return;
+    m.panTo(new window.naver.maps.LatLng(flyTo.lat, flyTo.lng));
+    if (flyTo.zoom) m.setZoom(flyTo.zoom, true);
+  }, [flyTo]);
+
+  const clusters = useMemo(() => {
+    if (!bounds) return [];
+    return getClusters(bounds, zoom);
+  }, [bounds, zoom, getClusters]);
+
+  const toScreen = useCallback((lat: number, lng: number) => {
+    const m = mapRef.current;
+    if (!m || !window.naver?.maps) return null;
+    try {
+      return m.getProjection().fromCoordToOffset(new window.naver.maps.LatLng(lat, lng));
+    } catch {
+      return null;
+    }
+  }, []);
+
+  return (
+    <div className="relative w-full h-full">
+      {/* 지도 컨테이너 — 항상 마운트, 명시적 크기 보장 */}
+      <div
+        ref={divRef}
+        className="absolute inset-0"
+        style={{ width: "100%", height: "100%", backgroundColor: "#e5e7eb" }}
+      />
+
+      {/* 로딩/에러 overlay */}
+      {(error || initError) && (
+        <div className="absolute inset-0 flex items-center justify-center text-xs text-red-600 bg-white/80 pointer-events-none">
+          {error ?? initError} — 새로고침 또는 GoogleMap로 fallback
+        </div>
+      )}
+      {!ready && !error && (
+        <div className="absolute inset-0 flex items-center justify-center text-xs text-gray-500 bg-white/80 pointer-events-none">
+          네이버 지도 로딩 중…
+        </div>
+      )}
+
+      {/* 마커 overlay */}
+      {clusters.map((feature) => {
+        const [lng, lat] = feature.geometry.coordinates;
+        const pt = toScreen(lat, lng);
+        if (!pt) return null;
+        const isCluster = feature.properties && "cluster" in feature.properties && feature.properties.cluster;
+        if (isCluster) {
+          const { cluster_id, point_count } = feature.properties as Supercluster.ClusterProperties;
+          const size = getClusterSize(point_count);
+          return (
+            <button
+              key={`c-${cluster_id}`}
+              onClick={() => {
+                const z = Math.min(getExpansionZoom(cluster_id), 18);
+                const m = mapRef.current;
+                if (!m || !window.naver?.maps) return;
+                m.panTo(new window.naver.maps.LatLng(lat, lng));
+                m.setZoom(z, true);
+              }}
+              className="absolute -translate-x-1/2 -translate-y-1/2 rounded-full bg-brand-500/90 text-white font-semibold shadow-lg ring-2 ring-white"
+              style={{ left: pt.x, top: pt.y, width: size, height: size, fontSize: size > 44 ? 14 : 12 }}
+            >
+              {point_count}
+            </button>
+          );
+        }
+        const r = (feature.properties as RestaurantProps).restaurant;
+        const cuisineIcon = getCuisineIcon(r.cuisine_type);
+        const isSel = selected?.id === r.id;
+        return (
+          <button
+            key={r.id}
+            onClick={() => onSelectRestaurant?.(r)}
+            className={`absolute -translate-x-1/2 -translate-y-full rounded-full shadow-md ring-2 ring-white transition-transform ${isSel ? "scale-125 z-10" : ""}`}
+            style={{ left: pt.x, top: pt.y, width: 32, height: 32, background: "#f59e0b", color: "#78350f" }}
+            title={r.name}
+          >
+            <Icon name={cuisineIcon} size={18} />
+          </button>
+        );
+      })}
+
+      {onMyLocation && (
+        <button
+          onClick={onMyLocation}
+          aria-label="내 위치"
+          className="absolute right-3 bottom-3 size-11 rounded-full bg-white shadow-lg flex items-center justify-center"
+        >
+          <Icon name="my-location" size={22} />
+        </button>
+      )}
+    </div>
+  );
+}

frontend/src/components/RestaurantDetail.tsx

@@ -24,6 +24,15 @@ function buildSearchQuery(r: Restaurant): string {
   return r.name;
 }
 
+// 좌표 기반 한국 판정 (WGS84). KR bbox 대략 33~38.7°N, 124~132°E.
+// 좌표 없으면 region 첫 토큰으로 fallback (구 데이터 호환).
+function isKoreaRestaurant(r: Restaurant): boolean {
+  if (r.latitude != null && r.longitude != null) {
+    return r.latitude >= 33 && r.latitude <= 38.7 && r.longitude >= 124 && r.longitude <= 132;
+  }
+  return !r.region || r.region.split("|")[0] === "한국";
+}
+
 export default function RestaurantDetail({
   restaurant,
   onClose,
@@ -138,6 +147,26 @@ export default function RestaurantDetail({
         )}
         {restaurant.google_place_id && (
           <p className="flex gap-3">
+            {isKoreaRestaurant(restaurant) ? (
+              <>
+                <a
+                  href={`https://map.naver.com/p/search/${encodeURIComponent(buildSearchQuery(restaurant))}`}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-green-600 dark:text-green-400 hover:underline text-xs"
+                >
+                  네이버 지도에서 보기
+                </a>
+                <a
+                  href={`https://www.google.com/maps/search/?api=1&query=${encodeURIComponent(buildSearchQuery(restaurant))}`}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-gray-500 dark:text-gray-400 hover:underline text-xs"
+                >
+                  Google Maps
+                </a>
+              </>
+            ) : (
               <a
                 href={`https://www.google.com/maps/search/?api=1&query=${encodeURIComponent(buildSearchQuery(restaurant))}`}
                 target="_blank"
@@ -146,15 +175,6 @@ export default function RestaurantDetail({
               >
                 Google Maps에서 보기
               </a>
-            {(!restaurant.region || restaurant.region.split("|")[0] === "한국") && (
-              <a
-                href={`https://map.naver.com/v5/search/${encodeURIComponent(restaurant.name)}`}
-                target="_blank"
-                rel="noopener noreferrer"
-                className="text-green-600 dark:text-green-400 hover:underline text-xs"
-              >
-                네이버 지도에서 보기
-              </a>
             )}
           </p>
         )}

frontend/src/components/ReviewSection.tsx

@@ -257,6 +257,9 @@ export default function ReviewSection({ restaurantId }: ReviewSectionProps) {
                     <>
                       <div className="flex items-center gap-2 mb-1">
                         {review.user_avatar_url && (
+                          // eslint-disable-next-line @next/next/no-img-element
+                          // #343 — Google avatar URL은 remotePatterns에 추가됨.
+                          // next/image 전환은 SSR/lazy 효과 미미한 5x5 아바타라 후속에서 일괄 적용.
                           <img
                             src={review.user_avatar_url}
                             alt=""

k8s/secrets.yaml.template

@@ -9,9 +9,12 @@ type: Opaque
 stringData:
   ORACLE_USER: "<oracle-username>"
   ORACLE_PASSWORD: "<oracle-password>"
-  ORACLE_DSN: "<tns-alias>_high?TNS_ADMIN=/etc/oracle/wallet"
+  ORACLE_DSN: "<tns-alias>_medium?TNS_ADMIN=/etc/oracle/wallet"
   JWT_SECRET: "<jwt-secret>"
   OCI_COMPARTMENT_ID: "<oci-compartment-id>"
   OCI_CHAT_MODEL_ID: "<oci-chat-model-id>"
   GOOGLE_MAPS_API_KEY: "<google-maps-api-key>"
   YOUTUBE_DATA_API_KEY: "<youtube-data-api-key>"
+  # #357 — Naver Search API (선택). 미설정 시 DDG 폴백.
+  NAVER_CLIENT_ID: "<naver-client-id>"
+  NAVER_CLIENT_SECRET: "<naver-client-secret>"