# 번개라디오 개발자 가이드

로컬에서 개발하는 번개라디오 앱을 위한 백엔드 API 명세입니다. (AI 코더 참고용)

## Base URL

```
https://tune.tideflo.work/api/v1
```

모든 응답은 `application/json; charset=utf-8` 입니다. CORS는 허용되어 있습니다.

## 표준 응답 형식

성공:

```json
{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "per_page": 30, "total": 37, "total_pages": 2 }
}
```

- `data` — 실제 페이로드 (객체 또는 배열)
- `meta` — 목록 응답에만 포함(페이지네이션)

실패:

```json
{
  "success": false,
  "error": { "code": "not_found", "message": "채널을 찾을 수 없습니다" }
}
```

HTTP 상태코드도 함께 사용합니다(200/201/400/401/404/409/422/502 등). 자세한 내용은 [에러 코드](errors) 참고.

## 인증 개요

- **익명 청취**: 방송국 목록·상세·스트림 재생은 **인증 없이** 호출 가능합니다. (기존 번개라디오 UX 유지)
- **선택적 계정**: 즐겨찾기 동기화 등은 이메일+비밀번호 계정으로 발급받은 **Bearer 토큰** 사용.
- **기기 식별**: 계정 없이도 `X-Device-UUID` 헤더로 기기 단위 즐겨찾기가 가능합니다.
- 2차 계획: 구글/카카오/네이버 소셜 로그인.

자세한 내용은 [계정·즐겨찾기](account) 참고.

## 빠른 시작

```bash
# 헬스체크
curl https://tune.tideflo.work/api/v1/health

# 추천 방송국 목록
curl "https://tune.tideflo.work/api/v1/stations?featured=1"

# 특정 채널 재생 URL 발급 (KBS 쿨FM 예)
curl https://tune.tideflo.work/api/v1/stations/kbs-coolfm
curl https://tune.tideflo.work/api/v1/stations/5/stream
```

## 엔드포인트 요약

| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | `/health` | 서비스·DB 상태 |
| GET | `/categories` | 카테고리(장르) 목록 |
| GET | `/stations` | 방송국 목록(필터·검색·페이지) |
| GET | `/stations/{id\|slug}` | 방송국 상세(+스트림) |
| GET | `/stations/{id}/stream` | 재생 URL 발급 |
| POST | `/auth/register` | 회원가입 |
| POST | `/auth/login` | 로그인 |
| GET | `/auth/me` | 내 정보 |
| POST | `/auth/logout` | 로그아웃 |
| GET | `/favorites` | 즐겨찾기 목록 |
| POST | `/favorites` | 즐겨찾기 추가 |
| DELETE | `/favorites/{stationId}` | 즐겨찾기 삭제 |