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:
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user