k-lottery: Instructions file for Codex

CLAUDE.md

동행복권 로또 6/45 구매 · 잔액 확인 · 예치금 충전 · 당첨 확인 자동화. 소유자 본인 계정을 대상으로 하는 개인용 도구다.

배포명은 k-lottery, import 는 klottery 다 (python-dotenv → dotenv 와 같은 관례). 앞으로 이 저장소에 MCP 서버가 추가된다.

명령어

목적	명령
스크립트 실행	uv run scripts/<name>.py [옵션]
의존성 추가	uv add <pkg> (개발용은 uv add --dev <pkg>)
환경 동기화	uv sync
린트	uv run ruff check --fix .
포맷	uv run ruff format .
타입 검사	uv run ty check
테스트	uv run pytest
훅 설치 (최초 1회)	uv run pre-commit install
훅 전체 실행	uv run pre-commit run --all-files

• pip / python 을 직접 호출하지 않는다. 실행은 항상 uv run 을 거친다.
• pyproject.toml 의 dependencies 를 손으로 편집하지 않는다. uv add / uv remove 를 쓴다 (uv.lock 이 함께 갱신되어야 한다).
• .venv/ 를 직접 수정하지 않는다. uv sync 가 유일한 기준이다.
• Python 은 .python-version 의 3.13 을 따른다.

사이트 스펙 — 먼저 읽을 것

docs/dhlottery-api-spec.md 가 유일한 진실이다. 실제 로그인 세션에서 캡처해 검증한 URL·필드·응답 구조가 들어 있다. 사이트 관련 코드를 쓰거나 고치기 전에 반드시 확인한다.

• 동행복권은 2026년에 개편됐다. 인터넷의 기존 봇 코드와 블로그는 대부분 죽은 엔드포인트(common.do?method=..., userSsl.do?method=login)를 쓴다. 베끼지 마라.
• 참조 구현(techinpark/lottery-bot, roeniss/dhlottery-api)도 각각 틀린 값이 있다. 실측 스펙과 어긋나면 실측을 따른다.
• 스펙에 없는 엔드포인트가 필요해지면 추측하지 말고 DevTools 로 캡처해 스펙 문서에 먼저 기록한 뒤 구현한다.
• 구매 응답에 자동화 탐지(isAllowed=="N")가 있다. 이 분기를 절대 삼키지 않는다.

구조

src/klottery/      공용 로직 — 두 곳 이상에서 쓰이는 코드만 올린다
src/klottery/mcp/  MCP 서버 배선 — 도메인 로직을 두지 않는다
scripts/           자동화 진입점 — 얇게 유지한다 (인자 파싱 → 공용 로직 호출 → 출력)
tests/             pytest. 네트워크를 타지 않는다
data/              수집 결과·쿠키. gitignore 대상 (.gitkeep 만 추적)
docs/              API 스펙, 설계 계획

src/klottery/endpoints.py 가 사이트에 붙는 유일한 지점이다. URL·폼 필드명·매직값은 전부 거기 두고, 다른 모듈은 참조만 한다. 사이트가 또 개편되면 그 파일만 고치면 된다.

uv sync 가 프로젝트 자체를 venv 에 설치하므로 scripts/ 에서 from klottery.x import y 가 그대로 동작한다. sys.path 조작이나 상대 경로 import 를 넣지 않는다.

새 자동화를 추가할 때:

1. scripts/<동사>.py 로 진입점을 만든다 (예: buy.py, deposit.py, results.py).
2. 로직이 다른 스크립트와 겹치기 시작하면 그때 src/klottery/ 로 올린다. 미리 올리지 않는다.
3. 사이트에 직접 붙는 코드(엔드포인트·셀렉터·폼 필드)는 src/klottery/ 의 한 모듈에 모은다. 사이트 개편 시 수정 지점이 하나여야 한다.