# 보조운전 (Operation Assistant) — 브레인스토밍

> 2026-05-30, C-6111 PGMEA 측류 추출식 증류탑 기준

## 1. 목표

LLM(MCP) + 실시간 DCS 데이터 + KB(SOP)를 결합하여 운전원의 startup / 생산 순도 확인 / 생산 모드 / shutdown 과정을 **단계별로 보조**하는 UI.

## 2. 핵심 설계 원칙

| 구분 | 처리 방식 | 예시 |
|:----|:---------|:-----|
| **DCS 계측 항목** | 시스템 자동 검증 (`find_tags`/`run_sql`/`query_events`) | Pump 상태, FICQ SP, XV open/close, 온도/압력 |
| **수동 항목** (hand valve, local gauge, visual) | LLM 지시 → **운전원이 "확인완료" 클릭** | "HV-6115 개방하세요" → 버튼 클릭 |
| **계산/분석 항목** | MCP tool + LLM 추론 | 물질수지 검증, 순도 확인, R/P 계산 |

## 3. 시스템 아키텍처

```
┌─────────────────────────────────────────────────────────────┐
│  보조운전 UI (신규 pane ops.html + ops.js)                   │
│  ┌─ sub-tabs: [startup] [verify_purity] [production] [shutdown] │
│  └─ Step progress bar + 단계별 카드 + 확인 버튼               │
└──────────────────┬──────────────────────────────────────────┘
                   │ HTTP (JSON-RPC)
┌──────────────────▼──────────────────────────────────────────┐
│  C# Controller (/api/ops/*)                                 │
│  - GET /api/ops/guide?unit=C-6111&mode=startup&step=1      │
│  - POST /api/ops/confirm { unit, mode, step, feedback }     │
│  - GET /api/ops/state?unit=C-6111                           │
└──────────────────┬──────────────────────────────────────────┘
                   │ IMcpService
┌──────────────────▼──────────────────────────────────────────┐
│  Python MCP Server (server.py)                               │
│  - execute_operation_guide(unit, mode, step, feedback)      │
│  - KB 검색 (rag_query) + 실시간 데이터 검증 (find_tags)     │
│  - 내부 state machine으로 현재 단계 추적                      │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│  Data Sources                                               │
│  ├─ Qdrant (KB — SOP 문서)                                  │
│  ├─ PostgreSQL (DCS 실시간/이력 데이터)                      │
│  └─ vLLM (Qwen3.6-35B-A3B-FP8)                             │
└─────────────────────────────────────────────────────────────┘
```

## 4. SOP 문서 구조 (KB ingest 용)

각 SOP는 JSON 구조의 step 배열로 청킹:

```json
{
  "doc_id": "c-6111-startup-sop",
  "title": "C-6111 Start-up 절차",
  "unit": "C-6111",
  "mode": "startup",
  "steps": [
    {
      "step": 1,
      "title": "전단계 안전 확인",
      "actions": [
        "비상정지 버튼(XV-6123, XV-6124) CLOSE 확인",
        "컬럼 진공압 PI-6111 확인 (~50 torr)"
      ],
      "verification_type": "operator",
      "expected": null
    },
    {
      "step": 2,
      "title": "원료 라인 구성",
      "actions": [
        "HV-6101 개방 (feed line, 수동밸브)",
        "HV-6115 개방 (reflux return, 수동밸브)",
        "HV-6116 개방 (bottom line, 수동밸브)"
      ],
      "verification_type": "operator",
      "expected": null
    },
    {
      "step": 3,
      "title": "원료 공급 펌프 기동 및 유량 설정",
      "actions": [
        "P-6102 R-RUN 전환",
        "FICQ-6101 SP=820 kg/hr 설정"
      ],
      "verification_type": "system",
      "expected": {
        "p-6102.pv": "R-RUN",
        "ficq-6101.pv": { "min": 800, "max": 840 }
      }
    },
    {
      "step": 4,
      "title": "Reboiler 가온",
      "actions": [
        "TICA-6111A SP=81.5°C 설정",
        "Reboiler 응축수 라인 확인"
      ],
      "verification_type": "mixed",
      "system_checks": [
        { "tag": "tica-6111a.pv", "min": 78, "max": 85 }
      ],
      "operator_action": "Reboiler 응축수 드레인 밸브 개방 확인"
    }
  ]
}
```

