MyClub/DOCS/ANALYTICS_TEST_INSTRUCTIONS.md

# Analytics Graph Fix - Testing Instructions

## What Was Fixed

### 1. Frontend Improvements
- **Added error detection**: The page now detects when Umami returns no data
- **Visual feedback**: Orange warning banner appears when analytics are not configured
- **Empty state display**: Graph shows a clear message when no data is available
- **Better error messages**: Czech language messages explaining the issue

### 2. Backend Improvements
- **Enhanced logging**: Detailed logs at every step of Umami connection
- **Auto-detection**: System automatically finds the first Umami website if UMAMI_WEBSITE_ID is empty
- **Better error handling**: Graceful fallback when Umami is unreachable

## How to Test

### Step 1: Restart Backend
Restart your backend to apply the changes:

```bash
# If using Docker:
docker-compose restart backend

# Or rebuild if needed:
docker-compose up -d --build backend

# If running locally:
make run
# or
go run main.go
```

### Step 2: Watch Backend Logs
Open a terminal and watch the logs:

```bash
# Docker:
docker-compose logs -f backend

# Local:
# Logs will appear in the terminal where you run the server
```

### Step 3: Access Analytics Page
1. Open your browser
2. Go to: `http://localhost:3000/admin/analytika` (or your frontend URL)
3. Log in as admin if needed

### Step 4: Observe the Behavior

#### Scenario A: Umami is Properly Connected
You should see:
- **Backend logs**:
  ```
  [INFO] UMAMI_WEBSITE_ID is empty, attempting to auto-detect...
  [INFO] Attempting to get default Umami website ID from https://umami.tdvorak.dev
  [INFO] Successfully authenticated with Umami at https://umami.tdvorak.dev
  [INFO] Found default Umami website: ID=xxxxx, Name=..., Domain=...
  [INFO] Auto-detected and cached Umami website ID: xxxxx
  [INFO] Using Umami website ID: xxxxx
  [INFO] Successfully fetched Umami stats for websiteID=xxxxx (days=0)
  ```

- **Frontend display**:
  - Statistics cards showing numbers (may be 0 if no traffic yet)
  - Graph displaying page views (or empty state if no data)
  - Country flags showing visitor locations

#### Scenario B: No Data Yet (Normal for New Sites)
You should see:
- **Backend logs**: Successful connection messages
- **Frontend display**: 
  - Orange warning banner: "Analytika není k dispozici"
  - Message: "Umami není správně nakonfigurováno nebo ještě nebyly zaznamenány žádné návštěvy"
  - Empty graph with "Žádná data pro zobrazení"

#### Scenario C: Umami Connection Failed
You should see:
- **Backend logs**:
  ```
  [ERROR] Failed to resolve Umami website ID: ...
  [WARN] No Umami websites found in instance at https://umami.tdvorak.dev
  ```

- **Frontend display**:
  - Orange warning banner with error message
  - All statistics showing 0
  - Empty graph

### Step 5: Generate Test Traffic (Optional)
To populate the analytics with data:

1. Open your website in multiple tabs/browsers
2. Navigate to different pages
3. Wait 2-5 minutes for Umami to process the data
4. Refresh the analytics page
5. You should now see data in the graphs

## Expected Log Output (Success Case)

```
2025-01-14 13:45:23 [INFO] UMAMI_WEBSITE_ID is empty, attempting to auto-detect...
2025-01-14 13:45:23 [INFO] Attempting to find Umami website by domain: localhost
2025-01-14 13:45:23 [INFO] Attempting to get default Umami website ID from https://umami.tdvorak.dev
2025-01-14 13:45:23 [INFO] Successfully authenticated with Umami at https://umami.tdvorak.dev (new token issued, expires at 2025-01-15 12:45:23)
2025-01-14 13:45:24 [INFO] Found default Umami website: ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890, Name=My Fotbal Club, Domain=fotbalclub.example.com
2025-01-14 13:45:24 [INFO] Auto-detected and cached Umami website ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
2025-01-14 13:45:24 [INFO] Using Umami website ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
2025-01-14 13:45:25 [INFO] Successfully fetched Umami stats for websiteID=a1b2c3d4-e5f6-7890-abcd-ef1234567890 (days=0)
2025-01-14 13:45:25 [INFO] Successfully fetched 0 Umami metrics (websiteID=a1b2c3d4-e5f6-7890-abcd-ef1234567890, type=url, days=0)
```

## Troubleshooting

### Issue: Backend logs show "No websites found"
**Fix**: Log into Umami (`https://umami.tdvorak.dev`) and create a website:
1. Click "Add Website"
2. Enter name: "Fotbal Club"
3. Enter domain: your website domain
4. Click "Save"
5. Restart backend

### Issue: Backend logs show "Authentication failed"
**Fix**: Check credentials in `.env`:
```env
UMAMI_URL=https://umami.tdvorak.dev
UMAMI_USERNAME=admin
UMAMI_PASSWORD=eevRQ6h3G@!c#y4A1T
```

### Issue: Backend logs show connection timeout
**Fix**: 
1. Check if Umami is running: `curl https://umami.tdvorak.dev`
2. Check firewall/network settings
3. Verify UMAMI_URL is correct

### Issue: Graph shows but says "Žádná data"
**Fix**: This is normal! It means:
- Umami is connected ✓
- Website ID is detected ✓
- But no traffic has been recorded yet
- Solution: Visit your website and wait a few minutes

## Files Modified

1. **frontend/src/pages/admin/AnalyticsAdminPage.tsx**
   - Added error detection and display
   - Added empty state for graphs
   - Better visual feedback

2. **internal/controllers/umami_controller.go**
   - Enhanced logging at each step
   - Better error messages
   - Improved website ID resolution

3. **internal/services/umami_service.go**
   - Added detailed logging for authentication
   - Better error messages for website detection

## Next Steps After Successful Test

1. **Optional**: Set `UMAMI_WEBSITE_ID` in `.env` to avoid auto-detection on every restart
2. Monitor backend logs for any Umami-related errors
3. Check analytics page periodically to see real traffic data
4. Share the Umami dashboard URL with your team for detailed analytics

## Support

If you continue to experience issues:
1. Check the full backend logs
2. Verify Umami is accessible
3. Review `ANALYTICS_GRAPH_FIX.md` for detailed solutions