TurboTrades/docs/ADMIN_PANEL_COMPLETE.md

Admin Panel - Complete Implementation Guide

Overview

The TurboTrades Admin Panel is a comprehensive administrative interface for managing all aspects of the platform. This document outlines all implemented features, their usage, and technical details.

---

Table of Contents

1. Features Overview
2. Admin Panel Tabs
3. Backend API Endpoints
4. Component Architecture
5. Usage Guide
6. Troubleshooting

---

Features Overview

✅ Fully Implemented Features

1. Maintenance Mode Management

   • Enable/disable site-wide maintenance
   • Custom maintenance messages
   • Admin bypass with Steam ID whitelist
   • Scheduled maintenance with start/end times

2. Announcement System

   • Create, edit, and delete announcements
   • Multiple announcement types (info, warning, success, error)
   • Scheduled announcements with start/end dates
   • Dismissible announcements
   • Real-time display on frontend

3. Promotion Management

   • Create and manage promotional campaigns
   • Multiple promotion types (deposit bonus, discount, free item, custom)
   • Usage tracking and statistics
   • Promo code validation
   • User-specific usage limits
   • Detailed analytics dashboard

4. Trading & Market Settings

   • Enable/disable trading features
   • Configure deposit and withdrawal settings
   • Set commission rates
   • Price limits and auto-update intervals
   • Fee management

5. User Management

   • Search and filter users
   • View detailed user profiles
   • Balance adjustments with audit trail
   • Ban/unban users with reasons
   • Staff level management
   • Transaction history viewing

---

Admin Panel Tabs

1. Maintenance Tab

Purpose: Control site-wide maintenance mode and access restrictions.

Features:

• Toggle maintenance mode on/off
• Custom maintenance message
• Admin Steam ID whitelist for bypass
• Scheduled maintenance windows
• Real-time status indicator

Form Fields:

{
  enabled: Boolean,
  message: String,
  allowedSteamIds: Array<String>,
  scheduledStart: Date (optional),
  scheduledEnd: Date (optional)
}

API Endpoint: PATCH /api/admin/config/maintenance

---

2. Announcements Tab

Purpose: Create and manage site-wide announcements displayed to users.

Features:

• Create new announcements with type selection
• Edit existing announcements
• Delete announcements with confirmation modal
• Schedule announcements
• Enable/disable individual announcements
• Set dismissibility

Announcement Types:

• info - General information (blue)
• warning - Important warnings (yellow)
• success - Success messages (green)
• error - Critical alerts (red)

Form Fields:

{
  type: String (info|warning|success|error),
  message: String,
  enabled: Boolean,
  dismissible: Boolean,
  startDate: Date (optional),
  endDate: Date (optional)
}

API Endpoints:

• POST /api/admin/announcements - Create
• PUT /api/admin/announcements/:id - Update
• DELETE /api/admin/announcements/:id - Delete
• GET /api/config/announcements - Get active (public)

---

3. Promotions Tab

Purpose: Manage promotional campaigns and track their performance.

Features:

• Create promotion campaigns
• Edit existing promotions
• Delete promotions
• View detailed statistics
• Track usage and conversions
• Export promotion data

Promotion Types:

• deposit_bonus - Bonus on deposits
• discount - Percentage discount
• free_item - Free item giveaway
• custom - Custom promotion type

Form Fields:

{
  name: String,
  description: String,
  type: String,
  enabled: Boolean,
  startDate: Date,
  endDate: Date,
  bonusPercentage: Number,
  bonusAmount: Number,
  minDeposit: Number,
  maxBonus: Number,
  discountPercentage: Number,
  maxUsesPerUser: Number,
  maxTotalUses: Number,
  newUsersOnly: Boolean,
  code: String (optional),
  bannerImage: String (optional)
}

API Endpoints:

• POST /api/admin/promotions - Create
• GET /api/admin/promotions - List all with stats
• PUT /api/admin/promotions/:id - Update
• DELETE /api/admin/promotions/:id - Delete
• GET /api/admin/promotions/:id/stats - Get statistics
• GET /api/admin/promotions/:id/usage - Get usage details

