# 킨텍스 자동전시시스템 — 빌드/실행 개요

> **WISE(UIWS) 참조** — 빌드·배포 흐름(프론트 vite build → 백엔드 번들 / systemd / webhook 자동배포)은 `workspace/uiws/deploy/README_배포.md`·`DEV_HANDOFF.md`를 따른다.
> 본 문서는 **빌드/실행 개요**만 다룬다. 상세 CI/CD 파이프라인(Gitea webhook·deploy_server·systemd·nginx·롤백)은 **Phase E `kintex-devops-dev`** 산출물이 정본이다. 운영 서버·포트는 **G2 게이트**(GUARDiA 인프라와 별개 도메인) 확정 후.

---

## 1. 산출물 구성

킨텍스는 **3개 실행 단위**로 구성된다:

| 단위 | 빌드 | 산출물 | 실행 |
|------|------|--------|------|
| 백엔드 | `./gradlew bootJar` (JDK17) | `build/libs/kintex-*.jar` | `java -jar`(systemd 권장) |
| 프론트(웹) | `npm run build` (Node 18+, Vite) | `dist/`(역할별 번들) | nginx 정적 서빙(SPA 폴백) |
| 나노바나나 워커 | (Python, 빌드 없음) | `tools/nanobanana` 모듈 | 큐 소비 데몬(별도 서비스) |

> 프론트 dist를 백엔드 static에 번들하는 단일 jar 패키징(GUARDiA 표준)도 가능하나, 킨텍스는 **역할별 프론트 번들 분리**(PLANNING §2-1)이므로 nginx 정적 서빙 + 백엔드 API 분리를 기본으로 한다(Phase A SA가 배포 토폴로지 확정).

---

## 2. 로컬 빌드/실행

환경변수·설치는 [`ENV_SETUP.md`](ENV_SETUP.md) 참조.

```bash
# 백엔드
cd src/backend
./gradlew build              # 컴파일+테스트
./gradlew bootRun            # 개발 실행 (또는 java -jar build/libs/kintex-*.jar)

# 프론트
cd ../frontend
npm install
npm run dev                  # 개발 서버(프록시 → /api)
npm run build                # dist/ 생성

# 나노바나나 워커 (G1 승인 후 실호출)
cd ../../tools/nanobanana
pip install google-genai Pillow
python -m tools.nanobanana.worker
```

---

## 3. 빌드 게이트 (push 전 — WISE 관행)

WISE `.githooks/pre-push` 패턴을 준용해 파이프라인을 보호한다:

1. 시크릿 파일 커밋 차단(`.env`·`*.key`·`*-adminsdk-*.json` — gitignore 유지)
2. Flyway 마이그레이션 번호 충돌 검사(신규 = 최대+1)
3. 변경분 백엔드 `compileJava` / 프론트·워커 `tsc`·lint — **실패 시 push 차단**
4. 자동배포 경고(파이프라인 연결 시 push=배포 트리거)

---

## 4. 배포 흐름 (개요 — 상세는 Phase E)

GUARDiA 표준 배포 파이프라인 준용:

```
workspace/kintex ── git push ──> Gitea(zio/kintex) ── webhook ──> deploy_server
                                    └─> 빌드(gradlew bootJar · vite build) → Flyway 마이그 → jar 재기동 · dist 배포 → 헬스 게이트(GET /health)
```

- **Fail-Safe**: 백업 → 배포 → 헬스체크(200) → 실패 시 롤백(이전 jar 유지). 깨진 jar가 서버를 죽이지 않도록 clean bootJar 검증 후 교체(WISE 배포 자기방어 패턴).
- **systemd**: 백엔드 jar·워커 데몬을 유닛으로 등록(부팅 자동기동·재시작). AI env drop-in(`ANTHROPIC_API_KEY`·`ADMIN_PASSWORD_ENC`)은 표준 프레임워크 §7 방식.
- **nginx**: `<kintex-domain>` vhost → `/`=프론트 정적, `/api/`·`/ws`=백엔드 포트. TLS는 certbot. (도메인·포트 = G2 확정.)
- **운영 배포는 소유자 승인 필수.**

---

## 5. 선행 게이트

| 게이트 | 내용 | 영향 |
|--------|------|------|
| **G1** | 나노바나나(Gemini) 외부 호출 승인(PLANNING R12) | 워커 실이미지 생성·M5 배포. 미승인 시 목/degraded |
| **G2** | 배포 대상 서버·포트(별개 도메인) | Phase E 배포 착수 전 |

---

## 6. 참조

- 환경 구축: [`ENV_SETUP.md`](ENV_SETUP.md) · 개발 표준: [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md)
- 구현 백로그(Phase E 배포): [`IMPLEMENTATION_BACKLOG.md`](IMPLEMENTATION_BACKLOG.md)
- WISE 배포 원본(참조): `workspace/uiws/deploy/README_배포.md`·`workspace/uiws/DEV_HANDOFF.md`
- 표준 프레임워크 배포: `workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md` §7