MyClub/DOCS/FILE_TRACKING_ENHANCEMENT.md

# File Tracking Enhancement - Event & Article Attachments

## Problem
The file tracking system was not properly tracking event attachments and article attachments, causing files like PPTX documents to show "0 usage" even when they were actively being used in events or articles.

## Root Cause
1. **Event Attachments**: The `TrackEventFiles` function in `file_tracker.go` only tracked `image_url` and `file_url` fields, but completely ignored the `Attachments` array that stores multiple file attachments per event.

2. **Article Attachments**: The `TrackArticleFiles` function attempted to parse the attachments JSON but had a bug where all attachment field names were set to `"attachments"`, causing them to overwrite each other in the map (only the last attachment would be tracked).

## Solution

### Backend Changes

#### 1. Enhanced `file_tracker.go`
- **Added imports**: `encoding/json` and `path/filepath` for better parsing and filename extraction
- **Fixed `TrackArticleFiles`**: 
  - Properly parses JSON array of attachment URLs
  - Generates unique field names using the filename: `attachment_[filename]`
  - Handles duplicate filenames by appending suffixes
  - Falls back to comma-separated parsing if JSON parsing fails
  
- **Fixed `TrackEventFiles`**:
  - Iterates through all event attachments
  - Generates field names from attachment name or filename
  - Ensures unique field names using counters
  - Properly tracks each attachment URL separately

#### 2. New Admin Endpoint - `RefreshFileTracking`
Location: `internal/controllers/files_controller.go`

- **Purpose**: Re-scans all entities and updates file usage tracking
- **Route**: `POST /api/v1/admin/files/refresh-tracking`
- **Optional parameter**: `entity_type` (article, event, player, sponsor, contact, team, settings)
- **Returns**: Statistics of scanned entities by type
- **Features**:
  - Scans all entities in the database
  - Updates file usage records for each entity
  - Can target specific entity types or scan all
  - Provides detailed statistics on completion

#### 3. Enhanced MIME Type Detection
Expanded `detectMimeType` function to support many more file types including:
- Office documents (DOCX, XLSX, PPTX, PPT, DOC, XLS)
- Archives (ZIP, RAR, 7Z, TAR, GZ)
- Media files (MP4, AVI, MOV, MP3, WAV)
- Additional image formats (BMP, ICO)

### Frontend Changes

#### 1. New API Service Function
Location: `frontend/src/services/files.ts`

```typescript
export const refreshFileTracking = async (entityType?: string)
```
- Calls the new backend endpoint
- Returns statistics of scanned entities

#### 2. Enhanced Files Admin Page
Location: `frontend/src/pages/admin/FilesAdminPage.tsx`

- **New Button**: "Aktualizovat sledování" (Refresh Tracking)
  - Green outline style to differentiate from scan button
  - Located next to the existing "Skenovat soubory" button
  - Shows loading state during operation
  
- **New Modal**: Displays refresh tracking results
  - Shows success message
  - Displays statistics for each entity type:
    - Articles (Články)
    - Activities/Events (Aktivity)
    - Players (Hráči)
    - Sponsors (Sponzoři)
    - Contacts (Kontakty)
    - Teams (Týmy)

## How It Works

### File Tracking Flow
1. When an event/article is created or updated, the tracking function is called
2. The function extracts all file URLs (images, files, attachments)
3. For each URL, it creates a unique field name
4. The `UpdateFileUsages` function manages the file_usages table:
   - Adds new usage records
   - Removes old usage records no longer present
   - Updates existing records if URLs change

### Field Naming Convention
- Main fields: `image_url`, `file_url`, `og_image_url`, `logo_url`
- Attachments: `attachment_[filename]`
- Duplicates: `attachment_[filename]_a`, `attachment_[filename]_b`, etc.

## Usage Instructions

### For Existing Files (Your Case)
1. Go to Admin → Files Management
2. Click the green "Aktualizovat sledování" (Refresh Tracking) button
3. Wait for the process to complete
4. A modal will show statistics of how many entities were scanned
5. Refresh the files list to see updated usage counts

### For New Files
File tracking happens automatically when:
- Creating a new event with attachments
- Updating an event's attachments
- Creating/updating articles with attachments
- Any entity with file references is saved

## Files Modified

### Backend
- `internal/services/file_tracker.go` - Fixed attachment tracking logic
- `internal/controllers/files_controller.go` - Added RefreshFileTracking endpoint, enhanced MIME detection
- `internal/routes/routes.go` - Added new route

### Frontend
- `frontend/src/services/files.ts` - Added refreshFileTracking function
- `frontend/src/pages/admin/FilesAdminPage.tsx` - Added refresh button and result modal

## Benefits

1. **Accurate Usage Tracking**: All attachments are now properly tracked
2. **Better File Management**: Admins can see which files are truly unused
3. **Prevents Accidental Deletion**: Files in use will be protected
4. **Easy Maintenance**: One-click refresh of all tracking data
5. **Comprehensive MIME Support**: Better file type detection for various formats

## Testing Recommendations

1. Create an event with multiple PPTX attachments
2. Check the files admin page - usage count should be > 0
3. Click "Aktualizovat sledování" to refresh tracking
4. Verify all attachment types are tracked correctly
5. Try deleting a file that's in use - should show warning with usage info