> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/developer/database-schema.md).

# 데이터베이스 스키마

## 개요

이 문서에서는 PlantPulse 플랫폼에서 사용하는 데이터베이스의 스키마를 안내합니다. PlantPulse는 목적에 맞게 두 가지 데이터베이스를 함께 사용하고 있습니다. 처음 접하시는 분이라면, 구조적인 설정 데이터는 PostgreSQL에, 대량의 시계열 데이터는 Cassandra에 저장된다는 점을 먼저 이해해 주시면 전체 구조를 파악하시기 쉽습니다.

```mermaid
graph LR
  subgraph PG["PostgreSQL (메타스토어)"]
    COMP[mm_company]
    SITE[mm_site]
    ASSET[mm_asset]
    TAG[mm_tag]
    USER[mm_user]
    SG[mm_security_group]
    OPC[mm_opc]
    ALARM[mm_alarm_rule]
    OEE[mm_oee]
  end

  subgraph CASS["Cassandra (시계열)"]
    TP[tm_tag_point]
    TA[tm_tag_alarm]
    AD[tm_asset_data]
    AA_T[tm_asset_alarm]
    AE[tm_asset_event]
  end

  ASSET -->|tag_id 매핑| TAG
  TAG -.->|FK| OPC
  ASSET -.->|FK| SITE
  SITE -.->|FK| COMP
  USER -.->|FK| SG
  ALARM -.->|FK| TAG

  TAG -.->|키 참조| TP
  TAG -.->|키 참조| TA
  ASSET -.->|키 참조| AD
  ASSET -.->|키 참조| AA_T
  ASSET -.->|키 참조| AE
```

| DB             | 역할      | 데이터 특성                              |
| -------------- | ------- | ----------------------------------- |
| **PostgreSQL** | 메타스토어   | 사용자, 사이트, 에셋, 태그, 알람 설정 등 구조적 데이터   |
| **Cassandra**  | 시계열 스토어 | 태그 포인트, 알람 이력, 에셋 데이터 등 대용량 시계열 데이터 |

> **명명 규칙**: `mm_*` 은 PostgreSQL **M**aster **M**etadata, `tm_*` 은 Cassandra **T**ime-series **M**etric. 자세한 ID 명명 규칙은 [도메인 ID 네이밍 컨벤션](/plantpulse-platform/developer/id-naming-convention.md) 참고.

***

## PostgreSQL 스키마 (메타스토어)

PostgreSQL은 플랫폼의 메타데이터를 관리하는 역할을 담당합니다. 사용자 정보, 사이트 구성, 에셋 계층, 태그 정의, 알람 설정 등 구조화된 데이터가 이곳에 저장됩니다.

### 연결 정보

| 항목       | 기본값                              |
| -------- | -------------------------------- |
| URL      | `jdbc:postgresql://HOST:5432/pp` |
| User     | plantpulse                       |
| Database | pp                               |

### 테이블 목록

#### 조직·사이트

**MM\_COMPANY** — 회사 정보

| 컬럼                 | 타입      | 설명                                  |
| ------------------ | ------- | ----------------------------------- |
| COMPANY\_ID        | VARCHAR | PK. `COMP_XXXXX` 형식 (COMP\_SEQ 시퀀스) |
| COMPANY\_NAME      | VARCHAR | 회사명                                 |
| COMPANY\_LOGO\_URL | VARCHAR | 로고 URL                              |

**mm\_site** — 사이트(공장)

| 컬럼           | 타입        | 설명                                  |
| ------------ | --------- | ----------------------------------- |
| SITE\_ID     | VARCHAR   | PK. `SITE_XXXXX` 형식 (SITE\_SEQ 시퀀스) |
| SITE\_NAME   | VARCHAR   | 사이트명                                |
| LAT          | DOUBLE    | 위도                                  |
| LNG          | DOUBLE    | 경도                                  |
| COMPANY\_ID  | VARCHAR   | FK → MM\_COMPANY                    |
| DESCRIPTION  | TEXT      | 설명                                  |
| INSERT\_DATE | TIMESTAMP | 생성일                                 |
| UPDATE\_DATE | TIMESTAMP | 수정일                                 |

