kintex/docs/architecture/data.md

# 킨텍스 자동전시시스템 — 데이터 아키텍처 (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 |

---

## 9. 변경 이력

| 버전 | 일자 | 작성자 | 내용 |
|---|---|---|---|
| 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 후속. |