KJBank 흔적 삭제

2026-06-02 09:27:16 +09:00
parent ba5b2e61a5
commit a0ea62f8cc
30 changed files with 557 additions and 2817 deletions
@@ -0,0 +1,273 @@
+# 개발환경 준비 사항
+
+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) 의 "초기 세팅 가이드" 로 이동해 프로젝트 클론과 의존 모듈 설치를 진행하세요.