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](./ADMIN_QUICK_START.md)** - Common tasks and procedures
- **[Full Documentation](./ADMIN_SYSTEM.md)** - Complete API and feature reference
- **[Admin Panel](http://localhost:5173/admin)** - 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`:

```env
ADMIN_STEAM_IDS=76561198000000000,76561198000000001
```

### 3. Promote Users to Admin

Run the make-admin script:

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

Example:
```bash
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

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

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

### Enable Maintenance Mode

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

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

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

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

```bash
# 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](./ADMIN_QUICK_START.md)** - Common tasks
- **[Full Documentation](./ADMIN_SYSTEM.md)** - Complete reference
- **[API Endpoints](./API_ENDPOINTS.md)** - API documentation
- **[Security Features](./SECURITY_FEATURES.md)** - 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*