#### 에셋·설비 계층

**MM\_ASSET\_TREE** — 에셋 계층 구조 (ISA-95)

PlantPulse에서는 공장의 설비를 ISA-95 표준에 따라 계층적으로 관리합니다. 아래 테이블이 그 계층 구조를 표현합니다.

| 컬럼                | 타입      | 설명                                |
| ----------------- | ------- | --------------------------------- |
| ASSET\_ID         | VARCHAR | PK                                |
| PARENT\_ASSET\_ID | VARCHAR | FK → MM\_ASSET\_TREE (자기 참조)      |
| ASSET\_NAME       | VARCHAR | 에셋명                               |
| ASSET\_ORDER      | INT     | 정렬 순서                             |
| ASSET\_SVG\_IMG   | TEXT    | SVG 이미지                           |
| ASSET\_TYPE       | CHAR(1) | `A`=Area, `L`=Line, `M`=Equipment |
| SITE\_ID          | VARCHAR | FK → mm\_site                     |
| TABLE\_TYPE       | VARCHAR | 테이블 유형                            |

**계층 구조**:

```
Site (공장)
  └── Area (A) - 영역
      └── Line (L) - 생산라인
          └── Equipment (M) - 설비/장비
```

#### OPC·데이터 수집

**mm\_opc** — OPC 서버

OPC 서버는 산업 현장의 데이터 소스를 나타냅니다. 이 테이블에서 각 OPC 서버의 연결 정보를 관리합니다.

| 컬럼              | 타입      | 설명                         |
| --------------- | ------- | -------------------------- |
| OPC\_ID         | VARCHAR | PK                         |
| OPC\_NAME       | VARCHAR | OPC 서버명                    |
| OPC\_TYPE       | VARCHAR | 프로토콜 유형 (OPC-UA, Modbus 등) |
| OPC\_SERVER\_IP | VARCHAR | 서버 IP                      |
| SITE\_ID        | VARCHAR | FK → mm\_site              |

**mm\_tag** — 태그(데이터 포인트)

태그는 센서나 PLC에서 수집되는 개별 데이터 포인트를 의미합니다. 각 태그에는 알람 임계값, 단위, 표시 형식 등의 속성이 정의되어 있습니다.

| 컬럼                | 타입      | 설명                                 |
| ----------------- | ------- | ---------------------------------- |
| TAG\_ID           | VARCHAR | PK. `TAG_####` 또는 `VTAG_####` 형식   |
| TAG\_NAME         | VARCHAR | 태그명                                |
| TAG\_SOURCE       | VARCHAR | 데이터 소스                             |
| JAVA\_TYPE        | VARCHAR | 데이터 타입 (Double, Integer, String 등) |
| ALIAS\_NAME       | VARCHAR | 별칭                                 |
| IMPORTANCE        | VARCHAR | 중요도                                |
| INTERVAL          | INT     | 수집 주기                              |
| UNIT              | VARCHAR | 단위 (℃, %, bar 등)                   |
| TRIP\_HI          | DOUBLE  | Trip High 한계값                      |
| HI\_HI            | DOUBLE  | High-High 한계값                      |
| HI                | DOUBLE  | High 한계값                           |
| LO                | DOUBLE  | Low 한계값                            |
| LO\_LO            | DOUBLE  | Low-Low 한계값                        |
| TRIP\_LO          | DOUBLE  | Trip Low 한계값                       |
| MIN\_VALUE        | DOUBLE  | 표시 최소값                             |
| MAX\_VALUE        | DOUBLE  | 표시 최대값                             |
| DISPLAY\_FORMAT   | VARCHAR | 표시 형식                              |
| LINKED\_ASSET\_ID | VARCHAR | FK → MM\_ASSET\_TREE               |
| OPC\_ID           | VARCHAR | FK → mm\_opc                       |

**mm\_point** — 포인트 데이터 (TimescaleDB Hypertable)

