TODO: 프론트엔드 Next.js 마이그레이션

이 문서는 기존 Java/Spring 백엔드(ilshin)는 유지하면서, JSP/jQuery 기반의 프론트엔드를 Next.js 기반으로 전환하기 위한 작업 목록입니다.

단계 1: 사전 준비 및 분석

Next.js 프로젝트 생성: create-next-app을 사용하여 신규 Next.js 프로젝트 생성 (TypeScript 사용 권장)
프로젝트 구조 설정: 폴더 구조 정의 (e.g., components, pages or app, styles, lib or utils, hooks, api)
스타일링 솔루션 선택 및 설정:
- CSS Modules, Tailwind CSS, Styled Components, Emotion 등 선택
- 기본 테마 및 전역 스타일 설정
기존 프론트엔드 분석 (매우 중요):
- 페이지/뷰 식별: WebContent/WEB-INF/view/ 내 모든 JSP 파일 분석하여 페이지 목록 작성
- 컴포넌트 식별: 재사용되는 UI 요소 식별 (버튼, 폼, 테이블, 모달, 차트, 그리드 등). 특히 jqGrid, Highcharts 등 특정 라이브러리 기반 컴포넌트 파악
- 라우팅 분석: 기존 URL 패턴 (*.do 등)과 Spring Controller 매핑 관계 파악하여 Next.js 라우팅 구조 설계
- 인증/인가 흐름 분석: 로그인 방식, 세션 관리, 페이지 접근 권한 로직 파악
- 기존 JavaScript 분석: WebContent/js/ 내 파일 분석하여 중요한 UI 로직, 데이터 처리, 상태 관리 방식 파악 (특히 common.js 등)
상태 관리 전략 수립: Next.js 애플리케이션의 상태 관리 방법 결정 (Context API, Zustand, Jotai, Redux 등)
UI 라이브러리/컴포넌트 시스템 검토: 필요한 경우 Material UI, Chakra UI, Ant Design, Shadcn/ui 등 검토 또는 자체 디자인 시스템 구축 결정

단계 2: 백엔드 API 준비 (핵심 작업)

배경: 현재 백엔드 아키텍처는 Spring MVC 기반으로, @Controller가 요청을 받아 비즈니스 로직을 처리하는 @Service를 호출하고, 그 결과를 ModelAndView 또는 모델 객체에 담아 InternalResourceViewResolver를 통해 /WEB-INF/view/ 경로의 JSP 뷰로 전달하여 렌더링하는 구조입니다. Next.js 프론트엔드와 통신하기 위해서는, 기존의 Service 계층과 비즈니스 로직은 최대한 재사용하면서, Controller 레벨에서 JSP 뷰 이름 대신 JSON 데이터를 반환하는 RESTful API 엔드포인트를 새로 구축하거나 기존 Controller를 수정해야 합니다.

기존 기능 및 데이터 흐름 분석 (재확인):
- WebContent/WEB-INF/view/의 각 JSP 페이지와 매핑되는 com.pms.controller 패키지 내의 Spring Controller 메소드 파악 (@RequestMapping 경로 확인)
- 각 Controller 메소드가 호출하는 Service 메소드 및 사용되는 데이터 모델(VO/DTO) 분석
- 페이지 로딩 시 필요한 데이터 조회 로직, 폼 제출 시 데이터 처리 로직 식별
API 엔드포인트 상세 설계:
- 기존 기능 기반으로 필요한 REST API 엔드포인트 목록 작성 (리소스 기반 설계 권장, e.g., /api/products, /api/boms, /api/documents, /api/projects, /api/users 등)
- 각 리소스별 CRUD(POST, GET, PUT/PATCH, DELETE) 엔드포인트 정의
  - 예: GET /api/products (목록 조회), GET /api/products/{id} (상세 조회), POST /api/products (생성), PUT /api/products/{id} (수정), DELETE /api/products/{id} (삭제)
