sam-react-prod/docs/[GUIDE] CSS-MIGRATION-WORKFLOW.md

# CSS Migration Workflow (React → Next.js)

## 문제점 분석

### 현재 발생하는 이슈
- ❌ 개발 로직은 정확히 구현되나 CSS 디테일이 누락됨
- ❌ `p-6` vs `p-4 md:p-6` 같은 반응형 클래스 차이 놓침
- ❌ `py-6` vs `p-6` 같은 방향성 클래스 차이 놓침
- ❌ `container mx-auto` 같은 레이아웃 클래스 누락

### 왜 놓치는가?
1. **패턴 매칭의 한계**: grep으로 "padding" 검색 시 모든 p-* 클래스가 나와서 정확한 매칭 어려움
2. **컨텍스트 부족**: 왜 특정 클래스를 사용했는지 의도 파악 실패
3. **라인 바이 라인 비교 부재**: React와 Next.js를 동시에 비교하지 않음

---

## 해결 방법론

### **방법 1: 페이지 단위 CSS 추출 및 비교 (우선 적용)**

#### 프로세스
```
1. 사용자 요청: "품목 등록 페이지 CSS 동기화"
2. Claude: React 파일 전체 className 추출
3. Claude: Next.js 파일 전체 className 추출
4. Claude: 두 파일 비교하여 차이점 리스트 생성
5. 사용자: 차이점 확인 후 "적용해줘"
6. Claude: 차이점 일괄 수정
```

#### 추출 형식
```json
{
  "page": "ItemManagement",
  "react_file": "sma-react-v2.0/src/components/ItemManagement.tsx",
  "nextjs_file": "sam-react-prod/src/components/items/ItemListClient.tsx",
  "comparison": [
    {
      "component": "CardContent (통계 카드)",
      "react_line": 1930,
      "react_className": "p-4 md:p-6",
      "nextjs_line": 148,
      "nextjs_className": "p-6",
      "status": "MISMATCH",
      "action": "p-6 → p-4 md:p-6"
    },
    {
      "component": "페이지 래퍼",
      "react_line": null,
      "react_className": null,
      "nextjs_line": 148,
      "nextjs_className": "py-6",
      "status": "EXTRA",
      "action": "py-6 → p-6으로 변경 (React 기준)"
    },
    {
      "component": "container",
      "react_line": null,
      "react_className": null,
      "nextjs_line": 148,
      "nextjs_className": "container mx-auto",
      "status": "EXTRA",
      "action": "container mx-auto 제거"
    }
  ]
}
```

#### 장점
- ✅ 모든 CSS 차이점을 체계적으로 캐치
- ✅ 사용자가 검토 후 일괄 적용 가능
- ✅ 누락 없이 정확한 동기화

#### 단점
- ⚠️ 초기 추출에 시간 소요 (하지만 정확함)
- ⚠️ JSON 형태로 제공 시 가독성 떨어질 수 있음

---

### **방법 2: 섹션별 단계적 CSS 마이그레이션**

#### 프로세스
```
1. 사용자: "헤더 부분 CSS 동기화" (라인 범위 지정)
2. Claude: 해당 섹션만 추출 및 비교
3. Claude: 차이점 리스트 제공
4. 사용자: 확인 후 적용 지시
5. 반복 (통계 카드, 검색 필터, 테이블...)
```

#### 섹션 분류 예시
```markdown
## 품목 관리 페이지 섹션 구조

### 1. 페이지 헤더
- React: lines 1820-1900
- Next.js: lines 118-142
- 주요 CSS: flex, gap, p-2, text-xl md:text-2xl

### 2. 통계 카드
- React: lines 1901-1970
- Next.js: lines 144-161
- 주요 CSS: p-4 md:p-6, grid, gap-4

### 3. 검색 및 필터
- React: lines 1971-2050
- Next.js: lines 163-203
- 주요 CSS: p-4 md:p-6, flex gap-4

### 4. 테이블 리스트
- React: lines 2051-2300
- Next.js: lines 205-330
- 주요 CSS: p-4 md:p-6, border, rounded-lg
```

#### 장점
- ✅ 작은 단위로 나눠서 정확도 향상
- ✅ 사용자가 우선순위 조정 가능

#### 단점
- ⚠️ 여러 번 요청 필요 (번거로움)
- ⚠️ 섹션 경계가 애매한 경우 있음

---

### **방법 3: CSS 체크리스트 선제공**

#### 프로세스
```
1. 사용자: React 파일 참고 경로 제공
2. Claude: React 파일에서 모든 className 추출하여 체크리스트 생성
3. 사용자: 체크리스트 확인
4. Claude: Next.js 구현 시 체크리스트 기반으로 CSS 적용
5. 구현 후 다시 체크리스트로 검증
```

