From 68342e25ce47f812d06b6df73aefc848efcc4516 Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Sun, 26 Jul 2026 02:09:06 +0900 Subject: [PATCH] docs: audit frontend platform capabilities --- README.md | 19 + .../frontend-platform-capability-review.md | 447 ++++++ ...rontend-platform-implementation-roadmap.md | 954 ++++++++++++ .../frontend-ports-adapters-and-boundaries.md | 1253 ++++++++++++++++ docs/architecture/layers.md | 8 + docs/architecture/overview.md | 47 +- .../routing-pages-and-patterns.md | 492 +++++++ docs/architecture/starter-experience.md | 10 +- .../typescript-state-and-data-flow.md | 549 +++++++ docs/styling/design-system-platform.md | 868 +++++++++++ docs/styling/design-tokens.md | 7 + .../frontend-platform-testing-strategy.md | 1283 +++++++++++++++++ docs/testing/taxonomy.md | 7 + 13 files changed, 5934 insertions(+), 10 deletions(-) create mode 100644 docs/architecture/frontend-platform-capability-review.md create mode 100644 docs/architecture/frontend-platform-implementation-roadmap.md create mode 100644 docs/architecture/frontend-ports-adapters-and-boundaries.md create mode 100644 docs/architecture/routing-pages-and-patterns.md create mode 100644 docs/architecture/typescript-state-and-data-flow.md create mode 100644 docs/styling/design-system-platform.md create mode 100644 docs/testing/frontend-platform-testing-strategy.md diff --git a/README.md b/README.md index 43bcad9..0c67f8c 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,25 @@ See `docs/architecture/overview.md`, `docs/architecture/layers.md`, and visible starter routes do not depend on that fixture and continue to build after it is removed. +### Platform capability review + +The starter shell is implemented, but the repository review also records the +remaining work required before feature teams can use every declared contract +through one end-to-end application path: + +- [platform capability review](docs/architecture/frontend-platform-capability-review.md) +- [ports, adapters, and feature boundaries](docs/architecture/frontend-ports-adapters-and-boundaries.md) +- [TypeScript, state ownership, and data flow](docs/architecture/typescript-state-and-data-flow.md) +- [routing, page templates, and reusable patterns](docs/architecture/routing-pages-and-patterns.md) +- [design-system platform](docs/styling/design-system-platform.md) +- [frontend platform testing strategy](docs/testing/frontend-platform-testing-strategy.md) +- [implementation roadmap](docs/architecture/frontend-platform-implementation-roadmap.md) + +These documents distinguish repository defaults from opt-in adapters and +project-owned integrations. They are target designs and review findings; a +capability is not treated as implemented until its branch acceptance criteria +and executable gates pass. + ## Verification Common local checks: diff --git a/docs/architecture/frontend-platform-capability-review.md b/docs/architecture/frontend-platform-capability-review.md new file mode 100644 index 0000000..bbf50d2 --- /dev/null +++ b/docs/architecture/frontend-platform-capability-review.md @@ -0,0 +1,447 @@ +# 프론트엔드 플랫폼 역량 재검토 + +## 1. 문서 목적 + +이 문서는 도메인 기능과 실제 운영 환경의 배포 증적을 제외하고, 이 저장소가 새 +프론트엔드 제품의 출발점으로 제공해야 하는 공통 역량을 다시 평가한다. 평가 +기준은 다음과 같다. + +- 코드나 설정 파일이 존재하는지만 보지 않는다. +- 부트스트랩부터 화면까지 실제 호출 경로가 연결되는지 확인한다. +- 선언한 레지스트리와 정책이 런타임 및 CI에서 집행되는지 확인한다. +- 기본 번들에 포함할 역량과 필요할 때 설치할 확장 역량을 구분한다. +- 특정 벤더를 채택하더라도 제품 코드가 벤더 API에 직접 결합되지 않는지 확인한다. + +검토 기준 브랜치는 `develop`, 기준 커밋은 `cb195f8`이다. 이후 구현으로 경로나 +세부 내용이 달라질 수 있으므로, 각 항목은 문서의 경로뿐 아니라 해당 테스트와 +아키텍처 게이트로 계속 검증해야 한다. + +## 2. 결론 + +현재 저장소는 다음 기반이 강하다. + +- 런타임 설정과 릴리스 매니페스트 검증 +- 도메인, 애플리케이션, 프레젠테이션, outbound adapter의 의존 방향 +- 공통 HTTP 실패 형태와 제한된 retry 정책 +- 앱 셸, 반응형 내비게이션, 테마, 비동기 상태 표면 +- Vitest, Testing Library, MSW, Playwright, axe를 이용한 테스트 계층 +- CI 게이트 taxonomy와 호환성·보안·성능·릴리스 계약 문서 + +그러나 “도메인 기능을 바로 추가할 수 있는 프론트엔드 플랫폼” 기준으로는 아직 +중요한 연결부가 빠져 있다. 가장 큰 문제는 공통 기능이 없다는 것보다 이미 있는 +기능이 실제 기능 화면의 표준 호출 경로로 조립되지 않았다는 점이다. + +특히 다음은 선행 해결이 필요하다. + +1. React 화면이 호출할 application input API와 런타임 주입 경계 +2. TanStack Query를 사용하는 표준 query/mutation inbound adapter +3. TypeScript 전환 전에 TS 파일까지 검사하도록 만드는 도구 안전망 +4. path/query/body projection과 runtime timeout/retry가 정확히 연결된 HTTP 계층 +5. 선언과 실행이 일치하는 typed route 계약 +6. 전체를 제거할 수 있는 실제 reference feature +7. 폼, 페이지 템플릿, 확장된 디자인 시스템과 컴포넌트 워크벤치 + +따라서 현재 상태를 “프론트 공통부가 모두 구현됐다”고 표현하면 범위가 과장된다. +더 정확한 표현은 다음과 같다. + +> 운영·안전 계약과 범용 앱 셸은 갖춰졌지만, 기능 개발자가 사용하는 application +> API, 서버 상태, 폼, 라우팅, 페이지 패턴의 표준 수직 경로는 아직 보강이 +> 필요하다. + +## 3. 판정 기준 + +| 판정 | 의미 | +| --- | --- | +| 준비됨 | 구현, 실제 조립, 자동 검증이 모두 존재한다. | +| 부분 준비 | 핵심 구현은 있으나 실제 호출 경로, 정책 집행, 예제가 불완전하다. | +| 미제공 | 새 기능을 만들 때 팀이 직접 선택·설계해야 한다. | +| 프로젝트 선택 | 기본 번들에 강제하면 비용이 더 크며, 경계와 recipe만 제공한다. | + +## 4. 역량 매트릭스 + +| 영역 | 현재 판정 | 근거 | 필요한 다음 상태 | +| --- | --- | --- | --- | +| 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 | +| 계층 의존 방향 | 부분 준비 | `.dependency-cruiser.cjs`, `src/application/ports` | inbound/outbound 명명과 `contracts` 소유권까지 집행 | +| application facade | 부분 준비 | `create-application.js`는 있으나 `main.jsx`에서 우회 | UI에는 input API만 주입 | +| HTTP client | 부분 준비 | timeout, abort, retry, auth, envelope, Zod가 존재 | path/query, parsed body, runtime 설정, 정리 로직 보완 | +| retry | 부분 준비 | safe/keyed 요청 정책 존재 | retry 소유자 단일화, 설정 연결, telemetry | +| 오류 모델 | 부분 준비 | error registry와 normalization 존재 | typed discriminated union과 계층별 mapper | +| 검증 | 부분 준비 | runtime/API Zod 존재 | route/form/domain 경계를 분리하고 실제 parse 결과 사용 | +| 인증 연동 | 준비됨/프로젝트 선택 | opaque auth owner와 demo seam 존재 | 인증 방식별 recipe; 기본 token 저장소는 추가하지 않음 | +| 서버 상태 | 미제공에 가까운 부분 준비 | QueryClientProvider와 cache port는 존재 | query/mutation hook과 화면 reference flow | +| 클라이언트 상태 | 부분 준비 | local state, theme context, session external store | 상태 소유권 표와 typed external-store 예제 | +| 범용 global store | 프로젝트 선택 | 별도 라이브러리 없음 | 필요 조건에 따라 Zustand/Redux Toolkit/state machine 선택 | +| 라우팅 | 부분 준비 | lazy route, access hint, registry 존재 | typed runtime map, codec, recovery, metadata 집행 | +| 앱 셸·반응형 | 부분 준비 | header/sidebar/content/theme 구현 | 접근 가능한 mobile drawer와 focus 복원 | +| 페이지 템플릿 | 미제공 | 각 페이지가 직접 레이아웃 조립 | list/detail/form/status 등 슬롯 기반 템플릿 | +| 디자인 토큰 | 부분 준비 | semantic color/theme 토큰 존재 | typography, spacing, motion, layer 등 3단계 토큰 | +| 공통 UI | 부분 준비 | Button, TextField, Card, Alert, Badge, Dialog | form/navigation/overlay/data/layout primitives 확장 | +| 아이콘 | 미제공 | 문자 기호를 직접 사용 | Lucide를 로컬 icon facade 뒤에서 사용 | +| 폼 | 미제공 | 수동 문자열 검증 예제만 존재 | schema 기반 form facade와 422/dirty/pending 정책 | +| 국제화 | 미제공 | 한국어 문자열·locale이 하드코딩 | typed message/formatter/locale/RTL 경계 | +| logging/diagnostics | 미제공 | telemetry port는 있으나 logger 없음 | redaction이 적용된 diagnostics/logging 경계 | +| telemetry | 부분 준비 | registry, queue, redaction 존재 | HTTP·boot·cache·storage·route 사건에 실제 연결 | +| 비동기 상태 불변식 | 부분 준비 | 공통 model/surface는 있으나 일부 모순 상태를 허용 | query/mutation 상태 조합과 action latch를 닫음 | +| 단위·통합·E2E | 준비됨 | Vitest, RTL, MSW, Playwright 3엔진 | TS 테스트 검사, 실제 bootstrap 통합, 위험 시나리오 보강 | +| UI 회귀 검증 | 미제공 | axe/reflow는 있으나 visual baseline 없음 | Storybook 또는 동급 workshop과 시각 회귀 | +| 샘플 제거 | 부분 준비 | fixture 제거 테스트 존재 | sample domain/registry/runtime 전체 제거 검증 | +| registry·compatibility 집행 | 부분 준비 | registry와 gate는 있으나 실제 before/after 및 orphan 검사가 제한적 | type/reference/orphan/diff/migration을 자동 검증 | +| 공급망 검사 | 부분 준비 | lockfile·문서·gate는 있으나 실제 transitive 취약점/license/SBOM 깊이가 부족 | pinned scanner와 policy exception/증적 연결 | +| realtime·offline·file 등 | 프로젝트 선택 | 현재 없음 | port/adapter recipe와 선택 기준 제공 | + +## 5. 우선순위별 발견 사항 + +### 5.1 P0: 기능 개발을 막는 항목 + +#### application 계층이 런타임에서 우회된다 + +`src/bootstrap/composition-root.js`는 application을 생성하지만 +`src/bootstrap/main.jsx`는 이를 라우터에 주입하지 않는다. UI에는 auth, storage, +telemetry 같은 raw outbound dependency와 concrete QueryClient가 전달된다. +`src/application/create-application.js`도 use case 중심 input API보다 outbound +capability를 다시 노출하는 형태다. + +목표 상태: + +- `Application`은 UI가 호출할 query/command use case를 제공한다. +- `ApplicationProvider`는 이 API만 React tree에 제공한다. +- 페이지는 HTTP, storage, auth SDK, telemetry sink를 직접 호출하지 않는다. +- bootstrap만 concrete outbound adapter를 알고 조합한다. +- 실제 bootstrap부터 reference page까지 연결한 통합 테스트가 있다. + +#### 서버 상태 라이브러리는 마운트됐지만 사용할 수 없다 + +`QueryClientProvider`는 존재하지만 저장소의 제품 코드에서 `useQuery`와 +`useMutation`을 사용하지 않는다. 동시에 presentation의 `@tanstack/**` import는 +금지돼 있다. 현재 `QueryCachePort`는 명령형 read/write/invalidate만 제공하여 +React 구독, 요청 상태, cancellation, optimistic update를 대신할 수 없다. + +목표 상태: + +- canonical target인 `src/adapters/inbound/react/platform/query`에 벤더 연동을 + 한정한다. 마이그레이션 중에는 기존 `presentation`을 같은 inbound 경계로 + 취급하되 새 대체 경로를 만들지 않는다. +- `useApplicationQuery`, `useApplicationMutation` 또는 같은 역할의 typed + controller hook을 제공한다. +- HTTP retry와 query retry 중 한 계층만 재시도 책임을 갖는다. +- loading, empty, refreshing, stale, offline, error, conflict, optimistic rollback을 + reference feature에서 보여 준다. + +#### TypeScript 전환 전에 검사 도구가 TS를 인식해야 한다 + +현재 source는 모두 JS/JSX이고 `strict + allowJs + checkJs`를 사용한다. 이는 좋은 +중간 안전망이지만 다음 도구는 TS migration을 그대로 따라가지 못한다. + +- ESLint의 계층·보안 glob은 JS/JSX 중심이다. +- registry scanner는 `.ts`와 `.tsx`를 찾지 않는다. +- registry governance 경로가 `.js` 확장자로 고정되어 있다. +- tests는 현재 `tsconfig.json` 검사 범위에서 빠진다. + +따라서 파일 확장자를 먼저 바꾸면 새 TS 코드가 일부 자동 검사에서 빠질 수 있다. +TypeScript 전환은 +[TypeScript의 JavaScript migration 가이드](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) +처럼 점진적으로 진행하되, 이 저장소에서는 tooling glob과 CI를 먼저 고쳐야 한다. + +#### HTTP 계약에 선언과 실행의 차이가 있다 + +현재 HTTP 계층은 공통화 수준이 높지만 다음 정확성 문제가 남아 있다. + +- runtime config의 `REQUEST_TIMEOUT_MS`, `MAX_RETRY_ATTEMPTS`가 client 생성에 + 전달되지 않는다. +- operation path에 path parameter와 search parameter를 투영하는 표준 builder가 + 없다. +- sample filter는 cache key에만 반영되고 실제 요청 URL에는 반영되지 않는다. +- Zod의 parsed/transformed request body 대신 원본 body를 전송한다. +- request validation의 조기 반환 경로에서 timeout/listener 정리가 늦어진다. +- HTTP failure, retry, recovery가 telemetry 사건과 이어지지 않는다. + +client를 거대한 범용 함수로 계속 확장하지 말고 transport, request builder, auth, +timeout, retry, decoder, mapper 책임을 분리해야 한다. application에는 범용 HTTP +메서드보다 feature가 요구하는 gateway interface를 노출한다. + +#### route registry가 실행 계약이 아니다 + +route registry에는 `paramsSchema`, `searchSchema`, `loadingSurface`, +`errorSurface`, `chunkId`가 있지만 실제 router tree, lazy module, navigation +목록은 별도로 작성된다. 여러 필드는 선언만 되고 런타임에 사용되지 않는다. +chunk recovery use case와 redirect loop guard도 실제 route flow에 연결되지 않는다. + +목표 상태: + +- serializable contract와 executable runtime map을 분리한다. +- `satisfies Record`로 양방향 완전성을 검사한다. +- params/search는 Zod codec으로 경계에서 parse하고 URL builder도 같은 codec을 + 사용한다. +- loading/error/chunk/access/title/navigation metadata를 실제 route object에 + 연결한다. +- route change 시 boundary reset, focus, scroll, navigation cancellation을 + 검증한다. + +#### reference feature가 완전히 제거되지 않는다 + +현재 sample removal gate는 `src/sample/contract-fixture`만 삭제한다. sample API +operation, schema, mapper, domain model, query key는 다른 production 경로에 남는다. +반면 화면에 노출된 `/sample/resources`는 실제 query 수직 흐름을 실행하지 않는다. + +reference feature는 domain, application input/output, schemas, operation, +mapper, query controller, pages, tests를 한 소유 경계 아래 모아야 한다. 해당 모듈과 +registry contribution을 제거한 뒤 typecheck, architecture, test, build가 모두 +통과해야 “제거 가능”으로 판정한다. + +#### 비동기·복구 상태의 불변식이 닫혀 있지 않다 + +공통 async model과 gallery가 있지만 선언 가능한 상태 조합 중 일부는 사용자 +행동과 모순될 수 있다. stale data가 있는 degraded 상태와 refreshing, mutation +pending과 conflict, retry button과 실제 handler 존재 여부를 typed state로 +닫아야 한다. 상태를 boolean 여러 개로 조합하지 않고 다음과 같은 discriminated +state와 action capability로 표현한다. + +```text +initial-loading +ready +refreshing-with-data +empty +degraded-with-data +terminal-error +mutation-pending +mutation-conflict +``` + +chunk recovery와 release coherence도 policy 함수가 존재하는 것으로 완료되지 +않는다. 실제 lazy import failure가 manifest 재확인, build 비교, 단 한 번의 guarded +reload, 반복 실패 지원 표면까지 이어지고 E2E로 검증되어야 한다. + +#### telemetry, registry, 공급망 gate의 실행 깊이가 부족하다 + +telemetry registry에는 여러 사건이 있지만 실제 production producer는 제한적이다. +boot, API attempt/final failure, auth recovery, storage/cache degradation, release/chunk +recovery를 registry 사건에 연결해야 한다. + +registry/compatibility 검사는 다음까지 확장한다. + +- ID와 enum/type의 양방향 완전성 +- referenced schema/message/token의 존재 +- 실행 코드에서 소비되지 않는 orphan 항목 +- 기준 commit과 현재 commit 사이의 실제 contract diff +- breaking change의 version/migration/rollback metadata + +공급망 검사는 단순 문자열 secret 탐지에 머물지 않고 transitive dependency, +known vulnerability, license policy, SBOM/provenance를 pinned tool로 검사해야 한다. +도구 장애와 취약점 발견을 구분하고, 예외에는 owner·사유·만료일을 요구한다. + +### 5.2 P1: 공통 플랫폼 기본 제공 항목 + +- schema 기반 form facade와 field/error/pending/dirty/422 정책 +- standard, collection, detail, form, status page template +- 접근 가능한 drawer, menu, popover, select 같은 interaction primitive +- token → primitive → pattern → template로 이어지는 디자인 시스템 +- Lucide를 감싼 local icon registry와 `IconButton` +- typed message key, locale provider, formatter, pseudo-locale/RTL smoke +- redacted structured diagnostics/logger와 telemetry wiring +- Storybook 또는 동급 isolated UI workshop +- Playwright visual baseline, shared MSW scenarios, built-dist E2E +- React Hooks, JSX accessibility, TanStack Query 관련 lint +- source와 tests를 모두 포함하는 TypeScript project references +- registry/compatibility의 실제 diff와 orphan reference 검사 +- transitive vulnerability, license, SBOM/provenance 공급망 gate + +### 5.3 P2: 경계와 recipe를 제공할 선택 항목 + +다음 기능을 모든 앱의 초기 번들에 설치할 필요는 없다. 대신 port 또는 local +vendor facade, 선택 조건, 실패 정책, 테스트 fixture를 문서로 제공한다. + +| capability | 대표 기술 | 기본 제공할 경계 | 실제 설치 조건 | +| --- | --- | --- | --- | +| realtime | WebSocket, SSE | subscribe/unsubscribe, reconnect, resume, heartbeat | 서버가 push event를 제공할 때 | +| offline storage | IndexedDB | versioned repository, migration, quota failure | offline read/write가 제품 요구일 때 | +| background/cache | Service Worker, PWA | cache ownership, update, rollback recipe | installable/offline 앱일 때 | +| file transfer | presigned HTTP, multipart | progress, cancel, size/type validation | 업로드·대용량 다운로드가 있을 때 | +| generated API | OpenAPI, GraphQL, gRPC-Web | generated client를 gateway 뒤에 감싸는 규칙 | 서버 계약 형식이 확정됐을 때 | +| feature flag | local/remote flag provider | typed flag key, default, stale behavior | staged rollout가 필요할 때 | +| worker | Web Worker | request/result/cancel protocol | UI thread를 막는 CPU 작업이 있을 때 | +| multi-tab | BroadcastChannel | event versioning, source ID, conflict policy | 탭 간 동기화가 필요할 때 | +| browser capability | clipboard, notification, media | permission/result port | 해당 UX가 있을 때 | +| client workflow | Zustand, Redux Toolkit, state machine | state ownership decision과 local facade | cross-feature workflow가 실제로 생길 때 | +| large data UI | virtualization, data grid | owned component facade | 데이터 규모가 측정 기준을 넘을 때 | +| analytics/error sink | vendor SDK, OpenTelemetry | redaction, consent, sampling adapter | 운영 provider와 정책이 정해졌을 때 | + +서버의 Redis, MongoDB, PostgreSQL, MinIO를 브라우저가 직접 연결하는 구조는 기본 +frontend adapter catalog에 넣지 않는다. 브라우저는 권한 있는 backend API/BFF를 +통해 이 자원에 접근해야 한다. 프론트에서 대응되는 변화 지점은 데이터베이스 +vendor가 아니라 HTTP/GraphQL/gRPC-Web, realtime, file transfer, cache, storage, +worker, browser capability 같은 프로토콜·런타임 capability다. + +### 성능 최적화는 모두 adapter 문제인가 + +아니다. 먼저 측정하고 병목의 소유 계층에 맞는 수단을 적용한다. + +| 문제 | 기본 제공할 수단 | adapter/facade가 필요한 경우 | +| --- | --- | --- | +| 초기 JS가 큼 | route/feature lazy loading, bundle budget, dependency inventory | remote module이나 별도 delivery 전략이 있을 때 | +| 중복 네트워크 | TanStack deduplication/cache, abort, bounded retry | offline cache나 generated client를 교체할 때 | +| 느린 화면 전환 | prefetch policy, stable shell, cached-data surface | route별 prefetch provider가 필요할 때 | +| 긴 main-thread task | profiler 기준으로 계산 분리 | Web Worker message adapter | +| 대량 목록 | pagination과 server filter를 우선 | virtualizer/data-grid facade | +| 이미지 전송량 | width/height, lazy loading, responsive source 규칙 | Image CDN URL builder adapter | +| 재방문/offline | HTTP cache contract | Service Worker/IndexedDB adapter | +| 불필요한 render | 상태 소유권 축소와 component boundary | 보통 adapter가 아니며 측정 후 memoization | + +기본 skeleton은 bundle budget, lazy route, query cancellation/cache, responsive +image 규칙, stable layout, lab performance test를 제공한다. Web Worker, +virtualization, Image CDN, Service Worker는 실제 병목과 제품 요구가 확인될 때 +설치한다. 라이브러리를 미리 많이 넣는 것은 최적화가 아니라 초기 번들·공급망 +표면을 늘리는 일이 될 수 있다. + +## 6. 질문별 직접 답변 + +### 프론트도 inbound/outbound로 나누는가 + +나눈다. 현재 구조에서는 `presentation`이 사실상 inbound adapter이고 +`src/adapters`가 outbound adapter다. 이름과 문서가 이 역할을 명확히 드러내지 +않아 모두 같은 adapter처럼 보인 것이다. + +| 역할 | 프론트 예 | +| --- | --- | +| input/inbound port | `ListResources`, `CreateResource` 같은 application API | +| inbound adapter | React page/controller, router, form event, push-event translator | +| output/outbound port | resource gateway, session, storage, clock, diagnostics | +| outbound adapter | HTTP, auth SDK, browser storage, TanStack cache, telemetry sink | + +React, router, form library, icon library마다 application port를 만들 필요는 없다. +UI 내부 교체만 필요한 라이브러리는 React inbound adapter 내부 vendor facade로 +충분하다. port는 application 정책과 외부 소유권 사이의 경계에 둔다. + +### 왜 현재 모두 `adapters` 아래에 있는가 + +실제로 모두 있지는 않다. UI driver가 `presentation`이라는 이름으로 분리돼 있고, +`adapters`에는 주로 outbound 구현이 있다. 다만 다음 두 대안 중 하나를 명시적으로 +선택해야 한다. + +1. 변경량을 줄여 `presentation = inbound adapter`로 문서화하고 + `adapters/outbound`만 명시한다. +2. TypeScript/feature migration과 함께 `adapters/inbound/react`와 + `adapters/outbound`로 재구성한다. + +이 저장소는 input API 부재와 flat contracts 문제도 함께 고쳐야 하므로 두 번째 +구조가 장기적으로 더 명확하다. 단, 대규모 rename 자체를 기능 개선으로 세지 말고 +architecture gate와 수직 reference feature가 먼저 또는 같은 브랜치에서 +증명되어야 한다. + +### TypeScript로 바꾸는 것이 좋은가 + +좋다. 특히 registry ID, Result/error union, port generic, route params/search, +component variant를 컴파일 시점에 닫을 수 있다. 다만 일괄 rename은 권장하지 +않는다. tooling → core contracts → application ports/use cases → outbound → +bootstrap → React TSX → tests 순서로 이동한다. + +### store 기본 설정이 필요한가 + +상태 전략은 기본 제공해야 하지만 범용 global store dependency는 필수로 넣지 +않는다. + +- local interaction: `useState`/`useReducer` +- shareable navigation state: URL +- server state: TanStack Query +- form state: form facade +- low-frequency cross-cutting state: context 또는 typed external store +- complex cross-feature workflow: Zustand/Redux Toolkit/state machine 중 선택 +- persistence: `StoragePort` + +서버 데이터를 global store에 복사하지 않는 규칙이 중요하다. +[TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview), +[Redux Toolkit](https://redux-toolkit.js.org/introduction/getting-started), +[Zustand](https://zustand.docs.pmnd.rs/)의 역할은 서로 같지 않다. + +### retry, API client, logger, token manager, error, validation은 어디에 있는가 + +- retry: `src/adapters/http/retry-policy.js`, 부분 준비 +- API client: `src/adapters/http/client.js`, 부분 준비 +- logger: 없음. telemetry와 분리하거나 diagnostics port로 합치는 결정 필요 +- token manager: 의도적으로 없음. opaque external auth owner가 credential을 소유 +- error: `src/contracts/errors.js`와 HTTP normalization, 부분 준비 +- validation: runtime/API Zod는 존재, route/form/domain 분리는 미완성 + +token manager를 기본으로 추가하지 않는 이유는 token lifecycle이 인증 방식마다 +다르고 localStorage token을 일반 해법으로 만들면 보안 위험이 커지기 때문이다. +BFF HttpOnly cookie 또는 OIDC/Auth SDK가 credential을 소유하도록 두고, SPA +memory token이 필요한 프로젝트만 auth adapter를 추가한다. + +### Lucide React를 쓰면 디자인 시스템이 되는가 + +아니다. [Lucide React](https://lucide.dev/guide/packages/lucide-react)는 +tree-shakable SVG icon source로 적절하지만 select, dialog, menu, focus management +같은 UI behavior는 제공하지 않는다. Lucide는 local icon facade 뒤에 두고, +복잡한 interaction은 [Radix Primitives](https://www.radix-ui.com/primitives/docs/overview/introduction) +또는 React Aria 계열과 같은 headless primitive를 owned wrapper 뒤에서 선택한다. + +### 테스트는 현재 어떤 상태인가 + +테스트 도구 구성은 강한 편이다. 다만 다음이 빠져 있다. + +- TS source와 test 전체 typecheck +- 실제 composition root부터 page까지의 통합 +- query/mutation controller와 optimistic rollback +- route registry/runtime map 정합성 +- runtime timeout/retry와 path/query/parsed body +- shared MSW scenario catalog +- isolated component stories와 interaction test +- stable-environment visual regression +- built `dist` 대상 release E2E +- 위험 기반 coverage gate + +### 라우팅 전략은 무엇이 적절한가 + +현재 client-only clean architecture와 TanStack Query 조합은 유지하되, 목표 +skeleton은 React Router Data Mode의 route object, blocker, scroll restoration, +route error 경계를 사용한다. 서버 상태의 소유자는 계속 application input과 +TanStack Query이며 loader/action이 같은 데이터를 별도로 요청하지 않는다. +[React Router 공식 mode 설명](https://reactrouter.com/start/modes)에 따라 +Framework Mode는 SSR/static generation, route module, framework-owned data +loading을 실제 요구할 때만 선택한다. + +### 바로 쓸 수 있는 디자인 패턴은 무엇을 제공해야 하는가 + +패턴 이름만 나열하지 않고 다음 executable blueprint를 제공해야 한다. + +- page controller: route/form event를 application input으로 변환 +- query/mutation adapter: server state lifecycle을 React에 연결 +- command/query use case: 읽기와 상태 변경 의도를 분리 +- gateway: application이 외부 데이터 소유자를 추상화 +- mapper/anti-corruption layer: transport DTO를 core model로 변환 +- Result + failure mapper: throw와 사용자 메시지 경계를 통제 +- strategy: retry, cache, auth recovery, feature flag 정책 교체 +- observer/external store: session/theme/realtime 구독 +- state machine: 복잡한 workflow에만 선택적으로 사용 +- compound component/headless wrapper: 접근 가능한 복합 UI를 소유 +- page template: layout과 상태 표면을 데이터 소유권에서 분리 + +## 7. 실전 투입 준비 완료 기준 + +막연한 백분율 대신 아래 조건을 모두 자동 또는 명시적 검토로 확인한다. + +1. reference feature가 route → controller → input use case → output gateway → + adapter → mapper → query cache → UI 상태 표면을 통과한다. +2. application input API 외에는 UI에서 outbound dependency에 접근할 수 없다. +3. TypeScript source와 tests가 strict 검사되고 JS 우회 경로가 없다. +4. HTTP path/query/body/auth/timeout/retry/cancel/decode 실패가 계약 테스트된다. +5. typed route registry와 runtime map이 양방향 완전성을 가진다. +6. list/detail/form/status page template과 form error 정책이 준비돼 있다. +7. 디자인 시스템 primitive/pattern이 isolated workshop, interaction, a11y, + visual test를 가진다. +8. sample/reference feature 전체 삭제 후 typecheck/test/build가 통과한다. +9. optional adapter는 설치 조건, 보안 경계, 실패 정책, 테스트 recipe가 있다. +10. 새 feature 추가 문서가 파일 경로, 금지 의존, 실패 상태, 테스트, 검증 명령까지 + 안내한다. + +이 기준은 배포 provider, 실제 인증 tenant, 운영 telemetry vendor, production field +data 같은 프로젝트별 외부 작업을 포함하지 않는다. + +## 8. 관련 상세 문서 + +- [프론트 포트·어댑터와 기능 경계](./frontend-ports-adapters-and-boundaries.md) +- [TypeScript·상태·데이터 흐름](./typescript-state-and-data-flow.md) +- [라우팅·페이지·재사용 패턴](./routing-pages-and-patterns.md) +- [프론트 플랫폼 구현 로드맵](./frontend-platform-implementation-roadmap.md) +- [디자인 시스템 플랫폼](../styling/design-system-platform.md) +- [프론트 플랫폼 테스트 전략](../testing/frontend-platform-testing-strategy.md) diff --git a/docs/architecture/frontend-platform-implementation-roadmap.md b/docs/architecture/frontend-platform-implementation-roadmap.md new file mode 100644 index 0000000..5423921 --- /dev/null +++ b/docs/architecture/frontend-platform-implementation-roadmap.md @@ -0,0 +1,954 @@ +# 프론트엔드 플랫폼 구현 로드맵 + +## 1. 목적과 준비 완료의 의미 + +이 문서는 `develop`의 `cb195f8`을 계획 기준선으로 삼아, 현재 저장소에 선언된 +프론트엔드 계약을 실제 런타임과 자동 검증까지 연결하는 구현 순서를 정의한다. +기준 커밋은 출발점일 뿐이며 각 구현 브랜치는 직전 브랜치가 병합된 최신 +`develop`에서 시작한다. + +구현 단계는 다음처럼 구분한다. + +| 단계 | 목적 | exit 상태 | +| --- | --- | --- | +| P0 | 새 기능이 사용할 input/output, HTTP/query, route/recovery 수직 경로 완성 | `LOCAL_CORE_READY` | +| P1 | form/page/design/i18n, diagnostics, test, 공급망까지 템플릿 품질 완성 | `LOCAL_TEMPLATE_READY` | +| P2 | 실제 요구가 생겼을 때 선택할 adapter recipe 제공 | 선택 항목만 `RECIPE_READY` | + +P0와 P1은 사용자가 요청한 높은 수준의 저장소 내부 준비도를 판단하기 전에 모두 +끝내야 한다. 이를 정밀한 백분율 점수로 표현하지 않고 다음 세 조건으로 +판정한다. + +1. 계약과 레지스트리의 모든 필드에 실제 consumer가 있다. +2. 정상 경로와 실패 경로가 자동 테스트로 증명된다. +3. 각 변경이 독립적으로 되돌릴 수 있고 feature branch와 evidence가 보존된다. + +P2는 제품 번들에 모든 기술을 미리 넣는 단계가 아니다. 선택 조건, port/facade, +fake adapter, 실패 정책과 제거 절차를 준비하는 단계다. + +## 2. 명시적인 범위 밖 + +다음 항목은 저장소가 seam, fail-closed 기본값, 검증 명령과 증거 형식을 제공할 +수는 있지만 실제 완료는 외부 프로젝트 또는 운영 환경의 책임이다. + +- 실제 hosting/CDN의 atomic deploy, cache purge, 응답 헤더와 rollback 실행 +- 실제 OAuth/OIDC/기업 IdP tenant, client, redirect URI와 token lifecycle +- production telemetry, RUM, analytics, error-reporting vendor와 consent 정책 +- 실제 사용자에게서 수집한 28일 field Web Vitals와 최소 표본 결정 +- 저장소 호스팅 서비스의 required check, branch protection과 evidence retention +- 운영용 CSP allowlist, signing key, provenance attestation과 비밀 관리 +- 실제 브랜드, 업무 문구, 번역 승인, 지원 locale와 법적 고지 +- 도메인 API, 권한 모델, 제품별 form schema와 업무 규칙 +- 운영 release 승인 + +이 항목이 준비되지 않아도 demo, fake, no-op, unavailable adapter를 사용해 +P0/P1의 저장소 내부 구현과 테스트를 끝낼 수 있어야 한다. 반대로 외부 증거가 +없는데 `PRODUCTION_READY`, `WCAG_READY`, `FIELD_SLO_READY`를 주장해서는 안 된다. +상위 promotion gate는 임의의 값을 만들어 PASS하지 않고 `FAIL_UNVERIFIED`를 +유지한다. + +## 3. 공통 구현 원칙 + +- `.ts`나 `.tsx`를 만들기 전에 lint, architecture, registry, typecheck와 test + 검색 범위가 해당 확장자를 검사한다. +- React는 application input port를 호출하고, application은 output port만 안다. + 구체 adapter 조립은 bootstrap만 담당한다. +- route, API, error, query, storage, telemetry와 release registry는 문서용 목록이 + 아니라 실행과 검증의 단일 소스다. +- path, search, body, response와 external event는 경계에서 parse하며 parse된 + 결과를 다음 계층으로 전달한다. +- retry, cache, redirect, reload, submission과 redaction에는 각각 한 명확한 + 정책 소유자만 둔다. +- 정상 테스트와 함께 invalid import, schema, URL, mutation, chunk, secret 같은 + negative fixture가 실제 gate에 의해 거절돼야 한다. +- vendor SDK type과 import는 local facade/adapter 밖으로 노출하지 않는다. +- 선택 gate가 닫히지 않은 라이브러리는 lockfile에 추가하지 않는다. +- 대규모 rename과 여러 capability를 한 merge에 섞지 않는다. + +## 4. Gitflow 브랜치 보존 규칙 + +현재 저장소는 `main`과 `develop`을 사용하고 feature prefix가 비어 있다. 아래 +표의 `feature-...` 이름을 그대로 `git flow feature start`에 전달한다. + +```text +최신 develop 확인 + -> git flow feature start <정확한 feature-... 이름> + -> 작은 검증 가능한 commit + -> git flow feature publish <정확한 feature-... 이름> + -> 자동 gate와 review + -> develop에 --no-ff merge + -> develop과 feature branch를 모두 push + -> local/origin feature branch 보존 +``` + +`git flow feature finish`는 feature branch를 삭제할 수 있으므로 사용하지 않는다. +병합 후에도 로컬 브랜치와 `origin/feature-...`를 제거하지 않는다. merge commit +SHA, feature tip, 실행한 gate와 artifact 위치를 PR 또는 merge evidence에 +기록한다. + +후속 브랜치는 미병합 feature branch에서 시작하지 않는다. 선행 브랜치를 먼저 +`develop`에 병합하고 최신 `develop`에서 새 브랜치를 시작한다. 병합 순서를 +바꾸려면 dependency와 acceptance를 다시 검토해야 한다. + +rollback은 reset이나 branch 삭제로 수행하지 않는다. + +1. 관련 promotion을 중단한다. +2. 보존된 feature branch와 merge commit으로 정확한 변경 범위를 찾는다. +3. `develop`에서 별도 `hotfix/...` 또는 revert branch를 만든다. +4. `git revert -m 1 `으로 merge를 되돌린다. +5. rollback gate 후 revert branch와 원래 feature branch를 모두 보존한다. +6. 수정은 최신 `develop`에서 새 feature branch로 다시 진행한다. + +## 5. 12개 브랜치와 병합 순서 + +```mermaid +flowchart TD + B01["01 P0 TypeScript tooling"] + B02["02 P0 input/output boundary"] + B03["03 P0 HTTP and query"] + B04["04 P0 routing and recovery"] + B05["05 P0 reference feature"] + B06["06 P1 forms and pages"] + B07["07 P1 design system"] + B08["08 P1 i18n"] + B09["09 P1 diagnostics"] + B10["10 P1 tests and registry evidence"] + B11["11 P1 supply chain"] + B12["12 P2 optional recipes"] + + B01 --> B02 --> B03 --> B04 --> B05 + B05 --> B06 --> B07 --> B08 --> B09 --> B10 --> B11 + B11 -. "요구가 확인된 recipe만" .-> B12 +``` + +| 순서 | 보존할 Gitflow feature branch | 단계 | 직접 선행조건 | rollback point | +| --- | --- | --- | --- | --- | +| 01 | `feature-frontend-typescript-tooling-foundation` | P0 | 기준선, VD-01 | RP-01 | +| 02 | `feature-frontend-application-boundary-runtime` | P0 | 01 | RP-02 | +| 03 | `feature-frontend-http-query-contract-execution` | P0 | 02 | RP-03 | +| 04 | `feature-frontend-routing-release-recovery-runtime` | P0 | 03, VD-03 | RP-04 | +| 05 | `feature-frontend-reference-feature-vertical-slice` | P0 | 04 | RP-05 | +| 06 | `feature-frontend-form-page-platform` | P1 | 05, VD-04 | RP-06 | +| 07 | `feature-frontend-design-system-platform` | P1 | 06, VD-05 | RP-07 | +| 08 | `feature-frontend-i18n-message-formatting-contract` | P1 | 07, VD-06 | RP-08 | +| 09 | `feature-frontend-diagnostics-telemetry-runtime` | P1 | 08, VD-07 | RP-09 | +| 10 | `feature-frontend-test-registry-evidence-hardening` | P1 | 09, VD-08 | RP-10 | +| 11 | `feature-frontend-supply-chain-verification` | P1 | 10, VD-09 | RP-11 | +| 12 | `feature-frontend-optional-adapter-recipes` | P2 | 11, VD-10 | RP-12 | + +## 6. 브랜치별 구현과 acceptance + +### 01. `feature-frontend-typescript-tooling-foundation` + +**목표** + +점진적 TypeScript 전환 전에 JS, JSX, TS, TSX와 테스트가 모두 같은 정적 분석과 +CI gate를 통과하게 한다. 애플리케이션 전체를 일괄 변환하지 않는다. + +**선행조건과 decision** + +- 기준선의 `pnpm ci:gate` 결과를 보존한다. +- TypeScript compiler와 기존 dependency 버전은 별도 dependency review 없이는 + 변경하지 않는다. +- 공식 JavaScript migration 방식처럼 점진적으로 전환한다. + [TypeScript JavaScript migration](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) + +**구체 변경 범위** + +- root, application/source, tests용 TypeScript project/reference를 분리한다. +- `src`, `tests`, `scripts`의 허용 확장자와 build output 제외 범위를 명시한다. +- ESLint, dependency-cruiser, registry scanner와 architecture script의 JS-only + glob 및 `.js` 고정 경로를 JS/TS 양쪽으로 확장한다. +- Vite, Vitest와 Playwright config가 TS source/test 오류를 우회하지 않게 한다. +- 기존 JS에는 `checkJs`, 새 TS에는 strict 정책을 적용한다. +- port, registry와 forbidden import용 `.ts`/`.tsx` fixture를 추가한다. + +**자동 테스트와 negative test** + +- JS와 TS source/test를 함께 typecheck하는 smoke +- TSX presentation의 concrete HTTP adapter import를 architecture gate가 거절 +- 잘못된 port 구현과 discriminated union 사용이 typecheck 실패 +- TS registry row의 누락 필드, 중복 ID와 unknown reference가 gate 실패 +- 기존 JS invalid-call fixture도 계속 실패 +- `pnpm lint`, `pnpm check:types`, `pnpm check:architecture`, + `pnpm check:registries`, `pnpm test:all`, `pnpm build` + +**Acceptance** + +- 허용된 모든 source/test 확장자가 typecheck, lint, architecture, registry gate + 중 필요한 검색 범위에 포함된다. +- JS 안전망이 약해지지 않은 상태에서 TS fixture가 CI에 의해 차단된다. +- 광범위한 unchecked cast나 임시 `any`로 통과시키지 않는다. +- production source 대량 변환 없이 독립적으로 revert할 수 있다. + +**Rollback** + +RP-01에서 merge를 revert하면 기존 JS 기준선으로 돌아간다. 후속 TS 작업은 +RP-01이 복구될 때까지 병합하지 않는다. + +### 02. `feature-frontend-application-boundary-runtime` + +**목표** + +UI가 호출할 input port와 application이 외부에 요구할 output port를 분리하고, +composition root가 생성한 `Application`을 실제 React tree에 주입한다. + +**선행조건과 decision** + +- 01의 TS-aware architecture gate가 병합돼 있어야 한다. +- 범용 client store는 추가하지 않는다. local interaction은 React state, 공유 + navigation state는 URL, server state는 query adapter가 소유한다. +- 실제 IdP 없이 demo/external/unavailable session adapter를 유지한다. + +**구체 변경 범위** + +- application input API를 query/command use case 중심으로 정의한다. +- gateway, session, cache, storage, clock, diagnostics와 release capability를 + output port로 분류한다. +- `createApplication`이 raw adapter를 다시 노출하지 않고 input API만 반환한다. +- `ApplicationProvider`와 `useApplication` 역할의 inbound React adapter를 둔다. +- bootstrap이 concrete output adapter를 선택하고 application을 router/page에 + 전달한다. +- presentation의 fetch, browser storage, concrete QueryClient와 outbound adapter + 직접 접근을 금지한다. +- inbound/outbound ownership을 architecture gate와 type fixture에 반영한다. + +**자동 테스트와 negative test** + +- fake output ports를 이용한 application use-case 단위 테스트 +- runtime config → composition root → provider → smoke page 통합 테스트 +- presentation의 `adapters/outbound`, `fetch`, concrete QueryClient import 거절 +- application의 React, router, browser storage, vendor SDK import 거절 +- 잘못된 output port 구현과 누락 input이 typecheck 실패 +- bootstrap 이외 계층의 concrete adapter 조립 거절 + +**Acceptance** + +- visible page가 raw outbound dependency 대신 application input API를 사용한다. +- 조립됐지만 사용되지 않는 application, HTTP와 release-info 객체가 없다. +- fake adapter만으로 application과 presentation의 정상·실패 경로를 테스트한다. +- vendor type이 application public API에 나타나지 않는다. + +**Rollback** + +RP-02는 기존 provider wiring을 한 merge로 되돌릴 수 있어야 한다. 임시 +compatibility wrapper는 05 reference feature 완료 전에 제거한다. + +### 03. `feature-frontend-http-query-contract-execution` + +**목표** + +API operation registry의 path/search/body/schema/timeout/retry가 실제 요청에 +반영되게 하고, TanStack Query를 application input과 React 사이의 제한된 inbound +adapter로 연결한다. + +**선행조건과 decision** + +- 02의 application error와 gateway 경계가 고정돼 있어야 한다. +- shared HTTP가 network retry를 소유하고 query adapter의 중복 retry는 끈다. + 다른 결정을 원하면 이 브랜치 전에 ADR을 남긴다. +- TanStack Query를 server-state adapter로 유지하되 Zustand/Redux Toolkit에 + server state를 복사하지 않는다. + +**구체 변경 범위** + +- request input을 operation/route ID, path params, search params, body, signal과 + idempotency key로 분리한다. +- operation registry에서 method, path, request/response schema, timeout과 retry + eligibility를 찾는다. +- deterministic path/search builder를 만들고 parse/transform된 query/body를 + 실제 URL/payload에 사용한다. +- runtime config의 timeout과 max attempts를 client factory에 주입한다. +- abort, timeout, retry delay와 listener cleanup을 injectable clock/scheduler + 경계로 통제한다. +- TanStack import를 허용할 local query adapter 경계를 하나만 둔다. +- `useApplicationQuery`, `useApplicationMutation` 역할의 controller API를 + 정의하고 query key, cancellation, invalidation과 optimistic rollback을 + 연결한다. +- base state를 loading/success/empty/terminal로, overlay를 + refreshing/stale-degraded/pending/conflict로 닫는다. +- refreshing/stale 및 pending/conflict의 배타성과 stale-failure latch를 + 명시적으로 구현한다. +- stale retry, duplicate-submit 방지와 conflict action을 실제 callback에 + 연결한다. + +**자동 테스트와 negative test** + +- path escaping, optional/array search, stable ordering 및 query key/request URL 일치 +- query/body transform 결과 전송, invalid input에서 `fetch` 0회 +- runtime timeout과 max attempts 0/1/N의 실제 호출 횟수 +- validation 실패, abort, success, exhausted retry의 timer/listener cleanup +- caller abort와 timeout의 서로 다른 typed failure +- unsafe mutation, non-retryable status와 schema failure retry 0회 +- 네 base state, 네 overlay와 허용 transition +- refreshing 실패의 stale latch 및 성공/재시도 후 해제 +- pending/conflict 동시 상태 fixture 거절 +- duplicate submit 1회, optimistic success/rejection rollback/conflict resolution +- unmount/navigation abort가 terminal error로 오인되지 않음 +- local adapter 밖의 `@tanstack/**` import 거절 + +**Acceptance** + +- cache key에 포함된 request 입력이 실제 URL/body에서도 동일하게 사용된다. +- runtime timeout/retry 설정이 실제 동작을 바꾼다. +- 모든 종료 경로의 cleanup과 한계 횟수를 fake clock으로 결정적으로 증명한다. +- QueryClientProvider가 단순 마운트 객체가 아니며 reference controller가 사용할 + 표준 API를 제공한다. +- `AsyncSurface`의 모든 action이 실제 command와 검증된 state transition을 가진다. + +**Rollback** + +RP-03은 application port를 유지하면서 이전 HTTP compatibility adapter 또는 +imperative controller로 되돌릴 수 있어야 한다. request builder와 query adapter +commit을 구분해 부분 revert가 가능하게 한다. + +### 04. `feature-frontend-routing-release-recovery-runtime` + +**목표** + +route registry를 executable router의 단일 계약으로 만들고 params/search/access/ +surface/chunk metadata를 route flow에 연결한다. lazy chunk 실패도 release +manifest와 bounded recovery에 실제 연결한다. + +**선행조건과 decision** + +- 03의 controller가 parsed route input을 받을 수 있어야 한다. +- VD-03 기본값은 React Router Data Mode다. route object, blocker, scroll + restoration과 route error 경계를 사용하되 server state는 application input과 + TanStack Query가 계속 소유한다. + [React Router modes](https://reactrouter.com/start/modes), + [Data Mode custom setup](https://reactrouter.com/start/data/custom) +- 고정된 `7.18.1` API로 전환하고 router version upgrade는 별도 dependency + 브랜치로 분리한다. +- 실제 hosting cache/purge는 범위 밖이며 test manifest server/browser adapter를 + 사용한다. + +**구체 변경 범위** + +- 직렬화 가능한 route contract와 component/codec runtime map을 분리한다. +- route ID의 contract/runtime 양방향 완전성을 TypeScript와 registry gate로 + 검사한다. +- registry에서 route objects, navigation, access hint, title, loading/error + surface와 chunk ID를 조립한다. +- params/search를 application 호출 전에 Zod codec으로 parse하고 URL builder도 + 같은 codec을 사용한다. +- unknown/authentication-required/forbidden/not-found/error surface의 소유자를 + 하나씩 정한다. +- route change의 boundary reset, document title, main focus와 scroll 정책을 + 적용한다. +- redirect-loop guard와 최대 hop을 실제 자동 redirect flow에 연결한다. +- build의 Vite asset manifest와 route chunk ID를 release manifest의 검증 가능한 + map으로 연결하고 `runtime-config.schema.json`을 artifact로 생성한다. +- config/release/build/asset mismatch 오류 kind를 정확히 나눈다. +- lazy rejection → no-store manifest refetch → active build/release pair 비교 → + guarded reload 1회 → 반복 실패 support/rollback surface를 연결한다. +- 일반 render error는 chunk reload 경로에 들어가지 않고 local reset을 유지한다. +- `FeatureBoundary`, `ReleaseInfoPort`와 chunk recovery controller를 production + call graph에 연결한다. + +**자동 테스트와 negative test** + +- registry row 추가 시 route tree/navigation 동시 추가 +- runtime 누락/orphan, duplicate path/ID, unknown schema/surface/chunk 거절 +- invalid params/search, unknown route와 access rejection에서 application/API 0회 +- URL parse/build round-trip과 canonical search +- redirect cycle이 최대 hop에서 종료 +- route 전환 후 error reset, main heading focus와 중복 surface 없음 +- stale chunk + manifest mismatch에서 no-store refetch 후 reload 정확히 1회 +- 같은 build/release pair의 두 번째 실패에서 reload 0회와 support surface +- manifest malformed/offline/storage unavailable의 fail-closed 동작 +- 일반 component throw가 chunk failure로 오분류되지 않음 +- build/config/release/asset mismatch의 정확한 error kind +- built `dist`의 route chunk map, runtime schema와 release artifact set 검증 + +**Acceptance** + +- 수동 route 열거와 registry가 서로 어긋날 수 없다. +- route metadata 중 consumer 없는 token이 0개다. +- invalid/unknown/access-rejected URL에서 product API 0회를 증명한다. +- chunk recovery 결정이 production call graph에 있으며 무한 reload가 불가능하다. +- 실제 CDN 없이 저장소 내부 recovery matrix가 결정적으로 통과한다. + +**Rollback** + +RP-04는 이전 수동 router와 generic route failure surface로 한 merge를 되돌릴 수 +있어야 한다. URL shape는 바꾸지 않으며 불가피한 변경은 compatibility redirect와 +migration이 있어야 한다. 실제 CDN purge는 rollback 범위에 포함하지 않는다. + +### 05. `feature-frontend-reference-feature-vertical-slice` + +**목표** + +route에서 실제 HTTP/query/application/presentation까지 연결되며 전체를 제거해도 +generic platform이 정상 부팅되는 하나의 reference feature를 만든다. + +**선행조건과 decision** + +- 01~04가 모두 병합돼 있어야 한다. +- 실제 backend와 IdP 대신 MSW/fake gateway와 demo auth를 사용한다. +- reference 업무 용어를 제품 도메인 계약으로 승격하지 않는다. + +**구체 변경 범위** + +- 흩어진 sample route, operation, schema, mapper, domain, query key, controller, + page와 tests를 canonical `src/features/reference-feature` 한 ownership 경계로 + 이동한다. +- feature 내부에 domain, application input/output, outbound gateway, DTO/schema, + mapper, query/mutation controller와 presentation page를 둔다. +- list filter가 URL codec, query key와 실제 HTTP request에 동일하게 반영된다. +- safe mutation으로 pending, duplicate prevention, optimistic state, conflict와 + rollback을 보여 준다. +- registry/application에는 removable contribution contract를 사용하고 generic + source에는 fixture-specific ID를 하드코딩하지 않는다. +- production bootstrap과 같은 composition 경로에 fake adapter를 주입한다. +- `src/features/reference-feature` 전체를 제거한 ephemeral copy에서 + typecheck/test/build/home smoke를 실행하도록 sample-removal gate를 다시 + 작성한다. + +**자동 테스트와 negative test** + +- bootstrap → router → controller → input use case → gateway → HTTP/MSW → + response schema → mapper → cache → page의 수직 통합 +- loading/success/empty/terminal/refreshing/stale/pending/conflict/recovery UI +- invalid search에서 gateway/fetch 0회 +- invalid DTO가 domain/view model로 전파되지 않음 +- backend forbidden을 client access hint와 무관하게 최종 반영 +- duplicate/unsafe mutation 전송 횟수 +- `src/features/reference-feature` 삭제 후 typecheck, architecture, registry, + unit/integration, home smoke와 build +- 삭제 후 sample route 부재와 `src`/`tests`의 fixture-specific ID 잔여 0개 +- generic home/examples route가 sample 없이 계속 작동 + +**Acceptance** + +- static page와 분리된 fixture가 아니라 실제 수직 경로 하나가 존재한다. +- reference feature를 삭제할 때 central registry를 수작업으로 수정하는 숨은 + 단계가 없거나 제거 명령이 이를 결정적으로 수행한다. +- feature 존재/제거 두 모드에서 P0 gate가 모두 통과한다. +- 01~04를 함께 revert해야만 sample을 제거할 수 있는 숨은 결합이 없다. + +**Rollback** + +RP-05는 P0 최종 지점이다. reference feature merge만 revert해도 generic platform은 +정상이어야 한다. + +## 7. P0 exit gate + +- JS/TS source와 tests가 동일한 정적 gate에 포함된다. +- UI는 application input API만 호출하고 concrete outbound adapter를 모른다. +- HTTP path/search/body/auth/timeout/retry/cancel/decode가 실행 계약과 일치한다. +- query/mutation controller와 모든 async state transition이 작동한다. +- route registry/runtime map과 route chunk map이 양방향 완전성을 가진다. +- lazy chunk failure가 bounded release recovery에 연결된다. +- reference feature가 실제 수직 경로를 실행하고 전체 삭제 gate를 통과한다. +- `pnpm ci:gate`와 P0에서 추가한 모든 negative fixture가 통과한다. + +위 조건이 모두 충족돼야 `LOCAL_CORE_READY`다. RP-05 증거를 보존한 뒤 P1을 +시작한다. + +## 8. P1 브랜치 + +### 06. `feature-frontend-form-page-platform` + +**목표** + +Zod schema와 application command를 연결하는 form controller 및 +standard/collection/detail/form/status page template를 제공한다. + +**선행조건과 decision** + +- 05의 mutation과 async state가 실제 reference flow에서 작동해야 한다. +- VD-04에서 React Hook Form + Zod resolver 사용 여부를 정한다. 복합 form 요구가 + 확정되면 local facade 뒤에 추가하고, 거절되면 native form + local controller가 + 같은 public API와 tests를 충족한다. + [React Hook Form resolvers](https://github.com/react-hook-form/resolvers), + [Zod](https://zod.dev/) +- vendor 결정 전에 dependency/lockfile을 변경하지 않는다. + +**구체 변경 범위** + +- presentation form schema와 domain invariant를 분리한다. +- field registration, parse/error map, dirty/touched/reset/pending/result를 local + form API로 감싼다. +- `422` field/form/unknown-server-field/global error mapping을 정의한다. +- 첫 오류 focus, error summary, field ID와 live-region을 연결한다. +- duplicate submit, cancel/leave와 unsaved-change 정책을 적용한다. +- `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`의 slot + 계약을 정의한다. +- heading, breadcrumb, actions, filters, content, aside와 feedback의 소유 위치를 + 표준화한다. +- reference list/detail/create-edit/status page를 controller와 template로 + 전환한다. +- template가 application use case나 query vendor를 직접 선택하지 않게 한다. + +**자동 테스트와 negative test** + +- client validation 실패에서 command 0회와 첫 invalid field focus +- transformed/defaulted data가 command에 전달됨 +- field/form/unknown server error와 conflict 후 입력 보존 +- pending 중 연속 submit에도 command 1회 +- reset 후 dirty 해제와 navigation confirmation/focus restore +- secret-like input이 URL/storage/log/telemetry에 나타나면 실패 +- 각 template의 최소/전체 slot 및 async/error variation +- 320px, zoom, 긴 heading/action과 wide layout +- heading/landmark/accessibility-name/axe +- template가 application/HTTP/query vendor를 import하면 gate 실패 +- action callback 없이 활성 버튼을 렌더링하면 실패 + +**Acceptance** + +- form engine을 바꿔도 page와 application API가 변하지 않는다. +- multi-field form의 validation/pending/dirty/422/conflict가 실행된다. +- 새 feature가 layout CSS를 복사하지 않고 다섯 page 유형을 조립한다. +- template는 layout/state slot만 소유하고 데이터 정책은 소유하지 않는다. + +**Rollback** + +RP-06은 기존 reference controls/layout으로 돌아가도 controller/application +경계가 유지돼야 한다. vendor adapter, form contract와 template commit을 구분해 +부분 revert가 가능하게 한다. + +### 07. `feature-frontend-design-system-platform` + +**목표** + +기존 theme와 primitive를 token → primitive → pattern → template 계층으로 +확장하고, 모바일 drawer와 복합 interaction을 접근 가능한 local API로 제공한다. + +**선행조건과 decision** + +- 06의 page/form에서 반복되는 실제 token/primitive 요구를 수집한다. +- VD-05에서 icon source와 headless interaction 방식을 결정한다. +- Lucide를 선택하면 static named import만 local icon facade에서 허용한다. + [Lucide React](https://lucide.dev/guide/react), + [Lucide accessibility](https://lucide.dev/guide/react/advanced/accessibility) +- headless vendor가 미결정이면 native dialog/disclosure/control 범위만 완료하며, + 미지원 widget을 임의 구현해 완료로 표시하지 않는다. + +**구체 변경 범위** + +- primitive/semantic/component token을 분리한다. +- color, typography, spacing, size, radius, elevation, z-layer, motion, breakpoint와 + opacity 계약을 정의한다. +- light/dark/system, forced-colors와 reduced-motion을 닫는다. +- design-system public entry와 deep-import 금지 규칙을 만든다. +- 기존 Button/TextField/Card/Alert/Badge/Dialog를 호환 가능한 public API로 + 이동한다. +- LinkButton/IconButton/Field/TextArea/Select/Checkbox/RadioGroup/Switch/ + Spinner/Skeleton/VisuallyHidden을 기본 제공한다. +- Drawer/Popover/Tooltip/Menu/Tabs/Breadcrumbs/Pagination/Toast/ProgressBar 및 + 필요한 focus/portal utility를 추가한다. +- 모바일 navigation을 Drawer로 전환해 focus 이동, modal/background 정책, + Escape/scrim/link dismiss와 trigger focus restore를 구현한다. +- 앱 셸의 문자 glyph/raw control을 local icon/primitive로 교체한다. +- `/examples/ui`와 `/examples/states`에서 interactive state를 실제 동작으로 + 노출한다. + +**자동 테스트와 negative test** + +- 필수 semantic token의 light/dark/forced-colors 정의 +- undefined CSS variable/raw palette 사용 거절 +- interactive icon의 accessible name 누락 거절, decorative icon tree 제외 +- product code의 direct icon/headless vendor 또는 deep import 거절 +- disabled/pending/focus/invalid와 reduced-motion/theme persistence +- keyboard-only open/move/select/dismiss/focus restore +- Drawer open 시 background interaction 차단과 compact reflow +- Menu/Tabs arrow key, typeahead와 activation 정책 +- Tooltip만으로 필수 정보를 제공하는 fixture 거절 +- Toast queue 상한/duplicate collapse/timeout pause +- Chromium/Firefox/WebKit component/E2E/axe + +**Acceptance** + +- shell, templates와 reference feature가 public design-system API를 사용한다. +- product code의 raw palette, vendor icon/headless import가 0개다. +- mobile navigation이 검증된 focus/dismiss contract를 따른다. +- gallery action이 handler 없는 장식이 아니라 실행 가능한 상태를 시연한다. +- token 누락과 접근 불가능한 interaction을 자동 gate가 차단한다. + +**Rollback** + +RP-07은 compatibility export로 기존 primitive import를 복구할 수 있어야 한다. +token rename은 alias/migration 기간을 두고, vendor adapter와 local API commit을 +분리한다. + +### 08. `feature-frontend-i18n-message-formatting-contract` + +**목표** + +사용자 문구, 날짜, 숫자, 상대 시간과 direction을 typed message/formatter 경계로 +옮겨 특정 언어 literal과 locale 가정을 공통 UI에서 제거한다. + +**선행조건과 decision** + +- 07까지의 common user-facing string 목록이 확보돼 있어야 한다. +- VD-06 기본값은 browser `Intl` + typed local catalog다. extraction/plural 등 + 요구가 이를 넘을 때만 vendor를 선택한다. +- 실제 번역 승인과 지원 locale은 외부 프로젝트 범위다. + +**구체 변경 범위** + +- typed message key와 interpolation parameter 계약을 정의한다. +- locale provider, fallback locale, direction과 date/number/relative-time + formatter를 제공한다. +- shell, route, async/form error와 design-system 기본 copy를 catalog로 이동한다. +- backend raw message를 번역 key로 신뢰하지 않고 error registry로 매핑한다. +- pseudo-locale와 RTL smoke locale을 테스트 전용으로 제공한다. +- unknown key/locale, formatter failure와 missing interpolation의 fallback을 + 정의한다. + +**자동 테스트와 negative test** + +- 모든 등록 locale의 key parity와 interpolation 정합성 +- unknown locale/key에서 raw key/stack을 노출하지 않는 fallback +- pseudo-locale 확장에 대한 layout/reflow +- RTL shell/drawer/breadcrumb와 directional icon +- 날짜/숫자/timezone의 결정적 test +- untrusted HTML interpolation 및 backend message 직접 렌더링 거절 +- common UI의 금지된 hardcoded user-facing literal 검출 + +**Acceptance** + +- shell/state/form/error copy가 typed catalog를 통과한다. +- pseudo-locale와 RTL E2E가 통과한다. +- 실제 제품 번역 없이도 locale 교체 지점과 실패 정책이 검증된다. +- key rename에는 compatibility alias 또는 migration이 있다. + +**Rollback** + +RP-08은 기존 기본 언어 catalog를 fallback으로 유지한다. 번역 catalog를 +파괴적으로 덮어쓰지 않는다. + +### 09. `feature-frontend-diagnostics-telemetry-runtime` + +**목표** + +structured diagnostics와 telemetry를 구분하고 boot, HTTP, cache, storage, route, +render와 release 사건을 실제 producer에 연결한다. + +**선행조건과 decision** + +- route/HTTP/query/form/release failure kind가 안정돼 있어야 한다. +- VD-07에서 외부 exporter를 선택하지 않아도 된다. no-op 또는 기존 + best-effort HTTP sink를 기본으로 하고 실제 vendor SDK는 외부 adapter다. + +**구체 변경 범위** + +- diagnostics/logger output port와 telemetry event port의 책임을 분리한다. +- level, event ID, timestamp, correlation/request/route/release context와 redaction + 정책을 정의한다. +- `app.boot.failed`, `api.request.failed`, `ui.render.failed`, + `release.mismatch.detected`, `telemetry.delivery.dropped`를 production path에 + 연결한다. +- retry attempt마다 terminal failure를 중복 발행하지 않고 bounded summary만 + 남긴다. +- route/path/query/body/error에서 고카디널리티와 민감 값을 제거한다. +- queue 상한, drop reason bucket, sink failure와 nonrecursive fallback을 + 구현한다. +- reference feature에서 route → application → HTTP outcome correlation을 + 증명한다. + +**자동 테스트와 negative test** + +- registry event가 production path에서 필요한 횟수만 발행 +- success/retry recovery/terminal failure event 차이 +- Authorization/cookie/token/raw form/body/PII-like fixture redaction +- large/circular/unknown error에서도 serializer가 throw하지 않음 +- queue full/sink failure가 app failure나 재귀 폭주를 만들지 않음 +- unknown/high-cardinality event context 거절 +- mount 전 boot failure도 안전한 evidence 생성 +- no-op adapter에서도 동일 application behavior + +**Acceptance** + +- 필수 telemetry event 중 producer 없는 항목이 0개다. +- sink/vendor가 없어도 기능이 정상이며 failure evidence가 제한된다. +- credential/raw user input이 queue, console과 artifact에 남지 않는다. +- exporter wiring만 독립적으로 제거할 수 있다. + +**Rollback** + +RP-09는 exporter를 제거하고 즉시 no-op adapter로 전환할 수 있어야 한다. +diagnostics port와 redaction test는 유지한다. + +### 10. `feature-frontend-test-registry-evidence-hardening` + +**목표** + +registry의 구조/참조/consumer/호환성을 실제 diff로 검증하고, P0/P1 위험 경로를 +실제 bootstrap과 built artifact에서 증명한다. + +**선행조건과 decision** + +- 09까지의 public contract와 registry field가 안정돼 있어야 한다. +- VD-08 기본값은 dev-only Storybook workshop과 local Playwright visual + baseline이다. cloud review service는 선택이다. +- `/examples/ui`, `/examples/states`는 실제 앱 composition의 통합 smoke로 + 유지하며 isolated story의 SSOT를 대신하지 않는다. + [Storybook documentation](https://storybook.js.org/docs) + +**구체 변경 범위** + +- route/API/schema/error/query/storage/telemetry/config/release registry의 field + type/enum/unique/cross-reference/consumer/orphan을 machine-readable하게 검사한다. +- 직전 승인 snapshot과 현재 snapshot의 actual diff로 additive/behavioral/ + breaking/removal을 계산한다. +- breaking에는 version bump, migration, compatibility window와 rollback + evidence를 요구한다. +- hardcoded `current: additive`, empty high-risk review와 self-asserted PASS를 + 제거한다. +- source와 tests를 모두 포함하는 TypeScript check를 CI 필수 gate로 만든다. +- MSW handler를 operation/schema 기반 shared scenario catalog로 통합한다. +- 실제 `main` composition과 built `dist`의 integration/release E2E를 추가한다. +- Playwright compact/mobile project와 risk-based coverage threshold를 추가한다. +- deterministic clock/random/fetch/storage helper, unexpected console/unhandled + rejection 실패 정책을 제공한다. +- 선택된 workshop interaction 또는 안정 환경의 visual baseline을 추가한다. +- JUnit/screenshot/trace/evidence naming과 CI gate registry를 맞춘다. + +**자동 테스트와 negative test** + +- duplicate ID/path, invalid enum/type, missing field/reference와 orphan 거절 +- actual removal/type narrowing/path change를 additive로 표시하면 실패 +- breaking diff의 version/migration/rollback 누락 실패 +- ordering-only diff는 semantic change가 아님 +- 승인 baseline digest 변조 실패 +- unexpected network/operation, provider 누락과 unhandled error 실패 +- critical policy coverage threshold 미달 실패 +- built artifact의 source map, config schema 누락과 broken chunk 실패 +- compact viewport와 Chromium/Firefox/WebKit navigation/a11y smoke +- reference feature 제거 모드의 generic E2E/build +- screenshot mask가 전체 UI를 가려 false PASS를 만들면 실패 + +**Acceptance** + +- route 선언/실행 불일치와 telemetry producer 누락을 registry gate가 잡는다. +- compatibility impact가 하드코딩 상수가 아니라 actual diff다. +- 테스트가 source module만이 아니라 real composition과 `dist`를 증명한다. +- 모든 P0/P1 high-risk policy에 negative fixture가 하나 이상 있다. +- CI artifact로 browser/release/fixture 실패를 재현할 수 있다. + +**Rollback** + +RP-10은 직전 승인 registry snapshot과 test evidence다. flaky visual/browser +infrastructure commit은 product behavior와 분리한다. 장기 skip으로 PASS하지 않고 +owner와 만료 시한이 있는 quarantine만 허용한다. + +### 11. `feature-frontend-supply-chain-verification` + +**목표** + +직접·전이 dependency, vulnerability, license, secret, SBOM/inventory와 provenance를 +검증 가능한 release gate로 만든다. + +**선행조건과 decision** + +- 10까지 최종 build/test dependency 구조가 안정돼 있어야 한다. +- VD-09에서 vulnerability source, license policy, SBOM format과 attestation + provider를 선택한다. +- provider가 미결정이면 임의 PASS를 만들지 않고 promotion을 + `FAIL_UNVERIFIED`로 유지한다. local inventory/fixture 검증은 완료할 수 있다. + +**구체 변경 범위** + +- frozen lockfile에서 direct/transitive dependency inventory를 생성한다. +- name/version, direct/transitive, resolved integrity와 license를 deterministic하게 + 기록한다. +- actual baseline/lockfile diff에서 new/removed/changed dependency와 + reviewer-required risk를 계산한다. +- secret scan 범위를 source/dist/tracked config/generated manifest와 artifact + metadata에 맞게 확장한다. +- 선택된 vulnerability/license adapter가 severity, exception owner/expiry를 + machine-readable evidence로 남기게 한다. +- SBOM 또는 동등 inventory, build digest와 provenance statement를 coherent + release artifact set에 연결한다. +- frozen install과 동일 source/lock/config의 reproducible build를 검증한다. + +**자동 테스트와 negative test** + +- transitive dependency inventory 누락 실패 +- lockfile integrity/digest 변조와 unfrozen install 실패 +- high-risk dependency의 self-approval 실패 +- 금지 license, threshold vulnerability와 만료 exception 실패 +- source/dist/config secret fixture 검출 및 test-secret allowlist 통제 +- SBOM/inventory와 release manifest digest 불일치 실패 +- provenance subject와 artifact digest 불일치 실패 +- dependency ordering만 달라도 deterministic output 유지 + +**Acceptance** + +- dependency diff와 high-risk review가 하드코딩 빈 배열이 아니다. +- transitive inventory, license와 vulnerability 결과가 release evidence에 + 포함된다. +- provider/organization decision이 없으면 상위 promotion이 명시적으로 + `FAIL_UNVERIFIED`다. +- 위험 dependency upgrade만 독립적으로 revert할 수 있다. + +**Rollback** + +RP-11은 P1 최종 저장소 기준선이다. scanner outage를 무검증 승인으로 우회하지 +않고 promotion을 보류한다. + +## 9. P1 exit gate + +- 현실적인 form의 validation/dirty/pending/422/conflict가 작동한다. +- collection/detail/form/status를 포함한 page template가 reference feature에서 + 사용된다. +- token → primitive → pattern → template 경계가 자동 보호된다. +- compact navigation과 interaction의 keyboard/focus 계약이 검증된다. +- typed message, pseudo-locale와 RTL smoke가 존재한다. +- 필수 telemetry event가 실제 producer에 연결되고 secret/PII가 redaction된다. +- registry/compatibility가 actual diff와 cross-reference로 검증된다. +- bootstrap과 built `dist`를 포함한 risk-based test/evidence가 남는다. +- transitive dependency, vulnerability, license와 local SBOM가 선택된 정책에 + 따라 검증된다. 외부 signing/provenance provider가 미결정이면 해당 promotion만 + `FAIL_UNVERIFIED`다. +- 현재 merge gate가 요구하는 등록 route의 signed manual accessibility evidence가 + 갱신된다. +- P0/P1 feature branch와 merge evidence가 local/origin에 모두 보존된다. + +위 조건이 모두 충족되면 `LOCAL_TEMPLATE_READY`다. 실제 hosting, IdP, +production sink와 field data 없이도 저장소 내부 상태는 달성할 수 있지만, 외부 +gate 없이는 production promotion을 통과했다고 보지 않는다. + +## 10. P2 브랜치 + +### 12. `feature-frontend-optional-adapter-recipes` + +**목표** + +모든 프로젝트에 dependency를 미리 설치하지 않고, 실제 요구가 확인된 capability의 +선택 기준, port/facade, fake adapter, failure policy와 test recipe를 제공한다. + +**선행조건과 decision** + +- P0/P1 public boundary가 안정돼 있어야 한다. +- VD-10에서 실제 소비 요구, owner, 보안 영향, bundle 예산과 제거 조건이 + 승인된 recipe만 구현한다. +- 승인되지 않은 recipe의 runtime dependency는 추가하지 않는다. + +**구체 변경 범위** + +| recipe | 기본 경계 | 반드시 다룰 실패 | +| --- | --- | --- | +| realtime | subscribe/unsubscribe, reconnect, resume, heartbeat | disconnect, duplicate/out-of-order, auth expiry | +| offline/IndexedDB | versioned repository와 migration | quota, corruption, migration rollback | +| Service Worker/PWA | cache ownership와 update controller | stale worker, update loop, offline fallback | +| file transfer | upload/download, progress, cancel | size/type rejection, abort, expired URL | +| generated API | generated client를 gateway 뒤에 감싸는 facade | contract drift, unsupported field | +| feature flag | typed key, default와 stale policy | provider unavailable, unknown flag | +| Web Worker | request/result/cancel protocol | crash, stale result, transfer failure | +| multi-tab | versioned BroadcastChannel event | self-echo, duplicate, conflict | +| browser permission | clipboard/notification/media result port | denied, dismissed, unsupported | +| client workflow | Zustand/Redux Toolkit/state-machine local facade | reset, mismatch, server-state duplication | +| large data UI | virtualizer/data-grid facade | focus loss, stale row, scale limit | +| analytics/error sink | consent/redaction/sampling adapter | denied consent, queue full, unavailable | + +- 각 recipe에 설치/금지 조건, ownership, security/privacy, bundle 영향, fallback과 + 제거 절차를 기록한다. +- runnable fixture는 production entry에서 제외한 opt-in example/test entry에 + 둔다. +- Zustand와 Redux Toolkit을 동시에 기본 설치하지 않는다. +- browser가 DB/object store에 직접 접속하는 recipe는 만들지 않고 권한 있는 + backend/BFF protocol adapter를 사용한다. + +**자동 테스트와 negative test** + +- 선택 recipe의 fake adapter contract 및 unavailable fallback +- unsubscribe/cancel/cleanup 누락 fixture 실패 +- local adapter 밖의 vendor SDK direct import 실패 +- credential을 localStorage/telemetry/URL에 저장하는 fixture 실패 +- server state를 client workflow store에 복제하는 fixture 실패 +- recipe 제거 후 base typecheck/test/build 통과 +- opt-in하지 않은 recipe가 production bundle에 없음을 검증 + +**Acceptance** + +- 선택 capability는 port/facade, fake adapter, failure matrix, tests와 제거 + 절차를 가진다. +- 선택하지 않은 capability는 dependency와 production code를 늘리지 않는다. +- recipe 하나의 도입/제거가 다른 recipe와 P0/P1 runtime을 변경하지 않는다. + +**Rollback** + +RP-12는 recipe별 merge commit이다. optional adapter 문제 시 해당 recipe commit만 +revert하고 RP-11을 유지한다. 여러 vendor를 되돌릴 수 없는 한 commit에 묶지 +않는다. + +## 11. Vendor decision gate + +| ID | 시점 | 결정 | 기본값 또는 미결정 시 처리 | 차단 범위 | +| --- | --- | --- | --- | --- | +| VD-01 | 01 전 | TypeScript migration 범위와 compiler 변경 | 기존 compiler 고정, tooling-first 점진 전환 | compiler upgrade와 source 변환 | +| VD-02 | 02 전 | 범용 client store | 추가하지 않음. local/URL/query/context 사용 | 실제 cross-feature workflow만 | +| VD-03 | 04 전 | React Router mode | Data Mode; server state는 TanStack/application 유지 | Framework/SSR 전환만 | +| VD-04 | 06 전 | form engine | 복합 form이면 RHF+Zod facade, 아니면 local/native | form 구현체 | +| VD-05 | 07 전 | icon/headless UI | local facade, native 우선; 미지원 behavior는 미완료 | icon/복합 primitive | +| VD-06 | 08 전 | i18n engine | `Intl` + typed local catalog | extraction/plural 고급 기능 | +| VD-07 | 09 전 | diagnostics/telemetry exporter | no-op/best-effort HTTP | production sink만 | +| VD-08 | 10 전 | Storybook/visual 방식 | dev-only Storybook + local Playwright baseline | cloud review/별도 배포 | +| VD-09 | 11 전 | vulnerability/license/SBOM/provenance | 임의 PASS 금지, `FAIL_UNVERIFIED` | release promotion | +| VD-10 | 12 전 | optional capability 요구 | 설치하지 않음 | 해당 recipe만 | + +각 decision에는 실제 요구, bundle/runtime/a11y/security 영향, local facade 방식, +대안, fallback/migration/removal, owner와 재검토 시점을 기록한다. + +결정이 지연될 때 vendor-neutral port와 no-op/fake/unavailable adapter를 먼저 +완성한다. 다만 vendor가 있어야 충족되는 behavior를 구현하지 않은 채 완료로 +표시해서는 안 된다. + +## 12. Rollback과 promotion + +| checkpoint | 포함 범위 | 다음 단계 진입 조건 | 대표 rollback 사유 | +| --- | --- | --- | --- | +| RP-01 | tooling | TS/JS fixture와 gate 통과 | TS 파일이 검사에서 누락 | +| RP-02 | application boundary | composition integration 통과 | UI가 raw adapter에 의존 | +| RP-03 | HTTP/query | request/state negative matrix 통과 | query 손실, retry/submit 폭주 | +| RP-04 | routing/recovery | registry와 reload-loop drill 통과 | invalid URL API 호출, reload loop | +| RP-05 | P0 reference | feature 존재/제거 gate 통과 | hidden sample coupling | +| RP-06 | form/page | form/page/a11y gate 통과 | 입력 손실, template 결합 | +| RP-07 | design system | token/interaction gate 통과 | focus/theme/vendor 회귀 | +| RP-08 | i18n | catalog/pseudo/RTL gate 통과 | missing key, locale 회귀 | +| RP-09 | diagnostics | producer/redaction gate 통과 | PII 노출, event 폭주 | +| RP-10 | test/registry | actual diff와 evidence gate 통과 | false PASS, flaky blocker | +| RP-11 | P1 supply chain | `LOCAL_TEMPLATE_READY` | 위험 dependency/검증 공백 | +| RP-12 | optional recipe | recipe별 opt-in gate | vendor 격리 실패 | + +```text +RP-05 + P0 exit + = LOCAL_CORE_READY + +RP-11 + P1 exit + = LOCAL_TEMPLATE_READY + +LOCAL_TEMPLATE_READY + + 실제 hosting/IdP/보안/접근성/운영 증거 + = PROJECT_INTEGRATION_READY + +PROJECT_INTEGRATION_READY + + production promotion과 eligible field data + = PRODUCTION/FIELD READY +``` + +저장소 내부와 외부 증거를 하나의 백분율로 숨기지 않는다. P0/P1의 모든 +acceptance가 자동 검증되고 외부 항목이 명확히 분리된 +`LOCAL_TEMPLATE_READY`를 높은 저장소 내부 준비도의 실질 기준으로 사용한다. + +## 13. 브랜치 공통 인수 체크리스트 + +각 feature branch는 병합 전에 다음을 evidence에 남긴다. + +- 목표와 변경하지 않는 범위 +- 시작한 `develop` SHA와 선행 merge SHA +- 변경한 public contract, registry와 compatibility 영향 +- positive/negative fixture +- 실행한 typecheck, lint, architecture, unit, integration, E2E와 build 명령 +- artifact와 browser/runtime 환경 +- dependency/lockfile 변경 및 vendor decision ID +- fake/no-op/unavailable adapter로 검증한 범위 +- external blocker와 `FAIL_UNVERIFIED` promotion +- merge commit과 보존된 local/origin feature tip +- rollback 대상 merge와 복구 확인 gate + +acceptance를 만족하지 못한 브랜치는 후속 브랜치의 기반으로 사용하지 않는다. +test를 skip하거나 문서상 예외로 바꾸는 것은 완료가 아니다. diff --git a/docs/architecture/frontend-ports-adapters-and-boundaries.md b/docs/architecture/frontend-ports-adapters-and-boundaries.md new file mode 100644 index 0000000..11c0c8d --- /dev/null +++ b/docs/architecture/frontend-ports-adapters-and-boundaries.md @@ -0,0 +1,1253 @@ +# 프론트엔드 포트·어댑터와 경계 설계 + +## 1. 문서 목적 + +이 문서는 이 저장소에서 도메인 기능을 추가할 때 사용할 경계와 확장 +절차를 정의한다. 다음 질문에 대한 단일 기준 문서다. + +- 프론트엔드에서 inbound와 outbound는 무엇인가? +- `presentation`은 왜 inbound adapter인가? +- application이 노출해야 할 API와 외부 기술 포트는 어떻게 다른가? +- React, Router, TanStack Query, HTTP, 인증, 저장소, 로깅을 어디에 + 배치하는가? +- 새 기술 adapter나 새 feature를 어떤 순서로 추가하는가? +- 예제 feature가 제품 코드에 남지 않았음을 어떻게 증명하는가? + +포트의 방향은 네트워크 패킷의 방향이 아니라 **application을 기준으로 +누가 누구를 호출하는지**로 결정한다. + +```text +사용자·브라우저 이벤트 + -> inbound adapter + -> input port + -> application use case + -> output port + -> outbound adapter + -> 외부 시스템 또는 브라우저 기능 +``` + +화살표는 런타임 호출 방향이다. 소스 의존성은 가능한 한 안쪽을 향한다. +구체 기술의 선택과 조립은 `bootstrap`에서만 수행한다. + +## 2. 핵심 용어 + +### 2.1 Input port + +외부가 application에 요청할 수 있는 작업의 계약이다. 사용자의 의도를 +나타내며 기술 이름 대신 업무 동사를 사용한다. + +예: + +- `ListReferenceItems` +- `CreateReferenceItem` +- `BeginSignIn` +- `ChangeColorScheme` +- `RecoverSession` + +Input port는 React hook, HTTP request, router loader 자체가 아니다. React나 +router가 없어도 테스트할 수 있는 함수 또는 인터페이스여야 한다. + +### 2.2 Inbound adapter + +사용자 입력이나 외부 이벤트를 input port 호출로 변환한다. 현재 저장소의 +`src/presentation`은 이름에 `adapter`가 없지만 이 역할을 담당한다. + +대표적인 inbound adapter: + +- React page와 component +- React Router route, loader, action, guard +- form controller와 feature hook +- 키보드, pointer, browser lifecycle event handler +- WebSocket이나 Service Worker가 수신한 이벤트를 use case로 전달하는 + event handler + +### 2.3 Output port + +application이 작업을 완료하기 위해 외부에 요구하는 capability 계약이다. +application이 소유하고 outbound adapter가 구현한다. + +대표적인 output port: + +- 도메인별 gateway 또는 repository +- session gateway +- clock, ID generator +- preference persistence +- logger, telemetry, error reporter +- feature flag reader + +Output port에는 `fetch`, `localStorage`, 특정 SDK 객체처럼 기술 구현이 +드러나지 않아야 한다. + +### 2.4 Outbound adapter + +output port를 실제 기술로 구현한다. + +대표적인 outbound adapter: + +- Fetch 기반 API gateway +- 외부 인증 SDK session gateway +- `localStorage`, `sessionStorage`, IndexedDB persistence +- telemetry 또는 error-reporting sink +- browser clock, random, crypto UUID +- feature flag SDK + +### 2.5 Bootstrap + +구체 구현을 선택하고 연결하는 composition root다. bootstrap만 다음 +결정을 알고 있어야 한다. + +- 어떤 HTTP transport를 사용할지 +- 어떤 인증 owner를 연결할지 +- 어떤 logger와 telemetry sink를 사용할지 +- QueryClient 설정은 무엇인지 +- 어떤 input port 구현을 `ApplicationProvider`에 공급할지 + +bootstrap은 page별 orchestration이나 업무 규칙을 소유하지 않는다. + +## 3. 현재 저장소의 구조 해석 + +현재 구조는 다음과 같이 해석한다. + +| 현재 경로 | 현재 역할 | 목표 역할 | +| --- | --- | --- | +| `src/domain` | 순수 model과 invariant | framework-neutral domain | +| `src/application` | port, policy, 일부 use case와 view model | input/output port와 use case | +| `src/presentation` | React UI, route, provider, 상태 화면 | inbound React adapter | +| `src/adapters` | HTTP, auth, storage, cache, telemetry 구현 | outbound adapter | +| `src/bootstrap` | runtime config와 구현 조립 | 유일한 composition root | +| `src/contracts` | 여러 계층의 registry가 혼재 | 소유 계층으로 분산 | +| `src/sample` | 제거 가능한 예제 일부 | 완전한 removable reference feature | + +현재 구조가 잘 제공하는 기반은 다음과 같다. + +- bootstrap 이전 runtime config와 release 검증 +- 인증 credential을 UI에 노출하지 않는 session seam +- bounded retry와 idempotency 정책 +- HTTP envelope 및 payload runtime validation +- 저장소 key registry와 민감정보 저장 금지 +- TanStack Query client 기본 정책 +- semantic telemetry allowlist +- render boundary와 async state surface +- route registry와 lazy page + +그러나 현재 실행 경로에는 다음 불일치가 있다. + +1. `src/bootstrap/composition-root.js`가 `application`을 만들지만 + `src/bootstrap/main.jsx`는 이를 사용하지 않고 `authSession`, + `storage`, `telemetry`를 presentation에 직접 전달한다. +2. `createApplication`이 input use case 대신 cache, storage, telemetry + output port를 그대로 노출한다. +3. `QueryClientProvider`는 존재하지만 실제 product route에서 + `useQuery` 또는 `useMutation`을 연결하는 query bridge가 없다. +4. route registry의 `paramsSchema`, `searchSchema`, `loadingSurface`, + `errorSurface`, `chunkId` 일부는 실행 route와 연결되지 않았다. +5. 제거 테스트는 `src/sample/contract-fixture`만 제거하며, sample API + operation, Zod schema, mapper, domain model과 query key는 다른 경로에 + 남는다. +6. runtime의 `REQUEST_TIMEOUT_MS`, `MAX_RETRY_ATTEMPTS`는 검증되지만 + concrete HTTP client 구성에 전달되지 않는다. + +이 문서의 목표 구조는 기존 기반을 폐기하는 것이 아니라 이러한 +불일치를 제거하는 것이다. + +## 4. Inbound와 outbound 분류표 + +| 관심사 | 방향 | Port 소유자 | Adapter 예 | 기본 제공 여부 | +| --- | --- | --- | --- | --- | +| React page와 component | inbound | application input API 소비 | React | 필수 | +| Routing과 navigation | inbound | route input/controller | React Router | 필수 | +| Form submit과 validation 표시 | inbound | command input port 소비 | React form controller | 필수 | +| Server-state query hook | inbound bridge | application input API 소비 | TanStack Query hook | 필수 | +| 외부 push event 처리 | inbound | event input port | WebSocket/SSE listener | 선택 | +| 도메인 API 접근 | outbound | application | Fetch gateway | 필수 | +| 인증 session | outbound | application | 외부 auth owner/SDK | 필수 seam | +| Credential attachment | outbound | transport 또는 auth integration | auth request decorator | 필수 seam | +| Preference persistence | outbound | application | browser storage | 필수 | +| 시간·ID·random | outbound | application | browser platform | 필수 | +| Logging·telemetry | outbound | application | console/remote sink | 필수 | +| Offline persistence | outbound | application | IndexedDB | 선택 | +| Feature flag | outbound | application | flag SDK | 선택 | +| Locale/message/formatter | UI platform | React inbound 계약 | `Intl` + local catalog | 필수 seam, vendor 선택 | +| 외부 오류 수집 | outbound | application | error-reporting SDK | 선택 | + +WebSocket은 한 단어로 항상 inbound 또는 outbound가 아니다. 연결을 열고 +메시지를 전송하는 기능은 application이 요구하는 output capability일 수 +있고, 수신된 메시지를 use case로 전달하는 handler는 inbound adapter다. +두 책임을 하나의 거대한 interface로 합치지 않는다. + +## 5. 왜 `presentation`이 inbound adapter인가 + +React component는 사용자의 클릭, 입력, URL 이동을 해석한다. 그 결과를 +application input port가 이해하는 command나 query로 바꾸고, 반환된 +view state를 HTML로 표현한다. 이는 전형적인 driving/inbound adapter다. + +```text +Button click + -> React event handler + -> CreateReferenceItem command + -> CreateReferenceItem input port + -> use case +``` + +따라서 `presentation`이 adapter라는 사실은 이름에 `adapter`가 붙었는지와 +관계없다. 다음 두 구조 모두 가능하다. + +```text +src/presentation # presentation을 inbound로 문서화 +src/adapters/outbound +``` + +또는 더 명시적으로: + +```text +src/adapters/inbound/react +src/adapters/outbound +``` + +이 저장소의 장기 목표는 두 번째 구조다. 점진적 전환 중에는 +`presentation = inbound/react`로 동일하게 취급한다. + +Presentation이 inbound라는 이유로 모든 component가 use case interface를 +가져야 하는 것은 아니다. `Button`, `Card`, `Dialog` 같은 순수 UI primitive는 +입력 props와 DOM behavior만 소유한다. page, controller hook, route +loader/action처럼 application 작업을 시작하는 경계에서 input port를 +사용한다. + +## 6. 브라우저가 서버 데이터 기술을 직접 연결하지 않는 이유 + +브라우저 adapter는 Redis, PostgreSQL, MongoDB, Kafka, MinIO 같은 서버 +인프라에 직접 연결하지 않는다. + +그 이유는 다음과 같다. + +- 브라우저 bundle과 runtime config는 사용자가 읽을 수 있어 서버 + credential을 안전하게 보관할 수 없다. +- 데이터베이스나 broker를 인터넷에 직접 노출하면 네트워크와 권한 경계가 + 무너진다. +- 브라우저는 신뢰할 수 없는 실행 환경이므로 authorization과 데이터 + invariant를 강제할 수 없다. +- DB driver, broker protocol, connection pool과 migration은 브라우저의 + lifecycle 및 bundle 제약과 맞지 않는다. +- 클라이언트 버전은 사용자마다 다를 수 있으므로 저장소 schema와 직접 + 결합하면 호환성 관리가 불가능해진다. + +브라우저는 HTTPS API, BFF, GraphQL, WebSocket 또는 SSE처럼 서버가 +노출한 제한된 계약과 통신한다. + +```text +Browser + -> HTTP/WebSocket adapter + -> Backend API/BFF + -> Redis/PostgreSQL/MongoDB/Kafka/MinIO +``` + +MinIO object URL을 받아 파일을 업로드하는 경우에도 브라우저 adapter는 +MinIO 관리자 credential이나 내부 API를 소유하지 않는다. 서버가 발급한 +짧은 수명의 제한된 URL과 업로드 정책만 사용한다. + +## 7. 권장 목표 디렉터리 구조 + +```text +src/ + core/ + kernel/ + result.ts + failure.ts + identifiers.ts + domain/ + application/ + ports/ + in/ + out/ + use-cases/ + policies/ + + adapters/ + inbound/ + react/ + app/ + application-provider.tsx + app-router.tsx + routing/ + query/ + pages/ + components/ + design-system/ + state/ + outbound/ + http/ + fetch-transport.ts + request-builder.ts + response-decoder.ts + retry-decorator.ts + auth/ + persistence/ + observability/ + platform/ + + features/ + reference-feature/ + domain/ + application/ + ports/ + in/ + out/ + use-cases/ + adapters/ + inbound/ + react/ + outbound/ + http/ + contracts/ + index.ts + + bootstrap/ + composition-root.ts + runtime-config.ts + main.tsx +``` + +`core`에는 모든 feature가 공유하는 작은 kernel과 truly cross-cutting +application capability만 둔다. `shared`, `common`, `utils` 같은 이름으로 +기술과 업무 규칙을 무제한 혼합하지 않는다. + +`features/reference-feature`는 구조를 설명하기 위한 완전한 수직 +슬라이스다. 이 폴더를 삭제하고 route 등록 한 곳만 제거했을 때 +typecheck, architecture check, test와 build가 모두 통과해야 한다. + +## 8. Input port 설계 규칙 + +### 8.1 사용자의 의도를 이름으로 표현한다 + +좋은 예: + +```ts +export interface ListReferenceItems { + execute( + query: ListReferenceItemsQuery, + context: RequestContext, + ): Promise>; +} +``` + +피해야 할 예: + +```ts +export interface HttpClient { + get(url: string): Promise; +} +``` + +Input port는 “HTTP GET을 실행한다”가 아니라 “항목을 조회한다”를 +표현한다. + +### 8.2 React와 browser type을 포함하지 않는다 + +Input port에 다음 type을 넣지 않는다. + +- `ReactNode`, `SyntheticEvent` +- `Request`, `Response`, `Headers` +- `QueryClient`, `UseQueryResult` +- `Location`, router navigate function +- `Storage`, `Window`, `Document` + +Inbound adapter가 해당 type을 application command와 query로 변환한다. + +### 8.3 예측 가능한 실패를 typed result로 반환한다 + +검증 실패, 인증 필요, conflict, network failure처럼 사용자 흐름에 +포함되는 실패는 `Result`로 반환한다. programmer error와 +불변식 위반을 모두 일반 API 실패로 숨기지는 않는다. + +```ts +export type Result = + | Readonly<{ ok: true; value: Value }> + | Readonly<{ ok: false; error: Failure }>; +``` + +### 8.4 Input port를 기술별로 합치지 않는다 + +`ApplicationService` 한 개에 모든 메서드를 계속 추가하지 않는다. +feature 단위 또는 응집된 capability 단위로 분리한다. + +```ts +export interface ReferenceFeatureApplication { + readonly list: ListReferenceItems; + readonly create: CreateReferenceItem; +} +``` + +## 9. Output port 설계 규칙 + +### 9.1 Application이 port를 소유한다 + +도메인별 gateway는 feature의 application 경로에 둔다. + +```ts +export interface ReferenceItemGateway { + list( + query: ListReferenceItemsQuery, + context: RequestContext, + ): Promise>; + + create( + command: CreateReferenceItemCommand, + context: RequestContext, + ): Promise>; +} +``` + +Fetch adapter는 이 interface를 구현하지만 application은 Fetch adapter를 +import하지 않는다. + +### 9.2 기술보다 capability를 표현한다 + +다음 이름을 우선한다. + +- `ReferenceItemGateway` +- `SessionGateway` +- `PreferenceStore` +- `Clock` +- `IdGenerator` +- `Logger` + +다음처럼 concrete 기술을 core port 이름에 포함하지 않는다. + +- `AxiosPort` +- `LocalStoragePort` +- `RedisPort` +- `TanStackPort` +- `SentryPort` + +### 9.3 Interface segregation을 지킨다 + +화면의 session 작업과 HTTP credential 부착은 호출 주체가 다르므로 +분리한다. + +```ts +export interface SessionGateway { + snapshot(): SessionSnapshot; + subscribe(listener: () => void): () => void; + beginSignIn(returnTo?: string): Promise; + signOut(): Promise; + recover(): Promise; +} + +export interface CredentialAttacher { + attach(request: Request): Promise; +} +``` + +`Request` type을 완전히 application 밖으로 유지하려면 +`CredentialAttacher`는 outbound HTTP 내부 계약으로 둔다. Session use +case는 `SessionGateway`만 안다. + +### 9.4 Clock과 ID도 concrete 구현과 분리한다 + +Application port 파일에 `Date.now`, `setTimeout`, `crypto.randomUUID` +구현을 함께 두지 않는다. + +```text +core/application/ports/out/clock.ts +adapters/outbound/platform/browser-clock.ts +adapters/outbound/platform/browser-id-generator.ts +``` + +### 9.5 범용 HTTP client를 application port로 노출하지 않는다 + +범용 transport는 outbound adapter 내부의 재사용 기술이다. 각 feature의 +gateway adapter가 transport를 사용해 DTO를 domain model로 매핑한다. + +```text +Application -> ReferenceItemGateway +ReferenceItemHttpGateway -> HttpTransport +HttpTransport -> fetch +``` + +이렇게 하면 application이 URL, method, header, response envelope를 알지 +않으며 API 기술을 교체할 수 있다. + +## 10. Composition root와 `ApplicationProvider` + +### 10.1 조립 순서 + +권장 조립 순서는 다음과 같다. + +```text +runtime config 검증 + -> release coherence 검증 + -> platform adapters 생성 + -> outbound gateways 생성 + -> use cases 생성 + -> application input API 생성 + -> React infrastructure provider 생성 + -> ApplicationProvider + -> Router +``` + +예: + +```ts +export function createApplicationComposition(runtime: RuntimeConfig) { + const clock = createBrowserClock(); + const logger = createRedactedLogger(runtime); + const sessionGateway = createExternalSessionGateway(runtime.auth); + const httpTransport = createHttpTransport({ + baseUrl: runtime.apiBaseUrl, + timeoutMs: runtime.requestTimeoutMs, + maxRetryAttempts: runtime.maxRetryAttempts, + logger, + }); + const referenceGateway = createReferenceItemHttpGateway(httpTransport); + + const reference = Object.freeze({ + list: createListReferenceItems({ gateway: referenceGateway, clock }), + create: createCreateReferenceItem({ gateway: referenceGateway, clock }), + }); + + const session = createSessionApplication({ gateway: sessionGateway, logger }); + + return Object.freeze({ + application: Object.freeze({ reference, session }), + infrastructure: Object.freeze({ + queryClient: createQueryClient(), + themeStorage: createThemeStorage(), + }), + }); +} +``` + +### 10.2 `ApplicationProvider`가 노출할 것 + +`ApplicationProvider`는 presentation이 호출할 input port만 노출한다. + +```ts +export interface ApplicationApi { + readonly reference: ReferenceFeatureApplication; + readonly session: SessionApplication; +} +``` + +다음 concrete 객체는 provider value에 넣지 않는다. + +- Fetch client +- raw HTTP client +- browser storage +- telemetry SDK +- auth SDK owner +- domain gateway adapter + +QueryClient처럼 React infrastructure provider가 직접 요구하는 concrete +객체는 bootstrap에서 해당 provider에 전달할 수 있다. 다만 feature page가 +QueryClient를 직접 가져가 application을 우회하지 않도록 query bridge를 +둔다. + +### 10.3 현재 runtime의 교정 목표 + +현재 `composition.application`이 만들어지고도 사용되지 않는 상태를 +허용하지 않는다. 다음 중 하나를 CI에서 검증한다. + +- `main`은 `composition.application`을 `ApplicationProvider`에 전달한다. +- presentation production source는 `composition.ports`나 concrete + outbound adapter를 import하거나 props로 받지 않는다. + +## 11. TanStack Query bridge + +TanStack Query는 두 역할을 가진다. + +1. QueryClient와 cache는 React 서버 상태 infrastructure다. +2. `useQuery`, `useMutation`은 React lifecycle을 application 호출에 + 연결하는 inbound bridge다. + +따라서 application이 TanStack type을 알면 안 되지만, inbound React +adapter 내부의 feature hook은 TanStack을 사용할 수 있다. + +```ts +export function useReferenceItems(query: ReferenceListQuery) { + const application = useApplication(); + + return useQuery({ + queryKey: referenceQueryKeys.list(query), + queryFn: async ({ signal }) => { + const result = await application.reference.list.execute(query, { + routeId: "REFERENCE_LIST", + operationId: "LIST_REFERENCE_ITEMS", + signal, + }); + + if (!result.ok) { + throw toQueryFailure(result.error); + } + return result.value; + }, + }); +} +``` + +Page는 `useQuery`를 직접 조합하지 않고 feature hook을 사용한다. + +```text +ReferenceListPage + -> useReferenceItems + -> ListReferenceItems input port + -> ReferenceItemGateway output port +``` + +Query bridge는 다음을 한곳에서 책임진다. + +- canonical query key +- AbortSignal 전달 +- application failure를 UI query failure로 투영 +- stale/refreshing 상태 변환 +- mutation 성공 후 namespace invalidation +- optimistic update와 rollback policy +- retry 소유권 + +HTTP transport가 retry를 소유하면 TanStack Query의 자동 retry는 기본적으로 +끄고, 두 계층에서 중복 retry하지 않는다. UI의 “다시 시도” 버튼은 새 +사용자 시도이며 transport의 자동 retry 횟수와 구분한다. + +Application이 실제로 cache 일관성 자체를 업무 규칙으로 요구하는 경우에만 +별도 `CachePort`를 둔다. 일반적인 server-state 표시를 위해 TanStack +Query의 모든 기능을 `read/write/invalidate` 세 메서드로 추상화하지 않는다. + +## 12. 상태 관리 경계 + +모든 상태를 한 global store에 넣지 않는다. + +| 상태 종류 | 기본 도구 | 저장 위치 | +| --- | --- | --- | +| 단일 component 표시 상태 | `useState`, `useReducer` | inbound React | +| URL과 공유 가능한 상태 | typed route params/search | router | +| 서버에서 소유한 상태 | TanStack Query bridge | inbound React infrastructure | +| session처럼 외부 store가 소유한 상태 | `useSyncExternalStore` | provider/bridge | +| theme 같은 작은 cross-page 설정 | context + preference port | provider/application | +| 복잡한 장기 client workflow | reducer 또는 state machine | feature application/inbound | +| 새로고침 후 유지할 공개 설정 | persistence output port | outbound persistence | + +Zustand, Redux Toolkit, Jotai, XState 등은 실제 상태 복잡성이 확인될 때 +선택한다. 기본 skeleton에는 상태 분류 규칙과 작은 typed external-store +예제가 필요하지만 범용 global store 의존성은 필수가 아니다. + +Global store를 도입할 때도 domain invariant를 selector와 action 내부에 +숨기지 않는다. 업무 규칙은 domain/application에 두고 store adapter는 +입력과 표시 상태를 연결한다. + +## 13. HTTP outbound adapter 계약 + +공통 HTTP transport가 지원해야 하는 최소 기능은 다음과 같다. + +- base URL과 상대 path의 안전한 결합 +- typed path parameter encoding +- canonical search parameter serialization +- parsed/normalized request body 전송 +- Content-Type과 response envelope 검증 +- operation별 auth 정책 +- runtime 기본 timeout과 operation override +- AbortSignal과 navigation cancellation +- safe/keyed/non-idempotent retry 구분 +- bounded exponential backoff와 `Retry-After` +- idempotency key의 logical request 단위 재사용 +- 401 recovery 1회 제한 +- request/trace ID의 안전한 투영 +- raw request/response/token을 버리는 error normalization +- terminal failure logging과 telemetry + +Operation registry는 문자열을 모아 둔 표가 아니라 TypeScript map으로 +요청과 응답 type을 연결해야 한다. + +```ts +interface ApiOperationMap { + LIST_REFERENCE_ITEMS: { + request: ListReferenceItemsRequest; + response: ReferenceItemListDto; + }; + CREATE_REFERENCE_ITEM: { + request: CreateReferenceItemRequest; + response: ReferenceItemDto; + }; +} +``` + +Zod 등 runtime schema가 반환한 `data`를 실제 request와 mapper 입력에 +사용한다. `safeParse` 성공 여부만 확인하고 원본 값을 계속 사용하지 않는다. + +## 14. 인증과 token 소유권 + +이 skeleton은 일반적인 browser token manager를 기본 제공하지 않는다. +이는 누락이 아니라 보안 기본값이다. + +권장 순서는 다음과 같다. + +1. 가능하면 BFF와 HttpOnly/Secure/SameSite cookie를 사용한다. +2. 외부 인증 SDK가 필요하면 SDK adapter가 token 획득, 갱신, 저장을 + 소유한다. +3. application과 presentation에는 credential이 아닌 session state와 + sign-in/sign-out use case만 노출한다. +4. HTTP adapter는 opaque credential attachment capability만 사용한다. +5. localStorage나 일반 application store에 access/refresh token을 넣지 + 않는다. + +SPA가 직접 bearer token을 사용해야 하는 프로젝트는 별도 보안 검토 후 +memory 중심 token owner adapter를 구현한다. 그 경우에도 이 저장소의 +`AUTH_TOKEN` storage 금지 계약을 우회하지 않는다. + +## 15. Error, validation, logger 경계 + +### 15.1 Error + +오류는 최소한 다음 경계를 거친다. + +```text +unknown thrown value + -> outbound adapter normalization + -> typed application failure + -> query/controller projection + -> localized safe user message +``` + +UI에는 다음을 전달하지 않는다. + +- raw stack +- backend message/details +- request/response body +- authorization header +- raw URL과 query +- storage value + +### 15.2 Validation + +Validation은 목적별로 분리한다. + +| 위치 | 검증 대상 | +| --- | --- | +| bootstrap | runtime config, release manifest | +| route inbound adapter | params와 search | +| form/controller | 사용자 입력과 field feedback | +| outbound API adapter | request DTO와 response DTO | +| domain | invariant와 value object | + +Form schema와 API request schema가 같은 모양이어도 역할이 다르므로 +무조건 하나로 합치지 않는다. 필요한 경우 application command로 +명시적으로 변환한다. + +### 15.3 Logger와 telemetry + +Logger와 telemetry는 같은 것이 아니다. + +- Logger: 운영 진단을 위한 level 기반 structured record +- Telemetry: registry에 정의된 semantic event와 metric +- Error reporter: 예외 집계와 release correlation + +기본 `Logger` output port는 safe context만 받는다. + +```ts +export interface Logger { + debug(message: string, context?: SafeLogContext): void; + info(message: string, context?: SafeLogContext): void; + warn(message: string, context?: SafeLogContext): void; + error(message: string, context?: SafeLogContext): void; +} +``` + +개발 환경에는 redacted console adapter, production에는 allowlist 기반 +remote adapter, 테스트에는 recording 또는 no-op adapter를 연결한다. +민감정보 redaction은 각 호출자의 선의가 아니라 adapter와 contract에서 +강제한다. + +## 16. Feature 경계와 removable reference feature + +Reference feature는 단순 UI fixture가 아니라 다음 경로를 모두 실행해야 +한다. + +```text +registered route + -> lazy page + -> controller/query bridge + -> application input port + -> use case + -> output gateway port + -> HTTP adapter + -> request schema + -> response schema + -> DTO mapper + -> domain model + -> view model + -> loading/empty/success/error UI +``` + +Reference feature 폴더가 소유해야 할 항목: + +- domain model과 value object +- input/output port +- use case +- API operation과 DTO schema +- HTTP gateway와 mapper +- query key와 query/mutation bridge +- route page와 feature component +- unit/component/integration/E2E test + +공통 registry가 필요한 경우 reference feature가 registration object를 +export하고 bootstrap 또는 route composition이 이를 수집한다. sample +operation을 전역 core registry 안에 하드코딩하지 않는다. + +제거 테스트는 다음을 수행해야 한다. + +1. `src/features/reference-feature` 전체 삭제 +2. reference route registration 삭제 +3. reference test 삭제 또는 제외 +4. 잔여 import와 registry owner 검색 +5. typecheck +6. architecture check +7. production build +8. built asset에서 reference operation/schema 문자열 부재 확인 + +제품 feature는 reference feature를 import할 수 없다. Reference feature도 +제품에서만 존재하는 feature를 import하지 않는다. + +## 17. 필수 adapter catalog + +| Adapter | 책임 | 기본 구현 | +| --- | --- | --- | +| Runtime config loader | public runtime config fetch와 검증 | Fetch + Zod | +| Release manifest loader | build/release coherence 확인 | Fetch + Zod | +| Browser clock | 현재 시간과 abortable sleep | browser timer | +| ID generator | idempotency/correlation용 opaque ID | `crypto.randomUUID` | +| HTTP transport | request, timeout, retry, decode | Fetch | +| Domain API gateway | DTO와 domain 변환 | feature HTTP gateway | +| Session gateway | session snapshot와 login lifecycle | external owner | +| Credential attacher | opaque request credential 처리 | auth owner | +| Preference store | 공개 preference persistence | browser storage | +| Query infrastructure | server-state cache 정책 | TanStack Query | +| Query bridge | input port와 React query 연결 | feature hook | +| Logger | redacted structured diagnostics | console/no-op/remote | +| Telemetry | allowlist semantic event 전달 | best-effort sink | +| Browser lifecycle | visibility/pagehide/online 상태 | browser event adapter | +| Router | URL을 page/controller로 변환 | React Router | +| Design system | 접근 가능한 primitive와 token | React/CSS | +| Locale/formatter | message key와 날짜·숫자·방향성 | local locale facade | +| UI workshop/visual gate | 격리 상태·interaction·회귀 검증 | Storybook + local Playwright | + +필수라는 의미는 모든 concrete library를 고정한다는 뜻이 아니다. 해당 +capability의 기본 정책, port 또는 안전한 no-op 구현과 composition +위치가 정의되어 있어야 한다는 뜻이다. + +## 18. 선택 adapter catalog + +| Adapter | 도입 조건 | 기본 상태 | +| --- | --- | --- | +| WebSocket/SSE | 실시간 server event 필요 | 미설치 recipe | +| IndexedDB | 큰 offline data 또는 durable queue 필요 | 미설치 recipe | +| Service Worker/PWA | offline shell과 installability 필요 | 미설치 recipe | +| Offline mutation queue | 재연결 후 명령 재처리 필요 | 미설치 recipe | +| Feature flag | remote rollout/kill switch 필요 | 미설치 recipe | +| Translation catalog vendor | 원격 catalog·복수 namespace 운영 필요 | 기본 locale facade 뒤에 미설치 | +| Analytics | 사용자 동의 기반 product analytics 필요 | 미설치 recipe | +| Error-reporting SDK | 운영 예외 집계 필요 | 미설치 recipe | +| OpenTelemetry | 조직 trace 연계 필요 | 미설치 recipe | +| Web Worker | CPU 작업이 main thread를 막음 | 미설치 recipe | +| Notification | 사용자 권한 기반 browser notification 필요 | 미설치 recipe | +| Clipboard/File/Media | 해당 browser capability 필요 | 미설치 recipe | +| Image CDN adapter | responsive image transform 필요 | 미설치 recipe | +| Virtualization | 대량 list rendering이 측정상 병목 | 미설치 recipe | +| OpenAPI generator | backend 계약에서 client 생성 필요 | 미설치 recipe | +| Zustand/Redux/Jotai | 복잡한 cross-page client state 확인 | 미설치 recipe | +| XState 등 state machine | 장기 workflow 상태 전이가 복잡함 | 미설치 recipe | +| Cloud visual-review service | 외부 승인·호스팅 workflow 필요 | 로컬 Storybook/visual gate 뒤에 미설치 | + +선택 adapter는 “나중에 쓸 수 있으므로” 기본 bundle에 넣지 않는다. 도입 +조건, 보안 영향, bundle 비용과 제거 방법이 확인된 경우에만 추가한다. + +## 19. 새 outbound adapter 추가 recipe + +### 단계 1: 해결할 문제를 capability로 정의한다 + +예: “LaunchDarkly를 붙인다”가 아니라 “feature flag를 평가한다”로 +정의한다. + +### 단계 2: Port가 정말 필요한지 판단한다 + +- application 정책이 이 capability를 호출하는가? +- React 화면 한 곳의 순수 표현 문제인가? +- 기존 port로 충분한가? +- 기술 교체와 테스트 격리가 실제로 필요한가? + +Application이 호출하지 않는 순수 UI library에는 억지 output port를 +만들지 않는다. + +### 단계 3: Application-owned output port를 작성한다 + +- 기술 중립 이름 +- 최소 메서드 +- typed input/output +- timeout/cancellation 필요 여부 +- 예측 가능한 failure union +- 민감정보 분류 + +### 단계 4: Contract와 정책을 작성한다 + +- runtime config +- retry/idempotency +- cache와 TTL +- fallback +- telemetry +- security/redaction +- browser compatibility + +### 단계 5: Concrete adapter를 구현한다 + +`src/adapters/outbound/` 또는 feature의 +`adapters/outbound`에 구현한다. Concrete SDK type은 이 경로 밖으로 +노출하지 않는다. + +### 단계 6: Composition root에서만 연결한다 + +Application이나 page에서 concrete constructor를 호출하지 않는다. + +### 단계 7: 테스트한다 + +- port contract test +- adapter unit test +- failure normalization +- timeout/cancellation +- redaction +- integration test +- deliberately failing negative fixture + +### 단계 8: 운영 계약을 갱신한다 + +- registry와 runtime schema +- dependency inventory +- bundle budget +- security policy +- runbook +- adapter catalog와 제거 절차 + +## 20. 새 inbound adapter 추가 recipe + +외부 이벤트를 application에 전달하는 adapter는 다음 순서를 따른다. + +1. 어떤 외부 event가 어떤 application 의도를 나타내는지 정의한다. +2. event payload를 runtime schema로 검증한다. +3. raw payload를 application command로 매핑한다. +4. input port를 호출한다. +5. duplicate, ordering, cancellation 정책을 정의한다. +6. 실패를 raw event source로 무한 재전파하지 않는다. +7. connect/disconnect lifecycle과 subscription cleanup을 테스트한다. + +예를 들어 WebSocket listener가 받은 JSON을 domain object로 바로 +사용하지 않는다. schema 검증과 command mapping 후 input port를 호출한다. + +## 21. 새 feature 추가 recipe + +### 단계 1: Feature 경계를 선언한다 + +- feature 이름과 owner +- 사용자 목표 +- route +- 입력 command/query +- 외부 gateway +- 성공/빈 화면/오류/권한 상태 + +### 단계 2: Domain을 작성한다 + +- entity/value object +- invariant +- 순수 policy +- framework와 transport type 금지 + +Domain 규칙이 없는 단순 표시 feature라면 빈 domain layer를 억지로 +만들지 않는다. + +### 단계 3: Input/output port와 use case를 작성한다 + +- input port는 사용자 의도 +- output port는 외부 capability +- `Result` failure 정의 +- cancellation context 정의 + +### 단계 4: Outbound gateway를 작성한다 + +- operation registration +- request DTO schema +- path/search/body mapping +- response DTO schema +- domain mapper +- error mapping + +### 단계 5: Inbound query/controller bridge를 작성한다 + +- canonical query key +- application input 호출 +- async state projection +- mutation invalidation 또는 optimistic rollback +- retry 버튼 behavior + +### 단계 6: Route를 등록한다 + +- route ID와 path +- typed params/search +- access hint +- lazy chunk +- loading/error surface +- title/navigation + +Registry metadata와 실제 route object를 별도로 두 번 작성하지 않는다. +하나의 typed definition에서 route object와 navigation을 생성한다. + +### 단계 7: Page와 상태를 조립한다 + +- page header와 focus 이동 +- loading +- empty +- success +- refreshing/stale +- terminal error +- 401/403/404 +- mutation pending/conflict +- responsive/keyboard/screen-reader + +### 단계 8: 테스트한다 + +- domain/use case unit +- port contract +- outbound adapter + MSW integration +- query/controller hook +- component +- route integration +- Playwright E2E +- axe와 수동 접근성 scope + +### 단계 9: 제거 가능성을 확인한다 + +Reference feature라면 전체 폴더 삭제 후 build가 통과해야 한다. 제품 +feature라면 다른 feature가 내부 구현 경로를 직접 import하지 않고 public +entry point만 사용해야 한다. + +## 22. Routing 규칙 + +Route definition은 다음 값을 type-safe하게 결합한다. + +- route ID +- path와 parameter type +- search schema와 normalized type +- access hint +- lazy component +- loading surface +- error boundary +- title +- navigation metadata +- prefetch policy + +Client route access는 UX 정책일 뿐 authorization이 아니다. 서버가 +최종 권한을 검증해야 한다. + +다음 규칙을 적용한다. + +- string path를 page에 하드코딩하지 않는다. +- URL search를 `Object.fromEntries` 결과 그대로 신뢰하지 않는다. +- route parameter를 domain ID로 사용하기 전에 검증한다. +- route 전환 시 진행 중 request에 AbortSignal을 전달한다. +- chunk load 실패는 release mismatch 정책에 따라 한 번만 복구한다. +- redirect loop guard는 실제 redirect 경로에 연결하거나 제거한다. +- browser-history routing을 사용하면 hosting의 SPA fallback을 release 계약으로 + 검증한다. + +## 23. Design system 경계 + +Design system은 inbound React adapter의 공유 UI capability다. + +최소 public surface: + +- semantic token +- typography와 spacing +- Button, IconButton +- TextField, TextArea, Select +- Checkbox, Radio, Switch +- Card, Alert, Badge +- Dialog, Drawer +- Loading, Empty, Error, Forbidden surface +- Tooltip, Tabs, Toast +- Table/List, Pagination +- Form field와 validation message + +Icon library는 design-system의 `Icon`과 `IconButton` 뒤에서 사용한다. +Page가 `lucide-react` 등 concrete icon package를 무제한 import하지 않도록 +허용 icon과 접근성 규칙을 한곳에서 관리한다. 정적 named import로 +tree-shaking을 유지하고 전체 icon registry를 runtime dynamic import하지 +않는다. + +Design system은 domain use case를 호출하지 않는다. Feature component가 +design-system primitive를 조합하고 controller hook을 통해 application을 +호출한다. + +## 24. 금지 패턴 + +다음 패턴은 architecture gate에서 차단해야 한다. + +### 경계 우회 + +- page가 `src/adapters/outbound`를 import +- presentation이 raw `fetch`, `localStorage`, auth SDK를 직접 사용 +- application이 React, Router, TanStack Query를 import +- domain이 application, browser global 또는 framework를 import +- bootstrap 외부에서 concrete adapter를 생성 +- `composition.ports`를 product presentation에 직접 전달 + +### Port 오용 + +- application port에 Axios, TanStack, SDK type 노출 +- input port 이름을 HTTP method나 UI event 이름으로 정의 +- 모든 capability를 하나의 `ApplicationService` 또는 `StorePort`로 합침 +- auth UI operation과 credential attachment를 하나의 과대 interface로 + 강제 +- application이 raw cache read/write를 page에 재노출 + +### HTTP와 retry + +- GET filter를 cache key에만 반영하고 request에서 누락 +- schema parse 결과를 버리고 원본 body 전송 +- keyed mutation retry 시 idempotency key 재생성 +- HTTP와 TanStack이 동시에 자동 retry +- navigation abort를 unknown error로 기록 +- validation early return에서 timeout/listener cleanup 누락 + +### 상태 + +- 서버 상태를 generic global store에 복제 +- URL에 있어야 할 filter를 별도 store에만 보관 +- token을 React state, persisted store, localStorage에 저장 +- domain invariant를 Zustand/Redux action 내부에만 구현 + +### 오류와 관측 + +- raw backend message 또는 stack을 사용자에게 표시 +- request/response body, raw URL, token을 logger/telemetry에 전달 +- `console.error`를 production error strategy로 간주 +- registry에 event만 선언하고 실제 발생 경로에서 emit하지 않음 + +### Registry와 예제 + +- route metadata를 선언하고 실제 route가 사용하지 않음 +- `contracts`를 모든 계층이 자유롭게 import하는 우회 폴더로 사용 +- product가 reference feature를 import +- reference feature를 삭제해도 sample domain/API schema가 초기 bundle에 + 남음 + +### 외부 인프라 + +- 브라우저에서 Redis, PostgreSQL, MongoDB, Kafka, MinIO 관리자 API에 + 직접 연결 +- server credential을 build/runtime config에 포함 +- 클라이언트 route guard를 authorization으로 간주 + +## 25. 테스트와 증적 기준 + +경계별 최소 테스트는 다음과 같다. + +| 대상 | 최소 검증 | +| --- | --- | +| Input use case | 성공, 각 failure branch, cancellation | +| Output port | contract fixture와 negative fixture | +| HTTP transport | path/query/body, timeout, retry, 401, abort, schema | +| DTO mapper | valid mapping과 invariant breach normalization | +| Query bridge | query key, loading, refresh, mutation invalidation, rollback | +| Route | registry-tree 일치, params/search, access, 404 | +| Provider | 실제 composition application 주입 | +| Logger/telemetry | allowlist, redaction, sink failure | +| Design system | keyboard, focus, label/error association, axe | +| Reference feature | full vertical integration과 complete removal | + +TypeScript 전환 후에는 source뿐 아니라 test와 architecture/security +fixture도 typecheck 또는 lint 대상이어야 한다. `.ts/.tsx`가 JS 전용 glob을 +우회하지 않도록 한다. + +Coverage는 단순 report 생성이 아니라 branch/function/line threshold를 +blocking gate로 둔다. 수치만 올리기 위한 구현 세부 테스트보다 port +contract와 실패 분기를 우선한다. + +## 26. 완료 기준 + +### 26.1 Architecture + +- [ ] 모든 application 작업에 명시적인 input port가 있다. +- [ ] 모든 외부 capability는 application-owned output port 뒤에 있다. +- [ ] Presentation은 concrete outbound adapter를 모른다. +- [ ] `main`은 raw ports 대신 application API를 제공한다. +- [ ] `contracts`는 unrestricted 우회 계층이 아니다. +- [ ] dependency rule과 문서의 source of truth가 하나다. +- [ ] TypeScript와 TSX도 동일한 architecture/security lint를 받는다. + +### 26.2 Runtime composition + +- [ ] runtime timeout/retry 설정이 실제 HTTP transport에 반영된다. +- [ ] QueryClient와 feature query bridge가 실제 route에서 동작한다. +- [ ] session UI API와 credential attachment가 분리되어 있다. +- [ ] logger와 telemetry가 HTTP/render/storage/cache failure 경로에 + 연결된다. +- [ ] page lifecycle에서 필요한 telemetry flush/cleanup이 수행된다. + +### 26.3 HTTP와 validation + +- [ ] path, search, body를 각각 검증하고 직렬화한다. +- [ ] schema가 반환한 normalized data를 실제 request에 사용한다. +- [ ] timeout과 AbortSignal listener가 모든 반환 경로에서 정리된다. +- [ ] retry는 runtime cap, idempotency와 `Retry-After`를 따른다. +- [ ] raw payload와 credential이 failure나 log에 포함되지 않는다. + +### 26.4 Routing과 상태 + +- [ ] route registry와 실행 route tree가 동일 source에서 생성된다. +- [ ] params/search schema가 실제 navigation에서 실행된다. +- [ ] loading/error/chunk/access metadata가 실행 behavior와 연결된다. +- [ ] local, URL, server, session, persisted state가 분류 규칙을 따른다. +- [ ] server state를 별도 global store에 중복 보관하지 않는다. + +### 26.5 Reference feature + +- [ ] route부터 API mapper와 화면까지 완전한 수직 경로가 실행된다. +- [ ] list/create 등 최소 query와 mutation 예제가 있다. +- [ ] loading/empty/error/refresh/conflict 상태가 있다. +- [ ] reference feature 전체 삭제 후 typecheck/test/build가 통과한다. +- [ ] built asset에 reference operation, schema, mapper가 남지 않는다. + +### 26.6 품질 + +- [ ] source와 test가 strict TypeScript 검사를 받는다. +- [ ] React Hooks와 JSX accessibility lint가 blocking이다. +- [ ] coverage threshold가 blocking이다. +- [ ] MSW integration, component, 3-engine E2E와 axe가 통과한다. +- [ ] bundle budget과 dependency inventory가 갱신된다. +- [ ] 선택 adapter는 도입 조건과 제거 절차가 문서화되어 있다. + +## 27. 구현 우선순위 + +### P0: 경계와 정확성 + +1. TypeScript 검사 도구와 `.ts/.tsx` architecture/security glob 준비 +2. input/output port 분리와 `ApplicationProvider` +3. HTTP path/query/body, parsed data, runtime retry/timeout, cleanup 교정 +4. Query bridge를 통한 실제 application 실행 +5. typed routing, registry-tree 단일화와 chunk recovery 실행 연결 +6. 완전한 removable reference feature와 제거 검증 + +### P1: 기본 플랫폼 완성도 + +1. error/result/validation/form kernel +2. 배타적인 async 상태와 page template +3. Logger와 telemetry 실제 wiring +4. design-system public API, icon wrapper와 headless interaction +5. locale/message/formatter와 pseudo-locale/RTL 경계 +6. Storybook, shared MSW, 시각 회귀와 built-output E2E +7. source/test TypeScript 전환 및 위험 기반 coverage/lint 강화 + +### P2: 프로젝트별 선택 capability + +WebSocket/SSE, offline/IndexedDB, Service Worker, feature flag, product +analytics, vendor error reporting, worker, virtualization, OpenAPI generation, +global store와 cloud visual-review service는 실제 프로젝트 요구와 측정 결과에 +따라 추가한다. + +P2 adapter를 많이 설치하는 것은 skeleton 완성도의 기준이 아니다. +안전한 경계, 도입 recipe, 테스트 계약과 제거 가능성이 준비되어 있는지가 +기준이다. diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md index 1134f27..5d278a0 100644 --- a/docs/architecture/layers.md +++ b/docs/architecture/layers.md @@ -22,6 +22,14 @@ The following edges are forbidden: `bootstrap` contains composition only. Business rules and page-specific orchestration belong to domain/application. +This table is the current coarse-grained rule. The +[ports, adapters, and feature-boundary target](./frontend-ports-adapters-and-boundaries.md) +defines the missing application input boundary, explains that `presentation` +acts as the inbound adapter, and separates current outbound adapters from +project-selected capabilities. The +[platform capability review](./frontend-platform-capability-review.md) records +where the current composition still bypasses this intended rule. + Architecture reports use this shape: ```json diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index ff860a0..dc7ffe7 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -18,14 +18,43 @@ flowchart LR Contracts --> Presentation ``` -Dependencies point inward. Presentation calls application use cases, adapters -implement application ports, and only the composition root selects concrete -adapters. Contract registries are the single named source for routes, API -operations, environment values, storage keys, errors, queries, telemetry, and -release tokens. +The intended dependency rule points inward: presentation calls application use +cases, adapters implement application ports, and only the composition root +selects concrete adapters. Contract registries are the intended named source +for routes, API operations, environment values, storage keys, errors, queries, +telemetry, and release tokens. The platform review below records where the +current runtime still bypasses that target or duplicates registry metadata. -The executable route tree is mounted only after runtime configuration and -release-manifest coherence pass. It receives the composed query client, +In ports-and-adapters terms, `presentation` is the current inbound adapter and +`adapters` contains the current outbound implementations. The target design +makes this role explicit, introduces application input ports, and prevents the +React tree from receiving raw outbound dependencies: + +```mermaid +flowchart LR + Driver[User, route, browser event] --> Inbound[React inbound adapter] + Inbound --> Input[Application input API] + Input --> UseCase[Use cases] + UseCase --> Output[Application output ports] + Output --> Outbound[HTTP, auth, storage, query, telemetry adapters] + Bootstrap2[Composition root] -. selects and injects .-> Input + Bootstrap2 -. selects and injects .-> Outbound +``` + +The current executable route tree is mounted only after runtime configuration +and release-manifest coherence pass. It receives the composed query client, credential-opaque session port, storage port, telemetry port, and immutable -build ID. Visible starter pages depend on those ports and contracts, never on a -concrete adapter or the removable sample fixture. +build ID. Visible starter pages do not depend on the removable sample fixture. + +This describes the current starter composition, not the completed target. The +capability review found that raw outbound capabilities still reach the React +tree, the composed application facade is not yet its entry point, and several +route, HTTP, recovery, telemetry, and sample-removal contracts are only +partially connected. Use the following documents for the evidence and migration +plan: + +- [Frontend platform capability review](./frontend-platform-capability-review.md) +- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md) +- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md) +- [Routing, pages, and patterns](./routing-pages-and-patterns.md) +- [Frontend platform implementation roadmap](./frontend-platform-implementation-roadmap.md) diff --git a/docs/architecture/routing-pages-and-patterns.md b/docs/architecture/routing-pages-and-patterns.md new file mode 100644 index 0000000..8f4bb80 --- /dev/null +++ b/docs/architecture/routing-pages-and-patterns.md @@ -0,0 +1,492 @@ +# 라우팅, 페이지 템플릿, 재사용 패턴 + +## 1. 목적 + +이 문서는 도메인과 무관하게 다음을 바로 구현할 수 있는 기준을 제공한다. + +- typed route와 안전한 URL +- session, permission, feature flag guard +- lazy chunk의 loading/error/recovery +- route 이동 시 focus, scroll, 취소, dirty form 처리 +- list, detail, form, status 등 공통 page template +- page controller와 application input use case의 연결 +- 프론트엔드에서 반복 사용하는 설계 패턴 + +## 2. 현재 상태와 문제 + +현재 구현에는 다음 장점이 있다. + +- route registry가 path와 access policy를 소유한다. +- route component를 lazy import한다. +- 앱 셸과 보호 route, not-found surface가 있다. +- route heading focus와 비동기/render error boundary가 있다. +- redirect loop와 chunk recovery에 대한 policy 함수가 일부 존재한다. + +하지만 `src/contracts/routes.js`의 metadata와 +`src/presentation/routes/app-router.jsx`의 executable route tree가 별도 수동 목록이다. +그 결과 다음 필드는 선언돼도 실제 행동을 보장하지 않는다. + +- params/search schema +- loading/error surface +- chunk ID +- route title/navigation label +- redirect loop guard +- chunk recovery policy + +페이지도 공통 `PageHeader` 외에는 각자 section과 class를 직접 조립한다. 목록, +상세, 편집, 오류 페이지의 반복되는 접근성·반응형·상태 표면을 기능 팀이 다시 +구현해야 한다. + +## 3. React Router mode 결정 + +[React Router 공식 mode 설명](https://reactrouter.com/start/modes)과 +[Data Mode custom setup](https://reactrouter.com/start/data/custom)은 +Declarative, Data, Framework Mode를 구분한다. + +저장소에는 현재 React Router `7.18.1`이 고정돼 있다. 구현 브랜치는 공식 문서의 +동일 버전 API를 기준으로 하고 router version upgrade를 Data Mode 구조 변경과 +같은 브랜치에 섞지 않는다. 위 공식 링크의 기본 표시 버전이 바뀌면 version +selector를 `7.18.1`로 맞춰 확인한다. + +| mode | 선택 조건 | 이 저장소에서의 판단 | +| --- | --- | --- | +| Declarative | React composition과 외부 data layer가 route data를 소유 | 현재 구현이 사용 중인 기준선 | +| Data | route object, blocker, scroll restoration, pending/navigation state가 필요 | 목표 skeleton의 navigation lifecycle에 적합 | +| Framework | route module, type-safe href, code splitting, SSR/static 전략을 framework가 소유 | client-only skeleton 기본값으로는 범위가 큼 | + +목표 결정: + +- client-only SPA와 TanStack Query/application use case를 유지한다. +- 현재 `BrowserRouter` 기반 Declarative Mode에서 `createBrowserRouter`와 + `RouterProvider` 기반 Data Mode로 이동한다. +- Data Mode를 선택하는 이유는 route object, navigation blocker, scroll + restoration, route error 경계를 일관되게 소유하기 위해서다. loader/action으로 + 서버 상태를 다시 소유하기 위해서가 아니다. +- loader/action을 추가할 때는 TanStack Query/application input을 prefetch하거나 + 호출하는 한 가지 소유 경로만 사용한다. +- 같은 데이터를 route loader와 TanStack Query가 각각 가져오지 않는다. +- SSR/static generation을 선택하기 전에는 Framework Mode를 기본값으로 만들지 + 않는다. + +전환 브랜치 전까지 현재 Declarative router에 새 custom scroll/blocker +implementation을 추가하지 않는다. 전환할 수 없는 프로젝트만 별도 ADR과 +`NavigationLifecycleAdapter`를 구현한다. + +## 4. route 계약과 runtime map + +### 4.1 두 종류의 레지스트리 + +직렬화 가능한 contract와 React implementation을 분리한다. + +```ts +export const routeContracts = { + home: { + id: "home", + path: "/", + access: "public", + navigation: "primary", + titleKey: "route.home.title", + loadingSurface: "page", + errorSurface: "page", + chunkId: "home", + }, + resourceDetail: { + id: "resourceDetail", + path: "/examples/resources/:resourceId", + access: "authenticated", + navigation: "hidden", + titleKey: "route.resourceDetail.title", + loadingSurface: "detail", + errorSurface: "detail", + chunkId: "reference-resource-detail", + }, +} as const satisfies RouteContractRegistry; +``` + +```tsx +export const routeRuntime = { + home: { + Component: lazy(() => import("../pages/home-page")), + paramsCodec: emptyParamsCodec, + searchCodec: emptySearchCodec, + }, + resourceDetail: { + Component: lazy(() => import("../features/resources/resource-detail-page")), + paramsCodec: resourceDetailParamsCodec, + searchCodec: resourceDetailSearchCodec, + }, +} satisfies Record; +``` + +요구 사항: + +- contract key와 `id`가 다르면 typecheck 실패 +- contract에는 함수, component, schema instance처럼 직렬화 불가능한 값을 넣지 않음 +- runtime map에는 실제 lazy component와 codec/guard만 둠 +- contract의 모든 route가 runtime에 있고 runtime의 모든 key가 contract에 있음 +- navigation은 contract에서 파생 +- build chunk manifest와 `chunkId` 대응을 검증 +- public runtime config나 server가 route component 이름을 임의 지정할 수 없음 + +### 4.2 params와 search codec + +URL은 외부 입력이다. page에서 `useParams()` 결과를 cast하지 않는다. + +```ts +const resourceDetailParamsSchema = z.object({ + resourceId: z.string().trim().min(1).max(100), +}); + +const resourceListSearchSchema = z.object({ + q: z.string().trim().max(100).catch(""), + page: z.coerce.number().int().min(1).catch(1), + sort: z.enum(["updated-desc", "name-asc"]).catch("updated-desc"), +}); +``` + +path params와 search params는 입력 형태와 serialization 규칙이 다르므로 같은 +interface로 뭉치지 않는다. 각각 parse와 serialize를 제공한다. + +```ts +interface PathParamsCodec { + parse( + input: Readonly>, + ): Result; + serialize(value: T): Readonly>; +} + +interface SearchParamsCodec { + parse(input: URLSearchParams): Result; + serialize(value: T): URLSearchParams; +} +``` + +규칙: + +- route input parse 실패와 backend 404를 구분한다. +- 알 수 없는 search key를 보존할지 제거할지 route별로 선언한다. +- default value를 URL에 항상 쓸지 생략할지 codec이 결정한다. +- array/date/boolean encoding을 feature마다 다르게 만들지 않는다. +- navigation link도 codec 기반 builder를 사용한다. +- query key에는 parsed value만 사용한다. +- 검색어·식별자를 telemetry에 기록하기 전에 sensitivity policy를 적용한다. + +### 4.3 route object 생성 + +하나의 factory가 다음을 조합한다. + +```text +route contract + + runtime component/codecs + + access guard + + feature flag guard + + suspense surface + + render/chunk error surface + + title/focus/scroll behavior + -> executable route object/tree +``` + +JSX에서 route별 ``를 다시 나열하지 않는다. nested layout이 필요한 경우 +contract에 parent ID를 두고 cycle/orphan/duplicate path를 registry gate에서 +검사한다. + +## 5. guard와 권한 + +### 5.1 guard 순서 + +권장 순서: + +1. runtime/bootstrap readiness +2. route 존재와 URL parse +3. feature flag +4. session readiness +5. authentication +6. coarse client permission hint +7. route component +8. server authorization result + +client guard는 UX 최적화일 뿐 보안 경계가 아니다. API/BFF가 항상 최종 권한을 +검사한다. + +### 5.2 guard 결과 + +```ts +type GuardDecision = + | { kind: "allow" } + | { kind: "redirect"; to: SafeLocation; reason: RedirectReason } + | { kind: "render"; surface: "auth-required" | "forbidden" | "not-found" }; +``` + +- redirect에는 origin route와 bounded return URL을 사용한다. +- 외부 redirect는 allowlist를 거친다. +- 동일한 route 쌍을 반복하는 redirect loop를 차단한다. +- session이 아직 resolving이면 forbidden으로 단정하지 않는다. +- server가 403을 반환하면 client claim을 신뢰해 화면을 계속 보여 주지 않는다. + +## 6. navigation lifecycle + +### 6.1 loading + +loading surface를 route metadata에 연결한다. + +| surface | 사용 | +| --- | --- | +| shell | 초기 앱 셸 진입 | +| page | 새로운 전체 페이지 | +| collection | table/list 구조 유지 | +| detail | metadata/content 구조 유지 | +| form | 필드 layout 구조 유지 | +| inline | 부분 action | + +cached data가 있으면 full-page skeleton으로 교체하지 않고 refreshing indicator를 +사용한다. `prefers-reduced-motion`에서 skeleton animation을 줄인다. + +### 6.2 error와 lazy chunk recovery + +route error boundary는 다음을 구분한다. + +- render/programmer error +- dynamic import/chunk load error +- application `AppFailure` +- URL parse failure +- not found + +chunk recovery 순서: + +1. 현재 build ID와 release manifest를 확인한다. +2. 새 manifest가 확인되고 같은 build에 대해 reload하지 않았다면 한 번만 reload한다. +3. 같은 failure가 반복되면 reload loop를 막는다. +4. 안전한 support surface와 trace/build ID를 표시한다. +5. recovery 결과를 redacted diagnostics에 기록한다. + +custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary는 +`location.key` 또는 route ID가 바뀌면 적절히 reset된다. + +### 6.3 focus와 scroll + +- route 성공 후 `main`의 page heading에 programmatic focus +- mouse 사용자가 불필요한 focus ring을 보지 않게 할 수는 있지만 keyboard focus + indication을 전역으로 제거하지 않음 +- modal/drawer가 닫히면 opener에 focus 복원 +- backward/forward navigation은 저장한 scroll 복원 +- 새 primary route는 top으로 이동 +- hash target은 fixed header offset과 focus 가능 여부를 처리 +- screen reader용 route title/live announcement는 중복 발표를 피함 + +### 6.4 취소와 dirty form + +- route 이동 시 진행 중 query signal을 취소한다. +- mutation은 취소 안전성이 명확할 때만 취소한다. +- dirty form blocker는 browser unload와 in-app navigation을 구분한다. +- 성공 저장 후 blocker를 해제한 다음 이동한다. +- autosave가 있는 form은 pending/failed 상태를 별도로 알린다. +- confirm dialog는 공통 accessible primitive를 사용한다. + +## 7. 페이지 템플릿 + +template은 데이터를 가져오거나 application을 호출하지 않는다. 슬롯, landmark, +focus target, responsive layout, 상태 위치만 소유한다. + +### 7.1 `StandardPageTemplate` + +슬롯: + +- breadcrumb 또는 back link +- title, description, status badge +- primary/secondary actions +- notices +- content +- contextual aside + +작은 화면에서 action wrapping 순서와 heading hierarchy를 보장한다. + +### 7.2 `CollectionPageTemplate` + +슬롯과 상태: + +- title/actions +- search/filter/sort toolbar +- active filter summary와 reset +- result count +- table/list/card view +- pagination 또는 load-more +- initial loading, refreshing, empty-first-use, empty-filtered, error +- bulk selection/action + +URL이 filter, sort, page를 소유한다. template은 query 상태를 직접 읽지 않는다. + +### 7.3 `DetailPageTemplate` + +- breadcrumb/back +- title/status/actions +- summary metadata +- main sections +- related/context aside +- loading/not-found/forbidden/error +- destructive action confirmation 위치 + +식별자가 바뀔 때 이전 entity 내용과 새 loading 상태를 혼동하지 않게 key/reset +정책을 명시한다. + +### 7.4 `FormPageTemplate` + +- title/description +- error summary +- field groups +- optional aside/help +- sticky 또는 normal action bar +- submit/cancel +- submitting/saved/conflict/unavailable +- dirty navigation confirmation + +template은 특정 form vendor를 import하지 않는다. + +### 7.5 `StatusPageTemplate` + +다음 변형을 제공한다. + +- unauthenticated +- forbidden +- not found +- unavailable +- offline +- maintenance +- unexpected + +각 변형은 heading, 짧은 설명, 안전한 primary/secondary action, 선택적 trace ID를 +갖는다. raw stack/response를 표시하지 않는다. + +### 7.6 선택 template + +다음은 project 필요가 있을 때 추가한다. + +- `SettingsPageTemplate` +- `DashboardGridTemplate` +- `SplitPaneTemplate` +- `WizardTemplate` +- `FullScreenTaskTemplate` + +## 8. page controller 패턴 + +page를 세 부분으로 나눈다. + +```text +route adapter + parses URL and guard context + ↓ +controller hook + invokes application query/mutation and maps UI events + ↓ +page view + renders template and design-system components +``` + +예: + +```tsx +export function ResourceListRoute() { + const input = useRouteInput(resourceListRoute); + if (!input.ok) return ; + + return ; +} + +function ResourceListController({ input }: ResourceListControllerProps) { + const controller = useResourceListController(input); + return ; +} +``` + +route parse boundary와 controller component를 분리하므로 controller hook은 +조건부로 호출되지 않는다. + +controller가 소유하는 것: + +- parsed route input을 application input으로 변환 +- query/mutation state +- pagination/filter/navigation event +- retry/refresh/action callbacks +- view model projection + +view가 소유하는 것: + +- semantic markup +- template/component 조립 +- focus target +- 사용자의 local-only interaction + +controller가 소유하지 않는 것: + +- HTTP URL 조립 +- credential +- transport DTO parse +- 도메인 invariant +- raw vendor SDK + +## 9. 권장 패턴 카탈로그 + +| 패턴 | 적용 위치 | 쓰는 이유 | 오용 | +| --- | --- | --- | --- | +| Ports and Adapters | application 외부 경계 | 정책과 기술 교체 분리 | 모든 작은 UI library에 port 생성 | +| Command/Query | application input | 읽기/변경 의도와 정책 분리 | CQRS 인프라를 필요 없이 도입 | +| Gateway | output port | 외부 데이터 capability 표현 | `get/post` 범용 HTTP를 application에 노출 | +| Anti-Corruption Mapper | outbound feature adapter | DTO 변화가 core로 전파되지 않게 함 | 단순 object spread로 타입만 바꿈 | +| Result | 예상 실패 | 실패 종류와 처리 경로를 닫음 | programmer error까지 모두 Result로 숨김 | +| Controller/View | inbound React | data lifecycle과 markup 분리 | 거대한 hook 하나에 모든 feature 로직 집중 | +| Strategy | retry/cache/auth recovery | 정책 교체와 테스트 가능성 | 설정 한 줄도 interface로 과도 추상화 | +| Observer/External Store | session/theme/realtime | React 외부 소유 상태 구독 | server state를 다시 external store에 복제 | +| State Machine | 복잡한 workflow | 유효 전이와 보상 명시 | 단순 modal open에 도입 | +| Headless/Compound Component | 복합 UI | behavior와 style/slot 분리 | vendor primitive를 제품 전역에 직접 노출 | +| Adapter Facade | icon/form/i18n vendor | React inbound 내부 vendor 교체 경계 | application port로 승격 | +| Page Template | 반복 layout/state | 접근성과 반응형 구조 재사용 | data fetching을 template에 포함 | +| Registry + Runtime Map | route/operation/event | 선언과 실행 완전성 | 모든 설정을 하나의 거대 전역 파일에 집중 | + +패턴은 추상화 파일만 만든 것으로 완료되지 않는다. reference usage, negative +architecture test, 실패 상태 test가 있어야 제공된 패턴으로 본다. + +## 10. 새 route/page 추가 recipe + +1. feature public 경계와 route ID를 정한다. +2. serializable route contract를 등록한다. +3. params/search Zod schema와 bidirectional codec을 작성한다. +4. safe URL builder를 export한다. +5. lazy page module과 runtime map entry를 추가한다. +6. session/permission/flag guard를 선언한다. +7. 적절한 page template을 선택한다. +8. controller hook을 application input API에 연결한다. +9. loading, empty, refreshing, error, auth, forbidden, not-found를 결정한다. +10. title/message key, focus, scroll, chunk ID를 연결한다. +11. 다음 검증을 추가한다. + - contract/runtime map type completeness + - codec round-trip/property cases + - guard decision unit + - page component state + - query/mutation integration + - keyboard/focus/axe + - direct URL, back/forward, refresh E2E + - chunk failure recovery가 필요한 route의 E2E +12. registry, type, architecture, component, integration, E2E gate를 실행한다. + +## 11. 금지 패턴 + +- page 안에서 raw `fetch`, storage, auth SDK, telemetry SDK 호출 +- `useParams()`/`URLSearchParams` 값을 cast만 하고 사용 +- route contract와 JSX route tree를 각각 수동 관리 +- protected route를 server authorization 대체 수단으로 취급 +- 모든 실패를 redirect 또는 full-page error로 처리 +- query data가 있는데 background error 때문에 내용을 제거 +- chunk load error에서 제한 없는 `location.reload` +- route heading focus outline을 CSS로 무조건 제거 +- template이 data fetching 또는 feature-specific copy를 소유 +- generic `BasePage` prop 하나에 모든 layout variation을 boolean으로 추가 + +## 12. 완료 기준 + +- 모든 route ID가 contract와 runtime map에서 compile-time 완전성을 가진다. +- params/search parse와 URL serialize가 같은 codec을 사용한다. +- route metadata가 loading/error/chunk/title/navigation 행동에 실제 연결된다. +- redirect와 chunk reload loop가 차단된다. +- route 이동 시 query 취소, focus, scroll, dirty policy가 검증된다. +- collection/detail/form/status reference page가 template을 사용한다. +- page view가 application input 외의 외부 capability를 직접 호출하지 않는다. +- 새 route recipe와 테스트만으로 별도 라우터 내부 지식 없이 기능을 추가할 수 있다. diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index b45a51f..d5e37ed 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -11,9 +11,9 @@ primitives, and state surfaces remain reusable. validated config + coherent release manifest -> concrete adapters -> QueryClientProvider + -> BrowserRouter -> ThemeProvider -> SessionProvider - -> BrowserRouter -> AppShell -> lazy route boundary ``` @@ -54,6 +54,14 @@ An external owner implements `readState`, `subscribe`, `beginSignIn`, ## Extending the starter +The steps below describe the current extension path. The platform review found +that several route metadata fields and the composed application facade are not +yet connected end to end. New platform work should follow +[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md) +and the +[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md) +rather than adding another independent route or data-loading convention. + 1. Register the route path, access hint, title, chunk, loading surface, error surface, and optional navigation metadata in `src/contracts/routes.js`. 2. Add a lazy page in `src/presentation/` and render it through `RouteSurface`. diff --git a/docs/architecture/typescript-state-and-data-flow.md b/docs/architecture/typescript-state-and-data-flow.md new file mode 100644 index 0000000..83f859b --- /dev/null +++ b/docs/architecture/typescript-state-and-data-flow.md @@ -0,0 +1,549 @@ +# TypeScript, 상태 소유권, 데이터 흐름 + +## 1. 목적 + +이 문서는 다음 질문에 대한 저장소 표준을 정의한다. + +- JavaScript를 어떤 순서로 TypeScript로 전환하는가. +- local, URL, server, form, global, persisted 상태를 어디에 둬야 하는가. +- React 화면이 application use case와 TanStack Query를 어떻게 사용해야 하는가. +- HTTP, retry, auth, error, validation, logging의 책임을 어떻게 나누는가. +- 새 query, mutation, form을 추가할 때 어떤 파일과 테스트가 필요한가. + +이 문서는 목표 설계다. 현재 구현 상태는 +[프론트엔드 플랫폼 역량 재검토](./frontend-platform-capability-review.md)를 따른다. + +## 2. TypeScript 전환 원칙 + +### 2.1 왜 전환하는가 + +현재 `strict + allowJs + checkJs`는 JavaScript 상태에서 유용한 안전망이다. 그러나 +JSDoc cast가 늘어나면 다음 계약을 정확히 닫기 어렵다. + +- `RouteId`, `OperationId`, `ErrorCode`, `StorageKey`, `TelemetryEvent` +- `Result`와 discriminated failure union +- use case input/output와 gateway generic +- route별 params/search type +- query key tuple +- component variant와 slot prop +- runtime registry의 key와 executable implementation의 완전성 + +TypeScript 전환 목적은 확장자 변경이 아니라 이 계약을 컴파일 단계에서 +검증하는 것이다. + +### 2.2 전환 전에 고칠 도구 + +다음 변경이 첫 브랜치에서 완료되기 전에는 source rename을 시작하지 않는다. + +1. ESLint가 `js`, `jsx`, `mjs`, `ts`, `tsx`, `mts`를 모두 검사한다. +2. `typescript-eslint`, React Hooks, JSX accessibility 규칙을 추가한다. +3. dependency-cruiser의 extension과 resolver가 TS/TSX를 포함한다. +4. `scripts/check-registries.mjs`가 TS/TSX를 검색한다. +5. `config/contracts/registry-governance.json`의 경로 갱신 절차를 만든다. +6. Vite, Vitest, Playwright, scripts, source, tests를 각각 typecheck한다. +7. invalid type fixture가 TS migration 후에도 “실패해야 통과”하는지 확인한다. +8. architecture/security/registry gate가 TS fixture 위반을 실제로 잡는 negative test를 + 추가한다. + +권장 project 구성: + +```text +tsconfig.base.json +tsconfig.app.json +tsconfig.node.json +tsconfig.test.json +tsconfig.json # project references only +``` + +`tsconfig.base.json`의 초기 핵심 옵션: + +```json +{ + "compilerOptions": { + "strict": true, + "noEmit": true, + "noUncheckedIndexedAccess": true, + "exactOptionalPropertyTypes": true, + "useUnknownInCatchVariables": true, + "noImplicitOverride": true, + "noFallthroughCasesInSwitch": true, + "verbatimModuleSyntax": true, + "isolatedModules": true + } +} +``` + +실제 TypeScript 7/Vite 호환 옵션은 설치된 공식 문서와 빌드 결과를 기준으로 +확정한다. 옵션을 한꺼번에 켜서 수백 개 예외를 만들지 말고, 각 단계에서 새 +예외를 금지한다. + +### 2.3 전환 순서 + +| 단계 | 대상 | 이유 | 종료 조건 | +| --- | --- | --- | --- | +| 0 | lint/typecheck/scanner/architecture tooling | TS 코드가 검사를 우회하지 않게 함 | TS 위반 fixture가 각 게이트에서 실패 | +| 1 | result, failure, ID, registry types | 이후 모든 계층의 언어가 됨 | stringly typed public ID 제거 | +| 2 | application input/output ports와 use case | 중심 계약을 먼저 고정 | input/output compile fixture 통과 | +| 3 | domain model과 mapper boundary | DTO와 core model 혼합 차단 | mapper contract test 통과 | +| 4 | outbound adapters | 외부 `unknown`을 경계에서 좁힘 | HTTP/storage/auth failure type 통과 | +| 5 | bootstrap/composition | 누락 dependency를 컴파일로 검출 | 실제 composition type test 통과 | +| 6 | React providers/controllers/routes | typed application API 소비 | route/runtime map 완전성 검사 | +| 7 | primitives/pages/templates | component API와 variant를 닫음 | stories/component tests typecheck | +| 8 | tests/scripts/config | 우회 없는 전체 저장소 | source `allowJs` 제거 가능 | + +각 단계는 빌드 가능한 작은 커밋으로 유지한다. JavaScript와 TypeScript가 공존하는 +동안에는 [공식 JavaScript migration 가이드](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)의 +점진적 방식을 사용한다. + +### 2.4 기본 type 계약 + +다음 형태를 core application에 둔다. + +```ts +export type Ok = Readonly<{ ok: true; value: T }>; +export type Err = Readonly<{ ok: false; error: E }>; +export type Result = Ok | Err; + +export type AppFailure = + | Readonly<{ kind: "unauthenticated"; code: "AUTH_REQUIRED"; traceId?: string }> + | Readonly<{ kind: "forbidden"; code: "FORBIDDEN"; traceId?: string }> + | Readonly<{ kind: "not-found"; code: "NOT_FOUND"; traceId?: string }> + | Readonly<{ kind: "conflict"; code: "CONFLICT"; traceId?: string }> + | Readonly<{ + kind: "validation"; + code: "VALIDATION_FAILED"; + fields: Readonly>; + traceId?: string; + }> + | Readonly<{ kind: "rate-limited"; code: "RATE_LIMITED"; retryAt?: Date }> + | Readonly<{ kind: "unavailable"; code: "UNAVAILABLE"; retryable: boolean }> + | Readonly<{ kind: "unexpected"; code: "UNEXPECTED"; traceId?: string }>; +``` + +원칙: + +- adapter에서 받은 `unknown`은 adapter 경계에서 parse한다. +- application은 `Response`, `AxiosError`, Zod 내부 오류 같은 vendor type을 + 노출하지 않는다. +- UI copy는 failure에 저장하지 않고 message key mapper에서 결정한다. +- 예상 가능한 실패는 `Result`; programmer bug와 render crash는 error boundary로 + 보낸다. +- `as`, non-null assertion, `any`는 경계에서 근거가 있을 때만 사용하고 lint + 예외에 사유를 기록한다. + +## 3. 상태 소유권 + +### 3.1 상태 분류표 + +상태를 만들기 전에 아래 순서로 소유자를 결정한다. + +| 질문 | 상태 종류 | 기본 도구 | 저장 위치 | +| --- | --- | --- | --- | +| 한 컴포넌트 상호작용에만 필요한가 | local UI | `useState`, `useReducer` | component/controller | +| URL로 공유·복원되어야 하는가 | navigation | router params/search + codec | URL | +| 서버가 진실의 원천인가 | server state | TanStack Query inbound adapter | Query cache | +| 입력 중이고 제출 전인가 | form | local form facade | form controller | +| 앱 전체에서 낮은 빈도로 바뀌는가 | cross-cutting | Context 또는 typed external store | provider/store | +| 여러 feature의 복잡한 workflow인가 | client workflow | reducer, Zustand, Redux Toolkit, state machine | feature-owned store | +| 새로고침 후 남아야 하는가 | persisted preference | `StoragePort` | versioned browser storage | +| 인증 credential인가 | auth secret | external auth owner | SDK memory 또는 HttpOnly cookie | + +금지: + +- server response를 global client store에 복사하지 않는다. +- URL에 있어야 할 filter/sort/page를 숨은 store에만 두지 않는다. +- component 내부에 머물 수 있는 modal open 상태를 전역화하지 않는다. +- access token을 localStorage, sessionStorage, 일반 Redux/Zustand store에 넣지 + 않는다. +- 모든 상태를 추상화하는 범용 `StorePort`를 만들지 않는다. + +### 3.2 범용 store 선택 기준 + +기본 skeleton에는 빈 Zustand/Redux store를 만들지 않는다. 실제 요구가 생기면 +다음 기준을 적용한다. + +| 조건 | 권장 | +| --- | --- | +| feature 한 곳의 단순 shared client state | feature reducer 또는 작은 Zustand store | +| 여러 팀이 action/state 규약, devtools, middleware, audit를 공유 | Redux Toolkit | +| 명시적 상태 전이, 병렬 상태, 취소/보상 workflow | state machine | +| session/theme처럼 저빈도 cross-cutting | `useSyncExternalStore` 또는 Context | + +vendor를 선택하더라도 feature 외부에는 hook/facade만 export한다. 제품 코드가 +store instance의 `getState`와 `setState`를 임의 호출하지 않게 한다. + +### 3.3 persistence + +persisted state는 다음 metadata를 가져야 한다. + +```ts +type PersistedRecord = Readonly<{ + version: number; + writtenAt: string; + value: T; +}>; +``` + +- key는 typed registry가 소유한다. +- read 시 schema parse와 migration을 거친다. +- quota, unavailable, corrupt, version mismatch를 구분한다. +- 민감정보와 credential을 저장하지 않는다. +- server state persistence와 offline mutation queue는 별도 project-selected + adapter다. + +## 4. 표준 데이터 호출 경로 + +```mermaid +sequenceDiagram + actor User + participant Page as React page + participant Controller as inbound query/mutation controller + participant App as application input use case + participant Gateway as output gateway + participant Adapter as HTTP/generated client adapter + participant API as Backend/BFF + + User->>Page: route or event + Page->>Controller: typed input + Controller->>App: query/command + AbortSignal + App->>Gateway: capability request + Gateway->>Adapter: DTO request + Adapter->>API: path/query/body/auth + API-->>Adapter: envelope or failure + Adapter-->>Gateway: parsed DTO Result + Gateway-->>App: mapped model Result + App-->>Controller: view data or AppFailure + Controller-->>Page: query/mutation state +``` + +페이지는 controller hook이 제공하는 상태만 렌더링한다. controller는 React, +TanStack Query와 application input interface를 알 수 있지만 use case의 concrete +구현과 outbound adapter는 모른다. + +### 4.1 Application API + +```ts +export interface Application { + readonly resources: { + list( + input: ListResourcesInput, + context: Readonly<{ signal: AbortSignal }>, + ): Promise>; + create( + command: CreateResourceCommand, + context?: Readonly<{ signal?: AbortSignal }>, + ): Promise>; + }; +} +``` + +`ApplicationProvider`는 이 API를 immutable value로 제공한다. controller 외의 +presentation 코드에서 raw HTTP/storage/telemetry port를 가져오는 hook은 만들지 +않는다. theme, locale 같은 UI platform provider는 별도다. + +### 4.2 query adapter + +```ts +export function useResourcesQuery(input: ListResourcesInput) { + const application = useApplication(); + + return useQuery({ + queryKey: resourceKeys.list(input), + queryFn: async ({ signal }) => + unwrapResult(await application.resources.list(input, { signal })), + retry: false, + staleTime: resourceQueryPolicy.list.staleTime, + }); +} +``` + +실제 구현 규칙: + +- query key는 readonly tuple factory로만 만든다. +- key에 들어간 filter는 실제 gateway request에도 동일하게 투영한다. +- `AbortSignal`을 application과 HTTP transport까지 전달한다. +- HTTP 계층이 bounded retry를 소유하면 query retry는 끈다. +- background error와 initial error의 UI를 구분한다. +- placeholder와 cached stale data가 있을 때 전체 화면 error로 교체하지 않는다. +- `select`는 view-only projection에 쓰고 도메인 규칙을 넣지 않는다. +- query hook은 feature public API에서 export한다. + +### 4.3 mutation adapter + +```ts +export function useCreateResourceMutation() { + const application = useApplication(); + const queryClient = useQueryClient(); + + return useMutation({ + mutationFn: (command: CreateResourceCommand) => + application.resources.create(command).then(unwrapResult), + onSuccess: () => + queryClient.invalidateQueries({ queryKey: resourceKeys.all }), + }); +} +``` + +기본 mutation은 navigation만으로 취소됐다고 가정하지 않는다. 서버 작업의 취소가 +안전한 operation만 controller가 보관한 `AbortController`와 명시적 cancel action을 +사용한다. idempotency key는 UI 입력으로 받지 않고 application use case가 +`IdGeneratorPort`로 만들며, 같은 논리 요청의 bounded HTTP retry와 auth replay는 +동일한 key를 재사용한다. + +실제 구현에서는 mutation마다 다음을 명시한다. + +- double-submit 방지와 idempotency key 소유자 +- cancel 가능 여부 +- optimistic update 적용 여부와 rollback snapshot +- 성공 후 invalidate/update/navigation 순서 +- 409 conflict와 422 field validation mapping +- offline 시 queue할지 즉시 실패할지 +- analytics/telemetry event와 redaction + +optimistic update는 기본값이 아니다. 서버 규칙을 확실히 재현할 수 있고 rollback이 +안전한 mutation에만 사용한다. + +## 5. HTTP client 책임 + +### 5.1 목표 파이프라인 + +```text +operation registry + -> path/search/body builder + -> credential attachment + -> timeout and external cancellation + -> bounded retry + -> fetch transport + -> status/envelope decoder + -> response schema decoder + -> feature DTO mapper + -> AppFailure mapper +``` + +각 단계의 입력과 출력은 typed result다. feature-specific model mapper를 공통 HTTP +client 안에 넣지 않는다. + +### 5.2 request projection + +operation definition은 최소 다음 계약을 갖는다. + +```ts +type OperationDefinition< + TPath, + TSearch, + TBody, + TResponse, +> = Readonly<{ + id: OperationId; + method: HttpMethod; + pathTemplate: string; + pathSchema: Schema; + searchSchema: Schema; + bodySchema: Schema; + responseSchema: Schema; + timeoutMs?: number; + retryClass: "never" | "safe" | "idempotency-keyed"; +}>; +``` + +규칙: + +- path segment는 `encodeURIComponent`에 해당하는 안전한 builder를 통과한다. +- query의 array/null/undefined/boolean/date serialization을 한 곳에서 정의한다. +- Zod parse 결과의 trim/default/coercion을 실제 request에 사용한다. +- GET/HEAD에는 body를 보내지 않는다. +- JSON content type은 body가 있을 때만 붙인다. +- base URL과 path를 문자열 덧붙이기로 조립하지 않는다. +- external URL은 별도 allowlist policy를 거친다. + +### 5.3 timeout, cancellation, retry + +소유권: + +- 사용자 navigation/unmount 취소: query/controller가 signal 생성 +- operation timeout: HTTP adapter +- retry: HTTP adapter 또는 query adapter 중 하나 +- 인증 복구 후 단 한 번 replay: auth decorator +- mutation idempotency: application/controller가 key 생성, operation이 허용 여부 선언 + +retry 조건: + +- safe method 또는 idempotency key가 있는 허용 operation만 대상 +- timeout, network, 명시된 429/5xx만 정책 대상 +- validation, auth denial, forbidden, not found, conflict는 자동 재시도하지 않음 +- `Retry-After`와 bounded exponential backoff/jitter 지원 +- tab hidden/offline 상태를 고려 +- 최대 횟수와 전체 elapsed budget을 함께 제한 +- 각 attempt와 final failure를 redacted telemetry로 기록 + +timer와 event listener는 성공, 실패, validation 조기 반환, external abort 모든 +경로에서 정리되어야 한다. + +## 6. 인증과 token 소유권 + +기본 skeleton은 token manager를 제공하지 않는다. + +지원 profile: + +| profile | credential 소유자 | frontend 역할 | +| --- | --- | --- | +| BFF/HttpOnly cookie | browser cookie + backend | `credentials`, CSRF 정책, session probe | +| external OIDC/Auth SDK | SDK memory/cache | attach/recover/login/logout를 auth adapter로 감쌈 | +| SPA memory token | auth adapter memory | 프로젝트가 명시적으로 선택할 때만 | + +공통 `AuthSessionReader`와 HTTP 전용 `CredentialProvider`를 분리한다. + +```ts +interface AuthSessionReader { + getSnapshot(): SessionSnapshot; + subscribe(listener: () => void): () => void; +} + +interface CredentialProvider { + attach(request: RequestInit): Promise; + recover(failure: AuthFailure): Promise<"recovered" | "not-recovered">; +} +``` + +UI는 credential을 읽지 않는다. HTTP adapter는 UI session action을 호출하지 +않는다. logout/login/redirect는 application input 또는 auth UI facade를 통해 +실행한다. + +## 7. 오류, 검증, logging + +### 7.1 검증 계층 + +| 경계 | 책임 | 예 | +| --- | --- | --- | +| runtime config | 앱을 안전하게 시작할 수 있는가 | URL, timeout, auth mode | +| route codec | URL을 typed input으로 읽고 쓸 수 있는가 | page, sort, ID | +| transport DTO | 외부 응답/요청 형식이 계약과 맞는가 | envelope, date string | +| form | 사용자가 수정 가능한 입력 형태가 유효한가 | required, length, format | +| application | use case precondition이 맞는가 | command 조합 | +| domain | 항상 지켜야 할 불변식인가 | valid state transition | + +같은 Zod schema를 무조건 모든 계층에서 재사용하지 않는다. transport DTO, form +value, application command, domain model이 우연히 같은 모양이어도 소유권과 +변경 이유가 다르다. 필요한 경우 mapper로 연결한다. + +### 7.2 사용자 오류 표면 + +`AppFailure`를 다음 UI 상태로 매핑한다. + +| failure | 기본 표면 | 자동 행동 | +| --- | --- | --- | +| unauthenticated | auth required 또는 login transition | auth policy에 따른 1회 복구 | +| forbidden | 권한 없음 | 없음 | +| not-found | route/detail not-found | 없음 | +| validation | error summary + field errors | 첫 오류 focus | +| conflict | 현재 데이터 유지 + conflict action | 자동 overwrite 금지 | +| rate-limited | inline retry time | 허용된 query만 지연 재시도 | +| unavailable | cached data 또는 retry surface | policy 범위 내 retry | +| unexpected | safe generic copy + trace ID | diagnostics emit | + +raw response body, stack, token, URL query, PII를 사용자 copy나 일반 log에 노출하지 +않는다. + +### 7.3 diagnostics와 telemetry + +현재 telemetry event contract와 별도로 개발·진단용 structured logger가 필요하다. +다음 두 설계 중 하나를 ADR로 결정한다. + +1. `DiagnosticsPort`가 log/event/span을 내부 method로 구분 +2. `LoggerPort`와 `TelemetryPort`를 분리 + +공통 요구: + +- log level과 event key는 닫힌 union +- attribute allowlist와 중앙 redaction +- dev adapter는 console을 사용하되 동일 redaction 적용 +- production adapter는 provider SDK를 감싸며 앱 코드는 SDK를 import하지 않음 +- 오류 객체 전체를 그대로 serialize하지 않음 +- trace ID/build ID/route ID/operation ID를 허용된 범위에서 연결 +- logging failure가 제품 flow를 실패시키지 않음 +- consent가 필요한 analytics와 essential diagnostics를 분리 + +## 8. 폼 표준 + +form vendor는 React Hook Form 또는 TanStack Form 등을 평가하되 local facade 뒤에 +둔다. vendor 선택과 무관하게 다음 API를 제공한다. + +- `Form` +- `FormField` +- `Label` +- `Description` +- `FieldError` +- `ErrorSummary` +- `useAppForm` +- `mapValidationFailureToFields` +- `useDirtyNavigationGuard` + +필수 동작: + +1. label, description, error를 stable ID와 `aria-describedby`로 연결 +2. submit 시 error summary와 첫 오류 focus +3. submitting 중 중복 제출 방지 +4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리 +5. 409 conflict는 validation error로 위장하지 않음 +6. 취소와 route 이탈 시 dirty policy 적용 +7. form value → application command mapper를 별도 함수로 둠 +8. browser autofill, IME composition, paste, password manager를 방해하지 않음 +9. loading skeleton으로 사용자의 입력을 덮지 않음 +10. form schema와 server contract mismatch를 integration test로 검증 + +## 9. 새 query 추가 recipe + +1. feature-owned input type과 application query use case를 추가한다. +2. 필요한 output gateway를 `ports/out`에 추가한다. +3. transport DTO schema와 mapper를 outbound feature adapter에 추가한다. +4. operation registry에 path/search/response/retry class를 등록한다. +5. readonly tuple query key factory를 추가한다. +6. inbound query controller hook을 추가한다. +7. page template에서 loading/empty/error/refreshing/success를 렌더링한다. +8. 다음 테스트를 추가한다. + - use case unit + - DTO mapper/schema contract + - path/search projection + - MSW success/empty/401/403/429/500/schema mismatch + - cancellation과 retry ownership + - component state + - route E2E +9. registry, type, architecture, unit, integration, E2E gate를 실행한다. + +금지: + +- page에서 `fetch` +- page에서 raw QueryClient +- cache key와 request filter의 별도 수동 조립 +- response DTO를 domain/application model로 사용 +- initial loading과 background refreshing을 같은 full-page skeleton으로 표시 + +## 10. 새 mutation/form 추가 recipe + +1. form value schema와 application command type을 분리한다. +2. value → command mapper를 작성한다. +3. input command use case와 output gateway method를 추가한다. +4. operation의 idempotency/retry 정책을 선언한다. +5. mutation controller에 invalidation/update/rollback 순서를 작성한다. +6. `FormPageTemplate`과 공통 field primitive로 화면을 구성한다. +7. 422, 409, unauthenticated, unavailable, abort를 각각 처리한다. +8. dirty navigation과 double-submit을 검증한다. +9. 다음 테스트를 추가한다. + - form schema와 mapper unit + - keyboard/label/error summary component + - MSW success/422/409/network-lost + - optimistic rollback을 쓰는 경우 cache snapshot + - 브라우저 navigation blocker와 성공 후 이동 + +## 11. 완료 기준 + +- TS/TSX가 lint, type, architecture, registry, security 검사를 우회하지 않는다. +- source와 test가 strict typecheck된다. +- UI는 application input API만 호출한다. +- reference query와 mutation이 TanStack adapter를 통해 동작한다. +- retry 책임이 단일 계층에 있고 cancellation/timeout과 충돌하지 않는다. +- path/search/parsed body가 실제 전송값과 일치한다. +- 상태 종류별 소유권이 테스트와 문서에서 확인된다. +- token은 UI와 일반 storage/store에 노출되지 않는다. +- failure와 validation의 각 계층이 typed mapper로 분리된다. +- query/mutation/form recipe만으로 새 기능을 만들 수 있다. diff --git a/docs/styling/design-system-platform.md b/docs/styling/design-system-platform.md new file mode 100644 index 0000000..3326ce9 --- /dev/null +++ b/docs/styling/design-system-platform.md @@ -0,0 +1,868 @@ +# 디자인 시스템 플랫폼 계약 + +이 문서는 도메인 기능을 추가하기 전에 프론트엔드 스켈레톤이 제공해야 하는 +디자인 시스템의 소유권, 계층, 기본 구성요소, 외부 라이브러리 경계, 검증 방법을 +정의한다. 목표는 특정 제품의 시각 언어를 미리 결정하는 것이 아니라, 제품 팀이 +접근성·반응형·국제화·테스트 규칙을 다시 발명하지 않고 기능 화면을 만들 수 있게 +하는 것이다. + +이 문서에서 `필수`는 모든 제품이 기반으로 사용할 계약을 뜻한다. `선택`은 +컴포넌트의 경계와 도입 기준은 제공하지만 실제 의존성이나 구현은 제품 요구가 +생긴 뒤 추가해도 되는 항목을 뜻한다. + +## 1. 현재 기준선과 확인된 공백 + +현재 저장소에는 다음 기반이 이미 있다. + +- `src/presentation/styles/theme.css` + - 의미 기반 light/dark 색상 토큰 + - focus indicator + - 반응형 앱 셸 + - reduced-motion 처리 +- `src/presentation/providers/theme-provider.jsx` + - `system`, `light`, `dark` 선호도 + - 저장소 포트를 통한 선호도 영속화 + - 운영체제 색상 변경 구독 +- `src/presentation/components/ui/` + - `Button` + - `TextField` + - `Card` + - `Alert` + - `Badge` + - `Dialog` +- `src/presentation/components/async-surface.jsx` + - 초기 로딩, 빈 화면, terminal error, background 상태 +- `src/presentation/components/state-surfaces.jsx` + - 인증 필요, 권한 없음, 찾을 수 없음 +- `/examples/ui`, `/examples/states` + - 실행 가능한 primitive와 상태 예제 +- component/E2E/axe 테스트 + - 필드 설명과 오류 연결 + - native dialog 닫기와 trigger focus 복원 + - 320px reflow + - Chromium, Firefox, WebKit + - 등록 라우트의 자동 접근성 검사 + +이 기반은 유효하지만 아직 디자인 시스템 플랫폼 전체는 아니다. + +1. 토큰이 색상 중심이며 typography, elevation, motion, z-layer, control size, + breakpoint가 계약으로 닫혀 있지 않다. +2. 공통 입력은 `TextField` 하나뿐이어서 일반적인 폼을 공통 규칙으로 만들 수 + 없다. +3. 앱 셸과 예제 화면에서 공용 primitive 대신 raw `button`, `select`, 링크 + class를 다시 작성하는 곳이 있다. +4. `☰`, `×` 같은 문자 glyph를 직접 사용하며 아이콘 공급자 경계가 없다. +5. `theme.css` 하나가 token, layout, primitive, pattern 스타일을 모두 소유한다. +6. runtime gallery는 있지만 격리된 story, interaction story, 시각 회귀 기준선이 + 없다. +7. 사용자 문구가 한국어 literal로 고정되어 locale과 RTL 계약이 없다. +8. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage` 같은 공통 페이지 + 템플릿이 없다. +9. 모바일 sidebar는 표시 전환은 되지만 modal drawer 수준의 focus 이동, focus + 복원, 배경 비활성화 계약은 없다. + +따라서 기존 구성요소는 폐기하지 않고 아래 목표 계층으로 이동·확장한다. + +## 2. 소유권과 의존성 원칙 + +디자인 시스템은 `presentation` 계층이 소유한다. 색상, 아이콘, 키보드 상호작용, +포커스, 화면 배치와 같은 문제는 도메인 규칙이 아니다. + +```text +product page + -> template + -> pattern + -> primitive + -> token +``` + +외부 UI 라이브러리를 사용하는 경우 흐름은 다음과 같다. + +```text +product page + -> local design-system API + -> local vendor facade + -> Lucide / React Aria / Radix +``` + +다음 규칙은 필수다. + +- 제품 페이지는 `lucide-react`, `react-aria-components`, `@radix-ui/*`를 직접 + import하지 않는다. +- 외부 UI 라이브러리 type을 공용 컴포넌트 API로 그대로 노출하지 않는다. +- 도메인과 application 계층은 React component, CSS class, icon name을 알지 + 않는다. +- primitive는 API 요청, query cache, 인증 상태와 같은 외부 상태를 직접 읽지 + 않는다. +- pattern과 template도 application use case를 직접 선택하지 않는다. 필요한 + 상태와 command callback을 props/slot으로 받는다. +- 제품별 색상이나 명칭을 primitive 내부에 하드코딩하지 않는다. +- 같은 의미의 접근성·키보드 동작을 페이지마다 다시 구현하지 않는다. +- 세 번째 사용 사례가 확인되기 전에는 제품 전용 조합을 무리하게 primitive로 + 승격하지 않는다. + +아이콘과 headless UI는 React inbound adapter의 vendor facade로 충분하다. +이들을 위한 application port를 만들지 않는다. HTTP, storage, telemetry처럼 +런타임 외부 자원을 교체하는 capability와 UI 구현 라이브러리를 구분한다. + +## 3. 목표 디렉터리 + +TypeScript 전환 이후의 목표 구조는 다음과 같다. 마이그레이션 중에는 기존 +경로에서 같은 소유권 규칙을 지키고, 한 번에 전체 경로를 이동하지 않아도 된다. + +```text +src/adapters/inbound/react/design-system/ + index.ts + tokens/ + primitive.css + semantic.css + component.css + token-contract.ts + primitives/ + button/ + field/ + checkbox/ + dialog/ + ... + patterns/ + async-surface/ + form/ + data-table/ + confirmation/ + ... + templates/ + standard-page/ + collection-page/ + detail-page/ + form-page/ + status-page/ + icons/ + icon.tsx + icon-button.tsx + semantic-icons.tsx + vendors/ + lucide.tsx + vendors/ + react-aria/ + testing/ + story-decorators.tsx + render-design-system.tsx +``` + +`index.ts`는 제품의 React inbound 코드가 사용할 public API다. 내부 파일 deep +import는 디자인 시스템 자체와 테스트에만 허용한다. 이 경계는 ESLint의 +`no-restricted-imports`로 검사한다. + +현재 `src/presentation`은 React inbound adapter 역할을 한다. TypeScript +마이그레이션 동안 기존 경로를 유지할 수 있지만, 최종 canonical target은 위 +경로다. 같은 컴포넌트를 `presentation`과 `adapters/inbound/react` 양쪽에 +복제하지 않고 feature 단위로 이동한다. + +## 4. 계층 계약 + +### 4.1 Tokens + +토큰은 시각적 결정을 이름으로 표현한다. 토큰은 세 계층으로 관리한다. + +```text +primitive token -> semantic token -> component token +``` + +예: + +```css +--palette-blue-600: ...; +--color-action: var(--palette-blue-600); +--button-primary-background: var(--color-action); +``` + +#### Primitive tokens + +원시 palette와 scale이다. 제품 코드에서 직접 소비하지 않는다. + +- palette +- spacing scale +- font size와 line height scale +- radius scale +- shadow scale +- duration과 easing scale +- fixed size scale + +#### Semantic tokens + +제품 코드와 대부분의 primitive가 소비하는 이름이다. + +- `surface`, `surface-muted`, `surface-elevated` +- `content`, `content-muted`, `content-inverse` +- `border`, `border-strong` +- `action`, `action-hover`, `action-pressed` +- `danger`, `warning`, `success`, `info` +- `focus-ring` +- `disabled-content`, `disabled-surface` + +#### Component tokens + +특정 primitive가 여러 semantic token을 조합할 때만 사용한다. + +- `button-primary-background` +- `field-border-invalid` +- `dialog-elevation` +- `navigation-active-background` + +컴포넌트 토큰은 제품별 variant를 만들기 위한 우회 경로가 아니다. 두 개 이상의 +컴포넌트가 같은 의미를 공유한다면 semantic token으로 승격한다. + +#### 필수 토큰 범주 + +| 범주 | 필수 내용 | +| --- | --- | +| Color | surface/content/border/action/status/focus, light/dark | +| Typography | family, size, line-height, weight, letter-spacing | +| Spacing | inset, inline, stack, section, page spacing scale | +| Size | control height, icon size, touch target, container width | +| Border | width, style, semantic border | +| Radius | control, surface, modal, full | +| Elevation | panel, popover, dialog, sticky shell | +| Z-layer | base, sticky, navigation, popover, modal, toast | +| Motion | fast/normal/slow duration, standard/emphasized easing | +| Breakpoint | compact, medium, wide와 container 계약 | +| Opacity | disabled, scrim, skeleton | + +토큰의 완료 조건은 다음과 같다. + +- light와 dark에서 모든 semantic token이 정의된다. +- `forced-colors`에서도 focus와 control 경계가 사라지지 않는다. +- 상태는 색상만으로 구분하지 않는다. +- 같은 raw value가 반복되면 named token으로 승격한다. +- 사용자 입력으로 CSS class나 CSS variable 이름을 조립하지 않는다. +- token contract test가 필수 token의 누락을 차단한다. +- chart나 canvas처럼 JavaScript 값이 필요한 경우에만 typed token accessor를 + 제공한다. + +## 5. 기본 컴포넌트 카탈로그 + +### 5.1 Primitives + +Primitive는 하나의 접근 가능한 상호작용 또는 작은 시각 단위를 제공한다. + +| 그룹 | 기본 제공 | 우선순위 | 핵심 계약 | +| --- | --- | --- | --- | +| Action | `Button` | 필수 | intent, size, disabled, pending, native semantics | +| Action | `LinkButton` | 필수 | navigation은 anchor/router link semantics 유지 | +| Action | `IconButton` | 필수 | accessible name 필수, 44px 권장 target | +| Form | `Field` | 필수 | label, description, error ID 조립 | +| Form | `TextField` | 필수 | text/email/password/search/autocomplete | +| Form | `TextArea` | 필수 | resize와 글자 수 안내 | +| Form | `Select` | 필수 | native 우선, 복합 선택은 headless 구현 | +| Form | `Checkbox` | 필수 | checked/indeterminate | +| Form | `RadioGroup` | 필수 | arrow-key와 group label | +| Form | `Switch` | 필수 | boolean setting 전용 | +| Form | `SearchField` | 필수 | clear action, submit semantics | +| Feedback | `Alert` | 필수 | inline feedback와 live-region 정책 분리 | +| Feedback | `Badge` | 필수 | color-only 금지 | +| Feedback | `Spinner` | 필수 | accessible label 또는 decorative | +| Feedback | `ProgressBar` | 필수 | determinate/indeterminate | +| Feedback | `Skeleton` | 필수 | 실제 layout과 유사한 크기, reduced motion | +| Feedback | `Toast` | 필수 | queue, 중복 방지, timeout pause | +| Surface | `Card` | 필수 | heading level 강제 금지, label 선택 가능 | +| Surface | `Separator` | 필수 | decorative/semantic 구분 | +| Overlay | `Dialog` | 필수 | modal semantics, focus trap/restore, Escape | +| Overlay | `Drawer` | 필수 | compact navigation과 side sheet | +| Overlay | `Popover` | 필수 | anchor, dismiss, collision | +| Overlay | `Tooltip` | 필수 | hover와 keyboard, 중요한 정보 단독 보유 금지 | +| Overlay | `Menu` | 필수 | roving focus, typeahead, Escape | +| Navigation | `Breadcrumbs` | 필수 | 현재 위치와 overflow | +| Navigation | `Tabs` | 필수 | manual/automatic activation 정책 | +| Navigation | `Pagination` | 필수 | current page, previous/next label | +| Utility | `VisuallyHidden` | 필수 | screen-reader-only content | +| Utility | `Portal` | 필수 | overlay root와 SSR-safe fallback | +| Utility | `FocusRing` | 필수 | input modality 인식 | +| Advanced | date/time picker | 선택 | locale/time zone 요구가 있을 때 | +| Advanced | file upload/dropzone | 선택 | upload adapter 요구가 있을 때 | +| Advanced | virtualizer/tree | 선택 | 실제 데이터 규모가 입증될 때 | + +Primitive API는 다음 규칙을 지킨다. + +- 기본 HTML semantics를 보존한다. +- `div onClick`로 button이나 link를 흉내 내지 않는다. +- `variant`, `size`, `tone`은 closed union과 정적 class map을 사용한다. +- pending은 focus를 잃게 하는 무조건적인 `disabled`와 구분한다. +- controlled와 uncontrolled 지원 여부를 문서화한다. +- ref 전달과 focus contract를 테스트한다. +- `className`은 escape hatch이지 public variant를 대체하지 않는다. +- 임의의 polymorphic `as`보다 `Button`과 `LinkButton`처럼 semantics가 명확한 + API를 우선한다. +- visual-only prop이 도메인 의미를 표현하지 않도록 한다. + +### 5.2 Patterns + +Pattern은 여러 primitive를 조합해 반복되는 사용자 문제를 해결한다. + +| Pattern | 필수 내용 | +| --- | --- | +| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh | +| `AccessSurface` | auth required, forbidden, not found | +| `Form` | submit, error summary, first-invalid focus, pending | +| `ConfirmationDialog` | destructive action 설명과 명시적 확인 | +| `ToastRegion` | queue, announcement, dismiss, focus policy | +| `SearchFilterToolbar` | search, filter, reset, result count | +| `DataTable` | caption, sorting, selection, responsive fallback | +| `PaginationBar` | result range와 page navigation | +| `NavigationDrawer` | mobile focus scope와 background inert | +| `DisclosureGroup` | help/settings section | + +Pattern은 application failure object 전체를 렌더링하지 않는다. 안전한 message key, +사용자 action, 표시 가능한 metadata만 받는다. + +### 5.3 Templates + +Template은 페이지 레이아웃과 상태 slot을 제공한다. API 호출과 도메인 use case는 +소유하지 않는다. + +#### `StandardPageTemplate` + +- breadcrumb 또는 back navigation +- eyebrow +- `h1` +- description +- status/metadata +- primary/secondary actions +- main content와 aside slot + +#### `CollectionPageTemplate` + +- page header +- search/filter/sort toolbar +- result count +- loading/empty/error slot +- table/list/card-grid slot +- pagination slot +- compact viewport에서의 대체 배치 + +#### `DetailPageTemplate` + +- breadcrumb/back +- title과 entity status +- page actions +- description list/section slot +- loading/not-found/forbidden/error 상태 + +#### `FormPageTemplate` + +- heading과 설명 +- error summary +- field section +- sticky 또는 inline action bar +- submit/cancel +- submitting, success, conflict +- unsaved-change navigation blocker 연결 지점 + +#### `StatusPageTemplate` + +- 401, 403, 404, 500, offline, maintenance +- safe description +- primary recovery action +- optional support reference +- raw endpoint, stack, token 노출 금지 + +Template의 heading 순서는 slot 소비자가 임의로 깨뜨리지 못하게 예제와 테스트로 +고정한다. 다만 `Card` 같은 하위 primitive가 무조건 `h3`를 생성해서도 안 된다. + +## 6. Lucide 아이콘 facade + +[Lucide for React 공식 문서](https://lucide.dev/guide/react)는 각 아이콘을 독립 +React component로 제공하며 명시적으로 import한 아이콘만 번들에 포함될 수 있는 +tree-shaking 구조를 제공한다. 기본 아이콘 공급자로 사용하기에 적합하지만 제품 +코드가 공급자 API에 결합되면 안 된다. + +### 6.1 필수 규칙 + +1. `lucide-react` import는 `icons/vendors/lucide.tsx`에서만 허용한다. +2. 제품 코드에는 Lucide component type, icon name, stroke prop을 노출하지 않는다. +3. 디자인 시스템이 승인한 작은 아이콘 집합만 명시적으로 import한다. +4. 모든 아이콘을 이름으로 동적 import하는 범용 `DynamicIcon`은 기본 제공하지 + 않는다. +5. 아이콘 색은 기본적으로 `currentColor`를 사용한다. +6. 크기와 stroke는 `--icon-size-*`, `--icon-stroke-*` 토큰을 사용한다. +7. 장식 아이콘은 기본적으로 `aria-hidden="true"`와 `focusable="false"`다. +8. 정보를 단독으로 전달하는 아이콘은 local `Icon` API의 `label`을 통해 + `role="img"`와 accessible name을 가진다. +9. 버튼 안의 아이콘은 장식으로 처리하고 버튼 자체에 visible label 또는 + `aria-label`을 둔다. +10. 상태를 아이콘이나 색상 하나만으로 전달하지 않는다. + +### 6.2 목표 API 예시 + +아래 예시는 방향을 설명한다. 실제 type과 경로는 TypeScript 전환 작업에서 +확정한다. + +```tsx +import { MenuIcon } from "@/presentation/design-system/icons"; +import { IconButton } from "@/presentation/design-system"; + + + + +``` + +vendor 파일은 의미 이름과 공급자 이름을 분리한다. + +```tsx +import { + Menu as LucideMenu, + X as LucideClose, + AlertTriangle as LucideWarning, +} from "lucide-react"; + +export const MenuGlyph = LucideMenu; +export const CloseGlyph = LucideClose; +export const WarningGlyph = LucideWarning; +``` + +`MenuGlyph` 같은 vendor export는 `semantic-icons.tsx` 밖으로 다시 노출하지 +않는다. 제품 코드는 `MenuIcon`, `CloseIcon`, `WarningIcon`만 사용한다. + +### 6.3 아이콘 추가 완료 조건 + +- 기존 semantic icon으로 표현할 수 없는지 먼저 확인했다. +- 서로 다른 제품 기능이 같은 의미 아이콘을 공유한다. +- accessible name과 decorative 여부를 결정했다. +- light/dark/high-contrast에서 보인다. +- 200% zoom과 compact viewport에서 잘리지 않는다. +- 신규 import 후 bundle budget을 통과한다. +- 공급자 교체 시 제품 코드 수정이 필요하지 않다. + +## 7. Headless UI 선택 기준 + +복잡한 overlay, collection, focus management를 직접 구현하기 전에 native +platform과 검증된 headless UI를 평가한다. + +- [React Aria 공식 시작 문서](https://react-aria.adobe.com/getting-started) +- [Radix Primitives 공식 소개](https://www.radix-ui.com/primitives/docs/overview/introduction) + +### 7.1 선택 순서 + +1. native HTML만으로 요구 semantics와 모든 지원 브라우저 동작을 충족하는지 + 확인한다. +2. native 구현이 불충분하면 React Aria와 Radix를 평가한다. +3. 한 프로젝트에서 같은 문제를 해결하는 headless 공급자를 둘 이상 기본값으로 + 사용하지 않는다. +4. 선택 결과와 버전·라이선스·bundle 영향을 ADR에 기록한다. +5. 공급자 component를 local primitive로 감싼 뒤에만 제품 코드에 노출한다. + +### 7.2 평가표 + +| 기준 | 확인 질문 | +| --- | --- | +| Semantics | WAI-ARIA pattern과 native semantics를 올바르게 사용하는가 | +| Keyboard | roving focus, typeahead, Escape, arrow key가 완전한가 | +| Focus | trap, restore, initial focus, nested overlay가 안전한가 | +| Input modality | mouse, touch, keyboard, screen reader가 동일하게 동작하는가 | +| i18n | RTL, locale number/date, IME를 지원하는가 | +| Styling | semantic token과 Tailwind/CSS layer에 결합 가능한가 | +| Bundle | component 단위 import와 tree shaking이 가능한가 | +| React/Vite | 현재 React와 Vite 조합을 공식 지원하는가 | +| SSR | future SSR profile에서 hydration ID가 안정적인가 | +| Testing | 접근성·상호작용 테스트 자료와 utility가 있는가 | +| Maintenance | release cadence, security 대응, license가 허용 가능한가 | + +현재 스켈레톤의 접근성·국제화 목표에는 React Aria Components가 우선 후보다. +Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다. 최종 선택은 +실제 prototype으로 `Select`, `Menu`, `Drawer` 세 가지를 구현해 다음을 비교한 뒤 +확정한다. + +- keyboard matrix +- screen reader announcement +- RTL +- mobile touch +- dark/high-contrast +- gzip 증가량 +- local API로 감쌀 때 필요한 코드량 + +공급자를 선택하더라도 `SelectProps = AriaSelectProps`처럼 vendor type alias를 +그대로 공용 API로 만들지 않는다. 제품이 실제로 지원하는 의미만 local prop으로 +닫는다. + +## 8. 접근성 계약 + +목표는 WCAG 2.2 AA에 맞춘 기본 동작이다. 자동 도구 통과는 적합성 선언이 아니며, +키보드와 보조기술 검토를 함께 수행한다. + +### 8.1 모든 컴포넌트의 공통 기준 + +- 올바른 native element와 role을 사용한다. +- visible label 또는 accessible name이 있다. +- keyboard만으로 모든 action을 실행할 수 있다. +- focus 순서가 DOM과 시각 순서에 맞는다. +- focus indicator를 제거하지 않는다. +- disabled와 readonly를 구분한다. +- 상태는 색상만으로 전달하지 않는다. +- 오류는 해당 control과 programmatically 연결한다. +- 필요한 변경만 live region으로 한 번 알린다. +- `prefers-reduced-motion`에서 불필요한 motion을 제거한다. +- 200% text zoom과 400% page zoom에서 정보가 손실되지 않는다. +- 320 CSS px reflow에서 양방향 scroll을 강요하지 않는다. +- touch target은 기본 44x44 CSS px를 목표로 한다. +- forced-colors에서 border, focus, selected state가 사라지지 않는다. +- RTL에서 logical direction과 key behavior를 검증한다. +- 한글·일본어·중국어 IME composition 중 입력을 조기에 검증하거나 제출하지 + 않는다. + +### 8.2 Overlay 기준 + +- 열기 trigger를 기록한다. +- 열릴 때 의미 있는 initial focus를 둔다. +- modal일 때 focus가 내부를 벗어나지 않는다. +- 배경 content를 `inert` 또는 동등한 방식으로 비활성화한다. +- Escape와 명시적 닫기 action을 제공한다. +- 닫은 뒤 trigger 또는 안전한 대체 위치로 focus를 복원한다. +- nested overlay와 route transition 중 orphan portal을 남기지 않는다. + +### 8.3 Form 기준 + +- label, description, error가 동일한 field ID 체계로 연결된다. +- required는 시각적 기호와 programmatic 상태를 함께 가진다. +- submit 실패 시 error summary로 focus를 이동한다. +- error summary 항목은 해당 field로 이동한다. +- async validation은 현재 입력보다 오래된 결과를 폐기한다. +- pending 상태를 screen reader에 알리되 같은 문구를 반복하지 않는다. +- 서버 오류의 raw body, stack, 내부 field path를 출력하지 않는다. + +## 9. 국제화 계약 + +디자인 시스템 primitive는 한국어 문구를 내부 기본값으로 숨기지 않는다. +접근성 label이나 오류 문구가 필요하면 명시적인 prop 또는 message key를 받는다. + +필수 국제화 기반: + +- `LocaleProvider` +- typed message key +- fallback locale +- ``과 `dir` 갱신 +- `Intl.DateTimeFormat` +- `Intl.NumberFormat` +- `Intl.ListFormat` +- plural/select message +- locale별 validation message +- pseudo-locale +- RTL story와 E2E smoke + +금지 패턴: + +- 번역 문장 중간에 JSX 문자열을 연결한다. +- 날짜를 `substring`이나 고정 구분자로 조립한다. +- icon direction을 locale 확인 없이 좌/우 이름으로 고정한다. +- route title, navigation label, toast message를 JSX literal로 분산한다. +- 번역 누락 시 빈 문자열을 렌더링한다. + +Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어야 한다. + +- `ko-KR`, light +- `en-US`, light +- `en-US`, dark +- pseudo-locale +- 대표 RTL locale + +## 10. Storybook과 시각 검증 + +현재 `/examples/ui`는 실행 중인 앱 셸과 primitive 통합을 확인하는 데 유지한다. +그러나 runtime gallery는 isolated component workshop을 대체하지 않는다. + +[Storybook 공식 UI 테스트 문서](https://storybook.js.org/docs/writing-tests)는 +story를 기반으로 interaction, accessibility, visual test를 구성하는 방법을 +제공한다. + +### 10.1 Storybook 필수 구성 + +- Vite 기반 Storybook +- TypeScript CSF story +- global theme toolbar +- locale/RTL toolbar +- compact/wide viewport +- Router, Theme, Locale, Session, Query decorator +- `@storybook/addon-a11y` +- a11y 결과를 CI에서 error로 처리 +- interaction `play` test +- story build gate + +### 10.2 각 컴포넌트의 필수 story + +- default +- 모든 semantic variant +- disabled와 readonly +- pending/loading +- 오류 +- 긴 문구 +- 빈 값 +- light/dark +- compact viewport +- keyboard interaction +- 해당되는 경우 open/closed, controlled/uncontrolled + +Form과 overlay는 다음 story를 추가한다. + +- submit 실패와 error summary +- async pending +- server field error +- Escape close +- outside interaction +- initial focus +- focus restoration +- nested content와 long content + +### 10.3 시각 회귀 + +기본 시각 회귀는 Playwright `toHaveScreenshot()`을 사용해 저장소 안에서 실행할 +수 있게 한다. Chromatic 같은 외부 서비스는 선택 사항이다. + +필수 안정화: + +- 동일한 Linux image, browser version, font +- animation과 caret 비활성화 +- 시간·랜덤·network 응답 고정 +- 동적 ID와 민감 데이터 mask +- light/dark baseline +- compact/wide baseline +- 변경된 baseline은 코드 리뷰 대상 + +failure screenshot은 시각 회귀가 아니다. 의도된 baseline과 실제 렌더링을 +비교하는 assertion이 있어야 한다. + +### 10.4 테스트 계층 + +| 계층 | 검증 대상 | +| --- | --- | +| Type check | prop union, ref, event와 slot type | +| Unit | token/variant map, pure formatter와 state reducer | +| Component | native semantics, keyboard, focus, callback | +| Story interaction | 실제 browser의 isolated behavior | +| Story a11y | 모든 주요 state의 axe | +| Visual | pixel/layout/theme regression | +| E2E | 앱 셸, route, form/query integration | +| Manual | screen reader, zoom, touch, forced-colors | + +DOM snapshot은 보이는 UI를 보장하지 않으므로 public markup contract가 꼭 필요한 +경우에만 사용한다. + +## 11. 컴포넌트 추가 Recipe + +새 component를 추가할 때 다음 순서를 생략하지 않는다. + +### Step 1. 문제와 계층을 결정한다 + +다음 질문을 issue 또는 설계 메모에 기록한다. + +- 단일 control인가, 반복되는 조합인가, 페이지 구조인가? +- primitive, pattern, template 중 어디에 속하는가? +- 기존 component의 variant로 해결할 수 있는가? +- 제품 전용 의미를 공통 디자인 시스템으로 잘못 올리는 것은 아닌가? +- native HTML로 충분한가? + +### Step 2. 상태 행렬을 작성한다 + +최소 상태: + +```text +default +hover +focus-visible +active/pressed +disabled +pending +invalid +light +dark +compact +long-content +``` + +선택/overlay component는 open, selected, indeterminate, empty, loading도 포함한다. + +### Step 3. 접근성 명세를 작성한다 + +- element/role +- accessible name +- keyboard table +- focus entry/exit/restore +- announcement +- error association +- reduced motion +- touch와 screen reader + +명세가 불명확하면 구현보다 먼저 native, React Aria, Radix prototype으로 검증한다. + +### Step 4. API를 닫는다 + +- TypeScript public props를 정의한다. +- semantic `variant`를 사용하고 raw color prop을 노출하지 않는다. +- callback 이름과 payload를 domain-neutral하게 정한다. +- controlled/uncontrolled 정책을 정한다. +- `className` escape hatch의 범위를 정한다. +- vendor prop과 type을 public API에 노출하지 않는다. + +### Step 5. 필요한 토큰을 추가한다 + +- 기존 semantic token으로 표현 가능한지 확인한다. +- raw 값 반복을 추가하지 않는다. +- light/dark/forced-colors 값을 함께 정의한다. +- token contract test를 갱신한다. + +### Step 6. 구현한다 + +- native semantics 우선 +- local vendor facade만 import +- static variant map +- ref/focus 지원 +- DOM 구조 최소화 +- render 중 전역 상태 변경 금지 +- 제품 API나 application service import 금지 + +### Step 7. Story를 작성한다 + +- 상태 행렬을 모두 story로 표현한다. +- interaction test를 작성한다. +- dark, compact, long-content를 포함한다. +- a11y test를 error mode로 실행한다. + +### Step 8. 자동 테스트를 작성한다 + +- role/name 중심 query +- keyboard와 focus +- disabled/pending +- callback +- controlled state +- 오류와 live region +- 필요한 visual baseline + +구현 class나 내부 DOM 순서만 확인하는 brittle test는 피한다. + +### Step 9. 통합 예제를 추가한다 + +- `/examples/ui`에는 primitive를 추가한다. +- `/examples/states`에는 새로운 공통 상태를 추가한다. +- pattern/template은 domain-neutral fixture로 실제 조합을 보여 준다. +- production profile에서 예제 route를 제외할 수 있는 계약을 유지한다. + +### Step 10. 문서와 public export를 갱신한다 + +- 사용 목적 +- 사용하지 말아야 할 경우 +- props와 variant +- keyboard +- 접근성 책임 +- i18n +- 예제 +- public `index.ts` export +- 변경 로그 + +### Step 11. 게이트를 실행한다 + +최소 실행 범위: + +```bash +corepack pnpm check:types +corepack pnpm lint +corepack pnpm check:architecture +corepack pnpm test:component +corepack pnpm test:e2e +corepack pnpm test:a11y +corepack pnpm build +corepack pnpm check:bundle +``` + +Storybook과 visual gate가 도입된 뒤에는 story build, interaction, story a11y, +visual comparison도 필수로 추가한다. + +## 12. Definition of Done + +컴포넌트는 아래 항목 중 자신의 state/capability matrix에 해당하는 항목을 +충족해야 `완료`다. 적용되지 않는 항목은 체크를 생략하지 말고 `N/A`와 이유를 +component contract에 기록한다. 예를 들어 `Separator`에는 pending/error/IME가, +읽기 전용 `Card`에는 controlled state와 field error가 적용되지 않는다. + +### API와 아키텍처 + +- [ ] primitive/pattern/template 소유권이 명확하다. +- [ ] public TypeScript API가 closed union으로 정의되었다. +- [ ] 제품 코드가 vendor package를 직접 import하지 않는다. +- [ ] domain/application dependency가 없다. +- [ ] public barrel을 통해 소비할 수 있다. +- [ ] 상태를 소유하는 경우 controlled/uncontrolled 계약이 문서화되었고, focus + target이 있는 경우 ref 계약이 문서화되었다. + +### Styling + +- [ ] raw 색상과 반복되는 임의 값이 없다. +- [ ] semantic token을 사용한다. +- [ ] light/dark가 완성되었다. +- [ ] compact/wide reflow가 된다. +- [ ] long text와 번역 확장을 견딘다. +- [ ] forced-colors에서도 의미가 유지된다. +- [ ] bundle budget을 통과한다. + +### 접근성 + +- [ ] native semantics와 accessible name이 있다. +- [ ] keyboard 동작이 명세와 일치한다. +- [ ] focus indicator, 이동, 복원이 올바르다. +- [ ] 상태가 색상에만 의존하지 않는다. +- [ ] 오류나 설명을 제공하는 component는 이들을 programmatically 연결한다. +- [ ] reduced-motion을 존중한다. +- [ ] 200%/400% zoom과 320px reflow를 확인했다. +- [ ] screen reader 수동 검토 항목이 정의되었다. + +### 국제화 + +- [ ] 사용자 문구를 소유하는 component는 이를 내부 literal로 고정하지 않는다. +- [ ] 날짜·숫자·목록을 표시하는 component는 locale formatter를 사용한다. +- [ ] pseudo-locale에서 잘리지 않는다. +- [ ] RTL에서 배치와 키보드가 올바르다. +- [ ] 문자 입력을 받는 component는 IME 입력을 깨뜨리지 않는다. + +### 테스트와 문서 + +- [ ] component behavior test가 있다. +- [ ] 모든 주요 상태 story가 있다. +- [ ] story interaction test가 있다. +- [ ] automated a11y가 통과한다. +- [ ] 필요한 visual baseline이 있다. +- [ ] runtime gallery 또는 pattern fixture가 있다. +- [ ] 사용법, 금지 사례, 접근성 책임이 문서화되었다. +- [ ] 전체 품질·아키텍처·bundle gate가 통과한다. + +## 13. 금지 패턴 + +- 제품 페이지에서 `lucide-react` 직접 import +- 제품 페이지에서 React Aria/Radix 직접 import +- `div`와 keyboard handler로 native button을 재구현 +- icon-only button에 accessible name 누락 +- 문자열 icon name으로 전체 icon package를 동적 로딩 +- 사용자 값으로 Tailwind/CSS class 조립 +- raw hex/OKLCH 값을 JSX나 component CSS에 반복 +- `as="div"`처럼 semantics를 무제한 변경하는 public API +- primitive에서 API/query/auth/storage를 직접 호출 +- 모든 상태를 하나의 전역 store에 저장 +- 오류 raw body, URL, header, token, stack 표시 +- locale 문장을 문자열 덧셈으로 구성 +- axe 통과만으로 접근성 완료 선언 +- failure screenshot만으로 시각 회귀 완료 선언 +- Storybook story 없이 runtime gallery 하나로 모든 variant를 대표 + +## 14. 단계별 도입 순서 + +1. TypeScript public API와 디자인 시스템 public barrel을 만든다. +2. token을 primitive/semantic/component 계층으로 분리한다. +3. 기존 Button, TextField, Card, Alert, Badge, Dialog를 새 계약으로 이동한다. +4. Lucide local facade와 `IconButton`을 추가하고 문자 glyph를 제거한다. +5. Field foundation과 필수 form primitives를 추가한다. +6. React Aria와 Radix prototype을 비교하고 headless ADR을 확정한다. +7. Drawer, Select, Menu, Popover, Tooltip을 local facade로 구현한다. +8. pattern과 page template을 추가한다. +9. locale provider, pseudo-locale, RTL 검증을 추가한다. +10. Storybook, story a11y, interaction test를 추가한다. +11. pinned browser 환경의 visual regression gate를 추가한다. +12. `/examples/ui`와 `/examples/states`를 통합 smoke gallery로 유지한다. + +이 순서는 라이브러리 수를 늘리는 것이 목표가 아니다. 각 단계가 제품 개발자가 +중복 구현할 문제를 하나씩 제거하고, 외부 공급자를 교체할 수 있는 로컬 계약과 +검증 증거를 남기는 것이 목표다. diff --git a/docs/styling/design-tokens.md b/docs/styling/design-tokens.md index 178d367..baf91eb 100644 --- a/docs/styling/design-tokens.md +++ b/docs/styling/design-tokens.md @@ -39,3 +39,10 @@ Arbitrary-value policy: The removable sample may demonstrate tokens, but production starter modules do not import from `src/sample/contract-fixture`. + +This file documents the currently implemented token and primitive baseline. +The [design-system platform contract](./design-system-platform.md) defines the +target token layers, component catalog, local Lucide/headless-library +facades, page patterns, accessibility and internationalization rules, isolated +workshop, and component-authoring recipe. Items in that target document are not +treated as implemented until their acceptance tests pass. diff --git a/docs/testing/frontend-platform-testing-strategy.md b/docs/testing/frontend-platform-testing-strategy.md new file mode 100644 index 0000000..5f3e6c6 --- /dev/null +++ b/docs/testing/frontend-platform-testing-strategy.md @@ -0,0 +1,1283 @@ +# 프론트엔드 플랫폼 테스트 전략 + +이 문서는 도메인 기능을 추가하기 전과 추가한 후에 프론트엔드 플랫폼의 위험을 +어느 테스트 계층에서 차단할지 정의한다. 목표는 테스트 개수를 늘리는 것이 아니라, +실패 원인과 가장 가까운 계층에서 빠르고 결정적으로 결함을 발견하고 실제 +브라우저·실제 production build에서만 드러나는 위험을 별도 게이트로 닫는 것이다. + +이 문서는 다음 공식 문서를 기술 기준으로 사용한다. + +- [Vitest 공식 가이드](https://vitest.dev/guide/) +- [Mock Service Worker 공식 문서](https://mswjs.io/docs/) +- [Playwright 공식 문서](https://playwright.dev/docs/intro) +- [Playwright 시각 비교 문서](https://playwright.dev/docs/test-snapshots) +- [Storybook UI 테스트 문서](https://storybook.js.org/docs/writing-tests) + +## 1. 테스트 원칙 + +1. 테스트는 구현 계층이 아니라 사용자·운영 위험에서 출발한다. +2. 같은 위험을 모든 계층에서 반복해 검증하지 않는다. +3. pure policy와 codec은 빠른 unit/contract test에서 가능한 모든 분기를 닫는다. +4. 브라우저 API, React lifecycle, focus, layout은 DOM 또는 실제 브라우저에서 + 검증한다. +5. HTTP client를 stub하는 대신 네트워크 경계는 MSW로 검증한다. +6. production boot와 route는 개발용 component fixture만으로 완료 처리하지 않는다. +7. 성공 경로만으로 완료하지 않는다. timeout, abort, schema mismatch, 권한, + 충돌, 재시도 소진을 포함한다. +8. 접근성 자동 검사와 시각 회귀는 서로 대체하지 않는다. +9. coverage 숫자는 누락 탐지 신호이며 behavior 완료 증거가 아니다. +10. flaky test를 자동 재시도로 숨기거나 `skip` 상태로 무기한 유지하지 않는다. +11. test-only 우회 경로와 mock credential을 production bundle에 포함하지 않는다. +12. 모든 CI gate는 실패 시 종료 코드가 non-zero여야 하며 + `continue-on-error`로 낮추지 않는다. + +## 2. 현재 기준선 + +현재 저장소는 테스트 계층과 CI 증거 경로를 명시적으로 분리한다. + +### 2.1 실행 명령 + +`package.json`에는 다음 계층이 있다. + +- `test:runtime-schema` +- `test:unit` +- `test:component` +- `test:integration` +- `test:e2e` +- `test:a11y` +- `review:a11y-manual` +- `test:sample-removal` +- `test:performance` + +Vitest 결과는 JUnit으로 `artifacts/tests/`에 기록되고 Playwright는 HTML report, +trace, failure screenshot을 보존한다. `config/ci/gates.json`은 품질 gate와 증거 +경로를 등록하며 `.gitea/workflows/quality-gates.yml`은 merge/release/production/ +field/documentation 단계를 구성한다. + +### 2.2 확인된 강점 + +- runtime config와 release manifest schema test가 분리되어 있다. +- retry, error classification, compatibility, performance policy 같은 pure logic에 + unit test가 있다. +- React Testing Library와 `user-event`로 component behavior를 검사한다. +- MSW Node server로 HTTP 경계를 실제 `fetch` 수준에서 격리한다. +- 잘못된 architecture/security/type fixture가 실제로 거절되는지 검증한다. +- Chromium, Firefox, WebKit 프로젝트가 구성되어 있다. +- 등록된 모든 route에 axe 검사가 있다. +- 320px reflow와 mobile navigation을 E2E로 확인한다. +- release build의 bundle과 lab performance budget이 별도 gate다. + +### 2.3 확인된 공백 + +#### 테스트 TypeScript가 typecheck 대상이 아니다 + +현재 `check:types`는 `tsconfig.json`의 include 범위에 의존하며 tests 전체의 +callback, mock, fixture, custom matcher type을 별도 프로젝트로 검사하지 않는다. +TypeScript 전환 뒤 Vitest가 test file을 변환해 실행할 수 있다는 사실은 +`tsc` typecheck를 대체하지 않는다. + +#### 실제 bootstrap integration test가 없다 + +`tests/component/bootstrap-shell.test.jsx`는 production bootstrap을 import하지 +않고 테스트 내부의 ``만 렌더링한다. E2E는 실제 entry를 통과하지만, +다음 실패를 작은 통합 테스트에서 식별하기 어렵다. + +- runtime config fetch 실패 +- config/manifest mismatch +- adapter composition 실패 +- provider 순서 또는 누락 +- external auth owner 유무 +- product tree를 마운트하기 전 fail-closed +- boot error shell의 safe metadata +- StrictMode와 unmount cleanup + +#### TanStack Query의 React integration test가 없다 + +Query cache adapter의 명령형 `read/write/invalidate` unit test는 있지만 +`useQuery`, `useMutation`, cancellation, stale/background refresh, optimistic +rollback을 사용하는 production presentation adapter가 아직 없다. 따라서 query +provider가 마운트되어도 React 사용자의 실제 상태 전환은 검증되지 않는다. + +#### Form 테스트가 단일 TextField 흐름에 머문다 + +현재 component/E2E는 label, description, error association과 빈 값 submit을 +검사한다. error summary, 첫 오류 focus, async validation race, 422 field error, +double submit, dirty navigation, mutation conflict는 없다. + +#### Route registry와 실행 tree가 별도로 테스트된다 + +registry snapshot과 일부 navigation/access policy test는 있으나 다음 계약을 +강제하지 않는다. + +- 모든 route ID에 lazy runtime module이 존재하는가 +- params/search가 실제 codec으로 검증되는가 +- deep link와 basename refresh가 동작하는가 +- chunk load failure가 1회 reload/support surface로 연결되는가 +- route error boundary가 location 변경 시 reset되는가 +- scroll restoration과 form navigation blocker가 동작하는가 + +#### Storybook과 시각 회귀가 없다 + +`/examples/ui`는 통합 gallery지만 component별 모든 state를 격리하지 않는다. +Storybook story, interaction story, story-level axe, `toHaveScreenshot()` baseline이 +없다. `screenshot: "only-on-failure"`는 디버깅 증거이며 시각 회귀 테스트가 아니다. + +#### MSW scenario가 공유되지 않는다 + +integration file마다 `setupServer`, handler, response body를 다시 정의한다. +Node integration, Storybook browser, feature component test, E2E mock service가 같은 +시나리오 이름과 contract fixture를 공유하지 않는다. + +#### E2E가 개발 서버를 대상으로 한다 + +현재 Playwright web server는 `pnpm dev`다. route behavior 확인에는 유효하지만 +다음 release 위험은 production build/preview에서만 확인할 수 있다. + +- hashed lazy chunk +- source 변환과 tree shaking +- base path +- deep-link fallback +- build-time environment +- release manifest와 runtime config 조합 +- minified code의 chunk failure + +#### Coverage가 실행·차단되지 않는다 + +`vitest.config.js`에는 reporter만 선언되어 있고 coverage provider, script, +threshold, diff policy가 없다. + +## 3. 위험 기반 테스트 계층 + +우선순위 의미: + +- `P0`: 오류가 발생하면 애플리케이션 부팅, 데이터 무결성, 인증, 주요 사용 흐름, + 보안 또는 접근성이 깨지는 위험 +- `P1`: 주요 기능 품질, 브라우저 호환성, 운영 복구와 개발 생산성을 저하하는 위험 +- `P2`: 고급 기능 또는 특정 제품 profile에서만 필요한 위험 + +| 위험 | 우선순위 | 가장 가까운 테스트 | 추가 증거 | +| --- | --- | --- | --- | +| runtime config/manifest mismatch | P0 | schema + bootstrap integration | built-dist smoke | +| secret-like client config | P0 | negative contract fixture | browser security gate | +| HTTP request/response schema mismatch | P0 | adapter integration + MSW | feature integration | +| 중복 retry 또는 unsafe mutation retry | P0 | unit policy + MSW integration | E2E degraded scenario | +| 401 복구 loop | P0 | auth/HTTP integration | protected route E2E | +| query cancellation/stale state 오류 | P0 | query hook integration | route E2E | +| optimistic mutation rollback 오류 | P0 | mutation integration | visual state smoke | +| form validation/422 mapping 오류 | P0 | form component integration | route E2E | +| route access/deep-link 오류 | P0 | route contract/component | built-dist E2E | +| lazy chunk 복구 loop | P0 | use-case unit + release E2E | runbook drill | +| keyboard/focus/accessible name 오류 | P0 | component + story a11y | E2E/manual | +| theme/token contrast 오류 | P0 | token contract + axe | visual/manual | +| responsive overflow | P1 | component layout + E2E | visual | +| 브라우저 엔진 차이 | P1 | 3-engine E2E | manual device smoke | +| visual regression | P1 | pinned Chromium screenshot | reviewer approval | +| i18n/RTL/long text clipping | P1 | story + visual | route smoke | +| telemetry redaction | P0 | unit/adapter integration | bootstrap smoke | +| bundle 증가 | P1 | build manifest budget | release gate | +| render/performance 저하 | P1 | component profiler 선택 | lab/field metrics | +| virtualized collection | P2 | browser component | large-data E2E | +| offline/PWA persistence | P2 | service-worker integration | installable build E2E | + +## 4. TypeScript 테스트 계약 + +TypeScript 전환 후 production과 test typecheck를 분리하되 둘 다 merge gate로 +차단한다. + +### 4.1 목표 구성 + +```text +tsconfig.base.json +tsconfig.app.json +tsconfig.node.json +tsconfig.test.json +tsconfig.json # project references +``` + +`tsconfig.test.json`에는 다음을 포함한다. + +- `tests/**/*.ts` +- `tests/**/*.tsx` +- `src/**/*.stories.ts` +- `src/**/*.stories.tsx` +- `tests/setup.ts` +- custom matcher type +- MSW handlers와 factories +- Playwright tests는 필요하면 별도 `tsconfig.e2e.json` + +권장 명령: + +```bash +tsc --noEmit -p tsconfig.app.json +tsc --noEmit -p tsconfig.test.json +tsc --noEmit -p tsconfig.e2e.json +``` + +### 4.2 Type-level test + +다음은 runtime test가 아니라 compile-time test로 닫는다. + +- route ID와 runtime route map의 exhaustive mapping +- `routePath` params 누락과 잘못된 key +- query key factory input/output +- component variant closed union +- form schema와 default value shape +- use case command/result +- public port 구현 누락 +- vendor type이 public facade 밖으로 새는 문제 + +필요하면 Vitest의 `expectTypeOf`를 사용하되 실제 `tsc`도 실행한다. 의도적으로 +실패해야 하는 fixture는 독립 `tsconfig`와 `@ts-expect-error` 설명을 사용한다. +부정 fixture가 실수로 통과하면 gate가 실패해야 한다. + +### 4.3 금지 사항 + +- test file을 `any`로 우회 +- `as unknown as`로 mock contract를 무조건 통과 +- production type error를 test mock에서 숨김 +- test는 실행되므로 typecheck도 된다고 가정 +- 의도와 설명 없는 `@ts-ignore` + +## 5. Unit과 Contract 테스트 + +### 5.1 Unit 대상 + +DOM과 network 없이 결정 가능한 로직은 unit test로 검증한다. + +- error classification +- retry eligibility, attempt cap, backoff와 jitter bound +- query key canonicalization +- route access decision +- params/search codec +- locale formatter wrapper +- token/variant static map +- async view-state reducer +- form DTO mapper +- optimistic patch/rollback reducer +- chunk recovery decision +- redaction +- performance/readiness formula + +시간, random, UUID는 주입하거나 fake timer로 통제한다. 실제 `setTimeout`을 +기다리는 test를 만들지 않는다. + +### 5.2 Contract 대상 + +registry와 외부 boundary의 안정된 shape를 검증한다. + +- runtime config schema +- release manifest schema +- API operation registry +- request/response schema registry +- error registry +- route registry/runtime map +- storage key registry +- telemetry event registry +- design token registry +- mock scenario registry + +inline snapshot은 사람이 검토 가능한 작고 안정된 registry에만 사용한다. +큰 payload, DOM tree, CSS 전체를 snapshot으로 고정하지 않는다. + +### 5.3 Negative fixture + +positive test만으로 control을 증명하지 않는다. + +```text +tests/fixtures/ + architecture/ + allowed/ + forbidden/ + security/ + allowed/ + forbidden/ + typecheck/ + allowed/ + forbidden/ + routes/ + malformed-search/ + contracts/ + malformed-envelope/ +``` + +부정 fixture는 실제 production validator와 동일한 entry로 실행한다. + +## 6. 실제 Bootstrap Integration + +bootstrap test는 production entry의 로직을 재작성하지 않는다. `main.tsx`는 DOM +탐색과 최종 호출만 남기고, 테스트 가능한 함수로 boot를 추출한다. + +목표 API 예: + +```ts +bootstrapApplication({ + rootElement, + fetcher, + host, + buildConfig, + createRoot, +}); +``` + +production은 실제 dependency를 넘기고 integration test는 deterministic +dependency를 넘긴다. + +### 6.1 필수 시나리오 + +| 시나리오 | 기대 | +| --- | --- | +| valid config + coherent manifest | product tree가 한 번 마운트 | +| config fetch network failure | product tree 미마운트, safe boot shell | +| config non-JSON | safe code만 표시 | +| forbidden secret-like key | fail-closed | +| config schema mismatch | issue detail/endpoint/body 비노출 | +| manifest fetch/shape failure | safe release failure | +| config/build/release mismatch | product tree 미마운트 | +| external auth owner 존재 | external session adapter 선택 | +| external auth owner 누락 | integration-failed session | +| local demo auth | local/development에서만 허용 | +| telemetry disabled | network/queue side effect 없음 | +| storage unavailable | memory/failure policy대로 boot | +| StrictMode | subscription/cleanup leak 없음 | +| unmount | listener, timer, pending request 정리 | + +### 6.2 Provider 조립 검증 + +현재 production provider 순서를 사실대로 검증한다. + +```text +QueryClientProvider + -> BrowserRouter + -> ThemeProvider + -> SessionProvider + -> AppShell +``` + +각 provider를 mock component로 대체해 문자열 순서만 검사하지 않는다. 실제 +Context/hook을 소비하는 작은 probe route를 렌더링해 provider가 사용 가능한지 +확인한다. + +application input facade를 도입한 목표 순서는 다음과 같다. + +```text +QueryClientProvider + -> ApplicationProvider + -> RouterProvider + -> ThemeProvider + -> SessionProvider + -> AppShell +``` + +04 routing branch에서 Data Mode로 전환할 때 `BrowserRouter`를 +`RouterProvider`로 바꾸고 테스트 fixture도 같은 composition factory에서 +생성한다. 문서에 적힌 provider 순서를 테스트 전용 shell로 재현하지 말고 +production composition 함수를 호출한다. + +### 6.3 Boot E2E + +bootstrap integration이 통과해도 다음은 production build smoke로 다시 확인한다. + +- `/config.json` no-store fetch +- `/release-manifest.json` coherence +- base path +- hashed asset reachability +- boot error shell +- public route +- protected route + +## 7. Query와 Mutation 테스트 + +TanStack Query를 canonical React inbound adapter 뒤에 연결한 뒤 다음 계층을 +제공한다. + +```text +Page / AsyncSurface / Form pattern + -> local query/mutation hook + -> TanStack Query lifecycle + -> application input use case + -> outbound gateway +``` + +### 7.1 Query 필수 시나리오 + +- 최초 pending은 loading surface를 표시한다. +- 성공 payload는 view model로 렌더링된다. +- 빈 array와 빈 page는 empty로 분류된다. +- background refetch 중 기존 data를 유지한다. +- stale + degraded 상태를 표시한다. +- 같은 query key 요청은 deduplicate된다. +- filter 순서가 달라도 canonical key가 같다. +- route unmount 또는 superseded input에서 request를 abort한다. +- aborted request는 terminal error나 telemetry failure로 오분류되지 않는다. +- offline/paused와 loading을 구분한다. +- 401 복구는 한 번만 수행한다. +- 재로그인 후 허용된 operation만 다시 실행한다. +- schema mismatch는 safe terminal failure다. +- retryable failure만 bounded retry한다. +- query error reset 후 다시 성공할 수 있다. + +각 test는 새로운 `QueryClient`를 생성하고 retry를 명시적으로 통제한다. singleton +cache를 test 사이에 공유하지 않는다. + +### 7.2 Mutation 필수 시나리오 + +- submit은 한 번만 전송된다. +- keyed mutation은 동일 logical action에서 idempotency key를 유지한다. +- 성공 후 올바른 query namespace만 invalidate한다. +- optimistic update와 success reconcile이 일치한다. +- 실패 시 이전 cache로 rollback한다. +- 409 conflict를 일반 500과 구분한다. +- 422 field error는 safe field map으로 전달한다. +- non-idempotent mutation은 자동 재시도하지 않는다. +- unmount 후 state update warning이 없다. +- 사용자 취소와 timeout을 구분한다. +- mutation pending 중 중복 action이 차단된다. + +### 7.3 Test helper + +```text +tests/support/query/ + create-test-query-client.ts + render-with-query.tsx + wait-for-query-idle.ts +``` + +helper는 production default를 복사하지 않는다. production factory를 호출하고 +필요한 시간·retry만 test override로 주입한다. + +## 8. Form 테스트 + +Form test는 field primitive, form controller, application command mapping을 +분리한다. + +### 8.1 Field primitive + +- visible label과 accessible name +- description/error `aria-describedby` +- `aria-invalid` +- required/readonly/disabled +- ref와 focus +- autocomplete/inputmode +- IME composition +- controlled/uncontrolled + +### 8.2 Form controller + +- default value +- touched/dirty +- submit validation 시점 +- error summary +- 첫 invalid field focus +- async validation race와 취소 +- server 422 field/global error +- pending/double submit +- reset과 server value reinitialize +- unsaved navigation blocker + +### 8.3 Application 경계 + +- UI string을 command DTO로 normalize +- 빈 문자열/null/undefined 정책 +- locale number/date parse +- client validation 통과 후에도 application/domain validation 수행 +- server field name을 승인된 UI field에만 매핑 +- 알 수 없는 server path는 form-level safe error로 이동 +- raw backend message를 직접 표시하지 않음 + +### 8.4 E2E 최소 흐름 + +1. keyboard만으로 field를 이동한다. +2. 빈 submit 후 error summary로 focus가 이동한다. +3. summary link로 field에 이동한다. +4. 값을 수정한다. +5. mutation pending을 확인한다. +6. success 또는 conflict/422를 확인한다. +7. success 후 dirty guard가 해제된다. + +## 9. Router 테스트 + +### 9.1 Contract + +- route ID는 unique하다. +- path와 navigation order가 unique하다. +- 모든 route ID에 runtime module이 있다. +- 모든 runtime module은 registry route ID를 참조한다. +- params/search codec이 실제 객체다. +- loading/error surface가 등록된 component key다. +- route title은 typed message key다. + +### 9.2 Component/integration + +- public route +- session-required route +- recovery-pending route +- integration-failed route +- forbidden result +- not-found route +- params success/failure +- search default/invalid/canonical serialization +- same-page query change +- route heading focus +- document title +- scroll restoration +- redirect loop guard +- dirty form blocker +- error boundary reset + +### 9.3 Built-dist E2E + +- direct deep link +- browser refresh +- basename 배포 +- back/forward +- lazy route navigation +- chunk request failure +- old HTML/new manifest mismatch +- 1회 reload guard +- 404 fallback + +client route guard는 UX이며 authorization이 아님을 test 이름과 문서에서 유지한다. +403은 server 결과로도 별도 검증한다. + +## 10. Design System 테스트 + +공용 컴포넌트는 한 번의 결함이 모든 페이지로 전파되므로 위험도가 높다. + +### 10.1 Component behavior + +- native role/name/value +- keyboard matrix +- focus-visible +- disabled/readonly/pending +- controlled/uncontrolled +- ref +- callback 횟수와 payload +- portal cleanup +- overlay focus trap/restore +- live-region announcement +- reduced motion + +class 이름 자체보다 사용자에게 관찰 가능한 behavior를 우선한다. variant class +map의 exhaustive 여부는 unit/type test에서 별도로 검사한다. + +### 10.2 Token contract + +- 필수 semantic token 존재 +- light/dark 모두 정의 +- component가 raw 색상 사용하지 않음 +- focus/status contrast +- forced-colors fallback +- 반복 arbitrary value 차단 +- token gallery와 registry 일치 + +### 10.3 Story matrix + +모든 primitive/pattern은 다음 story를 가진다. + +- default +- variants +- disabled/readonly +- pending/loading +- invalid/error +- long text +- compact +- dark +- pseudo-locale +- RTL + +overlay는 open, keyboard, outside dismiss, long content, nested content를 추가한다. +form은 client/server error와 async pending을 추가한다. + +### 10.4 접근성 + +Storybook a11y를 기본 `error`로 설정한다. route axe가 초기 화면만 검사하는 공백을 +open dialog, invalid form, expanded menu 같은 state story로 보완한다. + +자동 axe 결과가 없더라도 다음을 component behavior로 직접 검사한다. + +- focus order +- focus trap/restore +- keyboard shortcut +- live announcement의 중복 +- visible focus + +## 11. Shared MSW Scenario Catalog + +[MSW](https://mswjs.io/docs/)는 request client를 mock하지 않고 HTTP 경계에서 +요청을 가로챈다. Node integration과 browser workshop이 동일한 operation contract +및 scenario vocabulary를 사용하도록 중앙 catalog를 만든다. + +### 11.1 목표 구조 + +```text +tests/mocks/ + contracts/ + envelopes.ts + payloads.ts + handlers/ + runtime-config.ts + release-manifest.ts + resources.ts + scenarios/ + catalog.ts + create-scenario-handlers.ts + server.ts + browser.ts + +tests/factories/ + failure-factory.ts + resource-factory.ts + session-owner-factory.ts +``` + +### 11.2 공통 scenario ID + +| ID | 응답 | +| --- | --- | +| `success` | 유효 envelope와 data | +| `empty` | 유효한 빈 collection | +| `slow` | 통제된 지연 | +| `network-error` | transport 실패 | +| `timeout` | client timeout 초과 | +| `aborted` | navigation/user/superseded abort | +| `content-type-mismatch` | JSON이 아닌 content type | +| `malformed-json` | 파싱 불가능한 JSON | +| `envelope-mismatch` | top-level contract 위반 | +| `schema-mismatch` | data payload contract 위반 | +| `auth-recover-once` | 첫 401 후 복구 성공 | +| `auth-persistent-401` | 복구 뒤에도 401 | +| `forbidden-403` | 권한 없음 | +| `not-found-404` | 리소스 없음 | +| `conflict-409` | mutation conflict | +| `validation-422` | 승인된 field/global error | +| `rate-limited-429` | Retry-After 포함 | +| `server-retry-success` | bounded retry 뒤 성공 | +| `server-terminal-500` | retry 소진 | + +### 11.3 Catalog 규칙 + +- scenario ID는 typed closed set이다. +- operation별 허용 scenario를 명시한다. +- factory default는 고정 값이며 random에 의존하지 않는다. +- timestamp/UUID가 필요하면 seeded factory를 사용한다. +- raw fixture에는 실제 개인정보·token을 넣지 않는다. +- test가 override한 handler는 `afterEach`에서 reset한다. +- 처리되지 않은 request는 `onUnhandledRequest: "error"`로 실패한다. +- test가 expected request count와 중요한 header/body를 검증한다. +- retry test는 attempt counter를 test 내부에서 초기화한다. +- scenario response는 production schema validator도 통과하거나 의도적으로 + 실패해야 한다. + +### 11.4 환경별 사용 + +```text +Vitest Node + -> setupServer(...handlers) + +Storybook + -> setupWorker(...handlers) + +Playwright release E2E + -> shared scenario catalog로 생성한 local mock API + 또는 동일 fixture builder를 사용하는 page.route +``` + +MSW browser worker와 scenario selector는 development/test entry에서만 import한다. +production runtime config에 `MOCK_MODE`, `SCENARIO`, fake token 같은 key를 추가하지 +않는다. + +## 12. Storybook 테스트 + +Storybook은 component를 격리해 state를 열거하고 실제 브라우저 interaction과 +접근성을 검사하는 개발·CI surface다. `/examples/ui`는 앱 통합 smoke로 유지하되 +Storybook을 대신하지 않는다. + +### 12.1 Global decorator + +- semantic token stylesheet +- ThemeProvider +- LocaleProvider +- Memory Router +- SessionProvider test owner +- QueryClientProvider +- MSW browser worker +- portal root + +모든 story가 production provider와 다른 임의 wrapper를 만들지 않도록 +`renderStory` helper를 하나만 둔다. + +### 12.2 Interaction test + +Storybook `play` 함수는 다음에 사용한다. + +- menu/dialog/drawer 열기와 닫기 +- keyboard navigation +- form validation +- toast dismiss +- tab/pagination selection +- optimistic mutation state + +같은 세부 behavior를 RTL unit과 story에 모두 복사하지 않는다. pure DOM behavior는 +빠른 component test, 여러 provider/network/browser interaction은 story에 둔다. + +### 12.3 Story a11y + +- 기본 policy는 error +- rule disable은 component/story별 owner, 사유, 만료일 필요 +- critical/serious만이 아니라 목표 WCAG tag의 모든 violation을 검토 +- incomplete 결과는 수동 검토 목록으로 전달 + +### 12.4 Story build + +`build-storybook`은 merge gate다. 다음을 차단한다. + +- 깨진 import +- 누락된 provider +- vendor facade 교체 오류 +- story type error +- public component가 isolated build에서만 실패하는 문제 + +Storybook static artifact를 production application artifact와 합치지 않는다. + +## 13. Playwright 전략 + +### 13.1 두 실행 profile + +#### 개발 피드백 + +- Vite dev server +- 빠른 Chromium 중심 smoke +- 로컬 `reuseExistingServer` +- 개발 중 route와 form 확인 + +#### Release 검증 + +```text +pnpm build + -> pnpm preview + -> Playwright release config +``` + +- CI에서 기존 server 재사용 금지 +- production `dist` +- 실제 runtime config/release manifest +- base path와 hashed chunks +- trace, video 또는 screenshot evidence + +merge gate의 주요 E2E도 가능한 한 built-dist를 사용하고, dev E2E는 개발 편의 +명령으로 분리한다. + +### 13.2 3-engine 정책 + +다음 critical smoke는 Chromium, Firefox, WebKit 모두 실행한다. + +- boot +- public route navigation +- protected route/session +- form submit/error +- dialog/drawer/menu keyboard +- theme +- 320px reflow +- automated a11y +- deep link +- lazy chunk + +고비용 exhaustive visual matrix는 pinned Chromium 하나로 실행한다. 엔진 차이 +위험이 큰 native dialog, date/input, focus behavior는 WebKit과 Firefox에서도 +별도 behavior assertion을 유지한다. + +### 13.3 Mobile과 responsive + +최소 viewport: + +- 320x720: 최소 reflow +- 390x844: 일반 mobile navigation/touch +- 768x1024: tablet +- 1280x720: desktop +- 1440x900: wide layout + +검증: + +- horizontal overflow +- sticky header/sidebar +- mobile drawer focus +- touch target +- long translated text +- landscape +- software keyboard로 가려질 수 있는 form action +- dialog max height와 scroll +- reduced motion +- dark theme + +device descriptor는 browser/device 특성을 흉내 내지만 실제 기기를 완전히 +대체하지 않는다. 제품 release policy가 요구하면 iOS Safari/Android Chrome +수동 또는 device-farm smoke를 추가한다. + +### 13.4 시각 회귀 + +Playwright `toHaveScreenshot()`을 사용한다. + +필수 baseline: + +- app shell compact/wide +- 각 page template +- 모든 design-system primitive group +- loading/empty/error/401/403/404 +- invalid form +- open dialog/drawer/menu +- light/dark +- pseudo-locale/RTL 대표 + +결정성 규칙: + +- OS, browser, font, device scale을 CI image로 고정 +- animation/caret 비활성화 +- clock/random/network fixture 고정 +- 개인정보와 동적 ID mask +- update snapshot은 전용 명령과 reviewer 승인을 요구 +- threshold를 높여 실제 차이를 숨기지 않는다. + +Chromatic 같은 cloud visual service는 선택이다. 저장소 내부 Playwright baseline은 +외부 서비스 없이도 실행 가능해야 한다. + +### 13.5 실패 증거 + +- trace: first retry 또는 최종 실패 +- screenshot: 실패 상태 +- HTML report +- console/page error +- network failure summary +- release/build ID + +CI retry를 허용하는 경우 첫 실패 trace도 폐기하지 않는다. retry 후 통과한 test는 +flaky signal로 집계한다. + +## 14. Coverage 정책 + +Coverage 목표는 “99% 완성도”와 같은 표현을 숫자로 대신하기 위한 것이 아니다. +높은 위험의 branch가 실행되었는지 확인하는 보조 gate다. + +### 14.1 도구 + +Vitest coverage provider를 명시적으로 설치하고 `coverage` script를 추가한다. +Vite/Vitest 조합에서는 V8 provider를 기본 후보로 사용하되 source map 정확성을 +fixture로 확인한다. + +필수 report: + +- text +- JSON summary +- LCOV 또는 Cobertura + +### 14.2 위험별 목표 + +| 영역 | Line/statement 참고 | Branch 우선 목표 | +| --- | --- | --- | +| registry/codec/schema | 95~100% | 100%에 가깝게 | +| retry/error/auth/chunk policy | 95~100% | 모든 결정 분기 | +| HTTP/storage/telemetry adapter | 90% 이상 | 모든 failure class | +| query/mutation/form controller | 90% 이상 | 상태 전이 전부 | +| design-system primitive | 숫자보다 state matrix | keyboard/error/open 전부 | +| route/page composition | 80% 이상 참고 | critical route 전부 | +| scripts/release checks | 90% 이상 | positive/negative fixture | + +전체 global threshold 하나만 두면 쉬운 파일로 위험한 파일의 누락을 가릴 수 있다. +glob 또는 별도 package/명령으로 high-risk module threshold를 강화한다. + +### 14.3 Diff coverage + +신규·변경 코드의 executable line과 branch는 기본적으로 테스트되어야 한다. +예외는 다음을 기록한다. + +- 실행 불가능한 defensive line +- browser engine 전용 branch +- external evidence만 가능한 branch +- owner +- 사유 +- 만료일 또는 제거 조건 + +### 14.4 제외 + +다음만 명시적으로 제외한다. + +- generated type +- build output +- story metadata 자체 +- 순수 type-only file +- schema에서 생성된 code + +bootstrap, facade, error fallback을 “테스트가 어렵다”는 이유로 제외하지 않는다. + +## 15. Fixture와 테스트 디렉터리 + +현재 중앙 test taxonomy를 유지하면서 책임을 명확히 한다. + +```text +tests/ + runtime-schema/ + unit/ + contract/ + component/ + integration/ + bootstrap/ + query/ + forms/ + features/ + e2e/ + smoke/ + routes/ + forms/ + accessibility/ + visual/ + mocks/ + contracts/ + handlers/ + scenarios/ + factories/ + fixtures/ + architecture/ + security/ + typecheck/ + contracts/ + support/ + render/ + query/ + router/ + clock/ + setup.ts +``` + +Story는 component와 가까이 둔다. + +```text +src/adapters/inbound/react/design-system/primitives/button/ + button.tsx + button.css + button.stories.tsx +``` + +### 15.1 역할 구분 + +- `factory`: 유효한 typed object를 기본값과 override로 생성 +- `fixture`: 변경하지 않는 positive/negative 샘플 +- `handler`: operation request를 intercept +- `scenario`: 여러 handler와 상태를 사용자 흐름으로 조합 +- `support`: render wrapper, deterministic clock, test query client + +factory가 production schema를 우회하지 않게 contract test에서 생성 결과를 +validate한다. + +### 15.2 파일 이름 + +- unit/component/integration: `*.test.ts`, `*.test.tsx` +- Playwright: `*.spec.ts` +- story: `*.stories.tsx` +- negative fixture는 기대 실패 이유를 directory/name으로 표현 + +`utils.ts`, `helpers.ts`, `fixture.ts` 같은 의미 없는 단일 파일에 모든 기능을 +모으지 않는다. + +## 16. CI Gate 설계 + +기존 gate taxonomy에 다음 검증을 명시적으로 포함한다. + +### 16.1 Merge gate + +- frozen install +- production typecheck +- test/e2e typecheck +- lint +- architecture +- runtime schema +- unit +- contract +- component +- integration +- coverage +- Storybook build +- Storybook interaction/a11y +- critical 3-engine E2E +- automated route a11y +- signed manual accessibility evidence for every registered route in scope +- design-system visual baseline +- production build +- sample removal +- security + +### 16.2 Release gate + +- bundle budget +- built-dist 3-engine smoke +- base path/deep-link +- release/config coherence +- chunk mismatch recovery +- hosting header +- lab performance +- release visual smoke + +### 16.3 Production/field gate + +- rollback/runbook drill +- provider smoke +- approved production Web Vitals evidence + +외부 배포 주소나 28일 field evidence가 없는 skeleton 개발 단계에서는 해당 gate가 +실제 프로젝트가 채울 계약으로 남는다. 이를 fake data로 통과시키지 않는다. +현재 `FE-GATE-009`의 signed manual accessibility review는 merge gate다. 이 +문서는 이를 production/field gate로 이동시키지 않는다. + +### 16.4 병렬화와 shard + +- unit/contract/component는 안정된 shard key를 사용한다. +- Playwright는 project와 shard를 함께 증거 이름에 포함한다. +- shard 하나가 실패해도 나머지 증거를 업로드한다. +- 최종 gate는 모든 shard의 통과를 AND로 계산한다. +- test order 의존성을 찾기 위해 정기적으로 순서를 섞을 수 있으나 random seed를 + 증거에 기록한다. + +### 16.5 Flaky policy + +- merge를 통과시키기 위한 임의 `test.skip` 금지 +- quarantine에는 owner, defect ID, 영향 route, 만료일 필요 +- retry 후 pass도 성공으로만 집계하지 않고 flaky report에 기록 +- 동일 test가 반복되면 clock/network/focus/shared-state 원인을 제거 +- CI machine 성능에 맞추기 위해 assertion을 제거하거나 timeout만 계속 늘리지 + 않는다. + +## 17. 새 Feature 테스트 Recipe + +도메인 feature를 추가할 때 다음 순서를 따른다. + +각 단계는 feature capability에 해당할 때 적용한다. 적용되지 않는 query, +mutation, form, visual, native-browser 항목은 조용히 생략하지 않고 테스트 계획에 +`N/A`와 이유를 기록한다. 예를 들어 read-only static route에 422, optimistic +rollback, dirty form test를 만들지 않는다. + +### Step 1. 위험과 계약을 열거한다 + +- 사용자가 완료하려는 action은 무엇인가? +- 데이터 손실, 중복 mutation, 권한 노출 위험은 무엇인가? +- URL, API operation, query key, telemetry event는 무엇인가? +- loading/empty/stale/error/conflict/access 상태는 무엇인가? +- keyboard, mobile, locale 요구는 무엇인가? + +위험마다 가장 가까운 테스트 계층을 지정한다. + +### Step 2. Type과 schema를 먼저 닫는다 + +- route params/search +- command/query +- API request/response +- domain/application result +- view model +- form value +- query key + +positive와 negative type/schema fixture를 추가한다. + +### Step 3. MSW scenario를 등록한다 + +feature operation에 필요한 scenario ID를 catalog에 추가한다. + +최소: + +- success +- empty 또는 not-found +- slow +- auth/forbidden +- schema mismatch +- retryable/terminal failure +- mutation이면 409/422 + +기존 공통 scenario로 충분하면 새 이름을 만들지 않는다. + +### Step 4. Pure policy와 mapper를 unit test한다 + +- normalization +- mapping +- policy +- error classification +- query key +- optimistic update를 사용하는 mutation의 patch/rollback + +DOM이나 MSW를 불필요하게 사용하지 않는다. + +### Step 5. Query/mutation integration을 작성한다 + +- 실제 local query adapter +- 새 QueryClient +- 실제 application use case +- MSW +- query cancellation/retry, mutation invalidation, 적용되는 경우 optimistic + rollback + +HTTP client를 `vi.fn()` 결과로 대체해 boundary contract를 건너뛰지 않는다. + +### Step 6. Form이 있는 경우 form/controller를 작성한다 + +- field semantics +- client validation +- 422 mapping +- submit pending +- conflict +- dirty/reset + +### Step 7. Page component를 검증한다 + +- page template +- initial/loading/empty/success/error +- actions +- route params/search +- heading focus +- access state + +role과 accessible name으로 상호작용한다. + +### Step 8. Story를 추가한다 + +- 모든 주요 state +- dark +- compact +- long/pseudo locale +- interaction +- a11y + +### Step 9. E2E critical flow를 추가한다 + +- direct route +- keyboard flow +- success +- 사용자 복구 가능한 failure +- mobile +- 3-engine이 필요한 native/focus behavior + +implementation detail가 아니라 사용자 결과를 assertion한다. + +### Step 10. Visual baseline을 추가한다 + +새 layout, template variant, 상태 표면이 생긴 경우만 baseline을 추가한다. 기존 +primitive를 단순히 조합한 모든 feature page를 무조건 screenshot으로 고정하지 +않는다. + +### Step 11. Evidence와 문서를 갱신한다 + +- test taxonomy +- route/accessibility scope +- CI gate evidence +- feature recipe +- 운영 failure/runbook 연결 + +### Step 12. 전체 gate를 실행한다 + +```bash +corepack pnpm check:types +corepack pnpm lint +corepack pnpm check:architecture +corepack pnpm test:runtime-schema +corepack pnpm test:unit +corepack pnpm test:component +corepack pnpm test:integration +corepack pnpm test:e2e +corepack pnpm test:a11y +corepack pnpm build +corepack pnpm check:bundle +``` + +TypeScript test, Storybook, coverage, visual, built-dist 명령이 도입되면 위 목록과 +CI registry에 추가한다. + +## 18. Feature Definition of Done + +아래 체크는 feature에 존재하는 capability에 적용한다. `N/A`에는 이유와 해당 +위험을 대신 검증하는 계층을 기록한다. 공통 type, architecture, bootstrap, +접근성, security gate는 임의로 `N/A` 처리할 수 없다. + +### Type과 계약 + +- [ ] production source와 test source typecheck가 통과한다. +- [ ] route/API/query/form type이 closed contract다. +- [ ] positive와 필요한 negative schema fixture가 있다. +- [ ] registry와 runtime mapping이 exhaustive하다. + +### Unit과 integration + +- [ ] pure policy와 mapper의 모든 중요 branch를 검증했다. +- [ ] MSW shared scenario를 사용한다. +- [ ] unhandled request가 test를 실패시킨다. +- [ ] query가 있으면 cancellation, retry, stale 상태를 검증했다. +- [ ] mutation이 있으면 invalidation/conflict를, optimistic update를 쓰면 + rollback을 검증했다. +- [ ] auth recovery가 bounded임을 검증했다. + +### Form과 UI + +- [ ] form이 있으면 field label/description/error가 연결된다. +- [ ] form이 있으면 error summary와 first-invalid focus가 동작한다. +- [ ] mutation form이 있으면 pending과 double submit을 검증했다. +- [ ] loading/empty/success/error/access 상태가 있다. +- [ ] keyboard와 focus test가 있다. +- [ ] component/story a11y가 통과한다. + +### Router와 bootstrap + +- [ ] deep link와 browser navigation이 동작한다. +- [ ] params/search invalid 입력이 안전하게 처리된다. +- [ ] route error를 검증하고 lazy chunk가 있는 경우 recovery를 검증했다. +- [ ] 실제 bootstrap/provider composition에서 feature가 동작한다. +- [ ] built-dist smoke가 통과한다. + +### Browser와 visual + +- [ ] native/focus/browser 차이가 있는 critical flow가 지정된 3개 엔진에서 + 통과하고, 나머지는 browser matrix 정책을 따른다. +- [ ] 320px와 대표 mobile viewport에서 overflow가 없다. +- [ ] 필요한 light/dark visual baseline이 있다. +- [ ] pseudo-locale/긴 문구가 잘리지 않는다. +- [ ] failure trace와 report가 CI evidence로 남는다. + +### Coverage와 운영 + +- [ ] high-risk module branch 목표를 충족한다. +- [ ] 신규 코드의 미검증 branch에 승인 없는 예외가 없다. +- [ ] bundle/performance budget을 통과한다. +- [ ] telemetry/error output에 민감 정보가 없다. +- [ ] 관련 gate와 evidence registry가 갱신되었다. + +## 19. 금지 패턴 + +- production bootstrap을 복사한 test-only shell만 검증 +- query cache singleton을 test 사이에 공유 +- `fetch`나 HTTP client 전체를 `vi.fn()`으로 대체하고 MSW integration 생략 +- 성공 응답만 제공하는 feature mock +- test마다 서로 다른 401/422/500 body를 임의 작성 +- test에서 실제 sleep 사용 +- timeout을 늘려 race condition 숨김 +- implementation class와 DOM nesting만 assertion +- 대형 DOM snapshot으로 behavior test 대체 +- failure screenshot을 visual regression이라고 부름 +- dev server E2E만으로 release build 완료 선언 +- Chromium만 통과하고 native focus/browser 호환 완료 선언 +- axe 결과만으로 접근성 완료 선언 +- global coverage 숫자로 고위험 branch 누락 은폐 +- type error를 `any`, `@ts-ignore`, 이중 cast로 숨김 +- production bundle에 MSW worker, mock selector, fake credential 포함 +- flaky test를 owner/만료일 없이 skip +- CI gate에 `continue-on-error` + +## 20. 단계별 도입 순서 + +1. `tsconfig.test.json`과 test typecheck gate를 추가한다. +2. production bootstrap을 주입 가능한 함수로 추출하고 integration test를 만든다. +3. MSW handlers/scenario/factory를 중앙 catalog로 이동한다. +4. query/mutation presentation adapter와 integration harness를 만든다. +5. form foundation과 form/controller test matrix를 만든다. +6. route registry/runtime map contract와 built-dist E2E를 추가한다. +7. Storybook build, interaction, a11y gate를 추가한다. +8. pinned Chromium visual baseline을 추가한다. +9. critical flow의 3-engine release profile을 분리한다. +10. V8 coverage와 high-risk/diff policy를 차단 gate로 추가한다. +11. feature recipe와 Definition of Done를 pull request template에 연결한다. + +이 순서의 완료 기준은 테스트 도구를 모두 설치하는 것이 아니다. 새 도메인 +기능이 추가되었을 때 개발자가 성공·실패·권한·복구·접근성·브라우저·release +위험을 어디서 어떻게 검증할지 추가 설계 없이 결정할 수 있어야 한다. diff --git a/docs/testing/taxonomy.md b/docs/testing/taxonomy.md index 0f460aa..8a4b847 100644 --- a/docs/testing/taxonomy.md +++ b/docs/testing/taxonomy.md @@ -29,3 +29,10 @@ Promotion is an AND graph: 2. merge gates plus release gates 3. release gates plus rollback/runbook drills 4. production promotion plus eligible field Web Vitals evidence + +This file describes the currently registered taxonomy. The +[frontend platform testing strategy](./frontend-platform-testing-strategy.md) +documents the target additions: test TypeScript projects, real bootstrap +composition tests, shared MSW scenarios, query/mutation/form/router coverage, +Storybook interaction and accessibility checks, visual regression, and a +built-output Playwright profile.