4.7 KiB
플랫폼 구성 화면 (EXAMPLES_PLATFORM) 설계
작성일: 2026-07-31
1. 문제
템플릿이 무엇을 설치해 두었는지 확인할 방법이 없다. 홈 화면은 "실행 계약 / 교체 가능한 연동 / 접근 가능한 화면"이라는 세 문장으로만 요약하고, 실제로 어떤 라우트·계약·런타임 능력이 설치되어 있는지는 소스를 직접 읽어야만 알 수 있다.
2. 해결 방향
설치 상태를 레지스트리에서 파생해서만 렌더하는 화면을 하나 추가한다. 수기 서술을 두지 않으므로 코드가 바뀌면 화면이 따라 바뀌고, 문서가 낡는 문제가 발생하지 않는다.
이 선택에는 부수 효과가 있다. reference feature를 삭제하면 관련 행이 자동으로 사라지므로
test:sample-removal harness의 잔재 스캔과 충돌하지 않는다. 반대로 수기 목록이었다면 샘플 이름이
페이지에 박혀 harness가 실패했을 것이다.
3. 배치
| 항목 | 값 | 근거 |
|---|---|---|
routeId |
EXAMPLES_PLATFORM |
|
path |
/examples/platform |
제품 개발 시 통째로 삭제 가능한 examples/ 옥 |
access |
public |
세션 연동 없이 확인 가능해야 함 |
loadingSurface |
example-page |
governance allowedValues에 이미 존재 — 신규 값 추가 없음 |
errorSurface |
route-boundary |
동일 |
chunkId |
route-examples-platform |
|
navigationOrder |
15 |
홈(10)과 UI(20) 사이. 기존 값 재번호 불필요 |
| 구현 파일 | src/presentation/examples/platform-overview-page.tsx |
examples/는 check:i18n 한글 리터럴 스캔 대상이 아님 |
4. 섹션 구성
전부 파생 데이터다.
| # | 섹션 | 출처 | 표현 대상 |
|---|---|---|---|
| 1 | 릴리스 신원 | ApplicationApi.runtime.getReleaseSummary() |
buildId, releaseId, configSchemaVersion, contractSet digest |
| 2 | 설치된 라우트 | ROUTE_REGISTRY |
path, access, chunkId, params/search 스키마 |
| 3 | 계약과 HTTP 오퍼레이션 | COMPOSED_CONTRACT_CONTRIBUTIONS, EXPECTED_CONTRACT_SET_PACKAGES |
외부 계약 패키지 수, 오퍼레이션별 재시도 의미·예산·바이트 한도·deadline·효과 확정성 |
| 4 | 서버 상태와 실행 상한 | SERVER_STATE_PROFILES, HTTP_EXECUTION_CEILINGS |
4개 프로파일의 staleTime·gcTime·결과 예산, 강제되는 실행 상한 |
| 5 | 선택적 런타임 능력 | INSTALLED_RUNTIME_CAPABILITIES |
realtime / webWorker / serviceWorker / offlineCommands 선택 여부 |
섹션 3의 "외부 계약 패키지 0개"와 섹션 5의 "4개 능력 전부 미선택"이 "어디까지 제공하는가"에 대한 답이다. 공통 런타임은 구현·검증되어 있으나 제품 기여물이 없어 선택되지 않은 상태임을 드러낸다.
5. 런타임 해석 결과
초판은 CAPABILITY_OVERRIDES 해석 결과를 제외했다. 해석이 bootstrap에서 일어나고
presentation-does-not-know-adapters 규칙이 presentation → bootstrap import를 금지했기 때문이다.
이후 docs/superpowers/plans/2026-07-31-platform-overview-completion.md가 그 경로를 만들었다.
describeRuntimeCapabilities가 정적 선택과 해석 결과를 경계된 스냅샷으로 축약하고,
RuntimeCapabilitiesPort를 통해 합성 루트가 그 스냅샷을 애플리케이션에 전달한다. 표현 계층은
runtime.getCapabilitySnapshot()만 호출하므로 bootstrap을 여전히 알지 못한다.
스냅샷이 selected와 active를 함께 실으므로 화면은 세 상태를 구분한다.
| 상태 | 조건 | 표시 |
|---|---|---|
| 미선택 | selected === 0 |
애초에 설치되지 않았다 |
| 운영자가 비활성화함 | selected > 0 && active === 0 |
설치됐으나 런타임 설정이 껐다 |
| 활성 | active > 0 |
지금 동작한다 |
6. 함께 변경되는 파일
src/contracts/routes.ts— 레지스트리 항목src/contracts/route-runtime-contract.ts— 런타임 계약 항목src/presentation/routes/route-runtime.tsx— lazy importsrc/presentation/i18n/catalog.ts— ko/enroute.EXAMPLES_PLATFORM.{title,navigation}public/release-manifest.json—routeChunks항목config/contracts/registry-baseline.json및 승인·증거 파일src/presentation/styles/— 요약 그리드 스타일tests/component/platform-overview-page.test.tsx— 컴포넌트 테스트
7. 검증
- 타입, lint, 아키텍처, i18n, 디자인 시스템, 레지스트리 게이트
test:all- removal harness 4종. 특히
test:sample-removal이후에도 페이지가 빈 상태로 정상 렌더되어야 한다. - 실제 브라우저 렌더 확인