docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code 밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가 2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다 (design-docs harness/01-harness-design.md 13절 Q1·Q2). - 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리 CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서 src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져 AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는 지금처럼 그 폴더를 만질 때 규칙을 읽는다. - 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다), CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다). - 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다. 기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴 때의 경로를 그대로 둔다. - link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이 AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는 check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다. workflow는 CI 재편 몫이라 고치지 않았다. - check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다. 위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은 이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은 `git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는 가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다. 검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py, python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사 시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다. BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로 바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
This commit is contained in:
@@ -0,0 +1,336 @@
|
||||
# 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<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-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<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, 재생 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<DomainType>`) 안 된다. 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를 주장하지 않는다.
|
||||
@@ -1,336 +1 @@
|
||||
# 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<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-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<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, 재생 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<DomainType>`) 안 된다. 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를 주장하지 않는다.
|
||||
@AGENTS.md
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
애플리케이션 유스케이스 계층. 패키지 루트: `dev.caskeleton.application`.
|
||||
|
||||
허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 **모듈 규칙**은
|
||||
[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||||
[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||||
모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도
|
||||
추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user