MyClub/DOCS/FILES_MANAGEMENT_TESTING.md

Files Management System - Testing Guide

Prerequisites

1. Run database migration:

# Set in .env
RUN_MIGRATIONS=true

# Or run manually
migrate -path database/migrations -database "postgresql://user:pass@localhost:5432/fotbal?sslmode=disable" up

2. Start the application:

go run main.go

3. Start the frontend:

cd frontend
npm start

Test Scenarios

1. File Upload Tracking

Test: Upload a new file

# Upload via API
curl -X POST http://localhost:8080/api/v1/upload \
  -H "Content-Type: multipart/form-data" \
  -F "file=@test-image.jpg" \
  -b "cookies.txt"

Expected:

• File is saved to uploads/YYYY/MM/ directory
• Database record created in uploaded_files table
• File appears in admin files list

Verify:

• Navigate to /admin/soubory
• Check if file appears in "Všechny soubory" tab
• Verify metadata (size, type, date) is correct

2. Usage Tracking - Article

Test: Create article with image

1. Go to /admin/clanky
2. Create new article
3. Upload or select an image
4. Save article

Expected:

• File usage record created in file_usages table
• Usage count = 1 in files list
• Usage details show article title and link

Verify:

• Go to /admin/soubory
• Find the uploaded image
• Click on usage count badge
• Modal shows article where it's used

3. Usage Tracking - Player

Test: Create player with image

1. Go to /admin/hraci
2. Create new player
3. Upload player photo
4. Save player

Expected:

• File usage tracked for player entity
• Usage details show player name

Verify:

• Check file usage in files admin
• Verify entity_type = "player"
• Verify link to player detail works

4. Unused Files Detection

Test: Upload file without using it

1. Upload image via upload API or article editor
2. Don't assign it to any entity
3. Navigate to /admin/soubory
4. Click "Nepoužívané" tab

Expected:

• File appears in unused files list
• Safe to delete without warnings

Verify:

• Unused file is listed
• Can delete without "in use" warning

5. Duplicate Detection

Test: Upload same file twice

1. Upload test.jpg
2. Upload the same test.jpg again (or copy with different name)
3. Go to /admin/soubory
4. Click "Duplicity" tab

Expected:

• Files grouped by MD5 hash
• Shows 2+ files in same group
• Both files visible in duplicate group

Verify:

• Duplicate group shows hash
• All duplicate files listed
• Can compare file details

6. Safe Deletion - File in Use

Test: Delete file that's being used

1. Use an image in an article
2. Go to /admin/soubory
3. Try to delete that image

Expected:

• Warning modal appears
• Shows where file is used (article title)
• Requires confirmation to force delete

Verify:

• Warning message displayed
• Usage details shown
• "Přesto smazat" button for force delete

7. Safe Deletion - Unused File

Test: Delete unused file

1. Upload file without using it
2. Go to /admin/soubory → Nepoužívané
3. Delete the file

Expected:

• Simple confirmation
• File deleted from disk and database
• No longer appears in any list

Verify:

• File removed from filesystem
• Database record deleted
• Not in any files list

8. File Scan and Sync

Test: Sync files with database

1. Manually copy a file to uploads/2025/10/ directory
2. Go to /admin/soubory
3. Click "Skenovat soubory" button

Expected:

• Scan finds the manually added file
• Database record created
• File now appears in admin list
• Shows count of found/new/orphaned files

Verify:

• Toast shows scan results
• New file appears in list
• Correct metadata extracted

9. Search and Filter

Test: Search for files

1. Upload several files with different types
2. Go to /admin/soubory
3. Use search box to find specific file
4. Use MIME type filter

Expected:

• Search filters by filename
• MIME type dropdown filters results
• Results update in real-time

Verify:

• Search works for partial matches
• Filter works for image/pdf/etc.
• Results are accurate

10. Copy URL to Clipboard

Test: Copy file URL

1. Go to /admin/soubory
2. Click copy icon next to a file
3. Paste in browser or article editor

Expected:

• URL copied to clipboard
• Toast confirmation shown
• URL is valid and accessible

Verify:

