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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-13 10:15:58 +01:00
parent 9a0dbe050b
commit 2d4b52adfc
15 changed files with 735 additions and 64 deletions
--- a/.paul/phases/05-tech-debt-3/05-01-PLAN.md
+++ b/.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>
--- a/.paul/phases/05-tech-debt-3/05-01-SUMMARY.md
+++ b/.paul/phases/05-tech-debt-3/05-01-SUMMARY.md
@@ -0,0 +1,103 @@
+---
+phase: 05-tech-debt-3
+plan: 01
+subsystem: core
+tags: [flash, session, php, controllers, tech-debt]
+
+requires: []
+provides:
+  - OrdersController używa Flash::set()/Flash::get() zamiast bezpośrednich $_SESSION writes
+  - ShipmentController używa Flash::set()/Flash::get() zamiast bezpośrednich $_SESSION writes
+  - Ujednolicony wzorzec flash messages w całej aplikacji
+affects: []
+
+tech-stack:
+  added: []
+  patterns:
+    - "Flash messages: zawsze Flash::set('namespace.type', ...) / Flash::get('namespace.type', ''); nigdy bezpośrednio $_SESSION"
+
+key-files:
+  created: []
+  modified:
+    - src/Modules/Orders/OrdersController.php
+    - src/Modules/Shipments/ShipmentController.php
+
+key-decisions:
+  - "Klucze flash z namespace: 'order.success'/'order.error' i 'shipment.success'/'shipment.error' — spójne z konwencją dot-notation"
+
+patterns-established:
+  - "Flash messages: Flash::set('module.type', msg) przy zapisie; Flash::get('module.type', '') przy odczycie — bez unset (Flash::get() usuwa automatycznie)"
+
+duration: ~10min
+started: 2026-03-13T00:00:00Z
+completed: 2026-03-13T00:00:00Z
+---
+
+# Phase 5 Plan 01: Flash Migration Summary
+
+**Zastąpiono 10 bezpośrednich odwołań do `$_SESSION['*_flash_*']` wywołaniami `Flash::set()`/`Flash::get()` w OrdersController i ShipmentController — cała aplikacja używa teraz jednego wzorca flash messages.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~10 min |
+| Started | 2026-03-13 |
+| Completed | 2026-03-13 |
+| Tasks | 2 completed |
+| Files modified | 2 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: OrdersController używa Flash | Pass | 4 miejsca zastąpione; import Flash dodany; zero odwołań do `$_SESSION['order_flash_*']` |
+| AC-2: ShipmentController używa Flash | Pass | 6 miejsc zastąpionych; import Flash dodany; zero odwołań do `$_SESSION['shipment_flash_*']` |
+| AC-3: Brak regresji — widoki nadal otrzymują flashSuccess/flashError | Pass | Zmienne `flashSuccess`/`flashError` nadal przekazywane do template->render() bez zmian nazw |
+
+## Accomplishments
+
+- Usunięto 10 bezpośrednich `$_SESSION` writes (4 w OrdersController, 6 w ShipmentController)
+- Dodano `use App\Core\Support\Flash` do obu kontrolerów
+- Cała aplikacja używa teraz jednego mechanizmu flash — `Flash::set()`/`Flash::get()`
+- Concern `[MEDIUM] Direct $_SESSION Writes in Controllers Instead of Flash` zamknięty
+
+## Task Commits
+
+Brak atomicznych commitów — zmiany do zacommitowania po UNIFY (w commit fazy).
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Modules/Orders/OrdersController.php` | Modified | Dodano `use Flash`; 4x `$_SESSION['order_flash_*']` → `Flash::set/get` |
+| `src/Modules/Shipments/ShipmentController.php` | Modified | Dodano `use Flash`; 6x `$_SESSION['shipment_flash_*']` → `Flash::set/get` |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Klucze `order.success`/`order.error` i `shipment.success`/`shipment.error` | Spójne z dot-notation; namespace izoluje klucze między modułami | Wzorzec do stosowania przy nowych modułach |
+
+## Deviations from Plan
+
+None — plan wykonany dokładnie według specyfikacji.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Ready:**
+- Wzorzec flash messages ujednolicony — nowi deweloperzy mają jeden wzorzec do naśladowania
+
+**Concerns:**
+- None
+
+**Blockers:**
+- None
+
+---
+*Phase: 05-tech-debt-3, Plan: 01*
+*Completed: 2026-03-13*