# Phase 8: Marketplace

**Goal:** Player-to-player trading system (Premium+ only)
**Priority:** Medium
**Status:** Not Started
**Last Updated:** November 29, 2025

---

## Overview

The Marketplace enables Premium and Elite players to trade items with each other through auctions and fixed-price listings. This creates a player economy and provides an additional incentive for premium subscriptions.

**Key Features:**
- Premium/Elite tier only
- Auction and fixed-price (buyout) listings
- 48-hour listing duration
- 5% marketplace fee on sales
- Bidding with outbid notifications
- Search and filter functionality

---

## Task Groups

### Marketplace Data Models (3 tasks)

| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 8.1 | Create MarketplaceListing dataclass | ⬜ | Item, seller, price, auction settings, expiration |
| 8.2 | Create Bid dataclass | ⬜ | Bidder, amount, timestamp |
| 8.3 | **Checkpoint:** Verify serialization | ⬜ | Test round-trip to JSON, Appwrite storage |

**Listing Structure:**
```python
@dataclass
class MarketplaceListing:
    listing_id: str
    seller_id: str
    item: Item
    listing_type: str  # "auction" | "fixed_price"
    starting_price: int
    buyout_price: Optional[int]
    current_bid: Optional[int]
    current_bidder_id: Optional[str]
    bids: List[Bid]
    created_at: datetime
    expires_at: datetime
    status: str  # "active" | "sold" | "expired" | "cancelled"
```

**Deliverable:** Marketplace data models ready

---

### Marketplace APIs (6 tasks)

| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 8.4 | Implement browse API | ⬜ | `GET /api/v1/marketplace` - Filtering, sorting, pagination |
| 8.5 | Implement listing creation API | ⬜ | `POST /api/v1/marketplace/listings` - Auction + fixed price |
| 8.6 | Implement bidding API | ⬜ | `POST /api/v1/marketplace/listings/{id}/bid` - Validate bid amounts |
| 8.7 | Implement buyout API | ⬜ | `POST /api/v1/marketplace/listings/{id}/buyout` - Instant purchase |
| 8.8 | Implement listing cancellation | ⬜ | `DELETE /api/v1/marketplace/listings/{id}` - Return item to seller |
| 8.9 | Implement my listings/bids API | ⬜ | `GET /api/v1/marketplace/my-listings`, `/my-bids` |

**Deliverable:** Full marketplace API

---

### Auction Processing (3 tasks)

| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 8.10 | Implement auction processing task | ⬜ | Periodic RQ job to end expired auctions |
| 8.11 | Implement bid notifications | ⬜ | Notify when outbid (in-app notification) |
| 8.12 | Implement sale completion | ⬜ | Transfer item, gold minus 5% fee |

**Auction Processing Flow:**
```
Every 5 minutes:
  1. Query listings where expires_at <= now AND status = 'active'
  2. For each expired listing:
     - If has bids: Award to highest bidder, transfer gold (minus fee)
     - If no bids: Return item to seller, mark expired
  3. Send notifications to winners/sellers
```

**Deliverable:** Automated auction resolution

---

### Marketplace UI (4 tasks)

| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 8.13 | Create marketplace browse UI | ⬜ | `templates/marketplace/browse.html` - Grid/list view, filters |
| 8.14 | Create listing detail UI | ⬜ | `templates/marketplace/detail.html` - Item, bids, timer |
| 8.15 | Create listing creation UI | ⬜ | `templates/marketplace/create.html` - Form for creating listings |
| 8.16 | Create my listings/bids UI | ⬜ | `templates/marketplace/my-listings.html` |

**Deliverable:** Full marketplace UI

---

### Testing & Validation (3 tasks)

| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 8.17 | Test auction flow | ⬜ | Full auction cycle: list → bid → expire → award |
| 8.18 | Test tier restrictions | ⬜ | Verify Premium+ only |
| 8.19 | **Final Checkpoint:** Integration test | ⬜ | Complete buy/sell flow |

**Deliverable:** Validated marketplace system

---

## API Endpoints Summary

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/marketplace` | Browse listings (filter, sort, paginate) |
| `GET` | `/api/v1/marketplace/listings/{id}` | Get listing detail |
| `POST` | `/api/v1/marketplace/listings` | Create new listing |
| `POST` | `/api/v1/marketplace/listings/{id}/bid` | Place bid |
| `POST` | `/api/v1/marketplace/listings/{id}/buyout` | Instant purchase |
| `DELETE` | `/api/v1/marketplace/listings/{id}` | Cancel listing |
| `GET` | `/api/v1/marketplace/my-listings` | Get user's listings |
| `GET` | `/api/v1/marketplace/my-bids` | Get user's active bids |

---

## Files to Create/Modify

**New Files:**
- `/api/app/models/marketplace.py` - MarketplaceListing, Bid
- `/api/app/services/marketplace_service.py` - Marketplace operations
- `/api/app/api/marketplace.py` - Marketplace API blueprint
- `/api/app/tasks/marketplace_tasks.py` - Auction processing job
- `/public_web/templates/marketplace/browse.html`
- `/public_web/templates/marketplace/detail.html`
- `/public_web/templates/marketplace/create.html`
- `/public_web/templates/marketplace/my-listings.html`

**Modified Files:**
- `/api/app/__init__.py` - Register marketplace blueprint
- `/api/app/services/character_service.py` - Gold transfer, item transfer

---

## Testing Criteria

### Unit Tests
- [ ] Listing creation validation
- [ ] Bid validation (must exceed current bid)
- [ ] Buyout validation (sufficient gold)
- [ ] Fee calculation (5%)

### Integration Tests
- [ ] Create listing → item removed from inventory
- [ ] Place bid → gold held in escrow
- [ ] Outbid → gold returned to previous bidder
- [ ] Auction ends → item transferred, gold transferred
- [ ] Cancel listing → item returned

### Manual Testing
- [ ] Browse and filter listings
- [ ] Create auction and fixed-price listings
- [ ] Bid on auctions
- [ ] Buyout items
- [ ] Check notifications when outbid

---

## Success Criteria

- [ ] Premium/Elite tier restriction enforced
- [ ] Listings created and displayed correctly
- [ ] Bidding works with proper validation
- [ ] Buyout works with instant purchase
- [ ] Auctions expire and resolve correctly
- [ ] 5% fee deducted on sales
- [ ] Notifications sent when outbid
- [ ] UI is responsive and functional

---

## Dependencies

**Requires (already implemented):**
- Character system (inventory, gold)
- Item system
- Authentication with tiers

---

## Task Summary

| Group | Tasks | Checkpoints |
|-------|-------|-------------|
| Marketplace Data Models | 2 | 1 |
| Marketplace APIs | 6 | 0 |
| Auction Processing | 3 | 0 |
| Marketplace UI | 4 | 0 |
| Testing & Validation | 2 | 1 |
| **Total** | **17** | **2** |