docs: 생성한 기능이 짝 백엔드 Envelope를 읽는다는 결정과 결과를 적는다

문제
매뉴얼 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
This commit is contained in:
DongHyeonka
2026-11-03 20:13:31 +09:00
parent bd83b496cc
commit f3b87b3f02
6 changed files with 96 additions and 31 deletions
+5 -2
View File
@@ -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와 `<main>`은 타입 주석·문서·테스트로만 지킨다. 실행 검사는 없다 (1101/09-03).
- OPFS: lease 밖(FINISH~commit)에서 다른 탭이 같은 partition에 쓰는 경합은 검증하지 않았다 (0929/05-01).
@@ -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
+1 -1
View File
@@ -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` |
+25 -18
View File
@@ -185,31 +185,38 @@ corepack pnpm create:feature invoice-feature
- 패키지 신원 네 필드(`packageId`, `version`, `digest`, `sourceRevision`)는 `<base>-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(`<base>-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 스키마(`<base>-schemas.ts`의 `<base>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/<id>/<base>-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 행의 입력 칸**
+8 -5
View File
@@ -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`로 바꾸면 다음 저장이 새 키를 만든다. 키를 다시 쓰는 것은 결과 불명으로 남은 요청뿐이다(같은 파일). 백엔드가 말한 "같은 키"와 어긋난다.
@@ -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·`<main>`은 실행 검사가 없다. 플랫폼 라우트와 같은 경로의 기능 라우트를 검사하지 않는다.
- 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/<id>/<base>-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를 모른다.