MyClub/DOCS/FILES_MANAGEMENT_TESTING.md

# Files Management System - Testing Guide

## Prerequisites

1. Run database migration:
```bash
# 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:
```bash
go run main.go
```

3. Start the frontend:
```bash
cd frontend
npm start
```

## Test Scenarios

### 1. File Upload Tracking

**Test:** Upload a new file
```bash
# 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
```bash
curl http://localhost:8080/api/v1/admin/files \
  -H "Cookie: token=YOUR_JWT_TOKEN"
```

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

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

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

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

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

## Database Verification

### Check uploaded_files table
```sql
SELECT * FROM uploaded_files ORDER BY created_at DESC LIMIT 10;
```

### Check file_usages table
```sql
SELECT * FROM file_usages ORDER BY created_at DESC LIMIT 10;
```

### Find unused files
```sql
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
```sql
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
```sql
-- 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