# 01. 새 기능 추가하기 — 0~11단계 핵심은 둘이다. - 뼈대는 손으로 만들지 않는다. `corepack pnpm create:feature `로 만든다. - 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다. 다른 기능 폴더를 복사해 이름을 바꾸는 방법은 쓰지 않는다. 그 방법은 접두어 없는 전역 ID, 복사된 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다. 생성 명령은 이 문제를 미리 피한 파일을 쓴다. 템플릿에는 복사해 볼 기능 샘플이 없다. 생성 뼈대에 없는 모양은 이 매뉴얼 안의 코드 조각으로 보인다. 코드 조각 위의 `manual-code-block` 표식이 그 조각을 둘 자리다. 조각은 `create:feature invoice-feature --with-create`로 만든 기능을 기준으로 쓴다. `tests/unit/manual-code-blocks.test.ts`가 그 기능을 저장소 사본에 만들고 조각을 그 자리에 그대로 넣어 타입 검사와 동작 시험을 돌린다. ## 전체 흐름 ```text 0 경계 정하기 (기존 context? 새 context?) → 1 create:feature로 뼈대 만들기 → 2 도메인 모델 (선택) → 3 API 계약 → 4 application input → 5 HTTP 어댑터와 조립 기여 → 6 라우트 → 7 쿼리·뮤테이션 → 8 페이지 → 9 기준선과 증거 → 10 테스트 → 11 제거 확인 ``` 1단계의 생성 명령이 3~8단계와 10단계의 가장 작은 판을 한 번에 만든다. - 라우트 1개 (파라미터 없는 목록) - GET 1개 (`SAFE`, `EXTERNAL_BEARER`). 경로는 짝 백엔드 `new-feature.sh`와 같은 `/`이다 - 쿼리 1개와 무효화 topic 1개 - `CollectionPage` 페이지 1개와 ko-KR·en-US 문구. 결과 수는 백엔드가 보낸 `meta.page.total`이다 - 테스트 3개와 테스트용 앱 파일 1개 (application input 단위 테스트, 라우터를 거치는 페이지 테스트, 백엔드 본문을 적은 gateway 테스트, `-test-app.tsx`) `--with-create`를 주면 짝 백엔드 `new-feature.sh`가 만드는 나머지 두 엔드포인트를 함께 만든다. - 상세 GET(`GET //{id}`)과 `DetailPage` 상세 페이지 - 작성 POST(`POST /`, 201)와 `FormPage` 작성 폼, 결과 불명 화면 - 작성 폼 테스트: 201 저장 뒤 상세 열기, 400 `_INVALID`를 이름 칸에 보이고 다시 저장, 응답을 잃은 저장 - 작성은 기본이 `NEVER`다. 백엔드 생성기의 create가 `NOT_IDEMPOTENT`라서다. 백엔드 create를 KEYED로 바꿨으면 `--keyed`를 함께 준다([02 결정표 3절](02-decision-tables.md#3-재시도-의미)). 그래서 3~8단계는 "처음부터 쓰기"가 아니라 "생성된 파일을 실제 계약과 화면으로 바꾸기"다. ## 단계마다 적은 것 - ① **정할 것**: 이 단계에서 고르는 값과 선택지. - ② **기준**: 무엇을 보고 고르나. 표가 필요한 판단은 [02 결정표](02-decision-tables.md)에 있다. - ③ **잡는 검사 / 못 잡는 것**: 실수했을 때 어느 명령(게이트 ID)이 어떤 메시지로 잡는가. "못 잡음"은 이 커밋의 검사가 잡지 못한다는 뜻이다. 메시지 전체는 [reference/errors.md](reference/errors.md)에 있다. - ④ **쓸 스킬**: AI 에이전트가 부를 스킬. --- ## 0단계. 경계와 소속 정하기 ① **정할 것** - 기존 context에 넣을지, 새 context를 만들지. - context: 같은 URL 앞부분(라우트 루트) 아래에서 함께 지연 로드되는 기능 묶음이다. - 기능 ID. 케밥 표기만 쓴다. 소문자 단어를 `-`로 잇는 꼴이다(`invoice-feature`). ② **기준** - context 판단은 [02 결정표 1절](02-decision-tables.md#1-context-경계)과 원칙 1을 본다. - 기능 ID는 네 곳에 같은 문자열로 들어간다. 나중에 바꾸기 어렵다. - `feature-module.ts`의 `FEATURE_MODULE_ID` - 계약의 `featureId` - `ApplicationFeatureInputs`의 키 - `config/runtime/.json`의 `FEATURE_OVERRIDES` 키 - ID가 `-feature`로 끝나면 생성 명령은 그 앞부분을 접두어로 쓴다. `invoice-feature`면 `invoice`, `INVOICE_`, `Invoice`다. - 근거: `scale-architecture.md` §5(모듈 소유), §7(개수 예산), §9(라우터 구조). ③ **잡는 검사 / 못 잡는 것** - 기능 라우트가 context 루트 밖에 있으면 앱 모듈이 적재 때 거부한다. - 메시지: `Route () of feature is not under the route root of its context (...)` - 앱 모듈을 적재하는 테스트(라우터를 거치는 페이지 테스트, component 테스트)와 앱 부팅이 실패한다. `tests/architecture/context-route-roots.test.ts`는 이 규칙을 fixture로만 고정하고, 설치된 기능의 라우트는 보지 않는다. - 생성 명령은 라우트를 늘 루트 아래에 둔다. 손으로 경로를 바꿀 때만 걸린다. - context 하나에 기능이 예산보다 많으면 생성기가 거부한다. - 메시지: `Context feature cardinality exceeds budget ` - 예산은 선언 파일의 `CONTEXT_MAX_FEATURES`다. - **못 잡음**: 경계를 잘못 고른 것 자체. 업무가 다른 기능을 한 context에 넣어도 검사는 통과한다. ④ **쓸 스킬**: `domain-driven-design` --- ## 1단계. 뼈대 만들기 — `create:feature` 기본 길은 생성 명령이다. ```bash corepack pnpm create:feature invoice-feature ``` 명령이 하는 일: ```text 인자 검사 → 설치된 기능·context·라우트·topic·문구 키 읽기 → 충돌 검사 (겹치면 아무것도 쓰지 않고 거부) → 파일 쓰기 (있는 파일은 덮어쓰지 않음) → 생성기 실행 → 생성기가 거부하면 만든 파일을 모두 지움 → dev server manifest(public/release-manifest.json, 추적 파일) 다시 쓰기 → 만든 파일과 다음 할 일 출력 ``` - 기능과 함께 커밋할 추적 파일은 둘이다. dev server manifest와 초기 JS 기록이다. 기능 브랜치 둘이 같은 줄에서 충돌하면 명령을 다시 돌린다. 표와 명령은 [03 문서 A](03-outside-feature-folder.md#a-생성-명령이-만든다)에 있다. ① **정할 것** - `--context `: 0단계에서 기존 context를 골랐을 때만 준다. - `--with-create`: 상세와 작성까지 만든다. 짝 백엔드에서 `scripts/new-feature.sh `을 같은 이름으로 돌렸을 때 준다(예: 프론트 `invoice-feature`, 백엔드 `Invoice` → 둘 다 `/invoices`). - `--keyed`: `--with-create`와 함께만. 백엔드 create를 멱등성 executor 뒤에 두었을 때(KEYED) 준다. - `--package @scope/name@x.y.z --digest sha256:<64 hex> --revision `: 계약 패키지가 이미 배포됐을 때 준다. 셋은 함께 준다. - 둘 다 없으면 새 context와 자리표시자 계약 신원으로 만든다. - 자리표시자 신원: 패키지가 아직 없을 때 쓰는 가짜 신원이다. 로컬·개발 빌드는 되고, staging·production 승인은 거절한다. ② **기준** - 패키지가 아직 없으면 자리표시자로 시작한다. 3단계에서 실제 신원으로 바꾼다([02 결정표 2절](02-decision-tables.md#2-계약-출처)). - 손으로 만드는 길도 있다. `docs/architecture/starter-experience.md`의 "Adding a feature" 절이 그 순서다. 다만 전역 ID 접두어, 무작위 topic, a11y 기록을 직접 챙겨야 한다. - 인자·파일·출력 전체는 [reference/create-feature.md](reference/create-feature.md)에 있다. ③ **잡는 검사 / 못 잡는 것** - 명령 자체가 거부한다. ID 형식, 기존 기능·context와 겹침, 라우트·경로·chunk·문구 키 충돌, topic 충돌, 패키지 신원 형식. - 생성기가 거부한다. 선언 헤더가 리터럴이 아님, 없는 context, 예산 초과. - 이때 명령은 만든 파일을 모두 지우고 `the feature index generator rejected the feature, nothing was kept:`로 끝난다. - 생성한 context 선언은 `tests/unit/create-feature.test.ts`가 생성기의 선언 읽기와 앱 모듈 조립으로 실행한다. 라우트가 그 루트 밖이면 그 테스트가 실패한다. ④ **쓸 스킬**: `clean-architecture`, `codebase-design` --- ## 2단계. 도메인 모델 (선택) 생성 명령은 `domain/` 폴더를 만들지 않는다. ① **정할 것**: 업무 규칙(불변식)이 있는가. - 불변식: 늘 참이어야 하는 업무 조건이다. 예: "금액은 0 이상", "마감일은 시작일 뒤". ② **기준** - 업무 규칙이 없으면 만들지 않는다. mapper가 DTO를 화면 값으로 바꾸는 것으로 충분하다. - 있으면 `domain/.ts`에 둔다. - 생성 함수에서 불변식을 검사하고 `Object.freeze`로 고정한다. - 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(예: 와이어 `name`을 화면 값 `displayName`으로). - 예: 청구서는 발행일 뒤에만 마감된다. `domain/.ts` 한 파일이다. ```ts export type Invoice = Readonly<{ invoiceId: string; /** Calendar dates, YYYY-MM-DD. */ issuedOn: string; dueOn: string; }>; /** An invoice falls due on or after the day it is issued. */ export function createInvoice(input: Invoice): Invoice { if (!/^\d{4}-\d{2}-\d{2}$/u.test(input.issuedOn) || !/^\d{4}-\d{2}-\d{2}$/u.test(input.dueOn)) { throw new RangeError("Invoice dates are calendar dates (YYYY-MM-DD)."); } if (input.dueOn < input.issuedOn) { throw new RangeError("An invoice falls due on or after the day it is issued."); } return Object.freeze({ ...input }); } ``` - 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다. - 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다. - 서버가 정한 제한이면 `contracts/-schemas.ts`에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다. - 생성 판(`--with-create`)도 이름 길이 상수(`_NAME_MAX_LENGTH`)를 스키마(`contracts/-schemas.ts`)와 폼(`presentation/-form.ts`)에만 둔다. `domain/`에는 없다. - domain에는 서버 제한이 바뀌어도 그대로인 업무 규칙만 둔다(예: "마감일은 시작일 뒤"). ③ **잡는 검사 / 못 잡는 것** - React·HTTP·application을 import하면 `check:architecture`(FE-GATE-010)가 `feature-domain-is-framework-neutral` 규칙으로 막는다. - **못 잡음**: 불변식을 domain 대신 페이지에 쓰는 것. 규칙 위치는 검사하지 않는다. ④ **쓸 스킬**: `clean-architecture`, `codebase-design` --- ## 3단계. API 계약 생성된 파일: - `contracts/-feature-contract.ts`: 선언 쪽. 라우트, 무효화, 계약 패키지 신원(`contractPackages`). - `contracts/-contract-contribution.ts`: HTTP 계약(descriptor). operation을 적는 곳은 여기 하나다. 이것이 실행되고, `check:registries`의 FE-REG-API 행도 여기서 뽑는다. - `contracts/-schema-metadata.ts`: 스키마 메타데이터(FE-REG-SCHEMA 행). 스키마 ID마다 쓰이는 자리(`boundary`)와 소유자를 적는다. - `contracts/-schemas.ts`: zod 스키마와 검증기. - `contracts/-mapper.ts`: 와이어 값 → 화면 값. FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-operations.ts`의 `projectApiOperationRows`). 같은 API를 다른 파일에 다시 적지 않는다. ① **정할 것** - 계약 출처. 실제 패키지 / 자리표시자. [02 결정표 2절](02-decision-tables.md#2-계약-출처) - operation마다: - 재시도 의미(`retrySemantics`). [02 결정표 3절](02-decision-tables.md#3-재시도-의미) - 쓰기의 실패 분류(`commandEffect`). [02 결정표 4절](02-decision-tables.md#4-결과-불명) - 인증 프로필(`authProfileId`). [02 결정표 5절](02-decision-tables.md#5-인증) - 바이트 한도·마감: `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`. - 스키마 ID, operation ID. 모두 기능 접두어를 붙인다([reference/global-ids.md](reference/global-ids.md)). ② **기준** - 밖에서 들어오는 값(응답, 문제 응답, 입력)은 받는 자리에서 검증한다(원칙 4). - 검증기는 `src/contracts/zod-validator.ts`의 `zodValidator(schemaId, schema)` 하나를 쓴다. 기능마다 복사하지 않는다. - 검증을 일부러 생략할 때는 `src/contracts/unvalidated-payload.ts`의 `unvalidatedPayload(schemaId, reason)`를 쓴다. 이유가 빈 문자열이면 throw한다. 생략 목록은 `listUnvalidatedPayloads`가 보여 준다. - zod는 `src/contracts/zod.ts`로만 import한다. - 경로는 짝 백엔드 컨트롤러의 매핑과 같은 `/`이다. 생성된 descriptor는 `API_PATH` 상수 하나를 쓴다. 백엔드에 `--path`를 줬으면 이 상수를 같은 값으로 바꾼다. - 백엔드의 `api-base-path`(기본 `/v1`, 로컬 `/api`)는 descriptor에 적지 않는다. `config/runtime/.json`의 `API_BASE_URL`에 붙이고 끝을 `/`로 둔다(예: `https://api.example.com/v1/`). 끝 `/`가 없으면 실행기가 `URL_ORIGIN_ESCAPED`로 보내지 않는다. - 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 `GET /` 페이지 목록(`PageParams`)을 더하기 전에는 생성된 목록이 405를 받는다. - 계약 패키지(`@org-contracts/*`)는 `contracts/-contract-contribution.ts` 이름의 파일에서만 import한다. - 패키지 신원 네 필드(`packageId`, `version`, `digest`, `sourceRevision`)는 `-feature-contract.ts`의 상수 하나에 있다. 바꿀 때는 넷을 함께 바꾼다. - 근거: `scale-architecture.md` §13(재시도), §20~§22(검증 경계와 예산). **응답 모양: 짝 백엔드의 Envelope** 생성한 기능은 짝 백엔드의 응답을 그대로 읽는다. 짝 백엔드의 정본은 `clean-architecture-backend-template/docs/web/http-contract.md`다(아래 `http-contract.md`). - Envelope: 성공·실패 본문을 한 번 더 감싸는 공통 바깥 객체다(`http-contract.md` §1). - 성공: `{ "success": true, "data": ..., "meta": ... }` - 실패: `{ "success": false, "error": { "code", ... }, "meta": ... }` - 이 모양을 읽게 하는 것은 V3 descriptor(`-contract-contribution.ts`)의 한 줄 `responseEnvelope: "ENVELOPE_V1"`이다. 생성된 operation에는 모두 들어 있다. - operation을 손으로 더할 때마다 이 줄을 적는다. 이 값은 operation마다 따로다. 감싸지 않는 백엔드면 `"NONE"`을 적는다. 줄은 빼지 않는다. - 줄을 빠뜨리면 `check:types`가 그 descriptor의 `satisfies InstalledHttpContract<...>`에서 실패한다(`Property 'responseEnvelope' is missing ...`, 1103/16-01). 기여 안의 operation 모두에서 빼도 같다. - 한 계약 기여 안에서 이 값이 다른 operation이 있으면 계약 조립이 거부한다(`/: responseEnvelope NONE, but in the same contribution reads ENVELOPE_V1; ...`). 기여 하나는 백엔드 하나의 패키지라서다. 그래서 값을 잘못 적으면 앱을 조립하는 테스트와 `check:registries`가 실패한다. - **못 잡음**: 기여 안의 operation 모두에 같은 틀린 값을 적는 것(짝 백엔드인데 모두 `"NONE"`). 그때는 아래 MSW 줄의 손글씨 gateway 테스트만 잡는다. ```text 성공 status → Envelope 확인 → data를 outputValidator로 검증 → mapSuccess 실패 status → Envelope 확인 → error를 problemValidator로 검증 → 판정(effect) → mapProblem ``` - 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다. - problem 스키마(`-schemas.ts`의 `ProblemSchema`)는 Envelope의 `error` 객체다. 분기는 `code`로 한다. `message`는 버린다. - 400·409·422와 백엔드가 정한 5xx 여섯이 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. - 기준 표는 백엔드 커밋 하나에 묶여 있다(`config/contracts/backend-contract-pin.json`). 백엔드 표의 행은 `config/contracts/backend-http-contract-excerpt.json`에 그대로 옮겨 두었고, `test:unit`이 답 표(`config/contracts/backend-idempotency-answers.json`)를 그 사본과 대조한다. - **짝 백엔드를 새로 받을 때마다** `corepack pnpm check:backend-contract-drift --backend <백엔드 checkout>`을 돌린다. 게이트 밖이라 CI는 돌리지 않는다. 1이면 pin 뒤 백엔드 표가 바뀌었거나 사본·답 표가 pin과 다르다. 출력이 그 행을 말한다. 2는 비교하지 못했다는 뜻이고 통과가 아니다(checkout이 없거나 pin 커밋이 없다). - pin을 올릴 때: pin의 `backend.commit`과 답 표의 `source.commit`을 바꾸고 같은 명령에 `--write-excerpt`를 붙여 사본을 다시 옮긴다. 그다음 답 표와 [백엔드 계약 6.1절](../architecture/backend-api-and-server-state-contract.md) 표를 명령이 통과할 때까지 고친다. 옮기지 않는 행은 pin의 `notCopied`에 이유와 함께 적는다. - 업무 규칙 거절(`_INVALID`, `*_ALREADY_EXISTS` 등)은 표에 없어 결과 불명이 된다. 그 엔드포인트가 쓰기 전에만 내는 code면 `commandEffect.refusedBeforeWrite`에 적는다. 적어야 사용자가 값을 고쳐 다시 저장할 수 있다(02 결정표 4절). - `mapProblem`이 없거나 `undefined`를 돌려주면 백엔드 code·필드 오류·status별 kind로 읽는다(`src/adapters/http/backend-envelope.ts`). - 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다. - MSW: `createHttpScenarioHandler`는 descriptor의 `responseEnvelope`를 보고 Envelope로 답한다(`tests/mocks/handlers/http-scenarios.ts`). 그래서 시나리오 테스트는 선언이 틀려도 통과한다. 생성된 `tests/features//-http-gateway.test.ts`는 백엔드 본문을 그대로 적어 검사한다. operation을 더하면 이 파일에도 그 operation의 백엔드 본문 테스트를 더한다. - `http-contract.md`는 status·`code`의 **뜻**(예: 409 `IDEMPOTENT_IN_FLIGHT`)의 정본이다. 기능 코드에서 그 code는 problem의 `code`로 읽는다. **짝 백엔드가 아닌 백엔드** DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 백엔드에 붙일 때: 1. 모든 descriptor의 `responseEnvelope`를 `"NONE" as const`로 바꾼다. 줄을 지우면 `check:types`가 실패한다. 2. problem 스키마를 problem details 모양으로 바꾼다. 3. `classifyProblem`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다. problem 스키마, 작성의 `commandEffect`, `mapProblem`의 예는 [02 결정표 4절](02-decision-tables.md#4-결과-불명)의 「problem details 백엔드의 예」에 있다. 그 기능의 MSW 본문도 DTO와 problem details로 손으로 적는다. **입력과 스키마 메타데이터** `inputValidator` 하나가 operation 입력 전체를 검증한다. 입력이 요청의 어디로 가는지는 `projectRequest`가 정한다. - 경로 파라미터: `pathValues`. 키는 `pathTemplate`의 `{이름}`과 같다. - 검색값: `queryEntries`. 인코딩한 쿼리는 8,192바이트까지다(`HTTP_EXECUTION_CEILINGS.encodedQueryBytes`). - 본문: `body`. `requestBody: "JSON"`일 때만 쓴다. 아니면 `null`이다. 경로 파라미터와 본문을 함께 받는 operation(예: `PUT /items/{id}` + 본문)은 입력 스키마 하나에 둘을 담고 `projectRequest`가 나눈다. 정본: descriptor 칸은 `src/contracts/external-contract-runtime.ts`(`InstalledHttpContract`), 스키마 메타데이터 칸은 `src/contracts/schema-registry.ts`(`SchemaDefinition`). 스키마 `boundary` 값: - `route-params`: 라우트 경로 파라미터(`paramsSchema`). 같은 스키마를 경로 파라미터 GET의 `inputValidator`로도 쓴다. - `route-search`: 라우트 검색값에만 쓴다. - `route-search-api-request`: 라우트 검색값이면서 GET 쿼리다. 목록 검색이 이 경우다. - `api-request`: 요청 입력. - `api-response`: 응답 DTO. - `api-problem`: 실패 본문(`problemValidator`). Envelope operation이면 `error` 객체다. FE-REG-API의 `problemSchema`가 이 행을 가리킨다. 스키마 메타데이터의 `boundary`·`direction`·`unknownFieldPolicy`는 손으로 적지만 `tests/unit/schema-metadata-policy.test.ts`(`test:unit`)가 실제 쓰임과 대조한다. - `boundary`: descriptor의 입력·응답·실패 검증기와 라우트의 `paramsSchema`·`searchSchema`에서 쓰인 자리로 정해진다. 다르면 `: row <적은 값>, used as <맞는 값>`으로 실패한다. 쓰이는데 행이 없으면 `: no FE-REG-SCHEMA row`. - `direction`: 입력은 `REQUEST`, 응답·실패는 `RESPONSE`. - `unknownFieldPolicy`: zod가 모르는 키를 거부하면(`.strict()`) `REJECT_UNKNOWN`, 버리면(`.strip()`) `STRIP_UNKNOWN`. - descriptor의 입력·응답·실패 검증기로 쓰인 스키마의 행은 `direction`·`unknownFieldPolicy`를 빼지 않는다. 빼면 `row states no direction` 또는 `row states no unknownFieldPolicy`로 실패한다(1106/07-02). 칸이 없으면 응답 DTO를 `.strict()`로 바꿔도 행이 바뀌지 않아 `check:registries`가 breaking으로 보지 못한다. 라우트에만 쓰이는 행은 두 칸이 없어도 된다. 모르는 필드를 볼 객체가 없는 검증기(`responseBody: "NONE"` 출력의 `z.undefined()`, 문자열·null 본문)는 `direction`만 본다. - 이 테스트는 설치된 기능을 읽는다. 기능을 더한 상태에서 `test:unit`을 돌릴 때 잡힌다. 예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸과 응답 모양 줄만 적었다. ```ts // GET /notices?q=... inputValidator 스키마 NoticeListQuery (boundary: "route-search-api-request") pathTemplate: "/notices", inputValidator: zodValidator("NoticeListQuery", noticeListQuerySchema), responseEnvelope: "ENVELOPE_V1" as const, projectRequest: (input) => Object.freeze({ pathValues: Object.freeze({}), queryEntries: Object.freeze(input.q === undefined ? [] : [Object.freeze(["q", input.q] as const)]), body: null, }), // GET /notices/{noticeId} inputValidator 스키마 NoticeParams (boundary: "route-params") pathTemplate: "/notices/{noticeId}", inputValidator: zodValidator("NoticeParams", noticeParamsSchema), responseEnvelope: "ENVELOPE_V1" as const, projectRequest: (input) => Object.freeze({ pathValues: Object.freeze({ noticeId: input.noticeId }), queryEntries: Object.freeze([]), body: null, }), ``` ③ **잡는 검사 / 못 잡는 것** - descriptor의 입력·응답·실패 스키마 ID가 스키마 메타데이터에 없으면 `check:registries`가 실패한다. - 메시지: `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` (`responseSchema`, `problemSchema`도 같다) - 스키마 메타데이터의 `boundary`·`direction`·`unknownFieldPolicy`가 실제 쓰임과 다르면 `test:unit`의 `tests/unit/schema-metadata-policy.test.ts`가 실패한다(위 "입력과 스키마 메타데이터"). - 인증 프로필 이름이 틀리면 계약 조립이 거부한다. `check:registries`(원인 `reason`도 적는다)와 그 기능의 실행부를 적재하는 테스트가 실패한다. `check:types`·`check:architecture`·`verify:documentation`은 통과한다. - 오류의 `reason`: `/: unknown authProfileId ` - 스키마 ID나 operation ID가 겹치면 적재 때 그 ID를 말하며 실패한다. - 예: `Invalid or duplicate schema definition: `, 계약 조립 `duplicate operation: ` - `TEMPLATE_FIXTURE` 출처를 제품 기능에 쓰면 계약 조립이 거부한다. - 오류의 `reason`: `: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to only; pin an EXTERNAL_PACKAGE` - zod를 직접 import하면 `check:architecture`가 `zod-is-reached-through-contracts-zod`로 막는다. - 계약 패키지를 다른 파일에서 import하면 `external-contract-package-single-import-path`로 막는다. - 자리표시자 신원은 staging·production 승인(`check:release-admission`, FE-GATE-027)이 거절한다. - **못 잡음**: 쓰기 실패를 서버 계약과 다르게 분류하는 것. 서버가 보장하지 않는 code를 `NOT_APPLIED`로 적어도 검사는 통과한다. 백엔드 계약을 보고 사람이 확인한다. - **못 잡음**: 자리표시자 신원은 로컬·개발 빌드와 merge 게이트를 통과한다. 의도된 동작이다. ④ **쓸 스킬**: `clean-architecture`, `codebase-design`, `api-and-interface-design`, `security-and-hardening` --- ## 4단계. application input 생성된 파일: `application/-feature-api.ts` - input 타입: 페이지가 부르는 메서드 모음. - gateway 타입: HTTP 어댑터가 구현하는 port. - `createFeatureInput(gateway, { telemetry })`: input을 만드는 함수. - `ApplicationFeatureInputs` 보강: `declare module ".../application-api.ts"`로 기능 ID와 input 타입을 잇는다. - 보강(module augmentation): 다른 파일에 있는 타입에 키를 더하는 TypeScript 문법이다. ① **정할 것** - input 메서드 이름. 사용자가 하는 일로 짓는다(`listItems`, `createInvoice`). - 반환 타입. `Result`(`src/contracts/result.ts`)를 쓴다. - 쓰기 메서드의 호출 문맥. 쓰기는 뮤테이션의 `intent`를 받아 gateway까지 넘긴다(`Readonly<{ signal?: AbortSignal; intent: MutationIntent }>`). `KEYED` 쓰기의 멱등 키가 intent에 있다. `--with-create`의 `CommandContext`가 이 모양이다. - 실패 telemetry의 `kind`. `.<동작>.failed` 꼴로 접두어를 붙인다. ② **기준** - application은 React, HTTP, 어댑터를 모른다. gateway port만 안다. - telemetry는 결과를 바꾸지 않는다. `failOpenTelemetryPort`로 감싼다(`src/platform/telemetry/telemetry-port.ts`). - 근거: `scale-architecture.md` §24(텔레메트리 소유), §26(업무 동작에는 fail-open). - 쓰지 않는 것: `src/application/result.ts`(폐기 재수출), `src/application/ports/telemetry-port.ts`(이름만 같은 다른 타입). ③ **잡는 검사 / 못 잡는 것** - application이 React·어댑터·presentation을 import하면 `check:architecture`가 `feature-application-does-not-know-runtime`으로 막는다. - 보강 키와 조립 기여의 `featureId`가 다르면 조립이 실패한다. - 메시지: `feature adapter contribution installed an input for ` - input 모양이 보강 타입과 다르면 `check:types`(FE-GATE-003)가 막는다. 음성 fixture `tests/fixtures/typecheck/invalid-feature-input.ts`도 같은 게이트의 `check:types:fixtures`에서 돈다. - **못 잡음**: telemetry `kind` 중복. 유일성 검사가 없다. 접두어로 피한다. ④ **쓸 스킬**: `clean-architecture`, `codebase-design` --- ## 5단계. HTTP 어댑터와 조립 기여 생성된 파일: - `adapters/-http-gateway.ts`: `defineFeatureHttpOperationForRoutes`로 operation과 route ID를 묶고, gateway를 구현한다. - `adapters/create--feature-input.ts`: `defineFeatureAdapterContribution`으로 조립 기여를 선언한다. - 조립 기여: 부팅 때 플랫폼이 기능에게 capability를 주고 input을 받아 가는 약속이다. ① **정할 것** - `needs`: 기능이 받을 capability. 템플릿이 만드는 것은 `http`, `telemetry`다. - 문제 응답 → 실패 매핑. 필요하면 `mapProblem`을 둔다(예: 409, 422를 업무 실패로). Envelope operation에서 `mapProblem`은 kind·code·필드 오류만 바꾸고 적용 여부는 못 바꾼다. 쓰기 전 거절이면 그 code를 `refusedBeforeWrite`에도 적는다. - operation마다 `routeId`. `defineFeatureHttpOperationForRoutes`로 정의할 때 적는다. ② **기준** - `routeId`는 요청 결과 기록에 붙는 이름표다. - 요청이 끝날 때마다 진단 기록(`http.request.completed`)과 실패 telemetry(`api.request.failed`)에 `route_id`로 실린다(`src/bootstrap/runtime-adapters.ts`의 `createHttpObservationProjector`). - URL, 재시도, 취소, 캐시에는 쓰이지 않는다(`src/adapters/http/feature-http-binding.ts`는 이 값을 실행기에 넘기기만 한다). - `routeId`에는 그 요청을 보내는 화면의 route ID를 적는다. - 읽기: 데이터를 그리는 화면. 목록 GET은 목록 route, 상세 GET은 상세 route. - 쓰기: 저장 버튼이 있는 화면. 작성 폼 route가 따로 있으면 그 route. - 여러 화면에서 부르면 주로 부르는 화면 하나를 고른다. 이름표는 하나뿐이다. - `needs`에는 실제로 쓰는 것만 적는다. - 템플릿이 만들지 않는 capability(예: `indexedDb`)는 `src/bootstrap/product-composition.ts`에서 만든다. 제품이 새로 만드는 capability의 타입은 `src/features/product-capabilities.ts`에 적는다. [03 문서](03-outside-feature-folder.md)를 본다. - 문제 응답 매핑 예제: 짝 백엔드는 `create:feature --with-create`의 `adapters/-http-gateway.ts`(400 `_INVALID` → 이름 칸). problem details 백엔드는 [02 결정표 4절](02-decision-tables.md#4-결과-불명)의 조각 2. ③ **잡는 검사 / 못 잡는 것** - presentation이 기능 `adapters/`를 import하면 `feature-presentation-does-not-know-outbound-adapters`로 막는다. - adapters가 presentation을 import하면 `feature-adapters-do-not-know-presentation`으로 막는다. - 기능 루트 파일(`feature-module.ts` 등)이나 계층이 아닌 폴더(`support/` 등)의 파일이 `src/adapters`에 닿으면 `feature-and-app-roots-do-not-reach-adapters`로 막는다. 기능 안에서 `src/adapters`에 닿을 수 있는 곳은 `adapters/` 폴더뿐이다. - operation ID·route ID·입력 타입을 틀리면 `check:types`가 막는다. 음성 fixture: `tests/fixtures/typecheck/invalid-http-operation-id.ts`, `tests/fixtures/typecheck/invalid-http-route-id.ts`, `tests/fixtures/typecheck/invalid-http-operation-input.ts`(`check:types:fixtures`). - 호스트가 주지 않는 capability를 `needs`에 적으면 조립이 실패한다. - 메시지: `feature needs , which the host did not provide` - operation을 계약에 두고 기능 `adapters/`·`application/`에서 쓰지 않으면 `check:registries`(FE-GATE-010)가 실패한다. - 메시지: `FE-REG-API. has no executable consumer for operationId=` - **못 잡음**: `routeId`가 실제로 요청을 보내는 화면과 다른 것. 타입은 기능의 route ID인지만 본다. - **못 잡음**: 기능 `contracts/`나 다섯 폴더 밖에 새로 만든 폴더(예: `hooks/`)를 거쳐 `src/adapters`에 닿는 import. `.dependency-cruiser.json`에 그 경로를 막는 규칙이 없다. 기능 안에는 `domain/`, `application/`, `contracts/`, `adapters/`, `presentation/` 다섯 폴더만 둔다. ④ **쓸 스킬**: `clean-architecture`, `codebase-design` --- ## 6단계. 라우트 생성된 파일과 자리: - 계약의 `routes`와 `routeRuntimeContracts`. 같은 route ID를 두 곳에 쓴다. - `presentation/-feature-runtime.ts`: 지연 로드 페이지 표. `moduleId`는 계약과 같아야 한다. - `context-routes.ts`: context가 적재하는 라우트 목록. 생성된 판은 계약의 라우트를 그대로 옮긴다. - `presentation/-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다. - 문구 `route..title`, `route..navigation` (ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다. - 계약 `routes`의 `title`·`navigationLabel`은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(`scripts/test-performance.ts`, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면 `check:registries`가 behavior-change로 기록한다. - 기능 폴더 밖: `docs/accessibility/route-reviews/.md`(pending 기록). 생성 명령이 만든다. ① **정할 것** - `access`: `public`(로그인 없이) 또는 `session-required`(로그인 필요). - `loadingSurface`: 로딩 화면 이름. 케밥 표기. - `errorSurface`: `route-boundary`, `feature-boundary`, `not-found` 중 하나. 생성된 판은 `feature-boundary`다. - `chunkId`: 지연 로드 청크 이름. 전역에서 유일해야 한다. - `navigationOrder`: 메뉴 순서. `null`이면 메뉴에 나오지 않는다. - 파라미터·검색값이 있으면 그 스키마와 codec(`paramsCodec`, `searchCodec`). - codec: URL 문자열을 타입 있는 값으로 바꾸고 되돌리는 함수다. ② **기준** - 경로는 계약에만 적는다. 페이지와 링크는 route ID와 `buildRouteUrl`로 URL을 만든다. 경로 문자열을 페이지에 다시 적지 않는다. - 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제: `create:feature --with-create`의 `context-routes.ts`(상세 라우트의 params codec). - 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 기본 생성 판의 목록 라우트는 파라미터가 없어서 넘기지 않는다. `--with-create` 판의 상세 라우트는 codec을 넘긴다. 안 넘기면 `Unregistered route codec: `로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제: `--with-create` 판의 `presentation/-routes.ts`. - 검색값(`?status=open`)을 읽는 목록은 아래 두 조각을 더한다. 생성 뼈대의 목록 라우트에는 검색값이 없다. - 조각 1(`contracts/-list-search.ts`)이 검색값 스키마다. 그 스키마를 `presentation/-route-codecs.ts`의 `_ROUTE_CODECS`에 `ListSearch`라는 codec ID로 싣는다. - 계약의 목록 라우트 `searchSchema`와 `routeRuntimeContracts`의 `searchCodec`을 그 codec ID로 바꾼다. 기본 판처럼 `context-routes.ts` handle에 `codecs`가 없으면 `--with-create` 판처럼 싣는다. - 라우터는 페이지를 그리기 전에 그 codec으로 검색값을 해석한다. 틀린 값이면 페이지 대신 잘못된 경로 화면을 그린다. - 조각 2(`presentation/use--list-filters.ts`)가 페이지에서 그 값을 타입대로 읽는 hook이다. 같은 codec으로 다시 읽으므로 cast가 없다. ```ts import { z } from "../../../contracts/zod.ts"; /** The list route's search values (`?status=open`). Absent means every invoice. */ export const invoiceListSearchSchema = z .object({ status: z.enum(["open", "paid"]).optional() }) .strict(); export type InvoiceListSearch = z.output; ``` ```ts import { useMemo } from "react"; import { useRouteInput } from "../../../presentation/routes/route-input.tsx"; import { invoiceListSearchSchema, type InvoiceListSearch, } from "../contracts/invoice-list-search.ts"; /** * The router parsed the search with this codec before the page rendered. * Reading it back through the same codec gives its type without a cast. */ export function useInvoiceListFilters(): InvoiceListSearch { const { search } = useRouteInput(); return useMemo(() => invoiceListSearchSchema.parse(search), [search]); } ``` - 상세 경로는 목록 경로 뒤에 `/items/:`을 붙인다. 예: `/notice/items/:noticeId`. `/notice/:noticeId`로 두지 않는다. - 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼 `/notice/new`가 있으면 id가 `new`인 공지는 `/notice/:noticeId`로 열 수 없다. - `items/`를 끼우면 정적 경로와 겹치지 않는다. 생성 판(`--with-create`)의 상세 라우트도 이렇게 한다(`<목록 경로>/items/:Id`). - `tests/e2e/accessibility.spec.ts`는 기능마다 고치지 않는다(1103/16-03). - 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 이름과 상관없이 모두 `a11y-1`로 바꾼다. 파라미터 스키마가 이 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사하므로, id 스키마는 짧은 영문·숫자 문자열을 받게 둔다. - API 요청은 설치된 descriptor에서 method와 `pathTemplate`으로 찾아 답한다. 목록 조회에는 빈 목록을 그 operation의 모양(`responseEnvelope: "ENVELOPE_V1"`이면 Envelope)으로 답한다. 그 뒤 경고 상자(`role="alert"`)가 없는지 본다. 그래서 목록 페이지는 빈 상태로 검사된다. - 한 자원을 읽는 조회(경로 파라미터가 있고 빈 목록을 받지 않는 GET)에는 빈 목록 말고 답할 것이 없다. 그래서 상세 페이지는 실패 상태로 그려지고, 테스트 결과에 `a11y-data-state` annotation이 남는다. - `a11y.json`은 그 라우트를 통과(`scope`)가 아니라 `notChecked`에 적는다. report(`scripts/write-a11y-report.ts`)는 라우트의 `paramsSchema`가 그런 GET의 입력 스키마이면 descriptor만 보고 그 라우트를 `notChecked`로 기대한다. spec이 기록을 남기지 않으면 `a11y.json not written:`으로 실패한다(1106/11-01). 생성 명령의 상세 라우트는 GET과 같은 `Params`를 쓰므로 이 규칙에 든다. - 그 GET을 부르지 않는 페이지의 라우트(예: 상세 아래의 하위 항목 작성 폼 `/things/:thingId/parts/new`)는 상세 GET의 입력 스키마를 `paramsSchema`로 쓰지 않는다. 같은 스키마를 쓰면 report가 기록을 기대하는데 spec은 한 자원 응답을 보지 못해 기록을 남기지 않으므로 실패한다. 그 라우트에 자기 `paramsSchema`(예: `ThingPartCreateParams`)를 따로 둔다. - 설치된 GET이 아닌 요청을 그리기 전에 보내면 spec이 실패한다(`requests no installed list or single-resource read answers`). - spec은 h1이 보일 때까지 기다린다. 그래서 상세 페이지는 데이터가 없을 때도 h1을 그린다. 예: `heading={{ title: notice?.title ?? message("notice.detail.titlePending") }}`처럼 데이터가 없으면 고정 제목("공지")을 쓴다. - 기능이 앱 홈(`/`)을 대신하려면 route ID `APP_HOME`을 쓴다. `docs/architecture/starter-experience.md`의 "Product home and layouts" 절을 본다. ③ **잡는 검사 / 못 잡는 것** - route ID가 겹치면 조립이 실패한다. 메시지: `Duplicate route registry key: ` - 경로·`chunkId`가 겹치면 `check:registries`가 실패한다. 메시지: `FE-REG-ROUTE. duplicates path= from ` - `loadingSurface`가 케밥 표기가 아니면 `check:registries`가 `does not match`로 실패한다. - `context-routes.ts`의 handle이 계약에 없는 route ID를 가리키면 context 적재가 거부한다. - 메시지: `Route handle loaded by context is not a contract route of its features (...)` - 라우트별 a11y 기록이 없으면 세 곳이 잡는다. - `verify:documentation`(FE-GATE-017): `docs/accessibility/route-reviews/ has no record for route IDs: ` - `review:a11y-manual -- --format-only`(FE-GATE-009): `missing record` - `test:unit`의 `tests/unit/manual-a11y-evidence.test.ts` - en-US 문구 키가 ko-KR과 다르면 `check:i18n`(FE-GATE-010)이 `en-US catalog keys do not match ko-KR`로 실패한다. - **못 잡음**: `navigationOrder` 중복. 같은 숫자가 둘이어도 통과한다. 생성 명령은 설치된 최댓값 + 10을 쓴다. - **못 잡음**: 페이지가 경로를 문자열로 적어 계약과 어긋나는 것. 라우터를 거치는 페이지 테스트가 있을 때만 잡힌다(10단계). ④ **쓸 스킬**: 정해 둔 스킬 없음. 이 절과 02 결정표로 판단한다. --- ## 7단계. 쿼리·뮤테이션 바인딩 생성된 파일: `presentation/use--items.ts` (`bindQuery` + `useApplicationQuery`) ① **정할 것** - 쿼리 namespace: `defineQueryNamespaceIdentity(name, version)`. 캐시 키의 앞부분이다. - 무효화 topic: `qinv.` 뒤에 무작위 26자. 쓰기가 끝나면 어떤 쿼리를 다시 받을지 잇는 이름이다. - profile: `LIST_STANDARD`, `DETAIL_STANDARD`, `LOOKUP_STABLE`, `VOLATILE_STATUS` 중 하나. 캐시 시간 정책이다. 정의는 `src/contracts/server-state.ts`. - `measureResult`: 결과 크기 추정 함수. 캐시 예산에 쓴다. - `definitionId`: 쿼리·뮤테이션 정의 이름. - 쓰기가 있으면 뮤테이션 정책: `duplicatePolicy`, `invalidate`. operation ID와 멱등 키 여부는 정하지 않는다. descriptor에서 받는다(아래). ② **기준** - topic은 복사하지 않는다. 새 topic이 더 필요하면 값을 새로 만든다. - 형식: `qinv.` + 소문자·숫자 26자. `scripts/create-feature.ts`의 `randomTopicSuffix`가 쓰는 방식이다. - `measureResult`에서 `JSON.stringify`를 쓰지 않는다. 문자열 바이트와 항목당 고정 크기로 어림한다(생성된 `measureItems` 참고). - 뮤테이션 정책의 operation ID와 `requiresIdempotencyKey`는 `commandMutationIdentity(_CONTRACT)`(`src/contracts/server-state.ts`)로 descriptor에서 받는다. 손으로 적지 않는다. - 실행기는 intent의 operation ID가 descriptor와 다르면 보내기 전에 거부한다. 문자열 ID는 그보다 먼저 `check:types`가 막는다(③). 그래서 저장 때 거부되는 것은 `commandMutationIdentity`에 손으로 만든 객체를 넘긴 오타뿐이다. 그때는 저장이 항상 실패하고, 화면은 "요청을 처리할 수 없습니다"다. - `requiresIdempotencyKey`는 `retrySemantics`가 `KEYED`일 때만 참이다. - V3 HTTP descriptor가 없는 쓰기(Fileserver 업로드처럼 `execute`가 HTTP 실행기를 거치지 않는 것)는 descriptor 모양 객체를 넘긴다: `...commandMutationIdentity({ contract: { operationId: "", method: "POST", retrySemantics: "KEYED" } })`. intent가 멱등 키를 실어야 하면(Fileserver 업로드에 `idempotencyKey`를 넘길 때) `retrySemantics`는 `"KEYED"`, 아니면 `"NEVER"`다. 이 ID를 대조할 descriptor가 없으므로 ID는 intent의 이름일 뿐이고, 오타는 어느 검사도 잡지 않는다(③). - 테스트에서 descriptor 없이 정책을 만들 때는 `tests/helpers/mutation-operation-id.ts`의 `testMutationOperationId("")`를 쓴다. 이 helper는 operation ID만 돌려주므로 `requiresIdempotencyKey`는 따로 적는다. 문자열을 그대로 적으면 `check:types:test`가 실패한다. - 쓰기 정책은 `duplicatePolicy: "REJECT_WHILE_ACTIVE"`, `invalidate: [topic]`을 쓴다. ```ts const INVOICE_CREATE_MUTATION_POLICY = Object.freeze({ definitionId: "invoice-create-v1", definitionVersion: 1, ...commandMutationIdentity(INVOICE_CREATE_CONTRACT), duplicatePolicy: "REJECT_WHILE_ACTIVE" as const, invalidate: Object.freeze([INVOICE_ITEM_INVALIDATION_TOPIC]), }); ``` - 예제: `create:feature --with-create`의 `presentation/use--create.ts`. ③ **잡는 검사 / 못 잡는 것** - topic·namespace가 겹치면 조립 때 실패한다. 메시지: `Duplicate invalidation topic: `, `Duplicate invalidation namespace: ` - topic 형식이 틀리면 `Query invalidation topic is invalid.`로 실패한다. - 등록되지 않은 profile은 실행 때 `Unregistered server-state profile: `로 실패한다. - topic·namespace·edge를 더하기만 하면 레지스트리 기준선은 바뀌지 않는다(additive). 9단계에서 할 일이 없다. - 뮤테이션 정책의 operation ID를 `commandMutationIdentity`로 받으면 descriptor 상수 이름의 오타는 `check:types`가 막는다. 쓰기 descriptor 대신 GET descriptor를 넘기면 바인딩 때 `commandMutationIdentity: is a GET; a mutation binds a write operation`으로 throw한다. - 뮤테이션 정책에 operation ID를 문자열로 직접 적으면 `check:types`가 실패한다. `BoundMutation.operationId`는 `MutationOperationId`이고, 이 값은 `commandMutationIdentity`만 만든다. 오류는 그 문자열을 `MutationOperationId`에 넣을 수 없다고 말한다. - **못 잡음**: `commandMutationIdentity`에 descriptor 상수 대신 손으로 만든 객체(`{ contract: { operationId: "…", … } }`)를 넘기는 것. descriptor가 있는 쓰기면 그 오타는 저장할 때 실행기가 보내기 전에 거부한다(`MISSING_IDEMPOTENCY_KEY` 위반). descriptor가 없는 쓰기(②의 Fileserver 업로드 등)는 대조할 곳이 없어 오타가 그대로 intent 이름이 된다. - `bindQuery`의 `owner`·`operationId`, 뮤테이션 정책의 `owner`는 적지 않는다. 읽는 곳이 없어 `@deprecated` 선택 칸이 됐고, 다음 릴리스에서 지운다. 요청 기록의 operation ID는 descriptor의 것이다. - **못 잡음**: `definitionId` 중복. 유일성 검사가 없다. ④ **쓸 스킬**: 정해 둔 스킬 없음. 이 절과 02 결정표로 판단한다. --- ## 8단계. 페이지 생성된 파일: `presentation/-list-page.tsx` (`CollectionPage` + `AsyncSurface`) ① **정할 것** - 페이지 템플릿. [02 결정표 6절](02-decision-tables.md#6-페이지-템플릿) - 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 다시 보내도 되는 요청(`KEYED`, `IDEMPOTENT`. 뮤테이션 정책의 `resendSafe`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. 폼 밖에서 `mutation.submit`을 부르는 화면도 `NEVER` 쓰기의 같은 입력을 다시 보낼 수 없다. 훅이 `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)로 거절한다. `AsyncSurface`에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의 `state`를 넘긴다). - 폼이면 서버 필드 오류를 받을 필드(`useAppForm`의 `allowedServerFields`). 짝 백엔드는 필드 검증 거절을 400 `VALIDATION_FAILED`와 `details[{field, code}]`로 보낸다(422가 아니다). 공유 MSW 시나리오에는 짝 백엔드가 보내지 않는 `validation-422`만 있고, Envelope operation에서 그 답은 결과 불명이다. 짝 백엔드 모양의 필드 오류 테스트는 생성된 작성 폼 테스트(`-create-page.test.tsx`)처럼 400 본문을 손으로 적는다. ② **기준** - 화면 문구는 모두 catalog에서 가져온다(`message(key)`). - 링크는 6단계의 URL 함수로 만든다. - 결과 불명 화면 예제: `create:feature --with-create`의 `presentation/-create-page.tsx`. problem details 백엔드도 화면은 같다. 다른 것은 `commandEffect`와 `mapProblem`뿐이다([02 결정표 4절](02-decision-tables.md#4-결과-불명)). - 다시 시도가 아닌 실패 행동(다시 로그인, 안전한 화면으로 이동)의 버튼은 페이지가 handler를 넘길 때만 그려진다. 생성된 목록 페이지는 `onRetry`만 넘긴다. - 실패의 `action`(`src/contracts/errors.ts`의 `ERROR_REGISTRY`)이 `reauth`(401)·`navigate`(403·404)일 때 쓸 hook이다. `AsyncSurface`에 `onAction={useInvoiceFailureAction(query.state.failure)}`로 넘긴다. - `retry`는 쿼리(`onRetry`)가, `reload-once`는 청크 복구 경계가 맡는다. 이 hook은 `undefined`를 돌려준다. ```ts import { useCallback } from "react"; import { useLocation, useNavigate } from "react-router-dom"; import type { AppFailure } from "../../../contracts/errors.ts"; import { useSession } from "../../../presentation/providers/session-provider.tsx"; /** Sign in again and come back here, or leave for the home screen. */ export function useInvoiceFailureAction( failure: AppFailure | undefined, ): (() => void) | undefined { const location = useLocation(); const navigate = useNavigate(); const { beginSignIn } = useSession(); const action = failure?.action; const handleAction = useCallback(() => { if (action === "reauth") { const returnTo = `${location.pathname}${location.search}${location.hash}`; void beginSignIn(returnTo).catch(() => { void navigate("/"); }); return; } if (action === "navigate") void navigate("/"); }, [action, beginSignIn, location.hash, location.pathname, location.search, navigate]); return action === "reauth" || action === "navigate" ? handleAction : undefined; } ``` ③ **잡는 검사 / 못 잡는 것** - TanStack·HTTP 어댑터를 직접 import하면 `check:architecture`가 `feature-presentation-does-not-know-outbound-adapters`, `presentation-does-not-fetch-directly`로 막는다. - 디자인 시스템 하위 경로를 import하면 `design-system-is-reached-through-its-index`로 막는다. - 화면에 문자를 직접 쓰면 `lint`(FE-GATE-002)가 막는다. - 메시지: `Screen words come from the message catalog: use message(key) (0929/08-02).` - **못 잡음**: `KEYED` 쓰기에서 결과 불명 화면을 빠뜨린 것. 기능 테스트로만 잡힌다. ④ **쓸 스킬**: `frontend-ui-engineering` --- ## 9단계. 기준선과 증거 ① **정할 것** - 레지스트리 기준선을 바꿀 변경인가. - 레지스트리 기준선: 승인된 레지스트리 스냅샷(`config/contracts/registry-baseline.json`)이다. - 런타임에 기능을 끌 스위치가 필요한가(`FEATURE_OVERRIDES`). ② **기준** - 라우트, operation, 스키마, 무효화 topic·namespace·edge를 **더하기만** 하면 기준선은 바뀌지 않는다. - 행을 **빼거나** breaking 칸을 **바꾸면** breaking 변경이다. breaking 칸은 `config/contracts/registry-governance.json`의 `breakingFields`다. 배열 칸에서 값을 빼는 것도 breaking이다. - FE-REG-API 예: 생성 API의 `acceptedStatuses`를 `[200, 201]`에서 `[201]`로 줄이거나, `problemSchema`를 바꾸거나, 검증기를 `unvalidatedPayload`로 바꾸면(`unvalidated` 칸) breaking이다. - status를 더하는 것, 바이트 상한·마감·`retryBudget`·`traffic`·`commandEffect`·`commandRecovery`를 바꾸는 것은 behavior-change다. 통과하지만 스냅샷 diff(`artifacts/quality/registries.json`의 `compatibility.changes`)에 남는다. PR에서 본다. - FE-REG-SCHEMA 예: 응답 DTO를 `.strict()`로 바꾸고 스키마 메타 행을 `REJECT_UNKNOWN`으로 고치면(`direction: "RESPONSE"`) `response-reader-narrowed` breaking이다. 백엔드가 응답에 필드를 하나 더하면 그 API가 `SCHEMA_MISMATCH`로 실패하기 때문이다. 반대(`REJECT_UNKNOWN`→`STRIP_UNKNOWN`)와 요청 행은 behavior-change다. - breaking 변경이면 둘 중 하나를 한다. - `REGISTRY_BASELINE_OWNER`, `REGISTRY_BASELINE_REASON`을 주고 `corepack pnpm update:registry-baseline`을 돌린다. - 또는 `config/contracts/registry-change-evidence.json`에 항목을 더한다. 칸 설명은 `docs/operations/ci-quality-gates.md`에 있다. - a11y 기록은 생성 명령이 pending으로 만든다. 서명은 릴리스 전에 사람이 한다([03 문서](03-outside-feature-folder.md)). - 자리표시자 계약 신원은 staging 배포 전에 바꾼다([03 문서](03-outside-feature-folder.md)). - 선택: `config/runtime/.json`의 `FEATURE_OVERRIDES`에 기능 ID를 적으면 그 환경에서 기능을 끈다. ③ **잡는 검사 / 못 잡는 것** - breaking 변경에 승인이 없으면 `check:registries`가 실패한다. - 메시지: `breaking change missing evidence: ` - 지금 diff와 맞지 않는 증거 행이 남으면 `stale breaking evidence : ...`로 실패한다. - **못 잡음**: 사람이 서명하지 않은 a11y 기록은 merge 게이트를 통과한다. 릴리스 게이트 FE-GATE-028이 막는다. - **못 잡음**: descriptor의 함수는 행에 없다. `classifyProblem`·`classifyStatus`가 무엇을 `NOT_APPLIED`로 보는지, `projectRequest`가 무엇을 보내는지는 PR에서 본다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` --- ## 10단계. 테스트 생성된 파일: - `tests/features//-feature-input.test.ts`: application input 단위 테스트. - `tests/features//-list-page.test.tsx`: 라우터를 거치는 페이지 테스트. - 앱 전체를 조립하고(`createRuntimeComposition`, `RuntimeApplication`), 로그인한 뒤 URL로 들어간다. - API 응답은 MSW로 준다. `tests/mocks/handlers/http-scenarios.ts`의 `createHttpScenarioHandler(_CONTRACT, { scenario, payload })`를 쓴다. - 시나리오 이름의 정본은 `tests/mocks/scenarios/catalog.ts`의 `HttpScenarioId`다. ① **정할 것**: 어떤 상태를 테스트하나(성공, 빈 목록, 실패와 다시 시도, 결과 불명). ② **기준** - 라우터를 거치는 페이지 테스트를 최소 하나 둔다. 0·6·8단계의 "못 잡음" 대부분을 이 테스트가 잡는다. - 기능 테스트는 `tests/features//`에만 둔다. `tests/mocks/`의 공유 파일은 쓰기만 하고 고치지 않는다. - 보낸 요청(헤더·본문)은 MSW의 `request:start` 이벤트로 모아서 확인한다. - `createHttpScenarioHandler`는 응답만 정한다. 받은 요청을 돌려주지 않는다. - 생성된 페이지 테스트의 `setupServer` 설정을 아래처럼 바꾼다. ```tsx const api = setupServer(); const sent: Request[] = []; beforeAll(() => { api.listen({ onUnhandledRequest: "error" }); api.events.on("request:start", ({ request }) => void sent.push(request.clone())); }); afterEach(() => { api.resetHandlers(); sent.length = 0; }); ``` - `request.clone()`: 요청 본문은 한 번만 읽힌다. 복사본을 모아 두어야 테스트에서 `json()`을 부를 수 있다. - 같은 멱등 키 재전송 확인 순서: ```text api.use(... { scenario: "in-flight-409" }) → 저장 → 결과 불명 화면 → api.use(... 성공 응답) → "같은 요청으로 다시 보내기" 클릭 → POST 두 개의 Idempotency-Key가 같은지 본다 ``` ```tsx const posts = sent.filter((request) => request.method === "POST"); expect(posts).toHaveLength(2); expect(posts[1]!.headers.get("idempotency-key")).toBe(posts[0]!.headers.get("idempotency-key")); expect(await posts[0]!.json()).toEqual({ title: "새 공지", body: "본문입니다." }); ``` - 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제: `create:feature --with-create --keyed`의 `tests/features//-create-page.test.tsx`(POST를 받을 때마다 사본을 모으고 같은 키 재전송을 본다). - 서버 권한 거절(403)은 라우터를 거치는 페이지 테스트로 본다. 생성된 페이지 테스트와 같은 도우미(`-test-app.tsx`)를 쓴다. - 403은 본문 없이 답한다. 실행기는 401·403의 본문을 읽지 않고 닫는다. 페이지 테스트 환경(jsdom + MSW)에서 본문이 있는 403(공유 시나리오 `forbidden-403`)은 그 닫기가 끝나지 않아 화면이 로딩에 머물렀다(2026-11-08 확인). ```tsx // @vitest-environment jsdom import { screen, within } from "@testing-library/react"; import { http, HttpResponse } from "msw"; import { setupServer } from "msw/node"; import { afterAll, afterEach, beforeAll, expect, it } from "vitest"; import { invoiceRouteUrl } from "../../../src/features/invoice-feature/presentation/invoice-routes.ts"; import { KO_MESSAGES } from "../../../src/presentation/i18n/catalog.ts"; import { API, openSignedIn } from "./invoice-test-app.tsx"; const api = setupServer(); beforeAll(() => api.listen({ onUnhandledRequest: "error" })); afterEach(() => api.resetHandlers()); afterAll(() => api.close()); it("shows the forbidden state when the backend refuses the list", async () => { api.use(http.get(`${API}/invoices`, () => new HttpResponse(null, { status: 403 }))); await openSignedIn(invoiceRouteUrl("INVOICE_LIST")); const alert = await screen.findByRole("alert"); expect( within(alert).getByRole("heading", { name: KO_MESSAGES["access.forbidden.title"] }), ).toBeVisible(); }); ``` - 빠르게 돌리기: `node scripts/run-vitest.ts run tests/features/` - CI에서는 `test:coverage`(FE-GATE-005)가 `tests/features`를 돈다. `test:unit`은 `tests/unit`만 돈다. ③ **잡는 검사 / 못 잡는 것** - 테스트 실패는 `test:coverage`가 잡는다. 커버리지 하한도 같은 명령이 본다(`config/testing/risk-coverage.json`). - **못 잡음**: 기능 전용 브라우저 테스트(e2e)를 둘 자리가 기능 폴더 안에 없다. Playwright는 `tests/e2e`만 읽는다. 그 폴더에 둔 spec은 기능을 지울 때 함께 지워야 한다(11단계). ④ **쓸 스킬**: `test-driven-development`, `playwright-best-practices` --- ## 11단계. 제거 확인 ```bash corepack pnpm test:sample-removal -- --feature=invoice-feature ``` 이 명령이 하는 일: ```text 저장소 복사본 만들기 → 기능 폴더, 기능 테스트 폴더, (마지막 기능이면) context, FEATURE_OVERRIDES 키, 기능 폴더를 가리키는 커버리지 정책 행, owner가 기능 ID인 증거 정책 행을 지움 → 레지스트리 기준선을 다시 찍음 (빼는 변경은 breaking이라서) → 타입·아키텍처·레지스트리·테스트·커버리지·CI 계약·빌드 게이트 → 지운 기능을 가리키는 파일이 남았는지 찾음 (src: 기능 ID·폴더 이름을 담은 파일, tests: 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일) ``` ① **정할 것**: 없음. 확인 단계다. ② **기준** - 기능 전용 파일은 기능 폴더와 `tests/features//` 안에 둔다(원칙 6). - 폴더 밖에 둘 수밖에 없는 파일은 [03 문서](03-outside-feature-folder.md)의 "기능을 지울 때" 목록에 있다. 실제로 지울 때 그 목록을 함께 지운다. ③ **잡는 검사 / 못 잡는 것** - 남은 파일이 지운 기능을 가리키면 실패한다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일, 그리고 본문에 `-`가 든 기능 ID나 폴더 이름을 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다. - 메시지: ` removal failed:` 다음 줄 `fixture-id-residue: residue: ` - 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다. - spec 본문은 이름 단위로 찾는다(1106/16-01). 적힌 그대로(대소문자 구분) 찾고, 앞뒤에 `[A-Za-z0-9_-]`가 붙으면 다른 이름이다. `test.describe("invoice-feature", …)`는 잔여이고, `product-feature`를 지울 때 `generate-product-feature-index.ts`처럼 더 긴 이름 안에 든 것은 잔여가 아니다. spec은 `test:all`(vitest)도 드릴의 다른 단계도 돌리지 않으므로 이 검사가 아니면 다음 CI의 브라우저 게이트에서야 실패한다. - `-`가 없는 한 단어 ID·폴더 이름(`messages`, `status`)은 spec 본문에서 찾지 않는다. 템플릿 spec이 그 단어를 평범하게 쓰므로(`status: 200`, `getByRole("status")`) 찾으면 템플릿 spec이 잔여로 나온다. - **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, 한 단어 ID만 본문에 적은 spec, `docs/accessibility/route-reviews/.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` --- ## merge 전에 돌릴 것 생성 명령 출력의 `Next:` 2번이 돌릴 명령 목록이다. 정본은 `config/ci/gates.json`의 `merge` 단계다. 한 가지는 따로 본다. - `check:bundle`(FE-GATE-012): 기능 하나가 초기 JS를 늘린다. - `feature-module.ts`가 정적으로 끌어오는 선언·스키마·문구가 초기 청크에 들어가기 때문이다. - 지연 페이지가 셸과 같은 구성요소(`Button`, `SearchField` 등)를 쓰면 그 구성요소가 공유 청크로 떨어져 초기 파일 수도 하나 늘 수 있다. 파일 수 상한(`initialJsFiles`)은 여유가 있다. - 예산은 `config/performance/budgets.json`에 있다. 넘었을 때 고르는 법은 `docs/operations/performance-evidence.md`에 있다. 넘으면 예산을 올리기 전에 팀이 정한다. - 생성 명령의 드릴(`test:feature-scaffold`)도 merge 단계 명령으로 이 검사를 돈다. - 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 기능과 함께 바뀐다. `test:unit`이 빌드와 대조한다. 생성 명령 출력 `Next:` 3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(`test:sample-removal -- --feature=`)은 지운 뒤 기록을 다시 쓰고 검사한다. - 로컬에서 FE-GATE-013을 돌리려면 `VITE_COMMIT_SHA=$(git rev-parse HEAD)`를 준다. 없으면 release candidate가 `source.revision`을 거절한다. 실패한 게이트의 로그는 `artifacts/quality/gates/FE-GATE-.txt`에 있다. - workflow와 같은 조건으로 돌리려면 README 로컬 merge 게이트 반복문 아래의 env 블록대로 `CI=true`와 CI 빌드 식별값(`VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest)을 주고 깨끗한 clone에서 돌린다. 이 값 없이 통과해도 CI에서 떨어질 수 있다(1103/11-07, 11-08). - 게이트는 한 checkout에서 하나씩 돌린다. 게이트와 증거 검사는 `dist`와 `artifacts/`의 고정 경로를 읽는다. - 브라우저 테스트(`playwright test`)를 한 checkout에서 둘 이상 동시에 돌릴 때는 실행마다 다른 `TEST_RUN_ID`를 준다. 예: `TEST_RUN_ID=a corepack pnpm exec playwright test`. 그 실행의 빌드·결과·report는 `.tmp/runs//` 아래에 생긴다. - 서버 포트는 run ID가 없어도 빈 포트를 고른다. 같은 기계의 두 worktree도 부딪히지 않는다. 고정하려면 `TEST_E2E_PORT` 같은 포트 변수를 준다. - `ci:gate`에는 `TEST_RUN_ID`를 주지 않는다. 주면 증거가 기본 경로에 생기지 않아 게이트가 `command-generated evidence was not freshly produced`로 실패한다. - 변수 표와 한계는 [테스트 전략 13.6절](../testing/frontend-platform-testing-strategy.md)에 있다(1105/12-04).