문제: 모듈 문서가 ArchUnit 규칙을 `domain_is_pure`, `query_ports_do_not_leak_domain_jpa_or_web_types` 같은 소문자 이름으로 가리킨다. 지금 코드의 규칙은 `DOMAIN_IS_PURE` 같은 대문자 `static final ArchRule` 상수이고 소문자 이름은 운영 코드 어디에도 없다. 문서의 이름으로 규칙을 찾으면 아무것도 나오지 않는다. 방법: `src/**`의 CLAUDE.md와 README에서 backtick으로 쓴 소문자 규칙 이름 중, 같은 이름의 대문자 ArchRule 상수가 코드에 있는 것만 그 상수 이름으로 바꾼다(31곳, 파일 8개). 지운 규칙을 적은 곳 (`inbound_port_implementations_do_not_declare_keyed_idempotency`)은 지웠다는 기록이라 그대로 둔다. 위험: shared-contract 운영 코드 Javadoc 두 곳 (`DomainContextPropagator`, `ThreadLocalDomainContextPropagator`)이 아직 소문자 `no_inheritable_thread_local`을 쓴다. 이 작업 범위(문서) 밖이라 고치지 않았다. 검증: 바꾼 이름마다 `static final ArchRule <NAME>` 또는 `<NAME> =`가 코드에 있는지 스크립트로 대조했다. python3 scripts/check-docs.py rc=0, check-work-docs.py rc=0.
26 KiB
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 가 모아둔다 (이 문서는 모듈 규칙 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<I, O> |
inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 CommandUseCase나 QueryUseCase를 상속한다. |
usecase.CommandUseCase<C extends Command, R> |
쓰기 유스케이스의 inbound 포트. 구현은 반드시 @UseCaseCapability를 단다. |
usecase.QueryUseCase<Q extends Query, R> |
읽기 전용 유스케이스의 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<P> |
닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. |
messaging.event.IntegrationEventDraft<P> |
로컬 인코딩 전의 타입 있는 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 포트 구현) | <Verb><Noun>UseCase, ArchUnit이 강제 |
기능의 application 패키지 |
*ApplicationUseCase(application-fileserver, application-notification), *Service(notification, fileserver) |
| command·query record | *Command / *Query |
그 유스케이스 옆 | — |
| aggregate 영속(aggregate 전체를 저장하고 돌려준다) | <Aggregate>Repository |
aggregate의 domain 패키지, 도메인이 가진다 | — |
| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | <Thing>StorePort |
application 패키지 | *WritePort(옛 onboarding fixture, 지움) |
| aggregate가 아니라 projection을 돌려주는 읽기 모델 | <Thing>QueryPort |
application 패키지. projection만 돌려준다(ArchUnit) | — |
| 그 밖의 outbound 포트 | <Capability>Port |
application 패키지 | — |
| 서버가 정하는 id 생성 | <Aggregate>IdFactory extends IdFactory<<Aggregate>Id> |
domain 패키지. id record는 implements ResourceId<Self> |
OutboxEventIdFactory(샘플. event id는 resource id가 아니다) |
| 설정 바인딩 | *Settings(운영) 또는 *Policy(인가·도메인 정책), ArchUnit이 강제 |
그것을 바인딩하는 leaf | — |
| Throwable | *Exception, ArchUnit이 강제 |
— | — |
| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 <Port>Contract. fake의 시험과 각 어댑터의 시험이 상속한다 |
testFixtures | 값 타입 시험의 이름이 한때 *ContractTest였다. 지금은 *ValueTypesTest다 |
저장소의 한 줄 규칙: 도메인이 알아볼 만한 것을 저장하면 도메인의 Repository다. 애플리케이션에
필요한 배관이면 application의 StorePort다.
패키지 소유 (Package ownership)
이 절은 템플릿이 어떤 패키지를 가지는지와 업무 기능이 어디로 가는지의 정본이다.
docs/manual/03-placement.md가 이곳을 가리킨다.
- 업무 기능은
dev.caskeleton.application.<feature>다(그리고dev.caskeleton.domain.<feature>,...adapter.inbound.web.<feature>,...bootstrap.autoconfigure.<feature>). 루트마다 바로 아래에 기능 하나당 패키지 하나를 두고,command·usecase·port하위 패키지를 두지 않는다. <feature>는 아래 템플릿 패키지 이름 중 하나가 아니다. 같은 이름의 템플릿 패키지 옆에 둔 기능은 같은 패키지 트리에 들어가고, 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-bootstrapsrc/test에 있어서 architecture suite와 document-contract lane이 모두 본다).TemplatePackageOwnershipDocumentTest(document-contract lane,mainCheck)는 표와 그 클래스의 패키지 이름이나 소유 leaf가 다르거나, 표에 적힌 패키지가 표가 말한 leaf에 없으면 실패한다.TemplatePackageOwnershipRuleTest(architectureTest)는 적힌 이름이 운영 클래스 어디에도 없으면 실패한다. 새 템플릿 패키지는 같은 변경에서 둘 모두에 들어간다. - 못 잡는 것: 아무도 적지 않은 새 템플릿 패키지. 기능은 같은 leaf에 생성되므로
(
scripts/new-feature.sh) 적히지 않은 패키지는 기능과 구별되지 않는다. 적는 것까지가 패키지를 더하는 일이다. - 버린 대안: 적힌 최상위 패키지만 허용하기(파생 기능마다 템플릿 목록을 고쳐야 한다 — 기능마다
병합 충돌이 난다), 플랫폼 패키지용
application-platformleaf를 따로 두기(2026-11-01 성숙도 리뷰에서 따졌다: 경계는 더 분명하지만, 이름 규칙에 필요한 것보다 registry edge가 많아진다).
정해진 유스케이스 모양 (Canonical use case shape)
@RequiresPermission("user:register")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.KEYED,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
public class RegisterUserUseCase implements CommandUseCase<RegisterUserCommand, User> {
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<T> / Runnable이라 checked 예외를 던지지 못한다. Spring
TransactionCallback<T>의 제약과 같다. 도메인의 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, 재생 TTLAPP_IDEMPOTENCY_TTL24h ≤72h이고 lease보다 짧지 않다, 실패 보존 24h이고 재생 TTL보다 짧지 않다). 유스케이스나 서비스 자신의 설정에서 만들지 않는다. - action은
IdempotentAction.Outcome(Success/RetryableNoEffect/EffectUnknown)을 돌려준다. 던진 예외는 효과를 모름(effect-unknown)으로 센다. 처리 중이면 409IDEMPOTENT_IN_FLIGHT, fingerprint(SHA-256)가 다르면 422IDEMPOTENT_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<DomainType>) 안 된다. ArchUnitQUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES가 강제한다. projection 사용 자체는 강요된 기본이 아니라 선택이다. - 엄격한 절차: 모든 읽기는
QueryUseCasebean을 거친다. 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_TRANSPORTAPPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATIONAPPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXTAPPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORKINBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASEINBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITYQUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES(*QueryPort반환 순수성)
테스트
cd src
./gradlew :application-core:test
./gradlew :app-bootstrap:architectureTest
위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox 영속, 그 밖의 메시징 R2 capability를 주장하지 않는다.