kintex/CLAUDE.md

# KINTEX AI 시스템 (킨텍스 전시관리 AI)

킨텍스(KINTEX, 한국국제전시장) 전시 운영 전 과정을 AI로 자동화하는 시스템 프로젝트.
부스 배치 설계 → 인테리어/장치 공사 → 네트워크 배선 → 전기/조명 설계 → **나노바나나(Gemini 이미지 생성)로 시공 후 결과 사진 시각화**까지를 하나의 파이프라인으로 다룬다.

## 프로젝트 구조

```
kintex/
├── CLAUDE.md                  # 이 파일 — 프로젝트 규칙과 에이전트 오케스트레이션
├── .claude/
│   ├── agents/                # 서브에이전트 정의 (기획/디자인/개발/시각화/검증)
│   └── skills/                # 스킬 (나노바나나 연동 등)
├── docs/
│   ├── analysis/              # 킨텍스 웹사이트 분석, ReRoomAI 소스 분석
│   ├── PLANNING.md            # 시스템 기획서 (기획 에이전트 산출물)
│   └── design.md              # UI 디자인 스펙 — Google Stitch 전달용 (디자인 에이전트 산출물)
├── tools/
│   └── nanobanana/            # Gemini 이미지 생성(나노바나나) 연동 모듈
└── src/                       # 서비스 구현 (백엔드/프론트) — 이후 단계
```

## 기술 스택 (확정 2026-07-11 · 사용자 지정)

| 레이어 | 기술 |
|--------|------|
| 프론트엔드 | **React 18/19 + Vite + TypeScript** (반응형: 데스크톱=설계/에디터, 모바일=조회·승인·현장) |
| 백엔드 | **Spring Boot 3.x (Java 17) + MyBatis** — REST + WebSocket(STOMP), 룰 엔진·배치/배선 엔진 |
| DB | **PostgreSQL (+ PostGIS)** — 부스 폴리곤·트렌치 포인트·배선 LineString 공간 데이터 |
| 비동기 | Redis 작업 큐 (RenderJob·서류·알림) |
| 이미지 생성 | **나노바나나 Python 워커 사이드카** (`tools/nanobanana`, google-genai + `gemini-3.1-flash-image-preview`) — Spring이 큐로 트리거, 결과는 오브젝트 스토리지 + WebSocket 완료 푸시 |
| 인증 | 행사 단위 RBAC(JWT) |

GUARDiA 표준 프레임워크(Spring Boot 3.5 + React 19 + MyBatis + PostgreSQL)와 정렬. 상세 아키텍처는 `docs/PLANNING.md` §8. **신규 코드는 이 스택을 따른다** — developer 에이전트는 `src/` 구현 시 백엔드 Spring Boot/MyBatis, 프론트 React(Vite)를 사용하고, 나노바나나 호출은 `tools/nanobanana` Python 워커 모듈만 경유한다.

## 에이전트 워크플로

작업은 아래 순서의 서브에이전트 체인으로 진행한다. 각 에이전트는 `.claude/agents/`에 정의되어 있다.

1. **planner (기획 에이전트)** — `docs/analysis/`의 리서치를 근거로 `docs/PLANNING.md` 작성/갱신
2. **designer (디자인 에이전트)** — PLANNING.md를 근거로 `docs/design.md` 작성 (Stitch에 바로 붙여넣을 화면별 프롬프트 포함)
3. **developer (개발 에이전트)** — PLANNING.md/design.md를 근거로 `src/` 구현
4. **visualizer (시각화 에이전트)** — 나노바나나 스킬로 부스/공사 결과 이미지 생성 파이프라인 담당
5. **reviewer (검증 에이전트)** — 산출물 교차 검증 (기획-디자인-구현 정합성)

새 기능 요청이 오면: planner로 기획 반영 → designer로 화면 반영 → developer 구현 → reviewer 검증 순으로 진행할 것.

## 규칙

- 모든 문서는 한국어로 작성한다. 코드 식별자/커밋 메시지는 영어.
- 기획/디자인 문서를 수정할 때는 반드시 해당 에이전트를 통해 수정한다 (직접 수정 금지).
- 나노바나나 호출은 `tools/nanobanana/` 모듈만 사용한다. API 키는 환경변수 `GEMINI_API_KEY`.
- 파일 삭제 전에는 반드시 사용자에게 확인받는다.
- 도메인 용어: 부스(booth), 장치공사(booth construction), 반입/반출(move-in/move-out), 주최자(organizer), 참가업체(exhibitor), 관람객(visitor).

## 참조 자산

- `docs/PLANNING.md` — 시스템 기획서(v1.2, M1~M9 모듈·나노바나나 파이프라인). **기획 변경은 planner 경유.**
- `docs/design.md` — UI 디자인 스펙(14화면 Stitch 프롬프트). **디자인 변경은 designer 경유.**
- `docs/IMPLEMENTATION_BACKLOG.md` — 구현 백로그(Phase 0~5, 모듈별 작업·담당·의존)
- `docs/analysis/kintex-website.md` — kintex.com 전체 페이지 분석
- `docs/analysis/reroomai-source.md` — ReRoomAI 소스 분석(나노바나나 image-to-image·보존/교체 프롬프트 차용)
- `docs/BACKLOG.md` — 검증 에이전트 지적사항 티켓 목록
- `stitch_kintex_ai_system_architect/` — Stitch 생성 화면 18종·DESIGN.md 3종(designer 학습·정합화 참조)

## 하네스: 구현 (kintex-impl-orchestrator)

**목표:** PLANNING v1.2의 M1~M9를 React(Vite) + Spring Boot 3.x(Java17) + MyBatis + PostgreSQL(PostGIS) + Redis + 나노바나나 Python 워커로 P0(M2·M3·M4·M5)부터 구현.

**트리거:** 킨텍스 구현·부스 배치/설계/배선/시각화 구현·백엔드/프론트/스키마 구현·Stitch 화면 이식·src 구현·배포·다시 실행·특정 모듈만 요청 시 `kintex-impl-orchestrator` 스킬을 사용하라. 단순 질문은 직접 응답 가능.

**에이전트:** kintex-backend-dev · kintex-frontend-dev · kintex-db-engineer · visualizer(나노바나나 워커) · kintex-qa · kintex-devops-dev + designer · planner · reviewer

**선행 게이트:** G1 나노바나나(Gemini) 외부 호출 승인(PLANNING R12) · G2 배포 대상 서버·포트(GUARDiA 인프라와 별개 도메인).

**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| 2026-07-11 | 구현 하네스 초기 구성 — 전문 에이전트 6종 + kintex-impl-orchestrator + 구현 백로그 | 전체 | 범용 에이전트만 존재 → 스택(React/Spring/MyBatis/PostgreSQL) 확정 후 실제 구현 조율 팀 구성. developer 스택 갱신·designer에 Stitch 학습 트랙 추가 |