MyClub/DOCS/ADMIN_TROUBLESHOOTING.md

Admin Panel Troubleshooting Guide

Common Issues & Solutions

1. Cache Viewer - 404 Error on /api/v1/admin/cache/list

Problem:

GET http://localhost:3000/api/v1/admin/cache/list 404 (Not Found)

Root Cause: The frontend dev server is hitting localhost:3000 instead of the backend at localhost:8080. This happens when the frontend environment variables aren't loaded properly.

Solution:

1. Verify frontend/.env contains:

   REACT_APP_API_URL=http://localhost:8080/api/v1
   

2. Restart the frontend dev server:

   cd frontend
   npm start
   

   Important: React dev server only loads .env variables on startup. Changes require a restart.

3. Verify in browser console that API calls hit localhost:8080:

   // Open browser console and check:
   console.log(process.env.REACT_APP_API_URL);
   // Should output: http://localhost:8080/api/v1
   

Backend Route: The route exists in internal/routes/routes.go:294:

cache.GET("/list", baseController.GetAdminCacheList)

---

2. User Management - Editor Role Getting 403 Errors

Problem:

403 Přístup odepřen
Rozhodčí píská: tato část hřiště je jen pro kapitány (adminy).

Root Cause: This is CORRECT behavior! The editor role is designed with limited permissions.

Permissions Breakdown:

Admin Role (Full Access)

• ✅ User management
• ✅ Settings & configuration
• ✅ Cache & prefetch management
• ✅ All CRUD operations
• ✅ Newsletter management
• ✅ Analytics
• ✅ All admin pages

Editor Role (Limited Access)

• ✅ Create/edit articles
• ✅ Create/edit events
• ✅ Create/edit teams & players
• ✅ Create/edit sponsors
• ❌ User management
• ❌ Settings
• ❌ Cache/prefetch
• ❌ Newsletter management
• ❌ Analytics

Implementation: See internal/routes/routes.go:174-176:

admin := protected.Group("/admin")
admin.Use(middleware.RoleAuth("admin"))  // ← Requires admin role

