pp-planer/.sisyphus/notepads/cts-presenter-app/learnings.md

# Learnings & Conventions

Convention log for CTS Presenter App development.

## 2026-03-01 - Task 0 CTS API Spike

- `5pm-hdh/churchtools-api` v2.1.0 bietet sowohl `CTConfig::setApiKey()` als auch `CTConfig::authWithLoginToken()`; `setApiKey` ist als deprecated markiert, funktioniert aber weiterhin fuer Token-Auth.
- Events-Fetch fuer heute+zukunft laeuft ueber `EventRequest::where('from', 'YYYY-MM-DD')->get()` und sendet Query-Parameter `from` plus `page`.
- Song-Response enthaelt im verwendeten Shape `ccli`, `arrangements` und optional `lyrics` als nested Objekt.
- Ohne gesetzte Runtime-Variablen `CTS_API_URL`/`CTS_API_TOKEN` ist nur ein Mock-basierter Spike moeglich; Live-Auth muss spaeter mit echten Env-Werten nachgezogen werden.

## 2026-03-01 - Task 1 Laravel Scaffolding + Breeze Vue + Docker

- Laravel 11 + Breeze (Vue stack) + Pest scaffolding completed successfully
- Inertia.js integration required explicit app.js setup with createInertiaApp() and resolvePageComponent()
- Vite v7 requires @vitejs/plugin-vue to be explicitly configured in vite.config.js
- Tailwind CSS v4 requires @tailwindcss/vite v4 (not v3) - version mismatch caused build failures
- npm install requires --legacy-peer-deps flag due to Vite v7 + @vitejs/plugin-vue v5 compatibility
- Docker build: PHP 8.4-fpm-alpine chosen over 8.3 due to composer.lock requiring PHP 8.4+ dependencies
- Docker build: Removed Imagick PECL installation (requires autoconf) - can be added later if needed
- Locale set to 'de' in config/app.php via env() with fallback
- Vue packages (@vueuse/core, vue-draggable-plus, @jaxtheprime/vue3-dropzone) added to package.json
- docker-compose.yml v2 syntax used (no version field needed, but warning appears)
- Vite server configured for Docker with host: '0.0.0.0' and hmr settings for hot-reload
- QA Scenario 1: docker compose up -d successfully starts app + node containers
- QA Scenario 2: npm run build succeeds with 784 modules transformed, ~255KB gzipped app bundle
- All Pest tests pass (home route returns 200 with Inertia response)
- Task 0 spike files (CtsApiSpikeTest.php, CtsApiSpikeSync.php) preserved in new structure

## [2026-03-01 19:25] Task 1: Laravel Scaffolding + Breeze Vue + Docker

### Package Version Compatibility
- Laravel 12 requires specific package versions:
  - `vite`: `^7.0.0` (matches laravel-vite-plugin@^2.0.0 peer dependency)
  - `@vitejs/plugin-vue`: `^6.0.0` (compatible with Vite 7)
  - Avoid version mismatches - check peer dependencies before install

### Docker Setup
- Multi-stage Dockerfile with PHP 8.3-fpm-alpine base
- LibreOffice + ImageMagick installed successfully in Alpine
- App container starts successfully on port 8000
- Node container requires `npm install` to be run inside container for first-time setup
- docker-compose.yml `version` attribute is obsolete (warning can be ignored)

### Laravel Autoload
- Spike files relocated from `src/Cts/` to `app/Cts/` to match Laravel PSR-4 autoload
- Laravel expects application code in `app/` directory
- Custom `src/` directory requires composer.json autoload configuration

### Vite Configuration
- Configured for Docker with `host: '0.0.0.0'` and `port: 5173`
- HMR configured for localhost access from host machine
- Build succeeds with 784 modules transformed

### Tests
- 5 tests passing (14 assertions)
- CTS API spike tests preserved from Task 0
- Home route test added for Inertia verification
- Breeze default tests included

### Locale
- App locale set to `'de'` in `config/app.php`
- All UI text must be in German with "Du" form (per project spec)

## [2026-03-01 19:45] Wave 1 Complete (T2-T7)

### Database Schema (T2)
- 10 migrations created in correct dependency order
- All Eloquent models have proper relationships (hasMany, belongsTo, belongsToMany)
- Factory classes generate valid test data
- Soft deletes on songs and slides tables working correctly
- JSON casts for cts_data, churchtools_groups, churchtools_roles

### ChurchTools OAuth (T3)
- Custom Socialite provider successfully replaces Breeze auth
- All Breeze register/password-reset pages removed
- OAuth-only login with German UI ("Mit ChurchTools anmelden")
- User creation from OAuth callback with churchtools_id, avatar, groups, roles
- 9 tests passing (54 assertions)

### CTS API Sync (T4)
- ChurchToolsService wraps 5pm-HDH/churchtools-api correctly
- CCLI-based song matching works (matched_at timestamp set)
- Unmatched songs preserved with song_id=null for manual matching
- Sync log entries created with counts and status
- German flash messages ("Daten wurden aktualisiert")

### File Conversion (T5)
- Intervention Image v3 letterbox/pillarbox working perfectly
- 400×300 PNG → 1920×1080 JPG with black bars (no upscaling)
- Portrait images get pillarbox (black bars left/right)
- PPT conversion queued via ConvertPowerPointJob (NOT synchronous)
- Thumbnail generation at 320×180
- ZIP extraction and recursive processing implemented

