From ee81c448f024e1abfc3d60c1a27e93e229888165 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 01:17:32 +0900 Subject: [PATCH] =?UTF-8?q?fix(reference):=20=EC=83=98=ED=94=8C=20?= =?UTF-8?q?=EB=A7=81=ED=81=AC=EB=A5=BC=20route=20ID=EB=A1=9C=20=EB=A7=8C?= =?UTF-8?q?=EB=93=A4=EA=B3=A0=20route=20=EC=9E=85=EB=A0=A5=20cast=EB=A5=BC?= =?UTF-8?q?=20=EC=97=86=EC=95=A4=EB=8B=A4=20(1101/16-04)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 경로 정본은 계약의 `routes[*].path`인데, 샘플 페이지가 같은 경로를 문자열로 8곳에 다시 적는다(목록 2, 상세 1, 폼 3, 상태 1, 실패 행동 1). route 입력은 `routeInput.search as ReferenceListFilters`와 `String(route.params.resourceId)`로 cast한다. 계약에서 경로만 바꾸면 tsc는 통과하고 링크는 NOT_FOUND로 간다. 문서(routing-pages-and-patterns 4.2절, 10절 4단계)는 codec 기반 builder와 cast 금지를 권하는데, 샘플이 반대 패턴을 보여 주고 복사되는 기능이 그 습관을 가져간다. 고른 방법: 이미 있는 URL builder를 쓴다. - `buildRouteUrl(routeId, input, featureCodecs)`(`src/presentation/routes/ route-codecs.ts`)가 route ID로 계약 `path`를 찾고, 라우터가 parse에 쓰는 같은 codec으로 직렬화한다. canonical redirect도 이 함수를 쓴다. `src/platform`에는 URL builder가 없다. 그래서 플랫폼에 새 공개 헬퍼를 더하지 않았다. - 기능 쪽 helper는 `presentation/reference-routes.ts`에 둔다. - `referenceRouteUrl(routeId, input)`: `buildRouteUrl`에 이 기능의 codec을 넘기는 한 줄 래퍼다. routeId는 이 기능 계약의 키로 좁힌다. - `useReferenceListFilters()`, `useReferenceResourceId()`: 라우터가 이미 통과시킨 route 입력을 같은 codec으로 다시 parse해서 codec의 출력 타입을 얻는다. cast가 없다. 목록 필터는 `useMemo`로 묶어 route 입력이 그대로면 같은 객체를 준다. - `REFERENCE_FEATURE_ROUTE_CODECS`를 `reference-feature-runtime.ts`에서 새 `presentation/reference-route-codecs.ts`로 옮겼다. - runtime 파일이 페이지를 lazy import하므로, 페이지 쪽이 runtime 파일에서 codec을 가져오면 순환 의존이 된다. - codec 표를 helper 파일에 같이 두지 않은 이유: 그러면 `context-routes.ts`가 router의 builder·hook까지 끌어와 초기 JS가 585 B 늘었다(204,809 B로 예산 204,800 B 초과). 분리하면 475 B다. - `context-routes.ts`와 `reference-contract.test.ts`는 새 위치에서 가져온다. - 페이지 8곳을 route ID 호출로 바꿨다. 기능 presentation에 `"/examples/` 문자열이 0건, route 입력 cast가 0건이다. 남은 `"/examples/` 4건은 계약의 `path`(정본)다. - 기능 README에 helper 위치와 쓰는 법을 적었다. 버린 대안: - 리뷰 (b)처럼 기능 안에 경로 치환·직렬화를 새로 쓰는 헬퍼: 라우터와 같은 일을 두 번 구현한다. 플랫폼 builder가 이미 route ID와 기능 codec을 받는다. - 리뷰 (c)처럼 `buildRouteUrl`의 input 타입을 route ID별로 좁히기: 플랫폼은 기능 codec 타입을 모른다(15-01 이후 codec은 지연 적재). 라우터 API 변경이라 이 발견 범위를 넘는다. - 플랫폼 `useRouteInput`을 제네릭으로 바꿔 타입 단언하기: 런타임 검사 없는 단언이라 cast를 다른 이름으로 옮길 뿐이다. 위험·한계: - 목록 링크가 이제 정식 URL(`/examples/reference-resources?limit=20`)을 가리킨다. 전에는 `?limit` 없는 주소로 갔다가 라우터가 같은 URL로 replace했다. 도착 URL과 history 항목 수는 같다. 폼의 "목록을 새로 불러와 확인" 링크 href 기대값을 이 값으로 바꿨다. - `buildRouteUrl`은 codec이 거절하는 입력에 예외를 던진다. 백엔드가 공백만 있는 id를 주면(DTO는 `min(1)`, route codec은 trim 후 `min(1)`) 목록 렌더가 기능 오류 경계로 간다. 전에는 링크가 잘못된 주소 화면으로 갔다. DTO와 route codec의 id 규칙 차이는 이 변경 전부터 있다. - route 입력을 한 번 더 parse한다. 값이 작아 비용은 무시할 만하다. - 초기 JS gzip이 204,224 B에서 204,699 B로 475 B 늘었다(예산 204,800 B, 여유 576 B → 101 B). 새 코드가 초기 청크에 들어간 것이 아니다. `route-codecs.ts`는 원래 초기 청크에 있었다. 페이지가 이 모듈을 import하자 rolldown이 `boot` 청크에 있던 것을 공유 청크(`route-input`)로 옮기고, `route-input`과 `server-state-scope-provider`를 두 청크로 나눴다. 늘어난 양은 청크 분리 비용이다. 예산 값은 바꾸지 않았다. - 페이지 테스트의 진입 URL 문자열은 그대로 뒀다. 테스트가 경로를 적는 것은 이 발견의 완료 기준 밖이다. - 상태 페이지의 `(state as ReferenceSupportState)`는 history state 처리라 route 입력 cast가 아니다. 그대로 뒀다. 검증: - RED(수정 전): 새 `tests/features/reference-feature/ reference-route-links.test.tsx`는 계약의 네 경로를 모두 옮긴(vi.mock) 상태로 목록→상세→목록→폼→목록, 목록→지원 페이지→목록을 걷는다. 2개 모두 실패했다. 상세 링크가 `href=".../items/reference-1"`(기대 `.../entries/reference-1`), 지원 페이지 대신 NOT_FOUND가 나왔다. - GREEN(수정 후): 같은 테스트 2개 통과. `tests/features/reference-feature` 18 files 89 tests 통과(href 기대값 1곳 변경 뒤). - 회귀: tests/features, tests/component, tests/architecture, tests/scale, 관련 unit 3개, generator 테스트 81 files 464 tests 통과. 첫 실행에서는 부하(평균 23~35)로 타임아웃 2건(app-build-input, global-local-independence)이 났고, 단독 재실행과 최종 재실행에서 통과했다. - 초기 JS gzip(`scripts/build-frontend.ts` 후 check-bundle과 같은 분류로 측정): 수정 전 204,224 B, 수정 후 204,699 B. - `tsc` app·test·node 통과. 바꾼 파일 `eslint --max-warnings=0` 통과. - `check-architecture.ts`(pnpm 대신 exec 전용 shim): 381 modules, 순환·위반 없음, rc=0. `verify-documentation-readiness` PASS_SCOPED, `check-i18n` PASS. - 페이지 테스트 harness(`renderReference`, `inputWith`)는 새 테스트와 함께 쓰도록 `reference-page-harness.tsx`로 옮겼다. 내용은 그대로다. Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-04 --- src/features/reference-feature/README.md | 9 ++ .../reference-feature/context-routes.ts | 6 +- .../presentation/reference-feature-runtime.ts | 18 +-- .../reference-resource-detail-page.tsx | 10 +- .../reference-resource-form-page.tsx | 7 +- .../presentation/reference-resource-page.tsx | 7 +- .../reference-resource-status-page.tsx | 3 +- .../presentation/reference-route-codecs.ts | 17 +++ .../presentation/reference-routes.ts | 37 ++++++ .../use-reference-failure-action.ts | 5 +- .../presentation/use-reference-feature.ts | 5 +- .../reference-contract.test.ts | 2 +- .../reference-page-harness.tsx | 109 +++++++++++++++++ .../reference-feature/reference-page.test.tsx | 111 +----------------- .../reference-route-links.test.tsx | 108 +++++++++++++++++ 15 files changed, 312 insertions(+), 142 deletions(-) create mode 100644 src/features/reference-feature/presentation/reference-route-codecs.ts create mode 100644 src/features/reference-feature/presentation/reference-routes.ts create mode 100644 tests/features/reference-feature/reference-page-harness.tsx create mode 100644 tests/features/reference-feature/reference-route-links.test.tsx diff --git a/src/features/reference-feature/README.md b/src/features/reference-feature/README.md index 3fc8d7b0..392fffea 100644 --- a/src/features/reference-feature/README.md +++ b/src/features/reference-feature/README.md @@ -42,6 +42,15 @@ route codec과 URL builder는 `src/presentation/routes/route-codecs.ts`, route t 않는다. page는 HTTP client, storage, auth owner, output port나 TanStack API를 직접 import하지 않는다. +page는 경로 문자열을 적지 않는다. 경로는 계약의 `path` 한 곳에만 있다. +`presentation/reference-routes.ts`가 다음 helper를 둔다. 이 기능의 route codec은 +`presentation/reference-route-codecs.ts`에 있다. + +- 링크: `referenceRouteUrl(routeId, { params, search })`. 위 `buildRouteUrl`에 + 이 기능의 codec을 넘긴다. +- route 입력: `useReferenceListFilters()`, `useReferenceResourceId()`. 이미 + 통과한 codec으로 다시 읽어 cast 없이 타입을 얻는다. + ## 설치 지점 feature가 실제 contribution을 소유한다. diff --git a/src/features/reference-feature/context-routes.ts b/src/features/reference-feature/context-routes.ts index a36d5220..d5a214df 100644 --- a/src/features/reference-feature/context-routes.ts +++ b/src/features/reference-feature/context-routes.ts @@ -1,10 +1,8 @@ import type { RouteObject } from "react-router-dom"; import { REFERENCE_FEATURE_CONTRACT } from "./contracts/reference-feature-contract.ts"; -import { - REFERENCE_FEATURE_ROUTE_CODECS, - REFERENCE_FEATURE_ROUTE_RUNTIME, -} from "./presentation/reference-feature-runtime.ts"; +import { REFERENCE_FEATURE_ROUTE_RUNTIME } from "./presentation/reference-feature-runtime.ts"; +import { REFERENCE_FEATURE_ROUTE_CODECS } from "./presentation/reference-route-codecs.ts"; export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze( Object.values(REFERENCE_FEATURE_CONTRACT.routes).map((definition) => { diff --git a/src/features/reference-feature/presentation/reference-feature-runtime.ts b/src/features/reference-feature/presentation/reference-feature-runtime.ts index 8d33baeb..133683eb 100644 --- a/src/features/reference-feature/presentation/reference-feature-runtime.ts +++ b/src/features/reference-feature/presentation/reference-feature-runtime.ts @@ -1,21 +1,9 @@ import { lazy } from "react"; import { REFERENCE_FEATURE_ID } from "../contracts/reference-feature-contract.ts"; -import { - referenceResourceListQuerySchema, - referenceResourceParamsSchema, -} from "../contracts/reference-schemas.ts"; - -/** - * 15-01. Route codecs travel with the context routes (`context-routes.ts` puts - * them on each route handle), not with the boot-time feature module: zod - * schemas are executable and the shell needs none of them before a reference - * route is entered. - */ -export const REFERENCE_FEATURE_ROUTE_CODECS = { - ReferenceResourceListQuery: referenceResourceListQuerySchema, - ReferenceResourceParams: referenceResourceParamsSchema, -} as const; +// 16-04. The codecs have their own file: the pages' link helpers need them and +// this file lazy-loads the pages, so a page importing it would close a cycle. +import { REFERENCE_FEATURE_ROUTE_CODECS } from "./reference-route-codecs.ts"; export const REFERENCE_FEATURE_ROUTE_RUNTIME = { REFERENCE_RESOURCE_LIST: Object.freeze({ diff --git a/src/features/reference-feature/presentation/reference-resource-detail-page.tsx b/src/features/reference-feature/presentation/reference-resource-detail-page.tsx index 29d6e9b3..20e1f551 100644 --- a/src/features/reference-feature/presentation/reference-resource-detail-page.tsx +++ b/src/features/reference-feature/presentation/reference-resource-detail-page.tsx @@ -4,15 +4,17 @@ import { AsyncSurface, DetailPage, } from "../../../presentation/design-system/index.ts"; -import { useRouteInput } from "../../../presentation/routes/route-input.tsx"; import { useLocale } from "../../../presentation/i18n/index.ts"; +import { + referenceRouteUrl, + useReferenceResourceId, +} from "./reference-routes.ts"; import { useReferenceFailureAction } from "./use-reference-failure-action.ts"; import { useReferenceDetail } from "./use-reference-feature.ts"; export default function ReferenceResourceDetailPage() { const { date, message } = useLocale(); - const route = useRouteInput(); - const resourceId = String(route.params.resourceId); + const resourceId = useReferenceResourceId(); const { query } = useReferenceDetail(resourceId); const resource = query.data; const failureAction = useReferenceFailureAction(query.state.failure); @@ -21,7 +23,7 @@ export default function ReferenceResourceDetailPage() { + {message("reference.list.resources")} } diff --git a/src/features/reference-feature/presentation/reference-resource-form-page.tsx b/src/features/reference-feature/presentation/reference-resource-form-page.tsx index 13d796d4..5661e415 100644 --- a/src/features/reference-feature/presentation/reference-resource-form-page.tsx +++ b/src/features/reference-feature/presentation/reference-resource-form-page.tsx @@ -23,6 +23,7 @@ import { toCreateReferenceCommand, type ReferenceResourceFormValues, } from "./reference-resource-form.ts"; +import { referenceRouteUrl } from "./reference-routes.ts"; import { useReferenceFailureAction } from "./use-reference-failure-action.ts"; import { useReferenceCreate } from "./use-reference-feature.ts"; @@ -71,7 +72,7 @@ export default function ReferenceResourceFormPage() { @@ -111,7 +112,7 @@ export default function ReferenceResourceFormPage() {