# TriplePick 2026

**"AI(GPT · Claude · Gemini) vs 너"** — 글로벌 축구 승부예측 서비스.
3개 AI 모델이 매 경기를 서로 다르게 예측하고, 유저는 픽을 찍어 AI와 겨룬다.
끝까지 가장 정확하게 맞힌 1인에게 100만원 챌린지.

## 아키텍처

```
o2o-triple-pick/
├── docker-compose.yml      # db · api · worker · frontend 한 번에 실행
├── backend/                # FastAPI + SQLAlchemy(async) + PostgreSQL
│   ├── app/                #   API · 워커(APScheduler) · AI/이메일 실연동
│   └── .env.example
└── frontend/               # React + Vite + TypeScript + Tailwind v4
    ├── src/                #   pages · components · lib(api 연동)
    └── .env.example
```

- **frontend** — React SPA. nginx 가 정적 파일 서빙 + `/api` 를 백엔드로 프록시.
- **backend (api)** — FastAPI. 경기/AI예측/crowd 읽기, 픽 제출, 채점, 리더보드, 관리자.
- **backend (worker)** — APScheduler 별도 프로세스. 아래 "시간 기반 작업" 자동 처리.
- **db** — PostgreSQL.

## 빠른 시작 (Docker)

```bash
cp backend/.env.example backend/.env      # 키(선택) 채우기
docker compose up --build
# 프론트:  http://localhost:8080
# API 문서: http://localhost:8000/docs
```

DB 는 최초 기동 시 6경기 + AI 예측(부트스트랩) + crowd baseline 으로 자동 시드된다.
AI/이메일 키가 없어도 전체 플로우(예측·제출·채점·리더보드)는 즉시 동작한다.

## 시간 기반 작업 (워커가 자동 처리)

조사된 "필요한 시간들"을 워커 단일 프로세스가 모두 담당한다:

| 작업 | 시점 | 설정 |
|---|---|---|
| 투표 오픈 | 킥오프 − 48h (D-2) | `VOTE_OPEN_HOURS_BEFORE` |
| 투표 마감 | 킥오프 − 5분 | `VOTE_LOCK_MINUTES_BEFORE` |
| 상태 전이 (scheduled→open→locked→finished) | 주기 틱 | `STATUS_TICK_SECONDS` (기본 60s) |
| AI 예측 생성 (3모델 실 API 호출) | 매일 KST 00:05 | `AI_GENERATE_HOUR` / `_MINUTE` |
| 결과 메일 발송 (구독자) | 경기 종료 +3h | `RESULT_EMAIL_DELAY_MINUTES` |

> 데모에서는 `DEMO_FORCE_OPEN=true` 로 마감 전까지 항상 투표 가능. **운영 배포 시 false**.

## 외부 연동 (실연동 — 키 없으면 해당 기능만 생략)

- **AI 3모델** — OpenAI(GPT) · Anthropic(Claude, `claude-opus-4-8`) · Google(Gemini).
  `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GOOGLE_API_KEY`.
- **이메일** — SMTP. `SMTP_HOST` 외 `backend/.env` 참조.

## API 요약

| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | `/api/matches?lang=ko` | 전체 경기 (예측·crowd 포함) |
| GET | `/api/matches/{id}` | 경기 상세 |
| POST | `/api/predictions` | 픽 제출 (1회 수정·crowd 증분·매칭 모델) |
| GET | `/api/leaderboard` | 누적 포인트 랭킹 |
| POST | `/api/admin/result` | (Bearer) 결과 입력 → 채점 |
| POST | `/api/admin/ai-predictions` | (Bearer) AI 예측 수동 upsert |

## 로컬 개발 (Docker 없이)

```bash
# 백엔드
cd backend && python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Postgres 띄우고 DATABASE_URL 지정 후:
uvicorn app.main:app --reload          # API
python -m app.worker                   # 워커

# 프론트
cd frontend && npm install && npm run dev   # http://localhost:5173 (/api → :8000 프록시)
```

## 채점 규칙

`docs/SCORING.md` (SSOT). 정확 스코어 5 · 근접 3 · 승패 2 · 부분 1 · 빗나감 0.
누적 포인트 1위에게 최종 상금. 임직원/운영진 배제.

## 문서
- `docs/SCORING.md` — 채점·심사 SSOT
- `docs/DESIGN.md` — 디자인 토큰 SSOT
- `docs/BACKEND.md` — 초기 백엔드 설계 메모(Firebase 기준 → 현 구현은 FastAPI)