MMCL/SOURCE/docs/MMCL 실제 구현 및 개발 착수 계획 (V4)_implementation_plan.md

# MMCL 실제 구현 및 개발 착수 계획 (V4)

프론트엔드 웹 개발이 분리되어 진행됨에 따라, 백엔드 서버 및 하드웨어 에이전트(Delphi, Python)의 실제 구현 코드 작성과 API 연동 명세서 공유를 위한 세부 작업 계획입니다.

## User Review Required
> [!IMPORTANT]
> 아래 명시된 **개발 산출물 내역(API 문서, 파이썬 서버, 델파이 NILM 에이전트, LED 에이전트)**이 요구사항과 일치하는지 확인해 주세요. 특히 NILM 에이전트를 **Delphi(FireDAC 및 MQTT 라이브러리 활용)**로 작성하는 방향이 맞는지 검토 부탁드립니다. 
> 승인해 주시면 즉시 문서를 추출하고 전체 코드를 작성하겠습니다.

## Proposed Changes

### 1. 웹 개발자 공유용 API 프로토콜 문서
#### [NEW] `docs/api_protocol_spec.md`
- 웹 프론트엔드 파트와 파이썬 서버가 통신하기 위한 REST API 규약 명세서.
- `GET /api/machines` : 장비(기계)의 현재 전력 사용량 및 경광등 상태 조회.
- `POST /api/chat_control` : 사용자의 자연어 제어 명령(Message) 전송 및 핸드쉐이크 대기 후 결과 응답.
- 각 API의 Request/Response JSON 구조 및 상태(Error) 코드 명세.

### 2. 리눅스 서버 (Mistral LLM 연동 파이썬 서버)
#### [MODIFY] `backend/main.py`
- 기존의 단순 단어 매칭 Mock 로직을 제거합니다.
- 로컬 환경(예: Ollama 또는 vLLM)에 설치된 **Mistral LLM**의 API(localhost)로 사용자 프롬프트를 전송하여, LLM이 직접 의도(제어 대상 색상 등)를 분석 및 추출하도록 구현합니다.
- 추출된 목표 상태를 DB(`sensor_info`의 `target_...`)에 업데이트하고, Agent의 하드웨어 제어가 끝날 때까지 대기(Polling)하는 핸드쉐이크 로직.

### 3. NILM MQTT Agent (Delphi)
#### [NEW] `agents/delphi_nilm_agent/NilmMQTT_Agent.dpr` & `Main.pas`
- **Delphi (RAD Studio)** 환경에서 구동되는 백그라운드 콘솔(또는 서비스) 애플리케이션 뼈대 코드.
- 일반적인 MQTT 클라이언트 라이브러리를 사용하여 브로커에 Subscribe(구독) 처리.
- **FireDAC**(`TFDConnection`, `TFDQuery`)을 사용하여 MariaDB(MySQL)에 연결.
- 메시지 수신 이벤트 발생 시 `sensor_info`를 UPDATE(현재 상태 갱신)하고 `sensor_history_log`에 INSERT(이력 적재) 하는 로직 구현.

### 4. 경광등(LED) 제어 Agent
#### [NEW] `agents/led_agent.py` (Python)
- 라즈베리파이 등 리눅스/PC 환경 구동을 가정한 파이썬 에이전트.
- DB를 지속적으로 감시하여 `target_...` 값이 `value_...` 값과 달라지면 하드웨어 릴레이/GPIO 제어(또는 시리얼 통신)를 수행합니다.
- 제어 완료 후 DB에 `value_...` (현재 상태) 값을 업데이트하여 백엔드에 핸드쉐이크 완료 신호를 보냅니다.

## Verification Plan
1. API 명세서가 웹 개발자가 바로 개발에 착수할 수 있도록 구체적이고 명확한지 확인.
2. 파이썬 백엔드가 실제 Mistral LLM으로 HTTP 요청을 보내는 로직이 정상적으로 작성되었는지 코드 리뷰.
3. Delphi 코드가 FireDAC 기반 DB 연결과 MQTT 수신 이벤트를 표준적인 Pascal 문법으로 준수하여 작성되었는지 검증.