admin/mtgonline
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mtgonline/ENDPOINT_AUDIT.md
T
akadmin 1e7c762452 Complete Phase 2: Card import, deck building, and full API 
- 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
2026-07-25 02:56:29 +00:00

263 lines
9.0 KiB
Markdown
Raw Permalink Blame History

# Backend Endpoint Audit Report
**Date:** 2026-07-24
**Scope:** Roadmap Section 2.2 - API Endpoints
**Status:** ✅ Review Complete
---
## Executive Summary
The backend has implemented a **simplified card import feature** that differs significantly from the roadmap specification. While the core deck management and user data endpoints are complete, the card import workflow uses a different approach (list-based vs file-based upload).
---
## Section 2.2 - User Deck CRUD ✅ COMPLETE
All deck management endpoints are implemented and match the roadmap:
| Roadmap Endpoint | Status | Implementation |
|-----------------|--------|----------------|
| `POST /decks/` | ✅ | Create user deck with DRAFT status |
| `GET /decks/` | ✅ | List decks with filtering (status, folder, precedent) and pagination |
| `GET /decks/{deck_id}` | ✅ | Get full deck details with cards |
| `PATCH /decks/{deck_id}` | ✅ | Update deck (name, status, folder) |
| `POST /decks/{deck_id}/finalize` | ✅ | Transition DRAFT → FINAL |
| `DELETE /decks/{deck_id}` | ✅ | Delete deck (admin override for FINAL) |
| `GET /decks/{deck_id}/cards` | ✅ | List cards with quantities and details |
**Location:** `backend/app/routers/decks.py`
**Router Prefix:** `/decks` (included in main.py)
---
## Section 2.2 - Card Search & Suggestions ⚠️ PARTIAL
### Implemented Endpoints
| Endpoint | Status | Notes |
|----------|--------|-------|
| `GET /api/mtg/cards/search` | ✅ | Search cards by name (no type/set/color filters) |
| `GET /api/mtg/cards/{card_name}` | ✅ | Get card by name |
| `GET /api/mtg/cards/sets` | ✅ | List all sets |
| `GET /api/mtg/cards/sets/{set_code}` | ✅ | Get specific set |
| `GET /api/mtg/cards/set/{set_code}` | ✅ | Get cards in set |
**Location:** `backend/app/routers/card_router.py`
**Router Prefix:** `/api/mtg/cards` (NOTE: `/mtg/cards` not `/api/cards`)
### Missing Endpoints
| Roadmap Endpoint | Status | Issue |
|-----------------|--------|-------|
| `GET /api/cards/search?q={query}&type={type}&set={set}&color={color}` | ❌ | **Filters missing** - search only supports `q` parameter, not type/set/color filters |
| `GET /api/cards/{card_id}` | ❌ | **ID lookup missing** - only name-based lookup exists |
| `GET /api/sets/` | ✅ | Implemented as `/api/mtg/cards/sets` |
| `GET /api/cards/suggest?deck_id={deck_id}&limit={n}` | ❌ | **Suggestion endpoint missing** - no card suggestion functionality |
### Additional Card Endpoints (Not in Roadmap)
| Endpoint | Status | Notes |
|----------|--------|-------|
| `GET /api/mtg/cards/types` | ✅ | Get unique card types |
| `GET /api/mtg/cards/rarities` | ✅ | Get unique card rarities |
| `GET /api/mtg/cards/statistics` | ✅ | Database statistics |
---
## Section 2.2 - Card Import ❌ SIGNIFICANT DIFFERENCES
### Roadmap Specification
The roadmap specified a **file-based import workflow**:
- `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
### Current Implementation
The actual implementation uses a **simplified list-based approach**:
| Current Endpoint | Roadmap Equivalent | Status |
|-----------------|-------------------|--------|
| `POST /api/v1/card-import/` | `POST /cards/import` | ✅ **Functionally different** - accepts card name list, not file upload |
| `GET /api/v1/card-import/status` | `GET /cards/import/{import_id}/status` | ⚠️ **Simplified** - returns current import status, not batch progress |
| `GET /api/v1/card-import/summary` | `GET /cards/import/{import_id}/results` | ⚠️ **Simplified** - returns match summary, not detailed results |
| **Missing** | `POST /cards/import/{import_id}/confirm` | ❌ **Not implemented** - no confirmation step |
| `GET /api/v1/user-data/collection` | `GET /user/cards` | ✅ Implemented under user data |
| `DELETE /api/v1/user-data/collection/{card_id}` | `DELETE /user/cards/{card_import_id}` | ⚠️ **Different** - deletes by card_id, not import_id |
### Implementation Details
**Current Card Import Flow:**
1. User sends `POST /api/v1/card-import/` with card name list
2. System matches names to database cards (exact, case-insensitive, partial matching)
3. Results stored in `user_card_imports` table as JSON
4. User can view status and summary via GET endpoints
**Missing File Upload:**
- No file parsing (XLSX, CSV, JSON, ODS)
- No batch processing
- No import ID tracking
- No confirmation workflow
---
## Section 2.2 - User Data Endpoints ✅ COMPLETE
All user data endpoints are implemented:
### Replays
| Endpoint | Status |
|----------|--------|
| `POST /api/v1/user-data/replays/` | ✅ |
| `GET /api/v1/user-data/replays/{replay_id}` | ✅ |
| `PATCH /api/v1/user-data/replays/{replay_id}` | ✅ |
| `DELETE /api/v1/user-data/replays/{replay_id}` | ✅ |
### Collection (Cards)
| Endpoint | Status |
|----------|--------|
| `POST /api/v1/user-data/collection/` | ✅ |
| `GET /api/v1/user-data/collection/` | ✅ |
| `PATCH /api/v1/user-data/collection/{card_id}` | ✅ |
| `DELETE /api/v1/user-data/collection/{card_id}` | ✅ |
### Groups
| Endpoint | Status |
|----------|--------|
| `POST /api/v1/user-data/groups/` | ✅ |
| `GET /api/v1/user-data/groups/` | ✅ |
| `GET /api/v1/user-data/groups/{group_id}` | ✅ |
| `PATCH /api/v1/user-data/groups/{group_id}` | ✅ |
| `DELETE /api/v1/user-data/groups/{group_id}` | ✅ |
### Networks
| Endpoint | Status |
|----------|--------|
| `POST /api/v1/user-data/networks/` | ✅ |
| `GET /api/v1/user-data/networks/` | ✅ |
| `GET /api/v1/user-data/networks/{network_id}` | ✅ |
| `PATCH /api/v1/user-data/networks/{network_id}` | ✅ |
| `DELETE /api/v1/user-data/networks/{network_id}` | ✅ |
### Preferences
| Endpoint | Status |
|----------|--------|
| `GET /api/v1/user-data/preferences/` | ✅ |
| `PATCH /api/v1/user-data/preferences/` | ✅ |
### Activity
| Endpoint | Status |
|----------|--------|
| `GET /api/v1/user-data/activity/` | ✅ |
**Location:** `backend/app/routers/user_data.py`
**Router Prefix:** `/api/v1/user-data`
---
## Section 2.2 - Deck Precedents ✅ COMPLETE
| Endpoint | Status |
|----------|--------|
| `GET /decks/precedents` | ✅ |
| `POST /decks/precedents` | ✅ |
| `GET /decks/precedents/{precedent_id}` | ✅ |
| `POST /decks/precedents/{precedent_id}/use` | ✅ |
**Location:** `backend/app/routers/decks.py`
---
## Section 2.2 - Card Suggestions ✅ PARTIAL
| Endpoint | Status |
|----------|--------|
| `GET /decks/{deck_id}/suggestions` | ✅ |
| `POST /decks/{deck_id}/suggestions` | ✅ |
**Note:** These are deck-specific suggestions (add to deck), not the general card suggestion endpoint from the roadmap (`GET /api/cards/suggest`).
---
## Summary of Gaps
### Critical Missing Features
1. **File-based card import workflow**
- No file upload (XLSX, CSV, JSON, ODS parsing)
- No batch processing with import IDs
- No confirmation step
- No progress tracking
2. **Card search filters**
- Search endpoint missing type, set, and color filters
- Only supports name search
3. **Card ID lookup**
- No endpoint to get card by ID
- Only name-based lookup exists
4. **General card suggestions**
- No `GET /api/cards/suggest` endpoint
- Only deck-specific suggestions exist
### Implemented but Different from Roadmap
1. **Card import approach** - List-based vs file-based
2. **Router prefix** - `/api/mtg/cards` vs `/api/cards`
3. **Deck suggestions** - Deck-specific vs general card suggestions
---
## Recommendations
### Option A: Align with Roadmap (Recommended)
Implement the file-based import workflow:
1. Add file upload endpoint with XLSX/CSV/JSON/ODS parsing
2. Create import batch processing with progress tracking
3. Add confirmation step for matching results
4. Implement card search filters (type, set, color)
5. Add card ID lookup endpoint
6. Implement general card suggestion service
### Option B: Simplify Roadmap
Accept the current simplified implementation:
1. Document the simplified card import approach
2. Update ROADMAP.md to reflect actual implementation
3. Consider adding file upload as future enhancement
---
## File Locations
| Feature | File |
|---------|------|
| Deck CRUD | `backend/app/routers/decks.py` |
| Card Search | `backend/app/routers/card_router.py` |
| Card Import | `backend/app/routers/card_import.py` |
| User Data | `backend/app/routers/user_data.py` |
| Deck Precedents | `backend/app/routers/decks.py` |
| Deck Suggestions | `backend/app/routers/decks.py` |
---
## Next Steps
1. **Decide on card import approach** (file-based vs list-based)
2. **If file-based**: Implement file upload and parsing services
3. **If list-based**: Update ROADMAP.md to reflect actual implementation
4. **Add missing search filters** to card search endpoint
5. **Add card ID lookup** endpoint
6. **Implement general card suggestion service**
---
**Audit Complete:** 2026-07-24T04:20:00Z
Reference in New Issue View Git Blame Copy Permalink