2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는 문서가 지금 코드와 다른 말을 한다. - 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로 가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/, 패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06). - 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다. optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리 블록이 옮긴 곳을 가리킨다(1112/09-02). - 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로 가리킨다(1112/08-17). - 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007), drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는 꼬리 문장(1112/02-08). - 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다 (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은 verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07). - create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자 (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15). - secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장 (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫 (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조 (1106/14-02). 고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다. 버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다). 위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제 docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드 예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture 규칙과 부딪쳐 결정 대기로 남긴다. 검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과 FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다. Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04, 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15, 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02, 0929/14-03, 0929/13-10, 1106/14-02
272 lines
24 KiB
Markdown
272 lines
24 KiB
Markdown
# 스타터 경험 계약
|
|
|
|
이 repo는 인프라 계약만 주지 않는다. 바로 실행되는 앱을 준다. 이 앱은 특정 도메인에 묶이지 않는다.
|
|
스타터 경험(starter experience)은 일부러 페이지 단위로 갈아 끼울 수 있게 만들었다.
|
|
셸, provider, 경계, UI primitive, 상태 화면(state surface)은 그대로 다시 쓴다.
|
|
|
|
## runtime 조립
|
|
|
|
```text
|
|
validated config + coherent release manifest
|
|
-> concrete adapters
|
|
-> QueryClientProvider
|
|
-> ApplicationProvider
|
|
-> RouterProvider
|
|
-> ThemeProvider
|
|
-> SessionProvider
|
|
-> AppShell
|
|
-> lazy route boundary
|
|
```
|
|
|
|
설정 검증이나 release 정합성 검사가 실패하면 부팅은 제품 화면을 마운트하기 전에 멈춘다.
|
|
지연 로드(lazy) 페이지는 각각 Suspense와 telemetry를 남기는 라우트 경계 안에서 렌더링된다.
|
|
라우트가 바뀌면 포커스가 새 페이지 제목으로 옮겨진다.
|
|
건너뛰기 링크(skip link)와 랜드마크는 셸에 고정되어 바뀌지 않는다.
|
|
|
|
## 등록된 라우트
|
|
|
|
라우트 목록은 `ROUTE_REGISTRY`(`src/features/installed-feature-contracts.ts`)다.
|
|
`src/contracts/routes.ts`의 플랫폼 라우트에, 설치된 모든 feature의 라우트를 더한 것이다.
|
|
플랫폼 개요 페이지(`/examples/platform`)가 조립된 목록을 실행 중에 보여 준다.
|
|
그래서 이 문서는 목록을 따로 복사해 두지 않는다.
|
|
|
|
내비게이션의 이름과 순서는 `ROUTE_REGISTRY`에서 온다. 사이드바는 라우트 목록을 따로 두지 않는다.
|
|
클라이언트가 내리는 접근 판단은 어디서도 인가(authorization)라고 내세우지 않는다.
|
|
|
|
## 인증 연결 지점
|
|
|
|
세션 port가 제공하는 것은 상태 구독, 로그인 시작, 로그아웃, 자격 증명(credential) 붙이기, 세션 복구, 미인증 알림이다.
|
|
application 계층과 presentation 계층은 자격 증명의 내용을 들여다보지 않는다.
|
|
|
|
- `demo`: 로컬·개발 환경에서만 쓰는 상태 전환이다. 자격 증명이 없다.
|
|
- `external`: `globalThis.__CA_FRONTEND_AUTH_OWNER__`에 맡긴다.
|
|
- 외부 owner가 없거나 잘못됐을 때: `integration-failed`로 막고 실패한다(fail closed).
|
|
|
|
외부 owner는 `readState`, `readSubject`, `subscribe`,
|
|
`beginSignIn`, `signOut`, `attachCredential`, `recoverSession`,
|
|
`notifyUnauthenticated`를 구현한다. 토큰을 받아 오고 저장하는 일은 owner가 맡는다.
|
|
이 메서드 중 하나라도 빠진 owner는 거부된다. 그러면 세션은 `integration-failed`로 막힌다(fail closed).
|
|
|
|
owner가 일으키는 상태 전환과, 응답마다 `recover()`가 남기는 상태는
|
|
`src/application/ports/auth-session-port.ts`의 `SessionState`와 `SessionGateway.recover`에 적혀 있다.
|
|
짝 백엔드(paired backend)의 두 인증 모드에는 새로 쓰지 않고 복사하면 되는 owner가 있다.
|
|
JWT 모드는 `recipes/session-owners/oidc-pkce-session-owner.ts`다(Keycloak, PKCE를 쓰는 authorization code, `EXTERNAL_BEARER`).
|
|
Redis 세션 모드는 `recipes/session-owners/cookie-session-owner.ts`다(세션 쿠키, 그리고 `SESSION_COOKIE_*` 프로필과 `X-XSRF-TOKEN` provider).
|
|
`docs/manual/04-paired-backend-session.md`가 이 둘을 연결한다.
|
|
백엔드 템플릿이 주지 않는 것도 이 문서에 적혀 있다. realm 안의 브라우저 클라이언트, 그리고 로그인·로그아웃·세션 endpoint다.
|
|
|
|
`readSubject()`는 필수다. subject는 로그인한 사용자를 가리키는 식별자다.
|
|
서버 상태 캐시는 세션 상태나 subject가 바뀔 때만 비운다.
|
|
그래서 같은 사용자의 토큰을 갱신해도 캐시된 데이터는 남는다. `readSubject()`는 다음을 돌려줘야 한다.
|
|
|
|
- 내용을 해석하지 않는 빈 값이 아닌 문자열. 한 사용자는 토큰을 갱신해도 값이 같고,
|
|
사용자끼리는 값이 달라야 한다. 예: OIDC `sub` claim, Supabase
|
|
`session.user.id`, Firebase `user.uid`
|
|
- 아무도 로그인하지 않았으면 `null`
|
|
- access token, refresh token, 그 밖의 어떤 자격 증명도 돌려주지 않는다
|
|
|
|
owner가 `authenticated`를 알리는데 `readSubject()`가 `null`이나 `""`를 돌려주면,
|
|
runtime은 토큰 갱신과 계정 전환을 구별하지 못한다. 이때는 막힌 쪽으로 실패한다(fail closed).
|
|
그런 알림이 올 때마다 서버 상태를 비운다. 그리고 매번
|
|
`cache.operation.failed` 진단을 `operation: SCOPE_FENCE`, `reason: SUBJECT_MISSING`과 함께 남긴다.
|
|
이 진단이 보이면 owner가 subject를 알려 주지 않는다는 뜻이다.
|
|
`demo` adapter는 고정된 데모 사용자 하나를 subject로 알린다.
|
|
|
|
마이그레이션: 예전에는 `readSubject()`가 선택이었다. 이전 release에 맞춰 쓴 owner는 이 메서드를 더해야 한다.
|
|
없으면 시작할 때 owner가 거부된다(세션이 `integration-failed`가 된다).
|
|
TypeScript로 쓴 owner는 `ExternalSessionOwner`에 맞춰 더는 컴파일되지 않는다.
|
|
`AuthSessionPort`나 `SessionGateway`를 직접 구현한 코드도 같은 식으로 `getSubject()`를 더해야 한다.
|
|
|
|
## 스타터 확장
|
|
|
|
새 플랫폼 작업은 따로 노는 라우트 규칙이나 데이터 로딩 규칙을 하나 더 만들지 않는다.
|
|
대신 지금 규칙인 [기능 매뉴얼의 패턴 표](../manual/reference/patterns.md)와 [계층 규칙](layers.md)을 따른다.
|
|
설계 배경(기록)은 [라우팅, 페이지 템플릿, 재사용 패턴](../design/2026-07-26-routing-pages-and-patterns-design.md)과
|
|
[TypeScript, 상태, 데이터 흐름 목표](../design/2026-07-26-typescript-state-and-data-flow-design.md)다.
|
|
|
|
### 스타터 화면 바꾸기
|
|
|
|
`/`(`src/presentation/pages/home-page.tsx`)는 플랫폼의 `APP_HOME`이다.
|
|
feature가 그 route id를 선언하면 이 자리를 넘겨받는다("제품 홈과 레이아웃" 참고).
|
|
홈에 있는 스타터 링크는 내비게이션의 처음 세 화면이다.
|
|
|
|
템플릿은 예제 feature를 주지 않는다. 예제 화면(`/examples/ui`,
|
|
`/examples/states`, `/examples/auth`)과 참조 샘플은 2026-11-07에 지웠다.
|
|
디자인 시스템 갤러리와 화면 상태 갤러리는 workshop story
|
|
(`src/presentation/design-system/galleries.stories.tsx`)다.
|
|
feature를 만드는 방법은 매뉴얼(`docs/manual/`)과 `create:feature`가 보여 준다.
|
|
제품이 한동안 남겨 두는 샘플은 `scripts/lib/removable-template-features.ts`에 적는다.
|
|
`verify:documentation`은 샘플이 설치돼 있는 동안 그 경로를 검사한다.
|
|
샘플의 `feature-module.ts`가 없어지면 그 경로를 받아들인다(1105/14-01).
|
|
`corepack pnpm test:sample-removal`은 repo 복사본에서 샘플을 지우고 그 복사본에서 gate를 돌린다.
|
|
|
|
플랫폼 개요(`/examples/platform`,
|
|
`src/presentation/examples/platform-overview-page.tsx`)는 플랫폼 라우트로 남는다.
|
|
이 페이지는 설치된 registry를 보여 준다. lab gate(FE-GATE-026)는 이 페이지에 들어가는 시간을 잰다.
|
|
feature 라우트라면 처음 들어갈 때 페이지보다 먼저 그 context의 routes 모듈도 불러온다.
|
|
이 두 번째 요청 왕복은 200 ms budget 안에 들어가지 않는다.
|
|
이 페이지의 테스트는 `tests/component/starter-*.test.tsx` 파일들이다.
|
|
|
|
플랫폼의 component 테스트(router, 경계, 셸, runtime 트리)는
|
|
`tests/helpers/fixture-feature.tsx`에 있는 테스트 전용 feature의 페이지에서 돈다.
|
|
`tests/e2e`와 `tests/visual`의 브라우저 수준 검사는 홈 페이지, 플랫폼 개요, 갤러리 story를 쓴다.
|
|
feature가 있어야 하는 검사(`tests/e2e/generated-feature.spec.ts`, chunk 복구 spec)는
|
|
`create:feature`가 쓰는 feature를 넣은 repo 복사본을 만든다(`scripts/lib/generated-feature.ts`).
|
|
|
|
### 소유 선언
|
|
|
|
`scripts/generate-product-feature-index.ts`가 feature, context, app을 찾아낸다.
|
|
각 경계는 자기 부모만 선언한다. 선언은 생성기가 읽는, export된 문자열 리터럴이나 정수 리터럴이다.
|
|
|
|
| 파일 | export |
|
|
| --- | --- |
|
|
| `src/apps/<app>/app-module.ts` | `APP_MODULE_ID`, `APP_MAX_CONTEXTS` |
|
|
| `src/contexts/<context>/context-module.ts` | `CONTEXT_MODULE_ID`, `CONTEXT_APP_ID`, `CONTEXT_ROUTE_PATH`, `CONTEXT_MAX_FEATURES` |
|
|
| `src/features/<feature>/feature-module.ts` | `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`, `FEATURE_MODULE` |
|
|
| `src/features/<feature>/feature-runtime.ts` | `FEATURE_RUNTIME` (`feature-module.ts`만 동적으로 import한다) |
|
|
| `src/features/<feature>/context-routes.ts` | `FEATURE_CONTEXT_ROUTES` |
|
|
| `src/contexts/<context>/context-layout.tsx` (선택) | `CONTEXT_LAYOUT`, 그 context 고유의 레이아웃("제품 홈과 레이아웃") |
|
|
|
|
생성기는 `src/.generated/`(git이 무시한다)에 세 가지를 쓴다.
|
|
설치 카탈로그가 import하는 feature 색인, router가 지연 로드하는 context 색인, 선택된 app이다.
|
|
모든 빌드·검사 script가 생성기를 먼저 돌린다. 직접 돌리려면
|
|
`corepack pnpm generate:feature-index`를 쓴다. 다음 경우에 생성기는 해당 파일 이름을 대며 실패한다.
|
|
|
|
- `src/features/` 아래 디렉터리에 `feature-module.ts`가 없을 때. feature가 아닌 코드
|
|
(테스트가 조립하는 IndexedDB 소비자,
|
|
`tests/fixtures/indexeddb-consumer`)는 `src/features/` 밖에 둔다.
|
|
- feature가 선언되지 않은 context를 가리키거나, context가 선언되지 않은 app을 가리킬 때.
|
|
- context나 app이 선언한 budget을 넘을 때.
|
|
- `VITE_PRODUCT_FEATURES`가 app이 선언하지 않은 feature를 가리킬 때.
|
|
이 변수는 무엇이든 컴파일하기 전에, 여기서 설치할 feature 집합을 줄인다.
|
|
|
|
### feature 추가
|
|
|
|
1. `src/features/<feature>/feature-module.ts`를 만든다. `defineFeatureModule`
|
|
(`src/features/feature-module.ts`)로 `FEATURE_MODULE`을 만든다. 이 파일은
|
|
feature의 선언이고 초기 chunk에 들어간다. 그래서 데이터만 담는다.
|
|
담는 것은 셋이다. 첫째, 선언 계약이다(라우트, 라우트 runtime 계약,
|
|
무효화(invalidation), topic 버전, 부팅 때 release manifest와 맞춰 보는 외부 `contractPackages`).
|
|
둘째, message 카탈로그다. 셋째, `feature-runtime.ts`를 동적으로 import하는
|
|
`loadRuntime`이다. `create:feature`가 완성된 파일을 써 준다.
|
|
2. `defineFeatureRuntime`으로 `src/features/<feature>/feature-runtime.ts`를 만든다.
|
|
담는 것은 셋이다. `schemas`(feature의 라우트 schema와 API schema에 대한 FE-REG-SCHEMA 행),
|
|
adapter contribution(`defineFeatureAdapterContribution`. `needs`에 받을 플랫폼 capability를 적는다),
|
|
contract contribution(HTTP operation)이다.
|
|
feature의 라우트 하나에 들어갈 때 router가 이 파일을 불러온다(`application.features.load`).
|
|
어디에서도 이 파일을 정적으로 import하지 않는다. 그러면 feature마다 실행 코드 전체가
|
|
다시 초기 chunk에 들어간다. 대략 gzip 3.9 KB다
|
|
(`tests/unit/feature-shape-growth.test.ts`는 feature 하나의 상한을 1 KiB로 둔다).
|
|
HTTP API는 contract contribution descriptor로 한 번만 쓴다. 이 descriptor가 실제로 실행된다.
|
|
그리고 여기서 뽑아낸 FE-REG-API 행을 `check:registries`가 관리한다
|
|
(`src/contracts/api-operations.ts`의 `projectApiOperationRows`).
|
|
제품 feature의 contract contribution은 `EXTERNAL_PACKAGE` source를 쓴다.
|
|
`TEMPLATE_FIXTURE`는 템플릿의 참조 샘플이 쓰던 source다. 이 source는 release 계약 집합에
|
|
절대 들어가지 않는다. composer는 어느 제품 feature에서든 이 source를 거부한다.
|
|
3. `FEATURE_CONTEXT_ROUTES`를 export하는 `src/features/<feature>/context-routes.ts`를 만든다.
|
|
페이지 컴포넌트는 여기서 지연 import한다. 각 route handle은 그 라우트의 params/search `codecs`를 갖는다.
|
|
소유 context는 자기 route root에 들어갈 때만 이 파일을 불러온다
|
|
(예: `create:feature <id> --with-create`로 만든 feature의 `context-routes.ts`).
|
|
각 handle의 `routeId`는 같은 context에 있는 feature 계약의 라우트여야 한다.
|
|
아니면 context가 라우트를 불러올 때 거부하고, 라우트·context·feature 이름을 댄다
|
|
(`src/contexts/bounded-context-module.ts`).
|
|
4. `FEATURE_CONTEXT_ID`에 소유 context를 적는다. 있는 context를 쓰거나,
|
|
app이 소유하는 `src/contexts/<context>/context-module.ts`를 더한다.
|
|
feature 계약의 라우트 경로는 모두 그 context의 `CONTEXT_ROUTE_PATH`이거나 그 아래여야 한다.
|
|
또 다른 context의 같은 root나 더 구체적인 root 아래에 들어가면 안 된다.
|
|
router는 feature 라우트를 소유 context 안에서만 렌더링하기 때문이다.
|
|
플랫폼 라우트가 그 경로에 응답해서도 안 된다. router는 `AppShell`의 플랫폼 라우트를 먼저 시도한다.
|
|
그래서 다음 경로에서는 feature가 렌더링되지 않는다. 플랫폼 라우트와 같은 경로,
|
|
`APP_HOME`이 아닌 id로 쓴 `/`, 레이아웃 없는 `*` root(찾을 수 없음 라우트가 모든 URL을 가져간다)다.
|
|
이 규칙을 어긴 라우트는 app 모듈이 불러올 때 거부하고, 라우트·feature·context 이름을 댄다
|
|
(`src/apps/deployable-app-module.ts`). 플랫폼 홈을 넘겨받는 라우트는 예외다
|
|
("제품 홈과 레이아웃").
|
|
5. feature에 application 입력이 있으면 feature 쪽에서 `ApplicationFeatureInputs`를
|
|
확장(augment)한다(IndexedDB 소비자 fixture가
|
|
`tests/fixtures/indexeddb-consumer/application/local-draft-api.ts`에서 이렇게 한다).
|
|
6. `corepack pnpm check:architecture`, `corepack pnpm check:types`,
|
|
`corepack pnpm check:registries`와 테스트를 돌린다. `tests/unit/two-feature-install-typecheck.test.ts`는
|
|
feature가 둘 이상일 때도 설치 카탈로그가 컴파일되는지 지킨다.
|
|
7. `corepack pnpm test:sample-removal -- --feature=<feature id>`를 돌린다.
|
|
이 feature를 빼도 제품이 빌드되고 gate를 통과하는지 확인한다.
|
|
|
|
feature 디렉터리 밖 파일은 아래 표에 있다. feature에 필요한 나머지는 모두
|
|
`src/features/<feature>/`와 `tests/features/<feature>/` 안에 있다.
|
|
|
|
| 파일 | 언제 | 없으면 실패하는 것 |
|
|
| --- | --- | --- |
|
|
| `src/.generated/*` | 손으로 고치지 않는다. 모든 빌드·검사 script가 다시 만든다 | — |
|
|
| `public/release-manifest.json` (추적 파일, dev server의 manifest) | feature를 더하거나 뺄 때마다. `create:feature`가 다시 쓴다(`node scripts/write-dev-release-manifest.ts`). feature와 같은 커밋에 넣는다. 두 feature 브랜치가 모두 이 파일의 `setDigest` 줄을 바꾼다. 병합 충돌이 나면 아무 쪽이나 고르고 명령을 다시 돌린다(1105/16-01) | `test:unit`(`tests/unit/dev-release-manifest.test.ts`)이 실패하며 이 명령을 알려 준다. dev server가 부팅하지 못한다(`CONTRACT_SET_PACKAGE_MISSING`) |
|
|
| `config/scale/feature-shape-ceilings.json` `initialJavascript` (추적 파일) | feature를 더하거나 뺄 때마다, 그리고 초기 JavaScript를 바꾸는 템플릿 변경마다: `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. 그 변경과 같은 커밋에 넣는다. 병합 충돌이 나면 명령을 다시 돌린다 | `test:unit`(feature-shape growth 테스트가 이 값을 빌드 결과와 비교한다) |
|
|
| `src/contexts/<context>/context-module.ts` | feature에 새 context가 필요할 때 | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
|
|
| `src/contexts/<context>/context-layout.tsx` | context에 `AppShell` 대신 자기 틀이 필요할 때(아래 "제품 홈과 레이아웃" 참고) | 없음. 파일이 없으면 context는 `AppShell` 안에서 렌더링된다 |
|
|
| `docs/accessibility/route-reviews/<ROUTE_ID>.md` | feature가 더하는 라우트마다. 기록 하나를 복사해 `Status: pending-manual-review`로 되돌린다 | `test:unit`(`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation`(route ID를 댄다), FE-GATE-009(`review:a11y-manual -- --format-only`). release 때는 FE-GATE-028이 서명된 검토를 요구한다 |
|
|
| `tests/e2e/accessibility.spec.ts` | feature마다 고치지 않는다(1103/16-03). 이 파일은 모든 경로 파라미터를 한 값으로 채우고, 각 API 요청에 설치된 descriptor로 응답한다. 목록 읽기에는 `responseEnvelope` 틀에 담은 빈 목록으로 응답한다. 보호된 페이지가 렌더링 전에 설치된 GET이 아닌 요청을 보낼 때만 고친다 | `test:a11y`(FE-GATE-009): 설치된 GET 어디에도 선언되지 않은 요청이 오면 그 라우트가 실패한다. 목록만 읽은 페이지에 경고 상자(`role="alert"`)가 떠도 실패한다 |
|
|
| `src/features/product-capabilities.ts` (제품 소유) | `needs`가 템플릿이 만들지 않는 capability를 가리킬 때: `ProductFeaturePlatformCapabilities`에 그 타입을 적는다. `FeaturePlatformCapabilities`가 이를 확장하므로 app, scripts, tests의 타입 검사 프로그램이 모두 그 키를 본다(`product-composition.ts` 안에 둔 augmentation은 scripts의 프로그램이 보지 못한다) | `check:types`: feature에서 `Type '"<capability>"' is not assignable to type 'keyof FeaturePlatformCapabilities'` |
|
|
| `src/bootstrap/product-composition.ts` (제품 소유) | `needs`가 템플릿이 만들지 않는 capability를 가리킬 때: 여기서 그 capability를 돌려준다. 타입은 `product-capabilities.ts`에 적는다. `indexedDb`는 `recipes/frontend-capabilities/indexeddb-feature-capability.ts`처럼 만든다. 제품 인증 프로필의 자격 증명도 여기서 돌려준다. 세션을 직접 소유하는 제품(BFF의 httpOnly 쿠키)은 부팅 전에 host 전역에 세션 owner를 설치하지 않는다. 대신 `composeProductSessionOwner`에서 돌려준다 | `check:types`. 실행 중에는 `feature <id> needs <capability>, which the host did not provide`. 세션 owner가 없으면 `AUTH_MODE: "external"`은 세션이 `integration-failed`인 채로 부팅한다 |
|
|
| `src/contracts/product-contracts.ts` (제품 소유) | 제품 인증 프로필, 또는 제품 runtime 설정 키와 그 FE-REG-ENV 행(`PRODUCT_ENV_REGISTRY`) | 인증 프로필: 그 operation을 불러오는 모든 gate가 `Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>`로 실패한다. 설정 키: 키를 읽는 곳에서 `check:types`가 실패한다. 키에는 `.default()`를 주거나 `.optional()`로 만든다. 템플릿 테스트는 `tests/helpers/runtime-config.ts`로 설정을 만들고, 이 helper는 제품의 기본값을 채운다. 그래서 기본값 없는 필수 키는 이 테스트를 실패시킨다. FE-REG-ENV 행: `check:registries`가 행의 필드를 검사한다. `tests/unit/env-registry-coverage.test.ts`(`test:unit`)는 키마다 행이 있고, 그 행에 schema의 `required`와 `defaultValue`가 적혀 있기를 요구한다 |
|
|
| `config/runtime/<profile>.json` | 선택: `FEATURE_OVERRIDES` 항목으로 feature를 끈다 | 없음 |
|
|
| `package.json`, lockfile, `config/security/dependency-change-evidence.json` | contract contribution이 생성된 `@org-contracts/*` 패키지를 운영 의존성(production dependency)으로 import할 때 | `generate:supply-chain`(`check:bundle` 안에서 돈다): `high-risk dependency missing review: add:<package>` |
|
|
|
|
중앙 카탈로그(`src/features/installed-*.ts`)와 registry governance 파일은 바뀌지 않는다.
|
|
거기 적힌 소비자 디렉터리는 모든 feature를 덮는 glob이다
|
|
(`src/features/*/adapters`, `config/contracts/registry-governance.json`).
|
|
라우트의 params/search schema id는 feature가 등록한 schema와 맞춰 본다.
|
|
`loadingSurface`는 kebab-case 이름이기만 하면 된다.
|
|
그래서 자기 schema와 loading surface를 가진 라우트도 governance를 고칠 필요가 없다.
|
|
registry baseline도 바뀌지 않는다. 새 라우트, API operation,
|
|
schema, 무효화 topic, namespace, edge는 registry에 더하기만 하는 변경이다.
|
|
`update:registry-baseline`이나 breaking 증거는 행이나 그래프 항목을 지우거나 바꿀 때만 필요하다.
|
|
`tests/unit/second-api-feature-registries.test.ts`는 이런 feature(API
|
|
operation 하나, 자기 search schema와 loading surface를 가진 라우트 하나, 무효화 topic 하나)를
|
|
repo 복사본에 더하고 `check:registries`를 돌린다.
|
|
|
|
schema, operation, mapper, 라우트, chunk의 id와 무효화 topic은 전역이다.
|
|
앞에 feature 이름을 붙인다. `create:feature`는
|
|
`<Pascal>NoRequest`를 쓴다. 맨 `NoRequest`를 쓰면 feature끼리 이름이 겹친다.
|
|
feature 자기 operation의 MSW 시나리오는 feature의 설치된 계약을 넣은
|
|
`createHttpScenarioHandler`(`tests/mocks/handlers/http-scenarios.ts`)로 만든다.
|
|
공유 시나리오 카탈로그는 바뀌지 않는다.
|
|
|
|
### 제품 홈과 레이아웃
|
|
|
|
홈이 feature 화면인 제품이나, 화면이 `AppShell`이 아닌 다른 틀을 쓰는 제품은 그것을 선언한다.
|
|
router와 카탈로그는 바뀌지 않는다.
|
|
|
|
- **홈.** feature는 계약에 id가 `APP_HOME`인 라우트를 선언해 플랫폼 홈을 넘겨받는다.
|
|
feature가 넘겨받을 수 있는 라우트는 플랫폼이 정한다
|
|
(`src/contracts/routes.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS`).
|
|
그 밖의 플랫폼 route id를 쓰면 여전히 중복이다.
|
|
두 feature가 `APP_HOME`을 선언하면 카탈로그를 불러올 때 둘의 이름을 대며 실패한다.
|
|
router는 소유 context의 route root가 무엇이든, 그 라우트를 소유 context와 함께 자기 경로에 마운트한다.
|
|
빌드에서 feature를 빼면(`VITE_PRODUCT_FEATURES`) 플랫폼 홈이 돌아온다.
|
|
실행 중에 feature를 끄면 그 경로에 비활성 feature 페이지가 뜬다.
|
|
- **레이아웃.** `CONTEXT_LAYOUT`(컴포넌트)을 export하는 `src/contexts/<context>/context-layout.tsx`가
|
|
있는 context는 `AppShell` 대신 그 레이아웃 아래에서 렌더링된다.
|
|
생성된 색인은 그 context의 라우트 하나에 들어갈 때 이 파일을 지연 로드한다.
|
|
router는 context를 그 feature들이 등록한 경로마다 레이아웃 아래에 마운트한다.
|
|
그래서 모르는 URL은 여전히 `AppShell` 안의 찾을 수 없음 페이지로 간다.
|
|
레이아웃 파일이 같은 컴포넌트를 export하는 context끼리는, 사용자가 그 사이를 옮겨 다녀도
|
|
레이아웃 인스턴스 하나를 유지한다. 그래서 여러 route root가 레이아웃 하나를 함께 쓸 수 있다.
|
|
- **접근성.** 레이아웃은 `#main-content`로 가는 건너뛰기 링크를 렌더링한다.
|
|
그리고 `<Outlet />`을 감싸는 `<main id="main-content" tabIndex={-1}>`을 정확히 하나 렌더링한다.
|
|
router는 라우트가 바뀔 때마다 포커스를 그곳으로 옮긴다.
|
|
레이아웃 라우트는 `AppShell`의 형제이고, 절대 그 안에 들어가지 않는다.
|
|
`tests/component/layout-landmarks.test.tsx`는 `AppShell`과 설치된 모든 context의
|
|
레이아웃을 렌더링하고, 이 둘이 없는 레이아웃을 실패시킨다.
|
|
- **실패.** 배포로 사라진 레이아웃 chunk도 라우트 chunk처럼 한 번 새로고침해 복구한다.
|
|
라우트 경계와 feature 경계는 `AppShell`에서와 똑같이 동작한다.
|
|
- 4단계의 route root 규칙은 모든 레이아웃에 걸쳐 적용된다.
|
|
두 context가 어떤 레이아웃을 갖든, root는 그 아래 URL을 가져간다.
|
|
|
|
`tests/component/context-layouts.test.tsx`는 이렇게 선언한 제품
|
|
(`tests/helpers/fixture-layout-product.tsx`)을 설치해 본다.
|
|
|
|
### 출시 전에
|
|
|
|
- 프로젝트 전용 변형을 더하기 전에 의미 토큰(semantic token), UI primitive, 상태 화면을 먼저 쓴다.
|
|
- component 동작 테스트, 모든 브라우저 엔진 E2E, 자동 axe 검사, 서명된 수동 라우트 증거를 더한다.
|
|
|
|
테마 선택은 공개된 `COLOR_SCHEME` 저장소 계약이다.
|
|
인증 토큰과 그 밖의 비밀 값은 계속 저장 금지 키다.
|