TurboTrades/ADMIN_README.md

TurboTrades Admin System

A comprehensive admin panel for managing users, site configuration, maintenance mode, announcements, and promotions.

🎯 Quick Links

• Quick Start Guide - Common tasks and procedures
• Full Documentation - Complete API and feature reference
• Admin Panel - Access the dashboard

---

✨ Features

User Management

• 🔍 Search users by username, Steam ID, or email
• 💰 Add/remove user balance with audit trail
• 🔨 Ban/unban users (temporary or permanent)
• 👮 Manage staff levels (0-5)
• 📊 View user statistics and transaction history
• 📦 Bulk user operations

Site Configuration

• 🔧 Maintenance mode with scheduling
• 📢 Site-wide announcements (info, warning, success, error)
• 🎁 Promotional campaigns (deposit bonuses, discounts)
• 💱 Trading settings (fees, limits, toggles)
• 🏪 Market settings (commission, price ranges)
• ⚡ Feature toggles

Dashboard & Analytics

• 📈 Real-time statistics
• 💵 Financial reports
• 📋 Transaction monitoring
• 📦 Item management
• 🔄 Price updates

---

🚀 Setup

1. Install Dependencies

Already included in the main project. The admin system uses:

• Backend: Fastify, MongoDB (Mongoose), UUID
• Frontend: Vue 3, Lucide icons, Vue Toastification

2. Configure Admin Access

Add admin Steam IDs to .env:

ADMIN_STEAM_IDS=76561198000000000,76561198000000001

3. Promote Users to Admin

Run the make-admin script:

node make-admin.js <steamId> <staffLevel>

Example:

node make-admin.js 76561198000000000 5

Staff Levels:

• 0 - Regular User
• 1 - Support Staff
• 2 - Moderator
• 3 - Admin (full access to admin panel)
• 4 - Senior Admin
• 5 - Super Admin (can promote others to admin)

4. Access Admin Panel

Navigate to: http://localhost:5173/admin

You must be authenticated and have staff level 3+ or be in the ADMIN_STEAM_IDS list.

---

📁 File Structure

TurboTrades/
├── models/
│   ├── SiteConfig.js          # Site configuration model
│   ├── PromoUsage.js          # Promotion usage tracking
│   └── User.js                # User model (includes staff level)
│
├── routes/
│   ├── admin.js               # Existing admin routes (prices, etc)
│   ├── admin-management.js    # NEW: User/config management routes
│   └── config.js              # NEW: Public config endpoints
│
├── middleware/
│   └── maintenance.js         # NEW: Maintenance mode middleware
│
├── frontend/src/
│   ├── views/
│   │   └── AdminPage.vue      # Main admin dashboard
│   │
│   └── components/
│       ├── AdminUsersPanel.vue   # NEW: User management
│       └── AdminConfigPanel.vue  # NEW: Site configuration
│
└── docs/
    ├── ADMIN_README.md          # This file
    ├── ADMIN_QUICK_START.md     # Quick reference guide
    └── ADMIN_SYSTEM.md          # Complete documentation

---

🎮 Usage Examples

Search and Ban a User

// 1. Search
const users = await api.get('/admin/users/search', {
  params: { query: 'player123' }
});

// 2. Ban for 7 days
await api.post(`/admin/users/${users.data.users[0]._id}/ban`, {
  banned: true,
  reason: 'Violation of ToS - Item duplication',
  duration: 168 // hours
});

Add User Balance

await api.post('/admin/users/USER_ID/balance', {
  amount: 50.00,
  reason: 'Compensation for bug #1234',
  type: 'add'
});

Enable Maintenance Mode

await api.patch('/admin/config/maintenance', {
  enabled: true,
  message: 'Server maintenance in progress. Back soon!',
  allowedSteamIds: ['76561198000000000'],
  scheduledEnd: '2024-01-01T12:00:00Z'
});

Create Announcement

await api.post('/admin/announcements', {
  type: 'success',
  message: 'New CS2 skins just added to the market!',
  enabled: true,
  dismissible: true,
  endDate: '2024-01-07T23:59:59Z'
});

Create Promotion

await api.post('/admin/promotions', {
  name: 'Weekend Bonus',
  description: 'Get 10% extra on all deposits this weekend!',
  type: 'deposit_bonus',
  enabled: true,
  startDate: '2024-01-06T00:00:00Z',
  endDate: '2024-01-07T23:59:59Z',
  bonusPercentage: 10,
  minDeposit: 10,
  maxBonus: 50,
  maxUsesPerUser: 1
});

---

🔌 API Endpoints

User Management

Method	Endpoint	Description
GET	/api/admin/users/search	Search users
GET	/api/admin/users/:id	Get user details
POST	/api/admin/users/:id/balance	Adjust balance
POST	/api/admin/users/:id/ban	Ban/unban user
POST	/api/admin/users/:id/staff-level	Change staff level
GET	/api/admin/users/:id/transactions	Get user transactions
POST	/api/admin/users/bulk-ban	Bulk ban users

