[QA] QA-12 검증 실행 시점·배치 5모드 · 트랜잭션 경계 · 멱등성

[yslee4601]

우선순위 P2 · 출시 전 전수 QA 12/13 · 상위 이슈 #252

배경

인터페이스정의서 6장이 같은 1,200% 검증을 언제 도느냐를 5가지 모드로 나눴다.
"계산 엔진은 하나, 부르는 시점만 5가지"가 설계 원칙인데, 엔진이 정말 하나인지 확인된 적이 없다.
다섯 개의 답이 서로 다르면 이 제품의 신뢰가 무너진다.

검사 대상 — 5가지 실행 모드

모드	언제	결과가 남는 곳
① 즉시 재계산	데이터 변경 직후, 도메인 이벤트 리스너	cap_check(check_kind='REALTIME')
② 확정 전 차단 검증	POST /transactions/{id}/confirm (IF-API-25)	cap_check(check_kind='PRE_CONFIRM') · exception_case
③ 수동 재검증	CONT-W02 [한도 재검증] (IF-API-19B)	cap_check(check_kind='MANUAL') — V28__add_manual_cap_check_kind
④ 월 통합검증	VRUN-W02 실행 (IF-API-48)	validation_run 10단계
⑤ 일배치	변경 계약 스캔	batch_watermark

볼 것

1. 엔진 단일성 — 5개 모드가 정말로 같은 계산 코드를 부르는가. 같은 입력에 같은 답을 주는가
2. 10단계 진행률 — 운영정책서 제43조 current_step 모델대로 도는가. 실패 시 어디서 멈추고 무엇이 남는가
3. 트랜잭션 경계
   • 4-3 규칙 3: 확정 검증과 예외 생성은 같은 트랜잭션 — 한도 초과로 막혔는데 예외가 안 만들어지면 그 건이 영영 묻힌다
   • 4-3 규칙 5: POST /contracts 는 같은 트랜잭션에서 예상 스케줄까지 만든다
   • 배치 Step 경계와 롤백 범위 (06_배치_Step_협업계약.md)
4. 멱등성
   • FUN-040 스케줄 생성 멱등성
   • Idempotency-Key (IF-API-51)
   • ⑩ 확정 후 재실행 시 중복 0건 (시연 10컷 마지막)
   • 데모 시드 재실행
5. 동시성 — 같은 검증 실행에 두 요청이 동시에 오면(FGC-VRUN-005), 대사 실행 중복(uq_reconciliation_run), V7__run_progress_and_snapshot_locks 의 잠금이 실제로 동작하는가
6. 확정 후 잠금 — V30__validation_run_finalization · V31__lock_reconciliation_results_after_validation_finalization 이 전 화면·전 API에서 지켜지는가
7. 배치가 앱 기동 시 저절로 안 도는가 — spring.batch.job.enabled: false
8. 시간대 — SIR-008 Asia/Seoul. 월 경계(말일 23:59 / 1일 00:00) 처리

통과 기준

• 5개 모드가 같은 입력에 같은 판정을 냄을 테스트로 확인
• 확정 검증 ↔ 예외 생성 트랜잭션 원자성이 실패 주입 테스트로 확인되었다
• 재실행 중복 0건이 실측되었다
• 동시 요청 시나리오가 테스트로 있다
• 확정 후 잠금이 전 경로에서 확인되었다
• 월 경계 시각 처리가 확인되었다

---

공통 규칙 (모든 QA 이슈에 적용)

• 근거 없는 수정 금지 — 00_인덱스/근거대장.md를 먼저 읽고, 모든 수정 제안에 근거 ID(REG-xx / SRC-xx)를 붙인다. 못 붙이면 "근거 없음 — 확인 필요"로 남긴다.
• 발견을 3분류한다 — ① 문서가 틀림 ② 구현이 틀림 ③ 아직 구현 안 됨(문서 유효). ③을 ①로 오인해 지우면 설계 의도가 사라진다.
• 이 이슈에서 직접 고치는 것은 "명백한 오기·1줄짜리"까지. 판단이 필요한 것은 후속 이슈로 분리하고 여기에 링크한다.
• PR 하나가 커지지 않게 — 검사 결과를 먼저 이 이슈에 표로 남기고, 수정은 그다음에 올린다.

[yslee4601]

QA-12 결과 — 1,200% 검증 5개 실행 모드 (기준 f12a2ddf)

총평: PASS. 5개 모드 전부 단일 엔진(CapCalculator.calculate)으로 수렴하고,
트랜잭션 경계·멱등성·동시성·확정 후 잠금 모두 통과. 통합 테스트 4클래스
(BatchWriterIdempotency / FinalizedValidationRunImmutability /
ValidationRunFinalizationService / CommissionPayment) GREEN.

통과 기준 6개

1. 엔진 단일성 ✅ — ①③④⑤는 CapCheckServiceImpl.calculateAndSave 공통 경로,
   ②는 같은 엔진 + 실제 확정액 병합(문서화된 의도, CommissionPaymentServiceImpl:1461).
2. 트랜잭션 경계 ✅ — confirm noRollbackFor 구조로 "예외 기록 후 거부" 커밋(:158, failFirst:1083),
   POST /contracts 같은 트랜잭션 스케줄 생성(ContractService:124-173), 배치 Step은 docs/06 계약과 1:1.
3. 멱등성 ✅ — 확정 재시도 cap_check 중복 0건(테스트 확증), IF-API-51 키+V30 UNIQUE,
   월 배치 uq_cap_check_monthly upsert, 시드는 Flyway 버전 관리라 재실행 자체가 없음.
4. 동시성 ✅ — 실행 기동 3중 방어(CREATED guard → 단일스레드 재확인 → 조건부 UPDATE),
   uq_reconciliation_run + FOR UPDATE 직렬화, finalize 행 잠금+조건부 UPDATE.
5. 확정 후 잠금 ✅ — V1/V7/V31 트리거가 결과 테이블 전체를 DB 수준에서 차단, 앱/화면/직접 SQL 우회 불가.
6. 설정 ✅ — spring.batch.job.enabled=false, Asia/Seoul(@scheduled zone 포함), 월 경계는 LocalDate 산술.

발견 (조치 제안)

• [③ 미구현/문서 유효] IF-EVT-01~05 도메인 이벤트 미구현 — 모드 ①은 동기 인라인 호출로 동작(기능 동등).
  실효·부활 등 상태사건 즉시 재계산은 일배치로만 보정됨. 문서에 "1차 동기 호출" 각주 제안.
• [③ 미구현/문서 유효] 일배치의 차익거래·원장 재검사 미구현(§7-5 대비) — 코드 주석에 예정 명시.
• [하] FINALIZED 잠금이 journal_header 정정·schedule_header에는 앱 계층에만 있음(결과 스냅샷은 DB 불변).
• [하] 모드 ② cap_check INSERT 2벌(유지보수 리스크, 현재 값 불일치 불가능).

상세: qa-findings/qa-12-report.md