83 lines
4.7 KiB
Markdown
83 lines
4.7 KiB
Markdown
# 플랫폼 구성 화면 (`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. 함께 변경되는 파일
|
|
|
|
1. `src/contracts/routes.ts` — 레지스트리 항목
|
|
2. `src/contracts/route-runtime-contract.ts` — 런타임 계약 항목
|
|
3. `src/presentation/routes/route-runtime.tsx` — lazy import
|
|
4. `src/presentation/i18n/catalog.ts` — ko/en `route.EXAMPLES_PLATFORM.{title,navigation}`
|
|
5. `public/release-manifest.json` — `routeChunks` 항목
|
|
6. `config/contracts/registry-baseline.json` 및 승인·증거 파일
|
|
7. `src/presentation/styles/` — 요약 그리드 스타일
|
|
8. `tests/component/platform-overview-page.test.tsx` — 컴포넌트 테스트
|
|
|
|
## 7. 검증
|
|
|
|
- 타입, lint, 아키텍처, i18n, 디자인 시스템, 레지스트리 게이트
|
|
- `test:all`
|
|
- removal harness 4종. 특히 `test:sample-removal` 이후에도 페이지가 빈 상태로 정상 렌더되어야 한다.
|
|
- 실제 브라우저 렌더 확인
|