docs(manual): 짝 백엔드 생성 기능의 쓰기 값 넷을 결정표에 적는다
문제 짝 백엔드에 쓰기를 붙일 때 기능 작성자가 정하는 값 넷(호출 문맥 intent, retryBudget, classifyStatus, operationIdentityField)을 매뉴얼이 정해 주지 않는다. 02 3절은 "retryBudget 안에서 같은 키로 재전송"과 "참조 기능은 0"을 함께 적어 부딪히고, 401·403·429를 짝 백엔드가 쓰기 전에 거절하는지는 어느 문서에도 없다. 실험에서 실행기 코드를 읽고 값을 정했다(리뷰 B1~B4). 또 백엔드 생성 create가 NOT_IDEMPOTENT라는 사실과 프론트 retrySemantics의 관계가 적혀 있지 않다(03-07). 고른 방법 - 02 3절에 "짝 백엔드의 생성 기능에 붙일 때" 표를 둔다. 백엔드 create를 그대로 두면 NEVER, IdempotencyExecutor 뒤로 옮기면 KEYED. 두 경우의 retrySemantics, retryBudget(0 / 1과 실제 상한 계산), commandRecovery와 operationIdentityField의 뜻(실행기는 읽지 않음), intent 전달, classifyStatus(401 보안 필터, 403 @RequiresPermission 프록시, 429 rate-limit interceptor preHandle — 백엔드 코드에서 확인), refusedBeforeWrite, acceptedStatuses, 결과 불명 화면, 생성 테스트를 적는다. - 01 4단계에 쓰기 메서드의 호출 문맥(intent), 8단계에 NEVER는 다시 보내기 버튼이 없다는 것과 생성 예제 위치를 적는다. - 표의 값은 create:feature --with-create(--keyed)가 만드는 값과 같다. 버린 대안 - classifyStatus를 "백엔드 확인 전에는 생략"으로 두기(리뷰 권고 (1)의 잠정안): 백엔드 코드를 확인해 생성 create에서는 셋 다 use case 전이라 NOT_APPLIED로 적었다. use case가 AuthorizationPort를 쓰기 뒤에 부르면 지우라고 조건을 붙였다. 위험·한계 - classifyStatus 판정은 백엔드 c508b1ba의 생성 템플릿과 web 어댑터 기준이다. 백엔드가 바뀌면 다시 본다. 검증 - verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-07 Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
This commit is contained in:
@@ -323,6 +323,7 @@ projectRequest: (input) => Object.freeze({
|
||||
|
||||
- input 메서드 이름. 사용자가 하는 일로 짓는다(`listItems`, `createInvoice`).
|
||||
- 반환 타입. `Result<Value>`(`src/contracts/result.ts`)를 쓴다.
|
||||
- 쓰기 메서드의 호출 문맥. 쓰기는 뮤테이션의 `intent`를 받아 gateway까지 넘긴다(`Readonly<{ signal?: AbortSignal; intent: MutationIntent }>`). `KEYED` 쓰기의 멱등 키가 intent에 있다. `--with-create`의 `<Base>CommandContext`가 이 모양이다.
|
||||
- 실패 telemetry의 `kind`. `<base>.<동작>.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 <id> --with-create`의 `presentation/<base>-create-page.tsx`(짝 백엔드 Envelope), `src/features/reference-feature/presentation/reference-resource-form-page.tsx`(problem details)
|
||||
|
||||
③ **잡는 검사 / 못 잡는 것**
|
||||
|
||||
|
||||
@@ -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(<OPERATION>_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 <id> --with-create
|
||||
└─ IdempotencyExecutor 뒤로 옮김 (KEYED, 백엔드 docs/manual/05-idempotency.md "KEYED로 만드는 순서")
|
||||
→ 프론트 KEYED ← create:feature <id> --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 → 바인딩까지 그대로 넘긴다(생성된 `<Base>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` | `["<FEATURE>_INVALID"]` | 같다 | 이름 규칙을 트랜잭션 전에 검사한다(4절) |
|
||||
| `acceptedStatuses` | `[201]` | `[201]` | `ResponseEntity.created`. 같은 키 재생도 첫 요청과 같은 201이다 |
|
||||
| 결과 불명 화면 | 확인만. 다시 보내기 버튼 없음 | "같은 요청으로 다시 보내기"가 같은 키로 보낸다 | 키 없는 재전송은 서버가 새 요청으로 본다 |
|
||||
| 생성 테스트 | 응답 유실 → 결과 불명, 다시 보내기 없음, 키 헤더 없음 | 응답 유실 → 같은 키로 다시 보내기. 503 `IDEMPOTENCY_UNAVAILABLE` → 같은 키로 1회 자동 재전송 | `tests/features/<id>/<base>-create-page.test.tsx`, `<base>-http-gateway.test.ts` |
|
||||
|
||||
- 테스트 하네스의 재시도 상한: 생성된 gateway 테스트는 앱 기본값(`maxRetryAttempts: 2`)으로 돈다. 그래야 `retryBudget: 1`의 재전송이 보인다. 페이지 테스트(`<base>-test-app.tsx`)는 실패를 바로 보이려고 `MAX_RETRY_ATTEMPTS: 0`이다.
|
||||
|
||||
**정본**: 백엔드가 멱등 키 요청에 어떻게 답하는지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2(멱등성 응답)다. 여기에 표를 옮기지 않는다.
|
||||
|
||||
**어디에 적나**: `contracts/<base>-contract-contribution.ts`의 `retrySemantics`, `commandRecovery`, `frontend.retryBudget`. 다른 파일에 다시 적지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user