TurboTrades/ADMIN_SYSTEM.md

TurboTrades Admin System Documentation

Overview

The TurboTrades admin system provides comprehensive administrative controls for managing users, site configuration, maintenance mode, announcements, and promotions.

Table of Contents

1. Features
2. Setup
3. User Management
4. Site Configuration
5. Maintenance Mode
6. Announcements
7. Promotions
8. API Reference

---

Features

User Management

• ✅ Search users by username, Steam ID, or email
• ✅ View detailed user information and statistics
• ✅ Add or remove user balance
• ✅ Ban/unban users (permanent or temporary)
• ✅ Manage staff levels (0-5)
• ✅ View user transaction history
• ✅ Bulk user operations

Site Configuration

• ✅ Maintenance mode with scheduled start/end
• ✅ Site-wide announcements
• ✅ Promotional campaigns
• ✅ Trading settings (deposits, withdrawals, fees)
• ✅ Market settings (commission, price limits)
• ✅ Feature toggles

Administration Tools

• ✅ Real-time dashboard
• ✅ Financial analytics
• ✅ Transaction monitoring
• ✅ Price management
• ✅ System health checks

---

Setup

1. Set Admin Steam IDs

Add admin Steam IDs to your .env file:

ADMIN_STEAM_IDS=76561198000000000,76561198000000001,76561198000000002

Multiple Steam IDs should be comma-separated.

2. Set User Staff Levels

Use the provided script to promote users to admin:

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

Staff Levels:

• 0 - Regular User (default)
• 1 - Support Staff
• 2 - Moderator
• 3 - Admin
• 4 - Senior Admin
• 5 - Super Admin

Example:

node make-admin.js 76561198000000000 5

3. Access Admin Panel

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

Only users with staff level 3+ or listed in ADMIN_STEAM_IDS can access the admin panel.

---

User Management

Search Users

Endpoint: GET /api/admin/users/search

Query Parameters:

• query - Search term (username, Steam ID, or email)
• limit - Maximum results (default: 20)

Example:

const response = await api.get('/admin/users/search', {
  params: { query: 'john', limit: 20 }
});

Get User Details

Endpoint: GET /api/admin/users/:id

Returns detailed user information including transaction statistics.

Adjust User Balance

Endpoint: POST /api/admin/users/:id/balance

Body:

{
  "amount": 100.00,
  "reason": "Compensation for issue #123",
  "type": "add"  // or "remove"
}

Response:

{
  "success": true,
  "message": "Successfully added $100.00",
  "user": {
    "id": "...",
    "username": "player1",
    "balance": 250.00
  },
  "transaction": {
    "id": "...",
    "amount": 100.00,
    "type": "bonus"
  }
}

Ban/Unban User

Endpoint: POST /api/admin/users/:id/ban

Body:

{
  "banned": true,
  "reason": "Violation of terms of service",
  "duration": 168  // hours (0 = permanent)
}

Duration Examples:

• 0 - Permanent ban
• 1 - 1 hour
• 24 - 24 hours
• 168 - 7 days
• 720 - 30 days
• 8760 - 1 year

Change Staff Level

Endpoint: POST /api/admin/users/:id/staff-level

Body:

{
  "level": 3  // 0-5
}

Note: Only Super Admins (level 5) can promote users to admin level (3+).

Bulk Ban Users

Endpoint: POST /api/admin/users/bulk-ban

Body:

{
  "userIds": ["userId1", "userId2", "userId3"],
  "banned": true,
  "reason": "Mass violation",
  "duration": 0
}

---

Site Configuration

Get Site Configuration

Endpoint: GET /api/admin/config

Returns the complete site configuration including maintenance, trading, market settings, etc.

Get Public Configuration

Endpoint: GET /api/config/public

Returns public-facing configuration (no authentication required).

---

Maintenance Mode

Enable/Disable Maintenance

Endpoint: PATCH /api/admin/config/maintenance

Body:

{
  "enabled": true,
  "message": "We're performing scheduled maintenance. Be back soon!",
  "allowedSteamIds": ["76561198000000000"],
  "scheduledStart": "2024-01-01T00:00:00Z",
  "scheduledEnd": "2024-01-01T04:00:00Z"
}

