# MMCL (Machine Monitoring Control 소포 LLM) 목업 프로젝트 기획서

> [!NOTE]
> 본 문서는 실제 장비 납품이 아닌, 전체적인 아키텍처의 가능성을 타진하고 흐름을 테스트하기 위한 **PoC (Proof of Concept) 목업 프로젝트**용 기획서입니다.

## 1. 프로젝트 개요 (Overview)

* **프로젝트명**: MMCL (Machine Monitoring Control for LLM) Mockup
* **목표**: NILM(비침입형 부하 모니터링) 데이터를 수집하고, 기구축된 Mistral LLM과 연동하여 자연어로 장비 상태를 파악하며, 장비의 경광등 상태를 제어하는 전체 시스템 구조 설계 및 구현.
* **핵심 컨셉**: NILM과 DB 사이에 Agent를 배치하고, 하드웨어 직접 제어를 배제하여 **데이터베이스(MariaDB)의 특정 상태 필드를 조작**하고 Agent가 이를 동기화함으로써 제어를 시뮬레이션합니다.

## 2. 주요 기능 요구사항 (Key Requirements)

### 2.1. 데이터 수집 및 통신 에이전트 (MQTT & Agents)
* **NILM MQTT 통신**: NILM 장비는 MQTT 통신을 이용해 장비의 전력, 전류 등 상태 정보를 브로드캐스트합니다.
* **NILM Agent**: MQTT 브로커를 구독(Subscribe)하여 데이터를 수신하고, 이를 파싱해 실시간으로 MariaDB에 저장(Insert)합니다.
* **경광등 Agent**: DB의 경광등 제어 상태값을 지속적으로 확인(또는 이벤트 수신)하여, 장비 옆에 부착된 실제/모의 경광등의 불빛 상태를 동기화합니다. **물리적 제어 로직 완료 후 DB에 완료 상태를 기록하여 백엔드에 알립니다.**

### 2.2. 상태 및 제어 데이터베이스 (MariaDB)
* **모니터링 데이터**: NILM 장비에서 넘어온 측정값을 저장하는 시계열 특성의 테이블.
* **경광등 상태 데이터**: 장비 상태에 따른 경광등 색상을 제어하기 위한 테이블.
  * 🔴 **적색 (Red)**: 에러 상태
  * 🟡 **노란색 (Yellow)**: 대기 상태
  * 🟢 **초록색 (Green)**: 작동 상태

### 2.3. Python 백엔드 서버 및 Mistral LLM 연동
* **Python API 서버**: 파이썬으로 구동되는 서버를 구축하여 프론트엔드와 LLM/DB 간의 통신(자연어 질의응답 및 제어)을 중계합니다.
* **Mistral LLM**: 로컬에 설치된 Mistral LLM을 호출하여 사용자의 자연어를 분석하고 SQL 변환 또는 룰 판단을 수행합니다.
* **제어 결과 검증 로직 (Handshake Validation)**: 
  - 사용자가 자연어로 제어를 지시하면 파이썬 서버가 DB에 **목표 상태(Target Status)**를 업데이트하고 대기합니다.
  - `경광등 Agent`가 이를 감지하여 실제 경광등의 상태를 변경한 뒤, DB에 **제어 완료(Current Status 반영)** 상태를 업데이트합니다.
  - 파이썬 서버는 이 완료 정보를 확인한 후에야 비로소 "정상적으로 적용이 완료되었습니다." 와 같은 자연어 응답을 사용자에게 리턴합니다.

---

## 3. 시스템 아키텍처 (System Architecture)

> [!TIP]
> 파이썬 서버와 경광등 Agent 간의 확실한 상태 동기화를 위해, 비동기 폴링(Polling) 방식 또는 데이터베이스 이벤트를 통한 대기(Wait) 로직이 적용됩니다.

