diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index daae252f..9bc5358d 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -323,6 +323,7 @@ projectRequest: (input) => Object.freeze({ - input 메서드 이름. 사용자가 하는 일로 짓는다(`listItems`, `createInvoice`). - 반환 타입. `Result`(`src/contracts/result.ts`)를 쓴다. +- 쓰기 메서드의 호출 문맥. 쓰기는 뮤테이션의 `intent`를 받아 gateway까지 넘긴다(`Readonly<{ signal?: AbortSignal; intent: MutationIntent }>`). `KEYED` 쓰기의 멱등 키가 intent에 있다. `--with-create`의 `CommandContext`가 이 모양이다. - 실패 telemetry의 `kind`. `.<동작>.failed` 꼴로 접두어를 붙인다. ② **기준** @@ -511,14 +512,14 @@ projectRequest: (input) => Object.freeze({ ① **정할 것** - 페이지 템플릿. [02 결정표 6절](02-decision-tables.md#6-페이지-템플릿) -- `KEYED` 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). +- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 키가 있는 요청(`KEYED`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. - 폼이면 서버 422 오류를 받을 필드(`useAppForm`의 `allowedServerFields`). ② **기준** - 화면 문구는 모두 catalog에서 가져온다(`message(key)`). - 링크는 6단계의 URL 함수로 만든다. -- 결과 불명 화면 예제: `src/features/reference-feature/presentation/reference-resource-form-page.tsx` +- 결과 불명 화면 예제: `create:feature --with-create`의 `presentation/-create-page.tsx`(짝 백엔드 Envelope), `src/features/reference-feature/presentation/reference-resource-form-page.tsx`(problem details) ③ **잡는 검사 / 못 잡는 것** diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 1fed09ad..2db25794 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -88,7 +88,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 |---|---|---|---| | 서버 보장 | 멱등 키(`Idempotency-Key` 헤더)로 같은 요청의 중복 적용을 막는다 | 같은 요청을 여러 번 적용해도 결과가 같다 (키 없이) | 중복을 막지 못한다 | | 자동 재시도 | 실제로 보내기 전까지만. 보낸 뒤 결과를 모르면 결과 불명(4절)으로 넘긴다. 예외: 짝 백엔드가 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거절)로 답하면 `retryBudget` 안에서 같은 키로 다시 보낸다 | 된다 | 하지 않는다 | -| descriptor | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 참조 기능은 `retryBudget: 0` | — | `retryBudget: 0` 필수 | +| descriptor | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 짝 백엔드는 `retryBudget: 1`(아래 표), 참조 기능은 `0` | — | `retryBudget: 0` 필수 | | 뮤테이션 정책 | `...commandMutationIdentity(_CONTRACT)`가 `requiresIdempotencyKey: true`를 준다 | 같은 함수가 `false`를 준다 | 같은 함수가 `false`를 준다 | - 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다. @@ -96,6 +96,36 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 **기준**: 원칙 3. 서버 계약에 적힌 보장으로 고른다. 모르면 `NEVER`로 두고 백엔드에 묻는다. +**짝 백엔드의 생성 기능에 붙일 때 (1103/16-07, 03-07)** + +짝 백엔드 `new-feature.sh`가 만드는 create는 `NOT_IDEMPOTENT`다(`Create__Feature__UseCase.java.tmpl`). `Idempotency-Key`를 읽지 않는다. 그래서 프론트 쪽 값은 백엔드 create를 그대로 두었는지로 정해진다. + +```text +백엔드 create + ├─ 생성한 그대로 (NOT_IDEMPOTENT, 키를 읽지 않음) + │ → 프론트 NEVER ← create:feature --with-create + └─ IdempotencyExecutor 뒤로 옮김 (KEYED, 백엔드 docs/manual/05-idempotency.md "KEYED로 만드는 순서") + → 프론트 KEYED ← create:feature --with-create --keyed +``` + +백엔드가 키를 읽지 않는데 프론트를 `KEYED`로 두면 안 된다. 결과 불명 화면의 "같은 요청으로 다시 보내기"가 새 항목을 하나 더 만든다. 같은 키가 중복을 막는다는 보장이 백엔드에 없다. + +두 경우의 값이다. 생성 명령이 이 값을 쓴다. 손으로 만들 때도 같은 값을 쓴다. + +| 값 | `NEVER` (백엔드 그대로) | `KEYED` (백엔드 KEYED) | 이유 | +|---|---|---|---| +| `retrySemantics` | `"NEVER"` | `"KEYED"` | 백엔드가 키를 읽는지 | +| `frontend.retryBudget` | `0` (조립이 강제) | `1` | 백엔드는 503 `IDEMPOTENCY_UNAVAILABLE`(작업 실행 전 거절)에 "같은 키로 다시"를 요구한다. 실행기는 이 답에만 같은 키로 스스로 다시 보낸다. 실제 상한은 min(`retryBudget`, 앱 `MAX_RETRY_ATTEMPTS`(기본 2), 하드 상한 2)이다. 응답을 잃은 뒤에는 스스로 다시 보내지 않는다 | +| `commandRecovery` | `null` | `{ mode: "IDEMPOTENCY_REPLAY", operationIdentityField: "idempotencyKey" }` | 조립이 `KEYED`에 요구한다. `operationIdentityField`는 같은 요청을 알아보는 값의 이름이다. 실행기는 intent의 `idempotencyKey`를 `Idempotency-Key` 헤더로 보낸다. 이 칸은 FE-REG-API에 기록되고 실행기는 읽지 않는다 | +| 호출 문맥의 `intent` | 넘긴다(키 없음) | 넘긴다(키 있음) | 뮤테이션 조정자가 만든 intent를 input → gateway → 바인딩까지 그대로 넘긴다(생성된 `CommandContext`가 `intent`를 필수로 받는다). 빠뜨리면 `KEYED`는 보내기 전에 거부된다 | +| `commandEffect.classifyStatus` | `() => "NOT_APPLIED"` | 같다 | 생성된 create의 401은 보안 필터 체인, 403은 use case의 `@RequiresPermission` 프록시, 429는 rate-limit interceptor(`preHandle`)가 use case 전에 낸다. use case 안에서 `AuthorizationPort`를 쓰기 뒤에 부르게 바꾸면 403이 쓰기 뒤에도 나올 수 있다. 그때는 이 칸을 지운다(= `MAYBE_APPLIED`) | +| `commandEffect.refusedBeforeWrite` | `["_INVALID"]` | 같다 | 이름 규칙을 트랜잭션 전에 검사한다(4절) | +| `acceptedStatuses` | `[201]` | `[201]` | `ResponseEntity.created`. 같은 키 재생도 첫 요청과 같은 201이다 | +| 결과 불명 화면 | 확인만. 다시 보내기 버튼 없음 | "같은 요청으로 다시 보내기"가 같은 키로 보낸다 | 키 없는 재전송은 서버가 새 요청으로 본다 | +| 생성 테스트 | 응답 유실 → 결과 불명, 다시 보내기 없음, 키 헤더 없음 | 응답 유실 → 같은 키로 다시 보내기. 503 `IDEMPOTENCY_UNAVAILABLE` → 같은 키로 1회 자동 재전송 | `tests/features//-create-page.test.tsx`, `-http-gateway.test.ts` | + +- 테스트 하네스의 재시도 상한: 생성된 gateway 테스트는 앱 기본값(`maxRetryAttempts: 2`)으로 돈다. 그래야 `retryBudget: 1`의 재전송이 보인다. 페이지 테스트(`-test-app.tsx`)는 실패를 바로 보이려고 `MAX_RETRY_ATTEMPTS: 0`이다. + **정본**: 백엔드가 멱등 키 요청에 어떻게 답하는지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2(멱등성 응답)다. 여기에 표를 옮기지 않는다. **어디에 적나**: `contracts/-contract-contribution.ts`의 `retrySemantics`, `commandRecovery`, `frontend.retryBudget`. 다른 파일에 다시 적지 않는다.