All routes under /admin/* require the admin role. Editors cannot access these endpoints.

If you need to grant editor access to specific admin features:

1. Move those routes outside the admin group
2. Apply middleware.RoleAuth("editor") to allow both admins and editors
3. Or create a separate middleware that accepts both roles

---

3. User Update - 404 Error on PUT /admin/users/:id

Problem:

PUT http://localhost:8080/api/v1/admin/users/2 404 (Not Found)

Possible Causes:

A. Backend Not Running

# Check if backend is running:
curl http://localhost:8080/api/v1/health

# If no response, start the backend:
go run main.go

B. Route Not Registered

The route should be registered in routes.go:225:

admin.PUT("/users/:id", authController.AdminUpdateUser)

Verify it exists and the controller method is implemented.

C. Authentication Issue

Ensure you're logged in as an admin:

# Check auth token in browser DevTools → Application → Cookies
# Look for: auth_token

Testing the Endpoint:

# Get auth token from browser cookies, then:
curl -X PUT http://localhost:8080/api/v1/admin/users/2 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Test User","email":"test@test.com","role":"editor","isActive":true}'

---

4. Password Reset - 500 Internal Server Error

Problem:

POST http://localhost:8080/api/v1/admin/users/2/reset-password 500 (Internal Server Error)
Error: failed to send reset email

Root Cause: SMTP email configuration is missing or invalid.

Solution:

Step 1: Configure SMTP in .env

Add valid SMTP credentials to your .env file:

# Basic SMTP Configuration (required)
SMTP_HOST=smtp.gmail.com          # Your SMTP server
SMTP_PORT=587                     # 587 for TLS, 465 for SSL
SMTP_USER=your-email@gmail.com    # Your email address
SMTP_PASSWORD=your-app-password   # App password (not regular password)
SMTP_FROM=noreply@yourclub.com    # From email address
SMTP_FROM_NAME="Your Club Name"   # From name
SMTP_ENCRYPTION=tls               # tls, ssl, or none
SMTP_AUTH=true
SMTP_SKIP_VERIFY=false

# Email Templates (should already exist)
EMAIL_TEMPLATE_DIR=./templates/emails

Step 2: Optional - Admin-Specific SMTP Override

For password resets triggered by admins, you can use separate credentials:

# Optional: Admin-specific SMTP for password resets
ADMIN_RESET_SMTP_HOST=smtp.purelymail.com
ADMIN_RESET_SMTP_PORT=465
ADMIN_RESET_SMTP_USER=system@yourclub.com
ADMIN_RESET_SMTP_PASS=secure_password_here
ADMIN_RESET_SMTP_FROM=system@yourclub.com
ADMIN_RESET_SMTP_FROM_NAME="Club Admin"

Step 3: Restart Backend

# Stop the backend (Ctrl+C)
# Restart:
go run main.go

Step 4: Test SMTP Configuration

Try sending a test email from the admin panel:

1. Navigate to Newsletter settings
2. Use the "Send Test Email" feature
3. Verify you receive the email

Common SMTP Providers:

Gmail

• Host: smtp.gmail.com
• Port: 587 (TLS) or 465 (SSL)
• Important: Use an App Password, not your regular password
• Generate one at: https://myaccount.google.com/apppasswords

Outlook/Hotmail

• Host: smtp-mail.outlook.com
• Port: 587
• Use your Microsoft account credentials

Purelymail

• Host: smtp.purelymail.com
• Port: 465 (SSL)
• Very reliable for transactional emails

Improved Error Messages: The system now shows detailed SMTP errors in the frontend:

• Configuration validation errors
• SMTP connection errors
• Authentication failures

Check the error toast for specific details about what went wrong.

---

Environment Variables Checklist

Required for Full Functionality

# Backend API
PORT=8080
APP_ENV=development
DEBUG=true

# Database
DB_HOST=db
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=fotbal_club

# Authentication
JWT_SECRET=your_secure_secret_here  # Change this!
JWT_EXPIRATION_HOURS=24

# Email/SMTP (Required for password resets)
SMTP_HOST=smtp.yourprovider.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASSWORD=your-password
SMTP_FROM=noreply@yourclub.com
SMTP_FROM_NAME="Your Club"
SMTP_ENCRYPTION=tls
SMTP_AUTH=true

# Frontend (for CORS and API calls)
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080
REACT_APP_API_URL=http://localhost:8080/api/v1

---

Quick Debugging Commands

Check Backend Health

curl http://localhost:8080/api/v1/health

Check If You're Authenticated

# In browser console:
fetch('/api/v1/auth/me', { credentials: 'include' })
  .then(r => r.json())
  .then(console.log)

List All Registered Routes (Go)

# Add this temporarily to main.go after routes.SetupRoutes():
# r.Routes() will show all registered routes

Check Backend Logs

Look for errors in the terminal where you ran go run main.go. Common issues:

• Database connection errors
• SMTP configuration warnings
• Missing environment variables

---

Role-Based Access Control (RBAC)

Middleware Chain

Request → JWTAuth → RoleAuth → Controller

1. JWTAuth: Validates JWT token, loads user
2. RoleAuth: Checks if user.role matches required role
3. Controller: Executes business logic

Customizing Access

To allow editors to access specific admin features:

// Option 1: Move route outside admin group
protected.PUT("/articles/:id", baseController.UpdateArticle)

// Option 2: Create editor-accessible subgroup
editorAdmin := protected.Group("/editor-admin")
editorAdmin.Use(middleware.RoleAuth("editor"))
{
    editorAdmin.GET("/stats", statsController.GetEditorStats)
}

// Option 3: Custom middleware for multiple roles
func RoleAuthMultiple(roles ...string) gin.HandlerFunc {
    return func(c *gin.Context) {
        userRole := c.GetString("userRole")
        for _, role := range roles {
            if userRole == role {
                c.Next()
                return
            }
        }
        c.JSON(403, gin.H{"error": "Insufficient permissions"})
        c.Abort()
    }
}

---

Testing Checklist

After making changes, test:

• Backend health endpoint responds
• Frontend loads without errors
• Admin can log in
• Editor can log in
• Admin can access user management
• Editor CANNOT access user management (403)
• Admin can create/edit users
• Password reset emails send successfully
• Cache viewer loads data
• All API calls hit correct port (8080, not 3000)

---

Need More Help?

Check Logs

• Backend: Terminal where go run main.go is running
• Frontend: Browser DevTools → Console
• Network: Browser DevTools → Network tab

Common Log Messages

Backend

[startup] NewsletterEnabled=true (from settings)
Server starting on port 8080

Frontend Console Errors

// BAD - hitting wrong port
GET http://localhost:3000/api/v1/admin/cache/list 404

// GOOD - hitting correct port  
GET http://localhost:8080/api/v1/admin/cache/list 200

14. Rich Text Editor Not Visible

Problem: The Quill rich text editor appears blank or invisible in articles, activities, or other content forms. The editor toolbar and text area don't show up.

Root Cause: Quill CSS files weren't loading due to component-level imports not working properly with CRACO/Create React App build setup.

Solution: The CSS imports have been moved to frontend/src/index.tsx to load globally:

// Quill editor styles (MUST be imported globally)
import 'react-quill/dist/quill.snow.css';
import 'react-image-crop/dist/ReactCrop.css';
import './styles/custom-editor.css';

After applying this fix:

1. Restart the frontend dev server (required for CSS changes):

   cd frontend
   npm start
   

2. Clear browser cache or do a hard refresh (Ctrl+Shift+R / Cmd+Shift+R)

3. Verify the editor is now visible with:

   • Toolbar buttons (bold, italic, headers, etc.)
   • White text area with proper styling
   • Image upload and formatting controls

Technical Note: Component-level CSS imports (import './style.css' inside a component) don't always process correctly with webpack/CRACO. Critical third-party CSS like Quill must be imported at the app entry point.

---

Still Stuck?

1. Verify all environment variables are set correctly
2. Restart both frontend and backend
3. Clear browser cache and cookies
4. Check database is running (docker-compose ps if using Docker)
5. Review recent code changes that might affect routing