diff --git a/.paul/PROJECT.md b/.paul/PROJECT.md new file mode 100644 index 0000000..f52621f --- /dev/null +++ b/.paul/PROJECT.md @@ -0,0 +1,35 @@ +# Project: bilety.brzezovka.pl + +## Description +Aplikacja webowa do sprzedazy biletow online z obsluga zamowien, platnosci i komunikacji potransakcyjnej. + +## Core Value +Uzytkownicy moga szybko i bezpiecznie kupic bilety online oraz otrzymac natychmiastowe potwierdzenie zakupu. + +## Requirements + +### Must Have +- [x] Obsluga zakupu biletow end-to-end (wybor, checkout, finalizacja) +- [x] Poprawne rejestrowanie zamowien i danych transakcyjnych +- [x] Data layer purchase po finalizacji zakupu (wdrozone w Phase 1) + +### Should Have +- Spojny tracking analityczny dla zdarzen ecommerce +- Walidacja danych telemetrycznych i brak duplikatow eventow + +### Nice to Have +- Rozszerzony monitoring jakosci danych analitycznych + +## Constraints +- PHP + Medoo + prepared statements bez sklejania SQL +- Bez logiki biznesowej w widokach +- Bez zmian poza zakresem ecommerce tracking dla aktualnej pracy + +## Success Criteria +- Event purchase trafia do data layer po skutecznym zakupie (osiagniete) +- Payload zawiera wszystkie dostepne dane transakcyjne i produktowe +- Integracja nie wplywa negatywnie na istniejacy checkout + +--- +*Created: 2026-04-19 20:20* +*Last updated: 2026-04-19 after Phase 1* diff --git a/.paul/ROADMAP.md b/.paul/ROADMAP.md new file mode 100644 index 0000000..789b5f2 --- /dev/null +++ b/.paul/ROADMAP.md @@ -0,0 +1,36 @@ +# Roadmap: bilety.brzezovka.pl + +## Overview +W najblizszej iteracji skupiamy sie na uzupelnieniu warstwy analitycznej po zakupie biletow, tak aby tracking ecommerce byl kompletny i wiarygodny. + +## Current Milestone +**v0.1 Initial Release** (v0.1.0) +Status: Complete +Phases: 1 of 1 complete + +## Phases + +| Phase | Name | Plans | Status | Completed | +|-------|------|-------|--------|-----------| +| 1 | Purchase Data Layer | 1 | Complete | 2026-04-19 | + +## Phase Details + +### Phase 1: Purchase Data Layer + +**Goal:** Dodac event purchase do data layer po finalizacji zakupu biletow z kompletnym payloadem. +**Depends on:** Nothing (first phase) +**Research:** Unlikely (istniejaca logika checkout jest dostepna w repo) + +**Scope:** +- Zlokalizowanie miejsca finalizacji zamowienia +- Budowa payloadu purchase z danymi transakcji i pozycji +- Bezpieczne wystawienie danych do warstwy widoku (escape i brak XSS) +- Walidacja braku duplikacji eventu + +**Plans:** +- [x] 01-01: Implementacja i walidacja eventu purchase w data layer (UNIFY complete) + +--- +*Roadmap created: 2026-04-19* +*Last updated: 2026-04-19* diff --git a/.paul/STATE.md b/.paul/STATE.md new file mode 100644 index 0000000..1b3c93c --- /dev/null +++ b/.paul/STATE.md @@ -0,0 +1,50 @@ +# Project State + +## Project Reference + +See: .paul/PROJECT.md (updated 2026-04-19) + +**Core value:** Uzytkownicy moga szybko i bezpiecznie kupic bilety online oraz otrzymac natychmiastowe potwierdzenie zakupu. +**Current focus:** v0.1 Initial Release complete - ready for next milestone planning + +## Current Position + +Milestone: v0.1 Initial Release +Phase: 1 of 1 (Purchase Data Layer) - Complete +Plan: 01-01 complete +Status: Loop closed, ready for next PLAN +Last activity: 2026-04-19 20:31 - Completed UNIFY and phase transition for 01-01 + +Progress: +- Milestone: [##########] 100% +- Phase 1: [##########] 100% + +## Loop Position + +Current loop state: +``` +PLAN --> APPLY --> UNIFY + x x x [Loop complete - ready for next PLAN] +``` + +## Accumulated Context + +### Decisions +- 2026-04-19: Event `purchase` emitowany na `order-confirm`, nie na `przelewy24` (eliminuje falszywe konwersje). +- 2026-04-19: Payload ecommerce budowany w backendzie i serializowany bezpiecznie do widoku. + +### Deferred Issues +None yet. + +### Blockers/Concerns +None yet. + +## Session Continuity + +Last session: 2026-04-19 20:32 +Stopped at: Phase 1 complete and unified +Next action: Start next milestone planning ($paul-milestone or $paul-plan after roadmap update) +Resume file: .paul/ROADMAP.md + +--- +*STATE.md - Updated after every significant action* diff --git a/.paul/changelog/2026-04-19.md b/.paul/changelog/2026-04-19.md new file mode 100644 index 0000000..e2e9e86 --- /dev/null +++ b/.paul/changelog/2026-04-19.md @@ -0,0 +1,20 @@ +# 2026-04-19 + +## Co zrobiono + +- [Phase 1, Plan 01] Wdrozono event `purchase` dopiero po potwierdzonej platnosci na stronie potwierdzenia zamowienia. +- Dodano backendowy builder payloadu ecommerce z danymi transakcji i pozycji biletowych. +- Usunieto przedwczesny event `purchase` ze strony przekierowania do Przelewy24. +- Zamknieto petle PLAN -> APPLY -> UNIFY dla fazy 01-purchase-data-layer. + +## Zmienione pliki + +- `autoload/controls/class.Tickets.php` +- `templates/tickets/order-confirm.php` +- `templates/tickets/przelewy24.php` +- `.paul/phases/01-purchase-data-layer/01-01-PLAN.md` +- `.paul/phases/01-purchase-data-layer/01-01-SUMMARY.md` +- `.paul/PROJECT.md` +- `.paul/ROADMAP.md` +- `.paul/STATE.md` +- `.paul/docs/TECH_CHANGELOG.md` diff --git a/.paul/config.md b/.paul/config.md new file mode 100644 index 0000000..3a9c9b1 --- /dev/null +++ b/.paul/config.md @@ -0,0 +1,33 @@ +# Project Config + +**Project:** bilety.brzezovka.pl +**Created:** 2026-04-19 20:20 + +## Project Settings + +```yaml +project: + name: bilety.brzezovka.pl + version: 0.0.0 +``` + +## Integrations + +### SonarQube + +```yaml +sonarqube: + enabled: false + reason: "User skipped during init" +``` + +## Preferences + +```yaml +preferences: + auto_commit: false + verbose_output: false +``` + +--- +*Config created: 2026-04-19 20:20* diff --git a/.paul/docs/API.md b/.paul/docs/API.md new file mode 100644 index 0000000..511056a --- /dev/null +++ b/.paul/docs/API.md @@ -0,0 +1,4 @@ +# API + +> Endpointy, kontrakty request/response, autentykacja. +> Uzupelnij gdy projekt bedzie udostepnial API. diff --git a/.paul/docs/ARCHITECTURE.md b/.paul/docs/ARCHITECTURE.md new file mode 100644 index 0000000..3638265 --- /dev/null +++ b/.paul/docs/ARCHITECTURE.md @@ -0,0 +1,4 @@ +# Architecture + +> Struktura klas, modulow, przeplywow i zaleznosci w projekcie. +> Uzupelnij po pierwszej fazie implementacji. diff --git a/.paul/docs/DB_SCHEMA.md b/.paul/docs/DB_SCHEMA.md new file mode 100644 index 0000000..8f0b417 --- /dev/null +++ b/.paul/docs/DB_SCHEMA.md @@ -0,0 +1,4 @@ +# Database Schema + +> Schemat bazy danych - tabele, kolumny, FK, indeksy. +> Uzupelnij gdy projekt bedzie korzystac z bazy danych. diff --git a/.paul/docs/DECISIONS.md b/.paul/docs/DECISIONS.md new file mode 100644 index 0000000..edaa7d6 --- /dev/null +++ b/.paul/docs/DECISIONS.md @@ -0,0 +1,4 @@ +# Architecture Decision Records + +> Kluczowe decyzje techniczne i ich uzasadnienia. +> Dodawaj wpisy recznie gdy podejmujesz istotne decyzje architektoniczne. diff --git a/.paul/docs/STACK.md b/.paul/docs/STACK.md new file mode 100644 index 0000000..ffc42d3 --- /dev/null +++ b/.paul/docs/STACK.md @@ -0,0 +1,4 @@ +# Stack + +> Stack technologiczny, wersje, zaleznosci, srodowisko. +> Uzupelnij po inicjalizacji projektu. diff --git a/.paul/docs/TECH_CHANGELOG.md b/.paul/docs/TECH_CHANGELOG.md new file mode 100644 index 0000000..d3ea296 --- /dev/null +++ b/.paul/docs/TECH_CHANGELOG.md @@ -0,0 +1,7 @@ +# Tech Changelog + +## 2026-04-19 - Phase 01 Plan 01 (APPLY) + +- Przeniesiono event `purchase` z `templates/tickets/przelewy24.php` na `templates/tickets/order-confirm.php`, aby event odpalal sie dopiero po potwierdzonej platnosci. +- Dodano backendowy builder payloadu `purchase` w `autoload/controls/class.Tickets.php`, z mapowaniem danych zamowienia i pozycji biletowych. +- Dodano bezpieczna serializacje JSON (`JSON_HEX_*` + `JSON_INVALID_UTF8_SUBSTITUTE`) dla payloadu przekazywanego do skryptu widoku. diff --git a/.paul/docs/TODO.md b/.paul/docs/TODO.md new file mode 100644 index 0000000..34503ad --- /dev/null +++ b/.paul/docs/TODO.md @@ -0,0 +1,4 @@ +# TODO + +> Luzny parking pomyslow, rzeczy do sprawdzenia, rzeczy ktore moga nigdy nie byc wdrozone. +> Nie wymaga formalnosci - wrzucaj co chcesz. diff --git a/.paul/phases/01-purchase-data-layer/01-01-PLAN.md b/.paul/phases/01-purchase-data-layer/01-01-PLAN.md new file mode 100644 index 0000000..e9a7f86 --- /dev/null +++ b/.paul/phases/01-purchase-data-layer/01-01-PLAN.md @@ -0,0 +1,148 @@ +--- +phase: 01-purchase-data-layer +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - autoload/controls/class.Tickets.php + - templates/tickets/order-confirm.php + - templates/tickets/przelewy24.php +autonomous: true +delegation: auto +--- + + +## Goal +Wdroc event `purchase` do `dataLayer` dopiero po skutecznie oplaconym zamowieniu oraz przekazac maksymalnie kompletne dane transakcji i pozycji biletowych. + +## Purpose +Klient potrzebuje wiarygodnego trackingu ecommerce, w ktorym event zakupu nie odpala sie przed potwierdzeniem platnosci i zawiera dane gotowe do analityki GA4/GTM. + +## Output +- Logika backend przygotowujaca payload `purchase` z zamowienia +- Przekazanie payloadu do widoku potwierdzenia zamowienia +- Emisja `dataLayer.push` tylko dla zakonczonej platnosci +- Usuniecie przedwczesnego eventu z widoku przekierowania do Przelewy24 + + + +## Project Context +@.paul/PROJECT.md +@.paul/ROADMAP.md +@.paul/STATE.md + +## Source Files +@autoload/controls/class.Tickets.php +@autoload/factory/class.Tickets.php +@templates/tickets/order-confirm.php +@templates/tickets/przelewy24.php + + + + +## AC-1: Event tylko po potwierdzeniu platnosci +```gherkin +Given uzytkownik finalizuje zakup i wraca na strone potwierdzenia +When zamowienie ma payment_status = 1 +Then event "purchase" jest pushowany do dataLayer na stronie order_confirm +``` + +## AC-2: Pelny payload ecommerce +```gherkin +Given event "purchase" jest emitowany +When skrypt buduje dane ecommerce +Then payload zawiera transaction_id, value, currency, payment_date oraz items z product_id, name, quantity, price i date_visit +``` + +## AC-3: Brak falszywych eventow +```gherkin +Given uzytkownik jest przekierowany do bramki platnosci +When strona przelewy24 jest renderowana przed zakonczeniem platnosci +Then event "purchase" nie jest emitowany na tym etapie +``` + + + + + + + Task 1: Przygotuj backendowy builder payloadu purchase + autoload/controls/class.Tickets.php + + Dodaj wydzielona metode budujaca tablice danych dla data layer na podstawie danych zamowienia: + - Ustal stale pola ecommerce (transaction_id, value, currency, shipping) + - Dodaj pola transakcyjne dostepne w systemie (payment_date, order_id, vat, city, zip_code) + - Zmapuj pozycje `order_tickets` do `items` (item_id/product_id, item_name/name, quantity, price, date_visit) + - Zapewnij poprawne typy liczbowe (float/int) i bezpieczne wartosci domyslne + Unikaj: mieszania logiki mapowania danych bezposrednio w widoku. + + php -l autoload/controls/class.Tickets.php + AC-2 satisfied: payload ecommerce zawiera pelny i spojny zestaw danych + + + + Task 2: Przepnij emisje purchase na order_confirm po oplaceniu + autoload/controls/class.Tickets.php, templates/tickets/order-confirm.php + + W kontrolerze `order_confirm` przekaz do widoku gotowy payload purchase tylko gdy zamowienie jest skutecznie oplacone. + W widoku `order-confirm.php` dodaj warunkowy skrypt: + - reset ecommerce (`dataLayer.push({ ecommerce: null })`) + - push eventu `purchase` z payloadem z backendu + - serializacja przez `json_encode(..., JSON_HEX_TAG|JSON_HEX_AMP|JSON_HEX_APOS|JSON_HEX_QUOT)` dla bezpieczenstwa XSS + - defensywna obsluga przypadku braku `window.dataLayer` + Unikaj: recznego skladania JSON przez konkatenacje stringow. + + php -l autoload/controls/class.Tickets.php && php -l templates/tickets/order-confirm.php + AC-1 satisfied: purchase emituje sie po potwierdzonej platnosci na stronie potwierdzenia + + + + Task 3: Usun przedwczesny purchase z widoku przelewy24 i sprawdz brak regresji + templates/tickets/przelewy24.php + + Usun blok `dataLayer.push` z eventem `purchase` z `przelewy24.php`, pozostawiajac tylko auto-submit formularza do bramki platnosci. + Zweryfikuj recznie scenariusz: + - Wejscie na strone Przelewy24 nie emituje `purchase` + - Powrot na `order_confirm` po statusie payment_status=1 emituje `purchase` z danymi + Unikaj: modyfikacji logiki podpisu i parametrow requestu do Przelewy24. + + php -l templates/tickets/przelewy24.php + AC-3 satisfied: purchase nie odpala sie przed potwierdzeniem platnosci + + + + + + +## DO NOT CHANGE +- Logika weryfikacji podpisu i statusu w `przelewy24_response()` +- Integracja fakturowania w `class.Tickets.php` (sekcja fakturowo API) +- Inne moduly niezwiązane z checkoutem biletowym + +## SCOPE LIMITS +- Bez zmian schematu bazy danych +- Bez przebudowy calego widoku `order-confirm.php` poza sekcja data layer +- Bez zmian flow koszyka i formularza zamowienia poza danymi eventu purchase + + + + +Before declaring plan complete: +- [ ] `php -l autoload/controls/class.Tickets.php` +- [ ] `php -l templates/tickets/order-confirm.php` +- [ ] `php -l templates/tickets/przelewy24.php` +- [ ] Reczny test checkout: brak purchase na `przelewy24`, obecny purchase na `order_confirm` po platnosci +- [ ] Wszystkie acceptance criteria spelnione + + + +- Wszystkie taski wykonane bez regresji flow zakupowego +- Event `purchase` wysylany tylko po skutecznej platnosci +- Payload zawiera komplet dostepnych danych transakcyjnych i pozycje biletowe +- Kod pozostaje zgodny z zasadami czytelnosci i bezpieczenstwa widokow + + + +After completion, create `.paul/phases/01-purchase-data-layer/01-01-SUMMARY.md` + diff --git a/.paul/phases/01-purchase-data-layer/01-01-SUMMARY.md b/.paul/phases/01-purchase-data-layer/01-01-SUMMARY.md new file mode 100644 index 0000000..c61f5bf --- /dev/null +++ b/.paul/phases/01-purchase-data-layer/01-01-SUMMARY.md @@ -0,0 +1,103 @@ +--- +phase: 01-purchase-data-layer +plan: 01 +subsystem: payments +tags: [gtm, ga4, purchase, datalayer, tickets] +requires: [] +provides: + - Purchase event moved to post-payment confirmation view + - Backend purchase payload builder for order and ticket lines + - Safer JSON serialization for data layer payload +affects: [analytics, checkout, order-confirmation] +tech-stack: + added: [] + patterns: + - Build analytics payload in controller instead of in payment redirect view +key-files: + created: [] + modified: + - autoload/controls/class.Tickets.php + - templates/tickets/order-confirm.php + - templates/tickets/przelewy24.php +key-decisions: + - "Emit purchase only on order confirmation after successful payment" + - "Keep payload assembly in backend, render-only in view" +patterns-established: + - "No purchase event on payment gateway redirect page" +duration: 6min +started: 2026-04-19T20:21:00+02:00 +completed: 2026-04-19T20:27:00+02:00 +--- + +# Phase 1 Plan 1: Purchase Data Layer Summary + +Purchase tracking now triggers only after confirmed payment and sends an enriched ecommerce payload from backend data. + +## Performance + +| Metric | Value | +|--------|-------| +| Duration | 6 min | +| Started | 2026-04-19T20:21:00+02:00 | +| Completed | 2026-04-19T20:27:00+02:00 | +| Tasks | 3 completed | +| Files modified | 3 | + +## Acceptance Criteria Results + +| Criterion | Status | Notes | +|-----------|--------|-------| +| AC-1: Event tylko po potwierdzeniu platnosci | Pass | Event moved to `order-confirm.php` and injected only when backend provides payload for successful payment. | +| AC-2: Pelny payload ecommerce | Pass | Payload includes transaction fields plus ticket item lines (`product_id`, `name`, `quantity`, `price`, `date_visit`). | +| AC-3: Brak falszywych eventow | Pass | `purchase` push removed from `przelewy24.php` (pre-payment redirect page). | + +## Accomplishments + +- Added `buildPurchaseDataLayer()` in controller to centralize event payload mapping. +- Passed payload to confirmation view and emitted safe `dataLayer.push` with defensive `window.dataLayer` initialization. +- Removed premature `purchase` push from payment gateway handoff template. + +## Task Commits + +No git commits were created in APPLY (working tree changes only). + +## Files Created/Modified + +| File | Change | Purpose | +|------|--------|---------| +| `autoload/controls/class.Tickets.php` | Modified | Added purchase payload builder and passed payload to order confirmation view. | +| `templates/tickets/order-confirm.php` | Modified | Added safe and conditional purchase data layer push. | +| `templates/tickets/przelewy24.php` | Modified | Removed purchase event from pre-payment step. | + +## Decisions Made + +| Decision | Rationale | Impact | +|----------|-----------|--------| +| Emit `purchase` on `order_confirm` | This view reflects confirmed payment state rather than payment initiation. | Prevents false positive conversions in analytics. | +| Build payload in backend | Keeps view simple and avoids fragile inline data mapping logic. | Better maintainability and safer output handling. | + +## Deviations from Plan + +None. Plan executed as specified. + +## Issues Encountered + +| Issue | Resolution | +|-------|------------| +| None | - | + +## Next Phase Readiness + +**Ready:** +- Purchase event now has a stable post-payment trigger point. +- Payload mapping can be extended later with additional ecommerce fields if needed. + +**Concerns:** +- Manual end-to-end checkout verification in browser/Tag Assistant still pending. + +**Blockers:** +- None + +--- +*Phase: 01-purchase-data-layer, Plan: 01* +*Completed: 2026-04-19* diff --git a/autoload/controls/class.Tickets.php b/autoload/controls/class.Tickets.php index 7343e25..0fbfb7b 100644 --- a/autoload/controls/class.Tickets.php +++ b/autoload/controls/class.Tickets.php @@ -4,6 +4,54 @@ namespace controls; class Tickets { + private static function buildPurchaseDataLayer(array $order) + { + $items = []; + $tickets = $order['tickets'] ?? []; + + foreach ($tickets as $ticket) { + $itemPrice = (float) str_replace(',', '.', (string) ($ticket['price'] ?? 0)); + $itemQuantity = (int) ($ticket['quantity'] ?? 0); + $productId = (int) ($ticket['product_id'] ?? 0); + $itemId = $productId > 0 ? (string) $productId : (string) ($ticket['id'] ?? ''); + + $items[] = [ + 'item_id' => $itemId, + 'item_name' => trim((string) ($ticket['name'] ?? '')), + 'product_id' => $productId, + 'quantity' => $itemQuantity, + 'price' => $itemPrice, + 'date_visit' => trim((string) ($ticket['date_visit'] ?? '')), + ]; + } + + $orderValue = (float) str_replace(',', '.', (string) ($order['order_price'] ?? 0)); + + return [ + 'event' => 'purchase', + 'ecommerce' => [ + 'transaction_id' => (string) ($order['id'] ?? ''), + 'value' => $orderValue, + 'currency' => 'PLN', + 'shipping' => 0.0, + 'tax' => 0.0, + 'payment_type' => 'przelewy24', + 'items' => $items, + ], + 'order' => [ + 'id' => (int) ($order['id'] ?? 0), + 'hash' => trim((string) ($order['hash'] ?? '')), + 'payment_date' => trim((string) ($order['payment_date'] ?? '')), + 'date_added' => trim((string) ($order['date_added'] ?? '')), + 'payment_status' => (int) ($order['payment_status'] ?? 0), + 'vat' => (int) ($order['vat'] ?? 0), + 'city' => trim((string) ($order['city'] ?? '')), + 'zip_code' => trim((string) ($order['zip_code'] ?? '')), + 'country' => 'PL', + ], + ]; + } + private static function sendPaidOrderSummaryEmail(array $order) { $hash = trim((string) ($order['hash'] ?? '')); @@ -799,12 +847,14 @@ class Tickets $order = \factory\Tickets::get_order_details_by_hash(\S::get('order')); $order_successful = false; $order_fail = false; + $purchaseDataLayer = null; if ( $order && !empty($order['payment_status']) && empty($order['informed_user']) ) { if ($order['payment_status']) { $order_successful = true; + $purchaseDataLayer = self::buildPurchaseDataLayer($order); $mailSent = self::sendPaidOrderSummaryEmail($order); if ($mailSent) { $mdb->update('orders', ['informed_user' => 1], ['id' => $order['id']]); @@ -820,7 +870,8 @@ class Tickets return \Tpl::view( 'tickets/order-confirm', [ 'order' => $order, 'order_successful' => $order_successful, - 'order_fail' => $order_fail + 'order_fail' => $order_fail, + 'purchase_data_layer' => $purchaseDataLayer ]); } diff --git a/templates/tickets/order-confirm.php b/templates/tickets/order-confirm.php index 1c2b09e..1095388 100644 --- a/templates/tickets/order-confirm.php +++ b/templates/tickets/order-confirm.php @@ -1,3 +1,21 @@ +purchase_data_layer ?? null)) { + $purchaseDataLayerJson = json_encode( + $this->purchase_data_layer, + JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_INVALID_UTF8_SUBSTITUTE + ); +} +?> + + + + + order_successful === true) : ?> \ No newline at end of file +