20 KiB
20 KiB
KINTEX AI 전시·행사시스템 — 개발계획서
- 문서 종류: 개발계획서(Development Plan)
- 프로젝트: KINTEX AI 전시·행사시스템 (KINTEX AI Exhibition & Event System)
- 작성일: 2026-07-12 · 버전: v1.0
- 근거 문서:
docs/PLANNING.md(v3.4) ·docs/IMPLEMENTATION_BACKLOG.md(v2.0) ·docs/BUILD_DEPLOY.md·docs/architecture/*· 실제 구현 스키마(Flyway V1~V49)- 산출물 정책: 개발계획서·설계서는 개발 착수 시점 1회 작성(본 문서). 사용자/운영자 지침서는 UI 정렬 안정화 후 별도 산출.
- 보안: 본 문서에는 자격증명·비밀번호·SSH·내부 IP·시크릿을 기재하지 않는다.
목차
- 사업 개요
- 목표 및 기대효과
- 개발 범위(모듈)
- 기술 스택
- 시스템 아키텍처 개요
- 개발 방법론 및 조직(에이전트 트랙)
- 개발 단계(Phase)와 WBS
- 마일스톤 및 일정
- 선행 게이트 및 전제조건
- 리스크 관리
- 품질 관리 방침
- 보안 방침
- 배포(CI/CD) 계획
1. 사업 개요
1-1. 배경
킨텍스(KINTEX, 한국국제전시장)는 총 전시면적 108,011㎡(2028년 제3전시장 완공 시 178,000㎡)를 운영하나, 전시 준비 실무는 HWP 서식 다운로드 → 이메일/방문 제출, CAD 수작업 배치도 → 홀매니저 육안 검수, 수기 위치표시도 기반 유틸리티 신청에 머물러 있다. 온라인 작업신고(kxwp.kintex.com)는 서류 업로드 창구 수준이며, 참가업체 유틸리티 신청은 킨텍스 공통 플랫폼 없이 전시회별 주최자 사무국 시스템으로 파편화되어 있다.
1-2. 비전
"신청서를 내는 순간, 시공 후 사진을 먼저 본다."
전시장 운영 전 과정(홀 배정 → 부스 배치 → 장치공사 설계 → 전기/조명 → 네트워크/유틸리티 배선 → 반입/반출)을 AI로 자동 설계·검증하고, 그 결과를 나노바나나(Gemini 이미지 생성)로 '공사 후 결과 사진'처럼 시공 전에 미리 생성해 보여주는 것이 핵심 차별화다.
1-3. 정체성 확장(제품 진화)
- v2.0 자동전시시스템: 부스 시공 시각화(P0 코어 M2~M5)를 심장으로 두되, 전시 기획·판매·시공·운영·관람객·사후분석 전 주기를 자동화하는 베뉴 운영 플랫폼으로 확장(도메인 모듈 M10~M18 신설).
- v3.0 다중 전시관 SaaS: KINTEX를 기준 테넌트(#1)로 두고 코엑스(COEX) 등을 테넌트로 온보딩하는 멀티테넌트 SaaS. 기능은 보존하고
tenant_id격리 레이어만 순증. - v3.2 대외 접점 3-트랙: visitor(관람객) / business(주최자·참가업체) / agency(공사·장치·협력사) 3-트랙 IA 재구성.
- v3.4 AI 사용성 & 토큰 최소화: 전 화면 인라인 AI 진입점 표준화 + LLM 토큰 최소화 6원칙(§8A).
근거: PLANNING §1·§1-2·§1A·§2-2·§8A.
2. 목표 및 기대효과
| 목표(To-Be) | 현재(As-Is) | 개선 |
|---|---|---|
| 홀 배정 견적 | 문의→협의→견적 수일 | 규칙 엔진 즉시 자동 견적(2,250원/㎡ × 성수기/전시장 계수) |
| 부스 배치도 초안 | CAD 수작업 수일~수주 | 조건 입력 후 수 분 내 복수 안(1·2·3안) 생성·선택/병합 |
| 도면 규정 검수 | 홀매니저 육안 | 규정 위반 자동 플래깅(높이 5m·방염·리깅 등) 후 사람 확정 |
| 유틸리티 위치표시도 | 참가업체 수기 작도 | 부스 좌표 클릭 → 자동 배선안 + 자동 견적 |
| 시공 결과 예측 | 불가(외주 조감도) | 표준 샷 세트 자동 생성(정면/야간/통로/배선 오버레이) |
근거: PLANNING §1-3 목표(정량).
3. 개발 범위(모듈)
3-1. 코어(P0, 불변) — 설계·시각화
- M2 플로어플랜 스튜디오 — 부스 배치 자동 생성(제약 솔버 중심), 3안 생성 → 선택/병합, 규정 자동 검증(통로·바닥하중·비상구).
- M3 부스 설계 스튜디오 — 조립/독립 부스 설계 3안, 규정 사전 검증(높이 5m·리깅 6.5~8.5m·방염·이격).
- M4 유틸리티 설계 — (a) 전기·조명, (b) 네트워크·급배수·압축공기. 트렌치 최단 배선 자동 산출, 위치표시도 자동 생성, 자동 견적.
- M5 나노바나나 시각화 — M2~M4 구조화 데이터를 프롬프트로 컴파일해 "시공 후 사진" 표준 샷 세트(S1~S7) 생성.
3-2. 판매·발주·정산(P1)
- M1 홀 배정·자동 견적 / M6 서류·마일스톤 워크플로 / M7 등록업체 매칭·견적 / M9 정산·결제
- M15 공사/장치 옥션(핵심 플로우) — AI 설계자료를 근거로 등록업체가 견적서(Quotation) 제출 → 역경매(라운드·실시간 순위) → 낙찰(Award) → 계약/발주 연동. 폐루프의 연결고리.
- M8 반입/반출 물류 슬롯(P2)
3-3. 관람·참가·마케팅
- M10 관람객 등록·티켓·배지·체크인·리드캡처(P1) / M12 마케팅·EDM·공개 홍보 사이트(P1, SEO·다국어)
- M11 비즈니스 매칭 / M13 wayfinding·실내 내비 / M14 현장운영(혼잡·안전·주차·에너지) (P2)
3-4. 경영·콘텐츠·관리(P1)
- M16 경영분석 BI — 운영사(킨텍스) 관점 수익성/ROI(가동률·매출구성·행사별 P&L·전시장 ROI·리텐션/LTV·수율·경영진 KPI) + 참가사 관점 ROI.
- M17 CMS — 콘텐츠·공지·참가업체 마이크로사이트·다국어·사이니지 연계.
- M18 관리자 백오피스 — §5B 시스템관리 + 킨텍스 마스터데이터(홀·요율·규정 룰셋·등록업체).
3-5. 공통/시스템관리 레이어(§5B, P1·전 모듈 선행 기반)
UIWS(GUARDiA 표준 프레임워크) 이식: 인증(JWT+2FA/OTP·로그인 실패 잠금·admin 비번 env 주입), 시스템관리(사용자·역할/권한 RBAC·공통코드·메뉴·감사로그·시스템설정), 공통 업무기능(worklog·schedule·message·notice·opinion·search·meeting·report·notification 등).
근거: PLANNING §5(M1~M9)·§5A(M10~M18)·§5B(공통 레이어)·기능 우선순위 총괄표.
4. 기술 스택
| 레이어 | 기술 | 비고 |
|---|---|---|
| 프론트엔드 | React 18/19 + Vite + TypeScript | 반응형(데스크톱=설계/에디터, 모바일=조회·승인·현장), 역할별 번들 분리 |
| 백엔드 | Spring Boot 3.x(Java 17) + MyBatis | REST + WebSocket(STOMP), 룰 엔진·배치/배선 엔진(서비스 계층) |
| DB | PostgreSQL + PostGIS | 부스 폴리곤·트렌치 포인트·배선 LineString 공간 데이터, Flyway 마이그레이션 |
| 비동기 | Redis 작업 큐 | RenderJob·서류·알림 |
| 이미지 생성 | 나노바나나 Python 워커 사이드카(tools/nanobanana) |
google-genai + gemini-3.1-flash-image-preview, Spring이 큐로 트리거 |
| 인증 | JWT + RBAC + TOTP 2FA | 행사 단위 RBAC, UIWS 표준 이식 |
| AI(텍스트) | Claude 기본 + 설정형 전환(AiTextRouter/AiConfig) | Claude→Ollama 소형모델 폴백, 토큰 최소화 라우팅 |
| 모바일 | Expo SDK 51 + React Native + TypeScript(mobile/) |
코드베이스 1개·배포 타깃 2개(B2B 운영/B2C 관람객) |
- GUARDiA 표준 프레임워크(Spring Boot + React + MyBatis + PostgreSQL) 정렬.
- 나노바나나 image-to-image 파이프라인은 Python SDK(google-genai) 검증 자산을 재사용하기 위해 Python 워커 사이드카로 유지하고, Spring은 큐·오케스트레이션·상태 관리만 담당.
근거: PLANNING §8 아키텍처, CLAUDE.md 기술 스택 확정표.
5. 시스템 아키텍처 개요
- 역할별 분리 프론트 + 공유 백엔드: organizer·exhibitor·contractor·ops·admin 5개 인증 앱 + public(공개 사이트)·visitor(관람객 앱). 공유 디자인 시스템·공유 컴포넌트·공유 API 계약 상속(최소권한·공격면 축소).
- 공유 Spring Boot 백엔드: REST + WebSocket, 룰 엔진(요율/규정), 배치·배선 엔진(PostGIS), 옥션 엔진(M15), BI 집계(M16), CMS(M17), Redis 큐, 나노바나나 워커.
- 데이터: PostgreSQL+PostGIS(업무·공간 데이터) + 오브젝트 스토리지(도면·생성 이미지·서식·콘텐츠).
- 멀티테넌시: 공유 스키마 +
tenant_id컬럼(단일 DB) 논리 격리, fail-closed 다층 방어(필터→서비스 가드→MyBatis 강제 바인딩→PostGIS). - AI 사용성·토큰 최소화: 단일
/ai/ask계약, 결정론 우선 라우팅(사실조회는 LLM 미호출), 소형모델 우선 티어링, RAG 발췌·캐시·구조화 출력.
상세는 설계서(
02_설계서.md) 참조. 근거: PLANNING §8·§8-1·§8-2·§8A.
6. 개발 방법론 및 조직(에이전트 트랙)
- 방법론: 하네스 기반 에이전트 오케스트레이션(
kintex-impl-orchestrator). Phase A(아키텍처) → B(공통 레이어) → C(부스 코어) → D(도메인) → E(배포)의 단계적 진행, 각 모듈 완성 직후 QA 점진 검증. - 문서 워크플로(CLAUDE.md): planner(기획, PLANNING.md) → designer(디자인, design.md·Stitch 경유) → developer(구현, src/) → visualizer(나노바나나) → reviewer(교차 검증).
- 개발 조직(에이전트 트랙):
| 구분 | 에이전트 | 역할 |
|---|---|---|
| 거버넌스 | kintex-pm·dev-pm·pmo | 범위·일정·게이트·품질 게이트·산출물 관리 |
| 아키텍트 | kintex-aa·sa·ta·da·na | 애플리케이션·시스템·기술·데이터·네트워크 아키텍처 |
| 공통 | kintex-common-dev | UIWS 공통/시스템관리·2FA 이식 |
| 코어 | kintex-backend-dev·frontend-dev·db-engineer | Spring/MyBatis·React·PostGIS 스키마 |
| 도메인 | kintex-bidding-dev·visitor-dev·cms-dev·bi-dev·admin-dev | M15·M10·M12/M17·M16·M18 |
| AI·시각화 | kintex-ai-dev·visualizer | Claude AI 기능·나노바나나 |
| 품질·배포 | kintex-qa·devops-dev | 경계면 QA·CI/CD |
| 모바일 | kintex-mobile-dev | Expo 앱 트랙 |
근거: CLAUDE.md 하네스(kintex-impl-orchestrator) 로스터, IMPLEMENTATION_BACKLOG 담당 약칭.
7. 개발 단계(Phase)와 WBS
Phase A — 아키텍처·거버넌스
| ID | 작업 | 산출물 |
|---|---|---|
| A-1 | 애플리케이션 아키텍처(모듈 경계·레이어·API 표준·패키지) | architecture/app.md |
| A-2 | 시스템 아키텍처·NFR(확장성·HA·성능·보안영역·배포 토폴로지) | architecture/system.md |
| A-3 | 기술 표준(스택·빌드/배포·개발표준·관측성·AiTextRouter) | architecture/tech.md |
| A-4 | 데이터 아키텍처(전사 ERD·공간데이터·마스터·공통코드·BI 마트) | architecture/data.md |
| A-5 | 네트워크 아키텍처(DMZ/내부망·방화벽·부하분산) | architecture/network.md |
| A-6 | 아키텍처↔PLANNING 정합 검증 | 불일치 0/티켓화 |
Phase B — 공통/시스템관리 레이어(★전 모듈 선행)
| ID | 작업 | 완료 기준 |
|---|---|---|
| B-0 | 스캐폴드(Spring Boot·Vite·PostGIS·Flyway) | 빌드·마이그레이션 통과 |
| B-1 | 인증 JWT+RBAC(6역할) + 2FA(TOTP) + 로그인 실패 잠금 + admin 비번 env | 2FA 등록/검증/초기화 왕복 |
| B-2 | 시스템관리(사용자·역할/권한·공통코드·메뉴·감사로그·설정) | CRUD·RBAC 가드·감사 기록 |
| B-3 | 공통 업무기능(worklog·schedule·message·notice·opinion·search·meeting·report·notification) | 각 모듈 API 왕복 |
| B-4 | 공통 컴포넌트(예외·응답봉투·감사 AOP·알림 단일화) + 프론트 공통 | AA 표준 정합 |
| B-5 | 점진 QA(2FA·RBAC·비번/PII 미노출·경계면) | 통과까지 반려 |
Phase C — P0 부스 시공 코어
| ID | 모듈 | 완료 기준 |
|---|---|---|
| C-M2 | 플로어플랜(Booth polygon·Trench·PostGIS 규정검증·3안 생성/병합) | 3안 생성·병합·규정 재검증 |
| C-M3 | 부스 설계(조립/독립·규정 사전검증·3안/병합) | 위반 사전 플래깅·컨펌 |
| C-M4 | 유틸리티 배선(Wiring LineString·자동 견적·위치표시도) | 최단 배선·견적·위치표시도 |
| C-M5 | 나노바나나(RenderJob·Redis·WebSocket·워커·S6 래스터·Before/After) | (G1 시)실생성/미승인시 목·워터마크 강제 |
| C-C | 공통 화면(로그인·주최자·참가업체·홀매니저·현장 모바일) | 역할별 진입·상태 처리 |
Phase D — P1 도메인(역할별 포털 분리)
| ID | 모듈 | 완료 기준 |
|---|---|---|
| D-M15 | 공사/장치 옥션(견적서 제출→역경매→낙찰, 등록업체만 응찰) | 견적서·역경매·낙찰 왕복 |
| D-M10 | 관람객·현장(등록·티켓·배지/QR·체크인·리드캡처) | 등록→배지→체크인→리드 |
| D-M12/17 | 마케팅·공개사이트·CMS(SEO·다국어·게시 워크플로) | 공개 조회·게시·SEO |
| D-M16 | 경영분석 BI(가동률·P&L·리텐션·KPI·Recharts) | 지표 집계·드릴다운·내보내기 |
| D-M18 | 관리자 백오피스(시스템관리+마스터데이터·룰셋 버전) | RBAC·마스터 CRUD·룰셋 버전 |
| D-M1/6/7/9 | 배정·서류·매칭·정산 | 견적·마일스톤·정산 |
Phase E — P2 + 빌드·배포
M11 비즈매칭 / M13 wayfinding / M14 현장운영 + 역할별 프론트 번들·Spring jar·워커 서비스 빌드·Gitea CI/CD·systemd·env(G2 후).
Phase F — 벤치마킹 유래 추가(티켓·관람객)
스마트티켓 부정입장 방지(회전 QR)·환불 규정 정교화·티켓/배지 다국어·세션 정원 RSVP·간편결제·라이브 공지(ⓑ 보강 6) + 티켓 오픈 알림·주차 연계·혼잡 안내·QR 명함 교환·대기열·멤버십·개인화 홈·셀프 체크인 키오스크(ⓒ 신규 8).
근거: IMPLEMENTATION_BACKLOG v2.0 Phase A~F 전문.
8. 마일스톤 및 일정(로드맵)
| Phase | 기간(목표) | 범위 요약 |
|---|---|---|
| Phase 1 — 설계·시각화 코어(MVP) | ~4개월 | §5B 공통 레이어 선행 + M2(단일 홀 근사 도면)·M3·M4·M5(S1·S2·S6·S7) |
| Phase 2 — 워크플로·운영 통합 | ~4개월 | M1·M6·M7·M9 + 홀매니저 대시보드 + 전 홀(10개) 도면 확장 |
| Phase 3 — 현장·확장 | ~4개월+ | M8·kxwp 정식 API·정밀 조도·다국어 규정 챗봇·관람객 플로어플랜 |
- 각 Phase 종료 시 reviewer 에이전트 교차 검증(기획-디자인-구현 정합성).
- Phase 1 착수 조건: Gemini API 키·홀 참조 사진·트렌치 좌표(미확보 시 공개 스펙 기반 '가정' 그리드).
근거: PLANNING §9 로드맵.
9. 선행 게이트 및 전제조건
| 게이트 | 내용 | 영향 |
|---|---|---|
| G1 | 나노바나나(Gemini) 외부 호출 소유자 승인(PLANNING R12) | M5 실호출·배포 전. 미승인 시 목/degraded |
| G2 | 배포 대상 서버·포트(개발 kintex.zioinfo.co.kr 포트 8021, 운영 별개 도메인) |
Phase E 배포 착수 전 |
| G3 | 모바일 EAS 클라우드 빌드 소유자 승인 | 앱 실빌드·QR 배포 전 |
전제조건(킨텍스 협의): CAD 도면·트렌치 실측 제공, kxwp 연동 논의, 요금 정합성 확인(인터넷 150,000 vs KT 80,000). 확보 자산: 홀별 평면도 JPG 15장 + CAD(제1전시장 트렌치 DWG) → PLANNING R4 부분 해소.
근거: IMPLEMENTATION_BACKLOG 선행 게이트·확보 자산, CLAUDE.md 하네스 게이트.
10. 리스크 관리
| # | 리스크 | 영향 | 완화 |
|---|---|---|---|
| R1 | AI 생성 이미지가 실제 시공과 다름(계약 오인 분쟁) | 높음 | 전 이미지 워터마크·고지, 계약/심사 서류 자동 배제, "시공 기준은 도면" 동의 |
| R2 | 도면 심사 책임(자동 통과 ≠ 승인) | 높음 | 시스템을 '사전 필터'로 정의, 최종 승인 주체 명시, 면책·룰셋 버전 기록 |
| R3 | kxwp 연동 불확실성(폐쇄형·API 미공개) | 중간 | 파일 자동 생성+수동 업로드 릴레이로 독립 가치 확보, 병행 협의 |
| R4 | 트렌치·CAD 실측 미확보 | 높음 | '가정' 그리드 라벨링 + 킨텍스 데이터 제공을 Phase 2 전제로 계약화 |
| R6 | 이미지 생성 비용·지연(부스 수백 개) | 중간 | 자동 생성 S1·S7 한정, 온디맨드+스키마 해시 캐시, 행사별 쿼터 |
| R8 | 요금·규정 공개값과 실계약가 차이 | 중간 | "공시가 기준, 최종가는 킨텍스 확정" 고지, 룰셋 버전 교체 절차 |
| R10 | 부스 설계 영업비밀 민감성 | 중간 | 행사 단위 격리, 소유 참가업체+주최자+홀매니저로 접근 한정 |
| R12 | 나노바나나(Gemini) 외부 API 승인 게이트 | 높음 | G1 승인 선행, 미승인 시 온프레미스 이미지 생성 폴백 검토 |
근거: PLANNING §10 리스크 및 제약(R1~R12).
11. 품질 관리 방침
- 점진 QA: 각 모듈 완성 직후 kintex-qa가 백엔드 응답 shape ↔ 프론트 호출 경계면 불일치를 교차 검증. 공간 로직(배치·배선·규정) 정합, 빌드 회귀 확인.
- 품질 게이트(반려 사유): 자격증명·PII·스택트레이스 미노출, AI 이미지 워터마크 강제, 등록업체 응찰 게이트, admin 비번 env 주입.
- 빌드 게이트(push 전): 시크릿 커밋 차단, Flyway 번호 충돌 검사, 변경분 compileJava/tsc·lint 실패 시 push 차단.
- 정합성 검증: reviewer 에이전트가 기획-디자인-구현 3자 정합을 Phase 종료 시 교차 검증.
근거: IMPLEMENTATION_BACKLOG 진행 규칙·B-5, BUILD_DEPLOY §3.
12. 보안 방침
- 인증·인가: JWT + 행사 단위 RBAC(ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER) + 플랫폼/테넌트 관리자 계층 + TOTP 2차 인증(업무 사용자 필수, 관람객 미강제).
- 자격증명 보호:
password_hash(BCrypt)·otp_secret(TOTP)는 API 응답에서 완전 제외. admin 비밀번호는 env(ADMIN_PASSWORD_ENCAES-256-GCM + 별도 키파일) 주입, 하드코딩admin123시드 금지. - 테넌트 격리: 전 계층
tenant_id강제, 크로스-테넌트 접근은 플랫폼 슈퍼관리자 전용 API로만(감사). - 외부 API: 온프레미스 원칙. 예외 승인 = Claude API(
api.anthropic.com), 나노바나나(Gemini)는 G1 승인 게이트. 키는 서버 env로만 로드(코드·DB·커밋·로그·응답 기록 금지). - 에러 응답: 스택트레이스 미노출 — 요약 메시지만 전달. 감사로그(승인·낙찰·설계 변경·룰셋 개정·리드 접근)에 전수 기록.
근거: PLANNING §5B-3·§8-2·§10, CLAUDE.md 보안 제약, 실제 스키마(app_user 컬럼 코멘트).
13. 배포(CI/CD) 계획
- 실행 단위 3개: 백엔드(
./gradlew bootJar→ jar, systemd) / 프론트(Vitenpm run build→ dist, nginx 정적 서빙, 역할별 번들 분리) / 나노바나나 워커(Python 큐 소비 데몬). - 파이프라인:
workspace/kintex → git push → Gitea(zio/kintex) → webhook → deploy_server. 빌드(bootJar·vite build) → Flyway 마이그레이션 → jar 재기동·dist 배포 → 헬스 게이트(GET /health). - Fail-Safe: 백업 → 배포 → 헬스체크(200) → 실패 시 롤백(이전 jar 유지). clean bootJar 검증 후 교체.
- 인프라: systemd 유닛(백엔드·워커), nginx vhost(
/=프론트 정적,/api/·/ws=백엔드), TLS certbot, AI env drop-in. - 개발 도메인:
kintex.zioinfo.co.kr(포트 8021, PostGIS+Redis+Flyway). 운영 배포는 소유자 승인 필수(G2).
근거: BUILD_DEPLOY §1·§4·§5, CLAUDE.md 하네스(kintex-impl-orchestrator) G2 게이트.
후속 산출: 본 개발계획서와 함께
02_설계서.md를 산출한다. 사용자지침서·운영자지침서는 UI 정렬 안정화 이후 별도 산출(본 산출 범위 아님 — deliverables 갱신 정책상 완성+QA 통과 후 최신 메뉴 반영).