# baekjoon-bot(폴더 구조화 이전 버전)
작성: AI / 수정: nkey

매일 백준(BOJ) 문제를 추천해주고, 디스코드 메시지(payload)로 쓸 수 있는 형태로 반환하는 FastAPI 서비스입니다.  
`/today`에서 추천 문제 + 링크 + Discord embed payload를 생성하며, (선택) PostgreSQL에 문제집(workbook) 진행상황을 저장해 “문제집에서 아직 안 보낸 문제”를 고르는 모드도 제공합니다.  
디스코드 메시지 자동화는 n8n을 활용하였습니다.

## Quickstart
### Recommended
```bash
# clone
git clone https://nkeystudy.site/gitea/nkey/baekjoon-bot.git
cd baekjoon-bot

# venv
python -m venv .venv
source .venv/bin/activate

# deps
pip install -r requirements.txt

# env (필수: DATABASE_URL)
cat > .env <<'EOF'
DATABASE_URL=postgresql+asyncpg://USER:PASSWORD@HOST:5432/DBNAME
# (admin API 사용 시 필수)
ADMIN_PASSWORD=change-me
EOF

# run
uvicorn app:app --host 0.0.0.0 --port 8000

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

### Alternative (optional) - Docker
```bash
docker build -f dockerfile -t baekjoon-bot:local .
docker run --rm -p 8000:8000 --env-file .env baekjoon-bot:local

# verify
curl -s http://localhost:8000/ | cat
```

## Requirements
- Runtime/Language: Python 3.12+ (Dockerfile 기준)
- Dependencies: `fastapi`, `uvicorn`, `sqlalchemy>=2.0`, `asyncpg`, `requests`, `httpx`, `python-dotenv` 등 (`requirements.txt`)
- Tools: (optional) Docker

## Configuration
### Environment Variables
| Key | Description | Default | Required |
|---|---|---:|:---:|
| `DATABASE_URL` | SQLAlchemy async DB URL (예: `postgresql+asyncpg://...`) | - | ✅ |
| `ADMIN_PASSWORD` | Admin API 인증 비밀번호 (`X-Admin-Password` 헤더와 비교) | `""` | ✅ (admin API) |
| `SOURCE_MODE_DEFAULT` | `/today` 기본 소스 모드 | `search` |  |
| `WORKBOOK_ID_DEFAULT` | `source_mode=workbook`에서 `workbook_id` 미지정 시 기본값 | - |  |
| `DIFFICULTY_MODE_DEFAULT` | `/today` 기본 난이도 모드 | `easy` |  |
| `TAG_MODE_DEFAULT` | `/today` 기본 태그 모드 | `easy` |  |
| `LANG_DEFAULT` | `/today` 기본 언어 | `all` |  |
| `DIFFICULTY_EASY` | easy 난이도 범위 | `6..10` |  |
| `DIFFICULTY_HARD` | hard 난이도 범위 | `11..15` |  |
| `DIFFICULTY_ALL` | all 난이도 범위 | `1..30` |  |
| `TAGS_EASY` | easy 태그 프리셋(CSV) | `""` |  |
| `TAGS_HARD` | hard 태그 프리셋(CSV) | `""` |  |
| `TAGS_ALL` | all 태그 프리셋(CSV) | `""` |  |
| `TAG_PICK` | 태그 선택 정책 (random/none/전체) | `random` |  |
| `TAG_PICK_EASY` | easy 태그 선택 정책 | `TAG_PICK` |  |
| `TAG_PICK_HARD` | hard 태그 선택 정책 | `TAG_PICK` |  |
| `TAG_PICK_ALL` | all 태그 선택 정책 | `TAG_PICK` 또는 `none` |  |
| `TAGS_JOIN` | 태그 결합 방식 | `or` |  |

### Ports
| Service | Port | Description |
|---|---:|---|
| API | 8000 | FastAPI(Uvicorn) |

## Usage (minimal)
- 오늘의 추천 문제(검색 모드, 기본값)
  - `GET /today`
- 난이도/태그/언어 지정
  - `GET /today?difficulty=6..10&tags=dp,graphs&lang=ko,en`
- 문제집(workbook) 모드로 추천
  - `GET /today?source_mode=workbook&workbook_id=12345&workbook_pick=level_asc`
- Admin: 문제집 메타(제목/레벨/태그) 보강
  - `POST /admin/workbooks/{workbook_id}/enrich` + `X-Admin-Password: ...`

## Docs
- Operations: `docs/OPERATIONS.md`
- Development: `docs/DEVELOPMENT.md`
- API: `docs/API.md`

## CI/CD
- Workflow: `.gitea/workflows/cicd.yml`
- Trigger: `main` 브랜치로 `push` 시 실행
- Flow:
  1) (수동) checkout: Gitea 서브패스(`/gitea`)를 고려해 `git init` + `git fetch`로 소스 가져옴
  2) Docker Hub 로그인
  3) 이미지 빌드/푸시: `${DOCKERHUB_USERNAME}/baekjoon-bot:latest`
  4) 서버 배포: 서버에 존재하는 app 관련 compose 파일(`/nkeysworld/compose.apps.yml`)로 `pull/up -d` 수행
  5) Discord Webhook으로 성공/실패 알림 전송

### Required Secrets
| Key | Used for |
|---|---|
| `NKEY_PAT` | workflow 내 수동 checkout 시 Gitea repo fetch 인증 |
| `DOCKERHUB_USERNAME` | Docker Hub 이미지 네임스페이스 |
| `DOCKERHUB_TOKEN` | Docker Hub 로그인 토큰 |
| `DISCORD_WEBHOOK` | CI/CD 결과 알림 전송 |

> NOTE: workflow의 빌드 단계는 `docker build -t ... .`(기본 Dockerfile 사용) 형태입니다. 레포의 빌드 파일명은 `dockerfile`(소문자)이므로, CI 환경에서 기본 Dockerfile을 쓰려면 파일명/옵션 정합성을 확인하세요.