문제: 프론트 docs/는 지금 동작을 설명하는 문서와 쓴 때의 기록이 한 폴더에 섞여 있다. docs/architecture/에는 현재 계약 10개와 목표 설계 14개, 결정 기록 VD 23개가 같이 있고, 설계서·계획서는 플러그인 이름 폴더(docs/superpowers/)에 있다. 문서 체계 규칙(design-docs conventions/docs-system.md v1, 2026-11-07 소유자 결정)은 수명으로 나누고 폴더 이름을 백엔드와 같게 하라고 정한다. 고른 방법: 내용 변경 없이 git mv만 담는다. git이 이름 바뀜을 알아보고 리뷰어가 이동과 내용 변경을 따로 볼 수 있게 하려는 것이다. 참조 수정과 머리 블록은 다음 커밋들이 한다. - docs/superpowers/specs → docs/design/, plans → docs/history/plans/ - docs/architecture/ 목표 설계 13개와 styling·testing의 목표 설계 2개 → docs/design/<작성일>-<이름>-design.md (2026-07-30 결정 정본은 이름 그대로) - docs/architecture/decisions/VD-* → docs/adr/ (번호 유지) 위험: 이 커밋만으로는 옮긴 문서를 가리키는 링크와 경로가 깨진다. 다음 커밋이 고친다. 게이트가 읽는 파일(review-ledger.json, review-evidence.md, adapter-remediation-ledger.md, INVENTORY.md)은 옮기지 않았다. docs/history/는 복사한 프로젝트가 지워도 된다는 약속 (tests/unit/deletable-history-documents.test.ts)이 있어서 코드가 읽는 파일을 둘 수 없다. SPEC.md는 공통 완료 기준을 매뉴얼로 옮긴 뒤 따로 옮긴다. 검증: git status가 이름 바뀜(R) 66개만 보인다.
3.0 KiB
3.0 KiB
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은 중앙에서 조립할 필요가 있다.
결정
- 고정된 React Router
7.18.1의createBrowserRouter와RouterProvider를 사용하는 Data Mode를 기본값으로 채택한다. - 직렬화 가능한 route contract와 React component/codec runtime map을 분리한다.
- 모든 executable route object와 navigation은 registry에서 생성한다. JSX에서 route 목록을 다시 열거하지 않는다.
- params/search는 route 경계의 Zod codec으로 parse하고 같은 codec으로 canonical URL을 생성한다.
- loader/action은 같은 서버 데이터를 직접 다시 요청하지 않는다. 필요하면 application input 또는 query adapter 한 경로를 호출한다.
- 서버 상태, retry, cache와 mutation lifecycle은 application input과 TanStack Query가 계속 소유한다.
- lazy chunk rejection만 release recovery input으로 보내며 일반 render error는 route/feature boundary가 소유한다.
- 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 범위에 포함하지 않는다.