# 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