feat: Complete admin panel implementation

- Add user management system with all CRUD operations - Add promotion statistics dashboard with export - Simplify Trading & Market settings UI - Fix promotion schema (dates now optional) - Add missing API endpoints and PATCH support - Add comprehensive documentation - Fix critical bugs (deletePromotion, duplicate endpoints) All features tested and production-ready.
2026-01-10 21:57:55 +00:00
parent b90cdd59df
commit 63c578b0ae
52 changed files with 21810 additions and 61 deletions
--- a/ADMIN_SYSTEM.md
+++ b/ADMIN_SYSTEM.md
@@ -0,0 +1,675 @@
+# 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.