Promotion Statistics Modal:

• Total uses
• Unique users
• Total bonus given
• Average bonus per use
• Usage rate
• Recent usage table with user details
• Export functionality (JSON format)

---

4. Trading & Market Tab

Purpose: Configure trading and marketplace settings.

Trading Settings:

{
  enabled: Boolean,
  depositEnabled: Boolean,
  withdrawEnabled: Boolean,
  minDeposit: Number,
  minWithdraw: Number,
  withdrawFee: Number (0-1, percentage),
  maxItemsPerTrade: Number
}

Market Settings:

{
  enabled: Boolean,
  commission: Number (0-1, percentage),
  minListingPrice: Number,
  maxListingPrice: Number,
  autoUpdatePrices: Boolean,
  priceUpdateInterval: Number (milliseconds)
}

API Endpoints:

• PATCH /api/admin/config/trading - Update trading settings
• PATCH /api/admin/config/market - Update market settings

---

5. User Management Tab

Purpose: Manage users, permissions, and account actions.

Features:

• Search users by username, Steam ID, or email
• View detailed user profiles
• Adjust user balances with reasons
• Ban/unban users
• Set staff levels (User, Moderator, Support, Admin, Super Admin)
• View transaction history
• Real-time user statistics

User Actions:

1. View Details - Full user profile with statistics
2. Adjust Balance - Add or subtract funds with audit trail
3. Ban User - Ban with reason and optional duration
4. Unban User - Remove ban
5. Promote User - Set staff level

Balance Adjustment:

{
  type: String (credit|debit),
  amount: Number,
  reason: String
}

Ban User:

{
  banned: Boolean,
  reason: String,
  duration: Number (hours, 0 = permanent)
}

Staff Levels:

• 0 - Regular User
• 1 - Moderator
• 2 - Support
• 3 - Admin
• 4 - Super Admin

API Endpoints:

• GET /api/admin/users/search - Search users
• GET /api/admin/users/:id - Get user details
• GET /api/admin/users/:id/stats - Get user statistics
• GET /api/admin/users/:id/transactions - Get transactions
• PATCH /api/admin/users/:id/balance - Adjust balance
• PATCH /api/admin/users/:id/ban - Ban/unban user
• PATCH /api/admin/users/:id/staff-level - Update staff level

---

Backend API Endpoints

Configuration Endpoints

GET    /api/admin/config                    - Get all configuration
PATCH  /api/admin/config/maintenance        - Update maintenance settings
PATCH  /api/admin/config/trading            - Update trading settings
PATCH  /api/admin/config/market             - Update market settings

Announcement Endpoints

POST   /api/admin/announcements             - Create announcement
PUT    /api/admin/announcements/:id         - Update announcement
DELETE /api/admin/announcements/:id         - Delete announcement
GET    /api/config/announcements            - Get active announcements (public)

Promotion Endpoints

POST   /api/admin/promotions                - Create promotion
GET    /api/admin/promotions                - List all promotions
PUT    /api/admin/promotions/:id            - Update promotion
DELETE /api/admin/promotions/:id            - Delete promotion
GET    /api/admin/promotions/:id/stats      - Get promotion statistics
GET    /api/admin/promotions/:id/usage      - Get promotion usage details
GET    /api/config/promotions               - Get active promotions (public)
POST   /api/config/validate-promo           - Validate promo code (public)

User Management Endpoints

GET    /api/admin/users/search              - Search users
GET    /api/admin/users/:id                 - Get user details
GET    /api/admin/users/:id/stats           - Get user statistics
GET    /api/admin/users/:id/transactions    - Get user transactions
PATCH  /api/admin/users/:id/balance         - Adjust user balance
PATCH  /api/admin/users/:id/ban             - Ban/unban user
PATCH  /api/admin/users/:id/staff-level     - Update staff level

---

Component Architecture

Main Components

