docs: 회복 필요 응답의 클라이언트 안내를 한 가지로 맞추고 확인 리뷰를 기록한다

문제: 70fb80bf 뒤 IDEMPOTENCY_RECOVERY_REQUIRED에 대한 클라이언트 안내가
문서마다 달랐다. http-contract 표는 새 키 금지, 매뉴얼 05 표는 옛 문구(재전송도
위험), runbook은 효과가 없으면 새 키라고 했다. 결정 ① 뒤에는 같은 키 재전송이
작업을 다시 돌리지 않으므로 안전하다.

방법: 세 문서를 "자동 재시도 안 함, 같은 키 재전송은 안전(서버가 판정하고
다시 돌리지 않음), 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키"로
맞췄다. 70fb80bf 확인 리뷰(Important 0, Minor 9) 결과를 재리뷰 README 15.2절과
round5/review.md에 남기고, 업그레이드 안내의 결정 행에 커밋 해시를 적었다.

위험·한계: 문서만 바뀐다. 나머지 Minor 8건은 기록만 했다.

검증: :app-bootstrap:documentContractTest, :app-bootstrap:repositoryContractTest
통과.

Refs: docs/reviews/2026-11-03-rereview/README.md 15.2절
This commit is contained in:
DongHyeonka
2026-11-04 20:36:39 +09:00
parent 70fb80bf04
commit c508b1ba4b
5 changed files with 207 additions and 8 deletions
+1 -1
View File
@@ -51,7 +51,7 @@ DB 커밋 중 연결 끊김 ─────────────────
| 422 `IDEMPOTENT_REQUEST_MISMATCH` | 같은 키에 다른 본문 | 클라이언트 버그. 재전송 안 함 |
| 503 `IDEMPOTENCY_UNAVAILABLE` | 실행 전 거부 | 같은 키로 나중에 |
| 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, `retryable=true` | 실행 뒤 결과 기록 실패. 적용됐을 수 있음 | "적용 안 됨"이라 하지 않는다. **같은 키로** 나중에 재전송, 새 키 금지 |
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 재전송·재실행 모두 위험. 업무 데이터로 확인 |
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 자동 재시도 안 함. 같은 키 재전송은 안전(재생·실행·다시 500을 서버가 판정, 다시 돌리지 않음). 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키 |
| 500 `DB_COMPLETION_UNKNOWN`, `retryable=false` | DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 | 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정 |
같은 키 재전송은 작업을 다시 돌리지 않는다. 첫 시도가 실행을 시작한 뒤 processing lease(기본 30s)가
@@ -318,3 +318,9 @@ PR #1을 만든 뒤 사용자가 묶음이 기본값으로 정한 세 가지를
| `:performanceCheck` | rc=0 | 27초 | 22.93 |
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 4초 | 20.00 |
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 18.72 |
### 15.2 확인 리뷰 (`70fb80bf`만)
리뷰어 1명([round5/review.md](round5/review.md)): Critical 0, **Important 0**, 회귀 0, Minor 9(7건은 이 커밋, 2건은 이전부터). 결정 ①②③이 코드·공유 계약·문서에 결정대로 들어갔고, lease가 지난 `EXECUTING`을 다시 실행하는 경로는 남지 않았으며, PostgreSQL과 Redis가 같은 판정을 한다.
Minor 중 RR5-01-01(`IDEMPOTENCY_RECOVERY_REQUIRED`의 클라이언트 안내가 `http-contract.md` 표·매뉴얼 05 표·runbook에서 서로 다름 — 표는 "새 키 금지", runbook은 "효과가 없으면 새 키")은 오케스트레이터가 이번 커밋에서 만든 모순이라 바로 고쳤다: 세 문서와 프론트 인계 문서를 "자동 재시도 안 함, 같은 키 재전송은 안전(서버가 판정하고 다시 돌리지 않음), 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키"로 맞췄다. 나머지 Minor 8건은 11.1절 결정대로 기록만 한다(round5/review.md) — 그중 RR5-02-01은 heredoc·호출하지 않은 함수·여러 줄 문자열 안의 `cd`도 따라간다는 것으로, 이 repo에서는 그 step이 실패해 조용한 거짓 통과는 아니다.
@@ -0,0 +1,193 @@
# r8 확인 리뷰 (2026-11-04)
대상: 커밋 `70fb80bf`(소유자 결정 ①②③ 반영), Base `b76285a5`. 리뷰어 1명이 세 영역을 나눠 직접 봤다(하위 에이전트 없음).
발견 ID는 `RR5-<영역>-<순번>`이다. 영역 번호: 01 멱등성(결정 ①), 02 workflow `cd`(결정 ②), 03 설정 검사(결정 ③).
## 범위
### 본 pathspec
| 영역 | pathspec |
| --- | --- |
| 01 멱등성 | `src/application-core` (idempotency 패키지·CLAUDE.md·README, testFixtures `IdempotencyStoreContract`), `src/adapter/outbound/persistence-jpa` (`.../idempotency/postgresql`, 통합 테스트, README), `src/adapter/outbound/cache-redis` (`IdempotencyScripts`, `RedisIdempotencyStoreAdapter`, 테스트, README), `src/adapter/outbound/redis-runtime/src/testFixtures` (`InMemorySemanticRedisCommands`), `docs/web/http-contract.md` §2, `docs/manual/05-idempotency.md`, `docs/runbooks/idempotency-unavailable.md`, `docs/upgrade/2026-11-maturity-review.md`(B-30·5절 표), `docs/study/postgresql-jpa-walkthrough.ko.md` |
| 02 workflow `cd` | `src/build-logic` (`WorkflowGradleInvocations`, `StrictLaneStagesPlugin`, 두 테스트, README), `AGENTS.md`, `CLAUDE.md`, `docs/upgrade/...`(B-36) |
| 03 설정 | `src/composition/idempotency` (`IdempotencySettings`, 테스트, README), `docs/registries/env-keys.yaml`, `src/.env.example`, `docs/upgrade/...`(B-24) |
요구사항은 `docs/reviews/2026-11-03-rereview/README.md` 15절(결정 ①②③과 r8 묶음 결과·남은 것)으로 맞춰 봤다.
변경 밖이지만 판정에 필요해 함께 읽은 것: `IdempotencyExecutor` 전체, PG `IdempotencyClaimGateway`의 INSERT, `PublishPosterImageUseCase`(executor 호출 모양), 두 저장소의 `markFailed`·`complete`, cache-redis·persistence-jpa의 lane 정의.
### 불러온 스킬과 적용한 기준
| 스킬 | 적용한 기준 | 본 것 |
| --- | --- | --- |
| `superpowers:requesting-code-review` | 리뷰어 템플릿: 계획(15절 결정) 대비 구현, 테스트가 진짜 동작을 보는가, 호환성·마이그레이션, Strengths·심각도별 Issues·Assessment, Declined to judge, 읽기 전용, 하위 에이전트 금지 | 결정 ①②③을 코드·계약 테스트·문서와 하나씩 맞췄다. 이 문서 양식이 그 템플릿이다 |
| `api-and-interface-design` | 멱등 키 절: 원자적 claim(유일 제약·원자 스크립트), 처리 중 중복에 대한 의도된 응답, 결과는 성공·실패·불명 셋, 보존 기간은 가장 긴 재전송 경로보다 길게. Hyrum's Law(관찰되는 동작 변경), 일관된 오류 의미(값 하나에 뜻 하나) | PG `on conflict` + 행 잠금과 Lua 원자성에서 늦은 완료가 다른 판정과 겹치지 않는지, `inspect`·`renew` 결과 값의 뜻 변화(RR5-01-02), 계약 문서끼리의 안내 일치(RR5-01-01), `failure-retention ≥ replay-ttl` 검사 |
| `doubt-driven-development` | 주장(CLAIM)을 적고 반증을 먼저 찾는다. 하위 에이전트를 띄울 수 없어 자기 반대 논증으로 대신했다 — 새 맥락 리뷰가 아니므로 약한 형태다. 교차 모델 검토는 비대화 하위 에이전트 맥락이라 건너뛰었다 | 주장 4개를 반증하려 했다: "다시 실행하는 경로가 없다"(TakenOver를 만드는 곳 전부, 같은 attempt 재사용 경로), "두 저장소가 같은 판정을 한다"(CLAIM·TRANSITION·RENEW·INSPECT 대조), "cd 추적이 새 거짓 통과를 만들지 않는다"(셸 모양 18개 실행), "③이 기존 설정을 깨지 않는다"(저장소 안 설정값 검색) |
| `ci-cd-and-automation` | 게이트를 조용히 건너뛰지 못하게, 실패를 숨기는 명령을 실행으로 세지 않게 | `verifyStrictLaneStages`가 실제로는 돌지 않거나 실패를 막지 못하는 명령을 세는 모양(RR5-02-01·02), 실제 workflow에 대한 판정 |
### 실행한 명령과 결과
- `git diff --stat b76285a5..70fb80bf`, 영역별 `git diff b76285a5..70fb80bf -- <pathspec>`, `git show 70fb80bf:<file>`.
- 셸 모양 판독 실험: HEAD의 `WorkflowGradleInvocations.java`를 scratchpad로 꺼내 `javac`로 따로 컴파일하고, `run: |` 스크립트 18개를 읽혔다. 결과는 RR5-02-01·02 근거에 적었다.
- 별도 worktree(`git worktree add --detach <scratchpad>/rr5 70fb80bf`), 공유 잠금(`flock .../heavy.lock`) 아래:
- `./gradlew :application-core:test --tests '*InMemoryIdempotencyStoreContractTest' :adapter:outbound:cache-redis:test --tests '*RedisIdempotencyStoreContractTest' --tests '*RedisIdempotencyStoreAdapterTest' :composition:idempotency:test --tests '*IdempotencySettingsTest' --offline` → rc=0. 결과 XML: fake 계약 25개 중 12개 skip, command fake 위 Redis 계약 25개 중 12개 skip(둘 다 시간 케이스 12개 전부), `RedisIdempotencyStoreAdapterTest` 30/30, `IdempotencySettingsTest` 22/22. `-q`로 돌려 결과가 빌드 캐시에서 복원됐는지는 확인하지 않았다.
- `./gradlew -p build-logic test --tests '*WorkflowGradleInvocationsTest' --offline` → rc=0, 20/20.
- `./gradlew verifyStrictLaneStages --dry-run --offline` → `every strict lane is in an executed stage.`
- 끝나고 `git worktree remove --force`.
### 못 본 것
- 실 PostgreSQL·실 Redis 계약 lane(`jpaPlatformContractTest`, `redisContainerContractTest`)은 다시 돌리지 않았다. Docker가 필요하다. README 15절의 결과(PG 계약 25/25, `redisContainerContractTest` 64/64)와 Redis lane의 `rejectSkipped = true`(`src/adapter/outbound/cache-redis/build.gradle:92`)를 근거로 삼았다.
- 프론트 짝 문서(`clean-architecture-frontend-template` `docs/architecture/backend-api-and-server-state-contract.md`)는 다른 repo라 보지 않았다.
- optional-platforms 빌드의 `verifyStrictLaneStages`는 돌리지 않았다(README 15.1 통과 기록만 봤다).
## Strengths
- 결정 ①을 두 저장소가 같은 모양으로 구현했다. PG는 lease 지난 `EXECUTING`에 아무 문장도 실행하지 않고 `RecoveryRequired`만 돌려준다(`PostgreSqlIdempotencyStore.java:153-159`). Redis CLAIM도 `rev`·TTL을 건드리지 않고 답한다(`IdempotencyScripts.java:92-97`). 지운 `abandonExpiredExecution` SQL이 갖던 "갱신 실패 → indeterminate" 분기도 함께 사라져 실패 경로가 하나 줄었다.
- 넘겨받기 경로가 둘(만료된 `CLAIMED`, `FAILED_RETRYABLE`)로만 남았다. PG `resetClaim` 호출 3곳(`PostgreSqlIdempotencyStore.java:131-133, 147-152`)과 Redis `TAKEN_OVER` 1곳(`IdempotencyScripts.java:98-107`) 어디에도 `EXECUTING`이 없다.
- `renew`는 두 저장소가 같은 조건으로 거절한다. PG는 원래 `processing_lease_until > clock_timestamp()`가 있었고(`IdempotencyTransitionGateway.java:74`), Redis RENEW가 같은 검사를 서버 `TIME`으로 더했다(`IdempotencyScripts.java:215-220`).
- 공유 계약에 시간 케이스 6개를 더해 두 실 저장소에서 같은 판정을 강제한다(`IdempotencyStoreContract.java:493-617`). 옛 "늦은 complete 거절" 케이스를 지우지 않고 반대로 바꿔(`:516-532`) 이전 결정과의 차이가 테스트 이력에 남는다.
- command fake의 Lua 복사본 세 곳을 같은 커밋에서 맞췄다(`InMemorySemanticRedisCommands.java:227-232, 324-327, 378-386`). adapter 테스트가 늦은 complete·재생, inspect, renew를 fake 시계로 본다(`RedisIdempotencyStoreAdapterTest.java:356-425`).
- runbook이 "lease 지난 `EXECUTING`은 지우지 않는다"를 이유(늦은 결과가 `ABSENT`를 만나 사라지고 같은 키가 다시 실행된다)와 함께 적고(`docs/runbooks/idempotency-unavailable.md:99-102`), 옛 버전이 남긴 `EXPIRED_EXECUTION` 행을 읽는 법도 남겼다(`:75-76`).
- 결정 ③의 메시지가 두 키와 두 값을 함께 보여 준다(`IdempotencySettings.java:91-101`). 경계값(같으면 통과, 1분 짧으면 거부)을 테스트가 본다(`IdempotencySettingsTest.java:204-249`).
- 결정 ②의 판독이 보수적이다. `cd`는 "정확히 두 단어 + 따옴표 벗긴 상대 경로"일 때만 따라간다(`WorkflowGradleInvocations.java:266-271`). 따옴표 안 `;`, 백틱, `builtin cd`, `cd --` 같은 모양은 모두 "읽지 않음"으로 떨어진다. 실험에서 확인했다.
- 세지 않은 명령을 이유와 함께 실패 메시지에 싣는다(`StrictLaneStagesPlugin.java:154, 194-213`). 파생 서비스가 왜 실패하는지 메시지만으로 안다.
## 발견 재확인 표
| ID | 상태 | 근거 |
| --- | --- | --- |
| 결정 ① lease 지난 `EXECUTING` → 기록 그대로 `RecoveryRequired` | 닫힘 | `PostgreSqlIdempotencyStore.java:153-159`, `IdempotencyScripts.java:92-97`, `InMemorySemanticRedisCommands.java:227-232`, 계약 `IdempotencyStoreContract.java:493-514` |
| 결정 ① 주인의 늦은 `complete`·`markFailed` 기록, 다음 claim 재생 | 닫힘 | PG `COMPLETE_SQL`·`FAIL_SQL`은 lease를 보지 않는다(`IdempotencyTransitionGateway.java:77-120`), Redis TRANSITION도(`IdempotencyScripts.java:112-158`). 계약 `:516-577` |
| 결정 ① 주인 아닌 호출 거절 | 닫힘 | 소유자 튜플 비교가 그대로다(`PostgreSqlIdempotencyStore.java:479-505`, `IdempotencyScripts.java:122-141`). `EXECUTING`은 넘겨받지 않으므로 다른 주인이 생기지 않는다 |
| 결정 ① `renew` 거절 | 닫힘 (Minor RR5-01-02) | `IdempotencyScripts.java:215-220`, `IdempotencyTransitionGateway.java:74`, 계약 `:600-617` |
| 결정 ① 남의 lease 지난 실행 `inspect` → `ABANDONED` | 닫힘 (Minor RR5-01-02) | `PostgreSqlIdempotencyStore.java:421-426`, `IdempotencyScripts.java:292-300`, `RedisIdempotencyStoreAdapter.java:394-397`, 계약 `:580-598` |
| 결정 ① 문서(http-contract·manual·runbook·upgrade) | 부분 | 동작 설명은 맞다. 클라이언트 안내가 세 문서에서 갈라졌다(RR5-01-01) |
| 결정 ② 같은 셸의 `cd <상대 경로>` 추적 | 닫힘 (Minor RR5-02-01) | `WorkflowGradleInvocations.java:212-308`, 테스트 `WorkflowGradleInvocationsTest`(20/20), 실제 workflow 판정 통과 |
| 결정 ③ `failure-retention < replay-ttl` 기동 실패 | 닫힘 (Minor RR5-03-01) | `IdempotencySettings.java:87-101`, `IdempotencySettingsTest.java:204-249`, `env-keys.yaml:1683-1698`, B-24 |
| README 15절 남음: CLAIMED → 시작에서 PG는 lease를 보고 Redis는 보지 않는다 | 그대로(이전부터, 결정 범위 밖) | PG `START_SQL`(`IdempotencyTransitionGateway.java:39`) vs Redis TRANSITION(lease 검사 없음). 결정 ① 뒤로는 Redis 쪽이 오히려 결과를 남긴다. 중복 실행은 없다 |
| README 15절 남음: `|| true`·`| tee`·`if` 안 gradlew를 실행으로 센다 | 그대로(이전부터) | 같은 종류의 모양 둘을 더 찾았다(RR5-02-02) |
회귀로 판정한 발견은 없다.
## Issues
### Critical (Must Fix)
없음.
### Important (Should Fix)
없음.
### Minor (Nice to Have)
#### RR5-01-01 · `IDEMPOTENCY_RECOVERY_REQUIRED` 클라이언트 안내가 세 문서에서 갈라졌다
- 위치: `docs/web/http-contract.md:113`, `docs/manual/05-idempotency.md:54`, `docs/runbooks/idempotency-unavailable.md:97`
- 무엇이 틀렸나: 이 커밋이 http-contract 표 행만 바꿨다. 세 문서가 이제 서로 다른 말을 한다.
- http-contract 표: "같은 키로 다시 보내도 서버는 작업을 다시 돌리지 않는다 … 아니면 다시 500이다. 새 키로 보내지 않는다."
- 같은 절 아래 문단(`http-contract.md:127`): "효과 없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다." 표의 "다시 돌리지 않는다 / 아니면 다시 500"과 어긋난다.
- manual 표(`05-idempotency.md:54`): "재전송·재실행 모두 위험." 같은 행의 옛 문구가 남았다. 그런데 manual은 "짝 프론트 분류기도 이 표를 따른다"고 적는다(`:69`).
- runbook(`idempotency-unavailable.md:97`): "효과가 없으면 클라이언트는 새 키로 다시 보낸다." http-contract의 "새 키로 보내지 않는다"와 정면으로 다르다.
- 왜 중요한가: 결정 ①로 충돌한 실행(crash)의 기록은 `EXECUTING`으로 lease + `replay-ttl`(기본 약 24h) 동안 남는다. runbook은 이 기록을 지우지 말라고 한다(`:99-102`). 그래서 효과가 없다고 확인된 뒤 남는 길은 새 키뿐이다. 그런데 http-contract만 읽은 클라이언트는 새 키를 막는다. 그 사용자는 기록이 사라질 때까지 진행하지 못한다. 중복 실행이나 데이터 손상은 생기지 않는다. 드문 경우의 진행 막힘이라 낮은 쪽(Minor)으로 분류했다.
- 고치는 법: 표 행을 "자동 재시도하지 않는다. 같은 키 재전송은 안전하다(재생·500·효과 없던 실패면 실행). 업무 데이터로 효과가 없다고 확인되면 운영 절차에 따라 새 키로 다시 보낸다"처럼 runbook과 맞춘다. manual 표 행을 같은 문구로 바꾼다.
- 가이드 심각도 Low · P2 · 증거 E1(문서 대조)
#### RR5-01-02 · `renew`·`inspect` 결과 값의 뜻이 하나씩 늘었다
- 위치: `IdempotencyScripts.java:217-220`, `PostgreSqlIdempotencyStore.java:236-239`, `IdempotencyInspectionOutcome.java:11-17`
- 무엇이 틀렸나:
- lease가 끝난 주인의 `renew`가 `NOT_OWNER`를 받는다. 그 주인은 여전히 주인이다. 같은 handle로 `complete`하면 `COMPLETED`가 난다. `NOT_OWNER`는 다른 곳에서 "기록이 다른 주인에게 넘어갔다"는 뜻이다(PG 주석 `PostgreSqlIdempotencyStore.java:445-447`이 "값 하나에 뜻 하나"를 지킨다고 적는다).
- `inspect`의 `ABANDONED`가 "끝난 포기"와 "남의 실행이 lease를 넘김(아직 `COMPLETED`로 바뀔 수 있음)" 둘을 뜻한다. javadoc에는 적혀 있다.
- 왜 중요한가: 지금 `renew`·`inspect`를 부르는 곳은 executor뿐이고 executor는 `renew`를 부르지 않는다. 그래서 지금 틀린 동작은 없다. 나중에 lease를 늘리는 executor가 `NOT_OWNER`를 "넘겨받혔다"로 읽고 작업을 멈추거나 `complete`를 건너뛰면, 결정 ①이 지키려던 늦은 결과가 사라진다. 숨은 위험이다.
- 고치는 법: `IdempotencyRenewOutcome`에 `LEASE_EXPIRED`(owner 없음)를 더하고 두 저장소와 계약이 그 값을 쓰게 한다. 아니면 `IdempotencyStorePort.renew` javadoc에 "lease가 끝났으면 `NOT_OWNER`지만 `complete`·`markFailed`는 여전히 받는다"를 적는다. `ABANDONED`는 javadoc을 그대로 두거나 `RECOVERY_REQUIRED_EXPIRED_EXECUTION` 같은 값을 나눈다.
- 가이드 심각도 Low · P3 · 증거 E2(코드 읽기, 계약 `:600-617`이 `isNotEqualTo(RENEWED)`만 본다)
#### RR5-01-03 · 포트 javadoc의 "주인의 마지막 보고를 기록이 갖는다"가 동작과 다르다
- 위치: `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyStorePort.java:15-16`
- 무엇이 틀렸나: "the holder's last report is the one the record keeps"라고 적었다. 실제로 기록은 첫 종료 보고를 갖는다. `COMPLETED` 뒤의 `markFailed`는 PG `NOT_IN_PROGRESS`(`PostgreSqlIdempotencyStore.java:501-503`), Redis `NOT_OWNER`나 `NOT_IN_PROGRESS`로 거절된다.
- 왜 중요한가: 포트 구현자가 이 문장대로 "마지막 보고로 덮어쓰기"를 만들면 완료된 결과가 실패로 바뀐다. 계약에 그 케이스가 없어 막지 못한다.
- 고치는 법: "the holder's final report — its completion or its failure, whichever comes first — is recorded"로 고친다.
- 가이드 심각도 Low · P3 · 증거 E1
#### RR5-01-04 · 늦은 실패 경로를 계약이 끝까지 보지 않는다
- 위치: `IdempotencyStoreContract.java:556-578`, `RedisIdempotencyStoreAdapterTest.java:356-425`
- 무엇이 틀렸나:
- 늦은 재시도 가능 실패 케이스는 `MARKED_RETRYABLE`만 확인한다. 문서가 약속한 "다음 같은 키 요청이 다시 실행한다"(`http-contract.md:127`)는 시간 케이스로 확인하지 않는다.
- 늦은 `EFFECT_UNKNOWN_ABANDONED` 보고 케이스가 없다.
- command fake 쪽은 늦은 `complete`·`inspect`·`renew`만 본다. 늦은 `markFailed`는 fake 복사본으로 한 번도 지나가지 않는다.
- fake와 command fake 위 계약은 시간 케이스 12개를 모두 skip한다(실행 결과). 시간 케이스는 실 PG·실 Redis lane에서만 돈다.
- 왜 중요한가: 지금 코드는 맞다(PG `FAIL_SQL`이 lease를 now로 당기고 `FAILED_RETRYABLE`은 `resetClaim`으로 간다. Redis CLAIM은 `FAILED_RETRYABLE`을 넘겨받는다). 다만 이 경로가 바뀌어도 잡을 테스트가 없다.
- 고치는 법: `:556` 케이스 끝에 다음 claim이 `TakenOverClaimed`인지 확인을 더한다. 늦은 `EFFECT_UNKNOWN_ABANDONED` → 다음 claim `RecoveryRequired` 케이스를 더한다. adapter 테스트에 늦은 `markFailed` 한 건을 더한다.
- 가이드 심각도 Low · P3 · 증거 E3(테스트 실행 결과의 skip 목록)
#### RR5-01-05 · (이전부터) PostgreSQL에서는 결정 ①이 말하는 상황이 기본 사용 모양에서 생기지 않는다
- 위치: `IdempotencyClaimGateway.java:59`, `PublishPosterImageUseCase.java:108-117`, `persistence-jpa.yml:181`, `docs/web/http-contract.md:123-129`
- 무엇이 틀렸나: PG 저장소는 호출자의 쓰기 트랜잭션 안에서만 돈다. 샘플처럼 `transactions.inWrite(() -> executor.execute(...))`로 부르면 claim·실행·complete가 한 트랜잭션이다. 두 번째 요청의 `insert … on conflict do nothing`은 첫 요청의 커밋 전 행을 기다린다. 그래서 두 번째 요청은 "lease 지난 `EXECUTING`"을 보지 못하고 잠금에서 기다린다. 또 쓰기 트랜잭션 제한(30s, B-21)이 기본 lease(30s)와 같아서 30s를 넘는 요청은 취소되고 claim 행까지 롤백된다. 새 문단 "첫 시도가 lease보다 오래 걸려도 그 결과는 기록된다 … 두 저장소 모두 500으로 답한다"는 PG 기본 사용에서 맞지 않는다.
- 왜 중요한가: 이 커밋이 만든 동작 문제는 아니다. 옛 문서도 PG에 대해 같은 정도로 틀렸다. 다만 이 커밋이 새로 쓴 약속 문장이 PG 운영자에게 "30s 넘는 요청도 결과가 남는다"고 읽힌다. 실제로는 요청이 실패하고 기록이 사라져, 같은 키 재전송이 트랜잭션 밖 효과를 다시 일으킬 수 있다.
- 고치는 법: http-contract §2 문단에 "PostgreSQL 저장소를 한 쓰기 트랜잭션 안에서 쓰면 같은 키 요청은 첫 요청이 끝날 때까지 기다리고, 쓰기 트랜잭션 제한(기본 30s)을 넘는 요청은 기록과 함께 롤백된다"를 더한다.
- 가이드 심각도 Low · P3 · 증거 E2(SQL·호출 모양·설정값 읽기, 실행 재현은 안 했다)
#### RR5-02-01 · 셸이 그 자리에서 실행하지 않는 `cd` 줄도 따라간다
- 위치: `WorkflowGradleInvocations.java:31-45`(클래스 주석 "certain to have run"), `:212-308`, `:732-765`
- 무엇이 틀렸나: 판독기는 줄 단위로 목록을 나눈다. 셸 문법의 일부를 모른다. 아래 모양에서 셸은 저장소 루트에 있는데 판독기는 `src`라고 읽고 `:ci`를 실행으로 센다. 실험 결과 모두 `countsSrcCi=true, reason=null`이었다.
- heredoc 본문의 `cd src` 줄 (`cat > x.sh <<'EOF'` / `cd src` / `EOF` / `./gradlew ci`)
- 정의만 하고 부르지 않은 함수 본문 (`enter() {` / ` cd src` / `}`). 여는 `{`가 첫 단어가 아니라 깊이를 세지 않는다(`:231-252`)
- 여러 줄 따옴표 문자열 안의 `cd src` 줄
- 이스케이프한 `\;` 뒤의 `cd src && ./gradlew ci`
- 왜 중요한가: 이 저장소에는 루트에 `gradlew`가 없다. 그래서 위 모양의 `./gradlew ci`는 실제로 실패하고 workflow가 빨갛게 된다. 조용한 거짓 통과는 아니다. 조용한 거짓 통과가 되려면 다른 빌드 디렉터리(예: `src/optional-platforms`)에서 `../gradlew ci`가 성공하는 억지 모양이 필요하다. 그래서 Minor다. 다만 클래스 주석의 "확실히 실행된 cd만 따라간다"는 사실보다 강하다.
- 고치는 법: `<<`가 있는 줄 뒤, `name() {`·`function` 정의, 짝이 안 맞는 따옴표가 있는 줄 뒤의 `cd`는 "읽지 않음"으로 둔다. 아니면 주석을 "줄 단위로 읽으며 heredoc·함수 본문·여러 줄 문자열은 구분하지 않는다"로 낮춘다.
- 가이드 심각도 Low · P3 · 증거 E3(scratchpad 판독 실험)
#### RR5-02-02 · (이전부터) 실패를 막지 못하는 모양 둘이 README 15절 "남음" 목록에 없다
- 위치: `WorkflowGradleInvocations.java:58`(구분자에 `&` 없음), `:803-830`
- 무엇이 틀렸나: 실험 결과 둘 다 `countsSrcCi=true`였다.
- `cd src; ./gradlew ci &`: 백그라운드 실행이라 step이 결과를 기다리지 않는다. `&`는 task 이름으로 읽힌다(`tasks=[ci, &]`).
- `false && cd src && ./gradlew ci` 다음 줄 `echo done`: 앞 명령이 실패하면 gradlew는 돌지 않는다. `bash -e`는 `&&` 목록 중간 실패로 끝나지 않는다. 그래서 step이 통과한다. `working-directory: src`와 `A && ./gradlew ci`에도 이전부터 있던 모양이다.
- 왜 중요한가: 둘 다 조용한 거짓 통과다. README 15절은 `|| true`·`| tee`·`if`만 적어서 남은 범위가 실제보다 좁게 읽힌다.
- 고치는 법: README 15절 "남음"에 두 모양을 더한다. 고칠 때는 `&`를 구분자로 읽고 그 앞 명령을 세지 않는다. `&&` 목록 중 마지막이 아닌 gradlew와 마지막이 아닌 목록의 gradlew는 세지 않는다.
- 가이드 심각도 Low · P2 · 증거 E3
#### RR5-02-03 · 실패 메시지가 다른 디렉터리로 읽힌 명령은 보여 주지 않는다
- 위치: `StrictLaneStagesPlugin.java:194-213`
- 무엇이 틀렸나: `notCounted`는 `uncountedReason`이 있는 명령만 싣는다. `cd scr && ./gradlew ci`(오타)처럼 따라간 `cd`가 다른 빌드로 이끈 명령은 이유가 `null`이라 빠진다. 메시지는 "a command started in another directory"라고만 한다.
- 왜 중요한가: 결정 ②의 목적이 "파생 서비스가 왜 실패하는지 알게"였다. 가장 흔한 실수(경로 오타, `working-directory`와 `cd`를 둘 다 써서 `src/src`)가 이름 없이 남는다.
- 고치는 법: 단계를 요청했지만 `buildDirectory()`가 다른 명령도 "다른 빌드 `<dir>`에서 시작한다"로 함께 싣는다.
- 가이드 심각도 Low · P3 · 증거 E2
#### RR5-03-01 · `APP_IDEMPOTENCY_TTL` 쪽 안내가 새 상한을 말하지 않는다
- 위치: `docs/registries/env-keys.yaml:1602-1616`, `src/composition/idempotency/src/main/resources/config/module-defaults/idempotency.yml:14-17`, `src/composition/idempotency/README.md:48`(조정 표의 `APP_IDEMPOTENCY_TTL` 칸)
- 무엇이 틀렸나: 결정 ③으로 `replay-ttl`은 이제 `failure-retention`(기본 24h)보다 길 수 없다. 그런데 `APP_IDEMPOTENCY_TTL` 행의 주석과 `validation`(`..._le_72h_ge_processing_lease`)은 72h 상한과 lease 하한만 말한다. module-defaults 주석도 lease 검사만 적는다. 새 검사는 `FAILURE_RETENTION` 행에만 있다.
- 왜 중요한가: `APP_IDEMPOTENCY_TTL`만 48h·72h로 올리는 운영자는 TTL 행만 보고 기동 실패를 만난다. 메시지가 두 키와 값을 보여 주고 B-24가 적고 있어 바로 고칠 수 있다. 그래서 Minor다.
- 고치는 법: TTL 행 주석에 "and not longer than APP_IDEMPOTENCY_FAILURE_RETENTION"을 더하고 `validation`을 `..._le_failure_retention`으로 맞춘다. module-defaults 주석과 composition README 조정 표에도 한 줄씩 더한다.
- 가이드 심각도 Low · P3 · 증거 E1
## Declined to judge
- 프론트 짝 문서 갱신 여부: 다른 repo라 보지 않았다.
- 배포 중 옛 버전과 새 버전이 한 저장소를 함께 쓰는 동안: 옛 인스턴스의 claim은 여전히 기록을 `ABANDONED`로 바꿔 새 인스턴스의 늦은 완료를 거절한다. 중복 실행은 없고 옛 동작 그대로라 판단하지 않았다.
- 같은 claim attempt를 다시 쓰는 호출: `ReplayedAcquire` 뒤 Redis는 `ALREADY_STARTED`로 작업을 다시 돌리고 PG는 digest의 revision 차이로 `OPERATION_CONFLICT`를 낸다. 이전부터의 차이이고, 지금 호출자는 모두 요청마다 새 attempt를 만든다(`PublishPosterImageUseCase.java:106`). 범위 밖이다.
- 비동기 웹 요청 timeout(B-32)이 lease보다 짧으면 "첫 요청은 자기 응답을 정상으로 받는다"가 맞지 않는다: 웹 계층 설정 문제라 범위 밖이다.
- PG `jpaPlatformContractTest` lane에 `rejectSkipped`가 없다: PG 계약은 `elapse`를 구현해 시간 케이스가 skip되지 않는다. 이전부터의 lane 설정이다.
- 결정 ②의 구현 방식(손으로 짠 판독기 vs 셸 파서 사용, 또는 `working-directory`만 허용) 사이의 선택 기록: 결정 자체는 소유자가 내렸고, 구현 방식 선택 이유가 클래스 주석에 일부만 있다. 결정을 뒤집는 문제가 아니라 판단하지 않았다.
## 수렴 판단
세 영역 모두 이 라운드가 만든 새 Important 이상 결함은 없다. 결정 ①②③은 코드·계약 테스트·운영 문서에 결정대로 들어갔다. 회귀로 판정한 발견도 없다.
이 커밋이 만든 것은 Minor 7건(RR5-01-01~04, RR5-02-01·03, RR5-03-01)이다. 이전부터 있던 것이 2건(RR5-01-05, RR5-02-02)이다. 다음 수정 라운드는 필요하지 않다. Minor는 기록만 한다.
건수: Critical 0 · Important 0 · Minor 9(이 커밋 7: RR5-01-01·02·03·04, RR5-02-01·03, RR5-03-01 / 이전부터 2: RR5-01-05, RR5-02-02).
## Assessment
**Ready to merge? Yes**
결정 ①②③이 두 저장소·공유 계약·문서에 같은 판정으로 들어갔고, 새 넘겨받기 경로나 새 조용한 거짓 통과는 찾지 못했다. 남은 것은 문서 사이의 안내 차이와 테스트·판독기의 작은 틈이다.
+6 -6
View File
@@ -1,10 +1,10 @@
# 업그레이드 안내 — 2026-11 성숙도 리뷰 수정
- 범위: `01a8a2a70..refactor/maturity-review-2026-11` (main → 이 브랜치, 커밋 11개와 이 줄을 고친 문서 커밋)
- 범위: `01a8a2a70..refactor/maturity-review-2026-11` (main → 이 브랜치)
- 커밋: `34565130` High·P1 19건 · `1400dc15` 남은 발견·매뉴얼·생성 명령 · `5786126c` 남은 항목과 합친 뒤 결함 ·
`7ef8d0b4` 재리뷰 기록 · `bbe944bd` 재리뷰 결함 · `ecc74b7d` 2차 재리뷰 기록·이 안내 · `1885bf8d` 2차 재리뷰 결함 ·
`339cf8fd` 3차 확인 리뷰 기록 · `f40c03c6` 3차 확인 리뷰 Minor · `c2e55510` 마지막 확인 리뷰 기록 ·
`2678955c` 테스트 코드 정적 분석(B-40) — `docs(review)` 기록 커밋은 문서만 바꾼다
`2678955c` 테스트 코드 정적 분석(B-40) · `70fb80bf` 소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록, `failure-retention` 기동 검사, workflow `cd`) — `docs(...)` 커밋은 문서만 바꾼다
- 근거 문서: `docs/reviews/2026-11-01-maturity-review/README.md` 13~16절, `docs/reviews/2026-11-03-rereview/README.md`
4·6·8~13절, 각 커밋의 `BREAKING CHANGE:` 꼬리말
- 아래 표의 각 줄은 위 범위의 diff와 코드로 확인했다. 확인하지 못한 것은 그 자리에 "확인 못 함"으로 적었고 9절에
@@ -79,7 +79,7 @@
| B-21 | 트랜잭션 제한: `TransactionPort` 쓰기·읽기 트랜잭션 30초(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`, env 키 아님) | 30초를 넘는 트랜잭션은 문장이 취소되고 `DB_QUERY_CANCELED`로 실패 | 긴 일괄 작업은 쪼갠다. 꼭 필요하면 프로필 yml에서 값을 올린다 | `1400dc15` · `persistence-jpa.yml` |
| B-22 | 격리 수준을 Hikari에서 고정: `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`. 다른 값이면 거부. `TransactionPort`는 트랜잭션마다 격리 수준을 정하지 않는다 | 다른 격리 수준을 설정했다면 기동 실패(`HikariPoolConstraintValidator`) | 값을 지운다. 더 높은 격리가 필요한 곳은 따로 설계한다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/.../startup/HikariPoolConstraintValidator.java` |
| B-23 | H2 드라이버가 운영 jar에서 빠짐(persistence-jpa `runtimeOnly` → `testRuntimeOnly`). `bootRunH2` 작업만 따로 넣는다 | `APP_PERSISTENCE_VENDOR=h2`로 `bootRunH2` 밖에서 띄우면 드라이버가 없다(정확한 오류 확인 못 함) | 로컬은 Compose PostgreSQL 또는 `bootRunH2`를 쓴다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/build.gradle` |
| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다. `APP_IDEMPOTENCY_TTL`(replay TTL)은 그 lease보다 짧으면 안 된다(재리뷰 RR-03-11). `APP_IDEMPOTENCY_FAILURE_RETENTION`은 replay TTL보다 짧으면 안 된다(RR3-03-02) | 2초 이하면, replay TTL < lease면, 또는 failure retention < replay TTL이면 기동 실패(exit 78). 마지막은 메시지에 `failure-retention`·`replay-ttl` 두 키와 값이 나온다 | lease를 2초보다 길게(기본 30s), replay TTL을 lease 이상으로(기본 24h), failure retention을 replay TTL 이상으로(기본 24h — 기본값끼리는 그대로 뜬다) | `5786126c`, `bbe944bd`, 3차 수정, 2026-11-04 소유자 결정 · `src/composition/idempotency/.../IdempotencySettings.java` |
| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다. `APP_IDEMPOTENCY_TTL`(replay TTL)은 그 lease보다 짧으면 안 된다(재리뷰 RR-03-11). `APP_IDEMPOTENCY_FAILURE_RETENTION`은 replay TTL보다 짧으면 안 된다(RR3-03-02) | 2초 이하면, replay TTL < lease면, 또는 failure retention < replay TTL이면 기동 실패(exit 78). 마지막은 메시지에 `failure-retention`·`replay-ttl` 두 키와 값이 나온다 | lease를 2초보다 길게(기본 30s), replay TTL을 lease 이상으로(기본 24h), failure retention을 replay TTL 이상으로(기본 24h — 기본값끼리는 그대로 뜬다) | `5786126c`, `bbe944bd`, 3차 수정, `70fb80bf`(2026-11-04 소유자 결정) · `src/composition/idempotency/.../IdempotencySettings.java` |
| B-25 | 알림 콜백 본문 상한 65508 → 65251(바인딩에서 상한 검사) | `.env`에 옛 예제 값 `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES=65508`이 있으면 기동 실패 `max-body-bytes must be 1..65251` | 값을 지우거나 65251 이하로 | `5786126c` · `src/adapter/outbound/notification/.../autoconfigure/NotificationPlatformSettings.java` |
| B-26 | `config/module-defaults/`에 같은 이름 파일이 둘이거나, 두 파일이 같은 키를 실으면 기동 실패 | 기동 실패 `two capability modules ship config/module-defaults/<file>` 또는 `... both ship <key>`(exit 78) | 자기 leaf의 module-defaults 파일 이름·키가 템플릿 모듈과 겹치지 않게 한다 | `1400dc15` · `src/adapter/outbound/support/.../startup/ModuleDefaultsEnvironmentPostProcessor.java` |
| B-27 | (sample-portfolio를 남겨 둔 경우) 데모 계정은 활성 프로필이 모두 `local`·`test`·`demo` 중 하나일 때만. 프로필이 없어도 거부 | 기동 실패 `the sample's demo accounts authenticate only under the local, test or demo profile` | `SPRING_PROFILES_ACTIVE=demo`(이미지·jar), `local`(bootRun)로 띄우거나 sample 보안 설정을 지운다. 세 프로필 모두 sample `application.yml`이 object storage를 끈다(RR2-04-02) | `5786126c`, `bbe944bd` · `src/sample-portfolio/.../security/SampleDemoAccountsProductionGuard.java` |
@@ -92,7 +92,7 @@
|---|---|---|---|---|
| B-28 | 처리 중 409 `IDEMPOTENT_IN_FLIGHT`: `retryable` false→true, `Retry-After: 2` 추가. gRPC trailer `error-retryable`과 GraphQL extension `retryable`도 true | 409를 "재시도 금지"로 처리하던 클라이언트가 틀린다 | **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송하게 한다. 새 키 금지 | `34565130` · `src/shared-contract/.../error/OperationalError.java`, `docs/registries/error-codes.yaml` |
| B-29 | Envelope의 `null` 필드를 키째 생략: 성공은 `error` 키 없음, 실패는 `data` 키 없음, `meta.page`·`meta.correlationId`·`error.details`도 값이 없으면 키 없음. 빈 목록은 그대로 | `"error": null`·`"data": null`을 기대하던 클라이언트·계약 테스트가 깨진다 | `success`로 가르고 키 존재로 판단하지 않는다 | `34565130` · `src/adapter/inbound/web/.../envelope/EnvelopeWireFormatConfig.java` |
| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송. 실행 중 lease가 지난 기록은 두 저장소 모두 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다 — Redis 저장소는 전에 넘겨받아 작업을 다시 돌렸다(재리뷰 RR-01-11). 그 기록은 바꾸지 않아, 첫 시도가 늦게 끝나면 결과가 기록되고 그 뒤 재전송은 재생을 받는다(5절) | `bbe944bd`, 3차 수정, 2026-11-04 소유자 결정 · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` |
| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송. 실행 중 lease가 지난 기록은 두 저장소 모두 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다 — Redis 저장소는 전에 넘겨받아 작업을 다시 돌렸다(재리뷰 RR-01-11). 그 기록은 바꾸지 않아, 첫 시도가 늦게 끝나면 결과가 기록되고 그 뒤 재전송은 재생을 받는다(5절) | `bbe944bd`, 3차 수정, `70fb80bf`(2026-11-04 소유자 결정) · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` |
| B-31 | 핸들러 밖 오류(`/error` 디스패치)를 `EnvelopeErrorController`가 실패 Envelope로 답한다. 전에는 Boot `/error` 맵이 `success:true`로 감싸져 요청 경로까지 실려 나갔다. 기본 JWT 체인에서 익명 400이 401로 바뀌지 않는다. 4xx·5xx 본문은 `success:true`로 감싸지 않는다. 보안 체인이 `DispatcherType.ERROR`를 허용한다 | 오류 본문 모양이 바뀐다. 자기 SecurityFilterChain이 ERROR 디스패치를 막으면 400이 401로 나간다 | 자기 체인에 `auth.dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 넣는다(템플릿 `SecurityConfig`와 같게) | `bbe944bd` · `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`, `.../auth/SecurityConfig.java` |
| B-32 | 새·바뀐 오류 코드: 비동기 요청 timeout 500 `INTERNAL_ERROR` → 503 `REQUEST_TIMEOUT`(retryable). `IDEMPOTENCY_KEY_INVALID` 400(`details.reason`=`MISSING`·`MALFORMED`, `IdempotencyKeyHeader.parse`를 쓰는 엔드포인트, sample은 `BAD_PARAMETER`에서 바뀜). web-advanced 예외 10종이 모두 500 `INTERNAL_ERROR`였다가 각자 코드(`ADMISSION_REFUSED` 503 등) | 코드로 분기하던 클라이언트가 새 코드를 모른다 | 클라이언트 분기표에 더한다. web-advanced 표는 `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | `1400dc15` · `src/adapter/inbound/web/.../error/WebTransportError.java`, `HttpStatusErrorCodes.java`, `src/adapter/inbound/web-advanced/.../error/WebAdvancedError.java` |
| B-33 | DB 실패 분류: 낙관적 잠금 충돌 500 → 409 `DB_OPTIMISTIC_CONFLICT`. 커밋 단계 연결 끊김(08xxx, 40003 등)을 재시도 가능으로 답하던 것 → 500 `DB_COMPLETION_UNKNOWN`(retryable=false) | 응답 status·code가 바뀐다 | 409는 다시 읽고 재시도, `DB_COMPLETION_UNKNOWN`은 업무 데이터로 결과를 확인 | `34565130`, `1400dc15` · `src/adapter/outbound/persistence-jpa/.../failure/PersistenceExceptionTranslator.java` |
@@ -103,7 +103,7 @@
|---|---|---|---|---|
| B-34 | 템플릿 패키지 규칙(ArchUnit): `FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`, `TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`. 템플릿 이름: application `usecase command query capability transaction security tenant observability secret messaging outbox idempotency operation lease lock cache realtime notification fileserver objectstorage`, domain `identifier stereotype` | 기능 패키지 이름이 이 목록과 겹치거나(예: `domain.lock`), 업무 코드를 템플릿 패키지(예: `application.usecase.*`)에 두고 기능 패키지를 import하면 `:app-bootstrap:architectureTest` 실패 | 기능 패키지 이름을 바꾸고, 업무 코드를 `dev.caskeleton.application.<feature>`로 옮긴다. 규칙 정본은 `src/application-core/CLAUDE.md` "Package ownership" | `5786126c` · `src/app-bootstrap/src/architectureTest/.../TemplatePackageOwnership.java` |
| B-35 | JPA 규칙: 양방향 연관은 한쪽에서만 매핑(`mappedBy`), notification·fileserver 저장소 엔티티는 그 leaf 안에서만, `@Version` 엔티티의 bulk update는 version을 올려야 함 | 위반 엔티티·쿼리가 있으면 architectureTest 실패 | 매핑·쿼리를 고친다 | `34565130`, `1400dc15`, `bbe944bd` · `src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java` |
| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)에서 시작해 같은 `run:` 셸이 그 앞에서 실행한 `cd <상대 경로>`(`cd src && ./gradlew …`, `cd src; ./gradlew …`, 앞 줄의 `cd src`)를 따라간 뒤 `-p`를 붙인 디렉터리로 정하고(2026-11-04 소유자 결정), `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x<task>`·`-p<dir>`도 Gradle처럼 읽는다(RR3-04-02). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/<VAR>`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src`도 `cd src`도 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다. 확실히 따라갈 수 없는 디렉터리 이동(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`, `if`/`for`/`case`·`{ }`·서브셸 안의 `cd`, `||`·`|`로 이은 `cd`, 다른 명령과 `&&`로 묶인 `cd` 다음 줄) 뒤의 명령도 세지 않고, 실패 메시지에 그 명령과 이유를 적는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 두거나 같은 셸에서 `cd <상대 경로>`로 옮긴 뒤 부른다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c`, 2026-11-04 소유자 결정 · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../strictlane/WorkflowGradleInvocations.java`, `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` |
| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)에서 시작해 같은 `run:` 셸이 그 앞에서 실행한 `cd <상대 경로>`(`cd src && ./gradlew …`, `cd src; ./gradlew …`, 앞 줄의 `cd src`)를 따라간 뒤 `-p`를 붙인 디렉터리로 정하고(`70fb80bf`(2026-11-04 소유자 결정)), `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x<task>`·`-p<dir>`도 Gradle처럼 읽는다(RR3-04-02). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/<VAR>`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src`도 `cd src`도 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다. 확실히 따라갈 수 없는 디렉터리 이동(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`, `if`/`for`/`case`·`{ }`·서브셸 안의 `cd`, `||`·`|`로 이은 `cd`, 다른 명령과 `&&`로 묶인 `cd` 다음 줄) 뒤의 명령도 세지 않고, 실패 메시지에 그 명령과 이유를 적는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 두거나 같은 셸에서 `cd <상대 경로>`로 옮긴 뒤 부른다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c`, `70fb80bf`(2026-11-04 소유자 결정) · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../strictlane/WorkflowGradleInvocations.java`, `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` |
| B-37 | app-bootstrap 테스트 lane 분리: 저장소 파일을 읽는 테스트는 태그 `document-contract`(main 단계) 또는 `repository-contract`(`check`)여야 하고, 일반 `test` lane에는 `ca.repository.root`가 없다 | app-bootstrap에 둔 자기 테스트가 저장소 파일을 읽으면 `test`에서 실패 | 태그를 단다 | `1400dc15` · `src/app-bootstrap/build.gradle` |
| B-40 | 테스트 코드 정적 분석 `testQualityCheck`: SpotBugs·FindSecBugs를 main 밖 모든 source set(test, testFixtures, integrationTest, systemTest 등)에 돌린다. 테스트용 제외 목록은 `config/spotbugs/exclude-test.xml`(보안 범주·내부 상태 노출·생성자 예외·반환값 null 역참조·아키텍처 위반 fixture). 분석 classpath가 그 source set의 runtime classpath로 넓어졌고, 분석이 불완전하면(빠진 클래스) 실패한다. main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci` | 자기 테스트 코드의 SpotBugs 발견(예: `CountDownLatch.await` 반환값 무시, 공유 변수 비원자 쓰기, 닫지 않은 `Statement`)이 main 단계를 막는다. 테스트 classpath에 없는 타입을 참조하면 `SpotBugs analysis incomplete` | 고치거나, 클래스·메서드로 좁힌 Match를 이유와 함께 `exclude-test.xml`에 더한다. 빠진 타입은 그 테스트 suite 의존성에 넣는다 | `2678955c` · `src/build-logic/.../quality/QualityConventionsPlugin.java`, `src/config/spotbugs/exclude-test.xml`, `src/build.gradle` |
@@ -223,7 +223,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur
| deprecated | `APP_CACHE_REDIS_TTL_JITTER`는 아무것도 바인딩하지 않음(`removal_deadline: 2027-02-28`) | 값이 아무 효과 없다 | `1400dc15` · `env-keys.yaml` |
| HTTP client(JDK transport) | 스트리밍 응답의 read-idle 감시가 전용 데몬 스레드 하나(`httpclient-jdk-read-idle`)에서 돈다. 스트림마다 감시 작업 하나, 스트림을 닫으면 작업을 바로 취소 | 스레드 덤프에 그 스레드가 하나 보인다. 공용 `ForkJoinPool`이 바빠도 timeout이 설정값에 난다(전에는 늦게 났다). Apache transport(기본)는 영향 없음 | 3차 확인 리뷰 RR3-03-01 · `src/adapter/outbound/httpclient/.../jdk/ReadIdleInputStream.java` |
| 멱등성 | `IDEMPOTENCY_RECOVERY_REQUIRED`를 내는 예외 메시지 끝에 scope digest가 붙는다. Redis 기록 조회(INSPECT 스크립트)가 `leaseUntil`을 돌려줘 `processingLeaseUntil`이 실제 lease 끝이다(전에는 key TTL 끝, 즉 lease + replay TTL) | 예외 메시지 전체에 맞추던 로그 매처는 고친다. 회복 절차는 `docs/runbooks/idempotency-unavailable.md`(digest로 기록을 찾는다) | 3차 확인 리뷰 RR3-03-03·05 · `src/application-core/.../idempotency/IdempotencyRecoveryRequiredException.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` |
| 멱등성(lease가 지난 실행) | lease가 지난 `EXECUTING` 기록을 claim이 만나면 기록을 바꾸지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 그 실행의 주인이 늦게 부른 `complete`·`markFailed`는 기록된다. 전에는 두 저장소 모두 기록을 `ABANDONED`로 바꿔(PostgreSQL은 `last_transition_kind` `EXPIRED_EXECUTION`) 늦은 결과를 거절했고 첫 요청도 500이었다. 이미 끝난 lease의 `renew`는 두 저장소 모두 거절한다(Redis는 전에 받아들였다). 남의 lease 지난 실행을 `inspect`하면 `ABANDONED`(전에는 `IN_PROGRESS_OTHER`) | 30s를 넘는 정상 요청이 이제 결과를 남기고 정상 응답을 받는다. 같은 키 재전송은 500을 받은 뒤 재생을 받을 수 있다. 직접 구현한 store는 `IdempotencyStoreContract`의 바뀐 시간 케이스로 확인한다. 운영자는 `EXECUTING` 기록을 지우지 않는다 — 살아 있는 실행의 늦은 결과가 기록을 못 찾아(`ABSENT`) 사라진다(`docs/runbooks/idempotency-unavailable.md`) | 2026-11-04 소유자 결정 · `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java` |
| 멱등성(lease가 지난 실행) | lease가 지난 `EXECUTING` 기록을 claim이 만나면 기록을 바꾸지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 그 실행의 주인이 늦게 부른 `complete`·`markFailed`는 기록된다. 전에는 두 저장소 모두 기록을 `ABANDONED`로 바꿔(PostgreSQL은 `last_transition_kind` `EXPIRED_EXECUTION`) 늦은 결과를 거절했고 첫 요청도 500이었다. 이미 끝난 lease의 `renew`는 두 저장소 모두 거절한다(Redis는 전에 받아들였다). 남의 lease 지난 실행을 `inspect`하면 `ABANDONED`(전에는 `IN_PROGRESS_OTHER`) | 30s를 넘는 정상 요청이 이제 결과를 남기고 정상 응답을 받는다. 같은 키 재전송은 500을 받은 뒤 재생을 받을 수 있다. 직접 구현한 store는 `IdempotencyStoreContract`의 바뀐 시간 케이스로 확인한다. 운영자는 `EXECUTING` 기록을 지우지 않는다 — 살아 있는 실행의 늦은 결과가 기록을 못 찾아(`ABSENT`) 사라진다(`docs/runbooks/idempotency-unavailable.md`) | `70fb80bf`(2026-11-04 소유자 결정) · `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java` |
| sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` |
## 6. 따라오는 순서
+1 -1
View File
@@ -110,7 +110,7 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
| --- | --- | --- | --- | --- | --- |
| 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다 |
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 |
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 결과는 업무 데이터로 확인한다. 같은 키로 나중에 다시 보내도 서버는 작업을 다시 돌리지 않는다 — 첫 시도가 늦게 끝났으면 그 결과를 재생하고, 아니면 다시 500이다. 새 키로 보내지 않는다 |
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 같은 키 재전송은 안전하다 — 서버는 효과가 있었을 수 있는 작업을 다시 돌리지 않고, 첫 시도가 늦게 끝났으면 그 결과를 재생하며, 효과 없이 끝났으면 실행하고, 아니면 다시 500이다. 결과는 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차(`docs/runbooks/idempotency-unavailable.md`)에 따라 새 키로 다시 보낸다 |
- **결과 불명이 무엇을 뜻하나.** 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서
불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은