Jacek Pyziak
0b4ffb7146
Phase 110 complete: - add Statistics -> Podsumowanie page - add monthly order count and value charts per integration plus total - use Chart.js with table fallback and 04-2026 default history start - update PAUL and DOCS technical documentation
198 lines
9.5 KiB
Markdown
198 lines
9.5 KiB
Markdown
---
|
|
phase: 110-statistics-summary
|
|
plan: 01
|
|
subsystem: statistics
|
|
tags: [statistics, charts, chartjs, monthly-summary, ui, reporting]
|
|
requires:
|
|
- phase: 105-orders-statistics
|
|
provides: daily statistics filters, channel semantics, status group filtering
|
|
- phase: 109-checkbox-multiselect-filters
|
|
provides: reusable checkbox multiselect filter enhancement
|
|
provides:
|
|
- /statistics/summary monthly summary page
|
|
- monthly order count chart per integration plus total
|
|
- monthly order value chart per integration plus total
|
|
- DOCS baseline synchronized from .paul/codebase
|
|
affects: [statistics, reporting, sidebar-navigation]
|
|
tech-stack:
|
|
added: [Chart.js 4.4.8 CDN]
|
|
patterns: [monthly statistics aggregation, Chart.js view-model, table fallback]
|
|
key-files:
|
|
created:
|
|
- resources/views/statistics/summary.php
|
|
- public/assets/js/modules/statistics-summary-charts.js
|
|
- DOCS/ARCHITECTURE.md
|
|
- DOCS/DB_SCHEMA.md
|
|
- DOCS/TECH_CHANGELOG.md
|
|
modified:
|
|
- src/Modules/Statistics/OrdersStatisticsController.php
|
|
- src/Modules/Statistics/OrdersStatisticsRepository.php
|
|
- routes/web.php
|
|
- resources/views/layouts/app.php
|
|
- resources/lang/pl.php
|
|
- resources/scss/app.scss
|
|
- public/assets/css/app.css
|
|
key-decisions:
|
|
- "Default summary history starts at 2026-04-01 even if older orders exist."
|
|
- "Charts use Chart.js 4.4.8 from CDN for interactive legend and tooltips."
|
|
- "Gross order value uses existing statistics gross amount semantics."
|
|
patterns-established:
|
|
- "Monthly statistics use the same channel/status/effective-date helpers as daily statistics."
|
|
- "Charts are backed by HTML table fallbacks."
|
|
duration: ~90min
|
|
started: 2026-04-28T22:20:00+02:00
|
|
completed: 2026-04-28T23:50:00+02:00
|
|
---
|
|
|
|
# Phase 110 Plan 01: Statistics Summary
|
|
|
|
Monthly statistics summary shipped with two interactive Chart.js line charts, compact filters, per-integration series, total series, and table fallbacks.
|
|
|
|
## Performance
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| Duration | ~90min |
|
|
| Started | 2026-04-28T22:20:00+02:00 |
|
|
| Completed | 2026-04-28T23:50:00+02:00 |
|
|
| Tasks | 3 auto tasks + 1 human verification checkpoint |
|
|
| Files modified | 18 |
|
|
|
|
## Acceptance Criteria Results
|
|
|
|
| Criterion | Status | Notes |
|
|
|-----------|--------|-------|
|
|
| AC-1: Sidebar Navigation | Pass | `Podsumowanie` added first under `Statystyki`; `/statistics/summary` route registered with active state. |
|
|
| AC-2: Monthly Order Count Chart | Pass | Count chart model contains one dataset per selected integration plus `Razem`; rendered by Chart.js. |
|
|
| AC-3: Monthly Order Value Chart | Pass | Value chart model contains one dataset per selected integration plus `Razem`; values formatted as money in tooltips/table. |
|
|
| AC-4: Existing Statistics Semantics Reused | Pass | Controller reuses channel/status filter flow; repository reuses effective date/channel/status/gross SQL helpers. |
|
|
| AC-5: Empty and Degraded States | Pass | Empty state shown when no data; tables remain visible as fallback below charts. |
|
|
|
|
## Accomplishments
|
|
|
|
- Added authenticated `/statistics/summary` page with monthly order count and order gross value charts.
|
|
- Added `OrdersStatisticsRepository::aggregateByMonth()` using prepared parameters and existing statistics SQL helper semantics.
|
|
- Added `OrdersStatisticsController::summary()` and a chart/table view-model with total lines.
|
|
- Updated sidebar navigation, translations, SCSS, compiled CSS, and Chart.js frontend module.
|
|
- Created root `DOCS/` technical documentation required by `AGENTS.md` and synchronized it with `.paul/codebase/`.
|
|
|
|
## Task Commits
|
|
|
|
Task-level atomic commits were not used in this inline APPLY. A single phase commit is created during transition.
|
|
|
|
| Task | Commit | Type | Description |
|
|
|------|--------|------|-------------|
|
|
| Task 1: Add monthly statistics backend and route | phase commit | feat | Controller summary action, monthly aggregation, `/statistics/summary` route |
|
|
| Task 2: Add summary UI, charts, menu item, and translations | phase commit | feat | Summary view, sidebar link, Chart.js charts, SCSS/CSS |
|
|
| Task 3: Update technical documentation | phase commit | docs | `DOCS/` and `.paul/codebase/` updates |
|
|
|
|
## Files Created/Modified
|
|
|
|
| File | Change | Purpose |
|
|
|------|--------|---------|
|
|
| `src/Modules/Statistics/OrdersStatisticsController.php` | Modified | Added summary action, monthly default range from `2026-04-01`, chart/table view-model builders. |
|
|
| `src/Modules/Statistics/OrdersStatisticsRepository.php` | Modified | Added `aggregateByMonth()` with existing statistics SQL semantics. |
|
|
| `routes/web.php` | Modified | Registered authenticated `GET /statistics/summary`. |
|
|
| `resources/views/layouts/app.php` | Modified | Added `Podsumowanie` sidebar link and Chart.js/module scripts. |
|
|
| `resources/views/statistics/summary.php` | Created | Summary filters, two charts, and two fallback tables. |
|
|
| `resources/lang/pl.php` | Modified | Added navigation and `statistics.summary.*` translations. |
|
|
| `public/assets/js/modules/statistics-summary-charts.js` | Created | Chart.js renderer for count/value line charts. |
|
|
| `resources/scss/app.scss` | Modified | Added compact two-column desktop layout and chart/table styles. |
|
|
| `public/assets/css/app.css` | Modified | Compiled CSS output. |
|
|
| `DOCS/ARCHITECTURE.md` | Created | Root architecture docs baseline plus summary feature. |
|
|
| `DOCS/DB_SCHEMA.md` | Created | Root schema docs baseline plus reporting usage note. |
|
|
| `DOCS/TECH_CHANGELOG.md` | Created | Root technical changelog baseline plus phase 110 entry. |
|
|
| `.paul/codebase/architecture.md` | Modified | Documented route, controller flow, Chart.js module. |
|
|
| `.paul/codebase/db_schema.md` | Modified | Documented no-migration reporting usage. |
|
|
| `.paul/codebase/tech_changelog.md` | Modified | Added phase 110 technical changelog. |
|
|
|
|
## Decisions Made
|
|
|
|
| Decision | Rationale | Impact |
|
|
|----------|-----------|--------|
|
|
| Start history at `2026-04-01` | User requested `04-2026` as hard start despite older data. | Default summary excludes older months unless code changes later. |
|
|
| Use Chart.js 4.4.8 CDN | User requested an interactive JS library; project already uses CDN for Quill. | No npm dependency or build pipeline change. |
|
|
| Use gross order values | Existing statistics gross semantics are stable and already documented. | Value chart matches current order statistics totals. |
|
|
| Keep table fallback | Required degraded state and useful for verification. | Data remains visible without Chart.js/JS. |
|
|
|
|
## Deviations from Plan
|
|
|
|
| Type | Count | Impact |
|
|
|------|-------|--------|
|
|
| Scope adjustments from user feedback | 3 | Improved UI and changed default date semantics. |
|
|
| Environment blockers | 3 | Verification limits only; code/build checks passed. |
|
|
|
|
**Total impact:** Controlled deviations; feature outcome matches latest user request.
|
|
|
|
### Adjusted During APPLY
|
|
|
|
**Chart renderer changed to Chart.js**
|
|
- Found during user feedback after APPLY.
|
|
- Fix: Added Chart.js CDN and rewrote `statistics-summary-charts.js` to use Chart.js legends/tooltips.
|
|
- Verification: `node --check`, PHP lint, CSS build, Sonar scan.
|
|
|
|
**Desktop layout split**
|
|
- Found during user feedback after APPLY.
|
|
- Fix: Added two-column chart grid and two-column table grid from 1100px.
|
|
- Verification: PHP lint and CSS build.
|
|
|
|
**Default history start**
|
|
- Found during user feedback after APPLY.
|
|
- Fix: Set summary default `date_from` to `2026-04-01`.
|
|
- Verification: PHP lint.
|
|
|
|
### Deferred Items
|
|
|
|
- SonarQube issue import into `DOCS/todo.md` was not performed because no SonarQube MCP resources/tools are available in this Codex session.
|
|
- Full authenticated HTTP verification was not possible locally because MySQL/XAMPP refused the DB connection.
|
|
- PHPUnit was not run because `composer` is not available in PATH and `vendor/` is absent.
|
|
|
|
## Issues Encountered
|
|
|
|
| Issue | Resolution |
|
|
|-------|------------|
|
|
| Local bootstrap failed with MySQL connection refused. | Started PHP dev server anyway; documented DB blocker. |
|
|
| `composer test` unavailable. | Documented test blocker; ran available lint/build/static checks. |
|
|
| Sonar MCP unavailable. | Ran `sonar-scanner` successfully and documented inability to fetch issue details. |
|
|
|
|
## Verification Results
|
|
|
|
| Check | Result |
|
|
|-------|--------|
|
|
| `php -l src/Modules/Statistics/OrdersStatisticsController.php` | Pass |
|
|
| `php -l src/Modules/Statistics/OrdersStatisticsRepository.php` | Pass |
|
|
| `php -l routes/web.php` | Pass |
|
|
| `php -l resources/views/layouts/app.php` | Pass |
|
|
| `php -l resources/views/statistics/summary.php` | Pass |
|
|
| `php -l resources/lang/pl.php` | Pass |
|
|
| `node --check public/assets/js/modules/statistics-summary-charts.js` | Pass |
|
|
| `npm run build:css` | Pass |
|
|
| `sonar-scanner` | Pass; report uploaded to SonarQube |
|
|
| Local `/statistics/summary` HTTP 200 | Blocked by local MySQL connection refused |
|
|
| `composer test` / PHPUnit | Blocked: `composer` not in PATH and `vendor/` absent |
|
|
|
|
## Skill Audit
|
|
|
|
| Expected | Invoked | Notes |
|
|
|----------|---------|-------|
|
|
| `sonar-scanner` | yes | Ran successfully after APPLY changes. |
|
|
|
|
## Next Phase Readiness
|
|
|
|
**Ready:**
|
|
- Statistics summary page exists and is wired into sidebar navigation.
|
|
- Monthly aggregation pattern can be reused for future reporting charts.
|
|
- Root `DOCS/` docs now exist for future AGENTS.md-compliant changes.
|
|
|
|
**Concerns:**
|
|
- Chart.js is CDN-based; if offline operation becomes required, vendor locally or add npm build support.
|
|
- Local verification depends on XAMPP/MySQL being available.
|
|
- Sonar issue import still needs a working SonarQube MCP/tool path.
|
|
|
|
**Blockers:**
|
|
- None for closing Phase 110.
|
|
|
|
---
|
|
*Phase: 110-statistics-summary, Plan: 01*
|
|
*Completed: 2026-04-28*
|