diff --git a/.claude/skills/new-feature/SKILL.md b/.claude/skills/new-feature/SKILL.md index 223336a1..b7ee5925 100644 --- a/.claude/skills/new-feature/SKILL.md +++ b/.claude/skills/new-feature/SKILL.md @@ -9,7 +9,7 @@ description: 이 백엔드 템플릿에 새 업무 기능(도메인 개념, 유 1. `docs/work/README.md`와 `docs/work/new-feature.md`를 끝까지 읽는다. 크기를 정한다. 새 capability 모듈, 새 leaf, 새 공개 계약(HTTP 경로·오류 코드·env 키)은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다. 2. 받을 것을 확인한다: 기능 이름(PascalCase), 저장소 선택(어떤 persistence leaf, migration 번호대), 권한, 재전송될 수 있는 쓰기인지. 저장소 선택은 사람이 정한다. brief에 없으면 묻는다. -3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다. +3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다. 4. 뼈대: 노트북에서는 `scripts/new-feature.sh --no-format`. 포맷은 편집 훅이 파일마다 맞추고, 마지막에 desktop `./gradlew spotlessApply`로 한 번 더 본다. 5. 안쪽부터 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립(`docs/manual/02-new-feature.md`). 필요한 장만 더 읽는다: 저장 04, 재시도될 쓰기 05, 오류 06, 권한 07, 테스트 08, 이벤트 09, capability 10. 6. 동작은 테스트를 먼저 쓴다(`.claude/rules/java-tests.md`). 포트마다 fake 하나와 공유 계약(`XxxContract`)을 포트 소유 leaf의 testFixtures에 두고, 실제 adapter도 실 DB lane에서 같은 계약을 상속한다. diff --git a/docs/manual/03-placement.md b/docs/manual/03-placement.md index 06c626f9..cf26df08 100644 --- a/docs/manual/03-placement.md +++ b/docs/manual/03-placement.md @@ -55,8 +55,8 @@ - ``는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과 겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를 이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다. -- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/AGENTS.md` - 「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성 +- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/README.md` + 「패키지 소유 (Package ownership)」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성 뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다. - 이름 규칙은 같은 파일 「Naming convention」이 정본이다. diff --git a/docs/manual/05-idempotency.md b/docs/manual/05-idempotency.md index 707251aa..e2b6be64 100644 --- a/docs/manual/05-idempotency.md +++ b/docs/manual/05-idempotency.md @@ -16,7 +16,7 @@ DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false) ``` -정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/AGENTS.md` 「Idempotency (KEYED)」 +정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/README.md` 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」 (executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명). ## 판단: 이 쓰기를 KEYED로 만드나 diff --git a/docs/manual/09-outbox-events.md b/docs/manual/09-outbox-events.md index 48a560ce..7ccf0d17 100644 --- a/docs/manual/09-outbox-events.md +++ b/docs/manual/09-outbox-events.md @@ -17,7 +17,7 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을 없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다. -정본: `src/application-core/AGENTS.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, +정본: `src/application-core/README.md` 「계약 타입」(이벤트 타입 표), `docs/messaging/outbox-inbox.md`, `docs/messaging/delivery-guarantees.md`. ## 순서 diff --git a/docs/manual/11-checklist.md b/docs/manual/11-checklist.md index 2282613d..7c1cf0f9 100644 --- a/docs/manual/11-checklist.md +++ b/docs/manual/11-checklist.md @@ -5,7 +5,7 @@ ## 배치·이름 - [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `` 패키지). -- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다. +- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다. - [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다. ## domain diff --git a/docs/manual/README.md b/docs/manual/README.md index 33a4068d..bd3c82f8 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -44,7 +44,7 @@ | 테스트 작성 규칙 | `.claude/rules/java-tests.md` | | leaf 목록·허용 의존 | `src/config/architecture/modules.json` | | 이름 규칙(유스케이스·포트·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」 | +| 유스케이스 모양·트랜잭션 모양 | `src/application-core/README.md` 「정해진 유스케이스 모양 (Canonical use case shape)」, `src/application-core/AGENTS.md` 「허용하는 트랜잭션 모양 (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` | diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index e6f68de7..7a3e871e 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -18,3 +18,4 @@ | 5 | Agent 도구 금지를 풀었다(`.claude/settings.json`의 `"Agent"` deny 삭제). 결과만 받는 일은 서브에이전트(`.claude/agents/`의 `arch-reviewer`·`verify-api`·`code-simplifier`)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(`docs/work/delegate.md` 4.3절). `.gitignore`에 `!.claude/agents/`를 더했다 | 서비스가 Agent 도구를 계속 막으려면 자기 `.claude/settings.json`에 `"Agent"` deny를 남긴다. `verify-api`는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다 | | 6 | repo 스킬 둘을 더했다: `.claude/skills/new-feature`(새 기능 실행 순서), `.claude/skills/desktop-gates`(Gradle·Docker를 desktop에서 돌리는 순서). 모델이 설명의 발동 조건을 보고 부른다. 설치된 스킬이 없던 `skills-lock.json`을 지웠다. `.gitignore`에 `!.claude/skills/`를 더했다 | `desktop-gates`는 소유자 환경을 가정하므로 서비스 환경에 맞게 고치거나 지운다. 서비스가 `skills-lock.json`을 썼다면 merge에서 삭제 충돌이 난다. 쓰면 남긴다 | | 7 | 예측·실측 장부 `docs/ledger/estimates.jsonl`(형식 `docs/ledger/README.md`)을 두었다. `.gitattributes`가 이 파일에 `merge=union`을 준다 | 서비스는 템플릿의 줄을 지우고 자기 작업의 줄부터 쌓는다. 템플릿 줄은 템플릿 작업의 기록이다 | +| 8 | 지역 규칙이 200줄을 넘던 셋(`src/application-core`, `src/adapter/outbound/persistence-jpa`, `src/adapter/inbound/graphql`)의 표와 계약을 같은 폴더 `README.md` 끝 「지역 규칙에서 옮긴 표와 계약」 절로 옮겼다. 템플릿 패키지 목록(「패키지 소유」 표)의 정본도 `src/application-core/README.md`다 | 서비스가 그 절을 고쳤다면 README의 같은 절로 옮긴다. 서비스 문서·테스트가 `src/application-core/AGENTS.md`의 「Package ownership」 표를 읽으면 `README.md`로 바꾼다 | diff --git a/docs/work/README.md b/docs/work/README.md index f770bacd..1de50824 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -74,6 +74,6 @@ ## 8. 이 폴더를 고칠 때 -- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다. +- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 폴더 지역 규칙(`src/**/AGENTS.md`) 200줄(넘으면 표·근거를 그 leaf README로), 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다. - 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 규칙·스킬·서브에이전트 문서도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다. - 이 폴더, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다. diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index 5ff0fde4..3ae4367d 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -29,7 +29,7 @@ ## 4. 절차 1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다. -2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다. +2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다. 3. capability 모듈이면 `docs/manual/10-capabilities.md`의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다. 4. 뼈대를 만든다: `scripts/new-feature.sh `(`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 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다. diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index 5d0dd5f0..f72f5daf 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -199,7 +199,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신 - 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다. - 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다. - 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`). -- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. +- 템플릿 패키지 목록은 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. - capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. - vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다. - source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`). @@ -213,7 +213,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼 - [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다) - [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports` - [ ] leaf `AGENTS.md`(그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄), 자기 README나 family README의 다섯 칸(`docs/README.md` 「모듈 README」). capability면 README에 제공하는 것, 추가할 한 줄, 필요한 env 키 -- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표 +- [ ] 템플릿 패키지를 더하거나 지우면 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표와 `TemplatePackageOwnership` - [ ] ArchUnit 규칙과 그 위반·허용 fixture - [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다) - [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행 diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index 32dceaad..ebcdc7b4 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -14,7 +14,7 @@ things break that, and both are mechanical: `CLAUDE.md`, and every folder rule book `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 + root `CLAUDE.md` + README + +2. Length. Each entry file has a line limit (a folder rule book src/**/AGENTS.md too: 200), and the entry path (map + root `CLAUDE.md` + README + one playbook) has a total limit, so a session reads the whole path instead of skimming it. The map limit is 40 lines (owner decision 2026-11-07: vision, map and HARD-STOP only). @@ -67,6 +67,9 @@ HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-pattern MAP_LIMIT = 40 CLAUDE_ENTRY_LIMIT = 10 +# A folder rule book is read whole whenever a file in that folder is opened. Claude Code's guidance is +# under 200 lines per instruction file; tables and design reasons go to the leaf README. +MODULE_GUIDE_LIMIT = 200 README_LIMIT = 80 PLAYBOOK_LIMIT = 150 ENTRY_PATH_LIMIT = 350 @@ -230,6 +233,17 @@ def check_guide_pairs(errors: list[str]) -> None: errors.append(f"{rel(entry)}: imports {rel(entry.with_name('AGENTS.md'))}, which does not exist") +def check_guide_limits(errors: list[str], report: list[str]) -> None: + longest = 0 + for guide in module_guides(): + lines = line_count(guide) + longest = max(longest, lines) + if lines > MODULE_GUIDE_LIMIT: + errors.append(f"{rel(guide)}: {lines} lines, limit {MODULE_GUIDE_LIMIT}" + " (move tables and design reasons to the leaf README and leave a pointer)") + report.append(f"longest src/**/AGENTS.md: {longest}/{MODULE_GUIDE_LIMIT}") + + def check_claude_entry(errors: list[str]) -> None: """The root CLAUDE.md starts with the import, so a Claude Code session reads the map.""" lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines() @@ -351,6 +365,7 @@ def main() -> int: check_limits(errors, report) check_claude_entry(errors) check_guide_pairs(errors) + check_guide_limits(errors, report) check_skeleton(errors) check_history(errors, report) check_links(errors, report) diff --git a/scripts/tests/test_check_work_docs.py b/scripts/tests/test_check_work_docs.py index f4ff5e88..f035c530 100644 --- a/scripts/tests/test_check_work_docs.py +++ b/scripts/tests/test_check_work_docs.py @@ -101,6 +101,14 @@ class CheckWorkDocsTest(unittest.TestCase): self.addCleanup(setattr, check_work_docs, "ENTRY_PATH_LIMIT", original) self.assertFailsWith(f"docs/work/improve.md: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {lines} lines") + def test_a_folder_rule_book_over_two_hundred_lines_fails(self) -> None: + self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 200) + self.assertFailsWith("src/app/AGENTS.md: 201 lines, limit 200") + + def test_a_folder_rule_book_of_two_hundred_lines_passes(self) -> None: + self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 199) + self.assertEqual(self.repo.run(), (0, "")) + def test_a_folder_rule_book_without_its_claude_import_fails(self) -> None: self.repo.write("src/web/AGENTS.md", "# web\n") self.assertFailsWith("src/web/CLAUDE.md: missing; it must be the one line '@AGENTS.md'") diff --git a/src/adapter/inbound/graphql/AGENTS.md b/src/adapter/inbound/graphql/AGENTS.md index bec9db91..36ba5fec 100644 --- a/src/adapter/inbound/graphql/AGENTS.md +++ b/src/adapter/inbound/graphql/AGENTS.md @@ -142,42 +142,9 @@ health 스키마만 소유한다. ## 구현된 플랫폼 범위 — 등급으로 말한다 -"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 capability 마다 아래 등급을 -쓰고, **현재 등급보다 높게 표현하지 않는다.** +표와 자세한 계약은 [README.md](README.md) 「구현된 플랫폼 범위 — 등급으로 말한다」 절이다. 지킬 것: -| 등급 | 의미 | -| --- | --- | -| `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 를 구현하는 - 형태로 새로 만든다. +- capability마다 그 표의 등급을 쓰고, 현재 등급보다 높게 표현하지 않는다(README·문서·커밋 본문 모두). ## 테스트 diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index edc1cf9a..015de45f 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -365,3 +365,46 @@ GraphQL/graphql-java SPI 를 구현한 타입이 없어 2026-09-25 에 삭제했 feature GraphQL schema/resolver 는 여전히 이 leaf 밖이다(스켈레톤은 health 표면만 소유). 실부하 성능 증거와 실 datastore 통합 증거도 없다. + +## 지역 규칙에서 옮긴 표와 계약 + +이 절의 표와 계약은 지역 규칙 [AGENTS.md](AGENTS.md)에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 `AGENTS.md`를 같은 변경에서 고친다. + +### 구현된 플랫폼 범위 — 등급으로 말한다 + +"구현됐다" 는 네 가지 서로 다른 사실을 한 단어로 덮는다. 그래서 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 를 구현하는 + 형태로 새로 만든다. diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/authz/RolePermissionPolicyTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/authz/RolePermissionPolicyTest.java index 2a7c8cba..ae6743e3 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/authz/RolePermissionPolicyTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/authz/RolePermissionPolicyTest.java @@ -12,7 +12,7 @@ import org.springframework.boot.test.context.runner.ApplicationContextRunner; import org.springframework.context.annotation.Configuration; /** - * Binding test for {@link RolePermissionPolicy} (AGENTS.md §설정과 런타임: every new + * Binding test for {@link RolePermissionPolicy} (.claude/rules/settings-and-runtime.md: every new * {@code @ConfigurationProperties} class gets a binding test). Verifies the {@code * app.authz.role-permissions.=} YAML/env shape binds to the {@code Map>} the registry consumes, and that an absent block is null-safe. diff --git a/src/adapter/outbound/persistence-jpa/AGENTS.md b/src/adapter/outbound/persistence-jpa/AGENTS.md index b6131bef..e8a178c9 100644 --- a/src/adapter/outbound/persistence-jpa/AGENTS.md +++ b/src/adapter/outbound/persistence-jpa/AGENTS.md @@ -11,7 +11,8 @@ 패키지 루트: `dev.caskeleton.adapter.outbound.persistence`. 예전에 코드 주석으로 두던 설계 결정(트랜잭션 template, 감사 값 잡기, 실패 번역 SPI, 멱등성·outbox 동시성, 분산 -lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 계약 표의 정본으로 남는다. +lock TTL)과 계약 표(트랜잭션 모드, SQLState → 오류 코드, vendor, lane)는 [README.md](README.md)에 있다. 이 파일은 이 +폴더를 고칠 때 지킬 모듈 규칙의 정본이다. 이 모듈은 RDBMS·JPA 구현 기반이다. MongoDB, Redis, DynamoDB나 다른 NoSQL 저장소를 위한 저장소 중립 core가 아니다. 앞으로의 NoSQL 영속 어댑터는 application·domain 포트를 직접 구현하고 이 모듈에 의존하면 안 된다. @@ -43,33 +44,11 @@ lock TTL)은 [README.md](README.md)에 있다. 이 파일은 모듈 규칙과 ### 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 후보를 막아 준다고 기대지 -않는다. +표와 자세한 계약은 [README.md](README.md) 「Spring 조립 소유」 절이다. 지킬 것: -`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`가 늘지 않게 한다. +- `AutoConfiguration.imports`의 두 항목(`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`)은 둘 다 `app.persistence-jpa.enabled=true`를 요구한다. `enabled=false`는 DataSource·pool·Flyway까지 완전히 끈다. +- 트랜잭션 엔진은 `SpringTransaction` 하나다. 두 번째 엔진을 만들지 않는다. +- 이 leaf는 유스케이스를 만들거나 부르지 않는다(outbox relay는 `composition:outbox-relay`). `dev.caskeleton.bootstrap`을 import하지 않고, 기동 실패는 `adapter:outbound:support`(`support.startup`)를 거치며, 새 조립 도우미는 package-private로 둔다. ### 양보할 수 없는 것 @@ -92,26 +71,9 @@ migration 기동 순서, 해석된 datasource·버전 검증, OSIV·DDL·pool·T ### 플랫폼 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 -``` +표와 자세한 계약은 [README.md](README.md) 「플랫폼 lane」 절이다. 지킬 것: -Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 시작하지 못하면 건너뛰기가 -아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다. +- Docker를 쓰는 lane은 실패하면 닫힌다. 고른 lane이 아무것도 찾지 못하거나 container가 뜨지 못하면 건너뛰기가 아니라 오류다. ## 책임 @@ -137,44 +99,10 @@ Docker를 쓰는 모든 lane은 실패하면 닫힌다. 고른 lane이 아무것 ## vendor 고르기 -vendor 조립 둘이 이 모듈에 있고, 각각 자기 하위 패키지에 있으며, 각각 같은 SPI bean 둘(outbox claim, SQLState 대응)을 -등록한다: +표와 자세한 계약은 [README.md](README.md) 「vendor 고르기」 절이다. 지킬 것: -| 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는 있으면 안 된다. +- vendor 선택은 `config/PersistenceVendorSettings`(enum) 하나이고 모듈 기본값은 PostgreSQL이다. H2는 `bootRunH2`로만 고르는 로컬 저장소이고 prod에서 거절된다. +- 선택 capability 하나를 위한 어댑터(지금 `fileserver` 패키지)는 그 capability의 스위치(`@ConditionalOnProperty`)를 단다. 아무도 켜지 않은 capability의 store는 bean이 되면 안 된다. ## 허용 @@ -203,117 +131,26 @@ capability의 store는 있으면 안 된다. ## TransactionPort 구현 계약 -`SpringTransaction`은 모드마다 `TransactionTemplate`을 하나씩 미리 만든다: +표와 자세한 계약은 [README.md](README.md) 「TransactionPort 구현 계약」 절이다. 지킬 것: -| 모드 | 전파 | 격리 | 읽기 전용 | 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` **하나** 안에서 묶어 처리하거나, -반복문을 트랜잭션 밖으로 뺀다. +- 모드마다 미리 만든 `TransactionTemplate`을 만든 뒤 바꾸지 않는다. 격리 수준은 template이 아니라 pool(READ COMMITTED, `HikariPoolConstraintValidator`)에 고정한다. +- 모든 모드에 시간 한계가 있다. `inRootWrite`는 실제 바깥 트랜잭션이 있으면 action 전에 `NestedRootTransactionRejectedException`을 던지고, 커밋한 뒤에만 값을 돌려준다. +- `inNew` 풀 크기 제약과 반복문 금지는 [application-core/AGENTS.md](../../../application-core/AGENTS.md)와 같다. ## 영속 실패 번역 계약 (feature-persistence-failure-baseline) -날것의 Spring `DataAccessException`(과 그 안의 JPA 예외·SQLState·제약 이름)은 절대 표현 계층에 닿으면 안 된다. -`failure/PersistenceExceptionTranslator`가 `DataAccessException`을 SQLState로 아래 §SQLState → 오류 코드 표와 대조해 -분류하고, `DB_*` `OperationalError` 코드 하나를 실은 프레임워크 중립 `shared.error.PersistenceFailureException`을 돌려준다. +표와 자세한 계약은 [README.md](README.md) 「영속 실패 번역 계약 (feature-persistence-failure-baseline)」 절이다. 그 SQLState → 오류 코드 표가 정본이다. 지킬 것: -**표준 행(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). +- 날것의 `DataAccessException`(과 그 안의 SQLState·제약 이름)은 표현 계층에 닿지 않는다. `DataAccessException`을 잡는 repository 어댑터는 `PersistenceExceptionTranslator`로 번역해 carrier를 다시 던지고, 빈 결과면 원래 예외를 다시 던진다. +- PostgreSQL 행은 손으로 두 번째 표를 만들지 않고 `PostgreSqlState`와 classifier에 더한다(`SqlStateClassificationParityTest`). +- 커밋 중 결과를 모르는 실패는 `DB_COMPLETION_UNKNOWN`이고 절대 재시도하지 않는다. ## 영속 감사 계약 (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` 필드 없음)가 강제한다. +표와 자세한 계약은 [README.md](README.md) 「영속 감사 계약 (feature-persistence-auditing-contract)」 절이다. 지킬 것: -- **잡기 = 손으로 명시해 넣기(지금 기본).** 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를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다. +- 감사 필드는 `audit/AuditableEntity`에만 있고 도메인 aggregate에는 없다(ArchUnit `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`). +- repository 어댑터가 `Clock`과 `AuditContextPort`로 감사 값을 손으로 넣는다. bulk·native `@Query` UPDATE도 감사 열을 명시해 넣는다. ## MapStruct 생성 mapper 예외 (feature-architecture-enforcement-rules) diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index 4688c323..a2e0f42e 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -2,11 +2,10 @@ RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: `dev.caskeleton.adapter.persistence`. -허용/금지 의존, 테스트 명령, 그리고 **계약 테이블**(TransactionPort 모드표, SQLState → Error -Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 [AGENTS.md](AGENTS.md) 다. -이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 -"왜 이렇게 했나"가 궁금할 때 본다. 표가 AGENTS.md 에 있으면 여기서는 중복하지 않고 그 근거만 -적는다. +허용/금지 의존과 테스트 명령은 [AGENTS.md](AGENTS.md) 가 정본이다. **계약 테이블**(TransactionPort +모드표, SQLState → Error Code 매트릭스, auditing 계약, vendor·lane 표)은 이 문서 끝 「지역 규칙에서 옮긴 +표와 계약」 절이 정본이다. 나머지는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 +기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. ## capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env @@ -106,8 +105,8 @@ promotion gate, 생성하는 곳 없는 `JpaTransactionObservation` 등)은 `doc `TransactionTemplate` 은 문서상 thread-safe 지만 **mutable** 하다. 매 호출마다 propagation / readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로 (`WRITE` / `READ_ONLY` / `REQUIRES_NEW`) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가 -사라지고, 각 모드를 따로 감사(audit)할 수 있다. 세 템플릿 모두 isolation 을 `READ_COMMITTED` -로 고정한다(모드표는 AGENTS.md §TransactionPort implementation contract). +사라지고, 각 모드를 따로 감사(audit)할 수 있다. isolation 은 템플릿이 아니라 pool 에 `READ_COMMITTED` +로 고정한다(모드표와 이유는 아래 「TransactionPort 구현 계약」). ### 왜 `inRootWrite`가 별도 템플릿이나 `NEVER` propagation을 만들지 않나 `inRootWrite`의 실행 속성은 `inWrite`와 같은 `WRITE + REQUIRED + READ_COMMITTED`라 기존 @@ -179,8 +178,8 @@ Spring Boot 메인 클래스는 `dev.caskeleton.bootstrap` 에 있어서, `@Auto ## failure — 퍼시스턴스 실패 변환 SPI -매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 SSOT 는 AGENTS.md §Persistence -failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 적는다. +매트릭스(SQLState → `DB_*` 코드, category, http, retryable)의 정본은 아래 「영속 실패 번역 계약 +(feature-persistence-failure-baseline)」 절이다. 여기서는 SPI 구조와 fallback 근거만 적는다. ### SPI-pluggable 설계 (vendor 추출) `PersistenceExceptionTranslator` 는 exact-state → code 맵을 등록된 모든 `SqlStateErrorMapping` @@ -502,7 +501,7 @@ stream migration이 중단되면 history/registry/object 상태를 먼저 확인 ## lock — 분산 락 -provider 선택표(flag → bean → registry)의 SSOT 는 AGENTS.md(또는 app-bootstrap 와이어링)다. +provider 선택(flag → bean → registry)의 정본은 설정 코드 `lock/DistributedLockPersistenceConfig`(bean 이름 `distributedLockProvider`)다. 여기서는 어댑터/설정 결정 근거만 적는다. ### `LockRegistryDistributedLock` 계약 @@ -683,3 +682,215 @@ holder 가 락을 잡을 수 있다. - **검사는 이 guard 하나다.** prod만 보던 `JpaSchemaSafetyValidator`는 이 guard보다 늦게 돌아 한 번도 발동하지 않았고, 실제 prod 거부는 `PROFILE_MISMATCH`가 아닌 `IllegalStateException`이었다. 두 검사를 합치면서 guard가 `PROFILE_MISMATCH`를 던진다. + +## 지역 규칙에서 옮긴 표와 계약 + +이 절의 표와 계약은 지역 규칙 [AGENTS.md](AGENTS.md)에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 `AGENTS.md`를 같은 변경에서 고친다. + +### 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`가 늘지 않게 한다. + +### 플랫폼 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가 시작하지 못하면 건너뛰기가 +아니라 오류다 — 건너뛴 계약은 아무도 시험하지 않은 데이터베이스에 대해 성공을 알린다. + +### 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는 있으면 안 된다. + +### 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를 지나지 않으므로 계속 감사 열을 명시해 넣어야 한다. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java index e271b74a..a8175b20 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java @@ -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/AGENTS.md); everything else under the two roots is a + // ownership" table in src/application-core/README.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. diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java index 9a2d7991..76369981 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipRuleTest.java @@ -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/AGENTS.md) following it") + + " src/application-core/README.md) following it") .containsAll(TemplatePackageOwnership.APPLICATION_PACKAGES.keySet()); assertThat(domain) .as("TemplatePackageOwnership.DOMAIN_PACKAGES names a package that no longer exists") diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java index 460dfacb..a291a243 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnership.java @@ -15,7 +15,7 @@ import java.util.TreeSet; * owns each, and which packages are a service's business features. * *

