문제: 앞 커밋이 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
11 KiB
MongoDB 문서 영속성 플랫폼 — 저장소 적응 계약
설계서: docs/design/2026-08-11-mongodb-document-persistence-platform-design.md
Stable 계획서: docs/history/plans/2026-08-11-mongodb-document-persistence-platform-implementation-plan.md
Advanced 계획서: docs/history/plans/2026-08-11-mongodb-advanced-capabilities-expansion-plan.md
설계 패키지는 자기 모듈 root(modules/mongodb)와 root package(io.backend.skeleton.mongodb)를 계약이
아니라 구현 가정으로 적었다. 이 파일은 그 가정한 배치를 이 저장소에 어떻게 옮겼는지 적은 유일한
기록이다. 바뀐 것은 경로, 빌드 DSL, 조립 루트의 소유뿐이다. 공개 계약, 정책 순서, 오류 의미는 명세대로
구현했다.
1. 모듈 배치가 다른 이유
설계는 modules/mongodb/ 아래에 Stable Gradle 프로젝트 19개, modules/mongodb-advanced/ 아래에 Advanced
프로젝트 12개를 가정한다. 이 저장소는 Clean Architecture 템플릿이고, 닫힌 쪽으로 실패하는 registry
(gradle/modules.json)가 Gradle 프로젝트 목록을 정한다. settings.gradle이
registry에 있는 프로젝트만 포함하고, verifyCleanArchitectureDependencies가 허용하지 않은 의존을 막는다.
설계의 모듈마다 Gradle 프로젝트를 만들면 AGENTS.md의 HARD-STOP 5번(registry·Gradle 의존성 검증 위반)에
걸린다.
그래서 설계의 모듈 31개는 등록된 leaf :adapter:outbound:persistence-mongo 안의 package 경계가
된다. docs/httpclient/repository-adaptation.md가 먼저 세운
방식을 따른다. 설계의 모듈 의존 표(§6.3)는 MongoModuleBoundaryTest가 닫힌 edge 행렬로 강제한다.
- 최상위 package마다 import해도 되는 package를 선언한다.
- 행렬과 실제 트리가 정확히 같은지 비교한다.
- 관측한 edge는 모두 행렬에 있어야 한다.
금지된 edge는 Gradle 의존이 빠졌을 때와 똑같이 빌드를 실패시킨다. 아무도 등록하지 않은 새 package도 그렇다.
예전에는 이 문서의 주장이 테스트보다 강했다. 규칙은 역방향 의존 몇 개만 막고 나머지는 말하지 않았다.
그래서 설계의 DAG 밖의 edge가 있었고 통과했다. geo → imperative가 그중 하나다. 지금은 그런 edge를
지우지 않고 행렬에 선언했다. 하나하나가 코드가 실제로 기대는 결합이다. 적어 두는 이유는 다음 edge가
사고가 아니라 결정이 되게 하려는 것이다.
2. Package 대응
Root package: io.backend.skeleton.mongodb → dev.caskeleton.adapter.outbound.mongo.
2.1 Stable 모듈
| 설계 모듈 | 저장소 package |
|---|---|
mongodb-core-api |
…outbound.mongo.api (+ .capability, .consistency, .error, .mapping, .observation, .profile, .schema) |
mongodb-spring-data |
…outbound.mongo.mapping (+ .type), …outbound.mongo.failure |
mongodb-imperative |
…outbound.mongo.imperative (+ .atomic, .bulk, .revision) |
mongodb-query |
…outbound.mongo.query (+ .budget, .pagination) |
mongodb-aggregation |
…outbound.mongo.aggregation |
mongodb-transaction |
…outbound.mongo.transaction (+ .retry, .session) |
mongodb-index-schema |
…outbound.mongo.schema (+ .index, .manifest, .model, .ttl, .validation) |
mongodb-geospatial |
…outbound.mongo.geo |
mongodb-migration-core |
…outbound.mongo.migration |
mongodb-migration-flamingock |
…outbound.mongo.migration.flamingock |
mongodb-observability |
…outbound.mongo.observation |
mongodb-security |
…outbound.mongo.security (+ .admin), …outbound.mongo.nativecap |
mongodb-spring-boot-starter |
…outbound.mongo.autoconfigure |
mongodb-testkit-core |
…outbound.mongo.testkit.mapping, .compat, .performance (testFixtures source set) |
mongodb-testkit-replicaset |
…outbound.mongo.testkit.rs (testFixtures, 컨테이너 fixture는 mongoProviderTestkit source set) |
mongodb-testkit-failover |
…outbound.mongo.testkit.failover (testFixtures, 컨테이너 fixture는 mongoProviderTestkit source set) |
mongodb-testkit-migration |
…outbound.mongo.testkit.migration (testFixtures source set) |
…outbound.mongo.architecture는 설계에 짝이 없다. testFixtures source set에 있고, @MongoOperation
표시 annotation과, 파생 서비스가 자기 document·repository 코드에 적용하는 재사용 ArchUnit 규칙 묶음
(MongoRepositoryArchitectureRules)을 가진다.
2.2 Advanced 모듈
| 설계 모듈 | 저장소 package |
|---|---|
mongodb-sharding |
…outbound.mongo.advanced.sharding (+ D4 shard plane용 .admin) |
mongodb-csfle |
…outbound.mongo.advanced.encryption.csfle |
mongodb-queryable-encryption |
…outbound.mongo.advanced.encryption.qe |
mongodb-tenancy-shared |
…outbound.mongo.advanced.tenancy.shared |
mongodb-tenancy-database |
…outbound.mongo.advanced.tenancy.database |
mongodb-testkit-sharded |
…outbound.mongo.testkit.sharded (testFixtures source set) |
mongodb-timeseries, mongodb-search, mongodb-vector-search, mongodb-gridfs-compat,
mongodb-testkit-atlas는 이제 package가 없다. 각각 구현 없는 operations interface와 그것을 매개변수로
채우던 descriptor뿐이었고, 2026-09-25에 지웠다(docs/capability-status.md).
설계의 「Stable 모듈은 Advanced 모듈에 의존하지 않는다」 규칙은 ArchUnit 테스트로 남았다
(MongoModuleBoundaryTest의 noStablePackageDependsOnAnAdvancedCapability). 모든 Advanced 진입점은
MongoAdvancedCapabilityGuard를 받고, 그 MongoAdvancedCapabilityFlags가 해당 capability를 켜지 않았으면
생성을 거부한다. flag 뒤에 설정 속성은 없다. Advanced 타입은 라이브러리 API이고, 그것을 만드는 도입 측
어댑터가 guard를 만든다.
3. 그 밖에 일부러 바꾼 것
| 설계 가정 | 저장소 현실 | 적응 |
|---|---|---|
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 계열이다. 정확한 버전은 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이 강제한다. |
작업마다 git commit |
AGENTS.md: 커밋 정책은 human-only |
구현은 stage하지 않은 채 넘겼고, 커밋은 사람이 했다. 계획 중 일부러 실행하지 않은 단계는 이것 하나이고, 여기 적어 둔다. |
docs/mongodb/**, scripts/verify-mongodb-*.sh |
저장소가 이미 docs/와 scripts/를 가진다 |
같은 저장소 상대 경로에 만들었다. 게이트 스크립트 둘은 지금도 있다(5절). |
4. 설계에서 바뀌지 않은 것
- D1 / D2 / D3 / D4 노출 plane과 순서가 정해진 D3 허가 절차(§5).
- D1/D2 client 세대에는
apiStrict=true인 Stable API V1. D3/D4는 별도 세대. - 결과를 모르는 두 경우(
WRITE_RESULT_UNKNOWN,TRANSACTION_COMMIT_UNKNOWN)를 포함한MongoExecutionOutcome, 그리고MongoFailureContext가 허락하는 필드 목록. - 안정된 예외 계층 전체와, 코드보다 label을 먼저 보는 분류 순서.
- BSON 표현 manifest(UUID
STANDARD,Decimal128, UTC 순간, 별칭 타입 metadata)와 문서 크기 예산. - update operator를 먼저 쓰는 쓰기, 그리고 문서 전체 교체의 선행 조건인 낙관적 revision.
- 별개 loop인 transaction 본문 재시도와 commit 재시도: 본문 시도마다 새 session, commit 결과를 모르면 commit만 재시도. commit 결과를 모르면 본문을 다시 돌리지 않는다.
- query, aggregation, index의 등록된 연산 이름과 manifest. 자유 형식 JSON query와 상한 없는 pipeline은 없다.
- 인증한 cursor와 유일한 동률 처리 기준을 요구하는 keyset 페이지 나누기.
- TTL은 물리적 정리일 뿐이다. 접근 거부나 업무 일정의 유일한 근거가 아니다.
- manifest가 소유한 index/validator 상태와, 소유하지 않은 것은 절대 지우지 않는 적용 정책.
- 가짓수가 적은 관측 tag, 명령 가리기, credential 참조 간접화.
- Stable 릴리스 게이트의 증거 분류. Advanced 승격 요건(실제 토폴로지 증거)은 ADR-MONGO-ADV-001의 검토
의무다. 그것을 검사하는 클래스는 없다.
scripts/verify-mongodb-advanced.sh는 빠진 증거를 보고할 뿐이다.
5. 검증
릴리스 게이트 스크립트 scripts/verify-mongodb-platform.sh와 scripts/verify-mongodb-advanced.sh가 있다.
이름을 지정한 Gradle lane을 돌리고, 건너뛴 lane을 통과로 세지 않으며, 승격 정보를 보고한다. 릴리스·승격
증거를 만들 때 쓴다. 아래 명령은 로컬 진단에 계속 쓸모가 있다.
저장소 루트에서:
./gradlew :adapter:outbound:persistence-mongo:check --console=plain
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain
컨테이너가 필요한 lane(mongoCompatibilityTest, mongoMigrationTest, mongoSecurityIntegrationTest,
mongoReplicaSetTest, mongoFailoverTest, mongoPerformanceTest)은 check에 들어 있지 않다.
MONGODB_DOCKER=1 bash scripts/verify-mongodb-platform.sh로 돌리거나, 이름으로 하나씩 돌린다.