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/docs/ADMIN_DEBUG_PANEL.md
+++ b/docs/ADMIN_DEBUG_PANEL.md
@@ -0,0 +1,386 @@
+# Admin Debug Panel Documentation
+
+## Overview
+The Admin Debug Panel is a comprehensive testing and debugging tool integrated into the admin dashboard. It consolidates all system testing, diagnostics, and troubleshooting features in one centralized location.
+
+## Location
+Access the debug panel at: **Admin Dashboard → Debug Tab**
+
+Or directly at: `/admin` (scroll to Debug section)
+
+## Features
+
+### 🔐 Auth & Connectivity Tab
+Tests authentication status and backend connectivity.
+
+#### Authentication Status
+- **Logged In** - Current authentication state
+- **Username** - Current user's display name
+- **Steam ID** - User's Steam ID
+- **Staff Level** - Permission level (0-5)
+- **Is Admin** - Admin status (staffLevel >= 3)
+- **Balance** - Current account balance
+
+#### Backend Connectivity Tests
+Automated tests that run on panel load:
+
+1. **Health Check** - Verifies backend is running
+2. **Auth Check** - Validates user session and cookies
+3. **Admin Config Access** - Tests admin endpoint access
+4. **Admin Routes Access** - Tests user management routes
+
+#### Quick Actions
+- **Refresh Auth** - Reload user authentication data
+- **Clear Cache** - Clear localStorage and sessionStorage
+- **Test Admin Route** - Quick test of admin config endpoint
+- **Copy Debug Info** - Copy all debug data to clipboard (JSON format)
+
+#### Environment Info
+- API Base URL
+- Current Route
+- Window Location
+- User Agent
+
+### 📢 Announcements Tab
+Test and debug announcement system functionality.
+
+#### Status Display
+- **Total Loaded** - Number of announcements fetched
+- **Active** - Announcements passing all filters
+- **Dismissed** - Count of dismissed announcements
+
+#### Announcement List
+Shows all announcements with detailed information:
+- **Type Badge** - Info, Warning, Success, or Error
+- **Enabled Status** - ✅ Enabled or ❌ Disabled
+- **Dismissible Status** - 👋 Dismissible or 🔒 Permanent
+- **Message** - Full announcement text
+- **Metadata** - ID, start date, end date, dismissed status
+
+#### Test Actions
+- **Reload** - Refresh announcements from API
+- **Clear Dismissed** - Remove dismissed IDs from localStorage
+- **Test API** - Direct fetch test bypassing axios
+
+#### API Response Viewer
+Shows raw JSON response from last API call for debugging
+
+### 🔧 Maintenance Tab
+Test maintenance mode functionality and admin bypass.
+
+#### Maintenance Status Card
+Large visual indicator showing:
+- Current maintenance state (Active ⚠️ or Operational ✅)
+- Maintenance message
+- Color-coded based on status
+
+#### Status Information
+- **Maintenance Enabled** - Current state
+- **Scheduled End** - When maintenance will end (if scheduled)
+- **Whitelisted Users** - Count of Steam IDs allowed during maintenance
+
+#### Test Actions
+- **Reload** - Refresh maintenance status
+- **Test Admin Bypass** - Verify admin can access during maintenance
+- **Test User Block** - Instructions to test non-admin blocking
+
+#### Test Results
+Shows results of maintenance tests with pass/fail indicators
+
+### ⚙️ System Tab
+*(Future expansion for system-wide diagnostics)*
+
+Planned features:
+- WebSocket connection status
+- Market price updates
+- Steam bot status
+- Database connection health
+- Cache statistics
+- Performance metrics
+
+## Using the Debug Panel
+
+### Basic Workflow
+
+1. **Navigate to Admin Dashboard**
+   ```
+   http://localhost:5173/admin
+   ```
+
+2. **Click Debug Tab**
+   - Automatically runs connectivity tests
+   - Displays current auth status
+
+3. **Switch Between Tabs**
+   - Each tab auto-loads relevant data
+   - Tests run automatically where applicable
+
+4. **Run Manual Tests**
+   - Click action buttons to run specific tests
+   - View results in real-time
+   - Check console for detailed logs
+
+### Testing Announcements
+
+1. **Navigate to Announcements Tab**
+2. **Check Status Metrics**
+   - Verify announcements are loaded
+   - Check active count vs total
+3. **Review Announcement List**
+   - Ensure enabled state is correct
+   - Verify date ranges
+   - Check for dismissed badges
+4. **Test Actions**
+   - Clear dismissed to reset state
+   - Test API directly to bypass axios
+5. **Check Console Logs**
+   - Look for "📡 Debug: Fetching announcements..."
+   - Verify "✅ Debug: Loaded announcements"
+6. **Compare with Frontend**
+   - Navigate to home page
+   - Verify announcements display correctly
+
+### Testing Maintenance Mode
+
+1. **Navigate to Maintenance Tab**
+2. **Check Current Status**
+   - View status card color
+   - Read maintenance message
+3. **Test Admin Bypass**
+   - Click "Test Admin Bypass"
+   - Should show success ✅
+   - Verify admin can still make API calls
+4. **Test User Block**
+   - Open incognito window
+   - Navigate to site
+   - Should see maintenance page
+5. **Toggle Maintenance**
+   - Go back to Config tab
+   - Enable/disable maintenance
+   - Return to Debug → Maintenance tab
+   - Click reload to verify changes
+
+### Debugging Issues
+
+#### Problem: Announcements Not Showing
+
+1. Go to Debug → Announcements tab
+2. Check "Total Loaded" count
+3. If 0:
+   - Click "Test API" button
+   - Check API Response section
+   - Look for errors in response
+   - Verify backend is running
+4. If loaded but not active:
+   - Check announcement list for disabled badges
+   - Verify dates (may be expired or not started)
+   - Check if dismissed
+5. Check browser console for errors
+
+#### Problem: Admin Actions Blocked During Maintenance
+
+1. Go to Debug → Maintenance tab
+2. Verify maintenance is enabled
+3. Click "Test Admin Bypass"
+4. If fails:
+   - Check Auth tab for admin status
+   - Verify staffLevel >= 3
+   - Check backend logs for maintenance middleware
+   - Verify cookies/tokens are valid
+5. Check Auth & Connectivity tab
+6. Run "Test Admin Route"
+7. Review error messages
+
+#### Problem: Auth Not Working
+
+1. Go to Debug → Auth & Connectivity tab
+2. Check "Logged In" status
+3. Run "Run All Tests" button
+4. Review each test result:
+   - Health Check - backend connectivity
+   - Auth Check - session validity
+   - Admin Config - permission check
+5. Click "Refresh Auth" to reload
+6. If still failing:
+   - Check cookies in browser DevTools
+   - Clear cache and re-login
+   - Check backend logs
+
+## Console Logging
+
+The debug panel outputs detailed console logs:
+
+### Announcements
+```
+🔵 Debug: AnnouncementBanner mounted
+📡 Debug: Fetching announcements...
+✅ Debug: Loaded announcements: [...]
+```
+
+### Maintenance
+```
+✅ Admin [username] bypassing maintenance mode for /api/admin/config
+⚠️ Blocking request during maintenance: /api/market/listings
+```
+
+### Tests
+```
+📡 Response: { success: true, ... }
+✅ Test passed: Health Check
+❌ Test failed: Admin Config Access
+```
+
+## Quick Reference
+
+### Color Codes
+
+| Color | Meaning | Example |
+|-------|---------|---------|
+| 🟢 Green | Success / Active | Logged in, test passed |
+| 🔴 Red | Error / Failed | Not authenticated, test failed |
+| 🟡 Yellow | Warning | Maintenance active |
+| 🔵 Blue | Info | Loading, running |
+| ⚪ Gray | Pending | Test not run yet |
+
+### Staff Levels
+
+| Level | Role | Color | Access |
+|-------|------|-------|--------|
+| 0 | User | Gray | Standard user |
+| 1 | Staff | Orange | Basic staff tools |
+| 2 | Moderator | Green | Moderation tools |
+| 3 | Admin | Blue | Full admin access |
+| 4-5 | Super Admin | Purple | System-level access |
+
+### Common Actions
+
+| Action | Shortcut | Result |
+|--------|----------|--------|
+| Reload Tab Data | Click reload button | Refreshes current tab data |
+| Run All Tests | Click "Run All Tests" | Runs connectivity suite |
+| Clear Cache | Click "Clear Cache" | Clears all storage |
+| Copy Debug Data | Click "Copy Debug Info" | JSON to clipboard |
+
+## Best Practices
+
+### When to Use Debug Panel
+
+✅ **Use debug panel for:**
+- Testing new features before release
+- Diagnosing user-reported issues
+- Verifying admin functionality
+- Checking maintenance mode setup
+- Troubleshooting API connectivity
+- Validating authentication flow
+
+❌ **Don't use debug panel for:**
+- Production monitoring (use proper monitoring tools)
+- Performance profiling (use browser DevTools)
+- Database queries (use backend tools)
+- Security testing (use penetration testing tools)
+
+### Debugging Workflow
+
+1. **Identify Issue** - What's not working?
+2. **Check Relevant Tab** - Auth, Announcements, or Maintenance
+3. **Review Status** - Check metrics and indicators
+4. **Run Tests** - Use action buttons to test
+5. **Check Logs** - Browser console and backend logs
+6. **Copy Debug Info** - Save state for later analysis
+7. **Fix Issue** - Make necessary changes
+8. **Re-test** - Verify fix with debug panel
+
+### Sharing Debug Info
+
+When reporting issues or asking for help:
+
+1. Click "Copy Debug Info" button
+2. Paste into text editor
+3. Add relevant console errors
+4. Include backend logs if available
+5. Note reproduction steps
+6. Share with team
+
+## Troubleshooting
+
+### Debug Panel Not Loading
+
+- Clear browser cache (Ctrl+Shift+R)
+- Check browser console for errors
+- Verify you're logged in as admin (staffLevel >= 3)
+- Try restarting frontend dev server
+
+### Tests Timing Out
+
+- Check backend is running (`npm run dev`)
+- Verify port 3000 is accessible
+- Check firewall/antivirus settings
+- Try increasing axios timeout
+
+### Data Not Refreshing
+
+- Click reload button on specific tab
+- Run "Refresh Auth" in quick actions
+- Clear cache and reload page
+- Check WebSocket connection status
+
+## Future Enhancements
+
+Planned features for future versions:
+
+- **Real-time Monitoring** - Live stats and metrics
+- **WebSocket Tester** - Test WS connections
+- **Database Query Tool** - Run safe queries from panel
+- **Log Viewer** - Backend logs in panel
+- **Performance Metrics** - Response times, load stats
+- **Export Reports** - Save debug sessions as files
+- **Scheduled Tests** - Auto-run tests periodically
+- **Alert System** - Notify when tests fail
+
+## Security Notes
+
+- Debug panel is **admin-only** (requires staffLevel >= 3)
+- Sensitive data (passwords, keys) never displayed
+- Actions are logged for audit trail
+- No direct database access from panel
+- All tests use authenticated endpoints
+- Panel disabled in production builds (optional)
+
+## API Endpoints Used
+
+The debug panel tests these endpoints:
+
+```
+GET  /api/health                      - Health check
+GET  /api/auth/me                     - Auth status
+GET  /api/admin/config                - Admin config
+GET  /api/admin/users/search          - User search
+GET  /api/config/announcements        - Announcements
+GET  /api/config/public               - Public config
+```
+
+## Related Documentation
+
+- [Maintenance Mode Guide](./ADMIN_MAINTENANCE_FIX.md)
+- [Announcements System](./TESTING_MAINTENANCE_AND_ANNOUNCEMENTS.md)
+- [Admin Panel Overview](./TurboTrades_Admin_Toggles_and_Routes.md)
+- [Banned Page](./BANNED_PAGE.md)
+
+## Support
+
+If you encounter issues with the debug panel:
+
+1. Check this documentation first
+2. Review console logs for errors
+3. Copy debug info to clipboard
+4. Report to development team with:
+   - Debug info JSON
+   - Console errors
+   - Steps to reproduce
+   - Expected vs actual behavior
+
+---
+
+**Last Updated:** January 2024  
+**Version:** 1.0.0  
+**Maintainer:** Development Team