This is the machine copy of the "Package ownership" tables in {@code - * src/application-core/AGENTS.md}, which are the rule book. A template change that adds, renames, + * src/application-core/README.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/AGENTS.md" + + " Rename the feature (template packages: src/application-core/README.md" + " \"Package ownership\").")); } } diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java index 45d436d7..690ceac8 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/TemplatePackageOwnershipDocumentTest.java @@ -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/AGENTS.md}, which people and agents read, and {@link + * src/application-core/README.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/AGENTS.md"; + private static final String RULE_BOOK = "src/application-core/README.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.*`) |"; diff --git a/src/application-core/AGENTS.md b/src/application-core/AGENTS.md index 56e4d359..1797cfb5 100644 --- a/src/application-core/AGENTS.md +++ b/src/application-core/AGENTS.md @@ -52,29 +52,9 @@ ## 계약 타입 -| 타입 | 용도 | -|---|---| -| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | -| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | -| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 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

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | -| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 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 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | +표와 자세한 계약은 [README.md](README.md) 「계약 타입」 절이다. 지킬 것: + +- 구체 inbound 포트는 `CommandUseCase`나 `QueryUseCase`를 상속하고, 그 구현은 `@UseCaseCapability`를 단다(ArchUnit `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY`). ## 알림 (NOTIF-ADR-005) @@ -107,113 +87,19 @@ architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가 ## 패키지 소유 (Package ownership) -이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. -`docs/manual/03-placement.md`가 이곳을 가리킨다. +표와 자세한 계약은 [README.md](README.md) 「패키지 소유 (Package ownership)」 절이다. 그 표가 템플릿 패키지 목록의 정본이다. 지킬 것: -- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, - `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 - 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. -- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 - 기능은 같은 패키지 트리에 들어가고, 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가 많아진다). +- 업무 기능은 루트마다 바로 아래에 기능 하나당 패키지 하나다(`dev.caskeleton.application.`, `dev.caskeleton.domain.` 등). `command`·`usecase`·`port` 하위 패키지를 두지 않는다. +- ``는 템플릿 패키지 이름이 아니다. 업무 코드를 템플릿 패키지에 넣지 않고, 템플릿 패키지는 기능 패키지를 import하지 않는다(`NamingConventionTest`). +- 템플릿 패키지를 더하거나 이름을 바꾸거나 지우면 README 표와 `TemplatePackageOwnership`을 같은 변경에서 고친다. `TemplatePackageOwnershipDocumentTest`가 둘을 대조한다. ## 정해진 유스케이스 모양 (Canonical use case shape) -```java -@RequiresPermission("user:register") -@UseCaseCapability( - transactionMode = TransactionMode.WRITE, - idempotency = Idempotency.KEYED, - repositoryAccess = RepositoryAccess.WRITE_REPOSITORY) -public class RegisterUserUseCase implements CommandUseCase { +표와 자세한 계약은 [README.md](README.md) 「정해진 유스케이스 모양 (Canonical use case shape)」 절이다. 지킬 것: - 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`, 두 검사 모두). +- 유스케이스는 평범한 Java이고 final이 아니다(web 어댑터가 CGLIB proxy로 `@RequiresPermission`을 강제한다). 조립 루트가 bean으로 만든다. application-core는 DI 프레임워크에 스스로 등록하지 않는다. +- 상태를 바꾸면 `@RequiresPermission`, 시스템만 부르면 `@SystemInvoked(reason = ...)`를 달고 bean으로 두지 않는다. 시스템 호출자 목록의 정본은 `docs/manual/07-authorization.md` 「시스템이 부르는 쓰기」다. +- 일은 `TransactionPort`로 감싼다(아래 「허용하는 트랜잭션 모양」). ## 허용하는 트랜잭션 모양 (Allowed transactional shapes) @@ -250,45 +136,10 @@ hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 ## 멱등성 (KEYED) — feature-rate-limit-idempotency-contract -`@UseCaseCapability(idempotency = Idempotency.KEYED)`는 **지원한다**. KEYED 유스케이스는 자기 일을 -`dev.caskeleton.application.idempotency.IdempotencyExecutor`로 감싼다. 소유자를 안전하게 지키는 -유일한 세대다. V1 `IdempotencyScope`/`tryBegin` API는 없어졌다. +표와 자세한 계약은 [README.md](README.md) 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」 절이다. 지킬 것: -- **범위(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는 -이 브랜치가 병합될 때 지웠다. +- KEYED 유스케이스는 일을 `IdempotencyExecutor`로 감싼다. 원본 `Idempotency-Key`는 이 계층에 들이지 않고 `IdempotencyScopeDigest`만 받는다. +- executor는 `composition:idempotency`가 만든다. 유스케이스나 서비스 설정에서 만들지 않는다. 운영에서 메모리 저장소는 금지다. ## 읽기·query 경로 (feature-application-query-bypass-contract) diff --git a/src/application-core/README.md b/src/application-core/README.md index 5aa32fe9..792fb1e0 100644 --- a/src/application-core/README.md +++ b/src/application-core/README.md @@ -656,3 +656,185 @@ leaf의 코드 Javadoc과 `docs/notification/`이 정본이다. R1 오케스트 `application-objectstorage`의 `objectstorage.content`로, 항상 함께 다니는 `CancellationView` 옆에 옮겼다. 다른 전송(HTTP client·gRPC·GraphQL)은 각자의 deadline 타입을 쓴다. - 포트 계약 `secret.testkit.SecretSourceContract`, fake `InMemorySecretSource`(testFixtures). + +## 지역 규칙에서 옮긴 표와 계약 + +이 절의 표와 계약은 지역 규칙 [AGENTS.md](AGENTS.md)에 있던 것을 2026-11-07에 옮겼다(지역 규칙은 200줄 이하). 규칙이 바뀌면 이 절과 `AGENTS.md`를 같은 변경에서 고친다. + +### 계약 타입 + +| 타입 | 용도 | +|---|---| +| `usecase.UseCase` | inbound 포트의 기반 타입. 구체 inbound 포트는 반드시 `CommandUseCase`나 `QueryUseCase`를 상속한다. | +| `usecase.CommandUseCase` | 쓰기 유스케이스의 inbound 포트. 구현은 반드시 `@UseCaseCapability`를 단다. | +| `usecase.QueryUseCase` | 읽기 전용 유스케이스의 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

