orderPRO/.paul/phases/110-statistics-summary/110-01-PLAN.md

---
phase: 110-statistics-summary
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/summary.php
  - resources/lang/pl.php
  - public/assets/js/modules/statistics-summary-charts.js
  - resources/scss/app.scss
  - public/assets/css/app.css
  - DOCS/ARCHITECTURE.md
  - DOCS/DB_SCHEMA.md
  - DOCS/TECH_CHANGELOG.md
  - .paul/codebase/architecture.md
  - .paul/codebase/db_schema.md
  - .paul/codebase/tech_changelog.md
autonomous: false
delegation: off
---

<objective>
## Goal
Add a new first submenu item `Statystyki -> Podsumowanie` with two monthly line charts:
- monthly order count per integration plus a total line,
- monthly order value per integration plus a total line.

## Purpose
The operator needs a quick trend view before opening detailed daily order statistics. The summary should show how each sales integration contributes month by month and how the total business volume changes over time.

## Output
- New authenticated endpoint `/statistics/summary`.
- Sidebar order: `Podsumowanie` first, existing `Zamowienia` second.
- New summary view with compact filters and two charts.
- Backend monthly aggregation using existing orders data, grouped by integration/channel.
- Technical documentation updates. No database migration is expected.
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
@AGENTS.md
@.paul/codebase/architecture.md
@.paul/codebase/db_schema.md

## Prior Work
@.paul/phases/105-orders-statistics/105-01-SUMMARY.md
@.paul/phases/109-checkbox-multiselect-filters/109-01-SUMMARY.md

## Source Files
@src/Modules/Statistics/OrdersStatisticsController.php
@src/Modules/Statistics/OrdersStatisticsRepository.php
@resources/views/statistics/orders.php
@resources/views/layouts/app.php
@routes/web.php
@resources/lang/pl.php
@resources/scss/app.scss
@package.json

## Notes
- `DOCS/DB_SCHEMA.md` and `DOCS/ARCHITECTURE.md` are required by `AGENTS.md`, but they are currently missing in the repo. APPLY should create them or reconcile them from `.paul/codebase/*` before documenting this feature.
- Existing statistics code already has filter parsing patterns, channel labels, status group defaults, collation handling, and amount fallback logic. Reuse those rather than creating a separate query style.
- `SPECIAL-FLOWS.md` requires `sonar-scanner` after APPLY and before UNIFY; frontend-design is optional for this UI work.
</context>

<skills>
## Required Skills (from SPECIAL-FLOWS.md)

| Skill | Priority | When to Invoke | Loaded? |
|-------|----------|----------------|---------|
| sonar-scanner | required | After APPLY, before UNIFY | o |
| /frontend-design | optional | During chart UI implementation/review | o |

**BLOCKING:** `sonar-scanner` must be run before UNIFY unless the environment blocks it.
</skills>

<acceptance_criteria>

## AC-1: Sidebar Navigation
```gherkin
Given the user is authenticated
When the sidebar statistics section is visible
Then the first item under "Statystyki" is "Podsumowanie"
And the second item remains "Zamowienia"
And clicking "Podsumowanie" opens `/statistics/summary`
And the active state highlights "Podsumowanie" on that page
```

## AC-2: Monthly Order Count Chart
```gherkin
Given orders exist across multiple months and integrations
When the user opens `/statistics/summary`
Then the page shows an order count chart grouped by month
And each integration has its own line
And an additional "Razem" line sums all selected integrations per month
```

## AC-3: Monthly Order Value Chart
```gherkin
Given orders exist across multiple months and integrations
When the user opens `/statistics/summary`
Then the page shows an order value chart grouped by month
And each integration has its own line
And an additional "Razem" line sums all selected integrations per month
And values are displayed as money with two decimal places
```

## AC-4: Existing Statistics Semantics Reused
```gherkin
Given the user changes the date range, channel selection, or status group selection
When the summary page reloads
Then both charts use the same selected filters
And channel labels match existing statistics labels
And default status groups still exclude the cancelled group
```

