From bf86fe5cd077d0f450dc2cda2b84b34b0003664d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 20:55:50 +0900 Subject: [PATCH] =?UTF-8?q?docs(contract):=204.2=EC=A0=88=EC=9D=98=20400?= =?UTF-8?q?=C2=B7422=20=ED=96=89=EC=9D=84=20=EC=A7=9D=20=EB=B0=B1=EC=97=94?= =?UTF-8?q?=EB=93=9C=20=EA=B1=B0=EC=A0=88=20=ED=91=9C=EC=97=90=20=EB=A7=9E?= =?UTF-8?q?=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 계약 문서 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 --- docs/architecture/backend-api-and-server-state-contract.md | 4 ++-- docs/reviews/2026-11-01-maturity-review/README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 83d9be19..3c7b8d47 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -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 별도 | diff --git a/docs/reviews/2026-11-01-maturity-review/README.md b/docs/reviews/2026-11-01-maturity-review/README.md index e210e4d0..08946263 100644 --- a/docs/reviews/2026-11-01-maturity-review/README.md +++ b/docs/reviews/2026-11-01-maturity-review/README.md @@ -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와 남은 차이** (의도한 것):