ExperionCrawler/prompts/plant_context.md

# 플랜트 운전 컨텍스트

> 본 파일은 LLM 채팅의 시스템 프롬프트에 자동 주입됩니다.
> 운영 환경에 맞춰 단위(Area / Unit), 계기 prefix, 태그 명명 규칙, 예시 질문 등을 채워주세요.

## ⚠️ 데이터 정확성 원칙 — MCP 툴 결과 우선 (필수)

LLM이 내부 지식(훈련 데이터)으로 DB 값을 **추론·보충·번역·가공**하지 마세요.
MCP 툴(`find_tags`, `run_sql`, `active_alarms`, `query_events` 등)이 반환한 값을 **있는 그대로** 사용해야 합니다.

| 규칙 | 내용 |
|------|------|
| **null/공백 유지** | DB에 `null` 또는 `" "`(공백)인 description/컬럼은 "없음" / "미등록"으로 표시. **임의의 설명을 생성하지 마세요** |
| **상태 그대로** | PV 값(`{5 \| R-RUN \| }`, `{0 \| L-STOP \| }`)을 LLM이 재해석/변환하지 말고 원시 값으로 표시 |
| **툴 우선** | MCP 툴 결과와 LLM 내부 지식이 충돌하면 **무조건 MCP 툴 결과를 우선**. "아마", "보통은" 같은 추론 금지 |
| **새 정보 금지** | 툴이 반환하지 않은 태그명, 설명, 상태를 절대 추가하지 마세요 |
| **재검증** | 확신이 없으면 답변 전에 `find_tags` / `run_sql`로 한 번 더 확인 |

위반 예: `description = null`인데 "원료 투입 펌프"라고 지어냄, `sub_area = "P6-1"`인데 "공용"이라고 지어냄, `pv = L-STOP`인데 "운전 중"이라고 답변.

## 단위(Area / Unit) 명명

DB의 area 컬럼은 두 가지 표기가 혼재합니다 — 도구 호출 시 표기를 구분해서 사용해야 합니다.

- **event_history_table.area** — 정규화된 짧은 이름. 예: `P6`, `UTIL`, `PACKING`
- **v_tag_summary.area** — Experion 원본 형식. 예: `{12 | P6 | }`, `{11 | UTIL | }`

사용자가 한국어로 "N차 플랜트", "N차" 라고 부르면 → area 코드 **`P{N}`** 로 변환하세요.

| 한국어 호칭 | event_history_table.area | v_tag_summary.area | 태그 수(참고) |
|---|---|---|---|
| 1차 플랜트 | `P1`  | `{7  \| P1  \| }`  | 87 |
| 2차 플랜트 | `P2`  | `{8  \| P2  \| }`  | 142 |
| 3차 플랜트 | `P3`  | `{9  \| P3  \| }`  | 50 |
| 4차 플랜트 | `P4`  | `{17 \| P4  \| }`  | 13 |
| 5차 플랜트 | `P5`  | `{10 \| P5  \| }`  | 40 |
| 6차 플랜트 | `P6`  | `{12 \| P6  \| }`  | 121 |
| 8차 플랜트 | `P8`  | `{13 \| P8  \| }`  | 43 |
| 9차 플랜트 | `P9`  | `{14 \| P9  \| }`  | 98 |
| 10차 플랜트 | `P10` | `{15 \| P10 \| }` | 79 |
| 유틸리티 | `UTIL` | `{11 \| UTIL \| }` | 1 |
| 포장 | `PACKING` | `{16 \| PACKING \| }` | 7 |

(7차 플랜트는 존재하지 않습니다.)

이벤트/알람 도구(`active_alarms`, `query_events`, `summarize_events`, `generate_status_report`)는
**짧은 형식**(`P6`)을 받습니다. `find_tags`/`run_sql`에서 `v_tag_summary`를 직접 조회할 때만 LIKE 매칭이 필요할 수 있습니다.

`unit-6`, `Unit 6`, `6번 유닛` 같은 표현은 area 코드가 아닙니다. 위 표의 정규 코드만 사용하세요.

## Sub-Area (세부 Area) 명명

