sam-react-prod/claudedocs/guides/[GUIDE] ZOD-VALIDATION-TROUBLESHOOTING.md

Zod Validation 문제 해결 가이드

문제 1: 영어 에러 메시지 표시

증상

• 필수 필드 미입력 시 영어 에러 메시지 표시
• 예: "Invalid input: expected string, received undefined"
• 예: "Invalid option: expected one of 'ASSEMBLY'|'BENDING'|'PURCHASED'"

원인

• z.string() 또는 z.enum()에 undefined 값이 들어오면 타입 체크가 먼저 실행됨
• 커스텀 한글 에러 메시지 전에 Zod 내부 타입 에러가 먼저 발생

해결 방법: z.preprocess() 패턴 사용

✅ 올바른 방법 (String 필드)

// 상품명, 품목명 등
const fieldSchema = z.preprocess(
  (val) => val === undefined || val === null ? "" : val,
  z.string().min(1, '필드명을 입력해주세요').max(200, '최대 200자')
);

✅ 올바른 방법 (Enum 필드)

// 부품 유형 등
partType: z.preprocess(
  (val) => val === undefined || val === null ? "" : val,
  z.string()
    .min(1, '부품 유형을 선택해주세요')
    .refine(
      (val) => ['ASSEMBLY', 'BENDING', 'PURCHASED'].includes(val),
      { message: '부품 유형을 선택해주세요' }
    )
)

❌ 잘못된 방법

// z.enum()은 undefined 처리 못 함
partType: z.enum(['ASSEMBLY', 'BENDING', 'PURCHASED'], {
  errorMap: () => ({ message: '부품 유형을 선택해주세요' }),
})

// .default()는 .min() 전에 사용 불가
z.string().default("").min(1, 'message') // Syntax Error!

---

문제 2: 불필요한 필드 검증으로 다중 에러 발생

증상

• 특정 품목 유형(FG, PT 등)에 없는 필드가 검증되어 에러 발생
• 예: 제품(FG)에 가격 필드 없는데 가격 필드 검증 에러 7개 발생

원인

• itemMasterBaseSchema를 모든 품목 유형이 공유
• 특정 유형에 없는 필드도 스키마에 포함되어 검증됨

해결 방법: .omit() 사용

✅ 올바른 방법

// 제품(FG) - 가격 정보 제거
const productSchemaBase = itemMasterBaseSchema
  .omit({
    purchasePrice: true,
    salesPrice: true,
    processingCost: true,
    laborCost: true,
    installCost: true,
  })
  .merge(productFieldsSchema);

---

문제 3: 공통 필수 필드가 특정 유형에서 불필요

증상

• itemMasterBaseSchema의 itemName이 필수인데, 부품(PT)은 category1을 사용
• 부품 유형만 선택 안 해도 "품목명을 입력해주세요" 에러 발생

원인

• itemMasterBaseSchema에서 itemName: itemNameSchema (필수)
• 부품(PT)은 itemName 사용 안 하고 category1 사용

해결 방법: .extend() 로 필드 오버라이드

✅ 올바른 방법

// 부품(PT) - itemName을 선택 사항으로 변경
const partSchemaBase = itemMasterBaseSchema
  .extend({
    itemName: z.string().max(200).optional(), // 필수 → 선택
  })
  .merge(partFieldsSchema);

---

문제 4: 단계별 검증 (조건부 필드 검증)

증상

• 사용자 화면에 안 보이는 필드 에러가 알럿 카드에 표시됨
• 예: 부품 유형 선택 전인데 "품목명", "설치 유형" 등 에러 동시 발생

원인

• Zod의 .refine()은 모든 refinement를 순차 실행
• 조건 체크 없이 모든 필드 검증 시도

해결 방법: .superRefine() + early return

✅ 올바른 방법

export const partSchema = partSchemaBase
  .superRefine((data, ctx) => {
    // 1단계: 부품 유형 필수 체크
    if (!data.partType || data.partType === '') {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: '부품 유형을 선택해주세요',
        path: ['partType'],
      });
      return; // 여기서 검증 중단 - 더 이상 체크 안 함
    }

    // 2단계: 부품 유형이 있을 때만 품목명 체크
    if (!data.category1) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: '품목명을 선택해주세요',
        path: ['category1'],
      });
    }

    // 3단계: 특정 부품 유형에만 해당하는 필드
    if (data.partType === 'ASSEMBLY') {
      if (!data.installationType) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          message: '설치 유형을 선택해주세요',
          path: ['installationType'],
        });
      }
      // ... 다른 필수 필드들
    }
  });

