DongHyeonka 7535a4ca7a fix(idempotency)!: 적용한 핸들의 재전송을 전이 종류와 인자로 가린다
문제: 전이를 적용한 핸들이 그 전이를 다시 보낼 때 세 저장소가 서로, 그리고
포트 Javadoc과 다르게 답한다(재리뷰 round8 RR8-04-01·02, 같은 원인).
- markFailed를 다른 disposition으로 다시 보내면 fake·Redis·PostgreSQL 모두
  NOT_OWNER다. 기록을 남이 가져갔다는 틀린 신호이고 Javadoc은
  OPERATION_CONFLICT라고 적는다.
- retention만 다르면 fake·Redis는 ALREADY_MARKED_SAME_OPERATION, PostgreSQL은
  fail digest에 retention이 들어 있어 OPERATION_CONFLICT다.
- Redis는 start가 돌려준 핸들로 renew한 뒤 그 핸들로 start를 보내면
  ALREADY_STARTED_SAME_OPERATION으로 답한다. renew도 기록을 EXECUTING·
  revision+1로 두어 TRANSITION이 상태와 revision만으로는 start와 구별하지
  못한다. executor는 그 답에 action을 실행해 이미 도는 작업을 한 번 더
  돌린다. fake·PostgreSQL은 NOT_OWNER다.
원인은 하나다. "적용한 핸들"을 revision 하나로만 가리고 전이 종류와 인자를
같이 보지 않는다.

방법: 소유자 결정(2026-11-07, 1103 README 19.4절 ② (a))대로 다른
disposition은 OPERATION_CONFLICT, 다른 retention은 "이미 처리됨"으로 맞춘다.
retention은 complete의 replay TTL처럼 결과를 얼마나 보관하나일 뿐이라
비교하지 않는다.
- Redis: 기록 hash에 lastKind(CLAIM·START·RENEW·COMPLETE·FAIL)를 남긴다.
  TRANSITION의 재전송 판정은 "rev == 핸들 rev + 1 그리고 lastKind == 이
  전이"다. 그 안에서 상태가 목표면 ALREADY, 아니면(다른 disposition의
  실패) OPERATION_CONFLICT. claim·takeover는 CLAIM을 써 넘겨받기 전 종류가
  남지 않게 한다. 어댑터가 전이 종류를 9번째 인자로 보낸다. 명령 fake를
  같이 고친다.
- PostgreSQL: fail 재생 판정이 두 실패 종류(FAIL_RETRYABLE·FAIL_ABANDONED)를
  모두 실패의 재생으로 읽는다. fail digest에서 retention을 뺀다.
- fake: 적용한 핸들의 markFailed 재전송에 disposition이 다르면
  OPERATION_CONFLICT.
- 공유 계약 IdempotencyStoreContract에 케이스 셋(다른 retention, 다른
  disposition과 기록 유지, renew 뒤 같은 핸들의 start)을 더했다.
- PostgreSqlIdempotencyIntegrationTest의 "다른 retention은 conflict" 케이스가
  옛 동작을 고정하고 있어 결정대로 "이미 처리됨, 처음 retention 유지"로
  바꿨다(...IsConfirmedAndKeepsItsRetention).
  IdempotencyFailOutcome·IdempotencyStartOutcome·IdempotencyStorePort Javadoc,
  결정 색인 2.4절(새 행과 「넘겨받기 전 핸들의 재전송」 적용 조건),
  application-core CLAUDE.md·README, cache-redis·persistence-jpa README,
  TESTING_STRATEGY, 업그레이드 안내 5절 행을 같이 고쳤다.
버린 대안: 다른 disposition을 NOT_OWNER로 두고 Javadoc만 고치기(19.4절 ②
(b), 소유자가 고르지 않음, 적용한 핸들에 "넘겨받혔다"는 틀린 신호),
다른 retention도 OPERATION_CONFLICT(② (c), Redis 기록에 retention을 더하고
Lua를 바꿔야 하며 보관 기간을 인자로 본다), Redis start 분기만
"renewedFromRev가 있으면 ALREADY 아님"으로 막기(같은 상태에 머무는 전이가
늘면 다시 갈라진다).