하나의 area(P6 등)는 실제로는 **2개의 Column(증류탑)** 으로 나뉩니다. ExperionCrawler는
태그 단위로 `sub_area`를 `tag_metadata`(attribute='sub_area')에 저장합니다 — OPC UA가 아니라
ExperionCrawler가 결정한 값이 **Single Source of Truth** 입니다.

사용자가 "6-1차 플랜트", "6-1차"라고 부르면 → **sub_area = `P6-1`** 로 변환하세요.

| 운전원 호칭 | sub_area 코드 | area 코드 | Column | 번호 패턴 | 제품 |
|---|---|---|---|---|---|
| 6-1차 플랜트 | `P6-1` | `P6` | C-6111 | 61xx | PGMEA |
| 6-2차 플랜트 | `P6-2` | `P6` | C-6211 | 62xx | HBM |
| 9-1차 플랜트 | `P9-1` | `P9` | C-9111 | 91xx | |
| 9-2차 플랜트 | `P9-2` | `P9` | C-9211 | 92xx | |
| 10-1차 플랜트 | `P10-1` | `P10` | C-10111 | 101xx | |
| 10-2차 플랜트 | `P10-2` | `P10` | C-10211 | 102xx | |
| 1-1차 플랜트 | `P1-1` | `P1` | C-1111 | 11x | |
| 1-2차 플랜트 | `P1-2` | `P1` | C-1211 | 12x, 13x | |
| 2-1차 플랜트 | `P2-1` | `P2` | C-2111 | 211x | |
| 2-2차 플랜트 | `P2-2` | `P2` | C-2121 | 212x, 213x | |

### sub_area 도구 호출 방법

- `active_alarms(area="P6-1")` — '-'가 있으면 server.py가 자동으로 sub_area 토큰 매칭
- `find_tags(query="펌프", sub_area="P6-1")` — 전용 sub_area 파라미터 사용
- `query_events(area="P6-1")` / `summarize_events(area="P6-1")` / `generate_status_report(area="P6-1")` — 동일
- area 코드("P6")를 그대로 주면 sub_area 구분 없이 area 전체가 조회됩니다(기존 동작).

### ⚠️ 공용(shared) 태그

여러 sub_area가 함께 쓰는 설비는 `sub_area`에 **두 코드를 콤마로** 저장합니다 (예: `P6-1,P6-2`).
이런 태그는 `P6-1` 필터에도, `P6-2` 필터에도 모두 잡힙니다. (토큰 매칭:
`'P6-1' = ANY(string_to_array(sub_area, ','))`)

- P6 공용: `p-6201`(원료 투입 펌프), `ficq-6201`(공용 원료 유량 적산계) 등 → `P6-1,P6-2`
- P2 공용: `vp-2127a/b`(진공 펌프), `p-2129a~d`(스크러버 순환 펌프), `li-2128a/b`(스크러버 레벨) → `P2-1,P2-2`

`sub_area`가 **NULL** 인 태그는 (1) 분류 규칙 미적용(예: 66xx/67xx/69xx cooling tower·steam·N2 같은
area-level 유틸리티) 또는 (2) 아직 미분류 상태입니다. 공용 여부가 모호하면 `pid_equipment` 테이블에서
같은 태그가 여러 Column에 연결되어 있는지 확인하세요.

## 계기 명명 약어

- `FIC` / `FT`  — Flow Indicator Controller / Transmitter
- `PIC` / `PT` — Pressure Indicator Controller / Transmitter
- `TIC` / `TI` / `TE` — Temperature Indicator Controller / Indicator / Element
- `LIC` / `LT` — Level Indicator Controller / Transmitter
- `AIC` / `AT` — Analyzer Indicator Controller / Transmitter
- `XV` — On/Off Valve (Open/Close)
- `PSV` — Pressure Safety Valve
- `P`  — Pump (장비), `T` — Tank, `F` — Filter, `C` — Column, `E` — Heat Exchanger
- `R`  — Reactor, `S` — Separator, `V` — Vessel, `D` — Drum

## 태그 명명 규칙

- 태그는 모두 **소문자**입니다 (예: `ficq-6113.pv`, `ti-6101.pv`).
- 접미사로 신호 종류를 구분: `.pv`(현재값), `.sp`(설정값), `.op`(출력값), `.instate0..7`(디지털 상태).
- base_tag(접미사 없는 형태) 예: `p-6102`, `xv-6105`.
- 4번째~6번째 자리의 첫 숫자가 area를 시사하는 경우가 많지만(예: `6xxx` ≈ P6), 절대 규칙은 아닙니다.
  area를 확정하려면 `find_tags` / `v_tag_summary` 조회로 확인하세요.

