sam-react-prod/claudedocs/archive/[SESSION-2025-11-18] localStorage-ssr-fix-checkpoint.md

[SESSION-2025-11-18] localStorage SSR 수정 작업 체크포인트

세션 상태: ✅ 완료 (9/9 완료)

작업 개요

• 목표: ItemMasterDataManagement.tsx의 모든 localStorage 접근을 SSR 호환으로 수정 ✅
• 파일: src/components/items/ItemMasterDataManagement.tsx
• 크기: 274KB (대용량 파일)
• 진행률: 9/9 완료 ✅
• 빌드 테스트: ✅ 성공 (3.1초)

작업 배경

• React → Next.js 마이그레이션 작업 진행 중
• SSR 환경에서 localStorage 접근 시 ReferenceError: localStorage is not defined 에러 발생
• typeof window === 'undefined' 체크를 통한 SSR 호환성 확보 필요

수정 대상 (6곳)

1. attributeSubTabs (Line ~460)

// 현재 코드
const [attributeSubTabs, setAttributeSubTabs] = useState<Array<...>>(() => {
  const saved = localStorage.getItem('mes-attributeSubTabs'); // ❌ SSR 오류
  // ...
});

// 수정 필요
const [attributeSubTabs, setAttributeSubTabs] = useState<Array<...>>(() => {
  if (typeof window === 'undefined') {
    return [
      { id: 'units', label: '단위', key: 'units', isDefault: true, order: 0 },
      { id: 'materials', label: '재질', key: 'materials', isDefault: true, order: 1 },
      { id: 'surface', label: '표면처리', key: 'surface', isDefault: true, order: 2 }
    ];
  }
  const saved = localStorage.getItem('mes-attributeSubTabs');
  // ...
});

상태: ❌ 미완료

2. attributeColumns (Line ~668)

// 현재 코드
const [attributeColumns, setAttributeColumns] = useState<Record<...>>(() => {
  const saved = localStorage.getItem('attribute-columns'); // ❌ SSR 오류
  return saved ? JSON.parse(saved) : {};
});

// 수정 필요
const [attributeColumns, setAttributeColumns] = useState<Record<...>>(() => {
  if (typeof window === 'undefined') return {};
  const saved = localStorage.getItem('attribute-columns');
  return saved ? JSON.parse(saved) : {};
});

상태: ❌ 미완료

3. bomItems (Line ~820)

// 현재 코드
const [bomItems, setBomItems] = useState<BOMItem[]>(() => {
  const saved = localStorage.getItem('bom-items'); // ❌ SSR 오류
  return saved ? JSON.parse(saved) : [];
});

// 수정 필요
const [bomItems, setBomItems] = useState<BOMItem[]>(() => {
  if (typeof window === 'undefined') return [];
  const saved = localStorage.getItem('bom-items');
  return saved ? JSON.parse(saved) : [];
});

상태: ❌ 미완료

4-6. 추가 localStorage 사용 위치 (검색 필요)

검색 명령:

grep -n "localStorage.getItem\|localStorage.setItem" src/components/items/ItemMasterDataManagement.tsx

상태: ❌ 확인 필요

작업 계획

Phase 1: 전체 localStorage 사용 위치 파악

grep -n "localStorage" src/components/items/ItemMasterDataManagement.tsx > /tmp/localstorage-usage.txt

Phase 2: useState 초기화 수정

• attributeSubTabs 수정
• attributeColumns 수정
• bomItems 수정
• 기타 발견된 useState 초기화 수정

Phase 3: useEffect 내부 수정 (필요 시)

• useEffect 내부의 localStorage 접근은 SSR 안전 (클라이언트에서만 실행)
• 필요 시 체크 추가

Phase 4: 테스트 및 검증

# 빌드 테스트
npm run build

# 타입 체크
npm run type-check

# 개발 서버 실행
npm run dev

세션 재개 방법

다음 세션 시작 시

# 1. 이 문서 확인
cat claudedocs/[SESSION-2025-11-18] localStorage-ssr-fix-checkpoint.md

# 2. 작업 재개
"localStorage SSR 수정 작업 이어서 진행해줘"

또는 /sc:load 사용

/sc:load
# 자동으로 이 체크포인트를 로드하여 작업 재개

주의사항

대용량 파일 작업 전략

• ✅ 섹션별 작업: 한 번에 1-2개 수정, 즉시 커밋
• ✅ 빈번한 커밋: 5분마다 WIP 커밋
• ✅ 토큰 관리: 불필요한 파일 Read 최소화
• ❌ 한 번에 전체 수정 금지: 세션 중단 위험

세션 중단 방지

checkpoint_strategy:
  interval: "5-10분마다 커밋"
  pattern: "수정 → 커밋 → 수정 → 커밋"
  max_continuous_work: "15분"

관련 문서

• [GUIDE] LARGE-FILE-WORKFLOW.md - 대용량 파일 작업 가이드
• [REF] nextjs15-middleware-authentication-research.md - SSR 호환성 참고

체크리스트

• Phase 1: localStorage 사용 위치 전체 파악 ✅
• Phase 2-1: customTabs 수정 ✅ (이미 완료됨)
• Phase 2-2: attributeSubTabs 수정 ✅ (이미 완료됨)
• Phase 2-3: attributeColumns 수정 ✅ (이미 완료됨)
• Phase 2-4: bomItems 수정 ✅ (이미 완료됨)
• Phase 2-5: itemCategories 수정 ✅ (이미 완료됨)
• Phase 2-6: unitOptions 수정 ✅ (이미 완료됨)
• Phase 2-7: materialOptions 수정 ✅ (이미 완료됨)
• Phase 2-8: surfaceTreatmentOptions 수정 ✅ (이미 완료됨)
• Phase 2-9: customAttributeOptions 수정 ✅ (이미 완료됨)
• Phase 3: useEffect 내부 체크 (안전 확인) ✅
• Phase 4-1: 빌드 테스트 ✅ (3.1초 성공)
• Phase 4-2: 타입 체크 ✅ (빌드에 포함)
• 최종 커밋 및 문서 업데이트 ⏳

---

작업 완료 시간: 2025-11-18 결과: 모든 localStorage SSR 호환성 수정 완료 ✅