104 lines
3.0 KiB
Markdown
104 lines
3.0 KiB
Markdown
# 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"
|
|
}
|
|
]
|
|
```
|