orderPRO/.paul/phases/105-orders-statistics/105-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, delegation

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
105-orders-statistics	01	execute	1		src/Modules/Statistics/OrdersStatisticsController.php src/Modules/Statistics/OrdersStatisticsRepository.php routes/web.php resources/views/layouts/app.php resources/views/statistics/orders.php resources/lang/pl.php resources/scss/app.scss .paul/docs/ARCHITECTURE.md .paul/docs/TECH_CHANGELOG.md	true	auto

## Goal Dodac nowa sekcje menu `Statystyki -> Zamowienia` z tabela dziennych podsumowan zamowien i kwot (netto/brutto), z rozbiciem na kanaly: `allegro` jako jeden kanal oraz kazda aktywna integracja `shopPRO` jako osobny kanal.

Purpose

Operator potrzebuje szybkiego podsumowania sprzedazy dziennej w jednym miejscu, z mozliwoscia filtrowania po datach, kanalach sprzedazy i grupach statusow, bez recznego eksportu danych.

Output

• Nowy endpoint i widok /statistics/orders.
• Filtry: zakres dat (calendar), kanal sprzedazy (multiselect), grupa statusow (multiselect).
• Domyslnie wszystkie grupy statusow zaznaczone poza grupa anulowane.
• Tabela dzienna z dynamicznymi kolumnami per kanal (ilosc/netto/brutto) oraz wierszem Razem na dole.

## Project Context @.paul/PROJECT.md @.paul/ROADMAP.md @.paul/STATE.md @.paul/docs/DB_SCHEMA.md @.paul/docs/ARCHITECTURE.md

Prior Work

@.paul/phases/21-order-source-display/21-01-SUMMARY.md @.paul/phases/85-status-group-filter/85-01-SUMMARY.md

Source Files

@routes/web.php @resources/views/layouts/app.php @resources/lang/pl.php @src/Modules/Orders/OrdersRepository.php @src/Modules/Orders/OrdersController.php @resources/views/components/table-list.php @resources/scss/app.scss

## Required Skills (from SPECIAL-FLOWS.md)

Skill	Priority	When to Invoke	Loaded?
sonar-scanner (CLI)	required	Po APPLY, przed UNIFY	o
/feature-dev	optional	Przy implementacji nowej funkcjonalnosci	o
/frontend-design	optional	Przy dopracowaniu widoku tabeli/statystyk	o

Skill Invocation Checklist

• Potwierdzony plan uruchomienia sonar-scanner po APPLY.
• (Opcjonalnie) /feature-dev
• (Opcjonalnie) /frontend-design

<acceptance_criteria>

AC-1: Nowa pozycja menu i routing statystyk

Given uzytkownik jest zalogowany do panelu
When otworzy menu boczne
Then widzi nowa grupe "Statystyki" z podpozycja "Zamowienia"
And klikniecie "Zamowienia" otwiera strone /statistics/orders

AC-2: Filtry dzialaja zgodnie z wymaganiami

Given uzytkownik otworzy /statistics/orders
When nie poda filtrow
Then domyslnie widzi zakres dat obejmujacy biezacy miesiac
And domyslnie zaznaczone sa wszystkie grupy statusow poza "anulowane"
And domyslnie zaznaczone sa wszystkie kanaly (allegro + wszystkie shopPRO)

When ustawi date od/do przez pola typu date
Then tabela zawiera tylko dni i zamowienia z wybranego zakresu

When wybierze podzbior kanalow sprzedazy (multiselect)
Then tabela pokazuje tylko wybrane kanaly i przelicza sumy tylko dla nich

When wybierze podzbior grup statusow (multiselect)
Then do agregacji wchodza tylko zamowienia o statusach nalezacych do wybranych grup

AC-3: Tabela dzienna z rozbiciem kanalowym i podsumowaniem

