From ac52a93920c7f2e7cf47f19ce3ddcff49a15ec59 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 22:39:52 +0900 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=EB=AA=A9=ED=91=9C=20?= =?UTF-8?q?=EC=84=A4=EA=B3=84=20=EB=AC=B8=EC=84=9C=EC=9D=98=20V2=20?= =?UTF-8?q?=EC=83=81=ED=83=9C=EC=99=80=20401=20=EB=AC=B8=EC=9E=A5=EC=9D=84?= =?UTF-8?q?=20=EC=A7=80=EA=B8=88=20=EC=BD=94=EB=93=9C=EC=97=90=20=EB=A7=9E?= =?UTF-8?q?=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 docs/README.md는 목표 설계 문서의 기능이 지금 동작하는지 문서 안의 상태 값으로 확인하라고 한다. 그런데 2026-11-03에 지운 V2 구성요소가 여전히 COMPOSED다(VD-23 머리, VD-24 머리, api-contract-schema-mapper 원장 세 행). VD-23은 "401 recovery는 replay-safe operation만 한 번 수행한다"를 적는데, 정본 8.4(FRT-D016)와 코드는 숨은 refresh-and-replay를 하지 않는다. 코드 주석 다섯 곳이 이 VD-23을 근거로 가리킨다. 지금 실행 규칙인 6.1절(쓰기 전 거절 표)은 "backend implementation pending"인 목표 설계 문서에 있어 verify:documentation 검사 밖이다. 고른 방법 - VD-23: 정본 우선 안내를 붙이고, V2 baseline을 REMOVED(048f490·12f3bb7)로, V3 contract executor를 COMPOSED로 적는다. 401 문장을 정본 8.4 문장으로 바꾸고, 2절 defineRestOperation 앞에 삭제 안내를 둔다. - VD-24 머리와 api-contract-schema-mapper 원장의 V2 행을 REMOVED로, shared executor 행을 V3 실행기 설명으로 바꾼다. - backend-api-and-server-state-contract.md 상태 줄에 4.1·6·6.1절은 지금 실행 규칙이라고 적고, docs/README.md 1절에서 그 절을 링크한다. 그 결과 이 문서도 경로 검사를 받으므로, 백엔드 repo 경로 7곳에 clean-architecture-backend-template/ 접두어를 붙였다. - 버린 대안: 6.1절을 docs/contracts/로 옮기기. 백엔드 pin·답 표 JSON· backend-envelope.ts 주석이 이 절을 가리켜 같이 고쳐야 할 곳이 늘어난다. 위험·한계 - 원장 행의 나머지 문장과 VD-23 본문에는 V2 시기 서술이 남아 있다. 상태 값과 401 규칙만 맞췄고, 남은 서술은 "V2 기록"이라고 표시했다. 검증 - git grep "401 recovery는 auth-required" -- docs/architecture: 0건. - verify:documentation PASS_SCOPED, documentation-readiness· changelog-review-ids 테스트 통과. Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-03, 03-adapters-http-state.md 03-06 --- docs/README.md | 1 + ...contract-schema-mapper-and-server-state.md | 13 +++++---- .../backend-api-and-server-state-contract.md | 18 ++++++------ ...-transport-selection-and-rest-execution.md | 28 ++++++++++++++----- ...D-24-runtime-schema-and-boundary-mapper.md | 2 +- 5 files changed, 39 insertions(+), 23 deletions(-) diff --git a/docs/README.md b/docs/README.md index 507dd42c..f6c82275 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,6 +32,7 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어 - 새 기능 추가 매뉴얼(작업 순서, 단계별 판단 기준, `create:feature`): [`manual/`](manual/), [`manual/reference/`](manual/reference/). 한국어다 - 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다 - 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md) +- 짝 백엔드 Envelope 판정과 쓰기 전 거절 표(지금 실행 규칙, `src/adapters/http/backend-envelope.ts`의 근거): [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md) 4.1·6·6.1절. 기준 커밋은 [`../config/contracts/backend-contract-pin.json`](../config/contracts/backend-contract-pin.json). 같은 문서의 나머지 절은 목표 설계다 - 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md) - 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md) - 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/) diff --git a/docs/architecture/api-contract-schema-mapper-and-server-state.md b/docs/architecture/api-contract-schema-mapper-and-server-state.md index cf323151..1a874e72 100644 --- a/docs/architecture/api-contract-schema-mapper-and-server-state.md +++ b/docs/architecture/api-contract-schema-mapper-and-server-state.md @@ -81,8 +81,8 @@ PromotionEvidence | capability | primary current status | 현재 증거 | 목표 또는 잔여 | | --- | --- | --- | --- | | installed REST reference vertical | `COMPOSED` | operation registry → request schema → HTTP → envelope/payload schema → mapper → application input → Query 화면 경로 | 아래 REST hardening delta와 실제 제품 provider 계약 | -| shared REST JSON executor | `COMPOSED` | path/search/body codec projection, shared deadline/retry-sleep budget, AbortSignal, bounded auth recovery, exact envelope/media/status, safe failure와 diagnostics | 204/304/412 execution join과 actual provider conformance | -| REST v2 security/execution baseline | `COMPOSED` | collision-aware operation composition, path placeholder↔codec key exact join, prefix-preserving HTTPS/loopback provider, named bearer/CSRF profile와 credential-mode ceiling, auth fail-before-fetch, bounded JSON, outbound correlation/status·physical-attempt 관측 | cookie-CSRF/CORS provider evidence, 204/304/412 conditional execution과 compatibility artifact | +| shared REST JSON executor (V3 contract executor) | `COMPOSED` | `src/adapters/http/http-execution-v3.ts`: descriptor 하나로 실행, shared deadline/retry 예산, AbortSignal, exact media/status, 짝 백엔드 Envelope 판정(`backend-envelope.ts`), safe failure와 diagnostics. 401은 끝이고 숨은 auth recovery는 없다(정본 8.4) | 204/304/412 등 남은 REST hardening delta | +| REST v2 security/execution baseline | `REMOVED` | 2026-11-03 V2 HTTP 경로 삭제(`048f490`·`12f3bb7`). V2 provider·CSRF 프로필 해석도 함께 지웠다 | 지금 경로는 V3 contract executor(아래 행) | | GraphQL provider-neutral reference adapter | `DESIGNED_NOT_IMPLEMENTED` | source/dependency/codegen/runtime 없음 | persisted-operation-only transport, GraphQL response decoder, mapper binding과 contract harness | | product GraphQL composition | `NOT_SELECTED` | endpoint/schema/persisted manifest/owner 없음 | 제품 query가 REST보다 GraphQL aggregation을 정당화할 때 선택 | | GraphQL batching, subscription, `@defer`/`@stream` | `NOT_SELECTED` | 없음 | 각각 독립 ADR, proxy/browser lifecycle과 cache semantics 필요 | @@ -98,7 +98,7 @@ PromotionEvidence | Protobuf REST Gateway reference contract/harness | `DESIGNED_NOT_IMPLEMENTED` | HttpRule/transcoder/OpenAPI/provider fixture 없음 | selected kind의 deterministic/provider conformance | | product Protobuf REST Gateway composition | `NOT_SELECTED` | route/provider/owner 없음 | curated BFF, grpc-gateway 또는 Envoy transcoder 중 하나와 public HTTP contract 승인 | | feature runtime request/response Schema | `COMPOSED` | Zod request/payload schemas와 installed schema registry가 reference feature에 연결 | byte/depth/node ceiling, unknown-field profile, schema artifact/digest와 multi-protocol source governance | -| schema/mapper v2 reference baseline | `COMPOSED` | collision-aware schema codec/mapper contribution install, operation schema/mapper reference resolution, request reject/response strip 방향, bounded collection, typed no-throw mapping result와 operation별 cast-free result guard | actual codec fingerprint, source provenance와 multi-protocol compatibility policy | +| schema/mapper v2 reference baseline | `REMOVED` | 2026-11-03 삭제(`12f3bb7`). schema는 descriptor 검증기와 FE-REG-SCHEMA 행, mapping은 descriptor `mapSuccess`다 | — | | generated contract artifact governance | `DESIGNED_NOT_IMPLEMENTED` | `generated-api` recipe만 있고 generator/provider 선택 없음 | OpenAPI/GraphQL/proto source authentication, pinned generation, drift/breaking gate와 N/N-1 | | feature boundary Mapper | `COMPOSED` | installed mapper metadata composer와 response-schema exact join 뒤 typed no-throw MappingResult → immutable domain/application view 실행 | numeric/date/null/enum canonical rules와 generated-artifact join | | TanStack Query memory Server State | `COMPOSED` | QueryClient, cancellation, stale-degraded UI, session-generation cancel/clear fence와 invalidation coordinator | account identity projection과 bounded topic↔namespace many-to-many registry | @@ -264,9 +264,10 @@ registry validation은 다음을 build/boot 전에 거절한다. Connect/gRPC-Web operation↔provider의 runtime/wire/status/capability tuple mismatch -현재 installed reference operation은 REST v2 metadata를 사용한다. operation, -runtime schema codec과 mapper contribution은 object spread가 아니라 각각의 -collision-aware composer로 설치되며 duplicate ID를 덮어쓰기 전에 거절한다. +현재 installed reference operation은 V3 descriptor 하나로 적는다(REST v2 metadata는 +2026-11-03에 지웠다). contract contribution은 object spread가 아니라 collision-aware +composer로 설치되며 duplicate ID를 덮어쓰기 전에 거절한다. 아래 binding 검증 서술은 +V2 기록이 섞여 있다. 지금 규칙은 `src/contracts/external-contract-runtime.ts`가 정본이다. boot-time binding 검증은 path placeholder와 codec key, provider/auth/CSRF profile, path/request/response schema와 mapper input schema를 exact resolve한 뒤 immutable registry를 발행한다. GraphQL/Connect/gRPC-Web discriminant와 protocol-specific diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index af797905..74d87dd5 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -8,7 +8,7 @@ > 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다. -- 상태: frontend handoff design accepted, backend implementation/evidence pending +- 상태: frontend handoff design accepted, backend implementation/evidence pending. 단 4.1·6·6.1절(Envelope 읽기, effect 판정, 쓰기 전 거절 표)은 지금 실행 규칙이다(`COMPOSED`, `src/adapters/http/backend-envelope.ts`) - 기준일: 2026-07-28 - 대상: Web API/BFF, application service, persistence, identity, GraphQL router, Connect/gRPC-Web gateway, Protobuf REST Gateway와 운영 owner @@ -301,7 +301,7 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 | `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_LOCK_TIMEOUT`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT` (409) | persistence 어댑터가 SQL·JPA 실패를 바꾼 것. 트랜잭션 안이나 commit에서 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FailureCategory.java:86-102`, `StandardSqlStateErrorMapping.java:46-52`, `PersistenceExceptionTranslator.java:133` | | `LOCK_ACQUISITION_TIMEOUT` (409) | 분산 락 대기 초과. use case 안 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `LockRegistryDistributedLock.java:50`, `:53` | | 참조 도메인 `WORKLOG_INVALID`, `POSTER_INVALID_STATE`, `POSTER_IMAGE_REQUIRED` (400), `WORKLOG_CONFLICT`, `POSTER_ALREADY_EXISTS`, `POSTER_IMAGE_ALREADY_PUBLISHED` (409) | application·domain 예외 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `DomainExceptionHandler.java:52-90` | -| 선택 모듈 web-advanced `PATCH_REJECTED` (400), `PATCH_TEST_FAILED` (409) | patch 라이브러리. 부르는 코드가 단계를 정한다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | +| 선택 모듈 web-advanced `PATCH_REJECTED` (400), `PATCH_TEST_FAILED` (409) | patch 라이브러리. 부르는 코드가 단계를 정한다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `clean-architecture-backend-template/src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | | 선택 모듈 fileserver `BAD_REQUEST` (400), `FILE_ALREADY_EXISTS`, `FILE_NOT_READY`, `UPLOAD_OFFSET_MISMATCH`, `CONCURRENT_MODIFICATION` (409), `INTEGRITY_MISMATCH`, `MALWARE_DETECTED`, `INVALID_PATH`, `PATH_OUTSIDE_NAMESPACE` (422) | application·outbound 층. `INTEGRITY_MISMATCH`·`MALWARE_DETECTED`는 레코드를 `REJECTED`로 쓴 뒤 던진다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FileserverErrorCode.java:26-44`, `FinalizeUploadApplicationUseCase.java:211-224`, `:336-341` | - application-notification의 `VALIDATION_FAILED`(`NotificationFailureCode`)는 @@ -314,19 +314,19 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 `IDEMPOTENCY_RECOVERY_REQUIRED`, §4의 503 `REQUEST_TIMEOUT`이다. 실행기가 자동으로 다시 보내는 것은 KEYED 명령의 503 `IDEMPOTENCY_UNAVAILABLE`뿐이다. 나머지는 결과 불명 화면에서 사용자가 같은 키로 다시 보낸다. -- 파일 위치(백엔드 repo 기준): - - `GlobalExceptionHandler.java`, `HttpStatusErrorCodes.java`: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/` +- 파일 위치(백엔드 repo `clean-architecture-backend-template` 기준): + - `GlobalExceptionHandler.java`, `HttpStatusErrorCodes.java`: `clean-architecture-backend-template/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/` - `PageParams.java`, `SortParam.java`: 같은 모듈 `.../web/pagination/` - `IdempotencyKeyHeader.java`: 같은 모듈 `.../web/http/` - - `IdempotencyExecutor.java`: `src/application-core/src/main/java/dev/caskeleton/application/idempotency/` - - `JsonIdempotentResponseCodec.java`: `src/adapter/inbound/web-advanced/.../advanced/idempotency/` + - `IdempotencyExecutor.java`: `clean-architecture-backend-template/src/application-core/src/main/java/dev/caskeleton/application/idempotency/` + - `JsonIdempotentResponseCodec.java`: `clean-architecture-backend-template/src/adapter/inbound/web-advanced/.../advanced/idempotency/` - `FailureCategory.java`, `StandardSqlStateErrorMapping.java`, `PersistenceExceptionTranslator.java`, `LockRegistryDistributedLock.java`: - `src/adapter/outbound/persistence-jpa/` + `clean-architecture-backend-template/src/adapter/outbound/persistence-jpa/` - `PosterImagePublicationController.java`, `WorkLogWebMapper.java`, - `RepoStatsAclMapper.java`, `DomainExceptionHandler.java`: `src/sample-portfolio/` + `RepoStatsAclMapper.java`, `DomainExceptionHandler.java`: `clean-architecture-backend-template/src/sample-portfolio/` - `FileserverErrorCode.java`, `FinalizeUploadApplicationUseCase.java`: - `src/application-fileserver/` + `clean-architecture-backend-template/src/application-fileserver/` **operation이 선언하는 쓰기 전 거절**(1103/03-01): 업무 code는 엔드포인트마다 단계가 달라 위 표에 "쓰기 뒤 가능"으로 둔다. 쓰기 전에만 그 code를 내는 엔드포인트를 diff --git a/docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md b/docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md index 0e1e2fa6..d24ca9a7 100644 --- a/docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md +++ b/docs/architecture/decisions/VD-23-api-transport-selection-and-rest-execution.md @@ -1,9 +1,17 @@ # VD-23: API transport selection과 REST execution -- 상태: Accepted — REST v2 security/execution baseline composed, advanced profiles pending +> **정본 안내 (non-authoritative for runtime capability decisions)** +> +> Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker, +> Service Worker, offline command와 Background Sync의 구현 결정은 +> [프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계](../2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)가 정본이다. +> 본 결정의 해당 서술이 정본과 충돌하면 정본을 따른다. + +- 상태: Accepted — REST v2 실행 경로는 2026-11-03에 지웠다(`048f490`·`12f3bb7`). 지금 REST 실행은 V3 contract executor다. advanced profiles pending - 결정일: 2026-07-28 - installed REST reference vertical: `COMPOSED` -- REST v2 security/execution baseline: `COMPOSED` +- REST v2 security/execution baseline: `REMOVED` (2026-11-03, `048f490`·`12f3bb7`) +- V3 contract executor(descriptor → FE-REG-API 행 투영, 짝 백엔드 Envelope 판정): `COMPOSED` - provider/path/auth profile baseline: `COMPOSED` - conditional execution/provider-conformance delta: `DESIGNED_NOT_IMPLEMENTED` - GraphQL/Connect/gRPC-Web/REST Gateway product selection: `NOT_SELECTED` @@ -23,8 +31,9 @@ TanStack Query까지 실제 production composition에 연결된다. 따라서 RE 현재 reference operation은 v2 metadata, collision-aware composition, allowlisted credential patch, auth fail-before-fetch, prefix-preserving target, shared logical deadline, exact JSON media/success status, bounded decoder와 typed mapping failure를 -실행한다. correlation header, success status group과 401 replay를 포함한 physical -attempt도 terminal observation에 연결한다. +실행한다. correlation header와 success status group을 포함한 physical attempt도 +terminal observation에 연결한다. 401은 끝이다. 숨은 refresh-and-replay는 하지 않는다 +(정본 8.4, FRT-D016). 이 절의 "v2 metadata" 서술은 2026-11-03 V2 삭제 전의 기록이다. operation은 path placeholder↔codec key exact join, named provider/bearer/CSRF profile, provider credential-mode ceiling과 encoded query byte ceiling도 실행한다. @@ -61,6 +70,10 @@ feature use case ### 2. REST operation은 실행 source와 정적 manifest를 분리하지 않는다 +> 2026-11-03: 아래 `defineRestOperation`(V2 행)은 지웠다(`12f3bb7`). 지금 operation은 +> contract contribution의 V3 descriptor 하나로 적고, FE-REG-API 행은 그 descriptor에서 +> 뽑는다(`src/contracts/api-operations.ts`). + 목표 API는 feature가 generic이 연결된 definition을 만든다. ```text @@ -419,9 +432,10 @@ network failure - schema, mapper, 4xx validation/authz/conflict와 redirect failure는 retry하지 않는다. - caller cancel, navigation supersede, runtime teardown, attempt timeout과 logical deadline을 다른 safe failure로 유지한다. -- 401 recovery는 auth-required이면서 replay-safe한 operation만 한 번 수행한다. -- 동시 401은 session owner의 single-flight recovery를 공유한다. -- physical attempt, logical retry와 auth replay를 따로 관측한다. +- 401 response 뒤 숨은 refresh-and-replay를 하지 않는다. command를 새 credential로 + 자동 replay하지 않는다(정본 8.4, FRT-D016). 자격 증명 owner가 보내기 전에 + credential을 준비하고, 401은 그 요청의 끝이다. +- physical attempt와 logical retry를 따로 관측한다. ### 9. Closed execution diff --git a/docs/architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md b/docs/architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md index 39c6f3d4..b32324e7 100644 --- a/docs/architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md +++ b/docs/architecture/decisions/VD-24-runtime-schema-and-boundary-mapper.md @@ -1,6 +1,6 @@ # VD-24: Runtime Schema와 boundary Mapper -- 상태: Accepted — reference typed codec/mapper baseline composed, artifact governance pending +- 상태: Accepted — reference typed codec/mapper baseline은 2026-11-03에 지웠다(`12f3bb7`, `MAPPER_REGISTRY`·`RUNTIME_SCHEMA_CODECS` 삭제). 지금 schema는 V3 descriptor 검증기와 FE-REG-SCHEMA 행, mapping은 descriptor의 `mapSuccess`다. artifact governance pending - 결정일: 2026-07-28 - reference REST Schema/Mapper vertical: `COMPOSED` - semantic compatibility/codegen governance delta: