================================================================================
  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 컨테이너 사용 시에만 필요)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  용도: 로컬 개발용 DB(MySQL/PostgreSQL)를 컨테이너로 실행
        ※ Redis는 Embedded Redis가 자동 구동되므로 Docker 불필요

  * 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 mos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'jsh'@'%' IDENTIFIED BY 'jsh@';
    GRANT ALL ON mos.* TO 'jsh'@'%';


  [2-3] Node.js (프론트엔드 개발 시 필요)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  용도: WTM 프론트엔드 개발 서버 실행 (Vue 3 또는 React 18)

  * Windows
    winget install --id OpenJS.NodeJS.LTS

  * macOS
    brew install node@22

  * Linux
    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
    sudo apt install -y nodejs

  설치 확인:
    node -v   → v22.x.x
    npm -v    → 10.x.x

  프론트엔드 선택:
  +----------------------+------------------+----------+---------------------+
  | 프로젝트             | 프레임워크       | 포트     | UI 라이브러리       |
  +----------------------+------------------+----------+---------------------+
  | wtm-frontend-vue     | Vue 3 + Vite     | 5173     | PrimeVue 4          |
  | wtm-frontend-react   | React 18 + Vite  | 5174     | PrimeReact 10       |
  +----------------------+------------------+----------+---------------------+

  두 프론트엔드는 동일한 백엔드 API(wtm-api :8081)에 연결됩니다.
  프로젝트 상황에 맞는 프레임워크를 선택하세요.

  빠른 시작:
    # Vue 3 버전
    cd wtm-frontend-vue
    npm install && npm run dev       → http://localhost:5173

    # React 18 버전
    cd wtm-frontend-react
    npm install && npm run dev       → http://localhost:5174


  [2-4] Redis (설치 불필요)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  용도: 캐시, 세션 저장소

  ※ WBX Spring Framework에 Embedded Redis가 내장되어 있어 별도 설치가
    필요하지 않습니다. 앱 시작 시 다음 순서로 자동 동작합니다:

    1) 외부 Redis 감지 → 그대로 사용 (운영 환경)
    2) 외부 Redis 없음 → Embedded Redis 자동 시작 (개발 환경)
    3) Embedded Redis 실패 → 인메모리 캐시 전환 (최후 안전장치)

  운영 환경에서 외부 Redis를 사용하려면 .env에 설정:
    SPRING_DATA_REDIS_HOST=redis.company.com


--------------------------------------------------------------------------------
  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는 Embedded Redis 자동 구동)
    docker compose -f docker-compose-dev.yml up -d

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

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

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

    [WTM 프로젝트 사용 시]
    cd wtm-api
    gradlew.bat :wtm-api:bootRun      (Windows)
    ./gradlew :wtm-api:bootRun        (Linux/macOS)

    http://localhost:8081/actuator/health      → {"status":"UP"}
    http://localhost:8081/swagger-ui   → WTM API 문서
    http://localhost:8081/admin/login  → WTM 관리 콘솔

    [WTM 프론트엔드 실행 — Vue 3 또는 React 18 중 택 1]
    # Vue 3 버전
    cd wtm-frontend-vue
    npm install && npm run dev
    http://localhost:5173              → WTM 프론트엔드 (Vue 3)

    # React 18 버전
    cd wtm-frontend-react
    npm install && npm run dev
    http://localhost:5174              → WTM 프론트엔드 (React 18)


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

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

    # 3) MySQL/PostgreSQL 설치 후 DB 생성
    #    위 [2-2] 참고
    #    (Redis는 Embedded Redis 자동 구동 — 설치 불필요)

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

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


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

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

  +------------------+--------+----------+------------------------------+
  | 서비스           | 포트   | 계정     | 비고                         |
  +------------------+--------+----------+------------------------------+
  | MySQL 8.0        | 3306   | jsh      | PW: jsh@ (기본 프로필)       |
  |                  |        |          | root PW: rootpassword        |
  | PostgreSQL 16    | 5432   | jsh      | PW: jsh@ (--profile pg)      |
  | Redis 7          | 6379   | -        | Embedded Redis 자동 구동     |
  +------------------+--------+----------+------------------------------+

  프로필별 실행:
    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 (Vue: 5173, React: 5174)

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


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

  +--------+------------------+------------------------------------------+
  | 포트   | 서비스           | 비고                                     |
  +--------+------------------+------------------------------------------+
  | 8080   | wbx-spring-core  | API, Admin, Health, Swagger              |
  | 8081   | wtm-api          | WTM API, Admin, Swagger                  |
  | 3306   | MySQL            | 기본 DB (mysql 프로필)                   |
  | 5432   | PostgreSQL       | 대안 DB (postgresql 프로필)              |
  | 6379   | Redis            | Embedded Redis 자동 구동 (별도 설치 불필요)|
  | 5173   | wtm-frontend-vue | Vue 3 개발 서버                          |
  | 5174   | wtm-frontend-react| React 18 개발 서버                      |
  | 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: Embedded Redis가 자동 구동됩니다. 별도 조치 불필요.
     로그에 "[WBX] Embedded Redis 시작" 출력 시 정상 동작.
     포트 6379가 이미 사용 중이면 외부 Redis를 자동 감지하여 사용합니다.

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

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

  Q: 프론트엔드(Vue/React) npm install 실패
  A: Node.js 22 LTS가 설치되어 있는지 확인:  node -v
     node_modules 삭제 후 재설치: rm -rf node_modules && npm install

  Q: 프론트엔드에서 API 호출 시 CORS 에러
  A: wtm-api의 application.yml에서 CORS 설정 확인:
     cors.allowed-origins에 http://localhost:5173, http://localhost:5174 포함 필요
     또는 .env에서 CORS_ORIGINS 설정

  Q: Vue(5173)와 React(5174) 동시 실행 가능한가?
  A: 네, 포트가 다르므로 동시 실행 가능합니다. 둘 다 동일한 wtm-api(:8081)에
     연결되며 API 프록시가 각각 설정되어 있습니다.


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

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


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