Witryna z jednego dokumentu: powtarzalny standard wdrożenia

Agencja, która wdraża strony seryjnie, prędzej czy później staje przed tym samym pytaniem: jak zapewnić powtarzalny standard wykonania, gdy każdą witrynę składa inna osoba, w innym tygodniu, pod presją terminu. Odpowiedzią jest opisanie witryny dokumentem, a nie pamięcią zespołu.

Import z dokumentu JSON to rdzeń planów Scale. Zmienia jednostkę pracy: zamiast redagować stronę, redagujesz plik, który tę stronę definiuje. Wdrożenie przestaje być rzemiosłem, a staje się procesem.

Zakres dokumentu

Jeden plik opisuje komplet: dane firmy, szablon i paletę, wszystkie podstrony, sekcje wewnątrz nich, formularze, menu oraz wersje językowe. Nie istnieje stan przechowywany gdzieś obok. Jeżeli czegoś nie ma w dokumencie, nie ma tego na stronie.

Wynikają z tego dwie konsekwencje. Po pierwsze, witrynę można odtworzyć od zera na dowolnym środowisku i w dowolnym momencie. Po drugie, import w trybie aktualizacji jest źródłem prawdy dla obszaru, który obejmuje, i tak należy go traktować w procedurach zespołu.

{
  "template": "serwis",
  "business": { "name": "EuroBarriersPro", "city": "Szczecin",
                "languages": ["pl", "en", "de", "fr"] },
  "theme": { "palette": "szmaragd" },
  "pages": [
    { "slug": "", "title": "Bariery drogowe i ogrodzenia tymczasowe",
      "sections": [
        { "type": "eq_hero", "data": { "headline": "Bariery, które wracają z każdej budowy" } },
        { "type": "eq_categories", "data": { "source": "catalog", "limit": 6 } }
      ] }
  ]
}

Powyższy fragment to nie cały kontrakt, tylko jego szkielet: pełny dokument opisuje też formularze (pola, adresy powiadomień), menu per język, ustawienia SEO każdej podstrony i, w witrynach katalogowych, kategorie z produktami. Kontrakt jest udostępniany jako zasób MCP i w dokumentacji; asystent, który go pobrał, generuje dokument przechodzący walidację zwykle za pierwszym razem.

Trzy tryby pracy

Parametr owner_user_id umieszcza witrynę bezpośrednio na koncie klienta i przepuszcza operację przez limity jego planu. Bez tego parametru import jest administracyjny, co sprawdza się przy makietach i prezentacjach ofertowych.

Wersje językowe warto zaplanować na etapie projektu, ponieważ parowanie podstron między językami powstaje podczas importu. Dołożenie języka później również działa, ale odpowiedzialność za zgodność struktury przechodzi wtedy na zespół.

Walidacja przed wdrożeniem

Parametr preview: true uruchamia próbę na sucho: sprawdzenie zgodności z kontraktem, podsumowanie podstron i kontrolę limitów planu właściciela, bez zapisu jakichkolwiek danych. Wynikiem jest albo lista tego, co powstanie, albo lista naruszeń kontraktu, punkt po punkcie.

Rekomendowany cykl wdrożeniowy:

1. przygotowanie dokumentu, ręcznie lub asystentem podłączonym przez MCP, który wcześniej pobrał kontrakt,
2. uruchomienie preview: true,
3. korekta zgłoszonych naruszeń,
4. import produkcyjny,
5. przegląd witryny i zapis dokumentu w repozytorium.

Punkt piąty odróżnia proces od jednorazowego wdrożenia. Dokument w repozytorium daje czytelny wykaz zmian, odtwarzalność oraz gotowy punkt wyjścia dla kolejnego klienta z tej samej branży.

Najczęstsze naruszenia kontraktu

Z pierwszych wdrożeń zebraliśmy krótką listę błędów, które zatrzymują preview najczęściej:

