# 그룹웨어 마이그레이션 가이드
## 현행 시스템 → 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 → 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)