Files
clean-architecture-backend-…/docs/mongodb/support-matrix.md
T
DongHyeonka 6a792b8144 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
2026-11-11 22:15:42 +09:00

92 lines
6.7 KiB
Markdown

# MongoDB 플랫폼 — 지원 매트릭스
설계서 §4. 이 파일은 플랫폼이 우연히 돌아가는 환경이 아니라 *인증한* 환경을 적는다. 이 표에 없는 구성은
누군가 그 구성으로 게이트를 돌리고 행을 더하기 전까지 지원하지 않는다.
## 1. 런타임 기준
| 구성 요소 | 버전 | 정책 |
|---|---|---|
| Java | 21 | 저장소 런타임 기준. |
| 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 자체 관측. |
| Testcontainers | Boot BOM이 정한다 | replica set, failover, migration, compatibility lane. |
BOM이 정한 실제 버전은 leaf의 잠금 파일 `src/adapter/outbound/persistence-mongo/gradle.lockfile`에 있다.
버전을 이 표에 옮겨 적지 않는다. 옮겨 적은 숫자는 다음 업그레이드에서 틀린 글이 된다.
설계의 기준은 Spring Boot 4.1 계열 / Spring Data MongoDB 5.1 계열이다. 이 저장소는 Spring Boot 4.0 계열 /
Spring Data MongoDB 5.0 계열이므로, 플랫폼은 둘에 공통인 API 면만 쓴다.
[repository-adaptation.md](repository-adaptation.md) §3을 본다.
## 2. 서버 버전
| Lane | 버전 | 고정한 이미지(key) | Gradle task |
|---|---|---|---|
| 주 인증 | MongoDB 8.0 | `mongo-8` | `mongoReplicaSetTest`, `mongoFailoverTest` |
| 호환성 | MongoDB 7.0 | `mongo-7` | `mongoCompatibilityTest` |
| 네트워크 장애 주입 | — | `toxiproxy` | `mongoFailoverTest` |
이미지는 고정하고 `latest`를 쓰지 않는다. 바뀌는 tag를 쓰면 인증 결과는 행에 적은 버전이 아니라 그날 아침
받은 무언가를 설명한다. 이미지의 정본은 `gradle/container-images.properties`다. 표의 key마다
digest와 그 digest의 tag(주석)가 거기 있다. patch 버전은 이 표에 옮겨 적지 않는다. 새 patch 버전을 시험할 때는
`-PmongoPrimaryImage=…` / `-PmongoCompatibilityImage=…`로 덮어쓰고, 게이트가 통과하면 그 파일을 고친다.
`MongoVersionMatrix.standard()`가 이 표의 기계용 형태다. 그 밖의 버전은 `certifies()`에서 실패한다.
## 3. 토폴로지
| 토폴로지 | 상태 | 인증하는 것 | 인증하지 않는 것 |
|---|---|---|---|
| Standalone | **smoke만** | 기본 CRUD와 매핑. | 운영 profile이 아니고 Stable 릴리스 증거로 세지 않는다(D-03). Standalone 서버 위의 운영 profile이나 `platform.transactions=true`는 `MongoStartupValidator`가 시작할 때 거부한다. |
| 노드 하나짜리 replica set | **로컬 기본값**(D-02) | transaction, retryable write, change stream — 운영과 같은 의미. | 선출. 노드 하나짜리 set은 선출을 하지 않으므로 여기서는 failover 동작을 시험하지 않는다. |
| 노드 세 개짜리 replica set | **Stable 운영 게이트** | 위의 모든 것과 primary failover, commit 결과를 모를 때의 처리. | shard 라우팅. |
| Sharded cluster | **Advanced 게이트** | shard key 라우팅 분류, scatter-gather 거부, `admin` plane 작업. | Stable 게이트에 들지 않는다. |
| Atlas / provider 관리형 | **인증 안 함** | 실제 대상 배포에서의 암호화는 도입하는 쪽이 만들 증거다. | 검색과 vector 검색은 이 leaf에 구현이 없다. native `$search` 명령은 등록한 D3 연산으로 `PolicyAwareMongoNativeGateway`를 거쳐야만 갈 수 있다. |
## 4. Stable API와 client 세대
| Plane | Stable API | 용도 |
|---|---|---|
| D1 표준 문서 영속성 | V1, `apiStrict=true` | repository, 타입 있는 query, atomic update, 낙관적 revision. |
| D2 고급 문서 연산 | V1, `apiStrict=true` | `MongoTemplate`, transaction, bulk, aggregation, keyset cursor. |
| D3 명시적 Mongo capability | strict 아님 | native BSON, CSFLE/QE, shard를 아는 연산 — 각각 등록한 capability 뒤에 있다. |
| D4 Admin plane | strict 아님 | collection, validator, index, migration, shard, repair 명령. credential도 client도 따로다. |
D3는 날것의 client로 빠지는 출구가 아니다. 모든 호출은 이 순서대로 지나간다: capability 등록 → database
profile → collection 허용 목록 → 연산 이름 → timeout → 일관성 profile → 결과 상한 → trace → 가리기 → 명령
분류 → D4 거부.
## 5. Validation action
Stable validation action은 `error`와 `warn`이다. `errorAndLog`는 7.0이나 8.0에서 Stable 계약에 들지
**않고**, `MongoValidatorDescriptor`가 거부한다.
## 6. 명시적으로 지원하지 않는 것
설계 §3.4에 따라 아래는 하나도 제공하지 않는다. 하나라도 더하는 것은 기능 요청이 아니라 설계 변경이다.
- 범용 `CommonMongoRepository<T, ID>`.
- 실행 중 임의의 `runCommand`.
- 운영에서 index 자동 생성.
- Standalone 운영 계약.
- 정확한 업무 일정 도구나 유일한 접근 제어로서의 TTL.
- 날것의 change event를 외부 업무 통합 이벤트로 내보내기.
- 새 파일의 정본으로서의 GridFS.
- 오래 사는 BSON schema로서의 Java FQCN.
- 상한 없는 skip 페이지 나누기, 상한 없는 aggregation pipeline, 상한 없는 regex, 상한 없는 결과.
## 7. Capability 등급
| 등급 | Capability | 켜는 법 |
|---|---|---|
| Stable, 자동 구성 | 매핑과 BSON converter, 명령형 실행, atomic update, bulk 부분 결과, 일관성 profile, 재시도/변환, 연산 예산, 관측, 타입 있는 client profile, 시작 검증, health | `app.persistence-mongo.enabled=true`일 때 bean을 등록한다. |
| Stable, 라이브러리 API | transaction, causal session, 낙관적 revision, query builder와 keyset 페이지 나누기, aggregation executor, schema/index/validator manifest와 diff, TTL 계약, GeoJSON, migration runner, admin plane, native capability gateway | 도입하는 쪽의 어댑터 leaf가 이 leaf를 `implementation`으로 받고 타입을 만든다. |
| Advanced, 라이브러리 API | shard를 아는 query와 shard admin, CSFLE, Queryable Encryption(equality/range), shared collection tenancy 정책 | 위와 같고, 그 capability를 켠 flag의 `MongoAdvancedCapabilityGuard`가 더 필요하다. 설정 속성은 없다. |
| Experimental, 라이브러리 API | tenant마다 database client registry와 migration coordinator, reshard 승인 | Advanced와 같다. 승격에는 [ADR-MONGO-ADV-001](../adr/ADR-MONGO-ADV-001-capability-promotion.md)의 증거가 더 필요하다. |
검색, vector 검색, time series, GridFS 호환은 구현 없는 interface였고 2026-09-25에 지웠다
(`docs/capability-status.md`).