share job

2026-04-09 11:12:12 +09:00
commit f8427ee1d0
193 changed files with 23830 additions and 0 deletions
--- a/MIGRATION_GUIDE.md
+++ b/MIGRATION_GUIDE.md
@@ -0,0 +1,339 @@
+# 그룹웨어 마이그레이션 가이드
+
+## 현행 시스템 → 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)