diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 5fad9e6a..13d88ca9 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -160,45 +160,17 @@ authorization을 다시 수행한다. ### 4.1 JSON envelope -모든 현재 JSON success/failure는 다음 envelope를 사용한다. +Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정본이다. 이 +문서에 표를 다시 적지 않는다. -```json -{ - "success": true, - "data": {}, - "meta": { - "requestId": "server-request-id", - "traceId": "server-trace-id", - "correlationId": "client-correlation-id" - } -} -``` - -```json -{ - "success": false, - "error": { - "code": "STABLE_MACHINE_CODE", - "category": "optional-safe-category", - "message": "optional non-sensitive copy", - "retryable": false, - "details": {} - }, - "meta": { - "requestId": "server-request-id", - "traceId": "server-trace-id", - "correlationId": "client-correlation-id" - } -} -``` - -Envelope 최상위 unknown field는 현재 거절된다. ordinary resource DTO의 unknown -field는 frontend schema에서 strip되지만 additive compatibility는 contract -review와 fixture를 먼저 통과해야 한다. - -`requestId`, `traceId`, `correlationId`는 각각 1..128 범위의 안전한 opaque -identifier다. credential, user data, cursor, validator와 database key를 -identifier에 encode하지 않는다. +- 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md) + 1절 "Envelope 키 존재 규칙" +- 기준 버전: 백엔드 성숙도 리뷰 2026-11-01의 15절 결정(2026-11-03)을 반영한 본. + 값이 null인 필드는 키째 생략한다. 백엔드에 이 변경의 커밋이 생기면 그 SHA로 + 바꾼다. +- 프론트에서 Envelope를 읽는 곳: V2 `src/adapters/http/schema-registry.ts`와 + `src/adapters/http/client.ts`. V3 실행기는 Envelope 없이 DTO를 검증한다 + (`src/adapters/http/index.ts` V2 주석). ### 4.2 Status와 error @@ -208,7 +180,7 @@ identifier에 encode하지 않는다. | `401` | 인증 없음/만료. 이미 적용된 command를 401로 반환하지 않음 | | `403` | authenticated principal에게 권한 없음 | | `404` | authorization 정책상 공개 가능한 not-found | -| `409` | idempotency fingerprint, domain revision 또는 semantic conflict | +| `409` | domain revision 또는 semantic conflict. 멱등성 응답(409·422·400)은 6절 | | `412` | selected conditional write의 `If-Match` precondition 실패 | | `422` | field validation. bounded `details.issues[]`만 허용 | | `429` | rate limit. 유효한 `Retry-After`와 operation 정책 제공 | @@ -264,50 +236,20 @@ Cross-origin bearer provider 최소 CORS: `CREATE_REFERENCE_RESOURCE`는 keyed command다. frontend memory single-flight는 backend idempotency를 대체하지 않는다. -idempotency identity: +멱등성 응답의 status·`error.code`·`retryable`·`Retry-After`와 키 문법은 짝 +백엔드 템플릿 문서가 정본이다. 이 문서에 표를 다시 적지 않는다. -```text -principal/tenant - + semantic operation ID and contract version - + Idempotency-Key - + canonical request fingerprint -``` - -권장 record: - -```text -IdempotencyRecord - principalFingerprint - operationId - contractVersion - idempotencyKeyHash - requestFingerprint - state = IN_PROGRESS | COMMITTED | FAILED_SAFE | EFFECT_UNKNOWN - responseStatus - responseEnvelopeReference - resourceRevision | null - leaseOwner + leaseExpiry - retentionExpiry - createdAt + completedAt -``` - -불변조건: - -- claim과 command transaction의 관계가 원자적이거나 crash reconciliation - 가능해야 한다. -- 같은 key와 같은 fingerprint replay는 같은 authoritative receipt를 반환한다. -- 같은 key와 다른 fingerprint는 `409 IDEMPOTENCY_KEY_REUSED`다. -- concurrent replay는 하나만 실행하고 나머지는 같은 result를 기다리거나 - bounded `IN_PROGRESS` 결과를 받는다. -- commit 뒤 response 유실은 새 resource를 만들지 않는다. -- `EFFECT_UNKNOWN`은 새 key로 자동 재시도하지 않고 status/reconcile endpoint로 - 확인한다. -- retention은 frontend retry/recovery 최대 window보다 길고 quota/abuse limit이 - 있다. -- key 원문과 request body를 log/metric label에 넣지 않는다. - -Database unique constraint 또는 durable compare-and-set이 최종 중복 방지 -authority여야 한다. process-local map/lock만 사용하지 않는다. +- 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md) + 2절 "멱등성 응답", 4절 "web 전용 오류 코드" +- 기준 버전: 4.1절과 같다(백엔드 리뷰 2026-11-01 15절 결정, 2026-11-03). +- 프론트가 그 응답을 읽는 곳: + - 키 생성·검사: `src/contracts/mutation-intent.ts` `isValidIdempotencyKey` + - 결과 불명 재전송이 같은 키를 쓰고 `Retry-After`까지 기다리는 곳: + `src/presentation/adapters/query/application-query.ts` + - V2 거절 판정: `src/adapters/http/client.ts` `IDEMPOTENCY_REFUSALS` + - V3 참조 기능 판정: `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts` + (effect), `src/features/reference-feature/adapters/reference-http-gateway.ts` + (code) ## 7. Cursor pagination과 snapshot