sam-react-prod/docs/[GUIDE] LARGE-FILE-WORKFLOW.md

# 대용량 파일 작업 워크플로우

## 개요
React → Next.js 디자인 마이그레이션 시 대용량 파일(>1000줄)을 체계적으로 처리하기 위한 프로토콜

## 트리거 조건
다음 조건 중 하나라도 해당되면 이 워크플로우를 적용:
- ✅ 파일 크기 >1000줄
- ✅ 여러 섹션/기능이 혼재된 복잡한 컴포넌트
- ✅ React → Next.js 디자인 정확 복제 작업
- ✅ 사용자가 명시적으로 "세밀한 작업" 또는 "정확한 복제" 요청

## Phase 1: 사전 분석 (Pre-Analysis)

### 1-1. 파일 크기 확인 및 전략 수립
```
<1000줄: 일반 접근 (전체 파일 한 번에 처리)
1000-3000줄: 섹션별 분해 (3-4개 섹션)
>3000줄: 기능별 분해 (1000줄 단위)
```

### 1-2. 섹션 식별 및 라인 범위 파악
React 파일을 읽고 주요 섹션 구분:
```markdown
## 섹션 분해 계획

| 섹션 | 라인 범위 | 예상 복잡도 | 체크포인트 수 |
|------|----------|------------|--------------|
| Header | 100-150 | 낮음 | 6개 |
| StatCards | 150-200 | 낮음 | 8개 |
| SearchFilter | 200-280 | 중간 | 10개 |
| Tabs+Table | 280-600 | 높음 | 15개 |
| DetailView | 600-1100 | 매우 높음 | 20개 |
```

## Phase 2: 섹션별 6단계 워크플로우

**각 섹션마다 순차적으로 아래 6단계 실행:**

### Step 1: 구조 파악 하기
**목적**: 컴포넌트의 구조적 뼈대 이해

**체크리스트**:
- [ ] 사용된 컴포넌트 목록 (Card, Button, Input 등)
- [ ] Props 구조 (어떤 데이터를 받는가)
- [ ] State 변수 (어떤 상태를 관리하는가)
- [ ] 자식 컴포넌트 계층 구조
- [ ] 조건부 렌더링 로직

**출력 포맷**:
```markdown
## [섹션명] 구조 분석

### 컴포넌트 구성
- 최상위: Card
- 자식: CardHeader, CardContent, Button

### Props
- items: ItemMaster[]
- onItemClick: (id: string) => void

### State
- selectedType: string
- searchTerm: string

### 조건부 렌더링
- filteredItems.length === 0 → 빈 상태 메시지
```

### Step 2: 기능 구현 하기
**목적**: 스타일 없이 순수 기능만 먼저 동작하게 만들기

**원칙**:
- ✅ 클릭 이벤트, 상태 변경 등 **동작**만 구현
- ❌ CSS 클래스는 최소한만 (레이아웃 깨지지 않을 정도)
- ✅ 데이터 바인딩, 필터링 로직 완성

**예시**:
```typescript
// ✅ 좋은 예: 기능만 구현
<div>
  <input
    value={searchTerm}
    onChange={(e) => setSearchTerm(e.target.value)}
  />
  <button onClick={handleCreate}>등록</button>
</div>

// ❌ 나쁜 예: 스타일까지 구현
<div className="flex items-center justify-between gap-4 p-6 rounded-lg shadow-md">
  <input
    className="text-sm border rounded px-3 py-2"
    value={searchTerm}
    onChange={(e) => setSearchTerm(e.target.value)}
  />
</div>
```

### Step 3: 기능 검증
**목적**: 스타일 전에 기능이 완벽히 동작하는지 확인

**검증 항목**:
- [ ] 클릭 이벤트가 정상 동작하는가
- [ ] 상태 변경이 UI에 반영되는가
- [ ] 데이터 필터링/정렬이 올바른가
- [ ] 조건부 렌더링이 정확한가
- [ ] 빌드 에러가 없는가

**검증 방법**:
```bash
npm run build  # 빌드 성공 확인
npm run dev    # 개발 서버로 동작 테스트
```

### Step 4: 스타일 파악 하기
**목적**: React 코드의 정확한 CSS 클래스 체크리스트 작성

**중요**: 이 단계가 가장 중요! 모든 CSS 클래스를 빠짐없이 기록

**체크리스트 작성 규칙**:
1. **계층 구조 유지**: 부모 → 자식 순서로 체크리스트 작성
2. **모든 클래스 기록**: text-*, font-*, bg-*, border-* 등 모든 클래스
3. **부정 체크**: `font-bold ❌`처럼 없어야 할 클래스도 명시
4. **반응형 포함**: `md:`, `lg:` 같은 반응형 클래스도 모두 기록

**체크리스트 템플릿**:
```markdown
## [섹션명] 스타일 체크리스트

### Container (최상위 div)
- [ ] className: `flex flex-col md:flex-row md:items-center justify-between gap-4`

### Icon Box
- [ ] div className: `p-2 bg-primary/10 rounded-lg hidden md:block`
- [ ] Icon className: `w-6 h-6 text-primary`

### Title Area
- [ ] Title wrapper: `flex items-center gap-2`
- [ ] h1 className: `text-xl md:text-2xl` ⚠️ font-bold ❌ (없어야 함)
- [ ] Badge className: `variant="secondary" gap-1`
- [ ] Badge Icon: `h-3 w-3`
- [ ] Version text: "v1.0.0" (3자리)

### Subtitle
- [ ] p className: `text-sm text-muted-foreground mt-1`

### Stats Card
- [ ] Label: `text-sm font-medium text-muted-foreground`
- [ ] Value: `text-3xl md:text-4xl font-bold mt-2` ⚠️ NOT text-2xl
- [ ] Icon: `w-10 h-10 md:w-12 md:h-12 opacity-15 ${iconColor}`
```

**추출 방법**:
```bash
# React 파일의 특정 라인 범위를 정확히 읽기
Read file_path="..." offset=1899 limit=30
```

### Step 5: 스타일 구현 하기
**목적**: 체크리스트를 보며 CSS 클래스 1:1 정확 복제

**원칙**:
- ✅ 체크리스트의 모든 항목을 하나씩 확인하며 적용
- ✅ 클래스 순서도 가능한 동일하게 유지
- ❌ 추측하거나 비슷한 걸로 대체하지 않기

**작업 방법**:
```
1. 체크리스트 1번 항목 보기
2. Edit 도구로 해당 부분 수정
3. 체크리스트 2번 항목 보기
4. Edit 도구로 해당 부분 수정
... 반복
```

### Step 6: 스타일 검증
**목적**: React와 Next.js 코드의 완전 일치 확인

**검증 방법**:
```markdown
## 스타일 검증 결과

### Header Section

**React (라인 1899-1917)**:
```tsx
<h1 className="text-xl md:text-2xl">품목 관리</h1>
```

**Next.js (현재 구현)**:
```tsx
<h1 className="text-xl md:text-2xl">품목 관리</h1>
```

✅ 일치

---

**React**:
```tsx
<p className="text-3xl md:text-4xl font-bold">{stat.value}</p>
```

**Next.js**:
```tsx
<p className="text-2xl font-bold">{stat.value}</p>
```

❌ 불일치: 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 기반 체계적 작업 분해 및 순차 실행