```mermaid
graph TD
    subgraph Equipment Layer
        NILM_Equip[NILM 장비]
        Warning_Light[장비 경광등]
    end

    subgraph Messaging & Agents
        MQTT_Broker((MQTT Broker))
        NILM_Agent[NILM Agent]
        LED_Agent[경광등 Agent]
    end

    subgraph Database MariaDB
        DB_NILM[(NILM Status Table)]
        DB_LED[(Warning Light Table)]
    end

    subgraph Backend Server
        Python_API[Python Server API]
        LLM_Agent[Mistral LLM]
    end

    subgraph User Interface
        UI[Web Dashboard / Chat]
    end

    %% Data Flow
    NILM_Equip -- "1. MQTT Publish" --> MQTT_Broker
    MQTT_Broker -- "2. Subscribe" --> NILM_Agent
    NILM_Agent -- "3. Insert 실시간 데이터" --> DB_NILM
    
    UI -- "4. 자연어 제어 명령" --> Python_API
    Python_API <--> LLM_Agent
    
    Python_API -- "5. Update 목표 상태 설정 및 대기" --> DB_LED
    
    LED_Agent -- "6. Select 목표 상태 감지" --> DB_LED
    LED_Agent -- "7. 물리적 제어 수행" --> Warning_Light
    LED_Agent -- "8. Update 제어 완료(현재 상태) 기록" --> DB_LED
    
    Python_API -. "9. 완료 기록 확인 (Polling/Event)" .-> DB_LED
    Python_API -- "10. '적용완료' 응답 반환" --> UI
```

---

## 4. 데이터베이스 스키마 설계 (Draft)

### 4.1. 장비 상태 로그 테이블 (`nilm_status_log`)

| 컬럼명 | 데이터 타입 | 설명 | 비고 |
|---|---|---|---|
| `id` | INT (PK) | 고유 식별자 | Auto Increment |
| `timestamp` | DATETIME | 측정 시간 | |
| `device_id` | VARCHAR | 대상 장비 식별자 | 예: "MACHINE_01" |
| `active_power` | FLOAT | 유효 전력 (W) | |
| `current` | FLOAT | 전류 (A) | |
| `voltage` | FLOAT | 전압 (V) | |

### 4.2. 경광등 제어 테이블 (`warning_light_control`)
파이썬 서버와 경광등 Agent 간의 상태 동기화(핸드쉐이크)를 위해 상태 필드를 `target_status`와 `current_status`로 분리하여 설계합니다.

| 컬럼명 | 데이터 타입 | 설명 | 비고 |
|---|---|---|---|
| `device_id` | VARCHAR (PK)| 제어 장비 식별자 | 예: "MACHINE_01_LIGHT" |
| `target_status` | VARCHAR | 파이썬 서버가 지시한 목표 상태 | "RED", "YELLOW", "GREEN" |
| `current_status` | VARCHAR | Agent가 물리적 적용을 완료한 현재 상태 | "RED", "YELLOW", "GREEN" |
| `last_updated_by` | VARCHAR | 마지막 제어 주체 | "USER", "LLM_RULE" |
| `updated_at` | DATETIME | 마지막 변경 시간 | |

> [!IMPORTANT]
> `target_status`와 `current_status`가 다를 경우, 시스템은 제어 명령이 내려졌으나 아직 하드웨어에 적용되지 않은 **진행 중(Pending)** 상태로 인식합니다. 두 값이 같아지면 제어가 **완료(Completed)**된 것으로 간주합니다.

---

## 5. 예상 시나리오 (User Story)

1. **데이터 적재 시작**: NILM 장비가 MQTT로 데이터를 쏘면, `NILM Agent`가 이를 받아 MariaDB `nilm_status_log` 테이블에 Insert 합니다.
2. **자연어 제어 명령**: 사용자가 채팅 인터페이스에 "1번 장비를 작동상태(초록색)로 변경해줘"라고 명령합니다.
3. **서버의 제어 지시 및 대기**: 
    - 파이썬 서버(LLM 연동)가 DB의 `target_status` 필드를 `GREEN`으로 Update 합니다.
    - 서버는 `current_status` 필드값이 `GREEN`으로 바뀔 때까지 비동기 폴링 방식으로 대기합니다.
4. **Agent 물리 제어 및 동기화**: 
    - `경광등 Agent`가 DB를 주기적으로 확인하여 `target_status`(`GREEN`)와 `current_status`(기존 상태)가 다름을 감지합니다.
    - 실제 경광등의 불빛을 초록색으로 물리적으로 변경합니다.
    - 변경 완료 후, `경광등 Agent`는 DB의 `current_status`를 `GREEN`으로 Update 하여 완료를 알립니다.
5. **서버 최종 확인 및 응답**: 
    - 대기 중이던 파이썬 서버가 `current_status`가 `GREEN`으로 변경된 것을 데이터베이스에서 확인합니다.
    - 프론트엔드로 "정상적으로 장비를 작동상태(초록색)로 변경 완료했습니다." 라고 자연어 결과를 리턴합니다.