포인트 데이터는 실시간으로 수집되는 측정값을 저장하는 테이블입니다. TimescaleDB의 Hypertable로 구성되어 있어 시계열 데이터를 효율적으로 처리할 수 있습니다.

| 컬럼          | 타입        | 설명                     |
| ----------- | --------- | ---------------------- |
| timestamp   | TIMESTAMP | PK (복합)                |
| site\_id    | VARCHAR   | PK (복합). FK → mm\_site |
| opc\_id     | VARCHAR   | PK (복합). FK → mm\_opc  |
| tag\_id     | VARCHAR   | PK (복합). FK → mm\_tag  |
| area\_id    | VARCHAR   | 영역 ID                  |
| line\_id    | VARCHAR   | 라인 ID                  |
| asset\_id   | VARCHAR   | 설비 ID                  |
| value       | VARCHAR   | 측정값                    |
| type        | VARCHAR   | 데이터 타입                 |
| latency     | INT       | 수집 지연(ms)              |
| error\_code | VARCHAR   | 에러 코드                  |
| quality     | VARCHAR   | 품질 플래그                 |
| attribute   | JSONB     | 확장 속성                  |

* **인덱스**: `mm_point_idx_1 (site_id, area_id, line_id, opc_id, tag_id)`
* **보관 기간**: 10일 (설정 가능)
* **압축**: tag\_id 기준, timestamp DESC 정렬
* **벌크 삽입**: COPY 전략

#### 알람 설정

**mm\_alarm\_config** — 알람 설정

알람 설정 테이블에서는 각 태그에 대한 알람 조건, 우선순위, 알림 방식 등을 정의합니다.

| 컬럼                      | 타입      | 설명                       |
| ----------------------- | ------- | ------------------------ |
| ALARM\_CONFIG\_ID       | VARCHAR | PK                       |
| TAG\_ID                 | VARCHAR | FK → mm\_tag             |
| ALARM\_CONFIG\_NAME     | VARCHAR | 설정명                      |
| ALARM\_CONFIG\_PRIORITY | VARCHAR | 우선순위 (INFO, WARN, ERROR) |
| ALARM\_CONFIG\_DESC     | TEXT    | 설명                       |
| ALARM\_TYPE             | VARCHAR | `BAND` (밴드) 또는 `DEFAULT` |
| CONDITION               | VARCHAR | 조건식                      |
| MESSAGE                 | VARCHAR | 알람 메시지                   |
| EPL                     | TEXT    | EPL 쿼리                   |
| SEND\_EMAIL             | BOOLEAN | 이메일 발송 여부                |
| SEND\_SMS               | BOOLEAN | SMS 발송 여부                |
| DUPLICATE\_CHECK        | BOOLEAN | 중복 체크 여부                 |
| DUPLICATE\_CHECK\_TIME  | INT     | 중복 체크 시간(분)              |

#### 사용자·보안

**USER\_LOGIN** — 사용자 계정

| 컬럼                   | 타입        | 설명                        |
| -------------------- | --------- | ------------------------- |
| USER\_ID             | VARCHAR   | PK. 로그인 ID                |
| PASSWORD             | VARCHAR   | 비밀번호 (해시)                 |
| ROLE                 | VARCHAR   | 역할 (ADMIN, MANAGER, USER) |
| SECURITY\_ID         | VARCHAR   | 보안 그룹                     |
| NAME                 | VARCHAR   | 이름                        |
| EMAIL                | VARCHAR   | 이메일                       |
| PHONE                | VARCHAR   | 전화번호                      |
| ADDRESS              | VARCHAR   | 주소                        |
| INSERT\_USER\_ID     | VARCHAR   | 등록자                       |
| INSERT\_DATE         | TIMESTAMP | 등록일                       |
| LAST\_UPDATE\_DATE   | TIMESTAMP | 최종 수정일                    |
| ATTR\_01 \~ ATTR\_10 | VARCHAR   | 확장 속성                     |

**user\_login\_session** — 사용자 세션

