# application-core — 애플리케이션 유스케이스 ## 등록 정보 - 모듈 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`. 패키지 루트: `dev.caskeleton.application`. 코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT). ## 책임 (Responsibility) - 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약. - 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스). - 애플리케이션 예외와 정책 타입. - 포트를 거쳐 도메인 모델을 조율한다. - `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다. - `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는 어댑터가 가진다. - 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의 payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다. ## 허용 - `:domain-core` - `:shared-contract` - Java 표준 라이브러리 타입. ## 금지 (Forbidden) - `adapter-*` 구현 클래스. - `app-bootstrap`. - 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. ## 계약 타입 | 타입 | 용도 | |---|---| | `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

` | 닫힌 정확한 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 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | ## 알림 (NOTIF-ADR-005) 알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과 `dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`, `NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이 유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다. ## 이름 규칙 (Naming convention) 이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」 열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다. | 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) | |---|---|---|---| | 유스케이스(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`다 | 저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에 필요한 배관이면 application의 `StorePort`다.** ## 패키지 소유 (Package ownership) 이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. `docs/manual/03-placement.md`가 이곳을 가리킨다. - 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. - ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다. - 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지 않는다. - 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을 더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다. | 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 | |---|---|---| | `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 | 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`은 그것이 싣는 호출 기한이다) | | 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 | |---|---|---| | `identifier` | domain-core | `ResourceId`, `IdFactory` | | `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` | 강제하는 곳: - `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) ```java @RequiresPermission("user:register") @UseCaseCapability( transactionMode = TransactionMode.WRITE, idempotency = Idempotency.KEYED, repositoryAccess = RepositoryAccess.WRITE_REPOSITORY) public class RegisterUserUseCase implements CommandUseCase { private final UserRepository users; private final TransactionPort tx; public RegisterUserUseCase(UserRepository users, TransactionPort tx) { this.users = users; this.tx = tx; } @Override public User handle(RegisterUserCommand cmd) { return tx.inWrite(() -> { // ... domain coordination }); } } ``` 이 클래스는 평범한 Java다. 조립 루트가 포트와 설정 값을 넣어 만든다. application-core는 DI 프레임워크에 스스로 등록하지 않는다. 클래스는 **final이 아니다**: 상태를 바꾸는 유스케이스는 `@RequiresPermission`을 선언하고, web 어댑터는 CGLIB proxy로 그것을 강제하는데, CGLIB는 final 클래스를 상속하지 못한다(`RequiresPermissionProxyabilityTest`). 같은 이유로 bean으로 등록한다. `new`로 만든 유스케이스는 검사를 받지 않는다. 시스템만 부르는 유스케이스(스케줄러, relay, 메시지 소비자)는 권한 대신 `@SystemInvoked(reason = ...)`를 달고 bean이 아니다. 권한 검사가 없는 쓰기라서 사용자 요청이 닿으면 안 되기 때문이다. 그 시스템 호출자가 유스케이스를 만든다: 스케줄러는 조립 모듈, 메시지 핸들러는 `..adapter.inbound.messaging..` 안의 `@SystemCaller(reason = ...)`, 예약 작업은 서비스 자신의 `..adapter.inbound.scheduler..` 패키지 안의 `@SystemCaller`다. 이 셋과 각각의 위치는 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」가 정본 목록이다. 모두 강제된다: `@SystemInvoked` bean은 기동에 실패한다. `@SystemCaller`가 아닌 inbound 어댑터가 그 유스케이스에 의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 실패한다. `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`는 그 표지(그리고 표지가 붙은 클래스 안에 든 클래스)를 사용자 전송 계층에 두지 못하게 한다. `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`는 사용자 전송 계층이 시스템 호출자를 부르지 못하게 한다(그 클래스로든, 그것이 구현한 프로젝트 인터페이스로든). `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`는 시스템 호출자가 `Runnable`이나 프로젝트 밖의 다른 타입이 되지 못하게 한다. 그런 타입은 어떤 의존 규칙도 따라가지 못한다. 타입 이름이 드러나지 않는 경로(이름으로 찾는 bean, 설정이 넘겨주는 함수)는 보지 못한다. 매뉴얼 07장이 그 경로와 그것을 막는 곳을 적는다. `@RequiresPermission` bean이 있는데 강제할 advisor가 없는 조립도 기동에 실패한다 (`composition:service-runtime`의 `PermissionEnforcementGuard`, 두 검사 모두). ## 허용하는 트랜잭션 모양 (Allowed transactional shapes) | 유스케이스 모양 | `transactionMode` | TransactionPort 호출 | 언제 | |---|---|---|---| | 쓰기 command | `WRITE` | `tx.inWrite(...)` | `CommandUseCase`의 기본. | | 물리 루트 쓰기 command | `WRITE` | `tx.inRootWrite(...)` | 바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. | | 읽기 전용 query | `READ_ONLY` | `tx.inRead(...)` | `QueryUseCase`의 기본. | | outbox·감사·보상 | `REQUIRES_NEW` | `tx.inNew(...)` | 유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. | `NESTED`와 `NEVER` 전파는 금지다. `inRootWrite`는 action이나 `PlatformTransactionManager`를 부르기 전에 실제로 열린 바깥 트랜잭션을 반드시 거절한다. 루트 전용 동작을 `REQUIRES_NEW`로 흉내 내면 안 된다. `WRITE_REPOSITORY + WRITE` 유스케이스의 직접 경계 적합성 규칙은 `inWrite`와 `inRootWrite`가 모두 만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다. ### 콜백 시그니처 계약 `TransactionPort` 콜백은 `Supplier` / `Runnable`이라 checked 예외를 던지지 못한다. Spring `TransactionCallback`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로 감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로 감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다. ### `inNew` 풀 크기 제약 `inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다. ``` hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 ``` **금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길 수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다. ## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract `@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 `dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. - **범위(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`). - 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된 실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 — retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07). 예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는 이 브랜치가 병합될 때 지웠다. ## 읽기·query 경로 (feature-application-query-bypass-contract) 읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다. | 모양 | 돌려주는 것 | 언제 | 어떻게 | |---|---|---|---| | **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 | - **순수성 가드레일(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 가드레일(강제됨) - `APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT` - `APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION` - `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT` - `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` 반환 순수성) ## 테스트 ```bash cd src ./gradlew :application-core:test ./gradlew :app-bootstrap:architectureTest ``` 위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox 영속, 그 밖의 메시징 R2 capability를 주장하지 않는다.