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

- 2026-03-01: Fuer 1920x1080 Slide-Output ohne Upscaling funktioniert in Intervention Image v3 die Kombination aus schwarzer Canvas (`create()->fill('000000')`), `scaleDown(width: 1920, height: 1080)` und zentriertem `place(...)` stabil.
- 2026-03-01: Bei Fake-Storage in Tests muessen Zielordner vor direktem Intervention-`save()` explizit erstellt werden (`makeDirectory`/`mkdir`), sonst wirft Intervention `NotWritableException`.
- 2026-03-01: Fuer Testverifikation von Letterbox/Pillarbox sind farbige PNG-Testbilder sinnvoller als `UploadedFile::fake()->image(...)`, weil Fake-Bilder sonst komplett schwarz sein koennen.
- 2026-03-01: CTS-Sync laeuft stabil mit `EventRequest::where("from", heute)` + `EventAgendaRequest::fromEvent(...)->get()`, wenn Services per `cts_event_id` und Agenda-Songs per (`service_id`,`order`) upserted werden; CCLI-Matching bleibt strikt auf `songs.ccli_id` und setzt nur dann `song_id`/`matched_at`.
- 2026-03-01: SongController CRUD nutzt `auth:sanctum` Middleware; `actingAs()` in Tests funktioniert damit problemlos (Sanctum unterstuetzt Session-Auth in Tests).
- 2026-03-01: SQLite gibt `date`-Spalten als `YYYY-MM-DD 00:00:00` zurueck statt `YYYY-MM-DD` — Accessor muss `substr($date, 0, 10)` nutzen fuer saubere Date-Only Werte.
- 2026-03-01: `Attribute::get()` in Laravel 12 fuer berechnete Accessors statt altem `get{Name}Attribute()` Pattern. Snake_case `last_used_in_service` mapped automatisch auf `lastUsedInService()` Methode.
- 2026-03-01: Default-Gruppen (Strophe 1=#3B82F6, Refrain=#10B981, Bridge=#F59E0B) und Default-Arrangement 'Normal' werden automatisch bei Song-Erstellung via SongService erzeugt.
- 2026-03-01: `Rule::unique('songs', 'ccli_id')->ignore($songId)->whereNull('deleted_at')` stellt sicher, dass Soft-Deleted Songs die Unique-Constraint nicht blockieren.
- 2026-03-01: `bootstrap/app.php` braucht explizit `api: __DIR__.'/../routes/api.php'` in `withRouting()` — ist nicht automatisch registriert in Laravel 12.
- 2026-03-01: Service-Listenstatus laesst sich performant in einem Query aggregieren via `withCount(...)` fuer Song-Metriken plus `addSelect`-Subqueries fuer `has_sermon_slides` und datumsabhaengige `info_slides_count` (inkl. globaler `information`-Slides mit `service_id = null`).
- 2026-03-01: TranslationService line-count distribution: iterate groups (by order) → slides (by order), for each slide count lines in `text_content`, then slice that many lines from the translated text array. `array_slice` + offset tracking works cleanly.
- 2026-03-01: URL scraping is best-effort only: `Http::timeout(10)->get($url)` + `strip_tags()` + `trim()`. Return null on any failure — no exceptions bubble up. PHP 8.1+ allows `catch (\Exception)` without variable capture.
- 2026-03-01: Translation routes: `POST /api/translation/fetch-url` (preview), `POST /api/songs/{song}/translation/import` (save), `DELETE /api/songs/{song}/translation` (remove). All under `auth:sanctum` middleware.
- 2026-03-01: `removeTranslation` uses a two-step approach: collect slide IDs via `SongSlide::whereIn('song_group_id', $song->groups()->pluck('id'))` then bulk-update `text_content_translated = null`, avoiding N+1 queries.
- 2026-03-01: Der Arrangement-Konfigurator bleibt stabil bei mehrfachen Gruppeninstanzen, wenn die Sequenz mit Vue-Keys im Muster `${group.id}-${index}` gerendert und die Reihenfolge nach jedem Drag-End sofort per `router.put(..., { preserveScroll: true })` gespeichert wird.

## [2026-03-01] Wave 2 Complete — T8-T13

### T11: Arrangement Configurator
- ArrangementController: store (clone from default), clone (duplicate existing), update (reorder groups), destroy (prevent last)
- ArrangementConfigurator.vue: vue-draggable-plus with clone mode for group pills
- **CRITICAL**: Vue key for repeating groups MUST be `${group.id}-${index}` NOT just `group.id` (groups repeat in arrangements)
- Color picker integration: group_colors array in update payload, applied to SongGroup records
- Default arrangement protection: if deleting is_default=true, promote next arrangement to default
- Tests: 4 passing (17 assertions)

### T12: Song Matching Service
- SongMatchingService: autoMatch (CCLI), manualAssign, requestCreation (email), unassign
- ServiceSongController: API endpoints for /api/service-songs/{id}/assign, /request, /unassign
- Auto-match runs during CTS sync (ChurchToolsService updated to call autoMatch)
- MissingSongRequest mailable already existed from T7, reused here
- matched_at timestamp tracks when assignment occurred
- Tests: 14 passing (33 assertions)

### T13: Translation Service
- TranslationService: fetchFromUrl (HTTP + strip_tags), importTranslation (line-count distribution), removeTranslation
- TranslationController: POST /translation/fetch-url, POST /songs/{song}/translation/import, DELETE /songs/{song}/translation
- Line-count algorithm: for each slide (ordered by group.order, slide.order), take N lines from translated text where N = original slide line count
- Best-effort URL scraping: Http::timeout(10), catch all exceptions, return null on failure
- has_translation flag on Song model tracks translation state
- Tests: 18 passing (18 assertions)

### Wave 2 Summary
- All 6 tasks completed in parallel delegation
- T11 timed out during polling but work completed successfully
- Total: 103 tests passing (488 assertions)
- Vite build: ✓ successful
- Commit: d915f8c (27 files, +3951/-25 lines)

### Next: Wave 3 (T14-T19)
- Service Edit page layout + 4 blocks (Information, Moderation, Sermon, Songs)
- Song preview modal + PDF download
- All blocks integrate SlideUploader/SlideGrid from T10
- ArrangementConfigurator from T11 embedded in Songs block

## [2026-03-01] T16: Moderation Block (Service-Specific Slides)

- ModerationBlock.vue: Simple wrapper around SlideUploader + SlideGrid with `showExpireDate=false`
- Filtering: `type='moderation' AND service_id = current_service` via computed property
- SlideUploader/SlideGrid already support `showExpireDate` prop (from T10)
- Service-specific filtering ensures moderation slides from Service A don't appear in Service B
- No expire_date field anywhere in UI (unlike Information block)
- Tests: 5 passing (14 assertions) — verifies service-specific isolation
- Vite build: ✓ successful

### T17: Sermon Block (Service-Specific Slides)
- SermonBlock.vue: Identical to ModerationBlock but with `type='sermon'`
- Filters slides: `type='sermon' AND service_id = current_service`
- Uses SlideUploader with `type="sermon"`, `serviceId={current}`, `showExpireDate={false}`
- Uses SlideGrid with `showExpireDate={false}`
- Tests: 5 passing (14 assertions) — verifies service-specific filtering, type isolation, no expire_date
- Build: ✓ successful
- 2026-03-01: Songs-Block nutzt fuer unmatched CTS-Songs eine lokale Such-Eingabe plus gefiltertes Select (Titel/CCLI), danach `POST /api/service-songs/{id}/assign` und soft reload nur von `serviceSongs`.
- 2026-03-01: Arrangement-Auswahl wird ueber ein neues `arrangement-selected` Event aus dem ArrangementConfigurator nach oben gemeldet und per `PATCH /api/service-songs/{id}` als `song_arrangement_id` sofort gespeichert.
- 2026-03-01: Translation-Toggle im Songs-Block speichert direkt per `PATCH /api/service-songs/{id}` (`use_translation`) und bleibt so ohne separaten Save-Button konsistent mit dem Auto-Save-Prinzip.

## [2026-03-01] T15: Information Block (Slides + Expire Dates)

- InformationBlock.vue: Wraps SlideUploader + SlideGrid with `showExpireDate=true` and `serviceId=null` (global slides)
- Server-side filtering in ServiceController.edit(): `type='information' AND expire_date >= service.date AND (service_id IS NULL OR service_id = current)`
- Information slides are GLOBAL — not tied to a specific service, appear in all services where `expire_date >= service.date`
- The `whereNull('deleted_at')` in edit() query is redundant with SoftDeletes trait but harmless
- Slides without expire_date are excluded from information block (require scheduling)
- SlideUploader passes `serviceId=null` for information slides (they're global, not service-specific)
- ExpiringSoonCount computed: badges warn when slides expire within 3 days of service date
- Edit.vue updated: replaced placeholder for 'information' block key with actual InformationBlock component
- `router.reload({ preserveScroll: true })` used for refreshing page after slide upload/delete/update
- Tests: 7 passing (105 assertions) — covers expire date filtering, global visibility, soft-delete exclusion, type isolation, null expire_date, ordering
- Full suite: 122 tests passing (658 assertions)
- Vite build: ✓ successful


## [2026-03-01] T14: Service Edit Page Layout + Routing

### ServiceController::edit()
- Eager-loads `serviceSongs` (ordered), `serviceSongs.song`, `serviceSongs.arrangement`, `slides`
- Information slides query is complex: global (service_id=null) + service-specific, filtered by expire_date >= service.date
- Moderation/sermon slides filtered from loaded `$service->slides` collection via `->where('type', ...)`
- Service data returned as explicit array (not full model) to control frontend shape
- serviceSongs mapped to include nested song/arrangement data as null-safe arrays

### Edit.vue Page Pattern
- Uses collapsible accordion blocks (expandedBlocks ref with boolean per key)
- 4 blocks: Information, Moderation, Predigt, Songs — each with colored gradient icon, badge count, chevron toggle
- Block content area is placeholder div (T15-T18 will replace with actual components)
- Vue Transition with max-h trick for collapse animation
- `router.get(route('services.index'))` for back navigation
- German date format: `toLocaleDateString('de-DE', { weekday: 'long', day: '2-digit', month: 'long', year: 'numeric' })`

### Index.vue Integration
- "Bearbeiten" button now uses `router.get(route('services.edit', service.id))` instead of showComingSoon

### Route
- `GET /services/{service}/edit` → `services.edit` named route, uses implicit model binding
- Placed after finalize/reopen POST routes in web.php

### Test Pattern
- PHPUnit style (not Pest) in this project's ServiceControllerTest
- `$this->withoutVite()` required for Inertia page assertion tests
- `assertInertia(fn ($page) => $page->component(...)->has(...)->where(...))` for deep prop assertions
- Auth test: unauthenticated GET redirects to login route

## [2026-03-01] T19: Song Preview Modal + PDF Download

### SongPdfController
- Previous session left corrupted file: missing closing `}` for class and missing `use Illuminate\Http\Response` import
- Controller has two methods: `preview()` returns JSON (for Vue modal), `download()` returns PDF via barryvdh/laravel-dompdf
- `buildGroupsInOrder()` extracted as private helper used by both methods
- Route: `GET /songs/{song}/arrangements/{arrangement}/pdf` -> `songs.pdf`
- `abort_unless($arrangement->song_id === $song->id, 404)` prevents cross-song arrangement access

### PDF Template
- **CRITICAL**: Old-school CSS only (NO Tailwind) — DomPDF cannot render utility classes
- DejaVu Sans font (`font-family: 'DejaVu Sans', sans-serif`) handles German umlauts correctly
- `page-break-inside: avoid` on `.group-section` keeps groups together across pages
- `white-space: pre-wrap` preserves line breaks in slide text content
- Copyright footer uses `border-top` separator, `font-size: 8pt`, muted color

### SongPreviewModal.vue
- Teleport to body for z-index isolation
- Click-outside dismiss via `@click` on backdrop with `e.target === e.currentTarget` check
- Escape key listener added on mount, removed on unmount
- Groups sorted by `ag.order`, slides by `slide.order` in computed property
- Side-by-side translation display using `grid grid-cols-2 gap-4` when `useTranslation && slide.text_content_translated`
- PDF download link as `<a>` with `target="_blank"` (not router navigation)

### Tests (Pest style)
- 9 tests, 25 assertions — covers: content type, filename, groups in order, translations, copyright, 404 for wrong song, auth redirect, umlauts, empty arrangement
- DomPDF `download()` returns `Illuminate\Http\Response` with `Content-Disposition: attachment; filename=...`
- `assertHeader('Content-Type', 'application/pdf')` verifies PDF generation succeeded
- Content-Disposition header contains slugified `song.title` + `arrangement.name`