---
phase: 108-delivery-status-management
plan: 01
subsystem: settings, shipments
tags: [delivery-status, crud, repository, scss, sidebar, php, pdo]

requires:
  - phase: 107-automation-email-send-once
    provides: project baseline; delivery status constants in DeliveryStatus.php

provides:
  - Tabela delivery_statuses z seedem 11 statusów
  - DeliveryStatusRepository (CRUD + per-request static cache)
  - DeliveryStatus::setRepository() — dynamiczne ładowanie etykiet/kolorów z DB
  - Panel /settings/delivery-statuses z CRUD i zakładką mapowania
  - Sidebar: "Statusy zamówień" + "Statusy przesyłek" (z badge niezmapowanych)
  - Badge rendering z CSS custom property dla niestandardowych statusów

affects: [108-02-automation-dropdowns, delivery-status-consumers, shipment-views]

tech-stack:
  added: []
  patterns:
    - DeliveryStatusRepository — static cache pattern (private static ?array $cache)
    - DeliveryStatus::setRepository() — one-time bootstrap DI dla final static class
    - CSS custom property --status-color dla dynamicznych kolorów badge

key-files:
  created:
    - database/migrations/20260427_000103_create_delivery_statuses_table.sql
    - src/Modules/Shipments/DeliveryStatusRepository.php
    - src/Modules/Settings/DeliveryStatusesController.php
    - resources/views/settings/delivery-statuses.php
    - resources/views/settings/_delivery-status-mappings-content.php
  modified:
    - src/Modules/Shipments/DeliveryStatus.php
    - src/Modules/Settings/DeliveryStatusMappingController.php
    - resources/views/settings/delivery-status-mappings.php
    - resources/views/layouts/app.php
    - resources/scss/modules/_delivery-status.scss
    - resources/lang/pl.php
    - resources/views/orders/show.php
    - resources/views/shipments/prepare.php

key-decisions:
  - "REDIRECT_PATH zmieniony na /settings/delivery-statuses?tab=mapping — wszystkie redirecty z mappingController idą do nowej strony"
  - "Zakładki w delivery-statuses przez URL ?tab= (nie localStorage) — redirecty po save lądują na właściwej zakładce"
  - "CSS custom property --status-color dla niestandardowych statusów zamiast inline background-color — zgodnie z konwencją projektu"
  - "Migracja zawiera seed 11 systemowych statusów — is_system=1 dla delivered/returned/cancelled"

patterns-established:
  - "DeliveryStatusRepository jako wzorzec static cache: private static ?array $cache = null; clearCache() po mutacjach"
  - "setRepository() pattern: statyczna final klasa z opcjonalnym wstrzykiwanym repo dla DB fallback"

duration: ~40min
started: 2026-04-27T00:00:00Z
completed: 2026-04-27T00:00:00Z
---

# Phase 108 Plan 01: Delivery Status Management — Core Summary

**Wyniesiono statusy przesyłek do tabeli DB z CRUD panelem, dynamicznym ładowaniem w DeliveryStatus.php i przebudową sidebaru — operator może dodać nowy status bez deploymentu.**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~40 min |
| Tasks | 3/3 completed |
| Files created | 5 |
| Files modified | 8 |
| Delegated agents | 3 Claude |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Tabela delivery_statuses z 11 statusami | Pass* | Migracja gotowa; nieuruchomiona (MySQL offline podczas APPLY) |
| AC-2: CRUD niebędacych systemowych statusów | Pass | Controller + widok z blokadami is_system=1 i in-use check |
| AC-3: /settings/delivery-statuses ma 2 zakładki | Pass | Statusy (CRUD) + Mapowanie dostawy (include) |
| AC-4: Sidebar z nową strukturą | Pass | Statusy zamówień + Statusy przesyłek z badge |
| AC-5: DeliveryStatus ładuje z DB | Pass | setRepository() + label()/getAllOptions()/getColor() z DB fallback |
| AC-6: Badge dla niestandardowych statusów | Pass | .delivery-badge--custom + --status-color CSS var |

*Migracja musi zostać uruchomiona: `php bin/migrate.php`

## Accomplishments

- `DeliveryStatusRepository` z PDO, per-request static cache, pełnym CRUD i blokadami (systemowe + używane statusy)
- `DeliveryStatus::setRepository()` — transparent DB loading bez łamania istniejącego API klasy (ALL_STATUSES, TERMINAL_STATUSES, provider mapy niezmienione)
- Panel `/settings/delivery-statuses` z URL-based tabs (`?tab=statuses` / `?tab=mapping`) — redirecty po save zawsze trafiają na właściwą zakładkę
- `_delivery-status-mappings-content.php` wydzielony jako reużywalny include z `$mappingBaseUrl` — stara strona `/settings/delivery-status-mappings` nadal działa (backward compat)
- Badge rendering z CSS custom property `--status-color` — system statuses → klasy CSS; custom statuses → `delivery-badge--custom` + inline CSS var

