# API Reference
작성: AI / 수정: nkey

## Base URL
- 로컬: `http://localhost:8000`

## Authentication
- Admin API 전용
  - Header: `X-Admin-Password: <ADMIN_PASSWORD>`
  - `ADMIN_PASSWORD` 미설정 시 admin API는 500으로 실패합니다.

## Endpoints (Top)

### GET /
상태 확인(헬스체크).
```bash
curl -s http://localhost:8000/
```

### GET /today
오늘의 추천 문제를 반환합니다. 기본은 solved.ac 검색(search) 모드이며, workbook 모드로도 동작합니다.

#### Query Parameters
- `source_mode` (string): `search|workbook` (기본값: `SOURCE_MODE_DEFAULT` 또는 `search`)
- workbook 모드:
  - `workbook_id` (int, optional): workbook id. 미지정 시 `WORKBOOK_ID_DEFAULT` 사용 시도
  - `workbook_pick` (string): `random|level_asc` (기본: `level_asc`)
- search 모드(필터):
  - `difficulty_mode` (string): `easy|hard|all` (기본값: `DIFFICULTY_MODE_DEFAULT` 또는 `easy`)
  - `tag_mode` (string): `easy|hard|all` (기본값: `TAG_MODE_DEFAULT` 또는 `easy`)
  - `difficulty` (string, optional): 예 `6..10` (지정 시 `difficulty_mode`보다 우선)
  - `tags` (string, optional): 예 `dp,graphs` (지정 시 `tag_mode`보다 우선)
  - `lang` (string): `ko | en | ko,en | all` (기본값: `LANG_DEFAULT` 또는 `all`)

#### Examples
- 기본(search) 모드:
```bash
curl -s "http://localhost:8000/today" | cat
```

- 난이도/태그/언어 직접 지정:
```bash
curl -s "http://localhost:8000/today?difficulty=6..10&tags=dp,graphs&lang=ko,en" | cat
```

- workbook 모드:
```bash
curl -s "http://localhost:8000/today?source_mode=workbook&workbook_id=12345&workbook_pick=level_asc" | cat
```

#### Response (성공 예시 형태)
- 공통: `problemId`, `title`, `level`, `problemUrl`, `solvedUrl`, `discordPayload` 포함
- search 모드: `query`, `difficulty`, `tags`, `difficulty_mode`, `tag_mode`, `lang` 포함
- workbook 모드: `workbook_id` 포함

#### Errors
- workbook 모드에서 `workbook_id`를 확정할 수 없을 때: 400
- workbook 모드에서 더 이상 뽑을 문제가 없을 때: 409 (`no_more_problems_in_workbook`)
- search 모드에서 solved.ac 조회 실패: 503 (`failed_to_fetch_problem`)

---

### POST /admin/workbooks/{workbook_id}/enrich
workbook에 포함된 문제들의 메타(제목/레벨/태그)를 solved.ac `problem/show`로 채웁니다. (DB 필요)

#### Auth
- `X-Admin-Password` 필요

#### Query Parameters
- `only_missing` (bool, default `true`): `true`면 NULL만 채움 / `false`면 덮어씀
- `commit_every` (int, default `50`, 1~500): 몇 개마다 commit할지
- `sleep_sec` (float, default `0.12`, 0.0~2.0): solved.ac 호출 사이 대기

#### Example
```bash
curl -s -X POST \
  -H "X-Admin-Password: change-me" \
  "http://localhost:8000/admin/workbooks/12345/enrich?only_missing=true&commit_every=50&sleep_sec=0.12" | cat
```

#### Response
- `status: ok`
- `result`에 `target_count`, `updated`, `skipped`, `failed` 등 요약 포함

---

### DELETE /admin/workbooks/{workbook_id}/reset
해당 workbook의 전송(픽) 기록을 초기화하여, 다시 문제를 뽑을 수 있게 합니다. (DB 필요)

#### Auth
- `X-Admin-Password` 필요

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

#### Response
- `deleted_sends`: 삭제된 기록 수

## Data Models (참고)
- `discordPayload`는 Discord Webhook/봇 메시지에 사용할 수 있는 `embeds` 구조를 포함합니다.
  - 실제 전송(Discord webhook 호출)은 이 서비스 밖(외부 스케줄러/워크플로우)에서 수행하는 것을 전제로 합니다.