docs(core): core·조립·빌드·플랫폼 모듈 문서를 한국어로 옮긴다
문제: core 계층(application·domain·shared-contract), app-bootstrap, composition, registry, build-logic, optional 빌드의 모듈 문서가 영어다. 세션이 처음 읽는 지역 규칙인데 소유자는 2026-11-07에 살아 있는 문서를 모두 한국어로 쓰기로 정했다. leaf CLAUDE.md 셋은 Spring Boot 버전을 4.0.0으로 복사해 두었는데 실제 버전(libs.versions.toml)과 다르다. 방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키는 말로 바꾼다. 다른 문서·코드가 제목으로 가리키는 절(application-core의 Naming convention·Package ownership·Canonical use case shape·Allowed transactional shapes, shared-contract의 Responsibility·Forbidden, messaging의 발행 재시도 절)은 영어 원제를 괄호로 남겨 그 참조가 계속 찾아지게 한다. 참조하는 쪽을 고치는 것은 이 작업 범위 밖이다. 코드와 어긋난 주장은 코드에 맞춘다: TransactionPort 구현을 `adapter-persistence`에서 `adapter:outbound:persistence-jpa`의 `SpringTransaction`으로, registry README의 빈 의존 목록 예를 persistence-mongo(실제 목록은 application-core·shared-contract)에서 domain-core·shared-contract·messaging-core-api로 고친다. TemplatePackageOwnershipDocumentTest는 표 머리 문자열로 표를 찾으므로 머리 상수를 한국어 머리(`| 패키지 (...) |`)로 맞춘다. 표와 기계 사본을 대조하는 계약은 그대로다. 위험: 영어 원제를 괄호로 남긴 제목은 참조하는 문서가 한국어 제목으로 바뀌면 괄호를 지울 수 있다. 본문의 짧은 이력 번호(07-08, 06-01, 11-M9)는 뜻을 바꾸지 않으려고 그대로 옮겼다. 검증: python3 scripts/check-docs.py rc=0(번역한 파일의 language 줄 8개, number 줄 3개 지움), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0, unittest discover scripts/tests 43개 통과.
This commit is contained in:
+230
-245
@@ -1,180 +1,173 @@
|
||||
# application-core — application use cases
|
||||
# application-core — 애플리케이션 유스케이스
|
||||
|
||||
## Registered identity
|
||||
## 등록 정보
|
||||
|
||||
- Module ID: `application-core`
|
||||
- Gradle path: `:application-core`
|
||||
- Focused test (derived from Gradle path): `./gradlew :application-core:test --console=plain`
|
||||
- Runtime baseline: Java 21; repository framework baseline: the Spring Boot 4.x version pinned by the shared version catalog.
|
||||
- Registry SSOT: `src/config/architecture/modules.json`.
|
||||
- 모듈 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`.
|
||||
|
||||
Package root: `dev.caskeleton.application`.
|
||||
패키지 루트: `dev.caskeleton.application`.
|
||||
|
||||
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
|
||||
|
||||
## Responsibility
|
||||
## 책임 (Responsibility)
|
||||
|
||||
- Use case inbound ports (`CommandUseCase`, `QueryUseCase`) and their command / query contracts.
|
||||
- Outbound ports (`*Port` interfaces) the use cases depend on.
|
||||
- Application exceptions and policy types.
|
||||
- Coordinate domain models through ports.
|
||||
- Own application transaction boundaries through the `TransactionPort` abstraction.
|
||||
- Expose framework-free invocation context through ports such as `CorrelationIdPort`; adapters own
|
||||
MDC or other concrete storage.
|
||||
- Own the framework-free semantic integration-event draft, validated-event value contract and
|
||||
exact typed payload contribution SPI. This is the messaging semantic contract R1 boundary only.
|
||||
- 유스케이스 inbound 포트(`CommandUseCase`, `QueryUseCase`)와 그 command·query 계약.
|
||||
- 유스케이스가 의존하는 outbound 포트(`*Port` 인터페이스).
|
||||
- 애플리케이션 예외와 정책 타입.
|
||||
- 포트를 거쳐 도메인 모델을 조율한다.
|
||||
- `TransactionPort` 추상화로 애플리케이션 트랜잭션 경계를 가진다.
|
||||
- `CorrelationIdPort` 같은 포트로 프레임워크 없는 호출 문맥을 내놓는다. MDC 같은 실제 저장소는
|
||||
어댑터가 가진다.
|
||||
- 프레임워크 없는 integration event 초안(semantic draft), 검증된 이벤트의 값 계약, 정확한 타입의
|
||||
payload를 내놓는 SPI를 가진다. 메시징 semantic contract R1 경계까지만이다.
|
||||
|
||||
## Allowed
|
||||
## 허용
|
||||
|
||||
- `:domain-core`
|
||||
- `:shared-contract`
|
||||
- Java standard library types.
|
||||
- Java 표준 라이브러리 타입.
|
||||
|
||||
## Forbidden
|
||||
## 금지 (Forbidden)
|
||||
|
||||
- `adapter-*` implementation classes.
|
||||
- `adapter-*` 구현 클래스.
|
||||
- `app-bootstrap`.
|
||||
- Controller request/response DTOs.
|
||||
- JPA entities and Spring Data repositories.
|
||||
- HTTP status, transport types (`org.springframework.web..`).
|
||||
- `org.springframework.transaction.annotation.Transactional` (use `TransactionPort` instead).
|
||||
- `org.springframework.context.ApplicationContext` — direct dependency forbidden
|
||||
(`getBean(Class)` reflection-style bypass blocked by the ArchUnit rule `application_does_not_depend_on_application_context`). String-key
|
||||
bean lookup / `Class.forName(String)` / `BeanFactory#getBeansOfType` remain
|
||||
ArchUnit's static-analysis blind spot — guard via code review checklist.
|
||||
- Lombok (`lombok..`) — also forbidden in `domain-core`. Within `application-core`,
|
||||
Lombok is currently not in scope for the contract; if you intend to use it,
|
||||
weigh the bytecode opacity cost first.
|
||||
- Persistence-layer transaction annotations of any kind inside this module.
|
||||
- Diagnostic frameworks (`org.slf4j`, `java.util.logging`, Logback, Log4j, Micrometer). Express
|
||||
diagnostic intent through a specific outbound `*Port`; adapters own rendering.
|
||||
- Messaging provider/runtime types: physical topic, Kafka record or metadata, JSON tree/raw JSON
|
||||
payload, serializer/schema-validator implementation, security topology and publication epoch.
|
||||
- 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.
|
||||
|
||||
## Contract types
|
||||
## 계약 타입
|
||||
|
||||
| Type | Purpose |
|
||||
| 타입 | 용도 |
|
||||
|---|---|
|
||||
| `usecase.UseCase<I, O>` | Base type for inbound ports. Concrete inbound ports MUST extend `CommandUseCase` or `QueryUseCase`. |
|
||||
| `usecase.CommandUseCase<C extends Command, R>` | Inbound port for write use cases. Implementations MUST be annotated `@UseCaseCapability`. |
|
||||
| `usecase.QueryUseCase<Q extends Query, R>` | Inbound port for read-only use cases. Implementations MUST declare `transactionMode = READ_ONLY` and `repositoryAccess = READ_REPOSITORY`. |
|
||||
| `command.Command` | Marker for write intents. Plain immutable types built from domain values. |
|
||||
| `query.Query` | Marker for read intents. Plain immutable types built from domain values. |
|
||||
| `transaction.TransactionPort` | Outbound port for join-capable write/read, physical root-only write, and independent write boundaries. Implemented by `adapter-persistence`. |
|
||||
| `secret.SecretSourcePort` | Framework-free outbound secret-resolution seam. Deployment selects a backend in app-bootstrap; concrete environment/cloud/vault readers belong to outbound adapter leaves. |
|
||||
| `transaction.NestedRootTransactionRejectedException` | Fail-fast signal raised before action/provider side effects when `inRootWrite` detects an actual ambient transaction. |
|
||||
| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED` and `NEVER` are intentionally absent. |
|
||||
| `transaction.Isolation` | `READ_COMMITTED` (pinned default) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED` is forbidden (not declared); the vendor default is never used (engine defaults differ — PostgreSQL READ COMMITTED vs MySQL InnoDB REPEATABLE READ). Routing the stricter levels through `TransactionPort` is a `planned` joint change with `feature-application-port-usecase-contract`; the shipped call path pins `READ_COMMITTED`. |
|
||||
| `capability.UseCaseCapability` | Mandatory annotation on every concrete use case: declares `transactionMode`, `idempotency`, `repositoryAccess`, `externalOutboundAllowed`. |
|
||||
| `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>` | Closed exact-record payload type, canonical component order, local schema identity/hash and provider-neutral descriptor contribution. |
|
||||
| `messaging.event.IntegrationEventDraft<P>` | Typed semantic event before local encoding; never JSON, Kafka or persistence state. Built only through `IntegrationEventDrafts` (`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). |
|
||||
| `messaging.event.IntegrationEventDrafts` | The one way a feature builds a draft: contract id, version and destination from the contract, correlation from the request when canonical (else the event id), `SINGLE_TENANT_SCOPE` for a feature without tenants. |
|
||||
| `messaging.event.IntegrationIdentity` | The one grammar and the length bounds of event, correlation/causation and aggregate ids. Test a value with `isCanonical(value, bound)`; never copy the pattern. |
|
||||
| `messaging.event.ValidatedIntegrationEvent` | Stable semantic identities plus immutable exact encoded bytes and hashes, ready for a later durable append boundary. |
|
||||
| `messaging.event.IntegrationEventEncoderPort` | Framework-free local draft-to-validated-event boundary implemented by an outbound adapter (the template's: `adapter:outbound:support` `JsonIntegrationEventEncoder`). |
|
||||
| `outbox.OutboxAppendPort` | The one outbox append: a `ValidatedIntegrationEvent`, in the caller's write transaction. |
|
||||
| `tenant.TenantId` | The tenant identifier and its one grammar (`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`); the web and GraphQL transport contexts both carry it. Built by a transport from verified authentication data only. |
|
||||
| `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 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. |
|
||||
|
||||
## Notification (NOTIF-ADR-005)
|
||||
## 알림 (NOTIF-ADR-005)
|
||||
|
||||
None of the notification types are in this leaf. `..notification.platform..` and the simple
|
||||
`NotificationPort`, `Notification` and `NotificationChannel` directly under
|
||||
`dev.caskeleton.application.notification` all belong to leaf `application-notification`; the shared
|
||||
package prefix is the only link. The R1 orchestration types were removed on 2026-09-25.
|
||||
알림 타입은 이 leaf에 하나도 없다. `..notification.platform..`과
|
||||
`dev.caskeleton.application.notification` 바로 아래의 단순한 `NotificationPort`, `Notification`,
|
||||
`NotificationChannel`은 모두 leaf `application-notification`의 것이다. 패키지 접두어가 같은 것이
|
||||
유일한 연결이다. R1 조율 타입은 2026-09-25에 지웠다.
|
||||
|
||||
## Naming convention
|
||||
## 이름 규칙 (Naming convention)
|
||||
|
||||
This section is the repository's naming rule book. `NamingConventionTest` (app-bootstrap
|
||||
architectureTest) enforces the machine-checkable rows; the rest are review rules, and a review checks
|
||||
them against this table. A new feature follows the "new code" column; the "existing exceptions" are
|
||||
named so nobody copies them by accident.
|
||||
이 절이 저장소의 이름 규칙 정본이다. 기계로 볼 수 있는 행은 `NamingConventionTest`(app-bootstrap
|
||||
architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 이 표와 대조한다. 새 기능은 「새 코드」
|
||||
열을 따른다. 「이미 있는 예외」는 누가 실수로 따라 하지 않게 이름을 적어 둔 것이다.
|
||||
|
||||
| Role | Name | Where | Existing exceptions (do not copy) |
|
||||
| 역할 | 이름 | 위치 | 이미 있는 예외(따라 하지 않는다) |
|
||||
|---|---|---|---|
|
||||
| Use case (inbound port implementation) | `<Verb><Noun>UseCase`, enforced by ArchUnit | `application` package of the feature | `*ApplicationUseCase` (application-fileserver, application-notification), `*Service` (notification, fileserver) |
|
||||
| Command / query record | `*Command` / `*Query` | next to its use case | — |
|
||||
| Aggregate persistence (stores and returns whole aggregates) | `<Aggregate>Repository` | **domain** package of the aggregate, owned by the domain | — |
|
||||
| Technical store the application owns (outbox, idempotency, operation rows) | `<Thing>StorePort` | application package | `*WritePort` (old onboarding fixture, removed) |
|
||||
| Read model that returns projections, not aggregates | `<Thing>QueryPort` | application package; returns projections only (ArchUnit) | — |
|
||||
| Any other outbound port | `<Capability>Port` | application package | — |
|
||||
| Server-assigned id generation | `<Aggregate>IdFactory extends IdFactory<<Aggregate>Id>` | domain package; the id record `implements ResourceId<Self>` | `OutboxEventIdFactory` (sample; event ids are not resource ids) |
|
||||
| Configuration binding | `*Settings` (operational) or `*Policy` (authorization / domain policy), enforced by ArchUnit | the leaf that binds it | — |
|
||||
| Throwable | `*Exception`, enforced by ArchUnit | — | — |
|
||||
| Contract test kit for a port | abstract `<Port>Contract` in the port owner's testFixtures; the fake's and each adapter's test extend it | testFixtures | value-type tests were once named `*ContractTest`; they are `*ValueTypesTest` now |
|
||||
| 유스케이스(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`다 |
|
||||
|
||||
The one-line rule for stores: **if the domain would recognise the thing it stores, it is a
|
||||
`Repository` in the domain; if it is plumbing the application needs, it is a `StorePort` in the
|
||||
application.**
|
||||
저장소의 한 줄 규칙: **도메인이 알아볼 만한 것을 저장하면 도메인의 `Repository`다. 애플리케이션에
|
||||
필요한 배관이면 application의 `StorePort`다.**
|
||||
|
||||
## Package ownership
|
||||
## 패키지 소유 (Package ownership)
|
||||
|
||||
This section is the rule book for **which packages the template owns** and where a business feature
|
||||
goes. `docs/manual/03-placement.md` points here.
|
||||
이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다.
|
||||
`docs/manual/03-placement.md`가 이곳을 가리킨다.
|
||||
|
||||
- A business feature is `dev.caskeleton.application.<feature>` (and `dev.caskeleton.domain.<feature>`,
|
||||
`...adapter.inbound.web.<feature>`, `...bootstrap.autoconfigure.<feature>`): one package per feature
|
||||
directly under each root, no `command`/`usecase`/`port` sub-packages.
|
||||
- `<feature>` is **not** one of the template package names below. A feature beside a template
|
||||
package of the same name lands in the same package tree, and every upstream template update merges
|
||||
into it.
|
||||
- Template packages never import a feature package. Business code does not go into a template
|
||||
package, even when the name fits.
|
||||
- Everything under the two roots that is not listed here is a feature. A derived service adds
|
||||
features without editing this list; the template edits it when it adds, renames or removes one of
|
||||
its own packages.
|
||||
- 업무 기능은 `dev.caskeleton.application.<feature>`다(그리고 `dev.caskeleton.domain.<feature>`,
|
||||
`...adapter.inbound.web.<feature>`, `...bootstrap.autoconfigure.<feature>`). 루트마다 바로 아래에
|
||||
기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다.
|
||||
- `<feature>`는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔
|
||||
기능은 같은 패키지 트리에 들어가고, upstream 템플릿 갱신이 올 때마다 그 기능에 섞여 들어간다.
|
||||
- 템플릿 패키지는 기능 패키지를 import하지 않는다. 이름이 맞아도 업무 코드를 템플릿 패키지에 넣지
|
||||
않는다.
|
||||
- 두 루트 아래에서 여기 적히지 않은 것은 모두 기능이다. 파생 서비스는 이 목록을 고치지 않고 기능을
|
||||
더한다. 템플릿은 자기 패키지를 더하거나, 이름을 바꾸거나, 지울 때 이 목록을 고친다.
|
||||
|
||||
| Package (`dev.caskeleton.application.*`) | Owning leaf | Holds |
|
||||
| 패키지 (`dev.caskeleton.application.*`) | 소유 leaf | 담는 것 |
|
||||
|---|---|---|
|
||||
| `usecase`, `command`, `query` | application-core | inbound port base types and the command/query markers |
|
||||
| `capability` | application-core | `@UseCaseCapability` and its enums |
|
||||
| `transaction` | application-core | `TransactionPort` and its modes |
|
||||
| `security` | application-core | authorization port, `@RequiresPermission`, `@SystemInvoked`, `@SystemCaller`, `ObjectAccessPolicy` |
|
||||
| `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 | the integration-event semantic contract |
|
||||
| `outbox` | application-core | transactional outbox append and relay |
|
||||
| `idempotency` | application-core | keyed idempotency executor and store port |
|
||||
| `operation` | application-core | durable (long-running) operations |
|
||||
| `lease`, `lock` | application-core | distributed lease and lock ports |
|
||||
| `cache` | application-core | cache region port |
|
||||
| `realtime` | application-core | live event replay port |
|
||||
| `notification` | application-notification | notification capability |
|
||||
| `fileserver` | application-fileserver | file server capability |
|
||||
| `objectstorage` | application-objectstorage | object storage capability (its `content.CallBudget` is the call deadline it carries) |
|
||||
| `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`은 그것이 싣는 호출 기한이다) |
|
||||
|
||||
| Package (`dev.caskeleton.domain.*`) | Owning leaf | Holds |
|
||||
| 패키지 (`dev.caskeleton.domain.*`) | 소유 leaf | 담는 것 |
|
||||
|---|---|---|
|
||||
| `identifier` | domain-core | `ResourceId`, `IdFactory` |
|
||||
| `stereotype` | domain-core | `@AggregateRoot`, `@DomainEvent`, `@ValueObject` |
|
||||
|
||||
Enforcement:
|
||||
강제하는 곳:
|
||||
|
||||
- `scripts/new-feature.sh` refuses a feature name that is already a package under any of the five
|
||||
roots, in any leaf — every template package included.
|
||||
- `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`: a feature package
|
||||
under either root does not take a name from these tables. Every feature has a domain package, so a
|
||||
feature named `operation` is caught at `dev.caskeleton.domain.operation`.
|
||||
- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: a feature class written
|
||||
into a template package keeps the template's name but imports its own domain, and that import is
|
||||
what fails.
|
||||
- These tables are the rule book; the machine copy the rules read is `TemplatePackageOwnership`
|
||||
(app-bootstrap `src/test`, so both the architecture suite and the document-contract lane see it).
|
||||
`TemplatePackageOwnershipDocumentTest` (document-contract lane, `mainCheck`) fails when the tables
|
||||
and that class differ in a package name or owning leaf, or when a listed package is not in the
|
||||
leaf the table names; `TemplatePackageOwnershipRuleTest` (architectureTest) fails when a listed
|
||||
name exists in no production class. A new template package joins both in the same change.
|
||||
- Not caught: a new template package that nobody lists. Features are generated into the same leaves
|
||||
(`scripts/new-feature.sh`), so an unlisted package is indistinguishable from a feature. Listing it
|
||||
is part of adding it.
|
||||
- Rejected alternatives: allowing only the listed top-level packages (every derived feature would
|
||||
have to edit the template's list — a merge conflict per feature), and a separate
|
||||
`application-platform` leaf for the platform packages (weighed in the 2026-11-01 maturity review: clearer
|
||||
boundary, but more registry edges than a naming rule needs).
|
||||
- `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
|
||||
## 정해진 유스케이스 모양 (Canonical use case shape)
|
||||
|
||||
```java
|
||||
@RequiresPermission("user:register")
|
||||
@@ -201,135 +194,127 @@ public class RegisterUserUseCase implements CommandUseCase<RegisterUserCommand,
|
||||
}
|
||||
```
|
||||
|
||||
The class is plain Java. A composition root constructs it with its ports and configuration values;
|
||||
application-core never self-registers with a DI framework. It is **not final**: a mutating use case
|
||||
declares `@RequiresPermission`, the web adapter enforces it through a CGLIB proxy, and CGLIB cannot
|
||||
subclass a final class (`RequiresPermissionProxyabilityTest`). It is registered as a bean for the
|
||||
same reason — a use case built with `new` is never checked. A use case only the system calls (a
|
||||
scheduler, a relay, a message consumer) carries `@SystemInvoked(reason = ...)` instead of a
|
||||
permission and is not a bean: it is a write with no permission check, so no user request may reach
|
||||
it. Its system caller constructs it — a composition module for a scheduler, a
|
||||
`@SystemCaller(reason = ...)` message handler in `..adapter.inbound.messaging..`, or a
|
||||
`@SystemCaller` scheduled job in the service's own `..adapter.inbound.scheduler..` package. Manual
|
||||
07 「시스템이 부르는 쓰기」 is the canonical list of the three and where each lives. All of it is
|
||||
enforced — a `@SystemInvoked` bean fails startup, an inbound adapter that depends on one without
|
||||
being a `@SystemCaller` fails `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`,
|
||||
`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS` keeps the mark (and classes nested in a marked
|
||||
one) off user transports, `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS` keeps a user transport
|
||||
from calling a system caller (by its class or by a project interface it implements), and
|
||||
`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES` keeps a system caller from being a `Runnable` or any
|
||||
other type outside the project, which no dependency rule could follow. Paths that name no type (a
|
||||
bean looked up by name, a function a configuration hands over) are not seen; manual 07 lists them
|
||||
and what holds them. A composition with `@RequiresPermission`
|
||||
beans but no enforcing advisor fails startup too (`composition:service-runtime`
|
||||
`PermissionEnforcementGuard`, both checks).
|
||||
이 클래스는 평범한 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
|
||||
## 허용하는 트랜잭션 모양 (Allowed transactional shapes)
|
||||
|
||||
| Use case shape | `transactionMode` | TransactionPort call | When |
|
||||
| 유스케이스 모양 | `transactionMode` | TransactionPort 호출 | 언제 |
|
||||
|---|---|---|---|
|
||||
| Write command | `WRITE` | `tx.inWrite(...)` | Default for `CommandUseCase`. |
|
||||
| Physical-root write command | `WRITE` | `tx.inRootWrite(...)` | Only when orchestration must prove there is no ambient transaction and expose a result after commit. |
|
||||
| Read-only query | `READ_ONLY` | `tx.inRead(...)` | Default for `QueryUseCase`. |
|
||||
| Outbox / audit / compensation | `REQUIRES_NEW` | `tx.inNew(...)` | Only when the use case MUST commit independently of the caller. |
|
||||
| 쓰기 command | `WRITE` | `tx.inWrite(...)` | `CommandUseCase`의 기본. |
|
||||
| 물리 루트 쓰기 command | `WRITE` | `tx.inRootWrite(...)` | 바깥 트랜잭션이 없음을 증명하고 커밋 뒤에 결과를 내놓아야 하는 조율일 때만. |
|
||||
| 읽기 전용 query | `READ_ONLY` | `tx.inRead(...)` | `QueryUseCase`의 기본. |
|
||||
| outbox·감사·보상 | `REQUIRES_NEW` | `tx.inNew(...)` | 유스케이스가 반드시 호출자와 따로 커밋해야 할 때만. |
|
||||
|
||||
`NESTED` and `NEVER` propagation are forbidden.
|
||||
`inRootWrite` MUST reject an actual ambient transaction before invoking its action or
|
||||
`PlatformTransactionManager`; it MUST NOT emulate root-only behavior with `REQUIRES_NEW`.
|
||||
Both `inWrite` and `inRootWrite` satisfy the direct boundary fitness rule for a
|
||||
`WRITE_REPOSITORY + WRITE` use case. READ and REQUIRES_NEW mappings remain exclusive.
|
||||
`NESTED`와 `NEVER` 전파는 금지다.
|
||||
`inRootWrite`는 action이나 `PlatformTransactionManager`를 부르기 전에 실제로 열린 바깥 트랜잭션을
|
||||
반드시 거절한다. 루트 전용 동작을 `REQUIRES_NEW`로 흉내 내면 안 된다.
|
||||
`WRITE_REPOSITORY + WRITE` 유스케이스의 직접 경계 적합성 규칙은 `inWrite`와 `inRootWrite`가 모두
|
||||
만족한다. READ와 REQUIRES_NEW의 대응은 계속 서로 배타적이다.
|
||||
|
||||
### Callback signature contract
|
||||
### 콜백 시그니처 계약
|
||||
|
||||
`TransactionPort` callbacks are `Supplier<T>` / `Runnable` and cannot throw checked
|
||||
exceptions. This matches Spring's `TransactionCallback<T>` constraint. Wrap domain
|
||||
checked exceptions into `RuntimeException` subclasses
|
||||
(`DomainException extends RuntimeException`); `IOException` → `UncheckedIOException`;
|
||||
`SQLException` is auto-translated by Spring's `DataAccessException` hierarchy.
|
||||
`TransactionPort` 콜백은 `Supplier<T>` / `Runnable`이라 checked 예외를 던지지 못한다. Spring
|
||||
`TransactionCallback<T>`의 제약과 같다. 도메인의 checked 예외는 `RuntimeException` 하위 클래스로
|
||||
감싼다(`DomainException extends RuntimeException`). `IOException`은 `UncheckedIOException`으로
|
||||
감싼다. `SQLException`은 Spring의 `DataAccessException` 계층이 자동으로 번역한다.
|
||||
|
||||
### `inNew` pool-sizing constraint
|
||||
### `inNew` 풀 크기 제약
|
||||
|
||||
`inNew` acquires a new physical JDBC connection. Pool size MUST satisfy:
|
||||
`inNew`는 새 물리 JDBC 연결을 얻는다. 풀 크기는 반드시 다음을 만족한다.
|
||||
|
||||
```
|
||||
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
|
||||
```
|
||||
|
||||
**Forbidden**: calling `tx.inNew(...)` inside a loop over many records — pool
|
||||
exhaustion + deadlock risk. Batch records inside ONE `inNew` call, or move the
|
||||
loop outside the transaction boundary.
|
||||
**금지**: 많은 레코드를 도는 반복문 안에서 `tx.inNew(...)`를 부른다 — 풀이 바닥나고 교착이 생길
|
||||
수 있다. 레코드를 `inNew` 호출 **하나** 안에서 묶어 처리하거나, 반복문을 트랜잭션 경계 밖으로 뺀다.
|
||||
|
||||
## Idempotency (KEYED) — feature-rate-limit-idempotency-contract
|
||||
## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract
|
||||
|
||||
`@UseCaseCapability(idempotency = Idempotency.KEYED)` is **supported**. A KEYED use case wraps
|
||||
its work with `dev.caskeleton.application.idempotency.IdempotencyExecutor` — the one owner-safe
|
||||
generation; the V1 `IdempotencyScope`/`tryBegin` API is gone.
|
||||
`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을
|
||||
`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는
|
||||
유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다.
|
||||
|
||||
- **Scope**: the caller passes an `IdempotencyScopeDigest` — a versioned HMAC of
|
||||
principal + client key + operation code, computed before the executor sees it. The raw
|
||||
`Idempotency-Key` never reaches this layer or the store.
|
||||
- **Store**: `IdempotencyStorePort`, contributed by exactly one provider selected with
|
||||
`app.capabilities.idempotency.provider` (`redis` → `cache-redis`, `postgresql` →
|
||||
`persistence-jpa`; default `disabled`). In-memory prod storage is forbidden.
|
||||
- **Executor**: built once by `composition:idempotency` `IdempotencyAutoConfiguration` from
|
||||
`IdempotencySettings` (processing lease 30s, replay TTL `APP_IDEMPOTENCY_TTL` 24h ≤72h and not
|
||||
shorter than the lease, failure retention 24h and not shorter than the replay TTL). Do not
|
||||
construct it in a use case or a service's own config.
|
||||
- The action returns `IdempotentAction.Outcome` (`Success` / `RetryableNoEffect` /
|
||||
`EffectUnknown`); a thrown exception counts as effect-unknown. In progress → 409
|
||||
`IDEMPOTENT_IN_FLIGHT`, fingerprint mismatch (SHA-256) → 422 `IDEMPOTENT_REQUEST_MISMATCH`;
|
||||
`IdempotencyUnavailableException` and `IdempotencyRecoveryRequiredException` mean the store
|
||||
could not prove the outcome, so do not blindly retry.
|
||||
- Every store answers an execution whose processing lease ran out with `RecoveryRequired` and never
|
||||
takes it over; only a claim that never started or a retryable failure is taken over. The answer
|
||||
leaves the record to its holder: the holder's first late `complete`/`markFailed` is recorded, a
|
||||
lease that ran out is not renewed and a claim whose lease ran out is not started — both answer
|
||||
`LEASE_EXPIRED`, not `NOT_OWNER`, and the executor turns a refused start into "not applied"
|
||||
(owner decision 2026-11-04). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
|
||||
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases.
|
||||
- Every transition names the operation its record was claimed under (`IdempotencyOwner.claimOperationId()`).
|
||||
Another one is `OPERATION_CONFLICT` in every store and changes nothing; so is an inspection that
|
||||
brings the owner token under another operation (owner decision 2026-11-06).
|
||||
- A transition already applied is confirmed ("already …") only to the handle it was applied from —
|
||||
the record one revision past it, moved there by that kind of transition. Any other handle is
|
||||
`NOT_OWNER`, the same attempt's handle from before a takeover included, and so is a start through
|
||||
the handle a renewal was applied from; a start through a released handle is `ABSENT` or
|
||||
`NOT_OWNER` by whether the store keeps the released record (owner decision 2026-11-06,
|
||||
- **범위(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`).
|
||||
- The applying handle resending `markFailed` with another disposition is `OPERATION_CONFLICT` and
|
||||
the recorded failure stays; with only another retention it is `ALREADY_MARKED_SAME_OPERATION` and
|
||||
the first retention stays — retention, like a completion's replay TTL, is not compared (owner
|
||||
decision 2026-11-07).
|
||||
- 적용한 handle이 다른 disposition으로 `markFailed`를 다시 보내면 `OPERATION_CONFLICT`이고 기록된
|
||||
실패가 남는다. retention만 다르면 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다 —
|
||||
retention은 완료의 재생 TTL처럼 비교하지 않는다(소유자 결정 2026-11-07).
|
||||
|
||||
The former ArchUnit freeze rule `inbound_port_implementations_do_not_declare_keyed_idempotency`
|
||||
and its fixture were removed when this branch merged.
|
||||
예전 ArchUnit 동결 규칙 `inbound_port_implementations_do_not_declare_keyed_idempotency`와 그 fixture는
|
||||
이 브랜치가 병합될 때 지웠다.
|
||||
|
||||
## Read / query path (feature-application-query-bypass-contract)
|
||||
## 읽기·query 경로 (feature-application-query-bypass-contract)
|
||||
|
||||
The read side has two equally-valid shapes; pick per read, do not force one:
|
||||
읽기 쪽에는 똑같이 유효한 모양이 둘 있다. 읽기마다 고르고, 하나를 강요하지 않는다.
|
||||
|
||||
| Shape | Returns | When | How |
|
||||
| 모양 | 돌려주는 것 | 언제 | 어떻게 |
|
||||
|---|---|---|---|
|
||||
| **Through-aggregate** (default for simple reads) | domain aggregate via a `*Repository` port | read shape == write aggregate **and** the aggregate is the minimal invariant boundary (no lazy collections needed) | `QueryUseCase` → repository port → `Order` |
|
||||
| **Projection (CQRS-lite)** | application-layer projection DTO via a `*QueryPort` | read shape ≠ write, or to skip aggregate hydration / lazy-collection joins | `QueryUseCase` → `*QueryPort` → `OrderSummary` (record); query via JPQL `SELECT new` / JdbcTemplate |
|
||||
| **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 |
|
||||
|
||||
- **Purity guardrail (core, machine-enforced):** a read port whose simple name ends
|
||||
with `QueryPort` MUST return application-layer projection DTOs only — never a domain
|
||||
aggregate, JPA entity, or web type, **including through generic type arguments**
|
||||
(`List<DomainType>`). Enforced by ArchUnit `query_ports_do_not_leak_domain_jpa_or_web_types`.
|
||||
Projection usage itself is **opt-in**, not a forced default.
|
||||
- **Strict ceremony:** every read goes through a `QueryUseCase` bean. There is no thin
|
||||
web→read-port path — that would bypass the mandatory `@UseCaseCapability` fitness function.
|
||||
- **Transaction:** reads default to `TransactionPort.inRead`. A no-tx (autocommit) read
|
||||
is an opt-in only when `spring.jpa.open-in-view=false` is confirmed **and** the read is
|
||||
projection-only (no lazy access) **and** a single statement; otherwise keep `inRead`.
|
||||
- **Capability:** a repository-backed projection read is still
|
||||
`repositoryAccess = READ_REPOSITORY`. "Projection vs aggregate" is the return *shape* axis,
|
||||
orthogonal to the repository-access *level* axis — no new enum. Outbound-HTTP reads (no
|
||||
repository) stay `RepositoryAccess.NONE`.
|
||||
- Full CQRS with a separate physical read store is out of scope — escalation only.
|
||||
- **순수성 가드레일(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 guardrails (enforced)
|
||||
## ArchUnit 가드레일(강제됨)
|
||||
|
||||
- `application_does_not_depend_on_adapters_or_transport`
|
||||
- `application_does_not_use_spring_transactional_annotation`
|
||||
@@ -337,9 +322,9 @@ The read side has two equally-valid shapes; pick per read, do not force one:
|
||||
- `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` return purity)
|
||||
- `query_ports_do_not_leak_domain_jpa_or_web_types`(`*QueryPort` 반환 순수성)
|
||||
|
||||
## Test
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
cd src
|
||||
@@ -347,5 +332,5 @@ cd src
|
||||
./gradlew :app-bootstrap:architectureTest
|
||||
```
|
||||
|
||||
The messaging types above establish semantic contract R1 only. They do not claim JSON Schema
|
||||
qualification, Kafka publication, durable outbox persistence or any messaging R2 capability.
|
||||
위 메시징 타입은 semantic contract R1까지만 세운다. JSON Schema 검증, Kafka 발행, durable outbox
|
||||
영속, 그 밖의 메시징 R2 capability를 주장하지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user