From cf37e496d444cee278adab0aa32e497315533076 Mon Sep 17 00:00:00 2001
From: joungmin <joungmin@joungmins-Mac-mini.local>
Date: Tue, 16 Jun 2026 10:56:51 +0900
Subject: [PATCH] =?UTF-8?q?docs(design):=20#363=20=EC=8B=A4=20=EC=9A=B4?=
 =?UTF-8?q?=EC=98=81=20fix=20=EA=B8=B0=EB=A1=9D=20(1~2=EB=8B=A8=EA=B3=84?=
 =?UTF-8?q?=20+=20v0.1.57=20=EC=95=88=EC=A0=95=ED=99=94)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 배포 흐름 v0.1.51~v0.1.57 정리
- 운영 진단 확인사항 (NCLOUD 도메인 형식, Search/Maps 별개 시스템)
- NaverMapView 안정화 핵심 결정사항 (divRef 항상 마운트, ResizeObserver, try/catch)
- 후속 분리 항목 명시

Refs: #363

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

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 docs/design/363-map-sdk-branch/README.md | 28 ++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docs/design/363-map-sdk-branch/README.md b/docs/design/363-map-sdk-branch/README.md
index 17bd618..d8a4063 100644
--- a/docs/design/363-map-sdk-branch/README.md
+++ b/docs/design/363-map-sdk-branch/README.md
@@ -82,3 +82,31 @@ MapView (dispatcher)
 - 한 화면 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에 도입.