Files
clean-architecture-backend-…/docs/testing
DongHyeonka 1443510638 fix(idempotency)!: 이미 적용된 전이는 그 전이를 적용한 핸들에게만 확인한다
문제: 이미 적용된 전이를 다시 보낸 호출에 Redis·PostgreSQL 저장소와
in-memory fake가 다르게 답한다.
- 같은 attempt가 넘겨받기 전 핸들로, 넘겨받은 뒤 적용된 complete를 다시
  보내면 Redis·PostgreSQL은 ALREADY_COMPLETED_SAME_RESULT, fake는 NOT_OWNER.
- 같은 경우의 markFailed는 Redis ALREADY_MARKED_SAME_OPERATION, PostgreSQL
  OPERATION_CONFLICT, fake NOT_OWNER. markFailed를 적용한 핸들이 응답을
  잃고 다시 보내면 fake만 NOT_OWNER.
- release한 핸들로 start하면 PostgreSQL은 NOT_OWNER, Redis·fake는 ABSENT.
- 같은 원인(재생 판정이 "어느 핸들이 적용했나"를 보지 않음)이 다른 전이에도
  있다. PostgreSQL은 기록된 renew·release와 digest가 다른 핸들을 모두
  OPERATION_CONFLICT로 답해, 주인이 renew가 돌려준 핸들로 다시 renew해도
  거절하고 넘겨받기 전 핸들의 renew·release도 OPERATION_CONFLICT다. fake는
  적용한 핸들이 start·renew를 다시 보내도 NOT_OWNER다.

방법: 소유자 결정(2026-11-06) 「넘겨받기 전 핸들의 재전송」「해제된 핸들로
start」대로 맞춘다. "적용한 핸들"은 owner identity가 같고 기록보다
revision이 하나 낮은 핸들이다. 라운드6에서 start에 쓴 기준을 모든 전이에
쓴다.
- Redis TRANSITION과 command fake: ALREADY 조건에서 "start가 아니면 아무
  핸들" 분기를 지우고 rev == handle rev + 1만 남긴다. 다른 핸들은 revision
  검사로 내려가 NOT_OWNER·WRONG_STATE.
- PostgreSQL: replayVerdict가 적용한 핸들일 때만 재생(같은 digest → 이미
  처리됨, 다른 digest → OPERATION_CONFLICT)으로 읽는다. 다른 핸들은 owner
  검사로 내려가 NOT_OWNER. complete 재생 판정도 owner token 대신 적용한
  핸들을 본다.
- fake: 마지막으로 적용한 전이와 그 핸들·인자(renew lease, fail disposition)
  를 기억해 start·renew·complete·markFailed 재전송에 저장소와 같게 답한다.
- release한 핸들의 start는 계약이 ABSENT·NOT_OWNER를 둘 다 받고 포트
  Javadoc(IdempotencyStartOutcome)에 적는다. 코드 동작은 그대로.
버린 대안: PostgreSQL complete·fail 재생을 전이 digest 비교만으로
하기(complete digest에 replay TTL이 들어가 같은 결과·다른 TTL 재전송이
RESPONSE_CONFLICT가 된다), Redis를 원래 주석 의도대로 두고 fake·PostgreSQL을
"operation의 아무 핸들"로 넓히기(소유자 결정과 반대, 넘겨받기 전 핸들이 남의
결과를 자기 것으로 확인받는다), 재생 핸들을 attempt만으로 가리기(같은
attempt가 넘겨받으면 attempt가 올라가지만 renew 뒤의 낡은 핸들은 attempt가
같다).
공유 계약 IdempotencyStoreContract에 10케이스를 더했다. 포트 결과 enum
Javadoc 넷, application-core CLAUDE.md·README, persistence-jpa·cache-redis
README, TESTING_STRATEGY, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다.

위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 넘겨받기 전 핸들로 다시
보내지 않고 renew·release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접
부르는 코드는 넘겨받기 전 핸들의 재전송에 NOT_OWNER를 받고, PostgreSQL에서
renew를 이어 부를 수 있게 된다. fake로 응답 유실을 흉내 내던 테스트는 이제
"이미 처리됨"을 받는다. 적용한 핸들이 markFailed를 다른 retention·disposition
으로 다시 보낼 때의 답은 저장소마다 다르고 IdempotencyFailOutcome Javadoc과도
다르다(범위 밖, 보고에 적음).

검증: desktop, 공유 잠금, 기준 73d39212.
- RED(기준 커밋 + 계약 테스트만, 로그 ~/r8-f4-red-logs/): in-memory fake
  계약 59 중 4 실패(적용한 핸들의 start·renew·markFailed 재전송,
  "expected: ALREADY_MARKED_SAME_OPERATION but was: NOT_OWNER" 등), Redis
  command fake 2·실 Redis(redisContainerContractTest) 2 실패("expected:
  NOT_OWNER but was: ALREADY_COMPLETED_SAME_RESULT"·"…ALREADY_MARKED_SAME_
  OPERATION"), 실 PostgreSQL(jpaPlatformContractTest) 5 실패(complete는
  ALREADY_COMPLETED_SAME_RESULT, markFailed·renew·release는
  OPERATION_CONFLICT, 두 번째 renew는 "expected: RENEWED but was:
  OPERATION_CONFLICT"). release한 핸들의 start 케이스는 동작 변경이 없어
  처음부터 셋 다 통과한다. lane마다 실패 수는 위 계약 실패 수와 같다.
- GREEN(이 커밋과 같은 트리 377d1232, 로그 ~/r8-f4-green-logs/): 네 leaf
  check(application-core 422·skip 19 fake 시간 케이스, persistence-jpa 664,
  cache-redis 225, redis-runtime 65), 네 leaf testQualityCheck,
  redisContainerContractTest 100, jpaPlatformContractTest 429,
  postgresqlIdempotencyIntegrationTest 10, fake를 쓰는 leaf(composition:
  idempotency check 32, redis-sdk test 310, web test 329, sample-portfolio
  test 339), documentContractTest 66 — 모두 rc=0, 실패 0.
- scripts/check-work-docs.py, git diff --check 통과.

BREAKING CHANGE: IdempotencyStorePort 구현은 이미 적용된 전이의 재전송을 그
전이를 적용한 핸들(기록보다 revision이 하나 낮은 핸들)에게만 "이미 처리됨"
으로 확인하고 다른 핸들은 NOT_OWNER로 답해야 한다. 직접 구현한 store는
IdempotencyStoreContract의 새 케이스로 확인한다.
2026-11-07 01:01:41 +09:00
..