MMCL/docs/MMCL_API_Spec.md

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

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

---

1. 설비 목록 및 상태 조회

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

[Response 예시]

[
  {
    "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

{
  "message": "장비에 에러가 발생했어. 경광등 빨간색, 노란색 켜줘!",
  "machine_id": "dev1"
}

[Response 예시 - 성공 시]

{
  "reply": "[LLM] 명령이 승인되었습니다. 하드웨어 경광등이 RED, YELLOW 상태로 변경 완료되었습니다."
}

[Response 예시 - 의도 파악 실패 시 / 실패 시]

{
  "reply": "[LLM] 전달하신 메시지에서 제어할 경광등 색상 명령을 파악하지 못했습니다."
}

• 참고: 상태 확인 및 제어 성공/실패 등 모든 API 응답은 {"reply": "메세지"} 포맷으로 일관성 있게 반환됩니다.

---

3. AI 제어 로그 조회

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

[Response 예시]

[
  {
    "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 예시]

[
  {
    "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"
  }
]