ptarrant/Code_of_Conquest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
70b2b0f1244eeb5300dc3cdf916d08a77934d14b
Code_of_Conquest/docs/phases/Phase8-Marketplace.md
Phillip Tarrant df26abd207 feat: Implement Phase 5 Quest System (100% complete) 
Add YAML-driven quest system with context-aware offering:

Core Implementation:
- Quest data models (Quest, QuestObjective, QuestReward, QuestTriggers)
- QuestService for YAML loading and caching
- QuestEligibilityService with level, location, and probability filtering
- LoreService stub (MockLoreService) ready for Phase 6 Weaviate integration

Quest Content:
- 5 example quests across difficulty tiers (2 easy, 2 medium, 1 hard)
- Quest-centric design: quests define their NPC givers
- Location-based probability weights for natural quest offering

AI Integration:
- Quest offering section in npc_dialogue.j2 template
- Response parser extracts [QUEST_OFFER:quest_id] markers
- AI naturally weaves quest offers into NPC conversations

API Endpoints:
- POST /api/v1/quests/accept - Accept quest offer
- POST /api/v1/quests/decline - Decline quest offer
- POST /api/v1/quests/progress - Update objective progress
- POST /api/v1/quests/complete - Complete quest, claim rewards
- POST /api/v1/quests/abandon - Abandon active quest
- GET /api/v1/characters/{id}/quests - List character quests
- GET /api/v1/quests/{quest_id} - Get quest details

Frontend:
- Quest tracker sidebar with HTMX integration
- Quest offer modal for accept/decline flow
- Quest detail modal for viewing progress
- Combat service integration for kill objective tracking

Testing:
- Unit tests for Quest models and serialization
- Integration tests for full quest lifecycle
- Comprehensive test coverage for eligibility service

Documentation:
- Reorganized docs into /docs/phases/ structure
- Added Phase 5-12 planning documents
- Updated ROADMAP.md with new structure

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-29 15:42:55 -06:00

207 lines
6.5 KiB
Markdown
Raw Blame History

# 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** |
Reference in New Issue View Git Blame Copy Permalink