fix(forms): 짝 백엔드 필드 검증 code마다 문구를 보인다 (1101/14.4)
문제
짝 백엔드는 필드 검증 실패의 details[].code에 NOT_BLANK, SIZE 같은 자기
code를 싣는다(백엔드 5786126c ClientSafeValidationDetails.java RULES 18-42와
INVALID). 폼 문구 표(form-contracts.ts VALIDATION_COPY)에는 zod code와
REQUIRED만 있어서, 백엔드 code는 모두 form.validation.unknown("입력값을
확인해 주세요.")이 된다. 필드 위치는 맞지만 무엇이 틀렸는지 알 수 없다.
고른 방법
- VALIDATION_COPY에 백엔드 code 20개를 모두 넣었다. 뜻이 같은 것은 기존
키를 쓴다: NOT_NULL·NOT_BLANK·NOT_EMPTY → required, PATTERN →
invalidFormat, TYPE_MISMATCH → invalidType, ASSERT_TRUE·ASSERT_FALSE →
invalidValue.
- 나머지 13개는 새 키로 ko-KR·en-US 문구를 넣었다(size, min, max, positive,
positiveOrZero, negative, negativeOrZero, email, past, pastOrPresent,
future, futureOrPresent, invalid). ar-EG는 en-US 표를 그대로 쓴다.
- 모르는 code는 그대로 form.validation.unknown이다.
- 백엔드 code를 쓰는 곳은 V2 client가 이미 details[].code를 issue code로
넘기는 경로(errors.ts safeValidationIssues)라 표 한 곳만 바꿨다.
버린 대안
- SIZE를 tooSmall·tooBig에 맞추기: SIZE는 짧은지 긴지 말하지 않는다. 한쪽
문구를 고르면 틀린 말을 할 수 있다.
- 백엔드가 보낸 message를 보여 주기: 백엔드 문구를 화면에 그리지 않는 규칙
(check-i18n rawFailureRender, errors.ts)을 깬다. 한국어만 있다.
- 백엔드 소스에서 code 목록을 읽는 검사: 두 repo가 나란히 있어야 돈다.
목록은 테스트에 SHA와 함께 적었다.
위험·한계
- 백엔드가 code를 더하면 프론트는 알지 못하고 기본 문구가 나온다. 알아챌
방법은 백엔드가 code 목록을 문서나 레지스트리로 내주는 것이다(최종 보고에
제안).
- 페이지·정렬 파라미터 code(PAGE_NEGATIVE, SIZE_EXCEEDS_MAX 등)는 details가
배열이 아니라 폼 issue가 되지 않으므로 넣지 않았다.
- 초기 JS gzip 202,770 → 203,165 B(+395, 예산 204,800). i18n catalog가 초기
청크에 있다.
검증
- RED: tests/component/form-foundation.test.tsx 3행 실패. ko-KR·en-US 모두
백엔드 code 20개가 기본 문구였고, 400 VALIDATION_FAILED NOT_BLANK 행은
"Name: 입력값을 확인해 주세요."를 보였다.
- GREEN: 위 3행과 "keeps the default copy for a code it does not know" 통과.
tests/component·unit·features 237 files 2951 tests 통과.
- node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts:
237 keys across 4 locales PASS. node scripts/check-registries.ts: PASS,
compatibility=none.
- tsc app·test 통과, 바꾼 파일 eslint 통과.
- 초기 JS는 기준 트리와 이 트리를 각각 build-frontend.ts로 빌드하고
check-bundle.ts와 같은 방식(classifyViteJavascript initialFiles, gzipSync)으로
쟀다. check-bundle.ts는 pnpm이 만드는 bundle.json이 필요해 돌리지 않았다.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4
This commit is contained in:
@@ -37,6 +37,30 @@ const VALIDATION_COPY = Object.freeze({
|
||||
invalid_type: "form.validation.invalidType",
|
||||
invalid_format: "form.validation.invalidFormat",
|
||||
invalid_value: "form.validation.invalidValue",
|
||||
// 1101/14.4. The paired backend's field codes, every one it can send
|
||||
// (clean-architecture-backend-template 5786126c,
|
||||
// ClientSafeValidationDetails.java RULES and INVALID). A code it adds later
|
||||
// shows form.validation.unknown until it gets a row here.
|
||||
NOT_NULL: "form.validation.required",
|
||||
NOT_BLANK: "form.validation.required",
|
||||
NOT_EMPTY: "form.validation.required",
|
||||
SIZE: "form.validation.size",
|
||||
MIN: "form.validation.min",
|
||||
MAX: "form.validation.max",
|
||||
POSITIVE: "form.validation.positive",
|
||||
POSITIVE_OR_ZERO: "form.validation.positiveOrZero",
|
||||
NEGATIVE: "form.validation.negative",
|
||||
NEGATIVE_OR_ZERO: "form.validation.negativeOrZero",
|
||||
PATTERN: "form.validation.invalidFormat",
|
||||
EMAIL: "form.validation.email",
|
||||
PAST: "form.validation.past",
|
||||
PAST_OR_PRESENT: "form.validation.pastOrPresent",
|
||||
FUTURE: "form.validation.future",
|
||||
FUTURE_OR_PRESENT: "form.validation.futureOrPresent",
|
||||
ASSERT_TRUE: "form.validation.invalidValue",
|
||||
ASSERT_FALSE: "form.validation.invalidValue",
|
||||
TYPE_MISMATCH: "form.validation.invalidType",
|
||||
INVALID: "form.validation.invalid",
|
||||
});
|
||||
|
||||
type MessageResolver = (key: ParameterlessMessageKey) => string;
|
||||
|
||||
@@ -140,6 +140,19 @@ const PLATFORM_KO_MESSAGES = {
|
||||
"form.validation.invalidType": "입력 형식을 확인해 주세요.",
|
||||
"form.validation.invalidFormat": "입력 형식을 확인해 주세요.",
|
||||
"form.validation.invalidValue": "허용된 값을 선택해 주세요.",
|
||||
"form.validation.size": "길이나 개수가 허용 범위를 벗어났습니다.",
|
||||
"form.validation.min": "허용된 최솟값보다 작습니다.",
|
||||
"form.validation.max": "허용된 최댓값보다 큽니다.",
|
||||
"form.validation.positive": "0보다 큰 값을 입력해 주세요.",
|
||||
"form.validation.positiveOrZero": "0 이상의 값을 입력해 주세요.",
|
||||
"form.validation.negative": "0보다 작은 값을 입력해 주세요.",
|
||||
"form.validation.negativeOrZero": "0 이하의 값을 입력해 주세요.",
|
||||
"form.validation.email": "이메일 주소 형식을 확인해 주세요.",
|
||||
"form.validation.past": "지난 시각을 입력해 주세요.",
|
||||
"form.validation.pastOrPresent": "앞으로의 시각은 입력할 수 없습니다.",
|
||||
"form.validation.future": "앞으로의 시각을 입력해 주세요.",
|
||||
"form.validation.futureOrPresent": "지난 시각은 입력할 수 없습니다.",
|
||||
"form.validation.invalid": "올바른 값을 입력해 주세요.",
|
||||
"form.validation.unknown": "입력값을 확인해 주세요.",
|
||||
"form.validation.retry": "입력값을 다시 확인해 주세요.",
|
||||
"form.validation.unknownField":
|
||||
@@ -339,6 +352,19 @@ const PLATFORM_EN_MESSAGES = {
|
||||
"form.validation.invalidType": "Check the input type.",
|
||||
"form.validation.invalidFormat": "Check the input format.",
|
||||
"form.validation.invalidValue": "Choose an allowed value.",
|
||||
"form.validation.size": "The length or count is outside the allowed range.",
|
||||
"form.validation.min": "This value is below the allowed minimum.",
|
||||
"form.validation.max": "This value is above the allowed maximum.",
|
||||
"form.validation.positive": "Enter a value greater than 0.",
|
||||
"form.validation.positiveOrZero": "Enter 0 or a greater value.",
|
||||
"form.validation.negative": "Enter a value less than 0.",
|
||||
"form.validation.negativeOrZero": "Enter 0 or a smaller value.",
|
||||
"form.validation.email": "Check the email address format.",
|
||||
"form.validation.past": "Enter a time in the past.",
|
||||
"form.validation.pastOrPresent": "A future time is not allowed.",
|
||||
"form.validation.future": "Enter a time in the future.",
|
||||
"form.validation.futureOrPresent": "A past time is not allowed.",
|
||||
"form.validation.invalid": "Enter a valid value.",
|
||||
"form.validation.unknown": "Check the entered value.",
|
||||
"form.validation.retry": "Review the entered values.",
|
||||
"form.validation.unknownField":
|
||||
|
||||
@@ -22,7 +22,12 @@ import {
|
||||
FormField,
|
||||
useAppForm,
|
||||
useDirtyNavigationGuard,
|
||||
validationMessage,
|
||||
} from "../../src/presentation/forms/index.ts";
|
||||
import {
|
||||
formatMessage,
|
||||
type ParameterlessMessageKey,
|
||||
} from "../../src/presentation/i18n/index.ts";
|
||||
|
||||
type Values = Readonly<Record<"name" | "note", string>>;
|
||||
|
||||
@@ -206,6 +211,8 @@ describe("local form facade", () => {
|
||||
expect(screen.getByRole("textbox", { name: /Note/ })).not.toHaveAttribute(
|
||||
"aria-invalid",
|
||||
);
|
||||
// NOT_BLANK has its own copy, not the "check the value" default.
|
||||
expect(screen.getByRole("alert")).toHaveTextContent("필수 입력값입니다.");
|
||||
// A class-level error names no form field.
|
||||
expect(screen.getByRole("alert")).toHaveTextContent(
|
||||
"서버가 확인하지 못한 입력 항목",
|
||||
@@ -448,6 +455,57 @@ describe("local form facade", () => {
|
||||
});
|
||||
});
|
||||
|
||||
// 1101/14.4. Every code the paired backend can put in a field error's
|
||||
// details[].code: clean-architecture-backend-template 5786126c,
|
||||
// ClientSafeValidationDetails.java RULES (18-42) and its INVALID fallback.
|
||||
// http-contract.md §4 names the shape, not the list. A code missing from the
|
||||
// form copy table shows the "check the value" default instead.
|
||||
const BACKEND_FIELD_CODES = [
|
||||
"NOT_NULL",
|
||||
"NOT_BLANK",
|
||||
"NOT_EMPTY",
|
||||
"SIZE",
|
||||
"MIN",
|
||||
"MAX",
|
||||
"POSITIVE",
|
||||
"POSITIVE_OR_ZERO",
|
||||
"NEGATIVE",
|
||||
"NEGATIVE_OR_ZERO",
|
||||
"PATTERN",
|
||||
"EMAIL",
|
||||
"PAST",
|
||||
"PAST_OR_PRESENT",
|
||||
"FUTURE",
|
||||
"FUTURE_OR_PRESENT",
|
||||
"ASSERT_TRUE",
|
||||
"ASSERT_FALSE",
|
||||
"TYPE_MISMATCH",
|
||||
"INVALID",
|
||||
] as const;
|
||||
|
||||
describe("paired backend field codes", () => {
|
||||
it.each(["ko-KR", "en-US"] as const)(
|
||||
"gives every backend field code its own %s copy",
|
||||
(locale) => {
|
||||
const message = (key: ParameterlessMessageKey) =>
|
||||
formatMessage(locale, key);
|
||||
const fallback = message("form.validation.unknown");
|
||||
|
||||
expect(
|
||||
BACKEND_FIELD_CODES.filter(
|
||||
(code) => validationMessage(code, message) === fallback,
|
||||
),
|
||||
).toEqual([]);
|
||||
},
|
||||
);
|
||||
|
||||
it("keeps the default copy for a code it does not know", () => {
|
||||
expect(validationMessage("SOME_FUTURE_CODE")).toBe(
|
||||
formatMessage("ko-KR", "form.validation.unknown"),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("dirty navigation guard", () => {
|
||||
it("blocks navigation, restores focus on stay and proceeds explicitly", async () => {
|
||||
const user = userEvent.setup();
|
||||
|
||||
Reference in New Issue
Block a user