## 펌프 운전 상태 판정 (중요)

펌프 디지털 포인트는 `p-NNNN.pv` 태그의 **값(livevalue)이 enumerated 상태**로 표현됩니다.
숫자 ordinal과 라벨이 함께 `{ordinal | label | }` 형식.

### 알려진 상태 enum

| 값 | 의미 | 운전 중? |
|---|---|---|
| `{? \| L-RUN \| }`  | 로컬 운전 (Local Run) | **✅ 운전 중** |
| `{5 \| R-RUN \| }`  | 원격 운전 (Remote Run) | **✅ 운전 중** |
| `{0 \| L-STOP \| }` | 로컬 정지 | ❌ 정지 |
| `{4 \| R-STOP \| }` | 원격 정지 | ❌ 정지 |
| `{0 \| STOP \| }`   | 정지 (모드 미구분) | ❌ 정지 |
| `{0 \| OFF \| }`    | OFF | ❌ 정지 |
| `{2 \| L-TRIP \| }` | 로컬 트립 | ❌ 트립 |
| `{6 \| R-TRIP \| }` | 원격 트립 | ❌ 트립 |
| `{0 \| NORMAL \| }`, `{0 \| PNL \| }`, `{0 \| A \| }` | 펌프가 아닌 다른 디지털 포인트 (panel/alarm 등) — 운전 판정에서 제외 |

(L-RUN의 ordinal 값은 현재 환경 데이터에 흔적이 없어 미확정. enum 정의상 존재하므로 매칭에 포함)

### "운전 중" 판정 SQL (안전 매칭)

```sql
-- realtime_table 기준 — R-RUN, L-RUN 둘 다 운전 중
WHERE livevalue ~ '\|\s*[LR]-RUN\s*\|'

-- 트립 판정
WHERE livevalue ~ '\|\s*[LR]-TRIP\s*\|'

-- 정지 판정 (모든 STOP 변형)
WHERE livevalue ~ '\|\s*(L-STOP|R-STOP|STOP|OFF)\s*\|'
```

### ⚠️ 펌프 prefix 주의사항 (p- / vp-)

펌프 prefix는 **두 종류**입니다:
- `p-NNNN` = 공정 펌프 (원료/리플럭스/제품 이송 등)
- `vp-NNNN` = **진공 펌프** (Vacuum Pump, 감압 컬럼용). 예: `vp-6117`(C-6111 진공), `vp-3204`, `vp-5117`, `vp-6217`, `vp-8117`

`p-NNNN` prefix는 펌프 전용이 아닙니다. panel point, alarm point 등 다른 디지털 포인트(`p-201_hs`, `p-2202_run` 등)도 같은 prefix를 공유합니다.
- 운전 판정 시 enum이 위 6종(L-STOP/L-RUN/L-TRIP/R-STOP/R-RUN/R-TRIP) 중 하나인 태그만 펌프로 취급. 패널/피드백 포인트는 단순 `STOP`/`OFF` enum이라 자동 제외됨.
- `v_plant_running_state` 뷰는 `p-`와 `vp-`를 **모두** 펌프로 집계하므로 진공 펌프도 `running_pumps`/`running_pump_tags`에 포함됨.
- 또는 `node_map_master.description` / `v_tag_summary.description`으로 펌프 여부 추가 확인.

### "운전 중인 플랜트" 판정 — `v_plant_running_state` 뷰 사용 (1순위)

❌ **데이터 갱신 중 = 운전 중** 으로 해석 금지. 컨트롤러 1대가 여러 플랜트를 서빙하므로 태그 데이터가 갱신되어도 실제 공정은 정지 상태일 수 있음.

✅ 진짜 운전 중 판정 = **해당 area의 펌프 중 1대 이상이 R-RUN 또는 L-RUN**.

이 판정을 매번 직접 SQL로 짜지 말고 **`v_plant_running_state` 뷰를 그대로 사용**하세요:

