From f3b87b3f020b2e4d6fc237d20bb2e8c4971a49d1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 20:13:31 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=83=9D=EC=84=B1=ED=95=9C=20=EA=B8=B0?= =?UTF-8?q?=EB=8A=A5=EC=9D=B4=20=EC=A7=9D=20=EB=B0=B1=EC=97=94=EB=93=9C=20?= =?UTF-8?q?Envelope=EB=A5=BC=20=EC=9D=BD=EB=8A=94=EB=8B=A4=EB=8A=94=20?= =?UTF-8?q?=EA=B2=B0=EC=A0=95=EA=B3=BC=20=EA=B2=B0=EA=B3=BC=EB=A5=BC=20?= =?UTF-8?q?=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 매뉴얼 01 3단계, CHANGELOG 미출시 절, 리뷰 README 14.3은 "생성한 기능은 짝 백엔드 응답을 그대로 읽지 못한다, 해결 방법은 정하지 않았다"를 알려진 제한으로 적는다. 7db32e1로 V3가 responseEnvelope: "ENVELOPE_V1" operation의 Envelope를 읽게 되어 이 문장들이 틀렸다. 매뉴얼 02 4절의 503 흐름도와 계약 문서 4.1절도 "V3는 Envelope 없이 DTO를 검증"으로 적는다. 고른 방법 - 리뷰 README 14.6: 선택지 넷(V3 operation 단위 / provider 단위 / 백엔드 problem+json 모드 / 기능 스키마가 감쌈)의 판정과 이유, V2와 같은 판정 표, 의도한 차이 세 가지, RED→GREEN·게이트 결과, 남은 것. 14.3 행의 처리 칸은 14.6을 가리킨다. - 매뉴얼 01 3단계: "응답 모양"을 짝 백엔드 Envelope 기준으로 다시 쓰고, Envelope가 아닌 백엔드에 붙이는 순서(responseEnvelope 줄 삭제, problem details 스키마)를 따로 적었다. 알려진 제한 문단은 지웠다. - 매뉴얼 02 4절: 실행기가 먼저 정하는 판정 목록과 바뀐 503 흐름. - CHANGELOG: [계약] 행 하나, 알려진 제한을 남은 차이(참조 기능 미선언, V2와의 차이 셋, e2e 접근성 스펙의 [] 본문)로 바꿨다. - 14.4와 CHANGELOG의 "V3 진단에 problem code가 없다"에 bd83b49가 싣는 범위(멱등성 거절 reason 두 값)와 싣지 않는 것, 그 이유를 적었다. - 계약 문서 4.1절·compatibility.md: Envelope를 읽는 곳을 backend-envelope.ts로 고쳤다. 버린 대안 - 백엔드에 요청 문서 쓰기: (나)를 고르지 않아 요청할 것이 없다. 위험·한계 - 문서의 게이트 결과는 이 커밋 직전 트리(bd83b49, scaffold·sample-removal은 7db32e1)에서 잰 값이다. - 백엔드 링크는 두 repo가 나란히 있을 때만 열린다(기존과 같다). 검증 - verify:documentation PASS_SCOPED. - 게이트 수치는 README 14.6 결과 표에 실행한 커밋과 함께 적었다. - tests/unit/changelog-review-ids.test.ts 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6 --- CHANGELOG.md | 7 ++- .../backend-api-and-server-state-contract.md | 8 +-- docs/contracts/compatibility.md | 2 +- docs/manual/01-add-a-feature.md | 43 ++++++++------- docs/manual/02-decision-tables.md | 13 +++-- .../2026-11-01-maturity-review/README.md | 54 ++++++++++++++++++- 6 files changed, 96 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 160723aa..4a29f83c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -74,6 +74,7 @@ | [계약] | V2 Envelope에 `data` 키가 없으면 `null`로 읽는다. `meta.requestId`·`traceId`는 선택이다. 짝 백엔드는 null 필드를 생략한다 (백엔드 리뷰 1101/02-02) | `src/adapters/http/schema-registry.ts` | `969979d` | | [계약] | V2: 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`가 `effect: "NOT_APPLIED"`와 진단 reason을 싣는다. 409의 `Retry-After`는 `retryAfterMs`로 실린다(V3 PROBLEM 실패도 같다). 결과 불명 요청을 같은 키로 다시 보낼 때 그 시각까지(최대 5초) 기다린다. 응답 code의 정본은 백엔드 템플릿 `docs/web/http-contract.md` §2다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/adapters/http/feature-http-binding.ts`, `src/presentation/adapters/query/application-query.ts` | `93782b0`, `47fec5c` | | [계약] | V2 클라이언트가 짝 백엔드의 400 `VALIDATION_FAILED`(필드 목록 `details: [{field, code, message}]`)를 422와 같은 `VALIDATION_REJECTED`·`validationIssues`로 읽는다. 필드 검증 거절(422와 이 400)은 `effect: "NOT_APPLIED"`다. 전에는 결과 불명으로 붙들어 폼에서 값을 고쳐도 다시 저장할 수 없었다. 그 밖의 400·409는 그대로 결과 불명이다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/contracts/errors.ts` | `02e35d2`, `64e98ee` | +| [계약] | V3 descriptor에 선택 필드 `responseEnvelope`가 생겼다. `"ENVELOPE_V1"`이면 V3 실행기가 짝 백엔드 Envelope(`{success, data\|error, meta}`)를 읽는다. `outputValidator`는 `data`(키가 없으면 `null`), `problemValidator`는 `error`를 받는다. 멱등성 거절·처리 중 409·503 `IDEMPOTENCY_UNAVAILABLE`·필드 검증 400은 실행기가 V2와 같은 표로 먼저 판정하고, `mapProblem`이 답하지 않으면 V2와 같은 kind·code·필드 오류로 읽는다. 성공 status의 Envelope 아닌 본문은 새 위반 `ENVELOPE_MISMATCH`다(`HttpContractViolationKind`에 추가만, exhaustive switch는 분기를 더한다). Envelope operation의 진단은 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`에 V2와 같은 `reason`을 싣는다(`HttpDiagnosticReason`에 두 값 추가). `create:feature`가 만든 기능은 이 값을 선언하고 problem 스키마가 Envelope `error`다. 값이 없는 descriptor(참조 기능 포함)는 그대로다. 이전에 만든 기능을 짝 백엔드에 붙이려면 contribution에 `responseEnvelope: "ENVELOPE_V1" as const`를 더하고 problem 스키마를 `error` 모양(`code` 필수)으로 바꾼다 (1101 README 14.3) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/`, `scripts/create-feature.ts`, `tests/mocks/handlers/http-scenarios.ts` | `7db32e1`, `bd83b49` | | [계약] | V3 실행 결과에 선택 필드 `sentRequestId`가 생겼다. 서버가 `x-correlation-id`를 돌려주지 않으면 `AppFailure.requestId`는 보낸 값이다. 결과 불명·조회 실패 화면에 "지원 참조" 줄이 보인다 (0929/03-04) | `src/adapters/http/http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts` | `849d000` | | [계약] | `ResumableUploadPort.upload()`: part 발급(BFF)이 401/403으로 거절하면 recovery가 `RESUME` 대신 `NONE`(`retryable: false`)이다. 세션 만료·권한 회수라 재인증 전에는 다시 불러도 같다. object store PUT 403은 그대로 `RESUME`이다 (0929/01-01) | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | `c5f87aa` | | [계약] | realtime stream coordinator의 effect·recovery·close 마감 실패가 `IDLE_TIMEOUT` 대신 `APPLY_FAILED`/`APPLY`, `PROVIDER_UNAVAILABLE`/`RECOVER`, `PROVIDER_UNAVAILABLE`/`CLOSE`로 나온다. `RealtimeObservation.reason`도 같다 (1101/04-02) | `src/adapters/realtime/stream-coordinator.ts` | `1196b86` | @@ -120,8 +121,10 @@ ### 알려진 제한 - 백엔드 응답 code 정본(`clean-architecture-backend-template/docs/web/http-contract.md`)은 아직 백엔드 repo에 커밋되지 않았다. 그래서 프론트 계약 문서는 커밋 SHA 대신 결정일로 기준을 적었다. 백엔드 application 층이 쓰기 뒤에 `VALIDATION_FAILED`를 던지면 "적용 안 됨" 판정이 틀린다. 지금 백엔드는 이 code를 요청 바인딩 단계에서만 낸다. -- 백엔드 필드 검증 code(`NOT_BLANK`, `SIZE` 등)가 폼 문구 표에 없어 "입력값을 확인해 주세요." 기본 문구가 나온다. V3 실행기 진단에는 problem code가 없다. -- **`create:feature`로 만든 기능과 참조 기능(V3 실행기)은 짝 백엔드의 Envelope 응답(`{success, data|error, meta}`)을 그대로 읽지 못한다.** V3는 DTO 본문과 problem details를 읽는다. 백엔드 맞추기는 V2 클라이언트에만 들어갔다. 해결 방법은 아직 정하지 않았다 (1101 README 14.3). +- 백엔드 필드 검증 code(`NOT_BLANK`, `SIZE` 등)가 폼 문구 표에 없어 "입력값을 확인해 주세요." 기본 문구가 나온다. V3 실행기 진단은 Envelope operation의 멱등성 거절 두 가지만 V2와 같은 `reason`으로 남긴다. 그 밖의 백엔드 code는 진단에 없고 실패의 `code`에만 있다. DTO 모드 operation의 진단에는 code가 없다. +- 참조 기능은 `responseEnvelope`를 선언하지 않아 지금도 DTO와 problem details만 읽는다. 짝 백엔드에 붙이려면 그 기능의 contribution과 problem 스키마·`mapProblem`·MSW 본문을 Envelope로 바꾼다. `create:feature`로 만든 기능은 Envelope를 읽는다 (1101 README 14.3). +- V3 Envelope 경로와 V2의 차이 세 가지(1101 README 14.6): 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸 KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 둘 다 결과 불명). 구조 예산(깊이 64 등)은 V3에만 있다. +- `tests/e2e/accessibility.spec.ts`는 모든 API에 `[]`로 답한다. 생성한 기능은 그 본문을 Envelope 불일치로 읽으므로, 그 라우트는 빈 목록 대신 오류 화면이 검사된다. e2e로 확인하지는 않았다. - webkit에서 `old-tab-chunk-recovery.spec.ts`가 가끔 "preload했지만 쓰지 않음" 경고로 실패할 수 있다(한 번 관찰, 10회 반복은 통과). - context 레이아웃의 skip link와 `
`은 타입 주석·문서·테스트로만 지킨다. 실행 검사는 없다 (1101/09-03). - OPFS: lease 밖(FINISH~commit)에서 다른 탭이 같은 partition에 쓰는 경합은 검증하지 않았다 (0929/05-01). diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 13d88ca9..83d9be19 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -168,9 +168,11 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 - 기준 버전: 백엔드 성숙도 리뷰 2026-11-01의 15절 결정(2026-11-03)을 반영한 본. 값이 null인 필드는 키째 생략한다. 백엔드에 이 변경의 커밋이 생기면 그 SHA로 바꾼다. -- 프론트에서 Envelope를 읽는 곳: V2 `src/adapters/http/schema-registry.ts`와 - `src/adapters/http/client.ts`. V3 실행기는 Envelope 없이 DTO를 검증한다 - (`src/adapters/http/index.ts` V2 주석). +- 프론트에서 Envelope를 읽는 곳: `src/adapters/http/backend-envelope.ts` + (스키마는 `schema-registry.ts`). V2 `client.ts`는 늘 이것을 쓴다. V3 실행기는 + descriptor가 `responseEnvelope: "ENVELOPE_V1"`일 때만 쓴다. `create:feature`가 + 만든 기능은 이 값을 선언한다. 참조 기능은 선언하지 않고 DTO와 problem + details를 검증한다. ### 4.2 Status와 error diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index 49c43497..25152bdb 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -24,7 +24,7 @@ reader that accepts it must ship before any writer sends it. | `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `capabilityOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` | | `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` | | Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` | -| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/schema-registry.ts` | +| HTTP success/failure envelope (V2, and V3 with `responseEnvelope: "ENVELOPE_V1"`) | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/schema-registry.ts`, read by `src/adapters/http/backend-envelope.ts` | | HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in `src/features/reference-feature/contracts/reference-schemas.ts` | | Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` | | Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 9cbccbc7..d4253183 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -185,31 +185,38 @@ corepack pnpm create:feature invoice-feature - 패키지 신원 네 필드(`packageId`, `version`, `digest`, `sourceRevision`)는 `-feature-contract.ts`의 상수 하나에 있다. 바꿀 때는 넷을 함께 바꾼다. - 근거: `scale-architecture.md` §13(재시도), §20~§22(검증 경계와 예산). -**응답 모양: 뼈대와 MSW(V3 모양)를 따른다** +**응답 모양: 짝 백엔드의 Envelope** -뼈대·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`로 읽는다. - -**알려진 제한: 지금 만든 기능은 짝 백엔드의 응답을 그대로 읽지 못한다.** +- Envelope: 성공·실패 본문을 한 번 더 감싸는 공통 바깥 객체다(`http-contract.md` §1). + - 성공: `{ "success": true, "data": ..., "meta": ... }` + - 실패: `{ "success": false, "error": { "code", ... }, "meta": ... }` +- 이 모양을 읽게 하는 것은 V3 descriptor(`-contract-contribution.ts`)의 한 줄 `responseEnvelope: "ENVELOPE_V1"`이다. 뼈대에 들어 있다. ```text -짝 백엔드 성공 Envelope → DTO 스키마 검증 실패 → 읽기 실패 -짝 백엔드 실패 Envelope → problem 스키마 검증 실패 → 읽기는 실패, 쓰기는 결과 불명(MAYBE_APPLIED) +성공 status → Envelope 확인 → data를 outputValidator로 검증 → mapSuccess +실패 status → Envelope 확인 → error를 problemValidator로 검증 → 판정(effect) → mapProblem ``` -짝 백엔드에 붙이려면 따로 작업이 필요하다. 선택지는 둘이다. 백엔드가 이 API에 DTO·problem details 본문을 보내거나, 프론트 V3 쪽이 Envelope를 벗긴다(기능 스키마에서, 또는 실행기에서 한 번). 아직 어느 쪽도 정하지 않았고, 이 템플릿에 예제가 없다. +- 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다. +- problem 스키마(`-schemas.ts`의 `ProblemSchema`)는 Envelope의 `error` 객체다. 분기는 `code`로 한다. `message`는 버린다. +- 백엔드가 operation과 상관없이 정한 판정(멱등성 거절, 처리 중 409, 필드 검증 400)은 실행기가 먼저 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. +- `mapProblem`이 없거나 `undefined`를 돌려주면 V2 클라이언트와 같은 kind·code·필드 오류로 읽는다(`src/adapters/http/backend-envelope.ts`). +- 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다. V2 `maxResponseBytes`와 같은 값이다. +- MSW: `createHttpScenarioHandler`는 descriptor의 `responseEnvelope`를 보고 Envelope로 답한다(`tests/mocks/handlers/http-scenarios.ts`). 생성된 `tests/features//-http-gateway.test.ts`는 백엔드 본문을 그대로 적어 검사한다. +- `http-contract.md`는 status·`code`의 **뜻**(예: 409 `IDEMPOTENT_IN_FLIGHT`)의 정본이다. 기능 코드에서 그 code는 problem의 `code`로 읽는다. + +**짝 백엔드가 아닌 백엔드** + +DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 백엔드에 붙일 때: + +1. descriptor에서 `responseEnvelope` 줄을 지운다. +2. problem 스키마를 problem details 모양으로 바꾼다. +3. `classifyProblem`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다. + +참조 기능(`src/features/reference-feature/`)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다. **V2 행의 입력 칸** diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 31e1a1d7..42e977fa 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -141,6 +141,9 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 같은 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`). +- `responseEnvelope: "ENVELOPE_V1"`인 operation은 짝 백엔드가 operation과 상관없이 정한 판정을 실행기가 먼저 적용한다(`src/adapters/http/backend-envelope.ts`의 `envelopeFailureEffect`). `classifyProblem`은 그 밖의 응답만 받는다. + - `NOT_APPLIED`: 422, 필드 목록이 있는 400 `VALIDATION_FAILED`, 400 `IDEMPOTENCY_KEY_INVALID` + - `MAYBE_APPLIED`: 409 `IDEMPOTENT_IN_FLIGHT`, 503 `IDEMPOTENCY_UNAVAILABLE`. `classifyProblem`이 `NOT_APPLIED`라고 해도 바뀌지 않는다 **503 `IDEMPOTENCY_UNAVAILABLE`는 `NOT_APPLIED`로 분류하지 않는다.** @@ -150,14 +153,14 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 ```text 503 IDEMPOTENCY_UNAVAILABLE - → V3 실행기: 본문을 기능의 problem 스키마로 검증 - ├─ 통과 (problem details 모양) → 기능의 classifyProblem이 정한다 - │ 참조 기능: 400·422와 정해 둔 409 code만 NOT_APPLIED → 503은 MAYBE_APPLIED - └─ 실패 (짝 백엔드의 Envelope 모양) → 쓰기는 MAYBE_APPLIED + → V3 실행기 + ├─ responseEnvelope: "ENVELOPE_V1" (생성한 기능) → 실행기가 MAYBE_APPLIED로 정한다 + └─ Envelope 없음 (참조 기능) → 기능의 classifyProblem이 정한다 + 참조 기능: 400·422와 정해 둔 409 code만 NOT_APPLIED → 503은 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`). +- V2 클라이언트(레거시)도 같다. V2와 V3 Envelope 경로가 같은 표(`src/adapters/http/backend-envelope.ts`)를 읽는다. V2는 `NOT_APPLIED`만 싣고 503은 effect 없이 돌아온다. 뮤테이션 조정자가 그것을 `MAYBE_APPLIED`로 본다(`src/presentation/adapters/query/application-query.ts`의 `mutationFailureWithEffect`). - 판정: 맞는다. 지금 동작은 `MAYBE_APPLIED`이고 재전송은 같은 키다. 백엔드가 요구하는 행동과 같다. - 다른 점은 화면뿐이다. 서버는 "실행 안 함"이라고 답했지만 화면은 "결과를 모른다"로 보여 준다. - `NOT_APPLIED`로 바꾸면 다음 저장이 새 키를 만든다. 키를 다시 쓰는 것은 결과 불명으로 남은 요청뿐이다(같은 파일). 백엔드가 말한 "같은 키"와 어긋난다. diff --git a/docs/reviews/2026-11-01-maturity-review/README.md b/docs/reviews/2026-11-01-maturity-review/README.md index a7fff703..16fb43a3 100644 --- a/docs/reviews/2026-11-01-maturity-review/README.md +++ b/docs/reviews/2026-11-01-maturity-review/README.md @@ -499,7 +499,7 @@ | 적재에 실패한 레지스트리 source를 "missing registry source"로만 적어, 기능 계약의 깨진 import가 파일 없음처럼 보였다 | U6·U3 후속을 합칠 때 실제로 겪었다 | 고쳤다(`3ea7c37`, 새 테스트) | | 등록 라우트가 없는 URL에서 적재가 실패하면 진단 `route_id`가 `NOT_FOUND`다 | NOT_FOUND splat이 모든 URL에 맞아 gateway의 `?? routeModule.id`를 쓰지 않는다 | 남김(14.4) | | `tests/e2e/reference-route.spec.ts`가 세 엔진에서 실패했다. 0929/08-02가 목록 h1을 "참조 기능"으로 바꿨는데 테스트는 영어 route 제목을 기다렸다. 그 수정 때 e2e를 돌리지 않았다 | 14.5 첫 e2e 실행. 화면은 정상(스크린샷) | 고쳤다(`87aebf4`) | -| **생성한 기능은 짝 백엔드 응답을 그대로 읽지 못한다.** `create:feature`와 참조 기능이 쓰는 V3 실행기는 응답 본문을 DTO로 바로 검증하고 오류를 problem details(최상위 `code`)로 읽는다. 짝 백엔드는 모든 JSON 응답을 Envelope(`{success, data\|error, meta}`)로 보낸다. 01-01~02-02의 백엔드 맞추기는 V2 클라이언트만 Envelope에 맞췄다 | `src/adapters/http/index.ts` 41-48행 주석("V2는 봉투를, V3는 DTO 자체를 검증"), `docs/architecture/backend-api-and-server-state-contract.md` 4.1절, 백엔드 `docs/web/http-contract.md` 1절. 매뉴얼 재실험(아래)에서 실험자가 3단계에서 막혔다 | 확인된 결함 · High · P1. 두 템플릿을 짝으로 써서 빨리 출시한다는 목표에 직접 걸린다. 고치려면 결정이 필요하다(V3에 Envelope 읽기 추가 / 백엔드에 problem+json 모드 / BFF가 변환). 남김 | +| **생성한 기능은 짝 백엔드 응답을 그대로 읽지 못한다.** `create:feature`와 참조 기능이 쓰는 V3 실행기는 응답 본문을 DTO로 바로 검증하고 오류를 problem details(최상위 `code`)로 읽는다. 짝 백엔드는 모든 JSON 응답을 Envelope(`{success, data\|error, meta}`)로 보낸다. 01-01~02-02의 백엔드 맞추기는 V2 클라이언트만 Envelope에 맞췄다 | `src/adapters/http/index.ts` 41-48행 주석("V2는 봉투를, V3는 DTO 자체를 검증"), `docs/architecture/backend-api-and-server-state-contract.md` 4.1절, 백엔드 `docs/web/http-contract.md` 1절. 매뉴얼 재실험(아래)에서 실험자가 3단계에서 막혔다 | 확인된 결함 · High · P1. 두 템플릿을 짝으로 써서 빨리 출시한다는 목표에 직접 걸린다. 고쳤다(`7db32e1`). V3 descriptor의 `responseEnvelope: "ENVELOPE_V1"`, 결정과 결과는 14.6 | | 매뉴얼만 보고 기능(`notice-feature`, 목록·상세·작성 폼)을 추가하는 실험 E를 다시 했다. 막힘 5건(각 2~5분), 예고된 실패 1건. 원래 실험 E의 막힘 12곳보다 줄었지만 "막힘 0" 기준은 못 맞췄다 | 실험 브랜치 `worktree-agent-a13a14a7bbd252aad` `b58d131` 본문. 끝 상태: tsc 3종, registries(additive), i18n, 문서 검사, 기능 테스트 21건, unit·component·integration 3,022건 통과 | 막힘 5건은 매뉴얼에 메웠다(`5c2f8b8`). 응답 모양 막힘은 위 결함이 원인이라 매뉴얼에는 제한으로만 적었다 | | webkit에서 `old-tab-chunk-recovery.spec.ts`가 한 번 실패했다. preload한 청크(badge·card·schema-registry·server-state)를 load 뒤 몇 초 안에 쓰지 않았다는 브라우저 경고를 strict 검사가 실패로 본다 | 14.5 최종 e2e. 같은 커밋에서 webkit 10회 반복은 10/10 통과(load 16) | 간헐 실패 위험 · Low. 08-08이 초기 preload 청크를 늘린 것과 관련 있을 수 있다. 남김 | | `check:remediation-ledger`가 기준 커밋에서도 4건 실패했다(게이트 밖) | 예산 1건은 `313f9ba`로 풀렸다. 테스트가 TR-02~04 ID를 적지 않는 3건은 남았다 | 남김 | @@ -508,7 +508,7 @@ - 백엔드 응답 code 정본(`docs/web/http-contract.md`)이 백엔드 repo에 아직 커밋되지 않았다. 프론트 계약 문서는 SHA 대신 결정일로 기준을 적었다. - "검증 거절은 적용 안 됨" 판정: 백엔드 application 층이 쓰기 뒤 `VALIDATION_FAILED`를 던지면 틀린다. 필드 목록 없는 400 `VALIDATION_FAILED`와 그 밖의 400·409는 여전히 결과 불명이다. -- 백엔드 필드 검증 code(`NOT_BLANK`, `SIZE` 등)가 폼 문구 표에 없어 기본 문구가 나온다. V3 실행기 진단에 problem code가 없다. +- 백엔드 필드 검증 code(`NOT_BLANK`, `SIZE` 등)가 폼 문구 표에 없어 기본 문구가 나온다. V3 실행기 진단에 problem code가 없다. (2026-11-03: Envelope operation은 V2와 같은 멱등성 거절 `reason`을 싣는다. 14.6) - 09-03: 레이아웃의 skip link·`
`은 실행 검사가 없다. 플랫폼 라우트와 같은 경로의 기능 라우트를 검사하지 않는다. - 09-02 이식: env.ts의 FE-REG-ENV 행과 tech-log의 부트 전 BFF owner 설치는 아직 템플릿 파일 수정이 필요하다. 다운스트림 이식은 하지 않았다. - 0929/05-01: lease 밖(FINISH~commit) 다른 탭 경합은 검증하지 않았다. @@ -531,3 +531,53 @@ | `test:e2e` (chromium·firefox·webkit) | 186 통과, 1 실패(webkit 간헐, 14.3), 3 skip. 바로 전 실행(`313f9ba`)에서는 `reference-route.spec.ts`가 실패해 `87aebf4`로 고쳤다 | | `test:visual` | 6 통과. 골든을 다시 찍지 않았다 | | 실행하지 않음 | 실제 Gitea runner, 실제 HTTPS 호스트 probe, 다운스트림(tech-log·memento) 이식 | + +### 14.6 V3 Envelope 읽기 (14.3 High, 2026-11-03) + +**결정**: (가) V3 실행기에 operation 단위 Envelope 읽기를 더한다. V3 descriptor에 선택 필드 `responseEnvelope: "ENVELOPE_V1"`을 두고, `create:feature`가 만든 기능은 이 값을 선언한다. 값이 없는 descriptor는 지금처럼 DTO와 problem details를 읽는다. + +| 선택지 | 판정 | 이유 | +|---|---|---| +| (가) V3 실행기, operation 단위 | 고름 | 프레임 확인·바이트 상한·구조 예산·판정이 실행기 한 곳에 있다. V2와 같은 해석 모듈(`src/adapters/http/backend-envelope.ts`)을 써서 두 경로의 판정이 갈라질 수 없다. 값이 없는 descriptor는 바뀌지 않아 참조 기능·테스트 계약·recipe를 건드리지 않는다 | +| (가) V3 실행기, provider 단위 | 버림 | V3 실행기는 `baseUrl` 하나라 provider 단위가 곧 앱 전체다. 참조 기능과 테스트 계약의 problem details fixture가 모두 깨진다. 한 앱이 두 모양의 API를 같이 쓸 수 없다 | +| (나) 백엔드가 problem+json·DTO 모드 제공 | 버림 | 백엔드 소유자 결정 2("JSON 응답은 모두 Envelope", 백엔드 `docs/web/http-contract.md` 1절)와 반대다. 백엔드가 두 응답 모양을 계속 유지해야 한다. 고르지 않았으므로 요청 문서는 쓰지 않았다 | +| (다) 기능 스키마가 Envelope를 직접 감쌈 | 버림 | 기능마다 null 생략·`success` 판별·멱등성 판정을 다시 쓴다. V2 행은 `data`의 스키마 ID를 적으므로 V2/V3 동등 검사(`tests/unit/http-operation-v2-v3-parity.test.ts`)의 스키마 ID가 갈라진다. 실행기는 여전히 백엔드 code를 모른다 | + +**V2와 같은 판정**: V2 `client.ts`가 갖고 있던 멱등성 거절 표, 필드 검증 판정, gateway status 규칙을 `backend-envelope.ts`로 옮겼다. V2, V3 실행기, feature binding이 이 파일 하나를 읽는다. `tests/integration/http-execution-v3-envelope.test.ts`가 같은 응답을 V2와 V3에 보내 kind·code·httpStatus·effect·retryAfterMs·validationIssues를 비교한다. + +| 응답 (쓰기, `classifyProblem`은 모두 `MAYBE_APPLIED`) | kind | effect | 그 밖 | +|---|---|---|---| +| 409 `IDEMPOTENT_IN_FLIGHT`, `Retry-After: 2` | `CONFLICT` | `MAYBE_APPLIED`. `classifyProblem`이 `NOT_APPLIED`라고 해도 바뀌지 않는다 | `retryAfterMs` 2,000 | +| 422 `IDEMPOTENT_REQUEST_MISMATCH` | `VALIDATION_REJECTED` | `NOT_APPLIED` | | +| 400 `IDEMPOTENCY_KEY_INVALID` | `UNKNOWN_CLIENT_FAILURE` | `NOT_APPLIED` | | +| 503 `IDEMPOTENCY_UNAVAILABLE` | `SERVER_FAILURE` | `MAYBE_APPLIED`. 위와 같이 고정 | | +| 400 `VALIDATION_FAILED` + 필드 목록 | `VALIDATION_REJECTED` | `NOT_APPLIED` | `validationIssues` | +| 400 `VALIDATION_FAILED` + `{cause}` | `UNKNOWN_CLIENT_FAILURE` | `classifyProblem` | | +| 그 밖의 실패 (예: 409 도메인 충돌) | V2와 같은 status 규칙 | `classifyProblem` | | + +- 바이트 상한: 성공 Envelope는 본문 전체를 `responseByteLimit`(V2 `maxResponseBytes`와 같은 값)로 센다. 실패 Envelope는 min(64 KiB, `responseByteLimit`)이다. 구조 예산도 Envelope 전체에 건다. +- `mapProblem`이 없거나 `undefined`를 돌려주면 V2와 같은 kind·code·필드 오류로 읽는다. +- 성공 status인데 Envelope가 아닌 본문(맨 DTO, 실패 Envelope, `error`가 붙은 성공)은 새 위반 `ENVELOPE_MISMATCH`이고 `AppFailure.kind`도 `ENVELOPE_MISMATCH`다(V2와 같다). +- MSW `createHttpScenarioHandler`가 descriptor를 보고 Envelope로 답한다. 생성된 `tests/features//-http-gateway.test.ts`는 백엔드 본문을 그대로 적어 성공·null 생략·실패·필드 검증·맨 DTO 거절을 검사한다. + +**V2와 남은 차이** (의도한 것): + +- 64 KiB보다 크고 `maxResponseBytes` 이하인 실패 Envelope는 V2만 읽는다. V3 problem 상한(scale-architecture.md §7.3)은 올리지 않았다. 짝 백엔드에서 이 크기가 나오는 실패는 bulk 부분 실패뿐이고, 프론트에 bulk 사용처가 없다. +- 보낸 KEYED 요청의 503: V2는 같은 키로 자동 재시도하고, V3는 재시도하지 않고 결과 불명으로 화면에 넘긴다(V3 규칙 `canRetryTransport`). effect 판정은 둘 다 `MAYBE_APPLIED`다. +- 구조 예산(깊이 64, 항목 100,000)은 V3에만 있다. + +**결과** + +| 항목 | 결과 | +|---|---| +| 커밋 | `7db32e1`(Envelope 읽기·뼈대·테스트), `bd83b49`(진단 reason), 이 문서·매뉴얼·CHANGELOG는 그다음 커밋 | +| RED | 새 통합 테스트 19건 중 17건 실패(성공 Envelope → `SCHEMA_MISMATCH`, 실패 Envelope → `PROBLEM_SCHEMA_INVALID`·결과 불명, 조립이 `unexpected key: responseEnvelope`로 거부). 크기 2건은 처음부터 통과(상한이 이미 본문 전체를 센다, 동작 고정) | +| GREEN | 같은 파일 25건(MSW 시나리오 6행 추가) 통과. `bd83b49`의 진단 4행을 더해 29건 | +| 초기 JS | 202,770 → 203,352 B (+582 B, `7db32e1` +551 B, `bd83b49` +31 B). 남은 여유 1,448 B | +| 게이트 | `bd83b49`에서: `check:types`, `lint`, `check:architecture`, `check:adapter-inventory`, `check:registries`, `check:diagnostics`, `check:ci`, `verify:documentation` 통과. `test:unit` 2,604 / `test:integration` 204 / `test:component` 244 / features·contract 124건 통과. `check:bundle` 203,352 / 204,800 B. `7db32e1` 코드 상태에서: `test:feature-scaffold` 16개 검사(생성한 gateway 테스트 5건 포함), `test:sample-removal` 23개 검사 통과 | + +**남은 것** + +- 참조 기능은 `responseEnvelope`를 선언하지 않는다. 지금도 DTO·problem details fixture로 돈다. 짝 백엔드에 붙이려면 contribution·problem 스키마·`mapProblem`·MSW 본문을 바꿔야 한다. 참조 기능을 Envelope로 옮길지는 결정이 필요하다. +- `tests/e2e/accessibility.spec.ts`는 모든 API에 `[]`로 답한다. 생성한 기능의 라우트는 빈 목록 대신 Envelope 불일치 오류 화면이 검사된다. e2e는 돌리지 않았다. +- 진단(14.4): Envelope operation의 실행기는 백엔드 code를 알게 되어, V2와 같은 멱등성 거절 `reason` 두 값(`IDEMPOTENT_REQUEST_MISMATCH`, `IDEMPOTENCY_KEY_RULE_MISMATCH`)을 싣는다(`bd83b49`, `tests/integration/http-execution-v3-envelope.test.ts`가 V2 기록과 비교). 그 밖의 백엔드 code는 싣지 않는다. 진단 `reason`은 이 repo가 소유한 닫힌 목록(taxonomy)이고, 서버 code를 그대로 넣지 않는다는 `93782b0` 결정을 따른다. code는 실패의 `AppFailure.code`에 남는다. 원 code를 진단에 실으려면 진단 키를 새로 두고(`src/contracts/diagnostics.ts`) projector(`src/bootstrap/runtime-adapters.ts`)를 바꿔야 하며, 그 cardinality 결정이 먼저다. DTO 모드 operation은 여전히 code를 모른다.