Maintenance Features

• Scheduled Maintenance: Set start and end times for automatic activation
• Whitelist: Allow specific Steam IDs to access during maintenance
• Custom Message: Display a custom message to users
• Admin Bypass: Staff level 3+ automatically bypass maintenance

Middleware Integration

The maintenance middleware automatically checks all requests:

// In index.js, add to your routes:
import { checkMaintenance } from './middleware/maintenance.js';

fastify.addHook('preHandler', checkMaintenance);

Exempt Endpoints:

• /health
• /api/health
• /api/config/public

---

Announcements

Create Announcement

Endpoint: POST /api/admin/announcements

Body:

{
  "type": "info",  // info, warning, success, error
  "message": "New features coming this weekend!",
  "enabled": true,
  "dismissible": true,
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-01-07T23:59:59Z"
}

Update Announcement

Endpoint: PATCH /api/admin/announcements/:id

Delete Announcement

Endpoint: DELETE /api/admin/announcements/:id

Get Active Announcements

Endpoint: GET /api/config/announcements

Returns only currently active announcements (public endpoint).

---

Promotions

Promotion Types

1. Deposit Bonus - Give users a percentage bonus on deposits
2. Discount - Reduce prices by a percentage
3. Free Item - Award free items
4. Custom - Custom promotional logic

Create Promotion

Endpoint: POST /api/admin/promotions

Example - 10% Deposit Bonus:

{
  "name": "Welcome Bonus",
  "description": "Get 10% extra on your first deposit!",
  "type": "deposit_bonus",
  "enabled": true,
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z",
  "bonusPercentage": 10,
  "minDeposit": 10.00,
  "maxBonus": 50.00,
  "maxUsesPerUser": 1,
  "maxTotalUses": 1000,
  "newUsersOnly": true,
  "code": "WELCOME10"
}

Promotion Fields

Field	Type	Description
name	string	Promotion name
description	string	Detailed description
type	string	deposit_bonus, discount, free_item, custom
enabled	boolean	Is promotion active
startDate	date	When promotion starts
endDate	date	When promotion ends
bonusPercentage	number	Percentage bonus (0-100)
bonusAmount	number	Fixed bonus amount
minDeposit	number	Minimum deposit required
maxBonus	number	Maximum bonus cap
discountPercentage	number	Discount percentage
maxUsesPerUser	number	Uses per user
maxTotalUses	number	Total uses allowed (null = unlimited)
newUsersOnly	boolean	Only for new users
code	string	Optional promo code

Update Promotion

Endpoint: PATCH /api/admin/promotions/:id

Delete Promotion

Endpoint: DELETE /api/admin/promotions/:id

Get Promotion Usage Stats

Endpoint: GET /api/admin/promotions/:id/usage

Query Parameters:

• limit - Results per page (default: 50)
• skip - Pagination offset (default: 0)

Response:

{
  "success": true,
  "usages": [...],
  "stats": {
    "totalUses": 450,
    "totalBonusGiven": 2250.00,
    "uniqueUsers": 430,
    "averageBonusPerUse": 5.00
  },
  "pagination": {
    "total": 450,
    "limit": 50,
    "skip": 0,
    "hasMore": true
  }
}

Validate Promo Code

Endpoint: POST /api/config/validate-promo

Body:

{
  "code": "WELCOME10"
}

---

Trading & Market Settings

Update Trading Settings

Endpoint: PATCH /api/admin/config/trading

Body:

{
  "enabled": true,
  "depositEnabled": true,
  "withdrawEnabled": true,
  "minDeposit": 0.10,
  "minWithdraw": 0.50,
  "withdrawFee": 0.05,
  "maxItemsPerTrade": 50
}

Update Market Settings

Endpoint: PATCH /api/admin/config/market

Body:

{
  "enabled": true,
  "commission": 0.10,
  "minListingPrice": 0.01,
  "maxListingPrice": 100000,
  "autoUpdatePrices": true,
  "priceUpdateInterval": 3600000
}

---

API Reference

