Files
clean-architecture-frontend…/docs
DongHyeonka d6e4e51688 fix(contexts): 계약에 없는 라우트 핸들을 라우트 적재 때 막는다 (09-06)
문제: context gateway는 적재한 라우트의 handle `routeId`가 가리키는
등록 라우트를 그린다. `context-routes.ts`가 기능 계약에 없는 route id를
handle에 실으면(오타, 계약에서 지운 라우트) 적재는 성공하고, 그 URL을
그릴 때 context 경계 실패 화면이 된다. 7139c7c가 리뷰의 (1)(2)를 했고
(3) "핸들의 route id가 레지스트리에 있는가"는 설계 선택으로 남겼다.

고른 방법: 적재 때 검사한다. `defineBoundedContextModule`이
`route.loadRoutes`를 감싸, 적재한 각 라우트의 handle `routeId`가 그
context 기능들의 계약 라우트 id에 없으면 TypeError로 실패한다. 메시지에
route id, context id, 기능 id를 담는다. handle에 `routeId`가 없어도
실패한다(gateway는 그 라우트를 NOT_FOUND로 그린다).
- 모든 context가 이 함수를 거치므로(생성된 product-context-index) 모든
  context에 걸린다. 모든 context의 라우트를 적재하는 기존 단위 테스트
  (tests/unit/route-runtime.test.ts)가 개발 단계에서 잡는다.
- 적재 실패는 09-09(de48db2)의 "청크 누락이 아닌 적재 실패" 경로로
  context 경계에 가서 `ui.render.failed` 진단을 남긴다. 테스트로 확인했다.
- 라우트는 계속 늦게 읽는다. context를 정의할 때는 loadRoutes를 부르지
  않는다.
- 7139c7c의 `contractRoutePaths`를 bounded-context-module.ts로 옮겨
  앱 모듈과 같이 쓴다. "계약 라우트"의 정의가 한 곳에 남는다.
- starter-experience.md 기능 추가 3단계에 규칙을 적었다.

버린 대안:
- 헬퍼로 제공: 그 헬퍼를 쓰는 context만 지킨다. 안 쓰면 그만이다.
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 handle을 모른다.

위험·한계:
- 생성된 index는 기능별 라우트를 합쳐서 돌려주므로, 어느 기능의
  `context-routes.ts`가 잘못된 handle을 냈는지는 알 수 없다. 메시지는
  그 context의 기능 id 전부를 적는다. 기능이 하나인 context(지금
  reference)는 정확하다.
- 최상위 라우트만 본다. 지금 context 라우트는 평평하다. children을 쓰는
  context가 생기면 재귀가 필요하다.
- `defineBoundedContextModule`을 거치지 않고 손으로 만든 context 객체는
  검사되지 않는다. 그 경우는 기존처럼 렌더 때 context 경계가 잡는다.
- 등록 라우트가 없는 URL에서 난 적재 실패는 진단 route_id가 NOT_FOUND다.
  레지스트리의 NOT_FOUND splat이 모든 URL에 맞아 gateway의
  `?? routeModule.id` 대체가 쓰이지 않는다. 09-09의 동작이고 고치지 않았다.
- 초기 JS gzip +141 B(203,818 -> 203,959 B, 여유 982 -> 841 B).
  같은 worktree에서 `vite build` 두 번으로 쟀다.

검증:
- RED: tests/architecture/context-route-roots.test.ts 새 3건 중 거절
  2건이 "promise resolved ... instead of rejecting"으로 실패(10건 중 2
  실패). tests/component/context-boundary-diagnostics.test.tsx 새 1건이
  route_id "FIXTURE_ITEMSS"(렌더 때 경계)로 실패.
- GREEN: 두 파일 10건, 4건 통과.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
  runtime-schema,integration,scripts,scale}(pnpm을 띄우는 4개 제외)
  296 files 중 3,383 통과, 1건 실패. 실패는 telemetry-storm.test.ts의
  10초 timeout(부하 34)이고 단독 재실행에서 4건 통과했다.
  check-registries, check-adapter-inventory 통과.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과.
  verify-documentation-readiness PASS_SCOPED.
- check:architecture는 pnpm이 필요해 돌리지 않았다.

Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-06
2026-11-03 00:53:27 +09:00
..

문서 색인

docs/의 문서를 세 묶음으로 나눈다.

1. 현재 계약   지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계   앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력   리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다

문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는 문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로 확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.

README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.

1. 현재 계약

처음 읽을 입구 문서 6개다.

문서 정하는 것
README.md 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
architecture/optional-adapter-recipes.md 선택 기능(recipe)을 넣고 빼는 절차
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

입구 문서가 가리키는 세부 규칙:

게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md verify:documentation (FE-GATE-017)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)

2. 목표 설계

설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.

3. 작업 이력·리뷰

템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다. 복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의 "Files you can delete after copying" 절에 있다.

경로 내용
superpowers/ 과거 작업 계획과 스펙
reviews/ 리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다
../SPEC.md, ../tasks/ 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다