문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
13 KiB
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 가 모아둔다 (이 문서는 모듈 규칙 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 「계약 타입」 절이다. 지킬 것:
- 구체 inbound 포트는
CommandUseCase나QueryUseCase를 상속하고, 그 구현은@UseCaseCapability를 단다(ArchUnitINBOUND_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 포트 구현) | <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)
표와 자세한 계약은 README.md 「패키지 소유 (Package ownership)」 절이다. 그 표가 템플릿 패키지 목록의 정본이다. 지킬 것:
- 업무 기능은 루트마다 바로 아래에 기능 하나당 패키지 하나다(
dev.caskeleton.application.<feature>,dev.caskeleton.domain.<feature>등).command·usecase·port하위 패키지를 두지 않는다. <feature>는 템플릿 패키지 이름이 아니다. 업무 코드를 템플릿 패키지에 넣지 않고, 템플릿 패키지는 기능 패키지를 import하지 않는다(NamingConventionTest).- 템플릿 패키지를 더하거나 이름을 바꾸거나 지우면 README 표와
TemplatePackageOwnership을 같은 변경에서 고친다.TemplatePackageOwnershipDocumentTest가 둘을 대조한다.
정해진 유스케이스 모양 (Canonical use case shape)
표와 자세한 계약은 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<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
표와 자세한 계약은 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<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반환 순수성)
테스트
- fake·in-memory 포트로 유스케이스 흐름을 검증한다. Spring context를 띄우지 않는다.
- 포트마다 fake 하나와 추상 계약 테스트(
*Contract)를 이 모듈 testFixtures에 둔다. 작성 규칙은.claude/rules/java-tests.md다.
./gradlew :application-core:test
./gradlew :app-bootstrap:architectureTest
위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox 영속, 그 밖의 메시징 R2 capability를 주장하지 않는다.