caadiq
c7b0a51924
- uploads playlist ID를 Redis에 영구 캐싱 (불변값) - 일일 API 사용량 6,480 → 4,320 units (33% 절감) - 문서 업데이트 (컨테이너 분리 구조, X source.name 빈 문자열) - CLAUDE.md에 문서 업데이트 필수 안내 추가 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
191 lines
3.1 KiB
Markdown
191 lines
3.1 KiB
Markdown
# API 명세
|
|
|
|
Base URL: `/api`
|
|
|
|
## 인증
|
|
|
|
### POST /auth/login
|
|
로그인 (JWT 토큰 발급)
|
|
|
|
### GET /auth/me
|
|
현재 사용자 정보 (인증 필요)
|
|
|
|
---
|
|
|
|
## 멤버
|
|
|
|
### GET /members
|
|
멤버 목록 조회
|
|
|
|
### GET /members/:id
|
|
멤버 상세 조회
|
|
|
|
---
|
|
|
|
## 앨범
|
|
|
|
### GET /albums
|
|
앨범 목록 조회
|
|
|
|
### GET /albums/:id
|
|
앨범 상세 조회
|
|
|
|
---
|
|
|
|
## 일정
|
|
|
|
### GET /schedules
|
|
일정 조회
|
|
|
|
**Query Parameters:**
|
|
- `year`, `month` - 월별 조회 (필수, search 없을 때)
|
|
- `search` - 검색어 (Meilisearch 사용)
|
|
- `offset`, `limit` - 페이징
|
|
|
|
**월별 조회 응답:**
|
|
```json
|
|
{
|
|
"2026-01-18": {
|
|
"categories": [
|
|
{ "id": 2, "name": "유튜브", "color": "#ff0033", "count": 3 }
|
|
],
|
|
"schedules": [
|
|
{
|
|
"id": 123,
|
|
"title": "...",
|
|
"time": "19:00:00",
|
|
"category": { "id": 2, "name": "유튜브", "color": "#ff0033" },
|
|
"source": {
|
|
"name": "fromis_9",
|
|
"url": "https://www.youtube.com/watch?v=VIDEO_ID"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**source 객체 (카테고리별):**
|
|
- YouTube (category_id=2): `{ name: "채널명", url: "https://www.youtube.com/..." }`
|
|
- X (category_id=3): `{ name: "", url: "https://x.com/realfromis_9/status/..." }` (name 빈 문자열)
|
|
- 기타 카테고리: source 없음
|
|
|
|
**검색 응답:**
|
|
```json
|
|
{
|
|
"schedules": [
|
|
{
|
|
"id": 123,
|
|
"title": "...",
|
|
"datetime": "2026-01-18T19:00:00",
|
|
"category": { "id": 2, "name": "유튜브", "color": "#ff0033" },
|
|
"source": { "name": "fromis_9", "url": "https://..." },
|
|
"members": ["송하영"],
|
|
"_rankingScore": 0.95
|
|
}
|
|
],
|
|
"total": 100,
|
|
"offset": 0,
|
|
"limit": 20,
|
|
"hasMore": true
|
|
}
|
|
```
|
|
|
|
### GET /schedules/:id
|
|
일정 상세 조회
|
|
|
|
### POST /schedules/sync-search
|
|
Meilisearch 전체 동기화 (인증 필요)
|
|
|
|
---
|
|
|
|
## 추천 검색어
|
|
|
|
### GET /schedules/suggestions
|
|
추천 검색어 조회
|
|
|
|
**Query Parameters:**
|
|
- `q` - 검색어 (2자 이상)
|
|
- `limit` - 결과 개수 (기본 10)
|
|
|
|
**응답:**
|
|
```json
|
|
{
|
|
"suggestions": ["송하영", "송하영 직캠", "하영"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 관리자 - 봇 관리 (인증 필요)
|
|
|
|
### GET /admin/bots
|
|
봇 목록 조회
|
|
|
|
**응답:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "youtube-fromis9",
|
|
"name": "fromis_9",
|
|
"type": "youtube",
|
|
"status": "running",
|
|
"last_check_at": "2026-01-18T10:30:00Z",
|
|
"last_added_count": 2,
|
|
"schedules_added": 150,
|
|
"check_interval": 2,
|
|
"error_message": null,
|
|
"enabled": true
|
|
}
|
|
]
|
|
```
|
|
|
|
### POST /admin/bots/:id/start
|
|
봇 시작
|
|
|
|
### POST /admin/bots/:id/stop
|
|
봇 정지
|
|
|
|
### POST /admin/bots/:id/sync-all
|
|
전체 동기화 (모든 영상/트윗 수집)
|
|
|
|
**응답:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"addedCount": 25,
|
|
"total": 100
|
|
}
|
|
```
|
|
|
|
### GET /admin/bots/quota-warning
|
|
YouTube API 할당량 경고 조회
|
|
|
|
**응답:**
|
|
```json
|
|
{
|
|
"active": true,
|
|
"message": "YouTube API 할당량 초과",
|
|
"timestamp": "2026-01-18T10:00:00Z"
|
|
}
|
|
```
|
|
|
|
### DELETE /admin/bots/quota-warning
|
|
할당량 경고 해제
|
|
|
|
---
|
|
|
|
## 헬스 체크
|
|
|
|
### GET /health
|
|
서버 상태 확인
|
|
|
|
---
|
|
|
|
## API 문서
|
|
|
|
### GET /docs
|
|
Scalar API Reference UI
|
|
|
|
### GET /docs/json
|
|
OpenAPI JSON 스펙
|