❌ 잘못된 방법

// .refine()은 모든 체크를 실행함
.refine((data) => !!data.partType, { ... })
.refine((data) => !!data.category1, { ... }) // partType 없어도 실행됨!
.refine((data) => {
  if (data.partType === 'ASSEMBLY') {
    return !!data.installationType; // partType 없어도 실행됨!
  }
  return true;
}, { ... })

---

문제 5: .omit() + .extend() + .superRefine() 조합 시 refinement 유실

증상

• validation.ts에서 superRefine() 작성했는데 적용 안 됨
• 여전히 단계별 검증이 작동하지 않음
• Console.log도 나타나지 않아 superRefine 자체가 실행되지 않음

원인

CRITICAL: .omit()은 refinement를 제거합니다!

// ❌ 잘못된 패턴 - refinement가 유실됨
const partSchemaForForm = partSchemaBase
  .omit({ createdAt: true, updatedAt: true })
  .superRefine((data, ctx) => { /* 이 부분이 실행 안 됨! */ });

// discriminatedUnion에서 사용
partSchemaForForm.extend({ itemType: z.literal('PT') })
// → Error: "Object schemas containing refinements cannot be extended"

추가 문제: .extend()도 refinement가 있는 스키마에 사용 불가

해결 방법: .omit() → .merge() → .superRefine() 순서

✅ 올바른 방법

// 1. omit으로 불필요한 필드 제거
// 2. merge로 itemType 추가
// 3. superRefine을 마지막에 적용 (핵심!)
const partSchemaForForm = partSchemaBase
  .omit({ createdAt: true, updatedAt: true })
  .merge(z.object({ itemType: z.literal('PT') }))
  .superRefine((data, ctx) => {
    // 이제 이 부분이 실행됨!
    if (!data.partType || data.partType === '') {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: '부품 유형을 선택해주세요',
        path: ['partType'],
      });
      return;
    }

    if (!data.category1 || data.category1 === '') {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: '품목명을 선택해주세요',
        path: ['category1'],
      });
    }
  });

// discriminatedUnion에서는 그대로 사용
export const createItemFormSchema = z.discriminatedUnion('itemType', [
  productSchema.omit({ createdAt: true, updatedAt: true }).extend({ itemType: z.literal('FG') }),
  partSchemaForForm, // itemType이 이미 merge되어 있음
  // ...
]);

❌ 잘못된 방법들

// 방법 1: superRefine을 merge 전에 적용
const wrong1 = partSchemaBase
  .omit({ ... })
  .superRefine((data, ctx) => { /* 실행 안 됨 */ })
  .merge(z.object({ itemType: z.literal('PT') })); // merge가 refinement 덮어씀

// 방법 2: extend 사용
const wrong2 = partSchemaBase
  .omit({ ... })
  .superRefine((data, ctx) => { /* ... */ })
  .extend({ itemType: z.literal('PT') }); // Error!

// 방법 3: discriminatedUnion에서 다시 extend
partSchemaForForm.extend({ itemType: z.literal('PT') }) // Error!

핵심 원칙

1. .omit()은 항상 refinement를 제거함 - 순서 상관없음
2. refinement는 항상 마지막에 적용 - .merge() 이후
3. .extend()는 refinement 있는 스키마에 사용 불가 - .merge() 사용
4. discriminatedUnion에서는 완성된 스키마 사용 - 추가 merge/extend 없이

---

문제 6: Form과 Validation의 필드명 불일치

증상

• superRefine에서 early return을 사용했는데도 하위 필드 에러가 계속 나타남
• Console.log에서 superRefine이 실행되지만, 체크하는 필드가 항상 undefined
• 예: 절곡(BENDING) 부품에서 "종류" 선택 안 해도 "재질", "폭 합계", "모양&길이" 에러 발생

원인

Form 컴포넌트와 Validation 스키마에서 다른 필드명을 사용

// ❌ ItemForm.tsx에서
setValue('category3', selected.code); // category3에 저장

// ❌ validation.ts에서
if (!data.category2 || data.category2 === '') { // category2 체크
  // category3에 값이 있는데 category2를 체크하니까 항상 undefined!
}

해결 방법: 필드명 통일

✅ 올바른 방법

// ItemForm.tsx - 필드명을 validation과 동일하게
setValue('category2', selected.code); // category3 → category2로 수정
clearErrors('category2');

