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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user