diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 1bff4f87..08f57e77 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -169,15 +169,7 @@ language src/adapter/outbound/persistence-notification/CLAUDE.md language src/adapter/outbound/redis-sdk/README.md language src/adapter/outbound/redis-sdk/compose/README.md language src/adapter/outbound/support/CLAUDE.md -language src/app-bootstrap/CLAUDE.md language src/app-bootstrap/src/test/resources/developer-experience/broken-readme.md -language src/application-core/CLAUDE.md -language src/build-logic/README.md -language src/composition/outbox-relay/CLAUDE.md -language src/config/architecture/README.md -language src/domain-core/CLAUDE.md -language src/platforms/optional-build/README.md -language src/shared-contract/CLAUDE.md # 참조: 지금 트리·registry에 없는 경로. 고치거나 「> 이력」 인용 블록으로 옮기면 지운다. reference AGENTS.md src/build-tools/ @@ -214,6 +206,3 @@ number src/adapter/outbound/objectstorage/CLAUDE.md Spring Boot 4.0.0 number src/adapter/outbound/persistence-jpa/CLAUDE.md Spring Boot 4.0.0 number src/adapter/outbound/persistence-mongo/CLAUDE.md Spring Boot 4.0.0 number src/adapter/outbound/support/CLAUDE.md Spring Boot 4.0.0 -number src/app-bootstrap/CLAUDE.md Spring Boot 4.0.0 -number src/domain-core/CLAUDE.md Spring Boot 4.0.0 -number src/shared-contract/CLAUDE.md Spring Boot 4.0.0 diff --git a/src/app-bootstrap/CLAUDE.md b/src/app-bootstrap/CLAUDE.md index e12f76f1..3ec72357 100644 --- a/src/app-bootstrap/CLAUDE.md +++ b/src/app-bootstrap/CLAUDE.md @@ -1,125 +1,118 @@ -# app-bootstrap — application entry point & composition root +# app-bootstrap — 애플리케이션 진입점과 조립 루트 -## Registered identity +## 등록 정보 -- Module ID: `app-bootstrap` -- Gradle path: `:app-bootstrap` -- Focused test (derived from Gradle path): `./gradlew :app-bootstrap:test --console=plain` -- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0. -- Registry SSOT: `src/config/architecture/modules.json`. +- 모듈 ID: `app-bootstrap` +- Gradle 경로: `:app-bootstrap` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. -Package root: `dev.caskeleton.bootstrap`. +패키지 루트: `dev.caskeleton.bootstrap`. -## Responsibility +## 책임 -- Spring Boot entrypoint (`CaSkeletonApplication`). -- Runtime settings and logging bootstrap. -- Final cross-module wiring. -- Architecture tests that inspect all modules. +- Spring Boot 진입점(`CaSkeletonApplication`). +- 런타임 설정과 로깅 시작. +- 모듈을 가로지르는 마지막 배선. +- 모든 모듈을 들여다보는 아키텍처 시험. -## Allowed +## 허용 -- Runtime leaves explicitly declared by this module's Gradle dependencies and permitted by the - architecture registry. The resolved Gradle runtime graph is the runtime SSOT; do not duplicate a - membership list in metadata. -- Spring Boot startup/runtime dependencies. -- ArchUnit in tests. +- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle + runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다. +- Spring Boot 시작·런타임 의존성. +- 시험에서 ArchUnit. -## Forbidden +## 금지 -- Concrete business policy. -- Controllers, use cases, repository adapters, or mappers authored directly under bootstrap. -- Settings classes that implement business logic. -- Implementing an `application-core` or `domain-core` port. A class that implements one is an - outbound adapter and belongs in an `adapter/outbound/*` leaf, however its dependencies are - configured — `CompositionRootBoundaryArchitectureTest` enforces this, with no exceptions. -- Raising a startup failure with `throw new IllegalStateException(...)`. Use `StartupFailures` - (`adapter:outbound:support`, package `support.startup`: `envValidation` / `profileMismatch` / - `requiredAdapterDisabled` / `migrationFailed`), so the - failure carries its sysexits exit code and structured log fields — - `StartupFailureContractArchitectureTest` enforces this. -- Answering "is this production?" locally. `dev.caskeleton.shared.runtime.RuntimeEnvironment` owns - the profile vocabulary for the whole repository. -- Depending on `org.testcontainers` from `src/test`. Real-service tests belong to - `src/integrationTest`; see `docs/testing/TESTING_STRATEGY.md`. +- 구체적인 업무 정책. +- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper. +- 업무 로직을 구현하는 설정 클래스. +- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게 + 설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 — + `CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다. +- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures` + (`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` / + `requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그 + 필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다. +- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는 + `dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다. +- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에 + 둔다. `docs/testing/TESTING_STRATEGY.md`를 본다. -## Package layout +## 패키지 배치 -The rules below exist because their absence is what produced the drift this module was reviewed for -(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). Half the -capabilities lived under `autoconfigure/` and half at the package root; `Settings` classes were split -between a `settings/` package and their feature packages with no stated rule; and the same -decomposition problem was solved two different ways in the same leaf — Notification as nine focused -configurations, Redis as one 376-line class. +아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다 +(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/` +아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능 +패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은 +설정 아홉 개로, Redis는 376줄 클래스 하나로. -- **A capability's assembly lives in the capability's own module**, registered by that module's - `AutoConfiguration.imports`, with its settings in the module's `config/module-defaults/*.yml`. - JPA (startup guards, Flyway strategy, lock decorator, readiness and full-off handling in - `JpaActivationEnvironmentPostProcessor`) is `adapter:outbound:persistence-jpa`; Redis (readiness) is - `adapter:outbound:cache-redis`; notification is `composition:notification-platform`. Every - capability is a commented `runtimeOnly` line in `build.gradle`; the default composition is web, - observability, the cores, support and identifier. This leaf keeps no list of capabilities: no - switch registry, no cross-capability dependency validator, no activation endpoint. Component scan - covers `dev.caskeleton.bootstrap` only; web (`WebAdapterAutoConfiguration`, `WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`) and support - (`OutboundSupportConfig`) arrive through their own `AutoConfiguration.imports`. What stays in `autoconfigure//` is application - composition every application needs: `common` (the clock). The outbox relay, the idempotency - executor and the durable operations (use cases and `/operations` endpoints, 07-08) are - `composition:outbox-relay`, `composition:idempotency` and `composition:durable-operation`, selected - by one `runtimeOnly` line each and building nothing until their ports exist. A capability's role→permission mapping ships in its own - `config/module-defaults` file, not in `config/security.yml`. The runtime wiring every composition root needs — - tracing, the metrics contract filters, domain-context propagation, user-principal pseudonymization - (`PrivacySettings`) and the actuator chain — is `composition:service-runtime`. -- **`Settings` lives beside its capability**, not in `settings/`. The `settings/` package - holds only settings that belong to no capability — `BootstrapSettings`, `RuntimeSafetySettings` — - bound strictly with `StrictSettingsBinder`, never scanned. Logging has no settings record: - `logback-spring.xml` reads `app.logging.*` itself and `LoggingConfigurationRule` refuses values - Logback cannot use. -- **`runtime/` holds guards about the application itself** — secrets, numeric bounds, error-detail - exposure, multi-instance coordination, the runtime-profile check (`RuntimeEnvironmentProfileValidator`). - A guard about a capability's settings (the JPA OSIV/DDL/pool/TLS/vendor guards, the Mongo - connection-source rule, the GraphQL deployment-mode rule) ships with that capability's module, so - it exists exactly when the capability does. -- **The startup failure vocabulary lives in `adapter:outbound:support`** (`support.startup`: phases, - error codes, exceptions, `StartupFailures`, `StartupValidationContext`, `StartupOrder`, - `ReadinessGroup`, `RuntimeWarnings`), so capability modules fail the same way without depending on - this leaf. `runtime/startup/` keeps only `StartupFailureExceptionReporter`. -- **An environment-only guard is a `StartupRule` bean** (`support.startup`): it returns violations, - and the one `StartupRuleRunner` raises them before any other singleton exists (declare it with a - `static` `@Bean` method that takes only the `Environment`, the bean factory or an `ObjectProvider` - of static `RequiredProductionSecrets`; in every profile the runner creates each rule and each - `RequiredProductionSecrets` before any rule runs, and fails the boot naming any other bean one of - them creates, and naming any whose runtime class has an `@Value`/`@Autowired`/ - `@Inject`/`@Resource` member, a `@PostConstruct`/`@PreDestroy` callback or a - `@ConfigurationProperties` binding — those are created before the post-processors and would stay - unset). A guard that needs another bean stays a bean. A - capability's production secrets are the capability's: its module contributes a - `RequiredProductionSecrets` bean, and `SecretSourceValidator` checks the names without knowing - which roles exist. +- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가 + 등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략, + lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는 + `adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은 + `composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한 + `runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability + 목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다. + component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`, + `WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support + (`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure//`에 + 남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay, + 멱등성 executor, durable operation(유스케이스와 `/operations` endpoint, 07-08)은 + `composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각 + `runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의 + role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults` + 파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context + 전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다. +- **`Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는 + 어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다. + 이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가 + 없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸 + 수 없는 값을 거절한다. +- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출, + 여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에 + 대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그 + capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다. +- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외, + `StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`). + 그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는 + `StartupFailureExceptionReporter`만 남는다. +- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한 + `StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적 + `RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든 + profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩 + 만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에 + `@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백, + `@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다 + 먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영 + 비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고, + `SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다. -## Decomposition threshold +## 분해 기준 -State it rather than leaving it to taste, because "it felt long enough" is what produced two -different answers for the same question. +취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다. -- One `@Configuration` holds one assembly concern. Split when it passes roughly **eight `@Bean` - methods**, or as soon as it assembles two unrelated port families — whichever comes first. -- One `@ConfigurationProperties` class owns one capability namespace. -- A capability that needs more than one configuration gets a root class holding its `enabled` - condition, `@EnableConfigurationProperties`, and an `@Import` of the per-concern classes. Scan - nothing: `@Import` from a gated root is what keeps `enabled=false` load-bearing rather than advisory. - `cache-redis`'s `capability/RedisCapabilityConfig` is the reference example. Optional adapter - capabilities that own reusable Spring composition publish their own root instead. Notification - uses `adapter:outbound:notification`'s `NotificationPlatformAutoConfiguration` plus - `composition:notification-platform`'s `NotificationApplicationCompositionAutoConfiguration`; JPA uses the - package-private `PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig` and - `startup.JpaStartupAutoConfiguration` from `adapter:outbound:persistence-jpa`, which is not in the - default composition (`// runtimeOnly project(':adapter:outbound:persistence-jpa')` in - `build.gradle`). - Mongo follows the same rule: the persistence-mongo leaf owns MongoRootAutoConfiguration and its internal health bridge; bootstrap owns no Mongo-specific production health configuration. -- Shared helpers of a split capability get their own type named for what they are, not a `*Util` - bucket — `cache-redis`'s `capability/RedisKeys` is the reference. +- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로 + 관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다. +- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다. +- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건, + `@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다: + 조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다. + `cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional + 어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의 + `NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의 + `NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는 + `adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`, + `PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에 + 없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`). + Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health + bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다. +- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 — + `cache-redis`의 `capability/RedisKeys`가 참조 예다. -## Test +## 테스트 ```bash cd src diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java index 508b7d22..137c5a94 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java @@ -31,8 +31,8 @@ class TemplatePackageOwnershipDocumentTest { private static final String RULE_BOOK = "src/application-core/CLAUDE.md"; private static final String REGISTRY = "src/config/architecture/modules.json"; - private static final String APPLICATION_TABLE = "| Package (`dev.caskeleton.application.*`) |"; - private static final String DOMAIN_TABLE = "| Package (`dev.caskeleton.domain.*`) |"; + private static final String APPLICATION_TABLE = "| 패키지 (`dev.caskeleton.application.*`) |"; + private static final String DOMAIN_TABLE = "| 패키지 (`dev.caskeleton.domain.*`) |"; private static final Pattern PACKAGE_NAME = Pattern.compile("`([a-z][a-z0-9]*)`"); private final Path root = RepositoryContractResources.fromSystemProperty().repositoryRoot(); @@ -83,7 +83,7 @@ class TemplatePackageOwnershipDocumentTest { // then assertThat(missing) .as( - "packages %s lists are not in the leaf its \"Owning leaf\" column names; a package was" + "packages %s lists are not in the leaf its \"소유 leaf\" column names; a package was" + " moved or removed without the table (and TemplatePackageOwnership) following it", RULE_BOOK) .isEmpty(); diff --git a/src/application-core/CLAUDE.md b/src/application-core/CLAUDE.md index 0d8b3171..fb6ecce2 100644 --- a/src/application-core/CLAUDE.md +++ b/src/application-core/CLAUDE.md @@ -1,180 +1,173 @@ -# application-core — application use cases +# application-core — 애플리케이션 유스케이스 -## Registered identity +## 등록 정보 -- Module ID: `application-core` -- Gradle path: `:application-core` -- Focused test (derived from Gradle path): `./gradlew :application-core:test --console=plain` -- Runtime baseline: Java 21; repository framework baseline: the Spring Boot 4.x version pinned by the shared version catalog. -- Registry SSOT: `src/config/architecture/modules.json`. +- 모듈 ID: `application-core` +- Gradle 경로: `:application-core` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-core:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(`src/gradle/libs.versions.toml`)가 고정한 Spring Boot 4.x다. +- registry 정본: `src/config/architecture/modules.json`. -Package root: `dev.caskeleton.application`. +패키지 루트: `dev.caskeleton.application`. 코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). -## Responsibility +## 책임 (Responsibility) -- Use case inbound ports (`CommandUseCase`, `QueryUseCase`) and their command / query contracts. -- Outbound ports (`*Port` interfaces) the use cases depend on. -- Application exceptions and policy types. -- Coordinate domain models through ports. -- Own application transaction boundaries through the `TransactionPort` abstraction. -- Expose framework-free invocation context through ports such as `CorrelationIdPort`; adapters own - MDC or other concrete storage. -- Own the framework-free semantic integration-event draft, validated-event value contract and - exact typed payload contribution SPI. This is the messaging semantic contract R1 boundary only. +- 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약. +- 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스). +- 애플리케이션 예외와 정책 타입. +- 포트를 거쳐 도메인 모델을 조율한다. +- `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다. +- `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는 + 어댑터가 가진다. +- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의 + payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다. -## Allowed +## 허용 - `:domain-core` - `:shared-contract` -- Java standard library types. +- Java 표준 라이브러리 타입. -## Forbidden +## 금지 (Forbidden) -- `adapter-*` implementation classes. +- `adapter-*` 구현 클래스. - `app-bootstrap`. -- Controller request/response DTOs. -- JPA entities and Spring Data repositories. -- HTTP status, transport types (`org.springframework.web..`). -- `org.springframework.transaction.annotation.Transactional` (use `TransactionPort` instead). -- `org.springframework.context.ApplicationContext` — direct dependency forbidden - (`getBean(Class)` reflection-style bypass blocked by the ArchUnit rule `application_does_not_depend_on_application_context`). String-key - bean lookup / `Class.forName(String)` / `BeanFactory#getBeansOfType` remain - ArchUnit's static-analysis blind spot — guard via code review checklist. -- Lombok (`lombok..`) — also forbidden in `domain-core`. Within `application-core`, - Lombok is currently not in scope for the contract; if you intend to use it, - weigh the bytecode opacity cost first. -- Persistence-layer transaction annotations of any kind inside this module. -- Diagnostic frameworks (`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). Express - diagnostic intent through a specific outbound `*Port`; adapters own rendering. -- Messaging provider/runtime types: physical topic, Kafka record or metadata, JSON tree/raw JSON - payload, serializer/schema-validator implementation, security topology and publication epoch. +- controller의 요청·응답 DTO. +- JPA 엔티티와 Spring Data repository. +- HTTP 상태, 전송 타입(`org.springframework.web..`). +- `org.springframework.transaction.annotation.Transactional`(대신 `TransactionPort`를 쓴다). +- `org.springframework.context.ApplicationContext` — 직접 의존 금지 + (`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `application_does_not_depend_on_application_context`가 막는다). 문자열 키로 + bean을 찾기, `Class.forName(String)`, `BeanFactory#getBeansOfType`은 ArchUnit 정적 분석이 + 보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다. +- Lombok(`lombok..`) — `domain-core`에서도 금지다. `application-core`에서는 지금 Lombok이 + 계약 범위에 없다. 쓰려면 바이트코드가 불투명해지는 비용을 먼저 따진다. +- 이 모듈 안의 영속 계층 트랜잭션 애너테이션은 종류를 가리지 않고 금지다. +- 진단 프레임워크(`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). 진단 의도는 + 전용 outbound `*Port`로 나타내고, 어떻게 남길지는 어댑터가 정한다. +- 메시징 provider·런타임 타입: 물리 topic, Kafka record나 metadata, JSON tree·raw JSON payload, + serializer·schema validator 구현, 보안 토폴로지, publication epoch. -## Contract types +## 계약 타입 -| Type | Purpose | +| 타입 | 용도 | |---|---| -| `usecase.UseCase` | Base type for inbound ports. Concrete inbound ports MUST extend `CommandUseCase` or `QueryUseCase`. | -| `usecase.CommandUseCase` | Inbound port for write use cases. Implementations MUST be annotated `@UseCaseCapability`. | -| `usecase.QueryUseCase` | Inbound port for read-only use cases. Implementations MUST declare `transactionMode = READ_ONLY` and `repositoryAccess = READ_REPOSITORY`. | -| `command.Command` | Marker for write intents. Plain immutable types built from domain values. | -| `query.Query` | Marker for read intents. Plain immutable types built from domain values. | -| `transaction.TransactionPort` | Outbound port for join-capable write/read, physical root-only write, and independent write boundaries. Implemented by `adapter-persistence`. | -| `secret.SecretSourcePort` | Framework-free outbound secret-resolution seam. Deployment selects a backend in app-bootstrap; concrete environment/cloud/vault readers belong to outbound adapter leaves. | -| `transaction.NestedRootTransactionRejectedException` | Fail-fast signal raised before action/provider side effects when `inRootWrite` detects an actual ambient transaction. | -| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED` and `NEVER` are intentionally absent. | -| `transaction.Isolation` | `READ_COMMITTED` (pinned default) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED` is forbidden (not declared); the vendor default is never used (engine defaults differ — PostgreSQL READ COMMITTED vs MySQL InnoDB REPEATABLE READ). Routing the stricter levels through `TransactionPort` is a `planned` joint change with `feature-application-port-usecase-contract`; the shipped call path pins `READ_COMMITTED`. | -| `capability.UseCaseCapability` | Mandatory annotation on every concrete use case: declares `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`. | +| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | +| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | +| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 inbound 포트. 구현은 반드시 `transactionMode = READ_ONLY`와 `repositoryAccess = READ_REPOSITORY`를 선언한다. | +| `command.Command` | 쓰기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | +| `query.Query` | 읽기 의도의 표지. 도메인 값으로 만든 평범한 불변 타입이다. | +| `transaction.TransactionPort` | 합류할 수 있는 쓰기·읽기, 물리 루트에서만 하는 쓰기, 독립 쓰기 경계를 내놓는 outbound 포트. `adapter:outbound:persistence-jpa`의 `SpringTransaction`이 구현한다. | +| `secret.SecretSourcePort` | 프레임워크 없는 outbound 비밀 해석 이음매. 배포가 app-bootstrap에서 backend를 고른다. 실제 환경 변수·클라우드·vault 리더는 outbound 어댑터 leaf에 둔다. | +| `transaction.NestedRootTransactionRejectedException` | `inRootWrite`가 실제로 열린 바깥 트랜잭션을 찾았을 때, action이나 provider 부작용 전에 바로 던지는 실패 신호. | +| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED`와 `NEVER`는 일부러 없다. | +| `transaction.Isolation` | `READ_COMMITTED`(고정 기본값) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED`는 금지다(선언하지 않았다). vendor 기본값은 쓰지 않는다(엔진마다 기본값이 다르다 — PostgreSQL은 READ COMMITTED, MySQL InnoDB는 REPEATABLE READ). 더 엄격한 수준을 `TransactionPort`로 넘기는 일은 `feature-application-port-usecase-contract`와 함께 바꿀 `planned` 항목이다. 지금 호출 경로는 `READ_COMMITTED`로 고정한다. | +| `capability.UseCaseCapability` | 모든 구체 유스케이스에 반드시 다는 애너테이션: `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`를 선언한다. | | `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. | | `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. | -| `messaging.contract.IntegrationEventContractContribution

