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: 차이점 일괄 수정

추출 형식

{
  "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. 반복 (통계 카드, 검색 필터, 테이블...)

섹션 분류 예시

## 품목 관리 페이지 섹션 구조

### 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. 구현 후 다시 체크리스트로 검증

체크리스트 형식

## 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): 실험 완료, 베스트 프랙티스 확립, 표준 워크플로우 정립