| 컬럼             | 타입        | 설명                        |
| -------------- | --------- | ------------------------- |
| login\_id      | VARCHAR   | PK (복합). FK → USER\_LOGIN |
| session\_key   | VARCHAR   | PK (복합). 세션 키             |
| session\_value | VARCHAR   | 세션 값                      |
| update\_date   | TIMESTAMP | 갱신일                       |

#### 기타 테이블

아래 테이블들은 대시보드, 그래프, 제품 정보 등 다양한 부가 기능을 지원합니다.

| 테이블                       | 역할        |
| ------------------------- | --------- |
| MM\_CANVAS                | 캔버스 설정    |
| mm\_product               | 제품 정보     |
| mm\_oee                   | OEE 메트릭   |
| mm\_query\_history        | 쿼리 이력     |
| MM\_ASSET\_STATEMENT      | 에셋 스테이트먼트 |
| mm\_control               | 제어 설정     |
| MM\_SERVER                | 서버 정보     |
| MM\_EMPLOYEE              | 직원 정보     |
| MM\_CUSTOMER              | 고객 정보     |
| MM\_TRIGGER               | 트리거 설정    |
| MM\_TRIGGER\_ATTRIBUTES   | 트리거 속성    |
| mm\_alarm\_recieve\_users | 알람 수신자 매핑 |

### 테이블 관계도

아래 다이어그램은 주요 테이블 간의 관계를 보여줍니다. 화살표 방향은 외래 키(FK) 참조 방향을 나타냅니다.

```
MM_COMPANY
    │ (company_id)
    ▼
mm_site
    ├──────────────────┐
    │ (site_id)        │ (site_id)
    ▼                  ▼
mm_opc           MM_ASSET_TREE ◄──┐
    │ (opc_id)        │            │ (parent_asset_id)
    ▼                 └────────────┘
mm_tag ──────────────▶ MM_ASSET_TREE
    │  (linked_asset_id)
    ▼
mm_alarm_config
mm_point (TimescaleDB)
```

***

## Cassandra 스키마 (시계열 스토어)

Cassandra는 대용량 시계열 데이터를 저장하고 빠르게 조회하기 위한 저장소입니다. 태그 포인트, 알람 이벤트, 에셋 메트릭 등 시간 기반의 데이터가 이곳에 쌓입니다.

### 연결 정보

| 항목          | 기본값                                     |
| ----------- | --------------------------------------- |
| Host        | HOST:9042                               |
| Keyspace    | `pp`                                    |
| Replication | NetworkTopologyStrategy, datacenter1: 1 |
| Compaction  | UCS (Unified Compaction Strategy)       |
| Compression | ZStandard Level 3                       |

### 커스텀 함수 (UDF/UDA)

PlantPulse는 Cassandra에서 데이터를 편리하게 처리하기 위해 아래와 같은 커스텀 함수를 제공합니다.

```sql
-- 타입 변환 함수
TO_INT(text) → int
TO_LONG(text) → bigint
TO_DOUBLE(text) → double
TO_FLOAT(text) → float
TO_BOOLEAN(text) → boolean

-- 집계 함수
value_first()  -- 파티션 내 첫 값
value_last()   -- 파티션 내 마지막 값
```

### 테이블 분류

Cassandra 테이블은 용도에 따라 여러 그룹으로 나뉩니다. 아래에서 각 그룹별 테이블을 안내합니다.

#### 태그 포인트 테이블 (`tm_tag_*`)

