# application-core — 애플리케이션 유스케이스 ## 등록 정보 - 모듈 ID: `application-core` - Gradle 경로: `:application-core` - 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-core:test --console=plain` - 실행 기준: Java 21. 프레임워크 기준은 공용 버전 카탈로그(`gradle/libs.versions.toml`)가 고정한 Spring Boot 4.x다. - registry 정본: `gradle/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. ## 계약 타입 표와 자세한 계약은 [README.md](README.md) 「계약 타입」 절이다. 지킬 것: - 구체 inbound 포트는 `CommandUseCase`나 `QueryUseCase`를 상속하고, 그 구현은 `@UseCaseCapability`를 단다(ArchUnit `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY`). ## 알림 (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` | 그 유스케이스 옆 | — | | 요청 값 record: command가 담는 호출자 요청 내용(호출자가 누구인지는 뺀 값), 또는 포트 인자 묶음 | `*Request` | 그것을 담는 command나 받는 포트 옆 | `CreateUploadRequest`·`FinalizeUploadRequest`(application-fileserver `upload`, command는 `port.in`), `VerificationRequest`(application-fileserver `api.security`, 포트는 `upload`), application-objectstorage의 `request` 패키지(포트는 `port`, leaf가 값 타입 패키지로 정했다) | | 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` | `DurableOperationIdFactory`(durable operation id는 aggregate의 resource id가 아니라 `IdFactory`를 따르지 않는다), `NotificationIdGeneratorPort`(application-notification), `UploadIdentifierPort`(application-fileserver). 셋 다 사용자 전송이 쥐면 `USER_TRANSPORTS_DO_NOT_HOLD_PERSISTENCE_OR_ID_PORTS`가 막는다 | | 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — | | Throwable | `*Exception`, ArchUnit이 강제 | — | — | | 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 | 저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에 필요한 배관이면 application의 `StorePort`다.** ## 패키지 소유 (Package ownership) 표와 자세한 계약은 [README.md](README.md) 「패키지 소유 (Package ownership)」 절이다. 그 표가 템플릿 패키지 목록의 정본이다. 지킬 것: - 업무 기능은 루트마다 바로 아래에 기능 하나당 패키지 하나다(`dev.caskeleton.application.`, `dev.caskeleton.domain.` 등). `command`·`usecase`·`port` 하위 패키지를 두지 않는다. - ``는 템플릿 패키지 이름이 아니다. 업무 코드를 템플릿 패키지에 넣지 않고, 템플릿 패키지는 기능 패키지를 import하지 않는다(`NamingConventionTest`). - 템플릿 패키지를 더하거나 이름을 바꾸거나 지우면 README 표와 `TemplatePackageOwnership`을 같은 변경에서 고친다. `TemplatePackageOwnershipDocumentTest`가 둘을 대조한다. ## 정해진 유스케이스 모양 (Canonical use case shape) 표와 자세한 계약은 [README.md](README.md) 「정해진 유스케이스 모양 (Canonical use case shape)」 절이다. 지킬 것: - 유스케이스는 평범한 Java이고 final이 아니다(web 어댑터가 CGLIB proxy로 `@RequiresPermission`을 강제한다). 조립 루트가 bean으로 만든다. application-core는 DI 프레임워크에 스스로 등록하지 않는다. - 상태를 바꾸면 `@RequiresPermission`, 시스템만 부르면 `@SystemInvoked(reason = ...)`를 달고 bean으로 두지 않는다. 시스템 호출자 목록의 정본은 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」다. - 일은 `TransactionPort`로 감싼다(아래 「허용하는 트랜잭션 모양」). ## 허용하는 트랜잭션 모양 (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 표와 자세한 계약은 [README.md](README.md) 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」 절이다. 지킬 것: - KEYED 유스케이스는 일을 `IdempotencyExecutor`로 감싼다. 원본 `Idempotency-Key`는 이 계층에 들이지 않고 `IdempotencyScopeDigest`만 받는다. - executor는 `composition:idempotency`가 만든다. 유스케이스나 서비스 설정에서 만들지 않는다. 운영에서 메모리 저장소는 금지다. ## 읽기·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` 반환 순수성) ## 테스트 - fake·in-memory 포트로 유스케이스 흐름을 검증한다. Spring context를 띄우지 않는다. - 포트마다 fake 하나와 추상 계약 테스트(`*Contract`)를 이 모듈 testFixtures에 둔다. 작성 규칙은 `.claude/rules/java-tests.md`다. ```bash ./gradlew :application-core:test ./gradlew :app-bootstrap:architectureTest ``` 위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox 영속, 그 밖의 메시징 R2 capability를 주장하지 않는다.