Docs: [main] readme, api, development, operations 문서 작성

docs/API.md

@@ -0,0 +1,105 @@
+# 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 호출)은 이 서비스 밖(외부 스케줄러/워크플로우)에서 수행하는 것을 전제로 합니다.