From dcadc0be92decc998a5d7b57a84e0f3a0ad8e591 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 21:38:04 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20V2=20HTTP=20=EA=B2=BD=EB=A1=9C=20?= =?UTF-8?q?=EC=82=AD=EC=A0=9C=EB=A5=BC=20CHANGELOG=EC=99=80=20=EB=A6=AC?= =?UTF-8?q?=EB=B7=B0=20=EA=B8=B0=EB=A1=9D=EC=97=90=20=EC=A0=81=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 048f490(V2 클라이언트 삭제)과 12f3bb7(V2 API 행 삭제)은 공개 이름을 깨는 변경인데 CHANGELOG 미출시 절에 행이 없고, "먼저 할 일" 절의 기능 모양 옮기기 순서가 아직 apiContract(V2 API 필드 네 개)를 만들라고 적는다. 리뷰 README 14.6의 "V2와 남은 차이"도 V2가 있는 것으로 적는다. 고른 방법 - CHANGELOG: [계약] BREAKING 행 둘(지운 이름, 옮기는 법, memento-web 영향)을 더하고, "먼저 할 일" 1·3번을 schemas 하나로 고쳤다. - 리뷰 README 14.7: 사용자 지시, 지우기 전·후 도식, 두 커밋이 지운 것과 바꾼 것, 레지스트리 재승인 digest, 초기 JS 변화, 사라진 V2 전용 동작, 남긴 BoundedPollOperationContract, 다운스트림 영향. 14.6의 차이 절에 지금은 없다고 적었다. 위험·한계 - 다운스트림 동기화 방법은 CHANGELOG의 문장뿐이다. memento-web을 직접 옮겨 보지는 않았다. 검증 - verify:documentation PASS_SCOPED. - tests/unit/changelog-review-ids.test.ts 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7 --- CHANGELOG.md | 9 ++++---- .../2026-11-01-maturity-review/README.md | 23 ++++++++++++++++++- 2 files changed, 27 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ce92cbbc..0b0fe2a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,14 +20,14 @@ `298201f`. 기능 하나가 초기 JS에 약 3.9 KB gzip을 더해서, 참조 모양 기능 하나만 더해도 초기 JS 예산(204,800 B)을 넘었다. 그래서 기능을 두 부분으로 나눴다. - **선언**(`feature-module.ts`, `FeatureModule`): 초기 청크에 남는다. `id`, `contracts`(route 표, route runtime 계약, invalidation, topic version, 새 `contractPackages`), `routes`, `messages`, `loadRuntime`만 가진다. -- **실행부**(`feature-runtime.ts`, `defineFeatureRuntime`): 그 기능의 route에 처음 들어갈 때 router가 `application.features.load(featureId)`로 적재한다. V2 API 계약(`apiOperations`, `schemas`, `runtimeSchemas`, `mappers`), adapter contribution, contract contribution을 가진다. +- **실행부**(`feature-runtime.ts`, `defineFeatureRuntime`): 그 기능의 route에 처음 들어갈 때 router가 `application.features.load(featureId)`로 적재한다. 스키마 메타데이터(`schemas`), adapter contribution, contract contribution을 가진다. HTTP operation은 contract contribution에만 적는다(아래 V2 API 행 삭제 행). - route codec은 `context-routes.ts`의 route handle(`handle.codecs`)에 실려 route와 함께 적재된다. `*-runtime-descriptor.ts`와 `src/features/installed-feature-runtimes.tsx`는 없어졌다. 기존 기능을 옮기는 순서(`src/features/reference-feature/`가 완성된 모양이다): -1. 기능 계약에서 V2 API 필드 네 개(`apiOperations`, `schemas`, `runtimeSchemas`, `mappers`)를 별도 파일로 뺀다. 참조: `contracts/reference-api-contract.ts`의 `REFERENCE_API_CONTRACT`. +1. 기능 계약에서 스키마 메타데이터(`schemas`)를 별도 파일로 뺀다. 참조: `contracts/reference-schema-metadata.ts`의 `REFERENCE_SCHEMA_METADATA`. V2 API 필드(`apiOperations`, `runtimeSchemas`, `mappers`)는 지운다. 2. 선언 계약에 `contractPackages`를 더한다. 그 기능의 `EXTERNAL_PACKAGE` contribution이 고정하는 계약 패키지 identity 목록이다. 없으면 `Object.freeze([])`. 부팅 때 release manifest를 이 목록과 맞춰 본다. 선언하지 않은 패키지를 적재하면 거절한다(`src/features/installed-contract-contributions.ts`). -3. `src/features//feature-runtime.ts`를 만든다. `defineFeatureRuntime({ featureId, apiContract, adapters: [...], contractContributions: [...] })`. 참조: `src/features/reference-feature/feature-runtime.ts`. `featureId`가 모듈 id와 다르면 적재 때 실패한다. +3. `src/features//feature-runtime.ts`를 만든다. `defineFeatureRuntime({ featureId, schemas, adapters: [...], contractContributions: [...] })`. 참조: `src/features/reference-feature/feature-runtime.ts`. `featureId`가 모듈 id와 다르면 적재 때 실패한다. 4. `feature-module.ts`에서 `adapters`, `contractContributions`, `runtimes`(route codec·route runtime)를 지우고 `loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME`을 넣는다. `feature-runtime.ts`를 어디서도 정적으로 import하지 않는다. 그러면 실행부 전체가 다시 초기 청크에 들어간다. 5. route codec을 runtime descriptor에서 `context-routes.ts`의 각 route `handle.codecs`로 옮긴다. 참조: `REFERENCE_FEATURE_ROUTE_CODECS`(`presentation/reference-feature-runtime.ts`). 플랫폼 codec과 같은 id는 쓸 수 없다. 6. 기능 input(`application.features.get(id)`)은 적재 뒤에만 있다. 그 기능의 route 밖에서 읽는 코드는 먼저 `await application.features.load(id)`를 부른다. `ApplicationApi.features`를 직접 구현하거나 fake로 만든 코드는 `load`를 더한다(공개 포트에 추가만 했다). 런타임 설정으로 꺼진 기능은 적재하지 않는다. @@ -75,7 +75,8 @@ | [계약] | 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` | | [계약] | 거절의 적용 여부를 계약 문서 6.1절 표(백엔드 `5786126c` 코드 기준)로 정한다. V2와 V3 Envelope operation이 같은 표(`src/adapters/http/backend-envelope.ts`)를 쓴다. 적용 안 됨은 400 `VALIDATION_FAILED`(details 모양과 상관없음)·400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`뿐이고, 그 밖의 400·409·422는 결과 불명이다. V2에서 `IDEMPOTENT_REQUEST_MISMATCH`가 아닌 422는 이제 결과 불명이라 폼에서 값을 고쳐도 다시 저장할 수 없다. 필드 검증을 422로 보내는 백엔드를 쓰는 프로젝트는 영향을 받는다. 필드 목록 없는 400 `VALIDATION_FAILED`는 바로 다시 저장할 수 있다. V3 Envelope operation의 400·409·422는 `classifyProblem` 대신 이 표가 정한다 (1101/14.4) | `src/adapters/http/backend-envelope.ts`, `src/adapters/http/client.ts`, `src/adapters/http/http-execution-v3.ts` | `3261208` | -| [계약] **BREAKING** | V2 HTTP 클라이언트를 지웠다. HTTP 경로는 V3 실행기 하나다. 배럴(`src/adapters/http/index.ts`)에서 `createHttpClient`, `HttpClient`, `HttpClientDependencies`, `HttpFailure`, `HttpResult`, `LegacyHttpInput`, `Scheduler`, `OperationRequestInput`가, `src/bootstrap/runtime-adapters.ts`에서 `createRuntimeHttpClient`, `RuntimeHttpContract`가 없어졌다. 지운 파일: `client.ts`, `bounded-json.ts`, `request-builder.ts`, `resource-mapper.ts`, `retry-policy.ts`, `schema-registry.ts`(`src/adapters/http/`). Envelope 스키마는 `backend-envelope.ts`로 옮겼다. 템플릿과 tech-log·memento 모두 앱 안에서 V2 클라이언트를 부르는 곳이 없었다. 부르는 코드가 있으면 그 operation의 V3 descriptor를 만들어 `createFeatureHttpBinding`으로 실행한다. 초기 JS 203,354 → 201,598 B | `src/adapters/http/`, `src/bootstrap/runtime-adapters.ts`, `scripts/drill-runbook.ts` | `@@V2CLIENT@@` | +| [계약] **BREAKING** | 기능마다 적던 V2 API 행을 지웠다. HTTP operation은 contract contribution의 descriptor에 한 번만 적는다. FE-REG-API 행은 그 descriptor에서 뽑는다(`src/contracts/api-operations.ts`의 `projectApiOperationRows`: operationId·featureId·method·path·authProfileId·retrySemantics·requestBody·responseBody·responseEnvelope·requestSchema·responseSchema·problemSchema). `FeatureRuntime`은 `apiContract` 대신 `schemas`(FE-REG-SCHEMA 행)를 받는다. 지운 이름: `defineRestOperation`, `ApiOperation`, `RestOperationV2`, `composeApiOperations`, `validateApiRuntimeBindings`, `getApiOperation`, contracts의 `API_OPERATIONS`; `rest-profiles.ts`의 `createRestProviderProfile`, `RestProviderProfile`, `resolveRestSecurityProfiles`, `validateRestProfileBindings`, `REST_CSRF_PROFILES`, `RestCsrfProfile`; `loaded-feature-runtimes.ts`의 `RUNTIME_SCHEMA_CODECS`, `MAPPER_REGISTRY`, `REST_PROFILE_BINDINGS_VALID`, `API_RUNTIME_BINDINGS_VALID`. realtime `apiOperations` 바인딩은 `ApiOperationRow`를 받고, snapshot operation을 `method: "GET"`과 `retrySemantics` `SAFE`·`IDEMPOTENT`로 본다. 레지스트리 기준선을 다시 승인했다. 옮기는 법: `-api-contract.ts`의 `schemas`를 `-schema-metadata.ts`로 옮겨 `defineFeatureRuntime({ schemas })`에 넘기고, `apiOperations`·`runtimeSchemas`·`mappers`와 mapper 레지스트리 행을 지운다. 스키마 메타데이터에 descriptor 입력·응답 검증기의 schemaId가 있어야 한다. memento-frontend의 `memento-web`이 해당한다 | `src/contracts/api-operations.ts`, `src/features/feature-module.ts`, `src/features/installed-feature-runtime-registries.ts`, `config/contracts/`, `scripts/create-feature.ts` | `12f3bb7` | +| [계약] **BREAKING** | V2 HTTP 클라이언트를 지웠다. HTTP 경로는 V3 실행기 하나다. 배럴(`src/adapters/http/index.ts`)에서 `createHttpClient`, `HttpClient`, `HttpClientDependencies`, `HttpFailure`, `HttpResult`, `LegacyHttpInput`, `Scheduler`, `OperationRequestInput`가, `src/bootstrap/runtime-adapters.ts`에서 `createRuntimeHttpClient`, `RuntimeHttpContract`가 없어졌다. 지운 파일: `client.ts`, `bounded-json.ts`, `request-builder.ts`, `resource-mapper.ts`, `retry-policy.ts`, `schema-registry.ts`(`src/adapters/http/`). Envelope 스키마는 `backend-envelope.ts`로 옮겼다. 템플릿과 tech-log·memento 모두 앱 안에서 V2 클라이언트를 부르는 곳이 없었다. 부르는 코드가 있으면 그 operation의 V3 descriptor를 만들어 `createFeatureHttpBinding`으로 실행한다. 초기 JS 203,354 → 201,598 B | `src/adapters/http/`, `src/bootstrap/runtime-adapters.ts`, `scripts/drill-runbook.ts` | `048f490` | | [계약] | V3 descriptor에 선택 필드 `responseEnvelope`가 생겼다. `"ENVELOPE_V1"`이면 V3 실행기가 짝 백엔드 Envelope(`{success, data\|error, meta}`)를 읽는다. `outputValidator`는 `data`(키가 없으면 `null`), `problemValidator`는 `error`를 받는다. 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 적용 여부는 실행기가 V2와 같은 표로 정하고(아래 6.1 표 행), `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` | diff --git a/docs/reviews/2026-11-01-maturity-review/README.md b/docs/reviews/2026-11-01-maturity-review/README.md index 08946263..c19fdf74 100644 --- a/docs/reviews/2026-11-01-maturity-review/README.md +++ b/docs/reviews/2026-11-01-maturity-review/README.md @@ -577,7 +577,7 @@ Envelope operation에서는 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 ef - 버린 대안: (1) V2·V3에 표를 따로 두기: 두 번째 표가 다시 갈라진다. (2) 표 밖 400·409·422를 `classifyProblem`에 맡기기: 6.1절이 "표에 없는 400·409·422는 `MAYBE_APPLIED`"로 정했고, 참조 분류기처럼 400·422를 모두 `NOT_APPLIED`로 보는 패키지가 다음 저장에 새 키를 쓰게 한다. (3) 422를 필드 검증으로 남기기: 짝 백엔드는 필드 검증을 400으로 보내고, fileserver 422는 레코드를 쓴 뒤 던진다. - 위험: 필드 검증을 422로 보내는 다른 백엔드를 V2로 쓰는 프로젝트는 422 뒤에 다시 저장할 수 없게 된다(결과 불명 화면). 프론트 계약 문서 4.2절의 400·422 행을 짝 백엔드 기준으로 고쳤다. -**V2와 남은 차이** (의도한 것): +**V2와 남은 차이** (의도한 것, 14.7에서 V2를 지워 지금은 없다): - 64 KiB보다 크고 `maxResponseBytes` 이하인 실패 Envelope는 V2만 읽는다. V3 problem 상한(scale-architecture.md §7.3)은 올리지 않았다. 짝 백엔드에서 이 크기가 나오는 실패는 bulk 부분 실패뿐이고, 프론트에 bulk 사용처가 없다. - 보낸 KEYED 요청의 503: V2는 같은 키로 자동 재시도하고, V3는 재시도하지 않고 결과 불명으로 화면에 넘긴다(V3 규칙 `canRetryTransport`). effect 판정은 둘 다 `MAYBE_APPLIED`다. @@ -598,3 +598,24 @@ Envelope operation에서는 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 ef - 참조 기능은 `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를 모른다. + +### 14.7 V2 HTTP 경로 삭제 (2026-11-03, 사용자 지시) + +사용자 지시: "V2 V3 이렇게 남기지 말고 최신화된 것 하나만 남겨 놔. 레거시를 코드에 둬서 코드 크기 키우지 말고." 이어서 V2 API 행까지 지우고 레지스트리 기준선을 다시 승인하는 것을 승인했다("둘 다 지워"). + +```text +지우기 전: 기능 하나 = V2 API 행(*-api-contract.ts, 검사용) + V3 descriptor(실행용) + 둘을 맞추는 테스트 + HTTP 실행 = V3 실행기 + 아무도 부르지 않는 V2 클라이언트 +지운 뒤: 기능 하나 = descriptor 하나. FE-REG-API 행은 descriptor에서 뽑는다 + HTTP 실행 = V3 실행기 하나 +``` + +| 커밋 | 지운 것 | 바꾼 것 | +|---|---|---| +| `048f490` | V2 클라이언트와 딸린 파일 6개(`src/adapters/http/client.ts` 등), bootstrap의 `createRuntimeHttpClient`, V2 전용 테스트 7개 | Envelope 스키마는 `backend-envelope.ts`로, V2로 돌던 폼 테스트는 V3 Envelope 계약으로, `drill:runbook` FE-RB-003은 V3 실행기를 실제로 돌려 요청 수를 센다 | +| `12f3bb7` | V2 API 행(`defineRestOperation` 등), 기능의 `runtimeSchemas`·`mappers`, V2 보안 프로필 해석(`resolveRestSecurityProfiles` 등), V2/V3 일치 테스트 | FE-REG-API 행을 descriptor에서 뽑는다(`projectApiOperationRows`). `FeatureRuntime`은 `schemas`만 받는다. realtime snapshot 검사는 뽑은 행을 읽는다. 레지스트리 기준선 재승인(digest `16f72742…`, 승인자 `DongHyeonka`) | + +- 초기 JS: 203,354 → 201,598 B(`048f490`) → 200,911 B. 14.6 시작(202,770 B)보다 1,859 B 작다. +- 사라진 V2 전용 동작: 401 뒤 세션 복구 후 한 번 재전송, 보낸 KEYED 요청의 503 자동 재시도. 14.6의 "V2와 남은 차이"는 비교할 대상이 없어졌다. +- 남긴 것: `src/application/policies/bounded-polling.ts`의 `BoundedPollOperationContract`는 `contractVersion: 2` 필드를 갖지만 realtime polling recipe의 자체 계약이고 V2 HTTP 경로가 아니다. 고치지 않았다. +- 다운스트림: tech-log·memento 모두 V2 클라이언트를 부르지 않는다. memento-frontend의 `memento-web` 기능은 V2 API 행을 쓰므로 동기화 때 CHANGELOG의 옮기는 법을 따른다.