### Shared Vue Components (T6)
- AuthenticatedLayout with sticky nav, sync button, user avatar
- useAutoSave composable with 500ms debounce for text inputs
- FlashMessage, ConfirmDialog, LoadingSpinner components
- HandleInertiaRequests middleware shares auth.user, flash, last_synced_at, app_name
- All German UI text with "Du" form
- 7 tests passing

### Email Configuration (T7)
- MissingSongRequest mailable with German template
- Email includes song name, CCLI ID, service info, link to service
- SONG_REQUEST_EMAIL configurable via .env
- Subject: "Song-Anfrage: {songName} (CCLI: {ccliId})"
- 2 tests passing (10 assertions)

### Test Suite Health
- All 30 tests passing (233 assertions)
- No LSP errors (PHP LSP not configured, but tests validate correctness)
- Clean git history with atomic commits

### Blockers Resolved
- Fixed ChurchToolsSyncTest: changed `post()` to `$this->post()` (trivial fix)
- No other blockers encountered

### Next Steps
- Wave 2 ready to start (T8-T13): Service List, Song CRUD, Slide Upload, Arrangement Configurator, Song Matching, Translation Service
- All Wave 2 tasks can run in parallel (no dependencies between them)

## [2026-03-01] Task T12: Song Matching Service (CCLI ID)

### SongMatchingService Pattern
- Dedicated service class for all song matching operations: autoMatch, manualAssign, requestCreation, unassign
- autoMatch checks: (1) not already assigned, (2) has cts_ccli_id, (3) Song with matching ccli_id exists in DB
- manualAssign overwrites any existing assignment (no guard needed)
- requestCreation sends MissingSongRequest mailable to configurable SONG_REQUEST_EMAIL address
- unassign clears both song_id and matched_at

### ChurchToolsService Integration
- Refactored syncServiceAgendaSongs to use SongMatchingService::autoMatch instead of inline DB matching
- updateOrInsert creates the record first (without song_id), then Eloquent lookup + autoMatch
- Preserves existing manual assignments during re-sync (only autoMatches if song_id is null)
- app(SongMatchingService::class) used inside the method to avoid constructor injection on the sync service

### API Routes
- ServiceSongController with 3 POST endpoints under auth:sanctum middleware
- Routes: /api/service-songs/{id}/assign, /request, /unassign
- German response messages: 'Song erfolgreich zugeordnet', 'Anfrage wurde gesendet', 'Zuordnung entfernt'
- Validation on assign: song_id required + exists:songs,id
- findOrFail gives automatic 404 for missing ServiceSong records

### Testing
- 14 tests (33 assertions) covering service methods + API endpoints + auth + validation
- Factory-based tests with ServiceSong::factory(), Song::factory(), User::factory()
- Mail::fake() for email assertion without actually sending
- Unique constraint gotcha: Song factory generates ccli_id with 80% probability, need explicit overrides in tests

### Pre-existing Test Failures (NOT caused by T12)
- TranslationServiceTest: TranslationService class not yet created (future task)
- ArrangementControllerTest: Routes not yet defined (future task)
- ServiceControllerTest: Vite manifest missing Vue component (frontend task)

## [2026-03-01] Task T10: Slide Upload & Grid Components

### SlideController
- SlideController handles 3 routes: POST /slides, DELETE /slides/{slide}, PATCH /slides/{slide}/expire-date
- Image uploads processed synchronously via FileConversionService (1920×1080 JPG + 320×180 thumbnail)
- PPT uploads stored to temp location then dispatched via ConvertPowerPointJob (async)
- ZIP uploads processed recursively via processZip() — images sync, PPTs async
- Moderation & sermon slides require service_id; information slides can be global (service_id nullable)
- Extension validation done manually after Laravel validation (controller checks getClientOriginalExtension)

### Vue Components
- @jaxtheprime/vue3-dropzone v1.1.0: v-model for files, @change event when files selected, slots for placeholder-img/title/description
- CSS variables for theming: --v3-dropzone--primary, --v3-dropzone--border, etc.
- Must hide default preview with `.v3-dropzone__preview { display: none }` since we use SlideGrid
- SlideUploader emits 'uploaded' after all files processed sequentially
- SlideGrid emits 'deleted' and 'updated' for parent refresh
- Inline expire date editing: click-to-edit pattern with save/cancel buttons

### Testing
- PPTX controller test requires mocking FileConversionService since fake files aren't real PowerPoint
- Use `$this->postJson()` for validation tests expecting 422 (otherwise Laravel redirects with 302)
- Mockery mock with `app()->instance()` works for service container injection
- All 15 SlideControllerTest tests pass (37 assertions)
- Full suite: 103 tests, 488 assertions

### Design Patterns
- Amber/orange color palette matches AuthenticatedLayout nav gradient (from-amber-500 to-orange-600)
- Dropzone uses dashed border + amber gradient background for hover states
- Slide cards: rounded-xl, subtle shadow, hover lift (-translate-y-0.5), overlay controls
- Expire date color coding: red=expired, amber=expires within 7 days, emerald=active, gray=no date