문제: docs/manual(7c7ef32)만 보고 notice-feature(목록·상세·작성, GET 2 +
KEYED POST 1)를 만든 실험(b58d131, 합치지 않음)에서 매뉴얼이 답하지 않아
코드를 읽어야 했던 곳이 나왔다.
| 막힘 | 절 | 매뉴얼에 없던 것 |
|---|---|---|
| 1 | 01-3단계 | 백엔드 Envelope와 뼈대 problem details 중 무엇을 따르나 |
| 2 | 01-3단계 | V2 입력 칸(requestSource, pathSchema, pathParameterNames, maxEncodedSearchBytes, boundary) |
| 3 | 01-5단계 | routeId가 무엇에 쓰이고 쓰기에는 어느 route를 적나 |
| 4 | 01-6단계 | 상세 경로를 items/ 아래 두는 이유, a11y spec 치환 고치는 법 |
| 5 | 01-10단계 | 같은 멱등 키 재전송과 요청 본문을 테스트에서 보는 법 |
| 덧 | 02-4절, 01-2단계, patterns | 503 IDEMPOTENCY_UNAVAILABLE 판정, 길이 제한 위치, 검색 폼 예 |
고친 절과 근거(코드 위치):
- 01-3단계 "응답 모양": 뼈대·MSW·V3 실행기는 DTO와 problem details를 쓴다.
V3는 본문을 벗기지 않고 검증한다(src/adapters/http/http-execution-v3.ts:1410,
1633-1647; src/adapters/http/index.ts:41-48; backend-api-and-server-state-
contract.md:161-173). MSW는 {data} 감싼 응답을 실패 시나리오로 둔다
(tests/mocks/handlers/http-scenarios.ts:80-81, 143-150). 뼈대 problem 스키마는
최상위 code다(scripts/create-feature.ts:542-550). 짝 백엔드는 모든 JSON을
Envelope로 보낸다(backend docs/web/http-contract.md:16-33).
- 01-3단계 "V2 행의 입력 칸": 칸 표와 공지 예 두 행. 근거
src/contracts/api-operations.ts:9,25-27,112-125,142-190,
src/contracts/schema-registry.ts:6-11, config/contracts/registry-governance.json:220
(boundary는 허용값만 검사), tests/unit/http-operation-v2-v3-parity.test.ts:39-49,91,
src/adapters/http/request-builder.ts:129-135(V2만 읽음),
src/contracts/external-contract-runtime.ts:33,
src/adapters/http/http-contract-bridge.ts:225-231(V3 고정 상한 8,192).
- 01-5단계 routeId: 실행기에 넘겨 관측 기록의 route_id로만 쓴다
(src/adapters/http/feature-http-binding.ts:272-273,
src/adapters/http/http-execution-v3.ts:248-254,653-655,
src/bootstrap/runtime-adapters.ts:249-293). 기준은 "요청을 보내는 화면".
참조 기능 생성은 LIST를 적었다(reference-http-gateway.ts:32-34).
- 01-6단계: items/ 이유(reference-feature-contract.ts:36-37, React Router
정적 우선), a11y spec 치환 줄(tests/e2e/accessibility.spec.ts:26-29,36-43),
파라미터 해석 실패 시 잘못된 경로 화면(src/presentation/routes/app-router.tsx:371).
드릴 잔여물 검사는 기능 ID·폴더 이름만 찾는다(scripts/test-sample-removal.ts:
114-117,383-392). URL 함수가 codec을 넘겨야 한다는 줄도 더했다
(src/presentation/routes/route-codecs.ts:36,69-87; 생성 판
scripts/create-feature.ts:934-938은 넘기지 않음).
- 03 "기능을 지울 때"·C절, 01-11단계: a11y spec 치환 줄을 손으로 지운다.
- 01-10단계, patterns "테스트": msw request:start로 요청을 모으는 예
(실험 tests/features/notice-feature/notice-pages.test.tsx, msw 2.15
node_modules/msw/lib/core/experimental/frames/http-frame.d.ts:58,
생성 판 setupServer scripts/create-feature.ts:1147-1149).
- 02-4절 503: V3는 problem 스키마 실패면 쓰기를 MAYBE_APPLIED로 두고
(http-execution-v3.ts:1633-1647), 통과하면 기능 classifyProblem이 정한다
(src/adapters/http/http-effect-certainty.ts:99-131; 참조 기능
reference-feature-contract-contribution.ts:49-70은 503을 MAYBE_APPLIED).
V2 IDEMPOTENCY_REFUSALS에 503이 없어 effect가 비고
(src/adapters/http/client.ts:1035-1038,1109-1135) 조정자가 MAYBE_APPLIED로
본다(src/presentation/adapters/query/application-query.ts:824-834). 재전송은
같은 키, 새 저장은 새 키(같은 파일 583-589, 636-669). 판정: 백엔드 행동
(http-contract.md:94 "같은 키로 나중에 다시")과 맞는다. 화면 문구만 다르다.
- 01-2단계: 길이 제한은 경계 검증. 참조 기능도 스키마·폼에만 둔다
(reference-schemas.ts:66, reference-resource-form.ts:9).
- patterns "URL 검색값을 바꾸는 폼": 짧은 예(SearchField, CollectionPage
toolbar, buildRouteUrl search).
- errors.md: V2 입력 칸 실패 메시지 3개와 Unregistered route codec.
남긴 것:
- 응답 모양 제한: 지금 생성한 기능은 짝 백엔드의 Envelope 응답을 읽지
못한다. 매뉴얼에는 제한과 선택지 둘(백엔드가 DTO를 보냄 / 프론트 V3가
Envelope를 벗김)만 적었다. 결정은 없다. CHANGELOG·리뷰 기록은 이 커밋
범위 밖이다.
- 경로 파라미터와 본문을 함께 받는 operation(PUT 등)의 V2/V3 일치 규칙이
없다는 사실만 적었다.
- 예시 코드는 실험 브랜치의 notice 기능에서 옮겼다. 이 저장소에서 다시
돌려 보지 않았다(실험 커밋 기록상 기능 테스트 21개 통과).
검증:
- node scripts/generate-product-feature-index.ts &&
node scripts/verify-documentation-readiness.ts: PASS_SCOPED,
documentReferences의 docs/manual 8개 파일 missing 0
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts: 2 파일 16개 통과
- 새로 적은 실패 메시지·식별자: src·scripts·tests에서 모두 찾음.
request:start는 msw 타입에서 확인
630 lines
39 KiB
Markdown
630 lines
39 KiB
Markdown
# 01. 새 기능 추가하기 — 0~11단계
|
|
|
|
핵심은 둘이다.
|
|
|
|
- 뼈대는 손으로 만들지 않는다. `corepack pnpm create:feature <id>`로 만든다.
|
|
- 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다.
|
|
|
|
참조 기능(`src/features/reference-feature/`)을 복사해 이름을 바꾸는 방법은 쓰지 않는다.
|
|
그 방법은 접두어 없는 전역 ID, 참조 전용 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다.
|
|
생성 명령은 이 문제를 미리 피한 파일을 쓴다.
|
|
|
|
## 전체 흐름
|
|
|
|
```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`)
|
|
- 쿼리 1개와 무효화 topic 1개
|
|
- `CollectionPage` 페이지 1개와 ko-KR·en-US 문구
|
|
- 테스트 2개 (application input 단위 테스트, 라우터를 거치는 페이지 테스트)
|
|
|
|
그래서 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/<profile>.json`의 `FEATURE_OVERRIDES` 키
|
|
- ID가 `-feature`로 끝나면 생성 명령은 그 앞부분을 접두어로 쓴다. `invoice-feature`면 `invoice`, `INVOICE_`, `Invoice`다.
|
|
- 근거: `scale-architecture.md` §5(모듈 소유), §7(개수 예산), §9(라우터 구조).
|
|
|
|
③ **잡는 검사 / 못 잡는 것**
|
|
|
|
- 기능 라우트가 context 루트 밖에 있으면 앱 모듈이 적재 때 거부한다.
|
|
- 메시지: `Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (...)`
|
|
- `tests/architecture/context-route-roots.test.ts`(`test:coverage`, FE-GATE-005)와 라우터를 거치는 페이지 테스트가 이것을 실행한다.
|
|
- 생성 명령은 라우트를 늘 루트 아래에 둔다. 손으로 경로를 바꿀 때만 걸린다.
|
|
- context 하나에 기능이 예산보다 많으면 생성기가 거부한다.
|
|
- 메시지: `Context <context> feature cardinality <n> exceeds budget <max>`
|
|
- 예산은 선언 파일의 `CONTEXT_MAX_FEATURES`다.
|
|
- **못 잡음**: 경계를 잘못 고른 것 자체. 업무가 다른 기능을 한 context에 넣어도 검사는 통과한다.
|
|
|
|
④ **쓸 스킬**: `domain-driven-design`
|
|
|
|
---
|
|
|
|
## 1단계. 뼈대 만들기 — `create:feature`
|
|
|
|
기본 길은 생성 명령이다.
|
|
|
|
```bash
|
|
corepack pnpm create:feature invoice-feature
|
|
```
|
|
|
|
명령이 하는 일:
|
|
|
|
```text
|
|
인자 검사
|
|
→ 설치된 기능·context·라우트·topic·문구 키 읽기
|
|
→ 충돌 검사 (겹치면 아무것도 쓰지 않고 거부)
|
|
→ 파일 쓰기 (있는 파일은 덮어쓰지 않음)
|
|
→ 생성기 실행
|
|
→ 생성기가 거부하면 만든 파일을 모두 지움
|
|
→ 만든 파일과 다음 할 일 출력
|
|
```
|
|
|
|
① **정할 것**
|
|
|
|
- `--context <context id>`: 0단계에서 기존 context를 골랐을 때만 준다.
|
|
- `--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>`: 계약 패키지가 이미 배포됐을 때 준다. 셋은 함께 준다.
|
|
- 둘 다 없으면 새 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 reference-context`로 참조 context에 넣으면 참조 기능 테스트 `tests/features/reference-feature/installed-context-routing.test.ts`가 깨진다. 그 테스트는 참조 context의 라우트 수를 정확히 비교한다. 참조 context에는 넣지 않는다.
|
|
|
|
④ **쓸 스킬**: `clean-architecture`, `codebase-design`
|
|
|
|
---
|
|
|
|
## 2단계. 도메인 모델 (선택)
|
|
|
|
생성 명령은 `domain/` 폴더를 만들지 않는다.
|
|
|
|
① **정할 것**: 업무 규칙(불변식)이 있는가.
|
|
|
|
- 불변식: 늘 참이어야 하는 업무 조건이다. 예: "금액은 0 이상", "마감일은 시작일 뒤".
|
|
|
|
② **기준**
|
|
|
|
- 업무 규칙이 없으면 만들지 않는다. mapper가 DTO를 화면 값으로 바꾸는 것으로 충분하다.
|
|
- 있으면 `domain/<model>.ts`에 둔다.
|
|
- 생성 함수에서 불변식을 검사하고 `Object.freeze`로 고정한다.
|
|
- 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(참조 기능은 `name`을 `displayName`으로 바꾼다).
|
|
- 예제: `src/features/reference-feature/domain/`
|
|
- 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다.
|
|
- 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다.
|
|
- 서버가 정한 제한이면 `contracts/<base>-schemas.ts`에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다.
|
|
- 참조 기능도 이름 길이를 스키마(`reference-schemas.ts`)와 폼(`reference-resource-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/<base>-feature-contract.ts`: 선언 쪽. 라우트, 무효화, 계약 패키지 신원(`contractPackages`).
|
|
- `contracts/<base>-api-contract.ts`: V2 행. `check:registries`가 검사하는 선언이다.
|
|
- `contracts/<base>-contract-contribution.ts`: V3 descriptor. 실제로 실행되는 HTTP 계약이다.
|
|
- `contracts/<base>-schemas.ts`: zod 스키마와 검증기.
|
|
- `contracts/<base>-mapper.ts`: 와이어 값 → 화면 값.
|
|
|
|
같은 API를 V2와 V3로 두 번 쓴다. V2는 레지스트리 검사용 선언이고, V3는 실행용이다.
|
|
|
|
① **정할 것**
|
|
|
|
- 계약 출처. 실제 패키지 / 자리표시자. [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-인증)
|
|
- 바이트 한도·마감: V3 `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`. V2 `maxResponseBytes`는 V3 `responseByteLimit`와 같은 값이다.
|
|
- 스키마 ID, mapper 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한다.
|
|
- 계약 패키지(`@org-contracts/*`)는 `contracts/<service>-contract-contribution.ts` 이름의 파일에서만 import한다.
|
|
- 패키지 신원 네 필드(`packageId`, `version`, `digest`, `sourceRevision`)는 `<base>-feature-contract.ts`의 상수 하나에 있다. 바꿀 때는 넷을 함께 바꾼다.
|
|
- 근거: `scale-architecture.md` §13(재시도), §20~§22(검증 경계와 예산).
|
|
|
|
**응답 모양: 뼈대와 MSW(V3 모양)를 따른다**
|
|
|
|
뼈대·MSW·V3 실행기는 한 모양을 쓰고, 짝 백엔드는 다른 모양을 쓴다.
|
|
짝 백엔드의 정본은 `clean-architecture-backend-template/docs/web/http-contract.md`다(아래 `http-contract.md`).
|
|
|
|
| | 뼈대·MSW·V3 실행기 | 짝 백엔드 (`http-contract.md` §1) |
|
|
|---|---|---|
|
|
| 성공 본문 | DTO 자체. 예: `[{ "id": "n-1", "title": "..." }]` | Envelope `{ "success": true, "data": ..., "meta": ... }` |
|
|
| 실패 본문 | problem details `{ "type", "title", "status", "code" }`. `code`가 최상위에 있다 | Envelope `{ "success": false, "error": { "code", ... }, "meta": ... }` |
|
|
|
|
- Envelope: 성공·실패 본문을 한 번 더 감싸는 공통 바깥 객체다.
|
|
- problem details: 실패를 `type`·`title`·`status`로 적는 JSON 모양이다.
|
|
- V3 실행기는 응답 본문을 벗기지 않고 그대로 검증한다. 성공은 `outputValidator`, 실패는 `problemValidator`로 간다(`src/adapters/http/http-execution-v3.ts`).
|
|
- MSW 시나리오도 DTO와 problem details로 답한다. `{ data }`로 감싼 응답은 실패 사례인 `envelope-mismatch` 시나리오다(`tests/mocks/handlers/http-scenarios.ts`).
|
|
- Envelope를 읽는 코드는 V2 클라이언트(`src/adapters/http/client.ts`)뿐이다. 기능은 V3로 실행된다(`src/adapters/http/index.ts`의 V2 주석).
|
|
- `http-contract.md`는 status·`code`의 **뜻**(예: 409 `IDEMPOTENT_IN_FLIGHT`)의 정본이다. 기능 코드에서 그 code는 problem의 최상위 `code`로 읽는다.
|
|
|
|
**알려진 제한: 지금 만든 기능은 짝 백엔드의 응답을 그대로 읽지 못한다.**
|
|
|
|
```text
|
|
짝 백엔드 성공 Envelope → DTO 스키마 검증 실패 → 읽기 실패
|
|
짝 백엔드 실패 Envelope → problem 스키마 검증 실패 → 읽기는 실패, 쓰기는 결과 불명(MAYBE_APPLIED)
|
|
```
|
|
|
|
짝 백엔드에 붙이려면 따로 작업이 필요하다. 선택지는 둘이다. 백엔드가 이 API에 DTO·problem details 본문을 보내거나, 프론트 V3 쪽이 Envelope를 벗긴다(기능 스키마에서, 또는 실행기에서 한 번). 아직 어느 쪽도 정하지 않았고, 이 템플릿에 예제가 없다.
|
|
|
|
**V2 행의 입력 칸**
|
|
|
|
V2 행은 입력을 두 칸으로 나눠 적는다. 경로 파라미터는 `pathSchema`, 검색값·본문은 `requestSchema`다. V3는 입력 전체를 `inputValidator` 하나로 검증한다.
|
|
|
|
정본: 칸 정의는 `src/contracts/api-operations.ts`(`RestOperationV2`, `validateRestOperation`), 스키마 칸은 `src/contracts/schema-registry.ts`(`SchemaDefinition`). 아래는 자주 바꾸고 자주 막히는 칸만 적는다.
|
|
|
|
| 칸 | 뜻 | 값 고르는 법 | V3 짝 |
|
|
|---|---|---|---|
|
|
| `requestSource` | 입력이 요청의 어디로 가나 | `none`(입력 없음, 또는 경로 파라미터만), `search`(쿼리 문자열), `body`(JSON 본문) | `body`면 `requestBody: "JSON"`, 아니면 `"NONE"` |
|
|
| `requestSchema` | 검색값·본문 스키마 ID | `requestSource`가 `none`이면 기능의 빈 입력 스키마(`<Base>NoRequest`) | `requestSource`가 `none`이 아니면 `inputValidator`의 스키마 ID와 같다 |
|
|
| `pathSchema` | 경로 파라미터 스키마 ID. 비울 수 없다 | 경로 파라미터가 없으면 빈 입력 스키마 | 파라미터가 있으면 `inputValidator`의 스키마 ID와 같다 |
|
|
| `pathParameterNames` | `path`의 `{이름}` 목록 | `path`에 적은 이름과 정확히 같게. 없으면 `[]` | `projectRequest`가 돌려주는 `pathValues`의 키 |
|
|
| `maxEncodedSearchBytes` | 인코딩한 쿼리 문자열의 바이트 상한(0~32,768). V2 실행기만 읽는다 | 검색값이 없으면 0. 있으면 값의 최대 길이로 정한다(참조 기능 4,096) | 없음. V3는 고정 상한 8,192바이트(`HTTP_EXECUTION_CEILINGS.encodedQueryBytes`)를 쓴다 |
|
|
| 스키마 `boundary` | 그 스키마가 쓰이는 자리 | 아래 목록 | 없음 |
|
|
|
|
스키마 `boundary` 값:
|
|
|
|
- `route-params`: 라우트 경로 파라미터(`paramsSchema`). 같은 스키마를 GET의 `pathSchema`로도 쓴다.
|
|
- `route-search`: 라우트 검색값에만 쓴다.
|
|
- `route-search-api-request`: 라우트 검색값이면서 GET 쿼리다. 목록 검색이 이 경우다.
|
|
- `api-request`: 요청 본문, 그리고 빈 입력 스키마.
|
|
- `api-response`: 응답 DTO.
|
|
|
|
예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력 칸만 적었다. 나머지 칸은 생성된 행과 같다.
|
|
|
|
```ts
|
|
// GET /api/notices?q=... → V3 inputValidator: NoticeListQuery, projectRequest는 queryEntries를 채운다
|
|
NOTICE_LIST_ITEMS: defineRestOperation({
|
|
method: "GET",
|
|
path: "/api/notices",
|
|
requestSource: "search",
|
|
requestSchema: "NoticeListQuery", // boundary: "route-search-api-request"
|
|
pathSchema: "NoticeNoRequest", // boundary: "api-request"
|
|
pathParameterNames: [],
|
|
maxEncodedSearchBytes: 4_096,
|
|
}),
|
|
// GET /api/notices/{noticeId} → V3 inputValidator: NoticeParams, projectRequest는 pathValues를 채운다
|
|
NOTICE_GET_ITEM: defineRestOperation({
|
|
method: "GET",
|
|
path: "/api/notices/{noticeId}",
|
|
requestSource: "none",
|
|
requestSchema: "NoticeNoRequest",
|
|
pathSchema: "NoticeParams", // boundary: "route-params"
|
|
pathParameterNames: ["noticeId"],
|
|
maxEncodedSearchBytes: 0,
|
|
}),
|
|
```
|
|
|
|
경로 파라미터와 검색값·본문을 함께 받는 operation(예: `PUT /items/{id}` + 본문)은 아직 규칙이 없다. V2/V3 일치 테스트가 `V2 declares both a path and a request schema; decide which V3 input schema matches them`로 실패한다.
|
|
|
|
③ **잡는 검사 / 못 잡는 것**
|
|
|
|
- V2와 V3가 다르면 `tests/unit/http-operation-v2-v3-parity.test.ts`(`test:unit`, FE-GATE-005)가 실패한다.
|
|
- 비교하는 것: operation 목록, method, path, 성공 상태, 응답 한도, 인증 프로필, 재시도 의미, 쓰기 의미, 요청 본문, 스키마 ID.
|
|
- 마감 시간은 비교하지 않는다. V2 `timeoutMs`는 `null`이다.
|
|
- V2 입력 칸이 틀리면 모듈 로드 때 operation ID를 말하며 실패한다.
|
|
- `pathParameterNames`가 `path`의 이름과 다름: `REST path codec does not match its template: <operationId>`
|
|
- `pathSchema`가 비었거나 `maxEncodedSearchBytes`가 범위 밖: `Invalid REST operation contract: <operationId>`
|
|
- `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마: `Unresolved API schema binding: <operationId>`
|
|
- 인증 프로필 이름이 틀리면 operation을 적재하는 모든 게이트가 실패한다.
|
|
- 메시지: `REST security profiles are incoherent for <operationId>: unknown authProfileId <id>.`
|
|
- 스키마·mapper·operation ID가 겹치면 모듈 로드 때 그 ID를 말하며 실패한다.
|
|
- 예: `Invalid or duplicate schema definition: <schemaId>`
|
|
- `TEMPLATE_FIXTURE` 출처를 참조 기능 밖에서 쓰면 계약 조립이 거부한다.
|
|
- 오류의 `reason`: `<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature 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/<base>-feature-api.ts`
|
|
|
|
- input 타입: 페이지가 부르는 메서드 모음.
|
|
- gateway 타입: HTTP 어댑터가 구현하는 port.
|
|
- `create<Base>FeatureInput(gateway, { telemetry })`: input을 만드는 함수.
|
|
- `ApplicationFeatureInputs` 보강: `declare module ".../application-api.ts"`로 기능 ID와 input 타입을 잇는다.
|
|
- 보강(module augmentation): 다른 파일에 있는 타입에 키를 더하는 TypeScript 문법이다.
|
|
|
|
① **정할 것**
|
|
|
|
- input 메서드 이름. 사용자가 하는 일로 짓는다(`listItems`, `createInvoice`).
|
|
- 반환 타입. `Result<Value>`(`src/contracts/result.ts`)를 쓴다.
|
|
- 실패 telemetry의 `kind`. `<base>.<동작>.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 <id> installed an input for <other>`
|
|
- input 모양이 보강 타입과 다르면 `check:types`(FE-GATE-003)가 막는다. 음성 fixture `check:types:fixture:feature-input`도 같은 게이트에서 돈다.
|
|
- **못 잡음**: telemetry `kind` 중복. 유일성 검사가 없다. 접두어로 피한다.
|
|
|
|
④ **쓸 스킬**: `clean-architecture`, `codebase-design`
|
|
|
|
---
|
|
|
|
## 5단계. HTTP 어댑터와 조립 기여
|
|
|
|
생성된 파일:
|
|
|
|
- `adapters/<base>-http-gateway.ts`: `defineFeatureHttpOperationForRoutes`로 operation과 route ID를 묶고, gateway를 구현한다.
|
|
- `adapters/create-<base>-feature-input.ts`: `defineFeatureAdapterContribution`으로 조립 기여를 선언한다.
|
|
- 조립 기여: 부팅 때 플랫폼이 기능에게 capability를 주고 input을 받아 가는 약속이다.
|
|
|
|
① **정할 것**
|
|
|
|
- `needs`: 기능이 받을 capability. 템플릿이 만드는 것은 `http`, `telemetry`다.
|
|
- 문제 응답 → 실패 매핑. 필요하면 `mapProblem`을 둔다(예: 409, 422를 업무 실패로).
|
|
- 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.
|
|
- 여러 화면에서 부르면 주로 부르는 화면 하나를 고른다. 이름표는 하나뿐이다.
|
|
- 참조 기능은 생성 operation에 목록 route(`REFERENCE_RESOURCE_LIST`)를 적었다. 실제로 보내는 화면은 폼 route다. 동작은 같고 기록의 이름표만 다르다. 새 기능은 위 기준을 따른다.
|
|
- `needs`에는 실제로 쓰는 것만 적는다.
|
|
- 템플릿이 만들지 않는 capability(예: `indexedDb`)는 `src/bootstrap/product-composition.ts`에서 만든다. [03 문서](03-outside-feature-folder.md)를 본다.
|
|
- 문제 응답 매핑 예제: `src/features/reference-feature/adapters/reference-http-gateway.ts`
|
|
|
|
③ **잡는 검사 / 못 잡는 것**
|
|
|
|
- presentation이 기능 `adapters/`를 import하면 `feature-presentation-does-not-know-outbound-adapters`로 막는다.
|
|
- adapters가 presentation을 import하면 `feature-adapters-do-not-know-presentation`으로 막는다.
|
|
- 기능 루트 파일(`feature-module.ts` 등)이 `src/adapters`에 닿으면 `feature-and-app-roots-do-not-reach-adapters`로 막는다.
|
|
- operation ID·route ID·입력 타입을 틀리면 `check:types`가 막는다. 음성 fixture: `check:types:fixture:http-operation-id`, `check:types:fixture:http-route-id`, `check:types:fixture:http-operation-input`.
|
|
- 호스트가 주지 않는 capability를 `needs`에 적으면 조립이 실패한다.
|
|
- 메시지: `feature <id> needs <capability>, which the host did not provide`
|
|
- V2 operation을 선언하고 기능 `adapters/`·`application/`에서 쓰지 않으면 `check:registries`(FE-GATE-010)가 실패한다.
|
|
- 메시지: `FE-REG-API.<operationId> has no executable consumer for operationId=<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/<base>-feature-runtime.ts`: 지연 로드 페이지 표. `moduleId`는 계약과 같아야 한다.
|
|
- `context-routes.ts`: context가 적재하는 라우트 목록. 생성된 판은 계약의 라우트를 그대로 옮긴다.
|
|
- `presentation/<base>-routes.ts`: 링크용 URL 함수. route ID를 받아 `buildRouteUrl`(`src/presentation/routes/route-codecs.ts`)로 경로를 채운다.
|
|
- 문구 `route.<ROUTE_ID>.title`, `route.<ROUTE_ID>.navigation` (ko-KR, en-US).
|
|
- 기능 폴더 밖: `artifacts/tests/a11y-manual/<ROUTE_ID>.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`를 싣는다. 예제: `src/features/reference-feature/context-routes.ts`.
|
|
- 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 생성된 판은 파라미터가 없어서 넘기지 않는다. 안 넘기면 `Unregistered route codec: <codecId>`로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제: `src/features/reference-feature/presentation/reference-routes.ts`.
|
|
- 상세 경로는 목록 경로 뒤에 `/items/:<id 이름>`을 붙인다. 예: `/notice/items/:noticeId`. `/notice/:noticeId`로 두지 않는다.
|
|
- 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼 `/notice/new`가 있으면 id가 `new`인 공지는 `/notice/:noticeId`로 열 수 없다.
|
|
- `items/`를 끼우면 정적 경로와 겹치지 않는다. 참조 기능도 이렇게 한다(`/examples/reference-resources/items/:resourceId`).
|
|
- 경로 파라미터 이름이 `:resourceId`가 아니면 `tests/e2e/accessibility.spec.ts`의 치환 줄에 `.replace`를 하나 잇는다.
|
|
|
|
```ts
|
|
// 지금
|
|
: definition.path.replace(":resourceId", "reference-1");
|
|
// 예: 공지 기능의 /notice/items/:noticeId
|
|
: definition.path.replace(":resourceId", "reference-1").replace(":noticeId", "notice-1");
|
|
```
|
|
|
|
- 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 `:resourceId`만 실제 값으로 바꾼다.
|
|
- 안 고치면 `:noticeId`라는 글자가 그대로 id로 들어간다. 파라미터 스키마가 그 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사한다.
|
|
- 값은 아무 문자열이나 된다. 이 spec은 모든 API에 `[]`로 답해서 상세 페이지는 실패 상태로 그려진다.
|
|
- spec은 h1이 보일 때까지 기다린다. 그래서 상세 페이지는 데이터가 없을 때도 h1을 그린다. 예: `heading={{ title: notice?.title ?? message("notice.detail.titlePending") }}`처럼 데이터가 없으면 고정 제목("공지")을 쓴다.
|
|
- 이 줄은 기능 ID를 담지 않는다. 그래서 제거 드릴(11단계)이 잡지 못한다. 기능을 지울 때 손으로 지운다([03 문서](03-outside-feature-folder.md#기능을-지울-때)).
|
|
- 기능이 앱 홈(`/`)을 대신하려면 route ID `APP_HOME`을 쓴다. `docs/architecture/starter-experience.md`의 "Product home and layouts" 절을 본다.
|
|
|
|
③ **잡는 검사 / 못 잡는 것**
|
|
|
|
- route ID가 겹치면 조립이 실패한다. 메시지: `Duplicate route registry key: <ROUTE_ID>`
|
|
- 경로·`chunkId`가 겹치면 `check:registries`가 실패한다. 메시지: `FE-REG-ROUTE.<ROUTE_ID> duplicates path=<path> from <ROUTE_ID>`
|
|
- `loadingSurface`가 케밥 표기가 아니면 `check:registries`가 `does not match`로 실패한다.
|
|
- `context-routes.ts`의 handle이 계약에 없는 route ID를 가리키면 context 적재가 거부한다.
|
|
- 메시지: `Route handle <ROUTE_ID> loaded by context <context> is not a contract route of its features (...)`
|
|
- 라우트별 a11y 기록이 없으면 세 곳이 잡는다.
|
|
- `verify:documentation`(FE-GATE-017): `artifacts/tests/a11y-manual/ has no record for route IDs: <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-<base>-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`: 쿼리·뮤테이션 정의 이름.
|
|
- 쓰기가 있으면 뮤테이션 정책: `requiresIdempotencyKey`, `duplicatePolicy`, `invalidate`.
|
|
|
|
② **기준**
|
|
|
|
- topic은 복사하지 않는다. 새 topic이 더 필요하면 값을 새로 만든다.
|
|
- 형식: `qinv.` + 소문자·숫자 26자. `scripts/create-feature.ts`의 `randomTopicSuffix`가 쓰는 방식이다.
|
|
- `measureResult`에서 `JSON.stringify`를 쓰지 않는다. 문자열 바이트와 항목당 고정 크기로 어림한다(생성된 `measureItems` 참고).
|
|
- `KEYED` 쓰기는 `requiresIdempotencyKey: true`, `duplicatePolicy: "REJECT_WHILE_ACTIVE"`, `invalidate: [topic]`을 쓴다.
|
|
- 예제: `src/features/reference-feature/presentation/use-reference-feature.ts`의 생성 뮤테이션 정책.
|
|
|
|
③ **잡는 검사 / 못 잡는 것**
|
|
|
|
- topic·namespace가 겹치면 조립 때 실패한다. 메시지: `Duplicate invalidation topic: <topic>`, `Duplicate invalidation namespace: <key>`
|
|
- topic 형식이 틀리면 `Query invalidation topic is invalid.`로 실패한다.
|
|
- 등록되지 않은 profile은 실행 때 `Unregistered server-state profile: <id>`로 실패한다.
|
|
- topic·namespace·edge를 더하기만 하면 레지스트리 기준선은 바뀌지 않는다(additive). 9단계에서 할 일이 없다.
|
|
- **못 잡음**: `bindQuery`의 `operationId` 오타. 타입이 `string`이라 operation과 묶이지 않는다.
|
|
- **못 잡음**: `definitionId` 중복. 유일성 검사가 없다.
|
|
|
|
④ **쓸 스킬**: 정해 둔 스킬 없음. 이 절과 02 결정표로 판단한다.
|
|
|
|
---
|
|
|
|
## 8단계. 페이지
|
|
|
|
생성된 파일: `presentation/<base>-list-page.tsx` (`CollectionPage` + `AsyncSurface`)
|
|
|
|
① **정할 것**
|
|
|
|
- 페이지 템플릿. [02 결정표 6절](02-decision-tables.md#6-페이지-템플릿)
|
|
- `KEYED` 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기).
|
|
- 폼이면 서버 422 오류를 받을 필드(`useAppForm`의 `allowedServerFields`).
|
|
|
|
② **기준**
|
|
|
|
- 화면 문구는 모두 catalog에서 가져온다(`message(key)`).
|
|
- 링크는 6단계의 URL 함수로 만든다.
|
|
- 결과 불명 화면 예제: `src/features/reference-feature/presentation/reference-resource-form-page.tsx`
|
|
|
|
③ **잡는 검사 / 못 잡는 것**
|
|
|
|
- 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 변경이다. 둘 중 하나를 한다.
|
|
- `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/<profile>.json`의 `FEATURE_OVERRIDES`에 기능 ID를 적으면 그 환경에서 기능을 끈다.
|
|
|
|
③ **잡는 검사 / 못 잡는 것**
|
|
|
|
- breaking 변경에 승인이 없으면 `check:registries`가 실패한다.
|
|
- 메시지: `breaking change missing evidence: <changeId>`
|
|
- 지금 diff와 맞지 않는 증거 행이 남으면 `stale breaking evidence <changeId>: ...`로 실패한다.
|
|
- **못 잡음**: 사람이 서명하지 않은 a11y 기록은 merge 게이트를 통과한다. 릴리스 게이트 FE-GATE-028이 막는다.
|
|
|
|
④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration`
|
|
|
|
---
|
|
|
|
## 10단계. 테스트
|
|
|
|
생성된 파일:
|
|
|
|
- `tests/features/<id>/<base>-feature-input.test.ts`: application input 단위 테스트.
|
|
- `tests/features/<id>/<base>-list-page.test.tsx`: 라우터를 거치는 페이지 테스트.
|
|
- 앱 전체를 조립하고(`createRuntimeComposition`, `RuntimeApplication`), 로그인한 뒤 URL로 들어간다.
|
|
- API 응답은 MSW로 준다. `tests/mocks/handlers/http-scenarios.ts`의 `createHttpScenarioHandler(<OPERATION>_CONTRACT, { scenario, payload })`를 쓴다.
|
|
- 시나리오 이름의 정본은 `tests/mocks/scenarios/catalog.ts`의 `HttpScenarioId`다.
|
|
|
|
① **정할 것**: 어떤 상태를 테스트하나(성공, 빈 목록, 실패와 다시 시도, 결과 불명).
|
|
|
|
② **기준**
|
|
|
|
- 라우터를 거치는 페이지 테스트를 최소 하나 둔다. 0·6·8단계의 "못 잡음" 대부분을 이 테스트가 잡는다.
|
|
- 기능 테스트는 `tests/features/<id>/`에만 둔다. `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: "본문입니다." });
|
|
```
|
|
|
|
- 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제: `tests/features/reference-feature/reference-production-vertical.test.tsx`의 504 재전송 테스트.
|
|
- 빠르게 돌리기: `node scripts/run-vitest.ts run tests/features/<id>`
|
|
- 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와 tests에 기능 ID나 폴더 이름이 남았는지 찾음
|
|
```
|
|
|
|
① **정할 것**: 없음. 확인 단계다.
|
|
|
|
② **기준**
|
|
|
|
- 기능 전용 파일은 기능 폴더와 `tests/features/<id>/` 안에 둔다(원칙 6).
|
|
- 폴더 밖에 둘 수밖에 없는 파일은 [03 문서](03-outside-feature-folder.md)의 "기능을 지울 때" 목록에 있다. 실제로 지울 때 그 목록을 함께 지운다.
|
|
|
|
③ **잡는 검사 / 못 잡는 것**
|
|
|
|
- 남은 파일이 기능 ID나 폴더 이름을 담고 있으면 실패한다.
|
|
- 메시지: `<id> removal failed:` 다음 줄 `fixture-id-residue: residue: <files>`
|
|
- **못 잡음**: 기능 ID를 담지 않은 폴더 밖 파일. 예: route ID만 적은 e2e spec, `tests/e2e/accessibility.spec.ts`에 더한 파라미터 치환(6단계), `artifacts/tests/a11y-manual/<ROUTE_ID>.md`. 드릴은 `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`가 정적으로 끌어오는 선언·스키마·문구가 초기 청크에 들어가기 때문이다.
|
|
- 예산은 `config/performance/budgets.json`에 있다.
|
|
- 생성 명령의 드릴(`test:feature-scaffold`)은 이 검사를 돌리지 않는다. 넘으면 예산을 올리기 전에 팀이 정한다.
|