docs(architecture): 목표 설계 문서의 V2 상태와 401 문장을 지금 코드에 맞춘다

문제
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
This commit is contained in:
DongHyeonka
2026-11-04 22:39:52 +09:00
parent 5379c805ba
commit ac52a93920
5 changed files with 39 additions and 23 deletions
+1
View File
@@ -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/)
@@ -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
@@ -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를 내는 엔드포인트를
@@ -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
@@ -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: