feat: Complete Picture attachment system with polymorphic relationships (#206)

feat: Complete Picture attachment system with polymorphic relationships (#206)

* Remove the old Picture implementation
- New migration destroys the table
- Removed Model,Resource and Controller
- Removed Factory,Seeded and tests
- Remove api routes
- Updated openapi documentation

* feat: implement polymorphic picture attachment system for Items, Details, and Partners

## Features

### Core Implementation
- **Polymorphic Picture Model**: New Picture model with uuidMorphs('pictureable') for Item/Detail/Partner relationships
- **Database Migration**: Complete polymorphic table with proper indexing and UUID support
- **Enhanced Model Relationships**: Added morphMany pictures() to Item, Detail, and Partner models
- **Storage Configuration**: Added dedicated pictures storage config in localstorage.php

### API Endpoints
- POST /api/item/{item}/pictures - Attach AvailableImage to Item
- POST /api/detail/{detail}/pictures - Attach AvailableImage to Detail
- POST /api/partner/{partner}/pictures - Attach AvailableImage to Partner
- GET /api/pictures - List all pictures with polymorphic relationships
- GET /api/pictures/{id} - Show specific picture details
- PUT /api/pictures/{id} - Update picture metadata (internal_name, copyright)
- DELETE /api/pictures/{id} - Delete picture and associated file

### Attachment Workflow
- **Atomic Transactions**: File move + DB update + AvailableImage cleanup in single transaction
- **File Management**: Moves files from AvailableImage to Pictures directory
- **Metadata Extraction**: Captures file size, mime type, extension during attachment
- **Validation**: Comprehensive input validation and file existence checks
- **Error Handling**: Proper HTTP status codes and error responses

### Laravel Best Practices
- **Storage Facade**: All file operations use Laravel Storage facade
- **Database Transactions**: Ensures data consistency across file + DB operations
- **Polymorphic Relationships**: Single Picture model works with multiple parent types
- **RESTful API Design**: Proper HTTP methods, status codes, and resource patterns
- **Authentication**: All endpoints require auth:sanctum middleware

## Test Coverage (68 tests)

### Unit Tests
- Picture factory with polymorphic relationship support
- Model relationship validation across Item/Detail/Partner
- Factory state methods: forItem(), forDetail(), forPartner()

### Feature Tests
- **Attachment Tests**: Complete validation for all 3 attachment endpoints
- **CRUD Tests**: Full API testing with authentication/authorization
- **File Handling**: Storage facade mocking and file operation testing
- **Validation Tests**: Input validation, URL format, field length limits
- **Error Handling**: 404 responses, missing files, unauthorized access

### Files Changed
- app/Models/Picture.php (new)
- app/Http/Controllers/PictureController.php (new)
- app/Http/Resources/PictureResource.php (new)
- database/migrations/2025_07_08_191115_create_polymorphic_pictures_table.php (new)
- database/factories/PictureFactory.php (new)
- database/seeders/PictureSeeder.php (new)
- config/localstorage.php (updated)
- routes/api.php (updated)
- app/Models/Item.php (updated)
- app/Models/Detail.php (updated)
- app/Models/Partner.php (updated)
- tests/Unit/Picture/FactoryTest.php (new)
- tests/Feature/Api/Picture/* (new - 9 test files)
- CHANGELOG.md (updated)

## Technical Implementation

### Database Schema
`sql
CREATE TABLE pictures (
  id UUID PRIMARY KEY,
  internal_name VARCHAR(255) NOT NULL,
  backward_compatibility VARCHAR(255) NULL,
  copyright_text VARCHAR(1000) NULL,
  copyright_url VARCHAR(255) NULL,
  path VARCHAR(255) NOT NULL,
  upload_name VARCHAR(255) NOT NULL,
  upload_extension VARCHAR(50) NOT NULL,
  upload_mime_type VARCHAR(100) NOT NULL,
  upload_size BIGINT NOT NULL,
  pictureable_type VARCHAR(255) NOT NULL,
  pictureable_id UUID NOT NULL,
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  INDEX pictures_pictureable_idx (pictureable_type, pictureable_id)
);
``n
### Configuration Structure
`php
'pictures' => [
  'disk' => env('LOCAL_STORAGE_PICTURES_DISK', 'public'),
  'directory' => env('LOCAL_STORAGE_PICTURES_DIRECTORY', 'pictures'),
]
``n
This implementation provides a complete, tested, and Laravel-compliant solution for attaching images to Items, Details, and Partners with proper file management, database consistency, and comprehensive API coverage.

* # 📝 Update documentation for Picture attachment system

## 🎯 Summary

Updated comprehensive documentation across README.md and docs/ folder to reflect the new polymorphic Picture attachment system and updated storage configuration.

## 📚 Documentation Updates

### README.md
- **Picture Model Description**: Updated to reflect polymorphic relationships with Items, Details, and Partners
- **AvailableImage Model**: Enhanced description of processed image pool and attachment workflow
- **Image Processing Pipeline**: Added comprehensive section detailing 5-step workflow:
  1. Upload via `/api/image-upload`
  2. Background processing and optimization
  3. AvailableImage pool creation
  4. Transactional attachment to models
  5. Picture record management with full CRUD
- **Custom Endpoints**: Added Picture attachment endpoints and image management routes
- **API Endpoints Table**: Updated Pictures and AvailableImages descriptions
- **Storage Configuration**: Updated environment variables to reflect new naming structure

### docs/api-documentation.md
- **Picture Attachment Workflow**: Added detailed 5-step process documentation
- **Key Features**: Enhanced with polymorphic system, image pipeline, and mobile auth
- **Interactive Features**: Added file upload/download capabilities and polymorphic relationship management

### docs/api-models.md
- **Picture Model**: Added comprehensive documentation with:
  - Polymorphic relationships via `pictureable_type` and `pictureable_id`
  - Complete image metadata fields
  - Transactional file operations
  - Direct download and inline viewing capabilities
  - Storage configuration and attachment workflow
- **AvailableImage Model**: Enhanced with attachment workflow details
- **Data Relationships**: Added polymorphic Picture relationships diagram

### docs/index.md
- **Features**: Updated test counts and added polymorphic Picture system
- **Image Processing Pipeline**: Added comprehensive bullet points with transactional operations

## 🔧 Technical Details

- **Polymorphic Relationships**: Items, Details, and Partners can all have Pictures
- **Storage Configuration**: Clear separation of upload, available, and pictures storage
- **Transactional Operations**: Atomic file moves and database operations
- **File Management**: Automatic cleanup and metadata tracking
- **API Endpoints**: Complete CRUD plus specialized attachment endpoints

## ✅ Quality Assurance

- All documentation updated to reflect current implementation
- Consistent formatting and terminology across all files
- Clear workflow explanations for developers
- Updated API endpoint tables and relationship diagrams
- Storage configuration examples aligned with environment variables

## 🔗 Related

- Follows up on Picture attachment system implementation
- Complements existing CHANGELOG.md documentation
- Maintains consistency with Laravel 12 best practices
- Supports GitHub Pages documentation deployment

* Committing the updated openapi specifications

---------

Co-authored-by: Pascal HAVELANGE <havelangep@hotmail.com>