문제: 앞 커밋이 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
144 lines
8.8 KiB
Markdown
144 lines
8.8 KiB
Markdown
# 02. 새 도메인·유스케이스 추가
|
|
|
|
## 핵심
|
|
|
|
안쪽 계층부터 바깥으로 만든다. 각 단계는 그 단계의 테스트까지 끝내고 다음으로 간다.
|
|
생성 명령(01장)이 1~5단계의 뼈대를 만들고, 이 장은 각 단계에서 사람이 정할 것을 적는다.
|
|
|
|
```text
|
|
1 domain-core ─▶ 2 application-core ─▶ 3 outbound adapter ─▶ 4 inbound adapter ─▶ 5 app-bootstrap
|
|
모델·불변식 유스케이스·포트 저장·외부 연동 전송·DTO·오류 bean·조건·권한
|
|
(Java만) (Java + 계약 타입) (Spring·JPA 등) (HTTP 등) (조립)
|
|
```
|
|
|
|
바깥 계층은 안쪽을 알지만 안쪽은 바깥을 모른다. 그래서 안쪽부터 만들면 각 단계가 앞 단계만 보고
|
|
컴파일된다. 한 단계가 다른 leaf나 계층을 고쳐야 하면 거기서 멈추고 설계를 다시 본다
|
|
([새 기능 playbook](../work/new-feature.md) 「하지 말 것」).
|
|
|
|
## 0단계 — 배치를 정한다
|
|
|
|
먼저 03장으로 이 기능을 어디 둘지 정한다. 기본은 계층 leaf 안 `<feature>` 패키지다. 생성 명령은 이
|
|
기본값만 만든다.
|
|
|
|
## 1단계 — domain-core: 모델과 불변식
|
|
|
|
만드는 것: aggregate(`@AggregateRoot`), id(`@ValueObject` record, `ResourceId`), id 생성 포트
|
|
(`IdFactory` 상속), 저장 포트(`*Repository`), 불변식 예외(`Reason` enum).
|
|
예: 생성 결과 `src/domain/core/src/main/java/dev/caskeleton/domain/<f>/`.
|
|
|
|
검사: `DomainPurityArchitectureTest`(Spring·JPA·전송 타입 금지, setter 비공개, 감사 필드 금지),
|
|
`ForbiddenApiArchitectureTest.NO_LONG_ID_PK`.
|
|
|
|
### 판단: id를 누가 만드나
|
|
|
|
- **고르는 기준**: 클라이언트가 같은 요청을 다시 보낼 때 같은 리소스를 가리켜야 하는가.
|
|
- **기본값**: 서버가 만든다. domain `XIdFactory extends IdFactory<XId>` + `adapter:outbound:identifier`
|
|
구현. 문법은 id 값 객체 생성자에서 검사한다.
|
|
- **예외**: 클라이언트가 자연 키(주문번호 등)를 주는 기능은 그 키를 id로 쓴다. 이때 중복은 DB 유일성
|
|
제약이 막는다(04장). UUIDv7이 필요하면 `src/adapter/outbound/identifier/src/main/java/dev/caskeleton/adapter/outbound/identifier/UuidV7DurableOperationIdFactory.java`처럼 바꾼다.
|
|
|
|
### 판단: 불변식을 어디 두나
|
|
|
|
- **고르는 기준**: 규칙이 aggregate 하나의 상태만 보고 판정되는가.
|
|
- **기본값**: aggregate 메서드·팩토리 안. 위반은 `XInvariantException(Reason)`.
|
|
- **예외**: 둘 이상의 aggregate나 저장된 다른 행을 봐야 하는 규칙(중복 금지 등)은 유스케이스 + DB 제약.
|
|
조회 후 insert만으로는 동시 요청에서 깨진다(04장).
|
|
|
|
### 판단: 저장 포트를 누가 소유하나
|
|
|
|
- **고르는 기준**: 포트가 aggregate 단위로 말하는가, 기술적 저장·조회인가.
|
|
- **기본값**: aggregate를 통째로 저장·로드하면 domain 소유 `XRepository`.
|
|
- **예외**: 읽기 모양이 aggregate와 다르면 application 소유 `XQueryPort` + projection(record).
|
|
`QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 반환 타입을 검사한다. lease·claim 같은 기술
|
|
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application/core/AGENTS.md`.
|
|
|
|
## 2단계 — application-core: 유스케이스와 포트
|
|
|
|
만드는 것: command/query record, 유스케이스(쓰기 `CommandUseCase`, 읽기 `QueryUseCase`), 반환용 view
|
|
record, 오류 코드 enum과 carrier 예외. 예: `src/application/core/src/main/java/dev/caskeleton/application/<f>/`.
|
|
|
|
필수 선언(ArchUnit이 강제, `ApplicationBoundaryArchitectureTest`):
|
|
|
|
- 모든 유스케이스에 `@UseCaseCapability(transactionMode, idempotency, repositoryAccess)`. 선언과
|
|
실제 `TransactionPort` 호출이 맞아야 한다(`USE_CASE_CAPABILITY_MATCHES_TRANSACTION_PORT_BOUNDARY`).
|
|
- 쓰기 유스케이스에 `@RequiresPermission("<resource>:<action>")`(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`).
|
|
- 유스케이스 클래스는 `final`이 아니다. 권한 프록시가 하위 클래스를 만든다
|
|
(`src/bootstrap/app/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java`).
|
|
|
|
### 판단: 트랜잭션 모양
|
|
|
|
- **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
|
|
- **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`.
|
|
- **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만
|
|
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application/core/AGENTS.md`
|
|
「Allowed transactional shapes」.
|
|
|
|
### 판단: 무엇을 반환하나
|
|
|
|
- **기본값**: application view record(`XView`). 전송 계층이 aggregate를 받지 않는다
|
|
(`TypeBoundaryArchitectureTest.CONTROLLERS_DO_NOT_RETURN_DOMAIN_OR_ENTITY_TYPES`).
|
|
- **예외**: 같은 leaf 안 다른 유스케이스가 aggregate를 이어 받아야 하면 aggregate를 반환해도 된다.
|
|
컨트롤러는 그때도 응답 DTO로 바꾼다.
|
|
|
|
### 판단: 멱등성 선언
|
|
|
|
05장. 기본값 `NOT_IDEMPOTENT`(쓰기), `IDEMPOTENT`(읽기). 클라이언트가 재전송할 수 있는 결제·주문류
|
|
쓰기는 `KEYED`.
|
|
|
|
## 3단계 — outbound adapter
|
|
|
|
만드는 것: 포트 구현. 생성 명령은 id adapter(`adapter:outbound:identifier/<f>/Uuid<F>IdFactory`)만
|
|
만든다. 저장 adapter는 04장 순서로 직접 만든다.
|
|
|
|
필수: adapter는 포트 소유자 testFixtures의 `XRepositoryContract`를 실제 저장소로 상속하는 테스트를
|
|
가진다(08장). 실 DB가 필요하면 strict lane(`integrationTest` 등)에 둔다.
|
|
|
|
## 4단계 — inbound adapter (HTTP)
|
|
|
|
만드는 것: 컨트롤러, 요청·응답 DTO. 예: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/<f>/`.
|
|
|
|
- 컨트롤러는 변환만 한다: 요청 → command/query → 유스케이스 → `Envelope.ok(응답 DTO, ResponseMetaFactory.fromMdc())`.
|
|
repository·엔티티 직접 사용 금지(`CONTROLLERS_DO_NOT_ACCESS_REPOSITORIES_OR_JPA_ENTITIES`).
|
|
- 생성 201은 `Location` 헤더를 준다. 비동기 수락은 202(`DurableOperationController`).
|
|
- 경로는 lowerCamel 복수형(AIP-122).
|
|
- 실패는 던지기만 한다. `ApiErrorCarrier`를 전역 핸들러가 매핑한다(06장). 기능 전용 핸들러를 만들지 않는다.
|
|
|
|
### 판단: 입력 검증을 어디서 하나
|
|
|
|
- **고르는 기준**: 규칙이 도메인 규칙인가, wire 모양(형식·필수 키)인가.
|
|
- **기본값**: 도메인 규칙은 aggregate가 한 번만 검사한다. DTO에 같은 규칙을 bean validation으로 또 쓰지
|
|
않는다(두 벌이 갈라진다).
|
|
- **예외**: 도메인이 볼 수 없는 wire 모양 — 크기 상한, 형식 패턴, 필수 키 — 은 DTO에
|
|
`@NotNull`·`@Size`·`@Pattern`으로 둔다(`SubmitOperationHttpRequest`). 이것은 400 `VALIDATION_FAILED`로 나간다.
|
|
|
|
## 5단계 — app-bootstrap 조립
|
|
|
|
만드는 것: `@AutoConfiguration` 클래스 하나 + `AutoConfiguration.imports` 한 줄.
|
|
예: `src/bootstrap/durable-operation/src/main/java/dev/caskeleton/composition/operation/DurableOperationAutoConfiguration.java`.
|
|
|
|
- `@ConditionalOnBean(필요한 포트들)`: 포트 구현이 없으면 기능 전체가 없다.
|
|
- 유스케이스는 `@Bean`으로 만든다. 직접 `new` 하면 권한 프록시가 없어 `@RequiresPermission`이 조용히
|
|
빠진다.
|
|
- 컨트롤러는 component scan이 아니라 `@Import`로 등록한다. scan은 `dev.caskeleton.bootstrap`만 본다
|
|
(`CaSkeletonApplication`).
|
|
- 포트 구현이 다른 자동 설정에서 오면 `afterName`으로 순서를 적는다. 안 적으면 조건이 그 bean을 못 본다.
|
|
- 이벤트를 내면 계약 contribution도 `@Bean`으로 등록한다(09장).
|
|
- 역할 → 권한 매핑을 `app.authz.role-permissions`에 더한다(07장).
|
|
|
|
## 6단계 — 공개 계약이 바뀌었으면 함께 고친다
|
|
|
|
| 바뀐 것 | 같이 할 것 |
|
|
| --- | --- |
|
|
| 새 공개 경로(인증 없이 열림) | `docs/security/public-paths-snapshot.txt`, `./gradlew verifyPublicPathSnapshot` |
|
|
| 새 env 키 | `docs/registries/env-keys.yaml`, `./gradlew :app-bootstrap:verifyEnvKeys` |
|
|
| 새 의존성 | lockfile 갱신(`./gradlew :<leaf>:resolveAndLockAll --write-locks`), `verifyDependencyLocks` |
|
|
| 새 마이그레이션 | 04장 번호 규칙 |
|
|
| 새 이벤트 계약 | 09장 |
|
|
|
|
## 지금 이해하면 되는 것
|
|
|
|
- 안쪽부터: domain → application → outbound → inbound → bootstrap.
|
|
- 쓰기 유스케이스는 non-final + `@RequiresPermission` + bean. 셋 중 하나라도 빠지면 권한 검사가 없다.
|
|
- 조립은 포트가 있을 때만 켜진다. 저장 adapter가 생기기 전 기능은 없는 상태다.
|
|
- 같은 규칙을 두 곳에 쓰지 않는다. 도메인 규칙은 aggregate, wire 모양은 DTO.
|