fix(http): 필드 목록이 없는 422를 입력 오류로 읽지 않는다

문제
Envelope 실패 해석이 422를 모두 필드 검증으로 본다
(isFieldValidationFailure). 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH는
"같은 키를 다른 본문으로 보냈다"는 뜻이고 필드 목록이 없다. 그런데 kind가
VALIDATION_REJECTED가 되어 폼이 "입력값을 다시 확인해 주세요."를 띄운다.
사용자는 고칠 것이 없는 입력을 고치라는 말을 듣고, validation-error 상태는
지원 참조도 보이지 않는다. fileserver의 422(INTEGRITY_MISMATCH 등)도 같다.

고른 방법
422는 details에서 필드 목록(safeValidationIssues가 읽는 모양)이 나올 때만
필드 검증으로 본다. 필드 목록이 없는 422의 kind는 UNKNOWN_CLIENT_FAILURE다.
400 IDEMPOTENCY_KEY_INVALID와 같은 읽기다. 폼은 unavailable 상태와 지원
참조를 보인다. effect 판정(표)은 바꾸지 않았다. 422 MISMATCH는 그대로
NOT_APPLIED, 표 밖 422는 그대로 MAYBE_APPLIED다.

버린 대안
IDEMPOTENT_REQUEST_MISMATCH 한 code만 빼기: fileserver 422처럼 필드 목록
없는 다른 422가 계속 입력 오류로 보인다.

위험·한계
422로 필드 오류를 보내면서 details에 목록을 싣지 않는 백엔드는 이제 필드
오류 대신 실패 상태를 보인다. 짝 백엔드는 필드 검증을 400으로 보낸다.

검증
- RED: backend-envelope 단위 1건, envelope 통합 2건(422 MISMATCH·
  INTEGRITY_MISMATCH의 kind), form-foundation 1건(결과 unavailable, 문구
  없음) 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
  3,114건 통과. details.issues가 있는 422는 그대로 필드 오류다
  ("keeps the save off after a 422 the backend may have applied").
- check:types:app·test, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-05
This commit is contained in:
DongHyeonka
2026-11-04 20:27:53 +09:00
parent 61f70cb9b8
commit 613c1cfd0c
5 changed files with 94 additions and 13 deletions
+16 -10
View File
@@ -133,20 +133,24 @@ export function idempotencyRefusalReason(
}
/**
* 백엔드 1101/02-01 후속. A failure the form shows on its fields: a 422, or
* the paired backend's 400 VALIDATION_FAILED whose details is the field list
* (§4). This decides the kind and the issues only, not whether it applied.
* 백엔드 1101/02-01 후속. A failure the form shows on its fields: the paired
* backend's 400 VALIDATION_FAILED whose details is the field list (§4), or a
* 422 that carries a field list. This decides the kind and the issues only,
* not whether it applied.
*
* 1103/08-05. A 422 without one is not an input error: the paired backend's
* 422 IDEMPOTENT_REQUEST_MISMATCH (the same key went out with another body)
* and fileserver's 422s leave the user nothing to correct.
*/
export function isFieldValidationFailure(
status: number,
error: EnvelopeError,
): boolean {
return (
status === 422 ||
(status === 400 &&
error.code === "VALIDATION_FAILED" &&
Array.isArray(error.details))
);
return status === 422
? safeValidationIssues(error.details).length > 0
: status === 400 &&
error.code === "VALIDATION_FAILED" &&
Array.isArray(error.details);
}
/**
@@ -209,7 +213,9 @@ export function envelopeFailureReading(
return Object.freeze({
kind: fieldValidation
? "VALIDATION_REJECTED"
: gatewayFailureOr(status, kindForStatus(status)),
: status === 422
? "UNKNOWN_CLIENT_FAILURE"
: gatewayFailureOr(status, kindForStatus(status)),
code: error.code,
...(fieldValidation
? { validationIssues: safeValidationIssues(error.details) }