# Testy, import i aktualizacje

## Import ZIP w panelu administratora

W panelu administratora, w sekcji szablonów, wybierz import ZIP. Wymagane jest uprawnienie `templates.import`. Poprawna paczka trafia do testów ze statusem `testing`; sam upload nie publikuje szablonu i nie zmienia istniejących stron klientów.

### Struktura paczki ZIP

Paczka do importu w panelu zawiera `archive.json`, źródła GS Loom w `theme/` oraz dodatkowe zasoby w `assets/`, jeśli szablon ich używa. Możesz spakować te elementy bezpośrednio w głównym katalogu ZIP-a albo umieścić je w jednym wspólnym folderze:

```text
noir-explorer/
├── archive.json
├── theme/
│   ├── loom.json
│   ├── layout/
│   ├── templates/
│   ├── sections/
│   ├── blocks/
│   ├── config/
│   └── locales/
└── assets/
    └── blog.css
```

Folder `theme/` musi zawierać kompletny, poprawny szablon, w tym `loom.json`. Powyższe drzewo ilustruje układ paczki, a nie pełną listę plików szablonu. Nie dodawaj drugiego poziomu folderów otaczających paczkę ani plików spoza jej struktury, takich jak `.DS_Store` czy `__MACOSX`.

### Co zawiera archive.json

`archive.json` opisuje format archiwum i konfigurację produktu w GrowSite. Jest osobnym plikiem obok `theme/`; nie zastępuje manifestu `theme/loom.json` ani plików schema sekcji i bloków.

Przykład dla szablonu Noir Explorer:

```json
{
  "format": "gs-loom-archive",
  "version": 1,
  "configuration": {
    "key": "noir-explorer",
    "name": "Noir Explorer",
    "version": "1.0.0",
    "tier": "basic",
    "supports_blog": true,
    "price_cents": 0,
    "default_settings": {},
    "schema": {}
  }
}
```

| Pole | Znaczenie i wymagania |
| --- | --- |
| `format` | Wymagane: `gs-loom-archive`. |
| `version` | Wersja formatu archiwum: `1`. |
| `configuration.key` | Wymagany klucz identyczny z kluczem w `theme/loom.json`: 1–40 znaków, pierwsza mała litera, dalej małe litery, cyfry lub myślniki. |
| `configuration.name` | Wymagana nazwa produktu, maksymalnie 200 znaków. |
| `configuration.version` | Wymagana wersja produktu, maksymalnie 30 znaków. Przygotowując wydanie, ustaw ją zgodnie z wersją w `loom.json`. |
| `configuration.tier` | Wymagany poziom: `basic`, `plus` albo `premium`. |
| `configuration.supports_blog` | Wymagane `true` lub `false`, zgodnie z obsługą bloga w szablonie. |
| `configuration.price_cents` | Wymagana cena w centach: liczba całkowita od `0` do `10000000`. `0` oznacza szablon bezpłatny. |
| `configuration.default_settings` | Wymagane ustawienia domyślne produktu; `{}` oznacza brak dodatkowych wartości. |
| `configuration.schema` | Opcjonalna konfiguracja schema produktu; można pominąć lub użyć `{}`. Nie zastępuje plików `.schema.json` szablonu. |

### Przygotowanie i błędy importu

Najłatwiej zacząć od [GrowSite Skeleton ZIP](/downloads/growsite-skeleton.zip), który zawiera `archive.json`. [Launch Theme ZIP](/downloads/launch-theme.zip) zawiera źródła do pracy lokalnej: przed importem przez panel trzeba przenieść zawartość katalogu szablonu do `theme/` i dodać obok prawidłowy `archive.json`.