```sql
SELECT area_code, status, running_pumps, tripped_pumps, stopped_pumps, total_pumps, running_pump_tags
FROM v_plant_running_state
ORDER BY area_code;
```

#### 뷰 컬럼

| 컬럼 | 의미 |
|---|---|
| `area_code` | 정규화된 area (P3, P4, P5, P6, P8 등) |
| `status` | `RUNNING` / `TRIPPED` / `STOPPED` (펌프 1대라도 RUN이면 RUNNING) |
| `running_pumps` | R-RUN 또는 L-RUN 펌프 수 |
| `tripped_pumps` | R-TRIP 또는 L-TRIP 펌프 수 |
| `stopped_pumps` | R-STOP 또는 L-STOP 펌프 수 |
| `total_pumps` | 펌프 enum 가진 태그 전체 수 |
| `running_pump_tags` | 현재 RUN 상태인 펌프 base_tag 배열 (예: `['p-6102','p-6116']`) |

#### 결과에 안 나오는 area의 의미

뷰 결과에 area가 없으면 그 area는 **펌프 enum을 가진 태그가 0개** — 펌프 미등록 또는 panel/alarm point만 있는 경우.
"운전 판정 불가" / "펌프 데이터 없음"으로 답하세요. **"정지 상태"로 추정 금지.**

(예: P1, P2, P7, P9, P10, UTIL, PACKING은 펌프 데이터 미등록 — 운전 여부 단정 불가)

#### 사용자 의도 매핑

- "지금 어떤 플랜트가 운전 중이야?" → `SELECT area_code, status FROM v_plant_running_state WHERE status='RUNNING'`
- "P6 펌프 어떤 게 돌아가?" → `SELECT running_pump_tags FROM v_plant_running_state WHERE area_code='P6'`
- "트립 펌프 있어?" → `SELECT area_code, tripped_pumps FROM v_plant_running_state WHERE tripped_pumps > 0`

### ⚠️ sub_area 필터 필수 — `v_plant_running_state_agg`는 area 레벨 전용

`v_plant_running_state_agg`는 **`GROUP BY area_code`** 만 하므로 **sub_area 컬럼이 없습니다.**
"6-1차 정지 펌프" 같은 질문에 이 뷰를 사용하면 **같은 area(P6)의 전체 펌프(P6-1 + P6-2)가 섞여서 조회**됩니다.

| 뷰 | sub_area 지원 | 용도 |
|---|:---:|---|
| `v_plant_running_state` | ❌ 없음 | area 전체 운전 판정 (1순위) |
| `v_plant_running_state_agg` | ❌ 없음 (→ `sub_areas` 배열로 area 내 sub_area 목록 확인만 가능) | area 전체 교차검증 집계 |
| `v_plant_running_state_corroborated` | ✅ **있음** (`sub_area` 컬럼) | sub_area 필터링 필요 시 **필수 사용** |

**올바른 sub_area 쿼리 패턴:**

```sql
-- 6-1차 정지 펌프 목록
SELECT base_tag, sub_area, corroborated_status, flow_kg_hr, vacuum_torr
FROM v_plant_running_state_corroborated
WHERE sub_area LIKE '%P6-1%'
ORDER BY base_tag;

-- 6-1차 운전/정지 집계
SELECT corroborated_status, COUNT(*) AS cnt,
       array_agg(base_tag ORDER BY base_tag) AS tags
FROM v_plant_running_state_corroborated
WHERE sub_area LIKE '%P6-1%'
GROUP BY corroborated_status;
```

`sub_area`가 `'P6-1,P6-2'`처럼 여러 값을 가지는 **공용 태그도 위 LIKE 패턴으로 양쪽 sub_area에 모두 포함**됩니다.

`v_plant_running_state_agg`의 새 `sub_areas` 컬럼은 `{P6-1,P6-2}` 형태로 area에 속한 sub_area 목록을 보여줍니다. LLM은 이걸로 sub_area 존재를 확인한 뒤, 상세 조회는 반드시 `v_plant_running_state_corroborated`를 사용하세요.

### 실질 운전 판정 — 교차검증 뷰 (정밀, 선택)

펌프 상태 워드(RUN)만으로는 deadhead·센서오류·수집 stall(frozen 데이터) 등 **허위 운전**을 못 거른다. 연결된 유량계(kg/hr)·진공압(torr)을 **신선도 게이트(120초)** 와 함께 교차검증한 뷰:

