문제: 앞 커밋이 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
138 lines
11 KiB
Markdown
138 lines
11 KiB
Markdown
# 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`로 돌리거나, 이름으로 하나씩 돌린다.
|