| 테이블                             | TTL  | 용도                                             |
| ------------------------------- | ---- | ---------------------------------------------- |
| tm\_tag\_point                  | 62일  | 원시 태그 데이터                                      |
| tm\_tag\_point\_archive         | 365일 | 아카이브 데이터                                       |
| tm\_tag\_point\_map             | 1일   | 포인트 값 맵                                        |
| tm\_tag\_point\_map\_binary     | 1일   | 바이너리 맵                                         |
| tm\_tag\_point\_sampling        | 93일  | 샘플링 데이터                                        |
| tm\_tag\_point\_aggregation     | 93일  | 집계 (min, max, avg, count, sum, stddev, median) |
| tm\_tag\_point\_snapshot        | 93일  | 스냅샷                                            |
| tm\_tag\_point\_count           | -    | 카운트 메트릭                                        |
| tm\_tag\_point\_count\_by\_site | -    | 사이트별 카운트                                       |
| tm\_tag\_point\_count\_by\_opc  | -    | OPC별 카운트                                       |
| tm\_tag\_point\_count\_by\_date | -    | 일별 카운트                                         |
| tm\_tag\_point\_validation      | 93일  | 데이터 검증 결과                                      |
| tm\_tag\_point\_anomalies       | -    | 이상 탐지 데이터                                      |
| tm\_tag\_point\_forecasts       | -    | 예측 데이터                                         |

#### 알람 테이블 (`tm_tag_alarm_*`)

| 테이블                             | 용도          |
| ------------------------------- | ----------- |
| tm\_tag\_alarm                  | 알람 이벤트      |
| tm\_tag\_alarm\_on              | 활성(ON) 알람   |
| tm\_tag\_alarm\_duration        | 알람 지속 시간    |
| tm\_tag\_alarm\_count           | 알람 카운트      |
| tm\_tag\_alarm\_count\_by\_date | 일별 알람 카운트   |
| tm\_tag\_alarm\_count\_by\_opc  | OPC별 알람 카운트 |
| tm\_tag\_alarm\_count\_by\_site | 사이트별 알람 카운트 |

#### 에셋 테이블 (`tm_asset_*`)

| 테이블                            | 용도        |
| ------------------------------ | --------- |
| tm\_asset\_data                | 원시 에셋 데이터 |
| tm\_asset\_data\_based\_second | 초 단위 집계   |
| tm\_asset\_data\_based\_minute | 분 단위 집계   |
| tm\_asset\_data\_based\_hour   | 시간 단위 집계  |
| tm\_asset\_data\_based\_day    | 일 단위 집계   |
| tm\_asset\_alarm               | 에셋 알람     |
| tm\_asset\_health\_status      | 헬스 메트릭    |
| tm\_asset\_connection\_status  | 연결 상태     |
| tm\_asset\_status              | 전체 상태     |
| tm\_asset\_event               | 에셋 이벤트    |
| tm\_asset\_aggregation         | 집계 메트릭    |
| tm\_asset\_context             | 컨텍스트 데이터  |
| tm\_asset\_command             | 커맨드 이력    |
| tm\_asset\_timeline            | 타임라인 이벤트  |

#### OEE 테이블 (`tm_asset_oee_*`)

| 테이블                               | 용도           |
| --------------------------------- | ------------ |
| tm\_asset\_oee                    | 메인 OEE 메트릭   |
| tm\_asset\_oee\_equipment\_status | 설비 상태 (OEE용) |
| tm\_asset\_oee\_lot               | LOT 정보       |
| tm\_asset\_oee\_count             | OEE 카운트      |
| tm\_asset\_oee\_order             | 오더 데이터       |
| tm\_asset\_oee\_shift             | 시프트 정보       |
| tm\_asset\_oee\_product           | 제품 정보        |
| tm\_asset\_oee\_event\_history    | OEE 이벤트 이력   |
| tm\_asset\_oee\_history           | OEE 이력       |

#### OPC 테이블 (`tm_opc_*`)

| 테이블                                   | 용도            |
| ------------------------------------- | ------------- |
| tm\_opc\_point\_last\_update          | OPC별 최종 수신 시각 |
| tm\_opc\_connection\_status\_history  | 연결 상태 이력      |
| tm\_opc\_connection\_latency\_history | 지연 메트릭        |
| tm\_opc\_point\_count                 | 포인트 수         |
| tm\_opc\_point\_count\_by\_date       | 일별 포인트 수      |

#### 시스템 테이블 (`tm_system_*`, `tm_monitor_*`)

