web-temp/SSR_CSR_ANALYSIS.md

SSR/CSR 동작 분석 및 개선 리포트

🔴 심각한 버그 (✅ 수정 완료)

1. ✅ app.vue - Google Analytics 초기화가 SSR에서 실행됨

• 위치: app/app.vue:115-120
• 문제: useGtag() 초기화가 SSR에서 실행되어 서버 사이드 에러 발생 가능
• 영향: 서버 렌더링 시 에러 발생, 성능 저하
• 수정: if (import.meta.client) 체크 추가

2. ✅ useAnalytics.ts - window/navigator/location 사용 시 클라이언트 체크 없음

• 위치: layers/composables/useAnalytics.ts:108, 201-202, 255
• 문제: window.location, navigator.userAgent, location.href 사용 시 import.meta.client 체크 없음
• 영향: SSR에서 window is not defined 에러 발생
• 수정: 모든 분석 함수에 if (!import.meta.client) return 체크 추가

3. ✅ useScrollStore.ts - document.body 사용 시 클라이언트 체크 없음

• 위치: layers/stores/useScrollStore.ts:27, 29
• 문제: document.body.classList 조작 시 import.meta.client 체크 없음
• 영향: SSR에서 document is not defined 에러 발생
• 수정: controlScrollLock 함수에 if (!import.meta.client) return 체크 추가

4. ✅ useModalStore.ts - document.body 사용 시 클라이언트 체크 없음

• 위치: layers/stores/useModalStore.ts:29, 31
• 문제: document.body.classList 조작 시 import.meta.client 체크 없음
• 영향: SSR에서 document is not defined 에러 발생
• 수정: handleControlDimmed 함수에 if (!import.meta.client) return 체크 추가

5. ✅ localeUtil.ts - navigator 사용 시 클라이언트 체크 없음

• 위치: layers/utils/localeUtil.ts:76
• 문제: navigator.language 사용 시 import.meta.client 체크 없음
• 영향: SSR에서 navigator is not defined 에러 발생
• 수정: 브라우저 언어 체크 부분을 if (import.meta.client) 블록으로 감쌈

6. ✅ stoveUtil.ts - location 사용 시 클라이언트 체크 없음

• 위치: layers/utils/stoveUtil.ts:18, 21
• 문제: location.href 사용 시 import.meta.client 체크 없음
• 영향: SSR에서 location is not defined 에러 발생
• 수정: csrGoStoveLogin 함수에 if (!import.meta.client) return 체크 추가

🟡 중간 수준 이슈 (개선 권장)

7. ✅ pageData.global.ts - window.history 사용

• 위치: layers/middleware/pageData.global.ts:103
• 문제: window.history.replaceState 사용은 체크되어 있지만, 더 안전한 처리 필요
• 영향: 미미하지만 타입 안정성 개선 가능
• 수정: if (import.meta.client) 체크 추가

8. Header.vue - 불필요한 클라이언트 체크

• 위치: layers/components/layouts/Header.vue:55, 66
• 문제: hasActiveChild, isNavItemActive 함수에서 클라이언트 체크가 있지만, computed에서 사용 시 불필요한 체크
• 영향: 성능 미미한 저하
• 상태: 현재 동작에는 문제 없으나, 성능 최적화를 위해 추후 개선 가능

9. ✅ app.vue - scroll 이벤트 리스너

• 위치: app/app.vue:125
• 문제: useEventListener는 클라이언트에서만 동작하지만, 명시적 체크 없음
• 영향: 미미하지만 명확성 개선 가능
• 수정: onMounted 내부에 if (!import.meta.client) return 체크 추가

🟢 성능 개선 사항

10. ClientOnly 컴포넌트 최적화

• 위치: layers/components/layouts/Header.vue:386-416
• 개선: 이미 ClientOnly로 감싸져 있으나, 더 세밀한 최적화 가능
• 영향: 초기 렌더링 성능 개선

11. 불필요한 SSR 실행 방지

• 위치: 여러 컴포저블 및 유틸 함수
• 개선: 클라이언트 전용 함수는 명시적으로 .client.ts 확장자 사용 권장
• 영향: 번들 크기 및 초기 로드 시간 개선

12. useWindowSize 사용 최적화

• 위치: layers/components/layouts/Header.vue:14, 121
• 개선: useWindowSize는 클라이언트에서만 동작하지만, SSR에서도 초기화됨
• 영향: 미미한 성능 개선

📋 수정 우선순위

1. ✅ 즉시 수정 (버그): #1, #2, #3, #4, #5, #6 - 완료
2. ✅ 단기 개선 (안정성): #7, #9 - 완료 (#8은 성능 최적화로 추후 검토)
3. 중기 개선 (성능): #10, #11, #12 - 추후 검토

✅ 수정 완료 내역

수정된 파일 목록

1. app/app.vue - Google Analytics 초기화 및 scroll 이벤트 리스너 클라이언트 체크 추가
2. layers/composables/useAnalytics.ts - 모든 분석 함수에 클라이언트 체크 추가
3. layers/stores/useScrollStore.ts - controlScrollLock 함수에 클라이언트 체크 추가
4. layers/stores/useModalStore.ts - handleControlDimmed 함수에 클라이언트 체크 추가
5. layers/utils/localeUtil.ts - 브라우저 언어 체크에 클라이언트 체크 추가
6. layers/utils/stoveUtil.ts - csrGoStoveLogin 함수에 클라이언트 체크 추가
7. layers/middleware/pageData.global.ts - window.history 사용 시 클라이언트 체크 추가

수정 방법 요약

• 모든 브라우저 전용 API (window, document, navigator, location) 사용 시 import.meta.client 체크 추가
• 클라이언트 전용 함수는 함수 시작 부분에 if (!import.meta.client) return 추가
• 클라이언트 전용 코드 블록은 if (import.meta.client) { ... } 로 감쌈

🎯 개선 효과

1. SSR 안정성 향상: 서버 사이드에서 브라우저 API 접근 시 발생하던 에러 방지
2. 타입 안정성 개선: 클라이언트 전용 코드의 명확한 구분
3. 성능 개선: 불필요한 서버 사이드 실행 방지로 초기 렌더링 성능 향상
4. 코드 품질 향상: SSR/CSR 경계가 명확해져 유지보수성 향상

📝 추가 권장 사항

1. 클라이언트 전용 유틸 함수 분리: csr 접두사가 붙은 함수들은 .client.ts 확장자로 분리 고려
2. 타입 가드 활용: TypeScript 타입 가드를 활용하여 클라이언트 전용 코드 타입 안정성 향상
3. 테스트 강화: SSR/CSR 환경에서의 동작 테스트 추가
4. 성능 모니터링: 수정 후 SSR 성능 및 에러 로그 모니터링