위험·한계: 템플릿 호출자(IdempotencyExecutor)는 같은 인자로만 다시 보내고
renew를 부르지 않아 HTTP 동작은 같다. 포트를 직접 부르는 코드만 답이
바뀐다. 이 배포 전에 쓰인 Redis 기록에는 lastKind가 없어, 새 프로그램이
그 기록의 전이를 재전송으로 보지 않는다. 핸들은 프로세스 메모리에만 있고
같은 프로세스는 같은 프로그램을 돌리므로, 새 프로그램이 옛 프로그램이
적용한 전이의 핸들을 받는 경로는 템플릿에 없다고 본다(실행으로 확인하지
않음). PostgreSQL도 같은 이유로 옛 fail digest(retention 포함)와 새
digest를 같은 핸들로 비교하는 경로가 없다고 보고 digest VERSION을 올리지
않았다.

검증: desktop, 공유 잠금, --no-build-cache, 기준 3eb3b067.
- RED(기준 커밋 + 계약 케이스만, 로그 ~/r9-g4-red-logs/red-summary.txt):
  fake 62 중 1 실패(다른 disposition "expected: OPERATION_CONFLICT but was:
  NOT_OWNER"), Redis 명령 fake 62 중 2·실 Redis(redisContainerContractTest)
  103 중 2 실패(다른 disposition, renew 뒤 start "expected: NOT_OWNER but
  was: ALREADY_STARTED_SAME_OPERATION"), 실 PostgreSQL 62 중 2 실패(다른
  disposition, 다른 retention "expected: ALREADY_MARKED_SAME_OPERATION but
  was: OPERATION_CONFLICT").
- GREEN(이 커밋과 같은 트리 5a74698d, 로그 ~/r9-g4-green-logs/와 pass2/,
  수는 결과 XML에서 셈 test-counts.txt): 네 leaf check(application-core 426·
  skip 19 fake 시간 케이스, cache-redis 228, redis-runtime 65,
  persistence-jpa 666)와 testQualityCheck, redisContainerContractTest 103,
  jpaPlatformContractTest 432, fake를 쓰는 leaf(composition:idempotency 32,
  redis-sdk 310, web 341, sample-portfolio 339), documentContractTest 67 —
  모두 rc=0, 실패 0. postgresqlIdempotencyIntegrationTest는 1차에서 위 옛
  케이스 1건이 실패했고, 고친 뒤 pass2에서 persistence-jpa spotlessCheck·
  check·testQualityCheck와 함께 10 중 실패 0, rc=0.
- scripts/check-work-docs.py rc=0, git diff --check 통과.

BREAKING CHANGE: IdempotencyStorePort 구현은 적용한 핸들이 markFailed를 다른
disposition으로 다시 보내면 OPERATION_CONFLICT, retention만 다르면
ALREADY_MARKED_SAME_OPERATION으로 답해야 하고, renew를 적용한 핸들의 start를
"이미 시작됨"으로 확인하면 안 된다(NOT_OWNER). 직접 구현한 store는
IdempotencyStoreContract의 새 케이스로 확인한다.
2026-11-07 07:50:40 +09:00

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의 "템플릿 재사용 체크리스트"에 있습니다.

  1. src/settings.gradle의 rootProject.name을 새 서비스 이름으로 바꿉니다.

  2. 패키지 루트 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 단계는 위 체크리스트를 따릅니다.

  3. CaSkeletonApplication을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 예시 코드는 sample-portfolio에만 둡니다.

  4. 모듈 이름과 경계는 그대로 유지합니다.

검증은 먼저 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의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf build.gradle이 이 태스크의 태그를 test에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
  • openapiCheckSnapshot — 드리프트 검사 자체는 이미 자동으로 돈다. 이 태스크가 감싸는 OpenApiDriftContractTest는 :sample-portfolio:test의 일부이고, 그건 check 안이며 stage 1에서 실행된다. 이 태스크의 고유한 역할은 -PapproveOpenApiChange로 커밋된 스냅샷을 다시 만드는 것 — 의도된 API 변경을 사람이 승인하는 지점이다. 자동으로 돌리면 승인이 승인이 아니게 된다.

더 알아보기

S
Description
No description provided
Readme
46 MiB
Languages
Java 97.6%
Python 1.1%
Shell 0.9%
Go Template 0.3%