| 테이블                           | 용도           |
| ----------------------------- | ------------ |
| tm\_system\_log               | 시스템 로그       |
| tm\_system\_health\_status    | 시스템 헬스       |
| tm\_system\_trend             | 시스템 트렌드      |
| tm\_diagnostic                | 진단 데이터       |
| tm\_monitor\_nodes            | 노드 정보        |
| tm\_monitor\_cluster\_status  | 클러스터 상태      |
| tm\_monitor\_cluster\_metrics | 클러스터 메트릭     |
| tm\_edge\_status              | Edge 디바이스 상태 |
| tm\_database\_size            | DB 사이즈 추적    |

#### 설정·이력 테이블 (`tm_option_*`, `tm_pipeline_*`)

| 테이블                                      | 용도         |
| ---------------------------------------- | ---------- |
| tm\_option\_eql\_statement               | EPL 스테이트먼트 |
| tm\_option\_eql\_statement\_history      | EPL 이력     |
| tm\_option\_eql\_listener\_result        | 리스너 결과     |
| tm\_option\_job\_trigger\_history        | 잡 실행 이력    |
| tm\_option\_system\_start\_date          | 시스템 시작 시각  |
| tm\_option\_system\_properties           | 시스템 설정     |
| tm\_pipeline\_exception\_history         | 파이프라인 에러   |
| tm\_pipeline\_exception\_count\_by\_date | 일별 에러 카운트  |
| tm\_domain\_change\_history              | 도메인 변경 이력  |

#### 통계 테이블 (`tm_stats_*`)

| 테이블                         | 용도        |
| --------------------------- | --------- |
| tm\_stats\_site\_by\_date   | 일별 사이트 통계 |
| tm\_stats\_system\_by\_date | 일별 시스템 통계 |

### TTL (데이터 보관) 정책

각 데이터 유형별로 보관 기간(TTL)이 설정되어 있습니다. 필요에 따라 설정 파일에서 조정하실 수 있습니다.

| 데이터 유형     | TTL  | 설정 키                                |
| ---------- | ---- | ----------------------------------- |
| 태그 포인트     | 62일  | `storage.tag.point.ttl`             |
| 태그 포인트 맵   | 1일   | `storage.tag.point.map.ttl`         |
| 태그 샘플링     | 93일  | `storage.tag.point.sampling.ttl`    |
| 태그 스냅샷     | 93일  | `storage.tag.point.snapshot.ttl`    |
| 태그 집계      | 93일  | `storage.tag.point.aggregation.ttl` |
| 태그 아카이브    | 365일 | `storage.tag.point.archive.ttl`     |
| BLOB 데이터   | 93일  | `storage.blob.ttl`                  |
| 에셋 데이터 샘플링 | 31일  | -                                   |

### Compaction & Compression

Cassandra의 성능 최적화를 위해 아래와 같은 컴팩션 및 압축 전략을 사용하고 있습니다.

| 설정                  | 값                        |
| ------------------- | ------------------------ |
| Compaction Strategy | UCS (Unified Compaction) |
| Compression         | ZStandard Level 3        |
| Scaling Parameter   | T8                       |
| Min SSTable Size    | 128MiB                   |
| Target SSTable Size | 512MiB                   |
| Base Shard Count    | 8                        |

### 공통 컬럼 네이밍

Cassandra 테이블에서 공통적으로 사용되는 컬럼명과 그 의미를 아래 표에서 확인하실 수 있습니다.

| 컬럼                                        | 설명       |
| ----------------------------------------- | -------- |
| site\_id, opc\_id, tag\_id, asset\_id     | 엔티티 식별자  |
| timestamp                                 | 이벤트 시각   |
| date                                      | 날짜 파티션 키 |
| bucket                                    | 버킷 파티션 키 |
| value                                     | 측정값      |
| type                                      | 데이터 타입   |
| quality                                   | 품질 플래그   |
| latency                                   | 지연(ms)   |
| min, max, avg, count, sum, stddev, median | 집계 컬럼    |
| first, last                               | 시간 순서 집계 |