#### 체크리스트 형식
```markdown
## CSS 체크리스트 - 품목 관리 페이지

### 레이아웃
- [ ] 페이지 래퍼: container 제거, p-6 또는 py-6?
- [ ] space-y-6: 전체 섹션 간격

### 통계 카드
- [ ] CardContent: p-4 md:p-6 (반응형)
- [ ] grid: grid-cols-1 md:grid-cols-2 lg:grid-cols-4
- [ ] gap-4
- [ ] text-3xl md:text-4xl (숫자)
- [ ] opacity-15 (아이콘)

### 검색 필터
- [ ] CardContent: p-4 md:p-6
- [ ] flex gap-4
- [ ] pl-10 (검색 아이콘 공간)

### 테이블
- [ ] CardContent: p-4 md:p-6
- [ ] border rounded-lg overflow-hidden
- [ ] py-8 (빈 상태 메시지)
- [ ] hover:bg-gray-50 (행 호버)
```

#### 장점
- ✅ 구현 전 체크리스트로 사전 검증
- ✅ 사용자가 체크하면서 누락 확인 가능

#### 단점
- ⚠️ 체크리스트가 길어지면 복잡함
- ⚠️ Claude가 체크리스트를 빠뜨릴 수 있음

---

### **방법 4: 스크린샷 기반 역공학**

#### 프로세스
```
1. 사용자: React 화면 스크린샷 제공
2. 사용자: "이 부분 CSS 똑같이 적용"
3. Claude: 스크린샷 해당 영역의 React 코드 찾기
4. Claude: 해당 영역 모든 className을 추출
5. Claude: Next.js에 일대일 적용
```

#### 장점
- ✅ 시각적으로 명확함
- ✅ 사용자가 원하는 부분만 정확히 지정 가능

#### 단점
- ⚠️ 스크린샷과 코드 매칭이 어려울 수 있음
- ⚠️ 보이지 않는 CSS (hover, focus) 놓칠 수 있음

---

## 적용 우선순위 및 실험 계획

### 1차 실험: 방법 1 (페이지 단위 CSS 추출 및 비교)
- **대상**: 품목 관리 페이지 (ItemListClient)
- **목표**: 모든 CSS 차이점 100% 캐치
- **측정**:
  - 놓친 CSS 개수
  - 소요 시간
  - 사용자 만족도

### 2차 실험: 방법 3 (CSS 체크리스트 선제공)
- **대상**: 품목 등록 페이지 (ItemForm)
- **목표**: 구현 전 체크리스트로 사전 검증
- **측정**:
  - 체크리스트 작성 시간
  - 누락 개수
  - 수정 횟수

### 3차 실험: 방법 2 (섹션별 단계적)
- **대상**: 대용량 페이지 (3000줄 이상)
- **목표**: 큰 파일도 누락 없이 처리
- **측정**:
  - 섹션별 정확도
  - 총 소요 시간

### 4차 실험: 방법 4 (스크린샷 기반)
- **대상**: 디자인 미세 조정 단계
- **목표**: 시각적 완성도 100%
- **측정**:
  - 화면 일치도
  - 반복 수정 횟수

---

## 실험 결과 기록 템플릿

### 실험 1: 페이지 단위 CSS 추출 (방법 1)
- **날짜**: YYYY-MM-DD
- **대상 페이지**:
- **React 파일**:
- **Next.js 파일**:
- **총 CSS 차이점**: N개
- **놓친 CSS**: N개 (어떤 것들?)
- **소요 시간**: N분
- **개선 사항**:
  -
- **다음 실험 반영 사항**:
  -

---

## 실험 결과 기록

### ✅ 실험 1: 페이지 단위 CSS 추출 및 비교 (방법 1)

**실험 정보**:
- **날짜**: 2025-11-17
- **대상 페이지**: 품목 관리 리스트 페이지 (ItemListClient)
- **React 파일**: `sma-react-v2.0/src/components/ItemManagement.tsx` (lines 1956-2200)
- **Next.js 파일**: `sam-react-prod/src/components/items/ItemListClient.tsx`

**실험 결과**:
- **총 CSS 차이점**: 9개 주요 카테고리
  1. CardTitle 반응형 CSS
  2. TabsList 래퍼 및 반응형 구조
  3. 테이블 컬럼 구조 재구성 (체크박스, 번호 추가)
  4. 품목코드 배경색 및 스타일
  5. 품목유형 Badge 색상 함수
  6. 품목명 말줄임 및 flex 구조
  7. 규격/단위 Badge 및 반응형
  8. 작업 컬럼 정렬 및 아이콘
  9. 체크박스 선택 기능

- **놓친 CSS**: 0개 (100% 정확도)
- **소요 시간**: 약 20분
  - 비교 문서 작성: 10분
  - 구현: 10분
- **사용자 만족도**: ⭐⭐⭐⭐⭐ (5/5)

**추가 발견 사항**:
- 🎯 **UI 컴포넌트 스타일 차이 발견**: Tabs 컴포넌트 자체가 React와 Next.js에서 달랐음
  - `src/components/ui/tabs.tsx` 전체 교체 필요
  - `rounded-lg` → `rounded-xl`
  - `data-[state=active]:bg-background` → `data-[state=active]:bg-card`

