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

# 개발환경 준비 사항

EAPIM Portal 개발에 필요한 도구와 런타임을 설치하고 검증하는 절차입니다.
처음 환경을 세팅하는 신규 개발자는 이 문서를 끝까지 따라 진행한 뒤 [README.md](../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)

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

### Windows

1. [Azul Zulu JDK 8 다운로드](https://www.azul.com/downloads/?version=java-8-lts&package=jdk)
2. MSI 설치 후 `JAVA_HOME` 환경변수 등록
3. `PATH`에 `%JAVA_HOME%\bin` 추가

### 검증

```bash
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 권장)

```bash
# 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 다운로드](https://gradle.org/releases/)
2. `C:\gradle\gradle-8.7` 경로에 압축 해제
3. `GRADLE_HOME=C:\gradle\gradle-8.7` 환경변수 등록
4. `PATH`에 `%GRADLE_HOME%\bin` 추가

### 검증

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

---

## 3. (권장) direnv 사용

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

### 설치

```bash
# macOS
brew install direnv

# Windows (scoop)
scoop install direnv
```

### 셸 훅 등록 (한 번만)

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

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

### 프로젝트에서 허용

```bash
cd /path/to/eapim-portal
direnv allow
```

---

## 4. Git 설치

### macOS

```bash
brew install git
```

### Windows

[Git for Windows](https://git-scm.com/download/win) 설치. Git Bash가 함께 설치되어 README의 Bash 스니펫을 그대로 사용할 수 있습니다.

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

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

### 검증

```bash
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)

```bash
brew install node
```

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

```bash
# 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 다운로드](https://nodejs.org/en/download) 후 MSI 설치
2. 또는 [nvm-windows](https://github.com/coreybutler/nvm-windows/releases) 사용

#### 검증

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

### 6.2 프로젝트 SASS 의존성 설치

```bash
cd /path/to/eapim-portal
npm install
```

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

### 6.3 SASS 빌드 명령어

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

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

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

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

### 6.4 SASS 컴파일 검증

```bash
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. 최종 체크리스트

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

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

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