iDefineHD
63c578b0ae
- 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.
386 lines
11 KiB
Markdown
386 lines
11 KiB
Markdown
# 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 |