127 lines
11 KiB
Markdown
127 lines
11 KiB
Markdown
# 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를 사용하여 응답하도록 구현 (성공/실패 여부, 데이터, 메시지 등 포함)
|
|
```java
|
|
// 예시 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 등)으로 변경할지 결정해야 합니다.
|