rrrrr

old_code_documentation/EDIT_MEDIA_TROUBLESHOOTING.md

@@ -0,0 +1,144 @@
+# Edit Media API Troubleshooting Guide
+
+## Issue
+Players are trying to send edited images to the server via the edit image API, but nothing is happening on the server.
+
+## Diagnosis Performed
+
+### 1. **API Endpoint Status** ✅
+- **Endpoint**: `POST /api/player-edit-media`
+- **Status**: Exists and properly implemented
+- **Location**: `app/blueprints/api.py` (lines 711-851)
+- **Authentication**: Requires Bearer token with valid player auth code
+
+### 2. **Bug Found and Fixed** 🐛
+Found undefined variable bug in the `receive_edited_media()` function:
+- **Issue**: `playlist` variable was only defined inside an `if` block
+- **Problem**: When a player has no assigned playlist, the variable remained undefined
+- **Error**: Would cause `UnboundLocalError` when trying to return the response
+- **Fix**: Initialize `playlist = None` before the conditional block
+- **Commit**: `8a89df3`
+
+### 3. **Server Logs Check** ✅
+- No `player-edit-media` requests found in recent logs
+- **Conclusion**: Requests are not reaching the server, indicating a client-side issue
+
+## Possible Root Causes
+
+### A. **Player App Not Sending Requests**
+The player application might not be calling the edit media endpoint. Check:
+- Is the "edit on player" feature enabled for the content?
+- Does the player app have code to capture edited images?
+- Are there errors in the player app logs?
+
+### B. **Wrong Endpoint URL**
+If the player app is hardcoded with an incorrect URL, requests won't reach the server.
+- **Expected URL**: `{server_url}/api/player-edit-media`
+- **Required Header**: `Authorization: Bearer {player_auth_code}`
+
+### C. **Network Issues**
+- Firewall blocking requests
+- Network connectivity issues between player and server
+- SSL/HTTPS certificate validation failures
+
+### D. **Request Format Issues**
+The endpoint expects:
+```
+Content-Type: multipart/form-data
+- image_file: The edited image file (binary)
+- metadata: JSON string with this structure:
+  {
+    "time_of_modification": "2026-01-17T19:50:00Z",
+    "original_name": "image.jpg",
+    "new_name": "image_v1.jpg",
+    "version": 1,
+    "user_card_data": "optional_user_code"
+  }
+```
+
+### E. **Authentication Issues**
+- Player's auth code might be invalid
+- Bearer token not being sent correctly
+- Auth code might have changed
+
+## Testing Steps
+
+### 1. **Verify Endpoint is Accessible**
+```bash
+curl -X POST http://localhost:5000/api/player-edit-media \
+  -H "Authorization: Bearer <valid_player_auth_code>" \
+  -F "image_file=@test.jpg" \
+  -F "metadata={\"time_of_modification\":\"2026-01-17T20:00:00Z\",\"original_name\":\"4k1.jpg\",\"new_name\":\"4k1_v1.jpg\",\"version\":1}"
+```
+
+### 2. **Check Player Logs**
+Look for errors in the player application logs when attempting to send edits
+
+### 3. **Monitor Server Logs**
+Enable debug logging and watch for:
+```bash
+docker compose logs digiserver-app -f | grep -i "edit\|player-edit"
+```
+
+### 4. **Verify Player Has Valid Auth Code**
+```bash
+curl -X POST http://localhost:5000/api/auth/verify \
+  -H "Authorization: Bearer <player_auth_code>" \
+  -H "Content-Type: application/json"
+```
+
+## Server API Response
+
+### Success Response (200 OK)
+```json
+{
+  "success": true,
+  "message": "Edited media received and processed",
+  "edit_id": 123,
+  "version": 1,
+  "old_filename": "image.jpg",
+  "new_filename": "image_v1.jpg",
+  "new_playlist_version": 34
+}
+```
+
+### Error Responses
+- **401**: Missing or invalid authorization header
+- **403**: Invalid authentication code
+- **400**: Missing required fields (image_file, metadata, etc.)
+- **404**: Original content file not found in system
+- **500**: Internal server error (check logs)
+
+## Expected Server Behavior
+
+When an edit is successfully received:
+1. ✅ File is saved to `/static/uploads/edited_media/<content_id>/<filename>`
+2. ✅ Metadata JSON is saved alongside the file
+3. ✅ PlayerEdit record is created in database
+4. ✅ PlayerUser record is auto-created if user_card_data provided
+5. ✅ Playlist version is incremented (if player has assigned playlist)
+6. ✅ Playlist cache is cleared
+7. ✅ Action is logged in server_log table
+
+## Database Records
+
+After successful upload, check:
+```sql
+-- Player edit records
+SELECT * FROM player_edit WHERE player_id = ? ORDER BY created_at DESC;
+
+-- Verify file exists
+ls -la app/static/uploads/edited_media/
+
+-- Check server logs
+SELECT * FROM server_log WHERE action LIKE '%edited%' ORDER BY created_at DESC;
+```
+
+## Next Steps
+
+1. Check if player app is configured with correct server URL
+2. Verify player has "edit on player" enabled for the content
+3. Check player app logs for any error messages
+4. Test endpoint connectivity using curl/Postman
+5. Monitor server logs while player attempts to send an edit
+6. Verify player's auth code is valid and unchanged