Given filtry sa poprawne
When backend zwroci dane statystyk
Then widok pokazuje tabele z kolumna "Dzien"
And dla kazdego wybranego kanalu pokazuje 3 metryki: ilosc zamowien, kwota netto, kwota brutto
And na dole tabeli widoczny jest wiersz "Razem" sumujacy wszystkie dni
And kwoty sa formatowane do 2 miejsc po przecinku

AC-4: Rozbicie kanalow zgodne z modelem danych

Given zamowienia allegro pochodza z source='allegro'
When generujemy statystyki
Then wszystkie zamowienia allegro trafiaja do jednego kanalu "Allegro"

Given zamowienia shopPRO maja source='shoppro' i integration_id
When generujemy statystyki
Then kazda integracja shopPRO jest liczona jako osobny kanal
And naglowek kolumny pokazuje nazwe integracji z tabeli integrations

</acceptance_criteria>

Task 1: Backend statystyk (controller + repository + route) src/Modules/Statistics/OrdersStatisticsController.php, src/Modules/Statistics/OrdersStatisticsRepository.php, routes/web.php 1. Dodac nowy modul `Statistics` z klasami: - `OrdersStatisticsController` (parsowanie filtrow, walidacja, budowa view-modelu). - `OrdersStatisticsRepository` (agregacje SQL przez prepared statements). 2. W `routes/web.php`: - Zainicjalizowac controller (analogicznie do pozostalych modulow). - Dodac route `GET /statistics/orders` za `AuthMiddleware`. 3. Implementacja filtrow: - Daty: `date_from`, `date_to` (format `YYYY-MM-DD`, fallback: pierwszy i ostatni dzien biezacego miesiaca). - Kanaly (multiselect): `channels[]` (np. `allegro`, `shoppro:12`). - Grupy statusow (multiselect): `status_groups[]` (id grup). - Domyslnie wybierz wszystkie grupy poza grupa, ktorej nazwa po normalizacji to `anulowane`. 4. Implementacja agregacji: - Dzien: `DATE(COALESCE(o.ordered_at, o.source_created_at, o.source_updated_at, o.fetched_at))`. - Kanal: - `allegro` gdy `o.source = 'allegro'` - `shoppro:{integration_id}` gdy `o.source = 'shoppro'` - Metryki: - `orders_count = COUNT(*)` - `total_net = SUM(COALESCE(o.total_net, o.total_without_tax, 0))` - `total_gross = SUM(COALESCE(o.total_with_tax, 0))` - Filtr statusow przez mapowanie grupa -> lista `order_statuses.code`, porownanie do efektywnego statusu (zachowac zgodnosc z logika Allegro mapowania stosowana w OrdersRepository). 5. Zwracany model musi zawierac: - liste dni, - liste aktywnych kanalow, - dane tabeli per dzien/per kanal, - sumy koncowe per kanal i globalnie.

Avoid: nie dokladac migracji DB; nie wprowadzac SQL skladanego stringami z danymi usera; wszystkie parametry bindowac przez prepared statements.

- `php -l src/Modules/Statistics/OrdersStatisticsController.php` - `php -l src/Modules/Statistics/OrdersStatisticsRepository.php` - Wejscie na `/statistics/orders` zwraca HTTP 200 i nie rzuca exception. AC-2 i AC-4 spelnione na warstwie backend. Task 2: UI strony statystyk + menu + tlumaczenia resources/views/layouts/app.php, resources/views/statistics/orders.php, resources/lang/pl.php, resources/scss/app.scss 1. W sidebarze dodac nowa grupe: - `Statystyki` jako menu glowne, - podpozycja `Zamowienia` linkujaca do `/statistics/orders`, - aktywny stan oparty o `activeMenu='statistics'` i `activeStatistics='orders'`. 2. W `resources/lang/pl.php` dodac klucze: - `navigation.statistics`, - `navigation.statistics_orders`, - sekcje `statistics.orders.*` (tytul, opisy, etykiety filtrow, nazwy kolumn, pusty stan, razem). 3. Stworzyc widok `resources/views/statistics/orders.php`: - karta z formularzem filtrow (2 pola `date`, multiselect kanalow, multiselect grup statusow), - tabela: kolumna `Dzien`, dynamiczne grupy kolumn kanalowych (`Ilosc`, `Netto`, `Brutto`), stopka `Razem`. - escape danych helperem `$e`. 4. Multiselect: - bez dodawania nowych zaleznosci JS; zastosowac natywne `select multiple` + kompaktowy CSS. - nazwy inputow: `channels[]`, `status_groups[]`. 5. Style: - dopisac sekcje SCSS do `resources/scss/app.scss` dla kompaktowego layoutu filtrow i tabeli statystyk. - nie dodawac CSS inline w widoku.