• typ sekcji spoza rodziny szablonu: sekcja katalogowa w dokumencie wizytówki albo odwrotnie; każdy szablon ma własną listę dopuszczalnych typów,
• brak strony głównej (podstrona z pustym slug) albo dwie podstrony pod tym samym adresem w jednym języku,
• język w podstronie, którego nie ma w business.languages,
• listy w polach sekcji przekazane jako tekst zamiast tablicy (punkty oferty, pozycje FAQ, produkty),
• przekroczony limit planu właściciela: liczba podstron, języków lub witryn; walidator mówi, o ile.

Każde naruszenie jest zgłaszane ze ścieżką w dokumencie (która podstrona, która sekcja, które pole), więc poprawka nie wymaga zgadywania.

Dwa kontrakty, dwa modele witryn

Witryny usługowo-katalogowe i witryny korporacyjne B2B mają odrębne kontrakty i odrębne narzędzia importu. import_site odrzuca dokument CORPOTPL, a import_corpo_site odrzuca dokument usługowy. To zabezpieczenie jakościowe: chroni przed powstaniem konstrukcji, która formalnie działa, ale nie mieści się w żadnym z modeli i generuje koszty przy każdej późniejszej zmianie.

W testach z jednego dokumentu CORPOTPL powstała kompletna witryna licząca 139 podstron w sześciu wersjach językowych, z menu przypisanym do każdego języka, formularzami i sparowanymi odpowiednikami podstron. Nie jest to szkic do dokończenia, lecz struktura gotowa do wypełnienia treścią i publikacji.

Dokument opisujący wyłącznie katalog uruchamia z kolei samodzielny mini sklep z kategoriami, kartami produktów i danymi strukturalnymi, które wyszukiwarki odczytują jako oferty handlowe.

Dokument w repozytorium: praktyka wersjonowania

Dokument jest zwykłym plikiem tekstowym, więc trzyma się go tak jak kod: jeden katalog na klienta, jeden plik na witrynę, zmiany przez pull request z opisem, tagi przy każdym imporcie produkcyjnym. Trzy nawyki, które się opłacają:

1. Nazwa pliku z datą importu w tagu, nie w nazwie: klient/witryna.json plus tag 2026-09-04-import. Historia mówi, co i kiedy poszło na produkcję.
2. Rozdzielenie treści od struktury w przeglądzie: zmiany w polach tekstowych czyta osoba od treści, zmiany w liście podstron i sekcji osoba techniczna.
3. Import z pliku z repozytorium, nigdy z kopii lokalnej, żeby produkcja zawsze odpowiadała temu, co jest w historii.

Kiedy dokument, a kiedy panel

Dokument sprawdza się tam, gdzie witryna ma powtarzalną strukturę, wiele podstron lub wiele języków, a zmiany wracają cyklicznie. Panel pozostaje właściwym narzędziem do bieżącej redakcji: pojedynczej korekty treści, wymiany zdjęcia czy publikacji wpisu.

Podział sprawdzony w praktyce: struktura i treść seryjna z dokumentu, redakcja bieżąca w panelu lub przez update_section. Dzięki temu osoby nietechniczne w zespole pracują bez ryzyka naruszenia architektury witryny.

Korzyści operacyjne

• Skrócenie wdrożenia: struktura witryny powstaje w jednej operacji, a nie w kilkudziesięciu ekranach edytora.
• Powtarzalny standard: ten sam poziom SEO, danych strukturalnych i wersji językowych na każdej stronie w portfelu.
• Biblioteka szablonów branżowych: dokument udanego wdrożenia staje się punktem wyjścia dla kolejnych klientów z tej samej branży.
• Bezpieczne przekazanie: klient odchodzący od agencji otrzymuje kompletny opis swojej witryny, a agencja zachowuje wykaz wykonanej pracy.
• Kontrola jakości przed publikacją: tryb preview przenosi wykrywanie błędów przed moment, w którym zobaczy je klient.

Proces utrzymania witryn zbudowanych w ten sposób opisujemy w osobnym materiale: zarządzanie portfelem stron.