1. AdminConfigPanel.vue

   • Main container component
   • Tab navigation
   • State management for all sections
   • Integrates all sub-components

2. PromotionStatsModal.vue

   • Displays detailed promotion statistics
   • Shows usage history with user information
   • Export functionality
   • Real-time data loading

3. UserManagementTab.vue

   • Complete user management interface
   • Search and filter functionality
   • Multiple modals for different actions
   • Real-time user data

4. ConfirmModal.vue

   • Reusable confirmation modal
   • Used for delete operations
   • Customizable messages and styles

5. ToggleSwitch.vue

   • Reusable toggle component
   • Used for boolean settings

Component Hierarchy

AdminConfigPanel
├── ConfirmModal (delete confirmations)
├── PromotionStatsModal (promotion analytics)
├── Tab: Maintenance
│   ├── ToggleSwitch (enabled)
│   ├── Form fields
│   └── Save button
├── Tab: Announcements
│   ├── Announcement list
│   ├── Create/Edit modal
│   └── Delete with ConfirmModal
├── Tab: Promotions
│   ├── Promotion cards
│   ├── Create/Edit modal
│   ├── Stats button → PromotionStatsModal
│   └── Delete button
├── Tab: Trading & Market
│   ├── Trading form
│   └── Market form
└── Tab: User Management
    └── UserManagementTab
        ├── Search bar
        ├── User list
        ├── Details modal
        ├── Balance adjustment modal
        ├── Ban modal
        └── Promote modal

---

Usage Guide

Accessing the Admin Panel

1. Log in with an admin account (staffLevel >= 3)
2. Navigate to the admin section
3. Select the desired tab

Creating an Announcement

1. Go to Announcements tab
2. Click + Create Announcement
3. Select announcement type
4. Enter message
5. Configure settings:
   • Enable/disable
   • Set dismissibility
   • Optional: Schedule with start/end dates
6. Click Save

Managing Promotions

1. Go to Promotions tab
2. Click + Create Promotion
3. Fill in promotion details:
   • Name and description
   • Type (deposit_bonus, discount, etc.)
   • Date range
   • Bonus/discount settings
   • Usage limits
   • Optional: Promo code
4. Click Save

Viewing Promotion Stats:

• Click the Stats button on any promotion card
• View detailed analytics including:
  • Total uses
  • Unique users
  • Revenue impact
  • Recent usage
• Export data for further analysis

Adjusting User Balance

1. Go to User Management tab
2. Search for user
3. Click Balance button
4. Select adjustment type (Credit/Debit)
5. Enter amount and reason
6. Preview new balance
7. Confirm adjustment

Banning a User

1. Go to User Management tab
2. Search for user
3. Click Ban button
4. Enter ban reason (required)
5. Set duration in hours (0 = permanent)
6. Confirm ban

Note: Banned users are immediately logged out and cannot access the site until unbanned.

Configuring Maintenance Mode

1. Go to Maintenance tab
2. Toggle maintenance mode on
3. Set custom message
4. Add admin Steam IDs for bypass (optional)
5. Configure scheduled maintenance (optional)
6. Save settings

Admin Bypass: Admins with whitelisted Steam IDs can still access the site during maintenance by logging in through the maintenance page.

---

Data Models

SiteConfig Model

{
  maintenance: {
    enabled: Boolean,
    message: String,
    allowedSteamIds: [String],
    scheduledStart: Date,
    scheduledEnd: Date
  },
  announcements: [{
    id: String,
    type: String,
    message: String,
    enabled: Boolean,
    startDate: Date,
    endDate: Date,
    dismissible: Boolean,
    createdBy: String,
    createdAt: Date
  }],
  promotions: [{
    id: String,
    name: String,
    description: String,
    type: String,
    enabled: Boolean,
    startDate: Date,
    endDate: Date,
    bonusPercentage: Number,
    bonusAmount: Number,
    minDeposit: Number,
    maxBonus: Number,
    discountPercentage: Number,
    maxUsesPerUser: Number,
    maxTotalUses: Number,
    currentUses: Number,
    newUsersOnly: Boolean,
    code: String,
    bannerImage: String,
    createdBy: String,
    createdAt: Date
  }],
  trading: {
    enabled: Boolean,
    depositEnabled: Boolean,
    withdrawEnabled: Boolean,
    minDeposit: Number,
    minWithdraw: Number,
    withdrawFee: Number,
    maxItemsPerTrade: Number
  },
  market: {
    enabled: Boolean,
    commission: Number,
    minListingPrice: Number,
    maxListingPrice: Number,
    autoUpdatePrices: Boolean,
    priceUpdateInterval: Number
  }
}

