ga-commission-system/실행방법.md

# GA 수수료 정산 시스템 — 실행 방법

이 문서 하나만 보면 프로젝트를 처음부터 끝까지 실행할 수 있습니다.

---

## 1. 제일 쉬운 방법 (이것만 기억하세요)

1. `C:\Users\kyu\Desktop\ga_pro\ga-commission-system` 폴더를 엽니다.
2. **`실행.bat` 파일을 더블클릭**합니다.
3. 검은 창 2개가 열립니다. **끄지 말고** 1~2분 기다립니다.
4. 인터넷 브라우저(크롬 등)를 열고 주소창에 입력: **http://localhost:3000**
5. 로그인 — 아이디 `admin` / 비밀번호 `admin1234!`

끝입니다. 이게 "한 번에 실행"하는 방법입니다.

> 종료하려면 열려 있는 **검은 창 2개를 닫으면** 됩니다.

---

## 2. 처음 한 번만 — 준비물 확인

이 PC에는 이미 다 설치되어 있어서 **추가 설치는 필요 없습니다.** 참고용으로만 적어둡니다.

| 준비물 | 용도 | 현재 상태 |
|---|---|---|
| Java 17 | 백엔드 실행 | 설치됨 (17.0.11) |
| Node.js | 프론트엔드 실행 | 설치됨 (v24) |
| 데이터베이스 | 데이터 저장 | 원격 서버 사용 (아래 참고) |

**중요 — 데이터베이스 서버가 켜져 있어야 합니다.**
이 시스템은 데이터를 `192.168.0.60` 서버의 PostgreSQL에 저장합니다.
그 서버(또는 기기)가 꺼져 있으면 백엔드가 데이터를 못 읽어 화면이 비어 보이거나 오류가 납니다.
→ 실행 전에 `192.168.0.60` 기기가 켜져 있는지 확인하세요.

---

## 3. 실행하기

### 방법 A — `실행.bat` 더블클릭 (권장)

`실행.bat`을 더블클릭하면 자동으로 두 가지가 동시에 켜집니다.

- **백엔드 창** : 제목 `GA Backend (ga-api 8082)` — 서버 프로그램
- **프론트엔드 창** : 제목 `GA Frontend (3000)` — 화면(웹페이지)

각 창에 아래 글자가 보이면 준비 완료입니다.

- 백엔드 창: `Started GaApiApplication`
- 프론트엔드 창: `Local:  http://localhost:3000`

> 처음 실행하면 다운로드/빌드 때문에 **몇 분** 걸립니다. 두 번째부터는 빠릅니다.

### 방법 B — 손으로 직접 실행 (참고용)

`실행.bat`이 안 될 때를 위해 적어둡니다. 창을 **2개** 열어서 각각 입력하세요.

**창 1 — 백엔드** (`ga-commission-system` 폴더에서):
```
gradlew.bat :ga-api:bootRun
```

**창 2 — 프론트엔드** (`ga-commission-system\ga-frontend` 폴더에서):
```
npm install
npm run dev
```

---

## 4. 접속 & 로그인

- 주소: **http://localhost:3000**
- 아이디: `admin`
- 비밀번호: `admin1234!`  (관리자 계정, 모든 메뉴 권한)

브라우저에서 `localhost:3000`은 화면이고, 화면이 데이터를 요청하면
자동으로 백엔드(`localhost:8082`)로 전달됩니다. 그래서 주소는 `3000` 하나만 기억하면 됩니다.

---

## 5. 종료하기

- 열려 있는 **검은 창 2개를 그냥 닫으면** 종료됩니다.
- 또는 각 창에서 `Ctrl + C` 를 누르고 `Y` 입력.

---

## 6. 무엇이 어떻게 도는지 (구조)

```
   [브라우저]  http://localhost:3000
        |
        |  화면이 데이터를 요청 (/api/...)
        v
   [프론트엔드]  ga-frontend  (포트 3000)   ← 검은 창 2번
        |
        |  /api 요청을 백엔드로 전달
        v
   [백엔드]  ga-api  (포트 8082)            ← 검은 창 1번
        |
        |  데이터 읽기/쓰기
        v
   [데이터베이스]  PostgreSQL
   192.168.0.60 : 55432  (원격 서버, trading_ai/ga)
```

- 창이 2개인 이유: 화면(프론트)과 서버(백엔드)는 별개 프로그램이라 따로 켭니다.
- 데이터베이스는 이 PC가 아니라 **원격 서버**에 있어서 따로 켜지 않습니다(이미 운영 중).

---

## 7. 문제가 생기면

| 증상 | 원인 / 해결 |
|---|---|
| 화면이 안 열림 (`localhost:3000` 접속 안 됨) | 프론트엔드 창에 `http://localhost:3000` 글자가 나올 때까지 더 기다리세요. |
| 화면은 열리는데 데이터가 비어있음 / 로그인 오류 | 백엔드 창이 준비됐는지 확인. 그리고 `192.168.0.60` DB 서버가 켜져 있는지 확인. |
| 백엔드 창에 `Port 8082 ... in use` | 이미 백엔드가 켜져 있다는 뜻. 그 창은 닫아도 됨 (기존 것이 동작 중). |
| 백엔드 창에 `Connection refused` / DB 관련 오류 | `192.168.0.60` DB 서버 기기가 꺼져 있음 → 그 기기를 켜고 다시 실행. |
| `실행.bat` 더블클릭해도 아무 일도 없음 | 방법 B(손으로 직접 실행)로 하세요. |
| 첫 실행이 너무 오래 걸림 | 정상입니다. 다운로드+빌드로 처음엔 3~5분 걸릴 수 있어요. |

---

## 8. 상태 확인용 명령 (선택)

문제 진단이 필요할 때만 사용. `ga-commission-system` 폴더에서:

```
# 데이터베이스 서버가 켜져 있는지 + 현재 버전 확인
python ..\check_db_status.py

# 백엔드 주요 기능이 정상 동작하는지 점검
python smoke_v78.py
```

---

## 9. 참고 — Docker 방식 (지금은 사용 안 함)

`docker-compose.yml` 파일이 있어서, Docker가 설치돼 있다면
`docker compose up` 한 줄로 DB까지 포함해 전부 띄울 수 있습니다.
**단, 이 경우 데이터베이스가 빈 상태로 새로 만들어집니다**(원격 운영 DB와 다름).
현재 이 PC에는 Docker가 설치돼 있지 않고, 운영 데이터는 원격 DB에 있으므로
**위 1번 방법(`실행.bat`)을 사용하세요.**

---

## 요약 한 줄

> **`ga-commission-system\실행.bat` 더블클릭 → 1~2분 대기 → 브라우저 `http://localhost:3000` → `admin` / `admin1234!`**