문제 (재리뷰 round7 영속성 RR7-03-01~05) - 실패한 동시 인덱스 마이그레이션의 복구를 가이드·검사기·학습 문서가 "DROP INDEX 하나"로 안내한다. Flyway는 트랜잭션 밖에서 실패한 버전의 이력 행(success = false)을 남기고, 다음 배포의 validate가 그 행 때문에 다시 멈춘다. runbook에는 이 경우가 없고 이력 수정은 금지다. docs/jpa/runbooks.md "An invalid index exists"도 같은 이유로 재적용에서 멈춘다. - 검사기 Javadoc·학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 쓴다. 가이드가 요구하는 executeInTransaction=false를 붙이면 Flyway가 문장마다 커밋해 앞 문장이 남는다. - 가이드·검사기 Javadoc·실패 메시지·학습 문서가 "Flyway는 REINDEX … CONCURRENTLY를 트랜잭션 안에서 돌린다"고 쓴다. REINDEX SCHEMA|DATABASE CONCURRENTLY는 Flyway가 스스로 트랜잭션 밖에서 돌린다. - LockWaitMigrationInspector는 .sql.conf가 executeInTransaction=true면 SET LOCAL 뒤의 VACUUM FULL·REINDEX SCHEMA를 통과시킨다. Javadoc은 "늘 거부"라고 쓴다. - ledger 잠금 대기 IT가 동시 인덱스 파일을 "이 테스트에 예외로 적으라"고 안내하지만 예외를 적을 곳이 없다. 같은 원인으로 ledger의 다른 IT 두 개 (GrpcOperationLedgerPostgresIT, JpaGrpcOperationLedgerContractIT)도 모든 파일을 한 문자열로 실행해, 동시 인덱스 파일이 생기면 "cannot be executed within a pipeline"으로 실패한다. 고른 방법 - 복구(RR7-03-03): 소유자 결정(2026-11-06)대로 migration-failed.md에 "Recover a failed concurrent index migration" 절을 둔다. 진행 중 빌드 확인 → 무효 인덱스 DROP INDEX CONCURRENTLY → 원인 정리 → 그 버전의 실패 행만 DELETE → 재배포. "Do not"에 이 한 가지 예외를 적고 flyway repair는 계속 금지한다. SQL 세 블록에 runbook-sql 표시를 달고 postgresqlConcurrentIndexMigrationIntegrationTest가 runbook에서 읽어 실 PostgreSQL에서 돌린다(outbox runbook과 같은 방식). 가이드·검사기 Javadoc·메시지·학습 문서·jpa/runbooks.md는 그 절을 가리킨다. - 섞인 파일(RR7-03-04)·REINDEX(RR7-03-02): 문장을 고치고, 같은 IT와 잠금 대기 IT에 사실을 고정한다(섞인 파일 두 경우, REINDEX 다섯 형태). - 검사기(RR7-03-05): 트랜잭션 안에서 돌 수 없는 잠금 문장은 .sql.conf와 상관없이 거부한다(리뷰 권장안). 버린 안: Javadoc만 좁히기 — 그 파일은 PostgreSQL이 배포 때 25001로 거부하므로 검사기가 먼저 알려 주는 쪽이 맞다. 잠그지 않는 문장(plain VACUUM 등)은 이 검사기의 범위가 아니라 그대로 둔다. - ledger(RR7-03-01): IT에 RUN_OUTSIDE_A_TRANSACTION(파일 → 이유) 목록을 두고 잠금 대기 케이스에서 뺀다. 목록의 파일은 같은 IT가 동시 인덱스 문장 하나·executeInTransaction=false인지 ConcurrentIndexMigration Inspector로 본다. optional 빌드는 testkit에 의존할 수 없어 sharedMigrationFileSources가 그 파일과 MigrationResource를 복사한다 (VersionedMigrationFiles와 같은 방식). ledger IT 셋은 마이그레이션을 파일마다 따로 실행한다(Flyway처럼). 버린 안: 안내만 "다룰 수 없다"로 바꾸기 — 다음 동시 인덱스 파일이 생길 때 같은 질문이 다시 남는다. 위험·한계 - 검사기 변경으로 서비스의 자기 스트림 검사가 새로 실패할 수 있다. 걸리는 파일은 PostgreSQL이 배포 때 거부하는 파일뿐이라 배포된 적이 없다(업그레이드 안내 4.1에 적음). - runbook의 DELETE는 운영자가 version을 옮겨 적는다. NOT success라 성공한 행은 지우지 못하지만, 다른 버전의 실패 행을 잘못 적으면 그 행이 지워진다. 한 행만 지워야 하고 0행이면 다시 분류하라고 적었다. - ledger 복사 파일 두 개도 JDK만 써야 한다(각 Javadoc에 적음). - Spotless 검사는 같은 worktree에서 spotlessApply가 변경 없이 끝난 직후라 UP-TO-DATE로 처리됐다. 검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/) RED — 기준73d39212+ 이 커밋의 테스트(+ 기준 문서 주장을 단언하는 임시 메서드, + 임시 ledger V004): - persistence-jpa test --tests LockWaitMigrationInspectorTest: 80건 중 2건 실패, 검사기가 빈 목록(통과)을 돌려줌 (red-unit.log) - postgresqlMigrationLockWaitIntegrationTest: 47건 중 4건 실패 — 옛 주장 대로면 거부여야 할 REINDEX SCHEMA|DATABASE CONCURRENTLY가 applied, conf=true VACUUM FULL·REINDEX SCHEMA를 PostgreSQL은 25001로 거부하는데 검사기는 통과 (red2-lockwait.log) - postgresqlConcurrentIndexMigrationIntegrationTest: 9건 중 3건 실패 — 옛 절차(DROP INDEX) 뒤 재배포가 "Detected failed migration to version 2", conf를 붙인 섞인 파일이 행 3001·무효 인덱스·실패 이력을 남김, runbook 블록이 없어 복구 테스트 준비 실패(RED로 세지 않음) (red2-concurrent.log) - ledger integrationTest(V004 동시 인덱스): 6건 중 4건 실패 — 잠금 대기 IT "name it as an exception here", 다른 IT 둘 "cannot be executed within a pipeline" (red-ledger.log) GREEN — 이 커밋의 트리b49369e7: - :adapter:outbound:persistence-jpa:check rc=0 (test 666건 실패 0), :testQualityCheck rc=0 - postgresqlMigrationLockWaitIntegrationTest rc=0 (42건 실패 0) - postgresqlConcurrentIndexMigrationIntegrationTest rc=0 (7건 실패 0) - -p optional-platforms :grpc:grpc-operation-ledger-jpa:check integrationTest testQualityCheck rc=0 (IT 3+2+42건 실패 0) - :app-bootstrap:documentContractTest rc=0 (66건 실패 0) - 두 빌드의 verifyStrictLaneStages --dry-run rc=0 - ledger 탐침(임시 V004): 목록에 없으면 잠금 대기 케이스만 실패하고 메시지가 RUN_OUTSIDE_A_TRANSACTION을 가리킴(48건 중 1건), 목록에 넣으면 rc=0, 목록에 넣고 SET LOCAL을 섞으면 목록 검사가 "mixes a concurrent index statement"로 거부 - python3 scripts/check-work-docs.py --links docs: 깨진 링크 0 Refs: docs/reviews/2026-11-03-rereview/round7/03-persistence.md
ca-skeleton — Clean Architecture Spring Boot 템플릿
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 dev.caskeleton이며, 예시 도메인은 production 모듈이 아니라 sample-portfolio 모듈(WorkLog 작업 기록 게시판)에 격리합니다.
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 CLAUDE.md가, 빌드·환경 변수 상세는 src/README.md가 소유합니다.
아키텍처 한눈에
의존은 항상 바깥에서 안으로 흐릅니다. adapter가 core의 port에 의존하고, core는 adapter를 알지 못합니다. 이 방향이 유지되는 한 도메인 규칙과 기술 선택(웹 프레임워크, DB, 메시징)을 서로 독립적으로 바꿀 수 있습니다.
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
모든 런타임 모듈 -> shared-contract
sample-portfolio -> 등록된 런타임 리프 (fixture 소비자 전용)
family 수준의 책임은 다음과 같습니다.
| 모듈 family | 책임 |
|---|---|
domain-core |
순수 도메인 모델·불변식·이벤트·port. 프레임워크·transport·DB·IO 타입 금지 |
application-core |
command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지 |
adapter:inbound:* |
HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 |
adapter:outbound:persistence-* |
JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration |
adapter:outbound:* |
support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 app-bootstrap/build.gradle의 runtimeOnly 한 줄로 고릅니다 |
shared-contract |
skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
app-bootstrap |
Spring Boot entrypoint와 composition root |
sample-portfolio |
WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음 |
등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는
src/config/architecture/modules.json이 SSOT입니다. focused
test는 해당 Gradle path에서 ./gradlew <gradle-path>:test --console=plain 형태로 파생하며, root
문서나 기억에서 개별 leaf edge를 추론하지 않습니다.
퀵스타트
전제조건은 Temurin 21(루트 .tool-versions에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
scripts/bootstrap-local.sh # 다른 Compose overlay는 scripts/bootstrap-local.sh <profile>
scripts/bootstrap-local.sh는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, GET /api/healthcheck HTTP smoke를 순서대로 실행합니다. 각 단계가 bootstrap N/4 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
curl -fsS http://localhost:8080/api/healthcheck
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
docker compose -f docker-compose.yml -f docker-compose.local.yml down
src/.env.example은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 src/.env는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 src/README.md와 docs/registries/env-keys.yaml에 있습니다.
기본 조립과 부가 기능
기본 조립(bootJar)은 web, 관측, domain-core·application-core·shared-contract, support,
identifier뿐이라 DB·Redis·Kafka 없이 기동합니다.
cd src
./gradlew :app-bootstrap:bootRun
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능은 app-bootstrap/build.gradle에 주석 처리된
runtimeOnly 한 줄씩으로 있습니다. 줄의 주석을 풀고 필요한 env를 넣으면 켜지고, 줄을 지우면 사라집니다.
줄마다 필요한 env와 끄는 키는 src/README.md의 "기능 추가 = 한 줄 + env" 표에 있습니다.
| 프로파일 | 데이터스토어 (persistence-jpa 줄을 넣었을 때) | 스키마 소유자 |
|---|---|---|
local |
Compose PostgreSQL (./gradlew :app-bootstrap:bootRunH2는 줄 없이도 모듈을 자기 classpath에 올려 H2 in-memory로 실행) |
Flyway (H2는 Hibernate create-drop) |
dev |
PostgreSQL | Flyway |
prod |
PostgreSQL | Flyway |
H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 src/app-bootstrap/src/main/resources/의 application-{local,dev,prod}.yml이, 상세 설명은 src/README.md가 소유합니다.
새 프로젝트로 시작하기
이 저장소를 새 서비스의 출발점으로 쓸 때 핵심 단계는 다음과 같습니다. 전체 체크리스트는 AGENTS.md의 "템플릿 재사용 체크리스트"에 있습니다.
-
src/settings.gradle의
rootProject.name을 새 서비스 이름으로 바꿉니다. -
패키지 루트
dev.caskeleton을 조직·서비스 패키지로 바꿉니다. 소스뿐 아니라 빌드·설정 파일의 참조도 함께 바꿔야mainClass·group이 어긋나bootstrap이 깨지지 않습니다.cd src find . -type f \( -name '*.java' -o -name '*.gradle' -o -name '*.yml' \) -print0 | xargs -0 sed -i 's/dev.caskeleton/com.yourorg.yourservice/g'애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다.
-
CaSkeletonApplication을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 예시 코드는sample-portfolio에만 둡니다. -
모듈 이름과 경계는 그대로 유지합니다.
검증은 먼저 composition root의 빠른 테스트와 sample-off 계약을 확인합니다. 루트에서
./gradlew test를 호출하면 등록된 모든 하위 프로젝트의 test를 실행하므로 일상적인 로컬
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 ci task가
담당합니다.
cd src
./gradlew :app-bootstrap:test
./gradlew :sample-portfolio:check
./gradlew architectureCheck
병합 전 저장소 전체 검증이 필요하면 ./gradlew ci를 실행합니다.
sample-portfolio는 템플릿이 유지하는 fixture/reference 모듈이라 production 모듈이 의존하지 않고, runtime에 sample bean이나 endpoint를 넣지 않습니다. 다운스트림 fork에서 fixture가 더 필요 없을 때만 sample-off 테스트를 통과시킨 뒤 정리합니다.
아키텍처 규칙과 검증
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬 정책 권위는 AGENTS.md이며, CLAUDE.md는 작업을 시작할 때 읽는 지도입니다. 일의 종류별 절차는 docs/work/에 있습니다.
domain-core는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다.- controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다.
- inbound DTO는
application-core나domain-core로 들어가지 않습니다. - 비즈니스 정책은 mapper·filter·config·settings·controller에 두지 않습니다.
- 새 외부 시스템 연동은 domain/application port와 adapter 모듈로 표현합니다.
이 규칙은 두 축으로 자동 강제합니다. :app-bootstrap:architectureTest의 분할된 ArchUnit 규칙들이 컴파일된 소스 의존성을,
verifyCleanArchitectureDependencies 게이트가 JSON registry의 허용 Gradle project edge를
검사합니다.
cd src
./gradlew verifyCleanArchitectureDependencies
두 검증 축은 ci-quality-gates.yml의 release gate에 연결되어, 규칙 위반이 병합·릴리스를 막습니다.
수동 전용 Gradle 태스크
아래 세 태스크는 어떤 워크플로도 실행하지 않으며, 그게 의도다. 자동 실행이 틀린 이유를 각각 적어 둔다.
여기 적힌 태스크 이름이 실재하는지 검사하던 verifyReadmeCommands는 삭제했다. 그건 이 문서의
```bash 블록을 직접 파싱해 ./gradlew·docker compose·make 토큰을 실제 태스크 그래프와 대조하는
Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"가 그 파서가 읽을 수 있는 문법의
함수가 됐다. 문서와 코드가 어긋나는 것은 결함이지만, 빌드를 실패시켜서 고칠 일은 아니다.
cd src
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
./gradlew :sample-portfolio:openapiCheckSnapshot -PapproveOpenApiChange
grpcPerformanceTest— latency percentile·saturation·drain budget을 측정한다. 공유 CI runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leafbuild.gradle이 이 태스크의 태그를test에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.openapiCheckSnapshot— 드리프트 검사 자체는 이미 자동으로 돈다. 이 태스크가 감싸는OpenApiDriftContractTest는:sample-portfolio:test의 일부이고, 그건check안이며 stage 1에서 실행된다. 이 태스크의 고유한 역할은-PapproveOpenApiChange로 커밋된 스냅샷을 다시 만드는 것 — 의도된 API 변경을 사람이 승인하는 지점이다. 자동으로 돌리면 승인이 승인이 아니게 된다.
더 알아보기
- 빌드·검증 게이트·환경 변수 상세: src/README.md
- 모듈 레지스트리(등록 leaf SSOT): src/config/architecture/modules.json
- 에이전트·기여자 작업 규칙: AGENTS.md · CLAUDE.md
- release/publish 자동화는
.github/workflows/release.yml이 소유하며, release provenance·SBOM· 이미지 build/push를 해당 workflow의 명시적 권한과 게이트 아래에서 수행합니다. - 모듈별 설계 결정: domain-core · application-core · adapter:inbound:web · adapter:outbound:persistence-jpa · shared-contract · app-bootstrap