adsPRO/docs/PLAN.md

adsPRO - System Zarządzania Reklamami Google ADS & Facebook ADS

Opis projektu

adsPRO to narzędzie webowe (PHP) do zarządzania i automatyzacji kampanii reklamowych Google ADS (priorytet) oraz Facebook ADS (planowane). System umożliwia monitorowanie kampanii, zarządzanie produktami, analizę wydajności (ROAS, CTR, CPC) oraz automatyczne etykietowanie produktów (bestsellery, zombie itp.).

URL: https://adspro.projectpro.pl Hosting: Hostido (shared hosting)

Stack technologiczny

• PHP 8.x - czyste PHP z własną strukturą MVC (bez frameworka)
• MySQL/MariaDB - baza danych (Medoo ORM)
• Google ADS API - pobieranie danych kampanii i produktów (CRON)
• Facebook ADS API - planowane w przyszłości
• CRON - automatyczna synchronizacja danych
• SCSS - stylowanie (kompilacja do CSS)
• jQuery 3.6 - interaktywność frontend
• DataTables 2.1.7 - tabele z sortowaniem, filtrowaniem, paginacją
• Highcharts - wykresy wydajności
• Select2 - zaawansowane selecty
• Font Awesome - ikony

Struktura katalogów (nowa)

public_html/
├── index.php                   # Front controller + nowy router
├── .htaccess                   # Rewrite rules
├── .env                        # Konfiguracja (przyszłość - migracja z config.php)
├── config.php                  # Konfiguracja DB (obecna)
├── ajax.php                    # Ajax handler
├── api.php                     # API handler (Google ADS webhook)
├── cron.php                    # CRON handler
├── robots.txt
├── layout/
│   ├── favicon.png
│   ├── style.scss              # Główne style (SCSS)
│   └── style.css               # Skompilowane style
├── libraries/                  # Biblioteki zewnętrzne
│   ├── medoo/
│   ├── phpmailer/
│   ├── select2/
│   ├── jquery-confirm/
│   ├── functions.js            # Globalne funkcje JS
│   └── framework/              # Framework UI (skin, pluginy)
├── autoload/                   # Kod PHP (MVC)
│   ├── class.S.php             # Helper: sesje, requesty, narzędzia
│   ├── class.Tpl.php           # Template engine
│   ├── class.Cache.php         # Cache
│   ├── class.DbModel.php       # Bazowy model DB
│   ├── class.Html.php          # HTML helper
│   ├── controls/               # Kontrolery
│   │   ├── class.Site.php      # Router (do przebudowy)
│   │   ├── class.Users.php     # Logowanie, ustawienia
│   │   ├── class.Dashboard.php # NOWY - Dashboard główny
│   │   ├── class.Campaigns.php # Kampanie Google ADS
│   │   ├── class.Products.php  # Produkty
│   │   ├── class.Allegro.php   # Import Allegro
│   │   ├── class.Reports.php   # NOWY - Raporty i analityka
│   │   ├── class.Api.php       # Endpointy API
│   │   └── class.Cron.php      # CRON joby
│   ├── factory/                # Modele danych (DB queries)
│   │   ├── class.Users.php
│   │   ├── class.Campaigns.php
│   │   ├── class.Products.php
│   │   └── class.Cron.php
│   └── view/                   # View helpers
│       ├── class.Site.php      # Renderer layoutu
│       ├── class.Users.php
│       └── class.Cron.php
├── templates/                  # Szablony PHP
│   ├── site/
│   │   ├── layout-logged.php   # Layout z sidebar (PRZEBUDOWA)
│   │   └── layout-unlogged.php # Layout logowania (PRZEBUDOWA)
│   ├── auth/
│   │   └── login.php           # NOWY ekran logowania
│   ├── dashboard/
│   │   └── index.php           # NOWY dashboard
│   ├── campaigns/
│   │   └── main_view.php       # Widok kampanii
│   ├── products/
│   │   ├── main_view.php       # Lista produktów
│   │   └── product_history.php # Historia produktu
│   ├── allegro/
│   │   └── main_view.php       # Import Allegro
│   ├── reports/                # NOWE
│   │   └── index.php           # Raporty
│   ├── users/
│   │   ├── login-form.php      # Stary login (do usunięcia)
│   │   └── settings.php        # Ustawienia użytkownika
│   └── html/                   # Komponenty HTML
│       ├── button.php
│       ├── input.php
│       ├── select.php
│       └── ...
├── tools/
│   └── google-taxonomy.php
├── tmp/
└── docs/
    └── PLAN.md

