From f2d2267e2eb4bdeb95403b81c3c76217010e3928 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 03:23:03 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=98=AE=EA=B8=B0=EA=B1=B0=EB=82=98=20?= =?UTF-8?q?=EC=A7=80=EC=9A=B4=20=ED=83=80=EC=9E=85=C2=B7=EC=83=98=ED=94=8C?= =?UTF-8?q?=C2=B7=ED=94=8C=EB=9E=AB=ED=8F=BC=EC=9D=84=20=EA=B0=80=EB=A6=AC?= =?UTF-8?q?=ED=82=A4=EB=8D=98=20=EC=95=88=EB=82=B4=EB=A5=BC=20=EC=A7=80?= =?UTF-8?q?=EA=B8=88=20=EC=9D=B4=EB=A6=84=EC=9C=BC=EB=A1=9C=20=EA=B3=A0?= =?UTF-8?q?=EC=B9=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 모듈 README·AGENTS·매뉴얼·Javadoc이 옮기거나 이름을 바꾼 타입, 지운 샘플, 다른 repo로 옮긴 플랫폼을 그대로 가리켰다. - 옮기거나 바꾼 타입: OutboxConfig(지금 :composition:outbox-relay의 OutboxRelayAutoConfiguration), IdempotencyProviderSelectionConfig(지금 :composition:idempotency의 IdempotencyAutoConfiguration), TracingProperties·GraphQlPlatformProperties(지금 *Settings), SecretSource (지금 application-core SecretSourcePort), JsonNullableModule(지금 JsonNullableJackson3Module), PeriodTest·OutboxEventIdFactory(샘플과 함께 지움). - 지운 샘플: SampleDemoProfilesStartupSystemTest, 「sample 테스트」, IdempotencyAutoConfiguration·ManagementSecurityConfig Javadoc의 샘플. - 옮긴 플랫폼: graphql AGENTS·README가 messaging 플랫폼과 「두 패턴 공존」을 적었지만 그 플랫폼은 2026-11-08 messaging-library로 옮겼다. gRPC 문서는 grpc-library로 옮긴 플랫폼을 「vendored」·「벤더 starter」로 불렀다. - leaf CLAUDE.md를 가리키던 곳(지금 AGENTS.md), 복사한 숫자(httpclient java 파일 수, graphql systemTest 수), manual 06의 registry 머리말 옛 영어 인용. 고른 방법: 문장이 가리키는 대상만 지금 이름으로 바꾼다. 동작 설명은 그대로 둔다. 숫자는 지운다(레지스트리·빌드가 정한다). 검증: - 노트북: check-docs.py rc=0. check-work-docs.py는 main의 operate.md 151줄 때문에만 rc=1. - desktop(--no-build-cache, 트리 310eb524): 이 문서들을 읽는 시험 (:app-bootstrap:documentContractTest, repositoryContractTest — DeveloperExperienceContractTest 포함, MongoNamespaceContractTest, AwsQualificationClaimHonestyTest)과 Javadoc을 고친 두 leaf의 compileJava·spotlessCheck. 134건 실패 0, skip 1. --- docs/build.md | 2 +- docs/manual/06-errors.md | 4 ++-- docs/testing/TESTING_STRATEGY.md | 2 +- docs/websocket/runbook.md | 2 +- docs/work/reference/defect-patterns.md | 4 ++-- src/adapter/inbound/graphql/AGENTS.md | 22 +++++++------------ src/adapter/inbound/graphql/README.md | 13 +++++------ src/adapter/inbound/grpc/AGENTS.md | 4 ++-- src/adapter/inbound/grpc/README.md | 2 +- src/adapter/inbound/web/AGENTS.md | 2 +- src/adapter/inbound/web/README.md | 2 +- .../outbound/persistence-jpa/README.md | 4 ++-- src/application/core/AGENTS.md | 2 +- src/application/core/README.md | 2 +- src/bootstrap/app/README.md | 15 +++++++------ .../IdempotencyAutoConfiguration.java | 2 +- .../security/ManagementSecurityConfig.java | 2 +- 17 files changed, 40 insertions(+), 46 deletions(-) diff --git a/docs/build.md b/docs/build.md index f23d30eb..66083ac2 100644 --- a/docs/build.md +++ b/docs/build.md @@ -410,7 +410,7 @@ app: ### 분산 추적 - **`OTEL_EXPORTER_OTLP_ENDPOINT`** — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel - SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증한다. + SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingSettings` 가 검증한다. - **`APP_TRACING_ENABLED`** — `false` 면 tracing seam 은 꺼지지만, `meta.traceId` 는 `WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성한다(D4 disabled-fallback 보장). - **`APP_TRACING_SAMPLE_RATE`** — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float. diff --git a/docs/manual/06-errors.md b/docs/manual/06-errors.md index febe2b59..cf69867c 100644 --- a/docs/manual/06-errors.md +++ b/docs/manual/06-errors.md @@ -55,8 +55,8 @@ gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로 - 템플릿 운영 코드: `OperationalError` + `docs/registries/error-codes.yaml`을 같은 변경에서 고친다. `ErrorCodeRegistryMappingTest`(app-bootstrap)가 status 일치를 검사한다. -- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 "Product/fork ApiErrorCode enums own local - registries"). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위 +- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 「제품·fork의 ApiErrorCode enum은 자기 레지스트리·계약을 + 가진다」). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위 `ErrorCodeRegistryMappingTest`(`src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ErrorCodeRegistryMappingTest.java`)다. ## 지금 이해하면 되는 것 diff --git a/docs/testing/TESTING_STRATEGY.md b/docs/testing/TESTING_STRATEGY.md index b8a0b20f..af863e27 100644 --- a/docs/testing/TESTING_STRATEGY.md +++ b/docs/testing/TESTING_STRATEGY.md @@ -289,7 +289,7 @@ source set에서 태그 `jpa-contract`로 `jpaPlatformContractTest` lane이 돌 케이스 3건이 실패함을 확인했다. - `OutboxAggregateSequenceContract`는 포트 Javadoc의 세 약속 중 둘을 보지 않았다(RR-01-06). "쓰기 트랜잭션 밖 거부"와 "롤백된 번호는 다시 준다"를 넣었다. fake는 `DirectTransactionPort`를 받으면 같은 - 규칙으로 동작한다(인자 없이 만들면 예전처럼 트랜잭션을 보지 않는다 — sample 테스트가 쓰는 방식). + 규칙으로 동작한다(인자 없이 만들면 예전처럼 트랜잭션을 보지 않는다). `CacheRegionContract`에는 2^53 위 revision 한 자리 차이 경우를 넣었다. fake가 revision을 double로 비교하게 바꾼 변이가 이제 실패한다(전에는 통과). diff --git a/docs/websocket/runbook.md b/docs/websocket/runbook.md index cda6966c..0a6a1e6e 100644 --- a/docs/websocket/runbook.md +++ b/docs/websocket/runbook.md @@ -2,7 +2,7 @@ > **범위:** 내보내는 조립은 WebSocket 런타임을 조립하지 않는다. 이 runbook은 `PlatformWebSocketHandler`를 스스로 등록한 > 서비스에 적용한다(`src/adapter/inbound/websocket/README.md` 「라이브러리 API」). STOMP channel의 규칙은 leaf -> `CLAUDE.md`에 있다. +> `AGENTS.md`에 있다. 무엇을 보았는지로 나눴다. 장애 중에 손에 있는 것이 그것이기 때문이다. diff --git a/docs/work/reference/defect-patterns.md b/docs/work/reference/defect-patterns.md index ab58e17d..4f306a9b 100644 --- a/docs/work/reference/defect-patterns.md +++ b/docs/work/reference/defect-patterns.md @@ -17,7 +17,7 @@ - **모양**: 계약·runbook·매뉴얼·README·Javadoc·실패 메시지가 현재 동작과 다르다. - **막는 기준**: 동작을 바꾸는 변경은 그 동작을 설명하는 모든 문서를 같은 변경에서 고친다. 대상: `docs/web/http-contract.md`, `docs/registries/`, runbook, 매뉴얼, leaf README·`CLAUDE.md`, Javadoc, 업그레이드 안내. 고친 뒤 옛 표현을 grep으로 찾아 남은 곳을 없앤다. -- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/CLAUDE.md`를 grep. +- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/AGENTS.md`를 grep. - **장치**: 일부만 있다. runbook 숫자와 상수를 비교하는 document-contract lane, runbook SQL을 실 PostgreSQL에서 그대로 실행하는 lane. 나머지는 리뷰가 본다. 이 repo는 문서 전체를 파싱하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 8절). ### A3. 선언과 실행이 떨어져 있다 @@ -65,7 +65,7 @@ - **모양**: 프로필·환경 이름 하나가 다르면 위험한 기능이 열린다. 허용한 값으로는 실제로 동작하지 않는다. - **막는 기준**: 위험한 기능(데모 계정, 비밀 검사 면제 등)은 거부 목록이 아니라 허용 목록으로 연다. 허용 목록의 값마다 실제로 그 값으로 동작해야 한다. - **볼 것**: 프로필·환경 이름 문자열 비교, 허용 값마다 실제로 기동하는 테스트가 있는지. -- **장치**: `SampleDemoProfilesStartupSystemTest`(허용 프로필마다 기동). +- **장치**: 기동 때 profile 값을 검사하는 `RuntimeEnvironmentProfileValidator`와 그 시험. 허용 프로필마다 실제로 기동해 보던 시험은 샘플과 함께 지웠다(2026-11-07). ### A10. 글로만 있는 규칙 diff --git a/src/adapter/inbound/graphql/AGENTS.md b/src/adapter/inbound/graphql/AGENTS.md index 608c3e39..7e2f8099 100644 --- a/src/adapter/inbound/graphql/AGENTS.md +++ b/src/adapter/inbound/graphql/AGENTS.md @@ -16,21 +16,15 @@ Package root: `dev.caskeleton.adapter.inbound.graphql`. ## 플랫폼 모듈 = sub-package (Gradle 모듈 아님) GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이 -leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은 +leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 여러 기능 package를 같은 방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성 SSOT(`gradle/modules.json`)까지 밀어올리지 않는다는 선택이다. -**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매 -플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는 -`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간 -낡는다. 즉 이 레포에는 두 패턴이 공존한다: - -| | 방식 | 경계 강제 | -| --- | --- | --- | -| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 | -| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) | - -어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다. +**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하다. 자매 플랫폼 messaging 은 +한때 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 그 플랫폼은 2026-11-08 별도 repo +`messaging-library`로 옮겨 버전으로 받는다(`docs/work/reference/related-repos.md`). 그래서 이 repo 안에는 비교할 다른 +패턴이 없다. GraphQL 내부를 leaf로 나누는 일은 레지스트리에 leaf를 더하는 변경이고, 경계 강제는 지금 +아래 ArchUnit 테스트(전송 경계만)다. sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/` 모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다 @@ -101,7 +95,7 @@ required-class 검사가 이 테스트가 조용히 사라지는 것을 막는 고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부 `testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행 프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다. -- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가 +- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformSettings` 가 `@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티 게이트가 이 선언을 요구한다. @@ -157,7 +151,7 @@ health 스키마만 소유한다. ```bash ./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지 -./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버) +./gradlew :adapter:inbound:graphql:systemTest --console=plain # 실제 HTTP 서버 ``` `graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면 diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index c7db8089..70f606b0 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -127,7 +127,7 @@ gRPC 와 달리 spring-graphql / graphql-java 는 Spring Boot BOM 이 관리한 플랫폼 정책은 `spring.graphql.*` 로 표현할 수 없다 — cost/page 한계, preparsed 캐시 경계, 관측 label 로 허용할 operation 이름은 전부 이 leaf 의 결정이다. 그래서 -`GraphQlPlatformProperties` 가 **`app.graphql`** prefix 로 `@ConfigurationProperties` 를 +`GraphQlPlatformSettings` 가 **`app.graphql`** prefix 로 `@ConfigurationProperties` 를 바인딩한다(`spring.graphql.platform.*` 이 아니다 — 그 prefix 는 존재한 적이 없다). ```yaml @@ -180,16 +180,15 @@ composition root 는 이 leaf 를 채택할 때 인증/인가 및 CORS 정책을 (`gradle/modules.json`)에 추가하는 것은 레지스트리· `settings.gradle` fail-closed 검증·의존 게이트를 동시에 건드리는 변경이다. GraphQL 표면은 하나의 인바운드 전송 경계이므로 그 **내부** 분할을 레포 전역 SSOT 까지 밀어올리지 않기로 하고, -**모듈 = bounded sub-package** 로 매핑했다(선례: httpclient leaf 가 366개 java 파일을 같은 방식으로 +**모듈 = bounded sub-package** 로 매핑했다(선례: httpclient leaf 가 여러 기능 package를 같은 방식으로 담는다). -**정직하게 기록해 둘 반례:** 이후 main 에 통합된 자매 플랫폼 messaging 은 정반대로 -**자기 leaf 를 레지스트리에 하나씩 등록**했다(지금의 leaf 목록과 수는 레지스트리가 정한다). 즉 레지스트리는 닫혀 있지 않았고, -"확장하면 게이트가 깨진다"는 전제는 과했다. 두 플랫폼이 서로 다른 패턴을 쓰고 있으므로 -**어느 쪽으로 통일할지는 미결 아키텍처 결정**이다. +**정직하게 기록해 둘 반례:** 자매 플랫폼 messaging 은 정반대로 **자기 leaf 를 레지스트리에 하나씩 +등록**했다. 즉 레지스트리는 닫혀 있지 않았고, "확장하면 게이트가 깨진다"는 전제는 과했다. 그 플랫폼은 +2026-11-08 별도 repo `messaging-library`로 옮겼으므로 지금 이 repo에서 두 패턴이 공존하지는 않는다. sub-package 경계를 값으로 선언하던 `moduleboundary/` 모델(소스 텍스트 스캐너 포함)은 -2026-09-25 에 삭제했다. 두 플랫폼 중 어느 패턴으로 통일할지 정할 때 다시 설계한다. +2026-09-25 에 삭제했다. GraphQL 내부를 leaf로 나누기로 정할 때 다시 설계한다. ## 전송 경계 규칙은 빌드 때 ArchUnit 으로 검사한다 diff --git a/src/adapter/inbound/grpc/AGENTS.md b/src/adapter/inbound/grpc/AGENTS.md index 0eb3956a..b5e6b947 100644 --- a/src/adapter/inbound/grpc/AGENTS.md +++ b/src/adapter/inbound/grpc/AGENTS.md @@ -42,8 +42,8 @@ Package root: `dev.caskeleton.adapter.inbound.grpc`. 타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다 (모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이 -`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*` -키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`). +`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 `grpc-library` starter를 함께 받은 서비스의 +`app.grpc.platform.*` 키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`). | key | default | 의미 | |---|---|---| diff --git a/src/adapter/inbound/grpc/README.md b/src/adapter/inbound/grpc/README.md index e713d0cf..57b8b82b 100644 --- a/src/adapter/inbound/grpc/README.md +++ b/src/adapter/inbound/grpc/README.md @@ -59,7 +59,7 @@ io.grpc 기본값은 메시지 4 MiB, 연결당 동시 호출 무제한, 호출마다 스레드를 늘리는 cached executor, 서버 deadline 없음, 연결 수명 무제한이다. 어댑터 서버는 이 값을 모두 명시한다. -| 키 (`app.grpc.server.*`) | 기본값 | 같은 값의 출처 (vendored 플랫폼) | +| 키 (`app.grpc.server.*`) | 기본값 | 같은 값의 출처 (`grpc-library` 플랫폼) | |---|---|---| | `max-inbound-message-bytes` | 1048576 (1 MiB) | `GrpcTransportLimits.DEFAULT_MAX_MESSAGE_BYTES` | | `max-inbound-metadata-bytes` | 8192 (8 KiB) | `GrpcTransportLimits.DEFAULT_MAX_METADATA_BYTES` | diff --git a/src/adapter/inbound/web/AGENTS.md b/src/adapter/inbound/web/AGENTS.md index fbc2fd8a..3983047a 100644 --- a/src/adapter/inbound/web/AGENTS.md +++ b/src/adapter/inbound/web/AGENTS.md @@ -136,7 +136,7 @@ B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. |---|---|---|---|---| | 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` | | 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` | -| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 | +| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(생성 명령이 만드는 aggregate의 시험) — 생성자가 유일하고 바뀌지 않는 생성 경로다 | | 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 | - **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은 diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 9173bad1..62439653 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -469,7 +469,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML (/api 없이) 계속 접근 가능하게 유지. ### JacksonNullableConfig -- `JsonNullableModule` 을 Spring 관리 `ObjectMapper` 에 등록. 없으면 PATCH 요청 DTO 의 `JsonNullable`(B2)를 +- `JacksonNullableConfig`가 `JsonNullable` 처리기 모듈(`JsonNullableJackson3Module`)을 Spring 관리 `ObjectMapper` 에 등록. 없으면 PATCH 요청 DTO 의 `JsonNullable`(B2)를 Jackson 이 역직렬화하지 못해 absent / explicit-null 구분이 조용히 붕괴된다. - 스켈레톤 전역 web 관심사(공유 `Patch` 타입과 짝)라 기능 모듈이 아니라 adapter-web 에 위치. diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index 581c36df..403e60e6 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -40,7 +40,7 @@ bean과 함께 Boot의 JDBC·Hibernate·Spring Data JPA·Flyway 자동 설정도 `ModuleDefaultsEnvironmentPostProcessor`가 가장 낮은 우선순위로 읽으므로 애플리케이션 설정과 환경변수가 언제나 이긴다. -outbox **relay**(스케줄러)는 이 모듈이 아니라 합성 루트의 `OutboxConfig`가 조립한다. use case를 +outbox **relay**(스케줄러)는 이 모듈이 아니라 조립 모듈 `:composition:outbox-relay`의 `OutboxRelayAutoConfiguration`이 조립한다. use case를 만들고 구동하는 일은 driven adapter의 몫이 아니기 때문이다. 그 설정은 이 모듈이 주는 `OutboxStorePort`와 messaging이 주는 `OutboxMessagePublishPort`가 모두 있을 때만 켜진다. @@ -217,7 +217,7 @@ Spring Boot 메인 클래스는 `dev.caskeleton.bootstrap` 에 있어서, `@Auto `app.capabilities.idempotency.provider=postgresql` 일 때만 켜진다 (`autoconfigure/PostgreSqlIdempotencyStoreConfig`). 이 leaf 는 `IdempotencyStorePort` 구현 (`PostgreSqlIdempotencyStore`) 하나만 내놓고, executor 는 app-bootstrap -`IdempotencyProviderSelectionConfig` 가 만든다. V1 JDBC store 와 `jdbc` provider 값은 없다. +조립 모듈 `:composition:idempotency`의 `IdempotencyAutoConfiguration`이 만든다. V1 JDBC store 와 `jdbc` provider 값은 없다. - **스키마**: 기본 테이블은 primary Flyway(`db/migration/postgresql/V1__idempotency_record.sql`)가, owner-safe 컬럼은 `db/migration/jpa/idempotency` stream 이 소유한다. 기동 시 diff --git a/src/application/core/AGENTS.md b/src/application/core/AGENTS.md index e321756b..9d5e5859 100644 --- a/src/application/core/AGENTS.md +++ b/src/application/core/AGENTS.md @@ -77,7 +77,7 @@ architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 | 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | `StorePort` | application 패키지 | `*WritePort`(옛 onboarding fixture, 지움) | | aggregate가 아니라 projection을 돌려주는 읽기 모델 | `QueryPort` | application 패키지. projection만 돌려준다(ArchUnit) | — | | 그 밖의 outbound 포트 | `Port` | application 패키지 | — | -| 서버가 정하는 id 생성 | `IdFactory extends IdFactory<Id>` | domain 패키지. id record는 `implements ResourceId` | `OutboxEventIdFactory`(샘플. event id는 resource id가 아니다) | +| 서버가 정하는 id 생성 | `IdFactory extends IdFactory<Id>` | domain 패키지. id record는 `implements ResourceId` | `DurableOperationIdFactory`(durable operation id는 aggregate의 resource id가 아니라 `IdFactory`를 따르지 않는다) | | 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — | | Throwable | `*Exception`, ArchUnit이 강제 | — | — | | 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 | diff --git a/src/application/core/README.md b/src/application/core/README.md index ade67b6d..83132c58 100644 --- a/src/application/core/README.md +++ b/src/application/core/README.md @@ -284,7 +284,7 @@ application 계층이 claim·replay·복구 **정책** 을 소유하고, 저장 `LEASE_EXPIRED` 를 받는다. 이 값은 `NOT_OWNER`(기록이 남에게 넘어감)와 다르다: 시작 전이면 아무것도 돌지 않았고 다음 claim 이 넘겨받으며, executor 는 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거부)로 답한다. 실행 중이면 주인은 여전히 `complete`·`markFailed` 할 수 있다(RR5-01-02). -- 생성은 app-bootstrap `IdempotencyProviderSelectionConfig` 가 한 번 한다(`IdempotencySettings`: +- 생성은 조립 모듈 `:composition:idempotency`의 `IdempotencyAutoConfiguration`이 한 번 한다(`IdempotencySettings`: processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h(replay TTL 이상), codec id `json-v2`, policy revision 2). 유스케이스나 서비스 설정이 직접 만들지 않는다. - 이 계약은 요청 재생(replay) 근거를 남길 뿐이다. store 와 비즈니스 DB 사이의 exactly-once 를 diff --git a/src/bootstrap/app/README.md b/src/bootstrap/app/README.md index f5134be7..0acfa9f7 100644 --- a/src/bootstrap/app/README.md +++ b/src/bootstrap/app/README.md @@ -85,11 +85,12 @@ README의 "startup" 절에 있다. 시크릿을 어디서 읽을지(env / Vault / 클라우드 시크릿 매니저)를 인터페이스 뒤로 숨기고, 위험한 런타임 설정값은 기동 시점에 막는다. -### SecretSource -- **시크릿 해석을 인터페이스 한 겹 뒤로 숨긴 backend seam 이다.** 시크릿이 필요한 코드는 이 - 인터페이스에만 의존하고, 실제 백엔드(env / Vault / AWS Secrets Manager / GCP Secret Manager)는 +### SecretSourcePort +- **시크릿 해석을 인터페이스 한 겹 뒤로 숨긴 backend seam 이다.** 포트는 application-core + `dev.caskeleton.application.secret`에 있다. 시크릿이 필요한 코드는 이 인터페이스에만 의존하고, + 실제 백엔드(env / Vault / AWS Secrets Manager / GCP Secret Manager)는 `SecretSourceFactory`가 설정값으로 고른다. 설정과 구현 선택을 한 factory에 모으는 패턴이다. - 백엔드를 추가하는 비용이 "새 `SecretSource` 구현 1개 + `SecretSourceStrategy` enum 값 1개 + + 백엔드를 추가하는 비용이 "새 `SecretSourcePort` 구현 1개 + `SecretSourceStrategy` enum 값 1개 + factory case 1개"로 고정되고, 소비자(`SecretSourceValidator`, 향후 어댑터)는 전혀 손대지 않는다. - **빈 문자열은 "없음"으로 취급한다.** `resolve`가 blank 값을 `Optional.empty()`로 돌려주지 않으면, "값은 존재하지만 비어 있는" 시크릿이 존재 검사(presence check)를 통과해 버려 prod 부팅을 막을 수 @@ -98,7 +99,7 @@ README의 "startup" 절에 있다. ### SecretSourceStrategy - **enum 값 하나가 곧 백엔드 하나라는 확장 규약을 못 박는다.** `app.secret-source.strategy`로 바인딩되며 `ENVIRONMENT`만 기본 제공한다. 미래 백엔드(VAULT, AWS_SECRETS_MANAGER, - GCP_SECRET_MANAGER)는 주석으로만 남겨 두어, 추가 절차가 "enum 값 + `SecretSource` 구현 + factory + GCP_SECRET_MANAGER)는 주석으로만 남겨 두어, 추가 절차가 "enum 값 + `SecretSourcePort` 구현 + factory case"임을 코드에서 바로 읽히게 했다(rate-limit algorithm enum 패턴과 동일). ### SecretSourceSettings @@ -108,7 +109,7 @@ README의 "startup" 절에 있다. ### SecretSourceConfig - **시크릿 백엔드와 그 시작 가드를 composition root 에서만 와이어링한다.** `SecretSourceFactory`로 - 선택된 `SecretSource`(기본 `ENVIRONMENT`)와, 그것을 통해 필수 시크릿을 검증하는 + 선택된 `SecretSourcePort` 구현(기본 `ENVIRONMENT`)과, 그것을 통해 필수 시크릿을 검증하는 `SecretSourceValidator`를 빈으로 노출한다. 검증기를 Spring 스테레오타입 없는 일반 클래스로 둔 이유는 단위 테스트 가능성을 지키기 위함이고, 이 config 가 유일한 production 와이어링이다. - **`RuntimeSafetyConfig`와 일부러 분리했다.** 시크릿 계약은 secrets-config-source-contract 가 @@ -117,7 +118,7 @@ README의 "startup" 절에 있다. ### SecretSourceFactory - **유일한 확장 지점을 `switch` 하나로 모았다.** 새 백엔드는 `SecretSourceStrategy` 값 + - `SecretSource` 구현 + 이 `switch`의 case 추가로 끝나고 소비자는 바뀌지 않는다. + `SecretSourcePort` 구현 + 이 `switch`의 case 추가로 끝나고 소비자는 바뀌지 않는다. factory 한곳에 "확장 비용이 어디에 있는가"를 보이게 했다. ### EnvironmentSecretSource diff --git a/src/bootstrap/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencyAutoConfiguration.java b/src/bootstrap/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencyAutoConfiguration.java index 1a26e96f..28339218 100644 --- a/src/bootstrap/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencyAutoConfiguration.java +++ b/src/bootstrap/idempotency/src/main/java/dev/caskeleton/composition/idempotency/IdempotencyAutoConfiguration.java @@ -21,7 +21,7 @@ import org.springframework.core.env.Environment; * replay TTL, retention, codec id, policy revision — is the same whichever store holds the records, * so it lives in one {@link IdempotencySettings} record and the executor is built here from it. * Every composition root that serves idempotent requests takes this module rather than a copy of - * it: the application and the sample build the same executor from the same checks. + * it, so every one builds the same executor from the same checks. * *

A selected provider must yield exactly one store. None means the provider's module is not on * the runtime classpath or its switch is off; two means something else registered one (a scan-found diff --git a/src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/management/security/ManagementSecurityConfig.java b/src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/management/security/ManagementSecurityConfig.java index 24551983..1677eb5d 100644 --- a/src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/management/security/ManagementSecurityConfig.java +++ b/src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/management/security/ManagementSecurityConfig.java @@ -32,7 +32,7 @@ import org.springframework.security.web.authentication.HttpStatusEntryPoint; * *

A composition root that deliberately wants another actuator posture declares its own bean * named {@code actuatorSecurityFilterChain}; this one then steps aside instead of putting two - * chains with the same matcher in front of the same requests. The standalone sample does that. + * chains with the same matcher in front of the same requests. */ @AutoConfiguration( before = {