## AC-5: Empty and Degraded States
```gherkin
Given the selected filters return no orders
When the user opens `/statistics/summary`
Then the page shows a clear empty state instead of broken charts

Given JavaScript fails to load
When the user opens `/statistics/summary`
Then the monthly data remains visible in an HTML table fallback
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Add monthly statistics backend and route</name>
  <files>src/Modules/Statistics/OrdersStatisticsController.php, src/Modules/Statistics/OrdersStatisticsRepository.php, routes/web.php</files>
  <action>
    Extend the existing Statistics module with a new summary action:
    - Add `summary(Request $request): Response` to `OrdersStatisticsController`.
    - Reuse or extract existing filter helpers for date range, channel options, selected channels, status groups, selected status groups, and status-code resolution.
    - Use a useful monthly default range: first day of January of the current year through the current date, unless GET filters are supplied.
    - Add repository method `aggregateByMonth(string $dateFrom, string $dateTo, array $channels, array $statusCodes): array`.
    - The query must reuse the existing effective date, channel, gross amount, and status SQL semantics from `aggregateByDay()`.
    - Group rows by `DATE_FORMAT(effective_date, "%Y-%m")` and channel key.
    - Build a controller view-model with ordered month labels, per-channel count series, per-channel value series, and total series for both charts.
    - Add route `GET /statistics/summary` behind `AuthMiddleware` using the existing controller instance.

    Avoid: no schema changes, no raw user input in SQL strings, no duplicate channel/status logic that can drift from `/statistics/orders`.
  </action>
  <verify>
    - `php -l src/Modules/Statistics/OrdersStatisticsController.php`
    - `php -l src/Modules/Statistics/OrdersStatisticsRepository.php`
    - `php -l routes/web.php`
    - Manual check that `/statistics/summary` returns HTTP 200 for an authenticated session.
  </verify>
  <done>AC-2, AC-3, and AC-4 satisfied at backend/view-model level.</done>
</task>

<task type="auto">
  <name>Task 2: Add summary UI, charts, menu item, and translations</name>
  <files>resources/views/layouts/app.php, resources/views/statistics/summary.php, resources/lang/pl.php, public/assets/js/modules/statistics-summary-charts.js, resources/scss/app.scss, public/assets/css/app.css</files>
  <action>
    Create the visible statistics summary experience:
    - Add `Podsumowanie` translation keys under navigation and `statistics.summary.*`.
    - In the sidebar statistics group, place `Podsumowanie` before `Zamowienia`, link it to `/statistics/summary`, and use `activeStatistics='summary'`.
    - Create `resources/views/statistics/summary.php` with compact filters matching `/statistics/orders`: date from/to, channels multiselect, status groups multiselect, submit/reset actions.
    - Render two chart panels: order count and order value. Each panel must include a `<canvas>` or SVG/chart container plus a table fallback with monthly rows and per-series columns.
    - Add `public/assets/js/modules/statistics-summary-charts.js` to render the two charts from JSON embedded in the page after escaping through `json_encode(..., JSON_HEX_*)`.
    - Keep chart rendering small and local. Do not add a package dependency unless implementation discovers existing project-approved chart tooling.
    - Include the module in `resources/views/layouts/app.php` with `filemtime()` cache busting.
    - Add compact SCSS in `resources/scss/app.scss`, then build `public/assets/css/app.css` with `npm run build:css`.

    Avoid: no inline CSS in PHP views, no native `alert()`/`confirm()`, no decorative oversized dashboard layout. The page should stay dense and operational.
  </action>
  <verify>
    - `php -l resources/views/layouts/app.php`
    - `php -l resources/views/statistics/summary.php`
    - `php -l resources/lang/pl.php`
    - `npm run build:css`
    - Browser/manual check confirms two non-empty charts render when data exists and fallback tables are present in the DOM.
  </verify>
  <done>AC-1, AC-2, AC-3, and AC-5 satisfied at UI level.</done>
</task>

<task type="auto">
  <name>Task 3: Update technical documentation</name>
  <files>DOCS/ARCHITECTURE.md, DOCS/DB_SCHEMA.md, DOCS/TECH_CHANGELOG.md, .paul/codebase/architecture.md, .paul/codebase/db_schema.md, .paul/codebase/tech_changelog.md</files>
  <action>
    Update documentation required by `AGENTS.md` and PAUL:
    - If root `DOCS/` files are still missing, create `DOCS/ARCHITECTURE.md`, `DOCS/DB_SCHEMA.md`, and `DOCS/TECH_CHANGELOG.md` using the current `.paul/codebase/*` documents as the baseline where appropriate.
    - Document the new `/statistics/summary` route, controller action, repository monthly aggregation method, chart frontend module, and sidebar change in architecture docs.
    - Document that the feature uses existing `orders`, `integrations`, `order_status_groups`, and `order_statuses` tables without migration changes.
    - Add a dated technical changelog entry explaining the new summary charts and why no DB schema change was needed.
    - Keep `.paul/codebase/*` in sync with the same architecture/schema/changelog facts.
  </action>
  <verify>
    - `git diff -- DOCS .paul/codebase` shows architecture/changelog updates and no false DB migration claim.
    - Documentation mentions `/statistics/summary`, `aggregateByMonth()`, and `statistics-summary-charts.js`.
  </verify>
  <done>Documentation requirements from `AGENTS.md` and PAUL are satisfied.</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>`Statystyki -> Podsumowanie` with two monthly charts</what-built>
  <how-to-verify>
    1. Open `/statistics/summary`.
    2. Confirm the sidebar shows `Podsumowanie` as the first item under `Statystyki`.
    3. Confirm chart 1 shows monthly order counts with one line per integration plus `Razem`.
    4. Confirm chart 2 shows monthly order values with one line per integration plus `Razem`.
    5. Change filters and confirm both charts update consistently.
  </how-to-verify>
  <resume-signal>Type "approved" to continue to UNIFY, or describe visual/data issues to fix.</resume-signal>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- Import/synchronization modules for Allegro/shopPRO.
- Existing `/statistics/orders` route contract and GET parameter names.
- Database migrations unless a blocker proves the existing schema cannot support the charts.
- Runtime DB env behavior: do not wire `DB_HOST_REMOTE` into application runtime.

## SCOPE LIMITS
- This plan adds only summary charts for orders. It does not add exports, product charts, inventory charts, or accounting reports.
- Values chart uses the existing gross amount semantics from current order statistics unless the user explicitly asks for net values.
- Chart interactivity is limited to readable lines/legend/tooltips if implemented locally; advanced drill-down is out of scope.
- No new native alerts or confirms.

</boundaries>

<verification>
Before declaring plan complete:
- [ ] `php -l src/Modules/Statistics/OrdersStatisticsController.php`
- [ ] `php -l src/Modules/Statistics/OrdersStatisticsRepository.php`
- [ ] `php -l routes/web.php`
- [ ] `php -l resources/views/layouts/app.php`
- [ ] `php -l resources/views/statistics/summary.php`
- [ ] `php -l resources/lang/pl.php`
- [ ] `npm run build:css`
- [ ] Manual/browser check: `/statistics/summary` renders two charts and table fallbacks.
- [ ] Manual/browser check: sidebar order and active states are correct.
- [ ] Manual data check: monthly total equals sum of integration values for at least one month.
- [ ] Documentation updated in `DOCS/` and `.paul/codebase/`.
- [ ] `sonar-scanner` run before UNIFY, or blocker recorded if unavailable.
- [ ] All acceptance criteria met.
</verification>

<success_criteria>
- `Statystyki -> Podsumowanie` is the first statistics submenu item.
- `/statistics/summary` displays two monthly charts: order count and order value.
- Each chart includes separate integration series and a `Razem` series.
- Filters are consistent with existing order statistics behavior.
- No database schema change is introduced.
- Technical documentation is updated.
</success_criteria>

<output>
After completion, create `.paul/phases/110-statistics-summary/110-01-SUMMARY.md`.
</output>