ythong/harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(zio-harness): v1.1.0 — auto source analysis + GUARDiA/KINTEX knowledge base

Browse Source 
- SessionStart hook (scripts/graphify_setup.py): auto-install graphifyy[sql],
  build knowledge graph on first run (graphify extract --code-only, local AST),
  incremental graphify update thereafter — install-only smartness
- knowledge/kintex/: all 183 KINTEX md docs bundled (planning/design/analysis)
- knowledge/guardia/: distilled GUARDiA-wide knowledge from 2,483 md files
  (solutions-catalog, standard-framework, operations-cicd, lessons-learned;
  credentials/IP-free curated)
- SKILL.md: graph-first codebase query rules + knowledge base loading guide

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
DESKTOP-TKLFCPR\ython 2026-07-12 23:15:35 +09:00
parent 4ef3732da1
commit 1ef2235939
66 changed files with 15769 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.claude-plugin/marketplace.json
View File

@ -15,8 +15,8 @@
{ {
"name": "zio-harness", "name": "zio-harness",
"source": "./plugins/zio-harness", "source": "./plugins/zio-harness",
"description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.", "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억. 설치만으로 graphify 지식 그래프가 소스를 자동 분석(SessionStart 훅)하고, KINTEX 도메인 md 지식 베이스를 내장.",
"version": "1.0.1" "version": "1.1.0"
}, },
{ {
"name": "proposal-builder", "name": "proposal-builder",

4
plugins/zio-harness/.claude-plugin/plugin.json
View File

@ -1,7 +1,7 @@
{ {
"name": "zio-harness", "name": "zio-harness",
"description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.", "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억. 설치만으로 graphify 지식 그래프가 소스를 자동 분석(SessionStart 훅)하고, KINTEX 도메인 md 지식 베이스를 내장.",
"version": "1.0.1", "version": "1.1.0",
"author": { "author": {
"name": "ythong", "name": "ythong",
"url": "https://git.zioinfo.co.kr/ythong" "url": "https://git.zioinfo.co.kr/ythong"

16
plugins/zio-harness/hooks/hooks.json Normal file
View File

@ -0,0 +1,16 @@
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume",
"hooks": [
{
"type": "command",
"command": "python \"${CLAUDE_PLUGIN_ROOT}/scripts/graphify_setup.py\"",
"timeout": 600
}
]
}
]
}
}

259
plugins/zio-harness/knowledge/guardia/lessons-learned.md Normal file
View File

@ -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/<sol>/.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)

259
plugins/zio-harness/knowledge/guardia/operations-cicd.md Normal file
View File

@ -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/<repo>` | 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/<sol>/` 소스 완성 → repos/<sol> fresh init → Gitea `zio/<sol>` repo 생성 + push
2. 서버: `/opt/<sol>/src` git clone(체크아웃), DB `{sol}_db`/`{sol}_user` 생성, systemd `guardia-<sol>.service` 등록(setup_<sol>_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`에 <sol> 배포 블록 추가 → **서버 사본 반영 + 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 금지

400
plugins/zio-harness/knowledge/guardia/solutions-catalog.md Normal file
View File

@ -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/<sol>/` 하위. 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·<sol>별 화면·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 인스턴스 공유(솔루션별 `<sol>_db`/`<sol>_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/<sol>` (작업 소스) ↔ `repos/<sol>` (push용 독립 저장소) ↔ Gitea ↔ 서버 `/opt/<sol>` 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 <sol>.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/`(솔루션 로컬 오케스트레이터 + `<sol>-{backend,frontend,db,qa,devops}-dev` + 도메인 AI 에이전트 4종 `<sol>-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 기재. 접속 정보는 도메인+포트까지만.

377
plugins/zio-harness/knowledge/guardia/standard-framework.md Normal file
View File

@ -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/<sol>/` 통합 런처에 편입 |
| 백엔드 | **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** — `<sol>_db` / `<sol>_user` | 공유 인스턴스 + 솔루션별 분리 계정, Hikari `maximum-pool-size: 3` |
| 리포트 | JasperReports (PDF) | 공통 |
| 패키징 | **단일 jar** | 프론트 빌드 → 백엔드 static 번들 → 하나의 jar로 배포 |
### 스택 관련 규칙
- 프론트 axios baseURL은 `/api` — nginx가 `/` → SPA 정적 파일, `/api/` → 백엔드 포트로 프록시하므로 별도 CORS 불필요.
- 모든 API 응답은 봉투(envelope) 형식: `ApiResponse<T> = { success, data, message }`, 목록은 `PageResponse<T>`.
- 클라이언트(웹·모바일)는 봉투 언랩(unwrap) 유틸을 공통화한다 — 모바일 이식 시 `PageResponse` 봉투 언랩 누락이 실제 경계면 버그 사례.
- DB 스키마의 단일 진실원천은 마이그레이션 DDL (Hibernate 사용 시 `ddl-auto: validate`).
- 신규 솔루션 명명: DB `<sol>_db`/`<sol>_user`, 패키지 `com.zioinfo.<sol>`, 포트는 솔루션별 고정 할당.
- 시크릿·접속정보는 전부 환경변수/프로퍼티 주입 — 하드코딩 금지. (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_<solution>`).
- 스택: 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**(`<sol>_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/<sol> (개발 소스)
→ repos/<sol> (fresh git init 독립 저장소)
→ Gitea push (git.zioinfo.co.kr/zio/<sol>)
→ Gitea webhook (push 이벤트)
→ deploy_server (webhook 수신 → git pull → 빌드 → 재시작)
→ systemd (<sol>.service — 부팅 자동기동·재시작)
→ nginx (도메인 vhost: / → SPA 정적, /api/ → 백엔드 포트 프록시, certbot TLS)
```
### 7.1a nginx vhost 표준 (도메인 서빙형)
```
브라우저 ── https ──> nginx(<sol>.zioinfo.co.kr)
├─ / → /var/www/<sol> (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 <domain>`(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/<sol>/`(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 `<sol>_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` 등)으로만 한다.

156
plugins/zio-harness/knowledge/kintex/CLAUDE.md Normal file
View File

@ -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 "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` 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).

21
plugins/zio-harness/knowledge/kintex/README.md Normal file
View File

@ -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 스킬
```

97
plugins/zio-harness/knowledge/kintex/docs/API_GUIDE.md Normal file
View File

@ -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<T>`:
```json
{ "success": true, "data": { ... }, "error": null }
{ "success": false, "data": null, "error": { "code": "FORBIDDEN", "message": "이 행사/부스에 대한 권한이 없습니다." } }
```
- 목록: `PageResponse<T>` = `{ "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 <JWT>` (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)

29
plugins/zio-harness/knowledge/kintex/docs/BACKLOG.md Normal file
View File

@ -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 |

87
plugins/zio-harness/knowledge/kintex/docs/BUILD_DEPLOY.md Normal file
View File

@ -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**: `<kintex-domain>` 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

74
plugins/zio-harness/knowledge/kintex/docs/COMMON_CODES.md Normal file
View File

@ -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·버전).

96
plugins/zio-harness/knowledge/kintex/docs/DESIGN_SYSTEM_NIFTY.md Normal file
View File

@ -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 스타일 학습" 지시 |

130
plugins/zio-harness/knowledge/kintex/docs/DEVELOPMENT_GUIDE.md Normal file
View File

@ -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<T>` = `{ success, data, error }`, 목록 `PageResponse<T>` = `{ 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/<module>-<요약>`, 수정은 `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`

127
plugins/zio-harness/knowledge/kintex/docs/ENV_SETUP.md Normal file
View File

@ -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 <gitea>/zio/kintex.git
cd kintex
# 백엔드 (JDK17)
cd src/backend && ./gradlew build # Phase B-0 스캐폴드 이후
# 프론트 (Node 18+)
cd ../frontend && npm install
# 나노바나나 Python 워커
cd ../../tools/nanobanana
pip install google-genai Pillow
```
---
## 3. PostgreSQL + PostGIS (`kintex_db`)
WISE와 동일하게 **공유 PostgreSQL 인스턴스에 전용 DB + 전용 계정**을 두어 타 솔루션과 물리 분리한다.
```sql
-- 관리자(postgres/sudo) 권한으로 실행
CREATE ROLE kintex LOGIN PASSWORD '<개발용-임시-변경대상>'
NOSUPERUSER NOCREATEDB NOCREATEROLE;
CREATE DATABASE kintex_db OWNER kintex ENCODING 'UTF8';
-- kintex_db 접속 후 PostGIS 활성화
\c kintex_db
CREATE EXTENSION IF NOT EXISTS postgis;
```
- 콜레이션은 서버 인스턴스 컨벤션에 맞춤(WISE는 `en_US.UTF-8`; UTF8이라 한글 저장/조회 정상).
- 스키마/시드는 **Flyway 순번 마이그레이션**(백로그 B-0)으로 적용. `ddl` 수동 검증이 필요하면 `SET ROLE kintex;` 후 마이그 SQL 실행.
- **원격 DB 접속(개발 PC)**: 5432가 외부 차단이면 SSH 로컬 포워딩 —
```bash
ssh -L 5432:localhost:5432 <shell계정>@<db-host> -N
# 앱은 jdbc:postgresql://localhost:5432/kintex_db 로 접속
```
---
## 4. Redis
로컬 기본 포트 6379. 큐 키 예: `kintex:renderjob:queue`(백엔드 발행 → Python 워커 소비). 개발 중 워커 미가동 시 큐잉·상태는 동작(발행까지).
---
## 5. 환경변수 목록 (표준 컨벤션)
> 비밀값은 **하드코딩 금지** — 모두 환경변수/`application.yml` 프로퍼티로 주입. `.env`·`*.key`는 gitignore.
### 5-1. 백엔드(Spring Boot)
| 변수 | 필수 | 설명 |
|------|------|------|
| `KINTEX_DB_PASSWORD` | **필수** | PostgreSQL `kintex` 계정 비밀번호 |
| `KINTEX_JWT_SECRET` | 권장 | JWT HMAC(HS256) 시크릿(최소 32바이트). 미설정 시 개발용 기본값(운영 금지) |
| `SERVER_PORT` | 선택 | 백엔드 포트(운영 포트는 G2 게이트에서 확정 — GUARDiA 인프라와 별개 도메인) |
| `REDIS_HOST` / `REDIS_PORT` | 선택 | 기본 `localhost` / `6379` |
| `RENDER_WORKER_TOKEN` | 워커 연동 시 | `/api/internal/render/callback` 공유 시크릿(`X-Worker-Token`) |
| `ANTHROPIC_API_KEY` | AI(Claude) 사용 시 | Claude 텍스트 AI. 키는 env only — DB/코드/로그/커밋/응답 기록 금지, 실패 시 Ollama 폴백 |
| `ADMIN_PASSWORD_ENC` / `ADMIN_KEY_FILE` | 운영 | admin 비번 AES-256-GCM 암호문 + 별도 키파일(root 600) → 기동 시 BCrypt 재시드 |
| `SMTP_HOST`·`SMTP_PORT`·`SMTP_USERNAME`·`SMTP_PASSWORD`·`KINTEX_MAIL_FROM` | 메일 발송 시 | 2차 인증 EMAIL 코드·알림 발송. 미설정 시 로컬 로그 모드 |
### 5-2. 나노바나나 Python 워커
| 변수 | 필수 | 설명 |
|------|------|------|
| `GEMINI_API_KEY` | 실호출 시(**G1 승인 대상**) | Gemini 이미지 생성 키. **워커에서만** 로드 — 백엔드 미취급, 코드/로그/커밋 금지 |
| `NANOBANANA_MODEL` | 선택 | 기본 `gemini-3.1-flash-image-preview` 오버라이드 |
> **G1 게이트**: Gemini 외부 호출은 소유자 승인 대상. 미승인 시 워커는 목/degraded로 동작(import·구조 성립, 실이미지 미생성).
---
## 6. 실행
```bash
# 백엔드
export KINTEX_DB_PASSWORD='****'
export KINTEX_JWT_SECRET='****-32bytes이상****'
cd src/backend && ./gradlew bootRun # 또는 java -jar build/libs/kintex-*.jar
# 프론트 (개발 서버 — axios baseURL=/api, 프록시로 백엔드 연결)
cd src/frontend && npm run dev
# 나노바나나 워커 (G1 승인 후 실호출; 미승인 시 목)
export GEMINI_API_KEY='****'
python -m tools.nanobanana.worker # 큐 소비 → 콜백(RENDER_WORKER_TOKEN)
```
헬스체크: `GET /health` → `{ "success": true, "data": { "status": "UP", "service": "kintex-backend" } }`.
---
## 7. 참조
- 빌드/배포 개요: [`BUILD_DEPLOY.md`](BUILD_DEPLOY.md)
- 개발 표준: [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md)
- 나노바나나 워커: [`../tools/nanobanana/README.md`](../tools/nanobanana/README.md)
- WISE 세팅 원본(참조): `workspace/uiws/backend/README.md`·`workspace/uiws/db/README_DB연동.md`

432
plugins/zio-harness/knowledge/kintex/docs/FEATURE_BACKLOG_100.md Normal file
View File

@ -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기능·전 화면 횡단 적용 |

160
plugins/zio-harness/knowledge/kintex/docs/FEATURE_GAP_ANALYSIS.md Normal file
View File

@ -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 미수정 |

102
plugins/zio-harness/knowledge/kintex/docs/GUARDIA_ALIGNMENT.md Normal file
View File

@ -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 <JWT>`(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)로 재작성.

100
plugins/zio-harness/knowledge/kintex/docs/IMPLEMENTATION_BACKLOG.md Normal file
View File

@ -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`. 기존 항목 무수정 |

135
plugins/zio-harness/knowledge/kintex/docs/OPS_RUNBOOK.md Normal file
View File

@ -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`

184
plugins/zio-harness/knowledge/kintex/docs/OWNER_FEEDBACK.md Normal file
View File

@ -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회 생성.

1272
plugins/zio-harness/knowledge/kintex/docs/PLANNING.md Normal file
View File

File diff suppressed because it is too large Load Diff

75
plugins/zio-harness/knowledge/kintex/docs/README.md Normal file
View File

@ -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/`)이 정본이며 본 세트에서 생성하지 않는다.

475
plugins/zio-harness/knowledge/kintex/docs/RFP_나라장터_제안요청서.md Normal file
View File

@ -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 |
---
## 문의처 (가안)
| 구분 | 내용 |
|---|---|
| 사업 담당 | (주)킨텍스 ○○팀 (가안) |
| 문의 방법 | 나라장터 질의 게시판(서면 질의 원칙) |
> 본 제안요청서의 해석에 이견이 있는 경우 발주기관의 해석에 따르며, 명시되지 않은 사항은 국가계약법령 및 관련 법규를 준용한다.

70
plugins/zio-harness/knowledge/kintex/docs/SECURITY.md Normal file
View File

@ -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·미등록업체 차단 동작

94
plugins/zio-harness/knowledge/kintex/docs/UNDEVELOPED_BACKLOG.md Normal file
View File

@ -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·대형 트랙·도메인·티켓·게이트) |

109
plugins/zio-harness/knowledge/kintex/docs/WORK_STATUS.md Normal file
View File

@ -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 `<script>` XML 이스케이프(2026-07-12 부팅 크래시)**: 어노테이션 SQL의 `<script>` 블록 안에 이스케이프 안 된 `<`/`<=` 비교연산이 있으면 SAX 파싱 실패 → 매퍼 빈 생성 실패 → **부팅 크래시 루프 → 헬스 게이트 롤백**. compileJava·일반 단위테스트로는 안 잡힘. `&lt;=`로 이스케이프하거나 비교를 뒤집어라(`now() > a.deadline`). 회귀 가드 = `MapperAnnotationParseTest`(전 @Mapper 어노테이션 SQL 파싱, DB 불필요).
- **배포 로그 판독**: deploy_server journal의 "ERROR ... 실패: [deploy-kintex] 프론트 빌드 시작"은 stderr 오기록으로 **성공 배포에도 찍힘** — 성패는 소요시간(실패≈12s/성공≈3min)과 jar mtime·ActiveEnterTimestamp로 판정.
- deploy_server 웹훅 로그는 실패 stderr를 잘라 기록 — 실제 에러는 서버 `/opt/kintex/src`에서 빌드 재현으로 확보.
- **2FA 운영 게이트**: admin 등 필수 역할은 최초 로그인 시 `OTP_ENROLL`(웹 UI에서 QR 등록 필요). 운영 배포 전 `KINTEX_OTP_ENC_KEY`(base64 32B) env 주입 필수(미주입 시 개발 파생키). 레거시 `/api/auth/login`은 secureLogin 위임 — OTP 대상은 401 OTP_REQUIRED(모바일은 2FA 플로우 채택 필요).
- dev DB에 E2E 테스트 계정 `qa-e2e-visitor@kintex.zioinfo.co.kr`(VISITOR) 존재 — 운영 이관 시 제거.
- git 대용량(CAD·PNG·build)로 커밋/푸시 느림 → 특정 경로 add + push 재시도. CAD/build/node_modules gitignore.
- 로컬 `vite build`는 win32 rollup 크래시 가능 → **서버 빌드 신뢰**(tsc 통과로 검증).
- 서버 `/opt/zioinfo/deploy_server.py`(kintex 블록)·`/opt/kintex/` 수정 시 반영+재시작.
- 보안 불변: 외부API 금지(Claude·Gemini 예외)·자격증명 미노출·AI 이미지 워터마크·admin env 시더.
## 8. 변경 이력 (이 문서)
| 일자 | 갱신 |
|---|---|
| 2026-07-11 | 최초 작성 — 요구사항 27건·현황·남은 큐·함정 |
| 2026-07-11 | 신규 5화면(SCR-13~17) 구현 완료 반영 + 미개발 통합 백로그 `UNDEVELOPED_BACKLOG.md` 신설·연결 |
| 2026-07-11 | 모바일 트랙 하네스 신설(kintex-mobile-dev + kintex-mobile-orchestrator, WISE 모바일 레퍼런스·Stitch 디자인 경유·G3 EAS 게이트) + 웹 WISE 기능 레퍼런스 강화(kintex-frontend-dev·impl-orchestrator) |
| 2026-07-12 | **제안서.pptx 완성**(나라장터 표준 7대장·97슬라이드·RTM 142/142 QA 승인·화면갤러리 19시안) + 산출물 7종 전체 완성(개발계획서·지침서3·프로그램사양서·DA·사업수행계획서). PLANNING v3.1(계정통합·앱 2타깃)·design v2.1(84화면)·백로그 Phase F. Stitch 신규 24/64 확보(웹코어 트랙 진행·실패 12건은 서비스 저하 — 재시도 예약). 재생성: deliverables/제안서/_gen/build_deck.py |
| 2026-07-12 | **Stitch 잔여 39화면 미확보 — 서비스 저하로 보류.** 확보 25/64(모바일 M4~M14·관리자 A1~A4/A7/A10·공개 P8·웹코어 18~21/24/28/31). 잔여: 웹코어 22/23/25~27/29/30/32~51(27)·관리자 A5/A6/A8/A9(4)·공개 P1~P7(7)·모바일 M15(1). generate 타임아웃 지속+list_screens 스테일(구 27건 고정). **회복 후 재실행 절차 = `_workspace/stitch_gen/harvest_report.md`**(수확 패스→재생성, 연속 3타임아웃 시 중단 규칙). Stitch 웹 UI(프로젝트 9385904003821333054) 육안 확인 권장. 부수: 로그인 슬라이드 CMS·RFP·보고서 4종 커밋(1de3b9b) |
| 2026-07-12 | **Stitch 전 화면 확보 완료(64/64)** — 서비스 회복 후 수확 패스 재실행: 잔여 39화면 전부 서버측 지연 생성 완료 상태(프로젝트 27→155 화면)로 재생성 0회·다운로드 43파일(보조 변형 5 포함: P4 3단계·P7 예매확인·M15 권종선택) 실패 0. `_workspace/stitch_gen/{harvest2.py,screen_titles.txt,harvest_report.md}`. 다음: frontend/mobile dev 이식 + design.md 🔲미생성 마커 갱신(designer 경유) |
| 2026-07-12 | **실데이터·2FA 트랙 마감** — ①실데이터 집계 API 5패키지(analytics·dashboard·ops·admin·catalog + V13 인덱스) ②TOTP 2FA 완결(SecretCipher AES-256-GCM·V12·OtpChallengePanel/OtpSetupPage·OTP_ENFORCE env) ③공통 업무기능 SCR-39~48 화면(`screens/work/`) 배선 ④M2 부스 겹침 검사(BOOTH_OVERLAP·compliance-v1.1) + 단위테스트 3종. 검증: backend compileJava+test·frontend tsc 통과, QA PASS(blocker/major 0, minor 2=RIGGING_RANGE semantics 소유자 결정 대기·운영 KINTEX_OTP_ENC_KEY 주입 게이트 — `_workspace/09_qa_track_close.md`). 계약 갭 기록: `_workspace/{07_work_api_gaps,08_m2m5_contract_changes}.md` |
| 2026-07-12 | **Stitch 확보 화면 이식 완료(웹 24 + 공개 7단계플로우 + 모바일 1)** — 에이전트 7팀 병렬(폴더 소유권 분리·공유파일 통합자 단일 배선). ①도메인: SCR-22/23/25(서류·신고서류·도크, M6/M8 샘플)·SCR-26/27/29/38(옥션 3종+수주 대시보드, M15 샘플, 봉인입찰 마스킹·등록업체만 응찰 UI)·SCR-30/32/33/34(관람객·리드·EDM·스폰서십, M10/M12 샘플, PII 마스킹)·SCR-35/36/37(CMS 3종, M17 샘플) ②관리자: **A5 감사로그·A6 시스템설정 = 라이브 백엔드 실배선**(PageResponse·시크릿 마스킹), A8 룰셋(정적 v1.1 스냅샷)·A9 테넌트(샘플) ③공개: P1~P7 자체 PublicShell(비인증 /public/*·/tickets/*, PG위임 고지) ④모바일: M15 티켓지갑(mobile/app/tickets, QR placeholder) ⑤통합: App 라우트 18종+AppShell "도메인 모듈" 네비. tsc -b EXIT 0·QA PASS(minor 2 코스메틱: kx-field 접두, ★/✓ 글리프). 각 팀 API 계약 초안 = `_workspace/port_*.md`. 커밋 becbc55 |
| 2026-07-12 | **10~12차 웨이브 + 리뉴얼 1차 체크포인트** — ①W10 이메일 채널(자체 Postfix 로컬 제출 — 소유자 승인·env 프로비저닝: 옥션 개설 공사업체 인앱+이메일 통지·EDM 발송(수신동의·상한500)·비번 재설정 메일·mail_log V36) ②W11 WISE 셸 정렬(소유자 지적 9건: 햄버거·단일펼침 아코디언·6그룹 IA 재구성·시스템관리 그룹·KINTEX CI 워드마크 로고·홈 차트 3종·하단 반응형·캘린더 정합·goScoped 링크수정(/login 폴백 제거·홀 파싱)) ③W12 시스템관리 기본기 8종(UIWS 40+ 대비 누락 지적 — 조직dept/company·프로그램·역할메뉴맵·인증정책·로그인이력·오류로그·시스템상태·메일/알림설정, V37·라우트 10종) ④제품 아이덴티티(지적 "뭐하는 사이트인지 모르겠다" — 공개 랜딩 제품 히어로+역할카드4+AI 파이프라인 스텝·로그인 태그라인·루트 분기 미인증→/public) ⑤홈 AI 허브(지적 "AI가 어디 있냐" — AI 도구 카드 5+자연어 퀵 입력) ⑥메뉴 IA 정합(누락 13종 편입·시스템관리 5소그룹·dead 0 — kintex-menu-recompose 절차) ⑦모바일 QR 페이지(/app-qr — WISE AppQrCode, EAS G3 승인·빌드 진행) ⑧제품명 확정 "KINTEX AI 전시·행사시스템"(4개 로케일 스윕) ⑨V38 데모 폐루프 시드(공통코드30·프로그램75·부서15·회사16·부스12·리드15·결재5·청구8·데모계정4 — 홈 todos/KPI 활성) ⑩SPA 캐시 정책(index.html no-store — 배포 반영 즉시). **신규 하네스 3종**: wise-ui 정렬(+menu-ia)·전면 리뉴얼(testdata)·벤치마킹(analyst·crawler). COEX 분석→3-트랙(visitor/business/agency) 기획 완료(PLANNING v3.2·신규 4화면 Stitch 진행) |
| 2026-07-12 | **8·9차 웨이브(100대 기능 8종) + ★SCR-HOME 메인 홈 + 테넌트 표준 + 크롤 적재** — ①**SCR-HOME**(소유자 지시: 홈 없음 지적→design.md v2.1.2 확정판·Stitch 시안(프로젝트 정리 후 생성 성공, scr_home/) 정합): `/home` 랜딩(로그인→홈 전환·워크스페이스 선택 흡수)=역할별 KPI+배너 캐러셀+**전시 포스터 쇼케이스**+WISE 월캘린더(홀센터 동적 필터)+**역할별 내 할 일**+공지/빠른작업/활동+워크스페이스 그리드+ShellFooter+`/api/home/{todos,showcase,hall-centers,summary}` ②**테넌트 표준(소유자 지시)**: ten_id='KINTEX'(V31 재명명·코드 정규화·JWT 하위호환)+**tenant_id 선두 복합 PK**(V31 전환+V27/29/30/33/34/35 신규분 표준 적용) ③크롤: kintex.com 전시 34건+포스터+상세(주최·홈페이지·품목·소개, V32) ④W8: F100 AI라우터(Claude→Ollama 폴백·AiConfig)+F051 리드AI재계산+CMS AI번역 실배선·F005/6 부스판매(V27·원자 hold)·F035 BOQ+F084 옥션수수료 정산(V28)·F028 전자결재(V29·결재함 실배선·/work/approval) ⑤W9: F041/42/43 물류4탭(V33)·F085 환불룰(refund-v1.0)+F083 세금계산서·리포트(V34·G2 게이트)·F092 Text-to-SQL(7단계 가드·PII차단)+F025 규정챗봇·F099 웹훅(HMAC 인바운드·아웃바운드 스텁)+F052 팔로업EDM 트리거(V35). 검증: compileJava·test·tsc·vite 전부 EXIT 0. 잔여 게이트: PG/국세청/실발송(G2)·공사업체 통지 이메일(Postfix 승인 대기) |
| 2026-07-12 | **7차 웨이브(MDI+테넌시2단계+i18n 스윕2)** — ①MDI 셸: 탭 문서 바(`MdiTabBar`+`mdiStore` sessionStorage·라우트 동기화·dedup·MAX 10·키보드 접근성·다크 토큰) 순증 레이어 — 잔여: DocumentHost 상태 보존(§2.7-3)·드래그 재정렬 ②테넌시 2단계: JWT `tid` 클레임(하위호환 폴백)·`EventAccessGuard` 테넌트 fail-closed(교차 테넌트 403 — `EventTenantMapper`+격리 테스트 3종)·전역 집계(analytics/admin/sysuser) 명시 스코핑 — company·audit_log는 Phase 3 후보 ③i18n 스윕2: 코어+admin 17화면·네임스페이스 30종(4개 언어) — 잔여 P2(도메인 모듈·work 공통)·P3(공유 ui) 목록=_workspace/impl_i18n_sweep2.md. 검증: tsc·vite·compileJava·test(75개) 전부 EXIT 0 |
| 2026-07-12 | **5·6차 웨이브(NFR+멀티테넌시) + 운영 도메인 라이브** — ①W5-1 다크테마(global.css `--dk-*`→`[data-theme=dark]` remap·시스템 선호 폴백·themeStore(localStorage)·AppShell 토글·공유 CSS 하드코딩 hex 토큰화·focus-ring/reduced-motion/스킵링크) ②W5-2 i18n(react-i18next ko/en/zh/ja·공개 P1~P7+로그인/가입/비번찾기 전 문구·LanguageSwitcher(공개셸+로그인+AppShell 배선)·fallback ko) ③W6 멀티테넌시 1단계(V26 tenant 마스터+event/hall/app_user tenant_id 순증·TenantContextFilter(X-Tenant-Id→Host→kintex)·catalog/hall 스코핑·`/api/admin/tenants` GET/POST 실배선 — 회귀 0) ④**운영 도메인 https://kintex.wise.ai.kr 라이브**(위 §2 참조). 검증: tsc·vite·compileJava·test 전부 EXIT 0 |
| 2026-07-12 | **4차 웨이브(백로그 4트랙) + ★OTP 로그인 루프 라이브 장애 수정** — ①**OTP 장애**(사용자 보고 "로그인 후 메인화면 안 나옴"): `verifyOtp`/`enrollVerify`가 코드 검증 **전에** 챌린지를 소비 → 오입력 1회면 이후 정답도 "세션 만료" 루프. 수정=성공 시에만 소비+실패 5회 한도(`OtpChallengeStore.recordFailure`)+`OtpChallengeStoreTest` ②SCR-14 현장운영 실전환(혼잡=체크인 파생·전력=utility 부하, IoT는 "센서 미연동" 정직 표기) ③M9 정산 신설(`/api/settlement`·V24 invoice/invoice_payment·`/settlement` 화면, ST_Area×요율+VAT 서버 권위·PG위임) ④M1 홀배정+자동견적(`/api/halls`·V25 기간 컬럼 순증·충돌 409+상세·rates-v1.0 견적·`/halls` 화면) ⑤공유 레이어: AuthUser.roleCode 순증 노출(JWT `rc` 클레임)+AdminGuard 정밀화+AppShell 플레이스홀더 네비 전량 배선(행사 컨텍스트 계산 경로)+`/_styleguide` prod 제외. 검증: compileJava·test·tsc -b --force·vite build 전부 EXIT 0 |
| 2026-07-12 | **3차 웨이브(백로그 3트랙) + 배포 크래시 근본수정** — ①크래시 규명: c6f3a8d jar가 MyBatis `<script>` XML 위반(AuctionMapper `deadline < now()`·VisitorMapper `<=`)으로 부팅 크래시 루프→롤백. 매퍼 교정 + `MapperAnnotationParseTest` 회귀 가드 + `checkin.css` 누락 작성(서버 프론트 빌드 실패 원인) ②M16 BI 전역: `GET /api/analytics/overview`(행사 간 매출·홀 가동률 추이·리텐션·선형회귀 예측, 홀매니저 전용, 마이그레이션 無) + /analytics 인라인 섹션 ③M18 관리자: 사용자·역할/권한·공통코드·메뉴 CRUD 화면 4종(백엔드 system 라이브 소비, 신규 백엔드 0)+`AdminGuard`(전 /admin/* 라우트 가드 배선)+랜딩 모듈 바로가기. A8 룰셋은 기왕 실배선 확인 ④SCR-15 일정: V23(category·est_visitors 백필 1,098건)+홀 가동률/캘린더 API 2종+실 전환 ⑤QA minor: ✓글리프 SVG화(kx-field·★는 기왕 해소). 검증: compileJava·test(매퍼 파싱 포함)·tsc -b --force·vite build 전부 EXIT 0. ⚠AdminGuard 판정 한계: 전역 role_code 미노출로 hallManager 기준 — 정확 판정은 AuthUser.roleCode 노출 필요(후속) |
| 2026-07-12 | **도메인 2차 웨이브(중단분 복구·마감)** — 중단됐던 미커밋 웨이브 완성: ①M15 옥션 실배선 고도화(`screens/auction/auctionApi.ts` 정본 + 스코어링·견적계산 단위테스트) ②M10 체크인 데스크(SCR-31, `/visitors/checkin` 라우트·네비 신규 배선, QR 토큰·checkin_at·리드 exhibitor_id/동의/메모 확장, 체크인/검색/통계/배지재발급/리드생성/CSV export API — 마스킹·RBAC·@Audited) + 룰기반 리드 스코어링 엔진(`visitor/scoring`) ③M17 CMS 버전 이력·미디어 라이브러리·공개 CMS API(`/api/public/cms`)·HtmlSanitizer ④단위테스트 7종. **★Flyway 수복: 이미 배포된 V17/V19에 append돼 있던 확장 SQL을 V21로 분리·원복**(체크섬 불일치 배포실패 예방). 검증: compileJava·test·tsc -b 전부 EXIT 0. ⚠고아 초안 `src/api/auction{Api,Types}.ts` 2파일은 화면 미사용(정본은 screens/auction 로컬) — 삭제는 소유자 확인 필요 규칙상 **미커밋·보류** |
| 2026-07-12 | **배포·핫픽스 3건 + 풀 E2E 라이브 검증 완료** — 1차 push는 서버 `tsc -b` 실패로 프론트 미배포(로컬 `--noEmit`과 설정 차이): ①toast 미렌더+TS6133·recharts formatter 타입 수정(8509787) ②레거시 `/api/auth/login`이 잠금·OTP 강제를 우회하던 보안 구멍 → secureLogin 위임(a657f95) ③**PG 별칭 소문자 폴딩으로 Map 매퍼 22파일·191별칭 전부 런타임 null이던 결함 → `AS "alias"` 일괄 교정(89bf2ce)** — login-slides imageUrl null(01:08부터)·secure 로그인 전멸이 이것. E2E 확인: secure 로그인 admin=OTP_ENROLL+챌린지(시크릿 미누출)·레거시=401 차단·visitor 가입→로그인→카탈로그 78건 실데이터·admin API 403 RBAC·Flyway V12/V13 적용·신규 번들 라이브. design.md v2.1.1(Stitch 84화면 상태 정합·designer 경유) |

134
plugins/zio-harness/knowledge/kintex/docs/analysis/coex-website.md Normal file
View File

@ -0,0 +1,134 @@
# 코엑스(COEX) 웹사이트 분석
> 분석일: 2026-07-12 · 대상: https://www.coex.co.kr/ (VISITOR), https://business.coex.co.kr/ (BUSINESS), cybercoex.co.kr / exhibitor.cybercoex.co.kr (참가업체 온라인신청)
> 목적: 코엑스의 방문자 유형별 정보구조(IA) 분석 → 킨텍스 자동전시시스템 **대외 접점 3-트랙(visitor/business/agency) 재구성** 근거 확보 (PLANNING §2-2)
> 방법: WebFetch(3 사이트 IA 크롤) + WebSearch 보조. 로그인·신청 상세는 접근 불가로 검색 결과로 보강.
---
## 0. 핵심 발견 — 코엑스는 방문자 유형별로 "사이트 자체"를 3개로 분리한다
코엑스 IA의 결정적 특징은 **메뉴 분기가 아니라 사이트(도메인) 분기**라는 점이다. 킨텍스가 단일 사이트(kintex.com) 안에서 정보·서식을 제공하는 것과 대비된다.
| 사이트 | 도메인 | 1차 대상 | 성격 |
|---|---|---|---|
| **VISITOR** | `www.coex.co.kr` | 관람객·일반 대중 | 방문 전/중 편의·행사 탐색 (마케팅·안내 톤) |
| **BUSINESS** | `business.coex.co.kr` | 전시주최자·임차인·(협력사) | 대관·임대·시설 규격·협력사·안전 (B2B 실무 톤) |
| **CYBER(참가신청)** | `cybercoex.co.kr` / `exhibitor.cybercoex.co.kr` | 참가업체 | 부스+부대시설 온라인 신청·결제 (트랜잭션 톤) |
이 3분할은 소유자가 지시한 **visitor / business / agency** 3-트랙과 거의 1:1로 대응한다(§4 대비표). 즉 코엑스는 이미 "누가 오느냐"로 진입점을 물리적으로 갈라 놓았고, 이는 킨텍스 시스템 재구성의 실증 레퍼런스가 된다.
---
## 1. VISITOR 사이트 (www.coex.co.kr) — 관람객·일반 대중
### 1-1. GNB 구조
- **40th Anniversary** — 창립 40주년 캠페인(브랜드 히어로)
- **행사** — 전시/컨퍼런스 일정 (진행중 30개 카드형, 티켓오픈 3개 하이라이트, Convention/Exhibition 카테고리, 일정·홈페이지·예약링크)
- **가이드(Guide)** — 방문객 편의 정보(§1-2)
- **하이라이트** — 주요 콘텐츠/기획
- **안전경영** — 경영방침·신고(공용)
- **Coex 소개** — 회사정보·채용·MICE 클러스터
- **Business** — 외부 링크(business.coex.co.kr로 이탈)
- **마곡 컨벤션센터** — 별도 시설 링크
### 1-2. 가이드(Guide) — 방문객 여정의 핵심
| 하위 메뉴 | 제공 정보 | 방문 시점 |
|---|---|---|
| **오시는 길** | 지하철(2/7/9호선)·버스 6개 정류장·승용차 7개 경로·자전거 등 교통수단별 상세 | 방문 전 |
| **주차안내** | 옥상·지하주차장 진입로, 건물별 게이트, 요금·위치 | 방문 전 |
| **편의시설** | 층별 편의 서비스(식음·쇼핑·시설) | 방문 전/중 |
| **실내 길찾기(실내 네비게이션)** | 광활한 코엑스 내부 목적지 탐색(wayfinding) | 방문 중 |
| **Coex VR** | 가상현실 사전 답사/현장 활용 | 방문 전/중 |
| **알림마당** | 공지사항·입찰공고 | 조회 |
| **고객문의** | 문의 접수 | 조회 |
| **뉴스** | 최신 소식 | 조회 |
- **접근성**: "수어 통역 서비스 제공" 명시 — 접근성을 방문안내 전면에 노출.
- **맞춤 알림**: 관심분야 선택 후 휴대폰 기반 맞춤 알림(관람객 리텐션 장치).
### 1-3. Family Site / 커머스 연계
CoexMall(쇼핑몰), KITA, WTC Seoul, KTNET, CALT, Coex VINA, COEX STORE 등 — 전시장을 넘어선 복합 MICE·리테일 생태계 링크.
---
## 2. BUSINESS 사이트 (business.coex.co.kr) — 주최자·임차인·협력사
### 2-1. GNB 구조
| 최상위 | 하위 |
|---|---|
| **전시/컨벤션** | 사업소개·주최전시회(26개 참가사 모집중)·컨벤션·해외사업(베트남·인니 등 8개) |
| **전시장** | 시설안내·임대절차및상담·임대관련자료(신청서및신고서/안내자료/도면)·임대비용·**서비스협력업체** |
| **회의실** | 시설안내·임대절차·임대관련자료·코엑스 스토어·**서비스협력업체** |
| **광장/로비** | 시설안내·이용절차·이용관련자료 |
| **베뉴서비스** | 이벤트·F&B·광고·촬영 |
| **가이드** | 주차·편의시설·고객문의·VR투어 (VISITOR 가이드 재노출) |
| **안전경영** | 경영방침·목표·실천강령·**온라인작업신고** |
| **Coex 소개** | 회사정보·연혁·조직도·채용·**MICE클러스터** |
### 2-2. 대상별 정보 배치 (BUSINESS 사이트 내부에서 다시 3자 구분)
- **전시주최자/임차인**: 전시장 > 임대절차및상담 → 시설규격(Hall A 10,368㎡·520부스 / Hall B 7,290㎡·360부스 / Hall C 10,348㎡ / Hall D 7,000명) → 임대비용 → 임대관련자료(신청서·신고서·도면). 대관 신청→서류→도면→요금 단계별 제공.
- **참가업체**: 각 전시회별 독립 신청 페이지 링크(외부 EMS = cybercoex 연동) + "회사 로그인". 즉 참가업체는 BUSINESS에서 정보만 보고, **신청은 CYBER로 이관**.
- **시공/협력업체**: 전시장·회의실 > **서비스협력업체**(공식 협력사 리스트) + 안전경영 > **온라인작업신고**(현장 작업 신고 = 킨텍스 kxwp에 해당) + 임직원 안전실천강령. → 협력사는 별도 사이트 없이 **BUSINESS 하위 + 안전경영 신고 시스템**에 얹혀 있다.
### 2-3. 시사점
코엑스는 **agency(협력사·시공)를 독립 트랙으로 완전 분리하지 않고** BUSINESS 사이트 하위(협력업체 리스트) + 안전경영(작업신고)로 배치했다. 반면 킨텍스는 독립부스 시공에 **등록 장치업체 필수(739개·14분류)**·리깅 구조계산서·규정 반려 리스크가 커서, 킨텍스 도메인에서는 agency를 **독립 트랙**으로 세우는 것이 정당화된다(§4 권고).
---
## 3. CYBER 참가신청 (cybercoex.co.kr / exhibitor.cybercoex.co.kr) — 참가업체 트랜잭션
> 직접 크롤 불가(로그인 기반) — WebSearch 결과로 재구성.
- **위치**: 서울 강남구 영동대로 513(삼성동 COEX). 참가업체 부스+부대시설 온라인 신청/지원 시스템.
- **신청 흐름**(검색 결과 기준):
1. `cybercoex.co.kr` **로그인** → 참가신청(각 전시회별 `exhibitor.cybercoex.co.kr/exhibition/{host}/{year}/{id}` 딥링크)
2. **부스비 30%** 청구서 발행일로부터 7일 내 납부
3. **부대시설 신청**(전기 등) + 각종 신고서(출입증 등) 제출
4. **잔금 70%** + 추가 비용 납부
- **성격**: 부스와 부대시설(전기·급배수·인터넷 등)을 **온라인으로 신청·결제**하는 트랜잭션 시스템. 킨텍스가 "전시회별 주최자 사무국 시스템(코리아팩 등)으로 파편화"된 것과 달리, 코엑스는 **cybercoex 공통 플랫폼**으로 참가업체 신청을 일원화했다(킨텍스 대비 코엑스의 강점).
---
## 4. 킨텍스(kintex.com) 대비표
| 축 | 코엑스(COEX) | 킨텍스(KINTEX) | 시스템 재구성 시사점 |
|---|---|---|---|
| **진입점 분리** | **사이트 3분할**(visitor/business/cyber 도메인) | 단일 사이트(kintex.com), 주최자 랜딩(index_organizer) 정도만 분기 | 킨텍스 시스템은 코엑스식 **트랙 분리**로 IA를 재편(소유자 지시) |
| **관람객(visitor)** | VISITOR 사이트 + 가이드(길찾기·주차·VR·알림) + 맞춤 알림 | 행사일정 검색·교통·주차(iparking) 수준, 관람객 전용 IA 약함 | visitor 트랙에 wayfinding·티켓·배지·맞춤알림 강화(코엑스 차용) |
| **주최자(business)** | BUSINESS 사이트, 임대절차·규격·요금·도면 단계별 | HWP 배정신청서·임대요율표 다운로드 중심 | business 트랙에 M1 자동견적·M2 배치·M6 서류 얹기 |
| **참가업체 신청** | **cybercoex 공통 플랫폼**(부스+부대시설 온라인·결제 일원화) | **전시회별 주최자 사무국 시스템으로 파편화**(공통 플랫폼 부재 = 최대 공백) | business 트랙 참가업체 e-서비스가 킨텍스 최대 차별화 여지 |
| **협력사(agency)** | BUSINESS 하위 협력업체 + 안전경영 온라인작업신고(독립 트랙 아님) | 등록업체 DB(739개·14분류) + kxwp 작업신고. **독립부스 등록업체 시공 필수** | 킨텍스는 agency를 **독립 트랙**으로(등록업체 검증·옥션·시공 — 코엑스보다 강함) |
| **협력사 강제성** | 협력사 리스트 안내 수준 | **미등록 업체 시공 엄금·자체시공 불가** | agency 트랙 = 등록업체 검증 게이트 + M15 옥션의 자연스러운 근거 |
| **온라인 작업신고** | 안전경영 > 온라인작업신고 | kxwp.kintex.com / kxfp.kintex.com | agency 트랙에서 도면제출·규정검증·작업신고 통합 |
| **시설 규격 공개** | Hall A~D ㎡·부스수·수용인원 공개 | 홀1~10 실측(63×171m·5t/㎡·600부스 등) 공개 | 양사 모두 규격 공개 → 자동 배치·견적 가능 |
| **커머스/부대사업** | CoexMall·STORE·F&B·광고·촬영 등 리테일 강함 | 부대시설(뽀로로파크·PBA·연회)·오피스·로케이션·광고 | visitor 트랙 부대서비스 안내로 흡수 가능(P2) |
| **맞춤 알림** | 관심분야 기반 휴대폰 알림 | 없음 | visitor 트랙 리텐션(M10·M12)에 반영 |
| **접근성** | 수어 통역 전면 노출 | 명시 약함 | visitor 트랙 접근성 고지 강화 |
---
## 5. 3-트랙 재구성에 차용할 코엑스 요소 (요약)
1. **진입점의 물리적 분리** — 랜딩에서 visitor/business/agency로 명확히 갈라 각 서브홈으로 보낸다(코엑스의 3-사이트 = 킨텍스의 3-트랙).
2. **visitor 트랙 = "가이드" 허브** — 오시는 길·주차·실내 길찾기·VR·편의시설·알림마당·문의를 한 곳에(코엑스 가이드 구조). 맞춤 알림·접근성 명시.
3. **business 트랙의 단계별 실무 흐름** — 임대절차→시설규격→요금→서류/도면(코엑스 전시장 메뉴) 위에 킨텍스 M1 자동견적·M2 배치·M6 서류를 얹는다.
4. **참가업체 신청 일원화** — 코엑스 cybercoex처럼 킨텍스의 파편화된 참가업체 신청을 business 트랙 공통 e-서비스로 통합(부스+유틸리티+결제).
5. **agency 트랙 = 협력사 + 작업신고 통합, 단 킨텍스는 독립 트랙으로 승격** — 코엑스는 BUSINESS 하위에 뒀지만, 킨텍스의 등록업체 필수·옥션 도메인은 독립 트랙(등록업체 검증·M15 옥션·시공 대시보드)을 정당화한다.
---
## 6. 분석한 URL 목록
- 정상 분석: `www.coex.co.kr`(VISITOR 메인), `www.coex.co.kr/guide/`(가이드), `business.coex.co.kr`(BUSINESS 메인)
- 검색 보조: `cybercoex.co.kr` / `exhibitor.cybercoex.co.kr`(참가업체 신청 — 로그인 기반, 직접 크롤 불가), `coexstore.co.kr`·`coexworld.co.kr`(부대/패밀리)
- 접근 불가: cybercoex 로그인 내부, 각 전시회 신청 상세
## 출처
- [코엑스 VISITOR](https://www.coex.co.kr/)
- [코엑스 가이드](https://www.coex.co.kr/guide/)
- [코엑스 BUSINESS](https://business.coex.co.kr/)
- [참가업체 전시부스 온라인신청 (cybercoex)](https://www.cybercoex.co.kr/)
- [exhibitor.cybercoex 참가신청 예시](https://exhibitor.cybercoex.co.kr/exhibition/100/2022/1235)
- [COEX STORE](https://www.coexstore.co.kr/)
</content>
</invoke>

92
plugins/zio-harness/knowledge/kintex/docs/analysis/kintex-website.md Normal file
View File

@ -0,0 +1,92 @@
# 킨텍스 웹사이트 분석
> 분석일: 2026-07-11 · 대상: https://www.kintex.com/web/ko/index.do 및 하위 25개 페이지, 전시주최자매뉴얼 PDF, 참가업체 매뉴얼 PDF
## 1. 사이트 구조 (메뉴 트리)
메인: `https://www.kintex.com/web/ko/index.do` (영문판 `/web/en/index.do`, 주최자 전용 랜딩 `/web/ko/index_organizer.do`)
- **행사안내** — `/web/ko/event/clist.do` (캘린더/리스트 뷰)
- 전체 일정 / 전시 일정(`?searchType=11`) / 회의 일정(`?searchType=23`) / 문화행사(`?searchType=12`) / 기타 행사(`?searchType=D`)
- **시설안내**
- 전시홀: 시설개요, 1전시장, 2전시장, 임대문의, 임대료
- 회의실: 시설개요, 임대문의, 1/2전시장 회의실, 임대료
- 킨텍스타워(오피스): 개요, 임대절차, 임대료, 공실현황
- 부대시설: 상설전시장, 로케이션(촬영장소 임대), 연회서비스, 광고시설
- 등록업체: `/web/ko/facility/ccpy/list.do` (지정·등록 협력업체 739개 DB)
- **이용안내**: 편의시설, 지원시설, 교통안내, 주차안내, 공식제휴호텔, 관광안내
- **홍보센터**: 공지사항(852건), 홍보자료, 고객만족센터, 고객의소리, CSR
- **열린경영**: 개요, CEO 인사말, ESG, 경영공시, 조직도, 위치안내
- **외부 연동**: VR 투어(K-MICE), 고양 MICE 인큐베이션센터
특징: 공식 웹사이트는 사실상 **정보 제공 + 서식(HWP/PDF) 다운로드 중심**이며, 참가업체 전용 GNB 메뉴는 없음. 주최자 중심 구조.
## 2. 핵심 비즈니스 도메인 및 프로세스
### 2-1. 주최자(Organizer) 여정 — 전시장 임대
1. **행사준비** (사용개시 150일~14일 전, 인기 행사는 1~2년 전 접수): 사용문의 → **전시홀 배정신청서**(HWP 양식) 방문/온라인 제출 → 배정협의 → 견적요청·확인
2. **계약·결제**: 사용신청 서류 제출 → 계약체결 안내공문 → 계약서 작성 + 계약금 20% → 1차 중도금 30% → 2차 중도금 20% → 잔금 30% + 관리비 예치금(임대료의 15~20%)
3. **행사개최준비**: **홀매니저 배정** 후 사전업무협의(장치, 홍보, 로비사용, 보안 등 D-30까지 협의 완료), 각종 신고서류 제출(D-7 기한) — 행사운영계획서, 부스배치도, 재해대처계획서, 방화관리 책임서약서, 주차관리 신청서, 보안요원 배치계획, 위험물 반입신고서 등. 온라인 접수는 `https://kxwp.kintex.com` ID/PW 로그인 후 업로드
4. **행사개최**: 보도자료·디렉토리 제출
5. **종료 후 정산**: 폐기물 처리비·전기사용료 등 관리비 정산, 세금계산서 수령
- 반홀 단위 계약 가능(예: 5A홀). 담당자 분업: 산업재/정부, 소비재, 컨벤션, 문화행사(장/단기), 홀매니징(행사지원팀)
### 2-2. 참가업체(Exhibitor) 여정
- 부스 유형: **조립부스**(주최측 기본 구조 + 간판/가구/조명 옵션 신청) vs **독립부스**(킨텍스 **등록 장치업체 필수**, 미등록 업체 시공 엄금, 자체시공 원칙 불가)
- 독립부스 장치공사: 평면도·입면도·조감도·**전기도면**을 온라인 작업신고 사이트에 제출. 구조 규정 — 높이 5m 이하, 리깅은 천장 6.5~8.5m + **구조계산서 D-7 제출**, 복층은 1/2 이내, 전 자재 방염 필수. 장내 전기톱·용접·페인트 작업 금지
- **유틸리티 신청** (바닥 트렌치 공급: 전기·급배수·압축공기·전화·인터넷·일부 가스):
- 전기: 220V 단상 1kW 55,000원, 분전반 50A 추가 100,000원 수준. 마감 약 D-25, 공급은 장치 마지막 날 오후
- 압축공기(내경 8mm) 150,000원/구, 급배수(급수15mm/배수25mm) 150,000원/구 — **시공 위치표시도 온라인 등록 필수**
- 인터넷 유선 150,000원/회선(KT 경유 회선당 80,000원 안내도 존재), 현장 추가신청 불가
- **반입/반출**: 하역장·화물출입구 이용 필수, 중량물(5t 이상) 우선 반입, 철거 시 화물차 순번제·통행증, 지게차는 지정업체 사전신청(유료), 적재물 방치 시 즉시 폐기
- 안전: 장치·철거기간 안전모 필수, 소음 70~75dB 제한(초과 시 전기공급 중단), 가스 반입 원칙 금지
### 2-3. 관람객(Visitor) 여정
행사일정 검색 → 교통(GTX-A 킨텍스역 도보 3분, 지하철/버스/KTX) → 주차(전용 4,200면+임시 4,000면, iparking 결제, 사전무인정산) → 편의시설(식음 40여 개소, 뽀로로파크·PBA스타디움·곤충박물관·갤러리네오 등 상설시설) → 제휴호텔·관광
### 2-4. 기타 사업
킨텍스타워 오피스 임대(70여 실, 62~250㎡), 로케이션(방송·영화 촬영지) 임대, 광고시설(LED 스크린, 현수막, 라이트박스, 랩핑, 천정배너) 임대, 연회·케이터링(한화호텔앤드리조트 '그래머시' 위탁), 자체 브랜드 전시회 개최 사업
## 3. 시설/인프라 스펙
- **총 전시면적 108,011㎡ (국내 최대)** / 2028년 제3전시장 완공 시 총 178,000㎡ (세계 20위권 목표)
- **1전시장**: 홀 1~5 (5개 홀), 53,541㎡ + 옥외 2,849㎡
- 홀당 10,611~10,773㎡ (A/B 2분할 가능, 예: 1A 4,941㎡/1B 5,670㎡), 63×171m, 층고 15m, 바닥하중 5t/㎡, 콘크리트 폴리싱, 홀당 약 600부스(3×3m)
- 트렌치 유틸리티: 전기·급배수·압축공기·전화·인터넷 (홀1은 가스 포함)
- **2전시장**: 홀 6~10 (5개 홀), 54,470㎡
- 홀6: 5,580㎡=93×60×10m(6A/B/C 각 1,860㎡), 2t/㎡, 카펫 마감, 200부스
- 홀7·8: 각 11,290㎡, 126×90×12m, 5t/㎡, 510부스 (홀7 가스 포함)
- 홀9: 13,238㎡ / 홀10: 13,072㎡, 132×99×15m, 5t/㎡
- 이동식 파티션으로 홀 분할·통합, 고층고로 복층부스·리깅 지원
- **회의실**: 총 37개. 1전시장 7,793㎡(그랜드볼룸 1,718㎡ 리셉션 2,000명, 이벤트홀 204, 중·소·분할회의실), 2전시장 5,510㎡(이벤트홀 6홀, 대회의실, VIP회의실 고정식 12~34명). 20명~5,000명 수용
- **임대료(2026)**: 전시홀 2,250원/㎡ (기본 12시간 08~20시, 초과 시 시간당 1일 임대료의 1/10, 장치일 6시간 무료), 로비 10,000원/㎡, 옥외 2,000원/㎡, 이벤트홀 2,420원/㎡. 성수기(3~5월, 9~11월) +10%, 비수기(1·2·7·12월) -10%, 1전시장 +10%. 회의실은 오전/오후/저녁 시간대별 요금(소회의실 30만 원~이벤트홀 통합 2,400만 원대), 용도 외 사용(전시·판매) 30% 할증
- **주차**: 전용 4,200면 + 임시 4,000면 + 킨텍스타워 2,200면. **양 전시장 간 100m 무빙워크 연결 통로**
- **회사**: (주)킨텍스, 2002년 설립·2005년 개장, 경기도+고양시+KOTRA 공동출자, 대표 이민우
## 4. 기존 온라인 서비스 (전시관리시스템 포함)
1. **킨텍스 온라인 작업신고 시스템** `https://kxwp.kintex.com` (및 `https://kxfp.kintex.com` — 동일 명칭의 별도 인스턴스): 주최자 신고서류 업로드, 장치업체 작업신고(부스 도면 제출) 용도. ID/PW 로그인 방식. ※ robots.txt 차단 + 직접 접속 실패로 내부 구조는 미확인 — 로그인 기반 폐쇄형 시스템
2. **전시홀/회의실 배정신청**: 온라인 제출 가능하다고 안내되나 실체는 **HWP 서식 다운로드 → 이메일/방문 제출** 수준 (배정신청서, 주최자신고서류, 임대요율표 등 HWP/PDF)
3. **등록업체 DB**: 웹에서 14개 분류(전시디자인설치, 리깅, 전기시설, 카펫/파이텍스, 급배수/Air, 가스설비, 철거, 운수통관, 가구비품, 경비용역, 광고싸인물, 지게차, 방염, 구조해석) × 지역 필터 검색, 엑셀 다운로드
4. **행사일정 시스템**: 캘린더/리스트, 유형별 필터
5. **참가업체 부대시설 신청**: 킨텍스 직영이 아니라 **각 전시회 주최자 사무국의 개별 온라인 시스템**(예: 코리아팩)에서 전기/압축공기/급배수/인터넷/지게차/초청장 신청 — 킨텍스 공통 플랫폼 부재
6. **주차 결제**: iparking 연동, 사전무인정산기
7. **오피스 공실현황** 조회, **VR 투어**(K-MICE), 고객의소리 온라인 접수
## 5. AI 자동화 기회
1. **부스 배치도(플로어플랜) 자동 생성·검증**: 홀 도면(63×171m 등 규격 공개) + 트렌치 위치 기반으로 부스 배치 자동 생성, 소방·피난 통로 규정, 높이 5m/복층 1/2 규정 자동 검증. 현재는 주최자가 CAD로 수작업 후 홀매니저가 육안 검수
2. **장치공사 도면 심사 자동화**: 독립부스 평면도·입면도·전기도면·리깅 구조계산서를 kxwp에 제출하면 사람이 검토하는 구조 → 도면 파싱 AI로 방염·높이·하중(2~5t/㎡ 홀별 상이)·리깅 높이(6.5~8.5m) 규정 위반 자동 플래깅
3. **유틸리티(전기·급배수·압축공기·통신) 신청·배선 최적화**: 참가업체가 위치표시도를 수기로 그려 등록하는 프로세스 → 부스 좌표 기반 트렌치 최단 배선 자동 산출, 분전반 용량(kW 합산) 자동 계산·요금 자동 견적, 마감기한(D-25 등) 리마인더 자동화
4. **임대 견적·배정 자동화**: 기본단가 2,250원/㎡ × 월별(±10%)·홀별(+10%) 차등 × 반홀 단위 + 관리비 예치금 15~20% 규칙이 명확 → 챗봇/견적기 자동화 용이. 홀 배정도 행사일정 DB와 연동한 가용성 실시간 조회 가능
5. **서류 워크플로 디지털화**: 배정신청서·주최자신고서류가 아직 **HWP 양식 + 이메일/방문 제출** → 웹폼 + AI 서류 검수(누락 항목, 재해대처계획서 적정성)로 전환. D-150(배정)/D-30(사전협의)/D-25(유틸리티)/D-7(신고서류) 마일스톤 자동 트래킹
6. **반입/반출 물류 스케줄링**: 화물차 순번제·통행증·하역장 배정을 수작업 운영 → 차량 예약 슬롯 시스템 + 대기열 최적화, 중량물(5t) 우선순위 자동 배치
7. **등록업체 매칭**: 739개 업체 DB가 단순 리스트 → 행사 유형·부스 규모·지역 기반 업체 추천, 견적 비교
8. **참가업체 공통 포털 부재**: 유틸리티 신청이 전시회별 주최자 시스템에 파편화 → 킨텍스 공통 참가업체 e-서비스 플랫폼(신청→위치도→결제→현장 개통 확인)이 가장 큰 공백
9. **다국어 안내/챗봇**: 해외 참가업체 대상 규정(방염, 소음 70dB, 안전모 등) 안내 자동화
## 6. 분석한 URL 목록
정상 분석: kintex.com 하위 23개 페이지 + 전시주최자매뉴얼 PDF + 코리아팩 참가업체 매뉴얼 PDF (총 25건)
접근 불가: `https://kxwp.kintex.com`, `https://kxfp.kintex.com` — robots.txt 차단/로그인 필요 (온라인 작업신고 시스템)

131
plugins/zio-harness/knowledge/kintex/docs/analysis/mobile-benchmark-exhibition-performance.md Normal file
View File

@ -0,0 +1,131 @@
# 전시·공연 모바일 앱 벤치마킹 (인기순) — 킨텍스 관람객(B2C) 앱
> 작성일: 2026-07-12 · 대상 트랙: KINTEX AI 전시·행사시스템 관람객(M10)·모바일 앱(`mobile/`, Expo)
> 소유자 지시: "모바일은 전시·공연 앱 벤치마킹 => 다운로드·좋아요가 가장 많은 순으로"
> 원칙: 스토어에서 확인된 수치만 사실로 기재하고 미확인·추정은 명시. 본 문서는 **분석·권고**만 기록하며 PLANNING.md·design.md를 직접 수정하지 않는다(적용은 kintex-mobile-orchestrator/designer 경유).
> 보완 관계: 기존 `docs/analysis/ticketing-app-benchmark.md`(예매·티켓 기능 대조)의 **상위 문서** — 여기서는 앱 인기순 랭킹·IA/UX·패턴 카탈로그를 다루고 기능 세부 대조는 티켓 문서를 참조한다.
---
## 0. 방법론 · 데이터 신뢰도 주의
- 수집: Google Play / App Store(KR) 공개 페이지 + 공개 보도. 크롤은 WebFetch/WebSearch만 사용.
- **Google Play 설치수**는 봇 차단으로 자동 수집 시 헤더만 노출되어 다수 **추정(범위)**로 표기했다. App Store는 평점·평가수가 안정적으로 노출되어 실값을 기재했다.
- ★**중대 해석 주의**: 한국 티켓팅 앱의 App Store 평점은 **1.3~1.8**로 매우 낮다. 이는 품질이 아니라 **티켓팅 실패·대기열 좌절에 따른 별점 폭탄(review bomb) 아티팩트**다 — 설치수·실사용은 오히려 최상위다. 따라서 "좋아요(평점) 순"과 "다운로드 순"은 **상반**하며, 아래 §1에 **두 개의 랭킹**을 분리 제시한다.
---
## 1. 인기순 랭킹표 (두 축)
### 1-A. 다운로드(설치) 기준 — "가장 많이 쓰는"
| 순위 | 앱 | 분류 | 플랫폼 | 설치수(Android) | 평점 | 평가/리뷰수 | 출처·비고 |
|---|---|---|---|---|---|---|---|
| 1 | **NOL(야놀자)** | 여가·공연·전시 슈퍼앱 | GP·AS | **1,000만+** (GP 단독) | — | — | outstanding.kr 보도(GP 누적 1천만). 공연·전시 예매 포함 슈퍼앱 |
| 2 | **NOL 티켓(구 인터파크티켓)** | 공연·전시·티켓 빅3 | GP·AS | 100만~500만+ *(추정)* | iOS 1.8 | iOS 2,100 | AS id440487844. 국내 공연·전시 예매 1위권. 평점=별점폭탄 |
| 3 | **Fever** (글로벌) | 이벤트·전시 발견·티켓 | GP·AS | **14,000,000** | GP 4.70 | 140,000 | appbrain/GP. 몰입형 전시(반고흐 등) 강세 |
| 4 | **Eventbrite** (글로벌) | 이벤트 발견·티켓 | GP·AS | 1,000만+ | GP 4.9 | 대량 | GP/SimilarWeb |
| 5 | **DICE** (글로벌) | 공연·라이브 티켓 | GP·AS | 월 1,000만+ 사용 | iOS 4.8 | iOS 97,000 | GP fm.dice. 양도(waitlist)·반환매 강점 |
| 6 | **티켓링크** | 공연·스포츠 티켓 빅3 | GP·AS | 50만~100만+ *(추정)* | — | — | GP kr.co.ticketlink.cne. 스마트티켓·스마트스탬프 |
| 7 | **멜론티켓** | 공연 티켓 빅3 | GP·AS | 50만~100만+ *(추정)* | iOS 1.8 | iOS 426 | AS id1103635576. 좌석 5분 선점 |
| 8 | **예스24 티켓** | 공연 티켓 | GP·AS | 10만~50만+ *(추정)* | iOS 1.3 | iOS 773 | AS id937042887 |
| 9 | **아트맵 ARTMAP** | 전시 큐레이션·발견 | GP·AS | 회원 14만+ (앱+웹+SNS) | 정성 긍정 | — | art-map.co.kr. 취향 기반 전시 추천·좋아요/다녀옴 |
| 10 | **국립현대미술관 전시안내(MMCA)** | 미술관 관람 | GP·AS | 5만~10만+ *(추정)* | iOS 4.2 | iOS 20 | AS id1350753069. 전시예약·QR관람권·오디오가이드·실내길찾기 |
| — | 서울시립미술관 도슨팅 / 국립중앙박물관 가이드 | 미술관/박물관 | GP·AS | 소~중규모 *(추정)* | — | — | 도슨트·오디오가이드 중심 |
| — | KOPIS(공연예술통합전산망) | 공연 통계·정보 공공 | 모바일웹 중심 | 전용앱 미약 | — | — | kopis.or.kr/mob. 예매 아닌 정보·통계 허브 |
| — | Whova (글로벌 컨퍼런스) | B2B 이벤트 앱 | GP·AS | 100만+ | 높음 | — | 기존 티켓 벤치마크 §1 참조(개인 아젠다·QR 명함·셀프 체크인) |
### 1-B. 좋아요(평점·만족도) 기준 — "가장 사랑받는"
| 순위 | 앱 | 평점 | 근거 | 킨텍스 시사 |
|---|---|---|---|---|
| 1 | **Eventbrite** | GP 4.9 | 발견성·간편 등록·게스트리스트 체크인 | 무료·정원제 전시 등록 UX가 콘서트 예매보다 관람객 앱에 적합 |
| 2 | **DICE** | iOS 4.8 (97K) | 무발권 QR·정품 양도(waitlist)·반환매 | 티켓 신뢰(재판매·양도) UX 우수 |
| 3 | **Fever** | GP 4.70 (140K) | 몰입형 전시 발견·큐레이션·추천 | 전시 "발견" 홈피드·추천이 만족도 핵심 |
| 4 | **국립현대미술관(MMCA)** | iOS 4.2 | 전시예약+QR관람권+오디오가이드+실내길찾기 **한 앱** 통합 | 킨텍스 관람객 앱과 가장 근접한 국내 롤모델 |
| 5 | **아트맵 ARTMAP** | 정성 긍정 | 취향 추천·좋아요/다녀옴 컬렉션 | 개인화 발견·"찜/방문" 데이터 루프 |
| 하위 | 국내 티켓팅 빅3(NOL 티켓·멜론·예스24) | 1.3~1.8 | **별점 폭탄 아티팩트**(티켓팅 좌절) | 설치는 최상위이나 만족도 낮음 → 킨텍스는 대기열 스트레스 낮은 무료 전시라 **만족도 우위 확보 가능** |
**요지**: 킨텍스 관람객 앱의 벤치마크 최적 조합 = **MMCA(국내 전시 통합 UX) + Eventbrite/DICE(신뢰·발견·양도) + Fever/아트맵(개인화 발견) + Whova(현장 인게이지먼트·비즈매칭)**. 국내 티켓팅 빅3는 예매 퍼널·부정입장 방지 기법만 차용(만족도 반면교사).
---
## 2. 상위 앱별 IA · 기능 · UX 분석
### 2-1. 국립현대미술관 전시안내 (MMCA) — 국내 전시 앱 롤모델 (iOS 4.2)
- **홈 IA**: 전시추천 → 전시예약 → QR관람권 → 오디오가이드(작품감상) → 실내 길찾기. **관람 여정 전체를 한 앱**에 담은 국내 유일급.
- **차용가치 최상**: (a) **전시 사전예약→QR 관람권 발권→현장 QR 입장** 폐루프, (b) **작품 단위 오디오가이드**(전시장 비콘/번호 입력), (c) **관내 실내 길찾기**. 킨텍스 SCR-M5/M6/M14/M15와 1:1 대응.
- **약점**: 4관 한정·평가 표본 적음(20). 추천·소셜·다국어 얕음.
### 2-2. Fever (글로벌, 14M·4.70) — 전시 "발견" 엔진
- **홈 IA**: 위치기반 **발견 피드**(오늘/이번주/인기/카테고리 타일) 중심. 리스트가 아니라 **큐레이션 카드**.
- **UX 강점**: 몰입형 전시(디지털 아트) 강세, **관심·위치 기반 추천**, 원탭 예약, 캘린더 리마인더.
- **차용**: 관람객 홈을 "행사 리스트"가 아닌 **개인화 발견 피드**(추천 존·근처·마감임박·AI추천 칩)로.
### 2-3. DICE (글로벌, iOS 4.8·97K) — 티켓 신뢰 UX
- **강점**: **무발권 QR**(입장 직전 활성화), **정품 재판매/양도 waitlist**(암표 차단), 리마인더, 라인업 상세.
- **차용**: 티켓 **양도·환불 대기열**(정원 소진 세션/티켓의 대기·취소표 알림), 입장 직전 QR 활성화(캡처 무효).
### 2-4. Eventbrite (글로벌, GP 4.9) — 무료·게스트 등록 표준
- **강점**: 마켓플레이스 **발견성**, 무료/유료 티켓 유형 선택→간편 등록→QR, 오거나이저 앱 게스트리스트 체크인.
- **차용**: 전시(무료·정원제)에 맞는 **짧은 등록 퍼널 + 게스트 등록 + 셀프 체크인**.
### 2-5. 아트맵 ARTMAP (전시 큐레이션, 회원 14만+)
- **강점**: **취향 기반 전시 추천**, **좋아요·다녀옴** 버튼으로 개인 컬렉션·취향 분석, 근처 갤러리, 일 400+ 전시 정보.
- **차용**: **찜(좋아요)·다녀옴 데이터 루프 → 개인화 추천** (킨텍스 즐겨찾기를 취향학습으로 승격).
### 2-6. 국내 티켓팅 빅3 (NOL 티켓·멜론·티켓링크·예스24) — 예매·입장 기법 (반면교사)
- **예매 퍼널**: 회차/좌석→권종→예매자→결제→완료. 좌석 선점 타이머(멜론 5분)·대기열·매크로 방지(CAPTCHA).
- **입장/부정방지**: 티켓링크 **스마트티켓**(무발권 QR/바코드)+**스마트스탬프**(단말 고유값 인식 → 캡처본 무효). QR 인식 위해 밝기 상향.
- **개인화**: 관심인물/공연/장르, **티켓오픈 알림**, 예매대기·취소표 우선권.
- **차용**: 부정입장 방지(디바이스 바인딩·회전 QR)·오픈 알림·다구간 환불 규정 — 상세는 `ticketing-app-benchmark.md` §2·§3.
- **주의**: 낮은 평점=티켓팅 스트레스. 킨텍스 무료 전시는 이 스트레스가 없어 **만족도 우위**가 기본값.
### 2-7. Whova (글로벌 B2B 컨퍼런스) — 현장 인게이지먼트
- **강점**: 참가자 고유 QR(배지+앱), **개인 아젠다(세션 정원)**, **QR 명함교환·매치메이킹·밋업**, 셀프 체크인 키오스크, 라이브 공지/폴.
- **차용**: 비즈매칭(SCR-M8)·세션 아젠다 정원(SCR-M9)·QR 명함교환·라이브 공지 피드.
---
## 3. 패턴 카탈로그 (전시·공연 앱 공통 베스트 프랙티스)
| 패턴 | 정의 | 대표 앱 | 킨텍스 대응 |
|---|---|---|---|
| **P-A 발견 피드 홈** | 리스트가 아닌 위치·취향 기반 큐레이션 카드 홈 | Fever·아트맵·NOL | SCR-M5 홈을 발견 피드로 |
| **P-B 관람 폐루프** | 예약→QR 관람권→현장 QR 입장→배지 승격 | MMCA·Whova | SCR-M14→M15→체크인→M5 (이미 정의) |
| **P-C 무발권/회전 QR** | 입장 직전 활성화·디바이스 바인딩으로 캡처 무효 | DICE·티켓링크 | SCR-M15 강화(현재 정적 QR) |
| **P-D 오픈/관심 알림 구독** | 오픈 예정·관심 행사 구독→푸시/EDM | NOL·COEX | 신규(공개사이트+앱) |
| **P-E 취향 학습(좋아요/다녀옴)** | 찜·방문 데이터→개인화 추천 | 아트맵·Fever | SCR-M5·M7 즐겨찾기→추천 승격 |
| **P-F 개인 아젠다·정원 RSVP** | 세션 즐겨찾기 + 정원·마감·대기 | Whova | SCR-M9 정원 상태 추가 |
| **P-G QR 명함교환·컨택트 지갑** | 관람객↔관람객/참가업체 상호 QR | Whova | SCR-M8 확장 |
| **P-H 오디오가이드/도슨트** | 작품·부스 단위 음성 해설 | MMCA·서울시립·박물관 | 신규(킨텍스 부스/전시 해설) |
| **P-I 실내 wayfinding** | 블루닷·경로·존레벨 폴백 | MMCA·COEX | SCR-M6(이미 정의) |
| **P-J 현장 편의 통합** | 주차 실시간·결제·혼잡/대기 한 동선 | 킨텍스 공식앱·COEX | 신규(주차·혼잡 위젯) |
| **P-K 셀프 체크인/즉석 배지** | 키오스크 셀프 등록·현장 배지 인쇄 | Whova·Eventbrite | 신규 화면 |
| **P-L 다국어·접근성** | 한/영/중/일 + WCAG AA + QR 대체 | Whova·COEX | 전 화면(강화) |
| **P-M 티켓 양도·취소표 대기** | 정품 재판매·대기열 알림(암표 차단) | DICE·NOL | 신규(정원 세션·티켓) |
---
## 4. 출처 URL
- NOL(야놀자) 1천만 다운로드: https://outstanding.kr/ (보도), GP `com.cultsotry.yanolja.nativeapp`
- NOL 티켓(인터파크): AS https://apps.apple.com/kr/app/id440487844 · GP `com.interpark.app.ticket`
- 멜론티켓: AS https://apps.apple.com/kr/app/id1103635576 · GP `com.iloen.melonticket`
- 예스24 티켓: AS https://apps.apple.com/kr/app/id937042887
- 티켓링크: GP `kr.co.ticketlink.cne` · 스마트티켓 https://www.ticketlink.co.kr/help/guide/popup/smart-ticket
- 아트맵 ARTMAP: AS id1446240686 · GP `com.artmap.app` · https://art-map.co.kr/
- 국립현대미술관 전시안내: AS https://apps.apple.com/kr/app/id1350753069 · GP `kr.go.mmca.hdexhibit`
- 서울시립미술관 도슨팅: GP `seoul.museum.art.act` · 국립중앙박물관: GP `or.kr.nationalmuseum`
- KOPIS: https://www.kopis.or.kr/mob/main/main.do
- Fever: GP `com.feverup.fever` · appbrain fever-events-tickets
- DICE: GP `fm.dice` · https://dice.fm/
- Eventbrite: GP `com.eventbrite.attendee` · SimilarWeb 통계
- Whova: https://whova.com/whova-event-app/
- (기능 세부 대조) `docs/analysis/ticketing-app-benchmark.md`
---
## 변경 이력
| 날짜 | 변경 내용 |
|---|---|
| 2026-07-12 | 최초 작성 — 전시·공연·티켓·미술관 앱 인기순 랭킹(다운로드/평점 2축), MMCA·Fever·DICE·Eventbrite·아트맵·티켓팅빅3·Whova IA/UX 분석, 패턴 카탈로그 13종(P-A~P-M). 별점폭탄 아티팩트 해석 주의 명기 |

30
plugins/zio-harness/knowledge/kintex/docs/analysis/nifty-design-refs.md Normal file
View File

@ -0,0 +1,30 @@
# Nifty 디자인 레퍼런스 (소유자 지정, 2026-07-12)
> **방향 확정(2026-07-12):** 킨텍스 공통 UI의 **디자인 기준을 Nifty(themeon)로 채택**한다. 개별 요소를 하나씩 지정받는 중 — 아래 표에 계속 누적. 적용은 wise-ui 하네스가 요소별 웨이브로 kx 토큰 번역 통일.
킨텍스 UI 정렬의 스타일 레퍼런스. GUARDiA ITSM이 원래 Nifty 다크 테마 기반이라 프로젝트 계보와 정합.
적용은 kx 토큰으로 번역(하드코딩 금지), 다크/라이트 양 테마, 이모지 금지(선 SVG).
| 영역 | 레퍼런스 URL | 적용 대상 | 상태 |
|---|---|---|---|
| 정적 테이블 헤더 | https://preview.themeon.net/nifty/tables/static-tables/ ("Advanced table headers") | `.kx-table` 공통 표준 | 진행 중 |
| 인터랙티브 그리드 | https://preview.themeon.net/nifty/tables/tabulator/ | 공통 DataGrid(정렬·필터·페이지·CSV export) — 관리자/목록 | 대기 |
| 상세 페이지 | https://preview.themeon.net/nifty/blog-apps/blog/ | 행사·전시·공지·옥션 등 상세 뷰 | 대기 |
| 카드 | https://preview.themeon.net/nifty/ui-elements/cards/ | `.kx-card` 공통 카드(헤더·바디·푸터·액션·컬러바) | 대기 |
| 버튼 | https://preview.themeon.net/nifty/ui-elements/buttons/ | `Button`/`.kx-btn` 공통(변형·크기·상태·아이콘·그룹) | 대기 |
| 드롭다운 | https://preview.themeon.net/nifty/ui-elements/dropdowns/ | 드롭다운/메뉴/셀렉트(kx 드롭다운) | 대기 |
| 컴포넌트 전반 | https://preview.themeon.net/nifty/ui-elements/components/ | 뱃지·알럿·탭·모달·툴팁·프로그레스·페이지네이션 등 공통 컴포넌트 | 대기 |
| 리스트 그룹 | https://preview.themeon.net/nifty/ui-elements/list-group/ | 리스트 그룹(공지·활동·검색결과·목록형 카드) | 대기 |
| 타이포그래피 | https://preview.themeon.net/nifty/ui-elements/ (typography) | 제목·본문·캡션 위계(kx 타이포 토큰) | 대기 |
| 모달/메시지박스 | https://preview.themeon.net/nifty/ui-elements/ (modals) | 모달·확인/경고 메시지박스(kx Modal) | 대기 |
| Offcanvas | https://preview.themeon.net/nifty/ui-elements/ (offcanvas) | 오프캔버스 패널(모바일 드로어·상세 슬라이드) | 대기 |
| 달력 | https://preview.themeon.net/nifty/app-views/calendar/ | 일정 캘린더(월/주/일)·이벤트 색/드래그·사이드 목록 | 완료(KxCalendarView 재스타일 2026-07-12 — 옅은 격자·옅은 노랑 today 틴트·소프트 카테고리 칩(color-mix), 미니 `.kx-cal` 동일 톤. `.kx-mcal`는 기존 소프트 톤 유지) |
| **UI-elements 전체** | **https://preview.themeon.net/nifty/ui-elements/** | **Nifty UI-elements 전 페이지를 킨텍스 공통 UI 기준으로 채택**(위 개별 + 나머지 요소 전부) | 기준 |
| 셸·메뉴(기존) | WISE(UIWS) AppLayout/LeftNav/CalendarView | 셸·아코디언·캘린더 | 완료(구조) |
| 상단바(top frame) | https://preview.themeon.net/nifty/ (navbar/header) | 상단 헤더 — 로고·검색·알림·설정·사용자 드롭다운·풀스크린·언어 | 대기 |
| 설정(레이아웃 커스터마이저) | https://preview.themeon.net/nifty/ (설정 아이콘 → 우측 패널) | 상단 설정 아이콘 클릭 → 우측 offcanvas: 테마(라이트/다크)·레이아웃 모드·사이드바·색상 등 실시간 조정 | 대기(공용 Offcanvas 재사용) |
## 원칙
- 레퍼런스의 **구조·위계·인터랙션**을 차용하되, 색·간격·폰트는 kx 디자인 토큰으로 번역.
- WISE(UIWS)가 대응물을 가진 영역은 WISE 우선(셸·시스템관리·공통기능). Nifty는 WISE에 없는 표현(고급 테이블·blog형 상세)의 레퍼런스.
- 신규 npm 의존성(Tabulator 등)은 번들·다크·i18n 정합 확인 후 파일럿→확산.

179
plugins/zio-harness/knowledge/kintex/docs/analysis/reroomai-source.md Normal file
View File

@ -0,0 +1,179 @@
# ReRoomAI 소스코드 분석
> 분석일: 2026-07-11 · 대상: `C:\GUARDiA\workspace\ReRoomAI` — AI 공간 인테리어 리디자인 웹 서비스
> 목적: 킨텍스 전시 부스 "시공 후 결과 사진 생성 AI" 시스템(PLANNING §6 나노바나나 파이프라인)의 구조보존 제어 파라미터 확정
> 연계: PLANNING.md R11 / BACKLOG B-11 해소 근거 문서
---
## 1. 프로젝트 개요
**ReRoom AI**는 방 사진 한 장을 업로드하고 공간 유형·인테리어 스타일을 선택하면 약 10초 만에 새로운 분위기의 방으로 재렌더링하는 AI 인테리어 리디자인 웹 서비스다.
핵심 설계 철학은 **"건축학적 뼈대 보존 + 표면 요소 교체"**. 원본 방의 벽·창문·문·천장·**카메라 시야 구도(perspective)**는 그대로 유지하고 가구·조명·색감·장식만 선택한 테마로 바꾼다. 이것이 킨텍스 부스 시스템에 이식할 가장 중요한 개념 — "빈 부스 공간 골격은 유지하고 그 안에 배치·인테리어·조명·배선만 시공된 결과를 합성"과 동일한 문제 구조다.
주요 기능:
- 6가지 공간 유형(거실/침실/주방/욕실/서재/원룸) × 8가지 스타일(모던/미니멀/북유럽/인더스트리얼/재팬디/미드센추리/한옥/호텔라운지)
- **이중 API 모드**: 데모 모드(서버 키, 브라우저 로컬 2회 + IP당 하루 10회 제한) / BYOK 모드(사용자 개인 키, 무제한)
- **Before/After 드래그 비교 슬라이더**(마우스·터치·키보드 지원)
- 결과 PNG 다운로드 + "다른 스타일로 다시 디자인"(원본 재업로드 없이 연속 실험)
- 클라이언트 Canvas 전처리(긴 쪽 1024px 다운스케일)
---
## 2. 기술 스택
| 레이어 | 기술 |
|--------|------|
| 프레임워크 | **Next.js 16.2.10** (App Router, Node runtime) — 단일 리포 서버리스, Vercel 배포 지향 |
| 언어 | TypeScript 5 |
| UI | React 19.2.4 |
| 스타일 | Tailwind CSS v4 (`@theme` 커스텀 토큰), Pretendard + Noto Serif KR (`next/font`) |
| **AI SDK** | **`@google/genai` ^2.10.0** (Google 공식 SDK) |
| **모델** | **`gemini-3.1-flash-image-preview`** (= 나노바나나 2 / Nano Banana 2) |
| 의존성 | 극히 단순 — `@google/genai`, `next`, `react`, `react-dom` **4개뿐** |
> 주목: `AGENTS.md`에 "이 Next.js는 학습 데이터와 다르다, 코드 작성 전 `node_modules/next/dist/docs/` 가이드를 읽으라"는 경고. Next 16 신버전이라 관례가 다를 수 있음.
---
## 3. 디렉터리 구조
```
ReRoomAI/
├── app/
│ ├── layout.tsx # 폰트·메타데이터·OG
│ ├── page.tsx # 섹션 조립: Header→Hero→StyleGallery→HowItWorks→Studio→Faq→Footer
│ ├── globals.css # 디자인 토큰(@theme)·그레인/리빌
│ └── api/generate/route.ts # ★ Gemini 이미지 생성 라우트(IP 레이트리밋 포함) — 시스템의 심장
├── components/
│ ├── Studio.tsx # ★ 메인 인터랙션(업로드·옵션·생성·결과) — 클라이언트 플로우 전체
│ ├── CompareSlider.tsx # ★ Before/After 슬라이더(clip-path + 포인터캡처)
│ ├── Header/Hero/StyleGallery/StyleCards/HowItWorks/Faq/Footer.tsx # 랜딩 섹션
│ └── Reveal.tsx # 스크롤 리빌 래퍼
├── lib/
│ ├── constants.ts # ★ 공간유형·스타일 정의 (UI와 서버 프롬프트 단일 출처)
│ └── useLocalStorage.ts # SSR 안전 localStorage 훅
├── .env.example # GEMINI_API_KEY
└── package.json
```
핵심 파일 4개: `app/api/generate/route.ts`(백엔드 생성), `lib/constants.ts`(프롬프트 사전), `components/Studio.tsx`(클라이언트 플로우), `components/CompareSlider.tsx`(결과 비교 UI).
---
## 4. AI / 이미지 생성 파이프라인 ★
### 사용 모델·API
- **Google Gemini `gemini-3.1-flash-image-preview`(나노바나나 2)** 를 `@google/genai` 공식 SDK의 `ai.models.generateContent()`로 호출.
- **입력 이미지 + 텍스트 지시문을 함께 전달**하는 멀티모달 image-to-image(인페인팅형 편집). Stable Diffusion·ControlNet 등 미사용 — 순수 Gemini 이미지 모델 단일 호출로 원본 구조를 참조·보존.
### 이미지 흐름 (입력 → 변환 → 결과)
```
[클라이언트 Studio.tsx]
1. 파일 업로드(드래그앤드롭/클릭) — image/* 검증, 10MB 상한
2. Canvas 전처리: 긴 쪽 1024px 다운스케일 → canvas.toDataURL('image/jpeg', 0.85) → base64 data URL (전송량·비용 절감 핵심)
3. POST /api/generate { image(base64), roomTypeId, styleId, byokKey }
[서버 route.ts — runtime='nodejs', maxDuration=60]
4. content-length 8MB 가드 → JSON 파싱 → roomType/style 유효성 검증
5. API 키 결정: BYOK 우선, 없으면 process.env.GEMINI_API_KEY
6. 데모 모드면 IP당 일일 제한(Map 인메모리) 체크
7. data URL에서 mimeType + base64 분리(정규식), 8MB*1.33 재검증
8. 프롬프트 조립 → Gemini generateContent 호출
9. 응답 candidate에서 inlineData(생성 이미지 base64) 추출
- finishReason==='SAFETY' → 차단 에러
- 성공 시에만 IP 카운트 차감(실패는 횟수 소모 안 함)
10. { image: base64 } 반환
[클라이언트]
11. `data:image/png;base64,${data.image}`로 resultImage 세팅
12. CompareSlider에 before(업로드)·after(결과) 주입
```
### 프롬프트 구성 방식 (★ 가장 차용 가치 높음)
**구조화된 사전(dictionary) 조각을 템플릿에 조립**. `lib/constants.ts`가 UI 라벨(한글)과 프롬프트 조각(영문)을 한 객체에 묶어 **UI 선택과 서버 프롬프트가 단일 출처 공유**:
```ts
// 공간 유형: { id, label(한글), prompt(영문) }
{ id: "living_room", label: "거실", prompt: "living room" }
// 스타일: { id, label, desc, swatch(색3종), prompt(상세 지시문) }
{ id: "modern", label: "모던", swatch:["#2b2b2e",...],
prompt: "sleek modern style: clean lines, neutral palette with charcoal and greige,
low-profile furniture, matte finishes, statement lighting" }
```
최종 지시문 템플릿(route.ts:106):
```
Redesign this {roomType.prompt} interior in {style.prompt}.
Keep the room architecture — walls, windows, doors, ceiling and camera perspective — exactly the same.
Replace furniture, lighting, color palette and decor to match the target style.
Photorealistic interior photography, natural lighting, high detail.
```
프롬프트 4단 구성: **① 대상+스타일 지정 → ② "보존할 것" 명시적 잠금(architecture/perspective) → ③ "교체할 것" 명시 → ④ 사진 품질 지시(photorealistic/natural lighting/high detail)**. 이 "보존/교체 명시적 분리" 패턴이 부스 시스템의 핵심.
---
## 5. 킨텍스 부스 시스템 차용 패턴 ★★★
(전시 부스 배치·인테리어·전기·조명·네트워크 배선 자동화 → 나노바나나 시공 후 결과 사진)
**(A) 모델·SDK 선택 — 검증된 정답 그대로 채택**
- `@google/genai` + `gemini-3.1-flash-image-preview`, `generateContent`에 `{ inlineData:{mimeType,data} }`(입력 이미지) + `{ text: instruction }`(지시문)을 `parts` 배열로 전달하는 호출 형태 복제. `nanobanana-visualize` 스킬이 이 호출 패턴을 표준화.
**(B) "보존/교체 명시적 분리" 프롬프트 아키텍처 — 부스 도메인 치환**
- ReRoom "walls·windows·ceiling·camera perspective exactly same" → 부스 **"부스 외곽 치수·기둥·바닥 트렌치 그리드·천장 트러스·통로 방향·카메라 앵글 유지"**.
- ReRoom "furniture·lighting·color·decor 교체" → 부스 **"집기(데스크·선반·배너·사이니지)·조명 기구·전기 콘센트·네트워크 AP·카펫/부스 벽면 그래픽 배치"**.
- **구조화 사전 재사용**: `ROOM_TYPES`/`STYLES` → 부스 도메인 사전
- `BOOTH_TYPES`(독립/조립/코너/아일랜드, 3×3·6×3…)
- `BOOTH_STYLES`(럭셔리/테크/친환경/미니멀…)
- `FIXTURE_LAYERS`(조명 레이어·전기 배선 레이어·네트워크 배선 레이어) — **레이어별 프롬프트 조각** 조립로 "조명만 야간 연출"(S2)·"배선 오버레이"(S6) 변형 렌더.
- 각 객체가 `{ id, label(한글), prompt(영문), swatch }`를 갖고 **UI 선택 ↔ 서버 프롬프트 단일 출처 공유** 유지 시 유지보수 비용 급감.
**(C) Before/After 비교 슬라이더(`CompareSlider.tsx`) — 거의 무수정 재사용**
- `clip-path: inset(0 {100-pos}% 0 0)`로 After 레이어 클립 → 리사이즈에도 픽셀 정렬 유지. 포인터 캡처 + 키보드(방향키·Shift 큰 스텝) + ARIA slider 접근성 완비 자립 컴포넌트. design.md S5(시공 전 빈 부스 ↔ 시공 후 렌더)에 그대로 투입. React/Next 스택이면 파일 복사 수준.
**(D) 클라이언트 Canvas 전처리(`Studio.handleImageFile`)**
- 긴 쪽 1024px 다운스케일 + JPEG 0.85 → base64. 전송량·모델 비용·응답시간 동시 절감 필수 전처리. 부스 도면/현장 사진 동일 적용.
**(E) API 라우트 방어 로직 — 프로덕션 안정성 템플릿**
- 다층 크기 가드(content-length 8MB → base64 ×1.33 재검증), `finishReason==='SAFETY'` 처리, **에러 분기**(API_KEY_INVALID / RESOURCE_EXHAUSTED·quota·429 / SAFETY)로 친화적 한글 메시지. **성공 시에만 사용량 차감**. 부스 API(RenderJob 워커)의 골격으로 복제.
**(F) 이중 키 모드(데모/BYOK) + IP 레이트리밋**
- 서버 인메모리 `Map<ip,{count,resetAt}>` 24h 윈도우. 전시회 현장 태블릿 데모 노출에 유용. **인메모리라 재시작·다중 인스턴스 취약** → 우리 시스템은 PostgreSQL/Redis 기반 RenderJob 쿼터로 대체(PLANNING §6-4 비용 제어와 통합).
**(G) 단계별 로딩 UX**
- `LOADING_STATUSES`("공간 구조 분석 → 스타일 요소 배치 → 조명·색상 튜닝 → 최종 고화질 렌더링") 2.5초 순환. 부스용 "부스 골격 인식 → 집기 배치 → 전기·조명 배선 → 최종 렌더링"으로 치환. design.md 진행 배지("생성 중… 평균 40초")와 연결.
---
## 6. UI / 화면 구성
단일 페이지(랜딩) 서비스. `page.tsx` 세로 조립: Header → Hero(CompareSlider LCP priority) → StyleGallery(카드 클릭 시 `window` 커스텀이벤트 `reroom:style`로 Studio 전달) → HowItWorks → **Studio ★** → Faq → Footer.
**Studio 흐름**(단일 컴포넌트가 입력→로딩→결과 3상태 조건부 렌더):
1. **입력** — 좌: `01 원본 업로드`(드래그존+미리보기), 우: `02 공간 유형`(pill), `03 스타일`(스와치 카드). 하단: BYOK 토글+키, 에러 alert, "생성하기".
2. **로딩** — 바운스 도트 + 순환 상태 텍스트(`aria-live`) + "약 10초".
3. **결과** — "Redesign Complete" 배지 + CompareSlider + [PNG 다운로드]/[다른 스타일]/[다른 사진].
상태 전부 로컬 `useState` + `useLocalStorage`(무료횟수·BYOK·키 영속). 전역 스토어·라우팅 없음 — 극경량 단일화면 SPA. 부스 초기 PoC도 이 패턴으로 빠르게 구현 후 확장 가능.
---
## 7. 설계 착수 3대 차용 결론
1. **호출 스택 그대로**: `@google/genai` → `gemini-3.1-flash-image-preview`, 입력이미지(inlineData)+지시문(text) parts 전달 image-to-image 편집. `route.ts`가 프로덕션 API 골격 템플릿.
2. **프롬프트 = 구조화 사전 조립 + 보존/교체 명시 분리**: `constants.ts` `{id,label,prompt}`를 부스 도메인(부스타입·스타일·조명/전기/네트워크 레이어)으로 치환, "골격·앵글 유지 / 집기·배선·조명 배치" 명시 잠금 템플릿.
3. **CompareSlider·Canvas 전처리·단계별 로딩 UX** 파일 복사 수준 재사용(React/Next 전제).
---
## 8. ★ 보안 결정 필요 사항 (선행)
나노바나나(Gemini) 이미지 생성은 **외부 API 호출**이다. GUARDiA 보안 제약(루트 CLAUDE.md)상 외부 API는 원칙 금지이며 현재 승인된 예외는 `api.anthropic.com`뿐 — **Gemini(generativelanguage.googleapis.com)는 미승인**. 단, 본 kintex 프로젝트는 GUARDiA ITSM(관공서 인프라 관제)과 별개 도메인의 독립 저장소(`zio/kintex`)이며, PLANNING v1.0과 사용자 요구가 명시적으로 나노바나나를 채택하고 있다.
**조치**: 부스 M5 파이프라인 구현 착수 전 소유자에게 **Gemini 외부 호출 승인 여부**를 확정한다. 승인 시 `GEMINI_API_KEY`를 서버 env로만 로드(코드·DB·커밋·로그·응답 기록 금지, ReRoomAI (E) 방어 패턴 준수). 미승인 시 대안 — 온프레미스 이미지 생성(SDXL 등) 어댑터로 폴백하되 image-to-image 구조보존 품질은 재평가 필요.

141
plugins/zio-harness/knowledge/kintex/docs/analysis/ticketing-app-benchmark.md Normal file
View File

@ -0,0 +1,141 @@
# 관람객·입장권 예매·모바일 앱 벤치마킹 — 코엑스 및 공연/티켓 앱
> 작성일: 2026-07-11 · 대상 트랙: 킨텍스 자동전시시스템 관람객(M10)·티켓·모바일 앱
> 목적: COEX·공연/티켓 빅3·글로벌 이벤트 앱을 조사하여 현행 `design.md` v2.1 티켓·관람객 화면(SCR-P7/P8·M14/M15·M5~M9)을 대조·보강.
> 원칙: 확인된 기능만 사실로 기술하고 미확인 항목은 "추정" 표기. 본 문서는 **권고만** 기록하며 PLANNING.md·design.md를 직접 수정하지 않는다.
---
## 1. 벤치마킹 대상별 요약
| 앱/서비스 | 분류 | 강점 | 약점/한계 | 특징 기능 |
|---|---|---|---|---|
| **COEX**(코엑스 공식 웹) | 전시장 운영사 | PC·모바일 실내 길찾기(PC 지도→모바일 QR 이전), 주차 혼잡 예측(KakaoT 데이터), 관심분야 행사 알림 | 전용 네이티브 앱보다 웹 중심(추정), 예매/티켓 기능은 각 주최자 사이트에 파편화 | 실내 내비게이션, 주차 혼잡 예보, 관심 기반 행사 알림 구독 |
| **인터파크 NOL 티켓** | 공연/티켓 빅3 | 성숙한 예매 퍼널·개인화(관심인물/공연/장르), 오픈 알림(티켓캐스트 알리미), 예매대기·취소표 우선권, 결제수단 사전등록 빠른결제 | 콘서트 특화(좌석 선점·대기열)로 무료 전시엔 과한 요소, 우편배송 등 물리 티켓 잔재 | 티켓오픈 알림, 관심 구독, 예매대기 서비스, 단계별 취소수수료 규정 |
| **멜론티켓** | 공연/티켓 빅3 | 좌석 5분 선점 UX, 수령방식 선택(배송/현장수령/모바일 발권), 당일 모바일티켓 제시 입장, 강한 매크로 방지(CAPTCHA) | 좌석제 공연 중심, 입장 UX 상세는 비공개(추정) | 모바일 발권, 좌석 선점 타이머, 봇 방지 |
| **티켓링크** | 공연/티켓 빅3 | 스마트티켓(별도 발권 없이 QR/바코드 입장), 스마트스탬프(휴대폰 고유값 인식 → 캡처 티켓 무효·부정입장 방지) | 좌석/경기 특화, SMS URL 등록 절차 존재 | 스마트티켓, 스마트스탬프(디바이스 바인딩), QR/바코드 입장 |
| **킨텍스 공식 앱**(com.kintex) | 전시 특화(자사) | 무료 사전등록, 실시간 주차현황·주차비 결제, 이벤트/할인권(맛집·호텔), 지역별 등록 분포 | 전시별 통합 예매·티켓 지갑·비즈매칭은 미약(추정), 부스 wayfinding 약함 | 사전등록, 주차 연계, 편의(할인권), 등록 분포 데이터 |
| **Whova**(글로벌 이벤트 앱) | 이벤트·컨퍼런스 | 참가자별 고유 QR(배지+앱), 리드 리트리벌, 멀티트랙 개인 아젠다+세션 정원 등록, 인앱 메시징·매치메이킹·밋업 스케줄·QR 명함교환, 셀프 체크인 키오스크, 온디맨드 배지 생성, 라이브 공지/폴 | 유료 SaaS, 국내 결제/PG·다국어 로컬라이즈는 별도 | 개인 아젠다(정원), QR 명함교환, 셀프 체크인 키오스크, 라이브 인게이지먼트 |
| **Eventbrite**(글로벌) | 티켓·발견 | 오거나이저 앱 QR 스캔·이름/게스트리스트 체크인, 마켓플레이스 발견성 | 컨퍼런스 당일 인게이지먼트는 약함 | 발견(마켓플레이스), 간편 체크인, 디지털 게스트 리스트 |
---
## 2. 조사 항목 ①~⑧ 베스트 프랙티스 비교
### ① 예매 퍼널 (단계 수·게스트 예매)
- **NOL/멜론/티켓링크**: 회차/좌석 → 권종/수량 → 예매자 → 결제 → 완료. 좌석제는 선점 타이머(멜론 5분). 콘서트는 대기열/대기번호. 회원 로그인 유도.
- **Whova/Eventbrite**: 무료·유료 티켓 유형별 수량 선택 → 등록폼 → (유료 시)결제 → QR 발급. 게스트 등록 허용, 셀프 등록 중심.
- **킨텍스 앱**: 무료 사전등록 폼 중심(결제 최소).
- **베스트**: 전시(대체로 무료·정원제)는 **좌석 선택 대신 권종·정원 기반 짧은 퍼널**이 적합. 게스트 예매 허용 + 무료 권종 결제 스킵 + 회원 저장 유도가 표준.
### ② 티켓 수령 방식 (QR·스마트티켓·본인인증)
- **티켓링크 스마트티켓**: 별도 발권 없이 앱/URL 등록 → QR·바코드. **스마트스탬프 = 휴대폰 고유값 인식**으로 캡처본 무효·부정입장 방지.
- **멜론**: 모바일 발권/현장수령/배송 선택, 당일 모바일티켓 제시.
- **Whova**: 참가자별 **고유 QR**(배지·앱 동시), 리드 리트리벌 연계.
- **베스트**: **모바일 QR 지갑 기본 + 디바이스 바인딩/본인인증으로 위·변조·양도 방지**. 캡처만으로 입장 불가(회전 토큰·기기 인식)가 정품 티켓 신뢰의 핵심.
### ③ 입장/체크인 UX (밝기 부스트·오프라인 QR)
- **공통(티켓링크 안내)**: QR 인식률 위해 **화면 밝기 상향** 권장.
- **Whova/Eventbrite**: 셀프 체크인 키오스크·오거나이저 앱 스캔, 이름/게스트리스트 폴백.
- **베스트**: **QR 풀스크린 + 자동 밝기 부스트 + 오프라인 캐시 표시**(현장 네트워크 불안정 대비) + 셀프 체크인 키오스크/즉석 배지 인쇄 폴백.
### ④ 취소·환불 플로우
- **NOL 티켓(공개 규정)**: 예매수수료는 예매 당일 자정까지만 환불. 취소수수료 = 관람일 D-10까지 정액(뮤지컬/콘서트 4,000원 등, 최대 티켓가 10%), D-9~D-7 10%, D-6~D-3 20%, D-2~D-1 30%, **당일 90%**. 웹 상단 '예매 취소' 셀프 메뉴.
- **베스트**: **구간별 취소수수료 규정(서버 권위) + 예상 환불액 실시간 표시 + 셀프 취소 + 원결제수단 자동 환불(PG 위임)**. 무료 전시는 노쇼 관리(취소 유도)가 관건.
### ⑤ 개인화 (관심 행사·오픈 알림·최근 본)
- **NOL**: 관심인물/관심공연/관심장르 → 맞춤 추천 + **티켓오픈일 알림(SMS·이메일)**, 예매대기·취소표 우선권.
- **COEX**: 관심분야 선택 → 관련 행사 알림.
- **Whova**: 개인 아젠다·AI 추천 세션·매치메이킹.
- **베스트**: **오픈 알림/관심 행사 구독 + 관심분야 기반 추천 + 최근 본 행사·부스**로 재방문·전환 견인.
### ⑥ 현장 편의 (주차·길찾기·혼잡도)
- **COEX**: 실내 내비(PC→모바일 QR), 주차 혼잡 예보(KakaoT).
- **킨텍스 앱**: 실시간 주차현황·주차비 결제, 할인권.
- **베스트**: **관람객 앱에 wayfinding + 실시간 주차(현황·결제·사전권) + 혼잡/대기 안내를 한 화면 동선**으로 통합. 킨텍스는 GTX-A 킨텍스역·iparking 연계가 차별점.
### ⑦ 멤버십/등급
- **NOL/멜론**: 회원 등급·포인트·간편결제 저장.
- **Whova**: 유형별(참가자/바이어/연사) 배지·권한 차등.
- **베스트**: **관람객 유형(일반/바이어/VIP)·재방문·바이어 인증 등급**으로 혜택·알림·비즈매칭 우선순위 차등. (전시 우선순위는 낮음)
### ⑧ 접근성·다국어
- **COEX/킨텍스**: 다국어 안내·수어 통역(COEX).
- **Whova**: 글로벌 대상 로컬라이즈.
- **베스트**: **티켓·배지·앱 다국어(한/영/중/일) + WCAG AA + QR/텍스트 대체수단**. 국제전시장 특성상 외국인 바이어 대응이 필수.
---
## 3. 킨텍스 자동전시시스템 반영 시사점 (ⓐⓑⓒ 3분류)
> 대조 기준: `design.md` v2.1 — SCR-P7(예매)·SCR-P8(확인·취소)·SCR-M14(모바일 예매)·SCR-M15(티켓 지갑)·SCR-M5(관람객 홈·배지)·SCR-M6(wayfinding)·SCR-M7(플로어플랜)·SCR-M8(비즈매칭)·SCR-M9(세션 아젠다) / `PLANNING.md` M10·M13.
### ⓐ 이미 반영됨 (현행 스펙이 베스트 프랙티스 충족)
| # | 항목 | 현행 근거 |
|---|---|---|
| A1 | 짧은 예매 퍼널(권종→예매자→결제→완료), 게스트+회원, 무료 권종 결제 스킵 | SCR-P7·M14 |
| A2 | PG 위임 결제(카드정보 미저장 안내·카드입력 UI 없음) | SCR-P7 3단계·M14 |
| A3 | 모바일 QR 티켓 지갑 + **자동 밝기 부스트** + 오프라인 캐시 표시 | SCR-M15 |
| A4 | 셀프 예매 확인·취소(게스트 예매번호+이메일 조회), PII 마스킹 | SCR-P8 |
| A5 | 구간별 환불 규정 표(D-7/D-3/당일) + 예상 환불액 + 원결제수단(PG 위임) | SCR-P8 |
| A6 | 티켓→체크인→모바일 배지 상태 승격 흐름 | SCR-M15→M5 |
| A7 | 관심분야 기반 AI 추천 세션·부스, 즐겨찾기 | SCR-M5·M9 |
| A8 | wayfinding(블루닷·존레벨 폴백)·인터랙티브 플로어플랜·비즈매칭 | SCR-M6·M7·M8 |
| A9 | 단체 예매(대표자+동반자 명단 CSV) | SCR-P7 2단계 |
| A10 | WCAG AA·라이트/다크·비시각 대안 목록 | 전 화면 공통 |
### ⓑ 보강 권고 (기존 화면 스펙 수정 후보 · P1)
| # | 권고 | 대상 화면/모듈 | 근거(§2) |
|---|---|---|---|
| B1 | **스마트티켓 부정입장 방지 강화** — 디바이스 바인딩/회전(애니메이션) QR + 본인인증으로 캡처본 무효·양도 방지(현행은 정적 QR) | SCR-M15·31 / M10 | ② 티켓링크 스마트스탬프 |
| B2 | **취소·환불 규정 정교화** — 단순 3구간(100/50/0%)을 인터파크식 다구간 수수료 + 예매수수료 별도 환불 규정으로 확장, 서버 권위 명시 | SCR-P8 / M9·M10 | ④ NOL 취소수수료 |
| B3 | **티켓·배지·관람객 앱 다국어(한/영/중/일)** — 현행 다국어는 공개사이트(M12)만 명시, 티켓·배지·지갑 화면에 다국어 확장 | SCR-P7·M5·M15 / M10·M12 | ⑧ 국제전시장 |
| B4 | **세션 정원 기반 사전등록(RSVP)** — 현행 즐겨찾기는 있으나 정원·마감·대기 미반영. 정원 소진·마감 상태 추가 | SCR-M9 / M11 | ① Whova 개인 아젠다 정원 |
| B5 | **결제수단 사전등록·간편결제 빠른결제** — 재방문·유료 권종 전환율 향상 | SCR-P7·M14 / M9 | ⑤ NOL 빠른결제 |
| B6 | **행사 라이브 공지 피드/현장 푸시** — 알림센터(M11)에 더해 행사별 라이브 공지 피드(긴급 안내·프로그램 변경) | SCR-M11·M5 / §5B notification·M12 | Whova 라이브 공지 |
### ⓒ 신규 화면/기능 후보 (P2 백로그)
| # | 후보 | 대상 화면/모듈 | 근거(§2) |
|---|---|---|---|
| C1 | **티켓 오픈 알림·관심 행사 구독** — 공개사이트+앱에서 오픈 예정 행사 구독→오픈 시 푸시/EDM | 신규(공개사이트·앱) / M10·M12 | ⑤ NOL 오픈알림·COEX 관심알림 |
| C2 | **관람객 앱 주차 연계** — iparking 실시간 현황·주차비 결제·사전 주차권 | 신규 SCR-M(주차) / M14·M10 | ⑥ 킨텍스 앱·COEX 주차예보 |
| C3 | **관람객 대면 혼잡/대기 안내** — 입장·주차·인기 세션 실시간 혼잡도(현행 M14는 홀매니저용) | 신규 위젯(SCR-M5) / M14 | ⑥ COEX 혼잡 예보 |
| C4 | **관람객↔관람객 QR 명함 교환·컨택트 지갑** — 현행 리드캡처는 참가업체→관람객만 | SCR-M8 확장 / M11 | ② Whova QR 명함교환 |
| C5 | **인기 세션/바이어 미팅 예매 대기열·취소표 알림** — 정원 초과 세션·미팅 슬롯 대기 우선권 | SCR-M9·M8 / M11 | ⑤ NOL 예매대기 |
| C6 | **관람객 멤버십/등급** — 일반/바이어/VIP·재방문·바이어 인증 등급별 혜택·매칭 우선순위 | 신규 마이 / M10 | ⑦ 등급 차등 |
| C7 | **최근 본 행사·부스 개인화 홈 피드** — 재방문 전환 | SCR-M5 확장 / M10·M12 | ⑤ 최근 본 |
| C8 | **셀프 체크인 키오스크·즉석 배지 인쇄 화면** — PLANNING M10 즉석배지 언급 있으나 화면 미정의 | 신규 SCR / M10 | ③ Whova 셀프 체크인 키오스크 |
### 톱 5 보강 권고 (우선 반영)
1. **B1 스마트티켓 부정입장 방지**(디바이스 바인딩·회전 QR·본인인증) — 정품 티켓 신뢰의 핵심.
2. **B2 취소·환불 규정 정교화**(다구간 수수료·예매수수료 분리·서버 권위) — 정산 정확성·분쟁 예방.
3. **C1 티켓 오픈 알림·관심 행사 구독** — 개인화·재방문·전환의 최대 레버.
4. **C2 관람객 앱 주차 연계**(iparking 실시간·결제·사전권) — 킨텍스 현장 편의 차별점.
5. **B3 티켓·배지·앱 다국어(한/영/중/일)** — 국제전시장 외국인 바이어 대응 필수.
---
## 4. 출처 URL
- COEX VISITOR(실내 길찾기·주차): https://www.coex.co.kr/ , https://www.coex.co.kr/guide/indoor-navigation/ , https://www.coex.co.kr/guide/parking-information/infomation/
- COEX 행사 일정·관심 알림: https://www.coex.co.kr/event/full-schedules/
- 인터파크 NOL 티켓 취소/환불: https://ticket.interpark.com/TiKi/Info/BookingGuide.asp?Url=guide_05.html
- 인터파크 NOL 티켓 수수료: https://ticket.interpark.com/TiKi/Info/BookingGuide.asp?Url=guide_11.html
- 인터파크 티켓캐스트(오픈 알림): https://ticket.interpark.com/TiKi/Info/BookingGuide.asp?Url=guide_10.html
- 인터파크 예매대기 서비스: https://ticket.interpark.com/TiKi/Info/BookingGuide.asp?Url=guide_13.html
- NOL 인터파크(개인화/오픈예정): https://nol.interpark.com/ , https://tickets.interpark.com/contents/notice
- 멜론티켓 이용안내: https://ticket.melon.com/customerservice/howto.htm
- 티켓링크 스마트티켓: https://www.ticketlink.co.kr/help/guide/popup/smart-ticket
- 티켓링크 앱: https://play.google.com/store/apps/details?id=kr.co.ticketlink.cne
- 멜론티켓 앱: https://play.google.com/store/apps/details?id=com.iloen.melonticket
- 킨텍스 주차/앱 사전등록: https://www.kintex.com/web/ko/service/parking_user.do , https://www.data.go.kr/data/15119880/fileData.do
- Whova 이벤트 앱 기능: https://whova.com/whova-event-app/ , https://whova.com/blog/best-event-conference-apps/
- Eventbrite vs Whova 비교: https://boompop.com/blog/whova-vs-eventbrite-comparison
- 이벤트 체크인 앱 비교: https://qrsage.com/blogs/best-event-check-in-app
---
## 변경 이력
| 날짜 | 변경 내용 |
|---|---|
| 2026-07-11 | 최초 작성 — COEX·NOL/멜론/티켓링크·킨텍스 앱·Whova/Eventbrite 7종 벤치마킹, ⓐ10·ⓑ6·ⓒ8 시사점, 톱5 보강 권고 |

401
plugins/zio-harness/knowledge/kintex/docs/architecture/app.md Normal file
View File

@ -0,0 +1,401 @@
# 킨텍스 자동전시시스템 — 애플리케이션 아키텍처 표준 (app.md)
> 작성: 애플리케이션 아키텍트(AA) · 작성일: 2026-07-11 · 버전: **v1.0** · BACKLOG **A-1**
> 근거: `docs/PLANNING.md` v2.0(§2 6역할 포털·§4 모듈맵·§5 M1~M9·§5A M10~M18·§5B 공통레이어·§8 아키텍처)·`docs/IMPLEMENTATION_BACKLOG.md`(Phase A~E)·`_workspace/01_backend_contracts.md`(P0 계약)·`src/backend` 스캐폴드 실측.
> 스택(확정·불변): React 18/19(Vite·TypeScript) + Spring Boot 3.x(Java 17) + MyBatis + PostgreSQL(PostGIS) + Redis + 나노바나나 Python 워커 사이드카.
>
> **문서 소유권**: 본 문서는 AA만 수정한다. 구현 에이전트(BE/FE/DB/COM/도메인 devs)는 이 표준을 **준수**하며, 위반 발견 시 kintex-qa와 함께 시정한다. 교차 문서(system.md·tech.md·data.md·network.md)와의 정합은 링크로 참조하고 직접 수정하지 않는다.
---
## 0. 목적과 적용 범위
본 문서는 킨텍스 자동전시시스템의 **애플리케이션 구조 일관성**을 규정하는 단일 표준이다. 개별 기능 구현 방식이 아니라 **모듈 경계·레이어링·패키지·API 규격·공통 컴포넌트·의존성 규칙**을 정의한다.
- **적용 대상**: `src/backend`(Spring Boot) 전 모듈, `src/frontend`(React) 전 포털, 나노바나나 워커와의 큐 계약, kintex-common(WISE/UIWS 이식) 공통 레이어.
- **정합 기준**: PLANNING §8/§8-1 아키텍처 개요와 **정합하며 이를 구체화**한다. 상충 시 PLANNING이 상위, 본 문서가 구현 표준.
- **현행 스캐폴드 정합**: 본 표준은 이미 스캐폴드된 실제 구조(§1.2)를 성문화한 것이며, 신규 모듈은 이 패턴을 복제한다. 기존 코드 변경을 요구하지 않는다(성문화·확장).
---
## 1. 패키지 구조 표준
### 1-1. 루트 패키지
전 백엔드 코드는 `com.zioinfo.kintex` 하위에 둔다(GUARDiA 표준 프레임워크 정렬, WISE=`com.zioinfo.*` 관례). 최상위는 **횡단 관심사(cross-cutting)** 와 **도메인 모듈(module)** 로 나뉜다.
```
com.zioinfo.kintex
├── KintexApplication # 부트 진입점
├── common # 횡단: 응답봉투·페이징·에러·감사·유틸 (모듈 무의존)
│ ├── ApiResponse / PageResponse
│ ├── error/ (ErrorCode·ApiException·GlobalExceptionHandler)
│ ├── audit/ (감사 AOP·@Audited — Phase B B-2/B-4)
│ └── code/ (공통코드 조회 캐시 — Phase B)
├── config # 부트 설정: SecurityConfig·WebSocketConfig·RedisConfig·MyBatisConfig
├── auth # 인증/인가: JWT·RBAC·2FA(OTP)·principal·guard (도메인 무관 공용)
│ ├── dto/ · mapper/
├── rules # 룰 엔진: 규정(compliance)·요율(rate) 룰셋 로딩·평가 (서비스 계층)
├── health # 헬스체크
└── module # ★도메인 모듈 루트 — 모듈별 서브패키지
├── m1 … m9 # 판매·운영(배정·서류·매칭·정산·물류)
├── m2 · m3 · m4 · m5 # ★P0 부스 시공 코어
├── m10 · m11 · m12 · m13 · m14 # 관람·참가·마케팅·wayfinding·현장운영
└── m15 · m16 · m17 · m18 # 옥션·BI·CMS·관리자
```
### 1-2. 모듈 내부 구조 (표준 레이아웃 — 스캐폴드 실측)
각 도메인 모듈 `module.mN`은 아래 4계층을 **고정 서브패키지**로 둔다. M2가 정본 참조 패턴이다.
```
module.mN
├── MNController # REST 진입 — 얇게 유지(가드·바인딩·위임만)
├── MNService # 서비스 인터페이스(계약)
├── MNServiceImpl # 서비스 구현(비즈니스 로직·트랜잭션 경계)
├── dto/ # 요청/응답 DTO — record 우선(불변)
│ └── *Dto / *Request / *Response
├── mapper/ # MyBatis 매퍼 인터페이스(@Mapper)
│ └── MNMapper (XML은 resources/mybatis/mapper/)
├── MNProperties (선택) # @ConfigurationProperties 모듈 설정
└── domain/ (선택) # 순수 도메인 모델·값객체(엔티티 매핑 시)
```
> **명명 규칙**: 서비스는 인터페이스(`FloorplanService`) + 구현(`FloorplanServiceImpl`) 분리(스캐폴드 실측). 컨트롤러는 `<도메인명>Controller`. DTO는 `record` 우선(불변·직렬화 안정). 모듈 접두어 `mN`은 패키지에만 쓰고 클래스명은 도메인 어휘(Floorplan·Design·Utility·RenderJob·Auction·Visitor…)를 쓴다.
### 1-3. 리소스 레이아웃
```
src/backend/src/main/resources
├── application.yml # 시크릿·엔드포인트는 env 플레이스홀더만(하드코딩 금지)
├── mybatis/mapper/**/*.xml # 공간 SQL(ST_*) 포함 매퍼 XML — mapper-locations로 로드
└── rulesets/ # 버전 관리 룰셋 데이터(코드 아님)
├── compliance-v1.json (compliance-v1.0)
└── rates-v1.json (rates-v1.0)
```
---
## 2. 레이어링 표준 (controller / service / mapper / domain / dto)
### 2-1. 레이어 책임 경계
| 레이어 | 책임 | 금지 |
|---|---|---|
| **Controller** | HTTP 바인딩, 입력 검증(`@Valid`), RBAC 가드 호출, 서비스 위임, `ApiResponse` 래핑 | 비즈니스 로직·SQL·트랜잭션·매퍼 직접 호출 |
| **Service (interface+Impl)** | 비즈니스 규칙, 트랜잭션 경계(`@Transactional`), 룰 엔진 호출, 매퍼 오케스트레이션, 도메인 예외 발생 | HTTP 타입(HttpServletRequest 등) 참조, 매퍼 XML 로직 침범 |
| **Mapper (MyBatis)** | DB 접근, 공간 SQL(`ST_*`) 바인딩. 인터페이스+XML 쌍 | 비즈니스 분기, DTO 조립(원시 `Map`/도메인 반환까지) |
| **DTO** | 계층·경계 데이터 전달(record 불변) | 로직·영속 어노테이션 |
| **domain / 값객체(선택)** | 순수 도메인 모델·계산(엔티티 매핑 시) | 프레임워크 의존 |
### 2-2. 계층 관통 흐름 (표준)
```
Controller ──(가드: EventAccessGuard)──► Service(interface)
└► ServiceImpl ──► Mapper(@Mapper) ──► PostgreSQL/PostGIS
└──► RuleEngine(rules) (공간 SQL은 XML)
└──► RedisTemplate(비동기 큐/실시간)
결과 DTO ◄── ServiceImpl ◄── Mapper(Map/도메인)
Controller ──► ApiResponse.ok(dto) | 예외 ──► GlobalExceptionHandler ──► ApiResponse.fail
```
- 컨트롤러는 **가드 호출 → 서비스 위임 → 봉투 래핑**만 한다(FloorplanController가 정본). 로직이 컨트롤러에 새면 위반.
- 서비스는 매퍼가 반환한 원시(`Map<String,Object>`/도메인)를 **DTO로 조립**한다. 매퍼는 DTO 조립을 하지 않는다.
- 공간 연산(부스 폴리곤·트렌치 KNN·배선 LineString·면적)은 **서비스가 아니라 매퍼 XML의 PostGIS SQL**로 수행하고 서비스는 스칼라/GeoJSON 결과만 사용한다(스캐폴드 `BoothMapper`·`WiringMapper` 계약).
### 2-3. 트랜잭션·읽기 정책
- 쓰기 서비스 메서드는 `@Transactional`, 조회는 `@Transactional(readOnly=true)`.
- **낙관적 잠금**: 배치·설계 등 버전 있는 리소스는 `version` 불일치 시 `CONFLICT`(409). (LayoutSaveRequest·DesignSaveRequest에 `version` 존재.)
- **BI(M16)**: 운영 DB 직조회 금지 — KpiSnapshot/데이터마트(스타 스키마) 또는 읽기 전용 경로로 격리(PLANNING §8-1·M16-1, 상세는 data.md DA 트랙).
---
## 3. 모듈 경계와 분류
### 3-1. 모듈 3계열 + 공통 레이어
| 계열 | 모듈 | 패키지 | 우선순위 | 비고 |
|---|---|---|---|---|
| **공통 레이어(선행 기반)** | 인증·시스템관리·공통업무기능 | `auth`·`common`·`module.m18`(system)·공통 모듈 | P1(전 모듈 선행) | §5B WISE/UIWS 이식 |
| **P0 부스 시공 코어(불변·심장)** | M2 플로어플랜·M3 부스설계·M4 유틸리티·M5 나노바나나 | `module.m2~m5` | **P0** | 스캐폴드 완비 |
| 판매·운영 | M1 배정견적·M6 서류·M7 매칭·M9 정산·M8 물류 | `module.m1·m6·m7·m9·m8` | P1/P2 | |
| 발주·계약 | **M15 공사/장치 옥션** | `module.m15` | **P1(핵심 플로우)** | 폐루프 연결고리 |
| 관람·참가·마케팅 | M10 관람객·M11 매칭·M12 마케팅/공개사이트·M13 wayfinding·M14 현장운영 | `module.m10~m14` | P1/P2 | |
| 경영·콘텐츠·관리 | M16 BI·M17 CMS·M18 관리자 | `module.m16·m17·m18` | P1 | |
### 3-2. 공간 데이터 공유 원칙 (불변)
M2(부스 폴리곤)→M3(부스 내부)→M4(배선)→M5(시각화)는 **하나의 PostGIS 공간 데이터 모델을 공유**한다. M13 wayfinding·M14 부하집계·M16 ㎡당 수익은 **동일 원천(Booth 폴리곤·Wiring LineString)을 재사용**한다. → 공간 지오메트리 소유는 **M2/M4 매퍼가 권위**이며, 소비 모듈은 조회만 한다(중복 저장 금지).
### 3-3. 권위(ownership) 경계 — 중복 제거 (PLANNING §5B-2 규칙)
| 관심사 | 권위 모듈 | 소비 모듈(읽기/이벤트) |
|---|---|---|
| 경영·수익 지표 | **M16 BI** | 대시보드·포털 |
| 일상 업무보고·통계 | 공통 `report/stats` | — |
| 콘텐츠·공지 발행 | **M17 CMS** | 공개사이트·사이니지 |
| 사내 알림성 공지 | 공통 `notice` | — |
| 알림 발송 채널 | 공통 `notification`(단일화) | M10·M12·M15(이벤트 발행) |
| 사용자·역할·공통코드·감사·마스터데이터 | **M18(=system)** | 전 모듈(RBAC·룰셋 공급) |
| 규정·요율 룰셋 | `rules` + M18(버전 관리) | M1·M2·M3·M4 |
---
## 4. 의존성 규칙 (참조 방향·순환 금지)
### 4-1. 허용 참조 방향 (단방향)
```
module.mN ──► rules · auth · common (횡단 계층 참조 허용)
module.mN ──► module.mK (오직 §4-2 표에 명시된 방향만, 하위→상위 데이터 소비)
common ──► (무의존) ★common은 어떤 module·auth·rules도 참조하지 않는다
auth ──► common (에러·봉투만)
rules ──► common
config ──► auth · common (보안/웹소켓/레디스 배선)
```
**철칙**: `common`은 순수 횡단 유틸(봉투·에러·감사·페이징)로 **어떤 도메인/인증/룰도 모른다**. 도메인 모듈이 common을 참조하지, 그 역은 없다.
### 4-2. 모듈 간 참조(도메인) — 명시 방향만 허용
PLANNING §4 모듈맵의 데이터 흐름을 코드 의존으로 옮긴다. **화살표 방향으로만 참조**(소비자→생산자 조회, 순환 금지).
| 소비 모듈 | 참조(생산) 모듈 | 목적 |
|---|---|---|
| M3 → M2 | 부스 좌표·행사 역참조 |
| M4 → M2 | 트렌치·부스 지오메트리 |
| M5 → M2·M3·M4 | 씬 컴파일 입력(scene) |
| M15 → M2·M3·M4·M5·M7 | 옥션 자료 패키지·등록업체 검증 |
| M9 → M1·M4·M15 | 정산 대상(배정·유틸·낙찰) |
| M13 → M2 | wayfinding 지오메트리 |
| M14 → M4·M10 | 부하·체크인 파생 |
| M16 → 전 모듈 | 지표 소비(읽기 전용/스냅샷) |
| M12 → M10·M17 | 세그먼트·콘텐츠 |
- **순환 금지**: 위 표에 역방향이 필요하면 **직접 참조 대신 이벤트(알림 큐)·공유 식별자**로 디커플. 예: M15 낙찰→M9는 M15가 M9를 호출하는 것이 아니라 **도메인 이벤트/발주 링크**로 전달(순환 회피).
- **모듈 간 결합은 서비스 인터페이스로만**: `mK.MKService`를 주입해 쓰고, 상대 모듈의 `mapper`·`ServiceImpl`·`dto` 내부를 직접 참조하지 않는다(계약 경유).
- **공간 원천**은 M2/M4 매퍼가 권위(§3-2) — 타 모듈은 그 서비스로 조회.
- 검증: 빌드 타임 아키텍처 테스트(ArchUnit 권장, tech.md TA 트랙)로 `common→module` 역참조·모듈 순환을 CI에서 차단.
---
## 5. REST API 설계 표준
### 5-1. 경로·버전
- **베이스**: `/api`. 공개(비인증) 홍보/워커 경로는 `/api/public/**`·`/api/internal/**` 접두어로 분리.
- **행사 스코프 리소스**: `/api/events/{eventId}/…` 하위에 배치(모든 도메인 리소스는 `{eventId}` 스코프). 중첩 예:
- M2 `…/events/{eventId}/halls/{hallId}/layout`
- M3 `…/events/{eventId}/booths/{boothId}/design`
- M4 `…/events/{eventId}/booths/{boothId}/utility`
- M5 `…/events/{eventId}/booths/{boothId}/render` · `…/events/{eventId}/render-jobs/{jobId}`
- **플랫폼(비행사) 리소스**: `/api/admin/**`(M18·백오피스, `hasRole(ADMIN)` 게이트), `/api/auth/**`(인증), `/api/me/**`(개인).
- **버전 정책**: P0/P1은 무접두 `/api`(단일 버전). **파괴적 변경 시에만** `/api/v2/…` 도입. 계약 진화는 **후방호환 우선**(필드 추가는 non-breaking, 제거·의미변경만 버전 상향). 룰셋·계약 semver는 페이로드의 `rulesetVersion`으로 별도 표기(코드 API 버전과 분리).
- **동사 규약**: 자원 CRUD는 표준 HTTP 메서드. 비 CRUD 액션은 하위 동사 세그먼트(`/validate`·`/auto-generate`·`/precheck`·`/quote`·`/wiring`·`/order`·`/render`)로 표현(스캐폴드 실측 패턴). 액션은 POST.
### 5-2. 응답 봉투 (ApiResponse<T> — 스캐폴드 정본)
모든 REST 응답은 `common.ApiResponse<T>`를 사용한다(예외 없음).
```json
{ "success": true, "data": { ... }, "error": null }
{ "success": false, "data": null, "error": { "code": "FORBIDDEN", "message": "요약 메시지" } }
```
- 성공은 컨트롤러가 `ApiResponse.ok(dto)`. 실패는 **던지고**(ApiException) `GlobalExceptionHandler`가 봉투로 변환(컨트롤러에서 실패 봉투 수동 조립 금지).
- **목록**: `common.PageResponse<T>` = `{ items, page, size, total }`. (P0 갤러리/워크스페이스처럼 소량 고정 목록은 배열 직접 반환 허용 — 계약 §0-1.)
### 5-3. 오류 코드 → HTTP (ErrorCode enum — 안정 계약)
`common.error.ErrorCode`가 코드↔HTTP 단일 매핑. 신규 코드는 여기에만 추가한다.
| code | HTTP | 의미 |
|---|---|---|
| `VALIDATION` | 400 | 요청 값 오류(필드 메시지) |
| `UNAUTHORIZED` | 401 | 미인증/토큰 만료 |
| `FORBIDDEN` | 403 | 행사/부스/역할 권한 없음 |
| `NOT_FOUND` | 404 | 대상 없음 |
| `CONFLICT` | 409 | 상태/버전 충돌(낙관적 잠금) |
| `COMPLIANCE_BLOCKED` | 422 | 규정 위반(차단) |
| `RENDER_QUOTA_EXCEEDED` | 429 | 이미지 생성 쿼터 소진 |
| `NOT_REGISTERED_COMPANY` | 403 | 미등록 장치업체 차단 |
| `NOT_IMPLEMENTED` | 501 | 매퍼/엔진 구현 대기(스켈레톤) |
| `INTERNAL` | 500 | 서버 오류(요약만) |
- **미구현 지점**은 `ApiException.notImplemented(...)`(501) 표준 사용 — 계약은 확정하되 매퍼/워커 대기 구간 표시(스캐폴드 관례).
- 도메인 확장 코드(옥션 마감·배지 만료 등)는 계열 접두 없이 `ErrorCode`에 추가하고 본 표에 반영(AA 승인).
### 5-4. 페이징·정렬·필터
- 쿼리 파라미터: `page`(0-base)·`size`(기본 20, 상한 100)·`sort=field,asc|desc`. 응답은 `PageResponse<T>`.
- 필터는 명시 쿼리 파라미터(자유 텍스트 SQL 금지). 통합검색(공통 search)은 별도 검색 서비스 경유.
### 5-5. 인증 헤더·공개 경로
- `Authorization: Bearer <JWT>`(HS256). 클레임: `sub`(userId)·`name`·`roles`(eventId→역할)·`hm`(홀매니저)·(Phase B 확장) `plat`(플랫폼 역할 ADMIN 등)·`otp`(2FA 통과 플래그).
- **무상태**(SessionCreationPolicy.STATELESS). CSRF disable, CORS는 config에서 관리.
- **공개(permitAll)**: `GET /health`, `POST /api/auth/login`, `/ws/**`, `POST /api/internal/render/callback`(워커 토큰), (Phase D) `/api/public/**`(공개 홍보사이트 조회). 그 외 전부 인증.
- 내부 워커 콜백은 `X-Worker-Token`(env) 검증. 공개사이트는 읽기 전용(행사 데이터 쓰기 불가).
### 5-6. 보안 불변 (API 계약 강제 — 위반 시 QA 반려)
1. **스택트레이스·내부 세부 미노출** — `error.message`는 사람이 읽을 요약만, 상세는 서버 로그. (`server.error.include-*: never` + GlobalExceptionHandler.)
2. **민감정보 응답 완전 제외** — IP·SSH·비밀번호·`os_pw_enc`·해시·내부 식별자. 사용자/업체는 이름·역할·번호 등 비민감 필드만.
3. **`GEMINI_API_KEY`는 백엔드가 다루지 않는다** — 나노바나나 Python 워커 전용. M5는 큐 발행까지만.
4. **AI 생성 이미지 응답은 항상** `watermarkRequired:true`+`watermarkText`+`notice`(계약·심사 서류 사용 금지) 포함(제거 불가, PLANNING §6-5).
5. **admin 비번**은 env `ADMIN_PASSWORD_ENC`(AES-256-GCM)+별도 키파일 주입, `admin123` 하드코딩 금지(§5B-3).
---
## 6. 인증·인가 아키텍처 (이중 RBAC)
PLANNING §2 6역할·§8-1 SSO 이중 권한을 코드 모델로 표준화한다. 인증 스택은 **WISE/UIWS 표준 이식**(JWT+2FA/OTP), 그 위에 킨텍스 행사 RBAC를 얹는다(재설계 금지).
### 6-1. 이중 권한 평가
| 계층 | 대상 | 저장/평가 | 게이트 |
|---|---|---|---|
| **플랫폼 역할(platform)** | ADMIN(백오피스), 셀프서비스(VISITOR/PUBLIC) | JWT `plat` 클레임 + Spring `hasRole` | `/api/admin/**`=`hasRole(ADMIN)`(§5B-1) |
| **행사 역할(event)** | ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER | JWT `roles`(eventId→역할)·`hm`, `KintexPrincipal.roleFor(eventId)` | `EventAccessGuard.requireRole(...)` |
- **현행 스캐폴드**(P0): `EventRole`(4역할) + `KintexPrincipal.hallManager` 플래그 + `EventAccessGuard`(require/requireEventAccess/requireRole). 이 4역할 게이트가 정본.
- **Phase B 확장**: 플랫폼 역할(ADMIN)·관람객 셀프서비스 계정·2FA(OTP)·로그인 실패 잠금을 `auth`에 추가(WISE `TotpService` 이식). `EventRole`은 유지, 플랫폼 역할은 별도 축으로 평가(직교).
### 6-2. 가드 사용 규약 (컨트롤러 표준)
```
guard.requireEventAccess(principal, eventId); // 열람: 멤버 or 홀매니저
guard.requireRole(principal, eventId, EventRole.ORGANIZER); // 편집/액션: 역할 한정
guard.requireRole(principal, eventId, EventRole.ORGANIZER, HALL_MANAGER); // 복수 허용
```
- **열람=행사 멤버 or 홀매니저 / 편집·액션=역할별**(계약 §0-5). 홀매니저는 전 행사 열람+승인(`hasAccess`가 항상 true).
- **등록업체 게이트(불변)**: CONTRACTOR 초대 수락·M15 응찰은 `companyRegistrationNo` 킨텍스 등록업체 검증 필수 → 미등록 `NOT_REGISTERED_COMPANY`(403). M7이 검증 권위.
- 가드는 **컨트롤러에서** 호출한다(서비스 진입 전). 서비스는 이미 인가된 것으로 가정하되, 크로스-모듈 호출 시 재검증이 필요하면 호출 측이 책임.
### 6-3. 개인정보·감사
- 리드캡처(M10)·관람객 데이터는 개인정보 — 동의·보존정책 필수(PLANNING R10). 접근은 소유 참가업체+주최자+홀매니저로 한정.
- **감사 대상**(§5B-1): 승인·**낙찰(M15)**·설계 변경·룰셋 개정·리드 접근을 `common.audit` AOP로 전수 기록(§7-3).
---
## 7. 공통 컴포넌트 표준 (kintex-common / WISE 정합)
공통 레이어는 `workspace/uiws`(WISE=GUARDiA 표준 프레임워크) 이식을 원칙으로 하되, 아래 컴포넌트는 **kintex 스캐폴드가 이미 정의한 계약을 정본**으로 삼는다(재설계 금지, 이식 시 정합).
### 7-1. 응답 봉투·페이징
- `common.ApiResponse<T>`(record: success·data·error{code,message})·`common.PageResponse<T>`. §5-2 정본. 모든 응답 필수.
### 7-2. 예외 체계
- `common.error.ErrorCode`(enum, HTTP 매핑) → `ApiException`(코드+요약 메시지) → `@RestControllerAdvice GlobalExceptionHandler`(봉투 변환·로그 격리). 3자 세트가 표준(§5-3). 신규 예외는 `ApiException`+`ErrorCode`만 사용(RuntimeException 남발 금지 — 최종 방어선만 `INTERNAL`).
### 7-3. 감사 AOP (Phase B B-2/B-4)
- `common.audit.@Audited` 어노테이션 + AOP 어드바이스로 상태 변경 API를 `TB_AUDIT_LOG`에 기록(액터·행사·대상·before/after 요약·룰셋 버전). **민감정보·비번·스택트레이스 미기록**(§5-6 정합). WISE `TB_AUDIT_LOG` 스키마 이식.
### 7-4. 공통코드 (Phase B)
- `common.code`가 코드 그룹/상세를 캐시 제공(홀·부스유형·공종 14분류·유틸리티 요금코드 등 도메인 코드 포함). 권위는 M18(system). 도메인 모듈은 하드코딩 대신 공통코드 조회.
### 7-5. 룰셋(버전 관리 데이터)
- `rules`가 `rulesets/*.json`(compliance·rate)을 로드·평가. **코드가 아닌 데이터** — 개정 시 파일 교체·`rulesetVersion` 리포트 기록(감사·면책, PLANNING R2). 연산자: `lte·gte·between·isTrue·eq·lteHall·excludesAll`.
### 7-6. 알림 단일화 (§5B-2)
- 발송 채널은 공통 `notification` 단일. 도메인 모듈(M10·M12·M15)은 직접 발송하지 않고 **이벤트를 발행**한다(마감 리마인더·낙찰·승인·결제 알림). WebSocket 실시간 경로는 §8.
### 7-7. 프론트 공통(FE, Phase B B-4)
- 2FA 화면·공통코드·검색바·그리드·달력·모달·파일업로드는 **공유 컴포넌트 라이브러리**로(WISE 이식, design.md 토큰 정합). 역할별 포털이 상속(중복 구현 금지).
---
## 8. WebSocket 이벤트 규격 (STOMP)
`config.WebSocketConfig` 정본. 실시간 진행/이벤트 푸시는 STOMP over WebSocket으로만 한다(REST 폴링 지양).
- **핸드셰이크**: `GET /ws`(SockJS). 공개 경로(핸드셰이크 후 STOMP CONNECT 헤더에 JWT 전달 — 인가는 구독 시점 평가).
- **prefix**: 서버→클라 브로드캐스트 `/topic`, 클라→서버 `/app`.
- **토픽 네이밍 표준**: `/topic/<도메인>/<식별자>`.
| 토픽 | 이벤트 | 발행 시점 | 대상 |
|---|---|---|---|
| `/topic/render/{jobId}` | `RenderJobDto`(DONE/FAILED) | 워커 콜백 relay(M5) | 발행 멤버 |
| `/topic/auction/{auctionId}` | 순위/라운드 마감(M15) | 응찰·타이머 | 옥션 참여 업체 |
| `/topic/events/{eventId}/notifications` | 알림(승인·마감·결제) | 공통 notification | 행사 멤버 |
| `/topic/events/{eventId}/checkin` | 입장/혼잡(M10·M14) | 체크인 | 홀매니저/주최자 |
- **페이로드는 REST DTO 재사용**(RenderJobDto 등) — 별도 WS 전용 스키마 금지(계약 일원화).
- **인가**: 구독 대상이 행사/부스 스코프면 CONNECT 시 신원 + 구독 시 접근 검증(민감 토픽 무단 구독 차단). 브로드캐스트에도 §5-6 민감정보 제외 동일 적용.
- 나노바나나·서류·알림은 **동일 비동기 패턴**: REST가 Redis 큐 발행 → 워커/서비스 처리 → WS 완료 푸시.
---
## 9. 비동기·큐 계약 (Redis · Python 워커)
- **RenderJob 큐**: `kintex:renderjob:queue`(env `RENDER_QUEUE_KEY`). 백엔드가 scene 페이로드(§6-2 PLANNING) leftPush → Python 워커 소비. 상태 `kintex:renderjob:job:{jobId}`, 쿼터 `kintex:renderjob:quota:{eventId}`(스캐폴드 실측 키).
- **성공 시에만 쿼터 차감**(PLANNING §6-5). 실패 에러는 `safeError`로 요약만 통과(스택트레이스 유입 차단).
- **워커 결합은 얇은 큐 계약으로만** — 백엔드는 큐잉·상태·콜백·WS relay만, 나노바나나 실호출·방어 로직은 워커(§6-4 PLANNING). `GEMINI_API_KEY` 백엔드 미접촉.
- 옥션 실시간 순위·라운드 마감 타이머, 서류/알림 생성도 Redis 재사용(동일 패턴). BI 집계는 배치/스냅샷(§2-3).
- **G1 게이트**: Gemini 외부 호출 미승인 시에도 큐잉/상태는 동작(목/degraded). 실호출·배포는 소유자 승인 후.
---
## 10. 역할별 프론트/백엔드 모듈화 원칙
### 10-1. 프론트 — 역할별 번들 분리 (PLANNING §2-1·§8-1)
6개 프론트를 **역할별 번들·도메인/서브패스 분리**로 배포해 최소권한·공격면 축소. **공유 디자인 시스템·공유 컴포넌트·공유 API 계약을 상속**(중복 구현 금지).
| 프론트 | 도메인(예) | 주 사용 모듈 | 채널 |
|---|---|---|---|
| 주최자 콘솔 | `organizer.` | M1·M2·M6·M15·M16·M12 | 데스크톱 주력 |
| 참가업체 포털 | `exhibitor.` | M3·M4·M5·M10·M11·M15·M9 | 데스크톱+모바일(리드캡처) |
| 업체 포털 | `contractor.` | M3·M4·M15·M8·M7 | 데스크톱+모바일(현장) |
| 운영 대시보드 | `ops.` | M2·M6·M8·M14·M16 | 데스크톱+모바일(검수) |
| 관리자 백오피스 | `admin.` | M18 | 웹 전용 |
| 공개/관람객 | `www`·`expo.` | M12·M10·M11·M13·M17 | 공개 SEO/SSR + 관람객 모바일 |
- **공유 계층**(모노레포 워크스페이스 권장): `packages/api-client`(계약 타입·fetch 래퍼·ApiResponse 언랩), `packages/ui`(공유 컴포넌트·디자인 토큰 `tokens.css`), `packages/auth`(JWT·2FA·라우팅 가드). 각 포털 앱은 이를 의존(역참조 금지).
- **기술 표준(스캐폴드)**: React 18 + Vite + TS, `react-router-dom`·`@tanstack/react-query`(서버 상태)·`zustand`(클라 상태)·`@stomp/stompjs`+`sockjs-client`(WS). 상세 빌드·라우팅은 tech.md(TA).
- **공개 홍보사이트(M12/M17)**: SEO/SSR·다국어(한/영/중/일)·CDN — 인증 앱과 **별도 렌더 경로**(공개 성능·검색 노출). 쓰기 불가.
### 10-2. 백엔드 — 단일 공유 모놀리식(모듈러) (PLANNING §8-1)
- **공유 Spring Boot 백엔드 1개**(모든 포털이 SSO+RBAC로 접근). 역할별로 백엔드를 쪼개지 않는다 — **모듈러 모놀리스**(`module.mN` 경계 + §4 의존 규칙)로 경계를 코드 레벨에서 강제.
- API 노출은 경로 접두(`/api/events/**`·`/api/admin/**`·`/api/public/**`)와 RBAC로 역할별 표면을 나눈다(별도 서비스 아님).
- 장래 서비스 분리가 필요하면 §4 모듈 경계가 분할선(느슨한 결합·이벤트 디커플이 선행 조건).
---
## 11. 신규 모듈 추가 체크리스트 (구현 에이전트용)
새 도메인 모듈(mN) 추가 시 본 표준 준수 확인:
1. 패키지 `com.zioinfo.kintex.module.mN` + 4계층(Controller·Service/Impl·dto·mapper) 생성(§1-2).
2. 컨트롤러는 가드→위임→`ApiResponse` 래핑만(§2-2, FloorplanController 패턴 복제).
3. 경로 `/api/events/{eventId}/…`(행사 스코프) 또는 `/api/admin/**`(플랫폼)(§5-1).
4. DTO는 record, 목록은 `PageResponse`, 오류는 `ApiException`+`ErrorCode`(§5-2/5-3).
5. 공간 데이터는 M2/M4 매퍼 권위 재사용(§3-2), 신규 지오메트리만 자기 매퍼 XML(PostGIS).
6. 크로스 모듈은 상대 `Service` 인터페이스로만, §4-2 방향 준수·순환 금지(이벤트 디커플).
7. 실시간은 `/topic/<도메인>/<id>` STOMP, 비동기는 Redis 큐(§8/§9).
8. 감사 대상 액션에 `@Audited`(§7-3), 알림은 `notification` 이벤트 발행(§7-6).
9. 보안 불변 5종(§5-6) 자체 점검 → QA 반려 방지.
10. 미완 구간은 `ApiException.notImplemented(...)`(501)로 계약만 확정(스캐폴드 관례).
---
## 12. 교차 아키텍처 참조 (링크)
- 시스템·NFR·배포 토폴로지 → `docs/architecture/system.md`(SA)
- 기술 표준·빌드/관측성·AiTextRouter → `docs/architecture/tech.md`(TA)
- 전사 ERD·공간데이터·마스터·BI 데이터마트 → `docs/architecture/data.md`(DA)
- DMZ/내부망·방화벽·외부 아웃바운드(Gemini) → `docs/architecture/network.md`(NA)
- P0 백엔드 API 계약(정본 예시) → `_workspace/01_backend_contracts.md`
- 기획·모듈 정의 → `docs/PLANNING.md` v2.0 · 실행 → `docs/IMPLEMENTATION_BACKLOG.md`
---
## 13. 변경 이력
| 버전 | 일자 | 작성자 | 내용 |
|---|---|---|---|
| v1.0 | 2026-07-11 | AA | 최초 — A-1. 패키지 구조(`com.zioinfo.kintex`)·4계층 레이어링·모듈 경계(P0 코어 M2~M5·도메인 M10~M18·공통 레이어 §5B)·의존성 규칙(common 무의존·모듈 단방향·순환 금지)·REST 표준(경로/버전/봉투/에러/페이징/인증)·이중 RBAC(플랫폼+행사)·WebSocket STOMP 규격·공통 컴포넌트(WISE 정합)·Redis 큐 계약·역할별 프론트 번들 분리 + 모듈러 모놀리스 백엔드. 스캐폴드(`src/backend`) 실측 정합, PLANNING v2.0 §8 정합. |

881
plugins/zio-harness/knowledge/kintex/docs/architecture/data.md Normal file
View File

@ -0,0 +1,881 @@
# 킨텍스 자동전시시스템 — 데이터 아키텍처 (A-4)
> 작성: kintex-data-architect(DA) · 작성일: 2026-07-11 · 버전: **v1.0**
> 근거: [`docs/PLANNING.md`](../PLANNING.md) v2.0(§5A M15/M16·§5B 공통코드·§7 ERD·§8 아키텍처) · [`_workspace/01_backend_contracts.md`](../../_workspace/01_backend_contracts.md)(P0 API 계약·§8 매퍼 인수) · [`docs/COMMON_CODES.md`](../COMMON_CODES.md)(공통코드) · [`docs/assets/floorplans/README.md`](../assets/floorplans/README.md)(홀 실측·트렌치 CAD) · 룰셋 `rulesets/compliance-v1.json`·`rates-v1.json`
> **문서 소유권(DA 트랙)**: 본 문서는 **데이터 모델·표준·거버넌스의 단일 출처**다. 물리 스키마(DDL·PostGIS·MyBatis 매퍼 XML) **구현은 kintex-db-engineer**가 담당하며, 본 문서는 그 구현 대상(target model)·표준·검수 기준을 정의한다. DA는 설계·표준·검수만 하고 `src/backend/**/db`·매퍼는 수정하지 않는다.
> 정합 대상: A-1 app.md(AA)·A-2 system.md(SA)·A-3 tech.md(TA)·A-5 network.md(NA) — 상충 발견 시 A-6(reviewer) 티켓화.
---
## 0. 범위·계층·원칙
### 0-1. 데이터 아키텍처 스코프
| 계층 | 대상 | 저장소 |
|---|---|---|
| 공통·시스템관리 (WISE/UIWS 이식) | 사용자·역할·공통코드·메뉴·감사·업무모듈 | PostgreSQL `TB_*` |
| 도메인 (킨텍스 코어 P0) | 행사·홀·부스·설계·유틸리티·렌더잡 | PostgreSQL + **PostGIS** |
| 도메인 (v2.0 확장) | 옥션·관람객/리드·CMS·마스터데이터 | PostgreSQL |
| 마스터·룰셋 (버전 관리 데이터) | 홀·요율·유틸요금·규정 룰셋·등록업체 | 파일(룰셋 JSON) + `TB_*` 마스터 |
| BI 데이터마트 (M16) | Fact/Dim 스타 스키마 + KpiSnapshot | PostgreSQL(별도 스키마 `mart`) / 읽기 전용 복제 |
| 대용량 바이너리 | 도면·생성 이미지·서식·견적 PDF | 오브젝트 스토리지(경로만 DB) |
### 0-2. 설계 원칙 (불변)
1. **단일 공간 원천**: 부스 폴리곤·트렌치 포인트·배선 LineString은 **PostGIS 단일 지오메트리 원천**. M2 검증·M4 라우팅·M5 시각화·M13 wayfinding·M14 부하집계·M16 ㎡당 수익이 **같은 지오메트리를 재사용**(PLANNING §7-3 불변, §4 설계원칙 (1)).
2. **룰셋은 데이터**: 요율·규정은 코드가 아닌 **버전 관리 파일**(`compliance-v*.json`·`rates-v*.json`). 모든 산출물에 `rulesetVersion`·`disclaimer` 각인(감사·면책). 마스터데이터 개정은 M18 백오피스에서 무중단 반영.
3. **PII 최소수집·분리·암호화**: 관람객/리드 개인정보는 §5 분류·보존·동의·암호화 정책을 강제. 민감 컬럼은 API 응답에서 완전 제외(계약 §0-3).
4. **운영/분석 분리**: 경영 지표는 운영 DB 직조회 금지 — **BI 데이터마트(스타 스키마)** 배치 적재 또는 읽기 전용 복제로 운영 부하 회피(PLANNING §8-1).
5. **이식 우선(재설계 금지)**: 공통·시스템·인증 스키마는 `workspace/uiws` `TB_*`를 이식(멱등 DDL). 킨텍스 고유는 도메인 테이블에만.
---
## 1. 전사 데이터 모델 — 개념(Conceptual)
### 1-1. 개념 ERD (도메인 영역)
```mermaid
erDiagram
EVENT ||--o{ HALL_ASSIGNMENT : "배정"
HALL ||--o{ HALL_ASSIGNMENT : "가용"
HALL_ASSIGNMENT ||--o{ LAYOUT : "배치안(버전)"
LAYOUT ||--o{ BOOTH : "부스(폴리곤)"
HALL ||--o{ TRENCH : "트렌치 그리드"
BOOTH ||--o{ DESIGN_PLAN : "설계안(버전)"
BOOTH ||--o{ UTILITY_ORDER : "유틸리티 신청"
UTILITY_ORDER ||--o{ WIRING_PATH : "배선(LineString)"
BOOTH ||--o{ RENDER_JOB : "시각화 샷"
EVENT ||--o{ EVENT_MEMBER : "참여자(RBAC)"
USER ||--o{ EVENT_MEMBER : "소속"
COMPANY ||--o{ EVENT_MEMBER : "업체계정"
EVENT ||--o{ AUCTION : "옥션(M15)"
AUCTION ||--o{ QUOTATION : "견적서=응찰"
AUCTION ||--o| AWARD : "낙찰"
COMPANY ||--o{ QUOTATION : "응찰업체(등록검증)"
BOOTH ||--o{ AUCTION : "자료첨부"
EVENT ||--o{ REGISTRATION : "관람객 등록(M10)"
VISITOR ||--o{ REGISTRATION : "관람객"
REGISTRATION ||--o{ BADGE : "배지/QR"
BADGE ||--o{ CHECK_IN : "체크인"
BOOTH ||--o{ LEAD : "리드캡처"
VISITOR ||--o{ LEAD : "스캔대상"
EVENT ||--o{ SETTLEMENT : "정산(M9)"
EVENT ||--o{ DOCUMENT : "서류/마일스톤(M6)"
EVENT ||--o{ CONTENT : "CMS(M17)"
EVENT ||--o{ FACT_MART : "BI 집계(M16)"
```
### 1-2. 주제영역(Subject Area) 맵
| 주제영역 | 핵심 엔티티 | 소유 모듈 | 특성 |
|---|---|---|---|
| **행사·조직·권한** | Event, User, Company, EventMember, Role | §5B·M18 | 마스터·RBAC 기준축 |
| **공간·시설** | Hall, HallFeature, Trench | M2·마스터 | PostGIS 지오메트리 |
| **설계·시공(P0)** | Layout, Booth, DesignPlan, UtilityOrder, WiringPath, RenderJob | M2~M5 | 버전·공간·비동기 |
| **발주·정산** | Auction, Quotation, Award, Settlement, PaymentSchedule, Document | M6·M9·M15 | 금액·계약·감사 |
| **관람·참가** | Visitor, Registration, Badge, CheckIn, Lead, Meeting | M10·M11 | **PII 집중 영역** |
| **콘텐츠·마스터** | Content, Microsite, MasterData, Ruleset | M17·M18 | 다국어·버전 |
| **분석(BI)** | FactBooking/Settlement/Utility/Auction/Visitor, Dim*, KpiSnapshot | M16 | 스타 스키마·집계 |
| **공통·감사** | AuditLog, CodeGroup, Code, Menu, Notification | §5B | 이식·전 모듈 공유 |
---
## 2. 전사 데이터 모델 — 논리·물리(Logical/Physical)
> 물리 테이블은 kintex-db-engineer가 구현. 아래는 **표준 대상 모델**(테이블·컬럼·타입·제약). 명명 규칙은 §4. `geom` 컬럼 상세는 §3.
### 2-1. 코어 P0 물리 ERD
```mermaid
erDiagram
TB_EVENT {
uuid event_id PK
varchar event_name
date start_date
date end_date
varchar status
timestamptz created_at
}
TB_HALL {
varchar hall_id PK "H1..H10, 반홀 H1A"
varchar hall_name
numeric area_m2
numeric floor_load_t_per_m2
numeric width_m
numeric depth_m
numeric ceiling_m
varchar floor_finish "concrete_polished|carpet"
int booth_capacity
geometry footprint "Polygon,0"
}
TB_HALL_ASSIGNMENT {
uuid assignment_id PK
uuid event_id FK
varchar hall_id FK
date occupy_from
date occupy_to
}
TB_BOOTH {
uuid booth_id PK
uuid layout_id FK
varchar booth_no "A-102"
varchar booth_type "independent|assembled"
numeric width_m
numeric depth_m
numeric height_m
numeric floor_load_t_per_m2
boolean premium
uuid assigned_company_id FK "nullable"
geometry geom "Polygon,0 · 홀로컬"
}
TB_LAYOUT {
uuid layout_id PK
uuid assignment_id FK
int version
varchar name
varchar status "draft|submitted|approved|rejected"
int source_option "선택/병합 출처 안번호"
jsonb merge_provenance "병합 출처 레이어"
timestamptz updated_at
}
TB_TRENCH {
uuid trench_id PK
varchar hall_id FK
varchar supply_matrix "power,water,air,gas,network 비트/배열"
boolean assumed "가정 그리드 여부(R4)"
geometry geom "Point,0 · 탭포인트"
geometry run_geom "LineString,0 · nullable"
}
TB_DESIGN_PLAN {
uuid design_id PK
uuid booth_id FK
int version
varchar status
jsonb spec "DesignSpec"
timestamptz updated_at
}
TB_UTILITY_ORDER {
uuid order_id PK
uuid booth_id FK
varchar status "draft|submitted|relayed"
jsonb quote "UtilityQuote 스냅샷"
varchar rateset_version
varchar location_diagram_url
timestamptz created_at
}
TB_WIRING_PATH {
uuid wiring_id PK
uuid order_id FK
varchar kind "power|network|plumbing|air"
numeric kw "nullable"
numeric length_m
geometry geom "LineString,0"
}
TB_RENDER_JOB {
uuid job_id PK
uuid booth_id FK
uuid event_id FK
varchar shot_preset "S1..S7"
varchar status "QUEUED|RUNNING|DONE|FAILED"
varchar image_url
varchar schema_hash "캐시키"
varchar model_version
varchar error_message "요약만"
timestamptz created_at
}
TB_COMPANY {
uuid company_id PK
varchar company_name
varchar registration_no "사업자번호(등록검증)"
varchar category_code "14분류 CONTRACTOR_CATEGORY"
varchar region
boolean kintex_registered "미등록 응찰 차단 게이트"
}
TB_EVENT_MEMBER {
uuid member_id PK
uuid event_id FK
uuid user_id FK
uuid company_id FK "nullable"
uuid booth_id FK "nullable · 참가업체 부스 스코프"
varchar event_role "ORGANIZER|EXHIBITOR|CONTRACTOR|HALL_MANAGER"
}
TB_EVENT ||--o{ TB_HALL_ASSIGNMENT : ""
TB_HALL ||--o{ TB_HALL_ASSIGNMENT : ""
TB_HALL ||--o{ TB_TRENCH : ""
TB_HALL_ASSIGNMENT ||--o{ TB_LAYOUT : ""
TB_LAYOUT ||--o{ TB_BOOTH : ""
TB_BOOTH ||--o{ TB_DESIGN_PLAN : ""
TB_BOOTH ||--o{ TB_UTILITY_ORDER : ""
TB_UTILITY_ORDER ||--o{ TB_WIRING_PATH : ""
TB_BOOTH ||--o{ TB_RENDER_JOB : ""
TB_COMPANY ||--o{ TB_BOOTH : "배정"
TB_EVENT ||--o{ TB_EVENT_MEMBER : ""
```
**계약 정합 근거**(01_backend_contracts §8 매퍼 인수 목록):
- `BoothMapper` → `TB_BOOTH.geom`(ST_MakePolygon/ST_AsGeoJSON), 판매면적 `ST_Area(geom)`, 통로폭 `ST_Distance/ST_Buffer`, 비상구 `ST_Intersects(TB_HALL_FEATURE)`.
- `DesignMapper` → `TB_DESIGN_PLAN.spec`(jsonb), `findEventIdByBooth`(RBAC 역참조 = TB_BOOTH→TB_LAYOUT→TB_HALL_ASSIGNMENT→event_id).
- `WiringMapper` → `TB_TRENCH` KNN(`geom <-> :point`), `TB_WIRING_PATH.geom` 최단(ST_Length), `TB_TRENCH.assumed` 플래그.
- `RenderJobMapper` → `TB_RENDER_JOB` 내구 이력·쿼터 정본(`countSucceededByEvent`, Redis는 큐/실시간).
- `UserMapper` → `TB_USER`(§2-3) 인증행(해시 응답 제외)·`TB_EVENT_MEMBER` 역할.
### 2-2. v2.0 확장 물리 ERD (옥션·관람·CMS)
```mermaid
erDiagram
TB_AUCTION {
uuid auction_id PK
uuid event_id FK
varchar auction_type "REVERSE|RFQ|FIXED"
varchar category_code "공종 14분류"
varchar status "OPEN|BIDDING|AWARDED|CLOSED"
int round_no
timestamptz deadline_at
varchar award_criteria "LOWEST|COMPOSITE"
jsonb weight "가격/평판/납기 가중치"
jsonb attached_refs "Booth/Design/Utility/Render 참조 자료"
}
TB_QUOTATION {
uuid quotation_id PK
uuid auction_id FK
uuid company_id FK "등록업체 검증"
int version
varchar status "SUBMITTED|REVISED|AWARDED|REJECTED"
jsonb line_items "공종·자재·수량·단가·금액"
numeric subtotal
numeric vat
numeric total
date valid_until
varchar lead_time
varchar pdf_url
timestamptz submitted_at
}
TB_AWARD {
uuid award_id PK
uuid auction_id FK
uuid quotation_id FK "선정 견적서"
numeric composite_score
varchar reason
varchar contract_doc_url "M6/M9 연동"
timestamptz awarded_at
}
TB_VISITOR {
uuid visitor_id PK
varchar name_enc "PII·AES-GCM"
varchar email_enc "PII·AES-GCM"
varchar phone_enc "PII·AES-GCM"
varchar org_name "준식별"
varchar job_title
jsonb interests "관심 업종"
varchar visitor_type "VISITOR|BUYER"
timestamptz created_at
}
TB_REGISTRATION {
uuid registration_id PK
uuid event_id FK
uuid visitor_id FK
varchar reg_type
boolean consent_privacy "동의(필수)"
boolean consent_marketing "동의(선택·정보통신망법)"
timestamptz consent_at
timestamptz registered_at
}
TB_BADGE {
uuid badge_id PK
uuid registration_id FK
varchar qr_token "회전 토큰·비추측"
varchar badge_template_id "M17"
}
TB_CHECK_IN {
uuid checkin_id PK
uuid badge_id FK
timestamptz checked_at
varchar gate
}
TB_LEAD {
uuid lead_id PK
uuid event_id FK
uuid booth_id FK "참가업체 스코프"
uuid visitor_id FK
int interest_score
varchar memo_enc "PII·AES-GCM"
boolean consent_share "리드 공유 동의"
timestamptz captured_at
}
TB_CONTENT {
uuid content_id PK
uuid event_id FK "nullable"
varchar content_type
varchar locale "ko|en|zh|ja"
int version
varchar status "draft|review|published"
jsonb body
}
TB_AUCTION ||--o{ TB_QUOTATION : ""
TB_AUCTION ||--o| TB_AWARD : ""
TB_QUOTATION ||--o| TB_AWARD : "선정"
TB_VISITOR ||--o{ TB_REGISTRATION : ""
TB_REGISTRATION ||--o{ TB_BADGE : ""
TB_BADGE ||--o{ TB_CHECK_IN : ""
TB_VISITOR ||--o{ TB_LEAD : ""
```
**보조 테이블**(도메인 완결): `TB_SETTLEMENT`(정산·M9)·`TB_PAYMENT_SCHEDULE`(납부 스케줄 20/30/20/30 + 예치금)·`TB_DOCUMENT`(서류·마일스톤 D-150/30/25/7·M6)·`TB_MEETING`(비즈매칭·M11)·`TB_MICROSITE`(참가업체·M17)·`TB_MASTER_DATA`(마스터 버전·M18). 상세 컬럼은 해당 도메인 에이전트 확정 시 본 문서 갱신.
### 2-3. 공통·시스템관리 물리 모델 (WISE/UIWS 이식 — 정본 참조)
> **재설계 금지**: 아래는 `workspace/uiws` `TB_*` 정본을 **그대로 이식**(멱등 DDL·`sql.init mode=always`+continue-on-error). 킨텍스는 표준 준수만 하고 컬럼을 임의 변경하지 않는다. 상세 컬럼 정의는 UIWS 레퍼런스가 정본.
| 테이블 | 역할 | 킨텍스 접합 |
|---|---|---|
| `TB_USER` | 사용자·인증(BCrypt 해시·`otp_secret` AES) | 6역할 + 등록업체 계정 + 관람객 셀프서비스 |
| `TB_CODE_GRP` / `TB_CODE` | 공통코드 그룹/값 | §4-3 도메인 코드 적재 |
| `TB_MENU` | 메뉴 트리·권한 매핑 | 역할별 포털 IA(§2-1) |
| `TB_AUDIT_LOG` | 감사 로그 | 승인·**낙찰**·설계변경·룰셋개정·**리드 접근(PII)** 전수 |
| `TB_NOTIFICATION` | 통합 알림 | D-데이 리마인더·낙찰·결제 |
| worklog/schedule/message/notice/meeting/report 등 | 공통 업무 | §5B-2 접합점만 이식 |
- **인증 표준(§5B-3)**: JWT + TOTP(RFC6238, SHA1·30s·6자리·±1) 2차 인증 + 로그인 실패 잠금. `admin` 비번은 env `ADMIN_PASSWORD_ENC`(AES-256-GCM) + 별도 키파일 복호 → 기동 시 BCrypt 재시드. **하드코딩 시드 금지**.
- **행사 RBAC 이중 평가**: 전역 `USER_ROLE`(WISE) + 행사 스코프 `EVENT_ROLE`(TB_EVENT_MEMBER) 병행. 킨텍스 1차 권한 = `EVENT_ROLE`(COMMON_CODES §3).
---
## 3. 공간 데이터 모델 표준 (PostGIS)
> M2~M5·M13·M14·M16이 공유하는 **단일 공간 원천**. 물리 구현(ST_* 매퍼 XML)은 db-engineer, 좌표계·타입·인덱스·검증 계약은 본 절이 표준.
### 3-1. 좌표계 표준 — 홀 로컬 데카르트
| 항목 | 표준 | 근거 |
|---|---|---|
| **SRID** | **`0`(로컬 데카르트, 미터)** — 지리좌표(4326) 아님 | 부스/트렌치/배선은 홀 로컬 미터 좌표(계약 `polygon`=홀 로컬 미터, `[[0,0],[6,0]...]`) |
| 타입 | **`geometry`**(geography 아님) | 평면 미터 연산: `ST_Area`=㎡ 직접, `ST_Distance`=m 직접, `ST_Length`=m 직접 |
| 원점 | 홀별 원점(도면 좌하단) 기준, hall_id로 좌표계 분리 | 홀마다 독립 로컬 원점 |
| 단위 | 미터(m). 각도는 도(°) | 계약 `sizeM`·`heightM`·`lengthM` |
| 정밀도 | 좌표 소수 3자리(mm), 면적/길이 소수 2자리 | 시공 실무 정밀도 |
> **주의(교차 좌표계 금지)**: 홀 로컬 좌표는 홀 간 직접 공간연산 불가(각 홀 원점 상이). 홀 전경(S7)·부지 컨텍스트가 필요하면 별도 `venue` 좌표계 변환 테이블로 배치(Phase 2). Phase 1은 단일 홀 기준(홀7 권장, PLANNING §9).
### 3-2. 지오메트리 컬럼 표준
| 엔티티 | 컬럼 | PostGIS 타입 | 규칙 |
|---|---|---|---|
| **부스** `TB_BOOTH` | `geom` | `geometry(Polygon, 0)` | 닫힌 링(첫=끝 좌표), 단순(ST_IsSimple)·유효(ST_IsValid), CCW 권장 |
| **홀 외곽** `TB_HALL` | `footprint` | `geometry(Polygon, 0)` | 홀 경계 |
| **홀 시설** `TB_HALL_FEATURE` | `geom` | `geometry(Geometry, 0)` | 기둥(Point Ø2.5m 버퍼)·비상구(Point/LineString)·셔터·화장실 — `feature_type` 구분 |
| **트렌치** `TB_TRENCH` | `geom` | `geometry(Point, 0)` | 탭/액세스 포인트(KNN 대상). `run_geom geometry(LineString,0)` 옵션(트렌치 런) |
| **배선** `TB_WIRING_PATH` | `geom` | `geometry(LineString, 0)` | 트렌치→단말 경로. `kind`별 1행 |
### 3-3. 공간 연산 계약 (매퍼 XML 대상 — db-engineer 인수)
| 용도 | 연산 | 규정/계약 매핑 |
|---|---|---|
| 판매면적 | `ST_Area(geom)` (m²) | LayoutSummary `salesAreaM2`, BI ㎡당 수익 |
| 통로 폭 최소 | `ST_Distance` + `ST_Buffer`(부스 간극) | 규정 `AISLE_WIDTH_MIN`(≥3m·block) |
| 비상구 차단 | `ST_Intersects(booth, exit_access_zone)` count | 규정 `EXIT_ACCESS`(=0·block) |
| 최근접 트렌치 | KNN `geom <-> :point ORDER BY … LIMIT k` | `WiringMapper.findNearestTrenches` |
| 최단 배선 | 경로 LineString `ST_Length` (통로 횡단 최소 휴리스틱) | `WiringMapper.shortestPath`, `WiringResult.lengthM` |
| 부스 겹침 | `ST_Overlaps` / `ST_Intersects` 자기조인 | 배치 무결성(솔버 후검증) |
| 홀 이탈 | `ST_Contains(hall.footprint, booth.geom)` | 부스가 홀 경계 내 |
- **가정 트렌치(R4)**: 실측 미확보 홀은 공개 규격 기반 가정 그리드 → `TB_TRENCH.assumed=true`. `WiringResult.assumedTrench=true` → 프론트 "가정 트렌치 좌표(실측 대기)" 배지(계약 §5). CAD 트렌치 실측(`평면,트렌치.dwg`, floorplans README) 확보 시 홀 단위 교체·`assumed=false`.
- **좌표 검증 게이트**: 저장 전 `ST_IsValid`·닫힌 링·홀 내포 검증 실패 시 `VALIDATION`(400). 무효 지오메트리 저장 금지.
### 3-4. 공간 인덱스·성능 표준
- 전 `geom` 컬럼 **GiST 인덱스**(`USING gist(geom)`) 필수. 트렌치 KNN·통로 버퍼·비상구 교차의 실시간 응답 근거.
- 부스 수 홀당 200~600(PLANNING). 배치 검증은 홀 단위 배치(bounding box 선필터 후 정밀 연산).
- 대량 좌표는 서버 산출값 권위 — 프론트 좌표는 참고, 규정 판정은 PostGIS 산출값과 대조(compliance-v1 `AISLE_WIDTH_MIN.note`).
---
## 4. 데이터 표준 (명명·코드·마스터)
### 4-1. 명명 규칙 (Naming Convention)
| 대상 | 규칙 | 예 |
|---|---|---|
| 테이블 | `TB_` + `UPPER_SNAKE`(단수) — WISE 표준 계승 | `TB_BOOTH`, `TB_AUCTION` |
| 컬럼(물리) | `snake_case`, PostgreSQL 무인용 소문자(대소문자 혼용·인용식별자 금지) | `booth_id`, `floor_load_t_per_m2` |
| PK | `<엔티티>_id`, **UUID**(도메인) / WISE 이식 테이블은 정본 PK 유지 | `event_id`, `job_id` |
| FK | 참조 PK명 동일 | `TB_BOOTH.layout_id` |
| 지오메트리 | `geom`(주 지오메트리) / `<용도>_geom` | `geom`, `footprint`, `run_geom` |
| 암호화 PII | `<필드>_enc` 접미 | `email_enc`, `otp_secret`(WISE) |
| 코드 컬럼 | `<의미>_code` 또는 상태 `status` | `category_code`, `status` |
| 불리언 | `is_`/동사 또는 `<x>_yn`(WISE 공통은 `USE_YN`) | `premium`, `assumed`, `use_yn` |
| 시각 | `*_at`(`timestamptz`), 날짜 `*_date`(`date`) | `created_at`, `deadline_at`, `start_date` |
| 금액 | `numeric`, 원(KRW) 정수 스케일, 통화 `currency` 명시 | `total`, `vat` |
| BI 마트 | 팩트 `FACT_*`, 차원 `DIM_*`, 스냅샷 `KPI_SNAPSHOT` | `FACT_BOOKING`, `DIM_HALL` |
- **DTO(camelCase) ↔ 컬럼(snake_case) 매핑**: MyBatis `mapUnderscoreToCamelCase=true` 또는 명시 `resultMap`. 계약 DTO(`boothNo`↔`booth_no`, `floorLoadTPerM2`↔`floor_load_t_per_m2`)는 01_backend_contracts를 정본으로 매핑.
- **응답 제외 컬럼(불변, 계약 §0-3)**: `*_enc`·비번 해시·`otp_secret`·내부 IP/SSH·내부 식별자는 API 응답 완전 제외. 표시는 이름·역할·번호 등 비민감 필드만.
### 4-2. 데이터 타입 표준
| 논리형 | 물리형(PostgreSQL) | 비고 |
|---|---|---|
| 식별자 | `uuid`(도메인) | `gen_random_uuid()` |
| 반정형 스펙 | `jsonb` | DesignSpec·quote·line_items·merge_provenance — GIN 인덱스 선택 |
| 공간 | `geometry(<type>, 0)` | §3 |
| 상태·코드 | `varchar` + 공통코드 검증(앱 레벨) | ENUM 물리타입 지양(룰셋/코드 유연성) |
| 금액 | `numeric(15,2)` | |
| 시각 | `timestamptz`(UTC 저장, Asia/Seoul 표시) | |
### 4-3. 공통코드 체계 (WISE 정합)
> 정본 = [`docs/COMMON_CODES.md`](../COMMON_CODES.md)(단일 출처). 적재 `TB_CODE_GRP`/`TB_CODE`, 코드값=영문 상수·코드명=한글. **DA 검수 관점**: 코드 vs 마스터 경계 준수, "확인 필요" 코드값 임의 확정 금지.
- **코드 vs 마스터 경계(핵심 표준)**: 열거 가능 소수값=**공통코드**(BOOTH_TYPE·RENDER_STATUS·SHOT_PRESET 등), 다건·CRUD·버전 대상=**마스터/룰셋**(홀·요율·규정·등록업체) — 공통코드에 넣지 않는다(COMMON_CODES §1·§4 말미).
- **확정 코드**(계약/PLANNING 근거): `EVENT_ROLE`·`PORTAL_ROLE`·`BOOTH_TYPE`·`COMPLIANCE_SEVERITY`·`RENDER_STATUS`·`SHOT_PRESET`·`USE_YN`.
- **DA 확정 대기(확인 필요)**: `AUCTION_STATUS`·`QUOTATION_STATUS`(M15)·`ZONE_TYPE` 확장·상태 전이(`LAYOUT_STATUS`/`DESIGN_STATUS`/`UTILITY_ORDER_STATUS`의 submitted 이후)·`COMPLIANCE_GROUP` 전체 — 도메인 에이전트 확정 시 **COMMON_CODES + 본 ERD 컬럼 주석 동시 갱신**(DA 검수 항목).
- **신규 도메인 코드 제안**(DA): `CONTRACTOR_CATEGORY`(등록업체 14분류: 전시디자인설치·리깅·전기시설·카펫/파이텍스·급배수/Air·가스설비·철거·운수통관·가구비품·경비용역·광고싸인물·지게차·방염·구조해석), `UTILITY_KIND`(power·network·plumbing·air·gas), `AUCTION_TYPE`(REVERSE·RFQ·FIXED), `CONTENT_LOCALE`(ko·en·zh·ja) — 확정 시 COMMON_CODES §2에 승격.
### 4-4. 마스터데이터 관리 정책 (M18 백오피스)
| 마스터 | 저장 형태 | 버전 관리 | 권한 | 개정 절차 |
|---|---|---|---|---|
| **홀 마스터** | `TB_HALL`(+`TB_HALL_FEATURE`·`footprint`) | 스키마 컬럼 `revision`·이력 테이블 | ADMIN | CAD 실측 확보 시 교체(floorplans README 대조), 제3전시장(2028) H11~H18 확장 구조 |
| **요율 룰셋** | `rulesets/rates-v*.json`(파일) | 파일 버전(`rates-v1.0`) + `TB_MASTER_DATA` 메타 | ADMIN | 연 단위 개정 → 새 파일 교체, 산출물에 `rulesetVersion` 각인, 기존 견적 스냅샷 불변 |
| **유틸리티 요금** | rates-v*.json `utility` 절 | 상동 | ADMIN | 인터넷 150,000 vs KT 80,000 정합 확인 후 확정(R8) |
| **규정 룰셋** | `rulesets/compliance-v*.json` | 파일 버전(`compliance-v1.0`) | ADMIN | 규정 개정 시 교체, 리포트에 `rulesetVersion`+`disclaimer` 각인(면책·감사) |
| **등록업체 DB** | `TB_COMPANY`(739개·14분류) | 주기 수집 + `kintex_registered` 검증 플래그 | ADMIN | 웹 공개 데이터 수집→자체 DB화, 추후 공식 피드. **미등록=옥션 응찰/초대 차단 게이트**(불변) |
- **룰셋 스냅샷 원칙**: 견적(`TB_UTILITY_ORDER.quote`·`rateset_version`)·규정 리포트는 산출 시점 룰셋 버전을 **스냅샷 각인**. 이후 룰셋 개정이 과거 산출물을 변경하지 않는다(감사·재현성).
- **버전 관리 = 룰 엔진 결합**: 룰셋은 코드가 아닌 데이터 → M18 개정이 무중단 반영(PLANNING §8-1). 개정은 `TB_AUDIT_LOG` 전수 기록.
---
## 5. 데이터 품질·거버넌스
### 5-1. 개인정보(PII) 분류 체계
> 집중 영역 = 관람·참가(M10/M11). **주민등록번호 등 고유식별정보는 수집하지 않는다**(수집 최소화).
| 등급 | 분류 | 대상 컬럼(예) | 처리 |
|---|---|---|---|
| **P1 식별정보** | 직접 식별 | `TB_VISITOR.name_enc/email_enc/phone_enc`, `TB_LEAD.memo_enc` | **컬럼 AES-256-GCM 암호화** 저장, 응답 제외/마스킹, 접근 감사 |
| **P2 준식별** | 결합 식별 | `org_name`·`job_title`·`interests`·`visitor_type` | 접근 통제, BI는 집계/익명화만 반입 |
| **P3 인증비밀** | 크리덴셜 | `TB_USER` 비번 해시(BCrypt)·`otp_secret`(AES) | 절대 응답 금지, 로그 금지 |
| **P4 공개/비식별** | 비민감 | 부스명·업체명(표시용)·행사·집계 | 일반 처리 |
- **BoothDto 준거**: `assignedCompanyName`는 "표시용, 내부 식별자·민감정보 미포함"(BoothDto Javadoc) — P4. 부스 설계(TB_DESIGN_PLAN.spec)는 영업비밀(R10) → 행사 격리·접근 제한.
### 5-2. 암호화 정책
| 데이터 | 방식 | 근거 |
|---|---|---|
| PII 컬럼(P1) | **AES-256-GCM** 컬럼 암호화, 키는 서버 env/별도 키파일(코드·DB·커밋·로그 금지) | GUARDiA 보안 불변 `os_pw_enc` 패턴 |
| 비밀번호 | BCrypt(단방향) | WISE 표준 |
| OTP 시크릿 | AES-256-GCM | §5B-3 TOTP |
| 전송 | TLS(포털·API·워커 콜백) | NA(network.md) 정합 |
| 오브젝트 스토리지 | 접근 제어 URL(서명·만료), 도면/설계 행사 격리 | R10 |
### 5-3. 동의(Consent)·수집 최소화
- **동의 분리**: `TB_REGISTRATION.consent_privacy`(개인정보 수집·이용, **필수**) / `consent_marketing`(EDM 발송, **선택**, 정보통신망법) / `TB_LEAD.consent_share`(참가업체 리드 공유). 각 `consent_at` 시각 기록.
- **목적 구속**: 마케팅 미동의자는 M12 EDM 세그먼트 제외(발송 파이프라인 게이트). 리드 공유 미동의는 참가업체 반출 차단.
- **최소 수집**: 관람객 폼은 목적 필요 최소 필드. 셀프서비스 계정은 행사 데이터 쓰기 권한 없음(PLANNING §2).
### 5-4. 보존·파기 정책
| 데이터 | 보존 | 파기 |
|---|---|---|
| 관람객 등록·배지·체크인(PII) | 행사 종료 후 정책 기간(기본 1년, 재참가 분석 목적 별도 동의 시 연장) | 기간 경과 자동 익명화/삭제 |
| 리드(참가업체 반출본) | 참가업체 자산 — 반출 시점 이후 참가업체 책임, 플랫폼 원본은 위 관람객 정책 준수 | 상동 |
| 도면·설계·생성 이미지 | 행사 종료 후 보존(참가업체 자산, PLANNING §8) — 별도 정의 | 참가업체 요청 시 삭제 |
| 견적서 PDF·낙찰(M15) | 계약·감사 목적 장기 보존 | 법정 보존기간 준수 |
| 감사로그 | 장기 보존(불변·append-only) | 미파기 |
| BI 마트·KpiSnapshot | 집계(비식별) — 장기 보존 | — |
### 5-5. 감사(Audit)·데이터 계보(Lineage)
- **감사 대상(전수, `TB_AUDIT_LOG`)**: 승인·**낙찰(M15 Award)**·설계 변경·**룰셋/마스터 개정**·**리드/PII 접근**·권한 변경·로그인/OTP. append-only, 행위자·시각·전후값·행사 스코프 기록(COMMON_CODES §2-1 audit 확장).
- **데이터 계보(원천→마트)**:
```
[운영 원천] [BI 데이터마트 M16]
TB_HALL_ASSIGNMENT / 행사일정 ──▶ FACT_BOOKING (가동률·RevPAD·㎡당수익)
TB_SETTLEMENT (M9) ──▶ FACT_SETTLEMENT (매출구성·P&L)
TB_UTILITY_ORDER (M4) ──▶ FACT_UTILITY (유틸 매출)
TB_AUCTION/QUOTATION/AWARD ──▶ FACT_AUCTION (옥션 수수료)
TB_REGISTRATION/CHECK_IN (M10) ──▶ FACT_VISITOR (관람·리텐션) ※PII 비반입, 집계만
TB_HALL/PostGIS ST_Area ──▶ DIM_HALL (면적 정규화)
─(배치/야간 적재)─▶ KPI_SNAPSHOT (경영진 KPI)
```
- **PII 격리(계보 규칙)**: BI 마트는 P1/P2 원본을 반입하지 않는다 — 관람객은 **집계·코호트·익명 키**만 반입(FACT_VISITOR는 방문 카운트·세그먼트 차원, 개인 식별자 없음). M16 리텐션/LTV는 참가사(Company) 단위이며 개인 관람객이 아님.
- **데이터 품질 규칙(DQ)**: 참조무결성(FK), 지오메트리 유효성(§3-3 게이트), 룰셋 버전 각인 누락 0, 금액 통화 명시, 상태 코드 공통코드 준수. 마트 적재 시 원천-집계 정합 체크(§6-4).
---
## 6. BI 데이터마트 (M16) — 스타 스키마
> 대상: **kintex-bi-dev**. PLANNING §5A M16-1 운영사(킨텍스) 관점 7지표 정합. 관점 격리 = ① 참가업체 ROI(자기 부스) / ② 운영사 수익성(전 행사) 별도 대시보드·권한(PLANNING §440). 적재 = 배치/야간 `KPI_SNAPSHOT` 또는 읽기 전용 복제(운영 부하 회피, §8-1).
### 6-1. 스타 스키마 ERD
```mermaid
erDiagram
DIM_DATE {
int date_key PK "YYYYMMDD"
date full_date
int year
int quarter
int month
boolean is_peak "성수기 3-5·9-11"
boolean is_offpeak "비수기 1·2·7·12"
}
DIM_HALL {
varchar hall_key PK "H1..H10/반홀"
varchar hall_name
numeric area_m2 "㎡ 정규화 기준"
varchar center "1전시장|2전시장"
numeric floor_load
varchar floor_finish
}
DIM_EVENT {
uuid event_key PK
varchar event_name
varchar event_type
date start_date
date end_date
int duration_days
}
DIM_EXHIBITOR {
uuid exhibitor_key PK "=company_id"
varchar company_name
varchar category
varchar region
int first_participation_year "코호트"
}
FACT_BOOKING {
uuid booking_id PK
int date_key FK
varchar hall_key FK
uuid event_key FK
numeric occupied_area_m2
numeric available_area_m2
int occupied_days
int available_days
numeric rental_revenue
numeric season_coeff "성수기/비수기/1전시장 계수"
}
FACT_SETTLEMENT {
uuid settlement_id PK
int date_key FK
uuid event_key FK
varchar revenue_segment "rental|utility|auction_fee|lobby|outdoor|parking"
numeric revenue
numeric direct_cost "운영·에너지·인력"
numeric contribution_margin
}
FACT_UTILITY {
uuid util_fact_id PK
int date_key FK
uuid event_key FK
uuid exhibitor_key FK
varchar utility_kind "power|network|plumbing|air"
numeric amount
}
FACT_AUCTION {
uuid auction_fact_id PK
int date_key FK
uuid event_key FK
varchar category_code
numeric awarded_amount
numeric platform_fee
int bid_count
}
FACT_VISITOR {
uuid visitor_fact_id PK
int date_key FK
uuid event_key FK
varchar visitor_segment "visitor|buyer (익명 세그먼트)"
int registered_count
int checkin_count
int lead_count "PII 없음·집계만"
}
KPI_SNAPSHOT {
uuid snapshot_id PK
int date_key FK
varchar scope "venue|center|hall|event"
varchar scope_key
varchar kpi_code "OCC|REVPAD|MARGIN|RETENTION|LTV|YIELD"
numeric kpi_value
numeric target_value
timestamptz built_at
}
DIM_DATE ||--o{ FACT_BOOKING : ""
DIM_HALL ||--o{ FACT_BOOKING : ""
DIM_EVENT ||--o{ FACT_BOOKING : ""
DIM_DATE ||--o{ FACT_SETTLEMENT : ""
DIM_EVENT ||--o{ FACT_SETTLEMENT : ""
DIM_DATE ||--o{ FACT_UTILITY : ""
DIM_EXHIBITOR ||--o{ FACT_UTILITY : ""
DIM_DATE ||--o{ FACT_AUCTION : ""
DIM_DATE ||--o{ FACT_VISITOR : ""
DIM_EVENT ||--o{ FACT_VISITOR : ""
DIM_DATE ||--o{ KPI_SNAPSHOT : ""
```
### 6-2. 팩트 그레인(Grain) 정의
| 팩트 | 그레인(1행 = ) | 가법성 |
|---|---|---|
| `FACT_BOOKING` | 행사×홀(반홀)×기간 배정 1건 | 면적·일수·매출 가법, 계수 비가법 |
| `FACT_SETTLEMENT` | 행사×매출세그먼트×정산일 | 매출·원가·공헌이익 가법 |
| `FACT_UTILITY` | 행사×참가사×유틸종류 신청 1건 | 금액 가법 |
| `FACT_AUCTION` | 옥션(낙찰) 1건 | 낙찰액·수수료 가법, bid_count 준가법 |
| `FACT_VISITOR` | 행사×관람일×세그먼트 집계 | 카운트 가법(**개인 식별자 없음**) |
### 6-3. M16-1 지표 → 마트 매핑
| # | 운영사 지표 | 산식 | 소스 팩트/차원 |
|---|---|---|---|
| ① | 홀·기간별 가동률 | Σ occupied_area×days / Σ available_area×days ×100 | FACT_BOOKING × DIM_HALL × DIM_DATE |
| ② | 매출 구성(mix) | revenue by segment | FACT_SETTLEMENT/FACT_UTILITY/FACT_AUCTION |
| ③ | 행사별 P&L·마진 | Σ revenue − Σ direct_cost = 공헌이익, 마진율 | FACT_SETTLEMENT × DIM_EVENT |
| ④ | 전시장별 ROI·RevPAD·㎡당 수익 | revenue / area_m2 (㎡ 정규화) | FACT_BOOKING × DIM_HALL(area_m2) |
| ⑤ | 참가사 리텐션·LTV | 코호트 재참가율, LTV=Σ(임대+유틸+옥션)/재참가주기 | DIM_EXHIBITOR(first_year) × FACT_* 다년 |
| ⑥ | 수요예측·수율/가격 | 성수기 계수·홀별 수요, 요율 시뮬레이션 | FACT_BOOKING 이력 × rates 룰셋 |
| ⑦ | 경영진 KPI 대시보드 | ①~⑥ 요약 + 목표 대비(점유 60~75%) | KPI_SNAPSHOT |
### 6-4. 적재·품질 표준
- **적재 방식**: 야간 배치 ETL(운영→`mart` 스키마) 또는 읽기 전용 복제(운영 부하 회피). `KPI_SNAPSHOT`은 스냅샷 시점(`built_at`) 각인 → 시계열 추이·재현성.
- **㎡ 정규화 권위**: DIM_HALL.area_m2는 **PostGIS `ST_Area` 산출값 또는 홀 마스터 확정값** 단일 출처(대형홀 vs 소형홀 생산성 비교 정합, ④ RevPAD 근거).
- **정합 체크(DQ)**: 마트 매출 합 = 운영 정산 합(허용오차 0), 가동률 분모(가용 홀·일수) = 행사일정×홀 마스터, 관점 격리(참가사 대시보드는 exhibitor_key 필터 강제).
- **PII 비반입(불변)**: FACT_VISITOR는 카운트/세그먼트만 — TB_VISITOR P1/P2 컬럼 마트 유입 금지(§5-5 계보 규칙).
- **한계 각인**: LTV·리텐션 다년 데이터 필요(초기 단년 근사), 수율 최적가=시뮬레이션 참고치(최종 요율은 킨텍스 경영 결정, R8) — 대시보드 고지.
---
## 7. DA 검수 체크리스트 (Phase A 게이트)
> 본 문서를 기준으로 db-engineer 물리 구현·타 트랙 산출물을 검수하는 항목(A-6 reviewer 정합 입력).
| # | 검수 항목 | 기준 |
|---|---|---|
| 1 | 명명 규칙 준수 | `TB_`·snake_case·`_enc`·`geom`·`FACT_/DIM_` (§4-1) |
| 2 | 공간 좌표계 | SRID 0·geometry·GiST 인덱스·`ST_IsValid` 게이트 (§3) |
| 3 | 공통코드 경계 | 코드 vs 마스터 분리, "확인 필요" 임의확정 금지 (§4-3) |
| 4 | 룰셋 스냅샷 | 견적·리포트에 `rulesetVersion` 각인, 과거본 불변 (§4-4) |
| 5 | PII 암호화·응답제외 | P1 `_enc` AES-GCM, 민감컬럼 API 완전 제외 (§5-1/5-2, 계약 §0-3) |
| 6 | 동의 게이트 | marketing 미동의 EDM 제외, share 미동의 반출 차단 (§5-3) |
| 7 | 감사 전수 | 낙찰·룰셋개정·리드접근·권한변경 기록 (§5-5) |
| 8 | BI PII 비반입 | 마트에 개인식별자 유입 0, 관점 격리 (§6-4) |
| 9 | 계약 정합 | §8 매퍼 인수 테이블/컬럼 = 본 ERD (§2-1) |
---
## 8. 미결·후속 (확정 대기)
| 항목 | 상태 | 담당 |
|---|---|---|
| M15 옥션 상태 코드(`AUCTION_STATUS`·`QUOTATION_STATUS`) 확정 | 확인 필요 | bidding-dev + DA |
| 상태 전이(layout/design/utility submitted 이후) | 확인 필요 | M6 승인 워크플로 + DA |
| `TB_SETTLEMENT`·`TB_MEETING`·`TB_MICROSITE` 상세 컬럼 | 골격만 | 도메인 에이전트 + DA |
| CAD 트렌치 실측 → `TB_TRENCH.assumed=false` 교체 | 미확보(R4) | 킨텍스 협의 |
| 홀 간 venue 좌표계 변환(S7·부지) | Phase 2 | DA + M2 |
| 제3전시장(2028) H11~H18 홀 마스터 확장 | 구조 대비 | DA |
| 인터넷 요금 정합(150,000 vs 80,000) | 확인 필요(R8) | 킨텍스 + M18 |
---
## 10. FK 최소화·공통코드 관리 표준 (소유자 지시 2026-07-12)
> 소유자 원칙: **"FK는 최소화, 공통코드로 관리"**. 본 절은 §4·§5-5(DQ) 위에 **참조무결성·범주값 관리 방식의 단일 정책**을 확정한다. 이미 적용된 마이그레이션(V1~V43)은 **불변** — 본 절은 표준·감사·백로그이며 파괴적 재작성을 지시하지 않는다. 구현(신규 멱등 마이그레이션)은 kintex-db-engineer.
### 10-1. 물리 FK 제약 최소화 정책
- **기본값 = 물리 FK 미설정**: 신규 테넌트/도메인 테이블은 DB `FOREIGN KEY`/`REFERENCES`를 **두지 않는다**. 참조무결성은 **애플리케이션 레이어(서비스·매퍼 검증) + 명명 규약(`*_id` 소프트 참조)**로 보장(§4-1 FK 명명 유지, 물리 제약만 생략).
- **근거(4)**: ① **멀티테넌트 복합키 마찰** — 테넌트 루트(`event`·`hall`·`app_user`)는 `PRIMARY KEY (tenant_id, id)`로 전환됨(V31). 단일 `id` 참조 FK는 `UNIQUE(id)` 보조제약을 강제하고, V31이 실제로 **전 자식 FK를 드롭→복합PK 전환→UNIQUE(id)로 재생성**하는 동적 스윕을 수행해야 했다(마찰 실증). ② **MyBatis** — 조인·삭제 순서를 앱이 제어. ③ **마이그레이션·시드 순서 자유** — 멱등 `ON CONFLICT` 시드가 부모 선삽입에 묶이지 않음. ④ **성능·재배치** — 부스 replaceBooths·부스 교체 시 자식 재지정이 잦음(V3 utility_order·render_job는 이미 소프트 참조 채택 — 정본 사례).
- **예외 화이트리스트(FK 유지 허용)**: 아래 **강한 무결성이 필수이고 테넌트 복합키가 아닌 전역 시스템/RBAC 구성**만 물리 FK를 허용한다. 그 외 신규 FK 신설 **금지**.
| # | 자식 → 부모 | 마이그레이션 | 유지 사유 |
|---|---|---|---|
| W1 | `common_code.grp_code` → `common_code_group` | V7 | 코드값 고아 방지(공통코드 정합의 근간)·전역·정적 |
| W2 | `sys_menu.parent_id` → `sys_menu`(self) | V7 | 메뉴 트리 순환/고아 방지·전역 |
| W3 | `sys_role_permission`(role_code→`sys_role`, perm_code→`sys_permission`) | V7 | RBAC 권한 매핑 무결성(보안 임계)·전역 |
| W4 | `sys_role_menu`(role_code→`sys_role`, menu_id→`sys_menu`) | V37 | RBAC 메뉴 매핑 무결성·전역 |
### 10-2. 공통코드로 범주값 관리 정책
- **범주형 컬럼 = 공통코드**: 상태·유형·카테고리·모드·구분·심각도 등 **열거 가능 소수값**은 자유문자열/DB enum/전용 참조테이블이 아닌 **공통코드(`common_code_group`/`common_code`)로 관리**. 컬럼엔 코드값(영문 상수)만 저장, 표시명은 조인/캐시(§4-3, COMMON_CODES 정본). DB `ENUM` 물리타입은 지양(§4-2 — 룰셋/코드 유연성).
- **정본 화면 = W12 공통코드 관리**(CommonCodeAdminPage): 그룹/상세 CRUD의 단일 관리 지점. 신규 범주 컬럼 도입 시 **먼저 공통코드 그룹을 정의**하고 컬럼 주석에 `-- 공통코드(GRP)` 표기(V37 `partner_type` 사례).
- **코드 vs 마스터 경계(불변, §4-3)**: 다건·CRUD·버전 대상(홀·요율·규정 룰셋·등록업체)은 공통코드가 아니라 마스터/룰셋. 범주 컬럼만 공통코드로.
### 10-3. 테넌트 표준 정합
- 공통코드도 **테넌트 스코프 원칙 준수**([[tenant-id-pk-standard]]). 현행 `common_code_group`/`common_code`는 전역(테넌트 미부여) 이식본 — 킨텍스 단일 테넌트 운영 중엔 전역 공유가 유효하나, 멀티테넌트 확장 시 **테넌트별 코드 오버라이드**가 필요하면 `(tenant_id, grp_code, code)` 확장을 백로그로 둔다(§10-7 B4, 지금은 순증 시드만).
- 소프트 참조 인덱스는 `(tenant_id, *_id)` 복합 선두로 생성(§10-4).
### 10-4. 소프트 참조 무결성 보완책 (명문화)
물리 FK를 생략하는 대신 아래를 강제한다:
1. **앱 레이어 검증**: 부모 존재 확인은 서비스/매퍼에서 수행(삽입 전 조회 또는 조인 검증). 낙찰·정산 등 임계 트랜잭션은 명시적 존재검증 필수.
2. **삭제 시 고아 방지 규약**: 부모 삭제는 서비스가 자식 선삭제/무효화(soft-delete `use_yn='N'` 우선). 물리 CASCADE에 의존하지 않는다.
3. **논리참조 인덱스**: 조회·조인·고아 스캔 가속을 위해 소프트 FK 컬럼에 `(tenant_id, <ref>_id)` 인덱스(§10-7 B2).
4. **고아 검증 쿼리(DQ)**: 야간/배포 후 `LEFT JOIN ... WHERE parent.id IS NULL` 고아 스캔을 운영 점검 쿼리로 상비(마트 적재 전 DQ 게이트, §6-4). §5-5 DQ의 "참조무결성(FK)"은 **소프트 참조 무결성(앱+검증쿼리)**으로 해석 갱신.
---
## 11. 뷰·구체화뷰·함수 사용 지침 (소유자 지시 2026-07-12)
> 파생·집계·재사용 계산은 **결정론적 SQL 객체**로 캡슐화해 상태 백필·중복 로직·토큰 낭비를 줄인다. **실사용 근거 없는 선제 생성 금지**(남용 방지).
### 11-1. VIEW (`v_*`) — 실시간 파생·경량 조인·상태 산출
- 용도: 저장 없이 **결정론적 파생**(생명주기 상태·경량 조인·표시용 코드명 조인). 상태/구분 컬럼 백필 대신 **뷰 산출 권장**.
- 정본 사례(V43): `v_event_calendar`(날짜로 `lifecycle` UPCOMING/ONGOING/ENDED 산출 — 별도 상태 컬럼 불필요), `v_event_monthly_summary`(월별 건수 집계). 이 패턴을 신규 파생에 재사용.
- 규약: `CREATE OR REPLACE VIEW`, `tenant_id` 컬럼 노출·필터 유지, 하부 테이블 인덱스에 의존(뷰 자체 인덱스 불가), 민감 컬럼(§5-1 P1/P3) 미노출·마스킹만.
### 11-2. MATERIALIZED VIEW (`mv_*`) — 무겁고 자주 조회·실시간성 낮은 집계
- 용도: **BI 대시보드 KPI·홀 가동률·리드/ROI·월/연 통계** 등 비용 큰 집계로 실시간성이 덜 중요한 것(§6 마트 KPI_SNAPSHOT과 정합 — mview는 경량 대체/보조).
- **새로고침 전략 명시 필수**: 주기(야간 배치)·`REFRESH MATERIALIZED VIEW CONCURRENTLY`(무중단·유니크 인덱스 전제)·mview 자체 인덱스(`tenant_id` + 조회 키) 생성.
- 남용 판단 기준:
| 상황 | 선택 |
|---|---|
| 실시간성 필수·경량 | VIEW |
| 실시간성 낮음·집계 무거움·반복 조회 | MATERIALIZED VIEW |
| 경영 KPI 시계열·스냅샷 재현성 | KPI_SNAPSHOT 테이블(§6) |
| 1회성·희소 조회 | 뷰/mview 생성 안 함(온디맨드 쿼리) |
### 11-3. FUNCTION (`fn_*`) — 재사용 계산 로직 캡슐화
- 용도: 여러 쿼리·화면 공유 계산(기간→분기 산출, 요율 계산 보조, 거리/트래블타임 보조). **부수효과 없는 순수/`IMMUTABLE`·`STABLE` 우선**, PL/pgSQL은 꼭 필요할 때만(SQL 함수 우선).
- 규약: `CREATE OR REPLACE FUNCTION fn_*`, `tenant_id` 파라미터화, 룰셋 의존 계산(요율)은 스냅샷 버전 인자(§4-4)로 재현성 보장.
### 11-4. STORED PROCEDURE (`sp_*`) — 집합연산·다단계 트랜잭션
- 용도: **대량 집합 처리·다단계 트랜잭션·정기 롤업**은 앱 루프(행 단위 왕복) 대신 **DB 프로시저(PL/pgSQL) 세트기반 처리**. 예: 월마감 집계, `REFRESH MATERIALIZED VIEW`, 대량 상태전이, 정산 롤업.
- **경계(남용 금지)**: **비즈니스 로직 대부분은 앱(Service) 유지**. DB 프로시저는 **성능이 결정적일 때만**(대량·세트기반이 앱 루프 대비 확연히 유리). 검증·권한·감사·룰셋 판정 등 도메인 규칙을 프로시저로 이관하지 않는다.
- 순수/부수효과 구분: 반환값만 있는 재사용 계산 = `fn_*`(`IMMUTABLE`/`STABLE`), **부수효과(쓰기·다단계 커밋) 있는 것만 `PROCEDURE sp_*`**(`CALL`). 명명 `fn_*`/`sp_*`, 멱등 `CREATE OR REPLACE`, `tenant_id` 파라미터·스코프 준수.
### 11-5. 공통 규약
- 명명 `v_*`·`mv_*`·`fn_*`·`sp_*`. 마이그레이션 멱등(`CREATE OR REPLACE` / mview는 `IF NOT EXISTS` 가드). 테넌트 스코프 유지. 실사용 근거(화면/API/AI 답변) 있는 것만 생성.
---
## 13. 자동화 배치 카탈로그 (대상·주기·멱등 — 데이터 표준 관점)
> **무엇을 배치로 돌릴지**(대상·주기·멱등·잠금)만 데이터 표준에서 정의한다. **실행 프레임워크**(Spring `@Scheduled`/Quartz/cron·분산락)는 아키텍처(A-1 app.md/A-3 tech.md, kintex-sa/ta) 표준 영역 — 본 카탈로그를 그쪽으로 링크. 구현 인계: **스케줄러=backend-dev, 프로시저/mview=db-engineer**.
| # | 배치 작업 | 데이터 대상 | 주기(권고) | 멱등성 | 재시도·잠금 요건 |
|---|---|---|---|---|---|
| J1 | **mview 새로고침** | `mv_hall_occupancy`·`mv_lead_roi_summary`·KPI 집계(§6) | 야간 1회(+수요 트리거) | `REFRESH ... CONCURRENTLY` 자연 멱등 | 단일 실행락(중복 REFRESH 방지)·실패 시 다음 주기 |
| J2 | **KPI 스냅샷 적재** | `KPI_SNAPSHOT`(§6-4, `built_at` 각인) | 야간 배치 | 스냅샷 키(date_key,scope) UPSERT | 원천-집계 정합 DQ 통과 후 커밋 |
| J3 | **마감임박 알림·해야할일 자동생성** | D-데이(문서/마일스톤 D-150/30/25/7)·옥션 deadline·납부 스케줄 | 일 1회(+정시) | 발송/생성 대상 dedup 키(대상+일자) | 이미 발송분 스킵(중복 통지 금지)·실패 재큐 |
| J4 | **EDM/옥션 통지 발송** | 캠페인·옥션 통지(SMTP, [[smtp-email-approval]]) | 예약시각·이벤트 트리거 | mail_log 상태(sent/skipped)로 재발송 차단 | 마케팅 미동의 세그먼트 제외 게이트(§5-3)·발송락 |
| J5 | **세션/토큰·만료 데이터 정리** | 만료 비번재설정 토큰·잠금 해제·로그인이력 보존기간 | 시간별/일별 | 조건부 삭제(자연 멱등) | — |
| J6 | **소프트 참조 고아 검출(DQ)** | §10-4 논리참조 무결성(event/hall/company 참조 고아) | 야간(마트 적재 전) | 읽기 전용 스캔 | 고아 발견 시 리포트·차단(마트 적재 게이트) |
| J7 | **PII 보존·파기** | 관람객 등록·배지·체크인(행사종료+1년, §5-4) | 일 1회 | 기간 경과분 익명화/삭제(재실행 안전) | 동의 연장분 제외·감사로그 기록 |
| J8 | **행사 crawl 갱신** | 외부 행사정보(kintex-crawler 트랙) | 정기(일/주) | 소스키 UPSERT | 소스 실패 격리·부분성공 허용 |
| J9 | **정산 롤업** | `sp_settlement_rollup`(정산→FACT_SETTLEMENT) | 마감 주기 | 재실행 시 기간 재계산(UPSERT) | 정산 확정 상태만 대상·실행락 |
- **공통 요건**: 모든 배치는 ① **멱등**(재실행 안전 — UPSERT/조건부/dedup), ② **중복실행 방지 잠금**(분산락 — 실행수단은 아키텍처), ③ **실패 격리·재시도**(부분성공 허용·다음 주기 복구), ④ **감사**(J4·J7 등 통지·파기는 `audit_log` 기록), ⑤ **테넌트 스코프**(배치도 tenant 루프/필터).
- 세트기반 롤업(J2·J9)·대량 상태전이는 §11-4 `sp_*` 프로시저 후보. 알림/발송(J3·J4)의 **판정·세그먼트 규칙은 앱(Service)** — 프로시저는 대량 적재만.
---
## 12. 감사표 + kintex-db-engineer 인계 백로그
> 대조 대상: `src/backend/src/main/resources/db/migration/` V1~V43 전수. **파괴적 재작성 금지** — FK 드롭은 권고(별도 승인 후), 즉시 실행 백로그 = 공통코드 시드·논리참조 인덱스·뷰(순증 멱등). 신규 마이그레이션 번호는 **V43 이후 여유 번호(V44~) 권고**(진행 중 V43·신규분과 충돌 회피 — 실제 번호는 db-engineer가 병합 시점 최댓값+1로 확정).
### 12-1. 감사표 A — 현행 물리 FK 목록 (유지/제거 권고)
현행 물리 FK 약 40건. **유지=화이트리스트 4그룹(§10-1)**, 그 외는 소프트 참조 **제거 권고**(우선순위 P1: 테넌트 루트 참조 / P3: 아그리게잇 내부 — 무해·비복제).
| 분류 | 자식 → 부모(FK) | 마이그레이션 | 판정 |
|---|---|---|---|
| **유지(W1~W4)** | common_code.grp_code→common_code_group; sys_menu.parent_id(self); sys_role_permission(role/perm); sys_role_menu(role/menu) | V7·V37 | **유지** |
| **P1 제거권고** | hall_assignment.event_id→event, hall_id→hall; event_member.event_id→event, user_id→app_user, company_id→company | V2 | 소프트 참조(테넌트 루트·V31 마찰) |
| **P1 제거권고** | trench.hall_id→hall; hall_exit.hall_id→hall; layout.event_id→event, hall_id→hall; utility_order.event_id→event | V3 | 소프트 참조(hall/event 루트) |
| **P1 제거권고** | doc/milestone 3× event_id→event | V14 | 소프트 참조 |
| **P1 제거권고** | dock_reservation.event_id→event, hall_id→hall, dock_id→dock; booth_sale.event_id→event, hall_id→hall | V15·V27 | 소프트 참조 |
| **P1 제거권고** | auction.event_id→event; auction_invite.company_id→company; bid.company_id→company; company_reputation.company_id→company | V16 | 소프트 참조(company/event 루트) |
| **P1 제거권고** | visitor_registration.event_id→event; lead.event_id→event; campaign 3× event_id→event; sponsorship.package_id; settlement.event_id→event; logistics 3× event_id→event | V17·V18·V24·V33 | 소프트 참조 |
| **P3 잔류허용(무해·비복제)** | booth.layout_id→layout; design_plan.booth_id→booth; auction_invite/bid/award.auction_id→auction, award.bid_id→bid; content_version.content_id→cms_content; payment_schedule/refund/tax.invoice_id→invoice; approval_line/history.approval_id→approval; message_recipient/opinion_reply/meeting_attendee | V3·V8·V16·V19·V24·V29·V34 | 아그리게잇 내부 CASCADE — 유지해도 무해, **신규 테이블엔 미복제**(소프트 우선) |
> **주의**: P1 제거는 **자동 실행 대상 아님** — 기존 FK 드롭은 테넌트 복합키 정합·데이터 검증 후 **소유자 승인 별도 DROP 마이그레이션**으로만. 표준의 실질 효력은 **신규 테이블에 FK 미신설 + P1 패턴 미복제**에 있다.
### 12-2. 감사표 B — 범주형 컬럼 → 공통코드 그룹 매핑 (전환 후보)
자유문자열/주석 열거 범주 컬럼 ≈ **34개**. 기존 시드 그룹(V7·V37)과 정합, 신규 그룹(★)은 V44 순증 시드 대상. 코드값=현행 저장값 유지(스키마 불변).
| 그룹코드 | 컬럼(테이블.컬럼) | 마이그 | 코드값(현행) | 상태 |
|---|---|---|---|---|
| `USER_STATUS`★ | app_user.status | V2 | ACTIVE·(LOCKED·INACTIVE) | 신규 |
| `CONTRACTOR_CATEGORY`★ | company.category, auction.category | V2·V16 | 14분류(전시디자인설치·리깅·전기시설·카펫/파이텍스·급배수Air·가스·철거·운수통관·가구비품·경비·광고싸인·지게차·방염·구조해석) | 신규(COMMON_CODES §2 승격) |
| `HALL_FLOOR_TYPE`★ | hall.floor_type | V2 | concrete_polished·carpet·outdoor | 신규 |
| `MASTER_DATA_CATEGORY`★ | master_data.category | V2 | RATE·UTILITY_FEE·COMPLIANCE | 신규 |
| `EVENT_STATUS`★ | event.status | V2 | active·cancelled·(closed) | 신규 |
| `EVENT_CATEGORY`★ | event.category | V23 | (행사 분류 — 값 확인 필요) | 신규 |
| `LAYOUT_STATUS` | layout.status | V3 | draft·submitted·approved·rejected | COMMON_CODES 등재(시드화 필요) |
| `BOOTH_TYPE` | booth.booth_type | V3 | assembled·independent·corner·island | 등재(corner·island 추가) |
| `DESIGN_STATUS` | design_plan.status | V3 | draft·submitted·approved·rejected | 등재(시드화) |
| `UTILITY_ORDER_STATUS` | utility_order.status | V3 | draft·submitted·relayed | 등재(시드화) |
| `RENDER_STATUS` | render_job.status | V3 | QUEUED·RUNNING·DONE·FAILED | 등재(시드화) |
| `SHOT_PRESET` | render_job.shot_preset | V3 | S1~S7 | 등재(시드화) |
| `MILESTONE_TYPE`★ | milestone.milestone_type | V14 | assignment·pre_review·utility·documents·opening | 신규 |
| `DOC_TYPE`★ | document.doc_type | V14 | operation_plan·booth_layout·disaster_plan… | 신규 |
| `APPROVAL_STATUS`★ | document.status, approval.status | V14·V29 | pending·draft·submitted·approved·rejected / DRAFT… | 신규 |
| `DOCK_RESV_STATUS`★ | dock_reservation.status | V15 | (예약 상태) | 신규 |
| `AUCTION_TYPE` | auction.auction_type | V16 | reverse·rfq | 등재(COMMON_CODES §2, 소문자 정합) |
| `AWARD_CRITERIA`★ | auction.award_criteria | V16 | lowest·comprehensive | 신규 |
| `QUOTATION_STATUS` | bid.status | V16 | submitted·revised·awarded·rejected | 등재(확인 필요 → 확정) |
| `VISITOR_TYPE` | visitor_registration.visitor_type | V17 | visitor·buyer·vip | 등재(vip 추가) |
| `CHECKIN_STATE`★ | visitor_registration.checkin_state | V17 | done·waiting·cancelled | 신규 |
| `CAMPAIGN_STATUS`★ | campaign.status | V18 | draft·scheduled·sending·done | 신규 |
| `SPONSOR_CONTRACT_STATUS`★ | sponsorship.contract_status | V18 | signed·pending | 신규 |
| `CONTENT_TYPE`★ | cms_content.content_type | V19 | PAGE·POST·NOTICE·BLOCK | 신규 |
| `CONTENT_STATUS`★ | cms_content.status | V19 | draft·review·approved·published | 신규 |
| `TRANS_STATUS`★ | content_i18n.trans_status | V19 | none·ai·reviewed | 신규 |
| `INQUIRY_TYPE`★ | public inquiry.inquiry_type | V20 | shell·raw·premium·general | 신규 |
| `INQUIRY_STATUS`★ | public inquiry.status | V20 | received·in_review·closed | 신규 |
| `HALL_ASSIGN_STATUS`★ | hall_assignment.status | V25 | assigned·… | 신규 |
| `TENANT_STATUS`★ | tenant.status | V26 | active·onboarding·suspended | 신규 |
| `BOOTH_SALE_STATUS`★ | booth_sale.status | V27 | available·held·sold·blocked | 신규 |
| `INVOICE_CATEGORY`★ | invoice.category | V28 | rental·utility·auction_fee… | 신규 |
| `SETTLEMENT_STATUS`★ | settlement.status | V24 | pending·invoiced·paid·overdue | 신규 |
| `PAYMENT_METHOD`★ | payment_schedule.method | V24 | manual·transfer·card | 신규 |
| `APPROVAL_LINE_STATUS`★ | approval_line.line_status | V29 | WAIT·approved·rejected | 신규 |
| `EQUIP_CATEGORY`★·`RENTAL_STATUS`★·`RENTAL_ITEM_CATEGORY`★·`ORDER_STATUS`★·`FREIGHT_STATUS`★ | V33 logistics 5종 | V33 | forklift…/requested…/furniture…/ordered…/registered… | 신규 |
| `REFUND_STATUS`★·`TAX_INVOICE_STATUS`★ | refund.status·tax_invoice.status | V34 | recorded·settled / issued·void | 신규 |
| `WEBHOOK_EVENT_TYPE`★·`WEBHOOK_STATUS`★ | webhook 등 | V35 | lead.hot…/disabled·queued·sent·failed | 신규 |
| `MAIL_CATEGORY`★·`MAIL_STATUS`★ | mail_log.category·status | V36 | AUCTION_OPEN·EDM·PASSWORD_RESET / sent·failed·skipped | 신규 |
| `VISITOR_GUIDE_CAT`★ | visitor_guide.category | V43 | TRANSPORT·PARKING·ADMISSION·FACILITY·ACCESS·OVERVIEW | 신규 |
| `TRANSPORT_MODE`★ | (관람객 교통 안내 세부) | V43 | (지하철·버스·자가용·KTX 등 — 확인 필요) | 신규 |
> 이미 시드된 그룹(V7·V37): USE_YN·USER_ROLE·VERIFY_METHOD·PRG_TYPE·MSG_RCV_TYPE·WORK_*·SCHE_GUBUN·IMPORTANCE·NOTICE_TYPE·OPINION_STATUS·NOTI_TYPE·REPORT_TYPE·PARTNER_TYPE — 재시드 불필요. **"확인 필요" 코드값(EVENT_CATEGORY·QUOTATION_STATUS·TRANSPORT_MODE 등)은 도메인 에이전트 확정 후 값 고정**(COMMON_CODES §2 규칙).
### 12-3. db-engineer 인계 백로그 (신규 멱등 마이그레이션 — 번호 V44~ 권고)
| ID | 백로그 | 형태 | 우선순위 |
|---|---|---|---|
| **B1** | 감사표 B ★ 신규 그룹 + 상세 공통코드 **순증 시드**(`common_code_group`/`common_code`, `ON CONFLICT DO UPDATE`) + 기존 등재 그룹(LAYOUT_STATUS·DESIGN_STATUS·RENDER_STATUS·SHOT_PRESET 등) 시드화. 컬럼 스키마 불변(코드값=현행 저장값). "확인 필요" 값은 확정분만. | V44(멱등 시드) | **P1** |
| **B2** | 소프트 참조 **논리참조 인덱스**: P1 소프트 참조 컬럼에 `(tenant_id, <ref>_id)` 인덱스(`CREATE INDEX IF NOT EXISTS`). 예: event 참조 자식들의 `(tenant_id, event_id)`, hall 참조의 `(tenant_id, hall_id)`. 이미 있는 idx(idx_lead_event 등)는 스킵. | V45(멱등 인덱스) | **P2** |
| **B3** | 뷰/mview/함수 **순증 후보**(§11): ⓐ `v_booth_display`(부스+코드명 조인·표시용), ⓑ `mv_hall_occupancy`(홀·기간 가동률 — REFRESH CONCURRENTLY·`(tenant_id,hall_key)` 유니크 인덱스), ⓒ `mv_lead_roi_summary`(리드/ROI 월별), ⓓ `fn_period_to_quarter(date)`·`fn_utility_fee(...,ruleset_version)`(재사용 계산). **실사용 화면/AI 근거 확인 후** 생성. | V46(뷰/함수, CREATE OR REPLACE) | P3 |
| **B4** | (멀티테넌트 확장 시) 공통코드 테넌트 오버라이드 `(tenant_id, grp_code, code)` 확장 — 현재 단일 테넌트라 **보류**(구조 대비만). | 후속 | P4 |
| **B5** | (소유자 승인 후) P1 FK **DROP 마이그레이션** — 테넌트 복합키 정합·고아 검증 통과 후에만. 자동 실행 금지. | 승인 대기 | P4 |
| **B6** | **프로시저 후보**(§11-4·§13): `sp_settlement_rollup`(J9)·`sp_kpi_snapshot_build`(J2)·`sp_refresh_marts`(J1 mview 일괄 REFRESH). 성능 결정적일 때만·CREATE OR REPLACE. | V46(뷰와 동반) | P3 |
| **B7** | **자동화 배치**(§13 J1~J9) — 대상·주기·멱등은 본 표 확정. 실행 프레임워크(스케줄러·분산락)는 **아키텍처(kintex-sa/ta) 인계**, 스케줄러 배선 backend-dev. | 인계(아키텍처+backend) | P2 |
---
## 9. 변경 이력
| 버전 | 일자 | 작성자 | 내용 |
|---|---|---|---|
| v1.1 | 2026-07-12 | kintex-data-architect(DA) | **§10 FK 최소화·공통코드 관리 표준**(소유자 지시) — 물리 FK 기본 미설정+화이트리스트 4그룹(W1~W4 RBAC/공통코드 구성), 범주값 공통코드화 정책, 테넌트 스코프 정합, 소프트 참조 무결성 보완책 / **§11 뷰·구체화뷰·함수·프로시저 지침**(`v_*` 실시간 파생·`mv_*` 무거운 집계+REFRESH 전략·`fn_*` 재사용 계산·`sp_*` 집합연산/다단계 트랜잭션·남용 판단 기준) / **§13 자동화 배치 카탈로그**(J1~J9 대상·주기·멱등·잠금 — 실행 프레임워크는 아키텍처 인계) / **§12 감사표 A(현행 FK 약 40건 유지4/제거권고 P1·잔류P3)+B(범주 컬럼 34개→공통코드 그룹 매핑)+db-engineer 백로그 B1~B7(V44 시드·V45 인덱스·V46 뷰·프로시저·배치 인계, 번호 V44~ 권고)**. 기존 마이그레이션 불변·비파괴. |
| v1.0 | 2026-07-11 | kintex-data-architect(DA) | 최초 — 전사 데이터 모델(개념→논리→물리 ERD, PLANNING §7 확장)·공간 데이터 표준(PostGIS SRID0·부스 POLYGON·트렌치 POINT·배선 LineString)·데이터 표준(명명·타입·공통코드 WISE 정합·마스터/룰셋 관리)·품질·거버넌스(PII 분류·암호화·동의·보존·감사·계보)·**BI 데이터마트 M16 스타 스키마(FACT_BOOKING/SETTLEMENT/UTILITY/AUCTION/VISITOR + DIM_DATE/HALL/EVENT/EXHIBITOR + KPI_SNAPSHOT, M16-1 7지표 정합)** 정의. 물리 구현은 db-engineer 인수, 코드값 확인필요 항목은 §8 후속. |

273
plugins/zio-harness/knowledge/kintex/docs/architecture/network.md Normal file
View File

@ -0,0 +1,273 @@
# 킨텍스 자동전시시스템 — 네트워크 아키텍처 (A-5)
> 작성: 네트워크 아키텍트(NA) · 작성일: 2026-07-11 · 버전 v1.0
> 근거: `../PLANNING.md` v2.0 (§2-1 역할별 포털, §8 아키텍처, §8-1 v2.0 보강, §10 R12 외부 API 게이트), `../IMPLEMENTATION_BACKLOG.md` A-5
> 교차참조(Phase A 동시 산출·정합 대상): AA `app.md`(A-1) · SA `system.md`(A-2, 보안영역·배포 토폴로지) · TA `tech.md`(A-3, 관측성·AiTextRouter) · DA `data.md`(A-4)
> 범위: **IT 인프라 네트워크(계정·서비스·데이터 트래픽 경로)** 설계·정책. 구현(nginx·방화벽 룰·systemd·CI/CD)은 devops(DEV) 트랙. 본 문서는 설계·정책·리뷰이며 코드/설정을 생성하지 않는다.
---
## 0. 범위 경계 — M4 전시장 유틸리티 배선과의 구분 (필독)
본 문서가 다루는 것은 **플랫폼 IT 인프라 네트워크**(웹/모바일 클라이언트 ↔ 애플리케이션 ↔ 데이터/AI 워커 사이의 트래픽 경로, 보안영역, 방화벽, 부하분산, 외부 아웃바운드)이다.
이는 **M4 유틸리티 설계 모듈이 다루는 전시장 바닥 트렌치 배선(전기·조명·인터넷/전화·급배수·압축공기)과 완전히 별개**다.
| 구분 | M4 유틸리티 배선 (PLANNING §M4) | 본 문서 = IT 인프라 네트워크 (A-5) |
|---|---|---|
| 대상 | 전시홀 바닥 트렌치의 **물리 배선**(부스별 전기 kW·인터넷 회선·급배수 구) | 플랫폼 서버·서비스·클라이언트 간 **데이터 트래픽** |
| 데이터 성격 | 배선 경로 = PostGIS LineString(**업무 데이터**), 위치표시도, 자동 견적 | VLAN·서브넷·방화벽 존·LB·TLS·아웃바운드 |
| 소유 | M4 개발(BE/DB/FE) — 도메인 기능 | NA(본 문서) + devops 구현 |
| 관계 | M4의 "인터넷 유선 150,000원/회선" 신청은 **전시 참가업체가 전시장에서 쓸 회선** — 플랫폼 운영 네트워크와 무관 | 플랫폼 자체가 도는 인프라 |
> 요약: "전시장에 깔리는 인터넷 회선"(M4, 참가업체 상품)과 "이 플랫폼이 도는 네트워크"(A-5, 운영 인프라)는 이름만 겹칠 뿐 다른 계층이다. 혼동 시 보안영역·정산이 오염되므로 문서·코드·용어에서 항상 분리한다.
---
## 1. 설계 원칙
1. **2영역 분리(공개 vs 내부) 최소권한**: 불특정 다수가 접근하는 **공개/관람객 트래픽(DMZ)** 과 킨텍스 직원·관리자·백오피스가 쓰는 **내부 운영(내부망)** 을 물리/논리적으로 분리한다. 공개 영역이 뚫려도 내부망·데이터 계층에 직접 도달하지 못한다(계층 방어).
2. **역할별 프론트 = 공격면 분리**(PLANNING §8-1): organizer·exhibitor·contractor·ops·admin·public/visitor 6개 프론트를 별도 번들·도메인/서브패스로 배포. 네트워크 계층에서도 **공개 성격(public/visitor)** 과 **인증 필수(organizer·exhibitor·contractor·ops·admin)** 를 존으로 나눈다.
3. **기본 거부(default-deny)**: 인바운드·아웃바운드 모두 화이트리스트. 특히 **아웃바운드는 승인된 목적지(Claude·Gemini·PG·SMTP·모델서버)만** 포워드 프록시/egress 방화벽을 통해 허용, 그 외 전면 차단(폐쇄망 지향).
4. **단일 진입 + TLS 종단**: 모든 외부 인바운드는 리버스 프록시/로드밸런서(nginx) 한 곳에서 TLS 종단하고 내부는 사설망 트래픽. 백엔드 포트는 외부 미노출.
5. **GUARDiA 인프라와 도메인 분리**: kintex는 독립 저장소(`zio/kintex`)이며 GUARDiA ITSM/관제 인프라 서버(`101.79.17.164`)와 **별개 도메인·별개 배포 대상**이다(배포 서버·포트는 G2 게이트에서 확정). 본 설계는 그 별개 도메인 위에 존을 정의한다.
---
## 2. 보안영역(Security Zone) 모델
4계층 존 + 관리 존으로 나눈다. 존 간 통신은 명시된 방향·포트만 허용한다.
```mermaid
graph TB
subgraph INET[인터넷 / 불특정 다수]
U1[일반 대중·관람객]
U2[주최자·참가업체·업체<br/>인증 사용자]
U3[킨텍스 직원·관리자]
PGc[PG사 콜백]
end
subgraph EDGE[엣지 / DDoS·CDN·WAF]
CDN[CDN·정적 캐시<br/>공개사이트 에셋·이미지]
WAF[WAF + DDoS 방어<br/>레이트리밋]
end
subgraph DMZ[DMZ · 공개 영역]
LBp[리버스 프록시/LB<br/>TLS 종단 · 공개]
PUB[public www/expo<br/>SSR·SEO·다국어 렌더]
VIS[visitor 관람객 앱 게이트웨이]
APIGWp[공개 API GW<br/>등록·조회·티켓·wayfinding·PG콜백]
end
subgraph INTNET[내부망 · 인증·운영 영역]
LBi[내부 프록시/LB<br/>TLS · mTLS 옵션]
AUTH[SSO/JWT·RBAC·2FA<br/>인증 게이트]
APIGWi[내부 API GW<br/>organizer·exhibitor·contractor·ops·admin]
APP[공유 Spring Boot 백엔드<br/>룰·배치/배선·옥션·BI·CMS]
end
subgraph AITIER[AI 워커 존 · egress 제한]
REDIS[(Redis 작업 큐)]
NB[나노바나나 Python 워커]
OLL[온프레미스 모델<br/>Ollama 폴백]
end
subgraph DATA[데이터 존 · 최내곽]
PG[(PostgreSQL+PostGIS)]
OBJ[(오브젝트 스토리지)]
RREP[(BI 읽기전용 복제/스냅샷)]
end
subgraph MGMT[관리 존]
BAST[배스천/점프호스트<br/>SSH·운영접근]
OBS[관측성<br/>로그·메트릭·트레이스]
end
subgraph OUT[승인된 아웃바운드 목적지]
ANTH[api.anthropic.com<br/>Claude ✅승인]
GEM[generativelanguage.googleapis.com<br/>Gemini ⚠️G1 게이트]
PGext[PG사 결제 API]
SMTP[SMTP 메일]
end
U1 --> WAF --> CDN
U1 --> WAF --> LBp
U2 --> WAF --> LBp
PGc --> WAF --> LBp
U3 -->|VPN/허용 IP| LBi
LBp --> PUB & VIS & APIGWp
APIGWp --> AUTH
LBi --> AUTH --> APIGWi --> APP
APIGWp -.제한 라우팅.-> APP
APP --> REDIS --> NB
APP --> PG
APP --> OBJ
APP --> RREP
NB --> OBJ
NB -.egress only.-> GEM
APP -.egress.-> ANTH
APP -.egress.-> PGext
APP -.egress.-> SMTP
NB & APP -.폴백.-> OLL
BAST -.운영 SSH.-> INTNET & AITIER & DATA
APP & NB & PUB -.로그/메트릭.-> OBS
```
### 2-1. 존 정의·신뢰수준
| 존 | 신뢰 | 구성 요소 | 인바운드 허용 | 아웃바운드 허용 |
|---|---|---|---|---|
| **엣지** | 무신뢰 | CDN, WAF/DDoS | 인터넷 80/443 | DMZ LB |
| **DMZ(공개)** | 낮음 | 공개 LB(TLS 종단), `public` SSR, `visitor` 게이트웨이, 공개 API GW, PG 콜백 수신 | 엣지에서만 | 내부망 API GW(제한 라우팅), 데이터 존 직결 **금지** |
| **내부망(인증·운영)** | 중 | 내부 LB, SSO/인증 게이트, 내부 API GW, 공유 Spring Boot 백엔드, 룰·배치/배선·옥션·BI·CMS 서비스 | DMZ(허용 API만)·관리 존(허용 IP/VPN) | 데이터 존, AI 워커 존, 승인 아웃바운드(프록시 경유) |
| **AI 워커 존** | 중(egress 통제) | Redis 큐, 나노바나나 Python 워커, 온프레미스 모델(Ollama) | 내부망(큐 소비만) | 데이터 존(OBJ 적재), **Gemini egress 단일 경로만** |
| **데이터 존(최내곽)** | 높음 | PostgreSQL+PostGIS, 오브젝트 스토리지, BI 읽기전용 복제 | 내부망·AI 워커(정의된 서비스 계정만) | 없음(아웃바운드 전면 차단) |
| **관리 존** | 높음 | 배스천/점프호스트, 관측성(로그·메트릭·트레이스), 백업 | 운영자 VPN/허용 IP만 | 대상 존 SSH·수집 |
**핵심 규칙**: DMZ → 데이터 존 **직접 접근 절대 금지**. 공개 트래픽이 데이터에 닿으려면 반드시 내부망 백엔드 API를 경유(인증·인가·검증). 데이터 존은 아웃바운드가 없어 유출 경로 자체를 제거한다.
---
## 3. 공개(DMZ) vs 내부망 — 포털·도메인 매핑
PLANNING §2-1 6역할 포털을 네트워크 노출 성격으로 재분류한다.
| 포털/앱 | 도메인(예시, G2에서 확정) | 노출 영역 | 인증 | 렌더 경로 |
|---|---|---|---|---|
| 공개 홍보 사이트 (M12) | `www.` / `expo.` | **DMZ(공개)** | 불필요(쓰기 없음) | SSR/정적 생성 + CDN, SEO·다국어(hreflang) |
| 관람객 앱 (M10·M13) | `visitor.` (모바일 API) | **DMZ(공개)** | 셀프서비스(경량, 쓰기 제한) | 모바일 클라이언트 ↔ 공개 API GW |
| 주최자 콘솔 | `organizer.` | **내부망(인증)** | JWT SSO + Event owner | React SPA + 내부 API GW |
| 참가업체 포털 | `exhibitor.` | **내부망(인증)** | JWT SSO + Event member | React SPA |
| 업체 포털·옥션 | `contractor.` | **내부망(인증)** | 등록업체 검증 계정 | React SPA |
| 운영 대시보드(홀매니저) | `ops.` | **내부망(운영)** — 접근 IP/VPN 제한 권장 | 킨텍스 내부 계정 | React SPA |
| 관리자 백오피스 (M18) | `admin.` | **내부망(관리)** — **강한 제한**(VPN/허용 IP·2FA 필수·모바일 미제공) | 플랫폼 관리자 + 2FA 강제 | React SPA(웹 전용) |
- **공개(DMZ) 3원칙**: (1) 쓰기 권한 없음(등록·조회·티켓·매칭 조회만), (2) 데이터 존 직결 불가, (3) 캐시/CDN 적극(공개 성능·검색 노출). 공개 API GW는 **읽기·등록 한정 엔드포인트만** 화이트리스트로 노출.
- **내부망 인증 앱**: SSO/JWT + 역할·행사 이중 RBAC(§8-1). `ops.`·`admin.`은 킨텍스 내부 대역/VPN·허용 IP로 접근 자체를 좁힌다(직원 대상이므로 인터넷 전면 노출 불필요).
- **admin. 백오피스**: 최고 위험. VPN 또는 킨텍스 사내망 + 허용 IP allowlist + 2FA(OTP) 강제 + 감사로그 전량. 크로스-테넌트 권한을 가지므로 공개 인터넷 경로에서 도달 불가하게 한다.
---
## 4. 방화벽 · WAF 정책
### 4-1. 방화벽(존 간 트래픽 매트릭스)
| From \ To | 엣지 | DMZ | 내부망 | AI 워커 | 데이터 | 관리 | 인터넷(egress) |
|---|---|---|---|---|---|---|---|
| **인터넷** | 443/80 | (엣지 경유) | ✗ | ✗ | ✗ | ✗ | — |
| **엣지** | — | 443 | ✗ | ✗ | ✗ | ✗ | ✗ |
| **DMZ** | — | — | 내부 API GW(허용 엔드포인트 https) | ✗ | ✗ | ✗ | ✗ |
| **내부망** | — | — | — | Redis 6379·워커 | PG 5432·OBJ https | ✗ | 프록시 경유(§5) |
| **AI 워커** | — | — | 완료 푸시(WebSocket) | — | OBJ https | ✗ | Gemini 단일(§5) |
| **데이터** | — | — | — | — | — | ✗ | **✗(전면 차단)** |
| **관리** | — | — | SSH | SSH | SSH(제한) | — | 패키지/업데이트(제한) |
- 기본 정책 = **DROP**. 위 표의 명시 경로만 ALLOW. 포트는 예시(운영값은 devops가 G2에서 확정).
- 백엔드(Spring Boot)·Redis·PostgreSQL·오브젝트 스토리지 포트는 **인터넷에 미노출** — 사설 대역에서만 청취.
- DMZ↔내부망 사이는 **애플리케이션 프로토콜(HTTPS/API)만** 통과, DB 프로토콜(5432 등) 횡단 금지.
### 4-2. WAF (공개 트래픽 전면)
DMZ 진입 전 엣지에서 WAF를 통과시킨다.
- **OWASP Top10 룰셋**(SQLi·XSS·경로조작·SSRF·파일업로드 악용). 도면/이미지 업로드(M2·M3·M5)·CMS(M17)·공개 등록 폼(M10)이 주요 표적 → 업로드 확장자·MIME·크기 검증을 WAF + 애플리케이션 이중.
- **봇/스크래핑 방어**: 공개사이트(M12)는 SEO 목적상 정상 크롤러(구글봇 등)는 허용하되, 등록·티켓·비즈매칭 엔드포인트는 봇 챌린지·리캡차 옵션.
- **PG 콜백 검증**: DMZ에서 수신하는 PG 결제 콜백은 **출처 IP allowlist + 서명 검증**을 WAF/애플리케이션에서 이중 확인(위조 콜백 차단).
- **관리자·옥션 엔드포인트**: `admin.`·M15 옥션 응찰(가격 조작 민감)은 WAF 예외 없이 최상위 룰 + 레이트리밋 강화.
---
## 5. 외부 연동 아웃바운드 정책 (승인 게이트 준수)
**폐쇄망 지향 — egress 기본 차단.** 승인된 목적지만 포워드 프록시(egress 게이트웨이)를 통해 도메인 화이트리스트로 허용하고, 그 외 전량 차단·로깅한다.
| 목적지 | 용도 | 승인 상태 | 경로 · 정책 |
|---|---|---|---|
| `api.anthropic.com` | Claude 텍스트 AI(규정검수·서류·BI 인사이트·AiTextRouter 기본) | **✅ 승인**(2026-07-03, 소유자) | 백엔드 → egress 프록시. `ANTHROPIC_API_KEY`는 **서버 env only** — DB·코드·커밋·로그·응답 기록 금지. 실패 시 Ollama 폴백 |
| `generativelanguage.googleapis.com` | Gemini 나노바나나 이미지 생성(M5) | **⚠️ 미승인 — G1 게이트**(PLANNING R12) | **나노바나나 Python 워커에서만** egress. `GEMINI_API_KEY`는 워커 env only(백엔드 미취급). **G1 소유자 승인 전 실호출·배포 금지** → 미승인 시 워커 목/degraded(import·구조만 성립). 승인 시에도 워커 존 단일 경로만 개방 |
| PG사 결제 API | M9 정산·결제, M10 티켓, M15 발주 | 결제 필수(도메인 확정 G2) | 백엔드 → egress. 콜백은 인바운드(§4-2). 키·상점ID env only |
| SMTP | 2차 인증 EMAIL 코드·알림 발송 | 필요 | 지정 SMTP host:port만. 미설정 시 로컬 로그 모드 |
| 온프레미스 모델(Ollama 등) | AI 폴백·임베딩 | 내부(egress 아님) | AI 워커/내부망 내부 통신 — 외부 나가지 않음 |
**아웃바운드 통제 원칙**:
1. **단일 egress 게이트웨이** 경유 — 각 서비스가 임의 외부 IP로 직접 나가지 못한다. 목적지 도메인 allowlist로만 통과.
2. **키 격리 = 네트워크 격리와 정합**: Gemini 키는 워커 존에만, Claude/PG 키는 백엔드에만. 데이터 존은 아웃바운드 자체가 없어 어떤 키도 외부로 나갈 수 없다.
3. **G1 게이트 강제**: Gemini egress 룰은 G1 승인 이전엔 **비활성(차단)** 상태로 배포. 승인 티켓 없이 열리지 않도록 devops가 방화벽/프록시 룰을 게이트에 종속.
4. **감사**: 전 아웃바운드는 목적지·시각·서비스만 로깅(요청 본문·키·응답 미기록 — 자격증명 보호 원칙).
---
## 6. 부하분산 · TLS 종단 · API 게이트웨이
### 6-1. 로드밸런싱
- **공개 LB(DMZ)**: `www/expo`·`visitor`·공개 API GW 앞단. SSR 렌더 인스턴스와 정적 에셋(CDN 오프로드)을 분리. 관람객 대량 트래픽(개막일 사전등록·체크인 피크, M10)을 수평 확장 대상으로 본다.
- **내부 LB(내부망)**: 공유 Spring Boot 백엔드 앞단. organizer·exhibitor·contractor·ops·admin 트래픽을 라우팅. 무상태 세션(JWT) 전제로 라운드로빈/최소연결 + 헬스체크.
- **WebSocket/STOMP**: 나노바나나 완료 푸시·옥션 실시간 순위(M15)는 WS 스티키/전용 경로 필요 — LB에서 WS 업그레이드·타임아웃·스티키 정책 별도(TA `tech.md`와 정합).
- **AI 워커**: HTTP 인입 대상 아님(Redis 큐 소비형) — LB 대상 아님, 워커 수평 확장은 큐 컨슈머 스케일로 처리.
### 6-2. TLS 종단
- **모든 외부 인바운드는 LB(nginx)에서 TLS 종단**. 인증서는 공개 도메인(공개사이트)과 인증 포털 도메인 각각 관리(SAN/멀티도메인 또는 개별).
- 종단 후 내부는 사설망 평문 또는 존 간 mTLS(옵션). **DMZ→내부망 호출은 mTLS 권장**(공개 영역이 내부 API를 사칭 호출하지 못하도록).
- HSTS·TLS1.2+ 강제·약한 cipher 비활성. `admin.`·옥션 등 민감 경로는 최신 TLS만.
### 6-3. API 게이트웨이 (공개/내부 분리)
- **공개 API GW(DMZ)**: 화이트리스트 엔드포인트만 — 관람객 등록·조회·티켓·wayfinding 조회·PG 콜백. **쓰기·관리·설계·옥션 엔드포인트 노출 금지**. 레이트리밋·봇 방어 1차.
- **내부 API GW(내부망)**: 인증 필수 전 기능. SSO/JWT 검증 → 역할·행사 RBAC(§8-1) → 백엔드 라우팅. 옥션(M15)·설계(M2~M5)·BI(M16)·admin(M18) 전부 여기.
- 두 GW는 **동일 공유 백엔드**를 바라보되 **노출 표면이 다르다**(공개는 극히 일부, 내부는 전체). 이 분리가 최소권한 네트워크의 핵심.
---
## 7. DDoS · 레이트리밋 (공개 트래픽)
공개 영역은 불특정 다수 노출 → 가용성 위협 상수. 계층 방어한다.
| 계층 | 대상 | 정책 |
|---|---|---|
| 엣지(WAF/CDN) | 볼류메트릭 DDoS(L3/4), 정적 에셋 | CDN 캐시로 오리진 보호, SYN/UDP 플러드 스크러빙, 지오/IP 평판 필터 |
| 공개 LB | L7 요청 폭주 | 커넥션·요청률 상한, slowloris 타임아웃, 동시연결 캡 |
| 공개 API GW | 엔드포인트별 레이트리밋 | 등록·티켓·비즈매칭은 IP/계정별 토큰버킷. **개막일 피크(M10 체크인)** 대비 버스트 허용치 별도 |
| 애플리케이션 | 남용 방지 | 로그인·2FA·PG 콜백은 강한 레이트리밋 + 실패 잠금(§8-1 로그인 실패 잠금과 정합) |
- **옥션(M15) 특수**: 마감 직전 응찰 폭주·자동응찰 스크립트 가능성 → 응찰 API는 계정별 레이트리밋 + 서버 권위 타임스탬프(클라이언트 시간 불신) + 이상 패턴(초당 다중 인하) 플래그.
- **관람객 체크인 오프라인 폴백**(PLANNING M10 한계): 현장 네트워크 불안정·DDoS 시에도 QR 체크인은 오프라인 대기열·후동기화가 가능해야 함 — 네트워크 장애가 현장 운영 정지로 직결되지 않도록 클라이언트 폴백을 전제.
---
## 8. 세그먼테이션 · 격리
1. **행사(Event) 단위 데이터 격리**(PLANNING R10): 부스 설계는 경쟁사 민감 정보. 네트워크가 아니라 **애플리케이션 RBAC + 데이터 존 접근 계정 최소화**로 격리(같은 백엔드 안에서 행사별 인가). 네트워크 세그먼트는 존 단위, 테넌트 격리는 인가 계층 — 이중.
2. **서비스 계정 분리**: 백엔드·워커·BI 복제는 **각기 다른 DB 계정/최소 권한**으로 데이터 존 접근(워커는 OBJ 쓰기만, BI는 읽기전용 복제만). 한 서비스 침해가 전 데이터로 번지지 않게 한다.
3. **BI 부하·경로 분리**(PLANNING §8-1): 운영 DB 보호를 위해 BI(M16)는 **읽기전용 복제/스냅샷(KpiSnapshot)** 을 별도로 바라본다 — 운영 트래픽과 분석 트래픽의 경로 분리.
4. **관리 평면 분리**: SSH·운영 접근은 배스천 경유만(직접 접근 금지). 관측성(로그·메트릭)은 관리 존에 수집하되 로그에 자격증명·PII·스택트레이스 미기록(에러 응답 = 요약만, GUARDiA 보안 원칙 정합).
5. **모바일 채널**: 참가업체 리드캡처·홀매니저 현장 검수·업체 반입 QR·관람객 배지(§2-1)는 각 포털의 API 표면만 사용 — 모바일이라고 별도 백도어 없음. 공개(visitor)는 DMZ, 인증(exhibitor/ops/contractor 모바일)은 내부 API GW.
---
## 9. 폐쇄망 · 온프레미스 제약 반영
- **egress 기본 차단**은 폐쇄망 운영 기관 배포를 겨냥한 기본값이다. 승인 4목적지(Claude·Gemini(G1)·PG·SMTP) 외 외부 통신이 없어야 정상.
- **완전 폐쇄망(외부 API 전면 불가) 시나리오**: Claude/Gemini 미허용 환경에서는 온프레미스 모델(Ollama)로 폴백 — 텍스트 AI는 AiTextRouter가 자동 폴백, 이미지 생성(M5)은 온프레미스 대체(SDXL 등) 어댑터 검토(PLANNING R12 완화책). 이 경우 egress 게이트웨이의 외부 룰 전량 비활성.
- **GUARDiA 인프라 비침투**: kintex는 GUARDiA ITSM 관제망·`101.79.17.164`와 트래픽·자격증명·DB를 공유하지 않는다(별개 도메인·별개 존). 상호 egress/인바운드 룰 없음.
- **내부 모델 서버**는 AI 워커 존 내부 통신(외부 egress 아님) — RAM 제약(온프레미스 소형모델) 고려는 TA/AI 트랙, 네트워크는 내부 경로만 보장.
---
## 10. 미결·후속(devops·SA 정합 필요)
| # | 항목 | 의존 |
|---|---|---|
| N-1 | 실제 도메인·서브도메인·포트·인증서 발급 | **G2 게이트**(배포 대상 서버·도메인 확정) |
| N-2 | Gemini egress 방화벽 룰 활성화 | **G1 게이트**(소유자 승인) — 승인 전 차단 상태 배포 |
| N-3 | 존 물리 구현(VLAN/보안그룹/네임스페이스) vs 논리 분리 선택 | SA `system.md`(A-2) 배포 토폴로지와 정합 |
| N-4 | CDN·WAF 벤더·DDoS 스크러빙 사업자 선정 | devops·비용 |
| N-5 | mTLS(DMZ↔내부망) 적용 범위·인증서 회전 | TA `tech.md`(A-3) |
| N-6 | 관측성 수집 경로·보존정책(PII/자격증명 미기록 검증) | TA·QA |
| N-7 | BI 읽기전용 복제 토폴로지(복제 지연·경로) | DA `data.md`(A-4) |
> 본 문서는 네트워크 **설계·정책·존 계약**을 정의한다. 실제 nginx/방화벽/보안그룹/CI·CD 설정 코드는 devops(DEV)가 Phase E에서 구현하며, 존 모델·아웃바운드 게이트·2영역 분리 원칙은 본 문서를 계약으로 준수한다.

373
plugins/zio-harness/knowledge/kintex/docs/architecture/sso-hr-integration.md Normal file
View File

@ -0,0 +1,373 @@
# 킨텍스 AI 전시·행사시스템 — Open SSO · 인사(조직) API 연동 아키텍처
> 산출: 시스템 아키텍트(SA) · 작성일: 2026-07-12 · 대상: 소유자 지시("직원 인사(조직)정보는 API 방식, Open SSO 도입")
> 정합 근거: [`system.md`](system.md)(SA §5·§6 인증/연동), [`app.md`](app.md)(AA 인증 계약), [`network.md`](network.md)(NA 존/아웃바운드), [`data.md`](data.md)(DA 마스터/소프트참조), [`../PLANNING.md`](../PLANNING.md) §2(6역할)·§5B(공통·시스템관리)·§8, `../DEVELOPMENT_GUIDE.md` §4·§5
> **본 문서는 설계·계약·이행계획만 정본. src·기존 인증코드 미수정(파괴적 구현 금지).** 실제 구현은 인계 백로그(§9)로 각 dev 트랙에 위임.
> 확정 스택(불변): React 18/19(Vite·TS) + Spring Boot 3.x(Java 17)+MyBatis + PostgreSQL(PostGIS) + Redis. 신규 IdP(Keycloak)는 **온프레미스 인프라 구성요소**로 추가(스택 위반 아님).
---
## 0. 요지 (Executive Summary)
| 항목 | 결정 | 근거 |
|---|---|---|
| **인증 프로토콜** | **OIDC(우선) + SAML 2.0(옵션)** — Authorization Code + PKCE | 표준·웹/모바일 공통·JWKS 검증. SAML은 고객사 레거시 IdP 대비 폴백 |
| **IdP** | **Keycloak(자체 호스팅, 온프레미스)** | 오픈소스·OIDC/SAML/그룹·클레임 매핑·2FA·back-channel 로그아웃 내장. 외부 인터넷 API 아님(내부망 IdP) |
| **기존 JWT+2FA 관계** | **삭제·교체 금지. 공존(coexist)** — SSO를 1차 인증, 앱 JWT를 세션토큰으로 **브로커 발급**. 로컬 로그인은 폴백으로 유지 | W12 자산(app_user·event_member·TotpService) 보존, 무중단 이행 |
| **2FA** | IdP가 OTP 제공 시 **위임**(앱 OTP 강제 해제), 미제공 시 앱 TOTP 유지 | 중복 2FA 방지·기존 `TwoFactorService` 재사용 |
| **인사·조직** | 로컬 마스터 유지가 아니라 **`HrDirectoryClient` 어댑터로 외부 HR API 조달** + 로컬 **읽기 캐시 스냅샷**(HR 미가용 폴백) | HR 정본화, dept/sys_user는 캐시로 전환(멱등 upsert 배치) |
| **3자 매핑** | **SSO subject ↔ HR 사번(empNo) ↔ 로컬 user(app_user.id)** 매핑 테이블 신설 | 계정·조직·권한 정합 단일 키 체계 |
| **이행** | **coexist → pilot(파일럿 부서) → cutover(SSO 우선) → 로컬로그인 축소** 4단계 + 롤백 게이트 | 파괴 없는 점진 전환 |
**보안 정합(불변):** Open SSO(자체 IdP)·HR API(고객 내부망 인사시스템)는 **온프레미스/내부 통합 → 외부 인터넷 API 금지 규칙에 해당하지 않음**(Claude/Gemini 예외와 별개 범주). 단, 토큰·클라이언트 시크릿·HR 자격증명은 **env/시크릿 스토어 only**, 응답·로그·커밋 미노출, 마스킹 유지.
---
## 1. 현행(As-Is) 인증·조직 기준선
설계는 기존 코드를 **읽어 확인한 실제 계약** 위에 얹는다(교체 없음).
| 자산 | 실체 | 본 설계에서의 처리 |
|---|---|---|
| `app_user`(V2) | id·email·display_name·password_hash(BCrypt)·hall_manager·otp_secret·failed_login_count·locked_until·status | **보존.** 로컬 계정 정본 → 이행 후 "SSO 매핑 대상 + 로컬 폴백" |
| `event_member`(V2) | 행사 RBAC(ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER, booth/company 스코프) | **보존.** IdP는 행사 역할을 모름 → 행사 역할은 계속 로컬 권위 |
| `app_user.role_code`(V31) | 전역 역할(rc 클레임) | IdP 그룹/클레임 → 전역 역할 매핑 소스로 확장 |
| `dept`(V37) | 부서 트리(tenant_id·id·parent_id·sort_order·use_yn) | **HR 정본 시 읽기 캐시로 전환**(스냅샷 upsert) |
| `company`(V2/V37) | 등록업체(M7 응찰 게이트) | 불변(HR 무관 — 외부 파트너) |
| `JwtService` | HS256, 클레임 sub·name·roles(eventId→role)·hm·tid·rc | **불변.** SSO 성공 후 이 서비스로 **동일 형태 앱 JWT를 브로커 발급**(다운스트림 RBAC 무변경) |
| `TwoFactorService`/`TotpService`/`LoginAttemptService` | 로컬 2FA·잠금·챌린지 | IdP 2FA 위임 시 우회, 로컬 폴백 시 유지 |
| `JwtAuthenticationFilter` | Bearer 앱JWT → SecurityContext | **불변.** SSO 도입해도 백엔드 보호경로는 계속 앱 JWT 검증(핵심 무중단 포인트) |
> **설계 핵심 원칙:** SSO는 **로그인 게이트웨이만 교체**한다. 로그인 성공의 산출물은 여전히 "기존 형태의 앱 JWT"이므로, 84개 화면·전 RBAC 가드·행사 스코프 로직은 **한 줄도 바뀌지 않는다**. HR API는 **조직 마스터의 데이터 출처만 교체**한다(dept 트리 소비자 무변경).
---
## 2. 설계 A — Open SSO 도입 (OIDC / Keycloak)
### 2-1. 채택 결정 (ADR)
| # | 결정 | 이유 | 대안·트레이드오프 |
|---|---|---|---|
| A1 | **OIDC 우선**(SAML 옵션) | 웹+모바일(expo-auth-session) 동일 표준, JSON/JWKS, PKCE로 공개 클라이언트 안전 | SAML-only(모바일·SPA 부적합) 배제. 고객 레거시가 SAML뿐이면 Keycloak가 SAML IdP↔OIDC 브로커로 흡수 |
| A2 | **Keycloak 자체 호스팅** | 오픈소스·온프레미스·그룹/클레임 매핑·OTP·Identity Brokering(외부 AD/LDAP/SAML 연합)·back-channel 로그아웃 | 상용 IdP(비용·외부 SaaS=보안 위반) 배제. 경량 대안(자체 OIDC 구현)은 표준 준수·유지비 열위 |
| A3 | **브로커드 세션토큰**(IdP 토큰 → 앱 JWT 교환) | 다운스트림 RBAC·행사 스코프·tid/rc 클레임 무변경, 무상태 유지 | IdP 액세스토큰 직접 신뢰(리소스서버 모드)는 **행사 RBAC 클레임 부재**로 전 가드 재작성 필요 → 이행기엔 배제(§2-6 장기 옵션으로만) |
| A4 | **로컬 로그인 폴백 유지** | IdP 장애 시 관리자·핵심 운영 지속(가용성 NFR) | IdP 단일 의존(장애 시 전면 로그인 불가) 배제 |
**IdP 후보 근거:** Keycloak(1순위, 위 A2) / 대안 Authentik·ZITADEL(경량·최신 UX이나 조직 내 운영 실적·AD 연합 성숙도에서 Keycloak 우위) / Gluu·Ory Hydra(각각 무거움·인증 파트 분리 필요). **킨텍스 온프레미스·AD 연합·SAML 흡수** 요건에서 Keycloak 채택.
### 2-2. 토폴로지 (존 배치)
Keycloak는 **내부 애플리케이션 존**에 배치하고, 브라우저 리다이렉트를 위해 **리버스 프록시(nginx)의 별도 vhost**(`auth.<kintex-domain>`)로만 외부 노출한다. HR API·AD 연합은 IdP↔내부망 구간.
```mermaid
graph TB
subgraph EDGE["엣지 / DMZ (nginx TLS 종단)"]
RP[리버스 프록시<br/>app.· auth.· api. vhost]
end
subgraph APPZ["애플리케이션 존 (내부망)"]
FE[역할별 프론트 SPA + 공개/관람객]
BE[공유 백엔드 Spring Boot × N<br/>OIDC RP + 앱JWT 브로커]
KC[Keycloak IdP<br/>realm=KINTEX · OIDC/SAML · OTP]
end
subgraph DATAZ["데이터 존 (최심부)"]
PG[(PostgreSQL+PostGIS<br/>app_user·매핑·조직 캐시)]
KCDB[(Keycloak DB<br/>별도 스키마/DB)]
RED[(Redis<br/>state·nonce·세션상관)]
end
subgraph HRZONE["고객 내부망 (연동 대상)"]
AD[AD / LDAP<br/>직원 계정]
HRAPI[HR 인사시스템 API<br/>조직·직원 마스터]
end
FE -->|1 로그인 리다이렉트| RP --> KC
KC -.연합(선택).-> AD
FE -->|2 code+PKCE 콜백| RP --> BE
BE -->|3 code→token 교환·JWKS 검증| KC
BE -->|4 앱 JWT 발급| FE
BE --> PG
BE -.HrDirectoryClient(배치·조회).-> HRAPI
KC --> KCDB
BE --> RED
```
**배치 규칙**
- Keycloak DB는 앱 PG와 **별도 데이터베이스/스키마**(계정 데이터 격리·백업 주기 분리).
- `auth.<kintex-domain>` vhost는 IdP UI/토큰 엔드포인트만 프록시. 백오피스(admin.)와 동일하게 **접근 제한 정책**은 NA 확정.
- 아웃바운드: Keycloak→AD/LDAP, 백엔드→HR API는 **내부망 구간**(인터넷 egress 아님). NA egress 화이트리스트에 인터넷 목적지 추가 없음.
### 2-3. 로그인 시퀀스 (Authorization Code + PKCE → 앱 JWT 브로커)
```mermaid
sequenceDiagram
participant U as 사용자(브라우저/앱)
participant FE as 프론트(SPA/Expo)
participant BE as 백엔드(OIDC RP)
participant KC as Keycloak(IdP)
U->>FE: 로그인 클릭
FE->>FE: PKCE code_verifier/challenge, state, nonce 생성
FE->>KC: /authorize (code, PKCE challenge, redirect_uri)
KC->>U: 로그인 폼(+IdP OTP if 위임)
U->>KC: 자격증명(+OTP)
KC->>FE: redirect_uri?code=...&state=...
FE->>BE: POST /api/auth/oidc/callback (code, code_verifier, state)
BE->>KC: token 교환(code + code_verifier + client_secret)
KC->>BE: id_token + access_token (JWT)
BE->>KC: JWKS 공개키(캐시) — id_token 서명·iss·aud·nonce·exp 검증
BE->>BE: subject(sub)로 매핑 조회 → 로컬 user 해석/JIT 프로비저닝(§2-5)
BE->>BE: event_member 행사역할·hall_manager·tid·rc 조립
BE->>FE: 앱 JWT(JwtService.issue) + 워크스페이스(기존 LoginResponse 형태)
FE->>FE: 기존 저장키에 앱 JWT 저장 — 이후 전 API는 기존 그대로
```
**핵심:** 5~7단계 산출물 = **현행 `LoginResponse`와 100% 동일**. `/api/auth/oidc/callback`만 신설, 나머지 전 경로 불변.
### 2-4. 토큰 갱신·로그아웃 시퀀스
| 흐름 | 설계 |
|---|---|
| **앱 JWT 갱신** | 현행 TTL 정책 유지. 만료 시 프론트가 **silent OIDC 재인증**(prompt=none, IdP 세션 유효 시 무마찰) → 백엔드가 앱 JWT 재브로커. 리프레시 토큰은 백엔드가 보관(HttpOnly·서버측), 프론트 미노출 |
| **IdP 세션 만료** | silent 재인증 실패 → 로그인 화면. 앱 JWT 짧게, IdP 세션이 마스터 수명 |
| **로그아웃** | 프론트 로컬 토큰 파기 + `/api/auth/oidc/logout` → Keycloak end-session(`id_token_hint`). **back-channel logout**: Keycloak → 백엔드 `/api/auth/oidc/backchannel-logout`(로그아웃 토큰 검증) → Redis 세션상관 무효화(다중 인스턴스 팬아웃) |
| **단일 로그아웃(SLO)** | Keycloak realm SSO 로그아웃으로 연동 클라이언트 전파(웹·모바일·타 GUARDiA 연계 시) |
### 2-5. 계정 매핑 · JIT 프로비저닝 (SSO subject ↔ 로컬 user)
```mermaid
graph LR
SUB[OIDC sub<br/>=IdP subject] --> MAP[user_identity 매핑]
EMP[HR empNo<br/>=사번] --> MAP
LU[app_user.id<br/>=로컬 user] --> MAP
MAP --> RESOLVE{로컬 user 존재?}
RESOLVE -->|Yes| LOGIN[역할 조립 → 앱 JWT]
RESOLVE -->|No| JIT[JIT 프로비저닝<br/>app_user upsert + 매핑 생성]
JIT --> LOGIN
```
- **매핑 키:** IdP `sub`(불변 식별자) 우선. 보조 매칭키 = 이메일 + HR 사번(empNo, IdP 커스텀 클레임). **이메일 단독 매칭 금지**(재사용·변경 위험) — sub↔empNo 확정 후 email은 표시용.
- **JIT 프로비저닝:** 첫 SSO 로그인 시 매핑 없으면 `app_user`를 **password_hash 없이(SSO 전용 플래그)** 생성 + `user_identity` 매핑 생성. 로컬 폴백 비번은 미설정(SSO 전용 계정).
- **충돌 규칙:** 동일 이메일에 기존 로컬 계정 존재 → **자동 병합 금지, 관리자 수동 링크**(계정 탈취 방지). `link_status`(UNLINKED/LINKED/CONFLICT).
- **역할 소스:** 전역 역할(rc)·hall_manager = IdP 그룹/클레임 매핑(§2-7). **행사 역할(event_member)은 로컬 권위 유지**(IdP는 행사를 모름).
### 2-6. 기존 JWT+2FA 공존안 (핵심)
| 관심사 | 공존 규칙 |
|---|---|
| **1차 인증** | Keycloak(OIDC). 성공 후 백엔드가 **기존 `JwtService.issue()`로 앱 JWT 브로커** — 다운스트림 무변경 |
| **로컬 로그인** | `/api/auth/login`·`/login/secure` **유지**(폴백). 관리자·핵심 운영은 IdP 장애 시 로컬 폴백 허용. 일반 사용자는 이행 단계별로 SSO 우선/로컬 차단(§8) |
| **2FA** | IdP realm이 OTP 요구 시 → 앱 `requiresOtp` 위임(앱 OTP 강제 해제, 이중 2FA 방지). IdP OTP 미구성 계정·로컬 폴백 로그인 → **기존 `TwoFactorService` 그대로** |
| **admin 비번** | `ADMIN_PASSWORD_ENC` env 시드 정책 **유지**(IdP 장애 시 최후 관리자 접근) |
| **토큰 신뢰 모드** | 이행기 = **브로커 모드**(앱 JWT). 장기 옵션 = 리소스서버 모드(IdP 토큰 직접, 커스텀 클레임 매퍼로 행사역할 주입) — **행사 RBAC 재검증 부담으로 이행 완료 후 별도 과제**(A3) |
**공존 상태 판정 로직(개념):**
```
로그인 요청
├─ SSO 경로(/oidc/callback): IdP 검증 성공 → 매핑 해석 → 앱 JWT (2FA는 IdP 위임)
└─ 로컬 경로(/login, /login/secure): 기존 TwoFactorService (단계별 허용범위 §8)
다운스트림(전 API): 기존 JwtAuthenticationFilter가 앱 JWT만 검증 — 경로 무관 동일
```
### 2-7. 멀티테넌트·역할 매핑
- **tenant:** realm=단일(`KINTEX`) 또는 realm 그룹 클레임 `tenant`. 앱 `tid` 클레임 = IdP `tenant` 클레임(부재 시 기준 테넌트 `KINTEX` 폴백, 현행 `normalizeTenant` 규칙 준수).
- **역할 매핑표(IdP 그룹/클레임 → 앱 역할):**
| IdP 그룹/클레임 | 앱 전역 역할(rc) | hall_manager | 트랙 |
|---|---|---|---|
| `/kintex/admin` | ADMIN | - | 내부 백오피스 |
| `/kintex/manager` | MANAGER | - | 내부 운영 |
| `/kintex/hall-manager` | (rc null) | true | 내부 운영(홀) |
| `/kintex/staff` | STAFF | - | 내부 직원 |
| (매핑 없음·외부) | null | false | 행사역할은 event_member로 |
- **6역할 정합:** 주최자·참가업체·장치/공사업체는 대개 **외부**(HR 대상 아님) → SSO 계정이라도 행사 역할은 `event_member` 초대로만 부여. 관람객/일반대중은 셀프서비스(SSO 대상 아님·별도 트랙 §8 note).
### 2-8. 웹 + 모바일 플로우
| 클라이언트 | 라이브러리 | 리다이렉트 URI | 특이사항 |
|---|---|---|---|
| **웹 SPA(역할별 6종)** | `oidc-client-ts` 또는 백엔드 BFF 콜백 | `https://<role>.<kintex-domain>/auth/callback` | PKCE. 역할별 번들마다 클라이언트 등록(또는 와일드카드 redirect + 역할 라우팅) |
| **모바일(Expo)** | `expo-auth-session`(PKCE 기본) | `kintexai://auth/callback` (앱스킴) + `https://<domain>/auth/native-callback`(유니버설 링크 폴백) | 공개 클라이언트(시크릿 없음)=PKCE 필수. B2B 앱=SSO+IdP OTP, B2C 관람객 앱=SSO 대상 아님(셀프서비스 유지) |
- **클라이언트 등록(Keycloak):** `kintex-web`(confidential, BFF 콜백) / `kintex-mobile`(public, PKCE). redirect_uri·web_origins(CORS)·post_logout_redirect 화이트리스트 등록.
- **모바일 레퍼런스:** WISE 모바일(`workspace/guardia-messenger/app/uiws`) 2FA 로그인 화면 컨벤션 위에 expo-auth-session 브라우저 플로우 삽입(디자인은 Stitch 경유 — MEMORY 준수).
---
## 3. 설계 B — 인사(조직) API 연동 (HrDirectoryClient)
### 3-1. 채택 결정 (ADR)
| # | 결정 | 이유 |
|---|---|---|
| B1 | **어댑터 패턴 `HrDirectoryClient` 인터페이스 + 고객 HR 구현** | 고객사별 HR API 상이 → 인터페이스로 격리, 구현만 교체. Mock 구현으로 개발·폴백 |
| B2 | **로컬 읽기 캐시 스냅샷 유지**(HR 미가용 폴백) | HR 장애·야간 배치 실패에도 조직도·직원조회 지속(가용성). HR=정본, 로컬 dept/직원=파생 캐시 |
| B3 | **증분 동기화(배치) + 실시간 조회 혼합** | 조직 트리·직원 마스터는 배치 스냅샷(멱등 upsert), 로그인 순간 신원 확인은 실시간 조회(선택) |
| B4 | **PII 최소 수집·마스킹** | 직원 개인정보 경계(SA §5-3). 필요 필드만 수집, 연락처·주민식별 미수집/마스킹 |
### 3-2. 어댑터 계약 (인터페이스 · DTO)
**인터페이스(개념 시그니처 — backend-dev 구현):**
| 메서드 | 목적 | 동기성 |
|---|---|---|
| `List<HrDept> fetchOrgTree(tenantId, sinceRev?)` | 조직(부서) 트리 — 전체 또는 변경분 | 배치 |
| `Page<HrEmployee> fetchEmployees(tenantId, sinceRev?, page)` | 직원 마스터 — 전체/증분 페이지 | 배치 |
| `Optional<HrEmployee> findByEmpNo(tenantId, empNo)` | 로그인·매핑 시 단건 신원 확인 | 실시간(선택) |
| `SyncCursor currentRevision(tenantId)` | 증분 동기화 커서(변경 기준점) | 배치 |
**표준 DTO(계약·PII 최소):**
```
HrDept { empDeptCode, deptName, parentDeptCode, sortOrder, useYn, revision }
HrEmployee {
empNo, // 사번 = 매핑 정본 키
name, // 표시명
email, // SSO sub 보조 매칭·표시
deptCode, // 소속 부서(HrDept.empDeptCode 참조)
positionCode, // 직급(공통코드 POSITION 매핑)
employmentStatus, // 재직상태 ACTIVE|LEAVE|RETIRED
revision // 증분 동기화 기준
// 미수집: 주민번호·개인 연락처·급여 등 (PII 최소)
}
```
- **원격/캐시 이원화:** 서비스 계층은 항상 `HrDirectoryClient`를 부르되, HR 실패 시 `HrSnapshotRepository`(로컬 캐시)로 폴백(`degraded=true` 표기). 소비자(조직도·직원선택 컴포넌트)는 출처를 모름.
### 3-3. 동기화 전략
```mermaid
sequenceDiagram
participant SCH as 스케줄러(배치)
participant HC as HrDirectoryClient
participant HR as 고객 HR API
participant SNAP as 로컬 스냅샷(hr_dept_snapshot·hr_emp_snapshot)
participant DEPT as dept(파생 캐시)
SCH->>HC: fetchOrgTree(sinceRev) / fetchEmployees(sinceRev)
HC->>HR: GET 조직·직원 변경분
alt HR 정상
HR->>HC: 변경 레코드
HC->>SNAP: 멱등 upsert(revision 기준)
SNAP->>DEPT: dept 트리 파생 반영(use_yn·parent 매핑)
else HR 미가용
HC->>SNAP: 기존 스냅샷 유지(degraded)
Note over DEPT: 조직도·직원조회는 마지막 스냅샷으로 계속 서비스
end
```
- **주기:** 조직 트리·직원 = 야간 전체 리컨실 + 주간(수시) 증분. 로그인 시점 신원은 `findByEmpNo` 실시간(선택, 실패 시 스냅샷).
- **멱등:** `revision`/`empNo`/`empDeptCode` 기준 upsert. 삭제는 **소프트**(useYn='N', employmentStatus=RETIRED) — 물리삭제 금지(감사·과거 참조 보존).
- **정본 전환:** HR 정본화 후 `dept`·직원정보는 **읽기 전용 캐시**. 백오피스 조직 편집 UI는 "HR 마스터 편집 안내"로 전환(직접 수정 차단), 단 로컬 전용 부서(외부 파트너 그룹핑 등)는 `source='LOCAL'` 플래그로 공존 허용.
### 3-4. 기존 dept/sys_user 매핑
| 현행 | HR 연동 후 |
|---|---|
| `dept`(로컬 편집) | `source` 컬럼 추가 → `HR`(캐시, 읽기전용) / `LOCAL`(로컬 전용, 편집가능) 공존. HR 파생행은 배치만 갱신 |
| `sys_user`(=app_user 조회) | 직원 신원(name·dept·position)은 **HR 스냅샷 조인**으로 표시, `app_user`는 로그인/권한 최소필드만 |
| 조직도 화면(WISE 트리) | 데이터 출처만 HR 스냅샷 → 컴포넌트 무변경 |
---
## 4. 3자 매핑 통합 규칙 (SSO subject ↔ HR 사번 ↔ 로컬 user)
| 키 | 소유 | 역할 |
|---|---|---|
| `sub`(OIDC subject) | Keycloak | 로그인 신원 불변 식별자 |
| `empNo`(사번) | HR API | 직원·조직 정본 키(직급·부서·재직상태) |
| `app_user.id` | 로컬 | 앱 계정·권한(event_member·hall_manager·tid) 앵커 |
- **연결 테이블 `user_identity`**(§5): (tenant_id, app_user_id) ↔ (idp_sub, emp_no) + link_status.
- **로그인 해석 순서:** `sub` → user_identity 조회 → app_user 해석 → (선택) empNo로 HR 스냅샷 조인(부서·직급 최신화) → 역할 조립 → 앱 JWT.
- **불일치 처리:** sub 있으나 empNo 없음(외부 SSO 사용자) 허용 / empNo 있으나 sub 없음(미로그인 직원) 허용(사전 프로비저닝) / 이메일 충돌 = CONFLICT(관리자 수동 링크).
---
## 5. 데이터 모델 (신설 — DA 정합, 소프트참조 표준)
> 신규 테이블만. **기존 테이블 변경 최소**(dept에 `source` 컬럼 순증만). 테넌트 표준(V31: tenant_id DEFAULT 'KINTEX' 복합 PK 선두)·소프트참조(FK 남발 금지, 애플리케이션 조인) 준수. 실제 DDL은 db-engineer 인계(§9).
| 테이블 | 목적 | 핵심 컬럼(개념) |
|---|---|---|
| `user_identity` | 3자 매핑 | (tenant_id, app_user_id) PK, idp_sub UNIQUE, emp_no, link_status, provider, linked_at |
| `hr_dept_snapshot` | HR 조직 캐시 | (tenant_id, emp_dept_code) PK, dept_name, parent_dept_code, sort_order, use_yn, revision, synced_at |
| `hr_emp_snapshot` | HR 직원 캐시 | (tenant_id, emp_no) PK, name, email, dept_code, position_code, employment_status, revision, synced_at |
| `hr_sync_log` | 배치 감사 | (tenant_id, id) PK, kind(DEPT/EMP), rows_upserted, result, degraded, started_at, finished_at |
| `dept`(순증) | 출처 구분 | `source varchar(10) DEFAULT 'LOCAL'`('HR'|'LOCAL') 컬럼 추가(멱등 ALTER) |
- **PII 경계:** hr_emp_snapshot는 name·email·dept·position·status만. 연락처·식별번호 미보관. email은 표시·매칭용(마스킹은 로그·감사 계층).
- **소프트참조:** emp_no·emp_dept_code·idp_sub는 **소프트 참조**(FK 미설정) — HR/IdP 외부 키를 물리 FK로 묶지 않음(배치 순서·정합 유연성). 공통코드(POSITION·EMPLOYMENT_STATUS)는 common_code 순증.
---
## 6. NFR 정합 (SA system.md §3)
| NFR | SSO/HR 반영 |
|---|---|
| **확장성** | 백엔드 무상태 유지(OIDC state/nonce는 Redis 외부화). Keycloak는 클러스터 가능. HR 배치는 백엔드와 분리 스케줄(응답성 무영향) |
| **가용성/HA** | **로컬 로그인 폴백**(IdP 장애)·**HR 스냅샷 폴백**(HR 장애) 이중 degraded 모드로 코어 기능 유지. Keycloak 최소 2노드 + DB HA |
| **성능** | JWKS 공개키 캐시(매 요청 IdP 미호출). 로그인만 IdP 왕복, 이후 앱 JWT 로컬 검증(현행 성능 무변경). HR은 배치 오프라인 |
| **보안영역** | Keycloak=내부 애플리케이션 존, `auth.` vhost만 노출. HR/AD=내부망 구간(인터넷 egress 무증가). 토큰·시크릿 env only |
| **용량** | user_identity·hr_*_snapshot는 직원 규모(수백~수천) 소량. hr_sync_log 보존정책(N개월) |
---
## 7. 보안 · 개인정보 (불변 준수)
- **온프레미스 판정:** Keycloak(자체 IdP)·HR API(고객 내부 인사시스템)는 내부망 통합 → **외부 인터넷 API 금지 규칙 비해당**. NA egress 화이트리스트에 인터넷 목적지 신규 추가 없음.
- **시크릿:** OIDC client_secret·HR API 자격증명·리프레시 토큰 = **env/시크릿 스토어 only**(systemd EnvironmentFile drop-in, `ADMIN_PASSWORD_ENC` 방식 준용). DB·코드·로그·커밋·API응답 미기록.
- **토큰 노출 금지:** id_token/access_token/refresh_token은 응답 본문·로그 미노출. 프론트에는 앱 JWT만(리프레시는 서버 보관).
- **감사:** 계정 링크/언링크·JIT 프로비저닝·HR 배치·권한 매핑 변경 = `TB_AUDIT_LOG` 전수. 로그인 성공/실패는 기존 `login_history`(이메일/IP 마스킹) 재사용.
- **PII 최소화:** HR 수집 필드 최소, 삭제권·재직상태 반영(RETIRED 소프트), 보존정책 DA 확정.
- **검증:** id_token 서명(JWKS)·iss·aud·exp·nonce, code 교환 시 code_verifier(PKCE), state(CSRF), back-channel logout token 검증 필수.
---
## 8. 이행 계획 (coexist → pilot → cutover → 롤백)
| 단계 | 범위 | 로컬 로그인 | 완료 기준(게이트) | 롤백 |
|---|---|---|---|---|
| **0. 준비** | Keycloak 배치(realm/클라이언트)·매핑 테이블·HrDirectoryClient(Mock)·백엔드 `/oidc/*` 엔드포인트(피처플래그 `sso.enabled=false`) | 전면 허용(현행) | staging OIDC 왕복·앱 JWT 브로커·회귀 0 | 플래그 off = 완전 현행 |
| **1. coexist** | SSO 로그인 **옵션** 노출(로그인 화면 "SSO로 로그인" 병행). JIT 프로비저닝·수동 링크 UI | 전면 허용 | 파일럿 계정 SSO 로그인·역할 정합·2FA 위임 검증 | SSO 버튼 숨김 |
| **2. pilot** | **1개 부서(내부 직원)** SSO 우선 + HR 배치 실연동(스냅샷→dept). 로컬은 폴백만 | 파일럿 외 허용, 파일럿은 폴백 | HR 스냅샷 정합·조직도 HR 출처·degraded 폴백 동작 | 파일럿 부서 로컬 복귀 |
| **3. cutover** | 전 내부 직원 SSO 필수(로컬은 관리자·비상만). HR 정본화(dept 읽기전용) | 관리자·비상만 | 전 직원 SSO·HR 정본·이중 2FA 없음·감사 완비 | IdP 장애 시 로컬 폴백 자동 |
| **4. 정착** | 로컬 비번 로그인 축소(SSO 전용 계정 비번 미발급). 리소스서버 모드 전환은 별도 과제(A3) | 최소(비상 관리자) | 운영 안정·SLO 충족 | — |
- **무중단 원칙:** 각 단계는 **피처플래그**로 제어, 언제든 이전 단계 복귀. 다운스트림(앱 JWT 소비)은 전 단계 불변 → 화면·API 회귀 0이 롤백 안전판.
- **관람객/외부(B2C):** SSO 이행 대상 아님 — 셀프서비스(간편가입·게스트) 트랙 유지. 본 이행은 **내부 직원·조직** 한정.
---
## 9. 인계 백로그 (트랙별)
> 본 문서는 설계 정본. 아래는 각 dev 트랙 착수 항목. **모두 피처플래그 뒤에서 순증 구현**(기존 인증코드 미파괴).
| 트랙 | 항목 | 산출 |
|---|---|---|
| **backend-dev** | ① OIDC RP: `/api/auth/oidc/authorize-info·callback·logout·backchannel-logout`, JWKS 캐시·id_token 검증 ② 콜백 성공 후 **기존 `JwtService.issue()` 재사용**한 앱 JWT 브로커 ③ `HrDirectoryClient` 인터페이스 + Mock 구현 + 고객 어댑터 스텁 ④ 매핑 해석·JIT 프로비저닝·수동 링크 서비스 | 신규 패키지 `auth/oidc`, `hr/` (기존 `auth`·`security` 불변) |
| **common-dev(인증 레이어)** | ① 로그인 화면 SSO 버튼(피처플래그)·expo-auth-session(모바일) ② `TwoFactorService.requiresOtp` IdP 위임 분기(설정형) ③ 계정 링크/언링크 마이페이지·관리자 링크 UI | 인증 공통 레이어 |
| **db-engineer** | ① `user_identity`·`hr_dept_snapshot`·`hr_emp_snapshot`·`hr_sync_log` DDL(V38+, 멱등·테넌트 표준·소프트참조) ② `dept.source` 순증 ALTER ③ common_code POSITION·EMPLOYMENT_STATUS 순증 | Flyway 마이그레이션 |
| **mobile** | expo-auth-session PKCE 플로우 + B2B 앱 SSO/IdP OTP, WISE 모바일 로그인 컨벤션 위 삽입, 디자인 Stitch 경유 | `mobile/` 로그인 |
| **devops** | ① Keycloak 배치(systemd/컨테이너·별도 DB·realm import) ② `auth.<domain>` nginx vhost·TLS·접근제한 ③ client_secret·HR 자격증명 env drop-in(시크릿 스토어) ④ HR 배치 스케줄 | 인프라(G2 연계) |
| **planner(인계)** | PLANNING §5B/§8에 **Open SSO·HR API 연동** 반영(6역할·인증 스택·조직 마스터 출처 갱신). 관람객 SSO 제외 명시 | PLANNING 개정 |
| **NA/DA(정합)** | NA: `auth.` vhost·IdP↔AD/HR 내부망 구간 존 반영 / DA: hr_*_snapshot·user_identity ERD·PII 보존정책 편입 | network.md·data.md 갱신 |
---
## 10. 리스크
| # | 리스크 | 완화 |
|---|---|---|
| R1 | IdP 단일 장애 → 전면 로그인 불가 | 로컬 로그인 폴백 유지(§2-6)·Keycloak HA·앱 JWT 수명으로 순간 장애 흡수 |
| R2 | 이메일 재사용·계정 병합 오류 → 권한 탈취 | sub↔empNo 확정 매핑, 이메일 단독 병합 금지, CONFLICT 수동 링크·감사 |
| R3 | HR API 스펙 상이·미제공 | `HrDirectoryClient` 어댑터로 격리, Mock·스냅샷 폴백으로 개발·운영 지속 |
| R4 | 이중 2FA(IdP+앱) 마찰 | IdP OTP 위임 시 앱 OTP 강제 해제(설정형 분기) |
| R5 | 행사 RBAC 클레임 누락(리소스서버 직접 신뢰 시) | 이행기 브로커 모드 고정(앱 JWT에 event_member 조립). 직접 신뢰는 정착 후 별도 과제 |
| R6 | HR 정본 전환 후 로컬 조직 편집 상실 | `dept.source=LOCAL` 공존 허용(외부 파트너 그룹핑 등 로컬 전용 유지) |
| R7 | 토큰/시크릿 노출 | env only·서버측 리프레시 보관·응답/로그 미노출·JWKS 검증 |
---
## 11. 변경 이력
| 버전 | 일자 | 작성자 | 내용 |
|---|---|---|---|
| v1.0 | 2026-07-12 | SA | 최초 작성 — Open SSO(OIDC/Keycloak, PKCE, 브로커드 앱JWT 공존, 로컬 폴백, 2FA 위임, 6역할/멀티테넌트 매핑, 웹+모바일) + 인사·조직 API 연동(HrDirectoryClient 어댑터·스냅샷 폴백·증분 동기화·PII 최소) + 3자 매핑(sub↔empNo↔app_user) + 데이터 모델·NFR·보안·이행(coexist→pilot→cutover→롤백)·인계 백로그·리스크. 기존 W12 인증(app_user·event_member·TotpService·JwtService) 미수정 공존 설계. system.md/app.md/network.md/data.md 교차참조 |

357
plugins/zio-harness/knowledge/kintex/docs/architecture/system.md Normal file
View File

@ -0,0 +1,357 @@
# 킨텍스 자동전시시스템 — 시스템 아키텍처 · 비기능요건(NFR)
> 산출: 시스템 아키텍트(SA) · 작성일: 2026-07-11 · 대상 백로그: `IMPLEMENTATION_BACKLOG.md` **A-2**
> 정합 근거: [`../PLANNING.md`](../PLANNING.md) v2.0 §2(6역할)·§7(데이터·연동)·§8(아키텍처)·§10(리스크) · [`../IMPLEMENTATION_BACKLOG.md`](../IMPLEMENTATION_BACKLOG.md) · [`../analysis/reroomai-source.md`](../analysis/reroomai-source.md)(나노바나나 워커)
> 확정 스택(불변): React 18/19(Vite·TS) + Spring Boot 3.x(Java 17)+MyBatis + PostgreSQL(PostGIS) + Redis + 나노바나나 Python 워커. — `../DEVELOPMENT_GUIDE.md` §1, `../PLANNING.md` §8
> **문서 소유권**: 본 문서는 SA(시스템 아키텍처·NFR·구성·배포 토폴로지)만 정본. 애플리케이션 경계/API 표준=AA([`app.md`](app.md), A-1), 기술 표준/빌드·관측성=TA([`tech.md`](tech.md), A-3), 전사 ERD/공간·마스터·BI마트=DA([`data.md`](data.md), A-4), DMZ/방화벽/부하분산=NA([`network.md`](network.md), A-5). 본 문서는 그 상위 시스템 관점만 다루며 세부는 각 문서로 위임(교차참조).
---
## 0. 선행 게이트 (SA 반영 — 착수 전 소유자 확인)
| 게이트 | 내용 | 시스템 아키텍처 영향 |
|---|---|---|
| **G1** | 나노바나나(Gemini `generativelanguage.googleapis.com`) 외부 호출 승인(PLANNING R12) | 미승인 시 나노바나나 워커는 **목(mock)/degraded 모드**로 기동(구조·큐·워터마크 계약은 유지, 실이미지 생성만 차단). 승인 시 워커 서비스에만 `GEMINI_API_KEY` env 주입(§6-4). **아웃바운드 방화벽 정책은 워커 서브넷 한정** — NA 확정 |
| **G2** | 배포 대상 서버·포트(GUARDiA 인프라와 **별개 도메인**) | 배포 토폴로지(§4)의 물리 매핑·도메인·포트·TLS는 G2 확정 후 Phase E에서 실체화. 본 문서는 **논리 토폴로지**를 확정하고 물리값은 플레이스홀더(`<kintex-domain>`) 처리 |
> 두 게이트는 **아키텍처 설계를 막지 않는다** — 논리 구성·NFR·용량 산정은 게이트와 무관하게 확정하고, 물리 실체화(실호출·실배포)만 게이트에 종속시킨다.
---
## 1. 시스템 개요
킨텍스 자동전시시스템은 전시 생애주기(판매·기획 → 설계·시각화 → 발주·계약 → 참가·관람 → 현장운영 → 사후·경영)를 하나의 데이터·계정 체계로 자동화하는 **베뉴 운영 플랫폼**이다. 시스템은 **6개 역할별 분리 프론트 + 단일 공유 Spring Boot 백엔드 + 나노바나나 Python 워커 사이드카**를 **SSO·역할 RBAC** 위에 얹고, **PostGIS 공간 데이터 · Redis 비동기 큐 · 오브젝트 스토리지**를 공유 자원으로 둔다.
**아키텍처 대원칙 (PLANNING §4·§8 정합)**
1. **단일 공간 데이터 모델** — 부스 폴리곤·트렌치 포인트·배선 LineString을 PostGIS 지오메트리로 일원화. 시각화(M5)·검증(M2)·정산(M9)·wayfinding(M13)·BI(M16)가 같은 원천을 재사용.
2. **이미지 생성 전면 비동기** — Spring이 RenderJob을 Redis 큐에 발행 → Python 워커가 소비·생성 → 오브젝트 스토리지 적재 → WebSocket 완료 푸시. 백엔드는 오케스트레이션·상태만, `GEMINI_API_KEY`는 워커 전유.
3. **역할별 프론트 분리** — 최소권한·공격면 축소. 공유 디자인 시스템·컴포넌트·API 계약을 상속(중복 구현 금지).
4. **룰셋은 코드가 아닌 버전 데이터** — 요율·규정을 버전 파일로 두어 킨텍스 연 단위 개정을 무중단 반영.
5. **공개 vs 내부 보안영역 분리** — 공개 홍보/관람객(비인증·쓰기제한)과 내부 백오피스(관리자·크로스테넌트)를 물리·논리로 격리.
---
## 2. 논리 아키텍처 (컴포넌트 구성도)
```mermaid
graph TB
subgraph EDGE["엣지 / 공개영역 (DMZ)"]
CDN[CDN · 정적 캐시<br/>공개 이미지·번들·플로어플랜]
WAF[WAF / Reverse Proxy · nginx<br/>TLS 종단·라우팅·레이트리밋]
end
subgraph FRONT["역할별 분리 프론트 (React·Vite·TS, 공유 디자인시스템)"]
FO[organizer. 주최자 콘솔]
FE[exhibitor. 참가업체 포털]
FC[contractor. 업체 포털·옥션]
FM[ops. 운영 대시보드]
FA[admin. 관리자 백오피스<br/>★내부 전용]
FP[www/expo. 공개 홍보 사이트<br/>SSR/SSG·SEO·다국어]
FV[관람객 모바일/웹<br/>배지·wayfinding·매칭]
end
subgraph GATE["SSO · 역할 RBAC · API 진입"]
SSO[JWT SSO + TOTP 2FA<br/>플랫폼·행사 이중 RBAC 평가]
end
subgraph BACKEND["공유 Spring Boot 3.x 백엔드 (Java 17·MyBatis)"]
API[REST + WebSocket/STOMP]
RULE[룰 엔진 · 요율/규정 버전셋]
LAYOUT[배치·배선 엔진 · PostGIS 공간 SQL]
AUC[옥션 엔진 M15 · 라운드·순위·낙찰스코어]
BI[BI 집계 M16 · KpiSnapshot]
CMS[CMS·다국어 M17]
PUBSVC[공개 API · 사전등록·조회 read-only]
end
subgraph ASYNC["비동기 처리"]
REDIS[(Redis<br/>작업 큐·순위·타이머·캐시·쿼터·세션)]
NBW[나노바나나 Python 워커<br/>tools/nanobanana · google-genai]
DOCW[서류·PDF·EDM 워커<br/>동일 큐 계약]
end
subgraph DATA["데이터 계층"]
PG[(PostgreSQL + PostGIS<br/>업무·공간 데이터)]
RPL[(읽기 복제본<br/>BI·공개조회 오프로드)]
OBJ[(오브젝트 스토리지<br/>도면·생성이미지·서식·콘텐츠)]
end
subgraph EXT["외부 시스템 / 게이트"]
GEM[Google Gemini<br/>나노바나나 · ★G1]
CLA[Anthropic Claude<br/>AiTextRouter · env only]
PGPAY[PG 결제 · 세금계산서]
KXWP[kxwp/kxfp 작업신고<br/>파일 릴레이]
CCPY[등록업체 DB 739]
EVT[행사일정 시스템]
end
CDN --> WAF
FP -.CDN 캐시.-> CDN
FO & FE & FC & FM & FA & FP & FV --> WAF --> SSO --> API
WAF -->|공개 read-only| PUBSVC
API --> RULE & LAYOUT & AUC & BI & CMS
API --> REDIS
REDIS --> NBW & DOCW
NBW --> OBJ
NBW -.WebSocket 완료푸시.-> API
NBW -.★G1.-> GEM
DOCW --> OBJ
API --> PG
BI --> RPL
PUBSVC --> RPL
API -.AiTextRouter.-> CLA
API --> PGPAY
API -.파일 릴레이.-> KXWP
API --- CCPY & EVT
PG -.복제.-> RPL
```
### 2-1. 컴포넌트 책임 (시스템 관점)
| 컴포넌트 | 실행 단위 | 책임 | 확장 방식 |
|---|---|---|---|
| **역할별 프론트 6종+공개** | nginx 정적 서빙(역할별 dist 번들) | organizer·exhibitor·contractor·ops·admin(내부)·public/visitor. SPA. 데스크톱=설계·에디터, 모바일=현장·조회·승인 | CDN + 정적 스케일(무상태) |
| **공개 홍보 사이트(M12·M17)** | SSR/SSG 렌더 경로 + CDN | SEO·다국어(한/영/중/일)·hreflang·사이트맵, 공개 플로어플랜(M2 부산물) | CDN 캐시·정적 재생성, 인증영역과 별도 |
| **공유 백엔드(Spring Boot jar)** | `java -jar`(systemd, N 인스턴스) | REST+WebSocket, 룰/배치/배선/옥션/BI/CMS 서비스, 큐 발행·상태·콜백 | **수평 확장(무상태)** — 세션·순위·타이머는 Redis 외부화 |
| **나노바나나 워커** | Python 데몬(systemd, M 인스턴스) | Redis 큐 소비 → Gemini image-to-image → 워터마크 후처리 → OBJ 적재 → WebSocket 콜백. 재시도·비용상한·스키마해시 캐시·쿼터(성공 시 차감) | **큐 깊이 기반 수평 확장**(GPU/비용 독립 스케일) |
| **서류·PDF·EDM 워커** | Python/Java 데몬(동일 큐 계약) | 서식(HWP/PDF)·견적서 PDF(M15)·EDM 발송 비동기 | 큐 깊이 기반 확장 |
| **Redis** | 관리형/전용 노드(HA) | 작업 큐, 옥션 실시간 순위·라운드 마감 타이머, 응답 캐시·스키마해시 캐시, RenderJob 쿼터, WebSocket 세션 상관 | Sentinel/Cluster(§3-2) |
| **PostgreSQL+PostGIS** | 프라이머리 + 읽기 복제 | 업무·공간 데이터 단일 진실원천(Flyway 스키마) | 프라이머리 수직 + 읽기 복제 수평(BI·공개조회 오프로드) |
| **오브젝트 스토리지** | S3 호환/파일 스토어 | 도면·생성이미지·서식·콘텐츠·마이크로사이트 자산 | 스토리지 독립 확장 + CDN 프론팅 |
> **AA 위임**: 모듈 경계·패키지·API 표준·응답 봉투는 [`app.md`](app.md). 본 표는 **배포 단위·확장 특성** 관점만.
---
## 3. 비기능요건(NFR)
> 정량 목표는 킨텍스 실측(홀당 200~600부스, 홀 10개, 대형 행사 수만 관람객)과 PLANNING §10 리스크(R6 이미지 비용·지연)를 근거로 산정. 값은 **초기 목표치**이며 파일럿(Phase 1) 실측으로 보정한다.
### 3-1. 확장성 (Scalability)
| 항목 | 설계 | 근거·목표 |
|---|---|---|
| **백엔드 수평 확장** | Spring 인스턴스 무상태화 — JWT(자족적)·세션 없음, 옥션 순위·타이머·쿼터·캐시는 **Redis 외부화**. WebSocket은 STOMP+Redis 브로커 릴레이(다중 인스턴스 팬아웃) | 인스턴스 N대 로드밸런싱, 무중단 스케일아웃 |
| **워커 독립 확장** | 나노바나나·서류·EDM 워커는 백엔드와 **분리 스케일** — 큐 깊이(대기 Job 수) 기반 인스턴스 증감 | 이미지 생성 피크(행사 오픈 전 대량 컨펌)를 백엔드 응답성과 무관하게 흡수 |
| **읽기 부하 오프로드** | BI 집계·공개사이트 조회·플로어플랜 열람은 **읽기 복제본** 라우팅. 운영 프라이머리는 쓰기 트랜잭션 보호 | BI(M16) 무거운 집계가 운영 DB를 압박하지 않음(PLANNING §8-1) |
| **공개 트래픽 흡수** | 공개 홍보 사이트·공개 플로어플랜·이미지는 **CDN·SSG 캐시**로 오리진 오프로드. 사전등록만 오리진 write | 관람객 트래픽 급증(행사 D-데이) 시 오리진 보호 |
| **데이터 파티셔닝 여지** | 행사(Event) 단위 격리(§5) → 대량 데이터(리드·체크인·RenderJob)는 행사·기간 파티션 가능(DA 후속) | 다년·다행사 누적 확장 |
| **멀티테넌시** | 행사 단위 워크스페이스 + 플랫폼 RBAC. 신규 행사는 데이터·권한만 추가(코드·인프라 불변) | 무제한 행사 온보딩 |
### 3-2. 가용성 · HA (Availability)
| 계층 | HA 설계 | 목표 |
|---|---|---|
| **프론트/공개** | 정적 번들 CDN 다중 엣지 + nginx 다중화 | 단일 노드 장애 무영향 |
| **백엔드** | 최소 2 인스턴스 + 헬스체크(`GET /health`) 로드밸런싱. 롤링 배포(무중단) | 무중단 배포·인스턴스 장애 격리 |
| **Redis** | Sentinel(자동 failover) 또는 Cluster. 큐 손실 방지 위해 **AOF 지속화** + 소비자 ACK/재큐 | 프라이머리 다운 시 자동 승격, 진행 중 Job 유실 0 |
| **PostgreSQL** | 프라이머리-스탠바이 스트리밍 복제 + 자동 failover(Patroni/관리형). PITR 백업 | RPO 최소·RTO 분 단위 |
| **워커** | 무상태 소비자 N대. 처리 중 죽으면 **가시성 타임아웃 후 재큐**(멱등 Job) | 워커 장애가 사용자 응답 차단 안 함(비동기) |
| **오브젝트 스토리지** | 복제·버전 관리 스토리지 | 자산 내구성 보장 |
| **Fail-Safe 배포** | 백업 → 배포 → 헬스체크(200) → 실패 시 롤백(이전 jar 유지). clean bootJar 검증 후 교체 | 깨진 배포가 서비스 중단 유발 안 함(`../BUILD_DEPLOY.md`) |
| **degraded 모드** | G1 미승인/Gemini 장애 시 워커 목 응답(구조·워터마크 유지). Claude 실패 시 Ollama 폴백(AiTextRouter). PG 복제 지연 시 프라이머리 폴백 | 외부 의존 장애 시에도 코어 기능 유지 |
> **HA 목표 SLO(초기)**: 코어 인증·설계·조회 경로 **99.5%**(행사 성수기 99.9% 지향). 나노바나나 생성은 **best-effort 비동기**(SLA 대상 아님, 큐 소진 목표만). — 구체 SLO/알림 임계는 TA 관측성([`tech.md`](tech.md))과 연계.
### 3-3. 성능 (Performance)
**(a) 대량 부스 · 공간 연산**
| 시나리오 | 부하 특성 | 설계 대응 | 목표 |
|---|---|---|---|
| 플로어플랜 3안 생성(M2) | 홀당 200~600부스 제약 솔버 | 결정적 솔버(비-LLM) + 서비스 계층 연산, LLM은 조건 해석만. 무거운 생성은 필요 시 비동기화 | 3안 생성 수 분 내(PLANNING 목표) |
| 규정 검증·최단 배선(M2/M4) | PostGIS 버퍼·거리·KNN(`<->`) 연산 | 공간 인덱스(GiST) + 매퍼 XML `ST_*` 최적화. 홀 단위 스코프 쿼리 | 배치·배선 상호작용 P95 < 2s |
| 부스 목록·조회 | 대형 행사 수천 부스 그리드 | 페이지네이션(PageResponse) + 읽기 복제 + 캐시 | 목록 P95 < 500ms |
**(b) 이미지 생성 큐 (나노바나나)**
| 항목 | 산정 | 설계 |
|---|---|---|
| 생성 지연 | 단건 평균 ~40s(design 배지), Gemini 왕복 의존 | **전면 비동기** — 사용자는 진행 배지·WebSocket 완료 푸시 수신. 동기 대기 없음 |
| 대량 동시 요청 | 홀당 200~600부스 × S1·S7 자동(PLANNING R6) | **자동 생성은 S1·S7 한정**, 나머지 온디맨드. **동일 스키마해시 캐시**로 재생성 회피. 행사별 **RenderJob 쿼터**(성공 시에만 차감) |
| 처리량 스케일 | 워커 M대 병렬, 큐 깊이 기반 증감 | 피크 시 워커 스케일아웃으로 큐 소진 시간 제어. Gemini 쿼터·비용 상한은 워커 레벨 관리 |
| 전처리 절감 | 도면/현장사진 클라이언트 Canvas **긴 쪽 1024px 다운스케일 + JPEG 0.85**(ReRoomAI 실증) | 전송량·모델 비용·지연 동시 절감 |
| S6 배선 오버레이 | 좌표 정확성 목적 | **백엔드 래스터 합성 우선**(Gemini 미경유 결정적 산출) — 생성 비용·지연에서 제외 |
**(c) 공개사이트 트래픽**
| 항목 | 설계 | 목표 |
|---|---|---|
| 공개 홍보/플로어플랜 | SSR/SSG + CDN 캐시, 오리진 캐시 미스만 read-replica | 캐시 히트 P95 < 200ms, 트래픽 스파이크 CDN 흡수 |
| 사전등록 write | 오리진 write(멱등·중복 등록 가드) + 큐잉 완충(배지 발급 비동기) | 등록 급증 시 write 완충 |
| 실시간 옥션 순위(M15) | Redis 정렬셋 순위 + WebSocket 델타 푸시, 라운드 마감 타이머 | 순위 갱신 < 1s, 다중 인스턴스 팬아웃 |
### 3-4. 용량 산정 (Capacity — 초기 근사)
> 단일 대형 행사 기준. 킨텍스 대형 홀(홀7/8 각 510부스, 홀9/10 ~600부스), 대형 행사 관람객 수만 명 가정. **Phase 1 파일럿 실측으로 교정**.
| 자원 | 산정 기준 | 초기 용량 |
|---|---|---|
| **부스 데이터** | 대형 행사 3,000~5,000부스 × (폴리곤 + DesignPlan 버전 + UtilityOrder 배선) | 행사당 수만 지오메트리 레코드 — GiST 인덱스 필수 |
| **RenderJob/이미지** | 부스 3,000 × 자동 2샷(S1·S7) + 온디맨드 α, 이미지 평균 0.5~2MB(1024px) | 행사당 ~수천~1만 이미지, 수 GB~수십 GB → OBJ + CDN. 캐시로 재생성 억제 |
| **리드·체크인(M10)** | 관람객 수만 × 체크인 이벤트 + 참가업체 리드캡처 | 행사당 수만~수십만 이벤트 로우 → 파티셔닝 후보(개인정보 §5) |
| **동시 사용자** | 설계 피크(주최자·업체) 수백 + 공개/관람객 수천~수만(D-데이) | 인증영역 수백 동시(백엔드 N대) / 공개영역 CDN 흡수 |
| **Redis** | 큐 대기 Job + 옥션 순위셋 + 캐시 + 쿼터 카운터 | 수 GB. 큐 백로그 상한·모니터링 |
| **DB 연결풀** | 공유 백엔드 다인스턴스 × Hikari 풀 | **Hikari max 제한 + PgBouncer 권고**(GUARDiA 실측 교훈: 공유 PG `max_connections` 포화 방지). 인스턴스 수 × 풀 ≤ PG 상한 |
| **오브젝트 스토리지** | 도면 + 이미지 + 서식 + 콘텐츠, 다년 누적 | 행사당 수십 GB, 보존정책(§5-3) 기반 아카이빙 |
---
## 4. 배포 토폴로지
> **논리 토폴로지 확정**. 물리 서버·도메인·포트·TLS는 **G2 확정 후 Phase E**(`E-DEP`, `kintex-devops-dev`)에서 실체화. DMZ/방화벽/부하분산 세부는 NA([`network.md`](network.md)).
### 4-1. 배포 존(Zone) 구성
```mermaid
graph TB
subgraph PUBZ["공개 존 (DMZ / 인터넷 노출)"]
LB1[Reverse Proxy / WAF · nginx · TLS]
CDNZ[CDN 엣지]
PUBFE[공개 프론트 · SSR/SSG 정적]
end
subgraph APPZ["애플리케이션 존 (내부망)"]
APPFE[인증 프론트 정적 서빙<br/>organizer·exhibitor·contractor·ops]
APPBE[공유 백엔드 jar × N · systemd]
WKZ[워커 데몬 × M · systemd<br/>나노바나나 · 서류/EDM]
end
subgraph MGMTZ["관리 존 (내부 전용 · 접근 제한)"]
ADMFE[admin. 백오피스 프론트]
end
subgraph DATAZ["데이터 존 (내부, 최심부)"]
PGZ[(PostgreSQL+PostGIS<br/>프라이머리+스탠바이)]
RPLZ[(읽기 복제본)]
REDISZ[(Redis HA)]
OBJZ[(오브젝트 스토리지)]
end
subgraph EGRESS["아웃바운드 게이트 (워커/백엔드 한정)"]
OUT[허용 아웃바운드<br/>Gemini(G1)·Claude·PG결제·kxwp]
end
CDNZ --> PUBFE
LB1 --> PUBFE & APPFE & ADMFE
APPFE & ADMFE --> APPBE
APPBE --> PGZ & REDISZ & RPLZ & OBJZ
WKZ --> REDISZ & OBJZ
WKZ --> OUT
APPBE --> OUT
PGZ -.복제.-> RPLZ
```
### 4-2. 배포 단위(산출물) — `../BUILD_DEPLOY.md` §1 정합
| 단위 | 빌드 | 산출물 | 실행 | 배포 존 |
|---|---|---|---|---|
| 인증 프론트 6종 | `vite build`(역할별 번들) | `dist/`(organizer·exhibitor·contractor·ops·admin) | nginx 정적(SPA 폴백) | APP존(admin은 MGMT존) |
| 공개 프론트 | SSR/SSG 빌드 | 정적/렌더 번들 | CDN + 엣지 렌더 | 공개존 |
| 공유 백엔드 | `./gradlew bootJar`(JDK17) | `kintex-*.jar` | `java -jar` systemd × N | APP존 |
| 나노바나나 워커 | (빌드 없음) | `tools/nanobanana` | 큐 소비 데몬 systemd × M | APP존(아웃바운드 게이트) |
| 서류/EDM 워커 | — | 워커 모듈 | 큐 소비 데몬 | APP존 |
- **배포 흐름**(GUARDiA 표준 준용): `workspace/kintex` → git push → Gitea(`zio/kintex`) → webhook → deploy_server → 빌드(`bootJar`·`vite build`) → Flyway 마이그 → jar 재기동·dist 배포 → 헬스 게이트(`GET /health` 200) → 실패 시 롤백.
- **systemd 유닛**: 백엔드 jar · 워커 데몬 각각 유닛(부팅 자동기동·재시작). AI env drop-in(`ANTHROPIC_API_KEY`·`ADMIN_PASSWORD_ENC`)은 표준 프레임워크 §7 방식. **`GEMINI_API_KEY`는 나노바나나 워커 유닛에만** 주입(백엔드·프론트 미취급).
- **nginx vhost**: `<kintex-domain>` → `/`=프론트 정적, `/api/`·`/ws`=백엔드 포트. 관리자 백오피스(admin.)는 **별도 vhost + 접근 제한**(§5-1). TLS certbot. — 도메인·포트=G2.
- **환경 분리**: dev / staging / prod. staging에서 헬스·마이그·경계면 검증 후 prod 승격(운영 배포는 소유자 승인 필수).
> CI/CD 파이프라인 상세(deploy_server·롤백·webhook)는 **Phase E `kintex-devops-dev`** 정본. TA([`tech.md`](tech.md))의 빌드·관측성 표준과 연계.
---
## 5. 보안영역 · 데이터 보존 · 개인정보 경계
### 5-1. 보안영역 분리 (공개 vs 내부 백오피스)
| 영역 | 대상 | 노출 | 인증 | 격리 |
|---|---|---|---|---|
| **공개 영역** | www/expo 홍보사이트, 공개 플로어플랜, 사전등록, 관람객 앱 | 인터넷(DMZ) | 비인증 또는 셀프서비스(쓰기 제한) | 별도 렌더 경로·read-only API·행사 데이터 write 불가 |
| **인증 업무 영역** | organizer·exhibitor·contractor·ops | 인증 후 접근 | JWT SSO + TOTP 2FA + 행사 RBAC | 행사 단위 데이터 격리(§5-2) |
| **관리 영역(백오피스)** | admin. — 사용자·RBAC·마스터데이터·룰셋·감사로그·크로스테넌트 | **내부 전용**(웹 전용, 모바일 미제공) | ADMIN 역할 + 2FA 필수 + **접근 제한**(내부망/허용 IP — NA 확정) | 별도 vhost·존, 공개영역과 물리·논리 분리 |
- **최소권한·공격면 축소**: 6개 프론트 번들 분리로 역할별 코드·권한 최소화. 백오피스는 공개 인터넷에 노출하지 않는다.
- **이중 RBAC 평가**: 플랫폼 레벨(관리자)과 행사 레벨(주최자/참가/업체/홀매니저)을 JWT 클레임(`roles` eventId→역할, `hm` 홀매니저)으로 이중 평가. `/api/admin/**`·`/api/system/**` = `hasRole(ADMIN)`(PLANNING §5B-1, `../DEVELOPMENT_GUIDE.md` §4).
- **인증 스택(UIWS 표준 이식)**: JWT(HS256) + TOTP(RFC6238 SHA1·30s·6자리·±1) 2차 인증 + 로그인 실패 잠금 + admin 비번 env(`ADMIN_PASSWORD_ENC` AES-256-GCM + 별도 키파일 재시드, `admin123` 하드코딩 금지). 대상: 관리자·홀매니저·주최자·업체(내부/발주 권한) 2FA 필수, 관람객 셀프서비스 선택.
### 5-2. 데이터 격리 (행사 단위 · 영업비밀)
- **행사(Event) 단위 워크스페이스**: 부스 설계는 경쟁사에 민감(PLANNING R10). 부스 데이터 접근은 **소유 참가업체 + 주최자 + 홀매니저**로 한정. 모든 도메인 경로는 `{eventId}` 스코프 + RBAC 가드.
- **옥션(M15) 자료 격리**: AI 설계자료(M2~M5)는 옥션 초대된 **킨텍스 등록업체(M7 검증 통과)**만 열람. 미등록 업체 응찰 원천 차단(`NOT_REGISTERED_COMPANY` 403).
- **BI 관점 격리**: 참가업체 관점 ROI(자기 부스)와 운영사 관점 수익성(전 행사)은 **별도 대시보드·권한**으로 격리(PLANNING M16-1).
### 5-3. 개인정보 경계 · 데이터 보존
| 데이터 | 개인정보 등급 | 처리 원칙 | 보존 |
|---|---|---|---|
| 관람객 등록·배지·체크인·리드(M10) | **개인정보(PLANNING R10)** | 수집 시 **동의** 필수. 리드 접근은 감사로그(`TB_AUDIT_LOG`) 전수 기록. 참가업체는 자기 리드만 | **보존정책 명시**(행사 후 N개월, 동의 철회·삭제권 지원 — DA 확정) |
| 부스 설계·도면·생성이미지 | 참가업체 자산·영업비밀 | 행사 단위 격리, 응답에서 내부 식별자·해시 shape 제외 | **행사 종료 후 보존 정책 별도**(참가업체 자산, PLANNING §8) |
| 결제·정산(M9) | 금융·과세 정보 | PG 위임(카드정보 비보관), 세금계산서 연동 | 법정 보존 기간 준수 |
| 자격증명·비밀·API키 | 최고 민감 | **응답·로그·에러·커밋에 절대 노출 금지**. `GEMINI_API_KEY`·`ANTHROPIC_API_KEY`·OTP 시크릿·비번 해시 미노출. AES-256-GCM 저장, 비번 BCrypt | env only, DB·코드 미기록 |
| AI 생성 이미지 | 오인 위험(R1) | **워터마크 강제**("AI 생성 예상 이미지…") + 메타데이터. 계약·심사 서류 자동 배제. 제거 불가 | 캐시·스키마해시 관리 |
- **보안 불변(위반=QA 반려)**: 스택트레이스 차단(`GlobalExceptionHandler`·`DataAccessException` 핸들러), 민감필드 응답 제외, AI 워터마크 항상 포함, 등록업체 응찰 가드, admin env 시드. — `../DEVELOPMENT_GUIDE.md` §5 계약.
- **감사 추적**: 승인·낙찰(M15)·설계 변경·룰셋 개정·리드 접근(개인정보) 전수 `TB_AUDIT_LOG` 기록(PLANNING §5B-1).
---
## 6. 연동 아키텍처
### 6-1. SSO · 역할 RBAC (6역할)
- **단일 JWT SSO** 위에 플랫폼 레벨 + 행사 레벨 권한 이중 평가. 6역할: 주최자·참가업체·장치/공사업체·킨텍스 직원(홀매니저·운영)·관리자·관람객/일반대중.
- 역할별 프론트는 동일 SSO·API 계약을 상속하되 **번들·도메인 분리**. 백오피스(admin.)는 내부 전용·2FA 필수(§5-1).
- 등록업체 계정은 **M7 등록업체 DB 검증** 통과분만 초대·옥션 응찰. 관람객·일반대중은 셀프서비스(쓰기 제한).
- 인증 상세 계약은 [`app.md`](app.md)(AA)·`../DEVELOPMENT_GUIDE.md` §4.
- **Open SSO(OIDC/Keycloak) 도입 + 인사·조직 API 연동**은 별도 정본 [`sso-hr-integration.md`](sso-hr-integration.md)(SA) — 기존 JWT+2FA를 삭제 없이 **공존(SSO 1차 인증→앱 JWT 브로커, 로컬 폴백)**, 직원·조직은 `HrDirectoryClient` 어댑터로 조달(로컬 스냅샷 폴백). 관람객/외부는 SSO 제외(셀프서비스 유지).
### 6-2. 외부 게이트 (아웃바운드 통제)
| 연동 | 경로 | 통제 | 게이트 |
|---|---|---|---|
| **나노바나나(Gemini)** | 나노바나나 **워커 전용** 아웃바운드 → `generativelanguage.googleapis.com` | `GEMINI_API_KEY` 워커 env only. 워커 서브넷만 아웃바운드 허용(NA). 미승인 시 목/degraded | **G1** |
| **Claude(텍스트 AI)** | 백엔드 `AiTextRouter` → `api.anthropic.com` | `ANTHROPIC_API_KEY` env only(코드·DB·로그·응답 미기록). **실패 시 Ollama 폴백** | 승인됨(예외) |
| **PG 결제(M9)** | 백엔드 → 국내 PG(카드·계좌·세금계산서) | 카드정보 비보관(PG 위임), 결제 콜백 검증 | — |
| **kxwp/kxfp 작업신고(M6)** | **파일 릴레이**(제출용 파일 생성 + 업로드 안내) | 폐쇄형·API 미공개(R3). 초기 수동 릴레이, 정식 API는 킨텍스 협의(Phase 3) | — |
| **등록업체 DB(739)** | 주기 수집 → 자체 DB화 | 공개 데이터 수집, 추후 공식 피드 | — |
| **행사일정 시스템** | 공개 캘린더 수집 → 가용성 역산 | 정확 가용성은 킨텍스 내부 데이터 협의 | — |
| **CDN** | 공개 자산·이미지 프론팅 | 공개 read-only 자산만 | — |
- **아웃바운드 원칙**: 인터넷 아웃바운드는 **워커·백엔드 특정 경로만 허용**(화이트리스트). 그 외 외부 API 금지(GUARDiA 보안 제약, `../DEVELOPMENT_GUIDE.md` §5). 세부 방화벽 규칙은 NA([`network.md`](network.md)).
### 6-3. 비동기 큐 계약 (Redis)
- Spring 백엔드는 RenderJob·서류·EDM·알림을 **Redis 큐에 발행**하고 상태만 관리. 워커가 소비·처리·완료 콜백(WebSocket). **Java 재구현 대신 얇은 큐 계약으로 결합**(PLANNING §8, google-genai는 Python SDK → 워커 유지).
- 큐 신뢰성: AOF 지속화 + 소비자 ACK + 가시성 타임아웃 재큐(멱등 Job). 쿼터·순위·타이머·캐시도 Redis(§2-1).
---
## 7. 아키텍처 결정 요약 (ADR-lite)
| # | 결정 | 이유 | 대안·트레이드오프 |
|---|---|---|---|
| 1 | 나노바나나를 **Python 워커 사이드카**로 분리 | google-genai=Python SDK, ReRoomAI 검증 방어로직 이식(Java 재구현 회피). 이미지 생성 독립 스케일 | Java 통합(재검증 비용·강결합) 배제 |
| 2 | **역할별 프론트 번들 분리** | 최소권한·공격면 축소, 공개/백오피스 격리 | 단일 SPA(권한 혼재·공격면 확대) 배제. 공유 디자인/API로 중복 완화 |
| 3 | 백엔드 **무상태 + Redis 외부화** | 수평 확장·무중단 배포·다중 인스턴스 WebSocket 팬아웃 | 인메모리 상태(ReRoomAI Map 방식) — 재시작·다중인스턴스 취약(§reroomai (F)) 배제 |
| 4 | **읽기 복제 오프로드**(BI·공개조회) | 운영 프라이머리 보호(PLANNING §8-1) | 단일 DB 직조회(BI 부하 전파) 배제 |
| 5 | **CDN + SSG**로 공개 트래픽 흡수 | 관람객 스파이크·SEO·다국어 | 오리진 직서빙(스파이크 취약) 배제 |
| 6 | 룰셋 **버전 데이터** 분리 | 연 단위 요율·규정 개정 무중단 반영 | 코드 하드코딩(배포 필요) 배제 |
| 7 | S6 배선 오버레이 **백엔드 래스터 우선** | 좌표 정확성(생성 왜곡 배제)·비용/지연 제외 | Gemini 생성(재질·색 왜곡) 배제 |
---
## 8. 교차참조
- 기획 정본: [`../PLANNING.md`](../PLANNING.md) §2·§7·§8·§10
- 구현 백로그: [`../IMPLEMENTATION_BACKLOG.md`](../IMPLEMENTATION_BACKLOG.md) Phase A~E
- **Open SSO · 인사(조직) API 연동(SA)**: [`sso-hr-integration.md`](sso-hr-integration.md) — OIDC/Keycloak·HrDirectoryClient·3자 매핑·이행(coexist→cutover)
- 나노바나나 파이프라인 근거: [`../analysis/reroomai-source.md`](../analysis/reroomai-source.md)
- 애플리케이션 아키텍처(AA·A-1): [`app.md`](app.md) — 모듈 경계·API 표준·패키지
- 기술 표준(TA·A-3): [`tech.md`](tech.md) — 빌드·배포·관측성·AiTextRouter
- 데이터 아키텍처(DA·A-4): [`data.md`](data.md) — 전사 ERD·공간·마스터·BI 마트
- 네트워크 아키텍처(NA·A-5): [`network.md`](network.md) — DMZ/방화벽/부하분산/아웃바운드
- 개발 표준: [`../DEVELOPMENT_GUIDE.md`](../DEVELOPMENT_GUIDE.md) · 빌드/배포: [`../BUILD_DEPLOY.md`](../BUILD_DEPLOY.md)
---
## 9. 변경 이력
| 버전 | 일자 | 작성자 | 내용 |
|---|---|---|---|
| v1.0 | 2026-07-11 | SA | 최초 작성(A-2) — 시스템 구성도(역할별 프론트·공유 백엔드·백오피스·공개사이트·나노바나나 워커·Redis·PostGIS), 논리/배포 토폴로지, NFR(확장성·HA·성능(대량부스·이미지큐·공개트래픽)·용량 산정), 연동 아키텍처(SSO/RBAC 6역할·PG결제·kxwp 릴레이·외부 게이트 Claude/Gemini), 보안영역(공개 vs 백오피스)·데이터 보존·개인정보 경계, G1/G2 게이트, ADR-lite. PLANNING §8 정합·확정 스택 준수. AA/TA/DA/NA 교차참조 |

324
plugins/zio-harness/knowledge/kintex/docs/architecture/tech.md Normal file
View File

@ -0,0 +1,324 @@
# 킨텍스 자동전시시스템 — 기술 표준 (Technical Architecture)
> 작성: 기술 아키텍트(TA) · 작성일: 2026-07-11 · 버전: v1.0
> 근거: `docs/PLANNING.md` v2.0(§8 확정 스택·§8-1 아키텍처 보강·§10 리스크)·`docs/IMPLEMENTATION_BACKLOG.md`(A-3)·실측 스캐폴드(`src/backend/build.gradle`·`src/backend/src/main/resources/application.yml`·`src/frontend/package.json`·`tools/nanobanana/`)·`.claude/agents/kintex-ai-dev.md`
> 교차참조: 앱 아키텍처 `docs/architecture/app.md`(A-1) · 시스템/NFR `docs/architecture/system.md`(A-2) · 데이터 `docs/architecture/data.md`(A-4) · 네트워크 `docs/architecture/network.md`(A-5)
> **문서 소유권**: 본 tech.md는 TA만 수정한다. 확정 스택·버전·빌드/배포·개발표준·관측성·AI 프로바이더 표준의 단일 출처(SSOT)다. 스택 변경은 본 문서 개정을 선행한다.
---
## 0. 이 문서의 위치
Phase A(아키텍처·거버넌스) 4개 표준 문서 중 **기술 표준(A-3)** 이다. 애플리케이션 경계·레이어(app.md), NFR·토폴로지(system.md), 데이터 모델(data.md), 네트워크(network.md)와 정합한다. 본 문서는 "무엇을 어떤 버전으로, 어떻게 빌드·배포·개발·관측하는가"의 기술 규범을 확정한다. 기능 범위·모듈 우선순위는 PLANNING이 권위이며 본 문서는 그 위 기술 계층만 다룬다.
핵심 원칙 4가지:
1. **실측 스캐폴드 정합** — 이미 스캐폴드된 실제 스택(Spring Boot 3.2.5·React 18.3.1·google-genai 워커)에 표기를 맞춘다. "3.x" 같은 느슨한 표기 대신 핀 버전을 SSOT로 둔다.
2. **GUARDiA/UIWS 표준 정렬** — kintex는 `zio/kintex` 독립 저장소이나 GUARDiA 표준 프레임워크(UIWS)와 스택·인증·AI 프로바이더 패턴을 공유한다.
3. **보안 불변 우선** — 시크릿 env-only, 스택트레이스·자격증명·PII 미노출, AES-256-GCM은 코드보다 상위 제약(§10, PLANNING §10·보안 불변).
4. **결정론과 폐쇄망 우선** — 규정/요율은 버전 관리 데이터, AI는 온프레미스 폴백 필수, 외부 아웃바운드는 승인된 도메인만.
---
## 1. 확정 기술 스택 (버전 표준·SSOT)
> 아래 버전은 **실측 스캐폴드에서 채택된 값**이다. 임의 상향/하향 금지 — 변경은 TA 승인 + 본 표 개정 후.
### 1-1. 백엔드 (Spring Boot · Java 17 · MyBatis)
`src/backend/build.gradle` 기준.
| 항목 | 표준 값 | 근거/비고 |
|---|---|---|
| 언어/런타임 | **Java 17** (`sourceCompatibility`/`targetCompatibility` = 17) | GUARDiA 표준(전 솔루션 Java 17 정렬). Java 21 금지 |
| 프레임워크 | **Spring Boot 3.2.5** | 핀 버전. `org.springframework.boot` 플러그인 |
| 의존성 관리 | `io.spring.dependency-management` **1.1.4** | Spring Boot BOM 정렬 |
| 빌드 도구 | **Gradle** (wrapper 동봉 `gradlew`/`gradlew.bat`) | 시스템 Gradle 미의존, wrapper 고정 |
| 그룹/패키지 | `com.zioinfo.kintex` / rootProject `kintex-backend` | GUARDiA 네이밍 규약 |
| 버전 | `0.1.0-SNAPSHOT` | SemVer, 릴리스 시 `-SNAPSHOT` 제거 |
| ORM | **MyBatis** `mybatis-spring-boot-starter` **3.0.3** | Spring Boot 3.2.x 호환 핀. JPA 금지(공간 SQL은 매퍼 XML) |
| DB 드라이버 | `org.postgresql:postgresql` (runtimeOnly, BOM 관리) | PostGIS 함수는 `ST_*` 매퍼 XML |
| 캐시/큐 | `spring-boot-starter-data-redis` | RenderJob·서류·알림 큐 + 옥션 실시간 순위 |
| 실시간 | `spring-boot-starter-websocket` (STOMP) | RenderJob 완료·옥션 순위 푸시 |
| 인증 | `spring-boot-starter-security` + **jjwt 0.12.5** (api/impl/jackson) | JWT HS256 + RBAC + TOTP 2FA |
| 검증 | `spring-boot-starter-validation` | DTO Bean Validation |
| 보일러플레이트 | Lombok (compileOnly + annotationProcessor) | |
| 테스트 | `spring-boot-starter-test` + `spring-security-test`, JUnit Platform | |
| 인코딩 | **UTF-8 강제** (`JavaCompile.options.encoding = 'UTF-8'`) | Windows javac CP949 한글 리터럴 손상 방지 — **불변, 전 모듈 유지** |
**MyBatis 규약**(application.yml 기준):
- `mapper-locations: classpath*:mybatis/mapper/**/*.xml`
- `map-underscore-to-camel-case: true`, `jdbc-type-for-null: NULL`
- `@MapperScan`은 GUARDiA 표준(`annotationClass = Mapper.class`) — 빈 누락 크래시 방지(다른 솔루션 회귀 이력). db-engineer가 공간 SQL 매퍼 XML 소유.
**Hikari 풀 표준**: `maximum-pool-size = ${DB_POOL_MAX:3}`. 공유 PostgreSQL 보호(GUARDiA 표준). kintex 전용 DB `kintex_db`라도 서버 공용 PG면 캡 유지. 상향 필요 시 SA(system.md)·DA와 합의.
### 1-2. 프론트엔드 (React · Vite · TypeScript)
`src/frontend/package.json`·`vite.config.ts`·`tsconfig.json` 기준.
| 항목 | 표준 값 | 비고 |
|---|---|---|
| UI 라이브러리 | **React 18.3.1** (`react`/`react-dom`) | PLANNING "18/19" 중 **18.3.1 확정 채택** |
| 빌드/번들러 | **Vite 5.4.8** + `@vitejs/plugin-react` 4.3.2 | dev 서버 :5173, `/api`·`/ws` 프록시 |
| 언어 | **TypeScript 5.6.2** (`strict: true`) | `noUnusedLocals`/`noUnusedParameters`/`noFallthroughCasesInSwitch` 켬 |
| 라우팅 | `react-router-dom` **6.26.2** | 역할별 포털 라우팅 |
| 서버 상태 | `@tanstack/react-query` **5.59.0** | API 캐싱·재검증 표준. 수동 fetch 지양 |
| 클라이언트 상태 | `zustand` **4.5.5** | 전역 상태(경량). Redux 금지 |
| 실시간 | `@stomp/stompjs` **7.0.0** + `sockjs-client` **1.6.1** | 백엔드 STOMP 정합 |
| 경로 별칭 | `@/*` → `src/*` (vite alias + tsconfig paths) | 상대경로 지옥 회피 |
| 모듈 타입 | `"type": "module"` (ESM), `target ES2020` | |
**빌드 스크립트**(package.json): `build = "tsc -b && vite build"`, `typecheck/lint = "tsc --noEmit"`. **타입 에러는 빌드 실패** — CI 게이트.
**역할별 프론트 분리**(PLANNING §2-1·§8-1): organizer·exhibitor·contractor·ops·admin(인증) + public/visitor(공개). **번들 분리** 방식은 designer/FE 트랙 결정(모노레포 다중 진입점 vs 서브패스). 공유 디자인 시스템(design.md)·공유 컴포넌트·공유 API 계약은 **상속**(중복 구현 금지). 현재 스캐폴드는 단일 Vite 앱(`src/frontend`) — 분리 실행 시 본 표준의 라이브러리 버전을 전 번들이 공유한다.
### 1-3. 나노바나나 Python 워커 (사이드카)
`tools/nanobanana/` 기준. PLANNING §8 "Python 워커 유지 근거"(google-genai는 Python SDK, ReRoomAI 검증 client.py 재사용 — Java 재구현 회피).
| 항목 | 표준 값 | 비고 |
|---|---|---|
| 런타임 | **Python 3.11+** (개발 실측 3.14 `__pycache__`) | 배포는 3.11/3.12 LTS 권장(3.14는 개발 로컬) |
| 이미지 SDK | **google-genai** (`pip install google-genai`) | Gemini image-to-image. 지연 임포트(무네트워크 import 성립) |
| 모델 | `gemini-3.1-flash-image-preview` (나노바나나 2, env `NANOBANANA_MODEL`) | 하드코딩 아님, env 오버라이드 |
| 이미지 처리 | **Pillow(PIL)** | S6 배선 오버레이 결정적 래스터 합성·목 플레이스홀더 |
| 큐/이벤트 | **redis** (`redis.from_url`, BLPOP 소비 + pub/sub 발행) | 지연 연결 |
| 실행 | `python -m tools.nanobanana.worker` (루프) / `--smoke` (무네트워크) | |
**워커 불변식**(worker.py 헤더): ①G1 게이트 — 실 Gemini 호출은 `NANOBANANA_LIVE=1` + `GEMINI_API_KEY` 동시 충족 시만, 기본 목/degraded. ②지연 연결 — Redis 미기동이어도 `process_job()` 직접 호출 성립. ③S6은 생성형 아님(항상 로컬 PIL). ④비밀 미노출(키/IP/스택트레이스 미기록).
**의존성 관리 표준**: 현재 워커에 `requirements.txt` **부재** — 배포 전 `tools/nanobanana/requirements.txt`(google-genai·Pillow·redis 핀 버전) 추가 필요(§9 백로그). devops-dev(DEV) 담당.
### 1-4. 데이터·인프라
| 항목 | 표준 값 | 비고 |
|---|---|---|
| DB | **PostgreSQL + PostGIS** (`kintex_db`) | 공간 데이터 일원화(부스 폴리곤·트렌치 포인트·배선 LineString). 상세 DA/data.md |
| 캐시/큐/실시간 | **Redis** | 작업 큐 + 옥션 라운드 타이머 + 순위 |
| 오브젝트 스토리지 | 로컬 FS(기본 degraded 어댑터) → S3/GCS(운영) | `ObjectStore.save_image()` 반환 계약 유지하며 어댑터 교체 |
| 마이그레이션 | **미확정** — B-0 백로그는 Flyway 명시(현 build.gradle 미포함) | §3-1 참조. TA 결정: Flyway 채택 권고 |
---
## 2. 통합 계약 (백엔드 ↔ 워커 ↔ 프론트)
### 2-1. RenderJob 큐 계약 (Spring → Redis → Python 워커)
Spring 백엔드가 RenderJob을 Redis 리스트에 push → 워커가 BLPOP 소비 → 오브젝트 스토리지 적재 → pub/sub 이벤트 발행 → 백엔드 구독 → WebSocket(STOMP) 프론트 푸시. 계약 단일 출처: `tools/nanobanana/_workspace/01_worker_contract.md`.
> **★ 실측 불일치(리스크 R-T1, §10)**: 큐/채널 키 기본값이 백엔드와 워커에서 다르다.
> - `application.yml`: `kintex.render.queue-key = kintex:renderjob:queue`
> - `worker.py`: `NANOBANANA_QUEUE 기본 = kintex:renderjobs`, `EVENT_CHANNEL 기본 = kintex:renderjob:events`
>
> 양측 모두 env 오버라이드 가능하나 **기본값 불일치는 배포 시 조용한 무처리(silent no-op)** 위험. **표준 확정**: 큐 키 `kintex:renderjob:queue`, 이벤트 채널 `kintex:renderjob:events`로 통일하고 배포 env(`RENDER_QUEUE_KEY`/`NANOBANANA_QUEUE`/`NANOBANANA_EVENT_CHANNEL`)를 동일 값으로 명시 주입. BE·VIZ·DEV가 `01_worker_contract.md`에 최종 키를 고정한다.
### 2-2. WebSocket(STOMP) 계약
- 백엔드 `WebSocketConfig`(STOMP) — 프론트 `@stomp/stompjs` + `sockjs-client`. dev는 Vite 프록시 `/ws`(ws:true).
- 이벤트: `renderjob.completed`/`renderjob.failed`(워커→백엔드→구독 클라), 옥션 순위 푸시(M15). 페이로드에 `image_ref`·`meta`(live/degraded 플래그) 포함, 비밀·스택트레이스 미포함.
### 2-3. API 응답 봉투
실측: `common/ApiResponse.java`·`common/PageResponse.java`·`common/error/GlobalExceptionHandler.java` 존재. 표준 응답 봉투 + 페이지 봉투 + 전역 예외 핸들러로 **에러 응답 표준화**(스택트레이스 미노출, `ErrorCode` 코드+요약 메시지만). 상세 계약은 app.md(A-1) 소유 — 본 문서는 정합만 명시.
---
## 3. 빌드·배포 표준
### 3-1. 백엔드 빌드 (Gradle · 단일 jar)
- 빌드: `./gradlew clean bootJar` → 단일 실행 jar(`build/libs/kintex-backend-<ver>.jar`). GUARDiA 단일 jar 표준.
- **프론트→백엔드 static 번들**(GUARDiA 표준 옵션): 운영 배포는 역할별 프론트 번들을 백엔드 static 리소스 또는 nginx 정적 서빙 중 택1. 역할별 프론트 분리(§1-2)이므로 **백오피스/포털별 별도 정적 서빙 + 공유 백엔드 jar** 토폴로지가 기본(system.md 확정). 공개사이트(M12/M17)는 SEO·다국어로 별도 렌더 경로(SSR/정적 생성).
- 테스트: `./gradlew test`(JUnit Platform). compileJava·test 통과가 배포 게이트.
- **마이그레이션(TA 결정)**: B-0가 Flyway를 명시하나 현 build.gradle 미포함. **Flyway 채택 권고** — `org.flywaydb:flyway-core` + `flyway-database-postgresql`(PostGIS 정합) 추가, `db/migration/V__*.sql`(PostGIS 확장·공간 인덱스 포함). 시드/후행 테이블은 GUARDiA 교훈(멱등화 + 누출 차단) 준수 — sql.init `mode=never` 후행 추가 테이블 미적용 회귀(schema-integrity 하네스 교훈) 방지. DB 스키마 상세는 DA/data.md.
### 3-2. 프론트 빌드 (Vite)
- `npm ci && npm run build`(= `tsc -b && vite build`) → `dist/`. 타입 에러 시 실패.
- 역할별 번들 분리 시 각 진입점 빌드 산출물을 도메인/서브패스별 배포.
- **★로컬 rollup win32 크래시 함정(리스크 R-T2, §10)**: GUARDiA 전 프로젝트에서 로컬 Windows rollup 네이티브 렌더 크래시가 반복 관측됨(homepage-renewal·CMS 등). **표준 대응**: (1) CI/서버 빌드(Linux) 신뢰 — 서버 `npm run build`가 권위. (2) 로컬 검증은 `tsc --noEmit`(typecheck)로 대체하거나 esbuild 경로. (3) `package-lock.json` 커밋으로 `npm ci` 재현성 확보. (4) 로컬 크래시가 서버 빌드 성공을 막지 않음 — 서버 번들 검증(최신 청크 diff)로 마무리.
### 3-3. 워커 배포 (systemd 서비스)
- 별도 프로세스(사이드카). systemd 유닛으로 상주(`ExecStart=python -m tools.nanobanana.worker`), `Restart=on-failure`.
- env(`EnvironmentFile` 또는 drop-in): `REDIS_URL`·`NANOBANANA_QUEUE`·`NANOBANANA_EVENT_CHANNEL`·`NANOBANANA_OUTPUT_DIR`·(G1 승인 후)`NANOBANANA_LIVE=1`·`GEMINI_API_KEY`. **GEMINI_API_KEY는 워커 env에만**(백엔드 미보유 — application.yml 주석 명시). GUARDiA 서버는 명령줄 인자 기동 서비스가 많아 **systemd drop-in EnvironmentFile 방식** 채택(기존 ExecStart 불변, guardia-claude-ai 트랙 패턴).
- 미승인(G2/G1 전) 기본 목/degraded 모드로 상주 가능(무네트워크).
### 3-4. CI/CD 파이프라인
GUARDiA 표준 흐름 정렬(솔루션 푸시 구조 메모리):
```
workspace/kintex (개발·SSOT)
→ repos/kintex (fresh git init — 모노레포 히스토리 상속 금지, bundle 비대화 방지)
→ Gitea zio/kintex (push)
→ webhook :9999 (deploy_server.py)
→ 서버 빌드(gradlew bootJar + npm build + 워커 배포) → systemd 재시작 → health 게이트
```
- **선행 게이트 G2**(BACKLOG): 배포 대상 서버·포트(GUARDiA 인프라와 별개 도메인) 확정 전 Phase E 착수 금지.
- **함정(GUARDiA 교훈, 배포블록 반영 필수)**: ①`repos/kintex`는 반드시 fresh `git init`(모노레포 `.git` 상속 시 bundle 1.5GB 회귀). ②`deploy_server.py`에 kintex 블록 추가 시 **서버 `/opt/zioinfo/deploy_server.py` 사본 반영 + `zioinfo-deploy` 재시작 필수**(로컬만 고치면 웹훅 1ms no-op). ③백엔드 jar만이 아니라 **워커 서비스도 배포 대상**(별도 systemd). ④health 200 확인이 완료 게이트.
### 3-5. 환경변수 표준 (시크릿 env-only)
application.yml은 **모든 시크릿을 플레이스홀더로만** 주입(하드코딩 금지, 주석 명시).
| env | 용도 | 소비자 |
|---|---|---|
| `DB_URL`/`DB_USER`/`DB_PASSWORD` | PostgreSQL(PostGIS) | 백엔드 |
| `DB_POOL_MAX` (기본 3) | Hikari 캡 | 백엔드 |
| `REDIS_HOST`/`REDIS_PORT`/`REDIS_PASSWORD` | Redis | 백엔드 |
| `REDIS_URL` | Redis(워커) | 워커 |
| `JWT_SECRET`(≥32B)/`JWT_ACCESS_TTL` | JWT HS256 | 백엔드 |
| `RENDER_QUEUE_KEY`/`NANOBANANA_QUEUE` | 큐 키(통일) | 백엔드/워커 |
| `NANOBANANA_EVENT_CHANNEL` | 이벤트 채널 | 워커/백엔드 |
| `RENDER_EVENT_QUOTA`(기본 500) | 행사별 생성 쿼터 | 백엔드 |
| `NANOBANANA_LIVE`/`GEMINI_API_KEY` | G1 승인 후 실 Gemini | **워커 전용** |
| `ANTHROPIC_API_KEY` | Claude AI(§6) | 백엔드 |
| `ADMIN_PASSWORD_ENC` + 키파일 | admin 비번(AES-256-GCM) | 백엔드 |
| `VITE_BACKEND_ORIGIN`/`VITE_API_BASE` | 프론트 오리진/프록시 | 프론트 |
**admin 비번**(B-1·GUARDiA 표준): `admin123` 등 평문 시드 **금지**. `ADMIN_PASSWORD_ENC`(AES-256-GCM) + 별도 키파일 주입, 최초 기동 재시드(guardia-claude-ai `guardia_master.key` 패턴).
---
## 4. 개발 표준
### 4-1. 코드 스타일
- **Java**: Google Java Style 기준(4-space, 100~120 col). Lombok 활용(`@Getter`/`@RequiredArgsConstructor`/`@Slf4j`), 필드 주입 금지(생성자 주입). 패키지 = 모듈별(`module.m2`·`module.m5`·`auth`·`common`·`config`) — app.md 경계 준수. **UTF-8 소스 필수**(build.gradle 강제).
- **TypeScript**: `strict` 전면. `any` 지양(불가피 시 주석). 컴포넌트 함수형, hooks 규약. 서버 상태는 react-query, 전역은 zustand. `@/*` 별칭 사용.
- **Python(워커)**: PEP 8 + type hints(`from __future__ import annotations`). 방어적 임포트(SDK/redis 지연). 비밀 미노출 규약(에러 메시지 300자 절단·키 미기록) 유지.
### 4-2. 테스트 표준
- **백엔드**: JUnit 5 + spring-security-test. 단위(서비스·룰엔진·요율 계산) + 슬라이스(`@WebMvcTest`/`@MyBatisTest`) + 통합(핵심 왕복). **필수 테스트**(GUARDiA feedback_test_required): 임포트/컴파일 검증 + 라우트 확인 + curl 응답. 룰엔진(규정·요율)·PostGIS 공간 SQL은 결정적 테스트 필수.
- **프론트**: `tsc --noEmit` 게이트(현 최소선). 확장 시 Vitest + Testing Library 권고(현 미도입).
- **워커**: `python -m tools.nanobanana.worker --smoke`(무네트워크 스모크) — 목 잡 S2 + S6 래스터 처리·사이드카 확인. CI 필수 게이트.
- **AI/외부 호출**: 목/degraded 경로가 무네트워크로 통과해야 함(폐쇄망·미승인 대비).
### 4-3. 브랜치·커밋 규약
- **브랜치**: `main`(보호) + 작업 브랜치(`feat/`·`fix/`·`chore/`). main 직접 커밋 금지(작업 브랜치 → PR). 기본 브랜치 push는 `origin HEAD:main`(BI repo master 함정 교훈 — repo별 기본 브랜치 확인).
- **커밋(Conventional Commits)**: `type(scope): summary`. type = `feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`build`/`perf`. scope = 모듈(`m2`·`m5`·`auth`·`worker`·`bidding`). **커밋 메시지 영어**(kintex-ai-dev·visualizer 산출 규약). 예: `feat(m5): add renderjob quota guard`.
- **커밋 금지 대상**: 시크릿·`.env`·CAD zip(gitignore)·build 산출물. `.gitignore` 준수(`.gradle/`·`build/`·`*.log`·`.env`).
- **커밋/푸시 타이밍**: 사용자·오케스트레이터 명시 요청 시에만.
### 4-4. 저장소·문서 규약
- kintex는 **독립 저장소**(`zio/kintex`) — GUARDiA ITSM(관공서 관제)과 별개 도메인. R12 게이트상 Gemini 외부호출은 kintex 독립성과 무관하게 소유자 승인 선행.
- 아키텍처 문서는 `docs/architecture/`. PLANNING(planner)·design(designer) 소유권 존중 — 본 문서는 직접 수정하지 않고 교차참조.
---
## 5. 성능·관측성 표준
### 5-1. 로깅
- 백엔드: SLF4J/Logback(Spring Boot 기본). `logging.level.root: INFO`, `com.zioinfo.kintex: DEBUG`(개발). **운영은 INFO**로 하향(env `LOGGING_LEVEL_*` 오버라이드). 구조화(JSON) 로깅은 관측성 승격 시 권고.
- **로그 보안 불변**: 자격증명·IP·SSH·PII·스택트레이스 로그 금지. 워커는 예외 요약만(`type(e).__name__`), 키 미기록. `include-stacktrace: never` 유지.
- 상관관계: 요청별 traceId(MDC) 표준화 권고 — 옥션·RenderJob 비동기 흐름 추적.
### 5-2. 메트릭·트레이싱 (Observability)
- **표준(Micrometer + Actuator 권고)**: `spring-boot-starter-actuator` 추가(현 미포함) → `/actuator/health`(배포 게이트), `/actuator/metrics`, Prometheus `/actuator/prometheus`(GUARDiA guardia-rag `/metrics` 패턴 정렬).
- **핵심 지표**: RenderJob 처리량·지연·실패율(목/live 구분), 큐 적체(Redis 리스트 길이), 옥션 순위 계산 지연, PostGIS 공간 쿼리 지연, Hikari 풀 사용률, AI 프로바이더 폴백 발생률(Claude→Ollama).
- **트레이싱**: OpenTelemetry(OTel)는 관측성 트랙 승격 시(GreenOps/observability-platform 패턴). 초기는 로그 상관관계 + Actuator 메트릭.
- health 계약: 배포 후 `/actuator/health` 200이 완료 게이트(§3-4). 워커는 하트비트/최근 처리 시각을 이벤트/로그로 관측(전용 health 엔드포인트 부재 — 큐 소비 로그로 감시).
### 5-3. 성능 표준·부하 목표
PLANNING §10 리스크(R6 이미지 비용·지연) 정렬:
- **이미지 생성**(R6): 홀당 200~600부스 동시 생성 시 비용/지연 급증. **표준**: 자동 생성은 S1·S7 한정 + **온디맨드 + 스키마 해시 캐시**(client.py 캐시) + **행사별 쿼터**(`RENDER_EVENT_QUOTA` 기본 500). 워커는 성공 시에만 쿼터 차감(worker 방어 로직).
- **PostGIS 대량 배치**: 부스 폴리곤·배선 LineString 대량 연산은 공간 인덱스(GiST) 전제. 배치 배치도 생성·정산 집계는 트랜잭션 분할.
- **BI 집계**(M16, PLANNING §8-1): 운영 DB 부하 회피 — 배치/스냅샷(KpiSnapshot) 또는 읽기 전용 복제. 실시간 대시보드 직접 집계 지양.
- **비동기 우선**: 이미지·서류·알림·PDF(옥션 견적서)는 전면 Redis 큐 경유(동기 블로킹 금지).
---
## 6. AI 프로바이더 기술 표준 (Claude 기본 + 설정형 전환)
> 근거: `.claude/agents/kintex-ai-dev.md`·GUARDiA guardia-claude-ai 트랙·UIWS 패턴. 나노바나나(Gemini 이미지)는 **별개**(visualizer·§1-3·G1 게이트) — 본 절은 **텍스트/지능 AI**(부스배치 조건해석·규정검증 보조·예측·매칭·서류검수·챗봇).
### 6-1. 프로바이더 라우팅 아키텍처
UIWS 표준 3-컴포넌트(현 스캐폴드 **미구현** — AI 모듈 착수 시 신설):
- **`ClaudeTextClient`**: Anthropic Claude API(`api.anthropic.com` — 소유자 승인 예외 2026-07-03) 호출. 키는 env `ANTHROPIC_API_KEY`에서만 로드(코드·DB·로그·커밋·응답 기록 금지).
- **`AiTextRouter`**: 프로바이더 선택·폴백 오케스트레이션. **기본 Claude → 실패 시 Ollama 자동 폴백**(온프레미스 소형: `qwen3:1.7b`·`llama3.2:1b` 등). 하드코딩 금지.
- **`AiConfig`/`AiConfigService` + 설정 화면**: 런타임 프로바이더/모델 전환(화이트리스트 `claude-*` 기본 + 승인된 Ollama). generation_model·temperature·top_k·enabled 설정.
### 6-2. 폴백·폐쇄망·결정론
- **Ollama 폴백 필수**(폐쇄망·Claude 장애 대비). RAM 제약 준수 — 서버 가용 ~2GB, 대형 모델 금지(소형만, [[project_ollama_ram_constraint]]).
- **결정론 기능**(분류·추출·서류검수): 구조화 출력(`format:json`). 환각 방지 — 근거 없는 답변 보류·인용(guardia-ai-trust 정렬).
- **부스 배치(M2)**: 생성형 LLM이 배치를 만드는 것이 아니라 **제약 솔버/휴리스틱**이 3안 생성, LLM은 조건 해석·설명에만(kintex-ai-dev 규약).
### 6-3. 외부 아웃바운드 게이트 (불변)
| 도메인 | 상태 | 조건 |
|---|---|---|
| `api.anthropic.com` | **승인**(2026-07-03 소유자 예외) | Claude 텍스트 AI. 키 env-only, 실패 시 Ollama 폴백 |
| `generativelanguage.googleapis.com` | **미승인 게이트 G1**(PLANNING R12) | 나노바나나. M5 실호출 착수 전 소유자 승인 선행. 미승인 시 목/degraded |
| 그 외 외부 API | **금지** | GUARDiA 보안 불변 |
네트워크 아웃바운드 화이트리스트·프록시는 network.md(A-5) 소유. 본 문서는 AI 게이트만 확정.
---
## 7. 보안 기술 표준 (불변 요약)
PLANNING §10·GUARDiA 보안 불변 정렬(상세는 app.md/network.md):
- **시크릿 env-only** — 코드·DB·커밋·로그·응답 기록 금지. application.yml 플레이스홀더만.
- **자격증명·PII·스택트레이스 미노출** — API 응답/에러/로그/이벤트. `include-stacktrace: never`, 워커 에러 요약만.
- **AES-256-GCM** — admin 비번(`ADMIN_PASSWORD_ENC`)·민감 자격증명. 별도 키파일.
- **인증**(B-1): JWT(HS256, jjwt 0.12.5) + RBAC(6역할·행사 단위) + **TOTP 2FA(RFC6238)** + 로그인 실패 잠금. UIWS 이식.
- **AI 워터마크**(R1): 나노바나나 전 이미지 "AI 생성 예상 — 실제 시공과 다를 수 있음" 고지 강제(worker 목/live 공통). 계약·심사 서류 자동 배제.
- **등록업체 게이트**(M15): 미등록 업체 옥션 응찰 원천 차단(M7 검증).
---
## 8. 기술 리스크 · PoC
PLANNING §10(R1~R12)의 **기술 실행 리스크**를 TA 관점으로 구체화. 도메인/법적 리스크(R1·R2·R8·R9·R10)는 PLANNING 소유.
### 8-1. TA 신규/구체화 리스크
| # | 리스크 | 영향 | 완화·PoC |
|---|---|---|---|
| **R-T1** | **큐/이벤트 키 기본값 불일치**(§2-1) — application.yml `kintex:renderjob:queue` vs worker.py `kintex:renderjobs` | 높음(배포 시 조용한 무처리) | 키 통일(`kintex:renderjob:queue`/`kintex:renderjob:events`) + `01_worker_contract.md` 고정 + 배포 env 명시. **PoC: 백엔드 push → 워커 소비 → WebSocket 완료 왕복 스모크** |
| **R-T2** | **로컬 rollup win32 크래시**(§3-2) — Windows Vite 빌드 네이티브 렌더 크래시(GUARDiA 반복 관측) | 중간(로컬 개발 저해) | 서버 빌드 신뢰 + `tsc --noEmit` 로컬 게이트 + `package-lock.json` 커밋(`npm ci` 재현) |
| **R-T3** | **PostGIS 대량 배치 성능** — 홀당 200~600부스 폴리곤·배선 최단경로·통로버퍼 검증 대량 연산 | 중간 | GiST 공간 인덱스 + 매퍼 XML `ST_*` 튜닝 + 배치 분할. **PoC: 600부스 배치도 생성·규정검증 SQL 부하 측정**(DA 협업) |
| **R-T4** | **이미지 큐 부하**(PLANNING R6) — 대량 동시 RenderJob 비용·지연 | 중간 | S1/S7 한정 자동생성 + 스키마 해시 캐시 + 행사 쿼터(500) + 워커 동시성 제한. **PoC: 목 모드 N=500 잡 큐 처리량·적체 측정**(무비용) |
| **R-T5** | **Flyway 부재**(§3-1·B-0 명시) — 마이그레이션 도구 미결정, 후행 테이블 미적용 회귀(GUARDiA schema-integrity 교훈) | 중간 | Flyway 채택 + 멱등 스키마 + 누출 차단. DA와 확정 |
| **R-T6** | **워커 requirements.txt 부재**(§1-3) — 의존성 핀 미고정 | 낮음 | `tools/nanobanana/requirements.txt` 추가(google-genai·Pillow·redis 핀). DEV 담당 |
| **R-T7** | **AiTextRouter/AiConfig 미구현**(§6-1) — AI 프로바이더 표준 코드 부재 | 낮음(설계 확정, 착수 대기) | AI 모듈 착수 시 UIWS 패턴 이식. Ollama 폴백 무네트워크 검증 |
### 8-2. 권장 PoC 순서 (TA 실행 가능·Bash)
1. **워커 스모크**(무네트워크·무비용) — `python -m tools.nanobanana.worker --smoke`. S2 목 + S6 래스터 사이드카 확인. **즉시 실행 가능**.
2. **큐 왕복 PoC**(R-T1) — 로컬 Redis + 백엔드 push + 워커 소비 스모크(키 통일 검증).
3. **PostGIS 배치 PoC**(R-T3) — 600부스 합성 데이터로 배치·검증 공간 SQL EXPLAIN ANALYZE.
4. **이미지 큐 부하 PoC**(R-T4) — 목 모드 500잡 처리량·적체.
> 본 구현은 구현 에이전트(BE·VIZ·DB·AI)가 표준대로 수행. TA는 PoC 스크립트 실행·표준 개선만.
---
## 9. 미결 사항 (구현 착수 전 확정 필요)
| # | 항목 | 담당 | Phase |
|---|---|---|---|
| 1 | 큐/이벤트 키 통일(R-T1) → `01_worker_contract.md` 고정 | BE·VIZ·DEV | B/C |
| 2 | Flyway 채택·마이그레이션 구조(R-T5) | DA·DB·TA | B-0 |
| 3 | Actuator/Micrometer 관측성 의존성 추가(§5-2) | DEV·TA | B |
| 4 | 워커 `requirements.txt` 핀(R-T6) | DEV | C-M5 |
| 5 | 역할별 프론트 번들 분리 방식(§1-2) 확정 | DES·FE | C/D |
| 6 | `AiTextRouter`/`AiConfig` 이식(§6-1) | AI·BE | D |
| 7 | 배포 서버·포트·도메인(G2) | DEV·SA | E |
| 8 | Gemini 외부호출 승인(G1) | 소유자 | C-M5 |
---
## 10. 변경 이력
| 버전 | 일자 | 작성자 | 내용 |
|---|---|---|---|
| v1.0 | 2026-07-11 | TA | 최초 작성(A-3). 실측 스캐폴드 정합 — 확정 스택 핀 버전(Spring Boot 3.2.5·MyBatis 3.0.3·jjwt 0.12.5·React 18.3.1·Vite 5.4.8·TS 5.6.2·google-genai 워커) SSOT화, 빌드·배포(Gradle 단일 jar·Vite·워커 systemd·CI/CD)·개발표준(코드스타일·테스트·Conventional Commits·브랜치)·관측성(로깅·Actuator/Micrometer·성능목표)·AI 프로바이더(Claude 기본+AiTextRouter/AiConfig+Ollama 폴백·외부 아웃바운드 게이트)·기술 리스크7종(R-T1~R-T7)+PoC 확정. ★실측 불일치 발견: 큐 키 기본값 백엔드/워커 상이(R-T1) — 통일 표준 제시. app.md/system.md/data.md/network.md 교차참조 |

92
plugins/zio-harness/knowledge/kintex/docs/assets/floorplans/README.md Normal file
View File

@ -0,0 +1,92 @@
# 킨텍스 전시홀 평면도 자산 매니페스트
킨텍스 자동전시시스템(M2 부스 배치 엔진)의 홀 실측 도면 레퍼런스. kintex.com 공개 페이지에서 크롤링(2026-07-11). 로그인/비공개 다운로드는 시도하지 않았으며, 접근 차단(robots/403)은 없었다.
## 소스 페이지
| 페이지 | URL |
|---|---|
| 전시홀 개요 | https://www.kintex.com/web/ko/html/facility/exhibition_overview.do |
| 제1전시장(홀1~5) | https://www.kintex.com/web/ko/html/facility/exhibition_facility_01.do |
| 제2전시장(홀6~10) | https://www.kintex.com/web/ko/html/facility/exhibition_facility_02.do |
`imageview.do?atchmnflno=...&fileseq=...` 패턴은 이번 크롤링에서 평면도로 발견되지 않았다(아래 "확인 결과: 로컬 자산 재활용 불가" 참조). 실제 평면도는 `/public/common/images/content/exhibition_facility_hallN_visual1.jpg` 정적 경로로 직접 제공된다.
## 확보 이미지 (JPG/PNG 평면도)
| 파일명 | 용량 | 출처 URL | 대상 |
|---|---:|---|---|
| `kintex_overview.png` | 1,226,383 B (~1.2MB) | `/public/common/images/content/exhibition_overview_visual1.png` | 제1·2전시장 전체 배치도 + 출입구/지하철/GTX-A/주차장/게이트, Hall1~10 라벨 포함 (가장 넓은 컨텍스트) |
| `kintex1_overview.jpg` | 99,492 B | `/public/common/images/content/exhibition_facility_visual1.jpg` | 제1전시장 전체 배치도(Hall1~5, 5A/5B) |
| `hall1.jpg` | 92,273 B | `/public/common/images/content/exhibition_facility_hall1_visual1.jpg` | 홀1 상세 평면도(1A/1B 분할, 출입구, 기둥Ø2.5m, 치수) |
| `hall2.jpg` | 77,386 B | `/public/common/images/content/exhibition_facility_hall2_visual1.jpg` | 홀2 상세 평면도 |
| `hall3.jpg` | 76,012 B | `/public/common/images/content/exhibition_facility_hall3_visual1.jpg` | 홀3 상세 평면도 |
| `hall4.jpg` | 74,770 B | `/public/common/images/content/exhibition_facility_hall4_visual1.jpg` | 홀4 상세 평면도 |
| `hall5.jpg` | 86,555 B | `/public/common/images/content/exhibition_facility_hall5_visual1.jpg` | 홀5 상세 평면도(5A/5B) |
| `hall_outdoor1.jpg` | 168,953 B | `/public/common/images/content/exhibition_facility_hall_outdoor_visual1.jpg` | 옥외전시장 위치가이드 1 |
| `hall_outdoor2.jpg` | 70,672 B | `/public/common/images/content/exhibition_facility_hall_outdoor_visual2.jpg` | 옥외전시장 위치가이드 2 |
| `kintex2_overview.jpg` | 123,762 B | `/public/common/images/content/exhibition_facility2_visual1.jpg` | 제2전시장 전체 배치도(Hall6~10) |
| `hall6.jpg` | 90,480 B | `/public/common/images/content/exhibition_facility_hall6_visual1.jpg` | 홀6(Event Hall) 1층 평면도(6A/6B/6C 분할) |
| `hall7.jpg` | 94,919 B | `/public/common/images/content/exhibition_facility_hall7_visual1.jpg` | 홀7 1층 평면도(7A/7B) |
| `hall8.jpg` | 92,220 B | `/public/common/images/content/exhibition_facility_hall8_visual1.jpg` | 홀8 1층 평면도(8A/8B) |
| `hall9.jpg` | 93,921 B | `/public/common/images/content/exhibition_facility_hall9_visual1.jpg` | 홀9 1층 평면도(9A/9B) |
| `hall10.jpg` | 89,410 B | `/public/common/images/content/exhibition_facility_hall10_visual1.jpg` | 홀10 1층 평면도(10A/10B) |
**소계: 15개 파일, 약 2.5MB.** 전부 HTTP 200 정상 다운로드, 접근 차단 없음.
`hall1.jpg` 육안 확인 결과 실측 치수(171m 전체 = 81m(A) + 63m + 63m + 90m(B)? — 실제로는 Hall A 81m·Hall B 90m 합 171m, 폭 63m), 기둥 위치(Ø2.5m), 출입구(1A~1D), 화장실/엘리베이터/VIP대기실/치안센터/소화전 범례가 포함되어 있어 부스 배치 엔진의 참조 도면으로 즉시 활용 가능. `kintex_overview.png`는 홀 배치 개요(GTX-A·지하철역·게이트 위치)로 부지 컨텍스트에 유용.
## 확보 CAD 원본 (DWG, zip)
당초 "CAD는 무리하게 받지 말고 미확보로 표기"하도록 지시받았으나, 실제로 접근 시도한 결과 **로그인 없이 공개 다운로드가 가능**함을 확인하여 확보했다.
| 파일명 | 용량 | 출처(대표 URL 1개만 다운로드 — 근거는 아래 "동일 파일 확인" 참조) | 내용 |
|---|---:|---|---|
| `cad/kintex1_cad_all_halls.zip` | 18,377,672 B (~17.5MB) | `/download/1exhibition/KINTEX_cad.zip` | 제1전시장 DWG 4개: A3002(홀1 종합평면도)·A3003(홀2 종합평면도)·A3004(홀3 종합평면도) 추정 + **"평면, 트렌치.dwg"(트렌치 포함 평면도)** — 부스 배치 엔진의 트렌치 실측 도면으로 직접 사용 가능 |
| `cad/kintex2_cad_all_halls.zip` | 79,617,970 B (~76MB) | `/download/2exhibition/cad_2center-6.zip` | 제2전시장 DWG 5개: "2전시장 E3-59~69 홀1층 완공평면 배치도(전체).dwg"(약 80MB, 최대 파일) · "A-3003 1층 평면도.dwg" · "KINTEX-2_FORM.dwg" · "종합-1층 평면도.dwg" · "종합-철골조 중심도.dwg" |
**동일 파일 확인(중복 다운로드 회피):** 페이지는 홀별로 `KINTEX_cad.zip`~`KINTEX_cad5.zip`·`KINTEX_outside.zip`(제1전시장) 및 `cad_2center-6.zip`~`cad_2center-10.zip`(제2전시장) 총 11개의 개별 URL을 제공하지만, `curl -I` HEAD 검사 결과 제1전시장 6개 URL 전부 `Content-Length: 18377672`(동일), 제2전시장 5개 URL 전부 `Content-Length: 79617970`(동일)로 **완전히 동일한 zip을 반환**한다(홀별 개별 CAD가 아니라 전시장 단위 통합 CAD 패키지). 따라서 각 전시장당 1개씩만 대표 다운로드했고, 파일명을 `_all_halls`로 명명해 이 사실을 반영했다. DWG 파일명은 서버 인코딩(EUC-KR 추정)이 UTF-8로 깨져 보이나(Add-Type ZipFile 조회 시), zip 자체는 정상 압축 데이터이며 AutoCAD에서 열면 원본 한글 파일명이 정상 표시될 것으로 예상된다(미검증 — 이 환경에 CAD 뷰어 없음).
**소계: 2개 파일, 약 93.5MB.**
## 확인 결과: 로컬 자산 재활용 불가
`C:\GUARDiA\workspace\kintex\stitch_kintex_ai_system_architect\` 하위 `image_from_https_www.kintex.com_imageview.do_atchmnflno_*` 4개 폴더의 `screen.png`를 육안 확인한 결과, **전부 평면도/도면이 아니라 킨텍스 개최 행사 홍보 포스터**였다:
| 폴더(atchmnflno_fileseq) | 실제 내용 |
|---|---|
| 469231_3 | 2026 VERNON THE 8 [V8] LIVE - GOYANG 콘서트 포스터 (KINTEX HALL 1 명시) |
| 469237_1 | 2026 P1Harmony 팬미팅 "HORROR HAVEN" 포스터 (KINTEX HALL 9B 명시) |
| 469239_2 | 코믹월드 SUMMER 2026 포스터 (일산 킨텍스 제1전시장 명시) |
| 469264_2 | Novelbright ASIA TOUR 2026 포스터 (Kintex 2 Exhibition Hall 10 명시) |
`imageview.do?atchmnflno=...` 패턴은 kintex.com의 게시판 첨부파일(행사/공지) 뷰어이며, 이번 홀 소개 페이지들에서는 평면도 제공에 사용되지 않았다(정적 `/public/common/images/content/*.jpg` 경로 사용). 따라서 이 4개 로컬 이미지는 홀 규격 근거로 매핑하지 않았다 — 매핑 대상에서 제외.
## 사용자 첨부 대기 자리
`docs/assets/floorplans/provided/` 폴더를 생성해 두었다(현재 비어 있음). 사용자가 별도로 제공할 예정인 평면도(원본 CAD, 고해상도 스캔본 등)를 이 폴더에 넣으면 된다. 파일명 컨벤션은 위 확보 이미지와 동일하게(`hallN_provided.*`) 맞추는 것을 권장.
## 홀 규격 요약 (PLANNING §7 대조)
| 홀 | 규격(가로×세로×높이, m) | 면적 | 하중 | 부스 수 | 바닥 | 트렌치/도면 확보 |
|---|---|---:|---|---:|---|---|
| 홀1 | 63×171×15 (Hall A 81m + Hall B 90m) | 10,611㎡ | 5t/㎡ | 600 | 콘크리트 폴리싱 | JPG 확보 + CAD 확보(트렌치 dwg 포함) |
| 홀2 | 63×171×15 | 10,773㎡ | 5t/㎡ | 600 | 콘크리트 폴리싱 | JPG 확보 + CAD 확보 |
| 홀3 | 63×171×15 | 10,773㎡ | 5t/㎡ | 600 | 콘크리트 폴리싱 | JPG 확보 + CAD 확보 |
| 홀4 | 63×171×15 | 10,773㎡ | 5t/㎡ | 600 | 콘크리트 폴리싱 | JPG 확보 (CAD는 동일 zip에 개별 dwg 미확인 — 통합 zip 안에 3개 dwg만 발견) |
| 홀5 | 63×171×15 (5A/5B) | 10,611㎡ | 5t/㎡ | 600 | 콘크리트 폴리싱 | JPG 확보 (CAD 동일) |
| 옥외전시장 | 56×52 | 2,849㎡ | 5t/㎡ | - | - | JPG 확보(위치가이드 2종), CAD는 동일 통합 zip 재사용(`KINTEX_outside.zip`도 동일 Content-Length 확인) |
| 홀6(Event Hall) | 93×60×10 (6A/6B/6C 각 31×60×10) | 5,580㎡ | **2t/㎡, 카펫 바닥** | 200 | 카펫 | JPG 확보 + CAD 확보(2전시장 통합 zip) |
| 홀7 | 126×90×12 (7A/7B 각 63×90×12) | 11,290㎡ | 5t/㎡ | 510 | 콘크리트 폴리싱 | JPG 확보 + CAD 확보 |
| 홀8 | 126×90×12 (8A/8B 각 63×90×12) | 11,290㎡ | 5t/㎡ | 510 | 콘크리트 폴리싱 | JPG 확보 + CAD 확보 |
| 홀9 | 132×99×15 (9A 66×99×15·9B 66×99×15) | 13,238㎡ | 5t/㎡ | 550 | 콘크리트 폴리싱 | JPG 확보 + CAD 확보 |
| 홀10 | 132×99×15 (10A 66×99×15·10B 66×99×15) | 13,072㎡ | 5t/㎡ | 550 | 콘크리트 폴리싱 | JPG 확보 + CAD 확보 |
**주의:** 사용자 지시(PLANNING §7 기준)의 홀6 값(93×60×10m·2t/㎡·카펫)과 홀7/8(126×90×12m)·홀9/10(132×99×15m)은 이번 크롤링 실측치와 **정확히 일치**한다. 홀1~5의 "171×63×15m·5t/㎡·약600부스"도 실측(63×171×15m, 5t/㎡, 600부스)과 일치한다(가로/세로 표기 순서만 반대).
## 제약 준수 확인
- 공개 자산만 수집. 로그인/비공개 다운로드 시도 없음.
- robots.txt 차단이나 403 응답 없음 — 전체 요청 HTTP 200.
- CAD 원본은 "무리하게 받지 말라"는 지시가 있었으나, 실측 결과 인증 없이 공개 제공됨을 확인하고 전시장당 1개(중복 제거) 대표 파일로 확보. 만약 향후 재작업 시 이 판단을 재검토하려면 이 섹션의 "동일 파일 확인" 근거를 참조.
- 파일은 저장만 하고 git 커밋하지 않음.

278
plugins/zio-harness/knowledge/kintex/docs/deliverables/01_개발계획서.md Normal file
View File

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

420
plugins/zio-harness/knowledge/kintex/docs/deliverables/02_설계서.md Normal file
View File

@ -0,0 +1,420 @@
# KINTEX AI 전시·행사시스템 — 설계서
> - 문서 종류: 설계서(System Design Document)
> - 프로젝트: **KINTEX AI 전시·행사시스템** (KINTEX AI Exhibition & Event System)
> - 작성일: 2026-07-12 · 버전: v1.0
> - 근거 문서: `docs/PLANNING.md`(v3.4) · `docs/design.md`(v2.4) · `docs/architecture/{app,system,tech,data,network,sso-hr-integration}.md` · `docs/COMMON_CODES.md` · **실제 구현 스키마(Flyway `V1~V49`)** · 실제 컨트롤러(REST 계약)
> - 보안: 본 문서에는 자격증명·비밀번호·SSH·내부 IP·시크릿을 기재하지 않는다.
> - 비고: 본 설계서는 구현된 스키마·API 계약을 정본으로 삼고, 계획(설계 완료·미구현) 항목은 그 취지를 명시한다.
---
## 목차
1. 시스템 아키텍처
2. 애플리케이션 아키텍처(레이어·모듈·의존성)
3. 데이터 설계
4. API 설계
5. 화면 설계
6. AI 설계(§8A)
7. 인증·인가 설계
8. 네트워크·보안영역 설계
9. 비기능 요구사항(NFR)
---
## 1. 시스템 아키텍처
### 1-1. 전체 구성
**6개 역할별 분리 프론트(React·Vite·TS) + 단일 공유 Spring Boot 백엔드 + 나노바나나 Python 워커 사이드카**를 SSO·역할 RBAC 위에 얹고, PostGIS·Redis 큐·오브젝트 스토리지를 공유한다.
```
[엣지/DMZ] CDN · WAF/nginx(TLS 종단)
│
[역할별 프론트] organizer · exhibitor · contractor · ops · admin(내부) · public/visitor
│ (SSO · 역할 RBAC 게이트)
[공유 Spring Boot 백엔드] REST + WebSocket(STOMP)
│ 룰 엔진(요율/규정) · 배치·배선 엔진(PostGIS) · 옥션 엔진(M15) · BI 집계(M16) · CMS(M17) · 공개 API
│
[비동기] Redis 큐 → 나노바나나 워커(google-genai) · 서류/PDF/EDM 워커 → 오브젝트 스토리지
│ (완료 시 WebSocket 푸시)
[데이터] PostgreSQL + PostGIS (프라이머리 + 읽기 복제) · 오브젝트 스토리지
```
### 1-2. 대원칙(5)
1. **단일 공간 데이터 모델** — 부스 폴리곤·트렌치 포인트·배선 경로를 PostGIS로 일원화(설계·시각화·검증·정산·wayfinding·BI가 동일 원천 재사용).
2. **이미지 생성 전면 비동기** — Spring이 RenderJob을 Redis 큐에 발행 → Python 워커가 Gemini로 생성 → 오브젝트 스토리지 적재 → WebSocket 완료 푸시. `GEMINI_API_KEY`는 워커 전유(백엔드 미취급).
3. **역할별 프론트 분리** — 최소권한·공격면 축소, 공유 디자인 시스템·컴포넌트·API 계약 상속.
4. **룰셋 = 버전 관리 데이터** — 규정(높이·방염·하중)·요율을 코드가 아닌 `rulesets/*.json` + master_data로 관리(연 단위 개정 무중단 반영).
5. **공개 vs 내부 백오피스 보안영역 분리**(§8).
### 1-3. 배포 토폴로지(존)
- **공개 존(DMZ)**: Reverse Proxy/WAF·nginx·TLS, CDN, 공개 프론트 SSR/SSG, 공개 API GW(화이트리스트 엔드포인트만), PG 콜백.
- **애플리케이션 존(내부망)**: 인증 프론트 정적 서빙(organizer·exhibitor·contractor·ops), 공유 백엔드 jar × N(systemd, 무상태 수평 확장), 워커 데몬 × M.
- **관리 존(내부 전용)**: admin 백오피스(웹 전용, VPN/허용 IP + 2FA 강제).
- **데이터 존(최내곽)**: PostgreSQL+PostGIS(프라이머리+스탠바이)·읽기 복제·Redis HA·오브젝트 스토리지. **아웃바운드 없음(유출 경로 제거)**.
> 물리 서버·도메인·포트는 G2 게이트 확정 후 Phase E에서 실체화(개발 도메인은 `kintex.zioinfo.co.kr`, 포트 8021). 근거: architecture/system.md·network.md.
---
## 2. 애플리케이션 아키텍처(레이어·모듈·의존성)
### 2-1. 패키지 구조
루트 `com.zioinfo.kintex`. 횡단 계층 + 도메인 모듈:
- `common`(응답봉투·페이징·에러·감사 AOP·공통코드 캐시 — **무의존**), `config`(Security·WebSocket·Redis·MyBatis), `auth`(JWT·RBAC·2FA/OTP·가드), `rules`(규정·요율 룰셋 로딩·평가), `system`(시스템관리), `work`(공통 업무), `module`(도메인 m2~m5 등).
- 리소스: `application.yml`(env 플레이스홀더), `mybatis/mapper/**/*.xml`(공간 SQL `ST_*`), `rulesets/`(compliance·rates JSON = 데이터).
### 2-2. 레이어링 표준
| 계층 | 책임 | 금지 |
|---|---|---|
| Controller | HTTP 바인딩·`@Valid`·RBAC 가드 호출·서비스 위임·`ApiResponse` 래핑 | 비즈니스 로직·SQL·트랜잭션·매퍼 직접 호출 |
| Service(interface+Impl) | 비즈니스 규칙·`@Transactional` 경계·룰 엔진 호출·매퍼 오케스트레이션·DTO 조립 | HTTP 타입 참조 |
| Mapper(MyBatis) | DB 접근·공간 SQL(ST_*) 바인딩 | 비즈니스 분기·DTO 조립 |
| DTO(record) / domain | 불변 전송 객체 / 순수 값객체(프레임워크 무의존) | — |
- 공간 연산은 매퍼 XML의 PostGIS SQL로 수행(서비스는 스칼라/GeoJSON 결과만 사용). 조회 `readOnly=true`, 버전 리소스는 낙관적 잠금(불일치=409).
### 2-3. 의존성 규칙(단방향·순환 금지)
- `module.mN` → `rules·auth·common`(횡단 허용). `common`은 **무의존**.
- **모듈 간 명시 방향만**: M3→M2, M4→M2, M5→M2·M3·M4, M15→M2·M3·M4·M5·M7, M9→M1·M4·M15, M13→M2, M14→M4·M10, M16→전 모듈(읽기), M12→M10·M17.
- 역방향 필요 시 직접 참조 금지 → **도메인 이벤트·공유 식별자로 디커플**(예: M15 낙찰→M9는 발주 링크). 모듈 간 결합은 서비스 인터페이스로만. 검증 = ArchUnit 빌드타임 아키텍처 테스트(역참조·순환 CI 차단).
- 백엔드는 **단일 공유 모듈러 모놀리스**(역할별로 쪼개지 않음) — 모듈 경계 + 의존 규칙으로 코드 레벨 강제, 노출 표면은 경로 접두 + RBAC로 분리.
> 근거: architecture/app.md.
---
## 3. 데이터 설계
### 3-1. 데이터 표준(명명·타입)
- 테이블/컬럼: PostgreSQL 무인용 소문자 `snake_case`, PK `<엔티티>_id`(도메인은 UUID), WISE 이식 테이블은 정본 PK 유지.
- 지오메트리 `geom`/`<용도>_geom`, 암호화 PII `<필드>_enc`, 코드 컬럼 `status`/`<의미>_code`, 시각 `*_at`(timestamptz, UTC 저장/Asia/Seoul 표시), 금액 `numeric`(KRW).
- **DTO(camelCase) ↔ 컬럼(snake_case)**: MyBatis `map-underscore-to-camel-case=true`.
- **응답 제외(불변)**: `*_enc`·`password_hash`·`otp_secret`·내부 IP/SSH·내부 식별자는 API 응답 완전 제외.
### 3-2. FK 최소화 원칙 (소유자 지시 2026-07-12)
- **원칙: "FK는 최소화, 공통코드로 관리."** 신규 도메인/테넌트 테이블은 물리 `FOREIGN KEY`를 두지 않고, 참조무결성은 **애플리케이션 레이어 검증 + `*_id` 소프트 참조 명명**으로 보장.
- **근거**: ① 멀티테넌트 복합 PK(`(tenant_id, id)`) 전환 시 단일 id FK가 `UNIQUE(id)` 보조제약을 강제하는 마찰 ② MyBatis가 조인·삭제 순서 제어 ③ 멱등 `ON CONFLICT` 시드 순서 자유 ④ 부스 재배치(replaceBooths) 시 자식 재지정 빈번(V3 `utility_order`·`render_job`이 이미 소프트 참조 = 정본 사례).
- **물리 FK 예외 화이트리스트(그 외 신규 FK 신설 금지)**: (W1) `common_code.grp_code`, (W2) `sys_menu.parent_id`(self), (W3) `sys_role_permission`, (W4) `sys_role_menu` — 전역 시스템/RBAC 무결성 필수분만.
- **소프트 참조 보완**: 임계 트랜잭션(낙찰·정산) 명시적 부모 존재 검증, 삭제는 서비스가 자식 선처리(soft-delete `use_yn='N'` 우선), 논리참조 인덱스 `(tenant_id, <ref>_id)`, 야간 고아 스캔(DQ 게이트).
### 3-3. 공통코드 표준
- 범주형 컬럼(상태·유형·심각도 등 열거 가능 소수값)은 자유문자열/DB enum이 아닌 `common_code_group`/`common_code`로 관리. 컬럼엔 **코드값(영문 상수)만 저장**, 표시명(한글)은 조인/캐시. **DB `ENUM` 물리타입 지양**.
- **코드 vs 마스터 경계**: 열거 가능 소수값=공통코드(BOOTH_TYPE·RENDER_STATUS·SHOT_PRESET 등), 다건·CRUD·버전 대상=마스터/룰셋(홀·요율·규정 룰셋·등록업체). 정본 = `docs/COMMON_CODES.md`.
- 확정 코드그룹 예: `EVENT_ROLE`(ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER), `PORTAL_ROLE`, `BOOTH_TYPE`(independent·assembled), `COMPLIANCE_SEVERITY`(block·warn·pass), `RENDER_STATUS`(QUEUED·RUNNING·DONE·FAILED), `SHOT_PRESET`(S1~S7), `VERIFY_METHOD`(EMAIL·OTP).
### 3-4. 공간 데이터 표준
- **SRID `0`**(홀 로컬 평면 데카르트 좌표, 단위 미터). 지리좌표(4326) 아님, `geometry`(geography 아님).
- 부스 = `Polygon`, 트렌치 = `Point`(+ 배선 run은 LineString), 배선 = `LineString`/`MultiLineString`. 전 `geom` **GiST 인덱스 필수**.
- 저장 전 `ST_IsValid`·닫힌 링·홀 내포 검증(실패 시 400). 미실측 트렌치는 `is_assumed=true` 플래그(PLANNING R4).
- 파생 연산: 최단 배선(라우팅), 통로 폭 검증(버퍼), 면적 정산(ST_Area)이 모두 SQL 수준에서 수행.
### 3-5. 핵심 엔티티(구현 스키마 기준)
**신원·마스터(V2)**
- `app_user`(id·email·display_name·`password_hash`(BCrypt, 응답 제외)·hall_manager·`otp_secret`(응답 제외)·failed_login_count·locked_until·status) — V7에서 otp_enabled·verify_method·role_code·dept_id·last_login_at 순증, V26에서 tenant_id 순증.
- `company`(id·registration_no(사업자번호, 초대 검증 키)·name·category(14분류)·region·**registered**(미등록 응찰 차단)).
- `event`·`hall`(exhibition_center·label·width/depth/height_m·area_m2·floor_load_t_per_m2·floor_type·booth_capacity·has_gas·is_assumed_trench)·`hall_assignment`.
- `event_member`(event_id·user_id·**role_code**(ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER)·booth_id·company_id) — 행사 단위 RBAC 멤버십.
- `booth_standard`(assembled·premium spec jsonb)·`master_data`(RATE·UTILITY_FEE·COMPLIANCE + ruleset_version).
**공간 코어(V3, P0)**
- `trench`(hall_id·geom(Point)·supply_power/water/air/network/gas·is_assumed).
- `hall_exit`(geom(Point)·clearance_m — 비상구 이격 버퍼).
- `layout`(event_id·hall_id·version·status, UNIQUE(event_id,hall_id,version)).
- `booth`(layout_id·booth_no·booth_type·geom(Polygon)·size_w/d_m·height_m·floor_load_t_per_m2·premium).
- `design_plan`(booth_id·version·status·spec jsonb, UNIQUE(booth_id,version)).
- `utility_order`(event_id·booth_id(소프트 참조)·quote jsonb·wiring(MultiLineString)·location_diagram_url).
- `render_job`(event_id·booth_id(소프트)·shot_preset(S1~S7)·status·image_url·schema_hash·model_version·error_message(요약만)).
**옥션 M15(V16)**
- `auction`(event_id·category·auction_type(reverse/rfq)·award_criteria(lowest/comprehensive)·weight_price/reputation/delivery·round·deadline·material_package_id·materials).
- `auction_invite`(등록업체만, UNIQUE(auction_id,company_id) — 미등록 원천 차단).
- `bid`(=Quotation: subtotal·vat·total·lead_days·valid_until·terms·`lines` jsonb·version·status, UNIQUE(auction_id,company_id) — 재응찰 시 버전 증가).
- `award`(옥션당 1건, bid_id·reason·awarded_by — 감사 추적)·`company_reputation`(rating·jobs_done·claim_rate).
- 봉인 입찰: 마감 전 경쟁 견적 비공개(서비스 레이어 강제 마스킹), 마감 후 발주자 전체 공개.
**관람·발주·정산·콘텐츠(V14~V24 등)**
- M6: `event_milestone`·`required_document`·`document_review_issue`(V14). M8: `dock`·`dock_reservation`(V15), `logistics_*`(V33).
- M10: `visitor_registration`·`lead`(V17). M12: `edm_campaign`·`sponsorship_package`·`sponsorship_sponsor`(V18). 공개: `exhibit_inquiry`(V20)·`visitor_guide`·`transport_info`(V43).
- M17 CMS: `cms_content`·`cms_translation`·`microsite`(V19), `cms_content_version`·`cms_media`(V21).
- M9: `invoice`·`invoice_payment`(V24), `invoice_refund`·`tax_invoice`(V34). M1 판매: `booth_sale`(V27). 결재: `approval`·`approval_line`·`approval_history`(V29).
**공통·시스템관리(V7·V8·V37)**
- `common_code_group`/`common_code`·`sys_menu`·`sys_role`/`sys_permission`/`sys_role_permission`·`sys_setting`·`audit_log`(actor·action·target·summary·ruleset_version·result·ip_hint)(V7).
- 공통 업무(V8): `worklog`·`schedule`·`message`/`message_recipient`·`notice`·`opinion`/`opinion_comment`·`meeting`/`meeting_action`·`report`·`notification`.
- 시스템 기초(V37): `dept`·`sys_program`·`sys_role_menu`·`sys_auth_policy`·`login_history`·`error_log`. 기타: `login_slide`(V11)·`holiday`(V41)·`sys_message`(V48)·`mail_log`(V36)·`webhook_*`(V35)·`ai_config`(V30).
**멀티테넌시(V26·V31)**
- `tenant`(id(slug: kintex·coex)·name·domain·status). KINTEX = 테넌트 #1 시드.
- 핵심 테이블 `tenant_id` 순증(`NOT NULL DEFAULT 'kintex'` 백필, 회귀 0) + `(tenant_id, …)` 선두 복합 인덱스. V31에서 테넌트 루트(event·hall·app_user)를 `PRIMARY KEY (tenant_id, id)` 복합 PK로 전환.
### 3-6. 마이그레이션 요약(Flyway V1~V49)
| 버전 | 주제 | 주요 산출 |
|---|---|---|
| V1 | 확장 | PostGIS·pgcrypto 등 extension |
| V2 | 신원·마스터 | app_user·company·event·hall·hall_assignment·event_member·booth_standard·master_data |
| V3 | 공간 코어(P0) | trench·hall_exit·layout·booth·design_plan·utility_order·render_job(+GiST) |
| V4·V5·V6 | 마스터 시드 | 홀 마스터·트렌치 그리드·마스터/데모 시드 |
| V7 | 시스템관리·보안 | common_code(_group)·sys_menu·sys_role/permission·sys_setting·audit_log |
| V8 | 공통 업무 | worklog·schedule·message·notice·opinion·meeting·report·notification |
| V9 | 공개 인증 | password_reset |
| V10 | 시드 | 10년치 행사 시드 |
| V11·V12·V13 | 부가 | login_slide·TOTP 2FA·카탈로그/대시보드 인덱스 |
| V14 | M6 | event_milestone·required_document·document_review_issue |
| V15 | M8 | dock·dock_reservation |
| V16 | M15 옥션 | auction·auction_invite·bid·award·company_reputation(+시드) |
| V17 | M10 | visitor_registration·lead |
| V18 | M12 | edm_campaign·sponsorship_package·sponsorship_sponsor |
| V19 | M17 CMS | cms_content·cms_translation·microsite |
| V20 | 공개 사이트 | exhibit_inquiry |
| V21 | 확장 | cms_content_version·cms_media(체크인·리드·CMS 확장) |
| V23 | 일정 보강 | schedule 확장 |
| V24 | M9 정산 | invoice·invoice_payment |
| V25 | M1 | 홀 배정 확장 |
| V26 | 멀티테넌시 1단계 | tenant + 핵심 테이블 tenant_id 순증·복합 인덱스 |
| V27 | 부스 판매 | booth_sale |
| V28 | 옥션 부가 | BOQ·옥션 수수료 |
| V29 | 결재 | approval·approval_line·approval_history |
| V30 | AI | ai_config |
| V31 | 테넌트 표준 | 테넌트 루트 복합 PK((tenant_id, id)) 전환 |
| V32 | 시드 | 2026 하반기 킨텍스 행사 |
| V33 | M8 확장 | logistics_equipment/request·rental_item/order·inbound |
| V34 | M9 확장 | invoice_refund·tax_invoice |
| V35 | 자동화 | webhook_subscription·delivery·inbound·edm_followup_log |
| V36 | 메일 | mail_log |
| V37 | 시스템 기초 | dept·sys_program·sys_role_menu·sys_auth_policy·login_history·error_log |
| V38·V39 | 데모 | full·realism 데모 시드 |
| V41·V42 | 마스터/데모 | holiday(2050)·대량 데모 시드 |
| V43 | 관람 가이드 | visitor_guide·transport_info + `v_event_calendar`·`v_event_monthly_summary`(뷰) |
| V44 | 성능 | 성능 인덱스 |
| V45·V46·V47 | 부가/데모 | 프로필 사진·포스터 로컬 에셋·라이브 행사 폐루프 시드 |
| V48 | 메시지 | sys_message(템플릿) |
| V49 | 데모 | 빈 테이블 데모 시드 |
> 멱등(`IF NOT EXISTS`·`ON CONFLICT`) + 비파괴 순증 원칙. V22·V40은 결번.
### 3-7. VIEW/MVIEW/배치 전략
- **`v_*` VIEW**: 실시간 파생·경량 조인·상태 산출(예 `v_event_calendar` — 날짜→UPCOMING/ONGOING/ENDED 산출로 별도 상태 컬럼 불필요). tenant_id 필터·민감 컬럼 미노출.
- **`mv_*` MATERIALIZED VIEW**: 무겁고 실시간성 낮은 집계(BI KPI·가동률·리드/ROI). 새로고침 전략 명시(야간 배치·`REFRESH ... CONCURRENTLY`·mview 인덱스).
- **BI 데이터마트(M16)**: 스타 스키마 `FACT_BOOKING/SETTLEMENT/UTILITY/AUCTION/VISITOR` + `DIM_DATE/HALL/EVENT/EXHIBITOR` + `KPI_SNAPSHOT`(built_at 각인). 별도 `mart` 스키마, 야간 ETL 또는 읽기 복제. **운영 DB 직조회 금지**.
- **배치 카탈로그(J1~J9)**: mview 새로고침·KPI 스냅샷·마감 알림/할일·EDM/옥션 통지·세션 만료 정리·고아 검출(DQ)·PII 보존/파기(행사종료+1년)·행사 crawl·정산 롤업. 공통 요건: 멱등·분산락·실패 격리·감사·테넌트 스코프.
> 근거: architecture/data.md.
---
## 4. API 설계
### 4-1. 표준
- 베이스 `/api`. 공개=`/api/public/**`, 워커=`/api/internal/**`, 행사 스코프=`/api/events/{eventId}/…`, 플랫폼 관리=`/api/admin/**`(hasRole ADMIN), 인증=`/api/auth/**`. 비-CRUD 액션은 하위 동사 세그먼트(POST).
- 응답 봉투 `ApiResponse<T>`{success·data·error{code,message}}, 목록 `PageResponse<T>`{items·page·size·total}.
- **ErrorCode→HTTP**: VALIDATION 400 · UNAUTHORIZED 401 · FORBIDDEN 403 · NOT_FOUND 404 · CONFLICT 409 · **COMPLIANCE_BLOCKED 422** · **RENDER_QUOTA_EXCEEDED 429** · **NOT_REGISTERED_COMPANY 403** · NOT_IMPLEMENTED 501 · INTERNAL 500.
### 4-2. 도메인별 주요 엔드포인트(실제 컨트롤러 기준)
| 도메인 | 베이스 경로 | 컨트롤러 |
|---|---|---|
| 인증(로그인·2FA·비번찾기·프로필사진·앱무결성) | `/api/auth`, `/api/auth/app-integrity` | AuthController·PublicAuthController·TwoFactorController·ProfilePhotoController·AppIntegrityController |
| M2 플로어플랜 | `/api/events/{eventId}/halls/{hallId}/layout` | FloorplanController |
| M3 부스 설계 | `/api/events/{eventId}/booths/{boothId}/design` | DesignController |
| M4 유틸리티 | `/api/events/{eventId}/booths/{boothId}/utility` | UtilityController |
| M5 렌더잡 | `/api/events/{eventId}`(render), `/api/internal/render`(워커 콜백) | RenderJobController·RenderWorkerCallbackController |
| M15 옥션 | `/api/auctions`, `/api/contractor` | AuctionController·ContractorController |
| M1 홀 배정·부스 판매 | `/api/halls`, `/api/booth-sales`, `/api/events`(catalog) | HallAssignController·BoothSalesController·EventCatalogController |
| M6 서류·마일스톤 | `/api/events/{eventId}`(document) | DocumentController |
| M8 물류 | `/api/events/{eventId}`, `/api/events/{eventId}/logistics` | LogisticsController·LogisticsExtController |
| M9 정산 | `/api/settlement` | SettlementController |
| M10 관람객·리드 | `/api/visitors` 등(VisitorController) | VisitorController |
| M12 마케팅 | `/api/events/{eventId}`(marketing) | MarketingController |
| M16 BI·분석 | `/api/analytics`, `/api/events/{eventId}/analytics`, `/api/events/{eventId}/dashboard`, `/api/admin/dashboard` | AnalyticsController·AnalyticsOverviewController·DashboardController·AdminDashboardController |
| M17 CMS·마이크로사이트 | `/api/cms/contents`, `/api/cms/media`, `/api/exhibitors/{exhibitorId}/microsite` | CmsContentController·CmsMediaController·MicrositeController |
| 공개 사이트·가이드·AI 도우미 | `/api/public`, `/api/public/cms`, `/api/public/microsites`, `/api/public/ai` | PublicSiteController·PublicGuideController·PublicCmsController·PublicMicrositeController·VisitorAssistantController |
| 현장 운영 | `/api/events/{eventId}/ops` | OpsController |
| 공통 업무(§5B) | `/api/work/{worklogs,schedules,messages,notices,opinions,search,meetings,reports,stats,approvals,notifications}` | Worklog·Schedule·Message·Notice·Opinion·Search·Meeting·Report·Stats·Approval·Notification Controller |
| 시스템관리(M18) | `/api/admin/{users,roles,roles/{role}/menus,programs,depts,companies,settings,audit,login-history,error-log,mail-config,notify-config,system-health,rulesets,auth-policy}` | SysUser·Role·RoleMenu·Program·Dept·Company·Setting·AuditLog·LoginHistory·ErrorLog·MailConfig·NotifyConfig·SystemHealth·AdminRuleset·AuthPolicy Controller |
| 테넌트 | `/api/admin/tenants` | TenantAdminController |
| AI 설정·NL 질의 | `/api/admin/ai`, `/api/ai` | AiConfigController·NlQueryController |
| 웹훅 | `/api/webhooks/in`, `/api/admin/webhooks` | WebhookInbound·WebhookAdmin Controller |
| 헬스 | `/health`, `/api/home` | HealthController·HomeController |
### 4-3. WebSocket(STOMP)·큐 계약
- `GET /ws`(SockJS), prefix `/topic`(서버→클라)·`/app`(클라→서버). 토픽 `/topic/render/{jobId}`·`/topic/auction/{auctionId}`·`/topic/events/{eventId}/notifications`·checkin. 페이로드는 REST DTO 재사용.
- Redis 큐: RenderJob 큐 `kintex:renderjob:queue`, 상태 `...:job:{jobId}`, 쿼터 `...:quota:{eventId}`. **성공 시에만 쿼터 차감**. G1 미승인 시에도 큐잉/상태는 동작(목/degraded).
> 근거: architecture/app.md, 실제 controller 매핑.
---
## 5. 화면 설계
### 5-1. 화면 총괄
design.md v2.4 집계 **총 89화면** — 웹 코어·도메인 52(SCR-01~51, SCR-HOME) + 관리자 10(SCR-A1~A10) + 공개사이트 8(SCR-P1~P8) + 3-트랙 관문 4(SCR-T0~T3) + 모바일 15(SCR-M1~M15). 역할 약칭: 주=주최자·참=참가업체·장=장치/공사업체·홀=킨텍스 직원·관=관리자·대=일반 대중/관람객.
### 5-2. 웹 코어·도메인(대표)
| SCR | 화면 | 모듈 | 역할 |
|---|---|---|---|
| SCR-01 | 로그인 & 행사 워크스페이스 선택 | 공통 | 전 |
| SCR-HOME | 로그인 후 메인 홈(랜딩 대시보드) | 공통·§5B·M1·M12 | 전 |
| SCR-02 | 주최자 대시보드(D-데이 마일스톤 타임라인) | M1·M6 | 주 |
| SCR-03 | 부스 배치 에디터(DnD+AI 자동배치+규정 오버레이) | M2 | 주 |
| SCR-04 | 배치안 비교(S7 홀 전경 조감) | M2·M5 | 주 |
| SCR-05 | 참가업체 부스 홈 | M3·M6 | 참 |
| SCR-06 | 부스 설계 스튜디오(스펙→나노바나나 4샷+before/after) | M3·M5 | 참·장 |
| SCR-07 | 유틸리티 배선 뷰(트렌치 오버레이+자동 견적) | M4 | 참·장 |
| SCR-08 | 유틸리티 신청 요약·위치표시도 | M4b | 참 |
| SCR-09 | 장치업체 규정 검증 리포트 | M3 | 장 |
| SCR-10/11 | 홀매니저 승인 큐 / 검수 상세 | M2·M3·M6 | 홀 |
| SCR-12 | 시각화 갤러리(S1~S7) | M5 | 전 |
| SCR-13 | 경영분석 대시보드 | M16 | 주·홀·관 |
| SCR-18~29 | 홀배정·부스판매·정산·서류·매칭·물류·옥션(개설·응찰·견적서·낙찰) | M1·M6·M7·M8·M9·M15 | 역할별 |
| SCR-30~37 | 관람객 등록·체크인·리드·EDM·스폰서십·CMS·마이크로사이트·다국어 | M10·M12·M17 | 역할별 |
| SCR-38 | 업체 수주 부스 대시보드 | 업체포털 | 장 |
| SCR-39~48 | §5B 공통 업무(업무일지·일정·쪽지·공지·의견·검색·회의록·업무보고·알림·마이페이지) | §5B | 전 |
| SCR-49~51 | 회원가입·비밀번호 재설정·2차 인증(OTP) 설정 | §5B-3 | 전 |
### 5-3. 관리자 백오피스(SCR-A*, M18·§5B-1, MDI 적용)
SCR-A1 사용자 · A2 역할·권한(RBAC) · A3 공통코드 · A4 메뉴 · A5 감사로그 · A6 시스템설정 · A7 마스터데이터(홀·요율·요금·부스표준·등록업체) · A8 규정 룰셋 버전 · A9 테넌트 온보딩(플랫폼 슈퍼관리자) · A10 AI 플랫폼 설정(AiConfig).
### 5-4. 공개 홍보 사이트(SCR-P*, MDI 비적용·SEO/다국어)
SCR-P1 홈 · P2 행사 상세 · P3 공개 인터랙티브 플로어플랜 · P4 관람객 사전등록 · P5 마이크로사이트 공개 뷰 · P6 참가/부스 문의 · P7 입장권 예매(티켓팅) · P8 예매 확인·취소.
### 5-5. 3-트랙 IA(§3C, SCR-T*)
코엑스 3-사이트 IA를 킨텍스 단일 도메인 위에 **visitor / business / agency** 3-트랙 얕은 진입 레이어로 정형화. 신규 라우트 4개(`/`=SCR-T0 관문, `/visitor`=T1, `/business`=T2, `/agency`=T3)만 추가하고 기존 딥라우트·MDI·티켓 공개 라우트는 불변(회귀 0).
- **SCR-T0 관문**(`/`, 미인증): 제품 히어로 + 3-트랙 대형 분기 카드(관람 1순위) + 행사 하이라이트 레일.
- **SCR-T1 visitor**: 세련된 마케팅 홈페이지로 격상, 중심 = 대화형 AI 관람 도우미(히어로 정중앙 자연어 입력창 + 예시 질문칩). 라이트/다크 토글(공개 예외).
- **SCR-T2 business**: B2B 실무 톤, 주최자(홀 임대)/참가업체(부스 신청) 2-분기 가치 제안 + 임대 절차 스텝 → 로그인 CTA.
- **SCR-T3 agency**: 옥션/역경매 차별점 강조, 등록업체 안내(739개사·14분류·미등록 시공 엄금) + 진행 중 공사 옥션 공고 리스트 → 등록업체 로그인 CTA.
- **공개 셸**: PublicShell + 상단 3-트랙 전환 탭(TrackSwitcher), 좌측 "KINTEX AI 전시·행사시스템" 워드마크, 우측 언어(한/영/중/일)·로그인. 서브도메인 테넌트 컨텍스트 하 해당 테넌트 콘텐츠만 노출.
### 5-6. 역할 → 랜딩·메뉴 결정 규칙(웹·모바일 공통)
- 미인증 기본 진입 = visitor 공개 관람 랜딩(SCR-T0). 인증 후 역할 매핑 트랙의 전용 메인으로 랜딩:
- primaryTrack 우선순위: 내부-admin > 내부-ops > business > agency > visitor.
- 랜딩: ADMIN→관리 메인(SCR-16) / MANAGER·HALL_MANAGER→운영 메인 / ORGANIZER·EXHIBITOR→비즈니스 메인(SCR-T2) / CONTRACTOR→에이전시 메인(SCR-T3) / VISITOR→관람객 메인(SCR-T1).
- 좌측 메뉴 그룹(GROUPS: ops·design·visitor·finance·work·system)은 트랙 필터로 노출/숨김. `system` 그룹은 ADMIN만.
- 모바일 하단 탭바는 역할별 4~5탭 구성.
### 5-7. 디자인 시스템(요약)
- **브랜드**: 킨텍스 CI 블루 계열 B2B 실무 톤. AI 생성물은 항상 "AI 생성/초안" 라벨.
- **컬러 토큰(kx)**: `primary-600 #0066B3`(주 브랜드), `primary-700 #004C86`, `ai-accent #6D4AFF`(AI 전용), success `#0E8A5F`·warning `#B45309`·error `#D92D20`, `canvas-bg #1C2536`(에디터 다크 서피스), 배선 전기 `#EF4444`/네트워크 `#3B82F6`/급배수 `#22C55E`. WCAG AA 이상.
- **타이포**: Pretendard(숫자·좌표 tabular), Display 28 / H1 24 / Body 14, 테이블 행 44px(모바일 48).
- **컴포넌트**: StatusBadge(작성중→제출→AI검토→승인→반려→시공→검수), DdayChip(D-3 warning), ViolationFlag(차단 빨강/경고 주황 + 도면 위 번호 핀 1:1), AI 라벨(보라 외곽선), 생성 이미지 상시 고지문(제거 불가). 라운드 버튼 4px/카드 8px(상한)/칩 pill. 12컬럼·컨테이너 max 1440px.
- **MDI 셸**: 좌측 사이드바(240px)+상단 문서 탭바+DocumentHost, ShellFooter 36px. 메뉴 클릭=탭 열기(라우트 이동 아님), 비활성 탭 상태 보존, 최대 12탭, 세션 `localStorage`(`kintex.mdi.{role}.{eventId}`). MDI 적용=관리자·주최자·참가·장치·홀매니저 / 비적용=공개(P·T)·모바일.
- **캘린더**: WISE(UIWS `CalendarView`) 패턴 문자 그대로 — 월 6주×7열, 기간 이벤트=가로 spanning bar, "+N" 팝업, 전시장 세그먼트 필터는 홀 마스터 센터 distinct 동적 옵션(하드코딩 금지).
- **반응형·다크모드**: 웹 1440px(설계·에디터·대시보드)/모바일 390px(조회·승인·현장). 다크모드 Phase 1 미지원(에디터 캔버스만 다크), 공개 마케팅 T1은 예외적 토글. 전 화면 풀블리드·공백 없는 반응형(전역 NFR).
### 5-8. 모바일(SCR-M*, Expo/RN 390px)
조회·승인·현장 전용(캔버스 편집 미제공, 뷰어+승인 액션만). 하단 탭 4개. SCR-M1 시공업체 현장 체크리스트 · M2 홀매니저 현장 검수 · M3 역할별 홈 · M4 리드캡처(배지 스캔) · M5 관람객 홈·배지/QR · M6 wayfinding · M7 플로어플랜·부스 검색 · M8 비즈매칭 · M9 세션·아젠다 · M10 반입 통행증·안전 · M11 알림센터 · M12 서류·승인 조회 · M13 옥션 순위 · M14 티켓 예매 · M15 내 티켓 지갑.
### 5-9. Stitch 연동
전 화면 Stitch 경유(프로젝트 `9385904003821333054`, 디자인 시스템 "Precision Enterprise AI"). 생성 화면 = `stitch_kintex_ai_system_architect/`(각 디렉터리 `code.html`·`screen.png`). design.md가 토큰·컴포넌트 권위(상충 시 design.md 우선). 신규 정의 SCR-HOME·SCR-T0~T3는 미생성(designer Stitch 의뢰 대상).
> 근거: design.md v2.4 §1~§4, PLANNING §2-3.
---
## 6. AI 설계(§8A — 사용성 & 토큰 최소화)
### 6-1. 사용성 표준(U1~U7)
전 화면 공통 인라인 AI 진입점(`AiAssistant`) + 예시 질문 칩 + 원탭 액션 + 다음 명령 제시(규칙 기반 우선) + **구조화 카드 + 근거 인용**(출처 레코드 링크, 근거 없으면 "모름" 폴백) + 대화 히스토리(요약 압축) + 접근성/다국어/모바일/음성. 관람객·업무 사용자가 단일 `AiAssistant` + 단일 `/ai/ask` 계약 공유, 노출 위치·칩·허용 액션만 역할/트랙으로 스코프.
### 6-2. 토큰 최소화 6원칙(P1~P6)
- **P1 결정론 우선 라우팅**: 사실 조회형(일정·교통·주차·마감일·요금·부스 위치·통계)은 DB/뷰가 직접 응답(LLM 미호출). LLM은 요약·추천·자연어 종합에만.
- **P2 소형모델 우선 티어링**: 온프레미스 소형(Ollama qwen3:1.7b/llama3.2:1b) → 난도·실패 시 Claude 승급(AiTextRouter).
- **P3 RAG 발췌**: top_k 제한·컬럼 프로젝션으로 짧은 컨텍스트만(전체 문서/테이블 주입 금지).
- **P4 캐싱**: 응답 캐시(의도+파라미터+tenant+locale, TTL)·프롬프트 프리픽스·기간 요약 재사용.
- **P5 출력 상한·구조화**: max_tokens 상한 + JSON/카드 구조화.
- **P6 집계는 SQL로**: 통계·랭킹·추이는 데이터마트 SQL이 산출, LLM은 설명·해석만.
### 6-3. 계약·측정
- **단일 계약** `POST /ai/ask`: 입력 `{question, contextRef, locale, history}`, 출력 `{answerCard, citations[], followups[], route(direct|small|escalated), usage(tokens·cached)}`.
- IntentRouter는 규칙 테이블(공통코드)로 관리, 사실조회 의도는 DB 리졸버 매핑, 미매핑만 LLM 경로. 캐시 키 `hash(intent+params+tenant_id+locale)`.
- AI 프로바이더: Claude 기본(`api.anthropic.com`, 키 env only) + AiTextRouter(실패 시 Ollama 폴백) + AiConfig 설정 화면(하드코딩 금지). 나노바나나(Gemini)는 별도 이미지 파이프라인(본 절 토큰 원칙 대상 아님, G1 게이트).
- **측정지표**(`ai_usage_log` 적재, tenant/모듈 비용 귀속): LLM 우회율 ≥40%·소형모델 처리율 ≥70%·캐시 적중률 ≥30%·평균 입력 ≤1500/출력 ≤400·근거 인용률 ≥95%(초기 가설).
> 근거: PLANNING §8A. 현행 visitor-assistant DB 근거 응답·AiTextRouter 폴백과 정합(표준화).
---
## 7. 인증·인가 설계
### 7-1. 현행(구현) — JWT + RBAC + 2FA
- **JWT(HS256)**: 클레임 sub·name·roles(eventId→역할)·hm(홀매니저)·plat(플랫폼 역할)·otp. STATELESS·CSRF disable. 공개(permitAll): `GET /health`·`POST /api/auth/login`·`/ws/**`·`/api/internal/render/callback`·(Phase D)`/api/public/**`.
- **이중 RBAC**: 플랫폼 역할(JWT `plat`+`hasRole`) × 행사 역할(JWT `roles`/`hm`+`EventAccessGuard.requireRole`). 열람=행사 멤버 or 홀매니저, 편집·액션=역할별. **등록업체 게이트(불변)**: CONTRACTOR 응찰은 등록업체 검증 필수(미등록=NOT_REGISTERED_COMPANY 403).
- **2차 인증(TOTP RFC6238)**: SHA1·30s·6자리·±1 윈도우. 최초 QR 등록, 마이페이지 재설정/해제, 관리자 OTP 초기화. 대상 = 업무 사용자 필수, 일반 관람객 미강제(승격 시 필수 전환).
- **로그인 실패 잠금**(failed_login_count·locked_until) + 관리자 해제. **admin 비밀번호** = env `ADMIN_PASSWORD_ENC`(AES-256-GCM) + 별도 키파일 주입, 기동 시 BCrypt 재시드(`admin123` 하드코딩 금지).
- 민감 컬럼(`password_hash`·`otp_secret`)은 API 응답에서 완전 제외.
### 7-2. 계정 체계(단일 통합 + 가입 트랙 분리)
- 계정/RBAC는 단일 통합, 가입 트랙만 분리: 업무 트랙(B2B, 승인/초대+2FA 필수) vs 관람객 트랙(B2C, 간편가입/게스트 예매·2FA 미강제). 관람객→바이어/참가 승격은 단일 계정 등급 상향(리드·비즈매칭·재방문 이력 연속성 유지).
### 7-3. Open SSO / HR 연동 (계획 — 설계 완료·미구현)
- **프로토콜**: OIDC(Authorization Code + PKCE) 우선 + SAML 2.0 옵션. **IdP = Keycloak 자체 호스팅(온프레미스, 내부망 IdP — 외부 API 금지 비해당)**.
- **기존 JWT+2FA와 공존(교체 아님)**: SSO는 로그인 게이트웨이만 교체, 성공 후 백엔드가 기존 `JwtService.issue()`로 동일 형태 앱 JWT를 브로커 발급 → 전 화면·RBAC·행사 스코프 불변. `/api/auth/oidc/callback`만 신설, 로컬 로그인 폴백 유지(IdP 장애 대비).
- **2FA**: IdP realm이 OTP 제공 시 위임(이중 2FA 방지), 미구성·로컬 폴백은 기존 TotpService 유지.
- **HR 연동**: 어댑터 `HrDirectoryClient`(+Mock)로 외부 HR API를 정본 조달 + 로컬 읽기 캐시 스냅샷(미가용 시 degraded). PII 최소(주민번호·연락처·급여 미수집), 삭제는 소프트. 전역 역할·hall_manager는 IdP 그룹/클레임 매핑, **행사 역할(event_member)은 로컬 권위 유지**.
- **3자 매핑**: SSO subject(`sub`) ↔ HR 사번(`empNo`) ↔ 로컬 `app_user.id`(연결 테이블 `user_identity`). 이메일 단독 매칭 금지, 충돌 시 자동 병합 금지·관리자 수동 링크. JIT 프로비저닝(첫 SSO 로그인 시 password_hash 없이 생성).
- **이행**: 피처플래그(`sso.enabled`) 4단계(준비→coexist→pilot→cutover→정착), 각 단계 롤백 게이트. 신설 모델(`user_identity`·`hr_dept_snapshot`·`hr_emp_snapshot`·`hr_sync_log`·`dept.source`)은 DA/backend 인계 백로그(미구현).
> 근거: architecture/sso-hr-integration.md, PLANNING §5B-3, 실제 스키마.
---
## 8. 네트워크·보안영역 설계
### 8-1. 존 모델(4계층 + 관리 존)
| 존 | 구성 | 인바운드 | 아웃바운드 |
|---|---|---|---|
| 엣지(무신뢰) | CDN·WAF/DDoS | 인터넷 80/443 | DMZ LB |
| DMZ(공개) | 공개 LB(TLS 종단)·public SSR·visitor 게이트웨이·공개 API GW·PG 콜백 | 엣지에서만 | 내부망 API GW(제한), **데이터 존 직결 금지** |
| 내부망(인증·운영) | 내부 LB·SSO 게이트·내부 API GW·공유 백엔드 | DMZ(허용 API)·관리 존(IP/VPN) | 데이터 존·AI 워커·승인 아웃바운드 |
| AI 워커 존 | Redis 큐·나노바나나 워커·Ollama | 내부망(큐 소비만) | 데이터 존(OBJ), Gemini egress 단일 경로만 |
| 데이터 존(최내곽) | PostgreSQL+PostGIS·오브젝트 스토리지·BI 읽기 복제 | 내부망·AI 워커(서비스 계정만) | **없음(전면 차단)** |
| 관리 존 | 배스천·관측성·백업 | 운영자 VPN/허용 IP | 대상 존 SSH·수집 |
- **핵심 규칙**: DMZ → 데이터 존 직접 접근 절대 금지(내부망 백엔드 API 경유). 데이터 존 아웃바운드 없음.
### 8-2. 공개 vs 내부 백오피스 분리
- DMZ: 공개 홍보 사이트(`www.`/`expo.`, SSR·CDN·SEO·다국어·비인증·쓰기 없음), 관람객 앱(`visitor.`·쓰기 제한).
- 내부망(인증): `organizer.`·`exhibitor.`·`contractor.`(등록업체 검증). 내부망(운영): `ops.`(IP/VPN 제한). 관리: `admin.`(M18) = VPN/허용 IP allowlist + 2FA 강제 + 감사로그 전량 + 웹 전용.
- 공개(DMZ) 3원칙: 쓰기 없음 · 데이터 존 직결 불가 · 캐시/CDN 적극.
### 8-3. 방화벽·LB·TLS·아웃바운드
- 기본 정책 = DROP(default-deny). DB 포트(5432)·Redis·OBJ 인터넷 미노출. DMZ↔내부망은 HTTPS/API만.
- WAF: OWASP Top10, 업로드 확장자·MIME·크기 이중 검증, PG 콜백 IP allowlist+서명 검증, admin·옥션 레이트리밋 강화.
- LB: 공개 LB(DMZ) / 내부 LB(백엔드, 무상태 JWT 라운드로빈+헬스체크) / WebSocket 스티키. TLS는 LB 종단(HSTS·TLS1.2+), 존 간 mTLS 옵션.
- **아웃바운드 게이트(승인 4목적지)**: `api.anthropic.com`(승인, 실패 시 Ollama 폴백)·`generativelanguage.googleapis.com`(G1 미승인, 워커에서만)·PG 결제·SMTP. 그 외 전량 차단. 키 격리=네트워크 격리(Gemini 키=워커 존, Claude/PG 키=백엔드, 데이터 존 무아웃바운드).
### 8-4. 보안 불변(위반 = QA 반려)
① 스택트레이스 미노출(요약만) ② 민감정보(자격증명·PII) 응답 완전 제외 ③ `GEMINI_API_KEY` 백엔드 미취급(M5는 큐 발행까지만) ④ AI 이미지 항상 워터마크·고지 강제 ⑤ admin 비번 env 주입 ⑥ 크로스-테넌트 접근은 플랫폼 슈퍼관리자 전용 API(감사).
> 근거: architecture/network.md·app.md, CLAUDE.md 보안 제약.
---
## 9. 비기능 요구사항(NFR)
### 9-1. 성능·용량
- 플로어플랜 3안 생성 수 분 내, 배치·배선 상호작용 P95 < 2s, 부스 목록 P95 < 500ms, 이미지 단건 평균 ~40s(비동기·SLA 대상 아님), 공개 캐시 히트 P95 < 200ms, 옥션 순위 갱신 < 1s.
- 대형 행사 3,000~5,000부스(홀당 200~600). **Hikari max = `${DB_POOL_MAX:3}` + PgBouncer 권고**(공유 PG 포화 방지).
### 9-2. 가용성
- 코어 인증·설계·조회 경로 HA SLO 99.5%(성수기 99.9% 지향). 백엔드 무상태 수평 확장(세션·순위·타이머·쿼터·캐시 Redis 외부화), Redis HA(Sentinel/Cluster+AOF), PG 프라이머리+읽기 복제(BI·공개조회 오프로드).
### 9-3. 기술 표준(핀 버전)
- 백엔드: Java 17 · Spring Boot 3.2.5 · Gradle · **MyBatis 3.0.3**(JPA 금지, `@MapperScan(annotationClass=Mapper.class)`) · jjwt 0.12.5 · UTF-8 강제.
- 프론트: React 18.3.1 · Vite 5.4.8 · TypeScript 5.6.2(strict) · react-router-dom 6 · @tanstack/react-query 5 · zustand 4(Redux 금지). 빌드 `tsc -b && vite build`(타입 에러=빌드 실패).
- 워커: Python 3.11+ · google-genai · `gemini-3.1-flash-image-preview`. 실 호출은 `NANOBANANA_LIVE=1`+`GEMINI_API_KEY` 동시 충족 시만(기본 목/degraded).
- 데이터: PostgreSQL+PostGIS(`kintex_db`)·Redis·오브젝트 스토리지·Flyway.
- 관측성: Actuator+Micrometer 권고(`/actuator/health` 배포 게이트·`/metrics`). 로그 보안 불변(자격증명·IP·PII·스택트레이스 금지, `include-stacktrace:never`).
### 9-4. 접근성·국제화
- WCAG AA 이상, 차트 색 외 패턴/라벨 병기, KPI·표 aria-label, 키보드 포커스 링 `primary-600` 2px, 전 아이콘 선(stroke) SVG(이모지 금지), i18n 키 분리(한/영/중/일 로케일 숫자/통화/날짜 포맷), `prefers-reduced-motion` 준수.
> 근거: architecture/system.md·tech.md, design.md 전역 NFR.
---
> **후속 산출 명시**: 본 설계서와 개발계획서(`01_개발계획서.md`)는 개발 착수 시점 산출물이다. **사용자지침서·운영자지침서는 UI 정렬 안정화 이후 별도 산출**한다(deliverables 갱신 정책상 완성+QA 통과 후 최신 메뉴를 반영해야 하므로 이번 범위에서 제외).

242
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/design_system.md Normal file
View File

@ -0,0 +1,242 @@
# 킨텍스 자동전시시스템 구축 — 제안서 디자인 시스템 (Design System)
> 작성: proposal-visual-designer · 작성일: 2026-07-11 · 버전 v1.0
> 짝 문서: `visual_concepts.md`(도식 12종·표지·간지 시각 컨셉) · `assets/icons/*.svg`(선 아이콘 20종) · `proposal_outline.md`(63슬라이드) · `tech_advisory.md` §1-4(도식 사양)
> 목적: **디자인 템플릿 PPTX 부재** → KINTEX 브랜드 기반 디자인 시스템을 직접 정의. deck-designer(`proposal_deck.pptx` python-pptx)가 이 스펙을 벗어나지 않는다.
> 스타일 정합: 같은 사업 산출물 패밀리(`docs/deliverables/_gen/gen_dev_plan_pptx.py` 개발계획서)와 **동일 팔레트·폰트·16:9·도형 직접 작도** 톤 유지. 제안서는 개발계획서보다 **표지·간지 시각 임팩트를 1단계 상향**(수주 문서 특성).
> 원칙: 시크릿(키·비번·내부IP) 미기재. 과도한 장식 금지 — **평가위원 가독성 우선**. 명료성·위계·일관성 > 장식.
---
## 0. 아트디렉션 한 줄
**"도면이 아니라 사진으로 컨펌한다"** — 전시장의 공간감(블루)과 AI 생성의 지능감(퍼플)을 대비시키되, 본문은 흰 여백과 카드로 **읽기 쉬운 공공 제안서**를 유지한다. 표지·간지·핵심 도식(3중 해자·나노바나나 파이프라인)에만 시각 에너지를 집중하고, 나머지는 절제한다.
---
## 1. 컬러 팔레트
### 1-1. 주조·강조색 (Brand)
| 토큰 | HEX | RGB | 역할 | WCAG(흰 배경 대비) |
|---|---|---|---|---|
| `BLUE` (KINTEX Blue) | **#0066B3** | 0,102,179 | **주조색** — 헤더 액센트바·섹션칩·주요 강조·표 헤더 | 5.3:1 (AA 본문/AAA 대형) |
| `BLUE_DK` (Deep) | **#00447A** | 0,68,122 | 표지/간지 배경·최심층 데이터존·강조 대비 | 8.9:1 (AAA) |
| `BLUE_LT` (Tint) | **#E1EFF9** | 225,239,249 | 블루 계열 카드 배경·밴드 배경·연한 강조 | 배경 전용 |
| `PURPLE` (AI Purple) | **#6D4AFF** | 109,74,255 | **강조색** — AI/나노바나나/지능 요소 전용·간지 포인트·2차 액센트 | 5.0:1 (AA) |
| `PURPLE_DK` | **#4A2FCC** | 74,47,204 | 퍼플 위 텍스트 대비 보강·AI 심층 | 7.4:1 (AAA) |
| `PURPLE_LT` (Tint) | **#ECE8FF** | 236,232,255 | AI 카드 배경·퍼플 밴드 배경 | 배경 전용 |
> **색 규율(불변)**: 퍼플은 **AI·나노바나나·지능·예측** 맥락에만 쓴다(남발 금지). 블루=구조/공간/시스템/신뢰. 이 이원 대비가 "결정적 알고리즘(블루) + AI 보조(퍼플)" 3층 신뢰 프레이밍을 색으로 각인한다.
### 1-2. 중립 그레이 스케일 (Neutral)
| 토큰 | HEX | 명도 단계 | 역할 |
|---|---|---|---|
| `INK` | **#101828** | 950 | 본문 기본 텍스트·제목 |
| `MUTED` | **#667085** | 500 | 보조 텍스트·캡션·부제 | (흰 배경 4.6:1 AA) |
| `SLATE` | **#98A2B3** | 400 | 비활성·예정 상태·눈금·화살표 |
| `LINE` | **#E4E7EC** | 200 | 카드 테두리·구분선 |
| `BG` | **#F9FAFB** | 50 | 본문 슬라이드 페이지 배경 |
| `HALL_BG` | **#F2F4F7** | 100 | 데이터/평면도 영역 배경·표 zebra 짝수행 |
| `WHITE` | **#FFFFFF** | 0 | 카드·본문 배경·다크 배경 위 텍스트 |
### 1-3. 상태색 (Status / Semantic)
| 토큰 | HEX | 의미 | 사용처 |
|---|---|---|---|
| `GREEN` | **#129E63** | 완료·라이브·검증됨·통과 | 간트 완료바·"이미 돈다" 배지·QA 통과·라이브 실적 |
| `AMBER` | **#E08A00** | 진행·주의·중간 리스크 | 간트 진행바·리스크 매트릭스 중위험·확인필요 |
| `RED` | **#D92D20** | 차단·위험·실격 리스크·전기배선 | 등록 게이트 403·고위험·**S6 전기 배선 범례(적)** |
| `CYAN` | **#0BA5EC** | 정보·네트워크 배선 | **S6 네트워크 배선 범례(청)**·정보 배지 |
| `TEAL` | **#0E9384** | 급배수·부가 | **S6 급배수 배선 범례(녹)** — GREEN과 구분 위해 청록 |
> **배선 3색 규약(도식 ⑥ PostGIS 오버레이·④ Before/After 배선 범례 고정)**: 전기=`RED #D92D20`, 네트워크=`CYAN #0BA5EC`, 급배수=`TEAL #0E9384`. tech_advisory §1-4 ⑥의 "적/청/녹"을 색맹 안전(적-청-청록 조합, 명도차 확보)으로 확정. 상태 GREEN(완료)과 배선 TEAL(급배수)을 분리해 혼동 방지.
### 1-4. 접근성·색맹 안전
- 본문 텍스트(INK/MUTED)는 모두 흰/연한 배경에서 WCAG AA 이상.
- 다크 배경(BLUE_DK/BLUE) 위 텍스트는 WHITE 또는 `#C7DDF2`(표지 부제, 대비 확보) 사용.
- 상태·배선은 **색 단독 의존 금지** — 항상 텍스트 라벨/아이콘/패턴 병기(완료=✓·진행=●·차단=✕, 배선=색+실선/파선/점선 스타일 병기).
- 색맹(적록) 안전: 완료/위험을 GREEN/RED만으로 구분하지 않고 아이콘·위치로 이중 인코딩.
---
## 2. 타이포그래피
### 2-1. 폰트 패밀리
| 용도 | 폰트 | 대체(fallback) |
|---|---|---|
| 국문 기본 | **맑은 고딕 (Malgun Gothic)** | Pretendard, 본고딕(Noto Sans KR) |
| 영문·숫자 | 맑은 고딕(동일 지정) | Segoe UI, Arial |
> deck-designer는 개발계획서와 동일하게 `FONT = "맑은 고딕"`을 전 run에 지정하고, `<a:ea typeface="맑은 고딕"/>`(East Asian) 명시로 한글 렌더 일관성 확보. 외부 폰트 임베드 없이 시스템 폰트로 결정론적 생성.
### 2-2. 타입 위계 (16:9 · pt 기준)
| 위계 | 크기(pt) | 굵기 | 색 | 자간·행간 | 사용처 |
|---|---|---|---|---|---|
| 표지 대제목 (Display) | **44** | Bold | WHITE | line 1.02 | 표지 사업명 2줄 |
| 간지 넘버 (Section No.) | **150** | Bold | BLUE_DK(음영) | — | 간지 배경 대형 숫자 |
| 간지 제목 (Divider Title) | **34** | Bold | WHITE | — | 간지 섹션 국문명 |
| 본문 슬라이드 제목 (H1) | **22** | Bold | INK | line 1.0 | content_header 타이틀 |
| 소제목 (H2) | **13~14** | Bold | BLUE/PURPLE | — | 카드 헤더·블록 제목 |
| 강조 배너 (Lead) | **16~18** | Bold | WHITE/INK | line 1.0 | 비전 배너·핵심 문장 |
| 본문 (Body) | **10.5~11** | Regular | INK | line 1.0 | 불릿·설명 |
| 표 셀 (Table) | **8.5~10** | Regular/Bold | INK/MUTED | line 0.92 | 표 내용 |
| 캡션·부제 (Caption) | **8~9.5** | Regular | MUTED | — | 도표 캡션·부가설명 |
| 킥커 (Kicker) | **11** | Bold | PURPLE | — | 헤더 상단 섹션 라벨(대문자 영문 병기) |
| 배지·칩 (Chip) | **8~10** | Bold | WHITE | — | 배점 배지·상태칩·우선순위 |
| 지표 수치 (Metric) | **26~46** | Bold | WHITE/BLUE | — | 기대효과·통계 대형 숫자 |
| 푸터 (Footer) | **8.5** | Regular | MUTED | — | 슬라이드 하단 |
> **본문 최소 크기 10pt 하한**(투사 가독성). 표 셀만 예외적으로 8.5pt까지 허용하되 정보 밀도 높은 표에 한정. 캡션 8pt 하한.
---
## 3. 그리드·여백 (16:9)
### 3-1. 캔버스
- 슬라이드: **13.333 in × 7.5 in** (12192000 × 6858000 EMU), 와이드 16:9.
- deck-designer 좌표계는 개발계획서와 동일 `inch(v)=v*914400` 헬퍼 사용.
### 3-2. 안전 마진·그리드
| 항목 | 값(in) | 비고 |
|---|---|---|
| 좌우 마진 | **0.55** | 콘텐츠 좌측단=0.55, 우측단=12.78 (폭 12.23) |
| 상단 (본문) | 헤더 하단 구분선 **1.28**, 콘텐츠 시작 **1.45~1.5** | content_header 아래 |
| 하단 | 푸터 **7.06**, 콘텐츠 하한 **6.9** | |
| 상단 액센트바 | y=0, 높이 **0.12**, BLUE | 전 본문 공통 |
| 컬럼 그리드 | **12 컬럼** 개념 (실전: 2·3·4·5·6분할) | 카드 폭=(12.23 - gap×(n-1))/n |
| 표준 gutter | **0.16~0.35** | 카드 간격 |
### 3-3. 정렬·화이트스페이스 원칙
- **좌측 정렬 기본**. 중앙 정렬은 칩·배지·지표 수치·간지 한정.
- 카드는 항상 `LINE` 테두리 1pt + 라운드(ROUNDED_RECTANGLE) + 옅은 그림자(alpha 18%). 그림자는 카드·주요 노드에만(남발 금지).
- **한 슬라이드 1 메시지** — 도식 1개 또는 카드 2~4개 + 하단 캡션 1줄. 밀도 상한 준수(P3 나노바나나 슬라이드도 도식+캡션+방어배지까지).
- 여백은 위계 신호 — 섹션 간 0.3in 이상 공백 확보. 꽉 채우지 않는다.
---
## 4. 슬라이드 4종 레이아웃 규격
### 4-1. 표지 (Cover) — S01
- 배경: `BLUE_DK` 풀블리드 + 우측 겹침 평행사변형 2매(`BLUE` 큰 것, `PURPLE` 작은 것)로 대각 에너지. **여기에 나노바나나 시공 예측 히어로 이미지(워터마크)를 우측 평행사변형 영역에 반투명 합성**(개발계획서 대비 상향 포인트, `visual_concepts.md` §표지 참조).
- 좌상: 원형 브랜드 마크(WHITE 원+PURPLE 코어) + "KINTEX · WISE AI" 15pt WHITE Bold.
- 문서종류 배지 2개: "기술제안서"(PURPLE) + "Technical Proposal"(딥블루).
- 대제목: 사업명 2줄 44pt WHITE Bold. 그 아래 슬로건 배너 강조.
- 하단 메타바: 사업명·기술스택·작성일 (라인 구분).
- **슬로건 각인**: "신청서를 내는 순간, 시공 후 사진을 먼저 본다." — 부제로 대형 배치.
### 4-2. 간지 (Section Divider) — 각 P1~P9 앞
- 배경: `BLUE_DK` 풀블리드 + 우측 평행사변형 2매(BLUE/PURPLE).
- 좌측: 대형 섹션 넘버 **150pt**(BLUE_DK보다 살짝 밝은 `#2C4E82` 음영톤) + PURPLE 언더바 + 국문 제목 34pt + 영문 13pt.
- 우측: 해당 섹션 핵심 포인트 3개(PURPLE 원 불릿 + WHITE 12.5pt).
- **배점 배지**: 간지 우상단에 해당 섹션 평가배점 배지(예 "P3 · 기술제안 35점")를 추가 — 배점 규율 시각화(개발계획서엔 없던 제안서 전용 요소).
### 4-3. 본문 (Content) — 표준
- `content_header(kicker, title, idx)`: 상단 액센트바(BLUE 0.12) + 섹션번호 칩(라운드, BLUE) + 킥커(PURPLE 11pt) + 제목(INK 22pt) + 구분선(1.28) + 푸터.
- 콘텐츠 영역: y 1.45~6.9. 카드/표/도식 배치.
- 하단 **캡션 1줄** 필수(도식 슬라이드) — MUTED 9pt, tech_advisory 각 도식 "캡션" 텍스트 그대로.
- REQ 배지(선택): 우상단에 해당 슬라이드 대응 REQ-ID 소형 배지(회색) — RTM 정합 가시화.
### 4-4. 도식 (Diagram) — 핵심 12종
- 본문 헤더 동일 + 콘텐츠 전체를 단일 도식에 할애.
- 도형은 **python-pptx 직접 작도**(외부 이미지 금지, 개발계획서 원칙 계승). 노드=ROUNDED_RECTANGLE, 연결=화살표 텍스트("→"/"›") 또는 얇은 라인 rect, 아이콘=본 시스템 SVG(단색 stroke, 슬라이드에선 도형 근사 또는 SVG를 EMF/PNG 없이 도형으로 재현).
- 각 도식 상세는 `visual_concepts.md`에 좌표·색·라벨 수준으로 명세.
---
## 5. 컴포넌트 스타일
| 컴포넌트 | 규칙 |
|---|---|
| **카드 (Card)** | ROUNDED_RECTANGLE, fill WHITE, line LINE 1pt, 그림자(alpha 18%, blur 90k, dist 38k). 헤더 있으면 상단 컬러 바(0.07~0.5) 또는 좌측 컬러 스트립(0.08~0.09). |
| **섹션 넘버 칩** | 0.62×0.62 라운드, BLUE(또는 PURPLE), WHITE 20pt Bold 중앙. |
| **배점 배지** | 라운드칩, fill=섹션색, WHITE 8~10pt Bold. "20점"/"35점" 등. 배점 큰 P3는 PURPLE 강조. |
| **상태 칩** | 라운드, 완료=GREEN·진행=AMBER·예정=SLATE·차단=RED. 텍스트+색 이중. |
| **불릿** | 작은 OVAL(0.09~0.11) 컬러 점 + 텍스트. 컬러=맥락색(블루/퍼플/상태). 이모지 불릿 금지 — **선 아이콘 또는 도형 점만**. |
| **콜아웃/배너** | 풀폭 라운드 rect, fill=BLUE(비전)/INK(권한구조)/PURPLE(AI강조), WHITE Bold 중앙. |
| **번호 배지** | 작은 OVAL, fill=색, WHITE 8pt Bold 숫자. 프로세스 스텝. |
| **프로세스 스텝** | 카드 나열 + 사이 화살표("›" 16pt SLATE). 좌→우 흐름. |
| **표 (Table)** | 헤더=BLUE 풀폭 라운드바 WHITE Bold, 본문 zebra(짝수행 `#FCFCFD`/HALL_BG), 행 구분 LINE 0.01, 셀 8.5~10pt. 강조행(낙찰 등)=BLUE_LT + Bold. |
| **아이콘** | 본 시스템 `assets/icons/*.svg` — 선(stroke) 스타일, 24×24, stroke-width 1.75, currentColor. 슬라이드 내 색=맥락색. |
---
## 6. 차트 스타일 (BI 도식 · S38·S39·S61)
- 라이브러리 톤: Recharts 목업 재현(막대·라인·도넛·KPI 카드).
- **시퀀셜(단일 계열)**: BLUE 계열 명도 그라데이션(#00447A→#0066B3→#4A90D9→#9CC3E8).
- **카테고리(다계열)**: BLUE / PURPLE / TEAL / AMBER / SLATE 순환(최대 5, 색맹 안전 순서). 6번째부터 명도 변주.
- **비교(Before/After·As-Is/To-Be)**: As-Is=SLATE(회색, 과거), To-Be=BLUE(현재/개선). 개선 화살표=PURPLE.
- **강조 수치**: 대형 Metric(26~46pt) + 단위 소형. KPI 카드는 BLUE/PURPLE 교차 fill + WHITE 수치.
- 축·그리드: SLATE 얇은 선, 라벨 8pt MUTED. 범례는 색+텍스트+마커 형태 병기.
- 도넛/파이: 최대 5조각, 나머지 "기타" 회색 통합. 중앙에 총계 수치.
---
## 7. 아이콘 시스템 (선 스타일 SVG — 직접 제작)
### 7-1. 공통 제작 규격 (전 20종 통일)
- **viewBox**: `0 0 24 24`
- **fill**: `none` (면 채움 절대 금지)
- **stroke**: `currentColor` (슬라이드에서 맥락색 상속)
- **stroke-width**: `1.75` (전 아이콘 동일 시각 무게)
- **stroke-linecap**: `round`, **stroke-linejoin**: `round`
- **그리드 정렬**: 24 그리드, 여백 2(콘텐츠 영역 2~22), 코너 반경 통일감.
- **외부 라이브러리·폰트아이콘·온라인 생성 금지** — 전량 직접 패스 작도.
- 한 세트 통일 메타포: 기하 단순·동일 디테일 밀도(오버피팅 금지).
### 7-2. 아이콘 20종 (최소 16종 요구 → 20종 제작)
| # | 파일명 | 의미 | 주 사용 슬라이드 |
|---|---|---|---|
| 1 | `ai-sparkle.svg` | AI/스파클/지능 | 나노바나나·AI 전 슬라이드·간지 |
| 2 | `booth-layout.svg` | 부스/레이아웃/배치 | M2 플로어플랜·모듈맵 |
| 3 | `wiring-power.svg` | 배선/전기/유틸리티 | M4 배선·아키텍처 |
| 4 | `camera-render.svg` | 카메라/렌더링/시각화 | 나노바나나 샷세트·표지 |
| 5 | `auction-gavel.svg` | 옥션/경매 망치 | M15 옥션 폐루프 |
| 6 | `visitor-badge.svg` | 관람객/배지 | M10 관람·등록 |
| 7 | `shield-security.svg` | 보안/방패 | P5 보안·불변원칙 |
| 8 | `watermark.svg` | 워터마크 | AI 이미지 보안·워터마크 |
| 9 | `tenant-building.svg` | 테넌트/전시관/빌딩 | 멀티테넌시·확장 |
| 10 | `schedule-gantt.svg` | 일정/간트 | P8 일정·마일스톤 |
| 11 | `org-people.svg` | 조직/사람 | 추진체계도·페르소나 |
| 12 | `check-verify.svg` | 체크/검증/규정 | 규정검증·QA·커버리지 |
| 13 | `dashboard-chart.svg` | 대시보드/차트/BI | M16 경영분석·기대효과 |
| 14 | `mobile.svg` | 모바일/반응형 | 현장·모바일·접근성 |
| 15 | `document-rtm.svg` | 문서/서류/RTM | M6 서류·RTM·커버리지 |
| 16 | `risk-warning.svg` | 리스크/경고 | 리스크 매트릭스·확인필요 |
| 17 | `postgis-spatial.svg` | 공간데이터/PostGIS/폴리곤 | 단일 공간원천·배선 |
| 18 | `pipeline-flow.svg` | 파이프라인/큐/비동기 | 나노바나나 파이프라인·아키텍처 |
| 19 | `network-zone.svg` | 망분리/보안영역 | 보안영역 분리도 |
| 20 | `closed-loop.svg` | 폐루프/순환 | 생애주기 폐루프·옥션 |
> 16종 요구 대비 **20종 제작**(공간데이터·파이프라인·망분리·폐루프 4종 추가 — 킨텍스 도식 핵심 메타포 보강).
### 7-3. deck-designer 아이콘 사용 지침
- python-pptx는 SVG 직접 임베드가 어려우므로, 각 아이콘은 **(a) 슬라이드 헤더/칩 옆 시각 앵커**로 쓸 때는 대응 도형(원+선) 근사 작도, **(b) 아이콘 자체가 콘텐츠일 때**는 SVG를 사전 PNG 변환(cairosvg/inkscape) 후 삽입 가능. 변환 시 stroke 색=맥락색으로 렌더.
- 색 상속: 아이콘 stroke는 배치 맥락색(블루=구조, 퍼플=AI, 상태색=상태)으로 지정.
---
## 8. deck-designer 전달 요약 (준수 계약)
1. **팔레트 상수**를 §1 표 그대로 코드 상단에 정의(개발계획서 `gen_dev_plan_pptx.py`와 동일 변수명 재사용 + PURPLE_DK·RED·CYAN·TEAL 추가).
2. **폰트** 맑은 고딕 전 run + East Asian 지정.
3. **레이아웃 4종**(§4) 헬퍼 함수화: `cover()`, `divider(no,kr,en,points,score)`, `content_header()`, 도식별 함수.
4. **12종 도식 + 표준 3종**(추진체계·리스크·기대효과)은 `visual_concepts.md` 좌표·라벨대로 작도. 재해석 금지.
5. **색 규율**: 퍼플=AI 전용, 배선 3색 고정(적/청/청록), 상태색 의미 고정.
6. **가독성 우선**: 본문 10pt 하한, 한 슬라이드 1메시지, 캡션 1줄, 여백 확보.
7. **보안**: 시크릿·내부IP 도식/라벨에 미기재. 외부 API는 "승인 예외"로만 표기.

342
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/g2b_standard_toc.md Normal file
View File

@ -0,0 +1,342 @@
# 나라장터(g2b) 정보시스템 구축 부문 — 표준 제안서 목차·평가배점 조사 및 킨텍스 제안서 재편 매핑
> 작성: rfp-analyst · 작성일: 2026-07-12 · 목적: 킨텍스 제안서(P1~P9, 63슬라이드) 목차 재편 근거
> 원칙: **확인된 1차 출처(법령·실제 RFP)만 사실로 기재**, 그 외는 [가정]/[통례] 표기. 시크릿 미기재.
> 대상 제안서 파일은 **읽기만**(수정 금지) — 본 문서는 매핑·권고만 산출.
> 짝 문서: `proposal_outline.md`(현행 P1~P9) · `rfp_analysis.md`(§4 배점 가정) · `tech_advisory.md`(§5 WBS·§6 SM) · `rtm.md`
---
## 0. 핵심 결론 (요약)
1. **표준 목차의 단일 출처**는 조달청 「협상에 의한 계약 제안서평가 세부기준」 **[별지 제5호서식] 제안서 서식(예시: 소프트웨어개발·유지관리사업)** — 7개 대장(Ⅰ 일반현황 ~ Ⅶ 그 밖의 사항)이다. 이 목차가 **평가부문 = 제안서 장(章)**으로 1:1 정렬된다.
2. **정성평가 평가항목의 단일 출처**는 같은 세부기준 **[별표 3의2] 소프트웨어 및 시스템 개발사업** — "정보시스템 구축"에 해당하는 표준 평가표. 부문: **전략 및 방법론 / 수행계획(기술·기능) / 수행기반 / 프로젝트 관리 / 프로젝트 지원 / 하도급 / 필수 제안**.
3. **배점은 세부기준이 고정하지 않는다.** 제9조⑤에 따라 **수요기관이 항목별 배점한도를 결정**(항목당 30점 초과 금지, 하도급 5점 이상, 국산제품 활용 2점 이내). 정보화사업 총 배점은 「행정기관·공공기관 정보시스템 구축·운영 지침」 **제18조**에 따라 **기술 90(정성 70 + 정량 20) / 가격 10**(원칙), HW 비중 50% 이상 사업은 **기술 80 / 가격 20** 허용.
4. **현행 킨텍스 제안서의 80/20 배점 가정(rfp_analysis §4)은 정보화 표준(90/10)과 다르다** — 실제 공고 확인 전까지 [가정]이며, SW 중심 사업이면 90/10이 표준. (본 문서는 지적만, proposal 파일 수정 없음.)
5. 현행 63슬라이드는 **표준 7대장에 전부 매핑 가능**하나, **신설이 필요한 장 4개**(Ⅰ 일반현황 / Ⅴ·Ⅵ 프로젝트 관리·지원 보강 / 상생협력·하도급 / 정량평가 대응)가 있다. 미배치 슬라이드 0.
---
## 1. 조달청 기술평가 표준 항목·배점 (출처·연도 명시)
### 1-1. 전체 배점 체계 (법령 확정 사실)
| 구분 | 배점 | 출처(조항) |
|---|---|---|
| 종합 = 기술능력평가 + 입찰가격평가 | 100 | 세부기준 제9조① |
| 기술능력평가 | **80점** (세부기준 원칙) / 정보화사업은 **90점**(지침 제18조) | 세부기준 제9조①1 · 지침 제18조 |
| 입찰가격평가 | 20점(원칙) / 정보화 10점 | 세부기준 제9조①2 |
| ─ 정성평가 | (기술 90 기준) **70점** | 실제 RFP 표본 §1 |
| ─ 정량평가 | **20점 이내**(총 배점한도) | 세부기준 제9조④ |
| HW 비중 50%↑ 예외 | 기술 80 / 가격 20 허용 | 지침 제18조 |
> **출처 정본**: 조달청 「협상에 의한 계약 제안서평가 세부기준」(조달청지침, 최신 개정 **2024. 9. 6. 시행**; 2017. 6. 1. 최초 시행). 정보화 총배점은 「행정기관 및 공공기관 정보시스템 구축·운영 지침」(행정안전부고시 제2024-66호, **2024. 8. 28. 시행**) 제18조.
### 1-2. 정성평가 표준 평가표 — [별표 3의2] 소프트웨어 및 시스템 개발사업 (정보시스템 구축 표준)
> **세부기준은 각 세부항목에 고정 점수를 부여하지 않는다**(수요기관이 배점한도 결정). 아래는 **평가항목 ↔ 세부평가항목 구조**(법령 원문 그대로). 배점 예시는 §1-3 실제 RFP 표본 참조.
| 평가항목(부문) | 세부평가항목 | 채점 관점(평가위원이 무엇을 보는가) |
|---|---|---|
| **전략 및 방법론** | 사업이해도 | 사업 목표·특성 부합, 구체성·적절성. (기획용역 ISP 수행자 참여 시 1등급 하향) |
| | 추진전략 | 수행 일정·위험요소 고려한 추진전략 타당성 |
| | 추진체계 | 수행조직(전문업체·기술지원·공동수급체·하도급) 역할·책임·품질확보·협력 방안 |
| | 사업추진방법론 | 방법론 구체성·적절성, 적용사례·경험, 단계별 산출물 제시 |
| **수행계획**(≈기술 및 기능) | 시스템 요구사항 | 장비 규격 충족·인터페이스·확장성·공급/설치·유지관리 |
| | 국산제품 활용 기여도 | 국산장비 도입방안 적절성·국내기업 지원 (배점 **2점 이내**, 국내입찰 한정) |
| | 기능 요구사항 | 기능·기대·제약 대비 구현방안 구체성·실현가능성 |
| | 성능 요구사항 | 성능충족 구현·테스트·방법론·분석도구 |
| | 인터페이스 요구사항 | 타 시스템 연계 방안·사용자 UI 분석/설계/구현/테스트 |
| | 유지관리 정책 | 제조사 유지관리(기간·비용·부품·보증) |
| **수행기반** | 적용기술 | 적용 기술의 확장·실현 가능성 |
| | 개발환경 | 장비·작업장소 등 인프라 준비·대응 |
| | 보안 요구사항 | 기술적 보안 구현(설계→구현→검증 단계 반영) |
| | 제약사항 | 기술·표준(**표준 프레임워크 적용 포함**)·언어·방법론·법제도·안전관리 제약 대응 |
| **프로젝트 관리** | 일정관리 | 수행기간·세부일정·단계별 산출물 연계 |
| | 품질관리 | 품질관리 범위·절차·점검, 품질보증 인증 근거 |
| | 기밀보안관리 | 물리적·관리적 보안 체계·대책 |
| | 위험 및 이슈 관리 | 위험·이슈 식별·분석·절차·대응 |
| **프로젝트 지원** | 인수인계 | 인계 전략·검사 대상/방법·충족조건·인계계획 |
| | 교육훈련 | 운영자·관리자·사용자 교육 내용·방법·기간·인원·횟수 |
| | 기술지원 | 지원 범위·수준·기술 매뉴얼 |
| | 하자보수 계획 | 하자담보 기간 내 하자보수 범위·조치절차·대응 |
| **하도급** | 하도급 계획의 적정성 | 하도급 금액/계약금액 비율 적정성 (배점 **5점 이상 필수**; **20억원 이상 SW사업은 제외 불가**) |
| **필수 제안** | (수요기관 지정) | 제안요청 필수사항 반영 여부 |
### 1-3. 정량평가 항목 (별표 8~14, 총 20점 이내)
| 정량 항목 | 출처 | 비고 |
|---|---|---|
| 경영상태 | 별표8 | 기업신용평가 |
| 수행실적 | 별표9 | 동일·유사 사업 실적 |
| 책임성·성실성 | 별표10 | |
| **상생협력** | **별표11** | 중소기업 공동수급체 참여 지분율 — 50%↑=5.0점 … 35%미만=1.0점 (**최대 5점**). 중소기업 단독=최고등급, 참여지분 0=0점 |
| 상용SW 유지관리 하도급금액 적정성 | 별표12 | |
| SW기술자료 임치 | 별표13 | |
| 정량 필수제안 | 별표14 | |
### 1-4. 실제 RFP 배점 표본 (구체 숫자 예시) — g2b R25BK00879799 (정보시스템 구축, HW 포함형, 30p 이내)
> 표본은 90/10(기술 90+가격 10) 채택. 부문 세분은 수요기관 재량임을 실증.
| 구분 | 평가항목 | 배점 |
|---|---|---|
| 정량(20) | 보유인력 5 · 경영상태 5 · 수행실적 5 · 사회적책임 3 · 지리적거리 2 | 20 |
| 정성(70) | 사업의 이해도(10) · 시스템 구성(20) · 시스템 기능(20) · 운영방안(10) · 사업관리 및 지원(10) | 70 |
| 가격(10) | 입찰가격평가 | 10 |
---
## 2. 정보시스템 부문 표준 제안서 목차 (장·절 구조)
### 2-1. 표준 목차 정본 — [별지 제5호서식] 제안서 서식(예시: 소프트웨어개발·유지관리사업)
> 출처: 세부기준 별지 제5호서식(법령 원문). **평가부문과 장 구조가 일치**하도록 설계됨. 각 절 옆은 대응 평가항목(별표 3의2).
```
Ⅰ. 일반현황
1. 입찰자 일반현황 (일반현황·주요 연혁·자본금·매출액)
2. 해당 사업의 수행조직 및 업무분장 → [정성] 추진체계 / [정량] 경영·실적
3. 해당 사업의 핵심투입인력 및 이력사항 → [정량] 보유인력
Ⅱ. 전략 및 방법론
1. 사업 이해도 → 전략및방법론·사업이해도
2. 추진전략 → 추진전략·추진체계
3. 적용기술 → 수행기반·적용기술
4. 표준 프레임워크 적용 → 수행기반·제약사항(표준FW)
5. 개발 방법론 → 사업추진방법론
Ⅲ. 기술 및 기능
1. 시스템 장비구성 요구사항 → 수행계획·시스템 요구사항
2. 기능 요구사항 → 수행계획·기능 요구사항
3. 보안 요구사항 → 수행기반·보안 요구사항
4. 데이터 요구사항 → (기능/데이터)
5. 시스템 운영 요구사항
6. 제약사항 → 수행기반·제약사항
Ⅳ. 성능 및 품질
1. 성능 요구사항 → 수행계획·성능 요구사항
2. 품질 요구사항 → 프로젝트관리·품질관리
3. 인터페이스 요구사항 → 수행계획·인터페이스 요구사항
4. 테스트 요구사항
Ⅴ. 프로젝트 관리
1. 관리방법론
2. 관리역량
3. 일정계획 → 프로젝트관리·일정관리
4. 개발장비
Ⅵ. 프로젝트 지원
1. 품질보증 → 프로젝트관리·품질관리
2. 시험운영
3. 교육훈련 → 프로젝트지원·교육훈련
4. 유지보수 → 프로젝트지원·기술지원/하자보수
5. 기밀보안 → 프로젝트관리·기밀보안관리
6. 비상대책
Ⅶ. 그 밖의 사항 → 기대효과·확장·상생협력 등
```
### 2-2. 실제 RFP 표본의 목차 요구 (간소형 예시) — g2b R25BK00879799 (30p 이내)
```
Ⅰ. 사업의 이해 : 과제수행목표·제안개요·제안사현황·추진체계및전략·제안의특징및장점
Ⅱ. 시스템 관련사항: 총괄시스템구성전략·기능별시스템구성및기능·성능구현 사전운영방안·향후활용방안
Ⅲ. 사업관리 및 지원: 사업관리(보고·일정·위험)·시스템지원방안(교육·기술지원·유지보수)
Ⅳ. 첨부자료
※ "발주처 요청 외 제안사가 중요하다고 판단한 목차·내용은 별도 기술하고 근거자료 첨부"
```
> **판독**: 소형·HW형 RFP는 별지 5호서식을 3~4장으로 압축한다. **대형 SW 구축**은 별지 5호서식 7대장을 그대로 쓰는 경향. 킨텍스 규모(전 전시 파이프라인)는 **7대장 채택 권장**.
### 2-3. 장별 "무엇을 담는가" (평가위원 채점 관점 요약)
| 장 | 담을 내용 | 채점 포인트 |
|---|---|---|
| Ⅰ 일반현황 | 제안사 개요·실적·재무, 수행조직도·R&R, 핵심인력 이력 | 정량(보유인력·경영·실적) 근거 + 조직 신뢰 |
| Ⅱ 전략·방법론 | 사업이해도, 추진전략/체계, 적용기술, 표준FW, 개발방법론 | "우리가 사업을 제대로 이해했고, 검증된 방법으로 한다"는 확신. **차별화(Win Theme) 메시지의 1차 노출 지점** |
| Ⅲ 기술·기능 | 요구기능 구현방안, 시스템 구성, 보안·데이터, 제약 대응 | 요구사항 대비 구현 구체성·실현가능성. **최다 배점 통례 → 기능 차별화 총력** |
| Ⅳ 성능·품질 | 성능충족·테스트, 품질보증, 인터페이스, 가용성/SLA | 정량 목표치·검증방법 제시 |
| Ⅴ 프로젝트 관리 | 관리방법론·역량, 일정계획, 위험·이슈, 품질관리 | 일정 준수·리스크 통제 실행력 |
| Ⅵ 프로젝트 지원 | 인수인계, 교육, 기술지원, **유지보수(SM)**, 기밀보안, 비상대책 | 구축 후 지속가능성·이관·운영 |
| Ⅶ 그 밖의 사항 | 기대효과, 확장, 상생협력·하도급, 부가제안 | 정성 가점·정책부합 |
---
## 3. 재편 매핑표 — 현행 킨텍스 P1~P9 (63슬라이드) → 표준 7대장
> 규칙: 각 슬라이드를 표준 장·절로 이동. **차별화(나노바나나·AI 폐루프)는 배점 높은 Ⅲ(기술·기능) + Ⅱ(전략·방법론) 접점에 배치**해 노출 극대화. 미배치 0.
### 3-1. 전면부 (표지·요약)
| 현행 | 표준 배치 | 비고 |
|---|---|---|
| S01 표지 | 표지 | 유지 |
| S02 제안 개요 | **Ⅰ 일반현황 §1 앞 or 제안개요 간지** | 제안사 소개는 Ⅰ으로 흡수 |
| S03 목차 | 목차 | 7대장 인덱스로 재구성 |
| S04 제안 핵심요약(3중 해자) | **Ⅱ 전략·방법론 §2 추진전략** 도입(요약 간지) | Win Theme 조기 각인 |
| S05 배점 대응 맵 | 목차 직후 간지 | 표준 배점(90/10)으로 갱신 권고 |
| S06 [가정] 고지 간지 | 부록 or 서두 노트 | 유지 |
### 3-2. P1 사업이해 → Ⅱ 전략·방법론 §1
| 현행 | 표준 배치 |
|---|---|
| S07 사업 배경·목적 | **Ⅱ §1 사업 이해도** |
| S08 As-Is 프로세스 병목 | **Ⅱ §1 사업 이해도** |
| S09 이해관계자·페르소나 | **Ⅱ §1 사업 이해도** |
| S10 To-Be 목표(정량) | **Ⅱ §1 사업 이해도** (→ 효과 지표는 Ⅶ와 연계) |
### 3-3. P2 추진전략 → Ⅱ 전략·방법론 §2·§5 + Ⅰ
| 현행 | 표준 배치 |
|---|---|
| S11 비전·포지셔닝 | **Ⅱ §2 추진전략** |
| S12 3중 해자 전략 | **Ⅱ §2 추진전략** (차별화 앵커) |
| S13 Win Theme 5선 | **Ⅱ §2 추진전략** (배점 정렬 배지 병기) |
| S14 전시 생애주기 폐루프 | **Ⅱ §5 개발 방법론**(생애주기 방법론) |
| S15 추진체계·수행조직 | **Ⅰ 일반현황 §2 수행조직·업무분장** (+ Ⅱ §2 추진체계 교차) |
### 3-4. P3 기술제안 (25슬라이드) → Ⅲ 기술·기능 중심 + Ⅱ 적용기술 + Ⅳ 일부
> **핵심 전략**: 나노바나나·AI 폐루프는 **Ⅱ §3 적용기술**(방법론·차별화 관점)과 **Ⅲ §2 기능 요구사항**(구현 관점) **두 장에 걸쳐 노출** → 전략및방법론·기술및기능 양쪽 배점 동시 획득.
| 현행 | 표준 배치 |
|---|---|
| S16 전체 모듈맵 | **Ⅲ 기술·기능 도입부**(기능 조망) |
| **S17~S23 나노바나나 시공예측(7)** | **Ⅱ §3 적용기술**(S17 개요·S19 구조보존·S20 파이프라인·S23 AI신뢰) + **Ⅲ §2 기능 요구사항**(S18 샷세트·S21 Before/After·S22 RenderJob 방어). **7슬라이드 절대 유지** |
| S24 플로어플랜 스튜디오(M2) | **Ⅲ §2 기능 요구사항** (+ 적용기술 교차) |
| S25 배치 규정 자동검증 | **Ⅲ §2 기능 요구사항** |
| S26 부스 설계 스튜디오(M3) | **Ⅲ §2 기능 요구사항** |
| S27 유틸리티 설계(M4)·PostGIS 배선 | **Ⅲ §2 기능 요구사항** (+ Ⅲ §4 데이터 요구사항 교차) |
| S28 위치표시도·유틸리티 신청 | **Ⅲ §2 기능 요구사항** |
| S29 옥션 개요·폐루프 | **Ⅲ §2 기능 요구사항** (차별화 폐루프) |
| S30 역경매·실시간 순위 | **Ⅲ §2 기능 요구사항** |
| S31 종합평가 낙찰 | **Ⅲ §2 기능 요구사항** |
| S32 등록 게이트·발주 전환 | **Ⅲ §2 기능 요구사항** (+ Ⅲ §3 보안 교차) |
| S33 판매·홀배정·견적(M1) | **Ⅲ §2 기능 요구사항** |
| S34 서류·마일스톤(M6) | **Ⅲ §2 기능 요구사항** (+ Ⅲ §5 시스템 운영 교차) |
| S35 관람객 등록·배지·리드(M10) | **Ⅲ §2 기능 요구사항** |
| S36 비즈매칭·마케팅·공개사이트(M11·12·17) | **Ⅲ §2 기능 요구사항** |
| S37 정산·결제(M9) | **Ⅲ §2 기능 요구사항** |
| S38 경영분석 BI-1(M16) | **Ⅲ §2 기능 요구사항** (+ Ⅲ §4 데이터 교차) |
| S39 경영분석 BI-2(M16) | **Ⅲ §2 기능 요구사항** |
| S40 현장운영·물류(M8·13·14) | **Ⅲ §2 기능 요구사항** |
### 3-5. P4 아키텍처 → Ⅱ §3·§4 + Ⅲ §1·§4·§5
| 현행 | 표준 배치 |
|---|---|
| S41 전체 아키텍처 | **Ⅲ §1 시스템 장비구성 요구사항** (+ Ⅱ §3 적용기술) |
| S42 단일 공간 데이터 원천(PostGIS) | **Ⅲ §4 데이터 요구사항** |
| S43 확장성·비동기 | **Ⅳ §1 성능 요구사항** (+ Ⅶ 확장 연계) |
| S44 AI 플랫폼 라우팅(Claude→Ollama) | **Ⅱ §3 적용기술** |
| S45 연동·마스터데이터 | **Ⅳ §3 인터페이스 요구사항** (+ Ⅲ §5 시스템 운영) |
### 3-6. P5 보안·개인정보 → Ⅲ §3 + Ⅴ·Ⅵ 기밀보안
> 표준은 **기술적 보안 = Ⅲ §3 보안 요구사항**, **관리적 기밀보안 = Ⅴ 기밀보안관리 / Ⅵ §5 기밀보안**으로 분리. 현행 P5를 분할 배치.
| 현행 | 표준 배치 |
|---|---|
| S46 보안 개요·불변 원칙 | **Ⅲ §3 보안 요구사항** (개요) |
| S47 보안영역 분리(망 구성) | **Ⅲ §3 보안 요구사항** (+ Ⅲ §1 구성) |
| S48 인증·접근통제(2FA·RBAC) | **Ⅲ §3 보안 요구사항** |
| S49 AI·이미지 보안(워터마크) | **Ⅲ §3 보안 요구사항** (차별화 보안) |
| S50 개인정보·감사·안전코딩 | **Ⅲ §3 보안 요구사항** + **Ⅴ §? 기밀보안관리 / Ⅵ §5 기밀보안** (관리적 요소 이관) |
### 3-7. P6 비기능 → Ⅳ 성능·품질
| 현행 | 표준 배치 |
|---|---|
| S51 성능·가용성 SLA | **Ⅳ §1 성능 요구사항** |
| S52 나노바나나 성능 | **Ⅳ §1 성능 요구사항** |
| S53 접근성·다국어·테마·반응형 | **Ⅳ §2 품질 요구사항** |
| S54 관측성·데이터 | **Ⅳ §2 품질 요구사항** (+ Ⅴ 관리 연계) |
### 3-8. P7 멀티테넌시·확장 → Ⅲ §5 + Ⅶ
| 현행 | 표준 배치 |
|---|---|
| S55 멀티테넌트 SaaS 비전 | **Ⅶ 그 밖의 사항**(확장 비전) |
| S56 테넌트 격리 아키텍처 | **Ⅲ §5 시스템 운영 요구사항** (+ Ⅲ §3 보안 격리) |
| S57 온보딩·2계층 관리자 | **Ⅲ §5 시스템 운영 요구사항** |
### 3-9. P8 사업관리·일정·조직 → Ⅴ 프로젝트 관리 + Ⅵ
| 현행 | 표준 배치 |
|---|---|
| S58 추진 일정·Phase | **Ⅴ §3 일정계획** |
| S59 선행 게이트·리스크 관리 | **Ⅴ §1 관리방법론 / 위험·이슈 관리** |
| S60 품질·형상관리 | **Ⅴ §2 관리역량(품질관리)** + **Ⅵ §1 품질보증** |
### 3-10. P9 기대효과 → Ⅶ 그 밖의 사항
| 현행 | 표준 배치 |
|---|---|
| S61 정량 기대효과 | **Ⅶ 그 밖의 사항** |
| S62 정성·전략 효과 | **Ⅶ 그 밖의 사항** |
| S63 확장 비전·마무리 | **Ⅶ 그 밖의 사항** |
### 3-11. 매핑 커버리지 요약
| 표준 장 | 배치된 현행 슬라이드 | 소계 |
|---|---|---|
| 표지·목차 | S01·S03·S05·S06 | 4 |
| Ⅰ 일반현황 | S02·S15 (+ **신설 필요**) | 2 |
| Ⅱ 전략·방법론 | S04·S07~S14·S17·S19·S20·S23·S41(교차)·S44 | 14 |
| Ⅲ 기술·기능 | S16·S18·S21·S22·S24~S40·S42·S45(교차)·S46~S50·S56·S57 | 34 |
| Ⅳ 성능·품질 | S43·S51~S54 | 5 |
| Ⅴ 프로젝트 관리 | S58·S59·S60 | 3 |
| Ⅵ 프로젝트 지원 | S50(관리적 일부)·S60(품질보증) (+ **대폭 신설 필요**) | ~1 |
| Ⅶ 그 밖의 사항 | S55·S61·S62·S63 | 4 |
| **미배치** | — | **0** |
---
## 4. 표준 목차 채택 시 신설 필요 장(章)과 내용 소스
> 현행 63슬라이드가 **표준 대비 취약하거나 부재**한 영역. 실제 공고 시 감점·실격 방지를 위해 신설.
| 신설/보강 대상 | 이유 | 내용 소스(지목) |
|---|---|---|
| **Ⅰ 일반현황 (신설)** | 제안사 일반현황·연혁·자본금·매출, 수행조직도·R&R, **핵심투입인력 이력**은 정량평가(보유인력·경영·실적) 근거. 현행에 사실상 부재(S02·S15 부분). | `tech_advisory §5-2` 직군별 M/M 산정 → 투입인력표. 제안사 실적은 발주 확인 후 확보(⚠확인필요) |
| **Ⅵ 프로젝트 지원 (대폭 신설)** | 인수인계·교육훈련·기술지원·**유지보수(SM)**·비상대책은 표준 정성 부문. 현행 P8이 품질/형상만 얇게 다룸. | `tech_advisory §6 SM 운영 체계`(SLA·장애대응·정기점검·CI/CD 운영·ITSM 프로세스·조직 R&R §6-1) · §5-1 WBS(SM 이관·인수인계) |
| **Ⅴ 프로젝트 관리 보강** | 표준은 관리방법론·관리역량·위험/이슈를 독립 부문으로 배점. 현행 배점 2점 가정으로 과소. | `tech_advisory §5 WBS·공수` · `proposal_strategy §4 리스크` |
| **상생협력·하도급 (신설)** | 정량 별표11(중소기업 참여지분율, 최대 5점)·정성 하도급 계획 적정성(5점 이상). **20억↑ SW사업은 하도급 평가 제외 불가**. 현행 없음. | 공동수급/중소기업 참여 계획·하도급 계획서(별지 제14호서식) — 컨소시엄 구성 확정 후(⚠확인필요) |
| **정량평가 대응 절 (신설)** | 보유인력·경영상태·수행실적·사회적책임은 필수 증빙 미제출 시 최하점. 별첨 근거 필요. | Ⅰ 일반현황 + 별첨(증빙) — 발주 확인 후 |
| **표준 프레임워크 적용 절 (Ⅱ §4)** | 별표3의2 제약사항에 "표준 프레임워크 적용 포함" 명시. 공공 SW 필수 관점. | 확정 스택(Spring Boot/React) — 전자정부 표준FW 적용 여부는 ⚠확인필요(현재 스택은 GUARDiA 표준) |
---
## 5. 재편 권고 (Win Theme 노출 극대화)
1. **7대장 채택**: 킨텍스 규모(전 전시 생애주기)는 별지 5호서식 7대장 구조가 정합. 현행 P1~P9를 §3 매핑대로 재배열.
2. **나노바나나(S17~S23) 이중 노출**: Ⅱ §3 적용기술(방법론·차별화)과 Ⅲ §2 기능 요구사항(구현) 양쪽에 배치 → **전략및방법론 + 기술및기능 배점 동시 겨냥**. 7슬라이드 축소 금지.
3. **AI 폐루프(배치·설계·배선·옥션 S24~S32)**: Ⅲ §2 기능 요구사항에 집중 배치(최다 배점 장). 폐루프 차별화 메시지를 기능 채점표에 직접 정렬.
4. **보안 분할**: 기술적 보안 → Ⅲ §3, 관리적 기밀보안 → Ⅴ·Ⅵ. 표준 채점 구조에 맞춰 배점 누수 방지.
5. **Ⅵ 프로젝트 지원 신설**로 "구축 후 지속가능성"(SM·교육·이관) 확보 — 공공 평가위원 필수 확인 항목.
6. **배점 표기 갱신**: 현행 80/20 가정 → 정보화 표준 90/10(정성70+정량20)로 갱신 권고(실제 공고 확인 시 확정). *proposal 파일 수정은 별도 지시 필요 — 본 문서는 근거만 제공.*
---
## 6. 출처 URL 전체 목록
**1차 출처 (법령·실제 문서 — 본문 근거)**
- 조달청 협상에 의한 계약 제안서평가 세부기준 (국가법령정보센터): https://law.go.kr/LSW/admRulLsInfoP.do?admRulSeq=2100000088849
- 조달청 협상에 의한 계약 제안서평가 세부기준 PDF (별표3의2·별표11·별지5호서식 원문 추출): https://bidform.co.kr/updata/notifile/ab689c32028cee2185e44dcd24c0fb89.pdf
- 실제 나라장터 정보시스템 구축 RFP 제안서 작성요령(배점·목차 표본, g2b R25BK00879799): https://www.g2b.go.kr/pn/pnp/pnpe/UntyAtchFile/downloadFile.do?bidPbancNo=R25BK00879799&bidPbancOrd=000&fileType=&fileSeq=3
- 행정기관 및 공공기관 정보시스템 구축·운영 지침 제18조(평가배점) (국가법령정보센터): https://www.law.go.kr/LSW//admRulInfoP.do?admRulSeq=2100000246404&chrClsCd=010201
- 정보시스템 구축·운영 지침 제18조(평가배점) — 국민건강보험공단 법령DB: https://www.nhis.or.kr/lm/lmxsrv/law/joHistoryContent.do?SEQ=1541&SEQ_CONTENTS=4250027&DATE_START=20240828&DATE_END=20190823
**참고 출처 (통례·가이드)**
- KOSA 소프트웨어 사업 가이드북 v3.0: https://www.sw.or.kr/upload/common/027d281c-2a7a-4886-b96b-e9ad04c7a309.pdf
- 공공 SW사업 제안요청서 작성 예시(SW 법제도 반영): https://smallake.kr/wp-content/uploads/2023/03/붙임공공SW사업-제안요청서-작성-예시.pdf
- NIPA SW사업 단계별 발주 가이드: https://www.nipa.kr/home/2-7-1-1/7089
- 조달청 협상에 의한 계약 제안서평가 세부기준(2026.1.26. 시행 안내, 도로교통공단): https://www.koroad.or.kr/main/board/22/305400/board_view.do
---
## 7. 확인 필요 (삭제 금지)
| # | 항목 | 사유 |
|---|---|---|
| T1 | 실제 킨텍스 공고의 배점·목차 강제 여부 | 본 문서는 표준·표본 근거. 실제 공고가 별지 5호서식과 다른 목차를 강제할 수 있음 |
| T2 | 정보화(SW중심) vs HW중심 판정 | 90/10 vs 80/20 결정. 킨텍스 시스템은 SW 중심 → 90/10 추정, 공고 확인 필요 |
| T3 | 컨소시엄·중소기업 참여·하도급 구성 | 상생협력(별표11)·하도급(별표3의2) 대응은 컨소시엄 확정 후 작성 |
| T4 | 전자정부 표준프레임워크 적용 요구 여부 | 별표3의2 제약사항에 표준FW 명시 — 현행 스택(GUARDiA 표준)과 정합성 공고 확인 |
| T5 | 사업금액 20억원 이상 여부 | 20억↑이면 하도급 평가항목 제외 불가(세부기준 제9조⑤ 단서) |

998
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/proposal_content.md Normal file
View File

@ -0,0 +1,998 @@
# 킨텍스 자동전시시스템 구축 — 제안서 본문 (Proposal Content · 슬라이드 단위)
> 작성: proposal-writer · 작성일: 2026-07-11 · 버전 v1.0
> 입력: `proposal_outline.md`(63슬라이드 배점 가중 목차) · `proposal_strategy.md`(Win Theme 5·리스크 R-1~R-8) · `tech_advisory.md`(§0 라이브 실적/구현 계획 구분·도식 12종 사양·NFR 21·보안 20·공수 ~150M/M·SM) · `rfp_analysis.md`+`rtm.md`(REQ 142)
> 산출 규격: 슬라이드별 [번호·섹션·헤드라인(3초 메시지)·본문 불릿(근거)·도표 지시(tech_advisory 도식 ID)·대응 REQ·출처]. 문체 = **주장 → 근거(라이브 실적/설계 문서) → 효과**. 과장 금지 — tech_advisory §0 구분표에 따라 **[검증됨]**(구축 완료·라이브)과 **[구현 계획]**(설계 확정·미완)을 표기 라벨로 명확 구분.
> 보안 불변: 시크릿(키·비번·IP·SSH) 미기재. AI 생성 이미지는 워터마크·고지 정책 명시.
> deck-designer 지침: 도식 지시의 "도식ID"는 `tech_advisory.md §1-4`의 번호(①~⑫)와 1:1. 아이콘 전량 선(stroke) SVG.
---
## 표기 범례 (전 슬라이드 공통)
- **[검증됨]** = WORK_STATUS(2026-07-11) 라이브 확인분. "이미 기동 중".
- **[구현 계획]** = 설계·데이터모델 확정, 구현 대기. "표준대로 채운다".
- **[협의]** = 발주처 협의·확인 필요(⚠) 항목. 정직 고지 대상.
- **REQ** 열 = 해당 슬라이드가 충족하는 요구사항 ID(RTM 반영 근거).
---
# 0. 표지·목차 (S01~S06)
## S01 · 표지
- **섹션**: 표지
- **헤드라인**: **"신청서를 내는 순간, 시공 후 사진을 먼저 본다."**
- **본문**
- 사업명: 킨텍스(KINTEX) 자동전시시스템 구축
- 서브 슬로건: "설계 → 시각화 → 발주 → 시공 → 운영 → 분석. 킨텍스에서 한 흐름으로 끝난다."
- 제안사·제안일 표기 영역(로고 자리)
- **도표 지시**: 배경 = 나노바나나 시공 예측 히어로 이미지(Before 빈 부스 → After 시공 사진). **워터마크 항상 표기**("AI 생성 예상 이미지 — 실제 시공과 다를 수 있음. 계약·심사 서류 사용 금지"). 도식ID 없음(히어로).
- **REQ**: REQ-A-001, REQ-S-009
- **출처**: strategy §0, PLANNING §1-2
## S02 · 제안 개요
- **섹션**: 표지
- **헤드라인**: "우리는 도면이 아니라 사진으로 컨펌하고, 그 사진으로 발주까지 종결한다."
- **본문**
- 우리는 누구: GUARDiA 표준 프레임워크(WISE/UIWS) 검증 자산 위에 전시 도메인 코어를 얹은 팀
- 왜 우리인가: ①나노바나나 시공 예측 ②PostGIS 실측 공간데이터 ③공사 옥션 폐루프 — **세 결합을 이미 라이브로 검증** [검증됨]
- 차별점 1줄: "말이 아니라 이미 돈다" — 인프라·인증·PostGIS 코어·나노바나나·자동배포가 기동 중
- **도표 지시**: 제안사 핵심 자산 아이콘 3종(선 SVG) — 시공예측·공간데이터·옥션폐루프.
- **REQ**: REQ-A-001, REQ-N-008, REQ-F-025
- **출처**: tech_advisory §0-1, strategy §0
## S03 · 목차
- **섹션**: 표지
- **헤드라인**: "배점을 따라 읽으십시오 — 제안서 무게가 곧 배점 배분입니다."
- **본문**
- P1 사업이해 · P2 추진전략 · P3 기술제안 · P4 아키텍처 · P5 보안·개인정보 · P6 비기능 · P7 멀티테넌시·확장 · P8 사업관리·일정·조직 · P9 기대효과
- P3(기술제안)이 전체 25슬라이드(≈40%) — 배점 35점 정렬
- **도표 지시**: 목차 인덱스(9섹션) + 각 섹션 배점 배지 병기. 도식ID 없음.
- **REQ**: (내비게이션 — 개별 REQ 없음)
- **출처**: outline 배분 총괄표
## S04 · 제안 핵심 요약(1p)
- **섹션**: 표지
- **헤드라인**: "단일 요소는 모방할 수 있으나, 세 결합은 재현하기 어렵다 — 우리만의 해자."
- **본문**
- Win Theme 5선: WT-1 시공 예측 · WT-2 배치·설계·배선 3안+규정검증 · WT-3 옥션 폐루프 · WT-4 보안 3중 격리 · WT-5 멀티테넌트 SaaS
- 3중 해자: 나노바나나 시공 예측 ∩ PostGIS 실측 공간데이터 ∩ 공사 옥션 폐루프
- 배점의 44%(35/80)가 P3에 집중 → 제안 무게 집중 근거
- **도표 지시**: **도식① 3중 해자 벤다이어그램**(3원 60% 겹침, 중앙 교집합 "재현 난이도 높은 결합 = 우리만의 해자(Moat)"). tech_advisory §1-4 ①.
- **REQ**: REQ-A-001·002, REQ-N-008·017, REQ-F-025
- **출처**: strategy §3-3, tech_advisory §1-4 ①
## S05 · 배점 대응 맵
- **섹션**: 표지
- **헤드라인**: "우리 제안은 배점이 큰 곳에 정확히 무게를 실었다."
- **본문**
- AI 시각화·설계(핵심) 20점 → WT-1·WT-2 전면(P3 나노바나나 7슬라이드+배치·설계·배선 5슬라이드)
- 기능 구현 15점 → 모듈맵 1장 조망 + 옥션·관람·BI 상세
- 아키텍처 10·보안 10·비기능 8·사업이해·전략 10·멀티테넌시 5·사업관리 2
- **도표 지시**: 배점-섹션 정렬 매트릭스(80점 히트맵). 도식ID 없음(인포그래픽).
- **REQ**: (배점 정렬 — 전 REQ 계열 조망)
- **출처**: strategy §2, outline 배분 총괄
## S06 · [가정] 고지 간지
- **섹션**: 표지
- **헤드라인**: "가정은 숨기지 않고 드러냅니다 — 실제 공고 확인 시 즉시 재정렬합니다."
- **본문**
- 실제 RFP 부재 → 평가배점·제출규격은 공공 SI 통례 기준 **[가정]** (리스크 R-4 정면 방어)
- 목차는 안전 정렬(사업이해→전략→기술→아키→보안→비기능→확장→관리→기대효과)
- 확인 필요 8항목(C1~C8)은 부록 A에 집약 → 정직성을 강점화
- **도표 지시**: 간단 노트 카드(리스크 R-4 방어 문구). 도식ID 없음.
- **REQ**: (투명 고지 — 개별 REQ 없음)
- **출처**: strategy §4 R-4, rfp_analysis §4·§5
---
# P1. 사업이해 (S07~S10)
## S07 · 사업 배경·목적
- **섹션**: P1 사업이해
- **헤드라인**: "108,011㎡의 아시아 3위 전시장, 준비는 여전히 HWP·CAD 수작업이다."
- **본문**
- 킨텍스 규모: 현 108,011㎡ → 2028년 제3전시장 완공 시 178,000㎡(국내 최대·아시아권 상위)
- 현행 병목: 부스 배치는 CAD 외주 수작업, 신고서류는 HWP 수기, 배선·위치표시도 육안 작도
- 목적: 전시 준비 전 과정을 AI로 자동화해 리드타임·오류·외주비용을 동시 절감
- **도표 지시**: 킨텍스 규모 인포그래픽(면적·홀 수·연간 행사 규모 지표 카드). 도식ID 없음.
- **REQ**: (사업 맥락 — 개별 REQ 없음)
- **출처**: PLANNING §1-1
## S08 · As-Is 프로세스 병목
- **섹션**: P1 사업이해
- **헤드라인**: "D-150부터 D-7까지, 마디마다 사람이 기다리고 CAD를 외주한다."
- **본문**
- D-150 판매·견적: 견적 산출을 담당자가 수기 회신 → 대기 발생
- D-30 배치·설계: CAD 외주 수일~수주, 규정 위반은 홀매니저 육안 검수 병목
- D-25 유틸리티: 전기·네트워크·급배수 신청이 개별 채널로 파편화
- D-7 제출·검수: kxwp 제출·서류 육안 검토
- **도표 지시**: **As-Is 타임라인 다이어그램**(D-데이별 Pain Point 표시). 도식ID 없음(표준 타임라인).
- **REQ**: (병목 진단 — 개별 REQ 없음, To-Be 근거)
- **출처**: PLANNING §3-1·3-2
## S09 · 이해관계자·페르소나
- **섹션**: P1 사업이해
- **헤드라인**: "6역할+2관리자, 각자의 과업·고통·기대를 정확히 안다."
- **본문**
- 주최자(organizer): 배치·행사 총괄 — CAD 수작업 고통
- 참가업체(exhibitor): 도면을 못 읽어 개장일에 결과 첫 대면 — 시공 예측 니즈
- 공사·장치업체(contractor): 리스트+엑셀 매칭, 견적 비교 부재
- 홀매니저(ops): 규정 육안 검수 병목
- 관람객(visitor): 등록·배지·현장 체크인
- 일반 대중(public): 공개 홍보·플로어플랜 열람
- +플랫폼 관리자·테넌트 관리자
- **도표 지시**: 페르소나 카드 6종(과업·Pain·기대 3행). 도식ID 없음.
- **REQ**: REQ-F-081(역할별 포털의 근거)
- **출처**: PLANNING §2
## S10 · To-Be 목표(정량)
- **섹션**: P1 사업이해
- **헤드라인**: "견적은 즉시, 배치는 수 분, 검수는 자동, 결과는 사진으로."
- **본문**
- 견적: 수일 대기 → **즉시**(규칙엔진 2,250원/㎡ 자동 계산)
- 배치: 수주 CAD 외주 → **수 분 3안 자동생성**
- 규정 검수: 육안 → **제출 전 자동 플래깅**
- 위치표시도: 수기 작도 → **좌표 클릭 자동 작도**
- 시공 결과: 개장일 첫 대면 → **신청 시점 사진 예측**
- **도표 지시**: As-Is→To-Be 대비표(정량 개선 5행). 도식ID 없음(표).
- **REQ**: REQ-F-002, REQ-F-007, REQ-F-009, REQ-F-017, REQ-A-001
- **출처**: PLANNING §1-3
---
# P2. 추진전략 (S11~S15)
## S11 · 비전·포지셔닝
- **섹션**: P2 추진전략
- **헤드라인**: "도면과 표를 보여주는 전시테크가 아니라, 사진으로 컨펌하는 베뉴 운영 플랫폼."
- **본문**
- 기존 전시테크는 도면·3D 뷰어 수준 → 우리는 **사진급 시공 예측**으로 의사결정
- 단일 폐루프: 설계 자료가 곧 발주 근거 → 발주까지 한 흐름에서 종결
- 데이터 주권: 온프레미스 Ollama 기본, 외부 AI는 승인 예외만
- **도표 지시**: 비전 슬로건 대형 타이포. 도식ID 없음.
- **REQ**: (포지셔닝 — 개별 REQ 없음)
- **출처**: PLANNING §1-2, strategy §0
## S12 · 3중 해자 전략
- **섹션**: P2 추진전략
- **헤드라인**: "셋 중 하나는 흉내낼 수 있어도, 셋의 결합은 재현 난이도가 높다."
- **본문**
- 원A 나노바나나 시공 예측: image-to-image 구조보존·40초·S1~S7 [검증됨: G1 승인·워커 라이브]
- 원B PostGIS 실측 공간데이터: 부스 폴리곤·트렌치 포인트·배선 LineString 단일 원천 [검증됨: M2~M5 매퍼 라이브]
- 원C 공사 옥션 폐루프: AI 자료→응찰→낙찰→발주 자동전환 [구현 계획: Phase D]
- **도표 지시**: **도식① 3중 해자 벤다이어그램**(S04와 동일·상세 재강조). tech_advisory §1-4 ①.
- **REQ**: REQ-A-001·002, REQ-N-008·017, REQ-F-025·032
- **출처**: strategy §3-3, tech_advisory §0-1·§1-4 ①
## S13 · Win Theme 5선
- **섹션**: P2 추진전략
- **헤드라인**: "다섯 개의 차별화 메시지가 배점 다섯 곳을 정확히 겨눈다."
- **본문**
- WT-1 "도면이 아니라 사진으로 컨펌한다" — 배점 20(AI 시각화 핵심)
- WT-2 "수 분 내 3안, 제출 전 규정 자동검증" — 배점 20+15 교차
- WT-3 "사진 수준 자료로 응찰하고 발주까지 끝낸다" — 배점 15(폐루프)
- WT-4 "AI가 만든 것은 표시하고, 남의 데이터는 차단한다" — 배점 10(보안)
- WT-5 "코드 배포 없이 데이터 온보딩만으로 새 전시관을 연다" — 배점 5(확장)
- **도표 지시**: Win Theme 5카드(각 카드에 배점 배지). 도식ID 없음.
- **REQ**: REQ-A-001, REQ-F-007·025, REQ-S-009·018, REQ-F-077
- **출처**: strategy §1
## S14 · 전시 생애주기 폐루프
- **섹션**: P2 추진전략
- **헤드라인**: "설계 → 시각화 → 발주 → 시공 → 운영 → 분석이 하나의 순환으로 닫힌다."
- **본문**
- 판매·기획(M1) → 설계·시각화(M2~M5) → 발주·계약(M15·M6·M9) → 참가·관람(M10·M11) → 현장운영(M8·M13·M14) → 사후·경영(M16)
- 각 단계 산출물이 다음 단계 입력 → 재입력·중복 작업 제거
- 분석(M16)이 다음 행사 기획(M1)으로 환류
- **도표 지시**: 생애주기 폐루프 순환도(M모듈 매핑). 도식ID 없음(순환도).
- **REQ**: (생애주기 조망 — 상세 REQ는 P3에서 반영)
- **출처**: PLANNING §1-2-1
## S15 · 추진체계·수행조직
- **섹션**: P2 추진전략
- **헤드라인**: "거버넌스·아키텍트·코어·도메인·AI·QA·DevOps가 게이트로 맞물린다."
- **본문**
- 거버넌스: 총괄 PM · PMO · 개발 PM
- 아키텍트 풀: AA · SA · TA · DA · NA(5종 아키텍처 확정 완료)
- 실행: 공통·코어(백엔드·프론트·DB) · 도메인(옥션·관람·CMS·BI·관리자) · AI·시각화 · QA · DevOps
- 게이트: 선행 게이트(G1·G2) + Phase 게이트 QA 통과
- **도표 지시**: **추진체계도(조직도)** — 거버넌스+아키텍트+실행팀 계층. tech_advisory §1-4 말미(추가 표준 도식).
- **REQ**: REQ-N-004(품질 게이트)
- **출처**: 하네스 팀 구성, tech_advisory §5-1
---
# P3. 기술제안 (S16~S40, 25슬라이드 · 배점 35 · 최다 집중)
## P3-A. 모듈 조망
## S16 · 전체 모듈맵
- **섹션**: P3 기술제안
- **헤드라인**: "18개 모듈+공통 레이어를 한 장으로 조망 — P0 코어 4개가 심장이다."
- **본문**
- P0 코어(강조): M2 플로어플랜·M3 부스설계·M4 유틸리티·M5 나노바나나
- P1 도메인: M1 판매·M6 서류·M7 등록·M9 정산·M15 옥션·M10 관람·M12/M17 CMS·M16 BI·M18 관리자
- P2 확장: M8 물류·M11 비즈매칭·M13 wayfinding·M14 현장 IoT
- **공통/시스템관리 레이어(§5B) — 전 모듈 선행 기반** [검증됨: WISE 이식 Flyway V1~V9]: 공통코드·메뉴(F-073), 공통 업무모듈 일지·일정·쪽지·공지·검색(F-074), 회의록 STT·업무보고 통계 PDF(F-075), 통합 알림센터 WebSocket(F-076)
- 멀티테넌시(§1A): tenant_id 격리 기반 [구현 계획]
- 100대 기능 성숙도: 기구현 63·부분 18·신규 19(정량)
- **도표 지시**: **도식② 모듈맵(생애주기 6단계 × 우선순위 P0/P1/P2 매트릭스)** + 하단 공통 레이어 띠. tech_advisory §1-4 ②.
- **REQ**: REQ-F-073·074·075·076, 전 모듈 조망
- **출처**: rfp_analysis §2-1, tech_advisory §1-4 ②·§0
## P3-B. 나노바나나 시공 예측 — WT-1 (S17~S23, 7슬라이드 · 축소 금지)
## S17 · 나노바나나 개요
- **섹션**: P3 기술제안(WT-1)
- **헤드라인**: "시공 전에 사진으로 의사결정한다 — 경쟁 전시테크가 못 하는 차별화."
- **본문**
- 문제: 참가업체는 도면을 못 읽어 개장일에야 결과를 처음 본다(PLANNING §2)
- 해법: image-to-image로 빈 부스(도면/실측)를 시공 후 사진으로 예측
- 실증: Gemini 라이브(G1 소유자 승인 완료), `gemini-3.1-flash-image-preview` 워커 상주 [검증됨]
- 효과: 조감도 외주(비용·시간) 대체, 신청 시점 의사결정
- **도표 지시**: 히어로 Before/After 실물(워터마크 표기). 도식ID 없음(히어로).
- **REQ**: REQ-A-001
- **출처**: strategy §1 WT-1, tech_advisory §0-1·§2 WT-1
## S18 · 표준 샷세트 S1~S7
- **섹션**: P3 기술제안(WT-1)
- **헤드라인**: "정면·야간·통로·내부·Before/After·배선·홀전경 — 7컷을 평균 40초에."
- **본문**
- S1 정면 부스 전경 / S2 야간 조명 연출(조도 배치안 반영) / S3 통로 시점 / S4 부스 내부 / S5 Before/After / S6 배선 오버레이 / S7 홀 전경
- 자동생성은 비용·품질 제어 위해 **S1·S7 한정**, 나머지는 온디맨드 [구현 계획: 샷세트 파이프라인]
- 모든 컷에 워터마크·고지 항상 포함
- **도표 지시**: 샷세트 7컷 그리드(각 컷 워터마크 배지). 도식ID 없음(그리드).
- **REQ**: REQ-A-001, REQ-F-019(조명 조도 배치안)
- **출처**: tech_advisory §2 WT-1, PLANNING §6
## S19 · image-to-image 구조보존
- **섹션**: P3 기술제안(WT-1)
- **헤드라인**: "골격·치수·통로·카메라 앵글은 잠그고, 스타일·재질만 사실화한다."
- **본문**
- 참조 이미지 `inlineData` + 구조화 프롬프트 사전(BOOTH_TYPES·BOOTH_STYLES·FIXTURE_LAYERS)
- **보존(잠금)**: 부스 골격·치수·통로·카메라 앵글 → 왜곡·과장 방지
- **교체(사실화)**: 스타일·재질·마감만 → 사진 리얼리티
- 검증 패턴: ReRoomAI image-to-image 보존/교체 분리 이식(reroomai-source.md)
- **도표 지시**: 보존/교체 파라미터 도식(잠금 항목 vs 교체 항목 2열). 도식ID 없음.
- **REQ**: REQ-A-002, REQ-A-003
- **출처**: tech_advisory §2 WT-1, docs/analysis/reroomai-source.md
## S20 · AI 파이프라인 아키텍처
- **섹션**: P3 기술제안(WT-1)
- **헤드라인**: "생성은 전면 비동기 — 사용자는 대기하지 않고, 완료는 WebSocket으로 밀어준다."
- **본문**
- 흐름: 사용자 요청 → Spring RenderJob 생성·쿼터 확인 → Redis 큐(leftPush) → Python 워커(BLPOP) → Gemini image-to-image → 워터마크 후처리·S6 로컬 PIL 래스터 → 오브젝트 스토리지 → pub/sub → 백엔드 relay → WebSocket `/topic/render/{jobId}` → 프론트 완료 푸시
- degraded 분기: G1 미승인/Gemini 장애 시 워커 목(mock) 응답·구조·워터마크 유지(REQ-N-005)
- 성공 시에만 쿼터 차감, `GEMINI_API_KEY`는 워커 env only
- **도표 지시**: **도식③ 나노바나나 파이프라인 플로우(8박스 좌→우)**. tech_advisory §1-4 ③.
- **REQ**: REQ-A-007, REQ-N-006
- **출처**: tech_advisory §1-4 ③·§2 WT-1
## S21 · Before/After·배선 오버레이
- **섹션**: P3 기술제안(WT-1)
- **헤드라인**: "드래그 한 번으로 빈 부스와 시공 후를 비교하고, 배선을 색으로 겹쳐 본다."
- **본문**
- Before/After: 좌우 분할 카드 + 중앙 드래그 핸들, ARIA slider·키보드 좌우 조작(WCAG AA)
- S6 배선 오버레이: Gemini 미경유, 백엔드/워커 로컬 PIL **결정적 래스터 합성**(좌표 정확성·비용/지연 제외)
- 색상 규약: 전기=적색, 네트워크=청색, 급배수=녹색
- **도표 지시**: **도식④ Before/After 슬라이더**(좌 "Before: 빈 부스", 우 "After: 시공 후 예상(AI 생성·워터마크)", 하단 워터마크 배지). tech_advisory §1-4 ④.
- **REQ**: REQ-A-004, REQ-A-005
- **출처**: tech_advisory §1-4 ④·§2 WT-1
## S22 · RenderJob 방어·품질
- **섹션**: P3 기술제안(WT-1)
- **헤드라인**: "다층 방어로 실패를 흡수하고, 성공했을 때만 쿼터를 쓴다."
- **본문**
- 크기가드·mimeType 자동감지·SAFETY 분기·친화적 한글 에러
- 간판 한글 렌더 실패 시 **간판영역 후처리 합성**(리스크 R-5 방어)
- 대량 생성 제어: 자동생성 S1·S7 한정 + 동일 스키마해시 캐시 + 행사별 쿼터(성공 시만 차감)
- **도표 지시**: RenderJob 상태 시퀀스(방어 계층 표시). 도식ID 없음(시퀀스).
- **REQ**: REQ-A-006, REQ-A-008, REQ-N-007
- **출처**: tech_advisory §2 WT-1, strategy §4 R-5
## S23 · AI 신뢰 원칙
- **섹션**: P3 기술제안(WT-1)
- **헤드라인**: "결정적 알고리즘이 중심, LLM은 보조, 최종 확정은 사람 — 워터마크는 불변."
- **본문**
- 3층 신뢰: 결정적 알고리즘(제약 솔버·PostGIS) 중심 + LLM 보조 + 사람 최종 확정
- 워터마크 항상 포함(`watermarkRequired:true`), 계약·심사 서류 사용 금지 고지 제거 불가
- AI 답변은 RAG 근거·인용·환각 차단(abstain)으로 오판 리스크 차단(리스크 R-6 방어)
- **도표 지시**: AI 3층 신뢰 구조 도식(결정론→LLM→사람). 도식ID 없음.
- **REQ**: REQ-S-009, REQ-A-017
- **출처**: tech_advisory §2 WT-2·WT-4, strategy §4 R-6
## P3-C. 배치·설계·배선 AI 자동화 — WT-2 (S24~S28, 5슬라이드)
## S24 · 플로어플랜 스튜디오(M2)
- **섹션**: P3 기술제안(WT-2)
- **헤드라인**: "제약 솔버가 상이한 목표로 정확히 3안 — 사람이 선택·병합·확정한다."
- **본문**
- 3안 자동생성: **결정적 제약 솔버**(비-LLM)가 통로 효율/프리미엄 부스/균형 등 목표별 생성, LLM은 조건해석만(REQ-A-009)
- 선택/병합 편집 + 최종안 버전기록·부스좌표 확정·초대링크(REQ-F-008·010)
- M2 매퍼(PostGIS 공간 SQL) [검증됨], 3안 생성·병합·집계 API [구현 계획]
- **도표 지시**: **도식⑤ 3안 비교 화면**(3열 카드·각 카드 최적화 목표·미니 배치도·지표, 하단 액션바 선택/병합/재검증). tech_advisory §1-4 ⑤.
- **REQ**: REQ-F-007·008·010, REQ-A-009
- **출처**: tech_advisory §1-4 ⑤·§2 WT-2
## S25 · 배치 규정 자동검증
- **섹션**: P3 기술제안(WT-2)
- **헤드라인**: "피난통로·바닥하중·비상구를 제출 전에 자동으로 플래깅한다."
- **본문**
- 룰엔진(`compliance-v*.json` 버전 데이터) + PostGIS 공간 판정: 통로폭 `ST_Distance/ST_Buffer`, 비상구 `ST_Intersects`, 홀 이탈 `ST_Contains`, 바닥하중 홀별
- 병합 후 재검증 필수, 위반 시 `COMPLIANCE_BLOCKED`(422)
- 원칙: 규정검증=플래깅까지, 구조안전 판정은 구조기술사/킨텍스(Non-Goal 명시, 리스크 R-6)
- **도표 지시**: 규정 위반 플래그 대시보드(위반 항목·홀별 하중·비상구 교차 목록). 도식ID 없음(대시보드).
- **REQ**: REQ-F-009, REQ-A-010
- **출처**: tech_advisory §2 WT-2, strategy §4 R-6
## S26 · 부스 설계 스튜디오(M3)
- **섹션**: P3 기술제안(WT-2)
- **헤드라인**: "조립부스 3D 프리뷰·독립부스 3안, 높이·리깅·방염·이격은 사전 검증."
- **본문**
- 조립부스 옵션·3D 프리뷰(REQ-F-011), 독립부스 설계 3안·선택/병합·버전(REQ-F-012)
- 설계 규정 사전검증: 높이 5m·리깅 6.5~8.5m·방염·이격(REQ-F-013)
- 도면 업로드 비전 추출·검증(REQ-F-014·A-020)
- **도표 지시**: 설계 3안 + 규정 체크리스트(높이·리깅·방염·이격). 도식ID 없음.
- **REQ**: REQ-F-011·012·013·014, REQ-A-020
- **출처**: tech_advisory §2 WT-2, PLANNING §M3
## S27 · 유틸리티 설계(M4)
- **섹션**: P3 기술제안(WT-2)
- **헤드라인**: "기기→kW→분전반을 자동 산출하고, 트렌치→분전반 최단 배선을 PostGIS가 그린다."
- **본문**
- 전기 용량·분전반 자동산출: 기기목록→kW 합산→분전반 산출(REQ-F-015)
- 배선 경로: 최근접 트렌치 KNN(`geom <-> point`)→최단 배선 LineString(`ST_Length`, 통로 횡단 최소 휴리스틱)(REQ-F-016)
- 실측 근거: 홀별 평면도 JPG 15장 + CAD "평면,트렌치.dwg" 확보 [검증됨], 미확보 구간은 "가정 좌표(실측 대기)" 라벨(리스크 R-2)
- **도표 지시**: **도식⑥ PostGIS 배선 오버레이**(부스 폴리곤·트렌치 포인트◆·분전반▣·색상별 LineString, 전기 적/네트 청/급배수 녹). tech_advisory §1-4 ⑥.
- **REQ**: REQ-F-015, REQ-F-016
- **출처**: tech_advisory §1-4 ⑥·§2 WT-2, strategy §4 R-2
## S28 · 위치표시도·유틸리티 신청
- **섹션**: P3 기술제안(WT-2)
- **헤드라인**: "좌표 클릭으로 위치표시도를 자동 작도하고, 신청·견적은 D-25 역산으로 챙긴다."
- **본문**
- 위치표시도 자동생성: 좌표 클릭 자동 작도, 수기 작도 폐지(REQ-F-017)
- 네트워크·급배수·압축공기 신청 + 마감 리마인더(D-25 역산)(REQ-F-018)
- 자동 견적 연동
- **도표 지시**: 위치표시도 자동생성 예시(좌표 클릭 → 작도 결과). 도식ID 없음.
- **REQ**: REQ-F-017, REQ-F-018
- **출처**: tech_advisory §2 WT-2, PLANNING §M4
## P3-D. 공사 옥션 폐루프 — WT-3 (S29~S32, 4슬라이드)
## S29 · 옥션 개요·폐루프
- **섹션**: P3 기술제안(WT-3)
- **헤드라인**: "AI가 만든 설계 자료가 곧 응찰 근거이고, 한 흐름에서 발주까지 끝난다."
- **본문**
- AI 자료 패키지(M2 배치+M3 설계+M4 배선/BOQ+M5 시공예측 이미지)가 응찰 근거(`attached_refs`)
- 옥션 유형 설정형(REVERSE 역경매/RFQ/FIXED), 물량서(BOQ) 자동산출(REQ-F-031)
- 데이터모델: `TB_AUCTION 1─N TB_QUOTATION ─ TB_AWARD` [구현 계획: Phase D-M15]
- **도표 지시**: **도식⑦ 옥션 폐루프 흐름도**(AI 자료 패키지→옥션 개설→등록 게이트→견적 제출→실시간 순위→종합평가 낙찰→발주 자동전환). tech_advisory §1-4 ⑦.
- **REQ**: REQ-F-025·026, REQ-F-031
- **출처**: tech_advisory §1-4 ⑦·§2 WT-3
## S30 · 역경매·실시간 순위
- **섹션**: P3 기술제안(WT-3)
- **헤드라인**: "라운드·마감·최저가·내 위치를 실시간으로, 자동마감까지."
- **본문**
- 실시간 순위 = Redis 정렬셋 + WebSocket `/topic/auction/{auctionId}` 델타 푸시
- 라운드 마감 = Redis 타이머(자동마감)
- 익명 옵션·내 위치 표시(REQ-F-027)
- 스캐폴드 4계층·큐·WS 패턴 확정으로 실현성 입증 [구현 계획]
- **도표 지시**: 실시간 순위 보드 목업(업체 순위·최저가·잔여 시간). 도식ID 없음(목업).
- **REQ**: REQ-F-027
- **출처**: tech_advisory §2 WT-3
## S31 · 종합평가 낙찰
- **섹션**: P3 기술제안(WT-3)
- **헤드라인**: "가격만이 아니라 평판·납기까지 가중 스코어로 투명하게 낙찰한다."
- **본문**
- 가중 스코어: 가격+평판+납기(`weight` jsonb, 옥션별 설정형, 예: 가격 0.6/평판 0.25/납기 0.15)(REQ-F-028)
- 항목별 비교표·선정 사유 제시
- 등록업체 AI 매칭 추천(REQ-F-030), 물량서(BOQ) 근거(REQ-F-031)
- **도표 지시**: **도식⑧ 종합평가 스코어 비교표**(업체 행 × 평가항목 열 + 가중 종합점수 + 낙찰 하이라이트). tech_advisory §1-4 ⑧.
- **REQ**: REQ-F-028, REQ-F-030, REQ-F-031
- **출처**: tech_advisory §1-4 ⑧·§2 WT-3
## S32 · 등록 게이트·발주 전환
- **섹션**: P3 기술제안(WT-3)
- **헤드라인**: "미등록 업체는 응찰 자체가 차단(403)되고, 낙찰은 계약·발주로 자동 전환된다."
- **본문**
- 등록 게이트: 미등록 업체 응찰 원천 차단 `NOT_REGISTERED_COMPANY`(403), M7이 `TB_COMPANY.kintex_registered` 검증 권위 → 킨텍스 "등록업체 시공 필수" 규정을 시스템이 강제(REQ-S-007)
- 발주 전환: Award → 계약/발주 자동전환(M6·M9 연동, 이벤트 디커플·순환 금지)(REQ-F-032)
- **도표 지시**: 등록 검증 시퀀스 + 발주 전환 흐름. 도식ID 없음(시퀀스).
- **REQ**: REQ-F-029, REQ-F-032, REQ-S-007
- **출처**: tech_advisory §2 WT-3·§4 REQ-S-007
## P3-E. 판매·서류·워크플로 (S33~S34)
## S33 · 판매·홀배정·견적(M1)
- **섹션**: P3 기술제안
- **헤드라인**: "가용성은 실시간 캘린더로, 견적은 규칙엔진으로 즉시, 신청은 웹폼→HWP로."
- **본문**
- 홀/반홀 가용성 실시간 캘린더(REQ-F-001)
- 규칙엔진 자동 견적(2,250원/㎡, 요율 공식본 [협의: C4])(REQ-F-002)
- 배정신청 웹폼→HWP 자동생성(REQ-F-003), 부스 판매 인벤토리(REQ-F-004), 온라인 셀프 선택·판매(REQ-F-005)
- 임대계약 전자서명(선택, REQ-F-006)
- **도표 지시**: 견적 규칙엔진 계산 흐름(면적×요율→견적). 도식ID 없음.
- **REQ**: REQ-F-001·002·003·004·005·006
- **출처**: PLANNING §M1, rfp_analysis(C4 요율)
## S34 · 서류·마일스톤(M6)
- **섹션**: P3 기술제안
- **헤드라인**: "D-150/30/25/7을 역산해 알리고, 웹폼은 HWP/PDF로, 검수는 AI가 돕는다."
- **본문**
- 마일스톤 자동생성·역산 알림(REQ-F-020), 신고서류 웹폼→HWP/PDF 자동생성 7종(REQ-F-021)
- 서류 버전·전자결재 워크플로(REQ-F-023), OCR 계약·납품서 자동등록(REQ-F-024·A-020)
- AI 서류 검수(누락·불일치)(REQ-A-011), 규정 자연어 챗봇(근거·인용)(REQ-A-012)
- kxwp 제출 릴레이: 웹폼→HWP/PDF까지 API 무관하게 완결, 릴레이 단계만 킨텍스 IT 협의 [협의: C2, 리스크 R-3](REQ-F-022)
- **도표 지시**: 마일스톤 역산 타임라인(D-데이별 서류·알림). 도식ID 없음(타임라인).
- **REQ**: REQ-F-020·021·022·023·024, REQ-A-011·012
- **출처**: tech_advisory §2, strategy §4 R-3
## P3-F. 관람·참가 (S35~S36)
## S35 · 관람객 등록·배지·리드(M10)
- **섹션**: P3 기술제안
- **헤드라인**: "사전등록→모바일 배지→현장 체크인→리드까지, 오프라인에서도 끊기지 않는다."
- **본문**
- 온라인 사전등록(유형별·중복검증)(REQ-F-037), 모바일 배지/QR 발급(REQ-F-038)
- 현장 QR 체크인·즉석 인쇄·집계(REQ-F-039), **오프라인 체크인 폴백**(REQ-F-040)
- 참가업체 리드캡처(REQ-F-041), AI 리드 스코어링·분류(REQ-F-042·A-018), 세그먼트 EDM(REQ-F-043)
- 티켓발권·AI폼빌더·스마트배지(선택, REQ-F-044)
- **도표 지시**: 등록→체크인→리드 여정도. 도식ID 없음(여정도).
- **REQ**: REQ-F-037·038·039·040·041·042·043·044, REQ-A-018
- **출처**: PLANNING §M10, tech_advisory §7
## S36 · 비즈매칭·마케팅·공개사이트(M11·M12·M17)
- **섹션**: P3 기술제안
- **헤드라인**: "AI가 매칭을 추천하고, 다국어 공개사이트·마이크로사이트가 SEO로 관람객을 모은다."
- **본문**
- AI 비즈매칭 추천(REQ-F-045·A-018), 미팅 슬롯·성과 리포트(REQ-F-046), 이벤트 모바일앱·세션·채팅·설문(REQ-F-047)
- 공개 홍보 사이트(SEO·다국어)(REQ-F-048), 공개 인터랙티브 플로어플랜(REQ-F-049), 세그먼트 EDM·캠페인 자동화(REQ-F-050), 스폰서십 패키지·대시보드(REQ-F-051)
- CMS 게시 워크플로·버전(REQ-F-067), 마이크로사이트(REQ-F-068), 다국어 콘텐츠·hreflang(REQ-F-069)
- AI 카피·이미지 초안·다국어 번역(REQ-A-015)
- **도표 지시**: 공개사이트 + 마이크로사이트 목업. 도식ID 없음(목업).
- **REQ**: REQ-F-045·046·047·048·049·050·051·067·068·069, REQ-A-015·018
- **출처**: PLANNING §M11·M12·M17, tech_advisory §1-2
## P3-G. 정산·경영분석·현장 (S37~S40)
## S37 · 정산·결제(M9)
- **섹션**: P3 기술제안
- **헤드라인**: "납부는 스케줄로, 결제는 PG로, 예치금은 실사용까지 투명하게 정산한다."
- **본문**
- 납부 스케줄 자동생성·알림(REQ-F-056), 유틸리티·부대 PG 결제(REQ-F-057)
- 예치금 실사용 정산 투명화(REQ-F-058), 세금계산서·옥션 수수료 정산(REQ-F-059)
- 환불·취소 규정 자동(선택, REQ-F-060)
- **도표 지시**: 정산 흐름도(납부→결제→예치금 정산→세금계산서). 도식ID 없음.
- **REQ**: REQ-F-056·057·058·059·060
- **출처**: PLANNING §M9
## S38 · 경영분석 BI(M16)-1
- **섹션**: P3 기술제안
- **헤드라인**: "가동률·매출구성·행사별 P&L·㎡당 수익을 운영사 관점 한 화면에."
- **본문**
- 홀·기간별 가동률 대시보드(REQ-F-061), 매출 구성·행사별 P&L(REQ-F-062)
- 전시장 ROI·RevPAD·㎡당 수익(REQ-F-063)
- 데이터: BI 집계·조회는 읽기복제 오프로드(운영 프라이머리 보호)
- **도표 지시**: BI 대시보드 목업(Recharts — 가동률·매출구성·P&L·RevPAD). 도식ID 없음(목업).
- **REQ**: REQ-F-061·062·063
- **출처**: PLANNING §M16, tech_advisory §3 REQ-N-010
## S39 · 경영분석 BI(M16)-2
- **섹션**: P3 기술제안
- **헤드라인**: "리텐션·LTV·참가사 ROI를 권한 격리로, AI가 수요를 예측하고 KPI를 브리핑한다."
- **본문**
- 참가사 리텐션·LTV 코호트(REQ-F-064), 참가업체 관점 ROI(권한 격리)(REQ-F-065), 경영진 KPI 대시보드·드릴다운(REQ-F-066)
- AI 수요예측·수율/동적가격(REQ-A-013), AI KPI 브리핑·자연어 조회 Text-to-SQL(REQ-A-014)
- BI 마트는 개인 식별자 비반입(집계만), 참가업체는 자사 데이터만(격리)
- **도표 지시**: KPI 드릴다운 + AI 인사이트 카드. 도식ID 없음.
- **REQ**: REQ-F-064·065·066, REQ-A-013·014
- **출처**: PLANNING §M16, tech_advisory §4 REQ-S-013
## S40 · 현장운영·물류(M8·M13·M14)
- **섹션**: P3 기술제안
- **헤드라인**: "반입/반출 슬롯·통행증 QR·wayfinding·이상탐지 — 선택 기능은 시설 협의 전제로."
- **본문**
- 반입/반출 슬롯 예약(REQ-F-033), 통행증 QR·중량물 우선(REQ-F-034), 지게차·부대장비 렌탈(REQ-F-035), 철거 대기열 시뮬레이션(REQ-F-036)
- 실내 wayfinding·POI·경로(REQ-F-052), 실시간 혼잡 모니터·예측(REQ-F-053·A-019), 홀 전력부하·주차 점유(REQ-F-054), 안전 위반·이상탐지(REQ-F-055·A-019)
- 사이니지 콘텐츠 배포(REQ-F-070)
- **[협의]**: wayfinding 비콘·IoT·사이니지 HW는 킨텍스 시설 인프라 협의 전제(C7, 리스크 R-7). 미협의 시에도 코어 가치(WT-1~4)는 HW 독립
- **도표 지시**: 현장 운영 상황판(혼잡·전력·안전·물류 슬롯). 도식ID 없음(상황판).
- **REQ**: REQ-F-033·034·035·036·052·053·054·055·070, REQ-A-019
- **출처**: PLANNING §M8·M13·M14, strategy §4 R-7
---
# P4. 아키텍처·기술스택 (S41~S45, 배점 10)
## S41 · 전체 아키텍처
- **섹션**: P4 아키텍처
- **헤드라인**: "확정 스택으로 이미 기동 중 — 도상이 아니라 동작하는 아키텍처다."
- **본문**
- 4-Tier + 사이드카: React 18/19(Vite·TS) 역할별 분리 → SSO(JWT+2FA)·이중 RBAC → 공유 Spring Boot 3.2.5(Java 17)+MyBatis 모듈러 모놀리스 → PostgreSQL+PostGIS(+읽기복제)/Redis/오브젝트 스토리지
- 사이드카: 나노바나나 Python 워커(이미지) + Claude AI(AiTextRouter·Ollama 폴백)(텍스트)
- 실증: 인프라·CI/CD·인증·PostGIS 코어·나노바나나 [검증됨]
- **도표 지시**: **도식⑨ 시스템 아키텍처 다이어그램(6밴드 계층 + 우측 외부 게이트 컬럼)**. tech_advisory §1-4 ⑨.
- **REQ**: REQ-A-016, REQ-F-081(역할별 프론트)
- **출처**: tech_advisory §1-1·§1-4 ⑨·§0-1
## S42 · 단일 공간 데이터 원천
- **섹션**: P4 아키텍처
- **헤드라인**: "부스 폴리곤·트렌치 포인트·배선 LineString은 하나의 원천에서만 산다."
- **본문**
- M2 폴리곤·M4 배선 매퍼가 권위, 소비 모듈은 조회만·중복 저장 금지(REQ-N-017)
- PostGIS 단일 공간 원천(SRID 0 홀 로컬 미터), 전 `geom` GiST 인덱스 실시간(REQ-N-008)
- 검증 게이트: ArchUnit·계약 검수로 중복 저장 방지
- **도표 지시**: 공간 데이터 원천 모델(폴리곤·포인트·LineString 단일 원천). 도식ID 없음(개념 모델).
- **REQ**: REQ-N-008, REQ-N-017
- **출처**: tech_advisory §3(N-008·017), data.md §0-2
## S43 · 확장성·비동기
- **섹션**: P4 아키텍처
- **헤드라인**: "워커는 큐 깊이로 독립 확장하고, BI·공개는 읽기복제로 오프로드한다."
- **본문**
- 워커 독립 스케일: 나노바나나·서류·EDM 워커 큐 깊이 기반 증감(REQ-N-009)
- 읽기복제 오프로드: BI 집계·공개 조회·플로어플랜 열람 읽기복제 라우팅(REQ-N-010)
- 공개영역 CDN·요청률 상한(REQ-N-019), 워커 장애 재큐(멱등 Job)(REQ-N-011)
- 역할별 프론트 번들 분리(REQ-F-081, 방식 확정 대기 [구현 계획])
- **도표 지시**: 배포 토폴로지도(프론트·백엔드 2인스턴스·워커 N·읽기복제·CDN). 도식ID 없음(토폴로지).
- **REQ**: REQ-N-009·010·011·019, REQ-F-081
- **출처**: tech_advisory §3, system.md §3-1
## S44 · AI 플랫폼 라우팅
- **섹션**: P4 아키텍처
- **헤드라인**: "Claude 기본, 장애·폐쇄망이면 Ollama 폴백 — LLM 직접호출은 금지, 중앙 경유만."
- **본문**
- `AiTextRouter`: Claude 기본(`api.anthropic.com` 승인 예외) → Ollama 폴백(REQ-A-016)
- 나노바나나는 큐/콜백만(백엔드는 이미지 미취급), degraded 시 목 응답(REQ-A-007, N-005)
- AiTextRouter/AiConfig는 UIWS 패턴 [구현 계획: 착수 대기]
- **도표 지시**: AI 라우터 폴백 흐름(Claude→실패→Ollama). 도식ID 없음.
- **REQ**: REQ-A-007, REQ-A-016
- **출처**: tech_advisory §1-2 AI(텍스트)·§6
## S45 · 연동·마스터데이터
- **섹션**: P4 아키텍처
- **헤드라인**: "외부는 게이트웨이로, 룰셋·요율은 버전 데이터로 무중단 개정한다."
- **본문**
- API·웹훅·CRM/ERP 연동 게이트웨이(선택, REQ-F-080)
- 룰셋·마스터데이터 버전관리(요율·규정 룰셋), M18 백오피스·감사 기록으로 무중단 개정(REQ-F-072)
- 외부 게이트: Gemini(워커존)·Claude(백엔드)·PG 결제·kxwp 릴레이·등록업체 DB 739
- **도표 지시**: 연동 인터페이스 맵(내부↔외부 게이트웨이). 도식ID 없음.
- **REQ**: REQ-F-072, REQ-F-080
- **출처**: tech_advisory §1-2, §6-3
---
# P5. 보안·개인정보 (S46~S50, 배점 10 · WT-4)
## S46 · 보안 개요·불변 원칙
- **섹션**: P5 보안·개인정보
- **헤드라인**: "AI가 만든 것은 표시하고, 남의 데이터는 차단한다 — REQ-S 20항목 전량 커버."
- **본문**
- 불변 원칙 4대: 외부 API 격리 · 워터마크 항상 · PII 격리 · 테넌트 fail-closed
- 보안 성숙도: 인증·워터마크·admin env는 [검증됨](설계가 아니라 동작하는 통제)
- REQ-S 20항목 커버리지 100%
- **도표 지시**: REQ-S 20항목 커버리지 표(항목·충족방안·상태). 도식ID 없음(표).
- **REQ**: REQ-S 전량(001~020)
- **출처**: tech_advisory §4·§0-1
## S47 · 보안영역 분리
- **섹션**: P5 보안·개인정보
- **헤드라인**: "공개 DMZ는 쓰기 권한이 없고, 데이터존은 아웃바운드가 0이다."
- **본문**
- 존 계층: 인터넷→엣지(CDN·WAF)→DMZ(공개, 쓰기 없음)→내부망(인증)→AI 워커존(egress 제한)→데이터존(최내곽, 아웃바운드 전면 차단)
- 철칙: DMZ→데이터존 직접 접근 절대 금지, 데이터존 아웃바운드 0(유출 경로 제거)
- egress 화이트리스트: 승인 4목적지만(Claude·Gemini·PG·SMTP), 그 외 DROP
- fail-closed 다층 테넌트 격리와 정합(REQ-S-018)
- **도표 지시**: **도식⑩ 보안영역 분리도(존 다이어그램 + 관리존 + egress 컬럼)**. tech_advisory §1-4 ⑩.
- **REQ**: REQ-S-020, REQ-S-018, REQ-N-018
- **출처**: tech_advisory §1-4 ⑩·§4, network.md §2
## S48 · 인증·접근통제
- **섹션**: P5 보안·개인정보
- **헤드라인**: "JWT+2FA는 이미 라이브, admin 비번은 env로 재시드, RBAC는 3중이다."
- **본문**
- JWT(HS256)+TOTP 2FA(RFC6238)+로그인 실패 잠금 [검증됨: Flyway V7/V8](REQ-S-005)
- admin 비번 env 재시드(AES-256-GCM, admin123 금지) [검증됨: env 시더](REQ-S-004)
- 행사 RBAC 3중(테넌트 격리 ⊃ 행사 RBAC, 열람/편집 게이트)(REQ-S-006), admin/internal 엔드포인트 게이트(REQ-S-008)
- RBAC·감사·시스템설정 백오피스(REQ-F-071)
- 미등록 업체 차단(403)과 연계(REQ-S-007)
- **도표 지시**: 인증 흐름 + RBAC 3중 구조. 도식ID 없음.
- **REQ**: REQ-S-004·005·006·007·008, REQ-F-071
- **출처**: tech_advisory §4·§0-1(라이브)
## S49 · AI·이미지 보안
- **섹션**: P5 보안·개인정보
- **헤드라인**: "생성 이미지는 워터마크·금지 고지 불변, 외부 API 키는 워커 env에만 산다."
- **본문**
- 워터마크 항상: M5 응답 `watermarkRequired:true`+text+notice(계약·심사 서류 금지), 제거 불가 [검증됨](REQ-S-009)
- 외부 API 정책: Ollama 기본 + Claude/Gemini만 승인 예외, egress 그 외 DROP(REQ-S-001)
- `GEMINI_API_KEY` 워커 env only(백엔드 미취급, 워커존 단일 egress)(REQ-S-002)
- RAG 근거·인용·환각 차단(abstain)(REQ-A-017)
- **도표 지시**: 워터마크 실물 + 외부 API 격리(워커존 단일 egress). 도식ID 없음.
- **REQ**: REQ-S-001·002·009, REQ-A-017
- **출처**: tech_advisory §4·§2 WT-4
## S50 · 개인정보·감사·안전코딩
- **섹션**: P5 보안·개인정보
- **헤드라인**: "PII는 동의·마스킹·암호화·응답 제외, 민감 액션은 전수 감사, 코드는 안전하게."
- **본문**
- PII: 동의 분리(privacy/marketing/share)·최소수집·`*_enc` AES-256-GCM·응답 완전 제외·보존/파기(REQ-S-013)
- 자격증명·키 완전 제외(응답/로그/커밋 마스킹)(REQ-S-003), 스택트레이스 미노출(REQ-S-010), DataAccessException 요약 매핑(REQ-S-011)
- 민감 액션 감사 전수(`TB_AUDIT_LOG` tenant_id 포함, `@Audited` AOP)(REQ-S-012)
- 안전코딩: 입력 검증(REQ-S-014)·XSS/CSP(REQ-S-015)·인젝션 차단 MyBatis `#{}`(REQ-S-016)·IDOR/CSRF/JWT 회전(REQ-S-017)
- 관측성: 로그·메트릭·트레이스에 PII/스택트레이스 미기록(REQ-N-018)
- **도표 지시**: PII 마스킹 예시 + 감사로그 표. 도식ID 없음.
- **REQ**: REQ-S-003·010·011·012·013·014·015·016·017, REQ-N-018
- **출처**: tech_advisory §4, data.md §5
---
# P6. 비기능 (S51~S54, 배점 8)
## S51 · 성능·가용성 SLA
- **섹션**: P6 비기능
- **헤드라인**: "코어 SLO 99.5%(성수기 99.9% 지향), 무중단 롤링·PITR·degraded로 버틴다."
- **본문**
- 코어 SLO 99.5%(성수기 99.9% 지향), 무상태 백엔드+Redis 외부화(REQ-N-001)
- 백엔드 2인스턴스·헬스체크 LB·롤링 무중단(REQ-N-002), PG 스탠바이 복제·자동 failover·PITR(REQ-N-003)
- degraded 모드: Gemini 장애=목 응답, Claude 장애=Ollama 폴백, PG 복제지연=프라이머리 폴백(REQ-N-005)
- 워커 장애 재큐(멱등)(REQ-N-011)
- **도표 지시**: SLA 수치표 + HA 구성도(프론트·백엔드·Redis·PG·워커 다중화). 도식ID 없음(표+구성도).
- **REQ**: REQ-N-001·002·003·005·011
- **출처**: tech_advisory §3·§6-2, system.md §3-2
## S52 · 나노바나나 성능
- **섹션**: P6 비기능
- **헤드라인**: "단건 평균 40초, 1024px 전처리·자동생성 한정·캐시·쿼터로 대량을 제어한다."
- **본문**
- 단건 평균 ≤40s, 전면 비동기(WS 완료 푸시)(REQ-N-006)
- 전처리: 클라 Canvas 1024px 다운스케일 + JPEG 0.85
- 대량 제어: 자동생성 S1·S7 한정 + 동일 스키마해시 캐시 + 행사별 쿼터(성공 시만 차감)(REQ-N-007)
- **도표 지시**: 렌더 성능 지표 카드(40초·1024px·캐시 히트·쿼터). 도식ID 없음.
- **REQ**: REQ-N-006, REQ-N-007
- **출처**: tech_advisory §3, system.md §3-3
## S53 · 접근성·다국어·테마·반응형
- **섹션**: P6 비기능
- **헤드라인**: "WCAG 2.1 AA+KWCAG 2.2, 한/영/중/일, 라이트/다크, 데스크톱/모바일 전부."
- **본문**
- 접근성: WCAG 2.1 AA + 공공 KWCAG 2.2 병행(REQ-N-012), 캔버스/맵 비시각 대안(데이터 테이블·키보드 부스 선택)(REQ-N-013)
- 다국어: i18n 외부화(한 기본+영/중/일)·hreflang·로케일 포맷(REQ-N-014)
- 테마: 라이트/다크 CSS 토큰 2벌·prefers-color-scheme(REQ-N-015)
- 반응형: 데스크톱=설계/에디터, 모바일=현장/조회/승인(REQ-N-016)
- [구현 계획: 전면 스윕 대기]
- **도표 지시**: 접근성·다국어 매트릭스. 도식ID 없음(매트릭스).
- **REQ**: REQ-N-012·013·014·015·016, REQ-F-069(다국어 정합)
- **출처**: tech_advisory §3, PLANNING §8
## S54 · 관측성·데이터
- **섹션**: P6 비기능
- **헤드라인**: "로그·메트릭·트레이스에 PII·스택트레이스는 남기지 않고, BI는 배치 ETL로 정합한다."
- **본문**
- 관측성: 로그·메트릭·트레이스 관리존 수집, 자격증명·PII·스택트레이스 미기록(`include-stacktrace: never`)(REQ-N-018)
- BI 데이터마트: 스타 스키마(FACT/DIM) 야간 배치 ETL 또는 읽기복제 적재, KpiSnapshot(원천-집계 정합 오차 0)(REQ-N-021)
- 공개영역 CDN·요청률 상한과 정합(REQ-N-019)
- **도표 지시**: 관측성 파이프라인(수집→저장→대시보드). 도식ID 없음.
- **REQ**: REQ-N-018, REQ-N-021, REQ-N-019
- **출처**: tech_advisory §3, data.md §6, tech.md §5
---
# P7. 멀티테넌시·확장 (S55~S57, 배점 5 · WT-5)
## S55 · 멀티테넌트 SaaS 비전
- **섹션**: P7 멀티테넌시·확장
- **헤드라인**: "KINTEX #1에서 검증하고, COEX #2로 확장하며, 제3전시장을 표준으로 맞는다."
- **본문**
- KINTEX=기준 테넌트 #1, COEX=테넌트 #2(온보딩 대상)
- 제3전시장(2028, 178,000㎡) 확장 + 국내 전시산업 표준 플랫폼화
- 개발 부담 최소화: 멀티테넌시=격리 레이어만 추가, 기능 로직 불변(리스크 R-8)
- **도표 지시**: 테넌트 확장 로드맵(KINTEX→COEX→제3전시장→타 전시관). 도식ID 없음(로드맵).
- **REQ**: (비전 — 상세 REQ는 S56·S57)
- **출처**: strategy §1 WT-5·§4 R-8, PLANNING §1A
## S56 · 테넌트 격리 아키텍처
- **섹션**: P7 멀티테넌시·확장
- **헤드라인**: "한 층이라도 불일치하면 차단 — 컨텍스트→서비스→MyBatis→PostGIS 4층 방어."
- **본문**
- 격리 축: `tenant_id`(전시관) ⊃ `event_id`(행사) ⊃ 행사 RBAC 3중
- fail-closed 4층: ①컨텍스트 필터(서브도메인+소속, 불일치 거부)→②서비스 가드→③MyBatis 인터셉터(tenant_id 자동 주입)→④PostGIS(tenant_id 선두 복합 인덱스)(REQ-S-018)
- tenant_id 선두 복합 인덱스로 격리 쿼리 성능(REQ-N-020)
- [구현 계획: 스키마·컨텍스트 구현 대기, 백필 전 단일테넌트 무중단→검증 후 필터 활성화]
- **도표 지시**: **도식⑪ 멀티테넌시 격리 아키텍처도(수직 4층 방어 스택 + 좌측 테넌트 컨텍스트 진입)**. tech_advisory §1-4 ⑪.
- **REQ**: REQ-F-077·078, REQ-S-018, REQ-N-020
- **출처**: tech_advisory §1-3·§1-4 ⑪
## S57 · 온보딩·2계층 관리자
- **섹션**: P7 멀티테넌시·확장
- **헤드라인**: "코드 배포 없이 데이터 온보딩 6단계로 새 전시관을 연다."
- **본문**
- 온보딩: 코드 배포 없이 데이터 온보딩(홀·요율·규정 룰셋·마스터데이터 입력 수준)(REQ-F-077)
- 2계층 관리자: 플랫폼 슈퍼관리자(테넌트 스위처) / 테넌트 관리자(단일 스코프)(REQ-F-079)
- 테넌트 컨텍스트 해소(REQ-F-078)
- 공통코드·메뉴 관리(§5B, REQ-F-073) 기반 재사용
- **도표 지시**: 온보딩 6단계 도식 + 테넌트 스위처 화면. 도식ID 없음(단계 도식).
- **REQ**: REQ-F-077·078·079, REQ-F-073
- **출처**: tech_advisory §1-3, strategy §1 WT-5
---
# P8. 사업관리·일정·조직 (S58~S60, 배점 2)
## S58 · 추진 일정·Phase
- **섹션**: P8 사업관리·일정·조직
- **헤드라인**: "Phase 1 코어 → Phase 2 워크플로/운영 → Phase 3 현장/확장, 게이트로 진행."
- **본문**
- Phase 1(~4M): 아키텍처(A)·공통레이어(B, 2FA/시스템관리)·P0 코어(C: M2·M3·M4·M5)
- Phase 2(~4M): 옥션 M15·관람 M10·BI M16·관리자 M18·판매/서류/정산 M1/6/7/9·CMS M12/17
- Phase 3(~4M+): 멀티테넌시·M11·M13·M14·배포 안정화·SM 이관
- 공수: 총 ~150 M/M 규모(핵심 146 + PMO/QA 4~8), 라이브 스캐폴드로 Phase A/B 공수 실측 절감
- [주의: 예산·사업기간은 실제 RFP 부재로 가정, 공고 확인 시 재정렬]
- **도표 지시**: **도식⑫ 일정 간트(Phase × 모듈 + 마일스톤 다이아몬드 G1·G2·Phase 게이트·QA 게이트·오픈)**. tech_advisory §1-4 ⑫.
- **REQ**: (일정 — 실행력 근거)
- **출처**: tech_advisory §1-4 ⑫·§5, PLANNING §9
## S59 · 선행 게이트·리스크 관리
- **섹션**: P8 사업관리·일정·조직
- **헤드라인**: "약한 고리를 숨기지 않고 드러내 방어한다 — 선제 대응이 곧 신뢰다."
- **본문**
- 선행 게이트: G1 나노바나나 승인 [검증됨: 완료]·G2 배포서버 [검증됨: 완료]
- 리스크 R-1~R-8 정면 방어: 외부 API(승인 게이트+degraded 폴백)·CAD 실측(가정 라벨+협의 선행)·kxwp(단계적 접근)·배점 가정(투명 고지)·이미지 품질(후처리 합성)·AI 오판(사람 확정)·HW 연동(협의 전제)·확장 부담(격리 레이어만)
- 확인 필요 8항목(C1~C8) 관리
- **도표 지시**: **리스크 매트릭스(발생×영향 2×2에 R-1~R-8·C1~C8 배치)** + 게이트. tech_advisory §1-4 말미(추가 표준 도식).
- **REQ**: (리스크 관리 — 방어 논리)
- **출처**: strategy §4, rfp_analysis §6, tech_advisory §0
## S60 · 품질·형상관리
- **섹션**: P8 사업관리·일정·조직
- **헤드라인**: "배포는 헬스체크로 지키고 실패하면 롤백, 의존성은 SCA 게이트로 막는다."
- **본문**
- Fail-Safe 배포: 백업→배포→헬스체크 200→실패 시 롤백(이전 jar 유지) [검증됨: deploy_kintex.sh](REQ-N-004)
- QA 게이트: 점진 경계면 검증·보안 불변·빌드 회귀(Phase 게이트 통과 후 진행)
- SCA CI 게이트: OWASP Dependency-Check 정기 스캔·패치(REQ-S-019)
- 형상관리: Gitea `zio/kintex`·Conventional Commits·main 보호·환경 분리(dev/staging/prod)
- **도표 지시**: 품질 게이트 흐름(빌드→테스트→SCA→헬스체크→롤백). 도식ID 없음.
- **REQ**: REQ-N-004, REQ-S-019
- **출처**: tech_advisory §6-5·§0-1(라이브), §4 REQ-S-019
---
# P9. 기대효과 (S61~S63, 가점)
## S61 · 정량 기대효과
- **섹션**: P9 기대효과
- **헤드라인**: "견적 수일→즉시, 배치 수주→수 분, 검수 육안→자동, 결과는 사진으로."
- **본문**
- 견적: 수일 대기 → 즉시(규칙엔진)
- 배치: 수주 CAD 외주 → 수 분 3안 자동생성
- 규정 검수: 육안 → 제출 전 자동 플래깅
- 위치표시도: 수기 → 좌표 클릭 자동 작도
- 시공 결과: 개장일 첫 대면 → 신청 시점 사진 예측
- **도표 지시**: **기대효과 정량 인포그래픽(5지표 Before/After)**. tech_advisory §1-4 말미(추가 표준 도식).
- **REQ**: REQ-F-002·007·009·017, REQ-A-001
- **출처**: PLANNING §1-3, strategy §5
## S62 · 정성·전략 효과
- **섹션**: P9 기대효과
- **헤드라인**: "참가업체는 영업력을, 홀매니저는 시간을, 킨텍스는 데이터 주권을 얻는다."
- **본문**
- 참가업체: 사진급 자료로 영업력·수주력 강화
- 홀매니저: 규정 검수 병목 해소로 처리량 증대
- 킨텍스: 온프레미스 우선·외부 AI 격리로 데이터 주권 확보
- 산업: 국내 전시산업 표준 플랫폼화
- **도표 지시**: 이해관계자별 효과 카드. 도식ID 없음.
- **REQ**: (정성 효과 — 전략)
- **출처**: strategy §3
## S63 · 확장 비전·마무리
- **섹션**: P9 기대효과
- **헤드라인**: "킨텍스에서 검증하고, 코엑스로 확장하며, 다시 사진으로 컨펌한다."
- **본문**
- 확장: COEX·제3전시장·타 전시관 SaaS 확장
- 재사용: 검증된 공통 프레임워크(WISE/UIWS) 위에 도메인 코어 이식
- 클로징: "신청서를 내는 순간, 시공 후 사진을 먼저 본다."
- **도표 지시**: 확장 비전 로드맵 + 클로징 슬로건 대형 타이포. 도식ID 없음.
- **REQ**: REQ-F-077(확장 근거)
- **출처**: strategy §1 WT-5
---
# 부록 (선택 삽입)
## 부록 A · 확인 필요·협의 사항
- C1 평가배점·제출규격(가정) · C2 kxwp API(REQ-F-022) · C3 CAD·트렌치 실측(REQ-F-016 정확도) · C4 인터넷 요율 공식본(REQ-F-002) · C5 나노바나나 G1(완료) · C6 코엑스 실측(REQ-F-077) · C7 사이니지·비콘·IoT HW(REQ-F-070·052~055) · C8 기타 협의
- 정직성 어필: 모든 [가정]·[협의]를 1장 집약 → 발주처 협업 자세
## 부록 B · REQ 커버리지 매트릭스
- 아래 "RTM 반영표" 참조(142 REQ ↔ 슬라이드 1:1)
## 부록 C · 100대 기능 성숙도
- 기구현 63 · 부분 18 · 신규 19(정량, rfp_analysis §4)
---
# RTM 반영표 (REQ → 슬라이드 · 142 REQ 전량)
> 규칙: 각 REQ의 **주 반영 슬라이드**(굵게) + 보조 슬라이드. QA는 이 표로 142 REQ 반영상태 ☑ 최종 검증. 미반영 0.
## REQ-F (기능 81)
| REQ | 요약 | 반영 슬라이드 |
|---|---|---|
| REQ-F-001 | 홀 가용성 캘린더 | **S33** |
| REQ-F-002 | 규칙엔진 견적 | **S33** · S10·S61 |
| REQ-F-003 | 웹폼→HWP | **S33** |
| REQ-F-004 | 부스판매 인벤토리 | **S33** |
| REQ-F-005 | 온라인 셀프선택 | **S33** |
| REQ-F-006 | 임대계약 전자서명 | **S33** |
| REQ-F-007 | 배치 3안 자동생성 | **S24** · S10·S61·S13 |
| REQ-F-008 | 배치안 선택/병합 | **S24** |
| REQ-F-009 | 배치 규정 검증·재검증 | **S25** · S10·S61 |
| REQ-F-010 | 최종안 버전·좌표·초대링크 | **S24** |
| REQ-F-011 | 조립부스 3D 프리뷰 | **S26** |
| REQ-F-012 | 독립부스 3안·버전 | **S26** |
| REQ-F-013 | 설계 규정 사전검증 | **S26** |
| REQ-F-014 | 도면 비전 추출·검증 | **S26** |
| REQ-F-015 | 전기용량·분전반 산출 | **S27** |
| REQ-F-016 | 배선경로 PostGIS 최단 | **S27** · S42 |
| REQ-F-017 | 위치표시도 자동생성 | **S28** · S10·S61 |
| REQ-F-018 | 네트워크·급배수·압축공기 신청 | **S28** |
| REQ-F-019 | 조명 조도 배치안 | **S18** |
| REQ-F-020 | 마일스톤 역산 알림 | **S34** |
| REQ-F-021 | 신고서류 웹폼→HWP/PDF | **S34** |
| REQ-F-022 | kxwp 릴레이 ⚠ | **S34** · S59(리스크 R-3) |
| REQ-F-023 | 서류 버전·전자결재 | **S34** |
| REQ-F-024 | OCR 계약·납품서 | **S34** |
| REQ-F-025 | 역경매 옥션 개설 | **S29** · S12·S13 |
| REQ-F-026 | AI 자료 기반 응찰·PDF | **S29** |
| REQ-F-027 | 실시간 순위·자동마감 | **S30** |
| REQ-F-028 | 종합평가 낙찰 스코어 | **S31** |
| REQ-F-029 | 등록업체 게이트 | **S32** |
| REQ-F-030 | 등록업체 AI 매칭 | **S31** |
| REQ-F-031 | 물량서 BOQ 산출 | **S31** · S29 |
| REQ-F-032 | 낙찰→발주 자동전환 | **S32** · S12 |
| REQ-F-033 | 반입/반출 슬롯 | **S40** |
| REQ-F-034 | 통행증 QR | **S40** |
| REQ-F-035 | 지게차·렌탈 | **S40** |
| REQ-F-036 | 철거 대기열 시뮬 | **S40** |
| REQ-F-037 | 사전등록 | **S35** |
| REQ-F-038 | 모바일 배지/QR | **S35** |
| REQ-F-039 | 현장 체크인·집계 | **S35** |
| REQ-F-040 | 오프라인 체크인 폴백 | **S35** · S51 |
| REQ-F-041 | 리드캡처 | **S35** |
| REQ-F-042 | AI 리드 스코어링 | **S35** |
| REQ-F-043 | 세그먼트 EDM | **S35** |
| REQ-F-044 | 티켓발권·스마트배지 | **S35** |
| REQ-F-045 | AI 비즈매칭 | **S36** |
| REQ-F-046 | 미팅 슬롯·리포트 | **S36** |
| REQ-F-047 | 이벤트 모바일앱 | **S36** |
| REQ-F-048 | 공개 홍보 사이트 | **S36** |
| REQ-F-049 | 인터랙티브 플로어플랜 | **S36** |
| REQ-F-050 | 세그먼트 EDM 캠페인 | **S36** |
| REQ-F-051 | 스폰서십 패키지 | **S36** |
| REQ-F-052 | wayfinding | **S40** |
| REQ-F-053 | 혼잡 모니터·예측 | **S40** |
| REQ-F-054 | 전력부하·주차 | **S40** |
| REQ-F-055 | 안전 이상탐지 | **S40** |
| REQ-F-056 | 납부 스케줄 | **S37** |
| REQ-F-057 | PG 결제 | **S37** |
| REQ-F-058 | 예치금 정산 | **S37** |
| REQ-F-059 | 세금계산서·수수료 | **S37** |
| REQ-F-060 | 환불·취소 규정 | **S37** |
| REQ-F-061 | 가동률 대시보드 | **S38** |
| REQ-F-062 | 매출·P&L | **S38** |
| REQ-F-063 | ROI·RevPAD·㎡당 수익 | **S38** |
| REQ-F-064 | 리텐션·LTV | **S39** |
| REQ-F-065 | 참가업체 ROI 격리 | **S39** |
| REQ-F-066 | 경영진 KPI 드릴다운 | **S39** |
| REQ-F-067 | CMS 게시 워크플로 | **S36** |
| REQ-F-068 | 마이크로사이트 | **S36** |
| REQ-F-069 | 다국어 콘텐츠·hreflang | **S36** · S53 |
| REQ-F-070 | 사이니지 배포 ⚠ | **S40** · S59 |
| REQ-F-071 | RBAC·감사 백오피스 | **S48** |
| REQ-F-072 | 룰셋·마스터데이터 버전 | **S45** |
| REQ-F-073 | 공통코드·메뉴 | **S16** · S57 |
| REQ-F-074 | 공통 업무모듈 | **S16** |
| REQ-F-075 | 회의록 STT·업무보고 PDF | **S16** |
| REQ-F-076 | 통합 알림센터 WebSocket | **S16** |
| REQ-F-077 | 멀티테넌트 격리·온보딩 | **S56·S57** · S55·S63 |
| REQ-F-078 | 테넌트 컨텍스트 해소 | **S56** · S57 |
| REQ-F-079 | 2계층 관리자 | **S57** |
| REQ-F-080 | API·웹훅·CRM/ERP 연동 | **S45** |
| REQ-F-081 | 역할별 프론트 포털 | **S43** · S41·S09 |
## REQ-A (AI 20)
| REQ | 요약 | 반영 슬라이드 |
|---|---|---|
| REQ-A-001 | 샷세트 S1~S7 | **S17·S18** · S01·S12·S61 |
| REQ-A-002 | image-to-image 구조보존 | **S19** · S12 |
| REQ-A-003 | 구조화 프롬프트 사전 | **S19** |
| REQ-A-004 | S6 배선 오버레이 래스터 | **S21** |
| REQ-A-005 | Before/After 슬라이더 | **S21** |
| REQ-A-006 | RenderJob 방어 | **S22** |
| REQ-A-007 | 비동기 큐·WebSocket | **S20** · S44 |
| REQ-A-008 | 간판 텍스트 검수·후처리 | **S22** |
| REQ-A-009 | 배치 3안(제약 솔버+LLM) | **S24** |
| REQ-A-010 | AI 규정 검증 | **S25** · S26 |
| REQ-A-011 | AI 서류 검수 | **S34** |
| REQ-A-012 | 규정 챗봇(근거·인용) | **S34** |
| REQ-A-013 | AI 수요예측·동적가격 | **S39** |
| REQ-A-014 | KPI 브리핑·Text-to-SQL | **S39** |
| REQ-A-015 | AI 카피·번역 | **S36** |
| REQ-A-016 | AI 라우터(Claude→Ollama) | **S44** · S41 |
| REQ-A-017 | RAG·인용·환각 차단 | **S49** · S23 |
| REQ-A-018 | AI 리드 스코어·매칭 | **S35·S36** |
| REQ-A-019 | 현장 이상탐지·예측 | **S40** |
| REQ-A-020 | 도면 비전·OCR 등록 | **S26·S34** |
## REQ-N (비기능 21)
| REQ | 요약 | 반영 슬라이드 |
|---|---|---|
| REQ-N-001 | SLO 99.5% | **S51** |
| REQ-N-002 | 2인스턴스 롤링 무중단 | **S51** · S43 |
| REQ-N-003 | PG 스탠바이·PITR | **S51** |
| REQ-N-004 | Fail-Safe 배포 | **S60** |
| REQ-N-005 | degraded 모드 | **S51** · S20·S44 |
| REQ-N-006 | 나노바나나 40초·1024px | **S52** · S20 |
| REQ-N-007 | 대량 생성 제어 | **S52** · S22 |
| REQ-N-008 | 공간쿼리 GiST 실시간 | **S42** · S12 |
| REQ-N-009 | 워커 독립 스케일 | **S43** |
| REQ-N-010 | BI/공개 읽기복제 | **S43** · S38 |
| REQ-N-011 | 워커 재큐(멱등) | **S43** · S51 |
| REQ-N-012 | WCAG 2.1 AA·KWCAG 2.2 | **S53** |
| REQ-N-013 | 캔버스 비시각 대안 | **S53** |
| REQ-N-014 | 다국어 i18n·hreflang | **S53** |
| REQ-N-015 | 라이트/다크 테마 | **S53** |
| REQ-N-016 | 반응형 | **S53** |
| REQ-N-017 | 단일 공간 원천 | **S42** |
| REQ-N-018 | 관측성·미기록 | **S54** · S50 |
| REQ-N-019 | 공개 CDN·요청률 상한 | **S43** · S54 |
| REQ-N-020 | tenant_id 선두 복합 인덱스 | **S56** |
| REQ-N-021 | BI 데이터마트 배치 ETL | **S54** · S38 |
## REQ-S (보안 20)
| REQ | 요약 | 반영 슬라이드 |
|---|---|---|
| REQ-S-001 | 외부 API 정책 | **S49** · S47 |
| REQ-S-002 | GEMINI 키 워커 env only | **S49** |
| REQ-S-003 | 자격증명·키 완전 제외 | **S50** |
| REQ-S-004 | admin 비번 env 재시드 | **S48** |
| REQ-S-005 | JWT+2FA·실패 잠금 | **S48** |
| REQ-S-006 | 행사 RBAC 3중 | **S48** |
| REQ-S-007 | 미등록 업체 차단(403) | **S32** · S48 |
| REQ-S-008 | admin/internal 게이트 | **S48** |
| REQ-S-009 | 이미지 워터마크 항상 | **S49** · S23·S01 |
| REQ-S-010 | 스택트레이스 미노출 | **S50** |
| REQ-S-011 | DataAccessException 요약 | **S50** |
| REQ-S-012 | 감사로그 전수 | **S50** |
| REQ-S-013 | PII 동의·마스킹·암호화 | **S50** · S39 |
| REQ-S-014 | 입력 검증 | **S50** |
| REQ-S-015 | XSS·CSP | **S50** |
| REQ-S-016 | 인젝션 차단 | **S50** |
| REQ-S-017 | IDOR·CSRF·JWT 회전 | **S50** |
| REQ-S-018 | fail-closed 테넌트 격리 | **S56** · S47 |
| REQ-S-019 | 의존성 SCA CI 게이트 | **S60** · S50 |
| REQ-S-020 | 보안영역 분리 | **S47** |
---
## 커버리지 요약
| 유형 | REQ 수 | 반영 | 미반영 |
|---|---|---|---|
| REQ-F (기능) | 81 | 81 | 0 |
| REQ-A (AI) | 20 | 20 | 0 |
| REQ-N (비기능) | 21 | 21 | 0 |
| REQ-S (보안) | 20 | 20 | 0 |
| **총계** | **142** | **142** | **0** |
**슬라이드 총계**: 63(S01~S63) + 부록 3(A·B·C)
**RTM 커버리지**: 142/142 반영, **미반영 0**
**과장 방지 준수**: 라이브 확인분(인프라·CI/CD·나노바나나·인증·워터마크·PostGIS 코어·평면도 자산)만 [검증됨], 도메인 모듈·멀티테넌시·집계 API·i18n/접근성 전면 적용은 [구현 계획]으로 구분 표기. 시크릿(키·비번·IP·SSH) 전면 미기재. AI 생성 이미지는 전 슬라이드에서 워터마크·금지 고지 정책 명시.

210
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/proposal_outline.md Normal file
View File

@ -0,0 +1,210 @@
# 킨텍스 자동전시시스템 구축 — 제안서 목차 (Proposal Outline · PPT)
> 작성: proposal-strategist · 작성일: 2026-07-11 · 버전 v1.0
> 짝 문서: `proposal_strategy.md`(Win Theme·평가대응·리스크) · `rtm.md`(REQ↔섹션 매핑) · `rfp_analysis.md`(배점·규격)
> 형식: **PowerPoint(.pptx) 기술제안서**, 분량 자율(권장 40~80p) → **목표 ~63슬라이드**. 실제 공고 확인 시 재정렬(rfp_analysis C1).
> 목차 코드: P1 사업이해 · P2 추진전략 · P3 기술제안 · P4 아키텍처 · P5 보안·개인정보 · P6 비기능 · P7 멀티테넌시·확장 · P8 사업관리·일정·조직 · P9 기대효과 (RTM 정합).
> 배분 원칙: **배점 가중** — P3(35점) ≈ 40%, P4·P5(각 10점) 각 ~8%, P6(8점) ~6%, P1+P2(10점) ~16%, P7(5점) ~5%, P8(2점) ~5%, P9 ~5%.
---
## 슬라이드 배분 총괄 (배점 정렬)
| 구간 | 목차 | 평가배점(가정) | 슬라이드 수 | 비중 | 핵심 Win Theme |
|---|---|---|---|---|---|
| 표지·목차·오버헤드 | — | — | 6 | 10% | 슬로건 각인 |
| P1 | 사업이해 | 10(P1+P2 공유) | 4 | 6% | 도메인 이해 |
| P2 | 추진전략 | 10(P1+P2 공유) | 5 | 8% | 3중 해자 |
| **P3** | **기술제안** | **20+15=35** | **25** | **40%** | **WT-1·2·3 총력** |
| P4 | 아키텍처·기술스택 | 10 | 5 | 8% | 확정 스택·공간원천 |
| P5 | 보안·개인정보 | 10 | 5 | 8% | WT-4 |
| P6 | 비기능 | 8 | 4 | 6% | SLA 수치 |
| P7 | 멀티테넌시·확장 | 5 | 3 | 5% | WT-5 |
| P8 | 사업관리·일정·조직 | 2 | 3 | 5% | 실행력·게이트 |
| P9 | 기대효과 | 가점 | 3 | 5% | 정량 ROI |
| **합계** | | **80(+가격20)** | **63** | 100% | |
---
## 0. 표지·목차 (6슬라이드)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 기획 |
|---|---|---|---|
| S01 | 표지 | 사업명 + 슬로건 "신청서를 내는 순간, 시공 후 사진을 먼저 본다" | 나노바나나 시공 예측 히어로 이미지(워터마크) 배경 |
| S02 | 제안 개요 | 우리는 누구·왜 우리인가 3줄 | 제안사 로고·핵심 자산 아이콘(선 SVG) |
| S03 | 목차 | P1~P9 네비게이션 | 목차 인덱스(9섹션 배점 배지 병기) |
| S04 | 제안 핵심 요약(1p) | Win Theme 5선 + 3중 해자 한눈에 | **3중 해자 벤다이어그램**(시공예측∩PostGIS∩옥션폐루프) |
| S05 | 배점 대응 맵 | 우리 제안이 배점 어디를 어떻게 겨냥하는가 | **배점-섹션 정렬 매트릭스**(80점 히트맵) |
| S06 | [가정] 고지 간지 | 배점·규격 가정 투명 고지·공고 시 재정렬 | 간단 노트 카드(리스크 R-4 방어) |
---
## P1. 사업이해 (4슬라이드 · 배점 사업이해·추진전략 10)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ/근거 |
|---|---|---|---|---|
| S07 | 사업 배경·목적 | 킨텍스 108,011㎡(2028년 178,000㎡), 전시 준비 여전히 HWP·CAD 수작업 | 킨텍스 규모 인포그래픽 | PLANNING §1-1 |
| S08 | As-Is 프로세스 병목 | D-150/30/25/7 타임라인의 Pain Point(견적 대기·CAD 외주·kxwp 육안검수·유틸리티 파편화) | **As-Is 타임라인 다이어그램**(D-데이별 병목 표시) | PLANNING §3-1·3-2 |
| S09 | 이해관계자·페르소나 | 6역할+2관리자 계층의 과업·고통·기대 | **페르소나 카드 6종**(주최자·참가·업체·홀매니저·관람객·대중) | PLANNING §2 |
| S10 | To-Be 목표(정량) | 견적 즉시·배치 수분·규정 자동검증·위치표시도 자동·시공 예측 | **As-Is→To-Be 대비표**(정량 개선 5행) | PLANNING §1-3 |
---
## P2. 추진전략 (5슬라이드 · 배점 P1과 공유)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ/근거 |
|---|---|---|---|---|
| S11 | 비전·포지셔닝 | "도면이 아니라 사진으로 컨펌한다" 베뉴 운영 플랫폼 | 비전 슬로건 대형 타이포 | PLANNING §1-2 |
| S12 | **3중 해자 전략** | 시공예측∩PostGIS∩옥션폐루프 결합의 재현 난이도 | **3원 벤다이어그램(재강조·상세)** | strategy §3-3 |
| S13 | Win Theme 5선 | WT-1~5 슬로건·배점 정렬 | **Win Theme 5카드**(배점 배지 병기) | strategy §1 |
| S14 | 전시 생애주기 폐루프 | 설계→시각화→발주→시공→운영→분석 한 흐름 | **생애주기 폐루프 순환도**(M모듈 매핑) | PLANNING §1-2-1 |
| S15 | 추진체계·수행조직 | 아키텍트·코어·도메인·AI·QA·DevOps 팀 + 게이트 | **추진체계도(조직도)** | 하네스 팀 구성 |
---
## P3. 기술제안 (25슬라이드 · 배점 AI시각화·설계 20 + 기능구현 15 = 35 · **최다 집중**)
### P3-A. 모듈 조망 (1)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S16 | 전체 모듈맵 | M1~M18+§5B+§1A 한 장 조망, P0 코어 강조 | **모듈맵(생애주기×우선순위 매트릭스)** | rfp_analysis §2-1 |
### P3-B. 나노바나나 시공 예측 — WT-1 최우선 (7)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S17 | 나노바나나 개요 | "시공 전에 사진으로 의사결정" 경쟁 미보유 차별화 | 히어로 Before/After 실물 | REQ-A-001 |
| S18 | 표준 샷세트 S1~S7 | 정면·야간·통로·내부·Before/After·배선·홀전경 | **샷세트 7컷 그리드**(워터마크) | REQ-A-001, F-019 |
| S19 | image-to-image 구조보존 | 골격·치수·통로·앵글 잠금, 스타일만 사실화 | **보존/교체 파라미터 도식** | REQ-A-002·003 |
| S20 | AI 파이프라인 아키텍처 | Spring 큐→Redis→Python 워커→오브젝트스토리지→WebSocket | **나노바나나 파이프라인 플로우** | REQ-A-007, N-006 |
| S21 | Before/After·배선 오버레이 | 드래그 슬라이더(ARIA), S6 백엔드 래스터 합성(전기적·네트청·급배수녹) | Before/After 슬라이더 + 배선 색상 범례 | REQ-A-004·005 |
| S22 | RenderJob 방어·품질 | 다층 크기가드·SAFETY 분기·간판 한글 후처리·성공 시만 쿼터 | **RenderJob 상태 시퀀스**(방어 계층) | REQ-A-006·008 |
| S23 | AI 신뢰 원칙 | 결정적 알고리즘+LLM 보조+사람 확정, 워터마크 불변 | AI 3층 신뢰 구조 도식 | REQ-S-009, A-017 |
### P3-C. 배치·설계·배선 AI 자동화 — WT-2 (5)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S24 | 플로어플랜 스튜디오(M2) | 부스 배치 3안 자동생성·선택/병합·버전 | **3안 비교 화면 목업** | REQ-F-007·008·010, A-009 |
| S25 | 배치 규정 자동검증 | 피난통로·바닥하중 홀별·비상구·복층·소방 병합 후 재검증 | **규정 위반 플래그 대시보드** | REQ-F-009, A-010 |
| S26 | 부스 설계 스튜디오(M3) | 조립 3D 프리뷰·독립부스 3안·규정 사전검증(높이·리깅·방염·이격)·도면 비전추출 | 설계 3안+규정 체크리스트 | REQ-F-011~014, A-020 |
| S27 | 유틸리티 설계(M4) | 기기→kW→분전반 자동산출, 트렌치→분전반 PostGIS 최단 배선 | **PostGIS 배선 경로 오버레이** | REQ-F-015·016 |
| S28 | 위치표시도·유틸리티 신청 | 좌표 클릭 자동 작도(수기 폐지)·자동 견적·D-25 역산 | 위치표시도 자동생성 예시 | REQ-F-017·018 |
### P3-D. 공사 옥션 폐루프 — WT-3 (4)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S29 | 옥션 개요·폐루프 | AI 설계자료→응찰 근거→발주까지 한 흐름 | **옥션 폐루프 흐름도**(M2~M5→M15→M6·M9) | REQ-F-025·026 |
| S30 | 역경매·실시간 순위 | 라운드·마감·최저가·내 위치(익명 옵션)·자동마감 | **실시간 순위 보드 목업** | REQ-F-027 |
| S31 | 종합평가 낙찰 | 가격+평판+납기 가중 스코어·항목별 비교표 | **종합평가 스코어 비교표** | REQ-F-028·030·031 |
| S32 | 등록 게이트·발주 전환 | 미등록 업체 응찰 원천 차단(403)·낙찰→계약/발주 자동전환 | **등록 검증 시퀀스** + 발주 전환 | REQ-F-029·032, S-007 |
### P3-E. 판매·서류·워크플로 (2)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S33 | 판매·홀배정·견적(M1) | 가용성 캘린더·규칙엔진 견적(2,250원/㎡)·웹폼→HWP·셀프 부스선택 | 견적 규칙엔진 계산 흐름 | REQ-F-001~005 |
| S34 | 서류·마일스톤(M6) | D-150/30/25/7 역산·웹폼→HWP/PDF 7종·AI 서류검수·kxwp 릴레이(⚠협의)·전자결재·OCR | 마일스톤 역산 타임라인 | REQ-F-020~024, A-011 |
### P3-F. 관람·참가 (2)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S35 | 관람객 등록·배지·리드(M10) | 사전등록·모바일 배지/QR·현장 체크인·오프라인 폴백·리드캡처·세그먼트 EDM | 등록→체크인→리드 여정도 | REQ-F-037~043 |
| S36 | 비즈매칭·마케팅·공개사이트(M11·M12·M17) | AI 비즈매칭·SEO 다국어 공개사이트·인터랙티브 플로어플랜·마이크로사이트·CMS 게시 워크플로 | 공개사이트+마이크로사이트 목업 | REQ-F-045·048~051·067~069 |
### P3-G. 정산·경영분석·현장 (4)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S37 | 정산·결제(M9) | 납부 스케줄·PG 결제·예치금 실사용 투명 정산·세금계산서·옥션 수수료 | 정산 흐름도 | REQ-F-056~059 |
| S38 | 경영분석 BI(M16)-1 | 가동률·매출구성·행사별 P&L·RevPAD·㎡당 수익(운영사 관점) | **BI 대시보드 목업(Recharts)** | REQ-F-061~063 |
| S39 | 경영분석 BI(M16)-2 | 리텐션·LTV 코호트·참가사 ROI(권한 격리)·경영진 KPI·AI 수요예측·KPI 브리핑·Text-to-SQL | KPI 드릴다운 + AI 인사이트 카드 | REQ-F-064~066, A-013·014 |
| S40 | 현장운영·물류(M8·M13·M14) | 반입/반출 슬롯·통행증 QR·wayfinding·혼잡/전력/안전 이상탐지(선택·협의 전제) | 현장 운영 상황판 | REQ-F-033~036·052~055, A-019 |
---
## P4. 아키텍처·기술스택 (5슬라이드 · 배점 10)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S41 | 전체 아키텍처 | 확정 스택 React18/19+Spring Boot 3.x+MyBatis+PostgreSQL/PostGIS+Redis+나노바나나 Python 워커 | **시스템 아키텍처 다이어그램**(전 계층) | rfp_analysis §1, REQ-A-016 |
| S42 | 단일 공간 데이터 원천 | M2폴리곤·M4배선 매퍼 권위, 소비 모듈 조회만·중복 금지, PostGIS GiST 실시간 | **공간 데이터 원천 모델**(폴리곤·포인트·LineString) | REQ-N-008·017 |
| S43 | 확장성·비동기 | 워커 독립스케일(큐 깊이)·읽기복제 BI 오프로드·공개영역 CDN·역할별 프론트 분리 | **배포 토폴로지도** | REQ-N-009·010·019, F-081 |
| S44 | AI 플랫폼 라우팅 | Claude 기본→Ollama 폴백·중앙경유·LLM 직접호출 금지, 나노바나나 큐/콜백 | **AI 라우터 폴백 흐름** | REQ-A-007·016 |
| S45 | 연동·마스터데이터 | API·웹훅·CRM/ERP 게이트웨이·룰셋/마스터데이터 버전관리·무중단 개정 | 연동 인터페이스 맵 | REQ-F-072·080 |
---
## P5. 보안·개인정보 (5슬라이드 · 배점 10 · WT-4)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S46 | 보안 개요·불변 원칙 | "AI가 만든 것은 표시, 남의 데이터는 차단" REQ-S 20 커버리지 | **REQ-S 20항목 커버리지 표** | REQ-S 전량 |
| S47 | 보안영역 분리 | 공개 DMZ 쓰기 불가·데이터존 직결 불가·DMZ↔내부 HTTPS만 | **보안영역 분리도(망 구성)** | REQ-S-020, N-018 |
| S48 | 인증·접근통제 | JWT+2FA OTP(TOTP)·실패 잠금·admin 비번 env 재시드·RBAC 3중·admin/internal 게이트 | 인증 흐름 + RBAC 3중 구조 | REQ-S-004~008 |
| S49 | AI·이미지 보안 | 나노바나나 워터마크 항상·계약/심사 금지 고지·외부 API 워커 env only·RAG 환각차단 | **워터마크 실물** + 외부 API 격리 | REQ-S-001·002·009, A-017 |
| S50 | 개인정보·감사·안전코딩 | PII 동의·마스킹·AES-256-GCM·응답 제외·감사로그 전수·XSS/인젝션/IDOR·SCA 게이트·스택트레이스 미노출 | PII 마스킹 예시 + 감사로그 표 | REQ-S-010~017·019 |
---
## P6. 비기능 (4슬라이드 · 배점 8)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S51 | 성능·가용성 SLA | SLO 99.5%(성수기 99.9%)·백엔드 2인스턴스 롤링·PG 스탠바이+PITR·degraded 모드 | **SLA 수치표** + HA 구성도 | REQ-N-001~005·011 |
| S52 | 나노바나나 성능 | 평균 40초·1024px+JPEG 0.85 전처리·자동생성 S1·S7 한정·캐시·쿼터 | 렌더 성능 지표 카드 | REQ-N-006·007 |
| S53 | 접근성·다국어·테마·반응형 | WCAG 2.1 AA+KWCAG 2.2·비시각 대안·i18n 한/영/중/일·hreflang·라이트/다크·데스크톱/모바일 | 접근성·다국어 매트릭스 | REQ-N-012~016 |
| S54 | 관측성·데이터 | 로그·메트릭·트레이스(PII/스택트레이스 미기록)·BI 데이터마트 배치 ETL/읽기복제 | 관측성 파이프라인 | REQ-N-018·021 |
---
## P7. 멀티테넌시·확장 (3슬라이드 · 배점 5 · WT-5)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S55 | 멀티테넌트 SaaS 비전 | KINTEX #1 검증→COEX 확장, 제3전시장 대비 표준 플랫폼 | 테넌트 확장 로드맵 | §1A, WT-5 |
| S56 | 테넌트 격리 아키텍처 | tenant_id 전파·fail-closed 다층 격리(컨텍스트→서비스→MyBatis→PostGIS)·선두 복합 인덱스 | **멀티테넌시 격리 아키텍처도** | REQ-F-077·078, S-018, N-020 |
| S57 | 온보딩·2계층 관리자 | 코드 배포 없이 데이터 온보딩 6단계·플랫폼/테넌트 관리자·테넌트 스위처 | **온보딩 6단계 도식** | REQ-F-077·079 |
---
## P8. 사업관리·일정·조직 (3슬라이드 · 배점 2)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ |
|---|---|---|---|---|
| S58 | 추진 일정·Phase | Phase 1 코어(~4M)·2 워크플로/운영(~4M)·3 현장/확장(~4M+) | **일정 간트 차트**(Phase×모듈) | PLANNING §9 |
| S59 | 선행 게이트·리스크 관리 | G1 나노바나나 승인·G2 배포서버·확인필요 8항목(C1~C8) 관리 | **리스크 매트릭스**(발생×영향) + 게이트 | strategy §4, rfp_analysis §6 |
| S60 | 품질·형상관리 | Fail-Safe 배포(헬스체크·롤백)·QA 게이트·SCA CI·경계면 검증 | 품질 게이트 흐름 | REQ-N-004, S-019 |
---
## P9. 기대효과 (3슬라이드 · 가점)
| # | 슬라이드 | 핵심 메시지 | 그래픽/도표 | REQ/근거 |
|---|---|---|---|---|
| S61 | 정량 기대효과 | 견적 수일→즉시·배치 수주→수분·검수 육안→자동·위치표시도 자동·시공 예측 가능 | **기대효과 정량 인포그래픽**(5지표 Before/After) | PLANNING §1-3 |
| S62 | 정성·전략 효과 | 참가업체 영업력·홀매니저 병목 해소·데이터 주권·전시산업 표준화 | 이해관계자별 효과 카드 | strategy §3 |
| S63 | 확장 비전·마무리 | COEX·제3전시장·타 전시관 SaaS 확장, 슬로건 재각인 | 확장 비전 로드맵 + 클로징 슬로건 | WT-5 |
---
## 부록 (선택 삽입)
| 항목 | 내용 | 근거 |
|---|---|---|
| A. 확인 필요·협의 사항 | C1~C8([가정]·⚠확인필요) 집약 — 정직성 어필, 리스크 R-1~R-8 방어 요약 | rfp_analysis §6, strategy §4 |
| B. REQ 커버리지 매트릭스 | 142 REQ(F81·A20·N21·S20)↔P1~P9 반영 표(RTM 요약) | rtm.md |
| C. 100대 기능 성숙도 | 기구현 63·부분 18·신규 19 정량 | rfp_analysis §4 |
---
## deck-designer·writer 전달 핵심
- **필수 도식 12종**(반드시 제작): ①3중 해자 벤다이어그램(S04·S12) ②모듈맵(S16) ③나노바나나 파이프라인 플로우(S20) ④Before/After 슬라이더(S21) ⑤3안 비교 화면(S24) ⑥PostGIS 배선 오버레이(S27) ⑦옥션 폐루프 흐름도(S29) ⑧종합평가 스코어 비교표(S31) ⑨시스템 아키텍처 다이어그램(S41) ⑩보안영역 분리도(S47) ⑪멀티테넌시 격리 아키텍처도(S56) ⑫일정 간트(S58).
- **추진체계도**(S15)·**리스크 매트릭스**(S59)·**기대효과 인포그래픽**(S61)은 공공 제안 표준 필수.
- **아이콘**: 전량 선(line/stroke) 스타일 SVG 직접 제작(외부 라이브러리 금지) — proposal-visual-designer 산출 준수.
- **RTM 정합 검증**: 각 슬라이드 REQ 매핑을 rtm.md 반영상태(☐→☑)로 갱신. 142 REQ 누락 0 — qa가 본 목차의 REQ 열로 교차 점검.
- **배점 규율**: P3(S16~S40, 25슬라이드)가 전체의 40%. 나노바나나(S17~S23) 7슬라이드는 절대 축소 금지(최고 배점 20). 선택 기능(S40 등)은 압축 유지.

117
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/proposal_qa.md Normal file
View File

@ -0,0 +1,117 @@
# 제안서 최종 QA 보고 — 킨텍스 자동전시시스템 (나라장터 표준 7대장 재조립판)
> QA: proposal-qa · 일자: 2026-07-12 · 대상: `docs/deliverables/제안서.pptx` (97슬라이드) + `_workspace/proposal/build_deck.py`
> 검증 방법: python-pptx 텍스트 추출(`_qa_extract.py`) + REQ range 전개 대조(`_qa_rtm.py`) + 구조/배점/라벨 스캔(`_qa_struct.py`) + PowerPoint COM PNG 렌더(`render_check.py`) 시각 확인.
> **최종 판정: 승인(PASS)** — 중대 결함 3건 수정 완료·재빌드·재검증. 잔여 이슈는 발주처 확인 항목([가정]/[협의])뿐(정직하게 라벨링됨).
---
## 종합 결과
| # | 검증 항목 | 판정 | 비고 |
|---|---|---|---|
| 1 | 표준 목차 정합(7대장·신설 9슬라이드) | ✅ PASS | Ⅰ~Ⅶ 순차, 신설 9종 전량 실재 |
| 2 | RTM 커버리지(142 REQ) | ✅ PASS(수정 후) | 142/142. 결함 3건(F-008·F-010·F-026) 수정 |
| 3 | 배점 정렬(90/10) | ✅ PASS | 80/20·35/80 잔재 0, 재정렬 각주 존재 |
| 4 | 정직성 라벨 | ✅ PASS | tech_advisory §0과 일치 |
| 5 | 보안(노출/워터마크) | ✅ PASS | 자격증명 노출 0, AI 고지 존재 |
| 6 | 구조 품질(목차·간지·번호) | ✅ PASS | 목차↔장 순서·배점 배지 정합 |
**수정 건수: 3건**(build_deck.py 3개 편집 → 재빌드 → COM 재렌더 → 통과)
---
## 1. 표준 목차 정합 — PASS
7대장이 `g2b_standard_toc.md` §2-1(별지 제5호서식)과 순서·구조 일치. 각 장 앞 섹션 간지(7개) 배치.
| 장 | 슬라이드 | 섹션 간지 |
|---|---|---|
| Ⅰ 일반현황 | S6~S9 | S5 GENERAL STATUS |
| Ⅱ 전략·방법론 | S11~S25 | S10 STRATEGY & METHODOLOGY |
| Ⅲ 기술·기능 | S27~S56 | S26 TECHNOLOGY & FUNCTION |
| Ⅳ 성능·품질 | S58~S63 | S57 PERFORMANCE & QUALITY |
| Ⅴ 프로젝트 관리 | S65~S68 | S64 PROJECT MANAGEMENT |
| Ⅵ 프로젝트 지원 | S70~S73 | S69 PROJECT SUPPORT |
| Ⅶ 그 밖의 사항 | S75~S79 | S74 멀티테넌시·확장 |
**신설 9슬라이드 전량 실재·내용 소스 정합:**
투입인력 M/M(S7·tech_advisory §5-2) · 정량평가(S9) · 표준FW(S24) · 관리방법론(S66 PMBOK) · 인수인계교육(S70) · SM/SLA(S71 §6) · 장애비상(S72) · 기밀보안(S73) · 상생협력(S76 별표11).
---
## 2. RTM 커버리지 — PASS(수정 후 142/142)
REQ 배지가 range 표기(예: `REQ-F-073~076`, 연속 `REQ-F-045~051·067~069`)를 포함하므로 range 전개 후 대조. 이전 QA에서 모호했던 7건 우선 확정:
| REQ | 최초 상태 | 확정 결과 |
|---|---|---|
| F-008 배치안 선택/병합 편집 | 콘텐츠 O(S31)·배지 X | **수정**: S31 배지에 008 추가 |
| F-010 최종안 버전기록·좌표확정·초대링크 | 콘텐츠 X·배지 X (진성 누락) | **수정**: S31에 4번째 플로우 칩 "[최종안 확정·초대링크]" + 캡션 + 배지 010 추가 |
| F-026 AI자료 기반 견적서 응찰·PDF·버전 | 콘텐츠 O(S36)·배지 X | **수정**: S36 배지에 026 추가 |
| F-032 낙찰→발주 자동전환 | 배지 O(S39) | 이상 없음 |
| A-003 구조화 프롬프트 보존/교체 | 배지 O(S20) | 이상 없음 |
| A-005 Before/After 슬라이더 | 배지 O(S29) | 이상 없음 |
| A-008 간판 텍스트 비전 검수 | 배지 O(S30) | 이상 없음 |
**range 전개 후 잔여 유일 진성 누락 = F-010**(초대링크/최종안 확정 콘텐츠·배지 모두 부재) → 콘텐츠+배지 동시 보강으로 해소.
수정 후 union(단독 토큰 + range 전개) 대조: **142/142 전량 반영, 미반영 0.** 부록 B(S82) "미반영 0" 표기가 사실과 일치함(수정 전에는 F-008/010/026 미배지로 과장 소지 → 해소).
---
## 3. 배점 정렬 — PASS
- 표기 일관: **기술 90(정성70+정량20) / 가격 10** (S3 배점맵, S4 [가정] 간지). `기술 80`·`가격 20`·`80/20`·`35/80` 잔재 **0건**.
- 재정렬 각주 존재: S3 "실제 공고 확인 시 재정렬", S4·S7·S81 동일 취지. 정보화 지침 제18조 원칙값 근거 명기.
- S3 배점맵이 각 부문↔장(Ⅱ·Ⅲ최다·Ⅳ·Ⅴ·Ⅵ·Ⅰ·Ⅶ) 정확 매핑.
---
## 4. 정직성 라벨 — PASS
표본: [검증됨] 16 · [구현 계획] 4 · [협의] 2 · [가정] 5 · [Non-Goal] 1. `tech_advisory §0`(라이브 실적 vs 구현 계획)과 일치:
- **[검증됨]**(라이브): 나노바나나 Gemini 워커(S17·19), PostGIS 매퍼(S17), JWT+2FA(S52), CI/CD Fail-Safe(S24), 인프라·코어(S48) — §0-1과 일치.
- **[구현 계획]**: 옥션 M15 폐루프(S17·36·37 "Phase D-M15"), 멀티테넌시(S27), F-081 프론트 분리(S60) — §0-2와 일치. 과장(구현 완료 오기) 0.
---
## 5. 보안 — PASS
- 전 슬라이드 텍스트 스캔: IPv4/서버IP · `sk-`/`AIza` API키값 · SSH계정 · 비밀번호 값 노출 **0건**.
- AI 생성/워터마크 고지: 갤러리 도입부(S85) "본 화면은 Google Stitch 기반 AI 생성 디자인 시안…" 고지 박스 존재. M5 이미지 워터마크 불변(REQ-S-009) [검증됨] S22·50·53. 갤러리 전 시안(S85~97) "AI 생성" 고지 병기.
---
## 6. 구조 품질 — PASS
- 목차(S2 "나라장터 정보시스템 표준 7대장")↔실제 장 순서·슬라이드 번호 정합.
- 간지 배점 배지(S3): 부문↔장 매핑·배점 숫자 정확.
- 부록 A(100대 기능 성숙도)·B(REQ 매트릭스)·C(가정·협의 집약)·D(화면 갤러리) 순 구성.
---
## 수정 내역 (build_deck.py)
| 슬라이드 | 편집 | 커버 REQ |
|---|---|---|
| S31 배치 3안 | 배지 `REQ-F-007·A-009`→`REQ-F-007·008·010·A-009`; 액션칩 3→4([최종안 확정·초대링크] 추가); 캡션에 F-008·F-010 근거 명시 | F-008, F-010 |
| S36 옥션 폐루프 | 배지 `REQ-F-025·031`→`REQ-F-025·026·031` (콘텐츠 "견적서 제출 PDF·버전" 기존재) | F-026 |
재빌드(97슬라이드) → COM 렌더 → S31/S36 시각 확인(오버플로·깨짐 없음, 4칩 균등 배치).
---
## 잔여 이슈 (결함 아님 — 발주처 확인 항목)
`g2b_standard_toc.md §7` T1~T5 및 부록 C 집약대로 정직 라벨링됨. QA 통과를 막지 않음:
- 배점 90/10, 예산·M/M(~150), 투입인력 실명·단가 → [가정], 공고 확정 시 재정렬/기재
- 상생협력·하도급 구체 지분 → [공고·컨소 확정 시 기재]
- wayfinding 비콘·IoT·사이니지 HW(F-070·052~055) → [협의] 시설 인프라 전제
- kxwp 연동(F-022) → ⚠확인필요
---
## 최종 판정: **승인(PASS)**
7대장 표준 목차·신설 9슬라이드 완비, RTM 142/142(수정 3건 후), 배점 90/10 일관, 정직성 라벨 정합, 보안 노출 0, AI 고지 존재. 실제 공고 확인 시 배점·목차·투입계획 재정렬만 반영하면 제출 가능.

150
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/proposal_strategy.md Normal file
View File

@ -0,0 +1,150 @@
# 킨텍스 자동전시시스템 구축 — 수주 전략서 (Proposal Strategy)
> 작성: proposal-strategist · 작성일: 2026-07-11 · 버전 v1.0
> 입력: `rfp_analysis.md`(REQ 142 · 배점 가정 기술80/가격20) · `rtm.md`(P1~P9 매핑) · `docs/PLANNING.md` §1~§2
> 원칙: **배점이 전략을 지배한다.** 과장·허위 금지 — rfp_analysis에 근거 있는 주장만 기재. 시크릿(키·비번·내부IP) 미기재.
> 성격: 실제 RFP 부재 → 평가배점·제출규격은 **[가정]**(공공 SI 통례). 실제 공고 확인 시 교체.
---
## 0. 전략 요약 (Executive Summary)
**한 문장 포지셔닝**: 킨텍스 자동전시시스템은 "도면과 표를 보여주는" 기존 전시테크가 아니라, **"신청서를 내는 순간 시공 후 사진을 먼저 보여주고, 그 사진으로 발주까지 종결하는" 유일한 폐루프 플랫폼**이다.
**수주 논리 3단**:
1. **배점의 44%(35/80)가 P3 기술제안**(AI 시각화·설계 20 + 기능 구현 15)에 몰려 있다 → 제안서 분량·메시지·그래픽의 40% 이상을 P3에, 그중 절반을 나노바나나+M2~M5 폐루프에 집중한다.
2. 경쟁(글로벌 전시테크·기존 공공 SI)은 **나노바나나 시공 예측 + PostGIS 실측 공간데이터 + 옥션 폐루프**의 결합을 재현할 수 없다 → 이 3결합을 "우리만의 해자(moat)"로 전면화한다.
3. 공공 발주처의 최대 리스크(외부 API·개인정보·안전서류 오용)를 **선제 방어 논리**(G1 승인 게이트+degraded 폴백, AI 워터마크 불변, PII·테넌트 3중 격리)로 무장해 감점을 원천 차단한다.
**슬로건 후보(표지·간지용)**:
- 메인: **"신청서를 내는 순간, 시공 후 사진을 먼저 본다."** (PLANNING §1-2 비전 직인용)
- 서브: **"설계 → 시각화 → 발주 → 시공 → 운영 → 분석. 킨텍스에서 한 흐름으로 끝난다."**
---
## 1. Win Theme (차별화 메시지 5선)
> 각 Win Theme = ①발주처 핵심 니즈 ②우리 차별화 메시지(슬로건) ③배점 정렬 ④근거(REQ/PLANNING) ⑤증빙 방식. 배점 가중 순으로 배열.
### WT-1. 시공 전에 사진으로 의사결정한다 — 나노바나나 시공 예측 (최우선 · 배점 20)
- **발주처 니즈**: 참가업체·주최자가 "도면을 읽지 못해 개장일에야 결과를 처음 본다"(PLANNING §2 참가업체 Pain). 조감도 외주는 비용·시간.
- **슬로건**: **"도면이 아니라 사진으로 컨펌한다."**
- **차별화 메시지**: image-to-image 구조보존(골격·치수·통로·카메라 앵글 잠금, 스타일만 사실화)으로 표준 샷세트 S1~S7(정면·야간조명·통로·내부·Before/After·배선 오버레이·홀전경)을 평균 40초에 자동 생성. **경쟁 전시테크가 보유하지 못한 기능**(rfp_analysis §4 win 우선순위 ①).
- **배점 정렬**: "AI 시각화·설계 자동화(핵심 차별화) 20점" 직격. 대응 REQ-A-001~008, REQ-F-019.
- **증빙**: Before/After 드래그 슬라이더 실물 캡처, 샷세트 예시 이미지(워터마크 포함), RenderJob 파이프라인 도식.
### WT-2. 배치·설계·배선을 AI가 3안 자동생성하고 규정을 자동검증한다 (배점 20+15 교차)
- **발주처 니즈**: 주최자 CAD 수작업 수일~수주, 홀매니저 육안 규정 검수 병목(PLANNING §1-3, §3-2).
- **슬로건**: **"수 분 내 3안, 제출 전 규정 자동검증."**
- **차별화 메시지**: 제약 솔버+LLM 조건해석으로 부스 배치/부스 설계 각 3안 자동생성·선택/병합·버전관리(REQ-F-007~013). 규정(피난통로·바닥하중 홀별·높이 5m·리깅 6.5~8.5m·방염·이격)을 제출 전 자동 플래깅. PostGIS 최단경로로 트렌치→분전반 배선·위치표시도 자동 작도(수기 폐지, REQ-F-015~017).
- **배점 정렬**: AI 시각화·설계(핵심) 20 + 기능 구현 15의 코어. 대응 REQ-A-009·010·020, REQ-F-007~018.
- **증빙**: 3안 비교 화면, 규정 위반 플래그 대시보드, PostGIS 배선 경로 오버레이, "사람이 최종 확정"(AI는 보조) 명시.
### WT-3. AI 설계자료가 곧 발주 근거가 된다 — 공사 옥션 폐루프 (배점 15 · 폐루프 핵심)
- **발주처 니즈**: 등록업체 739개가 단순 리스트+엑셀, 매칭·견적 비교 부재(PLANNING §3-2).
- **슬로건**: **"사진 수준 자료로 응찰하고, 한 흐름에서 발주까지 끝낸다."**
- **차별화 메시지**: M2~M5가 생성한 배치·설계·배선/BOQ·시공 예측 이미지가 곧 역경매 응찰 근거. 실시간 순위·종합평가 낙찰(가격+평판+납기)→계약/발주 자동전환(REQ-F-025~032). **미등록 업체 응찰 원천 차단(403)** 으로 킨텍스 "등록업체 시공 필수" 규정을 시스템이 강제.
- **배점 정렬**: 기능 구현 15 + 보안(등록 게이트). 대응 REQ-F-025~032, REQ-S-007.
- **증빙**: 옥션 흐름도(설계자료→응찰→실시간순위→낙찰→발주), 종합평가 스코어 비교표, 등록 게이트 차단 시퀀스.
### WT-4. 공공이 안심하는 AI — 워터마크·PII·테넌트 3중 격리 불변 (배점 10)
- **발주처 니즈**: 생성 이미지의 계약·심사 서류 오용 우려, 관람객/리드 개인정보 보호, 다전시관 데이터 혼입 방지.
- **슬로건**: **"AI가 만든 것은 반드시 표시하고, 남의 데이터는 원천 차단한다."**
- **차별화 메시지**: M5 이미지 응답에 워터마크 **항상** 포함(watermarkRequired:true·계약/심사 서류 금지 고지, REQ-S-009). PII 동의·마스킹·AES-256-GCM·응답 완전 제외(REQ-S-013). fail-closed 다층 테넌트 격리(컨텍스트 필터→서비스 가드→MyBatis 인터셉터→PostGIS, REQ-S-018). 외부 API는 Ollama 기본+Claude/Gemini만 승인 예외(REQ-S-001).
- **배점 정렬**: 보안·개인정보 10점. 대응 REQ-S 20항목 전량.
- **증빙**: 보안영역 분리도(DMZ/내부망), 워터마크 실물, 감사로그 전수 표, PII 마스킹 예시.
### WT-5. 킨텍스에서 검증하고 코엑스로 확장한다 — 멀티테넌트 SaaS (배점 5 · 미래가치)
- **발주처 니즈**: 킨텍스 제3전시장(2028, 178,000㎡) 확장 + 국내 전시산업 표준 플랫폼화.
- **슬로건**: **"코드 배포 없이 데이터 온보딩만으로 새 전시관을 연다."**
- **차별화 메시지**: KINTEX=기준 테넌트 #1, COEX=테넌트 #2 온보딩 6단계(마스터데이터 입력 수준). tenant_id 전파·2계층 관리자(플랫폼/테넌트)·컨텍스트 해소(REQ-F-077~079). 기능은 전부 보존, 데이터·권한만 전시관 단위 분리.
- **배점 정렬**: 멀티테넌시·확장성 5점 + 사업 미래 비전. 대응 REQ-F-077~079, REQ-N-020, REQ-S-018.
- **증빙**: 멀티테넌시 격리 아키텍처, 온보딩 6단계 도식, 테넌트 스위처 화면.
---
## 2. 평가항목별 대응 전략 (배점 가중)
> 각 평가부문에 "무엇을·어떻게 보여줄지". 정량 항목=수치, 정성 항목=스토리. 배점 큰 순.
| # | 평가부문 | 배점 | 대응 전략 (증빙·실적·방법론·도표) | 주요 REQ | 목차 |
|---|---|---|---|---|---|
| 1 | **AI 시각화·설계 자동화(핵심)** | **20** | WT-1·WT-2 전면. 나노바나나 파이프라인 도식 + Before/After 실물 + 3안 생성·규정검증·PostGIS 배선 화면. "결정적 알고리즘 중심(제약 솔버) + LLM 보조 + 사람 최종확정" 3층 구조로 **AI 신뢰성** 강조 | REQ-A-001~010·020, F-007~019 | P3 |
| 2 | **기능 구현(M1~M18)** | 15 | 모듈맵 1장으로 전 모듈 조망 → 배점 큰 옥션(WT-3)·관람·BI를 상세, 선택(P2) 기능은 "구현 로드맵"으로 간결. 100대 기능 성숙도(기구현 63·부분 18·신규 19) **정량 제시** | REQ-F 전량, 특히 F-025~032 | P3 |
| 3 | **AI 설계 자동화(폐루프)** | (20 내) | WT-3. 옥션 흐름도 + 종합평가 스코어 비교표 + 발주 자동전환. AI 자료→응찰 근거 연결이 **경쟁이 못 하는 폐루프** | REQ-F-025~032, S-007 | P3 |
| 4 | 아키텍처·기술스택 | 10 | 확정 스택(React18/19+Spring Boot 3.x+MyBatis+PostgreSQL/PostGIS+Redis+나노바나나 Python 워커) 정합. 단일 공간 원천(M2폴리곤·M4배선 매퍼 권위)·워커 독립스케일·읽기복제 오프로드·역할별 프론트 분리 도식 | REQ-N-008~010·017·019, A-007·016, F-072·080·081 | P4 |
| 5 | 보안·개인정보(불변) | 10 | WT-4. REQ-S 20항목 커버리지 표 + 보안영역 분리도 + 워터마크·PII·감사로그·2FA. **감점/실격 리스크를 정면 방어** | REQ-S 20 전량, A-006·017 | P5 |
| 6 | 비기능(성능·가용성·접근성·다국어) | 8 | SLO 99.5%(성수기 99.9% 지향)·백엔드 2인스턴스 롤링 무중단·PG 스탠바이+PITR·나노바나나 40초/1024px·WCAG 2.1 AA+KWCAG 2.2·i18n 한/영/중/일·라이트/다크. **수치 SLA 표** | REQ-N 21 전량 | P6 |
| 7 | 멀티테넌시·확장성(COEX) | 5 | WT-5. 격리 아키텍처 + 온보딩 6단계 + tenant_id 선두 복합 인덱스. 제3전시장·타 전시관 확장 미래가치 | REQ-F-077~079, N-020, S-018 | P7 |
| 8 | 사업이해·추진전략 | 10 | As-Is 병목(HWP·CAD 수작업·kxwp·유틸리티 파편화) → To-Be 정량목표(견적 즉시·배치 수분·위치표시도 자동) 대비표. **킨텍스 실무 프로세스 정확 이해**(D-150/30/25/7 타임라인)로 도메인 신뢰 확보 | 전체 맥락 | P1·P2 |
| 9 | 사업관리·품질·일정 | 2 | Phase 1~3(코어→워크플로/운영→현장/확장) 간트 + QA 게이트 + Fail-Safe 배포 + 선행게이트(G1·G2) 관리. 배점 낮으나 실행력 신뢰 | REQ-N-004, S-019 | P8 |
| — | 기대효과 | (가점) | To-Be 정량 개선(견적 수일→즉시, 배치 수주→수분, 검수 육안→자동) + ROI·표준화·확장 스토리 | 목표표(§1-3) | P9 |
**분량 배분 원칙**: P3(35점)에 전체 슬라이드의 ~40%, 그중 절반을 나노바나나+M2~M5. P4·P5(각 10점) 각 ~8%, P6(8점) ~6%, P1+P2(10점) ~16%, P7(5점) ~5%, P8(2점) ~5%, P9 ~5%. 선택 기능은 압축.
---
## 3. 경쟁사 대비 강점 (Competitive Positioning)
> 근거 있는 비교만. 경쟁을 폄하하지 않고 "우리가 결합한 것"을 강조.
### 3-1. 글로벌 전시테크(ExpoPlatform·VenueSight·Swapcard·RainFocus 등) 대비
| 축 | 글로벌 전시테크 | 킨텍스 자동전시시스템 | 근거 |
|---|---|---|---|
| 시공 결과 시각화 | 도면·3D 뷰어 수준, 사진급 시공 예측 **미보유** | 나노바나나 image-to-image 구조보존 사진 생성 | PLANNING §1-2·§6, WT-1 |
| 공간 데이터 | 좌표·구역 관리 | **PostGIS 실측**(부스 폴리곤·트렌치 포인트·배선 LineString) 단일 원천 | REQ-N-008·017, data.md |
| 발주 연결 | 리드/매칭까지, 공사 발주 폐루프 약함 | AI 설계자료→역경매 응찰→낙찰→발주 자동전환 폐루프 | WT-3, §M15 |
| 킨텍스 도메인 정합 | 범용 글로벌 규격 | 킨텍스 규정(높이 5m·리깅·방염·바닥하중)·요율(2,250원/㎡)·D-데이 타임라인 내재화 | PLANNING §3, §7-1 |
| 데이터 주권 | 해외 SaaS·데이터 국외 | 온프레미스 Ollama 기본, 외부 AI는 승인 예외만·워커 env 격리 | REQ-S-001·002 |
**메시지**: "글로벌 전시테크의 기능(부스판매·리드·비즈매칭·BI)은 이식하되, 그들이 못 하는 **실측 공간데이터×시공 예측 이미지×옥션 폐루프**를 관통시켰다."
### 3-2. 기존 공공 SI(범용 웹시스템 구축) 대비
| 축 | 범용 SI | 킨텍스 자동전시시스템 | 근거 |
|---|---|---|---|
| AI 내재화 | 챗봇·검색 부가 수준 | 배치 3안·규정검증·시공 예측·수요예측이 **핵심 업무 자동화** | REQ-A 20항목 |
| 공간 연산 | 일반 CRUD | PostGIS GiST 실시간 공간쿼리(트렌치 KNN·통로버퍼·비상구 교차) | REQ-N-008 |
| 표준 프레임워크 | 개별 구축 | GUARDiA 표준(WISE/UIWS) 공통·시스템관리·JWT+2FA 이식으로 검증된 자산 재사용 | REQ-F-071~076, §5B |
| 확장성 | 단일 기관 | 멀티테넌트 SaaS(COEX 온보딩)로 재사용·표준화 | WT-5, §1A |
**메시지**: "범용 SI가 아니라 전시 도메인 전용 AI 자동화 플랫폼. 검증된 공통 프레임워크(UIWS/WISE) 위에 도메인 코어(M2~M5)와 폐루프(M15)를 얹어 **개발 리스크와 기간을 동시에 단축**한다."
### 3-3. 우리만의 3중 해자(Moat) — 한 장 요약
**나노바나나 시공 예측 이미지 ∩ PostGIS 실측 공간데이터 ∩ 공사 옥션 폐루프** — 이 세 가지의 결합은 단일 요소로는 모방 가능하나 **셋의 결합은 재현 난이도가 높다**. 제안서 P3 도입부에 "3원 벤다이어그램" 1장으로 각인.
---
## 4. 리스크 방어 논리 ([가정]·⚠확인필요 정면 대응)
> 평가위원이 반드시 파고들 "약한 고리"를 **선제적으로 드러내고 방어**한다. 숨기면 감점, 정면 대응하면 신뢰.
| # | 리스크(발주처 우려) | 방어 논리 (정면 대응) | 근거 | 제안서 위치 |
|---|---|---|---|---|
| R-1 | **G1 나노바나나 Gemini 외부 API 미승인 시 핵심 기능 붕괴?** | "승인 게이트 + degraded 폴백" 2중 설계. G1 미승인/Gemini 장애 시 워커 **목(mock) 응답·구조·워터마크 유지**로 화면·워크플로 계속 동작(REQ-N-005). 승인 확보를 **선행 게이트로 프로젝트 관리**(kintex-pm 통제). 외부 API는 워커 env only·백엔드 미취급으로 보안 격리 | REQ-S-001·002, N-005, C5 | P3 도입·P5·P8 |
| R-2 | **CAD·트렌치 실측 데이터 미확보로 배선·배치 정확도 의심?** | 미확보 정직 고지 + "공개 스펙 기반 가정 그리드 + '가정' 라벨"로 데모, **실측 반영을 킨텍스 협의 선행작업으로 명시**. 확보 자산(홀별 평면도 JPG 15장·CAD DWG "평면,트렌치.dwg")으로 실현성 입증 | C3, PLANNING R4, CLAUDE.md 확보자산 | P3 배선·P8 |
| R-3 | **kxwp/kxfp 폐쇄형 API 미공개로 제출 연동 불가?** | "초기 수동 릴레이 → 목표 API 연동" 단계적 접근. 웹폼→HWP/PDF 자동생성까지는 API 무관하게 완결, 릴레이 단계만 킨텍스 IT 협의(⚠확인필요 명시). 리스크를 범위·일정에 반영 | REQ-F-022, C2 | P3 서류·P8 |
| R-4 | **평가배점·제출규격이 가정이라 목차 정합성 의심?** | 배점 가정을 **투명 고지**하고 "실제 공고 확인 시 목차·분량 즉시 재정렬" 유연성 제시. 목차는 공공 SI 통례(사업이해→전략→기술→아키→보안→비기능→확장→관리→기대효과)로 안전 정렬 | rfp_analysis §4·§5, C1 | P1·목차 간지 |
| R-5 | **간판 한글 텍스트 등 생성 이미지 품질 편차?** | 간판 텍스트 비전 오탈자 검수 + 한글 렌더 실패 시 **간판영역 후처리 합성**(REQ-A-008). 자동생성은 S1·S7 한정·캐시·쿼터로 품질/비용 제어(REQ-N-007) | REQ-A-008, N-007, R5 | P3 AI·P6 |
| R-6 | **AI 환각·오판(규정 오검증·설계 오류) 책임?** | "AI는 보조, 사람이 최종 확정" 원칙 불변. 규정검증=플래깅까지, 구조안전 판정은 구조기술사/킨텍스(Non-Goal 명시). AI 답변은 RAG 근거·인용·환각 차단(abstain)(REQ-A-017) | Non-Goal §1-4, REQ-A-017 | P3·P5 |
| R-7 | **사이니지 HW·비콘·IoT 센서 연동 불확실?** | 선택(P2) 기능으로 분류, "킨텍스 시설 인프라 협의 전제" 명시. 미협의 시에도 코어 가치 불변(WT-1~4는 HW 독립) | REQ-F-070·052~055, C7 | P3 현장·P8 |
| R-8 | **다전시관 확장이 개발 부담을 키우지 않나?** | 멀티테넌시=격리 레이어만 추가(tenant_id 전파), 기능 로직 불변. 백필 전 단일테넌트 무중단 동작, 검증 후 필터 활성화(회귀 방지) | §1A-5, REQ-F-077 | P7 |
**방어 원칙**: 모든 [가정]·⚠확인필요 항목은 제안서 부록 "확인 필요·협의 사항" 1장으로 집약해 **정직성**을 오히려 강점화(발주처와의 협업 자세 어필).
---
## 5. writer·deck-designer 전달 지침
- **메시지 우선순위**: WT-1 > WT-2 > WT-3 > WT-4 > WT-5 순으로 슬라이드 무게. P3 도입부에 "3중 해자" 벤다이어그램 필수.
- **정량 강조**: 견적 수일→즉시, 배치 수주→수분, 검수 육안→자동, 40초 렌더, SLO 99.5%, REQ 142 커버리지 등 숫자를 표지·간지·기대효과에 반복 노출.
- **AI 신뢰 프레이밍**: "결정적 알고리즘(제약 솔버·PostGIS) 중심 + LLM 보조 + 사람 최종확정" 3층을 모든 AI 슬라이드 캡션에 삽입 → 공공 AI 불안 해소.
- **RTM 정합**: 전 142 REQ가 P1~P9 어딘가에 반영되도록 목차(§proposal_outline.md)의 REQ 매핑을 준수. 누락 0.
- **금지**: 시크릿·내부IP·미확보 데이터의 확정적 서술 금지. 미확보는 "가정/협의 전제" 라벨 필수.

366
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/rfp_analysis.md Normal file
View File

@ -0,0 +1,366 @@
# 킨텍스 자동전시시스템 구축 — 요구사항 분석서 (가상 RFP 기반)
> 작성: rfp-analyst · 작성일: 2026-07-11 · 버전 v1.0
> **성격**: 실제 RFP 문서는 부재하며, 발주처(킨텍스, 한국국제전시장)의 내부 기획 문서를 "가상 RFP"의 요구사항 원천으로 삼아 제안서 작성·평가 대응용으로 구조화 추출한 것이다.
> **근거 문서(출처)**: `docs/PLANNING.md`(v3.0), `docs/FEATURE_BACKLOG_100.md`(v1.1), `docs/SECURITY.md`, `docs/architecture/{app,system,tech,data,network}.md`, `CLAUDE.md`(kintex 섹션).
> **원칙**: 문서에 없는 요구는 발명하지 않는다(각 REQ에 출처 병기). 비밀번호·키·IP 등 시크릿은 미기재. 가정(assumption)은 "[가정]"으로 명시.
---
## 1. 사업 개요 (가정 포함)
| 항목 | 내용 | 근거/비고 |
|---|---|---|
| 사업명 | 킨텍스 자동전시시스템(Exhibition Automation Platform) 구축 | PLANNING §1-2-1 |
| 발주처(가정) | 킨텍스(KINTEX, 한국국제전시장) — 기준 테넌트 #1 | PLANNING §1A-1 |
| 사업 목적 | 전시장 운영 전 주기(홀 배정→부스 배치→장치공사 설계→전기/조명→네트워크/유틸리티 배선→반입/반출→관람객·정산·경영분석)를 AI로 자동 설계·검증하고, 시공 결과를 나노바나나(Gemini 이미지 생성)로 "공사 후 사진"처럼 사전 시각화 | PLANNING §1-2 |
| 정체성 | 부스 시공 도구를 넘어 전시 기획·판매·시공·운영·관람·사후분석 전 주기를 아우르는 베뉴 운영 플랫폼 + 다중 전시관(Venue) 멀티테넌트 SaaS(KINTEX #1, COEX 온보딩) | PLANNING §1-2-1·§1A |
| 범위 모듈 | 코어 M2~M5(P0), 판매·발주·정산 M1·M6·M7·M9·M15, 관람·참가 M8·M10~M14, 경영·콘텐츠·관리 M16~M18, 공통/시스템관리 레이어 §5B, 멀티테넌시 §1A | PLANNING §4-1 |
| 확정 기술스택 | React 18/19(Vite·TS) + Spring Boot 3.x(Java 17) + MyBatis + PostgreSQL(PostGIS) + Redis + 나노바나나 Python 워커 사이드카 | PLANNING §8, CLAUDE.md |
| AI 플랫폼 | 텍스트=Claude 기본(AiTextRouter/AiConfig, `ANTHROPIC_API_KEY` env) → Ollama 폴백 / 이미지=나노바나나(Gemini `gemini-3.1-flash-image-preview`) | FEATURE_BACKLOG §0, PLANNING §6-4 |
| 사용자 역할 | 6 행사역할(주최자·참가업체·장치/시공업체·홀매니저·관람객·일반대중) + 2 관리자계층(테넌트 관리자·플랫폼 슈퍼관리자) | PLANNING §2·§1A-4 |
| 로드맵(가정) | Phase 1 코어(~4개월)·Phase 2 워크플로/운영(~4개월)·Phase 3 현장/확장(~4개월+) | PLANNING §9 |
| 선행 게이트 | G1 나노바나나 Gemini 승인(외부 API), G2 개발/배포 서버(kintex.zioinfo.co.kr, PostGIS+Redis) | CLAUDE.md, PLANNING §10 R12 |
**[가정] 명시 항목**: 예산·계약방식·정확한 사업기간·평가배점·제출규격은 실제 RFP가 없어 공공 SI 통례를 가정한다(§4·§5).
---
## 2. 과업 범위
### 2-1. 기능 과업 범위 (모듈별)
| 계열 | 모듈 | 우선순위 | 범위 요지 | 출처 |
|---|---|---|---|---|
| 코어(불변) | M2 플로어플랜 스튜디오 | P0 | 부스 배치 3안 자동생성·선택/병합·규정 자동검증·버전 | PLANNING §M2 |
| 코어 | M3 부스 설계 스튜디오 | P0 | 조립/독립부스 설계 3안·규정 사전검증·도면 비전추출 | PLANNING §M3 |
| 코어 | M4 유틸리티 설계 | P0 | 전기·조명 용량/분전반/배선(M4a), 네트워크·급배수·압축공기·위치표시도(M4b) | PLANNING §M4 |
| 코어 | M5 나노바나나 시각화 | P0 | 시공 후 예상사진 표준 샷세트(S1~S7)·Before/After·워터마크 | PLANNING §M5·§6 |
| 판매·발주 | M1 홀 배정·자동견적 | P1 | 가용성 캘린더·규칙엔진 견적·배정신청 서식 | PLANNING §M1 |
| 판매·발주 | M6 서류·마일스톤 | P1 | D-150/30/25/7 역산·웹폼→HWP/PDF·AI 서류검수·kxwp 릴레이 | PLANNING §M6 |
| 판매·발주 | M7 등록업체 매칭 | P1 | 14분류×739개 업체 추천·RFQ·등록업체 검증 | PLANNING §M7 |
| 판매·발주 | M15 공사/장치 옥션 | P1(핵심) | 역경매·견적서(Quotation) 응찰·실시간 순위·종합평가 낙찰·발주전환 | PLANNING §M15 |
| 판매·발주 | M9 정산·결제 | P1 | 납부스케줄·PG결제·예치금 실사용 정산·세금계산서 | PLANNING §M9 |
| 물류 | M8 반입/반출 물류 | P2 | 슬롯예약·통행증 QR·중량물 우선·지게차 | PLANNING §M8 |
| 관람 | M10 관람객 등록·배지·리드 | P1 | 사전등록·모바일 배지/QR·현장 체크인·리드캡처·오프라인 폴백 | PLANNING §M10 |
| 관람 | M11 비즈니스 매칭 | P2 | AI 미팅추천·슬롯예약·성과 리포트 | PLANNING §M11 |
| 관람 | M12 마케팅·공개 홍보사이트 | P1 | SEO·다국어 공개사이트·인터랙티브 플로어플랜·세그먼트 EDM | PLANNING §M12 |
| 관람 | M13 wayfinding | P2 | 실내 내비(블루닷/존레벨)·POI 검색·경로 | PLANNING §M13 |
| 현장 | M14 현장운영 | P2 | 혼잡·전력부하·주차·안전위반 플래그 | PLANNING §M14 |
| 경영 | M16 경영분석 BI | P1(승격) | 가동률·매출구성·P&L·RevPAD·리텐션/LTV·수요예측·KPI(운영사+참가사 관점 분리) | PLANNING §M16·§M16-1 |
| 경영 | M17 CMS | P1 | 콘텐츠·공지·마이크로사이트·다국어·게시 워크플로·사이니지 | PLANNING §M17 |
| 관리 | M18 관리자 백오피스 | P1 | RBAC·감사·마스터데이터·룰셋 버전관리 | PLANNING §M18 |
| 공통 | §5B 공통/시스템관리 레이어 | P1(선행기반) | UIWS 표준 이식: 시스템관리·공통 업무모듈·JWT+2FA/OTP | PLANNING §5B |
| 멀티테넌시 | §1A 다중 전시관 SaaS | P1 | tenant_id 격리·컨텍스트 해소·2계층 관리자·온보딩 | PLANNING §1A·§8-2 |
### 2-2. 비기능 과업 범위
| 축 | 범위 | 출처 |
|---|---|---|
| 성능 | RenderJob 평균 40초·1024px 전처리, PostGIS GiST 실시간 응답, 읽기복제 BI 오프로드 | system.md §3-3, PLANNING §6-5 |
| 가용성/HA | 코어 경로 SLO 99.5%(성수기 99.9% 지향), 백엔드 최소 2인스턴스·롤링 무중단, PG 프라이머리-스탠바이+PITR, degraded 모드 | system.md §3-2 |
| 확장성 | 워커 독립 스케일(큐 깊이 기반), 공개영역 CDN, 역할별 프론트 번들 분리 | system.md §3-1 |
| 접근성 | WCAG 2.1 AA(핵심여정 AAA 지향), 공공 KWCAG 2.2 병행 | FEATURE_BACKLOG §6-N1 |
| 다국어 | 한(기본)+영/중/일, i18n 외부화·hreflang·로케일 포맷 | FEATURE_BACKLOG §6-N3 |
| 테마 | CSS 토큰 라이트/다크 2벌·시스템 연동 | FEATURE_BACKLOG §6-N4 |
| 공간데이터 | 부스 폴리곤·트렌치 포인트·배선 LineString 단일 PostGIS 원천 | data.md, PLANNING §7-3 |
| 보안 | §3 참조(REQ-S) | SECURITY.md |
### 2-3. 범위 제외(Non-Goals)
- 킨텍스 임대계약 법적 전자계약 체결(Phase 3 이후 검토) — 초기엔 견적·서류 준비까지. (PLANNING §1-4)
- 구조계산서의 구조 안전성 최종 판정(AI는 항목 체크·누락 검출까지, 판정은 구조기술사/킨텍스). (PLANNING §1-4·§M3)
- 소방 법규 최종 유권해석·승인(시스템은 사전 필터). (PLANNING §M2)
- 신규 전시관 고유 도메인 로직 자동생성(온보딩은 마스터데이터 입력 수준). (PLANNING §1-4·§1A-5)
---
## 3. 요구사항 목록
> ID 체계: 기능 `REQ-F-###`, 비기능 `REQ-N-###`, 보안 `REQ-S-###`, AI `REQ-A-###`.
> 유형: **필수** / **선택**(P2·확장·조건부). 확인 필요 항목은 "⚠확인필요"로 표기(삭제 금지).
### 3-1. 기능 요구사항 (REQ-F)
#### M1 판매·홀배정·견적
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-001 | 홀/반홀 가용성 실시간 캘린더 조회(행사일정 DB 연동) | 필수 | F001, §M1 |
| REQ-F-002 | 규칙엔진 자동 견적(2,250원/㎡×면적×일수×성수기/비수기/1전시장 계수+초과시간+예치금 15~20%) | 필수 | F002, §M1 |
| REQ-F-003 | 배정신청 웹폼 → 킨텍스 제출 서식(HWP) 자동 생성 | 필수 | F004, §M1 |
| REQ-F-004 | 부스 판매 인벤토리 관리(부스 단위 판매/홀드/예약 상태) | 필수 | F005 |
| REQ-F-005 | 온라인 부스 셀프 선택·판매(인터랙티브 맵) | 필수 | F006 |
| REQ-F-006 | 임대계약 전자서명 워크플로 | 선택 | F007(Phase3, Non-Goal 완화) |
#### M2 플로어플랜 스튜디오 (P0)
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-007 | 홀 선택·조건 입력 후 부스 배치 정확히 3안 자동생성(제약 솔버, 상이한 최적화 목표) | 필수 | F008, §M2 |
| REQ-F-008 | 배치안 선택 또는 구역/블록 병합 편집(안별 레이어 토글·드래그) | 필수 | F009, §M2 |
| REQ-F-009 | 배치 규정 자동검증(피난통로·바닥하중 홀별·비상구·복층가능홀·소방 체크리스트), 병합 후 재검증 | 필수 | F010, §M2 |
| REQ-F-010 | 최종안 버전 기록(선택/병합 출처 안번호 추적)·부스별 좌표/번호 확정·참가업체 초대 링크 발급 | 필수 | §M2 |
#### M3 부스 설계 스튜디오 (P0)
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-011 | 조립부스 옵션(간판·가구·조명) 웹 선택·3D 프리뷰 | 필수 | F012, §M3 |
| REQ-F-012 | 독립부스 레이아웃·파라메트릭 구조 3안 자동생성·선택/병합·버전 기록 | 필수 | F011, §M3 |
| REQ-F-013 | 설계 규정 사전검증(높이 5m·리깅 6.5~8.5m·복층 1/2·방염·이격 30/60cm·금지작업) 제출 전 플래깅 | 필수 | F013, §M3 |
| REQ-F-014 | 도면(PDF/이미지) 업로드 비전 추출·치수/구조 검증("참고용 검증" 라벨) | 필수 | F014, §M3 |
#### M4 유틸리티 설계 (P0)
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-015 | 기기목록→kW 합산→분전반 용량/수량 자동 산출 | 필수 | F015, §M4a |
| REQ-F-016 | 최근접 트렌치→분전반 배선 경로 자동생성(통로 횡단 최소화, PostGIS 최단) | 필수 | F016, §M4 |
| REQ-F-017 | 유틸리티 위치표시도 자동생성(좌표 클릭, 수기 작도 폐지) | 필수 | F017, §M4b |
| REQ-F-018 | 네트워크·급배수·압축공기 신청·자동견적·마감(D-25) 역산 리마인더 | 필수 | F038, §M4b |
| REQ-F-019 | 조명 조도목표별 배치안 제안(전시품 강조/상담존) | 선택 | F018, §M4a |
#### M6 서류·마일스톤
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-020 | D-150/30/25/7 마일스톤 자동생성·역산 알림 | 필수 | F021, §M6 |
| REQ-F-021 | 신고서류 7종+ 웹폼→HWP/PDF 자동생성(킨텍스 제출 형식) | 필수 | F022, §M6 |
| REQ-F-022 | kxwp 제출 파일 릴레이·업로드 안내(초기 수동 릴레이, 목표 API) ⚠확인필요(폐쇄형 API 미공개) | 필수 | F027, §M6·R3 |
| REQ-F-023 | 서류 버전·다단계 전자결재 워크플로 | 필수 | F028, §5B |
| REQ-F-024 | OCR 계약·납품서 자동 등록 | 필수 | F026 |
#### M15 공사/장치 옥션 (P1 핵심)
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-025 | 역경매 옥션 개설·라운드·마감(유형 설정형: 역경매/단일라운드 RFQ/고정가 비교) | 필수 | F029, §M15 |
| REQ-F-026 | AI 생성 자료(M2배치·M3설계·M4배선/BOQ·M5이미지) 열람 기반 견적서(Quotation) 제출·PDF·버전 | 필수 | F030, §M15 |
| REQ-F-027 | 실시간 순위·최저가·내 위치 노출(익명 옵션)·라운드 종료 자동마감 | 필수 | F031, §M15 |
| REQ-F-028 | 종합평가 낙찰 스코어(가격+평판+납기 가중)·항목별 비교표 | 필수 | F032, §M15 |
| REQ-F-029 | 등록업체 검증 게이트 — 미등록 업체 응찰 원천 차단 | 필수 | F033, §M15·§M7 |
| REQ-F-030 | 등록업체 AI 매칭 추천(규모·업종·지역) | 필수 | F034, §M7 |
| REQ-F-031 | 물량서(BOQ) 설계기반 자동산출 | 필수 | F035, §M4·§M15 |
| REQ-F-032 | 낙찰(Award)→계약/발주 문서 자동전환(M6·M9 연동) | 필수 | F036, §M15 |
#### M8 물류
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-033 | 반입/반출 하역장 슬롯 예약제 | 선택 | F039, §M8 |
| REQ-F-034 | 통행증 QR 발급·중량물 우선배치 | 선택 | F040, §M8 |
| REQ-F-035 | 지게차·부대장비 신청 연동, 부대물품 렌탈 주문 | 선택 | F041·F042, §M8 |
| REQ-F-036 | 철거 피크 대기열 시뮬레이션 | 선택 | F044, §M8 |
#### M10 관람객 등록·배지·리드
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-037 | 온라인 사전등록(유형별 폼·중복 검증) | 필수 | F045, §M10 |
| REQ-F-038 | 모바일 배지/QR 발급 | 필수 | F047, §M10 |
| REQ-F-039 | 현장 QR 체크인·즉석 배지 인쇄·실시간 입장 집계 | 필수 | F048, §M10 |
| REQ-F-040 | 오프라인 체크인 폴백(현장 네트워크 장애 대비 후동기화) | 필수 | F049, §M10, network.md |
| REQ-F-041 | 참가업체 리드캡처(배지 QR 스캔·관심도·메모) | 필수 | F050, §M10 |
| REQ-F-042 | AI 리드 스코어링·자동 분류 | 선택 | F051 |
| REQ-F-043 | 리드 팔로업 세그먼트 EDM 자동 | 필수 | F052, §M10·§M12 |
| REQ-F-044 | 티켓 발권·유료 등록 결제, AI 폼빌더, 스마트배지 | 선택 | F053·F046·F054 |
#### M11 비즈매칭·이벤트앱
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-045 | AI 비즈매칭 추천(프로필·intent) | 선택 | F055, §M11 |
| REQ-F-046 | 미팅 슬롯 예약·일정관리·성과 리포트 | 선택 | F056·F062, §M11 |
| REQ-F-047 | 이벤트 모바일앱(일정·부스·프로필), 세션·아젠다, 인앱 채팅, 실시간 설문 | 선택 | F057~F061 |
#### M12 마케팅·공개 홍보사이트
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-048 | 공개 홍보 사이트(SEO·다국어 한/영/중/일·SSR/정적) | 필수 | F063, §M12 |
| REQ-F-049 | 공개 인터랙티브 플로어플랜(M2 데이터 부산물) | 필수 | F064, §M12 |
| REQ-F-050 | 세그먼트 EDM·캠페인 자동화·리마인더 | 필수 | F065, §M12 |
| REQ-F-051 | 스폰서십 패키지·판매·이행 관리 + 스폰서 대시보드 | 필수 | F070·F071 |
#### M13·M14 현장/wayfinding
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-052 | 실내 wayfinding(블루닷/존레벨 폴백)·POI 검색·경로안내 | 선택 | F072·F073, §M13 |
| REQ-F-053 | 실시간 입장·혼잡 모니터·오버플로 예측 | 선택 | F074, §M14 |
| REQ-F-054 | 홀 전력부하 집계·에너지 모니터, 주차 점유 연동 | 선택 | F075·F077, §M14 |
| REQ-F-055 | 안전 위반·소음·금지작업 자동 플래그·신고, 현장 이상탐지 알림 | 선택 | F076·F079, §M14 |
#### M9 정산·결제
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-056 | 납부 스케줄(계약금/중도금/잔금/예치금) 자동생성·알림 | 필수 | F080, §M9 |
| REQ-F-057 | 유틸리티·부대 PG 결제 | 필수 | F081, §M9 |
| REQ-F-058 | 예치금 대비 실사용(검침) 정산 투명화 | 필수 | F082, §M9 |
| REQ-F-059 | 세금계산서·정산 리포트 자동, 옥션 수수료 정산 연동 | 필수 | F083·F084, §M9 |
| REQ-F-060 | 환불·취소 규정 자동 적용 | 선택 | F085 |
#### M16 경영분석 BI
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-061 | 홀·기간별 가동률(occupancy) 대시보드(반홀 분할·성수기 구분) | 필수 | F086, §M16-1① |
| REQ-F-062 | 매출 구성(임대·유틸리티·부대·옥션 수수료)·행사별 P&L | 필수 | F087, §M16-1②③ |
| REQ-F-063 | 전시장 ROI·RevPAD·㎡당 수익(㎡ 정규화) | 필수 | F088, §M16-1④ |
| REQ-F-064 | 참가사 리텐션·LTV 코호트 | 필수 | F089, §M16-1⑤ |
| REQ-F-065 | 참가업체 관점 ROI(리드 기반) — 운영사 관점과 대시보드/권한 격리 | 필수 | F091, §M16-1 |
| REQ-F-066 | 경영진 KPI 대시보드(목표 대비 실적·드릴다운) | 필수 | F093, §M16-1⑦ |
#### M17 CMS
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-067 | 전시 콘텐츠·공지 게시 워크플로(초안→검수→게시)·버전관리 | 필수 | F068, §M17 |
| REQ-F-068 | 참가업체 마이크로사이트(부스·제품·나노바나나 예상샷) | 필수 | F067, §M17 |
| REQ-F-069 | 다국어(한/영/중/일) 콘텐츠 관리·hreflang | 필수 | F069, §M17 |
| REQ-F-070 | 디지털 사이니지 콘텐츠 중앙 배포 ⚠확인필요(사이니지 HW 연동 킨텍스 협의) | 선택 | F078, §M17 |
#### M18·§5B·§1A 관리·공통·멀티테넌시
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-F-071 | RBAC·감사로그·시스템설정 백오피스(admin. 웹 전용) | 필수 | F094, §M18·§5B-1 |
| REQ-F-072 | 룰셋·마스터데이터(홀·요율·규정·부스표준) 버전관리·무중단 개정 | 필수 | F095, §M18 |
| REQ-F-073 | 공통코드·메뉴 관리(도메인 코드: 홀/부스유형/공종14/유틸요금) | 필수 | §5B-1 |
| REQ-F-074 | 공통 업무모듈: 업무일지·일정·쪽지·공지·의견·통합검색 | 필수 | F098, §5B-2 |
| REQ-F-075 | 회의록(녹음→STT→회의록 PDF), 일/주/월/분기/연 업무보고·통계 PDF | 필수 | §5B-2 |
| REQ-F-076 | 통합 알림센터(마감 D-데이·낙찰·승인·결제, WebSocket) | 필수 | §5B-2 |
| REQ-F-077 | 멀티테넌트 격리·전시관 온보딩(코드 배포 없이 데이터 온보딩 6단계) | 필수 | F096, §1A·§8-2 |
| REQ-F-078 | 테넌트 컨텍스트 해소(서브도메인 우선+사용자소속 보조, 불일치 거부) | 필수 | §1A-3 |
| REQ-F-079 | 2계층 관리자(플랫폼 슈퍼관리자 테넌트스위처 / 테넌트 관리자 단일스코프) | 필수 | §1A-4 |
| REQ-F-080 | API·웹훅·CRM/ERP 연동 게이트웨이 | 선택 | F099 |
| REQ-F-081 | 역할별 프론트 포털 분리(organizer·exhibitor·contractor·ops·admin·public+visitor) 공유 디자인시스템 상속 | 필수 | §2-1, §8-1 |
### 3-2. AI 요구사항 (REQ-A)
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-A-001 | 나노바나나 시공 예상 사진 표준 샷세트(S1 정면·S2 야간·S3 통로·S4 내부·S5 Before/After·S7 홀전경) 생성 | 필수 | F019, §6-3 |
| REQ-A-002 | image-to-image 구조보존(참조이미지 inlineData+지시문) — 골격/치수/통로/카메라 앵글 잠금, 스타일만 사실화 | 필수 | §6-4 |
| REQ-A-003 | 구조화 프롬프트 사전(BOOTH_TYPES·BOOTH_STYLES·FIXTURE_LAYERS) 조립·보존/교체 명시 분리 | 필수 | §6-4 |
| REQ-A-004 | S6 배선 오버레이 백엔드 래스터 합성 우선(전기 적·네트워크 청·급배수 녹, 좌표 정확) | 필수 | §6-3 |
| REQ-A-005 | Before/After 드래그 슬라이더(빈 부스↔시공 후, ARIA·키보드) | 필수 | F020, §6-5 |
| REQ-A-006 | RenderJob 방어(다층 크기가드·mimeType 자동감지·SAFETY 분기·친화적 한글 에러·성공 시에만 쿼터 차감) | 필수 | §6-5 |
| REQ-A-007 | 단계별 로딩 UX(골격인식→집기→배선→렌더) aria-live 순환·비동기 큐·WebSocket 완료 푸시 | 필수 | §6-5, §8 |
| REQ-A-008 | 간판 텍스트 비전 오탈자 검수 + 한글 렌더 실패 시 간판영역 후처리 합성 | 필수 | §6-4, R5 |
| REQ-A-009 | 부스 배치 3안 AI 자동생성(제약 솔버 + LLM 조건해석, 결정적 알고리즘 중심) | 필수 | F008, §M2 |
| REQ-A-010 | AI 규정 자동검증(배치·설계 규정 위반 플래깅) | 필수 | F010·F013 |
| REQ-A-011 | AI 서류 검수(누락·배치도-계획서 불일치 검출) | 필수 | F023, §M6 |
| REQ-A-012 | 규정 자연어 챗봇(근거·인용 기반) | 선택 | F025 |
| REQ-A-013 | AI 수요예측·수율/동적가격 시뮬레이션 | 필수 | F090·F003, §M16-1⑥ |
| REQ-A-014 | AI 경영진 KPI 요약·인사이트 브리핑 자동, 자연어 조회(Text-to-SQL) | 필수/선택 | F093/F092 |
| REQ-A-015 | AI 카피·이미지 초안 생성, 다국어 콘텐츠 자동번역+검수 | 필수 | F066·F069, §M12·§M17 |
| REQ-A-016 | AI 플랫폼 라우터(Claude 기본→Ollama 폴백)·중앙경유·LLM 직접호출 신설 금지 | 필수 | F100, §6, FEATURE_BACKLOG §0 |
| REQ-A-017 | AI 답변 근거(RAG)·인용·환각 차단(abstain) | 필수 | FEATURE_BACKLOG §0 |
| REQ-A-018 | AI 리드 스코어링, 비즈매칭 추천, 세션/부스 추천 | 선택 | F051·F055·F059 |
| REQ-A-019 | 현장 이상탐지·혼잡/철거 대기열 예측 | 선택 | F074·F044·F079 |
| REQ-A-020 | 도면 비전 추출(치수·구조), OCR 문서 자동등록 | 필수 | F014·F026 |
### 3-3. 비기능 요구사항 (REQ-N)
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-N-001 | 코어 인증·설계·조회 경로 가용성 SLO 99.5%(성수기 99.9% 지향) | 필수 | system.md §3-2 |
| REQ-N-002 | 백엔드 최소 2 인스턴스+헬스체크 LB·롤링 무중단 배포 | 필수 | system.md §3-2 |
| REQ-N-003 | PostgreSQL 프라이머리-스탠바이 스트리밍 복제+자동 failover+PITR 백업 | 필수 | system.md §3-2 |
| REQ-N-004 | Fail-Safe 배포(백업→배포→헬스체크 200→실패 시 롤백) | 필수 | system.md §3-2 |
| REQ-N-005 | degraded 모드(G1 미승인/Gemini 장애 시 워커 목 응답·구조·워터마크 유지, Claude 실패 시 Ollama 폴백) | 필수 | system.md §3-2 |
| REQ-N-006 | 나노바나나 생성 성능: 평균 40초 목표·1024px 다운스케일+JPEG 0.85 전처리 | 필수 | system.md §3-3, §6-5 |
| REQ-N-007 | 대량 동시 생성 제어: 자동생성 S1·S7 한정·동일 스키마해시 캐시·행사별 RenderJob 쿼터 | 필수 | system.md §3-3, R6 |
| REQ-N-008 | 공간쿼리 성능: 전 geom 컬럼 GiST 인덱스(트렌치 KNN·통로버퍼·비상구 교차 실시간) | 필수 | data.md §3-4 |
| REQ-N-009 | 워커 독립 스케일(큐 깊이 기반 증감), 백엔드 응답성과 분리 | 필수 | system.md §3-1 |
| REQ-N-010 | BI·공개조회·플로어플랜 열람 읽기복제 오프로드(운영 프라이머리 보호) | 필수 | system.md §3-1, §8-1 |
| REQ-N-011 | 워커 장애 시 가시성 타임아웃 후 재큐(멱등 Job) | 필수 | system.md §3-2 |
| REQ-N-012 | 웹접근성 WCAG 2.1 AA(핵심여정 AAA 지향)·공공 KWCAG 2.2 병행 | 필수 | FEATURE_BACKLOG §6-N1 |
| REQ-N-013 | 캔버스/맵 비시각 대안(데이터 테이블·검색·키보드 선택) 필수 제공 | 필수 | FEATURE_BACKLOG §6-N1 |
| REQ-N-014 | 다국어 i18n 외부화(한 기본+영/중/일)·로케일 전환·hreflang·로케일 포맷 | 필수 | FEATURE_BACKLOG §6-N3 |
| REQ-N-015 | 라이트/다크 테마 CSS 토큰 2벌·prefers-color-scheme 연동·선택 영속 | 필수 | FEATURE_BACKLOG §6-N4 |
| REQ-N-016 | 반응형(데스크톱=설계/에디터, 모바일=현장/조회/승인) | 필수 | PLANNING §8, §2-1 |
| REQ-N-017 | 단일 공간 원천(M2폴리곤·M4배선 매퍼 권위, 소비 모듈 조회만·중복 저장 금지) | 필수 | app.md, data.md |
| REQ-N-018 | 관측성(로그·메트릭·트레이스) 관리존 수집, 로그에 자격증명·PII·스택트레이스 미기록 | 필수 | network.md, tech.md |
| REQ-N-019 | 공개영역 CDN·요청률 상한·slowloris 타임아웃(가용성 계층 방어) | 필수 | network.md §7 |
| REQ-N-020 | tenant_id 선두 복합 인덱스 표준화(격리 쿼리 성능) | 필수 | §8-2 |
| REQ-N-021 | BI 데이터마트(스타 스키마 Fact/Dim) 야간 배치 ETL 또는 읽기복제 적재 | 필수 | data.md, §M16-1 |
### 3-4. 보안 요구사항 (REQ-S)
| REQ-ID | 요구사항 | 유형 | 출처 |
|---|---|---|---|
| REQ-S-001 | 외부 API 정책: 온프레미스 Ollama 기본, Claude(api.anthropic.com)·Gemini(나노바나나)만 승인 예외, 그 외 금지 | 필수 | SECURITY.md §1 |
| REQ-S-002 | GEMINI_API_KEY 나노바나나 Python 워커 env only(백엔드 미취급), Spring은 큐/콜백만 | 필수 | SECURITY.md §1 |
| REQ-S-003 | 자격증명·키·내부IP·SSH·워커토큰 응답/로그/에러/커밋 완전 제외·마스킹 | 필수 | SECURITY.md §2 |
| REQ-S-004 | admin 비밀번호 env `ADMIN_PASSWORD_ENC`(AES-256-GCM)+별도 키파일→기동 시 BCrypt 재시드, 하드코딩 시드 금지 | 필수 | SECURITY.md §3 |
| REQ-S-005 | JWT(HS256)+2차 인증 OTP/EMAIL(TOTP RFC6238)+로그인 실패 잠금(관리자 해제) | 필수 | SECURITY.md §4, §5B-3 |
| REQ-S-006 | 행사 단위 RBAC(열람=멤버/홀매니저, 편집=역할별 게이트) — 테넌트 격리 ⊃ 행사 RBAC 3중 | 필수 | SECURITY.md §4, §2 |
| REQ-S-007 | 미등록 장치업체 초대·응찰 차단(NOT_REGISTERED_COMPANY 403) | 필수 | SECURITY.md §4, §M15 |
| REQ-S-008 | `/api/admin/**`=ADMIN 게이트, `/api/internal/**`=워커 공유 시크릿(X-Worker-Token)만 | 필수 | SECURITY.md §4 |
| REQ-S-009 | M5 나노바나나 이미지 응답 항상 watermarkRequired:true+watermarkText+notice(계약·심사 서류 금지) | 필수 | SECURITY.md §5, §6-6 |
| REQ-S-010 | 오류 응답 스택트레이스·relation/컬럼명·내부경로 미노출(ApiResponse.error 요약만) | 필수 | SECURITY.md §6 |
| REQ-S-011 | DataAccessException @RestControllerAdvice로 INTERNAL 요약 매핑(테이블/컬럼 누출 차단) | 필수 | SECURITY.md §6, system.md |
| REQ-S-012 | 민감 액션(승인·낙찰·설계변경·룰셋개정·리드접근·로그인/권한변경) TB_AUDIT_LOG 전수(tenant_id 포함) | 필수 | SECURITY.md §7, §6-N2 |
| REQ-S-013 | PII(관람객·리드) 동의·보존정책·최소수집·마스킹·응답 완전 제외, `*_enc` AES-256-GCM | 필수 | data.md §5, R10 |
| REQ-S-014 | 입력 검증(Bean Validation 화이트리스트·파일 MIME/크기 가드) | 필수 | FEATURE_BACKLOG §6-N2 |
| REQ-S-015 | XSS 방지(React 이스케이프·dangerouslySetInnerHTML 금지·CMS sanitize·CSP) | 필수 | FEATURE_BACKLOG §6-N2 |
| REQ-S-016 | 인젝션 차단(MyBatis `#{}` 강제·`${}` 금지, PostGIS/명령/LDAP) | 필수 | FEATURE_BACKLOG §6-N2 |
| REQ-S-017 | IDOR 방지(리소스 소유·tenant_id 검증), CSRF/SameSite·JWT 만료·회전 | 필수 | FEATURE_BACKLOG §6-N2 |
| REQ-S-018 | fail-closed 다층 테넌트 격리(컨텍스트 필터→서비스 가드→MyBatis 공통 인터셉터→PostGIS) | 필수 | §8-2 |
| REQ-S-019 | 의존성 취약점 SCA(OWASP Dependency-Check) CI 게이트·정기 패치 | 필수 | FEATURE_BACKLOG §6-N2 |
| REQ-S-020 | 보안영역 분리(공개 DMZ 쓰기권한 없음·데이터존 직결 불가, DMZ↔내부 HTTPS만·DB 프로토콜 횡단 금지) | 필수 | network.md |
---
## 4. 평가 관점 (공공 SI 표준 배점 — 가정)
> 실제 RFP·평가표가 없어 공공 정보화 SI 통례를 가정한다. **[가정]** — 실제 공고 확인 시 교체.
| 구분 | 평가부문 | 배점(가정) | win theme 우선순위 근거 |
|---|---|---|---|
| 기술 | 사업이해·추진전략 | 10 | 전시 도메인·As-Is 병목 이해(§3) |
| 기술 | **AI 시각화·설계 자동화(핵심 차별화)** | **20** | M2~M5 P0 코어 + 나노바나나 시공 예측(경쟁 전시테크 미보유 폐루프) |
| 기술 | 기능 구현(M1~M18 전 모듈) | 15 | 100대 기능(이미 63·부분 18·신규 19) |
| 기술 | 아키텍처·기술스택 | 10 | 확정 스택 정합·PostGIS 공간데이터·Python 워커 사이드카 |
| 기술 | 보안·개인정보(SECURITY 불변) | 10 | REQ-S 20항목·워터마크·PII·테넌트 격리 |
| 기술 | 비기능(성능·가용성·접근성·다국어) | 8 | SLO 99.5%·WCAG AA·KWCAG·i18n |
| 기술 | 멀티테넌시·확장성(COEX 온보딩) | 5 | §1A SaaS 확장 |
| 기술 | 사업관리·품질·일정 | 2 | Phase 1~3·QA 게이트 |
| **기술 소계** | | **80** | |
| 가격 | 입찰가격 | 20 | |
| **총계** | | **100** | |
**win theme 우선순위(배점 가중)**: ① 나노바나나 시공 예측 시각화(최고 차별화, 20점) → ② 부스 배치·설계·배선 AI 자동화 폐루프(M2~M5) → ③ 공사 옥션(M15) 발주 종결 → ④ 보안·개인정보·워터마크(공공 신뢰) → ⑤ 멀티테넌트 SaaS 확장.
---
## 5. 제출 규격 (가정)
> 실제 RFP 규격이 없어 공공 SI 제안 통례를 가정한다. **[가정]** — 실제 공고 확인 시 교체.
| 항목 | 가정값 | 비고 |
|---|---|---|
| 제안서 형식 | PowerPoint(.pptx) 기술제안서 | proposal-builder 파이프라인 정합 |
| 분량 | 자율(권장 40~80p) | 실제 공고 확인 필요 |
| 목차 | 사업이해→추진전략→기술제안(AI 시각화·설계·옥션·관람·BI)→아키텍처→보안→비기능→멀티테넌시→사업관리→기대효과 | §4 배점 정합 |
| 서식 | 발주처 지정 시 준수, 미지정 시 표준 제안 템플릿 | ⚠확인필요 |
| 필수 도식 | 모듈맵(§4)·아키텍처(§8)·나노바나나 파이프라인(§6)·옥션 플로우(§M15)·추진체계·일정(Phase 1~3) | PLANNING 근거 |
| 제출 부수·마감 | ⚠확인필요(실제 공고) | — |
| 자격요건 | ⚠확인필요(실적·인증 — CSAP/ISMS 등 공공 요건 가능성) | — |
---
## 6. 확인 필요·상충 항목 (삭제 금지)
| # | 항목 | 사유 |
|---|---|---|
| C1 | 예산·계약방식·사업기간·평가배점·제출규격 | 실제 RFP 부재 — 전부 가정, 공고 확인 시 교체 |
| C2 | kxwp/kxfp API 연동 | 폐쇄형·API 미공개, 킨텍스 IT 협의 필수(R3) — 초기 수동 릴레이 |
| C3 | 트렌치·CAD 실측 데이터 | 미확보, 공개 스펙 기반 가정 그리드+'가정' 라벨(R4) |
| C4 | 인터넷 요금 정합성(150,000원 vs KT 80,000원 병존) | 킨텍스 확인 필요(R8) |
| C5 | 나노바나나 Gemini 외부 API 승인(G1) | 미승인 시 온프레미스 폴백 검토(R12) |
| C6 | 코엑스 등 신규 전시관 홀·요율·규정 실측 | 미확보, 온보딩 시 입력·근거 없는 추정 금지(§1A-5) |
| C7 | 사이니지 HW·비콘(wayfinding)·IoT 센서 연동 | 킨텍스 시설 인프라 협의 전제(M13·M14·M17) |
| C8 | 자격요건(공공 인증 CSAP/ISMS 등) | 실제 공고 확인 필요 |
---
## 부록. REQ 총계
| 유형 | 개수 |
|---|---|
| REQ-F (기능) | 81 |
| REQ-A (AI) | 20 |
| REQ-N (비기능) | 21 |
| REQ-S (보안) | 20 |
| **총계** | **142** |
</content>

196
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/rtm.md Normal file
View File

@ -0,0 +1,196 @@
# 요구사항 추적표 (RTM) — 킨텍스 자동전시시스템 제안서
> 작성: rfp-analyst · 작성일: 2026-07-11 · 버전 v1.0
> 짝 문서: `rfp_analysis.md`(요구사항 정의). 본 RTM은 **REQ-ID ↔ 제안서 목차 섹션 1:1 매핑 준비 + 평가부문 매핑 + 반영 상태**의 단일 진실원천이다.
> 사용법: writer/deck-designer가 각 REQ를 제안서 본문/슬라이드에 반영하며 "제안서 섹션" 및 "반영상태(☐미반영/◑작성중/☑완료)"를 갱신한다. QA는 전 REQ 반영 여부를 이 표로 교차 점검한다.
> 제안서 목차 코드: **P1**사업이해 · **P2**추진전략 · **P3**기술제안(AI 시각화·설계·옥션·관람·BI) · **P4**아키텍처 · **P5**보안·개인정보 · **P6**비기능 · **P7**멀티테넌시·확장 · **P8**사업관리·일정·조직 · **P9**기대효과. (평가부문은 rfp_analysis §4 배점 기준)
---
## 1. 기능 요구사항 (REQ-F)
| REQ-ID | 요구사항 요약 | 유형 | 모듈 | 제안서 섹션(준비) | 평가부문 | 반영상태 |
|---|---|---|---|---|---|---|
| REQ-F-001 | 홀/반홀 가용성 실시간 캘린더 | 필수 | M1 | P3 판매·견적 | 기능 구현 | ☐ |
| REQ-F-002 | 규칙엔진 자동 견적 | 필수 | M1 | P3 판매·견적 | 기능 구현 | ☐ |
| REQ-F-003 | 배정신청 웹폼→HWP 자동생성 | 필수 | M1 | P3 판매·견적 | 기능 구현 | ☐ |
| REQ-F-004 | 부스 판매 인벤토리 관리 | 필수 | M1/M2 | P3 판매·견적 | 기능 구현 | ☐ |
| REQ-F-005 | 온라인 부스 셀프 선택·판매 | 필수 | M2 | P3 판매·견적 | 기능 구현 | ☐ |
| REQ-F-006 | 임대계약 전자서명 | 선택 | M6/M9 | P3 판매·견적 | 기능 구현 | ☐ |
| REQ-F-007 | 부스 배치 3안 자동생성 | 필수 | M2 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-008 | 배치안 선택/병합 편집 | 필수 | M2 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-009 | 배치 규정 자동검증·병합 후 재검증 | 필수 | M2 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-010 | 최종안 버전기록·부스좌표 확정·초대링크 | 필수 | M2 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-011 | 조립부스 옵션·3D 프리뷰 | 필수 | M3 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-012 | 독립부스 설계 3안·선택/병합·버전 | 필수 | M3 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-013 | 설계 규정 사전검증(높이·리깅·방염·이격) | 필수 | M3 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-014 | 도면 업로드 비전 추출·검증 | 필수 | M3 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-015 | 전기 용량·분전반 자동산출 | 필수 | M4a | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-016 | 배선 경로 자동생성(PostGIS 최단) | 필수 | M4 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-017 | 위치표시도 자동생성 | 필수 | M4b | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-F-018 | 네트워크·급배수·압축공기 신청·마감 리마인더 | 필수 | M4b | P3 AI 시각화·설계 | 기능 구현 | ☐ |
| REQ-F-019 | 조명 조도 배치안 제안 | 선택 | M4a | P3 AI 시각화·설계 | AI 시각화·설계 | ☐ |
| REQ-F-020 | 마일스톤 자동생성·역산 알림 | 필수 | M6 | P3 서류·워크플로 | 기능 구현 | ☐ |
| REQ-F-021 | 신고서류 웹폼→HWP/PDF 자동생성 | 필수 | M6 | P3 서류·워크플로 | 기능 구현 | ☐ |
| REQ-F-022 | kxwp 제출 파일 릴레이 ⚠확인필요 | 필수 | M6 | P3 서류·워크플로 | 기능 구현 | ☐ |
| REQ-F-023 | 서류 버전·전자결재 워크플로 | 필수 | M6/§5B | P3 서류·워크플로 | 기능 구현 | ☐ |
| REQ-F-024 | OCR 계약·납품서 자동등록 | 필수 | AI | P3 서류·워크플로 | 기능 구현 | ☐ |
| REQ-F-025 | 역경매 옥션 개설·라운드·마감 | 필수 | M15 | P3 공사 옥션 | AI 시각화·설계(폐루프) | ☐ |
| REQ-F-026 | AI 자료 기반 견적서 응찰·PDF·버전 | 필수 | M15 | P3 공사 옥션 | AI 시각화·설계(폐루프) | ☐ |
| REQ-F-027 | 실시간 순위·자동마감 | 필수 | M15 | P3 공사 옥션 | 기능 구현 | ☐ |
| REQ-F-028 | 종합평가 낙찰 스코어·비교표 | 필수 | M15 | P3 공사 옥션 | 기능 구현 | ☐ |
| REQ-F-029 | 등록업체 검증 게이트(응찰 차단) | 필수 | M15/M7 | P3 공사 옥션 / P5 보안 | 보안·개인정보 | ☐ |
| REQ-F-030 | 등록업체 AI 매칭 추천 | 필수 | M7 | P3 공사 옥션 | 기능 구현 | ☐ |
| REQ-F-031 | 물량서(BOQ) 자동산출 | 필수 | M4/M15 | P3 공사 옥션 | AI 시각화·설계 | ☐ |
| REQ-F-032 | 낙찰→계약·발주 자동전환 | 필수 | M15 | P3 공사 옥션 | 기능 구현 | ☐ |
| REQ-F-033 | 반입/반출 슬롯 예약 | 선택 | M8 | P3 참가·물류 | 기능 구현 | ☐ |
| REQ-F-034 | 통행증 QR·중량물 우선 | 선택 | M8 | P3 참가·물류 | 기능 구현 | ☐ |
| REQ-F-035 | 지게차·부대장비·렌탈 주문 | 선택 | M8 | P3 참가·물류 | 기능 구현 | ☐ |
| REQ-F-036 | 철거 대기열 시뮬레이션 | 선택 | M8 | P3 참가·물류 | AI 시각화·설계 | ☐ |
| REQ-F-037 | 온라인 사전등록(유형별·중복검증) | 필수 | M10 | P3 관람 | 기능 구현 | ☐ |
| REQ-F-038 | 모바일 배지/QR 발급 | 필수 | M10 | P3 관람 | 기능 구현 | ☐ |
| REQ-F-039 | 현장 QR 체크인·즉석 인쇄·집계 | 필수 | M10 | P3 관람 | 기능 구현 | ☐ |
| REQ-F-040 | 오프라인 체크인 폴백 | 필수 | M10 | P3 관람 / P6 비기능 | 비기능 | ☐ |
| REQ-F-041 | 참가업체 리드캡처 | 필수 | M10 | P3 관람 | 기능 구현 | ☐ |
| REQ-F-042 | AI 리드 스코어링·분류 | 선택 | AI | P3 관람 | AI 시각화·설계 | ☐ |
| REQ-F-043 | 리드 팔로업 세그먼트 EDM | 필수 | M10/M12 | P3 관람 | 기능 구현 | ☐ |
| REQ-F-044 | 티켓발권·AI폼빌더·스마트배지 | 선택 | M10 | P3 관람 | 기능 구현 | ☐ |
| REQ-F-045 | AI 비즈매칭 추천 | 선택 | M11 | P3 관람 | AI 시각화·설계 | ☐ |
| REQ-F-046 | 미팅 슬롯·성과 리포트 | 선택 | M11 | P3 관람 | 기능 구현 | ☐ |
| REQ-F-047 | 이벤트 모바일앱·세션·채팅·설문 | 선택 | M11 | P3 관람 | 기능 구현 | ☐ |
| REQ-F-048 | 공개 홍보 사이트(SEO·다국어) | 필수 | M12 | P3 마케팅·공개 | 기능 구현 | ☐ |
| REQ-F-049 | 공개 인터랙티브 플로어플랜 | 필수 | M12 | P3 마케팅·공개 | 기능 구현 | ☐ |
| REQ-F-050 | 세그먼트 EDM·캠페인 자동화 | 필수 | M12 | P3 마케팅·공개 | 기능 구현 | ☐ |
| REQ-F-051 | 스폰서십 패키지·대시보드 | 필수 | M12/M16 | P3 마케팅·공개 | 기능 구현 | ☐ |
| REQ-F-052 | 실내 wayfinding·POI·경로 | 선택 | M13 | P3 현장운영 | 기능 구현 | ☐ |
| REQ-F-053 | 실시간 혼잡 모니터·예측 | 선택 | M14 | P3 현장운영 | AI 시각화·설계 | ☐ |
| REQ-F-054 | 홀 전력부하·주차 점유 | 선택 | M14 | P3 현장운영 | 기능 구현 | ☐ |
| REQ-F-055 | 안전 위반·이상탐지 알림 | 선택 | M14 | P3 현장운영 | AI 시각화·설계 | ☐ |
| REQ-F-056 | 납부 스케줄 자동생성·알림 | 필수 | M9 | P3 정산 | 기능 구현 | ☐ |
| REQ-F-057 | 유틸리티·부대 PG 결제 | 필수 | M9 | P3 정산 | 기능 구현 | ☐ |
| REQ-F-058 | 예치금 실사용 정산 투명화 | 필수 | M9 | P3 정산 | 기능 구현 | ☐ |
| REQ-F-059 | 세금계산서·옥션 수수료 정산 | 필수 | M9 | P3 정산 | 기능 구현 | ☐ |
| REQ-F-060 | 환불·취소 규정 자동 | 선택 | M9 | P3 정산 | 기능 구현 | ☐ |
| REQ-F-061 | 홀·기간별 가동률 대시보드 | 필수 | M16 | P3 경영 BI | 기능 구현 | ☐ |
| REQ-F-062 | 매출 구성·행사별 P&L | 필수 | M16 | P3 경영 BI | 기능 구현 | ☐ |
| REQ-F-063 | 전시장 ROI·RevPAD·㎡당 수익 | 필수 | M16 | P3 경영 BI | 기능 구현 | ☐ |
| REQ-F-064 | 참가사 리텐션·LTV 코호트 | 필수 | M16 | P3 경영 BI | 기능 구현 | ☐ |
| REQ-F-065 | 참가업체 관점 ROI(권한 격리) | 필수 | M16 | P3 경영 BI / P5 보안 | 기능 구현 | ☐ |
| REQ-F-066 | 경영진 KPI 대시보드·드릴다운 | 필수 | M16 | P3 경영 BI | 기능 구현 | ☐ |
| REQ-F-067 | CMS 게시 워크플로·버전 | 필수 | M17 | P3 마케팅·공개 | 기능 구현 | ☐ |
| REQ-F-068 | 참가업체 마이크로사이트 | 필수 | M17 | P3 마케팅·공개 | 기능 구현 | ☐ |
| REQ-F-069 | 다국어 콘텐츠·hreflang | 필수 | M17 | P3 마케팅·공개 / P6 | 비기능 | ☐ |
| REQ-F-070 | 사이니지 콘텐츠 배포 ⚠확인필요 | 선택 | M17 | P3 현장운영 | 기능 구현 | ☐ |
| REQ-F-071 | RBAC·감사·시스템설정 백오피스 | 필수 | M18/§5B | P5 보안 / P8 관리 | 보안·개인정보 | ☐ |
| REQ-F-072 | 룰셋·마스터데이터 버전관리 | 필수 | M18 | P4 아키텍처 / P8 | 아키텍처 | ☐ |
| REQ-F-073 | 공통코드·메뉴 관리 | 필수 | §5B | P8 관리 | 기능 구현 | ☐ |
| REQ-F-074 | 공통 업무모듈(일지·일정·쪽지·공지·검색) | 필수 | §5B | P8 관리 | 기능 구현 | ☐ |
| REQ-F-075 | 회의록(STT)·업무보고 통계 PDF | 필수 | §5B | P8 관리 | 기능 구현 | ☐ |
| REQ-F-076 | 통합 알림센터(WebSocket) | 필수 | §5B | P8 관리 | 기능 구현 | ☐ |
| REQ-F-077 | 멀티테넌트 격리·전시관 온보딩 | 필수 | §1A | P7 멀티테넌시 | 멀티테넌시·확장 | ☐ |
| REQ-F-078 | 테넌트 컨텍스트 해소 | 필수 | §1A | P7 멀티테넌시 | 멀티테넌시·확장 | ☐ |
| REQ-F-079 | 2계층 관리자(플랫폼/테넌트) | 필수 | §1A | P7 멀티테넌시 / P5 | 멀티테넌시·확장 | ☐ |
| REQ-F-080 | API·웹훅·CRM/ERP 연동 게이트웨이 | 선택 | 연동 | P4 아키텍처 | 아키텍처 | ☐ |
| REQ-F-081 | 역할별 프론트 포털 분리 | 필수 | §2-1 | P4 아키텍처 | 아키텍처 | ☐ |
## 2. AI 요구사항 (REQ-A)
| REQ-ID | 요구사항 요약 | 유형 | 모듈 | 제안서 섹션(준비) | 평가부문 | 반영상태 |
|---|---|---|---|---|---|---|
| REQ-A-001 | 나노바나나 시공 예상사진 샷세트 S1~S7 | 필수 | M5 | P3 AI 시각화(핵심) | AI 시각화·설계(핵심) | ☐ |
| REQ-A-002 | image-to-image 구조보존(골격/앵글 잠금) | 필수 | M5 | P3 AI 시각화(핵심) | AI 시각화·설계(핵심) | ☐ |
| REQ-A-003 | 구조화 프롬프트 사전·보존/교체 분리 | 필수 | M5 | P3 AI 시각화(핵심) | AI 시각화·설계(핵심) | ☐ |
| REQ-A-004 | S6 배선 오버레이 백엔드 래스터 합성 | 필수 | M5 | P3 AI 시각화(핵심) | AI 시각화·설계(핵심) | ☐ |
| REQ-A-005 | Before/After 드래그 슬라이더 | 필수 | M5 | P3 AI 시각화(핵심) | AI 시각화·설계(핵심) | ☐ |
| REQ-A-006 | RenderJob 방어(크기가드·SAFETY·쿼터) | 필수 | M5 | P3 AI 시각화 / P5 보안 | 보안·개인정보 | ☐ |
| REQ-A-007 | 단계별 로딩·비동기 큐·WebSocket 푸시 | 필수 | M5 | P4 아키텍처 | 아키텍처 | ☐ |
| REQ-A-008 | 간판 텍스트 비전 검수·후처리 합성 | 필수 | M5 | P3 AI 시각화 | AI 시각화·설계 | ☐ |
| REQ-A-009 | 부스 배치 3안 AI(제약 솔버+LLM) | 필수 | M2 | P3 AI 시각화·설계 | AI 시각화·설계(핵심) | ☐ |
| REQ-A-010 | AI 규정 자동검증(배치·설계) | 필수 | M2/M3 | P3 AI 시각화·설계 | AI 시각화·설계 | ☐ |
| REQ-A-011 | AI 서류 검수(누락·불일치) | 필수 | M6 | P3 서류·워크플로 | AI 시각화·설계 | ☐ |
| REQ-A-012 | 규정 자연어 챗봇(근거·인용) | 선택 | AI | P3 서류·워크플로 | AI 시각화·설계 | ☐ |
| REQ-A-013 | AI 수요예측·수율/동적가격 | 필수 | M16 | P3 경영 BI | AI 시각화·설계 | ☐ |
| REQ-A-014 | AI KPI 브리핑·자연어 조회(Text-to-SQL) | 필수/선택 | M16 | P3 경영 BI | AI 시각화·설계 | ☐ |
| REQ-A-015 | AI 카피·이미지 초안·다국어 번역 | 필수 | M12/M17 | P3 마케팅·공개 | AI 시각화·설계 | ☐ |
| REQ-A-016 | AI 플랫폼 라우터(Claude→Ollama 폴백) | 필수 | §6 | P4 아키텍처 / P5 보안 | 아키텍처 | ☐ |
| REQ-A-017 | AI 근거(RAG)·인용·환각 차단 | 필수 | §6 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-A-018 | AI 리드 스코어·매칭·추천 | 선택 | M10/M11 | P3 관람 | AI 시각화·설계 | ☐ |
| REQ-A-019 | 현장 이상탐지·혼잡/철거 예측 | 선택 | M14/M8 | P3 현장운영 | AI 시각화·설계 | ☐ |
| REQ-A-020 | 도면 비전 추출·OCR 문서 등록 | 필수 | M3/AI | P3 AI 시각화·설계 | AI 시각화·설계 | ☐ |
## 3. 비기능 요구사항 (REQ-N)
| REQ-ID | 요구사항 요약 | 유형 | 제안서 섹션(준비) | 평가부문 | 반영상태 |
|---|---|---|---|---|---|
| REQ-N-001 | 코어 가용성 SLO 99.5%(성수기 99.9%) | 필수 | P6 비기능 | 비기능 | ☐ |
| REQ-N-002 | 백엔드 2인스턴스·롤링 무중단 | 필수 | P4 아키텍처 / P6 | 비기능 | ☐ |
| REQ-N-003 | PG 스탠바이 복제·failover·PITR | 필수 | P4 아키텍처 / P6 | 비기능 | ☐ |
| REQ-N-004 | Fail-Safe 배포(헬스체크·롤백) | 필수 | P8 사업관리 | 사업관리·품질 | ☐ |
| REQ-N-005 | degraded 모드(목 응답·폴백) | 필수 | P4 아키텍처 / P6 | 비기능 | ☐ |
| REQ-N-006 | 나노바나나 40초·1024px 전처리 | 필수 | P6 비기능 | 비기능 | ☐ |
| REQ-N-007 | 대량 생성 제어(S1·S7·캐시·쿼터) | 필수 | P6 비기능 | 비기능 | ☐ |
| REQ-N-008 | 공간쿼리 GiST 실시간 | 필수 | P4 아키텍처 | 아키텍처 | ☐ |
| REQ-N-009 | 워커 독립 스케일 | 필수 | P4 아키텍처 | 아키텍처 | ☐ |
| REQ-N-010 | BI/공개 읽기복제 오프로드 | 필수 | P4 아키텍처 | 아키텍처 | ☐ |
| REQ-N-011 | 워커 장애 재큐(멱등 Job) | 필수 | P4 아키텍처 / P6 | 비기능 | ☐ |
| REQ-N-012 | WCAG 2.1 AA·KWCAG 2.2 | 필수 | P6 비기능 | 비기능 | ☐ |
| REQ-N-013 | 캔버스/맵 비시각 대안 | 필수 | P6 비기능 | 비기능 | ☐ |
| REQ-N-014 | 다국어 i18n·hreflang·로케일 포맷 | 필수 | P6 비기능 | 비기능 | ☐ |
| REQ-N-015 | 라이트/다크 테마 CSS 토큰 | 필수 | P6 비기능 | 비기능 | ☐ |
| REQ-N-016 | 반응형(데스크톱/모바일) | 필수 | P6 비기능 | 비기능 | ☐ |
| REQ-N-017 | 단일 공간 원천(중복 저장 금지) | 필수 | P4 아키텍처 | 아키텍처 | ☐ |
| REQ-N-018 | 관측성(로그·PII/스택트레이스 미기록) | 필수 | P5 보안 / P6 | 비기능 | ☐ |
| REQ-N-019 | 공개영역 CDN·요청률 상한 | 필수 | P4 아키텍처 / P6 | 비기능 | ☐ |
| REQ-N-020 | tenant_id 선두 복합 인덱스 | 필수 | P7 멀티테넌시 / P4 | 멀티테넌시·확장 | ☐ |
| REQ-N-021 | BI 데이터마트 배치 ETL/읽기복제 | 필수 | P4 아키텍처 | 아키텍처 | ☐ |
## 4. 보안 요구사항 (REQ-S)
| REQ-ID | 요구사항 요약 | 유형 | 제안서 섹션(준비) | 평가부문 | 반영상태 |
|---|---|---|---|---|---|
| REQ-S-001 | 외부 API 정책(Ollama 기본·Claude/Gemini 예외) | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-002 | GEMINI_API_KEY 워커 env only | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-003 | 자격증명·키 응답/로그/커밋 완전 제외 | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-004 | admin 비번 env 재시드(AES-256-GCM) | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-005 | JWT+2FA OTP(TOTP)·실패 잠금 | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-006 | 행사 RBAC(테넌트 격리 ⊃ 행사 3중) | 필수 | P5 보안 / P7 | 보안·개인정보 | ☐ |
| REQ-S-007 | 미등록 업체 차단(403) | 필수 | P5 보안 / P3 옥션 | 보안·개인정보 | ☐ |
| REQ-S-008 | admin/internal 엔드포인트 게이트 | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-009 | M5 이미지 워터마크 항상 포함 | 필수 | P5 보안 / P3 AI | 보안·개인정보 | ☐ |
| REQ-S-010 | 오류 응답 스택트레이스 미노출 | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-011 | DataAccessException 요약 매핑 | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-012 | 민감 액션 감사로그 전수(tenant_id) | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-013 | PII 동의·보존·마스킹·AES-256-GCM | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-014 | 입력 검증(Bean Validation·파일 가드) | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-015 | XSS 방지·CSP·CMS sanitize | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-016 | 인젝션 차단(MyBatis #{} 강제) | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-017 | IDOR 방지·CSRF·JWT 회전 | 필수 | P5 보안 | 보안·개인정보 | ☐ |
| REQ-S-018 | fail-closed 다층 테넌트 격리 | 필수 | P7 멀티테넌시 / P5 | 멀티테넌시·확장 | ☐ |
| REQ-S-019 | 의존성 SCA CI 게이트 | 필수 | P5 보안 / P8 | 사업관리·품질 | ☐ |
| REQ-S-020 | 보안영역 분리(DMZ/내부망) | 필수 | P4 아키텍처 / P5 | 보안·개인정보 | ☐ |
---
## 5. 커버리지 요약
| 유형 | REQ 수 | 필수 | 선택 |
|---|---|---|---|
| REQ-F (기능) | 81 | 62 | 19 |
| REQ-A (AI) | 20 | 15 | 5 |
| REQ-N (비기능) | 21 | 21 | 0 |
| REQ-S (보안) | 20 | 20 | 0 |
| **총계** | **142** | **118** | **24** |
**제안서 섹션 커버리지 목표**: P3(기술제안)에 최다 REQ 집중(AI 시각화·설계 win theme), P5(보안)에 REQ-S 20 + 관련 REQ-A/F, P4(아키텍처)에 REQ-N/A 인프라 항목, P7(멀티테넌시)에 §1A 계열. QA는 전 142개 REQ의 반영상태가 ☑ 완료되었는지 본 표로 최종 검증한다.
## 6. 확인 필요 REQ (제안 전 발주처 협의)
| REQ-ID | 확인 사항 | rfp_analysis 참조 |
|---|---|---|
| REQ-F-022 | kxwp API 연동(폐쇄형·미공개) | C2 |
| REQ-F-070 | 사이니지 HW 연동 | C7 |
| REQ-F-052/053/054/055 | wayfinding 비콘·IoT 센서 인프라 | C7 |
| REQ-A-001~008 | 나노바나나 Gemini 승인(G1) — 미승인 시 온프레미스 폴백 | C5 |
| REQ-F-002 | 인터넷 요금 정합성·요율 공식본 | C4 |
| REQ-F-077 | 코엑스 등 신규 전시관 실측 데이터 | C6 |
</content>

374
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/tech_advisory.md Normal file
View File

@ -0,0 +1,374 @@
# 킨텍스 자동전시시스템 구축 — 기술·아키텍처 자문서 (Tech Advisory)
> 작성: proposal-tech-advisor(아키텍처 허브) · 작성일: 2026-07-11 · 버전 v1.0
> 입력: `rfp_analysis.md`(REQ 142)·`rtm.md`·`proposal_strategy.md`+`proposal_outline.md`(Win Theme 5·필수 도식 12종)·**`docs/architecture/{app,system,tech,data,network}.md`**(AA/SA/TA/DA/NA 확정 아키텍처 5종)·`docs/PLANNING.md` v3.0·`docs/SECURITY.md`·`docs/WORK_STATUS.md`(라이브 실적)·kintex `CLAUDE.md`(스택 확정).
> **성격**: 아키텍처 전문가 풀(AA·SA·TA·DA·NA)이 이미 확정한 5종 아키텍처를 **재발명하지 않고**, 제안서(writer·visual-designer·deck-designer)용으로 **종합·상충 조정·재구성**한 기술 자문. 전문가 풀 산출물이 이미 충분해 추가 소집(kintex-sa/ta/da) 불요 — 공백(SM 운영·SLA·WBS/공수·도식 사양)만 본 문서가 저술.
> **원칙(불변)**: ①과장 금지 — WORK_STATUS 라이브 확인분만 "구축 완료/검증됨", 나머지는 "구현 계획". ②시크릿(키·비번·내부IP) 미기재. ③실현 가능성 우선 — 확정 스택·기존 스캐폴드·이식 자산으로 뒷받침.
---
## 0. 기술 신뢰성 기반 — 라이브 실적 vs 구현 계획 (과장 방지 핵심)
> 평가위원 최대 관심 = "제안이 말뿐인가, 실제로 되는가". 본 절이 그 답이다. WORK_STATUS(2026-07-11) 라이브 확인분과 구현 계획을 **명확히 구분**한다. 제안서 P8(사업관리)·P4(아키텍처) 신뢰 근거로 인용.
### 0-1. 구축 완료·라이브 (검증됨 — "이미 돈다")
| 영역 | 라이브 실적 | 검증 근거 |
|---|---|---|
| **개발/배포 인프라** | `kintex.zioinfo.co.kr` TLS + 백엔드 8021 + PostGIS + Redis + 나노바나나 워커 systemd 상주 | WORK_STATUS §4 인프라(라이브) |
| **CI/CD 자동배포** | Gitea webhook → `deploy_kintex.sh`(bootJar+vite build→배포→health→롤백). push 시 자동배포 | WORK_STATUS §2·§7 |
| **나노바나나 이미지 생성** | Gemini 라이브(G1 소유자 승인 완료), `gemini-3.1-flash-image-preview` 워커 | WORK_STATUS §2·§4 |
| **인증(JWT/RBAC/2FA)** | JWT+RBAC 6역할 + TOTP OTP + 로그인 실패 잠금 + admin env 시더(admin123 금지) | WORK_STATUS §4, Flyway V7/V8 |
| **P0 코어 매퍼(PostGIS)** | M2~M5 매퍼 배선(501 해소)·룰엔진·공간 SQL | WORK_STATUS §4 백엔드(라이브) |
| **공통 레이어(WISE 이식)** | 시스템관리·공통 업무기능·공개 인증(register/forgot/reset) | Flyway V1~V9(테이블 39) |
| **프론트(Stitch 반영)** | 로그인(히어로+CI+회원가입/비번찾기/아이디기억) + 부스 설계 스튜디오·대시보드·갤러리·신규 8+5화면 | WORK_STATUS §4·§6 |
| **평면도/CAD 자산** | 홀별 평면도 JPG 15 + CAD(제1전시장 "평면,트렌치.dwg") 확보 → 트렌치 실측 원천 | WORK_STATUS §4, CLAUDE.md 확보자산 |
→ **메시지**: "제안 아키텍처는 도상이 아니라 **이미 기동 중인 시스템**이다. 스캐폴드·인증·PostGIS 코어·나노바나나·자동배포 파이프라인이 라이브로 검증됐다." (전시테크/범용 SI가 제시하지 못하는 실증 우위)
### 0-2. 구현 계획 (설계 확정·미완 — "표준대로 채운다")
| 영역 | 상태 | 근거 |
|---|---|---|
| 도메인 모듈 M15 옥션·M10 관람·M12/17 CMS·M16 BI·M18 관리자 | 설계 확정, 구현 대기(Phase D) | IMPLEMENTATION_BACKLOG Phase D |
| 멀티테넌시(tenant_id 전파·컨텍스트 해소) | 데이터모델 확정, 스키마·컨텍스트 구현 대기 | WORK_STATUS §6, data.md §1A |
| 실데이터 집계 전환(신규 5화면 샘플→API) | 화면 이식 완료, 집계 API 미구축 | WORK_STATUS §6, UNDEVELOPED_BACKLOG §1 |
| 접근성/i18n/테마 전면 적용 | NFR 표준 확정, 전면 스윕 대기 | WORK_STATUS §6 |
| 역할별 프론트 번들 분리 | 방식 확정 대기(모노레포 vs 서브패스) | tech.md §9-5 |
| AiTextRouter/AiConfig(텍스트 AI) | 설계 확정(UIWS 패턴), 착수 대기 | tech.md §6-1·R-T7 |
→ **원칙**: 위 항목은 제안서에서 **"구현 계획"**으로만 서술. "구현 완료"로 오기 금지(감점/신뢰 훼손 리스크).
---
## 1. 목표 아키텍처 종합 (5종 아키텍처 → 제안서 재구성)
### 1-1. 목표 아키텍처 4-Tier + 사이드카 (한 문장)
**React 18/19(Vite·TS) 역할별 분리 프론트 → SSO(JWT+2FA)·이중 RBAC → 공유 Spring Boot 3.2.5(Java 17)+MyBatis 모듈러 모놀리스 → PostgreSQL+PostGIS 단일 공간 원천(+읽기복제) / Redis 비동기 큐 / 오브젝트 스토리지**, 그 위에 **나노바나나 Python 워커 사이드카**(이미지 생성)와 **Claude AI(AiTextRouter·Ollama 폴백)**(텍스트 지능)를 **얇은 큐/HTTP 계약으로 결합**한다. (app.md §1·§10, system.md §1~§2, tech.md §1)
### 1-2. 계층별 종합 (전문가 풀 산출 통합)
| 계층 | 구성(확정) | 권위 문서 | 핵심 근거 |
|---|---|---|---|
| **표현(App)** | 역할별 6프론트(organizer·exhibitor·contractor·ops·admin·public/visitor) 번들 분리 + 공유 디자인시스템/컴포넌트/api-client 상속. 데스크톱=설계·에디터, 모바일=현장·조회·승인 | app.md §10, system.md §2-1 | 최소권한·공격면 축소, 중복구현 금지 |
| **인증·인가** | 단일 JWT SSO(HS256, jjwt 0.12.5) + TOTP 2FA(RFC6238) + 로그인 실패 잠금 + **이중 RBAC**(플랫폼 `plat`/행사 `roles·hm`) | app.md §6, tech.md §7 | WISE/UIWS 이식(재설계 금지) |
| **애플리케이션(백엔드)** | 공유 Spring Boot **모듈러 모놀리스**(`com.zioinfo.kintex.module.mN`, 4계층 Controller/Service/Mapper/DTO) + 룰엔진 + 배치/배선 엔진(PostGIS) + 옥션·BI·CMS 서비스 | app.md §1~§5·§10-2 | 단일 공유 백엔드·경로/RBAC로 역할 표면 분리 |
| **비동기** | Redis 큐(RenderJob·서류·EDM·알림) + 옥션 실시간 순위/타이머 + 캐시/쿼터/WS 세션 상관. STOMP over WebSocket 실시간 푸시 | app.md §8·§9, system.md §6-3 | 백엔드 무상태화 → 수평 확장 |
| **AI(이미지)** | 나노바나나 Python 워커(google-genai, `gemini-3.1-flash-image-preview`) — image-to-image 구조보존 + 워터마크 후처리 + S6 로컬 PIL 래스터 | tech.md §1-3, system.md ADR-1 | google-genai=Python SDK, Java 재구현 회피 |
| **AI(텍스트)** | `AiTextRouter`: Claude 기본(`api.anthropic.com` 승인 예외) → **Ollama 폴백**(폐쇄망/장애). 부스 배치는 **제약 솔버 주도**, LLM은 조건해석만 | tech.md §6 | 결정론 우선·환각 차단·데이터 주권 |
| **데이터** | PostgreSQL+PostGIS 단일 공간 원천(부스 Polygon·트렌치 Point·배선 LineString, SRID 0) + 프라이머리-스탠바이 복제 + 읽기복제(BI·공개 오프로드) + BI 데이터마트(스타 스키마) | data.md §2~§6 | 단일 공간 원천 불변·운영/분석 분리 |
| **저장(바이너리)** | 오브젝트 스토리지(도면·생성이미지·서식·PDF·콘텐츠) — 경로만 DB, CDN 프론팅 | data.md §0-1, system.md §2-1 | 대용량 독립 확장 |
| **네트워크·보안영역** | 4존+관리존(엣지·DMZ·내부망·AI워커·데이터·관리) 계층 방어, DMZ→데이터존 직결 금지, egress 화이트리스트(Claude·Gemini·PG·SMTP) | network.md §2~§5 | 공개/내부 물리·논리 분리·폐쇄망 지향 |
### 1-3. 멀티테넌시 격리 구조 (다중 전시관 SaaS)
- **격리 축**: `tenant_id`(전시관: KINTEX #1·COEX #2…) ⊃ `event_id`(행사) ⊃ 행사 RBAC(역할). 3중 격리.
- **fail-closed 다층 방어**(REQ-S-018): ①테넌트 컨텍스트 필터(서브도메인 우선+사용자소속 보조, 불일치 거부) → ②서비스 가드 → ③MyBatis 공통 인터셉터(tenant_id 자동 주입) → ④PostGIS/쿼리(선두 복합 인덱스). 어느 한 층이라도 불일치면 차단.
- **온보딩**: 코드 배포 없이 **데이터 온보딩**(홀·요율·규정 룰셋·마스터데이터 입력). 기능 로직 불변. (app.md §6, data.md §4-4, system.md §3-1 멀티테넌시)
- **주의(현실)**: 멀티테넌시는 **구현 계획**(WORK_STATUS §6). 제안 시 "데이터모델 확정→스키마 tenant_id→컨텍스트 배선" 3단계 로드맵으로 서술, 백필 전 단일테넌트 무중단 동작→검증 후 필터 활성화(회귀 방지).
### 1-4. 필수 도식 12종 — 작도 사양 (deck-designer 직접 작도용)
> 각 도식의 **박스·연결·라벨 텍스트**를 명세. visual-designer(선 SVG 아이콘)·deck-designer(python-pptx)가 재해석 없이 작도. 모든 라벨은 한국어, 아이콘은 선(stroke) 스타일.
#### ① 3중 해자 벤다이어그램 (S04·S12)
- **형태**: 3원 교집합 벤다이어그램. 3개 동일 크기 원 60% 겹침.
- **원 라벨**: 원A "나노바나나 시공 예측 이미지"(부제: image-to-image 구조보존·40초·S1~S7), 원B "PostGIS 실측 공간데이터"(부제: 부스 폴리곤·트렌치 포인트·배선 LineString 단일 원천), 원C "공사 옥션 폐루프"(부제: AI 자료→응찰→낙찰→발주 자동전환).
- **중앙 교집합(3원 겹침)**: 강조 배지 "재현 난이도 높은 결합 = 우리만의 해자(Moat)". 2원 교집합에는 회색 "단일 요소는 모방 가능".
- **하단 캡션**: "셋의 결합은 경쟁 전시테크·범용 SI가 재현하기 어렵다."
#### ② 모듈맵 — 생애주기 × 우선순위 매트릭스 (S16)
- **형태**: 가로축=전시 생애주기 6단계(판매·기획 → 설계·시각화 → 발주·계약 → 참가·관람 → 현장운영 → 사후·경영), 세로축=우선순위(P0 코어 / P1 / P2).
- **박스(모듈 칩)**: P0행에 **M2 플로어플랜·M3 부스설계·M4 유틸리티·M5 나노바나나**(강조색·굵은 테두리). P1행 M1·M6·M7·M9·M15(옥션 강조)·M10·M12·M16·M17·M18·§5B 공통·§1A 멀티테넌시. P2행 M8·M11·M13·M14.
- **하단 레이어 띠**: "공통/시스템관리 레이어(§5B) — 전 모듈 선행 기반" + "멀티테넌시(§1A) — tenant_id 격리".
- **캡션**: "18개 모듈 + 공통 레이어를 한 장으로 조망. P0 4개가 심장."
#### ③ 나노바나나 파이프라인 플로우 (S20)
- **형태**: 좌→우 수평 플로우, 8박스.
- **박스·라벨**: `[사용자: 렌더 요청]` → `[Spring 백엔드: RenderJob 생성·쿼터 확인]` → `[Redis 큐 kintex:renderjob:queue(leftPush)]` → `[나노바나나 Python 워커(BLPOP 소비)]` → `[Gemini image-to-image(G1 승인·라이브)]` → `[워터마크 후처리·S6 로컬 PIL 래스터]` → `[오브젝트 스토리지 적재]` → `[pub/sub → 백엔드 relay → WebSocket/STOMP /topic/render/{jobId}]` → `[프론트: 완료 푸시·갤러리 갱신]`.
- **분기 주석**: 워커 하단에 점선 "degraded: G1 미승인/Gemini 장애 시 목(mock) 응답·구조·워터마크 유지". "성공 시에만 쿼터 차감".
- **보안 배지**: `GEMINI_API_KEY`는 워커 env only(백엔드 미취급).
- **캡션**: "이미지 생성 전면 비동기 — 사용자 동기 대기 없음, 평균 40초."
#### ④ Before/After 슬라이더 (S21)
- **형태**: 좌우 분할 이미지 카드 + 중앙 세로 드래그 핸들.
- **라벨**: 좌 "Before: 빈 부스(도면/실측)", 우 "After: 시공 후 예상(AI 생성·워터마크)". 핸들 "드래그로 비교".
- **접근성 배지**: "ARIA slider·키보드 좌우 조작 지원(WCAG AA)".
- **하단**: 워터마크 텍스트 예시 배지 "AI 생성 예상 이미지 — 실제 시공과 다를 수 있음. 계약·심사 서류 사용 금지."
#### ⑤ 3안 비교 화면 (S24)
- **형태**: 3열 카드(안1·안2·안3) + 상단 공통 홀 정보 바 + 하단 액션 바.
- **카드 라벨**: 각 카드 상단 "안 N — 최적화 목표"(예: 안1 "통로 효율 최대", 안2 "프리미엄 부스 최대", 안3 "균형"). 카드 본문 미니 배치도 썸네일 + 지표(판매면적 ㎡·부스 수·규정 위반 0/N).
- **액션 바**: `[안 선택]` `[구역/블록 병합 편집]` `[병합 후 재검증]`.
- **캡션**: "제약 솔버가 상이한 최적화 목표로 정확히 3안 생성. 사람이 선택·병합·최종 확정."
#### ⑥ PostGIS 배선 오버레이 (S27)
- **형태**: 홀 평면도 위 배선 경로 오버레이. 부스 폴리곤(연회색) + 트렌치 포인트(◆) + 분전반(▣) + 배선 LineString(색상별).
- **색상 범례**: 전기=적색, 네트워크=청색, 급배수=녹색(S6 규약 정합).
- **주석 배지**: "최근접 트렌치 KNN(`geom <-> point`)", "최단 경로(`ST_Length`)·통로 횡단 최소화", 가정 트렌치엔 "가정 좌표(실측 대기)" 배지.
- **캡션**: "수기 위치표시도 폐지 — 좌표 클릭 자동 작도. SRID 0 홀 로컬 미터, GiST 인덱스 실시간."
#### ⑦ 옥션 폐루프 흐름도 (S29)
- **형태**: 순환/좌→우 흐름, 좌측에 AI 자료 패키지 스택.
- **박스**: `[M2 배치 + M3 설계 + M4 배선/BOQ + M5 시공예측 이미지]`(AI 생성 자료 패키지) → `[옥션 개설(역경매/RFQ/고정가)]` → `[등록업체 검증 게이트: 미등록 응찰 차단 403]` → `[견적서(Quotation) 제출·PDF·버전]` → `[실시간 순위·라운드 마감(Redis 정렬셋·WS 델타)]` → `[종합평가 낙찰(가격+평판+납기)]` → `[Award → 계약/발주 자동전환(M6·M9 연동)]`.
- **캡션**: "AI 설계자료가 곧 발주 근거. 사진 수준 자료로 응찰→발주까지 한 흐름."
#### ⑧ 종합평가 스코어 비교표 (S31)
- **형태**: 업체 행 × 평가항목 열 표 + 가중 합계 열 + 낙찰 하이라이트 행.
- **열**: 업체명 | 견적금액(점수) | 평판(점수) | 납기(점수) | **가중 종합점수** | 순위.
- **가중치 주석 바**: "가중치(예): 가격 0.6 / 평판 0.25 / 납기 0.15 — 옥션별 설정형(`weight` jsonb)".
- **하이라이트**: 1위 행 강조 + "낙찰(Award)" 배지 + "선정 사유·항목별 비교" 캡션.
#### ⑨ 시스템 아키텍처 다이어그램 — 전 계층 (S41)
- **형태**: 상하 6밴드 계층도(system.md §2 논리 아키텍처 재구성).
- **밴드1 엣지/DMZ**: `[CDN·정적캐시]` `[WAF/Reverse Proxy(nginx)·TLS 종단·레이트리밋]`.
- **밴드2 역할별 프론트**: organizer·exhibitor·contractor·ops·admin(내부 배지)·public/visitor(공개 SSR/SEO/다국어 배지).
- **밴드3 SSO·RBAC**: `[JWT SSO + TOTP 2FA · 이중 RBAC(플랫폼/행사)]`.
- **밴드4 공유 백엔드**: `[REST + WebSocket/STOMP]` 아래 `[룰엔진]` `[배치·배선 엔진·PostGIS]` `[옥션 M15]` `[BI M16·KpiSnapshot]` `[CMS M17]` `[공개 API read-only]`.
- **밴드5 비동기**: `[Redis 큐·순위·타이머·캐시·쿼터]` → `[나노바나나 워커]` `[서류·EDM 워커]`.
- **밴드6 데이터**: `[PostgreSQL+PostGIS]` `[읽기복제(BI·공개)]` `[오브젝트 스토리지]`.
- **우측 외부 게이트 컬럼**: `[Gemini(G1·라이브)]` `[Claude(AiTextRouter)]` `[PG 결제]` `[kxwp 릴레이]` `[등록업체 DB 739]`.
- **연결 주석**: 워커→Gemini "egress only", 워커→백엔드 "WebSocket 완료 푸시", 백엔드→읽기복제 "BI/공개 오프로드".
#### ⑩ 보안영역 분리도 (망 구성) (S47)
- **형태**: 좌→우 신뢰도 상승 존 다이어그램(network.md §2).
- **존 박스**: `[인터넷]` → `[엣지: CDN·WAF·DDoS]` → `[DMZ(공개): 공개LB·public SSR·visitor GW·공개 API GW·PG콜백 — 쓰기권한 없음]` → `[내부망(인증): 내부LB·SSO/2FA·내부 API GW·공유 백엔드]` → `[AI 워커존(egress 제한): Redis·나노바나나·Ollama]` → `[데이터존(최내곽): PostgreSQL+PostGIS·오브젝트 스토리지·읽기복제 — 아웃바운드 전면 차단]`. 상단 `[관리존: 배스천·관측성]`.
- **철칙 배지(굵게)**: "DMZ → 데이터존 직접 접근 절대 금지", "데이터존 아웃바운드 0(유출 경로 제거)", "admin. = VPN/허용IP+2FA, 인터넷 미도달".
- **egress 컬럼**: 승인 4목적지만(Claude·Gemini·PG·SMTP), 그 외 DROP.
#### ⑪ 멀티테넌시 격리 아키텍처도 (S56)
- **형태**: 수직 4층 방어 스택 + 좌측 테넌트 컨텍스트 진입.
- **진입**: `[요청: 서브도메인(kintex./coex.) + JWT 사용자 소속]` → `[테넌트 컨텍스트 해소: 불일치 시 거부]`.
- **4층 박스(위→아래)**: `[①컨텍스트 필터]` → `[②서비스 가드]` → `[③MyBatis 공통 인터셉터(tenant_id 자동 주입)]` → `[④PostGIS/쿼리: tenant_id 선두 복합 인덱스]`.
- **우측 데이터**: `[TB_* … WHERE tenant_id = ctx]` 격리 표현. 하단 배지 "fail-closed — 한 층이라도 불일치면 차단".
- **캡션**: "KINTEX #1 검증 → COEX #2 코드 배포 없이 데이터 온보딩. 기능 불변, 데이터·권한만 분리."
#### ⑫ 일정 간트 (Phase × 모듈) (S58)
- **형태**: 가로 타임라인 3구간(Phase 1 ~4M / Phase 2 ~4M / Phase 3 ~4M+), 세로 워크스트림 막대.
- **막대(Phase 1)**: 아키텍처(A)·공통레이어(B, 2FA/시스템관리)·P0 코어(C: M2·M3·M4·M5).
- **막대(Phase 2)**: 옥션 M15·관람 M10·BI M16·관리자 M18·판매/서류/정산 M1/6/7/9·CMS M12/17.
- **막대(Phase 3)**: 멀티테넌시·M11·M13·M14·배포 안정화·SM 이관.
- **마일스톤 다이아몬드**: G1(나노바나나 승인·완료)·G2(배포서버·완료)·Phase 게이트·QA 게이트·오픈.
- **캡션**: "선행 게이트 통제 + Phase 게이트 QA 통과 후 진행."
> **추가 표준 도식**(공공 제안 필수, outline 명시): 추진체계도(S15)=거버넌스(PM/PMO/dev-PM)+아키텍트(AA·SA·TA·DA·NA)+코어/도메인/AI/QA/DevOps 팀 조직도 / 리스크 매트릭스(S59)=발생×영향 2×2에 R-1~R-8·C1~C8 배치 / 기대효과 인포그래픽(S61)=견적·배치·검수·위치표시도·시공예측 5지표 Before/After. 사양은 §2·§5·strategy §4 참조.
---
## 2. Win Theme 기술 근거 (5선 — 실현 가능성 입증)
### WT-1. 나노바나나 시공 예측 (배점 20 · 최우선)
- **기술 골자**: RenderJob 큐(Redis `kintex:renderjob:queue`) → Python 워커(BLPOP) → Gemini **image-to-image 구조보존** → 워터마크 후처리 → 오브젝트 스토리지 → WebSocket `/topic/render/{jobId}` 완료 푸시.
- **구조보존 메커니즘**(REQ-A-002·003): 참조 이미지 `inlineData` + 구조화 프롬프트 사전(BOOTH_TYPES·BOOTH_STYLES·FIXTURE_LAYERS)에서 **보존(골격·치수·통로·카메라 앵글) / 교체(스타일·재질만 사실화) 명시 분리**. ReRoomAI 검증 패턴 이식(reroomai-source.md).
- **방어**(REQ-A-006): 다층 크기가드·mimeType 자동감지·SAFETY 분기·친화적 한글 에러·**성공 시에만 쿼터 차감**. 간판 한글 렌더 실패 시 간판영역 후처리 합성(REQ-A-008).
- **S6 배선 오버레이**(REQ-A-004): Gemini 미경유 — **백엔드/워커 로컬 PIL 결정적 래스터 합성**(전기 적·네트 청·급배수 녹). 좌표 정확성 확보·비용/지연 제외.
- **실현 근거**: **라이브 검증**(G1 승인·워커 Gemini 실동작, WORK_STATUS §4). "말이 아니라 이미 돈다."
- **도식**: ③파이프라인·④Before/After.
### WT-2. 배치·설계·배선 AI 3안 + 규정 자동검증 (배점 20+15 교차)
- **기술 골자**: 부스 배치 3안은 **결정적 제약 솔버**(비-LLM)가 상이한 최적화 목표로 생성, LLM(Claude)은 조건 해석·설명만(REQ-A-009). → 공공 "AI 신뢰성" 프레이밍의 핵심(결정론 주도).
- **규정 자동검증**(REQ-F-009·013, REQ-A-010): 룰셋(`compliance-v*.json` 버전 데이터)을 룰엔진이 평가 + PostGIS 공간 판정(통로폭 `ST_Distance/ST_Buffer`·비상구 `ST_Intersects`·홀 이탈 `ST_Contains`·바닥하중 홀별). 병합 후 재검증. 위반 시 `COMPLIANCE_BLOCKED`(422).
- **배선 자동 작도**(REQ-F-015~017): 기기목록→kW 합산→분전반 산출, 최근접 트렌치 KNN(`geom <-> point`)→최단 배선 LineString(`ST_Length`, 통로 횡단 최소 휴리스틱), 위치표시도 좌표 클릭 자동 작도(수기 폐지).
- **AI 신뢰 3층**: 결정적 알고리즘(제약 솔버·PostGIS) 중심 + LLM 보조 + **사람 최종 확정**. 규정검증=플래깅까지, 구조안전 판정은 구조기술사/킨텍스(Non-Goal). RAG 근거·인용·환각 차단(abstain, REQ-A-017).
- **실현 근거**: M2~M5 매퍼(PostGIS 공간 SQL)·룰엔진 **라이브**(WORK_STATUS §4). 3안 생성·병합·집계 API는 구현 계획.
- **도식**: ⑤3안 비교·⑥PostGIS 배선.
### WT-3. 공사 옥션 폐루프 (배점 15 · 폐루프 핵심)
- **기술 골자**: `TB_AUCTION 1─N TB_QUOTATION ─ TB_AWARD`. 옥션 유형 설정형(REVERSE/RFQ/FIXED). AI 자료 패키지(M2~M5 참조 `attached_refs`) 열람 기반 견적서 제출·PDF·버전. 실시간 순위=Redis 정렬셋 + WebSocket `/topic/auction/{auctionId}` 델타 푸시, 라운드 마감=Redis 타이머.
- **등록 게이트**(REQ-S-007): 미등록 업체 응찰 원천 차단 `NOT_REGISTERED_COMPANY`(403). M7이 `TB_COMPANY.kintex_registered` 검증 권위. → 킨텍스 "등록업체 시공 필수" 규정을 시스템이 강제.
- **종합평가·발주 전환**(REQ-F-028·032): 가중 스코어(가격+평판+납기, `weight` jsonb) → Award → 계약/발주 자동전환(M6·M9 연동, 이벤트 디커플·순환 금지).
- **실현 근거**: 옥션은 **구현 계획**(Phase D-M15). 스캐폴드 4계층·큐·WS 패턴·데이터모델 확정으로 실현성 입증.
- **도식**: ⑦옥션 폐루프·⑧종합평가 스코어.
### WT-4. 3중 보안 — 워터마크·PII·테넌트 (배점 10)
- **워터마크**(REQ-S-009): M5 이미지 응답 **항상** `watermarkRequired:true`+`watermarkText`+`notice`(계약·심사 서류 금지). 제거 불가(계약 강제, app.md §5-6). 워커 목/live 공통.
- **PII 격리**(REQ-S-013): 관람객/리드 `*_enc` AES-256-GCM 컬럼 암호화, 응답 완전 제외/마스킹, 동의 분리(privacy 필수/marketing 선택/share), 접근 감사 전수. BI 마트는 개인 식별자 비반입(집계만).
- **테넌트 3중**(REQ-S-018): §1-3 fail-closed 4층(컨텍스트→서비스→MyBatis→PostGIS).
- **외부 API 격리**(REQ-S-001·002): Ollama 기본 + Claude/Gemini만 승인 예외. `GEMINI_API_KEY` 워커 env only(백엔드 미취급), egress 워커존 단일 경로.
- **실현 근거**: 인증(JWT/RBAC/2FA/admin env)·워터마크 **라이브**. PII 암호화·테넌트 필터는 구현 계획.
- **도식**: ⑩보안영역 분리·⑪멀티테넌시 격리.
### WT-5. 멀티테넌트 SaaS 확장 (배점 5 · 미래가치)
- **기술 골자**: §1-3. tenant_id 전파 + 2계층 관리자(플랫폼 슈퍼관리자 테넌트스위처 / 테넌트 관리자 단일스코프) + 컨텍스트 해소. 온보딩 6단계=마스터데이터 입력 수준.
- **개발 부담 최소화**(strategy R-8): 멀티테넌시=격리 레이어만 추가, 기능 로직 불변. 백필 전 단일테넌트 무중단→검증 후 필터 활성화(회귀 방지).
- **실현 근거**: 구현 계획(WORK_STATUS §6). GUARDiA 표준 프레임워크 멀티테넌트 패턴 재사용.
- **도식**: ⑪멀티테넌시 격리.
---
## 3. 비기능(NFR) 충족안 — REQ-N 21건 전부 대응 (P6·P4)
> 근거: system.md §3(확장성·HA·성능·용량)·tech.md §5(관측성·성능)·data.md §3·§6·network.md §7. **SLO 99.5%(성수기 99.9% 지향)**.
| REQ-ID | 요구 | 충족 방안(기술) | 측정/게이트 | 근거 |
|---|---|---|---|---|
| REQ-N-001 | 코어 SLO 99.5% | 무상태 백엔드 + Redis 외부화 + HA(§아래) | 월 가용성 ≥99.5%, `/actuator/health` | system.md §3-2 |
| REQ-N-002 | 백엔드 2인스턴스·롤링 무중단 | 최소 2 인스턴스 + 헬스체크 LB + 롤링 배포 | 무중단 배포 검증(스테이징→prod) | system.md §3-2 |
| REQ-N-003 | PG 스탠바이·failover·PITR | 프라이머리-스탠바이 스트리밍 복제 + Patroni/관리형 자동 failover + PITR | RPO 최소·RTO 분 단위 | system.md §3-2 |
| REQ-N-004 | Fail-Safe 배포 | 백업→배포→헬스체크 200→실패 시 롤백(이전 jar 유지) | **라이브**(deploy_kintex.sh) | WORK_STATUS §2 |
| REQ-N-005 | degraded 모드 | G1 미승인/Gemini 장애=워커 목 응답(구조·워터마크 유지), Claude 실패=Ollama 폴백, PG 복제지연=프라이머리 폴백 | 무네트워크 스모크 통과 | system.md §3-2 |
| REQ-N-006 | 나노바나나 40초·1024px | 전면 비동기(WS 완료 푸시) + 클라 Canvas 1024px 다운스케일+JPEG 0.85 전처리 | 단건 평균 ≤40s | system.md §3-3 |
| REQ-N-007 | 대량 생성 제어 | 자동생성 **S1·S7 한정** + 동일 스키마해시 캐시 + 행사별 RenderJob 쿼터(`RENDER_EVENT_QUOTA` 기본 500·성공 시만 차감) | 쿼터/캐시 히트율 | system.md §3-3, R6 |
| REQ-N-008 | 공간쿼리 GiST 실시간 | 전 `geom` 컬럼 GiST 인덱스(트렌치 KNN·통로버퍼·비상구 교차) | 배치·배선 P95 <2s | data.md §3-4 |
| REQ-N-009 | 워커 독립 스케일 | 나노바나나·서류·EDM 워커 큐 깊이 기반 증감, 백엔드 응답성과 분리 | 큐 적체 모니터 | system.md §3-1 |
| REQ-N-010 | BI/공개 읽기복제 오프로드 | BI 집계·공개 조회·플로어플랜 열람 읽기복제 라우팅, 운영 프라이머리 보호 | 프라이머리 부하 격리 | system.md §3-1 |
| REQ-N-011 | 워커 장애 재큐(멱등) | 무상태 소비자 N대 + 가시성 타임아웃 후 재큐(멱등 Job) + AOF 지속화 + ACK | 진행 Job 유실 0 | system.md §3-2 |
| REQ-N-012 | WCAG 2.1 AA·KWCAG 2.2 | 시맨틱 마크업·ARIA·키보드·대비, 공공 KWCAG 2.2 병행 점검 | 접근성 자동+수동 감사 | rfp §6-N1 |
| REQ-N-013 | 캔버스/맵 비시각 대안 | 플로어플랜/배선 캔버스에 데이터 테이블·검색·키보드 부스 선택 대안 필수 제공 | 비시각 경로 검증 | rfp §6-N1 |
| REQ-N-014 | 다국어 i18n·hreflang | i18n 외부화(한 기본+영/중/일)·로케일 전환·hreflang·로케일 포맷 | 4로케일 전환 | rfp §6-N3 |
| REQ-N-015 | 라이트/다크 테마 | CSS 토큰 2벌·prefers-color-scheme 연동·선택 영속 | 테마 왕복 | rfp §6-N4 |
| REQ-N-016 | 반응형 | 데스크톱=설계/에디터, 모바일=현장/조회/승인 | 브레이크포인트 검증 | PLANNING §8 |
| REQ-N-017 | 단일 공간 원천 | M2 폴리곤·M4 배선 매퍼 권위, 소비 모듈 조회만·중복 저장 금지 | ArchUnit·계약 검수 | app.md §3-2, data.md §0-2 |
| REQ-N-018 | 관측성·미기록 | 로그·메트릭·트레이스 관리존 수집, 자격증명·PII·스택트레이스 미기록(`include-stacktrace: never`) | 로그 감사 | tech.md §5, network.md §8 |
| REQ-N-019 | 공개영역 CDN·요청률 상한 | 공개 SSG+CDN 캐시·요청률 상한·slowloris 타임아웃·동시연결 캡 | 스파이크 CDN 흡수 | network.md §7 |
| REQ-N-020 | tenant_id 선두 복합 인덱스 | 격리 쿼리 표준 인덱스(tenant_id 선두) | 격리 쿼리 성능 | data.md, §1-3 |
| REQ-N-021 | BI 데이터마트 배치 ETL | 스타 스키마(FACT/DIM) 야간 배치 ETL 또는 읽기복제 적재, KpiSnapshot | 원천-집계 정합(오차 0) | data.md §6 |
**HA 구성 요약(P6 SLA 표 입력)**: 프론트/공개=CDN 다중엣지+nginx 다중화 / 백엔드=2+ 인스턴스 헬스체크 LB·롤링 / Redis=Sentinel(자동 failover)+AOF / PostgreSQL=프라이머리-스탠바이+자동 failover+PITR / 워커=무상태 N대·재큐 / 배포=Fail-Safe(롤백). **SLO: 코어 99.5%(성수기 99.9% 지향), 나노바나나 생성=best-effort 비동기(큐 소진 목표).**
**용량 산정(P4·P6 근거)**: 단일 대형 행사 3,000~5,000부스(수만 지오메트리·GiST 필수) / RenderJob 부스 3,000×자동 2샷(S1·S7)+온디맨드=수천~1만 이미지(수 GB~수십 GB, OBJ+CDN·캐시 억제) / 리드·체크인 수만~수십만(파티셔닝 후보) / 동시 사용자 인증 수백+공개 수천~수만(CDN 흡수) / **DB 연결풀 Hikari max 3(`DB_POOL_MAX`)+PgBouncer 권고**(공유 PG 포화 방지). (system.md §3-4)
---
## 4. 보안 충족안 — REQ-S 20건 전부 대응 (P5 · 시크릿 값 미기재)
> 근거: SECURITY.md·app.md §5-6·§6·network.md·data.md §5·tech.md §7. **불변(위반=QA 반려)**.
| REQ-ID | 요구 | 충족 방안(기술) | 근거 |
|---|---|---|---|
| REQ-S-001 | 외부 API 정책 | Ollama 기본 + Claude(`api.anthropic.com`)·Gemini만 승인 예외, egress 화이트리스트 그 외 DROP | network.md §5 |
| REQ-S-002 | GEMINI 키 워커 env only | 나노바나나 워커 env only, Spring은 큐/콜백만, 워커존 단일 egress | tech.md §3-5 |
| REQ-S-003 | 자격증명·키 완전 제외 | 응답/로그/에러/커밋 마스킹, `*_enc`·해시·내부IP·워커토큰 미노출 | tech.md §7 |
| REQ-S-004 | admin 비번 env 재시드 | `ADMIN_PASSWORD_ENC`(AES-256-GCM)+별도 키파일→기동 시 BCrypt 재시드, admin123 금지 | **라이브**(env 시더) |
| REQ-S-005 | JWT+2FA+실패 잠금 | JWT(HS256)+TOTP(RFC6238)+로그인 실패 잠금(관리자 해제) | **라이브**(V7/V8) |
| REQ-S-006 | 행사 RBAC 3중 | 테넌트 격리 ⊃ 행사 RBAC(열람=멤버/홀매니저, 편집=역할별 게이트) | app.md §6 |
| REQ-S-007 | 미등록 업체 차단 | M15 응찰·초대 `NOT_REGISTERED_COMPANY`(403), M7 검증 권위 | app.md §6-2 |
| REQ-S-008 | admin/internal 게이트 | `/api/admin/**`=hasRole(ADMIN), `/api/internal/**`=X-Worker-Token | app.md §5-5 |
| REQ-S-009 | 이미지 워터마크 항상 | M5 응답 항상 watermarkRequired:true+text+notice, 제거 불가 | **라이브**·app.md §5-6 |
| REQ-S-010 | 오류 스택트레이스 미노출 | `server.error.include-*: never` + ApiResponse.error 요약만 | tech.md §5-1 |
| REQ-S-011 | DataAccessException 요약 매핑 | `@RestControllerAdvice GlobalExceptionHandler` INTERNAL 요약(테이블/컬럼 누출 차단) | app.md §7-2 |
| REQ-S-012 | 민감 액션 감사 전수 | 승인·낙찰·설계변경·룰셋개정·리드접근·로그인/권한 `TB_AUDIT_LOG`(tenant_id 포함, `@Audited` AOP) | app.md §7-3 |
| REQ-S-013 | PII 동의·마스킹·암호화 | 동의 분리(privacy/marketing/share)·최소수집·`*_enc` AES-256-GCM·응답 제외·보존/파기 | data.md §5 |
| REQ-S-014 | 입력 검증 | Bean Validation 화이트리스트·파일 MIME/크기 가드(WAF+앱 이중) | tech.md §7, network.md §4-2 |
| REQ-S-015 | XSS 방지·CSP | React 이스케이프·dangerouslySetInnerHTML 금지·CMS sanitize·CSP | rfp §6-N2 |
| REQ-S-016 | 인젝션 차단 | MyBatis `#{}` 강제·`${}` 금지, PostGIS/명령/LDAP 파라미터 바인딩 | rfp §6-N2 |
| REQ-S-017 | IDOR·CSRF·JWT 회전 | 리소스 소유·tenant_id 검증, CSRF/SameSite, JWT 만료·회전 | rfp §6-N2 |
| REQ-S-018 | fail-closed 테넌트 격리 | 4층(컨텍스트 필터→서비스 가드→MyBatis 인터셉터→PostGIS) | §1-3 |
| REQ-S-019 | 의존성 SCA CI 게이트 | OWASP Dependency-Check CI 게이트·정기 패치 | rfp §6-N2 |
| REQ-S-020 | 보안영역 분리 | 공개 DMZ 쓰기 없음·데이터존 직결 불가·DMZ↔내부 HTTPS(mTLS 권장)만·DB 프로토콜 횡단 금지 | network.md §2·§4 |
**보안 성숙도 강조점(P5)**: ①이미 라이브인 인증·워터마크·admin env(4·5·9번 실증) → "설계가 아니라 동작하는 통제". ②데이터존 아웃바운드 0으로 유출 경로 자체 제거(network.md 철칙). ③외부 AI 키 격리=네트워크 격리 정합(Gemini 워커존만, Claude 백엔드만, 데이터존 무egress).
---
## 5. WBS·공수(M/M) 산정 (P8)
> 근거: IMPLEMENTATION_BACKLOG Phase A~E·PLANNING §9 로드맵(Phase 1~3 각 ~4개월)·142 REQ·18 모듈. 산정 기반=유사 공공 AI SI 생산성 + 기능 규모(100대 기능: 기구현 63·부분 18·신규 19) + 라이브 스캐폴드로 인한 **착수 리스크·초기 구축 공수 절감** 반영.
### 5-1. WBS 구조 (Phase × 산출물)
| Phase | 기간(가정) | 주요 작업(WBS) | 완료 게이트 |
|---|---|---|---|
| **A 아키텍처·거버넌스** | 착수~1M | AA/SA/TA/DA/NA 5종 아키텍처(**완료**)·정합 검증 | 아키텍처 확정·불일치 0 |
| **B 공통/시스템관리 레이어** | ~Phase1 내 | 인증(JWT/2FA)·시스템관리·공통 업무기능·공통 컴포넌트(WISE 이식) | 2FA/RBAC/감사 왕복(**대부분 라이브**) |
| **C P0 부스 코어** | Phase1(~4M) | M2 플로어플랜(3안·규정검증)·M3 부스설계·M4 배선·M5 나노바나나 | 3안·병합·재검증·시각화 |
| **D P1 도메인** | Phase2(~4M) | M15 옥션·M10 관람·M12/17 CMS/공개·M16 BI·M18 관리자·M1/6/7/9 | 각 모듈 왕복·QA 통과 |
| **E P2·배포·확장** | Phase3(~4M+) | M11·M13·M14·**멀티테넌시**·역할별 번들 분리·배포 안정화·SM 이관 | (G2 후)배포·이관 |
### 5-2. 직군별 공수 산정 (M/M)
> 12개월(Phase 1~3) 기준. 라이브 스캐폴드/인프라/인증 실적으로 초기 구축 공수를 이미 일부 소화 → 산정에 반영(과다 산정 금지). Phase A는 대부분 완료(감독 공수만 잔여).
| 직군 | Phase 1 | Phase 2 | Phase 3 | 합계(M/M) | 산정 근거 |
|---|---|---|---|---|---|
| 총괄 PM | 4 | 4 | 4 | 12 | 상주 1.0 FTE |
| 아키텍트(AA·SA·TA·DA·NA) | 8 | 4 | 2 | 14 | Phase A 집중(완료)→거버넌스 감독 |
| 백엔드(공통·코어·도메인) | 12 | 16 | 12 | 40 | 18모듈 코어, 최대 투입 직군 |
| 프론트엔드(역할별 6포털) | 8 | 12 | 8 | 28 | Stitch 이식+역할별 번들 |
| DB 엔지니어(PostGIS) | 4 | 4 | 2 | 10 | 공간 스키마·매퍼·BI 마트·멀티테넌시 |
| AI 개발(Claude·제약 솔버) | 4 | 4 | 2 | 10 | 배치 솔버·규정보조·예측·AiTextRouter |
| 시각화(나노바나나 워커) | 4 | 2 | 2 | 8 | 파이프라인(라이브)·샷세트·품질 |
| QA | 4 | 6 | 6 | 16 | 점진 경계면·보안 불변·회귀 |
| DevOps/인프라 | 2 | 2 | 4 | 8 | CI/CD(라이브)·배포·이관 |
| **소계** | **50** | **54** | **42** | **146** | |
- **총 공수: 약 146 M/M**(핵심 개발) + PMO/형상관리·품질보증 오버헤드(약 4~8 M/M) → **총 ~150 M/M 규모**.
- **가격평가·투입계획 정합**: 위 산정은 가격제안 투입인력표(직군·기간·M/M)와 1:1 매핑. 라이브 실적(스캐폴드·인증·인프라·나노바나나)이 Phase A/B 공수를 실측 절감 → 동일 규모 대비 **착수 리스크·초기 구축비 우위**.
- **주의**: 예산·사업기간은 실제 RFP 부재로 [가정](공공 SI 통례). 실제 공고 확인 시 M/M·기간 즉시 재정렬.
---
## 6. SM 운영 체계 (SLA·장애대응·정기점검·CI/CD 운영)
> SI 구축 후 유지보수/운영 제안. **이미 라이브인 자동배포 파이프라인을 실적으로 인용**(과장 아님 — WORK_STATUS §2·§7 검증분).
### 6-1. 운영 체계·조직(R&R)
- **서비스 데스크·ITSM 프로세스**: 요청(SR)·장애(Incident)·변경(Change)·배포(Release)·문제(Problem·RCA). 공통 업무모듈(통합검색·알림·회의록)·감사로그 기반 티켓 이력.
- **조직**: 운영 총괄 1 + 백엔드/프론트 유지보수 + DB/인프라(DevOps) + AI 워커 담당 + QA. 근무체계=평일 상주 + 행사 성수기(3~5·9~11월) 온콜.
### 6-2. SLA 지표
| 지표 | 목표 | 측정 |
|---|---|---|
| 코어 서비스 가용성 | **99.5%**(성수기 99.9% 지향) | 월 가용성·`/actuator/health` |
| 장애 응답시간 | 심각도별(P1 즉시·P2 30분·P3 4시간) | 티켓 타임스탬프 |
| 장애 복구시간(MTTR) | P1 ≤2h·P2 ≤1영업일 | 복구 완료 기록 |
| 배포 성공률 | ≥99%(Fail-Safe 롤백 자동) | 배포 로그 health 게이트 |
| 나노바나나 큐 소진 | best-effort(피크 워커 스케일아웃) | 큐 적체·처리량 |
측정·보고: 월간 SLA 리포트(가용성·MTTR·티켓·배포). 페널티 체계는 계약 조건에 따름(RFP 확인 필요).
### 6-3. 유지보수 활동
- **예방정비·정기점검**: DB 인덱스/통계·복제 지연·백업(PITR) 정상성, Redis AOF·큐 백로그, 워커 하트비트, 디스크/스토리지 용량, 인증서(TLS) 만료 점검.
- **패치/보안 업데이트**: OWASP Dependency-Check SCA 정기 스캔(REQ-S-019)·의존성 패치, OS/미들웨어 보안 패치. 룰셋(요율·규정) **무중단 개정**(버전 데이터, M18 백오피스·감사 기록).
- **성능 튜닝**: PostGIS 공간 쿼리(GiST·EXPLAIN ANALYZE)·Hikari 풀·읽기복제 라우팅·BI 배치 ETL 시간 최적화.
- **형상관리**: Gitea `zio/kintex`·Conventional Commits·main 보호·환경 분리(dev/staging/prod).
### 6-4. 장애 대응
- **등급분류·에스컬레이션**: P1(서비스 중단)~P4(경미). 자동 알림(WebSocket/통합 알림센터)·온콜 에스컬레이션.
- **RCA·재발방지**: 장애 후 근본원인 분석(RCA) 리포트·재발방지 조치 티켓화. 감사로그·관측성(로그/메트릭/트레이스, PII·스택트레이스 미기록)로 추적.
- **degraded/BCP·DR**: G1/Gemini 장애=워커 목 응답(구조·워터마크 유지), Claude 장애=Ollama 폴백, PG 장애=자동 failover+PITR, 배포 실패=자동 롤백. 데이터 백업·복구 절차(RPO 최소·RTO 분 단위).
### 6-5. CI/CD 운영 (라이브 실적 인용)
- **자동배포 파이프라인(라이브·검증됨)**: `workspace/kintex` → Gitea webhook → `deploy_kintex.sh`(bootJar + vite build → 배포 → **health 게이트 → 실패 시 롤백**). push 시 자동배포. (WORK_STATUS §2·§7)
- **운영 함정 숙지(실측 교훈)**: 서버 `/opt/zioinfo/deploy_server.py`(kintex 블록)·`/opt/kintex/` 수정 시 **반영+재시작 필수**(로컬만 고치면 웹훅 1ms no-op), 백엔드도 반드시 빌드, `sh ./gradlew`(실행권한), 로컬 vite rollup win32 크래시=**서버 빌드 신뢰**(tsc 통과 검증).
### 6-6. 이행/이관
- 인수인계(WORK_STATUS.md 인수인계 문서 체계 활용)·안정화·지식이전(운영자/개발자 지침서 PPT·프로그램 사양서)·종료 시 이관 계획. 운영 도메인 `kintex.wise.ai.kr` 전환(후속).
---
## 7. RTM 기술 파트 갱신 입력 (REQ ↔ tech_advisory 절 매핑)
> rfp-analyst RTM 반영상태 갱신용. 각 REQ 계열이 본 자문서 어느 절에서 기술적으로 대응되는지 매핑. QA는 이 표로 기술 파트 커버리지 교차 점검.
| REQ 계열 | 범위 | tech_advisory 대응 절 | 제안서 목차 |
|---|---|---|---|
| REQ-F-007~019(배치·설계·배선 코어) | M2~M4 | §2 WT-2, §1-2, 도식 ⑤⑥ | P3 |
| REQ-F-025~032(옥션) | M15 | §2 WT-3, 도식 ⑦⑧ | P3 |
| REQ-F-037~055(관람·현장·물류) | M8·M10~M14 | §1-2 App/데이터, §3(오프라인 폴백 N-폴백) | P3 |
| REQ-F-061~066(BI) | M16 | §1-2 데이터, §3 REQ-N-021, data.md 마트 | P3 |
| REQ-F-071~081(관리·공통·멀티테넌시·포털) | M18·§5B·§1A | §1-2·§1-3, 도식 ⑪ | P4·P5·P7·P8 |
| REQ-F-001~006·020~024·033~036·048~051·056~060·067~070 | 판매·서류·정산·CMS·공개 | §1-2 계층·§2 WT, §6(룰셋 운영) | P3 |
| **REQ-A-001~008**(나노바나나) | M5 | §2 WT-1, 도식 ③④ | P3(핵심) |
| REQ-A-009·010·020(배치·규정·비전) | M2/M3 | §2 WT-2 | P3 |
| REQ-A-013·014(예측·KPI·Text-to-SQL) | M16 | §1-2 AI(텍스트), §3 N-021 | P3 |
| REQ-A-016·017(라우터·RAG·환각) | §6 | §1-2 AI(텍스트), §4(abstain) | P4·P5 |
| REQ-A-011·012·015·018·019(검수·챗봇·카피·리드·이상탐지) | 다수 | §1-2 AI(텍스트) | P3 |
| **REQ-N-001~021** | 비기능 21 | **§3 전체 표(21행 1:1)** | P6·P4 |
| **REQ-S-001~020** | 보안 20 | **§4 전체 표(20행 1:1)** | P5 |
| (인프라·HA·배포·관측성) | N-002·003·004·018 | §1-2·§3·§6 SM·§0 실적 | P4·P6·P8 |
---
## 요약 보고 (오케스트레이터·writer·deck-designer용)
**1. 도식 12종 사양 완비 여부**: ✅ **12/12 완비**(§1-4). ①3중 해자 벤 ②모듈맵 ③나노바나나 파이프라인 ④Before/After ⑤3안 비교 ⑥PostGIS 배선 ⑦옥션 폐루프 ⑧종합평가 스코어 ⑨시스템 아키텍처 ⑩보안영역 분리 ⑪멀티테넌시 격리 ⑫일정 간트 — 각 박스·연결·라벨 텍스트 작도 사양 기술. 추가 표준 도식 3종(추진체계도·리스크 매트릭스·기대효과)은 사양 위치 지정(§1-4 말미).
**2. REQ 대응 커버리지**: **미대응 0**. REQ-N 21건 전부(§3 표 21행 1:1), REQ-S 20건 전부(§4 표 20행 1:1), REQ-F/REQ-A는 §1-2·§2 Win Theme·§7 매핑표로 전 계열 대응. 총 142 REQ 기술 파트 커버(§7 RTM 갱신 입력).
**3. 공수 총 M/M**: **약 146 M/M**(핵심 개발, 직군 9종×Phase 3구간) + PMO/QA 오버헤드 4~8 → **총 ~150 M/M 규모**(12개월·Phase 1~3). 라이브 스캐폴드·인증·인프라·나노바나나 실적으로 Phase A/B 공수 실측 절감 반영 = 동일 규모 대비 착수 우위.
**4. 과장 방지 준수**: 라이브 확인분(인프라·CI/CD·나노바나나·인증·워터마크·PostGIS 코어·평면도 자산)만 "구축 완료/검증됨", 도메인 모듈·멀티테넌시·집계 API·i18n/접근성 전면 적용은 "구현 계획"으로 명확 구분(§0). 시크릿(키·비번·내부IP) 전면 미기재.
**5. 파일**: `C:\GUARDiA\workspace\kintex\_workspace\proposal\tech_advisory.md`

274
plugins/zio-harness/knowledge/kintex/docs/deliverables/제안서/_gen/visual_concepts.md Normal file
View File

@ -0,0 +1,274 @@
# 킨텍스 자동전시시스템 구축 — 도식 시각 컨셉 (Visual Concepts)
> 작성: proposal-visual-designer · 작성일: 2026-07-11 · 버전 v1.0
> 짝 문서: `design_system.md`(팔레트·타이포·레이아웃) · `assets/icons/*.svg`(선 아이콘 20종) · `tech_advisory.md` §1-4(도식 12종 박스·연결·라벨 사양) · `proposal_outline.md`(슬라이드 배치)
> 목적: 필수 도식 12종 + 표준 3종(추진체계·리스크·기대효과) + 표지·간지·3중 해자의 **시각 컨셉을 좌표·색·라벨 수준으로 구체화**. deck-designer가 python-pptx로 재해석 없이 작도.
> 좌표 규약: 단위 **inch**, 16:9 캔버스 13.333×7.5, 콘텐츠 폭 12.23(x 0.55~12.78), 본문 콘텐츠 y 1.45~6.9. 색 토큰=`design_system.md` §1. 폰트 맑은 고딕.
> 공통: 노드=ROUNDED_RECTANGLE, 카드 그림자 alpha 18%, 연결 화살표="→"(15pt)/"›"(16pt) SLATE, 하단 캡션 MUTED 9pt 1줄. **본문 10pt 하한 준수**.
---
## A. 표지 (S01) — "도면이 아니라 사진으로 컨펌한다"
**컨셉**: 좌측은 절제된 텍스트 존, 우측은 나노바나나 시공 예측 이미지가 대각으로 침투 — "왼쪽은 제안(텍스트), 오른쪽은 결과(사진)"의 물리적 은유.
- **배경**: `BLUE_DK` 풀블리드(-0.1,-0.1,13.53,7.7).
- **우측 대각 이미지 존**: 평행사변형 2매 겹침 — ①`BLUE` (6.4,-1.5,9,11, PARALLELOGRAM) ②`PURPLE` (9.2,-2.0,7,12, PARALLELOGRAM). **그 위에 나노바나나 생성 부스 시공 사진(워터마크 포함)을 반투명(alpha ~35%) 합성** — 이미지 없으면 blue→purple 그라디언트 도형으로 대체(폴백). 이미지 우하단에 소형 워터마크 배지 "AI 생성 예상 이미지".
- **좌상 브랜드**: WHITE OVAL(0.85,0.8,0.42) + PURPLE 코어 OVAL(0.97,0.92,0.18) + "KINTEX · WISE AI" 15pt WHITE Bold (1.42,0.78).
- **문서 배지**: (0.85,2.35) "기술제안서" PURPLE 12pt / (2.72,2.35) "Technical Proposal" 딥블루 10.5pt.
- **대제목** (0.85,2.9,11,1.9): 2줄 46pt WHITE Bold — "킨텍스 자동전시시스템" / "구축 기술제안서". line 1.02.
- **슬로건 배너**(핵심): (0.85,4.75,11.4,0.7) 반투명 화이트 라운드 rect(alpha 12%) 위 PURPLE 좌측 바 + "신청서를 내는 순간, 시공 후 사진을 먼저 본다." 18pt WHITE Bold.
- **서브 카피** (0.88,5.6): "설계 → 시각화 → 발주 → 시공 → 운영 → 분석. 킨텍스에서 한 흐름으로 끝난다." 12.5pt `#B9C7EA`.
- **하단 메타바** (0.85,6.15 라인): 사업명·기술스택 2줄 + 우측 "작성일 2026-07-11". 개발계획서 표지 하단과 동일 구조.
- **아이콘 앵커**: 슬로건 좌측에 `camera-render` 근사 도형(WHITE stroke).
---
## B. 간지 (Section Divider) — P1~P9 공통 템플릿
**컨셉**: 개발계획서 간지 계승 + **배점 배지 추가**(제안서 배점 규율 시각화).
- 배경 `BLUE_DK` + 우측 평행사변형 2매(BLUE 8.6,-1.5,8,11 / PURPLE 10.9,-2,6,12).
- 좌측 대형 넘버 150pt `#2C4E82` (1.0,2.15). PURPLE 언더바(1.15,3.9,0.9,0.09). 국문 제목 34pt WHITE(1.15,4.05). 영문 13pt `#9CB4D8`(1.18,4.85).
- 우측 포인트 3개: PURPLE OVAL 불릿(8.05,y) + WHITE 12.5pt(8.35,y), y=2.35+i*0.62.
- **★배점 배지 (우상단, 신규)**: (10.3,0.7,2.2,0.62) 라운드 rect, fill=섹션색(P3=PURPLE, 그 외 BLUE), WHITE Bold — 예 "기술제안 · 35점". P3만 PURPLE로 최다 배점 강조.
- 섹션별 넘버/제목/영문/포인트/배점:
| 섹션 | No | 제목 | EN | 배점배지 | 포인트 3 |
|---|---|---|---|---|---|
| P1 | 01 | 사업이해 | BUSINESS UNDERSTANDING | 사업이해·전략 10점(BLUE) | As-Is 병목 / 6역할 페르소나 / To-Be 정량목표 |
| P2 | 02 | 추진전략 | STRATEGY | Win Theme 5선(BLUE) | 3중 해자 / 생애주기 폐루프 / 추진체계 |
| P3 | 03 | 기술제안 | TECHNICAL SOLUTION | 기술제안 · 35점(PURPLE) | 나노바나나 시공예측 / 배치·설계·배선 AI / 옥션 폐루프 |
| P4 | 04 | 아키텍처·기술스택 | ARCHITECTURE | 아키텍처 10점(BLUE) | 확정 스택 4-Tier / 단일 공간원천 / AI 라우팅 |
| P5 | 05 | 보안·개인정보 | SECURITY & PRIVACY | 보안 10점(BLUE) | 워터마크 / PII 3중격리 / 망분리 |
| P6 | 06 | 비기능(NFR) | NON-FUNCTIONAL | 비기능 8점(BLUE) | SLO 99.5% / 렌더 40초 / 접근성·다국어 |
| P7 | 07 | 멀티테넌시·확장 | MULTI-TENANCY | 확장 5점(BLUE) | 격리 아키텍처 / 온보딩 6단계 / COEX 확장 |
| P8 | 08 | 사업관리·일정·조직 | PROJECT MANAGEMENT | 사업관리 2점(BLUE) | Phase 간트 / 선행게이트 / 품질관리 |
| P9 | 09 | 기대효과 | EXPECTED BENEFITS | 가점(PURPLE) | 정량 ROI / 정성효과 / 확장비전 |
---
## C. 필수 도식 12종
### ① 3중 해자 벤다이어그램 (S04 요약판 · S12 상세판) ★최중요
**컨셉**: 3원 60% 교집합. 중앙 교집합만 컬러 채도 최대(해자), 2원 교집합은 회색(모방 가능). "결합의 희소성"을 색 채도로 표현.
- **3원 배치**(정삼각 구도, 반경 r=1.9): 원A 중심(5.4,3.6) `PURPLE` stroke 2.5pt + PURPLE_LT 반투명 fill / 원B 중심(7.9,3.6) `BLUE` / 원C 중심(6.65,5.5) `TEAL`. OVAL 도형, fill은 반투명(alpha 22%)로 겹침 표현.
- **원 라벨**(각 원 바깥 가까이):
- 원A(좌상) `ai-sparkle` 아이콘 + "나노바나나 시공 예측 이미지" 13pt PURPLE Bold / 부제 "image-to-image 구조보존 · 40초 · S1~S7" 8.5pt MUTED.
- 원B(우상) `postgis-spatial` + "PostGIS 실측 공간데이터" 13pt BLUE Bold / "부스 폴리곤·트렌치·배선 LineString 단일 원천".
- 원C(하) `closed-loop`+`auction-gavel` + "공사 옥션 폐루프" 13pt TEAL Bold / "AI 자료→응찰→낙찰→발주 자동전환".
- **중앙 3원 교집합**(6.65,4.2 부근): 강조 배지 라운드 rect(INK fill) + WHITE Bold "우리만의 해자(Moat)" 11pt / 소자 "재현 난이도 높은 결합".
- **2원 교집합 3곳**: 소형 회색 라벨 "단일 요소는 모방 가능" 8pt SLATE.
- **하단 캡션**(중앙 정렬): "셋의 결합은 경쟁 전시테크·범용 SI가 재현하기 어렵다." 9.5pt MUTED.
- S04(요약판)=벤+한줄, S12(상세판)=벤 좌측 + 우측에 3결합 재현난이도 근거 3불릿 카드(strategy §3-3).
### ② 모듈맵 — 생애주기 × 우선순위 매트릭스 (S16)
- **매트릭스 프레임**: x=생애주기 6단계 열, y=우선순위 3행(P0/P1/P2). 콘텐츠 영역(0.55,1.7)~(12.78,6.2).
- **열 헤더**(y=1.7, 각 폭 ~1.95): "판매·기획" / "설계·시각화" / "발주·계약" / "참가·관람" / "현장운영" / "사후·경영". BLUE 밴드 WHITE 10pt Bold.
- **행 라벨**(좌측 x=0.55, 폭 0.9): P0(PURPLE)/P1(BLUE)/P2(SLATE) 세로 배지.
- **모듈 칩** 배치:
- **P0행**(굵은 테두리 2pt·PURPLE·강조): M2 플로어플랜(설계열) · M3 부스설계 · M4 유틸리티 · M5 나노바나나. 각 칩에 대응 아이콘(`booth-layout`/`camera-render`/`wiring-power`/`ai-sparkle`).
- **P1행**(BLUE 1pt): M1(판매)·M16(사후, 2회 span)·M6/M7(발주)·M15 옥션(발주·강조 테두리)·M10(참가)·M12·M17(참가/사후)·M18(전열 하단)·§5B·§1A.
- **P2행**(SLATE): M8·M11·M13·M14(현장운영열 집중).
- **하단 레이어 띠 2줄**(y~5.8): ①BLUE_LT 풀폭 "공통/시스템관리 레이어(§5B) — 전 모듈 선행 기반" ②PURPLE_LT "멀티테넌시(§1A) — tenant_id 격리".
- **캡션**: "18개 모듈 + 공통 레이어를 한 장으로 조망. P0 4개가 심장." 9.5pt.
### ③ 나노바나나 파이프라인 플로우 (S20) ★WT-1
**컨셉**: 좌→우 8박스 수평 플로우. 전면 비동기를 "동기 대기 없음" 배지로 각인. AI 구간(워커·Gemini)만 PURPLE, 나머지 BLUE.
- **박스 8개**(y=2.6, 높이 0.95, 폭 ~1.35, gap 0.06):
1. `[사용자: 렌더 요청]` BLUE_LT (아이콘 `mobile`)
2. `[Spring 백엔드: RenderJob 생성·쿼터 확인]` WHITE/BLUE
3. `[Redis 큐 leftPush]` WHITE/BLUE (아이콘 `pipeline-flow`)
4. `[나노바나나 Python 워커 (BLPOP)]` PURPLE_LT/PURPLE (아이콘 `ai-sparkle`)
5. `[Gemini image-to-image (G1 승인·라이브)]` PURPLE_LT/PURPLE
6. `[워터마크 후처리 · S6 로컬 PIL 래스터]` PURPLE_LT/PURPLE (아이콘 `watermark`)
7. `[오브젝트 스토리지 적재]` WHITE/BLUE
8. `[WebSocket/STOMP → 프론트 완료 푸시·갤러리 갱신]` BLUE_LT
- 박스 사이 "→" 15pt SLATE.
- **분기 주석**(워커 하단 점선 콜아웃, AMBER 테두리): "degraded: G1 미승인/Gemini 장애 시 목(mock) 응답 — 구조·워터마크 유지". 옆에 "성공 시에만 쿼터 차감" GREEN 소배지.
- **보안 배지**(우상단): `shield-security` + "GEMINI_API_KEY = 워커 env only (백엔드 미취급)" 9pt RED 테두리.
- **라이브 배지**: 박스4·5에 GREEN "라이브" 소배지("이미 돈다").
- **캡션**: "이미지 생성 전면 비동기 — 사용자 동기 대기 없음, 평균 40초." 9.5pt.
### ④ Before/After 슬라이더 (S21)
- **좌우 분할 이미지 카드**(2.0,2.0,9.3,3.3): 좌반부=빈 부스(HALL_BG + 도면 라인 오버레이), 우반부=시공 후(BLUE→PURPLE 그라디언트 + 나노바나나 이미지 자리).
- **중앙 세로 드래그 핸들**(x≈6.65): 세로 WHITE 라인 3pt + 중앙 원형 핸들(WHITE OVAL + `‹›` 양방향 화살표).
- **라벨**: 좌상단 "Before: 빈 부스 (도면/실측)" 칩 SLATE / 우상단 "After: 시공 후 예상 (AI 생성)" 칩 PURPLE.
- **접근성 배지**(하단): `check-verify` + "ARIA slider · 키보드 좌우 조작 지원 (WCAG AA)" 9pt.
- **워터마크 고지 배지**(맨 하단, RED 테두리): "AI 생성 예상 이미지 — 실제 시공과 다를 수 있음. 계약·심사 서류 사용 금지." 8.5pt.
- **우측 배선 색상 범례 미니**(S21이 배선 오버레이 겸함): 전기=RED / 네트워크=CYAN / 급배수=TEAL 3줄(색 사각+텍스트+선스타일 실선/파선/점선).
### ⑤ 3안 비교 화면 목업 (S24)
- **상단 홀 정보 바**(0.55,1.6,12.23,0.5) BLUE_LT: "제1전시장 5홀 · 판매가능 10,080㎡ · 통로규정 v3" 좌 + `booth-layout` 아이콘.
- **3열 카드**(각 3.9 폭, gap 0.28, y 2.25, 높이 3.3):
- 카드 상단 헤더바: "안 1 — 통로 효율 최대"(BLUE) / "안 2 — 프리미엄 부스 최대"(PURPLE) / "안 3 — 균형"(TEAL).
- 본문: 미니 배치도 썸네일(HALL_BG + 부스 폴리곤 격자 도형) + 지표 3행 "판매면적 ㎡ / 부스 수 / 규정위반 0건"(위반0=GREEN 체크 `check-verify`).
- 안2는 프리미엄 강조(굵은 부스 몇 개), 안3은 균등 격자.
- **하단 액션 바**(0.55,5.75,12.23,0.6): 버튼칩 3개 "[안 선택]" BLUE / "[구역·블록 병합 편집]" WHITE 테두리 / "[병합 후 재검증]" PURPLE.
- **캡션**: "제약 솔버가 상이한 최적화 목표로 정확히 3안 생성. 사람이 선택·병합·최종 확정." (AI 신뢰 3층 프레이밍).
### ⑥ PostGIS 배선 오버레이 (S27) ★WT-2
**컨셉**: 홀 평면도 위 실측 배선. 3색 규약 고정 + 색맹 안전(선 스타일 병기).
- **평면도 캔버스**(0.55,1.7,8.6,4.6) HALL_BG 라운드:
- **부스 폴리곤** 다수: 연회색(`#D8DEE8`) 사각 격자 도형.
- **트렌치 포인트** ◆: TEAL 다이아 소도형, 라인 따라 배치.
- **분전반** ▣: INK 사각 + 라벨.
- **배선 LineString 3색**(부스→최근접 트렌치→분전반):
- 전기 = `RED` 실선 2pt
- 네트워크 = `CYAN` 파선(dash 6 3)
- 급배수 = `TEAL` 점선(dot 2 3)
- **가정 트렌치**엔 AMBER "가정 좌표(실측 대기)" 소배지.
- **우측 범례·주석 패널**(9.35,1.7,3.4,4.6) WHITE 카드:
- 제목 "배선 색상 범례" + 3색 행(색+선스타일+라벨).
- 주석 배지 3개: "최근접 트렌치 KNN (geom <-> point)" / "최단 경로 ST_Length · 통로 횡단 최소" / "SRID 0 홀 로컬 미터 · GiST 실시간".
- 아이콘 `wiring-power`·`postgis-spatial`.
- **캡션**: "수기 위치표시도 폐지 — 좌표 클릭 자동 작도."
### ⑦ 옥션 폐루프 흐름도 (S29) ★WT-3
**컨셉**: 좌측 AI 자료 패키지 스택 → 우측 순환 흐름. "AI 자료가 곧 발주 근거"를 좌→우 물리 연결로.
- **좌측 AI 자료 패키지 스택**(0.55,2.0,2.6,3.0) PURPLE_LT 카드, 4겹 쌓임 효과:
- "M2 배치 + M3 설계 + M4 배선/BOQ + M5 시공예측 이미지" 각 줄, 아이콘 `booth-layout`/`camera-render`. 상단 `ai-sparkle`.
- **우측 흐름 7박스**(순환 배열 또는 좌→우 2행 지그재그, y 2.0~5.5):
1. `[옥션 개설 (역경매/RFQ/고정가)]` BLUE (`auction-gavel`)
2. `[등록업체 검증 게이트: 미등록 응찰 차단 403]` RED 테두리 강조 (`shield-security`)
3. `[견적서 제출 · PDF · 버전]` WHITE/BLUE (`document-rtm`)
4. `[실시간 순위 · 라운드 마감 (Redis 정렬셋·WS 델타)]` BLUE (`dashboard-chart`)
5. `[종합평가 낙찰 (가격+평판+납기)]` PURPLE (`check-verify`)
6. `[Award → 계약/발주 자동전환 (M6·M9)]` TEAL
- 6→다시 자료로 순환 화살표(`closed-loop` 곡선 화살표).
- **게이트2 강조**: RED "미등록 = 응찰 원천 차단" 배지 — 킨텍스 규정 시스템 강제 포인트.
- **캡션**: "AI 설계자료가 곧 발주 근거. 사진 수준 자료로 응찰→발주까지 한 흐름."
### ⑧ 종합평가 스코어 비교표 (S31)
- **표**(0.55,2.0,12.23): 헤더 BLUE 풀폭 — 열: "업체명 | 견적금액(점수) | 평판(점수) | 납기(점수) | **가중 종합점수** | 순위".
- **행 4~5개**(zebra): 예 A사/B사/C사/D사. 각 셀 숫자 + 괄호 환산점수.
- **가중치 주석 바**(표 상단 또는 하단): "가중치(예): 가격 0.6 / 평판 0.25 / 납기 0.15 — 옥션별 설정형(weight jsonb)" 9pt MUTED.
- **1위 행 강조**: BLUE_LT 배경 + Bold + 우측 "낙찰(Award)" GREEN 배지 + `check-verify`.
- **우측 또는 하단 캡션 카드**: "선정 사유·항목별 비교 근거 자동 산출". 종합점수 열은 막대 미니바(가중합 시각화, BLUE 그라데이션).
- **캡션**: "가격만이 아니라 평판·납기 가중 — 투명·최적 발주."
### ⑨ 시스템 아키텍처 다이어그램 — 전 계층 (S41)
**컨셉**: 개발계획서 아키텍처 밴드도 계승·확장. 상하 6밴드 + 우측 외부 게이트 컬럼.
- **밴드**(좌측 라벨칩 1.55폭 + 본문, 폭 12.23):
1. **엣지/DMZ**(y~1.5): `[CDN·정적캐시]` `[WAF/Reverse Proxy(nginx)·TLS·레이트리밋]` BLUE_LT.
2. **역할별 프론트**(y~2.15): organizer·exhibitor·contractor·ops·admin(내부 배지 회색)·public/visitor(공개 SSR/SEO/다국어 배지). 6노드.
3. **SSO·RBAC**(y~2.8): `[JWT SSO + TOTP 2FA · 이중 RBAC(플랫폼/행사)]` 풀폭 (`shield-security`).
4. **공유 백엔드**(y~3.45, 높이 늘림): `[REST + WebSocket/STOMP]` 상단 + 하위 `[룰엔진]` `[배치·배선 엔진·PostGIS]` `[옥션 M15]` `[BI M16]` `[CMS M17]` `[공개 API read-only]`.
5. **비동기**(y~4.5): `[Redis 큐·순위·타이머·캐시·쿼터]` → `[나노바나나 워커]`(PURPLE) `[서류·EDM 워커]`.
6. **데이터**(y~5.15): `[PostgreSQL+PostGIS]` `[읽기복제(BI·공개)]` `[오브젝트 스토리지]`.
- **우측 외부 게이트 컬럼**(x~11.4 세로): `[Gemini(G1·라이브)]` `[Claude(AiTextRouter)]` `[PG 결제]` `[kxwp 릴레이]` `[등록업체 DB 739]`. 라이브=GREEN 배지.
- **연결 주석**(얇은 선+라벨): 워커→Gemini "egress only" / 워커→백엔드 "WebSocket 완료 푸시" / 백엔드→읽기복제 "BI/공개 오프로드".
- 계층별 색: 표현=BLUE_LT, 백엔드=WHITE/BLUE, AI밴드=PURPLE_LT, 데이터=HALL_BG.
### ⑩ 보안영역 분리도 (망 구성) (S47) ★WT-4
**컨셉**: 좌→우 신뢰도 상승 존. 철칙 배지를 굵게. `network-zone` 메타포.
- **존 박스 6개**(좌→우, 각 폭 ~2.0, y 2.2 높이 3.0, 우로 갈수록 테두리 진하게):
1. `[인터넷]` SLATE
2. `[엣지: CDN·WAF·DDoS]` BLUE_LT
3. `[DMZ(공개): 공개LB·public SSR·visitor GW·공개 API·PG콜백 — 쓰기권한 없음]` BLUE
4. `[내부망(인증): 내부LB·SSO/2FA·내부 API·공유 백엔드]` BLUE_DK
5. `[AI 워커존(egress 제한): Redis·나노바나나·Ollama]` PURPLE
6. `[데이터존(최내곽): PostgreSQL+PostGIS·오브젝트·읽기복제 — 아웃바운드 전면 차단]` INK
- 존 사이 화살표 "HTTPS만" 라벨.
- **상단 관리존**(가로 띠): `[관리존: 배스천·관측성 — VPN/허용IP+2FA, 인터넷 미도달]`.
- **철칙 배지 3개**(하단, RED 굵은 테두리): "DMZ → 데이터존 직접 접근 절대 금지" / "데이터존 아웃바운드 0 (유출경로 제거)" / "admin = VPN/허용IP+2FA".
- **egress 컬럼**(우측): "승인 4목적지만 — Claude·Gemini·PG·SMTP / 그 외 DROP" (`shield-security`).
- **캡션**: "공개/내부 물리·논리 분리 · 데이터존 무egress로 유출경로 자체 제거."
### ⑪ 멀티테넌시 격리 아키텍처도 (S56)
**컨셉**: 수직 4층 방어 스택. fail-closed를 "한 층이라도 불일치 = 차단" 배지로.
- **좌측 진입**(1.0,2.0,3.2,1.4): `[요청: 서브도메인(kintex./coex.) + JWT 사용자 소속]` → `[테넌트 컨텍스트 해소: 불일치 시 거부]` (`tenant-building`).
- **중앙 4층 방어 스택**(위→아래, 각 폭 5.0, 높이 0.85, y 2.0~5.5):
1. `[①컨텍스트 필터]` BLUE_LT
2. `[②서비스 가드]` BLUE
3. `[③MyBatis 공통 인터셉터 (tenant_id 자동 주입)]` BLUE_DK
4. `[④PostGIS/쿼리: tenant_id 선두 복합 인덱스]` PURPLE
- 층 사이 아래 화살표.
- **우측 데이터 표현**(9.3,2.0,3.4,3.5) WHITE 카드: `[TB_* … WHERE tenant_id = ctx]` 격리 도형 — KINTEX(#1)·COEX(#2) 두 색 파티션 시각화.
- **하단 배지**(RED): "fail-closed — 한 층이라도 불일치면 차단".
- **캡션**: "KINTEX #1 검증 → COEX #2 코드 배포 없이 데이터 온보딩. 기능 불변, 데이터·권한만 분리."
### ⑫ 일정 간트 (Phase × 모듈) (S58)
**컨셉**: 개발계획서 간트 계승. 3구간 + 라이브 실적(GREEN 완료)으로 "이미 돈다" 실증.
- **타임라인**(gx=3.55, gw=9.15, 3구간 Phase1/2/3 각 ~4M 눈금).
- **상태 범례**(우상단): 완료 GREEN / 진행 AMBER / 예정 SLATE.
- **워크스트림 막대 행**(좌측 Phase+워크스트림 라벨, 우측 막대):
- Phase1: 아키텍처(A·완료 GREEN) / 공통레이어 B 2FA·시스템관리(완료 GREEN) / P0 코어 M2·M3·M4·M5(진행 AMBER, 하위 "스캐폴드·인증·매퍼·룰엔진·나노바나나=완료 GREEN" / "3안·병합·실데이터=진행 AMBER").
- Phase2: 옥션 M15 / 관람 M10 / BI M16 / 관리자 M18 / 판매·서류·정산 M1·M6·M7·M9 / CMS M12·M17 (예정 SLATE).
- Phase3: 멀티테넌시 / M11·M13·M14 / 배포 안정화·SM 이관 (예정 SLATE, 배포 일부 진행 AMBER).
- **마일스톤 다이아몬드**(◆): G1(나노바나나 승인·완료 GREEN) · G2(배포서버·완료 GREEN) · Phase 게이트 · QA 게이트 · 오픈.
- **현재 시점 마커**: PURPLE 세로선 + "현재".
- **캡션**: "선행 게이트 통제 + Phase 게이트 QA 통과 후 진행. G1·G2 완료 — 실증 기반." (`schedule-gantt`).
---
## D. 표준 필수 도식 3종
### ⑬ 추진체계도 (조직도) (S15)
- **최상위**(중앙 4.9,1.5,3.55,0.72) BLUE: "프로젝트 총괄 (PM)" / "범위·일정·리스크·게이트(G1·G2)" (`org-people`).
- **2단**(연결선 아래): "개발 PM"(PURPLE) / "PMO"(PURPLE).
- **3단 아키텍트 그룹**(BLUE_LT 띠): AA·SA·TA·DA·NA 5노드(WHITE/BLUE) — "앱/시스템·NFR/기술표준/데이터·ERD/네트워크·보안".
- **4단 구현 그룹**(PURPLE_LT 띠): 공통/시스템·백엔드·프론트·DB·도메인(bidding·visitor·cms·bi·admin)·AI·시각화 6노드(WHITE/PURPLE).
- **하단**: 품질(kintex-qa · GREEN) / 배포(devops-dev · 딥블루).
- 개발계획서 조직도와 동일 구조 재사용 — 제안서용으로 "발주처 보고 라인" 소표기 추가 가능.
### ⑭ 리스크 매트릭스 (S59)
**컨셉**: 발생가능성 × 영향도 2축 4사분면 버블 + 게이트.
- **매트릭스**(2.5,1.8,6.5,4.5): x=발생가능성(낮→높), y=영향도(낮→높). 4사분면 배경 명도(우상=RED_LT 위험, 좌하=GREEN_LT 안전).
- **버블**(R-1~R-8 배치, tech_advisory/strategy §4):
- R-1(나노바나나 미승인) 고영향·중발생 → 우상 근처, AMBER.
- R-2(CAD·트렌치 미확보) 고영향·중발생 AMBER.
- R-3(kxwp 폐쇄 API) 중·중 SLATE.
- R-4(배점 가정) 중·중, R-5(간판 품질) 중·중, R-6(AI 환각) 고·저, R-7(HW 연동) 중·저, R-8(확장 부담) 저·저 GREEN.
- 버블 크기=영향도, 색=위험등급, 라벨 "R-n" + 툴팁 텍스트 소자.
- **우측 게이트·대응 패널**(9.3,1.8,3.4,4.5) WHITE 카드: "선행 게이트 G1(완료)·G2(완료)" + "각 리스크 방어 논리 1줄" 스크롤 리스트 + `check-verify`/`risk-warning`.
- **캡션**: "약한 고리를 선제 노출·방어 — 숨기지 않아 신뢰."
### ⑮ 기대효과 정량 인포그래픽 (S61)
- **5지표 Before/After 카드**(5열, 각 2.4 폭, y 1.85, 높이 1.85) — 개발계획서 기대효과 카드 계승:
| 지표 | As-Is(SLATE) | ↓(PURPLE) | To-Be(BLUE) |
|---|---|---|---|
| 홀 배정 견적 | 수일 | | 즉시 |
| 배치도 초안 | 수일~수주 | | 수 분 |
| 규정 검수 | 육안 검토 | | 자동 플래깅 |
| 유틸리티 신청 | 수기 작도 | | 클릭+자동견적 |
| 시공 결과 예측 | 불가(외주) | | 표준 샷 자동생성 |
- 각 카드: 지표명 Bold + As-Is(회색) + ↓ 화살표 PURPLE + To-Be(BLUE Bold) + 대응 아이콘(`document-rtm`/`booth-layout`/`check-verify`/`wiring-power`/`camera-render`).
- **하단 임팩트 지표 스트립**(대형 수치): "40초 렌더 · 99.5% SLO · 142 REQ 커버 · 18 모듈" BLUE/PURPLE 교차 KPI 카드.
- **캡션**: "리드타임 수일→즉시·수분, 검수 육안→자동. 정량 개선을 숫자로 각인."
---
## E. deck-designer 작도 체크리스트
1. **색 규율**: 퍼플=AI/나노바나나 전용. 배선 3색 고정(전기 RED 실선 / 네트워크 CYAN 파선 / 급배수 TEAL 점선) — 색+선스타일 이중 인코딩(색맹 안전).
2. **라이브 배지(GREEN "이미 돈다")**: 나노바나나 파이프라인(③)·간트(⑫)·아키텍처(⑨) 외부게이트에 반드시 표기 — tech_advisory §0 실증 우위.
3. **워터마크 고지**: Before/After(④)·AI 이미지 보안 슬라이드에 RED 테두리 고지 배지 필수(REQ-S-009).
4. **캡션 1줄**: 12종 각 도식 하단에 tech_advisory 지정 캡션 그대로. MUTED 9~9.5pt.
5. **아이콘**: `assets/icons/*.svg` 20종 — 헤더 앵커는 도형 근사, 콘텐츠 아이콘은 PNG 변환 후 stroke=맥락색. 이모지 금지.
6. **가독성**: 본문 10pt 하한, 한 슬라이드 1 도식/1 메시지, 여백 확보. 도식 박스 라벨 8~10pt.
7. **배점 규율 시각화**: 간지 배점 배지(P3=PURPLE 35점 최강조), 모듈맵 P0 굵은 테두리.
8. **보안**: 시크릿·내부IP·키값 도식·라벨 미기재. 외부 API는 "승인 예외/env only"로만.

1924
plugins/zio-harness/knowledge/kintex/docs/design.md Normal file
View File

File diff suppressed because one or more lines are too long

138
plugins/zio-harness/knowledge/kintex/docs/security/mobile-security-audit.md Normal file
View File

@ -0,0 +1,138 @@
# KINTEX AI 모바일 앱 + 백엔드 보안 감사 결과
> 감사일: 2026-07-12 · 감사자: 통합 QA(reviewer) · 방식: 정적 소스 감사(코드 미수정, 읽기전용)
> 체크리스트: `mobile-security-checklist.md` · 개선 백로그: 본 문서 §하단
> 증거는 `파일:라인` 표기. `mobile/`는 다른 에이전트 편집 중이라 스냅샷 기준.
## 종합 판정
| 영역 | PASS | FAIL | N-A | 총평 |
|------|:----:|:----:|:---:|------|
| 1. 위변조 방지 | 1 | 5 | 0 | **최대 약점** — 루트/디버거/무결성 탐지·난독화 선언 부재 |
| 2. 데이터 보호 | 5 | 2 | 0 | SecureStore·로그 청결 우수 / FLAG_SECURE·백그라운드 마스킹 부재 |
| 3. 통신 보안 | 2 | 2 | 0 | HTTPS 강제 / cleartext 차단 선언·피닝 부재 |
| 4. 인증·세션 | 4 | 1 | 0 | 2FA·잠금·RBAC 견고 / 생체 로컬잠금 부재 |
| 5. 시큐어 코딩 | 7 | 0 | 0 | **모범** — SQLi 가드·CSPRNG·스택트레이스 차단 완비 |
| 6. 빌드·배포 | 4 | 2 | 0 | env 시크릿·오류응답 청결 / 권한 최소화·CORS 명시 보강 |
전반: **백엔드·시큐어코딩은 공공 기준 대비 견고**. **모바일 클라이언트 측 위변조 방지(anti-tampering)와 화면보호가 최대 갭** — 공공 대민 앱 기준(KISA 위변조 항목군)에서 필수 보강 대상.
---
## 1. 앱 위변조 방지
| ID | 판정 | 위험도 | 증거 / 근거 |
|----|------|--------|-------------|
| AT-1 루트/탈옥 탐지 | **FAIL** | High | package.json 의존성에 `jail-monkey`·`freerasp`·root 탐지 라이브러리 없음(mobile/package.json 13~33). 코드 내 탐지 로직 0건. |
| AT-2 서명/무결성 | **FAIL** | High | Play Integrity/App Attest·서명 지문 검증 코드 없음. 리패키징 탐지 부재. |
| AT-3 코드 난독화 | **FAIL** | Med | app.json에 `jsEngine: "hermes"` 미선언(mobile/app.json 2~53) — RN 0.74 기본 Hermes지만 명시·R8 설정 없음. `expo-build-properties`(R8/ProGuard) 미설치. |
| AT-4 디버거/에뮬레이터 | **FAIL** | Med | Frida/디버거/에뮬레이터 탐지 없음. |
| AT-5 디버그 비활성 | **부분 PASS** | Low | eas.json production=`app-bundle`(비디버그 기본, eas.json 18~22). 단 `android:debuggable=false` 명시·`__DEV__` 스트립 확인 필요. |
| AT-6 개발자모드/USB | **FAIL** | Med | 개발자옵션·USB 디버깅 감지 없음. |
## 2. 데이터 보호
| ID | 판정 | 위험도 | 증거 / 근거 |
|----|------|--------|-------------|
| DP-1 토큰 안전저장 | **PASS** | — | JWT를 expo-secure-store(Keychain/Keystore)에 저장(mobile/lib/secureStore.ts 10~25, mobile/context/AuthContext.tsx 62~66). web만 AsyncStorage 폴백(비네이티브). |
| DP-2 하드코딩 비밀 0 | **PASS** | — | 시크릿/키/토큰 grep 0건(mobile 전체). config.ts는 base URL만(공개, mobile/lib/config.ts 10~11). |
| DP-3 비밀번호 미저장 | **PASS** | — | 비밀번호는 요청 body로만 전송, 저장 로직 없음(mobile/lib/auth.ts 26~33, login.tsx 주석 4). |
| DP-4 화면캡처/오버레이 | **FAIL** | Med | 2FA/티켓QR 등 민감화면에 FLAG_SECURE 미적용(grep 0건). `expo-screen-capture` 미설치. |
| DP-5 백그라운드 스냅샷 | **FAIL** | Med | 앱 전환 시 민감화면 마스킹 로직 없음. |
| DP-6 클립보드 보호 | **PASS(경미)** | Low | 클립보드 강제복사 코드 없음. 티켓/개인정보 필드 클립보드 제어는 별도 검토 권장. |
| DP-7 로그 민감정보 0 | **PASS** | — | `console.log/warn/error` grep 0건(mobile 전체). 토큰·비밀번호 로깅 없음. |
## 3. 통신 보안
| ID | 판정 | 위험도 | 증거 / 근거 |
|----|------|--------|-------------|
| NW-1 TLS 강제 | **부분 PASS** | Med | base URL `https://kintex.zioinfo.co.kr`(mobile/app.json 45, config.ts 11). cleartext `http://` grep 0건. 단 Android `usesCleartextTraffic=false`·networkSecurityConfig 미선언(기본 SDK34 false지만 명시 권장). |
| NW-2 인증서 검증 | **PASS** | — | 표준 fetch(트러스트스토어 검증), 검증 우회 코드 없음(mobile/lib/api.ts 56~61). |
| NW-3 인증서 피닝 | **FAIL** | Med | 인증서/공개키 피닝 미적용. 공공 대민 앱 권고사항. |
| NW-4 API 키 미노출 | **PASS** | — | 통신에 클라이언트 API 키 없음. Authorization은 런타임 발급 JWT만(mobile/lib/api.ts 52). |
## 4. 인증·세션
| ID | 판정 | 위험도 | 증거 / 근거 |
|----|------|--------|-------------|
| AU-1 2FA(TOTP) | **PASS** | — | OTP_REQUIRED→재제출 흐름(mobile/lib/auth.ts 26~38, login.tsx 62~84). 서버 TotpService(HS 라이브러리 codeVerifier, backend security/TotpService.java 46~57). |
| AU-2 생체·로컬잠금 | **FAIL** | Med | `expo-local-authentication` 미설치, 로컬 재잠금 없음(진행 중 내정보 트랙과 연계). |
| AU-3 세션 만료·재발급 | **PASS** | — | 401 시 메모리 토큰 정리·재로그인 유도(mobile/lib/api.ts 67~70). 서버 TTL env(backend application.yml 67, JwtService 만료 66). |
| AU-4 로그인 실패 잠금 | **PASS** | — | 임계 초과 시 locked_until 설정, 계정열거 방지 일반화 메시지(backend security/LoginAttemptService.java 34~57). 클라 ACCOUNT_LOCKED 처리(login.tsx 74~75). |
| AU-5 서버측 RBAC | **PASS** | — | 행사 단위 RBAC를 JWT roles 클레임+컨트롤러 가드로 서버 강제(backend JwtService.java 47~69, SecurityConfig.java 48). |
## 5. 시큐어 코딩
| ID | 판정 | 위험도 | 증거 / 근거 |
|----|------|--------|-------------|
| SC-1 입력검증 | **PASS** | — | 클라 검증(login.tsx 53~60, register.tsx 27~30) + 서버 @Valid(GlobalExceptionHandler MethodArgumentNotValid 39~47). |
| SC-2 SQLi 방지 | **PASS** | — | MyBatis 동적 `${}`는 NlQueryReadMapper.xml `${sql}` 단 1곳, 결정론적 화이트리스트 가드 통과분만 실행(backend NlQuerySqlGuard.java: 단일SELECT·테이블 화이트리스트·주석/다중문/PII/LIMIT 검증 56~130). 그 외 전부 `#{}` 바인딩. |
| SC-3 안전한 난수 | **PASS** | — | OTP IV SecureRandom(backend SecretCipher.java 31,44), OTP secret은 totp SecretGenerator(CSPRNG), 웹훅 HmacSHA256. |
| SC-4 웹뷰 안전설정 | **N-A→PASS** | — | WebView 미사용(mobile grep 0건). 공격면 없음. |
| SC-5 딥링크 검증 | **부분 PASS** | Low | scheme `kintex`(app.json 6). expo-router 라우팅. 딥링크 파라미터 명시 검증 로직 추가 권장(현재 인증가드로 보호). |
| SC-6 스택트레이스 미노출 | **PASS** | — | 서버 include-stacktrace/message: never(application.yml 13~14), GlobalExceptionHandler 요약만 반환·스택 미저장(51~62), 401 봉투(SecurityConfig 49~57). 클라 요약 메시지만 노출(api.ts 82~89). |
| SC-7 암호화 저장 | **PASS** | — | OTP secret AES-256-GCM 봉인(backend SecretCipher.java seal/open 39~77, `enc:v1:` 포맷). |
## 6. 빌드·배포
| ID | 판정 | 위험도 | 증거 / 근거 |
|----|------|--------|-------------|
| BD-1 릴리스 로그/소스맵 | **PASS(경미)** | Low | console 로그 0건. 소스맵 배포 제외·`__DEV__` 스트립은 빌드시 확인 권장. |
| BD-2 최소 권한 | **부분 PASS** | Med | app.json에 명시 권한 선언 없음(기본 Expo 권한만). expo-image-picker 사용(package.json 19) → 카메라/사진 권한 발생. `blockedPermissions`로 불필요 권한 제거 권장. |
| BD-3 서드파티 취약점 | **미검증** | Med | `npm audit` 미실행(감사 범위상 코드 실행 배제). 의존성 버전은 SDK51 정렬 최신(package.json). CI에 audit 게이트 권장. |
| BD-4 서버 오류응답 | **PASS** | — | IP/SSH/비밀번호/스택트레이스 응답 미노출(GlobalExceptionHandler, ServerOut 스키마 규칙 준수). error_log 요약 1줄만(51~59). |
| BD-5 CORS/헤더 | **부분 PASS** | Med | `.cors(cors -> {})`에 CorsConfigurationSource 빈 미정의(backend SecurityConfig.java 35) → 명시 허용출처 없음(와일드카드 `*`도 없음). 운영 도메인 명시 권장. |
| BD-6 시크릿 주입 | **PASS(주의)** | Med | JWT_SECRET·KINTEX_OTP_ENC_KEY·DB/SMTP/ADMIN 비번 전부 env 주입(application.yml 27,43,66,76,83). **주의**: JWT_SECRET 개발 폴백 `CHANGE_ME_DEV_ONLY...`(66), OTP 키 미주입 시 개발 파생키 경고(SecretCipher 88) → **운영 env 주입 필수**. GEMINI_API_KEY는 워커 전용, 백엔드 미사용(9). |
---
## 추가 관찰(비차단, 운영 하드닝)
- **로그 레벨**: `logging.level.com.zioinfo.kintex: DEBUG`(application.yml 106) — 운영 프로파일에서 INFO로 하향 권장(민감 파라미터 verbose 노출 위험).
- **JWT 저장 위치**: 웹 타깃만 AsyncStorage 폴백(secureStore.ts 10) — 관람객 B2C 웹뷰/PWA 배포 시 XSS 토큰 탈취면 존재. 네이티브 앱은 무관.
- **웹훅 인증**: `/api/webhooks/in/**` permitAll이나 토큰+HMAC-SHA256 이중검증·상수시간 비교(WebhookSignature.java `MessageDigest.isEqual` 58) — 양호.
---
## 개선 백로그 (FAIL/취약 → 구현 작업 전환)
> 담당: 위변조·SecureStore·화면보호·network config = **kintex-mobile-dev** / 백엔드 = **kintex-backend-dev** / EAS·빌드설정 = **kintex-devops-dev**
> 코드 편집은 각 담당 에이전트가 수행(본 QA는 문서·감사만). SDK51 호환 주의 병기.
### P0 (High · 공공 대민 필수)
| # | 항목 | 담당 | 권장 구현 | SDK51 주의 |
|---|------|------|-----------|-----------|
| B1 | AT-1 루트/탈옥 탐지 | mobile-dev | `jail-monkey`(isJailBroken/canMockLocation) 또는 `freerasp-react-native` 도입 → 루팅 단말 경고·민감기능 제한. config plugin으로 prebuild 반영 | jail-monkey는 config plugin 필요(bare/prebuild). Expo 관리형은 `expo prebuild` 또는 dev-client 필요 — devops와 협의 |
| B2 | AT-2 앱 무결성 검증 | mobile-dev + backend-dev | Android **Play Integrity API**·iOS **App Attest** 토큰을 로그인/민감 API에 첨부 → backend에서 검증. 서명 지문 확인 | Expo 관리형은 네이티브 모듈 → dev-client/prebuild. 서버 검증 엔드포인트 신설 |
| B3 | AT-3 난독화 선언 | devops-dev | app.json `android.jsEngine:"hermes"`(또는 최상위) 명시 + `expo-build-properties`로 `android.enableProguardInReleaseBuilds:true`·`enableShrinkResources:true` | expo-build-properties 플러그인 추가·prebuild 필요. Hermes는 RN0.74 기본이나 명시로 회귀 방지 |
| B4 | DP-4 화면캡처 방지 | mobile-dev | `expo-screen-capture` `preventScreenCaptureAsync()`를 2FA·티켓QR·개인정보 화면 focus 시 적용 | expo-screen-capture SDK51 호환. iOS는 캡처 감지만·Android는 FLAG_SECURE 차단 |
### P1 (Med)
| # | 항목 | 담당 | 권장 구현 | SDK51 주의 |
|---|------|------|-----------|-----------|
| B5 | NW-1 cleartext 차단 명시 | devops-dev | `expo-build-properties`로 `android.usesCleartextTraffic:false` 명시 + iOS ATS 유지 확인 | prebuild 반영 |
| B6 | NW-3 인증서 피닝 | mobile-dev + devops-dev | `react-native-ssl-pinning` 또는 build-properties networkSecurityConfig `pin-set`(SPKI 해시). 백엔드 인증서 갱신 로테이션 절차 병행 | 피닝 만료/로테이션 운영 리스크 — 백업 핀 2개 이상 |
| B7 | DP-5 백그라운드 마스킹 | mobile-dev | AppState 'inactive/background' 시 오버레이 블러/스플래시 표시(민감 화면) | RN AppState + 조건부 렌더 |
| B8 | AU-2 생체 로컬잠금 | mobile-dev | `expo-local-authentication`으로 앱 재진입·민감작업 시 생체 재인증(내정보 트랙과 통합) | SDK51 호환. 폴백(PIN) 설계 |
| B9 | AT-4/AT-6 디버거·개발자모드 탐지 | mobile-dev | freerasp의 debugger/emulator/hooking 탐지 콜백 활용(B1과 통합) | B1과 동일 도입 경로 |
| B10 | BD-2 권한 최소화 | devops-dev | app.json `android.permissions` 명시 + `blockedPermissions`로 불필요 권한 제거. image-picker 권한 문자열(카메라/사진) 최소화 | image-picker는 권한 필요 — 사용처만 요청 |
| B11 | BD-5 CORS 명시 | backend-dev | `CorsConfigurationSource` 빈으로 운영 도메인(`kintex.zioinfo.co.kr`·`kintex.wise.ai.kr`)만 allowedOrigins 명시, 와일드카드 금지 | Spring Security 6 lambda DSL |
| B12 | BD-6 운영 시크릿 강제 | devops-dev + backend-dev | 운영 배포 시 JWT_SECRET·KINTEX_OTP_ENC_KEY env 주입 검증(부재 시 기동 실패 fail-fast 검토), DEBUG 로그 INFO 하향 | 개발 폴백 값 운영 유입 차단 |
| B13 | BD-3 의존성 CVE | devops-dev | CI에 `npm audit --audit-level=high`(mobile) + gradle 의존성 스캔 게이트 추가 | 정기 스캔 |
### P2 (Low · 하드닝)
| # | 항목 | 담당 | 권장 구현 |
|---|------|------|-----------|
| B14 | AT-5 debuggable 검증 | devops-dev | 릴리스 빌드 `android:debuggable=false`·소스맵 미배포·`__DEV__` 스트립 CI 검증 |
| B15 | SC-5 딥링크 검증 | mobile-dev | `kintex://` 딥링크 진입 파라미터 스키마 검증·화이트리스트 라우팅 |
| B16 | DP-6 클립보드 정책 | mobile-dev | 티켓QR·개인정보 필드 `contextMenuHidden`·민감 복사 자동클리어 |
---
## 재검증 게이트(구현 후)
1. `mobile/`: jail-monkey/freerasp 도입·screen-capture 적용·build-properties(hermes/R8/cleartext) 반영 → 본 문서 AT-*/DP-4/NW-1 재판정.
2. `backend`: CorsConfigurationSource 빈·운영 로그레벨·시크릿 fail-fast → BD-5/6 재판정.
3. 빌드 회귀: `mobile tsc --noEmit` EXIT 0, `./gradlew build` 통과 확인.

85
plugins/zio-harness/knowledge/kintex/docs/security/mobile-security-checklist.md Normal file
View File

@ -0,0 +1,85 @@
# KINTEX AI 모바일 앱 + 백엔드 보안 체크리스트
> 대상: `mobile/`(Expo SDK 51 · expo-router · RN 0.74) + `src/backend`(Spring Boot 3.x · MyBatis · PostgreSQL)
> 기준 표준: **OWASP MASVS v2 / MSTG**, **행안부·KISA "모바일 대민 서비스 앱 소스코드 검증 가이드"**, **전자정부 모바일 표준보안 요구사항**
> 킨텍스는 공공 전시장(한국국제전시장) 대상 서비스 — 공공기관 대민 앱 기준을 함께 적용한다.
> 판정 결과는 `mobile-security-audit.md`, 개선 작업은 동 문서 하단 백로그 참조.
## 표준 매핑 표기
- MASVS-STORAGE / -CRYPTO / -AUTH / -NETWORK / -PLATFORM / -CODE / -RESILIENCE
- KISA: 대민 앱 검증 가이드 항목군(위변조·데이터보호·통신·인증·시큐어코딩·서버)
---
## 1. 앱 위변조 방지 (Anti-Tampering) — MASVS-RESILIENCE / KISA 위변조
| ID | 항목 | 기준 | 근거 표준 |
|----|------|------|-----------|
| AT-1 | 루트/탈옥 탐지 | 루팅(Android)·탈옥(iOS) 단말에서 실행 시 경고·기능 제한·차단 | MASVS-RESILIENCE-1, KISA 위변조-1 |
| AT-2 | 앱 서명/무결성 검증 | 서명 인증서 지문 확인, 리패키징(재서명) 탐지, Play Integrity/App Attest 검토 | MASVS-RESILIENCE-2, KISA 위변조-2 |
| AT-3 | 코드 난독화 | JS 번들 Hermes 바이트코드 컴파일, 네이티브 R8/ProGuard 난독화·최적화 활성 | MASVS-RESILIENCE-3 |
| AT-4 | 디버거/후킹 탐지 | 디버거 attach·Frida/Xposed 후킹·에뮬레이터 실행 탐지 | MASVS-RESILIENCE-4 |
| AT-5 | 디버그 비활성 | 릴리스 빌드 `android:debuggable=false`, JS `__DEV__` 코드 제거 | MASVS-RESILIENCE, KISA 위변조-3 |
| AT-6 | 개발자모드/USB 디버깅 대응 | 민감 작업 시 개발자옵션·USB 디버깅 활성 감지·경고 | KISA 위변조-4 |
## 2. 데이터 보호 (Data at Rest) — MASVS-STORAGE / KISA 데이터보호
| ID | 항목 | 기준 | 근거 표준 |
|----|------|------|-----------|
| DP-1 | 토큰 안전저장 | JWT·세션 토큰은 Keychain(iOS)/Keystore(Android) = expo-secure-store, 평문 AsyncStorage 금지 | MASVS-STORAGE-1, KISA 데이터-1 |
| DP-2 | 하드코딩 비밀 0 | 소스·설정에 API 키·비밀번호·토큰 하드코딩 없음(grep 0건) | MASVS-STORAGE-2, KISA 데이터-2 |
| DP-3 | 비밀번호 미저장 | 로그인 비밀번호를 단말에 어떤 형태로도 저장하지 않음 | MASVS-STORAGE-1 |
| DP-4 | 화면캡처/오버레이 방지 | 민감 화면(2FA·티켓QR·개인정보) FLAG_SECURE로 캡처·녹화·오버레이 차단 | MASVS-PLATFORM-3, KISA 데이터-4 |
| DP-5 | 백그라운드 스냅샷 | 앱 전환 시 민감 화면 마스킹(태스크 스위처 스냅샷 노출 방지) | MASVS-STORAGE-7 |
| DP-6 | 클립보드 보호 | 비밀번호·토큰·개인정보 필드 클립보드 복사 최소화·자동삭제 | MASVS-STORAGE-8 |
| DP-7 | 로그 내 민감정보 0 | 토큰·비밀번호·개인정보를 로그(console/logcat)에 남기지 않음 | MASVS-STORAGE-3, KISA 데이터-3 |
## 3. 통신 보안 (Data in Transit) — MASVS-NETWORK / KISA 통신
| ID | 항목 | 기준 | 근거 표준 |
|----|------|------|-----------|
| NW-1 | TLS 강제 | 모든 API가 HTTPS. 평문 HTTP(cleartext) 차단 — Android networkSecurityConfig(`cleartextTrafficPermitted=false`), iOS ATS 유지 | MASVS-NETWORK-1, KISA 통신-1 |
| NW-2 | 인증서 검증 | 서버 인증서·호스트명 검증(기본 트러스트스토어). 검증 우회 코드 없음 | MASVS-NETWORK-2 |
| NW-3 | 인증서 피닝 | 공공/민감 앱 권고 — 서버 인증서·공개키 피닝 검토·적용 | MASVS-NETWORK-4, KISA 통신-2 |
| NW-4 | API 키 미노출 | 통신에 클라이언트 하드코딩 API 키 사용 안 함(base URL만 공개) | MASVS-STORAGE-2 |
## 4. 인증·세션 — MASVS-AUTH / KISA 인증
| ID | 항목 | 기준 | 근거 표준 |
|----|------|------|-----------|
| AU-1 | 2차 인증(2FA) | TOTP 기반 OTP 로그인 흐름(OTP_REQUIRED→재제출) 지원 | MASVS-AUTH-1, KISA 인증-1 |
| AU-2 | 생체·로컬 잠금 | 앱 로컬 생체(Face/Touch/지문) 재잠금 옵션(민감 진입) | MASVS-AUTH-2 |
| AU-3 | 세션 만료·재발급 | 액세스 토큰 TTL, 만료 시 401 처리·재로그인 유도 | MASVS-AUTH-3 |
| AU-4 | 로그인 실패 잠금 | 연속 실패 임계 초과 시 계정 잠금(서버), 계정 열거 방지 일반화 메시지 | MASVS-AUTH-6, KISA 인증-2 |
| AU-5 | 서버측 권한검증 | 행사 단위 RBAC를 서버에서 강제(클라이언트 신뢰 금지) | MASVS-AUTH-4 |
## 5. 시큐어 코딩 — MASVS-CODE / KISA 시큐어코딩
| ID | 항목 | 기준 | 근거 표준 |
|----|------|------|-----------|
| SC-1 | 입력검증 | 클라이언트·서버 이중 입력검증(이메일·비밀번호 길이·형식) | MASVS-CODE-4, KISA SC-1 |
| SC-2 | SQL 인젝션 방지 | MyBatis 파라미터 바인딩(`#{}`), 동적 `${}` 미사용 또는 화이트리스트 가드 | KISA SC-2 |
| SC-3 | 안전한 난수 | 토큰·OTP·IV 생성에 CSPRNG(SecureRandom) 사용 | MASVS-CRYPTO-3 |
| SC-4 | 웹뷰 안전설정 | (있으면) JS브리지 최소화·파일접근 차단·신뢰 URL만 로드 | MASVS-PLATFORM-2 |
| SC-5 | 딥링크 검증 | 커스텀 스킴(`kintex://`) 파라미터 검증, 미검증 라우팅 금지 | MASVS-PLATFORM-1 |
| SC-6 | 예외/스택트레이스 미노출 | 서버·클라이언트 모두 스택트레이스·내부 세부 미노출, 요약 메시지만 | MASVS-CODE-5, KISA 서버-4 |
| SC-7 | 암호화 저장 | 민감 시크릿(OTP secret 등) AES-256-GCM 저장 | MASVS-CRYPTO-1 |
## 6. 빌드·배포 — MASVS-RESILIENCE / KISA 서버·배포
| ID | 항목 | 기준 | 근거 표준 |
|----|------|------|-----------|
| BD-1 | 릴리스 로그/소스맵 | 릴리스 빌드에 디버그 로그·소스맵 미포함 | MASVS-RESILIENCE-3 |
| BD-2 | 최소 권한 | app.json 권한 최소화, 불필요 권한 제거(blockedPermissions) | MASVS-PLATFORM-1, KISA 서버-1 |
| BD-3 | 서드파티 취약점 | package.json 의존성 CVE 스캔(npm audit), 최신 유지 | MASVS-CODE-3 |
| BD-4 | 서버 오류응답 | 백엔드 오류 응답에 IP·SSH·비밀번호·스택트레이스 미노출 | KISA 서버-3·4 |
| BD-5 | CORS/헤더 | CORS 허용출처 명시(와일드카드 금지), 보안 헤더 | KISA 서버-2 |
| BD-6 | 시크릿 주입 | JWT_SECRET·암호화 키·DB/SMTP 비번은 env 주입, 코드/커밋 미포함 | MASVS-STORAGE-2 |
---
## 판정 기호
- **PASS** — 기준 충족(증거 있음)
- **FAIL** — 기준 미충족(구현 필요)
- **N-A** — 현재 미적용 대상(해당 기능 부재)
- 위험도: **High**(공공/민감 필수) · **Med** · **Low**

66
plugins/zio-harness/knowledge/kintex/mobile/README.md Normal file
View File

@ -0,0 +1,66 @@
# KINTEX AI 전시관리 — 모바일 앱 (mobile/)
React Native + Expo(expo-router, TypeScript) 모바일 앱. 조회·승인·현장 시나리오 전용
(design.md §4). 백엔드는 공유 API `https://kintex.zioinfo.co.kr`.
## 스택
- Expo SDK 51 · expo-router ~3.5 · React Native 0.74 · TypeScript
- JWT는 `expo-secure-store`(네이티브 keychain/keystore)에 저장, 웹은 AsyncStorage 폴백
- 디자인 토큰: `theme/`(docs/design.md §1 팔레트·타이포). 신규 토큰 없음.
- 다국어: `react-i18next` + `expo-localization`(SDK51 호환). 지원 ko(기본/폴백)·en·zh·ja.
## 다국어(i18n)
- 초기화 `lib/i18n/`(동기 init — 디바이스 로케일 감지, 저장 선택은 부팅 시 반영). 리소스 `lib/i18n/locales/{ko,en,zh,ja}.ts`.
- **ko가 키 형상의 단일 출처** — en/zh/ja는 `Translations`(DeepString) 타입 구현이라 키 누락 시 tsc가 잡음(병렬 편집 함정 회피: 직렬·키 대조).
- 언어 선택 지속: AsyncStorage 키 `kintex_lang`. 전환 UI `components/LanguageSelector.tsx`(더보기·내정보에 배치), 상태 `context/LanguageContext.tsx`.
- 커버 화면(우선순위): 로그인/2FA·회원가입·비번찾기·홈·현장·갤러리·더보기·내정보·티켓 지갑·탭/스택 타이틀·역할 라벨. 미커버(폴백=현행 한국어): `checklist`·`inspection`·`tickets/select`·티켓 카드/필터탭 컴포넌트(`components/tickets/*`).
## 역할별 랜딩
- `lib/roleTrack.ts` — 웹 `src/frontend/src/lib/roleTrack.ts` 패리티(우선순위 admin>ops>business>agency>visitor, 미판정=visitor 기본).
- 로그인 응답 user에 roleCode가 없어 `hallManager`를 ops 신호로 사용(roleCode 아는 호출부는 옵션 전달).
- 모바일 랜딩 매핑: admin/ops/business→`/(tabs)` 홈 · agency(장치·시공)→`/(tabs)/field` · visitor(관람객)→`/tickets`.
- 콜드 부팅 시 workspaces 미복원 misroute 방지 위해 로그인 시 계산한 랜딩 경로를 secure-store에 지속(`AuthContext`).
## 실행
```bash
cd mobile
npm install
npm run typecheck # tsc --noEmit
npm start # Expo 개발 서버 (Expo Go / 에뮬레이터)
```
API 베이스는 `app.json > extra.apiBase` 또는 `EXPO_PUBLIC_API_BASE` 환경변수로 재정의.
시크릿(키 등)은 하드코딩하지 않는다.
## 화면
| 경로 | 화면 | 근거 |
|---|---|---|
| `app/login.tsx` | 로그인(2FA/OTP·아이디 기억·비번찾기/회원가입) | SCR-01 |
| `app/register.tsx` | 회원가입 | 04_backend_public_auth §1 |
| `app/forgot-password.tsx` | 비밀번호 찾기/초기화 | 04 §2·§3 |
| `app/(tabs)/index.tsx` | 홈/대시보드(역할별 진입) | design §2-2 |
| `app/(tabs)/field.tsx` | 현장 허브(역할 분기) | — |
| `app/(tabs)/gallery.tsx` | 시각화 갤러리(워터마크 상시) | SCR-12 |
| `app/(tabs)/more.tsx` | 계정(내정보 진입)·서버 상태·로그아웃 | — |
| `app/profile.tsx` | 내정보(WISE mypage 이식·생체인식 잠금·프로필 사진 등록) | WISE `uiws/mypage.tsx` |
| `app/checklist.tsx` | 현장 체크리스트(48px 터치·오프라인·사진) | SCR-M1 |
| `app/inspection.tsx` | 현장 검수(승인/반려·AI 플래그) | SCR-M2 |
## 계약·보안 준수
- 응답 오류 봉투 `{ success, data, error }` 처리(`lib/api.ts`), degraded 폴백(`isDegraded`).
- AI 생성 이미지는 `components/AiImage.tsx`가 워터마크 + "AI 생성 예상 이미지" 고지를 **항상** 표시(제거 불가).
- 비밀번호는 저장하지 않음. "아이디 기억"은 이메일만 AsyncStorage 보관.
## 보안 하드닝(위변조 방지 · 화면보호)
근거: `docs/security/mobile-security-audit.md`(B1~B13) · 상세: `_workspace/08_mobile_security_hardening.md`. 모두 방어적(네이티브 미지원 기기 graceful).
- **위변조 탐지(B1/B9)**: `lib/integrity.ts`(jail-monkey) — 루팅·후킹·디버거·개발자모드·USB 디버깅 탐지. 로그인 시 비차단 경고(공공 대민 정책).
- **화면캡처 방지(B4)+백그라운드 마스킹(B7)**: `context/SecureScreenContext.tsx`의 `useSecureScreen(key)` — 2FA 로그인·티켓 QR·내정보에서 캡처 차단(FLAG_SECURE)+태스크 스위처 마스킹.
- **난독화(B3)·cleartext 차단(B5)·권한 최소화(B10)**: `app.json`(Hermes·expo-build-properties R8/ProGuard·usesCleartextTraffic:false·iOS ATS·android.permissions/blockedPermissions).
- **앱 무결성 토큰(B2 전송부)**: `lib/api.ts`가 `X-Integrity-Token` 조건부 첨부(발급기 등록 시). 서버 검증은 backend-dev 인계.
- **한계**: 인증서 피닝(B6)은 회귀 위험으로 미도입 — 커스텀 config plugin 경로 문서화(`_workspace/08`). EAS 실빌드는 devops·G3 게이트.
## 남은 작업
- 실 화면 데이터 API 배선 확대(부스 목록·검수 요청 제출 — 백엔드 M6/C-4 확장 대기).
- 앱 아이콘/스플래시 에셋(`assets/`), 푸시 알림.
- i18n 잔여 화면 키 추출: `checklist`·`inspection`·`tickets/select`·`components/tickets/*`(현재 한국어 폴백).
- EAS 실빌드(eas.json 프로파일) — G3 게이트(소유자 승인).

27
plugins/zio-harness/knowledge/kintex/src/frontend/README.md Normal file
View File

@ -0,0 +1,27 @@
# KINTEX AI 전시관리 — Frontend
React 18 + Vite 5 + TypeScript. 백엔드(Spring Boot :8080) 계약(`_workspace/01_backend_contracts.md`) 기반.
## 개발
```bash
npm install
npm run dev # Vite 개발 서버 :5173 (/api·/ws → :8080 프록시)
npm run typecheck # tsc -b (타입 체크)
npm run build # tsc -b && vite build
```
`.env.example` → `.env` 복사. `VITE_BACKEND_ORIGIN`으로 백엔드 오리진 지정(기본 `http://localhost:8080`).
## 구조
- `src/styles/tokens.css` — 디자인 토큰 **단일 출처**(design.md §1). 하드코딩 금지, 이 변수만 참조.
- `src/api/` — `client`(JWT·봉투·오류코드), `endpoints`(계약 래퍼), `types`(응답 shape), `websocket`(STOMP RenderJob).
- `src/store/authStore.ts` — 인증/워크스페이스 상태(zustand).
- `src/components/ui/` — StatusBadge·DdayChip·AiLabel·Button·AiImage(워터마크 상시)·States.
- `src/components/layout/AppShell.tsx` — 인증 셸(사이드바+상단바).
- `src/screens/login/` — SCR-01 로그인·워크스페이스·초대(등록업체 차단).
- `src/screens/floorplan/` — SCR-03 배치 에디터(SVG 캔버스·AI 자동배치·검증).
## 원칙
- 백엔드 응답 shape과 정확히 일치. 불일치는 `_workspace/02_frontend_progress.md`에 기록.
- AI 생성 이미지 워터마크·고지문 제거 불가. 접근성 WCAG AA.
- 캔버스 편집은 데스크톱 전용(모바일은 뷰어+승인).

182
plugins/zio-harness/knowledge/kintex/stitch_kintex_ai_system_architect/kintex_ai_intelligence_system/DESIGN.md Normal file
View File

@ -0,0 +1,182 @@
---
name: Kintex AI Intelligence System
colors:
surface: '#f9f9fc'
surface-dim: '#dadadc'
surface-bright: '#f9f9fc'
surface-container-lowest: '#ffffff'
surface-container-low: '#f3f3f6'
surface-container: '#eeeef0'
surface-container-high: '#e8e8ea'
surface-container-highest: '#e2e2e5'
on-surface: '#1a1c1e'
on-surface-variant: '#424751'
inverse-surface: '#2f3133'
inverse-on-surface: '#f0f0f3'
outline: '#727782'
outline-variant: '#c2c6d3'
surface-tint: '#115fac'
primary: '#00427d'
on-primary: '#ffffff'
primary-container: '#0059a6'
on-primary-container: '#b6d1ff'
inverse-primary: '#a6c8ff'
secondary: '#5427e6'
on-secondary: '#ffffff'
secondary-container: '#6d4aff'
on-secondary-container: '#f3edff'
tertiary: '#004950'
on-tertiary: '#ffffff'
tertiary-container: '#00636b'
on-tertiary-container: '#65e2ef'
error: '#ba1a1a'
on-error: '#ffffff'
error-container: '#ffdad6'
on-error-container: '#93000a'
primary-fixed: '#d5e3ff'
primary-fixed-dim: '#a6c8ff'
on-primary-fixed: '#001c3b'
on-primary-fixed-variant: '#004786'
secondary-fixed: '#e5deff'
secondary-fixed-dim: '#c9bfff'
on-secondary-fixed: '#1b0063'
on-secondary-fixed-variant: '#4500d8'
tertiary-fixed: '#87f3ff'
tertiary-fixed-dim: '#59d8e5'
on-tertiary-fixed: '#001f23'
on-tertiary-fixed-variant: '#004f55'
background: '#f9f9fc'
on-background: '#1a1c1e'
surface-variant: '#e2e2e5'
ai-surface: '#F5F3FF'
status-safe: '#2ECC71'
status-warning: '#F1C40F'
status-alert: '#E74C3C'
surface-muted: '#F8FAFC'
typography:
display-lg:
fontFamily: Hanken Grotesk
fontSize: 48px
fontWeight: '700'
lineHeight: '1.2'
letterSpacing: -0.02em
display-lg-mobile:
fontFamily: Hanken Grotesk
fontSize: 32px
fontWeight: '700'
lineHeight: '1.2'
headline-lg:
fontFamily: Hanken Grotesk
fontSize: 32px
fontWeight: '600'
lineHeight: '1.3'
headline-md:
fontFamily: Hanken Grotesk
fontSize: 24px
fontWeight: '600'
lineHeight: '1.4'
body-lg:
fontFamily: Hanken Grotesk
fontSize: 18px
fontWeight: '400'
lineHeight: '1.6'
body-md:
fontFamily: Hanken Grotesk
fontSize: 16px
fontWeight: '400'
lineHeight: '1.6'
body-sm:
fontFamily: Hanken Grotesk
fontSize: 14px
fontWeight: '400'
lineHeight: '1.5'
label-md:
fontFamily: Hanken Grotesk
fontSize: 14px
fontWeight: '600'
lineHeight: '1'
letterSpacing: 0.05em
code-sm:
fontFamily: Courier Prime
fontSize: 13px
fontWeight: '400'
lineHeight: '1.4'
rounded:
sm: 0.125rem
DEFAULT: 0.25rem
md: 0.375rem
lg: 0.5rem
xl: 0.75rem
full: 9999px
spacing:
unit: 4px
gutter: 24px
margin-mobile: 16px
margin-desktop: 48px
container-max: 1440px
---
## Brand & Style
The design system is engineered for the intersection of industrial facility management and advanced artificial intelligence. It adopts a **Corporate / Modern** aesthetic that prioritizes reliability, precision, and efficiency. The target audience includes exhibition managers, technical engineers, and corporate stakeholders who require high-density information delivery without cognitive overload.
The visual narrative balances the "stability" of traditional infrastructure management with the "intelligence" of AI integration. By utilizing a clean, structured layout with subtle technological accents, the UI evokes a sense of trustworthy authority and forward-thinking innovation. White space is used strategically to maintain clarity in complex data environments, ensuring that "human-centric" service remains at the forefront of "technology-driven" operations.
## Colors
The palette is anchored by **Corporate Blue (#0059A6)**, representing the established heritage of KINTEX and professional facility management. This is contrasted by **AI-Accent Purple (#6D4AFF)**, which is reserved exclusively for intelligent features, automated insights, and predictive maintenance indicators.
**Neutral tones** are predominantly cool grays to maintain a technical feel. Surface colors utilize a tiered approach: white for primary cards, and `surface-muted` for background grouping. The `ai-surface` is a very subtle purple tint used to highlight dashboard sections or components that are actively powered by AI, providing a clear visual cue for "smart" versus "manual" data.
## Typography
The typography system relies on **Hanken Grotesk** to provide a sharp, contemporary, and highly legible experience across both digital interfaces and technical reports. For Korean text, **Pretendard** is the designated fallback, ensuring consistent weights and optical balance.
Hierarchy is strictly enforced to manage high-density data. Headlines use a tighter letter-spacing to appear more cohesive and authoritative. Labels use all-caps and increased tracking for utility-based navigation and metadata tags. For logs and technical ID strings, a monospaced font is utilized to differentiate system data from user-readable content.
## Layout & Spacing
This design system employs a **Fixed Grid** model for desktop, centered within a 1440px container to ensure readability of data tables and management dashboards. A 12-column grid is standard, allowing for flexible layouts of 2, 3, 4, or 6 units.
For exhibition management tasks, a **High-Density** spacing rhythm is utilized (4px base unit).
- **Desktop:** 24px gutters with 48px page margins.
- **Tablet:** 16px gutters with 32px page margins.
- **Mobile:** 12px gutters with 16px page margins.
Content reflows from multi-column grids to single-column stacks on mobile, with secondary navigation moving to a bottom-tab bar or a simplified "hamburger" menu to maximize vertical screen real estate for data visualization.
## Elevation & Depth
Visual hierarchy is established through **Tonal Layers** and **Low-Contrast Outlines** rather than heavy shadows, maintaining a professional and clean "B2B dashboard" feel.
- **Level 0 (Surface):** The main background color.
- **Level 1 (Cards):** Raised using a 1px border (#E2E8F0) or a very soft, diffused shadow (0px 4px 12px, 4% opacity).
- **Level 2 (Active/Overlays):** Used for modals and dropdowns, featuring a slightly more pronounced shadow and a backdrop blur (8px) to separate the element from the dense data behind it.
AI-specific components may use a subtle purple outer-glow (tinted shadow) to indicate an active processing state or a high-confidence recommendation.
## Shapes
The shape language is **Soft**, utilizing small radii to maintain a disciplined, architectural feel.
- **Standard elements** (Buttons, Inputs, Cards): 0.25rem (4px).
- **Large containers** (Section blocks): 0.5rem (8px).
- **Interactive Tags/Chips:** May use a pill-shape for high-contrast status indicators, but structural components must remain geometric.
This minimal roundedness reflects the industrial nature of KINTEX while softening the edges for a modern software experience.
## Components
### Buttons
Primary buttons use the Corporate Blue. AI-action buttons use the Purple accent. Both feature a subtle 1px inset border on hover to provide tactile feedback. Text is always semi-bold Hanken Grotesk.
### Input Fields
Inputs utilize a 1px border-bottom as the primary visual marker in high-density forms, or a full 4px rounded box in standard layouts. The focus state uses a 2px Corporate Blue border.
### Cards
Cards are the primary container for data. They must feature a clear "Header" section with 16px padding, separated by a 1px divider from the "Content" area. AI-powered cards include a left-hand purple border accent (4px width).
### Chips & Status Indicators
Used for "Safe", "Warning", or "Alert" status. They are small, high-density elements with a background-tinted version of the status color and dark-text for accessibility.
### Data Lists
Lists must support high-density viewing. Row heights are kept at 40px for desktop with a subtle hover state (#F1F5F9) to help the user track information across horizontal planes.

36
plugins/zio-harness/knowledge/kintex/stitch_kintex_ai_system_architect/kintex_ai_system_proposal.md Normal file
View File

@ -0,0 +1,36 @@
# 킨텍스(KINTEX) AI 시스템 개발 기획안
## 1. 개요
본 기획안은 대한민국 최대 전시 컨벤션 센터인 킨텍스의 디지털 전환을 가속화하고, AI 기술을 통해 방문객 경험을 혁신하며 운영 효율성을 극대화하기 위한 'KINTEX AI Intelligence System' 구축을 제안합니다.
## 2. 핵심 목표
- **방문객 경험 혁신**: 개인화된 추천 및 실시간 안내 서비스 제공
- **운영 효율화**: 데이터 기반의 전시장 운영 및 혼잡도 관리
- **전시 마케팅 고도화**: 전시 주최자 및 참가 업체를 위한 맞춤형 매칭 및 분석 리포트 제공
## 3. 주요 AI 시스템 기능 제안
### A. 스마트 방문객 가이드 (AI Concierge)
- **개인화된 전시 일정 추천**: 방문객의 관심 분야 및 과거 방문 이력을 분석하여 맞춤형 전시 및 세션 추천
- **실시간 다국어 챗봇/보이스봇**: 위치 안내, 부대시설 정보, 주차 정보 등을 다국어로 실시간 응대
- **AR 기반 실내 내비게이션**: 대규모 전시장 내에서 목적지(부스, 편의시설)까지의 최적 경로 안내
### B. 지능형 전시장 관리 (Smart Hall Operations)
- **AI 혼잡도 분석 및 예측**: CCTV 데이터를 활용한 실시간 인파 밀집도 분석 및 위험 구역 사전 경고
- **에너지 최적화 시스템**: 전시장 내 인원 분포에 따른 조명 및 냉난방 자동 최적 제어
- **주차 수요 예측**: 실시간 주차 상황 데이터와 행사 일정을 연계하여 주차 공간 최적 배정 및 안내
### C. 비즈니스 매칭 및 데이터 분석 (Business Intelligence)
- **AI 비즈니스 매칭**: 전시 주최자와 잠재적 참가 업체, 혹은 참가 업체와 바이어 간의 최적 매칭 제안
- **성과 분석 리포트**: 부스별 방문자 수, 체류 시간, 유입 경로 등을 분석하여 참가 업체에 제공
- **전시회 트렌드 분석**: 글로벌 전시 트렌드 데이터를 분석하여 신규 기획 전시 테마 제안
## 4. 시스템 아키텍처 (Harness) 제안
- **Data Lake**: 웹사이트 로그, 현장 센서 데이터, 외부 트렌드 데이터를 통합 관리
- **AI Model Layer**: 자연어 처리(LLM), 컴퓨터 비전(CCTV 분석), 예측 모델(주차/에너지) 탑재
- **API Gateway**: 모바일 앱, 웹사이트, 키오스크 등 다양한 채널에 AI 기능 공급
## 5. 기대 효과
- 방문객 만족도 제고 및 체류 시간 증대
- 운영 비용 절감 및 인력 운용 효율화
- 전시 데이터 자산화를 통한 새로운 비즈니스 모델 창출

181
plugins/zio-harness/knowledge/kintex/stitch_kintex_ai_system_architect/kintex_nexus/DESIGN.md Normal file
View File

@ -0,0 +1,181 @@
---
name: Kintex Nexus
colors:
surface: '#f8f9fa'
surface-dim: '#d9dadb'
surface-bright: '#f8f9fa'
surface-container-lowest: '#ffffff'
surface-container-low: '#f3f4f5'
surface-container: '#edeeef'
surface-container-high: '#e7e8e9'
surface-container-highest: '#e1e3e4'
on-surface: '#191c1d'
on-surface-variant: '#424751'
inverse-surface: '#2e3132'
inverse-on-surface: '#f0f1f2'
outline: '#727782'
outline-variant: '#c2c6d3'
surface-tint: '#115fac'
primary: '#00427d'
on-primary: '#ffffff'
primary-container: '#0059a6'
on-primary-container: '#b6d1ff'
inverse-primary: '#a6c8ff'
secondary: '#39608d'
on-secondary: '#ffffff'
secondary-container: '#a6ccff'
on-secondary-container: '#2e5682'
tertiary: '#8a0002'
on-tertiary: '#ffffff'
tertiary-container: '#b60004'
on-tertiary-container: '#ffc1b8'
error: '#ba1a1a'
on-error: '#ffffff'
error-container: '#ffdad6'
on-error-container: '#93000a'
primary-fixed: '#d5e3ff'
primary-fixed-dim: '#a6c8ff'
on-primary-fixed: '#001c3b'
on-primary-fixed-variant: '#004786'
secondary-fixed: '#d2e4ff'
secondary-fixed-dim: '#a3c9fc'
on-secondary-fixed: '#001c37'
on-secondary-fixed-variant: '#1e4974'
tertiary-fixed: '#ffdad5'
tertiary-fixed-dim: '#ffb4a9'
on-tertiary-fixed: '#410000'
on-tertiary-fixed-variant: '#930002'
background: '#f8f9fa'
on-background: '#191c1d'
surface-variant: '#e1e3e4'
surface-border: '#E5E7EB'
status-active: '#10B981'
status-pending: '#F59E0B'
table-header: '#F1F5F9'
typography:
headline-lg:
fontFamily: Hanken Grotesk
fontSize: 30px
fontWeight: '700'
lineHeight: 38px
letterSpacing: -0.02em
headline-lg-mobile:
fontFamily: Hanken Grotesk
fontSize: 24px
fontWeight: '700'
lineHeight: 32px
headline-md:
fontFamily: Hanken Grotesk
fontSize: 20px
fontWeight: '600'
lineHeight: 28px
body-lg:
fontFamily: Hanken Grotesk
fontSize: 16px
fontWeight: '400'
lineHeight: 24px
body-md:
fontFamily: Hanken Grotesk
fontSize: 14px
fontWeight: '400'
lineHeight: 20px
body-sm:
fontFamily: Hanken Grotesk
fontSize: 13px
fontWeight: '400'
lineHeight: 18px
label-md:
fontFamily: Hanken Grotesk
fontSize: 12px
fontWeight: '600'
lineHeight: 16px
letterSpacing: 0.05em
mono-data:
fontFamily: jetbrainsMono
fontSize: 13px
fontWeight: '400'
lineHeight: 18px
rounded:
sm: 0.125rem
DEFAULT: 0.25rem
md: 0.375rem
lg: 0.5rem
xl: 0.75rem
full: 9999px
spacing:
container-max: 1440px
margin-desktop: 32px
margin-mobile: 16px
gutter: 24px
stack-sm: 8px
stack-md: 16px
stack-lg: 24px
---
## Brand & Style
The design system is engineered for the high-density requirements of exhibition management and administrative oversight. It targets professional operators and event organizers who require a high degree of "information scent" and clarity.
The aesthetic follows a **Corporate / Modern** movement, prioritizing structural integrity and functional density over decorative flourishes. It utilizes a balanced combination of high-density data visualization and clear, hierarchical navigation. The UI evokes a sense of reliability and institutional authority, reflecting the physical scale of the KINTEX venue. The layout is systematic, utilizing a clean "dashboard-first" philosophy where every pixel serves a purpose in decision-making and logistics management.
## Colors
The palette is anchored by **Corporate Blue (#0059A6)**, representing the established brand identity and used for primary actions, navigation headers, and brand-critical elements. A **Secondary Blue (#6389B8)** acts as a supportive hue for data visualization and secondary interactive states, bridging the gap between brand identity and UI utility.
**Tertiary Red (#E32219)** is reserved strictly for high-urgency alerts, error states, and critical "Delete" or "Cancel" actions to ensure it maintains its semantic impact. The neutral foundation relies on **Light Gray (#F8F9FA)** for background surfaces to reduce eye strain during long working sessions, with darker grays used for structural borders and high-contrast text.
## Typography
This design system uses **Hanken Grotesk** for its exceptional legibility in dense administrative interfaces. It provides a sharp, contemporary feel that aligns with the "Pretendard" aesthetic requested while offering superior geometric balance for international stakeholders.
- **Headlines:** Use Bold weights for section titles to establish a strong visual anchor.
- **Body:** Standard body text is set at 14px (md) to maximize information density without compromising readability.
- **Data Sets:** For numerical values, ID strings, or technical logs within tables, the **JetBrains Mono** font (mono-data) is recommended to ensure clear distinction between characters and aligned columns.
- **Labels:** Small, uppercase labels with increased letter spacing are used for table headers and category tags to differentiate them from interactive content.
## Layout & Spacing
The layout utilizes a **Fixed-Fluid Hybrid Grid**. The main sidebar navigation is fixed (240px), while the content area expands to a maximum of 1440px to ensure data tables don't become excessively wide and difficult to scan horizontally.
A **base-8 spacing system** is strictly enforced to maintain rhythmic consistency.
- **Desktop:** 12-column grid with 24px gutters.
- **Tablet:** 8-column grid with 20px gutters.
- **Mobile:** 4-column grid with 16px margins.
Content should reflow into single-column stacks on mobile devices. For complex data tables, horizontal scrolling is the preferred pattern over hidden columns to ensure all administrative data remains accessible.
## Elevation & Depth
To maintain a "Professional & Functional" aesthetic, this design system avoids heavy shadows. Depth is primarily conveyed through **Tonal Layers** and **Low-Contrast Outlines**.
- **Level 0 (Base):** Light Gray background (#F8F9FA).
- **Level 1 (Cards/Containers):** White background with a 1px border (#E5E7EB). No shadow.
- **Level 2 (Modals/Dropdowns):** White background with a subtle, tight ambient shadow (Blur 8px, Y 4px, Opacity 5%) to indicate temporary interaction layers.
- **Interactive Elements:** Buttons and inputs use a flat design with a 1px solid stroke. Primary buttons use a solid fill to pop against the outlined secondary elements.
## Shapes
The design system employs a **Soft (0.25rem)** roundedness level. This subtle rounding softens the industrial nature of the dashboard while maintaining a professional, structured appearance.
- **Inputs and Buttons:** 4px (0.25rem) radius.
- **Cards and Containers:** 8px (0.5rem) radius.
- **Status Tags:** Fully rounded (pill) to clearly distinguish them from interactive buttons or input fields.
## Components
### Data Tables
Tables are the heart of the system. Use a "Zebra Stripe" pattern (alternate rows in #F9FAFB) for long datasets. Headers must be "Sticky" during scroll and styled with a light gray background and `label-md` typography.
### Analytics Charts
Use a minimalist approach. Grid lines should be faint (#F3F4F6). Primary data series should use Corporate Blue (#0059A6), with secondary series in #6389B8 and #94A3B8. Avoid 3D effects.
### Status Cards
Exhibition status cards should feature a prominent "Current State" indicator (e.g., "Active," "Completed," "Scheduled") using semantic background tints and dark text for accessibility.
### Buttons
- **Primary:** Solid #0059A6 with white text.
- **Secondary:** White background with #E5E7EB border and #374151 text.
- **Destructive:** Solid #E32219 for critical admin actions.
### Administrative Controls
Toggle switches should be used for binary states (e.g., "Public Visibility"). Checkboxes are preferred for multi-select actions in tables. Input fields should have a distinct focus state using a 2px Corporate Blue border.

164
plugins/zio-harness/knowledge/kintex/stitch_kintex_ai_system_architect/precision_enterprise_ai/DESIGN.md Normal file
View File

@ -0,0 +1,164 @@
---
name: Precision Enterprise AI
colors:
surface: '#f9f9ff'
surface-dim: '#d2daf0'
surface-bright: '#f9f9ff'
surface-container-lowest: '#ffffff'
surface-container-low: '#f1f3ff'
surface-container: '#e9edff'
surface-container-high: '#e0e8ff'
surface-container-highest: '#dbe2f9'
on-surface: '#141b2c'
on-surface-variant: '#414751'
inverse-surface: '#293041'
inverse-on-surface: '#edf0ff'
outline: '#717782'
outline-variant: '#c1c7d3'
surface-tint: '#0060a9'
primary: '#004e8b'
on-primary: '#ffffff'
primary-container: '#0066b3'
on-primary-container: '#d2e3ff'
inverse-primary: '#a2c9ff'
secondary: '#5427e6'
on-secondary: '#ffffff'
secondary-container: '#6d4aff'
on-secondary-container: '#f3edff'
tertiary: '#00583b'
on-tertiary: '#ffffff'
tertiary-container: '#00734e'
on-tertiary-container: '#8ef7c3'
error: '#ba1a1a'
on-error: '#ffffff'
error-container: '#ffdad6'
on-error-container: '#93000a'
primary-fixed: '#d3e4ff'
primary-fixed-dim: '#a2c9ff'
on-primary-fixed: '#001c38'
on-primary-fixed-variant: '#004881'
secondary-fixed: '#e5deff'
secondary-fixed-dim: '#c9bfff'
on-secondary-fixed: '#1b0063'
on-secondary-fixed-variant: '#4500d8'
tertiary-fixed: '#8ef7c4'
tertiary-fixed-dim: '#72daa9'
on-tertiary-fixed: '#002113'
on-tertiary-fixed-variant: '#005236'
background: '#f9f9ff'
on-background: '#141b2c'
surface-variant: '#dbe2f9'
typography:
display-lg:
fontFamily: Inter
fontSize: 36px
fontWeight: '700'
lineHeight: 44px
letterSpacing: -0.02em
display-lg-mobile:
fontFamily: Inter
fontSize: 28px
fontWeight: '700'
lineHeight: 36px
headline-md:
fontFamily: Inter
fontSize: 24px
fontWeight: '600'
lineHeight: 32px
title-sm:
fontFamily: Inter
fontSize: 18px
fontWeight: '600'
lineHeight: 28px
body-base:
fontFamily: Inter
fontSize: 14px
fontWeight: '400'
lineHeight: 20px
body-sm:
fontFamily: Inter
fontSize: 13px
fontWeight: '400'
lineHeight: 18px
label-md:
fontFamily: Geist
fontSize: 12px
fontWeight: '600'
lineHeight: 16px
letterSpacing: 0.02em
label-xs:
fontFamily: Geist
fontSize: 11px
fontWeight: '500'
lineHeight: 14px
rounded:
sm: 0.125rem
DEFAULT: 0.25rem
md: 0.375rem
lg: 0.5rem
xl: 0.75rem
full: 9999px
spacing:
base: 4px
container-padding: 24px
gutter: 16px
stack-sm: 8px
stack-md: 16px
stack-lg: 24px
---
## Brand & Style
This design system is engineered for a high-stakes B2B enterprise environment, specifically tailored for exhibition management. The brand personality is rooted in **reliability, precision, and institutional authority**, reflecting the scale of the KINTEX infrastructure.
The design style follows a **Corporate / Modern** aesthetic with a focus on data density and functional clarity. It prioritizes information hierarchy to support rapid decision-making in complex workflows. The UI utilizes a structured grid, high-contrast typography, and purposeful use of color to distinguish between human-managed data and AI-generated suggestions. The emotional response should be one of "controlled efficiency"—where the user feels empowered by the tool's intelligence rather than overwhelmed by its complexity.
## Colors
The palette is dominated by **KINTEX Blue (#0066B3)**, establishing a professional and trustworthy foundation. A specialized **AI Accent (Purple #6D4AFF)** is introduced specifically to highlight features where the system provides drafts, suggestions, or automated logic.
- **Primary Tier**: Used for core actions and active states.
- **AI Tier**: Reserved for generative elements and automated labels.
- **Canvas Tier**: A deep charcoal surface (#1C2536) is utilized for the "Editor Canvas" to provide a high-contrast workspace for layout planning and spatial management, separating the "work" area from the "management" UI.
- **Neutrals**: A sophisticated range of grays from #F9FAFB (backgrounds) to #101828 (primary text) ensures deep legibility and clean separation of UI layers.
## Typography
This design system utilizes **Inter** as the primary typeface for its exceptional legibility in high-density data environments, serving as a modern surrogate for Pretendard. **Geist** is used for labels and monospaced technical data to reinforce the "AI/Systems" feel.
The typographic scale is optimized for SaaS:
- **High Density**: The base body size is set to **14px** to allow more data to be visible on the screen simultaneously.
- **Weight Contrast**: Bold weights (600/700) are used strictly for headings and critical status indicators to guide the eye quickly.
- **Technical Precision**: Labels and captions use a slightly tighter tracking and smaller scale (11px-12px) for metadata that supports primary content.
## Layout & Spacing
The layout follows a **Fluid Grid** model with a 4px baseline shift to ensure consistent alignment.
- **Desktop**: 12-column grid with 16px gutters and 24px outer margins.
- **Information Density**: Padding in data tables and property panels is kept tight (8px to 12px) to maximize content visibility without sacrificing touch/click targets.
- **Editor Canvas**: Operates on a dedicated 8px or 16px snap-to-grid system for precise placement of exhibition booths and assets.
- **Reflow**: On tablet devices, the side navigation collapses into an icon-only rail, while the 12-column grid transitions to an 8-column layout.
## Elevation & Depth
The system uses **Tonal Layers** rather than heavy shadows to maintain a clean, professional workspace.
- **Level 0 (Base)**: Background surface (#F9FAFB).
- **Level 1 (Cards/Sections)**: White surface with a thin 1px border (#E4E7EC). No shadow.
- **Level 2 (Modals/Popovers)**: White surface with a soft, neutral ambient shadow (Y: 4px, Blur: 12px, 10% opacity) to provide focus.
- **The Editor Surface**: Uses a "Reverse Elevation" strategy where the canvas is the lowest level (dark background), and tools/panels float above it with subtle glassmorphism effects (10px backdrop blur) to maintain context of the underlying layout.
## Shapes
A **Soft (0.25rem)** roundedness is applied throughout the system to balance professional rigor with modern software aesthetics.
- **Small Components**: Checkboxes, inputs, and small buttons use the 4px (0.25rem) radius.
- **Large Components**: Cards and modals scale up to 8px (0.5rem) to soften the overall interface.
- **AI Elements**: Components specifically related to AI (Drafts, Suggestions) may utilize a slightly more organic feel, but must stay within the system's 8px maximum limit to maintain visual cohesion.
## Components
- **StatusBadge**: Follows a strict semantic progression: Gray (Draft) -> Blue (In Review) -> Purple (AI Optimized) -> Green (Approved) -> Red (Violation/Conflict).
- **DdayChip**: A compact, high-contrast tag used in lists to show time-sensitive deadlines (e.g., "D-15"). Uses a bold background and white text.
- **AI Labels**: Elements generated or drafted by the system are marked with a Purple (#6D4AFF) hairline outline and a small sparkle icon prefix.
- **ViolationFlag**: High-visibility red indicator (#D92D20) used in the canvas to mark booth placement errors or safety regulation breaches.
- **Input Fields**: Minimal styling with a 1px border. On focus, the border transitions to KINTEX Blue with a soft 2px outer glow.
- **Buttons**:
- **Primary**: Solid KINTEX Blue.
- **Secondary**: Outlined Blue or Gray.
- **AI Action**: Solid Purple with a subtle gradient to indicate "Generative" capability.
- **Cards**: Use a white background, 1px border, and no shadow. The header of the card should have a 4px padding-left accent color matching its status.

71
plugins/zio-harness/knowledge/kintex/tools/nanobanana/README.md Normal file
View File

@ -0,0 +1,71 @@
# tools/nanobanana — Gemini 이미지 생성(나노바나나) 연동 모듈
부스/인테리어/배선/조명 설계 데이터를 "시공 후 결과 사진"으로 렌더링한다.
설계 기준: ReRoomAI 실증 패턴(`docs/analysis/reroomai-source.md`) + PLANNING §6.
## 준비
```bash
pip install google-genai Pillow
export GEMINI_API_KEY=발급받은_키 # https://aistudio.google.com
```
- 모델 기본값: `gemini-3.1-flash-image-preview`(나노바나나 2). `NANOBANANA_MODEL`로 오버라이드.
- ★ 실제 Gemini 호출은 소유자 승인 대기(reroomai-source.md §8). 키/네트워크 없이도 import·구조는 성립.
## 빠른 시작 (§6-2 scene 스키마)
```python
from tools.nanobanana.client import NanoBananaClient
scene = {
"hall": {"id": "제1전시장 7홀", "dims_m": [126, 90], "ceiling_m": 12},
"booth": {"id": "A-102", "size_m": [6, 3], "type": "independent"},
"design": {
"signage": {"text": "주식회사 가디아"},
"brand_color": "#0052A5",
"zones": [{"type": "demo"}, {"type": "consult"}],
"materials": [{"part": "wall", "finish": "matte_white"}],
},
"lighting": {"mode": "night", "color_temp_k": 4000},
"wiring": {"power": [{"from_trench": [1, 1], "to": [5, 2], "kw": 3}]},
"render_hints": {"style": "tech"},
}
c = NanoBananaClient()
img = c.render_shot(scene, shot_preset="S2",
reference_image="empty_booth.jpg", # 빈 부스 실측 → 구조 보존
seed=12345) # 컷 간 일관성(B-12)
img.save("output/visualizations/booth_S2.png") # 사이드카 .meta.json 동시 기록
```
## 표준 샷 세트 S1~S7 (PLANNING §6-3)
| 샷 | 호출 | 용도 |
|---|---|---|
| S1 정면 주간 | `render_shot(scene,"S1")` | 기본 시안 확인 |
| S2 정면 야간 | `render_shot(scene,"S2")` | 조명 연출 평가 |
| S3 통로 뷰 | `render_shot(scene,"S3")` | 관람객 시점 동선 |
| S4 내부 뷰 | `render_shot(scene,"S4")` | 인테리어/집기 배치 |
| S5 Before/After | S1 결과 + `reference_image`(빈 부스 실측) 쌍 | 시공 전/후 비교 |
| S6 배선 오버레이 | `render_wiring_overlay_raster(wiring, hall_dims_m, kinds)` ★래스터 합성 | 시공 검증(좌표 정합) |
| S7 홀 전경 조감 | `render_shot(scene,"S7")` | 배치안 비교(SCR-04) |
### S6 — 생성형 아님 (B-02)
시공 검증용 S6는 좌표 정합이 보장되는 **백엔드 래스터 합성**이다(로컬 PIL):
```python
from tools.nanobanana.client import render_wiring_overlay_raster
ov = render_wiring_overlay_raster(scene["wiring"], hall_dims_m=(6, 3),
kinds=["power", "network", "plumbing"],
base_image="floorplan.png") # 선택
ov.save("output/visualizations/booth_S6_wiring.png")
```
`generate_wiring_overlay(layout, kind)`(생성형)는 발표/설명용 보조 이미지 전용 — 시공 검증 사용 금지.
## 하위호환
평면 `booth_spec` dict를 쓰던 기존 코드는 `generate_booth_photo(booth_spec, view, time_of_day)`가
내부적으로 §6-2 scene 으로 변환 후 `render_shot`에 위임한다(그대로 동작).
## 방어·정책
- 입력 이미지 8MB 상한 + 긴 쪽 1024px 다운스케일/JPEG 0.85(`downscale_for_upload`).
- 에러 분기: `NanoBananaAuthError`(키 무효) / `NanoBananaQuotaError`(429·쿼터) / `NanoBananaSafetyError`(SAFETY).
- 쿼터/카운트는 **성공 시에만** 차감(`usage_recorder` 훅).
- 모든 산출 이미지에 "AI 생성 예상 이미지 — 실제 시공 결과와 다를 수 있음" 워터마크(계약 서류 사용 금지).
- 메타데이터(생성일·스키마 해시·모델 버전·seed)는 사이드카 `.meta.json` + PNG tEXt 청크로 임베드(B-03).
- API 키는 환경변수 `GEMINI_API_KEY`에서만 로드 — 코드/로그/커밋에 절대 기록 금지.

39
plugins/zio-harness/knowledge/kintex/tools/test/README.md Normal file
View File

@ -0,0 +1,39 @@
# KINTEX 테스트 도구
GUARDiA `scripts/check/run_full_test.py` 패턴을 킨텍스(백엔드 8021)로 경량 이식한 스모크/회귀 러너.
## kintex_smoke_test.py
배포 후 검증·회귀·스모크용. **읽기(GET) + 미인증 로그인 프로브만** 보내며 파괴적 요청은 없다.
검증 항목:
- **배포 게이트**: `GET /health` → 200 + `data.status=UP`
- **인증**: `/api/auth/login` 프로브(라우터 등록) · `/api/auth/workspaces`·`/me`
- **공통·시스템**: `/api/common/menus`·`/api/common/code-groups`·`/api/admin/menus`
- **공통 업무(WISE)**: `/api/work/notices`·`/api/work/stats/worklog`·`/api/work/notifications/unread-count`
- **전시 코어(M2~M5)**: layout·design·utility 라우터 등록
판정: 200/201=OK, 401/403/400/422=라우터 존재·인증필요(정상), 404/501=미등록/미구현(실패).
### 실행 모드
| 모드 | 방법 | 필요 env |
|------|------|----------|
| SSH(기본) | 로컬 PC→서버 SSH→서버 내부 curl | `KINTEX_SSH_HOST`, `KINTEX_SSH_PASSWORD`(또는 `KINTEX_SSH_KEYFILE`) |
| `--local` | 같은 호스트에서 로컬 curl | 없음 |
| `--http` | 도메인 직접 | `KINTEX_BASE`(예 `https://kintex.zioinfo.co.kr`) |
선택 env: `KINTEX_SSH_USER`(기본 root)·`KINTEX_BASE`(기본 `http://127.0.0.1:8021`)·`KINTEX_TEST_EMAIL`/`KINTEX_TEST_PASSWORD`(주어지면 1차 로그인 shape 확인).
```bash
python tools/test/kintex_smoke_test.py # SSH
python tools/test/kintex_smoke_test.py --local # 서버 로컬
KINTEX_BASE=https://kintex.zioinfo.co.kr python tools/test/kintex_smoke_test.py --http
```
결과: `tools/test/_results/latest.json` + 타임스탬프 파일. 종료코드 0=통과, 1=실패(CI 게이트용).
## 보안
- 시크릿 하드코딩 0 — SSH·테스트계정은 env only, 로그/리포트에 미노출.
- 실서버 데이터 변경 없음(읽기 + 미인증 프로브).

103
plugins/zio-harness/scripts/graphify_setup.py Normal file
View File

@ -0,0 +1,103 @@
#!/usr/bin/env python3
"""zio-harness graphify bootstrap.
SessionStart hook: ensure graphify (+SQL parser) is installed, then
build or update the project knowledge graph so the assistant can answer
codebase questions from graphify-out/graph.json immediately.
Env switches:
ZIO_HARNESS_NO_GRAPHIFY=1 skip everything
ZIO_HARNESS_GRAPHIFY_FULL=1 allow first-time extraction even without .git
"""
import importlib.util
import os
import shutil
import subprocess
import sys
import sysconfig
TIMEOUT_INSTALL = 300
TIMEOUT_GRAPH = 480
def log(msg: str) -> None:
print(f"[zio-harness] {msg}")
def has_module(name: str) -> bool:
try:
return importlib.util.find_spec(name) is not None
except Exception:
return False
def find_graphify() -> str | None:
exe = shutil.which("graphify")
if exe:
return exe
scripts = sysconfig.get_path("scripts") or ""
for candidate in ("graphify.exe", "graphify"):
path = os.path.join(scripts, candidate)
if os.path.isfile(path):
return path
return None
def ensure_installed() -> str | None:
if find_graphify() and has_module("tree_sitter_sql"):
return find_graphify()
log("installing graphifyy[sql] (one-time)...")
try:
subprocess.run(
[sys.executable, "-m", "pip", "install", "--quiet", "graphifyy[sql]"],
timeout=TIMEOUT_INSTALL,
check=False,
)
except Exception as exc: # network down, pip missing, etc.
log(f"install skipped: {exc}")
return find_graphify()
def run_graphify(exe: str, *args: str) -> int:
try:
proc = subprocess.run([exe, *args], timeout=TIMEOUT_GRAPH, check=False)
return proc.returncode
except Exception as exc:
log(f"graphify {' '.join(args[:1])} failed: {exc}")
return 1
def main() -> int:
if os.environ.get("ZIO_HARNESS_NO_GRAPHIFY") == "1":
return 0
cwd = os.getcwd()
home = os.path.expanduser("~")
graph = os.path.join(cwd, "graphify-out", "graph.json")
is_project = os.path.isdir(os.path.join(cwd, ".git")) or os.path.isfile(graph)
if os.path.normcase(cwd) == os.path.normcase(home):
return 0 # never index the home directory
if not is_project and os.environ.get("ZIO_HARNESS_GRAPHIFY_FULL") != "1":
return 0 # not a project root — stay quiet
exe = ensure_installed()
if not exe:
log("graphify unavailable — skipping knowledge graph")
return 0
if os.path.isfile(graph):
rc = run_graphify(exe, "update", cwd)
if rc == 0:
log("knowledge graph updated (graphify-out/graph.json) — "
"use `graphify query/explain/path` for codebase questions")
else:
log("building knowledge graph (first run, local AST only)...")
rc = run_graphify(exe, "extract", cwd, "--code-only")
if rc == 0:
log("knowledge graph built at graphify-out/graph.json — "
"use `graphify query/explain/path` for codebase questions")
return 0
if __name__ == "__main__":
sys.exit(main())

38
plugins/zio-harness/skills/zio-harness/SKILL.md
View File

@ -32,6 +32,44 @@ analyst → agent → bot → (orchestrator 종합)
| E2E 테스트 | `references/playwright.md` | | E2E 테스트 | `references/playwright.md` |
| DB/MCP 작업 | `references/database.md` | | DB/MCP 작업 | `references/database.md` |
| 에이전트 설계 | `references/orchestrator.md`, `references/analyst.md`, `references/bot.md`, `references/agent.md` | | 에이전트 설계 | `references/orchestrator.md`, `references/analyst.md`, `references/bot.md`, `references/agent.md` |
| KINTEX 도메인 지식 | `knowledge/kintex/` (기획서·설계·분석·백로그 등 md 전체) |
| GUARDiA 전사 지식 | `knowledge/guardia/` (솔루션 카탈로그·표준 프레임워크·운영 CI/CD·개발 교훈) |
## 지식 그래프 (graphify) — 소스 자동 분석
플러그인 설치만으로 프로젝트 소스가 자동 분석된다. SessionStart 훅(`scripts/graphify_setup.py`)이:
1. `graphifyy[sql]` 패키지를 자동 설치 (pip, 1회)
2. 그래프가 없으면 `graphify extract . --code-only`로 최초 구축 (로컬 AST — LLM/외부 API 불필요)
3. 그래프가 있으면 `graphify update .`로 변경분만 갱신
**규칙 — 코드베이스 구조 질문은 그래프 우선:**
- `graphify-out/graph.json`이 존재하면 파일 전수 검색 전에 반드시 그래프를 먼저 조회한다:
- `graphify query "<질문>"` — 관련 노드 BFS 탐색
- `graphify explain "<심볼>"` — 노드·이웃 설명
- `graphify path "A" "B"` — 두 심볼 간 경로
- `graphify affected "X"` — 변경 영향 범위 (리팩터링 전 필수)
- analyst는 Phase 1 분석 시 그래프 조회 결과를 `_workspace/00_analysis.md`에 인용한다.
- agent는 구현 전 `graphify affected`로 영향 파일을 확인한다.
- 훅을 끄려면 환경변수 `ZIO_HARNESS_NO_GRAPHIFY=1`.
## KINTEX 지식 베이스
`knowledge/kintex/`에 KINTEX AI 전시·행사시스템의 전체 md 문서(기획 PLANNING·design·데이터표준·벤치마킹 분석·백로그·소유자 피드백 로그 등)가 내장되어 있다. KINTEX 관련 작업 시 이 폴더를 도메인 지식 소스로 우선 참조한다.
## GUARDiA 전사 지식 베이스
GUARDiA 전체 md 문서(2,400여 개)를 분석·정제한 지식이 `knowledge/guardia/`에 내장되어 있다:
| 파일 | 내용 | 참조 시점 |
|------|------|----------|
| `solutions-catalog.md` | 전 솔루션 카탈로그 (스택·포트·DB·연동 맵) | 어떤 GUARDiA 솔루션이든 작업 시작 시 |
| `standard-framework.md` | GUARDiA 표준 프레임워크 (UIMS 기준 스택·인증 JWT+2FA·공통모듈·WISE 디자인·AI 플랫폼·보안 불변) | 신규 기능/솔루션 개발 시 |
| `operations-cicd.md` | 배포 파이프라인·webhook·systemd·health 게이트·테스트 체계 | 배포/운영 작업 시 |
| `lessons-learned.md` | 증상→근본원인→해결 패턴 교훈 모음 (DB·배포·AI·UI·프로세스) | 오류 진단·리팩터링 전 필수 |
analyst는 분석 시작 시 이 지식 베이스를 프로젝트 컨텍스트로 로드하고, 교훈 문서의 기지 함정과 충돌하는 구현을 발견하면 즉시 보고한다.
--- ---