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

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