a52a77ad2a
All checks were successful
Build Docker Image / build (pull_request) Successful in 8m34s
Rewrote ~/.claude/skills/paper-dynasty/scripts/generate_summary.py and validate_database.py to use the Paper Dynasty API (via api_client.py) instead of sqlite3.connect() on a local file. generate_summary.py: now accepts --cardset-id / --env flags and fetches batting/pitching card counts and player count via GET /battingcards and GET /pitchingcards endpoints. validate_database.py: now accepts --cardset-id / --env flags and validates via API: checks card counts > 0, and that every player in the cardset has at least one batting or pitching card. Rarity-change comparison (two-DB diff) and raw field validation (groundout_b, percentage ranges) are removed — these relied on direct SQLite access and are not available through the public API. Also documents in CLAUDE.md that companion skill scripts use the API only, per the project's SQLite → PostgreSQL migration. Closes #124 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
68 lines
3.0 KiB
Markdown
68 lines
3.0 KiB
Markdown
# Paper Dynasty Database API
|
|
|
|
FastAPI backend for baseball card game data. Peewee ORM with SQLite (WAL mode).
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 # Dev server
|
|
python main.py # Alt start
|
|
python db_migrations.py # Run migrations
|
|
docker build -t paper-dynasty-db . # Build image
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- **Routers**: Domain-based in `app/routers_v2/` (cards, players, teams, packs, stats, gauntlets, scouting)
|
|
- **ORM**: Peewee with SQLite (`storage/pd_master.db`, WAL journaling)
|
|
- **Card images**: Playwright/Chromium renders HTML templates → screenshots (see `routers_v2/players.py`)
|
|
- **Logging**: Rotating files in `logs/database/{date}.log`
|
|
|
|
## Key Constants
|
|
|
|
- `LIVE_CARDSET_ID`: 24 (current active cardset, in `db_engine.py`)
|
|
- `ranked_cardsets`: Legal cardsets for ranked play
|
|
- `CARDSETS`: Configuration for game modes and card availability
|
|
|
|
## Environments & Troubleshooting
|
|
|
|
| | Dev | Prod |
|
|
|---|---|---|
|
|
| **URL** | pddev.manticorum.com | pd.manticorum.com |
|
|
| **Host** | `ssh pd-database` | `ssh akamai` → `/root/container-data/paper-dynasty` |
|
|
| **API container** | `dev_pd_database` | `pd_api` |
|
|
| **PostgreSQL** | `pd_postgres` (port 5432) | `pd_postgres` |
|
|
| **Adminer** | port 8081 | — |
|
|
| **API port** | 816 | 815 |
|
|
| **Image** | `manticorum67/paper-dynasty-database` | `manticorum67/paper-dynasty-database` |
|
|
|
|
### Logs
|
|
- **Container logs**: `docker logs --since 1h pd_api`
|
|
- **Log file (in container)**: `logs/database/YYYY-MM-DD.log` (date-stamped daily, no rotation)
|
|
- **API docs**: `/api/docs` and `/api/redoc`
|
|
|
|
### Key Env Vars
|
|
`API_TOKEN`, `LOG_LEVEL`, `DATABASE_TYPE` (sqlite/postgresql), `POSTGRES_HOST`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`
|
|
|
|
### Common Issues
|
|
- 502 Bad Gateway → API container crashed; check `docker logs pd_api`
|
|
- Card image generation failures → Playwright/Chromium issue; check for missing dependencies
|
|
- SQLite locking (dev) → WAL mode should prevent, but check for long-running writes
|
|
- DB connection errors → verify `POSTGRES_HOST` points to correct container name
|
|
- **CI/CD**: Gitea Actions on PR to `main` — builds Docker image, auto-generates CalVer version (`YYYY.MM.BUILD`) on merge
|
|
|
|
### Release Workflow
|
|
1. Create feature/fix branches off `next-release` (e.g., `fix/card-pricing`)
|
|
2. When done, merge the branch into `next-release` — this is the staging branch where changes accumulate
|
|
3. When ready to release, open a PR from `next-release` → `main`
|
|
4. CI builds Docker image on PR; CalVer tag is created on merge
|
|
5. Deploy the new image to production
|
|
|
|
## Important
|
|
|
|
- Docker image installs only Playwright Chromium (not all browsers) to optimize size
|
|
- Teams have dynamic card pricing based on market activity
|
|
- Supports both human players and AI teams
|
|
- Gauntlet events use special reward structures and card pools
|
|
- Companion skill scripts (`~/.claude/skills/paper-dynasty/scripts/`) use the API, never direct DB access
|