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>
This commit is contained in:
206
docs/phases/Phase8-Marketplace.md
Normal file
206
docs/phases/Phase8-Marketplace.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# 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
Block a user