Code_of_Conquest/docs/phases/Phase8-Marketplace.md

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:

@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