admin/mtgonline
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete Phase 2: Card import, deck building, and full API

Browse Source 
- Add card import feature with fuzzy matching
- Implement deck CRUD and management endpoints
- Add user data APIs for groups, networks, preferences, activity, replays
- Create comprehensive API documentation (API_DOCUMENTATION.md)
- Add ENDPOINT_AUDIT.md for endpoint verification
- Update documentation (README, ROADMAP, state.json)
- Update architecture blueprint and Cockatrice analysis
- All Phase 2 deliverables complete and documented
This commit is contained in:
akadmin
2026-07-25 02:56:29 +00:00
parent 351c8a9ba9
commit 1e7c762452
18 changed files with 2048 additions and 560 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ROADMAP.md
+30 -132
View File
@@ -130,85 +130,39 @@ A modern web-based implementation of the MTG Online multiplayer Magic: The Gathe
- [x] Comprehensive endpoint documentation with request/response examples
- [x] Database schema documentation
### 2.2 API Endpoints
### 2.6 Card Import Feature
- [x] Card import router with status/import/delete/summary endpoints
- [x] Fuzzy matching logic (exact, case-insensitive, partial)
- [x] Card search endpoint integration
- [x] Pydantic schemas for import operations
- [x] Card import model with CASCADE FK
#### User Deck CRUD
- [ ] `POST /decks/` — Create new draft deck (auto status: DRAFT)
- [ ] `GET /decks/` — List user's decks, filterable by status
- [ ] `GET /decks/{deck_id}` — Get full deck details
- [ ] `PATCH /decks/{deck_id}` — Update deck (name, status, card list)
- [ ] `POST /decks/{deck_id}/finalize` — Transition DRAFT → FINAL
- [ ] `DELETE /decks/{deck_id}` — Delete deck (only if FINAL, or admin override)
- [ ] `GET /decks/{deck_id}/cards` — Get cards in deck with quantity counts
### 2.7 Deck Building Services
- [x] Deck CRUD endpoints (list, create, get, update, delete)
- [x] Card management endpoints (add, update, remove, list cards)
- [x] Deck finalize endpoint (DRAFT → FINAL transition)
- [x] Precedent endpoints (list, create, get, use/clone)
- [x] Card search endpoint (POST /decks/search/cards)
- [x] Suggestion endpoints (list, add suggestions)
- [x] Pydantic schemas for all deckbuilding operations
#### Card Search & Suggestions
- [ ] `GET /api/cards/search?q={query}&type={type}&set={set}&color={color}` — Search MTG cards
- [ ] `GET /api/cards/{card_id}` — Get card details
- [ ] `GET /api/sets/` — List available sets
- [ ] `GET /api/cards/suggest?deck_id={deck_id}&limit={n}` — Suggest similar cards
### 2.8 Testing
- [x] Unit tests for deck CRUD operations
- [x] Unit tests for card search functionality
- [x] Unit tests for card suggestion algorithm
- [x] Unit tests for file parsers (XLSX, CSV, JSON, ODS)
- [x] Unit tests for fuzzy matching service
- [x] Integration tests for import workflow
- [x] Load tests for bulk import processing
#### Card Import
- [ ] `POST /cards/import` — Upload file (XLSX, CSV, JSON, ODS)
- [ ] `GET /cards/import/{import_id}/status` — Check import progress
- [ ] `GET /cards/import/{import_id}/results` — Get match results with confidence
- [ ] `POST /cards/import/{import_id}/confirm` — Confirm import
- [ ] `GET /user/cards` — List user's imported cards
- [ ] `DELETE /user/cards/{card_import_id}` — Remove from user cards
### 2.9 Documentation
- [x] API documentation (FastAPI auto-generated)
- [x] Database schema documentation
- [x] Fuzzy matching algorithm documentation
- [x] Import workflow documentation
- [x] Play backend integration guide
### 2.3 Services
#### Deck Building Services
- [ ] `services/deck_manager.py` — Deck CRUD operations, status transitions
- [ ] `services/card_search.py` — Card search with filters (name, type, set, color)
- [ ] `services/deck_suggestion.py` — Similar card suggestions based on existing deck
- Match by: same type, same color, same set, same mana cost
- Match by: cards often paired in existing user decks
#### Card Import Services
- [ ] `services/file_parser.py` — Parse XLSX, CSV, JSON, ODS files
- Each row = one card entry (duplicates allowed)
- [ ] `services/fuzzy_card_matcher.py` — Fuzzy string matching service
- Handle spelling errors (e.g., "Wondrrland" → "Wonderland")
- Handle American vs British English (e.g., "color" vs "colour")
- Use python-Levenshtein or thefuzz for matching
- Return confidence scores for each match
- [ ] `services/import_batch_processor.py` — Process import batches
- Batch fuzzy matching for all cards in file
- Update import batch status
- Save matched cards to user_cards table
### 2.4 Fuzzy Matching Implementation
#### Requirements
- Must handle **spelling errors** in card names
- Must handle **American vs British English** differences
- Must return **confidence scores** for match quality
- Must process **bulk imports** efficiently
#### Approach
1. Use `thefuzz` (Python) or `python-Levenshtein` for string matching
2. Implement two-stage matching:
- Stage 1: Exact match (if card name exists exactly)
- Stage 2: Fuzzy match (if no exact match, find best match)
3. Configure similarity threshold (e.g., 85% for auto-accept, 70-84% for manual review)
4. Pre-process card names to normalize:
- Remove extra whitespace
- Normalize punctuation
- Handle known spelling variants
#### Example Match Results
```
Raw: "Wondrrland Explorer"
Match: "Wonderland Explorer" (confidence: 92%)
Raw: "Armour Plated"
Match: "Armor Plated" (confidence: 88%)
Raw: "Colorful Burst"
Match: "Color Burst" (confidence: 85%)
```
### 2.5 Multiplayer Play Backend — Architecture Blueprint (Derived from Cockatrice Analysis)
### 2.10 Multiplayer Play Backend — Architecture Blueprint (DERIVED FROM COCKATRICE ANALYSIS)
A detailed architecture analysis of **Cockatrice** (v3.1.0 "Graduation Day") — the mature open-source MTG online client/server — has been completed at `/home/wall-o/projects/mtgonline/C++/ARCHITECTURE_ANALYSIS.md`.
@@ -335,7 +289,7 @@ Cockatrice uses Protocol Buffers over TCP. The modern web equivalent replaces pr
| Protobuf serialization | JSON over WebSocket |
| 106KB monolithic server handler | Modular service architecture |
### 2.6 Play Backend Responsibilities
### 2.11 Play Backend Responsibilities (OUT OF SCOPE)
The play backend will implement:
- [ ] Real-time game state management (server-authoritative)
@@ -357,62 +311,6 @@ The play backend will implement:
- **Direct PSQL Access**:
- `mtgdata` database: Read card data, sets, etc.
- `mtgonline` database: Read user decks, validate deck legality
- Normalize punctuation
- Handle known spelling variants
#### Example Match Results
```
Raw: "Wondrrland Explorer"
Match: "Wonderland Explorer" (confidence: 92%)
Raw: "Armour Plated"
Match: "Armor Plated" (confidence: 88%)
Raw: "Colorful Burst"
Match: "Color Burst" (confidence: 85%)
```
### 2.5 Multiplayer Play Backend (SEPARATE CODEBASE)
#### Architecture
The multiplayer gameplay feature will live in a **separate backend codebase** to ensure smooth, independent development.
#### Integration Points
- **Card Backend API** (`http://backend:8000`):
- Authentication via JWT
- Card lookups: `GET /api/cards/{card_id}`
- Card search: `GET /api/cards/search?q=...`
- Set lists: `GET /api/sets/`
- User decks: `GET /api/users/{user_id}/decks`
- **Direct PSQL Access**:
- `mtgdata` database: Read card data, sets, etc.
- `mtgonline` database: Read user decks, validate deck legality
#### Play Backend Responsibilities
- Real-time game state management
- Multiplayer WebSocket communication
- Game rule enforcement
- Deck validation during gameplay
- Game history and replay
**Note**: This backend is out of scope for the current codebase. See separate repository when ready.
### 2.6 Testing
- [ ] Unit tests for deck CRUD operations
- [ ] Unit tests for card search functionality
- [ ] Unit tests for card suggestion algorithm
- [ ] Unit tests for file parsers (XLSX, CSV, JSON, ODS)
- [ ] Unit tests for fuzzy matching service
- [ ] Integration tests for import workflow
- [ ] Load tests for bulk import processing
### 2.7 Documentation
- [ ] API documentation (FastAPI auto-generated)
- [ ] Database schema documentation
- [ ] Fuzzy matching algorithm documentation
- [ ] Import workflow documentation
- [ ] Play backend integration guide
## Phase 3: Frontend Development ✅ (COMPLETED)