# Instrukcja tworzenia aktualizacji shopPRO

## Nowy sposób (od v0.301) — automatyczny build script

### Wymagania
- Git z tagami wersji (np. `v0.299`, `v0.300`)
- PowerShell

### Workflow

```
1. Pracuj normalnie: commit, push, commit, push...
2. Gdy wersja gotowa:
   → git tag v0.XXX
   → ./build-update.ps1 -ToTag v0.XXX -ChangelogEntry "NEW - opis"
3. Upload plików z updates/0.XX/ na serwer aktualizacji
```

### Użycie build-update.ps1

```powershell
# Podgląd zmian (bez tworzenia plików)
./build-update.ps1 -ToTag v0.301 -DryRun

# Budowanie paczki (auto-detect poprzedniego tagu)
./build-update.ps1 -ToTag v0.301 -ChangelogEntry "NEW - opis zmiany"

# Z jawnym tagiem źródłowym
./build-update.ps1 -FromTag v0.300 -ToTag v0.301 -ChangelogEntry "NEW - opis"
```

### Co robi skrypt automatycznie
1. `git diff --name-status` między tagami → listy dodanych/zmodyfikowanych/usuniętych plików
2. Filtrowanie przez `.updateignore` (pliki deweloperskie, konfiguracyjne itp.)
3. Kopiowanie plików do temp, tworzenie ZIP
4. SHA256 checksum ZIP-a
5. Generowanie `ver_X.XXX_manifest.json`
6. Generowanie legacy `_sql.txt` i `_files.txt` (okres przejściowy)
7. Aktualizacja `versions.php` i `changelog.php`
8. Cleanup

### Pliki wynikowe
- `updates/0.XX/ver_X.XXX.zip` — paczka z plikami
- `updates/0.XX/ver_X.XXX_manifest.json` — manifest z checksumem, listą zmian, SQL
- `updates/0.XX/ver_X.XXX_sql.txt` — legacy SQL (okres przejściowy)
- `updates/0.XX/ver_X.XXX_files.txt` — legacy lista plików do usunięcia (okres przejściowy)

### Migracje SQL
Pliki SQL umieszczaj w `migrations/{version}.sql` (np. `migrations/0.301.sql`).
Build script automatycznie je wczyta i umieści w manifeście + legacy `_sql.txt`.

### Format manifestu
```json
{
    "version": "0.301",
    "date": "2026-02-22",
    "checksum_zip": "sha256:abc123...",
    "files": {
        "modified": ["autoload/Domain/Order/OrderRepository.php"],
        "added": ["autoload/Domain/Order/NewHelper.php"],
        "deleted": ["autoload/shop/OldClass.php"]
    },
    "directories_deleted": [],
    "sql": ["ALTER TABLE pp_x ADD COLUMN y INT DEFAULT 0"],
    "changelog": "NEW - opis zmiany"
}
```

### .updateignore
Plik w katalogu głównym projektu, wzorce plików wykluczonych z paczek (jak `.gitignore`).

---

## Stary sposób (do v0.300) — ręczne pakowanie

### Struktura aktualizacji

Aktualizacje znajdują się w folderze `updates/0.XX/` gdzie XX oznacza dziesiątki wersji.

#### Pliki aktualizacji:
- `ver_X.XXX.zip` - paczka ZIP ze zmienionymi plikami (BEZ folderu wersji, bezpośrednio struktura katalogów)
- `ver_X.XXX_sql.txt` - opcjonalny plik z zapytaniami SQL (jeśli wymagane zmiany w bazie)
- `ver_X.XXX_files.txt` - opcjonalny plik z listą plików do **USUNIĘCIA** przy aktualizacji (format: `F: ../sciezka/do/pliku.php`)
- `changelog.php` - historia zmian
- `versions.php` - konfiguracja wersji (zmienna `$current_ver`)

#### Zasada pakowania plików
- Do paczek aktualizacji **nie dodajemy plików `*.md`** (dokumentacja jest tylko wewnętrzna/deweloperska).
- Do paczek aktualizacji **nie dodajemy `updates/changelog.php`** (to plik serwisowy po stronie repozytorium aktualizacji, nie runtime klienta).
- Do paczek aktualizacji **nie dodajemy głównego `.htaccess` z katalogu projektu** (ten plik wdrażamy osobno, poza ZIP aktualizacji).

### Procedura ręczna

1. Określ numer wersji
2. Utwórz folder tymczasowy: `mkdir -p temp/temp_XXX/sciezka/do/pliku`
3. Skopiuj zmienione pliki do folderu tymczasowego
4. Utwórz ZIP z zawartości folderu (nie z samego folderu!)
5. Usuń folder tymczasowy
6. Zaktualizuj `changelog.php` i `versions.php`
7. (Opcjonalnie) Utwórz `_sql.txt` i `_files.txt`

**WAŻNE:** W archiwum ZIP NIE powinno być folderu z nazwą wersji. Struktura ZIP zaczyna się bezpośrednio od katalogów projektu (admin/, autoload/, itp.).

## Status bieżącej aktualizacji (ver. 0.302)

- Wersja udostępniona: `0.302` (data: 2026-02-22).
- Pliki publikacyjne:
    - `updates/0.30/ver_0.302.zip`
- Pliki metadanych aktualizacji:
    - `updates/changelog.php`
    - `updates/versions.php` (`$current_ver = 302`)
- Weryfikacja testów przed publikacją:
    - `OK (730 tests, 2066 assertions)`