zio
276293ebe7
- system/message: sys_message template CRUD + {key} render API (ADMIN-gated, render for authed)
- V48: sys_message table + 36 seeded templates (9 codes x ko/en/zh/ja), idempotent upsert
- V49: backfill 12 empty domain tables (render_job, cms_media, logistics_*, mail_log,
edm_followup, webhook_*, login_history, sys_role_menu, audit_log); idempotent guards.
followup ON CONFLICT targets business key (event_id, lead_id) to skip pre-seeded rows
- frontend: Nifty token/typography sweep (--fs-*/--fw-*), public e-card 3:4 media + cover fit,
footer copy update across ko/en/zh/ja
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
147 lines
17 KiB
Markdown
147 lines
17 KiB
Markdown
# 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 검증 순으로 진행할 것.
|
|
|
|
## 규칙
|
|
|
|
- 모든 문서는 한국어로 작성한다. 코드 식별자/커밋 메시지는 영어.
|
|
- 기획/디자인 문서를 수정할 때는 반드시 해당 에이전트를 통해 수정한다 (직접 수정 금지).
|
|
- **화면 디자인은 항상 Google Stitch에 의뢰한다** (웹·모바일·관리자·공개사이트 공통): designer가 design.md에 화면 스펙+영어 Stitch 프롬프트 작성 → Stitch 생성(`mcp__stitch__*`, 프로젝트 9385904003821333054, 디자인 시스템 "Precision Enterprise AI") → 생성 HTML을 `stitch_kintex_ai_system_architect/`에 확보 → frontend/mobile dev가 이식. 손그림 UI·Stitch 미경유 신규 화면 금지.
|
|
- 나노바나나 호출은 `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)
|
|
|
|
**목표:** 킨텍스 **자동전시시스템**(Exhibition Automation Platform) — PLANNING v2.0(부스 코어 M2~M5 + 도메인 M10~M18 + WISE/UIWS 공통·시스템관리 레이어 §5B, 6역할 웹/모바일 분리)을 React(Vite)+Spring Boot 3.x(Java17)+MyBatis+PostgreSQL(PostGIS)+Redis+나노바나나 Python 워커로 구현. AI=Claude 기본+설정형 전환(AiTextRouter/AiConfig). 공통 프레임워크 레퍼런스=WISE(UIWS `workspace/uiws`).
|
|
|
|
**트리거:** 킨텍스 구현·부스 배치/설계/배선/시각화·옥션/입찰/견적서·관람객/등록/배지/리드·경영분석/BI·CMS/공개 홍보 사이트·관리자 백오피스·공통기능/시스템관리/2FA·UIWS/WISE 이식·역할별 웹/모바일·AI(Claude)·아키텍처(AA/SA/TA/DA/NA)·src 구현·배포·다시 실행·특정 모듈만 요청 시 `kintex-impl-orchestrator` 스킬을 사용하라.
|
|
|
|
**에이전트(전문 20 + 범용):** 거버넌스 kintex-pm·dev-pm·pmo / 아키텍트 kintex-aa·sa·ta·da·na / 공통 kintex-common-dev / 코어 kintex-backend-dev·frontend-dev·db-engineer / 도메인 kintex-bidding-dev·visitor-dev·cms-dev·bi-dev·admin-dev / AI·시각화 kintex-ai-dev·visualizer / 품질·배포 kintex-qa·devops-dev + planner·designer·reviewer
|
|
|
|
**선행 게이트: G1·G2 모두 해소** — G1 나노바나나 Gemini 라이브(워커 env `GEMINI_API_KEY`+`NANOBANANA_LIVE=1`, `gemini-3.1-flash-image-preview`, 키 마스킹·미커밋). G2 개발 **`kintex.zioinfo.co.kr`**(DNS 해소 → 101.79.17.164, **포트 8021**, PostGIS+Redis+Flyway) / 운영 `kintex.wise.ai.kr`(후속). CI/CD 라이브(deploy_server kintex 블록·Gitea webhook #47·자동배포 E2E 검증).
|
|
|
|
**확보 자산:** `docs/assets/floorplans/` — 홀별 평면도 JPG 15장 + CAD(제1전시장 "평면,트렌치.dwg" 포함) → PLANNING R4(트렌치·CAD) 해소. 평면도 입력 포맷 = **CAD(DWG) + JPG**. CAD zip은 gitignore(로컬 보존).
|
|
|
|
**변경 이력:**
|
|
| 날짜 | 변경 내용 | 대상 | 사유 |
|
|
|------|----------|------|------|
|
|
| 2026-07-11 | 구현 하네스 초기 구성 — 전문 에이전트 6종 + kintex-impl-orchestrator + 구현 백로그 | 전체 | 범용 에이전트만 존재 → 스택 확정 후 실제 구현 조율 팀 구성 |
|
|
| 2026-07-11 | **v2.0 재구성** — 자동전시시스템 확장(PLANNING v2.0). 신규 에이전트 11종(아키텍트 5·공통 1·도메인 5·AI 1) + 오케스트레이터·백로그 v2.0(Phase A 아키텍처→B 공통레이어→C 부스코어→D 도메인→E 배포) | 전체 | 스코프 확장(전시 전기능·경영분석·CMS·관리자·역할분리·공사 옥션·WISE 공통레이어·AI Claude 전환) |
|
|
| 2026-07-11 | WISE 웹 기능 레퍼런스 강화 — kintex-frontend-dev에 uiws frontend(pages 공통 업무기능) 차용 원칙, 오케스트레이터에 웹 기능 화면 WISE 패턴·Stitch 디자인 경유·모바일 경계 명시 + 로스터에 kintex-mobile-dev(경계) 추가 | kintex-frontend-dev·kintex-impl-orchestrator | "웹도 wise 기능 참고" 요청 |
|
|
| 2026-07-12 | **세션 대량 구현·배포** — visitor 메인(AI 관람 도우미 홈·기능타일·연월 브리핑, 근거=크롤 적재 DB)·3-트랙 관문/서브홈·역할별 랜딩+메뉴 게이트(plan_role_routing)·공개 AI/캘린더 API(V43)·정산 데이터 정렬(V47)·포스터 이미지 빌드내장(V46)·성능 인덱스(V44)·아바타 API(V45). AI 토큰최소화 기획(PLANNING v3.4 §8A)·데이터표준(FK최소화·공통코드·view/mview·배치, data.md)·Open SSO+HR 연동 설계(sso-hr-integration.md). 배포 커밋 214b6df→3077cb0, health 게이트 통과 | 전체 | 소유자 라이브 피드백 연속 반영. **전 지시 로그: `docs/OWNER_FEEDBACK.md`(권위)** |
|
|
| 2026-07-12 | **선행 게이트 해소·검증 교훈** — G1 나노바나나 Gemini 라이브·G2 kintex.zioinfo.co.kr:8021 CI/CD 라이브. 배포 전 필수: **Flyway 마이그레이션 라이브 dry-run(BEGIN…ROLLBACK)**·시크릿 fail-fast 프로파일 확인·파일단위 커밋(공유 트리 교차 방지)·health 게이트. Stitch 불안정 시 design.md 스펙 직접 구현(문서화 폴백) | 전체·kintex-devops-dev | 다수 배포 롤백/캐시/교차커밋 사고 후 표준화 |
|
|
|
|
---
|
|
|
|
## 하네스: 벤치마킹·크롤링 (kintex-benchmark-orchestrator)
|
|
|
|
**목표:** 레퍼런스 사이트(COEX 등) 크롤·분석·벤치마크 백로그 산출(kintex-benchmark-analyst) + 외부 행사 데이터 크롤 적재(kintex-crawler-dev). 적용은 planner/renewal/wise-ui 하네스 연계.
|
|
|
|
**트리거:** 벤치마킹, 사이트 분석해서 재구성, 경쟁사 비교, 크롤링(행사정보 수집·갱신), 데이터 수집, 다시 실행, 특정 사이트만 요청 시 `kintex-benchmark-orchestrator` 스킬을 사용하라.
|
|
|
|
**변경 이력:**
|
|
| 날짜 | 변경 내용 | 대상 | 사유 |
|
|
|------|----------|------|------|
|
|
| 2026-07-12 | 초기 구성(analyst·crawler 에이전트 + 오케스트레이터) | 전체 | "크롤링/벤치마킹 하네스 생성" 요청 — COEX 3-트랙 재구성·행사 크롤 정례화 |
|
|
| 2026-07-12 | **모바일 앱 벤치마킹**(전시·공연 앱 다운로드·평점 상위순) → `docs/analysis/mobile-benchmark-exhibition-performance.md` + 백로그 12항목. 핵심: 다운로드↔만족도 상반(티켓팅 빅3 저평점) → MMCA·Eventbrite·DICE·Fever 롤모델. **관람객 정보 크롤→DB 적재**(V43 visitor_guide·transport, 포스터 34장 V46) | kintex-benchmark-analyst·kintex-crawler-dev | "모바일은 전시·공연 앱 벤치마킹 다운로드·좋아요순" + "크롤링해서 db 저장" |
|
|
|
|
---
|
|
|
|
## 하네스: 전면 리뉴얼 (kintex-renewal-orchestrator)
|
|
|
|
**목표:** 내비게이션(브레드크럼·상세→메인 복귀·404)·전 화면 WISE 정렬·마스터/테스트 데이터 전면 생성(공통코드·프로그램·부서·데모 폐루프)을 총괄 리뉴얼. UI 정렬은 wise-ui 하네스 에이전트 재사용 + kintex-testdata-dev 신규.
|
|
|
|
**트리거:** 리뉴얼, 전면 개편, 상세에서 메인 못 감/내비 문제, 테스트 데이터 생성, 데이터 채워/화면 비어 있음, 공통코드·프로그램 채움, 다시 실행, 특정 영역만 요청 시 `kintex-renewal-orchestrator` 스킬을 사용하라.
|
|
|
|
**변경 이력:**
|
|
| 날짜 | 변경 내용 | 대상 | 사유 |
|
|
|------|----------|------|------|
|
|
| 2026-07-12 | 초기 구성(kintex-testdata-dev 신규 + wise-ui/menu-ia/qa 재사용 + 오케스트레이터) | 전체 | 소유자 지시 — 상세→메인 복귀 부재·전면 리뉴얼·테스트 데이터/공통코드/프로그램 채움 |
|
|
| 2026-07-12 | **코엑스풍 공개사이트 리뉴얼**(design.md v2.4 §3C-V 비주얼·모션 — 시네마틱 히어로·스크롤 리빌·카운트업·포스터 카드 리프트/줌·오토스크롤, prefers-reduced-motion·CLS 0) + **행사스코프 데이터 정렬**(V47 e-2026-live 폐루프·V49 잔여 보강). ★교훈: 화면이 비는 진짜 원인=시드가 데모 해소행사(workspaces[0]=start_date 최소)에 안 묶임 | kintex-frontend-dev·kintex-testdata-dev·designer | "코엑스처럼 지금 착수"·"정산 데이터 없음"·"모든 테이블 데이터" |
|
|
|
|
---
|
|
|
|
## 하네스: WISE UI 정렬 (kintex-wise-ui-orchestrator)
|
|
|
|
**목표:** 킨텍스 UI(셸·아코디언 메뉴 IA·캘린더·차트·전 화면)를 WISE(UIWS `C:\GUARDiA\workspace\uiws\frontend`) 컨벤션에 **문자 그대로** 정렬(자체 재해석 금지 — 소유자 원칙 2026-07-12). 감사(kintex-wise-ui-auditor)→정렬 이식(kintex-wise-ui-dev)→QA(kintex-qa 재사용).
|
|
|
|
**트리거:** WISE처럼/WISE대로, UI 정렬, 메뉴 재구성, 아코디언/햄버거 메뉴, 셸·사이드바·푸터 수정, 캘린더 WISE, 대시보드 구성, 차트, 로고 교체, 반응형 깨짐, 다시 실행, 특정 화면만 요청 시 `kintex-wise-ui-orchestrator` 스킬을 사용하라.
|
|
|
|
**변경 이력:**
|
|
| 날짜 | 변경 내용 | 대상 | 사유 |
|
|
|------|----------|------|------|
|
|
| 2026-07-12 | 초기 구성(에이전트 2 신규 + kintex-qa 재사용 + 오케스트레이터) | 전체 | 소유자 강한 피드백("전부 WISE대로 안 되어 있다" — 시스템관리 메뉴 실종·햄버거/아코디언 부재·캘린더·대시보드·로고) |
|
|
| 2026-07-12 | 메뉴 IA 전담 추가 — kintex-menu-ia-dev + kintex-menu-recompose 스킬(표준 카테고리 v1·라우트↔메뉴 정합 절차), 오케스트레이터 Phase 2.5 편입 | agents·skills | "카테고리별 메뉴 재구성 하네스" 요청 — 별도 오케스트레이터 대신 중복 회피 확장 |
|
|
| 2026-07-12 | **Nifty 디자인 시스템 전면 정렬** — 카드 Nifty 타입(`.kx-card` subtle 그림자·hover·`--flush`/`__media`/`__header`/`__body`/`__footer` 구조)·타이포(`--fs-micro`/`--fs-nano`·`--fw-*` 토큰·공용 `.kx-page__title`/`.kx-section__title`·font-size 179+weight 415 토큰화)·그리드(`.kx-table` Nifty Advanced header로 6화면 수렴). **캘린더 Nifty**(옅은 격자·연노랑 today·소프트 이벤트칩)·**파란버튼 흰글자**(`--color-on-accent` 다크대응)·favicon 정정. 기준: `docs/DESIGN_SYSTEM_NIFTY.md`·`_workspace/audit_typography_grid.md` | kintex-frontend-dev·kintex-qa | 소유자 반복 강피드백("Nifty 카드/그리드/폰트 안 맞음"·"파란버튼 흰글자"·"달력 Nifty") |
|
|
|
|
---
|
|
|
|
## 하네스: 모바일 앱 (kintex-mobile-orchestrator)
|
|
|
|
**목표:** `mobile/`(Expo SDK 51 + expo-router + React Native 0.74 + TS) 모바일 앱 트랙 — 화면(SCR-M*)·실데이터 API 배선·오프라인/푸시/i18n·에셋·EAS 빌드·APK·QR 배포. **레퍼런스 = WISE 모바일**(`workspace/guardia-messenger/app/uiws/` — uiwsApi 봉투 언랩·2FA 로그인·화면 컨벤션), **디자인 = Stitch 경유**(designer → design.md SCR-M* → Stitch 생성 → RN 이식).
|
|
|
|
**트리거:** 모바일 앱, 앱 화면, Expo, 앱 기능 추가, 앱 빌드, APK, QR 배포, 푸시 알림, 앱 오프라인, 앱 아이콘/스플래시, EAS, 모바일 QA, 다시 실행, 특정 화면만 요청 시 `kintex-mobile-orchestrator` 스킬을 사용하라. (웹·백엔드·도메인 모듈은 `kintex-impl-orchestrator`.)
|
|
|
|
**게이트 G3:** EAS 실빌드·배포는 외부 클라우드 빌드 — 소유자 승인 후 실행(승인 전엔 eas.json·에셋 준비까지만).
|
|
|
|
**변경 이력:**
|
|
| 날짜 | 변경 내용 | 대상 | 사유 |
|
|
|------|----------|------|------|
|
|
| 2026-07-11 | 초기 구성 — kintex-mobile-dev 신규 + 오케스트레이터(재사용: designer·backend-dev·qa·devops-dev·reviewer). WISE 모바일 레퍼런스·Stitch 디자인 경유 반영 | 전체 | 모바일 앱 트랙 전담 하네스 부재("하네스 생성" + "wise 모바일 참고" + "디자인은 스티치" 요청) |
|
|
| 2026-07-11 | **앱 타깃 2개 확정 반영** — 코드베이스 1(mobile/) + 배포 타깃 2(①운영 B2B: 2FA 필수·사내 QR ②관람객 B2C: 스토어 공개·간편가입·게스트). 계정은 단일 통합+가입 트랙 분리(PLANNING v3.1) | kintex-mobile-dev·오케스트레이터 | 소유자 확정 — 회원가입 관람객 포함 질의 → 하이브리드(계정 통합·앱 분리) 채택 |
|
|
| 2026-07-12 | **내정보(WISE)+생체인식(expo-local-authentication)+프로필 사진(expo-image-picker)** + **앱 위변조 방지·시큐어코딩 보안 체크리스트**(루트/탈옥·무결성·Hermes+R8·화면캡처·cleartext·권한최소, `docs/security/mobile-security-*.md`) + **다국어(react-i18next)·역할별 랜딩 패리티** 착수 | kintex-mobile-dev·kintex-qa | "모바일 내정보 WISE+생체+사진"·"앱 위변조방지·시큐어코딩·보안체크"·"모바일도 동일 로직"·"웹 4개국어인데 모바일은?" |
|