• Toast says "Zkopírováno"
• Pasted URL works in browser
• URL format is correct (/uploads/...)

11. Usage Update on Entity Edit

Test: Update article image

1. Create article with image A
2. Edit article, change to image B
3. Check file usages

Expected:

• Image A usage removed
• Image B usage added
• Usage counts updated correctly

Verify:

• Image A shows 0 usage (if not used elsewhere)
• Image B shows usage for article
• Database reflects changes

12. Multiple Usages

Test: Use same file in multiple places

1. Upload one image
2. Use in 3 different articles
3. Check file details

Expected:

• Usage count = 3
• All 3 articles listed in usage modal
• Each usage shows correct entity info

Verify:

• Usage modal shows all 3 articles
• Each has correct title and link
• Usage count badge shows "3"

API Testing

Using curl or Postman

List all files

curl http://localhost:8080/api/v1/admin/files \
  -H "Cookie: token=YOUR_JWT_TOKEN"

Get unused files

curl http://localhost:8080/api/v1/admin/files/unused \
  -H "Cookie: token=YOUR_JWT_TOKEN"

Get duplicates

curl http://localhost:8080/api/v1/admin/files/duplicates \
  -H "Cookie: token=YOUR_JWT_TOKEN"

Get file usages

curl http://localhost:8080/api/v1/admin/files/123/usages \
  -H "Cookie: token=YOUR_JWT_TOKEN"

Delete file

curl -X DELETE http://localhost:8080/api/v1/admin/files/123 \
  -H "Cookie: token=YOUR_JWT_TOKEN"

Scan files

curl -X POST http://localhost:8080/api/v1/admin/files/scan \
  -H "Cookie: token=YOUR_JWT_TOKEN"

Database Verification

Check uploaded_files table

SELECT * FROM uploaded_files ORDER BY created_at DESC LIMIT 10;

Check file_usages table

SELECT * FROM file_usages ORDER BY created_at DESC LIMIT 10;

Find unused files

SELECT uf.* 
FROM uploaded_files uf
LEFT JOIN file_usages fu ON fu.file_id = uf.id
WHERE fu.id IS NULL;

Find files with most usages

SELECT uf.filename, uf.file_url, COUNT(fu.id) as usage_count
FROM uploaded_files uf
LEFT JOIN file_usages fu ON fu.file_id = uf.id
GROUP BY uf.id
ORDER BY usage_count DESC
LIMIT 10;

Find duplicate files

-- This requires calculating MD5 hashes in the application
-- The API endpoint handles this

Performance Testing

Large File Sets

1. Upload 100+ files
2. Test pagination and loading performance
3. Verify search/filter responsiveness

Concurrent Operations

1. Multiple users uploading simultaneously
2. File usage tracking under load
3. Deletion operations concurrent with usage tracking

Edge Cases

Test these scenarios:

1. File deleted from disk but still in DB

   • Scan should mark as orphaned
   • Usage warnings should still work

2. Very large files

   • Test upload limits
   • Verify size display formatting

3. Special characters in filename

   • Upload files with special chars
   • Verify storage and retrieval

4. Simultaneous usage updates

   • Edit multiple entities using same file
   • Verify usage count accuracy

5. Database connection issues

   • Test graceful degradation
   • Verify tracking doesn't break uploads

Success Criteria

✅ All files are tracked in database ✅ Usage tracking works for all entity types ✅ Unused files are correctly identified ✅ Duplicates are detected and grouped ✅ Safe deletion prevents data loss ✅ File scan syncs correctly ✅ Search and filter work accurately ✅ UI is responsive and user-friendly ✅ No performance issues with 100+ files ✅ All API endpoints return correct data

Common Issues & Solutions

Issue: Files not being tracked

Solution: Ensure services.NewFileTracker() is called after create/update in controllers

Issue: Duplicates not detected

Solution: Verify MD5 hash calculation in calculateFileMD5() function

Issue: Usage count incorrect

Solution: Check TrackFileUsage() is called with correct entity_type and entity_id

Issue: Orphaned records

Solution: Run scan to sync database with filesystem

Issue: Permission errors

Solution: Verify uploads directory permissions (755) and admin authentication