340 lines
9.0 KiB
Markdown
340 lines
9.0 KiB
Markdown
# 그룹웨어 마이그레이션 가이드
|
|
|
|
## 현행 시스템 → Spring Boot + Next.js 전환
|
|
|
|
---
|
|
|
|
## 현행 시스템 개요
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| 프레임워크 | Grails 2.5.0 |
|
|
| 언어 | Groovy / Java |
|
|
| ORM | MyBatis (SQL XML 방식) |
|
|
| DB | Oracle (JNDI: `java:comp/env/loginsDS`) |
|
|
| 빌드 | Maven |
|
|
| 뷰 | GSP + Daum Editor |
|
|
| 버전관리 | SVN |
|
|
|
|
### 현행 주요 모듈
|
|
|
|
| 모듈 | 설명 |
|
|
|------|------|
|
|
| board | 게시판 |
|
|
| tam | 결재 관리 |
|
|
| wplan | 근무 계획 |
|
|
| wtime | 근무 시간 관리 |
|
|
| envset | 환경 설정 / 사용자 관리 |
|
|
| fedex | 배송 연동 |
|
|
| common | 공통 (인증, 코드, 첨부파일, 보안) |
|
|
|
|
---
|
|
|
|
## 신규 기술 스택 (회사 표준)
|
|
|
|
| 계층 | 기술 | 버전 |
|
|
|------|------|------|
|
|
| OS | Ubuntu | 24.04 LTS |
|
|
| Web/Proxy | Nginx | 1.26.x Stable |
|
|
| Frontend | Next.js | 15.x (React 19 기반) |
|
|
| Runtime | Node.js | 22 LTS |
|
|
| 패키지 관리 | pnpm | 최신 |
|
|
| API Gateway | Spring Cloud Gateway | 4.x (Spring Boot 3.x 기반) |
|
|
| Backend | Spring Boot | 3.4.x |
|
|
| JDK | OpenJDK | 21 LTS |
|
|
| 빌드 도구 | Gradle | 8.x |
|
|
| DB (신규 표준) | MariaDB | 11.4 LTS |
|
|
| DB (현재 유지) | Oracle | 기존 그대로 유지 |
|
|
| Cache | Redis | 7.x |
|
|
| MQ | RabbitMQ | 3.13.x |
|
|
| 컨테이너 | Docker / Docker Compose | 최신 Stable |
|
|
| 형상관리 | GitHub | - |
|
|
| CI/CD | Jenkins | LTS |
|
|
|
|
---
|
|
|
|
## 신규 아키텍처
|
|
|
|
```
|
|
[Nginx]
|
|
│
|
|
[Next.js 15.x] ──→ [Spring Cloud Gateway 4.x] ──→ [Spring Boot 3.4.x]
|
|
│
|
|
[Redis Cache]
|
|
│
|
|
[Oracle DB] ← 현재
|
|
[MariaDB] ← 추후 전환
|
|
```
|
|
|
|
### 폴더 구조
|
|
|
|
```
|
|
NEW/
|
|
backend/ ← Spring Boot 3.4.x 프로젝트 (Gradle)
|
|
frontend/ ← Next.js 15.x 프로젝트 (pnpm)
|
|
MIGRATION_GUIDE.md
|
|
```
|
|
|
|
---
|
|
|
|
## DB 전환 전략
|
|
|
|
### 단계별 계획
|
|
|
|
```
|
|
1단계 (현재): Oracle 유지하며 신규 시스템 개발
|
|
2단계 (추후): 신규 시스템 안정화 및 검증 완료 후 MariaDB 마이그레이션
|
|
```
|
|
|
|
### SQL 이중화 전략 (MyBatis databaseId 활용)
|
|
|
|
기존 Oracle SQL XML을 그대로 사용하면서, MariaDB 문법 버전을 병행 작성.
|
|
전환 시 `application.yml`의 databaseId 설정만 변경하면 즉시 교체 가능.
|
|
|
|
```xml
|
|
<!-- Oracle 전용 쿼리 -->
|
|
<select id="selectList" databaseId="oracle">
|
|
SELECT * FROM (
|
|
SELECT ROWNUM AS rn, t.* FROM board t WHERE ROWNUM <= #{endRow}
|
|
) WHERE rn > #{startRow}
|
|
</select>
|
|
|
|
<!-- MariaDB 전용 쿼리 (추후 전환용) -->
|
|
<select id="selectList" databaseId="mariadb">
|
|
SELECT * FROM board
|
|
LIMIT #{size} OFFSET #{offset}
|
|
</select>
|
|
```
|
|
|
|
### Oracle → MariaDB 주요 변환 포인트
|
|
|
|
| 항목 | Oracle | MariaDB |
|
|
|------|--------|---------|
|
|
| 페이징 | ROWNUM | LIMIT / OFFSET |
|
|
| 시퀀스 | sequence.NEXTVAL | AUTO_INCREMENT |
|
|
| 날짜 함수 | SYSDATE, TO_DATE | NOW(), STR_TO_DATE |
|
|
| 문자열 연결 | `||` | CONCAT() 또는 `||` |
|
|
| NVL | NVL() | IFNULL() / COALESCE() |
|
|
| DECODE | DECODE() | CASE WHEN |
|
|
| 가상 테이블 | FROM DUAL | FROM DUAL (지원) 또는 생략 |
|
|
|
|
---
|
|
|
|
## Phase 1. 분석 및 설계
|
|
|
|
### 1-1. 현행 파악 체크리스트
|
|
|
|
- [ ] 각 컨트롤러의 URL 매핑 목록화 (`UrlMappings.groovy` + 각 컨트롤러)
|
|
- [ ] 세션/인증 방식 파악 (`SecurityFilter`, `AuthService`)
|
|
- [ ] 공통 유틸 파악 (`CommonUtil`, `ReqUtil`, `FormatUtil` 등)
|
|
- [ ] SQL XML의 쿼리별 입출력 파라미터 파악
|
|
- [ ] 파일 첨부 저장 방식 파악 (`AttachService`)
|
|
- [ ] 메뉴/권한 구조 파악 (`MenuService`, `SecurityService`)
|
|
|
|
### 1-2. 인증 구조 전환 설계
|
|
|
|
```
|
|
기존: 세션 기반 (SecurityFilter.groovy)
|
|
신규: JWT 기반
|
|
- POST /api/auth/login → JWT 발급
|
|
- 모든 요청 헤더: Authorization: Bearer {token}
|
|
- Spring Security Filter Chain 구성
|
|
- Redis를 활용한 토큰 블랙리스트/Refresh Token 관리
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 2. Spring Boot 백엔드 구성
|
|
|
|
### 2-1. 주요 의존성 (build.gradle)
|
|
|
|
```groovy
|
|
dependencies {
|
|
// Web
|
|
implementation 'org.springframework.boot:spring-boot-starter-web'
|
|
|
|
// Security & JWT
|
|
implementation 'org.springframework.boot:spring-boot-starter-security'
|
|
implementation 'io.jsonwebtoken:jjwt-api:0.12.x'
|
|
|
|
// MyBatis
|
|
implementation 'org.mybatis.spring.boot:mybatis-spring-boot-starter:3.x'
|
|
|
|
// Oracle JDBC
|
|
implementation 'com.oracle.database.jdbc:ojdbc11'
|
|
|
|
// MariaDB JDBC (추후 전환용)
|
|
runtimeOnly 'org.mariadb.jdbc:mariadb-java-client'
|
|
|
|
// Redis
|
|
implementation 'org.springframework.boot:spring-boot-starter-data-redis'
|
|
|
|
// Validation
|
|
implementation 'org.springframework.boot:spring-boot-starter-validation'
|
|
|
|
// Lombok
|
|
compileOnly 'org.projectlombok:lombok'
|
|
annotationProcessor 'org.projectlombok:lombok'
|
|
|
|
// Excel (Apache POI)
|
|
implementation 'org.apache.poi:poi-ooxml:5.x'
|
|
}
|
|
```
|
|
|
|
### 2-2. MyBatis 마이그레이션 (기존 SQL XML 재사용)
|
|
|
|
기존 `src/java/sql/` 의 XML 파일을 Spring Boot 프로젝트로 복사 후 경미한 수정만 필요.
|
|
|
|
| 작업 | 내용 |
|
|
|------|------|
|
|
| Mapper XML 이동 | `src/main/resources/mapper/` 로 복사 |
|
|
| Mapper Interface 생성 | XML의 각 쿼리 ID에 대응하는 Java Interface 작성 |
|
|
| VO/DTO 클래스 | Groovy VO → Java POJO (Lombok 활용) |
|
|
| SqlSessionFactory | MyBatis Spring Boot Starter 자동 설정 |
|
|
| databaseId 설정 | Oracle/MariaDB 구분을 위한 DatabaseIdProvider 등록 |
|
|
|
|
### 2-3. 모듈별 변환 순서
|
|
|
|
```
|
|
1. common → 인증(JWT + Redis), 코드, 공통 유틸
|
|
2. envset → 사용자/권한/메뉴 관리
|
|
3. board → 게시판 (전형적인 CRUD로 패턴 확립)
|
|
4. tam → 결재 워크플로우
|
|
5. wplan → 근무 계획
|
|
6. wtime → 근무 시간
|
|
7. fedex → 외부 연동
|
|
```
|
|
|
|
### 2-4. API 응답 공통 형식
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": { ... },
|
|
"message": "",
|
|
"pagination": {
|
|
"page": 1,
|
|
"size": 20,
|
|
"total": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 3. Next.js 프론트엔드 구성
|
|
|
|
### 3-1. 주요 의존성
|
|
|
|
```
|
|
- Next.js 15.x (App Router, React 19)
|
|
- TypeScript
|
|
- Tailwind CSS
|
|
- shadcn/ui (UI 컴포넌트)
|
|
- TanStack Query v5 (서버 상태 관리)
|
|
- Zustand (클라이언트 상태 관리)
|
|
- react-hook-form + zod (폼 검증)
|
|
- axios (API 호출)
|
|
- Toast UI Editor 또는 Tiptap (WYSIWYG - Daum Editor 대체)
|
|
```
|
|
|
|
### 3-2. 페이지 구조
|
|
|
|
```
|
|
/app
|
|
/login
|
|
/(main)
|
|
/dashboard
|
|
/board/[boardType]
|
|
/tam ← 결재
|
|
/wplan ← 근무계획
|
|
/wtime ← 근무시간
|
|
/envset ← 환경설정
|
|
/users
|
|
/codes
|
|
/menus
|
|
```
|
|
|
|
### 3-3. GSP → Next.js 화면 변환
|
|
|
|
```
|
|
Daum Editor → Toast UI Editor 또는 Tiptap
|
|
GSP 페이징 태그 → 커스텀 Pagination 컴포넌트
|
|
GSP 공통 레이아웃 → app/layout.tsx
|
|
세션 체크 → JWT 기반 Next.js Middleware
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 4. 인프라 구성 (Docker)
|
|
|
|
### docker-compose.yml 구성 예시
|
|
|
|
```yaml
|
|
services:
|
|
nginx:
|
|
image: nginx:1.26
|
|
frontend:
|
|
build: ./frontend # Next.js
|
|
gateway:
|
|
build: ./gateway # Spring Cloud Gateway
|
|
backend:
|
|
build: ./backend # Spring Boot
|
|
redis:
|
|
image: redis:7
|
|
rabbitmq:
|
|
image: rabbitmq:3.13-management
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 5. 통합 및 검증
|
|
|
|
### 5-1. 모듈별 검증 체크리스트
|
|
|
|
- [ ] 기존 SQL 결과와 신규 API 응답값 동일 여부 확인
|
|
- [ ] 페이징, 검색 조건 동작 확인
|
|
- [ ] 파일 첨부/다운로드 동작 확인
|
|
- [ ] 결재 워크플로우 흐름 검증
|
|
- [ ] 권한/메뉴 제어 동작 확인
|
|
- [ ] Excel 다운로드 동작 확인
|
|
|
|
### 5-2. 병행 운영 전략
|
|
|
|
```
|
|
1단계: 기존 Grails 운영 유지
|
|
2단계: 신규 시스템 완성 모듈부터 부분 교체
|
|
3단계: 전체 전환 후 기존 시스템 종료
|
|
4단계: DB를 Oracle → MariaDB 마이그레이션
|
|
```
|
|
|
|
---
|
|
|
|
## 작업량 예상
|
|
|
|
| 영역 | 난이도 | 이유 |
|
|
|------|--------|------|
|
|
| MyBatis SQL 재사용 | 낮음 | XML 거의 그대로 사용 가능 |
|
|
| SQL 이중화 (Oracle+MariaDB) | 중간 | databaseId로 병행 관리 |
|
|
| Spring Boot API 변환 | 중간 | 서비스 로직 Groovy → Java 변환 |
|
|
| JWT + Redis 인증 | 중간 | 세션 → Stateless 구조 변경 |
|
|
| 결재(tam) 로직 | 높음 | 워크플로우 복잡도 |
|
|
| Next.js 화면 재작성 | 높음 | 전체 UI 새로 작성 필요 |
|
|
| 파일 첨부 처리 | 중간 | 저장 경로/방식 재설계 필요 |
|
|
| Docker 인프라 구성 | 중간 | 서비스별 컨테이너화 |
|
|
|
|
---
|
|
|
|
## 진행 현황
|
|
|
|
- [x] NEW 폴더 및 하위 구조 생성
|
|
- [x] 마이그레이션 가이드 문서 작성 (기술 스택 확정)
|
|
- [ ] Spring Boot 백엔드 프로젝트 초기 세팅
|
|
- [ ] Next.js 프론트엔드 프로젝트 초기 세팅
|
|
- [ ] Phase 1: 현행 분석
|
|
- [ ] Phase 2: 백엔드 구축
|
|
- [ ] Phase 3: 프론트엔드 구축
|
|
- [ ] Phase 4: 인프라(Docker) 구성
|
|
- [ ] Phase 5: 통합 및 검증
|
|
- [ ] DB 마이그레이션 (Oracle → MariaDB)
|