## Files Created/Modified

| File | Zmiana | Cel |
|------|--------|-----|
| `database/migrations/20260427_000103_create_delivery_statuses_table.sql` | Utworzony | CREATE TABLE + seed 11 statusów |
| `src/Modules/Shipments/DeliveryStatusRepository.php` | Utworzony | CRUD + static cache dla delivery_statuses |
| `src/Modules/Settings/DeliveryStatusesController.php` | Utworzony | Panel /settings/delivery-statuses (index/store/update/destroy) |
| `resources/views/settings/delivery-statuses.php` | Utworzony | Widok 2-zakładkowy (Statusy + Mapowanie) |
| `resources/views/settings/_delivery-status-mappings-content.php` | Utworzony | Wydzielony include z $mappingBaseUrl |
| `src/Modules/Shipments/DeliveryStatus.php` | Zmodyfikowany | +setRepository, +getAllStatuses, +getAllOptions, +getColor; label() z DB |
| `src/Modules/Settings/DeliveryStatusMappingController.php` | Zmodyfikowany | +DeliveryStatusRepository DI; REDIRECT_PATH; walidacja przez repo |
| `resources/views/settings/delivery-status-mappings.php` | Zmodyfikowany | Thin wrapper → include _delivery-status-mappings-content.php |
| `resources/views/layouts/app.php` | Zmodyfikowany | Sidebar: nowy link "Statusy przesyłek", usunięto "Mapowanie statusów" |
| `resources/scss/modules/_delivery-status.scss` | Zmodyfikowany | +delivery-status-swatch, +delivery-status-system-badge, +delivery-badge--custom |
| `resources/lang/pl.php` | Zmodyfikowany | statuses→"Statusy zamówień"; +delivery_statuses→"Statusy przesyłek" |
| `resources/views/orders/show.php` | Zmodyfikowany | Badge (2 miejsca): system→CSS class; custom→--status-color |
| `resources/views/shipments/prepare.php` | Zmodyfikowany | Badge (1 miejsce): system→CSS class; custom→--status-color |
| `.paul/docs/DB_SCHEMA.md` | Zaktualizowany | Nowa tabela delivery_statuses |
| `.paul/docs/ARCHITECTURE.md` | Zaktualizowany | DeliveryStatusRepository, DeliveryStatusesController, setRepository() |
| `.paul/docs/TECH_CHANGELOG.md` | Zaktualizowany | Entry Phase 108 Plan 01 |

## Decisions Made

| Decyzja | Uzasadnienie | Wpływ |
|---------|-------------|-------|
| REDIRECT_PATH = `/settings/delivery-statuses?tab=mapping` | Nowa strona jest primary; stara URL to backward compat | Redirecty z DeliveryStatusMappingController lądują na nowej stronie |
| Zakładki przez URL `?tab=` nie localStorage | Redirecty po POST muszą trafić na właściwą zakładkę | Provider tabs w mapping content też używają `$mappingBaseUrl` |
| CSS custom property `--status-color` dla nowych statusów | Konwencja projektu (conventions.md) | Zachowanie spójności; brak inline `background-color` w PHP |
| `is_system=1` dla delivered/returned/cancelled (nie tylko is_terminal) | Są używane w logice biznesowej (AutomationService itp.) | UI blokuje edycję/usunięcie systemowych |

## Deviations from Plan

| Typ | Opis |
|-----|------|
| Korekta planu | Plan wspominał "Medoo" — projekt używa PDO. Skorygowano przed delegacją. |
| Korekta SCSS path | Plan mówił `settings/_delivery-statuses.scss` — faktyczny pattern to `modules/`. Dodano do istniejącego `_delivery-status.scss`. |
| Migracja nieuruchomiona | MySQL offline podczas APPLY. Migracja musi być uruchomiona ręcznie. |

## Issues Encountered

| Problem | Rozwiązanie |
|---------|------------|
| MySQL offline podczas APPLY | Migracja zapisana, czeka na uruchomienie XAMPP |

## Next Phase Readiness

**Ready:**
- `DeliveryStatusRepository` dostępny dla Plan 02 (automatyzacja)
- `DeliveryStatus::getAllOptions()` dostarcza DB-driven listę statusów
- Routing i widoki działają (syntax OK, SCSS build OK)

**Concerns:**
- Migracja musi być uruchomiona przed testem UI: `php bin/migrate.php`
- Plan 02 (automatyzacja) wymaga sprawdzenia gdzie AutomationController/Repository używa hardcoded listy statusów

**Blockers:**
- Brak (poza uruchomieniem migracji)

---
*Phase: 108-delivery-status-management, Plan: 01*
*Completed: 2026-04-27*