1083 lines
54 KiB
Markdown
1083 lines
54 KiB
Markdown
# 프론트엔드 플랫폼 구현 로드맵
|
|
|
|
## 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-commit>`으로 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가 가능하게 한다.
|
|
|
|
**구현 증거 (2026-07-26)**
|
|
|
|
- VD-04에서 dependency 추가 없는 native controller + Zod local facade를
|
|
채택했고 vendor 도입 조건을 문서화했다.
|
|
- `src/presentation/forms`가 field registration, parse/error map,
|
|
dirty/touched/reset/pending/result, 422 allowlist, first-error focus,
|
|
duplicate submit과 dirty navigation을 제공한다.
|
|
- `src/presentation/templates`가 다섯 page 유형의 slot/landmark/responsive
|
|
계약을 제공하며 architecture negative fixture가 application/vendor import를
|
|
거절한다.
|
|
- reference list/detail/create/status route가 네 구체 template를 사용하고
|
|
production composition test가 list → form → command → HTTP → invalidation →
|
|
list 경로를 실행한다.
|
|
- component/integration/E2E test가 validation, transform, 422, conflict,
|
|
secret 비노출, navigation focus와 320px reflow를 검증한다.
|
|
|
|
### 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을
|
|
분리한다.
|
|
|
|
**구현 증거 (2026-07-26)**
|
|
|
|
- VD-05에서 `lucide-react@1.25.0` static semantic facade와 native-first
|
|
interaction을 채택하고 headless vendor 재평가 조건을 닫았다.
|
|
- `src/presentation/design-system`이 48개 필수 token, public TypeScript barrel,
|
|
action/form/feedback/overlay/navigation primitive와 공통 pattern을 제공한다.
|
|
- 기존 `components/ui` 경로는 compatibility export로 유지하고 앱 셸, gallery와
|
|
reference feature는 public entry를 소비한다.
|
|
- 모바일 navigation은 native modal Drawer로 전환되어 배경 비활성화, Escape,
|
|
route dismiss와 trigger focus restore를 제공한다.
|
|
- source/negative fixture gate가 undefined token, raw palette, direct vendor,
|
|
deep import, tooltip-only 정보와 accessible name 누락을 거절한다.
|
|
- component/browser test가 Menu typeahead, Tabs activation, Toast queue,
|
|
form controls, compact reflow와 open-dialog axe를 실행한다. 로컬 WebKit은 host
|
|
`libevent-2.1.so.7` 부재로 환경 검증 상태를 유지한다.
|
|
|
|
### 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를
|
|
파괴적으로 덮어쓰지 않는다.
|
|
|
|
**구현 증거 (2026-07-26)**
|
|
|
|
- VD-06에서 dependency를 추가하지 않는 browser `Intl` + typed local catalog를
|
|
채택하고 vendor 재평가 조건, fallback과 key migration 정책을 문서화했다.
|
|
- `src/presentation/i18n`이 137개 common key, key별 interpolation,
|
|
`ko-KR` fallback, compatibility alias, date/number/relative/list/plural/select
|
|
formatter와 `LocaleProvider`를 제공한다.
|
|
- shell, route lifecycle/access/recovery, async/form error, page template와
|
|
design-system default copy가 catalog consumer로 연결됐다.
|
|
- feature route copy는 feature-owned catalog contribution으로 분리되어 reference
|
|
feature 제거 시 source와 built artifact에 전용 message key가 남지 않는다.
|
|
- reference application mapper는 locale-formatted date 대신 timestamp를
|
|
반환하고 presentation formatter가 UTC 또는 명시 timezone을 적용한다.
|
|
- `check:i18n`과 type negative fixture가 catalog/placeholder 불일치,
|
|
hardcoded common literal, backend raw message render, unsafe HTML,
|
|
unknown key와 interpolation mismatch를 거절한다.
|
|
- unit/component/browser test가 safe fallback, pseudo 320px reflow,
|
|
document `lang/dir`, RTL Drawer/Tabs/directional icon과 deterministic formatter를
|
|
검증한다.
|
|
|
|
### 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는 유지한다.
|
|
|
|
**구현 증거 (2026-07-26)**
|
|
|
|
- VD-07에서 level/event 기반 `DiagnosticsPort`와 semantic `TelemetryPort`를
|
|
분리하고 bounded memory/no-op 또는 설정 기반 best-effort HTTP exporter를
|
|
채택했다.
|
|
- diagnostics 8종과 telemetry 5종의 registry, context/attribute allowlist,
|
|
고카디널리티 value policy, timestamp와 status/attempt/duration/queue bucket을
|
|
구현했다.
|
|
- boot, route, render, HTTP logical outcome, cache, storage, release mismatch와
|
|
telemetry drop을 production composition에 연결했다. HTTP는 success/recovery/
|
|
terminal/abort 각각 logical execution당 diagnostics 한 번, terminal
|
|
non-abort failure telemetry 한 번만 발행한다.
|
|
- bounded oldest-drop queue, drop reason 집계, sink/observer failure 격리와
|
|
nonrecursive delivery evidence를 구현했다. exporter가 없으면 network와 queue
|
|
side effect가 없는 true no-op이다.
|
|
- `check:diagnostics`, source negative fixture와 TypeScript negative fixture가
|
|
producer 누락, direct console, unknown event/context, raw URL/query/body/
|
|
credential 경계를 거절한다.
|
|
- unit/integration test가 circular/hostile error, pre-mount boot, queue/sink
|
|
failure, no-op, cache/storage/release producer, success/retry recovery/terminal/
|
|
abort 횟수와 reference route/operation/correlation context를 검증한다.
|
|
|
|
### 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만 허용한다.
|
|
|
|
**구현 증거 (2026-07-26)**
|
|
|
|
- VD-08에서 dev-only Storybook static workshop과 production build를 대상으로 한
|
|
local Playwright visual baseline을 채택하고 cloud review는 선택 사항으로
|
|
분리했다.
|
|
- 10개 registry의 required field, runtime type, enum, unique, cross-reference,
|
|
consumer와 orphan을 검사하고 승인 snapshot digest와 현재 snapshot의 actual
|
|
semantic diff를 계산한다. 행·field·type·path뿐 아니라 registry 검증 계약
|
|
변경도 breaking evidence 대상이다.
|
|
- ordering-only 변경은 `none`, row addition은 `additive`, 일반 값 변경은
|
|
`behavior-change`, 제거/type/path/contract 변경은 `breaking`으로 계산한다.
|
|
breaking에는 version, migration, compatibility window, rollback과 owner를
|
|
요구하며 digest 변조와 누락 fixture가 실제로 실패한다.
|
|
- API operation별 19개 shared MSW scenario catalog와 strict unhandled-request
|
|
server를 제공하고 reference vertical integration이 공통 envelope/handler를
|
|
사용한다.
|
|
- 기본 Playwright는 `build` + `preview`의 실제 `dist`를 Chromium, Firefox,
|
|
WebKit에서 검사하고 별도 compact project를 제공한다. 개발 피드백용 Vite
|
|
profile은 `playwright.dev.config.js`로 분리했다.
|
|
- Storybook public primitive story, interaction과 axe test, wide/compact/
|
|
pseudo/dark/state surface의 pinned Chromium visual baseline 4종을 CI evidence로
|
|
연결했다.
|
|
- V8 coverage와 9개 high-risk module을 대상으로 40개 scoped threshold를
|
|
적용하고 threshold 미달 fixture를 차단한다.
|
|
- deterministic clock/random/scheduler/storage, unexpected console/page error/
|
|
request failure 정책, 무소유 skip과 full-screen mask 금지 gate를 제공한다.
|
|
- JUnit, HTML report, trace/screenshot, coverage, registry와 fixture artifact를
|
|
기존 26개 blocking gate taxonomy에 연결했다.
|
|
|
|
### 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을 보류한다.
|
|
|
|
**구현 증거 (2026-07-26)**
|
|
|
|
- VD-09에서 frozen pnpm graph와 lockfile을 local SSOT로, package manifest
|
|
license policy와 CycloneDX 1.6을 local evidence로 채택했다. 외부 vulnerability
|
|
report와 signed attestation이 없으면 promotion은 `FAIL_UNVERIFIED`다.
|
|
- 현재 직접 35개, 전체 전이 561개 dependency의 name/version, direct/scope/
|
|
optional, SHA-512 integrity, license와 dependency edge를 deterministic
|
|
inventory로 생성한다. lockfile row와 inventory가 양방향 일치하지 않으면
|
|
실패한다.
|
|
- 승인 baseline digest와 actual add/remove/change/upgrade diff를 계산하고 새
|
|
direct production dependency에는 owner와 다른 reviewer, reason과 rollback을
|
|
요구한다.
|
|
- CycloneDX SBOM component/edge와 local in-toto/SLSA 형태 provenance의
|
|
source/lock/SBOM/dist digest를 coherence gate로 다시 계산한다.
|
|
- license allow/deny, vulnerability severity와 독립·만료 exception 정책,
|
|
provider lock digest와 attestation subject를 machine-readable하게 검증한다.
|
|
provider fixture는 promotion PASS를 증명한 뒤 unconfigured
|
|
`FAIL_UNVERIFIED`를 복원한다.
|
|
- secret scan을 source/scripts/tests/config/schema/public/dist/generated release
|
|
metadata로 확장하고 원문 대신 rule/path/line/fingerprint만 SARIF에 남긴다.
|
|
test-only allowlist도 owner/reason/expiry를 강제한다.
|
|
- `SOURCE_DATE_EPOCH` 기반 동일 build 2회 digest, 실제 frozen install mismatch,
|
|
transitive omission/integrity/baseline/self-review/license/vulnerability/
|
|
provider/SBOM/provenance/secret negative fixture를 blocking gate에 연결했다.
|
|
|
|
## 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하거나 문서상 예외로 바꾸는 것은 완료가 아니다.
|