release: 4차 배포 — AI 경로추천 추가 (MSG-488~490)

[gyuhochoime]

3차 배포(#103, d60ff3e) 이후 develop에 쌓인 3개 커밋(AI 경로추천 웨이브 MSG-488~490)을 배포한다. main 트리는 develop 8d3ff99(MSG-474)와 동일했으므로 그 뒤 전부가 이번 범위다. 이 브랜치의 트리는 origin/develop 0b2c355와 바이트 동일(git diff 0줄).

웹 (fillmap.kr — 이번 배포로 실제 반영되는 부분)

• MSG-488 AI 경로추천 페이지 신설 /ai-route — 사이드 레일 5번째 항목(홈 · AI 경로추천 · 업로드 · 도감 · 프로필), 자연어 문장 → POST /api/routes/recommend → 좌측 패널 카드(순번·종류 태그·표시명·추천 이유) + 지도 오버레이(번호 마커·격자 강조·연결선), 결과 부족 배너, 에러 5종 안내. 로그인 전용(익명 401). ui-web Skeleton 신설·RetryNotice 승격 (MSG-488 feat: [웹] AI 경로추천 페이지 — 자연어 요청·결과 카드·지도 오버레이 #104)
• MSG-489 자동 동작 — 문장이 화면 밖 지역을 말하면(mentionedArea) 확인 없이 그 중심으로 이동 + 1km 축척 고정 + 토스트 + 2차 자동 재요청(서버 10초 rate limit이 예외가 아니라 잔여 대기 후 발사), 출발지 자동 판정(현위치가 뷰포트 안일 때만 origin 전송·"현재 위치에서 출발" 표시) (MSG-489 feat: [웹] AI 경로추천 — 지역 자동 이동·1km 축척 고정·2차 자동 재요청·출발지 자동 판정 #105)
• MSG-490 실보행 경로 — 직선을 먼저 그린 채 POST /api/routes/walk-paths로 세그먼트별 실경로 좌표열·실거리 점진 교체, 실패 세그먼트는 직선·직선 거리 유지의 조용한 폴백 (MSG-490 feat: [웹] AI 경로추천 실보행 경로 — walk-paths 점진 렌더·세그먼트 폴백·실거리 표기 #106)

apps/web + packages: 83 files, +5274/−73

모바일 (apps/mobile — 스토어 배포와 무관, 코드만 동반)

• OpenAPI UserProfileResponseDto.role 필수화에 따른 테스트 픽스처 2파일 +2줄. 화면·모델 변경 없음

BE 선행 조건 (전부 배포 확인됨 — 각 PR 실측)

• POST /api/routes/recommend(BE MSG-457·458·468) — 488·489 브라우저 검증이 실 API 응답으로 수행됨. 익명 401/2403 실측 → 로그인 전용 게이트
• POST /api/routes/walk-paths(BE MSG-483) — 490 실동작 S1~S8 실 API 통과, 부분 실패(resolved:false)는 200으로 옴
• 2차 자동 재요청은 10초 rate limit 예외가 아님(실측 429/14429) → FE가 대기 후 발사. BE 정책 변경 없이 동작
• 이번 범위의 openapi/api-docs.json 변경은 1줄(walk-paths 추가·role 등 필드 추가분 스냅샷 갱신)이며 생성물 드리프트 0

히스토리 — 이 PR은 "Create a merge commit" 으로 머지

#103도 결국 squash로 들어가(d60ff3e의 부모가 42df186 하나) merge-base가 여전히 f55d7b8(MSG-105)이라, develop→main 직접 PR은 가짜 충돌이 잡힌다(양쪽 트리는 동일). 이 브랜치의 커밋 ad3f681은 main(d60ff3e)과 develop(0b2c355)을 둘 다 부모로 기록한 머지 커밋이고 트리는 develop과 동일하다. merge commit으로 머지해야 main 이력이 develop과 연결돼 다음 릴리스부터 develop→main 직접 PR이 가능해진다. squash면 #96·#103과 같은 상태가 반복된다.

배포 확인

머지 → Actions CD (web) 실행 확인 → https://fillmap.kr 로그인 → 사이드 레일 "AI 경로추천" → 문장 입력("서면에서 밥 먹고 카페 들르기") → 카드·지도 경로 표시 확인.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PStNrbdpwCLXUSGvpK8JZs

[claude]

Claude finished @gyuhochoime's task in 5m 41s —— View job

---

코드 리뷰 완료

작업 목록

• 컨텍스트 파악 (PR 정보, CLAUDE.md, 변경 파일 목록)
• git diff origin/main...HEAD로 변경분 확인
• AI 경로추천 기능 로직 레이어 리뷰 (model/api — ai-route-store, route-request, route-legs, route-error, route-mentioned-area, route-origin, route-overlay, route-point-view)
• 페이지/UI 레이어 리뷰 (AiRoutePage, use-ai-route-auto-move, use-ai-route-overlay-publish 등)
• 기존 코드 수정분 리뷰 (geolocation, map-shell, side-rail-nav, use-occupied-grids-query)
• ui-web 신규 컴포넌트 리뷰 (Skeleton, RetryNotice)
• 인라인 코멘트 게시
• 최종 요약 코멘트 게시 (gh pr comment)

전체 요약은 별도 코멘트로 게시했습니다: #107 (comment)

한 줄 요약: RN 경계·비동기 경합 방어·에러 폴백 처리가 전반적으로 매우 꼼꼼합니다. 🟡 1건(RouteResultList.tsx — 카드 목록에 order 정렬 누락, 인라인 코멘트에 수정 예시 포함) 외에는 버그·타입 안정성·성능·보안 관점에서 지적할 사항을 찾지 못했습니다.

[github-actions]

React Doctor found no new issues. 🎉

_{Reviewed by React Doctor for commit ad3f681.}

[claude]

코드 리뷰 요약 — PR #107 (AI 경로추천, MSG-488~490)

95개 변경 파일 중 신규/수정 로직 전체를 diff만이 아니라 주변 코드까지 Read로 확인했습니다 (모델 레이어 8개 파일, API 훅 2개, 페이지·UI 컴포넌트 15개, 인프라 수정분 8개, ui-web 신규 컴포넌트 2개).

잘한 점

• RN 경계·순수 함수 분리가 일관됩니다. route-request.ts·route-origin.ts·route-mentioned-area.ts·route-legs.ts·route-overlay.ts 전부 지도 SDK·document·navigator를 모르는 순수 함수이고, 플랫폼 접근은 use-ai-route-auto-move.ts 같은 뷰-레이어 훅에만 있습니다.
• 비동기 경합·무한 루프 방어가 촘촘합니다. 2차 자동 재요청의 서버 10초 rate limit 대응(secondaryDelayMs), 정착 대기 상한이 가시 상태에서만 소모되는 처리(advanceSettleDeadline), StrictMode 이펙트 2회 실행 방어(스토어 플래그로 재발사 차단) 등이 전부 근거(실측 로그·리뷰 코멘트 번호)와 함께 문서화돼 있고 테스트(use-ai-route-auto-move.test.tsx 582줄)로 커버됩니다.
• 에러/폴백 처리가 조용하고 일관적입니다. walk-paths 실패·부분 실패는 에러 UI 없이 직선 근사로 조용히 폴백하고(route-legs.ts·route-overlay.ts), 서버 문자열을 그대로 렌더하지 않고 FE 고정 문구를 쓰는 정책(route-error.ts)이 지켜졌습니다.
• 문서-코드 정합성이 높습니다. docs/spec/MSG-488~490.md에 남긴 트레이드오프(예: origin 구간 walk-paths 미배선 결정)가 실제 코드의 "확장점" 주석과 정확히 일치합니다.

지적 사항

🟡 apps/web/src/pages/ai-route/ui/RouteResultList.tsx:34 — 카드 목록이 points를 order 정렬 없이 그대로 렌더합니다. 같은 points를 쓰는 route-legs.ts·route-overlay.ts는 둘 다 [...points].sort((a, b) => a.order - b.order)로 방어적으로 정렬하는데 카드 렌더링만 빠져 있어, 서버 응답 배열이 order 오름차순이 아닌 경우(타입 주석은 보장하지 않음) 카드 순서·도보 커넥터 위치가 실제 방문 순서와 어긋날 수 있습니다. 현재 테스트 픽스처는 항상 정렬된 배열만 써서 이 경로가 커버되지 않습니다. 서버가 항상 정렬해서 준다는 보장이 있다면 낮은 우선순위입니다 — 추측 포함, 인라인 코멘트에 수정 예시를 남겼습니다.

그 외에는 버그·타입 안정성·성능·보안 관점에서 문제가 될 만한 지점을 찾지 못했습니다. 메모이제이션(useMemo로 오버레이 clear→재게시 깜빡임 방지), mutation 캐시 무효화 생략에 대한 명시적 판단(읽기형 POST) 등도 근거가 타당합니다.

View job run · branch: release/4th-deploy

[claude]

🟡 권장 — points.map()이 order 정렬 없이 서버가 준 배열 순서 그대로 카드를 렌더합니다.

같은 points를 소비하는 route-legs.ts:111와 route-overlay.ts:90는 둘 다 [...points].sort((a, b) => a.order - b.order)로 방어적으로 정렬한 뒤 파생하는데, 카드 목록만 이 정렬이 빠져 있습니다. RoutePointDto.order의 타입 주석은 "방문 순서(1부터 연속)"일 뿐 배열 자체가 그 순서로 온다는 계약은 아니라서, 서버 응답 배열이 order 오름차순이 아니면:

• 카드가 방문 순서와 다르게 표시되고
• index > 0 && leg 커넥터가 leg.find(item => item.toOrder === point.order)로 리그를 찾긴 하지만, 화면상 "바로 위 카드"가 실제 leg.fromOrder의 지점이 아닐 수 있어 커넥터 위치와 의미가 어긋납니다.

현재 테스트 픽스처(test/route-points.ts)가 항상 정렬된 배열만 만들어서 이 경로는 테스트로 잡히지 않습니다. 서버가 실제로 항상 정렬해 준다는 보장이 있다면 무시해도 되지만(추측), 방어적으로는 다음처럼 맞추는 게 다른 두 파생 함수와 일관됩니다.

const orderedPoints = useMemo(
  () => [...points].sort((a, b) => a.order - b.order),
  [points],
);
// ...
{orderedPoints.map((point, index) => { ... })}