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

#### ✅ 올바른 방법 (Enum 필드)
```typescript
// 부품 유형 등
partType: z.preprocess(
  (val) => val === undefined || val === null ? "" : val,
  z.string()
    .min(1, '부품 유형을 선택해주세요')
    .refine(
      (val) => ['ASSEMBLY', 'BENDING', 'PURCHASED'].includes(val),
      { message: '부품 유형을 선택해주세요' }
    )
)
```

#### ❌ 잘못된 방법
```typescript
// 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()` 사용

#### ✅ 올바른 방법
```typescript
// 제품(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()` 로 필드 오버라이드

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

---

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

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

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

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

#### ✅ 올바른 방법
```typescript
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'],
        });
      }
      // ... 다른 필수 필드들
    }
  });
```

#### ❌ 잘못된 방법
```typescript
// .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를 제거합니다!**

```typescript
// ❌ 잘못된 패턴 - 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()` 순서

#### ✅ 올바른 방법
```typescript
// 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되어 있음
  // ...
]);
```

#### ❌ 잘못된 방법들
```typescript
// 방법 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 스키마에서 다른 필드명을 사용**

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

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

### 해결 방법: 필드명 통일

#### ✅ 올바른 방법
```typescript
// 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. **필드명 불일치 찾기**:
   ```bash
   # 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 컴포넌트의 다른 이벤트 핸들러에서 동일한 필드를 자동 설정**

```typescript
// ❌ 품목명 선택 시 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 체크로 진행 → 에러 발생!
```

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

#### ✅ 올바른 방법
```typescript
// 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로 필드 값 확인**:
   ```typescript
   .superRefine((data, ctx) => {
     console.log('🔍 검증 시작:', {
       category2: data.category2,
       category2Type: typeof data.category2,
     });
   })
   ```

2. **Form 컴포넌트에서 setValue 호출 검색**:
   ```bash
   # 동일한 필드를 여러 곳에서 설정하는지 확인
   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) 스키마 완성본

```typescript
// 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 필드가 비어있지 않다고 판단하여 필수 검증 통과

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

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

#### ✅ 올바른 방법
```typescript
// 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', '');
  // ...
};
```

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

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

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

#### ✅ 올바른 방법
```typescript
{/* 단위 필드 */}
<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()로 완전히 새로 정의

#### ✅ 올바른 방법
```typescript
// 원자재/부자재 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(),
});
```

#### ❌ 잘못된 방법
```typescript
// .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`
- `/src/components/items/ItemForm.tsx`
- `/src/types/item.ts`