Files
clean-architecture-backend-…/docs/mongodb/runbooks/unknown-commit.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

4.4 KiB

title, category, severity, owner, last_updated, status
title category severity owner last_updated status
Runbook — MongoDB transaction commit 결과를 모름 mongodb P1 oncall 2026-08-13 운영

Runbook: transaction commit 결과를 모름

설계서 §16, 결정 D-10, 시나리오 UNKNOWN_TRANSACTION_COMMIT_RESULT.

MongoExecutionOutcome.TRANSACTION_COMMIT_UNKNOWN은 commit이 적용됐을 수 있다는 뜻이다. 실패가 아니고, 호출자에게 실패로 알리면 절대 안 된다. 가장 나쁜 대응은 transaction 본문을 다시 돌리는 것이다. commit이 적용됐다면 본문이 두 번 적용된다.

증상

  • 로그의 MongoTransactionCommitUnknownException.
  • Metric failureCategory=TRANSACTION_COMMIT_UNKNOWN.
  • 보통 primary 선출과 함께 온다. failover.md를 본다.
  • 하류에서 효과가 두 번 났다는 보고(이중 결제, 이중 증가)는 이 상황 자체가 아니라 이것을 잘못 다룬 결과다.

진단

  1. 플랫폼이 자동으로 옳게 했는지 확인한다. MongoTransactionRetryCoordinator는 같은 session에서 MongoRetryBudget 안에서 commit만 재시도한다. 이미 commit된 transaction에 대한 commit 재시도는 설계상 아무 일도 하지 않는다. 대부분은 여기서 끝나고 사람에게 오지 않는다.

  2. 예산을 다 썼으면 실제 상태를 알아낸다. commit은 적용됐거나 안 됐다. 짐작하지 말고 어느 쪽인지 알아내야 한다.

    • 본문이 결정적 표시(멱등 key, 업무 id, revision)를 썼으면 그것을 다시 읽는다. MongoCommitReconciler가 하는 일이 정확히 이것이고, 설계가 transaction에 표시를 쓰라고 요구하는 이유다.
    • 표시가 없으면 하류 흔적에서 되짚는다: outbox 행, 감사 기록, 외부 부수 효과. 비교할 것이 아무것도 없으면 그 transaction은 맞춰 볼 수 있게 설계되지 않은 것이고, 그것을 발견 사항으로 적는다.
  3. 본문이 다시 돌았는지 본다. 같은 연산 이름과 correlation id로 두 번째 실행이 있는지 grep한다. 본문이 두 번 돌았으면 효과를 되돌려야 하고, 다시 돌린 코드 경로는 결함이다. 결과를 모르는 commit의 범위는 COMMIT_ONLY(MongoRetryScope.COMMIT_ONLY)이고 BODY가 아니다.

조치

commit이 적용됐다. 할 일은 없다. 맞춰 본 결과를 기록한다.

commit이 적용되지 않았다. 연산 전체를 처음부터 다시 돌린다. 새 session, 새 본문 시도. 앞 시도가 흔적을 남기지 않았음을 확인했으므로 안전하다.

알아낼 수 없다. 재시도하지 않는다. 상향 보고한다. 여기서 확인 없이 재시도하면 「효과 없음」과 「효과 두 번」 사이의 동전 던지기다. 결제나 알림 경로에서는 중복이 지연보다 나쁘다. 도메인이 지원하면 대상 엔티티를 얼리고, 연산 이름, correlation id, 문서 id, 시간 구간, 확인한 것을 넘긴다.

반복된다. 한 시간에 한 번을 넘으면 commit 경로가 구조적인 무언가와 경쟁하고 있다. 관측한 선출 시간보다 짧은 maxCommitTime, 너무 큰 transaction, 너무 작은 재시도 예산 같은 것이다. 예산이나 transaction 모양을 고친다. 재시도 횟수만 올리고 해결됐다고 하지 않는다.

예방

  • 모든 transaction 본문은 자기 commit을 식별하는 결정적 표시를 쓴다.
  • maxCommitTime은 관측한 선출 시간의 p99보다 길다.
  • 호출자는 결과를 모른다는 사실을 일반 500으로 바꾸지 않고 자기 호출자에게 그대로 올린다. 결과를 모르는 것을 실패로 알리면 호출자가 재시도하고, 그것이 일어나면 안 되는 단 하나의 일이다.
  • 문서 하나의 atomic 연산을 먼저 쓴다(D-09). 문서 하나의 쓰기를 감싸려고만 있는 transaction은 이 실패 모드를 쓸데없이 만든 것이다.

상향 보고

  • 상태를 알아낼 수 없고 연산에 외부 효과가 있으면 늘 P1.
  • 서비스 소유자를 바로 호출한다. DB 소유자는 선출이 원인일 때만 호출한다.

확인

./gradlew :adapter:outbound:persistence-mongo:mongoFailoverTest --console=plain

MongoFailoverScenario.UNKNOWN_TRANSACTION_COMMIT_RESULT가 이 경로를 실제 노드 세 개짜리 set에서 돌리고, coordinator 테스트가 commit 결과를 모를 때 본문을 다시 돌리지 않음을 단언한다.