| Komunikat | Co sprawdzić |
| --- | --- |
| `Unsupported archive path` | Sprawdź układ folderów i obecność dokładnie jednego `archive.json` w głównym katalogu paczki. Folder otaczający jest rozpoznawany na podstawie tego pliku. |
| `Configuration does not match the Loom manifest` | Ujednolić `configuration.key` i klucz w `theme/loom.json`. |
| `GS Loom validation failed` | Popraw źródła szablonu zgodnie ze szczegółami błędu kompilatora. |
| `Duplicate archive entry` | Usuń zduplikowane ścieżki, również zapisane raz z `/`, a raz z separatorem Windows. |

Limit przesyłanego ZIP-a wynosi 24 MiB. Archiwum może zawierać do 5000 wpisów, łącznie do 48 000 000 bajtów po rozpakowaniu i do 25 000 000 bajtów na plik. Dowiązania symboliczne oraz segmenty ścieżek `.` i `..` są odrzucane.

## Instalacja, sprawdzanie i aktualizacja

Uruchamiaj z głównego katalogu repozytorium:

```bash
npm run loom:import -- /absolute/path/my-theme
npm run themes:build
npm run themes:check
npm run loom:test
npm run themes:test
```

Następnie w katalogu `api`:

```bash
php artisan themes:sync --activate
```

Na końcu przebuduj panel i renderer:

```bash
npm run build:customer
npm run build:renderer
```

`--activate` aktywuje nowe produkty. Synchronizacja zachowuje ceny i status już istniejących produktów. Nie aktualizuje treści stron klientów.

Do kolejnego wydania zwiększ wersję manifestu i użyj:

```bash
npm run loom:update -- /absolute/path/my-theme
npm run themes:build
```

Aktualizacja nie może usuwać używanych definicji sekcji, bloków, szablonów stron ani identyfikatorów ustawień; typy dotychczasowych ustawień muszą pozostać zgodne. Nie jest to pełna analiza wszystkich zmian wyglądu: usunięcie warunku lub zmiana HTML nadal może zmienić prezentację zapisanej strony. Sprawdź istniejące dokumenty przed wdrożeniem.

`themes:build` przebudowuje rejestry po bezpośredniej edycji źródeł w repozytorium. Nie zastępuje kontroli kompatybilności `loom:update`.

## Kontrola przed wydaniem

Sprawdź nowe i wcześniej zapisane strony. Zweryfikuj pusty tekst, zero, wyłączony checkbox, bogaty tekst, linki, dodanie i kolejność bloków, blok statyczny, mobile i SSR. Zmiana ustawienia ma być widoczna w podglądzie i po ponownym odczycie z API.

Testy projektu:

```bash
npm run loom:test
npm run themes:test
npm run build:renderer
node --test scripts/paylio-renderer.test.mjs scripts/theme-renderer.test.mjs
```

W `api`:

```bash
php artisan test --compact --filter=loom_theme_settings
php artisan test --compact tests/Feature/LoomDocumentTest.php
```


## Najczęstsze problemy

| Komunikat lub objaw | Co sprawdzić |
| --- | --- |
| `expected one schema` | Dokładnie jeden prawidłowy blok schema w każdej sekcji i bloku |
| `Unknown setting` | Literówka w ID albo brak deklaracji pola |
| `Invalid range` | Liczbowe min/max/default i dodatni step |
| Brak bloku na liście | Targeting rodzica, prywatna nazwa, presets |
| Brak produktu w katalogu | `catalog`, `home.json`, build i synchronizacja API |
| Klucz zamiast tłumaczenia | Nazwa pliku, zagnieżdżenie klucza i defaultLocale |
| Nieaktualny rejestr | Uruchom `themes:build` i sprawdź wygenerowane zmiany |
| Nieobsługiwany plik | Podkatalog, plik binarny lub JavaScript w paczce |

Import źródeł z terminala wymaga dostępu do repozytorium. Import ZIP w panelu jest dostępny dla uprawnionych administratorów; nie jest publicznym procesem zgłoszenia do marketplace. Zachowuj wersję źródeł i artefakty wdrożenia, żeby móc przywrócić poprzednie wydanie wraz z rejestrami.