From 5c2f8b875cdf11d2d21878bff31b0e5b1fb21335 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 08:01:25 +0900 Subject: [PATCH] =?UTF-8?q?docs(manual):=20=EB=A7=A4=EB=89=B4=EC=96=BC?= =?UTF-8?q?=EB=A7=8C=EC=9C=BC=EB=A1=9C=20=EA=B8=B0=EB=8A=A5=EC=9D=84=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80=ED=95=9C=20=EC=8B=A4=ED=97=98=EC=9D=98=20?= =?UTF-8?q?=EB=A7=89=ED=9E=98=205=EA=B1=B4=EC=9D=84=20=EB=A9=94=EC=9A=B4?= =?UTF-8?q?=EB=8B=A4=20(1101/16-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 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 타입에서 확인 --- docs/manual/01-add-a-feature.md | 150 ++++++++++++++++++++++- docs/manual/02-decision-tables.md | 21 ++++ docs/manual/03-outside-feature-folder.md | 4 +- docs/manual/reference/errors.md | 4 + docs/manual/reference/patterns.md | 53 +++++++- 5 files changed, 228 insertions(+), 4 deletions(-) diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 333f772b..9cbccbc7 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -138,6 +138,11 @@ corepack pnpm create:feature invoice-feature - 생성 함수에서 불변식을 검사하고 `Object.freeze`로 고정한다. - 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(참조 기능은 `name`을 `displayName`으로 바꾼다). - 예제: `src/features/reference-feature/domain/` +- 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다. + - 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다. + - 서버가 정한 제한이면 `contracts/-schemas.ts`에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다. + - 참조 기능도 이름 길이를 스키마(`reference-schemas.ts`)와 폼(`reference-resource-form.ts`)에만 둔다. `domain/`에는 없다. + - domain에는 서버 제한이 바뀌어도 그대로인 업무 규칙만 둔다(예: "마감일은 시작일 뒤"). ③ **잡는 검사 / 못 잡는 것** @@ -180,11 +185,91 @@ corepack pnpm create:feature invoice-feature - 패키지 신원 네 필드(`packageId`, `version`, `digest`, `sourceRevision`)는 `-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`이면 기능의 빈 입력 스키마(`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: ` + - `pathSchema`가 비었거나 `maxEncodedSearchBytes`가 범위 밖: `Invalid REST operation contract: ` + - `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마: `Unresolved API schema binding: ` - 인증 프로필 이름이 틀리면 operation을 적재하는 모든 게이트가 실패한다. - 메시지: `REST security profiles are incoherent for : unknown authProfileId .` - 스키마·mapper·operation ID가 겹치면 모듈 로드 때 그 ID를 말하며 실패한다. @@ -248,9 +333,18 @@ corepack pnpm create:feature invoice-feature - `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` @@ -265,6 +359,7 @@ corepack pnpm create:feature invoice-feature - 메시지: `feature needs , which the host did not provide` - V2 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` @@ -296,7 +391,24 @@ corepack pnpm create:feature invoice-feature - 경로는 계약에만 적는다. 페이지와 링크는 route ID와 `buildRouteUrl`로 URL을 만든다. 경로 문자열을 페이지에 다시 적지 않는다. - 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제: `src/features/reference-feature/context-routes.ts`. -- 경로 파라미터가 `:resourceId`가 아니면 `tests/e2e/accessibility.spec.ts`를 고쳐야 한다([03 문서](03-outside-feature-folder.md)). + - 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 생성된 판은 파라미터가 없어서 넘기지 않는다. 안 넘기면 `Unregistered route codec: `로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제: `src/features/reference-feature/presentation/reference-routes.ts`. +- 상세 경로는 목록 경로 뒤에 `/items/:`을 붙인다. 예: `/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" 절을 본다. ③ **잡는 검사 / 못 잡는 것** @@ -425,6 +537,40 @@ corepack pnpm create:feature invoice-feature - 라우터를 거치는 페이지 테스트를 최소 하나 둔다. 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: "본문입니다." }); + ``` + + - 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제: `tests/features/reference-feature/reference-production-vertical.test.tsx`의 504 재전송 테스트. - 빠르게 돌리기: `node scripts/run-vitest.ts run tests/features/` - CI에서는 `test:coverage`(FE-GATE-005)가 `tests/features`를 돈다. `test:unit`은 `tests/unit`만 돈다. @@ -465,7 +611,7 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature - 남은 파일이 기능 ID나 폴더 이름을 담고 있으면 실패한다. - 메시지: ` removal failed:` 다음 줄 `fixture-id-residue: residue: ` -- **못 잡음**: 기능 ID를 담지 않은 폴더 밖 파일. 예: route ID만 적은 e2e spec, `artifacts/tests/a11y-manual/.md`. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. +- **못 잡음**: 기능 ID를 담지 않은 폴더 밖 파일. 예: route ID만 적은 e2e spec, `tests/e2e/accessibility.spec.ts`에 더한 파라미터 치환(6단계), `artifacts/tests/a11y-manual/.md`. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index d9772672..31e1a1d7 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -140,6 +140,27 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 서버가 보장하는 것만 `NOT_APPLIED`로 적는다. 나머지는 `MAYBE_APPLIED`다. - 같은 status라도 code로 나뉠 수 있다. 예: 409 중 "처리 중"은 `MAYBE_APPLIED`여야 한다. `NOT_APPLIED`로 보면 다음 저장이 새 키를 만들어 같은 작업이 두 번 적용된다. - 401·403·429는 문제 응답 본문을 읽기 전에 status로 나뉜다. 서버가 상태를 안 바꾼다고 보장하면 `classifyStatus`로 `NOT_APPLIED`를 돌려준다. 없으면 `MAYBE_APPLIED`다. +- 문제 응답 본문이 기능의 problem 스키마를 통과하지 못하면 `classifyProblem`을 부르지 않는다. 쓰기는 `MAYBE_APPLIED`가 된다(`src/adapters/http/http-execution-v3.ts`). + +**503 `IDEMPOTENCY_UNAVAILABLE`는 `NOT_APPLIED`로 분류하지 않는다.** + +백엔드는 이 응답을 "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로 정한다(`http-contract.md` §2 두 번째 표). 적용은 안 됐지만 다음 전송은 같은 키다. 위 표의 두 칸 어디에도 딱 맞지 않는다. + +지금 프론트 동작: + +```text +503 IDEMPOTENCY_UNAVAILABLE + → V3 실행기: 본문을 기능의 problem 스키마로 검증 + ├─ 통과 (problem details 모양) → 기능의 classifyProblem이 정한다 + │ 참조 기능: 400·422와 정해 둔 409 code만 NOT_APPLIED → 503은 MAYBE_APPLIED + └─ 실패 (짝 백엔드의 Envelope 모양) → 쓰기는 MAYBE_APPLIED + → 결과 불명 화면 → "같은 요청으로 다시 보내기"가 같은 키로 보낸다 +``` + +- V2 클라이언트(레거시)도 같다. `src/adapters/http/client.ts`의 `IDEMPOTENCY_REFUSALS`에는 422 `IDEMPOTENT_REQUEST_MISMATCH`와 400 `IDEMPOTENCY_KEY_INVALID`만 있다. 503은 effect 없이 돌아오고, 뮤테이션 조정자가 `MAYBE_APPLIED`로 본다(`src/presentation/adapters/query/application-query.ts`의 `mutationFailureWithEffect`). +- 판정: 맞는다. 지금 동작은 `MAYBE_APPLIED`이고 재전송은 같은 키다. 백엔드가 요구하는 행동과 같다. +- 다른 점은 화면뿐이다. 서버는 "실행 안 함"이라고 답했지만 화면은 "결과를 모른다"로 보여 준다. +- `NOT_APPLIED`로 바꾸면 다음 저장이 새 키를 만든다. 키를 다시 쓰는 것은 결과 불명으로 남은 요청뿐이다(같은 파일). 백엔드가 말한 "같은 키"와 어긋난다. **정본**: 어떤 status·code가 "적용 안 됨"인지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2다. diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index 54072d37..1c13012f 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -101,7 +101,7 @@ release admission refused for staging: 언제와 실패 메시지는 정본 표에 있다. 여기에는 무엇을 위해 고치는지만 적는다. - `src/contexts//context-layout.tsx`: context가 `AppShell` 대신 자기 틀을 쓸 때. 예제: `tests/helpers/fixture-layout-product.tsx`. -- `tests/e2e/accessibility.spec.ts`: 경로 파라미터가 `:resourceId`가 아닐 때, 또는 모든 API가 `[]`를 답하면 그려지지 않는 보호 페이지일 때. +- `tests/e2e/accessibility.spec.ts`: 경로 파라미터가 `:resourceId`가 아닐 때, 또는 모든 API가 `[]`를 답하면 그려지지 않는 보호 페이지일 때. 치환 줄 고치는 법은 [01 문서 6단계](01-add-a-feature.md#6단계-라우트). - `src/bootstrap/product-composition.ts`: `needs`에 템플릿이 만들지 않는 capability를 적었을 때. 제품 인증 프로필의 자격 증명도 여기서 준다. - 템플릿 파일 `src/bootstrap/runtime-adapters.ts`는 고치지 않는다. - `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때. @@ -141,6 +141,8 @@ release admission refused for staging: - `artifacts/tests/a11y-manual/.md` (라우트마다) - 남아도 검사는 실패하지 않는다. 검사는 등록된 라우트의 기록만 읽는다. 그래서 잊기 쉽다. - 기능 전용 `tests/e2e/` spec +- `tests/e2e/accessibility.spec.ts`에 더한 `.replace(":<파라미터>", "<값>")` + - 기능 ID를 담지 않아 제거 드릴이 잡지 못한다. 남아도 어떤 검사도 실패하지 않는다. - `config/runtime/.json`의 `FEATURE_OVERRIDES` 키 - `config/testing/risk-coverage.json`에서 그 기능을 가리키는 행 - 그 기능만 쓰던 제품 capability, 제품 인증 프로필, 계약 패키지 의존성 diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 1f98e36c..6cd11943 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -85,6 +85,10 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `Invalid or duplicate runtime schema codec: ` | 런타임 codec ID 중복 | `contracts/-schemas.ts` | | `Invalid or duplicate boundary mapper: ` | mapper ID 중복 또는 형식 | `contracts/-mapper.ts` | | `Duplicate API operation: ` | V2 operation ID 중복 | `contracts/-api-contract.ts` | +| `REST path codec does not match its template: ` | V2 `pathParameterNames`가 `path`의 `{이름}`과 다르다 | `contracts/-api-contract.ts` ([01 문서 3단계](../01-add-a-feature.md#3단계-api-계약) "V2 행의 입력 칸") | +| `Invalid REST operation contract: ` | V2 행 형식. 예: 빈 `pathSchema`, `maxEncodedSearchBytes`가 0~32,768 밖 | 같은 곳 | +| `Unresolved API schema binding: ` | V2 `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마 | 같은 파일의 `schemas`, `contracts/-schemas.ts`의 codec | +| `Unregistered route codec: ` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/-routes.ts` | | `contract package is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/-contract-contribution.ts`의 `source` | | ` contributes contract package , which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `_CONTRACT_PACKAGE` 하나를 쓰게 한다 | | `contract package is declared with conflicting identities` | 두 기능이 같은 패키지를 다른 버전·digest로 선언했다 | 두 기능의 `_CONTRACT_PACKAGE`를 맞춘다 | diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index 60778258..80171943 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -28,7 +28,50 @@ | context 라우트 적재 | `src/platform/routing/context-route-module.ts` | 생성 뼈대 `context-routes.ts` | context 적재(계약에 없는 handle) | | route ID로 URL 만들기 | `src/presentation/routes/route-codecs.ts`의 `buildRouteUrl` | 생성 뼈대 `presentation/-routes.ts`, 참조 기능 `presentation/reference-routes.ts` | 타입(기능의 route ID만 받음) | | 파라미터·검색값 codec | `src/presentation/routes/route-codecs.ts` | 참조 기능 `presentation/reference-route-codecs.ts` | 해석 실패 시 잘못된 경로 화면 | -| URL 필터를 바꾸는 폼 | 검색값 codec | 없음 (참조 기능은 필터를 보여 주기만 한다) | — | +| URL 검색값 읽기 | `src/presentation/routes/route-input.tsx`의 `useRouteInput` + 검색값 codec | 참조 기능 `presentation/reference-routes.ts` | 해석 실패 시 잘못된 경로 화면 | +| URL 검색값을 바꾸는 폼 | `buildRouteUrl`의 `search`, 디자인 시스템 `SearchField`, `CollectionPage`의 `toolbar` | 기능 예제 없음. 아래 짧은 예 | 라우터를 거치는 페이지 테스트 | + +### URL 검색값을 바꾸는 폼 (짧은 예) + +검색값의 정본은 URL이다. 입력 중인 글자만 state에 둔다. + +```text +사용자가 검색어를 입력한다 (state의 draft만 바뀐다) + → 제출하면 navigate(목록 URL + ?q=...) + → 라우터가 검색값 codec으로 q를 읽는다 + → 목록 쿼리 입력이 바뀌어 GET을 다시 보낸다 +``` + +준비: + +- 목록 라우트의 `searchSchema`와 `routeRuntimeContracts`의 `searchCodec`. +- 그 codec을 `context-routes.ts` handle의 `codecs`와 URL 함수(`buildRouteUrl`의 세 번째 인자)에 함께 넘긴다. +- 검색값을 읽는 hook. 참조 기능 `reference-routes.ts`의 `useReferenceListFilters`가 예제다. + +```tsx +// 공지 기능의 목록 페이지. noticeRouteUrl은 생성된 -routes.ts의 URL 함수다. +const navigate = useNavigate(); +const listQuery = useNoticeListQuery(); // URL 검색값 읽기 +const [draft, setDraft] = useState(listQuery.q ?? ""); +const search = (q: string) => + void navigate(noticeRouteUrl("NOTICE_LIST", q.trim() ? { search: { q: q.trim() } } : {})); + + { event.preventDefault(); search(draft); }}> + setDraft(event.currentTarget.value)} + onClear={() => { setDraft(""); search(""); }} + /> + + + } + /* heading, resultCount, children은 생성된 목록 페이지와 같다 */ +/> +``` ## API와 검증 @@ -68,6 +111,14 @@ | 화면 문구 | `src/presentation/i18n/index.ts`, 기능 문구 catalog | 생성 뼈대 `contracts/-message-catalog.ts` | `lint`(문구 literal), `check:i18n`(ko-KR·en-US 키) | | 권한 분기 | 라우트 `access`, 서버 403 → 실패 | 참조 기능 403 화면 테스트 | 가드 테스트. 역할·권한 힌트 예제는 없음 | +## 테스트 + +| 패턴 | 정의 | 예제 | 검사 | +|---|---|---|---| +| 응답 시나리오 | `tests/mocks/handlers/http-scenarios.ts`의 `createHttpScenarioHandler` | 생성 뼈대 페이지 테스트 | `test:coverage` | +| 보낸 요청(헤더·본문) 확인 | MSW `setupServer().events.on("request:start")` | [01 문서 10단계](../01-add-a-feature.md#10단계-테스트)의 짧은 예. 핸들러에서 모으는 방법은 참조 기능 `reference-production-vertical.test.tsx`의 504 재전송 테스트 | `test:coverage` | +| 같은 멱등 키 재전송 | 시나리오 `in-flight-409` + 위 요청 모으기 | 01 문서 10단계 | `test:coverage` | + ## 관측 | 패턴 | 정의 | 예제 | 검사 |