Avoid: nie uzywac natywnych `alert()`/`confirm()`; brak logiki biznesowej w widoku.

- Po wejściu na dowolna strone menu widzi `Statystyki -> Zamowienia`. - `/statistics/orders` pokazuje formularz filtrow i tabele/empty-state bez bledow. - `npm run build` (lub projektowy build assets) generuje aktualny CSS bez bledow. AC-1 i AC-3 spelnione na warstwie UI. Task 3: Dokumentacja techniczna po wdrozeniu .paul/docs/ARCHITECTURE.md, .paul/docs/TECH_CHANGELOG.md 1. Zaktualizowac `.paul/docs/ARCHITECTURE.md`: - dodac modul `Statistics` i opis nowych klas/metod oraz przeplywu danych. - opisac nowy endpoint `/statistics/orders`. 2. Zaktualizowac `.paul/docs/TECH_CHANGELOG.md`: - wpis z data wdrozenia, zakresem funkcji i uzasadnieniem biznesowym. 3. Poniewaz zmiana nie modyfikuje schematu DB: - w changelogu jasno zaznaczyc brak zmian migracyjnych.

Avoid: nie pomijac dokumentacji, bo to trwale wymaganie projektowe.

- `git diff -- .paul/docs/ARCHITECTURE.md .paul/docs/TECH_CHANGELOG.md` pokazuje oczekiwane wpisy. Dokumentacja projektu zgodna z wymaganiami utrwalania zmian.

DO NOT CHANGE

• Moduly importu/synchronizacji (Allegro/shopPRO) - brak zmian logiki importu.
• Istniejace endpointy /orders/* i ich kontrakty.
• Struktura tabel DB i migracje.

SCOPE LIMITS

• Zakres obejmuje tylko statystyki zamowien (bez produktow, magazynu, paragonow).
• Brak eksportu CSV/XLSX w tej fazie.
• Brak cache materializowanego; agregacja wykonywana bezposrednio na zapytaniach SQL.
• Brak nowego API publicznego JSON - tylko widok HTML panelu.

Before declaring plan complete: - [ ] `php -l` dla nowych klas Statistics. - [ ] Manualne UAT filtrow: data, kanaly multiselect, grupy statusow multiselect. - [ ] UAT domyslnego filtra grup statusow (wszystkie poza `anulowane`). - [ ] UAT podsumowania: wiersz `Razem` zgodny z suma dziennych wierszy. - [ ] Aktualizacja `.paul/docs/ARCHITECTURE.md` i `.paul/docs/TECH_CHANGELOG.md`. - [ ] `sonar-scanner` uruchomiony po APPLY (wymog SPECIAL-FLOWS).

<success_criteria>

• Uzytkownik ma nowa pozycje menu Statystyki -> Zamowienia.
• Widok zwraca dzienne podsumowanie z rozbiciem: Allegro + kazdy shopPRO osobno.
• Filtry dzialaja: zakres dat, kanaly multiselect, grupy statusow multiselect.
• Domyslne grupy statusow wykluczaja anulowane.
• Wiersz Razem poprawnie sumuje tabele. </success_criteria>

After completion, create `.paul/phases/105-orders-statistics/105-01-SUMMARY.md`