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](#features-overview)
2. [Admin Panel Tabs](#admin-panel-tabs)
3. [Backend API Endpoints](#backend-api-endpoints)
4. [Component Architecture](#component-architecture)
5. [Usage Guide](#usage-guide)
6. [Troubleshooting](#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**:
```javascript
{
  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**:
```javascript
{
  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**:
```javascript
{
  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**:
```javascript
{
  enabled: Boolean,
  depositEnabled: Boolean,
  withdrawEnabled: Boolean,
  minDeposit: Number,
  minWithdraw: Number,
  withdrawFee: Number (0-1, percentage),
  maxItemsPerTrade: Number
}
```

**Market Settings**:
```javascript
{
  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**:
```javascript
{
  type: String (credit|debit),
  amount: Number,
  reason: String
}
```

**Ban User**:
```javascript
{
  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

```javascript
{
  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

```javascript
{
  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:

```javascript
// 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:

```bash
# 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