6caf43e1ed
- harness·zio-harness·proposal-builder·zioinfo → plugins/zioinfo (git mv 히스토리 보존) - 스킬 4·커맨드 3(/zioinfo:pmo·proposal·wiki)·에이전트 15·graphify 훅·knowledge 통합 - 신규: /zioinfo:wiki (graphify LLM wiki — graphify-out/wiki/ 커뮤니티별 아티클) - 신규: ZIO WISE 테마 (themes/zioinfo.json, experimental) - manifest 최신화: $schema·displayName(ZIO INFOTECH Suite)·experimental.themes - marketplace.json 단일 엔트리, 루트 plugin.json 제거 - CLAUDE.md·PROJECT_MAP·docs/plugins.md·README 3종·CHANGELOG·설치가이드 pptx 재구성 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
128 lines
5.4 KiB
Markdown
128 lines
5.4 KiB
Markdown
# 킨텍스 자동전시시스템 — 개발환경 구축 가이드
|
|
|
|
> **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`
|