` | 닫힌 정확한 record payload 타입, 정해진 component 순서, 로컬 schema identity·hash, provider 중립 descriptor 기여. | +| `messaging.event.IntegrationEventDraft

` | 로컬 인코딩 전의 타입 있는 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 전송 문맥이 모두 이 값을 싣는다. 전송 계층이 검증된 인증 데이터로만 만든다. | + +### 패키지 소유 (Package ownership) + +이 절은 **템플릿이 어떤 패키지를 가지는지**와 업무 기능이 어디로 가는지의 정본이다. +`docs/manual/03-placement.md`가 이곳을 가리킨다. + +- 업무 기능은 `dev.caskeleton.application.`다(그리고 `dev.caskeleton.domain.`, + `...adapter.inbound.web.`, `...bootstrap.autoconfigure.`). 루트마다 바로 아래에 + 기능 하나당 패키지 하나를 두고, `command`·`usecase`·`port` 하위 패키지를 두지 않는다. +- ``는 아래 템플릿 패키지 이름 중 하나가 **아니다**. 같은 이름의 템플릿 패키지 옆에 둔 + 기능은 같은 패키지 트리에 들어가고, 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 { + + 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`, 두 검사 모두). + +### 멱등성 (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는 +이 브랜치가 병합될 때 지웠다.