# MMCL 파이썬 백엔드 API 명세서 (API Specification)

본 문서는 FastAPI로 구축된 MMCL(Machine Monitoring Control for LLM) 백엔드 서버의 통신 규약을 정의합니다.

---

## 1. 설비 목록 및 상태 조회
* **URL**: `/api/machines`
* **Method**: `GET`
* **설명**: 데이터베이스에 등록된 전체 설비 목록과 각 설비의 현재 전력량, 경광등 현재 상태(value) 및 목표 상태(target)를 조회합니다.

**[Response 예시]**
```json
[
  {
    "id": "dev1",
    "machine_name": "프레스기 A",
    "location": "공장 1동",
    "latest_power": 120.5,
    "led_green": 1,
    "led_yellow": 0,
    "led_red": 0,
    "t_green": 1,
    "t_yellow": 0,
    "t_red": 0,
    "light_status": "GREEN",
    "target_light_status": "GREEN"
  }
]
```

---

## 2. LLM 자연어 기반 경광등 제어
* **URL**: `/api/chat_control`
* **Method**: `POST`
* **설명**: 사용자의 자연어 명령을 입력받아 로컬 Mistral LLM이 제어 의도(색상: RED, YELLOW, GREEN)를 분석한 뒤, DB의 목표 상태(target_status)를 업데이트합니다. 
  "빨간색, 노란색 켜줘"와 같이 두 개 이상의 다중 색상 제어 명령도 배열 형태로 동시 처리가 가능합니다.
  이후 하드웨어 에이전트(델파이 클라이언트 등)가 상태를 변경할 때까지 대기(최대 15초)하다가 결과를 반환합니다.

**[Request Body]** `application/json`
```json
{
  "message": "장비에 에러가 발생했어. 경광등 빨간색, 노란색 켜줘!",
  "machine_id": "dev1"
}
```

**[Response 예시 - 성공 시]**
```json
{
  "reply": "[LLM] 명령이 승인되었습니다. 하드웨어 경광등이 RED, YELLOW 상태로 변경 완료되었습니다."
}
```

**[Response 예시 - 의도 파악 실패 시 / 실패 시]**
```json
{
  "reply": "[LLM] 전달하신 메시지에서 제어할 경광등 색상 명령을 파악하지 못했습니다."
}
```
* **참고**: 상태 확인 및 제어 성공/실패 등 모든 API 응답은 `{"reply": "메세지"}` 포맷으로 일관성 있게 반환됩니다.

---

## 3. AI 제어 로그 조회
* **URL**: `/api/ai_control_logs`
* **Method**: `GET`
* **설명**: LLM을 통해 실행된 설비/LED 제어 이력을 최신순으로 50건 조회합니다. (프론트엔드의 'AI 제어 로그' 화면용)

**[Response 예시]**
```json
[
  {
    "log_id": 1,
    "req_text": "장비에 에러가 발생했어. 경광등 빨간색 켜줘!",
    "target_val": "RED",
    "created_at": "2026-07-21T15:00:00",
    "dev_name": "프레스기 A"
  }
]
```

---

## 4. 알림 (이벤트 로그) 조회
* **URL**: `/api/event_logs`
* **Method**: `GET`
* **설명**: 설비의 에러 및 이벤트 발생 이력을 최신순으로 50건 조회합니다. (프론트엔드의 '알림(이벤트 로그)' 화면용)

**[Response 예시]**
```json
[
  {
    "event_id": 1,
    "event_type": "POWER_ANOMALY",
    "status": "RESOLVED",
    "occurred_at": "2026-07-21T14:30:00",
    "resolved_at": "2026-07-21T14:45:00",
    "dev_name": "프레스기 A"
  }
]
```