feat: reorganize admin settings with tabbed interface and documentation
- Reorganized admin settings into tabbed interface (General, Security, Payment Methods) - Vertical tabs on desktop, horizontal scrollable on mobile - Moved Payment Methods from separate menu to Settings tab - Fixed admin profile reuse and dashboard blocking - Fixed maintenance mode guard to use AppConfig model - Added admin auto-redirect after login (admins → /admin, users → /) - Reorganized documentation into docs/ folder structure - Created comprehensive README and documentation index - Added PWA and Web Push notifications to to-do list
This commit is contained in:
dwindown
267
docs/guides/testing-guide.md
Normal file
267
docs/guides/testing-guide.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# Maintenance Mode - Testing Guide
|
||||
|
||||
## ✅ **Fixed Implementation**
|
||||
|
||||
### **What Was Wrong:**
|
||||
The original implementation had a critical flaw - it checked `request.user` which doesn't exist until AFTER the JWT guard runs. This meant:
|
||||
- Admins would also be blocked
|
||||
- The guard couldn't distinguish between admin and regular users
|
||||
|
||||
### **What Was Fixed:**
|
||||
- MaintenanceGuard now manually verifies JWT tokens using `JwtService`
|
||||
- Extracts user role from token payload
|
||||
- Allows admins through, blocks everyone else
|
||||
- Works independently of the JWT guard
|
||||
|
||||
---
|
||||
|
||||
## **🧪 How to Test Maintenance Mode**
|
||||
|
||||
### **Prerequisites:**
|
||||
1. Have at least 2 user accounts:
|
||||
- One admin account (role: 'admin')
|
||||
- One regular user account (role: 'user')
|
||||
2. Both API and Web servers running
|
||||
|
||||
---
|
||||
|
||||
### **Test Scenario 1: Enable Maintenance Mode**
|
||||
|
||||
#### **Step 1: Login as Admin**
|
||||
```
|
||||
1. Go to http://localhost:5174/auth/login
|
||||
2. Login with admin credentials
|
||||
3. Navigate to http://localhost:5174/admin/settings
|
||||
```
|
||||
|
||||
#### **Step 2: Enable Maintenance**
|
||||
```
|
||||
1. Find "Maintenance Mode" section
|
||||
2. Toggle the switch to ON
|
||||
3. Optionally change the message to: "We're upgrading! Back in 10 minutes."
|
||||
4. Click "Save Settings"
|
||||
5. You should see success toast
|
||||
```
|
||||
|
||||
#### **Step 3: Verify Admin Still Has Access**
|
||||
```
|
||||
1. Stay logged in as admin
|
||||
2. Navigate to different admin pages:
|
||||
- /admin (Dashboard)
|
||||
- /admin/users
|
||||
- /admin/plans
|
||||
3. All should work normally ✅
|
||||
4. Try accessing main app: http://localhost:5174/
|
||||
5. Admin should see maintenance page ❌ (this is expected - only admin panel works)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Test Scenario 2: Regular User Experience**
|
||||
|
||||
#### **Step 1: Open Incognito/Private Window**
|
||||
```
|
||||
1. Open new incognito window
|
||||
2. Go to http://localhost:5174
|
||||
```
|
||||
|
||||
#### **Step 2: Try to Access Without Login**
|
||||
```
|
||||
1. You'll be redirected to login page
|
||||
2. Try to login with regular user credentials
|
||||
3. After successful login, you should see MAINTENANCE PAGE ✅
|
||||
4. The page should display your custom message
|
||||
```
|
||||
|
||||
#### **Step 3: Verify User is Blocked**
|
||||
```
|
||||
1. Try to navigate to any route:
|
||||
- /
|
||||
- /wallets
|
||||
- /transactions
|
||||
2. All should show maintenance page ✅
|
||||
3. Click "Refresh Page" button
|
||||
4. Should still show maintenance (because it's still ON)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **Test Scenario 3: Disable Maintenance Mode**
|
||||
|
||||
#### **Step 1: As Admin, Disable Maintenance**
|
||||
```
|
||||
1. Go back to admin window (still logged in)
|
||||
2. Navigate to /admin/settings
|
||||
3. Toggle "Maintenance Mode" to OFF
|
||||
4. Click "Save Settings"
|
||||
```
|
||||
|
||||
#### **Step 2: Verify User Can Access Again**
|
||||
```
|
||||
1. Go to incognito window (with regular user)
|
||||
2. Click "Refresh Page" button
|
||||
3. User should now see the normal app ✅
|
||||
4. Try navigating to different pages - all should work
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## **📊 Expected Behavior Matrix**
|
||||
|
||||
| User Type | Maintenance OFF | Maintenance ON |
|
||||
|-----------|----------------|----------------|
|
||||
| **Not Logged In** | Can login | Can login, then see maintenance page |
|
||||
| **Regular User** | Full access | Maintenance page on all routes |
|
||||
| **Admin User** | Full access | Admin panel works, main app shows maintenance |
|
||||
|
||||
---
|
||||
|
||||
## **🔍 How to Verify It's Working**
|
||||
|
||||
### **Check 1: API Returns 503**
|
||||
Open browser DevTools (F12) → Network tab:
|
||||
```
|
||||
1. With maintenance ON, as regular user
|
||||
2. Try to access any protected route
|
||||
3. Look for API calls
|
||||
4. Should see 503 status code
|
||||
5. Response body should have:
|
||||
{
|
||||
"statusCode": 503,
|
||||
"message": "Your custom message",
|
||||
"maintenanceMode": true
|
||||
}
|
||||
```
|
||||
|
||||
### **Check 2: Admin Bypasses Maintenance**
|
||||
```
|
||||
1. With maintenance ON, as admin
|
||||
2. Open DevTools → Network tab
|
||||
3. Navigate to /admin/users
|
||||
4. API calls should return 200 OK (not 503)
|
||||
5. Admin panel should work normally
|
||||
```
|
||||
|
||||
### **Check 3: Database Config**
|
||||
Check the database directly:
|
||||
```sql
|
||||
SELECT * FROM "Config" WHERE key = 'maintenance_mode';
|
||||
-- Should show: value = 'true' when ON, 'false' when OFF
|
||||
|
||||
SELECT * FROM "Config" WHERE key = 'maintenance_message';
|
||||
-- Should show your custom message
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## **🐛 Troubleshooting**
|
||||
|
||||
### **Problem: Admin Also Sees Maintenance Page**
|
||||
**Cause:** JWT token might be invalid or expired
|
||||
**Solution:**
|
||||
1. Logout and login again as admin
|
||||
2. Check browser console for errors
|
||||
3. Verify JWT_SECRET in .env matches between sessions
|
||||
|
||||
### **Problem: Regular User Can Still Access**
|
||||
**Cause:** Maintenance mode not actually enabled in DB
|
||||
**Solution:**
|
||||
1. Check database: `SELECT * FROM "Config" WHERE key = 'maintenance_mode'`
|
||||
2. If value is not 'true', manually update:
|
||||
```sql
|
||||
UPDATE "Config" SET value = 'true' WHERE key = 'maintenance_mode';
|
||||
```
|
||||
3. Or toggle it again in Admin Settings
|
||||
|
||||
### **Problem: Maintenance Page Never Shows**
|
||||
**Cause:** Axios interceptor not set up properly
|
||||
**Solution:**
|
||||
1. Check browser console for errors
|
||||
2. Verify App.tsx has `setupAxiosInterceptors` call
|
||||
3. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
|
||||
|
||||
### **Problem: Auth Routes Also Blocked**
|
||||
**Cause:** @SkipMaintenance decorator missing
|
||||
**Solution:**
|
||||
1. Verify auth.controller.ts has @SkipMaintenance on login/register
|
||||
2. Restart API server
|
||||
|
||||
---
|
||||
|
||||
## **🎯 Quick Test Checklist**
|
||||
|
||||
- [ ] Admin can enable maintenance mode
|
||||
- [ ] Admin can customize maintenance message
|
||||
- [ ] Admin can still access admin panel when maintenance is ON
|
||||
- [ ] Regular user sees maintenance page when maintenance is ON
|
||||
- [ ] Maintenance page displays custom message
|
||||
- [ ] Refresh button works on maintenance page
|
||||
- [ ] Admin can disable maintenance mode
|
||||
- [ ] Regular user can access app after maintenance is OFF
|
||||
- [ ] Login/register still work during maintenance
|
||||
- [ ] Health check endpoints still work during maintenance
|
||||
|
||||
---
|
||||
|
||||
## **📝 Notes**
|
||||
|
||||
### **Routes That Always Work (Even During Maintenance):**
|
||||
- `/health` - Health check
|
||||
- `/health/db` - Database check
|
||||
- `/auth/login` - Login
|
||||
- `/auth/register` - Register
|
||||
- `/auth/verify-otp` - OTP verification
|
||||
- `/auth/google` - Google OAuth
|
||||
- `/admin/*` - All admin routes (for admins only)
|
||||
|
||||
### **Routes That Get Blocked:**
|
||||
- `/` - Main dashboard
|
||||
- `/wallets` - Wallets page
|
||||
- `/transactions` - Transactions page
|
||||
- `/api/users/me` - User profile
|
||||
- `/api/wallets` - Wallet API
|
||||
- `/api/transactions` - Transaction API
|
||||
- Any other non-admin, non-auth route
|
||||
|
||||
### **How Admins Are Identified:**
|
||||
1. MaintenanceGuard extracts JWT token from `Authorization` header
|
||||
2. Verifies token using JwtService
|
||||
3. Checks if `payload.role === 'admin'`
|
||||
4. If true, allows access
|
||||
5. If false or no token, blocks with 503
|
||||
|
||||
---
|
||||
|
||||
## **🚀 Production Deployment Notes**
|
||||
|
||||
### **Before Enabling Maintenance:**
|
||||
1. Notify users via email/notification
|
||||
2. Set a clear maintenance message with expected duration
|
||||
3. Schedule during low-traffic hours
|
||||
4. Have rollback plan ready
|
||||
|
||||
### **During Maintenance:**
|
||||
1. Monitor admin panel access
|
||||
2. Check logs for any issues
|
||||
3. Test critical features before re-enabling
|
||||
|
||||
### **After Maintenance:**
|
||||
1. Disable maintenance mode
|
||||
2. Monitor for any issues
|
||||
3. Verify all features work
|
||||
4. Notify users that system is back online
|
||||
|
||||
---
|
||||
|
||||
## **✅ Summary**
|
||||
|
||||
Maintenance mode is now **fully functional** with proper admin bypass. The system:
|
||||
- ✅ Blocks regular users when enabled
|
||||
- ✅ Allows admins to continue working
|
||||
- ✅ Shows professional maintenance page
|
||||
- ✅ Displays custom admin messages
|
||||
- ✅ Can be toggled on/off from Admin Settings
|
||||
- ✅ Preserves auth functionality
|
||||
- ✅ Keeps health checks working
|
||||
|
||||
**Ready for production use!**
|
||||
Reference in New Issue
Block a user