Project-Pro/shopPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ver. 0.300: Manifest-based update system with checksum verification and file backup

Browse Source 
Replaces the manual ZIP packaging workflow with an automated build script.
UpdateRepository now supports both manifest JSON format (new) and legacy
_sql.txt/_files.txt format (fallback), enabling a smooth transition for
existing client instances.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jacek Pyziak
2026-02-21 23:30:58 +01:00
parent d2e85e94df
commit b409806f02
19 changed files with 932 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
docs/UPDATE_INSTRUCTIONS.md
View File

@@ -1,136 +1,113 @@
# Instrukcja tworzenia aktualizacji shopPRO
## Struktura aktualizacji
## 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:
#### 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
#### 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 tworzenia nowej aktualizacji
### Procedura ręczna
## Status biezacej aktualizacji (ver. 0.299)
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`
- Wersja udostepniona: `0.299` (data: 2026-02-21).
**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.300)
- Wersja udostępniona: `0.300` (data: 2026-02-21).
- Pliki publikacyjne:
- `updates/0.20/ver_0.299.zip`
- `updates/0.30/ver_0.300.zip`
- Pliki metadanych aktualizacji:
- `updates/changelog.php`
- `updates/versions.php` (`$current_ver = 299`)
- Weryfikacja testow przed publikacja:
- `OK (687 tests, 1971 assertions)`
### 1. Określ numer wersji
Sprawdź ostatnią wersję w `updates/` i zwiększ o 1.
### 2. Utwórz folder tymczasowy ze strukturą w katalogu temp
```bash
mkdir -p temp/temp_XXX/sciezka/do/pliku
```
**WAŻNE:** W archiwum ZIP NIE powinno być folderu z nazwą wersji (np. ver_0.234/).
Struktura ZIP powinna zaczynać się bezpośrednio od katalogów projektu (admin/, autoload/, itp.).
### 3. Skopiuj zmienione pliki do folderu tymczasowego
```bash
cp sciezka/do/pliku.php temp/temp_XXX/sciezka/do/pliku.php
```
### 4. Utwórz plik ZIP z zawartości folderu (nie z samego folderu!)
```powershell
cd temp/temp_XXX
powershell -Command "Compress-Archive -Path '*' -DestinationPath '../ver_X.XXX.zip' -Force"
```
### 5. Usuń folder tymczasowy
```bash
rm -rf temp/temp_XXX
```
### 6. Zaktualizuj changelog.php
Dodaj wpis na początku pliku:
```html
<b>ver. X.XXX - DD.MM.YYYY</b><br />
- NEW/FIX/UPDATE - opis zmiany
<hr>
```
Prefiksy:
- `NEW` - nowa funkcjonalność
- `FIX` - naprawa błędu
- `UPDATE` - aktualizacja istniejącej funkcjonalności
### 7. Zaktualizuj versions.php
Zmień wartość `$current_ver` na nowy numer wersji (bez przedrostka 0.):
```php
$current_ver = 234; // dla wersji 0.234
```
### 8. (Opcjonalnie) Utwórz plik SQL
Jeśli aktualizacja wymaga zmian w bazie danych, utwórz plik `ver_X.XXX_sql.txt` z zapytaniami SQL.
### 9. (Opcjonalnie) Utwórz plik z listą plików do usunięcia
Jeśli aktualizacja wymaga usunięcia przestarzałych plików, utwórz plik `ver_X.XXX_files.txt`:
```
F: ../sciezka/do/pliku1.php
F: ../sciezka/do/pliku2.php
```
**UWAGA:** Pliki wymienione w tym pliku zostaną USUNIĘTE z systemu podczas aktualizacji.
## Przykład - aktualizacja 0.234
Zmienione pliki:
- `autoload/admin/controls/class.ShopOrder.php`
- `admin/templates/shop-order/order-details.php`
Opis: Dodanie przycisku do zaznaczania zamówienia jako wysłane do trustmate.io
### Komendy:
```bash
# Utwórz strukturę w folderze tymczasowym
mkdir -p temp/temp_234/autoload/admin/controls
mkdir -p temp/temp_234/admin/templates/shop-order
# Skopiuj pliki
cp autoload/admin/controls/class.ShopOrder.php temp/temp_234/autoload/admin/controls/
cp admin/templates/shop-order/order-details.php temp/temp_234/admin/templates/shop-order/
# Utwórz ZIP z ZAWARTOŚCI folderu (ważne: wejdź do folderu i spakuj '*')
cd temp/temp_234
powershell -Command "Compress-Archive -Path '*' -DestinationPath '../ver_0.234.zip' -Force"
# Wróć i usuń folder tymczasowy
cd ..
rm -rf temp_234
```
### Poprawna struktura ZIP:
```
ver_0.234.zip
├── admin/
│ └── templates/
│ └── shop-order/
│ └── order-details.php
└── autoload/
└── admin/
└── controls/
└── class.ShopOrder.php
```
### NIEPOPRAWNA struktura (do uniknięcia):
```
ver_0.234.zip
└── ver_0.234/ <-- tego folderu NIE powinno być!
├── admin/
└── autoload/
```
- `updates/versions.php` (`$current_ver = 300`)
- Weryfikacja testów przed publikacją:
- `OK (692 tests, 1988 assertions)`