Nowy system routingu

Zasada działania

Zamiast obecnego ?module=X&action=Y → czyste URLe obsługiwane przez .htaccess + nowy router w class.Site.php.

Mapa URL

URL	Kontroler	Metoda	Opis
/login	Users	login_form	Ekran logowania
/logout	Users	logout	Wylogowanie
/	Dashboard	index	Dashboard główny
/campaigns	Campaigns	main_view	Lista kampanii
/campaigns/history/{id}	Campaigns	history	Historia kampanii
/products	Products	main_view	Lista produktów
/products/history/{id}	Products	product_history	Historia produktu
/allegro	Allegro	main_view	Import Allegro
/reports	Reports	index	Raporty
/settings	Users	settings	Ustawienia konta
/api/*	Api	*	Endpointy API
/cron/*	Cron	*	CRON joby

Nowy .htaccess

RewriteEngine On
RewriteBase /

# Statyczne zasoby - pomijaj
RewriteCond %{REQUEST_URI} ^/(libraries|layout|upload|temp)/ [NC]
RewriteRule ^ - [L]

# Wszystko inne → index.php
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [L,QSA]

Nowy router (class.Site.php)

// Parsowanie URL z $_SERVER['REQUEST_URI']
// Mapowanie: /segment1/segment2/segment3 → kontroler/akcja/parametry
// Fallback na dashboard dla zalogowanych, login dla niezalogowanych

Główne funkcje

1. Nowy ekran logowania

• Nowoczesny design: podzielony ekran (lewa strona - branding/grafika, prawa - formularz)
• Logo "adsPRO" z subtitlem
• Pola: email + hasło
• Checkbox "Zapamiętaj mnie"
• Walidacja AJAX
• Animacje przejścia
• Responsywność (mobile: tylko formularz)

2. Nowy layout z menu bocznym (sidebar)

• Sidebar (lewa strona, 260px):
  • Logo "adsPRO" na górze
  • Menu nawigacyjne z ikonami Font Awesome:
    • 📊 Dashboard (/)
    • 📢 Kampanie (/campaigns)
    • 📦 Produkty (/products)
    • 📥 Allegro import (/allegro)
    • 📈 Raporty (/reports)
    • ⚙️ Ustawienia (/settings)
  • Aktywny element podświetlony
  • Możliwość zwijania sidebar (collapsed → same ikony, 60px)
  • Na dole: info o zalogowanym użytkowniku + przycisk wylogowania
• Top bar (nad contentem):
  • Przycisk hamburger (toggle sidebar)
  • Breadcrumbs (ścieżka nawigacji)
  • Szybkie akcje / notyfikacje (przyszłość)
• Content area:
  • Pełna szerokość minus sidebar
  • Padding 25px
  • Tło #F4F6F9 (jaśniejsze od obecnego)

3. Dashboard (NOWY)

• Kafelki podsumowujące (karty):
  • Łączna liczba kampanii
  • Łączna liczba produktów
  • Średni ROAS (30 dni)
  • Łączne wydatki (30 dni)
• Wykres trendu ROAS (ostatnie 30 dni)
• Lista ostatnio zmodyfikowanych kampanii
• Produkty wymagające uwagi (niski ROAS, zombie)

4. Zarządzanie kampaniami Google ADS

• Wybór klienta (select)
• Lista kampanii z metrykami (DataTables)
• Historia kampanii z wykresem Highcharts
• Metryki: ROAS, budżet, wydatki, wartość konwersji, strategia bidding
• Usuwanie kampanii i wpisów historii
• Komentarze do kampanii

5. Zarządzanie produktami

• Wybór klienta
• Konfiguracja min. ROAS dla bestsellerów
• Tabela produktów z metrykami:
  • Wyświetlenia, kliknięcia, CTR, koszt, CPC
  • Konwersje, wartość konwersji, ROAS
  • Custom labels (bestseller/zombie/deleted/pla/paused)
• Edycja inline (min_roas, custom_label)
• Edycja produktu w modalu (tytuł, opis, kategoria Google)
• Historia produktu z wykresem
• Bulk delete zaznaczonych produktów

6. Import Allegro

• Upload pliku CSV
• Automatyczne mapowanie ofert
• Raport importu (dodane, zaktualizowane)

7. Raporty (NOWY - przyszłość)

• Raport wydajności kampanii
• Raport produktów (bestsellery vs zombie)
• Eksport do Excel
• Porównanie okresów

8. Ustawienia

• Dane konta (email)
• Zmiana hasła
• Konfiguracja Pushover (powiadomienia)
• Klucze API (przyszłość: Google ADS, Facebook ADS)

9. CRON - synchronizacja danych

• cron_products - synchronizacja produktów z Google ADS
• cron_products_history_30 - historia 30-dniowa produktów
• cron_xml - generowanie XML
• cron_phrases - synchronizacja fraz
• cron_phrases_history_30 - historia 30-dniowa fraz

Plan implementacji

Etap	Zakres	Priorytet	Pliki
1. Nowy routing	Przebudowa routera, nowy .htaccess, parsowanie czystych URL	🔴 Wysoki	.htaccess, index.php, controls/class.Site.php
2. Nowy layout (sidebar)	Layout z bocznym menu, top bar, responsywność	🔴 Wysoki	templates/site/layout-logged.php, layout/style.scss
3. Nowy ekran logowania	Nowoczesny split-screen login, nowy layout-unlogged	🔴 Wysoki	templates/site/layout-unlogged.php, templates/auth/login.php, layout/style.scss
4. Dashboard	Nowa strona startowa z podsumowaniem	🟡 Średni	controls/class.Dashboard.php, templates/dashboard/index.php
5. Migracja kampanii	Dostosowanie widoku kampanii do nowego routingu	🟡 Średni	controls/class.Campaigns.php, templates/campaigns/*
6. Migracja produktów	Dostosowanie widoku produktów do nowego routingu	🟡 Średni	controls/class.Products.php, templates/products/*
7. Migracja Allegro	Dostosowanie importu Allegro	🟢 Niski	controls/class.Allegro.php, templates/allegro/*
8. Moduł raportów	Nowy moduł analityczny	🟢 Niski	controls/class.Reports.php, templates/reports/*
9. Facebook ADS	Integracja z Facebook ADS API	🔵 Przyszłość	Nowe kontrolery, factory, szablony

Kolorystyka i design

Paleta kolorów

• Primary (akcent): #6690F4 (niebieski - obecny)
• Sidebar tło: #1E2A3A (ciemny granat)
• Sidebar tekst: #A8B7C7 (jasny szary)
• Sidebar active: #6690F4 (primary)
• Content tło: #F4F6F9 (jasnoszary)
• Karty: #FFFFFF
• Tekst: #4E5E6A (obecny)
• Success: #57B951
• Danger: #CC0000
• Warning: #FF8C00

Typografia

• Font: Open Sans (obecny - zachowany)
• Rozmiar bazowy: 14px (sidebar), 15px (content)

Bezpieczeństwo

• Hasła hashowane MD5 (obecne) → TODO: migracja na bcrypt
• Sesje PHP + cookie "zapamiętaj mnie"
• Prepared statements (Medoo ORM)
• htmlspecialchars() w szablonach
• TODO: CSRF tokeny w formularzach
• TODO: migracja config.php → .env (z .htaccess deny)

Przyszłe rozszerzenia

• Facebook ADS API - zarządzanie kampaniami FB
• System powiadomień (Pushover + in-app)
• Wielojęzyczność (PL/EN)
• Role użytkowników (admin, manager, viewer)
• Automatyczne reguły (np. "jeśli ROAS < X → zmień label na zombie")
• Integracja z Google Merchant Center
• API REST do integracji z innymi systemami