diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ec79b3b..921aa68 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -15,8 +15,8 @@ { "name": "zio-harness", "source": "./plugins/zio-harness", - "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.", - "version": "1.0.1" + "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억. 설치만으로 graphify 지식 그래프가 소스를 자동 분석(SessionStart 훅)하고, KINTEX 도메인 md 지식 베이스를 내장.", + "version": "1.1.0" }, { "name": "proposal-builder", diff --git a/plugins/zio-harness/.claude-plugin/plugin.json b/plugins/zio-harness/.claude-plugin/plugin.json index 7a3f612..3b6d65c 100644 --- a/plugins/zio-harness/.claude-plugin/plugin.json +++ b/plugins/zio-harness/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "zio-harness", - "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.", - "version": "1.0.1", + "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억. 설치만으로 graphify 지식 그래프가 소스를 자동 분석(SessionStart 훅)하고, KINTEX 도메인 md 지식 베이스를 내장.", + "version": "1.1.0", "author": { "name": "ythong", "url": "https://git.zioinfo.co.kr/ythong" diff --git a/plugins/zio-harness/hooks/hooks.json b/plugins/zio-harness/hooks/hooks.json new file mode 100644 index 0000000..59e0588 --- /dev/null +++ b/plugins/zio-harness/hooks/hooks.json @@ -0,0 +1,16 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup|resume", + "hooks": [ + { + "type": "command", + "command": "python \"${CLAUDE_PLUGIN_ROOT}/scripts/graphify_setup.py\"", + "timeout": 600 + } + ] + } + ] + } +} diff --git a/plugins/zio-harness/knowledge/guardia/lessons-learned.md b/plugins/zio-harness/knowledge/guardia/lessons-learned.md new file mode 100644 index 0000000..5911620 --- /dev/null +++ b/plugins/zio-harness/knowledge/guardia/lessons-learned.md @@ -0,0 +1,259 @@ +# GUARDiA 개발 교훈 (Lessons Learned) + +> GUARDiA 전 하네스 변경 이력(★교훈·근본원인·함정)과 kintex 트랙 소유자 피드백 로그에서 추출한 지식 문서. +> 각 항목은 **[증상 → 근본원인 → 해결 패턴]** 구조. 신규 개발·배포·디버깅 시 먼저 이 문서를 대조하라. +> 출처: `C:\GUARDiA\CLAUDE.md`(하네스 변경 이력), `workspace\kintex\CLAUDE.md`, `workspace\kintex\docs\OWNER_FEEDBACK.md` +> 갱신: 2026-07-12 + +--- + +## 1. DB / 스키마 + +### 1.1 `sql.init mode=never` + schema.sql 후행 확장 함정 (최다 재발 패턴) +- **증상:** 운영 중 특정 API만 500, 로그에 `relation "xxx" does not exist` (OCR `ocr_ai_task`에서 최초 규명, bi 4테이블·erp 6+테이블 등 전 솔루션 확산). +- **근본원인:** 초기 배포 후 `schema.sql`에 테이블을 추가해도 `spring.sql.init.mode: never`면 재적용되지 않음. 스키마 파일과 실제 DB가 조용히 갈라진다. +- **해결 패턴 (검증됨, 2026-06-18 OCR·BI):** + 1. 시드에 유니크 인덱스를 걸어 **멱등화** (재실행해도 중복 삽입 없음) + 2. `mode: always` + `continue-on-error: true` 로 전환 + 3. `DataAccessException` 전역 핸들러로 SQL 오류 **누출 차단** (스택트레이스 미노출) + 4. 전 솔루션 grep 감사: `mode: never` 패턴 발견 시 동일 수복 (bi·pms·rpa·cms·mes가 동일 위험군이었음) + +### 1.2 매퍼가 참조하나 schema에 정의 없는 테이블 (2레이어 누락) +- **증상:** ERP에서 mode=always로 바꿔도 여전히 `relation does not exist` 잔존. +- **근본원인:** 애초에 schema.sql에 **정의 자체가 없는** 테이블 11종. 직접 분석으로 잡히는 레이어(6)와 조인으로만 드러나는 레이어(5, erp_bom·employee 등)가 따로 존재. +- **해결 패턴:** 매퍼 XML을 역설계해 `schema-missing-tables.sql` 별도 파일로 정의 → **해당 파일만 mode=always** 적용(기존 시드 무영향). 누락 컬럼은 멱등 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`. + +### 1.3 PostgreSQL 방언 함정 2종 +- **ROUND(double, int) 불가:** MES `productionKpi` 500. PG는 `round(double precision, int)` 시그니처가 없음 → **전체 식을 `::numeric` 캐스팅** 후 ROUND. +- **ORDER BY/함수에서 SELECT 별칭 참조 불가:** ERP finance costVariance 500. PG는 별칭을 함수 인자·ORDER BY 식 내부에서 참조 못 함 → **별칭 대신 전체 식을 반복** 기술. + +### 1.4 "테이블 누락"과 "파라미터 이슈"를 구분하라 +- **증상:** 스키마 수복 후에도 일부 엔드포인트 500/4xx 잔존. +- **근본원인:** ERP procurement 2개는 필수 파라미터(vendorId/expiryDate) 미전달이 원인 — 테이블 문제가 아니라 **정상 동작**이었음. +- **해결 패턴:** 오류 분류를 먼저: relation 누락 / 컬럼 누락 / 방언 / 파라미터·계약 문제를 각각 다른 티켓으로. 일괄 "스키마 문제"로 뭉뚱그리면 헛수고. + +### 1.5 시드는 반드시 멱등 + 데모 스코프 정렬 (kintex) +- **증상:** 시드를 넣었는데도 정산·결제 등 행사스코프 화면이 텅 빔. +- **근본원인:** 화면이 비는 진짜 원인은 데이터 부재가 아니라 **시드가 데모 해소행사(workspaces[0]=start_date 최소, `e-2026-live`)에 안 묶임**. 화면은 현재 선택된 행사 스코프로 조회한다. +- **해결 패턴:** 데모 시드는 항상 "데모 계정이 실제로 진입하는 스코프(행사/테넌트/멤버십)"에 폐루프로 정렬. 403(행사 미가입)로 도면이 안 열리던 사고도 동일 계열 — 데모 계정 멤버십부터 확인. +- **연관 표준(kintex):** FK 최소화+공통코드 소프트참조, `tenant_id`는 복합 PK 선두, 핫패스 인덱스·view/mview·배치 카탈로그를 데이터 표준 문서로 관리. + +--- + +## 2. 배포 / CI-CD + +### 2.1 웹훅 "완료" 로그인데 실제로는 no-op (1ms 진단법) +- **증상:** push 해도 서버 반영 안 됨. 배포 로그는 "완료"로 찍힘. +- **근본원인 (guardia-rag에서 2중 결함):** ① Gitea에 웹훅 자체가 없었음 ② 서버의 `deploy_server.py`가 구버전이라 해당 repo 처리 블록이 없어 **웹훅을 받아도 1ms 만에 no-op** 종료. +- **해결 패턴:** **배포 로그가 '완료'여도 처리 시간이 1ms면 블록 부재를 의심하라.** 점검 순서: Gitea 웹훅 존재/브랜치/시크릿 → 서버 deploy_server에 repo 블록 존재 → hook test로 E2E(pull→빌드→restart→health) 확인. + +### 2.2 deploy_server.py는 서버 사본이 정본처럼 행동한다 +- **증상:** 로컬 저장소의 deploy_server.py를 고쳐도 배포 동작이 안 바뀜. +- **근본원인:** 실제 실행되는 것은 서버 `/opt/.../deploy_server.py` 사본. 로컬만 고치면 무의미. +- **해결 패턴:** deploy_server.py 수정 시 **서버 사본 반영 + 서비스 재시작까지가 한 세트.** 교체 전 `.bak` 백업. + +### 2.3 Gitea 웹훅 3대 고전 이슈 +- **증상:** 웹훅 미발화 또는 403. +- **근본원인/해결:** ① 웹훅 URL이 외부 도메인이면 NAT 헤어핀으로 실패 → **localhost로** ② secret 불일치 → 403, 배포 서버 설정과 일치시킴 ③ Gitea `app.ini` `ALLOWED_HOST_LIST`에 loopback 미허용 → 추가. + +### 2.4 배포 대상 경로가 git 체크아웃이 아니면 pull이 영원히 no-op +- **증상:** guardia-rag — 웹훅·배포 스크립트 정상인데 서버 코드가 안 바뀜. +- **근본원인:** `/opt/guardia-rag`가 git 저장소가 아니었음(수동 복사본) → `git pull` no-op. +- **해결 패턴:** 배포 대상 디렉터리는 반드시 git 체크아웃으로 전환(데이터 디렉터리 보존) 후 자동배포 연결. 서버 HEAD 해시로 반영 검증. + +### 2.5 배포 블록이 프론트만 배포하는 부분 결함 +- **증상:** manager — 프론트 변경은 반영되는데 백엔드 변경이 라이브에 안 나타남. +- **근본원인:** deploy_server의 해당 블록에 백엔드 rsync/재시작 단계가 없었음. +- **해결 패턴:** 배포 블록 신설·검증 시 **프론트/백엔드/마이그레이션/재시작 4단계를 체크리스트로** 확인. "일부만 배포되는" 블록은 정상처럼 보여 오래 숨는다. + +### 2.6 Flyway 마이그레이션은 라이브 dry-run 후 배포 (kintex 표준) +- **증상:** 마이그레이션 실패로 배포 롤백 반복. +- **해결 패턴:** 배포 전 운영 DB에 **`BEGIN … ROLLBACK` dry-run**으로 신규 V 스크립트를 검증. 추가로 시크릿 fail-fast 프로파일 확인 + 배포 후 health 게이트 통과까지가 완료 조건. + +### 2.7 공유 트리에서는 파일단위 커밋 +- **증상:** 여러 트랙이 같은 워킹트리에서 작업하다 서로의 미완성 변경이 교차 커밋됨. +- **해결 패턴:** `git add .` 금지 — 자기 작업 파일만 명시적으로 스테이징(파일단위 커밋). kintex 다수 배포 사고 후 표준화. + +### 2.8 자격증명 회전 시 배포 인프라 전체 동기화 +- **증상:** 일부 repo만 자동배포 죽어 있음(itsm/web/manager/docs). +- **근본원인:** Gitea 비밀번호 회전 후 deploy_server와 서버 원격 사본에 **구버전 자격증명이 잔존.** +- **해결 패턴:** 자격증명 회전은 "사용처 인벤토리 → 전 지점 일괄 갱신 → repo별 push/pull 검증"까지. 범용 push 스크립트로 지점 통일. + +### 2.9 서버 빌드 산출 경로 함정 +- **증상:** 홈페이지 — 빌드 성공인데 라이브 미반영. +- **근본원인:** 빌드는 `/opt/.../src`에서 하고 서빙은 별도 웹루트 — 산출물 복사 단계 누락. +- **해결 패턴:** "빌드 위치 ≠ 서빙 위치"를 배포 스크립트에 명시. push 스크립트의 bundle 단계가 일시 실패하면 수동 bundle→SFTP→push 동일 경로로 복구 가능함을 기록해 둠. + +--- + +## 3. AI / LLM + +### 3.1 대형 모델 500 에러의 진범은 코드가 아니라 서버 RAM +- **증상:** Ollama generate 500. 타임아웃을 늘려도(30→120s) 재발. +- **근본원인:** 서버 가용 RAM ~1.5~2.6GiB인데 7B/8B 모델은 4.3~4.6GiB 필요 → `model requires X GiB > available` 500. **swap은 무효** — Ollama는 물리 RAM만 검사한다. +- **해결 패턴:** **소형 모델 채택**이 정답: 비전=`moondream`, 텍스트=`llama3.2:1b`→`qwen3:1.7b`(+`deepseek-r1:1.5b`). 코드 수정(타임아웃)만으로 해결 안 되는 인프라 문제임을 먼저 판별하라(에러 메시지에 RAM 수치가 있음). + +### 3.2 Ollama 타임아웃 표준 = 120s (전 시스템 통일) +- **증상:** CPU 추론 콜드스타트에서 30s/45s 타임아웃으로 AI 기능 산발 실패. +- **해결 패턴:** 전 솔루션 OllamaClient/HTTP 타임아웃을 **generate·vision 모두 120s**로 통일(10여 개 시스템 전수 수정 이력). 신규 클라이언트도 120s가 기본. + +### 3.3 모델 태그 정확성 — `:latest`가 항상 있는 게 아니다 +- **증상:** `/api/generate` 404. +- **근본원인:** 서버에 `llava:7b`로 pull된 모델을 코드가 `llava`( = `:latest`)로 호출. +- **해결 패턴:** 서버 `/api/tags` 실측 태그를 그대로 사용 + model-status 진단 엔드포인트로 상시 확인 가능하게. + +### 3.4 콜드로드 위험 관리 +- **증상:** 임베딩/검색은 가벼운데 생성·비전 호출 순간 서버 전체가 흔들림. +- **근본원인:** 생성/비전 모델 콜드로드가 RAM을 순간 점유. +- **해결 패턴:** 소형 모델 기본 + **비전 자동로드 금지** + 동시성 제한 + 실패 시 "검색만 degraded:true" 폴백(전체 다운 대신 부분 기능 유지). + +### 3.5 폴백 체인과 프로바이더 아키텍처 +- **패턴:** 3계층 추론 폴백 **Claude(외부 승인 단일 경로) → Qwen3(온프레미스 소형) → 기존 소형 모델**. `AiTextRouter`+`AiConfig` 설정형 전환(UIWS 패턴). API 키는 서버 env에서만 로드 — DB·코드·커밋·로그·응답 기재 금지, 실패 시 자동 폴백. +- **경계 규칙:** 솔루션은 **중앙 guardia-rag 경유만** — 개별 솔루션에서 LLM 직접호출 신설 금지. 계약 URL 정합 주의(manager·mro에서 `/feedback`→`/rag/feedback` 오배선 실사례). + +### 3.6 목표 스택 vs 개발서버 어댑터 분리 +- **증상:** 고객 목표 스택(Qwen3-32B·vLLM·Milvus·GPU)을 개발서버에 그대로 올리려다 실행 불가. +- **해결 패턴:** 목표 스택은 어댑터/설정으로 정렬하되 개발서버(~2GB·GPU 없음)에서는 **경량 폴백(소형모델·Chroma·Ollama) 강제, 대형 스택 실행 금지.** 기본 env는 현행과 동일하게 유지해 회귀 0. + +### 3.7 AI 답변은 근거 기반 + 데이터는 사전 적재 (kintex) +- **패턴:** AI가 답하는 정보는 **크롤링해서 DB에 먼저 적재**(실시간 외부호출 금지), grounding+인용으로 환각 차단(abstain UX). 토큰 최소화: 결정론 라우팅·소형모델 우선·RAG 축소·캐싱·**집계는 SQL로**(LLM에 집계시키지 않는다). + +--- + +## 4. 프론트 / UI + +### 4.1 rollup win32 크래시 — 서버 빌드를 신뢰하라 +- **증상:** 로컬 Windows에서 Vite/rollup 빌드가 렌더 단계 크래시. +- **근본원인:** rollup win32 네이티브 이슈(로컬 환경 한정). +- **해결 패턴:** 로컬은 esbuild 등으로 문법 검증만 하고 **실빌드는 서버(Linux) 빌드를 신뢰** → 배포 청크 검증으로 확인. 로컬 크래시 때문에 코드를 의심하지 말 것. + +### 4.2 다크모드에서 컬러 버튼 글자가 어두워지는 버그 +- **증상:** 파란/컬러 배경 버튼·배지의 흰 글자가 다크모드에서 어두운 색으로 뒤집힘 (kintex 77곳+2곳). +- **근본원인:** 텍스트 색이 테마 변수(전경색)에 묶여 다크 전환 시 함께 반전. +- **해결 패턴:** 컬러 배경 위 텍스트는 **`--color-on-accent` 전용 토큰**(라이트/다크 모두 흰색)으로 분리. 신규 컴포넌트도 accent 배경이면 무조건 on-accent 사용. + +### 4.3 병렬 로케일 편집 = 키 유실 +- **증상:** 다국어 작업 후 일부 i18n 키가 사라져 화면에 키 이름이 노출. +- **근본원인:** 여러 에이전트/트랙이 **공유 i18n JSON을 동시 편집** → 마지막 쓰기가 다른 쪽 키를 덮어씀. +- **해결 패턴:** 로케일 파일 편집은 **직렬화** + 편집 후 로케일 간 **키 대조 게이트**(ko/en/zh/ja 키셋 diff)를 통과해야 완료. + +### 4.4 화면이 비는 원인은 UI 버그가 아닐 수 있다 (행사스코프) +- §1.5와 동일 사건의 프론트 측 교훈: "데이터 없음" 신고를 받으면 **API 빈 응답인지, 스코프(선택 행사·권한) 문제인지, 시드 문제인지**를 먼저 갈라라. 프론트 수정으로 덤비면 헛수고. + +### 4.5 UI 레퍼런스는 문자 그대로 — 자체 재해석 금지 +- **증상:** "전부 WISE대로 안 되어 있다" 강한 소유자 피드백(셸·아코디언 메뉴·캘린더·대시보드·로고). +- **해결 패턴:** 정본(UIWS frontend / Nifty ui-elements)을 **구조 그대로 이식**하고 토큰만 번역(kx). 디자인 기준은 학습 md(`DESIGN_SYSTEM_NIFTY.md` 등)로 문서화해 재해석 여지를 제거. 아이콘은 이모지 금지·선(stroke) SVG 직접 제작. + +### 4.6 홈/진입 IA를 기획 1순위로 +- **증상:** 84화면을 설계하고도 **로그인 후 홈이 누락**되는 사고. +- **해결 패턴:** 기획 단계에서 역할별 랜딩(디폴트 visitor, 로그인 후 role→홈 라우팅)과 메뉴 게이트를 최우선 정의. 미인증 루트는 로그인 폼이 아니라 **제품 소개 히어로 랜딩**. + +### 4.7 이미지 프레임과 실측 비율 정합 +- **증상:** 세로 포스터가 16:11 가로 카드에 늘어남/잘림. +- **해결 패턴:** 에셋 실측 비율(0.67~0.8)에 맞춘 프레임(3:4) + `object-fit: cover`. 외부 이미지는 **다운로드해 빌드 내장**(핫링크 금지)이 기본. + +### 4.8 Stitch(외부 디자인 도구) 불안정 시 문서화 폴백 +- **증상:** Stitch 생성 2회 연속 실패로 화면 작업 블로킹. +- **해결 패턴:** design.md에 스펙이 이미 있으므로 **스펙 직접 구현으로 폴백하고 폴백 사실을 문서화.** 외부 도구는 경유 원칙이되 단일 실패점이 되게 두지 않는다. + +### 4.9 기타 잔사고 +- **favicon:** repo의 favicon.ico가 톰캣 기본 아이콘인 채 배포 — 브랜드 에셋도 검증 대상. +- **CSS 변경 미반영 신고:** 실제로는 브라우저 캐시 — 배포 검증은 번들 해시/청크 내용으로. +- **반응형:** 전 화면 풀블리드·전 브레이크포인트·빈 여백 금지를 전역 NFR로 못 박아야 화면별 재작업이 줄어든다. + +--- + +## 5. 프로세스 / 하네스 운영 + +### 5.1 하네스 workspace-루트 등록 누락 (반복 사고) +- **증상:** 스킬/에이전트를 만들었는데 루트 세션에서 트리거되지 않음. +- **근본원인:** 하네스가 `workspace//.claude/`에만 존재 — 루트 `.claude/`에 미등록 (ITSM·Manager·UIWS·ESN·OCR 등 다수 사후 등록 이력). +- **해결 패턴:** 하네스 생성 시 **사용 위치(루트 vs 솔루션) 기준으로 등록 위치를 확정**하고, 주기적 "하네스 감사"로 ①루트 미등록 스킬 ②오케스트레이터가 참조하나 **어디에도 존재하지 않는 에이전트**(crm-* 4종, solution-devops-dev 실사례)를 검출·보수. + +### 5.2 MyBatis `@MapperScan`은 annotationClass를 지정하라 +- **증상:** OCR 기동 크래시 — TemplateMapper 빈 누락. +- **근본원인:** 광범위 `@MapperScan`이 인터페이스 스캔을 오동작. +- **해결 패턴:** `@MapperScan(annotationClass = Mapper.class)` 표준 — @Mapper 붙은 인터페이스만 빈 등록. 표준 프레임워크 명세에 편입됨. + +### 5.3 Spring bean 이름 충돌 +- **증상:** 신규 모듈 추가 후 기동 실패(bean-name collision). +- **근본원인:** `system/message`와 기존 `work/message`처럼 **다른 패키지의 동일 클래스명**이 같은 빈 이름 생성. +- **해결 패턴:** 공통 명사(message·notice 등) 모듈 신설 시 기존 패키지와 클래스명 충돌 여부 grep 후 명명(접두사) — 컴파일은 통과하고 기동에서 터지므로 배포 전 기동 테스트 필수. + +### 5.4 공유 파일 단일 소유 규칙 +- **증상:** 여러 에이전트가 App.jsx(라우팅)·네비게이션·i18n 등 공유 파일을 동시 수정 → 충돌·회귀. +- **해결 패턴:** 오케스트레이션 시 **공유 파일은 단일 에이전트가 소유**(예: 라우팅·네비 = renewal-dev 단독)하고 나머지는 요청만 한다. 데이터 목록(solutions.js 등)은 스프레드 병합 대신 단일 출처 유지. + +### 5.5 소유자 피드백은 권위 로그 파일로 전수 기록 +- **패턴:** 세션 중 지시를 `docs/OWNER_FEEDBACK.md` 같은 단일 권위 파일에 상태(완료/배포중/대기)와 함께 전수 기록 — 누락 방지와 "다시 실행" 요청의 기준점이 된다. 처리 로그(커밋 해시·마이그레이션 번호)도 함께. + +### 5.6 산출물(문서) 갱신 정책 +- **패턴:** 개발계획서·설계서는 개발 전/중 1회, 사용자·운영자 지침서는 **완성+QA 후 최종 메뉴 기준 1회.** UI가 요동치는 중에 지침서를 만들면 전량 재작업(비용) — "최초 1회 + 최종 1회, 중간 갱신 금지". + +### 5.7 하네스 간 경계(중복 회피) 명시 +- **패턴:** 신규 하네스는 반드시 인접 하네스와의 경계를 선언(예: 검색 인프라=rag, 환각방지=ai-trust, 이 하네스는 그 위 레이어만). 경계 없는 하네스는 서로 같은 파일을 재구현하며 §5.4 사고를 낳는다. + +### 5.8 오류 응답·보안 불변 +- **패턴:** 스택트레이스는 절대 노출하지 않고 ID+요약만 반환(§1.1의 누출 차단 핸들러와 세트). 자격증명·IP·키는 코드/커밋/로그/문서 어디에도 기재 금지 — 지식 문서(본 문서 포함)도 동일. + +### 5.9 "동작 안 함" 신고는 실경로부터 확인 +- **증상:** fa 솔루션 미인증 POST가 405 — 라우트 고장으로 오인. +- **근본원인:** 라우트는 정상, 실제 경로가 다름(`/api/fa/auth`) — 기존 특성. +- **해결 패턴:** 고장 신고를 받으면 수정 전에 **정상 계약(실경로·필수 파라미터·인증 요구)을 먼저 실측**해 "고장"인지 "오사용"인지 판별. + +--- + +## 6. 인프라 / 보안 운영 + +### 6.1 Java 서비스 env 주입은 systemd drop-in으로 +- **증상:** 전 서비스에 공통 환경변수(AI 키·admin 비번 참조)를 배포해야 하는데, 대부분의 Java 서비스가 EnvironmentFile 없이 명령줄 인자로 기동됨. +- **해결 패턴:** 기존 유닛 파일과 ExecStart를 건드리지 않고 **systemd drop-in(`ai-env.conf`)으로 EnvironmentFile만 추가** + daemon-reload. 17개 서비스에 무중단 일괄 적용된 검증 패턴. + +### 6.2 시크릿은 서버 내부에서 생성·암호화하고 값은 어디에도 남기지 않는다 +- **패턴:** admin 비밀번호는 서버에서 랜덤 생성 → AES-256-GCM 암호화 파일(600) + 별도 키파일(root 600) + root 전용 복호 헬퍼로 관리. 전 과정이 서버 내부 crypto로 이뤄져 세션 로그·커밋·문서에 값이 노출될 여지 자체를 제거. `admin123` 류 시드 하드코딩은 표준 위반. + +### 6.3 인증 표준: JWT+RBAC 위에 2FA를 "레이어로만" 추가 +- **증상:** 인증 이식 시 기존 auth를 통째로 교체하면 전 사용자 로그인 장애. +- **해결 패턴:** 기존 auth가 있으면 **교체 금지 — 2FA(TOTP RFC6238)만 레이어 추가**, 없으면 전체 이식. 로그인 실패 잠금 포함. 토큰 키는 앱별 분리(예: `uiws_*`)로 세션 간섭 방지. + +### 6.4 읽기전용/시간 가드는 백엔드+UI 이중 방어 +- **증상:** "금일 이전 업무일지 조회 전용" 같은 정책을 UI에서만 막으면 API 직접 호출로 우회됨. +- **해결 패턴:** **백엔드 403(저장된 데이터 기준 판정, 파라미터 조작 우회 차단) + UI 차단의 이중 방어.** 판정 기준은 요청값이 아니라 저장된 값(workDate)이어야 우회가 안 된다. + +### 6.5 외부 클라우드·발송 채널은 소유자 승인 게이트 +- **패턴:** EAS 클라우드 빌드(G3), SMTP 발송, root SSH, 외부 API(Anthropic 단일 예외) 등 경계를 넘는 작업은 **승인 게이트로 명시하고 승인 전엔 준비물(eas.json·에셋)까지만** 진행. 승인 이력은 CLAUDE.md/메모리에 날짜와 함께 기록. + +### 6.6 상시 회귀 테스트를 배포 완료 조건으로 +- **패턴:** 전 시스템 공용 회귀 스위트(예: 126/126)를 배포·수복 후 반드시 재실행 — "고친 것"과 "깨뜨린 것"을 같은 게이트로 검증. 테스트 스크립트의 인증도 하드코딩 대신 런타임 조달(암호화 저장소)로 유지. + +### 6.7 API 응답 스키마에서 민감 컬럼은 구조적으로 제외 +- **패턴:** `ip_addr`·`ssh_user`·`os_pw_enc` 같은 컬럼은 마스킹이 아니라 **응답 스키마(ServerOut)에서 아예 제외** — 실수로 새는 경로를 구조적으로 차단. 자격증명 컬럼은 AES-256-GCM 암호화 저장. + +--- + +## 7. 검증(QA) 운영 + +### 7.1 경계면(shape) 교차 검증은 모듈 완성 "직후" 점진 수행 +- **증상:** 백엔드 봉투(`PageResponse`)를 프론트가 배열로 언랩하거나, `audioId` 타입 불일치 등 — 컴파일은 통과하고 런타임에서만 터짐(UIWS 모바일 실사례 2건). +- **해결 패턴:** 백엔드 응답 shape과 프론트 호출부를 **동시에 읽어 교차 비교**하는 QA를 각 모듈 완성 직후 돌린다. 전부 만든 뒤 몰아서 하면 수정 범위가 폭발. + +### 7.2 "적용 완료" 판정은 라이브 실측으로 +- **패턴:** 대규모 전파(WISE 18종 등) 후 완료 판정은 ①health 게이트 ②스팟체크(라우트+인증 가드) ③실 E2E(대표 시나리오 1건) ④전체 회귀의 4단계. 파일만 바뀐 것과 라이브에 반영된 것은 다르다(§2 전반의 이유로). + +### 7.3 대량 전파는 감사 매트릭스 → 웨이브 병렬 → 직렬 배포 +- **패턴:** N개 솔루션 일괄 작업은 먼저 **유형 매트릭스 감사**(브랜딩만/승격/보강/신규)로 분류 → 유형별 웨이브 병렬 구현 → **배포는 직렬**(health 게이트 하나씩). 병렬 배포는 장애 원인 격리를 불가능하게 한다. + +--- + +## 부록: 배포 전 체크리스트 (교훈 요약) + +1. [ ] 스키마: 신규 테이블/컬럼이 mode 정책상 실제 적용되는가? 시드 멱등? (§1.1~1.2) +2. [ ] Flyway: 라이브 BEGIN…ROLLBACK dry-run 통과? (§2.6) +3. [ ] 커밋: 파일단위 스테이징인가? 공유 파일 소유자 확인? (§2.7, §5.4) +4. [ ] 웹훅: 배포 로그 처리시간 1ms 아님? 서버 HEAD 갱신 확인? (§2.1, §2.4) +5. [ ] 배포 블록: 프론트+백엔드+마이그레이션+재시작 4단계 모두? (§2.5) +6. [ ] health 게이트 통과 + 번들/청크 실측 검증(캐시 아님 확인)? (§2.6, §4.9) +7. [ ] 기동 테스트: bean 충돌·매퍼 빈 누락 없음? (§5.2~5.3) +8. [ ] AI: 소형모델·120s·태그 실측·중앙 rag 경유? (§3.1~3.5) +9. [ ] 시드: 데모 계정이 진입하는 스코프에 묶였는가? (§1.5) +10. [ ] 보안: 스택트레이스·자격증명·키 미노출? (§5.8) diff --git a/plugins/zio-harness/knowledge/guardia/operations-cicd.md b/plugins/zio-harness/knowledge/guardia/operations-cicd.md new file mode 100644 index 0000000..24bcae8 --- /dev/null +++ b/plugins/zio-harness/knowledge/guardia/operations-cicd.md @@ -0,0 +1,259 @@ +# GUARDiA 운영·CI/CD 지식 문서 + +> **출처:** `workspace/guardia-docs/` 운영·배포 가이드(19·20·21·43·48번 등) + 루트 `CLAUDE.md` 하네스 변경이력 + `docs/가디아_운영_노하우_전수.md` +> **작성:** 2026-07-12 | **대상:** GUARDiA 전 솔루션 운영·배포 담당 에이전트/개발자 +> **보안:** 이 문서에는 비밀번호·API 키·webhook secret·SSH 자격증명을 기재하지 않는다. 서버는 "GUARDiA 인프라 서버"(zioinfo.co.kr) 로 표기한다. + +--- + +## 1. 배포 파이프라인 전체 흐름 + +### 1.1 표준 흐름 (한 줄 요약) + +``` +workspace 소스 수정 → 모노레포 git commit + ↓ .git/hooks/post-commit 자동 실행 +git archive (추적 파일만 추출) → repos/{시스템}/ 동기화 + ↓ +repos/{시스템} → Gitea(git.zioinfo.co.kr) push + ↓ Gitea webhook (POST http://127.0.0.1:9999) +deploy_server.py (GUARDiA 인프라 서버, 포트 9999) + ↓ 레포별 배포 블록 실행 +서버 /opt/{시스템}/src git pull → 빌드(npm/mvn/pip) → 산출물 복사 + ↓ +systemctl restart {서비스} → health 게이트 확인 +``` + +### 1.2 단계별 상세 + +| 단계 | 위치 | 내용 | +|------|------|------| +| ① 소스 수정 | `C:\GUARDiA\workspace\<시스템>\` | 모든 개발은 workspace에서만. repos/ 직접 수정 금지 | +| ② 모노레포 커밋 | `C:\GUARDiA` (.git) | commit 시 post-commit 훅이 자동 발동 | +| ③ repos 동기화 | `C:\GUARDiA\repos\<시스템>\` | `git archive HEAD workspace/{시스템}/ \| tar -x` — **추적 파일만** 추출되므로 node_modules 유입 원천 차단 | +| ④ Gitea push | `git.zioinfo.co.kr/zio/` | repos/는 각각 독립 git repo (모노레포 .gitignore 처리) | +| ⑤ webhook 수신 | 서버 `/opt/zioinfo/deploy_server.py` :9999 | systemd 서비스 `zioinfo-deploy`. 로그: `/var/log/zioinfo/deploy.log` | +| ⑥ 배포 실행 | 서버 `/opt/<시스템>/` | 레포별 블록: git pull → 빌드 → 산출물 복사 → 서비스 재시작 | +| ⑦ health 게이트 | 각 서비스 health 엔드포인트 | 200/UP 확인 후 배포 완료 판정. 실패 시 롤백 검토 | + +### 1.3 시스템별 배포 블록 (deploy_server.py) + +- **zioinfo-web(홈페이지):** git pull → `frontend npm run build`(Vite outDir = `backend/src/main/resources/static/`) → 정적 파일 `/var/www/zioinfo/` 복사 → `mvn package` → app.jar 교체 → `systemctl restart zioinfo` +- **guardia-itsm(FastAPI):** git pull → `rsync -a --delete`(\_\_pycache\_\_·.git 제외) `/opt/guardia/src/ → /opt/guardia/app/` → venv pip install → `systemctl restart guardia` +- **guardia-manager:** git pull → npm build → dist를 `/var/www/manager/` 복사 → 백엔드 rsync → 재시작 (★한때 프론트만 배포되는 결함이 있어 백엔드 rsync 단계가 추가됨 — 2026-07-04) +- **Spring Boot 단일 jar 솔루션(ERP·CRM·OCR·BI·PMS·RPA·Groupware·Portal·Mall·CMS·MES·ESN 등):** frontend → backend static 번들 → 단일 jar 빌드 → jar 교체 → systemd 재시작 +- **guardia-rag(Python):** git pull → pip → restart → health (2026-07-04 파이프라인 완성) + +### 1.4 수동 배포 (자동 배포 불가 시) + +```bash +# 개발 PC에서 — 특정 시스템/전체 +python scripts/deploy/manual_deploy.py guardia-itsm # 별칭 itsm/web 가능 +python scripts/deploy/manual_deploy.py # 전체 + +# 서버에서 직접 (가장 확실) — 예: zioinfo-web +SRC=/opt/zioinfo/src +git -C $SRC fetch origin main && git -C $SRC reset --hard origin/main +cd $SRC/frontend && npm run build --silent +cp -rf $SRC/backend/src/main/resources/static/. /var/www/zioinfo/ +cd $SRC/backend && mvn clean package -DskipTests -q +cp $SRC/backend/target/zioinfo-web-*.jar /opt/zioinfo/app/app.jar +systemctl restart zioinfo && sleep 5 && systemctl is-active zioinfo +``` + +- ITSM 웹 UI에서도 배포 트리거 가능: `POST /api/cicd/deploy`(JWT 인증), `GET /api/cicd/status` +- Windows Task Scheduler: `GUARDiA-AutoDeploy-Hourly`(1시간마다 manual_deploy 전체), `GUARDiA-DailyParent`(매일 09:00 건강검진·성장일지) + +--- + +## 2. 배포 함정·체크리스트 (실사고 기반) + +### 2.1 파이프라인 인프라 함정 + +| # | 함정 | 증상 | 해법 | +|---|------|------|------| +| 1 | **deploy_server.py 서버 사본 미반영** | 로컬에서 deploy_server.py를 고쳐도 서버는 구버전 실행 | 수정 시 반드시 서버 `/opt/zioinfo/deploy_server.py`에 반영 + `systemctl restart zioinfo-deploy`. 백업본(.bak) 생성 후 교체 | +| 2 | **배포 블록 부재 = 1ms no-op** | 배포 로그에 '완료'가 찍혀도 처리 시간이 1ms 수준이면 해당 repo 블록이 deploy_server.py에 없는 것 | 로그의 소요 시간 확인. 신규 솔루션 추가 시 deploy_server.py에 배포 블록 추가 필수 (guardia-rag 사례: 웹훅 수신은 됐지만 블록 부재로 무동작) | +| 3 | **Gitea webhook 자체 부재** | push해도 :9999에 요청이 안 옴 | 신규 repo는 Gitea에 webhook 등록 필수 (URL=localhost:9999, push 이벤트, main 브랜치, secret 일치). hook test API로 검증 | +| 4 | **webhook 로컬 차단** | webhook 발송 실패 | `/etc/gitea/app.ini` `[webhook] ALLOW_LOCAL_NETWORKS = true` 필수. loopback을 ALLOWED_HOST_LIST에 포함 | +| 5 | **webhook URL이 외부 도메인** | NAT 헤어핀으로 전달 실패/지연 | webhook URL은 `http://localhost:9999`(서버 내부 루프백)로 설정 | +| 6 | **webhook secret 불일치 (403)** | deploy_server가 403 반환 | Gitea webhook secret과 deploy_server 설정값 일치 확인 (값은 문서에 기재 금지) | +| 7 | **서버 /opt 소스가 git 체크아웃이 아님** | webhook이 와도 git pull이 no-op | `/opt/<시스템>/src`는 반드시 Gitea repo의 git 체크아웃이어야 함 (guardia-rag 사례: 미git화 → git 체크아웃 전환) | +| 8 | **remote에 구버전 자격증명** | git pull 인증 실패로 자동배포 중단 | 서버 /opt/*/src remote URL의 자격증명 일관성 점검 (2026-06-12 itsm/web/manager/docs 복구 사례) | + +### 2.2 빌드·소스 함정 + +| # | 함정 | 해법 | +|---|------|------| +| 9 | **수동 배포 후 자동 배포 미작동** — 서버 커밋이 Gitea와 어긋나 이후 webhook이 '변경 없음' 처리 | `git fetch origin main && git reset --hard origin/main`으로 서버 소스를 origin에 강제 정렬 | +| 10 | **node_modules 실수 커밋** | .gitignore에 node_modules/·dist/·build/ 추가. post-commit이 git archive를 쓰므로 추적 파일만 넘어가는 구조 유지 | +| 11 | **nginx/브라우저 정적 캐시** — 배포해도 화면 미반영 | 정적 파일 강제 복사 + `systemctl reload nginx`; JS/CSS는 Vite 해시로 자동 무효화; 최종적으로 Ctrl+Shift+R | +| 12 | **Vite outDir 착각** — dist/를 찾다 파일 없음 | zioinfo-web은 outDir이 `backend/src/main/resources/static/` — 그 경로에서 복사 | +| 13 | **로컬 rollup win32 크래시** | 로컬 빌드 실패해도 서버 빌드(npm+mvn)를 신뢰하는 경로로 진행 (esbuild 대체 검증 병행) | +| 14 | **공유 트리 교차 커밋** | 여러 트랙이 같은 트리를 만질 때는 **파일 단위 커밋**으로 교차 오염 방지 (kintex 표준) | + +### 2.3 DB·스키마 함정 + +| # | 함정 | 해법 | +|---|------|------| +| 15 | **Flyway/DDL 마이그레이션 배포 사고** | 배포 전 라이브 DB에 **dry-run(BEGIN…ROLLBACK)** 필수 (kintex 표준화 교훈) | +| 16 | **`sql.init.mode: never` + schema.sql 후행 확장 = 누락 테이블** | 초기 배포 후 schema.sql에 테이블을 추가해도 재적용 안 됨 → 런타임 `relation does not exist` 500. 표준 수복: 시드 멱등화(유니크 인덱스) + `mode=always` + `continue-on-error` + DataAccessException 핸들러(스택트레이스 누출 차단) | +| 17 | **MyBatis 매퍼 빈 누락 크래시** | `@MapperScan(annotationClass = Mapper.class)` 사용 (OCR TemplateMapper 사례) | +| 18 | **시크릿 미주입 기동 실패** | 배포 전 시크릿 **fail-fast 프로파일** 확인 — env(systemd drop-in EnvironmentFile) 주입 여부 점검 | + +### 2.4 배포 전 체크리스트 (요약) + +``` +□ workspace에서만 수정했고 repos/ 직접 수정 없음 +□ 파일 단위 커밋 (공유 트리 교차 방지) +□ DDL 변경 시 라이브 Flyway dry-run(BEGIN…ROLLBACK) 통과 +□ deploy_server.py 변경 시 서버 사본 반영 + zioinfo-deploy 재시작 +□ 신규 repo면: Gitea webhook 등록 + deploy_server 배포 블록 + /opt git 체크아웃 3종 세트 +□ push 후 /var/log/zioinfo/deploy.log 에서 소요 시간 확인 (1ms면 블록 부재 의심) +□ 서비스 health 엔드포인트 200/UP 확인 (health 게이트) +□ 배포 후 회귀: run_full_test.py 통과 +``` + +--- + +## 3. 서비스 운영 맵 + +### 3.1 접속 체계 + +- 공개 접근은 **서브도메인 + nginx 리버스 프록시**: `zioinfo.co.kr`(홈페이지) / `itsm.` / `manager.` / `mail.` / `git.`(Gitea) / `jenkins.` / `docs.` / `kintex.`(킨텍스) 등 +- nginx 설정: `/etc/nginx/sites-available/{subdomain}.zioinfo.co.kr` +- SSL: Let's Encrypt(certbot 자동 갱신) 기본, 일부 ZeroSSL(acme.sh). 신규 서브도메인은 `certbot --nginx -d {sub}.zioinfo.co.kr` 발급 + +### 3.2 포트 맵 (GUARDiA 인프라 서버 내부) + +| 포트 | 서비스 | 비고 | +|------|--------|------| +| 9001 | GUARDiA ITSM (FastAPI) | 허브. 전 솔루션 연동 기준점 | +| 8002/8090 | GUARDiA Manager | ITSM JWT 재사용 | +| 8082 | zioinfo-web (홈페이지 Spring Boot) | 정적은 /var/www/zioinfo + nginx | +| 8003~8013 | ERP·CRM·OCR·BI·PMS·RPA·Groupware·Portal·Mall·CMS·MES | Spring Boot 단일 jar, DB `{sol}_db` | +| 8015/8016 | zioinfo-ESN / GUARDiA ESN | ESL 플랫폼 | +| 8018/8019 | MRO / Signage(e-SignBoard) | | +| 8021 | KINTEX | kintex.zioinfo.co.kr | +| 8025/8026 | 웹메일 (SMTP UI/백엔드) | Postfix/Dovecot 연동 | +| 8080 | Jenkins | 보조 CI (주력은 deploy_server) | +| 9003 | Gitea 내부 | 외부는 git.zioinfo.co.kr(443) 경유 | +| 9999 | deploy_server.py (webhook) | systemd `zioinfo-deploy` | +| 11434 | Ollama | 온프레미스 AI. RAM 제약으로 소형 모델(qwen3:1.7b·llama3.2:1b·moondream) 운용 | +| — | guardia-rag (중앙 RAG) | 전 솔루션 AI 질의 경유점 (LangChain+ChromaDB) | + +### 3.3 systemd 서비스 구성 개요 + +- 명명: `guardia`(ITSM)·`zioinfo`(홈페이지)·`guardia-manager`·`zioinfo-mail`·`zioinfo-deploy`(webhook)·`gitea`·`jenkins`·`postgresql`·`ollama` + 솔루션별 `guardia-{sol}.service` (예: guardia-ocr) — 총 17개+ active +- 경로 규약: 소스 `/opt/{sol}/src/`, 실행 `/opt/{sol}/app/`(또는 jar), 정적 `/var/www/{sol}/` +- **AI env 주입:** 전 서비스에 systemd **drop-in**(`ai-env.conf`, EnvironmentFile 추가) 방식 — 기존 ExecStart 불변. 시크릿은 `/opt/guardia/secrets/`(root 600) + env 파일에서만 로드, 코드·커밋·로그 기재 금지 +- 로그: `journalctl -u {서비스} -n 100 --no-pager` / 배포 로그 `tail -50 /var/log/zioinfo/deploy.log` + +```bash +# 전체 상태 빠른 점검 +for svc in nginx zioinfo guardia guardia-manager zioinfo-mail gitea jenkins postgresql ollama; do + printf "%-22s %s\n" $svc "$(systemctl is-active $svc 2>/dev/null)" +done +``` + +### 3.4 health 엔드포인트 패턴 + +| 계열 | 패턴 | 판정 | +|------|------|------| +| FastAPI (ITSM·mail 등) | `GET /health` 또는 `GET /api/health` | JSON `status` 필드 | +| Spring Boot 솔루션 | `GET /api/health` (또는 actuator health) | `UP`/200 | +| 배포 게이트 | 재시작 후 sleep 4~5초 → health 200 확인 | 실패 시 배포 실패 처리 | + +- **health 게이트 원칙:** 직렬 배포(솔루션 다수 동시 배포 시)에서 각 단계마다 health 통과 후 다음 진행. RAM이 빠듯한 서버 특성상 동시 재시작 금지·직렬 빌드가 표준. + +### 3.5 DB 운영 요점 + +- PostgreSQL: 솔루션별 DB 격리(`erp_db`·`crm_db`·`ocr_db`·… , 각 `{sol}_user`), Hikari max 3 (RAM 제약) +- 홈페이지는 SQLite(`/opt/zioinfo/app/data/zioinfo.db`) +- 백업: `pg_dump`(PostgreSQL) / 파일 복사(SQLite) — 일일 백업 루틴 대상 + +--- + +## 4. 테스트 체계 + +### 4.1 상시 전체 테스트 — run_full_test.py + +- 실행: `python3 C:\GUARDiA\scripts\check\run_full_test.py` (paramiko로 서버 내부에서 curl 실행) +- 규모: 22개 그룹 — **현재 126개 테스트**(초기 69 → 93 → 126으로 성장). service_health 그룹이 각 서비스 health를 우선 검사 +- 인증: admin 비밀번호를 **서버 암호화 저장소(root 전용 복호 헬퍼)에서 서버 내부 셸 변수로만 조달** — 값을 로컬로 가져오지 않고 출력·저장하지 않음 +- 결과 저장: `.claude/agents/_workspace/test_results/latest.json` +- 트리거: "테스트 해줘"·"검증해줘"·"배포 확인"·"회귀 테스트" → `test-orchestrator` 스킬 (에이전트 api-tester) + +### 4.2 배포와의 결합 + +- **배포 후 필수 회귀:** 배포 작업(특히 다중 솔루션·deploy_server 변경·스키마 변경) 뒤에는 반드시 126/126 통과를 확인하고 종료 (2026-07-04 WISE 전 솔루션 배포·홈페이지 리뉴얼 모두 이 게이트로 마감) +- 스모크: 각 솔루션에 개별 스모크 스크립트가 있으면 우선 실행 후 전체 테스트 (guardia-rag 스모크 3종 사례) +- E2E 검증 표준: push → webhook 수신 → git pull → 빌드 → restart → health → HEAD 커밋 자동 갱신 확인까지가 "자동배포 검증 완료"의 정의 + +--- + +## 5. 운영 점검 루틴 — guardia-ops-check + +정기/요청 시 수행하는 통합 헬스체크. 트리거: "운영 점검"·"서버 기동 확인"·"전체 상태 확인"·"테이블 누락 확인" → `guardia-ops-check-orchestrator` 스킬. + +### 5.1 3단 점검 구성 + +| 단계 | 에이전트 | 내용 | +|------|----------|------| +| ① Git 정합 | git-ops-dev | Gitea 자격증명 설정 상태·repo clone/원격 정합·workspace↔repos↔Gitea↔서버 4-way 동기화 (system-sync-orchestrator와 연계: deploy-verifier/deploy-fixer) | +| ② 서비스 기동 | server-health-checker | 전 solution systemd active + health 엔드포인트 응답 전수 확인 | +| ③ 스키마 무결성 | schema-audit-dev (schema-integrity 재사용) | 매퍼가 참조하는 테이블/컬럼 vs 라이브 DB 전수 대조 → `relation does not exist` 예방. 수복은 schema-fix-dev(멱등 ALTER/CREATE + mode=always + 누출 차단 패턴) | + +### 5.2 일상 운영 루틴 요약 + +```bash +# 1) 서비스 전수 상태 +systemctl is-active {서비스들} # 3.3 스니펫 + +# 2) 배포 최신성 +tail -20 /var/log/zioinfo/deploy.log # 최근 배포 + 소요시간(1ms 의심) +git -C /opt/{sol}/src log --oneline -3 # 서버 HEAD가 Gitea와 일치하는지 + +# 3) webhook 경로 생존 +ss -tlnp | grep 9999 # deploy_server 리스닝 +curl -s -X POST http://127.0.0.1:9999 -H 'Content-Type: application/json' \ + -d '{"repository":{"name":"zioinfo-web"},"ref":"refs/heads/main"}' # "Deploy queued" 기대 + +# 4) 리소스 (RAM 제약 서버) +free -h # Ollama 모델 로드 여부에 민감 — avail 감시 + +# 5) 전체 회귀 +python3 scripts/check/run_full_test.py # 126/126 +``` + +### 5.3 장애 대응 우선순위 + +1. health 실패 서비스 → `journalctl -u {svc} -n 100`으로 원인 (기동 실패 최다 원인: 시크릿 env 미주입·스키마 누락 테이블·RAM 부족 OOM) +2. 자동배포 불통 → §2.1 함정 표 순서대로 (블록 부재 → webhook 부재 → ALLOW_LOCAL_NETWORKS → secret → /opt git화 → remote 자격증명) +3. AI 기능 불능 → Ollama RAM 제약 우선 의심 (7B+ 모델은 서버에서 로드 불가 — 소형 모델 폴백 체인: Claude→Qwen3→소형 Ollama). `ollama-health-orchestrator` 하네스 참조 +4. 화면 미반영 → 캐시/정적 복사(§2.2 #11) → 그래도 안 되면 서버 HEAD 확인(§2.2 #9) + +### 5.4 부속 정기 루틴 + +- **부모 역할 하네스(guardia-parent):** 매일 건강검진(테스트·자가 수복)·성장일지 기록 — Task Scheduler `GUARDiA-DailyParent` 09:00 +- **SSL:** certbot 자동 갱신 + 만료 임박 도메인 월 1회 `certbot certificates` 확인 +- **백업:** DB pg_dump/파일 백업 일일, 배포 전 산출물(.bak) 백업 습관화 + +--- + +## 부록 A. 신규 솔루션 배포 온보딩 절차 (표준) + +1. `workspace//` 소스 완성 → repos/ fresh init → Gitea `zio/` repo 생성 + push +2. 서버: `/opt//src` git clone(체크아웃), DB `{sol}_db`/`{sol}_user` 생성, systemd `guardia-.service` 등록(setup__service.py 패턴) +3. AI env drop-in(`ai-env.conf`) 적용 (시크릿은 env 파일에서만) +4. Gitea webhook 등록 (localhost:9999·push·main·secret) + hook test +5. `deploy_server.py`에 배포 블록 추가 → **서버 사본 반영 + zioinfo-deploy 재시작** +6. push→자동배포 E2E 검증 (HEAD 갱신·health 200) → run_full_test.py 회귀 +7. `guardia-docs` 운영가이드 + 루트 CLAUDE.md 하네스 변경이력 갱신 + +## 부록 B. 보안 불변 규칙 (운영 문서 공통) + +- 자격증명(비밀번호·API 키·secret·SSH 계정)은 문서·코드·커밋·로그·API 응답에 절대 기재/노출 금지 — 서버 env 및 암호화 저장소(AES-256-GCM)에서만 조달 +- 에러 응답에 스택트레이스 미노출 (DataAccessException 핸들러 등 누출 차단) +- 외부 API 금지 원칙 유지 (예외: Anthropic Claude API 단일 경로 — 소유자 승인, 키는 서버 env에서만 로드, 실패 시 Ollama 폴백) +- Gitea 전용 운영 — GitHub push 금지 diff --git a/plugins/zio-harness/knowledge/guardia/solutions-catalog.md b/plugins/zio-harness/knowledge/guardia/solutions-catalog.md new file mode 100644 index 0000000..9b6beba --- /dev/null +++ b/plugins/zio-harness/knowledge/guardia/solutions-catalog.md @@ -0,0 +1,400 @@ +# GUARDiA 솔루션 카탈로그 + +> GUARDiA 프로젝트(`C:\GUARDiA\workspace\`) 전 솔루션의 지식 카탈로그. +> 권위 소스: 루트 `C:\GUARDiA\CLAUDE.md` + 각 솔루션 폴더의 `CLAUDE.md` / `application.yml` (2026-07 기준). +> 보안 원칙: 본 문서에는 비밀번호·API 키·토큰·SSH 자격증명·서버 IP를 기재하지 않는다 (도메인만 사용). + +--- + +## 1. 전체 시스템 맵 + +GUARDiA는 **ITSM을 허브**로 하는 멀티 솔루션 플랫폼이다. 모든 Spring Boot 솔루션은 +ITSM REST API(`:9001`)와 중앙 AI 서비스(guardia-rag `:8020`, Ollama `:11434`)를 공유한다. + +``` + ┌──────────────────────────────────────────┐ + │ GUARDiA ITSM (허브, FastAPI :9001/:8443) │ + │ SR·CMDB·인시던트·KB·SLA·배포·감사·CSAP │ + └──────┬──────────────┬──────────────┬──────┘ + │ JWT 재사용 │ REST 연동 │ APK 중앙저장소 + ┌────────────────┤ │ │ + │ │ │ │ + GUARDiA Manager Spring Boot 솔루션군 guardia-messenger (통합 모바일 런처) + (관제 :8002/:8090) ERP·CRM·OCR(WISE)·BI ITSM·13개 솔루션 화면 통합 (Expo, EAS APK) + PMS·RPA·Groupware· + Portal·Mall·CMS·MES· + HRM·ESN·FA·MRO·Signage + │ + ┌────────────────┼─────────────────────────────┐ + │ │ │ + 중앙 guardia-rag Ollama (:11434) Claude API (예외 승인) + (:8020, RAG/검증/ qwen3:1.7b·llama3.2:1b· env 키 로드 전용, + 에이전틱/학습) moondream·nomic-embed 실패 시 Ollama 폴백 + + [독립 트랙] + zioinfo-web (홈페이지 :8082, zioinfo.co.kr) — 문의만 연결 + zioinfo-mail (웹메일, mail.zioinfo.co.kr) + uiws/UIMS (:8090) — GUARDiA 표준 프레임워크 정본 (WISE 디자인·2FA·공통모듈의 단일 출처) + kintex (:8021, kintex.zioinfo.co.kr) — KINTEX AI 전시·행사시스템 + solution (solution.zioinfo.co.kr) — 솔루션 포털 (시연 가이드) + guardia-docs — 매뉴얼·운영 가이드 문서 저장소 +``` + +**핵심 연동 축** +| 축 | 내용 | +|----|------| +| ITSM 허브 | 각 솔루션의 `ItsmClient` + `ItsmSecuritySanitizer`(ip_addr/ssh_user/os_pw_enc 응답 제거)로 SR·CMDB·인시던트·SLA 데이터 교환 | +| 중앙 AI | guardia-rag 계약 `/answer`·`/verify`·`/agent`·`/structured`·`/feedback`·`/chat` — 솔루션은 LLM 직접호출 대신 중앙 rag 경유 (WISE_APPLY_SPEC) | +| 인증 | JWT + RBAC 공통. GUARDiA 표준(UIMS 승격): TOTP 2차 인증(OTP), admin 비번 env 암호화 주입(AES-256-GCM) | +| 배포 | Gitea(git.zioinfo.co.kr) push → webhook(:9999 deploy_server.py) → 빌드 → systemd 재시작 → health 게이트 | +| 모바일 | guardia-messenger 단일 Expo 앱 = 통합 런처. 각 솔루션 화면은 `app//` 하위. QR 배포(ITSM 중앙 APK 저장소) | + +--- + +## 2. 솔루션 요약 표 + +### 2.1 코어 플랫폼 (Python/FastAPI) + +| 솔루션 | 목적 한줄 | 기술스택 | 백엔드 포트 | 프론트 포트 | DB | 패키지/모듈 | 주요 연동 | +|--------|-----------|----------|------------|------------|-----|-------------|-----------| +| guardia-itsm | AI 기반 레거시 인프라 자율 운영(ChatOps ITSM) 허브 | Python 3.11 FastAPI + SQLAlchemy + Vanilla JS SPA | 9001 (HTTPS 8443) | static SPA 내장 | PostgreSQL(guardia_db) / SQLite(dev) | routers/ 120+ 라우터(1,400+ 엔드포인트) | 전 솔루션의 허브 (SR·CMDB·JWT·APK 저장소) | +| guardia-manager | ITSM·홈페이지·인프라·CI/CD 통합 관제 포털 | React 18+TS+Vite / FastAPI(경량) | 8002 | 8090 | manager_db(모니터링 영속) — 그 외 ITSM API 위임 | frontend/pages + backend/routers | ITSM JWT 재사용, Gitea API, 서비스 모니터링(30초 주기)·이메일/카카오 알림 | +| guardia-rag | 중앙 온프레미스 RAG/AI 서비스 (전 솔루션 공용) | Python FastAPI + LangChain + ChromaDB(Milvus 어댑터) + DuckDB | 8020 | — | ChromaDB 컬렉션(솔루션별 격리) + DuckDB | app/(retrieval·agent·chat·learning·output·observability) | 전 솔루션 AI 계약(`/answer`·`/verify`·`/agent`·`/structured`·`/chat`), Ollama·Claude 폴백 체인 | +| guardia-messenger | 통합 모바일 런처 앱 (전 솔루션 모바일 진입점) | React Native 0.74 + Expo SDK 51 + TS | — (ITSM API 호출) | EAS APK | — | app/(tabs·auth·별 화면·assistant) | ITSM(:8443)·13개 솔루션 API, QR 배포, 자연어 AI 어시스턴트(rag /chat) | + +### 2.2 Spring Boot 솔루션군 (표준: Spring Boot 3.5 Java 17 + React 19 + Vite + TS + MyBatis + PostgreSQL, 단일 jar) + +| 솔루션 | 목적 한줄 | 백엔드 포트 | 프론트 dev 포트 | DB / 유저 | 패키지 | 주요 연동 | +|--------|-----------|------------|----------------|-----------|--------|-----------| +| guardia-erp | AI 스마트 ERP (재무·생산·구매·인사·영업·AI경영분석) | 8003 | 3002 | erp_db | com.zioinfo.erp | ITSM 30+ 라우터(FinOps·G2B·OCR·전자결재), Kafka | +| guardia-crm | 공공기관 고객관계관리 (영업·캠페인·계약·입찰추적) | 8004 | 3003 | crm_db / crm_user | com.zioinfo.crm | ITSM 8모듈 통합(SR·CMDB·인시던트·KB·SLA), 모바일 15화면 | +| guardia-ocr → **WISE AI Platform** | 엔터프라이즈 지식검색·문서 AI (구 OCR, 마스터 브랜드) | 8005 | 3004 | ocr_db / ocr_user | com.zioinfo.ocr | ITSM/ERP/CRM 워크플로우 7종, 크롤러→DuckDB 학습, 중앙 rag | +| guardia-bi | 비즈니스 인텔리전스 (대시보드·KPI·ETL·Text-to-SQL) | 8006 | 3005 | bi_db / bi_user | com.zioinfo.bi | ITSM 데이터 피드 6종(SR·인시던트·CMDB·SLA·배포·CSAP) | +| guardia-pms | JIRA 호환 프로젝트 관리 + SI 산출물·감리 | 8007 | 3006 | pms_db / pms_user | com.zioinfo.pms | ITSM SR↔이슈 연계, RFP→RTM·회의록·소스명세 AI | +| guardia-rpa | 노코드 업무 자동화(봇·워크플로우·트리거·큐·ROI) | 8008 | 3007 | rpa_db / rpa_user | com.zioinfo.rpa | ITSM SR 자동화, OCR·ERP 연계 | +| guardia-groupware | 협업 그룹웨어(전자결재·게시판·일정·근태·예약·쪽지) | 8009 | 3008 | groupware_db / groupware_user | com.zioinfo.groupware | ITSM, 모바일 app/groupware/ | +| guardia-portal | SSO 단일 로그인 통합 업무 포털(카탈로그·위젯·알림) | 8010 | 3009 | portal_db / portal_user | com.zioinfo.portal | 전 GUARDiA 제품 SSO 바로가기, ITSM | +| guardia-mall | 미국 다지점 꽃집 옴니채널 e-커머스 | 8011 | 3010 | mall_db / mall_user | com.zioinfo.mall | 게이트웨이 어댑터(mock 기본), CRM·ERP·OCR·BI·ITSM, 고객앱+관리자앱 | +| guardia-cms | 헤드리스 콘텐츠 관리(Shopping CMS 중심) | 8012 | 3011 | cms_db / cms_user | com.zioinfo.cms | OCR/Mall/CRM/ITSM/BI, 게시 워크플로우·UGC·SEO | +| guardia-mes | 제조실행 통합(WMS+MES+QMS, SPC·OEE·LOT) | 8013 | 3012 | mes_db / mes_user | com.zioinfo.mes | ERP/ITSM/OCR/BI, 현장 작업자 모바일 | +| guardia-hrm | 인사관리(근태·급여·평가·채용·교육·조직) | 8014 | 단일 jar | hrm_db / hrm_user | com.zioinfo.hrm (+uiws·wise 모듈) | ITSM, UIWS 공통모듈·WISE AI 이식 | +| zioinfo-esn | ESL(전자가격표) 통합 플랫폼 1차 통합본 | 8015 | 3014 | esn_db / esn_user | com.zioinfo.esn | 레거시 ESN 6종 통합, Ollama 알람분석·POS 분류 | +| guardia-esn | ESL 통합 플랫폼 2차(레거시 8종 분석 재통합) | 8016 | 단일 jar | guardia_esn_db / guardia_esn_user | com.zioinfo.esn (13도메인) | 멀티테넌트(LGINNOTEK·LGIT·EMART·ZIOINFO), HCore 관제 | +| guardia-fa | 공장자동화(FA) — 설비·안돈·BOM·공정·생산지시·e-Paper | 8017 | 단일 jar | fa_db / fa_user | com.zioinfo.fa (domain: Equipment·AndonEvent·ProcessRoute 등) | ITSM, WISE AI, e-Paper 디스플레이 | +| guardia-mro | 설비보전(EAM/CMMS) + MRO 자재 구매·재고 | 8018 | 단일 jar | mro_db / mro_user | com.zioinfo.mro | 예방보전·작업지시·MTBF/MTTR, AI 예지보전, ITSM | +| guardia-signage | 전자간판(e-SignBoard) 중앙관제 — ESN 응용 | 8019 | 단일 jar | signage_db / signage_user | com.zioinfo.signage | ESN 파생(게이트웨이↔간판 태그), 템플릿·펌웨어 중앙배포 | + +### 2.3 독립 트랙 · 기타 + +| 솔루션 | 목적 한줄 | 기술스택 | 포트/도메인 | DB | 주요 연동 | +|--------|-----------|----------|------------|-----|-----------| +| zioinfo-web | 지오정보기술 회사 홈페이지 + 솔루션 소개 + 관리자 CMS | Spring Boot 3.2.5(Java 17, JPA) + React 18 + Vite | 8082 / zioinfo.co.kr | H2/JPA | ITSM 문의 연결, 전 솔루션 /solution/* 상세 페이지 | +| zioinfo-mail | 자사 SMTP(Postfix/Dovecot) 기반 웹메일 클라이언트 | FastAPI(IMAP/SMTP 프록시) + React SPA | mail.zioinfo.co.kr (웹 8025) | — (IMAP 저장소) | Postfix(25/587)·Dovecot(143/993), 주소록·서명·폴더 | +| uiws (UIMS) | URP인프라본부 업무관리 — **GUARDiA 표준 프레임워크 정본** | React 18+TS / Spring Boot 3.x(Java 17) + JWT+2FA | 8090 (운영 wise.ai.kr) | uiws_db (TB_* 20+) | AI 비서 WISE(Claude+도구 레지스트리), HRM 내재화, Jasper, 네이버웍스 알림 | +| kintex | KINTEX AI 전시·행사시스템 (부스 설계→배선→시각화→옥션→관람객) | React+Vite+TS / Spring Boot 3.x + MyBatis + PostGIS + Redis + 나노바나나 Python 워커 | 8021 / kintex.zioinfo.co.kr | PostgreSQL(+PostGIS) | Gemini 이미지 생성(나노바나나), WISE/UIWS 공통 레이어, Stitch 디자인 | +| solution | 솔루션 포털 — 전 솔루션 접속정보·시연 가이드 | React 19 + Vite + TS | solution.zioinfo.co.kr | — | ITSM CMDB 자산 등록, 홈페이지 이식 완료 | +| guardia-docs | 매뉴얼·운영 가이드 문서 저장소 (md) | Markdown | — | — | 전 솔루션 산출 문서(분석설계서·지침서·설치가이드 40+종) | + +### 2.4 백엔드 포트 전체 할당표 + +| 포트 | 서비스 | 포트 | 서비스 | +|------|--------|------|--------| +| 8002 | guardia-manager (backend) | 8013 | guardia-mes | +| 8003 | guardia-erp | 8014 | guardia-hrm | +| 8004 | guardia-crm | 8015 | zioinfo-esn | +| 8005 | guardia-ocr (WISE) | 8016 | guardia-esn | +| 8006 | guardia-bi | 8017 | guardia-fa | +| 8007 | guardia-pms | 8018 | guardia-mro | +| 8008 | guardia-rpa | 8019 | guardia-signage | +| 8009 | guardia-groupware | 8020 | guardia-rag (중앙 AI) | +| 8010 | guardia-portal | 8021 | kintex | +| 8011 | guardia-mall | 8025 | zioinfo-mail (웹) | +| 8012 | guardia-cms | 8082 | zioinfo-web | +| 8090 | manager 프론트 / uiws 운영 | 9001 / 8443 | guardia-itsm (HTTP/HTTPS) | +| 9999 | deploy_server.py (webhook) | 11434 | Ollama | + +프론트 dev 포트: 3002(erp) 3003(crm) 3004(ocr) 3005(bi) 3006(pms) 3007(rpa) 3008(groupware) 3009(portal) 3010(mall) 3011(cms) 3012(mes) 3014(zioinfo-esn). 나머지 Spring 솔루션(hrm·fa·mro·signage·guardia-esn)은 단일 jar(static 번들)로 dev 포트 고정 없음. + +DB는 단일 PostgreSQL 인스턴스 공유(솔루션별 `_db`/`_user` 분리 계정) — Hikari max 3 표준으로 커넥션 보호. + +--- + +## 3. 솔루션별 상세 + +### guardia-itsm (허브) +- 1,000+ 다중 관공서 레거시 인프라 대상 AI ChatOps 오케스트레이션 플랫폼. 메신저 한 줄 명령 → sLLM 파싱 → 에이전트리스(SSH/SFTP, paramiko) 배포·운영. 대상 서버 소프트웨어 설치 불필요. +- 30개 고도화 항목 완료(알림 WebSocket·첨부·타임라인·RBAC / AI 이상탐지·SR 챗봇·코드리뷰·KB 에이전트·멀티에이전트·예측 유지보수 / CMDB·CAB·문제관리·용량·서비스 카탈로그 / LDAP·2FA·PAM·취약점 스캔·해시체인 감사 / 리포트·분석·SLA·Grafana·FinOps / 멀티테넌트·PWA·i18n·게이트웨이). +- 이후 세대별 확장으로 120+ 라우터·1,400+ 엔드포인트: DR·네트워크·CSAP·디지털트윈·AI거버넌스·비용최적화·공급망보안·용량예측·대화형AI·패치·GRC·워크플로우엔진·장애예측·자동복구·정책엔진·카오스·지식그래프·AIOps·ZTNA/SBOM/N²SF·IDP·GreenOps·레거시현대화·옵저버빌리티·AI-SOC·시민포털·데이터거버넌스 등. +- Vibe 코딩(SR→AI 코드생성→리뷰→Gitea→Jenkins), SI 프로젝트 관리(si_* 9종), Upstage/Ollama OCR 워크플로우, 모바일 300기능 API(mobile2_ext), 나라장터 G2B·입찰 모니터·Jasper 문서 생성. +- 특이사항: 전 솔루션 APK 중앙 저장소(`GET /api/app/public-latest` 공개·CORS 허용), 상시 테스트 스위트(126/126) 회귀 게이트, Fail-Safe 배포(백업→배포→헬스체크→롤백). + +### guardia-manager +- ITSM API를 허브로 쓰는 경량 관제 포털(별도 업무 DB 최소화). NCloud 콘솔 스타일 대시보드(SR 추이·서버 상태·리소스·배포 이력). +- 15+ 서비스 상시 모니터링(systemd+HTTP+포트, 30초 주기) → manager_db 영속 + 다운 시 ITSM 알림·이메일·카카오 알림톡. +- APK 업로드→QR 생성→배포 랜딩(모바일 앱 배포 일원화 지점). + +### guardia-rag (중앙 AI) +- 전 솔루션이 공유하는 온프레미스 RAG 서비스. LangChain + ChromaDB(+Milvus 어댑터) + DuckDB 학습데이터, 솔루션별 컬렉션 격리. +- 계약: `/answer`(vector|hybrid|graph 검색)·`/verify`(근거검증)·`/agent`(tool-use)·`/structured`(결정론 JSON)·`/feedback`(학습)·`/chat`(멀티턴). +- 환각 방지 레이어(grounding·인용·신뢰도·I-don't-know 폴백) + 하이브리드/리랭크/GraphRAG + 관측성(/metrics, OTel). +- 추론 3계층 폴백: Claude → Qwen3(qwen3:1.7b) → 소형 Ollama 모델. 서버 RAM 제약으로 소형모델 기본·degraded 폴백 표준. + +### guardia-messenger +- 단일 Expo 앱(패키지 kr.co.zioinfo.guardia)에 13개 솔루션을 통합한 모바일 런처(솔루션 레지스트리 + 공유 인증/테마/API 라우팅). 기본 화면: 로그인·대시보드·SR 관리·AI 챗봇·알림·설정. +- 1세대 100기능(11카테고리: SR·AI자동화·인증보안·모니터링·현장서비스·승인·KB·준수·UX·통계·협업) + 2세대 100기능(#101~#200: 장애예측·GreenOps·보안점수·CVE·전자서명·AI브리핑·NFC자산·나라장터·시민민원 등 화면 30) + 확장(회의녹음→STT→회의록→SR판단·생체인증·오프라인·다크모드·Kanban·배치SSH·멀티기관). +- UIWS 모바일(app/uiws — 2FA 로그인·업무일지 조회전용 가드·회의록 Jasper PDF) 및 각 솔루션 화면(app/crm·ocr·groupware·portal·mall·hrm-* 등) 포함. +- 자연어 AI 어시스턴트(app/assistant): 크롤·OCR 학습데이터 기반 rag `/chat` 멀티턴 대화(근거검증·인용). EAS 클라우드 빌드 → ITSM 중앙 저장소 QR 배포. +- 빌드 불변 규칙: android/·ios/ 로컬 생성 금지(.easignore), expo-notifications 플러그인 등록 금지, expo-router/babel 추가 금지. + +### guardia-erp +- 6대 모듈: 재무·회계(전표/결산/세무/예산/FinOps) / 생산(BOM/생산지시/공정/품질) / 구매·재고(발주/입출고/협력사/G2B 나라장터) / 인사·급여(LDAP 동기화) / 영업·물류(수주/배송/매출분석) / AI 경영분석(KPI·예측·이상탐지·자연어조회). +- ITSM 30+ 라우터 연동(ItsmClient) — 대표: finops(비용 대시보드)·billing(세금계산서)·upstage_ocr(전표 자동등록)·g2b_opportunity(나라장터 계약→발주)·si_projects(프로젝트 원가)·approvals(전자결재)·cmdb(고정자산)·predictive(수요/매출 예측)·nlquery(자연어→SQL). +- Kafka 이벤트 드리븐, AI 전표 자동 분류. RBAC: ADMIN/CFO/MANAGER/USER/VIEWER, 급여·개인정보 컬럼 AES-256-GCM. + +### guardia-crm +- 공공기관 특화 CRM 135+ 기능(고객·영업·캠페인·계약·입찰추적) + ITSM 통합 8모듈(SR/CMDB/인시던트/KB/모니터/변경/SLA/배포) 40기능. +- 모바일 CRM 15화면(guardia-messenger/app/crm/). MyBatis XML 매퍼 8종. + +### guardia-ocr → WISE AI Platform +- **WISE**(Workplace Intelligence Search Engine)로 리브랜딩된 엔터프라이즈 지식·에이전틱 AI 플랫폼. 모듈: Gateway·Search·Chat·Knowledge·Agent·Studio·Admin·Monitor·Security + 확장 서비스(Contract·Purchase·Settlement·Policy·Meeting·Analytics·Copilot·Developer). +- 원기능(문서 엔진): `/api/ocr/{upload·parse·extract·qa·batch·history·stats}` — Ollama llava/moondream 비전 OCR, 다중 포맷(PDF/PNG/JPG/TIFF/BMP/HEIC/WEBP, 20MB). +- 문서 워크플로우 7종(`/api/workflow/*`): 계약서→계약레코드, 서버납품서→CMDB(ITSM), 청구서→과금, 장애보고서→SR, 회의록→액션아이템 SR, 감사보고서→CSAP 준수율, 브랜드 계약서. +- 민감정보 자동 마스킹(SensitiveDataMasker — 주민번호·카드·전화), 기본 템플릿 7종, 관리자 시스템(RBAC/감사로그/설정) 레퍼런스 구현체(다른 솔루션 admin의 원형 패턴). +- 크롤링 엔진(robots 준수·rate-limit·md5 중복제거)→배치 OCR→DuckDB 학습데이터 파이프라인. 현대백화점 엔터프라이즈 문서 AI(전자문서 파싱 중심·Tika/PyMuPDF·하이브리드 검색·LangGraph·Qwen3)의 기술 계층 호스트. + +### guardia-bi +- 데이터소스(JDBC 연결·자격증명 AES-256-GCM)·데이터셋·대시보드/위젯(7종 차트)·KPI(임계값 상태)·리포트·ETL·데이터 알림. +- AI 분석: 자연어→SQL(읽기전용 가드)·예측·이상탐지·인사이트 — 전 엔드포인트 Java 폴백 내장(Ollama 미가용 시에도 동작). +- ITSM 피드 6종(sr_stats·incident_trend·cmdb_summary·sla·deploy·csap). +- 모듈 경로: `/api/bi/{datasource·dataset·dashboard·widget·kpi·report·etl·alert·analytics·itsm}` + `/api/admin`(사용자/감사/설정). 차트: BAR/LINE/PIE/AREA/GAUGE/KPI/TABLE. + +### guardia-pms +- JIRA 호환 코어(프로젝트·컴포넌트·버전·이슈 키 시퀀스 PROJECT-N·EPIC/STORY/TASK/BUG/SUBTASK·상태전이·코멘트·워크로그·링크·변경이력·Scrum/Kanban 보드·스프린트·번다운/벨로시티/CFD) + 저장 필터. +- 정보화사업(SI) 특화: 행안부 6단계 표준 산출물·감리/준공 체크리스트·RTM(RFP→요구사항 분석서 AI 생성)·WBS 가중 진척률·전자결재·KMS·트리구조 답변형 게시판. +- AI: 이슈 자동분류·자연어→JQL·소스코드 분석→프로그램 명세서 자동 생성·회의록 자동작성(녹음 전사→액션아이템 이슈화)·일/주/월 업무보고서. 16개 기능 모듈(`/api/pms/*` + `/api/admin`). + +### guardia-rpa +- 노코드 워크플로우(JSONB 스텝 정의)·봇(Attended/Unattended)·트리거(스케줄/이벤트/웹훅/큐)·작업 큐·실행 이력·ROI 분석. +- 자산(변수+자격증명 AES-256-GCM 암호화, 응답 미노출). AI: 자연어→워크플로우·실패원인분석·이상탐지. + +### guardia-groupware +- 9모듈(`/api/gw/*`): 전자결재(다단계 결재선·상신/승인/반려·대리결재·history JSONB)·게시판(공지/일반/부서·댓글·상단고정)·일정(개인/공유/부서)·근태(출퇴근 체크·근무시간 산정)/휴가 승인·자원예약(회의실/차량/장비, 시간 중복 방지)·주소록/조직도(조직 트리)·문서함/자료실·쪽지(읽음/안읽음)·통합 대시보드(결재대기·최근글·일정·쪽지). +- AI(`/api/gw/ai`): 문서 요약·결재 자동 분류(양식/긴급도)·문서 초안 (Ollama + 전 기능 Java 폴백). 스키마 접두사 `gw_*`. + +### guardia-portal +- SSO 단일 로그인 통합 포털: 시스템 카탈로그+SSO 런처(sso_token URL), 역할별 위젯(JSONB config), 즐겨찾기, 통합 공지/알림 센터, 페더레이션 검색, 마이페이지. +- SSO는 동일 JWT 시크릿 신뢰 도메인에만 토큰 전달. + +### guardia-mall +- 미국 다지점 꽃집 옴니채널 e-커머스: 매장·ZIP 배송권역·매장별 재고 ON/OFF·3사이즈 상품·타임슬롯 스케줄링·당일배송·구독·서지프라이싱·기사 라우팅·매장간 재고이양·리뷰·CS. +- Redis 보조 캐시 사용(제품군 중 유일하게 명시). +- 결제/세금/주소/SMS/이메일은 외부 게이트웨이 어댑터(기본 mock, 운영 시 Stripe/TaxJar/GoogleMaps/Twilio/SendGrid 전환). +- AI: 상품추천·리뷰요약·자연어검색·수요예측·카드메시지·재고이양추천. 고객 쇼핑앱(app/mall/) + 매장 관리자앱(app/mall-admin/) 2트랙. + +### guardia-cms +- 헤드리스 CMS(Shopping 중심): 페이지/포스트/블록·버전관리·게시 워크플로우(draft→review→approved→published)·예약게시·상품 상세빌더·배너/프로모션·미디어·메뉴/카테고리·다국어/테마·SEO·폼빌더·UGC. +- AI: 콘텐츠 초안·이미지 태깅/대체텍스트·SEO 제안·번역·리뷰 요약/감성·UGC 모더레이션. + +### guardia-mes +- WMS+MES+QMS 통합: 작업지시·생산실적·공정/라우팅·BOM·설비/OEE·LOT추적 + 입출고·재고·로케이션·피킹·실사 + 수입/공정/출하검사·NCR·CAPA·SPC(Cp/Cpk)·성적서. +- AI: 불량원인분석·수요/생산예측·설비 예지보전·SPC 이상감지·재고최적화. 현장 작업자 모바일 앱 포함. + +### guardia-hrm +- 인사관리 독립 솔루션: 근태(attendance)·급여(payroll)·평가(performance)·채용(recruitment)·교육(training)·조직(organization)·직원(employee)·HR 대시보드. +- UIWS 공통모듈(uiws 패키지)·WISE AI(wise 패키지) 이식 완료. 급여/PII는 AES-256-GCM 암호화. +- 참고: UIWS 자체에도 "HRM 내재화" 트랙이 별도로 존재(URP 본부 자체 운영용) — 제품 HRM과 구분. + +### zioinfo-esn / guardia-esn (ESL 전자가격표) +- 레거시 Spring Boot 1.5/Java 8 ESN 프로젝트(ESN_WEB_ZIOINFO·LGInnotek·EMART 데몬 등 6~8종)를 현대화 통합. +- zioinfo-esn(8015) = 1차 통합(12도메인·13페이지), guardia-esn(8016) = 8종 레거시 분석 기반 재통합(13도메인·15페이지·67파일). +- 멀티테넌트(LGINNOTEK/LGIT/EMART/ZIOINFO), 템플릿·POS 변환(PosCvt)·알람·HCore 게이트웨이 관제·펌웨어·업데이트 큐·태그 바인딩. +- guardia-esn 13도메인 테이블: esn_tenants·store_groups·stores·templates·pos_cvt·alarms·hcores·work_history·firmware·users·products·tag_bindings·update_queue. +- AI: 알람 원인분석(GraphRAG 의존성 추적)·POS 데이터 자동 분류. Hikari max 3(공유 PG 보호)·`@MapperScan(annotationClass=Mapper.class)` 필수·SPA static permitAll. + +### guardia-fa +- 공장자동화(Factory Automation): 설비(Equipment)·안돈 이벤트(AndonEvent)·BOM·공정 라우팅(ProcessRoute)·생산지시(ProductionOrder)·공장 재고·e-Paper 디스플레이/템플릿. +- ESN의 e-Paper 기술을 공장 현장 표시에 응용. WISE AI 적용(전면 신규 트랙으로 RagClient 패턴 이식). + +### guardia-mro +- 설비보전(EAM/CMMS): 설비마스터·예방보전(PM)·작업지시(WO)·고장/정비이력·계측교정·신뢰성 지표(MTBF/MTTR/가동률). +- MRO 자재: 자재/BOM·재고·입출고·구매요청/발주·거래처·비용. AI: 고장원인분석·예지보전·자재수요예측. +- GUARDiA 표준 프레임워크(UIMS) 준수 신규 구축 — AI 플랫폼·OTP·DuckDB 학습 패턴 적용. + +### guardia-signage +- 전자간판(e-SignBoard) 중앙관제 — ESN(ESL Smart Network) 응용. e-Paper/플렉서블 간판 패널 원격 콘텐츠 변경. +- HQ 중앙관제↔게이트웨이(Gen1/2/2+)↔간판 태그. 간판 이미지 에디터·템플릿 일괄배포·매장코드별 계정 중앙관리·CSV→zip+md5→REST 30초 폴링·펌웨어 중앙배포·일일 백업/복구·모바일 이미지 전송·광고 스케줄. + +### zioinfo-web +- 회사 홈페이지: 뉴스/채용/연혁/문의/회원 DB 관리(관리자 CMS) + 전 솔루션 소개 페이지(Guardia*Detail, /solution/*). +- 5카테고리 IA(ai/itops/biz/mfg/commerce) 메가메뉴, WISE 배지, 관리자 이미지 관리 전 페이지(page-images API), 선 SVG 아이콘 원칙(이모지 금지). +- 솔루션 포털 페이지 이식 + 통합 메신저 QR 다운로드 페이지 보유. + +### zioinfo-mail +- 자사 Postfix(25/587)/Dovecot(143/993) SMTP 서버 위의 웹메일 클라이언트(3-패널 UI). FastAPI가 IMAP/SMTP 프록시. +- 주소록·서명·폴더 관리 확장. GUARDiA 알림 채널(옥션 통지·EDM·비밀번호 재설정)의 발송 인프라이기도 함. + +### uiws (UIMS) — GUARDiA 표준 프레임워크 정본 +- URP인프라본부 업무관리: worklog(업무일지)·schedule·message·stats·system·incident(장애지원내역)·notice·opinion(의견접수)·titletemplate·search(통합검색)·dashboard·meeting(회의록)·report/weeklyreport(업무보고) 등 58 프로그램·TB_* 테이블 20+. 백엔드 패키지 `com.urp.uiws`. +- **2026-07-03 GUARDiA 표준 프레임워크로 승격** — 스택·JWT+2FA(TOTP)·공통 업무모듈·WISE 디자인 시스템(시안 #11c3ff·Pretendard·선 SVG)·AI 플랫폼 선택형(AiTextRouter)·배포 표준의 단일 출처(`workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md`). +- AI 비서 WISE: Claude tool-use 대화(도구 레지스트리 8종·쓰기 확인 게이트), 인라인 고스트 자동완성, Text-to-SQL(읽기전용 5중 게이트+DataScope), DuckDB 개인 업무 학습, 지출결의서 영수증 OCR→Jasper 전표, 크롤링 학습(URL 화이트리스트), 연속 실시간 STT, 주간보고 AI 초안. +- HRM 내재화(H1~H6): 근태/휴가·평가(MBO/OKR/다면)·급여(온프레미스 4대보험 간이계산)·채용/온보딩·교육·증명서/대시보드 — `com.urp.uiws.hrm` 8모듈·TB_HRM_* 21테이블·PII 12컬럼 AES-256-GCM. +- 기간별 업무보고(일/주/월/분기/연 집계 + Jasper PDF), 행안부 표준 개발자 가이드 산출(govdoc), 원격지원 5W1H 기록 모듈. +- 모바일 UIMS(guardia-messenger app/uiws + 독립 mobile/): 회의녹음→STT→회의록 PDF, 금일 이전 업무일지 조회전용(백엔드 403+UI 이중 방어), QR/바코드·위치 체크인·홈 위젯 네이티브 3종, FCM 푸시. + +### kintex — KINTEX AI 전시·행사시스템 +- KINTEX(한국국제전시장) 전시 운영 자동화: 부스 배치 설계(M2)→부스 설계(M3)→네트워크/전기 배선(M4)→나노바나나(Gemini 이미지 생성) 시공 결과 시각화(M5) 파이프라인 + 도메인 모듈 M10~M18(공사 옥션 역경매·견적서, 관람객 등록/배지/QR/리드/매칭, 경영분석 BI, CMS 공개 홍보 사이트, 관리자 백오피스). +- 스택: React+Vite+TS / Spring Boot 3.x(Java 17) + MyBatis / PostgreSQL+PostGIS(부스 폴리곤·트렌치 포인트·배선 LineString) / Redis 작업 큐 / 나노바나나 Python 워커 사이드카(`tools/nanobanana`, GEMINI_API_KEY env). WISE/UIWS 공통 레이어(2FA·시스템관리) 이식, AI=Claude 기본+설정형 전환(AiTextRouter). +- 6역할 웹/모바일 분리(주최자·참가업체·공사업체·관람객·운영·관리자), Nifty 디자인 토큰(kx-*), 화면은 Google Stitch 경유 원칙. 모바일 2타깃(운영 B2B 2FA + 관람객 B2C 스토어) 단일 코드베이스(mobile/, Expo SDK 51). +- 크롤 기반 관람객 데이터(행사·포스터·교통 DB 적재), 코엑스풍 공개사이트, 행사스코프 데모 폐루프 시드. CI/CD: Gitea webhook → :8021 health 게이트, Flyway 마이그레이션 라이브 dry-run 필수. + +### solution / guardia-docs +- solution: 전 솔루션(15+종) 접속 URL·시연 가이드·모바일 화면을 담은 포털(solution.zioinfo.co.kr). 선 SVG 아이콘 직접 제작 원칙. 이후 zioinfo-web에 이식 완료. +- guardia-docs: 분석설계서·개발자/운영자 지침서·설치 가이드(리눅스/윈도우)·기능별 운영 가이드 40+종 마크다운 저장소. Gitea zio/guardia-docs. + +--- + +## 4. 공통 인프라 + +### 4.1 Gitea (git.zioinfo.co.kr) +- 전 솔루션의 단일 git 원격. 조직/사용자: `zio/*`(대부분 솔루션), `ythong/uiws`(UIWS). +- 로컬 구조: `workspace/` (작업 소스) ↔ `repos/` (push용 독립 저장소) ↔ Gitea ↔ 서버 `/opt/` 4-way 동기화(system-sync 하네스로 검증). +- `.gitignore`의 md 제외 패턴은 제거되어 문서도 push 대상. + +### 4.2 CI/CD Webhook 구조 +``` +Gitea push (main) → webhook → deploy_server.py (:9999, 서버 상주) + → 솔루션별 배포 블록: git pull → (npm build → static 번들) → mvn package/pip + → systemctl restart .service → health 게이트 (포트별 /health 또는 /api 응답) +``` +- Spring Boot 솔루션은 프론트 빌드를 `backend/src/main/resources/static`에 번들 → **단일 jar** 배포. +- Jenkins(:8080)는 보조 파이프라인(Jenkinsfile 각 repo 보유). ITSM 상시 테스트(`scripts/check/run_full_test.py`, 126개)가 배포 후 회귀 게이트. +- 교훈(권위 기록): deploy_server.py 수정 시 서버 사본 반영+재시작 필수, 배포 로그 '완료'여도 1ms면 해당 블록 부재 의심. + +### 4.2-1 서버 서비스 인벤토리 (systemd 단위, 17+ 서비스) + +| 서비스 계열 | 단위 예 | 비고 | +|-------------|---------|------| +| 허브/관제 | guardia-itsm · manager(backend 직접 실행) · zioinfo(홈페이지) | ITSM은 상시 테스트 게이트 대상 | +| Spring 제품군 | guardia-{erp·crm·ocr·bi·pms·rpa·groupware·portal·mall·cms·mes·hrm·fa·mro·signage}.service · guardia-esn · zioinfo-esn | 단일 jar + AI env drop-in(ai-env.conf) | +| AI/배포 인프라 | guardia-rag · zioinfo-deploy(deploy_server.py :9999) · Ollama | rag는 git 체크아웃 기반 자동배포 | +| 기타 | uiws(:8090) · kintex(:8021) · zioinfo-mail | uiws는 dev/prod 이원 운영 | + +### 4.3 AI 플랫폼 (Ollama + Claude + 중앙 rag) +- **Ollama** (localhost:11434, 온프레미스 전용): 서버 RAM 제약으로 소형 모델 표준 — `qwen3:1.7b`(생성)·`deepseek-r1:1.5b`(추론)·`llama3.2:1b`·`moondream`(비전)·`nomic-embed-text`(임베딩). 7B/8B는 RAM 부족으로 금지. +- **Claude API** (api.anthropic.com): 2026-07-03 소유자 승인 유일 외부 예외. 키는 서버 env에서만 로드(DB·코드·커밋·로그 기재 금지), 실패 시 Ollama 자동 폴백(UIWS AiTextRouter 패턴). 전 솔루션 3계층 폴백: Claude → Qwen3 → 소형 Ollama. +- **중앙 guardia-rag** (:8020): 전 솔루션 AI의 관문. 검색(hybrid/graph/rerank)+근거검증+에이전틱+구조화 출력+피드백 학습. 솔루션은 LLM 직접호출 신설 금지, RagClient로 중앙 계약 경유(WISE_APPLY_SPEC). 학습 데이터는 DuckDB. + +### 4.4 보안 불변 규칙 (전 솔루션 공통) +| 규칙 | 내용 | +|------|------| +| 외부 API 금지 | 온프레미스 Ollama만 허용. 유일 예외 = Claude API(env 키, 폴백 필수) | +| 자격증명 보호 | IP·SSH 계정·비밀번호를 API 응답/메신저/에러에 노출 금지. `ItsmSecuritySanitizer`로 ip_addr/ssh_user/os_pw_enc 제거 | +| 암호화 | 자격증명·PII 컬럼 AES-256-GCM (`CryptoUtil`, os_pw_enc 등) | +| root 금지 | 관리 대상(테넌트) 서버 root SSH 금지 — opsagent 계정. 자체 인프라 서버만 예외(소유자 승인) | +| 에러 응답 | 스택트레이스 미노출 — 에러 코드+요약만 (`GlobalExceptionHandler` / DataAccessException 핸들러) | +| 인증 표준 | JWT+RBAC + TOTP 2FA, admin 비밀번호는 고정 시드 제거 후 env 암호화 주입(ADMIN_PASSWORD_ENC + 별도 키파일) | + +### 4.4-1 GUARDiA 표준 프레임워크 구성요소 (UIMS 정본, `workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md`) + +| 구성요소 | 표준 내용 | +|----------|-----------| +| 스택 | React 18/19+TS+Vite+Tailwind / Spring Boot 3.5 Java 17 (FastAPI 예외: ITSM·Manager·rag) / PostgreSQL+MyBatis / 단일 jar | +| 인증 | JWT+RBAC + TOTP 2차 인증(RFC6238) + 로그인 실패 잠금 + admin 비번 env 암호화 재시드 | +| 공통 업무모듈 | worklog·schedule·message·stats·system·notice·opinion·search·meeting·report·notification·audit (uiws-port 이식) | +| 디자인 | WISE 디자인 시스템 — 시안 #11c3ff·블루 #1f29fc·Pretendard·카드형·선 SVG 아이콘, guardia-chief-designer 고정 리드 | +| AI | 플랫폼 선택형(Claude·Qwen3·DeepSeek·Ollama) `AiTextRouter` 폴백 + DuckDB 학습 분석 | +| 보안 | 외부 API 금지(Claude 예외)·자격증명 미노출·AES-256-GCM·감사로그 | +| 배포 | workspace→repos fresh init→Gitea→webhook→systemd, AI env drop-in, 직렬 빌드 | + +### 4.5 표준 개발 컨벤션 (Spring Boot 솔루션군) +- `@MapperScan(annotationClass = Mapper.class)` — basePackages만 쓰면 빈 누락 크래시(OCR에서 규명). +- schema.sql `IF NOT EXISTS` + `sql.init mode=always` + continue-on-error + 시드 멱등화 — 후행 테이블 추가 시 "relation does not exist" 방지(schema-integrity 패턴). +- Hikari `maximum-pool-size=3` (공유 PostgreSQL 인스턴스 보호), JSONB는 String + `#{f}::jsonb`, map-underscore-to-camel-case ON. +- 디자인: WISE 디자인 시스템(시안 #11c3ff·블루 #1f29fc·Pretendard·카드·선 SVG 아이콘) — `guardia-chief-designer` 리드. 공개 페이지 이모지 금지. +- 모바일: guardia-messenger 통합 런처 편입 + ITSM 중앙 APK 저장소 QR 배포(업로드는 Manager 일원화). + +### 4.6 도메인 맵 +| 도메인 | 용도 | +|--------|------| +| zioinfo.co.kr | 홈페이지(:8082)·ITSM(:8443)·개발 서버 루트 | +| git.zioinfo.co.kr | Gitea | +| mail.zioinfo.co.kr | 웹메일/SMTP | +| solution.zioinfo.co.kr | 솔루션 포털 | +| kintex.zioinfo.co.kr | KINTEX 개발(:8021) | +| wise.ai.kr | UIWS/WISE 운영 | + +--- + +## 5. 연동 매트릭스 + +각 솔루션이 어떤 공통 축과 연결되는지 요약 (●=핵심 연동, ○=부분/브랜딩 수준). + +| 솔루션 | ITSM API | 중앙 rag (WISE AI) | Messenger 모바일 화면 | zioinfo-web 소개 페이지 | Gitea CI/CD | +|--------|:--------:|:------------------:|:---------------------:|:-----------------------:|:-----------:| +| itsm | (허브) | ● (rag_enabled 토글) | ● (기본 탭 6 + 300기능) | ● /solution/itsm | ● | +| manager | ● (JWT 재사용) | ● (전면 신규 적용) | ○ (QR 배포 연계) | ○ | ● (프론트+백엔드 rsync) | +| erp | ● (30+ 라우터) | ● (질의화면 승격) | ● app/erp 계열 | ● | ● | +| crm | ● (8모듈 통합) | ● (부분 보강) | ● app/crm (15화면) | ● | ● | +| ocr(WISE) | ● (SR·CMDB·CSAP) | ● (기술계층 호스트) | ● app/ocr (6화면+) | ● /solution/ocr·wise | ● | +| bi | ● (피드 6종) | ○ (브랜딩) | ● app/bi (6화면) | ● | ● | +| pms | ● (SR↔이슈) | ● (질의화면 승격) | ● 모바일앱 | ● | ● | +| rpa | ● (SR 자동화) | ○ (브랜딩) | ● 모바일앱 | ● | ● | +| groupware | ● | ○ (브랜딩) | ● app/groupware (5화면) | ● | ● | +| portal | ● | ○ (브랜딩) | ● app/portal (4화면) | ● | ● | +| mall | ● | ● (부분 보강) | ● app/mall + app/mall-admin | ● | ● | +| cms | ● (BI/Mall 연계) | ● (질의화면 승격) | ● 모바일앱 | ● | ● | +| mes | ● (ERP 연계) | ● (부분 보강) | ● 현장 작업자 앱 | ● | ● | +| hrm | ● | ● (전면 신규) | ● app/hrm-* (7화면) | ● | ● | +| esn / zioinfo-esn | ● | ● (부분/전면) | ○ | ● /solution/esn | ● | +| fa | ● | ● (전면 신규) | ○ | ● | ● | +| mro | ● | ● (전면 신규) | ○ | ● | ● | +| signage | ● | ● (부분 보강) | ○ (모바일 이미지 전송) | ● | ● | +| uiws | ○ (동일 PG 인스턴스) | ● (AI 비서 WISE 원형) | ● app/uiws (9화면+) + 독립 mobile/ | — | ● (ythong/uiws) | +| kintex | ○ (표준 프레임워크 준수) | ● (Claude+설정형 AiTextRouter) | ● 독립 mobile/ (2타깃) | — | ● (webhook #47) | +| zioinfo-web | ○ (문의만) | — | ○ (QR 페이지) | (자신) | ● | +| zioinfo-mail | ○ (알림 발송 인프라) | — | — | ○ | ● | + +**2026-07-04 "WISE 전 솔루션 적용"** 결과 유형: 브랜딩만(bi·rpa·groupware·portal) / 질의화면 승격(cms·pms·erp) / 부분 보강(itsm·mes·signage·esn·mall·crm) / 전면 신규(manager·mro·hrm·zioinfo-esn·fa). 18종 전부 배포·health 게이트 통과. + +--- + +## 6. 하네스(에이전트 오케스트레이션) 생태계 요약 + +루트 `.claude/`에 등록된 오케스트레이터 스킬이 솔루션별 에이전트 팀을 지휘한다. 대표 매핑: + +| 영역 | 대표 오케스트레이터 | 담당 | +|------|--------------------|------| +| ITSM 운영 | guardia-orchestrator | SR·배포·코드리뷰·SLA·인시던트·RCA | +| 풀스택 통합 | guardia-fullstack-orchestrator | 4개 시스템 크로스 기능·API 계약·통합 QA | +| 개발 자동화 | guardia-dev-orchestrator | 자연어 요구→코드생성→리뷰→테스트→push (6프로젝트) | +| 솔루션별 | guardia-{crm·ocr·bi·pms·rpa·groupware·portal·mall·cms·mes·signage·esn}-orchestrator | 각 제품 기능 개발·배포 | +| AI 인프라 | guardia-rag-orchestrator / guardia-ai-trust-orchestrator / guardia-ai-technique-orchestrator / guardia-claude-ai-orchestrator | 검색 인프라 / 환각방지 / 최신기법(GraphRAG·rerank) / Claude 전환·OTP·학습 | +| 운영 점검 | system-sync / guardia-ops-check / schema-integrity / ollama-health / test-orchestrator | 4-way 동기화·기동·스키마 누락·Ollama 진단·상시 테스트 | +| 모바일 | mobile-build / mobile-unify / messenger-mega·mega2 / uiws-mobile / kintex-mobile | 빌드·QR 배포·통합 런처·기능 구현 | +| 문서/브랜드 | solution-doc / gitea-md-publish / wise-ai-platform / homepage-unified-renewal | PPT 산출물·md 게시·WISE 리브랜딩·홈페이지 | +| UIWS | uiws-orchestrator + uiws-port(전 솔루션 이식) + uiws-hrm·uiws-ai-assistant 등 | 표준 프레임워크 개발·전파 | +| KINTEX | kintex-impl / kintex-benchmark / kintex-renewal / kintex-wise-ui / kintex-mobile | 전시시스템 구현·크롤·리뉴얼·UI 정렬 | + +각 솔루션 폴더에도 자체 `.claude/`(솔루션 로컬 오케스트레이터 + `-{backend,frontend,db,qa,devops}-dev` + 도메인 AI 에이전트 4종 `-ai-*`)가 표준 설치되어 있다(solution-harness 메타 하네스). 디자인성 작업은 `guardia-chief-designer`가 고정 리드. + +--- + +## 7. 주요 이력 하이라이트 (타임라인) + +| 시기 | 사건 | +|------|------| +| 2026-05 | ITSM 30개 고도화 완료, Manager·Messenger·웹메일 구축, workspace 통합·repo 분리(Gitea 전용), UI 전면 개편 | +| 2026-06 초 | 확장 세대 1~6(디지털트윈·AIOps·ZTNA·IDP·GreenOps 등) — ITSM ~1,400 엔드포인트, Messenger 300기능, CI/CD 파이프라인 | +| 2026-06 중 | 제품군 대량 신설: ERP→CRM→OCR→BI→PMS→RPA→Groupware→Portal→Mall→CMS→MES→ESN(8003~8016 순차 포트 할당), 솔루션 포털 | +| 2026-06 말 | UIWS 하네스 루트 등록·전 솔루션 이식 트랙, RAG·AI 신뢰·최신 AI 기법 도입, 모바일 통합 런처 | +| 2026-07-03 | **UIMS → GUARDiA 표준 프레임워크 승격**, Claude API 승인(외부 API 유일 예외), MRO(8018)·Signage(8019) 신설, Qwen3/DeepSeek 소형모델 채택 | +| 2026-07-04 | **WISE AI Platform 리브랜딩(OCR)** + 전 솔루션 WISE AI 적용(18종), guardia-rag 자동배포 완성, 홈페이지 통합 리뉴얼 | +| 2026-07-11~12 | KINTEX AI 전시·행사시스템(8021) 구축 가속 — PLANNING v2.0/v3.4, Nifty 디자인 정렬, 모바일 2타깃, 크롤 기반 관람객 데이터 | + +--- + +## 부록: 이 문서의 갱신 규칙 + +- 신규 솔루션 추가 시: §2 표(포트·DB·패키지) + §3 상세 + §5 매트릭스에 행 추가. 포트는 8022부터 순차 할당 관례. +- 권위 소스 우선순위: 루트 `C:\GUARDiA\CLAUDE.md` > 솔루션 `CLAUDE.md` > `application.yml` 실측. +- 금지: 비밀번호·API 키·토큰·SSH 자격증명·서버 IP 기재. 접속 정보는 도메인+포트까지만. diff --git a/plugins/zio-harness/knowledge/guardia/standard-framework.md b/plugins/zio-harness/knowledge/guardia/standard-framework.md new file mode 100644 index 0000000..bd2978e --- /dev/null +++ b/plugins/zio-harness/knowledge/guardia/standard-framework.md @@ -0,0 +1,377 @@ +# GUARDiA 표준 프레임워크 (UIMS 기준) — 지식 문서 + +> **선언(2026-07-03):** UIMS(UIWS, `workspace/uiws`)가 **GUARDiA 표준 프레임워크**로 승격되었다. +> 모든 신규 프로젝트와 기존 솔루션은 이 표준을 기준으로 개발·리팩터링한다. +> +> - **표준 명세 단일 출처:** `workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md` +> - **정본 레퍼런스 구현:** `workspace/uiws` (읽기 전용 — 임의 수정 금지) +> - **AI 플랫폼 공통 계약:** `workspace/_ai_track/AI_PLATFORM_SPEC.md` +> - **WISE AI 적용 명세:** `workspace/_framework/WISE_APPLY_SPEC.md` +> +> 이 문서는 위 소스들을 하네스 지식용으로 통합 요약한 것이다. 충돌 시 단일 출처 문서가 우선한다. + +--- + +## 1. 표준 기술 스택 + +| 레이어 | 표준 | 비고 | +|--------|------|------| +| 프론트(웹) | **React 18/19 + TypeScript + Vite + Tailwind** | `pages/components/api/store/hooks/routes` 구조 | +| 프론트(모바일) | **React Native + Expo (expo-router)** | `guardia-messenger/app//` 통합 런처에 편입 | +| 백엔드 | **Spring Boot 3.5 / Java 17** | controller·service·repository·domain·dto 계층 | +| 백엔드 예외 | FastAPI (Python) | ITSM · Manager · guardia-rag 3개만 허용 | +| ORM | **MyBatis** (`@MapperScan(annotationClass=Mapper.class)`) 또는 JPA | 솔루션 내 일관성 유지 | +| DB | **PostgreSQL** — `_db` / `_user` | 공유 인스턴스 + 솔루션별 분리 계정, Hikari `maximum-pool-size: 3` | +| 리포트 | JasperReports (PDF) | 공통 | +| 패키징 | **단일 jar** | 프론트 빌드 → 백엔드 static 번들 → 하나의 jar로 배포 | + +### 스택 관련 규칙 +- 프론트 axios baseURL은 `/api` — nginx가 `/` → SPA 정적 파일, `/api/` → 백엔드 포트로 프록시하므로 별도 CORS 불필요. +- 모든 API 응답은 봉투(envelope) 형식: `ApiResponse = { success, data, message }`, 목록은 `PageResponse`. + - 클라이언트(웹·모바일)는 봉투 언랩(unwrap) 유틸을 공통화한다 — 모바일 이식 시 `PageResponse` 봉투 언랩 누락이 실제 경계면 버그 사례. +- DB 스키마의 단일 진실원천은 마이그레이션 DDL (Hibernate 사용 시 `ddl-auto: validate`). +- 신규 솔루션 명명: DB `_db`/`_user`, 패키지 `com.zioinfo.`, 포트는 솔루션별 고정 할당. +- 시크릿·접속정보는 전부 환경변수/프로퍼티 주입 — 하드코딩 금지. (UIMS 예: `UIWS_DB_PASSWORD` 필수, `UIWS_JWT_SECRET` 32바이트 이상 권장 — 미설정 기본값은 개발 전용, 운영 금지.) +- 메일 발송은 모드 스위치 표준: `MAIL_MODE=log`(기본, 로컬 로그 출력) / `smtp`(실발송, SMTP 접속정보 env 주입). 개발 환경에서 실발송 사고를 구조적으로 차단한다. +- 원격 DB 개발 접속은 SSH 로컬 포워딩 터널 경유(DB 포트 외부 비개방 전제). + +### UIMS(정본) 백엔드 패키지 구조 (레퍼런스) +``` +com.urp.uiws +├── config : SecurityConfig, JwtProperties, AuthProperties +├── security : JwtTokenProvider, JwtAuthenticationFilter, UserPrincipal, RestAuthEntryPoint, TokenType +├── common : response(ApiResponse·PageResponse), exception(ApiException·ErrorCode·GlobalExceptionHandler), mail(MailSender) +├── domain : User, LoginVerify, Dept, Role, Menu, RoleMenu, DeptRole (BaseEntity) +└── auth : controller / service(AuthService·TotpService) / repository / dto +``` + +--- + +## 2. 표준 인증 (JWT + RBAC + 2FA/OTP) + +### 2.1 JWT + RBAC +- JWT 발급(access·refresh) + 역할 기반 접근 제어. +- 역할 게이트 표준: `/api/admin/** = hasRole(ADMIN)`. +- 사용자 조회 `/api/auth/me`는 사용자 정보 + **메뉴 권한 트리**를 함께 반환(메뉴 노출 게이트). + +### 2.2 2차 인증 (2FA) +- **OTP(TOTP)**: RFC 6238 — SHA1 · 30초 주기 · 6자리 · ±1 윈도우 허용. UIMS `TotpService`를 이식한다. +- 로그인은 **2단계**: ① ID/PW → `verifyToken` 발급 → ② OTP(또는 이메일 코드) 검증 → access·refresh 발급. +- 검증 방식은 사용자별 `VERIFY_METHOD`(`EMAIL`/`OTP`)로 분기 — `EMAIL`은 6자리 코드 메일 발송, `OTP`는 TOTP 검증(발송 없음). 단일 `/verify-otp` 엔드포인트가 두 방식 모두 처리. +- 최초 로그인 시 QR 등록, 마이페이지에서 재설정/해제, **관리자에 의한 OTP 초기화**(`otp_secret = NULL`) 지원. +- 기존 솔루션 이식 시 테이블에 `otp_secret`·`otp_enabled` 컬럼을 **멱등 ALTER**로 추가. + +### 2.3 로그인 실패 잠금 +- 연속 로그인 실패 시 계정 잠금 + 관리자 해제 기능. + +### 2.4 admin 비밀번호 (env 암호화 주입 — 값 절대 미기재) +- 하드코딩 시드(예: 고정 초기 비밀번호) **금지**. +- 표준 방식: env `ADMIN_PASSWORD_ENC`(AES-256-GCM 암호문) + `ADMIN_KEY_FILE`(별도 키파일, root 전용 권한 600)을 기동 시 복호 → **BCrypt로 재시드**. +- 마스터 키·암호문 파일은 서버 시크릿 디렉터리에만 존재하며 코드·커밋·문서에 값을 기재하지 않는다. +- 서비스별 env 파일(`guardia-ai.env`: `ANTHROPIC_API_KEY` + `ADMIN_PASSWORD_ENC` + `ADMIN_KEY_FILE`)을 systemd **drop-in**(`ai-env.conf`, `EnvironmentFile` 추가)으로 주입한다 — Java 서비스 대부분이 명령줄 인자 기동이므로 drop-in이 표준. + +### 2.4a 기존 솔루션 인증 이식 원칙 +- 기존 auth 모듈이 있는 솔루션: **교체 금지** — 2FA(OTP)만 레이어로 추가한다. +- auth가 없는 솔루션: UIMS auth 전체 이식(JWT+2FA+잠금). +- 전환 트랙 표준 절차: ① `otp_secret`·`otp_enabled` 멱등 ALTER → ② `TotpService` 이식 → ③ 로그인 2단계 배선 → ④ 전 사용자 OTP 초기화(`otp_secret=NULL`) 1회 → ⑤ QR 등록/마이페이지 재설정/관리자 초기화 화면. +- admin 재시드 전환 시 하드코딩 시드는 제거하고 env 암호문 복호 → BCrypt 재시드로 대체(값은 서버 시크릿에만 존재). + +### 2.5 인증 API 표준 (Base: `/api/auth`) +| 메서드 | 경로 | 설명 | +|--------|------|------| +| POST | `/login` | 1차 로그인(ID/PW) → verifyToken | +| POST | `/verify-otp` | 2차 검증(이메일 코드/OTP) → access·refresh | +| POST | `/refresh` | 토큰 재발급 | +| POST | `/logout` | 로그아웃 | +| POST | `/signup` | 회원가입(승인 대기) | +| POST | `/find-id` | 아이디 찾기(마스킹 반환) | +| POST | `/reset-password` | 임시 비밀번호 메일 발송 | +| GET | `/me` | 사용자 + 메뉴권한 트리 | + +--- + +## 3. 표준 공통 업무 모듈 12종 (UIMS 업무협업 레이어) + +신규 솔루션은 필요 모듈을 `uiws-port-orchestrator`로 이식한다. 기존 auth가 있는 솔루션에는 **교체가 아니라 2FA 레이어만 추가**한다. + +| 모듈 | 이름 | 역할 | +|------|------|------| +| 1. worklog | 업무일지 | 일 단위 업무 기록·상세(시간대별)·진행상태·이슈 기록. 조회 권한은 DataScope(부서/작성자) 기반. 금일 이전 일지는 조회 전용 정책 가능 | +| 2. schedule | 일정 | 개인/부서 일정 등록·캘린더 뷰(월/주)·공유 일정 관리 | +| 3. message | 쪽지 | 사내 사용자 간 쪽지 발신/수신함·읽음 처리 | +| 4. stats | 통계 | 업무일지·일정 데이터 집계(근무현황 피벗 등) 통계 화면 | +| 5. system | 시스템관리 | 사용자·부서·역할/권한(RBAC)·메뉴·공통코드 관리 등 관리자 백오피스 | +| 6. notice | 공지 | 전사/부서 공지사항 게시·조회 | +| 7. opinion | 의견접수 | 사용자 의견·건의 접수 및 관리자 처리 | +| 8. search | 통합검색 | 업무일지·공지·일정 등 모듈 횡단 통합 검색 | +| 9. meeting | 회의록 | 회의 기록·(음성 STT→회의록 자동작성 확장)·액션아이템·Jasper PDF 출력 | +| 10. report | 업무보고 | 일일/주간/월간/분기/연간 기간별 업무현황 집계(`/api/reports/work-status`) + Jasper PDF 다운로드. 기간 산출은 서버 권위(WEEKLY=ISO 월~일, QUARTERLY=역년 분기) | +| 11. notification | 알림센터 | 시스템 이벤트·승인·쪽지 등 통합 알림 수신함 | +| 12. audit | 감사로그 | 주요 행위(로그인·데이터 변경·관리자 조작) 감사 기록(TB_AUDIT_LOG) | + +> 표준 명세에는 위 12종 외에 **dashboard(대시보드)·preference(개인화)·adminCode(공통코드)** 도 공통 레이어로 열거되어 있다(system과 함께 관리 영역 구성). + +### 3.1 모듈별 상세 규약 (UIMS 정본 기준) + +**worklog (업무일지)** +- 마스터/디테일 구조: `TB_WORKLOG`(일자·작성자·진행상태) + `TB_WORKLOG_DTL`(시간대별 상세 — 시작/종료 시각, 업무유형 코드, 이슈 내용). +- 조회 권한은 DataScope 3단계: ADMIN(전체) / MANAGER(부서+하위) / USER(본인). 모든 목록·집계 API에 필수 적용. +- 과거 일지 조회 전용 정책 적용 시: **저장된 workDate 기준**으로 백엔드 403(우회 차단) + UI 차단 이중 방어. 조회(GET)·신규 생성·댓글은 예외. + +**meeting (회의록)** +- `TB_MEETING` + `TB_MEETING_ACTION`(액션아이템). 확장 시 오디오 업로드 → STT → 회의록 자동작성 파이프라인(AI degraded 폴백 포함, 오디오는 STT 후 폐기). +- 회의록 PDF는 JasperReports(`meeting_minutes.jrxml`) 렌더. + +**report (업무보고)** +- 계약: `GET /api/reports/work-status?period=DAILY|WEEKLY|MONTHLY|QUARTERLY|YEARLY&baseDate&deptId&writerId` → `WorkReportDto(summary·byWriter·byType·byDay)`. +- PDF: `GET /api/reports/work-status/pdf`(동일 파라미터, `application/pdf`) — 공용 jrxml 1종으로 5기간 렌더. +- **기간 산출은 서버 권위**: WEEKLY = ISO 월~일, QUARTERLY = 역년 분기. DataScope 권한 필수. + +**system (시스템관리)** +- 사용자·부서(`TB_DEPT`)·역할(`TB_ROLE`)·메뉴(`TB_MENU`·`TB_ROLE_MENU`)·공통코드 관리. 메뉴 권한 트리는 로그인 응답(`/me`)으로 내려가 프론트 메뉴 노출을 게이트한다. +- 회원가입은 승인 대기(`APPROVAL_YN='N'`) → 관리자 승인 흐름. + +**audit (감사로그)** +- 로그인·데이터 변경·관리자 조작을 `TB_AUDIT_LOG`에 기록. 관리자 화면에서 조회. 감사로그 자체에 자격증명·PII 원문 미기록(마스킹). + +### 3.2 데이터 관례 +- 테이블 접두어 `TB_*` (UIMS 관례: `TB_USER`, `TB_WORKLOG`, `TB_MEETING`, `TB_LOGIN_VERIFY`, `TB_AUDIT_LOG` 등). +- 모든 시드·DDL은 **멱등**(유니크 인덱스 + on conflict / IF NOT EXISTS / 멱등 ALTER)으로 작성 — 재실행 안전. +- 후행 스키마 확장 시 `sql.init mode=never`면 재적용되지 않아 런타임 `relation does not exist` 500이 난다 → `mode=always` + `continue-on-error` + 시드 멱등화가 표준 패턴. +- 메뉴 신설 시 메뉴 시드까지 함께 커밋(화면은 있는데 메뉴에 없는 누락 방지). + +--- + +## 4. WISE 디자인 시스템 + +### 4.1 브랜드 토큰 +| 토큰 | 값 | 용도 | +|------|-----|------| +| 시안(Cyan) | `#11c3ff` | 브랜드 포인트 | +| 블루(Blue) | `#1f29fc` | 주 액션·강조 | +| 잉크(Ink) | `#252525` | 본문 텍스트 | +| 그레이(Gray) | `#3f3f3f` | 보조 텍스트 | + +### 4.2 원칙 +- **서체: Pretendard** 전면 적용. +- **카드 중심 레이아웃** + 라이트/다크 테마 토글 지원. +- **선(stroke) SVG 아이콘 직접 제작**: `fill:none`, `stroke:currentColor`. **외부 아이콘 라이브러리 금지**(이모지 아이콘도 공개 화면에서 배제). +- 색상 버튼/배지 위 텍스트는 다크 모드 대응 토큰(`--color-on-accent` 패턴)으로 흰 글자 보장. +- **디자인 수석 `guardia-chief-designer`가 전 UI 작업의 고정 리드** — 화면 방향 확정 → 구현 → 검수 순서. + +### 4.3 WISE AI 브랜딩 (전 솔루션 적용 표준) +- AI 메뉴명은 **"WISE AI"** + 부제 "Enterprise AI for Trusted Knowledge" (WISE = Workplace Intelligence Search Engine). 기존 AI 메뉴가 있으면 개명하며 중복 메뉴 신설 금지. +- AI 질의 화면 표준 구성: 질문 입력 → 답변(plain text) → **인용(sources) 카드 리스트**(문서명·위치, 없으면 "근거 문서 없음" 표기) → abstain/degraded 배지 → 👍/👎 피드백(기존 피드백 API 있을 때 연결). +- 환각차단 UX: `abstained=true` → 경고 톤 배지("근거가 부족해 답변을 보류했습니다" — 오류 아님 안내), `degraded` → 회색 배지(사유 코드). + +### 4.4 WISE AI 적용 판정 매트릭스 (A~F — WISE_APPLY_SPEC) +솔루션에 WISE AI를 적용할 때는 아래 6개 항목을 감사해 미충족분만 보강한다(기존 재구현 금지). + +| 항목 | 표준 | +|---|---| +| A. rag 클라이언트 | 백엔드 RagClient(기존 것 재사용 우선) — `/rag/answer` 프록시 엔드포인트 `POST /api/wise/ask` | +| B. AI 질의 화면 | 관리자 웹에 "WISE AI" 메뉴/페이지 1개 — 질문 입력 → 스피너 → 답변 | +| C. 인용 UX | 답변 하단 `sources[]` 카드(문서명·위치) | +| D. 환각차단 UX | abstain 경고 배지 / degraded 회색 배지 | +| E. 브랜딩 | 메뉴명 "WISE AI" + 부제, 기존 AI 메뉴 개명 | +| F. AI 설정 | 기존 AiConfig 화면 있으면 유지(없으면 별도 트랙) | + +**완료 정의(솔루션당):** A~E 충족(F는 기존 있을 때만) · 백엔드/프론트 빌드 통과 · 라이브 `/api/wise/ask` 200(답변 또는 abstain) · 화면 진입 확인 · 기존 화면 회귀 0(라우트 충돌 0). + +--- + +## 5. 표준 AI 플랫폼 (온프레미스 우선 + Claude) + +### 5.1 프로바이더 패밀리 (설정 화면 선택형 — UIMS AiConfigPage 미러) +| 패밀리 | 성격 | 경로 | +|--------|------|------| +| **Claude** | 프리미엄(외부, 소유자 승인 단일 예외) | Anthropic Messages API — 키는 env `ANTHROPIC_API_KEY`에서만 로드 | +| **Qwen** | 최고성능 오픈소스(범용, 기본 `qwen3:1.7b`) | Ollama 온프레미스 | +| **DeepSeek** | 오픈소스(추론 특화, `deepseek-r1:1.5b`) | Ollama 온프레미스 | +| **GLM (Zhipu)** | 오픈소스(범용, 9B — RAM 제약으로 서버 기동 보류) | Ollama 온프레미스 | +| **Ollama 소형** | 최종 폴백 (`llama3.2:1b`, 비전 `moondream`) | Ollama 온프레미스 | + +- GLM/Qwen/DeepSeek은 **Ollama 온프레미스로만** 사용 — 각사의 클라우드 API(Zhipu/DashScope/DeepSeek 클라우드) 호출 금지. + +**모델 화이트리스트 (임의 문자열 거부):** +``` +provider ∈ { claude, qwen, deepseek, glm, ollama } +claude ∈ { claude-sonnet-4-6 (기본), claude-haiku-4-5, claude-opus-4-8 } +qwen ∈ { qwen3:1.7b (기본), qwen3:0.6b, qwen3:4b* } +deepseek ∈ { deepseek-r1:1.5b (기본), deepseek-r1:7b* } +glm ∈ { glm4:9b* } +ollama ∈ { llama3.2:1b (기본), moondream(vision) } +``` +- `*` = RAM 초과 가능 — 설정 화면에 "RAM 여유 필요" 배지 표시, 선택은 허용하되 콜드로드 실패 시 폴백. +- GLM RAM 정책: 대형 모델이 서버 가용 RAM을 초과하면 화이트리스트 등록(선택 가능)은 유지하되 서버 pull/기동은 RAM 증설 전까지 보류 — 설정 화면에 "RAM 증설 필요" 경고를 **명시**한다(조용한 드롭 금지). + +### 5.2 AiTextRouter — 3계층 추론 폴백 체인 +``` +선택 provider 1차 시도 → 실패(degraded) 시: + claude → qwen(qwen3:1.7b) → ollama(llama3.2:1b) → degraded:true + qwen/deepseek/glm → 해당 Ollama 모델 → llama3.2:1b → degraded:true +``` +- Claude 실패는 예외(장애)로 취급하지 않는다 — degraded 표시 후 다음 단계 폴백(**서비스 중단 금지**). +- 동시 모델 로드 금지(서버 RAM 제약), 콜드로드 타임아웃 240s 이상 감안. +- 구현 레퍼런스: UIMS `common/ai/ClaudeTextClient` · `system/ai(AiTextRouter·AiConfigService)` · `AiConfigPage.tsx`. + +### 5.3 중앙 RAG 서비스 (guardia-rag) 계약 +- 아키텍처 결정: LangChain은 Python, 대부분 솔루션은 Java → **중앙 Python RAG 서비스 1개 + 각 솔루션의 얇은 REST 클라이언트**. 솔루션별 컬렉션 격리(`rag_`). +- 스택: LangChain + ChromaDB + Ollama 임베딩(`nomic-embed-text`). 엔터프라이즈 목표 스택(Milvus·vLLM·BGE-M3 등)은 어댑터로 정렬하되 개발 서버에서는 경량 폴백만 실행. + +**중앙 계약 엔드포인트** (변경 금지 — 소비만): +| 엔드포인트 | 역할 | +|-----------|------| +| `POST /rag/answer` | 근거 기반 답변. 요청 `{solution, query, retrieval_mode?}` → 응답 `answer, sources[], grounded, faithfulness, abstained, degraded/degraded_reason, trace_id` | +| `POST /rag/verify` (`/verify`) | 근거검증(grounding/faithfulness)·팩트체크 | +| `POST /rag/agent` (`/agent`) | 에이전틱 tool-use 실행 | +| `POST /rag/structured` (`/structured`) | 구조화 출력(JSON) 생성 | +| `POST /rag/feedback` (`/feedback`) | 👍/👎 + 교정 피드백 수집(학습 루프) | +| `POST /rag/chat` (`/chat`) | 멀티턴 RAG 대화(메신저 어시스턴트용) | + +**검색·응답 옵션:** +- `retrieval_mode`: `vector`(기본 벡터) | `hybrid`(BM25+Dense 하이브리드) | `graph`(GraphRAG — 문서 지식그래프) 선택형. 리랭킹은 중앙 서비스가 수행. +- 응답의 `grounded`/`faithfulness`는 근거검증 점수, `abstained`는 근거 미달 시 답변 보류(환각 차단), `trace_id`는 추적용. +- 생성/비전 모델 콜드로드는 서버 RAM을 위협 — 소형 모델 기본, 비전 자동 로드 금지, 동시성 제한, 실패 시 검색만 수행하는 `degraded:true` 폴백. + +**솔루션 측 소비 패턴:** +- 브라우저는 rag를 직접 호출하지 않는다 — **솔루션 백엔드가 프록시**: `POST /api/wise/ask {query}` → rag `/rag/answer` 호출(기존 JWT 필터 뒤, 로그인 사용자만). +- 솔루션에서 **LLM/Ollama 직접 호출 신설 금지** — 전부 중앙 rag 경유(서버 RAM 보호). +- rag 호출 실패는 "AI 서비스 일시 불가" 요약 메시지(스택트레이스 미노출), 타임아웃 240s. + +### 5.4 AI 학습 (피드백 루프 + DuckDB) +- 각 솔루션은 로컬 임베디드 **DuckDB**(`_learning.duckdb`)를 AI 피드백·학습 데이터셋·분석 저장소로 사용 (Java: `org.duckdb:duckdb_jdbc`, Python: `duckdb`). +- 표준 스키마(멱등): `ai_feedback(id, ts, solution, feature, question, answer, verdict, correction, user_masked)` · `ai_infer_log(id, ts, provider, model, latency_ms, degraded)`. +- 피드백 UI는 **로컬 DuckDB 기록 + 중앙 guardia-rag `/feedback` 전달 둘 다** 수행 — 중앙은 통합 학습·평가 게이트, 로컬은 솔루션별 분석/오프라인. +- 학습 파이프라인: 피드백 → 데이터셋 → LoRA 오프서버 학습 → 평가 게이트 → 모델 반영. +- PII·자격증명은 수집 시 마스킹, 솔루션별 파일 격리. + +--- + +## 6. 표준 보안 (불변 규칙) + +| 규칙 | 내용 | +|------|------| +| **외부 API 금지** | 온프레미스(Ollama)만 허용. **단일 예외:** Anthropic Claude API(`api.anthropic.com`, 소유자 승인) — 키는 서버 env에서만 로드, DB·코드·커밋·로그·응답 기록 금지, 실패 시 Ollama 자동 폴백. 그 외 외부 API 전면 금지 | +| **자격증명 미노출** | 비밀번호·SSH 계정·내부 IP·API 키·OTP 시크릿은 env 또는 DB(해시/암호화)에만 존재. API 응답·에러 메시지·로그·커밋에 절대 노출 금지 | +| **암호화 저장** | 민감 자격증명은 **AES-256-GCM** 암호화 저장(예: 서버 접속 비밀번호 컬럼, admin 비번 env 암호문). 사용자 비밀번호는 BCrypt 해시 | +| **스택트레이스 차단** | 에러 응답은 요약 메시지만 반환. `DataAccessException` 등 전역 예외 핸들러로 내부 정보 누출 차단 | +| **감사 추적** | 주요 명령·변경은 감사로그(TB_AUDIT_LOG)에 기록 | +| **응답 스키마 필터** | 서버 자산 API 응답에서 IP·SSH 계정·암호화 비번 컬럼 완전 제외 | +| **시드 안전성** | `sql.init mode=always` + `continue-on-error` + 시드 멱등화(유니크 인덱스) — 후행 스키마 확장에 의한 누락 테이블 500 방지 | +| **최소 권한** | 관리 대상(테넌트) 서버에 root SSH 직접 접속 금지 — 관제 전용 일반 계정 사용(자체 인프라 서버만 소유자 승인 예외) | + +--- + +## 7. 표준 배포 + +### 7.1 파이프라인 흐름 +``` +workspace/ (개발 소스) + → repos/ (fresh git init 독립 저장소) + → Gitea push (git.zioinfo.co.kr/zio/) + → Gitea webhook (push 이벤트) + → deploy_server (webhook 수신 → git pull → 빌드 → 재시작) + → systemd (.service — 부팅 자동기동·재시작) + → nginx (도메인 vhost: / → SPA 정적, /api/ → 백엔드 포트 프록시, certbot TLS) +``` + +### 7.1a nginx vhost 표준 (도메인 서빙형) +``` +브라우저 ── https ──> nginx(.zioinfo.co.kr) + ├─ / → /var/www/ (React SPA build, index.html 폴백) + └─ /api/ → 127.0.0.1:<백엔드 포트> (Spring Boot) +``` +- vhost 정본은 repo의 `deploy/nginx/*.conf`에 두고 서버 `sites-available` → `sites-enabled` 심링크. `nginx -t` 통과 후 reload(타 사이트 무영향 확인). +- 절차: DNS A 레코드 등록 → 전파 확인 → `certbot --nginx -d `(443 블록 + 80→443 리다이렉트 자동 주입, 갱신은 certbot timer) → 프론트 dist 복사 → 백엔드 systemd 기동. +- 백엔드 포트는 서버 점유 현황 확인 후 솔루션별 고정(`server.port: ${SERVER_PORT:<포트>}`). + +### 7.2 배포 규칙 +- **Fail-Safe 시퀀스**: 백업 → 배포 → 헬스체크 → 롤백. +- 배포 후 **health 게이트** 확인 필수(엔드포인트 200 확인 후 완료 선언). +- **서버 빌드는 직렬 실행** — 공유 메모리 서버에서 병렬 빌드 시 OOM 위험. +- AI env는 systemd **drop-in**으로 주입: 서비스 작업 디렉터리의 `guardia-ai.env`(600) + `ai-env.conf`(EnvironmentFile) — 기존 ExecStart 불변. +- 웹훅 시크릿·자격증명은 설정 파일/env로만 관리(마스킹), 배포 로그에 미노출. +- 함정 주의: 배포 로그가 "완료"여도 소요가 비정상적으로 짧으면 deploy_server에 해당 솔루션 블록이 없는 것일 수 있다 — deploy_server 수정 시 서버 사본 반영 + 재시작 필수. + +### 7.2a 배포 검증 체크리스트 +- [ ] 빌드: 백엔드 compile/bootJar 통과 + 프론트 빌드 통과(단일 jar면 프론트 → 백엔드 static 번들 순서 준수). +- [ ] DB: 마이그레이션/시드 멱등 확인 — 라이브 반영 전 dry-run(트랜잭션 BEGIN…ROLLBACK) 권장. +- [ ] 시크릿: fail-fast — 필수 env 미설정 시 기동 실패로 조기 검출(운영에서 개발 기본값 사용 금지). +- [ ] 커밋: 파일 단위로 스코프 분리(공유 트리 교차 커밋 방지). +- [ ] 배포 후: health 엔드포인트 200 → 대표 화면/대표 API 스팟체크 → 기존 기능 회귀 확인. +- [ ] 웹훅: Gitea webhook URL·secret·allowed hosts 정합(불일치 시 403/no-op으로 조용히 실패하는 사례 있음). + +### 7.3 프론트/백엔드 배포 형태 +- 표준은 **단일 jar**(프론트 빌드를 백엔드 static으로 번들) — jar 하나만 systemd로 기동. +- 일부 솔루션(UIMS 등)은 nginx 직접 서빙형: 프론트 `dist/` → `/var/www//`(SPA `index.html` 폴백), 백엔드는 전용 포트 systemd 기동. +- DNS(서브도메인 A 레코드) → certbot TLS(80→443 리다이렉트 자동 주입) → 배포 순서. + +--- + +## 8. 준수·이식 하네스 맵 + +| 트랙 | 담당 하네스 | +|------|------------| +| 공통 업무모듈·2FA 이식 | `uiws-port-orchestrator` | +| Claude AI 전환·OTP·admin 표준화 | `guardia-claude-ai-orchestrator` | +| RAG 검색 인프라 | `guardia-rag-orchestrator` | +| 환각 방지·근거검증 레이어 | `guardia-ai-trust-orchestrator` | +| 검색 품질 기법(GraphRAG·rerank 등) | `guardia-ai-technique-orchestrator` | +| WISE AI 전 솔루션 적용 | `wise-ai-platform-orchestrator` (+ `WISE_APPLY_SPEC.md`) | +| 관리자 백오피스 표준화 | `guardia-admin-orchestrator` | +| 스키마 무결성 점검·수복 | `schema-integrity-orchestrator` | + +### WISE AI 적용 불변 규칙 (적용 에이전트 공통) +1. 기존 기능 회귀 0 — 기존 AI/RAG 코드 삭제·개조 금지(보강·개명만). 빌드 통과 필수. +2. 외부 API 0(anthropic 예외) — 단, WISE 적용 트랙은 **rag 경유만**: 솔루션에서 LLM 직접 호출 신설 금지. +3. 자격증명·내부 IP·스택트레이스 미노출. rag 호출 실패는 요약 메시지로 처리. +4. 서버 RAM 존중 — 솔루션에서 Ollama 직접 호출 신설 금지(전부 중앙 rag 경유). +5. 커밋 메시지는 영문. push는 자동배포 스크립트 경유, 배포 후 health 확인. + +### 적용 대상 스코프 (2026-07 기준) +- Java(Spring Boot): erp·crm·ocr(WISE)·bi·pms·rpa·groupware·portal·mall·cms·mes·hrm·fa·esn·zioinfo-esn + 신규(mro·signage 등). +- Python(FastAPI 예외): itsm·manager·guardia-rag(중앙). +- 제외: uiws(표준 정본 — 읽기 전용)·zioinfo-web(AI 없음). + +### 신규 프로젝트 체크리스트 (요약) +1. 스택: React+TS+Vite / Spring Boot 3.5 Java 17 + MyBatis / PostgreSQL `_db` / 단일 jar. +2. 인증: JWT+RBAC + TOTP 2FA + 로그인 잠금 + admin 비번 env 암호화 재시드. +3. 공통 모듈: worklog·schedule·message·stats·system·notice·opinion·search·meeting·report·notification·audit 중 필요분 이식. +4. 디자인: WISE 토큰·Pretendard·카드·선 SVG 아이콘, `guardia-chief-designer` 리드. +5. AI: AiTextRouter 폴백 체인 + 중앙 guardia-rag 경유(`/api/wise/ask` 프록시) + DuckDB 피드백. +6. 보안: 외부 API 금지(Anthropic 예외)·자격증명 미노출·AES-256-GCM·스택트레이스 차단·감사로그. +7. 배포: repos→Gitea→webhook→systemd→nginx, health 게이트, Fail-Safe 롤백. + +--- + +## 8a. 용어 정리 + +| 용어 | 의미 | +|------|------| +| UIMS / UIWS | URP Infra Working System — GUARDiA 표준 프레임워크의 정본 레퍼런스 구현(`workspace/uiws`) | +| WISE | Workplace Intelligence Search Engine — 엔터프라이즈 AI 브랜드이자 디자인 시스템 명칭 | +| guardia-rag | 중앙 온프레미스 RAG 서비스(Python FastAPI) — 전 솔루션 AI 질의의 단일 경유점 | +| AiTextRouter | 프로바이더 선택 + 3계층 폴백을 수행하는 표준 AI 라우터(UIMS 패턴) | +| DataScope | 목록·집계 API의 조회 범위 권한(ADMIN 전체 / MANAGER 부서+하위 / USER 본인) | +| abstain | 근거 미달 시 답변을 보류하는 환각 차단 동작(`abstained=true`) | +| degraded | 상위 프로바이더 실패로 폴백·축소 동작 중임을 알리는 상태 플래그 | +| 단일 jar | 프론트 빌드 산출물을 백엔드 static에 번들해 jar 하나로 배포하는 표준 패키징 | + +--- + +## 9. 참조 소스 맵 + +| 문서 | 경로 | 성격 | +|------|------|------| +| 표준 프레임워크 명세 | `workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md` | **단일 출처(최우선)** | +| WISE AI 적용 명세 | `workspace/_framework/WISE_APPLY_SPEC.md` | 전 솔루션 WISE AI 적용 계약 | +| Stitch 디자인 베이스 | `workspace/_framework/STITCH_DESIGN_BASE.md` | 디자인 생성 기준 | +| AI 플랫폼 스펙 | `workspace/_ai_track/AI_PLATFORM_SPEC.md` | 프로바이더·화이트리스트·폴백·DuckDB 계약 | +| AI 설정화면 스펙 | `workspace/_ai_track/design/ai_platform_settings_spec.md` | AiConfig 화면 | +| OTP 마이페이지 스펙 | `workspace/_ai_track/design/otp_mypage_spec.md` | 2FA UX | +| UIMS 백엔드 README | `workspace/uiws/backend/README.md` | auth·봉투·패키지 구조 정본 | +| UIMS 배포 가이드 | `workspace/uiws/deploy/README_배포.md` | nginx vhost·certbot·systemd 절차 | +| 프로젝트 마스터 컨텍스트 | `C:\GUARDiA\CLAUDE.md` § "GUARDiA 표준 프레임워크 (UIMS 기준)" | 승격 선언·하네스 맵 | + +> **주의:** 이 지식 문서에는 비밀번호·API 키·토큰·SSH 자격증명을 기재하지 않는다. 실제 값은 서버 env/시크릿 파일에만 존재하며, 서버 식별은 도메인(`zioinfo.co.kr`, `git.zioinfo.co.kr` 등)으로만 한다. diff --git a/plugins/zio-harness/knowledge/kintex/CLAUDE.md b/plugins/zio-harness/knowledge/kintex/CLAUDE.md new file mode 100644 index 0000000..4406bee --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/CLAUDE.md @@ -0,0 +1,156 @@ +# 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개국어인데 모바일은?" | + +## graphify + +This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. + +Rules: +- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. +- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. +- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. +- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). diff --git a/plugins/zio-harness/knowledge/kintex/README.md b/plugins/zio-harness/knowledge/kintex/README.md new file mode 100644 index 0000000..04282aa --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/README.md @@ -0,0 +1,21 @@ +# KINTEX AI 시스템 + +킨텍스 전시 운영(부스 배치·인테리어 공사·네트워크 배선·전기·조명)을 AI로 자동화하고, +나노바나나(Gemini 이미지 생성)로 시공 후 결과 사진까지 미리 보여주는 시스템. + +- 개발 하네스 사용법: [CLAUDE.md](CLAUDE.md) +- 시스템 기획서: [docs/PLANNING.md](docs/PLANNING.md) +- UI 디자인 스펙(Stitch 전달용): [docs/design.md](docs/design.md) +- 도메인 리서치: [docs/analysis/](docs/analysis/) + +## 시작하기 (Claude Code / Cowork) +이 폴더를 Claude Code로 열면 CLAUDE.md와 `.claude/agents/`의 +기획(planner)·디자인(designer)·개발(developer)·시각화(visualizer)·검증(reviewer) +에이전트가 자동 인식된다. + +예시: +``` +> 부스 배치 추천 기능의 기획을 보강해줘 # → planner 에이전트 +> 배선 신청 화면 design.md에 추가해줘 # → designer 에이전트 +> 3x3 목공부스 야간 시안 이미지 만들어줘 # → visualizer + nanobanana-visualize 스킬 +``` diff --git a/plugins/zio-harness/knowledge/kintex/docs/API_GUIDE.md b/plugins/zio-harness/knowledge/kintex/docs/API_GUIDE.md new file mode 100644 index 0000000..1c62db4 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/API_GUIDE.md @@ -0,0 +1,97 @@ +# 킨텍스 자동전시시스템 — API 규약 가이드 + +> **WISE(UIWS) 참조** — 응답 봉투(`ApiResponse`/`PageResponse`)·인증(JWT+2FA)·에러 처리 규약은 `workspace/uiws/backend/README.md`를 따른다. +> **정본 계약서**: 엔드포인트 상세·요청/응답 shape·DB 매퍼 인수는 [`_workspace/01_backend_contracts.md`](../_workspace/01_backend_contracts.md)가 단일 진실원천이다. 본 문서는 **규약(convention)만 요약**하고 세부는 계약서로 링크한다(중복 서술 회피). + +--- + +## 1. 경로·버전 규약 + +- 베이스: `/api`. 프론트 axios `baseURL=/api`(동일 도메인 서빙, 별도 CORS 불필요). +- 도메인 경로는 **행사 스코프** 접두: `/api/events/{eventId}/…` (예 `…/halls/{hallId}/layout`, `…/booths/{boothId}/design`). +- 시스템/관리 경로: `/api/system/**`·`/api/admin/**`(ADMIN 전용). 인증: `/api/auth/**`. +- 내부(워커) 경로: `/api/internal/**`(공유 시크릿 인증). +- **버전**: P0는 무접두(`/api/...`). 파괴적 변경 발생 시 `/api/v2/...` 도입 — 계약서 변경 이력에 기록하고 frontend·qa에 통지. + +--- + +## 2. 응답 봉투 + +모든 응답은 `ApiResponse`: +```json +{ "success": true, "data": { ... }, "error": null } +{ "success": false, "data": null, "error": { "code": "FORBIDDEN", "message": "이 행사/부스에 대한 권한이 없습니다." } } +``` +- 목록: `PageResponse` = `{ "items": [...], "page": 0, "size": 20, "total": 123 }`. (P0 갤러리/워크스페이스는 배열 직접 반환도 허용 — 계약서 §0-1.) +- `error.message`는 사람이 읽을 **요약만**. 상세·스택트레이스 미노출(서버 로그). + +--- + +## 3. 오류 코드 → HTTP (고정) + +| code | HTTP | 의미 | +|---|---|---| +| `VALIDATION` | 400 | 요청 값 오류(필드 메시지 포함) | +| `UNAUTHORIZED` | 401 | 미인증/토큰 만료 | +| `FORBIDDEN` | 403 | 행사/부스 권한 없음 | +| `NOT_REGISTERED_COMPANY` | 403 | 미등록 장치업체 초대·응찰 차단 | +| `NOT_FOUND` | 404 | 대상 없음 | +| `CONFLICT` | 409 | 상태 충돌(낙관적 잠금 등) | +| `COMPLIANCE_BLOCKED` | 422 | 규정 위반(차단) | +| `RENDER_QUOTA_EXCEEDED` | 429 | 행사 이미지 생성 쿼터 소진 | +| `NOT_IMPLEMENTED` | 501 | 매퍼/엔진 구현 대기(스켈레톤) | +| `INTERNAL` | 500 | 서버 오류(요약만) | + +> 코드는 문자열 상수(`common.exception.ErrorCode`). 신규 코드 추가 시 계약서 §0-2와 본 표를 동시 갱신. + +--- + +## 4. 인증 헤더 · RBAC + +- 헤더: `Authorization: Bearer ` (HS256). 클레임: `sub`(userId)·`name`·`roles`(eventId→역할)·`hm`(홀매니저). +- 공개 경로(인증 불필요): `GET /health`, `POST /api/auth/login`, `/ws/**`, `POST /api/internal/render/callback`(워커 토큰). +- **2차 인증**: `POST /api/auth/login`(1차) → `verifyToken` → `POST /api/auth/verify-otp`(EMAIL 코드/OTP) → access·refresh. (WISE `auth` 이식 — [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md) §4.) +- **행사 단위 RBAC**: 역할 `ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER`([`COMMON_CODES.md`](COMMON_CODES.md) `EVENT_ROLE`). 가드 — 열람=행사 멤버 or 홀매니저 / 편집·액션=엔드포인트별 역할. + +--- + +## 5. 보안 불변 (API 계약 강제) + +- 민감정보(IP·SSH·비밀번호·해시·내부 식별자·`GEMINI_API_KEY`) 응답 완전 제외. 사용자/업체 표시는 비민감 필드만. +- **AI 생성 이미지**(M5)는 응답에 `watermarkRequired:true`+`watermarkText`+`notice`(계약·심사 서류 사용 금지) **항상** 포함. +- 워커 실패 시 `errorMessage`는 요약만 통과(스택트레이스 유입 차단). +- 상세: [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md) §5. + +--- + +## 6. 비동기·실시간 (Redis + WebSocket) + +- **RenderJob**: `POST …/render`(발행) → Redis 큐(`kintex:renderjob:queue`) → Python 워커 소비 → `POST /api/internal/render/callback`(콜백) → 상태 갱신. +- **WebSocket(STOMP)**: 핸드셰이크 `GET /ws`(SockJS), 브로드캐스트 prefix `/topic`, 클라→서버 `/app`. 구독 `/topic/render/{jobId}` → RenderJob 완료/실패 푸시. (승인 이벤트 토픽은 M6/C-4 확장.) + +--- + +## 7. 엔드포인트 카탈로그 (요약 — 상세는 계약서) + +> 각 항목의 요청/응답 shape·완성/스켈레톤(501) 현황은 [`_workspace/01_backend_contracts.md`](../_workspace/01_backend_contracts.md) 해당 절 참조. + +| 영역 | 대표 경로 | 계약서 절 | +|------|-----------|-----------| +| 헬스 | `GET /health` | §1 | +| 인증·워크스페이스 | `/api/auth/login·workspaces·me·accept-invite` | §2 | +| M2 플로어플랜 | `/api/events/{eventId}/halls/{hallId}/layout` (`GET·PUT·validate·auto-generate`) | §3 | +| M3 부스 설계 | `/api/events/{eventId}/booths/{boothId}/design` (`GET·PUT·precheck`) | §4 | +| M4 유틸리티/배선 | `/api/events/{eventId}/booths/{boothId}/utility` (`quote·wiring·order·GET`) | §5 | +| M5 나노바나나 | `/api/events/{eventId}/booths/{boothId}/render` · `/render-jobs/{jobId}` · `/api/internal/render/callback` | §6 | +| 룰셋 | `rulesets/compliance-v1.json`·`rates-v1.json` (데이터 계약) | §7 | +| DB 매퍼 인수 | UserMapper·BoothMapper·DesignMapper·WiringMapper·RenderJobMapper (PostGIS) | §8 | + +> Phase D 도메인(M10 관람객·M12 공개사이트/CMS·M15 옥션·M16 BI·M18 관리자)의 API는 각 도메인 에이전트가 계약서에 절을 추가하며 확장한다. 본 가이드의 §1~6 규약을 동일 준수. + +--- + +## 8. 참조 + +- 정본 계약서: [`_workspace/01_backend_contracts.md`](../_workspace/01_backend_contracts.md) +- 나노바나나 워커 계약: [`../tools/nanobanana/_workspace/01_worker_contract.md`](../tools/nanobanana/_workspace/01_worker_contract.md) +- 개발 표준: [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md) · 공통코드: [`COMMON_CODES.md`](COMMON_CODES.md) diff --git a/plugins/zio-harness/knowledge/kintex/docs/BACKLOG.md b/plugins/zio-harness/knowledge/kintex/docs/BACKLOG.md new file mode 100644 index 0000000..d04e117 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/BACKLOG.md @@ -0,0 +1,29 @@ +# BACKLOG — 검증 에이전트(reviewer) 지적사항 티켓 + +> v1.0 검증(2026-07-11) 결과. Critical 0건. 하네스 레벨의 기계적 수정(참조 파일 표기, 워터마크 문구 통일, S1~S7 샷 정렬, 배선 색상 규약, 간판 문구 파라미터, mime 자동 감지)은 v1.0.1에서 반영 완료. 아래는 잔여 티켓. + +| ID | 심각도 | 내용 | 담당 에이전트 | 상태 | +|---|---|---|---|---| +| B-01 | Major | 조립부스 옵션(간판·가구·조명 선택) 신청 UI 부재 — PLANNING M3 Phase 1 범위인데 design.md에 화면 없음. SCR-05/06에 조립부스 모드 추가 필요 | designer | open | +| B-02 | Major | S6 배선 오버레이의 시공 검증용 산출은 생성형이 아닌 백엔드 래스터 합성 렌더러로 구현 필요 (client.py에는 주의 주석만 반영됨) | developer | **done** (v1.2) — `render_wiring_overlay_raster()` 신설(로컬 PIL, 좌표 정합, power=적/network=청/plumbing=녹, 트렌치 마커·범례, base_image 합성). 생성형 `generate_wiring_overlay`는 발표 보조용으로 분리 | +| B-03 | Major | 나노바나나 입력 스키마를 PLANNING §6-2 정식 스키마(booth polygon, zones, shot preset, render_hints)로 확장 + GeneratedImage에 메타데이터(생성일·스키마 해시·모델 버전) 임베드 | visualizer/developer | **done** (v1.2) — `build_booth_prompt(scene)`가 §6-2 scene(hall/booth/design/lighting/wiring/shot/render_hints) 수용, `GeneratedImage.save()`가 사이드카 `.meta.json`+PNG tEXt 청크로 생성일·스키마 해시(SHA-256)·모델 버전·seed 결정적 임베드 | +| B-04 | Minor | design.md 화면 수 표기(13) → 실제 웹 12+모바일 2=14 정정 | designer | open | +| B-05 | Minor | SCR-02 프롬프트 사이드바 "정산" 메뉴 — IA와 불일치 정리 | designer | open | +| B-06 | Minor | SCR-01 이메일 인증 로그인 프롬프트 누락 | designer | open | +| B-07 | Minor | SCR-03 "공유" 버튼 프롬프트 누락 + 위반 요약(2/3)과 캔버스 핀 샘플(적2·주1) 불일치 | designer | open | +| B-08 | Minor | SCR-04 샘플 지표 산술 오류(510부스 ↔ 판매면적 4,420㎡) | designer | open | +| B-09 | Minor | analysis 문서 내 D-15/D-25 표기 혼재 정리 | planner | **done** (v1.1) — kintex-website.md §5 마일스톤을 D-150/D-30/D-25/D-7로 통일(유틸리티=D-25), D-15 오기 제거 | +| B-10 | Minor | 홀매니저(SCR-10/11)·현장 모바일(SCR-M1/M2) 화면에 Phase 2/3 라벨 부착, 조명 배치안 제안(M4a) 전용 UI 검토 | designer | open | +| B-11 | Major | ReRoomAI 소스 분석(docs/analysis/reroomai-source.md) — 소스 폴더 연결 대기 중. 완료 후 PLANNING §6 ReRoomAI 연계 절 보강 | planner/visualizer | **done** (v1.1) — 소스 분석 완료·PLANNING §6-4/6-5 확정(모델·SDK·구조화 사전·보존/교체 프롬프트 템플릿·RenderJob 방어·UX), §10 R11 해소·R12 추가 | +| B-12 | Minor | client.py에 동일 시드/일관성 파라미터(PLANNING §6-3) 지원 검토 (Gemini API 시드 지원 범위 확인 필요) | visualizer | **done** (v1.2) — `render_shot(..., seed=)` 지원. `GenerateContentConfig(seed=)`로 전달 시도하되 SDK/모델 미지원(TypeError)이면 자동으로 참조체인 기반 일관성(첫 컷을 다음 샷 reference_image로 재사용)으로 폴백. SKILL.md에 명시. ★실호출 검증은 소유자 승인 후 | + +## 신규 5화면(SCR-13~17) reviewer 검증 티켓 (2026-07-11 · 배포 가능 판정, 전부 Minor) + +| ID | 심각도 | 내용 | 담당 | 상태 | +|---|---|---|---|---| +| R13-01 | Minor | SCR-13 추세 차트 "AI 예측 점선 구간"이 스펙·힌트 문구엔 있으나 AreaChart가 점선 예측 구간을 미렌더 — 힌트가 없는 요소를 지칭(오도 소지). 점선 렌더 구현 또는 힌트 정정 | developer(designer 확인) | open | +| R15-01 | Minor | SCR-15 홀 셀렉트가 필터 로직에 미배선(선택 무효과) | developer | **done** (2026-07-11) — `matchesHall()` 배선("홀" 뒤 번호만 파싱, "제N전시장" N 오매칭 방지), tsc 재통과 | +| R15-02 | Minor | SCR-15 실 워크스페이스 모드에서 category를 'exhibition' 하드코딩 — 샘플/기본값 시각 표기 없음(estVisitors는 "집계 대기" 표기됨) | developer | open | +| R17-01 | Minor | SCR-17 스타일가이드에 "시스템 아이콘 라이브러리" 섹션 누락(스펙 9항목 중 1) — 아이콘 세트 교체(UNDEVELOPED_BACKLOG §1)와 함께 처리 권장 | developer(designer) | open | +| R17-02 | Minor | `chartColors.ts`의 `CHART.warning` 키가 §1-2 warning(#B45309)이 아닌 §1-4 violation-warn(#F79009) 값 — 값은 토큰 정합, 키 이름만 오용 위험 → `violationWarn` 등으로 개명 권장 | developer | open | +| R00-01 | 정보 | AppShell 단일 셸에 전 역할 네비 무차별 노출 — 역할별 포털+MDI 분리는 미착수 대형 트랙으로 기추적(UNDEVELOPED_BACKLOG §1·§4) | FE·DES | tracked | diff --git a/plugins/zio-harness/knowledge/kintex/docs/BUILD_DEPLOY.md b/plugins/zio-harness/knowledge/kintex/docs/BUILD_DEPLOY.md new file mode 100644 index 0000000..a5d18b2 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/BUILD_DEPLOY.md @@ -0,0 +1,87 @@ +# 킨텍스 자동전시시스템 — 빌드/실행 개요 + +> **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**: `` 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 diff --git a/plugins/zio-harness/knowledge/kintex/docs/COMMON_CODES.md b/plugins/zio-harness/knowledge/kintex/docs/COMMON_CODES.md new file mode 100644 index 0000000..c149726 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/COMMON_CODES.md @@ -0,0 +1,74 @@ +# 킨텍스 자동전시시스템 — 공통코드 정의 + +> **WISE(UIWS) 참조** — 공통코드 체계(그룹 `TB_CODE_GRP` / 값 `TB_CODE`, 코드값=영문 상수·코드명=한글 표기)는 `workspace/uiws/_workspace/01_analyst_codes.md`를 따른다. +> **확정 규칙**: **확정**=PLANNING/계약서에 값 명시 / **확인 필요**=Phase A(DA)·도메인 에이전트 확정 대기. 미정 코드값은 임의 확정 금지 — 확정 시 본 문서 + ERD 컬럼 주석 동시 갱신. +> 근거: [`PLANNING.md`](PLANNING.md)·[`design.md`](design.md)·[`_workspace/01_backend_contracts.md`](../_workspace/01_backend_contracts.md). + +--- + +## 1. 공통코드 관리 원칙 (WISE 체계 이식) + +- 적재: `TB_CODE_GRP`(그룹) / `TB_CODE`(값). 코드값은 **영문 상수**, 코드명은 화면 표기 **한글**. +- 시스템관리(B-2)의 공통코드 관리 화면에서 CRUD. DTO 필드 ↔ 코드그룹 매핑은 §4 표를 단일 출처로 준수. +- **코드 vs 마스터 구분**: 열거 가능한 소수 값은 공통코드, 다건·CRUD 대상(홀·요율·규정 룰셋·등록업체)은 **마스터 테이블**로 관리(공통코드 아님). + +--- + +## 2. 킨텍스 도메인 공통코드 + +| 그룹코드 | 그룹명 | 코드값 목록 (코드값=코드명) | 사용처 | 확정여부 | +|---|---|---|---|---| +| `EVENT_ROLE` | 행사 역할(RBAC) | `ORGANIZER`=주최자, `EXHIBITOR`=참가업체, `CONTRACTOR`=장치·시공업체, `HALL_MANAGER`=홀매니저(킨텍스 운영) | 계약서 §0-5 RBAC, JWT `roles`, 역할별 포털 | **확정** (계약서 §0-5) | +| `PORTAL_ROLE` | 포털/채널 역할(6분리) | `ORGANIZER`, `EXHIBITOR`, `CONTRACTOR`, `OPS`=킨텍스 직원/홀매니저, `ADMIN`=시스템관리자, `VISITOR`=관람객, `PUBLIC`=일반 대중 | PLANNING §2-1 역할별 웹/모바일 포털 분리 | **확정** (PLANNING §2-1) — VISITOR/PUBLIC은 P1·공개·셀프서비스 쓰기 제한 | +| `BOOTH_TYPE` | 부스 유형 | `independent`=독립부스, `assembled`=조립부스 | M2/M3 설계(계약서 `boothType`), 부스 마스터 | **확정** (PLANNING §5 M3: 조립/독립 · 계약서 design `boothType:"independent"`) | +| `ZONE_TYPE` | 부스 구역 유형 | `demo`=시연, `consult`=상담, `storage`=창고, `reception`=접수 (확장 가능) | M3 DesignSpec `zones[].type` | 부분 확정 (계약서에 demo·consult 명시, 그 외 **확인 필요** — designer/DA) | +| `LAYOUT_STATUS` | 배치안 상태 | `draft`=작성중, `submitted`=제출, `approved`=승인, `rejected`=반려 | M2 LayoutDto `status` | 부분 확정 (계약서 `draft` 명시, 전이 상태는 M6 승인 워크플로 **확인 필요**) | +| `DESIGN_STATUS` | 설계안 상태 | `draft`=작성중, `submitted`=제출, `approved`=승인, `rejected`=반려 | M3 DesignPlanDto `status` | 부분 확정 (계약서 `draft` 명시, 나머지 **확인 필요**) | +| `COMPLIANCE_SEVERITY` | 규정 심각도 | `block`=차단, `warn`=경고, `pass`=통과 | M2/M3 ComplianceReport `violations[].severity` | **확정** (계약서 §3·§4: block/warn + passCount) | +| `COMPLIANCE_GROUP` | 규정 그룹 | `egress`=피난/비상, `structure`=구조/하중, `height`=높이, `fire`=방염, `lighting`=조명 (룰셋 기준) | 규정 룰셋(`compliance-v1.json`), ComplianceReport `group` | 부분 확정 (계약서 `egress` 명시 — 전체 그룹은 룰셋 데이터가 정본, **확인 필요**) | +| `RENDER_STATUS` | 렌더잡 상태 | `QUEUED`=대기, `RUNNING`=진행, `DONE`=완료, `FAILED`=실패 | M5 RenderJobDto `status` | **확정** (계약서 §6) | +| `SHOT_PRESET` | 표준 샷 세트 | `S1`=정면 주간, `S2`=정면 야간, `S3`=통로 뷰, `S4`=내부 뷰, `S5`=Before/After, `S6`=배선 오버레이(래스터), `S7`=홀 전경 조감 | M5 RenderJobRequest `shotPreset` | **확정** (PLANNING §6-3 · 워커 README) | +| `UTILITY_ORDER_STATUS` | 유틸리티 신청 상태 | `draft`=작성중, `submitted`=제출, `relayed`=릴레이완료 | M4 UtilityOrderDto `status` | 부분 확정 (계약서 `submitted` 명시, 나머지 **확인 필요**) | +| `AUCTION_STATUS` | 옥션 상태 | `OPEN`=응찰중, `BIDDING`=라운드진행, `AWARDED`=낙찰, `CLOSED`=마감 (예시) | M15 공사/장치 옥션(Auction) | **확인 필요** (Phase D bidding-dev/DA 확정 — 계약 미정의) | +| `QUOTATION_STATUS` | 견적서 상태 | `SUBMITTED`=제출, `REVISED`=수정, `AWARDED`=낙찰, `REJECTED`=탈락 (예시) | M15 Quotation | **확인 필요** (Phase D bidding-dev/DA 확정) | +| `USE_YN` | 사용여부 | `Y`=사용, `N`=미사용 | 전 관리화면 공통 | **확정** (시스템 공통) | + +> 위 상태·옥션·구역 코드 중 **확인 필요** 항목은 예시 제안값이다. Phase A(DA)·해당 도메인 에이전트가 화면/워크플로 확정 시 값을 고정하고 본 문서·ERD를 동시 갱신한다. + +--- + +## 3. WISE 공통 레이어 코드 (이식 대상) + +공통 업무·시스템관리 레이어(B-2/B-3)를 WISE에서 이식할 때 아래 코드도 함께 이식한다(값은 WISE `01_analyst_codes.md` 정본): + +| 그룹코드 | 그룹명 | 요지 | +|---|---|---| +| `USER_ROLE` | 시스템 사용자 역할 | `USER`/`MANAGER`/`ADMIN` — 데이터 가시범위·권한 단일 소스(본인/팀/전체). 킨텍스는 `EVENT_ROLE`(행사 스코프)와 병행 운용 | +| `VERIFY_METHOD` | 2차검증 방식 | `EMAIL`=이메일 인증코드, `OTP`=OTP앱(TOTP). 사용자별 선택 | +| `PRG_TYPE` | 프로그램 유형 | `FORM`/`POPUP` — 메뉴/프로그램 관리 | +| `MSG_RCV_TYPE` | 쪽지 수신구분 | `RECV`/`REF` — 공통 message 모듈 이식 시 | +| (기타) | worklog·schedule·stats 코드 | worklog·schedule·통계 모듈 이식 시 WISE 코드(WORK_STATUS·WORK_TYPE·SCHE_GUBUN·IMPORTANCE·WORK_PROGRESS 등) 동반 이식 | + +> 킨텍스는 **행사 단위 역할(`EVENT_ROLE`)이 1차 권한 소스**다. WISE `USER_ROLE`(전역 가시범위)은 공통 업무 레이어(worklog 등)를 이식할 때만 병행 적용한다. + +--- + +## 4. DTO 필드 ↔ 코드그룹 매핑 요약 + +| DTO 필드 | 코드그룹 | 비고 | +|---|---|---| +| `myRole` / `eventRoles` | EVENT_ROLE | 행사별 역할(계약서 login·me) | +| `boothType` | BOOTH_TYPE | M2/M3 | +| `zones[].type` | ZONE_TYPE | M3 DesignSpec | +| `status`(layout) | LAYOUT_STATUS | M2 | +| `status`(design) | DESIGN_STATUS | M3 | +| `violations[].severity` | COMPLIANCE_SEVERITY | M2/M3 규정 리포트 | +| `violations[].group` | COMPLIANCE_GROUP | 룰셋 데이터 기준 | +| `status`(render) | RENDER_STATUS | M5 | +| `shotPreset` | SHOT_PRESET | M5 | +| `status`(utility order) | UTILITY_ORDER_STATUS | M4 | +| `status`(auction) | AUCTION_STATUS | M15 (확인 필요) | +| `verifyMethod` | VERIFY_METHOD | 2차 인증 | +| `useYn` | USE_YN | 공통 | + +> 비-코드(마스터 테이블): 홀(`Hall`)·요율 룰셋(`rates-v1.json`)·규정 룰셋(`compliance-v1.json`)·등록업체(`Company`)는 공통코드가 아니라 마스터/버전 파일로 관리(관리자 백오피스 M18에서 CRUD·버전). diff --git a/plugins/zio-harness/knowledge/kintex/docs/DESIGN_SYSTEM_NIFTY.md b/plugins/zio-harness/knowledge/kintex/docs/DESIGN_SYSTEM_NIFTY.md new file mode 100644 index 0000000..4b82a25 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/DESIGN_SYSTEM_NIFTY.md @@ -0,0 +1,96 @@ +# 킨텍스 디자인 시스템 — Nifty × kx 토큰 (학습 문서) + +> **목적:** 소유자 확정(2026-07-12) — 킨텍스 공통 UI의 디자인 기준 = **Nifty(themeon, Bootstrap 5 기반 관리자 테마)**. 이 문서는 Nifty 컴포넌트 패턴을 킨텍스 **kx 디자인 토큰**으로 번역하는 단일 규칙서다. 모든 UI 작업(에이전트·수동)은 착수 전 이 문서를 읽고 준수한다. +> 레퍼런스 인덱스: `docs/analysis/nifty-design-refs.md`. 토큰 정본: `src/frontend/src/styles/tokens.css`. + +--- + +## 0. 대원칙 (불변) +1. **kx 토큰으로만 번역** — Nifty/Bootstrap의 hex·px를 그대로 쓰지 말고 아래 토큰에 매핑. 하드코딩 hex 금지. +2. **다크/라이트 양 테마** — 색은 `--color-*`(테마 remap) 사용. `--dk-*` 직접 참조 금지. +3. **이모지 금지** — 아이콘은 선(stroke) SVG(`components/ui/icons.tsx`)만. +4. **WISE 우선** — 셸·시스템관리·공통기능·캘린더는 WISE(UIWS) 구조가 정본. Nifty는 WISE에 없는 **공통 컴포넌트 스타일**(테이블·카드·버튼·드롭다운·리스트그룹·모달·뱃지·알럿·탭)의 레퍼런스. +5. **접근성** — focus-visible 링(`--focus-ring`)·role/aria·WCAG AA·`prefers-reduced-motion`. + +## 1. 토큰 매핑표 (Nifty/Bootstrap → kx) + +### 색상 (Bootstrap contextual → kx) +| Nifty/BS | 의미 | kx 토큰 | +|---|---|---| +| primary | 주 액션 | `--color-primary-600`(#0066b3) / hover `--color-primary-700`(#004c86) | +| success | 성공·승인 | `--color-success`(#0e8a5f) / bg `--color-success-bg` | +| warning | 경고·임박 | `--color-warning`(#b45309) / bg `--color-warning-bg` | +| danger | 위험·오류 | `--color-error`(#d92d20) / bg `--color-error-bg` | +| info | 보조 정보 | `--color-primary-050/100` + `--color-primary-700` 텍스트 | +| default/light | 중립 | `--color-neutral-100` bg / `--color-neutral-700` 텍스트 / `--border-card` | +| dark | 강조 텍스트 | `--color-neutral-900`(#101828) | +| (AI 전용) | AI 기능 | `--color-ai-accent`(#6d4aff) / surface `--color-ai-surface` | + +### 타이포 (Nifty 위계 → kx `--fs-*`) +| 용도 | kx 토큰 | +|---|---| +| 페이지 타이틀(h1) | `--fs-h1` 24/32 | +| 섹션(h2) | `--fs-h2` 20/28 | +| 카드 제목(h3) | `--fs-h3` 16/24 | +| 본문 | `--fs-body` 14/22 | +| 캡션·헤더셀·메타 | `--fs-caption` 12/18 | +| 숫자열 | `--fs-body` + `font-variant-numeric: tabular-nums`(`.tnum`) | +| 코드/모노 | `--fs-mono` 13 / `--font-mono` | + +### 간격·모양 +| Nifty | kx | +|---|---| +| 컴포넌트 내부 패딩 | `--space-2`(8) ~ `--space-4`(16) | +| 카드 패딩 | `--space-4`(16) ~ `--space-5`(24) | +| 요소 간 gap | `--space-1~3` | +| 섹션 간 | `--space-5`(24, 상한 `--space-6` 32) | +| 버튼·인풋 radius | `--radius-sm`(4) | +| 카드·패널 radius | `--radius-lg`(8) | +| 배지·필·토글 | `--radius-pill` | + +## 2. 컴포넌트 규격 (Nifty 패턴 → kx 구현) + +### 2.1 버튼 (`Button` / `.kx-btn`) +- **변형**: primary(채움) · secondary(아웃라인) · ghost(투명) · danger. Nifty의 8색 전부를 만들지 말고 **의미 단위**(주/보조/위험/AI)로 수렴. +- **크기**: `sm`(높이 28·`--fs-caption`) · `md`(기본 36·`--fs-body`) · `lg`(44). Nifty xs~lg를 3단으로. +- **상태**: hover(명도 1단계)·active·disabled(opacity .5·cursor not-allowed)·loading(스피너). focus-visible 링 필수. +- **아이콘**: leadingIcon(선 SVG)·icon-only(정사각·aria-label). 버튼 그룹은 인접 radius 접합. +- **블록**: `block`=100% 폭. + +### 2.2 카드 (`.kx-card`) +- 구조: `kx-card`(테두리 `--border-card`·radius-lg·bg `--color-white`) > `kx-card__head`(제목 h3·우측 액션) · body · `kx-card__foot`(선택). +- Nifty 변형: **컬러 좌측 액센트 바**(상태 카드), **KPI 타일**(수치 강조 `--fs-display`), **미디어 카드**(포스터). 그림자는 과하지 않게(hover만 약한 elevation). + +### 2.3 테이블 (`.kx-table` — Nifty "Advanced table headers") +- thead th: bg `--color-neutral-050`·`--fs-caption`·중간색(`--color-neutral-500`)·좌정렬·`border-bottom: 2px --color-neutral-200`·sticky top. +- tbody td: `--fs-body`·`--color-neutral-700`·패딩 10px 12px·`border-bottom 1px`. +- zebra(`--zebra`)·행 hover(`--color-primary-050`)·선택행(`--color-primary-100`)·숫자열 `.kx-num` 우정렬 tnum. +- 인터랙티브(정렬·필터·페이지·CSV)는 **Tabulator**로 별도(§3). + +### 2.4 드롭다운 / 셀렉트 +- 트리거(버튼) + 메뉴(카드형·radius-sm·그림자 약)·항목 hover(`--color-primary-050`)·구분선·아이콘·위험 항목(danger 색). 키보드(↑↓·Esc·Enter)·aria-expanded. + +### 2.5 리스트 그룹 (`.kx-list-group`) +- 목록형(공지·활동·검색결과): 행 = 아이콘/점 + 제목 + 메타 + 우측 배지/시간. hover·active·구분선. 링크형은 전체 행 클릭. + +### 2.6 뱃지·필·알럿·탭·프로그레스·페이지네이션·모달·툴팁·offcanvas +- **뱃지/필**: `--radius-pill`·`--fs-caption`·상태색 bg+text(위 색표). +- **알럿**: 상태색 배경(연)+좌측 액센트+아이콘+닫기. info/success/warn/danger. +- **탭/세그**: `.kx-seg`(현존) — 활성 밑줄 또는 채움. role=tablist. +- **모달/메시지박스**: 백드롭(반투명)+카드(radius-lg)+헤더/바디/푸터(액션 버튼 우측). 확인/경고 메시지박스는 아이콘+제목+본문+2버튼. focus trap·Esc. +- **offcanvas**: 우/좌 슬라이드 패널(모바일 드로어·상세 슬라이드). 백드롭·Esc·트랜지션(reduced-motion 존중). +- **프로그레스/페이지네이션**: 상태색·`--radius-pill`(bar)·현재 페이지 강조. + +## 3. Tabulator (인터랙티브 데이터 그리드) +- 도입 시: 테마 CSS를 kx 토큰으로 오버라이드(헤더=§2.3 스타일 정합)·다크 대응·한글 로케일·CSV export. 관리자/대용량 목록에 파일럿 후 확산. 정적 표는 `.kx-table` 유지. + +## 4. 적용 절차 (에이전트 지침) +1. 이 문서 + `nifty-design-refs.md` 읽기 → 대상 요소의 Nifty 패턴 파악. +2. 해당 URL을 WebFetch로 확인(구조·변형·상태) → §1 토큰으로 번역. +3. 공통 컴포넌트(`components/ui/*`·`shared.css`)에 표준 확립 → 화면별 산재 스타일 수렴(중복 제거). +4. 검증: `tsc -b --force`·`vite build` EXIT 0 + 다크/라이트 스팟 + 헤드리스 렌더 대조. + +## 변경 이력 +| 일자 | 내용 | +|---|---| +| 2026-07-12 | 최초 작성 — Nifty(BS5) → kx 토큰 매핑·컴포넌트 규격·적용 절차. 소유자 "Nifty 스타일 학습" 지시 | diff --git a/plugins/zio-harness/knowledge/kintex/docs/DEVELOPMENT_GUIDE.md b/plugins/zio-harness/knowledge/kintex/docs/DEVELOPMENT_GUIDE.md new file mode 100644 index 0000000..6a0aa8c --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/DEVELOPMENT_GUIDE.md @@ -0,0 +1,130 @@ +# 킨텍스 자동전시시스템 — 개발 표준 가이드 + +> **WISE(UIWS) 참조** — `workspace/uiws`(GUARDiA 표준 프레임워크 정본)의 백엔드/인증/보안 컨벤션을 킨텍스 스택(MyBatis·PostGIS·Redis·나노바나나 워커)에 맞춰 정리했다. +> 정본 링크: 아키텍처 표준은 Phase A `docs/architecture/*`(kintex-aa/sa/ta), API 계약은 [`_workspace/01_backend_contracts.md`](../_workspace/01_backend_contracts.md), 프로젝트 규칙은 [`CLAUDE.md`](../CLAUDE.md). + +--- + +## 1. 기술 스택 (확정 — 변경 금지) + +[`CLAUDE.md`](../CLAUDE.md) §기술 스택이 정본. 요약: + +| 레이어 | 표준 | +|--------|------| +| 프론트(웹) | React 18/19 + Vite + TypeScript (역할별 번들 분리 — PLANNING §2-1) | +| 백엔드 | Spring Boot 3.x(Java 17) + MyBatis — REST + WebSocket(STOMP) | +| DB | PostgreSQL + **PostGIS**(부스 polygon·트렌치 point·배선 LineString) | +| 비동기 | Redis 작업 큐(RenderJob·서류·알림) | +| 이미지 생성 | 나노바나나 Python 워커 사이드카(`tools/nanobanana`, google-genai) | +| AI(텍스트) | Claude 기본 + 설정형 전환(`AiTextRouter`/`AiConfig`) — 실패 시 Ollama 폴백 | +| 인증 | 행사 단위 RBAC(JWT HS256) + 2차 인증(OTP/TOTP) | + +- 패키지 루트: **`com.zioinfo.kintex`** · DB: **`kintex_db`** +- 신규 코드는 이 스택만 사용. 나노바나나 호출은 `tools/nanobanana` Python 워커만 경유(백엔드는 큐 발행·상태·콜백까지만, `GEMINI_API_KEY` 미취급). + +--- + +## 2. 패키지·레이어 구조 (백엔드) + +WISE 계층(`controller·service·repository·domain·dto`)을 MyBatis로 매핑한다. `com.zioinfo.kintex` 하위: + +``` +com.zioinfo.kintex +├── config # SecurityConfig, JwtProperties, WebSocketConfig, RedisConfig, MyBatis @MapperScan(annotationClass=Mapper.class) +├── security # JwtTokenProvider, JwtAuthenticationFilter, KintexPrincipal, RestAuthEntryPoint +├── common # response(ApiResponse·PageResponse), exception(ApiException·ErrorCode·GlobalExceptionHandler), audit(AOP) +├── auth # controller / service(AuthService·TotpService) / mapper / dto +├── module +│ ├── m2 # 플로어플랜: controller·service·mapper(BoothMapper, PostGIS ST_*)·dto·engine(ComplianceRuleEngine) +│ ├── m3 # 부스 설계: DesignMapper·precheck +│ ├── m4 # 유틸리티/배선: WiringMapper·요율 룰 +│ ├── m5 # 나노바나나 RenderJob: 큐 발행·콜백·WebSocket 푸시 +│ └── … # M10·M12·M15·M16·M18 등 (Phase D) +├── system # 시스템관리(사용자·역할/권한·공통코드·메뉴·감사로그·설정) — WISE 이식(B-2) +└── work # 공통 업무기능(worklog·schedule·message·stats·notice…) — WISE 이식(B-3) +``` + +- **레이어 규칙**: `controller`(요청 검증·RBAC 진입) → `service`(트랜잭션·룰·엔진) → `mapper`(MyBatis XML, 공간 쿼리 `ST_*`). 컨트롤러는 도메인 로직 금지, 매퍼는 비즈니스 판단 금지. +- **매퍼**: `@Mapper` 인터페이스 + `resources/mybatis/mapper/*.xml`. PostGIS 연산(`ST_MakePolygon`·`ST_Area`·`ST_Distance`·`<->` KNN)은 XML에. +- **룰셋은 코드가 아닌 데이터**: 규정(`rulesets/compliance-v1.json`)·요율(`rulesets/rates-v1.json`)은 버전 파일. 개정 시 파일 교체, 리포트에 `rulesetVersion`·`disclaimer` 항상 기록. + +### 프론트(웹) 구조 +WISE 컨벤션 `pages/components/api/store/hooks/routes`. 역할별 포털(organizer·exhibitor·contractor·ops·admin·public+visitor)은 번들 분리(PLANNING §2-1)하되 공유 디자인 시스템·공통 컴포넌트·API 계약을 상속한다. axios `baseURL=/api`. + +--- + +## 3. API·응답 규약 + +상세는 [`API_GUIDE.md`](API_GUIDE.md) 및 계약서 [`_workspace/01_backend_contracts.md`](../_workspace/01_backend_contracts.md). 핵심: + +- 응답 봉투 `ApiResponse` = `{ success, data, error }`, 목록 `PageResponse` = `{ items, page, size, total }`. +- 오류 코드(문자열)→HTTP 매핑 고정(`VALIDATION`400·`FORBIDDEN`403·`COMPLIANCE_BLOCKED`422·`NOT_IMPLEMENTED`501 …). +- 모든 도메인 경로는 `{eventId}` 스코프 + 행사 단위 RBAC 가드. + +--- + +## 4. 인증 표준 (JWT + 2FA/OTP) — WISE 이식 + +GUARDiA 표준 프레임워크 §2 + WISE `auth` 모듈을 이식한다(백로그 B-1). + +- **1차 로그인**(ID/PW) → `verifyToken` 발급 → **2차 검증**(EMAIL 인증코드 또는 OTP/TOTP) → access·refresh 토큰. +- **OTP**: TOTP RFC6238(SHA1·30초·6자리·±1윈도). `TotpService` 이식. 최초 QR 등록, 마이페이지 재설정/해제, **관리자 OTP 초기화**(`otp_secret=NULL`). 사용자별 `VERIFY_METHOD`(EMAIL/OTP)로 분기. +- **RBAC**: JWT 클레임 `roles`(eventId→역할)·`hm`(홀매니저). `/api/system/**`·`/api/admin/**` = `hasRole(ADMIN)`. 데이터 가시범위(역할 스코프)는 WISE `DataScopeService` 패턴 참조. +- **로그인 실패 잠금** + 관리자 해제. +- **admin 비밀번호**: env `ADMIN_PASSWORD_ENC`(AES-256-GCM) + 별도 키파일 복호 → 기동 시 BCrypt 재시드. **`admin123` 하드코딩 시드 금지.** + +--- + +## 5. 보안 불변 (계약 강제 — 위반 시 QA 반려) + +| 규칙 | 내용 | +|------|------| +| 자격증명 미노출 | IP·SSH·비밀번호·해시·`GEMINI_API_KEY`·`ANTHROPIC_API_KEY`·OTP 시크릿을 응답·로그·에러메시지·커밋에 절대 노출 금지 | +| 민감 필드 제외 | 사용자/업체 응답은 이름·역할·번호 등 비민감 필드만. 내부 식별자·해시 shape 제외 | +| 스택트레이스 차단 | `error.message`는 사람이 읽을 요약만. 상세는 서버 로그. `GlobalExceptionHandler`·`DataAccessException` 핸들러로 누출 차단 | +| AI 이미지 워터마크 | 나노바나나 산출 이미지 응답은 `watermarkRequired:true`+`watermarkText`+`notice`(계약·심사 서류 사용 금지) **항상** 포함 — 제거 불가 | +| 등록업체 응찰 | 장치업체(CONTRACTOR)는 킨텍스 등록업체 검증 통과분만 초대·응찰(`NOT_REGISTERED_COMPANY` 403) | +| 외부 API 금지 | 온프레미스 우선. 예외: `api.anthropic.com`(Claude, 키 env only·실패 시 Ollama 폴백) + `Gemini`(나노바나나, G1 승인 대상·워커 전용) | +| 암호화 저장 | 비밀·자격증명 AES-256-GCM. 비밀번호는 BCrypt 해시 | + +--- + +## 6. 코딩 규약 + +- **언어**: 문서·주석·커밋 본문 설명은 한국어 허용, **코드 식별자·커밋 제목·PR 제목은 영어**. +- **네이밍**: Java `camelCase`/`PascalCase`, DB 컬럼 `SNAKE_CASE`(WISE와 동일 — 예 `WRITER_ID`·`START_HOUR`), DTO 필드 `camelCase`. +- **DTO ↔ 코드그룹 매핑**은 [`COMMON_CODES.md`](COMMON_CODES.md) 표를 단일 출처로 준수(`boothType`·`myRole`·`severity` 등). +- **널/기본값**: 상태·역할 등 NOT NULL 기본값은 코드 문서 기준(예 역할 기본 `USER`/부스 상태 기본 `draft`). +- **프론트**: TypeScript strict. API 응답 타입은 계약서 shape과 1:1. 임의 `any` 지양. +- **DB 마이그레이션**: `kintex_db`는 **Flyway 순번 마이그레이션**(`V__` / 번호 규약, 백로그 B-0). 스키마가 단일 진실원천 — 엔티티/매퍼는 이를 따른다. 마이그 번호 충돌 금지(신규는 최대 번호+1). + +--- + +## 7. 브랜치·커밋·PR + +WISE 파이프라인 보호(`.githooks/pre-push`) 관행을 준용한다. + +- **브랜치**: `main`(정본) 보호. 기능은 `feat/-<요약>`, 수정은 `fix/<요약>`. 아키텍처/공통은 Phase 라벨(예 `phaseB/auth-otp`). +- **커밋 메시지**: **Conventional Commits** — `feat(m2): 플로어플랜 규정검증 API`, `fix(auth): OTP 윈도우 경계 처리`, `docs(codes): 옥션 상태 코드 추가`. 타입: `feat·fix·docs·refactor·test·chore·build·ci`. +- **push 전 게이트(권장)**: 변경분 백엔드 `compileJava` / 프론트·워커 `tsc`·lint 통과 → 실패 시 push 금지. 시크릿 파일 커밋 차단(`.env`·`*.key`·`*-firebase-adminsdk-*.json` 등은 gitignore 유지). +- **PR 규칙**: 대상 Phase/모듈 명시 · 계약서(경계면) 변경 시 frontend·db·qa 영향 기재 · 보안 불변 체크(§5) · 관련 QA 통과 링크. 아키텍처 표준(Phase A) 위반은 시정 후 병합. +- **커밋/푸시 시점**: 사용자/오케스트레이터 지시가 있을 때만. 운영 배포는 소유자 승인 필수. + +--- + +## 8. 테스트 + +- **백엔드**: 서비스·룰 엔진 단위 테스트(규정 평가·요율 산식·배선 최단경로). 공간 쿼리는 PostGIS 통합 테스트(testcontainers 또는 로컬 PostGIS). +- **경계면(계약) 검증**: `kintex-qa`가 API 응답 shape ↔ 프론트 훅/컴포넌트 호출을 교차 대조(계약서 단일 출처). 각 모듈 완성 직후 점진 검증. +- **보안 회귀**: 자격증명·PII·스택트레이스 미노출, AI 워터마크 강제, 등록업체 응찰 가드, admin env 시드를 QA 반려 사유로 상시 점검. +- **워커**: 나노바나나 모듈은 키/네트워크 없이도 import·구조 성립(목/degraded). 쿼터는 성공 시에만 차감. + +--- + +## 9. 참조 + +- 프로젝트 규칙·에이전트 워크플로: [`CLAUDE.md`](../CLAUDE.md) +- 환경 구축: [`ENV_SETUP.md`](ENV_SETUP.md) · 빌드/배포: [`BUILD_DEPLOY.md`](BUILD_DEPLOY.md) +- API 규약: [`API_GUIDE.md`](API_GUIDE.md) · 공통코드: [`COMMON_CODES.md`](COMMON_CODES.md) +- 백엔드 계약서(정본): [`_workspace/01_backend_contracts.md`](../_workspace/01_backend_contracts.md) +- 표준 프레임워크: `workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md` diff --git a/plugins/zio-harness/knowledge/kintex/docs/ENV_SETUP.md b/plugins/zio-harness/knowledge/kintex/docs/ENV_SETUP.md new file mode 100644 index 0000000..c5b9ca7 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/ENV_SETUP.md @@ -0,0 +1,127 @@ +# 킨텍스 자동전시시스템 — 개발환경 구축 가이드 + +> **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 /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 @ -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` diff --git a/plugins/zio-harness/knowledge/kintex/docs/FEATURE_BACKLOG_100.md b/plugins/zio-harness/knowledge/kintex/docs/FEATURE_BACKLOG_100.md new file mode 100644 index 0000000..ddb48b4 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/FEATURE_BACKLOG_100.md @@ -0,0 +1,432 @@ +# 전시관리 AI 시스템 — 100대 기능 백로그 (FEATURE_BACKLOG_100) + +> 작성: planner · 작성일: 2026-07-11 · 버전: v1.0 +> 성격: **개발 에이전트(kintex-impl-orchestrator 및 도메인 에이전트) 소비용 기능 백로그**. 기존 `docs/PLANNING.md`(v3.0)·`docs/design.md`·`src`는 **수정하지 않는다** — 본 문서는 신규 산출물이며 PLANNING v3.0의 모듈(M1~M18 + §5B 공통레이어 + §1A 멀티테넌시) 위에 100대 기능을 매핑·갭 분석한 것이다. +> 짝 문서: `docs/FEATURE_GAP_ANALYSIS.md`(갭 요약 + 신규 기능 구현 권고·담당 에이전트). +> **핵심 테마: "AI로 사람 작업을 최소화한다."** 100개 기능 중 55개가 AI를 직접 활용하며(§AI 자동화 맵), 각 기능마다 "없애는 수작업"을 명시했다. + +--- + +## 0. 크롤링 근거 (글로벌 전시/이벤트/MICE·베뉴 SW 기능 조사, 2026-07-11) + +> 아래는 기능 발상의 **근거 출처**다. 특정 벤더의 문구·화면을 복제하지 않고, 조사된 기능 범주를 **자기 언어로 종합**해 킨텍스 도메인(공간 데이터·나노바나나·등록업체 규정·멀티테넌시)에 맞춰 재정의했다. 저작권 자료 원문 인용/모방 없음. + +| # | 범주 | 조사 대상(대표) | 종합한 기능 시사점 | +|---|---|---|---| +| S1 | 전시/트레이드쇼 관리 | Eventleaf, Swapcard, VenueSight, vFairs, WebMobi, Engineerica | 등록·티켓·배지·리드리트리벌·부스판매/플로어·이벤트앱을 단일 워크플로로 통합 | +| S2 | 스폰서십·참가업체 포털 | EventsAir, eShow, Accelevents, Cadmium, vFairs | 스폰서/참가업체 셀프 포털(패키지·결제·이행물·매직링크 초대), 부스 재고·동적가격 | +| S3 | 현장 체크인·배지 | Bizzabo, fielddrive, Eventdex, Expo Pass, mapd | QR/키오스크 체크인, 즉석 배지 인쇄·재발급, 실시간 출입 집계, 스마트 배지 | +| S4 | AI 이벤트테크 | eventtechnology.org, EventHex, Blackthorn, PCMA/Gevme, Forrester B2B | AI 매치메이킹·콘텐츠 생성·예측 분석·챗봇·리드 스코어·추천, 디지털 트윈형 어시스턴트 | +| S5 | 베뉴/공간 관리 | Planning Pod, iVvy, Skedda, Releventful, urVenue | 실시간 가용성·동적가격·점유율·RevPAR·space booking·인보이스 | +| S6 | 실내 매핑·wayfinding | Mappedin, ArcGIS Indoors, Esri | CAD/BIM→지오공간, 블루닷 내비, POI 검색, 점유 오버레이 | +| S7 | 물류·자재 핸들링 | GES, Brick Dynamics, Fern Expo, Pure Exhibits | 반입/반출(move-in/out)·드레이지·창고 선입고·통행증·서비스 매뉴얼 주문 포털 | +| S8 | 지속가능성·연동 | Cvent, Climatiq, Salesforce Net Zero, Xero | 탄소 리포팅, API/웹훅·CRM/ERP 연동, 결제·세금 자동화 | + +- 상세 링크(대표): eventleaf.com, swapcard.com, venuesight.com, vfairs.com, eventsair.com, bizzabo.com, fielddrive.com, eventtechnology.org, mappedin.com, esri.com(ArcGIS Indoors), insights.ges.com, cvent.com, climatiq.io. +- PLANNING v3.0 §머리말이 이미 인용한 벤치마크(ExpoPlatform·RainFocus·Brella·Grip·Pointr·ExhibitForce·FindRFP·Procore·4castplus 등)와 정합 — 본 백로그는 그 위에 기능을 100개로 세분·갭화한 것이다. + +### AI 플랫폼 정합 (불변) + +모든 신규 AI 기능은 **중앙 AI 플랫폼 경유**를 원칙으로 한다(PLANNING §6·§8, GUARDiA 표준): +- **텍스트/추론**: 기본 **Claude**(`AiTextRouter`/`AiConfig`, `ANTHROPIC_API_KEY` env) → 실패 시 **Ollama**(온프레미스) 자동 폴백. LLM 직접 호출 신설 금지, 라우터 경유. +- **이미지(시공 예상)**: **나노바나나(Gemini `gemini-3.1-flash-image-preview`)** — G1 승인됨, `GEMINI_API_KEY` 서버 env only, `tools/nanobanana` 워커 경유. +- **근거·검증**: 답변은 근거(RAG)·인용 기반, **환각 차단(abstain)**, 전 생성 이미지 **워터마크**("AI 생성 예상 이미지 — 실제 시공 결과와 다를 수 있음"). +- **격리**: 전 AI 산출물·쿼터는 `tenant_id` 격리(§8-2). + +--- + +## 1. 상태·표기 범례 + +- **역할**: 주최자 / 참가(참가업체) / 장치(장치·시공업체) / 홀매니저 / 관리자 / 관람객 / 대중 +- **우선순위**: P0(핵심 차별화·MVP 필수) · P1(운영 효율 핵심) · P2(확장) +- **AI**: `Y`(AI가 산출물 직접 생성/판단) · `부분`(AI 보조·규칙+AI 혼합) · `N`(비-AI 거래·인프라, 단 AI 산출물 소비/트리거) +- **복잡도**: S(소) / M(중) / L(대) +- **모듈매핑 상태**: `이미`(PLANNING v3.0에 커버됨) · `부분`(언급되나 미상세·UI/로직 갭) · `신규`(v3.0 미포함) + +**갭 요약: 이미 63 · 부분 18 · 신규 19 / AI 활용 55 · 비-AI 45** + +--- + +## 2. 카테고리별 기능 상세 (C1~C12) + +### C1. 판매·홀배정·견적 (7) — M1 · M16-1 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과(없애는 수작업) | +|---|---|---|---|---|---|---|---| +| F001 | 가용성 실시간 캘린더 | 주최자·관리자 | P1 | N | M | M1·**부분** | 문의·전화 가용성 확인 → 실시간 홀/반홀 조회 | +| F002 | 규칙기반 자동 견적 엔진 | 주최자 | P1 | 부분 | M | M1·이미 | 견적 협의 수일 → 즉시 자동 견적(요율·성수기 규칙) | +| F003 | 수율·동적가격 시뮬레이션 | 관리자 | P2 | Y | M | M16-1⑥·이미 | 수기 가격정책 → AI 수율 최적가 제안 | +| F004 | 배정신청 웹폼→HWP 자동생성 | 주최자 | P1 | N | S | M1·이미 | HWP 배정신청서 수기작성 → 자동 서식 생성 | +| F005 | 부스 판매 인벤토리 관리 | 주최자 | P1 | N | M | —·**신규** | 엑셀 부스 현황 관리 → 부스 단위 판매/홀드/예약 상태 | +| F006 | 온라인 부스 셀프 선택·판매 | 참가 | P1 | N | M | —·**신규** | 사무국 수기 배정 → 인터랙티브 맵 셀프 선택·결제 | +| F007 | 임대계약 전자서명 워크플로 | 주최자·관리자 | P2 | N | M | —·**신규** | 공문·종이 계약 → 전자서명 체결(Phase3, PLANNING Non-goal 완화) | + +### C2. 설계·시각화 코어 (13) — M2 · M3 · M4 · M5 (P0 심장·불변) + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F008 | 부스 배치 3안 자동생성 | 주최자 | P0 | Y | L | M2·이미 | CAD 배치도 수작업 수일 → 조건 입력 후 수분·3안 | +| F009 | 배치안 선택/병합 편집 | 주최자 | P0 | 부분 | L | M2·이미 | 수동 재작도 → 안별 레이어 토글·병합 | +| F010 | 배치 규정 자동검증 | 주최자·홀매니저 | P0 | Y | M | M2·이미 | 육안 검수 → 통로·바닥하중·비상구 자동 플래깅 | +| F011 | 독립부스 설계 3안 자동생성 | 참가·장치 | P0 | Y | L | M3·이미 | 도면 처음부터 작성 → AI 레이아웃/구조 3안 초안 | +| F012 | 조립부스 옵션 선택·3D 프리뷰 | 참가 | P0 | 부분 | M | M3·**부분**(B-01) | 옵션 신청서 종이작성 → 웹 선택·즉시 프리뷰 | +| F013 | 설계 규정 사전검증(높이·방염·리깅) | 장치 | P0 | Y | M | M3·이미 | 제출 후 반려 재작업 → 제출 전 자동 검증 | +| F014 | 도면 업로드 비전 추출·검증 | 장치 | P1 | Y | L | M3·이미 | 도면 수동 대조 → 비전 모델 치수·구조 추출 검증 | +| F015 | 전기 용량·분전반 자동산출 | 참가 | P0 | Y | M | M4a·이미 | 필요 kW 추정 → 기기목록→kW→분전반 자동 산출 | +| F016 | 배선 경로 자동생성(PostGIS 최단) | 참가 | P0 | Y | L | M4·이미 | 배선 감 설계 → 트렌치→분전반 최단 경로 자동 | +| F017 | 유틸리티 위치표시도 자동생성 | 참가 | P0 | Y | M | M4b·이미 | 위치표시도 수기 작도 → 좌표 클릭 자동 생성 | +| F018 | 조명 조도 배치안 제안 | 참가·장치 | P1 | Y | M | M4a·**부분**(B-10) | 조명 감 배치 → 조도목표별 배치안 제안 | +| F019 | 나노바나나 시공 예상 사진(S1~S7) | 참가·주최자 | P0 | Y | L | M5·이미 | 조감도 외주(배선·조명 미반영) → 시공 후 예상 사진 | +| F020 | Before/After 비교 뷰 | 참가 | P0 | Y | S | §6-5·이미 | 개장일 첫 확인 → 빈부스↔시공후 사전 비교 | + +### C3. 서류·규정·워크플로 (8) — M6 · §5B + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F021 | 마일스톤 자동생성·역산 알림 | 주최자·홀매니저 | P1 | N | M | M6·이미 | 수첩 마감관리 → D-150/30/25/7 자동 역산 알림 | +| F022 | 신고서류 웹폼→HWP/PDF 자동생성 | 주최자 | P1 | 부분 | M | M6·이미 | 서류 7종 HWP 수기 → 웹폼 입력·AI 자동 채움·서식 생성 | +| F023 | AI 서류 검수(누락·불일치) | 홀매니저 | P1 | Y | M | M6·이미 | 육안 검수 병목 → 누락·배치도-계획서 불일치 자동 검출 | +| F024 | 리깅 구조계산서 사전 체크 | 장치 | P2 | 부분 | M | M3·**부분**(Ph3) | 반려 리스크 → 필수 항목·누락 자동 체크(판정은 기술사) | +| F025 | 규정 자연어 챗봇 | 참가·장치 | P2 | Y | M | §5·**부분** | 매뉴얼 검색 → 대화형 규정 질의(근거·인용) | +| F026 | OCR 문서 자동등록(계약·납품) | 관리자·주최자 | P1 | Y | M | —·**신규** | 계약·납품서 수기 입력 → OCR 파싱 자동 등록 | +| F027 | kxwp 제출 파일 릴레이·안내 | 주최자·장치 | P1 | N | M | M6·이미(R3) | 이중 입력 → 제출용 파일 자동 생성·업로드 안내 | +| F028 | 서류 버전·전자결재 워크플로 | 주최자·홀매니저 | P1 | N | M | §5B·**부분** | 이메일 결재 → 다단계 전자결재·버전 이력 | + +### C4. 공사·장치 옥션·발주 (8) — M15 · M7 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F029 | 역경매 옥션 개설·라운드·마감 | 참가·주최자 | P1 | N | L | M15·이미 | 업체 개별 접촉 견적 → 경쟁 응찰 옥션 | +| F030 | AI 자료 기반 응찰(견적서 제출) | 장치 | P1 | 부분 | M | M15·이미 | 수기 견적 산정 → AI 자료(배치·물량·이미지) 근거 견적서 | +| F031 | 실시간 순위·익명 노출 | 장치·참가 | P1 | N | M | M15·이미 | 불투명 취합 → 실시간 순위·내 위치 노출 | +| F032 | 종합평가 낙찰 스코어(가격+평판+납기) | 주최자·참가 | P1 | 부분 | M | M15·이미 | 감·인맥 선정 → 가중 스코어 비교표 | +| F033 | 등록업체 검증 게이트(응찰 자격) | 관리자·주최자 | P1 | N | S | M15·M7·이미 | 수기 자격 확인 → 미등록 업체 응찰 원천 차단 | +| F034 | 등록업체 AI 매칭 추천 | 참가 | P1 | Y | M | M7·이미 | 739개 엑셀 리스트 뒤짐 → 규모·업종·지역 추천 | +| F035 | 물량서(BOQ) 자동산출 | 장치·참가 | P1 | Y | M | M4·M15·**부분** | 수기 물량 산출 → 설계 기반 자동 BOQ | +| F036 | 낙찰→계약·발주 자동전환 | 주최자·관리자 | P1 | N | M | M15·이미 | 계약서 재작성 → 낙찰 견적서 계약/발주 문서 전환 | + +### C5. 참가업체 서비스·물류 (8) — M8 · 참가업체 포털 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F037 | 참가업체 통합 서비스 포털 | 참가 | P1 | N | M | §2-1·**부분** | 행사별 파편화 신청 → 단일 통합 창구 | +| F038 | 유틸리티 원클릭 신청·마감 리마인더 | 참가 | P0 | N | M | M4b·이미 | 마감(D-25) 누락(구제 불가) → 역산 알림·원클릭 | +| F039 | 반입/반출 슬롯 예약 | 장치·참가 | P2 | N | M | M8·이미 | 현장 대기열 → 하역장 슬롯 예약제 | +| F040 | 통행증 QR 발급·중량물 우선배치 | 장치 | P2 | 부분 | M | M8·이미 | 순번제 대기 → QR 통행증·중량물 자동 우선 | +| F041 | 지게차·부대장비 신청 연동 | 장치 | P2 | N | S | M8·**부분** | 지정업체 별도 신청 → 통합 신청 | +| F042 | 부대물품(가구·집기) 렌탈 주문 | 참가 | P2 | N | S | —·**신규** | 개별 발주 → 카탈로그 렌탈 주문 | +| F043 | 배송·창고 선입고 트래킹 | 장치·참가 | P2 | N | M | —·**신규** | 화물 위치 불명 → 선입고·입고 트래킹(드레이지) | +| F044 | 철거 피크 대기열 시뮬레이션 | 홀매니저 | P2 | Y | M | M8·이미 | 철거일 현장 혼잡 → 대기열 예측 시뮬레이션 | + +### C6. 관람객 등록·배지·체크인·리드 (10) — M10 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F045 | 온라인 사전등록(유형별 폼) | 관람객 | P1 | 부분 | M | M10·이미 | 현장 등록 대기 → 온라인 사전등록·중복 검증 | +| F046 | AI 폼빌더(등록 폼 자동구성) | 주최자 | P2 | Y | S | —·**신규** | 폼 수동 제작 → 목적 입력→AI 폼 생성 | +| F047 | 모바일 배지/QR 발급 | 관람객 | P1 | N | S | M10·이미 | 종이 배지 → 모바일 배지/QR | +| F048 | 현장 QR 체크인·즉석 배지 인쇄 | 관람객·홀매니저 | P1 | N | M | M10·이미 | 수기 명부 → QR 체크인·즉석 인쇄 | +| F049 | 오프라인 체크인 폴백 | 홀매니저 | P1 | N | M | M10·이미 | 네트워크 장애 시 마비 → 오프라인 대비 동기화 | +| F050 | 리드캡처(배지 스캔·관심도·메모) | 참가 | P1 | N | M | M10·이미 | 명함 수기 수집 → QR 스캔·관심도·메모 | +| F051 | AI 리드 스코어링·자동 분류 | 참가 | P1 | Y | M | —·**신규** | 수기 등급 판단 → 행동·프로필 기반 AI 스코어 | +| F052 | 리드 팔로업 EDM 자동 | 참가 | P1 | Y | M | M10·M12·**부분** | 수동 팔로업 발송 → 리드 세그먼트 자동 EDM | +| F053 | 티켓 발권·유료 등록 결제 | 관람객·주최자 | P2 | N | M | M10·M9·**부분** | 현장 결제 → 온라인 발권·PG | +| F054 | 스마트 배지·웨어러블 연동 | 관람객 | P2 | N | L | —·**신규** | 수동 상호작용 → 탭 인터랙션·자동 참여 기록 | + +### C7. 비즈매칭·네트워킹·이벤트앱 (8) — M11 · 이벤트앱 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F055 | AI 비즈매칭 추천(프로필·intent) | 관람객·참가 | P2 | Y | L | M11·이미 | 주최자 개별 주선 → 프로필·의향 AI 매치 | +| F056 | 미팅 슬롯 예약·일정관리 | 관람객·참가 | P2 | N | M | M11·이미 | 수기 미팅 조율 → 슬롯 예약·캘린더 | +| F057 | 이벤트 모바일앱(일정·부스·프로필) | 관람객 | P1 | N | M | §2-1·**부분** | 종이 안내책자 → 모바일앱 통합 | +| F058 | 세션·아젠다 관리·개인 일정 | 관람객·주최자 | P2 | 부분 | M | —·**신규** | 수기 아젠다 → 개인화 세션 일정 | +| F059 | AI 세션·부스 추천 | 관람객 | P2 | Y | M | —·**신규** | 무작위 탐색 → 관심 기반 개인화 추천 | +| F060 | 인앱 채팅·네트워킹 | 관람객·참가 | P2 | N | M | —·**신규** | 오프라인 접촉만 → 인앱 채팅·명함 교환 | +| F061 | 실시간 설문·투표·Q&A | 관람객·주최자 | P2 | N | S | —·**신규** | 종이 설문 수거 → 실시간 인터랙션·집계 | +| F062 | 매칭 성과 리포트 | 참가·주최자 | P2 | Y | S | M11·M16·**부분** | 성과 미측정 → 미팅·연결 성과 리포트 | + +### C8. 마케팅·EDM·공개사이트·스폰서십 (9) — M12 · M17 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F063 | 공개 홍보 사이트(SEO·다국어) | 대중 | P1 | 부분 | M | M12·이미 | 정적 정보 페이지 → SEO·다국어(한/영/중/일) | +| F064 | 공개 인터랙티브 플로어플랜 | 대중·관람객 | P1 | N | M | M12·이미 | 정적 지도 이미지 → 인터랙티브 플로어플랜 | +| F065 | 세그먼트 EDM·캠페인 자동화 | 주최자 | P1 | Y | M | M12·이미 | 일괄 수동 발송 → 세그먼트별 캠페인·리마인더 | +| F066 | AI 카피·이미지 초안 생성 | 주최자 | P1 | Y | M | M12·이미 | 카피 수작성 → AI 카피·나노바나나 이미지 초안 | +| F067 | 참가업체 마이크로사이트 | 참가 | P1 | 부분 | M | M17·이미 | 개념 부재 → 부스·제품·예상샷 마이크로사이트 | +| F068 | CMS 콘텐츠·공지·게시 워크플로 | 주최자·관리자 | P1 | 부분 | M | M17·이미 | 정적 관리 → 초안→검수→게시 워크플로·버전 | +| F069 | 다국어 콘텐츠 자동 번역 | 관리자 | P1 | Y | M | M17·이미 | 수동 번역 → AI 번역+검수(한/영/중/일) | +| F070 | 스폰서십 패키지·판매·이행 관리 | 주최자 | P1 | N | M | —·**신규** | 스폰서 수기 관리 → 패키지·티어·이행물 판매 관리 | +| F071 | 스폰서 대시보드(노출·리드·ROI) | 주최자·참가 | P2 | 부분 | M | —·**신규** | 성과 미제공 → 노출·리드·ROI 대시보드 | + +### C9. 현장운영·wayfinding·안전 (8) — M13 · M14 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F072 | 실내 wayfinding(블루닷/존레벨) | 관람객 | P2 | N | L | M13·이미 | 길찾기 난이도(100m 무빙워크) → 실내 내비 | +| F073 | 시설 POI 검색·경로안내 | 관람객 | P2 | N | M | M13·이미 | 안내 데스크 문의 → 부스·화장실·비상구 검색 경로 | +| F074 | 실시간 입장·혼잡 모니터·예측 | 홀매니저 | P2 | Y | M | M14·이미 | 수기 통제 → 실시간 혼잡 + 오버플로 예측 | +| F075 | 홀 전력 부하 집계·에너지 모니터 | 홀매니저 | P2 | 부분 | M | M14·이미 | 소음·전력 수기 차단 → 홀 단위 부하 집계·이상 | +| F076 | 안전 위반 신고·소음·금지작업 플래그 | 홀매니저 | P2 | Y | M | M14·이미 | 육안 사후 적발 → 위반 자동 플래그·신고 | +| F077 | 주차 점유 연동(iparking) | 관람객·홀매니저 | P2 | N | S | M14·이미 | 주차 별도 안내 → 점유 실시간 연동 | +| F078 | 디지털 사이니지 콘텐츠 배포 | 관리자·홀매니저 | P2 | N | M | M17·**부분** | 수동 게시 → 중앙 사이니지 콘텐츠 배포 | +| F079 | 현장 이상탐지·자동 알림 | 홀매니저 | P2 | Y | M | —·**신규** | 사후 적발 → 이상 패턴 탐지·즉시 알림 | + +### C10. 정산·결제·재무 (6) — M9 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F080 | 납부 스케줄 자동생성·알림 | 주최자 | P1 | N | M | M9·이미 | 계약금/중도금/잔금 수동 관리 → 자동 스케줄·알림 | +| F081 | 유틸리티·부대 PG 결제 | 참가 | P1 | N | M | M9·이미 | 현장 정산 → 온라인 PG 결제 | +| F082 | 예치금 대비 실사용 정산 투명화 | 주최자·관리자 | P1 | 부분 | M | M9·이미 | 불투명 정산 → 검침·실사용 대비 내역 투명화 | +| F083 | 세금계산서·정산 리포트 자동 | 관리자 | P1 | N | M | M9·**부분** | 수기 발행 → 세금계산서·정산 리포트 자동 | +| F084 | 옥션 수수료·매출 정산 연동 | 관리자 | P2 | N | S | M9·M15·**부분** | 별도 관리 → 옥션 수수료·매출 정산 연동 | +| F085 | 환불·취소 규정 자동 적용 | 주최자·관리자 | P2 | N | S | —·**신규** | 수기 환불 처리 → 취소 규정 자동 적용 | + +### C11. 경영분석 BI·예측 (8) — M16 + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F086 | 홀·기간별 가동률 대시보드 | 관리자 | P1 | N | M | M16-1①·이미 | 수기 집계 → 점유/공실 가동률 대시보드 | +| F087 | 매출 구성·행사별 P&L | 관리자 | P1 | 부분 | M | M16-1②③·이미 | 산재 데이터 수집 → 매출 mix·행사별 P&L | +| F088 | 전시장 ROI·RevPAD·㎡당 수익 | 관리자 | P1 | 부분 | M | M16-1④·이미 | 미측정 → ㎡ 정규화 생산성 지표 | +| F089 | 참가사 리텐션·LTV 코호트 | 관리자 | P1 | Y | M | M16-1⑤·이미 | 미분석 → 재참가율·LTV 코호트 | +| F090 | 수요예측·성수기 예측 | 관리자 | P1 | Y | M | M16-1⑥·이미 | 감 예측 → 홀별·시즌 수요 AI 예측 | +| F091 | 참가업체 ROI(리드 기반) | 참가 | P1 | 부분 | M | M16·이미 | 부스 성과 미측정 → 리드 수·품질 대비 ROI | +| F092 | 자연어 조회(Text-to-SQL) | 관리자 | P2 | Y | M | —·**신규** | SQL/BI 전문 필요 → 자연어 질의 조회 | +| F093 | 경영진 KPI·AI 인사이트 브리핑 | 관리자 | P1 | Y | M | M16-1⑦·**부분** | 수동 보고서 작성 → KPI 요약·AI 브리핑 자동 | + +### C12. 플랫폼·AI·관리·연동 (7) — M18 · §5B · §1A + +| 번호 | 기능명 | 역할 | P | AI | 복잡 | 모듈·상태 | AI 자동화 효과 | +|---|---|---|---|---|---|---|---| +| F094 | RBAC·감사로그·시스템설정 백오피스 | 관리자 | P1 | N | M | M18·§5B-1·이미 | 데이터·권한 통제 부재 → RBAC·감사·설정 | +| F095 | 룰셋·마스터데이터 버전관리 | 관리자 | P1 | N | M | M18·이미 | 규정·요율 코드 하드코딩 → 버전 룰셋 무중단 개정 | +| F096 | 멀티테넌트 격리·전시관 온보딩 | 관리자 | P1 | N | L | §1A·§8-2·이미 | 킨텍스 전용 → 다중 전시관 격리·데이터 온보딩 | +| F097 | JWT+2FA(OTP)·로그인 실패잠금 | 전역 | P1 | N | M | §5B-3·이미 | 단순 로그인 → JWT+TOTP 2FA·실패잠금 | +| F098 | 공통 업무모듈(일정·쪽지·공지·회의록·보고) | 전역 | P1 | 부분 | M | §5B-2·이미 | 협업 도구 산재 → 통합 업무 레이어(회의록 AI·보고 자동) | +| F099 | API·웹훅·CRM 연동 게이트웨이 | 관리자 | P2 | N | M | —·**신규** | 수기 데이터 연계 → API/웹훅·CRM/ERP 연동 | +| F100 | AI 플랫폼 라우터(Claude·나노바나나·Ollama 폴백) | 관리자 | P1 | Y | M | §6·**부분** | 분산 LLM 호출 → 중앙 라우터·근거·워터마크·환각차단 | + +--- + +## 3. AI 자동화 맵 — "없앤 수작업" 목록 + +> **핵심 성과 지표: 100개 기능 중 55개가 AI 직접 활용(Y 33 + 부분 22 = 55%), 45개는 AI 산출물을 소비·트리거하는 거래·인프라 기능.** 아래는 AI가 대체·제거하는 수작업을 영역별로 집약한 것이다. + +| AI 자동화 영역 | 대표 기능 | 없애는 수작업 | 절감 정도(정성) | +|---|---|---|---| +| **설계 자동생성(3안)** | F008·F009·F011 | 배치도·부스 도면 CAD 수작업 | 수일~수주 → 수분 | +| **규정·서류 자동검수** | F010·F013·F023·F024 | 육안 검수·반려 재작업 | 검수 병목 제거, 반려 사전 차단 | +| **견적·물량 자동산출** | F002·F015·F016·F035 | 용량 추정·수기 배선·물량 산정 | 추정 오류·현장 증설 리스크 제거 | +| **위치표시도 자동화** | F017 | 유틸리티 위치표시도 수기 작도 | 작도 폐지 | +| **시공 예상 이미지(나노바나나)** | F019·F020·F066 | 조감도 외주(배선·조명 미반영) | 개장일 첫 확인 → 사전 사진 | +| **리드 자동 스코어·매칭** | F034·F051·F055·F059 | 명함 수기 분류·수동 매칭 | 등급 판단·주선 자동화 | +| **동선·혼잡·수요 예측** | F044·F074·F090 | 현장 감·수기 예측 | 오버플로/철거 혼잡 예측 | +| **콘텐츠·번역·EDM 자동초안** | F022·F052·F065·F069 | 카피·번역·서식 수작성 | 초안 자동 생성(사람 검수만) | +| **자연어 조회·경영 브리핑** | F092·F093 | SQL/BI 전문 조회·보고서 작성 | 자연어 질의·자동 브리핑 | +| **문서 OCR 자동등록** | F026 | 계약·납품서 수기 입력 | 자동 파싱 등록 | +| **규정 상담 챗봇** | F025 | 매뉴얼 검색 | 대화형 근거 질의 | +| **이상탐지·안전 플래그** | F076·F079 | 육안 사후 적발 | 실시간 이상 탐지 알림 | + +**AI 활용 기능(55) 전체 번호**: F002·F003·F008·F009·F010·F011·F012·F013·F014·F015·F016·F017·F018·F019·F020·F022·F023·F024·F025·F026·F030·F032·F034·F035·F040·F044·F045·F046·F051·F052·F055·F058·F059·F062·F063·F065·F066·F067·F068·F069·F071·F074·F075·F076·F079·F082·F087·F088·F089·F090·F091·F092·F093·F098·F100. + +--- + +## 4. 전체 요약표 (100대 기능 인덱스) + +| 번호 | 기능 | 카테고리 | 역할 | P | AI | 모듈매핑 | 상태 | +|---|---|---|---|---|---|---|---| +| F001 | 가용성 실시간 캘린더 | C1 판매 | 주최자·관리자 | P1 | N | M1 | 부분 | +| F002 | 규칙기반 자동 견적 | C1 판매 | 주최자 | P1 | 부분 | M1 | 이미 | +| F003 | 수율·동적가격 시뮬레이션 | C1 판매 | 관리자 | P2 | Y | M16-1 | 이미 | +| F004 | 배정신청 웹폼→HWP 자동 | C1 판매 | 주최자 | P1 | N | M1 | 이미 | +| F005 | 부스 판매 인벤토리 | C1 판매 | 주최자 | P1 | N | M1/M2 | 신규 | +| F006 | 온라인 부스 셀프 판매 | C1 판매 | 참가 | P1 | N | M2 | 신규 | +| F007 | 임대계약 전자서명 | C1 판매 | 주최자·관리자 | P2 | N | M6/M9 | 신규 | +| F008 | 부스 배치 3안 자동생성 | C2 코어 | 주최자 | P0 | Y | M2 | 이미 | +| F009 | 배치안 선택/병합 | C2 코어 | 주최자 | P0 | 부분 | M2 | 이미 | +| F010 | 배치 규정 자동검증 | C2 코어 | 주최자·홀매니저 | P0 | Y | M2 | 이미 | +| F011 | 독립부스 설계 3안 | C2 코어 | 참가·장치 | P0 | Y | M3 | 이미 | +| F012 | 조립부스 옵션·3D 프리뷰 | C2 코어 | 참가 | P0 | 부분 | M3 | 부분 | +| F013 | 설계 규정 사전검증 | C2 코어 | 장치 | P0 | Y | M3 | 이미 | +| F014 | 도면 비전 추출·검증 | C2 코어 | 장치 | P1 | Y | M3 | 이미 | +| F015 | 전기 용량·분전반 자동산출 | C2 코어 | 참가 | P0 | Y | M4a | 이미 | +| F016 | 배선 경로 자동생성 | C2 코어 | 참가 | P0 | Y | M4 | 이미 | +| F017 | 위치표시도 자동생성 | C2 코어 | 참가 | P0 | Y | M4b | 이미 | +| F018 | 조명 조도 배치안 제안 | C2 코어 | 참가·장치 | P1 | Y | M4a | 부분 | +| F019 | 나노바나나 시공 예상 사진 | C2 코어 | 참가·주최자 | P0 | Y | M5 | 이미 | +| F020 | Before/After 비교 뷰 | C2 코어 | 참가 | P0 | Y | M5/§6 | 이미 | +| F021 | 마일스톤 자동생성·알림 | C3 서류 | 주최자·홀매니저 | P1 | N | M6 | 이미 | +| F022 | 신고서류 웹폼→HWP 자동 | C3 서류 | 주최자 | P1 | 부분 | M6 | 이미 | +| F023 | AI 서류 검수 | C3 서류 | 홀매니저 | P1 | Y | M6 | 이미 | +| F024 | 리깅 구조계산서 사전체크 | C3 서류 | 장치 | P2 | 부분 | M3 | 부분 | +| F025 | 규정 자연어 챗봇 | C3 서류 | 참가·장치 | P2 | Y | §5/AI | 부분 | +| F026 | OCR 문서 자동등록 | C3 서류 | 관리자·주최자 | P1 | Y | 신규/AI | 신규 | +| F027 | kxwp 제출 파일 릴레이 | C3 서류 | 주최자·장치 | P1 | N | M6 | 이미 | +| F028 | 서류 버전·전자결재 | C3 서류 | 주최자·홀매니저 | P1 | N | §5B | 부분 | +| F029 | 역경매 옥션 개설 | C4 옥션 | 참가·주최자 | P1 | N | M15 | 이미 | +| F030 | AI 자료 기반 응찰 | C4 옥션 | 장치 | P1 | 부분 | M15 | 이미 | +| F031 | 실시간 순위·익명 | C4 옥션 | 장치·참가 | P1 | N | M15 | 이미 | +| F032 | 종합평가 낙찰 스코어 | C4 옥션 | 주최자·참가 | P1 | 부분 | M15 | 이미 | +| F033 | 등록업체 검증 게이트 | C4 옥션 | 관리자·주최자 | P1 | N | M15/M7 | 이미 | +| F034 | 등록업체 AI 매칭 추천 | C4 옥션 | 참가 | P1 | Y | M7 | 이미 | +| F035 | 물량서(BOQ) 자동산출 | C4 옥션 | 장치·참가 | P1 | Y | M4/M15 | 부분 | +| F036 | 낙찰→계약·발주 전환 | C4 옥션 | 주최자·관리자 | P1 | N | M15 | 이미 | +| F037 | 참가업체 통합 서비스 포털 | C5 물류 | 참가 | P1 | N | §2-1 | 부분 | +| F038 | 유틸리티 원클릭·리마인더 | C5 물류 | 참가 | P0 | N | M4b | 이미 | +| F039 | 반입/반출 슬롯 예약 | C5 물류 | 장치·참가 | P2 | N | M8 | 이미 | +| F040 | 통행증 QR·중량물 우선 | C5 물류 | 장치 | P2 | 부분 | M8 | 이미 | +| F041 | 지게차·부대장비 신청 | C5 물류 | 장치 | P2 | N | M8 | 부분 | +| F042 | 부대물품 렌탈 주문 | C5 물류 | 참가 | P2 | N | 신규 | 신규 | +| F043 | 배송·창고 선입고 트래킹 | C5 물류 | 장치·참가 | P2 | N | 신규 | 신규 | +| F044 | 철거 대기열 시뮬레이션 | C5 물류 | 홀매니저 | P2 | Y | M8 | 이미 | +| F045 | 온라인 사전등록 | C6 관람객 | 관람객 | P1 | 부분 | M10 | 이미 | +| F046 | AI 폼빌더 | C6 관람객 | 주최자 | P2 | Y | 신규/AI | 신규 | +| F047 | 모바일 배지/QR | C6 관람객 | 관람객 | P1 | N | M10 | 이미 | +| F048 | 현장 QR 체크인·즉석 인쇄 | C6 관람객 | 관람객·홀매니저 | P1 | N | M10 | 이미 | +| F049 | 오프라인 체크인 폴백 | C6 관람객 | 홀매니저 | P1 | N | M10 | 이미 | +| F050 | 리드캡처 | C6 관람객 | 참가 | P1 | N | M10 | 이미 | +| F051 | AI 리드 스코어링 | C6 관람객 | 참가 | P1 | Y | 신규/AI | 신규 | +| F052 | 리드 팔로업 EDM 자동 | C6 관람객 | 참가 | P1 | Y | M10/M12 | 부분 | +| F053 | 티켓 발권·유료 결제 | C6 관람객 | 관람객·주최자 | P2 | N | M10/M9 | 부분 | +| F054 | 스마트 배지·웨어러블 | C6 관람객 | 관람객 | P2 | N | 신규 | 신규 | +| F055 | AI 비즈매칭 추천 | C7 매칭 | 관람객·참가 | P2 | Y | M11 | 이미 | +| F056 | 미팅 슬롯 예약 | C7 매칭 | 관람객·참가 | P2 | N | M11 | 이미 | +| F057 | 이벤트 모바일앱 | C7 매칭 | 관람객 | P1 | N | §2-1 | 부분 | +| F058 | 세션·아젠다 관리 | C7 매칭 | 관람객·주최자 | P2 | 부분 | 신규 | 신규 | +| F059 | AI 세션·부스 추천 | C7 매칭 | 관람객 | P2 | Y | 신규/AI | 신규 | +| F060 | 인앱 채팅·네트워킹 | C7 매칭 | 관람객·참가 | P2 | N | 신규 | 신규 | +| F061 | 실시간 설문·투표·Q&A | C7 매칭 | 관람객·주최자 | P2 | N | 신규 | 신규 | +| F062 | 매칭 성과 리포트 | C7 매칭 | 참가·주최자 | P2 | Y | M11/M16 | 부분 | +| F063 | 공개 홍보 사이트 SEO·다국어 | C8 마케팅 | 대중 | P1 | 부분 | M12 | 이미 | +| F064 | 공개 인터랙티브 플로어플랜 | C8 마케팅 | 대중·관람객 | P1 | N | M12 | 이미 | +| F065 | 세그먼트 EDM·캠페인 자동화 | C8 마케팅 | 주최자 | P1 | Y | M12 | 이미 | +| F066 | AI 카피·이미지 초안 | C8 마케팅 | 주최자 | P1 | Y | M12 | 이미 | +| F067 | 참가업체 마이크로사이트 | C8 마케팅 | 참가 | P1 | 부분 | M17 | 이미 | +| F068 | CMS 콘텐츠·게시 워크플로 | C8 마케팅 | 주최자·관리자 | P1 | 부분 | M17 | 이미 | +| F069 | 다국어 콘텐츠 자동 번역 | C8 마케팅 | 관리자 | P1 | Y | M17 | 이미 | +| F070 | 스폰서십 패키지·판매 관리 | C8 마케팅 | 주최자 | P1 | N | 신규 | 신규 | +| F071 | 스폰서 대시보드 | C8 마케팅 | 주최자·참가 | P2 | 부분 | 신규/M16 | 신규 | +| F072 | 실내 wayfinding | C9 현장 | 관람객 | P2 | N | M13 | 이미 | +| F073 | 시설 POI 검색·경로 | C9 현장 | 관람객 | P2 | N | M13 | 이미 | +| F074 | 실시간 혼잡 모니터·예측 | C9 현장 | 홀매니저 | P2 | Y | M14 | 이미 | +| F075 | 홀 전력 부하·에너지 | C9 현장 | 홀매니저 | P2 | 부분 | M14 | 이미 | +| F076 | 안전 위반·소음 플래그 | C9 현장 | 홀매니저 | P2 | Y | M14 | 이미 | +| F077 | 주차 점유 연동 | C9 현장 | 관람객·홀매니저 | P2 | N | M14 | 이미 | +| F078 | 디지털 사이니지 배포 | C9 현장 | 관리자·홀매니저 | P2 | N | M17 | 부분 | +| F079 | 현장 이상탐지·알림 | C9 현장 | 홀매니저 | P2 | Y | 신규/AI | 신규 | +| F080 | 납부 스케줄 자동생성 | C10 정산 | 주최자 | P1 | N | M9 | 이미 | +| F081 | 유틸리티·부대 PG 결제 | C10 정산 | 참가 | P1 | N | M9 | 이미 | +| F082 | 예치금 실사용 정산 투명화 | C10 정산 | 주최자·관리자 | P1 | 부분 | M9 | 이미 | +| F083 | 세금계산서·정산 리포트 | C10 정산 | 관리자 | P1 | N | M9 | 부분 | +| F084 | 옥션 수수료·매출 정산 | C10 정산 | 관리자 | P2 | N | M9/M15 | 부분 | +| F085 | 환불·취소 규정 자동 | C10 정산 | 주최자·관리자 | P2 | N | 신규 | 신규 | +| F086 | 홀·기간별 가동률 | C11 BI | 관리자 | P1 | N | M16-1① | 이미 | +| F087 | 매출 구성·행사별 P&L | C11 BI | 관리자 | P1 | 부분 | M16-1②③ | 이미 | +| F088 | 전시장 ROI·RevPAD·㎡수익 | C11 BI | 관리자 | P1 | 부분 | M16-1④ | 이미 | +| F089 | 참가사 리텐션·LTV | C11 BI | 관리자 | P1 | Y | M16-1⑤ | 이미 | +| F090 | 수요예측·성수기 예측 | C11 BI | 관리자 | P1 | Y | M16-1⑥ | 이미 | +| F091 | 참가업체 ROI(리드) | C11 BI | 참가 | P1 | 부분 | M16 | 이미 | +| F092 | 자연어 조회 Text-to-SQL | C11 BI | 관리자 | P2 | Y | 신규/AI | 신규 | +| F093 | 경영진 KPI·AI 브리핑 | C11 BI | 관리자 | P1 | Y | M16-1⑦ | 부분 | +| F094 | RBAC·감사·시스템설정 | C12 플랫폼 | 관리자 | P1 | N | M18/§5B-1 | 이미 | +| F095 | 룰셋·마스터 버전관리 | C12 플랫폼 | 관리자 | P1 | N | M18 | 이미 | +| F096 | 멀티테넌트·전시관 온보딩 | C12 플랫폼 | 관리자 | P1 | N | §1A/§8-2 | 이미 | +| F097 | JWT+2FA(OTP)·실패잠금 | C12 플랫폼 | 전역 | P1 | N | §5B-3 | 이미 | +| F098 | 공통 업무모듈 | C12 플랫폼 | 전역 | P1 | 부분 | §5B-2 | 이미 | +| F099 | API·웹훅·CRM 게이트웨이 | C12 플랫폼 | 관리자 | P2 | N | 신규 | 신규 | +| F100 | AI 플랫폼 라우터 | C12 플랫폼 | 관리자 | P1 | Y | §6/AI | 부분 | + +--- + +## 5. 카테고리별 집계 + +| 카테고리 | 기능 수 | 이미 | 부분 | 신규 | AI 활용 | +|---|---|---|---|---|---| +| C1 판매·홀배정·견적 | 7 | 4 | 1 | 2 | 2 | +| C2 설계·시각화 코어 | 13 | 11 | 2 | 0 | 12 | +| C3 서류·규정·워크플로 | 8 | 4 | 3 | 1 | 5 | +| C4 공사·장치 옥션·발주 | 8 | 6 | 1 | 1 | 3 | +| C5 참가업체 서비스·물류 | 8 | 4 | 2 | 2 | 2 | +| C6 관람객 등록·배지·리드 | 10 | 6 | 1 | 3 | 4 | +| C7 비즈매칭·네트워킹·앱 | 8 | 2 | 2 | 4 | 4 | +| C8 마케팅·EDM·공개·스폰서 | 9 | 7 | 0 | 2 | 6 | +| C9 현장운영·wayfinding·안전 | 8 | 6 | 1 | 1 | 4 | +| C10 정산·결제·재무 | 6 | 3 | 2 | 1 | 1 | +| C11 경영분석 BI·예측 | 8 | 6 | 1 | 1 | 7 | +| C12 플랫폼·AI·관리·연동 | 7 | 6 | 1 | 0 | 1 | +| **합계** | **100** | **63** | **18** | **19** | **55** | + +--- + +## 6. 공통 품질(NFR) — 접근성·보안·다국어·테마 + +> **적용 범위: 100대 기능 전부 + 전 화면·전 API에 횡단 적용되는 비기능 요건(NFR).** 개별 기능(F001~F100)이 아니라 **모든 기능이 반드시 만족해야 하는 품질 게이트**다. QA(kintex-qa)가 기능 완료 판정 시 아래 4축을 동시 검증한다. 기존 `docs/SECURITY.md`(보안 불변)·`docs/design.md` v1.2 테마 토큰과 정합하며 상충 시 SECURITY.md가 우선한다. + +### N1. 웹접근성 (WCAG 2.1 AA · 공공 KWCAG) + +| 항목 | 기준 | 담당 | +|---|---|---| +| 준수 등급 | **WCAG 2.1 AA 필수**, 핵심 여정(등록·체크인·공개사이트)은 **AAA 지향**. 공공/정부 대상 노출 화면은 **KWCAG 2.2**(국가표준) 병행 준수 | frontend / designer | +| 시맨틱·ARIA | 시맨틱 HTML5 마크업, 의미 있는 `role`/`aria-*`, 폼 `label` 연결, 랜드마크 구조 | frontend | +| 키보드·포커스 | 전 인터랙션 키보드 조작, 논리적 탭 순서, 가시적 포커스 링, 모달 포커스 트랩·복귀 | frontend | +| 명도대비 | 텍스트 4.5:1(대형 3:1), UI 컴포넌트 3:1 — 라이트·다크 양 테마 각각 검증(N4) | designer / frontend | +| 스크린리더·대체텍스트 | 이미지 `alt`, 아이콘 SVG `title`/`aria-label`, **나노바나나 생성 이미지에 워터마크 고지 + 대체텍스트**, 캔버스(플로어플랜)는 텍스트 대안(부스 목록·좌표 요약) 제공 | frontend / visualizer | +| 동적 알림 | 진행 상태(RenderJob 로딩·옥션 순위)·토스트를 `aria-live`로 통지(§6-5 정합) | frontend | + +- **캔버스/맵 접근성 유의**: SVG/WebGL 플로어플랜(F008·F064·F072)은 시각 전용이므로 **동등한 비시각 대안**(데이터 테이블·검색·키보드 선택)을 필수 제공. + +### N2. 시큐어코딩 (OWASP Top 10 · SECURITY.md 불변) + +| 항목 | 기준 | 담당 | +|---|---|---| +| 입력 검증 | 전 엔드포인트 서버측 검증(Bean Validation), 화이트리스트·타입·범위, 파일 업로드 MIME/크기 가드(§6-5 다층 크기 가드 정합) | backend / common-dev | +| 출력 이스케이프(XSS) | React 자동 이스케이프 유지, `dangerouslySetInnerHTML` 금지(CMS 콘텐츠는 sanitize), 헤더 CSP | frontend / cms-dev | +| 인젝션 차단 | **MyBatis `#{}` 파라미터 바인딩 강제**(`${}` 금지), PostGIS/명령/LDAP 인젝션 차단, ORM 밖 동적 SQL 금지 | backend / db-engineer | +| CSRF·세션 | 상태변경 요청 토큰/SameSite, JWT 만료·회전, 로그인 실패 잠금(§5B-3·F097) | backend / common-dev | +| 인증·인가 | 전 엔드포인트 역할 게이트(행사 RBAC + 테넌트 격리 + `/api/admin/**` ADMIN + `/api/internal/**` 워커 토큰) — **IDOR 방지**(리소스 소유·tenant_id 검증) | backend | +| 시크릿 관리 | 자격증명·`GEMINI_API_KEY`·`ANTHROPIC_API_KEY`·JWT/DB 비번 **env only, 코드·DB·커밋·로그·응답 기록 금지**(SECURITY.md §1·§2), AES-256-GCM 저장 | backend / devops | +| 의존성 취약점 | npm/gradle 의존성 스캔(OWASP Dependency-Check/SCA) CI 게이트, 정기 패치 | devops | +| 감사로그 | 승인·낙찰(M15)·설계변경·룰셋개정·**리드(개인정보) 접근**·로그인/권한변경 전수 `TB_AUDIT_LOG`(tenant_id 포함, §8-2) | common-dev / backend | +| 개인정보 | 관람객·리드 동의·보존정책(§10 R10), 최소수집·마스킹, 응답 스키마 민감필드 완전 제외(SECURITY.md §2) | backend | + +### N3. 다국어 (i18n — 한 기본 + 영/중/일) + +| 항목 | 기준 | 담당 | +|---|---|---| +| 문자열 외부화 | UI 전 문자열 i18n 리소스(하드코딩 금지), 키 기반 번들, 누락 키 폴백(ko) | frontend | +| 로케일 전환 | 사용자 로케일 토글 + 브라우저 `Accept-Language` 감지, **테넌트 `locale_default`(§1A-1) 기본값 상속** | frontend / common-dev | +| 포맷 | 날짜/시간(시간대 `Asia/Seoul` 등 테넌트 기준)·숫자·통화(KRW 등) 로케일 포맷, PDF/서식도 로케일 반영 | frontend / backend | +| 콘텐츠 다국어 | CMS(M17·F069) 다국어 콘텐츠·`hreflang`·공개사이트 SEO(F063)와 정합, AI 자동 번역 + 사람 검수 | cms-dev | +| RTL 고려 | 초기 대상(한/영/중/일)은 LTR이나 향후 RTL 확장 대비 논리 속성(`margin-inline` 등) 사용 | frontend | + +### N4. 라이트/다크 테마 + +| 항목 | 기준 | 담당 | +|---|---|---| +| 테마 토큰 | **CSS 변수 기반 디자인 토큰**(색·표면·텍스트·경계), 라이트/다크 2벌 — design.md v1.2 캔버스 다크서피스 확장 정합 | designer / frontend | +| 토글·연동 | 사용자 수동 토글 + `prefers-color-scheme` 시스템 설정 연동, 선택 영속(localStorage/프로필) | frontend | +| 대비 준수 | 다크 모드도 N1 명도대비 기준 독립 충족(다크 서피스 위 텍스트·아이콘) | designer / frontend | +| 캔버스·이미지 | 플로어플랜 캔버스·나노바나나 이미지 뷰어 다크 서피스 대응, 생성 이미지 자체는 테마 무관(콘텐츠) | frontend / visualizer | + +### NFR 담당 매핑 요약 + +| NFR 축 | 주 담당 | 협업 | +|---|---|---| +| N1 접근성 | kintex-frontend-dev · designer | visualizer(캔버스 대안) | +| N2 시큐어코딩 | kintex-backend-dev · kintex-common-dev | kintex-db-engineer · kintex-devops-dev · kintex-qa(침투/회귀) | +| N3 다국어 | kintex-frontend-dev · kintex-cms-dev | kintex-common-dev(로케일·테넌트) | +| N4 테마 | designer · kintex-frontend-dev | — | + +> **QA 게이트(kintex-qa)**: 기능 완료 판정 = 기능 정합 + N1~N4 4축 통과. 자동화(axe-core 접근성·SCA 취약점·i18n 키 커버리지·테마 스냅샷) + 수동(스크린리더·키보드) 병행. + +--- + +## 7. 변경 이력 + +| 버전 | 일자 | 작성자 | 내용 | +|---|---|---|---| +| v1.0 | 2026-07-11 | planner | 최초 작성 — 글로벌 전시/이벤트/MICE·베뉴 SW 크롤링(8범주) 근거 종합, 100대 기능 12카테고리 분류, PLANNING v3.0(M1~M18·§5B·§1A) 모듈 매핑·갭 표기(이미 63/부분 18/신규 19), AI 자동화 맵(55/100) 신설. PLANNING.md·design.md·src 미수정(신규 파일만) | +| v1.1 | 2026-07-11 | planner | **공통 품질(NFR) 절 신설(§6)** — 접근성(WCAG 2.1 AA·공공 KWCAG)·시큐어코딩(OWASP Top10·SECURITY.md 불변 정합)·다국어(i18n 한/영/중/일·테넌트 로케일)·라이트/다크 테마(CSS 토큰) 4축 + 담당 에이전트 매핑 + QA 게이트. 전 100기능·전 화면 횡단 적용 | diff --git a/plugins/zio-harness/knowledge/kintex/docs/FEATURE_GAP_ANALYSIS.md b/plugins/zio-harness/knowledge/kintex/docs/FEATURE_GAP_ANALYSIS.md new file mode 100644 index 0000000..b9304ff --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/FEATURE_GAP_ANALYSIS.md @@ -0,0 +1,160 @@ +# 전시관리 100대 기능 — 갭 분석 및 구현 권고 (FEATURE_GAP_ANALYSIS) + +> 작성: planner · 작성일: 2026-07-11 · 버전: v1.0 +> 짝 문서: `docs/FEATURE_BACKLOG_100.md`(100대 기능 백로그 + AI 자동화 맵 + NFR). 본 문서는 그 백로그를 **기존 PLANNING v3.0 대비 갭**으로 정리하고, **신규·부분 기능을 어느 도메인 에이전트가 어느 Phase에 구현할지** 권고한다. +> **불변 준수**: 확정 스택(React18/19+Spring Boot 3.x(Java17)+MyBatis+PostgreSQL/PostGIS+Redis+나노바나나 Python 워커) · 멀티테넌시(tenant_id 격리) · 보안 불변(외부 API 게이트·워터마크·시크릿 env only). `docs/PLANNING.md`·`design.md`·`src` 미수정 — 본 문서는 구현 계획 입력물이다. + +--- + +## 1. 갭 요약 + +| 상태 | 개수 | 의미 | +|---|---|---| +| **이미 커버됨** | **63** | PLANNING v3.0(M1~M18·§5B·§1A)에 이미 명시 — 신규 기획 불필요, 구현 트랙에서 소화 | +| **부분** | **18** | 모듈은 있으나 화면/로직/UI가 미상세 — **보강 필요** | +| **신규** | **19** | v3.0 미포함 — **신규 기획·구현 필요** | +| 합계 | 100 | — | + +- **AI 활용**: 55/100 (Y 33 + 부분 22). AI 미사용 45는 거래·인프라 기능(결제·QR·RBAC 등)으로 AI 산출물을 소비/트리거. +- **결론**: 100대 기능의 **63%가 이미 v3.0 스코프 내** — 본 시스템 기획은 이미 글로벌 전시테크 대비 광범위하다. 실제 확장 필요분은 **부분 18 + 신규 19 = 37개**이며, 이 중 상당수가 관람객·네트워킹(C6·C7)과 참가업체 서비스(C5)에 몰려 있다(참가/관람 접점 심화 영역). + +### 카테고리별 갭 분포 + +| 카테고리 | 이미 | 부분 | 신규 | 갭(부분+신규) | +|---|---|---|---|---| +| C1 판매·홀배정·견적 | 4 | 1 | 2 | 3 | +| C2 설계·시각화 코어 | 11 | 2 | 0 | 2 | +| C3 서류·규정·워크플로 | 4 | 3 | 1 | 4 | +| C4 공사·장치 옥션 | 6 | 1 | 1 | 2 | +| C5 참가업체 서비스·물류 | 4 | 2 | 2 | 4 | +| C6 관람객 등록·배지·리드 | 6 | 1 | 3 | 4 | +| C7 비즈매칭·네트워킹·앱 | 2 | 2 | 4 | 6 | +| C8 마케팅·EDM·공개·스폰서 | 7 | 0 | 2 | 2 | +| C9 현장운영·wayfinding·안전 | 6 | 1 | 1 | 2 | +| C10 정산·결제·재무 | 3 | 2 | 1 | 3 | +| C11 경영분석 BI·예측 | 6 | 1 | 1 | 2 | +| C12 플랫폼·AI·관리·연동 | 6 | 1 | 0 | 1 | +| **합계** | **63** | **18** | **19** | **37** | + +--- + +## 2. 신규 기능(19) 구현 권고 + +> 각 신규 기능의 담당 도메인 에이전트·의존·PLANNING 반영 필요 여부. **P0 신규 없음**(P0 코어는 전부 이미 커버됨) — 신규는 P1 11개·P2 8개. + +| 번호 | 기능 | P | 담당(주) | 협업 | 의존 | PLANNING 반영 | +|---|---|---|---|---|---|---| +| F005 | 부스 판매 인벤토리 관리 | P1 | kintex-backend-dev | kintex-frontend-dev | M2 좌표 | M1/M2 절에 sales inventory 순증 | +| F006 | 온라인 부스 셀프 선택·판매 | P1 | kintex-frontend-dev | kintex-backend-dev | F005·M9 | M1/M2 exhibitor booth-sales | +| F007 | 임대계약 전자서명 | P2 | kintex-backend-dev | kintex-admin-dev | M6·M9 | §1 Non-goal 완화 표기 | +| F026 | OCR 문서 자동등록 | P1 | kintex-ai-dev | kintex-backend-dev | AI 라우터(F100) | M6에 OCR 흐름 순증 | +| F042 | 부대물품 렌탈 주문 | P2 | kintex-backend-dev | kintex-frontend-dev | M8 | M8 확장 | +| F043 | 배송·창고 선입고 트래킹 | P2 | kintex-backend-dev | kintex-devops-dev | M8 | M8 확장(드레이지) | +| F046 | AI 폼빌더 | P2 | kintex-ai-dev | kintex-visitor-dev | AI 라우터 | M10 순증 | +| F051 | AI 리드 스코어링·분류 | P1 | kintex-ai-dev | kintex-visitor-dev | M10 리드·AI 라우터 | M10 순증 | +| F054 | 스마트 배지·웨어러블 | P2 | kintex-visitor-dev | kintex-devops-dev | M10·HW 협의 | M10/M14 확장(HW 의존 명시) | +| F058 | 세션·아젠다 관리 | P2 | kintex-visitor-dev | — | M10 | M11/이벤트앱 순증 | +| F059 | AI 세션·부스 추천 | P2 | kintex-ai-dev | kintex-visitor-dev | F058·AI 라우터 | M11 순증 | +| F060 | 인앱 채팅·네트워킹 | P2 | kintex-visitor-dev | kintex-backend-dev(WebSocket) | M10 | M11 확장 | +| F061 | 실시간 설문·투표·Q&A | P2 | kintex-visitor-dev | — | 이벤트앱 | M11 순증 | +| F070 | 스폰서십 패키지·판매 관리 | P1 | kintex-cms-dev | kintex-backend-dev | M9·M12 | M12/M17 순증(스폰서십) | +| F071 | 스폰서 대시보드 | P2 | kintex-bi-dev | kintex-cms-dev | F070·M16 | M16/M12 순증 | +| F079 | 현장 이상탐지·알림 | P2 | kintex-ai-dev | kintex-visitor-dev | M14·AI 라우터 | M14 순증 | +| F085 | 환불·취소 규정 자동 | P2 | kintex-backend-dev | kintex-admin-dev(룰셋) | M9 | M9 확장 | +| F092 | 자연어 조회 Text-to-SQL | P2 | kintex-ai-dev | kintex-bi-dev | M16 데이터마트·AI 라우터 | M16 순증 | +| F099 | API·웹훅·CRM 게이트웨이 | P2 | kintex-backend-dev | kintex-devops-dev | 전 모듈 | §7-2 연동 순증 | + +## 3. 부분 기능(18) 보강 권고 + +> 모듈은 있으나 화면/로직 미상세 — 보강만 필요(신규 기획 최소). + +| 번호 | 기능 | P | 담당(주) | 보강 내용 | 기존 BACKLOG 연계 | +|---|---|---|---|---|---| +| F001 | 가용성 실시간 캘린더 | P1 | kintex-frontend-dev · kintex-backend-dev | M1 가용성 캘린더 UI/API 상세화 | — | +| F012 | 조립부스 옵션·3D 프리뷰 | P0 | designer · kintex-frontend-dev | SCR-05/06 조립부스 옵션 UI | **B-01(open)** | +| F018 | 조명 조도 배치안 제안 | P1 | visualizer · kintex-frontend-dev | M4a 조명 배치 전용 UI | **B-10(open)** | +| F024 | 리깅 구조계산서 사전체크 | P2 | kintex-ai-dev | 구조계산서 항목 체크(판정 제외) | Phase3 | +| F025 | 규정 자연어 챗봇 | P2 | kintex-ai-dev | RAG 규정 코퍼스 + 챗 UI | Phase3 | +| F028 | 서류 버전·전자결재 | P1 | kintex-common-dev | §5B approval 워크플로 배선 | — | +| F035 | 물량서(BOQ) 자동산출 | P1 | kintex-bidding-dev | M4/M15 물량 자동집계 | — | +| F037 | 참가업체 통합 서비스 포털 | P1 | kintex-frontend-dev | exhibitor. 포털 IA 상세 | — | +| F041 | 지게차·부대장비 신청 | P2 | kintex-backend-dev | M8 신청 통합 | — | +| F052 | 리드 팔로업 EDM 자동 | P1 | kintex-cms-dev · kintex-visitor-dev | M10→M12 자동 트리거 | — | +| F053 | 티켓 발권·유료 결제 | P2 | kintex-visitor-dev · kintex-backend-dev | M10+M9 유료 등록 | — | +| F057 | 이벤트 모바일앱 | P1 | kintex-visitor-dev | 관람객 앱 IA 상세 | — | +| F062 | 매칭 성과 리포트 | P2 | kintex-bi-dev · kintex-visitor-dev | M11→M16 성과 지표 | — | +| F078 | 디지털 사이니지 배포 | P2 | kintex-cms-dev | M17 사이니지 채널 | HW 협의 | +| F083 | 세금계산서·정산 리포트 | P1 | kintex-backend-dev | M9 세금계산서 자동 | 킨텍스 재무 협의 | +| F084 | 옥션 수수료·매출 정산 | P2 | kintex-bidding-dev · kintex-backend-dev | M9↔M15 정산 연동 | — | +| F093 | 경영진 KPI·AI 브리핑 | P1 | kintex-bi-dev · kintex-ai-dev | M16-1⑦ AI 브리핑 자동화 | — | +| F100 | AI 플랫폼 라우터 | P1 | kintex-ai-dev | AiTextRouter/AiConfig + 나노바나나·Ollama 폴백·근거·워터마크 | 전 AI 기능 선행 | + +--- + +## 4. 도메인 에이전트별 작업 집약 (신규+부분 37개) + +| 에이전트 | 담당 기능(주 담당) | 건수 | +|---|---|---| +| **kintex-ai-dev** | F026·F046·F051·F059·F079·F092·F100(주) + F024·F025·F093(협업) | 7주+3협 | +| **kintex-visitor-dev** | F054·F057·F058·F060·F061(주) + F046·F051·F052·F053·F059·F062·F079(협업) | 5주+7협 | +| **kintex-backend-dev** | F005·F007·F042·F043·F085·F099(주) + F001·F006·F026·F041·F053·F070·F083·F084(협업) | 6주+8협 | +| **kintex-frontend-dev** | F001·F006·F037·F057(주) + F005·F012·F018·N1/N3/N4 NFR 전반 | 4주+다수 | +| **kintex-cms-dev** | F070·F078(주) + F052·F071(협업) | 2주+2협 | +| **kintex-bi-dev** | F071·F093(주) + F062·F092(협업) | 2주+2협 | +| **kintex-bidding-dev** | F035·F084(주) | 2주 | +| **kintex-common-dev** | F028(주) + N2 감사·시큐어코딩 전반 | 1주+NFR | +| **kintex-admin-dev** | F007·F085 룰셋 협업 | 협업 | +| **kintex-db-engineer** | 신규 엔티티(부스판매·렌탈·스폰서십·리드스코어·설문·이상탐지) DDL + tenant_id·인덱스 | 횡단 | +| **kintex-devops-dev** | F043·F054·F099 연동·HW·SCA 스캔 | 협업 | +| **designer** | F012·F018 UI + N1 접근성·N4 테마 | 횡단 | +| **visualizer** | F018 조명·나노바나나 접근성 대안(N1) | 협업 | +| **kintex-qa** | 전 기능 + NFR 4축 게이트(§FEATURE_BACKLOG_100 §6) | 횡단 | + +--- + +## 5. Phase 편입 권고 (kintex-impl-orchestrator 입력) + +> PLANNING §9 로드맵(Phase 1 코어+공통 선행 / Phase 2 워크플로·운영 / Phase 3 현장·확장)에 신규·부분 기능을 배치. **이미(63) 기능은 각 모듈 구현 트랙에서 소화되므로 아래는 부분·신규(37) + 선행 기반만 표기.** + +### Phase 1 — 설계·시각화 코어 + 공통·AI 기반 선행 + +| 유형 | 기능 | 사유 | +|---|---|---| +| 선행 기반 | **F100 AI 플랫폼 라우터**, F094~F098(§5B 공통·인증·테넌트·NFR N2) | 전 AI·전 기능 선행 — 최우선 | +| 부분 보강 | F012(조립부스 UI, B-01), F018(조명 UI, B-10) | P0 코어 완성도 | +| 신규(조기) | F026 OCR 자동등록 | 서류(M6) 코어 흐름에 접합 | +| NFR | N1 접근성·N4 테마·N3 i18n 골격 | 전 화면 토큰·리소스 선행 | + +### Phase 2 — 워크플로·판매·옥션·정산 운영 통합 + +| 유형 | 기능 | +|---|---| +| 신규 | F005 부스 인벤토리, F006 셀프 판매, F007 전자서명, F042 렌탈, F043 배송트래킹, F070 스폰서십, F085 환불규정, F099 API 게이트웨이 | +| 부분 | F001 가용성 캘린더, F028 전자결재, F035 BOQ, F037 참가업체 포털, F041 지게차, F083 세금계산서, F084 옥션 정산 | + +### Phase 3 — 관람·네트워킹·현장·BI 확장 + +| 유형 | 기능 | +|---|---| +| 신규 | F046 폼빌더, F051 리드 스코어, F054 스마트배지, F058 아젠다, F059 세션추천, F060 인앱채팅, F061 설문, F071 스폰서 대시보드, F079 이상탐지, F092 Text-to-SQL | +| 부분 | F024 구조체크, F025 규정챗봇, F052 팔로업EDM, F053 티켓발권, F057 이벤트앱, F062 매칭리포트, F078 사이니지, F093 KPI브리핑 | + +--- + +## 6. 리스크·전제 (신규 기능 한정) + +| # | 리스크/전제 | 관련 기능 | 완화 | +|---|---|---|---| +| G1 | 스마트 배지·웨어러블은 하드웨어 인프라 의존 | F054 | HW 협의 전 소프트 전용 폴백(QR), 킨텍스 시설 협의 | +| G2 | 전자서명·PG·세금계산서는 킨텍스 재무·법무 프로세스 연동 협의 | F007·F083·F085 | 협의 성사 전 문서 생성까지, 외부 서명/PG는 승인된 국내 서비스 한정 | +| G3 | 신규 AI 기능(리드스코어·추천·Text-to-SQL·이상탐지)은 데이터 축적·정합에 의존 | F051·F059·F079·F092 | 초기 근사·룰 폴백, AI 라우터(F100) 경유·근거·환각차단, 온프레미스/승인 모델 | +| G4 | API·웹훅 게이트웨이는 외부 CRM/ERP 연동 시 보안 게이트 필요 | F099 | 외부 API 금지 원칙 정합(인바운드 웹훅·승인된 아웃바운드만), 시크릿 env only | +| G5 | 신규 엔티티는 전부 `tenant_id` 격리·NFR N1~N4 준수 필수 | 신규 19 전부 | db-engineer가 tenant_id·인덱스 표준(§8-2), qa가 NFR 게이트 | + +--- + +## 7. 변경 이력 + +| 버전 | 일자 | 작성자 | 내용 | +|---|---|---|---| +| v1.0 | 2026-07-11 | planner | 최초 작성 — FEATURE_BACKLOG_100 대비 갭 분석(이미 63/부분 18/신규 19), 신규 19·부분 18 구현 권고(담당 도메인 에이전트 매핑), 에이전트별 작업 집약, kintex-impl-orchestrator Phase 1/2/3 편입 권고, 신규 기능 리스크 5건. PLANNING.md·design.md·src 미수정 | diff --git a/plugins/zio-harness/knowledge/kintex/docs/GUARDIA_ALIGNMENT.md b/plugins/zio-harness/knowledge/kintex/docs/GUARDIA_ALIGNMENT.md new file mode 100644 index 0000000..d3b5a49 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/GUARDIA_ALIGNMENT.md @@ -0,0 +1,102 @@ +# KINTEX ↔ GUARDiA 표준 프레임워크 정합 매핑 + +> 킨텍스 자동전시시스템이 **GUARDiA 표준 프레임워크(UIMS/WISE 기준)** 를 어떻게 준수·차용·차이 처리하는지의 단일 참조. +> 정본 표준: `workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md` · WISE 적용 명세: `workspace/_framework/WISE_APPLY_SPEC.md` (둘 다 읽기 전용). +> 이 문서는 킨텍스 관점의 **매핑·갭**만 기록한다(표준 원문 복제 금지). + +--- + +## 0. 요약 + +| 축 | 표준(GUARDiA/UIMS) | KINTEX 상태 | +|----|--------------------|-------------| +| 스택 | Spring Boot 3.5 Java17 + React18/19 Vite + MyBatis + PostgreSQL | ✅ 준수 (+ PostGIS·Redis·나노바나나 Python 워커 = 도메인 확장) | +| 인증 | JWT + 2FA(OTP) + 로그인 실패 잠금 + admin 비번 env | ✅ 준수 (행사 단위 RBAC 로 역할 모델 확장) | +| 공통 모듈 | worklog·schedule·message·stats·system·notice·… | ✅ WISE 이식 (`work/*`·`system/*` 패키지) | +| 디자인 | WISE 토큰·선(stroke) SVG·chief-designer 리드 | ✅ 준수 | +| AI | 프로바이더 선택형 + AiTextRouter 폴백 + DuckDB 학습 | ◐ Claude 기본 + AiConfig 전환(설계) — 나노바나나(Gemini)는 **승인된 이미지 예외** | +| 보안 | 외부 API 금지(anthropic 예외)·AES-256-GCM·감사로그 | ✅ 준수 (+ Gemini 이미지 예외·AI 이미지 워터마크 강제) | +| 배포 | workspace→repos(fresh)→Gitea→webhook→systemd→nginx | ✅ 준수 (분리형: 프론트 dist→nginx / 백엔드 jar→8021) | +| 스키마 | Flyway/sql.init 멱등·mode·누출차단 | ◐ Flyway 사용 — GUARDiA sql.init 갭은 §4 참조 | + +범례: ✅ 완전 준수 · ◐ 부분/설계 · ✕ 미준수. + +--- + +## 1. 스택 정합 + +- **일치**: Spring Boot 3.x(Java 17)·MyBatis·React(Vite/TS)·PostgreSQL·단일 Gitea repo·systemd·nginx. +- **킨텍스 확장(표준 상위집합)**: + - **PostGIS** — 부스 폴리곤·트렌치 포인트·배선 LineString 공간 연산(표준엔 없음, 도메인 필수). + - **Redis 작업 큐** — RenderJob·서류·알림 비동기(`kintex:renderjob:queue`). + - **나노바나나 Python 워커** — Gemini 이미지 생성 사이드카(별도 systemd `kintex-nanobanana.service`). 백엔드는 큐 발행만, 키는 워커 env 전용. +- **패키징 차이**: 표준은 "단일 jar(프론트→백엔드 static 번들)". 킨텍스는 **역할별 프론트 번들 분리**(PLANNING §2-1)라 nginx 정적 서빙 + 백엔드 API 분리를 기본으로 한다. → 표준의 *의도*(무중단·헬스게이트 배포)는 유지, 물리 패키징만 분리형. + +## 2. 인증 정합 (JWT + 2FA) + +- **일치**: `Authorization: Bearer `(HS256), 2단계 로그인(`/api/auth/login` → `verify-otp`), admin 비번 env(`ADMIN_PASSWORD_ENC`+`ADMIN_KEY_FILE`) 재시드, 로그인 실패 잠금. +- **확장**: RBAC 가 전역 역할이 아니라 **행사(event) 스코프 역할**(`ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER`) — JWT 클레임 `roles`=eventId→역할, `hm`=홀매니저. `/api/admin/**`=ADMIN 게이트는 표준 그대로. +- **공개 경로**: `GET /health`·`POST /api/auth/login`·`/ws/**`·`POST /api/internal/render/callback`(워커 토큰). 그 외 인증 필요. + +## 3. 공통 모듈 정합 (WISE 이식) + +킨텍스 백엔드 `work/*`·`system/*` 패키지에 WISE 공통 레이어를 이식했다(컨트롤러 실측): + +| 표준 모듈 | KINTEX 경로 | +|-----------|-------------| +| worklog | `work/worklog` (`/api/work/...`) | +| schedule | `work/schedule` | +| message | `work/message` | +| stats | `work/stats` (`GET /api/work/stats/worklog`) | +| notice | `work/notice` (`/api/work/notices`) | +| opinion | `work/opinion` | +| search | `work/search` | +| meeting | `work/meeting` | +| report | `work/report` | +| notification | `work/notification` (`/api/work/notifications/unread-count`) | +| system(사용자·역할·공통코드·메뉴·설정·감사) | `system/*` + `common/audit` (`/api/common/**`·`/api/admin/**`) | + +이식 하네스: 신규 공통 모듈 필요 시 `uiws-port-orchestrator`(기존 솔루션 전파) 패턴 준용. 킨텍스는 `kintex-common-dev` 에이전트가 담당. + +## 4. 스키마 무결성 — Flyway 갭 (GUARDiA schema-integrity 패턴 요약) + +GUARDiA 다수 솔루션은 `sql.init.mode=never` + schema.sql 후행 확장 때문에 **누락 테이블**(`relation "x" does not exist`) 500 장애를 겪었고, 검증된 수복 패턴은: +1. **시드 멱등화** — 유니크 인덱스로 `INSERT ... ON CONFLICT DO NOTHING` (재적용 안전). +2. `sql.init.mode=always` + `continue-on-error` — 후행 추가 DDL 도 재기동 시 적용. +3. **DataAccessException 핸들러** — DB 오류를 요약 메시지로 변환(스택트레이스·relation 명 누출 차단). +4. 누락 테이블은 **레이어로 드러남** — 매퍼 `FROM`/`JOIN` 을 전수 추출해 한 번에 역설계. + +**킨텍스는 Flyway 순번 마이그레이션을 쓰므로 위 문제의 구조적 원인이 없다**(마이그레이션이 곧 스키마 권위). 남는 갭은 아래 3개뿐: + +| 갭 | GUARDiA 교훈 | 킨텍스 가드 | +|----|--------------|-------------| +| 시드 비멱등 | 재적용 시 중복키 | Flyway 마이그레이션의 시드는 `ON CONFLICT DO NOTHING`/`MERGE` 로 작성. repeatable 마이그(`R__`)는 자체 멱등. | +| baseline 오적용 | 기존 DB 에 V1 재실행 | `baseline-on-migrate=true` + 운영 DB 는 baseline 버전 명시. 신규 마이그 번호 = 현재 최대+1(pre-push 훅 충돌검사). | +| DB 오류 누출 | 스택트레이스 노출 | 표준 `@RestControllerAdvice`(ApiResponse.error 요약) 로 DataAccessException→`INTERNAL` 요약 매핑. **relation/컬럼명 응답 금지**(API_GUIDE §5). | + +→ 결론: 킨텍스는 **sql.init 이 아니라 Flyway** 이므로 GUARDiA "mode=always" 이식은 불필요. 대신 (a) 시드 멱등, (b) baseline 규율, (c) DB 오류 요약 핸들러 3개만 유지하면 동등한 무결성을 얻는다. + +## 5. AI 정합 + +- **Claude 기본 + 설정형 전환**: 표준 `AiTextRouter`/`AiConfig`(Claude→Qwen3→소형 폴백)를 킨텍스 AI(부스 배치·규정검증 보조·매칭·자연어조회·서류검수·챗봇)에 적용(설계, `kintex-ai-dev`). +- **나노바나나(Gemini) 이미지**: 표준의 "외부 API 금지"에 대한 **별도 승인 예외**(G1 게이트, `GEMINI_API_KEY` 워커 env only). 텍스트 AI 의 anthropic 예외와 동일 취급 — 키 미커밋·미로그·미응답. +- **AI 생성 이미지 워터마크 강제**(§SECURITY): 표준에 없는 킨텍스 고유 불변 — M5 응답에 `watermarkRequired:true` 항상 포함. + +## 6. 배포 정합 + +- **일치**: `workspace→repos(fresh git init)→Gitea(zio/kintex)→webhook→deploy_server→systemd→nginx`, Fail-Safe(백업→배포→헬스게이트 `GET /health` 200→롤백), 서버 빌드 직렬(OOM 방지). +- **킨텍스 블록**: `deploy/deploy_server_kintex_block.py`(정본 사본) — 포트 8021, 프론트 dist→`/var/www/kintex`, 백엔드 bootJar→`/opt/kintex/app/app.jar`, `kintex.service`+`kintex-nanobanana.service` 재기동, Flyway 자동 적용, `deploy_kintex.sh` 원자교체·헬스체크·롤백. +- **도메인/포트**: 개발 `kintex.zioinfo.co.kr`→101.79.17.164:8021 / 운영 `kintex.wise.ai.kr`(후속). +- **경량 push**: `scripts/push_kintex.py`(env-only 자격증명, fresh init, bundle→SFTP→push). + +## 7. 차용한 GUARDiA 자산 (이 정합 작업으로 kintex 에 추가) + +| kintex 파일 | 원본 패턴 | 용도 | +|-------------|-----------|------| +| `tools/test/kintex_smoke_test.py` | `scripts/check/run_full_test.py` | 8021 스모크/회귀(health+라우터등록+로그인 프로브) | +| `scripts/push_kintex.py` | `scripts/push/push_any_repo.py` | 단일 repo 경량 push(env-only) | +| `docs/GUARDIA_ALIGNMENT.md` | `_framework/*` | 본 정합 매핑 | +| `docs/SECURITY.md` | CLAUDE.md 보안 제약 | 킨텍스 관점 보안 불변 | +| `docs/OPS_RUNBOOK.md` | GUARDiA 운영/헬스체크 관행 | 헬스·재기동·롤백 런북 | + +> 원본 GUARDiA 자산은 **읽기 전용**으로 참조했고 수정하지 않았다. 킨텍스 사본은 kintex 컨텍스트(포트 8021·도메인·나노바나나·PostGIS)로 재작성. diff --git a/plugins/zio-harness/knowledge/kintex/docs/IMPLEMENTATION_BACKLOG.md b/plugins/zio-harness/knowledge/kintex/docs/IMPLEMENTATION_BACKLOG.md new file mode 100644 index 0000000..876b7e9 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/IMPLEMENTATION_BACKLOG.md @@ -0,0 +1,100 @@ +# 킨텍스 자동전시시스템 — 구현 백로그 v2.0 + +> 재작성: 2026-07-11 · 근거: `docs/PLANNING.md` v2.0(부스 코어 M2~M5 + 도메인 M10~M18 + 공통 레이어 §5B)·`docs/design.md` v1.1·`docs/analysis/*`·Stitch 산출물·평면도/CAD 자산(`docs/assets/floorplans/`) +> 실행: `kintex-impl-orchestrator`(에이전트 팀, model opus). 담당 약칭 — AA/SA/TA/DA/NA=아키텍트, COM=kintex-common-dev, BE=backend-dev, FE=frontend-dev, DB=db-engineer, VIZ=visualizer, AI=ai-dev, QA=kintex-qa, DEV=devops-dev, BID=bidding-dev, VIS=visitor-dev, CMS=cms-dev, BI=bi-dev, ADM=admin-dev, DES=designer. +> 스택: React(Vite·TS) + Spring Boot 3.x(Java17)+MyBatis + PostgreSQL(PostGIS) + Redis + 나노바나나 Python 워커. AI=Claude 기본+설정형 전환(AiTextRouter/AiConfig). 공통=WISE(UIWS) 이식. + +## 선행 게이트 (소유자 확인) +- **G1** 나노바나나(Gemini) 외부 호출 승인(PLANNING R12) — M5 실호출·배포 전. 미승인 시 목/degraded. +- **G2** 배포 대상 서버·포트(GUARDiA 인프라와 별개 도메인) — Phase E 전. + +## 확보 자산 +- 평면도 15장 + CAD(제1전시장 "평면,트렌치.dwg" 포함) `docs/assets/floorplans/` → **R4(트렌치·CAD) 해소**. CAD zip은 gitignore(로컬 보존), db-engineer가 트렌치 좌표 추출에 사용. 사용자 첨부 평면도는 `.../provided/`. + +--- + +## Phase A — 아키텍처·거버넌스 (아키텍트 팀 + reviewer) +| ID | 작업 | 담당 | 완료 기준 | +|---|---|---|---| +| A-1 | 애플리케이션 아키텍처(모듈 경계·레이어·API 표준·패키지) | AA | `docs/architecture/app.md` | +| A-2 | 시스템 아키텍처·NFR(확장성·HA·성능·보안영역·배포 토폴로지) | SA | `docs/architecture/system.md` | +| A-3 | 기술 표준(스택·빌드/배포·개발표준·관측성·AiTextRouter) | TA | `docs/architecture/tech.md` | +| A-4 | 데이터 아키텍처(전사 ERD·공간데이터·마스터·공통코드·거버넌스·BI 마트) | DA | `docs/architecture/data.md`+ERD | +| A-5 | 네트워크 아키텍처(DMZ/내부망 분리·방화벽·부하분산·외부 아웃바운드) | NA | `docs/architecture/network.md` | +| A-6 | 아키텍처↔PLANNING 정합 검증 | reviewer | 불일치 0/티켓화 | + +## Phase B — 공통/시스템관리 레이어 (★전 모듈 선행, PLANNING §5B, WISE/UIWS 이식) +| ID | 작업 | 담당 | 완료 기준 | +|---|---|---|---| +| B-0 | 스캐폴드: `src/backend`(Spring Boot 3.x·`com.zioinfo.kintex`)·`src/frontend`(Vite·TS)·`kintex_db`(PostGIS·Flyway) | BE·FE·DB | compileJava·build·마이그레이션 통과 | +| B-1 | 인증: JWT+RBAC(6역할) + **2차 인증 OTP(TOTP RFC6238)** + 로그인 실패 잠금 + admin 비번 env(AES-256-GCM, admin123 금지) | COM·BE | 2FA 등록/검증/초기화 왕복 | +| B-2 | 시스템관리: 사용자·역할/권한·공통코드·메뉴·감사로그·시스템설정(→ M18 통합) | COM·ADM·DB | CRUD·RBAC 가드·감사 기록 | +| B-3 | 공통 업무기능: worklog·schedule·message·stats·notice·opinion·search·meeting·report·notification·audit (WISE 이식) | COM·DB | 각 모듈 진입·API 왕복 | +| B-4 | 공통 컴포넌트(예외·응답봉투·감사 AOP·알림 단일화) + 프론트 공통(2FA 화면·공통코드·검색바·그리드·달력·모달) | COM·FE | AA 표준 정합 | +| B-5 | 점진 QA(2FA·RBAC·비번/PII 미노출·경계면) | QA | 통과까지 반려 | + +## Phase C — P0 부스 시공 코어 (M2·M3·M4·M5) +| ID | 모듈 | 작업 | 담당 | 완료 기준 | +|---|---|---|---|---| +| C-M2 | 플로어플랜 | Booth polygon·Trench(CAD 추출) 스키마·배치 저장/규정검증(PostGIS)·**AI 1·2·3안 생성→선택/병합**·SCR-03/04 이식 | DB·BE·AI·FE·QA | 3안 생성·병합·규정 재검증 | +| C-M3 | 부스 설계 | 조립/독립 설계·규정 사전검증(높이·리깅·방염)·3안 생성/병합·SCR-06/09 이식 | BE·AI·FE·QA | 위반 사전 플래깅·컨펌 | +| C-M4 | 유틸리티 배선 | Wiring LineString·전기/네트워크/급배수 배선·자동 견적·위치표시도·SCR-07/08 이식 | DB·BE·FE·QA | 최단 배선·견적·위치표시도 | +| C-M5 | 나노바나나 시각화 | RenderJob 발행/상태·Redis·WebSocket·워커 생성(G1)·S6 래스터·SCR-12·Before/After | BE·VIZ·FE·QA | (G1 시)실생성/미승인시 목·워터마크 강제 | +| C-C | 공통 화면 | SCR-01 로그인·SCR-02 주최자 대시보드·SCR-05 참가업체 홈·SCR-10/11 홀매니저·SCR-M1/M2 현장(모바일) 이식 | FE·QA | 역할별 진입·상태 처리 | + +## Phase D — P1 도메인 (역할별 포털 분리) +| ID | 모듈 | 작업 | 담당 | 완료 기준 | +|---|---|---|---|---| +| D-M15 | **공사/장치 옥션** | AI자료 패키지 열람→**견적서(Quotation) 제출**→역경매(라운드·순위)→전시업체 낙찰/확정→계약/발주. 등록업체만 응찰(M7 검증). `Auction 1─N Quotation ─ Award`·견적서 PDF/버전 | BID·BE·DB·FE·QA | 견적서 제출·역경매·낙찰 왕복 | +| D-M10 | **관람객·현장** | 등록·티켓(PG)·배지/QR·현장 체크인·리드캡처·관람객 웹/모바일 | VIS·BE·DB·FE·QA | 등록→배지→체크인→리드 | +| D-M12/17 | **마케팅·공개사이트·CMS** | 헤드리스 CMS·참가업체 마이크로사이트·**일반 대중 공개 홍보 사이트(SEO·다국어)**·배너/프로모션·EDM | CMS·BE·FE·QA | 공개 조회·게시 워크플로·SEO | +| D-M16 | **경영분석 BI** | 매출·홀 가동률·리텐션·이벤트 P&L·수요예측·KPI 대시보드·부스 트래픽/ROI(Recharts) | BI·DA·BE·FE·QA | 지표 집계·드릴다운·내보내기 | +| D-M18 | **관리자 백오피스** | 시스템관리(B-2)+킨텍스 마스터데이터(홀·요율·규정 룰셋·등록업체)·관리 대시보드 | ADM·BE·FE·QA | RBAC·마스터 CRUD·룰셋 버전 | +| D-M1/6/7/9 | 배정·서류·매칭·정산 | 홀 배정·자동견적(요율 룰)·마일스톤/서식·등록업체 매칭·정산/결제 | BE·FE·DB·QA | 견적·마일스톤·정산 | + +## Phase E — P2 + 빌드·배포 +| ID | 작업 | 담당 | 완료 기준 | +|---|---|---|---| +| E-M11 | 비즈니스 매칭(관람객↔참가업체/바이어) | VIS·AI | 추천·미팅예약 | +| E-M13 | wayfinding/실내 내비(M2 배치 재사용) | VIS·FE | 부스 검색·경로 | +| E-M14 | 현장운영(혼잡·안전·주차·에너지) | BE·FE | 대시보드·경보 | +| E-DEP | 역할별 프론트 번들 + Spring jar + 워커 서비스 빌드·Gitea CI/CD·systemd·env | DEV | (G2 후)push→배포 | + +## Phase F — 벤치마킹 유래(티켓·관람객) 추가 항목 +> 근거: `docs/analysis/ticketing-app-benchmark.md`(2026-07-11, COEX·NOL/멜론/티켓링크·킨텍스 앱·Whova/Eventbrite 벤치마킹). ⓑ=P1 보강(기존 화면 스펙 수정 후보), ⓒ=P2 신규(신규 화면/기능). **PLANNING.md·design.md 직접 수정 금지 — planner/designer 경유 반영.** 관련 화면 표기는 현행 design.md v2.1 기준. + +### ⓑ 보강 (P1) — 기존 화면 스펙 수정 후보 +| ID | 작업 | 대상 모듈 | 관련 화면 | 출처 | 담당 | 완료 기준 | +|---|---|---|---|---|---|---| +| F-B1 | 스마트티켓 부정입장 방지 — 디바이스 바인딩/회전(애니메이션) QR + 본인인증(캡처본 무효·양도 방지, 현행 정적 QR 대체) | M10 | SCR-M15·31 | 벤치 §2②·§3 B1 | VIS·BE·kintex-mobile-dev | 회전 토큰·기기 인식 체크인 왕복 | +| F-B2 | 취소·환불 규정 정교화 — 3구간(100/50/0%)→다구간 취소수수료 + 예매수수료 별도 환불 규정, 서버 권위 | M9·M10 | SCR-P8 | 벤치 §2④·§3 B2 | VIS·BE | 다구간 예상환불액 서버 산출·표시 | +| F-B3 | 티켓·배지·관람객 앱 다국어(한/영/중/일) — 공개사이트(M12) 외 티켓·배지·지갑 화면 확장 | M10·M12 | SCR-P7·M5·M15 | 벤치 §2⑧·§3 B3 | VIS·CMS·FE | 4개 언어 티켓·배지 렌더 | +| F-B4 | 세션 정원 기반 사전등록(RSVP) — 즐겨찾기에 정원·마감·대기 상태 추가 | M11 | SCR-M9 | 벤치 §2①·§3 B4 | VIS·AI·BE | 정원 소진·마감 상태 처리 | +| F-B5 | 결제수단 사전등록·간편결제 빠른결제 | M9 | SCR-P7·M14 | 벤치 §2⑤·§3 B5 | VIS·BE | 저장 결제수단 빠른결제 왕복 | +| F-B6 | 행사 라이브 공지 피드/현장 푸시 — 알림센터에 더해 행사별 라이브 공지(긴급·프로그램 변경) | §5B notification·M12 | SCR-M11·M5 | 벤치 §2⑤·§3 B6 | VIS·COM | 라이브 공지 발행·푸시 수신 | + +### ⓒ 신규 (P2) — 신규 화면/기능 후보 +| ID | 작업 | 대상 모듈 | 관련 화면 | 출처 | 담당 | 완료 기준 | +|---|---|---|---|---|---|---| +| F-C1 | 티켓 오픈 알림·관심 행사 구독 — 오픈 예정 행사 구독→오픈 시 푸시/EDM | M10·M12 | 신규(공개사이트·앱) | 벤치 §2⑤·§3 C1 | VIS·CMS | 구독→오픈 알림 발송 | +| F-C2 | 관람객 앱 주차 연계 — iparking 실시간 현황·주차비 결제·사전 주차권 | M14·M10 | 신규 SCR-M(주차) | 벤치 §2⑥·§3 C2 | VIS·kintex-mobile-dev·BE | 주차 현황 조회·결제 연계 | +| F-C3 | 관람객 대면 혼잡/대기 안내 — 입장·주차·인기 세션 실시간 혼잡도(현행 M14는 홀매니저용) | M14 | 신규 위젯(SCR-M5) | 벤치 §2⑥·§3 C3 | VIS·BE | 혼잡도 위젯 표시 | +| F-C4 | 관람객↔관람객 QR 명함 교환·컨택트 지갑 — 리드캡처(업체→관람객) 외 관람객 상호 교환 | M11 | SCR-M8 확장 | 벤치 §2②·§3 C4 | VIS | QR 교환·컨택트 저장 | +| F-C5 | 인기 세션/바이어 미팅 예매 대기열·취소표 알림 — 정원 초과 대기 우선권 | M11 | SCR-M9·M8 | 벤치 §2⑤·§3 C5 | VIS·AI | 대기 등록·취소표 알림 | +| F-C6 | 관람객 멤버십/등급 — 일반/바이어/VIP·재방문·바이어 인증 등급별 혜택·매칭 우선순위 | M10 | 신규 마이 | 벤치 §2⑦·§3 C6 | VIS·ADM | 등급 산정·혜택 차등 | +| F-C7 | 최근 본 행사·부스 개인화 홈 피드 — 재방문 전환 | M10·M12 | SCR-M5 확장 | 벤치 §2⑤·§3 C7 | VIS | 최근 본 이력·피드 | +| F-C8 | 셀프 체크인 키오스크·즉석 배지 인쇄 화면 — PLANNING M10 즉석배지 화면화 | M10 | 신규 SCR | 벤치 §2③·§3 C8 | VIS·FE | 키오스크 체크인·배지 인쇄 | + +## 진행 규칙 +- **Phase B(공통 레이어)는 전 도메인 선행 기반** — C/D 착수 전 인증·시스템관리·공통기능 정착. +- 각 모듈 완성 직후 QA 점진 검증. 보안 불변(자격증명·PII·스택트레이스 미노출·AI 워터마크·등록업체 응찰·admin env) 반려 사유. +- 기획=planner, 디자인=designer 경유. 아키텍처 표준(Phase A) 위반은 시정. +- **Phase F는 벤치마킹 유래 추가 백로그**(P1 보강 6·P2 신규 8) — 기존 SCR-P7/P8·M14/M15 등 화면 반영은 designer 경유, 모듈 반영은 planner 경유. 착수 우선순위는 벤치 §3 톱5(F-B1·F-B2·F-C1·F-C2·F-B3). + +--- + +## 변경 이력 +| 날짜 | 변경 내용 | +|---|---| +| 2026-07-11 | 백로그 v2.0 최초 재작성 | +| 2026-07-11 | Phase F 신설 — 티켓·관람객 벤치마킹 유래 항목 14개(ⓑ 보강 6 F-B1~B6 · ⓒ 신규 8 F-C1~C8) 추가. 근거 `docs/analysis/ticketing-app-benchmark.md`. 기존 항목 무수정 | diff --git a/plugins/zio-harness/knowledge/kintex/docs/OPS_RUNBOOK.md b/plugins/zio-harness/knowledge/kintex/docs/OPS_RUNBOOK.md new file mode 100644 index 0000000..21ed108 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/OPS_RUNBOOK.md @@ -0,0 +1,135 @@ +# KINTEX 운영 런북 — 헬스체크 · 재기동 · 롤백 + +> 킨텍스 개발/운영 서비스의 상태 점검·재기동·배포 검증·롤백 절차. GUARDiA 운영 관행 준용. +> **대상**: 개발 `kintex.zioinfo.co.kr` → 101.79.17.164, 백엔드 포트 **8021**. 운영 `kintex.wise.ai.kr`(후속). +> **보안**: 서버 접속 자격증명은 사내 비밀관리에서 조달(이 문서·스크립트에 미기재). root SSH 는 GUARDiA 인프라 예외(소유자 승인). + +--- + +## 0. 서비스 토폴로지 + +| 구성요소 | 실행 단위 | 포트/경로 | 헬스 | +|----------|-----------|-----------|------| +| 백엔드 API | systemd `kintex.service` (`/opt/kintex/app/app.jar`) | 8021 | `GET /health` → `data.status=UP` | +| 나노바나나 워커 | systemd `kintex-nanobanana.service` (Python) | Redis 큐 소비 | 큐 소비 로그 / 프로세스 active | +| 프론트(웹) | nginx 정적 (`/var/www/kintex`) | `kintex.zioinfo.co.kr` :80/443 | 페이지 200 | +| nginx vhost | `deploy/nginx/kintex.zioinfo.co.kr.conf` | `/`=정적, `/api/`·`/ws`=8021 | — | +| DB | PostgreSQL `kintex_db` (+PostGIS) | 5432(내부) | `SELECT 1` | +| 큐 | Redis | 6379(내부) | `redis-cli ping`→PONG | +| 배포 | `deploy_server.py`(webhook 수신) | 9999 | 로그 | + +의존: 백엔드 → PostgreSQL·Redis. 워커 → Redis·Gemini(G1). 프론트 → nginx → 백엔드. + +--- + +## 1. 헬스체크 (가장 먼저) + +**자동(권장)** — 스모크 러너로 배포·라우터 상태를 한 번에: +```bash +# 로컬 PC에서 SSH 경유 (env: KINTEX_SSH_HOST, KINTEX_SSH_PASSWORD) +python tools/test/kintex_smoke_test.py +# 서버(같은 호스트)에서 +python tools/test/kintex_smoke_test.py --local +# 도메인 직접 +KINTEX_BASE=https://kintex.zioinfo.co.kr python tools/test/kintex_smoke_test.py --http +``` +종료코드 0=전체 통과. 결과 `tools/test/_results/latest.json`. + +**수동** — 서버에서: +```bash +curl -s http://127.0.0.1:8021/health # {"success":true,"data":{"status":"UP","service":"kintex-backend",...}} +systemctl is-active kintex.service kintex-nanobanana.service +redis-cli ping # PONG +sudo -u postgres psql -d kintex_db -c 'SELECT 1;' +``` + +정상 판정: `/health` 200 + `status:UP` + 두 서비스 `active` + Redis PONG + DB 응답. + +--- + +## 2. 로그 확인 + +```bash +journalctl -u kintex.service -n 200 --no-pager # 백엔드 +journalctl -u kintex-nanobanana.service -n 100 --no-pager # 워커 +tail -n 100 /tmp/kintex_gradle.log # 최근 빌드 로그 +nginx -t && tail -n 50 /var/log/nginx/error.log # nginx +``` +> 로그에 자격증명·API키가 보이면 **즉시 보안 이슈**로 에스컬레이션(SECURITY §2). + +--- + +## 3. 재기동 + +```bash +# 백엔드만 +systemctl restart kintex.service && sleep 5 && curl -s http://127.0.0.1:8021/health + +# 워커만 (이미지 생성 멈춤·큐 적체 시) +systemctl restart kintex-nanobanana.service + +# 프론트/nginx (정적 서빙 이상) +nginx -t && systemctl reload nginx + +# DB/Redis 이슈는 공유 인스턴스 — 재기동 전 타 솔루션 영향 확인 후 소유자 승인 +``` + +부팅 자동기동: 두 유닛 모두 `enable` 상태여야 한다(`systemctl is-enabled kintex.service`). + +--- + +## 4. 배포 (webhook 자동) + +정상 경로는 **자동**이다: +``` +scripts/push_kintex.py "메시지" → Gitea(zio/kintex) push → webhook(#47) → deploy_server + → git pull → npm build → gradlew bootJar → jar 검증 → deploy_kintex.sh(원자교체) → /health 게이트 +``` +- 배포 후 검증: `python tools/test/kintex_smoke_test.py` (health + 라우터 등록). +- **수동 Jenkins 트리거 추가 발사 금지** — 동일 repo 동시 빌드 시 `target/*.jar` 교체가 깨진다(GUARDiA 함정). +- `deploy_kintex.sh` 는 자기방어: 프론트/백엔드 빌드 → jar 검증(`KintexApplication.class` 존재) → 원자 교체 → 헬스체크 → 실패 시 이전 jar 롤백. + +--- + +## 5. 롤백 + +### 5-1. 자동 롤백(기본) +`deploy_kintex.sh` 가 헬스체크 실패 시 **이전 jar 를 유지/복원**한다. 배포 후 `/health` 가 200이 아니면 스크립트가 롤백하고 실패로 종료 → deploy_server 가 ITSM 에 실패 알림. + +### 5-2. 수동 롤백 (자동 실패 시) +```bash +# 백엔드 이전 버전으로 (배포 스크립트가 백업본을 남기는 위치 확인) +ls -lt /opt/kintex/app/*.jar* /opt/kintex/app/backup/ 2>/dev/null +cp /opt/kintex/app/app.jar.bak /opt/kintex/app/app.jar # 백업 규약에 맞춰 +systemctl restart kintex.service && sleep 5 && curl -s http://127.0.0.1:8021/health + +# 소스 롤백(직전 커밋으로 재배포) +git -C /opt/kintex/src log --oneline -5 +git -C /opt/kintex/src reset --hard <직전_정상_커밋> +bash /opt/kintex/src/deploy/deploy_kintex.sh /opt/kintex/src +``` + +### 5-3. 스키마 롤백 주의 +Flyway 마이그레이션은 **전진(forward)만** 권장. 잘못된 마이그는 되돌리지 말고 **보정 마이그레이션(다음 번호)** 를 추가한다. `baseline-on-migrate=true` 이므로 운영 DB 임의 롤백 금지(GUARDIA_ALIGNMENT §4). + +--- + +## 6. 자주 겪는 이슈 (GUARDiA 교훈 반영) + +| 증상 | 원인 후보 | 조치 | +|------|-----------|------| +| `/health` 200인데 특정 API 404 | 라우터 미배포(구 jar) | 스모크 러너로 라우터 등록 확인 → 재배포 | +| API 500 `relation ... does not exist` | 마이그 미적용 | Flyway 상태 `flyway info`, 보정 마이그 추가(§5-3) | +| 이미지 생성 안 됨 / degraded | G1 미승인·`GEMINI_API_KEY` 미설정·워커 다운 | 워커 로그·env 확인, 워커 재기동. 키는 워커 env only | +| 배포 로그 "완료"인데 반영 안 됨 | deploy_server 블록 부재·1ms no-op | 서버 `/opt/zioinfo/deploy_server.py` 에 kintex 블록 반영·`zioinfo-deploy` 재시작 확인 | +| 빌드 OOM | 공유 8GB 동시 빌드 | 직렬 빌드 준수, 타 솔루션 빌드와 겹치지 않게 | +| push 했는데 자동배포 안 돎 | webhook 미설정/시크릿 불일치 | Gitea webhook #47 활성·secret 일치·URL localhost 확인 | + +--- + +## 7. 참조 + +- 배포 개요: [`BUILD_DEPLOY.md`](BUILD_DEPLOY.md) · 환경: [`ENV_SETUP.md`](ENV_SETUP.md) +- 정합·스키마 갭: [`GUARDIA_ALIGNMENT.md`](GUARDIA_ALIGNMENT.md) · 보안: [`SECURITY.md`](SECURITY.md) +- 배포 블록(정본 사본): `deploy/deploy_server_kintex_block.py` · 배포 스크립트: `deploy/deploy_kintex.sh` +- 스모크 러너: `tools/test/kintex_smoke_test.py` · 경량 push: `scripts/push_kintex.py` diff --git a/plugins/zio-harness/knowledge/kintex/docs/OWNER_FEEDBACK.md b/plugins/zio-harness/knowledge/kintex/docs/OWNER_FEEDBACK.md new file mode 100644 index 0000000..f68e6f5 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/OWNER_FEEDBACK.md @@ -0,0 +1,184 @@ +# 소유자 피드백·지시 로그 (KINTEX AI 전시·행사시스템) + +> 이번 세션에서 소유자가 지시한 모든 항목을 전수 기록한다. 상태: ✅완료(배포) · 🚚배포중 · ⏳작업중 · 📋대기. +> 이 파일을 기준으로 누락 없이 처리한다. 새 지시는 여기에 추가한다. +> 최종 갱신: 2026-07-12 + +--- + +## 1. 디자인 시스템 (Nifty / WISE) — 최우선 반복 지시 + +| # | 지시 | 상태 | 비고 | +|---|------|------|------| +| 1.1 | **Nifty 카드 타입** 적용 (https://preview.themeon.net/nifty/ui-elements/cards/) — 라운딩·그림자·헤더/바디/푸터 구조·보더 톤 | 📋대기 | `.kxp-ecard`는 8px 라운딩 있으나 Nifty 카드 구조 전면 정렬 필요. 다음 패스 | +| 1.2 | **그리드는 Nifty Advanced table headers**로 통일 (tables/static-tables) | ⏳작업중 | 정본 `.kx-table` 존재, 미준수 6화면 수렴 (감사완료) | +| 1.3 | **Tabulator 기능** 추가 (tables/tabulator — 정렬·필터·페이지·CSV) | 📋대기 | task #32 | +| 1.4 | **상세페이지 = Nifty blog** 스타일 (blog-apps/blog) | 📋대기 | task #33 | +| 1.5 | **버튼 = Nifty buttons**, **Dropdowns**, **컴포넌트**, **List Group**, **Typography/Modals/Offcanvas** = ui-elements 전체 채택 | ⏳부분 | Offcanvas 완료, 나머지 정렬 진행 | +| 1.6 | **Nifty 스타일 학습 md 생성** | ✅완료 | `docs/DESIGN_SYSTEM_NIFTY.md`·`docs/analysis/nifty-design-refs.md` | +| 1.7 | **아이콘은 선(line/stroke) SVG**로 직접 (이모지 금지) | ✅원칙 | 전 신규화면 준수 | +| 1.8 | **UI는 WISE(UIWS) 문자 그대로** — 셸·메뉴·캘린더 자체 재해석 금지 | ✅원칙 | 메모리 [[ui-follow-wise-strictly]] | +| 1.9 | **폰트를 페이지마다 안 맞춤** — 전 화면 타이포 일관화 | ⏳작업중 | 감사완료(하드코딩 262건/36파일). `--fs-micro`·공용 `.kx-page__title`·weight 토큰 신설로 정렬. 다음 패스 | +| 1.10 | **모든 경계선 엷은 회색** | ⏳부분 | 구조 보더는 neutral-200(#e4e7ec) 사용 중. 의미색·hover는 유지, 지정화면 정렬 | +| 1.11 | **좌우 2단 폭 50:50**, 전 화면 **공백 없는 반응형**(풀블리드) | ✅원칙 | task #39 스윕 대기 | +| 1.12 | **top 설정 아이콘** 추가 + **설정 레이아웃 커스터마이저**(offcanvas 테마/레이아웃/색상) | ⏳부분 | 설정 아이콘 완료, 커스터마이저 task #43 | + +## 2. 캘린더 + +| # | 지시 | 상태 | +|---|------|------| +| 2.1 | 캘린더를 **Nifty app-views/calendar**처럼 (옅은 회색 격자·연한 today·가벼운 이벤트 칩) | 🚚배포중 | 큰 캘린더 재스타일 완료(격자 neutral-100·today 연노랑·소프트 칩), 배포 중 | +| 2.2 | **공휴일 붉은색 + 일자 옆 공휴일명** (2050년까지 데이터) | 🚚배포중 | 큰 캘린더+미니 달력 배선. 7월은 공휴일 없음(8/15·9월 추석 표시) | +| 2.3 | **달력 경계선 모두 회색** | 🚚배포중 | 미니 달력 셀 회색 테두리 추가 | +| 2.4 | 일정 **월/주/일** 뷰 (WISE CalendarView) | ✅완료 | +| 2.5 | 전시 일정 50:50 비율·달력 날짜 위로(하단 공백 제거) | ✅완료 | + +## 3. 공개사이트 / 메인 / visitor + +| # | 지시 | 상태 | +|---|------|------| +| 3.1 | **첫 화면 = 제품 소개** (미인증 루트는 히어로 랜딩, 로그인 폼만 노출 금지) | ✅완료 | 메모리 [[product-identity-first]] | +| 3.2 | 제품명 **'KINTEX AI 전시·행사시스템'** | ✅완료 | +| 3.3 | **visitor 메인 = 세련된 홈페이지** (AI 관람 도우미 중심) | 🚚배포중 | AiAssistant·기능타일·연월 브리핑·쇼케이스 구현 | +| 3.4 | 메인에 **AI 기능 전면 노출** (AI가 뭘 하는지 한눈에) | 🚚배포중 | AI 기능 쇼케이스 6타일 | +| 3.5 | AI가 답하는 정보는 **크롤링해서 DB 저장** (실시간 외부호출 X) | ✅완료 | V43 visitor_guide·transport, 공개 AI API 근거응답 | +| 3.6 | **AI는 전시·행사정보 학습** (근거 기반) | ✅완료 | grounding + 인용, 환각 차단 | +| 3.7 | **AI가 연간·월간 전시·행사 기획정보 제시** | 🚚배포중 | AiPlanningBriefing(연/월 토글) | +| 3.8 | 비지터가 **가장 알고 싶은 정보를 AI로 쉽게** | ✅설계 | 관람 도우미 예시칩·구조화 카드 | +| 3.9 | 코엑스 분석 → **visitor/business/agency 3-트랙** 분리 | ✅완료 | 관문 + 3 서브홈 + TrackSwitcher | +| 3.10 | **"코엑스처럼" 전면 리뉴얼** (히어로 배경·애니메이션·비주얼) | 🚚배포중 | design.md v2.4 §3C-V, 코엑스풍 비주얼·모션 구현 | +| 3.11 | 메인 카드가 **밋밋한 파란 placeholder** (포스터 이미지 없음) | ✅완료 | V46 실제 포스터 이미지로 교체(배포됨) | +| 3.12 | **메인 카드 이미지 크기 안 맞음**(세로 포스터가 16:11 가로 프레임에 늘어남/잘림) | ⏳수정됨 | 포스터 실측 세로 0.67~0.8 → 카드 미디어 3:4 프레임 + `.kxp-ecard__poster` `object-fit:cover`(왜곡 제거). 다음 배포 | +| 3.13 | **메인 히어로 이미지 5장 회전(슬라이드)** | ⏳착수 | 크롤러가 KINTEX 전시장/시설 히어로 이미지 5장 `public/media/hero/` 확보 → 프론트 히어로 회전 UI(배포 후) | + +## 4. 역할 · 네비게이션 + +| # | 지시 | 상태 | +|---|------|------| +| 4.1 | **로그인 사용자 구분으로 메인페이지 + 메뉴 그룹 결정** (디폴트 visitor, 로그인 후 business/admin/agency) | 🚚배포중 | plan_role_routing 구현(admin→/admin·agency→/contractor·visitor→/visitor·ops/business→/home) + 역할별 메뉴 게이트 | +| 4.2 | **각 트랙 메인페이지 Stitch 디자인 의뢰** | ✅부분 | Stitch 2회 실패 → design.md 스펙 직접 구현(문서화 폴백) | +| 4.3 | **모바일 앱도 동일 로직** | 📋대기 | 웹 완료 후 모바일 반영 | +| 4.4 | **상세→메인 복귀·브레드크럼·404** 내비게이션 | ⏳ | renewal 하네스 | + +## 5. 데이터 / 시드 + +| # | 지시 | 상태 | +|---|------|------| +| 5.1 | **모든 테이블에 데이터** (50~100건) | ✅완료 | V42 대량시드(40테이블 2,535행) | +| 5.2 | **정산·결제 데이터 없음** — 행사스코프 정렬 | 🚚배포중 | V47: 데모 해소행사 `e-2026-live`에 정산 폐루프+옥션+관람객+리드+캠페인 | +| 5.3 | 테스트 데이터 **더 현실적으로** | ✅완료 | V39·V42 실감형 | +| 5.4 | 행사정보 **크롤링해서 데이터 넣기** | ✅완료 | 크롤 시드 | +| 5.5 | **연간·월간 전시 기획정보**도 적재 | ✅완료 | V43 event 생성열·v_event_calendar 뷰 | +| 5.6 | 포스터 이미지 **다 다운받아 빌드 내장** | 🚚배포중 | V46 34장 `/media/posters/` | + +## 6. 정산·도메인 화면 + +| # | 지시 | 상태 | +|---|------|------| +| 6.1 | **정산·결제 패딩 없음** | 🚚배포중 | `.kx-settle` 패딩 추가 | +| 6.2 | **참가업체 관리가 홈으로 감** — 전용 화면 신설 | 📋대기 | task #41 | +| 6.3 | 부서 관리 = **WISE 조직도** | ✅완료 | +| 6.4 | 결재관리 **반려·재상신·결재선** (WISE) | ✅완료 | +| 6.5 | 통합검색에 **행사·전시 포함** | ✅완료 | +| 6.6 | 시스템관리 **메시지 관리**({} 플레이스홀더+샘플) | 📋대기 | task #35 | +| 6.7 | 물류허브·서류/마일스톤·CMS·일정 = WISE | ✅완료 | +| 6.8 | **그룹권한(역할↔메뉴) 메뉴** 존재 확인 | ✅확인 | RoleAdminPage + RoleMenuAdminPage | + +## 7. 버튼 · 색상 · 대비 + +| # | 지시 | 상태 | +|---|------|------| +| 7.1 | **파란 배경 버튼 = 흰 글자** | ✅완료 | `--color-on-accent`(다크에서도 흰색). 라이브 반영(캐시 새로고침 필요) | +| 7.2 | 다크모드 색상배경 위 **흰 글자 어두워지는 버그** 전수 수정 | ✅완료 | 77곳 on-accent. +통계밴드 2곳 추가수정(배포중) | +| 7.3 | 회색 버튼은 옅은 ghost — 흰 글자 아님(솔리드 진회색만 흰글자) | ✅확인 | + +## 8. 파비콘 · 브랜드 + +| # | 지시 | 상태 | +|---|------|------| +| 8.1 | **KINTEX favicon** 추가 (홈페이지 크롤) | ✅완료 | 리포 favicon.ico가 톰캣 아이콘이던 것 규명→KINTEX .ico 재생성(v3) | +| 8.2 | **브랜드 밑에 영어 병기** | ✅완료 | "AI Exhibition & Event System" | + +## 9. 모바일 + +| # | 지시 | 상태 | +|---|------|------| +| 9.1 | **내정보 (WISE 참조) + 생체인식 + 사진등록** | ✅완료 | app/profile, expo-local-authentication, expo-image-picker. 아바타 API(백엔드) 완료 | +| 9.2 | **전시·공연 앱 벤치마킹** (다운로드·좋아요 상위순) | ✅완료 | docs/analysis/mobile-benchmark-exhibition-performance.md + 백로그 12항목 | +| 9.3 | **앱 위변조 방지 + 시큐어 코딩 + 보안 체크리스트 통과** | ✅완료 | 루트/탈옥·무결성·Hermes+R8·화면캡처·cleartext·권한최소. 체크리스트/감사 문서 | +| 9.4 | **다국어** — 웹 4개국어 완비, 모바일은 한국어(백로그) | ⏳ | 웹 ✅(ko/en/zh/ja), 모바일 i18n 미도입(MB-11) | + +## 10. AI + +| # | 지시 | 상태 | +|---|------|------| +| 10.1 | **AI 기능 쉽게 사용 + 토큰 최소화** | ✅완료 | PLANNING v3.4 §8A(결정론 라우팅·소형모델 우선·RAG축소·캐싱·집계는 SQL·측정지표) | +| 10.2 | AI 기능이 **하나도 구현 안 된 것 같다 → 구현** | ✅완료 | 공개 AI 관람 도우미 라이브(grounded=true, Claude) | +| 10.3 | 나노바나나 유료? | ✅답변 | Google Gemini 유료 | + +## 11. 데이터 아키텍처 (표준) + +| # | 지시 | 상태 | +|---|------|------| +| 11.1 | **FK 최소화, 공통코드로 관리** | ✅표준 | docs/architecture/data.md §10 (소프트참조·공통코드) | +| 11.2 | **필요한 인덱스 생성** | 🚚배포중 | V44 성능 인덱스 8건(핫패스) — 이미 배포됨 | +| 11.3 | **view/mview/function 고려** | ✅표준 | data.md §11 | +| 11.4 | **자동화 배치·프로시저 고려** | ✅표준 | data.md §13 배치 카탈로그 | +| 11.5 | **ten_id/tenant_id PK 맨 앞 복합키** | ✅원칙 | 메모리 [[tenant-id-pk-standard]] | + +## 12. 인증 / SSO / HR + +| # | 지시 | 상태 | +|---|------|------| +| 12.1 | **직원 인사(조직) 정보는 API 방식** | ✅설계 | docs/architecture/sso-hr-integration.md (HrDirectoryClient 어댑터+스냅샷) | +| 12.2 | **Open SSO 도입** | ✅설계 | Keycloak OIDC(PKCE)+SAML, 기존 JWT+2FA 공존(브로커) | + +## 13. 평면도 / 기타 + +| # | 지시 | 상태 | +|---|------|------| +| 13.1 | 도면 안 열림 / AI 시각화 어디감 | ✅원인 | 403(행사 미가입) → 데모계정 멤버십 해소. DWG는 SVG캔버스+JPG 렌더(DWG 바이너리는 좌표소스) | +| 13.2 | ReRoomAI 기능 (나노바나나 image-to-image) | ⏳ | visualizer 트랙 | + +--- + +## 미해결·대기 요약 (다음 우선 처리) + +1. **Nifty 디자인 시스템 전면 정렬** — 카드(ui-elements/cards)·폰트(--fs-micro·공용 제목클래스)·그리드(.kx-table 6화면) 일괄 (1.1·1.2·1.9) +2. **참가업체 관리 전용 화면** (6.2 / task #41) +3. **메시지 관리** (6.6 / task #35) +4. **Tabulator**·**상세 Nifty blog**·**설정 커스터마이저** (1.3·1.4·1.12 / task #32·33·43) +5. **전 화면 공백없는 반응형 스윕** (1.11 / task #39) +6. **모바일 역할 랜딩·다국어** (4.3·9.4) +7. **상세→메인 내비게이션** (4.4) + +--- + +## 처리 로그 (내가 처리·배포한 것 — 2026-07-12 세션) + +**배포 완료 (라이브):** 커밋 214b6df → 6e95ac6 → 87f310f/55e27b3 → 3077cb0 +- V42 대량시드(40테이블 2,535행) · V43 관람객 가이드/연월 캘린더 뷰 · V44 성능 인덱스 8건 · V45 아바타 컬럼 · V46 포스터 로컬화(73건) · V47 e-2026-live 정산 폐루프 +- 공개 AI 관람 도우미 API(grounded·Claude) · 연월 캘린더 API · 3-트랙 관문/서브홈 · 역할별 랜딩+메뉴 게이트 +- 미니/큰 캘린더 공휴일 표시·회색 테두리·Nifty 톤 · 코엑스풍 공개사이트 비주얼(히어로·모션·통계밴드) · 실제 포스터 이미지 +- 파란버튼 흰글자(`--color-on-accent`) · 다크모드 흰글자 77곳 · favicon(톰캣→KINTEX v3) · 2FA 방패 아이콘 · 브랜드 영문병기 · 정산 패딩 + +**구현 완료 (미배포 — 다음 배포 대기):** +- **Nifty 디자인 시스템 정렬**(카드 `.kx-card` Nifty 구조·`--fs-micro`/`--fw-*` 토큰·공용 제목클래스·테이블 `.kx-table` 6화면 수렴, font 179+weight 415 토큰화) +- **카드 이미지 3:4 프레임 + object-fit cover**(왜곡/잘림 제거) +- **메시지 관리 백엔드**(V48 sys_message + 렌더 API + 36샘플) +- **통계밴드 흰글자 2곳** · **푸터 "2026 © KINTEX..."** 4개국어 + +**병렬 진행 중:** 모바일 다국어+역할랜딩 · 잔여 데이터 보강(V49) · 산출물 문서 + +**설계·표준 문서 산출:** PLANNING v3.4(AI 토큰최소화 §8A) · design.md v2.4(공개 비주얼·모션) · docs/architecture/data.md(FK최소화·공통코드·view/mview·배치) · sso-hr-integration.md(Open SSO+HR) · DESIGN_SYSTEM_NIFTY.md · mobile-security-*.md · mobile-benchmark-*.md + +## 산출물(문서) 상태 + +| 산출물 | 타이밍 | 상태 | +|--------|--------|------| +| 개발계획서 | 개발 전/중 | 📋 생성 착수(PLANNING v3.4 기반) | +| 설계서(아키텍처·ERD·화면·API) | 개발 중 | 📋 생성 착수(design.md v2.4·architecture·backend 계약 기반) | +| 사용자 지침서 | **완성+QA 후**(최종 메뉴 반영) | ⏳ UI 정렬 안정화 후 — 지금 생성 시 재작업(정책: 최종 1회) | +| 운영자 지침서 | **완성+QA 후** | ⏳ 동일 | + +> 정책([[deliverables-update-policy]]): deliverables는 최초 1회 + 최종 1회. 개발계획서·설계서는 지금 생성 가능(내용 안정), 지침서는 현재 UI 정렬 파동이 끝난 뒤 최종 메뉴 기준으로 1회 생성. diff --git a/plugins/zio-harness/knowledge/kintex/docs/PLANNING.md b/plugins/zio-harness/knowledge/kintex/docs/PLANNING.md new file mode 100644 index 0000000..fe48e22 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/PLANNING.md @@ -0,0 +1,1272 @@ +# 킨텍스 AI 전시·행사시스템 (KINTEX AI Exhibition & Event System) 기획서 + +> 작성: 기획 에이전트(planner) · 작성일: 2026-07-11 · 최종 갱신: 2026-07-12 · 버전: **v3.4** +> **제품 공식 명칭(소유자 확정 2026-07-12): "KINTEX AI 전시·행사시스템"** — 기존 "자동전시시스템(Exhibition Automation Platform)"을 대체한다. 전시(exhibition)뿐 아니라 행사·이벤트(event) 전반을 포괄한다는 의미를 명칭에 반영. 본 명칭이 정본이며, 이하 본문·3-트랙 기획·타 문서 후속 반영 시 이 명칭을 사용한다(기존 "자동전시시스템" 표기는 문맥 보존을 위해 삭제하지 않고 잔존하나, 신규 표기는 정본 명칭을 따른다). +> 근거 문서: `docs/analysis/kintex-website.md` (킨텍스 웹사이트 25개 페이지 + 전시주최자매뉴얼 PDF + 참가업체 매뉴얼 PDF 전수 분석, 2026-07-11) +> 근거 문서: `docs/analysis/coex-website.md` (코엑스 VISITOR/BUSINESS/CYBER 3-사이트 IA 분석 + 킨텍스 대비표, 2026-07-12) — §2-2 대외 접점 3-트랙 재구성 확정 근거 +> 근거 문서: `docs/analysis/reroomai-source.md` (ReRoomAI 이미지 파이프라인 소스 분석, 2026-07-11) — 6장 나노바나나 파이프라인 제어 파라미터 확정 근거 +> 근거(글로벌 벤치마크, 2026-07-11 크롤링): Eventleaf·VenueSight·Whova·ExpoPlatform(전시관리·부스판매·리드캡처), Eventbase·Pointr·Swapcard·Brella·Grip(wayfinding·비즈매칭), RainFocus·Bizzabo(등록·리벤뉴), ExhibitForce·Ways·FinancialModelsLab·Digitevent(전시 BI/KPI), FindRFP·Procore·4castplus(RFQ/Tender/역경매). 각 §5 모듈에 매핑. +> +> **v2.0 정체성 확장**: 본 시스템은 "부스 시공 도구"를 넘어 **킨텍스 자동전시시스템(Exhibition Automation Platform)** 이다 — 전시 기획·판매·시공·운영·관람객·사후분석 전 주기를 아우른다. 기존 M2~M5 부스 시공 코어(P0)·나노바나나 파이프라인(§6)·확정 스택(§8)은 **보존**하고, 그 위에 관람객/비즈매칭/마케팅·공개사이트/wayfinding/현장운영/공사 옥션/BI/CMS/관리자 모듈(M10~M18)을 확장한다. +> **v3.0 정체성 확장 — 다중 전시관 SaaS**: 본 시스템은 **킨텍스 전용에서 다중 전시관(Venue) 멀티테넌트 SaaS**로 확장한다. 킨텍스(KINTEX)는 **기준 테넌트(테넌트 #1)** 로 유지되고, 코엑스(COEX) 등 여타 전시관을 테넌트로 온보딩한다. 기능(M1~M18·§5B·§6 나노바나나·§8 확정 스택)은 **전부 보존**하고, 그 위에 **테넌트 격리 레이어(tenant_id 전파·컨텍스트 해소·역할 계층)** 만 얹는다 — 기능은 그대로, 데이터·권한·컨텍스트가 전시관 단위로 분리된다. 상세는 **§1A**, 격리 전략은 **§8-2**. +> **v3.2 대외 접점 3-트랙 재구성**: 코엑스(COEX) IA 분석(3-사이트 분리: VISITOR/BUSINESS/CYBER)을 근거로, 대외 접점을 **visitor(관람객) / business(비즈니스=주최자·참가업체) / agency(에이전시=공사·장치·협력사)** 3개 트랙으로 분리·재편한다. 기존 6역할·7페르소나(§2)·포털 매트릭스(§2-1)·모듈(M1~M18)·화면(SCR-*)은 **전부 보존**하고, 그 위에 **트랙 셸(track shell) — 랜딩 3-분기 + 트랙별 서브홈 + 트랙-스코프 로그인 후 홈** IA 레이어만 얹는다. 상세는 **§2-2**(내부 역할 ops·admin은 대외 트랙 외부에 그대로 유지). +> **v3.4 AI 사용성 & 토큰 최소화**: 소유자 지시(2026-07-12) — "AI 기능을 쉽게 사용하도록 기획 + 토큰을 최소한으로 사용하는 방식 채용". 산재해 있던 AI 규약을 **§8A**로 명문화한다 — ① AI 사용성 표준(전 화면 인라인 진입점·예시 질문 칩·원탭 액션·다음 명령 제시·구조화 카드+근거 인용·대화 히스토리·다국어/모바일/음성) ② 토큰 최소화 6원칙(결정론 우선 라우팅으로 LLM 우회·소형모델 우선 티어링·RAG 발췌로 프롬프트 축소·캐싱·출력 상한/구조화·집계는 SQL) ③ 측정지표·목표 ④ design/개발 계약 포인트. 기존 스코프(§5B 공통 AI·§6 나노바나나·§8 스택·§8-2 격리)·화면·라우트 보존, 원칙·계약·지표만 순증. M10 관람객 AI 도우미·M16 BI·§5B 공통 AI 보조에 §8A 링크. 이미 진행 중(visitor-assistant DB 근거 응답·AiTextRouter Claude→Ollama 폴백)과 정합(재발명 아님·표준화). src·design.md 미수정(designer/backend 후속). +> **v3.3 로그인 사용자 구분 → 메인페이지·메뉴 그룹 결정 규칙**: 소유자 확정(2026-07-12) — **"로그인한 사용자의 사용자 구분으로 메인페이지가 결정되고, 좌측 메뉴 그룹도 결정된다."** §2-2의 3-트랙(visitor/business/agency) + 내부 역할(ops/admin) 위에, **미인증 기본 진입 = visitor 공개 관람 랜딩**, **인증 후 역할별 전용 메인**(business 메인·agency 메인·visitor 메인은 신규 화면 — designer Stitch 의뢰, admin/내부 = 관리 메인 또는 비즈니스 메인+시스템관리)과 **트랙별 좌측 메뉴 그룹 노출/숨김**을 결정하는 규칙을 **§2-3**에 확정한다. 기존 §2·§2-2·화면(SCR-*)·라우트는 보존(안 B 정합), 결정 규칙·트랙 메인 화면 목록만 순증. src·design.md 미수정(frontend·designer 후속). +> **문서 소유권**: 본 PLANNING.md는 planner만 수정한다. design.md·타 문서는 이 문서 변경 시 "designer/planner 후속 반영 필요"로만 표기하고 직접 수정하지 않는다. + +--- + +## 1. 개요 및 비전 + +### 1-1. 배경 + +킨텍스는 총 전시면적 108,011㎡(국내 최대, 2028년 제3전시장 완공 시 178,000㎡)를 운영하지만, 전시 준비 실무는 여전히 **HWP 서식 다운로드 → 이메일/방문 제출**, **CAD 수작업 배치도 → 홀매니저 육안 검수**, **수기 위치표시도 기반 유틸리티 신청**에 머물러 있다. 온라인 작업신고 시스템(kxwp.kintex.com)이 존재하나 로그인 기반 서류 업로드 창구 수준이며, 참가업체 유틸리티 신청은 킨텍스 공통 플랫폼 없이 전시회별 주최자 사무국 시스템(예: 코리아팩)에 파편화되어 있다. + +### 1-2. 비전 + +**"신청서를 내는 순간, 시공 후 사진을 먼저 본다."** + +전시장 운영 전 과정(홀 배정 → 부스 배치 → 장치공사 설계 → 전기/조명 → 네트워크/유틸리티 배선 → 반입/반출)을 AI로 자동 설계·검증하고, 그 결과를 **나노바나나(Gemini 이미지 생성 모델)로 '공사 후 결과 사진'처럼 시공 전에 미리 생성해 보여주는** 것이 본 시스템의 핵심 차별화다. + +기존 전시관리 솔루션(부스 배치 SW, 온라인 신청 포털)은 도면과 표를 보여준다. 본 시스템은 **주최자·참가업체가 도면을 읽지 못해도 의사결정할 수 있는 사진 수준의 시각화**를 제공한다. + +### 1-2-1. v2.0 비전 재정의 — 킨텍스 자동전시시스템 + +부스 시공 시각화(P0)는 여전히 심장이지만, v2.0에서 본 시스템은 전시 생애주기 전체를 하나의 데이터·계정 체계로 자동화하는 **베뉴 운영 플랫폼(Venue Operating Platform)** 으로 확장된다. 글로벌 전시테크(ExpoPlatform·VenueSight·Swapcard·RainFocus 등)가 제공하는 기능을 킨텍스 도메인에 이식하되, **킨텍스만의 차별점 — 실측 공간 데이터(PostGIS) + 나노바나나 시공 예측 이미지 — 을 관통시켜** 다른 전시테크가 하지 못하는 "설계→시각화→발주(옥션)→시공→운영→분석"의 폐루프를 완성한다. + +| 생애주기 단계 | 담당 모듈 | v1.x 대비 | +|---|---|---| +| 판매·기획 | M1(홀 배정·견적), M16(BI 수요예측·수율) | M16 신규(BI 승격) | +| 설계·시각화 (**심장, 불변**) | M2 배치 · M3 부스설계 · M4 배선 · **M5 나노바나나** | 보존 | +| 발주·계약 | M6 서류, M7 등록업체, **M15 공사/장치 옥션(입찰)**, M9 정산 | M15 신규(옥션 핵심) | +| 참가·관람 | M10 관람객 등록·배지·리드캡처, M11 비즈매칭, M12 마케팅·공개사이트, M13 wayfinding | 전부 신규 | +| 현장 운영 | M8 물류, M14 현장운영(혼잡·안전·주차·에너지) | M14 신규 | +| 사후·경영 | M16 BI(이벤트 P&L·리텐션·KPI), M17 CMS, M18 관리자 | 전부 신규 | + +이 폐루프의 핵심 연결고리가 **M15 공사/장치 옥션**이다: M2~M5가 생성한 AI 설계·물량·시공 예측 이미지가 곧 **역경매(reverse auction) 응찰의 근거 자료**가 되어, 참가업체/주최자가 사진 수준 자료를 보고 시공 발주까지 한 흐름에서 종결한다. + +### 1-3. 목표 (정량) + +| 목표 | 현재 (As-Is) | 목표 (To-Be) | 근거 | +|---|---|---|---| +| 홀 배정 견적 회신 | 문의→협의→견적 수일 | 즉시 자동 견적 (2,250원/㎡ × 성수기/전시장 규칙) | 요율이 규칙화 가능 | +| 부스 배치도 초안 작성 | 주최자 CAD 수작업 수일~수주 | 조건 입력 후 수 분 내 복수 안 생성 | 홀 규격(63×171m 등) 공개 | +| 도면 규정 검수 | 홀매니저 육안 검토 | 규정 위반 자동 플래깅(높이 5m, 방염 등) 후 사람 확정 | 규정이 수치화되어 있음 | +| 유틸리티 위치표시도 | 참가업체 수기 작도 | 부스 좌표 클릭 → 자동 배선안 + 자동 견적 | 트렌치 위치·단가 공개 | +| 시공 결과 예측 | 불가(조감도 별도 외주) | 표준 샷 세트 자동 생성(부스 정면/야간 조명/통로 뷰) | 나노바나나 파이프라인 | + +### 1-4. 범위 제외 (Non-Goals) + +- 킨텍스 임대계약 자체의 법적 체결(전자계약)은 Phase 3 이후 검토 — 초기에는 견적·서류 준비까지만. +- 구조계산서의 **구조 안전성 판정 자체를 AI가 대신하지 않는다.** (규정 항목 체크·누락 검출까지만, 최종 판정은 구조기술사/킨텍스) +- 관람객 대상 서비스(주차·티켓)는 P2 부가 범위. +- **멀티테넌시(§1A)는 데이터·권한 격리 레이어**이며, 전시관별 신규 도메인 로직(전시관 고유 규정 파서 등) 자동 생성은 Non-Goal — 새 전시관 온보딩은 마스터데이터 입력(§1A-5·§8-2) 수준까지. + +--- + +## 1A. 멀티테넌시 (다중 전시관 SaaS) — v3.0 + +> **핵심 원칙**: 기능·화면·모듈(M1~M18)·나노바나나 파이프라인(§6)·확정 스택(§8)은 **전부 보존**한다. v3.0이 더하는 것은 **① 테넌트(전시관) 모델 ② 전 도메인 엔티티 `tenant_id` 전파와 격리 ③ 테넌트 컨텍스트 해소 ④ 플랫폼/테넌트 2계층 관리자 역할 ⑤ 기존 데이터의 테넌트 #1(KINTEX) 백필**뿐이다. 즉 "무엇을 하는가"는 그대로, "누구의 데이터인가(전시관 단위)"만 분리된다. + +### 1A-1. 테넌트 = 전시관(Venue) 모델 + +**테넌트가 곧 전시관이다.** KINTEX = 테넌트 #1(기준), COEX = 테넌트 #2, … 신규 전시관은 테넌트 #N으로 온보딩. 테넌트 마스터를 **최상위 스코프**로 신설하고, 기존 마스터데이터(홀·요율·규정 룰셋·부스 표준)를 **테넌트 소유(tenant-owned)** 로 재정의한다. + +| 테넌트 마스터 필드 | 내용 | 예 | +|---|---|---| +| `tenant_code` | 전시관 식별 코드(불변) | `KINTEX`, `COEX` | +| `tenant_name` | 전시관 명칭(다국어) | 킨텍스 / KINTEX, 코엑스 / COEX | +| `branding` | 로고·색상·테마 토큰(공유 디자인시스템 위 테넌트 오버라이드) | 로고 URL·프라이머리 컬러 (designer 후속 반영) | +| `domain` / `subdomain` | 접속 도메인(§1A-3 컨텍스트 해소 키) | `kintex.wise.ai.kr`, `coex.wise.ai.kr` | +| `active` | 활성/비활성(온보딩 중·종료 테넌트 게이트) | true/false | +| `locale_default` | 기본 로케일·통화·시간대 | ko-KR / KRW / Asia/Seoul | + +**테넌트 소유 마스터데이터(§7-1 재정의)**: 홀 마스터·요율표·유틸리티 요금·규정 룰셋·부스 표준·등록업체 DB는 **각 전시관이 소유**한다. 킨텍스 홀1~10(§7-1 실측값)은 **테넌트 #1의 자산**이고, 코엑스 홀(A~D홀 등)은 테넌트 #2의 자산으로 별도 등록된다. 즉 §7-1의 킨텍스 실측 마스터는 **테넌트 #1의 초기 시드**로 위치가 재정의되며, 요율(2,250원/㎡ 등)·규정(높이 5m·리깅 6.5~8.5m 등)도 전시관마다 다른 값을 가질 수 있다(코엑스 실측값은 미확보 — 온보딩 시 입력, 근거 없는 추정 금지). + +### 1A-2. `tenant_id` 전파 및 테넌트 격리 + +**전 도메인 엔티티에 `tenant_id`(FK → 테넌트 마스터)를 추가**하고, 모든 조회/쓰기를 `tenant_id`로 스코프한다(횡단 접근 원천 차단). + +| 구분 | 대상 | tenant_id 처리 | +|---|---|---| +| **테넌트 스코프(격리)** | Event·Hall·Booth·DesignPlan·UtilityOrder·RenderJob·Document·Payment · Auction·Quotation·Award · Visitor·Registration·Badge·CheckIn·Lead·Meeting · KpiSnapshot·Content·Microsite · Company(등록업체) · User membership·Role 매핑·AuditLog · MasterData(홀·요율·요금·룰셋·부스표준) | 전 행에 `tenant_id` 컬럼, 전 쿼리 `WHERE tenant_id = :ctx` 강제(§8-2) | +| **전역 참조(공유)** | 시스템 공통코드 중 도메인 불변분(국가·통화·언어 코드 등), 플랫폼 설정 | `tenant_id` 없음(전역) 또는 `tenant_id IS NULL` = 전역 + 테넌트 오버라이드 | +| **테넌트 스코프 참조** | 공종 14분류·유틸리티 요금코드·부스유형 등 전시관마다 다를 수 있는 코드 | `tenant_id` 부여(전역 기본값을 테넌트가 오버라이드) | + +- **격리 규칙(불변)**: 어떤 사용자도 자신이 소속되지 않은 테넌트의 데이터를 **조회·수정·검색·집계할 수 없다**(예외 = 플랫폼 슈퍼관리자, §1A-4). 행사(Event) 단위 RBAC(§2)는 **테넌트 내부로 스코프**된다 — 즉 "행사 격리 ⊂ 테넌트 격리"의 2중 구조. +- **공용 참조 구분**: 코드성 데이터는 "전역(플랫폼 표준) vs 테넌트 오버라이드"를 구분한다. 예: 공종 14분류는 킨텍스 기준을 전역 기본값으로 두되, 전시관이 분류 체계를 달리하면 테넌트 스코프로 오버라이드. +- **크로스-테넌트 집계**: M16 BI의 전 테넌트 통합 지표는 **플랫폼 슈퍼관리자 전용**이며 별도 권한 게이트로만 접근(테넌트 관리자는 자기 전시관 범위만). + +### 1A-3. 테넌트 컨텍스트 해소 (Tenant Context Resolution) + +요청마다 **어느 테넌트인가**를 판별해 컨텍스트에 주입한다(§8-2 필터 계층). + +1. **서브도메인 우선**: `kintex.wise.ai.kr` → 테넌트 #1, `coex.wise.ai.kr` → 테넌트 #2. 게이트웨이/필터가 Host 헤더에서 `tenant_code`를 해소. +2. **사용자 소속 보조**: 로그인 사용자의 테넌트 멤버십으로 판별(서브도메인과 불일치 시 **거부** — 세션 하이재킹·오접속 차단). 다중 테넌트 소속(예: 복수 전시관 운영 대행사)은 명시적 테넌트 선택 후 컨텍스트 고정. +3. **주입**: 해소된 `tenant_id`를 요청 컨텍스트(ThreadLocal/Request scope)에 주입 → 서비스·MyBatis 매퍼가 이를 강제 바인딩(§8-2). 컨텍스트 미해소 요청은 **거부(fail-closed)**. +4. **공개 사이트(M12·M17)**: 서브도메인으로 테넌트 브랜딩·콘텐츠 분기(kintex/coex 공개 홍보 사이트가 각 테넌트 콘텐츠만 노출). + +### 1A-4. 역할 계층 확장 — 플랫폼 vs 테넌트 (2계층) + +기존 6역할(§2) 위에 **관리자 역할을 2계층으로 분리**한다. + +| 계층 | 역할 | 범위 | 권한 | +|---|---|---|---| +| **플랫폼** | **플랫폼 슈퍼관리자(Platform Super Admin)** | **전 테넌트(크로스-테넌트)** | 테넌트 마스터 CRUD·온보딩, 전 테넌트 사용자/감사 통제, 전역 코드·플랫폼 설정, 전 테넌트 BI(§1A-2). GUARDiA 플랫폼 운영 주체(zio) | +| **테넌트(전시관)** | **테넌트 관리자(Venue/Tenant Admin)** | **자기 전시관(단일 테넌트) 내부만** | 자기 전시관의 마스터데이터(홀·요율·규정 룰셋·부스 표준)·사용자·RBAC·감사로그·시스템설정. 예: 킨텍스 관리자 ↔ 코엑스 관리자 상호 격리 | +| **행사(Event)** | 주최자·참가업체·업체·홀매니저(§2 기존 6역할) | 테넌트 내부의 행사·부스 | **테넌트 내부로 스코프된** 기존 행사 RBAC(변경 없음, 단 상위에 tenant 경계 추가) | + +- **재정의**: §2의 기존 "관리자(Admin)" 페르소나는 **v3.0에서 "테넌트 관리자"로 재정의**되고, 그 위에 **플랫폼 슈퍼관리자**가 신설된다. §2-1 백오피스(`admin.`)는 두 계층이 **동일 앱·차등 권한**으로 진입(플랫폼 슈퍼관리자는 테넌트 스위처 보유, 테넌트 관리자는 자기 테넌트 고정). +- **홀매니저**: 킨텍스 홀매니저는 테넌트 #1 내부 계정으로, 코엑스 홀매니저는 테넌트 #2 내부 계정으로 각각 자기 전시관 행사만 열람/승인(크로스-테넌트 불가). + +### 1A-5. 마이그레이션 영향 및 백필 방침 + +- **기존 데이터 = 테넌트 #1(KINTEX)로 백필**: v2.0까지 축적된 전 데이터(행사·홀·부스·옥션·관람객·마스터데이터 등)는 **일괄 `tenant_id = 1(KINTEX)`** 로 백필한다. 킨텍스는 기준 테넌트이므로 기존 운영에 **무중단**. +- **스키마 변경은 설계만 — 임의 DDL 금지**: `tenant_id` 컬럼 추가·FK·인덱스·NOT NULL 제약·백필 DDL은 **db-engineer/DA 후속 트랙**이 수행한다(planner는 설계·영향 범위만 확정). 적용 순서(권고): ① 테넌트 마스터 테이블 신설 + KINTEX 시드(#1) → ② 각 도메인 테이블 `tenant_id` nullable 추가 → ③ 전 행 `1`로 백필 → ④ NOT NULL + FK + `(tenant_id, …)` 복합 인덱스 → ⑤ 애플리케이션 필터(§8-2) 활성화. 멱등 DDL·`sql.init mode=always`+continue-on-error 패턴(§5B-3) 준수. +- **회귀 방지**: 백필 완료 전에는 격리 필터를 강제하지 않고(단일 테넌트 동작 유지), 컬럼·인덱스·백필 검증 후 필터를 켠다(§8-2). 신규 테넌트(COEX) 온보딩은 필터 활성화 이후. +- **미확보 데이터**: 코엑스 등 신규 전시관의 홀 실측·요율·규정은 **온보딩 시 해당 테넌트가 입력**하며, 근거 없는 추정 시드는 금지(§10 R4 정합). + +> **후속 반영 필요**: 본 절의 스키마·필터·온보딩 절차는 `docs/design.md`·`docs/architecture/data.md`·src에 **미반영 상태** — db-engineer/DA/designer 후속 반영 필요(planner는 설계만 확정, 타 문서 직접 수정 안 함). + +--- + +## 2. 사용자 정의 및 페르소나 + +| 사용자군 | 페르소나 | 핵심 과업 | 현재 고통 | 본 시스템에서 얻는 것 | +|---|---|---|---|---| +| **주최자** (Organizer) | 김주최, 전시기획사 PM 8년차. 연 3회 킨텍스 행사 운영 | D-150 홀 배정신청 → 계약 → D-30 사전협의 → D-7 신고서류 → 정산 | HWP 서식 수기 작성, 부스배치도 CAD 외주, D-7 서류 7종 마감 추적 | 자동 견적, 배치도 자동 생성, 마일스톤 자동 트래킹, 완공 예상 이미지로 참가업체 영업 | +| **참가업체** (Exhibitor) | 박참가, 중소 제조사 마케팅 담당. 전시 경험 2회 | 부스 선택(조립/독립), 유틸리티 신청(D-25), 반입/반출 | 전기 몇 kW 필요한지 모름, 위치표시도 수기 작성, 시공 결과를 개장일에 처음 봄 | 클릭 신청 + 자동 견적, **시공 전 부스 사진 확인**, 마감 리마인더 | +| **장치·시공업체** (Contractor) | 이장치, 킨텍스 등록 장치업체(739개 등록업체 중 전시디자인설치 분류) 실장 | 평면도·입면도·조감도·전기도면 kxwp 제출, D-7 리깅 구조계산서, 현장 시공 | 규정(높이 5m, 방염, 리깅 6.5~8.5m) 반려 리스크, 도면 수정 반복 | 제출 전 자동 규정 검증, 배선/분전반 설계 자동 초안, 고객 컨펌용 예상 사진 | +| **킨텍스 운영팀 (홀매니저)** | 최매니저, 행사지원팀. 홀 3개 담당 | 사전업무협의(D-30), 신고서류 검토, 현장 안전 관리(소음 70~75dB, 안전모) | 서류 육안 검수 병목, 행사별 협의 이력 분산, 위반 현장 사후 적발 | 위반 자동 플래깅 대시보드, 협의 이력 일원화, 홀 단위 유틸리티 부하 집계 | +| **관람객** (Visitor) — P1로 승격 | 정관람, 일반 관람객/바이어 | 일정 검색 → 사전등록·티켓 → 교통(GTX-A 킨텍스역 도보 3분) → 주차(iparking) → 배지·체크인 → 관람·비즈매칭 | 부스 위치 탐색 불편, 현장 등록 대기 | 사전등록·모바일 배지/QR·wayfinding·비즈매칭·인터랙티브 플로어플랜 | +| **테넌트(전시관) 관리자** (Tenant/Venue Admin) — v3.0 재정의 | 한관리, 킨텍스 전시관 운영 관리자 (코엑스는 별도 관리자) | **자기 전시관 내부** 사용자·권한(RBAC)·마스터데이터(홀·요율·규정 룰셋·부스 표준)·감사로그·시스템설정 | 데이터 산재, 권한 통제 부재 | 자기 전시관 백오피스에서 행사 통제·감사·룰셋 버전 관리(타 전시관 격리) | +| **플랫폼 슈퍼관리자** (Platform Super Admin) — v3.0 신규 | 플랫폼(zio) 운영자 | **전 테넌트** 온보딩·테넌트 마스터·전역 코드·크로스-테넌트 감사·통합 BI | (신규 — 다중 전시관 통합 통제 부재) | 테넌트 스위처로 전 전시관 통제, 새 전시관(코엑스 등) 온보딩(§1A-4·§1A-5) | +| **일반 대중** (Public) — 신규 | 불특정 다수 잠재 관람객·잠재 주최자 | 킨텍스 전시 홍보 열람, 참가 문의 | 킨텍스 공식 사이트는 정보·서식 다운로드 수준 | SEO·다국어 공개 홍보 사이트(M12), 참가업체 마이크로사이트(M17), 관람 유도 | + +**권한 모델**: **테넌트(전시관) 격리 ⊃ 행사(Event) 단위 워크스페이스 + 행사 RBAC**의 3중 구조(§1A-4). 최상위에 테넌트 경계가 있고(전시관 간 데이터 원천 차단), 그 안에서 행사 단위 RBAC가 동작한다. 주최자가 행사 owner, 참가업체는 부스 단위 멤버, 장치/공사업체는 참가업체·주최자가 초대(등록업체 DB 검증 — 미등록 업체 초대·옥션 응찰 차단), 홀매니저는 **소속 전시관 내부** 계정으로 자기 전시관 행사 전체 열람+승인. **테넌트 관리자**는 자기 전시관 백오피스에서 통제(타 전시관 격리), **플랫폼 슈퍼관리자**만 크로스-테넌트 통제(§1A-4). 관람객·일반 대중은 공개/셀프서비스 계정(행사 데이터 쓰기 권한 없음, 등록·매칭·조회만) — 접속 서브도메인으로 테넌트가 고정(§1A-3). + +### 2-1. 역할별 웹/모바일 포털 분리 (IA·채널 매트릭스) + +각 역할은 목적이 다르므로 **별도 프론트 앱(도메인/서브패스 분리)**으로 제공하되, 공유 Spring Boot 백엔드 + SSO + 역할 RBAC 위에 얹는다. 데스크톱(설계·에디터·대시보드)과 모바일(현장·조회·승인)의 용도를 명확히 나눈다. **계정 체계·모바일 앱 채널은 §2-1-1(소유자 확정 2026-07-11)** 을 따른다. + +| 역할 | 웹 포털 (데스크톱 주력) | 모바일 채널 (앱 타깃) | 가입 트랙 | 주 사용 모듈 | 인증/권한 | +|---|---|---|---|---|---| +| **주최자** | 주최자 콘솔 `organizer.` — 홀 배정·배치·행사 대시보드·옥션 발주·BI | **운영 앱(B2B)** — 조회·승인·현장 상황판 | 승인/초대 + **2FA(OTP) 필수** | M1·M2·M6·M15·M16·M12 | Event owner | +| **참가업체** | 참가업체 포털 `exhibitor.` — 부스 신청·설계·유틸리티·옥션 발주 | **운영 앱(B2B)** — 현장 체크인·**리드캡처(배지 스캔)**·승인 | 승인/초대 + **2FA(OTP) 필수** | M3·M4·M5·M10·M11·M15·M9 | Event member(부스 단위) | +| **장치/공사업체** | 업체 포털 `contractor.` — 도면 제출·**AI 설계자료 열람·옥션 응찰(견적서 제출)** | **운영 앱(B2B)** — 현장 시공·반입 통행증·안전 체크 | 승인/초대(등록업체 검증) + **2FA(OTP) 필수** | M3·M4·M15·M8·M7 | 등록업체 검증 계정 | +| **킨텍스 직원(홀매니저·운영)** | 운영 대시보드 `ops.` — 검수·규정 플래그·홀 부하·물류·현장운영 | **운영 앱(B2B)** — 현장 검수·안전·혼잡 모니터 | 내부 계정 발급 + **2FA(OTP) 필수** | M2·M6·M8·M14·M16 | 내부 계정(행사 전체 열람·승인) | +| **테넌트 관리자** | 백오피스 `admin.`(테넌트 컨텍스트 고정) — 자기 전시관 사용자·RBAC·감사로그·마스터데이터·룰셋·시스템설정 | (없음, 웹 전용) | 내부 계정 발급 + **2FA(OTP) 필수** | **M18** | 테넌트(전시관) 관리자(단일 테넌트 스코프) | +| **플랫폼 슈퍼관리자** | 백오피스 `admin.`(테넌트 스위처) — 테넌트 마스터·온보딩·전역 코드·크로스-테넌트 감사·통합 BI | (없음, 웹 전용) | 내부 계정 발급 + **2FA(OTP) 필수** | **M18 + 테넌트 관리** | 플랫폼 슈퍼관리자(크로스-테넌트, §1A-4) | +| **관람객/일반 대중** | 공개 홍보 사이트 `www/expo.` (SEO·다국어) + 관람객 사전등록·**게스트 예매(가입 없이 티켓 구매)** | **관람객 앱(B2C, 스토어 공개)** — 배지/QR·티켓 지갑·wayfinding·비즈매칭·플로어플랜 | **간편가입(이메일/소셜) + 게스트 예매 허용 · 2FA 미강제** | M12·M10·M11·M13·M17 | 공개/셀프서비스(쓰기 제한) | + +- **분리 원칙**: 6개 프론트(organizer·exhibitor·contractor·ops·admin·public+visitor)는 **역할별 번들 분리**로 최소권한·공격면 축소. 공유 디자인 시스템(design.md)·공유 컴포넌트 라이브러리·공유 API 계약을 상속한다. (UI 상세·화면 목록은 designer 후속 반영 필요.) + +#### 2-1-1. 계정 체계 및 모바일 앱 채널 전략 (소유자 확정 2026-07-11) + +> **개정 표기**: 본 소절은 v3.1에서 소유자 확정안을 신설한 것이며, 기존 §2 권한 모델·§5B-3 인증·M10을 삭제하지 않고 정밀화한다(상충 시 본 확정안 우선). 근거: `docs/analysis/ticketing-app-benchmark.md`(게스트 예매·간편가입은 티켓팅 업계 표준). + +**(A) 계정 체계 — 단일 통합 + 가입 트랙 분리.** 계정 테이블/RBAC는 **하나(단일 통합)** 로 두고, 그 위에서 **가입 트랙(등급)만 분리**한다. + +| 가입 트랙 | 대상 | 가입 방식 | 2FA(OTP) | 예매/조회 | +|---|---|---|---|---| +| **업무 트랙(B2B)** | 주최자·참가업체·공사업체·킨텍스 직원·관리자 | **승인/초대 기반 가입(SCR-49)** | **필수** | 역할 RBAC에 따름 | +| **관람객 트랙(B2C)** | 일반 관람객·바이어 | **간편가입(이메일 또는 소셜 로그인)** | 미강제(선택) | **게스트 예매 허용**(가입 없이 티켓 구매, SCR-P7 기반영) | + +- **계정 승격 연속성**: 관람객 → 바이어/참가업체 담당자로 승격 시 **단일 계정 위 등급 상향**으로 처리하여 **데이터 연속성(리드·비즈매칭·재방문 이력)** 을 유지한다(계정 재생성 없음). 승격 시 업무 트랙 요건(승인·2FA)이 추가 적용된다. +- 게스트 예매자는 사후 간편가입 시 예매 이력을 계정에 병합(티켓 지갑 연속). + +**(B) 모바일 앱 — 코드베이스 1개(Expo `mobile/`), 배포 타깃 2개.** + +| 앱 타깃 | 대상 | 배포 채널 | 핵심 화면 | +|---|---|---|---| +| **① 운영 앱(B2B)** | 업무 사용자 전용 | **스토어 미공개** — 사내 QR/APK 배포 | 현장 체크리스트·검수·승인 | +| **② 관람객 앱(B2C)** | 일반 관람객·바이어 | **스토어 공개 배포** | 간편가입·티켓 지갑·배지/QR·wayfinding·비즈매칭 (SCR-M5~M9·M14/M15 계열) | + +- 두 타깃은 **단일 Expo 코드베이스(`mobile/`)** 에서 빌드 프로파일/엔트리로 분기한다(중복 구현 회피). 배포 채널·스토어 정책만 다르다. +- **관람객 1차 접점은 공개 웹(SCR-P7/P8)** 이며, 관람객 앱은 **리텐션 채널**(재방문·티켓 지갑·현장 wayfinding)로 위치한다. 앱 미설치 관람객도 웹 게스트 예매로 전 여정 완결 가능. +- 백오피스(관리자)는 모바일 미제공(웹 전용). 업무 사용자 모바일은 운영 앱으로만 제공. + +--- + +## 2-2. 대외 접점 3-트랙 재구성 (visitor / business / agency) — v3.2 + +> **소유자 확정(2026-07-12)**: 대외 접점을 **visitor(관람객) / business(비즈니스=주최자·참가업체) / agency(에이전시=공사·장치·협력사)** 3개 트랙으로 나눠 분리한다. 근거 = `docs/analysis/coex-website.md` — 코엑스가 방문자 유형별로 **사이트(도메인) 자체를 3개(VISITOR `coex.co.kr` / BUSINESS `business.coex.co.kr` / CYBER 참가신청 `cybercoex.co.kr`)로 분리**한 IA를 킨텍스 도메인에 이식한다. +> +> **보존 원칙**: 본 절은 §2 페르소나·§2-1 역할별 포털 매트릭스·§2-1-1 계정 체계·M1~M18·§8 아키텍처를 **삭제·재작성하지 않는다.** 6역할/7페르소나 구조는 유지되고, 그 위에 "대외 접점을 3개 트랙으로 묶어 진입점·서브홈·네비게이션 IA를 재편하는" **트랙 셸 레이어**만 순증한다. 내부 전용 역할(킨텍스 직원 ops·테넌트/플랫폼 관리자 admin)은 대외 트랙이 아니므로 3-트랙 밖에 그대로 둔다. + +### 2-2-1. 3-트랙 정의 — 대상·핵심 여정·진입 화면·제공 기능 + +| 트랙 | 대상(§2 역할 매핑) | 코엑스 대응 | 핵심 여정 | 진입 화면 | 제공 기능(모듈·SCR) | +|---|---|---|---|---|---| +| **visitor** (관람객) | 관람객 + 일반 대중(Public) | VISITOR `coex.co.kr` + 가이드 | 행사 탐색 → 사전등록/티켓 → 방문(교통·주차·길찾기) → 배지·체크인 → 관람·매칭 → 재방문 | visitor 서브홈(공개 랜딩) → SCR-P1 | 공개 홍보 사이트 M12(SCR-P1·P2·P3·P5), 사전등록·티켓 M10(SCR-P4·P6·P7·P8), wayfinding M13, 비즈매칭 M11, 관람객 앱(SCR-M5~M9·M14·M15) | +| **business** (비즈니스) | 주최자(Organizer) + 참가업체(Exhibitor) | BUSINESS `business.coex.co.kr` + CYBER `cybercoex.co.kr` | (주최자) 홀배정·견적 → 배치·서류 → 옥션 발주 → 정산·BI / (참가업체) 부스 신청 → 설계·유틸리티 → 시각화 → 리드 | business 서브홈 → 로그인 → 역할별 홈(주최자 SCR-02 / 참가 SCR-05) | 홀배정·견적 M1, 배치 M2, 부스설계 M3, 유틸리티 M4, 시각화 M5, 서류·마일스톤 M6, 옥션 발주 M15, 정산 M9, 관람·리드 M10, BI M16 | +| **agency** (에이전시) | 장치·공사업체(Contractor) + 등록·협력업체 | BUSINESS 하위 **서비스협력업체** + 안전경영 **온라인작업신고** (킨텍스는 독립 트랙으로 승격) | 등록업체 검증 → AI 설계자료 열람 → **옥션 응찰(견적서 제출)** → 수주 → 도면 제출·규정검증 → 현장 시공·작업신고 | agency 서브홈 → 로그인 → 수주/응찰 대시보드(SCR-27/28) | 부스설계(공유) M3, 규정검증 M3(SCR-09), 옥션 응찰 M15(SCR-27·28), 등록업체 매칭 M7(SCR-38), 반입/작업신고 M8, 현장 앱(SCR-M1·M10) | + +- **트랙 ↔ 역할 관계**: 트랙은 역할의 **상위 묶음(진입점 그룹)** 이지 역할의 대체가 아니다. business 트랙 안에 organizer·exhibitor 2역할이 공존하고, agency 트랙 안에 contractor + 등록업체 계정이 공존한다. 로그인 후 실제 권한·화면은 기존 §2 역할 RBAC 그대로. +- **코엑스와의 차이(정당화)**: 코엑스는 agency(협력사)를 BUSINESS 하위로 흡수했으나, 킨텍스는 **독립부스 등록 장치업체 필수·미등록 시공 엄금·리깅 구조계산서·739개 등록업체 DB·M15 역경매 옥션**이라는 강한 도메인이 있어 agency를 **독립 트랙**으로 세운다(§4 대비표 근거). + +### 2-2-2. 코엑스에서 차용할 요소 (트랙별) + +| 트랙 | 코엑스 차용 요소 | 킨텍스 반영 | +|---|---|---| +| visitor | "가이드" 단일 허브(오시는 길·주차·실내 길찾기·VR·편의시설·알림마당·문의) + 관심분야 맞춤 알림 + 수어/접근성 전면 노출 | visitor 서브홈에 방문 가이드 허브 구성(교통 GTX-A·주차 iparking·wayfinding M13·편의시설), 맞춤 알림·접근성 고지(M12·M10) | +| business | 임대절차→시설규격→요금→서류/도면 **단계별 실무 흐름** + 참가업체 신청 **공통 플랫폼(cybercoex)** 일원화 | business 서브홈에 주최자(대관·M1)·참가업체(신청·M3/M4) 단계 안내 + 킨텍스 최대 공백인 **참가업체 공통 e-서비스**를 business 트랙으로 통합 | +| agency | 서비스협력업체 리스트 + 안전경영 온라인작업신고 통합 | agency 서브홈에 등록업체 검증·수주·옥션·도면제출·작업신고(kxwp 릴레이)를 하나로(코엑스보다 강한 독립 트랙) | + +### 2-2-3. 공개 사이트 구조 — 랜딩 3-분기 + 트랙별 서브홈 + 로그인 후 홈 + +**(A) 랜딩(루트) = 3-트랙 분기 관문.** 최상위 진입점(예: `www.` 또는 테넌트 루트)은 코엑스 스타일로 **visitor / business / agency 3개 카드로 명확히 분기**하는 관문 랜딩을 제공한다. 관람객이 절대다수이므로 visitor를 시각적 1순위(히어로·행사 카드)로 두고, business·agency는 상단 유틸리티/카드로 노출(코엑스가 VISITOR를 메인에 두고 BUSINESS를 링크로 분리한 패턴 차용). + +**(B) 트랙별 서브홈(전용 공개 홈 3개).** +- **visitor 서브홈** — 공개·비로그인. 행사 일정·히어로·사전등록/티켓 CTA·방문 가이드 허브(SCR-P1 확장). SEO·다국어·MDI 비적용(§8-1). +- **business 서브홈** — 공개(안내) + 로그인 유도. 주최자 대관 안내·참가업체 참가 안내·요금·서류 안내(SCR-P6 확장) → "로그인/신청" CTA. +- **agency 서브홈** — 공개(안내) + 등록업체 로그인. 등록업체 안내·진행 중 옥션 공고·작업신고 안내 → 등록업체 로그인 CTA. + +**(C) 로그인 후 랜딩 — 권고: "트랙-스코프 홈(Track-scoped Home)".** +로그인 후 홈은 **단일 범용 홈(역할별 변형)** vs **트랙별 별도 홈** 두 안 중, **트랙별 별도 홈(단, 트랙 내부는 역할 변형)** 을 권고한다. + +| 안 | 내용 | 장점 | 단점 | 판정 | +|---|---|---|---|---| +| 단일 범용 홈(역할별 위젯 변형) | 로그인 후 하나의 홈, 역할에 따라 위젯만 다름 | 구현 단순, 계정 승격 연속성(§2-1-1) 매끄러움 | 트랙 정체성 약함, business·agency·visitor 혼재로 IA 혼란 | 부분 채택(트랙 내부) | +| **트랙별 별도 홈(트랙 내 역할 변형)** | 트랙 셸마다 홈, 홈 안에서 역할(주최자/참가 · 시공/등록)로 위젯 변형 | 코엑스식 트랙 정체성·최소권한·공격면 축소(§2-1), 기존 SCR-02/05/27 재사용 | 홈 3벌 유지 | **권고** | + +- **권고 근거**: business 트랙은 organizer(SCR-02)·exhibitor(SCR-05) **기존 홈을 그대로** 트랙 내 역할 변형으로 재사용하고, agency는 수주/응찰 대시보드(SCR-27/28)를 홈으로 삼는다 → **신규 홈 화면 최소**(트랙 관문 랜딩 + 서브홈 3개만 신규, 나머지는 재배치). 계정 승격 연속성(§2-1-1)은 **단일 통합 계정** 위에서 유지되므로 트랙별 홈이어도 데이터 연속성은 훼손되지 않는다(관람객→바이어/참가 승격 시 business 트랙 접근 권한만 추가). + +### 2-2-4. 라우트 체계 — 마이그레이션 비용 비교 후 권고 + +| 안 | 라우트 | 마이그레이션 비용 | SEO/딥링크 | 판정 | +|---|---|---|---|---| +| A. 전면 트랙 프리픽스 | 기존 `/o/`·`/e/`·`/c/`·`/tickets/`를 `/business/o/`·`/business/e/`·`/agency/c/`·`/visitor/tickets/`로 재작성 | **높음** — 전 딥링크·MDI 세션키(§design 2.7 `kintex.mdi.{role}.{eventId}`)·티켓 공개 라우트(`/tickets/:orderNo`) SEO 인덱스 전면 변경, 리다이렉트 맵 필요 | 기존 인덱스 무효화 위험 | 미채택 | +| **B. 트랙 셸 레이어 + 기존 딥 라우트 유지(하이브리드)** | **신규 얕은 트랙 진입 라우트만 추가** — `/`(관문 랜딩), `/visitor`(서브홈), `/business`(서브홈), `/agency`(서브홈). 로그인 후 **기존 역할 딥 라우트(`/o/{eventId}/...`·`/e/{eventId}/...`·`/m/...`·`/gallery/...`·`/tickets/...`)는 그대로 유지** | **낮음** — 기존 화면·MDI·티켓 SEO·세션키 불변, 트랙은 상위 셸/네비로만 그룹핑 | 기존 인덱스 보존, 신규 트랙 랜딩만 인덱싱 | **권고** | +| C. 서브도메인 분리 | `visit.` / `business.` / `agency.` 서브도메인(코엑스식) | 중간 — 배포·인증서·SSO 쿠키 도메인 조정, 단 §2-1·§8-1이 이미 역할 서브도메인(organizer.·exhibitor.·contractor.) 전제 | 트랙별 브랜딩·격리 명확 | **선택적 상위 옵션**(운영 단계) | + +- **권고 = 안 B(하이브리드) + 안 C 선택 결합**: 1차는 **경로 기반 트랙 셸(안 B)** 로 마이그레이션 비용 없이 트랙 IA를 얹고, 기존 딥 라우트(`/o/`·`/e/`·`/m/`·`/tickets/`)와 MDI 셸(design §2.7)·티켓 공개 라우트(SCR-P7/P8)를 **불변**으로 둔다. 운영 확장 시 §2-1의 역할 서브도메인 전략과 정합하여 트랙 서브도메인(안 C)을 상위에 얹을 수 있다(예: `business.` → business 서브홈 → 내부적으로 organizer/exhibitor 앱). +- **트랙 ↔ 기존 서브도메인 매핑**(§2-1 보존): visitor 트랙 ⊇ {`www/expo.` 공개 + 관람객 앱}, business 트랙 ⊇ {`organizer.`·`exhibitor.`}, agency 트랙 ⊇ {`contractor.`}. ops·admin 서브도메인은 트랙 외부(내부 전용). + +### 2-2-5. 기존 화면 재배치 매핑표 (현행 SCR/라우트 → 트랙) + +> 원칙: **화면·라우트는 이동·재작성하지 않는다**(안 B). 아래는 각 화면이 **어느 트랙 셸의 네비게이션·진입 그룹에 속하는가**의 논리적 귀속 표이며, designer/frontend는 이를 트랙 서브홈·네비 구성에만 사용한다. + +| 트랙 | 귀속 화면(design.md SCR) | 현행 라우트(유지) | 신규(트랙 셸) | +|---|---|---|---| +| **관문 랜딩** | (신규) 3-트랙 분기 관문 | `/` | ★신규 SCR 필요(designer) | +| **visitor** | SCR-P1·P2·P3·P5(공개사이트), SCR-P4·P6(등록·문의), SCR-P7·P8(티켓), SCR-M5~M9·M14·M15(관람객 앱) | `www/expo.` 공개, `/tickets/*`, 관람객 앱 | ★visitor 서브홈(SCR-P1 확장) | +| **business** | SCR-01(로그인), SCR-02·03·04·19(주최자), SCR-05·06·07·08·12(참가), SCR-15·18·20·21·22·23·24·25·26·29(M1/M6/M8/M9/M15 발주), SCR-13(BI), SCR-30·31·32(관람·리드), SCR-39~48(공통업무) | `/o/{eventId}/*`, `/e/{eventId}/*`, `/gallery/*` | ★business 서브홈(SCR-P6 확장) | +| **agency** | SCR-06·09(설계·규정, 공유), SCR-27·28(옥션 응찰), SCR-38(등록업체), SCR-M1·M10(현장·통행증) | `/c/{eventId}/*`(contractor, 기존 exhibitor 포털 공유 라우트), 옥션 응찰 라우트 | ★agency 서브홈(등록업체·옥션 공고) | +| **트랙 외부(내부)** | SCR-10·11(홀매니저), SCR-14(현장운영), SCR-16·A1~A10(관리자·시스템관리) | `/m/{eventId}/*`, `admin.` | (트랙 재편 대상 아님, 보존) | + +- **신규 화면 = 4종만**(관문 랜딩 1 + 서브홈 3). 나머지는 전량 기존 SCR 재사용 → designer/frontend 작업량 최소(§구현 지시서 `_workspace/plan_3track.md`). + +--- + +## 2-3. 사용자 구분 → 랜딩(메인페이지)·메뉴/탭 그룹 결정 규칙 — 웹+모바일 공통 (v3.3, 소유자 확정 2026-07-12) + +> **소유자 확정 규칙**: **"로그인한 사용자의 사용자 구분(역할)으로 메인페이지가 결정되고, 좌측 메뉴 그룹(모바일은 하단 탭바)도 결정된다."** 두 가지 축을 확정한다 — ① **미인증(비로그인) 기본 진입 = visitor 트랙**(공개 관람 랜딩), ② **인증 후에는 역할이 매핑되는 트랙의 전용 메인**으로 랜딩하고 메뉴/탭 그룹을 트랙-스코프로 노출한다. **웹과 모바일 앱은 동일 로직**을 따른다(모바일은 셸 대신 하단 탭바 구성이 역할별로 결정). +> **보존·경계**: §2 6역할/7페르소나·§2-2 3-트랙·§2-1 포털 매트릭스·기존 화면(SCR-*)·기존 딥 라우트(안 B, §2-2-4)를 **삭제·재작성하지 않는다.** 본 절은 그 위에 **랜딩 결정 로직 + 트랙별 메뉴/탭 가시성 + 신규 트랙 메인 화면 목록**만 순증한다. 본 절은 §2-2-3(C)의 "트랙-스코프 홈" 권고를 소유자 확정으로 **정밀화**한다 — 기존 홈(SCR-02/05/27)을 그대로 재사용하는 대신, **각 트랙 전용 "메인" 신규 화면(designer Stitch 의뢰)이 기존 역할 위젯을 조합**하는 형태로 확정. +> **현행 기준(실측)**: 현재 로그인 후 전원 `/home`(SCR-HOME) 고정(`LoginPage.completeLogin → navigate('/home')`), AppShell `GROUPS`(ops·design·visitor·finance·work·system) 전원 동일 노출(system 그룹만 `isAdmin` 게이트). 역할 신호: `EventRole = ORGANIZER|EXHIBITOR|CONTRACTOR|HALL_MANAGER`(워크스페이스 `myRole`) + `globalRole`(`app_user.role_code` = ADMIN|MANAGER|VISITOR…). authStore: `globalRole()`·`roleForCurrent()`·`workspaces`. **src·design.md 미수정(frontend·kintex-mobile·designer 후속).** + +### 2-3-1. 역할 → 트랙 매핑 확정표 (웹·모바일 공통) + +| 트랙 | 구성 역할(§2) | 판정 신호 | 웹 셸 | 모바일 앱 타깃(§2-1-1) | +|---|---|---|---|---| +| **visitor**(관람) | 관람객·일반대중·게스트 | **미인증** OR `globalRole=VISITOR` OR 업무 워크스페이스 0개 | 공개/관람객 셸(MDI 비적용, §2.7-6) | **관람객 앱(B2C)** | +| **business**(비즈니스) | ORGANIZER·EXHIBITOR | `myRole ∈ {ORGANIZER, EXHIBITOR}` 워크스페이스 보유 | AppShell(MDI) | **운영 앱(B2B)** | +| **agency**(에이전시) | CONTRACTOR·등록/협력업체 | `myRole=CONTRACTOR` 워크스페이스 보유(상위 트랙 없음) | AppShell(MDI) | **운영 앱(B2B)** | +| **내부-ops** | HALL_MANAGER·킨텍스 운영 | `globalRole=MANAGER` OR `myRole=HALL_MANAGER` 워크스페이스 | AppShell(MDI) | **운영 앱(B2B)** | +| **내부-admin** | 테넌트/플랫폼 관리자 | `globalRole=ADMIN`(=현행 `isAdmin`) | AppShell(MDI) + 시스템관리 그룹 | 웹 전용(모바일 백오피스 미제공, §2-1-1) | + +- **트랙 판정 헬퍼**: `trackOf(EventRole)` → ORGANIZER/EXHIBITOR = business, CONTRACTOR = agency, HALL_MANAGER = 내부-ops. `globalRole` 오버레이 → ADMIN = 내부-admin(system 그룹 부여), MANAGER = 내부-ops, VISITOR/null = visitor(업무 워크스페이스 없을 때). + +### 2-3-2. 판정 우선순위 · 멀티역할 · 트랙 스위칭 + +- **primaryTrack 우선순위(높음→낮음)**: **내부-admin > 내부-ops > business > agency > visitor.** 복수 역할 사용자(계정 통합, §2-1-1)의 **로그인 랜딩**은 이 우선순위로 결정한다. 예: `admin+organizer` → 내부-admin 랜딩(관리 메인, 단 비즈니스 메뉴도 접근), `contractor+exhibitor` → business 랜딩(둘 다 업무 트랙, business 우위). +- **activeTrack(반응형)**: 좌측 상단 **행사 전환 드롭다운(기존)** 으로 워크스페이스를 바꾸면 `activeTrack = trackOf(roleForCurrent())` 로 따라 바뀌어 메뉴/탭이 재스코프된다 → **별도 트랙 스위처 UI 신설 최소화**(기존 워크스페이스 선택 재사용). `globalRole=ADMIN` 의 시스템관리 오버레이는 activeTrack과 무관하게 항상 유지(현행 `isAdmin` 게이트 보존). +- **연속성**: 트랙별 메인/메뉴가 달라도 계정은 단일 통합(§2-1-1)이므로 리드·비즈매칭·재방문 이력은 훼손되지 않는다(관람객→바이어/참가 승격 시 business 트랙 접근 권한만 추가). + +### 2-3-3. 랜딩(메인페이지) 결정표 + +**(A) 웹** — `completeLogin` 분기 + 미인증 루트 가드. + +| 순서 | 상태·조건(신호) | 트랙 | 메인페이지 | 라우트(권고·안 B) | 화면 | +|---|---|---|---|---|---| +| 0 | **미인증(토큰 없음)** | visitor | 공개 관람 랜딩 | `/` (현행 `/login` 리다이렉트 → visitor 랜딩으로) | **SCR-T0(신규)** | +| 1 | `globalRole=ADMIN` | 내부-admin | 관리 메인(**또는** 비즈니스 메인+시스템관리) | `/admin`(또는 `/home`) | SCR-16(+SCR-T2) | +| 2 | `globalRole=MANAGER` OR HALL_MANAGER ws | 내부-ops | 운영 메인(비즈니스 메인 운영 변형) | `/home` | SCR-T2(운영 변형) | +| 3 | ORGANIZER/EXHIBITOR ws | business | 비즈니스 메인 | `/home` | **SCR-T2(신규)** | +| 4 | CONTRACTOR ws(1~3 없음) | agency | 에이전시 메인(수주·옥션) | `/contractor/dashboard`(또는 `/agency`) | **SCR-T3(신규)** | +| 5 | `globalRole=VISITOR` OR 업무 ws 0 | visitor | 관람객 메인 | `/visitor` | **SCR-T1(신규)** | +| — | 판정 불가(폴백) | — | 안전 폴백 | `/home` | SCR-HOME(현행) | + +**(B) 모바일 앱** — 동일 로직(진입 시 미인증=관람객, 로그인 후 역할별 홈 탭 네비게이터 스위칭). + +| 순서 | 상태·조건 | 트랙/역할 | 모바일 진입(랜딩) | 화면 | +|---|---|---|---|---| +| 0 | **미인증(토큰 없음)** | visitor(게스트) | **관람객 진입** — 행사탐색·사전등록·티켓·게스트 예매 | 모바일 관람객 홈(신규) | +| 1 | ADMIN | (모바일 백오피스 없음) | 보유 업무역할 메인, 없으면 관람 최소 뷰 | — | +| 2 | MANAGER/HALL_MANAGER | 내부-ops | 운영 홈(승인·현장 상황판) | SCR-M2 계열 + 운영 홈(신규) | +| 3 | ORGANIZER/EXHIBITOR | business | 업무 홈(주최=대시보드 / 참가=내 부스) | 모바일 비즈니스 홈(신규) | +| 4 | CONTRACTOR | agency | 수주/옥션 홈 + 현장 | SCR-M1 계열 + 모바일 에이전시 홈(신규) | +| 5 | VISITOR/게스트 | visitor | 관람객 홈(티켓·배지·wayfinding·매칭) | SCR-M5~M9·M14·M15 계열 | + +### 2-3-4. 좌측 메뉴 그룹 매트릭스 (웹 AppShell `GROUPS`) + +노출 규칙: `●` 전체 노출 · `◐` 부분(항목 필터) · `✕` 숨김. 현행 `visibleGroups = GROUPS.filter(!g.admin || isAdmin)` 를 **트랙 필터 추가**로 확장. + +| `GROUPS.id` (그룹명) | 내부-admin | 내부-ops | business(주최) | business(참가) | agency | visitor | +|---|---|---|---|---|---|---| +| `ops` 전시 운영 | ● | ● | ● | ◐(대시보드·참가업체 조회) | ✕ | ✕ | +| `design` 설계·시공 | ● | ●(검수·홀 부하) | ● | ●(부스설계·유틸·시각화) | ●(수주부스·공사옥션·규정·반입) | ✕ | +| `visitor` 관람객·마케팅 | ● | ● | ● | ◐(리드) | ✕ | ✕(셸 미노출) | +| `finance` 정산·분석 | ● | ● | ● | ◐(내 정산) | ✕ | ✕ | +| `work` 업무 공통 | ● | ● | ● | ● | ● | ✕ | +| `system` 시스템관리 | ● | ✕ | ✕ | ✕ | ✕ | ✕ | + +- **visitor 트랙**은 업무 AppShell(GROUPS) 미노출 — §2-2-3(B)의 공개/관람객 셸(내 티켓·내 행사·방문가이드·알림 최소 메뉴)을 사용한다. +- **agency `design` 그룹 부분(◐→항목)**: 노출 = `수주 부스`(`/contractor/dashboard`)·`공사 옥션`(`/auctions`)·`서류·마일스톤`(도면제출)·`반입·반출`. 숨김 = 주최자 전용 `플로어플랜 스튜디오` 편집. +- **내부-ops(홀매니저)**: `design`은 검수·홀 부하 관점(플로어플랜 RO), `system` 제외(테넌트 관리자 아님). + +### 2-3-5. 하단 탭바 매트릭스 (모바일, 역할별 결정) + +design.md §2-2 모바일 하단 탭 4개(홈/내 부스·승인/알림/더보기)를 **역할별 구성으로 확정**(탭 4~5개). + +| 트랙/역할 | 탭1 (홈) | 탭2 | 탭3 | 탭4 | 탭5 | +|---|---|---|---|---|---| +| visitor(미인증·관람객) | 행사탐색 | 티켓·배지 | 길찾기(wayfinding) | 알림 | 더보기(게스트→가입) | +| business 주최자 | 대시보드 | 참가·승인 | 현장 상황판 | 알림 | 더보기 | +| business 참가업체 | 내 부스 | 체크인·리드스캔 | 시각화 | 알림 | 더보기 | +| agency 공사·협력 | 수주·옥션 | 현장 체크리스트 | 통행증 | 알림 | 더보기 | +| 내부-ops 홀매니저 | 홈 | 승인·검수 | 현장(안전·혼잡) | 알림 | 더보기 | +| 내부-admin | (모바일 백오피스 미제공 — 웹 전용) | | | | | + +### 2-3-6. 신규 트랙 메인 화면 목록·스펙 (designer Stitch 의뢰 대상) + +> planner는 **화면 목록·용도·핵심 섹션·재사용 위젯**까지 확정한다. **SCR 번호 확정·Stitch 영어 프롬프트 작성·생성·이식은 designer 소관**(MEMORY: 전 화면 Stitch 경유). 아래 가칭 SCR-T0~T3(웹)·모바일 3종은 designer가 design.md에서 정식 번호·프롬프트로 확정한다. + +| # | 화면(가칭) | 채널 | 트랙 | 핵심 섹션/위젯 | 셸 | 조합할 기존 위젯 | +|---|---|---|---|---|---|---| +| 1 | **SCR-T0 공개 관람 랜딩(루트)** | 웹 | visitor(미인증) | 히어로·행사 카드·사전등록/티켓 CTA·**business/agency 로그인 진입**·방문가이드 허브 | 공개 셸 | §2-2-3(B) visitor 서브홈, SCR-P1 | +| 2 | **SCR-T1 관람객 메인** | 웹 | visitor(인증) | 내 티켓·모바일 배지·행사탐색·wayfinding·비즈매칭 | 관람객 셸 | SCR-P4·P7·P8 | +| 3 | **SCR-T2 비즈니스 메인** | 웹 | business/내부-ops | KPI·D-데이 할일·내 행사 — **역할 변형**(주최=마일스톤·홀 SCR-02 / 참가=내 부스·마감 SCR-05) | AppShell | SCR-02·05·HOME | +| 4 | **SCR-T3 에이전시 메인** | 웹 | agency | 수주 목록·진행 중 옥션·응찰 현황·규정검증 요약·작업신고 | AppShell | SCR-27·28·09·38 | +| 5 | **모바일 관람객 홈** | 모바일 | visitor | 행사탐색·티켓·배지·wayfinding | 관람객 앱 | SCR-M5~M9 | +| 6 | **모바일 비즈니스 홈** | 모바일 | business | 대시보드/내 부스·승인·리드(역할 변형) | 운영 앱 | (신규) | +| 7 | **모바일 에이전시 홈** | 모바일 | agency | 수주·옥션·현장 | 운영 앱 | SCR-M1 | + +- **관리 메인**(내부-admin)은 **기존 SCR-16 관리 대시보드 재사용**(신규 아님) — 비즈니스 메인(SCR-T2)+시스템관리 그룹 조합 대안 병기. +- **신규 Stitch 화면 = 웹 4(SCR-T0~T3) + 모바일 3 = 7종.** 나머지 세부 업무 화면은 전량 기존 SCR 재사용(안 B). + +### 2-3-7. 구현 권고 및 담당 (지시서 포인터) + +- **웹 (frontend 담당)**: ① `LoginPage.completeLogin` 을 `resolveLandingTrack(user, workspaces)` → `landingPath(track)` 분기로 교체(현행 `/home` 고정 폐기, business/내부는 `/home` 유지 = 회귀 0, agency=`/contractor/dashboard`·visitor=`/visitor` 신설 분기). ② 미인증 루트 `/` = SCR-T0(현행 `/login` 강제 리다이렉트 완화). ③ `AppShell.visibleGroups` 에 **트랙 필터** 추가(`GROUPS`/item에 선택적 `tracks?` 허용목록 필드, `activeTrack` 파생). ④ authStore에 `activeTrack()` 셀렉터 신설. **라우트·화면 재작성 없음(안 B).** +- **모바일 (kintex-mobile 담당)**: ① 앱 진입 미인증 = 관람객 탭 네비게이터. ② 로그인 후 `resolveLandingTrack` 동일 규칙으로 역할별 탭 네비게이터 스위칭(§2-3-5). ③ 탭 구성은 트랙-스코프. WISE 모바일 레퍼런스 컨벤션 준수. +- **지시서**: `_workspace/plan_role_routing.md`(웹+모바일 섹션·담당·웨이브 명시). **design.md/designer 후속**: 신규 트랙 메인 7종 Stitch 의뢰 + §2.7-6 역할별 적용·§2-1 사이트맵·§4 모바일 탭 매트릭스에 본 규칙 반영. + +--- + +## 3. 현행(As-Is) 프로세스 분석 + +### 3-1. 주최자 타임라인과 병목 + +분석 문서 기준 실제 프로세스: + +| 시점 | 현행 프로세스 | 매체 | Pain Point | +|---|---|---|---| +| D-150 ~ D-14 (인기 행사 1~2년 전) | 전시홀 배정신청서 제출 → 배정협의 → 견적 | **HWP 양식**, 방문/이메일 (온라인 제출 안내는 있으나 실체는 서식 다운로드) | 가용성 실시간 조회 불가, 견적 대기 | +| 계약 | 계약금 20% → 중도금 30%+20% → 잔금 30% + 관리비 예치금(임대료의 15~20%) | 공문+계약서 | 납부 일정 수동 관리 | +| D-30 | 홀매니저 배정 후 사전업무협의(장치·홍보·로비·보안) 완료 기한 | 대면/유선 | 협의 이력 비정형, 담당자 의존 | +| D-25 내외 | 참가업체 유틸리티 신청 마감(전기 등) | **전시회별 주최자 사무국 시스템** (킨텍스 공통 플랫폼 부재) | 행사마다 신청 채널 상이, 누락 빈발 | +| D-7 | 신고서류 일괄 제출: 행사운영계획서, 부스배치도, 재해대처계획서, 방화관리 책임서약서, 주차관리 신청서, 보안요원 배치계획, 위험물 반입신고서 + 리깅 구조계산서 | kxwp.kintex.com 업로드 | 서류 7종+ 마감 집중, 육안 검수 병목 | +| 행사 후 | 폐기물 처리비·전기사용료 등 관리비 정산 | 세금계산서 | 예치금 대비 실사용 정산 불투명 | + +### 3-2. 참가업체·장치업체 병목 + +- **독립부스는 킨텍스 등록 장치업체 시공 필수**(미등록 엄금, 자체시공 원칙 불가) — 그러나 등록업체 DB(14개 분류 × 739개)는 단순 리스트+엑셀 다운로드로, 매칭·견적 비교 기능 없음. +- 장치 도면(평면·입면·조감·전기)을 kxwp에 제출 → 사람이 검토. 규정은 수치로 명확(높이 5m 이하, 리깅 6.5~8.5m + 구조계산서 D-7, 복층 1/2 이내, 전 자재 방염, 홀별 바닥하중 2~5t/㎡)하나 검증은 수작업. +- 유틸리티는 **바닥 트렌치** 공급(전기·급배수·압축공기·전화·인터넷, 홀1·7은 가스 포함)인데, 참가업체가 **시공 위치표시도를 수기로 그려 온라인 등록**해야 하며 인터넷은 현장 추가신청 불가 — 마감(약 D-25) 놓치면 구제 수단 없음. +- 요금은 정형화되어 있으나 견적 자동화 없음: 전기 220V 단상 1kW 55,000원, 분전반 50A 추가 100,000원, 압축공기(내경 8mm) 150,000원/구, 급배수(급수15mm/배수25mm) 150,000원/구, 인터넷 유선 150,000원/회선(KT 경유 회선당 80,000원 안내 병존). +- 반입/반출: 화물차 순번제·통행증, 중량물(5t 이상) 우선 반입, 지게차 지정업체 사전신청(유료) — 슬롯 예약 시스템 없이 현장 대기열 운영. + +### 3-3. 구조적 공백 (분석 문서 §5 종합) + +1. **참가업체 공통 포털 부재** — 유틸리티 신청이 행사별로 파편화. 가장 큰 공백. +2. 배치도·도면·위치표시도 등 **공간 데이터가 전부 이미지/수기**로 오가며 구조화되지 않음 → 자동 검증·시각화·정산의 원천 데이터가 없음. +3. D-150/D-30/D-25/D-7 마일스톤이 시스템화되어 있지 않음. +4. 시공 결과를 사전에 볼 수단이 없음 — 조감도는 장치업체 외주 산출물이며 배선·조명 반영 안 됨. + +--- + +## 4. 시스템 구성 (모듈 맵) + +```mermaid +graph TB + subgraph 포털["역할별 포털 (§2-1)"] + ORG[주최자 콘솔] + EXH[참가업체 포털] + CON[업체 포털] + MGR[운영 대시보드] + ADM[관리자 백오피스] + PUB[공개사이트/관람객앱] + end + + subgraph 코어["설계·시각화 코어 (P0·불변)"] + M2[M2 플로어플랜 스튜디오
3안 생성·선택/병합·규정검증] + M3[M3 부스 설계 스튜디오
3안 생성·선택/병합] + M4[M4 유틸리티 설계
전기·조명/네트워크·급배수] + M5[M5 나노바나나
시공 후 예상 사진] + end + + subgraph 판매운영["판매·발주·정산"] + M1[M1 홀 배정·자동 견적] + M6[M6 서류·마일스톤] + M7[M7 등록업체 매칭] + M15[M15 공사/장치 옥션
역경매·견적서 응찰] + M8[M8 반입/반출 물류] + M9[M9 정산·결제] + end + + subgraph 관람참가["관람·참가·마케팅"] + M10[M10 관람객 등록·배지
체크인·리드캡처] + M11[M11 비즈니스 매칭] + M12[M12 마케팅·EDM
공개 홍보 사이트] + M13[M13 wayfinding
실내 내비] + M14[M14 현장운영
혼잡·안전·주차·에너지] + end + + subgraph 경영["경영·콘텐츠·관리"] + M16[M16 경영분석 BI
매출·가동률·P&L·수요예측] + M17[M17 CMS
콘텐츠·마이크로사이트·다국어] + M18[M18 관리자 시스템
RBAC·감사·마스터데이터] + end + + subgraph 외부["외부·기존 시스템"] + KXWP[kxwp/kxfp 작업신고] + CCPY[등록업체 DB 739개] + EVT[행사일정 시스템] + PG[PG 결제] + GEM[Gemini 나노바나나] + SGN[사이니지/wayfinding HW] + end + + ORG --> M1 --> M2 + ORG --> M6 + ORG --> M16 + EXH --> M3 --> M4 + CON --> M3 + CON --> M15 + MGR --> M2 + MGR --> M14 + ADM --> M18 + PUB --> M12 + PUB --> M10 + + M2 --> M3 --> M4 + M2 & M3 & M4 --> M5 + M4 --> M9 + M1 --> M9 + M3 --> M7 + M2 & M3 & M4 & M5 --> M15 + M15 --> M9 + EXH --> M8 + M10 --> M11 + M10 --> M14 + M2 --> M13 + M9 --> M16 + M10 --> M16 + M12 --> M17 + M18 -.룰셋·마스터.-> M1 + M18 -.RBAC.-> 포털 + + M5 --> GEM + M6 -.릴레이.-> KXWP + M7 --- CCPY + M15 --- CCPY + M1 --- EVT + M9 --- PG + M13 --- SGN + M17 --- SGN +``` + +**설계 원칙**: (1) M2(홀 좌표계 위 부스 폴리곤) → M3(부스 내부 설계) → M4(배선) → M5(시각화)가 **하나의 공간 데이터 모델(PostGIS 지오메트리)을 공유**한다. 모든 모듈의 산출물이 좌표를 가지므로 시각화·검증·정산·wayfinding·BI가 같은 원천에서 나온다. (2) **폐루프 연결고리 = M15 옥션**: 코어(M2~M5)의 AI 산출물을 응찰 근거로 소비해 발주(M9)·시공으로 잇는다. (3) **M18 관리자**가 룰셋·마스터데이터·RBAC를 전 모듈·전 포털에 공급한다. + +### 4-1. 모듈 우선순위 총괄 (M1~M18) + +| 계열 | 모듈 | 우선순위 | v2.0 | +|---|---|---|---| +| 코어 | M2 배치 · M3 부스설계 · M4 배선 · **M5 나노바나나** | **P0** | 보존 | +| 판매운영 | M1 배정견적 · M6 서류 · M7 매칭 · M9 정산 | P1 | 보존 | +| 판매운영 | **M15 공사/장치 옥션(입찰)** | **P1(핵심 플로우)** | 신규 | +| 판매운영 | M8 반입/반출 물류 | P2 | 보존 | +| 관람참가 | **M10 관람객 등록·배지·체크인·리드캡처** | **P1** | 신규 | +| 관람참가 | **M12 마케팅·EDM·공개 홍보 사이트** | **P1** | 신규 | +| 관람참가 | M11 비즈니스 매칭 | P2 | 신규 | +| 관람참가 | M13 wayfinding·실내 내비 | P2 | 신규 | +| 관람참가 | M14 현장운영(혼잡·안전·주차·에너지) | P2 | 신규 | +| 경영 | **M16 경영분석 BI** | **P1(승격)** | 신규 | +| 경영 | **M17 CMS** | **P1** | 신규 | +| 경영 | **M18 관리자 시스템** | **P1** | 신규 | + +--- + +## 5. 기능 상세 (모듈별) + +우선순위 기준: **P0** = 핵심 차별화 + 첫 상용 행사 적용 필수 / **P1** = 운영 효율 핵심 / **P2** = 확장. + +### M1. 행사·홀 배정 및 자동 견적 — P1 + +- **현재**: HWP 배정신청서 제출 → 담당자 협의 → 견적 수령 (수일). +- **AI 자동화 후**: 행사일정 DB 연동 가용성 캘린더에서 홀/반홀(예: 5A홀) 선택 → 규칙 엔진이 즉시 견적: `2,250원/㎡ × 면적 × 일수 × 성수기(3~5월·9~11월 +10%)/비수기(1·2·7·12월 -10%) × 1전시장 +10%` + 초과시간(시간당 1일 임대료의 1/10, 기본 12시간 08~20시, 장치일 6시간 무료) + 관리비 예치금 15~20%. 로비 10,000원/㎡·옥외 2,000원/㎡ 포함. 배정신청서는 웹폼 입력 → 킨텍스 제출 서식 자동 생성. +- **기대 효과**: 견적 리드타임 수일 → 즉시. 배정 협의는 사람이 유지(인기 행사 1~2년 전 접수 등 영업 판단 존재). +- **한계**: 최종 배정 확정은 킨텍스 내부 의사결정 — 시스템은 '신청+가견적'까지. +- **필요 데이터**: 임대요율표, 행사일정 DB, 홀/반홀 면적 마스터(1A 4,941㎡/1B 5,670㎡ 등). +- **연동**: 행사일정 시스템, M9 결제. + +### M2. 플로어플랜 스튜디오 (부스 배치 자동화) — **P0** + +- **현재**: 주최자가 CAD로 배치도 수작업 → D-7 kxwp 제출 → 홀매니저 육안 검수. +- **AI 자동화 후**: + 1. 홀 선택(예: 홀7 126×90m·바닥하중 5t/㎡·510부스 기준) + 조건 입력(목표 부스 수, 3×3m 기본/프리미엄 비율, 주출입구·무대·라운지) + 2. 배치 엔진이 통로 폭·비상구 접근·트렌치 위치를 제약조건으로 **정확히 3안(1안·2안·3안) 생성** (제약 충족 솔버 + 휴리스틱; 생성형 LLM이 아닌 결정적 알고리즘 중심, LLM은 조건 해석에 사용). 3안은 서로 다른 최적화 목표를 갖도록 다양화(예: 1안=부스 수 최대, 2안=동선·프리미엄 가시성 우선, 3안=피난·안전 여유 우선). + 3. **선택 또는 병합(merge)**: 사용자는 ① 한 안을 그대로 **선택**하거나, ② 여러 안의 구역/블록을 골라 **병합** — 예: "1안의 통로 구성 + 2안의 프리미엄존 배치 + 3안의 무대 위치"를 조합해 하나의 최종 배치로 합성. 병합 편집 화면에서 안별 레이어를 토글·드래그로 조합. + 4. 규정 자동 검증: 피난 통로 확보, 홀별 바닥하중(홀6 2t/㎡ vs 홀7~10 5t/㎡), 복층부스 가능 홀(고층고 12~15m 홀) 여부, 소방 규정 체크리스트. **병합 결과는 규정 검증을 재실행**(통로·바닥하중·비상구 재판정) — 병합으로 제약이 깨질 수 있으므로 확정 전 필수. + 5. **최종안 확정 → 버전 기록**: 확정 배치는 버전으로 저장(선택/병합 출처 안 번호 추적). 부스별 좌표·번호가 확정되면 참가업체 초대 링크 발급 → M3/M4의 입력이 됨. +- **기대 효과**: 배치 초안 수일 → 수 분. 검수는 "위반 플래그 확인" 작업으로 전환. 3안 비교·병합으로 주최자 영업 관행 반영 유연성 확보(R7 완화). +- **한계**: 소방 법규의 최종 유권해석·승인은 관할 기관/킨텍스 몫. 시스템 검증은 사전 필터. +- **필요 데이터**: 홀별 실측 도면(63×171m, 층고 10~15m, 기둥·셔터·비상구 좌표 — **킨텍스로부터 CAD 원본 확보 필요, 미확보 시 공개 규격 기반 근사 도면으로 Phase 1 진행**), 트렌치 그리드 좌표. +- **연동**: M5(홀 전경 시각화), M6(부스배치도 제출 서류 자동 생성), kxwp. + +### M3. 부스 설계 스튜디오 (인테리어·장치 공사 설계) — **P0** + +- **현재**: 조립부스는 주최측 기본 구조에 간판/가구/조명 옵션 신청서 작성. 독립부스는 장치업체가 평면·입면·조감·전기도면 작성 → kxwp 제출 → 반려 시 재작업. +- **AI 자동화 후**: + - **조립부스**: 옵션(간판 문구, 가구, 조명)을 웹에서 선택 → 3D 프리뷰 + M5 예상 사진 즉시 생성. + - **독립부스**: 부스 크기·업종·전시품·예산을 입력하면 AI가 레이아웃 초안(안내데스크, 시연존, 상담존, 창고) + 파라메트릭 구조(벽체·트러스·사인)를 **정확히 3안(1안·2안·3안) 생성**(예: 1안=시연 강조, 2안=상담·상권 동선 우선, 3안=예산 절감형). 사용자는 M2와 동일하게 ① 한 안 **선택** 또는 ② 여러 안의 구역/집기 블록을 조합해 **병합**해 최종 부스 설계를 만든다. 병합 결과는 규정 사전 검증(높이·이격·방염)을 재실행하고 최종안은 버전으로 기록. 장치업체는 확정 초안을 편집. + - **규정 사전 검증**: 높이 5m 이하, 리깅 천장 6.5~8.5m(구조계산서 D-7 필요 플래그), 복층 1/2 이내, 방염 자재 체크리스트, 장내 금지작업(전기톱·용접·페인트) 공정 경고를 **제출 전에** 자동 플래깅. + - 기존 도면(PDF/이미지) 업로드 시 비전 모델로 치수·구조 추출 → 동일 검증 적용 (정확도 한계로 "참고용 검증" 라벨). +- **기대 효과**: 반려 재작업 감소, 참가업체-장치업체 간 컨펌 사이클 단축(예상 사진으로 합의). +- **한계**: 자동 생성 설계는 '초안'. 시공 상세도·구조 판정은 장치업체/구조기술사 책임 — UI에 명시. +- **필요 데이터**: 부스 좌표(M2), 조립부스 표준 자재 카탈로그, 장치 규정집. +- **연동**: M7(장치업체 매칭), M5, kxwp(도면 제출). + +### M4. 유틸리티 설계 자동화 (전기·조명 / 네트워크·급배수) — **P0** + +두 서브모듈로 구성하되 하나의 배선 엔진 공유. + +**M4a. 전기·조명** +- **현재**: 참가업체가 필요 용량을 추정해 신청(1kW 55,000원, 분전반 50A 추가 100,000원), 위치표시도 수기 작성, 공급은 장치 마지막 날 오후. 조명 설계는 장치업체 감. +- **AI 자동화 후**: 부스 내 기기 목록(전시장비·조명·PC) 입력 → kW 합산 → 분전반 용량·수량 자동 산출 → 최근접 트렌치에서 분전반까지 배선 경로 자동 생성(통로 횡단 최소화) → 요금 자동 견적. 조명은 부스 설계(M3) 기반 조도 목표(전시품 강조/상담존)별 배치안 제안 → 야간 점등 예상 이미지(M5). +- **기대 효과**: 용량 과소신청(현장 증설 불가 리스크)·과다신청 방지, 홀매니저는 홀 단위 부하 집계로 안전 관리. +- **한계**: 실제 전기 시공은 등록 전기시설 업체 수행. 조도 계산은 근사치(정밀 조도 시뮬레이션은 P2). + +**M4b. 네트워크(인터넷/전화)·급배수·압축공기** +- **현재**: 인터넷 유선 150,000원/회선(KT 경유 회선당 80,000원 안내 병존 — **요금 정합성 킨텍스 확인 필요**), **현장 추가신청 불가**, 마감 약 D-25. 급배수·압축공기 각 150,000원/구, 위치표시도 온라인 등록 필수. +- **AI 자동화 후**: 부스 도면 위 단말 위치 클릭 → 트렌치 최단 배선 자동 산출 → 위치표시도 자동 생성(수기 작도 폐지) → 견적·신청·마감 리마인더(D-25 역산 알림)를 한 화면에서. 배선은 M5 오버레이 이미지로 확인. +- **기대 효과**: "현장 추가 불가" 유틸리티의 신청 누락 방지가 참가업체 최대 리스크 제거. +- **필요 데이터**: 홀별 트렌치 그리드 실측 좌표(홀1·7 가스 포함 여부 등 홀별 공급 매트릭스), 요금표 마스터. +- **연동**: M9(결제), kxwp/주최자 사무국(신청 릴레이), KT(인터넷 개통 — Phase 2 협의). + +### M5. 나노바나나 시각화 — **P0 (핵심 차별화)** + +- **현재**: 시공 결과를 사전에 볼 수 없음. 조감도는 외주 산출물로 배선·조명 미반영. +- **AI 자동화 후**: M2~M4의 구조화 데이터를 프롬프트로 컴파일해 Gemini 이미지 생성으로 "시공 후 사진" 표준 샷 세트 자동 생성. 상세는 6장. +- **기대 효과**: 참가업체 의사결정 가속, 주최자의 참가업체 유치 영업 자료, 장치업체 컨펌 커뮤니케이션 비용 절감. +- **한계**: 생성 이미지는 실제 시공과 다를 수 있음 — 전 이미지 워터마크·고지 필수(10장 리스크 참조). + +### M6. 서류·마일스톤 워크플로 — P1 + +- **현재**: D-7에 신고서류 7종+(행사운영계획서, 부스배치도, 재해대처계획서, 방화관리 책임서약서, 주차관리 신청서, 보안요원 배치계획, 위험물 반입신고서, 리깅 구조계산서)를 HWP 작성 후 kxwp 업로드. 마감 추적은 담당자 수첩. +- **AI 자동화 후**: 행사 생성 시 D-150(배정)/D-30(사전협의)/D-25(유틸리티)/D-7(신고서류) 마일스톤 자동 생성·역산 알림. 서식은 웹폼 → HWP/PDF 자동 생성(킨텍스 제출 형식 유지). LLM 서류 검수: 누락 항목, 배치도-운영계획서 간 불일치(부스 수 등), 재해대처계획서 필수 요소 체크 → 홀매니저에게 검수 요약 리포트. +- **기대 효과**: 마감 지연 사고 감소, 홀매니저 검수 시간 단축. +- **한계**: kxwp 내부 API 미공개(robots.txt 차단, 로그인 폐쇄형) — 초기에는 "제출용 파일 생성 + 업로드 안내" 릴레이 방식, 연동은 킨텍스 협의 후. + +### M7. 등록업체 매칭·견적 — P1 + +- **현재**: 14개 분류(전시디자인설치, 리깅, 전기시설, 카펫/파이텍스, 급배수/Air, 가스설비, 철거, 운수통관, 가구비품, 경비용역, 광고싸인물, 지게차, 방염, 구조해석) × 739개 업체 리스트를 지역 필터로 검색, 엑셀 다운로드. +- **AI 자동화 후**: 부스 규모·업종·예산·지역 기반 추천 → M3 설계안 첨부한 견적요청(RFQ)을 복수 업체에 발송 → 견적 비교. **독립부스 미등록 업체 시공 엄금** 규정을 시스템이 강제(등록업체만 초대 가능). +- **한계**: 업체 응답률·견적 품질은 시장 참여에 의존. 초기엔 매칭+연락 중개까지. + +### M8. 반입/반출 물류 슬롯 — P2 + +- **현재**: 화물차 순번제·통행증, 중량물 5t 이상 우선, 지게차 지정업체 사전신청, 적재물 방치 시 즉시 폐기 — 현장 대기열 운영. +- **AI 자동화 후**: 하역장·화물출입구 슬롯 예약제, 중량물 우선순위 자동 배치, 통행증 QR 발급, 지게차 신청 연동. 철거일 피크 대기열 시뮬레이션. +- **한계**: 현장 통제 인력 운영과 결합해야 실효 — 킨텍스 운영팀 협업 전제. + +### M9. 정산·결제 — P1 + +- **현재**: 계약금 20%→중도금 30%+20%→잔금 30%+예치금 15~20% 수동 관리, 행사 후 전기사용료·폐기물 처리비 정산. +- **AI 자동화 후**: 납부 스케줄 자동 생성·알림, 유틸리티 신청 건 PG 결제, 행사 후 실사용(전기 검침 등) 대비 예치금 정산 내역 투명화. +- **한계**: 킨텍스 재무 프로세스(세금계산서 등)와의 연동 협의 필요. + +--- + +## 5A. v2.0 신규 모듈 (M10~M18) + +> 벤치마크 근거는 각 모듈 말미 "근거"에 명시(크롤링 §머리말). 근거 없는 기능 확장은 배제하고, 킨텍스 도메인(공간 데이터·나노바나나·등록업체 규정)과 접합점이 있는 것만 채택했다. + +### M15. 공사/장치 옥션(입찰) 플랫폼 — **P1 (핵심 플로우)** + +> v2.0의 사업적 종결 모듈. **P0 코어(M2~M5)의 AI 산출물이 곧 응찰 근거 자료**가 되어, 설계→시각화→발주가 한 흐름으로 닫힌다. + +- **현재**: 독립부스 시공은 킨텍스 등록 장치업체 필수이나(미등록 엄금), 참가업체는 739개 업체 리스트를 엑셀로 받아 개별 접촉·수기 견적 취합. 견적 비교·경쟁 유도 수단 없음. +- **AI 자동화 후 — 역경매(reverse auction) 옥션**: + 1. **자료 열람**: 참가업체/주최자가 옥션을 개설하면, 초대(또는 공개)된 **킨텍스 등록업체만** 포털에서 AI 생성 자료 — M2 배치도·M3 부스 설계안·M4 배선/**물량서(BOQ)**·M5 나노바나나 시공 예상 이미지 + 스펙/사양서 — 를 열람. + 2. **응찰 = 견적서(Quotation) 제출**: 업체는 열람 자료에 근거해 **정식 견적서를 제출하는 것으로 응찰**한다. 견적서 모델 = 항목(공종·자재)·수량·단가·금액·납기·유효기간·조건 라인 + 첨부(도면/사양)·**총액·부가세**. 견적서는 **PDF로 산출·버전 관리**(수정 시 새 버전, 라운드 내 재응찰 이력 보존). + 3. **옥션 메커니즘**: 옥션 유형 설정형 — **기본 역경매**(라운드/마감 내 더 낮은 금액 또는 더 높은 종합점수로 재응찰) / 필요 시 단일 라운드 RFQ·고정가 비교. **응찰 라운드·마감·실시간 순위** 노출(현재 순위/최저가/내 위치, 익명 순위 옵션). 라운드 종료 자동 마감. + 4. **낙찰 기준**: **최저가** 또는 **종합평가**(가격 + 평판(과거 시공 평점·규정 준수 이력) + 납기) 가중 스코어. 기준·가중치는 옥션 개설 시 설정, 결과 화면에서 항목별 비교표 제공. + 5. **낙찰(Award) → 계약·발주 연동**: 전시업체(참가업체/주최자)가 옥션 결과로 **업체를 확정(낙찰)** → 낙찰 견적서를 계약/발주 문서로 전환(M6 서류·M9 정산 연동), 시공 일정은 M8 반입/마일스톤과 연결. +- **등록업체 게이트(불변)**: M7 등록업체 DB 검증으로 **미등록 업체 응찰 원천 차단**. 14개 분류(전시디자인설치·리깅·전기시설 등)별 옥션 세분 가능. +- **엔티티**: `Auction(옥션: 유형·라운드·마감·낙찰기준·가중치) 1─N Quotation(=Bid, 견적서: 라인아이템·총액·부가세·납기·유효기간·PDF·버전·업체) ─ Award(낙찰: 선정 견적서·사유·계약/발주 링크)`. +- **기대 효과**: 견적 취합 수일·불투명 → 경쟁 응찰로 가격 최적화·투명화. AI 자료 기반이라 **동일 사양 위 공정 비교**(사과 대 사과) 가능. +- **한계**: 업체 참여율·응찰 품질은 시장에 의존. 킨텍스가 등록업체 옥션을 공식 채널로 인정하는지 협의 필요(규정상 '등록업체 시공 필수'는 옥션과 정합). 실제 계약 체결·법적 효력은 당사자 책임 — 시스템은 견적 경쟁·낙찰 기록까지. +- **필요 데이터**: 등록업체 DB(M7), M2~M4 물량/사양, 평판 데이터(초기엔 규정 준수 이력·자기신고, 축적 후 시공 평점), 공종 표준 단가(선택). +- **연동**: M2~M5(자료), M7(업체 검증), M6(계약 서류), M9(발주·정산), M8(시공 일정). +- **근거**: FindRFP·Procore·4castplus(RFQ/RFP/Tender 구분·역경매·종합평가), Exhibitoronline(전시 부스 RFP 항목·타임라인 RFI 180일/RFP 120~150일/RFQ 90일 전). + +#### 입찰(옥션) 플로우 다이어그램 + +```mermaid +sequenceDiagram + participant EX as 참가업체/주최자 + participant AU as M15 옥션 + participant CORE as M2~M5 AI 자료 + participant C1 as 등록업체 A + participant C2 as 등록업체 B + participant M7 as M7 등록업체 검증 + participant AW as 낙찰·발주(M6/M9) + + EX->>AU: 옥션 개설(유형=역경매, 낙찰기준=종합평가, 라운드/마감) + CORE-->>AU: 배치·설계·배선/물량서·나노바나나 이미지 첨부 + AU->>M7: 응찰 자격 검증(등록업체만) + M7-->>AU: A·B 적격 / 미등록 C 차단 + AU-->>C1: 자료 열람 권한 + AU-->>C2: 자료 열람 권한 + C1->>AU: 견적서 v1 제출(총액·납기) + C2->>AU: 견적서 v1 제출 + AU-->>C1: 실시간 순위(현재 2위) + AU-->>C2: 실시간 순위(현재 1위) + C1->>AU: 견적서 v2 재응찰(라운드 내 인하) + AU->>AU: 마감 → 종합점수(가격+평판+납기) 산정 + AU-->>EX: 견적서 비교표 + 순위 + EX->>AW: 낙찰(Award) 선정 + AW-->>C1: 낙찰 통지 → 계약/발주 전환 +``` + +### M10. 관람객 등록·티켓·배지·현장체크인·리드캡처 — **P1** + +- **현재**: 킨텍스 공식은 행사일정 검색 수준. 관람객 등록·배지·리드캡처는 행사별 주최자 사무국에 파편화(공통 플랫폼 부재). +- **AI 자동화 후**: **간편가입(이메일 또는 소셜 로그인) 또는 게스트 예매(가입 없이 티켓 구매, SCR-P7 기반영)** → 온라인 사전등록(관람객/바이어 유형별 폼) → **모바일 배지/QR 발급** → 현장 QR 체크인(즉석 배지 인쇄·오프라인 대비) → 실시간 입장 집계. 참가업체 **리드캡처**: 운영 앱(B2B)으로 관람객 배지 QR 스캔 → 연락처·관심도 평점·메모 저장 → 팔로업 EDM(M12) 연계. 사전등록·체크인 데이터는 M16 BI로 흐른다. +- **계정 트랙·승격 연속성(소유자 확정 2026-07-11, §2-1-1)**: 관람객은 **간편가입 트랙(2FA 미강제)** 이며 게스트 예매를 허용한다. 관람객 → **바이어/참가업체 담당자 승격** 시 **단일 계정 위 등급 상향**으로 처리해 **리드·비즈매칭·재방문 이력의 데이터 연속성**을 유지한다(계정 재생성 없음, 승격 시 업무 트랙 요건 2FA 추가). 게스트 예매 후 간편가입 시 예매 이력을 티켓 지갑에 병합. +- **관람객 AI 도우미(§8A 정합)**: visitor 메인의 AI 도우미는 **§8A-1 사용성 표준**(인라인 진입점·예시 질문 칩·구조화 카드+근거 인용)과 **§8A-2 토큰 최소화**(일정·교통·주차·부스 위치 등 사실조회는 **DB 직접 응답=LLM 미호출 P1**, 종합 필요 시에만 소형모델 우선 P2·RAG 발췌 P3)를 따른다. 이미 DB 근거로 답하는 구조를 §8A 계약(`/ai/ask`)으로 표준화. +- **채널**: 관람객 1차 접점은 공개 웹(SCR-P7/P8), 리텐션은 **관람객 앱(B2C, 스토어 공개)** — 티켓 지갑·배지/QR·wayfinding·비즈매칭(§2-1-1 B). +- **기대 효과**: 현장 등록 대기 제거, 게스트 예매로 가입 마찰 최소화, 참가업체 ROI 측정(리드 수·품질), 관람객 흐름 데이터 확보. +- **한계**: 배지 QR·리드캡처는 개인정보(§10 R10) — 동의·보존정책 필수. 오프라인 체크인 폴백 필요(현장 네트워크 불안정). 게스트 예매는 최소 개인정보 수집·사후 계정 병합 정책 명시 필요. +- **필요 데이터**: 관람객 폼 스키마, 배지 템플릿(M17 CMS), 부스-참가업체 매핑(M2). +- **연동**: M11 비즈매칭, M12 마케팅, M13 wayfinding, M16 BI. +- **근거**: Eventleaf·VenueSight·Whova·WebMobi(자가등록·QR 체크인·즉석 배지·리드 리트리벌 앱·관심도 평점·메모). + +### M11. 비즈니스 매칭 — P2 + +- **현재**: 없음(주최자 개별 운영). +- **AI 자동화 후**: 관람객/참가업체 프로필·관심 업종·의향(intent) 기반 **AI 미팅 추천** → 미팅 슬롯 예약·일정 관리 → 부스 위치(M2)·wayfinding(M13) 연계 길안내. 매칭 성과는 M16 BI. +- **한계**: 매칭 품질은 프로필 데이터 충실도에 의존. AI 추천은 온프레미스/승인된 모델 범위 내(외부 API 게이트 §10 R12 준수). +- **필요 데이터**: 참가/관람 프로필(M10), 부스 업종 태그(M3). +- **연동**: M10·M13·M16. +- **근거**: Brella·Grip·Swapcard·RainFocus·Bizzabo(프로필·intent·행동신호 기반 AI 매치메이킹, 미팅 스케줄링). + +### M12. 마케팅·EDM·공개 홍보 사이트(일반 대중) — **P1** + +- **현재**: 킨텍스 공식 사이트는 정보·서식 다운로드 중심, 참가업체 전용 GNB 없음. +- **AI 자동화 후**: (1) **공개 홍보 사이트**(불특정 다수 대상) — 행사 소개·일정·교통·사전등록 유도, **SEO·다국어(한/영/중/일)** 최적화, 공개 인터랙티브 플로어플랜(M2 데이터 부산물). (2) **EDM/마케팅 자동화** — 세그먼트별(사전등록자·과거 관람객·바이어) 캠페인, 리마인더, 리드 팔로업(M10). AI 카피 초안·이미지(나노바나나 부스 예상샷 활용) 지원. 콘텐츠는 M17 CMS로 관리. +- **기대 효과**: 관람객 유치·재방문, 참가업체 노출, 킨텍스 브랜드 채널 통합. +- **한계**: 발송 규정(정보통신망법·수신동의) 준수, 다국어 번역 품질 검수 필요. +- **필요 데이터**: 행사 마스터(M1), 관람객 세그먼트(M10), 콘텐츠(M17). +- **연동**: M10·M11·M16·M17. +- **근거**: Event Tech Live·Swapcard(등록→리벤뉴 퍼널·EDM), 공개사이트·다국어는 GUARDiA 표준(SEO/다국어) 정렬. + +### M13. Wayfinding·실내 내비 — P2 + +- **현재**: 없음. 양 전시장 100m 무빙워크·복수 홀 구조로 길찾기 난이도 높음. +- **AI 자동화 후**: M2 실측 플로어플랜 위 **블루닷 실내 내비**(부스·시설·비상구·화장실 검색·경로), 관람객 앱(M10)·비즈매칭(M11) 연계. 킨텍스 규모상 UWB/BLE 비콘 하드웨어 인프라 협의 전제(정밀), 미보유 시 **지도 기반 존-레벨 길안내(하드웨어 무의존)로 시작**. +- **한계**: 정밀 측위는 비콘 인프라 투자 필요(킨텍스 시설 협의). 초기엔 인터랙티브 지도·QR 스팟 안내로 대체. +- **필요 데이터**: M2 지오메트리, 시설 POI, (선택)비콘 좌표. +- **연동**: M2·M10·M11·M17(사이니지). +- **근거**: Pointr·Eventbase·Mapsted·Swapcard(블루닷·UWB+BLE·CES 2026 70만 세션), 존-레벨 폴백 실증. + +### M14. 현장운영(혼잡·안전·주차·에너지) — P2 + +- **현재**: 소음 70~75dB 초과 시 전기 차단 등 수기 통제. 주차 iparking. 안전(안전모·금지작업)은 현장 육안. +- **AI 자동화 후**: 홀매니저 운영 대시보드에 **입장·혼잡 실시간(M10 체크인)**, 홀 단위 **전력 부하 집계(M4)**·에너지 모니터, 주차 점유(iparking 연계), 안전 체크(규정 위반 신고·소음·금지작업 플래그). 이상 시 알림. +- **한계**: 센서·IoT 연동은 킨텍스 시설 인프라 의존. 초기엔 M4/M10 파생 데이터 + 수기 입력 결합. +- **필요 데이터**: 체크인(M10), 전력(M4), 주차(iparking), 안전 룰셋(M18). +- **연동**: M4·M8·M10·M16. +- **근거**: Mapsted·Event Tech Live(현장 혼잡·에너지·운영 모니터링), 킨텍스 실측(소음/전력 규정). + +### M16. 경영분석 BI — **P1 (P2→P1 승격)** + +> 기존 design.md에서는 P2 게이트였으나 v2.0에서 **정식 P1 모듈로 스코프 편입**. **design.md 반영은 후속 designer 몫으로 표기**(planner는 스코프·데이터만 확정). + +- **현재**: 정산·가동률·참가사 데이터가 산재. 경영 의사결정은 수기 집계. +- **AI 자동화 후**: 경영 대시보드 — **매출**(임대·유틸리티·옥션 수수료), **홀 가동률**(RevPAD·㎡당 수익·점유율), **참가사 리텐션**(재참가율), **이벤트 P&L**(행사별 손익), **수요예측**(성수기·홀별), **수율/가격 최적화**(요율·성수기 계수 시뮬레이션), **KPI 대시보드**. 온프레미스/승인 모델 범위 내 예측·이상탐지. +- **기대 효과**: 저성과 홀·시즌 식별, 가격·배정 전략 데이터화. +- **한계**: 정확도는 원천 데이터(M1·M9·M10·M15) 정합성에 의존. 예측은 참고치. +- **필요 데이터**: M1 배정·M9 정산·M10 관람·M15 옥션·행사일정. +- **연동**: 전 모듈(데이터 소비), M18(권한). +- **근거**: ExhibitForce·JoinWays·FinancialModelsLab·Digitevent·TicketFairy(RevPAD·㎡당 수익·점유율 60~75%·이벤트 P&L·B2B 전시 KPI). + +#### M16-1. 운영사(킨텍스·venue operator) 관점 수익성/ROI + +> **관점 구분 필수**: BI는 두 관점을 분리 제공한다 — **① 참가업체 관점 ROI**(리드 수·품질·부스 비용 대비 성과, M10 리드 기반)와 **② 킨텍스 운영사 관점 수익성/ROI**(전시장 자산 수익화). 본 소절은 **② 운영사 관점**을 명시한다. 두 관점은 별도 대시보드·권한(참가업체는 자기 부스, 킨텍스는 전 행사)으로 격리. + +| # | 운영사 지표 | 정의/산식 | 데이터원 | +|---|---|---|---| +| ① | **홀·기간별 가동률(occupancy)** | 점유 홀·일수 / 가용 홀·일수 × 100, 반홀(1A/1B) 분할·공실 구분, 성수기/비수기 별 | M1 배정·행사일정 | +| ② | **매출 구성(revenue mix)** | 임대료(2,250원/㎡ 등) + 유틸리티(전기·급배수·인터넷) + 부대시설(옥외·로비·회의실·주차·옥션 수수료) 세그먼트별 | M1·M4·M9·M15 | +| ③ | **행사별 P&L / 수익성(마진)** | 행사 매출 − 직접원가(운영·에너지·인력) = 공헌이익·마진율, 행사 단위 손익 | M9 정산·M14 에너지·비용 마스터(M18) | +| ④ | **행사 유치·전시장별 ROI** | 전시장(1전시장/2전시장/홀별)·행사유형별 투자 대비 수익, RevPAD·㎡당 수익(㎡ 정규화로 대형홀 vs 소형홀 생산성 비교) | M1·M9·PostGIS 면적 | +| ⑤ | **참가사 리텐션·LTV** | 재참가율(코호트)·이탈률, 참가사 생애가치(LTV=누적 임대+유틸+옥션·평균 재참가 주기) | M1·M9 이력·다년 데이터 | +| ⑥ | **수요예측·수율/가격(yield/pricing) 최적화** | 성수기 계수·홀별 수요 예측, 요율·성수기(+10%)/비수기(-10%)·1전시장(+10%) 계수 시뮬레이션으로 수율 최적가 탐색 | M1 요율·과거 배정·M18 룰셋 | +| ⑦ | **경영진 KPI 대시보드** | 위 ①~⑥ 요약 + 목표 대비 실적(점유율 목표 60~75%·매출·마진·리텐션), 전시장·분기 드릴다운 | KpiSnapshot 집계 | + +- **BI AI(§8A 정합·토큰 최소화 핵심)**: 모든 **집계·랭킹·추이 수치는 데이터마트 SQL이 산출(§8A-2 P6)**, LLM은 그 수치에 대한 **자연어 설명·해석만** 담당(수치 계산에 LLM 금지). 자연어 질의(예 "지난 분기 홀7 가동률은?")도 **SQL 집계 → 카드 렌더**를 우선하고, LLM은 설명·후속 제안에만 사용. 동일 기간/스코프 요약은 캐시 재사용(§8A-2 P4). +- **데이터마트 설계(DA 트랙)**: 위 지표는 운영 DB 직조회가 아니라 **BI 데이터마트(스타 스키마: FactBooking·FactSettlement·FactUtility·FactAuction·FactVisitor + DimHall·DimEvent·DimDate·DimExhibitor)** 로 집계한다. `KpiSnapshot`(배치/야간 적재) 또는 읽기 전용 복제로 운영 부하 회피(§8-1). **데이터마트 상세 모델링은 DA(데이터 분석가) 후속 트랙**이며, planner는 지표·데이터원·관점 분리만 확정. +- **한계**: LTV·리텐션은 다년 축적 데이터 필요(초기엔 단년 근사). 수율 최적가는 시뮬레이션 참고치이며 최종 요율 확정은 킨텍스 경영 의사결정(§10 R8). +- **근거**: JoinWays·FinancialModelsLab·TicketFairy(RevPAD·㎡당 수익·점유율 60~75% 목표·이벤트별 P&L·수율 관리), ExhibitForce(이벤트 ROI·수익성 대시보드). + +### M17. CMS — **P1** + +- **현재**: 킨텍스 공지 852건·홍보자료를 공식 사이트가 정적 관리. 참가업체 마이크로사이트 개념 없음. +- **AI 자동화 후**: 전시 **콘텐츠·공지 관리**, **참가업체 마이크로사이트**(부스 소개·제품·나노바나나 예상샷 게시), **다국어**(한/영/중/일) 콘텐츠, **사이니지 연계**(디지털 사이니지·wayfinding 화면 콘텐츠 배포 — GUARDiA Signage 패턴 참고). 게시 워크플로(초안→검수→게시)·버전관리. +- **한계**: 사이니지 하드웨어 연동은 킨텍스 시설 협의. 다국어 번역 검수 필요. +- **필요 데이터**: 콘텐츠 스키마, 행사/부스 마스터, (선택)사이니지 기기. +- **연동**: M12(마케팅)·M13(wayfinding)·M10(배지 템플릿). +- **근거**: GUARDiA CMS·Signage 하네스 패턴(헤드리스 콘텐츠·게시 워크플로·다국어·사이니지 배포) 정렬 + 킨텍스 공지/홍보 도메인. + +### M18. 관리자 시스템(백오피스) — **P1** + +> **M18 = §5B 공통/시스템관리 레이어의 "시스템관리(system)" 모듈이 킨텍스 도메인 마스터데이터를 얹은 것.** 즉 M18은 독립 재구현이 아니라 **UIWS 표준 `system` 모듈을 채택·확장**한 것으로 정의한다(중복 제거). + +- **현재**: 없음(데이터·권한 통제 부재). +- **AI 자동화 후**: 별도 백오피스(`admin.`, 웹 전용) — UIWS 표준 시스템관리(사용자·역할 RBAC·공통코드·메뉴·감사로그·시스템설정) + **킨텍스 마스터데이터 관리**(홀 마스터·요율표·유틸리티 요금·규정 룰셋·등록업체 DB·표준 단가). 룰셋은 **버전 관리**(연 단위 요율·규정 개정 대응 — §8 룰 엔진과 결합). +- **기대 효과**: 크로스-테넌트 통제, 규정·요율 개정의 안전한 반영, 감사 대응. +- **한계**: 마스터데이터 원천(킨텍스 공식 확정본) 확보 필요(§7). +- **필요 데이터**: 전 마스터데이터, 사용자·권한 스키마(UIWS `TB_*`). +- **연동**: 전 모듈·전 포털(RBAC·룰셋 공급). +- **근거**: **UIWS 표준(`workspace/uiws`) 시스템관리** + GUARDiA 표준 프레임워크 §1·§3(사용자·RBAC·감사로그·시스템설정 백오피스 표준) 정렬. + +--- + +## 5B. 공통/시스템관리 레이어 (UIWS 표준 이식) + +> **채택 근거**: kintex 스택(Spring Boot 3.x·Java 17·React·MyBatis·PostgreSQL)이 **UIWS(UIMS, `workspace/uiws`) = GUARDiA 표준 프레임워크**와 동일하므로, 시스템관리·공통 업무 기능을 재설계하지 않고 **UIWS 표준을 공통 레이어로 그대로 이식**한다. 킨텍스 도메인 모듈(부스 M2~M5·옥션 M15·관람객 M10·BI M16·CMS M17 등)은 **이 공통 레이어 위에 얹힌다.** 이식 레퍼런스·정본 = `workspace/uiws`(읽기 전용), 표준 명세 = `workspace/_framework/GUARDIA_STANDARD_FRAMEWORK.md`. 이식 실행은 `uiws-port-orchestrator` 트랙(후속 개발). — **P1 (전 모듈 선행 기반)** + +### 5B-1. 시스템관리 (system) — M18과 통합 + +UIWS 표준 시스템관리를 kintex 관리자 백오피스(`admin.`)의 기반으로 채택. **M18은 이 모듈 + 킨텍스 마스터데이터 확장**이며 중복 정의하지 않는다. + +| 기능 | UIWS 표준 | kintex 확장/접합 | +|---|---|---| +| 사용자 관리 | `TB_USER` CRUD·상태·부서 | 6역할(§2) + 등록업체 계정·관람객 셀프서비스 계정 | +| 역할/권한 RBAC | 역할 게이트 `/api/admin/** = hasRole(ADMIN)` | 플랫폼 레벨(관리자) + 행사 레벨(주최자/참가/업체/홀매니저) 이중 평가(§8-1) | +| 공통코드(adminCode) | 코드 그룹·상세 | 홀/부스유형/공종(14분류)/유틸리티 요금코드 등 도메인 코드 | +| 메뉴 관리 | 메뉴 트리·권한 매핑 | 역할별 포털 IA(§2-1) 메뉴 구동 | +| 감사로그(audit) | `TB_AUDIT_LOG` | 승인·**낙찰(M15)**·설계 변경·룰셋 개정·리드 접근(개인정보) 전수 기록 | +| 시스템설정 | 환경설정 | 요율/규정 룰셋 버전, AI 게이트, 마감(D-25/D-7) 정책 | + +### 5B-2. 공통 업무 기능 (전 역할 공용) + +UIWS 표준 공통 모듈을 이식해 전 포털이 공유. 킨텍스 도메인 접합점을 명시(불필요 이식 배제). + +| 공통 모듈 | UIWS 표준 | kintex 접합 | +|---|---|---| +| worklog(업무일지) | 일일 업무일지·댓글 | 홀매니저 현장 일지, 업체 시공 일지 | +| schedule(일정) | 개인/부서 일정·캘린더 | 행사 마일스톤(M6)·옥션 마감·반입 슬롯(M8) 통합 뷰 | +| message(쪽지) | 사내 쪽지 | 주최자↔참가업체↔업체↔홀매니저 행사 내 커뮤니케이션 | +| notice(공지) | 공지 게시·팝업 | 킨텍스 공지(852건 도메인)·행사 공지 → M17 CMS와 채널 정합 | +| opinion(의견접수) | 의견/건의 | 고객의소리·규정 문의 | +| search(통합검색) | 크로스 모듈 검색 | 행사·부스·업체·문서·콘텐츠 통합 검색 | +| meeting(회의록) | 회의 녹음→STT→회의록(Jasper PDF) | 사전업무협의(D-30) 회의록 자동화 | +| report/보고(stats) | 일/주/월/분기/연 업무보고·통계(Jasper PDF) | 운영 리포트·M16 BI 원천 피드(중복 회피: 경영지표=M16, 업무보고=공통) | +| notification(알림센터) | 통합 알림 | 마감 리마인더(D-데이)·낙찰·승인·결제 알림, WebSocket | +| preference(개인화) | 즐겨찾기·최근방문 | 역할별 대시보드 개인화 | + +> **경계(중복 제거)**: 경영·수익 지표는 **M16 BI**가 권위, 일상 업무보고·통계는 공통 `report/stats`가 담당. 콘텐츠/공지 발행은 **M17 CMS**가 권위, 사내 알림성 공지는 공통 `notice`. 알림 발송 채널은 공통 `notification` 단일화(M10·M12·M15가 이벤트 발행). + +> **공통 AI 보조(§8A 정합)**: 전 업무 화면의 AI 보조(search·meeting 액션아이템·report 요약·초안 생성 등)는 **§8A 단일 AI 계약(`/ai/ask`)·사용성 표준·토큰 최소화 원칙**을 공유한다 — 사실조회는 결정론/DB 직답(LLM 미호출), 종합은 소형모델 우선·Claude 승급(`AiTextRouter`)·RAG 발췌·캐시·구조화 출력. 신규 LLM 직접 호출 경로 신설 금지(중앙 `/ai/ask` 경유). + +### 5B-3. 인증 (UIWS 표준: JWT + 2FA/OTP) + +kintex 인증은 §2 행사 단위 RBAC를 **UIWS 표준 인증 위에** 구현한다(재설계 금지). + +- **JWT + RBAC**: 발급·역할 게이트. §8-1 SSO(플랫폼+행사 이중 권한)와 결합. +- **2차 인증 OTP(TOTP RFC6238)**: SHA1·30s·6자리·±1 윈도우. `TotpService` 이식 — 로그인 2단계(비번→OTP), 최초 QR 등록, 마이페이지 재설정/해제, 관리자 OTP 초기화(`otp_secret=NULL`). **대상(소유자 확정 2026-07-11, §2-1-1 정합)**: **업무 사용자(주최자·참가업체·공사업체·킨텍스 직원·플랫폼/테넌트 관리자) = 필수**, **일반 관람객 셀프서비스 = 미강제(선택)**. 관람객이 바이어/참가업체 담당자로 승격(§2-1-1 A)하면 그 시점부터 업무 트랙 요건으로 2FA가 필수 전환된다. +- **로그인 실패 잠금** + 관리자 해제. +- **admin 비밀번호**: env `ADMIN_PASSWORD_ENC`(AES-256-GCM) + `ADMIN_KEY_FILE`(별도 키파일 root 600) 복호 → 기동 시 BCrypt 재시드. **하드코딩 `admin123` 시드 금지**(§10 보안). +- **스키마**: UIWS `TB_USER`·OTP 시크릿 컬럼·`TB_AUDIT_LOG` 이식(멱등 DDL, sql.init `mode=always`+continue-on-error). + +### 5B-4. 이식 원칙 + +1. **재설계 금지·이식 우선**: 공통 레이어는 `workspace/uiws` 코드/스키마/디자인을 이식(수정 최소화). 킨텍스 고유는 도메인 모듈에만. +2. **선행 기반**: 공통/시스템관리·인증은 도메인 모듈(M1~M17)보다 **선행**(Phase 1 착수 전제 — §9 갱신). +3. **중복 제거**: M18=시스템관리(5B-1), 기존 문서의 "관리자 시스템"은 본 절로 흡수. BI/CMS/알림은 위 경계 규칙으로 공통과 분리. +4. **디자인**: 공통 화면은 UIWS/WISE 디자인을 kintex design.md 토큰으로 정합 — **designer 후속 반영 필요**(planner는 스코프·구조만 확정). + +--- + +### 기능 우선순위 총괄표 + +| 모듈 | 기능 | 우선순위 | 필요 데이터 | 연동 | +|---|---|---|---|---| +| M2 | 부스 배치 자동 생성·규정 검증 | **P0** | 홀 실측 도면, 트렌치 좌표 | kxwp, M5 | +| M3 | 부스 설계 초안 + 규정 사전 검증 | **P0** | 규정집, 자재 카탈로그 | M7, M5, kxwp | +| M4a | 전기 용량·분전반·배선 + 조명 | **P0** | 트렌치 좌표, 요금표 | M9, M5 | +| M4b | 네트워크·급배수 배선 + 위치표시도 자동화 | **P0** | 트렌치 좌표, 요금표 | M9, KT | +| M5 | 나노바나나 시공 예상 사진 | **P0** | M2~M4 데이터, 참조 사진 | Gemini API | +| M1 | 가용성 조회·자동 견적 | P1 | 요율표, 행사일정 | 행사일정 DB | +| M6 | 마일스톤·서류 워크플로 | P1 | 서식 템플릿 | kxwp | +| M7 | 등록업체 매칭 | P1 | 등록업체 DB 739 | CCPY | +| M9 | 정산·결제 | P1 | 요율·납부 규칙 | PG | +| M8 | 반입/반출 슬롯 | P2 | 하역장 배치 | 운영팀 | +| **M15** | **공사/장치 옥션(역경매·견적서 응찰·낙찰)** | **P1(핵심)** | M2~M4 물량/사양, 등록업체 DB, 평판 | M2~M5, M7, M9, M6 | +| **M10** | **관람객 등록·배지·체크인·리드캡처** | **P1** | 관람객 폼, 배지 템플릿, 부스 매핑 | M11, M12, M13, M16 | +| **M12** | **마케팅·EDM·공개 홍보 사이트(SEO·다국어)** | **P1** | 행사 마스터, 관람 세그먼트 | M10, M16, M17 | +| **M16** | **경영분석 BI(운영사 관점 수익성/ROI + 참가사 ROI: 가동률·매출구성·행사별 P&L·전시장 ROI·리텐션/LTV·수율/가격·경영진 KPI)** | **P1(승격)** | M1·M4·M9·M10·M15·행사일정 → BI 데이터마트 | 전 모듈 | +| **M17** | **CMS(콘텐츠·마이크로사이트·다국어·사이니지)** | **P1** | 콘텐츠 스키마, 행사/부스 마스터 | M12, M13 | +| **M18** | **관리자 백오피스(RBAC·감사·마스터데이터·룰셋)** | **P1** | 전 마스터데이터, 사용자/권한 | 전 모듈·전 포털 | +| **§5B** | **공통/시스템관리 레이어(UIWS 표준 이식) + JWT+OTP 인증** | **P1(전 모듈 선행 기반)** | UIWS `TB_*`·표준 스키마 | 전 모듈·전 포털 | +| M11 | 비즈니스 매칭 | P2 | 프로필, 부스 업종 태그 | M10, M13, M16 | +| M13 | wayfinding·실내 내비 | P2 | M2 지오메트리, POI, (선택)비콘 | M2, M10, M17 | +| M14 | 현장운영(혼잡·안전·주차·에너지) | P2 | 체크인·전력·주차·안전 룰셋 | M4, M8, M10 | +| — | 다국어 규정 챗봇, 관람객 플로어플랜 | P2 | 매뉴얼 코퍼스 | — | + +--- + +## 6. 나노바나나 시각화 파이프라인 + +> **제어 파라미터 확정 (v1.1)**: 본 장의 모델·SDK·프롬프트 아키텍처·방어 로직은 ReRoomAI 소스 분석(`docs/analysis/reroomai-source.md`)의 실증 기법으로 확정되었다. ReRoomAI는 "건축 골격 보존 + 표면 요소 교체"라는 동형(同型) 문제(빈 부스 골격 유지 + 배치·인테리어·조명·배선 시공 결과 합성)를 검증된 단일 호출로 해결하고 있어, 그 호출 스택·프롬프트 패턴·방어 로직을 부스 도메인으로 치환해 채택한다. + +### 6-1. 파이프라인 개요 + +``` +구조화 데이터(M2~M4) → 씬 컴파일러(3D 간이 렌더/도면 래스터, 긴 쪽 1024px) → 프롬프트 빌더(구조화 사전 조립) +→ Gemini image-to-image 편집(참조 이미지 inlineData + 지시문 text) → RenderJob 방어·검수 → 후처리(워터마크·메타데이터) → CDN 캐시 +``` + +핵심 원칙: **텍스트 프롬프트 단독 생성이 아니라, 시스템이 만든 도면/간이 렌더를 참조 이미지로 넣어 구조(부스 위치·크기·통로·앵글)를 보존하고 스타일만 사실화**한다. ReRoomAI의 "참조 이미지 기반 구조 보존 + 스타일 변환" 패턴을 부스 도메인으로 이식한다. Stable Diffusion·ControlNet 등 별도 파이프라인 없이 **Gemini 이미지 모델 단일 호출**이 원본 구조를 참조·보존한다는 점이 ReRoomAI에서 실증되었다. + +### 6-2. 입력 데이터 스키마 (요약) + +```yaml +scene: + hall: { id: "H7", dims_m: [126, 90], ceiling_m: 12, floor: "concrete_polished" } + booth: { id: "A-102", polygon: [...], size_m: [6, 3], height_m: 4.2, type: "independent" } + design: # M3 산출 + walls: [...], signage: { text: "...", height_m: 3.8 } + zones: [{ type: "demo" }, { type: "consult" }] + materials: [{ part: "wall", finish: "matte_white", fire_retardant: true }] + lighting: # M4a 산출 + fixtures: [{ type: "spot", count: 6, target: "product" }] + mode: "day" | "night" + wiring: # M4 산출, 오버레이 샷 전용 + power: [{ from_trench: [x,y], to: [x,y], kw: 3 }] + network: [{ type: "lan", path: [...] }] +shot: { preset: "front", camera_height_m: 1.6, fov: 60 } +render_hints: { style: "photoreal_tradeshow", crowd: "sparse" } +``` + +### 6-3. 표준 샷 세트 + +| 샷 | 카메라 | 용도 | 생성 트리거 | +|---|---|---|---| +| S1 부스 정면 | 통로에서 눈높이 1.6m | 참가업체 컨펌 기본 컷 | M3 저장 시 자동 | +| S2 야간/점등 뷰 | S1 동일 구도, lighting=night | 조명 설계 검토 | M4a 조명 확정 시 | +| S3 통로 뷰 | 인접 통로에서 비스듬히, 옆 부스 포함 | 관람객 시선 시뮬레이션 | 요청 시 | +| S4 부스 내부 | 부스 안 상담존 시점 | 내부 동선 검토 | 요청 시 | +| S5 Before/After | 빈 홀 바닥 사진 ↔ S1 합성 페어 | 영업·홍보 | S1 생성 시 자동 페어링 | +| S6 배선 오버레이 | S1/평면 탑뷰에 전기(적)·네트워크(청)·급배수(녹) 경로 오버레이 | 시공업체·홀매니저 검증용 | M4 저장 시 | +| S7 홀 전경(조감) | 홀 전체 아이소메트릭 | 주최자 배치안 비교 | M2 배치안 생성 시 | + +S6(배선 오버레이)는 **생성형 이미지가 아니라 백엔드 래스터 합성이 우선**이다. 시공업체·홀매니저의 검증 산출물이므로 좌표 정확성이 목적이며, 생성 모델의 재질/색 왜곡이 개입되면 안 된다 → PostGIS 배선 지오메트리(전기 적·네트워크 청·급배수 녹)를 S1/평면 탑뷰 위에 백엔드 렌더러로 정확 오버레이하고, **배경만(부스 골격·바닥) 생성 이미지를 사용**한다. 이 경로는 Gemini 호출 없이(또는 배경 1회만) 결정적으로 산출된다. (BACKLOG B-02 — developer 트랙 백엔드 래스터 렌더러로 구현) + +### 6-4. 모델·SDK·프롬프트 아키텍처 (ReRoomAI 실증 기법 확정) + +**(1) 호출 스택 — 검증된 정답 채택** + +| 항목 | 확정값 | 근거 | +|---|---|---| +| SDK | `@google/genai` (Google 공식) | ReRoomAI `route.ts` 프로덕션 검증 | +| 모델 | `gemini-3.1-flash-image-preview` (나노바나나 2 / Nano Banana 2) | 동일 | +| 호출 형태 | `ai.models.generateContent()` — image-to-image 편집 | 동일 | +| 입력 구성 | `parts` 배열에 **입력 이미지 `{ inlineData: { mimeType, data(base64) } }` + 지시문 `{ text }`** 동시 전달 | 멀티모달 인페인팅형 편집 — 원본 구조 참조·보존 | +| 응답 처리 | candidate에서 `inlineData`(생성 이미지 base64) 추출 | 동일 | + +`tools/nanobanana/`(프로젝트 규칙) 모듈이 이 호출 패턴을 표준화하며, `nanobanana-visualize` 스킬이 부스 도메인 래퍼를 제공한다. + +**(2) 프롬프트 = 구조화 사전 조립 + "보존/교체 명시적 분리"** + +ReRoomAI `lib/constants.ts`의 핵심 패턴 — UI 라벨(한글)과 프롬프트 조각(영문)을 한 객체에 묶어 **UI 선택과 서버 프롬프트가 단일 출처를 공유** — 를 부스 도메인 구조화 사전으로 이식한다. 각 항목은 `{ id, label(한글), prompt(영문), swatch? }` 형태. + +```ts +// 부스 유형 — 골격 특성 프롬프트 조각 +BOOTH_TYPES = [ + { id: "assembled", label: "조립부스", prompt: "standard octanorm shell scheme booth, aluminium frame walls" }, + { id: "independent", label: "독립부스", prompt: "custom-built independent booth, free-standing structure" }, + { id: "corner", label: "코너부스", prompt: "corner booth open on two aisle-facing sides" }, + { id: "island", label: "아일랜드부스", prompt: "island booth open on all four sides" }, +] + +// 부스 스타일 — 표면·분위기 프롬프트 조각(+ swatch 색3종) +BOOTH_STYLES = [ + { id: "luxury", label: "럭셔리", prompt: "premium luxury exhibition design: warm wood, brass accents, layered lighting" }, + { id: "tech", label: "테크", prompt: "high-tech booth: LED walls, dark palette, cool white accent lighting" }, + { id: "eco", label: "친환경", prompt: "sustainable booth: recycled timber, greenery, warm diffuse lighting" }, + { id: "minimal", label: "미니멀", prompt: "minimal booth: clean white surfaces, hidden lighting, uncluttered" }, +] + +// 시공 레이어 — 조명/전기/네트워크 레이어별 프롬프트 조각(변형 렌더용) +FIXTURE_LAYERS = { + lighting: { day: "even daylight-balanced exhibition lighting", + night: "dramatic accent spotlights on products, dimmed ambient" }, + power: "power outlets and distribution box neatly integrated at booth base", + network: "network access point and cabling routed along booth structure", +} +``` + +이 사전들은 M2(부스 유형)·M3(스타일·집기)·M4(조명 모드·배선 레이어) UI 선택값과 그대로 매핑되어, 프롬프트 빌더가 조각을 조립한다. + +**(3) 부스 도메인 프롬프트 템플릿 (보존/교체 명시 잠금)** + +ReRoomAI 4단 구성(대상+스타일 → 보존 잠금 → 교체 지정 → 사진 품질)을 부스로 치환: + +``` +Render this exhibition booth as if construction is complete. +① 대상+스타일: {BOOTH_TYPES.prompt} at KINTEX exhibition hall, styled as {BOOTH_STYLES.prompt}. +② 보존 잠금(KEEP EXACTLY THE SAME): + booth outer footprint dimensions, structural columns, floor trench grid, + ceiling truss, aisle direction and the camera angle. +③ 교체·배치(REPLACE / PLACE): + fixtures — desks, shelves, banners, signage; + {FIXTURE_LAYERS.lighting[mode]}; {FIXTURE_LAYERS.power}; {FIXTURE_LAYERS.network}; + carpet and booth wall graphics — to match the target style. +④ 사진 품질: + photorealistic trade-show photography, natural exposure, high detail, + Korean exhibition hall interior (concrete polished / carpet floor per hall). +``` + +- **가변 직렬화**: 씬 스키마(6-2)의 치수·자재·간판 문구를 자연어로 직렬화해 위 슬롯에 주입. 홀별 사전 촬영 참조 사진을 함께 참조 이미지로 전달(홀6 카펫·홀7 콘크리트 폴리싱 등). +- **구조 보존 강화**: 씬 컴파일러 간이 렌더(회색 박스 수준)를 참조 이미지 `inlineData`로 제공 → "이 구도·배치를 유지, 사실적 재질로만". +- **간판 텍스트**: 생성 후 비전 모델로 오탈자 자동 검수. **한글 텍스트 렌더링 불안정은 알려진 한계** → 실패 시 간판 영역 후처리 합성. +- **레이어 변형**: `FIXTURE_LAYERS.lighting.night`만 교체하면 S2(야간 점등), 배선 레이어 강조는 S6(단, S6은 6-3대로 래스터 합성 우선). + +**(4) 일관성·비용 제어** + +- **일관성**: 같은 부스 S1~S5는 동일 참조 체인(간이 렌더 + 직전 결과)으로 생성해 컷 간 자재·색상 일치 유도. 완전 일치는 보장 불가 — UI에 "컷별 차이 존재 가능" 고지. (Gemini 시드 지원 범위는 구현 시 확인 — BACKLOG B-12) +- **비용 제어**: 저장 시 자동 생성은 S1·S7만, 나머지는 온디맨드. **동일 스키마 해시 캐시**. RenderJob 쿼터는 성공 시에만 차감(6-5). + +### 6-5. RenderJob 방어 로직 및 UX (ReRoomAI (D)(E)(G) 이식) + +**(1) Canvas 1024px 전처리 (전송량·비용·지연 동시 절감)** +- 클라이언트에서 도면/현장 사진을 **긴 쪽 1024px 다운스케일 → `toDataURL('image/jpeg', 0.85)` → base64 data URL**로 변환 후 전송. ReRoomAI `Studio.handleImageFile`과 동일. 부스 간이 렌더도 동일 규격으로 정규화. + +**(2) RenderJob 워커 방어 로직 (ReRoomAI `route.ts` 골격 복제)** +- **다층 크기 가드**: content-length 상한(8MB) → base64 실크기(×1.33) 재검증. +- **mimeType 자동 감지**: data URL에서 mimeType + base64 정규식 분리(하드코딩 금지). +- **SAFETY 처리**: 응답 `finishReason==='SAFETY'` → 차단 에러로 분기. +- **에러 분기 → 친화적 한글 메시지**: `API_KEY_INVALID` / `RESOURCE_EXHAUSTED·quota·429` / `SAFETY` 구분. +- **성공 시에만 쿼터 차감**: 실패는 사용량 소모 안 함. ReRoomAI는 인메모리 `Map`이나(재시작·다중 인스턴스 취약) — 본 시스템은 **PostgreSQL/Redis 기반 RenderJob 쿼터**(행사별 상한, 6-4 비용 제어와 통합)로 대체. +- 전 과정 비동기(8장): RenderJob 큐잉 → 워커 Gemini 호출 → WebSocket 완료 푸시 → 재시도·비용 상한·스키마 해시 캐시 워커 레벨 관리. + +**(3) 단계별 로딩 UX** +- ReRoomAI `LOADING_STATUSES` 순환 패턴을 부스용으로 치환: **"부스 골격 인식 → 집기 배치 → 전기·조명 배선 → 최종 고화질 렌더링"**을 `aria-live`로 순환 표시. 진행 배지("생성 중… 평균 40초")와 연결. 결과는 Before/After 드래그 슬라이더(ReRoomAI `CompareSlider.tsx` 거의 무수정 재사용 — clip-path + 포인터 캡처 + 키보드/ARIA)로 S5(빈 부스 ↔ 시공 후) 표시. + +### 6-6. 워터마크·고지 정책 (필수) + +- 모든 생성 이미지에 시각 워터마크 "**AI 생성 예상 이미지 — 실제 시공 결과와 다를 수 있음**" + 메타데이터(생성일, 스키마 해시, 모델 버전) 임베드. +- 계약·심사 서류에는 생성 이미지 사용 금지(도면만 유효) — 시스템이 서류 생성 시 자동 배제. +- 참가업체-장치업체 간 분쟁 예방: 컨펌 화면에 "시공 기준은 도면" 동의 체크. + +--- + +## 7. 데이터 및 연동 + +### 7-1. 마스터 데이터 (킨텍스 실측) + +| 데이터셋 | 내용(분석 문서 실측값) | 확보 방법 | 상태 | +|---|---|---|---| +| 홀 마스터 | 1전시장 홀1~5(홀당 10,611~10,773㎡, **171×63×15m**, 5t/㎡, 약 600부스) + **옥외전시장 2,849㎡**, 2전시장 홀6(5,580㎡=**93×60×10m**, 2t/㎡, 카펫, 200부스)·홀7/8(각 11,290㎡, 126×90×12m, 510부스)·홀9(13,238㎡)/홀10(13,072㎡, 132×99×15m). 반홀 분할(1A 4,941㎡/1B 5,670㎡ 등). **제3전시장(2028) 홀11~18 계획** | 공개 스펙 + 킨텍스 CAD 원본 요청 | 공개값 확보(2차 검증 반영), CAD 협의 필요 | +| 트렌치 그리드 | 홀별 트렌치 위치·공급 매트릭스(전기·급배수·압축공기·전화·인터넷, 홀1·7 가스) | **킨텍스 제공 필수** — 미공개 | 미확보 (Phase 1 착수 조건) | +| 요율 마스터 | 전시홀 2,250원/㎡(12h), 로비 10,000원/㎡, 옥외 2,000원/㎡, 이벤트홀 2,420원/㎡, 성수기 +10%/비수기 -10%/1전시장 +10%, 용도 외 30% 할증, 예치금 15~20% | 공개 임대요율표 | 확보 | +| 유틸리티 요금 | 전기 1kW 55,000원·분전반 50A 100,000원, 압축공기 150,000원/구, 급배수 150,000원/구, 인터넷 150,000원/회선(KT 80,000원 병존 — 정합 확인 필요) | 참가업체 매뉴얼 | 확보(검증 필요) | +| 부스 표준 사양 | **조립(기본)부스 표준 포함 품목: 스포트라이트 5개·220V 2구 콘센트 1개·방염 A급 바닥재·기본 전력 1kW/부스. 프리미엄 부스 6×3×4m·2kW.** 초과 전력·조명은 유틸리티 추가 신청 | 참가업체 매뉴얼(kintex.com 2차 검증) | 확보 | +| 규정 룰셋 | 높이 5m, 리깅 6.5~8.5m+구조계산서 D-7, 복층 1/2, 방염, 소음 70~75dB, **이격(인접 벽 30cm·천장 60cm), 조명 반입 금지(지정 조명만 사용)**, 금지작업 목록 | 매뉴얼 → 룰 엔진 코드화 | 확보 | +| 회의실 마스터 | 37개 회의실, 시간대별 요금 (P2 범위) | 공개 요율표 | 확보 | + +> **v3.0 테넌트 스코프 재정의(§1A-1)**: 위 §7-1 마스터데이터는 모두 **테넌트(전시관) 소유**로 재정의된다 — 표에 기재된 킨텍스 실측값(홀1~10, 2,250원/㎡, 높이 5m·리깅 6.5~8.5m 등)은 **테넌트 #1(KINTEX)의 초기 시드**이며, 코엑스 등 신규 테넌트는 자기 전시관의 홀·요율·유틸리티 요금·규정 룰셋·부스 표준을 **별도 소유·입력**한다(값이 다를 수 있음, 근거 없는 추정 금지). 각 마스터 행에 `tenant_id`가 부여된다(§1A-2). 코엑스 실측값은 미확보 — 온보딩 시 입력(§1A-5). + +### 7-2. 외부 연동 + +| 대상 | 방식 | 불확실성 | +|---|---|---| +| kxwp/kxfp 작업신고 | 초기: 제출 파일 자동 생성 + 업로드 안내(수동 릴레이). 목표: API 연동 | **높음** — 폐쇄형, API 미공개. 킨텍스 IT 협의 필수 | +| 등록업체 DB(739) | 웹 공개 데이터 주기 수집(엑셀 다운로드 제공됨) → 자체 DB화, 추후 공식 피드 | 낮음 | +| 행사일정 시스템 | 공개 캘린더 수집 → 가용성 역산(정확한 가용성은 킨텍스 내부 데이터 필요) | 중간 | +| Gemini API | `tools/nanobanana/` 모듈 경유(프로젝트 규칙), `GEMINI_API_KEY` | 낮음 (쿼터·비용 관리 필요) | +| PG 결제 | 국내 PG(카드·계좌이체·세금계산서) | 낮음 | +| KT 인터넷 개통 | Phase 2 협의 | 중간 | +| iparking(주차) | P2 | — | + +### 7-3. 핵심 엔티티 (요약 ERD) + +`Event(행사) 1─N Hall배정 1─N Booth(부스, PostGIS polygon) 1─N DesignPlan(버전, 3안·선택/병합 출처 추적) / UtilityOrder(전기·네트워크·급배수, 배선 LineString) / RenderJob(샷, 상태, 이미지) / Document(서식, 마일스톤) / Company(등록업체) / Payment` + +**v2.0 추가 엔티티**: +- 옥션: `Auction(유형·라운드·마감·낙찰기준·가중치) 1─N Quotation(=Bid, 견적서: 라인아이템[공종·자재·수량·단가·금액]·총액·부가세·납기·유효기간·조건·첨부·PDF·버전·업체) ─ Award(낙찰: 선정 견적서·사유·계약/발주 링크)`. Auction은 Booth/DesignPlan/UtilityOrder(물량)·RenderJob(이미지)을 참조 자료로 첨부. +- 관람: `Visitor(관람객) 1─N Registration(등록·유형) 1─N Badge(QR) ─ CheckIn(체크인) ; Lead(리드: 참가업체─관람객·관심도·메모) ; Meeting(비즈매칭 미팅·슬롯)`. +- 경영/관리: `KpiSnapshot(BI 집계) ; Content(CMS 콘텐츠·다국어·버전) ; Microsite(참가업체) ; MasterData(홀·요율·요금·룰셋·버전) ; User·Role·AuditLog(M18)`. +- 공간 데이터 공유(불변): Booth 폴리곤·배선 LineString은 M13 wayfinding·M14 부하집계·M16 ㎡당 수익이 동일 PostGIS 원천을 재사용. + +**v3.0 추가 엔티티 (멀티테넌시 §1A)**: +- 최상위 테넌트: `Tenant/Venue(전시관: tenant_code·tenant_name(다국어)·branding·domain/subdomain·active·locale_default) 1─N (전 도메인 엔티티)`. 킨텍스=`tenant_id=1`(기준), 코엑스=`tenant_id=2`. +- **`tenant_id` 전파(불변 격리)**: 위 §7-3의 **전 도메인 엔티티**(Event·Hall·Booth·DesignPlan·UtilityOrder·RenderJob·Document·Payment·Company·Auction·Quotation·Award·Visitor·Registration·Badge·CheckIn·Lead·Meeting·KpiSnapshot·Content·Microsite·MasterData·User membership·Role 매핑·AuditLog)에 `tenant_id`(FK → Tenant) 추가. 모든 조회/쓰기는 `WHERE tenant_id = :ctx` 강제(§8-2). +- **참조 데이터 구분**: 전역 공통코드(국가·통화·언어)는 `tenant_id` 없음(전역), 전시관마다 다를 수 있는 코드(공종 14분류·유틸리티 요금코드·부스유형)는 `tenant_id` 부여(전역 기본값 + 테넌트 오버라이드). +- **역할 계층**: `Role`에 플랫폼 슈퍼관리자(크로스-테넌트) vs 테넌트 관리자(단일 테넌트) 계층(§1A-4). User–Tenant 멤버십(다중 소속 허용, 컨텍스트는 단일 고정 §1A-3). +- **마이그레이션**: 기존 전 행 `tenant_id=1(KINTEX)` 백필(§1A-5, DDL은 db-engineer/DA 후속). + +--- + +## 8. 아키텍처 개요 + +전제 스택 (확정, GUARDiA 표준 프레임워크 정렬): **React 18/19(Vite·TypeScript) + Spring Boot 3.x(Java 17) + MyBatis + PostgreSQL(PostGIS) + Redis 작업 큐 + 나노바나나 Python 워커 사이드카**. + +```mermaid +graph LR + subgraph Frontend + WEB[React 18/19 웹 (Vite·TS)
반응형: 데스크톱=설계·에디터, 모바일=조회·승인·현장] + CANVAS[플로어플랜 캔버스
SVG/WebGL 편집기] + end + subgraph Backend + API[Spring Boot 3.x (Java 17)
REST + WebSocket/STOMP 진행 알림] + RULE[룰 엔진
규정 검증·요율 계산 (서비스 계층)] + LAYOUT[배치·배선 엔진
제약 솔버 + PostGIS 공간 SQL] + MYB[MyBatis
매퍼·공간 SQL 바인딩] + QUEUE[비동기 작업 큐 Redis
RenderJob·서류 생성·알림] + NB[나노바나나 Python 워커 사이드카
tools/nanobanana · google-genai SDK] + end + subgraph Data + PG[(PostgreSQL + PostGIS
공간 데이터·업무 데이터)] + OBJ[(오브젝트 스토리지
도면·생성 이미지·서식)] + end + WEB --> API + CANVAS --> API + API --> RULE + API --> LAYOUT + API --> MYB --> PG + LAYOUT --> MYB + API --> QUEUE --> NB --> OBJ + NB -.완료 푸시(WebSocket).-> API + NB -.Gemini API.-> EXT[Google Gemini] +``` + +- **백엔드 = Spring Boot 3.x(Java 17) + MyBatis**: REST API와 실시간 진행 알림은 Spring Web + WebSocket(STOMP)로 처리. 룰 엔진(규정·요율)과 배치/배선 엔진은 Spring 서비스 계층으로 두고, 공간 연산은 MyBatis 매퍼가 바인딩하는 **PostgreSQL PostGIS 공간 SQL**(부스 폴리곤·트렌치 포인트·배선 LineString)로 수행. +- **공간 데이터 일원화**: 부스 폴리곤·트렌치 포인트·배선 경로를 PostGIS 지오메트리로 저장 — 최단 배선(라우팅), 통로 폭 검증(버퍼 연산), 면적 정산이 모두 SQL 수준에서 수행. MyBatis가 `ST_*` 함수 호출을 매퍼 XML로 관리. +- **프론트 = React 18/19(Vite·TypeScript)**: 반응형(데스크톱=설계/에디터, 모바일=조회·승인·현장). 플로어플랜 캔버스는 SVG/WebGL. 현장 시나리오(홀매니저 검수 체크, 참가업체 승인, 반입 QR)는 모바일 뷰 최적화. UI 상세는 후속 `docs/design.md`. +- **이미지 생성은 전면 비동기 — Python 워커 사이드카**: Spring 백엔드가 RenderJob을 Redis 작업 큐에 넣으면 **별도 Python 워커(`tools/nanobanana`)** 가 소비해 Gemini(google-genai Python SDK)로 이미지를 생성하고, 결과를 오브젝트 스토리지에 적재한 뒤 WebSocket으로 완료를 푸시한다. 서류/알림 생성도 동일 큐를 경유. 재시도·비용 상한·스키마 해시 캐시는 워커 레벨에서 관리. + - **Python 워커 유지 근거**: 나노바나나 호출 스택(client.py)은 방금 ReRoomAI 검증 패턴으로 확정되었고 **google-genai는 Python SDK**를 사용한다(§6-4). 이를 Java로 재구현하면 검증된 방어 로직·프롬프트 조립을 이식·재검증하는 비용이 발생하므로, image-to-image 파이프라인은 **Python 워커 사이드카로 유지**하고 Spring 백엔드는 큐·오케스트레이션·상태 관리만 담당한다(Java 재구현 대신 얇은 큐 계약으로 결합). +- **룰 엔진 분리**: 규정(높이·방염·하중)과 요율을 코드가 아닌 버전 관리되는 룰셋 데이터로 유지 — 킨텍스 규정 개정(연 단위 요율 변경 등) 대응. Spring 서비스 계층이 룰셋을 로드·평가. +- 인증: 행사 단위 RBAC(2장 권한 모델) + JWT. 오브젝트 스토리지에 도면·생성 이미지·서식 적재. 도면·설계 데이터는 행사 종료 후 보존 정책 별도 정의(참가업체 자산). + +### 8-1. v2.0 아키텍처 보강 — 역할별 분리 프론트 + 공유 백엔드 + 공개사이트/백오피스 + +확정 스택(React + Spring Boot 3.x(Java 17) + MyBatis + PostgreSQL/PostGIS + Redis + 나노바나나 Python 워커)은 **불변**. 그 위에 v2.0의 다중 포털·공개사이트·백오피스를 얹는다. + +```mermaid +graph TB + subgraph 프론트["역할별 분리 프론트 (React·Vite·TS, 공유 디자인시스템)"] + FO[organizer. 주최자 콘솔] + FE[exhibitor. 참가업체 포털] + FC[contractor. 업체 포털·옥션] + FM[ops. 운영 대시보드] + FA[admin. 관리자 백오피스] + FP[www/expo. 공개 홍보 사이트
SEO·SSR·다국어] + FV[관람객 모바일 앱
배지·wayfinding·매칭] + end + subgraph 게이트["SSO · 역할 RBAC · API Gateway"] + SSO[JWT SSO + 역할·행사 RBAC] + end + subgraph 백엔드["공유 Spring Boot 3.x 백엔드"] + API[REST + WebSocket/STOMP] + RULE[룰 엔진·요율/규정] + LAYOUT[배치·배선 엔진 PostGIS] + AUC[옥션 엔진 M15
라운드·순위·낙찰스코어] + BI[BI 집계 M16] + CMS[CMS·다국어 M17] + QUEUE[Redis 큐] + NB[나노바나나 Python 워커] + end + subgraph 데이터["PostgreSQL+PostGIS · 오브젝트 스토리지"] + PG[(업무·공간 데이터)] + OBJ[(도면·이미지·서식·콘텐츠)] + end + FO & FE & FC & FM & FA & FP & FV --> SSO --> API + API --> RULE & LAYOUT & AUC & BI & CMS + API --> QUEUE --> NB --> OBJ + API --> PG + FP -. 캐시/CDN .-> OBJ +``` + +- **역할별 프론트 분리**: organizer·exhibitor·contractor·ops·admin 5개 인증 앱 + public(공개)·visitor(관람객 모바일). 각기 별도 번들·도메인/서브패스로 배포해 **최소권한·공격면 축소**, 단 **공유 디자인 시스템(design.md)·공유 컴포넌트·공유 API 계약**을 상속(중복 구현 금지). 데스크톱=설계/에디터/대시보드, 모바일=현장/조회/승인(§2-1 매트릭스). +- **SSO + 역할 RBAC + 2FA/OTP (§5B UIWS 표준)**: 단일 JWT SSO 위에 플랫폼 레벨(관리자)과 행사 레벨(주최자/참가/업체/홀매니저) 권한을 이중으로 평가. **인증 스택은 UIWS 표준을 이식** — JWT + TOTP(RFC6238) 2차 인증 + 로그인 실패 잠금 + admin 비번 env(`ADMIN_PASSWORD_ENC` AES-256-GCM + 별도 키파일) 주입(§5B-3). M18(=§5B-1 시스템관리)이 역할·권한·공통코드·메뉴·감사로그 마스터를 공급. 공통 업무 기능(worklog·schedule·message·notice·search·meeting·report·notification 등, §5B-2)은 전 포털 공유 레이어. +- **공개 홍보 사이트·CMS(M12·M17) — SEO·다국어**: 불특정 다수 대상이므로 **SSR/정적 생성 + 메타·사이트맵·구조화 데이터(SEO)**, **다국어(한/영/중/일) i18n·hreflang**, CDN 캐시. 인증 앱과 별도 렌더 경로(공개 성능·검색 노출 목적). 콘텐츠는 M17 헤드리스 CMS가 공급, 참가업체 마이크로사이트도 동일 파이프라인. +- **관리자 백오피스(M18)**: 웹 전용 별도 앱. 마스터데이터·룰셋(요율·규정)은 **버전 관리 데이터**로 룰 엔진에 로드 — 킨텍스 연 단위 개정 무중단 반영. 전 승인·낙찰·설계 변경은 감사로그. +- **옥션 엔진(M15)**: Spring 서비스 계층 + Redis(실시간 순위·라운드 마감 타이머) + WebSocket(순위 푸시). 견적서 PDF 생성은 서류 생성 큐(Redis) 재사용, 나노바나나와 동일 비동기 패턴. +- **BI(M16)**: 운영 DB 부하 회피를 위해 집계는 배치/스냅샷(KpiSnapshot) 또는 읽기 전용 복제 권장(구현 트랙 결정). 예측·이상탐지는 §10 R12(외부 API 게이트) 준수 — 온프레미스/승인 모델 범위. + +### 8-2. v3.0 멀티테넌트 격리 전략 (§1A 구현 아키텍처) + +확정 스택(§8·§8-1)은 **불변**. 그 위에 테넌트 격리 레이어를 얹는다. + +- **격리 전략 = 공유 스키마 + `tenant_id` 컬럼(단일 DB 유지)**: 현행 단일 DB `kintex_db`를 **유지**하고, 전 도메인 테이블에 `tenant_id` 컬럼을 두어 논리 격리한다. **테넌트별 DB 분리(DB-per-tenant)·스키마 분리는 채택하지 않는다** — 전시관 수(수 개~수십 개) 대비 운영·마이그레이션·배포 비용이 과하고, 크로스-테넌트 BI(§1A-2)·공유 나노바나나 워커·단일 배포 파이프라인과 상충. 공유 스키마 + tenant_id가 GUARDiA 표준(단일 DB·Hikari max 3) 및 SaaS 정석에 정합. + + | 전략 | 채택 | 사유 | + |---|---|---| + | 공유 스키마 + `tenant_id` 컬럼 | **채택** | 단일 `kintex_db` 유지, 운영·배포 단순, 크로스-테넌트 집계 용이, 온보딩 저비용 | + | 스키마-per-tenant | 미채택 | 마이그레이션 N배·커넥션 풀 부담, 이득 대비 과함 | + | DB-per-tenant | 미채택 | 인프라·배포·백업 N배, 소수 전시관에 과대 | + +- **강제 격리 계층 (fail-closed 다층 방어)**: + 1. **컨텍스트 해소 필터**: 게이트웨이/서블릿 필터가 서브도메인·JWT 클레임에서 `tenant_id`를 해소해 요청 컨텍스트에 주입(§1A-3). 미해소·불일치 요청은 **거부**. + 2. **서비스 계층 가드**: 컨텍스트 `tenant_id`를 신뢰 원천으로, 클라이언트가 보낸 tenant 파라미터는 **무시/검증**(위조 차단). + 3. **MyBatis 매퍼 강제 바인딩**: 전 매퍼 SQL에 `AND tenant_id = #{ctxTenantId}` 조건을 **공통 인터셉터/베이스 매퍼**로 주입(개별 쿼리 누락 방지). 쓰기 시 `tenant_id`를 컨텍스트에서 자동 세팅(클라이언트 입력 금지). + 4. **PostGIS 공간 쿼리도 동일**: 부스 폴리곤·배선 라우팅·면적 정산 등 `ST_*` 쿼리도 `tenant_id` 조건 하에서만 수행(전시관 간 공간 데이터 혼입 차단). +- **성능(테넌트 인덱스)**: 격리 쿼리가 항상 `tenant_id`를 선행 조건으로 가지므로 **`(tenant_id, …)` 선두 복합 인덱스**를 표준화(예: `(tenant_id, event_id)`, `(tenant_id, hall_id)`, PostGIS는 `tenant_id` + GiST 부분 인덱스). BI 데이터마트(§M16 Fact/Dim)도 `DimTenant` 추가·`tenant_id` 파티션 키 고려(DA 후속). +- **보안(교차 테넌트 차단)**: 전 계층 tenant 강제 + 감사로그(§5B-1)에 `tenant_id` 기록. 크로스-테넌트 접근은 플랫폼 슈퍼관리자 전용 API로만(명시적 권한 게이트·감사). 나노바나나 오브젝트 스토리지 경로·RenderJob 쿼터(§6-5)도 `tenant_id` 프리픽스로 격리(전시관별 이미지·쿼터 분리). +- **온보딩(새 전시관 추가 절차)**: ① 플랫폼 슈퍼관리자가 테넌트 마스터 생성(tenant_code·subdomain·branding·active=false) → ② 서브도메인·DNS·(선택)브랜딩 테마 등록 → ③ 해당 전시관 마스터데이터 입력(홀·요율·규정 룰셋·부스 표준·등록업체 — 근거 없는 추정 금지, §1A-5) → ④ 테넌트 관리자·홀매니저 계정 발급(OTP 등록) → ⑤ 스모크(격리 검증: 타 테넌트 데이터 불가시 확인) → ⑥ `active=true`. **코드 배포 없이 데이터 온보딩만으로 신규 전시관 오픈**(공유 스키마 이점). +- **후속 반영 필요**: 필터·인터셉터·인덱스·마이그레이션 DDL은 **db-engineer/DA/backend 후속 트랙**(planner 설계만). `docs/architecture/*.md`·`docs/design.md`·src 미반영. + +--- + +## 8A. AI 사용성 & 토큰 최소화 아키텍처 (v3.4, 소유자 지시 2026-07-12) + +> **소유자 지시**: "기획자는 AI 기능을 **쉽게 사용**할 수 있도록 기획하고, **토큰을 최소한으로 사용**하는 방식을 채용하라." 본 절은 전 모듈에 걸친 **AI 사용성 표준(§8A-1)** 과 **토큰 최소화 설계 원칙(§8A-2)** 을 명문화한다. **재발명이 아니라 이미 진행 중인 패턴의 표준화**다 — visitor 관람객 AI 도우미가 이미 **DB 근거로 답하고**, 공통 AI 계층이 **`AiTextRouter`로 Claude→Ollama(소형) 폴백**하며, 크롤 적재 DB(행사 데이터 등)를 근거로 삼는 구조가 존재한다. 본 절은 이를 **원칙·계약·측정지표로 고정**해 전 모듈(M10 관람객 AI 도우미·M16 BI·§5B 공통 AI 보조)이 동일 규약을 따르게 한다. +> **보존·경계**: §5B 공통 레이어·§8 확정 스택·§8-2 테넌트 격리·§6 나노바나나(이미지 생성은 별개 파이프라인·본 절의 "토큰"은 **텍스트 LLM** 대상)를 삭제·재작성하지 않는다. AI 게이트(외부 API 금지, `api.anthropic.com` 예외 — §10)·온프레미스 소형모델 RAM 제약([[project_ollama_ram_constraint]])과 정합한다. + +### 8A-1. AI 사용성 표준 — "어디서나 한 번에 물어본다" + +전 화면에 **동일한 AI 진입 규약**을 심어, 사용자가 메뉴를 뒤지지 않고 자연어로 즉시 도움을 받게 한다. 관람객(visitor 메인 AI 도우미)과 업무 사용자(업무 화면 AI 보조)가 **같은 컴포넌트·같은 로직**을 공유한다. + +| # | 사용성 요소 | 내용 | 적용 범위 | +|---|---|---|---| +| U1 | **인라인 AI 진입점** | 전 화면 공통 위치(헤더/우하단)에 "AI에게 물어보기" 버튼 + 자연어 질문창(공통 컴포넌트 `AiAssistant`). 화면 컨텍스트(현재 행사·부스·화면 ID)를 자동 첨부 | 웹·모바일 전 화면 | +| U2 | **예시 질문 칩(prompt chips)** | 자주 묻는 질문을 원클릭 칩으로 노출(화면·역할별 큐레이션). 예: 관람객 "오늘 열리는 전시는?"·"주차 어디?"·"부스 어떻게 찾아?" / 참가업체 "내 유틸리티 신청 마감일?"·"이 도면 규정 위반 있나?" | 화면·역할별 | +| U3 | **원탭 AI 액션** | 목록/상세에서 버튼 한 번으로 요약·추천·초안 생성. 예: 서류 요약, 옥션 응찰 비교 요약, EDM 카피 초안(M12), 회의록 액션아이템 추출(§5B meeting) | 목록·상세 화면 | +| U4 | **다음 명령 제시(proactive)** | 결과 하단에 후속 액션·후속 질문 칩 제시("이 배치안으로 시각화 생성?"·"이 업체에 옥션 초대?"). 프로액티브 제안은 **규칙 기반 우선**(LLM 미사용, §8A-2 P1) | 결과 카드 | +| U5 | **구조화 카드 + 근거 인용** | 답변은 자유 서술 대신 **구조화 카드**(핵심값·표·링크) + **근거 인용**(출처 레코드/문서 링크·"근거: 행사마스터 #123"). 근거 없으면 **"모름" 폴백**(환각 차단, GUARDiA AI-trust 정합) | 전 답변 | +| U6 | **대화 히스토리·후속 질문** | 세션 내 멀티턴 히스토리 + 후속 질문 칩. 히스토리는 **요약 압축**해 컨텍스트 재주입 최소화(§8A-2 P4) | 도우미 패널 | +| U7 | **접근성·다국어·모바일·음성** | 동일 로직을 웹·모바일 공유(§2-3 채널 규칙 정합), 다국어(한/영/중/일) UI, 스크린리더 대응, **음성 입력 옵션**(온디바이스 STT 고려·서버 부하·토큰 무관) | 전 채널 | + +- **관람객 vs 업무 사용자 공통화**: 두 페르소나가 **단일 `AiAssistant` 컴포넌트 + 단일 `/ai/ask` 계약**을 공유하고, 노출 위치·예시 칩·허용 액션만 역할/트랙(§2-3)으로 스코프한다 → 구현 중복 회피·UX 일관성. +- **신뢰성 우선**: 사용성(쉽게)은 신뢰성(근거·모름 폴백)과 함께 간다 — "빠르고 그럴듯한 환각"보다 "근거 있는 절제된 답"을 표준으로 한다(U5). + +### 8A-2. 토큰 최소화 설계 원칙 (핵심 설계 원칙 — 비용 효율) + +> **대원칙: "LLM은 최후에 최소로."** 답할 수 있는 것은 DB/규칙/집계로 먼저 답하고, 자연어 종합이 실제 필요한 부분에만, 가장 작은 모델로, 가장 짧은 컨텍스트로 호출한다. 아래 6원칙은 **`/ai/ask` 오케스트레이션의 결정 순서**이기도 하다. + +| 원칙 | 내용 | 계약/구현 지점 | +|---|---|---| +| **P1. 결정론 우선 라우팅** | 의도 분류(키워드·규칙·화면 컨텍스트)로 **LLM 없이 답할 수 있으면 LLM을 호출하지 않는다.** 연/월 일정·교통·주차·마감일·요금·부스 위치·통계 수치 등 **사실 조회형은 DB/뷰가 직접 응답**(카드 렌더). LLM은 **요약·추천·자연어 종합·다중 근거 통합**이 실제 필요할 때만 | `IntentRouter`(규칙 테이블) → `DirectAnswer`(DB) vs `LlmAnswer` 분기 | +| **P2. 소형모델 우선 티어링** | 기본 온프레미스 **소형(Ollama `qwen3:1.7b`/`llama3.2:1b`)** 로 처리 → 난도·실패 시에만 **Claude로 에스컬레이션**(`AiTextRouter` 폴백 체인 역방향 활용: 저비용 우선 → 고비용 승급). 난도 판정 = 컨텍스트 길이·요구 추론 깊이·소형모델 신뢰도 | `AiTextRouter`(기존)·`AiConfig` 티어 정책. RAM 제약([[project_ollama_ram_constraint]]) 정합 | +| **P3. RAG 그라운딩으로 프롬프트 축소** | 크롤 적재/도메인 DB에서 **필요 레코드만 발췌**(top_k 제한·컬럼 프로젝션)해 **짧은 컨텍스트**로 전달. **전체 문서·전체 테이블 주입 금지.** 근거 스니펫만 넣어 프롬프트 길이·환각 동시 억제 | RAG 검색 `top_k`(기본 3~5)·발췌 요약·근거 스니펫 | +| **P4. 캐싱** | ① **응답 캐시**: 동일 의도+동일 파라미터 질의 결과 캐시(TTL, 예 일정·요금 24h) ② **시스템 프롬프트 캐시**(프롬프트 프리픽스 재사용) ③ **동일 기간/스코프 요약 재사용**(M16 BI·기간 요약). 히스토리는 요약본만 재주입 | Redis 응답 캐시(키=의도+파라미터+tenant+locale), 프롬프트캐시 | +| **P5. 출력 상한·구조화** | `max_tokens` 상한 강제, **구조화(JSON/카드) 출력**으로 장문 방지. **스트리밍은 UX 체감용일 뿐 토큰량은 불변**임을 명시(비용 절감 아님) | `max_tokens`·`response_format`(structured), 스트리밍=표시 옵션 | +| **P6. 집계는 SQL로** | 통계·집계·랭킹·추이는 **LLM이 아니라 DB 집계(뷰/데이터마트)** 로 산출. LLM은 그 수치에 대한 **자연어 설명·해석만** 담당(수치 계산에 LLM 금지 — 환각·비용 이중 방지) | M16 BI 데이터마트(§M16-1)·SQL 집계 → LLM은 설명만 | + +**오케스트레이션 흐름(요약)**: `사용자 질문 → IntentRouter(P1) → [사실조회면] DB/뷰 카드 응답(LLM 0토큰) / [종합필요면] RAG 발췌(P3) → 캐시 조회(P4) → 소형모델(P2) → (난도↑) Claude 승급 → max_tokens·구조화 출력(P5) → 근거 인용 카드(U5)`. 통계는 항상 SQL 선처리(P6). + +### 8A-3. 측정지표 및 목표 (비용 가시성) + +> 토큰 최소화는 **측정되어야 관리된다.** 아래 지표를 `ai_usage_log`(질의별 토큰·모델·경로·캐시히트·지연)로 적재하고 M16 BI/관리자 대시보드에 노출한다. 목표치는 초기 가설이며 파일럿 후 보정(근거 없는 확정 금지). + +| 지표 | 정의 | 목표(초기 가설) | +|---|---|---| +| **LLM 우회율(deflection)** | 전 질의 중 P1 결정론/DB로 **LLM 없이** 처리된 비율 | **≥ 40%** (일정·요금·위치·통계형 다수) | +| **소형모델 처리율** | LLM 호출 중 소형(Ollama)로 완결(Claude 미승급) 비율 | **≥ 70%** | +| **캐시 적중률** | 캐시(P4)로 응답한 비율 | **≥ 30%**(반복 질의 화면) | +| **호출당 평균 입력 토큰** | LLM 호출 1건당 평균 프롬프트 토큰(RAG 발췌·히스토리 요약 후) | **≤ 1,500** | +| **호출당 평균 출력 토큰** | `max_tokens` 상한 하 평균 출력 | **≤ 400** | +| **근거 인용률** | LLM 답변 중 근거 링크·"모름" 폴백을 포함한 비율(U5) | **≥ 95%** | + +- **비용 귀속**: `ai_usage_log`는 `tenant_id`(§8-2)·모듈·역할을 태깅해 **테넌트/모듈별 비용 배분**을 가능케 한다(플랫폼 슈퍼관리자 크로스-테넌트 집계). + +### 8A-4. design/개발 에이전트 계약 포인트 + +> planner는 원칙·계약을 확정한다. **화면·컴포넌트 상세는 designer(Stitch 경유), 라우팅·캐시·모델 티어 구현은 backend/ai-dev 후속.** design.md·src 미수정. + +1. **단일 AI 계약** `POST /ai/ask` — 입력: `{ question, contextRef(화면·행사·부스), locale, history(요약) }`, 출력: `{ answerCard(구조화), citations[], followups[], route(direct|small|escalated), usage(tokens·cached) }`. 전 화면·전 채널(웹·모바일)이 이 단일 계약을 사용(U1·U7). +2. **라우팅 계약**: `IntentRouter`는 **규칙 테이블(공통코드)** 로 관리(코드 배포 없이 의도·직답 매핑 추가). 사실조회 의도는 **DB 리졸버 매핑**(일정·요금·위치·통계). 미매핑만 LLM 경로. +3. **캐시 계약**: 캐시 키 = `hash(intent + params + tenant_id + locale)`, TTL은 의도별 정책(공통코드). 무효화 = 원천 데이터 변경 이벤트(§5B notification 버스 재사용). +4. **모델 티어 계약**: `AiConfig`(§5B, 기존 AiTextRouter/AiConfig 패턴)에 **티어 정책**(기본 소형·승급 임계·모델명) 설정형 노출 — 하드코딩 금지, 관리자 조정 가능. 실패 시 폴백(소형↔Claude 상호). +5. **UI 컴포넌트 계약**: 공통 `AiAssistant`(진입점·질문창·칩·카드·히스토리) + `AiActionButton`(원탭 액션). 예시 칩·허용 액션은 **화면/역할 메타데이터**로 주입(designer가 화면별 큐레이션, Stitch 프롬프트에 반영). +6. **모듈 링크**: M10(§5A 관람객 AI 도우미)·M16(§M16-1 BI 자연어 설명)·§5B 공통 AI 보조가 본 절 원칙을 **동일 계약으로** 준수. 나노바나나(§6) 이미지 생성은 본 절 토큰 원칙 대상 아님(별도 RenderJob 쿼터·캐시). + +--- + +## 9. 로드맵 + +### Phase 1 — 설계·시각화 코어 (MVP, ~4개월) + +| 항목 | 내용 | +|---|---| +| 범위 | **§5B 공통/시스템관리 레이어 이식 선행(UIWS: 인증 JWT+OTP·시스템관리·핵심 공통모듈 — 전 모듈 기반)**, M2(단일 홀, 근사 도면), M3(조립부스 전체 + 독립부스 초안 생성), M4(전기·네트워크 배선 + 자동 견적, 신청서·위치표시도 파일 생성까지), M5(S1·S2·S6·S7 샷) | +| 산출물 | 웹 앱(주최자·참가업체·장치업체), 나노바나나 파이프라인 v1, 룰셋 v1(장치 규정·요금표), 근사 홀 도면 1종(홀7 권장 — 규격 공개 충실) | +| 검증 | 파일럿 1개 행사(또는 과거 행사 데이터 재현)로 배치→설계→배선→시각화 전체 여정 시연 | +| 착수 조건 | Gemini API 키, 홀 참조 사진 촬영(샷 프리셋별 배경), 트렌치 좌표(미확보 시 공개 스펙 기반 가정 그리드로 진행하되 '가정' 라벨) | + +### Phase 2 — 워크플로·운영 통합 (~4개월) + +| 항목 | 내용 | +|---|---| +| 범위 | M1(가용성+자동 견적), M6(마일스톤·서식 자동 생성·AI 서류 검수), M7(업체 매칭·RFQ), M9(PG 결제·납부 스케줄), 홀매니저 대시보드, 전 홀(10개) 도면 확장 | +| 산출물 | kxwp 제출 릴레이(파일 생성+안내), 등록업체 DB 수집 파이프라인, 정산 리포트 | +| 전제 | 킨텍스 협의: CAD 도면·트렌치 실측, kxwp 연동 논의 개시, 요금 정합성(인터넷 150,000 vs 80,000) 확인 | + +### Phase 3 — 현장·확장 (~4개월+) + +| 항목 | 내용 | +|---|---| +| 범위 | M8(반입/반출 슬롯·QR 통행증), kxwp 정식 API 연동(협의 성사 시), 정밀 조도 시뮬레이션, 다국어(영·중·일) 규정 챗봇, 관람객 플로어플랜 공개, 회의실·리깅 구조 사전 체크 확장 | +| 산출물 | 현장 모바일 운영 도구, 제3전시장(2028) 대비 홀 마스터 확장 구조 | + +각 Phase 종료 시 reviewer 에이전트 교차 검증(기획-디자인-구현 정합성) — CLAUDE.md 워크플로 준수. + +--- + +## 10. 리스크 및 제약 + +| # | 리스크/제약 | 영향 | 완화 | +|---|---|---|---| +| R1 | **AI 생성 이미지가 실제 시공과 다름** — 재질·색·디테일 오차는 구조적으로 불가피. 참가업체가 이미지를 계약 근거로 오인 시 분쟁 | 높음 | 전 이미지 워터마크·고지(6-5), 계약·심사 서류에서 자동 배제, "시공 기준은 도면" 동의 절차 | +| R2 | **도면 심사 책임 문제** — 자동 검증 통과가 킨텍스/소방 승인을 의미하지 않음. 시스템 통과 후 현장 반려 시 책임 소재 | 높음 | 시스템 역할을 '사전 필터'로 법적 정의, 최종 승인 주체(킨텍스·구조기술사) 명시, 검증 리포트에 면책 문구·룰셋 버전 기록 | +| R3 | **kxwp 연동 불확실성** — 폐쇄형 시스템, API 미공개. 연동 실패 시 이중 입력 부담 | 중간 | Phase 1~2는 '제출 파일 자동 생성+수동 업로드' 릴레이로 독립 가치 확보, 병행하여 킨텍스 IT 협의 | +| R4 | **트렌치·CAD 실측 데이터 미확보** — 배선 자동화 정확도 좌우 | 높음 | 공개 규격 기반 가정 그리드로 개발 진행 + '가정' 라벨, 킨텍스 데이터 제공을 Phase 2 전제조건으로 계약화 | +| R5 | 한글 간판 텍스트 렌더링 불안정(생성 모델 한계) | 중간 | 오탈자 자동 검수 + 실패 시 간판 영역 후처리 합성(6-4) | +| R6 | 이미지 생성 비용·지연 — 부스 수백 개(홀당 200~600부스) 동시 생성 시 비용 급증 | 중간 | 자동 생성은 S1·S7 한정, 온디맨드+캐시, 행사별 생성 쿼터 | +| R7 | 배치 엔진 결과가 주최자 영업 관행(프리미엄 부스 위치 정책 등)과 충돌 | 중간 | 자동안은 '초안', 수동 편집 캔버스 우선. 제약조건을 주최자가 조정 가능하게 | +| R8 | 요금·규정 데이터의 공식성 — 웹 공개값(예: 인터넷 150,000원 vs KT 80,000원 병존)이 실계약가와 다를 수 있음 | 중간 | 견적에 "공시가 기준, 최종가는 킨텍스 확정" 고지, 요율 마스터를 킨텍스 확인본으로 교체하는 절차 마련 | +| R9 | 이해관계 충돌 — 장치업체는 설계 자동화를 일감 위협으로 인식 가능 | 중간 | 포지셔닝을 '초안+검증 도구'로: 반려 감소·컨펌 단축이라는 업체 이득 강조, M7로 수주 채널 제공 | +| R10 | 개인정보·영업비밀 — 참가업체 부스 설계는 경쟁사에 민감 | 중간 | 행사 단위 격리, 부스 데이터 접근은 소유 참가업체+주최자+홀매니저로 한정 | +| R11 | ~~ReRoomAI 파이프라인 분석 미완 — 구조 보존 제어 상세는 소스 분석 후 확정~~ **[해소 v1.1]** | 낮음 | **해소(2026-07-11)**: `reroomai-source.md` 분석 완료 → 6장 모델·SDK·프롬프트 아키텍처·방어 로직 확정(6-4/6-5). BACKLOG B-11 done | +| R12 | **나노바나나(Gemini) 외부 API 미승인** — GUARDiA 외부 API 금지 원칙상 현재 승인 예외는 `api.anthropic.com`뿐이며, Gemini(`generativelanguage.googleapis.com`)는 미승인. kintex는 GUARDiA ITSM(관공서 관제)과 별개 도메인의 독립 저장소(`zio/kintex`)이나, 승인 없이 M5 구현 착수 시 원칙 위반 | 높음 | **M5 파이프라인 구현 착수 전 소유자 승인 확정 선행(게이트)**. 승인 시 `GEMINI_API_KEY`는 서버 env로만 로드(코드·DB·커밋·로그·응답 기록 금지, ReRoomAI (E) 방어 패턴 준수). **미승인 시 완화책**: 온프레미스 이미지 생성(SDXL 등) 폴백 어댑터 검토 — 단 image-to-image 구조보존 품질 재평가 필요 | + +--- + +## 11. 변경 이력 + +| 버전 | 일자 | 작성자 | 내용 | +|---|---|---|---| +| **v3.4** | 2026-07-12 | planner | **AI 사용성 & 토큰 최소화 아키텍처 신설(소유자 지시 2026-07-12).** 기존 스코프·화면·라우트 전부 보존, AI 원칙·계약·지표만 순증. ①헤더 v3.4 라인 + 버전 상향 ②**§8A 신설**(§8-2 뒤·§9 앞) — (8A-1) AI 사용성 표준 U1~U7(인라인 진입점 `AiAssistant`·예시 질문 칩·원탭 AI 액션·다음 명령 제시(규칙 우선)·구조화 카드+근거 인용·"모름" 폴백·대화 히스토리 요약·접근성/다국어/모바일/음성, 관람객·업무 사용자 단일 컴포넌트 공유) (8A-2) 토큰 최소화 6원칙 P1~P6(결정론 우선 라우팅으로 사실조회 LLM 미호출·소형모델 우선 티어링 AiTextRouter 저비용→승급·RAG 발췌 top_k 제한·캐싱 응답/프롬프트/기간요약·max_tokens 상한+구조화 출력(스트리밍=UX용 토큰 불변)·집계는 SQL LLM은 설명만) + 오케스트레이션 흐름 (8A-3) 측정지표·목표(LLM 우회율≥40%·소형모델 처리율≥70%·캐시 적중률≥30%·평균 입력≤1500/출력≤400·근거 인용률≥95%, `ai_usage_log` 적재·tenant/모듈 비용 귀속) (8A-4) design/개발 계약 6종(단일 `/ai/ask`·규칙테이블 IntentRouter·캐시 키·AiConfig 티어·공통 `AiAssistant`/`AiActionButton`·모듈 링크) ③**M10·M16-1·§5B-2에 §8A 정합 링크** 순증(관람객 AI 도우미 DB 직답·BI 집계 SQL/LLM 설명만·공통 AI 보조 중앙 `/ai/ask` 경유). 이미 진행 중(visitor-assistant DB 근거·AiTextRouter 폴백)과 정합·표준화(재발명 아님). 외부 API 게이트·RAM 제약 정합. **src·design.md 미수정** — designer(AiAssistant/칩 Stitch)·backend/ai-dev(라우팅·캐시·티어) 후속 | +| v1.0 | 2026-07-11 | planner | 최초 작성 — kintex-website.md 분석 기반 전체 기획. ReRoomAI 소스 분석(reroomai-source.md)은 추가 시 6장 갱신 예정 | +| v1.1 | 2026-07-11 | planner | ReRoomAI 소스 분석 반영. ①§6 나노바나나 파이프라인 제어 파라미터 확정 — 모델 `gemini-3.1-flash-image-preview`(나노바나나 2)·`@google/genai` SDK·image-to-image(inlineData+text parts) 호출 스택, 구조화 사전(BOOTH_TYPES·BOOTH_STYLES·FIXTURE_LAYERS) + "보존/교체 명시 분리" 부스 프롬프트 템플릿(§6-4), Canvas 1024px 전처리·RenderJob 방어 로직(크기 가드·SAFETY·에러 분기·성공 시에만 쿼터 차감)·단계별 로딩 UX 신설(§6-5). ②S6 배선 오버레이 백엔드 래스터 합성 우선 명확화(§6-3). ③§7 마스터 데이터 순증 반영(기본부스 표준 품목·프리미엄 6×3×4m 2kW·조명 반입 금지·이격 30/60cm·옥외 2,849㎡·홀6 93×60×10m·제3전시장 홀11~18). ④§10 R11 해소, R12(Gemini 외부 API 미승인·소유자 승인 게이트) 추가. BACKLOG B-11 done, B-09 정리 | +| v1.2 | 2026-07-11 | planner | **기술 스택 확정 — React + Spring Boot 3.x(Java 17) + MyBatis + PostgreSQL(PostGIS), 나노바나나 Python 워커 사이드카. GUARDiA 표준 프레임워크 정렬(사용자 지정).** §8 아키텍처 전면 정합화: 백엔드 FastAPI→Spring Boot 3.x + MyBatis(REST + WebSocket/STOMP, 룰·배치/배선 엔진=서비스 계층 + PostGIS 공간 SQL), 프론트 Next.js→React 18/19(Vite·TS, SVG/WebGL 캔버스), 비동기 큐 Redis 유지 + 이미지 생성은 별도 **Python 워커 사이드카(`tools/nanobanana`, google-genai Python SDK)** 로 분리(Spring이 RenderJob 큐잉→Python 워커 소비·생성→오브젝트 스토리지 적재→WebSocket 완료 푸시, 서류·알림도 동일 큐). Python 워커 유지 근거 명시(ReRoomAI 검증 client.py·Python SDK — Java 재구현 회피). 인증(행사 단위 RBAC+JWT)·오브젝트 스토리지 유지. §8 mermaid 갱신. **기능 범위(M1~M9)·우선순위·나노바나나 파이프라인 로직 불변** — 스택 표기 정합화만 수행 | +| **v2.0** | 2026-07-11 | planner | **정체성 확장 — 킨텍스 자동전시시스템(Exhibition Automation Platform).** 글로벌 전시테크 크롤링(Eventleaf·VenueSight·Whova·ExpoPlatform·Eventbase·Pointr·Swapcard·Brella·Grip·RainFocus·ExhibitForce·FindRFP·Procore·4castplus) 근거로 확장. ①§1 비전 재정의(생애주기 폐루프, M15 옥션이 코어를 발주로 연결) ②§2 역할·포털 매트릭스 신설 — 6역할(주최자·참가·업체·홀매니저·관리자·관람객/대중) 웹/모바일 분리(organizer·exhibitor·contractor·ops·admin·public+visitor), 관리자·일반대중 페르소나 추가 ③§4 모듈맵 mermaid 확장(M10~M18) + 우선순위 총괄 ④§5A 신규 모듈 상세: **M15 공사/장치 옥션(P1·핵심, 역경매·견적서(Quotation)=응찰·실시간 순위·종합평가 낙찰·등록업체만 응찰·Auction 1─N Quotation ─ Award·PDF/버전, 입찰 플로우 시퀀스 다이어그램)**, M10 관람객 등록·배지·리드캡처(P1), M12 마케팅·EDM·공개 홍보 사이트(P1·SEO/다국어), M16 경영분석 BI(P2→**P1 승격**, design.md 반영은 designer 후속), M17 CMS(P1), M18 관리자 백오피스(P1), M11 비즈매칭·M13 wayfinding·M14 현장운영(P2) ⑤**M2·M3 3안 생성→선택/병합 UX 구체화**(1·2·3안 다양화, 구역/블록 병합, 병합 후 규정 재검증, 버전 기록) ⑥§7-3 엔티티 확장(Auction/Quotation/Award·Visitor/Badge/Lead·KPI/Content/User) ⑦§8-1 아키텍처 보강(역할별 분리 프론트+SSO/RBAC+공개사이트 SEO/다국어+백오피스+옥션 엔진) ⑧**§5B 공통/시스템관리 레이어(UIWS 표준 이식) 신설** — kintex 스택=UIWS(GUARDiA 표준 프레임워크) 동일 → 시스템관리(사용자·RBAC·공통코드·메뉴·감사로그·시스템설정)와 공통 업무기능(worklog·schedule·message·stats·notice·opinion·search·meeting·report·notification·audit) + 인증(JWT + **2차 인증 OTP TOTP RFC6238** + 로그인 실패 잠금 + admin 비번 env `ADMIN_PASSWORD_ENC` 주입)을 `workspace/uiws` 레퍼런스로 이식, 도메인 모듈은 그 위에 적재. **M18 관리자 시스템을 UIWS 시스템관리와 통합(중복 제거)**, BI/CMS/알림 경계 규칙 정의, Phase 1 선행 기반으로 로드맵 반영. ⑨**§5A M16-1 운영사(킨텍스·venue operator) 관점 수익성/ROI 소절 신설** — 참가업체 관점 ROI(리드 기반)와 명시 구분하고, 킨텍스 관점 7지표(홀·기간별 가동률/매출구성/행사별 P&L·마진/전시장별 ROI·RevPAD·㎡당 수익/참가사 리텐션·LTV/수요예측·수율·가격 최적화/경영진 KPI) + 데이터원(M1·M4·M9·M10·M15) + **BI 데이터마트(스타 스키마 Fact/Dim, DA 후속 트랙)** 정의. **기존 M2~M5 P0 코어·§6 나노바나나 로직·§8 확정 스택 보존.** design.md/타 문서는 미수정 — designer/planner/DA 후속 반영 필요로 표기 | +| **v3.0** | 2026-07-11 | planner | **멀티테넌시(다중 전시관 SaaS) 확장 — 킨텍스 전용 → 다중 전시관, KINTEX=기준 테넌트 #1.** 기존 스코프(부스 코어 M2~M5·도메인 M10~M18·§5B 공통 레이어·§6 나노바나나·§8 확정 스택) **전부 보존**, 격리 레이어만 순증. ①헤더 v3.0 정체성 확장(다중 전시관 SaaS) ②**§1A 멀티테넌시 절 신설** — 테넌트=전시관(Venue) 모델(tenant_code·명칭·branding·domain/subdomain·active·locale, 홀·요율·규정 룰셋·부스표준을 테넌트 소유로 재정의)·`tenant_id` 전파 및 격리(전 도메인 엔티티 격리 vs 전역/테넌트 참조 구분)·테넌트 컨텍스트 해소(서브도메인 kintex/coex.wise.ai.kr 우선 + 사용자 소속 보조, fail-closed 주입)·역할 계층(플랫폼 슈퍼관리자 vs 테넌트 관리자 2계층, 행사 RBAC는 테넌트 내부 스코프)·마이그레이션(기존 데이터 tenant_id=1 백필, DDL은 db-engineer/DA 후속) ③**§2 역할 갱신** — 페르소나 관리자 행을 테넌트 관리자로 재정의 + 플랫폼 슈퍼관리자 신규, 권한 모델을 "테넌트 격리 ⊃ 행사 RBAC" 3중 구조로, §2-1 포털 매트릭스 admin 2계층 분리 ④**§7 데이터모델 갱신** — §7-1 마스터데이터 테넌트 스코프 재정의(킨텍스 실측=테넌트#1 시드), §7-3 Tenant/Venue 엔티티·tenant_id 전파·참조 구분·역할 계층·백필 추가 ⑤**§8-2 멀티테넌트 격리 전략 신설** — 공유 스키마 + tenant_id 컬럼(단일 kintex_db 유지·DB/스키마 분리 미채택, 비교표)·fail-closed 다층 강제(필터→서비스가드→MyBatis 공통 인터셉터→PostGIS)·성능(`(tenant_id,…)` 선두 인덱스)·보안(교차 차단·감사·스토리지/쿼터 격리)·온보딩 6단(코드 배포 없이 데이터 온보딩) ⑥§1 Non-Goal에 온보딩 범위 한정 추가. **design.md·architecture/*.md·src 미수정** — db-engineer/DA/designer 후속 반영 필요로 표기. 근거 없는 코엑스 실측 추정 배제(온보딩 시 입력) | +| **v3.3** | 2026-07-12 | planner | **사용자 구분 → 랜딩(메인페이지)·메뉴/탭 그룹 결정 규칙 확정 — 웹+모바일 공통(소유자 확정 2026-07-12).** 기존 스코프(§2 6역할·§2-2 3-트랙·§2-1 포털·화면 SCR-*·딥 라우트) 전부 보존, 결정 로직·트랙 메인 목록만 순증(안 B). ①헤더 v3.3 규칙 요약 라인 + 버전 상향 ②**§2-3 신설** — (2-3-1) 역할→트랙 매핑 확정표(visitor/business/agency/내부-ops/내부-admin, 판정 신호=EventRole `myRole`+globalRole `role_code`, 웹 셸·모바일 앱 타깃) (2-3-2) primaryTrack 우선순위(내부-admin>내부-ops>business>agency>visitor)·activeTrack 반응형(기존 행사 전환 재사용)·멀티역할 연속성 (2-3-3) 랜딩 결정표 **(A)웹**(미인증=SCR-T0 공개 관람 랜딩, 인증=역할별 전용 메인, completeLogin 분기·현행 `/home` 고정 교체) **(B)모바일**(동일 로직·역할별 홈 탭 스위칭) (2-3-4) 웹 AppShell `GROUPS` 트랙별 노출 매트릭스(●/◐/✕, `visibleGroups` 트랙 필터 확장) (2-3-5) **모바일 하단 탭바 역할별 매트릭스** (2-3-6) **신규 트랙 메인 화면 목록·스펙 7종**(웹 SCR-T0 공개랜딩·T1 관람객·T2 비즈니스(역할변형)·T3 에이전시 + 모바일 관람객/비즈니스/에이전시 홈 — designer Stitch 의뢰 대상, 관리 메인=SCR-16 재사용) (2-3-7) 구현 권고·담당(웹=frontend·모바일=kintex-mobile, 지시서 `_workspace/plan_role_routing.md`). §2-2-3(C) "트랙-스코프 홈" 권고를 소유자 확정으로 정밀화(기존 홈 재사용→전용 신규 메인이 기존 위젯 조합). **src·design.md 미수정** — frontend/kintex-mobile/designer 후속 반영 필요 | +| **v3.2** | 2026-07-12 | planner | **제품 명칭 확정 + 대외 접점 3-트랙 재구성(소유자 확정 2026-07-12).** 기존 스코프(M1~M18·§1A 멀티테넌시·§2 6역할/7페르소나·§2-1 포털 매트릭스·§5B 공통레이어·§6 나노바나나·§8 아키텍처·design.md SCR-*) **전부 보존**, IA 레이어만 순증. ①**제품 공식 명칭 = "KINTEX AI 전시·행사시스템"**(기존 "자동전시시스템/Exhibition Automation Platform" 대체 — 전시+행사/이벤트 포괄) → H1 제목·헤더 명칭 절 갱신, 정본 선언(기존 표기는 문맥 보존상 잔존) ②**`docs/analysis/coex-website.md` 신설** — 코엑스 3-사이트 IA(VISITOR `coex.co.kr`/BUSINESS `business.coex.co.kr`/CYBER 참가신청 `cybercoex.co.kr`) 분석 + 킨텍스(kintex.com) 대비표 11축 + 차용 요소. WebFetch 3사이트 + WebSearch 보조 ③**§2-2 대외 접점 3-트랙 재구성 신설** — visitor(관람객)/business(주최자·참가업체)/agency(공사·장치·협력사) 3-트랙 정의(대상·여정·진입화면·기능 매핑), 코엑스 차용요소, 공개사이트 구조(관문 랜딩 3-분기 + 트랙별 서브홈 3 + **로그인 후 트랙-스코프 홈 권고**), **라우트 체계 3안 비교→하이브리드(트랙 셸 + 기존 딥라우트 유지, 마이그레이션 비용 최소) 권고**, 기존 SCR/라우트→트랙 재배치 매핑표(신규 화면 4종=관문+서브홈3만, 나머지 재사용). 트랙은 역할의 상위 묶음(대체 아님), 내부역할 ops·admin은 트랙 외부 유지. 헤더 v3.2 정체성 라인 추가. **design.md·src 미수정(designer/frontend 후속)** — 구현 지시서 `_workspace/plan_3track.md` 별도 작성 | +| **v3.1** | 2026-07-11 | planner | **계정 통합 + 가입 트랙 분리 · 모바일 2타깃 확정(소유자 확정 2026-07-11).** 기존 스코프 전부 보존, 계정·앱 채널 전략만 정밀화(상충 시 확정안 우선·삭제 없이 개정 표기). ①**§2-1 채널 매트릭스 개정** — 모바일 열을 운영 앱(B2B)/관람객 앱(B2C)으로 분리, 가입 트랙 열 신설(업무=승인·초대+2FA 필수 vs 관람객=간편가입/게스트 예매+2FA 미강제) ②**§2-1-1 신설** — (A)계정 체계 단일 통합+가입 트랙 분리(승격 시 단일 계정 등급 상향으로 리드·비즈매칭·재방문 이력 연속성 유지), (B)모바일 코드베이스 1개(Expo `mobile/`)·배포 타깃 2개(운영 앱=스토어 미공개 사내 QR/APK, 관람객 앱=스토어 공개), 관람객 1차 접점=공개 웹(SCR-P7/P8)·앱=리텐션 채널 ③**§5B-3 인증 정밀화** — 2FA 대상을 "업무 사용자 필수·관람객 미강제"로, 승격 시 2FA 필수 전환 명시 ④**M10 갱신** — 간편가입/게스트 예매(SCR-P7)·계정 승격 연속성·게스트 예매 개인정보/병합 정책 반영. 근거: `docs/analysis/ticketing-app-benchmark.md`(게스트 예매·간편가입 업계 표준). design.md·타 문서 미수정(designer 후속 반영 필요), 시크릿 미기재 | diff --git a/plugins/zio-harness/knowledge/kintex/docs/README.md b/plugins/zio-harness/knowledge/kintex/docs/README.md new file mode 100644 index 0000000..973eae7 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/README.md @@ -0,0 +1,75 @@ +# 킨텍스 자동전시시스템 — 문서 인덱스 (문서 지도) + +> **WISE(UIWS) 참조** — 본 문서 세트는 GUARDiA 표준 프레임워크 정본 `workspace/uiws`(UIMS/WISE)의 개발 문서 구성을 레퍼런스로 킨텍스에 맞게 구성했다. +> 목적: 처음 합류하는 개발자가 "어떤 문서가 무엇을 담는지" 한눈에 파악하고, 중복 없이 정본 문서로 이동하게 한다. + +--- + +## 1. 프로젝트 한 줄 요약 + +킨텍스(한국국제전시장) 전시 운영 전 과정 — **부스 배치 → 부스/장치 설계 → 유틸리티 배선 → 나노바나나(Gemini) 시공 후 사진 시각화 → 공사 옥션 → 관람객·경영분석·공개사이트** — 을 AI로 자동화하는 **자동전시시스템(Exhibition Automation Platform)**. + +- 스택: React(Vite·TS) + Spring Boot 3.x(Java 17)·MyBatis + PostgreSQL(PostGIS) + Redis + 나노바나나 Python 워커 +- 패키지: `com.zioinfo.kintex` · DB: `kintex_db` +- AI: Claude 기본 + 설정형 프로바이더 전환(`AiTextRouter`/`AiConfig`) — GUARDiA 표준 프레임워크 준수 +- 공통 레이어(인증 2FA·시스템관리·업무기능) 레퍼런스: **WISE(UIWS)** `workspace/uiws` + +--- + +## 2. 문서 지도 + +### 2-1. 기획·설계 (정본 — 해당 에이전트 경유로만 수정) + +| 문서 | 담는 내용 | 수정 경로 | +|------|-----------|-----------| +| [`PLANNING.md`](PLANNING.md) | 시스템 기획서 v2.0 — 배경·역할/페르소나·모듈(M1~M18)·역할별 포털 분리·아키텍처 개요·나노바나나 파이프라인·리스크(R1~R12) | `planner` 에이전트 | +| [`design.md`](design.md) | UI 디자인 스펙 v1.1 — 화면(SCR-*) Stitch 프롬프트·화면 흐름·컴포넌트 | `designer` 에이전트 | +| [`IMPLEMENTATION_BACKLOG.md`](IMPLEMENTATION_BACKLOG.md) | 구현 백로그 v2.0 — Phase A~E, 모듈별 작업·담당 에이전트·완료 기준·선행 게이트(G1/G2) | `kintex-impl-orchestrator` | +| [`BACKLOG.md`](BACKLOG.md) | 검증(reviewer) 지적사항 티켓 목록 | `reviewer` 에이전트 | +| `architecture/` (Phase A 예정) | 애플리케이션·시스템·기술·데이터·네트워크 아키텍처 — **kintex-aa/sa/ta/da/na 산출 예정** | 아키텍트 팀 (Phase A) | + +### 2-2. 개발·온보딩·표준 (본 세트 — WISE 참조로 신규 작성) + +| 문서 | 담는 내용 | +|------|-----------| +| [`README.md`](README.md) | (이 문서) 문서 인덱스·문서 지도 | +| [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md) | 개발 표준 — 패키지/레이어·코딩 규약·인증(JWT+2FA/OTP)·보안 불변·브랜치/커밋(conventional)·테스트·PR | +| [`ENV_SETUP.md`](ENV_SETUP.md) | 개발환경 구축 — JDK17·Node·PostgreSQL+PostGIS·Redis·Python 워커 설치·실행·환경변수 목록 | +| [`COMMON_CODES.md`](COMMON_CODES.md) | 공통코드 정의 — WISE 공통코드 체계 + 킨텍스 도메인 코드(역할·부스타입·상태·규정 심각도·옥션 상태 등) | +| [`API_GUIDE.md`](API_GUIDE.md) | API 규약 — 경로·응답 봉투·오류 코드·인증 헤더·RBAC. 상세 계약은 백엔드 계약서 링크 | +| [`BUILD_DEPLOY.md`](BUILD_DEPLOY.md) | 빌드/실행 개요 — gradlew·vite·나노바나나 워커·단일 산출물. 상세 CI/CD는 Phase E devops | + +### 2-3. API·워커 계약 (정본 — 경계면 단일 진실원천) + +| 문서 | 담는 내용 | +|------|-----------| +| [`../_workspace/01_backend_contracts.md`](../_workspace/01_backend_contracts.md) | P0 백엔드 API 계약 — 인증·M2~M5 엔드포인트·응답 shape·오류 코드·DB 매퍼 인수 목록 (frontend·db·qa 대조용) | +| [`../tools/nanobanana/_workspace/01_worker_contract.md`](../tools/nanobanana/_workspace/01_worker_contract.md) | 나노바나나 워커 계약 — RenderJob 큐·scene 스키마·콜백 | + +### 2-4. 리서치·자산 + +| 위치 | 담는 내용 | +|------|-----------| +| [`analysis/kintex-website.md`](analysis/kintex-website.md) | kintex.com 전 페이지 + 주최자/참가업체 매뉴얼 분석 | +| [`analysis/reroomai-source.md`](analysis/reroomai-source.md) | ReRoomAI 소스 분석(나노바나나 image-to-image 패턴) | +| [`assets/floorplans/`](assets/floorplans/) | 홀별 평면도 JPG 15장 + CAD(트렌치 DWG, gitignore·로컬 보존) | + +### 2-5. 하네스 + +| 위치 | 담는 내용 | +|------|-----------| +| [`../CLAUDE.md`](../CLAUDE.md) | 프로젝트 마스터 컨텍스트 — 규칙·에이전트 워크플로·하네스 이력 | +| `../.claude/agents/` | 전문 에이전트 17종(아키텍트·공통·코어·도메인·AI·QA·devops) + 범용(planner·designer·developer·visualizer·reviewer) | +| `../.claude/skills/` | 스킬(kintex-impl-orchestrator·nanobanana-visualize) | + +--- + +## 3. 신규 개발자 시작 순서 (권장) + +1. 이 문서로 문서 지도 파악 → [`../CLAUDE.md`](../CLAUDE.md) 규칙 숙지 +2. [`ENV_SETUP.md`](ENV_SETUP.md) — 로컬 개발환경 구축(JDK17·Node·PostGIS·Redis·Python 워커) +3. [`PLANNING.md`](PLANNING.md) §1~2(배경·역할) + [`design.md`](design.md)(화면) 로 도메인 이해 +4. [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md) + [`API_GUIDE.md`](API_GUIDE.md) + [`COMMON_CODES.md`](COMMON_CODES.md) 로 개발 표준 습득 +5. [`IMPLEMENTATION_BACKLOG.md`](IMPLEMENTATION_BACKLOG.md) 에서 자기 Phase/모듈 확인 후 착수 (Phase A 아키텍처 → B 공통 → C 코어 → D 도메인 → E 배포) + +> **중복 회피 원칙**: 기획·화면·모듈 정의는 PLANNING/design/BACKLOG가 정본이다. 본 개발 문서 세트는 그 내용을 **재서술하지 않고 링크·요약**만 한다. 아키텍처(app/system/tech/data/network)는 Phase A 아키텍트 산출물(`architecture/`)이 정본이며 본 세트에서 생성하지 않는다. diff --git a/plugins/zio-harness/knowledge/kintex/docs/RFP_나라장터_제안요청서.md b/plugins/zio-harness/knowledge/kintex/docs/RFP_나라장터_제안요청서.md new file mode 100644 index 0000000..a2f6c46 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/RFP_나라장터_제안요청서.md @@ -0,0 +1,475 @@ +# 제안요청서 (RFP) + +# 킨텍스 AI 기반 전시운영 자동화 플랫폼 구축 + +> **나라장터(국가종합전자조달, g2b) 공고용 제안요청서** +> 발주기관: (주)킨텍스(KINTEX, 한국국제전시장) *(가정)* +> 작성일: 2026-07-12 · 문서번호: KINTEX-RFP-2026-○○○ *(가안)* +> 근거 문서: `docs/PLANNING.md` v3.1(시스템 기획서), `docs/IMPLEMENTATION_BACKLOG.md` v2.0(구현 백로그) +> ※ 본 문서에서 "(가안)" 표기 항목은 공고 시 확정한다. + +--- + +## 목차 + +1. 사업 개요 +2. 현황 및 문제점 +3. 사업 범위 (요구사항 총괄) + - 3.1 기능 요구사항 (SFR) + - 3.2 성능 요구사항 (PER) + - 3.3 시스템 장비구성 요구사항 (ECR) + - 3.4 인터페이스 요구사항 (SIR) + - 3.5 데이터 요구사항 (DAR) + - 3.6 테스트 요구사항 (TER) + - 3.7 품질 요구사항 (QUR) + - 3.8 보안 요구사항 (SER) + - 3.9 제약사항 (COR) + - 3.10 프로젝트 관리 요구사항 (PMR) + - 3.11 프로젝트 지원 요구사항 (PSR) +4. 제안서 작성 요령 및 목차 지정 +5. 평가 기준 +6. 계약 조건 및 일정 +7. 보안·준수사항 +8. 첨부 양식 목록 + +--- + +# 1. 사업 개요 + +## 1.1 사업명 + +**킨텍스 AI 기반 전시운영 자동화 플랫폼 구축** +(영문: KINTEX Exhibition Automation Platform) + +## 1.2 추진 배경 + +- 킨텍스는 총 전시면적 108,011㎡(국내 최대, 2028년 제3전시장 완공 시 178,000㎡)를 운영하나, 전시 준비 실무는 **HWP 서식 다운로드 → 이메일/방문 제출**, **CAD 수작업 배치도 → 홀매니저 육안 검수**, **수기 위치표시도 기반 유틸리티 신청**에 머물러 있음. +- 온라인 작업신고 시스템(kxwp)이 존재하나 로그인 기반 서류 업로드 창구 수준이며, 참가업체 유틸리티 신청은 킨텍스 공통 플랫폼 없이 전시회별 주최자 사무국 시스템에 파편화되어 있음. +- 배치도·도면·위치표시도 등 공간 데이터가 이미지/수기로만 유통되어 자동 검증·시각화·정산·분석의 원천 데이터가 부재함. +- 독립부스 시공은 킨텍스 등록 장치업체(14개 분류 × 739개) 시공이 필수이나, 업체 리스트/엑셀 다운로드 수준으로 견적 비교·경쟁 유도 수단이 없어 업체 선정이 불투명함. +- 관람객 등록·배지·리드 데이터가 행사별 주최자 사무국에 파편화되어 경영분석·재방문 유치에 활용되지 못함. + +## 1.3 사업 목적 + +- 전시장 운영 전 과정(홀 배정 → 부스 배치 → 장치공사 설계 → 전기/조명·네트워크 배선 → 발주 → 반입/반출 → 관람 → 정산·분석)을 **AI 기반으로 자동 설계·검증·시각화**하는 통합 플랫폼 구축. +- **생성형 AI 이미지 파이프라인**으로 시공 전에 "공사 후 결과 사진" 수준의 시각화를 제공하여, 도면을 읽지 못하는 주최자·참가업체도 의사결정 가능하게 함 ("신청서를 내는 순간, 시공 후 사진을 먼저 본다"). +- AI 설계 산출물(배치도·설계안·물량서·시공 예상 이미지)을 근거로 등록업체가 견적서로 응찰하는 **공사/장치 역경매(옥션)** 를 도입, 시공 발주의 가격 최적화·투명화 실현. +- 관람객 등록·배지·체크인·리드캡처와 경영분석(BI)까지 단일 데이터·계정 체계로 통합, "설계→시각화→발주→시공→운영→분석" 폐루프 완성. + +## 1.4 사업 기간 + +- **계약일로부터 12개월** (가안) +- 무상 하자보수: 검사 완료(최종 인수) 후 **12개월** 별도 + +## 1.5 사업 예산 + +- **금 ○○억 원 (부가세 포함)** (가안) +- ※ **예산 미정 — 공고 시 확정**. 제안 가격은 부가세 포함 총액으로 제출. + +## 1.6 발주기관 및 계약 방식 + +| 구분 | 내용 | +|---|---| +| 발주기관 | (주)킨텍스 *(가정)* | +| 입찰 방식 | 일반경쟁입찰, **협상에 의한 계약** (국가계약법 시행령 제43조 준용) | +| 공고 매체 | 나라장터(g2b.go.kr) *(가안)* | +| 계약 형태 | 총액 확정 계약 | + +--- + +# 2. 현황 및 문제점 + +## 2.1 현행 업무 프로세스 (As-Is) + +| 시점 | 현행 프로세스 | 매체 | 문제점 | +|---|---|---|---| +| D-150 ~ | 전시홀 배정신청서 제출 → 배정협의 → 견적 | HWP 양식, 방문/이메일 | 가용성 실시간 조회 불가, 견적 회신 수일 소요 | +| 계약 | 계약금 20% → 중도금 50% → 잔금 30% + 예치금 15~20% | 공문+계약서 | 납부 일정 수동 관리 | +| D-30 | 홀매니저 사전업무협의(장치·홍보·보안) | 대면/유선 | 협의 이력 비정형, 담당자 의존 | +| D-25 내외 | 참가업체 유틸리티 신청 마감(전기·인터넷·급배수 등) | 행사별 주최자 사무국 시스템 | 행사마다 신청 채널 상이, 누락 빈발, 위치표시도 수기 작도 | +| D-7 | 신고서류 7종+ 일괄 제출(운영계획서·부스배치도·재해대처계획서 등) | kxwp 업로드 | 마감 집중, 육안 검수 병목 | +| 행사 중 | 반입/반출 화물차 순번제·현장 대기열 | 현장 통제 | 슬롯 예약 체계 부재 | +| 행사 후 | 전기사용료·폐기물비 등 예치금 정산 | 세금계산서 | 정산 근거 불투명 | + +## 2.2 주요 문제점 요약 + +1. **수작업 부스 배치·견적**: 배치도 CAD 수작업 수일~수주, 견적 회신 수일. 규정(부스 높이 5m, 리깅 6.5~8.5m, 홀별 바닥하중 2~5t/㎡, 방염 등)이 수치로 명확함에도 검증은 육안. +2. **서류 반복 작성**: D-7 신고서류 7종 이상을 HWP로 수기 작성, 마일스톤(D-150/D-30/D-25/D-7) 추적 체계 부재. +3. **업체 선정 불투명**: 등록업체 739개 리스트를 엑셀로 받아 개별 접촉·수기 견적 취합. 동일 사양 기준 견적 비교·경쟁 수단 없음. +4. **시공 결과 사전 확인 불가**: 참가업체는 시공 결과를 개장일에 처음 봄. 조감도는 외주 산출물로 배선·조명 미반영. +5. **관람객 데이터 미활용**: 등록·체크인·리드 데이터가 파편화되어 참가업체 ROI 측정·재방문 유치·경영분석에 활용 불가. +6. **공간 데이터 비구조화**: 배치도·배선·위치표시도가 이미지/수기로 유통되어 자동화의 원천 데이터 부재. + +## 2.3 기대 효과 (To-Be) + +| 항목 | As-Is | To-Be | +|---|---|---| +| 홀 배정 견적 회신 | 수일 | 요율 룰 엔진 기반 즉시 자동 견적 | +| 부스 배치도 초안 | CAD 수작업 수일~수주 | 조건 입력 후 수 분 내 3안 자동 생성·병합 | +| 도면 규정 검수 | 육안 검토 | 위반 자동 플래깅 후 사람 확정 | +| 유틸리티 위치표시도 | 수기 작도 | 좌표 클릭 → 자동 배선안 + 자동 견적 + 위치표시도 자동 생성 | +| 시공 결과 예측 | 불가 | AI 생성 표준 샷 세트(정면/야간/통로/조감 등) 사전 제공 | +| 시공 발주 | 개별 접촉·수기 견적 | AI 자료 기반 역경매 옥션·견적서 비교·낙찰 | + +--- + +# 3. 사업 범위 (요구사항 총괄) + +## 3.0 시스템 개요 및 요구사항 총괄표 + +### 3.0.1 대상 시스템 구성 + +- **역할별 웹 포털 6종**: 주최자 콘솔(organizer) · 참가업체 포털(exhibitor) · 장치/공사업체 포털(contractor) · 킨텍스 운영 대시보드(ops) · 관리자 백오피스(admin) · 공개 홍보 사이트/관람객 웹(public) +- **모바일 앱 2타깃(단일 코드베이스)**: 운영 앱(B2B, 사내 QR/APK 배포) · 관람객 앱(B2C, 스토어 공개) +- **백엔드 공통 플랫폼**: 인증(JWT+2FA OTP)·룰 엔진·배치/배선 엔진(공간 SQL)·옥션 엔진·BI 집계·CMS·비동기 작업 큐·AI 이미지 생성 워커 + +### 3.0.2 요구사항 총괄표 + +| 분류 | 코드 | 건수 | 비고 | +|---|---|---|---| +| 기능 요구사항 | SFR-001 ~ SFR-036 | 36 | 모듈 M1~M18 + 공통 업무기능 + 포털/모바일 + AI 플랫폼 공통 | +| 성능 요구사항 | PER-001 ~ PER-006 | 6 | 동시사용자·응답시간·이미지 생성 큐 | +| 시스템 장비구성 | ECR-001 ~ ECR-004 | 4 | 서버·DB·스토리지·이중화 | +| 인터페이스 요구사항 | SIR-001 ~ SIR-007 | 7 | PG·이미지 생성 API·CAD/JPG·kxwp 등 | +| 데이터 요구사항 | DAR-001 ~ DAR-006 | 6 | 공간데이터·마스터데이터·개인정보 | +| 테스트 요구사항 | TER-001 ~ TER-004 | 4 | 단위·통합·성능·보안 | +| 품질 요구사항 | QUR-001 ~ QUR-004 | 4 | 표준·문서화·유지보수성 | +| 보안 요구사항 | SER-001 ~ SER-008 | 8 | 2FA·RBAC·감사·암호화 | +| 제약사항 | COR-001 ~ COR-006 | 6 | 기술스택·법규·데이터 확보 | +| 프로젝트 관리 | PMR-001 ~ PMR-005 | 5 | 방법론·조직·보고 | +| 프로젝트 지원 | PSR-001 ~ PSR-004 | 4 | 하자보수·교육·이관 | + +--- + +## 3.1 기능 요구사항 (SFR) + +> 우선순위: **P0** = 핵심 차별화(필수·선행) / **P1** = 운영 핵심(필수) / **P2** = 확장(구축 범위 내 기본 기능 구현, 고도화는 협의) + +### 3.1.1 공통/시스템관리 기능군 (전 모듈 선행 기반) + +| ID | 요구사항 명칭 | 상세 내용 | 우선순위 | +|---|---|---|---| +| SFR-001 | 통합 인증 (JWT + 2차 인증 OTP) | 단일 SSO(JWT) 기반 통합 로그인. **2차 인증 OTP(TOTP, RFC 6238: SHA1·30초·6자리·±1윈도우)** — 최초 QR 등록, 로그인 2단계(비밀번호→OTP), 마이페이지 재설정/해제, 관리자 OTP 초기화. 업무 사용자(주최자·참가업체·공사업체·직원·관리자) 2FA **필수**, 일반 관람객 미강제(선택). 로그인 실패 잠금 + 관리자 해제. 관리자(admin) 초기 비밀번호는 환경변수 암호화 주입(하드코딩 시드 금지) | P1 | +| SFR-002 | 역할 기반 권한 관리 (RBAC) | 6역할(주최자·참가업체·장치/공사업체·홀매니저/운영·관리자·관람객/일반대중) + **행사(Event) 단위 워크스페이스 RBAC** 이중 평가. 주최자=행사 owner, 참가업체=부스 단위 멤버, 업체=초대(등록업체 검증), 홀매니저=행사 전체 열람/승인. 역할·메뉴·API 단위 권한 게이트 | P1 | +| SFR-003 | 회원가입·계정 체계 | **단일 통합 계정 + 가입 트랙 분리**: 업무 트랙(승인/초대 기반 가입 + 2FA 필수) / 관람객 트랙(이메일·소셜 간편가입 + 게스트 예매 허용). 관람객→바이어/참가업체 담당자 **계정 승격 시 단일 계정 등급 상향**(리드·매칭·재방문 이력 연속성 유지, 계정 재생성 없음). 게스트 예매 이력의 사후 가입 병합 | P1 | +| SFR-004 | 시스템관리 (사용자·코드·메뉴) | 사용자 관리(CRUD·상태·소속), 역할/권한 관리, 공통코드 관리(홀·부스유형·공종 14분류·유틸리티 요금코드 등 도메인 코드 포함), 메뉴 관리(역할별 포털 메뉴 트리·권한 매핑), 시스템설정(룰셋 버전·AI 게이트·마감 정책 등) | P1 | +| SFR-005 | 감사로그 | 로그인·승인·**낙찰**·설계 변경·룰셋 개정·리드(개인정보) 접근 등 주요 행위 전수 기록. 행위자·일시·대상·전후 값. 관리자 조회·검색·기간 필터·내보내기 | P1 | +| SFR-006 | 공통 업무기능 — 업무일지·일정 | 업무일지(일일 일지·댓글 — 홀매니저 현장 일지·업체 시공 일지 활용), 일정 관리(개인/부서 캘린더 + **행사 마일스톤(D-150/D-30/D-25/D-7)·옥션 마감·반입 슬롯 통합 뷰**) | P1 | +| SFR-007 | 공통 업무기능 — 쪽지·공지·의견 | 쪽지(주최자↔참가업체↔업체↔홀매니저 행사 내 커뮤니케이션), 공지(게시·팝업, 행사 공지 — CMS 채널과 경계 정합), 의견접수(고객의소리·규정 문의) | P1 | +| SFR-008 | 공통 업무기능 — 통합검색·회의록·업무보고 | 통합검색(행사·부스·업체·문서·콘텐츠 크로스 모듈 검색), 회의록(**회의 음성 녹음 → STT(음성인식) → 회의록 자동 작성 → PDF 출력** — 사전업무협의(D-30) 회의록 자동화 적용), 업무보고·통계(일/주/월/분기/연 기간별 집계 보고서·**PDF 리포트 출력**) | P1 | +| SFR-009 | 공통 업무기능 — 알림센터·마이페이지 | 통합 알림센터(마감 리마인더(D-데이 역산)·낙찰·승인·결제 알림, 웹 실시간 푸시(WebSocket)·모바일 푸시), 마이페이지(프로필·OTP 관리·알림 설정·즐겨찾기·최근 방문 개인화) | P1 | + +### 3.1.2 부스 설계·시각화 코어 기능군 (P0 — 핵심 차별화) + +| ID | 요구사항 명칭 | 상세 내용 | 우선순위 | +|---|---|---|---| +| SFR-010 | M1. 행사·홀 배정 및 자동 견적 | 행사일정 연동 가용성 캘린더에서 홀/반홀 선택 → 룰 엔진 즉시 견적: 기본요율(전시홀 2,250원/㎡·로비 10,000원/㎡·옥외 2,000원/㎡) × 면적 × 일수 × 성수기(+10%)/비수기(-10%) × 1전시장(+10%) + 초과시간 요금 + 관리비 예치금(15~20%). 배정신청서 웹폼 입력 → 킨텍스 제출 서식 자동 생성. 최종 배정 확정은 킨텍스 내부 의사결정(시스템은 신청+가견적까지) | P1 | +| SFR-011 | M2. 플로어플랜 스튜디오 — 부스 배치 자동 생성 | 홀 선택(홀별 실측 규격·바닥하중) + 조건 입력(목표 부스 수·기본/프리미엄 비율·주출입구·무대) → 배치 엔진이 통로 폭·비상구 접근·트렌치 위치를 제약조건으로 **정확히 3안 자동 생성**(제약 충족 솔버+휴리스틱 중심, LLM은 조건 해석 보조). 3안은 서로 다른 최적화 목표(부스 수 최대/동선·가시성/피난·안전) | P0 | +| SFR-012 | M2. 배치안 선택·병합·규정 검증 | ① 한 안 선택 또는 ② 여러 안의 구역/블록을 레이어 토글·드래그로 조합 **병합**. 병합 결과 **규정 검증 자동 재실행**(피난 통로·홀별 바닥하중(2~5t/㎡)·비상구·복층 가능 홀 판정·소방 체크리스트). 최종안 버전 기록(선택/병합 출처 추적), 부스별 좌표·번호 확정 → 참가업체 초대 링크 발급. 수동 편집 캔버스(SVG/WebGL) 제공 | P0 | +| SFR-013 | M3. 부스 설계 스튜디오 | **조립부스**: 옵션(간판 문구·가구·조명) 웹 선택 → 프리뷰 + AI 예상 사진 즉시 생성. **독립부스**: 크기·업종·전시품·예산 입력 → AI가 레이아웃+파라메트릭 구조(벽체·트러스·사인) **3안 생성** → 선택/병합 → 버전 기록. 기존 도면(PDF/이미지) 업로드 시 비전 모델 치수·구조 추출("참고용 검증" 라벨) | P0 | +| SFR-014 | M3. 장치 규정 사전 검증 | 제출 전 자동 플래깅: 부스 높이 5m 이하, 리깅 6.5~8.5m(구조계산서 D-7 필요 플래그), 복층 1/2 이내, 방염 자재 체크리스트, 이격(인접 벽 30cm·천장 60cm), 장내 금지작업(전기톱·용접·페인트) 공정 경고, 조명 반입 금지 규정. 검증 리포트에 룰셋 버전·면책 문구 기록(시스템=사전 필터, 최종 승인=킨텍스·구조기술사) | P0 | +| SFR-015 | M4a. 전기·조명 설계 자동화 | 부스 내 기기 목록(전시장비·조명·PC) 입력 → kW 합산 → 분전반 용량·수량 자동 산출 → 최근접 트렌치→분전반 배선 경로 자동 생성(통로 횡단 최소화) → 요금 자동 견적(1kW 55,000원·분전반 50A 100,000원 등 요금 마스터 기반). 조명은 부스 설계 기반 조도 목표별 배치안 제안 + 야간 점등 예상 이미지 연계. 홀 단위 전력 부하 집계(홀매니저) | P0 | +| SFR-016 | M4b. 네트워크·급배수·압축공기 배선 자동화 | 부스 도면 위 단말 위치 클릭 → 트렌치 최단 배선 자동 산출 → **위치표시도 자동 생성**(수기 작도 폐지) → 견적·신청·마감 리마인더(D-25 역산)를 단일 화면 처리. "현장 추가신청 불가" 항목(인터넷 등) 신청 누락 방지 알림 | P0 | +| SFR-017 | M5. AI 시공 예상 이미지 생성 (생성형 이미지 파이프라인) | M2~M4 구조화 데이터를 씬 스키마로 컴파일 → 참조 이미지(도면/간이 렌더) + 구조화 프롬프트(보존/교체 명시 분리)로 **image-to-image 생성** → "시공 후 사진" 표준 샷 세트: S1 부스 정면·S2 야간 점등·S3 통로 뷰·S4 부스 내부·S5 Before/After 페어·S7 홀 전경(조감). 부스 유형/스타일/조명 레이어 사전(UI 선택값과 프롬프트 단일 출처) 기반 조립. 한글 간판 텍스트 오탈자 자동 검수·실패 시 후처리 합성 | P0 | +| SFR-018 | M5. 배선 오버레이(S6)·비동기 렌더 처리 | S6 배선 오버레이는 생성형이 아닌 **백엔드 래스터 합성**(공간 지오메트리를 전기 적·네트워크 청·급배수 녹으로 정확 오버레이 — 좌표 정확성 보장). 렌더 작업(RenderJob)은 전면 비동기: 큐 발행 → 워커 생성 → 오브젝트 스토리지 적재 → WebSocket 완료 푸시. 단계별 로딩 UX·Before/After 비교 슬라이더. 크기 가드·에러 분기(키/쿼터/세이프티)·**성공 시에만 쿼터 차감**·동일 스키마 해시 캐시·행사별 생성 쿼터 관리 | P0 | +| SFR-019 | M5. AI 이미지 워터마크·고지 (필수 불변) | 모든 생성 이미지에 시각 워터마크("AI 생성 예상 이미지 — 실제 시공 결과와 다를 수 있음") + 메타데이터(생성일·스키마 해시·모델 버전) 임베드. **계약·심사 서류에는 생성 이미지 자동 배제**(도면만 유효). 컨펌 화면 "시공 기준은 도면" 동의 체크 | P0 | + +### 3.1.3 판매·발주·정산 기능군 + +| ID | 요구사항 명칭 | 상세 내용 | 우선순위 | +|---|---|---|---| +| SFR-020 | M6. 서류·마일스톤 워크플로 | 행사 생성 시 D-150(배정)/D-30(사전협의)/D-25(유틸리티)/D-7(신고서류) 마일스톤 자동 생성·역산 알림. 신고서류 7종+(행사운영계획서·부스배치도·재해대처계획서·방화관리 책임서약서·주차관리 신청서·보안요원 배치계획·위험물 반입신고서·리깅 구조계산서)를 웹폼 → HWP/PDF 자동 생성(킨텍스 제출 형식 유지). AI 서류 검수(누락 항목·문서 간 불일치·필수 요소 체크) → 홀매니저 검수 요약 리포트. kxwp 제출은 파일 생성+업로드 안내 릴레이(직접 연동은 SIR-006) | P1 | +| SFR-021 | M7. 등록업체 매칭·검증 | 등록업체 DB(14개 분류 × 739개) 관리·검색·추천(부스 규모·업종·예산·지역 기반). 설계안 첨부 견적요청(RFQ) 복수 발송·비교. **미등록 업체 시공 엄금 규정의 시스템 강제**(미등록 업체 초대·응찰 원천 차단) | P1 | +| SFR-022 | M15. 공사/장치 옥션(역경매) — 자료 열람·응찰 | 참가업체/주최자가 옥션 개설 → 초대(또는 공개)된 **킨텍스 등록업체만** AI 생성 자료 패키지(M2 배치도·M3 설계안·M4 배선/물량서(BOQ)·M5 시공 예상 이미지+사양서) 열람 → **정식 견적서(Quotation) 제출로 응찰**. 견적서 = 라인아이템(공종·자재·수량·단가·금액)·총액·부가세·납기·유효기간·조건·첨부, **PDF 산출·버전 관리**(라운드 내 재응찰 이력 보존) | P1 | +| SFR-023 | M15. 옥션 메커니즘·낙찰 | 옥션 유형 설정형: 기본 **역경매**(라운드/마감 내 재응찰) / 단일 라운드 RFQ / 고정가 비교. 응찰 라운드·마감 타이머·**실시간 순위**(현재 순위·최저가·내 위치, 익명 옵션) WebSocket 노출, 라운드 종료 자동 마감. 낙찰 기준: 최저가 또는 **종합평가**(가격+평판+납기 가중 스코어, 개설 시 설정) — 항목별 비교표 제공. **낙찰(Award)** → 낙찰 견적서의 계약/발주 문서 전환(M6·M9 연동)·시공 일정 연계. 전 낙찰 행위 감사로그 | P1 | +| SFR-024 | M8. 반입/반출 물류 슬롯 | 하역장·화물출입구 슬롯 예약제, 중량물(5t 이상) 우선순위 자동 배치, 통행증 QR 발급, 지게차 사전신청 연동, 철거일 피크 대기열 시뮬레이션 | P2 | +| SFR-025 | M9. 정산·결제 | 납부 스케줄 자동 생성·알림(계약금 20%→중도금→잔금+예치금), 유틸리티 신청 건 PG 온라인 결제(SIR-001), 행사 후 실사용(전기 검침 등) 대비 예치금 정산 내역 투명화, 취소·환불 규정 다구간 수수료 서버 권위 산출 | P1 | + +### 3.1.4 관람객·마케팅 기능군 + +| ID | 요구사항 명칭 | 상세 내용 | 우선순위 | +|---|---|---|---| +| SFR-026 | M10. 관람객 등록·티켓·배지·체크인·리드캡처 | 간편가입(이메일/소셜) 또는 **게스트 예매**(가입 없이 티켓 구매) → 사전등록(관람객/바이어 유형별 폼) → **모바일 배지/QR 발급** → 현장 QR 체크인(즉석 배지 인쇄·오프라인 폴백) → 실시간 입장 집계. 참가업체 **리드캡처**: 운영 앱으로 배지 QR 스캔 → 연락처·관심도 평점·메모 저장 → 팔로업 EDM 연계. 부정입장 방지(디바이스 바인딩/회전 QR)는 고도화 제안 항목 | P1 | +| SFR-027 | M12. 마케팅·EDM·공개 홍보 사이트 | **공개 홍보 사이트**(불특정 다수): 행사 소개·일정·교통·사전등록 유도, **SEO(SSR/정적 생성·메타·사이트맵·구조화 데이터)·다국어(한/영/중/일)·hreflang**, 공개 인터랙티브 플로어플랜. **EDM/마케팅 자동화**: 세그먼트별(사전등록자·과거 관람객·바이어) 캠페인·리마인더·리드 팔로업, 수신동의 관리(정보통신망법 준수), AI 카피 초안·AI 예상샷 활용 | P1 | +| SFR-028 | M11. 비즈니스 매칭 | 관람객/참가업체 프로필·관심 업종·의향 기반 AI 미팅 추천 → 미팅 슬롯 예약·일정 관리 → 부스 위치·길안내 연계. 세션 정원·마감·대기 처리 | P2 | +| SFR-029 | M13. Wayfinding(실내 길안내) | M2 실측 플로어플랜 기반 부스·시설(비상구·화장실) 검색·경로 안내. 초기 **지도 기반 존-레벨 길안내(측위 하드웨어 무의존)** 구현, 정밀 측위(BLE/UWB)는 인프라 협의 시 확장 구조로 설계 | P2 | +| SFR-030 | M14. 현장운영 대시보드 | 홀매니저용: 입장·혼잡 실시간(체크인 데이터), 홀 단위 전력 부하 집계, 주차 점유(외부 연계), 안전 체크(규정 위반 신고·소음·금지작업 플래그), 이상 시 알림 | P2 | + +### 3.1.5 경영·콘텐츠·관리 기능군 + +| ID | 요구사항 명칭 | 상세 내용 | 우선순위 | +|---|---|---|---| +| SFR-031 | M16. 경영분석 BI | **운영사(킨텍스) 관점**: 홀·기간별 가동률(반홀 분할·성수기 구분), 매출 구성(임대+유틸리티+부대), 행사별 P&L·마진, 전시장별 ROI(RevPAD·㎡당 수익), 참가사 리텐션·LTV, 수요예측·수율/가격 시뮬레이션(요율·계수), 경영진 KPI 대시보드(목표 대비·드릴다운·내보내기). **참가업체 관점 ROI**(리드 수·품질·비용 대비 성과)와 대시보드·권한 분리. 집계는 BI 데이터마트(스타 스키마)/스냅샷 배치로 운영 DB 부하 회피 | P1 | +| SFR-032 | M17. CMS(콘텐츠 관리) | 전시 콘텐츠·공지 관리(게시 워크플로: 초안→검수→게시, 버전 관리), **참가업체 마이크로사이트**(부스 소개·제품·AI 예상샷 게시), 다국어(한/영/중/일) 콘텐츠, 배너/프로모션, 디지털 사이니지 연계 콘텐츠 배포(확장 구조) | P1 | +| SFR-033 | M18. 관리자 백오피스 | 웹 전용 별도 앱(admin). 시스템관리(SFR-004~005 통합) + **킨텍스 마스터데이터 관리**: 홀 마스터(규격·하중·트렌치)·요율표·유틸리티 요금·규정 룰셋(**버전 관리** — 연 단위 개정 무중단 반영)·등록업체 DB·표준 단가. **웹 주요 이미지 교체(이미지 슬롯 관리)**: 공개 사이트·포털의 메인 히어로·배너·주요 페이지 이미지를 관리자 화면에서 슬롯 단위로 업로드·교체·미리보기·롤백(개발자 배포 없이 운영자가 이미지 변경) | P1 | +| SFR-034 | 역할별 포털·모바일 앱 | 웹 포털 6종(§3.0.1) — 역할별 번들 분리(최소권한·공격면 축소), 공유 디자인 시스템·컴포넌트·API 계약 상속, 반응형(데스크톱=설계/에디터/대시보드, 모바일 웹=조회/승인). **모바일 앱 단일 크로스플랫폼 코드베이스·2배포 타깃**: ① 운영 앱(B2B — 현장 체크리스트·검수·승인·리드캡처, 스토어 미공개) ② 관람객 앱(B2C — 티켓 지갑·배지/QR·wayfinding·매칭, 스토어 공개). 역할/기능별 진입을 분기하는 **통합 런처 구조**로 구성. 운영 앱은 **관리자 화면 기반 QR 배포 체계**(앱 패키지 업로드 → QR 자동 생성 → 다운로드 랜딩 페이지, 스토어 미경유 사내 배포) 필수. 푸시 알림·오프라인 대비 포함 | P1 | + +### 3.1.6 AI 플랫폼 공통 기능군 + +| ID | 요구사항 명칭 | 상세 내용 | 우선순위 | +|---|---|---|---| +| SFR-035 | 하이브리드 AI 아키텍처 (온프레미스 sLLM + 상용 LLM API) | AI 텍스트 기능(배치 조건 해석·서류 검수·규정 문의 챗봇·EDM 카피 초안 등)은 **상용 LLM API와 온프레미스 sLLM을 병용하는 하이브리드 아키텍처**로 구현: ① 관리자 화면에서 AI 제공자/모델을 설정형으로 전환(무배포 변경) ② 상용 API 장애·쿼터 초과 시 **온프레미스 모델 자동 폴백 체인** ③ 개인정보·영업비밀(부스 설계 등) 포함 요청의 **외부 전송 차단 정책**(민감 데이터는 온프레미스 경로 처리). API 키는 서버 환경변수 관리(SER-005) | P1 | +| SFR-036 | RAG 기반 근거 제시형 AI 응답 (환각 차단) | 규정집·매뉴얼·룰셋·공지 등 내부 문서를 벡터DB에 임베딩·검색(RAG)하여 AI 응답에 **근거 문서·인용 출처를 함께 제시**. 근거 부족 시 임의 생성 대신 **답변 회피(abstain)** 처리로 환각(할루시네이션) 차단. 답변 신뢰도 표시, 사용자 피드백 수집 구조. 규정 문의 챗봇·AI 서류 검수 사유 제시(SFR-020)에 적용 | P1 | + +> **비고(범위 한정)**: ① 임대계약의 법적 전자계약 체결, ② 구조계산서의 구조 안전성 판정 자체(체크·누락 검출까지만), ③ 정밀 측위 하드웨어(비콘) 구축은 본 사업 범위에서 제외한다. 다중 전시관(멀티테넌트) 확장은 **테넌트 격리 가능 구조(데이터 모델·권한 계층)로 설계**하되, 타 전시관 실 온보딩은 본 사업 범위 외(COR-006). + +## 3.2 성능 요구사항 (PER) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| PER-001 | 동시 사용자 | 행사 피크(대형 행사 개장일) 기준 **동시 접속 2,000명 이상**(가안) 무중단 처리. 관람객 사전등록·체크인 피크 **초당 50건 이상**(가안) 처리 | +| PER-002 | 온라인 응답시간 | 일반 조회·트랜잭션 화면 응답 **3초 이내(95percentile)**, 단순 API 1초 이내(가안). 플로어플랜 캔버스 초기 로딩 5초 이내 | +| PER-003 | 배치·배선 엔진 처리 | 부스 배치 3안 생성: 홀당 부스 200~600개 기준 **5분 이내**(가안). 배선 경로 산출·규정 검증: 요청당 10초 이내(가안) | +| PER-004 | AI 이미지 생성 큐 | 렌더 작업은 전면 비동기 큐 처리(동기 대기 금지). 표준 샷 1장 평균 60초 내외 완료(외부 API 지연 제외, 가안), 큐 상태·진행률 실시간 표시. 자동 생성은 핵심 샷(S1·S7) 한정 + 온디맨드, 동일 입력 해시 캐시로 중복 생성 차단, 행사별 쿼터 상한 | +| PER-005 | 가용성 | 서비스 가동률 **99.5% 이상**(계획 정지 제외, 가안). 행사 기간 중 무중단 운영 원칙, 점검은 사전 공지 | +| PER-006 | 확장성 | 사용자·행사 수 증가 대비 수평 확장 가능 구조(무상태 API·큐 기반 워커 증설). 제3전시장(2028, 홀11~18) 홀 마스터 확장을 데이터 등록만으로 수용 | + +## 3.3 시스템 장비구성 요구사항 (ECR) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| ECR-001 | 서버 구성 | 웹/API 서버(WAS)·비동기 워커(이미지 생성·서류·알림)·DB 서버·캐시/큐(Redis)로 계층 분리. 규모 산정 및 구성(온프레미스/클라우드)은 제안사가 PER 요건 충족 근거와 함께 제안(발주기관 인프라 정책과 협의 확정) | +| ECR-002 | DB·공간데이터 | PostgreSQL + **PostGIS 확장**(부스 폴리곤·트렌치 포인트·배선 LineString 공간 연산). 정기 백업(일 단위 이상)·복구 절차 포함 | +| ECR-003 | 오브젝트 스토리지 | 도면·AI 생성 이미지·서식·콘텐츠 파일 적재용 오브젝트 스토리지. 공개 사이트 정적 자원 CDN/캐시 구성 제안 | +| ECR-004 | 이중화·백업 | DB 백업·장애 복구(RTO/RPO 목표 제시), 주요 구성요소 단일 장애점 최소화 방안 제안. HA 구성 수준은 예산 범위 내 제안사 제안 | + +## 3.4 인터페이스 요구사항 (SIR) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| SIR-001 | PG 결제 연동 | 국내 PG(토스페이먼츠 등) 연동 — 카드·계좌이체·간편결제, 유틸리티 신청·티켓 결제, 취소/부분환불, 결제 웹훅 처리, 세금계산서 발행 프로세스 연계(발주기관 재무 프로세스 협의) | +| SIR-002 | 생성형 이미지 API 연동 | 이미지 생성 모델 API(Google Gemini 이미지 생성 모델 — image-to-image, 참조 이미지+지시문) 연동. **별도 워커 프로세스에서만 호출**(백엔드 직접 호출 금지), API 키는 서버 환경변수로만 관리(코드·DB·로그 기재 금지), 쿼터·비용 상한·재시도·에러 분기 처리 | +| SIR-003 | CAD(DWG)/JPG 평면도 입력 | 홀 평면도 입력 포맷 = **CAD(DWG) + JPG**. CAD에서 홀 경계·기둥·비상구·트렌치 그리드 좌표를 추출해 공간 DB에 적재하는 도구/절차 구현. 도면(PDF/이미지) 업로드 비전 추출 포함(SFR-013) | +| SIR-004 | 행사일정 연동 | 킨텍스 행사일정 데이터 수집·연동(공개 캘린더 수집 → 가용성 역산, 내부 데이터 제공 시 정합 교체) | +| SIR-005 | 등록업체 DB 연동 | 킨텍스 등록업체 공개 데이터(14분류×739개) 주기 수집·자체 DB화, 추후 공식 피드 전환 가능 구조 | +| SIR-006 | kxwp 작업신고 릴레이 | 킨텍스 온라인 작업신고(kxwp)는 API 미공개 — 본 사업은 **제출용 파일 자동 생성 + 업로드 안내(수동 릴레이)** 까지 구현. 직접 연동은 발주기관 IT 협의 성사 시 변경 협의 대상 | +| SIR-007 | 나라장터(g2b) 연동 | **해당 없음** — 본 시스템은 나라장터와 시스템 연동을 요구하지 않음(본 문서는 조달 공고용이며, 구축 대상 시스템의 기능 범위에 g2b 연동은 포함되지 않음을 명시) | + +## 3.5 데이터 요구사항 (DAR) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| DAR-001 | 공간 데이터 일원화 (PostGIS) | 부스 폴리곤·트렌치 포인트·배선 경로(LineString)를 PostGIS 지오메트리로 단일 원천 저장. 최단 배선(라우팅)·통로 폭 검증(버퍼)·면적 정산·wayfinding·부하 집계·㎡당 수익 분석이 동일 공간 원천을 재사용 | +| DAR-002 | 마스터데이터 구축 | 홀 마스터(홀1~10 실측 규격·바닥하중·반홀 분할, 제3전시장 확장 구조), 트렌치 그리드(홀별 공급 매트릭스 — 전기·급배수·압축공기·전화·인터넷·가스), 요율표, 유틸리티 요금표, 부스 표준 사양(조립부스 포함 품목·프리미엄 사양), 규정 룰셋(높이·리깅·복층·방염·이격·소음·금지작업), 등록업체 DB. **룰셋·요율은 버전 관리 데이터**로 구축(코드 하드코딩 금지) | +| DAR-003 | 핵심 엔티티 모델 | 행사(Event)–홀배정–부스(Booth)–설계안(DesignPlan, 3안·선택/병합 출처·버전)–유틸리티주문(UtilityOrder)–렌더작업(RenderJob)–문서(Document)–결제(Payment) + 옥션(Auction–Quotation–Award) + 관람(Visitor–Registration–Badge–CheckIn–Lead–Meeting) + 경영(KpiSnapshot·Content·Microsite·MasterData·User·Role·AuditLog). ERD·표준 명명 규칙·데이터 사전 산출 | +| DAR-004 | 개인정보 보호 처리 | 관람객·리드 PII(성명·연락처·이메일)는 **암호화 저장(AES-256-GCM 등)** + 조회 화면 **마스킹** 기본. 수집 최소화·수집/이용 동의·보존기간·파기 정책 구현(게스트 예매는 최소 수집·사후 병합 정책 명시). 리드(개인정보) 접근 전수 감사로그 | +| DAR-005 | 데이터 격리 | 행사 단위 데이터 격리(부스 설계는 소유 참가업체+주최자+홀매니저만 접근 — 참가업체 간 영업비밀 보호). 데이터 모델은 전시관(테넌트) 단위 격리 가능 구조(tenant 식별자 수용)로 설계(COR-006) | +| DAR-006 | BI 데이터마트 | 경영분석은 운영 DB 직조회가 아닌 **스타 스키마 데이터마트**(Fact: 배정·정산·유틸리티·옥션·관람 / Dim: 홀·행사·일자·참가사) + 야간 배치/스냅샷 적재로 설계 | + +## 3.6 테스트 요구사항 (TER) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| TER-001 | 단위·통합 테스트 | 모듈별 단위 테스트 및 모듈 간 통합 테스트(설계→시각화→옥션→정산 폐루프 시나리오 포함). 테스트 계획서·케이스·결과서 산출 | +| TER-002 | 성능 테스트 | PER 요건(동시사용자·응답시간·큐 처리) 충족 검증 부하 테스트. 시나리오·결과 보고서 제출 | +| TER-003 | 시나리오 검증 (파일럿) | 실제(또는 과거) 행사 1건 데이터로 **배치→설계→배선→시각화→옥션→정산 전 여정 시연** 검증. 검수 기준 사전 합의 | +| TER-004 | 보안 테스트 | 웹 취약점 진단(OWASP Top 10 기준), 권한 우회·행사 간 데이터 격리·2FA 우회 여부 점검, 조치 결과 확인 후 검수 | + +## 3.7 품질 요구사항 (QUR) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| QUR-001 | 표준 준수 | 웹 표준·웹 접근성(KWCAG 2.2 — 공개 사이트 우선 적용)·반응형 지원. 브라우저 호환(Chrome·Edge·Safari 최신, 모바일 브라우저) | +| QUR-002 | 문서화 | 요구사항정의서, 화면설계서, ERD/테이블정의서, API 명세서, 시스템 구성도, 운영자/사용자 매뉴얼, 테스트 결과서 등 공공 SW사업 표준 산출물 제출 | +| QUR-003 | 유지보수성 | 계층 분리(프론트/백엔드/워커)·모듈화·코드 컨벤션 준수, 룰셋·요율·이미지 슬롯 등 **운영 변경 항목의 무배포 반영 구조**(관리자 화면 변경) | +| QUR-004 | AI 산출물 품질 관리 | AI 생성물(배치안·설계안·이미지·서류검수)은 전부 "초안/예상" 포지셔닝 — 사람 확정 절차·면책 고지·버전 기록 필수. 생성 이미지 품질 기준(구조 보존·워터마크)·재생성 절차 정의 | + +## 3.8 보안 요구사항 (SER) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| SER-001 | 2차 인증 (2FA OTP) | 업무 사용자 전원 TOTP(RFC 6238) 2차 인증 필수(SFR-001). OTP 시크릿 안전 저장, 관리자 초기화 절차, 로그인 실패 잠금 | +| SER-002 | 접근 통제 (RBAC) | 역할·행사 단위 이중 권한 평가, API 단위 권한 게이트, 관리자 API 역할 검증(`ADMIN` 이상), 최소권한 원칙·역할별 프론트 번들 분리 | +| SER-003 | 감사로그 | 인증·승인·낙찰·설계 변경·룰셋 개정·개인정보 접근 전수 기록(SFR-005), 위·변조 방지 보관, 보존기간 정책 | +| SER-004 | 데이터 암호화 | 개인정보·인증정보 암호화 저장(AES-256-GCM 등), 전송 구간 TLS 적용, 비밀번호 단방향 해시(BCrypt 등). 관리자 초기 비밀번호 환경변수 암호화 주입(하드코딩 금지) | +| SER-005 | 시크릿 관리 | API 키(이미지 생성·PG 등)·DB 접속정보는 서버 환경변수/시크릿 저장소로만 관리 — 소스코드·저장소·로그·화면 노출 금지 | +| SER-006 | 오류 응답 통제 | 스택트레이스·내부 경로·SQL 등 내부 정보 응답 노출 금지 — 오류 ID + 요약 메시지만 반환, 상세는 서버 로그 | +| SER-007 | 개인정보보호 | 개인정보보호법 준수: 수집 최소화·동의·마스킹·파기(DAR-004), 개인정보 처리방침 화면, 정보통신망법 광고성 정보 수신동의(EDM) | +| SER-008 | 세션·입력 보안 | JWT 만료·갱신 정책, CSRF/XSS/SQL Injection 방어, 파일 업로드 검증(확장자·크기·악성코드), 외부 입력값 전수 검증 | + +## 3.9 제약사항 (COR) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| COR-001 | 기술 스택 (지정) | 프론트엔드 **React 18/19 + Vite + TypeScript**, 백엔드 **Spring Boot 3.x(Java 17) + MyBatis, REST + WebSocket(STOMP)**, DB **PostgreSQL + PostGIS**, 비동기 큐 **Redis**, AI 이미지 생성 **Python 워커 사이드카**(백엔드는 큐·상태 관리만 담당), 인증 **행사 단위 RBAC + JWT(+2FA OTP)**. 동등 이상 대안 제시는 가능하나 발주기관 승인 필수 | +| COR-002 | AI 이미지의 법적 지위 | 생성 이미지는 참고용 — 계약·심사 근거 사용 금지(자동 배제), 워터마크·고지 필수(SFR-019). 시스템의 규정 검증은 '사전 필터'로 정의, 최종 승인 주체(킨텍스·소방·구조기술사)를 화면·리포트에 명시 | +| COR-003 | 발주기관 제공 데이터 의존 | 트렌치 실측 좌표·CAD 원본 등 일부 마스터데이터는 발주기관 제공 필수. 미확보 구간은 공개 규격 기반 근사('가정' 라벨 표기)로 개발 진행하고, 실측 데이터 확보 시 교체 절차를 수립(요금·규정 공시가도 동일 — "최종가는 킨텍스 확정" 고지) | +| COR-004 | 외부 시스템 제약 | kxwp는 직접 연동 불가 전제(릴레이 방식, SIR-006). KT 인터넷 개통·주차(iparking)·사이니지 하드웨어 연동은 협의 성사 시 확장 항목 | +| COR-005 | 산출물 언어·형상관리 | 산출 문서는 한국어 작성(코드 식별자·커밋 메시지는 영어 허용). 소스코드는 발주기관 지정 형상관리 저장소에 커밋, 지속적 통합/배포 체계 구성 | +| COR-006 | 확장 구조 (멀티테넌트 대비) | 데이터 모델·권한 계층은 다중 전시관(테넌트) 격리 확장이 가능한 구조(공유 스키마 + 테넌트 식별자 수용, 관리자 2계층 확장 여지)로 설계한다. 단, 타 전시관 실제 온보딩·운영은 본 사업 범위 외 | + +## 3.10 프로젝트 관리 요구사항 (PMR) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| PMR-001 | 수행 방법론·단계 | 단계적 구축: **1단계(~4개월) 공통 레이어(인증·시스템관리) + 설계·시각화 코어(M1~M5 중심) → 2단계(~4개월) 워크플로·옥션·관람객·CMS(M6·M7·M9·M10·M12·M15·M17) → 3단계(~4개월) BI·현장·확장(M8·M11·M13·M14·M16 고도화)·통합 안정화** (가안 — 상세 WBS는 착수 시 확정). 단계별 중간 검수 | +| PMR-002 | 수행 조직 | PM(총괄)·아키텍트(응용/데이터)·백엔드·프론트엔드·AI/데이터·QA·기획/디자인 역할을 포함한 투입 조직·M/M 제시. PM은 유사 사업 경험 보유자 | +| PMR-003 | 일정·진척 관리 | WBS 기반 주간 진척 보고, 월간 운영위원회 보고, 마일스톤·리스크·이슈 관리 대장 운영 | +| PMR-004 | 변경 관리 | 요구사항 추적표(RTM) 운영, 변경요청(CR) 절차·영향 분석·승인 체계. 과업 변경은 발주기관 서면 승인 | +| PMR-005 | 위험 관리 | 핵심 리스크(생성 이미지 오인 분쟁·심사 책임 소재·외부 연동 불확실성·실측 데이터 미확보·이미지 생성 비용/지연·업체 참여율 등)의 완화 방안을 제안서에 제시하고 수행 중 관리 | + +## 3.11 프로젝트 지원 요구사항 (PSR) + +| ID | 요구사항 명칭 | 상세 내용 | +|---|---|---| +| PSR-001 | 무상 하자보수 | 최종 검수 후 **12개월 무상 하자보수**. 하자 등급별 대응 시간(치명 4시간 내 응답 등) 제안 | +| PSR-002 | 교육·매뉴얼 | 역할별(관리자·홀매니저·주최자·참가업체·업체) 사용자 교육 실시, 운영자·사용자 매뉴얼 및 교육 자료 제공 | +| PSR-003 | 운영 이관 | 운영 조직 대상 기술 이전(아키텍처·배포·장애 대응·룰셋/마스터 운영 절차), 운영 절차서·장애 대응 절차서 제공 | +| PSR-004 | 안정화 지원 | 오픈 후 안정화 기간(최소 1개월, 가안) 상주 또는 밀착 지원, 초기 행사 적용 현장 지원 | + +--- + +# 4. 제안서 작성 요령 및 목차 지정 + +## 4.1 작성 요령 + +1. 제안서는 본 제안요청서의 요구사항 전체(SFR~PSR)에 대해 **항목별 수용 여부·구현 방안**을 기술하고, 요구사항 ID 기준 **요구사항 추적표(RTM)** 를 첨부한다. +2. 제안서는 **한글로 작성**하며, A4 기준 **200쪽 이내**(표지·목차·별첨 제외, 가안)로 한다. +3. 객관적 근거(유사 실적·화면 예시·아키텍처 도식) 중심으로 작성하고, 검증 불가한 미사여구는 지양한다. +4. 제안 내용은 계약 시 **계약문서의 일부**로 효력을 가지며, 제안한 사항은 사업 범위에 포함된 것으로 본다. +5. 제안서 제출 후 내용 변경은 불가하며, 허위 기재 시 협상 대상 제외 또는 계약 해지 사유가 된다. +6. 가격 제안서는 기술 제안서와 **분리 밀봉** 제출한다. + +## 4.2 제안서 목차 (지정) + +| 장 | 목차 | 주요 내용 | +|---|---|---| +| Ⅰ | 제안 개요 | 제안사 일반현황, 사업 이해도, 추진 목표·전략 | +| Ⅱ | 사업 수행 부문 | 요구사항 이해 및 구현 방안(SFR 모듈별), 시스템 아키텍처(응용·데이터·인프라), AI 설계·시각화 파이프라인 구현 방안, 옥션·관람객·BI·CMS 구현 방안, 공통 레이어·보안 구현 방안 | +| Ⅲ | 성능·품질 부문 | 성능 확보 방안(PER), 테스트 계획(TER), 품질 보증(QUR), 보안 대책(SER) | +| Ⅳ | 프로젝트 관리 부문 | 수행 방법론·WBS·일정, 투입 조직·인력(M/M), 위험·변경·의사소통 관리 | +| Ⅴ | 지원 부문 | 교육, 하자보수·안정화, 기술 이전·운영 이관 | +| Ⅵ | 별첨 | 요구사항 추적표(RTM), 투입인력 이력사항, 유사 사업 실적 증명, 기술적용계획표, 상생협력·보안 관련 확약 서류 | + +--- + +# 5. 평가 기준 + +## 5.1 평가 방법 + +- **협상에 의한 계약** — 기술평가(90점) + 가격평가(10점) 합산, 종합평점 고득점 순 협상적격자 선정 후 순차 협상. +- 기술평가 점수가 **기술평가 배점의 85% 미만**인 경우 협상적격자에서 제외한다(가안). +- 평가위원회는 발주기관이 구성하며, **제안설명회(PT)와 함께 제안 기술의 시연(데모) 평가를 실시한다** — 핵심 기능(AI 배치/설계 생성·시공 예상 이미지·옥션 등)에 대해 **실제 동작하는 프로토타입 시연**을 요구하며, 슬라이드·목업만으로는 실증 배점을 인정하지 않는다. +- 공동수급(컨소시엄)의 경우 기술평가는 **주사업자(대표사)의 역량·실적을 중심으로 평가**한다. + +## 5.2 기술평가 항목 (90점) + +| 평가 부문 | 평가 항목 | 배점 | +|---|---|---| +| 전략·이해 (10) | 사업 이해도·추진 전략의 타당성 | 5 | +| | 전시 도메인(홀 배정·장치 규정·유틸리티·반입출) 이해도 | 5 | +| 기술·기능 (38) | 부스 배치·설계·배선 자동화(3안 생성·병합·규정 검증) 구현 방안의 구체성·실현성 | 8 | +| | AI 시공 예상 이미지 파이프라인(구조 보존 image-to-image·비동기 큐·워터마크·비용 통제) 구현 방안 | 8 | +| | AI 플랫폼 아키텍처 — 온프레미스 sLLM+상용 API 하이브리드·자동 폴백·RAG 근거/인용·환각 차단(SFR-035/036) 구현 방안 | 6 | +| | 공간정보(PostGIS) 데이터 모델·CAD 좌표 추출·마스터데이터/룰셋 버전 관리 설계 | 5 | +| | 공사/장치 옥션(역경매·견적서·낙찰)·정산 구현 방안 | 4 | +| | 관람객(등록·배지·리드)·마케팅/공개사이트(SEO·다국어)·CMS·BI 구현 방안 | 4 | +| | 보안(2FA OTP·RBAC·감사·암호화·PII)·품질·성능 확보 방안 | 3 | +| 수행 능력·실증 (32) | **구현 완성도 실증 — 제안 핵심 기술의 동작 프로토타입 시연(데모) 평가** | 10 | +| | **유사 AI 플랫폼(생성형 AI·업무 자동화 등) 구축 실적 — 최근 3년, 유사 규모 이상 다수 보유 우대** | 8 | +| | **온프레미스 AI(sLLM·벡터DB) 구축·운영 경험** | 4 | +| | **공간정보(GIS/PostGIS) 처리 시스템 구축 실적** | 4 | +| | 수행 방법론·일정(WBS)·단계별 검수 계획의 적정성 | 3 | +| | 투입 조직·인력의 전문성(제안 기술 스택 실무 경험) | 3 | +| 관리·지원 (10) | 위험 관리(생성 이미지 분쟁·데이터 미확보·외부 연동)의 인식·대응 | 3 | +| | 하자보수·교육·기술 이전·안정화 지원 계획 | 4 | +| | 상생협력·중소기업 참여 계획 | 3 | +| **합계** | | **90** | + +## 5.3 가격평가 (10점) + +- 배점한도 10점, 입찰가격 평점 산식은 국가계약법령 협상에 의한 계약 기준 산식을 준용한다(최저 입찰가 대비 상대평가). +- 예정가격 초과 입찰은 무효로 한다. + +--- + +# 6. 계약 조건 및 일정 + +## 6.1 입찰 및 계약 방식 + +| 구분 | 내용 | +|---|---| +| 입찰 방식 | 일반경쟁입찰(협상에 의한 계약) | +| 참가 자격 | 소프트웨어사업자(SW진흥법에 따른 신고), 국가계약법상 결격 사유 없는 자. **SW진흥법 제48조에 따른 대기업인 소프트웨어사업자의 참여 제한 적용**(가안 — 공고 시 확정), **중소 SW기업 참여 우대**. 공동수급(컨소시엄) 허용 — 대표사(주사업자) 지분 50% 이상(가안), 기술평가는 주사업자 역량 중심(§5.1) | +| 계약 방식 | 총액 확정 계약 | +| 대가 지급 | 선금(계약금액의 일정률, 청구 시)·중도금(단계 검수)·잔금(최종 검수) — 계약 시 확정(가안) | +| 계약 보증 | 계약보증금 계약금액의 10%, 하자보수보증금 3%(가안) | +| 지체상금 | 지체상금률 1일 1/1000(가안, 국가계약법령 준용) | + +## 6.2 추진 일정 (가안) + +| 구분 | 일정 | 비고 | +|---|---|---| +| 입찰 공고 | 2026-07-20 (가안) | 나라장터 게시 | +| 제안요청 설명회 | 2026-07-27 (가안) | 참석 여부는 평가와 무관 (가안) | +| 질의 접수 마감 | 2026-08-07 (가안) | 서면(전자) 질의 | +| 질의 회신 | 2026-08-14 (가안) | 나라장터·발주기관 공지 | +| 제안서 제출 마감 | 2026-08-31 18:00 (가안) | 기술·가격 분리 제출 | +| 제안 평가(PT 포함) | 2026-09-07 주간 (가안) | 평가위원회 | +| 협상 및 계약 체결 | 2026-09-21 주간 (가안) | 협상적격자 순차 협상 | +| 사업 착수 | 계약일로부터 14일 이내 착수보고 | | +| 사업 종료 | 계약일로부터 12개월 (가안) | 최종 검수 | + +## 6.3 검수 및 하자보수 + +- 단계별 중간 검수(PMR-001) + 최종 통합 검수(파일럿 행사 전 여정 시연 포함, TER-003). +- 최종 검수 후 **무상 하자보수 12개월**(PSR-001). 하자보수 기간 중 결함은 수급인 부담으로 조치. +- 하자보수와 별개의 유지관리(운영) 계약은 별도 협의. + +--- + +# 7. 보안·준수사항 + +## 7.1 법규 준수 + +| 구분 | 내용 | +|---|---| +| 개인정보보호법 | 관람객·리드·회원 개인정보의 수집·이용·제공·파기 전 과정 준수. 수집 최소화, 동의 절차, 암호화·마스킹(DAR-004·SER-007), 개인정보 처리방침 게시. 수급인은 개인정보 처리 위탁 계약 및 교육 의무 이행 | +| 정보통신망법 | 광고성 정보(EDM) 전송 시 수신동의·수신거부 처리 준수 | +| SW진흥법 | 소프트웨어사업 계약·관리감독 관련 규정 준수. **대기업인 소프트웨어사업자 참여 제한(제48조) 적용**(가안 — 발주기관의 국가기관등 해당 여부에 따라 공고 시 최종 확정), **중소 SW기업 참여 우대 및 상생협력 적용**. SW 기술자 투입·대가 산정은 SW사업 대가산정 가이드 참조 | +| 국가계약법령 | 협상에 의한 계약 절차·입찰 무효·부정당업자 제재 등 준용 | + +## 7.2 보안 서약 및 자료 관리 + +1. 수급인 및 투입 인력 전원은 착수 시 **보안서약서**를 제출한다. +2. 사업 수행 중 취득한 발주기관 내부 정보(홀 실측 도면·트렌치 좌표·요율·업체·관람객 데이터 등)는 본 사업 목적 외 사용·외부 유출을 금지하며, 사업 종료 시 반환·파기한다. +3. 소스코드·저장소·문서·로그에 **자격증명(API 키·비밀번호·접속정보) 기재를 금지**한다(SER-005). +4. 외부 API(이미지 생성·PG 등) 사용은 발주기관 승인 범위 내로 한정하고, 전송 데이터에 개인정보·내부 기밀 포함을 금지한다. +5. 개발·운영 환경 분리, 운영 데이터의 개발 환경 반입 금지(불가피 시 비식별화). + +## 7.3 산출물 귀속 및 지식재산권 + +1. 본 사업으로 개발된 산출물(소스코드·문서·데이터·디자인)의 지식재산권은 **발주기관에 귀속**함을 원칙으로 한다(가안 — 계약 시 확정, SW진흥법 취지에 따른 공동 활용 협의 가능). +2. 제3자 상용 SW·오픈소스 사용 시 라이선스 목록·조건을 제안서에 명시하고, 라이선스 위반 책임은 수급인이 부담한다. +3. AI 생성 이미지의 활용 범위·고지 의무(SFR-019)는 산출물 인계 후에도 시스템 기능으로 유지되어야 한다. + +--- + +# 8. 첨부 양식 목록 + +| 번호 | 양식명 | 비고 | +|---|---|---| +| 별첨 1 | 입찰 참가 신청서 | 나라장터 전자 제출 | +| 별첨 2 | 제안서 표지 및 목차 양식 | §4.2 목차 준수 | +| 별첨 3 | 요구사항 추적표(RTM) 양식 | SFR~PSR 전 항목 대응 | +| 별첨 4 | 기술적용계획표 | 전자정부 표준·상호운용성·보안 기술 적용 계획 | +| 별첨 5 | 투입인력 이력사항 및 M/M 총괄표 | 자격·경력 증빙 첨부 | +| 별첨 6 | 유사 사업 수행 실적 증명서 | AI 플랫폼·GIS 실적은 최근 3년, 일반 실적 최근 5년(가안) | +| 별첨 6-1 | 시연(데모) 계획서 | 시연 대상 기능·환경·시나리오 (§5.1 실증 평가) | +| 별첨 7 | 보안서약서 (법인·개인) | 착수 시 전 인력 제출 | +| 별첨 8 | 개인정보 처리 위탁 확약서 | 개인정보보호법 준수 | +| 별첨 9 | 상생협력(하도급) 계획서 | 해당 시 | +| 별첨 10 | 청렴계약 이행 서약서 | | +| 별첨 11 | 가격 제안서 양식 | 부가세 포함, 분리 밀봉 | +| 별첨 12 | 오픈소스/상용 SW 라이선스 목록 양식 | §7.3 | + +--- + +## 문의처 (가안) + +| 구분 | 내용 | +|---|---| +| 사업 담당 | (주)킨텍스 ○○팀 (가안) | +| 문의 방법 | 나라장터 질의 게시판(서면 질의 원칙) | + +> 본 제안요청서의 해석에 이견이 있는 경우 발주기관의 해석에 따르며, 명시되지 않은 사항은 국가계약법령 및 관련 법규를 준용한다. diff --git a/plugins/zio-harness/knowledge/kintex/docs/SECURITY.md b/plugins/zio-harness/knowledge/kintex/docs/SECURITY.md new file mode 100644 index 0000000..e3a9b76 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/SECURITY.md @@ -0,0 +1,70 @@ +# KINTEX 보안 제약 (불변) + +> GUARDiA 보안 제약(`CLAUDE.md` / `_framework/GUARDIA_STANDARD_FRAMEWORK.md §6`)을 킨텍스 관점으로 정리한 단일 참조. +> 아래 규칙은 어떤 상황에서도 위반 불가. API 계약(`API_GUIDE.md §5`)·개발 표준(`DEVELOPMENT_GUIDE.md §5`)과 함께 강제된다. + +--- + +## 1. 외부 API 호출 정책 + +| 대상 | 정책 | 근거 | +|------|------|------| +| **온프레미스 Ollama** | 허용(기본) | 표준 온프레미스 우선 | +| **Anthropic Claude** (`api.anthropic.com`) | **승인된 단일 예외** — 키는 `ANTHROPIC_API_KEY` env only, 실패 시 Ollama 자동 폴백 | 소유자 승인(2026-07-03) | +| **Gemini 나노바나나** (이미지 생성) | **킨텍스 고유 승인 예외(G1 게이트)** — 키는 `GEMINI_API_KEY` **워커 env only**(백엔드 미취급), 미승인 시 목/degraded | PLANNING R12·G1 | +| 그 외 모든 외부 API | **금지** | 표준 불변 | + +- Claude/Gemini 키는 **DB·코드·커밋·로그·API 응답에 절대 기록 금지**. env 에서만 로드. +- Gemini 는 **나노바나나 Python 워커에서만** 로드한다. Spring 백엔드는 큐 발행/콜백 수신만 하고 키를 취급하지 않는다. + +## 2. 자격증명·민감정보 보호 + +- **응답 완전 제외**: 내부 IP·SSH 계정·비밀번호·비밀번호 해시·`GEMINI_API_KEY`·`ANTHROPIC_API_KEY`·내부 식별자·워커 토큰. (`ServerOut`류 스키마에서 제외 — API_GUIDE §5.) +- 사용자·업체 표시는 **비민감 필드만**. +- 로그·에러 메시지·메신저 알림에도 자격증명 노출 금지. +- 운영 스크립트(`scripts/push_kintex.py`·`tools/test/kintex_smoke_test.py`)는 **시크릿 하드코딩 0** — 전부 환경변수에서만 읽고, 조립한 인증 URL 조차 출력하지 않는다(마스킹). + +## 3. 암호화 저장 (AES-256-GCM) + +- admin 비밀번호: env `ADMIN_PASSWORD_ENC`(AES-256-GCM 암호문) + `ADMIN_KEY_FILE`(별도 키파일, root 600) → 기동 시 BCrypt 재시드. 하드코딩 `admin123`/`1111` 시드 금지. +- 저장이 필요한 외부 자격증명(SMTP 등)은 암호화 컬럼에만. 평문 저장 금지. +- JWT 시크릿(`KINTEX_JWT_SECRET`)·DB 비번(`KINTEX_DB_PASSWORD`)은 env/`application.yml` 프로퍼티 주입, `.env`·`*.key` 는 gitignore. + +## 4. 인증·권한 (JWT + 2FA + 행사 RBAC) + +- JWT(HS256) + **2차 인증(OTP/EMAIL 코드)** 2단계 로그인 + **로그인 실패 잠금**(관리자 해제). +- **행사 단위 RBAC**: 열람=행사 멤버 or 홀매니저 / 편집·액션=엔드포인트별 역할(`ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER`). +- **미등록 장치업체 차단**: 초대·응찰은 등록업체 검증(`NOT_REGISTERED_COMPANY` 403). +- `/api/admin/**` = ADMIN 역할 게이트. `/api/internal/**` = 워커 공유 시크릿(`X-Worker-Token`)만. + +## 5. AI 생성 이미지 워터마크 (킨텍스 고유 불변) + +- M5 나노바나나 결과 이미지 응답은 **항상** `watermarkRequired:true` + `watermarkText` + `notice`(계약·심사 서류 사용 금지 안내)를 포함한다. +- AI 생성 시각화는 **참고용**이며 계약·인허가 서류로 사용 불가 — UI·응답·PDF 어디서나 워터마크/고지 강제. + +## 6. 오류 응답 (스택트레이스 미노출) + +- 모든 오류는 `ApiResponse.error`(코드 + 사람이 읽는 요약 메시지)만 반환. **스택트레이스·relation/컬럼명·내부 경로 미노출**(서버 로그에만). +- DB 오류(DataAccessException)는 `@RestControllerAdvice` 로 `INTERNAL` 요약 매핑 → 테이블/컬럼명 누출 차단. +- 워커 실패 `errorMessage` 는 요약만 통과(스택트레이스 유입 차단). +- 오류 코드→HTTP 매핑은 `API_GUIDE.md §3` 고정 표를 따른다. + +## 7. 감사 추적 + +- 관리자·인증·권한 변경 등 민감 액션은 감사 로그(`common/audit`, `TB_AUDIT_LOG` 계열)에 기록. 감사 로그에도 비밀값 미기재. + +## 8. 서버 접속 (root 예외) + +- 관리 대상 서버는 opsagent 전용, root SSH 금지가 표준. **예외**: GUARDiA 자체 인프라 `101.79.17.164`(kintex 개발 호스트 포함)에 한해 운영 작업용 root SSH 허용(소유자 승인 2026-06-18). 운영 배포는 소유자 승인 필수. + +--- + +## 체크리스트 (배포·리뷰 전) + +- [ ] 응답/로그/커밋에 IP·SSH·비번·해시·API키·워커토큰 노출 0 (grep) +- [ ] Gemini/Claude 키는 env only — 코드·DB·커밋 미포함 +- [ ] admin 비번 하드코딩 시드 없음(env 재시드) +- [ ] M5 이미지 응답 `watermarkRequired:true` 포함 +- [ ] DB/서버 오류 → 요약 메시지(스택·relation 명 미노출) +- [ ] 운영 스크립트 시크릿 하드코딩 0(env-only, 마스킹) +- [ ] `/api/admin/**` ADMIN 게이트·행사 RBAC·미등록업체 차단 동작 diff --git a/plugins/zio-harness/knowledge/kintex/docs/UNDEVELOPED_BACKLOG.md b/plugins/zio-harness/knowledge/kintex/docs/UNDEVELOPED_BACKLOG.md new file mode 100644 index 0000000..b1ca691 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/UNDEVELOPED_BACKLOG.md @@ -0,0 +1,94 @@ +# 미개발 백로그 — 세션 스캔 통합 (UNDEVELOPED_BACKLOG) + +> 2026-07-11 세션 대화 전체 스캔 결과. "무엇이 아직 개발 안 됐는가"를 단일 문서로 통합. +> 상위 문서: `WORK_STATUS.md`(인수인계) · `IMPLEMENTATION_BACKLOG.md`(Phase 구조) · `FEATURE_BACKLOG_100.md`(100대 기능) · `BACKLOG.md`(reviewer 티켓). +> 상태: ⬜ 미착수 · 🔶 부분(샘플/스텁) · 🔷 진행 중 · ⏸ 게이트 대기 + +--- + +## 1. 신규 5화면(SCR-13~17) 트랙 — 이번 세션 파생 + +구현 자체는 완료(프론트 16파일 생성·tsc 통과, QA 진행 중). 아래는 **화면은 있으나 데이터/백엔드가 미개발**인 잔여. + +| 상태 | 항목 | 내용 | 담당 | 편입 Phase | +|---|---|---|---|---| +| ✅ | SCR-13 BI 실데이터 전환 | ~~집계 API 신설 필요~~ → **완료(2026-07-12)**: 행사 스코프 `/api/events/{id}/analytics`(P&L 포함) + 테넌트 전역 `/api/analytics/overview`(행사 간 매출·홀 가동률 추이·리텐션·선형회귀 예측). 잔여: 실 정산 데이터 연동 시 매출 산식 고도화(M9) | BI·BE | 완료 | +| ✅ | SCR-14 현장운영 실전환 | **완료(2026-07-12 W4)**: 혼잡=체크인 실집계 파생·전력=utility 부하 합산. CCTV·HVAC·iparking·조명 IoT는 하드웨어 계약 게이트(빈 상태 정직 표기 유지) | BE·FE | 완료 | +| ✅ | SCR-15 일정 실전환 | **완료(2026-07-12)**: V23(category·est_visitors 크롤 백필) + `/api/events/hall-utilization`·`/api/events/calendar` + 화면 실 전환. 잔여: hall_assignment 역사 백필(자유텍스트 파싱 리스크로 보류), M10 실집계 연동 시 est_visitors 갱신 | BE·FE | 완료 | +| 🔶 | SCR-16 관리자 집계 실전환 | 사용자수·활성행사수 등 실 가능 지표 API 연결. 실시간 방문객·주차·라이브는 M10/M14 이후 | ADM·BE | D-M18 | +| 🔶 | M18 관리자 본체 화면 | **users·roles·codes·menus CRUD 화면 + AdminGuard(전 /admin/* 가드) + A8 룰셋 실배선 확인 완료(2026-07-12)**. 잔여: A9 멀티테넌시 2단계(§4). roleCode 노출·테넌트 API 실배선은 완료(W4/W6) | ADM·BE | D-M18 | +| ⬜ | SCR-16 플로팅 AI 봇 | design.md상 P2·비노출 기본 — 미구현(주석만) | AI·FE | P2 | +| ✅ | AppShell 기존 네비 배선 | **완료(2026-07-12 W4)** — 행사 컨텍스트 계산 경로(useResolvedEventId) 배선 + 정산/홀배정 신설 | FE·DES | 완료 | +| ✅ | `/_styleguide` 노출 방침 | **완료(2026-07-12 W4)** — import.meta.env.DEV 분기(프로덕션 라우트 제거) | FE·TA | 완료 | +| ⬜ | Stitch 아이콘 세트 교체 | 이모지/글리프 → `stitch_kintex_ai_system_architect/_icons/` 정식 아이콘 전면 교체 | FE·DES | C-C | +| ⬜ | Stitch 구버전 폴더 정리 | `component_guide_kintex_ai_system/`(구버전, updated로 대체됨) 정리 — **삭제는 사용자 확인 후** | — | — | + +## 1B. Stitch 이식 트랙 파생 (2026-07-12) — 화면은 완료, 백엔드 대기 + +이식 25화면(웹 SCR-22~38·A5~A9·P1~P7 + 모바일 M15) 중 **A5·A6만 실배선**, 나머지는 샘플 데이터. 백엔드 구현 시 화면별 API 계약 초안 = `_workspace/port_{ops_docs,auction,visitor_marketing,cms,public,admin,mobile_m15}.md`. + +| 상태 | 항목 | 내용 | 편입 | +|---|---|---|---| +| ✅ | M6/M8 백엔드 | **완료(2026-07-12, V14/V15)** — impl_m6m8.md 참조 | 완료 | +| 🔶 | M15 옥션 백엔드 | **개설·봉인 응찰·낙찰·수주 대시보드 완료(V16 + 2차 웨이브 스코어링)**. 잔여: WebSocket 실시간 순위(현 폴링) | D-M15 | +| 🔶 | M10/M12 백엔드 | **사전등록·리드·체크인·배지·CSV·캠페인·스폰서십 완료(V17/V18/V21)**. 잔여: EDM 실 발송 게이트웨이·리드 AI 재계산(AiTextRouter) | D-M10/12 | +| 🔶 | M17 CMS 백엔드 | **콘텐츠·전이·번역·마이크로사이트·버전·미디어·공개API 완료(V19 + 2차 웨이브)**. 잔여: AI 자동번역 배선·예약게시 Redis 트리거 | D-M17 | +| ✅ | 공개 카탈로그 API | **완료(2026-07-12, V20 public_site)** — /api/public/events 등 라이브 검증 | 완료 | +| ✅ | 프론트 admin RBAC 가드 | **완료(2026-07-12)** — AdminGuard + 전 /admin/* 라우트 배선(hallManager 기준·백엔드가 최종 권위) | 완료 | +| ✅ | QA minor 2 | **완료(2026-07-12)** — kx-field 스코프 격리·★ SVG는 기왕 해소, ✓(OrganizerDashboardPage) IconCheck 교체 | 완료 | +| ⬜ | 모바일 B2C 탭 셸 | 관람객 트랙 탭 부재 — M15는 /tickets 라우트만 존재 + RN node_modules 손상(devops 재설치) | 모바일 | + +## 2. 백그라운드 산출물 — 커밋 대기·미완 검증 필요 + +| 상태 | 항목 | 내용 | 비고 | +|---|---|---|---| +| 🔷 | 모바일 앱(Expo) `mobile/` | 스캐폴드 생성됨 — 미커밋. 빌드/실행 검증·기능 범위 확정 미완 | node_modules gitignore 확인 | +| 🔶 | 산출물 `docs/deliverables/` | 사업수행계획서.docx + `_gen/` 스크립트만 확인됨. **지침서 3종(사용자·운영자·개발자) PPT·프로그램 사양서+순서도 PPT 폴더 부재 → 재실행 필요**. ★**갱신 정책(2026-07-11 사용자 지시): 최초 1회 생성 → 개발 완료 시 최종 1회만 갱신(중간 갱신 금지, 비용 절감)** — 자동갱신 스크립트는 최종 시점 1회 실행용 | `gen_xlsx.py.tmp.*` 잔재 정리 | +| ⬜ | 잡파일 정리 | `hs_err_pid*.log`·`replay_pid*.log`(JVM 크래시 잔재)·`_gen/*.tmp.*` — 삭제는 사용자 확인 후 | 루트 오염 | +| ⬜ | `ci/`(CI 로고 자산) 커밋 여부 | 미추적 상태 — 번들 참조 여부 확인 후 커밋/ignore 결정 | | + +## 3. 전 화면 공통 NFR — 미적용 (WORK_STATUS §6 이월) + +| 상태 | 항목 | 내용 | +|---|---|---| +| 🔶 | 라이트/다크 테마 | **토글+다크 팔레트+공유 레이어 토큰화 완료(2026-07-12 W5)**. 잔여: 화면별 하드코딩 hex 스윕(목록=_workspace/impl_theme_a11y.md) | +| 🔶 | 다국어(i18n) | **프레임워크(react-i18next ko/en/zh/ja)+공개 P1~P7+로그인/가입 완료(2026-07-12 W5)**. 잔여: 인증 후 화면 문구 추출(패턴=_workspace/impl_i18n.md) | +| 🔶 | 웹접근성 | 공유 레이어(focus-ring·reduced-motion·스킵링크) 완료(W5) — 화면 전면 감사·WCAG AA 검증 미완 | +| 🔶 | 반응형 풀스크린 | 데스크톱 1440 기준 — 태블릿/모바일 브레이크포인트 전면 적용 미완 | +| ⬜ | 시큐어코딩 점검 | 전면 감사(입력 검증·XSS·CSRF) 미실행 | + +## 4. 아키텍처·플랫폼 대형 트랙 — 미착수 + +| 상태 | 항목 | 내용 | 편입 | +|---|---|---|---| +| 🔶 | 멀티테넌시 구현 | **1단계 완료(2026-07-12 W6)**: V26 tenant 마스터+tenant_id(event/hall/app_user)·TenantContextFilter·catalog/hall 스코핑·admin tenants API. 잔여 2단계: 전 매퍼 스코핑·JWT tid·프론트 스위처(설계=_workspace/impl_tenant_phase1.md) | BE·FE | +| ⬜ | MDI 셸 전환 | design.md §2.7 다중문서 인터페이스 — 현 AppShell은 단일 문서 | FE·DES | +| ⬜ | 100대 기능 갭 | FEATURE_BACKLOG_100 기준 신규 19 + 부분 18 — 관람객·네트워킹·참가업체 서비스 집중, orchestrator Phase 편입 필요 | 전체 | + +## 5. 도메인 모듈(Phase D/E) — 미착수 + +| 상태 | 모듈 | 내용 | +|---|---|---| +| 🔶 | M15 공사/장치 옥션 | 코어 완료(§1B 참조) — 잔여: WebSocket 순위·계약 후속 | +| 🔶 | M10 관람객·현장 | 등록·배지/QR·체크인·리드 완료 — 잔여: 티켓 PG 실연동 | +| ⬜ | M12/M17 CMS·공개사이트 | 헤드리스 CMS·마이크로사이트·일반 대중 공개 홍보 사이트(SEO·다국어) | +| ✅ | M16 BI 백엔드 | **완료(2026-07-12 W3)** — 행사 스코프+전역 overview(리텐션·예측 포함) | +| ⬜ | M18 관리자 본체 | §1 참조 — 마스터데이터(홀·요율·룰셋·등록업체) CRUD 포함 | +| 🔶 | M1/6/7/9 | **M1 홀배정+자동견적·M6 서류·M9 정산 완료(W4)**. 잔여: M7 매칭·M9 실 PG | +| ⬜ | M11 비즈매칭 · M13 wayfinding | P2 | + +## 6. 잔여 reviewer 티켓 (BACKLOG.md open) + +B-01(조립부스 옵션 UI)·B-04(화면 수 표기)·B-05(정산 메뉴 IA)·B-06(이메일 인증 프롬프트)·B-07(SCR-03 공유·핀 불일치)·B-08(SCR-04 산술 오류)·B-10(Phase 라벨·조명 UI) — 전부 designer 담당. + +## 7. 게이트·인프라 후속 + +| 상태 | 항목 | 내용 | +|---|---|---| +| ✅ | 운영 도메인 | **https://kintex.wise.ai.kr 라이브(2026-07-12, 소유자 승인)** — wise 호스트 nginx 프록시(dev 오리진)+LE TLS. push→자동배포=운영 반영. 풀스택 분리는 호스트 자원(RAM 2G·디스크 95%) 확보 후 2단계 | +| 🔷 | 이번 트랙 마감 | QA(진행 중) → reviewer 정합 검증 → 커밋·push(자동배포) → WORK_STATUS 갱신 | + +## 변경 이력 +| 일자 | 갱신 | +|---|---| +| 2026-07-11 | 최초 작성 — 세션 대화 전체 스캔(신규 5화면 파생 잔여·커밋 대기·NFR·대형 트랙·도메인·티켓·게이트) | diff --git a/plugins/zio-harness/knowledge/kintex/docs/WORK_STATUS.md b/plugins/zio-harness/knowledge/kintex/docs/WORK_STATUS.md new file mode 100644 index 0000000..d98ef38 --- /dev/null +++ b/plugins/zio-harness/knowledge/kintex/docs/WORK_STATUS.md @@ -0,0 +1,109 @@ +# 킨텍스 자동전시시스템 — 작업 현황·인수인계 (WORK_STATUS) + +> **목적**: 다른 PC/세션에서 작업을 이어가기 위한 단일 인수인계 문서. **수시 업데이트**(기능 추가·변경·트랙 완료 시 갱신 후 커밋). +> 최종 갱신: 2026-07-11 · 리포 `git.zioinfo.co.kr/zio/kintex`(main) · 시크릿(비밀번호·키·서버IP)은 본 문서에 **미기재**(env·GUARDiA 공용 참조). + +--- + +## 0. 빠른 시작 (다른 PC에서 이어받기) +1. `git clone` `zio/kintex` → main. +2. 핵심 문서: `docs/PLANNING.md`(v3.0 기획)·`docs/design.md`(v1.2 화면·MDI)·`docs/IMPLEMENTATION_BACKLOG.md`·`docs/FEATURE_BACKLOG_100.md`·`docs/architecture/*`·`docs/GUARDIA_ALIGNMENT.md`·`docs/SECURITY.md`·`docs/ENV_SETUP.md`·`docs/OPS_RUNBOOK.md`·`CLAUDE.md`. +3. 하네스: `.claude/`(에이전트 ~20 + `kintex-impl-orchestrator` 스킬). 구현은 오케스트레이터가 조율. +4. 이 문서(WORK_STATUS.md)로 "무엇이 됐고/도는 중/남았는지" 파악. + +## 1. 프로젝트 개요 +킨텍스 **자동전시시스템**(다중 전시관 멀티테넌트 SaaS, KINTEX=테넌트#1, COEX 등 온보딩). 전시 생애주기(판매→AI 설계·시각화→공사 옥션→시공→운영→경영분석) 폐루프. + +## 2. 스택·인프라 (시크릿 제외) +- 프론트 React 18/19(Vite·TS) / 백엔드 Spring Boot 3.2.5(Java17)+MyBatis / DB PostgreSQL+PostGIS(Flyway) / Redis / 나노바나나 Python 워커(google-genai `gemini-3.1-flash-image-preview`). +- AI 지능 = **Claude 기본**(AiTextRouter/AiConfig) + Ollama 폴백. 이미지 = 나노바나나(Gemini, 소유자 승인=G1 라이브). +- 개발 배포: **https://kintex.zioinfo.co.kr**(TLS·백엔드 8021·PostGIS·Redis·워커 systemd). 서버 접속 자격증명은 **GUARDiA 공용**(env·리포 미기재). +- **운영 도메인: https://kintex.wise.ai.kr 라이브(2026-07-12)** — wise.ai.kr 호스트(211.37.173.197, SSH 9271·dev의 `/var/lib/jenkins/.ssh/id_ed25519_prod` 키 채널)의 nginx vhost `conf.d/kintex.conf`가 dev 오리진으로 리버스 프록시 + LE TLS(자동 갱신). **push→dev 자동배포 = 운영 즉시 반영**(단일 오리진). ★운영 호스트는 RAM 2G·디스크 95%(레거시 CUBRID/톰캣 14.6G)로 **풀스택 상주 불가 판정** — 자원 확보 후 UIWS 패턴(tar-over-ssh 승격, `workspace/uiws/_workspace/prod-provision/50_cicd_prod.md`)으로 2단계 분리. +- CI/CD: Gitea webhook → `deploy_kintex.sh`(백엔드 `sh gradlew bootJar` + 프론트 vite 빌드 → 배포 → health → 롤백). push하면 자동배포. + +## 3. 요구사항 로그 (이번 세션 누적 — 스코프 진화) +1. Gitea `kintex` 리포 생성 + 로컬 소스 push. +2. kintex.com 전 페이지 분석 + ReRoomAI 소스 분석 → AI 전시시스템 하네스 생성(부스 배치·인테리어·전기·조명·네트워크 배선 자동화 → 나노바나나 시공 후 사진). +3. 웹/모바일 UI는 디자인 에이전트로 design.md 생성 후 **Google Stitch** 전달. +4. 스택 확정: React + Spring Boot + MyBatis + PostgreSQL. +5. **구현용 하네스 전체 생성**(전문 에이전트 + 오케스트레이터 + 백로그). +6. **자동전시시스템**으로 확장: 전시 관련 모든 기능·**경영분석(BI)**·웹/모바일 역할별 분리·**별도 관리자 시스템**·**CMS**. +7. 사용자 역할: 전시하려는자/공사 입찰사/킨텍스 직원 등 + **일반 대중 공개 홍보 페이지**. +8. 공사업체가 **AI 생성 자료 열람 → 견적서 제출 → 옥션(역경매) → 전시업체가 업체 확정**. +9. **부스 구성 AI 1·2·3안 생성 → 선택 또는 병합**. +10. **UIWS(WISE) 시스템관리·공통기능 전체 이식**(2FA/OTP 포함). +11. AI·QA·AA·SA·NA·TA·DA + **PM·개발PM·PMO** 에이전트 고용. AI는 **Claude(클로드코드)로 구현 + 설정에서 모델 변경**. +12. 전시장 평면도 크롤링 확보(CAD+JPG) + **CAD/JPG 포맷 지원**. +13. **개발서버 + CI/CD 구축**(WISE env 참조·kintex.zioinfo.co.kr). +14. **멀티테넌시(tenant_id)** — 코엑스 등 다중 전시관. +15. **MDI(다중문서 인터페이스)** 셸. +16. **DB 별도 구성**(전용 kintex_db). +17. GUARDiA 솔루션 재사용 패턴(py/md) kintex 흡수. +18. 로그인 좌측 히어로 이미지 + **CI 로고**(ci/ 폴더). +19. **Stitch 전 화면 디자인 반영**(이미지 포함) + 신규 화면. +20. **회원가입·비밀번호 찾기/초기화·아이디 기억**. +21. **반응형 풀스크린 + 모바일 앱**. +22. **전시관리 100대 기능** 크롤링·기획(AI 자동화로 수작업 최소화) + 백로그. +23. **웹접근성·시큐어코딩·다국어·라이트/다크 테마**(공통 NFR). +24. 행안부 산출물 표준 → **사업수행계획서 + 전 산출물 Excel/PPT/Doc**. ~~기능 변경 시 자동 업데이트~~ → **(2026-07-11 변경) 최초 1회 생성 + 개발 완료 시 최종 1회만 갱신**(중간 갱신 금지·비용 절감, 자동갱신 스크립트는 최종 시점 실행용). +25. **사용자·운영자·개발자 지침서 PPT**. +26. **프로그램 사양서(기능별 상세) + 순서도 PPT**. +27. 본 WORK_STATUS.md로 인수인계·수시 업데이트. + +## 4. 완료·라이브 (커밋 기준) +- **문서**: PLANNING v3.0(멀티테넌시)·design.md v1.2(MDI)·아키텍처 5종(app/system/tech/data/network)·WISE 개발문서 6종·FEATURE_BACKLOG_100 + GAP_ANALYSIS·GUARDIA_ALIGNMENT·SECURITY·OPS_RUNBOOK. +- **백엔드(라이브)**: 스캐폴드 + 인증(JWT/RBAC) + M2~M5 매퍼 배선(501 해소·PostGIS) + 룰엔진 + Phase B 공통레이어(2FA/OTP·시스템관리·공통 업무기능 V7/V8) + 공개 인증(register·forgot·reset V9). Flyway V1~V9(테이블 39). +- **프론트(라이브)**: 로그인(히어로+CI로고+인증 UI: 회원가입·비번찾기·아이디기억) + Stitch 반영(부스 설계 스튜디오·대시보드·갤러리·신규 8화면 SCR-04/05/08/09/10/11 + 모바일 M1/M2) + 번들 이미지 25. +- **인프라(라이브)**: 개발서버 8021·PostGIS·Redis·나노바나나 워커(Gemini 라이브)·TLS·CI/CD 자동배포·배포 파이프라인 근본수정. +- **계정**: `admin@kintex.zioinfo.co.kr`(env 시더, role ADMIN) — 로그인 200 확인. +- **자산**: 평면도 JPG 15 + CAD(트렌치) `docs/assets/floorplans/`(CAD는 gitignore). Stitch 프로젝트 9385904003821333054 화면 `stitch_kintex_ai_system_architect/`. + +## 5. 진행 중(백그라운드 에이전트) — 커밋 대기 +- 모바일 앱(Expo, `mobile/`) 스캐폴드. +- 산출물: 사업수행계획서 + 행안부 표준양식 크롤링 + 전 산출물 Excel/PPT/Doc(`docs/deliverables/`) + 자동갱신 스크립트. +- 지침서 3종(사용자·운영자·개발자) PPT(`docs/deliverables/지침서/`). +- 프로그램 사양서(기능별 상세) + 순서도 PPT(`docs/deliverables/프로그램사양서/`). + +## 6. 남은 큐 (후속) +> **상세 미개발 통합 목록: `docs/UNDEVELOPED_BACKLOG.md`** (2026-07-11 세션 스캔 — 화면별 샘플→실데이터 전환·커밋 대기·NFR·대형 트랙 전체) +- **신규 5화면**: ~~반영 대기~~ → **구현 완료(2026-07-11)** — SCR-13~17(경영분석 `/analytics`·현장운영 `/ops/operations`·전시일정 `/schedule`·관리자 랜딩 `/admin`·스타일가이드 `/_styleguide`) design.md v1.3 매핑 + React 이식(tsc 통과·Recharts 도입). QA·reviewer·커밋 마감 진행 중. 데이터는 대부분 샘플(집계 API 미구축 — UNDEVELOPED_BACKLOG §1). +- **아이콘 세트 교체**(이모지 → Stitch 정식 아이콘, `_icons/`). +- **반응형 풀스크린 + 라이트/다크 테마 + 다국어(i18n) + 접근성** 전면 적용. +- **100대 기능 갭**(신규19/부분18) → orchestrator Phase 편입 구현(관람객·네트워킹·참가업체 서비스 집중). +- **멀티테넌시 구현**(DA 데이터모델 → db-engineer tenant_id 스키마 → backend 테넌트 컨텍스트). +- **MDI 프론트 전환**(design.md §2.7 기준). +- 도메인 모듈 구현: 옥션(M15)·관람객(M10)·CMS/공개사이트(M12/M17)·BI(M16)·관리자(M18). + +## 7. 배포·운영 함정 (반드시 숙지) +- `deploy_kintex.sh`는 백엔드도 빌드해야 함(과거 미빌드 버그·수정됨). `gradlew`는 `sh ./gradlew`(실행권한 이슈). `grep -q` SIGPIPE 회피. +- **★MyBatis+PostgreSQL 별칭(2026-07-12 규명)**: PG는 따옴표 없는 별칭을 소문자로 접음(`AS userId`→`userid`) → **Map 반환 @Select는 반드시 `AS "userId"`(쌍따옴표)**. 안 그러면 컴파일·단위테스트 통과하고 런타임에서 키 전부 null(secure 로그인 전멸·집계 API 0/null이었음). UserMapper.xml 컨벤션 준수. 신규 매퍼 작성 시 필수 점검. +- **프론트 검증은 `tsc -b`**(서버 빌드와 동일) — `tsc --noEmit`은 프로젝트 레퍼런스 설정을 안 타서 서버에서만 실패하는 오류(noUnusedLocals 등)를 놓침. **CSS import 누락은 tsc가 못 잡음** → 커밋 전 `npx vite build`도 통과시켜라(2026-07-12 checkin.css 누락으로 서버 프론트 빌드 2회 실패). +- **★MyBatis `