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

feat(134): backlog reality check

Browse Source 
Phase 134 complete:

- audit todo.md and concerns.md against current code/docs

- classify active, implemented, stale and decision-dependent backlog items

- route confirmed work to phases 135-142

Verification:

- git diff --check

- no runtime files changed

- sonar-scanner gap documented
This commit is contained in:
Jacek Pyziak
2026-05-16 20:42:53 +02:00
parent 0c1246b522
commit 53f01c392c
9 changed files with 671 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.paul/PROJECT.md
View File

@@ -12,9 +12,9 @@ Sprzedawca może obsługiwać zamówienia ze wszystkich kanałów
| Attribute | Value | | Attribute | Value |
|-----------|-------| |-----------|-------|
| Version | 3.8.0-dev | | Version | 3.9.0-dev |
| Status | v3.8 Erli Marketplace Integration complete in code - Phases 127-133 shipped; live Erli smoke/migrations remain operator follow-up | | Status | v3.9 Stabilizacja i splata dlugu technicznego in progress - Phase 134 backlog reality check complete; Phase 135 ready to plan |
| Last Updated | 2026-05-16 (Phase 133 closed) | | Last Updated | 2026-05-16 (Phase 134 closed) |
## Requirements ## Requirements
@@ -133,6 +133,7 @@ Sprzedawca może obsługiwać zamówienia ze wszystkich kanałów
- [x] Tracking i automatyzacje Erli: lokalny provider tracking jak w Allegro, retry niekrytycznej rejestracji paczki zewnetrznej Erli z `shipment_tracking_sync`, wspolny kontekst `shipment.created`/`shipment.status_changed` dla regul e-mail/SMS/statystyk — Phase 131 - [x] Tracking i automatyzacje Erli: lokalny provider tracking jak w Allegro, retry niekrytycznej rejestracji paczki zewnetrznej Erli z `shipment_tracking_sync`, wspolny kontekst `shipment.created`/`shipment.status_changed` dla regul e-mail/SMS/statystyk — Phase 131
- [x] Hardening Erli: spojna diagnostyka importu/ACK w `integration_order_sync_state.last_error`, brak ACK po blednym batchu, testy jednostkowe import/status sync i dokumentacja obserwowalnosci bez nowej migracji — Phase 132 - [x] Hardening Erli: spojna diagnostyka importu/ACK w `integration_order_sync_state.last_error`, brak ACK po blednym batchu, testy jednostkowe import/status sync i dokumentacja obserwowalnosci bez nowej migracji — Phase 132
- [x] Parytet Erli w powierzchniach wspolnych: filtr zrodla zamowien, kanaly statystyk dziennych/podsumowania, warunek integracji automatyzacji, menu integracji i etykiety `zrodlo` uzywaja wspolnego rejestru zrodel — Phase 133 - [x] Parytet Erli w powierzchniach wspolnych: filtr zrodla zamowien, kanaly statystyk dziennych/podsumowania, warunek integracji automatyzacji, menu integracji i etykiety `zrodlo` uzywaja wspolnego rejestru zrodel — Phase 133
- [x] Backlog Reality Check: `.paul/codebase/todo.md` i `.paul/codebase/concerns.md` sklasyfikowane przeciw aktualnemu kodowi/docs, z dowodami w `BACKLOG-AUDIT.md` i routingiem do faz 135-142 — Phase 134
- [x] Integracja polkurier.pl (fundament): pojedyncza globalna konfiguracja w `/settings/integrations/polkurier`, szyfrowany Token API + login, karta w hubie integracji obok Apaczki i realny test polaczenia przez `apimetod=test_auth_api` zweryfikowany na zywym koncie operatora; `ShipmentProviderRegistry` netkniety — `PolkurierShipmentService/TrackingService` w kolejnych fazach — Phase 127 - [x] Integracja polkurier.pl (fundament): pojedyncza globalna konfiguracja w `/settings/integrations/polkurier`, szyfrowany Token API + login, karta w hubie integracji obok Apaczki i realny test polaczenia przez `apimetod=test_auth_api` zweryfikowany na zywym koncie operatora; `ShipmentProviderRegistry` netkniety — `PolkurierShipmentService/TrackingService` w kolejnych fazach — Phase 127
- [x] polkurier ShipmentService + TrackingService + UI prepare panel: pelen kontrakt API (createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers), `PolkurierShipmentService` implementujacy `ShipmentProviderInterface` z normalizacja shipmenttype (lowercase) i splitem ulicy na street/housenumber/flatnumber, `PolkurierTrackingService` mapujacy statusy O/P/A/WP/D/Z/W na znormalizowane, panel "polkurier" w `prepare.php` z dynamiczna lista uslug z `available_carriers`, seed migracja `delivery_status_mappings(provider='polkurier')` z 7 wpisami z PDF v1.11; live test na #114/#115 zakonczony sukcesem po 4 iteracjach (ReferenceError → uppercase shipmenttype → orderno parsing → A4/A6); rozmiar etykiety sterowany w panelu klienta polkurier.pl (Ustawienia konta → Preferencje etykiet), NIE przez API — Phase 128 - [x] polkurier ShipmentService + TrackingService + UI prepare panel: pelen kontrakt API (createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers), `PolkurierShipmentService` implementujacy `ShipmentProviderInterface` z normalizacja shipmenttype (lowercase) i splitem ulicy na street/housenumber/flatnumber, `PolkurierTrackingService` mapujacy statusy O/P/A/WP/D/Z/W na znormalizowane, panel "polkurier" w `prepare.php` z dynamiczna lista uslug z `available_carriers`, seed migracja `delivery_status_mappings(provider='polkurier')` z 7 wpisami z PDF v1.11; live test na #114/#115 zakonczony sukcesem po 4 iteracjach (ReferenceError → uppercase shipmenttype → orderno parsing → A4/A6); rozmiar etykiety sterowany w panelu klienta polkurier.pl (Ustawienia konta → Preferencje etykiet), NIE przez API — Phase 128
- [x] Order User Notes module (Phase 129): pelen CRUD notatek autorskich operatora per zamowienie. Reuse `order_notes` przez nowy `note_type='user'` z `user_id` (FK→users SET NULL) + `author_name` (snapshot) + indeks `idx_order_notes_type_order`. `OrderNotesService` z autoryzacja DB-level (`WHERE user_id = :user_id`, rowCount=0 ⇒ 403). Sekcja `#notes` w "Wiadomosci i zalaczniki" w `/orders/{id}` z inline edit form + delete przez `OrderProAlerts.confirm`. Badge `[N]` (indigo neutralny) przy nr zamowienia na `/orders/list` (subquery `user_notes_count` w paginate). Brak admin override (brak systemu rol w aplikacji) — edit/delete tylko dla autora — Phase 129 - [x] Order User Notes module (Phase 129): pelen CRUD notatek autorskich operatora per zamowienie. Reuse `order_notes` przez nowy `note_type='user'` z `user_id` (FK→users SET NULL) + `author_name` (snapshot) + indeks `idx_order_notes_type_order`. `OrderNotesService` z autoryzacja DB-level (`WHERE user_id = :user_id`, rowCount=0 ⇒ 403). Sekcja `#notes` w "Wiadomosci i zalaczniki" w `/orders/{id}` z inline edit form + delete przez `OrderProAlerts.confirm`. Badge `[N]` (indigo neutralny) przy nr zamowienia na `/orders/list` (subquery `user_notes_count` w paginate). Brak admin override (brak systemu rol w aplikacji) — edit/delete tylko dla autora — Phase 129
@@ -145,7 +146,7 @@ Sprzedawca może obsługiwać zamówienia ze wszystkich kanałów
### Active (In Progress) ### Active (In Progress)
- [ ] Next milestone selection pending after v3.8 Erli closure. - [ ] v3.9 Stabilizacja i splata dlugu technicznego — Phase 135 Accounting Net Correctness ready to plan after Phase 134 audit.
### Planned (Next) ### Planned (Next)
@@ -261,6 +262,7 @@ PHP (XAMPP/Laravel), integracje z API marketplace'Ăłw (Allegro, Erli) oraz API
| `carrier_delivery_method_mappings` przechowuje `source_vendor_code`/`source_service_id` dla Erli | Vendor Erli i lokalny provider to osobne kontrakty, nie nalezy ich mieszac w polach Apaczki/InPost | 2026-05-16 | Active | | `carrier_delivery_method_mappings` przechowuje `source_vendor_code`/`source_service_id` dla Erli | Vendor Erli i lokalny provider to osobne kontrakty, nie nalezy ich mieszac w polach Apaczki/InPost | 2026-05-16 | Active |
| Erli hardening uzywa istniejacych powierzchni obserwowalnosci zamiast nowej tabeli logow | Operator wybral ujednolicenie istniejacych miejsc; `integration_order_sync_state.last_error`, wynik crona i activity log wystarczaja dla Phase 132 | 2026-05-16 | Active | | Erli hardening uzywa istniejacych powierzchni obserwowalnosci zamiast nowej tabeli logow | Operator wybral ujednolicenie istniejacych miejsc; `integration_order_sync_state.last_error`, wynik crona i activity log wystarczaja dla Phase 132 | 2026-05-16 | Active |
| Zrodla zamowien marketplace maja wspolny `OrderSourceRegistry` | Parytet Erli ma byc utrzymany wszedzie tam, gdzie kod potrzebuje listy lub etykiety zrodla; lokalne pary Allegro/shopPRO prowadzily do pominiec Erli | 2026-05-16 | Active | | Zrodla zamowien marketplace maja wspolny `OrderSourceRegistry` | Parytet Erli ma byc utrzymany wszedzie tam, gdzie kod potrzebuje listy lub etykiety zrodla; lokalne pary Allegro/shopPRO prowadzily do pominiec Erli | 2026-05-16 | Active |
| v3.9 debt phases start from evidence-backed backlog audit | Phase 134 rozdzielil wpisy aktywne, wdrozone, stale i decyzyjne; kolejne fazy 135-142 maja naprawiac tylko potwierdzone problemy | 2026-05-16 | Active |
| polkurier startuje jako jedna globalna konfiguracja (single-instance, mirror Apaczka/HostedSMS/SMSPLANET) z realnym testowym wywolaniem `apimetod=test_auth_api` | Operator ma jedno konto polkurier; fundament musi byc zweryfikowany na zywym API zanim dolozymy `PolkurierShipmentService` | 2026-05-14 | Active | | polkurier startuje jako jedna globalna konfiguracja (single-instance, mirror Apaczka/HostedSMS/SMSPLANET) z realnym testowym wywolaniem `apimetod=test_auth_api` | Operator ma jedno konto polkurier; fundament musi byc zweryfikowany na zywym API zanim dolozymy `PolkurierShipmentService` | 2026-05-14 | Active |
| polkurier wymaga `login + token` razem w body `authorization` (nie samego tokena) | Zweryfikowane w SDK polkurier-sdk (`Auth.php`/`Request.php`); kolumna `login VARCHAR(190)` w `polkurier_integration_settings` mimo ze PLAN tego nie wymagal — kontrakt API to dyktuje | 2026-05-14 | Active | | polkurier wymaga `login + token` razem w body `authorization` (nie samego tokena) | Zweryfikowane w SDK polkurier-sdk (`Auth.php`/`Request.php`); kolumna `login VARCHAR(190)` w `polkurier_integration_settings` mimo ze PLAN tego nie wymagal — kontrakt API to dyktuje | 2026-05-14 | Active |
| polkurier API: top-level `status` === `'success'` (nie `'ok'`), tresc bledu w polu `response` envelope'a | `ResponseStatus::SUCCESS = 'success'` z `src/Type/ResponseStatus.php` SDK; bledy rzucane przez `ErrorException($response->get('response'))` w `PolkurierWebService.php`. Pattern dla wszystkich przyszlych metod polkurier API (`createShipment`, `getLabel`, `getStatus`, `cancelOrder`, etc.) | 2026-05-14 | Active | | polkurier API: top-level `status` === `'success'` (nie `'ok'`), tresc bledu w polu `response` envelope'a | `ResponseStatus::SUCCESS = 'success'` z `src/Type/ResponseStatus.php` SDK; bledy rzucane przez `ErrorException($response->get('response'))` w `PolkurierWebService.php`. Pattern dla wszystkich przyszlych metod polkurier API (`createShipment`, `getLabel`, `getStatus`, `cancelOrder`, etc.) | 2026-05-14 | Active |
@@ -308,6 +310,6 @@ Quick Reference:
--- ---
*PROJECT.md — Updated when requirements or context change* *PROJECT.md — Updated when requirements or context change*
*Last updated: 2026-05-16 after Phase 133 (Erli Cross-Surface Parity) closure; v3.8 milestone complete in code* *Last updated: 2026-05-16 after Phase 134 (Backlog Reality Check) closure*

