문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금 정본이 어디인지 알 길이 없다. 설계서·계획서 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건.
68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
|
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
|
|
|
- 상태: 채택
|
|
- 작성일: 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 범위에 포함하지 않는다.
|