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.
This commit is contained in:
2026-01-10 21:57:55 +00:00
parent b90cdd59df
commit 63c578b0ae
52 changed files with 21810 additions and 61 deletions

View File

@@ -0,0 +1,692 @@
# 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