[P-Reinforce] Wikify Modern React Standards and ConnectAI Optimization Plan

00_Raw/레거시 React 코드베이스 마이그레이션.md

@@ -0,0 +1,66 @@
+# [[레거시 React 코드베이스 마이그레이션]]
+
+## 📌 Brief Summary
+레거시 React 코드베이스 마이그레이션(리팩토링)은 오래된 React 애플리케이션의 아키텍처, 상태 관리, 컴포넌트 구조 등을 최신 표준과 베스트 프랙티스에 맞게 개선하는 과정입니다 [1, 2]. 이 과정은 단순히 구식 코드를 수정하는 것을 넘어, 유닛 테스트를 통한 안정성 확보, 클래스형 컴포넌트에서 함수형/훅(Hook)으로의 전환, 그리고 점진적인 아키텍처 개편을 포함합니다 [2, 3]. 궁극적인 목표는 시스템의 결합도를 낮추고 유지보수성 및 확장성을 높여 누적된 기술 부채를 해결하는 것입니다 [1, 4].
+
+## 📖 Core Content
+*   **마이그레이션 준비 및 기본 원칙**: 
+    리팩토링을 시작하기 전 가장 먼저 수행해야 할 작업은 기존 기능이 깨지지 않도록 보장하는 유닛 테스트(Unit Test)를 작성하는 것입니다 [3, 5, 6]. 애플리케이션이 매우 작다면 처음부터 새로 작성하는 것이 나을 수도 있으나 [7], 일반적으로는 전면 재작성(Rewrite)보다는 점진적으로 개선하는 "리팩토링(Refactor, do not rewrite)" 철학을 따르는 것이 권장됩니다 [1].
+*   **컴포넌트 및 언어 현대화**: 
+    자바스크립트(JS)로 작성된 코드라면 타입스크립트(TS)로 업데이트하여 정적 타이핑을 적용합니다 [2, 8]. 또한, 레거시 클래스 기반 컴포넌트는 함수형 컴포넌트와 훅(Hooks)으로 마이그레이션해야 하며, 라이프사이클에 묶여 있던 불필요한 `useEffect` 사용을 식별하고 제거해야 합니다 [2].
+*   **상태 관리(State Management) 리팩토링**: 
+    과거의 방대한 Redux 스토어나 비효율적인 Context API 사용을 목적에 맞게 분리해야 합니다 [2, 9, 10]. 서버 상태(API 데이터)는 TanStack Query와 같은 라이브러리로 분리하여 관리하고, 전역 클라이언트 상태는 Zustand나 Context로 분리하며, 지역 상태는 컴포넌트 내부로 국한시키는 작업이 필요합니다 [2]. 이 과정 역시 한 번에 변경하기보다는 단일 스토어 단위(예: 알림 기능부터 시작해 체크아웃 플로우로 이동)로 점진적 마이그레이션을 진행합니다 [1].
+*   **아키텍처 및 폴더 구조 개편**: 
+    기존에 파일 타입별(예: components, hooks)로 나뉘어 있던 구조를 비즈니스 도메인이나 기능별(Feature-based) 구조로 개편합니다 [11, 12]. 더 나아가 Feature-Sliced Design(FSD) 같은 계층적 아키텍처를 도입하여 각 모듈의 응집도를 높이고 모듈 간 의존성을 단방향으로 제한합니다 [13, 14].
+*   **클린 코드와 스타일링 일관성 확보**: 
+    방대한 컴포넌트 내부의 데이터 페칭이나 비즈니스 로직은 커스텀 훅(Custom Hooks)으로 추출하여 모듈화합니다 [15, 16]. 여러 가지 CSS 방식(인라인 스타일, 외부 CSS, sx 등)이 혼재되어 있다면 하나로 표준화하여 일관성을 맞추고, ESLint 등의 도구를 도입하여 코드 린팅을 강제합니다 [6, 17-19].
+
+## ⚖️ Trade-offs & Caveats
+*   **전면 재작성(Rewrite) vs 점진적 마이그레이션**: 전면 재작성은 새로운 설계로 깨끗하게 코드를 짤 수 있다는 장점이 있으나, 시간 비용이 크고 기존의 비즈니스 로직 누락이라는 심각한 리스크가 있습니다 [1, 7]. 반면 점진적 리팩토링은 비교적 안전하지만, 과도기 동안 레거시 상태 관리(예: Context API)와 새로운 상태 관리(예: Zustand)가 공존하게 되어 구조적 복잡성이 일시적으로 증가할 수 있습니다 [1].
+*   **타입스크립트(TypeScript) 도입의 한계**: JS 코드를 TS로 전환하는 것은 안정성을 크게 높이지만, 팀원의 숙련도에 따라 인지적 오버헤드와 복잡성을 유발할 수 있습니다. 따라서 경험이 부족한 팀이라면 무리하게 한 번에 적용하기보다 점진적 채택이 필요합니다 [8].
+*   **추상화의 부작용**: DRY(Don't Repeat Yourself) 원칙을 극단적으로 추구하여 공통 로직을 무리하게 추상화하면, 코드가 지나치게 복잡해져 KISS(Keep It Simple, Stupid) 원칙에 위배됩니다 [20]. 잘못 추상화된 코드는 오히려 향후 변경을 어렵게 만들 수 있으므로 패턴이 세 번 이상 반복될 때까지 기다렸다가 추상화하는 것이 좋습니다 [20, 21].
+
+## 🔗 Knowledge Connections
+
+### Related Concepts
+
+#### [아키텍처/기반 기술]
+- [[Feature-Sliced Design]]
+  - 연결 이유: 레거시 구조의 파편화된 코드들을 논리적으로 재배치하고 향후 확장이 가능한 폴더 구조로 개편할 때 활용되는 현대적인 프론트엔드 아키텍처론입니다 [13, 14].
+  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 기능, 엔티티, 위젯 등으로 계층을 나누고 단방향 의존성 및 명시적 Public API를 설정하여 코드의 결합도를 낮추는 원리 [13, 14, 22].
+
+- [[점진적 마이그레이션 (Incremental Migration)]]
+  - 연결 이유: 대규모 레거시 시스템을 안전하게 리팩토링하기 위한 핵심 실행 전략입니다 [1].
+  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 새로운 기술(예: Zustand)을 도입할 때 전체를 재작성하지 않고, 알림 기능 등 독립적이고 작은 스토어부터 시작해 점진적으로 전환하는 리스크 관리 방법 [1].
+
+#### [구현/활용 도구]
+- [[커스텀 훅 (Custom Hooks)]]
+  - 연결 이유: 비대해진 레거시 컴포넌트 내부에서 비즈니스 로직과 UI 렌더링 로직을 분리해내는 핵심적인 리팩토링 단위입니다 [15, 16].
+  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 로직(예: `useFetch`, `useForm`)을 분리함으로써 개별 유닛 테스트가 용이해지고 컴포넌트의 책임을 단일화하는 원리 [15].
+
+- [[TanStack Query (React Query)]]
+  - 연결 이유: 기존 레거시 앱에서 Redux나 Context API로 억지로 관리하던 API 응답 데이터를 분리해내기 위한 서버 상태 관리 도구입니다 [2, 10, 23].
+  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 클라이언트 상태와 서버 상태를 명확히 분리함으로써 보일러플레이트를 줄이고 데이터 동기화를 자동화하는 방식 [10, 23].
+
+### Deeper Research Questions
+- 레거시 Context API에서 Zustand 등 다른 상태 관리 라이브러리로 점진적으로 마이그레이션할 때, 두 상태 시스템 간의 데이터 동기화 이슈는 어떻게 방지할 수 있는가?
+- TypeScript가 전혀 적용되지 않은 방대한 JavaScript 코드베이스에 TS를 도입할 때 가장 리스크가 적고 효율적인 점진적 적용(incremental adoption) 전략은 무엇인가?
+- 리팩토링 과정에서 기존 기능을 유지하고 있음을 증명하기 위해, 유닛 테스트와 시각적 회귀 테스트(Visual Regression Testing) 중 어느 것을 먼저 도입하는 것이 효과적인가?
+- 비즈니스 로직이 뷰(View)에 강하게 결합된 레거시 컴포넌트를 커스텀 훅으로 추출할 때 발생하는 의존성(props, state) 얽힘 문제는 어떤 패턴으로 해결할 수 있는가?
+- Feature-Sliced Design(FSD) 아키텍처로 개편 시, 여러 기능(Feature)에서 공통으로 교차되는 관심사(Cross-cutting concerns, 예: 인증 로직)는 어느 계층에 어떻게 배치해야 결합도를 최소화할 수 있는가?
+
+### Practical Application Contexts
+- **Implementation:** 클래스 컴포넌트의 복잡한 라이프사이클 메서드를 분석하여 함수형 컴포넌트의 훅(`useState`, `useEffect`)으로 1:1 대응 변환하고, 렌더링 최적화 로직을 재구성하는 코딩 작업 [2].
+- **System Design:** 단순히 컴포넌트, 훅, 스타일 단위로 분리되어 있던 폴더 구조를 분석하여 비즈니스 도메인(Auth, Dashboard 등) 단위로 재설계 및 디렉터리 구조 개편 [11, 12].
+- **Operation / Maintenance:** ESLint 및 Prettier와 함께 Git 훅(Husky 등)을 구축하여, 향후 새로 작성되는 코드가 레거시 패턴(구식 라이브러리 사용, CSS 혼재)으로 되돌아가지 않도록 코드 컨벤션을 자동화하여 유지보수 [19, 24].
+- **Learning Path:** 소규모 장난감(toy) 앱에서 먼저 TypeScript와 Custom Hooks 분리를 연습한 뒤, 레거시 코드베이스의 작은 컴포넌트부터 유닛 테스트를 작성해가며 점진적으로 규모를 키우는 실무 학습 방향 [5, 25].
+- **My Project Relevance:** 유지보수 기간이 오래되어 기술 부채가 쌓인 React 프로젝트를 인수받았을 때, 시스템의 중단 없이 코드 품질과 성능을 최신 기준에 맞게 현대화(Modernization)해야 하는 실무 환경에 직접 적용.
+
+### Adjacent Topics
+- [[클린 코드 (Clean Code)와 SOLID 원칙]]
+  - 확장 방향: 리팩토링 시 컴포넌트의 단일 책임 원칙(SRP)과 개방-폐쇄 원칙(OCP)을 준수하여 가독성과 확장성을 높이는 일반적인 소프트웨어 공학 설계 패턴 탐구.
+- [[프론트엔드 테스팅 (Frontend Testing)]]
+  - 확장 방향: 마이그레이션 과정에서 기존 기능이 훼손되지 않도록 보장하기 위해 Storybook 기반 UI 테스트나 Jest, Cypress 등을 활용한 테스트 커버리지 확보 전략 조사.
+
+---
+*Last updated: 2026-04-30*