### 청킹 전략

- 문서 1개 = 1개 unit × 1개 mode (startup/shutdown/production)
- 각 step의 `verification_type`: `operator` | `system` | `mixed`
- `expected` 필드: 자동 검증할 태그명(key)과 기대값(value)
- KB collection: `plant_operation`

## 5. UI 구조 (보조운전 화면)

### 5.1 레이아웃

```
┌─────────────────────────────────────────────────┐
│ [pane-hdr] 보조운전 / C-6111 운전 보조          │
├─────────────────────────────────────────────────┤
│ [mode-tabs]                                     │
│  ● START-UP  ○ 순도 확인  ○ 생산모드  ○ SHUTDOWN │
├─────────────────────────────────────────────────┤
│ [step-progress]                                 │
│  ■■■■□□□□□□□  Step 4/12                        │
│  ●●●●○○○○○○○  33%                               │
├─────────────────────────────────────────────────┤
│ [step-card]                                     │
│  ┌─────────────────────────────────────────┐   │
│  │ Step 4: Reboiler 가온                    │   │
│  │                                         │   │
│  │ □ TICA-6111A SP=81.5°C 설정             │   │
│  │   ✓ PV=79.6°C (설정 중...)              │   │
│  │ □ Reboiler 응축수 드레인 밸브 개방 확인  │   │
│  │   [✔ 확인완료] ← 운전원 클릭             │   │
│  │                                         │   │
│  │ [← 이전 단계]              [다음 단계 →] │   │
│  └─────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│ [참고 정보 패널 - collapsible]                  │
│  - 현재 컬럼 온도 프로파일                       │
│  - 현재 물질수지                                │
│  - 활성 알람                                   │
└─────────────────────────────────────────────────┘
```

### 5.2 sub-tab 구성

| 탭 | mode | 설명 |
|:---|:-----|:------|
| START-UP | `startup` | 초기 기동 → 정상 상태 도달 |
| 순도 확인 | `verify_purity` | 생산 전 물질수지 + 온도 프로파일 검증 |
| 생산모드 | `production` | 정상 운전 중 모니터링 및 미세 조정 |
| SHUTDOWN | `shutdown` | 정지 절차 |

### 5.3 step-card 구성 요소

- Step 번호 + 제목
- Action 항목 리스트 (체크박스 형태)
  - 시스템 자동 확인 항목: ✓ / ✗ 아이콘
  - 운전원 확인 항목: [확인완료] 버튼
- 진행 버튼: [← 이전] [다음 →]
- 참고정보 패널: 현재 공정 데이터 요약

## 6. MCP Tool: `execute_operation_guide`

### Signature

```python
@mcp.tool()
async def execute_operation_guide(
    unit: str,
    mode: str,            # "startup" | "verify_purity" | "production" | "shutdown"
    operator_feedback: str | None = None,
    current_step: int = 1
) -> str:
    """
    KB에서 SOP 조회 → 실시간 데이터 검증 → 다음 action 반환
    """
```

### 동작 흐름

1. KB에서 `unit` + `mode`에 해당하는 SOP 검색
2. `current_step`의 expected 조건을 실시간 데이터로 검증
3. 검증 실패 항목 있으면 → 경고 메시지
4. `operator_feedback`이 있으면 → 현재 step 메모에 기록
5. 다음 step 정보 + 검증 결과 + action 목록을 JSON으로 반환

### 응답 구조

```json
{
  "success": true,
  "unit": "C-6111",
  "mode": "startup",
  "current_step": 4,
  "total_steps": 12,
  "title": "Reboiler 가온",
  "actions": [
    {
      "description": "TICA-6111A SP=81.5°C 설정",
      "type": "system",
      "status": "in_progress",
      "detail": "PV=79.6°C, SP=81.5°C (설정 중...)"
    },
    {
      "description": "Reboiler 응축수 드레인 밸브 개방 확인",
      "type": "operator",
      "status": "pending",
      "detail": null
    }
  ],
  "all_verified": false,
  "can_proceed": false
}
```

## 7. C# Controller: `/api/ops/*`

