mirror of
https://github.com/mwisnowski/mtg_python_deckbuilder.git
synced 2025-12-16 15:40:12 +01:00
88cf832bf2
document deck summary DFC badges, exporter annotations, and per-face metadata across README/DOCKER/release notes record completion of all MDFC roadmap follow-ups and add the authoring guide for multi-face CSV entries wire in optional DFC_PER_FACE_SNAPSHOT env support, exporter regression tests, and diagnostics updates noted in the changelog
71 lines
4.8 KiB
Markdown
71 lines
4.8 KiB
Markdown
# Commander Catalog Onboarding
|
||
|
||
The Commander Browser and deck builder both read from `csv_files/commander_cards.csv`. This file is generated during setup and must stay in sync with the fields the web UI expects. Use this guide whenever you need to add a new commander, refresh the dataset, or troubleshoot missing entries.
|
||
|
||
## Where the file lives
|
||
|
||
- Default path: `csv_files/commander_cards.csv`
|
||
- Override: set `CSV_FILES_DIR` (env var) before launching the app; the loader resolves `commander_cards.csv` inside that directory.
|
||
- Caching: the web layer caches the parsed file in process. Restart the app or call `clear_commander_catalog_cache()` in a shell if you edit the CSV while the server is running.
|
||
|
||
## Required columns
|
||
|
||
The loader normalizes these columns; keep the header names exact. Optional fields can be blank but should still be present.
|
||
|
||
| Column | Notes |
|
||
| --- | --- |
|
||
| `name` | Printed front name. Used as the fallback display label.
|
||
| `faceName` | Front face name for MDFCs/split cards. Defaults to `name` when empty.
|
||
| `side` | Leave blank or `A` for the primary face. Secondary faces become distinct slugs.
|
||
| `colorIdentity` | WUBRG characters (any casing). `C` marks colorless identities.
|
||
| `colors` | Printed colors; mainly used for ordering badges.
|
||
| `manaCost` | Optional but keeps rows sortable in the UI.
|
||
| `manaValue` | Numeric converted mana cost.
|
||
| `type` | Full type line (e.g., `Legendary Creature — Phyrexian Angel`).
|
||
| `creatureTypes` | Python/JSON list or comma-separated string of creature subtypes.
|
||
| `text` | Oracle text. Enables partner/background detection and hover tooltips.
|
||
| `power` / `toughness` | Optional stats. Leave blank for non-creatures.
|
||
| `keywords` | Comma-separated keywords (Flying, Vigilance, …).
|
||
| `themeTags` | Python/JSON list of curated themes (e.g., `['Angels', 'Life Gain']`).
|
||
| `edhrecRank` | Optional EDHREC popularity rank (integer).
|
||
| `layout` | Layout string from MTGJSON (`normal`, `modal_dfc`, etc.).
|
||
|
||
Additional columns are preserved but ignored by the browser; feel free to keep upstream metadata.
|
||
|
||
## Recommended refresh workflow
|
||
|
||
1. Ensure dependencies are installed: `pip install -r requirements.txt`.
|
||
2. Regenerate the commander catalog with the MDFC-aware helper (multi-face merge always on):
|
||
```powershell
|
||
python -m code.scripts.refresh_commander_catalog
|
||
```
|
||
- Pass `--compat-snapshot` when you need both `csv_files/commander_cards.csv` and `csv_files/compat_faces/commander_cards_unmerged.csv` so downstream consumers can diff the historical row-per-face layout.
|
||
- The legacy `--mode` argument is deprecated; it no longer disables the merge but still maps `--mode compat` to `--compat-snapshot` for older automation. Use `--skip-setup` if `determine_commanders()` has already been run and you simply need to reapply tagging.
|
||
- When running the web service during staging, set `DFC_COMPAT_SNAPSHOT=1` if you need the compatibility snapshot written on each rebuild. The merge itself no longer requires a feature flag.
|
||
- Use the staging QA checklist (`docs/qa/mdfc_staging_checklist.md`) to validate commander flows and downstream consumers before promoting the flag in production.
|
||
3. Restart the web server (or your desktop app) so the cache reloads the new file.
|
||
4. Validate with the targeted test:
|
||
```powershell
|
||
python -m pytest -q code/tests/test_commander_catalog_loader.py
|
||
```
|
||
The test confirms required columns exist, normalization still works, and caching invalidates correctly.
|
||
|
||
## Manual edits (quick fixes)
|
||
|
||
If you need to hotfix a single row before a full regeneration:
|
||
|
||
1. Open the CSV in a UTF-8 aware editor (Excel can re-save with a UTF-8 BOM — prefer a text editor when possible).
|
||
2. Add or edit the row, ensuring the slug-worthy fields (`name`, `faceName`, `side`) are unique.
|
||
3. Keep the `themeTags` value as a Python/JSON list (e.g., `['Artifacts']`), or a comma-delimited list without stray quotes.
|
||
4. Save the file and restart the server so the cache refreshes.
|
||
5. Backfill the curated themes in `config/themes/` if the new commander should surface dedicated tags.
|
||
|
||
> Manual edits are acceptable for emergency fixes but commit regenerated data as soon as possible so automation stays trustworthy.
|
||
|
||
## Troubleshooting
|
||
|
||
- **`Commander catalog is unavailable` error**: The app could not find the CSV. Verify the file exists under `CSV_FILES_DIR` and has a header row.
|
||
- **Row missing in the browser**: Ensure the commander passed eligibility (legendary rules) and the row’s `layout`/`side` data is correct. Slug collisions are auto-deduped (`-2`, `-3`, …) but rely on unique `name`+`side` combos.
|
||
- **Theme chips absent**: Confirm `themeTags` contains at least one value and that the theme slug exists in the theme catalog; otherwise the UI hides the chips.
|
||
|
||
For deeper issues, enable verbose logs with `SHOW_LOGS=1` before restarting the web process.
|