71
.paul/ROADMAP.md
View File

@@ -6,6 +6,73 @@ orderPRO to narzedzie do wielokanalowego zarzadzania sprzedaza. Projekt przechod
## Current Milestone ## Current Milestone
v3.9 Stabilizacja i splata dlugu technicznego
Milestone porzadkujacy zbudowany z `.paul/codebase/todo.md` i `.paul/codebase/concerns.md`: poprawa znanych bugow, weryfikacja stalych ryzyk, domkniecie security/performance oraz ograniczenie dlugu technicznego, ktory utrudnia kolejne wdrozenia.
Rule for every phase/plan: przed implementacja sprawdzic w kodzie i dokumentacji, czy wpis nadal jest aktualny i czy nie zostal juz wdrozony; nastepnie przedstawic krotki plan operatorowi i zapytac o potwierdzenie. Dopiero po akceptacji wolno wprowadzac zmiany i uruchamiac testy. Jezeli wpis jest nieaktualny albo juz zrealizowany, faza/planu ma zamknac go dokumentacyjnie bez niepotrzebnej zmiany kodu.
Progress: 1 of 9 phases complete (11%).
| Phase | Name | Plans | Status |
|-------|------|-------|--------|
| 134 | Backlog Reality Check | 1/1 | Complete (2026-05-16; documentation-only audit, Sonar CLI gap documented) |
| 135 | Accounting Net Correctness | TBD | Ready to plan |
| 136 | Fakturownia Invoice Idempotency | TBD | Not started |
| 137 | Delivery Status Backlog Verification | TBD | Not started |
| 138 | Security and Legacy Hardening | TBD | Not started |
| 139 | Sonar Critical/Major Cleanup | TBD | Not started |
| 140 | Performance Safeguards | TBD | Not started |
| 141 | God Classes and Duplication Refactor | TBD | Not started |
| 142 | Architecture Guardrails | TBD | Not started |
### Phase 134: Backlog Reality Check
Focus: Zweryfikowac wszystkie wpisy z `.paul/codebase/todo.md` i `.paul/codebase/concerns.md` przeciw aktualnemu kodowi oraz dokumentacji. Dla kazdego wpisu oznaczyc: nadal aktywne, juz wdrozone, nieaktualne albo wymaga decyzji operatora. Wynik ma stac sie wejsciem do planow kolejnych faz.
Plans: 134-01 (complete; `.paul/phases/134-backlog-reality-check/134-01-SUMMARY.md`)
### Phase 135: Accounting Net Correctness
Focus: Poprawic znane rozbieznosci kwot netto: `RECEIPT-NET-FIX` dla `receipts.total_net` oraz `STAT-NET` dla statystyk zamowien bez stalego zalozenia 23% VAT. Zakres obejmuje ustalenie zrodla prawdy, ewentualny backfill i testy eksportow/statystyk.
Plans: TBD (defined during $paul-plan)
### Phase 136: Fakturownia Invoice Idempotency
Focus: Domknac `INVOICE-IDEMP-115`: zabezpieczyc delegowane wystawianie faktur przed podwojnym POST do Fakturowni po timeoutach lub utracie odpowiedzi, z weryfikacja mozliwosci `Idempotency-Key` albo deduplikacji po referencji.
Plans: TBD (defined during $paul-plan)
### Phase 137: Delivery Status Backlog Verification
Focus: Zweryfikowac wpis `DELIVERY-STATUS-MGMT` z todo oraz breaking changes po Phase 108: statusy DB-driven, stare klucze grup statusow, usuniecie `SHIPMENT_STATUS_OPTION_MAP` i realny wplyw na reguly automatyzacji. Jezeli funkcjonalnosc jest juz wdrozona, zamknac/oczyscic backlog i zostawic tylko potwierdzone luki.
Plans: TBD (defined during $paul-plan)
### Phase 138: Security and Legacy Hardening
Focus: Sprawdzic i naprawic po potwierdzeniu: szyfrowanie `print_api_keys.api_key`, `fsockopen('ssl://...')` w tescie skrzynki e-mail, injection przez zmienne szablonow, brakujacy import `RuntimeException`, stare `require` w widokach, raw `$_SESSION` i pozostale legacy patterns wskazane w concerns.
Plans: TBD (defined during $paul-plan)
### Phase 139: Sonar Critical/Major Cleanup
Focus: Zmniejszyc potwierdzone problemy SonarQube z `concerns.md`: generic exceptions, zbyt wiele returnow, powtarzajace sie literaly, cognitive complexity, unused parameters, use-namespace-import oraz accessibility (`aria-label`, `<output>`). Przed kazda grupa zmian odswiezyc stan skanu albo lokalnie potwierdzic wystepowanie problemu.
Plans: TBD (defined during $paul-plan)
### Phase 140: Performance Safeguards
Focus: Zweryfikowac i wdrozyc potwierdzone zabezpieczenia wydajnosciowe: deferred indexes `INDEX-106-01`, potencjalne N+1 w szczegolach zamowienia oraz ryzyko wzrostu kolejki cron bez backoffu. Indeksy i migracje wykonywac zgodnie z obecnym progiem danych i po potwierdzeniu operatora.
Plans: TBD (defined during $paul-plan)
### Phase 141: God Classes and Duplication Refactor
Focus: Wrocic do odlozonego Phase 68 i potwierdzonych `S1448`: `OrdersRepository`, `OrdersController`, `AutomationService`, `ShopproOrderMapper`, `ApaczkaShipmentService`, `ShopproIntegrationsController`, plus duplikacje `SslCertificateResolver`, `ToggleableRepositoryTrait`, `RedirectPathResolver` oraz overlap `ReceiptService`/accounting.
Plans: TBD (defined during $paul-plan)
### Phase 142: Architecture Guardrails
Focus: Po pilniejszych poprawkach zdecydowac, ktore guardraile sa warte wdrozenia teraz: interfejsy repozytoriow do testow, typowane event/action names, wspolna warstwa walidacji, ewentualne naglowki cache i lokalne query caching. Kazdy element wymaga osobnej decyzji, bo czesc ma niski impact.
Plans: TBD (defined during $paul-plan)
## Previous Milestone
v3.8 Erli Marketplace Integration - Complete in code v3.8 Erli Marketplace Integration - Complete in code
Pelna integracja z erli.pl wzorowana na istniejacej integracji Allegro: konfiguracja konta/API, pobieranie zamowien, mapowanie i synchronizacja statusow, generowanie etykiet, tracking oraz wlaczenie Erli w istniejace przeplywy automatyzacji, statystyk i obslugi zamowien. Pelna integracja z erli.pl wzorowana na istniejacej integracji Allegro: konfiguracja konta/API, pobieranie zamowien, mapowanie i synchronizacja statusow, generowanie etykiet, tracking oraz wlaczenie Erli w istniejace przeplywy automatyzacji, statystyk i obslugi zamowien.
@@ -57,7 +124,7 @@ Plans: 132-01 (complete)
Focus: Domknac Erli jako pelnoprawny kanal w istniejacych wspolnych powierzchniach: filtr `Zrodlo` na liscie zamowien, kanaly sprzedazy w `/statistics/orders` i `/statistics/summary`, warunki integracji w automatyzacjach oraz aktywne menu integracji. Wprowadzic maly wspolny rejestr zrodel, zeby ograniczyc kolejne lokalne pominiecia Erli. Focus: Domknac Erli jako pelnoprawny kanal w istniejacych wspolnych powierzchniach: filtr `Zrodlo` na liscie zamowien, kanaly sprzedazy w `/statistics/orders` i `/statistics/summary`, warunki integracji w automatyzacjach oraz aktywne menu integracji. Wprowadzic maly wspolny rejestr zrodel, zeby ograniczyc kolejne lokalne pominiecia Erli.
Plans: 133-01 (complete) Plans: 133-01 (complete)
## Previous Milestone (transition pending) ## Earlier Recent Milestone (transition pending)
v3.7 Invoices (Fakturownia integration) — Complete in code, transition/follow-ups pending v3.7 Invoices (Fakturownia integration) — Complete in code, transition/follow-ups pending
@@ -567,4 +634,4 @@ Archive: `.paul/milestones/v0.1-ROADMAP.md`
--- ---
*Roadmap created: 2026-03-12* *Roadmap created: 2026-03-12*
*Last updated: 2026-05-16 - Phase 133 complete; v3.8 complete in code* *Last updated: 2026-05-16 - Phase 134 complete; Phase 135 ready to plan*

