Files
clean-architecture-backend-…/docs/adr/ADR-MONGO-004-index-schema-admin-plane.md
T
DongHyeonka 59dff0041c ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.

- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
  입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
  따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
  울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
  않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
  docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
  링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
  docs-system.md 6.2절 다섯 칸)을 더했다.

버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).

위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).

검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
2026-11-07 22:20:18 +09:00

4.5 KiB

결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-08-13
  • 요약: 인덱스와 스키마 변경은 관리 평면이 맡는다는 결정이다.
  • 현재 정본: docs/mongodb/schema-index-migration-guide.md

ADR-MONGO-004 — index와 schema 변경은 admin plane의 것이다

  • 상태: 채택
  • 날짜: 2026-08-13
  • 설계 출처: 설계 §21–§25, 결정 D-11, D-13

배경

Spring Data는 애너테이션에서 index를 자동으로 만들 수 있다. 노트북에서는 편하다. 문서 1억 개가 든 collection에서 index 만들기는 용량 사건이다: primary의 CPU, IO, 메모리를 몇 분에서 몇 시간 동안 쓰고, pod 하나가 재시작했다는 이유로 시작된다.

더 나쁘게, pod N개가 재시작하면 N번 시작하고, 승인 단계도, 그 index가 필요한 코드와의 순서도, 나중에 무엇을 만들었는지의 기록도 없다.

schema validator도 같은 모양인데 날이 더 서 있다: 데이터가 있는 collection에서 validator를 조이면, 쓸 때는 적법했던 문서에 대한 쓰기를 거절한다.

TTL은 세 번째 모양이다. scheduler처럼 보이지만 아니다: TTL monitor는 대략 1분에 한 번 돌고 batch로 지우므로, 만료된 문서가 몇 분에서 몇 시간 동안 읽히는 것이 예사다.

결정

index와 validator는 manifest에 선언하고 admin plane(D4)이 적용한다. 운영에서 자동 index 만들기는 끈다.

  1. MongoManifestRegistry가 collection마다 선언한 index(MongoIndexManifest)와 validator(MongoSchemaManifest)를 가진다. manifest가 정본이고 pull request에서 리뷰한다.
  2. MongoIndexDiffEngine이 manifest를 관찰한 상태와 비교해 빠진 index, 남는 index, 바뀐 index를 알린다. 바뀐 것은 다시 내지 않고 알린다: MongoDB는 정의가 움직인 index를 소리 없이 다시 만들지 않는다.
  3. MongoIndexApplyPolicy가 환경이 할 수 있는 것을 정한다 — APPLY(로컬), APPLY_WITH_DIFF(staging), DIFF_WITH_APPROVED_APPLY(운영), REPORT_ONLY(감사).
  4. 모든 drop은 소유권이 막는다. MongoMetadataOwnership이 APPLICATION_MANAGED를 SEARCH_MANAGED, ENCRYPTION_MANAGED, EXTERNAL과 구별한다. 어긋났을 때 지울 수 있는 것은 애플리케이션이 관리하는 객체뿐이다. 소유권 없는 diff 엔진은 결국 enxcol_.customers.esc를 지우자고 제안하고, 「drift 도구가 치웠다」는 아주 나쁜 사고 요약이다.
  5. 은퇴는 단계를 밟는다. MongoIndexRetirementState가 index를 선언됨 → 숨김 → 안 쓰는 것 확인 → 지울 수 있음으로 옮기고, 전이마다 배포 한 번이다. 숨기기는 바로 되돌릴 수 있다. 지우기는 다시 만들기다.
  6. Stable validation action은 error와 warn뿐이다. errorAndLog는 7.0이나 8.0에서 Stable 계약에 속하지 않아 거절한다. 조이기는 warn+MODERATE → 경고 0 확인 → error+STRICT로, 배포 두 번에 걸쳐 간다.
  7. TTL은 물리적 치우기일 뿐이다(D-13). MongoExpirationAccessPolicy가 규칙을 말한다: 문서가 있다고 인가가 아니고, 없다고 기한이 아니다. 접근 통제는 만료 필드를 검사하고, 일정은 scheduler를 쓴다.
  8. migration은 checksum을 두고, 잠그고, 전제 조건을 검사하고, 이어서 할 수 있다. MongoMigrationRunner는 적용한 id의 checksum이 바뀌면 단단히 실패한다 — 두 환경이 id 하나 아래 다른 코드를 돌리는 것은 실패한 배포보다 나쁘다.

결과

좋은 점. index 만들기 일정은 용량을 아는 사람이 잡는다. 모든 단계에서 되돌릴 수 있다. drift는 위험하지 않게 보인다. 아무것도 자기가 가지지 않은 것을 지우지 않는다.

나쁜 점. index 더하기는 애너테이션이 아니라 manifest 변경 + 적용이다. 로컬 개발은 APPLY를 쓰므로 마찰은 그것이 정당한 환경에만 머문다.

버린 대안 — 「feature flag와 함께 자동으로 만들기」. flag가 운영에서 켜져 있으면 그것이 문제이고, 꺼져 있으면 manifest가 실제 장치이고 애너테이션은 두 번째의 갈라진 정본이다.