Big commit whatever

2026-06-04 12:44:22 +02:00
parent ee1a87f125
commit 4fb7b1691c
133 changed files with 26137 additions and 1097 deletions
@@ -0,0 +1,564 @@
+# Laravel Jukebox API - Complete Documentation
+
+## Project Overview
+- **Framework**: Laravel 13.0
+- **PHP Version**: ^8.3
+- **Database**: MySQL (configured via Docker at 172.17.0.1:3306)
+- **Authentication**: Laravel Sanctum 4.0 (Token-based API authentication)
+- **Purpose**: Music streaming/management API with role-based access control
+
+---
+
+## 1. API ROUTES
+
+### Location: `/routes/api.php`
+
+#### Public Routes (No Authentication Required)
+```
+POST   /register              - User registration
+POST   /login                 - User login
+```
+
+#### Authenticated Routes (Requires Sanctum token)
+
+**Auth Endpoints:**
+```
+POST   /logout                - Logout user
+GET    /me                    - Get current user info
+```
+
+**User Likes (Authenticated):**
+```
+GET    /me/likes              - Get user's liked tracks
+POST   /tracks/{track}/like   - Like a track
+DELETE /tracks/{track}/like   - Unlike a track
+```
+
+**Browse Routes (Read-only for authenticated users):**
+```
+GET    /labels                - List all labels
+GET    /labels/{label}        - Get label details
+GET    /genres                - List all genres
+GET    /genres/{genre}        - Get genre details
+GET    /artists               - List all artists
+GET    /artists/{artist}      - Get artist details
+GET    /albums                - List all albums
+GET    /albums/{album}        - Get album details
+GET    /tracks                - List all tracks
+GET    /tracks/{track}        - Get track details
+```
+
+**Admin-Only Routes (Requires 'admin' role):**
+```
+POST   /labels                - Create label
+PUT    /labels/{label}        - Update label
+DELETE /labels/{label}        - Delete label
+
+POST   /genres                - Create genre
+PUT    /genres/{genre}        - Update genre
+DELETE /genres/{genre}        - Delete genre
+
+POST   /artists               - Create artist
+PUT    /artists/{artist}      - Update artist
+DELETE /artists/{artist}      - Delete artist
+
+POST   /albums                - Create album
+PUT    /albums/{album}        - Update album
+DELETE /albums/{album}        - Delete album
+
+POST   /tracks                - Create track
+PUT    /tracks/{track}        - Update track
+DELETE /tracks/{track}        - Delete track
+
+GET    /users                 - List all users
+GET    /users/{user}          - Get user details
+PUT    /users/{user}          - Update user
+DELETE /users/{user}          - Delete user
+```
+
+#### Web Routes (`routes/web.php`)
+- Minimal: Single `GET /` returning welcome view (for blade/HTML views)
+
+---
+
+## 2. CONTROLLERS & METHODS
+
+### AuthController (`app/Http/Controllers/AuthController.php`)
+**Methods:**
+- `register(Request $request): JsonResponse` - Handles user registration
+  - Validates: name, email, password (min 8 chars, confirmed)
+  - Creates user with default 'user' role
+  - Returns token + user object
+  - HTTP 201
+
+- `login(Request $request): JsonResponse` - Handles user login
+  - Validates: email, password
+  - Returns token + user object if credentials valid
+  - Throws ValidationException if invalid
+
+- `logout(Request $request): JsonResponse` - Deletes current access token
+  - Returns success message
+
+- `me(Request $request): JsonResponse` - Returns current authenticated user
+  - Loads user role relationship
+
+---
+
+### UserController (`app/Http/Controllers/UserController.php`)
+**Methods:**
+- `index(): JsonResponse` - List all users with roles
+- `show(User $user): JsonResponse` - Get single user with role
+- `update(Request $request, User $user): JsonResponse`
+  - Validates: name, email (unique), password, role_id
+  - Returns updated user with role
+- `destroy(User $user): JsonResponse` - Delete user
+  - Returns HTTP 204
+
+---
+
+### ArtistController (`app/Http/Controllers/ArtistController.php`)
+**Methods:**
+- `index(): JsonResponse` - List artists with label relationship
+- `show(Artist $artist): JsonResponse` - Get artist with label, tracks, genres
+- `store(Request $request): JsonResponse`
+  - Validates: name, cover_path (nullable), release_date (nullable), label_id, duration
+  - Returns HTTP 201
+- `update(Request $request, Artist $artist): JsonResponse` - Update artist
+- `destroy(Artist $artist): JsonResponse` - Delete artist
+
+---
+
+### AlbumController (`app/Http/Controllers/AlbumController.php`)
+**Methods:**
+- `index(): JsonResponse` - List albums with labels
+- `show(Album $album): JsonResponse` - Get album with label, tracks, artists, genres
+- `store(Request $request): JsonResponse`
+  - Validates: title, cover_path, release_date, duration_seconds, type (enum: album|single|ep), label_id
+  - Returns HTTP 201
+- `update(Request $request, Album $album): JsonResponse` - Update album
+- `destroy(Album $album): JsonResponse` - Delete album
+
+---
+
+### TrackController (`app/Http/Controllers/TrackController.php`)
+**Methods:**
+- `index(): JsonResponse` - List tracks with album, artists, genres
+- `show(Track $track): JsonResponse` - Get track with album.label, artists, genres
+- `store(Request $request): JsonResponse`
+  - Validates: title, file_path, duration_seconds (nullable), album_id (nullable), artist_ids (array), genre_ids (array)
+  - Syncs artist and genre relationships
+  - Returns HTTP 201
+- `update(Request $request, Track $track): JsonResponse`
+  - Syncs artist and genre relationships
+- `destroy(Track $track): JsonResponse` - Delete track
+
+---
+
+### LikeController (`app/Http/Controllers/LikeController.php`)
+**Methods:**
+- `like(Request $request, Track $track): JsonResponse`
+  - Uses `syncWithoutDetaching()` to add like without removing existing ones
+- `unlike(Request $request, Track $track): JsonResponse`
+  - Uses `detach()` to remove like
+- `index(Request $request): JsonResponse`
+  - Returns user's liked tracks with album, artists, genres relationships
+
+---
+
+### GenreController (`app/Http/Controllers/GenreController.php`)
+**Methods:**
+- `index(): JsonResponse` - List all genres
+- `show(Genre $genre): JsonResponse` - Get single genre
+- `store(Request $request): JsonResponse` - Create genre (validates: name, max 100 chars)
+- `update(Request $request, Genre $genre): JsonResponse` - Update genre
+- `destroy(Genre $genre): JsonResponse` - Delete genre
+
+---
+
+### LabelController (`app/Http/Controllers/LabelController.php`)
+**Methods:**
+- `index(): JsonResponse` - List all labels
+- `show(Label $label): JsonResponse` - Get single label
+- `store(Request $request): JsonResponse` - Create label (validates: name, max 100 chars)
+- `update(Request $request, Label $label): JsonResponse` - Update label
+- `destroy(Label $label): JsonResponse` - Delete label
+
+---
+
+## 3. MODELS & RELATIONSHIPS
+
+### User Model
+**Attributes:** id, name, email, password (hashed), role_id, timestamps
+**Fillable:** name, email, password, role_id
+**Hidden:** password, remember_token
+**Traits:** HasApiTokens, HasFactory, Notifiable
+
+**Relationships:**
+- `role()`: BelongsTo(Role) - User's role
+- `likes()`: BelongsToMany(Track, 'likes') - Tracks user has liked
+
+---
+
+### Role Model
+**Attributes:** id, name, timestamps
+**Fillable:** name
+
+**Relationships:**
+- `users()`: HasMany(User) - Users with this role
+
+---
+
+### Artist Model
+**Attributes:** id, name, cover_path, release_date, label_id, duration, timestamps
+**Fillable:** name, cover_path, release_date, label_id, duration
+
+**Relationships:**
+- `label()`: BelongsTo(Label) - Artist's label
+- `tracks()`: BelongsToMany(Track, 'artist_track') - All tracks by artist
+
+---
+
+### Album Model
+**Attributes:** id, title, cover_path, release_date, duration_seconds, type (enum), label_id, timestamps
+**Fillable:** title, cover_path, release_date, duration_seconds, type, label_id
+
+**Relationships:**
+- `label()`: BelongsTo(Label) - Album's label
+- `tracks()`: HasMany(Track) - All tracks in album
+
+---
+
+### Track Model
+**Attributes:** id, title, file_path, duration_seconds, album_id, timestamps
+**Fillable:** title, file_path, duration_seconds, album_id
+
+**Relationships:**
+- `album()`: BelongsTo(Album) - Album containing track
+- `artists()`: BelongsToMany(Artist, 'artist_track') - Contributing artists
+- `genres()`: BelongsToMany(Genre, 'track_genre') - Track genres
+- `likedBy()`: BelongsToMany(User, 'likes') - Users who liked track
+
+---
+
+### Genre Model
+**Attributes:** id, name, timestamps
+**Fillable:** name
+
+**Relationships:**
+- `tracks()`: BelongsToMany(Track, 'track_genre') - Tracks in genre
+
+---
+
+### Label Model
+**Attributes:** id, name, timestamps
+**Fillable:** name
+
+**Relationships:**
+- `artists()`: HasMany(Artist) - Artists on label
+- `albums()`: HasMany(Album) - Albums on label
+
+---
+
+## 4. DATABASE SCHEMA & MIGRATIONS
+
+### Tables Created (in order)
+
+**1. roles**
+- id (PRIMARY)
+- name (VARCHAR)
+- timestamps
+
+**2. genres**
+- id (PRIMARY)
+- name (VARCHAR 100)
+- timestamps
+
+**3. labels**
+- id (PRIMARY)
+- name (VARCHAR 100)
+- timestamps
+
+**4. users**
+- id (PRIMARY)
+- name (VARCHAR)
+- email (VARCHAR)
+- password (VARCHAR)
+- role_id (FOREIGN KEY → roles.id)
+- timestamps
+
+**5. artists**
+- id (PRIMARY)
+- name (VARCHAR 255)
+- cover_path (VARCHAR 255, nullable)
+- release_date (DATETIME, nullable)
+- label_id (FOREIGN KEY → labels.id, nullable)
+- duration (INTEGER, nullable)
+- timestamps
+
+**6. albums**
+- id (PRIMARY)
+- title (VARCHAR 255)
+- cover_path (VARCHAR 255, nullable)
+- release_date (DATETIME, nullable)
+- duration_seconds (INTEGER, nullable)
+- type (ENUM: 'album', 'single', 'ep', default: 'album')
+- label_id (FOREIGN KEY → labels.id, nullable)
+- timestamps
+
+**7. tracks**
+- id (PRIMARY)
+- title (VARCHAR 255)
+- file_path (VARCHAR 255)
+- duration_seconds (INTEGER, nullable)
+- album_id (FOREIGN KEY → albums.id, nullable)
+- timestamps
+
+**8. artist_track** (pivot table)
+- artist_id (FOREIGN KEY → artists.id)
+- track_id (FOREIGN KEY → tracks.id)
+- PRIMARY KEY: (artist_id, track_id)
+- timestamps
+
+**9. track_genre** (pivot table)
+- track_id (FOREIGN KEY → tracks.id)
+- genre_id (FOREIGN KEY → genres.id)
+- PRIMARY KEY: (track_id, genre_id)
+- timestamps
+
+**10. likes** (pivot table)
+- user_id (FOREIGN KEY → users.id)
+- track_id (FOREIGN KEY → tracks.id)
+- PRIMARY KEY: (user_id, track_id)
+- timestamps
+
+**11. personal_access_tokens** (Sanctum)
+- id (PRIMARY)
+- tokenable_id, tokenable_type (polymorphic)
+- name (TEXT)
+- token (VARCHAR 64, UNIQUE)
+- abilities (TEXT, nullable)
+- last_used_at (TIMESTAMP, nullable)
+- expires_at (TIMESTAMP, nullable, indexed)
+- timestamps
+
+---
+
+## 5. AUTHENTICATION & AUTHORIZATION
+
+### Sanctum Configuration (`config/sanctum.php`)
+
+**Stateful Domains:**
+- localhost, localhost:3000, 127.0.0.1, 127.0.0.1:8000, ::1
+- Plus current application URL
+
+**Guard:** web (session guard, though API uses bearer tokens)
+
+**Expiration:** null (tokens don't expire automatically)
+
+**Token Prefix:** env('SANCTUM_TOKEN_PREFIX', '')
+
+**Middleware:**
+- authenticate_session: Laravel\Sanctum\Http\Middleware\AuthenticateSession
+- encrypt_cookies: Illuminate\Cookie\Middleware\EncryptCookies
+- validate_csrf_token: Illuminate\Foundation\Http\Middleware\ValidateCsrfToken
+
+### Auth Configuration (`config/auth.php`)
+
+**Default Guard:** web (session-based)
+
+**User Provider:** Eloquent (uses App\Models\User)
+
+**Password Broker:** users (uses users table)
+
+**Token Expiry:** 60 minutes
+
+### Custom Middleware
+
+**EnsureAdmin** (`app/Http/Middleware/EnsureAdmin.php`)
+- Checks if user's role name is 'admin'
+- Returns 403 Forbidden if not admin
+- Applied to routes group via 'admin' alias in `bootstrap/app.php`
+
+---
+
+## 6. SEEDERS & FACTORIES
+
+### DatabaseSeeder (`database/seeders/DatabaseSeeder.php`)
+Currently creates a single test user:
+```
+Name: Test User
+Email: test@example.com
+Password: Uses UserFactory default
+```
+
+The seeder is commented to create 10 users but currently just creates 1.
+
+### UserFactory (`database/factories/UserFactory.php`)
+**Attributes Generated:**
+- name: fake()->name()
+- email: fake()->unique()->safeEmail()
+- email_verified_at: now()
+- password: Hash::make('password')
+- remember_token: Str::random(10)
+
+**Methods:**
+- `unverified()`: Sets email_verified_at to null
+
+**Note:** No factory exists for other models (Artist, Album, Track, Genre, Label)
+
+---
+
+## 7. CORS CONFIGURATION
+
+**Status:** No explicit CORS configuration found
+
+**Implications:**
+- No `config/cors.php` file
+- Sanctum handles CORS implicitly via stateful domains configuration
+- Likely relying on Laravel default CORS handling or missing CORS setup
+- Frontend on localhost:3000 should work (listed in stateful domains)
+
+**Recommendation:** May need explicit CORS middleware for production cross-origin requests
+
+---
+
+## 8. RESOURCES & TRANSFORMERS
+
+**Status:** No JSON:API Resources or Transformers found
+
+**Current Approach:**
+- Direct Eloquent model casting to JSON
+- Raw `response()->json()` returns from controllers
+- Relationships loaded via `load()` and `with()` methods
+- No API resource classes (Laravel Resource classes) implemented
+
+**Data Transformation:**
+- Manual eager loading in controllers
+- Example: `$artist->load(['label', 'tracks.album', 'tracks.genres'])`
+
+---
+
+## 9. ENVIRONMENT CONFIGURATION
+
+### .env (Development)
+```
+APP_NAME=Laravel
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost
+
+DB_CONNECTION=mysql
+DB_HOST=172.17.0.1
+DB_PORT=3306
+DB_DATABASE=jukebox
+DB_USERNAME=jukebox_admin
+DB_PASSWORD=Super
+
+SESSION_DRIVER=database
+CACHE_STORE=database
+QUEUE_CONNECTION=database
+```
+
+### Key Settings
+- Debug mode enabled (local)
+- MySQL via Docker (172.17.0.1)
+- Database-backed sessions
+- Database-backed queue
+- Database-backed cache
+
+---
+
+## 10. DEPENDENCIES
+
+**Core:**
+- laravel/framework: ^13.0
+- laravel/sanctum: ^4.0
+- laravel/tinker: ^3.0
+
+**Dev:**
+- fakerphp/faker: ^1.23
+- laravel/pail: ^1.2.5
+- laravel/pint: ^1.27
+- mockery/mockery: ^1.6
+- nunomaduro/collision: ^8.6
+- phpunit/phpunit: ^12.5.12
+
+---
+
+## 11. KEY OBSERVATIONS & NOTES
+
+### Strengths
+1. **Clean Role-Based Architecture** - Admin/User separation via middleware
+2. **Proper Eloquent Relationships** - All pivot tables correctly implemented
+3. **Token-Based Auth** - Sanctum for stateless API authentication
+4. **Comprehensive Data Model** - Well-structured music catalog schema
+
+### Areas for Enhancement
+1. **No Resources/Transformers** - Consider Laravel API Resources for consistent responses
+2. **No CORS Config** - Explicit CORS setup recommended for production
+3. **Limited Factories** - Only UserFactory; others could enable better testing
+4. **No API Documentation** - Consider OpenAPI/Swagger docs
+5. **No Request DTOs** - Could use Form Requests for centralized validation
+6. **No Response Standardization** - No consistent error/success response format
+7. **No Pagination** - List endpoints return all results (performance concern)
+8. **No Query Filtering** - No search/filter capabilities on GET endpoints
+9. **No Rate Limiting** - No API rate limiting configured
+10. **Minimal Seeding** - Only test user; could seed sample data
+
+### Security Considerations
+1. Password hashing properly handled via Laravel
+2. CSRF protection configured (though API uses tokens)
+3. Access control via admin middleware is solid
+4. Foreign key constraints prevent orphaned records
+5. Role-based authorization working correctly
+
+### API Response Format
+Current format (no wrapper):
+```json
+{
+  "id": 1,
+  "name": "Track Name",
+  "duration_seconds": 240,
+  "created_at": "2026-04-23T...",
+  "updated_at": "2026-04-23T..."
+}
+```
+
+Could benefit from standardized wrapper:
+```json
+{
+  "success": true,
+  "data": { ... },
+  "message": "Success"
+}
+```
+
+---
+
+## 12. TESTING STRUCTURE
+
+**Test Framework:** PHPUnit 12.5.12
+
+**Test Directories:**
+- `tests/Feature/` - Feature tests
+- `tests/Unit/` - Unit tests
+- `tests/TestCase.php` - Base test class
+
+**Example Tests:** ExampleTest.php files (placeholder)
+
+**No comprehensive tests currently implemented**
+
+---
+
+## Summary
+
+This is a **music streaming/library API** built with Laravel 13, featuring:
+- ✅ User registration & login with Sanctum tokens
+- ✅ Role-based access control (admin/user)
+- ✅ Full CRUD for Artists, Albums, Tracks, Genres, Labels
+- ✅ User favorites/likes system
+- ✅ Proper database schema with relationships
+- ⚠️ Minimal documentation, testing, and optimization
+- ⚠️ Missing common API best practices
+
+Ready for development and enhancement with proper testing, documentation, and optimization work.