// validation.ts - 동일한 필드명 사용
if (!data.category2 || data.category2 === '') {
  ctx.addIssue({
    code: z.ZodIssueCode.custom,
    message: '종류를 선택해주세요',
    path: ['category2'], // 필드명 일치
  });
  return;
}

디버깅 방법

1. Form에서 setValue 호출 확인:

   • 어떤 필드명으로 값을 설정하는지 확인
   • 예: setValue('category2', value) 또는 setValue('category3', value)

2. Validation에서 체크하는 필드명 확인:

   • superRefine 내부에서 data.xxx 형태로 체크하는 필드명 확인
   • Console.log로 실제 값 확인: console.log('category2:', data.category2, 'category3:', data.category3)

3. 필드명 불일치 찾기:

   # Form 컴포넌트에서 setValue 사용 찾기
   grep -n "setValue('category" src/components/items/ItemForm.tsx
   
   # Validation에서 category 필드 체크 찾기
   grep -n "data.category" src/lib/utils/validation.ts
   

예방 방법

• Type 정의 파일 활용: /src/types/item.ts에서 필드명을 명확히 정의
• 일관된 네이밍: category1 (품목명), category2 (종류), category3 (하위 분류) 등 명확한 규칙
• 코드 리뷰: Form과 Validation 수정 시 필드명 일치 여부 확인

---

문제 7: Form에서 다른 곳에서 필드 값 자동 설정

증상

• Validation에서 early return을 사용했는데도 하위 필드 에러 발생
• Console.log에서 필드 값이 예상과 다르게 이미 설정되어 있음
• 예: BENDING 부품에서 "종류" 선택 안 했는데 category2: 'R'로 이미 설정됨

원인

Form 컴포넌트의 다른 이벤트 핸들러에서 동일한 필드를 자동 설정

// ❌ 품목명 선택 시 category2 자동 설정 (모든 부품 유형에서)
onValueChange={(val) => {
  setSelectedCategory1(val);
  setValue('category1', val);
  const cat = PART_TYPE_CATEGORIES[selectedPartType]?.categories.find(c => c.value === val);
  if (cat) setValue('category2', cat.code); // BENDING에서도 실행됨!
}}

// validation.ts에서
if (!data.category2 || data.category2 === '') {
  // category2가 이미 'R'로 설정되어 있어서 이 체크를 통과
  return;
}
// 그래서 material 체크로 진행 → 에러 발생!

해결 방법: 조건부 자동 설정

✅ 올바른 방법

// ItemForm.tsx - 특정 부품 유형에서만 자동 설정
onValueChange={(val) => {
  setSelectedCategory1(val);
  setValue('category1', val);
  const cat = PART_TYPE_CATEGORIES[selectedPartType]?.categories.find(c => c.value === val);

  // BENDING이 아닐 때만 category2 자동 설정 (BENDING은 별도로 "종류" 선택)
  if (cat && selectedPartType !== 'BENDING') {
    setValue('category2', cat.code);
  }
}}

// BENDING 부품의 "종류" 선택에서만 category2 설정
onValueChange={(value) => {
  setSelectedBendingItemType(value);
  const selected = PART_ITEM_NAMES[selectedCategory1].find(item => item.label === value);
  if (selected) {
    setValue('category2', selected.code); // 여기서만 설정
    clearErrors('category2');
  }
}}

디버깅 방법

1. Console.log로 필드 값 확인:

   .superRefine((data, ctx) => {
     console.log('🔍 검증 시작:', {
       category2: data.category2,
       category2Type: typeof data.category2,
     });
   })
   

2. Form 컴포넌트에서 setValue 호출 검색:

   # 동일한 필드를 여러 곳에서 설정하는지 확인
   grep -n "setValue('category2'" src/components/items/ItemForm.tsx
   

3. 예상치 못한 값 발견 시:

   • 해당 필드를 설정하는 모든 위치 확인
   • 각 위치에서 조건부 설정이 필요한지 판단
   • 부품 유형에 따라 다른 로직 적용

예방 방법

• 명확한 필드 책임 분리: 각 필드는 한 곳에서만 설정되도록
• 조건부 설정 명시: if (partType === 'SPECIFIC') 조건 명확히
• Console.log 디버깅: 문제 발생 시 실제 값 확인 습관화
• 필드 초기화: 부품 유형 변경 시 관련 필드 모두 초기화

---

체크리스트

필수 필드 추가 시

