refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다

문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
This commit is contained in:
DongHyeonka
2026-11-11 22:15:42 +09:00
parent 1388c06a9f
commit 6a792b8144
263 changed files with 1057 additions and 907 deletions
+1 -1
View File
@@ -12,7 +12,7 @@ model: inherit
## 순서
1. 루트 `AGENTS.md`의 HARD-STOP과 지도를 읽는다.
2. 바뀐 파일마다 registry `src/config/architecture/modules.json`의 `source_path`로 leaf를 찾고, 가장 가까운 `AGENTS.md`(leaf, family)를 읽는다.
2. 바뀐 파일마다 registry `gradle/modules.json`의 `source_path`로 leaf를 찾고, 가장 가까운 `AGENTS.md`(leaf, family)를 읽는다.
3. 운영 소스의 import를 본다: 순수성(`domain-core`·`application-*`·`shared-contract`의 framework import), inbound의 repository·Spring Data·entity 사용, inbound DTO가 core로 들어가는지, `dev.caskeleton.*` 주인 leaf가 `allowed_dependencies`(전이 포함)에 있는지.
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 가지 않았는지 본다(HARD-STOP 4). 이것은 import로 안 보이니 코드를 읽는다.
5. `build.gradle`·registry를 바꿨으면 새 edge가 registry에 있고 방향 그림(`app-bootstrap → adapter → application-core → domain-core`)을 거스르지 않는지 본다.
+1 -1
View File
@@ -23,6 +23,6 @@ GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 by
## 코드만 보고는 헷갈리는 것
- 저장소 파일을 읽는 테스트는 태그가 있어야 한다. 문서와 대조하면 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow·Compose를 읽으면 `repository-contract`(PR)다. 태그 없이 저장소를 읽으면 `test`에서 실패한다. 이유는 `src/build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」다.
- 저장소 파일을 읽는 테스트는 태그가 있어야 한다. 문서와 대조하면 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow·Compose를 읽으면 `repository-contract`(PR)다. 태그 없이 저장소를 읽으면 `test`에서 실패한다. 이유는 `build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」다.
- 성능 lane에는 단언을 끄는 스위치가 없다. `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 하나라도 있으면 테스트 전에 실패한다.
- 테스트는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절).
+6 -6
View File
@@ -6,13 +6,13 @@ paths:
- "src/**/application*.yml"
- "src/**/application*.yaml"
- "src/**/config/module-defaults/**"
- "src/.env.example"
- "src/.env.local.example"
- "src/Dockerfile"
- ".env.example"
- ".env.local.example"
- "Dockerfile"
- "compose.yaml"
- "compose/**"
- "src/**/compose/**"
- "src/app-bootstrap/compose-lanes/**"
- "src/bootstrap/app/compose-lanes/**"
---
# 설정과 런타임 규칙
@@ -23,12 +23,12 @@ paths:
- 새 설정 그룹은 typed settings class로 만든다. 흩어진 `@Value`보다 configuration properties와 settings class를 쓴다.
- 새 settings class를 만들면 바인딩·값 검증 테스트를 더한다.
- capability 모듈의 설정 prefix는 하나다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor다(`docs/manual/10-capabilities.md` 기준 4, Redis 예외 포함).
- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다(권한 설정이 막는다). 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다.
- `.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다(권한 설정이 막는다). 키 계약은 `.env.example`과 `docs/registries/env-keys.yaml`이다.
- `application.yml`은 환경마다 안전한 기본값과 분명한 자리표시자만 담는다.
## Docker·Compose
- `src/Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다.
- `Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다.
- container 안에서 필요한 profile, port, env 키를 문서나 예시 설정에 반영한다.
- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다(「개발 환경」과 lane overlay의 차이는 `docs/work/reference/terms.md`). 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`).
- Docker는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절).
+1 -1
View File
@@ -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/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다.
3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application/core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다.
4. 뼈대: 노트북에서는 `scripts/new-feature.sh <FeatureName> --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에서 같은 계약을 상속한다.
+32 -46
View File
@@ -1,68 +1,54 @@
# feature-container-runtime-contract — .dockerignore for src/ build context
# feature-container-runtime-contract — .dockerignore for the repository-root build context
#
# The docker build context is src/ (the Gradle root). This file excludes build
# noise that must not enter the image build context, while keeping everything
# the builder stage needs to resolve dependencies and run bootJar.
# The docker build context is the repository root, which is the Gradle root. The builder stage needs
# the Gradle build and the code, nothing else: not the documentation, the CI files, the development
# Compose environment or the scripts. So this file lets in only what the build reads (the first
# block), then takes the build noise back out of it (the rest). Rules apply in order and the last
# match wins.
# ---- Build recipe itself ----------------------------------------------------
# The Dockerfile is supplied with `-f` and is never needed inside the context. Leaving it in means
# `COPY . .` embeds it in the image AND makes every Dockerfile edit — a comment included — invalidate
# the cached dependency-resolution layer, which costs a full Gradle re-resolve (~3 min) for a change
# that affects nothing the builder reads.
Dockerfile
Dockerfile.*
.dockerignore
# ---- Version control --------------------------------------------------------
.git
.gitignore
.gitattributes
# ---- What the builder reads ------------------------------------------------
# Everything at the top is out, then the Gradle build is let back in: the wrapper, the root build
# scripts and their settings lockfile, gradle/ (wrapper, version catalog, module registry, test-image
# list), the convention plugins, the code-check tool settings and the layer code.
*
!gradlew
!gradlew.bat
!gradle/
!gradle.properties
!settings.gradle
!settings-gradle.lockfile
!build.gradle
!build-logic/
!config/
!src/
# The env contract examples, which were in the context while it was src/. No real .env: see below.
!.env.example
!.env.local.example
# ---- Gradle build output ----------------------------------------------------
# Exclude all module build/ directories; the builder stage produces them inside the container.
build/
**/build/
.gradle/
**/.gradle/
**/bin/
# ---- IDE / editor files -----------------------------------------------------
.idea/
**/.idea/
*.iml
.vscode/
**/*.iml
**/.vscode/
*.eclipse
.project
.classpath
.settings/
# ---- Documentation / governance (not needed for image build) ----------------
# Root CLAUDE.md and AGENTS.md are governance docs; not needed at build time.
*.md
docs/
**/.project
**/.classpath
**/.settings/
# ---- Environment / secrets (NEVER bake secrets into image layers) -----------
.env
**/.env
*.env
**/*.env
**/.env.lane
# ---- OS artifacts -----------------------------------------------------------
.DS_Store
**/.DS_Store
Thumbs.db
**/Thumbs.db
# ---- Test reports and coverage ----------------------------------------------
**/test-results/
**/reports/
**/jacoco/
# ---- Explicitly keep (negation rules to be safe) ----------------------------
# The Gradle wrapper, source trees, and build configuration are needed.
# Negation rules are not strictly required because the above globs don't
# accidentally exclude src/*, but listed for clarity.
!gradlew
!gradlew.bat
!gradle/
!**/src/
!**/build.gradle
!settings.gradle
+3 -3
View File
@@ -1,8 +1,8 @@
# =============================================================================
# The public catalogue of every environment variable this application reads.
#
# Generated from docs/registries/env-keys.yaml, which is the SSOT. Copy this file to src/.env and
# fill in the values your deployment needs; src/.env is gitignored because it is operator input,
# Generated from docs/registries/env-keys.yaml, which is the SSOT. Copy this file to .env and
# fill in the values your deployment needs; .env is gitignored because it is operator input,
# not a build input.
#
# Secret-classified keys are left empty on purpose. An example that carries a working credential
@@ -156,7 +156,7 @@ APP_REDIS_TIMEOUT_SCRIPT=1s
# reference empty and anonymous access not accepted, the application refuses to start while Redis
# is on; with the advanced one empty, scripts run as the application account and startup warns. The
# Compose Redis lanes connect as the fixture accounts of compose/redis/acl/lane-fixture-accounts.acl (the
# Redis comment in src/app-bootstrap/compose-lanes/compose-profile-contracts.json).
# Redis comment in src/bootstrap/app/compose-lanes/compose-profile-contracts.json).
APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE=
APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=false
APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE=
+6 -6
View File
@@ -1,8 +1,8 @@
# =============================================================================
# A local example for a service that selected some capabilities. Copy to src/.env.local and edit.
# A local example for a service that selected some capabilities. Copy to .env.local and edit.
#
# The default composition is web-only. A capability is on when its runtimeOnly line in
# app-bootstrap/build.gradle is uncommented, and each needs the infrastructure its Compose profile
# src/bootstrap/app/build.gradle is uncommented, and each needs the infrastructure its Compose profile
# provides. The values below are what each one needs once selected; a missing required value is
# refused at startup, naming the key. APP_*_ENABLED=false turns a selected capability off.
# =============================================================================
@@ -17,7 +17,7 @@ APP_DATASOURCE_USERNAME=ca_skeleton
APP_DATASOURCE_PASSWORD=
APP_DATASOURCE_DDL_AUTO=validate
# Messaging (Kafka): on when app-bootstrap/build.gradle carries
# Messaging (Kafka): on when src/bootstrap/app/build.gradle carries
# `runtimeOnly project(':adapter:outbound:messaging-kafka')`; APP_MESSAGING_ENABLED=false turns it off.
APP_MESSAGING_KAFKA_BROKERS=localhost:9092
@@ -25,14 +25,14 @@ APP_MESSAGING_KAFKA_BROKERS=localhost:9092
APP_OUTBOX_ENABLED=false
APP_OUTBOX_RELAY_ENABLED=false
# Mongo: on when its runtimeOnly line is in app-bootstrap/build.gradle. active-profile is required
# Mongo: on when its runtimeOnly line is in src/bootstrap/app/build.gradle. active-profile is required
# and selects exactly one client.
APP_PERSISTENCE_MONGO_ACTIVE_PROFILE=standard-uri
SPRING_MONGODB_URI=mongodb://localhost:27017/ca_skeleton
# GraphQL: on when its runtimeOnly line is in app-bootstrap/build.gradle. The deployment mode must
# GraphQL: on when its runtimeOnly line is in src/bootstrap/app/build.gradle. The deployment mode must
# match the runtime environment (local -> LOCAL).
APP_GRAPHQL_DEPLOYMENT_MODE=LOCAL
# Notification: on when its line and the persistence-jpa line are selected (it stores requests
# relationally). It then needs the eight key purposes and their ids listed in src/.env.example.
# relationally). It then needs the eight key purposes and their ids listed in .env.example.
+5 -12
View File
@@ -7,7 +7,7 @@
# machine nothing else is using: the runner takes one job at a time, and `needs` puts them after
# every other heavy job (owner decision 2026-11-07).
#
# Which lanes a stage means is decided by its Gradle task (src/build.gradle). The stage jobs
# Which lanes a stage means is decided by its Gradle task (build.gradle). The stage jobs
# (`main`, `integration`, `performance`) run it as one line; `verifyStrictLaneStages` fails a pull
# request that changes that line, its condition, or adds a way for it to pass quietly.
name: main
@@ -32,10 +32,6 @@ concurrency:
group: main-${{ github.ref }}
cancel-in-progress: false
defaults:
run:
working-directory: src
env:
# Reuse would hand one lane a container another lane had already faulted.
TESTCONTAINERS_REUSE_ENABLE: "false"
@@ -79,7 +75,7 @@ jobs:
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: bash ../scripts/ci/verify-configuration-cache.sh
- run: bash scripts/ci/verify-configuration-cache.sh
# Every committed Markdown link, external URLs included. A documentation check, so the main stage
# (owner decision 2026-09-16); scripts/check-docs.py checks the relative links on every pull request.
@@ -95,7 +91,7 @@ jobs:
--no-progress
--root-dir .
README.md
src/README.md
docs/build.md
'src/**/README.md'
'src/**/CLAUDE.md'
'docs/**/*.md'
@@ -110,7 +106,6 @@ jobs:
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/ci/trivy-scan.sh filesystem
working-directory: .
# Experimental by design: the result is reported, never used to block anything.
http3-experimental:
@@ -182,7 +177,6 @@ jobs:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: bash scripts/ci/redis-topology.sh ${{ matrix.topology }} ${{ matrix.redis }}
working-directory: .
# The one fileserver environment a pull request cannot provide: a real NFSv4 server.
fileserver-nfs-ambiguity:
@@ -272,7 +266,7 @@ jobs:
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :adapter:outbound:objectstorage:objectStorageAwsQualificationTest
# Every blocking Compose runtime lane, on the qualification image (src/Dockerfile
# Every blocking Compose runtime lane, on the qualification image (Dockerfile
# COMPOSITION=qualification: every capability module present).
compose-smoke:
if: ${{ github.event_name != 'push' }}
@@ -280,8 +274,7 @@ jobs:
timeout-minutes: 180
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
working-directory: .
- run: bash scripts/run-compose-runtime-smoke.sh --matrix src/bootstrap/app/compose-lanes/compose-profile-contracts.json
# Load, slow-client, shutdown, pool and resource bounds. Last, after every other heavy job of the
# run, so the bounds are measured on a runner that is not building something else.
+1 -7
View File
@@ -1,6 +1,6 @@
# Pull-request stage. Everything here blocks a merge, and the branch protection requires one check:
# `done`. Which leaves, lanes and checks the stage means is decided by the Gradle task `prCheck`
# (src/build.gradle), not here; `verifyStrictLaneStages` fails when this job stops running it as one
# (build.gradle), not here; `verifyStrictLaneStages` fails when this job stops running it as one
# line (docs/work/reference/gates.md).
#
# The adapter container lanes are not here: they run in main.yml on every push to main (owner
@@ -18,10 +18,6 @@ concurrency:
group: pr-${{ github.ref }}
cancel-in-progress: true
defaults:
run:
working-directory: src
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
@@ -43,7 +39,6 @@ jobs:
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/ci/trivy-scan.sh filesystem
working-directory: .
# The one required check. A job added above joins `needs` here, and the branch protection does
# not change.
@@ -53,7 +48,6 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Require every job of this stage to have succeeded
working-directory: .
env:
RESULTS: ${{ needs.gradle.result }} ${{ needs.vulnerabilities.result }}
run: |
+2 -13
View File
@@ -24,10 +24,6 @@ concurrency:
group: release-${{ github.ref }}
cancel-in-progress: false
defaults:
run:
working-directory: src
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
@@ -88,7 +84,6 @@ jobs:
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: python3 scripts/verify-httpclient-docs.py
working-directory: .
# One job per Stable PostgreSQL major: one job for three majors was one job for one major, because
# the platform starts only the first selected version. persistence-jpa's
@@ -167,9 +162,6 @@ jobs:
pinned_reference: ${{ steps.push.outputs.pinned_reference }}
runs-on: ubuntu-latest
timeout-minutes: 90
defaults:
run:
working-directory: .
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# The tag is the release identity; a tag that does not parse stops the release here. A manual
@@ -205,7 +197,7 @@ jobs:
SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
export SOURCE_DATE_EPOCH
DOCKER_BUILDKIT=1 docker build \
--file src/Dockerfile \
--file Dockerfile \
--tag "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" \
--tag "${IMAGE_REPOSITORY}:sha-${GITHUB_SHA}" \
--build-arg RELEASE_VERSION="${RELEASE_VERSION}" \
@@ -213,7 +205,7 @@ jobs:
--build-arg GIT_SHA="${GITHUB_SHA}" \
--build-arg SOURCE_URL="${SOURCE_URL}" \
--label org.opencontainers.image.created="$(git log -1 --format=%cI)" \
src
.
# The SBOM is printed and kept in the log before the blocking scan, so the inventory of an image
# that is refused still exists. A vulnerable image is never pushed: the push comes after.
- name: Inventory and scan the release image
@@ -249,9 +241,6 @@ jobs:
if: ${{ github.ref_type == 'tag' }}
runs-on: ubuntu-latest
timeout-minutes: 30
defaults:
run:
working-directory: .
env:
PINNED_REFERENCE: ${{ needs.app-image-release.outputs.pinned_reference }}
steps:
+1 -1
View File
@@ -9,6 +9,6 @@
# Public security and compatibility baselines require an explicit maintainer review.
/docs/security/ @DongHyeonka
/src/config/architecture/modules.json @DongHyeonka
/gradle/modules.json @DongHyeonka
*.approved.json @DongHyeonka
*.approved.txt @DongHyeonka
+1 -1
View File
@@ -79,7 +79,7 @@ mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mi
Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
(`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가
`cd src && ./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께
`./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께
커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를
막는다.
+1 -1
View File
@@ -5,7 +5,7 @@
## 검증
- [ ] 바꾼 모듈마다 `:<changed-leaf>:check`를 돌렸다.
- [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다.
- [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다.
- [ ] registry에 없는 production 모듈 의존을 더하지 않았다.
- [ ] 의존성을 바꿨으면 다시 만든 `gradle.lockfile`과 strict lock 검증을 함께 넣었다.
- [ ] Trivy 예외(suppression)에는 소유자가 검토한 이유와 90일 안의 만료일이 있다.
+3
View File
@@ -29,6 +29,9 @@ build/
# Written per run by the runtime-smoke wrapper; never committed.
/.env.lane
# bootRun's file log when APP_LOG_FILE_ENABLED=true: APP_LOG_FILE_PATH is relative to the repository root.
/logs/
# Local tool output (graphify knowledge graph, Playwright MCP snapshots).
graphify-out/
.playwright-mcp/
+6 -6
View File
@@ -1,6 +1,6 @@
# AGENTS.md — 백엔드 템플릿의 정본
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. 비전 전문은 `docs/vision.md`(소유자가 쓴다), 문제 정의는 `docs/problem-statement.md`다.
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. 비전 전문은 `docs/vision.md`(소유자가 쓴다), 문제 정의는 `docs/problem-statement.md`다.
## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다
@@ -14,11 +14,11 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버
## 지도
- Gradle 루트는 `src/`다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registry `src/config/architecture/modules.json`이다. 문서는 leaf 개수를 적지 않는다.
- Gradle 루트는 저장소 루트다. `src/`에는 계층 코드만 있다(`domain/`·`application/`·`adapter/`·`bootstrap/`·`shared-contract/`). leaf 목록·폴더·Gradle path·허용 의존의 정본은 registry `gradle/modules.json`이다. Gradle path는 폴더와 다르다(`:app-bootstrap`은 `src/bootstrap/app`). 문서는 leaf 개수를 적지 않는다.
- 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다.
- 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `src/build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다.
- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(`docs/work/reference/related-repos.md`). `src/composition/*`는 조립만 한다.
- capability는 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`.
- 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다.
- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(`docs/work/reference/related-repos.md`). `src/bootstrap/`은 조립 계층이다(조립 루트 `app`과 조립만 하는 `composition:*` leaf).
- capability는 `src/bootstrap/app/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`.
## 맡은 일
@@ -28,7 +28,7 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버
- 진입점은 `scripts/verify.sh <단계>`다. 단계 이름은 workflow와 같다(`pr`·`main`·`nightly`·`release`, 그리고 `docs`·`leaf`·`app`·`round`). Gradle·Docker가 드는 단계는 스크립트가 desktop으로 옮겨 잠금 아래에서 돌린다.
- leaf 하나: `scripts/verify.sh leaf <gradle-path>`. 경로는 registry의 `gradle_path`다. 기억이나 폴더 이름으로 짐작하지 않는다.
- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때, `src/`에서), 단계 묶음은 `scripts/verify.sh pr` 등. 게이트 고르기는 `docs/work/reference/gates.md`.
- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때), 단계 묶음은 `scripts/verify.sh pr` 등. 게이트 고르기는 `docs/work/reference/gates.md`.
- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북에서 돈다).
## 일하는 방식
+8 -8
View File
@@ -3,7 +3,7 @@
# feature-container-runtime-contract — multi-stage image build
#
# Build requirements:
# docker build -f src/Dockerfile src/ -t caskeleton:local \
# docker build -f Dockerfile . -t caskeleton:local \
# --build-arg RELEASE_VERSION=1.2.3 \
# --build-arg BUILD_VERSION=1.2.3+a1b2c3d4e5f6 \
# --build-arg GIT_SHA=a1b2c3d4e5f6 \
@@ -29,7 +29,7 @@ FROM eclipse-temurin:21-jdk-jammy@sha256:801b7e1a9c4befaf82bf9a2a58025ef43a7694b
ARG RELEASE_VERSION
ARG GIT_SHA
WORKDIR /build/src
WORKDIR /build
# Copy the Gradle wrapper and every module's build descriptor + dependency lockfile FIRST,
# so the expensive dependency-resolution layer is cached and only re-runs when a build.gradle
@@ -99,8 +99,8 @@ RUN case "${COMPOSITION}" in \
# every Dockerfile names the exact Gradle-staged artifact path rather than selecting a JAR, and the
# input here is that same fixed path Gradle wrote. Nothing in this stage may pick a JAR by pattern.
RUN java -Djarmode=tools \
-jar /build/src/app-bootstrap/build/docker/application.jar \
extract --layers --destination /build/src/app-bootstrap/build/docker/extracted
-jar /build/src/bootstrap/app/build/docker/application.jar \
extract --layers --destination /build/src/bootstrap/app/build/docker/extracted
# ---- Stage 2: runtime image -------------------------------------------------
# JRE-only slim image (D3: no full JDK in production image).
@@ -176,10 +176,10 @@ WORKDIR /app
#
# All four land in /app: the extracted application.jar is a thin JAR whose manifest Class-Path
# points at ./lib, which is what the dependencies layer unpacks to.
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/dependencies/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/spring-boot-loader/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/snapshot-dependencies/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/application/ ./
COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/dependencies/ ./
COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/spring-boot-loader/ ./
COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/snapshot-dependencies/ ./
COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/application/ ./
USER app
+30 -26
View File
@@ -1,33 +1,38 @@
# ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿
ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(`AGENTS.md`)과 같은 절차(`docs/work/`)로 일한다. 라이브러리 버전은 `src/gradle/libs.versions.toml`이 정한다.
ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(`AGENTS.md`)과 같은 절차(`docs/work/`)로 일한다. 라이브러리 버전은 `gradle/libs.versions.toml`이 정한다.
## 프로젝트 구조
저장소 루트에는 정해진 것만 둔다. 허용 목록 밖의 최상위 항목은 `scripts/check-repo-layout.py`가 PR에서 막는다.
저장소 루트가 Gradle 루트다. 빌드 도구와 빌드 파일은 루트에, 코드는 `src/`에 둔다. 허용 목록 밖의 최상위 항목은 `scripts/check-repo-layout.py`가 PR에서 막는다.
| 폴더 | 하는 일 | 먼저 읽을 곳 |
| 폴더·파일 | 하는 일 | 먼저 읽을 곳 |
| --- | --- | --- |
| `src/` | Gradle 루트. 모든 코드, 빌드 규칙, registry | [src/README.md](src/README.md) |
| `src/` | 계층별 앱 코드. leaf(Gradle 프로젝트)만 있다 | 아래 표 |
| `settings.gradle`, `build.gradle`, `gradlew` | Gradle 빌드. 단계 태스크(`prCheck`·`mainCheck` 등)와 registry를 읽는 settings | [docs/build.md](docs/build.md) |
| `gradle/` | wrapper, 버전 카탈로그 `libs.versions.toml`, 모듈 registry `modules.json`, 시험 컨테이너 이미지 목록 `container-images.properties` | [gradle/README.md](gradle/README.md) |
| `build-logic/` | 빌드 규칙(convention plugin, registry 검사) | [build-logic/README.md](build-logic/README.md) |
| `config/` | 코드 검사 도구 설정(checkstyle, spotbugs) | — |
| `Dockerfile`, `.env.example` | 릴리스 이미지(빌드 context는 저장소 루트), env 계약 | [docs/build.md](docs/build.md) |
| `docs/` | 문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | [docs/README.md](docs/README.md) |
| `scripts/` | Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 저장소 배치·문서 검사 | `scripts/bootstrap-local.sh`, `scripts/new-feature.sh` |
| `scripts/` | Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 검증 진입점, 저장소 배치·문서 검사 | `scripts/bootstrap-local.sh`, `scripts/new-feature.sh`, `scripts/verify.sh` |
| `compose.yaml` | 개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 |
| `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) |
| `.github/` | workflow, 공용 action, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) |
| `.gitea/` | workflow(`pr`·`main`·`release`)와 공용 action | [docs/work/reference/gates.md](docs/work/reference/gates.md) |
| `.github/` | CODEOWNERS, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) |
`src/` 아래 폴더는 계층 leaf, 조립, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다.
`src/` 아래 폴더는 계층이다. 같은 계층의 leaf는 그 계층 폴더 아래에 있다. leaf 목록·폴더·Gradle path·허용 의존은 registry `gradle/modules.json`이 정한다. Gradle path는 폴더와 다르다(`:application-core`는 `src/application/core`, `:composition:outbox-relay`는 `src/bootstrap/outbox-relay`).
| 폴더 | 책임 | 기본 조립에 들어가나 |
| --- | --- | --- |
| `domain-core/` | 도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 |
| `application-core/` | command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 |
| `application-fileserver/`, `application-notification/`, `application-objectstorage/` | capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 |
| `shared-contract/` | 저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 |
| `adapter/inbound/` | HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | `web`만 들어간다 |
| `adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 |
| `composition/` | 조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
| `app-bootstrap/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
| `build-logic/`, `config/`, `gradle/` | 빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 |
| `src/domain/core/` | 도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 |
| `src/application/core/` | command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 |
| `src/application/fileserver/`, `src/application/notification/`, `src/application/objectstorage/` | capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 |
| `src/shared-contract/` | 저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 |
| `src/adapter/inbound/` | HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | `web`만 들어간다 |
| `src/adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 |
| `src/bootstrap/app/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
| `src/bootstrap/` 의 나머지 | 조립만 하는 `composition:*` leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다.
@@ -61,17 +66,17 @@ curl -fsS http://localhost:8080/api/healthcheck
docker compose --profile '*' down
```
환경 변수는 `src/.env`(로컬 실행 입력)와 `src/.env.example`(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)이다.
환경 변수는 `.env`(로컬 실행 입력)와 `.env.example`(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 [docs/build.md](docs/build.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)이다.
## 기능 켜고 끄기
기본 조립(`bootJar`)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, `support`·`identifier`뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. `cd src && ./gradlew :app-bootstrap:bootRun`으로 바로 실행할 수 있다.
기본 조립(`bootJar`)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, `support`·`identifier`뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. `./gradlew :app-bootstrap:bootRun`으로 바로 실행할 수 있다.
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src/app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄씩으로 있다.
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src/bootstrap/app/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄씩으로 있다.
- 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다.
- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다.
- 줄마다 필요한 env 키와 끄는 키: [src/README.md](src/README.md) 「기능 추가 = 한 줄 + env」 표.
- 줄마다 필요한 env 키와 끄는 키: [docs/build.md](docs/build.md) 「기능 추가 = 한 줄 + env」 표.
- 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md).
- capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: [docs/manual/10-capabilities.md](docs/manual/10-capabilities.md).
@@ -91,19 +96,18 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` |
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.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/bootstrap/app/README.md)).
## 검증
명령은 `src/`에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 `gradle_path`에서 읽는다.
명령은 저장소 루트에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 `gradle_path`에서 읽는다.
```bash
cd src
./gradlew :app-bootstrap:check --console=plain
./gradlew architectureCheck --console=plain
```
`./gradlew test`는 모든 leaf의 `test`를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 [docs/work/reference/gates.md](docs/work/reference/gates.md)가 정한다. 게이트 태스크 하나하나의 설명은 [src/README.md](src/README.md) 「build.gradle — 빌드 / 검증 게이트」다.
`./gradlew test`는 모든 leaf의 `test`를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 [docs/work/reference/gates.md](docs/work/reference/gates.md)가 정한다. 게이트 태스크 하나하나의 설명은 [docs/build.md](docs/build.md) 「build.gradle — 빌드 / 검증 게이트」다.
문서를 고쳤으면 저장소 루트에서 `python3 scripts/check-docs.py`를 돌린다. 규칙은 [docs/README.md](docs/README.md) 「문서 검사」다.
@@ -111,7 +115,7 @@ cd src
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
1. `src/settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
1. `settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
```bash
@@ -123,7 +127,7 @@ cd src
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
6. 라이브러리 패키지 `dev.cakit.*`은 바꾸지 않는다. 별도 repo에서 받는 라이브러리의 패키지이고, 2번이 바꾸는 `dev.caskeleton`과 이름이 겹치지 않게 정했다. 라이브러리 목록은 [관련 저장소](docs/work/reference/related-repos.md)다.
7. Docker 이미지 이름과 애플리케이션 이름(`spring.application.name`)을 새 서비스 기준으로 바꾼다.
8. `src/.env.example`, `src/.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다.
8. `.env.example`, `.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다.
9. README와 운영 문서를 새 서비스 설명으로 고친다.
복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`).
+7 -7
View File
@@ -1,13 +1,13 @@
# build-logic — Gradle 정책 권위
registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. `src/build-logic/`, `src/settings.gradle`, `src/build.gradle`, `src/config/architecture/modules.json`을 고칠 때 읽는다. 루트 `AGENTS.md` HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 `docs/work/reference/gates.md`다.
registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. `build-logic/`, `settings.gradle`, `build.gradle`, `gradle/modules.json`을 고칠 때 읽는다. 루트 `AGENTS.md` HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 `docs/work/reference/gates.md`다.
## 정본 넷
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 `library_groups`, 행마다 `allowed_libraries`. 계층 leaf 행은 비워 둔다. 설명은 `src/config/architecture/README.md`). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `prCheck`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 그것을 workflow job에 묶는 `strictLaneStages`, 버전·리비전.
- `gradle/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 `library_groups`, 행마다 `allowed_libraries`. 계층 leaf 행은 비워 둔다. 설명은 `gradle/README.md`). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
- `settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
- `build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.
- `build.gradle`: 루트 라이프사이클(`ci`, `prCheck`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 그것을 workflow job에 묶는 `strictLaneStages`, 버전·리비전.
## 저장소 파일을 읽는 테스트
@@ -25,10 +25,10 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을
## 단계 job의 모양
- `verifyStrictLaneStages --dry-run`(PR)은 `explicitOnly`가 아닌 strict lane마다 `src/build.gradle`의 `strictLaneStages`가 선언한 단계 태스크 하나의 계획에 들어 있는지 본다(그래프 검사).
- `verifyStrictLaneStages --dry-run`(PR)은 `explicitOnly`가 아닌 strict lane마다 `build.gradle`의 `strictLaneStages`가 선언한 단계 태스크 하나의 계획에 들어 있는지 본다(그래프 검사).
- 단계마다 선언한 workflow job은 step의 `run: ./gradlew <단계> <옵션>` 줄을 가지고, 다른 step `run:`도 셸 문법 없는 `./gradlew` 한 줄이며, 선언 밖의 `if:`, 선언한 조건이 `!cancelled()`·`always()`가 아닌데 `needs:`, `continue-on-error`·`shell:`·`defaults:`, 따옴표 키·flow 형식, 이 빌드 밖의 `working-directory`가 없다. workflow는 선언한 이벤트로, 선언한 필터 한 줄만 달고 시작하고, PR 단계 job 하나가 이 검사를 돌린다(형식 검사, 셸을 해석하지 않는다).
- 단계를 더하거나 job을 바꾸면 `strictLaneStages`의 `stage` 줄과 workflow를 같은 커밋에서 고친다.
## 테스트
- `./gradlew -p build-logic test --console=plain`(`src/`에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다.
- `./gradlew -p build-logic test --console=plain`(저장소 루트에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다.
+3 -4
View File
@@ -15,7 +15,7 @@ capability를 가진 leaf의 시험이고, 그 시험이 읽는 파일은 그
| `ca.java-library` / `ca.spring-library` / `ca.spring-config` | 평범한 라이브러리와 Spring 라이브러리를 위한 Java·품질 규약의 leaf 단위 조합 |
| `ca.platform-module` | 플랫폼 성격의 Java 라이브러리 leaf(지금 `adapter:outbound:httpclient`)가 무엇인가: `java-library`. 이 규약을 쓰던 메시징·gRPC 플랫폼은 2026-11-08에 별도 repo `messaging-library`·`grpc-library`로 옮겼다(gRPC BOM 규약 `ca.grpc-platform-module`도 함께) |
| `ca.strict-test-lane` | 「이름 댄 시험이 돌았고 건너뛴 것이 없다」를 보는 유일한 장치: tag·이름·자기 source set으로 고른 `Test` lane이 아무것도 실행하지 않거나, `requires` 클래스를 빠뜨리거나, (`rejectSkipped`이면) 무엇이든 건너뛰면 실패한다. `performance()` lane은 언제나 건너뛰기를 거절하고 `performance.assertions.enabled=true`로 돈다. 빌드(`-P`, `GRADLE_OPTS`)나 lane이 다른 값을 넣으면 시험이 돌기 전에 실패한다. `mainStage()`는 tag로 고른 lane을 `test`에서 빼 leaf의 `mainCheck`로 옮긴다. `explicitOnly(reason)`는 바깥 입력이 필요한 lane을 모든 묶음 태스크에서 빼고, 묶음 태스크가 그 이유를 출력한다. 시험 source set을 더 두려면 leaf에 Gradle `jvm-test-suite` suite로 선언한다(`testing { suites { … } }`). suite 이름을 딴 lane은 그 suite 자신의 `Test` 태스크를 엄격하게 만들고, `ca.java-conventions`는 모든 suite에 BOM의 JUnit을 준다 |
| `ca.strict-lane-stages` (주 빌드의 루트) | lane 장치의 나머지 절반: `verifyStrictLaneStages --dry-run`은 그 빌드의 `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계 태스크 어느 것의 계획에도 없으면 실패한다(계획은 Gradle 자신의 것). 단계마다 그것을 돌리는 workflow job(파일·이벤트·job·옵션·조건)도 선언하고, 그 job이 정해진 한 줄 모양인지 고정 문자열로 본다(`src/build-logic/AGENTS.md` 「단계 job의 모양」). 2026-11-08까지 이 자리에 workflow YAML과 bash를 해석하던 판독기(`WorkflowGradleInvocations`·`ShellScript`·`TaskSelectors`)가 있었고, workflow를 셋으로 접으면서 지웠다 |
| `ca.strict-lane-stages` (주 빌드의 루트) | lane 장치의 나머지 절반: `verifyStrictLaneStages --dry-run`은 그 빌드의 `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계 태스크 어느 것의 계획에도 없으면 실패한다(계획은 Gradle 자신의 것). 단계마다 그것을 돌리는 workflow job(파일·이벤트·job·옵션·조건)도 선언하고, 그 job이 정해진 한 줄 모양인지 고정 문자열로 본다(`build-logic/AGENTS.md` 「단계 job의 모양」). 2026-11-08까지 이 자리에 workflow YAML과 bash를 해석하던 판독기(`WorkflowGradleInvocations`·`ShellScript`·`TaskSelectors`)가 있었고, workflow를 셋으로 접으면서 지웠다 |
| `ca.redis-topology-lane` | `main.yml`의 nightly `redis-topology` job(`scripts/ci/redis-topology.sh`)이 돌리는 Redis topology lane(모드 고르기, `-P` 속성 검증, 모드별 필수 클래스) |
| `ca.api-surface` | 읽기 전용 공개 API surface 검증과 따로 둔 갱신 태스크. leaf의 `check`에 배선한다(소유자 결정 20). 다른 leaf의 import를 리뷰한 adopter 부분집합(`adopterBaseline`)에 묶을 수도 있다 |
| `ca.config-contract` | app-bootstrap의 `verifyEnvKeys`(지운 build-tools included build에서 옮겼다. 소유자 결정 4가 그 태스크를 app-bootstrap에 둔다) |
@@ -26,7 +26,7 @@ capability를 가진 leaf의 시험이고, 그 시험이 읽는 파일은 그
| 클래스 | 가지는 것 |
| --- | --- |
| `dev.caskeleton.buildlogic.ModuleRegistry` | `config/architecture/modules.json`을 읽고 검증하기 |
| `dev.caskeleton.buildlogic.ModuleRegistry` | `gradle/modules.json`을 읽고 검증하기 |
| `dev.caskeleton.buildlogic.RequiredTestExecution` | 「이 빌드가 이름을 댄 시험은 실제로 돌았어야 한다」는 단 하나의 판정 |
| `dev.caskeleton.buildlogic.JavaPublicTypes` | 공개 최상위 타입. 정규식으로 맞추지 않고 javac로 파싱한다 |
@@ -44,7 +44,7 @@ JMH benchmark는 커뮤니티 플러그인 `me.champeau.jmh`를 쓴다. `ca.qual
| `ca.jpa-test-lanes` | `adapter/outbound/persistence-jpa/build.gradle`에 선언한 lane |
| `ca.test-jvm-agents`, `quarantineTest` | `ca.java-conventions`. quarantine 묶음에는 시험이 없었다 |
| `ca.jmh-benchmarks` | `me.champeau.jmh` |
| build-tools `ca.jpa-evidence`, `ca.jpa-qualification`(+ `junit` 증거 읽기) | 소유자 결정 4: persistence-jpa `JpaReadinessRegistryTest`, 인용한 시나리오를 모두 요구하고 건너뛰기를 거절하는 readiness lane, `config/jpa/release-registry.json`을 묶는 leaf의 `jpaReleaseQualification` |
| build-tools `ca.jpa-evidence`, `ca.jpa-qualification`(+ `junit` 증거 읽기) | 소유자 결정 4: persistence-jpa `JpaReadinessRegistryTest`, 인용한 시나리오를 모두 요구하고 건너뛰기를 거절하는 readiness lane, `src/adapter/outbound/persistence-jpa/release/release-registry.json`을 묶는 leaf의 `jpaReleaseQualification` |
| build-tools `ca.config-contract` | 바꾸지 않고 여기로 옮겼다 |
| `ca.public-path-snapshot` | app-bootstrap `PublicPathSnapshotTest`(lane `publicPathSnapshotTest`, 루트 별칭 `verifyPublicPathSnapshot`) |
| `ca.archive-hygiene` | 치울 것이 없다: leaf 버전이 더는 revision을 싣지 않으니 낡은 추적 가능 jar가 생기지 않는다 |
@@ -54,7 +54,6 @@ JMH benchmark는 커뮤니티 플러그인 `me.champeau.jmh`를 쓴다. `ca.qual
## 규약 시험하기
```bash
cd src
./gradlew -p build-logic test --console=plain
```
@@ -22,7 +22,7 @@ import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.json.JsonMapper;
/**
* Typed representation of config/architecture/modules.json.
* Typed representation of gradle/modules.json.
*
* <p>{@code libraryGroups} are the Maven group prefixes of the libraries this repository's owner
* publishes from other repositories (design-docs {@code repo-structure/05-library-repos.md} 10.2절,
@@ -30,11 +30,10 @@ public final class ArchitecturePlugin implements Plugin<Project> {
@Override
public void apply(Project project) {
Project root = project.getRootProject();
// The Gradle root (src/) owns the registry; the repository root is its parent, and every
// source_path in the registry is relative to the repository root.
File mainBuildDirectory = root.getProjectDir();
File registryFile = new File(mainBuildDirectory, "config/architecture/modules.json");
File repositoryRoot = mainBuildDirectory.getParentFile();
// The Gradle root is the repository root: it owns the registry, and every source_path in the
// registry is relative to it.
File repositoryRoot = root.getProjectDir();
File registryFile = new File(repositoryRoot, "gradle/modules.json");
ModuleRegistry registry = ModuleRegistry.read(registryFile, repositoryRoot);
List<ModuleRegistry.Module> modules = registry.modulesForBuild("main");
List<String> registryViolations = registryViolations(registry, modules);
@@ -58,7 +58,7 @@ public abstract class VerifyCleanArchitectureDependenciesTask extends DefaultTas
List<String> registryViolations = getRegistryViolations().get();
if (!registryViolations.isEmpty()) {
throw new GradleException(
"config/architecture/modules.json declares impossible edges:\n "
"gradle/modules.json declares impossible edges:\n "
+ String.join("\n ", registryViolations));
}
@@ -66,7 +66,7 @@ public abstract class VerifyCleanArchitectureDependenciesTask extends DefaultTas
if (!unregistered.isEmpty()) {
throw new GradleException(
"These build scripts have no registry entry, so the build does not include them and no"
+ " gate compiles or tests them. Register each in config/architecture/modules.json"
+ " gate compiles or tests them. Register each in gradle/modules.json"
+ " or delete it:\n "
+ String.join("\n ", unregistered));
}
@@ -143,7 +143,7 @@ public abstract class VerifyModuleDependencyDirectionTask extends DefaultTask {
+ new TreeSet<>(getAllowedLibraries().get())
+ ".\nDirect and compile-visible production dependencies on a library of the groups "
+ libraryGroups
+ " must be listed in the module's allowed_libraries (config/architecture/modules.json).");
+ " must be listed in the module's allowed_libraries (gradle/modules.json).");
}
}
}
@@ -20,12 +20,12 @@ public final class ConfigContractPlugin implements Plugin<Project> {
task -> {
task.setGroup("verification");
task.setDescription(
"Verifies shipped configuration APP_ references, src/.env.example, and env-keys.yaml stay registered.");
"Verifies shipped configuration APP_ references, .env.example, and env-keys.yaml stay registered.");
task.getEnvFile().fileValue(root.file(".env.example"));
task.getConfigurationFiles()
.from(
root.fileTree(
root.file("app-bootstrap/src/main/resources"),
root.file("src/bootstrap/app/src/main/resources"),
tree -> {
tree.include("application*.yml");
tree.include("config/*.yml");
@@ -34,12 +34,14 @@ public final class ConfigContractPlugin implements Plugin<Project> {
// (read by ModuleDefaultsEnvironmentPostProcessor), or config/<name>.yml for
// the leaves that load their own. They are shipped configuration whenever the
// module is selected, so their APP_ references are held to the same registry.
// The leaves live under src/ (the Gradle root is the repository root, which also
// holds docs, scripts and, on a developer checkout, .claude/worktrees).
root.fileTree(
root.getProjectDir(),
root.file("src"),
tree -> {
tree.include("*/**/src/main/resources/config/*.yml");
tree.include("*/**/src/main/resources/config/module-defaults/*.yml");
tree.exclude("app-bootstrap/**");
tree.exclude("bootstrap/app/**");
tree.exclude("**/build/**");
}));
// What an operator edits or runs: the development Compose file and the lane
@@ -52,26 +54,26 @@ public final class ConfigContractPlugin implements Plugin<Project> {
// by hand.
task.getOperatorFiles()
.from(
root.file("../compose.yaml"),
root.file("compose.yaml"),
root.fileTree(
root.file("app-bootstrap/compose-lanes"),
root.file("src/bootstrap/app/compose-lanes"),
tree -> {
tree.include("*.yaml");
// The lane-only services: their APP_* variables belong to the smoke
// clients, not to this application.
tree.exclude("lane-services.yaml");
}),
root.file("app-bootstrap/src/main/resources/logback-spring.xml"),
root.file("app-bootstrap/compose-lanes/compose-profile-contracts.json"),
root.file("../scripts/run-compose-runtime-smoke.sh"));
task.getRegistryFile().fileValue(root.file("../docs/registries/env-keys.yaml"));
root.file("src/bootstrap/app/src/main/resources/logback-spring.xml"),
root.file("src/bootstrap/app/compose-lanes/compose-profile-contracts.json"),
root.file("scripts/run-compose-runtime-smoke.sh"));
task.getRegistryFile().fileValue(root.file("docs/registries/env-keys.yaml"));
// No module path here: the typed properties come from the configuration metadata on
// the classpath the composition root wires (metadataClasspath), so this task knows no
// leaf by name (review 2026-11-03 RR-06-10).
task.getProductionSources()
.from(
root.fileTree(
root.getProjectDir(),
root.file("src"),
tree -> {
tree.include("**/src/main/**/*.java");
tree.include("**/src/main/**/*.yml");
@@ -147,7 +147,7 @@ public final class EnvContractVerifier {
failUnlessEmpty(
difference(requiredPlaceholders, envKeys),
"shipped configuration references required env absent from src/.env.example: ");
"shipped configuration references required env absent from .env.example: ");
List<EnvRegistryRow> registryRows = parseRegistryRows(registryFile);
Set<String> registryAppKeys = new TreeSet<>();
@@ -159,14 +159,14 @@ public final class EnvContractVerifier {
failUnlessEmpty(
difference(registryAppKeys, envKeys),
"docs/registries/env-keys.yaml registers APP_ keys absent from src/.env.example, so an "
"docs/registries/env-keys.yaml registers APP_ keys absent from .env.example, so an "
+ "adopter copying the example never sees them: ");
Set<String> envAppKeys = new TreeSet<>();
envKeys.stream().filter(name -> name.startsWith("APP_")).forEach(envAppKeys::add);
failUnlessEmpty(
difference(envAppKeys, registryAppKeys),
"src/.env.example declares APP_ keys absent from docs/registries/env-keys.yaml "
".env.example declares APP_ keys absent from docs/registries/env-keys.yaml "
+ "(registry is the SSOT for APP_ keys): ");
failUnlessEmpty(
difference(applicationAppReferences, registryAppKeys),
@@ -268,7 +268,7 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
// property rather than a JVM argument: a strict lane's own `jvmArgs` replace the argument list,
// and this used to be repeated in 28 lanes for that reason (review 2026-11-01 O-10b).
//
// The container images the lanes start come from config/testing/container-images.properties,
// The container images the lanes start come from gradle/container-images.properties,
// each as `ca.test.image.<key>`, with the file as an input (review 2026-11-01 08-04).
File images = containerImageCatalog(project);
Map<String, String> containerImages = containerImages(images);
@@ -303,7 +303,7 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
public static final String CONTAINER_IMAGE_PROPERTY_PREFIX = "ca.test.image.";
private static File containerImageCatalog(Project project) {
File catalog = project.getRootProject().file("config/testing/container-images.properties");
File catalog = project.getRootProject().file("gradle/container-images.properties");
if (!catalog.isFile()) {
throw new GradleException("Missing test container image catalog: " + catalog);
}
@@ -11,8 +11,8 @@ public final class ArchitectureRegistrySettingsPlugin implements Plugin<Settings
@Override
public void apply(Settings settings) {
try {
File repositoryRoot = settings.getSettingsDir().getParentFile().getCanonicalFile();
File registryFile = new File(settings.getSettingsDir(), "config/architecture/modules.json");
File repositoryRoot = settings.getSettingsDir().getCanonicalFile();
File registryFile = new File(settings.getSettingsDir(), "gradle/modules.json");
ModuleRegistrySettingsInstaller.install(settings, registryFile, repositoryRoot, "main");
} catch (IOException exception) {
throw new UncheckedIOException("failed to resolve architecture registry paths", exception);
@@ -12,7 +12,7 @@ import org.gradle.api.file.DirectoryProperty;
*
* <pre>
* strictLaneStages {
* workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows')
* workflowDirectory = layout.projectDirectory.dir('.gitea/workflows')
* stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'
* stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]',
* job: 'main', options: '--continue'
@@ -214,6 +214,29 @@ class ModuleRegistryTest {
assertEquals(List.of("adapter/gamma/build.gradle"), unregistered);
}
@Test
@DisplayName("Gradle 루트가 저장소 루트이면 included build와 점 폴더(다른 worktree)는 건너뛰고 src/의 미등록 스크립트만 찾는다")
void buildScriptsAreFoundFromTheRepositoryRootWithoutEnteringOtherCheckouts() throws Exception {
// given
Files.writeString(root.resolve("build.gradle"), "");
Files.writeString(root.resolve("src/alpha/build.gradle"), "");
Files.writeString(root.resolve("src/beta/build.gradle"), "");
Files.createDirectories(root.resolve("src/adapter/gamma"));
Files.writeString(root.resolve("src/adapter/gamma/build.gradle"), "");
Files.createDirectories(root.resolve("build-logic"));
Files.writeString(root.resolve("build-logic/settings.gradle"), "");
Files.writeString(root.resolve("build-logic/build.gradle"), "");
Files.createDirectories(root.resolve(".claude/worktrees/copy/src/delta"));
Files.writeString(root.resolve(".claude/worktrees/copy/src/delta/build.gradle"), "");
ModuleRegistry registry = read(valid());
// when
List<String> unregistered = registry.unregisteredBuildScripts(root.toFile());
// then
assertEquals(List.of("src/adapter/gamma/build.gradle"), unregistered);
}
private File write(String json) {
try {
Path file = root.resolve("modules.json");
@@ -31,8 +31,8 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
void aSecondCompositionRootIsGovernedByTheSameDependencyPolicy(
@TempDir Path temporaryRoot) throws IOException {
Path repository = temporaryRoot.resolve("repository");
Path project = repository.resolve("src");
Files.createDirectories(project.resolve("config/architecture"));
Path project = repository;
Files.createDirectories(project.resolve("gradle"));
Files.createDirectories(project.resolve("a"));
Files.createDirectories(project.resolve("example-app"));
@@ -54,20 +54,20 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
""",
UTF_8);
Files.writeString(
project.resolve("config/architecture/modules.json"),
project.resolve("gradle/modules.json"),
"""
{
"modules": [
{
"id": "a",
"gradle_path": ":a",
"source_path": "src/a",
"source_path": "a",
"allowed_dependencies": []
},
{
"id": "example-app",
"gradle_path": ":example-app",
"source_path": "src/example-app",
"source_path": "example-app",
"allowed_dependencies": []
}
]
@@ -230,8 +230,8 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
void aLayerModuleThatAllowsALibraryIsARegistryViolation(@TempDir Path temporaryRoot)
throws IOException {
// given
Path project = temporaryRoot.resolve("repository").resolve("src");
Files.createDirectories(project.resolve("config/architecture"));
Path project = temporaryRoot.resolve("repository");
Files.createDirectories(project.resolve("gradle"));
Files.createDirectories(project.resolve("domain-core"));
Files.writeString(
project.resolve("settings.gradle"), "rootProject.name = 'main'\ninclude 'domain-core'\n", UTF_8);
@@ -240,7 +240,7 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
"plugins { id 'ca.architecture' }\nsubprojects { apply plugin: 'java-library' }\n",
UTF_8);
Files.writeString(
project.resolve("config/architecture/modules.json"),
project.resolve("gradle/modules.json"),
"""
{
"library_groups": ["dev.cakit"],
@@ -248,7 +248,7 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
{
"id": "domain-core",
"gradle_path": ":domain-core",
"source_path": "src/domain-core",
"source_path": "domain-core",
"allowed_dependencies": [],
"allowed_libraries": ["dev.cakit.demo:demo-api"]
}
@@ -300,8 +300,8 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
private static Path libraryFixture(Path temporaryRoot, String declaration, String cLibraries)
throws IOException {
Path repository = temporaryRoot.resolve("repository");
Path project = repository.resolve("src");
Files.createDirectories(project.resolve("config/architecture"));
Path project = repository;
Files.createDirectories(project.resolve("gradle"));
Files.createDirectories(project.resolve("c"));
Path maven = temporaryRoot.resolve("maven");
pom(maven, "dev.cakit.demo", "demo-core", "");
@@ -339,7 +339,7 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
.formatted(maven.toUri(), declaration),
UTF_8);
Files.writeString(
project.resolve("config/architecture/modules.json"),
project.resolve("gradle/modules.json"),
"""
{
"library_groups": ["dev.cakit"],
@@ -347,7 +347,7 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
{
"id": "c",
"gradle_path": ":c",
"source_path": "src/c",
"source_path": "c",
"allowed_dependencies": [],
"allowed_libraries": %s
}
@@ -379,8 +379,8 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
private static Path fixture(Path temporaryRoot, boolean allowTransitiveA) throws IOException {
Path repository = temporaryRoot.resolve("repository");
Path project = repository.resolve("src");
Files.createDirectories(project.resolve("config/architecture"));
Path project = repository;
Files.createDirectories(project.resolve("gradle"));
for (String module : new String[] {"a", "b", "c"}) {
Files.createDirectories(project.resolve(module));
}
@@ -409,26 +409,26 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
String cAllowed = allowTransitiveA ? "[\"b\", \"a\"]" : "[\"b\"]";
Files.writeString(
project.resolve("config/architecture/modules.json"),
project.resolve("gradle/modules.json"),
"""
{
"modules": [
{
"id": "a",
"gradle_path": ":a",
"source_path": "src/a",
"source_path": "a",
"allowed_dependencies": []
},
{
"id": "b",
"gradle_path": ":b",
"source_path": "src/b",
"source_path": "b",
"allowed_dependencies": ["a"]
},
{
"id": "c",
"gradle_path": ":c",
"source_path": "src/c",
"source_path": "c",
"allowed_dependencies": %s
}
]
@@ -53,7 +53,7 @@ class VerifyNoIgnoredSourcePackagesFunctionalTest {
Path project = fixture(temporaryRoot, "a");
source(project, "a/src/main/java/example/Ok.java");
Files.writeString(
project.getParent().resolve(".git"),
project.resolve(".git"),
"gitdir: " + temporaryRoot.resolve("missing-git-dir") + "\n",
UTF_8);
@@ -65,10 +65,10 @@ class VerifyNoIgnoredSourcePackagesFunctionalTest {
.contains("verifyNoIgnoredSourcePackages: `git check-ignore` exited 128");
}
/** One registered leaf with an extra {@code integrationTest} source set, under {@code src/}. */
/** One registered leaf with an extra {@code integrationTest} source set, in the Gradle root. */
private static Path fixture(Path temporaryRoot, String leaf) throws IOException {
Path project = temporaryRoot.resolve("repository").resolve("src");
Files.createDirectories(project.resolve("config/architecture"));
Path project = temporaryRoot.resolve("repository");
Files.createDirectories(project.resolve("gradle"));
Files.createDirectories(project.resolve(leaf));
Files.writeString(
project.resolve("settings.gradle"),
@@ -89,14 +89,14 @@ class VerifyNoIgnoredSourcePackagesFunctionalTest {
""",
UTF_8);
Files.writeString(
project.resolve("config/architecture/modules.json"),
project.resolve("gradle/modules.json"),
"""
{
"modules": [
{
"id": "%1$s",
"gradle_path": ":%1$s",
"source_path": "src/%1$s",
"source_path": "%1$s",
"allowed_dependencies": []
}
]
@@ -167,7 +167,7 @@ class EnvContractVerifierTest {
List.of("APP_REDIS_"),
List.of()));
assertTrue(failure.getMessage().contains("required env absent from src/.env.example"));
assertTrue(failure.getMessage().contains("required env absent from .env.example"));
assertTrue(failure.getMessage().contains("APP_REQUIRED_SECONDARY"));
}
@@ -190,7 +190,7 @@ class EnvContractVerifierTest {
List.of("APP_REDIS_"),
List.of()));
assertTrue(failure.getMessage().contains("required env absent from src/.env.example"));
assertTrue(failure.getMessage().contains("required env absent from .env.example"));
assertTrue(failure.getMessage().contains("APP_REQUIRED"));
}
@@ -19,8 +19,7 @@ class PlatformModuleConventionTest {
writeCatalog();
// java-conventions refuses a build without the container image catalog (review 2026-11-01
// 08-04); a fixture build that starts no container still has to carry one, even empty.
Files.createDirectories(projectDir.resolve("config/testing"));
Files.writeString(projectDir.resolve("config/testing/container-images.properties"), "");
Files.writeString(projectDir.resolve("gradle/container-images.properties"), "");
Files.writeString(
projectDir.resolve("settings.gradle"),
"""
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Stream;
import org.gradle.testkit.runner.BuildResult;
import org.gradle.testkit.runner.GradleRunner;
@@ -16,8 +17,10 @@ import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;
/**
* A two-project build: a root that declares two stages, and a leaf with strict lanes. The workflows
* live where the real repository keeps them, one directory above the Gradle root.
* A two-project build: a root that declares two stages, and a leaf with strict lanes. Most tests keep
* the Gradle root one directory below the workflows (a build in {@code src/}, as this template had
* it until 2026-11-11); the repository-root tests move the same build up, as the template has it
* now, where this build's directory is {@code .}.
*/
class StrictLaneStagesFunctionalTest {
private static final String PR_WORKFLOW =
@@ -338,6 +341,52 @@ class StrictLaneStagesFunctionalTest {
assertThat(result.getOutput()).contains("stage :integrationCheck: option -x is not one of");
}
@Test
@DisplayName("Gradle 루트가 저장소 루트이면 working-directory 없는 단계 job으로 통과한다")
void aBuildAtTheRepositoryRootPassesWithJobsThatRunInTheRepositoryRoot() throws Exception {
// given
moveBuildToRepositoryRoot();
// when
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").build();
// then
assertThat(result.getOutput()).contains("every strict lane is in a stage its workflow job runs");
}
@Test
@DisplayName("Gradle 루트가 저장소 루트인데 job이 src에서 돌면 이 빌드의 폴더 . 을 대며 실패한다")
void aBuildAtTheRepositoryRootRefusesAJobThatRunsInSrc() throws Exception {
// given
moveBuildToRepositoryRoot();
workflow("pr.yml", PR_WORKFLOW);
// when
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail();
// then
assertThat(result.getOutput())
.contains("pr.yml job gradle runs in src, not in this build's directory .");
}
/** The same build at the repository root, beside .gitea/, with workflows that set no directory. */
private void moveBuildToRepositoryRoot() throws Exception {
for (String file :
List.of(
"settings.gradle", "build.gradle", "leaf/build.gradle", "leaf/src/test/java/LaneTest.java")) {
Path target = repository.resolve(file);
Files.createDirectories(target.getParent());
Files.writeString(
target,
Files.readString(gradleRoot.resolve(file))
.replace("'../.gitea/workflows'", "'.gitea/workflows'"));
}
gradleRoot = repository;
String sourceDirectory = "defaults:\n run:\n working-directory: src\n";
workflow("pr.yml", PR_WORKFLOW.replace(sourceDirectory, ""));
workflow("main.yml", MAIN_WORKFLOW.replace(sourceDirectory, ""));
}
private void leafLanes(String lanes) throws Exception {
Files.writeString(
gradleRoot.resolve("leaf/build.gradle"),
+3 -3
View File
@@ -151,7 +151,7 @@ tasks.register('testQualityCheck') {
tasks.register('verifyFeatureScaffold', Exec) {
group = 'verification'
description = 'Generates features with scripts/new-feature.sh in a scratch copy and runs the gates they must pass.'
workingDir = rootProject.projectDir.parentFile
workingDir = rootProject.projectDir
commandLine 'bash', 'scripts/verify-feature-scaffold.sh'
}
@@ -196,7 +196,7 @@ tasks.register('mainCheck') {
// The checks outside Gradle that the pull-request stage runs. Each is a script with its own tests
// (scripts/tests); these tasks only give them a stage, so pr.yml and scripts/verify.sh run the same
// one line. Repository root as working directory: that is where the scripts expect to start.
def repositoryRoot = rootProject.projectDir.parentFile
def repositoryRoot = rootProject.projectDir
tasks.register('verifyComposeProfiles', Exec) {
group = 'verification'
description = 'Renders every Compose lane and checks it renders exactly what it declares.'
@@ -241,7 +241,7 @@ tasks.register('prCheck') {
// through its category aggregate; no workflow line names it. The performance lane runs only
// nightly, after the other heavy jobs, on a runner nothing else is using (owner decision 2026-11-07).
strictLaneStages {
workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows')
workflowDirectory = layout.projectDirectory.dir('.gitea/workflows')
stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'
stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', job: 'main',
options: '--continue'
+6 -6
View File
@@ -21,7 +21,7 @@
# mail mailpit (STARTTLS 필수) SMTP 발송
#
# 이 파일이 마운트하는 보조 파일은 compose/ 아래에 있다. compose lane(테스트)은 이 파일을 바탕으로
# 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/app-bootstrap/compose-lanes/에 있다.
# 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/bootstrap/app/compose-lanes/에 있다.
# 경로는 모두 이 파일이 있는 저장소 루트 기준이다.
#
# auth profile은 keycloak client secret 파일이 있어야 뜬다. lane은 실행마다 만들고 지운다. 손으로 띄울
@@ -63,7 +63,7 @@ x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256
services:
app:
build:
context: src/
context: .
dockerfile: Dockerfile
args:
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
@@ -76,12 +76,12 @@ services:
# The composition is in the tag, so a lane's qualification image is never reused as the
# default one (Compose reuses a matching tag instead of building).
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this
# Optional, because .env is operator input and a fresh clone does not have one. Before this
# was marked optional, untracking that file made `docker compose config` fail outright on a
# clone. The tracked contract is src/.env.example; copy it. A compose lane does not depend on it:
# clone. The tracked contract is .env.example; copy it. A compose lane does not depend on it:
# its values go into a generated `environment:` block, which outranks every env_file.
env_file:
- path: ./src/.env
- path: ./.env
required: false
ports:
- "${APP_SERVER_PORT:-8080}:8080"
@@ -147,7 +147,7 @@ services:
# ---- PostgreSQL --------------------------------------------------------------
# Published on the loopback interface only, so a host-side run (`./gradlew :app-bootstrap:bootRun`,
# IDE) reaches the same database the containerised app reaches over the internal network. The
# port is the one src/.env.example's APP_DATASOURCE_URL names.
# port is the one .env.example's APP_DATASOURCE_URL names.
db:
profiles:
- jpa
+1 -1
View File
@@ -49,7 +49,7 @@ Redis ACL 파일은 완전한 `user` 줄만 받는다. 주석도, 줄 이어 쓰
## 누가 `lane-fixture-accounts.acl`을 읽나
- Redis 구성(topology) lane: `src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`
- Redis를 켜는 애플리케이션 Compose lane: `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의
- Redis를 켜는 애플리케이션 Compose lane: `src/bootstrap/app/compose-lanes/compose-profile-contracts.json`의
`local-redis`, `all-adapters`
- 개발 환경의 `redis` 서비스(루트 `compose.yaml`)
+5 -4
View File
@@ -98,6 +98,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
| 문서 | 무엇 |
| --- | --- |
| [build.md](build.md) | 빌드 스크립트(`build.gradle`의 게이트 태스크)와 환경 변수(`.env.example`) 참조(2026-11-11 재배치 전에는 `src` 폴더의 README였다) |
| [capability-status.md](capability-status.md) | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) |
| [storage-capability-boundary.md](storage-capability-boundary.md) | 파일 서버와 객체 저장소가 각각 맡는 경계 |
| [vision.md](vision.md) | 비전: 누구의 어떤 문제를 푸나, 성공하면 무엇이 달라지나, 속도보다 먼저 지킬 것(세 문장, 소유자가 쓴다. 에이전트는 읽기만 한다) |
@@ -175,8 +176,8 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
`grep -rn '<바꾼 이름>' docs src --include=*.md`.
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·태스크는 `capability-status.md` 「제거된 코드」나
`upgrade/`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다.
- 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는
registry(`src/config/architecture/modules.json`)를 가리킨다.
- 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `gradle/libs.versions.toml`, leaf 목록과 개수는
registry(`gradle/modules.json`)를 가리킨다.
- 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이
어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고,
`readme` 검사가 그 목록(`scripts/check-docs.py`의 `README_SECTIONS`)을 본다.
@@ -192,7 +193,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
| `link` | 살아 있는 문서의 마크다운 상대 링크가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 |
@@ -212,5 +213,5 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
## 여기에 없는 것
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/`(workflow가 부르는 것은 `scripts/ci/`)에 있다.
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다.
- 모듈 레지스트리·Gradle 정책은 `gradle/modules.json` 과 `build.gradle` 이 소유한다.
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다.
@@ -4,7 +4,7 @@
- 상태: 채택
- 작성일: 2026-09-07
- 요약: 공유 테스트 코드는 java-test-fixtures 한 가지 방식으로 둔다는 결정이다.
- 현재 정본: `src/build-logic/README.md`
- 현재 정본: `build-logic/README.md`
<!-- 머리 블록 끝 -->
# ADR-BUILD-001: 공유 시험 코드의 표준은 `java-test-fixtures`다
@@ -11,7 +11,7 @@
- 상태: 채택
- 날짜: 2026-08-30
- 범위: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json`
- 범위: `:grpc:*`, `:grpc-advanced:*`, `gradle/modules.json`
## 배경
@@ -16,7 +16,7 @@
> **대체됨.** 정규식 `.proto` 검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제 `:grpc:grpc-contract`
> (`src/grpc/grpc-contract/src/main/proto`)에 있고 Gradle protobuf 플러그인(`com.google.protobuf`, 버전은
> `src/gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된
> `gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된
> 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다. `buf lint`와 `buf breaking`
> (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)은 CI의 `.github/workflows/ci-quality-gates.yml`
> job `grpc-proto-buf`에서 돈다. proto organization은 `caskeleton`이다(예전에는 `hyeonworks`). 아래 글은 원래 결정의
@@ -19,7 +19,7 @@
## 배경
실시간 연결 플랫폼 설계는 스스로를 `modules/websocket` 아래 Gradle 모듈 열여덟 개로 모델링하고, 모듈마다 순수성 등급과 허용 의존
집합을 선언한다. 이 저장소의 `src/config/architecture/modules.json`은 leaf 목록을 가진 실패하면 닫히는 registry다. leaf 열여덟 개를
집합을 선언한다. 이 저장소의 `gradle/modules.json`은 leaf 목록을 가진 실패하면 닫히는 registry다. leaf 열여덟 개를
더하는 것은 자기 결정이 필요한 크기의 registry 변경이고, HARD-STOP #5가 그것을 은근슬쩍 하는 것을 금지한다.
이 저장소의 앞선 플랫폼 셋 — JPA, GraphQL, HTTP 플랫폼 — 이 같은 상황을 만났고 같은 방식으로 풀었다.
@@ -30,7 +30,7 @@
| R1 | `dev.caskeleton.application.notification` (직속) | public type 100개 |
| Platform | `dev.caskeleton.application.notification.platform..` | 신규 |
`application-core/CLAUDE.md`는 R1을 "R1 canonical"이라 부르고,
`src/application/core/CLAUDE.md`는 R1을 "R1 canonical"이라 부르고,
`docs/notification/migration-guide.md`는 R0 → platform 이행만 설명하며 R1의 처분을 전혀 다루지 않는다.
`Channel`, plan, dispatch, receipt/evidence 모델이 두 namespace에 중복 존재하고 둘 사이에 production
bridge도 import도 없다.
@@ -45,7 +45,7 @@ bridge도 import도 없다.
이유는 능력이 아니라 증거다. platform은 durable acceptance, fenced claim, event ledger, projection,
reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며
스스로 그렇게 선언한다 — `application-core/CLAUDE.md`가 "R1 application contract proven with fakes.
스스로 그렇게 선언한다 — `src/application/core/CLAUDE.md`가 "R1 application contract proven with fakes.
It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime
wiring qualification"(fake로 증명한 R1 애플리케이션 계약이다. PostgreSQL schema·locking, provider 프로토콜, 암호
검증기, 런타임 배선 검증은 주장하지 않는다)이라고 적어 둔 그대로다.
+20 -20
View File
@@ -1,9 +1,9 @@
# src — 빌드 스크립트 / 환경 변수 참조
# 빌드 스크립트 / 환경 변수 참조
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [AGENTS.md](../AGENTS.md),
저장소 루트가 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [AGENTS.md](../AGENTS.md),
모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다.
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
이 문서는 [build.gradle](../build.gradle) 과 [.env.example](../.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명한다.
@@ -51,8 +51,8 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
app 기동(Flyway 포함) → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, 리뷰
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가
끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `src/.env.example`은 커밋된
env 계약이고 `src/.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을
끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `.env.example`은 커밋된
env 계약이고 `.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을
함께 검사한다.
### 추적 가능한 버전과 의존성 잠금
@@ -94,7 +94,7 @@ archive task 자체는 timestamp 비보존·재현 가능한 file order·고정
### `verifyCleanArchitectureDependencies`
- **하는 일.** [config/architecture/modules.json](config/architecture/modules.json)의
- **하는 일.** [gradle/modules.json](../gradle/modules.json)의
`allowed_dependencies`를 읽고, 실제 Gradle 프로젝트 의존(`api` / `implementation` /
`compileOnly` / `runtimeOnly`)이 그 범위를 벗어나면 빌드를 실패시킨다.
- **JSON registry가 의존 방향의 SSOT이다.** 새 모듈이나 새 production 의존 edge를 추가하면
@@ -102,7 +102,7 @@ archive task 자체는 timestamp 비보존·재현 가능한 file order·고정
같은 registry를 읽고, 등록되지 않은 leaf나 허용되지 않은 edge를 fail-closed로 거부한다.
조립 루트가 받는 모듈의 별도 membership 검사는 없다. `app-bootstrap`의 `allowed_dependencies`
밖의 모듈은 방향 게이트가 막고, 무엇이 실제로 실리는지는 `app-bootstrap/build.gradle`의 의존성이
밖의 모듈은 방향 게이트가 막고, 무엇이 실제로 실리는지는 `src/bootstrap/app/build.gradle`의 의존성이
정한다.
세 opt-in inbound transport의 test-only composition, 실제 wire 경계, positive-count/zero-skip 증거는
@@ -131,7 +131,7 @@ Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돈다
태스크는 app-bootstrap에 유지, `build-tools` included build는 비워서 삭제).
- **하는 일.** `docs/registries/env-keys.yaml`, app-bootstrap의 `application*.yml` + `config/*.yml`,
capability 모듈이 싣는 `config/*.yml`·`config/module-defaults/*.yml`(기본 조립에 없어도 검사한다),
`src/.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지한다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를
`.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지한다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를
실패시킨다.
- **막으려는 것 3가지.** (1) 필수 env 가 조용히 누락되는 것, (2) 더 이상 쓰지 않는 stale env 키가
`.env.example` 에 남는 것, (3) 실제로 쓰는 `APP_` 키가 registry 에 등록되지 않고 빠져나가는 것.
@@ -143,15 +143,15 @@ Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돈다
- **C.** `.env.example` 의 모든 `APP_` 키는 registry 에 `- name: <KEY>` 행이 있어야 한다.
- **`SPRING_*` 키는 왜 registry 추적 대상이 아닌가.** `SPRING_*` 는 Spring Boot 가 정의한 native 키라
프로젝트가 소유한 계약이 아니다. 그래서 C 검사는 일부러 `APP_` prefix 로만 범위를 좁혔다.
- **비고.** `src/.env.example`이 커밋된 환경 계약이고 `src/.env`는 로컬 실행용 입력이다.
- **비고.** `.env.example`이 커밋된 환경 계약이고 `.env`는 로컬 실행용 입력이다.
### `verifyPublicPathSnapshot`
- **하는 일.** deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킨다.
- **배경.** 이 앱은 deny-by-default이다. 즉 `SECURITY_PUBLIC_PATHS` 가 먹이는 명시적 `permitAll()`
경로를 **제외한** 모든 요청은 인증을 요구한다
(`app-bootstrap/src/main/resources/config/security.yml` → `SecuritySettings.publicPaths()` →
`SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `src/.env` 였고 문서만 그대로 남아 있었다.
(`src/bootstrap/app/src/main/resources/config/security.yml` → `SecuritySettings.publicPaths()` →
`SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `.env` 였고 문서만 그대로 남아 있었다.
스냅샷 플러그인이 실제로 읽는 파일은 `config/security.yml`이다
(`build-logic/.../publicpath/PublicPathSnapshotPlugin.java`).
이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점이다.
@@ -207,7 +207,7 @@ drift하기 시작하면 그때 자동화한다. 진짜 항목을 상대로, 진
## .env — 환경 변수 레퍼런스
`spring-dotenv` 가 `src/.env` 를 읽어 외부화 설정을 주입한다(`bootRun` 의 working dir 가 `src/` 라
`spring-dotenv` 가 `.env` 를 읽어 외부화 설정을 주입한다(`bootRun` 의 working dir 가 저장소 루트라
이 파일이 잡힌다). 아래는 섹션별 키 설명이다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동
필요)로 간주한다.
@@ -253,10 +253,10 @@ drift하기 시작하면 그때 자동화한다. 진짜 항목을 상대로, 진
기본 조립(`bootJar`)에는 web, 관측(actuator·metrics·tracing·로그), `domain-core`·`application-core`·
`shared-contract`, `adapter:outbound:support`·`adapter:outbound:identifier`만 들어 있다. DB·Redis·
Kafka 없이 기동한다. 나머지 기능은 `app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄로
Kafka 없이 기동한다. 나머지 기능은 `src/bootstrap/app/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄로
있다.
- **켜기:** 그 줄의 주석을 풀고, 아래 env를 `src/.env`에 넣는다. 모듈이 classpath에 있으면 켜진다.
- **켜기:** 그 줄의 주석을 풀고, 아래 env를 `.env`에 넣는다. 모듈이 classpath에 있으면 켜진다.
- **끄기:** 줄을 지운다. 모듈의 bean·설정·의존성이 함께 빠진다. 줄은 두고 잠시 끄려면 "끄는 키"를
`false`로 준다(모든 키의 기본값은 `true`).
- **줄을 바꾼 뒤:** strict lock을 갱신한다.
@@ -296,9 +296,9 @@ Kafka 없이 기동한다. 나머지 기능은 `app-bootstrap/build.gradle`에
### Compose와 런타임 스모크
- **Docker Compose 최소 버전은 `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의
- **Docker Compose 최소 버전은 `src/bootstrap/app/compose-lanes/compose-profile-contracts.json`의
`minimumComposeVersion`이다.** 정본 스크립트가 검증한다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만
필요한 overlay·smoke client·스키마 적용은 `src/app-bootstrap/compose-lanes/`에 있다.
필요한 overlay·smoke client·스키마 적용은 `src/bootstrap/app/compose-lanes/`에 있다.
- 진입점은 둘뿐이고, 그 둘만이 증거다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이
초록으로 보고된다.
@@ -308,7 +308,7 @@ Kafka 없이 기동한다. 나머지 기능은 `app-bootstrap/build.gradle`에
# 동적: 계약의 blocking 레인을 zero-skip으로. create → up --wait → 필수 one-shot →
# 컨테이너 재시작·OOM 0 확인 → sanitized evidence → 고유 project teardown
./scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
./scripts/run-compose-runtime-smoke.sh --matrix src/bootstrap/app/compose-lanes/compose-profile-contracts.json
```
`--lane <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아니다.
@@ -357,7 +357,7 @@ app:
- `ACTIVE`는 exact destination/provider/operation-catalog binding을 요구한다. 현재 유일한
buffered-classic readiness card가 `NOT_IMPLEMENTED`이므로 provider resource 생성 전에
fail-closed한다. 아직 운영 HTTP provider를 활성화할 수 있다는 뜻이 아니다.
- 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아니다. 루트 `src/.env`,
- 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아니다. 루트 `.env`,
`app-bootstrap`의 application YAML, env-key registry에서 제거됐으며 canonical composition에
입력하면 상태와 무관하게 기동을 거부한다.
- 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠다. 이제 저장소 어디에도 남아 있지 않다.
@@ -381,7 +381,7 @@ app:
**파일 출력 + rolling**
- **`APP_LOG_FILE_ENABLED`** — `true` 면 rolling JSON 파일 appender 를 붙인다.
- **`APP_LOG_FILE_PATH`** — `bootRun` working dir(`src/`) 기준 상대 경로 또는 절대 경로.
- **`APP_LOG_FILE_PATH`** — `bootRun` working dir(저장소 루트) 기준 상대 경로 또는 절대 경로. 기본값 `logs/…`는 git이 무시한다.
- **`APP_LOG_FILE_MAX_SIZE`** — 파일 1개 최대 크기(단위 `KB` | `MB` | `GB`).
- **`APP_LOG_FILE_MAX_HISTORY`** — 보관할 rolled archive 개수. 1 이상 정수.
- **`APP_LOG_FILE_TOTAL_SIZE_CAP`** — 전체 rolled 파일 용량 상한(단위 `KB` | `MB` | `GB`, `0` = 비활성).
@@ -511,7 +511,7 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 한다(
### 프로파일과 데이터베이스
프로파일마다 데이터스토어가 다르고, 그 차이는 `app-bootstrap/src/main/resources/application-*.yml`
프로파일마다 데이터스토어가 다르고, 그 차이는 `src/bootstrap/app/src/main/resources/application-*.yml`
가 소유한다.
| 프로파일 | 데이터스토어 | 스키마 소유자 | 외부 인프라 |
+3 -3
View File
@@ -8,8 +8,8 @@ real provider."
| Column | The question | Who decides it |
| --- | --- | --- |
| **IMPLEMENTED** | Does this repository contain the capability? | `src/config/architecture/modules.json` — the leaf is registered |
| **WIRED** | Present when selected: does the module assemble itself — own `AutoConfiguration.imports`, own settings, on when present, off with `enabled=false` — once a service adds its one `runtimeOnly` line to `app-bootstrap/build.gradle`? | the leaf's `META-INF/spring/...AutoConfiguration.imports`, the commented line in `app-bootstrap/build.gradle`, and an activation test in the leaf (present = on, `enabled=false` = off) |
| **IMPLEMENTED** | Does this repository contain the capability? | `gradle/modules.json` — the leaf is registered |
| **WIRED** | Present when selected: does the module assemble itself — own `AutoConfiguration.imports`, own settings, on when present, off with `enabled=false` — once a service adds its one `runtimeOnly` line to `src/bootstrap/app/build.gradle`? | the leaf's `META-INF/spring/...AutoConfiguration.imports`, the commented line in `src/bootstrap/app/build.gradle`, and an activation test in the leaf (present = on, `enabled=false` = off) |
| **QUALIFIED** | Has it been proven against a real provider, by something CI runs? | a strict test lane against a real provider **and** a workflow that executes it |
The third column is the one that rots quietly, because a lane can exist and be invoked by nothing.
@@ -20,7 +20,7 @@ Each row below names the lane *and* the workflow, so "qualified" can be checked
The default composition — what `bootJar` builds — is web, observability, `domain-core`,
`application-core`, `shared-contract`, `adapter:outbound:support` and `adapter:outbound:identifier`.
Every **yes** row in WIRED below is absent from it until a service uncomments that row's
`runtimeOnly` line in `app-bootstrap/build.gradle`. A module on the classpath is on; its enabled key
`runtimeOnly` line in `src/bootstrap/app/build.gradle`. A module on the classpath is on; its enabled key
defaults to `true`, and `false` turns a present module fully off. `./gradlew
:app-bootstrap:qualificationBootJar` packages the main runtime plus every capability, for compose
lanes and CI; it is not a deployment artifact.
+1 -1
View File
@@ -41,7 +41,7 @@
## 파생 프로젝트가 할 일
1. Template 전용 표의 항목을 삭제한다. 삭제는 대부분 파일 삭제 + `config/architecture/modules.json`
1. Template 전용 표의 항목을 삭제한다. 삭제는 대부분 파일 삭제 + `gradle/modules.json`
에서 leaf 항목 제거로 끝난다 — 레지스트리가 leaf 목록의 SSOT이고, 개수를 따로 적어 둔 곳은 없다.
2. `docs/ci-cd/boundary.md`의 경계를 그대로 유지한 채 자기 GitOps 저장소를 연결한다.
3. `.trivyignore.yaml`과 CODEOWNERS는 그대로 쓴다.
@@ -4,7 +4,7 @@
- 상태: 대체됨
- 작성일: 2026-07-20
- 요약: 중복된 하네스 규칙을 레지스트리 기반 정책 엔진으로 바꾸려던 설계다.
- 현재 정본: `src/config/architecture/modules.json`
- 현재 정본: `gradle/modules.json`
- 대체됨: `docs/design/2026-07-25-harness-free-mode-b-amendment.md`
<!-- 머리 블록 끝 -->
@@ -4,7 +4,7 @@
- 상태: 채택
- 작성일: 2026-07-25
- 요약: application-core에서 Spring·로깅 의존을 걷어내고 확정된 outbox 실패를 보고하는 방식을 정한 설계다.
- 현재 정본: `src/composition/outbox-relay/README.md`
- 현재 정본: `src/bootstrap/outbox-relay/README.md`
<!-- 머리 블록 끝 -->
# Application Outbox Failure Reporting Refactoring Design
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-07-25
- 요약: 하네스 없이 application-core를 프레임워크·로깅 없이 두면서 outbox 실패를 구조화된 ERROR 한 줄로 남기는 설계다.
- 현재 정본: `src/composition/outbox-relay/README.md`
- 현재 정본: `src/bootstrap/outbox-relay/README.md`
<!-- 머리 블록 끝 -->
# Application Outbox Failure Reporting — Harness-Free Design
@@ -4,7 +4,7 @@
- 상태: 채택
- 작성일: 2026-07-25
- 요약: 하네스를 되살리지 않고 Gradle 부트스트랩과 의존 방향 검사를 복구하며 registry JSON을 정본으로 정한 범위 수정이다.
- 현재 정본: `src/config/architecture/modules.json`
- 현재 정본: `gradle/modules.json`
<!-- 머리 블록 끝 -->
# Harness-Free Mode B Amendment
@@ -4,7 +4,7 @@
- 상태: 채택
- 작성일: 2026-07-25
- 요약: leaf Gradle 의존 그래프를 Clean Architecture를 지키는 최소 모양으로 줄이는 정리 설계다.
- 현재 정본: `src/config/architecture/modules.json`
- 현재 정본: `gradle/modules.json`
<!-- 머리 블록 끝 -->
# Module and Gradle Hygiene Refactoring Design
@@ -4,7 +4,7 @@
- 상태: 채택
- 작성일: 2026-07-25
- 요약: 같은 모듈·Gradle 정리를 하네스 없이 적용하는 설계다.
- 현재 정본: `src/config/architecture/modules.json`
- 현재 정본: `gradle/modules.json`
<!-- 머리 블록 끝 -->
# Harness-Free Module and Gradle Hygiene Design
@@ -4,7 +4,7 @@
- 상태: 채택
- 작성일: 2026-09-18
- 요약: 기존 outbox 저장소는 두고 발행 전송만 메시징 플랫폼으로 넘기는 설계다.
- 현재 정본: `src/composition/outbox-relay/README.md`
- 현재 정본: `src/bootstrap/outbox-relay/README.md`
<!-- 머리 블록 끝 -->
# Outbox Transport-Only Cutover Design
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-09-18
- 요약: PostgreSQL 멱등성 저장소 조립을 app-bootstrap에서 persistence-jpa로 옮기는 설계다.
- 현재 정본: `src/composition/idempotency/README.md`
- 현재 정본: `src/bootstrap/idempotency/README.md`
<!-- 머리 블록 끝 -->
# PostgreSQL Idempotency Composition Ownership
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-09-18
- 요약: tracing과 capability 검증이 런타임 profile 어휘 하나를 쓰게 하는 설계다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# Runtime Environment and Tracing SSOT
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-09-19
- 요약: 가짜 조정 bean 없이 다중 인스턴스 런타임 계약을 세우는 설계다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# Multi-instance Runtime Contract
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-09-19
- 요약: 운영 코드가 Spring active profile을 직접 읽지 않게 하는 경계 설계다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# Runtime Profile Access Boundary
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-09-19
- 요약: 기동 순서를 실행 가능한 계약 테스트로 고정하는 설계다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# Startup Order Contract
-1
View File
@@ -72,7 +72,6 @@ V1__create_fileserver_metadata.sql → capability_schema_registry: jpa-fileser
## 업그레이드 확인
```bash
cd src
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :application-fileserver:check :adapter:inbound:web-fileserver:check \
:adapter:outbound:fileserver:check :adapter:outbound:persistence-fileserver:check \
@@ -4,7 +4,7 @@
- 상태: 대체됨
- 작성일: 2026-07-20
- 요약: 하네스 규칙을 레지스트리 기반 정책 엔진으로 바꾸려던 실행 계획이다.
- 현재 정본: `src/config/architecture/modules.json`
- 현재 정본: `gradle/modules.json`
- 대체됨: `docs/history/plans/2026-07-25-harness-free-mode-b-amendment.md`
<!-- 머리 블록 끝 -->
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-07-25
- 요약: 하네스 없이 application-core의 outbox 실패 보고를 프레임워크 없이 만드는 실행 계획이다.
- 현재 정본: `src/composition/outbox-relay/README.md`
- 현재 정본: `src/bootstrap/outbox-relay/README.md`
<!-- 머리 블록 끝 -->
# Application Outbox Failure Reporting Implementation Plan
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-07-25
- 요약: application-core에서 Spring·로깅 결합을 걷어내고 outbox 실패를 보고하는 실행 계획이다.
- 현재 정본: `src/composition/outbox-relay/README.md`
- 현재 정본: `src/bootstrap/outbox-relay/README.md`
<!-- 머리 블록 끝 -->
# Application Outbox Failure Reporting Implementation Plan
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-07-25
- 요약: 하네스 없이 Gradle 부트스트랩과 의존 방향 검사를 되살리는 실행 계획이다.
- 현재 정본: `src/config/architecture/modules.json`
- 현재 정본: `gradle/modules.json`
<!-- 머리 블록 끝 -->
# Harness-Free Mode B Amendment Implementation Plan
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-07-25
- 요약: 하네스 없이 leaf 의존·경계 정리를 적용하는 실행 계획이다.
- 현재 정본: `src/config/architecture/modules.json`
- 현재 정본: `gradle/modules.json`
<!-- 머리 블록 끝 -->
# Harness-Free Module and Gradle Hygiene Implementation Plan
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-07-25
- 요약: leaf Gradle 그래프를 최소로 줄이는 리팩터링 실행 계획이다.
- 현재 정본: `src/config/architecture/modules.json`
- 현재 정본: `gradle/modules.json`
<!-- 머리 블록 끝 -->
# Module and Gradle Hygiene Refactoring Implementation Plan
@@ -4,7 +4,7 @@
- 상태: 끝남
- 작성일: 2026-09-18
- 요약: outbox 저장소는 두고 발행 전송만 메시징 플랫폼으로 넘기는 실행 계획이다.
- 현재 정본: `src/composition/outbox-relay/README.md`
- 현재 정본: `src/bootstrap/outbox-relay/README.md`
<!-- 머리 블록 끝 -->
# Outbox Transport-Only Cutover Implementation Plan
@@ -4,7 +4,7 @@
- 상태: 끝남
- 작성일: 2026-09-18
- 요약: PostgreSQL 멱등성 저장소 조립을 persistence-jpa로 옮기는 계획이다.
- 현재 정본: `src/composition/idempotency/README.md`
- 현재 정본: `src/bootstrap/idempotency/README.md`
<!-- 머리 블록 끝 -->
# PostgreSQL Idempotency Composition Ownership — Plan
@@ -4,7 +4,7 @@
- 상태: 끝남
- 작성일: 2026-09-18
- 요약: tracing과 capability 검증이 런타임 profile 어휘 하나를 쓰게 하는 계획이다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# Runtime Environment and Tracing SSOT — Plan
@@ -4,7 +4,7 @@
- 상태: 끝남
- 작성일: 2026-09-19
- 요약: 다중 인스턴스 런타임 계약을 세우는 계획이다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# Multi-instance Runtime Contract — Plan
@@ -4,7 +4,7 @@
- 상태: 끝남
- 작성일: 2026-09-19
- 요약: 운영 코드가 active profile을 직접 읽지 않게 하는 계획이다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# Runtime Profile Access Boundary — Plan
@@ -4,7 +4,7 @@
- 상태: 끝남
- 작성일: 2026-09-19
- 요약: 기동 순서를 계약 테스트로 고정하는 계획이다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# Startup Order Contract — Plan
@@ -4,7 +4,7 @@
- 상태: 확인 안 함
- 작성일: 2026-09-23
- 요약: app-bootstrap 빌드 조립을 정리하는 실행 계획이다.
- 현재 정본: `src/app-bootstrap/README.md`
- 현재 정본: `src/bootstrap/app/README.md`
<!-- 머리 블록 끝 -->
# App Bootstrap Build Composition — implementation plan
+2 -2
View File
@@ -13,7 +13,7 @@
|---|---|---|---|
| `app.httpclient.enabled` | boolean | `true` | `APP_HTTPCLIENT_ENABLED` |
모듈은 있으면 켜진다. 서비스가 `app-bootstrap/build.gradle`에 `runtimeOnly project(':adapter:outbound:httpclient')`를
모듈은 있으면 켜진다. 서비스가 `src/bootstrap/app/build.gradle`에 `runtimeOnly project(':adapter:outbound:httpclient')`를
더하면, 모듈 자신의 `config/module-defaults/httpclient.yml`(support leaf의 `ModuleDefaultsEnvironmentPostProcessor`가
가장 낮은 우선순위로 읽는다)이 `enabled: true`를 준다. 빌드에 없는 것이 보통의 꺼진 상태다. `false`는 명시적으로
끈 것이다. 그러면 `HttpClientPlatformAutoConfiguration`도, 그것이 import하는 것도 처리되지 않는다. 바인딩되는
@@ -49,7 +49,7 @@ APP_HTTPCLIENT_DYNAMIC_TARGETS_0_ALLOWED_SCHEMES_0=https
`APP_HTTPCLIENT_CLIENTS_0_TIMEUOT_TOTAL_CALL`은 client를 조용히 기본 예산으로 두지 않고 시작을 실패시킨다.
환경 변수가 아니라 설정 파일로 준 모르는 key도 같은 이유로 엄격한 바인딩이 거부한다.
`src/.env`와 `docs/registries/env-keys.yaml`에는 `APP_HTTPCLIENT_ENABLED`만 있다. 배포와 상관없는 값을 가진
`.env`와 `docs/registries/env-keys.yaml`에는 `APP_HTTPCLIENT_ENABLED`만 있다. 배포와 상관없는 값을 가진
유일한 key다. index를 단 client를 `application.yml`에 template로 두면 모든 배포에 이름 없는 client가 생기고,
그것은 묶음 검증이 거부한다.
+1 -1
View File
@@ -9,7 +9,7 @@
# 첫 client의 `app.httpclient.clients[N].base-url`은 APP_HTTPCLIENT_CLIENTS_0_BASE_URL로,
# `clients[N].allowed-hosts[M]`은 APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0으로 준다.
#
# docs/registries/env-keys.yaml에 등록하고 src/.env에 담는 것은 APP_HTTPCLIENT_ENABLED뿐이다. 배포와
# docs/registries/env-keys.yaml에 등록하고 .env에 담는 것은 APP_HTTPCLIENT_ENABLED뿐이다. 배포와
# 상관없는 값을 가진 유일한 key이고, 세 방향을 대조하는 :app-bootstrap:verifyEnvKeys 게이트가 표현할 수
# 있는 유일한 key다. 아래 나머지는 모두 배포마다 다르고 환경에 직접 준다. index를 단 client를
# application.yml에 template로 두면 모든 배포에 이름 없는 client가 생기고, settings의 묶음 검증이 그것을
-1
View File
@@ -5,7 +5,6 @@
## 게이트
```bash
cd src
./gradlew :adapter:outbound:httpclient:test --console=plain
./gradlew :adapter:outbound:httpclient:httpClientStableContractTest --console=plain
./gradlew :adapter:outbound:httpclient:httpClientSecurityTest --console=plain
+3 -3
View File
@@ -15,8 +15,8 @@
## 1. 모듈 배치가 다른 이유
설계는 `modules/httpclient/` 아래에 Gradle 프로젝트 19개를 둔 새 라이브러리를 가정한다. 이 저장소는 Clean
Architecture 템플릿이고, **닫힌 쪽으로 실패하는 registry**(`src/config/architecture/modules.json`)가 Gradle 프로젝트
목록을 정한다. `src/settings.gradle`이 registry에 있는 프로젝트만 포함하고, `verifyCleanArchitectureDependencies`가
Architecture 템플릿이고, **닫힌 쪽으로 실패하는 registry**(`gradle/modules.json`)가 Gradle 프로젝트
목록을 정한다. `settings.gradle`이 registry에 있는 프로젝트만 포함하고, `verifyCleanArchitectureDependencies`가
허용하지 않은 의존을 막는다. leaf 목록은 registry가 정본이다. 설계의 모듈마다 Gradle 프로젝트를 만들면
`AGENTS.md`의 HARD-STOP 5번(registry·Gradle 의존성 검증 위반)에 걸린다.
@@ -60,7 +60,7 @@ Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbo
| 설계 가정 | 저장소 현실 | 적응 |
|---|---|---|
| Gradle Kotlin DSL, `build-logic` convention plugin | Groovy DSL, root `build.gradle` convention, `LockMode.STRICT` 의존성 잠금 | 의존성은 `src/adapter/outbound/httpclient/build.gradle`에 선언하고 `gradle.lockfile`을 다시 만들었다. |
| Spring Framework 6.2 기준, 7.0 호환 | 저장소 기준은 Spring Boot 4.0 계열 / Spring Framework 7.0이다. 정확한 버전은 `src/gradle/libs.versions.toml`의 `springBoot`다 | 공통 코드는 Spring 6.2 **API 면**을 대상으로 한다(공통 package에 6.2 전용이나 7.0 전용 클래스가 없다). Spring 7 HTTP Service Group 통합과 `RestTemplate` 이전 package는 지웠다. |
| Spring Framework 6.2 기준, 7.0 호환 | 저장소 기준은 Spring Boot 4.0 계열 / Spring Framework 7.0이다. 정확한 버전은 `gradle/libs.versions.toml`의 `springBoot`다 | 공통 코드는 Spring 6.2 **API 면**을 대상으로 한다(공통 package에 6.2 전용이나 7.0 전용 클래스가 없다). Spring 7 HTTP Service Group 통합과 `RestTemplate` 이전 package는 지웠다. |
| `settings.gradle.kts` 모듈 등록 | 닫힌 쪽으로 실패하는 registry | registry는 바꾸지 않았다. leaf 식별자, gradle path, 허용 의존은 그대로다. |
| 설계 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다 | Spring의 blocking factory는 Apache의 **classic** client를 쓰고, 그것은 HTTP/1.1만 한다. HTTP/2는 Apache의 async client에 있다 | `ApacheBlockingTransportProvider`는 HTTP/1.1을 선언하고 HTTP/2 profile을 시작 때 거부한다. blocking HTTP/2는 JDK transport가 맡고, `NegotiatedProtocolContractTest`가 잰다. |
| 설계 §28.1은 상태 있는 fixture로 WireMock을 든다 | WireMock의 Jetty 모듈은 이 모듈이 HTTP/3 때문에 이미 쓰는 Boot 관리 Jetty 12와 ABI가 달라 서버 시작에서 실패한다 | `StatefulUpstream`이 기존 fixture 서버 위에서 경로별 상태 있는 응답을 준다. shaded jar로 돌아가지 않고 WireMock 의존성을 지웠다 |
+6 -6
View File
@@ -14,8 +14,8 @@
## 1. 모듈 배치가 다른 이유
계획은 `modules/jpa/` 아래 Stable Gradle 프로젝트 18개와 `modules/jpa-experimental/` 아래 Experimental 프로젝트 7개를 둔
새 라이브러리를 가정한다. 이 저장소는 **fail-closed registry**(`src/config/architecture/modules.json`)를 가진 Clean
Architecture 템플릿이다. `src/settings.gradle`은 registry를 읽고 검증한 뒤 등록된 프로젝트만 들이고,
새 라이브러리를 가정한다. 이 저장소는 **fail-closed registry**(`gradle/modules.json`)를 가진 Clean
Architecture 템플릿이다. `settings.gradle`은 registry를 읽고 검증한 뒤 등록된 프로젝트만 들이고,
`verifyCleanArchitectureDependencies`가 그 밖의 edge를 막는다. leaf 목록은 registry가 정한다. 계획의 Gradle 프로젝트를
새로 만들면 `AGENTS.md`의 HARD-STOP #5를 어긴다.
@@ -85,10 +85,10 @@ Docker가 필요한 lane은 건너뛰지 않고 닫힌 채 실패한다. 이 lea
| 계획의 가정 | 저장소의 실제 | 대응 |
|---|---|---|
| Gradle Kotlin DSL, `build-logic` convention plugin, `jpa-library-conventions.gradle.kts` | Groovy DSL, `src/build-logic`의 convention plugin(Java로 씀: spotless google-java-format, checkstyle, SpotBugs + FindSecBugs, ErrorProne, `-Werror`, 파일 하나에 타입 하나), `LockMode.STRICT` 의존성 잠금 | source set과 의존성은 `src/adapter/outbound/persistence-jpa/build.gradle`에 선언했다. `gradle.lockfile`은 `resolveAndLockAll --write-locks`로 다시 만들었다. |
| Spring Boot 4.1 의존성 관리, Spring Data JPA 4.1 | 저장소 기준선은 `src/gradle/libs.versions.toml`의 Spring Boot 버전이다 | 버전은 저장소 BOM에서 물려받고 모듈마다 고정하지 않는다. 계획이 요구하는 그대로다("do not override Hibernate/Flyway/Hikari versions outside the Boot BOM"). |
| Gradle Kotlin DSL, `build-logic` convention plugin, `jpa-library-conventions.gradle.kts` | Groovy DSL, `build-logic`의 convention plugin(Java로 씀: spotless google-java-format, checkstyle, SpotBugs + FindSecBugs, ErrorProne, `-Werror`, 파일 하나에 타입 하나), `LockMode.STRICT` 의존성 잠금 | source set과 의존성은 `src/adapter/outbound/persistence-jpa/build.gradle`에 선언했다. `gradle.lockfile`은 `resolveAndLockAll --write-locks`로 다시 만들었다. |
| Spring Boot 4.1 의존성 관리, Spring Data JPA 4.1 | 저장소 기준선은 `gradle/libs.versions.toml`의 Spring Boot 버전이다 | 버전은 저장소 BOM에서 물려받고 모듈마다 고정하지 않는다. 계획이 요구하는 그대로다("do not override Hibernate/Flyway/Hikari versions outside the Boot BOM"). |
| Hibernate ORM 7.4가 Stable provider | 저장소 BOM이 `org.hibernate.orm:hibernate-core:7.1.8.Final`을 푼다(release registry의 `stable-tested-baseline`) | 설계의 *선언* Stable provider 기준선은 `HibernateProviderPolicy`에서 7.4로 남는다. 런타임 provider 버전은 Hibernate 자신에게서 읽어 보고한다. collection-fetch-pagination gate는 BOM이 푸는 provider에서 돌고, `HibernateProviderPolicy.driftsFromDeclaredBaseline()`이 차이를 초록 검사 뒤에 숨기지 않고 드러낸다. |
| PostgreSQL 16·17·18 Stable matrix | 컨테이너 이미지는 `src/config/testing/container-images.properties`에 digest로 고정한다 | `PostgreSqlVersion`이 PG 16, 17, 18을 정확히 선언한다. 기본 lane은 16이고, 다른 major는 `-Pjpa.matrix.versions=<major>`로 고른다. 계약 suite(`JpaPlatformContractSupport.start()`)는 JVM 하나에 major 하나만 받는다. 여러 major를 한 번에 받는 것은 `StablePostgreSqlMatrixContractTest`뿐이다. 모르는 값이나 빈 선택은 건너뛰지 않고 오류다. |
| PostgreSQL 16·17·18 Stable matrix | 컨테이너 이미지는 `gradle/container-images.properties`에 digest로 고정한다 | `PostgreSqlVersion`이 PG 16, 17, 18을 정확히 선언한다. 기본 lane은 16이고, 다른 major는 `-Pjpa.matrix.versions=<major>`로 고른다. 계약 suite(`JpaPlatformContractSupport.start()`)는 JVM 하나에 major 하나만 받는다. 여러 major를 한 번에 받는 것은 `StablePostgreSqlMatrixContractTest`뿐이다. 모르는 값이나 빈 선택은 건너뛰지 않고 오류다. |
| `settings.gradle.kts` 모듈 등록 | fail-closed registry | registry는 바꾸지 않았다. leaf 신원, Gradle path, 허용 의존은 그대로다. |
| `infra/jpa/{postgres,roles,toxiproxy}` | 이 repo는 운영 인프라 파일을 두지 않는다(2026-11-07 소유자 결정) | 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 `docs/jpa/security.md`로 옮겼다. |
| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, JPA workflow | 저장소가 이미 `docs/`와 workflow 폴더를 가진다 | 같은 저장소 상대 경로에 만들었다. JPA 전용 workflow 파일은 2026-11-08 단계 파일 셋(`.gitea/workflows`)의 job으로 접었다. |
@@ -96,7 +96,7 @@ Docker가 필요한 lane은 건너뛰지 않고 닫힌 채 실패한다. 이 lea
| task마다 `git add` + `git commit` | `AGENTS.md`: 커밋 정책은 `human-only`다. 에이전트는 stage, commit, amend, push를 하지 않는다 | 구현은 stage하지 않은 채로 넘겼다. 일부러 하지 않은 계획 단계는 이것 하나이고, 여기에 기록한다. |
| Querydsl을 선택 모듈 의존성으로 | Querydsl은 이 저장소의 의존성 묶음에 없다 | `querydsl`은 계획의 계약대로 구현하되 Querydsl 타입을 `compileOnly` 뒤에 둔다. 그래서 Stable 런타임 classpath에는 Querydsl이 없고, 쓰기로 한 배포가 artifact를 직접 더한다. |
| Hibernate Envers를 모듈 의존성으로 | Envers는 이 저장소의 의존성 묶음에 없다 | Querydsl과 같다. `compileOnly` + 명시적 opt-in. 계획의 "Envers is opt-in and never enabled by a global base class"와 맞는다. |
| `build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt` | `src/build-logic`은 있지만 Kotlin source set은 없다 | 패키지 경계는 이 leaf의 `JpaModuleBoundaryTest`(§1)가, leaf 경계는 `verifyCleanArchitectureDependencies`와 `:app-bootstrap:architectureTest`가 `src/config/architecture/modules.json`을 정본으로 강제한다. |
| 계획의 build-logic/src/test/kotlin/JpaModuleBoundaryTest.kt | `build-logic`은 있지만 Kotlin source set은 없다 | 패키지 경계는 이 leaf의 `JpaModuleBoundaryTest`(§1)가, leaf 경계는 `verifyCleanArchitectureDependencies`와 `:app-bootstrap:architectureTest`가 `gradle/modules.json`을 정본으로 강제한다. |
| `PostgreSqlRuntimeRoleVerifierIntegrationTest` (Task 45) | 보안 lane은 모듈마다의 `integrationTest`가 아니라 이 leaf의 suite 하나다 | `PostgreSqlSecurityContractTest`(tag `jpa-security`)가 실제 서버의 실제 제한 역할에 대고 `PostgreSqlRuntimeRoleVerifier.verify`와 `.requireSafe`를 돌린다. |
| `JpaSafetyProperties`, `JpaDataSourceProperties` | `NamingConventionTest`는 모든 `@ConfigurationProperties` 타입 이름이 `Settings`나 `Policy`로 끝나기를 요구한다 | `JpaSafetySettings`로 이름을 바꿨다. 묶는 속성 prefix와 모든 칸은 그대로이고 클래스 이름만 이 저장소 관례로 옮겼다. `JpaDataSourceProperties`에 해당하는 설정 클래스는 지금 없다. datasource 검사는 `JpaDataSourceProfileValidator`가 한다. |
+6 -7
View File
@@ -30,14 +30,13 @@ scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에
| 입력 | 규칙 | 어디서 막나 |
| --- | --- | --- |
| 이름 | PascalCase, 영숫자 | 스크립트 |
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/AGENTS.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` |
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
생성 뒤 확인:
```bash
cd src
./gradlew :domain-core:check :application-core:check :adapter:outbound:identifier:check \
:adapter:inbound:web:check :app-bootstrap:check architectureCheck --console=plain
```
@@ -69,7 +68,7 @@ verify-feature-scaffold.sh
-> 임시 디렉터리 삭제
```
- 루트 태스크 `verifyFeatureScaffold`(`src/build.gradle`)가 이 스크립트를 부르고 `mainCheck`에 들어
- 루트 태스크 `verifyFeatureScaffold`(`build.gradle`)가 이 스크립트를 부르고 `mainCheck`에 들어
있다. 중첩 Gradle 빌드라 PR 단계가 아니라 main 단계다.
- 템플릿이나 템플릿이 기대는 규칙(ArchUnit, Error Prone, 포맷)이 바뀌어 생성물이 깨지면 여기서 빨강이 된다.
- 생성된 테스트가 실행되지 않고 지나가는 일(빈 녹색)을 막으려고 결과 XML을 확인한다.
@@ -78,8 +77,8 @@ verify-feature-scaffold.sh
| 형태 | 결정 | 이유 |
| --- | --- | --- |
| `scripts/`의 bash + 텍스트 템플릿(`scripts/feature-scaffold/templates/**/*.tmpl`) | **채택** | 개발자 도구는 `scripts/`에 둔다는 repo 관례(`ca.developer-bootstrap` 플러그인을 지우고 `scripts/bootstrap-local.sh`로 옮긴 것, `src/build-logic/README.md`). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다 |
| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`src/build-logic/AGENTS.md`). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
| `scripts/`의 bash + 텍스트 템플릿(`scripts/feature-scaffold/templates/**/*.tmpl`) | **채택** | 개발자 도구는 `scripts/`에 둔다는 repo 관례(`ca.developer-bootstrap` 플러그인을 지우고 `scripts/bootstrap-local.sh`로 옮긴 것, `build-logic/README.md`). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다 |
| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`build-logic/AGENTS.md`). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
| 생성 대신 예시 기능을 커밋해 두고 복사 | 버림 | 복사본이 하나 더 생겨 규칙과 갈라진다. 이름 바꾸기를 사람이 손으로 한다 |
| 왕복 검사를 JUnit 안에서 javac로 컴파일 | 버림 | Spotless·Error Prone·ArchUnit 전체를 다시 구현해야 하고, 실제 게이트와 다른 것을 검사하게 된다. 실제 Gradle 게이트를 그대로 돌리는 쪽을 골랐다 |
| 생성 뒤 자동 `spotlessApply` | 채택(끄려면 `--no-format`) | google-java-format이 Javadoc을 이름 길이에 따라 다시 접는다. 템플릿만으로는 모든 이름에서 포맷 검사를 통과시킬 수 없다 |
@@ -90,7 +89,7 @@ verify-feature-scaffold.sh
| 파일 | 설정 | 왜 |
| --- | --- | --- |
| `src/domain-core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(`.claude/rules/java-tests.md` 규칙 6) |
| `src/application-core/build.gradle`, `src/adapter/inbound/web/build.gradle`, `src/app-bootstrap/build.gradle` | `testImplementation testFixtures(project(':domain-core'))` | 유스케이스·HTTP·조립 테스트가 그 fake를 쓴다 |
| `src/domain/core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(`.claude/rules/java-tests.md` 규칙 6) |
| `src/application/core/build.gradle`, `src/adapter/inbound/web/build.gradle`, `src/bootstrap/app/build.gradle` | `testImplementation testFixtures(project(':domain-core'))` | 유스케이스·HTTP·조립 테스트가 그 fake를 쓴다 |
| `src/adapter/inbound/web/build.gradle` | `implementation project(':domain-core')` | 컨트롤러가 경로 문자열을 도메인 id로 바꾼다 |
| `src/adapter/outbound/identifier/build.gradle` | `implementation project(':domain-core')` | id adapter가 도메인 `IdFactory` 포트를 구현한다 |
+6 -6
View File
@@ -24,7 +24,7 @@
만드는 것: aggregate(`@AggregateRoot`), id(`@ValueObject` record, `ResourceId`), id 생성 포트
(`IdFactory` 상속), 저장 포트(`*Repository`), 불변식 예외(`Reason` enum).
예: 생성 결과 `src/domain-core/src/main/java/dev/caskeleton/domain/<f>/`.
예: 생성 결과 `src/domain/core/src/main/java/dev/caskeleton/domain/<f>/`.
검사: `DomainPurityArchitectureTest`(Spring·JPA·전송 타입 금지, setter 비공개, 감사 필드 금지),
`ForbiddenApiArchitectureTest.NO_LONG_ID_PK`.
@@ -50,12 +50,12 @@
- **기본값**: aggregate를 통째로 저장·로드하면 domain 소유 `XRepository`.
- **예외**: 읽기 모양이 aggregate와 다르면 application 소유 `XQueryPort` + projection(record).
`QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 반환 타입을 검사한다. lease·claim 같은 기술
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/AGENTS.md`.
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application/core/AGENTS.md`.
## 2단계 — application-core: 유스케이스와 포트
만드는 것: command/query record, 유스케이스(쓰기 `CommandUseCase`, 읽기 `QueryUseCase`), 반환용 view
record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/main/java/dev/caskeleton/application/<f>/`.
record, 오류 코드 enum과 carrier 예외. 예: `src/application/core/src/main/java/dev/caskeleton/application/<f>/`.
필수 선언(ArchUnit이 강제, `ApplicationBoundaryArchitectureTest`):
@@ -63,14 +63,14 @@ record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/mai
실제 `TransactionPort` 호출이 맞아야 한다(`USE_CASE_CAPABILITY_MATCHES_TRANSACTION_PORT_BOUNDARY`).
- 쓰기 유스케이스에 `@RequiresPermission("<resource>:<action>")`(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`).
- 유스케이스 클래스는 `final`이 아니다. 권한 프록시가 하위 클래스를 만든다
(`src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java`).
(`src/bootstrap/app/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java`).
### 판단: 트랜잭션 모양
- **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
- **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`.
- **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/AGENTS.md`
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application/core/AGENTS.md`
「Allowed transactional shapes」.
### 판단: 무엇을 반환하나
@@ -114,7 +114,7 @@ record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/mai
## 5단계 — app-bootstrap 조립
만드는 것: `@AutoConfiguration` 클래스 하나 + `AutoConfiguration.imports` 한 줄.
예: `src/composition/durable-operation/src/main/java/dev/caskeleton/composition/operation/DurableOperationAutoConfiguration.java`.
예: `src/bootstrap/durable-operation/src/main/java/dev/caskeleton/composition/operation/DurableOperationAutoConfiguration.java`.
- `@ConditionalOnBean(필요한 포트들)`: 포트 구현이 없으면 기능 전체가 없다.
- 유스케이스는 `@Bean`으로 만든다. 직접 `new` 하면 권한 프록시가 없어 `@RequiresPermission`이 조용히
+5 -5
View File
@@ -8,11 +8,11 @@
```text
① 계층 leaf 안 패키지 (기본)
domain-core/.../domain/<f> -> application-core/.../application/<f> -> adapter:*/.../<f> -> app-bootstrap/.../autoconfigure/<f>
src/domain/core/.../domain/<f> -> src/application/core/.../application/<f> -> adapter:*/.../<f> -> src/bootstrap/app/.../autoconfigure/<f>
② 기능 전용 leaf (capability)
application-<f> -> persistence-<f>, adapter:outbound:<f>, adapter:inbound:web-<f> -> composition:<f>-platform
app-bootstrap/build.gradle 에 runtimeOnly 한 줄
src/bootstrap/app/build.gradle 에 runtimeOnly 한 줄
```
## 기준표
@@ -23,8 +23,8 @@
| 다른 서비스가 같은 기능을 라이브러리로 받나 | 아니오 | **예** |
| 한 줄 지워 기능을 통째로 빼야 하나 | 아니오(패키지 삭제) | **예**(`runtimeOnly` 한 줄) |
| leaf 단위 의존 방향 검사가 기능 안에도 걸리나 | 예(계층이 leaf) | 예 |
| 고칠 공용 파일 | 없음(+ imports 한 줄) | `modules.json`, `settings.gradle` 매핑, `app-bootstrap/build.gradle`, lockfile |
| 예시 | 생성 명령 출력, `application-core/.../operation` | `application-notification`, `application-fileserver`, `application-objectstorage` |
| 고칠 공용 파일 | 없음(+ imports 한 줄) | `modules.json`, `settings.gradle` 매핑, `src/bootstrap/app/build.gradle`, lockfile |
| 예시 | 생성 명령 출력, `src/application/core/.../operation` | `application-notification`, `application-fileserver`, `application-objectstorage` |
### 판단: ①과 ② 중 무엇인가
@@ -55,7 +55,7 @@
- `<f>`는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과
겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를
이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다.
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/README.md`
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application/core/README.md`
「패키지 소유 (Package ownership)」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성
뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다.
- 이름 규칙은 같은 파일 「Naming convention」이 정본이다.
+1 -1
View File
@@ -44,7 +44,7 @@ use case ── tx.inWrite ──▶ XRepository (domain 포트)
("모듈을 아는 곳은 모듈 자신뿐")을 어기고, ② 그 leaf의 공개 API 기준선
(`docs/architecture/jpa-api-surface.txt`)과 엔티티 scan 목록(`PersistenceJpaConfig`,
`PersistenceEntityScanCoverageTest`)을 고쳐야 하며, ③ upstream 병합 충돌 면이 넓어진다.
- 새 leaf는 `modules.json` 등록, lockfile 생성, `app-bootstrap/build.gradle` 한 줄이 필요하다(10장).
- 새 leaf는 `modules.json` 등록, lockfile 생성, `src/bootstrap/app/build.gradle` 한 줄이 필요하다(10장).
## 엔티티 매핑
+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/README.md` 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」
정본: `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로 만드나
+1 -1
View File
@@ -57,7 +57,7 @@ gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로
`ErrorCodeRegistryMappingTest`(app-bootstrap)가 status 일치를 검사한다.
- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 "Product/fork ApiErrorCode enums own local
registries"). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위
`ErrorCodeRegistryMappingTest`(`src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ErrorCodeRegistryMappingTest.java`)다.
`ErrorCodeRegistryMappingTest`(`src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ErrorCodeRegistryMappingTest.java`)다.
## 지금 이해하면 되는 것
+9 -9
View File
@@ -18,11 +18,11 @@
| 무엇 | 어디 |
| --- | --- |
| 선언 | `src/application-core/src/main/java/dev/caskeleton/application/security/RequiresPermission.java` — 쓰기 유스케이스에 필수(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`) |
| 선언 | `src/application/core/src/main/java/dev/caskeleton/application/security/RequiresPermission.java` — 쓰기 유스케이스에 필수(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`) |
| 검사 장치 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/authz/MethodSecurityConfig.java`의 advisor |
| 켜는 곳 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java` |
| 역할 → 권한 | `app.authz.role-permissions` (`src/app-bootstrap/src/main/resources/config/security.yml`), 바인딩 `RolePermissionPolicy` |
| 프록시 가능 | `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java` |
| 역할 → 권한 | `app.authz.role-permissions` (`src/bootstrap/app/src/main/resources/config/security.yml`), 바인딩 `RolePermissionPolicy` |
| 프록시 가능 | `src/bootstrap/app/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java` |
검사 자동 설정은 인증 체인(`WebSecurityAutoConfiguration`)과 **분리**되어 있다. 서비스가 자기 인증
방식으로 인증 체인을 바꿔도 권한 검사는 꺼지지 않는다(2026-11-01부터. 전에는 인증 체인 자동 설정을 빼면
@@ -57,16 +57,16 @@ client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지
- **고르는 기준**: 같은 권한을 가진 두 사람이 같은 객체에 대해 다른 답을 받아야 하는가(소유자, tenant).
- **기본값**: 유스케이스가 객체를 읽은 뒤 판정하고, 남의 것이면 **없는 것과 같은 404**로 답한다.
존재 여부도 정보다. 예: `GetDurableOperationUseCase`와 `DurableOperationAccessPolicy`
(`src/application-core/src/main/java/dev/caskeleton/application/operation/`).
(`src/application/core/src/main/java/dev/caskeleton/application/operation/`).
- **예외**: 여러 전송이 같은 판정을 써야 하거나 목록에서 한 번에 판정해야 하면
`ObjectAccessPolicy`(`src/application-core/src/main/java/dev/caskeleton/application/security/ObjectAccessPolicy.java`,
`ObjectAccessPolicy`(`src/application/core/src/main/java/dev/caskeleton/application/security/ObjectAccessPolicy.java`,
batch 메서드로 N+1 회피)를 구현한다. 존재를 숨길 필요가 없는 관리 화면은 403도 된다.
- tenant: 인증 정보에서만 만든 `TenantId`를 command에 싣는다. 요청 본문의 tenant 값을 믿지 않는다.
## 시스템이 부르는 쓰기: `@SystemInvoked`
스케줄러·relay·메시지 소비자처럼 사람이 아니라 시스템이 부르는 쓰기 유스케이스는 `@RequiresPermission` 대신
`@SystemInvoked(reason = "...")`를 단다(`src/application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java`).
`@SystemInvoked(reason = "...")`를 단다(`src/application/core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java`).
스케줄러·소비 스레드에는 인증(`Authentication`)이 없어서 권한 선언은 매번 거부되거나 아예 검사되지 않는
장식이 되기 때문이다. 이 표시가 붙은 유스케이스는 **권한 검사가 없는 쓰기**다. 그래서 사용자 요청이
닿으면 안 된다.
@@ -90,7 +90,7 @@ client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지
| 경로 | 어디에 두나 | 유스케이스는 누가 만드나 |
| --- | --- | --- |
| 조립 모듈의 스케줄러 | `composition:*` leaf. 예: outbox relay(`src/composition/outbox-relay`) | 조립 모듈의 `@Bean` 메서드가 `new`로 만들어 스케줄러에 넘긴다 |
| 조립 모듈의 스케줄러 | `composition:*` leaf. 예: outbox relay(`src/bootstrap/outbox-relay`) | 조립 모듈의 `@Bean` 메서드가 `new`로 만들어 스케줄러에 넘긴다 |
| 메시지 handler | `adapter:inbound:messaging` leaf, 또는 서비스 leaf의 `..adapter.inbound.messaging..` 패키지 | handler 생성자가 port를 받아 `new`로 만든다. handler에 `@SystemCaller`. 작업 순서는 09장 「소비」 4단계 |
| 예약 작업 | 서비스 자기 leaf의 `..adapter.inbound.scheduler..` 패키지. 등록된 scheduler leaf는 없다 | 작업 클래스 생성자가 port를 받아 `new`로 만든다. 작업 클래스에 `@SystemCaller`. 모양은 메시지 handler와 같고, 깨우는 것이 `@Scheduled` 메서드다. `Runnable`·`ApplicationRunner` 같은 프로젝트 밖 타입을 구현하지 않는다. task scheduler에 직접 등록하면 그 자리에서 `job::run`을 넘긴다 |
@@ -101,7 +101,7 @@ client가 같은 이름의 역할을 정의해도 이 서비스 권한이 되지
| 규칙 | 무엇을 막나 | 어디 |
| --- | --- | --- |
| bean 금지 | `@SystemInvoked` 유스케이스가 bean이면 기동 실패. 호출자가 `new`로 만들어 혼자 들고 있는 것만 허용한다 | `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` |
| bean 금지 | `@SystemInvoked` 유스케이스가 bean이면 기동 실패. 호출자가 `new`로 만들어 혼자 들고 있는 것만 허용한다 | `src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` |
| 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
| 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping과 channel interceptor·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) |
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등)에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 넷이다. ① 사용자 전송 패키지에 있는 클래스. ② 설정(`@Configuration`·`@AutoConfiguration`) 클래스 자신이 요청 처리기 타입(함수형 `RouterFunction`·`HandlerFunction`, `@RestController`·`@RequestMapping`, servlet·`Filter`·`HandlerInterceptor`, `WebSocketHandler`, GraphQL `DataFetcher`·`RuntimeWiringConfigurer`, gRPC `BindableService`·`ServerInterceptor`, STOMP `ChannelInterceptor`·`ExecutorChannelInterceptor` 등)에 의존하는 것. 요청 처리 코드를 설정에 직접 쓴 경우와 등록만 한 경우가 모두 든다. channel interceptor를 구현한 설정은 프레임마다 자기 메서드가 돈다. interceptor를 `@Bean`으로 내놓는 설정은 route를 등록하는 설정과 같다. 함수형 route나 data fetcher를 람다로 쓰면 그 코드가 설정 클래스의 메서드로 컴파일되어 설정이 곧 endpoint다. 처리 코드를 다른 클래스에 두고 메서드 참조로 등록만 해도(`route().GET("/orders", orders::list)`) 설정은 route builder에 의존한다. 클래스 의존으로는 등록과 처리 코드를 가를 수 없어서 둘 다 사용자 전송으로 센다. ③ 설정 안에 중첩된 클래스 가운데 사용자 전송 타입에 의존하는 것. 중첩된 JAX-RS 자원·`@ServerEndpoint`, `configureClientInboundChannel`에서 등록하는 STOMP channel interceptor(익명 클래스여도, STOMP 헤더를 읽지 않아도)도 여기서 잡힌다. 설정용 타입(`WebMvcConfigurer`·`WebSocketConfigurer`·STOMP broker 설정과 그 registry, CORS 설정, `RequestMethod`)에만 의존하는 중첩 클래스는 설정의 일부로 본다. inbound channel의 thread 수만 정하는 설정도 설정용이다. ④ 그 밖의 클래스 가운데 사용자 전송 타입에 의존하는 것. 사용자 전송 패키지 밖에 둔 channel interceptor가 여기에 든다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`(설정 필드를 읽는 익명 클래스여도)·CORS 설정·controller bean을 함께 만들어도 걸리지 않는다. 같은 클래스에 "지금 실행" route·data fetcher·interceptor를 쓰거나, route를 등록하거나, 안에 중첩한 endpoint가 작업을 부르면(설정의 메서드를 거쳐 불러도) 걸린다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
@@ -144,7 +144,7 @@ broker listener용 `@Payload`·`@Header`는 시스템 쪽이라 넣지 않는다
- `@SystemInvoked` 유스케이스는 bean이 아니고(`PermissionEnforcementGuard`), 시스템 호출자가 `new`로 만들어
혼자 든다. 그래서 사용자 전송은 시스템 호출자 객체를 거치지 않고는 그 유스케이스를 부를 수 없다.
- 의존 방향 게이트(`src/config/architecture/modules.json`): 등록된 leaf 가운데 `adapter:inbound:messaging`에
- 의존 방향 게이트(`gradle/modules.json`): 등록된 leaf 가운데 `adapter:inbound:messaging`에
의존할 수 있는 것은 조립 루트(`app-bootstrap`)뿐이다. 다른 leaf의 사용자 전송은 handler 타입을 컴파일조차
못 한다. 예약 작업은 서비스 자기 leaf에 있어서 같은 leaf의 controller와 사이에는 이 게이트가 없다. 그래서
위 길들은 사실상 controller와 작업이 같은 leaf에 있을 때, 또는 둘을 모두 보는 설정에서 생긴다.
+3 -3
View File
@@ -52,7 +52,7 @@ fake와 실제 adapter가 **같은 계약**을 통과해야 fake 위의 유스
## lane과 단계
`ci`(PR)의 leaf `test`는 Docker 없이 빠르게 끝나야 한다. 실 DB·실 서버가 필요한 테스트는 strict
lane으로 선언하고 단계를 지정한다. 선언은 `ca.strict-test-lane`(`src/build-logic/README.md`).
lane으로 선언하고 단계를 지정한다. 선언은 `ca.strict-test-lane`(`build-logic/README.md`).
| lane 종류 | 선언 | 도는 단계 |
| --- | --- | --- |
@@ -62,8 +62,8 @@ lane으로 선언하고 단계를 지정한다. 선언은 `ca.strict-test-lane`(
| 성능·부하 | performance 범주 | `performanceCheck` |
| 외부 입력 필요(자격증명 등) | `explicitOnly(reason)` | 어떤 집계에도 안 들어가고 이유가 출력된다 |
예: `src/app-bootstrap/build.gradle`의 `strictTestLanes { lane('integrationTest') { integration() … } }`,
`src/app-bootstrap/build.gradle`의 `publicPathSnapshotTest`(`mainStage()`).
예: `src/bootstrap/app/build.gradle`의 `strictTestLanes { lane('integrationTest') { integration() … } }`,
`src/bootstrap/app/build.gradle`의 `publicPathSnapshotTest`(`mainStage()`).
### 판단: 새 테스트를 어느 lane에
+5 -5
View File
@@ -17,15 +17,15 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐
DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을
없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다.
정본: `src/application-core/README.md` 「계약 타입」(이벤트 타입 표). 메시징 라이브러리 쪽 정본은 그 repo의
정본: `src/application/core/README.md` 「계약 타입」(이벤트 타입 표). 메시징 라이브러리 쪽 정본은 그 repo의
[outbox-inbox.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/outbox-inbox.md)와
[delivery-guarantees.md](https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library/src/branch/main/docs/messaging/delivery-guarantees.md)다.
## 순서
1. 계약을 정한다: 계약 id(`<service>.<aggregate>.<event>`), 버전, payload record, JSON schema 파일과 해시.
예: `src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationSubmittedContract.java`,
`src/application-core/src/main/resources/contracts/messaging/durable-operation.submitted/v1.schema.json`(해시는 계약 클래스 안).
예: `src/application/core/src/main/java/dev/caskeleton/application/operation/DurableOperationSubmittedContract.java`,
`src/application/core/src/main/resources/contracts/messaging/durable-operation.submitted/v1.schema.json`(해시는 계약 클래스 안).
2. payload record(`IntegrationPayload`)를 만든다.
3. 유스케이스의 `tx.inWrite` 안에서 저장 뒤 draft → encode → append. 예:
`SubmitDurableOperationUseCase`(application-core `operation`).
@@ -35,7 +35,7 @@ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공
소비자가 있으면 같은 event id를 두 번 받아도 효과가 한 번인지 보는 중복 제거 계약.
6. schema를 출시한다: `src/test/resources/contracts/released-payload-schemas.sha256`에 새 version 파일의
해시를 한 줄 더한다. 출시한 version 파일은 고치지 않는다 — 바뀌면 `ReleasedPayloadSchemaContract`
테스트가 실패한다. 필드를 바꾸는 변경은 새 version으로 낸다. 절차: `src/application-core/README.md`
테스트가 실패한다. 필드를 바꾸는 변경은 새 version으로 낸다. 절차: `src/application/core/README.md`
"payload version 올리기".
## 판단 지점
@@ -55,7 +55,7 @@ DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공
### event id·correlation·순서
draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occurredAt, requestCorrelationId, payload)`로
만든다(`src/application-core/src/main/java/dev/caskeleton/application/messaging/event/IntegrationEventDrafts.java`).
만든다(`src/application/core/src/main/java/dev/caskeleton/application/messaging/event/IntegrationEventDrafts.java`).
계약 id·payload 버전·목적지는 계약에서 오고, 기능이 정하는 것은 aggregate·순서·payload뿐이다.
`new IntegrationEventDraft<>(…)`를 직접 쓰면 빌드가 막는다(`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`).
예: `SubmitDurableOperationUseCase`.
+4 -4
View File
@@ -3,11 +3,11 @@
## 핵심
JPA·Redis·Kafka·알림·파일 서버 같은 부가 기능은 **의존성 한 줄로 켜지고, 그 줄을 지우면 사라지는
모듈**이다. 서비스는 `src/app-bootstrap/build.gradle`에서 필요한 모듈만 `runtimeOnly`로 고른다.
모듈**이다. 서비스는 `src/bootstrap/app/build.gradle`에서 필요한 모듈만 `runtimeOnly`로 고른다.
기본 조립은 web, 운영 관측, cores, support/identifier뿐이다. JPA도 한 줄로 켠다.
```text
app-bootstrap/build.gradle
src/bootstrap/app/build.gradle
runtimeOnly project(':adapter:outbound:persistence-jpa') ← 이 한 줄
│
▼
@@ -22,7 +22,7 @@ app-bootstrap/build.gradle
## 켜기
1. `src/app-bootstrap/build.gradle`의 해당 `runtimeOnly` 줄 주석을 푼다.
1. `src/bootstrap/app/build.gradle`의 해당 `runtimeOnly` 줄 주석을 푼다.
2. lockfile 갱신: `./gradlew :app-bootstrap:resolveAndLockAll --write-locks`, 확인
`./gradlew verifyDependencyLocks`.
3. 모듈 README의 env 키를 채운다. 키 목록 정본은 `docs/registries/env-keys.yaml`.
@@ -66,7 +66,7 @@ app-bootstrap/build.gradle
모듈 설정 기본값은 그 모듈의 `src/main/resources/config/module-defaults/<모듈>.yml`에 두고 `adapter:outbound:support`의 `ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. 의존성 closure에 support가 없는 leaf(persistence-mongo, graphql)만 자기 EPP가 `config/<이름>.yml`을 읽는다.
등록할 공용 파일: `src/config/architecture/modules.json`(leaf와 허용 edge), `src/settings.gradle`이 읽는
등록할 공용 파일: `gradle/modules.json`(leaf와 허용 edge), `settings.gradle`이 읽는
디렉터리 매핑, app-bootstrap의 허용 edge, 새 leaf lockfile. registry가 허용하지 않은 edge는
`architectureCheck`(의존 방향)가 막는다.
+3 -3
View File
@@ -1,12 +1,12 @@
# 11. 체크리스트 — PR 올리기 전
빠진 것이 있으면 해당 장으로 돌아간다. 검사 명령은 `src/`에서 실행한다.
빠진 것이 있으면 해당 장으로 돌아간다. 검사 명령은 저장소 루트에서 실행한다.
## 배치·이름
- [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `<feature>` 패키지).
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
- [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다.
- [ ] 패키지 이름이 템플릿 패키지(`src/application/core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
- [ ] 이름이 `src/application/core/AGENTS.md` 「Naming convention」을 따른다.
## domain
+6 -6
View File
@@ -42,9 +42,9 @@
| --- | --- |
| 계층 경계·금지 규칙 | `AGENTS.md`와 가장 가까운 `src/**/AGENTS.md` |
| 테스트 작성 규칙 | `.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/README.md` 「정해진 유스케이스 모양 (Canonical use case shape)」, `src/application-core/AGENTS.md` 「허용하는 트랜잭션 모양 (Allowed transactional shapes)」 |
| leaf 목록·허용 의존 | `gradle/modules.json` |
| 이름 규칙(유스케이스·포트·command·query) | `src/application/core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/bootstrap/app/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
| 유스케이스 모양·트랜잭션 모양 | `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` |
@@ -63,8 +63,8 @@
| 코드 | 역할 | 따라 하나 |
| --- | --- | --- |
| `scripts/new-feature.sh` 출력 | 계층 leaf에 나눈 업무 기능 | **이것을 따른다** |
| `src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/**` | ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 |
| `application-core/.../operation` + `DurableOperationAutoConfiguration`(composition:durable-operation) | 템플릿 플랫폼 기능 | 조립 모양(`@ConditionalOnBean` + 유스케이스 `@Bean`)만 본다 |
| `src/bootstrap/app/src/test/java/dev/caskeleton/onboarding/**` | ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 |
| `src/application/core/.../operation` + `DurableOperationAutoConfiguration`(composition:durable-operation) | 템플릿 플랫폼 기능 | 조립 모양(`@ConditionalOnBean` + 유스케이스 `@Bean`)만 본다 |
## 리뷰 뒤 첫 수정으로 생긴 패턴
@@ -81,6 +81,6 @@
| store는 호출자 트랜잭션을 요구한다 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java` | 04 |
| `@RequiresPermission` 검사는 인증 체인과 분리된 자동 설정 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java` | 07 |
| JWT audience 필수, 자기 client role만 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/JwtDecoderConfig.java`, `docs/runbooks/auth-audience-mismatch.md` | 07 |
| strict lane은 반드시 어떤 단계에 속한다 | `verifyStrictLaneStages`(`src/build.gradle` `strictLaneStages`) | 08 |
| strict lane은 반드시 어떤 단계에 속한다 | `verifyStrictLaneStages`(`build.gradle` `strictLaneStages`) | 08 |
| 서비스 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 | `NotificationSchemaStream`(persistence-notification) | 04 |
| 재시도 가능한 broker 거부는 DEAD가 아니라 재시도 | `docs/runbooks/outbox-dead-letter.md` | 09 |
+2 -2
View File
@@ -43,7 +43,7 @@ testFixtures가 아니라 테스트 소스에 둔 이유: testFixtures는 소비
## 2. 레지스트리와 Gradle에 leaf 등록
leaf 목록과 허용 의존 방향의 원본은 `src/config/architecture/modules.json`이다. 레지스트리에 없는 edge는
leaf 목록과 허용 의존 방향의 원본은 `gradle/modules.json`이다. 레지스트리에 없는 edge는
`verifyCleanArchitectureDependencies`가 거부한다.
1. `modules.json`의 `modules`에 서비스 leaf를 추가한다. 플랫폼 leaf로 가는 edge를 여기서 연다.
@@ -77,7 +77,7 @@ leaf 목록과 허용 의존 방향의 원본은 `src/config/architecture/module
}
```
4. `app-bootstrap/build.gradle`에서 두 leaf를 켠다. 플랫폼 leaf 줄은 주석으로 이미 있다.
4. `src/bootstrap/app/build.gradle`에서 두 leaf를 켠다. 플랫폼 leaf 줄은 주석으로 이미 있다.
```groovy
runtimeOnly project(':adapter:outbound:persistence-mongo')
+3 -3
View File
@@ -13,7 +13,7 @@
설계는 `modules/mongodb/` 아래에 Stable Gradle 프로젝트 19개, `modules/mongodb-advanced/` 아래에 Advanced
프로젝트 12개를 가정한다. 이 저장소는 Clean Architecture 템플릿이고, **닫힌 쪽으로 실패하는 registry**
(`src/config/architecture/modules.json`)가 Gradle 프로젝트 목록을 정한다. `src/settings.gradle`이
(`gradle/modules.json`)가 Gradle 프로젝트 목록을 정한다. `settings.gradle`이
registry에 있는 프로젝트만 포함하고, `verifyCleanArchitectureDependencies`가 허용하지 않은 의존을 막는다.
설계의 모듈마다 Gradle 프로젝트를 만들면 `AGENTS.md`의 HARD-STOP 5번(registry·Gradle 의존성 검증 위반)에
걸린다.
@@ -91,7 +91,7 @@ Root package: `io.backend.skeleton.mongodb` → `dev.caskeleton.adapter.outbound
|---|---|---|
| `modules/mongodb*` 아래 Gradle Kotlin DSL | Groovy DSL, root `build.gradle` convention, `LockMode.STRICT` 잠금 | 의존성은 `src/adapter/outbound/persistence-mongo/build.gradle`에 선언하고 `gradle.lockfile`을 다시 만들었다. |
| `mongodb-spring-boot-starter`는 앱이 의존하는 별도 모듈 | `modules.json`이 `adapter-outbound-persistence-mongo`에 명시적 프로젝트 경계를 준다. 런타임 편입은 leaf별 registry 필드가 아니라 해석한 런타임 classpath에서 정해진다 | `autoconfigure` package는 leaf 안에 두고 leaf 자신의 `META-INF/spring/…AutoConfiguration.imports`로 등록한다. httpclient 선례와 다르다. leaf를 실제로 조립하는지는 의존성 게이트와 런타임 편입 게이트가 정한다. |
| Spring Boot 4.1 / Spring Data MongoDB 5.1 기준 | 저장소 기준은 Spring Boot 4.0 계열 / Spring Data MongoDB 5.0 계열이다. 정확한 버전은 `src/gradle/libs.versions.toml`의 `springBoot`와 leaf의 `gradle.lockfile`이다 | 플랫폼은 둘에 공통인 Spring Data MongoDB **API 면**만 쓴다. 5.1에만 있는 타입은 참조하지 않는다. 실제 고정 버전은 support matrix가 가리킨다. |
| Spring Boot 4.1 / Spring Data MongoDB 5.1 기준 | 저장소 기준은 Spring Boot 4.0 계열 / Spring Data MongoDB 5.0 계열이다. 정확한 버전은 `gradle/libs.versions.toml`의 `springBoot`와 leaf의 `gradle.lockfile`이다 | 플랫폼은 둘에 공통인 Spring Data MongoDB **API 면**만 쓴다. 5.1에만 있는 타입은 참조하지 않는다. 실제 고정 버전은 support matrix가 가리킨다. |
| `MongoRetryScope`는 `mongodb-transaction`에 있다 | `mongodb-spring-data`의 실패 변환기가 재시도 범위를 분류해야 하는데 `mongodb-transaction`에 의존할 수 없다 | `MongoRetryScope`는 두 package가 이미 의존하는 `…api.error`(core-api)에 둔다. 값도 뜻도 같고, DAG에서 놓일 수 있는 자리는 하나다. |
| `mongodb-migration-flamingock`은 Flamingock에 의존한다 | 검증하지 않은 외부 의존성을 더하는 것은 이 작업 범위 밖이었다. 설계도 공개 계약이 Flamingock 타입에 의존하지 않기를 요구한다 | 어댑터는 provider 중립이다. 플랫폼이 소유한 `FlamingockChangeUnitView`를 받는다. 실제 Flamingock 배포판을 잇는 일은 그 view 뒤의 파일 하나만 바꾸면 된다. |
| Testkit은 따로 된 Gradle 모듈 | 설계는 production 모듈이 testkit에 의존하는 것을 금한다 | testkit은 `testFixtures` source set(ADR-BUILD-001)에 둔다. 컨테이너가 필요한 provider fixture는 별도 `mongoProviderTestkit` source set에 두어 보통 단위 테스트가 Testcontainers를 얻지 않게 한다. 방향은 `MongoModuleBoundaryTest`의 `noProductionPackageDependsOnTheTestkit`이 강제한다. |
@@ -124,7 +124,7 @@ Root package: `io.backend.skeleton.mongodb` → `dev.caskeleton.adapter.outbound
이름을 지정한 Gradle lane을 돌리고, 건너뛴 lane을 통과로 세지 않으며, 승격 정보를 보고한다. 릴리스·승격
증거를 만들 때 쓴다. 아래 명령은 로컬 진단에 계속 쓸모가 있다.
`src/`에서:
저장소 루트에서:
```bash
./gradlew :adapter:outbound:persistence-mongo:check --console=plain
-1
View File
@@ -67,7 +67,6 @@ DB 소유자에게 올린다. 애플리케이션은 큐에 쌓지 않고 닫힌
failover lane이 이 상황을 일부러 재현한다.
```bash
cd src
./gradlew :adapter:outbound:persistence-mongo:mongoFailoverTest --console=plain
```
-1
View File
@@ -72,7 +72,6 @@ status: 운영
## 확인
```bash
cd src
./gradlew :adapter:outbound:persistence-mongo:mongoFailoverTest --console=plain
```
-1
View File
@@ -128,7 +128,6 @@ pool과 SDAM 이벤트가 없으면 모든 failover가 「DB가 느려졌다」
## 9. 보안 lane이 이것을 어떻게 증명하나
```bash
cd src
./gradlew :adapter:outbound:persistence-mongo:mongoSecurityIntegrationTest --console=plain
```
+2 -2
View File
@@ -8,7 +8,7 @@
| 구성 요소 | 버전 | 정책 |
|---|---|---|
| Java | 21 | 저장소 런타임 기준. |
| Spring Boot | `src/gradle/libs.versions.toml`의 `springBoot` | BOM이 관리한다. driver를 따로 덮어쓰는 것은 금지한다. |
| Spring Boot | `gradle/libs.versions.toml`의 `springBoot` | BOM이 관리한다. driver를 따로 덮어쓰는 것은 금지한다. |
| Spring Data MongoDB | Boot BOM이 정한다 | repository와 `MongoTemplate` 통합. |
| MongoDB Java Driver | Boot BOM이 정한다 | 모듈에서 직접 고정하지 않는다. |
| Micrometer | Boot BOM이 정한다 | driver 자체 관측. |
@@ -30,7 +30,7 @@ Spring Data MongoDB 5.0 계열이므로, 플랫폼은 둘에 공통인 API 면
| 네트워크 장애 주입 | — | `toxiproxy` | `mongoFailoverTest` |
이미지는 고정하고 `latest`를 쓰지 않는다. 바뀌는 tag를 쓰면 인증 결과는 행에 적은 버전이 아니라 그날 아침
받은 무언가를 설명한다. 이미지의 정본은 `src/config/testing/container-images.properties`다. 표의 key마다
받은 무언가를 설명한다. 이미지의 정본은 `gradle/container-images.properties`다. 표의 key마다
digest와 그 digest의 tag(주석)가 거기 있다. patch 버전은 이 표에 옮겨 적지 않는다. 새 patch 버전을 시험할 때는
`-PmongoPrimaryImage=…` / `-PmongoCompatibilityImage=…`로 덮어쓰고, 게이트가 통과하면 그 파일을 고친다.
+2 -2
View File
@@ -1,10 +1,10 @@
# 설정 참조
알림 전달 플랫폼은 `app.notification.platform` 아래에 묶인다. 설정 트리는
`src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`에 있고,
`src/bootstrap/notification-platform/src/main/resources/config/module-defaults/notification.yml`에 있고,
support leaf의 `ModuleDefaultsEnvironmentPostProcessor`가 가장 낮은 우선순위로 읽는다. 그래서 이 모듈이 없는
애플리케이션에는 이 설정이 하나도 없다. 이 모듈은 어느 기본 조립에도 없다. 서비스가
`app-bootstrap/build.gradle`에 `runtimeOnly project(':composition:notification-platform')`(와 persistence-jpa 줄)를
`src/bootstrap/app/build.gradle`에 `runtimeOnly project(':composition:notification-platform')`(와 persistence-jpa 줄)를
더해 고르고, 모듈이 있으면 켜진다. 값마다 기본값이 붙어 있으므로 플랫폼을 끄는 배포는 아무것도 주지 않아도 된다.
> 이력: 2026-08-15까지 이 문서는 바인딩에 없는 속성(`max-retry-concurrency`, `scheduler-poll-interval`,
+1 -1
View File
@@ -45,7 +45,7 @@
],
"evidence": [
"adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/notification/PostgreSqlProviderEventLedgerContractTest.java",
"application-notification/src/test/java/dev/caskeleton/application/notification/platform/callback/CallbackIngestionAtomicityTest.java",
"application/notification/src/test/java/dev/caskeleton/application/notification/platform/callback/CallbackIngestionAtomicityTest.java",
"adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesCallbackContractTest.java"
]
},
+2 -2
View File
@@ -7,8 +7,8 @@
## 대응표가 있는 이유
계획은 가상의 저장소(`modules/notification/**`, root 패키지 `io.backend.skeleton.notification`, Gradle 프로젝트 31개)를
두고 쓰였다. 이 저장소는 fail-closed Clean Architecture 템플릿이다. `src/settings.gradle`은 registry
(`src/config/architecture/modules.json`)를 읽고 검증한 뒤 등록된 프로젝트만 들이고, `verifyCleanArchitectureDependencies`는
두고 쓰였다. 이 저장소는 fail-closed Clean Architecture 템플릿이다. `settings.gradle`은 registry
(`gradle/modules.json`)를 읽고 검증한 뒤 등록된 프로젝트만 들이고, `verifyCleanArchitectureDependencies`는
`allowed_dependencies` 밖의 프로젝트 edge를 거부한다.
Gradle 프로젝트 31개를 새로 만들면 `AGENTS.md`의 HARD-STOP #5를 어긴다. 패키지 README도 이것을 내다보고, 공개 계약과
+1 -1
View File
@@ -1870,7 +1870,7 @@ env_keys:
# --- Redis 런타임 설정 (app.redis.*) ----------------------------------
# APP_REDIS_ENABLED가 true일 때만 adapter-outbound-redis-runtime의 RedisRuntimeAutoConfiguration이
# 바인딩한다. application.yml은 Redis 없는 배포에 이 값을 넣지 않는다. src/.env.example은 운영자가
# 바인딩한다. application.yml은 Redis 없는 배포에 이 값을 넣지 않는다. .env.example은 운영자가
# 명시적으로 넣을 값을 적어 둘 뿐이다. verifyEnvKeys가 이 레지스트리를 런타임 모듈의 설정 메타데이터와
# 대조한다.
@@ -26,7 +26,7 @@ status: 초안
## 조치
- 잘못된 공개 경로 변경을 되돌린다.
- `src/`에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
- 저장소 루트에서 `./gradlew verifyPublicPathSnapshot`을 돌려 스냅숏과 비교한다.
## 에스컬레이션

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