Add player media editing feature with versioning

- Added PlayerEdit model to track edited media history - Created /api/player-edit-media endpoint for receiving edited files from players - Implemented versioned storage: edited_media/<content_id>/<filename_vN.ext> - Automatic playlist update when edited media is received - Updated content.filename to reference versioned file in playlist - Added 'Edited Media on the Player' card to player management page - UI shows version history grouped by original file - Each edit preserves previous versions in archive folder - Includes dark mode support for new UI elements - Documentation: PLAYER_EDIT_MEDIA_API.md
2025-12-06 00:06:11 +02:00
parent 3921a09c4e
commit 8d52c0338f
6 changed files with 537 additions and 10 deletions
--- a/PLAYER_EDIT_MEDIA_API.md
+++ b/PLAYER_EDIT_MEDIA_API.md
@@ -0,0 +1,181 @@
+# Player Edit Media API
+
+## Overview
+This API allows players to upload edited media files back to the server, maintaining version history and automatically updating playlists.
+
+## Endpoint
+
+### POST `/api/player-edit-media`
+
+Upload an edited media file from a player device.
+
+**Authentication Required:** Yes (Bearer token)
+
+**Rate Limit:** 60 requests per 60 seconds
+
+**Content-Type:** `multipart/form-data`
+
+## Request
+
+### Form Data
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `image_file` | File | Yes | The edited image file |
+| `metadata` | JSON String | Yes | Metadata about the edit (see below) |
+
+### Metadata JSON Structure
+
+```json
+{
+  "time_of_modification": "2025-12-05T20:30:00Z",
+  "original_name": "image.jpg",
+  "new_name": "image_v1.jpg",
+  "version": 1,
+  "user": "player_user_name"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `time_of_modification` | ISO 8601 DateTime | Yes | When the edit was made |
+| `original_name` | String | Yes | Original filename (must exist in content) |
+| `new_name` | String | Yes | New filename with version suffix |
+| `version` | Integer | Yes | Version number (1, 2, 3, etc.) |
+| `user` | String | No | User who made the edit |
+
+## Response
+
+### Success (200 OK)
+
+```json
+{
+  "success": true,
+  "message": "Edited media received and processed",
+  "edit_id": 123,
+  "version": 1,
+  "new_playlist_version": 5
+}
+```
+
+### Error Responses
+
+#### 400 Bad Request
+```json
+{
+  "error": "No image file provided"
+}
+```
+
+#### 404 Not Found
+```json
+{
+  "error": "Original content not found: image.jpg"
+}
+```
+
+#### 500 Internal Server Error
+```json
+{
+  "error": "Internal server error"
+}
+```
+
+## Workflow
+
+1. **Player edits media** - User edits an image/PDF/PPTX on the player device
+2. **Player uploads** - Player sends edited file + metadata to this endpoint
+3. **Server processes**:
+   - Saves edited file to `/static/uploads/edited_media/<content_id>/<new_name>`
+   - Saves metadata JSON to `/static/uploads/edited_media/<content_id>/<new_name>_metadata.json`
+   - Replaces original file in `/static/uploads/` with edited version
+   - Creates database record in `player_edit` table
+   - Increments playlist version to trigger player refresh
+   - Clears playlist cache
+4. **Player refreshes** - Next playlist check shows updated media
+
+## Version History
+
+Each edit is saved with a version number:
+- `image.jpg` → `image_v1.jpg` (first edit)
+- `image.jpg` → `image_v2.jpg` (second edit)
+- etc.
+
+All versions are preserved in the `edited_media/<content_id>/` folder.
+
+## Example cURL Request
+
+```bash
+# First, authenticate to get token
+TOKEN=$(curl -X POST http://server/api/auth/authenticate \
+  -H "Content-Type: application/json" \
+  -d '{"hostname": "player-1", "password": "password123"}' \
+  | jq -r '.token')
+
+# Upload edited media
+curl -X POST http://server/api/player-edit-media \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "image_file=@edited_image_v1.jpg" \
+  -F 'metadata={"time_of_modification":"2025-12-05T20:30:00Z","original_name":"image.jpg","new_name":"image_v1.jpg","version":1,"user":"john"}'
+```
+
+## Python Example
+
+```python
+import requests
+import json
+
+# Authenticate
+auth_response = requests.post(
+    'http://server/api/auth/authenticate',
+    json={'hostname': 'player-1', 'password': 'password123'}
+)
+token = auth_response.json()['token']
+
+# Prepare metadata
+metadata = {
+    'time_of_modification': '2025-12-05T20:30:00Z',
+    'original_name': 'image.jpg',
+    'new_name': 'image_v1.jpg',
+    'version': 1,
+    'user': 'john'
+}
+
+# Upload edited file
+with open('edited_image_v1.jpg', 'rb') as f:
+    response = requests.post(
+        'http://server/api/player-edit-media',
+        headers={'Authorization': f'Bearer {token}'},
+        files={'image_file': f},
+        data={'metadata': json.dumps(metadata)}
+    )
+
+print(response.json())
+```
+
+## Database Schema
+
+### player_edit Table
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | INTEGER | Primary key |
+| player_id | INTEGER | Foreign key to player |
+| content_id | INTEGER | Foreign key to content |
+| original_name | VARCHAR(255) | Original filename |
+| new_name | VARCHAR(255) | New filename with version |
+| version | INTEGER | Version number |
+| user | VARCHAR(255) | User who made the edit |
+| time_of_modification | DATETIME | When edit was made |
+| metadata_path | VARCHAR(512) | Path to metadata JSON |
+| edited_file_path | VARCHAR(512) | Path to edited file |
+| created_at | DATETIME | Record creation time |
+
+## UI Display
+
+Edited media history is displayed on the player management page under the "Edited Media on the Player" card, showing:
+- Original filename
+- Version number
+- Editor name
+- Modification time
+- Link to view edited file