- 목록 조회 시 필요한 검색, 필터링, 페이징 파라미터 정의 (e.g., GET /api/products?search=...&page=1&size=10)
- 파일 업로드/다운로드 등 특수 기능에 대한 엔드포인트 정의
- 기존의 복잡한 로직 (여러 서비스 호출 등)을 처리하기 위한 맞춤형 엔드포인트 정의 (필요 최소화)
인증/인가 API 상세 설계:
- 로그인: POST /api/auth/login (ID/PW 받아 성공 시 사용자 정보 및 세션 ID/토큰 반환)
- 로그아웃: POST /api/auth/logout
- 현재 사용자 상태 확인: GET /api/auth/status (세션/토큰 유효성 검사 및 사용자 정보 반환)
REST API 구현 전략 결정:
- 방법: 신규 @RestController 클래스 생성: API 전용 컨트롤러를 새로 만들고, 내부적으로 기존 Service 로직을 호출하여 JSON 반환. (기존 코드 영향 최소화, 역할 분리 명확) (권장)
REST API 실제 구현 (선택한 전략 기반):
- Spring MVC 또는 Spring WebFlux 기반으로 @RestController 구현
- Service 계층 재사용하여 비즈니스 로직 처리
- 데이터베이스 조회 결과를 DTO(Data Transfer Object)로 변환하여 반환 (필요시 API 전용 DTO 생성)
- ResponseEntity를 사용하여 HTTP 상태 코드, 헤더, 응답 본문 명시적으로 제어
- 예외 처리: @ControllerAdvice와 @ExceptionHandler를 사용하여 API 예외 공통 처리 및 표준화된 오류 응답 반환
CORS (Cross-Origin Resource Sharing) 설정:
- WebMvcConfigurer 인터페이스 구현 및 addCorsMappings 메소드 오버라이드하여 전역 CORS 설정
- 또는 Spring Security 사용 시 Security 설정 내에서 CORS 구성
- 허용할 Origin 명시 (http://localhost:9771 등 Next.js 개발 서버 주소 포함)
- 허용할 HTTP 메소드 (GET, POST, PUT, DELETE 등) 및 헤더 설정
API 응답 형식 표준화 구현:
- 공통 응답 Wrapper 클래스 정의 (e.g., ApiResponse<T>)
- 모든 API가 이 Wrapper를 사용하여 응답하도록 구현 (성공/실패 여부, 데이터, 메시지 등 포함)
```
// 예시 Wrapper 클래스
public class ApiResponse<T> {
    private boolean success;
    private T data;
    private String message;
    // 생성자, getter 등
}
```
API 문서화 자동화:
- springdoc-openapi (권장) 또는 Springfox 라이브러리 의존성 추가
- Spring Boot 설정 파일 또는 Java Configuration 통해 기본 설정 (API 정보, 서버 URL 등)
- Controller 및 DTO에 @Operation, @Parameter, @Schema 등 어노테이션 추가하여 API 명세 작성
- Swagger UI 접속 경로 활성화 (e.g., /swagger-ui.html)
API 인가(Authorization) 처리:
- Spring Security 설정 검토 및 활성화 (필요시)
- 기존 인증/인가 로직 (세션 기반 등) 분석하여 API 요청에도 적용되도록 설정
- 각 @RestController 메소드 또는 Security 설정에서 URL 패턴별 접근 권한 설정 (@PreAuthorize 또는 HttpSecurity 설정 활용)
- 기존 사용자 역할/권한 체계 연동

단계 3: Next.js 프론트엔드 개발

기본 레이아웃 컴포넌트 구현: Header, Footer, Sidebar/Menu 등 공통 레이아웃 구조 구현 (main/header.jsp, main/menu.jsp 등 참조)
라우팅 구현: 분석 단계에서 설계한 라우팅 구조에 따라 Next.js 페이지 생성 및 라우팅 설정 (pages 또는 app 디렉토리 사용)
공통 UI 컴포넌트 개발: 버튼, 입력 필드, 모달 등 재사용 가능한 기본 컴포넌트 구현 또는 UI 라이브러리 적용
주요 라이브러리 대체 컴포넌트 구현/선택:
- jqGrid 대체: TanStack Table, AG Grid, 또는 직접 구현
- Highcharts 대체: Recharts, Chart.js (react-chartjs-2), Nivo 등
- 기타 필요한 라이브러리 (달력, 파일 업로더 등) 대체 컴포넌트 구현/선택
페이지별 UI 구현: 각 페이지의 UI를 JSP 분석 결과 바탕으로 Next.js 컴포넌트 사용하여 구현
폼(Form) 구현: 데이터 입력/수정을 위한 폼 구현 (react-hook-form 등 라이브러리 사용 권장)
인증 흐름 구현: 로그인 페이지, API 연동, 토큰/세션 정보 저장 및 관리 로직 구현 (Client-side storage 보안 고려)
전역 상태 관리 설정: 선택한 상태 관리 라이브러리 설정 및 필요한 전역 상태(사용자 정보 등) 관리 로직 구현

단계 4: 백엔드 연동 및 통합

API 클라이언트 구현: 백엔드 API 호출을 위한 함수/모듈 구현 (fetch API, axios, SWR, React Query 등 사용)
데이터 연동: 각 페이지 및 컴포넌트에서 필요한 데이터를 API 클라이언트를 통해 가져와 화면에 표시
폼 제출 연동: 폼 데이터를 백엔드 API로 전송하는 로직 구현
인증/인가 연동: 로그인 상태에 따른 라우팅 제어, API 요청 시 인증 정보(토큰 등) 포함 로직 구현

단계 5: 테스트

단위 테스트: 주요 컴포넌트, 커스텀 훅, 유틸리티 함수 단위 테스트 작성 (Jest, React Testing Library 등)
통합 테스트: API 연동 부분 테스트 (Mocking 또는 실제 API 사용)
E2E 테스트: 주요 사용자 시나리오 기반 End-to-end 테스트 작성 (Cypress, Playwright 등)
크로스 브라우저 테스트: 주요 웹 브라우저 환경에서 테스트
성능 테스트: 초기 로딩 속도, 데이터 조회/처리 속도 등 성능 측정 및 개선

단계 6: 빌드 및 배포

Next.js 빌드 설정: 프로덕션 환경용 빌드 설정 (next build)
배포 전략 수립:
- 정적 파일(Static Export) 배포 또는 Node.js 서버를 이용한 배포 결정
- 백엔드(Tomcat)와 프론트엔드(Next.js) 분리 배포
- 필요시 리버스 프록시(Nginx 등) 설정하여 요청 라우팅 (e.g., /api는 백엔드, 나머지는 프론트엔드)
CI/CD 파이프라인 구축: 빌드, 테스트, 배포 자동화 파이프라인 구축
환경 변수 설정: 배포 환경(Production)에 맞는 환경 변수 설정 (API 주소, 시크릿 키 등)

단계 7: 기존 프론트엔드 코드 제거 (선택 사항)

Next.js 프론트엔드가 안정화된 후, 기존 WebContent 내 JSP 파일, 관련 JavaScript, CSS 등 제거
백엔드에서 JSP 렌더링 관련 의존성 제거 (가능한 경우)

주요 고려 사항:

백엔드 API 변경의 복잡성: 기존 코드가 뷰 렌더링과 강하게 결합되어 있다면, 순수 데이터만 반환하는 API로 변경하는 작업이 가장 중요하고 어려울 수 있습니다.
라이브러리 의존성: jqGrid, Highcharts 등 기존 JavaScript 라이브러리의 기능을 React/Next.js 생태계의 라이브러리로 대체하는 작업이 필요합니다.
인증 방식: 기존 세션 기반 인증을 계속 사용할지, 아니면 토큰 기반(JWT 등)으로 변경할지 결정해야 합니다.

11 KiB Raw Permalink Blame History