Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
00634028973ee205742386107d4cae8ede860682
orderPRO/.paul/phases/108-delivery-status-management/108-01-PLAN.md
Jacek Pyziak 0063402897 feat(108): delivery status management 
Phase 108 complete (v3.2 milestone):

Plan 108-01 — Delivery Status DB & CRUD:
- Tabela delivery_statuses z seedem 11 statusow systemowych
- DeliveryStatusRepository (CRUD + per-request static cache)
- DeliveryStatus::setRepository() — DB fallback dla static final class
- Panel /settings/delivery-statuses (zakladki Statusy + Mapowanie)
- Sidebar przebudowany: Statusy zamowien + Statusy przesylek

Plan 108-02 — Automation Dropdowns z DB + UI Refactor:
- Dropdowny automatyzacji ladowane z DB (warunek shipment_status + akcja update_shipment_status)
- Walidacja przez DeliveryStatus::getAllStatuses()
- Osobna podstrona formularza CRUD (delivery-status-form.php)
- Lista uproszczona: rename Terminal -> Koncowy, usunieta kolumna Typ
- BREAKING: drop backward compat dla starych grupowych kluczy automatyzacji
- Bug fix: path params w DeliveryStatusesController via \$request->input('id')

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-27 22:10:24 +02:00

327 lines
17 KiB
Markdown
Raw Blame History

