upload

DOCS/ANALYTICS_FIX.md

@@ -0,0 +1,78 @@
+# Analytics Admin Fix - 500 Error Resolution
+
+## Issue
+The analytics admin page was throwing a 500 Internal Server Error when accessing:
+```
+GET http://localhost:8080/api/v1/admin/umami/pageviews?days=0
+```
+
+This caused the entire analytics dashboard to fail to load.
+
+## Root Cause
+The Umami analytics endpoints (`/pageviews`, `/stats`, `/metrics`) were returning HTTP 500 errors when:
+- Umami credentials were not configured
+- Umami website ID was not set
+- Umami API calls failed for any reason
+
+## Solution
+Implemented **graceful degradation** for all Umami endpoints:
+
+### Changes Made
+
+1. **Added Configuration Checks** (`umami_controller.go`)
+   - All endpoints now check if Umami is configured before attempting API calls
+   - Returns empty data structures instead of errors when Umami is unavailable
+
+2. **Improved Error Handling**
+   - `GetPageviews`: Returns `[]` (empty array) instead of 500 error
+   - `GetStats`: Returns `{}` (empty object) instead of 500 error  
+   - `GetMetrics`: Returns `[]` (empty array) instead of 500 error
+
+3. **Enhanced Logging**
+   - Added detailed logging for debugging
+   - Logs now include: websiteID, days parameter, unit, startAt/endAt timestamps
+   - Clear warning messages when Umami is not configured
+
+### Benefits
+
+✅ **No More Crashes**: Analytics page loads successfully even without Umami
+✅ **Better UX**: Users see an empty dashboard instead of error page
+✅ **Clear Diagnostics**: Log messages clearly indicate Umami configuration issues
+✅ **Resilient Design**: Follows best practices for external service integration
+
+## Testing
+
+After the fix, accessing the analytics admin page will:
+- Load successfully ✓
+- Show empty charts and stats when Umami is not configured
+- Display data normally when Umami is properly configured
+
+## Configuration
+
+To enable Umami analytics, ensure these environment variables are set in `.env`:
+```env
+UMAMI_URL=https://your-umami-instance.com
+UMAMI_USERNAME=your_username
+UMAMI_PASSWORD=your_password
+UMAMI_WEBSITE_ID=  # Optional - will auto-detect
+```
+
+## Files Modified
+- `internal/controllers/umami_controller.go`
+  - `GetStats()` - Lines 196-236
+  - `GetMetrics()` - Lines 238-284
+  - `GetPageviews()` - Lines 286-349
+
+## Deployment
+```bash
+# Rebuild and restart the backend container
+docker-compose up -d --build backend
+
+# Or if running locally
+go build -o bin/fotbal-club main.go
+./bin/fotbal-club
+```
+
+## Related Documentation
+- See `ANALYTICS_INTEGRATION.md` for full Umami setup guide
+- See `QUICK_START_ANALYTICS.md` for analytics dashboard usage