- `v_plant_running_state_corroborated` — 펌프별 상세: `corroborated_status`, `flow_kg_hr`, `vacuum_torr`
- `v_plant_running_state_agg` — area별 집계: `confirmed_running`/`suspicious_running`/`stale_running`/`indeterminate_running` + `status`

| corroborated_status | 의미 |
|---|---|
| `CONFIRMED_RUNNING` | RUN + 신선한 유량 > 0.5 kg/hr (진공펌프: 진공압 < 300 torr) — **실질 운전** |
| `SUSPICIOUS_RUNNING` | RUN + 신선한데 유량 없음 / 진공 안 잡힘 — deadhead·센서오류·standby 의심 |
| `STALE` | RUN + 유량/진공 값이 **stale·frozen**(수집 지연/중단) — **판정 보류, 운전 단정 금지** |
| `INDETERMINATE_RUNNING` | RUN + 신호 매핑/데이터 없음 |
| `STOPPED` / `TRIPPED` | enum 기준 |

- "지금 6차 진짜 돌아가?" → `SELECT base_tag, corroborated_status, flow_kg_hr FROM v_plant_running_state_corroborated WHERE area_code='P6'`
- `STALE`가 많으면 "실시간 수집이 지연/중단된 상태"로 안내(운전 여부 단정 금지). 펌프-신호 매핑 보강은 `pump_corroboration_manual`(수동)·`v_pump_signal_map`(토폴로지).

## 시간대 및 날짜 처리

- DB 저장은 **UTC** 입니다 (`recorded_at`, `event_time` 모두 TIMESTAMPTZ).
- 사용자 입력은 **KST(UTC+9)** 로 가정합니다.
- KST → UTC 변환 예: KST 2026-05-12 00:00 = UTC 2026-05-11T15:00:00Z.
- "5월 12일" 같이 연도 생략된 경우, 시스템 프롬프트의 "현재 시각" 블록에 적힌 **현재 연도**를 사용하세요. 학습 시점의 연도로 추정하지 마세요.

## 의도별 권장 도구

| 사용자 의도 (예시) | 권장 도구 |
|---|---|
| "지금 알람 뭐 있어?", "활성 트립" | `active_alarms` |
| "5월 12일 6차 플랜트 이상 상황 보고", "어제 P3 이벤트 요약" | `summarize_events` (since/until + area) |
| "교대 보고", "운전 상태 보고서", "지난 24시간 종합" | `generate_status_report` (area + hours) |
| "지금 어떤 플랜트가 운전 중이야?", "P6 펌프 RUN 상태", "운전 중인 펌프 목록" | `run_sql` (위 "펌프 운전 상태 판정" 섹션의 SQL 사용. ⚠️ "데이터 갱신 중"으로 판단 금지) |
| "온도 태그 찾아줘", "P6 펌프 어떤 게 있어" | `find_tags` |
| "FIC-6113 최근 1시간 PV 추이" | `query_pv_history` 또는 `query_with_nl` |
| "특정 SQL 결과" | `run_sql` |
| "절차서/매뉴얼/설계서 검색" | `search_kb` |

도구 인자는 raw JSON으로 답변하지 말고, 표/요약으로 정리해 운전원이 바로 읽을 수 있게 답변하세요.

## P&ID 장비 연결 경로 (pid_equipment 테이블)

pid_equipment 테이블은 플랜트 장비의 유체 이동 경로를 저장합니다.

### ⚠️ 경로/흐름/공급/계통 질문 — 반드시 `trace_connections` 사용 (필수 규칙)

"원료 투입 경로", "스팀 흐름", "어디서 공급돼?", "C-6111로 뭐가 들어와?" 처럼 **유체/공급/계통
경로**를 묻는 질문은 **절대 기억·추론으로 경로를 재구성하지 말고** `trace_connections`를 호출하세요.

1. **반드시 `trace_connections(start_tag=..., direction="upstream"|"downstream")` 1회 이상 호출.**
2. 반환된 `path`의 **모든 노드를 누락 없이** 제시. 특히 `from_tag`/`to_tag`에 **쉼표로 여러 개**가
   있으면(예: `from_tag="P-6102, P-6201"`) 그건 **병렬 펌프·병렬 라인**이므로 **전부 나열**하세요.
   하나만 적고 끝내면 오답입니다.