---
phase: 108-delivery-status-management
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- database/migrations/20260427_000103_create_delivery_statuses_table.sql
- src/Modules/Shipments/DeliveryStatusRepository.php
- src/Modules/Shipments/DeliveryStatus.php
- src/Modules/Settings/DeliveryStatusesController.php
- src/Modules/Settings/DeliveryStatusMappingController.php
- resources/views/settings/delivery-statuses.php
- resources/views/settings/_delivery-status-mappings-content.php
- resources/views/settings/delivery-status-mappings.php
- resources/views/layouts/app.php
- resources/scss/settings/_delivery-statuses.scss
- resources/scss/app.scss
- resources/lang/pl.php
- routes/web.php
- .paul/docs/DB_SCHEMA.md
- .paul/docs/ARCHITECTURE.md
- .paul/docs/TECH_CHANGELOG.md
autonomous: true
delegation: on
---
<objective>
## Goal
Wyniesc statusy znormalizowane przesylek do tabeli DB, udostepnic CRUD w nowym panelu ustawien "Statusy przesylek" i dynamicznie ladowac statusy z DB wszedzie tam, gdzie wczesniej uzywano stalych z `DeliveryStatus.php`.
## Purpose
Dodanie nowego statusu znormalizowanego wymaga teraz zmiany kodu i deploymentu. Po tej fazie operator moze dodac wlasny status z UI bez ingerencji w kod. Statusy systemowe (delivered, returned, cancelled) pozostaja nieedytowalne.
## Output
- Tabela `delivery_statuses` z seedem 11 istniejacych statusow
- `DeliveryStatusRepository` — odczyt z DB z per-request static cache
- `DeliveryStatus.php` — laduje `ALL_STATUSES` i `LABEL_PL` z DB (fallback na stale przy bledzie)
- Nowy panel `/settings/delivery-statuses` z dwoma zakladkami: CRUD statusow + mapowanie dostawy
- Sidebar: "Statusy zamowien" (istniejaca pozycja), nowa pozycja "Statusy przesylek"
- Walidacja w `DeliveryStatusMappingController` uzywajaca danych z DB
</objective>
<context>
## Project Context
@.paul/PROJECT.md
@.paul/STATE.md
## Source Files
@src/Modules/Shipments/DeliveryStatus.php
@src/Modules/Settings/DeliveryStatusMappingController.php
@resources/views/settings/delivery-status-mappings.php
@resources/views/layouts/app.php
@resources/lang/pl.php
@routes/web.php
@.paul/docs/DB_SCHEMA.md
@.paul/docs/ARCHITECTURE.md
</context>
<skills>
## Required Skills
| Skill | Priority | When to Invoke | Loaded? |
|-------|----------|----------------|---------|
| sonar-scanner (CLI) | required | Po APPLY, przed UNIFY | o |
</skills>
<acceptance_criteria>
## AC-1: Tabela delivery_statuses istnieje i zawiera seed 11 statusow
```gherkin
Given migracja zostala uruchomiona
Then tabela delivery_statuses zawiera 11 wierszy odpowiadajacych stalym z DeliveryStatus.php
And kolumny: id, key, label_pl, color, sort_order, is_terminal, is_system, created_at
And statusy: delivered, returned, cancelled maja is_system=1, is_terminal=1
And pozostale 8 statusow maja is_system=0
```
## AC-2: CRUD niebedacych systemowymi statusami dziala z panelu
```gherkin
Given operator otwiera /settings/delivery-statuses (zakladka Statusy)
When doda nowy status z kluczem, etykieta, kolorem
Then status pojawia sie na liscie i w dropdownie mapowania statusow
When probuje edytowac status systemowy (delivered/returned/cancelled)
Then formularz jest zablokowany (readonly/disabled fields lub brak przycisku edycji)
When probuje usunac status uzyty w delivery_status_mappings lub shipment_packages
Then otrzymuje blad "Status jest uzywany, nie mozna usunac"
```
## AC-3: Strona /settings/delivery-statuses ma dwie zakladki
```gherkin
Given operator otwiera /settings/delivery-statuses
Then widzi zakladke "Statusy" (CRUD) i "Mapowanie dostawy"
And klikajac "Mapowanie dostawy" widzi te sama tresc co wczesniej na /settings/delivery-status-mappings
And /settings/delivery-status-mappings dalej dziala (backward compat dla zakładek)
```
## AC-4: Sidebar odzwierciedla nowa strukture nawigacji
```gherkin
Given operator jest w ustawieniach
Then widzi "Statusy zamowien" (link do /settings/statuses)
And widzi "Statusy przesylek" (link do /settings/delivery-statuses)
And stara pozycja "Mapowanie statusow dostawy" znika z sidebara
And badge z liczba niezmapowanych statusow widnieje przy "Statusy przesylek"
```
## AC-5: DeliveryStatus.php laduje statusy z DB
```gherkin
Given tabela delivery_statuses istnieje
When kod wywola DeliveryStatus::label($key)
Then zwraca etykiete z DB (nie hardcoded)
And kolejne wywolania w tym samym request uzywaja per-request static cache
```
## AC-6: Badge renderuje sie dla nowych statusow
```gherkin
Given status niebedacy jednym z 11 systemowych ma kolor #ff5500
When badge jest renderowany w liscie zamowien lub szczegolow przesylki
Then badge uzywa inline style="background-color: #ff5500" dla nieznanych kluczy CSS
And istniejace 11 statusow dalej korzysta z hardcoded klas CSS (.delivery-badge--delivered itp.)
```
</acceptance_criteria>
<tasks>
<task type="auto">
<name>Task 1: Migracja tabeli delivery_statuses i DeliveryStatusRepository</name>
<files>database/migrations/20260427_000103_create_delivery_statuses_table.sql, src/Modules/Shipments/DeliveryStatusRepository.php</files>
<action>
1. Utworzyc migracje `20260427_000103_create_delivery_statuses_table.sql`:
- CREATE TABLE `delivery_statuses` (
`id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
`key` VARCHAR(50) NOT NULL UNIQUE,
`label_pl` VARCHAR(100) NOT NULL,
`color` VARCHAR(7) NOT NULL DEFAULT '#6c757d',
`sort_order` TINYINT UNSIGNED NOT NULL DEFAULT 0,
`is_terminal` TINYINT(1) NOT NULL DEFAULT 0,
`is_system` TINYINT(1) NOT NULL DEFAULT 0,
`created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
- INSERT seed: wszystkie 11 statusow z DeliveryStatus.php (unknown, created, confirmed,
picked_up, in_transit, out_for_delivery, ready_for_pickup, delivered, returned,
cancelled, problem) z odpowiednimi wartosciami label_pl, color, sort_order,
is_terminal (delivered/returned/cancelled = 1), is_system (delivered/returned/cancelled = 1).
- Kolory bazujac na istniejacych klasach CSS (sprawdzic resources/scss/).
2. Utworzyc `src/Modules/Shipments/DeliveryStatusRepository.php`:
- Konstruktor przyjmuje `\Medoo\Medoo $db`
- `getAll(): array` — SELECT * FROM delivery_statuses ORDER BY sort_order ASC
z per-request static cache (prywatna static zmienna)
- `getByKey(string $key): ?array` — szuka w getAll()
- `getAllAsOptions(): array` — zwraca [key => label_pl] (do dropdownow)
- `create(array $data): int` — INSERT, zwraca id; waliduje unikalnosc key przed insertem
- `update(int $id, array $data): void` — UPDATE; blokuje is_system=1
- `delete(int $id): void` — DELETE; sprawdza czy key nie wystepuje w
delivery_status_mappings.normalized_status lub shipment_packages.delivery_status;
blokuje jesli is_system=1 lub uzywany
- `clearCache(): void` — resetuje static cache (do testow i po mutacjach)
</action>
<verify>
Uruchom migracje na lokalnej bazie. Sprawdz `SELECT COUNT(*) FROM delivery_statuses` = 11.
Sprawdz ze delivered/returned/cancelled maja is_system=1, is_terminal=1.
</verify>
<done>Dane bazodanowe gotowe; repozytorium dostepne do uzycia w pozostalych taskach.</done>
</task>
<task type="auto">
<name>Task 2: Dynamiczne ladowanie w DeliveryStatus.php + controller + widok CRUD + routing</name>
<files>src/Modules/Shipments/DeliveryStatus.php, src/Modules/Settings/DeliveryStatusesController.php, src/Modules/Settings/DeliveryStatusMappingController.php, resources/views/settings/delivery-statuses.php, resources/views/settings/_delivery-status-mappings-content.php, resources/views/settings/delivery-status-mappings.php, resources/scss/settings/_delivery-statuses.scss, resources/scss/app.scss, routes/web.php</files>
<action>
1. Zaktualizowac `DeliveryStatus.php`:
- Dodac statyczna metode `setRepository(DeliveryStatusRepository $repo): void` (called once at bootstrap)
- Zmodyfikowac `label(string $key): string` — gdy repozytorium jest wstrzykniete,
pobiera z DB przez `getByKey($key)['label_pl']`; fallback na `LABEL_PL[$key] ?? $key`
- Dodac `getAllStatuses(): array` — zwraca `DeliveryStatusRepository::getAll()` lub
fallback `ALL_STATUSES` gdy repo niedostepne
- Dodac `getAllOptions(): array` — zwraca `DeliveryStatusRepository::getAllAsOptions()` lub
fallback `LABEL_PL`
- STALE i TERMINAL_STATUSES/providerowe mapy (INPOST_MAP etc.) pozostaja hardcoded (nie
dotyczace listy statusow uzytkownika)
- Podpiac `DeliveryStatusRepository` w bootstrapie (app.php lub DI kontener projektu —
sprawdzic jak inne repozytoria sa inicjalizowane i powtorzyc ten sam wzorzec)
2. Zaktualizowac `DeliveryStatusMappingController`:
- Wstrzyknac `DeliveryStatusRepository` przez konstruktor
- W `save()` i `saveBulk()` — walidacja normalizedStatus przez
`$this->deliveryStatusRepository->getByKey($normalizedStatus) !== null`
zamiast `in_array($normalizedStatus, DeliveryStatus::ALL_STATUSES)`
- Zaktualizowac `REDIRECT_PATH` z `/settings/delivery-status-mappings`
na `/settings/delivery-statuses?tab=mapping`
- Zachowac parametr `?provider=` przy redirectach gdzie byl
3. Wydzielic zawartosc widoku mapowania do include'a:
- Przeniesc zawartosc `resources/views/settings/delivery-status-mappings.php` do
`resources/views/settings/_delivery-status-mappings-content.php`
- W `delivery-status-mappings.php` uzywac `include '_delivery-status-mappings-content.php'`
(zachowanie backward compat)
4. Utworzyc `DeliveryStatusesController.php` w `src/Modules/Settings/`:
- `index()` — laduje statusy z DeliveryStatusRepository, renderuje delivery-statuses.php;
przekazuje `$tab = $_GET['tab'] ?? 'statuses'` i dane mapowania gdy tab=mapping
- `store()` — POST create nowego statusu; waliduje key (lowercase, underscored), label_pl,
color (#hex); zapisuje przez repozytorium; redirect z Flash
- `update(int $id)` — POST edit; blokuje is_system=1; redirect z Flash
- `destroy(int $id)` — POST delete; blokuje is_system=1 i uzywane; redirect z Flash
- Każda akcja mutujaca: walidacja CSRF `_token`, potem `DeliveryStatusRepository::clearCache()`
5. Utworzyc widok `resources/views/settings/delivery-statuses.php`:
- Dwie zakladki: "Statusy" i "Mapowanie dostawy"
- Persystencja aktywnej zakladki przez `?tab=` param (nie localStorage — zeby linki
z sidebara "Statusy przesylek" i redirect po save trafialy w dobra zakladke)
- Zakladka "Statusy":
* Tabela statusow: kolor (swatchek), klucz, etykieta, sort_order, is_terminal,
akcje (edycja/usun dla nie-systemowych; informacja "systemowy" dla systemowych)
* Formularz dodawania nowego statusu (inline pod tabela lub modal)
* Formularz edycji (inline row edit lub osobny formularz)
* Potwierdzenie usuwania: `window.OrderProAlerts.confirm()`
* Formularz dodawania: pola key (slug, lowercase, max 50), label_pl, color (input type=color),
sort_order (number), is_terminal (checkbox)
- Zakladka "Mapowanie dostawy":
* include '_delivery-status-mappings-content.php'
6. Dodac styl `resources/scss/settings/_delivery-statuses.scss`:
- `.delivery-status-swatch` — maly kwadrat koloru (16x16px inline-block)
- `.delivery-status-system-badge` — np. szary badge "systemowy"
- Dodac `@use 'settings/delivery-statuses'` do `app.scss`
7. Dodac trasy w `routes/web.php`:
- GET `/settings/delivery-statuses` → `DeliveryStatusesController::index`
- POST `/settings/delivery-statuses` → `DeliveryStatusesController::store`
- POST `/settings/delivery-statuses/{id}/update` → `DeliveryStatusesController::update`
- POST `/settings/delivery-statuses/{id}/delete` → `DeliveryStatusesController::destroy`
</action>
<verify>
- GET /settings/delivery-statuses zwraca 200, widac zakladki
- Dodanie nowego statusu przez CRUD pojawia sie na liscie
- Proba edycji/usuniecia statusu systemowego jest blokowana (HTTP 400 lub redirect z bledem)
- GET /settings/delivery-status-mappings dalej dziala (backward compat)
- redirect po save mapowania idzie do /settings/delivery-statuses?tab=mapping
</verify>
<done>AC-2, AC-3, AC-5 spelnione.</done>
</task>
<task type="auto">
<name>Task 3: Sidebar, jezyk, badge rendering i dokumentacja</name>
<files>resources/views/layouts/app.php, resources/lang/pl.php, resources/views/orders/show.php, resources/views/shipments/prepare.php, .paul/docs/DB_SCHEMA.md, .paul/docs/ARCHITECTURE.md, .paul/docs/TECH_CHANGELOG.md</files>
<action>
1. Zaktualizowac `resources/lang/pl.php`:
- `navigation.statuses` → 'Statusy zamowien'
- Dodac `navigation.delivery_statuses` => 'Statusy przesylek'
2. Zaktualizowac sidebar `resources/views/layouts/app.php`:
- Zmieniac istniejaca pozycje "Statusy" (href=/settings/statuses) tylko etykiete na
$t('navigation.statuses') (juz uzywana, ale tresc sie zmieni po kroku 1)
- Podmiana calego bloku sidebar z "Mapowanie statusow dostawy" (linie ~130-147):
* Nowy link "Statusy przesylek" href=/settings/delivery-statuses
* active gdy $currentSettings === 'delivery-statuses'
LUB $currentSettings === 'delivery-status-mappings' (backward compat)
* Badge z liczba niezmapowanych (zachowac istniejaca logike z DeliveryStatusMappingRepository)
3. Zaktualizowac badge rendering:
- W `resources/views/orders/show.php` i `resources/views/shipments/prepare.php`:
Aktualny wzorzec:
`<span class="delivery-badge delivery-badge--<?= $e($pkgDeliveryStatus) ?>">`
Zmienic na helper lub inline logike:
- Jesli `$pkgDeliveryStatus` jest jednym z 11 stalych — uzyj klasy CSS jak dotychczas
- W przeciwnym razie: pobierz kolor z DeliveryStatus::getByKey() i dodaj
`style="background-color: <?= $e($color) ?>"`
Wzorzec do uzycia (zdefiniowac helper w DeliveryStatus lub inline w widoku):
```php
$statusColor = DeliveryStatus::getColor($pkgDeliveryStatus);
$isSystemStatus = in_array($pkgDeliveryStatus, DeliveryStatus::ALL_STATUSES);
$badgeClass = 'delivery-badge' . ($isSystemStatus ? ' delivery-badge--' . $pkgDeliveryStatus : '');
$badgeStyle = $isSystemStatus ? '' : 'background-color: ' . $statusColor . ';';
```
`<span class="<?= $e($badgeClass) ?>" <?= $badgeStyle ? 'style="' . $e($badgeStyle) . '"' : '' ?>>`
- Dodac do `DeliveryStatus.php` metode `getColor(string $key): string` — pobiera kolor z
repozytorium lub zwraca '#6c757d' jako fallback
4. Zaktualizowac `.paul/docs/DB_SCHEMA.md` (nowa tabela delivery_statuses)
5. Zaktualizowac `.paul/docs/ARCHITECTURE.md` (DeliveryStatusRepository, DeliveryStatusesController)
6. Zaktualizowac `.paul/docs/TECH_CHANGELOG.md` (entry dla Phase 108 Plan 01)
</action>
<verify>
- Sidebar pokazuje "Statusy zamowien" i "Statusy przesylek", brak "Mapowanie statusow dostawy"
- Badge dla istniejacych 11 statusow renderuje sie klasa CSS jak wczesniej
- Badge dla nowego custom statusu renderuje sie z inline style
- Na stronie zamowien i przesylki brak bledow PHP
</verify>
<done>AC-4, AC-6 spelnione; dokumentacja aktualna.</done>
</task>
</tasks>
<boundaries>
## DO NOT CHANGE
- Logika eventow automatyzacji, reguł i akcji niezwiazana z lista statusow
- Provider mapy (INPOST_MAP, APACZKA_MAP, ALLEGRO_MAP) — pozostaja hardcoded compile-time
- TERMINAL_STATUSES — stala pozostaje w kodzie dla logiki biznesowej; DB `is_terminal` jest dodatkowa informacja dla UI
- Runtime konfiguracji DB hostow (`DB_HOST` / `DB_HOST_REMOTE`)
- Istniejace CSS klasy `.delivery-badge--{status}` dla 11 systemowych statusow
## SCOPE LIMITS
- Brak zmian w logice normalizacji statusow dostawcow (normalize(), normalizeWithOverrides())
- Brak zmian w cronie ani harmonogramie
- Automatyzacje — dropdown statusow aktualizowany w Plan 02 (nie w tym planie)
</boundaries>
<verification>
Before declaring plan complete:
- [ ] `SELECT COUNT(*) FROM delivery_statuses` = 11
- [ ] GET /settings/delivery-statuses zwraca 200 z dwoma zakladkami
- [ ] Dodanie nowego statusu przez CRUD jest widoczne na liscie
- [ ] Statusy systemowe sa zablokowane przed edycja i usunieciem
- [ ] GET /settings/delivery-status-mappings nadal dziala (200)
- [ ] Redirect po save mapowania idzie do /settings/delivery-statuses?tab=mapping
- [ ] Sidebar pokazuje "Statusy zamowien" i "Statusy przesylek"
- [ ] Badge istniejacych statusow bez regresji
- [ ] Badge nowego custom statusu renderuje sie z inline style
- [ ] Dokumentacja .paul/docs/* zaktualizowana
</verification>
<success_criteria>
- Operator moze dodac nowy status znormalizowany z panelu bez deploymentu
- Status systemowy (delivered/returned/cancelled) jest nieedytowalny z UI
- Strona /settings/delivery-statuses ma dwie dzialajace zakladki
- Sidebar jest uporzadkowany zgodnie z nowa struktura
- Brak regresji w istniejacym wyswietlaniu odznaczen statusow
</success_criteria>
<output>
After completion, create `.paul/phases/108-delivery-status-management/108-01-SUMMARY.md`
</output>
Reference in New Issue View Git Blame Copy Permalink