feat(04-schema-docs): annotate ensure_* compensating migrations and update DB_SCHEMA.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.paul/phases/05-tech-debt-3/05-01-PLAN.md

@@ -0,0 +1,181 @@
+---
+phase: 05-tech-debt-3
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Modules/Orders/OrdersController.php
+  - src/Modules/Shipments/ShipmentController.php
+autonomous: true
+---
+
+<objective>
+## Goal
+Zastąpić bezpośrednie zapisy do `$_SESSION['order_flash_*']` i `$_SESSION['shipment_flash_*']` wywołaniami `Flash::set()` / `Flash::get()` w `OrdersController` i `ShipmentController`.
+
+## Purpose
+Ujednolicenie wzorca flash messages w całej aplikacji — obecnie `OrdersController` i `ShipmentController` omijają warstwę abstrakcji `Flash`, co tworzy dwa niekompatybilne mechanizmy. Pozostałe kontrolery (Settings) używają już `Flash::set()`/`Flash::get()`.
+
+## Output
+Dwa zmodyfikowane pliki PHP z usuniętymi bezpośrednimi odwołaniami do `$_SESSION['*_flash_*']`. Concern `[MEDIUM] Direct $_SESSION Writes` zamknięty.
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@src/Core/Support/Flash.php
+@src/Modules/Orders/OrdersController.php
+@src/Modules/Shipments/ShipmentController.php
+</context>
+
+<skills>
+## Required Skills (from SPECIAL-FLOWS.md)
+
+| Skill | Priority | When to Invoke | Loaded? |
+|-------|----------|----------------|---------|
+| sonar-scanner | required | Po APPLY, przed UNIFY | ○ |
+| /code-review | optional | Po implementacji, przed UNIFY | ○ |
+
+**BLOCKING:** `sonar-scanner` musi być uruchomiony przed UNIFY.
+
+## Skill Invocation Checklist
+- [ ] sonar-scanner uruchomiony (CLI w katalogu projektu)
+- [ ] /code-review opcjonalnie przed UNIFY
+
+</skills>
+
+<acceptance_criteria>
+
+## AC-1: OrdersController używa Flash
+```gherkin
+Given OrdersController.php nie zawiera żadnych odwołań do $_SESSION['order_flash_*']
+When przeglądamy kod OrdersController
+Then wszystkie odczyty flash używają Flash::get('order.success') i Flash::get('order.error')
+  And wszystkie zapisy flash używają Flash::set('order.success', ...) i Flash::set('order.error', ...)
+  And Flash jest zaimportowany przez use App\Core\Support\Flash
+```
+
+## AC-2: ShipmentController używa Flash
+```gherkin
+Given ShipmentController.php nie zawiera żadnych odwołań do $_SESSION['shipment_flash_*']
+When przeglądamy kod ShipmentController
+Then wszystkie odczyty flash używają Flash::get('shipment.success') i Flash::get('shipment.error')
+  And wszystkie zapisy flash używają Flash::set('shipment.success', ...) i Flash::set('shipment.error', ...)
+  And Flash jest zaimportowany przez use App\Core\Support\Flash
+```
+
+## AC-3: Brak regresji — widoki nadal otrzymują flashSuccess/flashError
+```gherkin
+Given widok orders/show.php oczekuje zmiennych $flashSuccess i $flashError
+  And widok shipments/prepare.php oczekuje zmiennych $flashSuccess i $flashError
+When kontrolery renderują widoki po migracji
+Then zmienne flashSuccess i flashError nadal są przekazywane do template->render()
+  And ich wartości pochodzą z Flash::get() zamiast z $_SESSION bezpośrednio
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Migracja flash messages w OrdersController</name>
+  <files>src/Modules/Orders/OrdersController.php</files>
+  <action>
+    1. Dodaj import `use App\Core\Support\Flash;` do sekcji use (po pozostałych use w pliku).
+
+    2. W metodzie `show()` (linie ~163–165) zastąp:
+       ```php
+       $flashSuccess = (string) ($_SESSION['order_flash_success'] ?? '');
+       $flashError = (string) ($_SESSION['order_flash_error'] ?? '');
+       unset($_SESSION['order_flash_success'], $_SESSION['order_flash_error']);
+       ```
+       przez:
+       ```php
+       $flashSuccess = (string) Flash::get('order.success', '');
+       $flashError = (string) Flash::get('order.error', '');
+       ```
+       (Flash::get() usuwa klucz automatycznie — unset zbędny)
+
+    3. W metodzie `updateStatus()` zastąp wszystkie zapisy `$_SESSION['order_flash_*']`:
+       - `$_SESSION['order_flash_error'] = ...` → `Flash::set('order.error', ...)`
+       - `$_SESSION['order_flash_success'] = ...` → `Flash::set('order.success', ...)`
+
+    Dotyczy 4 miejsc (linie ~204, ~210, ~219, ~221).
+    Nie zmieniaj nazw zmiennych przekazywanych do template->render() ('flashSuccess', 'flashError').
+  </action>
+  <verify>grep -n "_SESSION\['order_flash" src/Modules/Orders/OrdersController.php — zwraca 0 wyników</verify>
+  <done>AC-1 satisfied: brak bezpośrednich odwołań do $_SESSION['order_flash_*']</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Migracja flash messages w ShipmentController</name>
+  <files>src/Modules/Shipments/ShipmentController.php</files>
+  <action>
+    1. Dodaj import `use App\Core\Support\Flash;` do sekcji use (po pozostałych use w pliku).
+
+    2. W metodzie `prepare()` (linie ~93–95) zastąp:
+       ```php
+       $flashSuccess = (string) ($_SESSION['shipment_flash_success'] ?? '');
+       $flashError = (string) ($_SESSION['shipment_flash_error'] ?? '');
+       unset($_SESSION['shipment_flash_success'], $_SESSION['shipment_flash_error']);
+       ```
+       przez:
+       ```php
+       $flashSuccess = (string) Flash::get('shipment.success', '');
+       $flashError = (string) Flash::get('shipment.error', '');
+       ```
+
+    3. W metodach `create()` i `label()` zastąp wszystkie zapisy `$_SESSION['shipment_flash_*']`:
+       - `$_SESSION['shipment_flash_error'] = ...` → `Flash::set('shipment.error', ...)`
+       - `$_SESSION['shipment_flash_success'] = ...` → `Flash::set('shipment.success', ...)`
+
+    Dotyczy 6 miejsc (linie ~155, ~209, ~220, ~272, ~318, ~328).
+    Nie zmieniaj nazw zmiennych przekazywanych do template->render() ('flashSuccess', 'flashError').
+  </action>
+  <verify>grep -n "_SESSION\['shipment_flash" src/Modules/Shipments/ShipmentController.php — zwraca 0 wyników</verify>
+  <done>AC-2 i AC-3 satisfied: brak bezpośrednich odwołań do $_SESSION['shipment_flash_*'], zmienne flashSuccess/flashError nadal przekazywane do widoku</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- src/Core/Support/Flash.php (klasa Flash — działa poprawnie, nie modyfikować)
+- resources/views/orders/show.php (widok — oczekuje 'flashSuccess'/'flashError', nie zmieniać nazw kluczy w render())
+- resources/views/shipments/prepare.php (widok — analogicznie)
+- Żadne inne pliki poza dwoma kontrolerami
+
+## SCOPE LIMITS
+- Nie refaktoryzuj innych fragmentów kontrolerów — tylko flash messages
+- Nie zmieniaj nazw kluczy flash przekazywanych do widoków ('flashSuccess', 'flashError')
+- Nie dotykaj metody checkStatus() w ShipmentController — nie używa flash
+- Nie dodawaj nowych zależności
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] grep -rn "_SESSION\['order_flash" src/ — zero wyników
+- [ ] grep -rn "_SESSION\['shipment_flash" src/ — zero wyników
+- [ ] grep -n "use App\\Core\\Support\\Flash" src/Modules/Orders/OrdersController.php — jeden wynik
+- [ ] grep -n "use App\\Core\\Support\\Flash" src/Modules/Shipments/ShipmentController.php — jeden wynik
+- [ ] PHP lint: php -l src/Modules/Orders/OrdersController.php — No syntax errors
+- [ ] PHP lint: php -l src/Modules/Shipments/ShipmentController.php — No syntax errors
+</verification>
+
+<success_criteria>
+- Oba kontrolery używają Flash::set()/Flash::get() zamiast bezpośrednich $_SESSION writes
+- Zero odwołań do $_SESSION['order_flash_*'] i $_SESSION['shipment_flash_*'] w całej bazie kodu
+- PHP lint przechodzi bez błędów
+- Widoki nadal otrzymują flashSuccess i flashError (brak regresji w renderowaniu)
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/05-tech-debt-3/05-01-SUMMARY.md`
+</output>