Fix: [main] 리드미 수정 및 cicd md 파일 제외

2026-03-26 00:26:44 +09:00
parent ac75dcce7e
commit bd045b43c2
6 changed files with 375 additions and 350 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -1,105 +1,157 @@
 # API Reference
-작성: AI / 수정: nkey

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

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

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

 ---

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

-#### 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 호출 사이 대기
+**응답**: `{"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` |
+
+### 요청 예시

-#### 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
+  "http://localhost:8000/admin/workbooks/12345/enrich?only_missing=true"
 ```

-#### Response
- `status: ok`
- `result`에 `target_count`, `updated`, `skipped`, `failed` 등 요약 포함
+### 응답
+
+```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의 전송(픽) 기록을 초기화하여, 다시 문제를 뽑을 수 있게 합니다. (DB 필요)
+## DELETE /admin/workbooks/{workbook_id}/reset

-#### Auth
- `X-Admin-Password` 필요
+문제집의 발송 기록(`workbook_sends`)을 초기화하여 모든 문제를 다시 추천받을 수 있게 한다.
+
+### 요청 예시

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

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

-## Data Models (참고)
- `discordPayload`는 Discord Webhook/봇 메시지에 사용할 수 있는 `embeds` 구조를 포함합니다.
-  - 실제 전송(Discord webhook 호출)은 이 서비스 밖(외부 스케줄러/워크플로우)에서 수행하는 것을 전제로 합니다.
+```json
+{
+  "status": "ok",
+  "workbook_id": 12345,
+  "deleted_sends": 42,
+  "message": "workbook progress reset (problems can be picked again)"
+}
+```