================================================================================
  WBX Spring Framework - 개발환경 사전 설치 가이드
  Developer Quick Setup Guide v1.0
  아큐라시스템 | 2026년 3월
================================================================================

  이 문서는 WBX Spring Framework 개발을 시작하기 전에 필요한
  소프트웨어 설치 및 환경 설정을 안내합니다.

  TIP: scripts\install.bat (Windows) 또는 scripts/install.sh (Linux/macOS)를
       실행하면 JDK 자동 설치, 빌드 검증, .env 생성까지 한번에 처리됩니다.


--------------------------------------------------------------------------------
  1. 필수 소프트웨어
--------------------------------------------------------------------------------

  [1-1] JDK 21 (Eclipse Temurin LTS 권장)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  용도: Spring Boot 3.5 런타임

  * Windows
    winget install --id EclipseAdoptium.Temurin.21.JDK

  * macOS
    brew install --cask temurin@21

  * Ubuntu/Debian
    sudo apt update && sudo apt install -y temurin-21-jdk
    (Adoptium 저장소 미등록 시 https://adoptium.net 참고)

  * RHEL/Rocky
    sudo yum install -y temurin-21-jdk

  설치 확인:
    java -version
    → openjdk version "21.x.x" 이 출력되면 정상


  [1-2] Git
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  용도: 소스 코드 버전 관리, Gitea 저장소 연동

  * Windows
    winget install --id Git.Git

  * macOS
    brew install git

  * Linux
    sudo apt install -y git   (Ubuntu)
    sudo yum install -y git   (RHEL)

  설치 확인:
    git --version

  초기 설정:
    git config --global user.name "홍길동"
    git config --global user.email "hong@accurasoft.co.kr"


  [1-3] IDE (택 1)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  +------------------+----------------+------------------------------------+
  | IDE              | 권장 대상      | 핵심 장점                          |
  +------------------+----------------+------------------------------------+
  | IntelliJ IDEA    | 메인 개발      | Spring Boot 최적, 리팩터링, DB     |
  | VS Code          | 경량/FE 병행   | Extension Pack, DevContainer       |
  | Eclipse/STS      | 무료/레거시    | Spring Tool Suite 플러그인         |
  +------------------+----------------+------------------------------------+

  IntelliJ 필수 플러그인:
    - Spring Boot, Lombok, JPA Buddy, GitToolBox, .env, SonarLint
    - Settings > Build > Compiler > Annotation Processor 활성화

  VS Code 필수 Extension:
    - Java Pack, Spring Boot Pack, Lombok, Gradle, REST Client, GitLens


--------------------------------------------------------------------------------
  2. 선택 소프트웨어 (권장)
--------------------------------------------------------------------------------

  [2-1] Docker Desktop
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  용도: 로컬 개발용 DB(MySQL/PostgreSQL) + Redis를 컨테이너로 실행

  * Windows
    winget install --id Docker.DockerDesktop
    (설치 후 재부팅 필요)

  * macOS
    brew install --cask docker

  설치 확인:
    docker --version
    docker compose version

  주의: Docker Desktop은 대규모 기업(250명+/매출 $10M+) 유료 라이선스입니다.
        대안으로 Rancher Desktop, Podman Desktop 사용 가능합니다.


  [2-2] DB 직접 설치 (Docker 미사용 시)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  아래 중 프로젝트에 맞는 DBMS 1개를 선택하여 설치합니다.

  +------------------+----------+------------------------------------------+
  | DBMS             | 버전     | 설치                                     |
  +------------------+----------+------------------------------------------+
  | MySQL            | 8.0+     | winget install Oracle.MySQL               |
  | PostgreSQL       | 14+      | winget install PostgreSQL.PostgreSQL      |
  | Oracle           | 19c+     | 고객 DBA 설치/관리                       |
  | MSSQL            | 2019+    | winget install Microsoft.SQLServer.2022   |
  +------------------+----------+------------------------------------------+

  DB 생성 예시 (MySQL):
    CREATE DATABASE wbx_spring CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'wbxapp'@'localhost' IDENTIFIED BY 'password';
    GRANT ALL ON wbx_spring.* TO 'wbxapp'@'localhost';


  [2-3] Redis
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  용도: 캐시, 세션 저장소

  * Windows (Docker 권장, 네이티브 미지원)
    docker run -d -p 6379:6379 redis:7-alpine

  * macOS
    brew install redis && brew services start redis

  * Linux
    sudo apt install -y redis-server   (Ubuntu)
    sudo yum install -y redis          (RHEL)


--------------------------------------------------------------------------------
  3. 빠른 시작 (Quick Start)
--------------------------------------------------------------------------------

  아래 명령어를 순서대로 실행하면 개발 환경이 완성됩니다.

  [방법 A] Docker 사용 (권장, 3분)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # 1) 소스 클론
    git clone https://git.wbx.kr/accura/wbx-spring-core.git
    cd wbx-spring-core

    # 2) 설치 스크립트 실행 (JDK 자동 설치 + 빌드 + .env 생성)
    scripts\install.bat              (Windows)
    ./scripts/install.sh             (Linux/macOS)

    # 3) Docker로 MySQL + Redis 시작
    docker compose -f docker-compose-dev.yml up -d

    # 4) .env 파일 수정 (DB 비밀번호를 docker-compose 설정에 맞춤)
    #    DB_USER=wbxapp
    #    DB_PASS=password
    #    JWT_SECRET=dev-secret-key-for-local-development-only

    # 5) 앱 실행
    gradlew.bat bootRun              (Windows)
    ./gradlew bootRun                (Linux/macOS)

    # 6) 확인
    http://localhost:8080/health      → {"status":"UP"}
    http://localhost:8080/swagger-ui   → API 문서
    http://localhost:8080/admin/login  → 관리 콘솔


  [방법 B] DB 직접 설치 (Docker 없이)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # 1~2) 위와 동일 (클론 + install 스크립트)

    # 3) MySQL/PostgreSQL 설치 후 DB 생성
    #    위 [2-2] 참고

    # 4) Redis 설치
    #    위 [2-3] 참고

    # 5) .env 파일을 실제 DB 정보에 맞게 수정

    # 6~7) 앱 실행 및 확인 (위와 동일)


--------------------------------------------------------------------------------
  4. Docker Compose 서비스 구성
--------------------------------------------------------------------------------

  docker-compose-dev.yml 에 포함된 서비스:

  +------------------+--------+----------+------------------------------+
  | 서비스           | 포트   | 계정     | 비고                         |
  +------------------+--------+----------+------------------------------+
  | MySQL 8.0        | 3306   | wbxapp   | PW: password (기본 프로필)   |
  |                  |        |          | root PW: rootpassword        |
  | PostgreSQL 16    | 5432   | wbxapp   | PW: password (--profile pg)  |
  | Redis 7          | 6379   | -        | 인증 없음 (개발용)           |
  +------------------+--------+----------+------------------------------+

  프로필별 실행:
    docker compose -f docker-compose-dev.yml up -d                # MySQL + Redis
    docker compose -f docker-compose-dev.yml --profile pg up -d   # PostgreSQL + Redis


--------------------------------------------------------------------------------
  5. .env 설정 가이드
--------------------------------------------------------------------------------

  .env 파일은 install 스크립트가 자동 생성합니다.
  아래 항목을 환경에 맞게 수정하세요.

  [필수 수정]
    JWT_SECRET              운영: 256bit 이상 랜덤 키
                            개발: dev-secret-key-for-local-development-only
    DB_PASS                 실제 DB 비밀번호

  [환경별 수정]
    SPRING_PROFILES_ACTIVE  프로필 조합 (아래 참고)
    DB_HOST / DB_PORT       DB 서버 주소
    CORS_ORIGINS            프론트엔드 URL

  [프로필 조합 예시]
    로컬 개발 (MySQL)     : local,mysql
    로컬 개발 (PostgreSQL): local,postgresql
    운영 (Azure + MSSQL)  : prod,azure,mssql
    운영 (AWS + PG)       : prod,aws,postgresql
    운영 (On-Premise)     : prod,mysql  또는  prod,oracle


--------------------------------------------------------------------------------
  6. 네트워크 포트 요약
--------------------------------------------------------------------------------

  +--------+------------------+------------------------------------------+
  | 포트   | 서비스           | 비고                                     |
  +--------+------------------+------------------------------------------+
  | 8080   | Spring Boot      | API, Admin, Health, Swagger              |
  | 3306   | MySQL            | 기본 DB (mysql 프로필)                   |
  | 5432   | PostgreSQL       | 대안 DB (postgresql 프로필)              |
  | 6379   | Redis            | 캐시, 세션                               |
  | 8001   | WBX FastAPI      | 선택, 그룹웨어 동시 운영 시              |
  +--------+------------------+------------------------------------------+


--------------------------------------------------------------------------------
  7. 트러블슈팅
--------------------------------------------------------------------------------

  Q: install.bat 실행 시 "java 명령어 없음"
  A: 스크립트가 자동으로 JDK 21을 설치합니다. 실패 시 수동 설치:
     winget install --id EclipseAdoptium.Temurin.21.JDK

  Q: gradlew.bat 실행 시 "not recognized"
  A: 프로젝트 루트(wbx-spring-core/) 에서 실행하세요.
     또는 scripts\run-install.bat 을 사용하세요.

  Q: bootRun 시 DB 연결 실패
  A: 1) docker compose -f docker-compose-dev.yml up -d 로 DB 시작
     2) .env 파일의 DB_HOST, DB_PORT, DB_PASS 확인
     3) telnet localhost 3306 으로 연결 가능 여부 확인

  Q: Redis 연결 실패
  A: docker ps 에서 redis 컨테이너 실행 중인지 확인
     또는 Redis를 직접 설치하고 기본 포트(6379) 확인

  Q: Lombok 관련 컴파일 에러
  A: IDE에서 Annotation Processor 활성화 필요
     IntelliJ: Settings > Build > Compiler > Annotation Processors > Enable

  Q: 포트 충돌 (8080 이미 사용 중)
  A: netstat -ano | findstr :8080 으로 프로세스 확인 후 종료
     또는 application.yml에서 server.port 변경


--------------------------------------------------------------------------------
  8. 참고 문서
--------------------------------------------------------------------------------

  docs/WBX_Spring_Framework_개발자가이드.pdf         개발자 상세 가이드
  docs/WBX_Spring_Framework_설치가이드_OnPremise.pdf  운영 서버 설치 가이드
  docs/WBX_Spring_Framework_설치가이드_Cloud.pdf      클라우드 배포 가이드


================================================================================
  문의: accura@accurasoft.co.kr
================================================================================
