eapim-portal/djb-docs/개발환경-준비-사항.md

개발환경 준비 사항

EAPIM Portal 개발에 필요한 도구와 런타임을 설치하고 검증하는 절차입니다. 처음 환경을 세팅하는 신규 개발자는 이 문서를 끝까지 따라 진행한 뒤 README.md의 "초기 세팅 가이드" 단계를 이어서 수행하세요.

---

0. 한눈에 보는 요구사항

구분	도구	권장 버전	비고
백엔드	JDK	1.8 (Zulu 8 권장)	sourceCompatibility=1.8
빌드	Gradle	8.7	gradlew 사용 금지 — 시스템 gradle 직접 사용
형상관리	Git	2.30 이상	SSH 키 등록 권장
DB	Oracle Client/접근	19c	개발은 192.168.240.177:1598
프론트엔드 빌드	Node.js	18 LTS 이상	SCSS 컴파일 전용
프론트엔드 빌드	npm	Node.js 함께 설치	sass 패키지 사용
(선택) 환경 변수	direnv	최신	.envrc 자동 로드
(선택) IDE	IntelliJ IDEA	2023.x 이상	Lombok / MapStruct 플러그인

---

1. JDK 8 설치

Java 8 (1.8) 호환이 필요합니다. Azul Zulu JDK 8 사용을 권장합니다.

macOS (Homebrew)

brew install --cask zulu@8
# 설치 후 경로 확인
/usr/libexec/java_home -v 1.8

Windows

1. Azul Zulu JDK 8 다운로드
2. MSI 설치 후 JAVA_HOME 환경변수 등록
3. PATH에 %JAVA_HOME%\bin 추가

검증

java -version       # 1.8.x
javac -version      # 1.8.x
echo $JAVA_HOME     # macOS/Linux
echo %JAVA_HOME%    # Windows

---

2. Gradle 8.7 설치

이 프로젝트는 gradlew 사용을 금지합니다. 시스템에 설치된 gradle 8.7을 직접 사용합니다.

macOS (Homebrew + SDKMAN 권장)

# SDKMAN 설치 (이미 있으면 생략)
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# Gradle 8.7 설치
sdk install gradle 8.7
sdk default gradle 8.7

Windows

1. Gradle 8.7 Binary-only 다운로드
2. C:\gradle\gradle-8.7 경로에 압축 해제
3. GRADLE_HOME=C:\gradle\gradle-8.7 환경변수 등록
4. PATH에 %GRADLE_HOME%\bin 추가

검증

gradle -v
# Gradle 8.7
# JVM:        1.8.x

---

3. (권장) direnv 사용

저장소 루트의 .envrc 가 JAVA_HOME, GRADLE_USER_HOME 등을 자동 주입합니다. 디렉터리 진입만으로 환경이 격리되므로 다른 프로젝트와 JDK가 섞이지 않습니다.

설치

# macOS
brew install direnv

# Windows (scoop)
scoop install direnv

셸 훅 등록 (한 번만)

# zsh
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

# bash
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

프로젝트에서 허용

cd /path/to/eapim-portal
direnv allow

---

4. Git 설치

macOS

brew install git

Windows

Git for Windows 설치. Git Bash가 함께 설치되어 README의 Bash 스니펫을 그대로 사용할 수 있습니다.

SSH 키 등록 (사내 Git 서버용)

ssh-keygen -t ed25519 -C "your.email@djbank.co.kr"
cat ~/.ssh/id_ed25519.pub
# 출력된 공개키를 사내 Git 서버(192.168.240.178:18081)에 등록

검증

git --version
ssh -T git@192.168.240.178 -p 18081

---

5. Oracle 19c 접근 정보

개발 환경에서는 별도 Oracle 설치 없이 사내 개발 DB에 접속합니다.

• Host: 192.168.240.177
• Port: 1599
• Schemas: EMSADM (Portal), AGWADM (Gateway)
• 상세 계정/패스워드는 사내 비밀번호 관리자에게 문의

스테이징/운영은 JNDI를 통해 접근합니다 — jdbc/dsOBP_EMS, jdbc/dsOBP_AGW.

DB 클라이언트 도구는 자유 선택 (DBeaver, DataGrip, SQL Developer 등).

---

6. Node.js & SASS 빌드 환경

SCSS 파일을 CSS로 컴파일하기 위해 Node.js 환경이 필요합니다. src/main/resources/static/css/main.css 는 SASS 컴파일 결과물이므로 반드시 SCSS 파일을 수정한 뒤 컴파일해야 합니다.

6.1 Node.js 설치 (LTS 18 이상)

macOS (Homebrew)

brew install node

macOS / Linux (nvm 권장 — 버전 관리 용이)

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
exec $SHELL -l

# Node.js LTS 설치
nvm install --lts
nvm use --lts

Windows

1. Node.js LTS 다운로드 후 MSI 설치
2. 또는 nvm-windows 사용

검증

node -v   # v18.x 이상
npm -v    # 9.x 이상

6.2 프로젝트 SASS 의존성 설치

cd /path/to/eapim-portal
npm install

package.json 의 devDependencies.sass (Dart Sass) 가 node_modules/ 에 설치됩니다.

6.3 SASS 빌드 명령어

# 1회 컴파일 (개발용, 들여쓰기 유지)
npm run sass:build

# 1회 컴파일 (배포용, minified)
npm run sass:build:minified

# 파일 변경 감지 후 자동 컴파일 (개발 중 권장)
npm run sass:watch

# 빌드 + minified 동시 생성
npm run build

6.4 SASS 컴파일 검증

ls -lh src/main/resources/static/css/main.css
ls -lh src/main/resources/static/css/main.min.css

파일이 갱신되었고 브라우저에서 스타일이 정상 적용되면 성공입니다.

6.5 SASS 작업 시 주의사항

• src/main/resources/static/css/main.css 직접 수정 금지 — 재컴파일 시 덮어씌워짐
• SCSS 파일은 src/main/resources/static/sass/ 하위에서만 작성
• 새 파일 추가 시 파일명 앞에 언더스코어(_) 필수 (_filename.scss)
• @import 대신 @use 사용 (Dart Sass 3.0 호환)

---

7. (선택) IDE 설정

IntelliJ IDEA

1. Lombok 플러그인 설치 → Settings → Plugins → Lombok
2. Annotation Processing 활성화 → Settings → Build → Compiler → Annotation Processors → Enable annotation processing
3. Gradle JVM 설정 → Settings → Build → Build Tools → Gradle → Gradle JVM 을 JDK 1.8 (Zulu) 로 지정
4. MapStruct 는 별도 플러그인 불필요 (annotation processor 만 활성화되어 있으면 됨)

VS Code

• Extension Pack for Java
• Lombok Annotations Support
• Sass (Syler) — SCSS 문법 하이라이팅

---

8. 최종 체크리스트

아래 명령이 모두 정상 동작하면 개발환경 준비가 완료된 것입니다.

java -version          # 1.8.x
gradle -v              # 8.7 / JVM 1.8
git --version
node -v                # v18 이상
npm -v
direnv version         # (선택)

이후 README.md 의 "초기 세팅 가이드" 로 이동해 프로젝트 클론과 의존 모듈 설치를 진행하세요.