---
phase: 04-products-aggregate-breakdown
plan: 01
subsystem: ui
tags: [products, datatables, aggregation, breakdown, php, jquery]

requires:
  - phase: 03-products-all-campaigns-view
    provides: stable products scope filters and all-campaign selector behavior

provides:
  - Aggregated product rows (1 product = 1 row when no ad group is selected)
  - Expandable campaign/ad-group breakdown rows with full metrics
  - Edit actions kept only on the main product row

affects:
  - products table data contract from /products/get_products/
  - products DataTable row rendering and child-row behavior

tech-stack:
  added: []
  patterns:
    - aggregate main row + readonly scope breakdown in child row

key-files:
  created: []
  modified:
    - autoload/factory/class.Products.php
    - autoload/controls/class.Products.php
    - templates/products/main_view.php

key-decisions:
  - "Use one batch breakdown query for page product IDs to avoid N+1"
  - "Expose breakdown as row_meta in DataTables payload"
  - "Keep inline edit fields only in parent row"

patterns-established:
  - "When scope is not narrowed to ad_group_id, aggregate per product and show scope details on demand"

duration: ~23min
started: 2026-04-25T17:05:05+02:00
completed: 2026-04-25T17:28:08+02:00
---

# Phase 4 Plan 01: Products Aggregate Breakdown (Summary)

**Na /products wdrozono model: glowny agregat per produkt + rozwijane readonly podwiersze kampania/grupa z pelnymi metrykami.**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~23 min |
| Started | 2026-04-25T17:05:05+02:00 |
| Completed | 2026-04-25T17:28:08+02:00 |
| Tasks | 4/4 (3 auto + 1 human-verify) |
| Files modified | 3 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Agregacja produktu bez wybranej grupy | Pass | Backend grupuje po `p.id`, recordsTotal liczy DISTINCT produktow |
| AC-2: Rozwijane podwiersze z pelnym rozbiciem | Pass | Child-row DataTables renderuje pelny zestaw metryk per kampania+grupa |
| AC-3: Edycja tylko w wierszu glownym | Pass | Podwiersze sa readonly; inputy i akcje zostaja w parent row |
| AC-4: Brak regresji filtrowania/listy | Pass | User checkpoint `approved`; endpoint i lintery bez bledow |

## Accomplishments

- Przebudowano zapytania listy produktow tak, aby glowny wynik byl agregowany per produkt.
- Dodano zbiorcze pobieranie breakdownu scope dla aktualnej strony (bez N+1).
- Rozszerzono payload DataTables o `row_meta.breakdown_rows` i dodano UI rozwin/zwin z tabela szczegolow.

## Task Commits

Brak commitu fazowego na tym etapie (working tree zawiera rowniez inne lokalne zmiany projektu).

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `autoload/factory/class.Products.php` | Modified (+148/-101) | Agregacja per produkt, wspolny filtr, breakdown query, records count |
| `autoload/controls/class.Products.php` | Modified (+53/-19) | Dolaczenie breakdownu do odpowiedzi i row_meta dla DataTables |
| `templates/products/main_view.php` | Modified (+162/-1) | UI toggle, child-row render, style breakdownu |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| Batch breakdown query for page products | Ogranicza obciazenie DB i unika N+1 | Stabilna wydajnosc przy paginacji |
| Keep edit controls only in parent row | Zgodnosc z wymaganiem usera | Jasny podzial: edycja vs analiza |
| Render breakdown in DataTables child row | Minimalny blast radius dla istniejacego ukladu kolumn | Niska regresyjnosc UI |

## Deviations from Plan

### Summary

| Type | Count | Impact |
|------|-------|--------|
| Auto-fixed | 1 | Niski, bez zmiany zakresu |
| Scope additions | 0 | Brak |
| Deferred | 0 | Brak |

**Total impact:** Plan zrealizowany zgodnie z zakresem; jedna techniczna korekta podczas implementacji.

### Auto-fixed Issues

1. Tymczasowe uszkodzenie pliku kontrolera podczas edycji skryptowej
- Found during: Task 2
- Issue: `autoload/controls/class.Products.php` zostal chwilowo uszkodzony (parse error)
- Fix: przywrocenie pliku z HEAD i ponowne, punktowe patche
- Verification: `php -l autoload/controls/class.Products.php` OK

### Deferred Items

Brak.

## Issues Encountered

| Issue | Resolution |
|-------|------------|
| Konflikty przy automatycznej podmianie wiekszego bloku kontrolera | Zmiana strategii na male, precyzyjne patche i ponowna walidacja |

## Next Phase Readiness

**Ready:**
- Kontrakt endpointu `/products/get_products/` obsluguje agregat + breakdown.
- UI listy wspiera drill-down bez naruszania obecnych akcji.

**Concerns:**
- W working tree sa tez niezalezne lokalne zmiany (`.vscode/ftp-kr.sync.cache.json`).

**Blockers:**
- Brak.

---
*Phase: 04-products-aggregate-breakdown, Plan: 01*
*Completed: 2026-04-25*