docs: update README with card import API documentation and complete roadmap

2026-07-24 04:54:02 +00:00
parent 867b7a9c37
commit 351c8a9ba9
3 changed files with 185 additions and 90 deletions
@@ -11,6 +11,7 @@ This project provides a backend API for a Magic: The Gathering Online platform.
 - **MTGJSON Data Pipeline** — Downloads `AllPrintings.psql`, `AllIdentifiers.json`, `Keywords.json`, `CardTypes.json`, and `AllDeckFiles.zip` from MTGJSON v5 on startup or via a `POST /refresh` endpoint.
 - **Dual PostgreSQL** — Two databases: `mtgonline` for the application (users, decks, auth) and `mtgdata` for MTG card data.
 - **Redis Caching** — Used for card lookup caching and interaction pipeline state.
+- **Card Import Feature** — Users can import their card collection (fuzzy matching enabled) for deckbuilding constraints.
 - **REST API** — `/docs` (Swagger) available at runtime.

 ## Architecture
@@ -41,6 +42,71 @@ mtgonline/
 3. If no data exists, it downloads MTGJSON files from `https://mtgjson.com/api/v5/`, unzips if needed, and upserts them into `mtgdata` tables (`mtg_sets`, `mtg_cards`, etc.).
 4. The data is then available via REST endpoints.

+## API Endpoints
+
+### Card Import (New)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v1/card-import/status` | Get current card import status |
+| `POST` | `/api/v1/card-import/` | Import/update card collection |
+| `DELETE` | `/api/v1/card-import/` | Delete card import |
+| `GET` | `/api/v1/card-import/summary` | Get import summary with match results |
+
+**Card Import Request Body:**
+```json
+{
+  "card_names": ["Lightning Bolt", "Shock", "Thoughtseize"]
+}
+```
+
+**Card Import Response:**
+```json
+{
+  "message": "Imported 3 cards successfully",
+  "card_count": 3,
+  "card_names": ["Lightning Bolt", "Shock", "Thoughtseize"],
+  "imported_at": "2026-07-24T04:12:00"
+}
+```
+
+### User Data Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v1/user-data/profile` | Get user profile |
+| `PUT` | `/api/v1/user-data/profile` | Update user profile |
+| `GET` | `/api/v1/user-data/collection` | Get user card collection |
+| `GET` | `/api/v1/user-data/groups` | List user groups |
+| `GET` | `/api/v1/user-data/networks` | List user networks |
+| `GET` | `/api/v1/user-data/preferences` | Get user preferences |
+| `PUT` | `/api/v1/user-data/preferences` | Update user preferences |
+| `GET` | `/api/v1/user-data/activity` | Get user activity log |
+| `GET` | `/api/v1/user-data/replays` | List user replays |
+| `GET` | `/api/v1/user-data/replays/{replay_id}` | Get replay details |
+
+### Deck Management Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v1/decks/` | List user decks |
+| `POST` | `/api/v1/decks/` | Create new deck |
+| `GET` | `/api/v1/decks/{deck_id}` | Get deck details |
+| `PUT` | `/api/v1/decks/{deck_id}` | Update deck |
+| `DELETE` | `/api/v1/decks/{deck_id}` | Delete deck |
+| `POST` | `/api/v1/decks/{deck_id}/cards` | Add card to deck |
+| `PUT` | `/api/v1/decks/{deck_id}/cards/{card_id}` | Update deck card |
+| `DELETE` | `/api/v1/decks/{deck_id}/cards/{card_id}` | Remove card from deck |
+| `GET` | `/api/v1/decks/{deck_id}/cards` | List deck cards |
+| `POST` | `/api/v1/decks/{deck_id}/finalize` | Finalize deck (DRAFT → FINAL) |
+| `POST` | `/api/v1/decks/search/cards` | Search cards for deckbuilding |
+| `GET` | `/api/v1/decks/precedents/` | List deck precedents |
+| `POST` | `/api/v1/decks/precedents/` | Create precedent |
+| `GET` | `/api/v1/decks/precedents/{precedent_id}` | Get precedent details |
+| `POST` | `/api/v1/decks/precedents/{precedent_id}/use` | Use/clone precedent |
+| `GET` | `/api/v1/decks/suggestions/` | List card suggestions |
+| `POST` | `/api/v1/decks/suggestions/` | Add card suggestion |
+
 ## Quick Start

 ### Prerequisites
@@ -79,6 +145,42 @@ The backend will automatically download MTGJSON data on first startup (this may
 curl -X POST http://localhost:5555/refresh
 ```

+## Card Import Feature
+
+Users can import their card collection to enable deckbuilding with owned cards. The feature includes fuzzy matching for typos.
+
+### Import Cards
+
+```bash
+curl -X POST http://localhost:5555/api/v1/card-import/ \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "card_names": ["Lightning Bolt", "Shock", "Thoughtseize"]
+  }'
+```
+
+### Check Import Status
+
+```bash
+curl http://localhost:5555/api/v1/card-import/status \
+  -H "Authorization: Bearer <token>"
+```
+
+### Get Import Summary
+
+```bash
+curl http://localhost:5555/api/v1/card-import/summary \
+  -H "Authorization: Bearer <token>"
+```
+
+### Delete Import
+
+```bash
+curl -X DELETE http://localhost:5555/api/v1/card-import/ \
+  -H "Authorization: Bearer <token>"
+```
+
 ## Environment Variables

 | Variable | Default | Description |