Files
clean-architecture-backend-…/docs/work/reference
DongHyeonka 200019aa5c fix(idempotency)!: 두 멱등 저장소가 operation id·release·inspect에 같게 답한다
문제: 같은 호출에 Redis와 PostgreSQL 저장소(와 in-memory fake)가 다르게
답한다.
- owner token이 같아도 호출이 claim과 다른 operation id를 대면 Redis는
  다섯 전이(start·renew·complete·fail·release)를 OPERATION_CONFLICT로
  거절하고 PostgreSQL·fake는 적용한다. PostgreSQL은 CAS에 핸들의 claim
  operation만 쓰고 호출의 id는 last_transition_operation_id에 적기만 한다.
- PostgreSQL complete 재생은 operation id만 보고 owner를 보지 않아, 같은
  id를 쓴 다른 attempt의 늦은 complete를 이미 적용된 완료로 확인한다.
  Redis는 NOT_OWNER.
- fake의 claim·inspect는 같은 token·다른 operation에 OwnerOperationConflict
  ·OPERATION_CONFLICT를 내지 않는다. PostgreSQL·fake의 inspect는 완료된
  기록이면 그 응답을 재생하고 Redis는 OPERATION_CONFLICT.
- 기록이 없는 release에 Redis는 ALREADY_RELEASED_SAME_OPERATION, PostgreSQL
  ·fake는 ABSENT. Redis release는 revision을 보지 않아, 같은 attempt가 claim을
  넘겨받기 전 핸들로 지금의 claim을 지운다.

방법: 소유자 결정 (a)로 PostgreSQL·fake를 Redis에 맞춘다. owner token이
같고 호출 id가 기록의 claim id와 다르면 다섯 전이 모두 OPERATION_CONFLICT,
기록은 그대로. 나머지 셋은 "거절이 안전한 쪽, 운영 호출자 경로가 안 바뀌는
쪽"으로 정했다.
- complete 재생은 같은 owner token에만 확인한다(Redis에 맞춤).
- fake claim은 진행 중 기록에 OwnerOperationConflict, inspect는 같은 token·
  다른 operation이면 상태와 상관없이 OPERATION_CONFLICT. PostgreSQL inspect도
  완료 재생보다 이 검사를 먼저 한다.
- 기록 없는 release는 셋 다 ABSENT. Redis adapter가 ABSENT를 그대로 넘기고
  RELEASE 스크립트와 command fake가 핸들 revision을 본다. release한 기록을
  지울지 남길지는 저장소 선택이라 release 재시도는 ABSENT(Redis·fake)와
  ALREADY_RELEASED_SAME_OPERATION(PostgreSQL)으로 갈리는 것을 계약이 허용한다.
버린 대안: Redis를 PostgreSQL에 맞추기(Redis에는 전이 id를 둘 필드가 없어
인자가 죽는다), PostgreSQL release를 삭제로 바꾸기(release 뒤 기록 모양은
계약이 저장소 선택으로 정해 두었다), 기록 없는 release를 셋 다
ALREADY_RELEASED로(찾지 못한 것을 성공으로 확인한다 — JPA 설계 22.2와 반대).
공유 계약 IdempotencyStoreContract에 12케이스를 더했다. 포트·결과 enum
Javadoc, persistence-jpa·cache-redis README, TESTING_STRATEGY, application-core
CLAUDE.md, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다.

위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 늘 claim의 id를 넘기고
release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접 부르며 전이마다
다른 id를 넘기던 코드는 OPERATION_CONFLICT를 받는다. PostgreSQL 통합
테스트가 그렇게 쓰고 있어 claim의 id로 바꿨다. last_transition_operation_id
열은 이제 늘 claim_operation_id와 같다(마이그레이션은 건드리지 않음).
같은 token의 넘겨받기 전 핸들로 이미 끝난 complete·markFailed를 다시 보내는
경우는 저장소마다 답이 다르다(범위 밖, 보고에 적음).

검증: desktop, 공유 잠금, 기준 06f520e6.
- RED(기준 커밋 + 계약만): in-memory fake 계약 49 중 8 실패, Redis
  command fake 2, 실 Redis(redisContainerContractTest) 2, 실 PostgreSQL
  (jpaPlatformContractTest) 7 — 실패 메시지가 위 차이 그대로("expected:
  OPERATION_CONFLICT but was: STARTED", "expected: ABSENT but was:
  ALREADY_RELEASED_SAME_OPERATION" 등).
- GREEN(이 커밋과 같은 트리): 네 leaf check(application-core 412·skip 19
  시간 케이스, persistence-jpa 664, cache-redis 215, redis-runtime 65),
  네 leaf testQualityCheck, jpaPlatformContractTest 419,
  postgresqlIdempotencyIntegrationTest 10, redisContainerContractTest 90,
  app-bootstrap integrationTest 10, sample integrationTest 63,
  documentContractTest 65, architectureTest 228, composition:idempotency
  check 32 — 모두 rc=0, 실패·skip 0(fake 시간 케이스 19 제외).
- scripts/check-work-docs.py, --links docs, git diff --check 통과.

Refs: docs/reviews/2026-11-03-rereview/round6/02-idempotency-outbound.md Declined to judge
BREAKING CHANGE: 멱등 store 포트를 직접 부르는 코드는 전이마다 claim의
operation id(IdempotencyOwner.claimOperationId())를 넘겨야 한다. 다른 id는
OPERATION_CONFLICT다. Redis release는 기록이 없으면 ABSENT를 돌려준다.
직접 구현한 store는 IdempotencyStoreContract의 새 케이스를 통과해야 한다.
2026-11-06 22:25:45 +09:00
..