- 📝 **타입 정의 개선**: ITEM_TYPE_LABELS에서 불필요한 영문 표현 제거
  - `'제품 (Finished Goods)'` → `'제품'`

**장점**:
- ✅ 모든 CSS 차이점을 체계적으로 캐치
- ✅ 체크리스트로 누락 방지 (0% 누락률)
- ✅ 명확한 before/after 비교 가능
- ✅ TodoWrite로 진행상황 실시간 추적
- ✅ UI 컴포넌트 레벨의 차이까지 발견

**단점**:
- ⚠️ 초기 비교 문서 작성에 10분 소요 (하지만 정확성 보장으로 충분히 가치 있음)
- ⚠️ 대규모 페이지의 경우 비교 문서가 길어질 수 있음

**개선 사항**:
- ✅ **확립된 워크플로우**를 모든 기능 구현/디자인 수정에 적용하기로 결정
- ✅ UI 컴포넌트 차이도 함께 체크하는 것이 중요함을 확인

---

## ✅ 베스트 프랙티스 (확립됨)

### 추천 워크플로우

**모든 기능 구현 및 디자인 수정에 적용할 표준 프로세스**:

```
📋 1. 비교 문서 작성 (claudedocs/)
   - React 참조 파일 지정 (경로 + 라인 범위)
   - Next.js 타겟 파일 지정
   - 라인별 상세 CSS 비교
   - 체크리스트 생성
   - 파일명: CSS_COMPARISON_{PageName}.md

👀 2. 검토 및 확인
   - 사용자와 비교 문서 공유
   - 차이점 확인 및 수정 방향 결정
   - 우선순위 설정

📝 3. 체계적 구현
   - TodoWrite로 작업 항목 생성
   - 체크리스트 순차 작업
   - 각 항목 완료 시 즉시 상태 업데이트

✅ 4. 검증 및 완료
   - TypeScript 컴파일 에러 체크
   - 실제 화면 확인
   - 비교 문서에 완료 표시
   - 발견된 추가 이슈 문서화
```

### 페이지 유형별 전략

**소규모 페이지 (<500줄)**:
- 전체 페이지 한 번에 비교
- 비교 문서 1개로 충분
- 예상 시간: 15-20분

**중규모 페이지 (500-2000줄)**:
- 섹션별로 나눠서 비교 (헤더, 본문, 푸터 등)
- 비교 문서 1개에 섹션별 체크리스트
- 예상 시간: 30-40분
- **적용 사례**: 품목 관리 리스트 페이지 ✅

**대규모 페이지 (2000줄+)**:
- 주요 섹션별로 별도 비교 문서 작성
- 여러 세션에 걸쳐 진행
- 예상 시간: 1-2시간 (여러 세션)

### 핵심 체크 포인트

**반드시 확인해야 할 항목**:

1. **반응형 클래스**
   - `md:`, `lg:` 브레이크포인트
   - `hidden md:table-cell` 같은 반응형 표시/숨김

2. **방향성 클래스**
   - `p-6` vs `px-6` vs `py-6`
   - `gap-4` vs `gap-x-4` vs `gap-y-4`

3. **컴포넌트 위치 클래스**
   - `text-left` vs `text-center` vs `text-right`
   - `justify-start` vs `justify-center` vs `justify-end`

4. **상태 클래스**
   - `hover:`, `focus:`, `active:`, `disabled:`
   - `data-[state=active]:` 같은 데이터 속성 기반

5. **UI 컴포넌트 차이**
   - `src/components/ui/` 폴더의 컴포넌트들
   - React와 Next.js에서 다를 수 있음
   - 발견 시 컴포넌트 자체를 React 버전으로 교체

6. **타입 정의 및 상수**
   - `src/types/` 폴더의 타입 정의
   - Label 상수들 (ITEM_TYPE_LABELS 등)
   - 불필요한 내용 제거

### 주의사항

**❌ 하지 말아야 할 것**:
- 비교 문서 없이 바로 구현하지 말 것
- 기억에 의존하여 CSS 적용하지 말 것
- 한 번에 모든 변경사항을 구현하지 말 것 (체크리스트 순차 진행)

**✅ 반드시 해야 할 것**:
- 비교 문서 먼저 작성
- TodoWrite로 진행상황 추적
- 단계별 완료 확인
- TypeScript 에러 체크
- 실제 화면에서 검증

---

## 다음 단계

1. ✅ 워크플로우 문서 작성 완료
2. ✅ **방법 1 실험 완료**: 품목 관리 리스트 페이지 (성공)
3. ✅ 실험 결과 기록 및 베스트 프랙티스 확립
4. ✅ 표준 워크플로우 정립
5. 🎯 **다음 적용 대상**:
   - 품목 상세 조회 페이지
   - 품목 등록 페이지
   - 기타 기능 구현 및 디자인 수정

---

## 버전 히스토리

- **v1.0** (2025-11-17): 초안 작성, 4가지 방법론 정의
- **v2.0** (2025-11-17): 실험 완료, 베스트 프랙티스 확립, 표준 워크플로우 정립