added prp

2025-11-11 21:23:00 +01:00
parent d271f256b7
commit 0c83b15636
9 changed files with 4823 additions and 0 deletions
--- a/prp/api-specification.md
+++ b/prp/api-specification.md
@@ -0,0 +1,522 @@
+# API Specification
+
+## Overview
+RESTful API built with Laravel Sanctum for authentication. Provides endpoints for image management, style application, and AI processing integration.
+
+## Base URL
+```
+/api
+```
+
+## Authentication
+Laravel Sanctum token-based authentication using `Authorization: Bearer <token>` header.
+
+## Response Format
+All responses use JSON format with consistent structure:
+
+### Success Response
+```json
+{
+  "message": "Operation completed successfully",
+  "data": { ... }
+}
+```
+
+### Error Response
+```json
+{
+  "error": "Error description",
+  "message": "Detailed error message"
+}
+```
+
+## Endpoints
+
+### 1. Image Management
+
+#### 1.1 Get Images
+**Endpoint**: `GET /api/images`
+
+**Authentication**: Not required (filtered by visibility rules)
+
+**Description**: Retrieves paginated list of images with automatic filesystem synchronization
+
+**Query Parameters**:
+- None
+
+**Response**:
+```json
+[
+  {
+    "image_id": 1,
+    "path": "/storage/uploads/image.jpg",
+    "name": "image.jpg",
+    "is_temp": false,
+    "is_public": true,
+    "is_new": true
+  }
+]
+```
+
+**Business Logic**:
+- Synchronizes filesystem with database before returning results
+- Filters images based on authentication status
+- Adds `is_new` flag for recently uploaded images (within configurable timespan)
+- Returns images in descending order by `updated_at`
+
+**Error Codes**:
+- `500`: Internal server error during synchronization
+
+---
+
+#### 1.2 Upload Image
+**Endpoint**: `POST /api/images/upload`
+
+**Authentication**: Not required
+
+**Description**: Uploads new image file to the gallery
+
+**Request Body** (multipart/form-data):
+```json
+{
+  "image": "file (JPEG, PNG, WebP, max 10MB)"
+}
+```
+
+**Response**:
+```json
+{
+  "message": "Image uploaded successfully",
+  "image_id": 1,
+  "path": "/storage/uploads/new-image.jpg"
+}
+```
+
+**Validation Rules**:
+- `image`: required, image file, mime types: jpeg,png,webp, max:10240KB
+
+**Business Logic**:
+- Generates unique filename to prevent conflicts
+- Stores in `public/storage/uploads/` directory
+- Creates database record with `is_public = true`
+- Returns full URL path for immediate use
+
+**Error Codes**:
+- `422`: Validation failed (invalid file type/size)
+- `500`: File storage error
+
+---
+
+#### 1.3 Apply Style to Image
+**Endpoint**: `POST /api/images/style-change`
+
+**Authentication**: Not required (same-origin check)
+
+**Description**: Initiates AI style transformation process
+
+**Headers**:
+```
+Referer: https://yourdomain.com (same-origin validation)
+```
+
+**Request Body**:
+```json
+{
+  "image_id": 1,
+  "style_id": 1
+}
+```
+
+**Response**:
+```json
+{
+  "message": "Style change request sent",
+  "prompt_id": "comfyui-job-123",
+  "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
+  "plugin": "comfyui"
+}
+```
+
+**Validation Rules**:
+- `image_id`: required, exists in `images` table
+- `style_id`: nullable, exists in `styles` table
+
+**Business Logic**:
+- Validates same-origin request for security
+- Loads appropriate AI plugin based on style's API provider
+- Updates image record with `comfyui_prompt_id` and `style_id`
+- Returns tracking information for frontend progress monitoring
+
+**Error Codes**:
+- `403`: Unauthorized origin
+- `404`: Image or style not found
+- `422`: Validation failed
+- `500`: Plugin processing error
+
+---
+
+#### 1.4 Fetch Styled Image Result
+**Endpoint**: `GET /api/images/fetch-styled/{promptId}`
+
+**Authentication**: Not required
+
+**Description**: Retrieves result of completed AI style transformation
+
+**Path Parameters**:
+- `promptId`: string (ComfyUI job identifier)
+
+**Response**:
+```json
+{
+  "message": "Styled image fetched successfully",
+  "styled_image": {
+    "id": 2,
+    "path": "/storage/uploads/styled_image.png",
+    "is_temp": true
+  }
+}
+```
+
+**Business Logic**:
+- Finds image record by `comfyui_prompt_id`
+- Loads appropriate AI plugin to fetch result
+- Saves styled image to filesystem
+- Creates new database record for styled image
+- Links styled image to original via `original_image_id`
+
+**Error Codes**:
+- `404`: Image not found or still processing
+- `500`: Plugin fetch error or file save error
+
+---
+
+#### 1.5 Keep Styled Image
+**Endpoint**: `POST /api/images/keep`
+
+**Authentication**: Required (Sanctum)
+
+**Description**: Converts temporary styled image to permanent
+
+**Request Body**:
+```json
+{
+  "image_id": 2
+}
+```
+
+**Response**:
+```json
+{
+  "message": "Image kept successfully"
+}
+```
+
+**Validation Rules**:
+- `image_id`: required, exists in `images` table
+
+**Business Logic**:
+- Verifies user owns the image
+- Sets `is_temp = false` on image record
+- Image becomes permanent part of user's gallery
+
+**Error Codes**:
+- `401`: Unauthenticated
+- `404`: Image not found
+- `403`: User doesn't own image
+
+---
+
+#### 1.6 Delete Image
+**Endpoint**: `DELETE /api/images/{image}`
+
+**Authentication**: Required (Sanctum)
+
+**Description**: Permanently removes image and file
+
+**Path Parameters**:
+- `image`: integer (image ID)
+
+**Response**:
+```json
+{
+  "message": "Image deleted successfully"
+}
+```
+
+**Business Logic**:
+- Verifies user owns the image
+- Deletes physical file from storage
+- Removes database record
+- Cascading: styled images deleted when original is deleted
+
+**Error Codes**:
+- `401`: Unauthenticated
+- `404`: Image not found
+- `403`: User doesn't own image
+- `500`: File deletion error
+
+---
+
+#### 1.7 Get Image Status (Deprecated)
+**Endpoint**: `GET /api/images/status`
+
+**Authentication**: Not required
+
+**Description**: Legacy endpoint for image processing status
+
+**Query Parameters**:
+```json
+{
+  "image_id": 1,
+  "api_provider_name": "ComfyUI"
+}
+```
+
+**Response**:
+```json
+{
+  "status": "unknown"
+}
+```
+
+**Note**: Currently returns static response, replaced by WebSocket progress
+
+---
+
+### 2. Style Management
+
+#### 2.1 Get Available Styles
+**Endpoint**: `GET /api/styles`
+
+**Authentication**: Not required
+
+**Description**: Retrieves all enabled styles for style selector
+
+**Response**:
+```json
+[
+  {
+    "id": 1,
+    "title": "Oil Painting",
+    "description": "Classic oil painting style",
+    "preview_image": "/storage/style_previews/oil-painting.jpg",
+    "enabled": true
+  }
+]
+```
+
+**Business Logic**:
+- Returns only enabled styles
+- Includes preview images for UI display
+- Ordered by `sort_order` field
+
+**Error Codes**:
+- `500`: Database query error
+
+---
+
+### 3. AI Provider Management
+
+#### 3.1 Get ComfyUI URL
+**Endpoint**: `GET /api/comfyui-url`
+
+**Authentication**: Not required
+
+**Description**: Returns WebSocket URL for real-time progress updates
+
+**Query Parameters** (optional):
+```json
+{
+  "style_id": 1,
+  "image_uuid": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+**Response**:
+```json
+{
+  "comfyui_url": "https://your-comfyui-server.com"
+}
+```
+
+**Business Logic**:
+- Determines appropriate API provider based on style or image
+- Falls back to first available ComfyUI provider if none specified
+- Returns base URL for WebSocket connection
+
+**Error Codes**:
+- `404`: No enabled ComfyUI provider found
+
+---
+
+### 4. User Management
+
+#### 4.1 Get Authenticated User
+**Endpoint**: `GET /api/user`
+
+**Authentication**: Required (Sanctum)
+
+**Description**: Returns current authenticated user information
+
+**Response**:
+```json
+{
+  "id": 1,
+  "name": "John Doe",
+  "email": "john@example.com",
+  "role": "user",
+  "theme_preference": "light",
+  "locale": "en"
+}
+```
+
+**Error Codes**:
+- `401`: Unauthenticated
+
+---
+
+### 5. Admin Management
+
+#### 5.1 Store Navigation State
+**Endpoint**: `POST /api/admin/navigation-state`
+
+**Authentication**: Required (Sanctum)
+
+**Description**: Saves admin panel navigation preferences
+
+**Request Body**:
+```json
+{
+  "state": "collapsed",
+  "active_tab": "dashboard"
+}
+```
+
+**Response**:
+```json
+{
+  "message": "Navigation state saved"
+}
+```
+
+**Business Logic**:
+- Stores UI state preferences for admin users
+- Used by Filament admin panel for user experience
+
+---
+
+## WebSocket Integration
+
+### ComfyUI Progress Updates
+
+**Connection**:
+```
+WebSocket URL: ws://{comfyui-server-host}/ws
+```
+
+**Message Format**:
+```json
+{
+  "type": "progress",
+  "data": {
+    "prompt_id": "job-123",
+    "value": 50,
+    "max": 100
+  }
+}
+```
+
+**Frontend Handling**:
+- Connect to WebSocket after receiving `prompt_id` from style-change endpoint
+- Monitor progress messages for matching `prompt_id`
+- Update UI progress bar based on `value/max` percentage
+- Fetch final result when progress reaches 100%
+
+## Error Handling
+
+### HTTP Status Codes
+- `200`: Success
+- `201`: Created
+- `400`: Bad Request
+- `401`: Unauthenticated
+- `403`: Forbidden
+- `404`: Not Found
+- `422`: Validation Error
+- `500`: Internal Server Error
+
+### Error Response Structure
+```json
+{
+  "error": "Human readable error message",
+  "message": "Technical details for debugging",
+  "errors": {
+    "field_name": ["Specific field validation errors"]
+  }
+}
+```
+
+## Rate Limiting
+
+### Current Implementation
+- No explicit rate limiting configured
+- External AI services may have their own limits
+- Consider implementing for production deployment
+
+### Recommended Limits
+- Image upload: 10 per minute per user
+- Style change requests: 5 per minute per user
+- API calls: 1000 per hour per user
+
+## Security Considerations
+
+### Authentication
+- Laravel Sanctum for API authentication
+- Bearer token in Authorization header
+- CSRF protection for web routes
+
+### Input Validation
+- All inputs validated using Laravel Form Requests
+- File upload restrictions (type, size)
+- SQL injection prevention via Eloquent ORM
+
+### Same-Origin Policy
+- Style change endpoint validates request origin
+- Prevents CSRF attacks from external sites
+
+### File Security
+- Uploaded files stored outside web root
+- File type validation prevents malicious uploads
+- Secure file permissions on storage directories
+
+## Performance Considerations
+
+### Caching
+- No explicit caching implemented
+- Consider caching for frequently accessed data:
+  - Available styles list
+  - User permissions
+  - API provider configurations
+
+### Database Optimization
+- Eager loading for relationships (styles → ai_models → api_providers)
+- Consider indexes on frequently queried fields
+- Automatic filesystem synchronization on image listing
+
+### File Storage
+- Images stored on local filesystem
+- Consider CDN integration for global distribution
+- Automatic cleanup of temporary files
+
+## Future API Enhancements
+
+### Potential Endpoints
+- `GET /api/images/{id}/history` - Processing history for image
+- `POST /api/images/batch-style-change` - Apply style to multiple images
+- `GET /api/styles/search?q=term` - Search styles by name/description
+- `POST /api/users/preferences` - Update user preferences
+- `GET /api/admin/stats` - Application statistics for admins
+
+### WebSocket Enhancements
+- Real-time notifications for all users
+- Live gallery updates when new images are processed
+- Admin monitoring of processing queue status