# 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](../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을 통과로 세지 않으며, 승격 정보를 보고한다. 릴리스·승격 증거를 만들 때 쓴다. 아래 명령은 로컬 진단에 계속 쓸모가 있다. 저장소 루트에서: ```bash ./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`로 돌리거나, 이름으로 하나씩 돌린다.