58
.paul/STATE.md
View File

@@ -5,42 +5,42 @@
See: .paul/PROJECT.md (updated 2026-05-16) See: .paul/PROJECT.md (updated 2026-05-16)
**Core value:** Sprzedawca moze obslugiwac zamowienia ze wszystkich kanalow sprzedazy i nadawac przesylki bez przelaczania sie miedzy platformami. **Core value:** Sprzedawca moze obslugiwac zamowienia ze wszystkich kanalow sprzedazy i nadawac przesylki bez przelaczania sie miedzy platformami.
**Current focus:** v3.8 Erli Marketplace Integration complete in code; next milestone selection pending. **Current focus:** v3.9 Stabilizacja i splata dlugu technicznego; Phase 134 backlog audit complete, Phase 135 ready to plan.
## Current Position ## Current Position
Milestone: v3.8 Erli Marketplace Integration Milestone: v3.9 Stabilizacja i splata dlugu technicznego
Phase: 133 of 133 (Erli Cross-Surface Parity) - Complete Phase: 135 of 142 (Accounting Net Correctness) - Ready to plan
Plan: 133-01 unified Plan: Not started
Status: Loop complete; v3.8 complete in code Status: Phase 134 complete; ready for PLAN
Last activity: 2026-05-16 16:22 - Unified .paul/phases/133-erli-cross-surface-parity/133-01-PLAN.md Last activity: 2026-05-16 20:49 - Unified .paul/phases/134-backlog-reality-check/134-01-PLAN.md
Progress: Progress:
- Milestone v3.8: [##########] 100% (Phases 127-133 complete in code) - Milestone v3.9: [#---------] 11% (1 of 9 phases complete)
- Phase 133: [##########] 100% (complete) - Phase 135: [----------] 0% (ready to plan)
## Loop Position ## Loop Position
Current loop state: Current loop state:
``` ```
PLAN -> APPLY -> UNIFY PLAN -> APPLY -> UNIFY
done done done [Loop complete - ready for milestone completion or next milestone] done done done [Loop complete - ready for next PLAN]
``` ```
## Session Continuity ## Session Continuity
Last session: 2026-05-16 16:22 Last session: 2026-05-16 20:49
Stopped at: Phase 133 complete; v3.8 complete in code Stopped at: Phase 134 complete, ready to plan Phase 135
Next action: Choose next milestone or run $paul-complete-milestone for v3.8 archival/release closure Next action: $paul-plan for Phase 135 Accounting Net Correctness
Resume file: .paul/phases/133-erli-cross-surface-parity/133-01-SUMMARY.md Resume file: .paul/phases/134-backlog-reality-check/134-01-SUMMARY.md
## Pending parallel work ## Pending parallel work
- None — Phase 118, 121, 122 wszystkie zacommitowane (8f14851, 360eef1). - None — Phase 118, 121, 122 wszystkie zacommitowane (8f14851, 360eef1).
## Git State ## Git State
Last phase commit: feat(133): erli cross-surface parity Last phase commit: feat(134): backlog reality check
Previous: feat(132): erli hardening observability docs Previous: 0c1246b feat(133): erli cross-surface parity
Branch: main Branch: main
### Skill Audit (Phase 129) ### Skill Audit (Phase 129)
@@ -73,6 +73,31 @@ Branch: main
|----------|---------|-------| |----------|---------|-------|
| `sonar-scanner` | gap documented | Attempted after APPLY; CLI is not available in PATH. | | `sonar-scanner` | gap documented | Attempted after APPLY; CLI is not available in PATH. |
### Skill Audit (Phase 134)
| Expected | Invoked | Notes |
|----------|---------|-------|
| `sonar-scanner` | gap documented | Attempted after APPLY with `sonar-scanner --version`; CLI is not available in PATH. |
## Accumulated Context
### Recent Decisions
- Phase 134 is documentation-only: no runtime code or schema changes were made.
- Backlog entries are annotated, not deleted; stale/implemented cleanup is deferred to later phases.
- Phase 135 should start with confirmed accounting net issues: `RECEIPT-NET-FIX` and `STAT-NET`.
- Phase 139 must refresh Sonar before cleanup because the current concern counts are a stale baseline.
### Blockers / Concerns
- Phase 134: `sonar-scanner` is still unavailable in PATH.
- Phase 136: Fakturownia idempotency strategy needs API/operator confirmation before code changes.
- Phase 140: deferred indexes should be applied only after operator confirms dataset size/prod timing.
### Deferred Issues
- Backlog items and concern groups classified in `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md`; implementation deferred to phases 135-142.
## Pending Actions ## Pending Actions
- Manualne testy AC-1..AC-7 dla Phase 112 na zywej bazie (XAMPP online). - Manualne testy AC-1..AC-7 dla Phase 112 na zywej bazie (XAMPP online).
@@ -111,6 +136,7 @@ Branch: main
- Phase 133 follow-up: manualny smoke `/orders/list` -> filtr `Zrodlo` ma Allegro, shopPRO i Erli; `/statistics/orders` i `/statistics/summary` -> kanal Erli widoczny i liczony; edycja automatyzacji -> aktywna integracja Erli dostepna w warunku Integracja. - Phase 133 follow-up: manualny smoke `/orders/list` -> filtr `Zrodlo` ma Allegro, shopPRO i Erli; `/statistics/orders` i `/statistics/summary` -> kanal Erli widoczny i liczony; edycja automatyzacji -> aktywna integracja Erli dostepna w warunku Integracja.
- Phase 133 verification gap: `vendor/bin/phpunit` nie istnieje w checkoutcie, wiec testy `OrderSourceRegistryTest` i `OrdersStatisticsRepositoryTest` nie zostaly uruchomione przez PHPUnit; wykonano `php -l`, ad-hoc SQLite smoke i `git diff --check`. - Phase 133 verification gap: `vendor/bin/phpunit` nie istnieje w checkoutcie, wiec testy `OrderSourceRegistryTest` i `OrdersStatisticsRepositoryTest` nie zostaly uruchomione przez PHPUnit; wykonano `php -l`, ad-hoc SQLite smoke i `git diff --check`.
- Phase 133 skill gap: `sonar-scanner` nie jest dostepny w PATH, wiec skan SonarQube nie zostal uruchomiony. - Phase 133 skill gap: `sonar-scanner` nie jest dostepny w PATH, wiec skan SonarQube nie zostal uruchomiony.
- Phase 134 skill gap: `sonar-scanner` nie jest dostepny w PATH, wiec skan SonarQube nie zostal uruchomiony; baseline concerns pozostaje stale do odswiezenia przed Phase 139.
- Phase 127 follow-up: zaplanowac kolejna faze polkurier — `PolkurierShipmentService` (CreateOrder + GetLabel + OrderValuationV2 + AvailableCarriers mapping + UI mapowan metod dostawy + presety przesylek) — fundament + zweryfikowany kontrakt API gotowy. - Phase 127 follow-up: zaplanowac kolejna faze polkurier — `PolkurierShipmentService` (CreateOrder + GetLabel + OrderValuationV2 + AvailableCarriers mapping + UI mapowan metod dostawy + presety przesylek) — fundament + zweryfikowany kontrakt API gotowy.
- Phase 127 follow-up: drugi krok — `PolkurierTrackingService` + wpisy w `delivery_status_mappings` (provider='polkurier'). - Phase 127 follow-up: drugi krok — `PolkurierTrackingService` + wpisy w `delivery_status_mappings` (provider='polkurier').
- Phase 127 follow-up: po polkurier shipment service rozwazyc fazy paczkomaty (`InpostParcelMachines` / `PocztexPostOffices` / `Kurier48PostOffices` API juz dostepne w SDK polkuriera). - Phase 127 follow-up: po polkurier shipment service rozwazyc fazy paczkomaty (`InpostParcelMachines` / `PocztexPostOffices` / `Kurier48PostOffices` API juz dostepne w SDK polkuriera).
@@ -132,4 +158,4 @@ Branch: main
## Skill Requirements ## Skill Requirements
- `sonar-scanner` required after APPLY; Phase 116, Phase 117, Phase 121, Phase 122, Phase 128, Phase 129, Phase 130, Phase 131, Phase 132 and Phase 133 gaps documented because CLI was not available in PATH. - `sonar-scanner` required after APPLY; Phase 116, Phase 117, Phase 121, Phase 122, Phase 128, Phase 129, Phase 130, Phase 131, Phase 132, Phase 133 and Phase 134 gaps documented because CLI was not available in PATH.

10
.paul/changelog/2026-05-16.md
View File

@@ -27,6 +27,11 @@
- Statystyki zawsze pokazuja kanal Erli i licza `orders.source='erli'` w agregacjach dziennych, miesiecznych i diagnostyce. - Statystyki zawsze pokazuja kanal Erli i licza `orders.source='erli'` w agregacjach dziennych, miesiecznych i diagnostyce.
- Automatyzacje pobieraja typy integracji zamowieniowych z rejestru, wiec aktywna integracja Erli jest dostepna w warunku Integracja. - Automatyzacje pobieraja typy integracji zamowieniowych z rejestru, wiec aktywna integracja Erli jest dostepna w warunku Integracja.
- Udokumentowano gapy srodowiskowe Phase 133: brak `vendor/` dla PHPUnit oraz brak `sonar-scanner` w PATH. - Udokumentowano gapy srodowiskowe Phase 133: brak `vendor/` dla PHPUnit oraz brak `sonar-scanner` w PATH.
- [Phase 134, Plan 01] Przeprowadzono Backlog Reality Check dla `.paul/codebase/todo.md` i `.paul/codebase/concerns.md`.
- Utworzono `BACKLOG-AUDIT.md` z dowodami plik/metoda/wniosek oraz routingiem do faz 135-142.
- Oznaczono aktywne wpisy `RECEIPT-NET-FIX`, `STAT-NET` i `INVOICE-IDEMP-115`; `DELIVERY-STATUS-MGMT` sklasyfikowano jako wdrozone z pozostala weryfikacja operatorska.
- Sklasyfikowano concerns: stale liczby Sonar, aktywne ryzyka TLS/indexow/cron backoff, czesciowo wdrozone elementy `SslCertificateResolver` i `RedirectPathResolver`.
- Udokumentowano gap srodowiskowy Phase 134: brak `sonar-scanner` w PATH; kod runtime nie byl zmieniany.
## Zmienione pliki ## Zmienione pliki
@@ -76,6 +81,11 @@
- `tests/Unit/ErliOrdersSyncServiceTest.php` - `tests/Unit/ErliOrdersSyncServiceTest.php`
- `.paul/phases/133-erli-cross-surface-parity/133-01-PLAN.md` - `.paul/phases/133-erli-cross-surface-parity/133-01-PLAN.md`
- `.paul/phases/133-erli-cross-surface-parity/133-01-SUMMARY.md` - `.paul/phases/133-erli-cross-surface-parity/133-01-SUMMARY.md`
- `.paul/phases/134-backlog-reality-check/134-01-PLAN.md`
- `.paul/phases/134-backlog-reality-check/134-01-SUMMARY.md`
- `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md`
- `.paul/codebase/todo.md`
- `.paul/codebase/concerns.md`
- `src/Modules/Orders/OrderSourceRegistry.php` - `src/Modules/Orders/OrderSourceRegistry.php`
- `src/Modules/Orders/OrdersRepository.php` - `src/Modules/Orders/OrdersRepository.php`
- `src/Modules/Orders/OrdersController.php` - `src/Modules/Orders/OrdersController.php`

21
.paul/codebase/concerns.md
View File

@@ -1,5 +1,26 @@
# Technical Concerns & Debt # Technical Concerns & Debt
## Status audytu Phase 134 (2026-05-16)
Szczegoly i dowody: `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md`.
| Group / item | Status po audycie | Krotki wniosek |
|--------------|-------------------|----------------|
| God Classes | **Active** | Klasy nadal sa duze; stare LOC/method counts sa nieaktualne, ale Phase 141 pozostaje zasadny. |
| SonarQube Issues | **Stale baseline / active patterns** | Liczby wymagaja nowego skanu; lokalnie nadal widac wzorce do sprzatania. `RuntimeException` import jest juz naprawiony. |
| Breaking: delivery status group keys | **Active operational follow-up** | DB-driven statusy sa wdrozone, ale stare reguly automation moga wymagac odtworzenia przez operatora. |
| Breaking: `SHIPMENT_STATUS_OPTION_MAP` | **Implemented / stale** | Symbol nie wystepuje juz w runtime source. |
| Breaking: `_csrf_token` -> `_token` | **Implemented / stale** | Formularze/kontrolery uzywaja `_token`; wewnetrzny session key w `Csrf` nie jest problemem formularzy. |
| Known Bugs: `STAT-NET` | **Active** | Przeniesione do Phase 135 razem z `RECEIPT-NET-FIX`. |
| Deferred Indexes | **Active / deferred** | Indeksy nadal nie sa w migracjach; wykonac po decyzji operatora w Phase 140. |
| Security: print API keys | **Implemented / stale** | Przechowywany jest hash i prefix, nie raw `api_key`. |
| Security: mailbox TLS | **Active, wording stale** | Nie ma juz `fsockopen`, ale `stream_socket_client()` ma `verify_peer=false`. |
| Security: template variables | **Needs operator/security decision** | Resolver dopuszcza tylko znane mapy, ale trzeba zdecydowac polityke dla nieznanych `{{var}}`. |
| Architecture Concerns | **Active / low impact** | Zostawic do decyzji w Phase 142. |
| Duplication Areas | **Mixed** | `SslCertificateResolver` i `RedirectPathResolver` sa czesciowo wdrozone; reszta wymaga selektywnej decyzji. |
| Legacy patterns | **Mixed** | View `include/require` nadal wystepuja; raw `$_SESSION` glownie w warstwach Auth/Flash/Csrf/OAuth. |
| Performance Risks | **Active / needs profiling** | Return-risk indexes i cron backoff aktywne; `findDetails()` najpierw profilowac. |
## God Classes (Priority Refactor Targets) ## God Classes (Priority Refactor Targets)
| Class | LOC | Methods | Issue | | Class | LOC | Methods | Issue |

12
.paul/codebase/todo.md
View File

@@ -4,6 +4,9 @@
## RECEIPT-NET-FIX — `receipts.total_net` powinno byc realnym netto (data: 2026-05-12) ## RECEIPT-NET-FIX — `receipts.total_net` powinno byc realnym netto (data: 2026-05-12)
### Status audytu Phase 134 (2026-05-16)
- **Active** - `ReceiptService::issue()` nadal zapisuje `total_net` jako kopie brutto, a `buildItemsSnapshot()` nie zwraca netto. Dowody: `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md`.
### Kontekst ### Kontekst
- Phase 123-01 — eksport paragonow XLSX z VAT breakdown. - Phase 123-01 — eksport paragonow XLSX z VAT breakdown.
- `ReceiptService::issue()` (linie 81-82) zapisuje `total_net = total_gross` (kopia, nie realne netto). To znany bug, ale nie poprawiany w 123 (poza zakresem). - `ReceiptService::issue()` (linie 81-82) zapisuje `total_net = total_gross` (kopia, nie realne netto). To znany bug, ale nie poprawiany w 123 (poza zakresem).
@@ -18,6 +21,9 @@
## INVOICE-IDEMP-115 — idempotencja podwojnego POST do Fakturowni (data: 2026-05-10) ## INVOICE-IDEMP-115 — idempotencja podwojnego POST do Fakturowni (data: 2026-05-10)
### Status audytu Phase 134 (2026-05-16)
- **Active / needs operator/API decision** - brak lokalnego `pending_external`, idempotency key i lookupu po referencji przed ponownym POST. W Phase 136 najpierw potwierdzic mozliwosci API Fakturowni. Dowody: `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md`.
### Kontekst ### Kontekst
- Phase 115-01 — wystawianie faktury z zamowienia (delegacja Fakturownia). - Phase 115-01 — wystawianie faktury z zamowienia (delegacja Fakturownia).
- Flow: `InvoiceService::issueDelegated()` -> POST do Fakturowni -> on success INSERT do `invoices`. - Flow: `InvoiceService::issueDelegated()` -> POST do Fakturowni -> on success INSERT do `invoices`.
@@ -35,6 +41,9 @@
## STAT-NET — netto zamowien w statystykach (data: 2026-04-19) ## STAT-NET — netto zamowien w statystykach (data: 2026-04-19)
### Status audytu Phase 134 (2026-05-16)
- **Active** - `OrdersStatisticsRepository::netAmountSql()` nadal ma fallback `gross / 1.23`; mapper potrafi przyjac czesc pol netto/VAT, ale statystyki nie licza netto po pozycjach. Dowody: `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md`.
### Kontekst ### Kontekst
- Statystyki `/statistics/orders` pokazuja `Netto` per dzien/kanal. - Statystyki `/statistics/orders` pokazuja `Netto` per dzien/kanal.
- shopPRO nie wysyla kwoty netto ani na poziomie zamowienia (`orders.total_without_tax`), ani produktow (`order_items.original_price_without_tax` — rowniez puste). - shopPRO nie wysyla kwoty netto ani na poziomie zamowienia (`orders.total_without_tax`), ani produktow (`order_items.original_price_without_tax` — rowniez puste).
@@ -57,6 +66,9 @@
## DELIVERY-STATUS-MGMT — zarzadzanie statusami znormalizowanymi z panelu (data: 2026-04-26) ## DELIVERY-STATUS-MGMT — zarzadzanie statusami znormalizowanymi z panelu (data: 2026-04-26)
### Status audytu Phase 134 (2026-05-16)
- **Implemented; operator verification remains** - core DB-driven statusy, CRUD i dropdowny automatyzacji sa wdrozone po Phase 108. Phase 137 powinien zweryfikowac tylko stare reguly automatyzacji/operator migration i zamknac nieaktualny wpis. Dowody: `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md`.
### Kontekst ### Kontekst
- Aktualnie statusy znormalizowane (`created`, `confirmed`, `picked_up`, `in_transit`, itd.) sa stalymi w kodzie (`DeliveryStatus.php`). - Aktualnie statusy znormalizowane (`created`, `confirmed`, `picked_up`, `in_transit`, itd.) sa stalymi w kodzie (`DeliveryStatus.php`).
- Dodanie nowego statusu wymaga zmiany kodu + deploymentu. - Dodanie nowego statusu wymaga zmiany kodu + deploymentu.

220
.paul/phases/134-backlog-reality-check/134-01-PLAN.md Normal file
View File

@@ -0,0 +1,220 @@
---
phase: 134-backlog-reality-check
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- .paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md
- .paul/codebase/todo.md
- .paul/codebase/concerns.md
- .paul/phases/134-backlog-reality-check/134-01-SUMMARY.md
autonomous: true
delegation: off
---
<objective>
## Goal
Zweryfikowac wszystkie wpisy z `.paul/codebase/todo.md` i `.paul/codebase/concerns.md` przeciw aktualnemu kodowi oraz dokumentacji, a nastepnie oznaczyc kazdy wpis jako: nadal aktywny, juz wdrozony, nieaktualny albo wymaga decyzji operatora.
## Purpose
Milestone v3.9 ma najpierw ustalic realny stan backlogu, zeby kolejne fazy 135-142 poprawialy tylko potwierdzone problemy i nie powielaly pracy juz wykonanej w Phase 108, 123, 125, 127-133.
## Output
- `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md` z tabela audytu i dowodami.
- Krotkie statusy przy wpisach w `.paul/codebase/todo.md` i `.paul/codebase/concerns.md`.
- `.paul/phases/134-backlog-reality-check/134-01-SUMMARY.md` po APPLY.
</objective>
<context>
<clarifications>
- **Format wyniku** - Czy audyt ma stworzyc osobny raport, czy od razu przepisac backlog?
-> Odpowiedz: A - osobny raport + krotkie statusy w `todo.md` / `concerns.md`.
- **Zakres** - Czy Phase 134 ma wylacznie klasyfikowac wpisy, czy tez od razu usuwac/porzadkowac nieaktualne wpisy?
-> Odpowiedz: A - klasyfikowac i zostawic decyzje na kolejne fazy.
- **Dowody** - Jak szczegolowe maja byc potwierdzenia?
-> Odpowiedz: A - plik + metoda/sekcja + krotki wniosek.
</clarifications>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
@AGENTS.md
@DOCS/ARCHITECTURE.md
@DOCS/DB_SCHEMA.md
@DOCS/TECH_CHANGELOG.md
## Backlog Sources
@.paul/codebase/todo.md
@.paul/codebase/concerns.md
@.paul/codebase/architecture.md
@.paul/codebase/db_schema.md
@.paul/codebase/tech_changelog.md
@.paul/codebase/index.md
## Source Files To Check
@src/Modules/Accounting/ReceiptService.php
@src/Modules/Accounting/AccountingController.php
@src/Modules/Accounting/InvoiceService.php
@src/Modules/Settings/FakturowniaApiClient.php
@src/Modules/Statistics/OrdersStatisticsRepository.php
@src/Modules/Settings/ShopproOrderMapper.php
@src/Modules/Shipments/DeliveryStatus.php
@src/Modules/Shipments/DeliveryStatusRepository.php
@src/Modules/Settings/DeliveryStatusesController.php
@src/Modules/Settings/DeliveryStatusMappingController.php
@src/Modules/Automation/AutomationController.php
@src/Modules/Automation/AutomationService.php
@src/Modules/Settings/EmailMailboxController.php
@src/Modules/Printing/PrintApiKeyRepository.php
@src/Modules/Orders/OrdersRepository.php
@src/Modules/Cron/CronRunner.php
@src/Modules/Cron/ShipmentTrackingHandler.php
@src/Modules/Settings/AllegroOrderImportService.php
@resources/views/accounting/index.php
@resources/views/orders/show.php
@routes/web.php
@database/migrations/
</context>
<skills>
## Required Skills / Checks From SPECIAL-FLOWS.md
| Skill / Tool | Priority | When to Invoke | Loaded? |
|--------------|----------|----------------|---------|
| `sonar-scanner` | required | After APPLY, before UNIFY; if unavailable, document gap as in prior phases | o |
## Skill Invocation Checklist
- [ ] Run `sonar-scanner` after APPLY or document PATH/environment gap in SUMMARY and STATE.
</skills>
<acceptance_criteria>
## AC-1: Todo Backlog Classified
```gherkin
Given `.paul/codebase/todo.md` contains RECEIPT-NET-FIX, INVOICE-IDEMP-115, STAT-NET and DELIVERY-STATUS-MGMT entries
When the plan audits the current code and documentation
Then every todo entry has one explicit status: active, implemented, stale, or needs-operator-decision
And each status is backed by a file/method/section evidence note in BACKLOG-AUDIT.md
```
## AC-2: Concerns Classified
```gherkin
Given `.paul/codebase/concerns.md` lists Sonar, breaking-change, security, architecture, duplication, legacy and performance concerns
When the plan audits the current code and documentation
Then every concern group has a verified status and concise evidence in BACKLOG-AUDIT.md
And no concern is removed from the backlog during this plan
```
## AC-3: Backlog Gets Concise Statuses Only
```gherkin
Given the operator chose a separate report plus short backlog statuses
When the audit is complete
Then `.paul/codebase/todo.md` and `.paul/codebase/concerns.md` include compact status annotations that point to BACKLOG-AUDIT.md
And detailed evidence remains in the audit report rather than bloating the backlog files
```
## AC-4: No Runtime Behavior Change
```gherkin
Given Phase 134 is a reality-check phase
When APPLY executes this plan
Then application runtime files, migrations, SCSS, JS and views are not changed
And any confirmed implementation work is deferred to later phases 135-142 or marked as operator decision
```
</acceptance_criteria>
<tasks>
<task type="auto">
<name>Task 1: Audit todo entries against code and docs</name>
<files>.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md, .paul/codebase/todo.md</files>
<action>
For each entry in `.paul/codebase/todo.md`, verify current implementation and documentation:
- `RECEIPT-NET-FIX`: compare `ReceiptService::buildItemsSnapshot()` and receipt insert payload with `InvoiceService::buildItemsSnapshot()` and `AccountingController::buildVatBreakdown()`.
- `INVOICE-IDEMP-115`: inspect `InvoiceService::issueDelegated()` and `FakturowniaApiClient::createInvoice()` for idempotency key, pending local row, or external lookup before retry.
- `STAT-NET`: inspect `OrdersStatisticsRepository::netAmountSql()` and `ShopproOrderMapper` net fields; confirm whether item-level VAT fallback exists.
- `DELIVERY-STATUS-MGMT`: inspect Phase 108 implementation and docs for `delivery_statuses`, `DeliveryStatusRepository`, DB-driven dropdowns and remaining hardcoded fallback obligations.
Write detailed evidence to `BACKLOG-AUDIT.md`; add only compact status lines in `todo.md`.
Avoid fixing any application code in this phase because AC-4 limits the work to audit/classification.
</action>
<verify>rg -n "Status audytu|BACKLOG-AUDIT|RECEIPT-NET-FIX|INVOICE-IDEMP-115|STAT-NET|DELIVERY-STATUS-MGMT" .paul/codebase/todo.md .paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md</verify>
<done>AC-1 and AC-3 satisfied for all todo entries.</done>
</task>
<task type="auto">
<name>Task 2: Audit concerns and risk groups</name>
<files>.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md, .paul/codebase/concerns.md</files>
<action>
Verify each concern group in `.paul/codebase/concerns.md` against current code and docs:
- God classes / S1448 targets: re-count or inspect current files named in the table.
- Sonar issues: confirm locally searchable issues where possible; mark scan-dependent counts as stale-baseline if `sonar-scanner` or MCP data is unavailable.
- Breaking changes: verify Phase 108 delivery status contract and `_token` CSRF form naming.
- Known bugs: cross-link active issues already covered by todo audit.
- Deferred indexes and performance risks: inspect `OrdersRepository` return-risk subqueries and current migrations for missing indexes.
- Security / legacy patterns: inspect print API key storage, `EmailMailboxController::testConnection()`, template variable resolution, `RuntimeException` import, raw `$_SESSION`, and old view `require` patterns.
- Architecture concerns and duplication areas: classify as active/deferred/needs-decision with concise evidence.
Keep detailed findings in `BACKLOG-AUDIT.md`; add compact status annotations in `concerns.md`.
Avoid broad refactors or code edits; this phase is inventory, not remediation.
</action>
<verify>rg -n "Status audytu|BACKLOG-AUDIT|God Classes|SonarQube|Security|Performance Risks|Legacy" .paul/codebase/concerns.md .paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md</verify>
<done>AC-2, AC-3 and AC-4 satisfied for all concern groups.</done>
</task>
<task type="auto">
<name>Task 3: Finalize audit summary and verification</name>
<files>.paul/phases/134-backlog-reality-check/134-01-SUMMARY.md, .paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md</files>
<action>
Create `134-01-SUMMARY.md` with:
- counts by status: active, implemented, stale, needs-operator-decision;
- recommended next-phase inputs for phases 135-142;
- explicit note that runtime code was not changed;
- verification commands run and any environment gaps, including `sonar-scanner` if unavailable.
Ensure `BACKLOG-AUDIT.md` has enough structure for later phases to pick up one issue without re-reading the whole codebase.
</action>
<verify>git diff --check; rg -n "Runtime code changed: no|sonar-scanner|Phase 135|Phase 142" .paul/phases/134-backlog-reality-check/134-01-SUMMARY.md</verify>
<done>AC-1 through AC-4 satisfied, with a clear handoff for future phase planning.</done>
</task>
</tasks>
<boundaries>
## DO NOT CHANGE
- `src/**`
- `resources/**`
- `public/**`
- `routes/**`
- `database/migrations/**`
- `.env`, `.env.example`
## SCOPE LIMITS
- Do not implement fixes for RECEIPT-NET-FIX, STAT-NET, INVOICE-IDEMP-115, security items, indexes or refactors in this plan.
- Do not delete backlog entries, even if stale or already implemented; annotate them and defer cleanup decisions.
- Do not update DB schema docs unless the audit discovers documentation drift that blocks correct classification.
- Do not use `DB_HOST_REMOTE`; no database mutation is needed for this audit.
</boundaries>
<verification>
Before declaring plan complete:
- [ ] `rg -n "Status audytu|BACKLOG-AUDIT" .paul/codebase/todo.md .paul/codebase/concerns.md`
- [ ] `rg -n "RECEIPT-NET-FIX|INVOICE-IDEMP-115|STAT-NET|DELIVERY-STATUS-MGMT|Security|Performance Risks" .paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md`
- [ ] `git diff --check`
- [ ] `sonar-scanner` run after APPLY or missing CLI documented as a verification gap
- [ ] Confirm no runtime files changed: `git diff --name-only -- src resources public routes database`
- [ ] All acceptance criteria met
</verification>
<success_criteria>
- Every todo entry and concern group is classified.
- Each classification has file/method/section evidence in `BACKLOG-AUDIT.md`.
- `.paul/codebase/todo.md` and `.paul/codebase/concerns.md` get compact status annotations only.
- Runtime code and schema are unchanged.
- Summary names concrete next-phase inputs for phases 135-142.
</success_criteria>
<output>
After completion, create `.paul/phases/134-backlog-reality-check/134-01-SUMMARY.md`.
</output>

132
.paul/phases/134-backlog-reality-check/134-01-SUMMARY.md Normal file
View File

@@ -0,0 +1,132 @@
---
phase: 134-backlog-reality-check
plan: 01
subsystem: planning
tags: [backlog, audit, technical-debt, paul]
requires:
- phase: v3.9-milestone
provides: backlog-based roadmap from todo.md and concerns.md
provides:
- Backlog audit report with evidence
- Compact status annotations for todo.md and concerns.md
- Next-phase inputs for phases 135-142
affects: [phase-135, phase-136, phase-137, phase-138, phase-139, phase-140, phase-141, phase-142]
tech-stack:
added: []
patterns: [documentation-only audit, evidence-backed backlog triage]
key-files:
created:
- .paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md
modified:
- .paul/codebase/todo.md
- .paul/codebase/concerns.md
- .paul/ROADMAP.md
- .paul/STATE.md
- .paul/PROJECT.md
- .paul/changelog/2026-05-16.md
key-decisions:
- "Phase 134 is documentation-only: classify backlog reality without runtime fixes."
- "Implemented/stale backlog entries are annotated, not deleted."
- "Sonar counts remain stale until sonar-scanner is available again."
patterns-established:
- "Future debt phases should start from BACKLOG-AUDIT.md evidence instead of old backlog text."
duration: 25min
started: 2026-05-16T20:24:00+02:00
completed: 2026-05-16T20:49:00+02:00
---
# Phase 134 Plan 01: Backlog Reality Check Summary
Backlog items from `.paul/codebase/todo.md` and `.paul/codebase/concerns.md` were reconciled against current code/docs, with evidence captured for the next stabilization phases.
## Performance
| Metric | Value |
|--------|-------|
| Duration | ~25min |
| Started | 2026-05-16 20:24 |
| Completed | 2026-05-16 20:49 |
| Tasks | 3 completed |
| Files created/modified | 7 PAUL/docs files |
## Acceptance Criteria Results
| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Todo Backlog Classified | Pass | `RECEIPT-NET-FIX`, `INVOICE-IDEMP-115`, `STAT-NET`, and `DELIVERY-STATUS-MGMT` each have an explicit status and evidence in `BACKLOG-AUDIT.md`. |
| AC-2: Concerns Classified | Pass | Sonar, breaking changes, known bugs, indexes, security, architecture, duplication, legacy, and performance risks were classified. No concerns were removed. |
| AC-3: Backlog Gets Concise Statuses Only | Pass | `todo.md` and `concerns.md` received compact annotations pointing to `BACKLOG-AUDIT.md`; detailed evidence stayed in the report. |
| AC-4: No Runtime Behavior Change | Pass | `git diff --name-only -- src resources public routes database` returned no runtime paths. |
## Accomplishments
- Created `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md` with file/method evidence and next-phase routing.
- Marked 3 TODO items active, 1 implemented, and 1 active item needing Fakturownia API/operator decision.
- Marked concern groups as active, stale, implemented, or decision-dependent, including stale Sonar baseline and current TLS/backoff/index risks.
- Confirmed Phase 137 should not rebuild delivery status management; the remaining work is operator migration/verification of old automation rules.
- Preserved all backlog entries and deferred implementation fixes to phases 135-142.
## Files Created/Modified
| File | Change | Purpose |
|------|--------|---------|
| `.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md` | Created | Main audit report with evidence and phase routing. |
| `.paul/phases/134-backlog-reality-check/134-01-SUMMARY.md` | Created/updated | UNIFY summary and acceptance results. |
| `.paul/codebase/todo.md` | Modified | Compact status annotations for each TODO entry. |
| `.paul/codebase/concerns.md` | Modified | Compact Phase 134 status table for concern groups. |
| `.paul/ROADMAP.md` | Modified | Phase 134 completion and Phase 135 readiness. |
| `.paul/STATE.md` | Modified | Loop closure, Phase 135 routing, and Sonar gap. |
| `.paul/PROJECT.md` | Modified | v3.9 state and Phase 134 validated requirement/decision. |
| `.paul/changelog/2026-05-16.md` | Modified | Human-readable Phase 134 changelog entry. |
## Decisions Made
| Decision | Rationale | Impact |
|----------|-----------|--------|
| Keep Phase 134 documentation-only | The phase objective was reality-check classification, not remediation. | Runtime code stayed untouched; fixes route to later phases. |
| Annotate implemented/stale entries instead of deleting | Operator chose separate report plus short statuses, with cleanup deferred. | Historical backlog context remains available. |
| Treat Sonar counts as stale baseline | `sonar-scanner` is not available in PATH, and prior phases already documented that gap. | Phase 139 must refresh scan or locally confirm each issue before changes. |
## Deviations from Plan
| Type | Count | Impact |
|------|-------|--------|
| Auto-fixed | 0 | None. |
| Scope additions | 0 | None. |
| Deferred | 1 | Sonar scan remains blocked by missing CLI. |
The plan executed as documentation/audit work. The only verification gap is environmental: `sonar-scanner` is not available in PATH.
## Issues Encountered
| Issue | Resolution |
|-------|------------|
| `sonar-scanner --version` failed because the CLI is not in PATH. | Gap documented in this summary and `.paul/STATE.md`; Phase 139 should refresh Sonar before cleanup. |
## Verification Results
| Command | Result |
|---------|--------|
| `rg -n "Status audytu|BACKLOG-AUDIT" .paul/codebase/todo.md .paul/codebase/concerns.md` | Passed. |
| `rg -n "RECEIPT-NET-FIX|INVOICE-IDEMP-115|STAT-NET|DELIVERY-STATUS-MGMT|Security|Performance Risks" .paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md` | Passed. |
| `git diff --name-only -- src resources public routes database` | Passed; no runtime files changed. |
| `sonar-scanner --version` | Failed; CLI not available in PATH. |
| `git diff --check` | Passed; Git reported existing LF->CRLF normalization warnings only. |
## Next Phase Readiness
**Ready:**
- Phase 135 has confirmed active inputs: `RECEIPT-NET-FIX` and `STAT-NET`.
- Phase 136 has confirmed active input: `INVOICE-IDEMP-115`, with an explicit API-decision prerequisite.
- Phases 137-142 have scoped evidence and should not need to rediscover the backlog from scratch.
**Concerns:**
- Sonar baseline remains stale until the CLI or MCP flow is available.
- Some future items need operator/security/profiling decisions before implementation.
**Blockers:**
- None for planning Phase 135.
---
*Phase: 134-backlog-reality-check, Plan: 01*
*Completed: 2026-05-16*

158
.paul/phases/134-backlog-reality-check/BACKLOG-AUDIT.md Normal file
View File

@@ -0,0 +1,158 @@
# Phase 134 Backlog Reality Check
Audit date: 2026-05-16
Plan: `.paul/phases/134-backlog-reality-check/134-01-PLAN.md`
Scope: `.paul/codebase/todo.md` and `.paul/codebase/concerns.md` verified against current code and docs.
## Status Legend
| Status | Meaning |
|--------|---------|
| Active | Still present in code/docs and should feed a later phase. |
| Implemented | Current code already implements the requested behavior; backlog entry should be closed or reworded later. |
| Stale | The old description is inaccurate; keep only if rewritten to the current risk. |
| Needs operator decision | Requires product/operator choice, live environment check, or external API confirmation before code work. |
## Executive Summary
| Source | Active | Implemented | Stale | Needs operator decision |
|--------|--------|-------------|-------|-------------------------|
| TODO entries | 3 | 1 | 0 | 1 |
| Concern groups/items | 8 | 4 | 4 | 5 |
Main active work:
- Phase 135 should handle `RECEIPT-NET-FIX` and `STAT-NET`.
- Phase 136 should handle `INVOICE-IDEMP-115`, after confirming Fakturownia idempotency/deduplication options.
- Phase 137 should not rebuild delivery status management; it should verify operator migration of old automation rules and close stale leftovers.
- Phase 138 should focus on the still-current security/legacy items: weak TLS verification in mailbox test, template variable policy, raw session exceptions, and view include/require cleanup.
- Phase 140 should cover deferred indexes and cron backoff sizing.
- Phase 141 should cover confirmed large classes and remaining duplication.
Runtime code changed: no.
## TODO Audit
| ID | Status | Evidence | Conclusion / next phase |
|----|--------|----------|-------------------------|
| `RECEIPT-NET-FIX` | Active | `src/Modules/Accounting/ReceiptService.php::issue()` writes `total_net` from `$totalGross`; `buildItemsSnapshot()` returns only `items` and `total_gross`. `src/Modules/Accounting/InvoiceService.php::buildItemsSnapshot()` already computes `total_net` separately. `src/Modules/Accounting/AccountingController.php::buildVatBreakdown()` still has a gross `/ 1.23` legacy fallback when item VAT is missing. | Real bug still exists. Feed Phase 135. |
| `INVOICE-IDEMP-115` | Active + needs operator/API decision | `src/Modules/Accounting/InvoiceService.php::issueDelegated()` calls `FakturowniaApiClient::createInvoice()` before inserting the local invoice row. `src/Modules/Settings/FakturowniaApiClient.php::createInvoice()` posts `/invoices.json`; no `Idempotency-Key`, pending local row, or external lookup was found. | Risk of duplicate Fakturownia invoices still exists. Feed Phase 136; first verify Fakturownia support for idempotency header or query-by-reference. |
| `STAT-NET` | Active | `src/Modules/Statistics/OrdersStatisticsRepository.php::netAmountSql()` still falls back to `ROUND(gross / 1.23, 2)` and carries `TODO(STAT-NET)`. `src/Modules/Settings/ShopproOrderMapper.php` maps order-level net and item-level `price_net`/`net_price`/`price_netto` plus `tax_rate` when the source provides them, but statistics do not aggregate item-level VAT. | Real stats limitation remains. Feed Phase 135. |
| `DELIVERY-STATUS-MGMT` | Implemented; operator verification remains | `src/Modules/Shipments/DeliveryStatusRepository.php` provides DB CRUD/cache. `src/Modules/Shipments/DeliveryStatus.php` can use the repository and has constant fallback. `src/Modules/Settings/DeliveryStatusesController.php` provides UI CRUD. `src/Modules/Automation/AutomationController.php` and `AutomationService.php` use `DeliveryStatus::getAllStatuses()` / `getAllOptions()` instead of a removed hardcoded option map. | Core feature was implemented in Phase 108. Keep only Phase 137 verification for old automation rules and operator migration. |
## Concerns Audit
### God Classes
Status: Active.
Current rough counts from local files:
| Class | Current rough LOC | Current rough methods | Evidence / conclusion |
|-------|-------------------|-----------------------|-----------------------|
| `src/Modules/Orders/OrdersRepository.php` | 1109 | 37 | Still very large; Phase 141 target remains valid. |
| `src/Modules/Orders/OrdersController.php` | 1313 | 39 | Still combines list/detail/actions; Phase 141 target remains valid. |
| `src/Modules/Automation/AutomationService.php` | 712 | 28 | Smaller than old note but still broad; Phase 141 target remains valid. |
| `src/Modules/Settings/ShopproOrderMapper.php` | 788 | 27 | Still large mapper with many transformations; Phase 141 target remains valid. |
| `src/Modules/Shipments/ApaczkaShipmentService.php` | 926 | 30 | Still large service; old path in concerns says Settings, current path is Shipments. |
| `src/Modules/Settings/ShopproIntegrationsController.php` | 915 | 39 | Still broad integration/settings controller. |
The old LOC/method counts are stale, but the concern itself is active.
### SonarQube Issues
Status: stale baseline, locally active patterns.
Evidence:
- `.paul/STATE.md` records `sonar-scanner` gaps for phases 129-133.
- Local rough search still finds many generic exception/catch patterns, so `php:S112`-style cleanup remains plausible.
- `src/Modules/Settings/AllegroOrderImportService.php` now imports `RuntimeException`, so the old `php:S5911` blocker is implemented/stale.
- `src/Modules/Settings/EmailMailboxController.php::testConnection()` no longer uses `fsockopen()`, but uses `stream_socket_client()` with `verify_peer => false` and `verify_peer_name => false`; the old rule wording is stale, the security issue remains active.
- Accessibility counts need a fresh Sonar scan; local grep found many `aria-label` usages and did not establish the old Web issue counts.
Conclusion: refresh scan before Phase 139. Do not trust the old count of 174 as current truth.
### Breaking Changes
| Change | Status | Evidence / conclusion |
|--------|--------|-----------------------|
| Delivery status group keys moved to DB | Active operational follow-up / needs operator decision | Phase 108 code is DB-driven, but old automation rules using removed group keys still require operator review/recreation. Feed Phase 137. |
| `SHIPMENT_STATUS_OPTION_MAP` removed | Implemented/stale | `rg` found the symbol only in docs/backlog, not runtime source. `AutomationService` compares status keys directly and validates through `DeliveryStatus`. |
| `_csrf_token` -> `_token` | Implemented for forms; stale wording | Forms/controllers use `_token`. `src/Core/Security/Csrf.php` still uses internal session key `_csrf_token`, which is not the deprecated form field reference. |
### Known Bugs
| Issue | Status | Evidence / conclusion |
|-------|--------|-----------------------|
| `STAT-NET` | Active | Covered in TODO audit; Phase 135. |
| Missing net amounts for shopPRO orders | Active / needs source decision | `ShopproOrderMapper` can read net fields when present; source payload availability still needs confirmation. Phase 135. |
| `order.status_aged` condition fallback | Implemented/stale | Concerns already says fixed 2026-04-25; no new work in Phase 134. |
### Deferred Indexes
Status: Active, deferred.
Evidence:
- `DOCS/DB_SCHEMA.md` and `.paul/codebase/db_schema.md` list `idx_order_addresses_order_type` and `idx_shipment_packages_order_delivery` as deferred indexes.
- `database/migrations/` does not contain those index names.
- `src/Modules/Orders/OrdersRepository.php::customerReturnedCountSubquerySql()` still uses a correlated subquery over `shipment_packages` and `order_addresses`.
Conclusion: feed Phase 140; apply only after operator confirms current dataset/prod timing.
### Security Items
| Item | Status | Evidence / conclusion |
|------|--------|-----------------------|
| `print_api_keys.api_key` encryption | Implemented/stale | `src/Modules/Printing/PrintApiKeyRepository.php` stores `key_hash` and `key_prefix`, not raw `api_key`. `src/Modules/Printing/ApiKeyMiddleware.php` hashes incoming keys before lookup. No encryption action needed for a raw key column. |
| Email mailbox TLS test | Active; old wording stale | `EmailMailboxController::testConnection()` uses `stream_socket_client()`, but SSL verification is disabled (`verify_peer=false`, `verify_peer_name=false`). Feed Phase 138 with updated wording. |
| Email/SMS variable injection | Needs operator/security decision | `EmailTemplateController` and `SmsTemplateController` expose fixed `VARIABLE_GROUPS`; `SmsVariableResolver::resolve()` only replaces keys matching `[a-z_]+.[a-z_]+` from a supplied map and unknown variables become empty. Email preview keeps unknown variables unchanged. Decide desired policy: reject unknown variables at save, leave unchanged, or render empty. |
| `RuntimeException` missing import | Implemented/stale | `src/Modules/Settings/AllegroOrderImportService.php` has `use RuntimeException;`. |
### Architecture Concerns
Status: Active but low-impact / needs operator prioritization.
Evidence:
- No repository interface layer was introduced broadly; current code still injects concrete repositories.
- Event/action names remain string typed in automation/integration flows.
- Validation remains scattered across controllers/repositories.
- No broad HTTP cache/query cache layer was found.
Conclusion: feed Phase 142 as optional guardrails after higher-risk work.
### Duplication Areas
| Area | Status | Evidence / conclusion |
|------|--------|-----------------------|
| `SslCertificateResolver` | Partly implemented / wording stale | Resolver exists and is reused by API clients; remaining duplication is per-client cURL setup rather than CA path logic. |
| `ToggleableRepositoryTrait` | Active / needs design decision | Trait still mixes toggling with query concerns; Phase 141 or 142 can decide whether to split. |
| `RedirectPathResolver` | Partly implemented / wording stale | Resolver exists and is reused by several integration controllers; remaining local redirect differences should be verified before refactor. |
| `ReceiptService` vs accounting logic | Active | Receipt net/VAT overlap is still visible in `ReceiptService` and `AccountingController`; Phase 135 should reduce this while fixing net correctness. |
### Legacy / Deprecated Patterns
| Pattern | Status | Evidence / conclusion |
|---------|--------|-----------------------|
| `fsockopen('ssl://')` | Implemented/stale | No `fsockopen` remains in `EmailMailboxController`; update concern to weak TLS verification via `stream_socket_client()`. |
| `require` / `include` in views | Active, low priority | `resources/views/accounting/index.php`, `orders/list.php`, `orders/show.php`, layouts, and settings views still include components directly. Some are intentional current style; decide before broad cleanup. |
| Raw `$_SESSION` access | Partly active / needs decision | Raw session is mostly in `AuthService`, `Flash`, `Csrf`, and Allegro OAuth state. These may be acceptable boundary classes; decide whether to wrap OAuth/session internals in Phase 138. |
### Performance Risks
| Risk | Status | Evidence / conclusion |
|------|--------|-----------------------|
| Correlated return-risk subquery | Active | Covered by deferred indexes; Phase 140. |
| N+1 potential in order details | Needs profiling decision | `OrdersRepository::findDetails()` performs separate queries for order/address/items/etc. That may be acceptable for one detail page; profile before refactor. |
| Cron queue growth / no exponential backoff | Active / needs sizing | `CronRunner.php` passes fixed `60` seconds to `markJobFailed()`. `CronRepository::markJobFailed()` reschedules using `max(10, retryDelaySeconds)` while attempts remain; no exponential backoff was found. |
## Next-Phase Inputs
| Phase | Confirmed input |
|-------|-----------------|
| 135 | Fix `ReceiptService` net total; replace stats hardcoded `/1.23` with order/item VAT-aware path; decide backfill. |
| 136 | Add Fakturownia duplicate protection after API capability check. |
| 137 | Close implemented delivery status TODO; verify old automation rules and operator migration. |
| 138 | Update TLS verification, decide unknown variable policy, review raw session/view include cleanup. |
| 139 | Refresh Sonar scan first; then address confirmed critical/major issues. |
| 140 | Add/index-gate deferred indexes; evaluate `findDetails()` profiling; design cron backoff. |
| 141 | Refactor confirmed large classes and remaining duplication. |
| 142 | Decide lightweight architecture guardrails after higher-risk work. |