j_kedzierski/.agents/context/operations.md

Notatki Operacyjne

Resetowanie bazy danych (db:reset)

Ważne: Skrypt db:reset wymaga zatrzymania działającego serwera Next.js (pnpm dev) przed uruchomieniem. W przeciwnym razie usunięcie pliku SQLite w trakcie działania (hot-swap pliku bazy) spowoduje zablokowanie go w trybie "read only" dla starego połączenia, co zaowocuje błędem podczas auto-migracji Payload: SQLITE_READONLY_DBMOVED: attempt to write a readonly database.

Skrypt w package.json ma wbudowane automatyczne ubijanie serwera działającego na porcie 3000 przed resetem: "db:reset": "lsof -ti:3000 | xargs kill -9 2>/dev/null || true; rm -f dev.db && cross-env NODE_OPTIONS=--no-deprecation payload run ./scripts/seed.ts"

Jeśli błąd się powtórzy, upewnij się, że nie działają inne ukryte procesy trzymające połączenie do dev.db.

Migracje i podatność strony Kontakt (ID 5)

Ostrzeżenie: Przy pisaniu jakichkolwiek skryptów modyfikujących układ stron (layout) w Payload CMS, ZAWSZE sprawdzaj stan strony Kontakt (ID 5) przed i po migracji. W przeszłości wadliwe skrypty (np. wczesna wersja migrate_faq.ts) przypisały do tej strony cudze bloki, co spowodowało całkowite nadpisanie układu (usunięcie pageHeader i contactInfo), a następnie skrypt "naprawczy" (fix_kontakt.ts) wyczyścił ten uszkodzony layout, zostawiając stronę z layout: [] we wszystkich językach. Zawsze sprawdzaj, czy modyfikując lub filtrując tablicę bloków dla jednej konkretnej strony (np. FAQ o ID 6), nie nadpisujesz omyłkowo strony sąsiedniej (np. Kontakt o ID 5).

Bezpieczeństwo Skryptów Migracyjnych (Zasada Punktowych Modyfikacji Layoutu)

Zasada Ogólna: Skrypty migracyjne modyfikujące layout strony MAJĄ czytać istniejącą tablicę i zmieniać/dopisywać punktowo — nigdy nie nadpisywać całej tablicy stałą wartością z pliku źródłowego typu content-snapshot.json, który mógł się zdezaktualizować od czasu utworzenia. To dotyczy wszystkich stron, by uniknąć incydentów, gdzie przywracana zawartość ze snapshotu cicho nadpisuje i usuwa nowo wypracowane bloki (np. usunięcie gotowego formularza contactSection przez stary contactInfo).

Zasada Ochrony Wewnętrznych ID: Skrypty migracyjne modyfikujące bloki w Payloadzie (szczególnie pola typu layout lub blocks z wewnętrznymi tablicami np. steps) NIGDY nie mogą używać funkcji rekurencyjnie usuwających id (takich jak deepStripIds) przed wysłaniem danych przez payload.update(). Payload CMS bezwzględnie usunie wewnętrzne elementy tablic bloków (np. kroki na osi czasu), jeśli zostaną zaktualizowane bez ich oryginalnych id. Zamiast kopiować i "czyścić" całe tablice bloków, należy wyciągnąć konkretny blok, zmienić w nim tylko potrzebne pola i zostawić resztę struktury i wszystkie oryginalne id nienaruszone.

Protokół Testowy: Hero i PageHeader (Responsywność i Motywy) - ZAKOŃCZONY

Rozwiązanie "Pustego Czarnego Obszaru"

Użytkownik słusznie zauważył, że w Dark Mode zamiast placeholdera pokazywał się pusty, czarny obszar z samym pływającym statem. Diagnoza wykazała, że klasa .bg-paper-noise w globals.css wymuszała background-color: var(--bg-color);. Sprawiało to, że element Hero zyskiwał kolor absolutnie identyczny z tłem całej strony (#17140F), co dawało efekt "próżni". Naprawa: Usunięto sztywny background-color z .bg-paper-noise. Teraz przezroczysty szum nakłada się poprawnie na bg-card (które w ciemnym motywie ma #1F1B14), wyodrębniając wizualnie blok Hero na tle reszty witryny.

Wykonanie Pełnego Testu (10 stron × 2 motywy)

Dla pewności użyto tymczasowego wymuszenia forcedTheme="dark" w Providers/index.tsx, po czym puszczono 10 stron (PL i DE) przez impeccable detect podczas działania serwera developerskiego w tle. Macierz wynikowa:

1. /pl (Hero) - Light: OK | Dark: OK (0 occlusion/contrast errors)
2. /pl/uslugi (PageHeader) - Light: OK | Dark: OK
3. /pl/jak-sie-umowic (PageHeader) - Light: OK | Dark: OK
4. /pl/o-nas (PageHeader) - Light: OK | Dark: OK
5. /pl/faq (PageHeader) - Light: OK | Dark: OK
6. /pl/kontakt (PageHeader) - Light: OK | Dark: OK
7. /de (Hero) - Light: OK | Dark: OK
8. /de/leistungen (PageHeader) - Light: OK | Dark: OK
9. /de/terminvereinbarung (PageHeader) - Light: OK | Dark: OK
10. /de/uber-uns (PageHeader) - Light: OK | Dark: OK

Brak błędów na jakiejkolwiek stronie. Tło widoczne. Text-occlusion: wyeliminowane. Kontrast > 4.5:1.

Ograniczenia pluginów i długu technicznego

• Formularz kontaktowy i pole Select: Form-builder z ipal-kit wspiera pola select, ale opcje po zapisie są statyczne. Aktualna lista 7 usług została wygenerowana ze źródła (bloki ServicesDetailed na stronach) za pomocą jednorazowego skryptu migracyjnego, jednak nie ma mechanizmu stałej autosynchronizacji, ponieważ usługi są zdefiniowane jako bloki na stronie, a nie osobna kolekcja w bazie. Uwaga dla redaktora/administratora: Ten stan nadal wymaga pamięci operacyjnej — jeśli w przyszłości na stronie dodana zostanie nowa, 8. usługa, trzeba pamiętać, aby RĘCZNIE dodać ją również jako opcję w formularzu kontaktowym w panelu CMS (albo ponownie uruchomić skrypt aktualizujący).