• z.preprocess() 패턴으로 undefined → "" 변환
• .min(1, '한글 메시지') 사용
• enum 타입은 .refine() + array.includes() 패턴

품목 유형별 스키마 작성 시

• 해당 유형에 없는 필드는 .omit() 제거
• 공통 필수 필드가 불필요하면 .extend() 오버라이드
• refinement 작성 후 createItemFormSchema에서 사용

조건부 검증 작성 시

• .superRefine() 사용
• 필수 선행 조건 체크 후 return으로 중단
• 특정 값일 때만 검증하는 필드는 if (data.field === 'VALUE') 체크

---

실전 예제: 부품(PT) 스키마 완성본

// 1. 부품 전용 필드 정의
const partFieldsSchema = z.object({
  partType: z.preprocess(
    (val) => val === undefined || val === null ? "" : val,
    z.string()
      .min(1, '부품 유형을 선택해주세요')
      .refine(
        (val) => ['ASSEMBLY', 'BENDING', 'PURCHASED'].includes(val),
        { message: '부품 유형을 선택해주세요' }
      )
  ),
  // ... 기타 선택 필드들
});

// 2. Base 스키마 - itemName 제거
const partSchemaBase = itemMasterBaseSchema
  .extend({
    itemName: z.string().max(200).optional(),
  })
  .merge(partFieldsSchema);

// 3. Refinement 스키마 - 단계별 검증
export const partSchema = partSchemaBase
  .superRefine((data, ctx) => {
    // 1단계: 부품 유형 필수
    if (!data.partType || data.partType === '') {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: '부품 유형을 선택해주세요',
        path: ['partType'],
      });
      return; // 검증 중단
    }

    // 2단계: 품목명 필수
    if (!data.category1) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: '품목명을 선택해주세요',
        path: ['category1'],
      });
    }

    // 3단계: 조립 부품 전용
    if (data.partType === 'ASSEMBLY') {
      if (!data.installationType) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          message: '설치 유형을 선택해주세요',
          path: ['installationType'],
        });
      }
      // ... 기타 필수 필드
    }

    // 절곡품 전용
    if (data.partType === 'BENDING') {
      // ...
    }

    // 구매 부품 전용
    if (data.partType === 'PURCHASED') {
      // ...
    }
  });

// 4. 폼 스키마 - .omit() + .merge() + .superRefine() 패턴 적용
const partSchemaForForm = partSchemaBase
  .omit({ createdAt: true, updatedAt: true })
  .merge(z.object({ itemType: z.literal('PT') }))
  .superRefine((data, ctx) => {
    // refinement 로직 (위와 동일)
  });

export const createItemFormSchema = z.discriminatedUnion('itemType', [
  productSchema.omit({ createdAt: true, updatedAt: true }).extend({ itemType: z.literal('FG') }),
  partSchemaForForm, // refinement가 마지막에 적용된 완성 스키마
  // ...
]);

---

디버깅 팁

영어 에러 메시지가 나올 때

1. 해당 필드가 z.preprocess() 사용하는지 확인
2. undefined → "" 변환 로직 있는지 확인
3. enum 타입이면 .refine() 패턴으로 변경

불필요한 필드 에러가 나올 때

1. 해당 품목 유형 스키마에서 .omit() 사용했는지 확인
2. itemMasterBaseSchema의 필수 필드를 .extend() 오버라이드 했는지 확인

단계별 검증이 안 될 때

1. .superRefine() 사용했는지 확인
2. 선행 조건 체크 후 return 있는지 확인
3. createItemFormSchema에서 refinement 포함 스키마 사용하는지 확인
4. CRITICAL: .superRefine()이 .merge() 이후에 적용되었는지 확인
5. Console.log 추가해서 superRefine이 실행되는지 확인
6. .omit() 사용했다면 반드시 refinement를 마지막에 다시 적용
7. CRITICAL: Form과 Validation의 필드명 일치 확인!
   • Form에서 setValue('category3', value)인데 validation에서 data.category2 체크하면 안 됨
   • 두 곳의 필드명이 정확히 일치해야 함
8. CRITICAL: Console.log로 실제 필드 값 확인 - 예상과 다른 값이 이미 설정되어 있는지
   • 다른 이벤트 핸들러에서 동일한 필드를 자동 설정하고 있는지 확인
   • grep -n "setValue('필드명'" src/components/items/ItemForm.tsx로 모든 설정 위치 확인

---

문제 8: 필드가 자동으로 채워져서 필수 검증이 작동하지 않음

증상