| Route | Method | Description |
|:------|:-------|:------------|
| `/api/ops/guide` | GET | unit + mode + step → SOP 조회 + 검증 |
| `/api/ops/confirm` | POST | 운전원 확인 feedback 전송 |
| `/api/ops/state` | GET | 현재 진행 상태 조회 (재접속 등) |
| `/api/ops/reset` | POST | 진행 상태 초기화 |

## 8. 프론트엔드 구현 순서

| 단계 | 파일 | 내용 |
|:----:|:-----|:------|
| 1 | `index.html` | nav item #18 + pane + script 추가 |
| 2 | `panes/ops.html` | UI 레이아웃 (sub-tabs, progress, step-card) |
| 3 | `css/ops.css` | 전용 스타일 |
| 4 | `js/ops.js` | `paneInit.ops` — 탭 전환, step 렌더링, confirm 버튼 |
| 5 | `server.py` | `execute_operation_guide` MCP tool |
| 6 | C# Controller | `/api/ops/*` 라우트 |
| 7 | SOP 문서 | KB ingest 용 청킹 |

## 9. 향후 확장

- **다중 unit 지원**: C-6111 외 C-6211 등으로 확장
- **에이전트 모드**: LLM이 조건 만족 시 자동으로 다음 단계 진행
- **히스토리 트래킹**: 각 startup/shutdown 이력 DB 저장 → 패턴 분석
- **Alarm 연동**: 비정상 상황 감지 시 자동 shutdown 권고

## 10. 구현 전 사전 검증 항목

> ⚠️ 현재 이 문서는 **아이디어 스케치(브레인스토밍) 수준**이다. 아래 항목에 대한 검증과 사전 작업 없이 구현에 들어갈 경우, 실제 플랜트와의 정합성 문제로 재작업이 발생한다.

### 10.1 SOP JSON 구조 검증

| 검증 항목 | 상세 | 확인 방법 |
|:----------|:-----|:---------|
| step 필드 적절성 | title/actions/verification_type/expected만으로 모든 절차 표현 가능? | 실제 절차서 1개를 JSON으로 변환해보기 |
| 중첩 조건 표현 | "A 또는 B 상태" 같은 OR 조건 필요? `expected` 값의 표현력 | 태그 상태가 binary가 아닌 경우 (범위, enum) |
| 분기/조건부 step | 특정 조건에서만 수행하는 step 처리 | 예: "진공압이 50 torr 이하이면..." |
| 병렬 step | 동시에 수행 가능한 여러 action | 정렬 순서 강제 vs 자유로운 병렬 |
| 비정상 경로 | 정상 절차 외의 예외 처리 (재시도, 우회) | step 실패 시 fallback 절차 |

### 10.2 DCS 태그 계측 범위 검증

| 검증 항목 | 상세 | 확인 방법 |
|:----------|:-----|:---------|
| 검증 가능한 태그 목록 | SOP의 `expected` 조건에 사용할 태그들이 실제 realtime_table에 존재? | `find_tags` + `v_tag_summary` |
| 태그 데이터 타입 | digital(R-RUN/L-STOP) / analog(PV float) / enum 구분 | 각 태그별 `.pv` 값 형식 확인 |
| 계측 불가 항목 | 수동밸브, local gauge, visual check — 태그 없음 | SOP에서 `operator` 타입으로만 처리 |
| 신뢰도 | 태그 값이 0 또는 null인 경우 (고장/fault) | TI-6111A(PV=0), LI-6128(PV=0) 같은 사례 |

**C-6111 예비 조사 결과 (2026-05-30):**

| 태그 | 계측됨 | 데이터형 | 비고 |
|:----|:------:|:--------|:------|
| ficq-6101.pv | ✅ | analog | Feed SP=820 ✓ |
| ficq-6113.pv | ✅ | analog | Reflux SP=350 ✓ |
| ficq-6118.pv | ✅ | analog | Product SP=777.2 ✓ |
| pi-6111.pv | ✅ | analog | Vacuum ~48.5 torr ✓ |
| tica-6111a.pv | ✅ | analog | Reboiler SP=81.5 ✓ |
| ti-6111a.pv | ❌ | analog | PV=0 → 고장 의심 |
| ti-6111b/c/d.pv | ✅ | analog | Column profile ✓ |
| li-6128.pv | ❌ | analog | Scrubber level PV=0 → 미계측 |
| p-6102.pv | ✅ | digital? | R-RUN / L-STOP (상태 확인 필요) |
| xv-6123.pv | ? | digital | OPEN/CLOSE (태그 형식 확인 필요) |

