Merge remote-tracking branch 'origin/claude/t4-manual-history-ids-51889f' into claude/integration-r7

This commit is contained in:
DongHyeonka
2026-11-06 22:56:39 +09:00
5 changed files with 30 additions and 13 deletions
+7 -7
View File
@@ -54,7 +54,7 @@ DB 커밋 중 연결 끊김 ─────────────────
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 자동 재시도 안 함. 같은 키 재전송은 안전(재생·실행·다시 500을 서버가 판정, 다시 돌리지 않음). 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키 |
| 500 `DB_COMPLETION_UNKNOWN`, `retryable=false` | DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 | 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정 |
같은 키 재전송이 무엇을 막는지는 저장소마다 다르다(재리뷰 2026-11-04 RR5-01-05, 라운드6 RR6-02-05, 정본
같은 키 재전송이 무엇을 막는지는 저장소마다 다르다(정본
`docs/web/http-contract.md` 2절). Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을 다시 돌리지
않는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
요청이 다시 실행한다. 그래서 트랜잭션 밖 효과는 따로 멱등하게 만든다. 첫 시도가 processing lease(기본 30s)보다
@@ -74,15 +74,15 @@ DB 커밋 중 연결 끊김 ─────────────────
claim의 lease가 작업 시작 전에 끝나면 두 저장소 모두 시작을 거절하고(`LEASE_EXPIRED`), executor는 작업을
돌리지 않은 채 503 `IDEMPOTENCY_UNAVAILABLE`로 답한다. 다음 같은 키 요청이 그 claim을 넘겨받아 실행한다.
`IdempotencyClaimAttempt`를 재시도 사이에 들고 있다가 같은 attempt로 다시 부르는 호출자도 넘겨받는다(라운드6
RR6-02-01. 전에는 같은 claim을 재생받아 시작을 다시 거절당해 기록이 사라질 때까지 503이었다). 같은 attempt를
두 호출이 동시에 쓰면 서버가 가려내지 못하므로, 재시도는 앞 호출이 돌아온 뒤에 한다.
`IdempotencyClaimAttempt`를 재시도 사이에 들고 있다가 같은 attempt로 다시 부르는 호출자도 넘겨받는다(2026-11-05
확인 리뷰가 찾아 고쳤다. 전에는 같은 claim을 재생받아 시작을 다시 거절당해 기록이 사라질 때까지 503이었다).
같은 attempt를 두 호출이 동시에 쓰면 서버가 가려내지 못하므로, 재시도는 앞 호출이 돌아온 뒤에 한다.
기록은 lease + `replay-ttl` 동안 남고, `replay-ttl`이 lease보다 짧으면 기동이 실패한다
(`IdempotencyStoreContract`, 재리뷰 2026-11-04 RR-01-11·RR-03-11). 작업이 실패로 끝나 executor가 포기나
(`IdempotencyStoreContract`). 작업이 실패로 끝나 executor가 포기나
재시도 가능으로 표시한 기록은 표시한 때부터 `failure-retention`(기본 24h) 동안 남는다(PostgreSQL을 트랜잭션
하나로 쓰면 위처럼 롤백과 함께 사라진다). `failure-retention`이 `replay-ttl`보다 짧으면 기동이 실패한다.
짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 다시 돌리기 때문이다(RR3-03-02,
2026-11-04 소유자 결정). 거꾸로 말하면 `replay-ttl`(`APP_IDEMPOTENCY_TTL`)은 lease 이상, `failure-retention`
짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 다시 돌리기 때문이다(2026-11-04
소유자 결정). 거꾸로 말하면 `replay-ttl`(`APP_IDEMPOTENCY_TTL`)은 lease 이상, `failure-retention`
이하로 둔다.
409를 `retryable=true`로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
+3 -3
View File
@@ -95,7 +95,7 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re
예약 작업은 controller와 같은 leaf에 놓이기 쉽다. 그때 "지금 실행" endpoint가 작업 bean을 주입받아 부르면
권한 검사 없는 쓰기를 사용자가 부르게 된다. 아래 `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`가 이것을
빌드에서 막는다. 사용자도 같은 일을 시켜야 하면 `@RequiresPermission`을 단 사용자용 유스케이스를 따로
만든다(아래 D4 문단).
만든다(아래 권한 선언 검사 문단).
| 규칙 | 무엇을 막나 | 어디 |
| --- | --- | --- |
@@ -112,8 +112,8 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re
들이면 그 패키지를 이 목록에 더한다. 설정 안의 요청 처리 코드를 알아보는 요청 처리기 타입
(`ARE_REQUEST_HANDLER_TYPES`)도 나열 목록이라, 새 전송 라이브러리의 handler 타입을 함께 더한다.
D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는
쓰기라면 권한을 선언하고 역할에 매핑한다. 같은 쓰기를 사용자도 시스템도 부르면 유스케이스를 둘로 나눈다
쓰기 유스케이스의 권한 선언 검사(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`) 실패를 끄려고 이 표시를
쓰지 않는다. 사용자가 부르는 쓰기라면 권한을 선언하고 역할에 매핑한다. 같은 쓰기를 사용자도 시스템도 부르면 유스케이스를 둘로 나눈다
(사용자용 `@RequiresPermission`, 시스템용 `@SystemInvoked`). 업무 규칙은 domain에 두고 둘이 같이 쓴다.
### 규칙이 못 보는 길
+1 -1
View File
@@ -35,7 +35,7 @@ fake와 실제 adapter가 **같은 계약**을 통과해야 fake 위의 유스
1. 이름은 lowerCamelCase 행동 문장. 이름이 말한 성질을 단언한다. 예: 이름에 "트랜잭션 전에"를 넣었으면
트랜잭션이 없었다는 것도 단언하거나, 이름에서 뺀다.
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만, **한국어**로
(소유자 결정 5). 예: `@DisplayName("이름이 NAME_MAX_LENGTH + 1자이면 거절한다")`.
(2026-09-25 소유자 결정). 예: `@DisplayName("이름이 NAME_MAX_LENGTH + 1자이면 거절한다")`.
3. 본문 3문장 이상이면 `// given` `// when` `// then`. `// when`은 하나. 예외는 `catchThrowable`로 분리.
4. then은 when의 결과 하나만. 예외는 타입과 reason/code를 함께.
5. 포트 대역은 hand-rolled fake 하나, **포트 소유 leaf의 testFixtures**에. Mockito는 프레임워크 경계와
+2 -2
View File
@@ -75,7 +75,7 @@ draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occu
아니라 약 1.7×10¹⁵일 수 있다. 소비자는 번호를 "마지막으로 본 값보다 큰가"로만 비교하고 연속성을
가정하지 않는다. 비교는 aggregate identity(tenant scope 포함) 단위다. tenant scope를 바꾸는 배포는 옛
버전 인스턴스를 모두 멈춘 뒤 새 버전을 띄운다 — 섞여 돌면 새 scope의 번호가 옛 버전이 방금 쓴 번호보다
작을 수 있다(runbook `outbox-dead-letter.md` §8, 재리뷰 2차 RR-02-10).
작을 수 있다(runbook `outbox-dead-letter.md` §8).
## relay와 실패
@@ -86,7 +86,7 @@ draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occu
DEAD가 되지 않는다(1라운드 06-01·06-03). 대신 끝이 없다: 진짜 인증 오류, Kafka adapter가 이름을 모르는
broker 거부도 영원히 재시도된다. 행의 `last_failure_code`와 로그의 `error.reason`이 원인 코드를 남기고,
`outbox.retry.long.size`가 오래 재시도 중인 행을 센다. 처분(보류·재개·skip)은 publish-failed runbook
§4.1이다(재리뷰 RR-05-03).
§4.1이다.
- 발행 응답을 못 받으면 결과 불명(`OutboxPublishAmbiguousException`) — 05장 규칙과 같다.
- 운영: `docs/runbooks/outbox-dead-letter.md`, `docs/runbooks/outbox-publish-failed.md`.
+17
View File
@@ -149,3 +149,20 @@
- `RR-07-05`(CSRF 제외 규칙의 이유)는 README 6절 r4-f 행이 내용으로 다룬다.
- 나머지 20건은 round6 Minor다(`RR6-01-02`~`06`·`08`·`09`, `RR6-02-02`·`04`·`05`, `RR6-03-02`~`05`, `RR6-04-01`~`06`). README 17절은 영역별 건수만 적었고, r10 묶음이 영역 단위로 고쳤다.
- 이 검사는 "색인에 이름이 있나"만 본다. 고쳤는지는 처리 표와 확인 리뷰가 본다. 앞으로의 리뷰 README는 모든 ID를 이름으로 적는다(`improve.md` 4.1절 7단계).
## 8. `docs/manual/`에서 걷어낸 이력 ID (2026-11-06)
`docs/manual/` 본문에서 리뷰 ID와 번호만 쓴 결정을 걷어냈다. 문장의 뜻은 그대로이고, 괄호 안 근거만 여기로 옮겼다. 줄 번호는 걷어내기 전 기준 커밋 `06f520e6`의 줄이다.
| 원래 위치 | 원래 괄호 | 지금 본문 | 근거 |
| --- | --- | --- | --- |
| `docs/manual/05-idempotency.md:57` | "재리뷰 2026-11-04 RR5-01-05, 라운드6 RR6-02-05, 정본 `docs/web/http-contract.md` 2절" | 정본 가리킴만 남겼다 | `1103/RR5-01-05`(PostgreSQL 기본 모양에서는 lease 상황이 생기지 않는다, `round5/review.md`), `1103/RR6-02-05`(매뉴얼 첫 문장이 PostgreSQL 항목과 어긋났다, `round6/02-idempotency-outbound.md`) |
| `docs/manual/05-idempotency.md:78` | "라운드6 RR6-02-01" | "2026-11-05 확인 리뷰가 찾아 고쳤다" | `1103/RR6-02-01`(`LEASE_EXPIRED`로 거절당한 attempt를 다시 보내도 503만 받았다, `round6/02-idempotency-outbound.md`). 수정 커밋 `6e992970`(2026-11-05), `1103` README 17절 r10-02 |
| `docs/manual/05-idempotency.md:81` | "재리뷰 2026-11-04 RR-01-11·RR-03-11" | `IdempotencyStoreContract` 가리킴만 남겼다 | `1103/RR-01-11`(lease가 지난 실행 기록을 Redis가 넘겨받아 다시 실행했다, `round2/01-core-app-inbound.md`), `1103/RR-03-11`(replay TTL이 lease보다 짧으면 key가 lease 도중 사라졌다, `round2/03-outbound.md`). 수정 커밋 `1885bf8d`(2026-11-04) |
| `docs/manual/05-idempotency.md:84` | "RR3-03-02, 2026-11-04 소유자 결정" | "2026-11-04 소유자 결정" | `1103/RR3-03-02`(서버가 기억하는 기간 문서가 `failure-retention`을 빠뜨렸다, `round3/03-outbound.md`) |
| `docs/manual/07-authorization.md:98`, `:115` | "D4 문단", "D4 실패" | "권한 선언 검사 문단", "쓰기 유스케이스의 권한 선언 검사 실패" | D4는 인증·인가 계약 설계(`feature-authentication-authorization-contract`)의 결정 번호로, 규칙 `MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`을 가리킨다. 그 설계 문서는 이 repo에 없다. `ApplicationBoundaryArchitectureTest`의 주석 "D1 / D4"와 `1101/01-core-and-feature-pattern.md` 「ArchUnit D4」가 같은 번호다 |
| `docs/manual/08-testing.md:38` | "소유자 결정 5" | "2026-09-25 소유자 결정" | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 5번(`@DisplayName`은 한국어) |
| `docs/manual/09-outbox-events.md:78` | "재리뷰 2차 RR-02-10" | runbook 가리킴만 남겼다 | `1103/RR-02-10`(tenant scope가 바뀌는 배포의 rolling 구간에서 새 번호가 옛 버전이 쓴 번호보다 작다, `round2/02-persistence-messaging.md`) |
| `docs/manual/09-outbox-events.md:89` | "재리뷰 RR-05-03" | runbook 가리킴만 남겼다 | `1103/RR-05-03`(끝나지 않는 재시도 행을 운영자가 구분·처분할 수단이 없었다, `05-messaging.md`) |
- `RR-01-11`·`RR-02-10`·`RR-03-11`은 2차 재리뷰(`round2/`) 문서의 발견이다. 그 문서들은 1차 번호에 이어 `RR-` 접두어를 그대로 썼다. 머리말 표기("`RR-`는 1차 재리뷰")의 예외다.