{stat.value}
+``` + +**Next.js**: +```tsx +{stat.value}
+``` + +❌ 불일치: text-3xl md:text-4xl 누락 +``` + +**최종 빌드 검증**: +```bash +npm run build +``` + +--- + +## Phase 3: 섹션 통합 검증 + +모든 섹션 완료 후: +1. [ ] 전체 페이지 빌드 성공 +2. [ ] 모든 기능 정상 동작 +3. [ ] React와 시각적 차이 없음 +4. [ ] 반응형 동작 확인 (모바일, 태블릿, 데스크톱) + +--- + +## 실전 예시: ItemManagement (2600줄) + +### 파일 분석 +``` +파일: ItemManagement.tsx +크기: 2,600줄 +전략: 섹션별 분해 (5개 섹션) +``` + +### 섹션 분해 계획 +| 섹션 | 라인 | 복잡도 | 체크포인트 | +|------|------|--------|-----------| +| Header | 1899-1917 | 낮음 | 6개 | +| StatCards | 1790-1816, 1920 | 낮음 | 8개 | +| SearchFilter | 1929-1950 | 중간 | 10개 | +| Tabs+Table | 1956-2300 | 높음 | 15개 | +| DetailView | 2300-2900 | 매우 높음 | 20개 | + +### 작업 진행 +``` +✅ 1회차: Header (6단계 완료, 검증 통과) +✅ 2회차: StatCards (6단계 완료, 검증 통과) +✅ 3회차: SearchFilter (6단계 완료, 검증 통과) +🔄 4회차: Tabs+Table (진행 중...) +⏳ 5회차: DetailView (대기 중) +``` + +--- + +## 예상되는 실수 패턴 및 방지법 + +### 실수 1: 텍스트 사이즈 불일치 +**증상**: `text-2xl` vs `text-3xl md:text-4xl` +**원인**: 체크리스트에서 반응형 클래스 누락 +**방지**: 모든 `md:`, `lg:` 클래스도 체크리스트에 명시 + +### 실수 2: font-bold 유무 +**증상**: 타이틀에 bold가 있어야 하는데 없거나, 없어야 하는데 있거나 +**원인**: 부정 체크(❌)를 체크리스트에 안 적음 +**방지**: "없어야 할 클래스"도 `font-bold ❌` 형태로 명시 + +### 실수 3: opacity, shadow 같은 미세 스타일 +**증상**: `opacity-15` vs `opacity-20`, `shadow-sm` vs `shadow-md` +**원인**: 숫자까지 정확히 확인 안 함 +**방지**: 체크리스트에 정확한 값까지 기록 + +### 실수 4: 컴포넌트 variant 불일치 +**증상**: `variant="default"` vs `variant="secondary"` +**원인**: Props도 CSS처럼 체크해야 함 +**방지**: variant, size 같은 Props도 체크리스트에 포함 + +--- + +## 워크플로우 메타 규칙 + +### 언제 이 워크플로우를 사용하는가? +1. 사용자가 "React와 똑같이" 요청 +2. 파일이 1000줄 이상 +3. 이전에 디테일을 놓친 경험이 있을 때 +4. 사용자가 "체크리스트 방식으로" 명시 + +### 언제 사용하지 않는가? +1. 간단한 버그 수정 (<50줄) +2. 새로운 기능 추가 (참조할 React 코드 없음) +3. 리팩토링 작업 +4. 사용자가 "대략적으로만" 요청 + +### 워크플로우 적용 선언 +작업 시작 시 사용자에게 명시: +``` +📋 대용량 파일 워크플로우 적용 + +파일: ItemCreate.tsx (1,200줄) +전략: 4개 섹션으로 분해 +예상 시간: 40분 + +Section 1: FormHeader (진행 중...) +``` + +--- + +--- + +## Phase 4: 복잡한 다중 작업 처리 프로토콜 + +### 개요 +사용자가 여러 요구사항을 한 번에 제시할 때 누락 없이 체계적으로 처리하는 프로세스 + +### 트리거 조건 +다음 중 하나라도 해당되면 이 프로토콜 적용: +- ✅ 3개 이상의 독립적인 수정 요청 +- ✅ 여러 파일/섹션에 걸친 작업 +- ✅ 복잡한 로직 변경 + UI 수정 혼재 +- ✅ 사용자가 "여러 개 한번에" 또는 "전체적으로" 요청 + +### Step 1: TodoWrite로 작업 분해 및 체크리스트 생성 + +**원칙**: +- 모든 요구사항을 독립적인 태스크로 분해 +- 각 태스크는 검증 가능한 단위로 작성 +- 작업 순서를 논리적으로 정렬 (의존성 고려) + +**예시 입력**: +``` +사용자: "구매부품 화면을 다음과 같이 수정해줘: +1. 품목명 선택 시 전원, 용량, 단위, 비고 표시 +2. 전동개폐기는 220V/380V 선택 +3. 모터는 용량 입력 + 전압 선택 +4. 체인은 규격 선택 + 길이 입력 +5. 품목코드 자동생성 로직 변경 +6. 품목 상태를 품목코드 다음으로 이동" +``` + +**TodoWrite 출력**: +```typescript +[ + { + content: "요구사항 분석 및 파일 구조 파악", + status: "in_progress", + activeForm: "요구사항 분석 중" + }, + { + content: "품목명 선택 로직 확인 (기존 코드)", + status: "pending", + activeForm: "품목명 선택 로직 확인 중" + }, + { + content: "전원, 용량, 단위, 비고 필드 추가", + status: "pending", + activeForm: "필드 추가 중" + }, + { + content: "전동개폐기 전용 220V/380V 선택 구현", + status: "pending", + activeForm: "전동개폐기 필드 구현 중" + }, + { + content: "모터 전용 용량 입력 + 전압 선택 구현", + status: "pending", + activeForm: "모터 필드 구현 중" + }, + { + content: "체인 전용 규격 선택 + 길이 입력 구현", + status: "pending", + activeForm: "체인 필드 구현 중" + }, + { + content: "품목코드 자동생성 함수 수정", + status: "pending", + activeForm: "품목코드 로직 수정 중" + }, + { + content: "품목 상태 기존 위치 제거", + status: "pending", + activeForm: "품목 상태 제거 중" + }, + { + content: "품목 상태 새 위치(품목코드 다음)에 추가", + status: "pending", + activeForm: "품목 상태 추가 중" + }, + { + content: "전체 동작 검증 및 빌드 테스트", + status: "pending", + activeForm: "검증 중" + } +] +``` + +### Step 2: 순차적 실행 및 진행상황 업데이트 + +**실행 규칙**: +1. **한 번에 하나씩**: 절대 여러 태스크를 동시에 처리하지 않음 +2. **완료 후 체크**: 각 태스크 완료 즉시 TodoWrite 업데이트 +3. **명시적 보고**: "✅ N번 완료, 다음 N+1번 시작" 형태로 진행상황 공유 +4. **에러 처리**: 실패 시 즉시 보고, 해결 후 재개 + +**실행 흐름**: +``` +1. Task 1 시작 + → TodoWrite: status="in_progress" + → 작업 수행 + → 검증 + → TodoWrite: status="completed" + → 사용자에게 "✅ 1번 완료" 보고 + +2. Task 2 시작 + → TodoWrite: status="in_progress" + → 작업 수행 + ... +``` + +### Step 3: 중간 체크포인트 제시 + +**5개 태스크마다 중간 보고**: +```markdown +## 진행상황 (5/10 완료) + +✅ 완료: +1. 요구사항 분석 및 파일 구조 파악 +2. 품목명 선택 로직 확인 +3. 전원, 용량, 단위, 비고 필드 추가 +4. 전동개폐기 전용 필드 구현 +5. 모터 전용 필드 구현 + +🔄 진행 중: +6. 체인 전용 필드 구현 + +⏳ 대기 중: +7. 품목코드 자동생성 함수 수정 +8. 품목 상태 기존 위치 제거 +9. 품목 상태 새 위치 추가 +10. 전체 검증 +``` + +### Step 4: 최종 완료 보고서 + +**모든 태스크 완료 후**: +```markdown +## ✅ 전체 작업 완료 + +### 완료된 작업 요약 +1. ✅ 품목명 선택 시 전원, 용량, 단위, 비고 표시 (line 990-1122) +2. ✅ 전동개폐기 220V/380V 선택 구현 (line 990-1032) +3. ✅ 모터 용량 입력 + 전압 선택 구현 (line 1035-1057) +4. ✅ 체인 규격 선택 + 길이 입력 구현 (line 1060-1084) +5. ✅ 품목코드 자동생성 로직 변경 (line 248-305) +6. ✅ 품목 상태 이동 완료 (line 1138-1159) + +### 최종 확인사항 +- [x] 품목명 미선택 시: 품목명만 표시 +- [x] 전동개폐기 선택 시: 전원, 용량 정상 표시 +- [x] 모터 선택 시: 용량 입력, 전압 선택 정상 표시 +- [x] 체인 선택 시: 규격, 길이 정상 표시 +- [x] 품목코드 자동생성 정상 작동 +- [x] 품목 상태가 품목코드 다음에 위치 +- [x] 빌드 에러 없음 + +### 변경된 파일 +- `src/components/items/ItemForm.tsx` (6개 섹션 수정) + +### 다음 작업 대기 +모든 요구사항이 완료되었습니다. 추가 작업이 있으면 알려주세요. +``` + +### 실전 적용 예시 + +**Before (기존 방식 - 누락 발생)**: +``` +사용자: A, B, C, D 수정해줘 +AI: (A만 수정하고 B, C, D 누락) +``` + +**After (새 프로토콜 - 완벽 처리)**: +``` +사용자: A, B, C, D 수정해줘 + +AI: +[TodoWrite 생성] +1. [ ] A 수정 +2. [ ] B 수정 +3. [ ] C 수정 +4. [ ] D 수정 + +✅ 1/4 완료: A 수정 완료 (line 100-120) +✅ 2/4 완료: B 수정 완료 (line 200-250) +✅ 3/4 완료: C 수정 완료 (line 300-350) +✅ 4/4 완료: D 수정 완료 (line 400-450) + +## 전체 작업 완료 보고서 +[상세 내용...] +``` + +### 프로토콜 적용 기준 + +| 작업 복잡도 | 요구사항 수 | TodoWrite 사용 | 중간 보고 | +|------------|-----------|--------------|----------| +| 단순 (1-2개) | 1-2개 | 선택사항 | 불필요 | +| 보통 (3-5개) | 3-5개 | 필수 | 권장 | +| 복잡 (6개+) | 6개 이상 | 필수 | 필수 | + +### 예외 처리 + +**태스크 실패 시**: +```markdown +❌ 3/10 실패: 모터 필드 구현 중 에러 발생 + +**에러 내용**: +- TypeScript 타입 불일치 (line 1045) + +**해결 방안**: +1. 타입 정의 확인 +2. 수정 후 재시도 + +🔄 재시도 중... +✅ 3/10 완료: 모터 필드 구현 성공 +``` + +**의존성 문제 발견 시**: +```markdown +⚠️ 태스크 순서 변경 필요 + +**발견된 문제**: +- Task 5가 Task 3에 의존함 + +**재정렬**: +1. [x] Task 1 +2. [x] Task 2 +3. [ ] Task 3 (우선 처리) +4. [ ] Task 4 +5. [ ] Task 5 (Task 3 완료 후) +``` + +--- + +## 버전 히스토리 +- v1.0.0 (2025-01-14): 초기 버전 생성 +- 이유: ItemListClient 작업 시 text-2xl/text-3xl, font-bold 같은 미세한 차이 놓침 +- 목적: 체계적이고 완벽한 React → Next.js 마이그레이션 +- v1.1.0 (2025-01-15): Phase 4 추가 - 복잡한 다중 작업 처리 프로토콜 +- 이유: 여러 요구사항 동시 처리 시 누락 발생 방지 +- 목적: TodoWrite 기반 체계적 작업 분해 및 순차 실행 diff --git a/docs/[GUIDE] ZOD-VALIDATION-TROUBLESHOOTING.md b/docs/[GUIDE] ZOD-VALIDATION-TROUBLESHOOTING.md new file mode 100644 index 00000000..1cbdef75 --- /dev/null +++ b/docs/[GUIDE] ZOD-VALIDATION-TROUBLESHOOTING.md @@ -0,0 +1,662 @@ +# 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 +{/* 단위 필드 */} + +{errors.unit && ( ++ {errors.unit.message} +
+)} +``` + +### 해결 방법 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` \ No newline at end of file diff --git a/docs/[IMPL-2025-11-06] i18n-usage-guide.md b/docs/[IMPL-2025-11-06] i18n-usage-guide.md new file mode 100644 index 00000000..035893c1 --- /dev/null +++ b/docs/[IMPL-2025-11-06] i18n-usage-guide.md @@ -0,0 +1,738 @@ +# next-intl 다국어 설정 가이드 + +## 개요 + +이 문서는 Next.js 16 기반 멀티 테넌트 ERP 시스템의 다국어(i18n) 설정 및 사용법을 설명합니다. `next-intl` 라이브러리를 활용하여 한국어(ko), 영어(en), 일본어(ja) 3개 언어를 지원합니다. + +--- + +## 📦 설치된 패키지 + +```json +{ + "dependencies": { + "next-intl": "^latest" + } +} +``` + +--- + +## 🏗️ 프로젝트 구조 + +``` +src/ +├── i18n/ +│ ├── config.ts # i18n 설정 (지원 언어, 기본 언어) +│ └── request.ts # 서버사이드 메시지 로딩 +├── messages/ +│ ├── ko.json # 한국어 메시지 +│ ├── en.json # 영어 메시지 +│ └── ja.json # 일본어 메시지 +├── app/ +│ └── [locale]/ # 동적 로케일 라우팅 +│ ├── layout.tsx # 루트 레이아웃 (NextIntlClientProvider) +│ └── page.tsx # 홈 페이지 +├── components/ +│ ├── LanguageSwitcher.tsx # 언어 전환 컴포넌트 +│ ├── WelcomeMessage.tsx # 번역 샘플 컴포넌트 +│ └── NavigationMenu.tsx # 내비게이션 메뉴 컴포넌트 +└── middleware.ts # 로케일 감지 + 봇 차단 미들웨어 +``` + +--- + +## 🔧 핵심 설정 파일 + +### 1. i18n 설정 (`src/i18n/config.ts`) + +```typescript +export const locales = ['ko', 'en', 'ja'] as const; +export type Locale = (typeof locales)[number]; + +export const defaultLocale: Locale = 'ko'; + +export const localeNames: Record{t('appName')}
+{t('minLength', { min: 8 })}
+ // 출력: "최소 8자 이상 입력하세요" + ); +} +``` + +--- + +### 2. 서버 컴포넌트에서 사용 + +```typescript +import { useTranslations } from 'next-intl'; + +export default function ServerComponent() { + const t = useTranslations('common'); + + return ( +`${chunks}` }), + }} + /> + ); +} +``` + +--- + +### 2. 복수형 처리 + +```json +{ + "items": "{count, plural, =0 {항목 없음} =1 {1개 항목} other {#개 항목}}" +} +``` + +```typescript +const t = useTranslations(); + +
{t('items', { count: 0 })}
// "항목 없음" +{t('items', { count: 1 })}
// "1개 항목" +{t('items', { count: 5 })}
// "5개 항목" +``` + +--- + +### 3. 날짜 및 시간 포맷팅 + +```typescript +import { useFormatter } from 'next-intl'; + +export default function DateDisplay() { + const format = useFormatter(); + const date = new Date(); + + return ( +{format.dateTime(date, { dateStyle: 'full' })}
+{format.dateTime(date, { timeStyle: 'short' })}
+{format.number(price, { style: 'currency', currency: 'KRW' })}
+ {/* ₩1,234,568 */} + + {/* 퍼센트 */} +{format.number(0.85, { style: 'percent' })}
+ {/* 85% */} ++ {tValidation(error.message as any)} +
+ )} ++ {tValidation(error.message as any)} +
+ )} +{userName}
+{userPosition}
+에러 메시지: {error.message}
+스택 트레이스: {error.stack}
+일시적인 오류가 발생했습니다.
+ +