Site Configuration

Method	Endpoint	Description
GET	/api/admin/config	Get site config
PATCH	/api/admin/config/maintenance	Update maintenance mode
PATCH	/api/admin/config/trading	Update trading settings
PATCH	/api/admin/config/market	Update market settings

Announcements

Method	Endpoint	Description
POST	/api/admin/announcements	Create announcement
PATCH	/api/admin/announcements/:id	Update announcement
DELETE	/api/admin/announcements/:id	Delete announcement
GET	/api/config/announcements	Get active (public)

Promotions

Method	Endpoint	Description
GET	/api/admin/promotions	List all promotions
POST	/api/admin/promotions	Create promotion
PATCH	/api/admin/promotions/:id	Update promotion
DELETE	/api/admin/promotions/:id	Delete promotion
GET	/api/admin/promotions/:id/usage	Get usage stats
POST	/api/config/validate-promo	Validate promo code (public)

Public Config

Method	Endpoint	Description
GET	/api/config/public	Get public config
GET	/api/config/status	Get site status
GET	/api/config/announcements	Get active announcements
GET	/api/config/promotions	Get active promotions

---

🛡️ Security

Authentication

All admin endpoints require:

1. Valid JWT token in Authorization header
2. User has staff level 3+ OR Steam ID in ADMIN_STEAM_IDS

Audit Trail

All admin actions are logged with:

• Admin username and ID
• Action performed
• Timestamp
• Target user (if applicable)
• Reason provided

Best Practices

• ✅ Enable 2FA on admin accounts
• ✅ Use strong, unique passwords
• ✅ Review admin logs regularly
• ✅ Only promote trusted users to admin
• ✅ Document significant actions
• ❌ Never share admin credentials
• ❌ Don't make changes without reason

---

🧪 Testing

Test Admin Features

# 1. Start the backend
npm start

# 2. Start the frontend
cd frontend
npm run dev

# 3. Login with admin account
# 4. Navigate to /admin
# 5. Test each feature

Test Maintenance Mode

# Enable maintenance via API
curl -X PATCH http://localhost:3000/api/admin/config/maintenance \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Try accessing site as regular user (should see maintenance message)
# Access site as admin (should work normally)

# Disable maintenance
curl -X PATCH http://localhost:3000/api/admin/config/maintenance \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

---

🔧 Troubleshooting

Can't access admin panel

Problem: Getting 403 Forbidden Solution:

• Check if your account has staff level 3+
• Verify your Steam ID is in ADMIN_STEAM_IDS
• Clear browser cache and re-login

Maintenance mode not working

Problem: Users can still access site during maintenance Solution:

• Verify middleware is registered in index.js
• Check scheduled dates are correct
• Clear any caching layers
• Check browser console for errors

Promotion not applying

Problem: Users report promo code not working Solution:

• Verify promotion is enabled
• Check start/end dates
• Verify user meets requirements (new user only, min deposit, etc.)
• Check usage limits haven't been reached
• Validate promo code spelling

Balance adjustment failed

Problem: Can't adjust user balance Solution:

• Verify user ID is correct
• Check amount is positive number
• Ensure reason is provided (min 3 chars)
• Check user has sufficient balance (for removals)

---

📊 Monitoring

Dashboard Metrics

Monitor these key metrics daily:

• Total users & new registrations
• Active items & listings
• Transaction volume & value
• Failed transactions
• Support tickets
• System errors

Financial Reports

Weekly financial review:

• Total deposits & withdrawals
• Market commission earned
• Promotion bonuses given
• Net profit/loss
• Outstanding balances

---

🚀 Deployment

Production Checklist

• Set secure ADMIN_STEAM_IDS in production .env
• Enable 2FA for all admin accounts
• Set up admin action logging
• Configure rate limiting on admin endpoints
• Set up monitoring and alerts
• Document emergency procedures
• Train staff on admin features
• Set up backup admin access
• Review security best practices
• Test maintenance mode workflow

---

📚 Additional Resources

• Quick Start Guide - Common tasks
• Full Documentation - Complete reference
• API Endpoints - API documentation
• Security Features - Security guide

---

🤝 Contributing

When adding admin features:

1. Follow existing code patterns
2. Add appropriate authorization checks
3. Log all significant actions
4. Update documentation
5. Add error handling
6. Test thoroughly

---

📝 Version History

v1.0.0 (Initial Release)

• User management system
• Site configuration panel
• Maintenance mode
• Announcements system
• Promotions system
• Trading & market settings
• Dashboard & analytics

---

📞 Support

For questions or issues:

1. Check troubleshooting section
2. Review full documentation
3. Check server logs (backend.log)
4. Contact senior admin or development team

---

⚖️ License

Part of the TurboTrades platform. Internal use only.

---

Made with ❤️ for TurboTrades

Last Updated: 2024