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](#features)
2. [Setup](#setup)
3. [User Management](#user-management)
4. [Site Configuration](#site-configuration)
5. [Maintenance Mode](#maintenance-mode)
6. [Announcements](#announcements)
7. [Promotions](#promotions)
8. [API Reference](#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:

```env
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:

```bash
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:**
```bash
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:**
```javascript
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:**
```json
{
  "amount": 100.00,
  "reason": "Compensation for issue #123",
  "type": "add"  // or "remove"
}
```

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:

```javascript
// 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "code": "WELCOME10"
}
```

---

## Trading & Market Settings

### Update Trading Settings

**Endpoint:** `PATCH /api/admin/config/trading`

**Body:**
```json
{
  "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:**
```json
{
  "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:

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

### Response Format

**Success Response:**
```json
{
  "success": true,
  "message": "Operation completed",
  "data": { ... }
}
```

**Error Response:**
```json
{
  "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

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