### 10.3 Mode 분류 검증

| Mode | C-6111 적용 여부 | 비고 |
|:-----|:--------------:|:------|
| **startup** | ⬜ | 최초 기동 절차 존재? SIP(Startup Inspection Plan) 보유? |
| **verify_purity** | ⬜ | 생산 전 순도 분석 절차? off-spec 시 재순환 루틴? |
| **production** | ⬜ | 정상 운전 중 모니터링 항목? 조정 주기? |
| **shutdown** | ⬜ | 정지 절차? emergency shutdown과 normal shutdown 분리? |
| **grade_change** | ⬜ | 제품 grade 전환 절차 필요한가? (C-6111 연속식 단일 제품?) |
| **emergency** | ⬜ | Alarm/interlock 조건 발동 시 대응 절차? |

### 10.4 운전원 피드백 종류

| 피드백 | 의미 | UI 액션 |
|:-------|:-----|:---------|
| ✅ **확인완료** | 지시받은 수동 조작 완료 | 다음 step 진행 가능 |
| ⏸️ **보류** | 조건 미충족으로 일단 대기 | step 유지, 진행 불가 |
| ⚠️ **이상있음** | 예상과 다른 상태 발견 | LLM이 재확인/대안 제시 |
| 💬 **메모** | 자유 텍스트 기록 (운전일지) | step 로그에 기록 |

### 10.5 SOP 문서 소스 현황

| 항목 | 상태 | 액션 |
|:-----|:----|:------|
| C-6111 startup 절차서 | ❓ | 보유 여부 확인 필요 |
| C-6111 shutdown 절차서 | ❓ | 보유 여부 확인 필요 |
| 운전 체크리스트 양식 | ❓ | 기존 양식이 있다면 JSON 구조 맞출 기준 |
| P&ID (PFD) | ✅ | 이미 추출 완료 (node_map_master) |
| 물질수지/에너지수지 | ✅ | 오늘 작성한 공식 문서 |

### 10.6 사전 작업 목록

| 우선순위 | 작업 | 설명 | 담당 |
|:--------:|:-----|:------|:-----|
| **P0** | SOP 문서 확보 | C-6111 startup/shutdown 절차서 원본 수집 | 운전원/공정 |
| **P0** | 태그 매핑 | SOP의 모든 valve/기기명을 실제 DCS 태그명에 매핑 | 공정+개발 |
| **P0** | C-6111 startup 시나리오 시뮬 | JSON SOP 1건을 직접 작성해보며 필드 적절성 검증 | 개발 |
| **P1** | DCS 태그 형식 확인 | digital 태그의 .pv 값 형식 (R-RUN/L-STOP 등) | 개발 |
| **P1** | 예외 처리 정의 | 각 step별 실패 시나리오 및 fallback 정의 | 공정 |
| **P1** | UI 프로토타입 | panes/ops.html mockup 제작 (하드코딩 step) | 개발 |
| **P2** | MCP tool 구현 | `execute_operation_guide` server.py에 추가 | 개발 |
| **P2** | 피드백 타입 시험 | 운전원 확인 → 다음 step 전환까지 end-to-end | 통합 |

### 10.7 구현 원칙

1. **SOP 구조는 실제 절차서를 JSON으로 변환해보기 전에 확정 금지** — 필드 부족/과잉이 발생할 수 있음
2. **하드코딩 mock으로 UI 먼저 검증** — MCP tool 구현 전에 pane HTML+JS를 mock data로 동작시켜 UX 확인
3. **P0 검증 완료 후 P1, P1 완료 후 P2 진행** — 병렬 가능한 항목은 병렬
4. **처음부터 모든 mode를 만들지 않음** — startup만 먼저 구현, 다른 mode는 startup 구조 검증 후 확장

---

## 11. 참고 문서

- `docs/측류추출식-통합유량설정공식.md` — C-6111 물질수지/환류/온도보정/V_loss 공식
- `docs/보조운전-브레인스토밍.md` (본 문서)