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

6.7 KiB

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 §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의 증거가 더 필요하다.

검색, vector 검색, time series, GridFS 호환은 구현 없는 interface였고 2026-09-25에 지웠다 (docs/capability-status.md).