baekjoon-bot/docs/API.md

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 /

상태 확인(헬스체크).

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) 모드:

curl -s "http://localhost:8000/today" | cat

• 난이도/태그/언어 직접 지정:

curl -s "http://localhost:8000/today?difficulty=6..10&tags=dp,graphs&lang=ko,en" | cat

• workbook 모드:

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

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

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