From 3b7d73ab37aeb8262d6e55b5e283efb8b8b8be02 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 01:57:17 +0900 Subject: [PATCH] =?UTF-8?q?docs(contract):=20=EA=B3=84=EC=95=BD=204.1?= =?UTF-8?q?=C2=B76=EC=A0=88=EC=9D=B4=20=EB=B0=B1=EC=97=94=EB=93=9C=20http-?= =?UTF-8?q?contract.md=EB=A5=BC=20=EA=B0=80=EB=A6=AC=ED=82=A8=EB=8B=A4=20(?= =?UTF-8?q?=EB=B0=B1=EC=97=94=EB=93=9C=201101/02-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 docs/architecture/backend-api-and-server-state-contract.md 4.1절(JSON envelope)과 6절(Command와 idempotency)이 백엔드 계약을 직접 다시 적었다. 짝 백엔드가 바뀐 뒤 둘이 어긋난다. - 4.1절 예시는 meta id를 늘 싣고 null 생략 규칙이 없다. - 6절은 같은 키·다른 본문을 409 IDEMPOTENCY_KEY_REUSED로 적는다. 백엔드는 422 IDEMPOTENT_REQUEST_MISMATCH다. 처리 중 409의 retryable·Retry-After, 400 IDEMPOTENCY_KEY_INVALID도 없다. - 4.2절 409 행이 "idempotency fingerprint" 충돌을 409로 적는다. 백엔드 http-contract.md 5절은 이 두 절이 자기 문서를 가리켜야 한다고 적는다. 고른 방법 - 4.1절·6절의 표와 예시를 지우고 백엔드 문서 링크(1절, 2절·4절)와 기준 버전(백엔드 리뷰 2026-11-01 15절 결정, 2026-11-03)만 적는다. 백엔드 변경은 아직 커밋이 없어 SHA 대신 결정 날짜를 적고, 커밋이 생기면 SHA로 바꾸라고 적었다. - 프론트가 그 계약을 읽는 코드 위치만 남긴다. 표를 복사하지 않는다. - 4.2절 409 행에서 멱등성 충돌을 빼고 6절을 가리킨다. 버린 대안 - 프론트 문서의 표를 백엔드 값으로 고쳐 두기: 다음 백엔드 변경에서 다시 어긋난다. 위험·한계 - 링크는 두 repo가 같은 상위 폴더에 나란히 있을 때만 열린다 (../../../clean-architecture-backend-template/...). verify:documentation은 repo 밖 링크를 검사하지 않는다. - 6절에서 지운 권장 IdempotencyRecord와 불변조건은 짝 백엔드가 구현과 문서로 소유한다. 다른 백엔드를 붙이는 제품은 백엔드 문서를 기준으로 삼는다. - 4.2절의 422 행(field validation)은 그대로다. 짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다(백엔드 http-contract.md 4절). 이 차이는 이 변경 범위 밖이다. 검증 - node scripts/verify-documentation-readiness.ts: PASS_SCOPED. Refs: clean-architecture-backend-template docs/web/http-contract.md 5절, docs/reviews/2026-11-01-maturity-review/README.md 14.3 --- .../backend-api-and-server-state-contract.md | 106 ++++-------------- 1 file changed, 24 insertions(+), 82 deletions(-) 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