ERP-node/.cursor/rules/migration-guide.mdc

---
description: 
globs: 
alwaysApply: true
---
# Next.js 마이그레이션 가이드

## 마이그레이션 개요
현재 JSP/jQuery 기반 프론트엔드를 Next.js로 전환하는 작업이 계획되어 있습니다.
자세한 내용은 [TODO.md](mdc:TODO.md)를 참조하세요.

## 현재 프론트엔드 분석

### JSP 뷰 구조
```
WebContent/WEB-INF/view/
├── admin/          # 관리자 화면
├── approval/       # 승인 관리
├── common/         # 공통 컴포넌트
├── dashboard/      # 대시보드
├── main/           # 메인 화면
└── ...            # 기타 모듈별 화면
```

### 주요 JavaScript 라이브러리
- **jQuery**: 1.11.3/2.1.4 - DOM 조작 및 AJAX
- **jqGrid**: 4.7.1 - 데이터 그리드 (교체 필요)
- **Tabulator**: 테이블 컴포넌트
- **rMateChart**: 차트 라이브러리 (교체 필요)
- **CKEditor**: 텍스트 에디터

### CSS 프레임워크
- [all.css](mdc:WebContent/css/all.css) - 메인 스타일시트
- jQuery UI 테마 적용
- 반응형 디자인 미적용 (데스크톱 중심)

## API 설계 가이드

### RESTful API 변환
현재 Spring MVC는 JSP 뷰를 반환하는 구조입니다:
```java
@RequestMapping("/admin/menuMngList.do")
public String getMenuList(HttpServletRequest request, @RequestParam Map<String, Object> paramMap) {
    // 데이터 조회
    List<Map<String, Object>> menuList = adminService.getMenuList(request, paramMap);
    request.setAttribute("menuList", menuList);
    return "/admin/menu/menuMngList"; // JSP 뷰 반환
}
```

Next.js 연동을 위해 JSON API로 변환 필요:
```java
@RestController
@RequestMapping("/api")
public class AdminApiController {
    
    @GetMapping("/admin/menus")
    @ResponseBody
    public ResponseEntity<ApiResponse<List<Map<String, Object>>>> getMenuList(
            @RequestParam Map<String, Object> paramMap) {
        List<Map<String, Object>> menuList = adminService.getMenuList(null, paramMap);
        return ResponseEntity.ok(ApiResponse.success(menuList));
    }
}
```

### API 응답 표준화
```java
public class ApiResponse<T> {
    private boolean success;
    private T data;
    private String message;
    private String errorCode;
    
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(true, data, null, null);
    }
    
    public static <T> ApiResponse<T> error(String message, String errorCode) {
        return new ApiResponse<>(false, null, message, errorCode);
    }
}
```

## 컴포넌트 매핑 가이드

### 데이터 그리드 교체
**현재**: jqGrid 4.7.1
```javascript
$("#grid").jqGrid({
    url: 'menuMngList.do',
    datatype: 'json',
    colModel: [
        {name: 'menuName', label: '메뉴명'},
        {name: 'url', label: 'URL'}
    ]
});
```

**변환 후**: TanStack Table 또는 AG Grid
```tsx
import { useTable } from '@tanstack/react-table';

const MenuTable = () => {
    const columns = [
        { accessorKey: 'menuName', header: '메뉴명' },
        { accessorKey: 'url', header: 'URL' }
    ];
    
    const table = useTable({ data, columns });
    // 테이블 렌더링
};
```

### 차트 라이브러리 교체
**현재**: rMateChart
**변환 후**: Recharts 또는 Chart.js

### 폼 처리 교체
**현재**: jQuery 기반 폼 처리
**변환 후**: react-hook-form 사용

## 인증/인가 처리

### 현재 세션 기반 인증
```java
// 세션에서 사용자 정보 조회
PersonBean person = (PersonBean)request.getSession().getAttribute(Constants.PERSON_BEAN);
```

### Next.js 연동 방안
1. **세션 유지**: 쿠키 기반 세션 ID 전달
2. **JWT 토큰**: 새로운 토큰 기반 인증 도입
3. **하이브리드**: 기존 세션 + API 토큰

## 개발 단계별 접근

### Phase 1: API 개발
1. 기존 Controller 분석
2. @RestController 신규 생성
3. 기존 Service 재사용
4. CORS 설정 추가

### Phase 2: Next.js 기본 구조
1. Next.js 프로젝트 생성
2. 기본 레이아웃 구현
3. 라우팅 구조 설계
4. 공통 컴포넌트 개발

### Phase 3: 화면별 마이그레이션
1. 관리자 화면부터 시작
2. 주요 업무 화면 순차 전환
3. 대시보드 및 리포트 화면

### Phase 4: 테스트 및 최적화
1. 기능 테스트
2. 성능 최적화
3. 사용자 테스트
4. 점진적 배포

## 주의사항

### 데이터 호환성
- 기존 데이터베이스 스키마 유지
- API 응답 형식 표준화
- 날짜/시간 형식 통일

### 사용자 경험
- 기존 업무 프로세스 유지
- 화면 전환 시 혼란 최소화
- 점진적 마이그레이션 고려

### 성능 고려사항
- API 응답 속도 최적화
- 클라이언트 사이드 캐싱
- 이미지 및 정적 자원 최적화