# 킨텍스 자동전시시스템 — 개발환경 구축 가이드

> **WISE(UIWS) 참조** — `workspace/uiws`의 `backend/README.md`·`db/README_DB연동.md`·`DEV_HANDOFF.md` 세팅 절차를 킨텍스 스택(MyBatis·PostGIS·Redis·나노바나나 Python 워커)에 맞춰 정리했다.
> ⚠️ 본 문서의 환경변수 **이름은 표준 컨벤션**(신규 코드가 준수할 규약)이며, 실제 비밀값·서버 포트는 저장소에 두지 않는다(Phase A SA/DEV 및 사내 비밀관리에서 확정).

---

## 1. 사전 요구 도구

| 도구 | 버전 | 용도 |
|------|------|------|
| **JDK 17** | 17.x (LTS) | Spring Boot 3.x 백엔드 빌드/실행(`gradlew`) |
| **Node.js** | 18+ (LTS) | Vite 빌드(Node 16은 vite build 불가 — WISE 함정) |
| **npm** | Node 동봉 | 프론트 의존성 |
| **PostgreSQL** | 15+/16 | `kintex_db` |
| **PostGIS** | 3.x | 공간 확장(부스 polygon·트렌치 point·배선 LineString) |
| **Redis** | 6+/7 | 작업 큐(RenderJob·서류·알림) |
| **Python** | 3.11+ | 나노바나나 워커 사이드카 |
| **Git** | 2.x | Gitea(zio/kintex) |

> Gradle Wrapper(`gradlew`)가 없으면 로컬 Gradle 8.x로 `gradle wrapper --gradle-version 8.7` 1회 실행해 생성(WISE 관행).

---

## 2. 초기 세팅

```bash
git clone <gitea>/zio/kintex.git
cd kintex

# 백엔드 (JDK17)
cd src/backend && ./gradlew build          # Phase B-0 스캐폴드 이후

# 프론트 (Node 18+)
cd ../frontend && npm install

# 나노바나나 Python 워커
cd ../../tools/nanobanana
pip install google-genai Pillow
```

---

## 3. PostgreSQL + PostGIS (`kintex_db`)

WISE와 동일하게 **공유 PostgreSQL 인스턴스에 전용 DB + 전용 계정**을 두어 타 솔루션과 물리 분리한다.

```sql
-- 관리자(postgres/sudo) 권한으로 실행
CREATE ROLE kintex LOGIN PASSWORD '<개발용-임시-변경대상>'
  NOSUPERUSER NOCREATEDB NOCREATEROLE;
CREATE DATABASE kintex_db OWNER kintex ENCODING 'UTF8';
-- kintex_db 접속 후 PostGIS 활성화
\c kintex_db
CREATE EXTENSION IF NOT EXISTS postgis;
```

- 콜레이션은 서버 인스턴스 컨벤션에 맞춤(WISE는 `en_US.UTF-8`; UTF8이라 한글 저장/조회 정상).
- 스키마/시드는 **Flyway 순번 마이그레이션**(백로그 B-0)으로 적용. `ddl` 수동 검증이 필요하면 `SET ROLE kintex;` 후 마이그 SQL 실행.
- **원격 DB 접속(개발 PC)**: 5432가 외부 차단이면 SSH 로컬 포워딩 —
  ```bash
  ssh -L 5432:localhost:5432 <shell계정>@<db-host> -N
  # 앱은 jdbc:postgresql://localhost:5432/kintex_db 로 접속
  ```

---

## 4. Redis

로컬 기본 포트 6379. 큐 키 예: `kintex:renderjob:queue`(백엔드 발행 → Python 워커 소비). 개발 중 워커 미가동 시 큐잉·상태는 동작(발행까지).

---

## 5. 환경변수 목록 (표준 컨벤션)

> 비밀값은 **하드코딩 금지** — 모두 환경변수/`application.yml` 프로퍼티로 주입. `.env`·`*.key`는 gitignore.

### 5-1. 백엔드(Spring Boot)

| 변수 | 필수 | 설명 |
|------|------|------|
| `KINTEX_DB_PASSWORD` | **필수** | PostgreSQL `kintex` 계정 비밀번호 |
| `KINTEX_JWT_SECRET` | 권장 | JWT HMAC(HS256) 시크릿(최소 32바이트). 미설정 시 개발용 기본값(운영 금지) |
| `SERVER_PORT` | 선택 | 백엔드 포트(운영 포트는 G2 게이트에서 확정 — GUARDiA 인프라와 별개 도메인) |
| `REDIS_HOST` / `REDIS_PORT` | 선택 | 기본 `localhost` / `6379` |
| `RENDER_WORKER_TOKEN` | 워커 연동 시 | `/api/internal/render/callback` 공유 시크릿(`X-Worker-Token`) |
| `ANTHROPIC_API_KEY` | AI(Claude) 사용 시 | Claude 텍스트 AI. 키는 env only — DB/코드/로그/커밋/응답 기록 금지, 실패 시 Ollama 폴백 |
| `ADMIN_PASSWORD_ENC` / `ADMIN_KEY_FILE` | 운영 | admin 비번 AES-256-GCM 암호문 + 별도 키파일(root 600) → 기동 시 BCrypt 재시드 |
| `SMTP_HOST`·`SMTP_PORT`·`SMTP_USERNAME`·`SMTP_PASSWORD`·`KINTEX_MAIL_FROM` | 메일 발송 시 | 2차 인증 EMAIL 코드·알림 발송. 미설정 시 로컬 로그 모드 |

### 5-2. 나노바나나 Python 워커

| 변수 | 필수 | 설명 |
|------|------|------|
| `GEMINI_API_KEY` | 실호출 시(**G1 승인 대상**) | Gemini 이미지 생성 키. **워커에서만** 로드 — 백엔드 미취급, 코드/로그/커밋 금지 |
| `NANOBANANA_MODEL` | 선택 | 기본 `gemini-3.1-flash-image-preview` 오버라이드 |

> **G1 게이트**: Gemini 외부 호출은 소유자 승인 대상. 미승인 시 워커는 목/degraded로 동작(import·구조 성립, 실이미지 미생성).

---

## 6. 실행

```bash
# 백엔드
export KINTEX_DB_PASSWORD='****'
export KINTEX_JWT_SECRET='****-32bytes이상****'
cd src/backend && ./gradlew bootRun          # 또는 java -jar build/libs/kintex-*.jar

# 프론트 (개발 서버 — axios baseURL=/api, 프록시로 백엔드 연결)
cd src/frontend && npm run dev

# 나노바나나 워커 (G1 승인 후 실호출; 미승인 시 목)
export GEMINI_API_KEY='****'
python -m tools.nanobanana.worker      # 큐 소비 → 콜백(RENDER_WORKER_TOKEN)
```

헬스체크: `GET /health` → `{ "success": true, "data": { "status": "UP", "service": "kintex-backend" } }`.

---

## 7. 참조

- 빌드/배포 개요: [`BUILD_DEPLOY.md`](BUILD_DEPLOY.md)
- 개발 표준: [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md)
- 나노바나나 워커: [`../tools/nanobanana/README.md`](../tools/nanobanana/README.md)
- WISE 세팅 원본(참조): `workspace/uiws/backend/README.md`·`workspace/uiws/db/README_DB연동.md`
