Files
clean-architecture-frontend…/docs/adr/VD-03-react-router-data-mode.md
DongHyeonka 75fad73a7d docs(records): 기록·설계서·결정 기록 67개에 한국어 머리 블록을 단다
문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금
정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture
목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어
값을 쓴다.

고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은
한 글자도 고치지 않는다. 상태는 기계 변환이다.
- 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면
  확인 안 함 (채택 4, 확인 안 함 21)
- 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는
  같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5,
  확인 안 함 14. 이미 블록이 있던 5개는 그대로)
- 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에
  있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터
  한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다.
- 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일.

위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서
고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다.
보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는
문서나 코드 경로만 쓴다.

검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가
같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
2026-11-08 17:25:41 +09:00

3.6 KiB

결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-07-26
  • 요약: 라우터를 React Router Data Mode로 바꾸고 실행 route는 registry에서 만들며 서버 상태는 계속 application input과 TanStack Query가 소유한다는 결정이다.
  • 현재 정본: src/presentation/routes/, src/contracts/routes.ts

VD-03: React Router Data Mode와 서버 상태 소유권

  • 상태: Accepted
  • 결정일: 2026-07-26
  • 적용 브랜치: feature-frontend-routing-release-recovery-runtime

배경

기존 라우터는 BrowserRouter와 수동 JSX route 목록을 사용했다. 직렬화 가능한 route registry에 params/search schema, loading/error surface, access, title, navigation과 chunk ID가 있었지만 실행 route tree와 독립적이어서 선언과 행동이 어긋날 수 있었다.

이 저장소는 client-only SPA이며 서버 상태는 application input과 TanStack Query가 소유한다. Framework Mode의 loader/action 중심 데이터 소유권이나 SSR을 도입하지 않으면서 route object, 오류 경계와 navigation lifecycle은 중앙에서 조립할 필요가 있다.

결정

  1. 고정된 React Router 7.18.1의 createBrowserRouter와 RouterProvider를 사용하는 Data Mode를 기본값으로 채택한다.
  2. 직렬화 가능한 route contract와 React component/codec runtime map을 분리한다.
  3. 모든 executable route object와 navigation은 registry에서 생성한다. JSX에서 route 목록을 다시 열거하지 않는다.
  4. params/search는 route 경계의 Zod codec으로 parse하고 같은 codec으로 canonical URL을 생성한다.
  5. loader/action은 같은 서버 데이터를 직접 다시 요청하지 않는다. 필요하면 application input 또는 query adapter 한 경로를 호출한다.
  6. 서버 상태, retry, cache와 mutation lifecycle은 application input과 TanStack Query가 계속 소유한다.
  7. lazy chunk rejection만 release recovery input으로 보내며 일반 render error는 route/feature boundary가 소유한다.
  8. Framework Mode, SSR, static generation과 router version upgrade는 별도 dependency/architecture 브랜치에서 결정한다.

검증

  • route contract/runtime map의 누락과 orphan은 TypeScript negative fixture와 registry gate가 모두 거절한다.
  • duplicate ID/path, unknown codec/surface/chunk와 참조 불일치를 negative registry fixture로 검증한다.
  • params/search parse/build round-trip, canonical redirect, 최대 redirect hop, access rejection, title/focus와 boundary reset을 unit/component test로 검증한다.
  • Vite dynamic entry와 release route chunk map, runtime config JSON Schema를 build/release 검증기가 확인한다.
  • chunk failure는 no-store manifest refetch 후 build/release 쌍마다 한 번만 reload하며 offline, malformed manifest와 storage 실패는 fail-closed한다.

결과와 rollback

Data Router는 navigation lifecycle의 조립 경계이며 서버 데이터 계층이 아니다. 이 구분을 지키면 React Router를 교체해도 application input과 output port는 유지된다.

rollback은 RP-04 merge를 되돌려 이전 수동 router와 generic route failure surface로 복구한다. URL shape와 application API는 유지하고, 이미 배포된 asset cache의 purge는 저장소 rollback 범위에 포함하지 않는다.