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:
DongHyeonka
2026-11-07 21:58:12 +09:00
parent b3f63be655
commit 08f932123a
102 changed files with 3107 additions and 2986 deletions
+4 -4
View File
@@ -84,7 +84,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
| 하려는 일 | 시작할 곳 |
| --- | --- |
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [CLAUDE.md](CLAUDE.md) |
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [AGENTS.md](AGENTS.md) |
| 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` |
| 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` |
| 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` |
@@ -92,7 +92,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` |
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `CLAUDE.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)).
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)).
## 검증
@@ -130,6 +130,6 @@ cd src
## 규칙과 기여
- 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다.
- 일을 시작할 때 읽는 지도는 [CLAUDE.md](CLAUDE.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`다.
- 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/AGENTS.md`다.
- 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다.
+1 -1
View File
@@ -200,4 +200,4 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다.
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/CLAUDE.md` 가 소유한다.
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다.
+1 -1
View File
@@ -48,7 +48,7 @@ major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래
H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스
빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다.
`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `CLAUDE.md`는 측정을 기록한다.
`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `AGENTS.md`는 측정을 기록한다.
H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이
문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. **측정한 버전에서 관찰한
동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다.** 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이
+1 -1
View File
@@ -30,7 +30,7 @@ scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에
| 입력 | 규칙 | 어디서 막나 |
| --- | --- | --- |
| 이름 | PascalCase, 영숫자 | 스크립트 |
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/AGENTS.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
| HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, `ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122` |
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
+2 -2
View File
@@ -50,7 +50,7 @@
- **기본값**: 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/CLAUDE.md`.
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/AGENTS.md`.
## 2단계 — application-core: 유스케이스와 포트
@@ -70,7 +70,7 @@ record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/mai
- **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
- **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`.
- **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/CLAUDE.md`
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/AGENTS.md`
「Allowed transactional shapes」.
### 판단: 무엇을 반환하나
+1 -1
View File
@@ -55,7 +55,7 @@
- `<f>`는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과
겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를
이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다.
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/CLAUDE.md`
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/AGENTS.md`
「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성
뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다.
- 이름 규칙은 같은 파일 「Naming convention」이 정본이다.
+1 -1
View File
@@ -16,7 +16,7 @@
DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false)
```
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/CLAUDE.md` 「Idempotency (KEYED)」
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/AGENTS.md` 「Idempotency (KEYED)」
(executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명).
## 판단: 이 쓰기를 KEYED로 만드나
+1 -1
View File
@@ -17,7 +17,7 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐
DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을
없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다.
정본: `src/application-core/CLAUDE.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
정본: `src/application-core/AGENTS.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
`docs/messaging/delivery-guarantees.md`.
## 순서
+2 -2
View File
@@ -5,8 +5,8 @@
## 배치·이름
- [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `<feature>` 패키지).
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
- [ ] 이름이 `src/application-core/CLAUDE.md` 「Naming convention」을 따른다.
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
- [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다.
## domain
+2 -2
View File
@@ -42,8 +42,8 @@
| --- | --- |
| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.md`) |
| leaf 목록·허용 의존 | `src/config/architecture/modules.json` |
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/CLAUDE.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 |
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/AGENTS.md` 「Canonical use case shape」「Allowed transactional shapes」 |
| HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` |
| 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` |
| 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` |
+1 -1
View File
@@ -27,7 +27,7 @@
> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만
> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter /
> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다.
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다.
## 브로커 등급
+1 -1
View File
@@ -3,7 +3,7 @@
파생 서비스가 `adapter:outbound:persistence-mongo`를 실제로 쓰려면 **자기 Mongo 어댑터 leaf**를 하나
만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository·
mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다
(`src/adapter/outbound/persistence-mongo/CLAUDE.md` "Forbidden").
(`src/adapter/outbound/persistence-mongo/AGENTS.md` "Forbidden").
전체 흐름:
+14
View File
@@ -0,0 +1,14 @@
# 업그레이드 안내 — 2026-11 Claude Code 작업 환경(하네스)
- 범위: 지침 파일 배치(leaf 규칙 문서 이름, 루트 `AGENTS.md`·`CLAUDE.md`), `.claude/`의 권한·훅·규칙·스킬·서브에이전트, 예측·실측 장부
- 근거: 소유자 결정(2026-11-07), design-docs `harness/01-harness-design.md` 13절, `docs/work/reference/decisions.md` 「지침 배치」
## 1. 누가 읽나
이 템플릿을 받아 도메인을 채운 파생 서비스가 읽는다. 코드·설정·빌드의 동작은 바뀌지 않았다. 바뀐 것은 지침 파일의 자리와 Claude Code 세션 설정이다.
## 2. 바뀐 것과 할 일
| # | 바뀐 것 | 서비스가 할 일 |
| --- | --- | --- |
| 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src/<leaf>/CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) |
+1 -1
View File
@@ -31,7 +31,7 @@
1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다.
2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/CLAUDE.md`를 읽는다.
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다.
4. 스킬을 고른다. 정본은 `AGENTS.md` 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다.
5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다.
+2 -2
View File
@@ -4,7 +4,7 @@
## 1. 언제 쓰나
- `docs/work/`, `docs/manual/`, 루트·leaf `CLAUDE.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
- `docs/work/`, `docs/manual/`, 루트·leaf `AGENTS.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
- 이것은 아니다.
- 리뷰 문서 → [improve.md](improve.md)(리뷰 양식은 [reference/review-criteria.md](reference/review-criteria.md) 10절)
- 설계서·ADR → [research-design.md](research-design.md)
@@ -28,7 +28,7 @@
## 4. 절차
1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다".
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `CLAUDE.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `AGENTS.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다.
4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다.
5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다.
+1 -1
View File
@@ -69,7 +69,7 @@
### 4.3 리팩터링, 성능, 구조, 테스트 구조
- 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다.
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `CLAUDE.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `AGENTS.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
- 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.md 「성능 측정」, 지난 기준선은 [evidence.md](evidence.md)다. 지난 숫자는 현재 커밋에서 다시 잰다.
- 구조 변경: 설계서(`docs/design/`)와 계획서(`docs/history/plans/`)를 먼저 둔다. review-criteria.md 「leaf 변경 체크리스트」를 따른다. ArchUnit 규칙을 바꾸면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다.
- 테스트 구조: 지금 테스트가 증명하는 것(이름, 단언, skip 수)을 적는다. 고친 뒤 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지(변이) 본다. 옮겼으면 lane별 테스트 수를 전후로 비교한다.
+1 -1
View File
@@ -29,7 +29,7 @@
## 4. 절차
1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다.
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않는지 본다.
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다.
3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다.
4. 뼈대를 만든다: `scripts/new-feature.sh <FeatureName>`(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」).
5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다.
+2 -2
View File
@@ -2,7 +2,7 @@
이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다.
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/CLAUDE.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
## 패턴
@@ -121,7 +121,7 @@
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc |
| 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) |
| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) |
| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/platforms/messaging/CLAUDE.md`) |
| 복사본을 남긴 이유 | 가까운 `AGENTS.md`(예: `src/platforms/messaging/AGENTS.md`) |
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` |
## 패턴을 더하는 법
+5 -5
View File
@@ -101,7 +101,7 @@
| # | 관점 | 볼 곳 | 이런 증거면 결함 |
| --- | --- | --- | --- |
| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 |
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 |
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 |
| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 |
@@ -123,9 +123,9 @@
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 |
| 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 |
| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 |
| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
| 24 | 네이밍·의미 | `src/application-core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 |
| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 |
| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 |
@@ -199,7 +199,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신
- 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다.
- 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다.
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
- 템플릿 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
@@ -212,7 +212,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
- [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나
- [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다)
- [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports`
- [ ] leaf `CLAUDE.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
- [ ] leaf `AGENTS.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표
- [ ] ArchUnit 규칙과 그 위반·허용 fixture
- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다)
+1 -1
View File
@@ -26,7 +26,7 @@
- `docs/reviews/`의 리뷰 README 「결정」 절과 영역 문서의 「Declined to judge」
- `docs/adr/`(되돌리기 비싼 선택), `docs/design/`(설계서), `docs/history/plans/`(계획서)
- `git log --oneline -- <경로>`와 커밋 본문의 "고른 방법과 버린 대안"
- 가장 가까운 `src/**/CLAUDE.md`와 모듈 README
- 가장 가까운 `src/**/AGENTS.md`와 모듈 README
- 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(Spring Boot, Flyway, Hibernate 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다.
- 스킬: `superpowers:brainstorming`, 결정 기록은 `documentation-and-adrs`, 공식 문서 확인은 `source-driven-development`. 큰 판단은 `doubt-driven-development`로 반론을 세운다.
+49 -2
View File
@@ -61,7 +61,7 @@ from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parent.parent
EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt"
REGISTRY_FILE = "src/config/architecture/modules.json"
CHECKS = ("language", "head", "reference", "number", "map", "readme")
CHECKS = ("language", "head", "reference", "number", "map", "readme", "link")
# 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다.
RECORD_KINDS = [
@@ -148,6 +148,10 @@ VERSION = re.compile(r"(?<![\w.§])v?\d+\.\d+\.\d+(?:[.-][A-Za-z][A-Za-z0-9]*)*(
SPRING_BOOT_CELL = re.compile(r"^Spring Boot(?:\s+(?:BOM|버전))?$")
CELL_MARKUP = re.compile(r"[*_`]")
LINK_TEXT = re.compile(r"\[([^\]\n]*)\]\([^)\s]*\)")
# 상대 링크: 살아 있는 문서의 `[글](경로)`가 이 트리의 파일·폴더를 가리킨다. lychee(link-check.yml)는 PR에서
# 정해진 경로만 보고, 그 밖의 문서(`src/**/AGENTS.md`, `.claude/**`, 루트 `AGENTS.md`)의 상대 링크는 이 검사만 본다.
LINK_TARGET = re.compile(r"\[[^\]\n]*\]\(([^)\s]+)\)")
URL_SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*:", re.I)
@dataclass(frozen=True)
@@ -367,6 +371,49 @@ def inline_spans(lines: list[str]) -> list[tuple[int, str]]:
return spans
def link_targets(lines: list[str]) -> list[tuple[int, str]]:
"""(줄 번호, 상대 링크 대상) — 코드 블록·인라인 코드·「이력」 인용 블록 밖에서만."""
targets, fence, history = [], None, False
for number, line in enumerate(lines, start=1):
match = FENCE.match(line)
if fence:
if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence):
fence = None
continue
if match:
fence = match.group(1)
continue
quoted = line.lstrip().startswith(">")
if quoted and HISTORY_QUOTE.match(line):
history = True
elif not quoted:
history = False
if history:
continue
for found in LINK_TARGET.finditer(INLINE.sub("", line)):
target = found.group(1).split("#", 1)[0]
if target and not URL_SCHEME.match(target):
targets.append((number, target))
return targets
def check_link(root: Path, files: list[str]) -> list[Problem]:
known = known_paths(root)
problems = []
for path in files:
if not is_living(path):
continue
text = (root / path).read_text(encoding="utf-8")
lines = body_lines(text)
offset = len(text.split("\n")) - len(lines)
for number, target in link_targets(lines):
resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target))
if resolved.startswith("..") or not is_known(known, resolved):
problems.append(Problem("link", path, target, f"없는 곳을 가리키는 상대 링크다: {target}",
number + offset))
return problems
def registry_projects(root: Path) -> set[str]:
registry = root / REGISTRY_FILE
if not registry.is_file():
@@ -634,7 +681,7 @@ def check_readme(root: Path, files: list[str]) -> list[Problem]:
RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number,
"map": check_map, "readme": check_readme}
"map": check_map, "readme": check_readme, "link": check_link}
def read_exceptions(text: str) -> list[str]:
+4 -3
View File
@@ -9,7 +9,7 @@ to finish the job from those alone. Two things break that, and both are mechanic
who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference
files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`).
The same rule covers the other files a new session reads first: the rule book `AGENTS.md` and
every `src/**/CLAUDE.md` (owner decision 2026-11-07). Module READMEs, design documents and
every `src/**/AGENTS.md` (owner decision 2026-11-07). Module READMEs, design documents and
`docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository.
2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a
total limit, so a session reads the whole path instead of skimming it.
@@ -196,11 +196,12 @@ def check_skeleton(errors: list[str]) -> None:
def module_guides() -> list[Path]:
"""Every src/**/CLAUDE.md, the local rule book of a leaf or a family, outside build output."""
"""Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output.
The src/**/CLAUDE.md beside it is one line, `@AGENTS.md`, so Claude Code reads the same book."""
skipped = {"build", ".gradle", "node_modules"}
return sorted(
path
for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
for path in (REPO_ROOT / "src").rglob("AGENTS.md")
if not skipped.intersection(path.relative_to(REPO_ROOT).parts)
)
+32
View File
@@ -439,6 +439,38 @@ class ReadmeTest(RepositoryTestCase):
self.assertFailsWith(self.repo.run(("readme",)), "루트 README가 없다")
class LinkTest(RepositoryTestCase):
def errors_for(self, text: str, path: str = "src/app/AGENTS.md") -> list[str]:
self.repo.write(path, KOREAN + text)
return self.repo.run(("link",))
def test_a_relative_link_to_a_missing_file_fails(self) -> None:
self.assertFailsWith(self.errors_for("[설계](README.md)를 본다.\n"), "없는 곳을 가리키는 상대 링크다: README.md")
def test_a_relative_link_to_a_tracked_file_passes(self) -> None:
self.repo.write("src/app/README.md", KOREAN)
self.assertEqual(self.errors_for("[설계](README.md#결정)를 본다.\n"), [])
def test_a_link_up_the_tree_resolves_from_the_document_folder(self) -> None:
self.assertEqual(self.errors_for("[살아 있는 문서](../../docs/live.md)를 본다.\n"), [])
def test_a_link_out_of_the_repository_fails(self) -> None:
self.assertFailsWith(self.errors_for("[밖](../../../outside.md)를 본다.\n"), "../../../outside.md")
def test_a_folder_left_empty_on_disk_fails(self) -> None:
(self.repo.root / "src/app/moved").mkdir(parents=True)
self.assertFailsWith(self.errors_for("[옮김](moved/)을 본다.\n"), "moved/")
def test_urls_anchors_code_and_history_quotes_are_skipped(self) -> None:
text = ("[웹](https://example.com/x) [절](#절) `[코드](gone.md)`\n"
"```text\n[블록](gone.md)\n```\n> 이력: [옛 문서](gone.md)는 지웠다.\n")
self.assertEqual(self.errors_for(text), [])
def test_a_record_is_not_checked(self) -> None:
self.repo.write("docs/design/2026-08-11-x-design.md", head() + "[옛](gone.md)\n")
self.assertEqual(self.repo.run(("link",)), [])
class CommandLineTest(unittest.TestCase):
def test_an_unknown_check_is_a_usage_error(self) -> None:
self.assertEqual(check_docs.main(["--only", "spelling"]), 2)
+1 -1
View File
@@ -1,7 +1,7 @@
# src — 빌드 스크립트 / 환경 변수 참조
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT이다.
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다.
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
+218
View File
@@ -0,0 +1,218 @@
# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치)
## 등록 정보
- 모듈 ID: `adapter-inbound-graphql`
- Gradle 경로: `:adapter:inbound:graphql`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
Package root: `dev.caskeleton.adapter.inbound.graphql`.
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈
규칙 SSOT).
## 플랫폼 모듈 = sub-package (Gradle 모듈 아님)
GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이
leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은
방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성
SSOT(`src/config/architecture/modules.json`)까지 밀어올리지 않는다는 선택이다.
**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매
플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는
`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간
낡는다. 즉 이 레포에는 두 패턴이 공존한다:
| | 방식 | 경계 강제 |
| --- | --- | --- |
| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 |
| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) |
어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다.
sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/`
모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다
(`docs/capability-status.md` 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 —
`GraphQlTransportBoundaryArchitectureTest`(ArchUnit, 이 leaf 패키지 대상):
- resolver(`@SchemaMapping` 계열·`@BatchMapping`) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과
그 제네릭 인자에 raw `Map`, persistence 매핑 타입(`@Entity`/`@Document`/`@Table` 등, 단순명
매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이
오면 실패한다.
- raw `DataFetcher` 구현은 `scalar`·`schema`·`execution` 패키지에만 둔다.
두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의
required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다.
## 책임
- GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`,
프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를
자동 합성/바인딩하도록 얹는 얇은 계층이다.
- 그 위에 **GraphQL API 실행 플랫폼**(`...graphql` 하위 sub-package 군)이 스키마 계약·전송
프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을
소유한다. 플랫폼은 여전히 **feature-agnostic** 이며 정책·계약·검증 기계만 제공한다.
- feature-agnostic: `classpath:graphql/**` 스키마와 모든 `@Controller` `@QueryMapping`/
`@MutationMapping` 을 generic 하게 합성한다. **WorkLog 등 구체 기능을 이름으로 알지 않는다.**
- 있으면 켜진다: 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:inbound:graphql')`
한 줄로 고른다(기본 조립에는 없다). `APP_GRAPHQL_ENABLED=false`(`app.graphql.enabled`)만 끄며,
그때 `GraphQlActivationEnvironmentPostProcessor`가 Spring GraphQL 자동 설정도 exclude 한다.
실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께
명시해야 한다.
## 오류 코드 소유
`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현
코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를
`GraphQlErrorCode`에 둔다.
- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로
실패한다.
- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다.
GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 —
DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25).
- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire
계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다.
- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에
더하지 않는다.
`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를
고정한다.
## 허용
- `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제
의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이
거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일
의존해야 했고, 그건 의존 방향이 뒤집힌다.
- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음).
- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용),
`spring-boot-starter-security`(HTTP 인증/CORS qualification 용),
`io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**).
- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가
소유하고 production jar 에 들어가지 않는다.
- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`).
**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`·
`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만
`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를
고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
게이트가 이 선언을 요구한다.
## 금지
- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드
포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이
모듈을 자동 커버 — per-module 규칙 추가 불필요).
- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의
`HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다.
- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다.
## 오류 대응 (`Category → ErrorType`)
모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전
pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부
(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된
application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의
`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한
실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안
걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는
shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category →
wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다.
DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정).
## 향후 adopter 의 feature 기여 방법
- **스키마**: adopter feature 가 `src/main/resources/graphql/*.graphqls` 를 두면
`classpath:graphql/**` 병합으로 합칠 수 있다.
- **핸들러**: adopter 가 `@Controller` + `@QueryMapping`/`@MutationMapping` 빈을 등록하면 자동
바인딩된다.
- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나
`ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다.
템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는
health 스키마만 소유한다.
## 구현된 플랫폼 범위 — 등급으로 말한다
"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을
쓰고, **현재 등급보다 높게 표현하지 않는다.**
| 등급 | 의미 |
| --- | --- |
| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. |
| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. |
| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. |
| `production-verified` | 실부하·장애 시나리오 증거가 있다. |
| Capability | 등급 | 증거 |
| --- | --- | --- |
| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) |
| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 |
| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 |
| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 |
| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` |
| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) |
| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 |
| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` |
| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) |
| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 |
| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 |
| 실부하·장애 | 미달성 | 증거 없음 |
여전히 미구현인 것:
- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음).
- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`,
`advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에
삭제했다.
- 실제 datastore 통합 증거 — 없다.
- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription
replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다
(`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는
형태로 새로 만든다.
## 테스트
```bash
cd src
./gradlew :adapter:inbound:graphql:test --console=plain
./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain
```
테스트 레인:
```bash
./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버)
```
`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면
실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다.
## 아티팩트 게이트
```bash
./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain
./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain
```
- `GraphQlProductionClassesTest` — production 클래스에 `testkit`/`InMemory`/`ForTests`/`Fixture`/
`TestContext` 가 하나라도 있으면 실패한다(`test` 의 일부). 테스트용 request context 헬퍼(`testkit/GraphQlRequestContexts`)는
`src/testFixtures/java` 가 소유한다.
- `verifyGraphQlApiSurface` — `docs/architecture/graphql-api-surface.txt` 스냅샷과 실제 public
타입 목록이 다르면 실패한다. 단일 jar 안에서 `public` 은 모든 adopter 에게 public 이므로,
표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후:
`./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange`.
- mutation 멱등성 — 저장소에 연결된 적 없는 `GraphQlMutationIdempotencyInterceptor`·context·
fingerprint 와 `idempotencyKey` extension 허용을 2026-09-25 에 삭제했다. Stable 기본
`GraphQlExtensionsPolicy` 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면
application `IdempotencyExecutor` 를 use case 안에서 쓴다.
+1 -218
View File
@@ -1,218 +1 @@
# adapter:inbound:graphql — inbound GraphQL 어댑터(골격 장치)
## 등록 정보
- 모듈 ID: `adapter-inbound-graphql`
- Gradle 경로: `:adapter:inbound:graphql`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:graphql:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
Package root: `dev.caskeleton.adapter.inbound.graphql`.
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈
규칙 SSOT).
## 플랫폼 모듈 = sub-package (Gradle 모듈 아님)
GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이
leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은
방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성
SSOT(`src/config/architecture/modules.json`)까지 밀어올리지 않는다는 선택이다.
**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매
플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는
`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간
낡는다. 즉 이 레포에는 두 패턴이 공존한다:
| | 방식 | 경계 강제 |
| --- | --- | --- |
| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 |
| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) |
어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다.
sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/`
모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다
(`docs/capability-status.md` 제거 표). 지금 기계가 지키는 것은 전송 경계 두 가지뿐이다 —
`GraphQlTransportBoundaryArchitectureTest`(ArchUnit, 이 leaf 패키지 대상):
- resolver(`@SchemaMapping` 계열·`@BatchMapping`) 시그니처는 전송 타입만 쓴다. 반환·인자 타입과
그 제네릭 인자에 raw `Map`, persistence 매핑 타입(`@Entity`/`@Document`/`@Table` 등, 단순명
매칭), domain·outbound adapter·JPA/Hibernate/Spring Data/JDBC/Mongo/AWS/gRPC/Kafka 타입이
오면 실패한다.
- raw `DataFetcher` 구현은 `scalar`·`schema`·`execution` 패키지에만 둔다.
두 규칙 모두 위반 fixture 로 실제로 잡히는지 같은 테스트가 확인한다. `graphqlStableTest` 의
required-class 검사가 이 테스트가 조용히 사라지는 것을 막는다.
## 책임
- GraphQL 전송 인프라만: 최소 health 스키마(`skeleton.graphqls`) + `HealthGraphqlController`,
프로토콜 에러 매핑(`error/GraphQlWireErrorMapper`). Spring for GraphQL 이 스키마와 컨트롤러를
자동 합성/바인딩하도록 얹는 얇은 계층이다.
- 그 위에 **GraphQL API 실행 플랫폼**(`...graphql` 하위 sub-package 군)이 스키마 계약·전송
프로파일·실행 정책·비용 한계·DataLoader·페이지네이션·에러/보안 경계·관측을
소유한다. 플랫폼은 여전히 **feature-agnostic** 이며 정책·계약·검증 기계만 제공한다.
- feature-agnostic: `classpath:graphql/**` 스키마와 모든 `@Controller` `@QueryMapping`/
`@MutationMapping` 을 generic 하게 합성한다. **WorkLog 등 구체 기능을 이름으로 알지 않는다.**
- 있으면 켜진다: 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:inbound:graphql')`
한 줄로 고른다(기본 조립에는 없다). `APP_GRAPHQL_ENABLED=false`(`app.graphql.enabled`)만 끄며,
그때 `GraphQlActivationEnvironmentPostProcessor`가 Spring GraphQL 자동 설정도 exclude 한다.
실제 활성화 시 composition root 는 인증/인가·CORS 정책과 GraphiQL/introspection 운영 설정을 함께
명시해야 한다.
## 오류 코드 소유
`docs/registries/error-codes.yaml`은 골격 전체의 `OperationalError` 정본이다. 전송 계층마다 다른 표현
코드를 모두 받는 registry가 아니다. 그래서 GraphQL은 자기의 유한한 플랫폼 wire 코드 catalog를
`GraphQlErrorCode`에 둔다.
- GraphQL 플랫폼 mapper는 `GraphQlErrorCode.platform(...)`을 써야 한다. 등록되지 않은 플랫폼 코드는 바로
실패한다.
- application·domain `ApiErrorCode` 값은 별도 namespace로 남고 `GraphQlErrorCode.of(...)`로 그대로 지나간다.
GraphQL은 제품 오류의 이름을 바꾸면 안 된다. 이 길로 wire에 닿는 것은 등록된 `ApiErrorCode`뿐이다 —
DataLoader의 키별 실패도 그것을 싣고, 자유 문자열을 싣지 않는다(소유자 결정 2026-09-25).
- GraphQL이 가진 새 플랫폼 코드는 `GRAPHQL_` 접두어를 쓴다. 접두어 없는 기존 플랫폼 값은 얼려 둔 옛 wire
계약이고 `legacyUnprefixedPlatformCodes()`가 하나씩 적는다.
- 모델만 있는 capability 코드는 그 capability가 출하하는 요청 경로에 닿기 전까지 `platformCodes()`에
더하지 않는다.
`GraphQlErrorCodeCatalogTest`가 출하하는 catalog 전체, 접두어 규칙, application·플랫폼 namespace 분리를
고정한다.
## 허용
- `:application-core`, `:domain-core`, `:shared-contract`. `:application-core` 는 선언만이 아니라 실제
의존이다 — object 인가의 **답하는 계약**(`dev.caskeleton.application.security.ObjectAccessPolicy`)이
거기 살기 때문이다. 이 leaf 가 그 계약을 소유했다면 application 구현체가 인바운드 전송을 컴파일
의존해야 했고, 그건 의존 방향이 뒤집힌다.
- `spring-boot-starter-graphql` (Spring Boot BOM 관리 — 버전 명시 없음).
- test scope 에 한해 `spring-boot-starter-web`(random-port 전송 테스트용),
`spring-boot-starter-security`(HTTP 인증/CORS qualification 용),
`io.micrometer:micrometer-core`(실제 `MeterRegistry` 로 metric label cardinality 를 **측정**).
- `java-test-fixtures` — 계약 스위트·통합 fixture·in-memory 스텁은 `src/testFixtures/java` 가
소유하고 production jar 에 들어가지 않는다.
- test scope 에 한해 `archunit-junit5` — 전송 경계 규칙(`GraphQlTransportBoundaryArchitectureTest`).
**서버는 이 leaf 가 고르지 않는다.** production 파일 중 `org.springframework.web`·
`org.springframework.http` 을 import 하는 것은 **하나도 없다**(servlet API 는 body 상한 필터만
`compileOnly` 로 쓴다). 서버 선택은 composition root 의 결정이고, `gradle.lockfile` 이 이를
고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
게이트가 이 선언을 요구한다.
## 금지
- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드
포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`, 일반 `..adapter.inbound..` 규칙이 이
모듈을 자동 커버 — per-module 규칙 추가 불필요).
- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의
`HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다.
- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다.
## 오류 대응 (`Category → ErrorType`)
모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전
pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부
(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된
application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의
`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한
실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안
걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는
shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category →
wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다.
DataLoader 키 실패는 등록된 `ApiErrorCode` 만 싣는다(`GraphQlBatchLoadException`, 2026-09-25 소유자 결정).
## 향후 adopter 의 feature 기여 방법
- **스키마**: adopter feature 가 `src/main/resources/graphql/*.graphqls` 를 두면
`classpath:graphql/**` 병합으로 합칠 수 있다.
- **핸들러**: adopter 가 `@Controller` + `@QueryMapping`/`@MutationMapping` 빈을 등록하면 자동
바인딩된다.
- **도메인 예외 매핑**: adopter 는 자신의 `DataFetcherExceptionResolver` 를 추가하거나
`ApiErrorCarrier` 를 사용해 안정적 코드로 매핑할 수 있다.
템플릿에는 feature GraphQL schema/controller/resolver 가 없다. 이 leaf 는
health 스키마만 소유한다.
## 구현된 플랫폼 범위 — 등급으로 말한다
"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을
쓰고, **현재 등급보다 높게 표현하지 않는다.**
| 등급 | 의미 |
| --- | --- |
| `modelled` | 정책·계약 객체가 있고 단위 테스트가 있다. 요청 경로에는 없다. |
| `wired` | Spring 실행 경로에 연결돼 있고, 실제 endpoint 테스트가 그 사실을 증명한다. |
| `integration-verified` | 실제 외부 시스템(datastore/broker) 과의 통합 증거가 있다. |
| `production-verified` | 실부하·장애 시나리오 증거가 있다. |
| Capability | 등급 | 증거 |
| --- | --- | --- |
| 실행 파이프라인 / 인가 / cost 예산 | `wired` | `systemTest/runtime/GraphQlPlatformExecutionPathTest` (random-port, 거부 시 resolver 호출 0회) |
| depth/complexity 제한 (`cost/`) | `wired` | 같은 테스트의 depth/alias/complexity 케이스 |
| preparsed document cache (`execution/`) | `wired` | `GraphQlPreparsedDocumentAdapter` + 같은 테스트의 캐시 hit 케이스 |
| 커스텀 scalar (`scalar/`) | `wired` | 같은 테스트의 scalar coercion 케이스 |
| 요청 크기 (`http/`, body limit filter) | `wired` | `runtime/GraphQlPlatformWebInterceptorRequestBoundsTest`(auto-configured interceptor 로 byte·shape·extension 거부), `http/GraphQlRequestBoundsTest` |
| 관측 tag cardinality (`observation/`) | `wired` | `runtime/GraphQlRequestObservationConventionAdapter` 가 Spring 의 `ExecutionRequestObservationConvention` 을 구현해 Boot 의 `GraphQlObservationAutoConfiguration` 이 이 컨벤션을 가져간다. `autoconfigure/GraphQlObservationWiringTest`(프레임워크가 실제로 해석), `runtime/GraphQlRequestObservationConventionAdapterTest`(실제 `MeterRegistry` 에 임의 이름 10,000개 → series 1개) |
| object 인가 (`security/`) | `modelled` | 답하는 계약은 중립 `dev.caskeleton.application.security.ObjectAccessPolicy` 가 소유하고 이 leaf 는 `ApplicationObjectAuthorization` 매핑만 가진다. 실행 경로에 연결하는 configuration 은 없다 |
| DataLoader/batching (`dataloader/`) | `wired` | `runtime/GraphQlBatchLoaderRegistrationTest` (실제 graphql-java 실행 + Spring `BatchLoaderRegistry`, 50 parent → 3 downstream 호출), `dataloader/GraphQlBatchContractTest` |
| 요청 deadline (`maxExecutionTime`) | `wired` | `systemTest/runtime/GraphQlRequestDeadlineTest`(virtual thread: deadline 근처 `REQUEST_TIMEOUT`, 하위 필드 미실행), `GraphQlRequestDeadlineOnRequestThreadTest`(요청 스레드: 느린 resolver 가 끝난 뒤 응답 — 한계). 이미 도는 resolver 는 끊지 않는다(README 「요청 deadline」) |
| per-parent fetch(N+1) 신호 | `wired` | `systemTest/runtime/GraphQlPerParentFetchTest`(일반 `@SchemaMapping` 자식 → WARN 1줄 + `graphql.per.parent.fetch`, registrar 자식 → 조용함). 거부하지 않는다 |
| cursor 서명·connection (`pagination/`), fetch profile (`fetch/`) | 라이브러리 | 요청 경로에 없다. 서비스가 직접 호출한다 — README "라이브러리 API". `autoconfigure/GraphQlPolicyRequestPathTest` 가 auto-configuration 이 codec·key ring 을 만들지 않음을 고정 |
| 실부하·장애 | 미달성 | 증거 없음 |
여전히 미구현인 것:
- feature GraphQL schema/resolver — 이 leaf 는 health 표면만 소유한다(변경 없음).
- 실부하 성능/장애 시나리오 증거 — 없다. 시나리오 카탈로그와 릴리스 게이트(`release/`,
`advanced/release/`)와 스키마 호환성 비교기(`compat/`)는 호출하는 곳이 없어 2026-09-25 에
삭제했다.
- 실제 datastore 통합 증거 — 없다.
- `advanced/**`(SSE·RSocket·federation·incremental·HTTP GET·persisted operation·subscription
replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다
(`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는
형태로 새로 만든다.
## 테스트
```bash
cd src
./gradlew :adapter:inbound:graphql:test --console=plain
./gradlew :adapter:inbound:graphql:graphqlTransportQualificationTest --console=plain
```
테스트 레인:
```bash
./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버)
```
`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면
실패한다(`build.gradle` 의 strict lane `requires` + `rejectSkipped`). 같은 클래스는 `test` 에서도 돈다.
## 아티팩트 게이트
```bash
./gradlew :adapter:inbound:graphql:test --tests '*GraphQlProductionClassesTest' --console=plain
./gradlew :adapter:inbound:graphql:verifyGraphQlApiSurface --console=plain
```
- `GraphQlProductionClassesTest` — production 클래스에 `testkit`/`InMemory`/`ForTests`/`Fixture`/
`TestContext` 가 하나라도 있으면 실패한다(`test` 의 일부). 테스트용 request context 헬퍼(`testkit/GraphQlRequestContexts`)는
`src/testFixtures/java` 가 소유한다.
- `verifyGraphQlApiSurface` — `docs/architecture/graphql-api-surface.txt` 스냅샷과 실제 public
타입 목록이 다르면 실패한다. 단일 jar 안에서 `public` 은 모든 adopter 에게 public 이므로,
표면 증가는 리뷰 결정이지 빌드 부산물이 아니다. 승인 후:
`./gradlew :adapter:inbound:graphql:updateGraphQlApiSurface -PapproveGraphQlApiSurfaceChange`.
- mutation 멱등성 — 저장소에 연결된 적 없는 `GraphQlMutationIdempotencyInterceptor`·context·
fingerprint 와 `idempotencyKey` extension 허용을 2026-09-25 에 삭제했다. Stable 기본
`GraphQlExtensionsPolicy` 는 어떤 extension key 도 허용하지 않는다. 요청 재생 멱등성이 필요하면
application `IdempotencyExecutor` 를 use case 안에서 쓴다.
@AGENTS.md
+1 -1
View File
@@ -4,7 +4,7 @@
`dev.caskeleton.adapter.inbound.graphql`.
허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은
[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
모아둔 참조용 기록이다.
---
+115
View File
@@ -0,0 +1,115 @@
# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치)
## 등록 정보
- 모듈 ID: `adapter-inbound-grpc`
- Gradle 경로: `:adapter:inbound:grpc`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
Package root: `dev.caskeleton.adapter.inbound.grpc`.
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈
규칙 SSOT).
## 책임
- gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`),
feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` +
`GrpcExceptionHandlingInterceptor`), 그리고 `.proto` 없이도 부팅하는 최소 표면(standard
health, 명시적으로 켠 경우에만 reflection).
- feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을
이름으로 알지 않는다.
## 허용
- `:application-core`, `:domain-core`, `:shared-contract`.
- `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services),
`spring-boot-starter`, `spring-boot-starter-validation`.
## 금지
- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드
포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`).
- 이 스켈레톤 모듈에서의 `com.google.protobuf` 플러그인 / `.proto` — 향후 도입하는 스키마와
서비스는 consuming feature 모듈이 소유한다.
- 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의
`HealthcheckController` 와 동일 원칙).
## 설정 손잡이 (`app.grpc.server.*`)
타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다
(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이
`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*`
키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`).
| key | default | 의미 |
|---|---|---|
| `enabled` | `true` | 모듈이 있으면 켜진다. `false`면 관련 빈과 listener가 생기지 않는다 |
| `port` | `9090` | 바인딩 TCP 포트. `0` 이면 ephemeral 포트(테스트) |
| `bindAddress` | `127.0.0.1` | P1 insecure listener 바인드. loopback 주소만 허용한다 |
| `allowInsecureLocal` | `false` | local plaintext 위험을 명시적으로 승인하는 개발용 override |
| `reflectionEnabled` | `false` | v1 server reflection 노출을 독립적으로 opt-in 한다 |
| `shutdownGraceSeconds` | `5` | graceful shutdown 전체 예산(초, 0 이상). drain 대기를 포함한다 |
| `shutdownDrainSeconds` | `2` | health NOT_SERVING 뒤 listener 를 열어 둔 채 기다리는 초. `shutdownGraceSeconds` 이하 |
| `maxInboundMessageBytes` | `1048576` | 요청 메시지 상한. 넘으면 `RESOURCE_EXHAUSTED` (플랫폼 `GrpcTransportLimits`와 같은 값) |
| `maxInboundMetadataBytes` | `8192` | 호출당 metadata 상한 (플랫폼과 같은 값) |
| `maxConcurrentCallsPerConnection` | `100` | 연결당 동시 호출(HTTP/2 stream) 상한. 넘친 호출은 클라이언트에서 기다린다 |
| `executorMaxPoolSize` | `32` | feature 호출을 실행하는 고정 스레드 수 (플랫폼 executor 기본값) |
| `executorQueueCapacity` | `256` | 스레드를 기다릴 수 있는 호출 수(1..10000). 넘친 호출은 즉시 `RESOURCE_EXHAUSTED` |
| `defaultDeadline` | `10s` | deadline 없는(또는 더 긴) feature 호출의 서버 deadline. 넘으면 `DEADLINE_EXCEEDED` |
| `keepAliveTime` / `keepAliveTimeout` | `30s` / `10s` | 서버 keep-alive ping 간격 / 응답 대기 (플랫폼 `GrpcServerProfile.stable`) |
| `permitKeepAliveTime` | `30s` | 클라이언트 ping 최소 간격. `keepAliveTime` 이하 |
| `maxConnectionAge` / `maxConnectionAgeGrace` | `30m` / `30s` | 연결 수명과 GOAWAY 뒤 유예 |
한도 값의 근거·플랫폼과의 대응·포화 동작은 [README.md](README.md) 「서버 한도」 절이 소유한다.
`port`는 0..65535 범위여야 한다. 현재 transport credential은 plaintext뿐이므로
`enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면
configuration binding/startup 단계에서 실패한다.
## 이 capability 채택하기
gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다.
1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존
edge를 더한다.
2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에
`dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다.
3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다.
4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다.
5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다.
**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은
Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을
받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS
credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다.
## Feature 기여 방법
현재 저장소에는 feature RPC가 없다. 향후 feature를 도입할
때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한
개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면
listener 시작이 실패한다. 정책은 `Optional<Principal> authenticate(Metadata)`이고, 돌려준
호출자는 gRPC `Context`에 담겨 handler가 `GrpcAuthenticatedCaller.current()`로 읽는다. 정책이
빈 값·`null`을 반환하거나 예외를 던진 요청은 feature handler에 닿지
않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드
이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다).
## P1 증거와 한계
- `GrpcSafeActivationTest`: 기본 비활성, 관련 빈 부재, 설정 검증, feature 인증 정책 필수 조건.
- `GrpcP1BoundaryWireTest`: 실제 loopback ephemeral Netty unary service의 auth 성공/실패,
reflection-off, handler/listener/observer/raw-status 오류 sanitization과 sentinel redaction.
서버 한도(메시지 크기, 기본 deadline, 연결당 동시 호출, executor 포화)도 같은 wire 에서 검증한다.
이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS,
external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다.
## 테스트
```bash
cd src
./gradlew :adapter:inbound:grpc:test
```
+1 -115
View File
@@ -1,115 +1 @@
# adapter:inbound:grpc — inbound gRPC 어댑터(골격 장치)
## 등록 정보
- 모듈 ID: `adapter-inbound-grpc`
- Gradle 경로: `:adapter:inbound:grpc`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:grpc:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
Package root: `dev.caskeleton.adapter.inbound.grpc`.
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈
규칙 SSOT).
## 책임
- gRPC 전송 인프라만: 서버 수명주기(`GrpcServerRunner`), 타입드 설정(`GrpcServerSettings`),
feature 인증 정책 경계, 프로토콜 에러 매핑(`GrpcStatusMapper` +
`GrpcExceptionHandlingInterceptor`), 그리고 `.proto` 없이도 부팅하는 최소 표면(standard
health, 명시적으로 켠 경우에만 reflection).
- feature-agnostic: 모든 `io.grpc.BindableService` 빈을 generic 하게 등록하며 구체 기능을
이름으로 알지 않는다.
## 허용
- `:application-core`, `:domain-core`, `:shared-contract`.
- `io.grpc:*` (grpc-netty-shaded / grpc-protobuf / grpc-stub / grpc-services),
`spring-boot-starter`, `spring-boot-starter-validation`.
## 금지
- outbound 어댑터(`:adapter:outbound:*`)에 대한 직접 의존 — 인바운드는 application 아웃바운드
포트를 통해서만 persistence/messaging/cache/http 에 닿는다 (ArchUnit
`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`).
- 이 스켈레톤 모듈에서의 `com.google.protobuf` 플러그인 / `.proto` — 향후 도입하는 스키마와
서비스는 consuming feature 모듈이 소유한다.
- 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의
`HealthcheckController` 와 동일 원칙).
## 설정 손잡이 (`app.grpc.server.*`)
타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다
(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이
`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*`
키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`).
| key | default | 의미 |
|---|---|---|
| `enabled` | `true` | 모듈이 있으면 켜진다. `false`면 관련 빈과 listener가 생기지 않는다 |
| `port` | `9090` | 바인딩 TCP 포트. `0` 이면 ephemeral 포트(테스트) |
| `bindAddress` | `127.0.0.1` | P1 insecure listener 바인드. loopback 주소만 허용한다 |
| `allowInsecureLocal` | `false` | local plaintext 위험을 명시적으로 승인하는 개발용 override |
| `reflectionEnabled` | `false` | v1 server reflection 노출을 독립적으로 opt-in 한다 |
| `shutdownGraceSeconds` | `5` | graceful shutdown 전체 예산(초, 0 이상). drain 대기를 포함한다 |
| `shutdownDrainSeconds` | `2` | health NOT_SERVING 뒤 listener 를 열어 둔 채 기다리는 초. `shutdownGraceSeconds` 이하 |
| `maxInboundMessageBytes` | `1048576` | 요청 메시지 상한. 넘으면 `RESOURCE_EXHAUSTED` (플랫폼 `GrpcTransportLimits`와 같은 값) |
| `maxInboundMetadataBytes` | `8192` | 호출당 metadata 상한 (플랫폼과 같은 값) |
| `maxConcurrentCallsPerConnection` | `100` | 연결당 동시 호출(HTTP/2 stream) 상한. 넘친 호출은 클라이언트에서 기다린다 |
| `executorMaxPoolSize` | `32` | feature 호출을 실행하는 고정 스레드 수 (플랫폼 executor 기본값) |
| `executorQueueCapacity` | `256` | 스레드를 기다릴 수 있는 호출 수(1..10000). 넘친 호출은 즉시 `RESOURCE_EXHAUSTED` |
| `defaultDeadline` | `10s` | deadline 없는(또는 더 긴) feature 호출의 서버 deadline. 넘으면 `DEADLINE_EXCEEDED` |
| `keepAliveTime` / `keepAliveTimeout` | `30s` / `10s` | 서버 keep-alive ping 간격 / 응답 대기 (플랫폼 `GrpcServerProfile.stable`) |
| `permitKeepAliveTime` | `30s` | 클라이언트 ping 최소 간격. `keepAliveTime` 이하 |
| `maxConnectionAge` / `maxConnectionAgeGrace` | `30m` / `30s` | 연결 수명과 GOAWAY 뒤 유예 |
한도 값의 근거·플랫폼과의 대응·포화 동작은 [README.md](README.md) 「서버 한도」 절이 소유한다.
`port`는 0..65535 범위여야 한다. 현재 transport credential은 plaintext뿐이므로
`enabled=true`는 `allowInsecureLocal=true`와 실제 loopback `bindAddress`가 함께 없으면
configuration binding/startup 단계에서 실패한다.
## 이 capability 채택하기
gRPC도 **빌드 조립에서 고르는 것**이다. 기본 bootJar에는 이 leaf가 없다.
1. 쓰는 조립에 `:adapter:inbound:grpc`를 더하고 `config/architecture/modules.json`에 맞는 허용 의존
edge를 더한다.
2. 설정은 capability 루트로 등록한다. 출하하는 `@ConfigurationPropertiesScan`에
`dev.caskeleton.adapter.inbound.grpc`를 더하지 않는다.
3. 기능의 `BindableService`와 정확히 하나의 `GrpcAuthenticationPolicy`를 준다.
4. 승격 전에 `./gradlew :adapter:inbound:grpc:test :conditionalTransportQualification`을 돌린다.
5. 고른 런타임 계약에 대한 조립 소유의 설정·env registry 항목이 생기기 전에는 운영 채택이 끝난 것이 아니다.
**지금 전송의 한계:** P1 서버는 평문이고 일부러 loopback bind만 허용한다. 그래서 같은 프로세스나 같은
Pod sidecar 통신에만 맞다. 보통 Kubernetes Service를 위해 `0.0.0.0`에 bind할 수 없고, 다른 Pod의 트래픽을
받을 수 없으며, 클러스터를 향한 gRPC endpoint로 내세우면 안 된다. 클러스터에 노출하려면 미뤄 둔 TLS/mTLS
credential 경로와 따로 검증한 loopback 아닌 bind가 필요하다.
## Feature 기여 방법
현재 저장소에는 feature RPC가 없다. 향후 feature를 도입할
때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한
개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면
listener 시작이 실패한다. 정책은 `Optional<Principal> authenticate(Metadata)`이고, 돌려준
호출자는 gRPC `Context`에 담겨 handler가 `GrpcAuthenticatedCaller.current()`로 읽는다. 정책이
빈 값·`null`을 반환하거나 예외를 던진 요청은 feature handler에 닿지
않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드
이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다).
## P1 증거와 한계
- `GrpcSafeActivationTest`: 기본 비활성, 관련 빈 부재, 설정 검증, feature 인증 정책 필수 조건.
- `GrpcP1BoundaryWireTest`: 실제 loopback ephemeral Netty unary service의 auth 성공/실패,
reflection-off, handler/listener/observer/raw-status 오류 sanitization과 sentinel redaction.
서버 한도(메시지 크기, 기본 deadline, 연결당 동시 호출, executor 포화)도 같은 wire 에서 검증한다.
이 증거는 local insecure unary qualification일 뿐 production-ready 근거가 아니다. TLS/mTLS,
external bind, 메서드별 deadline, streaming/backpressure, generated protobuf 호환성은 P2로 남아 있다.
## 테스트
```bash
cd src
./gradlew :adapter:inbound:grpc:test
```
@AGENTS.md
+1 -1
View File
@@ -4,7 +4,7 @@
`dev.caskeleton.adapter.inbound.grpc`.
허용/금지 의존, 모듈 규칙, 설정 knob, 테스트 명령 같은 **모듈 규칙**은
[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
모아둔 참조용 기록이다.
---
+23
View File
@@ -0,0 +1,23 @@
# adapter:inbound:messaging
- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본:
`src/config/architecture/modules.json`.
- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는
inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의
`TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의
`MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에
아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다.
- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이
없다. 허용 edge는 registry 항목에서만 온다.
- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접
만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다
(`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계,
`docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」,
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`,
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler<T>`)만 구현하고,
`Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`).
- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`.
실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`).
- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본
group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다.
- 설계와 버린 대안: `README.md`.
+1 -23
View File
@@ -1,23 +1 @@
# adapter:inbound:messaging
- 모듈 ID `adapter-inbound-messaging`, Gradle 경로 `:adapter:inbound:messaging`. registry 정본:
`src/config/architecture/modules.json`.
- 책임: 들여온 메시징 플랫폼의 애플리케이션 소비 쪽이다 — 플랫폼이 애플리케이션에서 받아야 하는
inbox 부품(애플리케이션 DataSource 위의 `JdbcInboxRepository`, 그 `PlatformTransactionManager` 위의
`TransactionRunner`, 자기 Flyway stream `MessagingInboxSchemaStream`인 inbox migration)과 애플리케이션의
`MessageHandler` 구현들이다. 핸들러 하나는 전달 하나를 유스케이스 호출 하나로 바꾼다. 핸들러는 그 밖에
아무것도 등록하지 않는다: 플랫폼이 그 `destination()`과 `schemaVersions()`가 선언한 것을 decode한다.
- 경계: 핸들러에 업무 규칙을 두지 않는다(HARD-STOP 4). 영속 엔티티나 repository가 없다. broker SDK 타입이
없다. 허용 edge는 registry 항목에서만 온다.
- 쓰기 유스케이스를 부르는 핸들러는 `@SystemCaller(reason = ...)`이고 `@SystemInvoked` 유스케이스를 직접
만든다. 유스케이스는 bean이 아니고, 사용자 전송 계층은 핸들러를 부르지 않는다
(`docs/manual/09-outbox-events.md` 「소비 — 이벤트를 받는 쪽」 순서 4단계,
`docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」,
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`,
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). 핸들러는 프로젝트 타입(`MessageHandler<T>`)만 구현하고,
`Runnable`이나 프로젝트 밖의 다른 타입은 구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`).
- 시험: 자동 구성과 inbox 동작을 보는 시험. `./gradlew :adapter:inbound:messaging:check`.
실제 Kafka + PostgreSQL 재전달 lane은 `messagingInboxRedeliveryIntegrationTest`다(`:integrationCheck`).
- 좌표: group `dev.caskeleton.adapter.inbound`, jar `adapter-inbound-messaging`. 지우지 않는다 — 기본
group이면 Gradle에게 이 프로젝트와 `:adapter:outbound:messaging`은 같은 모듈이 된다.
- 설계와 버린 대안: `README.md`.
@AGENTS.md
@@ -0,0 +1,45 @@
# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리
## 등록 정보
- 모듈 ID: `adapter-inbound-web-advanced`
- Gradle 경로: `:adapter:inbound:web-advanced`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain`
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄,
설정은 [README.md](README.md)에 있다.
## 책임
- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch /
Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning,
operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록.
- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의
`AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다.
## 규칙
- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다.
`app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다.
- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다.
- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다
(서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나
`@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports
한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`).
- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와
OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`).
- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다:
forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache
header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`).
그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`).
- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음,
`application-core`·`domain-core`로 새는 DTO 없음.
## 테스트
```bash
cd src
./gradlew :adapter:inbound:web-advanced:check --console=plain
./gradlew :adapter:inbound:web-advanced:webAdvancedTest --console=plain
```
+1 -45
View File
@@ -1,45 +1 @@
# adapter:inbound:web-advanced — 골라 쓰는 web 라이브러리
## 등록 정보
- 모듈 ID: `adapter-inbound-web-advanced`
- Gradle 경로: `:adapter:inbound:web-advanced`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-advanced:test --console=plain`
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.inbound.web.advanced`. 무엇을 주는지, 서비스가 더하는 한 줄,
설정은 [README.md](README.md)에 있다.
## 책임
- servlet 운영 경로가 닿지 않는 web 라이브러리 코드: streaming, virtual thread admission, JSON Patch /
Merge Patch, CBOR·XML codec, OpenAPI 3.2 생성기와 breaking change 정책, URI·method 정책, versioning,
operation·budget·contract catalog, security context bridge, 멱등 응답 codec, route 목록.
- 스위치가 있는 MVC capability 셋(virtual thread, NDJSON, JSON sequence). 각각 이 leaf의
`AutoConfiguration.imports`에 적힌 `@AutoConfiguration`이고 기본은 꺼져 있다.
## 규칙
- 어떤 기본 조립에도 없다. `app-bootstrap` main은 이 leaf에 의존하지 않는다.
`app-bootstrap`은 저장소 전체 ArchUnit import가 이 leaf를 읽도록 `testRuntimeOnly`로만 받는다.
- `adapter:inbound:web`(`core` 어휘)에 의존하고, 그 반대는 없다.
- component scan에 걸리는 stereotype이 없다. 쓰는 애플리케이션은 어댑터 패키지를 scan할 수 있다
(서비스가 `dev.caskeleton.adapter.inbound.web`을 scan할 수 있다). 그래서 여기 둔 `@Configuration`이나
`@Component`는 스위치가 무엇을 말하든 만들어진다. 스위치가 있는 배선은 `@AutoConfiguration` + imports
한 줄이다. import되는 도우미는 stereotype을 달지 않는다(`MvcStreamingSupportConfiguration`).
- 아무 코드도 읽지 않는 설정, 시험만 부르는 `main`의 gate·증거 타입을 두지 않는다 — 릴리스 gate와
OpenAPI 승격 보고서를 바로 그 이유로 지웠다(`docs/capability-status.md`).
- 기능마다 세대 하나. 운영 web 경로가 이미 다른 방식으로 하는 일을 여기서 다시 구현하지 않는다:
forwarded header(`server.forward-headers-strategy`), CORS·CSRF(`CorsSettings`/`SecurityConfig`), cache
header(`CacheControlFilter`), JSON mapper(Boot의 `JsonMapper`), OpenAPI 손질(`OpenApiContractConfig`).
그 중복과 WebFlux `functional` 패키지는 2026-09-25에 지웠다(`docs/capability-status.md`).
- `adapter:inbound:web`의 inbound 어댑터 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음,
`application-core`·`domain-core`로 새는 DTO 없음.
## 테스트
```bash
cd src
./gradlew :adapter:inbound:web-advanced:check --console=plain
./gradlew :adapter:inbound:web-advanced:webAdvancedTest --console=plain
```
@AGENTS.md
+172
View File
@@ -0,0 +1,172 @@
# adapter:inbound:web — inbound HTTP 어댑터
## 등록 정보
- 모듈 ID: `adapter-inbound-web`
- Gradle 경로: `:adapter:inbound:web`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.inbound.web`.
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
## 책임
- HTTP controller.
- 요청·응답 DTO.
- 요청 DTO를 application command로 바꾸기.
- 인증, 검증, 오류 대응, filter, web·보안 설정.
- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥.
- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는,
전송 계층이 가진 OpenAPI 손질.
모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports`
루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다.
`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만
뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다.
이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이
이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual
thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context
bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다.
운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다
(Gradle registry + ArchUnit `WEB-ARCH-ADV`).
## 허용
- `:application-core`
- `:domain-core`
- `:shared-contract`
- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는
모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그
leaf에서 이 클래스만 허용한다.
- Spring Web·Security·Validation 의존성.
## 금지
- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기.
- controller에서 repository나 JPA 엔티티에 직접 접근하기.
- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙.
- DTO가 application이나 domain으로 새는 것.
## 경계 검증과 mapper 계약
`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위
가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임
패턴도 정한다.
- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`,
`fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을
`false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지
**않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는
wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional<T>`)을 써서 JSON `null`이 primitive `0`이 되지 못하게
한다.
- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는
*없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에
`org.openapitools:jackson-databind-nullable`(`JsonNullable<T>`)이나 `Optional<T>` wrapper를 쓴다.
- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL
정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로
보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한
`IllegalArgumentException`은 계속 `BAD_PARAMETER`다.
- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은
`application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다.
`@Valid` cascade 깊이는 3 이하로 둔다.
- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나
`LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다
(`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command`
타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다.
- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지
않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나
`RequestContextHolder`로 `requestId` / `traceId`를 전파한다.
- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에
닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답
원본 타입은 `domain-core`로 새면 안 된다.
- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가
실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로
답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다.
이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는
다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의
catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다.
기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약
(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`,
`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는
애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`).
## schema·직렬화 계약
`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1
*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch<T>` + `JsonNullable`,
B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의
`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제
설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`).
- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은
`JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` →
`"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z`
offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대
없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다.
- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과
schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가
큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융
endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를
잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할
때 정한다.
- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다
(`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로
만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다.
- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1
`read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지
않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch<T>`(B2)로
나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다.
- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운
필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용
Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은
다른 브랜치다.
## 업무 규칙 검증 계약
`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서,
「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과
계약 시험이 강제한다(새 런타임 장치가 아니다).
| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 |
|---|---|---|---|---|
| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` |
| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` |
| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 |
| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 |
- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은
`adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로
나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙
`VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다.
- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성
경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴
인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만
지키기」).
- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는
**클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index
이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본
`GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로
바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은
`feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다.
- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수
있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나
관련 `AGENTS.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날
위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지
`needs-confirmation`이다.
이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와
`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper
표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드
(`feature-operational-error-observability-foundation`).
## 테스트
```bash
cd src
./gradlew :adapter:inbound:web:test --console=plain
```
+1 -172
View File
@@ -1,172 +1 @@
# adapter:inbound:web — inbound HTTP 어댑터
## 등록 정보
- 모듈 ID: `adapter-inbound-web`
- Gradle 경로: `:adapter:inbound:web`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.inbound.web`.
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
## 책임
- HTTP controller.
- 요청·응답 DTO.
- 요청 DTO를 application command로 바꾸기.
- 인증, 검증, 오류 대응, filter, web·보안 설정.
- 애플리케이션이 가진 `CorrelationIdPort`로 내놓는, 걸러 낸 요청 correlation 문맥.
- `shared-contract`로 Swagger 의존을 새게 하지 않으면서 `ApiError.details`를 `type: object`로 두는,
전송 계층이 가진 OpenAPI 손질.
모든 서비스가 이 leaf를 싣는다. 그래서 servlet 운영 경로가 닿는 것만 담는다: 그 `AutoConfiguration.imports`
루트(`WebAdapterAutoConfiguration`은 envelope, filter, health, rate-limit bean을 import한다.
`WebSecurityAutoConfiguration`은 JWT chain을 import하므로, 자기 보안 방식을 가진 애플리케이션은 그 루트만
뺀다. `WebMethodSecurityAutoConfiguration`은 method security와 권한 포트를 import하고 chain을 바꿔도 남는다.
이 leaf를 scan하는 쪽은 없다), 그리고 `app-bootstrap`, `web-fileserver`, `composition:fileserver-platform`이
이름을 대는 타입과 그것이 전이로 참조하는 것. 운영 경로가 닿지 않는 라이브러리 코드(streaming, virtual
thread, patch, codec, OpenAPI 3.2, URI·method 정책, versioning, operation, budget, contract, security context
bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adapter:inbound:web-advanced`에 있다.
운영 경로에서 아무도 쓰지 않는 새 타입은 여기가 아니라 거기에 둔다. 이 leaf는 그 leaf에 의존하지 않는다
(Gradle registry + ArchUnit `WEB-ARCH-ADV`).
## 허용
- `:application-core`
- `:domain-core`
- `:shared-contract`
- `:adapter:outbound:support` — `StrictSettingsBinder`만. `app.security`(`SecuritySettings`, 인증 모드 포함)는
모든 모듈이 쓰는 엄격한 binder 하나로 바인딩한다(2026-11-01부터). ArchUnit inbound·outbound 규칙은 그
leaf에서 이 클래스만 허용한다.
- Spring Web·Security·Validation 의존성.
## 금지
- `adapter:outbound:persistence-jpa`나 다른 `adapter:outbound:*` 타입에 직접 의존하기.
- controller에서 repository나 JPA 엔티티에 직접 접근하기.
- controller, filter, config, mapper, settings 코드 안의 핵심 업무 규칙.
- DTO가 application이나 domain으로 새는 것.
## 경계 검증과 mapper 계약
`feature-boundary-validation-mapping-contract`(설계 기록)가 이 계층 경계의 동작을 정한다. 저장소 단위
가드레일(ArchUnit + Jackson 설정 + handler)은 정적 위반만 잡는다. 아래 계약은 참조 구현이 따라야 할 런타임
패턴도 정한다.
- **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`,
`fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을
`false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지
**않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는
wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional<T>`)을 써서 JSON `null`이 primitive `0`이 되지 못하게
한다.
- **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는
*없음*(바꾸지 않음), *명시한 null*(필드 비움), *값*(바꿈)을 구별해야 한다. 요청 record에
`org.openapitools:jackson-databind-nullable`(`JsonNullable<T>`)이나 `Optional<T>` wrapper를 쓴다.
- **B3 — mapper 안의 실패.** record 정규 생성자의 `IllegalArgumentException`, MapStruct가 생성한 NPE, ACL
정규화 실패 등은 `MappingException`을 던져 대응시킨다. 전역 handler가 그것을 `MAPPING_FAILED`(HTTP 400)로
보내고, `BAD_PARAMETER`나 `INTERNAL_ERROR`로 보내지 않는다. mapper가 아닌 호출자의 평범한
`IllegalArgumentException`은 계속 `BAD_PARAMETER`다.
- **B4 — 검증 층.** 클래스 수준 Bean Validation 제약은 *문법* 층(요청 DTO)에 속한다. 도메인 불변식은
`application-core` / `domain-core`에 속한다. 문법이 실패하면 `@GroupSequence(...)`로 불변식 평가를 건너뛴다.
`@Valid` cascade 깊이는 3 이하로 둔다.
- **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나
`LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다
(`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command`
타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다.
- **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지
않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나
`RequestContextHolder`로 `requestId` / `traceId`를 전파한다.
- **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에
닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답
원본 타입은 `domain-core`로 새면 안 된다.
- **B8 — bulk endpoint의 부분 성공.** envelope `success = true`는 모든 항목이 성공했을 때뿐이다. 일부가
실패하면 `success = false` + `error.code = BATCH_PARTIAL_FAILURE` + `error.details[]`(항목별 배열)로
답한다 — 단일 항목 endpoint와 모양이 다르다. 모양이 다르다는 것을 OpenAPI spec에 적는다.
이 모듈을 쓰는 모듈의 도메인 `@RestControllerAdvice`에는 `@Order(Ordered.HIGHEST_PRECEDENCE)`를 단다(또는
다른 방법으로 이 모듈의 기본 `GlobalExceptionHandler`보다 앞에 둔다). 그렇지 않으면 기본 handler의
catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ERROR`로 만든다.
기본 운영 handler(`error/GlobalExceptionHandler`), 오류 코드 계약
(`dev.caskeleton.shared.error.ApiErrorCode` + `OperationalError`), `error/ErrorResponseFactory`,
`envelope/EnvelopeBodyAdvice`는 이제 운영 모듈(`adapter:inbound:web` / `shared-contract`)에 있어서, 돌아가는
애플리케이션이 그것을 준다. 기능 전용 예외 handler와 오류 코드는 그 기능을 가진 모듈에 둔다(`docs/manual/06-errors.md`).
## schema·직렬화 계약
`feature-schema-serialization-contract`(설계 기록)가 wire 계약의 *응답을 만드는* 쪽을 정한다 — 위 B1
*요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch<T>` + `JsonNullable`,
B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의
`application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제
설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`).
- **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은
`JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` →
`"YYYY-MM-DD"`). 숫자 epoch나 `[y,m,d,...]` 배열이 되지 않는다. 서버 시간대는 **UTC**다: 시각은 `Z`
offset을 가진 `OffsetDateTime`/`Instant`로 낸다. 날짜만 있는 달력 필드에만 `LocalDate`를 쓴다. 시간대
없는 `LocalDateTime`을 응답 DTO에 넣지 **않는다** — offset 없이 직렬화되어 계약을 깬다.
- **S2 — 돈·BigDecimal.** 도메인이 따로 적지 않으면 기본 scale 2, 반올림 `HALF_UP`이다(KRW/JPY는 scale 0과
schema 메모). 값은 지수 표기로 직렬화되지 않는다 — 설정 키로 고정하지 않고 `JacksonSerializationPolicyTest`가
큰 값과 끝자리 0을 단언한다. API마다 JSON 표현을 **하나** 고르고 OpenAPI schema에 적는다: 공개·금융
endpoint는 **string**(`@JsonSerialize(using = ToStringSerializer.class)`. 클라이언트가 파싱하고 정밀도를
잃지 않는다), 내부 서비스 사이 endpoint는 **number + plain**. 기본값에 기대지 않는다 — endpoint를 설계할
때 정한다.
- **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다
(`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로
만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다.
- **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1
`read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지
않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch<T>`(B2)로
나타낸다. `domain-core`와 `application-core`는 이미 풀린 세 상태를 받고 wire 타입은 받지 않는다.
- **S5 — 이 브랜치의 범위 밖.** OpenAPI drift 강제는 검증 suite / api-contract-baseline의 몫이다. 지운
필드 재사용 금지 도구(`x-removed-fields` 대 markdown catalog)는 `needs-confirmation`이다. outbox·event용
Avro Schema Registry와 응답 필드 이름 바꾸기·versioning(`feature-api-compatibility-deprecation-contract`)은
다른 브랜치다.
## 업무 규칙 검증 계약
`feature-business-rule-validation-contract`(설계 기록)는 **어떤 규칙을 어느 경계에서 검증하는지** 정해서,
「검증」이 controller DTO나 DB 제약 하나로 뭉개지지 않게 한다. 위 경계·대응 계약 위에 놓이고, ArchUnit과
계약 시험이 강제한다(새 런타임 장치가 아니다).
| 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 |
|---|---|---|---|---|
| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` |
| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` |
| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 |
| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 |
- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은
`adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로
나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙
`VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다.
- **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성
경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴
인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만
지키기」).
- **C3 / C7 — 영속 무결성은 새는 것 없이 운영 오류로 대응한다.** unique·FK·check·serialization 실패는
**클라이언트에게 안전한 메시지만** 가진 `DATA_INTEGRITY` / `CONFLICT`로 대응한다. SQL 원문, 제약·index
이름, SQLState 코드, 예외 클래스, stack frame은 `error.message`나 `error.details`에 닿으면 안 된다. 기본
`GlobalExceptionHandler` catch-all이 이미 메시지를 불투명한 공용 메시지(`ClientErrorMessages.OPAQUE`)로
바꾸고 details를 `null`로 낸다. category가 맞는 대응(23505 → `CONFLICT/DB_UNIQUE_VIOLATION`, …)은
`feature-persistence-failure-baseline`의 영속 어댑터 번역기가 가진다.
- **C8 — 중복 검증에는 정본 소유자가 있어야 한다.** UX나 성능을 위해 같은 규칙을 다른 층에서 미리 검사할 수
있다(예: DB unique 제약을 따라 하는 application 사전 검사). 단 그 규칙의 **정본 소유자**를 코드 주석이나
관련 `CLAUDE.md`에 적어야 한다. 소유자를 적지 않은 중복 검증기는 리뷰에서 실패다(소리 없이 서로 어긋날
위험). 자동 규칙이 아니라 절차 게이트(PR 리뷰)다 — 소유자 표지 애너테이션이 정당해질 때까지
`needs-confirmation`이다.
이 브랜치의 범위 밖(참조만 하고 여기서 다시 구현하지 않는다): SQLState → 코드 9행 표와
`DataAccessException` 번역기(`feature-persistence-failure-baseline`), Jackson B1/B2 요청 경계 스위치와 mapper
표지 예외(`feature-boundary-validation-mapping-contract`), envelope, `Category` enum, `OperationalError` 코드
(`feature-operational-error-observability-foundation`).
## 테스트
```bash
cd src
./gradlew :adapter:inbound:web:test --console=plain
```
@AGENTS.md
+2 -2
View File
@@ -9,7 +9,7 @@ route inventory)는 opt-in leaf `adapter:inbound:web-advanced` 에 있다
([README](../web-advanced/README.md)).
허용/금지 의존, 경계 계약(B1~B8), 스키마/직렬화 계약(S1~S5), 비즈니스 규칙 검증 계약(C1~C8),
테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서
테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서
덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할
때 본다. 아래 설명은 별도 추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로
풀어 둔다.
@@ -197,7 +197,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
- **D5: RFC 7807 `ProblemDetail` 표현은 거부**하고 자체 `Envelope` 형식을 쓴다.
- **운영/전송/보안 예외만** 처리한다. 도메인 예외는 소비 모듈의 별도 `@RestControllerAdvice` 가 처리하고
Spring 이 두 advice 를 합성(compose)한다(CLAUDE.md 의 `@Order(HIGHEST_PRECEDENCE)` 규칙 참조).
Spring 이 두 advice 를 합성(compose)한다(AGENTS.md 의 `@Order(HIGHEST_PRECEDENCE)` 규칙 참조).
- **클라이언트 메시지는 allowlist다.** 예외 메시지, validation interpolated message, rejected
request value, raw request URL은
`error.message`/`details`에 넣지 않는다. `error.message`는 항상 shared-contract
+120
View File
@@ -0,0 +1,120 @@
# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계
## 등록 정보
- 모듈 ID: `adapter-inbound-websocket`
- Gradle 경로: `:adapter:inbound:websocket`
- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain`
- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`
패키지 루트: `dev.caskeleton.adapter.inbound.websocket`.
## 책임
이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다.
1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정,
handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는
만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다.
2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘
`core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의
어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을
적는다.
이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command
원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는
command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도
살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다.
이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다.
## 허용
- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존.
- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter.
- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane).
## 금지
- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기.
- repository, Spring Data, 영속 엔티티, 업무 정책 접근.
- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화.
- 켜져 있을 때 wildcard·빈 handshake origin.
- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기.
- 이 골격 leaf 안의 운영 기능 `@MessageMapping`.
- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다.
- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는
`WebSocketConnectionBudget`의 필드가 아니다.
- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다.
## 타입 있는 설정 (`app.websocket.*`)
속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만
설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다.
| 속성 | env | 기본값·역할 |
| --- | --- | --- |
| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 |
| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` |
| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 |
| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` |
| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 |
| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) |
| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) |
| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) |
| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) |
| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 |
`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다.
## 이 capability 채택하기
WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다.
1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용
edge를 더한다.
2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에
`dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다.
3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에
있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로
한다.
4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그
`SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다.
5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다:
`./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`.
## inbound 정책 (STOMP)
- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다.
- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다.
- 인증된 `SEND`는 `/app/**` 아래에만 허용한다.
- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다.
- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진
ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은
`ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그
밖에는 `WEBSOCKET_REQUEST_REJECTED`다.
## 이벤트 projection 계약
나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector<T>` bean을 기여할 수 있다.
broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이
실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는
`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로,
simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면
이벤트를 버린다(best-effort, R1).
템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다.
## 증거와 한계
| lane | 증명하는 것 |
| --- | --- |
| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 |
| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 |
| `websocketJettyTest` | Jetty에서 handler 런타임 계약 |
| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) |
| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 |
simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달,
롤백에 안전한 발행, replay·resume은 주지 않는다.
+1 -120
View File
@@ -1,120 +1 @@
# adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계
## 등록 정보
- 모듈 ID: `adapter-inbound-websocket`
- Gradle 경로: `:adapter:inbound:websocket`
- 이 모듈만 시험: `./gradlew :adapter:inbound:websocket:test --console=plain`
- 실행 기준: Java 21. Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`
패키지 루트: `dev.caskeleton.adapter.inbound.websocket`.
## 책임
이 leaf에는 **서로 다른 범위 둘**이 있고, 배포되는 기능 하나로 읽으면 안 된다.
1. **골라 쓰는 STOMP·SockJS 채널** — `stomp/**`가 Spring 전송 설정, 타입 있는 `app.websocket.*` 설정,
handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP `ERROR` 대응, 할 수 있는
만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다.
2. **servlet handler 라이브러리** — `servlet/`, `outbound/`, `budget/`과 id record 둘
`core/WebSocketConnectionId`, `protocol/WebSocketMessageId`. 설정 키도 Spring 설정도 없다: 서비스 자신의
어댑터 leaf가 `PlatformWebSocketHandler`를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을
적는다.
이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 `idempotency/` 패키지(command
원장, `WebSocketActorReference`, `WebSocketEndpointName`)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는
command는 그 유스케이스 안에서 애플리케이션 `IdempotencyExecutor`를 거친다. 범위(scope)는 다시 연결해도
살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다.
이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다.
## 허용
- `@DomainEvent` 표지를 위한 `:domain-core` 등록 의존.
- 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter.
- 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane).
## 금지
- 어떤 `adapter:outbound:*` 모듈에든 직접 의존하기.
- repository, Spring Data, 영속 엔티티, 업무 정책 접근.
- `@DomainEvent` payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화.
- 켜져 있을 때 wildcard·빈 handshake origin.
- 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기.
- 이 골격 leaf 안의 운영 기능 `@MessageMapping`.
- 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다.
- 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는
`WebSocketConnectionBudget`의 필드가 아니다.
- reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다.
## 타입 있는 설정 (`app.websocket.*`)
속성 트리 하나와 운영자 env 접두어 하나가 있다: `app.websocket.*` ↔ `APP_WEBSOCKET_*`. STOMP 채널만
설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다.
| 속성 | env | 기본값·역할 |
| --- | --- | --- |
| `app.websocket.enabled` | `APP_WEBSOCKET_ENABLED` | `true`. `false`이면 STOMP·SockJS 채널을 끈다 |
| `app.websocket.endpoint` | `APP_WEBSOCKET_ENDPOINT` | `/ws` |
| `app.websocket.allowed-origins` | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000`. 명시한 origin만 |
| `app.websocket.broadcast-destination` | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` |
| `app.websocket.channel-queue-capacity` | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000`. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수 |
| `app.websocket.message-size-limit` | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB`(Spring 기본값을 이제 명시한다) |
| `app.websocket.send-buffer-size-limit` | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB`(Spring 기본값을 이제 명시한다) |
| `app.websocket.send-time-limit` | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s`(Spring 기본값을 이제 명시한다) |
| `app.websocket.time-to-first-message` | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s`(Spring 기본값을 이제 명시한다) |
| `app.websocket.max-connections` | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000`. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다 |
`WebSocketSettings`는 `@Validated`다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다.
## 이 capability 채택하기
WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 **빌드 조립에서 고르는 것**이다.
1. 쓰는 조립의 의존성에 `:adapter:inbound:websocket`을 더하고 `config/architecture/modules.json`에 맞는 허용
edge를 더한다.
2. 설정 등록은 capability 루트에 둔다. 출하하는 `@ConfigurationPropertiesScan`에
`dev.caskeleton.adapter.inbound.websocket`을 다시 더하지 않는다.
3. STOMP·SockJS 채널은 이 leaf 자신의 `AutoConfiguration.imports`가 등록하고, leaf가 servlet classpath에
있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 `app.websocket.enabled=false`로
한다.
4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그
`SmartLifecycle` 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다.
5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다:
`./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification`.
## inbound 정책 (STOMP)
- HTTP upgrade에는 이미 비어 있지 않은 `Principal`이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다.
- STOMP `SUBSCRIBE`는 설정한 broadcast destination에만 허용한다.
- 인증된 `SEND`는 `/app/**` 아래에만 허용한다.
- 클라이언트가 `/topic/**`나 다른 destination으로 보내는 `SEND`는 거절한다.
- 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 `message` `WEBSOCKET_REQUEST_REJECTED`를 가진
ERROR frame이 된다. 그 `error-code` header는 cause chain에서 처음 나오는 `ApiErrorCarrier`가 실은
`ApiErrorCode`(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 그
밖에는 `WEBSOCKET_REQUEST_REJECTED`다.
## 이벤트 projection 계약
나중의 기능이 정확히 하나의 `@DomainEvent` 클래스에 대해 `LiveEventProjector<T>` bean을 기여할 수 있다.
broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이
실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는
`type`, 한계 있는 문자열 `fields`, `occurredAt`만 있다. broker 채널은 자기 한계 있는 executor를 가지므로,
simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면
이벤트를 버린다(best-effort, R1).
템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다.
## 증거와 한계
| lane | 증명하는 것 |
| --- | --- |
| `test` | STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료 |
| `systemTest` | 실제 Tomcat: STOMP 경계(`WebSocketBoundaryQualificationTest`), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄 |
| `websocketJettyTest` | Jetty에서 handler 런타임 계약 |
| `websocketNginxTest` | 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다) |
| `websocketTransportQualificationTest` | STOMP 경계 시험을 건너뛰지 않고 실행 |
simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달,
롤백에 안전한 발행, replay·resume은 주지 않는다.
@AGENTS.md
+1 -1
View File
@@ -1,6 +1,6 @@
# adapter-inbound-websocket
모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [CLAUDE.md](CLAUDE.md)가 SSOT다. 이 문서는 무엇을
모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [AGENTS.md](AGENTS.md)가 SSOT다. 이 문서는 무엇을
제공하는지, 어떻게 붙이는지, 왜 이런 모양인지를 적는다.
이 leaf는 두 가지를 제공한다. 서로 참조하지 않는다.
+180
View File
@@ -0,0 +1,180 @@
# adapter:outbound:cache-redis — cache와 Redis 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-cache-redis`
- Gradle 경로: `:adapter:outbound:cache-redis`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:cache-redis:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.cache`.
## 책임
- `application-core`의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다.
- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결,
capability별 실패 뜻을 가진다.
- semantic cache 포트(`CacheRegionPort`) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL
jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의
`CacheSourceRevisionOrder`다. Lua 사본은 `CacheRegionContract`(application-core testFixtures)가 그 순서에
맞추고, `RedisCacheRegionContractTest`와 `LiveRedisCacheRegionContractTest`가 그 계약을 상속한다.
- provider 중립 `EdgeRateLimitPort`를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로
구현한다.
- 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다.
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
- semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, `SemanticRedisCommands` 여덟 개, 조건부 Redis
runtime 조립은 `:adapter:outbound:redis-runtime`에 의존한다.
- 범용 typed SDK는 따로 둔 라이브러리 leaf `:adapter:outbound:redis-sdk`에 둔다(그 `README.md`를 본다). 이
leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다.
## Redis 런타임과 골라 쓰는 typed SDK (`…cache.redis.runtime`, `…cache.redis.sdk`)
등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의
`RedisRuntimePackageBoundaryTest`가 그 방향을 지킨다).
- `:adapter:outbound:redis-runtime`은 운영 기반이다: `RedisRuntimeSettings` 바인딩, credential 해석, topology
client, runtime 자신의 lane(`RedisConnectionKind.REGULAR`, `SCRIPT`)을 가진 `RedisRuntimeOwner`,
`SemanticRedisCommands`(이 leaf와 health contributor가 보내는 명령 여덟 개), health. `cache-redis`가 이 leaf에
의존한다.
- `:adapter:outbound:redis-sdk`는 골라 쓰는 범용 typed API를 가진다: `RedisCommandGateway`(`SemanticRedisCommands`를
상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고
자기 lane(`RedisSdkLane`: blocking, transaction, admin)과 admin 계정. 서비스가 그것을
`RedisLaneContribution`/`RedisAccountContribution` bean으로 runtime에 기여한다(`RedisSdkComposition`).
`cache-redis`는 운영에서도 시험에서도 그것에 의존하지 **않는다**.
- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 `SemanticRedisCommands`를 자기의 닫힌
semantic program(`RegisteredLuaScript`)으로 보낸다. `CommandPolicyGuard`를 지나지 않고,
`redis-command-policy.yml`이 그것을 다루지 않는다.
- 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 `RedisCorrectnessRoleSelectors`가 정하고,
`META-INF/spring.factories`에 runtime의 `RedisCorrectnessRequirement`로 등록한다.
`docs/design/2026-08-07-redis-wrapper-typed-api-design.md`가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의
일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은
`docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`에 있다.
- `sdk.api..`는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는
`sdk.api.reactive` 안에만 둔다.
- `sdk.lettuce..`가 계약을 구현한다. `sdk.config`는 속성, capability probe, 허가 정본을 가진다.
- `:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 골라 쓰는 typed SDK의 명령
정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책
파일이 아니다.
- `sdk.lettuce.operations`가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인
`RedisCommandGateway`를 거치고, 모든 호출은 돌기 전에 `CommandPolicyGuard`의 허가를 받는다. operation에서
driver를 직접 부르지 않는다.
- `sdk.cluster`는 client 쪽 slot 계산과 cluster 관찰을 가진다. `sdk.api`에만 의존하고 Lettuce를 import하지
않는다: slot을 명령을 만들기 전에 계산하므로 `CommandPolicyGuard`가 서버 redirect로 알게 되기 전에 cross-slot
요청을 거절할 수 있다.
- `sdk.programmability`는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지
않는다: catalog가 `EVAL`을 막고 `RedisScriptRegistry` digest의 `EVALSHA`만 닿을 수 있다. `FUNCTION LOAD`는
애플리케이션이 아니라 admin plane이다.
- 트랜잭션은 `WATCH`/`MULTI`/`EXEC`이고 **절대** 롤백하지 않는다. `TransactionResult`는 「실행됨」이나 「감시한
키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다.
줄 세운 명령은 `QueuedReply`를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 `+QUEUED`만 답했기
때문이다. 줄 세운 명령도 보통 명령과 같은 `CommandPolicyGuard` 허가를 지난다 — 트랜잭션은 guard를 피하는 길이
아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. `MULTI` 상태로 버려진 연결은 다음 호출자의
명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니,
트랜잭션이 기대는 읽기는 그 앞에서 `WATCH` 아래에 둔다.
- `sdk.raw`는 승인된 raw 명령 gateway다. catalog가 `RAW_ONLY`로 표시했고 *그리고* 배포가 그 명령에
`ApprovedRawCommand`를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다.
명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다.
- `sdk.admin`은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 `ADMIN_ONLY`이자
읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지
않게 응답을 걸러 낸다.
- `sdk.extensions.*`는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은
`ifSupported(...)`로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두
`ExtensionCommandRunner`로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가
아니라서 그 이름은 `LettuceRedisSearchOperations`가 직접 namespace를 붙인다.
- `RedisSdkModuleBoundaryTest`(`redis-sdk` 안)가 `redis-sdk` 소스 루트를 scan해 내부 패키지 그래프, driver 가두기,
아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다.
- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 `entries`, `members`, `rangeAll`, `keys` 없음. 선택 사항인
R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음.
metric이나 trace tag에 실제 키 없음.
## 경계
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
- inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다.
- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다.
- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다.
- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다.
- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다.
- rate-limit 조립은 `app.cache.redis`, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은
조율 role이고 실패하면 닫히는 것뿐이다.
- standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애
증거는 R2를 위해 따로 필요하다.
## 테스트
이 모듈만 보는 시험은 semantic 어댑터를 `testFixtures(project(':adapter:outbound:redis-runtime'))`의
`InMemorySemanticRedisCommands`에 대고 돌린다. `SemanticRedisCommands`의 유일한 fake이고, `StubRedisRuntimeClient`를
거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다.
실제 서버 lane이 둘 있다. `redisContainerContractTest`(integration category, `integrationCheck`에만 있다 — 이 leaf의
`mainCheck`에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 —
`config/testing/container-images.properties`의 `redis` image이고 `compose/redis/acl/lane-fixture-accounts.acl`을
읽어 들인다 — 그리고 `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest`,
`LiveRedisIdempotencyStoreContractTest`(메모리 fake도 통과하는 `application-core` 포트 계약),
`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`를 돌린다. 건너뛰기가 있으면 실패한다
(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의
낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. `RedisTestContainer`는 그 lane이
ACL 파일을 이름으로 댈 때만 서버를 띄운다.
`redisTopologyTest`는 외부 topology lane이고 `ca.redis-topology-lane`으로 선언한다. 이 leaf는 `standalone`과
`cluster`(`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`)를 선언한다. `redis-runtime`과
`redis-sdk`는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 `standalone`,
`sentinel`, `cluster`, `tls` 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(`sentinel`은
`redis.topology.master`가, `tls`는 `redis.topology.trust-material`이 더 필요하다), 시험을 하나도 찾지 못하거나
돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 `redisTopologyLane`에 적은 클래스가
실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. `tls`는 배포 모드가 아니라
lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다.
예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 `@Tag("redis-topology")`를 찾는 scan은
`failOnNoDiscoveredTests`가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로
관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가
줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다.
## 조립
`RedisRuntimeAutoConfiguration`은 이제 `:adapter:outbound:redis-runtime`의 것이다. Redis 설정과 공용 runtime 기반이
생기는 유일한 곳이고, `app.redis.enabled`(env `APP_REDIS_ENABLED`, 기본 `true` — 모듈이 있으면 켜진다)가 true인
동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 `RedisCapabilityConfig`(자기
`AutoConfiguration.imports`)가 그 runtime 위에 semantic 포트를 조립한다.
골라 쓰는 `:adapter:outbound:redis-sdk`는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그
`RedisStartupProbe`는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 `APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED`
스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야
한다.
모든 capability는 `CapabilityKeyspace`를 거쳐 `app.redis.namespace`의 namespace 하나 —
`{environment}:{service}:{domain}` — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이
각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다.
lane은 서로 다른 계정으로 인증한다. `RedisLane.account()`가 lane의 `RedisAccount`를 이름으로 대고, topology factory는
*설정한* 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다.
`SCRIPT` lane이 그것이 있는 이유다: `SCRIPT LOAD`와 `EVALSHA`는 advanced 계정의 것이라서, cache 항목을 읽는 계정은
script를 실행할 수 없다.
cache의 조건부 쓰기는 같은 계정이지만 자기 lane `CacheScriptLane.CACHE_SCRIPT`에서 돈다
(`app.capabilities.cache.maximum-script-connections`, `RedisCacheConfig`가 `RedisLaneContribution`으로 기여한다).
`SCRIPT`로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면
안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 `redis-runtime`의 meter(`RedisLaneMetrics`, `redis.lane.*`,
tag `lane`)이다. 그래서 cache가 `SCRIPT`를 쓰지 않는지는 짐작이 아니라 조회로 안다. `DEGRADED` health 순서는
`redis-runtime`과 함께 나가고, 그 leaf가 상태를 알린다(`config/module-defaults/redis-runtime.yml`).
Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 `RedisTransactionRunner`는 감시한 키(또는 명시한
`RedisSlotTag`)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 `RedisSdkLane.TRANSACTION`을
빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다.
설정 바인딩은 capability 기준 4(접두어 하나, `StrictSettingsBinder`)의 기록된 예외다(2026-11-03에 정함):
`app.redis.*`는 `redis-runtime`이 setter와 `validate()`로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서
`StrictSettingsBinder`(support)에 닿을 수 없기 때문이다. `app.capabilities.*`(cache, lease, rate-limit provider)는 이
leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. `app.rate-limit.*`은 이 leaf가 읽기만 하는 HTTP
경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은
그중 하나에 넣고, 네 번째 트리를 만들지 않는다.
`RedisRuntimeSettings`에는 클래스 수준 `@ConfigurationProperties`를 달면 안 된다: `RedisRuntimeAutoConfiguration`이
그것을 바인딩하므로 `APP_REDIS_ENABLED=false`이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는
properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 `@ConfigurationPropertiesScan`은
`dev.caskeleton.bootstrap.*` 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit
provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이
모듈은 bean을 하나도 기여하지 않는다.
+1 -180
View File
@@ -1,180 +1 @@
# adapter:outbound:cache-redis — cache와 Redis 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-cache-redis`
- Gradle 경로: `:adapter:outbound:cache-redis`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:cache-redis:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.cache`.
## 책임
- `application-core`의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다.
- 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결,
capability별 실패 뜻을 가진다.
- semantic cache 포트(`CacheRegionPort`) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL
jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의
`CacheSourceRevisionOrder`다. Lua 사본은 `CacheRegionContract`(application-core testFixtures)가 그 순서에
맞추고, `RedisCacheRegionContractTest`와 `LiveRedisCacheRegionContractTest`가 그 계약을 상속한다.
- provider 중립 `EdgeRateLimitPort`를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로
구현한다.
- 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다.
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
- semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, `SemanticRedisCommands` 여덟 개, 조건부 Redis
runtime 조립은 `:adapter:outbound:redis-runtime`에 의존한다.
- 범용 typed SDK는 따로 둔 라이브러리 leaf `:adapter:outbound:redis-sdk`에 둔다(그 `README.md`를 본다). 이
leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다.
## Redis 런타임과 골라 쓰는 typed SDK (`…cache.redis.runtime`, `…cache.redis.sdk`)
등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의
`RedisRuntimePackageBoundaryTest`가 그 방향을 지킨다).
- `:adapter:outbound:redis-runtime`은 운영 기반이다: `RedisRuntimeSettings` 바인딩, credential 해석, topology
client, runtime 자신의 lane(`RedisConnectionKind.REGULAR`, `SCRIPT`)을 가진 `RedisRuntimeOwner`,
`SemanticRedisCommands`(이 leaf와 health contributor가 보내는 명령 여덟 개), health. `cache-redis`가 이 leaf에
의존한다.
- `:adapter:outbound:redis-sdk`는 골라 쓰는 범용 typed API를 가진다: `RedisCommandGateway`(`SemanticRedisCommands`를
상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고
자기 lane(`RedisSdkLane`: blocking, transaction, admin)과 admin 계정. 서비스가 그것을
`RedisLaneContribution`/`RedisAccountContribution` bean으로 runtime에 기여한다(`RedisSdkComposition`).
`cache-redis`는 운영에서도 시험에서도 그것에 의존하지 **않는다**.
- 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 `SemanticRedisCommands`를 자기의 닫힌
semantic program(`RegisteredLuaScript`)으로 보낸다. `CommandPolicyGuard`를 지나지 않고,
`redis-command-policy.yml`이 그것을 다루지 않는다.
- 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 `RedisCorrectnessRoleSelectors`가 정하고,
`META-INF/spring.factories`에 runtime의 `RedisCorrectnessRequirement`로 등록한다.
`docs/design/2026-08-07-redis-wrapper-typed-api-design.md`가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의
일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은
`docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md`에 있다.
- `sdk.api..`는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는
`sdk.api.reactive` 안에만 둔다.
- `sdk.lettuce..`가 계약을 구현한다. `sdk.config`는 속성, capability probe, 허가 정본을 가진다.
- `:adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml`이 골라 쓰는 typed SDK의 명령
정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책
파일이 아니다.
- `sdk.lettuce.operations`가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인
`RedisCommandGateway`를 거치고, 모든 호출은 돌기 전에 `CommandPolicyGuard`의 허가를 받는다. operation에서
driver를 직접 부르지 않는다.
- `sdk.cluster`는 client 쪽 slot 계산과 cluster 관찰을 가진다. `sdk.api`에만 의존하고 Lettuce를 import하지
않는다: slot을 명령을 만들기 전에 계산하므로 `CommandPolicyGuard`가 서버 redirect로 알게 되기 전에 cross-slot
요청을 거절할 수 있다.
- `sdk.programmability`는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지
않는다: catalog가 `EVAL`을 막고 `RedisScriptRegistry` digest의 `EVALSHA`만 닿을 수 있다. `FUNCTION LOAD`는
애플리케이션이 아니라 admin plane이다.
- 트랜잭션은 `WATCH`/`MULTI`/`EXEC`이고 **절대** 롤백하지 않는다. `TransactionResult`는 「실행됨」이나 「감시한
키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다.
줄 세운 명령은 `QueuedReply`를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 `+QUEUED`만 답했기
때문이다. 줄 세운 명령도 보통 명령과 같은 `CommandPolicyGuard` 허가를 지난다 — 트랜잭션은 guard를 피하는 길이
아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. `MULTI` 상태로 버려진 연결은 다음 호출자의
명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니,
트랜잭션이 기대는 읽기는 그 앞에서 `WATCH` 아래에 둔다.
- `sdk.raw`는 승인된 raw 명령 gateway다. catalog가 `RAW_ONLY`로 표시했고 *그리고* 배포가 그 명령에
`ApprovedRawCommand`를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다.
명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다.
- `sdk.admin`은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 `ADMIN_ONLY`이자
읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지
않게 응답을 걸러 낸다.
- `sdk.extensions.*`는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은
`ifSupported(...)`로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두
`ExtensionCommandRunner`로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가
아니라서 그 이름은 `LettuceRedisSearchOperations`가 직접 namespace를 붙인다.
- `RedisSdkModuleBoundaryTest`(`redis-sdk` 안)가 `redis-sdk` 소스 루트를 scan해 내부 패키지 그래프, driver 가두기,
아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다.
- 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 `entries`, `members`, `rangeAll`, `keys` 없음. 선택 사항인
R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음.
metric이나 trace tag에 실제 키 없음.
## 경계
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
- inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다.
- cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다.
- Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다.
- application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다.
- cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다.
- rate-limit 조립은 `app.cache.redis`, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은
조율 role이고 실패하면 닫히는 것뿐이다.
- standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애
증거는 R2를 위해 따로 필요하다.
## 테스트
이 모듈만 보는 시험은 semantic 어댑터를 `testFixtures(project(':adapter:outbound:redis-runtime'))`의
`InMemorySemanticRedisCommands`에 대고 돌린다. `SemanticRedisCommands`의 유일한 fake이고, `StubRedisRuntimeClient`를
거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다.
실제 서버 lane이 둘 있다. `redisContainerContractTest`(integration category, `integrationCheck`에만 있다 — 이 leaf의
`mainCheck`에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 —
`config/testing/container-images.properties`의 `redis` image이고 `compose/redis/acl/lane-fixture-accounts.acl`을
읽어 들인다 — 그리고 `LiveRedisCacheRegionContractTest`, `LiveRedisDistributedLeaseContractTest`,
`LiveRedisIdempotencyStoreContractTest`(메모리 fake도 통과하는 `application-core` 포트 계약),
`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`를 돌린다. 건너뛰기가 있으면 실패한다
(2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의
낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. `RedisTestContainer`는 그 lane이
ACL 파일을 이름으로 댈 때만 서버를 띄운다.
`redisTopologyTest`는 외부 topology lane이고 `ca.redis-topology-lane`으로 선언한다. 이 leaf는 `standalone`과
`cluster`(`LiveRedisSemanticPortsTest`, `LiveRedisSemanticScriptAclProbeTest`)를 선언한다. `redis-runtime`과
`redis-sdk`는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 `standalone`,
`sentinel`, `cluster`, `tls` 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(`sentinel`은
`redis.topology.master`가, `tls`는 `redis.topology.trust-material`이 더 필요하다), 시험을 하나도 찾지 못하거나
돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 `redisTopologyLane`에 적은 클래스가
실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. `tls`는 배포 모드가 아니라
lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다.
예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 `@Tag("redis-topology")`를 찾는 scan은
`failOnNoDiscoveredTests`가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로
관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가
줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다.
## 조립
`RedisRuntimeAutoConfiguration`은 이제 `:adapter:outbound:redis-runtime`의 것이다. Redis 설정과 공용 runtime 기반이
생기는 유일한 곳이고, `app.redis.enabled`(env `APP_REDIS_ENABLED`, 기본 `true` — 모듈이 있으면 켜진다)가 true인
동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 `RedisCapabilityConfig`(자기
`AutoConfiguration.imports`)가 그 runtime 위에 semantic 포트를 조립한다.
골라 쓰는 `:adapter:outbound:redis-sdk`는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그
`RedisStartupProbe`는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 `APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED`
스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야
한다.
모든 capability는 `CapabilityKeyspace`를 거쳐 `app.redis.namespace`의 namespace 하나 —
`{environment}:{service}:{domain}` — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이
각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다.
lane은 서로 다른 계정으로 인증한다. `RedisLane.account()`가 lane의 `RedisAccount`를 이름으로 대고, topology factory는
*설정한* 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다.
`SCRIPT` lane이 그것이 있는 이유다: `SCRIPT LOAD`와 `EVALSHA`는 advanced 계정의 것이라서, cache 항목을 읽는 계정은
script를 실행할 수 없다.
cache의 조건부 쓰기는 같은 계정이지만 자기 lane `CacheScriptLane.CACHE_SCRIPT`에서 돈다
(`app.capabilities.cache.maximum-script-connections`, `RedisCacheConfig`가 `RedisLaneContribution`으로 기여한다).
`SCRIPT`로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면
안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 `redis-runtime`의 meter(`RedisLaneMetrics`, `redis.lane.*`,
tag `lane`)이다. 그래서 cache가 `SCRIPT`를 쓰지 않는지는 짐작이 아니라 조회로 안다. `DEGRADED` health 순서는
`redis-runtime`과 함께 나가고, 그 leaf가 상태를 알린다(`config/module-defaults/redis-runtime.yml`).
Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 `RedisTransactionRunner`는 감시한 키(또는 명시한
`RedisSlotTag`)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 `RedisSdkLane.TRANSACTION`을
빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다.
설정 바인딩은 capability 기준 4(접두어 하나, `StrictSettingsBinder`)의 기록된 예외다(2026-11-03에 정함):
`app.redis.*`는 `redis-runtime`이 setter와 `validate()`로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서
`StrictSettingsBinder`(support)에 닿을 수 없기 때문이다. `app.capabilities.*`(cache, lease, rate-limit provider)는 이
leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. `app.rate-limit.*`은 이 leaf가 읽기만 하는 HTTP
경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은
그중 하나에 넣고, 네 번째 트리를 만들지 않는다.
`RedisRuntimeSettings`에는 클래스 수준 `@ConfigurationProperties`를 달면 안 된다: `RedisRuntimeAutoConfiguration`이
그것을 바인딩하므로 `APP_REDIS_ENABLED=false`이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는
properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 `@ConfigurationPropertiesScan`은
`dev.caskeleton.bootstrap.*` 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit
provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이
모듈은 bean을 하나도 기여하지 않는다.
@AGENTS.md
+41
View File
@@ -0,0 +1,41 @@
# adapter:outbound:fileserver — 모듈 규칙
## 등록 정보
- 모듈 ID: `adapter-outbound-fileserver`
- Gradle 경로: `:adapter:outbound:fileserver`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:fileserver:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.fileserver.platform`. HTTP 파일 서버 플랫폼의 driven
(outbound) 어댑터다: `application-fileserver` 포트(내용 저장, 검증, 식별자, 감사, metric)를 구현한다.
설계 근거는 [README.md](README.md)에 있다.
## 책임
- `application-fileserver` 포트 뒤의 로컬 파일 시스템 내용 저장, 검증, 식별자, 감사, metric.
- `app.fileserver-platform.*`(기본 꺼짐)으로만 켠다. 이 leaf의 `AutoConfiguration.imports`에 등록한
`platform.autoconfigure.FileserverCapabilityAutoConfiguration`에서 켜진다.
- 자세한 전송·보안·운영 계약은 `docs/fileserver/` 아래에 있다. 인증된 동작은
`docs/fileserver/support-matrix.md`가 적는다.
## 허용
- 프로젝트 의존: 정본은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이고
`src/build.gradle`이 강제한다. `:domain-core`는 없다.
- 외부 런타임: JDK 파일 시스템, `spring-boot-autoconfigure`, `micrometer-core`, `slf4j-api`.
## 금지
- inbound 어댑터, 영속, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음).
- 파일 시스템·stream·프레임워크·provider 타입을 application 포트 너머로 새게 하기.
- `docs/fileserver/support-matrix.md`가 적지 않은 플랫폼 기능을 구현됐다고 내세우기.
- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상.
## 테스트
```bash
cd src
./gradlew :adapter:outbound:fileserver:check
```
+1 -41
View File
@@ -1,41 +1 @@
# adapter:outbound:fileserver — 모듈 규칙
## 등록 정보
- 모듈 ID: `adapter-outbound-fileserver`
- Gradle 경로: `:adapter:outbound:fileserver`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:fileserver:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.fileserver.platform`. HTTP 파일 서버 플랫폼의 driven
(outbound) 어댑터다: `application-fileserver` 포트(내용 저장, 검증, 식별자, 감사, metric)를 구현한다.
설계 근거는 [README.md](README.md)에 있다.
## 책임
- `application-fileserver` 포트 뒤의 로컬 파일 시스템 내용 저장, 검증, 식별자, 감사, metric.
- `app.fileserver-platform.*`(기본 꺼짐)으로만 켠다. 이 leaf의 `AutoConfiguration.imports`에 등록한
`platform.autoconfigure.FileserverCapabilityAutoConfiguration`에서 켜진다.
- 자세한 전송·보안·운영 계약은 `docs/fileserver/` 아래에 있다. 인증된 동작은
`docs/fileserver/support-matrix.md`가 적는다.
## 허용
- 프로젝트 의존: 정본은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이고
`src/build.gradle`이 강제한다. `:domain-core`는 없다.
- 외부 런타임: JDK 파일 시스템, `spring-boot-autoconfigure`, `micrometer-core`, `slf4j-api`.
## 금지
- inbound 어댑터, 영속, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음).
- 파일 시스템·stream·프레임워크·provider 타입을 application 포트 너머로 새게 하기.
- `docs/fileserver/support-matrix.md`가 적지 않은 플랫폼 기능을 구현됐다고 내세우기.
- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상.
## 테스트
```bash
cd src
./gradlew :adapter:outbound:fileserver:check
```
@AGENTS.md
+1 -1
View File
@@ -5,7 +5,7 @@ HTTP 파일 서버 플랫폼의 outbound(driven) 어댑터다. 패키지 루트:
시스템 내용 저장, 업로드 검증, 식별자, 감사, metric.
허용·금지 운영 의존 정책은 `src/config/architecture/modules.json`의 `adapter-outbound-fileserver` 항목이
가진다. 루트 Gradle 검증이 그 registry를 읽는다. 모듈 규칙은 [CLAUDE.md](CLAUDE.md)에 있다.
가진다. 루트 Gradle 검증이 그 registry를 읽는다. 모듈 규칙은 [AGENTS.md](AGENTS.md)에 있다.
전송·보안·설정·운영 계약은 `docs/fileserver/`에 있다. 이 파일 서버 플랫폼과 Object Storage 중 무엇을
고를지에 대한 저장소 단위 선택은
+86
View File
@@ -0,0 +1,86 @@
# adapter:outbound:httpclient — HTTP client 플랫폼
## 등록 정보
- 모듈 ID: `adapter-outbound-httpclient`
- Gradle 경로: `:adapter:outbound:httpclient`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:httpclient:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.httpclient`.
## 설계 정본
구현은 `docs/design/2026-08-08-httpclient-platform-design.md`를 따른다. 설계는 Gradle 모듈 19개를 따로 두는
것을 전제한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 여기서 **패키지**다.
그 대응과 그 밖에 일부러 바꾼 것은 모두 `docs/httpclient/repository-adaptation.md`에 적혀 있다. 타입을 다른
패키지로 옮기기 전에 그것을 읽는다.
## 책임
- 공개 호출 surface를 가진다: H1 typed service client(기본), H2 generic exchange, H3 dynamic target. H4 native
engine 접근은 `apache`, `jdk`, `http3` 안에 머문다.
- blocking만: 호출은 `RestClient`를 거쳐 호출자의 (virtual) 스레드에서 돈다. reactive stack(`WebClient`,
Reactor Netty)은 2026-09-25 소유자 결정으로 지웠다. 다시 들이지 않는다.
- Named Client Profile, runtime generation, transport SPI, deadline, 증거 기반 재시도, resilience, 인증, TLS,
SSRF 방어, streaming lifecycle, 관측을 가진다.
- 외부 HTTP 호출을 application·domain 포트 뒤에 맞춘다.
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
## 패키지 경계
`HttpClientModuleBoundaryTest`와 `PublicApiArchitectureTest`가 설계의 모듈 표를 강제한다:
- `api`는 플랫폼 안의 다른 어떤 것에도, Spring·Apache·Jetty·Resilience4j 타입에도 의존하지 않는다.
- `profile`은 공개적으로 `api`에만 의존한다.
- transport 패키지는 gateway로 거슬러 닿지 않는다.
- `resilience`는 transport에 의존하지 않는다 — 재시도 자격은 transport와 무관하다.
- 운영 패키지는 다시 쓰는 testkit에 의존하지 않는다. testkit은 Gradle `testFixtures`
(`src/testFixtures/java`)에 있고, 보통 시험, integration·performance lane, JMH가 명시적으로 쓴다. 그 의존은
test-fixture·test 설정에 머물러서 운영 코드는 여전히 닿지 못한다. 경계 규칙이 import하는 「운영 클래스」의
유일한 정의는 `PlatformClasses`다.
- Stable 코드는 `http3`를 참조하지 않는다.
- 어떤 클래스도 `org.springframework.web.service.registry`나 `RestTemplate`를 쓰지 않는다.
## 경계
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
- inbound controller·DTO, 영속, bootstrap, 샘플 의존이 없다.
- 재시도와 circuit breaker 코드는 기술적 resilience다. 업무 보상과 유스케이스 순서는 application·domain 계층에
남는다.
- application·domain 코드는 이 모듈의 gateway, operation descriptor, URI 타입, Spring HTTP 타입, engine client,
재시도 타입, wire DTO를 import하면 안 된다. 그 방향은 `config/architecture/modules.json`의 저장소 단위 Gradle
의존 게이트가 강제한다. 이 leaf의 ArchUnit 규칙은 leaf 안의 경계만 다룬다.
- 보통 호출은 등록된 profile과 profile 기준 template을 쓴다. 절대 URL은 H3만 쓴다.
- 조립은 `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` 아래에서 capability가 가진다: profile 바인딩,
기동 검증, transport 등록, service gateway, dynamic target, actuator endpoint가 이 leaf에 있고 Boot 자동 구성
metadata로 나간다. `HttpClientPlatformAutoConfiguration`은 `app.httpclient.enabled=true`일 때만 켜진다.
스위치가 꺼져 있으면 capability에는 bean이 하나도 없다 — 빈 registry가 아니라 아무것도 없다.
- `app-bootstrap`은 운영 코드에서 HTTP client 구현이나 자동 구성 클래스를 import하면 안 된다. 빌드에 넣을지는
이 런타임 켜기 스위치와 따로 정한다.
## 테스트
기본 lane: `./gradlew :adapter:outbound:httpclient:test`. 추가 lane은 모두 실패하면 닫힌다:
| lane | 용도 |
|---|---|
| `httpClientStableContractTest` | Apache와 JDK에 걸친 semantic 계약 하나 |
| `httpClientSecurityTest` | SSRF 표, credential 걷어내기, tag cardinality |
| `httpClientFailureInjectionTest` | Toxiproxy 장애. **Docker가 필요하고 없으면 실패한다** |
| `httpClientPerformanceTest` | pool, streaming, 재시도, 교체의 자원 한계 |
| `spring62ApiSurfaceScan` | Spring 6.2 API surface 가두기 |
| `spring70CompatibilityTest` | 저장소 기준 버전 위의 계약 suite |
| `jmh` | 호출당 부담 benchmark |
고른 lane은 소리 없이 건너뛰지 않는다: 장애 lane은 Docker가 없으면 던지고, 계약 lane은 transport 선택이
비었거나 모르는 것이면 던지고, performance lane은 실행마다 모든 한계를 단언한다 — 빌드가
`performance.assertions.enabled`에 `true` 아닌 값을 넣거나 그 시험 하나가 건너뛰어지면 strict lane 규약이
실패시킨다.
transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계약 하나
`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고
(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본
fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의
변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6).
+1 -86
View File
@@ -1,86 +1 @@
# adapter:outbound:httpclient — HTTP client 플랫폼
## 등록 정보
- 모듈 ID: `adapter-outbound-httpclient`
- Gradle 경로: `:adapter:outbound:httpclient`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:httpclient:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.httpclient`.
## 설계 정본
구현은 `docs/design/2026-08-08-httpclient-platform-design.md`를 따른다. 설계는 Gradle 모듈 19개를 따로 두는
것을 전제한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 여기서 **패키지**다.
그 대응과 그 밖에 일부러 바꾼 것은 모두 `docs/httpclient/repository-adaptation.md`에 적혀 있다. 타입을 다른
패키지로 옮기기 전에 그것을 읽는다.
## 책임
- 공개 호출 surface를 가진다: H1 typed service client(기본), H2 generic exchange, H3 dynamic target. H4 native
engine 접근은 `apache`, `jdk`, `http3` 안에 머문다.
- blocking만: 호출은 `RestClient`를 거쳐 호출자의 (virtual) 스레드에서 돈다. reactive stack(`WebClient`,
Reactor Netty)은 2026-09-25 소유자 결정으로 지웠다. 다시 들이지 않는다.
- Named Client Profile, runtime generation, transport SPI, deadline, 증거 기반 재시도, resilience, 인증, TLS,
SSRF 방어, streaming lifecycle, 관측을 가진다.
- 외부 HTTP 호출을 application·domain 포트 뒤에 맞춘다.
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
## 패키지 경계
`HttpClientModuleBoundaryTest`와 `PublicApiArchitectureTest`가 설계의 모듈 표를 강제한다:
- `api`는 플랫폼 안의 다른 어떤 것에도, Spring·Apache·Jetty·Resilience4j 타입에도 의존하지 않는다.
- `profile`은 공개적으로 `api`에만 의존한다.
- transport 패키지는 gateway로 거슬러 닿지 않는다.
- `resilience`는 transport에 의존하지 않는다 — 재시도 자격은 transport와 무관하다.
- 운영 패키지는 다시 쓰는 testkit에 의존하지 않는다. testkit은 Gradle `testFixtures`
(`src/testFixtures/java`)에 있고, 보통 시험, integration·performance lane, JMH가 명시적으로 쓴다. 그 의존은
test-fixture·test 설정에 머물러서 운영 코드는 여전히 닿지 못한다. 경계 규칙이 import하는 「운영 클래스」의
유일한 정의는 `PlatformClasses`다.
- Stable 코드는 `http3`를 참조하지 않는다.
- 어떤 클래스도 `org.springframework.web.service.registry`나 `RestTemplate`를 쓰지 않는다.
## 경계
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
- inbound controller·DTO, 영속, bootstrap, 샘플 의존이 없다.
- 재시도와 circuit breaker 코드는 기술적 resilience다. 업무 보상과 유스케이스 순서는 application·domain 계층에
남는다.
- application·domain 코드는 이 모듈의 gateway, operation descriptor, URI 타입, Spring HTTP 타입, engine client,
재시도 타입, wire DTO를 import하면 안 된다. 그 방향은 `config/architecture/modules.json`의 저장소 단위 Gradle
의존 게이트가 강제한다. 이 leaf의 ArchUnit 규칙은 leaf 안의 경계만 다룬다.
- 보통 호출은 등록된 profile과 profile 기준 template을 쓴다. 절대 URL은 H3만 쓴다.
- 조립은 `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` 아래에서 capability가 가진다: profile 바인딩,
기동 검증, transport 등록, service gateway, dynamic target, actuator endpoint가 이 leaf에 있고 Boot 자동 구성
metadata로 나간다. `HttpClientPlatformAutoConfiguration`은 `app.httpclient.enabled=true`일 때만 켜진다.
스위치가 꺼져 있으면 capability에는 bean이 하나도 없다 — 빈 registry가 아니라 아무것도 없다.
- `app-bootstrap`은 운영 코드에서 HTTP client 구현이나 자동 구성 클래스를 import하면 안 된다. 빌드에 넣을지는
이 런타임 켜기 스위치와 따로 정한다.
## 테스트
기본 lane: `./gradlew :adapter:outbound:httpclient:test`. 추가 lane은 모두 실패하면 닫힌다:
| lane | 용도 |
|---|---|
| `httpClientStableContractTest` | Apache와 JDK에 걸친 semantic 계약 하나 |
| `httpClientSecurityTest` | SSRF 표, credential 걷어내기, tag cardinality |
| `httpClientFailureInjectionTest` | Toxiproxy 장애. **Docker가 필요하고 없으면 실패한다** |
| `httpClientPerformanceTest` | pool, streaming, 재시도, 교체의 자원 한계 |
| `spring62ApiSurfaceScan` | Spring 6.2 API surface 가두기 |
| `spring70CompatibilityTest` | 저장소 기준 버전 위의 계약 suite |
| `jmh` | 호출당 부담 benchmark |
고른 lane은 소리 없이 건너뛰지 않는다: 장애 lane은 Docker가 없으면 던지고, 계약 lane은 transport 선택이
비었거나 모르는 것이면 던지고, performance lane은 실행마다 모든 한계를 단언한다 — 빌드가
`performance.assertions.enabled`에 `true` 아닌 값을 넣거나 그 시험 하나가 건너뛰어지면 strict lane 규약이
실패시킨다.
transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계약 하나
`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고
(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본
fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의
변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6).
@AGENTS.md
+53
View File
@@ -0,0 +1,53 @@
# adapter:outbound:identifier — IO 없는 기반 capability 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-identifier`
- Gradle 경로: `:adapter:outbound:identifier`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:identifier:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.identifier`.
예전에 코드 주석에 두던 설계 결정(알고리즘 정본, salt 출처, 빌드 선택)은 [README.md](README.md)에 있다.
## 책임
- `HmacUserPrincipalPseudonymizer` — `UserPrincipalPseudonymizerPort` 구현(UTF-8 principal의 HMAC-SHA-256,
소문자 hex).
- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` 구현(`uuid-creator`로 만든 UUIDv7).
operation id는 제출 이벤트의 id이기도 하고, 메시징 플랫폼의 message id는 UUIDv7만 받는다.
`composition:durable-operation`이 배선한다.
- leaf 이름은 「identifier」다. 범용 시계·난수 출처는 여기 없다. Gradle 경로와 쓰는 쪽이 이 이름을 쓰니
이름을 그대로 둔다(README).
- 배선은 이 leaf가 아니라 `composition/service-runtime`(`PseudonymizationConfig`)이다.
## 허용
[build.gradle](build.gradle)에 선언한다. registry 항목이 정본이다.
- `:application-core` — 두 클래스가 구현하는 포트.
- `:shared-contract`, `HmacSha256`만. 가명은 principal의 hex HMAC이다.
`HmacUserPrincipalPseudonymizerVectorTest`가 그것을 JVM 밖에서 계산한 벡터에 고정한다. 릴리스 전후에 쓴
로그를 이 값으로 잇기 때문이다.
- `:domain-core` — 기능의 서버 지정 id 어댑터가 여기서 그 도메인 `*IdFactory` 포트를 구현한다(registry
edge `adapter:outbound:identifier -> domain-core`, `docs/manual/02-new-feature.md`).
- `com.github.f4b6a3:uuid-creator`(`libs.uuid.creator`) — `UuidV7DurableOperationIdFactory`의 UUIDv7.
## 금지
- 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit
`IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다.
- inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`.
- 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다.
## 테스트
Spring context 없는 순수 단위 시험: `HmacUserPrincipalPseudonymizerTest`(RFC 4231 known-answer 벡터 포함),
`HmacUserPrincipalPseudonymizerVectorTest`, `UuidV7DurableOperationIdFactoryTest`.
```bash
cd src
./gradlew :adapter:outbound:identifier:test --console=plain
```
+1 -53
View File
@@ -1,53 +1 @@
# adapter:outbound:identifier — IO 없는 기반 capability 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-identifier`
- Gradle 경로: `:adapter:outbound:identifier`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:identifier:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.identifier`.
예전에 코드 주석에 두던 설계 결정(알고리즘 정본, salt 출처, 빌드 선택)은 [README.md](README.md)에 있다.
## 책임
- `HmacUserPrincipalPseudonymizer` — `UserPrincipalPseudonymizerPort` 구현(UTF-8 principal의 HMAC-SHA-256,
소문자 hex).
- `UuidV7DurableOperationIdFactory` — `DurableOperationIdFactory` 구현(`uuid-creator`로 만든 UUIDv7).
operation id는 제출 이벤트의 id이기도 하고, 메시징 플랫폼의 message id는 UUIDv7만 받는다.
`composition:durable-operation`이 배선한다.
- leaf 이름은 「identifier」다. 범용 시계·난수 출처는 여기 없다. Gradle 경로와 쓰는 쪽이 이 이름을 쓰니
이름을 그대로 둔다(README).
- 배선은 이 leaf가 아니라 `composition/service-runtime`(`PseudonymizationConfig`)이다.
## 허용
[build.gradle](build.gradle)에 선언한다. registry 항목이 정본이다.
- `:application-core` — 두 클래스가 구현하는 포트.
- `:shared-contract`, `HmacSha256`만. 가명은 principal의 hex HMAC이다.
`HmacUserPrincipalPseudonymizerVectorTest`가 그것을 JVM 밖에서 계산한 벡터에 고정한다. 릴리스 전후에 쓴
로그를 이 값으로 잇기 때문이다.
- `:domain-core` — 기능의 서버 지정 id 어댑터가 여기서 그 도메인 `*IdFactory` 포트를 구현한다(registry
edge `adapter:outbound:identifier -> domain-core`, `docs/manual/02-new-feature.md`).
- `com.github.f4b6a3:uuid-creator`(`libs.uuid.creator`) — `UuidV7DurableOperationIdFactory`의 UUIDv7.
## 금지
- 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit
`IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다.
- inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`.
- 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다.
## 테스트
Spring context 없는 순수 단위 시험: `HmacUserPrincipalPseudonymizerTest`(RFC 4231 known-answer 벡터 포함),
`HmacUserPrincipalPseudonymizerVectorTest`, `UuidV7DurableOperationIdFactoryTest`.
```bash
cd src
./gradlew :adapter:outbound:identifier:test --console=plain
```
@AGENTS.md
+2 -2
View File
@@ -3,7 +3,7 @@
이 leaf의 main 코드는 `HmacUserPrincipalPseudonymizer`와 `UuidV7DurableOperationIdFactory` 두 클래스다. 패키지 루트:
`dev.caskeleton.adapter.outbound.identifier`.
허용·금지 의존과 테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md)가 기준이다. 이 문서는
허용·금지 의존과 테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md)가 기준이다. 이 문서는
설계 결정의 근거를 모은다.
## 이름과 내용이 다른 이유 (review 05-21)
@@ -49,7 +49,7 @@ Spring 어노테이션이 없다. bean은
의존은 넷이다: `:application-core`(두 클래스가 구현하는 port), `:shared-contract`(`HmacSha256`),
`:domain-core`(기능의 `*IdFactory` 구현 자리), `uuid-creator`(UUIDv7). 목록과 이유는
[CLAUDE.md](CLAUDE.md) Allowed 절이 기준이다.
[AGENTS.md](AGENTS.md) Allowed 절이 기준이다.
`:application-core`를 `implementation`으로 받는다. 이 leaf의 public 타입 시그니처에
application-core 타입이 드러나지만, 조립하는 쪽이 application-core를 이미 classpath에 갖고 있다.
@@ -0,0 +1,13 @@
# adapter:outbound:messaging-kafka
- 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`.
registry 정본: `src/config/architecture/modules.json`.
- 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다:
`adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온
플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다.
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온
제품(`src/platforms/messaging/AGENTS.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
registry 항목에서만 온다.
- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane
`messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`).
- 설계: `README.md`.
+1 -13
View File
@@ -1,13 +1 @@
# adapter:outbound:messaging-kafka
- 모듈 ID `adapter-outbound-messaging-kafka`, Gradle 경로 `:adapter:outbound:messaging-kafka`.
registry 정본: `src/config/architecture/modules.json`.
- 책임: Kafka 발행 capability를 `runtimeOnly` 한 줄로 만든다. 운영 코드가 없다:
`adapter:outbound:messaging`(애플리케이션의 bridge)과 `messaging:messaging-spring-boot-starter-kafka`(들여온
플랫폼과 그 Kafka 전송)를 묶고, 모듈 기본값 `config/module-defaults/messaging.yml`을 싣는다.
- 경계: 여기 코드를 더하지 않는다. 발행 규칙은 bridge(`adapter:outbound:messaging`)에, Kafka 규칙은 들여온
제품(`src/platforms/messaging/CLAUDE.md`)에 속한다. 여기 클래스를 두면 세 번째 자리가 생긴다. 허용 edge는
registry 항목에서만 온다.
- 시험: 켜기 시험(`./gradlew :adapter:outbound:messaging-kafka:test`)과 실제 Kafka lane
`messagingKafkaRelayIntegrationTest`(relay → bridge → broker record 바이트, `:integrationCheck`).
- 설계: `README.md`.
@AGENTS.md
+46
View File
@@ -0,0 +1,46 @@
# adapter:outbound:messaging — 메시징 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-messaging`
- Gradle 경로: `:adapter:outbound:messaging`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:messaging:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.messaging`.
## 책임
- application·domain 포트 뒤에서 outbound 메시지 발행과 broker 연동을 구현한다.
- broker 설정, 꺼짐·안전 실패 기술 모드, outbox 발행 연결을 가진다.
- 조건 없이 하나만 있는 `Slf4jOutboxRelayFailureReportAdapter` bean으로 `OutboxRelayFailureReport`를 구조화해
남긴다.
- 공용 기술 관심사는 `adapter:outbound:support`를 다시 쓴다.
## 경계
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
- inbound DTO·controller, 영속 repository·엔티티, bootstrap, 샘플 의존이 없다.
- 정해진 플랫폼 bridge는 `messaging-core-api`(`schema` 패키지도 담는다)에만 의존할 수 있다.
`platformbridge/` 아래에서 `messaging-runtime-core`, 전송 SPI 구현, broker SDK 타입을 import하지 않는다.
- 발행 경로는 하나다: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` → 플랫폼 bridge. 옛
`KafkaSender` / `MessageBroker` R0 이음매와 실패해도 열리는(fail-open) `MessagePublisher`는 정해진 outbox와
함께 지웠다(2026-09-28). 두 번째 경로를 다시 들이지 않는다.
- 정해진 producer identity는 명시한 `app.messaging.producer-id`다. `spring.application.name`, host, pod,
프로세스 identity에서 끌어내지 않는다. 모듈이 켜져 있는데 bridge가 없으면 기동을 거절한다 — relay가 발행할
길이 없다.
- 템플릿의 `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder`)는 여기가 아니라
`adapter:outbound:support`에 있다: 유스케이스는 append하기 전에 인코딩하는데, 이 모듈을 싣지 않는 조립도
있다. R1 contract·binding 컴파일러와 JSON Schema envelope 인코더는 2026-09-25에 지웠다
(`docs/capability-status.md`).
- 주 classpath에 JSON Schema 엔진(NetworkNT)이 없다. 증거 manifest schema 검사와 capability card 검사
(`release/`)는 이 leaf의 시험(`evidence/`)이다. snakeyaml은 시험에서만 쓴다(소유자 결정 2026-09-25).
- 유스케이스 순서나 업무 라우팅 정책을 broker 어댑터 안에 숨기지 않는다.
- `OutboxMessagePublishAdapter`는 위임만 하고 의존성 로그를 내지 않는다. 확정된 FAILED/DEAD 전이가 정해진
ERROR 하나를 가진다.
## 테스트
가짜 정해진 publisher로 단위·계약 시험을 쓴다. 이 모듈만 보는 시험은 실제 네트워크나 broker를 쓰지 않는다.
설정이 바뀌면 settings record에 바인딩·검증 시험을 더한다.
+1 -46
View File
@@ -1,46 +1 @@
# adapter:outbound:messaging — 메시징 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-messaging`
- Gradle 경로: `:adapter:outbound:messaging`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:messaging:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.messaging`.
## 책임
- application·domain 포트 뒤에서 outbound 메시지 발행과 broker 연동을 구현한다.
- broker 설정, 꺼짐·안전 실패 기술 모드, outbox 발행 연결을 가진다.
- 조건 없이 하나만 있는 `Slf4jOutboxRelayFailureReportAdapter` bean으로 `OutboxRelayFailureReport`를 구조화해
남긴다.
- 공용 기술 관심사는 `adapter:outbound:support`를 다시 쓴다.
## 경계
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
- inbound DTO·controller, 영속 repository·엔티티, bootstrap, 샘플 의존이 없다.
- 정해진 플랫폼 bridge는 `messaging-core-api`(`schema` 패키지도 담는다)에만 의존할 수 있다.
`platformbridge/` 아래에서 `messaging-runtime-core`, 전송 SPI 구현, broker SDK 타입을 import하지 않는다.
- 발행 경로는 하나다: `OutboxMessagePublishAdapter` → `IntegrationEventPublishPort` → 플랫폼 bridge. 옛
`KafkaSender` / `MessageBroker` R0 이음매와 실패해도 열리는(fail-open) `MessagePublisher`는 정해진 outbox와
함께 지웠다(2026-09-28). 두 번째 경로를 다시 들이지 않는다.
- 정해진 producer identity는 명시한 `app.messaging.producer-id`다. `spring.application.name`, host, pod,
프로세스 identity에서 끌어내지 않는다. 모듈이 켜져 있는데 bridge가 없으면 기동을 거절한다 — relay가 발행할
길이 없다.
- 템플릿의 `IntegrationEventEncoderPort`(`JsonIntegrationEventEncoder`)는 여기가 아니라
`adapter:outbound:support`에 있다: 유스케이스는 append하기 전에 인코딩하는데, 이 모듈을 싣지 않는 조립도
있다. R1 contract·binding 컴파일러와 JSON Schema envelope 인코더는 2026-09-25에 지웠다
(`docs/capability-status.md`).
- 주 classpath에 JSON Schema 엔진(NetworkNT)이 없다. 증거 manifest schema 검사와 capability card 검사
(`release/`)는 이 leaf의 시험(`evidence/`)이다. snakeyaml은 시험에서만 쓴다(소유자 결정 2026-09-25).
- 유스케이스 순서나 업무 라우팅 정책을 broker 어댑터 안에 숨기지 않는다.
- `OutboxMessagePublishAdapter`는 위임만 하고 의존성 로그를 내지 않는다. 확정된 FAILED/DEAD 전이가 정해진
ERROR 하나를 가진다.
## 테스트
가짜 정해진 publisher로 단위·계약 시험을 쓴다. 이 모듈만 보는 시험은 실제 네트워크나 broker를 쓰지 않는다.
설정이 바뀌면 settings record에 바인딩·검증 시험을 더한다.
@AGENTS.md
+1 -1
View File
@@ -5,7 +5,7 @@
adapter로 구조화한다.
허용/금지 의존 정책은 `src/config/architecture/modules.json`과 이 모듈의
[CLAUDE.md](CLAUDE.md)가 소유한다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔
[AGENTS.md](AGENTS.md)가 소유한다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔
참조용 기록이다.
## 모듈 개요
@@ -0,0 +1,49 @@
# adapter:outbound:notification — 알림 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-notification`
- Gradle 경로: `:adapter:outbound:notification`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:notification:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.notification`.
## 책임
- 지금의 raw 알림 router·provider 이음매는 리뷰를 거친 정해진 전환(cutover)이 지울 때까지 `R0 legacy` 호환
기준선으로만 지킨다.
- 앞으로의 provider 프로토콜은 애플리케이션이 가진 포트 뒤에서 구현하고, SDK·전송·bootstrap·영속 타입을
새게 하지 않는다.
- provider 설정, 기술적 대체 장치, provider 연결을 가진다. 모드, 자격, 재시도·대체 판단, 업무 실패의 뜻은
애플리케이션 정책이 가진다.
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
## 지금의 R0 동결
- `RoutingNotifier`가 `(Channel, providerId)` 위에서 route 목록으로 퍼뜨린다.
- `FailOpenNotificationProvider`가 전역 fail-open 규칙 하나를 적용한다.
- `google-email`/`GoogleEmailClient`와 `slack-webhook`/`SlackClient`는 fake로만 쓰는 확장 이음매다. 운영 연동이나
검증된 provider card가 아니다.
- 커밋해 둔 provider 선택 키는 router의 `routes` + provider `enabled` 문법과 어긋나 있다. 정해진 그래프가
대신할 때까지 그 어긋남을 지키고 적어 둔다. 옛 키를 소리 없이 다르게 해석하지 않는다.
- 기능·애플리케이션 운영 소비자가 없고, 실제 provider·durable·수신 확인·보안·부하·교체 증거가 없다.
- 지울 옛 코드의 정확한 목록은 [README.md](README.md)에 있다. 정해진 대체물을 만드는 동안 그 클래스에 동작을
더하지 않는다.
## 경계
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
- inbound DTO·controller, 영속, bootstrap, 샘플 의존이 없다.
- provider 선택은 설정한 채널로 보낼 수 있지만 업무 자격 규칙을 담으면 안 된다.
- 줄 안에 완전한 이름으로 쓴 타입 참조가 없다. `adapter:outbound:fileserver`는 이미 이것을 금지했고 이 leaf는
아니었다. 그래서 같은 구문이 한 capability에서는 결함이고 다음 capability에서는 평범한 문체였다. 플랫폼 자동
구성에 그런 것이 스물두 개 쌓여 있었다.
`dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort jobs`처럼 쓴 매개변수는
import 블록이 읽기 쉽게 보여 주려고 있는 바로 그 leaf 사이 edge를 import 블록에서 숨긴다.
## 테스트
provider·client fake와 계약 시험을 쓴다. 실제 webhook이나 email 네트워크 호출이 없다. 설정을 바꾸면
바인딩·검증 시험을 더한다.
+1 -49
View File
@@ -1,49 +1 @@
# adapter:outbound:notification — 알림 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-notification`
- Gradle 경로: `:adapter:outbound:notification`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:notification:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.notification`.
## 책임
- 지금의 raw 알림 router·provider 이음매는 리뷰를 거친 정해진 전환(cutover)이 지울 때까지 `R0 legacy` 호환
기준선으로만 지킨다.
- 앞으로의 provider 프로토콜은 애플리케이션이 가진 포트 뒤에서 구현하고, SDK·전송·bootstrap·영속 타입을
새게 하지 않는다.
- provider 설정, 기술적 대체 장치, provider 연결을 가진다. 모드, 자격, 재시도·대체 판단, 업무 실패의 뜻은
애플리케이션 정책이 가진다.
- 공용 outbound 관심사는 `adapter:outbound:support`를 다시 쓴다.
## 지금의 R0 동결
- `RoutingNotifier`가 `(Channel, providerId)` 위에서 route 목록으로 퍼뜨린다.
- `FailOpenNotificationProvider`가 전역 fail-open 규칙 하나를 적용한다.
- `google-email`/`GoogleEmailClient`와 `slack-webhook`/`SlackClient`는 fake로만 쓰는 확장 이음매다. 운영 연동이나
검증된 provider card가 아니다.
- 커밋해 둔 provider 선택 키는 router의 `routes` + provider `enabled` 문법과 어긋나 있다. 정해진 그래프가
대신할 때까지 그 어긋남을 지키고 적어 둔다. 옛 키를 소리 없이 다르게 해석하지 않는다.
- 기능·애플리케이션 운영 소비자가 없고, 실제 provider·durable·수신 확인·보안·부하·교체 증거가 없다.
- 지울 옛 코드의 정확한 목록은 [README.md](README.md)에 있다. 정해진 대체물을 만드는 동안 그 클래스에 동작을
더하지 않는다.
## 경계
- 허용 의존 edge는 이 모듈의 `src/config/architecture/modules.json` 항목에서만 온다.
- inbound DTO·controller, 영속, bootstrap, 샘플 의존이 없다.
- provider 선택은 설정한 채널로 보낼 수 있지만 업무 자격 규칙을 담으면 안 된다.
- 줄 안에 완전한 이름으로 쓴 타입 참조가 없다. `adapter:outbound:fileserver`는 이미 이것을 금지했고 이 leaf는
아니었다. 그래서 같은 구문이 한 capability에서는 결함이고 다음 capability에서는 평범한 문체였다. 플랫폼 자동
구성에 그런 것이 스물두 개 쌓여 있었다.
`dev.caskeleton.application.notification.platform.dispatch.ReconciliationJobStorePort jobs`처럼 쓴 매개변수는
import 블록이 읽기 쉽게 보여 주려고 있는 바로 그 leaf 사이 edge를 import 블록에서 숨긴다.
## 테스트
provider·client fake와 계약 시험을 쓴다. 실제 webhook이나 email 네트워크 호출이 없다. 설정을 바꾸면
바인딩·검증 시험을 더한다.
@AGENTS.md
@@ -0,0 +1,48 @@
# adapter:outbound:objectstorage — 모듈 규칙
## 등록 정보
- 모듈 ID: `adapter-outbound-objectstorage`
- Gradle 경로: `:adapter:outbound:objectstorage`
- 이 모듈만 시험: `./gradlew :adapter:outbound:objectstorage:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.objectstorage`. 설계 근거와 사실대로 적은 준비 상태는
[README.md](README.md)와 `docs/registries/object-storage-readiness.yaml`에 있다.
## 책임
- application-core의 semantic object 게시·읽기·폐기·operation 해석 포트를 provider 중립의 한계 있는 streaming과
엄격한 durable 제어 레코드 뒤에서 구현한다.
- 기본 꺼짐인 `app.object-storage` 설정을, 고른 자원을 만들기 전에 정확하고 바뀌지 않는
provider·destination·route·policy 바인딩으로 컴파일한다.
- R1 전용 개발 provider로 `filesystem-local-dev`를 준다.
- scanner 유지보수 조립은 따로 둔다. 지원하지 않는 capability는 bean을 기여하지 않는다. purge·direct-grant·
multipart 포트는 없다.
## 허용
- 프로젝트 의존은 `src/config/architecture/modules.json`의 `adapter-outbound-objectstorage` 항목이 허용한 것뿐이다.
지금은 application-core, shared-contract, application-objectstorage, 그리고 등록된 support edge
(`adapter:outbound:support`: 모든 local-dev 파일 접근이 거치는 descriptor 기반 `SecureFileAccess`/
`SecureDirectoryWalk`, 그리고 `StrictSettingsBinder` — `app.object-storage` 트리는 환경 변수까지 엄격하게
바인딩한다. capability 규칙 4)다.
- provider SDK·설정 타입은 이 leaf 안에 머문다.
- provider 기여는 부작용 없이 지원 내용을 설명할 수 있고, 정확히 골라진 뒤에만 자원을 만들 수 있다.
## 금지
- inbound 어댑터, 이웃 outbound 어댑터, 영속, app-bootstrap 의존.
- provider 키·경로·locator·SDK 타입·Spring 타입·제어 레코드 타입이 application-core로 새는 것.
- 기본 provider·destination·namespace, 운영에서 local-dev, capability가 꺼져 있을 때 기동 중 변경.
- 보통 라우팅 타입이 scanner 유지보수 포트를 구현하기.
- `docs/registries/object-storage-readiness.yaml`의 정확한 행보다 높은 주장.
- 새 semantic operation을 옛 호출자 키 기반 덮어쓰기 뜻으로 되돌려 맞추기.
## 테스트
```bash
cd src
./gradlew :adapter:outbound:objectstorage:check --console=plain
```
+1 -48
View File
@@ -1,48 +1 @@
# adapter:outbound:objectstorage — 모듈 규칙
## 등록 정보
- 모듈 ID: `adapter-outbound-objectstorage`
- Gradle 경로: `:adapter:outbound:objectstorage`
- 이 모듈만 시험: `./gradlew :adapter:outbound:objectstorage:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.objectstorage`. 설계 근거와 사실대로 적은 준비 상태는
[README.md](README.md)와 `docs/registries/object-storage-readiness.yaml`에 있다.
## 책임
- application-core의 semantic object 게시·읽기·폐기·operation 해석 포트를 provider 중립의 한계 있는 streaming과
엄격한 durable 제어 레코드 뒤에서 구현한다.
- 기본 꺼짐인 `app.object-storage` 설정을, 고른 자원을 만들기 전에 정확하고 바뀌지 않는
provider·destination·route·policy 바인딩으로 컴파일한다.
- R1 전용 개발 provider로 `filesystem-local-dev`를 준다.
- scanner 유지보수 조립은 따로 둔다. 지원하지 않는 capability는 bean을 기여하지 않는다. purge·direct-grant·
multipart 포트는 없다.
## 허용
- 프로젝트 의존은 `src/config/architecture/modules.json`의 `adapter-outbound-objectstorage` 항목이 허용한 것뿐이다.
지금은 application-core, shared-contract, application-objectstorage, 그리고 등록된 support edge
(`adapter:outbound:support`: 모든 local-dev 파일 접근이 거치는 descriptor 기반 `SecureFileAccess`/
`SecureDirectoryWalk`, 그리고 `StrictSettingsBinder` — `app.object-storage` 트리는 환경 변수까지 엄격하게
바인딩한다. capability 규칙 4)다.
- provider SDK·설정 타입은 이 leaf 안에 머문다.
- provider 기여는 부작용 없이 지원 내용을 설명할 수 있고, 정확히 골라진 뒤에만 자원을 만들 수 있다.
## 금지
- inbound 어댑터, 이웃 outbound 어댑터, 영속, app-bootstrap 의존.
- provider 키·경로·locator·SDK 타입·Spring 타입·제어 레코드 타입이 application-core로 새는 것.
- 기본 provider·destination·namespace, 운영에서 local-dev, capability가 꺼져 있을 때 기동 중 변경.
- 보통 라우팅 타입이 scanner 유지보수 포트를 구현하기.
- `docs/registries/object-storage-readiness.yaml`의 정확한 행보다 높은 주장.
- 새 semantic operation을 옛 호출자 키 기반 덮어쓰기 뜻으로 되돌려 맞추기.
## 테스트
```bash
cd src
./gradlew :adapter:outbound:objectstorage:check --console=plain
```
@AGENTS.md
+1 -1
View File
@@ -4,7 +4,7 @@
`dev.caskeleton.application.objectstorage`의 semantic 계약을 구현하고, provider 키·경로·SDK 타입·제어
레코드를 애플리케이션 경계 뒤에 둔다.
허용 운영 의존은 `src/config/architecture/modules.json`이 가진다. 모듈 규칙은 [CLAUDE.md](CLAUDE.md), 전체
허용 운영 의존은 `src/config/architecture/modules.json`이 가진다. 모듈 규칙은 [AGENTS.md](AGENTS.md), 전체
설계는 `docs/design/2026-07-28-objectstorage-production-capability-design.md`, 정확한 증거 주장은
`docs/registries/object-storage-readiness.yaml`에 있다.
@@ -0,0 +1,59 @@
# persistence-fileserver
파일 서버 capability의 관계형 영속이다: 엔티티, Spring Data repository, `application-fileserver` 포트를 구현하는
store 어댑터. 루트 `AGENTS.md`와 `adapter/outbound/persistence-jpa/AGENTS.md`도 그대로 적용된다. 이 파일은 이
leaf에만 있는 것을 더한다.
## 패키지
- `entity/` — JPA 행만. 모든 엔티티는 `AssignedIdEntity`를 상속한다.
- `repository/` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`CleanupClaimSql`).
- 패키지 루트 — store 어댑터(`Jpa*`), `FileEntityMapper`, 그것들을 bean으로 등록하는 `@Configuration`
클래스.
`persistence-notification`도 같은 규칙(`platform.entity`, `platform.repository`, 어댑터는 `platform`)을
따르므로 두 capability leaf를 같은 방식으로 읽는다.
## 규칙
- **트랜잭션.** store는 트랜잭션을 열지 않는다. 모든 쓰기는 `CallerTransaction.require("<store> <operation>")`로
시작한다. 그래서 `TransactionPort.inWrite`를 잊은 유스케이스는 문장마다 커밋하지 않고 실패한다.
- **새 행.** id를 insert 전에 정하므로 엔티티가 새것인지 스스로 말해야 한다: `AssignedIdEntity`
(`Persistable<UUID>`)를 상속한다. 그렇지 않으면 `save`가 merge한다 — insert마다 SELECT가 앞서고, 이미 있는 id로
하는 두 번째 insert가 primary key에서 실패하지 않고 행을 덮어쓴다. 새 `@Version` 열은 primitive `long`으로 둬도
된다. 새것인지는 version이 아니라 `Persistable`이 정한다.
- **여기에 정책을 두지 않는다.** 재시도 예산, lease 길이 같은 판단은 `application-fileserver`의 것이고 포트
인자로 온다. claim token 같은 fence는 어댑터 필드가 아니라 포트 타입(`CleanupItem.claimToken`)에 실려 다닌다.
- **claim.** queue claim은 문장 하나다: CTE + `FOR UPDATE SKIP LOCKED` + `RETURNING`(`CleanupClaimSql`). 마무리
처리는 claim token을 맞춰 보고, 낡은 worker이면 0행을 update한다.
## migration
- `src/main/resources/db/migration/jpa/fileserver/V*.sql`. capability 자신의 Flyway stream
(`flyway_jpa_fileserver_history`)으로 적용한다.
- 적용한 파일은 고치지 않는다. 새 버전과 그 hash를 불변 목록에 더한다. `persistence-jpa`의
`AppliedMigrationImmutabilityTest`가 이 파일들을 있는 자리에서 고정한다.
## 테스트
- `src/test` — container 없는 이 leaf 자신의 시험. 돌리기:
`./gradlew :adapter:outbound:persistence-fileserver:test --console=plain`.
- `FileserverStoreCallerTransactionTest` — 모든 store의 보호된 쓰기는 호출자 트랜잭션이 없으면 repository에
닿기 전에 거절한다(위 트랜잭션 규칙, 쓰기마다 경우 하나. Spring Data repository는 mock이다).
- `FileserverPersistenceActivationTest` — scan은 `app.fileserver-platform.enabled` 뒤에서 이 패키지만 덮고,
JPA 루트 자동 구성보다 먼저 돈다.
- `repository.CleanupClaimSqlTest` — claim 글이 문장 하나 모양을 지킨다(claim 규칙). 잠금 자체는
`PostgreSqlFileserverReclamationIntegrationTest`가 PostgreSQL에서 본다.
- `entity.AssignedIdEntityTest` — H2 위의 Hibernate에서 `Persistable`로 새것인지 정한다.
새 store 쓰기는 보호 시험에 자기 경우를 더한다. 새 자동 구성은 켜기 시험에 자기 줄을 더한다.
- 포트 계약은 `application-fileserver` testFixtures에 있다(`*PortContract`, 그리고 테이블 하나를 같이 쓰는 quota
포트 셋의 `FileQuotaLedgerContract`). 메모리 fake와 PostgreSQL 시험이 모두 그것을 상속한다. 이 leaf가 구현하는
포트는 모두 계약이 있다(`docs/testing/TESTING_STRATEGY.md` 9.3절). 2026-11-03에 더한 일곱 개의 PostgreSQL
쪽은 `jpa-contract` tag를 달고 persistence-jpa의 `jpaPlatformContractTest` lane에서
`FileserverPostgreSqlStack` 위에 돈다. 경우마다 그 시계를 옮긴다.
- 실제 PostgreSQL 시험은 아직 `persistence-jpa`의 `postgresqlIntegrationTest` source set에 있다. 그 source set이
container와 Flyway 배선을 가지고, JPA readiness card(`persistence-jpa/release/readiness-cards.yaml`,
`JpaReadinessRegistryTest`가 검사)가 그 시험을 그 leaf의 태스크로 이름 댄다 — 옮기려면 card의 태스크와
selector도 함께 옮겨야 한다: `postgresqlFileserverMigrationIntegrationTest`,
`postgresqlFileserverMetadataIntegrationTest`, `postgresqlFileserverReclamationIntegrationTest`
(`./gradlew :adapter:outbound:persistence-jpa:<lane> --console=plain`).
@@ -1,59 +1 @@
# persistence-fileserver
파일 서버 capability의 관계형 영속이다: 엔티티, Spring Data repository, `application-fileserver` 포트를 구현하는
store 어댑터. 루트 `AGENTS.md`와 `adapter/outbound/persistence-jpa/CLAUDE.md`도 그대로 적용된다. 이 파일은 이
leaf에만 있는 것을 더한다.
## 패키지
- `entity/` — JPA 행만. 모든 엔티티는 `AssignedIdEntity`를 상속한다.
- `repository/` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`CleanupClaimSql`).
- 패키지 루트 — store 어댑터(`Jpa*`), `FileEntityMapper`, 그것들을 bean으로 등록하는 `@Configuration`
클래스.
`persistence-notification`도 같은 규칙(`platform.entity`, `platform.repository`, 어댑터는 `platform`)을
따르므로 두 capability leaf를 같은 방식으로 읽는다.
## 규칙
- **트랜잭션.** store는 트랜잭션을 열지 않는다. 모든 쓰기는 `CallerTransaction.require("<store> <operation>")`로
시작한다. 그래서 `TransactionPort.inWrite`를 잊은 유스케이스는 문장마다 커밋하지 않고 실패한다.
- **새 행.** id를 insert 전에 정하므로 엔티티가 새것인지 스스로 말해야 한다: `AssignedIdEntity`
(`Persistable<UUID>`)를 상속한다. 그렇지 않으면 `save`가 merge한다 — insert마다 SELECT가 앞서고, 이미 있는 id로
하는 두 번째 insert가 primary key에서 실패하지 않고 행을 덮어쓴다. 새 `@Version` 열은 primitive `long`으로 둬도
된다. 새것인지는 version이 아니라 `Persistable`이 정한다.
- **여기에 정책을 두지 않는다.** 재시도 예산, lease 길이 같은 판단은 `application-fileserver`의 것이고 포트
인자로 온다. claim token 같은 fence는 어댑터 필드가 아니라 포트 타입(`CleanupItem.claimToken`)에 실려 다닌다.
- **claim.** queue claim은 문장 하나다: CTE + `FOR UPDATE SKIP LOCKED` + `RETURNING`(`CleanupClaimSql`). 마무리
처리는 claim token을 맞춰 보고, 낡은 worker이면 0행을 update한다.
## migration
- `src/main/resources/db/migration/jpa/fileserver/V*.sql`. capability 자신의 Flyway stream
(`flyway_jpa_fileserver_history`)으로 적용한다.
- 적용한 파일은 고치지 않는다. 새 버전과 그 hash를 불변 목록에 더한다. `persistence-jpa`의
`AppliedMigrationImmutabilityTest`가 이 파일들을 있는 자리에서 고정한다.
## 테스트
- `src/test` — container 없는 이 leaf 자신의 시험. 돌리기:
`./gradlew :adapter:outbound:persistence-fileserver:test --console=plain`.
- `FileserverStoreCallerTransactionTest` — 모든 store의 보호된 쓰기는 호출자 트랜잭션이 없으면 repository에
닿기 전에 거절한다(위 트랜잭션 규칙, 쓰기마다 경우 하나. Spring Data repository는 mock이다).
- `FileserverPersistenceActivationTest` — scan은 `app.fileserver-platform.enabled` 뒤에서 이 패키지만 덮고,
JPA 루트 자동 구성보다 먼저 돈다.
- `repository.CleanupClaimSqlTest` — claim 글이 문장 하나 모양을 지킨다(claim 규칙). 잠금 자체는
`PostgreSqlFileserverReclamationIntegrationTest`가 PostgreSQL에서 본다.
- `entity.AssignedIdEntityTest` — H2 위의 Hibernate에서 `Persistable`로 새것인지 정한다.
새 store 쓰기는 보호 시험에 자기 경우를 더한다. 새 자동 구성은 켜기 시험에 자기 줄을 더한다.
- 포트 계약은 `application-fileserver` testFixtures에 있다(`*PortContract`, 그리고 테이블 하나를 같이 쓰는 quota
포트 셋의 `FileQuotaLedgerContract`). 메모리 fake와 PostgreSQL 시험이 모두 그것을 상속한다. 이 leaf가 구현하는
포트는 모두 계약이 있다(`docs/testing/TESTING_STRATEGY.md` 9.3절). 2026-11-03에 더한 일곱 개의 PostgreSQL
쪽은 `jpa-contract` tag를 달고 persistence-jpa의 `jpaPlatformContractTest` lane에서
`FileserverPostgreSqlStack` 위에 돈다. 경우마다 그 시계를 옮긴다.
- 실제 PostgreSQL 시험은 아직 `persistence-jpa`의 `postgresqlIntegrationTest` source set에 있다. 그 source set이
container와 Flyway 배선을 가지고, JPA readiness card(`persistence-jpa/release/readiness-cards.yaml`,
`JpaReadinessRegistryTest`가 검사)가 그 시험을 그 leaf의 태스크로 이름 댄다 — 옮기려면 card의 태스크와
selector도 함께 옮겨야 한다: `postgresqlFileserverMigrationIntegrationTest`,
`postgresqlFileserverMetadataIntegrationTest`, `postgresqlFileserverReclamationIntegrationTest`
(`./gradlew :adapter:outbound:persistence-jpa:<lane> --console=plain`).
@AGENTS.md
@@ -0,0 +1,357 @@
# adapter:outbound:persistence-jpa — JPA·PostgreSQL 영속 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-persistence-jpa`
- Gradle 경로: `:adapter:outbound:persistence-jpa`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-jpa:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.persistence`.
예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산
lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다.
이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다.
앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다.
## JPA 관계형 영속 플랫폼
`docs/design/2026-08-11-jpa-persistence-platform-design.md`의 플랫폼을 여기 구현했다. 설계는 그것을 Stable 라이브러리
모듈 18개로 모델링한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 이 leaf의
**패키지**이고 `docs/jpa/repository-adaptation.md`가 그 대응을 적는다. 타입을 다른 패키지로 옮기기 전에 그것을 읽는다.
| 플랫폼 패키지 | 가지는 것 |
|---|---|
| `autoconfigure` | package-private Boot 조립 루트·런타임: vendor와 선택 저장소 import, provider runtime bean. 일부러 공개 API로 내놓지 않는다 |
| `api` (+ `.capability`, `.error`, `.query`, `.transaction`) | 프레임워크 없는 계약: operation·query 이름, 안정된 오류 계층, 커밋 완료 증거, keyset cursor |
| `transaction` | `SpringTransaction`, 유일한 트랜잭션 엔진(Spring `PlatformTransactionManager` 위의 `TransactionPort`) |
| `springdata` | repository fragment, 안전한 정렬, fetch plan, keyset 실행, stream guard |
| `hibernate` (+ `.batch`, `.bulk`, `.stateless`) | statement inspector, 통계, batch, bulk DML, stateless session |
| `postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`) | SQLSTATE 분류, lock 옵션, JSONB, 배열과 범위, COPY |
| `migration` | `FlywaySchemaPolicy`(`startup` 패키지의 위험 설정 guard가 조립한다) |
| `startup` | package-private 기동 정책(`JpaStartupAutoConfiguration`): Flyway migration 전략, datasource env·제품 검사, OSIV·DDL·Hikari·TLS·H2 guard, `jpaplatform` actuator view, readiness `db` 기여. app-bootstrap에서 여기로 옮겼다 |
| `cache`, `envers`, `querydsl`, `security`, `observation` | 골라 쓰는 라이브러리 capability와 runtime role 검증기 |
| `experimental` | multi-tenancy, RLS, schema·database 테넌시, read replica — 배포가 스스로 만드는 라이브러리 코드. 켜는 flag가 없다 |
| `testkit`(`src/testFixtures/java`) | ArchUnit 규칙, fixture, query·plan 단언, PostgreSQL 표, 장애 주입, Flyway validate gate, concurrent index inspector, lock-wait inspector |
`springdata`, `hibernate`(`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`(`.error`, `.lock`,
`.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`, `querydsl`, `cache`, `observation`,
`experimental`은 **라이브러리 API**다: 어떤 설정도 그것을 조립하지 않고, 서비스가 이 leaf를 `implementation`으로 받는
자기 어댑터 leaf에서 부른다. 진입점과 각각을 증명하는 시험은 [README.md](README.md) 「라이브러리 API」에 있다.
### Spring 조립 소유
`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다:
`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다**
`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다.
둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은
`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은
2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지
않는다.
`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가
Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource,
pool, EntityManagerFactory, Flyway가 하나도 없다.
소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL
store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다),
`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를
고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability
registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌
data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다.
이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본
조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다:
migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고
(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정
(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면
안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다.
기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선
실수로 `verifyJpaApiSurface`가 늘지 않게 한다.
### 양보할 수 없는 것
- `GenericRepository<T, ID>`도 플랫폼 기반 repository도 없다. 도메인이 자기 repository를 가진다.
- `TransactionCompletionUnknownException`은 절대 재시도하지 않는다. `JpaFailureContext`는 재시도할 수 있는
completion-unknown 실패를 나타내기를 거절하고, `SpringTransaction`은 아무것도 재시도하지 않는다.
- 재시도하는 호출자는 새 트랜잭션과 새 Persistence Context에서 유스케이스 전체를 다시 돌린다.
- OSIV는 모든 runtime profile에서 false다. schema 변경은 Flyway가 가지고 Hibernate는 검증만 한다.
- 이미 쓰이는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다
(`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest`가 그것이 없는 migration을 거절한다. 그
규칙 전에 릴리스한 migration 목록에는 새 migration을 넣지 않는다. 그 목록은 inspector가 문장을 새로 배우고 이미
`main`에 있는 파일에서 그것을 찾았을 때만 늘어난다.
- Flyway는 PostgreSQL migration lock을 열린 트랜잭션이 아니라 세션 동안 쥔다. 아니면 `CREATE INDEX CONCURRENTLY`
migration이 Flyway를 영원히 기다린다: 모듈 기본값의 `spring.flyway.postgresql.transactional-lock: false`, 그리고 코드에서
만드는 모든 Flyway는 `FlywaySchemaPolicy.configure()`에서 시작한다(`JpaProductionArchitectureTest`가
`Flyway.configure()`와 Flyway 설정을 직접 만드는 것 — `new FluentConfiguration()`, `new ClassicConfiguration()`, 하위
클래스 — 을 거절한다. `docs/jpa/migration-guide.md` "Who may change the schema").
- metric tag, 예외 메시지, 로그는 SQL 매개변수, entity id, tenant id, 개인정보를 싣지 않는다.
- 계약은 실제 PostgreSQL에 대고 돈다. H2는 어떤 계약도 만족시키지 않는다.
### 플랫폼 lane
```bash
cd src
./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour
# Release blocking composition is CI-owned; locally run the exact database qualification set:
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \
:adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \
:adapter:outbound:persistence-jpa:jpaPlatformFailureTest \
:adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \
:adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \
:adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest
```
Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가
아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다.
## 책임
- JPA 엔티티.
- Spring Data repository.
- 영속 mapper.
- repository 어댑터 구현.
- outbox append: 모델 하나. `JpaOutboxStore`가 `OutboxAppendPort`를 구현하고 `ValidatedIntegrationEvent`의 정확한 envelope
바이트와 hash를 저장한다. claim은 그것으로 같은 이벤트를 되살린다. 정해진 metadata가 다 갖춰지지 않은 행은 읽을 수
없고 DEAD로 간다. 짐작으로 발행하지 않는다. `V19`는 발행하지 않은 정해진 형식 이전 행을 거절한다.
- outbox relay fencing: `claimBatch`가 claim의 행 lock 아래에서 claim한 relay(`lease_owner`)를 기록하고
`lease_token`을 올린다(`V17`). `markPublished`/`markFailed`/`markDead`는 `event_id` + `IN_FLIGHT` + owner + token에
대한 조건부 UPDATE 하나이고 `APPLIED`/`STALE`을 돌려준다. 완료는 행을 읽어서 덮어쓰지 않는다. V2 outbox 세대는
2026-09-25에 지웠다(`docs/capability-status.md`).
- `TransactionPort` 구현(`SpringTransaction`) — 애플리케이션의 트랜잭션 의도와 Spring `PlatformTransactionManager` 사이의
다리.
- 감사 metadata 기반 + actor 이음매(`audit/AuditableEntity`, `audit/AuditContextPort`, `audit/DomainContextAuditContext`) —
아래 「영속 감사 계약」을 본다.
- 모든 RDBMS vendor가 같이 쓰는 vendor SPI 확장점:
- `outbox/jpa/OutboxClaimRepository` — vendor 모듈이 claim 전략(예: FOR UPDATE SKIP LOCKED)을 구현한다. 구현은 그
옆 `outbox/postgresql`과 `outbox/h2`에 있다.
- `failure/SqlStateErrorMapping` — vendor 모듈이 vendor 전용 SQLState 행을 기여한다.
## vendor 고르기
vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을
등록한다:
| vendor | 패키지 | 고르는 것 | schema 소유 |
| --- | --- | --- | --- |
| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` |
| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 |
outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와
`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중
driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도
`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다.
`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고
`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그
`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를
`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01
성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가
고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤
속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다:
`postgresql` provider는 기동 때 H2 data source를 거절한다.
H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 —
capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는
`postgresqlIntegrationTest`에 남는다.
outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을
정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다.
### capability로 막은 store
선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver`
패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는
`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다.
그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가
필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은
capability의 store는 있으면 안 된다.
## 허용
- `:application-core`
- `:domain-core`
- `:shared-contract`
- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기)
- Spring Data JPA와 Spring transaction.
## 금지 (Forbidden)
- `adapter-web`, `app-bootstrap`, `adapter:outbound:support`를 뺀 다른 outbound 어댑터.
- 표현 계층 DTO.
- 업무 정책 판단.
- 영속 어댑터 안에 숨긴 유스케이스 조율.
- repository 어댑터가 애플리케이션 흐름을 감싸 `@Transactional`을 여는 것 — 포트를 가로지르는 트랜잭션은 애플리케이션
유스케이스가 `TransactionPort`로 가진다. 어댑터 안의 트랜잭션은 포트 메서드 자체가 원자적이어야 하는 저장 프로토콜을
정할 때만 허용한다(예: durable operation claim·읽기, live event 위치 할당 + insert).
[application-core/AGENTS.md](../../../application-core/AGENTS.md)를 본다.
- **DB driver**(`org.postgresql..`, `org.h2..`)나 **`org.flywaydb.database.postgresql..`** — vendor 전용이라 이 모듈의
맞는 vendor 패키지(`.postgresql`, `.h2`)에만 둔다. NoSQL 전용 의존은 앞으로 생길 자기 모듈에만 둔다.
`CleanArchitectureTest`의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`과 `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2`가
강제한다.
- NoSQL 어댑터 코드. MongoDB·Redis·DynamoDB 어댑터는 이 모듈의 자식이 아니라 이웃 모듈이다.
- registry가 허용하지 않은 이웃 영속 어댑터나 inbound·outbound 어댑터.
## TransactionPort 구현 계약
`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다:
| 모드 | 전파 | 격리 | 읽기 전용 | timeout |
|---|---|---|---|---|
| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) |
| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 |
| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) |
| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 |
격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이
`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용),
`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다
`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다.
모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가
취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의
`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다.
후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에
던진 업무 예외는 바꾸지 않고 넘긴다.
미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기
template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥
트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시
`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다.
`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를
올리고 호출자에게 성공 값을 돌려주지 않는다.
### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract)
`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다:
```
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
```
레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나,
반복문을 트랜잭션 밖으로 뺀다.
## 영속 실패 번역 계약 (feature-persistence-failure-baseline)
날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다.
`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해
분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다.
**표준 행(core):**
| SQLState | code | category | http | retryable |
|---|---|---|---|---|
| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true |
| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true |
| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false |
| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):**
| SQLState | code | vendor |
|---|---|---|
| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) |
| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL |
| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL |
| `57014` | `DB_QUERY_CANCELED` | PostgreSQL |
| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL |
| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 |
| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 |
PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다.
`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와
`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는
것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에
따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든
다르면 `SqlStateClassificationParityTest`가 실패한다.
**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA
`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`)
→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring
data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`.
**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기
트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`:
PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라
`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을
수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다.
- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다
(`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반
`INTERNAL` envelope으로 답하게 한다(새는 것 없음).
- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT).
## 영속 감사 계약 (feature-persistence-auditing-contract)
감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다.
`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성
명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다.
ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에
`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다.
- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서
감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로
넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다.
- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면
(scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은
feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다.
- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를
상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline /
feature-transaction-concurrency-contract가 가진다.
- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity`
계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data
listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다.
## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules)
영속 mapper에 MapStruct를 들이면, 생성된 mapper 클래스에 `javax.annotation.processing.Generated`가 붙는다. mapper 경계
위반을 금지하는 아키텍처 규칙은 반드시 ArchUnit predicate로 생성 코드를 뺀다:
```java
import javax.annotation.processing.Generated;
classes()
.that().resideInAPackage("..adapter.persistence.mapper..")
.and().areNotAnnotatedWith(Generated.class)
.should() /* ... boundary rule ... */;
```
> 애너테이션 FQN에 주의한다: MapStruct는 `javax.annotation.processing.Generated`를 쓴다. Spring AOT는
> `org.springframework.aot.generate.Generated`를 쓴다 — 둘을 섞지 **않는다**. 예외는 반드시 빼려는 빌드 단계가 기대하는
> 바로 그 애너테이션으로 범위를 잡는다.
지금 ca-tmpl mapper는 손으로 쓴 것이라 ArchUnit에 MapStruct 예외를 아직 배선하지 않았다 — 생성을 더할 때 위
predicate를 따르고, fixture mapper로 red/green 시험을 더한다.
## NoSQL 확장 규칙
`adapter-persistence-nosql-core`를 미리 만들지 않는다. NoSQL 저장소는 모델과 운영 계약이 서로 다르다. 실제 MongoDB,
Redis, DynamoDB 어댑터가 필요해지면 이웃 모듈을 만든다:
```text
adapter-persistence-mongodb
adapter-persistence-redis
adapter-persistence-dynamodb
```
그런 모듈은 application·domain 포트를 직접 구현하고 `adapter:outbound:persistence-jpa`에 의존하면 안 된다.
## 테스트
```bash
cd src
./gradlew :adapter:outbound:persistence-jpa:test --console=plain
```
+1 -357
View File
@@ -1,357 +1 @@
# adapter:outbound:persistence-jpa — JPA·PostgreSQL 영속 어댑터
## 등록 정보
- 모듈 ID: `adapter-outbound-persistence-jpa`
- Gradle 경로: `:adapter:outbound:persistence-jpa`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-jpa:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.persistence`.
예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산
lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다.
이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다.
앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다.
## JPA 관계형 영속 플랫폼
`docs/design/2026-08-11-jpa-persistence-platform-design.md`의 플랫폼을 여기 구현했다. 설계는 그것을 Stable 라이브러리
모듈 18개로 모델링한다. 이 저장소의 실패하면 닫히는 registry가 그 배치보다 앞서므로, 그 모듈들은 이 leaf의
**패키지**이고 `docs/jpa/repository-adaptation.md`가 그 대응을 적는다. 타입을 다른 패키지로 옮기기 전에 그것을 읽는다.
| 플랫폼 패키지 | 가지는 것 |
|---|---|
| `autoconfigure` | package-private Boot 조립 루트·런타임: vendor와 선택 저장소 import, provider runtime bean. 일부러 공개 API로 내놓지 않는다 |
| `api` (+ `.capability`, `.error`, `.query`, `.transaction`) | 프레임워크 없는 계약: operation·query 이름, 안정된 오류 계층, 커밋 완료 증거, keyset cursor |
| `transaction` | `SpringTransaction`, 유일한 트랜잭션 엔진(Spring `PlatformTransactionManager` 위의 `TransactionPort`) |
| `springdata` | repository fragment, 안전한 정렬, fetch plan, keyset 실행, stream guard |
| `hibernate` (+ `.batch`, `.bulk`, `.stateless`) | statement inspector, 통계, batch, bulk DML, stateless session |
| `postgresql` (+ `.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`) | SQLSTATE 분류, lock 옵션, JSONB, 배열과 범위, COPY |
| `migration` | `FlywaySchemaPolicy`(`startup` 패키지의 위험 설정 guard가 조립한다) |
| `startup` | package-private 기동 정책(`JpaStartupAutoConfiguration`): Flyway migration 전략, datasource env·제품 검사, OSIV·DDL·Hikari·TLS·H2 guard, `jpaplatform` actuator view, readiness `db` 기여. app-bootstrap에서 여기로 옮겼다 |
| `cache`, `envers`, `querydsl`, `security`, `observation` | 골라 쓰는 라이브러리 capability와 runtime role 검증기 |
| `experimental` | multi-tenancy, RLS, schema·database 테넌시, read replica — 배포가 스스로 만드는 라이브러리 코드. 켜는 flag가 없다 |
| `testkit`(`src/testFixtures/java`) | ArchUnit 규칙, fixture, query·plan 단언, PostgreSQL 표, 장애 주입, Flyway validate gate, concurrent index inspector, lock-wait inspector |
`springdata`, `hibernate`(`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`(`.error`, `.lock`,
`.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`, `querydsl`, `cache`, `observation`,
`experimental`은 **라이브러리 API**다: 어떤 설정도 그것을 조립하지 않고, 서비스가 이 leaf를 `implementation`으로 받는
자기 어댑터 leaf에서 부른다. 진입점과 각각을 증명하는 시험은 [README.md](README.md) 「라이브러리 API」에 있다.
### Spring 조립 소유
`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`는 package-private 항목 둘을 내놓는다:
`PersistenceJpaAutoConfiguration`과 `PersistenceJpaRuntimeConfig`. Boot가 그 후보를 따로따로 읽으므로 **둘 다**
`app.persistence-jpa.enabled=true`를 요구한다. 첫째는 vendor·entity·repository와 capability 저장소 import를 가진다.
둘째는 provider runtime bean(`HibernateProviderPolicy`, `PostgreSqlRuntimeRoleVerifier`)만 기여한다. 트랜잭션 엔진은
`SpringTransaction` 하나뿐이다. 두 번째 엔진(`SpringJpaTransactionExecutor`/`FullTransactionRetryCoordinator`)은
2026-09-25에 지웠다 — `docs/capability-status.md`를 본다. 첫째 후보의 조건이 이웃 import 후보를 막아 준다고 기대지
않는다.
`enabled=false`는 bean만이 아니라 완전히 끄기다: `JpaActivationEnvironmentPostProcessor`(이 leaf의 `spring.factories`)가
Boot의 `jdbc`/`hibernate`/`data.jpa`/`flyway` 자동 구성을 `spring.autoconfigure.exclude`에 붙인다. 그래서 DataSource,
pool, EntityManagerFactory, Flyway가 하나도 없다.
소유자를 안전하게 지키는 PostgreSQL 멱등성도 같은 분할을 쓴다: 이 leaf는 `IdempotencyStorePort` 뒤의 실제 PostgreSQL
store를 만들고(`PostgreSqlIdempotencyStoreConfig`, `app.capabilities.idempotency.provider=postgresql`일 때만 켜진다),
`composition:idempotency`가 provider 고르기, TTL·lease·codec 정책, executor 만들기, 배타성 검증을 가진다. 그 provider를
고르면 leaf는 `db/migration/jpa/core` + `db/migration/jpa/idempotency` Flyway stream도 적용하고 기동 때 capability
registry 행을 켜며(`IdempotencySchemaStream`, `app.runtime.migration-on-startup=false`이면 건너뛴다), PostgreSQL이 아닌
data source를 거절하고, `IdempotencyReaper`를 돌린다. V1·JDBC 멱등성 store도 `jdbc` provider 값도 없다.
이 모듈은 빌드 한 줄(`runtimeOnly project(':adapter:outbound:persistence-jpa')`)로 고르는 capability다. 템플릿의 기본
조립은 이것을 싣지 않는다. 그래서 관계형 저장소가 있을 때만 뜻이 있는 것은 모두 여기 있고 모듈과 함께 켜진다:
migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·TLS·vendor 안전, 걸러 낸 관리 endpoint·보고
(`startup`), metric을 단 다중 인스턴스 lock(`lock`), readiness `db` 기여, 출하하는 설정
(`config/module-defaults/persistence-jpa.yml`). 유스케이스 조립은 아니다: driven 어댑터가 유스케이스를 만들거나 부르면
안 되므로 outbox relay는 `composition:outbox-relay`다. leaf에는 `dev.caskeleton.bootstrap` import가 하나도 없어야 한다.
기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치고, 새 조립 도우미는 package-private로 둬서 배선
실수로 `verifyJpaApiSurface`가 늘지 않게 한다.
### 양보할 수 없는 것
- `GenericRepository<T, ID>`도 플랫폼 기반 repository도 없다. 도메인이 자기 repository를 가진다.
- `TransactionCompletionUnknownException`은 절대 재시도하지 않는다. `JpaFailureContext`는 재시도할 수 있는
completion-unknown 실패를 나타내기를 거절하고, `SpringTransaction`은 아무것도 재시도하지 않는다.
- 재시도하는 호출자는 새 트랜잭션과 새 Persistence Context에서 유스케이스 전체를 다시 돌린다.
- OSIV는 모든 runtime profile에서 false다. schema 변경은 Flyway가 가지고 Hibernate는 검증만 한다.
- 이미 쓰이는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다
(`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest`가 그것이 없는 migration을 거절한다. 그
규칙 전에 릴리스한 migration 목록에는 새 migration을 넣지 않는다. 그 목록은 inspector가 문장을 새로 배우고 이미
`main`에 있는 파일에서 그것을 찾았을 때만 늘어난다.
- Flyway는 PostgreSQL migration lock을 열린 트랜잭션이 아니라 세션 동안 쥔다. 아니면 `CREATE INDEX CONCURRENTLY`
migration이 Flyway를 영원히 기다린다: 모듈 기본값의 `spring.flyway.postgresql.transactional-lock: false`, 그리고 코드에서
만드는 모든 Flyway는 `FlywaySchemaPolicy.configure()`에서 시작한다(`JpaProductionArchitectureTest`가
`Flyway.configure()`와 Flyway 설정을 직접 만드는 것 — `new FluentConfiguration()`, `new ClassicConfiguration()`, 하위
클래스 — 을 거절한다. `docs/jpa/migration-guide.md` "Who may change the schema").
- metric tag, 예외 메시지, 로그는 SQL 매개변수, entity id, tenant id, 개인정보를 싣지 않는다.
- 계약은 실제 PostgreSQL에 대고 돈다. H2는 어떤 계약도 만족시키지 않는다.
### 플랫폼 lane
```bash
cd src
./gradlew :adapter:outbound:persistence-jpa:test # hermetic unit lane
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest # real PostgreSQL
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest # Flyway upgrade scenarios
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformFailureTest # deadlock
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest # EXPLAIN structure
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformSecurityTest # runtime role privileges
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest # pool behaviour
# Release blocking composition is CI-owned; locally run the exact database qualification set:
./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest \
:adapter:outbound:persistence-jpa:jpaPlatformMigrationTest \
:adapter:outbound:persistence-jpa:jpaPlatformFailureTest \
:adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest \
:adapter:outbound:persistence-jpa:jpaPlatformSecurityTest \
:adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest
```
Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가
아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다.
## 책임
- JPA 엔티티.
- Spring Data repository.
- 영속 mapper.
- repository 어댑터 구현.
- outbox append: 모델 하나. `JpaOutboxStore`가 `OutboxAppendPort`를 구현하고 `ValidatedIntegrationEvent`의 정확한 envelope
바이트와 hash를 저장한다. claim은 그것으로 같은 이벤트를 되살린다. 정해진 metadata가 다 갖춰지지 않은 행은 읽을 수
없고 DEAD로 간다. 짐작으로 발행하지 않는다. `V19`는 발행하지 않은 정해진 형식 이전 행을 거절한다.
- outbox relay fencing: `claimBatch`가 claim의 행 lock 아래에서 claim한 relay(`lease_owner`)를 기록하고
`lease_token`을 올린다(`V17`). `markPublished`/`markFailed`/`markDead`는 `event_id` + `IN_FLIGHT` + owner + token에
대한 조건부 UPDATE 하나이고 `APPLIED`/`STALE`을 돌려준다. 완료는 행을 읽어서 덮어쓰지 않는다. V2 outbox 세대는
2026-09-25에 지웠다(`docs/capability-status.md`).
- `TransactionPort` 구현(`SpringTransaction`) — 애플리케이션의 트랜잭션 의도와 Spring `PlatformTransactionManager` 사이의
다리.
- 감사 metadata 기반 + actor 이음매(`audit/AuditableEntity`, `audit/AuditContextPort`, `audit/DomainContextAuditContext`) —
아래 「영속 감사 계약」을 본다.
- 모든 RDBMS vendor가 같이 쓰는 vendor SPI 확장점:
- `outbox/jpa/OutboxClaimRepository` — vendor 모듈이 claim 전략(예: FOR UPDATE SKIP LOCKED)을 구현한다. 구현은 그
옆 `outbox/postgresql`과 `outbox/h2`에 있다.
- `failure/SqlStateErrorMapping` — vendor 모듈이 vendor 전용 SQLState 행을 기여한다.
## vendor 고르기
vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을
등록한다:
| vendor | 패키지 | 고르는 것 | schema 소유 |
| --- | --- | --- | --- |
| PostgreSQL | `.postgresql` | `app.persistence.vendor=postgresql`(기본값이기도 하다) | Flyway, `db/migration/postgresql` |
| H2 | `.h2` | `app.persistence.vendor=h2` | Hibernate `ddl-auto`, 엔티티만 |
outbox와 멱등성 기능은 기능별, 그다음 vendor별로 조각을 모아 둔다: `outbox/{jpa,postgresql,h2}`와
`idempotency/{jpa,postgresql}`. 어떤 claim repository를 등록할지는 여전히 위 vendor 설정이 정한다. 그 기능 클래스 중
driver 타입을 import하는 것이 없으므로, 그것들이 `.postgresql` 밖에 있어도
`PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`이 계속 지켜진다.
`config/PersistenceVendorSettings`가 선택자를 enum으로 바인딩한다. 그래서 모르는 값은 두 조립 중 어느 것도 읽지 않고
`OutboxClaimRepository`가 없다는 오류로 나타나는 대신 기동 때 실패한다. 선택은 모듈이 정한다: 그
`config/module-defaults/persistence-jpa.yml`이 모든 profile에서 vendor를 PostgreSQL로, `spring.flyway.enabled`를
`APP_FLYWAY_ENABLED`(true)로 기본 설정한다. 조립 루트의 profile 파일은 더는 그것을 다시 적지 않는다(2026-11-01
성숙도 리뷰 뒤로. 기본 조립 루트가 고르지 않은 capability의 설정을 알면 안 된다). H2는 `bootRunH2` 태스크가
고르는, 개발자가 명시해서 빠지는 길이다. `PersistenceVendorProdSafetyValidator`(`startup`)는 어떤
속성 출처가 주든 prod에서 H2를 거절한다. `bootRunH2`에서는 멱등성 provider가 `disabled`나 `redis`여야 한다:
`postgresql` provider는 기동 때 H2 data source를 거절한다.
H2는 로컬 개발 저장소이지 두 번째 운영 대상이 아니다. migration 트리가 없으므로, migration에만 있는 테이블 —
capability schema registry, Spring Integration lock 테이블 — 은 H2에 없다. vendor 동시성과 migration 충실도는
`postgresqlIntegrationTest`에 남는다.
outbox claim은 H2가 돌리는 유일한 vendor 문장이고 내용이 같다 — H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을
정말 건너뛰므로 claim이 뜻을 지킨다. `H2ClaimSqlTest`가 그것을 실제 H2에 대고 실행한다. H2에는 멱등성 store가 없다.
### capability로 막은 store
선택 capability 하나를 위한 어댑터는 이 모듈의 나머지와 달리 그 capability의 스위치를 단다. 지금은 `fileserver`
패키지가 그 경우다: 거기 있는 모든 `Jpa*` 어댑터는
`@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")`를 단다.
그 막음이 없으면 이 모듈을 넣기만 한 조립 루트도 그 bean을 만들고, 각 bean에는 파일 서버 설정만 주는 협력 객체가
필요하다. 지운 샘플 모듈이 쓰지도 않는 Fileserver 협력 객체 때문에 기동에 실패한 일이 그 예다. 아무도 켜지 않은
capability의 store는 있으면 안 된다.
## 허용
- `:application-core`
- `:domain-core`
- `:shared-contract`
- `:adapter:outbound:support`(타입 있는 기동 실패, EnvironmentPostProcessor 순서, readiness group, module-defaults 읽기)
- Spring Data JPA와 Spring transaction.
## 금지 (Forbidden)
- `adapter-web`, `app-bootstrap`, `adapter:outbound:support`를 뺀 다른 outbound 어댑터.
- 표현 계층 DTO.
- 업무 정책 판단.
- 영속 어댑터 안에 숨긴 유스케이스 조율.
- repository 어댑터가 애플리케이션 흐름을 감싸 `@Transactional`을 여는 것 — 포트를 가로지르는 트랜잭션은 애플리케이션
유스케이스가 `TransactionPort`로 가진다. 어댑터 안의 트랜잭션은 포트 메서드 자체가 원자적이어야 하는 저장 프로토콜을
정할 때만 허용한다(예: durable operation claim·읽기, live event 위치 할당 + insert).
[application-core/CLAUDE.md](../../../application-core/CLAUDE.md)를 본다.
- **DB driver**(`org.postgresql..`, `org.h2..`)나 **`org.flywaydb.database.postgresql..`** — vendor 전용이라 이 모듈의
맞는 vendor 패키지(`.postgresql`, `.h2`)에만 둔다. NoSQL 전용 의존은 앞으로 생길 자기 모듈에만 둔다.
`CleanArchitectureTest`의 ArchUnit `PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL`과 `PERSISTENCE_RDBMS_STAYS_NEUTRAL_OF_H2`가
강제한다.
- NoSQL 어댑터 코드. MongoDB·Redis·DynamoDB 어댑터는 이 모듈의 자식이 아니라 이웃 모듈이다.
- registry가 허용하지 않은 이웃 영속 어댑터나 inbound·outbound 어댑터.
## TransactionPort 구현 계약
`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다:
| 모드 | 전파 | 격리 | 읽기 전용 | timeout |
|---|---|---|---|---|
| `inWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `app.persistence-jpa.transaction.write-timeout`(30 s) |
| `inRootWrite` | `REQUIRED` | `READ_COMMITTED`(pool) | `false` | `inWrite`와 같음 |
| `inRead` | `REQUIRED` | `READ_COMMITTED`(pool) | `true` | `app.persistence-jpa.transaction.read-timeout`(30 s) |
| `inNew` | `REQUIRES_NEW` | `READ_COMMITTED`(pool) | `false` | 30 s, 고정 |
격리 수준은 template이 아니라 pool에 고정한다: template은 `ISOLATION_DEFAULT`를 쓰고, 모듈 기본값이
`spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`를 정하며(물리 연결마다 한 번 적용),
`HikariPoolConstraintValidator`가 다른 수준이면 기동을 거절한다. template마다 수준을 대면 Spring이 begin마다
`getTransactionIsolation()`을 부르고, pgjdbc는 그것에 `SHOW TRANSACTION ISOLATION LEVEL` 왕복으로 답했다.
모든 모드에는 시간 한계가 있다(2026-11-01부터). Spring이 남은 시간을 문장마다 넘기므로 느린 query나 lock 대기는 서버가
취소하고(`57014` → `DB_QUERY_CANCELED`), 다음 문장 전에 기한이 지난 경우도 같은 코드를 받는다: JDBC 경로에서는 Spring의
`TransactionTimedOutException`, JPA 경로(`JpaTransactionManager`, 운영)에서는 Hibernate 자신의 `TransactionException`이다.
후자는 SQLState가 없고, `SpringTransaction`이 기한이 지났음을 알기 때문에 분류된다(`translateAfterDeadline`). 기한 뒤에
던진 업무 예외는 바꾸지 않고 넘긴다.
미리 만든 template은 만든 뒤 바뀌지 않아서, 동시 호출자가 서로의 재설정을 볼 수 없다. `inRootWrite`는 미리 만든 쓰기
template을 다시 쓰지만, 먼저 `TransactionSynchronizationManager.isActualTransactionActive()`를 검사한다. 실제 바깥
트랜잭션이 있으면 action이나 `PlatformTransactionManager`를 부르기 전에 반드시
`NestedRootTransactionRejectedException`을 던진다. `NEVER`나 `REQUIRES_NEW`를 쓰면 안 된다.
`inRootWrite`는 `TransactionTemplate.execute`가 커밋한 뒤에만 action 값을 돌려준다. 커밋이 실패하면 트랜잭션 예외를
올리고 호출자에게 성공 값을 돌려주지 않는다.
### `inNew` 풀 크기 제약 (feature-application-port-usecase-contract)
`REQUIRES_NEW`는 바깥 트랜잭션의 연결을 쥔 채 새 물리 JDBC 연결을 얻는다. pool은 다음을 만족하게 잡는다:
```
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
```
레코드마다 `inNew`를 부르는 반복문은 금지다(pool 고갈 + 교착 위험). 레코드를 `inNew` **하나** 안에서 묶어 처리하거나,
반복문을 트랜잭션 밖으로 뺀다.
## 영속 실패 번역 계약 (feature-persistence-failure-baseline)
날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다.
`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해
분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다.
**표준 행(core):**
| SQLState | code | category | http | retryable |
|---|---|---|---|---|
| `08*` | `DB_UNAVAILABLE` | `TRANSIENT_DEPENDENCY` | 503 | true |
| `40001` | `DB_SERIALIZATION_FAILURE` | `CONFLICT` | 409 | true |
| `23502` | `DB_NULL_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
| `23503` | `DB_FK_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
| `23505` | `DB_UNIQUE_VIOLATION` | `CONFLICT` | 409 | false |
| `23514` | `DB_CHECK_VIOLATION` | `DATA_INTEGRITY` | 409 | false |
**vendor 전용 행(vendor 모듈이 `SqlStateErrorMapping` SPI로 기여):**
| SQLState | code | vendor |
|---|---|---|
| `40P01` | `DB_DEADLOCK` | PostgreSQL(`.postgresql` 패키지) |
| `55P03` | `DB_LOCK_TIMEOUT` | PostgreSQL |
| `25P03` | `DB_IDLE_IN_TX_TIMEOUT` | PostgreSQL |
| `57014` | `DB_QUERY_CANCELED` | PostgreSQL |
| `57P01`, `57P02` | `DB_UNAVAILABLE`(커밋 전. 커밋 중이면 completion-unknown) | PostgreSQL |
| `23513` | `DB_CHECK_VIOLATION` | H2(`.h2` 패키지) — H2는 CHECK를 core 표가 대응시키는 표준 23514가 아니라 23513으로 알린다 |
| `HYT00` | `DB_QUERY_CANCELED` | H2 — H2는 문장 timeout과 lock timeout을 상태 하나로 합친다 |
PostgreSQL 행은 두 번째 표가 아니다: 2026-11-01 전에는 손으로 관리하던 두 번째 표가 이미 어긋나 있었다.
`PostgreSqlSqlStateErrorMapping`이 그 행을 `PostgreSqlFailureClassifier`(SQLState → `FailureCategory`)와
`FailureCategory.operationalError()`(category → 코드)에서 끌어낸다 — 라이브러리 `PostgreSqlExceptionTranslator`가 쓰는
것과 같은 분류다 — 그리고 위 표준 행, 전용 코드가 없는 category(`INTERNAL_ERROR`), `COMPLETION_UNKNOWN`(단계에
따라 다르다)을 뺀다. PostgreSQL 상태를 더하려면 `PostgreSqlState`와 classifier에 더한다. 두 경로가 어떤 상태에서든
다르면 `SqlStateClassificationParityTest`가 실패한다.
**SQLState가 없고 타입으로 분류:** 진 `@Version` 경쟁(`OptimisticLockingFailureException`, JPA
`OptimisticLockException`) → `DB_OPTIMISTIC_CONFLICT`(409). 만료된 Spring 트랜잭션 기한(`TransactionTimedOutException`)
→ `DB_QUERY_CANCELED`. `SpringTransaction`이 시작한 트랜잭션의 기한이 지난 뒤의 다른 영속 실패(JPA, Spring
data-access, Spring transaction 예외) → `DB_QUERY_CANCELED`.
**커밋 단계(`translateCommitFailure`, ADR-JPA-003):** action이 돌아왔고 `SpringTransaction`이 자기가 시작한 쓰기
트랜잭션을 커밋하는 중이면, `08*`, `40003`, vendor가 기여한 종료 상태(`SqlStateErrorMapping.commitOutcomeUnknownStates()`:
PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 `DB_UNAVAILABLE`이 아니라
`TransactionCompletionUnknownException` → `DB_COMPLETION_UNKNOWN`(500, 절대 재시도하지 않음)이 된다: 서버가 이미 커밋했을
수 있다. 서버가 분명히 거절한 커밋(예: 미뤄진 `23505`)은 위 자기 행을 지킨다. 읽기 전용 커밋은 `DB_UNAVAILABLE`을 지킨다.
- `DataAccessException`을 잡는 repository 어댑터는 `translator.translate(ex)`를 부르고 carrier를 다시 던진다
(`ifPresent(e -> { throw e; })`). 빈 결과는 모르는 SQLState라는 뜻이다 — 원래 예외를 다시 던져 web catch-all이 일반
`INTERNAL` envelope으로 답하게 한다(새는 것 없음).
- category 정본은 값 10개의 `Category` enum이다 — `PERSISTENCE` category는 **없다**(설계 기록 §Audit CATEGORY_DRIFT).
## 영속 감사 계약 (feature-persistence-auditing-contract)
감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다.
`audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성
명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다.
ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에
`createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다.
- **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서
감사 값을 넣는다: INSERT(version null) → `initializeAudit(now, actor)`. UPDATE(version 있음) → 저장된 `created_*`를 그대로
넘기고 + `applyModification(now, actor)`. `created_*`는 `updatable = false`다.
- **actor 이음매.** `AuditContextPort.currentActor()`는 runtime-context 전파 이음매를 읽고, principal이 묶여 있지 않으면
(scheduler / Flyway / 익명) `"system"`으로 물러선다. actor 값의 뜻은
feature-authentication-authorization-contract가 가진다(여기서는 UNSUPPORTED). 타입은 `String`으로 고정한다.
- **빠지는 것.** `IdempotencyRecordEntity`(자기 `created_at`, `updated_at` 없음) 같은 기반·불변 엔티티는 `AuditableEntity`를
상속하지 **않는다**. `version`·낙관적 lock은 이 감사 기반이 아니라 feature-persistence-failure-baseline /
feature-transaction-concurrency-contract가 가진다.
- **자랄 길(미룸).** 트리에 두 번째 감사 구현은 없다. 손으로 넣는 것이 실수가 너무 잦아지면, 정해진 `AuditableEntity`
계약을 `created_*`/`updated_*` schema, actor 한계, `Clock`, `AuditContextPort` 뜻을 지키면서 한 번에 Spring Data
listener로 옮긴다. bulk·native `@Query` UPDATE도 listener를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다.
## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules)
영속 mapper에 MapStruct를 들이면, 생성된 mapper 클래스에 `javax.annotation.processing.Generated`가 붙는다. mapper 경계
위반을 금지하는 아키텍처 규칙은 반드시 ArchUnit predicate로 생성 코드를 뺀다:
```java
import javax.annotation.processing.Generated;
classes()
.that().resideInAPackage("..adapter.persistence.mapper..")
.and().areNotAnnotatedWith(Generated.class)
.should() /* ... boundary rule ... */;
```
> 애너테이션 FQN에 주의한다: MapStruct는 `javax.annotation.processing.Generated`를 쓴다. Spring AOT는
> `org.springframework.aot.generate.Generated`를 쓴다 — 둘을 섞지 **않는다**. 예외는 반드시 빼려는 빌드 단계가 기대하는
> 바로 그 애너테이션으로 범위를 잡는다.
지금 ca-tmpl mapper는 손으로 쓴 것이라 ArchUnit에 MapStruct 예외를 아직 배선하지 않았다 — 생성을 더할 때 위
predicate를 따르고, fixture mapper로 red/green 시험을 더한다.
## NoSQL 확장 규칙
`adapter-persistence-nosql-core`를 미리 만들지 않는다. NoSQL 저장소는 모델과 운영 계약이 서로 다르다. 실제 MongoDB,
Redis, DynamoDB 어댑터가 필요해지면 이웃 모듈을 만든다:
```text
adapter-persistence-mongodb
adapter-persistence-redis
adapter-persistence-dynamodb
```
그런 모듈은 application·domain 포트를 직접 구현하고 `adapter:outbound:persistence-jpa`에 의존하면 안 된다.
## 테스트
```bash
cd src
./gradlew :adapter:outbound:persistence-jpa:test --console=plain
```
@AGENTS.md
@@ -3,9 +3,9 @@
RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: `dev.caskeleton.adapter.persistence`.
허용/금지 의존, 테스트 명령, 그리고 **계약 테이블**(TransactionPort 모드표, SQLState → Error
Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [CLAUDE.md](CLAUDE.md) 다.
Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [AGENTS.md](AGENTS.md) 다.
이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다
"왜 이렇게 했나"가 궁금할 때 본다. 표가 CLAUDE.md 에 있으면 여기서는 중복하지 않고 그 근거만
"왜 이렇게 했나"가 궁금할 때 본다. 표가 AGENTS.md 에 있으면 여기서는 중복하지 않고 그 근거만
적는다.
## capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env
@@ -107,7 +107,7 @@ promotion gate, 생성하는 곳 없는 `JpaTransactionObservation` 등)은 `doc
readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로
(`WRITE` / `READ_ONLY` / `REQUIRES_NEW`) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가
사라지고, 각 모드를 따로 감사(audit)할 수 있다. 세 템플릿 모두 isolation 을 `READ_COMMITTED`
로 고정한다(모드표는 CLAUDE.md §TransactionPort implementation contract).
로 고정한다(모드표는 AGENTS.md §TransactionPort implementation contract).
### 왜 `inRootWrite`가 별도 템플릿이나 `NEVER` propagation을 만들지 않나
`inRootWrite`의 실행 속성은 `inWrite`와 같은 `WRITE + REQUIRED + READ_COMMITTED`라 기존
@@ -179,7 +179,7 @@ Spring Boot 메인 클래스는 `dev.caskeleton.bootstrap` 에 있어서, `@Auto
## failure — 퍼시스턴스 실패 변환 SPI
매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 CLAUDE.md §Persistence
매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 AGENTS.md §Persistence
failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 적는다.
### SPI-pluggable 설계 (vendor 추출)
@@ -502,7 +502,7 @@ stream migration이 중단되면 history/registry/object 상태를 먼저 확인
## lock — 분산 락
provider 선택표(flag → bean → registry)의 SSOT 는 CLAUDE.md(또는 app-bootstrap 와이어링)다.
provider 선택표(flag → bean → registry)의 SSOT 는 AGENTS.md(또는 app-bootstrap 와이어링)다.
여기서는 어댑터/설정 결정 근거만 적는다.
### `LockRegistryDistributedLock` 계약
@@ -0,0 +1,157 @@
# adapter:outbound:persistence-mongo — 모듈 규칙
## 등록 정보
- 모듈 ID: `adapter-outbound-persistence-mongo`
- Gradle 경로: `:adapter:outbound:persistence-mongo`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-mongo:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.mongo`. driven(outbound) 어댑터 — 골라 쓰는 MongoDB 문서 영속
플랫폼이다. 설계 근거는 [README.md](README.md)에 있다. 설계 패키지가 가정한 모듈 배치를 이 leaf에 대응시킨 것은
`docs/mongodb/repository-adaptation.md`에 있고, 그 대응이 바뀌면 고칠 파일이 그것이다.
## 책임
- 가짜 업무 도메인을 싣지 않고, 골라 쓰는 Mongo client, template, **플랫폼 정책** surface를 준다. 실제 fork가 자기
문서, repository, mapper, application·domain 포트 구현을 더한다.
- 멱등성·outbox·lock을 Mongo 위에 다시 구현하지 **않는다**(그것은 JPA에만 남는다).
- 있으면 켜진다: `app.persistence-mongo.enabled=false`가 아니면 `MongoRootAutoConfiguration`과 그것이 import하는
모든 것이 돈다(`matchIfMissing = true`. 출하하는 `config/mongo.yml`이 `APP_PERSISTENCE_MONGO_ENABLED`를 대응시키고
기본은 `true`). 빌드에 없는 것이 보통의 꺼진 상태다. 연결 URI와 데이터베이스는 Spring의 표준 `spring.mongodb.*`
설정에서 오고, 플랫폼 profile은 `app.persistence-mongo.platform.*`에서 온다.
연결 출처는 실패하면 닫힌다: `spring.mongodb.uri` / `SPRING_MONGODB_URI`가 비어 있지 않거나, 고른 typed profile이
`uri-secret`을 주고 배포가 `MongoCredentialResolver`를 줘야 한다. typed profile은 문서용만이 아니다:
`MongoProfileClientSettingsAutoConfiguration`이 `MongoClientSettingsFactory`를 Boot의 실제
`MongoClientSettings.Builder`에 가장 낮은 우선순위로 적용하므로, 그 TLS, Stable API, timeout, pool 정책이 일반
기본값을 덮는다. typed profile이 없으면(URI만) `MongoUriOnlyClientDefaults`가 Boot가 connection string을 적용하기
**전에** 유한한 socket·connect·server selection timeout과 pool 한계를 적용하므로, URI 매개변수가 여전히 이긴다.
자기 설정 키는 없다.
- 쓰는 쪽: 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 받는다. 절차는
`docs/mongodb/consumer-leaf-guide.md`다. 작동하는 예(문서, mapper, repository, 포트 구현)는 시험 소스 패키지
`…mongo.example`이고, `mongoStableContractTest`가 돌린다.
- `META-INF/spring.factories`로 등록한 `MongoDefaultsEnvironmentPostProcessor`가 `config/mongo.yml`을 가장 낮은
우선순위로 읽고, 명시한 `enabled=false`이면 Boot 4의 Mongo 자동 구성(Boot 자신의 등록 파일에서 읽는다)을
`spring.autoconfigure.exclude`에 붙인다.
- surface는 두 가지다. 자동 구성 bean(README.md 「자동 구성」에 적힌 것)은 `enabled=true`로 켜진다. 나머지는 모두
**라이브러리 API**다(README.md 「라이브러리 API」): 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로
받아 타입을 만든다. 라이브러리 API는 bean으로 등록하지 않고 자기 속성이 없다.
- Mongo health 연동은 leaf가 가진다. MongoRootAutoConfiguration이 내부 MongoPlatformHealthConfiguration을 import하고,
그것이 MongoPlatformHealthIndicator를 안정된 bean 이름 mongoPlatformHealthContributor 아래 Boot의 HealthIndicator
SPI에 맞춘다. 바깥 endpoint 노출은 여전히 애플리케이션 Actuator 노출 정책이 정한다.
## 허용
- 프로젝트 의존 둘. `Sha256`과 `HmacSha256` 도우미를 위한 `shared-contract`(테넌트 관찰 키, admin 명령 digest,
credential fingerprint, keyset cursor tag. `MongoDigestOutputTest`가 출력을 고정한다). `SecretSourcePort`만을 위한
`application-core`. registry 항목의 `allowed_dependencies`는 `["application-core", "shared-contract"]`이고 빌드가
실제로 쓰는 것과 맞는다. `MongoProfileClientSettingsAutoConfiguration`의 bridge가 typed profile의 `uri-secret`을
배포가 설정한 비밀 값 backend로 해석한다. `verifyCleanArchitectureDependencies`는 해석된 edge가 선언된 것의
부분집합인지만 보므로 쓰지 않는 허가는 매번 통과한다. `MongoRegistryPermissionParityTest`가 반대 방향을 보고 두
집합이 다르면 실패한다.
- 서비스는 `app-bootstrap/build.gradle`에서 주석 처리한 한 줄
`runtimeOnly project(':adapter:outbound:persistence-mongo')`로 이 leaf를 고른다. 기본 조립은 싣지 않는다. leaf는
imperative만이다: reactive 쌍둥이(`reactive/**`, reactive 트랜잭션·세션), change-stream 소비자, change-stream →
메시징 bridge는 2026-09-25에 지웠다(`docs/capability-status.md`). 그래서 leaf는 reactive starter도
reactive-streams driver도 싣지 않는다(`MongoReactiveDriverAbsenceTest`).
- 외부 의존: (sync) Mongo starter, spring-boot-autoconfigure, spring-boot-health, micrometer-core, slf4j-api,
configuration processor. Boot Health가 Jackson 애너테이션을 싣지만 런타임 JSON 직렬화는 애플리케이션의 몫이라서
Jackson 애너테이션은 compile 전용이다. 버전은 공용 Spring Boot BOM에서 온다. driver 버전을 직접 고정하지 않는다.
- 시험 전용: ArchUnit, Testcontainers(`mongodb`, `toxiproxy`).
## 금지 (Forbidden)
- inbound 어댑터, 이웃 outbound 어댑터, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음).
- 운영 코드에 자리표시용 `Example*` 문서, repository, record, 어댑터 타입을 싣기.
- 따로 승인된 계약 없이 Mongo 위에 멱등성·outbox·lock을 더하기.
- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상.
### 패키지 경계 규칙 (`MongoModuleBoundaryTest`)
설계의 모듈 의존 표를 그대로 옮긴 것이다. 하나라도 어기면 빌드가 실패한다:
- `…mongo.api..`는 Spring, MongoDB driver, BSON, Reactor를 import하지 않는다. 프레임워크 없는 핵심 계약이다.
`api/package-info.java`가 이유를 적는다.
- Stable 패키지는 `…mongo.advanced..`에 의존하지 않는다.
- 운영 패키지는 `…mongo.testkit..`에 의존하지 않는다.
- `query` ↛ `aggregation`, `schema` ↛ 실행 패키지, `observation` ↛ 실행 패키지, `migration` ↛ `migration.flamingock`.
### 일관성에 묶인 template
`MongoConsistencyBinder`는 일관성 profile마다 `MongoTemplate`을 하나 끌어낸다. Spring Data는 template의 지원 계약에
setter만 내놓고 getter를 내놓지 않는다. 그래서 따라가야 하는 부분 — write-concern resolver, 쓰기 결과 검사,
lifecycle 이벤트, entity callback과 auditing을 주는 `ApplicationContext` — 을 `MongoTemplateSupportContract`로 명시해
넘긴다. 여기서 private 필드에 대한 리플렉션은 금지다. context 밖에서 프로그램으로 callback을 등록한 template은
묶인 경로로 다시 만들 수 없다. 그 설정은 소리 없이 버리지 않고 지원하지 않는 것으로 둔다.
### 공개 surface
jar 하나 안의 모든 공개 최상위 타입이므로, `public`은 어느 패키지에 있든 모든 채택자에게 공개다.
`verifyMongoApiSurface`(`check` 안)가 surface를 개수를 담은 `docs/architecture/mongo-api-surface.txt`와 비교한다.
늘리려면 `updateMongoApiSurface -PapproveMongoApiSurfaceChange`가 필요하고, 그것은 리뷰 결정이다.
아키텍처 규칙 catalog(`…mongo.architecture`)는 운영이 아니라 **testkit** source set에 있다: ArchUnit 입력이고, 그것을
싣으면 모든 쓰는 쪽의 runtime classpath에 규칙 글이 올라갔다. 같은 이유로 릴리스 gate도 testkit 전용이고, 구현은
둘이 아니라 하나다: `…mongo.testkit.release`가 lane이 쓴 JUnit XML을 읽고, `scripts/verify-mongodb-platform.sh`와
`src/adapter/outbound/persistence-mongo/release/release-contracts.json`이 그것을 돌린다. 운영 classpath에 있던 두 번째
짝 — 손으로 만든 category 이름 집합과 그것을 검사한 gate — 은 자기 시험 말고는 호출자가 없었고 category 뒤에 정본도
없었다. 옮기지 않고 없앴다.
아직 남았고, 리뷰 정리의 일부로 일부러 하지 않은 것: 구현 패키지를 `internal` 루트 아래로 옮기고 그 안의 가시성을
낮추는 일. 약 200개 파일에 걸친 기계적 변경이라 자기 커밋에 둔다. 그 뒤에는 위 snapshot이 surface가 실제로
줄었다는 증거가 된다.
### credential과 운영 profile
운영 `MongoProfileProperties`는 TLS, 인증, 엄격한 Stable API, standalone이 아닌 topology, 유한한 양의 timeout을
선언해야 한다. `validate()`가 그것을 모두 강제한다. URI는 `secret://` 참조이고, 그것을 connection string으로 바꾸는
것은 `MongoCredentialResolver`뿐이다 — 값을 호출자가 준 함수에 넘기고 돌려주지 않으니, credential은 필드나 bean
속성이나 로그 줄이 아니라 호출 한 번의 지역 변수다.
`platform.profiles`가 비어 있지 않으면 채택은 일부러 실패하면 닫힌다. 조립 변경 하나에서 데이터 plane
`MongoCredentialResolver`와 함께 `MongoTopologyProbe`, `MongoSecurityProfile`, admin `MongoCredentialReference`,
`MongoSchemaVersionRange`를 준다. README.md에 필드 14개짜리 운영 profile 예가 다 있다. profile을 조금씩 주며 그
요구를 기동 실패 하나씩으로 알아내는 것은 받아들인 채택 길이 아니다.
기본 resolver는 `SecretSourcePort` 위의 bridge다(`MongoCredentialResolver.fromSecretSource`. 그 포트에 bean이 있고
다른 resolver가 없을 때 등록한다). 키는 Redis·HTTP client 모듈처럼 참조의 마지막 경로 조각이다. 싣지 않은 것:
실제 인증서를 가진 container가 필요한 TLS lane(믿는 CA, 틀린 CA, hostname 불일치, 만료된 인증서). 교체 순서 — 새
generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoClientGenerationConcurrencyTest`가 덮는다.
### 문체가 아닌 플랫폼 불변식
- 트랜잭션 본문 재시도와 커밋 재시도는 **따로 도는 반복문**이다: 본문 시도마다 새 세션, 모르는 커밋에는 커밋만
재시도. 커밋이 모호해진 뒤에는 본문을 다시 돌리지 않는다(`MongoTransactionRetryCoordinator`, ADR-MONGO-003).
- `MongoExecutionOutcome`의 모호한 값 둘을 성공이나 실패로 뭉개면 안 된다.
- BSON 표현은 라이브러리 기본값이 아니라 `MongoTypeRepresentationManifest`에서 온다(ADR-MONGO-002).
- index와 validator 변경은 manifest와 admin plane을 거친다. 모든 drop은 소유권이 막는다(ADR-MONGO-004).
- 모든 구체 Advanced 타입은 `@MongoAdvancedEntryPoint(capability)`나 `@MongoAdvancedPolicy`를 단다. entry point는
`MongoAdvancedCapabilityGuard`를 받고, 존재하기 전에 `require`를 부른다. `MongoAdvancedRules`가 두 절반을 강제한다.
「실행되는 것은 막는다」가 「누가 기억해 낸 것은 막는다」가 되지 않게 하는 것이 분류 규칙이다.
- flag에는 설정 속성이 없다. Advanced 타입은 라이브러리 API다: 채택자의 어댑터가 코드로
`MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안
된다.
- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는
문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다.
- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고
2026-09-25에 지웠다.
- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다.
## 테스트
`MongoCapabilityActivationTest`는 실제 `SpringApplication`을 띄워 있음 = 켜짐, 명시한 `enabled=false` = client·
template·플랫폼 bean 없음(Boot의 Mongo 자동 구성 포함)을 증명한다. `MongoPersistenceConfigTest`는 타입 있는 켜기
바인딩과, 네트워크 연결 없이 mock `MongoClient`와 실제 `MongoTemplate`으로 켜진 기반을 덮는다.
밀폐된 계약 시험은 `@Tag("mongodb-contract")`를 달고 `check`가 의존하는 `mongoStableContractTest`에서 돈다. container
lane은 `mongodb-replicaset` / `mongodb-failover`를 달고 자기 태스크에서만 돈다. 기본 `test` 태스크는 그것을 뺀다.
`check` 안에 Docker가 필요한 lane이 있으면 사람들이 `check`를 건너뛰게 되기 때문이다.
```bash
cd src
./gradlew :adapter:outbound:persistence-mongo:check --console=plain
```
릴리스 gate는 저장소 루트에서 돈다: `scripts/verify-mongodb-platform.sh`(Stable)와
`scripts/verify-mongodb-advanced.sh`(Advanced).
@@ -1,157 +1 @@
# adapter:outbound:persistence-mongo — 모듈 규칙
## 등록 정보
- 모듈 ID: `adapter-outbound-persistence-mongo`
- Gradle 경로: `:adapter:outbound:persistence-mongo`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:persistence-mongo:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound.mongo`. driven(outbound) 어댑터 — 골라 쓰는 MongoDB 문서 영속
플랫폼이다. 설계 근거는 [README.md](README.md)에 있다. 설계 패키지가 가정한 모듈 배치를 이 leaf에 대응시킨 것은
`docs/mongodb/repository-adaptation.md`에 있고, 그 대응이 바뀌면 고칠 파일이 그것이다.
## 책임
- 가짜 업무 도메인을 싣지 않고, 골라 쓰는 Mongo client, template, **플랫폼 정책** surface를 준다. 실제 fork가 자기
문서, repository, mapper, application·domain 포트 구현을 더한다.
- 멱등성·outbox·lock을 Mongo 위에 다시 구현하지 **않는다**(그것은 JPA에만 남는다).
- 있으면 켜진다: `app.persistence-mongo.enabled=false`가 아니면 `MongoRootAutoConfiguration`과 그것이 import하는
모든 것이 돈다(`matchIfMissing = true`. 출하하는 `config/mongo.yml`이 `APP_PERSISTENCE_MONGO_ENABLED`를 대응시키고
기본은 `true`). 빌드에 없는 것이 보통의 꺼진 상태다. 연결 URI와 데이터베이스는 Spring의 표준 `spring.mongodb.*`
설정에서 오고, 플랫폼 profile은 `app.persistence-mongo.platform.*`에서 온다.
연결 출처는 실패하면 닫힌다: `spring.mongodb.uri` / `SPRING_MONGODB_URI`가 비어 있지 않거나, 고른 typed profile이
`uri-secret`을 주고 배포가 `MongoCredentialResolver`를 줘야 한다. typed profile은 문서용만이 아니다:
`MongoProfileClientSettingsAutoConfiguration`이 `MongoClientSettingsFactory`를 Boot의 실제
`MongoClientSettings.Builder`에 가장 낮은 우선순위로 적용하므로, 그 TLS, Stable API, timeout, pool 정책이 일반
기본값을 덮는다. typed profile이 없으면(URI만) `MongoUriOnlyClientDefaults`가 Boot가 connection string을 적용하기
**전에** 유한한 socket·connect·server selection timeout과 pool 한계를 적용하므로, URI 매개변수가 여전히 이긴다.
자기 설정 키는 없다.
- 쓰는 쪽: 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로 받는다. 절차는
`docs/mongodb/consumer-leaf-guide.md`다. 작동하는 예(문서, mapper, repository, 포트 구현)는 시험 소스 패키지
`…mongo.example`이고, `mongoStableContractTest`가 돌린다.
- `META-INF/spring.factories`로 등록한 `MongoDefaultsEnvironmentPostProcessor`가 `config/mongo.yml`을 가장 낮은
우선순위로 읽고, 명시한 `enabled=false`이면 Boot 4의 Mongo 자동 구성(Boot 자신의 등록 파일에서 읽는다)을
`spring.autoconfigure.exclude`에 붙인다.
- surface는 두 가지다. 자동 구성 bean(README.md 「자동 구성」에 적힌 것)은 `enabled=true`로 켜진다. 나머지는 모두
**라이브러리 API**다(README.md 「라이브러리 API」): 서비스 자신의 어댑터 leaf가 이 leaf를 `implementation`으로
받아 타입을 만든다. 라이브러리 API는 bean으로 등록하지 않고 자기 속성이 없다.
- Mongo health 연동은 leaf가 가진다. MongoRootAutoConfiguration이 내부 MongoPlatformHealthConfiguration을 import하고,
그것이 MongoPlatformHealthIndicator를 안정된 bean 이름 mongoPlatformHealthContributor 아래 Boot의 HealthIndicator
SPI에 맞춘다. 바깥 endpoint 노출은 여전히 애플리케이션 Actuator 노출 정책이 정한다.
## 허용
- 프로젝트 의존 둘. `Sha256`과 `HmacSha256` 도우미를 위한 `shared-contract`(테넌트 관찰 키, admin 명령 digest,
credential fingerprint, keyset cursor tag. `MongoDigestOutputTest`가 출력을 고정한다). `SecretSourcePort`만을 위한
`application-core`. registry 항목의 `allowed_dependencies`는 `["application-core", "shared-contract"]`이고 빌드가
실제로 쓰는 것과 맞는다. `MongoProfileClientSettingsAutoConfiguration`의 bridge가 typed profile의 `uri-secret`을
배포가 설정한 비밀 값 backend로 해석한다. `verifyCleanArchitectureDependencies`는 해석된 edge가 선언된 것의
부분집합인지만 보므로 쓰지 않는 허가는 매번 통과한다. `MongoRegistryPermissionParityTest`가 반대 방향을 보고 두
집합이 다르면 실패한다.
- 서비스는 `app-bootstrap/build.gradle`에서 주석 처리한 한 줄
`runtimeOnly project(':adapter:outbound:persistence-mongo')`로 이 leaf를 고른다. 기본 조립은 싣지 않는다. leaf는
imperative만이다: reactive 쌍둥이(`reactive/**`, reactive 트랜잭션·세션), change-stream 소비자, change-stream →
메시징 bridge는 2026-09-25에 지웠다(`docs/capability-status.md`). 그래서 leaf는 reactive starter도
reactive-streams driver도 싣지 않는다(`MongoReactiveDriverAbsenceTest`).
- 외부 의존: (sync) Mongo starter, spring-boot-autoconfigure, spring-boot-health, micrometer-core, slf4j-api,
configuration processor. Boot Health가 Jackson 애너테이션을 싣지만 런타임 JSON 직렬화는 애플리케이션의 몫이라서
Jackson 애너테이션은 compile 전용이다. 버전은 공용 Spring Boot BOM에서 온다. driver 버전을 직접 고정하지 않는다.
- 시험 전용: ArchUnit, Testcontainers(`mongodb`, `toxiproxy`).
## 금지 (Forbidden)
- inbound 어댑터, 이웃 outbound 어댑터, `app-bootstrap`(ArchUnit `OUTBOUND_ADAPTERS_*` 규칙 묶음).
- 운영 코드에 자리표시용 `Example*` 문서, repository, record, 어댑터 타입을 싣기.
- 따로 승인된 계약 없이 Mongo 위에 멱등성·outbox·lock을 더하기.
- 줄 안에 완전한 이름으로 쓴 타입 참조, 파일 하나에 공개 최상위 타입 둘 이상.
### 패키지 경계 규칙 (`MongoModuleBoundaryTest`)
설계의 모듈 의존 표를 그대로 옮긴 것이다. 하나라도 어기면 빌드가 실패한다:
- `…mongo.api..`는 Spring, MongoDB driver, BSON, Reactor를 import하지 않는다. 프레임워크 없는 핵심 계약이다.
`api/package-info.java`가 이유를 적는다.
- Stable 패키지는 `…mongo.advanced..`에 의존하지 않는다.
- 운영 패키지는 `…mongo.testkit..`에 의존하지 않는다.
- `query` ↛ `aggregation`, `schema` ↛ 실행 패키지, `observation` ↛ 실행 패키지, `migration` ↛ `migration.flamingock`.
### 일관성에 묶인 template
`MongoConsistencyBinder`는 일관성 profile마다 `MongoTemplate`을 하나 끌어낸다. Spring Data는 template의 지원 계약에
setter만 내놓고 getter를 내놓지 않는다. 그래서 따라가야 하는 부분 — write-concern resolver, 쓰기 결과 검사,
lifecycle 이벤트, entity callback과 auditing을 주는 `ApplicationContext` — 을 `MongoTemplateSupportContract`로 명시해
넘긴다. 여기서 private 필드에 대한 리플렉션은 금지다. context 밖에서 프로그램으로 callback을 등록한 template은
묶인 경로로 다시 만들 수 없다. 그 설정은 소리 없이 버리지 않고 지원하지 않는 것으로 둔다.
### 공개 surface
jar 하나 안의 모든 공개 최상위 타입이므로, `public`은 어느 패키지에 있든 모든 채택자에게 공개다.
`verifyMongoApiSurface`(`check` 안)가 surface를 개수를 담은 `docs/architecture/mongo-api-surface.txt`와 비교한다.
늘리려면 `updateMongoApiSurface -PapproveMongoApiSurfaceChange`가 필요하고, 그것은 리뷰 결정이다.
아키텍처 규칙 catalog(`…mongo.architecture`)는 운영이 아니라 **testkit** source set에 있다: ArchUnit 입력이고, 그것을
싣으면 모든 쓰는 쪽의 runtime classpath에 규칙 글이 올라갔다. 같은 이유로 릴리스 gate도 testkit 전용이고, 구현은
둘이 아니라 하나다: `…mongo.testkit.release`가 lane이 쓴 JUnit XML을 읽고, `scripts/verify-mongodb-platform.sh`와
`src/adapter/outbound/persistence-mongo/release/release-contracts.json`이 그것을 돌린다. 운영 classpath에 있던 두 번째
짝 — 손으로 만든 category 이름 집합과 그것을 검사한 gate — 은 자기 시험 말고는 호출자가 없었고 category 뒤에 정본도
없었다. 옮기지 않고 없앴다.
아직 남았고, 리뷰 정리의 일부로 일부러 하지 않은 것: 구현 패키지를 `internal` 루트 아래로 옮기고 그 안의 가시성을
낮추는 일. 약 200개 파일에 걸친 기계적 변경이라 자기 커밋에 둔다. 그 뒤에는 위 snapshot이 surface가 실제로
줄었다는 증거가 된다.
### credential과 운영 profile
운영 `MongoProfileProperties`는 TLS, 인증, 엄격한 Stable API, standalone이 아닌 topology, 유한한 양의 timeout을
선언해야 한다. `validate()`가 그것을 모두 강제한다. URI는 `secret://` 참조이고, 그것을 connection string으로 바꾸는
것은 `MongoCredentialResolver`뿐이다 — 값을 호출자가 준 함수에 넘기고 돌려주지 않으니, credential은 필드나 bean
속성이나 로그 줄이 아니라 호출 한 번의 지역 변수다.
`platform.profiles`가 비어 있지 않으면 채택은 일부러 실패하면 닫힌다. 조립 변경 하나에서 데이터 plane
`MongoCredentialResolver`와 함께 `MongoTopologyProbe`, `MongoSecurityProfile`, admin `MongoCredentialReference`,
`MongoSchemaVersionRange`를 준다. README.md에 필드 14개짜리 운영 profile 예가 다 있다. profile을 조금씩 주며 그
요구를 기동 실패 하나씩으로 알아내는 것은 받아들인 채택 길이 아니다.
기본 resolver는 `SecretSourcePort` 위의 bridge다(`MongoCredentialResolver.fromSecretSource`. 그 포트에 bean이 있고
다른 resolver가 없을 때 등록한다). 키는 Redis·HTTP client 모듈처럼 참조의 마지막 경로 조각이다. 싣지 않은 것:
실제 인증서를 가진 container가 필요한 TLS lane(믿는 CA, 틀린 CA, hostname 불일치, 만료된 인증서). 교체 순서 — 새
generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoClientGenerationConcurrencyTest`가 덮는다.
### 문체가 아닌 플랫폼 불변식
- 트랜잭션 본문 재시도와 커밋 재시도는 **따로 도는 반복문**이다: 본문 시도마다 새 세션, 모르는 커밋에는 커밋만
재시도. 커밋이 모호해진 뒤에는 본문을 다시 돌리지 않는다(`MongoTransactionRetryCoordinator`, ADR-MONGO-003).
- `MongoExecutionOutcome`의 모호한 값 둘을 성공이나 실패로 뭉개면 안 된다.
- BSON 표현은 라이브러리 기본값이 아니라 `MongoTypeRepresentationManifest`에서 온다(ADR-MONGO-002).
- index와 validator 변경은 manifest와 admin plane을 거친다. 모든 drop은 소유권이 막는다(ADR-MONGO-004).
- 모든 구체 Advanced 타입은 `@MongoAdvancedEntryPoint(capability)`나 `@MongoAdvancedPolicy`를 단다. entry point는
`MongoAdvancedCapabilityGuard`를 받고, 존재하기 전에 `require`를 부른다. `MongoAdvancedRules`가 두 절반을 강제한다.
「실행되는 것은 막는다」가 「누가 기억해 낸 것은 막는다」가 되지 않게 하는 것이 분류 규칙이다.
- flag에는 설정 속성이 없다. Advanced 타입은 라이브러리 API다: 채택자의 어댑터가 코드로
`MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안
된다.
- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는
문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다.
- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고
2026-09-25에 지웠다.
- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다.
## 테스트
`MongoCapabilityActivationTest`는 실제 `SpringApplication`을 띄워 있음 = 켜짐, 명시한 `enabled=false` = client·
template·플랫폼 bean 없음(Boot의 Mongo 자동 구성 포함)을 증명한다. `MongoPersistenceConfigTest`는 타입 있는 켜기
바인딩과, 네트워크 연결 없이 mock `MongoClient`와 실제 `MongoTemplate`으로 켜진 기반을 덮는다.
밀폐된 계약 시험은 `@Tag("mongodb-contract")`를 달고 `check`가 의존하는 `mongoStableContractTest`에서 돈다. container
lane은 `mongodb-replicaset` / `mongodb-failover`를 달고 자기 태스크에서만 돈다. 기본 `test` 태스크는 그것을 뺀다.
`check` 안에 Docker가 필요한 lane이 있으면 사람들이 `check`를 건너뛰게 되기 때문이다.
```bash
cd src
./gradlew :adapter:outbound:persistence-mongo:check --console=plain
```
릴리스 gate는 저장소 루트에서 돈다: `scripts/verify-mongodb-platform.sh`(Stable)와
`scripts/verify-mongodb-advanced.sh`(Advanced).
@AGENTS.md
@@ -55,7 +55,7 @@ class MongoNamespaceContractTest {
@DisplayName("operator-facing Mongo documentation names only the Boot 4 canonical namespace")
void operatorDocumentationDoesNotRecommendTheDeprecatedNamespace() {
Path module = repositoryRoot().resolve("src/adapter/outbound/persistence-mongo");
List<Path> documents = List.of(module.resolve("README.md"), module.resolve("CLAUDE.md"));
List<Path> documents = List.of(module.resolve("README.md"), module.resolve("AGENTS.md"));
assertThat(documents)
.allSatisfy(path -> assertThat(Files.isRegularFile(path)).as(path.toString()).isTrue());
@@ -0,0 +1,52 @@
# adapter:outbound:persistence-notification — 알림 관계형 영속
## 등록 정보
- 모듈 ID: `adapter-outbound-persistence-notification`. Gradle 경로와 허용 edge는
`src/config/architecture/modules.json`에 있다.
- 이 모듈만 시험: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`.
- 패키지 루트: `dev.caskeleton.adapter.outbound.persistence.notification`. 패키지 규칙은
`persistence-fileserver`와 같아서 두 capability leaf를 같은 방식으로 읽는다:
- `platform.entity` — JPA 행만.
- `platform.repository` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`RecipientClaimSql`).
- `platform` — store 어댑터(`Jpa*`, `Jdbc*`, inbox의 `JpaNotificationInbox`와 그 outbox 도우미),
`NotificationRecordMapper`, payload codec.
- `configuration` — store를 bean으로 등록하는 자동 구성 창구. leaf 루트에는 scan 설정과 schema stream이 있다.
엔티티 생성자·접근자·변경자는 store가 다른 패키지에서 쓰니 public이다. 엔티티는 leaf를 떠나지 않는다(포트는
record를 싣는다). 가시성이 더는 그것을 말해 주지 않으므로 규칙이 말한다:
`JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`를 `JpaProductionArchitectureTest`(app-bootstrap
`architectureTest`)가 운영 그래프에 대고 이 leaf와 `persistence-fileserver`에 돌린다.
## 시험은 어디 있나
| 무엇 | 어디 | 돌리기 |
|---|---|---|
| 단위·배선 시험 | 이 leaf, `src/test` | `:adapter:outbound:persistence-notification:test` |
| 이 store들의 실제 PostgreSQL 시험 | `persistence-jpa`, `src/postgresqlIntegrationTest/.../persistence/notification`(그 lane이 container와 Flyway 배선을 가진다) | `:adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests '<class>'` |
| store가 통과해야 하는 포트 계약 | `application-notification` testFixtures, `*.testkit.*Contract`(preference, suppression, deduplication, request, reconciliation job, admin operation, template registry, recipient lease, recipient delivery, delivery attempt, attempt resolver, delivery projection, provider event ledger, contact point, 그리고 contact point·suppression store 위의 부수 효과) | 메모리 fake(`application-notification` 시험)와 `persistence-jpa`의 `PostgreSql*ContractTest`가 모두 계약을 상속한다. PostgreSQL 쪽은 `jpaPlatformContractTest`가 돌린다 |
| migration 고정 | `persistence-jpa/src/test/resources/db/applied-migrations.sha256` | `:adapter:outbound:persistence-jpa:test`의 `AppliedMigrationImmutabilityTest` |
`application-notification` testFixtures에 계약이 있는 포트의 store는 따로 손으로 쓴 PostgreSQL 시험이 아니라
그 계약의 PostgreSQL 하위 클래스로 시험한다. vendor에 관한 경우(CHECK 제약, bulk update의 `@Version`)는 하위
클래스에 남긴다. 계약이 없는 포트(serving-state 읽기 모델, 동의, inbox)와 그 이유는
`docs/testing/TESTING_STRATEGY.md` 9.2절에 있다.
## 규칙
- **모든 쓰기는 호출자의 트랜잭션에 합류한다.** store 쓰기는 `CallerTransaction.require("<what>")`로
시작한다. 트랜잭션은 유스케이스가 가진다(소유자 결정 2026-09-25).
- **migration**은 `src/main/resources/db/migration/jpa/notification-platform`에 있고 자기 Flyway stream
(`NotificationSchemaStream`, history 테이블 `flyway_jpa_notification_history`)으로 돈다. 적용한 파일은 고치지
않는다: 다음 `V<n>__`를 더하고, 그 SHA-256을 `applied-migrations.sha256`에 고정하고,
`NotificationFixtures.migrations()`에 더한다. 행을 지우는 migration은 어떤 행이 남고 왜인지 SQL 주석에
적는다. 이미 있는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다
(`docs/jpa/migration-guide.md` "Bound the lock wait". persistence-jpa의 `MigrationLockWaitTest`가 그것이 없는
migration을 거절한다).
- **insert냐 update냐는 데이터베이스가 정한다.** 찾은 뒤 insert하지 않는다: `ON CONFLICT (<unique key>) DO
NOTHING`으로 insert하고, 아무것도 insert하지 않았으면 관리되는 엔티티로 있는 행을 update한다
(`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`, `DeduplicationClaims.insertOrFind`). 충돌
대상에는 migration에 unique 제약이 있어야 한다.
- **`@Version` 테이블의 bulk·native `UPDATE`는 version을 올린다**(`version = version + 1`). 호출자가 그 행을 다시
읽을 수 있으면 `@Modifying(clearAutomatically = true, flushAutomatically = true)`다. version 부분은
`JpaVersionedBulkUpdateRule`(persistence-jpa testFixtures)이 `:app-bootstrap:architectureTest`에서 강제한다.
- repository는 `CrudRepository`가 아니라 `Repository`를 상속하고, 테넌트 범위의 finder만 내놓는다.
@@ -1,52 +1 @@
# adapter:outbound:persistence-notification — 알림 관계형 영속
## 등록 정보
- 모듈 ID: `adapter-outbound-persistence-notification`. Gradle 경로와 허용 edge는
`src/config/architecture/modules.json`에 있다.
- 이 모듈만 시험: `./gradlew :adapter:outbound:persistence-notification:test --console=plain`.
- 패키지 루트: `dev.caskeleton.adapter.outbound.persistence.notification`. 패키지 규칙은
`persistence-fileserver`와 같아서 두 capability leaf를 같은 방식으로 읽는다:
- `platform.entity` — JPA 행만.
- `platform.repository` — Spring Data 인터페이스와 그것이 돌리는 SQL 글(`RecipientClaimSql`).
- `platform` — store 어댑터(`Jpa*`, `Jdbc*`, inbox의 `JpaNotificationInbox`와 그 outbox 도우미),
`NotificationRecordMapper`, payload codec.
- `configuration` — store를 bean으로 등록하는 자동 구성 창구. leaf 루트에는 scan 설정과 schema stream이 있다.
엔티티 생성자·접근자·변경자는 store가 다른 패키지에서 쓰니 public이다. 엔티티는 leaf를 떠나지 않는다(포트는
record를 싣는다). 가시성이 더는 그것을 말해 주지 않으므로 규칙이 말한다:
`JpaArchitectureRules.entitiesAreUsedOnlyInsideTheirLeaf`를 `JpaProductionArchitectureTest`(app-bootstrap
`architectureTest`)가 운영 그래프에 대고 이 leaf와 `persistence-fileserver`에 돌린다.
## 시험은 어디 있나
| 무엇 | 어디 | 돌리기 |
|---|---|---|
| 단위·배선 시험 | 이 leaf, `src/test` | `:adapter:outbound:persistence-notification:test` |
| 이 store들의 실제 PostgreSQL 시험 | `persistence-jpa`, `src/postgresqlIntegrationTest/.../persistence/notification`(그 lane이 container와 Flyway 배선을 가진다) | `:adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests '<class>'` |
| store가 통과해야 하는 포트 계약 | `application-notification` testFixtures, `*.testkit.*Contract`(preference, suppression, deduplication, request, reconciliation job, admin operation, template registry, recipient lease, recipient delivery, delivery attempt, attempt resolver, delivery projection, provider event ledger, contact point, 그리고 contact point·suppression store 위의 부수 효과) | 메모리 fake(`application-notification` 시험)와 `persistence-jpa`의 `PostgreSql*ContractTest`가 모두 계약을 상속한다. PostgreSQL 쪽은 `jpaPlatformContractTest`가 돌린다 |
| migration 고정 | `persistence-jpa/src/test/resources/db/applied-migrations.sha256` | `:adapter:outbound:persistence-jpa:test`의 `AppliedMigrationImmutabilityTest` |
`application-notification` testFixtures에 계약이 있는 포트의 store는 따로 손으로 쓴 PostgreSQL 시험이 아니라
그 계약의 PostgreSQL 하위 클래스로 시험한다. vendor에 관한 경우(CHECK 제약, bulk update의 `@Version`)는 하위
클래스에 남긴다. 계약이 없는 포트(serving-state 읽기 모델, 동의, inbox)와 그 이유는
`docs/testing/TESTING_STRATEGY.md` 9.2절에 있다.
## 규칙
- **모든 쓰기는 호출자의 트랜잭션에 합류한다.** store 쓰기는 `CallerTransaction.require("<what>")`로
시작한다. 트랜잭션은 유스케이스가 가진다(소유자 결정 2026-09-25).
- **migration**은 `src/main/resources/db/migration/jpa/notification-platform`에 있고 자기 Flyway stream
(`NotificationSchemaStream`, history 테이블 `flyway_jpa_notification_history`)으로 돈다. 적용한 파일은 고치지
않는다: 다음 `V<n>__`를 더하고, 그 SHA-256을 `applied-migrations.sha256`에 고정하고,
`NotificationFixtures.migrations()`에 더한다. 행을 지우는 migration은 어떤 행이 남고 왜인지 SQL 주석에
적는다. 이미 있는 테이블을 잠그는 migration은 `SET LOCAL lock_timeout = '5s';`로 시작한다
(`docs/jpa/migration-guide.md` "Bound the lock wait". persistence-jpa의 `MigrationLockWaitTest`가 그것이 없는
migration을 거절한다).
- **insert냐 update냐는 데이터베이스가 정한다.** 찾은 뒤 insert하지 않는다: `ON CONFLICT (<unique key>) DO
NOTHING`으로 insert하고, 아무것도 insert하지 않았으면 관리되는 엔티티로 있는 행을 update한다
(`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`, `DeduplicationClaims.insertOrFind`). 충돌
대상에는 migration에 unique 제약이 있어야 한다.
- **`@Version` 테이블의 bulk·native `UPDATE`는 version을 올린다**(`version = version + 1`). 호출자가 그 행을 다시
읽을 수 있으면 `@Modifying(clearAutomatically = true, flushAutomatically = true)`다. version 부분은
`JpaVersionedBulkUpdateRule`(persistence-jpa testFixtures)이 `:app-bootstrap:architectureTest`에서 강제한다.
- repository는 `CrudRepository`가 아니라 `Repository`를 상속하고, 테넌트 범위의 finder만 내놓는다.
@AGENTS.md
+1 -1
View File
@@ -73,7 +73,7 @@ executor, operations).
등록된 script(`RedisScriptRegistry`). 서비스가 SDK를 조립하는 곳에서 넘긴다.
패키지 규칙(driver 가두기, 문자열 명령 surface 없음, 트랜잭션과 raw gateway의 불변식)은
`src/adapter/outbound/cache-redis/CLAUDE.md`의 「Redis 런타임과 골라 쓰는 typed SDK」에 있다.
`src/adapter/outbound/cache-redis/AGENTS.md`의 「Redis 런타임과 골라 쓰는 typed SDK」에 있다.
`RedisSdkModuleBoundaryTest`가 강제한다.
## env 키
+42
View File
@@ -0,0 +1,42 @@
# adapter:outbound:support — outbound 공용 지원
## 등록 정보
- 모듈 ID: `adapter-outbound-support`
- Gradle 경로: `:adapter:outbound:support`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:support:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound`와 `dev.caskeleton.adapter.outbound.support`.
## 책임
- 다시 쓰는 outbound correlation, fail-open 의존성 로그, 자동 구성 이음매를 가진다.
- 등록된 messaging·cache·notification·httpclient leaf가 쓰는 기술 지원을 준다.
- 템플릿의 `IntegrationEventEncoderPort`(`messaging/JsonIntegrationEventEncoder`)를 가진다.
`IntegrationEventEncoderAutoConfiguration`이 모든 contract contribution bean 위에 등록하고, 서비스 자신의
인코더가 있으면 물러선다. 여기 있는 이유는 유스케이스가 outbox에 append하기 전에 인코딩하는데, 메시징 모듈을
싣지 않는 조립도 있기 때문이다. 이것은 외부 시스템 프로토콜이 아니라 애플리케이션 자신의 envelope v1
형식이다.
- 디렉터리 descriptor 기준의 로컬 파일 시스템 기본 장치(`filesystem/SecureDirectoryWalk`,
`filesystem/SecureFileAccess`)를 가진다: root 아래에서 디렉터리 descriptor를 하나씩 따라가며
`NOFOLLOW_LINKS`로 열기, 만들기, 지우기, stat, 옮기기를 하고, symbolic 경로 요소와 바깥으로 나가기를 타입 있는
`IOException`으로 거절한다. 저장 capability가 그것을 자기 실패 어휘로 바꾼다(파일 서버의
`LocalStorageFailures`). 여기는 오류 코드를 모른다.
- 유일한 엄격 설정 바인딩 `StrictSettingsBinder`를 가진다. inbound leaf가 쓸 수 있는 유일한 support
클래스이기도 하다: `adapter:inbound:web`이 이것으로 `app.security`를 바인딩한다(registry edge와 클래스 이름을
댄 ArchUnit 예외, 2026-11-01부터). 타입에 있는 설정의 빈 값(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`)은
설정 안 함으로 바인딩한다. 타입에 없는 이름 아래의 빈 값은 계속 거절한다(2026-11-03에 정함).
- 기능 전용 client와 라우팅 정책은 그것을 가진 leaf에 둔다.
## 경계
- 허용 프로젝트 의존은 registry가 가진다: application, domain, shared 계약.
- inbound 전송, 영속, bootstrap, 샘플 의존이 없다.
- 업무 규칙이나 특정 외부 시스템 프로토콜 구현이 없다.
## 테스트
지원 동작은 이 모듈만 보는 단위 시험으로 본다. 시험할 계약이 설정 배선 자체가 아니면 Spring application
context를 띄우지 않는다.
+1 -42
View File
@@ -1,42 +1 @@
# adapter:outbound:support — outbound 공용 지원
## 등록 정보
- 모듈 ID: `adapter-outbound-support`
- Gradle 경로: `:adapter:outbound:support`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:support:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.adapter.outbound`와 `dev.caskeleton.adapter.outbound.support`.
## 책임
- 다시 쓰는 outbound correlation, fail-open 의존성 로그, 자동 구성 이음매를 가진다.
- 등록된 messaging·cache·notification·httpclient leaf가 쓰는 기술 지원을 준다.
- 템플릿의 `IntegrationEventEncoderPort`(`messaging/JsonIntegrationEventEncoder`)를 가진다.
`IntegrationEventEncoderAutoConfiguration`이 모든 contract contribution bean 위에 등록하고, 서비스 자신의
인코더가 있으면 물러선다. 여기 있는 이유는 유스케이스가 outbox에 append하기 전에 인코딩하는데, 메시징 모듈을
싣지 않는 조립도 있기 때문이다. 이것은 외부 시스템 프로토콜이 아니라 애플리케이션 자신의 envelope v1
형식이다.
- 디렉터리 descriptor 기준의 로컬 파일 시스템 기본 장치(`filesystem/SecureDirectoryWalk`,
`filesystem/SecureFileAccess`)를 가진다: root 아래에서 디렉터리 descriptor를 하나씩 따라가며
`NOFOLLOW_LINKS`로 열기, 만들기, 지우기, stat, 옮기기를 하고, symbolic 경로 요소와 바깥으로 나가기를 타입 있는
`IOException`으로 거절한다. 저장 capability가 그것을 자기 실패 어휘로 바꾼다(파일 서버의
`LocalStorageFailures`). 여기는 오류 코드를 모른다.
- 유일한 엄격 설정 바인딩 `StrictSettingsBinder`를 가진다. inbound leaf가 쓸 수 있는 유일한 support
클래스이기도 하다: `adapter:inbound:web`이 이것으로 `app.security`를 바인딩한다(registry edge와 클래스 이름을
댄 ArchUnit 예외, 2026-11-01부터). 타입에 있는 설정의 빈 값(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT=`)은
설정 안 함으로 바인딩한다. 타입에 없는 이름 아래의 빈 값은 계속 거절한다(2026-11-03에 정함).
- 기능 전용 client와 라우팅 정책은 그것을 가진 leaf에 둔다.
## 경계
- 허용 프로젝트 의존은 registry가 가진다: application, domain, shared 계약.
- inbound 전송, 영속, bootstrap, 샘플 의존이 없다.
- 업무 규칙이나 특정 외부 시스템 프로토콜 구현이 없다.
## 테스트
지원 동작은 이 모듈만 보는 단위 시험으로 본다. 시험할 계약이 설정 배선 자체가 아니면 Spring application
context를 띄우지 않는다.
@AGENTS.md
+1 -1
View File
@@ -6,7 +6,7 @@
허용/금지 의존 정책은 `src/build.gradle` 의
`allowedProjectDependencies['adapter:outbound:support']` 항목이 SSOT 다(이 모듈은 아직 별도
CLAUDE.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용
AGENTS.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용
기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다.
## 왜 별도 모듈인가
+121
View File
@@ -0,0 +1,121 @@
# app-bootstrap — 애플리케이션 진입점과 조립 루트
## 등록 정보
- 모듈 ID: `app-bootstrap`
- Gradle 경로: `:app-bootstrap`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.bootstrap`.
## 책임
- Spring Boot 진입점(`CaSkeletonApplication`).
- 런타임 설정과 로깅 시작.
- 모듈을 가로지르는 마지막 배선.
- 모든 모듈을 들여다보는 아키텍처 시험.
## 허용
- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle
runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다.
- Spring Boot 시작·런타임 의존성.
- 시험에서 ArchUnit.
## 금지
- 구체적인 업무 정책.
- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper.
- 업무 로직을 구현하는 설정 클래스.
- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게
설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 —
`CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다.
- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures`
(`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` /
`requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그
필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다.
- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는
`dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다.
- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에
둔다. `docs/testing/TESTING_STRATEGY.md`를 본다.
## 패키지 배치
아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다
(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/`
아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능
패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은
설정 아홉 개로, Redis는 376줄 클래스 하나로.
- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가
등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략,
lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는
`adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은
`composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한
`runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability
목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다.
component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`,
`WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support
(`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure/<name>/`에
남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay,
멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은
`composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각
`runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의
role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults`
파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context
전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다.
- **`<Capability>Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는
어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다.
이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가
없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸
수 없는 값을 거절한다.
- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출,
여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에
대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그
capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다.
- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외,
`StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`).
그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는
`StartupFailureExceptionReporter`만 남는다.
- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한
`StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적
`RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든
profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩
만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에
`@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백,
`@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다
먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영
비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고,
`SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다.
## 분해 기준
취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다.
- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로
관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다.
- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다.
- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건,
`@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다:
조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다.
`cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional
어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의
`NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의
`NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는
`adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`,
`PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에
없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`).
Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health
bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다.
- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 —
`cache-redis`의 `capability/RedisKeys`가 참조 예다.
## 테스트
```bash
cd src
./gradlew :app-bootstrap:test
./gradlew verifyCleanArchitectureDependencies
```
+1 -121
View File
@@ -1,121 +1 @@
# app-bootstrap — 애플리케이션 진입점과 조립 루트
## 등록 정보
- 모듈 ID: `app-bootstrap`
- Gradle 경로: `:app-bootstrap`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :app-bootstrap:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.bootstrap`.
## 책임
- Spring Boot 진입점(`CaSkeletonApplication`).
- 런타임 설정과 로깅 시작.
- 모듈을 가로지르는 마지막 배선.
- 모든 모듈을 들여다보는 아키텍처 시험.
## 허용
- 이 모듈의 Gradle 의존성이 분명히 선언하고 아키텍처 registry가 허용한 런타임 leaf. 해석된 Gradle
runtime 그래프가 런타임의 정본이다. 구성원 목록을 metadata에 다시 적지 않는다.
- Spring Boot 시작·런타임 의존성.
- 시험에서 ArchUnit.
## 금지
- 구체적인 업무 정책.
- bootstrap 아래에 직접 쓴 controller, 유스케이스, repository 어댑터, mapper.
- 업무 로직을 구현하는 설정 클래스.
- `application-core`나 `domain-core` 포트를 구현하기. 포트를 구현하는 클래스는 의존성을 어떻게
설정했든 outbound 어댑터이고 `adapter/outbound/*` leaf에 둔다 —
`CompositionRootBoundaryArchitectureTest`가 예외 없이 강제한다.
- 기동 실패를 `throw new IllegalStateException(...)`으로 내기. `StartupFailures`
(`adapter:outbound:support`, 패키지 `support.startup`: `envValidation` / `profileMismatch` /
`requiredAdapterDisabled` / `migrationFailed`)를 써서 실패가 sysexits 종료 코드와 구조화된 로그
필드를 싣게 한다 — `StartupFailureContractArchitectureTest`가 강제한다.
- 「운영 환경인가?」를 이 모듈 안에서 답하기. 저장소 전체의 profile 어휘는
`dev.caskeleton.shared.runtime.RuntimeEnvironment`가 가진다.
- `src/test`에서 `org.testcontainers`에 의존하기. 실제 서비스를 쓰는 시험은 `src/integrationTest`에
둔다. `docs/testing/TESTING_STRATEGY.md`를 본다.
## 패키지 배치
아래 규칙은 그것이 없어서 이 모듈의 리뷰 대상이 된 어긋남이 생겼기 때문에 있다
(`docs/reviews/2026-09-07-app-bootstrap-module-code-review.md`). capability의 절반은 `autoconfigure/`
아래, 절반은 패키지 루트에 있었다. `Settings` 클래스는 규칙 없이 `settings/` 패키지와 각 기능
패키지에 나뉘어 있었다. 그리고 같은 분해 문제를 같은 leaf에서 두 가지로 풀었다 — Notification은 작은
설정 아홉 개로, Redis는 376줄 클래스 하나로.
- **capability의 조립은 그 capability 자신의 모듈에 있다.** 그 모듈의 `AutoConfiguration.imports`가
등록하고, 설정은 그 모듈의 `config/module-defaults/*.yml`에 둔다. JPA(기동 guard, Flyway 전략,
lock decorator, readiness, `JpaActivationEnvironmentPostProcessor`의 완전히 끄기 처리)는
`adapter:outbound:persistence-jpa`, Redis(readiness)는 `adapter:outbound:cache-redis`, 알림은
`composition:notification-platform`이다. 모든 capability는 `build.gradle`에서 주석 처리한
`runtimeOnly` 한 줄이다. 기본 조립은 web, 관측, core들, support, identifier다. 이 leaf는 capability
목록을 두지 않는다: 스위치 registry도, capability 사이 의존 검증기도, 켜기 endpoint도 없다.
component scan은 `dev.caskeleton.bootstrap`만 본다. web(`WebAdapterAutoConfiguration`,
`WebSecurityAutoConfiguration`, `WebMethodSecurityAutoConfiguration`)과 support
(`OutboundSupportConfig`)는 자기 `AutoConfiguration.imports`로 들어온다. `autoconfigure/<name>/`에
남는 것은 모든 애플리케이션에 필요한 애플리케이션 조립인 `common`(시계)뿐이다. outbox relay,
멱등성 executor, durable operation(유스케이스와 `/operations` endpoint. 2026-11-01 성숙도 리뷰 뒤로 bootstrap 밖)은
`composition:outbox-relay`, `composition:idempotency`, `composition:durable-operation`이다. 각각
`runtimeOnly` 한 줄로 고르고, 자기 포트가 생기기 전에는 아무것도 만들지 않는다. capability의
role → permission 대응은 `config/security.yml`이 아니라 그 capability의 `config/module-defaults`
파일에 담긴다. 모든 조립 루트에 필요한 런타임 배선 — tracing, metric 계약 filter, domain-context
전파, 사용자 principal 가명화(`PrivacySettings`), actuator chain — 은 `composition:service-runtime`이다.
- **`<Capability>Settings`는 `settings/`가 아니라 그 capability 옆에 둔다.** `settings/` 패키지는
어느 capability에도 속하지 않는 설정 — `BootstrapSettings`, `RuntimeSafetySettings` — 만 담는다.
이 설정은 `StrictSettingsBinder`로 엄격하게 바인딩하고 scan하지 않는다. 로깅에는 settings record가
없다. `logback-spring.xml`이 `app.logging.*`을 직접 읽고 `LoggingConfigurationRule`이 Logback이 쓸
수 없는 값을 거절한다.
- **`runtime/`은 애플리케이션 자체에 대한 guard를 담는다** — 비밀 값, 숫자 한계, 오류 상세 노출,
여러 인스턴스 조율, runtime profile 검사(`RuntimeEnvironmentProfileValidator`). capability 설정에
대한 guard(JPA OSIV·DDL·pool·TLS·vendor guard, Mongo 연결 출처 규칙, GraphQL 배포 모드 규칙)는 그
capability의 모듈과 함께 나간다. 그래야 capability가 있을 때만 정확히 존재한다.
- **기동 실패 어휘는 `adapter:outbound:support`에 있다**(`support.startup`: phase, 오류 코드, 예외,
`StartupFailures`, `StartupValidationContext`, `StartupOrder`, `ReadinessGroup`, `RuntimeWarnings`).
그래서 capability 모듈은 이 leaf에 의존하지 않고 같은 방식으로 실패한다. `runtime/startup/`에는
`StartupFailureExceptionReporter`만 남는다.
- **환경만 보는 guard는 `StartupRule` bean이다**(`support.startup`). 위반을 돌려주고, 유일한
`StartupRuleRunner`가 다른 singleton이 생기기 전에 그것을 올린다(`Environment`, bean factory, 정적
`RequiredProductionSecrets`의 `ObjectProvider`만 받는 `static` `@Bean` 메서드로 선언한다. 모든
profile에서 runner는 어떤 규칙을 돌리기 전에 규칙마다, 그리고 `RequiredProductionSecrets`마다 하나씩
만든다. 그중 하나가 만드는 다른 bean이 있으면 그 이름을 대며 기동을 실패시킨다. runtime 클래스에
`@Value`/`@Autowired`/`@Inject`/`@Resource` 멤버, `@PostConstruct`/`@PreDestroy` 콜백,
`@ConfigurationProperties` 바인딩이 있는 것도 이름을 대며 실패시킨다 — 그런 것은 post-processor보다
먼저 만들어져 값이 비어 있게 된다). 다른 bean이 필요한 guard는 bean으로 남는다. capability의 운영
비밀 값은 그 capability의 것이다: 그 모듈이 `RequiredProductionSecrets` bean을 내놓고,
`SecretSourceValidator`는 어떤 role이 있는지 모르는 채로 이름을 검사한다.
## 분해 기준
취향에 맡기지 않고 적어 둔다. 「충분히 길다고 느꼈다」가 같은 질문에 두 가지 답을 낳았기 때문이다.
- `@Configuration` 하나는 조립 관심사 하나를 담는다. 대략 **`@Bean` 메서드 여덟 개**를 넘거나, 서로
관계없는 포트 묶음 둘을 조립하게 되면 — 둘 중 먼저 오는 때에 — 나눈다.
- `@ConfigurationProperties` 클래스 하나는 capability namespace 하나를 가진다.
- 설정이 둘 이상 필요한 capability는 루트 클래스를 둔다. 루트가 `enabled` 조건,
`@EnableConfigurationProperties`, 관심사별 클래스의 `@Import`를 가진다. 아무것도 scan하지 않는다:
조건이 걸린 루트에서 `@Import`해야 `enabled=false`가 권고가 아니라 실제로 끄는 스위치가 된다.
`cache-redis`의 `capability/RedisCapabilityConfig`가 참조 예다. 다시 쓸 Spring 조립을 가진 optional
어댑터 capability는 자기 루트를 내놓는다. 알림은 `adapter:outbound:notification`의
`NotificationPlatformAutoConfiguration`과 `composition:notification-platform`의
`NotificationApplicationCompositionAutoConfiguration`을 쓴다. JPA는
`adapter:outbound:persistence-jpa`의 package-private `PersistenceJpaAutoConfiguration`,
`PersistenceJpaRuntimeConfig`, `startup.JpaStartupAutoConfiguration`을 쓰고, 이 모듈은 기본 조립에
없다(`build.gradle`의 `// runtimeOnly project(':adapter:outbound:persistence-jpa')`).
Mongo도 같은 규칙을 따른다: persistence-mongo leaf가 MongoRootAutoConfiguration과 그 내부 health
bridge를 가지고, bootstrap은 Mongo 전용 운영 health 설정을 가지지 않는다.
- 나눈 capability의 공용 도우미는 `*Util` 바구니가 아니라 하는 일을 이름으로 단 자기 타입을 가진다 —
`cache-redis`의 `capability/RedisKeys`가 참조 예다.
## 테스트
```bash
cd src
./gradlew :app-bootstrap:test
./gradlew verifyCleanArchitectureDependencies
```
@AGENTS.md
+2 -2
View File
@@ -5,7 +5,7 @@
이 모듈은 비즈니스 로직을 담지 않는다. Spring Boot 기동, 런타임 설정 바인딩, 기본 runtime
모듈 간 최종 와이어링, 그리고 composition classpath를 대상으로 한 중앙 아키텍처 테스트만 둔다.
모든 leaf의 프로젝트 edge는 JSON registry를 읽는 Gradle 방향 게이트가 별도로 검사한다. 허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**의
SSOT 는 [CLAUDE.md](CLAUDE.md) 다.
SSOT 는 [AGENTS.md](AGENTS.md) 다.
기본 composition의 SSOT는 `build.gradle`의 실제 project dependency graph다. registry는 runtime
membership 목록을 두지 않는다. `allowed_dependencies` 밖의 project는 방향 게이트가 막는다.
@@ -417,7 +417,7 @@ relay 조립(`OutboxRelayAutoConfiguration`, 스케줄러·metrics·leader token
## build.gradle — 의존성 구성 근거
app-bootstrap 은 합성 루트라 "왜 이 의존성이, 왜 이 scope 로" 결정이 많다. 빌드 파일에는 한 줄
요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 **api vs implementation 정책**(CLAUDE.md):
요약만 두고, 비자명한 근거는 여기에 모은다. 바탕 원칙은 **api vs implementation 정책**(AGENTS.md):
모듈 간 의존은 기본 `implementation`이라 transitive 로 새지 않는다 — 그래서 테스트에서 그 타입이
필요하면 여기서 **명시적으로** 다시 선언한다.
@@ -14,7 +14,7 @@ import org.junit.jupiter.api.Test;
/**
* Freezes what is left of the Fileserver's exemption from the inbound use-case contract.
*
* <p>{@code application-core/CLAUDE.md} requires every inbound port implementation to extend {@code
* <p>{@code application-core/AGENTS.md} requires every inbound port implementation to extend {@code
* CommandUseCase} or {@code QueryUseCase} and to declare {@code @UseCaseCapability}. The ArchUnit
* rules that enforce it only match types that implement {@link UseCase}; a service that never does
* is invisible to them.
@@ -121,7 +121,7 @@ class ForbiddenApiArchitectureTest {
+ root
+ " lives in one of the listed operational contract packages, and the root holds"
+ " only its package-info; a business or domain concept belongs to the module that"
+ " owns it (shared-contract CLAUDE.md)")
+ " owns it (shared-contract AGENTS.md)")
.allowEmptyShould(true);
}
@@ -10,7 +10,7 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
/**
* Naming convention enforcement — the machine-checkable subset of the naming table in {@code
* src/application-core/CLAUDE.md} ("Naming convention"), which is the rule book.
* src/application-core/AGENTS.md} ("Naming convention"), which is the rule book.
*
* <p>This test enforces only the rules that ArchUnit can decide reliably (N6 configuration binding,
* I5 throwables, and the two package-ownership rules beside that table). The rest of that table —
@@ -55,7 +55,7 @@ class NamingConventionTest {
// Package ownership — a business feature package does not take a template package's name. The
// template's own packages are listed in TemplatePackageOwnership (machine copy of the "Package
// ownership" table in src/application-core/CLAUDE.md); everything else under the two roots is a
// ownership" table in src/application-core/AGENTS.md); everything else under the two roots is a
// feature, so a derived service adds features without editing the list. A feature always has a
// domain package (docs/manual/03-placement.md ①), which is where a feature named after an
// application template package — `operation`, `lock`, `cache` — shows up.
@@ -110,7 +110,7 @@ class TemplatePackageOwnershipRuleTest {
.as(
"a name in TemplatePackageOwnership.APPLICATION_PACKAGES that no longer exists was"
+ " renamed or removed without the list (and the table in"
+ " src/application-core/CLAUDE.md) following it")
+ " src/application-core/AGENTS.md) following it")
.containsAll(TemplatePackageOwnership.APPLICATION_PACKAGES.keySet());
assertThat(domain)
.as("TemplatePackageOwnership.DOMAIN_PACKAGES names a package that no longer exists")
@@ -15,7 +15,7 @@ import java.util.TreeSet;
* owns each, and which packages are a service's business features.
*
* <p>This is the machine copy of the "Package ownership" tables in {@code
* src/application-core/CLAUDE.md}, which are the rule book. A template change that adds, renames,
* src/application-core/AGENTS.md}, which are the rule book. A template change that adds, renames,
* moves or removes one of these packages changes the table and this class together. Two tests hold
* them to it: {@code TemplatePackageOwnershipDocumentTest} (document-contract lane, main stage)
* fails when the table and this class differ in a name or an owning leaf, or when a listed package
@@ -107,7 +107,7 @@ record TemplatePackageOwnership(String applicationRoot, String domainRoot) {
+ name.get()
+ "', a name the template already uses. A feature beside a template package"
+ " of the same name merges into the same tree on every upstream update."
+ " Rename the feature (template packages: src/application-core/CLAUDE.md"
+ " Rename the feature (template packages: src/application-core/AGENTS.md"
+ " \"Package ownership\")."));
}
}
@@ -19,7 +19,7 @@ import org.junit.jupiter.api.Test;
/**
* The template package list exists twice — the "Package ownership" tables in {@code
* src/application-core/CLAUDE.md}, which people and agents read, and {@link
* src/application-core/AGENTS.md}, which people and agents read, and {@link
* TemplatePackageOwnership}, which the architecture rules read — and nothing held the two together
* (original review 2026-11-01 §16.3). Changing either one alone fails here: a name or an owning
* leaf that differs, or a listed package that is not in the leaf the table says owns it.
@@ -29,7 +29,7 @@ import org.junit.jupiter.api.Test;
@Tag("document-contract")
class TemplatePackageOwnershipDocumentTest {
private static final String RULE_BOOK = "src/application-core/CLAUDE.md";
private static final String RULE_BOOK = "src/application-core/AGENTS.md";
private static final String REGISTRY = "src/config/architecture/modules.json";
private static final String APPLICATION_TABLE = "| 패키지 (`dev.caskeleton.application.*`) |";
private static final String DOMAIN_TABLE = "| 패키지 (`dev.caskeleton.domain.*`) |";
@@ -34,7 +34,7 @@ import org.junit.jupiter.api.Test;
*
* <p>So the rule is one-directional and mechanical: a vendor library named in a public or protected
* signature is declared {@code api}; one used only behind private members stays {@code
* implementation}. {@code src/platforms/messaging/CLAUDE.md} states it as policy — this holds it to
* implementation}. {@code src/platforms/messaging/AGENTS.md} states it as policy — this holds it to
* the source so the two cannot drift.
*
* <p>The libraries checked are the ones an adopter would otherwise have to reverse-engineer into
@@ -3,7 +3,7 @@ package dev.caskeleton.onboarding.domain.feature;
/**
* Aggregate-level persistence for {@link FeatureAggregate}. The domain owns it because it stores
* and returns whole aggregates — the {@code *Repository} side of the naming rule in {@code
* application-core/CLAUDE.md}; a technical store the application owns is a {@code *StorePort}.
* application-core/AGENTS.md}; a technical store the application owns is a {@code *StorePort}.
*/
public interface FeatureAggregateRepository {
+336
View File
@@ -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
View File
@@ -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
+1 -1
View File
@@ -3,7 +3,7 @@
애플리케이션 유스케이스 계층. 패키지 루트: `dev.caskeleton.application`.
허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 **모듈 규칙**은
[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
[AGENTS.md](AGENTS.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도
추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다.
+19
View File
@@ -0,0 +1,19 @@
# composition:outbox-relay
- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본:
`src/config/architecture/modules.json`.
- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한
바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연
tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric
(`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다.
- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`,
`OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging
줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다
(`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다.
- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우
(`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다.
- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰
고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는
`:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다.
- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`,
`docs/runbooks/outbox-dead-letter.md`.
+1 -19
View File
@@ -1,19 +1 @@
# composition:outbox-relay
- 모듈 ID `composition-outbox-relay`, Gradle 경로 `:composition:outbox-relay`. registry 정본:
`src/config/architecture/modules.json`.
- 책임: 애플리케이션의 outbox relay를 조립하고 돌린다. `app.outbox.*`(`OutboxSettings`, 엄격한
바인딩)로 `PublishPendingOutboxEventsUseCase`를 손으로 만들고, `OutboxRelayScheduler`(고정 지연
tick, 메시징 플랫폼의 admission phase보다 위에서 멈추는 `SmartLifecycle`)에서 돌리며, outbox metric
(`OutboxMetrics`: 자기 스레드에서 도는 gauge, relay가 내는 cycle 결과 counter)을 가진다.
- 경계: 포트만 이름으로 댄다 — `OutboxStorePort`, `OutboxMessagePublishPort`,
`OutboxRelayFailureReportPort`, `TransactionPort`. 모듈 타입은 대지 않으니 persistence나 messaging
줄을 지우면 relay도 빠진다. 업무 규칙, SQL, broker 타입이 없다. relay 유스케이스는 bean이 아니다
(`@SystemInvoked`, 권한 검사 없음). 허용 edge는 registry 항목에서만 온다.
- 기동 거절은 여기 있다. 설정과 포트가 만나는 곳이 여기뿐이기 때문이다: 최악의 경우
(`batch-size` × 발행 포트의 `longestAttempt`)가 `in-flight-timeout`에 닿는 batch는 기동에 실패한다.
- 시험: `./gradlew :composition:outbox-relay:check`. 종료 순서는 플랫폼 자신의 phase 상수에 맞춰
고정한다(`OutboxRelayShutdownOrderTest`). relay → bridge → 실제 Kafka로 가는 끝에서 끝까지 경로는
`:adapter:outbound:messaging-kafka:messagingKafkaRelayIntegrationTest`다.
- 설계와 버린 대안: `README.md`. 운영: `docs/runbooks/outbox-publish-failed.md`,
`docs/runbooks/outbox-dead-letter.md`.
@AGENTS.md
+38
View File
@@ -0,0 +1,38 @@
# domain-core — 순수 도메인 계층
## 등록 정보
- 모듈 ID: `domain-core`
- Gradle 경로: `:domain-core`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.domain`.
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
## 책임
- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스.
- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트.
- 도메인 불변식과 핵심 규칙.
## 허용
- Java 표준 라이브러리.
- 값만 담은 공용 운영 타입은 정말 필요할 때만.
## 금지
- Spring 애너테이션.
- JPA 애너테이션.
- Servlet·HTTP 타입.
- 어댑터, application, bootstrap, 표현 계층 DTO 의존.
## 테스트
```bash
cd src
./gradlew :domain-core:test
```
+1 -38
View File
@@ -1,38 +1 @@
# domain-core — 순수 도메인 계층
## 등록 정보
- 모듈 ID: `domain-core`
- Gradle 경로: `:domain-core`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :domain-core:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.domain`.
코드 주석에서 덜어낸 **설계 결정의 근거**는 [README.md](README.md) 가 모아둔다 (이 문서는 모듈 규칙 SSOT).
## 책임
- 업무 개념, 엔티티, 값 객체, enum, 도메인 이벤트, 도메인 서비스.
- 이 참조 구현이 아직 도메인 소유 영속 계약을 두는 곳의 repository 포트.
- 도메인 불변식과 핵심 규칙.
## 허용
- Java 표준 라이브러리.
- 값만 담은 공용 운영 타입은 정말 필요할 때만.
## 금지
- Spring 애너테이션.
- JPA 애너테이션.
- Servlet·HTTP 타입.
- 어댑터, application, bootstrap, 표현 계층 DTO 의존.
## 테스트
```bash
cd src
./gradlew :domain-core:test
```
@AGENTS.md
+1 -1
View File
@@ -2,7 +2,7 @@
순수 도메인 계층 모듈. 패키지 루트: `dev.caskeleton.domain`.
허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**은 [CLAUDE.md](CLAUDE.md) 가 SSOT 다.
허용/금지 의존, 책임 범위, 테스트 명령 같은 **모듈 규칙**은 [AGENTS.md](AGENTS.md) 가 SSOT 다.
이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다
"왜 이렇게 했나"가 궁금할 때 본다. 플랜/스펙 추적용 ID는
더 이상 코드 주석에 두지 않고, 그 근거를 아래에 쉬운 말로 풀어 둔다.
+88
View File
@@ -0,0 +1,88 @@
# grpc-advanced — 고급 gRPC capability의 지역 정본
이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
`src/config/architecture/modules.json`이 SSOT다. 루트 `AGENTS.md`와 충돌하면
루트가 이긴다.
이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는
불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다.
## 의존 방향
```text
grpc-advanced:* → grpc:* (허용)
grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
```
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/AGENTS.md`의
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
## Capability grade와 feature flag
capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는
결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기
때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다.
| grade | 시작 가능 | production 추가 승인 |
| --- | --- | --- |
| `ADVANCED_STABLE` | O | 불필요 |
| `EXPERIMENTAL` | O | **필요** |
| `WATCH` | X (추적만) | — |
| `DISABLED` | X | — |
property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off다.
`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을
구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.
## Leaf별 담당 capability
| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability |
| --- | --- | --- |
| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control |
| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 |
| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지
다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별
독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지
않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다.
## Promotion은 capability별로 독립이다
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
리뷰 규칙이다.
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
## 이 저장소에서 검증할 수 없는 것
capability별로 필요한 실제 인프라가 이 저장소에 없다.
- `grpc-web` → gRPC-Web 프록시
- `servlet-compat` → Servlet 컨테이너
- `xds` → 중지 가능한 xDS control plane
- `kotlin` → Kotlin 툴체인
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit`
등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.
## 금지
- Stable leaf(`grpc:*`)가 이 family를 참조하는 것.
- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
- `WATCH` capability를 스키마 소스로 사용하는 것.
- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.
+1 -88
View File
@@ -1,88 +1 @@
# grpc-advanced — 고급 gRPC capability의 지역 정본
이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
`src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면
root가 이긴다.
이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는
불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다.
## 의존 방향
```text
grpc-advanced:* → grpc:* (허용)
grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
```
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
## Capability grade와 feature flag
capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는
결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기
때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다.
| grade | 시작 가능 | production 추가 승인 |
| --- | --- | --- |
| `ADVANCED_STABLE` | O | 불필요 |
| `EXPERIMENTAL` | O | **필요** |
| `WATCH` | X (추적만) | — |
| `DISABLED` | X | — |
property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off다.
`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을
구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.
## Leaf별 담당 capability
| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability |
| --- | --- | --- |
| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control |
| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 |
| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지
다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별
독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지
않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다.
## Promotion은 capability별로 독립이다
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
리뷰 규칙이다.
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
## 이 저장소에서 검증할 수 없는 것
capability별로 필요한 실제 인프라가 이 저장소에 없다.
- `grpc-web` → gRPC-Web 프록시
- `servlet-compat` → Servlet 컨테이너
- `xds` → 중지 가능한 xDS control plane
- `kotlin` → Kotlin 툴체인
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit`
등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.
## 금지
- Stable leaf(`grpc:*`)가 이 family를 참조하는 것.
- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
- `WATCH` capability를 스키마 소스로 사용하는 것.
- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.
@AGENTS.md
+192
View File
@@ -0,0 +1,192 @@
# grpc — gRPC 플랫폼 family의 지역 정본
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된
`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
루트 `AGENTS.md`와 충돌하면 루트가 이긴다.
이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은
자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은
`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다.
설계 근거와 원본 계획 대비 deviation은
[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다.
## Family와 framework 규칙
leaf의 정확한 id는 registry에서 읽는다.
| Family | 역할 | 허용 framework |
| --- | --- | --- |
| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 |
| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 |
| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 |
| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 |
| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** |
| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 |
| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 |
`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와
실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이
전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은
`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다.
기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고,
server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두
그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면
기동을 거부한다.
`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이
family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표).
`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
같은 규칙인지 함께 본다.
## 증거 등급 — testkit이 하나의 leaf인 이유
원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를
네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test
lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date
결과를 제공하지 않는다).
`grpc-testkit`의 네 lane과 그 태그:
| lane | 태그 | 증명하는 것 |
| --- | --- | --- |
| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay |
| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain |
| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream |
| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget |
lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임
체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다.
**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은
release path의 flaky gate가 되고, flaky gate는 꺼진다.
## Stable 범위
Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming,
hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며
capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가
등록되면 startup을 거부한다.
`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의
`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
## Optional build에 있다는 것의 의미
`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반
`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는
`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
명시적으로 dependency를 가져오는 별도 변경이 필요하다.
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가
별도로 정의한다.
## application이 이 family에 도달하는 경로
`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
```text
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
```
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의
`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다.
starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 —
starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation
ledger adoption」).
## 테스트 명령
focused test는 registry의 `gradle_path`에서 파생한다.
```bash
cd src
./gradlew -p platforms/optional-build :grpc:<leaf>:test --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain
```
## 금지
- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용.
- Stable leaf에서 `:grpc-advanced:*` 참조.
- `grpc-testkit`을 production leaf가 의존하는 것.
- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다).
- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것
(`GrpcMetricCardinalityPolicy`가 거부한다).
### 채택할 때의 관측 게이트
`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지
않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의
`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
이름을 저장소가 인증한 metric처럼 내세우지 않는다.
### durable operation 원장 채택
`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable
operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고,
`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway
위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다.
원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다.
| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 |
| --- | --- | --- |
| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 |
| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 |
| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 |
기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고,
주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL
(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서
`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다.
**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는
(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에
적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서
온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게
했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다:
바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의
중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가
필요한 메서드가 그것을 필요로 할 때 키가 된다.
**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지
않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은
별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가
아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor
(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기
typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서
`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온
`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는
무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004).
**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난
끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을
예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든
배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다).
지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만
테이블이 끝없이 커진다.
커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두
이유는 모두 ADR-GRPC-004에 있다.
+1 -192
View File
@@ -1,192 +1 @@
# grpc — gRPC 플랫폼 family의 지역 정본
이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된
`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다.
이 family는 Clean Architecture의 계층이 아니라 **벤더드 RPC 플랫폼**이다 — `messaging:*`와 같은
자리에 있고 같은 이유로 있다. 자기 API(port)와 adapter와 조립 경계(starter)를 가지며, 애플리케이션은
`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다.
설계 근거와 원본 계획 대비 deviation은
[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다.
## Family와 framework 규칙
leaf의 정확한 id는 registry에서 읽는다.
| Family | 역할 | 허용 framework |
| --- | --- | --- |
| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 |
| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 |
| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 |
| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 |
| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** |
| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 |
| `grpc-testkit` | in-process / 실제 Netty / fault / performance 인증 | io.grpc netty-shaded, inprocess. production leaf가 의존하지 않는다 |
`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와
실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이
전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은
`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다.
기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고,
server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두
그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면
기동을 거부한다.
`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이
family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표).
`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
같은 규칙인지 함께 본다.
## 증거 등급 — testkit이 하나의 leaf인 이유
원본 계획은 testkit을 core/in-process/netty/fault 4개 모듈로 쪼갠다. 목적은 "in-process 결과를
네트워크 증거로 오해하지 않게 한다"이고, 이 저장소는 그 목적을 모듈 경계가 아니라 **strict test
lane**으로 표현한다(`ca.strict-test-lane`: lane은 아무것도 실행하지 않으면 실패하고 up-to-date
결과를 제공하지 않는다).
`grpc-testkit`의 네 lane과 그 태그:
| lane | 태그 | 증명하는 것 |
| --- | --- | --- |
| `grpcInProcessContractTest` | `grpc-inprocess` | adapter, interceptor 순서, status, validation, idempotency replay |
| `grpcNettyContractTest` | `grpc-netty` | 실제 소켓 위의 HTTP/2, TLS/mTLS, metadata·message hard limit, GOAWAY, drain |
| `grpcFaultTest` | `grpc-fault` | 각 증거 경계에서의 연결 손실, completion unknown, partial stream |
| `grpcPerformanceTest` | `grpc-performance` | latency percentile, saturation, drain budget |
lane 분리만으로는 리포트가 잘못된 run을 인용하는 것을 막지 못하므로 `GrpcEvidenceGrade`가 런타임
체크로 이를 붙든다: `CONTRACT` 등급으로 `tls`를 주장하면 예외다.
**performance lane은 기본 `test`에서 제외된다**(leaf `build.gradle`). 공유 CI runner에서의 측정은
release path의 flaky gate가 되고, flaky gate는 꺼진다.
## Stable 범위
Stable RPC 유형은 **Unary와 Server Streaming뿐**이다. Client Streaming, Bidirectional Streaming,
hedging, xDS, custom resolver/LB, gRPC-Web, Servlet, Reactor, Kotlin은 전부 `grpc-advanced:*`이며
capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog에 streaming method가
등록되면 startup을 거부한다.
`grpc-spring-boot-starter`는 어떤 advanced module도 참조하지 않는다. registry의
`allowed_dependencies`와 `verifyCleanArchitectureDependencies`가 이를 build time에 강제한다.
## Optional build에 있다는 것의 의미
`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반
`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는
`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
명시적으로 dependency를 가져오는 별도 변경이 필요하다.
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위는 release gate와 support matrix가
별도로 정의한다.
## application이 이 family에 도달하는 경로
`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
```text
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
```
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
직접 닿지 않는 규칙은 app-bootstrap ArchUnit(`INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`)이
검사한다. 현재 `adapter:inbound:grpc`는 이 family에 의존하지 않는다 — registry의
`allowed_dependencies`를 보라. 배선은 별도 결정이며, 그때 registry edge와 브리지가 함께 들어간다.
starter가 `operation-ledger-enabled=true`일 때 멱등성 판단 bean을 조립하는 것(03-11)은 이 배선이 아니다 —
starter는 서버를 만들지 않고, 그 bean을 서버에 붙이는 일은 채택하는 쪽의 몫이다(아래 「Durable operation
ledger adoption」).
## 테스트 명령
focused test는 registry의 `gradle_path`에서 파생한다.
```bash
cd src
./gradlew -p platforms/optional-build :grpc:<leaf>:test --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain
```
## 금지
- `grpc-core-api`에서 io.grpc / Spring / protobuf / JPA 타입 사용.
- Stable leaf에서 `:grpc-advanced:*` 참조.
- `grpc-testkit`을 production leaf가 의존하는 것.
- in-process 결과로 transport capability를 주장하는 것 (`GrpcEvidenceGrade`가 거부한다).
- metric tag에 raw metadata·payload·actor/tenant/object/stream/idempotency 식별자를 넣는 것
(`GrpcMetricCardinalityPolicy`가 거부한다).
### 채택할 때의 관측 게이트
`grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지
않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의
`.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
이름을 저장소가 인증한 metric처럼 내세우지 않는다.
### durable operation 원장 채택
`grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable
operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고,
`GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway
위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다.
원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다.
| 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 |
| --- | --- | --- |
| `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 |
| `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 |
| `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 |
기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고,
주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL
(`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서
`app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다.
**starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는
(a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에
적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서
온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게
했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다:
바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의
중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가
필요한 메서드가 그것을 필요로 할 때 키가 된다.
**서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지
않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은
별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가
아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor
(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기
typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서
`recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온
`GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는
무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004).
**지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난
끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을
예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든
배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다).
지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만
테이블이 끝없이 커진다.
커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두
이유는 모두 ADR-GRPC-004에 있다.
@AGENTS.md
+176
View File
@@ -0,0 +1,176 @@
# messaging — 메시징 플랫폼 family의 지역 정본
이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는
것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에
필요한 증거, runtime membership이 비어 있다는 사실의 의미.
루트 `AGENTS.md`와 충돌하면 루트가 이긴다.
## Family와 framework 규칙
leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의
역할로 정해진다.
| Family | 역할 | 허용 framework |
| --- | --- | --- |
| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 |
| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 |
신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`,
`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을,
`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을
갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께
가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check`
(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는
`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에
registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는
`shared-contract`의 정본과 같은 규칙인지 함께 본다.
### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization)
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽
재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과
descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다.
- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다.
broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든
publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지
않게 하려는 것이다.
다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두
publish 경로, 소비 경로 동작은 그대로):
- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로.
- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로.
- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로.
- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public.
버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로
번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
## Public surface 정책
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
`protobuf-java`가 이 규칙으로 `api`다.)
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
`implementation`으로 둔 것이 그 예다.
- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production
source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의
`build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가
들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만
등장하고 adopter가 이름 부를 일이 없다.
- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.
## Application runtime에 포함되는 기준
기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에
`runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와
`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이
사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다.
모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다.
일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다.
RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은
2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표).
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
qualification/support 상태를 함께 변경한다.
## application이 이 family에 도달하는 경로 (cutover 완료)
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
- application-owned port: `IntegrationEventPublishPort`
- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter`
- platform boundary: `EncodedMessagePublisher`
- central implementation: `DefaultMessagePublisher`
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
직접 보지 않는다.
**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical
`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy
`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지
않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security
profile(`KafkaSecurityConfigurer`)을 적용한다.
canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을
만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면
relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.
`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의
`JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`)
안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한
`IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과
다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다.
## Stable 승격에 필요한 증거
adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재
상태를 기록한다):
1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이
`BrokerCertificationEvidence`를 산출한다.
2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다.
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
증거가 아니다.
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
Experimental에서도 금지다.
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
있을 때만.
Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.
증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다:
```bash
./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain
```
레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며,
통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을
`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다.
게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고,
레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다).
skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는
`messaging-certification` 태그로 제외된다.
## Focused test
leaf의 `gradle_path`를 registry에서 읽어 파생한다.
```bash
cd src
./gradlew <gradle-path>:test --console=plain
```
Family 전체 검증:
```bash
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew architectureCheck --console=plain
./gradlew verifyDependencyLocks --console=plain
```
+1 -176
View File
@@ -1,176 +1 @@
# messaging — 메시징 플랫폼 family의 지역 정본
이 문서는 messaging family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
`src/config/architecture/modules.json`이 SSOT이며 이 문서는 그것을 복제하지 않는다. 여기서 정하는
것은 registry가 표현할 수 없는 것들이다: family별 framework 규칙, public surface 정책, Stable 승격에
필요한 증거, runtime membership이 비어 있다는 사실의 의미.
Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다.
## Family와 framework 규칙
leaf의 정확한 id는 registry에서 읽는다. family는 **디렉터리 이름의 접두사**가 아니라 아래 표의
역할로 정해진다.
| Family | 역할 | 허용 framework |
| --- | --- | --- |
| `*-api` (`core-api` — `api`·`schema` 패키지, `policy`, `reliability-api`, `transport-spi`) | 값 타입, 포트, 정책 계약 | Java stdlib만. Spring/broker SDK/logging framework 금지 |
| `schema-*` (json/avro/protobuf), `cloudevents` | 인코딩 구현 | 해당 codec 라이브러리만. Spring 금지 |
| `runtime-core`, `security`, `observability`, `admin`(계약 `admin` + 실행 `admin.runtime`), `reliability` | framework-free 실행 로직 | Micrometer는 `observability`에서만. 나머지는 stdlib |
| `kafka` | broker adapter | 해당 broker client. Spring은 client가 곧 Spring인 경우만 |
| `reliability-jdbc-postgresql` | 관계형 신뢰성 adapter (outbox·inbox repository, admin journal) | Spring JDBC / Spring TX. **JPA 아님** — 이름이 곧 계약이다 |
| `spring-boot-starter`, `spring-boot-starter-kafka` | 조립 경계 | Spring Boot autoconfigure. 여기서만 |
| `testkit` | 테스트 지원 | Testcontainers, JUnit. production leaf가 의존하지 않는다 |
신뢰성 기능은 세 leaf다. `messaging-reliability-api`가 vendor 중립 port(`OutboxRepository`,
`InboxRepository`)를, `messaging-reliability`가 그 port만 보는 relay·consumer 로직(stdlib)을,
`messaging-reliability-jdbc-postgresql`이 port의 관계형 구현과 migration(`V1001..V1005`, `V1101`)을
갖는다. 예전에는 `outbox-jdbc-postgresql` 하나가 relay 로직과 PG repository와 admin journal을 함께
가졌고 inbox도 같은 모양이었다(2026-09-25 리뷰 후속 작업에서 나눴다). 구현 leaf가 `jdbc-postgresql`로 명명된 이유: 구현은 Spring
JDBC이고 SQL은 `jsonb` · `FOR UPDATE SKIP LOCKED` · `ON CONFLICT` · `TIMESTAMPTZ`로 PostgreSQL
전용이다. `jpa`라는 이름은 사용하지 않는 기술을 광고하고, vendor 중립 port가 어디 있는지도 숨겼다.
### 공용 다이제스트 헬퍼를 복사해 두는 이유
`messaging-admin`(`HmacApprovalVerifier`, `PlanDigest`)과 `messaging-claim-check`
(`ClaimCheckIntegrityGuard`)는 SHA-256·HMAC-SHA256 계산을 자기 안에 둔다. 템플릿의
`shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이 family는 이 애플리케이션의
계층이 아니라 자기 API·SPI·composition을 가진 다른 제품이고(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정한 배치), `messaging:*` leaf는
`domain-core`·`application-core`·`shared-contract` 어느 타입에도 의존하지 않는다. 헬퍼 하나 때문에
registry edge를 주면 그 경계가 깨진다. 복사본을 고칠 때(키 길이 검사, constant-time 비교 등)는
`shared-contract`의 정본과 같은 규칙인지 함께 본다.
### 인증·인가 거부의 발행 재시도 여부 (Publish retryability of authentication and authorization)
이 제품 안에는 같은 category에 대한 재시도 규칙이 둘 있다. 의도다.
- category 기본값: `FailureDescriptor.defaultRetryable(AUTHENTICATION | AUTHORIZATION) = false`. 소비 쪽
재시도 엔진(`DefaultRetryDecisionEngine`)은 policy가 category를 따로 정하지 않으면 이 기본값과
descriptor의 `retryable`을 둘 다 요구한다. 그래서 인가받지 못한 메시지의 재전달은 지금도 재시도하지 않는다.
- publish 거부의 `retryable`: `KafkaPublishFailureClassifier`는 인증·인가 거부에 `retryable = true`를 붙인다.
broker가 레코드를 저장하지 않았고, credential 교체나 application보다 늦게 배포된 ACL은 몇 분 동안 모든
publish를 거부한 뒤 멈추기 때문이다. `retryable`을 믿는 publisher가 그 몇 분 동안의 레코드를 영구 보류하지
않게 하려는 것이다.
다시 시도하면 될 거부를 relay가 즉시 DEAD로 보내던 결함의 수정(2026-11-01 성숙도 리뷰 뒤)이 이 제품에서 바꾼 것(모두
publish 경로, 소비 경로 동작은 그대로):
- `KafkaPublishFailureClassifier`: 인증·인가 거부를 `retryable = true`로.
- `DefaultMessagePublisher`: runtime이 없을 때의 거부(`PUBLISH_RUNTIME_UNAVAILABLE`)를 `retryable = true`로.
- `KafkaMessagingTransport`: 닫힌 transport의 거부(`KAFKA_TRANSPORT_CLOSED`)를 `retryable = true`로.
- `MessagingShutdownLifecycle.PHASE`: platform 밖 relay의 순서 테스트가 참조하도록 public.
버린 대안: vendored 제품은 그대로 두고 application bridge(ACL)가 category를 보고 "인증·인가면 재시도"로
번역하는 것. 버린 이유: `retryable`은 이 제품이 "같은 레코드를 나중에 다시 보내면 받아질 수 있나"를 말하는
자리다. bridge가 category로 그 판단을 다시 하면 같은 사실을 제품과 bridge가 따로 정하고, 이 제품의
`PublishResult`를 읽는 다른 호출자는 bridge와 다른 답을 본다. 대신 이 제품 주석은 소비자 이름(application
relay, `composition:outbox-relay`)을 부르지 않는다 — "flag를 믿는 publisher"로 쓴다(2026-11-03).
## Public surface 정책
- **vendor 타입을 public signature에 노출하면 그 의존성은 `api`로 선언한다.** 숨긴다고 타입이
숨겨지지 않는다 — consumer가 이 모듈이 문서화한 API에 대해 컴파일하지 못하게 만들 뿐이다.
(`kafka-clients`, `cloudevents-api`, `micrometer-core`, `avro`,
`protobuf-java`가 이 규칙으로 `api`다.)
- 반대로 **노출하지 않는 것은 `implementation`으로 낮춘다.** starter가 노출하지 않는 하위 모듈을
`implementation`으로 내린 것이, JSON codec이 `ObjectMapper`를 private으로만 쓰고 Jackson을
`implementation`으로 둔 것이 그 예다.
- 이 규칙은 문서가 아니라 `MessagingPublicSurfaceContractTest`가 붙들고 있다. leaf의 production
source에서 public/protected 시그니처에 등장하는 vendor 라이브러리를 뽑아 그 leaf의
`build.gradle`이 `api`로 선언했는지 대조하고, starter의 `api` closure에 broker client 두 개가
들어오지 않는 것도 함께 본다. Spring Framework/Boot는 대상이 아니다 — 조립 경계 안에서만
등장하고 adopter가 이름 부를 일이 없다.
- 새 public 타입은 그 모듈의 계약이다. 삭제·시그니처 변경은 breaking change로 취급한다.
## Application runtime에 포함되는 기준
기본 조립에는 Messaging family가 없다. 서비스가 `app-bootstrap/build.gradle`에
`runtimeOnly project(':adapter:outbound:messaging-kafka')` 한 줄을 넣으면 그 모듈이 bridge와
`messaging-spring-boot-starter`(Kafka transport 포함)의 transitive project graph를 runtime에 싣는다. 이
사실의 SSOT는 Gradle `runtimeClasspath`이며 registry에 동일한 membership 목록을 복제하지 않는다.
모듈이 있으면 켜지고(`app.messaging.enabled` 기본 `true`), `APP_MESSAGING_ENABLED=false`로만 끈다.
일부 codec(cloudevents 등)·claim-check·testkit처럼 starter graph에 들어오지 않는 leaf는 build-only다.
RabbitMQ·Pulsar·NATS·Kafka Share·Spring Cloud Stream bridge leaf와 Debezium outbox 매핑은
2026-09-25에 삭제했다(`docs/capability-status.md` 제거 표).
새 leaf를 application에 채택할 때는 starter 또는 composition dependency와 architecture edge policy,
qualification/support 상태를 함께 변경한다.
## application이 이 family에 도달하는 경로 (cutover 완료)
리뷰(`docs/reviews/2026-08-14-messaging-module-code-review.md` §6.1·§6.3)가 정한
`application-owned port → platform anti-corruption bridge → platform` 경로는 이제 존재한다.
- application-owned port: `IntegrationEventPublishPort`
- bridge: `adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter`
- platform boundary: `EncodedMessagePublisher`
- central implementation: `DefaultMessagePublisher`
bridge는 exact canonical envelope bytes를 다시 serialize하지 않고, destination/access/admission/runtime
lease/transport/outcome normalization/observation은 platform 중앙 publish path를 그대로 탄다. bridge
package는 `messaging-core-api`만 보며 concrete runtime/transport/Kafka 타입을
직접 보지 않는다.
**application bridge cutover는 2026-09-28에 끝났다(2026-09-25 소유자 결정).** application의 outbox append는 canonical
`OutboxAppendPort` 하나이고, relay는 claim한 row의 validated event를 이 bridge로만 보낸다. legacy
`OutboxEvent`·`LegacyOutboxAppendPort`와 `MessageBroker → KafkaSender` R0 경로(TLS/SASL을 적용하지
않던 두 번째 producer)는 삭제했다. 남은 Kafka producer는 platform의 것 하나이고, broker security
profile(`KafkaSecurityConfigurer`)을 적용한다.
canonical bridge의 producer identity는 `app.messaging.producer-id`로 명시한다. 값이 없으면 bridge bean을
만들지 않으며 `spring.application.name`/host/pod 이름에서 identity를 발명하지 않는다. bridge가 없으면
relay가 발행할 곳이 없으므로 messaging 모듈이 켜진 상태에서는 기동이 거부된다.
`IntegrationEventEncoderPort`는 템플릿이 제공한다: `adapter:outbound:support`의
`JsonIntegrationEventEncoder`가 envelope v1(`shared-contract`의 `contracts/messaging/envelope/v1.schema.json`)
안에 payload record를 결정적 JSON으로 싣는다. 계약 catalog는 애플리케이션이 bean으로 등록한
`IntegrationEventContractContribution`뿐이고, 선언한 payload schema hash가 classpath의 schema 파일과
다르면 기동이 실패한다. payload를 JSON Schema로 매번 검증하려는 서비스는 자기 encoder bean을 두면 된다.
## Stable 승격에 필요한 증거
adapter를 Experimental → Stable로 올릴 때 필요한 것 (`docs/messaging/support-matrix.md`가 현재
상태를 기록한다):
1. 실제 broker container를 쓰는 fault 시나리오 lane이 존재하고, 그 lane이
`BrokerCertificationEvidence`를 산출한다.
2. `NetworkFaultScenario` 전 항목에 대해 evidence가 있거나, 없는 항목이 `knownGaps`로 명시된다.
3. capability 선언이 코드에서 파생된다 — `MessagingCapabilities`에 손으로 `true`를 쓰는 것은
증거가 아니다.
4. publish 실패 분류가 typed signal에서만 나온다. exception class 이름 substring 판정은
Experimental에서도 금지다.
5. unknown failure의 기본값이 `AMBIGUOUS`다. `REJECTED`는 전송이 시작되지 않았다는 typed 증거가
있을 때만.
Stable 문구는 evidence manifest가 존재할 때만 문서에 쓴다.
증거를 만드는 것은 인증 레인이고, manifest는 그 실행의 출력이다:
```bash
./gradlew :messaging:messaging-kafka:verifyMessagingCertificationEvidence --console=plain
```
레인(`messagingCertificationTest`)은 Toxiproxy를 broker 앞에 두고 장애를 주입하며,
통과한 시나리오마다 `BrokerCertificationEvidence` 한 줄을
`messaging-testkit/src/main/resources/messaging/broker-certification-evidence.jsonl`에 쓴다.
게이트는 커밋된 manifest와 이번 실행의 출력을 대조한다 — **manifest를 손으로 고치면 실패하고,
레인을 돌리면 manifest가 다시 쓰인다.** 이 레인만은 Docker 가드를 달지 않는다(없으면 실패한다).
skip하는 인증 레인은 아무도 켜지 않은 브로커에 대해 성공을 보고하기 때문이며, 그래서 `test`에서는
`messaging-certification` 태그로 제외된다.
## Focused test
leaf의 `gradle_path`를 registry에서 읽어 파생한다.
```bash
cd src
./gradlew <gradle-path>:test --console=plain
```
Family 전체 검증:
```bash
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew architectureCheck --console=plain
./gradlew verifyDependencyLocks --console=plain
```
@AGENTS.md
+69
View File
@@ -0,0 +1,69 @@
# shared-contract — 골격 전체가 쓰는 운영 계약
## 등록 정보
- 모듈 ID: `shared-contract`
- Gradle 경로: `:shared-contract`
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :shared-contract:test --console=plain`
- 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 `src/gradle/libs.versions.toml`이 정한다.
- registry 정본: `src/config/architecture/modules.json`.
패키지 루트: `dev.caskeleton.shared`.
예전에 코드 주석에 두던 설계 결정(오류 코드 분류, 응답 envelope 모양, metric cardinality 한계,
tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙의 정본으로
남는다.
## 책임 (Responsibility)
- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`).
- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum,
`error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`.
한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다).
- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`).
- 요청 값 계약(`request/Patch`).
- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과
span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는
이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다).
- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다):
`digest/Sha256`(SHA-256 digest 값과 유일한 `MessageDigest.getInstance("SHA-256")`),
`digest/HmacSha256`(서명과 상수 시간 검증), `retry/Backoff`(상한 있는 지수 ceiling. "full jitter"는
`U[0, ceiling]`이고 다른 뜻이 아니다). 들여온 `messaging:*`와 optional gRPC 빌드는 이 모듈에
의존하지 않고 자기 사본을 둔다. 각 제품의 AGENTS.md가 이유를 적는다(다른 제품이다. 2026-08-14 메시징
모듈 리뷰 뒤에 정했다). 이 도우미가 필요한 템플릿 leaf는 모두 `shared-contract` edge를 두고 복사하지
않고 쓴다. identifier, persistence-mongo, application-objectstorage, redis-sdk가 바로 이 때문에
edge를 받았고(2026-11-03에 정함), 각각 JVM 밖에서 계산한 벡터로 출력을 고정하는 시험이 있다.
- `observability/MdcKeys`: 모든 전송 계층(web, GraphQL, STOMP, gRPC)이 요청의 correlation을 넣는
snake_case MDC 키 이름(registry `docs/registries/mdc-keys.yaml`).
- `ratelimit/`: web edge와 Redis 어댑터 사이에 있는 provider 중립 edge rate-limit 포트
(`EdgeRateLimitPort`)와 그 값 타입(README 「ratelimit」).
- `security/Permission`: `AuthorizationPort`에 묻는 `resource:action` 권한 값(README 「security」).
- `concurrency/`: domain-context 전파 포트와 그 `ThreadLocal` 기본 구현(README 「concurrency」).
- `runtime/RuntimeEnvironment`: 모든 leaf가 「운영 환경인가?」에 답할 때 쓰는 유일한 runtime profile
어휘.
- `metrics/ForbiddenMetricTags`: 어떤 metric도 실으면 안 되는 high-cardinality tag 키.
- 이 모듈의 패키지는 위가 전부이고 다른 패키지는 둘 수 없다:
`ForbiddenApiArchitectureTest.SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가
`dev.caskeleton.shared` 아래 다른 패키지에 있는 클래스와 루트에 바로 있는 클래스를 거절한다. 루트에는
`package-info`만 있다. 새 계약 패키지는 그 시험의 `SHARED_CONTRACT_PACKAGES`와 이 목록에 함께
넣는다. `SharedContractPackageRuleTest`는 `SHARED_CONTRACT_PACKAGES`와 모듈의 패키지가 다르면
실패한다.
- 계약 시험만 읽는 registry 규칙 사본은 `main`이 아니라 `testFixtures`에 둔다:
`metrics/MetricNaming`, `metrics/CardinalityBounds`, `metrics/AlertSeverity`,
`tracing/BaggageAllowlist`. 운영 코드가 쓰게 될 때만 `main`으로 옮긴다.
- `contracts/messaging/envelope/` 아래의 범용 메시징 envelope schema 리소스. 전송 중립 envelope
metadata만 가진다. 기능 payload schema는 그 기능을 가진 모듈에 남는다. 리소스가 있다고 런타임에
찾아지거나 등록되는 것은 아니다.
## 허용
- Java 표준 라이브러리**만**. Spring, Jackson, JPA import는 없다.
## 금지 (Forbidden)
- 업무·도메인 개념(도메인 오류 코드는 그것을 쓰는 모듈에 둔다).
- 프레임워크 import(HTTP 상태는 전송 중립 `int`로 나타내고 web 모듈이 대응시킨다).
- 메시징 어댑터의 Task 6 validator 검증이 생기기 전에 Draft 2020-12 validator 호환을 주장하기.
## 테스트
```bash
cd src
./gradlew :shared-contract:test
```

Some files were not shown because too many files have changed in this diff Show More