문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와 입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는 문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를 보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한 문서의 경로만 본다. 고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number, map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨 scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이 부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는 문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation 단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의 documentation-readiness 시험이 이 repo를 그대로 두고 verify:documentation을 한 번 돌린다. - 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리 3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다. - 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와 도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는 이미 TS에 있다. - 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다 FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤 번역 커밋들이 지운다. - docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록· 검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수 절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와 글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다. - README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는 테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록 폴더 이름을 적지만 지운 사본에서도 통과하므로 deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를 테스트와 검사기 시험에 적었다). 위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때 verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다. review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자 검사에서 뺐다(HISTORY_HOLDERS). 검증: tests/unit/docs-system.test.ts(조건마다 실패 입력), documentation-readiness·template-feature-removal-documents· deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
307 lines
15 KiB
Markdown
307 lines
15 KiB
Markdown
# 프론트엔드 애플리케이션 기반(Frontend Application Foundation)
|
|
|
|
이 repo를 최소한의 React 프로젝트 템플릿으로 보지 않는다. 독립된 범용 SDK도
|
|
아니다.
|
|
아키텍처에서 맡는 역할은 다음과 같다:
|
|
|
|
> Frontend Application Foundation = 시작 골격(Starter / Composition Skeleton) + 재사용 capability 플랫폼(Reusable Capability Platform)
|
|
|
|
시작 골격 쪽은 bootstrap, 라우팅, provider, 프로젝트 규약, feature를 만들어
|
|
주는 `create:feature` 명령을 맡는다. 예시 feature는 싣지 않는다. capability
|
|
쪽은 재사용할 기술 문제를 맡는다. HTTP 실행, Server State, 인증 경계,
|
|
IndexedDB/OPFS, Cache Storage, realtime, 브라우저 RPC, 전송(transfer), 진단
|
|
같은 것이다.
|
|
|
|
정교한 capability의 비용은 제품 feature가 그 내부의 정교함을 몰라도 될 때만
|
|
받아들일 수 있다.
|
|
|
|
## 하이브리드 아키텍처
|
|
|
|
`src/`에는 최상위 폴더가 아홉 개 있다. 설명은 [계층 계약](./layers.md)의
|
|
표와 같다. 그 문서는 모든 import 규칙도 적는다.
|
|
|
|
platform 코드는 가로(수평)로 놓인다:
|
|
|
|
- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트
|
|
- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider
|
|
- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등
|
|
- `src/application` — 범용 use case, 포트, 정책, view-model
|
|
- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry
|
|
- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성
|
|
|
|
소유 선언이 feature를 배포 단위로 묶는다:
|
|
|
|
- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다
|
|
- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다
|
|
|
|
제품 비즈니스 코드는 세로(수직)로 놓인다:
|
|
|
|
- `src/features` — 지울 수 있는 수직 slice(`src/features/<id>/{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`)
|
|
|
|
feature 하나 안에는 다음이 있다:
|
|
|
|
- `features/<feature>/domain`
|
|
- `features/<feature>/application`
|
|
- `features/<feature>/contracts`
|
|
- `features/<feature>/adapters`
|
|
- `features/<feature>/presentation`
|
|
|
|
의존성 모델은 다음과 같다:
|
|
|
|
Domain / Use case
|
|
|
|
|
| owns
|
|
v
|
|
Business port
|
|
^
|
|
| implements / binds
|
|
|
|
|
Feature-owned adapter binding
|
|
|
|
|
| generic type + mapper/codec + policy
|
|
v
|
|
Reusable capability runtime
|
|
|
|
|
v
|
|
Browser / network / native API
|
|
|
|
use case는 platform adapter를 절대 import하지 않는다. 범용 바인딩은 feature의
|
|
adapter·조립 이음매(seam)에서 일어난다.
|
|
|
|
## capability별 타입 바인딩
|
|
|
|
HTTP, storage, realtime, transfer를 하나의 범용 `Repository<TKey, TValue>`
|
|
추상화로 묶지 않는다. 넷은 lifecycle과 실패의 의미가 서로 다르다.
|
|
|
|
재사용 capability 경계는 다음으로 조립한다:
|
|
|
|
- 범용 입력·출력 타입,
|
|
- feature가 소유한 mapper 또는 codec,
|
|
- feature가 고른 정책,
|
|
- capability 전용 runtime 하나.
|
|
|
|
HTTP 경로가 첫 구체 예다.
|
|
`src/adapters/http/feature-http-binding.ts`가 전송과 결과의 정규화를 맡는다.
|
|
`create:feature`가 만든 feature가 내놓는 것은 다음뿐이다:
|
|
|
|
- operation ID,
|
|
- route ID,
|
|
- 정확한 요청 입력 타입,
|
|
- 정확한 성공 값 타입,
|
|
- wire 형식을 domain으로 바꾸는 mapper.
|
|
|
|
그래서 feature gateway는 timeout, 취소, 전송 실패, 인증 실패, contract 위반
|
|
투영을 다시 구현하지 않는다.
|
|
|
|
storage, realtime, transfer는 실제 feature에서 반복이 생겨 필요가 드러난
|
|
뒤에야 자기 타입 바인더를 가질 수 있다. 이 셋을 HTTP 추상화에 억지로
|
|
끼우면 안 된다.
|
|
|
|
## 직접 만드는 adapter라는 탈출구
|
|
|
|
제품 feature는 재사용 capability가 비즈니스 요구를 지켜 줄 때 그 capability를
|
|
쓴다.
|
|
|
|
platform contract 때문에 비즈니스 모델을 바꾸거나 약하게 해야 한다면, feature는
|
|
같은 application port 뒤에 직접 만든 outbound adapter를 구현한다. 아키텍처
|
|
경계는 그대로다. platform 재사용은 선택이다.
|
|
|
|
## feature 설치
|
|
|
|
feature는 자기 contract, runtime, adapter contribution을 소유한다.
|
|
|
|
중앙의 설치 목록(catalog)은 모으는 지점일 뿐이다:
|
|
|
|
- `installed-product-manifest.ts`: 어떤 제품 feature를 컴파일하고 고르는지
|
|
- `installed-feature-contracts.ts`: feature 선언에서 boot 시점 contract(라우트,
|
|
라우트 runtime contract, 무효화)를 모은다
|
|
- `installed-feature-adapters.ts`: 활성 feature마다 하나씩 있는
|
|
application-input loader. router가 그 feature의 라우트에 들어갈 때
|
|
실행된다(15-01)
|
|
- `installed-contract-contributions.ts`: 선언된 contract 패키지와, HTTP
|
|
executor가 해석할 때 쓰는 registry. feature가 로드될 때 채워진다
|
|
- `installed-feature-runtime-registries.ts`: 모든 runtime 쪽 절반을 불러와
|
|
contract contribution, 거기서 투영한 FE-REG-API 행, FE-REG-SCHEMA registry를
|
|
조립한다. platform 개요 페이지가 제목을 그린 뒤 이 파일을 부른다
|
|
(1103/15-01). boot는 절대 부르지 않는다
|
|
- `loaded-feature-runtimes.ts`: 같은 registry를 모듈 상수(top-level await)로
|
|
둔 것. Node 스크립트, 테스트, registry 관리(governance)가 쓴다. `src` 아래
|
|
어떤 코드도 이 파일을 import하면 안 된다
|
|
(`boot-does-not-load-every-feature-runtime`)
|
|
|
|
feature 전용 조립은 그 feature 아래에 둔다. 중앙 목록에 feature별 분기 로직을
|
|
늘리면 안 된다.
|
|
|
|
adapter contribution은 자기가 쓰는 platform capability를 `needs`로 선언한다.
|
|
`src/features/feature-adapter-contribution.ts`의 범용 contribution 이음매가 그
|
|
목록에서 context를 만든다. 그래서 HTTP만 쓰는 feature는 IndexedDB에 닿지
|
|
못한다. IndexedDB만 쓰는 feature는 HTTP executor를 받지 않는다. 이 이음매는
|
|
`featureId -> ApplicationFeatureInputs[featureId]` 관계도 contribution을
|
|
정의하는 자리에서 묶는다. 마지막에 목록을 타입 캐스트해서 그 관계를 되찾지
|
|
않는다.
|
|
|
|
contribution은 `defineFeatureAdapterContribution()`을 거쳐야만 조립할 수
|
|
있다. 이 factory는 `composeFeatureAdapterInputs()`가 요구하는 비공개
|
|
contribution brand를 붙인다. 겉으로 보이는 필드가 같은 날 객체는 TypeScript가
|
|
거부하고, runtime에서도 다시 검사한다. 음성 타입 fixture
|
|
`invalid-direct-feature-composition.ts`가 FE-GATE-003에 들어 있다. 그래서
|
|
composer를 직접 불러 이 권한을 우회할 수 없다.
|
|
|
|
IndexedDB를 쓰는 feature에서는 `createIndexedDbRepositoryProvider()`가 조립
|
|
헬퍼다. 이 헬퍼는 feature가 소유한 repository 식별자를 타입이 붙은
|
|
`IndexedDbRepositoryPort` 인스턴스에 연결한다. 범용 storage repository를
|
|
만들지 않는다. dataset·migration·lifecycle 정책을 feature로 옮기지도 않는다.
|
|
|
|
지금 repo에는 실행 가능한 contribution 모양이 둘 있다:
|
|
|
|
- `create:feature`가 만드는 feature: `needs: ["http", "telemetry"]`
|
|
- Local Draft consumer: `needs: ["indexedDb"]`
|
|
|
|
Local Draft는 두 번째 capability 모양을 증명하는 테스트
|
|
fixture(`tests/fixtures/indexeddb-consumer`)다. 제품의 feature가 아니다. 그
|
|
browser-capability 테스트는 실제 `createIndexedDbRuntime`과 브라우저 자체
|
|
IndexedDB 위에서 feature를 조립한다. 이 이음매가 메모리 안 contract fixture에만
|
|
묶이지 않는다는 것을 이 테스트가 증명한다.
|
|
|
|
bootstrap은 `indexedDb`를 만들지 않는다. IndexedDB는 골라야 켜지는(opt-in)
|
|
참조 runtime이다(`config/recipes/frontend-capability-recipes.json`의
|
|
`productionComposition: false`). 조립 예시는
|
|
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`다
|
|
(`createLocalDraftIndexedDbCapability`. 이 함수는
|
|
`tests/recipes/indexeddb-feature-capability.test.ts`가 실행해 본다).
|
|
`needs: ["indexedDb"]`인 feature를 설치하는 제품은 이 예시를 복사한다. 그리고
|
|
제품이 소유한 `src/bootstrap/product-composition.ts`에서 `indexedDb`를
|
|
돌려준다. 그 전까지는 `src/bootstrap/runtime-adapters.ts`의 feature
|
|
capability가 앱 타입체크에서 실패한다. 그리고 `composeFeatureAdapterInputs()`가
|
|
`feature <id> needs indexedDb, which the host did not provide`로 조립을
|
|
거부한다.
|
|
|
|
제품이 다른 capability를 더하는 곳도 같은 파일이다. 제품 인증 profile의
|
|
credential provider를 더하는 곳도 이 파일이다. capability의 타입은 제품이
|
|
소유한 `src/features/product-capabilities.ts`에 둔다
|
|
(`ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities`가 이
|
|
타입을 확장한다). 그래서 feature를 보는 모든 타입체크 프로그램이 이 타입도
|
|
본다(`tests/unit/product-extension-typecheck.test.ts`). composition root는 다음
|
|
순서를 지킨다: scope fence, `ANONYMOUS` profile, 제품 provider, session, 다시
|
|
scope fence(`tests/unit/runtime-adapters-credential-order.test.ts`). session을
|
|
직접 소유하는 제품(session이 httpOnly 쿠키인 BFF)은 같은 파일의
|
|
`composeProductSessionOwner`에서 자기 session owner를 돌려준다. 이 함수는
|
|
`AUTH_MODE`가 `external`일 때만 불린다. 불릴 때는 `http`가 생기기 전에 가장
|
|
먼저 불리고, host의 `__CA_FRONTEND_AUTH_OWNER__`보다 앞선다. `null`을
|
|
돌려주면 session을 그 전역 값에 맡긴다. 이 함수의 context
|
|
(`src/bootstrap/product-session-owner-context.ts`)에는 다음이 들어 있다: 교환
|
|
전체에 deadline 하나를 거는 `fetch`, 로그인 redirect에 쓸 페이지, 그
|
|
redirect에만 쓰는 페이지의 session storage, `readCookie`. 제품 인증 profile,
|
|
runtime-config 키, 그 키의 FE-REG-ENV 행은 `src/contracts/product-contracts.ts`에
|
|
둔다. 각각 같은 검사를 거쳐 템플릿의 registry에 합류한다
|
|
(`tests/unit/product-composition-fixture.test.ts`).
|
|
|
|
## presentation 소비 표면
|
|
|
|
`ApplicationProvider`는 계속 presentation의 composition root다. 하지만 새
|
|
소비 코드는 루트 `ApplicationApi` service locator를 뒤져서 기능을 찾아가면
|
|
안 된다.
|
|
|
|
`src/presentation/providers/application-provider.tsx`의 좁은 hook을 쓴다:
|
|
|
|
- `useApplicationSession`
|
|
- `useApplicationPreferences`
|
|
- `useApplicationDiagnostics`
|
|
- `useApplicationRuntime`
|
|
- `useApplicationRecovery`
|
|
- `useApplicationFeature`
|
|
|
|
`useApplication`은 deprecated된 호환용 탈출구로만 남아 있다.
|
|
|
|
## 정식 import 경로
|
|
|
|
새 feature 코드는 깊은 runtime 모듈 대신 capability의 공개 진입점을 쓴다.
|
|
HTTP의 정식 경로는 `src/adapters/http/index.ts`다.
|
|
|
|
옮기는 기간에는 호환용 재수출이 있을 수 있다. 하지만 그 경로에는 호환용·
|
|
deprecated 경로라는 표시를 해야 한다. 그리고 끝없이 커지는 공개 barrel로
|
|
늘어나면 안 된다.
|
|
|
|
## 정책 소유
|
|
|
|
중복은 문법이 겹치는 비율이 아니라 소유로 판단한다.
|
|
|
|
가까이 두는 편이 감사하기 쉬우면 작은 로컬 검증기는 중복으로 남겨도 된다.
|
|
비즈니스 정책이나 동시성 정책은 owner가 하나여야 한다. 예를 들어 참조 create
|
|
mutation은 정의 ID, 멱등성 요구, 중복 정책, 무효화 정책을 feature가 소유한
|
|
정의 하나에 둔다. 사용하는 자리마다 묶는 것은 `scope`와 `execute`뿐이다.
|
|
|
|
## runtime 분해 규칙
|
|
|
|
큰 runtime 파일을 줄 수로 나누지 않는다.
|
|
|
|
경계에 자기만의 상태 기계, lifecycle owner, 실패 모델, 보상·복구 책임이
|
|
있으면 그 경계를 떼어 낸다. 떼어 낼 후보 이음매는 다음과 같다:
|
|
|
|
- 연결·열기·업그레이드 lifecycle,
|
|
- 트랜잭션 소유,
|
|
- migration 상태 기계,
|
|
- 재연결·backoff와 heartbeat,
|
|
- 구독 소유,
|
|
- 재시도·deadline·취소 소유,
|
|
- 정산(settlement)·조정(reconciliation)·정리(cleanup).
|
|
|
|
응집된 2,000줄짜리 상태 기계는 한데 둬도 된다. lifecycle owner가 여럿인
|
|
300줄짜리 파일이 더 나은 분리 후보다.
|
|
|
|
### 지금 runtime 경계 점검
|
|
|
|
지금 있는 큰 runtime 목록을 이 규칙으로 점검했다.
|
|
|
|
- IndexedDB는 여전히 크다. 하지만 연결, 트랜잭션, migration, 유지보수, 실패
|
|
변환은 이미 owner·모듈이 따로 있다.
|
|
- 이어 올리기(resumable upload)는 이미 runtime 정책, checkpoint 저장, HTTP
|
|
제어 평면 전송, 조각(part) 실행, 취소, mutation 잠금을 나눠 두었다.
|
|
- realtime은 이미 재연결 정책·조정자, 이벤트 codec·소비자, 스트림 조정을
|
|
나눠 두었다.
|
|
- OPFS는 브라우저 runtime, journal, byte-store, 정책, worker 프로토콜·runtime
|
|
책임으로 나뉘어 있다.
|
|
- HTTP V3는 재시도 가능 여부와 backoff를 실행 상태 기계 안에서 여전히 소유하고
|
|
있었다. 그래서 그 책임을 `src/adapters/http/http-retry-lifecycle.ts`로
|
|
옮겼다.
|
|
|
|
다른 runtime은 줄 수만 보고 나누지 않았다.
|
|
|
|
## 소비 품질 지표
|
|
|
|
추상화를 하나 더 들이기 전에, 실제 feature 사용 사례 여럿을 구현하거나
|
|
모델링하고 다음을 잰다:
|
|
|
|
- feature가 소유한 adapter LOC,
|
|
- 반복되는 platform 접착 코드(glue),
|
|
- feature에 드러나는 platform 내부 타입 수,
|
|
- 중앙 목록 수정 횟수,
|
|
- 평범한 query/command 하나에 바뀌는 파일 수,
|
|
- 브라우저·네트워크 기본 API가 feature로 새어 나오는지.
|
|
|
|
목표로 하는 feature 개발 경로는 다음과 같다:
|
|
|
|
1. domain 타입과 불변식,
|
|
2. use case,
|
|
3. port,
|
|
4. 전송·저장 schema와 mapper/codec,
|
|
5. capability 바인딩,
|
|
6. presentation controller/page.
|
|
|
|
제품 feature는 재시도 스케줄러, abort 소유, 효과 확실성(effect-certainty) 장치,
|
|
트랜잭션 lease, 재연결 조정자, OPFS journal, provider lifecycle을 몰라도 돼야
|
|
한다.
|
|
|
|
실행 가능한 REST·IndexedDB 소비 기준선은
|
|
[`capability-consumer-experience.md`](./capability-consumer-experience.md)에
|
|
적혀 있다. contract를 어디에 둘지와, 전역에 둘지 owner 가까이 둘지 점검한
|
|
결과는 [`contract-ownership.md`](./contract-ownership.md)에 적혀 있다.
|
|
|
|
## 검증 경로
|
|
|
|
제품 개발 검증, capability 검증, release 보증은 일부러 나눠 두었다.
|
|
[`docs/testing/taxonomy.md`](../testing/taxonomy.md)를 본다.
|
|
|
|
host 수준 CI runner 테스트는 `tests/unit`이 아니라 `tests/system`에 둔다.
|
|
재사용 capability의 소비 contract는 `tests/contract`에 둔다.
|