pawctioneer-bot/README.md

# Telegram Auction Bot - Complete Project Specification

## Project Overview

A Telegram bot for managing various types of auctions, built in Rust using SQLite as the backend database. The bot facilitates auctions between sellers and buyers without handling payments directly.

See a list of user stories for the project under `backlog/docs/user-stories.md`.

## Core Features

### Listing Types
1. **Basic Auctions**: Traditional time-based bidding with anti-sniping protection
2. **Multi-slot Auctions**: Multiple winners (e.g., 3 commission slots available)
3. **Fixed Price Listing**: Set price with limited quantity
4. **Blind Auctions**: Bidders submit amounts with descriptions; seller chooses winner (not necessarily highest bid)

### Key Functionality
- **Telegram Bot**: The bot is interacted with primarily through Telegram. Sellers can create listings, and view bids on listings. Buyers can bid on listings and view their bids.
- **Proxy/Automatic Bidding**: Users set maximum bid; system auto-bids up to that amount
- **Anti-sniping Protection**: Configurable time extension if bid placed in last N minutes
- **Buy-now Option**: Instant purchase at fixed price
- **Media Support**: Multiple images/videos per listing on the telegram post.
- **Outbid Notifications**: Configurable user notifications
- **Non-payment Handling**: Track failed payments, allow selection of next highest bidder
- **Localization Support**: Multi-language structure (to be implemented)
- **Admin Interface**: Separate web interface for moderation (to be implemented)

## Key Design Decisions

### 1. Proxy Bid Architecture
- **Proxy bids** are stored as strategies in `proxy_bids` table
- **Actual bids** are events stored in `bids` table
- When a bid is placed, system checks for proxy bids and generates actual bids
- `proxy_bid_id` in bids table is NULL for manual bids, references proxy for auto-generated

### 2. Database Normalization
- No redundant data - everything computed from source
- Winning bid inferred from highest non-cancelled bid
- Last proxy bid amount inferred from bids with that proxy_bid_id

### 3. Multi-slot Auctions
- Single auction with `slots_available > 1`
- Top N bids win (where N = slots_available)
- Each winning bid gets a slot_number

## Project Structure

```
auction-bot/
├── Cargo.toml           # Dependencies
├── .env                 # Environment variables (create from .env.example)
├── migrations/          # SQL migrations
│   └── 001_initial_schema.sql
└── src/
    └── main.rs         # Entry point, bot setup, command router
```

## Current Implementation Status

### ❌ Not Yet Implemented
- Auction creation flow
- Media upload handling
- Bidding flow
- Settings management
- Proxy bidding logic
- Anti-snipe detection and time extension
- Notification system
- Tasks for auction expiry, scheduled to run when the auction ends
- Admin web interface (separate from the bot, uses the same database)
- Auction browsing with pagination
- Bid history viewing
- Localization/i18n

## Critical Implementation Details

### Proxy Bidding Logic
```rust
// When a new bid is placed:
// 1. Insert the actual bid
// 2. Find all active proxy bids for this auction (except current bidder)
// 3. For each proxy that can beat the new bid:
//    - Generate actual bid = current_bid + min_increment
//    - Update proxy's last generated bid
//    - Only one proxy responds per bid event

// When proxy bid is created/updated:
// 1. Upsert proxy bid strategy
// 2. Check current winning bid
// 3. If can beat it, generate immediate bid
```

### Anti-Snipe Logic
```rust
// On each bid:
// 1. auction.ends_at = MAX(auction.ends_at, now + anti_snipe_minutes)
// 2. Notify users of time extension if there was one
```

### Auction State Management
- Consider using `HashMap<user_id, AuctionDraft>` for in-memory draft storage
- Or create `auction_drafts` table for persistence across bot restarts

### Background Tasks Needed
1. **Auction Expiry Checker** (every 30 seconds)
   - Find auctions where `ends_at < now AND is_active = true`
   - Mark as inactive
   - Create winner records
   - Send notifications

2. **Notification Dispatcher** (every 10 seconds)
   - Check notification queue
   - Batch send to avoid rate limits
   - Handle outbid, win, and reminder notifications

## Environment Variables (.env)

```bash
# Required
TELOXIDE_TOKEN=your_bot_token_here
DATABASE_URL=sqlite:pawctioneer_bot.db

# Optional
RUST_LOG=info,pawctioneer_bot=debug
ADMIN_USER_ID=your_telegram_user_id
WEB_PORT=3000  # For future admin interface
TZ=UTC
```

## Bot Commands (Set in BotFather)

```
start - Show welcome message
help - Show help message
newlisting - Create a new listing
mylistings - View your listings as a seller
mybids - View your active bids
settings - Configure notifications
```

## Dependencies Rationale

- **teloxide**: Modern Telegram bot framework with good ergonomics
- **sqlx**: Compile-time checked SQL queries, async support
- **tokio**: Industry standard async runtime
- **rust_decimal**: Proper decimal handling for money

## Next Implementation Steps (Priority Order)

### 1. Complete Listing Creation Flow
- Implement multi-step wizard state machine
- Handle media uploads (store Telegram file_ids)
- Add validation for each field
- Create listing in database

### 2. Implement Bidding System
- Place manual bid function
- Proxy bid creation and processing
- Bid validation (minimum amounts, increment checks)
- Update auction message after each bid

### 3. Add Background Tasks
- Tokio spawn for periodic tasks
- Auction expiry processing
- Notification sending

### 4. Listing Browsing
- Paginated list with filters
- Search functionality
- Detailed listing view with bid history

### 5. Admin Interface
- Axum web server in same binary
- Dashboard with stats
- User management (bans, warnings)
- Auction moderation tools

## Testing Checklist

- [ ] User registration on first interaction
- [ ] Auction creation (all types)
- [ ] Manual bidding
- [ ] Proxy bidding with conflicts
- [ ] Anti-snipe time extension
- [ ] Buy-now purchase
- [ ] Multi-slot auction with multiple winners
- [ ] Blind auction with description
- [ ] Non-payment flow
- [ ] User ban system
- [ ] Notification delivery
- [ ] Media upload and display

## Telegram API Rate Limits to Consider

- Telegram allows 30 messages/second to different users
- 20 messages/minute to same user
- Bulk notifications should be queued and throttled
- Edit message updates should be debounced