Authentication

All admin endpoints require authentication and admin privileges:

headers: {
  'Authorization': 'Bearer <jwt-token>'
}

Response Format

Success Response:

{
  "success": true,
  "message": "Operation completed",
  "data": { ... }
}

Error Response:

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message"
}

Error Codes

Code	Description
401	Authentication required
403	Admin access required
404	Resource not found
400	Invalid request
500	Server error

---

Frontend Components

AdminUsersPanel

User management interface with search, details, and actions.

Location: frontend/src/components/AdminUsersPanel.vue

Features:

• User search
• View user details
• Adjust balance
• Ban/unban users
• Change staff levels
• View transactions

AdminConfigPanel

Site configuration management interface.

Location: frontend/src/components/AdminConfigPanel.vue

Tabs:

1. Maintenance - Control maintenance mode
2. Announcements - Manage site announcements
3. Promotions - Create and manage promotions
4. Trading & Market - Configure trading settings

---

Database Models

SiteConfig

Stores all site-wide configuration.

Collection: siteconfigs

Key Fields:

• maintenance - Maintenance mode settings
• announcements - Active announcements
• promotions - Active promotions
• trading - Trading configuration
• market - Market configuration
• features - Feature toggles

PromoUsage

Tracks promotion usage by users.

Collection: promousages

Key Fields:

• userId - User who used the promo
• promoId - Promotion ID
• bonusAmount - Bonus received
• usedAt - Timestamp of usage

---

Best Practices

Security

1. Never expose admin endpoints without authentication
2. Log all admin actions for audit trails
3. Validate all inputs before processing
4. Use staff levels to control access to sensitive operations
5. Implement rate limiting on admin endpoints

User Management

1. Always provide reasons for bans and balance adjustments
2. Use temporary bans when appropriate
3. Review ban appeals regularly
4. Monitor admin activity for abuse

Promotions

1. Set reasonable limits on bonuses and uses
2. Test promotions before making them live
3. Monitor usage to prevent abuse
4. Set clear expiration dates
5. Use promo codes for tracking campaigns

Maintenance

1. Schedule maintenance during low-traffic periods
2. Provide advance notice to users
3. Keep maintenance windows short
4. Test thoroughly before ending maintenance
5. Use the whitelist to allow testing during maintenance

---

Troubleshooting

Users can't see announcements

• Check if announcement is enabled
• Verify start/end dates are correct
• Ensure announcement type is valid
• Check browser console for errors

Promotion not working

• Verify promotion is enabled
• Check start/end dates
• Verify user hasn't exceeded usage limit
• Check if promo code is correct
• Verify user meets all requirements (new user only, min deposit, etc.)

Maintenance mode not activating

• Check if scheduled dates are set correctly
• Verify middleware is registered
• Check config is saved properly
• Clear cache and reload

Balance adjustment failed

• Verify user exists
• Check amount is valid (positive number)
• Ensure reason is provided
• Check for sufficient balance when removing

---

Examples

Full Admin Workflow Example

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

const user = users.data.users[0];

// 2. View user details
const details = await api.get(`/admin/users/${user._id}`);
console.log(details.data.stats);

// 3. Add balance
await api.post(`/admin/users/${user._id}/balance`, {
  amount: 50.00,
  reason: 'Referral bonus',
  type: 'add'
});

// 4. Create announcement
await api.post('/admin/announcements', {
  type: 'success',
  message: 'New CS2 skins added!',
  enabled: true,
  dismissible: true
});

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

// 6. Enable maintenance mode
await api.patch('/admin/config/maintenance', {
  enabled: true,
  message: 'Maintenance in progress. Back in 30 minutes!',
  allowedSteamIds: [process.env.MY_STEAM_ID]
});

---

Support

For issues or questions:

• Check the troubleshooting section
• Review the API reference
• Check server logs for errors
• Contact the development team

---

Changelog

Version 1.0.0 (Initial Release)

• User management (search, ban, balance)
• Site configuration
• Maintenance mode
• Announcements system
• Promotions system
• Trading & market settings
• Frontend admin panels

---

License

Part of the TurboTrades platform.