` | Closed exact-record payload type, canonical component order, local schema identity/hash and provider-neutral descriptor contribution. | -| `messaging.event.IntegrationEventDraft

` | Typed semantic event before local encoding; never JSON, Kafka or persistence state. Built only through `IntegrationEventDrafts` (`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). | -| `messaging.event.IntegrationEventDrafts` | The one way a feature builds a draft: contract id, version and destination from the contract, correlation from the request when canonical (else the event id), `SINGLE_TENANT_SCOPE` for a feature without tenants. | -| `messaging.event.IntegrationIdentity` | The one grammar and the length bounds of event, correlation/causation and aggregate ids. Test a value with `isCanonical(value, bound)`; never copy the pattern. | -| `messaging.event.ValidatedIntegrationEvent` | Stable semantic identities plus immutable exact encoded bytes and hashes, ready for a later durable append boundary. | -| `messaging.event.IntegrationEventEncoderPort` | Framework-free local draft-to-validated-event boundary implemented by an outbound adapter (the template's: `adapter:outbound:support` `JsonIntegrationEventEncoder`). | -| `outbox.OutboxAppendPort` | The one outbox append: a `ValidatedIntegrationEvent`, in the caller's write transaction. | -| `tenant.TenantId` | The tenant identifier and its one grammar (`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`); the web and GraphQL transport contexts both carry it. Built by a transport from verified authentication data only. | +| `messaging.contract.IntegrationEventContractContribution

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | +| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 semantic 이벤트. JSON·Kafka·영속 상태가 아니다. `IntegrationEventDrafts`로만 만든다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). | +| `messaging.event.IntegrationEventDrafts` | 기능이 초안을 만드는 유일한 길: contract id·version·destination은 contract에서, correlation은 요청 값이 정규형이면 그 값(아니면 event id), 테넌트가 없는 기능은 `SINGLE_TENANT_SCOPE`. | +| `messaging.event.IntegrationIdentity` | event id, correlation·causation id, aggregate id의 유일한 문법과 길이 한계. 값은 `isCanonical(value, bound)`로 시험한다. 패턴을 복사하지 않는다. | +| `messaging.event.ValidatedIntegrationEvent` | 안정된 semantic identity와 바뀌지 않는 정확한 인코딩 바이트·hash. 뒤의 durable append 경계로 넘길 준비가 된 값이다. | +| `messaging.event.IntegrationEventEncoderPort` | 프레임워크 없는 로컬 경계(초안 → 검증된 이벤트). outbound 어댑터가 구현한다(템플릿은 `adapter:outbound:support`의 `JsonIntegrationEventEncoder`). | +| `outbox.OutboxAppendPort` | 유일한 outbox append: `ValidatedIntegrationEvent` 하나를 호출자의 쓰기 트랜잭션 안에서 넣는다. | +| `tenant.TenantId` | 테넌트 식별자와 그 유일한 문법(`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`). web과 GraphQL 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | -## Notification (NOTIF-ADR-005) +## 알림 (NOTIF-ADR-005) -None of the notification types are in this leaf. `..notification.platform..` and the simple -`NotificationPort`, `Notification` and `NotificationChannel` directly under -`dev.caskeleton.application.notification` all belong to leaf `application-notification`; the shared -package prefix is the only link. The R1 orchestration types were removed on 2026-09-25. +알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과 +`dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`, +`NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이 +유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다. -## Naming convention +## 이름 규칙 (Naming convention) -This section is the repository's naming rule book. `NamingConventionTest` (app-bootstrap -architectureTest) enforces the machine-checkable rows; the rest are review rules, and a review checks -them against this table. A new feature follows the "new code" column; the "existing exceptions" are -named so nobody copies them by accident. +이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap +architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」 +열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다. -| Role | Name | Where | Existing exceptions (do not copy) | +| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) | |---|---|---|---| -| Use case (inbound port implementation) | `UseCase`, enforced by ArchUnit | `application` package of the feature | `*ApplicationUseCase` (application-fileserver, application-notification), `*Service` (notification, fileserver) | -| Command / query record | `*Command` / `*Query` | next to its use case | — | -| Aggregate persistence (stores and returns whole aggregates) | `Repository` | **domain** package of the aggregate, owned by the domain | — | -| Technical store the application owns (outbox, idempotency, operation rows) | `StorePort` | application package | `*WritePort` (old onboarding fixture, removed) | -| Read model that returns projections, not aggregates | `QueryPort` | application package; returns projections only (ArchUnit) | — | -| Any other outbound port | `Port` | application package | — | -| Server-assigned id generation | `IdFactory extends IdFactory<Id>` | domain package; the id record `implements ResourceId` | `OutboxEventIdFactory` (sample; event ids are not resource ids) | -| Configuration binding | `*Settings` (operational) or `*Policy` (authorization / domain policy), enforced by ArchUnit | the leaf that binds it | — | -| Throwable | `*Exception`, enforced by ArchUnit | — | — | -| Contract test kit for a port | abstract `Contract` in the port owner's testFixtures; the fake's and each adapter's test extend it | testFixtures | value-type tests were once named `*ContractTest`; they are `*ValueTypesTest` now | +| 유스케이스(inbound 포트 구현) | `UseCase`, ArchUnit이 강제 | 기능의 `application` 패키지 | `*ApplicationUseCase`(application-fileserver, application-notification), `*Service`(notification, fileserver) | +| command·query record | `*Command` / `*Query` | 그 유스케이스 옆 | — | +| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | `Repository` | aggregate의 **domain** 패키지, 도메인이 가진다 | — | +| 애플리케이션이 가진 기술 저장소(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가 아니다) | +| 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — | +| Throwable | `*Exception`, ArchUnit이 강제 | — | — | +| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 | -The one-line rule for stores: **if the domain would recognise the thing it stores, it is a -`Repository` in the domain; if it is plumbing the application needs, it is a `StorePort` in the -application.** +저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에 +필요한 배관이면 application의 `StorePort`다.** -## Package ownership +## 패키지 소유 (Package ownership) -This section is the rule book for **which packages the template owns** and where a business feature -goes. `docs/manual/03-placement.md` points here. +이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. +`docs/manual/03-placement.md`가 이곳을 가리킨다. -- A business feature is `dev.caskeleton.application.` (and `dev.caskeleton.domain.`, - `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`): one package per feature - directly under each root, no `command`/`usecase`/`port` sub-packages. -- `` is **not** one of the template package names below. A feature beside a template - package of the same name lands in the same package tree, and every upstream template update merges - into it. -- Template packages never import a feature package. Business code does not go into a template - package, even when the name fits. -- Everything under the two roots that is not listed here is a feature. A derived service adds - features without editing this list; the template edits it when it adds, renames or removes one of - its own packages. +- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, + `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 + 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. +- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 + 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다. +- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 + 않는다. +- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 + 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다. -| Package (`dev.caskeleton.application.*`) | Owning leaf | Holds | +| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 | |---|---|---| -| `usecase`, `command`, `query` | application-core | inbound port base types and the command/query markers | -| `capability` | application-core | `@UseCaseCapability` and its enums | -| `transaction` | application-core | `TransactionPort` and its modes | -| `security` | application-core | authorization port, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` | +| `usecase`, `command`, `query` | application-core | inbound 포트 기반 타입과 command·query 표지 | +| `capability` | application-core | `@UseCaseCapability`와 그 enum | +| `transaction` | application-core | `TransactionPort`와 그 모드 | +| `security` | application-core | 인가 포트, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` | | `tenant` | application-core | `TenantId` | | `observability` | application-core | `CorrelationIdPort`, `UserPrincipalPseudonymizerPort` | | `secret` | application-core | `SecretSourcePort`, `SecretReference` | -| `messaging` | application-core | the integration-event semantic contract | -| `outbox` | application-core | transactional outbox append and relay | -| `idempotency` | application-core | keyed idempotency executor and store port | -| `operation` | application-core | durable (long-running) operations | -| `lease`, `lock` | application-core | distributed lease and lock ports | -| `cache` | application-core | cache region port | -| `realtime` | application-core | live event replay port | -| `notification` | application-notification | notification capability | -| `fileserver` | application-fileserver | file server capability | -| `objectstorage` | application-objectstorage | object storage capability (its `content.CallBudget` is the call deadline it carries) | +| `messaging` | application-core | integration event semantic contract | +| `outbox` | application-core | 트랜잭션 outbox append와 relay | +| `idempotency` | application-core | 키 기반 멱등성 executor와 store 포트 | +| `operation` | application-core | durable(오래 걸리는) operation | +| `lease`, `lock` | application-core | 분산 lease·lock 포트 | +| `cache` | application-core | cache region 포트 | +| `realtime` | application-core | live event 재생 포트 | +| `notification` | application-notification | 알림 capability | +| `fileserver` | application-fileserver | 파일 서버 capability | +| `objectstorage` | application-objectstorage | 오브젝트 스토리지 capability(`content.CallBudget`은 그것이 싣는 호출 기한이다) | -| Package (`dev.caskeleton.domain.*`) | Owning leaf | Holds | +| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 | |---|---|---| | `identifier` | domain-core | `ResourceId`, `IdFactory` | | `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` | -Enforcement: +강제하는 곳: -- `scripts/new-feature.sh` refuses a feature name that is already a package under any of the five - roots, in any leaf — every template package included. -- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: a feature package - under either root does not take a name from these tables. Every feature has a domain package, so a - feature named `operation` is caught at `dev.caskeleton.domain.operation`. -- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: a feature class written - into a template package keeps the template's name but imports its own domain, and that import is - what fails. -- These tables are the rule book; the machine copy the rules read is `TemplatePackageOwnership` - (app-bootstrap `src/test`, so both the architecture suite and the document-contract lane see it). - `TemplatePackageOwnershipDocumentTest` (document-contract lane, `mainCheck`) fails when the tables - and that class differ in a package name or owning leaf, or when a listed package is not in the - leaf the table names; `TemplatePackageOwnershipRuleTest` (architectureTest) fails when a listed - name exists in no production class. A new template package joins both in the same change. -- Not caught: a new template package that nobody lists. Features are generated into the same leaves - (`scripts/new-feature.sh`), so an unlisted package is indistinguishable from a feature. Listing it - is part of adding it. -- Rejected alternatives: allowing only the listed top-level packages (every derived feature would - have to edit the template's list — a merge conflict per feature), and a separate - `application-platform` leaf for the platform packages (weighed in the 2026-11-01 maturity review: clearer - boundary, but more registry edges than a naming rule needs). +- `scripts/new-feature.sh`는 다섯 루트 중 어디든, 어느 leaf든 이미 패키지로 있는 기능 이름을 + 거절한다. 템플릿 패키지도 모두 여기 걸린다. +- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: 두 루트 아래의 기능 + 패키지는 이 표의 이름을 쓰지 않는다. 기능마다 domain 패키지가 있으므로 `operation`이라는 기능은 + `dev.caskeleton.domain.operation`에서 걸린다. +- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: 템플릿 패키지 안에 쓴 + 기능 클래스는 템플릿 이름을 지니지만 자기 도메인을 import한다. 실패하는 것은 그 import다. +- 이 표가 정본이다. 규칙이 읽는 기계용 사본은 `TemplatePackageOwnership`이다(app-bootstrap + `src/test`에 있어서 architecture suite와 document-contract lane이 모두 본다). + `TemplatePackageOwnershipDocumentTest`(document-contract lane, `mainCheck`)는 표와 그 클래스의 + 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다. + `TemplatePackageOwnershipRuleTest`(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 + 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. +- 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로 + (`scripts/new-feature.sh`) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 + 더하는 일이다. +- 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다 + 병합 충돌이 난다), 플랫폼 패키지용 `application-platform` leaf를 따로 두기(2026-11-01 성숙도 + 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다). -## Canonical use case shape +## 정해진 유스케이스 모양 (Canonical use case shape) ```java @RequiresPermission("user:register") @@ -201,135 +194,127 @@ public class RegisterUserUseCase implements CommandUseCase` / `Runnable` and cannot throw checked -exceptions. This matches Spring's `TransactionCallback` constraint. Wrap domain -checked exceptions into `RuntimeException` subclasses -(`DomainException extends RuntimeException`); `IOException` → `UncheckedIOException`; -`SQLException` is auto-translated by Spring's `DataAccessException` hierarchy. +`TransactionPort` 콜백은 `Supplier` / `Runnable`이라 checked 예외를 던지지 못한다. Spring +`TransactionCallback`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로 +감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로 +감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다. -### `inNew` pool-sizing constraint +### `inNew` 풀 크기 제약 -`inNew` acquires a new physical JDBC connection. Pool size MUST satisfy: +`inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다. ``` hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 ``` -**Forbidden**: calling `tx.inNew(...)` inside a loop over many records — pool -exhaustion + deadlock risk. Batch records inside ONE `inNew` call, or move the -loop outside the transaction boundary. +**금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길 +수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다. -## Idempotency (KEYED) — feature-rate-limit-idempotency-contract +## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract -`@UseCaseCapability(idempotency = Idempotency.KEYED)` is **supported**. A KEYED use case wraps -its work with `dev.caskeleton.application.idempotency.IdempotencyExecutor` — the one owner-safe -generation; the V1 `IdempotencyScope`/`tryBegin` API is gone. +`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 +`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 +유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. -- **Scope**: the caller passes an `IdempotencyScopeDigest` — a versioned HMAC of - principal + client key + operation code, computed before the executor sees it. The raw - `Idempotency-Key` never reaches this layer or the store. -- **Store**: `IdempotencyStorePort`, contributed by exactly one provider selected with - `app.capabilities.idempotency.provider` (`redis` → `cache-redis`, `postgresql` → - `persistence-jpa`; default `disabled`). In-memory prod storage is forbidden. -- **Executor**: built once by `composition:idempotency` `IdempotencyAutoConfiguration` from - `IdempotencySettings` (processing lease 30s, replay TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h and not - shorter than the lease, failure retention 24h and not shorter than the replay TTL). Do not - construct it in a use case or a service's own config. -- The action returns `IdempotentAction.Outcome` (`Success` / `RetryableNoEffect` / - `EffectUnknown`); a thrown exception counts as effect-unknown. In progress → 409 - `IDEMPOTENT_IN_FLIGHT`, fingerprint mismatch (SHA-256) → 422 `IDEMPOTENT_REQUEST_MISMATCH`; - `IdempotencyUnavailableException` and `IdempotencyRecoveryRequiredException` mean the store - could not prove the outcome, so do not blindly retry. -- Every store answers an execution whose processing lease ran out with `RecoveryRequired` and never - takes it over; only a claim that never started or a retryable failure is taken over. The answer - leaves the record to its holder: the holder's first late `complete`/`markFailed` is recorded, a - lease that ran out is not renewed and a claim whose lease ran out is not started — both answer - `LEASE_EXPIRED`, not `NOT_OWNER`, and the executor turns a refused start into "not applied" - (owner decision 2026-11-04). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on - real servers; the in-memory fake models no time, so it runs only the contract's time-free cases. -- Every transition names the operation its record was claimed under (`IdempotencyOwner.claimOperationId()`). - Another one is `OPERATION_CONFLICT` in every store and changes nothing; so is an inspection that - brings the owner token under another operation (owner decision 2026-11-06). -- A transition already applied is confirmed ("already …") only to the handle it was applied from — - the record one revision past it, moved there by that kind of transition. Any other handle is - `NOT_OWNER`, the same attempt's handle from before a takeover included, and so is a start through - the handle a renewal was applied from; a start through a released handle is `ABSENT` or - `NOT_OWNER` by whether the store keeps the released record (owner decision 2026-11-06, +- **범위(scope)**: 호출자가 `IdempotencyScopeDigest`를 넘긴다. principal + client key + operation + code의 버전 있는 HMAC이고, executor가 받기 전에 계산한다. 원본 `Idempotency-Key`는 이 계층에도 + store에도 닿지 않는다. +- **store**: `IdempotencyStorePort`. `app.capabilities.idempotency.provider`로 고른 provider 정확히 + 하나가 내놓는다(`redis` → `cache-redis`, `postgresql` → `persistence-jpa`, 기본값 `disabled`). + 운영에서 메모리 저장소는 금지다. +- **executor**: `composition:idempotency`의 `IdempotencyAutoConfiguration`이 `IdempotencySettings`로 + 한 번 만든다(처리 lease 30s, 재생 TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h이고 lease보다 짧지 않다, 실패 + 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. +- action은 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)을 + 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409 + `IDEMPOTENT_IN_FLIGHT`, fingerprint(SHA-256)가 다르면 422 `IDEMPOTENT_REQUEST_MISMATCH`다. + `IdempotencyUnavailableException`과 `IdempotencyRecoveryRequiredException`은 store가 결과를 + 증명하지 못했다는 뜻이니 무턱대고 다시 시도하지 않는다. +- 모든 store는 처리 lease가 끝난 실행에 `RecoveryRequired`로 답하고 그 실행을 넘겨받지 않는다. + 넘겨받는 것은 시작하지 않은 claim이나 다시 시도할 수 있는 실패뿐이다. 이 답은 레코드를 가진 + 쪽에게 남긴다: 가진 쪽이 늦게 보낸 첫 `complete`/`markFailed`는 기록한다. lease가 끝난 것은 + 갱신하지 않고, lease가 끝난 claim은 시작하지 않는다. 둘 다 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 + 답하고, executor는 거절된 시작을 「적용 안 됨」으로 바꾼다(소유자 결정 2026-11-04). 레코드는 + lease에 재생 TTL을 더한 만큼 산다. `IdempotencyStoreContract`가 Redis와 PostgreSQL을 실제 서버에서 + 둘 모두에 맞춘다. 메모리 fake는 시간을 모델링하지 않으니 계약 중 시간이 없는 경우만 돈다. +- 모든 전이는 그 레코드를 claim한 operation을 이름으로 댄다(`IdempotencyOwner.claimOperationId()`). + 다른 operation이면 모든 store에서 `OPERATION_CONFLICT`이고 아무것도 바꾸지 않는다. owner token을 + 다른 operation으로 가져온 조회도 같다(소유자 결정 2026-11-06). +- 이미 적용된 전이는 그것을 적용한 handle에게만 「already …」로 확인해 준다. 그 handle은 그 전이로 + 옮겨 간, 한 revision 뒤의 레코드다. 다른 handle은 모두 `NOT_OWNER`다. 넘겨받기 전의 같은 시도의 + handle도, 갱신을 적용한 handle로 하는 시작도 그렇다. 놓아준 handle로 하는 시작은 store가 놓아준 + 레코드를 남기느냐에 따라 `ABSENT`나 `NOT_OWNER`다(소유자 결정 2026-11-06, `IdempotencyStoreContract`). -- The applying handle resending `markFailed` with another disposition is `OPERATION_CONFLICT` and - the recorded failure stays; with only another retention it is `ALREADY_MARKED_SAME_OPERATION` and - the first retention stays — retention, like a completion's replay TTL, is not compared (owner - decision 2026-11-07). +- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된 + 실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 — + retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07). -The former ArchUnit freeze rule `inbound_port_implementations_do_not_declare_keyed_idempotency` -and its fixture were removed when this branch merged. +예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는 +이 브랜치가 병합될 때 지웠다. -## Read / query path (feature-application-query-bypass-contract) +## 읽기·query 경로 (feature-application-query-bypass-contract) -The read side has two equally-valid shapes; pick per read, do not force one: +읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다. -| Shape | Returns | When | How | +| 모양 | 돌려주는 것 | 언제 | 어떻게 | |---|---|---|---| -| **Through-aggregate** (default for simple reads) | domain aggregate via a `*Repository` port | read shape == write aggregate **and** the aggregate is the minimal invariant boundary (no lazy collections needed) | `QueryUseCase` → repository port → `Order` | -| **Projection (CQRS-lite)** | application-layer projection DTO via a `*QueryPort` | read shape ≠ write, or to skip aggregate hydration / lazy-collection joins | `QueryUseCase` → `*QueryPort` → `OrderSummary` (record); query via JPQL `SELECT new` / JdbcTemplate | +| **aggregate를 거쳐서**(단순 읽기의 기본) | `*Repository` 포트로 받은 도메인 aggregate | 읽기 모양 == 쓰기 aggregate **이고** aggregate가 최소 불변식 경계일 때(지연 컬렉션이 필요 없음) | `QueryUseCase` → repository 포트 → `Order` | +| **projection (CQRS-lite)** | `*QueryPort`로 받은 애플리케이션 계층 projection DTO | 읽기 모양 ≠ 쓰기, 또는 aggregate 수화·지연 컬렉션 join을 건너뛰려 할 때 | `QueryUseCase` → `*QueryPort` → `OrderSummary`(record). query는 JPQL `SELECT new` / JdbcTemplate | -- **Purity guardrail (core, machine-enforced):** a read port whose simple name ends - with `QueryPort` MUST return application-layer projection DTOs only — never a domain - aggregate, JPA entity, or web type, **including through generic type arguments** - (`List`). Enforced by ArchUnit `query_ports_do_not_leak_domain_jpa_or_web_types`. - Projection usage itself is **opt-in**, not a forced default. -- **Strict ceremony:** every read goes through a `QueryUseCase` bean. There is no thin - web→read-port path — that would bypass the mandatory `@UseCaseCapability` fitness function. -- **Transaction:** reads default to `TransactionPort.inRead`. A no-tx (autocommit) read - is an opt-in only when `spring.jpa.open-in-view=false` is confirmed **and** the read is - projection-only (no lazy access) **and** a single statement; otherwise keep `inRead`. -- **Capability:** a repository-backed projection read is still - `repositoryAccess = READ_REPOSITORY`. "Projection vs aggregate" is the return *shape* axis, - orthogonal to the repository-access *level* axis — no new enum. Outbound-HTTP reads (no - repository) stay `RepositoryAccess.NONE`. -- Full CQRS with a separate physical read store is out of scope — escalation only. +- **순수성 가드레일(core, 기계로 강제):** 단순 이름이 `QueryPort`로 끝나는 읽기 포트는 반드시 + 애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 **제네릭 + 타입 인자를 거쳐서도**(`List`) 안 된다. ArchUnit + `query_ports_do_not_leak_domain_jpa_or_web_types`가 강제한다. projection 사용 자체는 강요된 기본이 + 아니라 **선택**이다. +- **엄격한 절차:** 모든 읽기는 `QueryUseCase` bean을 거친다. web → 읽기 포트로 바로 가는 얇은 + 경로는 없다. 그런 경로는 필수인 `@UseCaseCapability` 적합성 검사를 건너뛴다. +- **트랜잭션:** 읽기의 기본은 `TransactionPort.inRead`다. 트랜잭션 없는(autocommit) 읽기는 + `spring.jpa.open-in-view=false`가 확인됐고 **그리고** 읽기가 projection만 쓰고(지연 접근 없음) + **그리고** 문장 하나일 때만 고를 수 있다. 아니면 `inRead`를 쓴다. +- **capability:** repository를 쓰는 projection 읽기도 `repositoryAccess = READ_REPOSITORY`다. + 「projection이냐 aggregate냐」는 돌려주는 *모양* 축이고, repository 접근 *수준* 축과 따로다 — 새 + enum이 없다. outbound HTTP 읽기(repository 없음)는 `RepositoryAccess.NONE`이다. +- 물리적으로 따로 둔 읽기 저장소를 쓰는 완전한 CQRS는 범위 밖이다. 올려서 정할 일이다. -## ArchUnit guardrails (enforced) +## ArchUnit 가드레일(강제됨) - `application_does_not_depend_on_adapters_or_transport` - `application_does_not_use_spring_transactional_annotation` @@ -337,9 +322,9 @@ The read side has two equally-valid shapes; pick per read, do not force one: - `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK` - `inbound_port_implementations_end_with_use_case` - `inbound_port_implementations_declare_capability` -- `query_ports_do_not_leak_domain_jpa_or_web_types` (`*QueryPort` return purity) +- `query_ports_do_not_leak_domain_jpa_or_web_types`(`*QueryPort` 반환 순수성) -## Test +## 테스트 ```bash cd src @@ -347,5 +332,5 @@ cd src ./gradlew :app-bootstrap:architectureTest ``` -The messaging types above establish semantic contract R1 only. They do not claim JSON Schema -qualification, Kafka publication, durable outbox persistence or any messaging R2 capability. +위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox +영속, 그 밖의 메시징 R2 capability를 주장하지 않는다. diff --git a/src/build-logic/README.md b/src/build-logic/README.md index 279ff8c3..cd9fe39b 100644 --- a/src/build-logic/README.md +++ b/src/build-logic/README.md @@ -1,69 +1,67 @@ # build-logic -The included build that holds this repository's Gradle conventions: the architecture core, the -conventions every leaf applies, and one test-lane mechanism. A check that is about one capability -(notification, Mongo, messaging, GraphQL, JPA) is not here — it is a test in the leaf that owns the -capability, and the files it reads are declared as that test task's inputs. +이 저장소의 Gradle 규약을 담은 included build다: 아키텍처 핵심, 모든 leaf가 적용하는 규약, 시험 lane +장치 하나. capability 하나에 대한 검사(알림, Mongo, 메시징, GraphQL, JPA)는 여기 없다 — 그것은 그 +capability를 가진 leaf의 시험이고, 그 시험이 읽는 파일은 그 시험 태스크의 입력으로 선언한다. -## What is here +## 여기 있는 것 -| Plugin | Owns | +| 플러그인 | 가지는 것 | | --- | --- | -| `ca.architecture-registry` (settings) | project inclusion, directory mapping, and the parsed registry every other reader shares | -| `ca.architecture` | `verifyCleanArchitectureDependencies` (per-module direction), `verifyApplicationCoreDependencyPurity` (domain-core, shared-contract, application-*), `verifyNoIgnoredSourcePackages`, `architectureCheck` | -| `ca.java-conventions` | Java toolchain/compiler baseline, dependency locking, the Mockito test agent, the per-leaf `mainCheck` lifecycle, the leaf version (release version only) and `sourceRevision` (`JavaConventionsPlugin.sourceRevision`, also what the root `verifyReleaseProvenance` checks) | -| `ca.quality-conventions` | Spotless, Checkstyle, Error Prone, SpotBugs/FindSecBugs wiring shared by Java leaves | -| `ca.java-library` / `ca.spring-library` / `ca.spring-config` | leaf-level composition of the Java/quality conventions for plain and Spring libraries | -| `ca.platform-module` / `ca.grpc-platform-module` | what a vendored platform leaf (`messaging:*`, `grpc:*`, `grpc-advanced:*`) is: `java-library`, plus the gRPC BOM for the leaves that had it | -| `ca.strict-test-lane` | the one "named tests ran, none skipped" mechanism: tagged / named / own-source-set `Test` lanes that fail when they execute nothing, miss a `requires` class, or (with `rejectSkipped`) skip anything. A `performance()` lane always rejects skips and runs with `performance.assertions.enabled=true`; a build (`-P`, `GRADLE_OPTS`) or lane that sets another value fails it before a test runs. `mainStage()` moves a tagged lane out of `test` into the leaf's `mainCheck`; `explicitOnly(reason)` keeps a lane that needs an outside input out of every aggregate, and the aggregate prints the reason. Extra test source sets are Gradle `jvm-test-suite` suites declared in the leaf (`testing { suites { … } }`); a lane named after its suite makes the suite's own `Test` task strict, and `ca.java-conventions` gives every suite the BOM's JUnit | -| `ca.strict-lane-stages` (root of each build with strict lanes: the main build and optional-platforms) | the other half of the lane mechanism: `verifyStrictLaneStages --dry-run` fails when a strict lane of that build that is not `explicitOnly` is in the task plan of no declared stage that a workflow executes, or when a declared stage is executed by no workflow. The workflows are read together (`WorkflowGradleInvocations.readAll`, so a reusable workflow is judged by its callers) and their `run:` scripts parsed as bash (`ShellScript`: quotes, comments, heredoc bodies, substitutions and compound commands are read as the shell reads them, so a `cd` in a heredoc or a string is data). A command does not count when Gradle runs no task with it — `--dry-run`/`-m` (also in a bundle such as `-qm`), `-v`/`--version`, `-h`/`-?`/`--help`, `--status`, `--stop`, `--foreground` (also in a bundle such as `-qv`) — or rejects it: a short-option bundle whose later letter takes a value (`-mx`: only the first letter of a bundle takes one), or a value given to an option that takes none (`-m=yes`). The reader follows Gradle 9.0's parser. `GradleCommandLineTest` holds its option tables to the `--help` of the Gradle that runs build-logic — an upgrade that adds an option, as 9.2 adds `--task-graph`, fails until the option is placed — and runs the launcher with each no-task option but `--stop` and `--foreground` (both return a daemon action, not a build, in Gradle's `BuildActionsFactory`); which options take a value was probed against 9.0.0 in round 9 and is not re-run. Nor does a command for another build count (the build a command starts is its step's `working-directory`, or the job's or workflow's `defaults.run.working-directory`, moved by each `cd ` the same `run:` shell surely ran before it — alone in its list, or before the command in the same `&&` list — then joined with `-p`; the plugin reads this build's own directory from where it sits under the repository that holds `.github/workflows`). Every other command that does not count gives one of three reasons. **Its failure may not fail its step**: `\|\| true`, `\|\| :` or any `\|\|` but `\|\| exit `, a pipe's left side without `pipefail` (on with `shell: bash` or a top-level `set -o pipefail`), `!`, `&`, an `if`/`while` condition, the part before `&&` of a list that is not the script's last command, after `set +e`, after a `trap` whose `EXIT` or `ERR` action may `exit` with status 0 (a bare `exit` keeps the status in an `EXIT` trap, not in an `ERR` one), and `continue-on-error`. **It may not run**: after `\|\|`, after `&&` in a list that is not the script's last command, inside `if`/`while`/`for`/`case` or a function body, after a top-level `exit`, `exec ` or `set -n`, after one elsewhere — in a compound command, an and-or list or a function the script calls — that may end the script with status 0 (`exit 0`, a bare `exit` other than right after `\|\|`, `exit "$code"`), replace it or stop it running commands (`set -o noexec`), under an `if:` other than `always()`/`success()`/`!cancelled()`, in a workflow that starts only on events someone or something asks for (`workflow_dispatch`, `repository_dispatch`, `issue_comment`, a pull request with `types: [labeled]`, `workflow_run`, …; `push`, `pull_request`, `pull_request_target`, `merge_group`, `schedule` and `release` count), in a workflow whose change-flow triggers all carry a `paths` or `paths-ignore` filter (a change outside those paths does not start it; owner decision 2026-11-06), for any stage but `:releaseCheck` in a workflow that starts without a request or a path filter only on the release flow — `release`, or a `push` with `tags`/`tags-ignore` and no `branches`/`branches-ignore`, which a branch push does not start (owner decision 2026-11-07; `:releaseCheck` is the tag-only stage) — in a reusable (`workflow_call`-only) workflow that no counted job calls with `uses: ./.github/workflows/`, and in a job that `needs`, directly or through other jobs, a job with such an `if:` or with `continue-on-error`, unless its own `if:` is `always()` or `!cancelled()`. **This check does not read it**, although its failure would fail the step (a false failure on purpose): `\|\| exit 1`, `\|\| { …; exit 1; }`, inside `{ }` or `( )`, `$( )`, `bash -c`, `gradlew` as another command's argument (`timeout 60 ./gradlew`), after a directory change the reader does not follow (`cd "$VAR"`, `cd -`, `cd ~`, an absolute path, `pushd`/`popd`, `builtin cd`, `eval`/`source`, a `cd` anywhere inside a compound command or a function body, one joined with `\|\|`, piped or in the background, and the lines after a `cd` that shares an `&&` list with other commands — not guessed), a step whose `shell:` is not `bash` or `sh`, and a step with no `shell:` in a job whose `runs-on` may be a Windows runner, whose default shell is `pwsh` (a Windows label, an expression such as `${{ matrix.os }}`, a self-hosted label set without `linux` or `macos`; Linux and macOS runners default to `bash -e` and a `container:` job to `sh -e`, which are read alike). An `exit` that fails the step — `exit 1`, or `cmd \|\| exit` — and one in an uncalled function, a `( )` subshell or `$( )` stop nothing after them from counting. The failure names every command that names the stage but does not execute it, with its reason or the other build it starts, and says to run the stage as `./gradlew` on a line of its own. A lane the command removes with `-x` is not covered — matched the way Gradle matches task and project names, abbreviations included (`TaskSelectors`, a copy of Gradle's internal `NameMatcher`). A `run:` input of a `uses:` step is not a command. The plan is Gradle's own; the workflows are read for their `run:` steps with YAML folding applied (review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, owner decision 2026-11-04 on `cd`, RR5-02-01/02/03 in round 9, 2026-11-05 RR6-04-01..06, 2026-11-06 RR7-05-01, owner decision 2026-11-07 on the release flow) | -| `ca.redis-topology-lane` | the Redis topology lane (mode selection, `-P` property validation, per-mode required classes) the redis-sdk-topology workflow drives | -| `ca.api-surface` | read-only public API surface verification with a separate update task, wired into the leaf's `check` (owner decision 20); optionally holds other leaves' imports to a reviewed adopter subset (`adopterBaseline`) | -| `ca.config-contract` | app-bootstrap's `verifyEnvKeys` (moved from the deleted build-tools included build; owner decision 4 keeps the task in app-bootstrap) | -| `ca.bootrun-dotenv` | `bootRun`'s `.env` | +| `ca.architecture-registry` (settings) | 프로젝트 포함, 디렉터리 대응, 다른 모든 읽는 쪽이 같이 쓰는 파싱된 registry | +| `ca.architecture` | `verifyCleanArchitectureDependencies`(모듈별 방향), `verifyApplicationCoreDependencyPurity`(domain-core, shared-contract, application-*), `verifyNoIgnoredSourcePackages`, `architectureCheck` | +| `ca.java-conventions` | Java toolchain·컴파일러 기준, 의존성 잠금, Mockito 시험 agent, leaf별 `mainCheck` lifecycle, leaf 버전(릴리스 버전만)과 `sourceRevision`(`JavaConventionsPlugin.sourceRevision`. 루트 `verifyReleaseProvenance`가 검사하는 것도 이것이다) | +| `ca.quality-conventions` | Java leaf가 같이 쓰는 Spotless, Checkstyle, Error Prone, SpotBugs·FindSecBugs 배선 | +| `ca.java-library` / `ca.spring-library` / `ca.spring-config` | 평범한 라이브러리와 Spring 라이브러리를 위한 Java·품질 규약의 leaf 단위 조합 | +| `ca.platform-module` / `ca.grpc-platform-module` | 들여온 플랫폼 leaf(`messaging:*`, `grpc:*`, `grpc-advanced:*`)가 무엇인가: `java-library`, 그리고 원래 gRPC BOM을 쓰던 leaf에는 그 BOM | +| `ca.strict-test-lane` | 「이름 댄 시험이 돌았고 건너뛴 것이 없다」를 보는 유일한 장치: tag·이름·자기 source set으로 고른 `Test` lane이 아무것도 실행하지 않거나, `requires` 클래스를 빠뜨리거나, (`rejectSkipped`이면) 무엇이든 건너뛰면 실패한다. `performance()` lane은 언제나 건너뛰기를 거절하고 `performance.assertions.enabled=true`로 돈다. 빌드(`-P`, `GRADLE_OPTS`)나 lane이 다른 값을 넣으면 시험이 돌기 전에 실패한다. `mainStage()`는 tag로 고른 lane을 `test`에서 빼 leaf의 `mainCheck`로 옮긴다. `explicitOnly(reason)`는 바깥 입력이 필요한 lane을 모든 묶음 태스크에서 빼고, 묶음 태스크가 그 이유를 출력한다. 시험 source set을 더 두려면 leaf에 Gradle `jvm-test-suite` suite로 선언한다(`testing { suites { … } }`). suite 이름을 딴 lane은 그 suite 자신의 `Test` 태스크를 엄격하게 만들고, `ca.java-conventions`는 모든 suite에 BOM의 JUnit을 준다 | +| `ca.strict-lane-stages` (strict lane이 있는 각 빌드의 루트: 주 빌드와 optional-platforms) | lane 장치의 나머지 절반: `verifyStrictLaneStages --dry-run`은 그 빌드의 `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 선언된 단계 어느 것의 태스크 계획에도 없거나, 선언된 단계를 실행하는 workflow가 없으면 실패한다. workflow는 함께 읽고(`WorkflowGradleInvocations.readAll`. 그래서 재사용 workflow는 그것을 부르는 쪽으로 판정한다) `run:` 스크립트는 bash로 파싱한다(`ShellScript`: 따옴표, 주석, heredoc 본문, 치환, 복합 명령을 셸이 읽듯 읽는다. 그래서 heredoc이나 문자열 안의 `cd`는 데이터다). Gradle이 태스크를 하나도 돌리지 않는 명령은 세지 않는다 — `--dry-run`/`-m`(`-qm` 같은 묶음 안도), `-v`/`--version`, `-h`/`-?`/`--help`, `--status`, `--stop`, `--foreground`(`-qv` 같은 묶음 안도) — Gradle이 거절하는 명령도 세지 않는다: 뒤 글자가 값을 받는 짧은 옵션 묶음(`-mx`: 묶음에서는 첫 글자만 값을 받는다), 값을 받지 않는 옵션에 준 값(`-m=yes`). 읽는 방식은 Gradle 9.0의 파서를 따른다. `GradleCommandLineTest`는 옵션 표를 build-logic을 돌리는 Gradle의 `--help`와 맞춘다 — 옵션을 더하는 업그레이드는(9.2가 `--task-graph`를 더하듯) 그 옵션을 자리에 넣기 전까지 실패한다 — 그리고 `--stop`과 `--foreground`를 뺀 태스크 없는 옵션마다 launcher를 돌린다(둘은 Gradle `BuildActionsFactory`에서 빌드가 아니라 daemon 동작을 돌려준다). 어떤 옵션이 값을 받는지는 round 9에 9.0.0으로 탐침했고 다시 돌리지 않는다. 다른 빌드를 위한 명령도 세지 않는다(명령이 시작하는 빌드는 그 step의 `working-directory`, 또는 job이나 workflow의 `defaults.run.working-directory`에서 시작해, 같은 `run:` 셸이 그 앞에서 반드시 돌린 `cd <리터럴 상대 경로>`마다 옮기고 — 혼자 있는 목록이거나 같은 `&&` 목록에서 그 명령 앞에 있을 때 — 그다음 `-p`로 이은 곳이다. 플러그인은 이 빌드 자신의 디렉터리를 `.github/workflows`를 가진 저장소 아래 어디에 있는지로 읽는다). 세지 않는 그 밖의 명령은 모두 세 이유 중 하나를 댄다. **실패해도 step이 실패하지 않을 수 있다**: `\|\| true`, `\|\| :`, `\|\| exit <0 아닌 값>`이 아닌 모든 `\|\|`, `pipefail` 없는 pipe의 왼쪽(`shell: bash`나 최상위 `set -o pipefail`이면 켜진다), `!`, `&`, `if`/`while` 조건, 스크립트의 마지막 명령이 아닌 목록에서 `&&` 앞부분, `set +e` 뒤, `EXIT`나 `ERR` 동작이 상태 0으로 `exit`할 수 있는 `trap` 뒤(`EXIT` trap 안의 맨 `exit`는 상태를 지키지만 `ERR` trap 안에서는 아니다), `continue-on-error`. **돌지 않을 수 있다**: `\|\|` 뒤, 스크립트의 마지막 명령이 아닌 목록에서 `&&` 뒤, `if`/`while`/`for`/`case` 안이나 함수 본문 안, 최상위 `exit`·`exec `·`set -n` 뒤, 다른 곳 — 복합 명령, and-or 목록, 스크립트가 부르는 함수 — 에서 스크립트를 상태 0으로 끝낼 수 있는 것(`exit 0`, `\|\|` 바로 뒤가 아닌 맨 `exit`, `exit "$code"`), 스크립트를 바꿔치는 것, 명령 실행을 멈추는 것(`set -o noexec`) 뒤, `always()`/`success()`/`!cancelled()`가 아닌 `if:` 아래, 누가 또는 무엇이 요청해야만 시작하는 이벤트(`workflow_dispatch`, `repository_dispatch`, `issue_comment`, `types: [labeled]`인 pull request, `workflow_run`, …. `push`, `pull_request`, `pull_request_target`, `merge_group`, `schedule`, `release`는 센다)로만 시작하는 workflow 안, 변경 흐름 트리거가 모두 `paths`나 `paths-ignore` 필터를 가진 workflow 안(그 경로 밖의 변경은 workflow를 시작하지 않는다. 소유자 결정 2026-11-06), 요청이나 경로 필터 없이 릴리스 흐름에서만 시작하는 workflow 안의 `:releaseCheck`가 아닌 단계 — 릴리스 흐름은 `release`, 또는 `tags`/`tags-ignore`가 있고 `branches`/`branches-ignore`가 없는 `push`로, 브랜치 push로는 시작하지 않는다(소유자 결정 2026-11-07. `:releaseCheck`가 태그 전용 단계다) — 센 job 어느 것도 `uses: ./.github/workflows/`로 부르지 않는 재사용(`workflow_call`만 있는) workflow 안, 그리고 그런 `if:`나 `continue-on-error`를 가진 job을 직접 또는 다른 job을 거쳐 `needs`하는 job 안(자기 `if:`가 `always()`나 `!cancelled()`이면 예외). **이 검사가 읽지 않는다**(실패하면 step이 실패하지만, 일부러 거짓 실패로 둔다): `\|\| exit 1`, `\|\| { …; exit 1; }`, `{ }`나 `( )` 안, `$( )`, `bash -c`, 다른 명령의 인자인 `gradlew`(`timeout 60 ./gradlew`), 읽는 쪽이 따라가지 않는 디렉터리 이동 뒤(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`/`popd`, `builtin cd`, `eval`/`source`, 복합 명령이나 함수 본문 안의 `cd`, `\|\|`로 이은 것, pipe나 background로 돌린 것, 다른 명령과 같은 `&&` 목록에 있는 `cd`의 뒤 줄 — 짐작하지 않는다), `shell:`이 `bash`나 `sh`가 아닌 step, `runs-on`이 Windows runner일 수 있는 job에서 `shell:`이 없는 step(기본 셸이 `pwsh`다. Windows label, `${{ matrix.os }}` 같은 표현식, `linux`나 `macos`가 없는 self-hosted label 집합. Linux·macOS runner의 기본은 `bash -e`, `container:` job의 기본은 `sh -e`이고 둘을 같이 읽는다). step을 실패시키는 `exit` — `exit 1`, `cmd \|\| exit` — 와 부르지 않는 함수, `( )` subshell, `$( )` 안의 `exit`는 그 뒤의 명령이 세지는 것을 막지 않는다. 실패 메시지는 단계 이름을 대지만 그 단계를 실행하지 않는 모든 명령을 그 이유나 그것이 시작하는 다른 빌드와 함께 대고, 단계를 혼자 있는 줄의 `./gradlew`로 돌리라고 말한다. 명령이 `-x`로 뺀 lane은 덮인 것이 아니다 — Gradle이 태스크·프로젝트 이름을 맞추는 방식(약어 포함)으로 맞춘다(`TaskSelectors`, Gradle 내부 `NameMatcher`의 사본). `uses:` step의 `run:` 입력은 명령이 아니다. 계획은 Gradle 자신의 것이다. workflow는 YAML folding을 적용해 `run:` step을 읽는다(review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, `cd`에 대한 소유자 결정 2026-11-04, round 9의 RR5-02-01/02/03, 2026-11-05 RR6-04-01..06, 2026-11-06 RR7-05-01, 릴리스 흐름에 대한 소유자 결정 2026-11-07) | +| `ca.redis-topology-lane` | redis-sdk-topology workflow가 돌리는 Redis topology lane(모드 고르기, `-P` 속성 검증, 모드별 필수 클래스) | +| `ca.api-surface` | 읽기 전용 공개 API surface 검증과 따로 둔 갱신 태스크. leaf의 `check`에 배선한다(소유자 결정 20). 다른 leaf의 import를 리뷰한 adopter 부분집합(`adopterBaseline`)에 묶을 수도 있다 | +| `ca.config-contract` | app-bootstrap의 `verifyEnvKeys`(지운 build-tools included build에서 옮겼다. 소유자 결정 4가 그 태스크를 app-bootstrap에 둔다) | +| `ca.bootrun-dotenv` | `bootRun`의 `.env` | -Plain classes rather than plugins, because settings and projects load plugins through different -mechanisms and more than one caller needs each: +플러그인이 아니라 평범한 클래스로 둔 것. settings와 project는 플러그인을 서로 다른 방식으로 읽어 +들이고, 각각을 부르는 쪽이 둘 이상이기 때문이다: -| Class | Owns | +| 클래스 | 가지는 것 | | --- | --- | -| `dev.caskeleton.buildlogic.ModuleRegistry` | reading and validating `config/architecture/modules.json` | -| `dev.caskeleton.buildlogic.RequiredTestExecution` | the single decision "a test this build names must actually have run" | -| `dev.caskeleton.buildlogic.JavaPublicTypes` | public top-level types, parsed by javac rather than matched with a regular expression | +| `dev.caskeleton.buildlogic.ModuleRegistry` | `config/architecture/modules.json`을 읽고 검증하기 | +| `dev.caskeleton.buildlogic.RequiredTestExecution` | 「이 빌드가 이름을 댄 시험은 실제로 돌았어야 한다」는 단 하나의 판정 | +| `dev.caskeleton.buildlogic.JavaPublicTypes` | 공개 최상위 타입. 정규식으로 맞추지 않고 javac로 파싱한다 | -JMH benchmarks use the community `me.champeau.jmh` plugin; `ca.quality-conventions` only turns -Error Prone, `-Werror`, SpotBugs and Checkstyle off for benchmark and generated code. +JMH benchmark는 커뮤니티 플러그인 `me.champeau.jmh`를 쓴다. `ca.quality-conventions`는 benchmark와 +생성된 코드에서 Error Prone, `-Werror`, SpotBugs, Checkstyle을 끄기만 한다. -## What was removed, and what covers it +## 지운 것과 그것을 대신하는 것 -| Removed | Covered by | +| 지운 것 | 대신하는 것 | | --- | --- | -| `ca.runtime-membership` | the direction gate: nothing outside `allowed_dependencies` can reach a composition root | -| `ca.evidence`, `ca.conditional-transport-qualification`, `ca.strict-qualification` | `strictTestLanes` lanes with `requires` + `rejectSkipped`; the root `conditionalTransportQualification` and `verifyMessagingContracts` only aggregate them | -| `ca.dependency-policy` | a `componentSelection` rejection rule in the leaf (notification: YAML dataformat; messaging: Jackson 2 and any YAML module) and the registry (web-advanced has no allowed consumer). `rejectAll()` constraints were tried and do not fail: Spring's dependency management overrides the rejected version | -| `ca.graphql-platform` | the `graphqlStableTest` lane and `GraphQlProductionClassesTest` in the GraphQL leaf | -| `ca.jpa-test-lanes` | the lanes declared in `adapter/outbound/persistence-jpa/build.gradle` | -| `ca.test-jvm-agents`, `quarantineTest` | `ca.java-conventions`; the quarantine bucket had no tests | +| `ca.runtime-membership` | 방향 게이트: `allowed_dependencies` 밖의 것은 조립 루트에 닿을 수 없다 | +| `ca.evidence`, `ca.conditional-transport-qualification`, `ca.strict-qualification` | `requires` + `rejectSkipped`를 쓴 `strictTestLanes` lane. 루트 `conditionalTransportQualification`과 `verifyMessagingContracts`는 그 lane을 묶기만 한다 | +| `ca.dependency-policy` | leaf 안의 `componentSelection` 거절 규칙(notification: YAML dataformat, messaging: Jackson 2와 모든 YAML 모듈)과 registry(web-advanced는 허용된 소비자가 없다). `rejectAll()` 제약도 써 봤지만 실패하지 않는다: Spring의 의존성 관리가 거절한 버전을 덮어쓴다 | +| `ca.graphql-platform` | GraphQL leaf의 `graphqlStableTest` lane과 `GraphQlProductionClassesTest` | +| `ca.jpa-test-lanes` | `adapter/outbound/persistence-jpa/build.gradle`에 선언한 lane | +| `ca.test-jvm-agents`, `quarantineTest` | `ca.java-conventions`. quarantine 묶음에는 시험이 없었다 | | `ca.jmh-benchmarks` | `me.champeau.jmh` | -| build-tools `ca.jpa-evidence`, `ca.jpa-qualification` (+ `junit` evidence reader) | owner decision 4: persistence-jpa `JpaReadinessRegistryTest`, readiness lanes that require every cited scenario and reject skips, the leaf's `jpaReleaseQualification` aggregate over `config/jpa/release-registry.json` | -| build-tools `ca.config-contract` | moved here unchanged | -| `ca.public-path-snapshot` | app-bootstrap `PublicPathSnapshotTest` (lane `publicPathSnapshotTest`, root alias `verifyPublicPathSnapshot`) | -| `ca.archive-hygiene` | nothing to clean: leaf versions no longer carry the revision, so no stale traceable jar is produced | +| build-tools `ca.jpa-evidence`, `ca.jpa-qualification`(+ `junit` 증거 읽기) | 소유자 결정 4: persistence-jpa `JpaReadinessRegistryTest`, 인용한 시나리오를 모두 요구하고 건너뛰기를 거절하는 readiness lane, `config/jpa/release-registry.json`을 묶는 leaf의 `jpaReleaseQualification` | +| build-tools `ca.config-contract` | 바꾸지 않고 여기로 옮겼다 | +| `ca.public-path-snapshot` | app-bootstrap `PublicPathSnapshotTest`(lane `publicPathSnapshotTest`, 루트 별칭 `verifyPublicPathSnapshot`) | +| `ca.archive-hygiene` | 치울 것이 없다: leaf 버전이 더는 revision을 싣지 않으니 낡은 추적 가능 jar가 생기지 않는다 | | `ca.developer-bootstrap` | `scripts/bootstrap-local.sh` | -| `JpaAdopterApiSurfaceTest` (a regex import scan in persistence-jpa) | `ca.api-surface` `adopterBaseline` | +| `JpaAdopterApiSurfaceTest`(persistence-jpa의 정규식 import 검사) | `ca.api-surface` `adopterBaseline` | -## Testing a convention +## 규약 시험하기 ```bash cd src ./gradlew -p build-logic test --console=plain ``` -The lane and registry conventions are covered by Gradle TestKit against real builds rather than by -reading the plugin source, because the properties that matter — a lane that discovers nothing fails, -a lane reuses a result only when its classes and its lane policy (`rejectSkipped`, `requires`, tag, -category) are unchanged and it starts no server, a malformed registry is refused before any project is included — are -runtime behaviour rather than text in a script. Two of those tests exist because the obvious reading -of the Gradle documentation was wrong: `failOnNoDiscoveredTests` does not fire when a tag filter -matches nothing, and `failOnNoMatchingTests` does not fire when only *some* of the named tests are -missing. +lane과 registry 규약은 플러그인 소스를 읽는 대신 Gradle TestKit으로 실제 빌드에 대고 시험한다. +중요한 성질 — 아무것도 찾지 못한 lane은 실패한다, lane은 클래스와 lane 정책(`rejectSkipped`, +`requires`, tag, category)이 바뀌지 않았고 서버를 띄우지 않을 때만 결과를 다시 쓴다, 잘못된 registry는 +어떤 프로젝트도 포함하기 전에 거절된다 — 이 스크립트의 글이 아니라 런타임 동작이기 때문이다. 그중 +시험 둘은 Gradle 문서를 그대로 읽으면 틀렸기 때문에 있다: tag 필터가 아무것도 맞추지 못할 때 +`failOnNoDiscoveredTests`가 동작하지 않고, 이름을 댄 시험 중 *일부만* 없을 때 +`failOnNoMatchingTests`가 동작하지 않는다. diff --git a/src/composition/outbox-relay/CLAUDE.md b/src/composition/outbox-relay/CLAUDE.md index f63f9fa9..1f890d5f 100644 --- a/src/composition/outbox-relay/CLAUDE.md +++ b/src/composition/outbox-relay/CLAUDE.md @@ -1,21 +1,19 @@ # composition:outbox-relay -- Module ID `composition-outbox-relay`, Gradle path `:composition:outbox-relay`. Registry SSOT: +- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본: `src/config/architecture/modules.json`. -- Responsibility: assemble and drive the application's outbox relay. It builds - `PublishPendingOutboxEventsUseCase` by hand from `app.outbox.*` (`OutboxSettings`, strict binding), - runs it from `OutboxRelayScheduler` (fixed-delay ticks, a `SmartLifecycle` that stops above the - messaging platform's admission phase), and owns the outbox metrics (`OutboxMetrics`: gauges on a - thread of their own, the cycle-outcome counter from the relay). -- Boundaries: it names ports only — `OutboxStorePort`, `OutboxMessagePublishPort`, - `OutboxRelayFailureReportPort`, `TransactionPort` — never a module type, so removing the - persistence or messaging line removes the relay. No business rule, no SQL, no broker type. The - relay use case is never a bean (`@SystemInvoked`, no permission gate). Allowed edges come only from - the registry entry. -- Startup refusals live here because only here do the settings meet the ports: a batch whose worst - case (`batch-size` × the publish port's `longestAttempt`) reaches `in-flight-timeout` fails startup. -- Tests: `./gradlew :composition:outbox-relay:check`. The shutdown order is pinned against the - platform's own phase constant (`OutboxRelayShutdownOrderTest`); the end-to-end relay → bridge → real - Kafka path is `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`. -- Design and rejected alternatives: `README.md`. Operations: `docs/runbooks/outbox-publish-failed.md`, +- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한 + 바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연 + tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric + (`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다. +- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`, + `OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging + 줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다 + (`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다. +- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우 + (`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다. +- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰 + 고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는 + `:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다. +- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`, `docs/runbooks/outbox-dead-letter.md`. diff --git a/src/config/architecture/README.md b/src/config/architecture/README.md index 07a8d32b..b494cad8 100644 --- a/src/config/architecture/README.md +++ b/src/config/architecture/README.md @@ -1,13 +1,14 @@ -# Architecture module registry +# 아키텍처 모듈 registry -`modules.json` records Gradle project identity and the exact production project edges each leaf may -see. An empty `allowed_dependencies` list is meaningful: it means the leaf is intentionally -project-standalone, not that the registry entry is unfinished. +`modules.json`은 Gradle 프로젝트의 정체(id, Gradle 경로, 소스 경로)와 각 leaf가 볼 수 있는 운영 +프로젝트 edge를 정확히 적는다. 빈 `allowed_dependencies` 목록에도 뜻이 있다: 그 leaf가 일부러 다른 +프로젝트에 기대지 않는다는 뜻이지, registry 항목을 덜 채웠다는 뜻이 아니다. -`adapter-outbound-persistence-mongo` is the important example. That leaf owns the Mongo provider -implementation without importing application/domain project types; composition into application -ports is owned by the bootstrap/autoconfiguration side. Its empty dependency list is therefore an -explicit boundary and must remain empty until a real project edge is introduced and reviewed. +`domain-core`, `shared-contract`, 들여온 메시징 제품의 `messaging-core-api`가 그 예다. 빈 목록은 +분명한 경계이고, 실제 프로젝트 edge를 들여와 리뷰하기 전까지 비어 있어야 한다. 반대로 목록에 적힌 +edge는 빌드가 실제로 쓰는 것과 맞아야 한다. 예를 들어 `adapter-outbound-persistence-mongo`의 목록은 +`["application-core", "shared-contract"]`이고 `MongoRegistryPermissionParityTest`가 두 방향을 모두 +본다. -Runtime composition membership is derived from resolved runtime classpaths by the build logic; it is -not duplicated as a per-module field in this registry. +런타임 조립 구성원은 빌드 로직이 해석된 runtime classpath에서 얻는다. 이 registry에 모듈마다 칸으로 +다시 적지 않는다. diff --git a/src/domain-core/CLAUDE.md b/src/domain-core/CLAUDE.md index 7e32ff10..70bf470b 100644 --- a/src/domain-core/CLAUDE.md +++ b/src/domain-core/CLAUDE.md @@ -1,36 +1,36 @@ -# domain-core — pure domain layer +# domain-core — 순수 도메인 계층 -## Registered identity +## 등록 정보 -- Module ID: `domain-core` -- Gradle path: `:domain-core` -- Focused test (derived from Gradle path): `./gradlew :domain-core:test --console=plain` -- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0. -- Registry SSOT: `src/config/architecture/modules.json`. +- 모듈 ID: `domain-core` +- Gradle 경로: `:domain-core` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. -Package root: `dev.caskeleton.domain`. +패키지 루트: `dev.caskeleton.domain`. 코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). -## Responsibility +## 책임 -- Business concepts, entities, value objects, enums, domain events, domain services. -- Repository ports where this reference implementation still keeps domain-owned persistence contracts. -- Domain invariants and core rules. +- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스. +- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트. +- 도메인 불변식과 핵심 규칙. -## Allowed +## 허용 -- Java standard library. -- Value-only shared operational types only if truly needed. +- Java 표준 라이브러리. +- 값만 담은 공용 운영 타입은 정말 필요할 때만. -## Forbidden +## 금지 -- Spring annotations. -- JPA annotations. -- Servlet/HTTP types. -- Adapter, application, bootstrap, or presentation DTO dependencies. +- Spring 애너테이션. +- JPA 애너테이션. +- Servlet·HTTP 타입. +- 어댑터, application, bootstrap, 표현 계층 DTO 의존. -## Test +## 테스트 ```bash cd src diff --git a/src/platforms/grpc-advanced/CLAUDE.md b/src/platforms/grpc-advanced/CLAUDE.md index 158830ae..d78e9d8d 100644 --- a/src/platforms/grpc-advanced/CLAUDE.md +++ b/src/platforms/grpc-advanced/CLAUDE.md @@ -1,6 +1,6 @@ -# grpc-advanced — local authority for the advanced gRPC capabilities +# grpc-advanced — 고급 gRPC capability의 지역 정본 -이 문서는 `grpc-advanced:*` family의 **local authority**다. leaf 목록·gradle path·허용 의존성은 +이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 `src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다. diff --git a/src/platforms/grpc/CLAUDE.md b/src/platforms/grpc/CLAUDE.md index 190f58d1..d79d4be7 100644 --- a/src/platforms/grpc/CLAUDE.md +++ b/src/platforms/grpc/CLAUDE.md @@ -1,6 +1,6 @@ -# grpc — local authority for the gRPC platform family +# grpc — gRPC 플랫폼 family의 지역 정본 -이 문서는 `grpc:*` family의 **local authority**다. gRPC platform은 기본 application build와 분리된 +이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된 `src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, Stable 범위의 경계와 application에 채택될 때 필요한 계약이다. @@ -132,64 +132,61 @@ cd src (`GrpcMetricCardinalityPolicy`가 거부한다). -### Adoption-time observability gate +### 채택할 때의 관측 게이트 -The metric names implemented by `grpc-observability` are **not registered in -`docs/registries/metrics.yaml` yet** because this optional family is not a shipped runtime capability. -Do not present those names as repository-certified metrics until adoption adds registry entries with -the repository's `.seconds` / `.total` unit naming and the corresponding validation gate. +`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지 +않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의 +`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그 +이름을 저장소가 인증한 metric처럼 내세우지 않는다. -### Durable operation ledger adoption +### durable operation 원장 채택 -`grpc-spring-boot-starter` does not pull the JPA ledger adapter transitively (11-M9). A deployment that -needs durable operation idempotency adds `:grpc:grpc-operation-ledger-jpa` explicitly, defines a -`GrpcOperationLedger` bean (`new JpaGrpcOperationLedger(repository)`), includes that adapter's Flyway -location `db/migration/grpc` (V001 table, V002 retention index, V003 claim attempt), and sets the flag below. A deployment -that does not adopt the ledger pays no Spring Data JPA classpath cost. +`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(11-M9). durable +operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고, +`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway +위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다. +원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다. -| Key (`app.grpc.platform.*`) | Default | What it does | +| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 | | --- | --- | --- | -| `operation-ledger-enabled` | `false` | `true`: the starter assembles `GrpcIdempotencyInterceptor` (bean `grpcIdempotencyInterceptor`) and `GrpcOperationLedgerRetention` (bean `grpcOperationLedgerRetention`) over the deployment's `GrpcOperationLedger` bean, and refuses startup when there is none. `false`: neither bean exists, and a method that is `IDEMPOTENCY_KEY_REQUIRED` refuses startup | -| `operation-ledger-claim-ttl` | `5m` | How long an `IN_PROGRESS` claim is trusted to have a live owner. After it, a retry of the same request takes the claim over (`GrpcOperationLedger.reclaimStale`). Refused at startup unless longer than every keyed method's deadline | -| `operation-ledger-retention` | `24h` | How long a finished (`COMMITTED`/`FAILED_TERMINAL`) record is kept before `GrpcOperationLedgerRetention.purgeExpired` may delete it. `IN_PROGRESS` rows are never purged | +| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 | +| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 | +| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 | -Defaults: the 5-minute TTL is the value the ledger contract and interceptor tests certify, far beyond -a unary deadline, and short enough that a key whose owner died unblocks within a client's retry -patience. The 24-hour retention matches the HTTP idempotency replay TTL -(`app.capabilities.idempotency.replay-ttl`). A retry of a key after its record was purged is a new -operation, so the retention must exceed the callers' retry window. +기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고, +주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL +(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새 +operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다. -These keys are not in `docs/registries/env-keys.yaml`: no `app.grpc.platform.*` key is, because the -optional build is not part of the shipped runtime. They join the registry when a composition root -adopts the platform. +이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서 +`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다. -**Why the starter assembles the interceptor (option (b)), and not (a).** The 2026-11-01 maturity review proposed (a): -delete the flag and judge by whether a ledger bean exists. (b) was chosen on 2026-11-03 and is recorded in -ADR-GRPC-004: the flag stays and means what it says — when true, the -decision function is assembled and its TTL comes from configuration. (a) would have removed the false promise but left every adopter to rebuild the same -assembly and TTL validation by hand; (b) keeps that in one place. The interceptor bean has no -`@ConditionalOnMissingBean` on purpose: a replacement would silently ignore `operation-ledger-claim-ttl`. -Duplicates of a running operation are refused (`REJECT_IN_PROGRESS`), not told to wait; a -wait-and-poll option becomes a key when a keyed method needs it. +**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는 +(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에 +적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서 +온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게 +했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다: +바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의 +중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가 +필요한 메서드가 그것을 필요로 할 때 키가 된다. -**Server wiring is still the adopter's, and stays a separate decision.** The starter builds no -server, so assembling the decision does not wire the platform into `adapter:inbound:grpc` (see "배선은 -별도 결정" above). `GrpcIdempotencyInterceptor` is a decision function, not an `io.grpc.ServerInterceptor`. -The adopter injects the bean by type and calls it from its own `IDEMPOTENCY` stage interceptor -(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`) or from -its typed service adapter: `decide(...)` before the mutation, `recordCommit(...)` inside the mutation's -transaction, `recordFailure(...)` on a terminal failure. Both record calls take the `GrpcClaimToken` -the `PROCEED` decision carried: a commit by an attempt whose claim was taken over is refused (its -transaction rolls back) and its failure is ignored, so a slow owner cannot write over the attempt that -took its claim (ADR-GRPC-004). +**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지 +않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은 +별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가 +아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor +(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기 +typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서 +`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온 +`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는 +무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004). -**Purge scheduling is the adopter's.** `GrpcOperationLedgerRetention.purgeExpired(now)` deletes -expired finished rows in bounded batches (500 per statement) until a batch comes back short. The -starter does not schedule it: it owns no scheduler and cannot know which replica should run it, and a -scheduled bean would force a task scheduler onto every deployment. The adopter calls it from its own -scheduler (for example hourly); concurrent runs on several replicas are safe because the delete skips -locked rows. Running it never is safe but lets the table grow without bound. +**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난 +끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을 +예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든 +배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다). +지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만 +테이블이 끝없이 커진다. -The commit must be recorded in the mutation's transaction and the TTL must be longer than the slowest -keyed method; both reasons are in ADR-GRPC-004. +커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두 +이유는 모두 ADR-GRPC-004에 있다. diff --git a/src/platforms/messaging/CLAUDE.md b/src/platforms/messaging/CLAUDE.md index eda4b578..705cc3f3 100644 --- a/src/platforms/messaging/CLAUDE.md +++ b/src/platforms/messaging/CLAUDE.md @@ -1,6 +1,6 @@ -# messaging — local authority for the messaging platform family +# messaging — 메시징 플랫폼 family의 지역 정본 -이 문서는 messaging family의 **local authority**다. leaf 목록·gradle path·허용 의존성은 +이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은 `src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는 것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에 필요한 증거, runtime membership이 비어 있다는 사실의 의미. @@ -40,7 +40,7 @@ JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMES registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는 `shared-contract`의 정본과 같은 규칙인지 함께 본다. -### Publish retryability of authentication and authorization +### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization) 이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다. diff --git a/src/platforms/optional-build/README.md b/src/platforms/optional-build/README.md index e6bce651..8df221e1 100644 --- a/src/platforms/optional-build/README.md +++ b/src/platforms/optional-build/README.md @@ -1,13 +1,13 @@ -# Optional gRPC platforms +# optional gRPC 플랫폼 -The default application does not depend on `grpc/*` or `grpc-advanced/*`, so those projects (the -registry entries with `"build": "optional-grpc"`) are kept out of the main multi-project build. This build preserves their existing project paths and -internal project dependencies while making their configuration opt-in. +기본 애플리케이션은 `grpc/*`나 `grpc-advanced/*`에 의존하지 않는다. 그래서 이 프로젝트들(registry에서 +`"build": "optional-grpc"`인 항목)은 주 멀티 프로젝트 빌드에서 뺀다. 이 빌드는 그 프로젝트들의 원래 +프로젝트 경로와 내부 프로젝트 의존을 그대로 두면서, 그 설정을 고를 때만 켜지게 한다. ```bash ./gradlew -p platforms/optional-build ci ./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest ``` -`adapter:inbound:grpc` remains in the main application build because it is an application adapter; -the reusable gRPC platform libraries are optional capability code and live here. +`adapter:inbound:grpc`는 애플리케이션 어댑터라서 주 애플리케이션 빌드에 남는다. 다시 쓰는 gRPC +플랫폼 라이브러리는 optional capability 코드이고 여기 있다. diff --git a/src/shared-contract/CLAUDE.md b/src/shared-contract/CLAUDE.md index 3739e420..6722710c 100644 --- a/src/shared-contract/CLAUDE.md +++ b/src/shared-contract/CLAUDE.md @@ -1,72 +1,68 @@ -# shared-contract — skeleton-wide operational contract +# shared-contract — 골격 전체가 쓰는 운영 계약 -## Registered identity +## 등록 정보 -- Module ID: `shared-contract` -- Gradle path: `:shared-contract` -- Focused test (derived from Gradle path): `./gradlew :shared-contract:test --console=plain` -- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0. -- Registry SSOT: `src/config/architecture/modules.json`. +- 모듈 ID: `shared-contract` +- Gradle 경로: `:shared-contract` +- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :shared-contract:test --console=plain` +- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다. +- registry 정본: `src/config/architecture/modules.json`. -Package root: `dev.caskeleton.shared`. +패키지 루트: `dev.caskeleton.shared`. -Design decisions previously kept as code comments (error-code classification, response -envelope shape, metric cardinality bounds, tracing seam, domain-context propagation) live in -[README.md](README.md). This file stays the SSOT for module rules. +예전에 코드 주석에 두던 설계 결정(오류 코드 분류, 응답 envelope 모양, metric cardinality 한계, +tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙의 정본으로 +남는다. -## Responsibility -- Response envelope (`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`). -- Error code contract (`error/ApiErrorCode` interface, `error/OperationalError` enum, - `error/ApiErrorCarrier`) and the one client-facing wording table (`error/ClientErrorMessages`, - Korean, one message per `Category`, used by every transport). -- Cross-cutting mapper sentinel (`error/MappingException`). -- Request value contract (`request/Patch`). -- Tracing contract types (`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C - `traceparent` value type and the span-error-recording seam (feature-distributed-tracing-contract; the OTel - tracer runtime is a fork-activated seam, so these stay Java-stdlib-only). -- Stdlib helpers every leaf used to copy (moved here in the 2026-09-25 review follow-up): `digest/Sha256` (the - SHA-256 digest value and the one `MessageDigest.getInstance("SHA-256")`), `digest/HmacSha256` - (sign and constant-time verify), `retry/Backoff` (capped exponential ceiling; "full jitter" means - `U[0, ceiling]` and nothing else). Vendored `messaging:*` and the optional gRPC build do not depend - on this module and keep their own copies; each family's CLAUDE.md says why (a different product, - decided after the 2026-08-14 messaging module review). Every template leaf that needs one of these has the `shared-contract` edge and uses them - instead of copying: identifier, persistence-mongo, application-objectstorage and redis-sdk took the - edge for exactly this (decided 2026-11-03), each with a test - that pins its output to a vector computed outside the JVM. -- `observability/MdcKeys`: the snake_case MDC key names (registry `docs/registries/mdc-keys.yaml`) - every transport puts a request's correlation under — web, GraphQL, STOMP and gRPC alike. -- `ratelimit/`: the provider-neutral edge rate-limit port (`EdgeRateLimitPort`) and its value types, - between the web edge and the Redis adapter (README 「ratelimit」). -- `security/Permission`: the `resource:action` permission value `AuthorizationPort` is asked about - (README 「security」). -- `concurrency/`: the domain-context propagation port and its `ThreadLocal` default (README - 「concurrency」). -- `runtime/RuntimeEnvironment`: the one runtime-profile vocabulary every leaf answers "is this - production?" with. -- `metrics/ForbiddenMetricTags`: the high-cardinality tag keys no metric may carry. -- These are the module's packages and the only ones it may have: - `ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES` refuses a - class in any other package below `dev.caskeleton.shared` or directly in the root, which holds only - its `package-info`. A new contract package goes into that test's `SHARED_CONTRACT_PACKAGES` and - into this list together; `SharedContractPackageRuleTest` fails when `SHARED_CONTRACT_PACKAGES` and - the module's packages differ. -- Registry-rule mirrors read only by contract tests live in `testFixtures`, not `main`: +## 책임 (Responsibility) +- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`). +- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum, + `error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`. + 한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다). +- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`). +- 요청 값 계약(`request/Patch`). +- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과 + span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는 + 이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다). +- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다): + `digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`), + `digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는 + `U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 optional gRPC 빌드는 이 모듈에 + 의존하지 않고 자기 사본을 둔다. 각 제품의 CLAUDE.md가 이유를 적는다(다른 제품이다. 2026-08-14 메시징 + 모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지 + 않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에 + edge를 받았고(2026-11-03에 정함), 각각 JVM 밖에서 계산한 벡터로 출력을 고정하는 시험이 있다. +- `observability/MdcKeys`: 모든 전송 계층(web, GraphQL, STOMP, gRPC)이 요청의 correlation을 넣는 + snake_case MDC 키 이름(registry `docs/registries/mdc-keys.yaml`). +- `ratelimit/`: web edge와 Redis 어댑터 사이에 있는 provider 중립 edge rate-limit 포트 + (`EdgeRateLimitPort`)와 그 값 타입(README 「ratelimit」). +- `security/Permission`: `AuthorizationPort`에 묻는 `resource:action` 권한 값(README 「security」). +- `concurrency/`: domain-context 전파 포트와 그 `ThreadLocal` 기본 구현(README 「concurrency」). +- `runtime/RuntimeEnvironment`: 모든 leaf가 「운영 환경인가?」에 답할 때 쓰는 유일한 runtime profile + 어휘. +- `metrics/ForbiddenMetricTags`: 어떤 metric도 실으면 안 되는 high-cardinality tag 키. +- 이 모듈의 패키지는 위가 전부이고 다른 패키지는 둘 수 없다: + `ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 + `dev.caskeleton.shared` 아래 다른 패키지에 있는 클래스와 루트에 바로 있는 클래스를 거절한다. 루트에는 + `package-info`만 있다. 새 계약 패키지는 그 시험의 `SHARED_CONTRACT_PACKAGES`와 이 목록에 함께 + 넣는다. `SharedContractPackageRuleTest`는 `SHARED_CONTRACT_PACKAGES`와 모듈의 패키지가 다르면 + 실패한다. +- 계약 시험만 읽는 registry 규칙 사본은 `main`이 아니라 `testFixtures`에 둔다: `metrics/MetricNaming`, `metrics/CardinalityBounds`, `metrics/AlertSeverity`, - `tracing/BaggageAllowlist`. Move one to `main` only when production code consumes it. -- Generic messaging envelope schema resources under `contracts/messaging/envelope/`. - They own transport-neutral envelope metadata only; feature payload schemas remain in their - feature-owner modules. Resource presence is not runtime discovery or registration. + `tracing/BaggageAllowlist`. 운영 코드가 쓰게 될 때만 `main`으로 옮긴다. +- `contracts/messaging/envelope/` 아래의 범용 메시징 envelope schema 리소스. 전송 중립 envelope + metadata만 가진다. 기능 payload schema는 그 기능을 가진 모듈에 남는다. 리소스가 있다고 런타임에 + 찾아지거나 등록되는 것은 아니다. -## Allowed -- Java standard library ONLY. No Spring, no Jackson, no JPA imports. +## 허용 +- Java 표준 라이브러리**만**. Spring, Jackson, JPA import는 없다. -## Forbidden -- business/domain concept (domain error codes belong in the consuming module). -- framework imports (HTTP status is expressed as transport-neutral `int`; the web module maps it). -- claiming Draft 2020-12 validator compatibility before the messaging adapter's Task 6 validator - qualification exists. +## 금지 (Forbidden) +- 업무·도메인 개념(도메인 오류 코드는 그것을 쓰는 모듈에 둔다). +- 프레임워크 import(HTTP 상태는 전송 중립 `int`로 나타내고 web 모듈이 대응시킨다). +- 메시징 어댑터의 Task 6 validator 검증이 생기기 전에 Draft 2020-12 validator 호환을 주장하기. -## Test +## 테스트 ```bash cd src ./gradlew :shared-contract:test