# API Reference

## Base URL

`http://localhost:8000`

## 인증

Admin API(`/admin/*`)는 `X-Admin-Password` 헤더가 필요하다.
서버의 `ADMIN_PASSWORD` 환경변수와 일치해야 하며, 미설정 시 500 에러를 반환한다.

---

## GET /

헬스체크.

**응답**: `{"status": "ok"}`

---

## GET /today

오늘의 추천 문제를 반환한다. Search 모드와 Workbook 모드를 지원한다.

### 공통 파라미터

| 파라미터 | 타입 | 설명 | 기본값 |
|----------|------|------|--------|
| `source_mode` | string | `search` 또는 `workbook` | `SOURCE_MODE_DEFAULT` or `search` |

### Search 모드 파라미터

| 파라미터 | 타입 | 설명 | 기본값 |
|----------|------|------|--------|
| `difficulty_mode` | string | `easy`/`hard`/`all` | `DIFFICULTY_MODE_DEFAULT` or `easy` |
| `tag_mode` | string | `easy`/`hard`/`all` | `TAG_MODE_DEFAULT` or `easy` |
| `difficulty` | string | 난이도 범위 (예: `6..10`). 지정 시 `difficulty_mode`보다 우선 | - |
| `tags` | string | 태그 (예: `dp,graphs`). 지정 시 `tag_mode`보다 우선 | - |
| `lang` | string | 언어 필터: `ko`/`en`/`ko,en`/`all` | `LANG_DEFAULT` or `all` |

### Workbook 모드 파라미터

| 파라미터 | 타입 | 설명 | 기본값 |
|----------|------|------|--------|
| `workbook_id` | int | 문제집 ID | `WORKBOOK_ID_DEFAULT` |
| `workbook_pick` | string | `random` 또는 `level_asc` | `level_asc` |

### 응답 (Search 모드)

```json
{
  "source_mode": "search",
  "difficulty_mode": "easy",
  "tag_mode": "easy",
  "lang": "all",
  "difficulty": "6..10",
  "tags": ["dp"],
  "query": "*6..10 (tag:dp)",
  "problemId": 1234,
  "title": "문제 제목",
  "level": 8,
  "problemUrl": "https://www.acmicpc.net/problem/1234",
  "solvedUrl": "https://solved.ac/problems/id/1234",
  "discordPayload": { "embeds": [...] }
}
```

### 응답 (Workbook 모드)

```json
{
  "source_mode": "workbook",
  "workbook_id": 12345,
  "problemId": 1234,
  "title": "문제 제목",
  "level": 8,
  "problemUrl": "https://www.acmicpc.net/problem/1234",
  "solvedUrl": "https://solved.ac/problems/id/1234",
  "discordPayload": { "embeds": [...] }
}
```

### 에러

| 상태 코드 | 조건 |
|-----------|------|
| 400 | `difficulty_mode`/`tag_mode` 값이 유효하지 않음 |
| 400 | Workbook 모드에서 `workbook_id`를 확정할 수 없음 |
| 409 | Workbook에서 더 이상 뽑을 문제가 없음 (`no_more_problems_in_workbook`) |
| 503 | Search 모드에서 solved.ac 조회 실패 (`failed_to_fetch_problem`) |

---

## POST /admin/workbooks/{workbook_id}/enrich

문제집에 포함된 문제들의 메타데이터(제목, 난이도, 태그)를 solved.ac API로 채운다.

### 파라미터

| 파라미터 | 타입 | 설명 | 기본값 |
|----------|------|------|--------|
| `only_missing` | bool | `true`면 NULL 필드만 채움, `false`면 전체 덮어씀 | `true` |
| `commit_every` | int (1~500) | DB 커밋 배치 크기 | `50` |
| `sleep_sec` | float (0.0~2.0) | solved.ac 호출 간 대기 시간 | `0.12` |

### 요청 예시

```bash
curl -s -X POST \
  -H "X-Admin-Password: change-me" \
  "http://localhost:8000/admin/workbooks/12345/enrich?only_missing=true"
```

### 응답

```json
{
  "status": "ok",
  "result": {
    "workbook_id": 12345,
    "target_count": 100,
    "updated": 95,
    "skipped": 3,
    "failed": 2,
    "only_missing": true,
    "commit_every": 50,
    "sleep_sec": 0.12,
    "message": "enrich done"
  }
}
```

---

## DELETE /admin/workbooks/{workbook_id}/reset

문제집의 발송 기록(`workbook_sends`)을 초기화하여 모든 문제를 다시 추천받을 수 있게 한다.

### 요청 예시

```bash
curl -s -X DELETE \
  -H "X-Admin-Password: change-me" \
  "http://localhost:8000/admin/workbooks/12345/reset"
```

### 응답

```json
{
  "status": "ok",
  "workbook_id": 12345,
  "deleted_sends": 42,
  "message": "workbook progress reset (problems can be picked again)"
}
```