258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
---
|
|
phase: 105-orders-statistics
|
|
plan: 01
|
|
type: execute
|
|
wave: 1
|
|
depends_on: []
|
|
files_modified:
|
|
- 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
|
|
autonomous: true
|
|
delegation: auto
|
|
---
|
|
|
|
<objective>
|
|
## 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.
|
|
</objective>
|
|
|
|
<context>
|
|
## 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
|
|
</context>
|
|
|
|
<skills>
|
|
## 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
|
|
</skills>
|
|
|
|
<acceptance_criteria>
|
|
|
|
## AC-1: Nowa pozycja menu i routing statystyk
|
|
```gherkin
|
|
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
|
|
```gherkin
|
|
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
|
|
```gherkin
|
|
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
|
|
```gherkin
|
|
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>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Backend statystyk (controller + repository + route)</name>
|
|
<files>src/Modules/Statistics/OrdersStatisticsController.php, src/Modules/Statistics/OrdersStatisticsRepository.php, routes/web.php</files>
|
|
<action>
|
|
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.
|
|
</action>
|
|
<verify>
|
|
- `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.
|
|
</verify>
|
|
<done>AC-2 i AC-4 spelnione na warstwie backend.</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 2: UI strony statystyk + menu + tlumaczenia</name>
|
|
<files>resources/views/layouts/app.php, resources/views/statistics/orders.php, resources/lang/pl.php, resources/scss/app.scss</files>
|
|
<action>
|
|
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.
|
|
</action>
|
|
<verify>
|
|
- 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.
|
|
</verify>
|
|
<done>AC-1 i AC-3 spelnione na warstwie UI.</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 3: Dokumentacja techniczna po wdrozeniu</name>
|
|
<files>.paul/docs/ARCHITECTURE.md, .paul/docs/TECH_CHANGELOG.md</files>
|
|
<action>
|
|
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.
|
|
</action>
|
|
<verify>
|
|
- `git diff -- .paul/docs/ARCHITECTURE.md .paul/docs/TECH_CHANGELOG.md` pokazuje oczekiwane wpisy.
|
|
</verify>
|
|
<done>Dokumentacja projektu zgodna z wymaganiami utrwalania zmian.</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<boundaries>
|
|
|
|
## 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.
|
|
</boundaries>
|
|
|
|
<verification>
|
|
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).
|
|
</verification>
|
|
|
|
<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>
|
|
|
|
<output>
|
|
After completion, create `.paul/phases/105-orders-statistics/105-01-SUMMARY.md`
|
|
</output>
|
|
|