• 부자재/원자재/소모품(SM/RM/CS) 선택 후 바로 저장 시 단위(unit) 필수 에러가 발생하지 않음
• 에러 카드에 "품목명, 규격" 2개만 표시되고 "단위"는 누락됨
• Zod 스키마에서는 unit을 필수로 정의했는데 검증이 안 됨

원인

• ItemForm.tsx의 handleItemTypeChange 함수에서 모든 품목 유형에 대해 setValue('unit', 'EA') 실행
• 부자재/원자재/소모품을 선택해도 unit 필드에 자동으로 'EA'가 설정됨
• Zod validation에서 unit 필드가 비어있지 않다고 판단하여 필수 검증 통과

진단 방법

# ItemForm에서 해당 필드를 설정하는 모든 위치 찾기
grep -n "setValue('unit'" src/components/items/ItemForm.tsx

해결 방법 1: 조건부 초기화

✅ 올바른 방법

// ItemForm.tsx - handleItemTypeChange 함수
const handleItemTypeChange = (type: ItemType) => {
  setSelectedItemType(type);
  setValue('itemType', type);

  // react-hook-form 필드 초기화
  setValue('itemCode', '');
  setValue('itemName', '');
  // SM/RM/CS는 unit 필수이므로 빈 문자열로 초기화, FG/PT는 'EA'
  setValue('unit', (type === 'SM' || type === 'RM' || type === 'CS') ? '' : 'EA');
  setValue('specification', '');
  // ...
};

❌ 잘못된 방법

// 모든 품목 유형에 동일한 기본값 설정
setValue('unit', 'EA'); // ← SM/RM/CS도 'EA'가 들어가서 필수 검증 안 됨!

해결 방법 2: UI 에러 표시 추가

필드에 에러가 있을 때 빨간 테두리와 메시지를 표시해야 사용자가 알 수 있음

✅ 올바른 방법

{/* 단위 필드 */}
<Select
  value={selectedUnit}
  onValueChange={(value) => {
    setSelectedUnit(value);
    setValue('unit', value);
  }}
>
  <SelectTrigger id="unit" className={errors.unit ? 'border-red-500' : ''}>
    <SelectValue placeholder="단위를 선택하세요" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="EA">EA (개)</SelectItem>
    {/* ... */}
  </SelectContent>
</Select>
{errors.unit && (
  <p className="text-xs text-red-500 mt-1">
    {errors.unit.message}
  </p>
)}

해결 방법 3: z.object()로 완전히 새로 정의

.extend()나 .omit()이 제대로 작동하지 않을 때는 z.object()로 완전히 새로 정의

✅ 올바른 방법

// 원자재/부자재 Base 스키마
const materialSchemaBase = z.object({
  // 공통 필수 필드
  itemCode: z.string().optional(),
  itemName: itemNameSchema,
  itemType: itemTypeSchema,
  specification: materialSpecificationSchema, // 필수!
  unit: materialUnitSchema, // 필수!
  isActive: z.boolean().default(true),

  // ... 나머지 모든 필드 명시적으로 정의

  // 원자재/부자재 전용 필드
  material: z.string().max(100).optional(),
  length: z.string().max(50).optional(),
});

❌ 잘못된 방법

// .extend()만으로 오버라이드 시도 (작동하지 않을 수 있음)
const materialSchemaBase = itemMasterBaseSchema
  .merge(materialFieldsSchema)
  .extend({
    specification: materialSpecificationSchema, // optional이 그대로 남을 수 있음
    unit: materialUnitSchema, // optional이 그대로 남을 수 있음
  });

교훈

1. Form의 자동 설정 확인: 필수 검증이 안 되면 Form에서 해당 필드를 자동으로 채우고 있는지 확인
2. 조건부 초기화: 품목 유형마다 다른 기본값이 필요하면 조건부로 설정
3. UI 피드백: Validation 에러를 사용자가 볼 수 있도록 필드에 직접 표시
4. 명시적 정의: .extend()가 작동하지 않으면 z.object()로 완전히 새로 정의

---

작성일

2025-11-15

최종 수정일

2025-11-15

작성자

Claude Code

관련 파일

프론트엔드

• src/lib/utils/validation.ts - Zod 유효성 검증 스키마 정의
• src/components/items/ItemForm.tsx - 품목 등록/수정 폼 컴포넌트
• src/types/item.ts - 품목 타입 정의

참조 문서

• claudedocs/guides/[IMPL-2025-11-07] form-validation-guide.md - 폼 및 유효성 검증 가이드