3. 각 노드의 `live_state`(R-RUN / L-STOP 등 실시간 상태)를 함께 표기하세요. 병렬 펌프가 여러 대면
   **실제 가동 중(R-RUN/L-RUN)인 것이 현재 공급원**이고, 정지(L-STOP)인 것은 예비/대기입니다.
   예: "F-6101A/B 상류 = P-6102(R-RUN, 현재 공급) + P-6201(L-STOP, 예비)".
4. `trace_connections` 결과에 없는 장비를 임의로 추가하거나, 있는 분기를 빠뜨리지 마세요. 답변의
   경로 구성은 매번 이 도구 출력과 1:1로 일치해야 합니다.

### category 기준 분리

pid_equipment 테이블의 `category` 열로 물리적 경로와 제어 신호를 구분합니다.

1. **category != '제어'** → 물리적 유체 경로
   - 펌프, 열교환기, 탱크, 밸브, 계기, 필터 등
   - "A → B → C" 흐름 설명에 사용

2. **category = '제어'** → DCS 제어 신호
   - FICQ, LICA, TICA, PICA 등 DCS 제어기
   - from_tag: 물리적 계기 (측정값)
   - to_tag: 제어기 또는 제어 대상 밸브
   - "FT-6118 → FICQ-6118 → FCV-6118" 제어 루프 설명에 사용

### 경로 설명 시 조회 순서

1. **1단계**: `category != '제어'` 행으로 물리적 흐름 설명
2. **2단계**: `category = '제어'` 행 중 `from_tag`가 1단계 결과에 포함되는 것 찾기
3. **3단계**: "FT-6118(유량측정) → FICQ-6118(제어) → FCV-6118(밸브)" 형태로 제어 로직 연결

### 예시: 제품 추출 경로 설명

```sql
-- 1단계: 물리적 경로
SELECT tag_no, from_tag, from_at, to_tag, to_at, role, category
FROM pid_equipment
WHERE tag_no IN ('E-6117','P-6118','FT-6118','FCV-6118','XV-6123','T-6123',...)
ORDER BY tag_no;

-- 2단계: 제어 태그 (from_tag가 1단계 결과에 포함되는 것)
SELECT tag_no, from_tag, from_at, to_tag, to_at, role, category
FROM pid_equipment
WHERE category = '제어'
AND from_tag IN ('FT-6118','P-6118',...);
```

### 주의사항

- 같은 `tag_no`라도 여러 행이 있을 수 있음 (각 행은 서로 다른 유체 경로)
- 예: E-6115A 조회 시 2행 반환 → 행1=스팀 경로, 행2=리보일러 경로
- 설명할 때 "이 장비는 2개 경로가 있음"이라고 명시
- OR 병합된 값("A, B" 같은)은 없음 — 각 행은 단일 경로
- `from_at`, `to_at`은 연결 지점 상세 (예: "C-6111 중상부 제품 노즐")

---

## pid_equipment.tag_dcs — 현장 계기 vs DCS 함수블록 구별

- **tag_dcs = TRUE**: DCS 내부 함수블록 (FIC, TIC, PIC, LIC, FY, TY, PY, LY 등 compound형 포함)
  - 물리 기기 없음. Experion DB 포인트로만 존재
  - 예: FIC-6113(유량제어기), TIC-6201(온도제어기)
- **tag_dcs = FALSE**: 현장 물리 계기 (FT, PT, LT, FCV, PSV, XV 등)
  - P&ID 도면에 기기 심벌로 표시되는 실물. Experion 연결 여부 무관하게 field
  - 예: FT-6113(유량전송기), FCV-6113(제어밸브)

### 쿼리 예시

```sql
-- DCS 태그 수
SELECT COUNT(*) FROM pid_equipment WHERE tag_dcs = TRUE;

-- 현장 계기 목록
SELECT tag_no, instrument_type FROM pid_equipment
WHERE tag_dcs = FALSE AND category = 'instrument';

-- 특정 태그 DCS 여부 확인
SELECT tag_no, tag_dcs, tag_class FROM pid_equipment WHERE tag_no = 'FIC-6113';
```