SamProject/sam-react-prod
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
df3db155dd9f72fa02cd438c2767fc00a708e370
sam-react-prod/claudedocs/[GUIDE] CSS-MIGRATION-WORKFLOW.md
byeongcheolryu 21edc932d9 docs: localStorage SSR 수정 작업 세션 체크포인트 생성 
- ItemMasterDataManagement.tsx SSR 호환성 작업 계획 수립
- 6곳의 localStorage useState 초기화 수정 대상 파악
- 대용량 파일 작업 전략 및 세션 재개 방법 문서화

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 14:05:29 +09:00

12 KiB
Raw Blame History

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