docs(contract): 계약 4.1·6절이 백엔드 http-contract.md를 가리킨다 (백엔드 1101/02-01)

문제
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
This commit is contained in:
DongHyeonka
2026-11-03 02:00:45 +09:00
parent 183a4a373d
commit 3b7d73ab37
@@ -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