Added protecting hooks

docs/hooks.md

@@ -0,0 +1,150 @@
+# Hooki pluginu — automatyzacja tworzenia stron
+
+Plugin dostarcza hooki, które zdejmują z projektów powtarzalną robotę. Wpinasz je
+w kolekcje; działają automatycznie. Wszystkie gotowe do użycia (import z pluginu).
+
+Powiązane: [pages.md](./pages.md), [seo.md](./seo.md), [wymagania-prawne.md](./wymagania-prawne.md).
+
+---
+
+## buildRevalidateHook — ISR odświeżany po zapisie (NAJWAŻNIEJSZY)
+
+Bez tego ISR ma haczyk: redaktor zapisuje stronę i CZEKA na revalidate (do
+godziny). Z tym — zapisuje i OD RAZU widzi zmianę. To warunek, żeby ISR był
+używalny dla CMS.
+
+```ts
+// kolekcja Pages — z pliku projektu, który MOŻE importować next/cache
+import { revalidatePath } from 'next/cache'
+import { buildRevalidateHook } from '@intecion/ipal-kit'
+import { i18nConfig } from '@/i18n.config'
+
+const { afterChange, afterDelete } = buildRevalidateHook({
+  revalidatePath,        // wstrzykiwany — plugin NIE importuje next/cache
+  config: i18nConfig,
+})
+
+export const Pages: CollectionConfig = {
+  slug: 'pages',
+  hooks: { afterChange: [afterChange], afterDelete: [afterDelete] },
+  // ...
+}
+```
+
+**Dlaczego revalidatePath wstrzykiwany:** plugin nie importuje `next/cache` (to
+by wywaliło Payload przy generate:importmap / czystym Node). Projekt podaje.
+
+Obsługuje: wszystkie języki, root (home), zmianę slug (rewaliduje stary I nowy
+path — stary URL nie serwuje starej treści), delete.
+
+---
+
+## setPublishedAtHook — auto-data publikacji
+
+Ustawia `publishedAt` na teraz przy pierwszej publikacji (jeśli puste). Redaktor
+nie wpisuje daty ręcznie; data jest dokładna dla Article JSON-LD i sitemap.
+
+```ts
+import { setPublishedAtHook } from '@intecion/ipal-kit'
+// kolekcja z draftami (blog, artykuły):
+hooks: { beforeChange: [setPublishedAtHook] }
+```
+
+Ustawia tylko przy przejściu na published; nie nadpisuje istniejącej daty
+(redaktor może backdatować ręcznie).
+
+---
+
+## buildPreventDeleteSystemPage — ochrona stron systemowych
+
+Blokuje usunięcie strony przypisanej do roli (homepage, privacyPolicy,
+cookiePolicy, termsOfService). Redaktor nie usunie przypadkiem polityki
+prywatności albo strony głównej → nie rozbije routingu i linków compliance.
+
+```ts
+import { buildPreventDeleteSystemPage } from '@intecion/ipal-kit'
+hooks: { beforeDelete: [buildPreventDeleteSystemPage({ settingsSlug: 'site-settings' })] }
+```
+
+Żeby usunąć — najpierw odłącz rolę w Site Settings (świadoma decyzja).
+
+---
+
+## buildValidateUniqueRole — jedna strona = jedna rola
+
+Zapobiega przypisaniu tej samej strony do dwóch ról systemowych (np. homepage I
+privacyPolicy naraz → niejednoznaczny routing).
+
+```ts
+import { buildValidateUniqueRole } from '@intecion/ipal-kit'
+// na polu roli w SiteSettings:
+{
+  name: 'privacyPolicy',
+  type: 'relationship',
+  relationTo: 'pages',
+  hooks: { beforeValidate: [buildValidateUniqueRole({
+    siblingFields: ['homepage', 'cookiePolicy', 'termsOfService'],
+  })] },
+}
+```
+
+---
+
+## trackSlugHistoryHook — auto-redirect 301 przy zmianie slug
+
+Gdy slug się zmienia, zapisuje STARY slug do pola `slugHistory`. Projekt czyta to
+i robi 301 ze starego URL na nowy → zmiana adresu nie daje 404 (realna strata SEO
+z audytu).
+
+```ts
+import { trackSlugHistoryHook } from '@intecion/ipal-kit'
+
+export const Pages: CollectionConfig = {
+  fields: [
+    // ...
+    { name: 'slugHistory', type: 'array', admin: { readOnly: true },
+      fields: [{ name: 'slug', type: 'text' }] },
+  ],
+  hooks: { beforeChange: [trackSlugHistoryHook] },
+}
+```
+
+Projekt w resolveRoute / sprawdzeniu redirectów: jeśli żądany slug jest w
+slugHistory jakiejś strony → 301 na jej aktualny slug. Przykład:
+
+```ts
+// w page.tsx, gdy resolveRoute nie znajdzie strony po slug:
+const byHistory = await payload.find({
+  collection: 'pages',
+  where: { 'slugHistory.slug': { equals: requestedSlug } },
+  limit: 1,
+})
+if (byHistory.docs[0]) {
+  redirect(`/${locale}/${byHistory.docs[0].slug}`)   // 301 na aktualny
+}
+```
+
+---
+
+## KOLEJNOŚĆ hooków (ważne)
+
+W jednej kolekcji hooki tej samej fazy uruchamiają się po kolei. Typowa Media:
+```ts
+hooks: {
+  beforeOperation: [normalizeFilenameHook],   // czyste nazwy
+  afterChange: [afterChange],                  // revalidate
+  afterDelete: [afterDelete],
+}
+```
+Typowa Pages:
+```ts
+hooks: {
+  beforeChange: [setPublishedAtHook, trackSlugHistoryHook],
+  beforeDelete: [buildPreventDeleteSystemPage(...)],
+  afterChange: [afterChange],    // revalidate
+  afterDelete: [afterDelete],
+}
+```
+
+Które hooki wpiąć zależy od kolekcji — nie każda potrzebuje wszystkich (blog:
+setPublishedAt; wszystkie z URL: revalidate + slugHistory; Pages: + preventDelete).