MMCL/SOURCE/docs/api_protocol_spec.md

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

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

{
  "message": "에러가 발생했으니 1번 장비 불빛 빨간색으로 바꿔줘",
  "machine_id": "D_CNC_01"
}

• Response (성공, 200 OK):

{
  "reply": "[LLM 응답] 정상적으로 장비를 RED 상태로 변경 완료했습니다."
}

• Response (실패/에러):
  • 400 Bad Request : 필수 파라미터 누락
  • 500 Internal Server Error : LLM 분석 실패 또는 DB 통신 에러
  • 504 Gateway Timeout : Agent가 제어 명령을 하드웨어에 적용하는데 지정된 시간(약 10~15초)을 초과함.