MMCL/docs/mmcl_master_plan.md

MMCL (Machine Monitoring Control for LLM) 통합 프로젝트 기획 및 설계서

Note

본 문서는 지금까지 논의되고 설계된 MMCL 프로젝트의 기획 배경, 아키텍처, 데이터베이스 스키마, 핵심 로직 및 초기 산출물을 총괄하여 정리한 마스터 기획서입니다. 본 프로젝트는 실제 장비 납품 전 전체적인 데이터 흐름과 LLM 연동의 가능성을 타진하기 위한 PoC (Proof of Concept) 목업(Mockup) 프로젝트입니다.

---

1. 프로젝트 개요

• 프로젝트명: MMCL (Machine Monitoring Control for LLM) Mockup System
• 프로젝트 목표:
  1. 기계/설비에 부착된 NILM(비침입형 부하 모니터링) 장비로부터 실시간 측정 데이터를 수집 및 저장.
  2. 기구축된 Mistral LLM과 연동하여 사용자가 자연어로 장비의 상태를 파악.
  3. LLM 판단 또는 사용자 자연어 명령에 따라 설비의 경광등(Warning Light) 상태를 간접 제어.
• 핵심 컨셉: 직접적인 하드웨어 API 호출 방식이 아닌, 데이터베이스(MariaDB)의 특정 상태(Target) 필드를 조작하고 중간의 Agent가 이를 감지하여 물리적으로 동기화하는 비동기 핸드쉐이크(Handshake) 방식을 채택하여 결합도를 낮추고 시스템 안정성을 높입니다.

---

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

graph TD
    subgraph Equipment Layer
        MACH[설비/기계]
        NILM_Equip[NILM 측정 센서]
        Warning_Light[경광등 모듈]
        MACH --- NILM_Equip
        MACH --- Warning_Light
    end

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

    subgraph Database Layer (MariaDB)
        DB_Master[(dev/pos/type/status_info)]
        DB_Sensor[(sensor_info)]
        DB_Log[(sensor_history_log)]
    end

    subgraph Backend API (Python/FastAPI)
        API_Server[FastAPI Server]
        LLM[Mistral LLM]
    end

    subgraph Frontend Web
        UI[React/Vite Dashboard]
    end

    %% Data Flow
    NILM_Equip -- "1. MQTT Publish" --> MQTT_Broker
    MQTT_Broker -- "2. Subscribe" --> NILM_Agent
    NILM_Agent -- "3. 실시간 데이터 Update & Log Insert" --> DB_Sensor
    NILM_Agent -.-> DB_Log
    
    UI -- "4. 자연어 질의/명령" --> API_Server
    API_Server <--> LLM
    
    API_Server -- "5. 제어 '목표' 상태 Update" --> DB_Sensor
    
    LED_Agent -- "6. 목표 상태 감지 (Polling)" --> DB_Sensor
    LED_Agent -- "7. 물리적 LED 제어" --> Warning_Light
    LED_Agent -- "8. 제어 완료 '현재' 상태 Update" --> DB_Sensor
    
    API_Server -. "9. Agent 완료 확인 (비동기 대기)" .-> DB_Sensor
    API_Server -- "10. '적용 완료' 자연어 응답" --> UI

---

3. 핵심 모듈 및 로직 정의

3.1. NILM 에이전트 (데이터 수집 및 로깅)

• NILM 장비가 전송하는 데이터를 수신(MQTT)하여 데이터베이스를 실시간으로 최신화합니다.
• sensor_info 테이블의 value_chX... 컬럼을 갱신하여 시스템 전반에 최신 상태를 알리고, 동시에 sensor_history_log 테이블에 데이터를 Insert하여 시계열 이력을 보관합니다. 이를 통해 향후 대시보드에서 전력 사용량 트렌드 분석 등이 가능해집니다.

3.2. LLM 자연어 인터페이스 및 백엔드 서버

• FastAPI를 활용하여 프론트엔드와 LLM, DB 사이의 통신을 중계합니다.
• 사용자가 "에러 발생했어, 1번 장비 불빛 바꿔"와 같은 자연어를 입력하면, 백엔드가 Mistral LLM을 통해 사용자 의도를 분석하고 제어할 목표 상태(예: RED)를 결정합니다.

3.3. 비동기 핸드쉐이크 (Handshake) 제어 및 검증

• 목표 상태 지시: 백엔드 서버는 sensor_info의 target_chX_statusID 필드에 변경하고자 하는 목표 상태값을 기록합니다.
• 에이전트 동기화: 경광등 Agent가 주기적으로 DB를 읽어 target_... 값과 value_...(현재 물리적 상태) 값이 다름을 감지하면 실제 하드웨어를 제어합니다. 제어가 정상적으로 끝나면 value_... 값을 target_...과 동일하게 업데이트합니다.
• 완료 피드백 검증: 백엔드 서버는 지시 후 대기 루프(Polling)를 돌며 value_... 값이 변경되었는지 확인합니다. 값이 목표와 일치하는 것을 확인한 뒤에야 사용자 UI 화면으로 "제어가 정상적으로 완료되었습니다"라는 메시지를 반환합니다.

---

4. 데이터베이스 테이블 구조 요약

기존에 설계된 설비 테이블(dev_info) 구조를 바탕으로 MMCL의 핵심 요구사항을 확장 통합한 총 7개의 테이블 구성입니다.

테이블명	주요 역할 및 기능
dev_info	장비(NILM, 경광등)가 부착된 물리적 설비 및 기계의 마스터 정보 및 센서 식별번호 매핑.
sensor_info	각 센서의 실시간 최신 계측값(Current) 및 핸드쉐이크 로직을 위한 목표 상태(Target) 값 보관.
sensor_history_log	(신규) sensor_info 갱신 시 해당 시점의 측정값을 보관하는 시계열 이력 저장소.
pos_info	기계가 설치된 위치 및 구역 마스터 정보.
type_info	센서 유형 코드 정의 (1: NILM, 2: 경광등).
status_info	0(OFF), 1(ON) 등 시스템 내 공통 상태 코드 매핑.
nilm_init_value	설비별 NILM 측정의 기준이 되는 초기 세팅값.

---

5. 프로젝트 초기 산출물(뼈대 코드) 내역

위 아키텍처를 증명하고 빠르게 테스트해 볼 수 있도록 1차 작업 완료된 뼈대(Scaffolding) 코드 구조입니다.

1. 통합 DB 쿼리 (database/schema.sql): 통합된 7개 테이블 DDL 및 최초 기동용 테스트 더미 데이터.
2. 에이전트 모듈 (agents/):
   • nilm_agent_mock.py: NILM 가상 데이터 갱신 및 시계열 로깅 에이전트.
   • warning_light_agent.py: 목표값(Target)을 감지하고 동기화(Current 갱신)하는 핸드쉐이크 에이전트.
3. 백엔드 모듈 (backend/main.py): 핸드쉐이크 대기 로직 및 LLM 텍스트 룰 처리가 포함된 FastAPI 기반 API 서버.
4. 웹 대시보드 (frontend/): React + Vite 기반으로 구축된, Glassmorphism 디자인 패턴을 적용한 현대적 감각의 실시간 모니터링 & 채팅 화면.