Files
clean-architecture-frontend…/src
DongHyeonka 02e35d2b38 fix(http): 짝 백엔드의 400 VALIDATION_FAILED를 폼 필드 오류로 읽는다 (백엔드 1101/02-01)
문제
짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다. details는
위반 하나마다 {field, code, message}인 배열이다(백엔드 docs/web/http-
contract.md 4절, ClientSafeValidationDetails). field는 점으로 이은 속성
이름이고 인덱스는 뺀다. 클래스 수준 오류는 "request"다.
프론트 V2 클라이언트(client.ts)는 422만 필드 검증으로 읽는다. 400은
UNKNOWN_CLIENT_FAILURE이고 validationIssues가 없어서, 폼(use-app-form.ts)이
필드 오류 대신 "unavailable" 상태를 보인다. safeValidationIssues도
{issues}·{fieldErrors} 객체만 읽어서 배열 details를 버린다.

고른 방법
- V2: 400 + code VALIDATION_FAILED + details가 배열이면 422와 같은 것으로
  본다. kind VALIDATION_REJECTED와 validationIssues를 422 경로와 같은 식으로
  만든다. 폼은 기존 mapValidationFailureToFields와 allowedServerFields를
  그대로 쓴다. 새 폼 경로는 없다.
- safeValidationIssues: details가 배열이면 각 항목의 field를 path로 읽는다.
  message는 버린다. 후보 수는 기존 상한(MAX_VALIDATION_ISSUE_CANDIDATES)으로
  자른 뒤 projectValidationIssues에 넘긴다.
- 그 밖의 400은 그대로 둔다: details가 {cause}인 VALIDATION_FAILED(본문
  파싱 실패), details 없는 VALIDATION_FAILED, BAD_PARAMETER,
  IDEMPOTENCY_KEY_INVALID(NOT_APPLIED 판정 유지).

버린 대안
- 400 VALIDATION_FAILED 전체를 VALIDATION_REJECTED로: 파싱 실패 같은
  클라이언트 버그가 "입력값을 다시 확인해 주세요."로 보인다. 필드 목록이
  있을 때만 바꾼다.
- 공용 projectValidationIssues가 field를 path 별칭으로 받게: zod 이슈와
  V3 경로까지 같은 규칙을 갖게 된다. 백엔드 wire 모양은 V2 전용
  safeValidationIssues에서만 읽는다.
- V3 참조 기능 mapProblem도 바꾸기: 참조 fixture는 problem+json
  (type·title·status·issues)이라 짝 백엔드 Envelope가 problem 검증을 통과하지
  않는다. 짝 백엔드 wire를 읽는 곳은 V2다.

위험·한계
- 백엔드 code(NOT_BLANK, SIZE 등)는 폼 문구 표(VALIDATION_COPY)에 없어서
  필드 문구가 "입력값을 확인해 주세요."(form.validation.unknown)다. 필드
  위치는 맞게 표시된다. 코드별 문구는 이 변경 밖이다.
- 페이지·정렬 파라미터 검증(PageValidationException)은 details가 배열이
  아닌 단일 {field, code}라 지금처럼 UNKNOWN_CLIENT_FAILURE로 남는다. 폼
  입력이 아니라 목록 조회 파라미터다.
- V2 필드 검증 실패에는 effect가 없다(422와 같다). mutation 코디네이터는
  이것을 MAYBE_APPLIED로 보고 admission을 붙든다. 422에도 있던 기존 동작이다.

검증
- RED: tests/component/form-foundation.test.tsx 새 행이 실패. V2
  클라이언트가 400 VALIDATION_FAILED를 받으면 폼 결과가 "unavailable"이고
  Name 필드에 aria-invalid가 없다. tests/integration/http-client.test.ts
  "reads the field details as validation issues" 실패(kind
  UNKNOWN_CLIENT_FAILURE, issues 없음). 다른 400 3행은 처음부터 통과(유지
  동작 고정).
- GREEN: 위 행 모두 통과. tests/unit·contract·runtime-schema·integration·
  component·features·platform 283 files 중 282 통과, 3394 tests 통과.
  실패 1개(tests/unit/second-api-feature-registries.test.ts "passes
  check-registries…")는 기준 3b7d73a에서도 같은 메시지로 실패한다.
  tsc app·test·node 통과, 바꾼 파일 eslint 통과, check:registries PASS.

Refs: clean-architecture-backend-template docs/web/http-contract.md 4절
2026-11-03 02:15:48 +09:00
..