docs(contract): 4.2절의 400·422 행을 짝 백엔드 거절 표에 맞춘다
문제
계약 문서 4.2절은 422를 "field validation"으로 적는다. 3261208 뒤로 프론트는
422 중 IDEMPOTENT_REQUEST_MISMATCH만 적용 안 됨으로 보고, 짝 백엔드는 필드
검증을 400 VALIDATION_FAILED로 보낸다. 같은 문서의 6.1절 표와 4.2절이 서로
다른 말을 한다.
고른 방법
- 400 행에 짝 백엔드 필드 검증이 400 VALIDATION_FAILED라는 것을 더하고
적용 여부는 6.1절을 가리킨다.
- 422 행을 짝 백엔드 기준으로 바꿨다. 기본 배포는 IDEMPOTENT_REQUEST_MISMATCH만,
fileserver는 쓰기 뒤에도 나오는 code를 422로 보낸다. 폼 필드 오류는
details.issues[]가 있으면 여전히 읽는다.
- 리뷰 README 14.6의 위험 줄을 고친 상태로 바꿨다.
버린 대안
- 422 행을 그대로 두고 6.1절만 믿기: 같은 문서 안에서 두 절이 어긋난다.
위험·한계
- 422로 필드 검증을 보내는 다른 백엔드를 쓰는 프로젝트는 422 뒤에 폼에서
다시 저장할 수 없다. 문서는 그 동작을 적을 뿐 바꾸지 않는다.
검증
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.6
This commit is contained in:
@@ -178,13 +178,13 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정
|
||||
|
||||
| HTTP status | 의미 |
|
||||
| --- | --- |
|
||||
| `400` | malformed request 또는 closed request contract 위반 |
|
||||
| `400` | malformed request 또는 closed request contract 위반. 짝 백엔드의 필드 검증 실패는 400 `VALIDATION_FAILED`(필드 목록 `details`)다. 적용 여부는 6.1절 |
|
||||
| `401` | 인증 없음/만료. 이미 적용된 command를 401로 반환하지 않음 |
|
||||
| `403` | authenticated principal에게 권한 없음 |
|
||||
| `404` | authorization 정책상 공개 가능한 not-found |
|
||||
| `409` | domain revision 또는 semantic conflict. 멱등성 응답(409·422·400)은 6절 |
|
||||
| `412` | selected conditional write의 `If-Match` precondition 실패 |
|
||||
| `422` | field validation. bounded `details.issues[]`만 허용 |
|
||||
| `422` | 짝 백엔드에서는 field validation이 아니다. 기본 배포는 `IDEMPOTENT_REQUEST_MISMATCH`(6절)만, fileserver 모듈은 쓰기 뒤에도 나오는 code를 422로 보낸다. 프론트는 `IDEMPOTENT_REQUEST_MISMATCH`만 적용 안 됨으로 보고, 폼 필드 오류는 `details.issues[]`가 있으면 읽는다. 적용 여부는 6.1절 |
|
||||
| `429` | rate limit. 유효한 `Retry-After`와 operation 정책 제공 |
|
||||
| `500/502/503/504` | server/provider failure. command effect certainty 별도 |
|
||||
|
||||
|
||||
@@ -575,7 +575,7 @@ Envelope operation에서는 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 ef
|
||||
- RED: 바뀐 행 8건 실패(V2 `{cause}`·details 없음·`{field, code}`의 effect 3건, "unrelated 422" 진단 1건, V3 고정 판정 2건, 폼 2건). GREEN: 같은 파일들 128건 통과.
|
||||
- 게이트(`3261208`): `check:types`, `lint`, `check:architecture`, `check:diagnostics`, `check:ci`, `check:registries`, `check:adapter-inventory`, `verify:documentation` 통과. `test:unit` 2,604 / `test:integration` 209 / `test:component` 245 / features·contract 124건 통과. `check:bundle` 203,354 / 204,800 B. `test:feature-scaffold` 16개, `test:sample-removal` 23개 검사 통과. `f3b87b3`에서 다시 돌린 `test:feature-scaffold`는 한 번 실패했다. 실패한 것은 HTTP와 무관한 `tests/unit/task3-selective-integration.test.ts`("provider scope EOF close timed out")였고, 그때 호스트 load가 약 20이었다. 단독으로 3회 돌리면 3회 통과하고, `3261208` 실행에서도 통과했다
|
||||
- 버린 대안: (1) V2·V3에 표를 따로 두기: 두 번째 표가 다시 갈라진다. (2) 표 밖 400·409·422를 `classifyProblem`에 맡기기: 6.1절이 "표에 없는 400·409·422는 `MAYBE_APPLIED`"로 정했고, 참조 분류기처럼 400·422를 모두 `NOT_APPLIED`로 보는 패키지가 다음 저장에 새 키를 쓰게 한다. (3) 422를 필드 검증으로 남기기: 짝 백엔드는 필드 검증을 400으로 보내고, fileserver 422는 레코드를 쓴 뒤 던진다.
|
||||
- 위험: 필드 검증을 422로 보내는 다른 백엔드를 V2로 쓰는 프로젝트는 422 뒤에 다시 저장할 수 없게 된다(결과 불명 화면). 프론트 계약 문서 4.2절의 "`422` field validation" 행과 어긋난다. 그 줄은 이 브랜치 범위 밖이라 고치지 않았다.
|
||||
- 위험: 필드 검증을 422로 보내는 다른 백엔드를 V2로 쓰는 프로젝트는 422 뒤에 다시 저장할 수 없게 된다(결과 불명 화면). 프론트 계약 문서 4.2절의 400·422 행을 짝 백엔드 기준으로 고쳤다.
|
||||
|
||||
**V2와 남은 차이** (의도한 것):
|
||||
|
||||
|
||||
Reference in New Issue
Block a user