PromoUsage Model

{
  userId: ObjectId (ref: User),
  promoId: String,
  promoCode: String,
  promoName: String,
  promoType: String,
  bonusAmount: Number,
  discountAmount: Number,
  transactionId: ObjectId (ref: Transaction),
  depositAmount: Number,
  usedAt: Date,
  ipAddress: String
}

---

Troubleshooting

Common Issues

1. Changes not saving

• Check console for error messages
• Verify admin permissions (staffLevel >= 3)
• Ensure all required fields are filled
• Check network connection

2. Announcements not displaying

• Verify announcement is enabled
• Check start/end date range
• Ensure frontend is fetching from correct endpoint
• Clear browser cache

3. Maintenance mode issues

• Verify middleware is properly registered
• Check Steam ID format in whitelist
• Test with non-admin account
• Review maintenance middleware logs

4. Promotion stats not loading

• Verify promotion ID is correct
• Check PromoUsage collection exists
• Ensure stats endpoint is accessible
• Review backend logs for errors

5. User search not working

• Check search query syntax
• Verify database indexes exist
• Ensure proper permissions
• Test with different search terms

Debug Mode

Enable detailed logging:

// Backend (index.js)
console.log('🔍 Debug: Admin action', { user, action, data });

// Frontend (AdminConfigPanel.vue)
console.log('🔍 Debug: Form state', formData);

API Testing

Test endpoints using curl:

# Get config
curl -X GET http://localhost:3000/api/admin/config \
  -H "Authorization: Bearer YOUR_TOKEN"

# Update maintenance
curl -X PATCH http://localhost:3000/api/admin/config/maintenance \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "message": "Maintenance test"}'

# Search users
curl -X GET "http://localhost:3000/api/admin/users/search?query=john" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Security Considerations

1. Authentication Required: All admin endpoints require authentication and admin privileges
2. Audit Trail: Balance adjustments and bans are logged with admin information
3. Input Validation: All inputs are validated on backend
4. Rate Limiting: Consider implementing rate limits for admin actions
5. HTTPS Only: Admin panel should only be accessible over HTTPS in production

---

Future Enhancements

Potential features to add:

1. Audit Log Viewer

   • View all admin actions
   • Filter by admin, action type, date
   • Export audit logs

2. Advanced Analytics

   • Revenue charts
   • User growth graphs
   • Conversion funnels

3. Bulk Operations

   • Bulk user actions
   • Batch announcement creation
   • Mass balance adjustments

4. Email Notifications

   • Notify users of promotions
   • Send maintenance notifications
   • Alert admins of important events

5. Role-Based Permissions

   • Fine-grained permission system
   • Custom role creation
   • Permission templates

6. Scheduled Tasks

   • Automatic promotion activation
   • Scheduled announcements
   • Recurring maintenance windows

---

Support

For issues or questions:

1. Check this documentation
2. Review console logs (browser and server)
3. Check the troubleshooting section
4. Contact development team

---

Changelog

Version 1.0.0 (Current)

• ✅ Complete maintenance mode system
• ✅ Full announcement management
• ✅ Comprehensive promotion system with analytics
• ✅ Trading and market configuration
• ✅ User management with all CRUD operations
• ✅ Promotion statistics modal with export
• ✅ Real-time data updates
• ✅ Mobile-responsive design
• ✅ Complete API documentation

---

Last Updated: 2024 Maintained By: TurboTrades Development Team