# MMCL 프로젝트 API 연동 명세서

웹 프론트엔드 파트와 파이썬 백엔드 서버 간의 REST API 통신 규약입니다.

## 기본 정보
- **Base URL**: `http://<서버IP>:8000/api`
- **Content-Type**: `application/json`
- **CORS 설정**: 허용되어 있음

---

## 1. 장비 목록 및 상태 조회 (GET)
대시보드에 표출할 전체 기계(장비)의 전력량, 경광등 상태 정보를 실시간으로 가져옵니다. 프론트엔드에서 주기적으로(예: 1~2초 간격) Polling 해야 합니다.

- **URL**: `/machines`
- **Method**: `GET`
- **Request Body**: 없음
- **Response**: Array of Objects
```json
[
  {
    "id": "D_CNC_01",
    "machine_name": "CNC 선반 1호기",
    "location": "A동 1구역",
    "latest_power": 450.5,
    "light_status": "YELLOW",
    "target_light_status": "YELLOW"
  }
]
```
- **데이터 설명**:
  - `latest_power`: 해당 기계에 매핑된 NILM 센서의 가장 최근 채널1 전력(W). (센서 값이 없을 경우 null)
  - `light_status`: 에이전트가 실제 장비에 적용 완료한 경광등의 **현재 상태**. (RED / YELLOW / GREEN / OFF)
  - `target_light_status`: 파이썬 서버(또는 LLM)가 변경을 지시하여 아직 반영되지 않았거나 반영 중인 **목표 상태**.

---

## 2. 자연어 제어 명령 전송 (POST)
사용자의 자연어 메시지를 전송하여 LLM 분석을 의뢰하고, 분석 결과에 따른 경광등 제어 처리가 "하드웨어단까지 적용 완료" 될 때까지 서버에서 비동기 대기 후 응답을 줍니다. 대기 시간이 있으므로 프론트엔드에서는 로딩(Spinner) 처리가 필수적입니다.

- **URL**: `/chat_control`
- **Method**: `POST`
- **Request Body**:
```json
{
  "message": "에러가 발생했으니 1번 장비 불빛 빨간색으로 바꿔줘",
  "machine_id": "D_CNC_01"
}
```
- **Response (성공, 200 OK)**:
```json
{
  "reply": "[LLM 응답] 정상적으로 장비를 RED 상태로 변경 완료했습니다."
}
```
- **Response (실패/에러)**:
  - `400 Bad Request` : 필수 파라미터 누락
  - `500 Internal Server Error` : LLM 분석 실패 또는 DB 통신 에러
  - `504 Gateway Timeout` : Agent가 제어 명령을 하드웨어에 적용하는데 지정된 시간(약 10~15초)을 초과함.