158 lines
3.9 KiB
Markdown
158 lines
3.9 KiB
Markdown
# 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)"
|
|
}
|
|
```
|