adsPRO/docs/memory.md

2026-02-20 - Obsluga statusu ACTIVE dla klientow

Zmienione pliki

• autoload/controls/class.Clients.php

  • save() zapisuje teraz pole active (domyslnie 1, gdy brak wartosci z formularza).
  • Dodana nowa akcja set_active() pod endpoint /clients/set_active do szybkiej zmiany statusu klienta AJAX-em.
  • force_sync() ma dodatkowa walidacje:
    • nie pozwala kolejkowac synchronizacji dla klienta nieaktywnego (active != 1),
    • nadal blokuje klienta usunietego (deleted = 1) i klienta bez wymaganych ID.
  • Kompatybilnosc schematu clients bez kolumny deleted:
    • helpery clients_has_deleted_column() i sql_clients_not_deleted(),
    • force_sync() i sync_status() nie wywalaja sie, gdy w bazie nie ma kolumny deleted.

• templates/clients/main_view.php

  • Tabela klientow ma nowa kolumne Status (Aktywny/Nieaktywny).
  • Wiersz klienta trzyma data-active do obslugi UI i synchronizacji.
  • Dodany przycisk toggle (ikona fa-toggle-on/off) do natychmiastowej aktywacji/dezaktywacji.
  • Przyciski synchronizacji (kampanie/produkty/merchant) sa blokowane (disabled) dla nieaktywnego klienta i odblokowywane po aktywacji.
  • Formularz Dodaj/Edytuj klienta ma nowe pole Status klienta (active).
  • JS:
    • toggleClientActive() wysyla POST na /clients/set_active,
    • updateClientStatusUI() odswieza status i stan komorki Sync bez przeladowania strony,
    • loadSyncStatus() pomija paski postepu dla nieaktywnych klientow i pokazuje nieaktywny.

Gdzie to jest wykorzystywane

• Zarzadzanie statusem klienta:
  • UI listy i formularza: templates/clients/main_view.php
  • Backend zapisu i toggle: autoload/controls/class.Clients.php
• Ograniczenie recznego wymuszenia synchronizacji do klientow aktywnych:
  • autoload/controls/class.Clients.php (force_sync())

2026-02-20 - CRON kampanii (nowy przebieg, stare jako archiwum)

Zmienione pliki

• autoload/controls/class.Cron.php
  • Dodany nowy cron_campaigns() jako glowny endpoint pod nowy przeplyw.
  • Stary kod zostal zachowany jako archiwum: cron_campaigns_archive().
  • Nowy przebieg:
    • bierze tylko aktywnych klientow (active = 1) z Google Ads Customer ID,
    • liczy okno dat na podstawie google_ads_conversion_window_days z config.php (z fallbackiem),
    • konczy okno na przedwczoraj (bez pobierania danych dzisiejszych),
    • przechodzi po datach dzien po dniu (rosnaco),
    • zapisuje/aktualizuje kampanie do campaigns,
    • zapisuje/aktualizuje historie dzienne do campaigns_history (upsert po campaign_id + date_add),
    • zapisuje grupy reklam / groupy PMAX do campaign_ad_groups.
  • po zakonczeniu kampanii + ad groups dla klienta, dla calego okna dat pobiera search terms dzienne do campaign_search_terms_history,
  • po pobraniu historii search terms wykonuje agregacje do campaign_search_terms (zanim przejdzie do kolejnego klienta).
  • Dodany krok syncu fraz dodanych i wykluczonych:
    • tabele docelowe: campaign_keywords i campaign_negative_keywords,
    • uruchamiany raz na cykl klienta (po ostatnim dniu okna), nie x razy dla kazdego dnia.
• Kampanie produktowe / PMAX:
  • nie maja fraz dodanych, wiec w campaign_keywords moga miec 0 rekordow,
  • frazy wykluczone sa dalej synchronizowane do campaign_negative_keywords.

2026-02-20 - Produkty: przygotowanie schematu bazy

Zmienione pliki

• migrations/016_products_model_unification.sql

  • Dodane kolumny produktowe bezposrednio do products:
    • custom_label_4, custom_label_3, title, description, google_product_category, product_url.
  • Backfill danych z products_data -> products (tylko gdy pole w products jest puste).
  • Dodana nowa tabela agregacyjna products_aggregate:
    • scope: product_id + campaign_id + ad_group_id (unikalne),
    • metryki *_30 i *_all_time,
    • date_sync (kiedy agregat byl przeliczony).

• docs/database.sql

  • Zaktualizowana definicja products o nowe kolumny danych produktu.
  • Dodana definicja tabeli products_aggregate.

Ustalenie projektowe

• products staje sie glowna tabela danych produktu.
• products_data zostaje tymczasowo dla kompatybilnosci starego kodu; dane sa migrowane do products.
• Agregaty dla widokow /products powinny docelowo byc czytane z products_aggregate zamiast liczenia w locie.

2026-02-20 - Produkty: przepiecie na products + agregaty

Zmienione pliki

• autoload/factory/class.Products.php

  • get_product_data():
    • najpierw czyta pola produktowe z products (custom_label_4, custom_label_3, title, description, google_product_category, product_url),
    • fallback do products_data dla kompatybilnosci.
  • set_product_data():
    • zapisuje pole glownie do products,
    • rownolegle mirroruje zapis do products_data (kompatybilnosc starego kodu).

• autoload/controls/class.Cron.php

  • sync_products_fetch_for_client():
    • import produktow zapisuje dane produktowe bezposrednio do products (w tym title, product_url),
    • usuniete poleganie na products_data podczas samego fetchu.
  • aggregate_products_history_30_for_client():
    • po przeliczeniu products_history_30 odpala przebudowe agregatow products_aggregate dla klienta i dnia.
  • Dodana metoda rebuild_products_aggregate_for_client( $client_id, $date_sync ):
    • liczy metryki *_30 i *_all_time z products_history,
    • zapisuje scope (product_id + campaign_id + ad_group_id) do products_aggregate.
  • rebuild_products_temp_for_client():
    • przestawione z liczenia bezposrednio po products_history na odczyt z products_aggregate,
    • zmniejsza liczenie "w locie" dla widoku /products.
  • cron_product_history_30_save():
    • products_history_30 przechowuje teraz srednie dzienne wartosci z okna do 30 dni (zamiast sumy okna),
    • nadal zapisuje roas_all_time dla danego dnia.
  • generate_custom_feed_for_client():
    • zrodlo danych produktowych przepiete na products (bez wymaganego INNER JOIN products_data).
  • diagnostyka i pobieranie brakujacych URL (cron_products_urls):
    • logika "ma URL / brak URL" bierze pod uwage products.product_url z fallbackiem do products_data.

Gdzie to jest wykorzystywane

• Pipeline produktowy:

  • /cron/cron_products
  • etap fetch -> products_history,
  • etap agregacji -> products_history_30 + products_aggregate,
  • etap finalny -> products_temp budowane z products_aggregate.

• Widok tabeli produktow /products:

  • dane nadal czytane z products_temp, ale products_temp jest teraz zasilane agregatami z products_aggregate.
  • Dodany helper sync_campaigns_snapshot_for_client() dla nowego przebiegu kampanii.
  • Dodany helper sync_campaign_terms_backfill_for_client() dla kroku fraz (history + agregacja).
  • Tryb wykonania nowego pipeline kampanii: 1 dzien = 1 wywolanie CRON.
    • Na jednym wywolaniu: kampanie + ad groups + search terms history + agregacja search terms dla jednego dnia.
    • Kolejne wywolanie przechodzi do kolejnego dnia dla tego samego klienta.
  • Tryb debug dla nowego CRON:
    • ?debug=true zwraca czytelny HTML (podsumowanie + pelny payload),
    • bez debug zwracany jest standardowy JSON.
  • Dodany helper cleanup_pipeline_rows_outside_window() aby pipeline kampanii trzymal tylko aktualne okno dat.
  • Filtry klientow w nowym CRON kampanii sa odporne na stare dane (NULL): COALESCE(active,0), COALESCE(deleted,0), TRIM(COALESCE(google_ads_customer_id,'')).
  • Dodana kompatybilnosc schematu clients bez kolumny deleted:
    • helpery: clients_has_column(), sql_clients_not_deleted(), sql_clients_deleted(),
    • nowy pipeline kampanii (cron_campaigns/cron_universal) nie wywala sie na bazie bez deleted.
  • get_conversion_window_days( $prefer_config = false ) uwzglednia teraz konfiguracje z config.php.
  • sync_campaign_ad_groups_for_client() dostal parametr as_of_date.

• autoload/services/class.GoogleAdsApi.php

  • get_ad_groups_30_days() wspiera teraz parametr as_of_date i zakres dat [as_of_date-29, as_of_date].
  • get_ad_groups_all_time() wspiera teraz parametr as_of_date (filtr segments.date <= as_of_date z fallbackiem).

Gdzie to jest wykorzystywane

• Głowny CRON kampanii: /cron/cron_campaigns -> \controls\Cron::cron_campaigns().
• Uniwersalny CRON pipeline (zalecany endpoint): /cron/cron_universal -> \controls\Cron::cron_universal() (aktualnie deleguje do kroku kampanii).
• Archiwalny CRON kampanii (stara logika): /cron/cron_campaigns_archive.
• Dane do wykresow/tabel kampanii pozostaja pobierane z campaigns_history.

2026-02-20 - CRON uniwersalny jako glowny endpoint (1 dzien na wywolanie)

Zmienione pliki

• autoload/controls/class.Cron.php
  • cron_universal() nie deleguje juz do cron_campaigns().
  • W jednym wywolaniu realizuje sekwencje:
    • kampanie (snapshot + ad groups + search terms + agregacja),
    • produkty (fetch + products_history_30 + products_aggregate + products_temp).
  • Tryb pracy pozostaje: 1 wywolanie = 1 klient + 1 dzien.
  • Status dnia jest zapisywany do cron_sync_status dla obu pipeline:
    • campaigns,
    • products.
  • Gdy krok kampanii zwroci blad, krok produktow dla tego dnia jest pomijany (products_sync_skipped_reason=campaigns_failed).

Gdzie to jest wykorzystywane

• Docelowy adres CRON:
  • /cron/cron_universal?debug=true
• Stare endpointy (/cron/cron_campaigns, /cron/cron_products) pozostaja w kodzie, ale nie sa docelowa sciezka wykonywania.

2026-02-20 - Poprawka niezaleznosci pipeline w cron_universal

Problem

• campaigns mialo juz 100% (done) i cron_universal konczyl wykonanie, mimo ze products mial jeszcze zalegle daty.

Zmienione pliki

• autoload/controls/class.Cron.php
  • cron_universal() wybiera teraz aktywnego klienta niezaleznie dla obu pipeline:
    • campaigns,
    • products.
  • Zakonczenie "wszyscy przetworzeni" następuje dopiero, gdy oba pipeline nie maja juz aktywnych pozycji.
  • Dodane osobne liczenie pozostalych dat:
    • campaigns_remaining_dates,
    • products_remaining_dates.
  • Statusy done/pending sa zapisywane osobno dla kazdego pipeline; produkty nie sa juz blokowane przez sam fakt, ze kampanie sa skonczone globalnie.
  • Ujednolicenie trybu client_id:
    • kampanie i produkty wykonują sie niezaleznie (w tym samym wywolaniu), a bledy sa laczone tylko w odpowiedzi.

2026-02-20 - Usuniecie products_data

Zmienione pliki

• migrations/017_drop_products_data.sql

  • Dodana migracja usuwajaca tabele products_data.

• autoload/factory/class.Products.php

  • get_product_data() czyta dane tylko z products.
  • set_product_data() zapisuje dane tylko do products.

• autoload/controls/class.Cron.php

  • diagnostyka URL i wybieranie produktow bez URL opiera sie juz tylko o products.product_url.

• docs/database.sql

  • usunieta definicja tabeli products_data.

• migrations/demo_data.sql

  • usuniete operacje INSERT/DELETE na products_data,
  • etykiety demo (custom_label_4) sa ustawiane bezposrednio w products.

Gdzie to jest wykorzystywane

• Dane produktowe (title, description, google_product_category, custom_label_3, custom_label_4, product_url) sa trzymane tylko w products.

2026-02-20 - Ostatni krok cron_universal: URL z Merchant + alerty brakow

Zmienione pliki

• autoload/controls/class.Cron.php

  • Dodany helper sync_products_urls_and_alerts_for_client().
  • Na koncu przebiegu cron_universal (zarowno tryb automatyczny, jak i client_id) wykonywany jest krok:
    • pobranie URL produktow z Google Merchant Center dla produktow bez URL,
    • zapis URL do products.product_url.
  • Gdy offer_id nie istnieje w Merchant Center, tworzony/aktualizowany jest alert w campaign_alerts:
    • alert_type = products_missing_in_merchant_center,
    • scope techniczny: campaign_external_id = 0, ad_group_external_id = 0,
    • meta_json zawiera m.in. listy missing_offer_ids i missing_product_ids.
  • Gdy w danym dniu brak brakujacych produktow, dzienny alert tego typu jest czyszczony.
  • Do odpowiedzi cron dodane pola diagnostyczne:
    • merchant_urls_checked,
    • merchant_urls_updated,
    • merchant_missing_in_mc_count,
    • merchant_missing_offer_ids.
  • cron_universal ma dodatkowy fallback niezalezny od pipeline campaigns/products:
    • gdy oba pipeline sa zakonczone, ale sa jeszcze produkty bez URL, uruchamia sam krok Merchant URL + alerty (merchant_only=1),
    • dopiero brak takich produktow daje komunikat "Wszyscy aktywni klienci zostali przetworzeni...".
  • Krok Merchant URL nie jest wykonywany dla kazdego dnia okna; dziala jako osobny etap po zakonczeniu campaigns/products.
  • Do zapytan do GMC trafiaja tylko produkty z products.product_url IS NULL i merchant_url_not_found = 0.
  • Na jedno wywolanie wykonywana jest jedna paczka sprawdzen (limit z config.php: cron_products_urls_limit_per_client, ustawiony na 100).
  • Produkty, ktorych GMC nie zwraca (brak URL), sa oznaczane:
    • products.merchant_url_not_found = 1,
    • products.merchant_url_last_check = NOW(),
    • dzieki temu nie sa wysylane ponownie w nieskonczonosc.
  • Alert products_missing_in_merchant_center jest liczony na podstawie calej aktualnej puli merchant_url_not_found = 1 (nie tylko bieżącej paczki), wiec nie znika przy checked_products = 0.
  • Alerty sa per produkt (1 alert = 1 produkt):
    • dla kazdego produktu bez URL i z merchant_url_not_found = 1 tworzony jest osobny wpis w campaign_alerts,
    • tresc alertu zawiera nazwe produktu (fallback: name, dalej offer_id) i offer_id,
    • technicznie: campaign_external_id = products.id, co stabilizuje unikalnosc wpisu.

• migrations/018_products_merchant_url_flags.sql

  • Dodane kolumny w products:
    • merchant_url_not_found (TINYINT, domyslnie 0),
    • merchant_url_last_check (DATETIME).
  • Normalizacja: puste/sztuczne product_url ('', '0', '-', 'null') ustawiane na NULL.

• autoload/factory/class.Products.php

  • Przy zapisie product_url:
    • ustawiany jest merchant_url_last_check,
    • dla poprawnego URL resetowane jest merchant_url_not_found = 0.

2026-02-20 - Alerty na stronie /products dla klient + kampania

Zmienione pliki

• autoload/factory/class.Products.php

  • get_scope_alerts() nie wymaga juz wybranej grupy reklam:
    • minimalny scope: client_id + campaign_id,
    • filtr ad_group_id jest stosowany tylko opcjonalnie (gdy grupa jest wybrana).

• templates/products/main_view.php

  • load_scope_alerts() pobiera alerty juz dla kombinacji klient + kampania.
  • Sekcja alertow ma zaktualizowany opis: kampania + opcjonalna grupa reklam.

Gdzie to jest wykorzystywane

• /products
  • Panel alertow pod filtrami pokazuje alerty:
    • dla calej kampanii (gdy grupa reklam nie jest wybrana),
    • lub zawezone do konkretnej grupy (gdy grupa reklam jest wybrana).

2026-02-20 - Etykietowanie alertow Merchant (bez falszywej kampanii)

Zmienione pliki

• autoload/controls/class.Cron.php

  • Dla alertu products_missing_in_merchant_center nie jest juz zapisywany product_id w campaign_external_id.
  • Pola scope kampanii/grupy sa zapisywane jako 0 (alert produktowy, bez przypisania do kampanii).

• templates/campaign_alerts/main_view.php

  • Dla alertu products_missing_in_merchant_center tabela alertow pokazuje:
    • Kampania: Produkt (Merchant Center),
    • Grupa reklam: ---.
  • Dla pozostalych alertow fallback Kampania #... / Grupa reklam #... dziala tylko dla dodatnich external_id; dla 0 pokazuje neutralne etykiety.

2026-02-20 - Powiazanie campaign_alerts z products

Zmienione pliki

• migrations/019_campaign_alerts_product_id.sql

  • Dodana kolumna campaign_alerts.product_id (NULL) oraz indeks idx_alert_product.

• autoload/controls/class.Cron.php

  • Alerty products_missing_in_merchant_center zapisuja product_id w tabeli campaign_alerts.
  • Dla zachowania unikalnosci dziennej per produkt, techniczny campaign_external_id pozostaje rowny product_id.

• autoload/factory/class.CampaignAlerts.php

  • get_alerts() zwraca teraz rowniez pole product_id.

• docs/database.sql

  • Dodana aktualna definicja tabeli campaign_alerts z kolumna product_id.

2026-02-20 - CRON produktow: title nie jest uzupelniany automatycznie

Zmienione pliki

• autoload/controls/class.Cron.php
  • W syncu produktow do tabeli products CRON nie zapisuje juz pola title.
  • Dla nowych produktow CRON zapisuje tylko name (bez title).
  • Dla istniejacych produktow usunieto automatyczne uzupelnianie pustego title.

Gdzie to jest wykorzystywane

• /cron/cron_universal
  • automatyczny import produktow nie nadpisuje ani nie uzupelnia products.title,
  • title pozostaje polem do recznej edycji i wysylki do GMC.

2026-02-20 - Lista produktow z 0 wyswietlen (30 dni) na /products

Zmienione pliki

• autoload/factory/class.Products.php

  • Dodana metoda get_products_without_impressions_30( $client_id, $campaign_id, $limit ).
  • Zwraca produkty z wybranej kampanii, ktore maja sume impressions_30 = 0 na podstawie products_aggregate.
  • Dodatkowy filtr ad_group_id (opcjonalny), aby lista byla zgodna z aktualnym filtrem grupy reklam na widoku.

• autoload/controls/class.Products.php

  • Dodany endpoint get_products_without_impressions_30().
  • Zwraca JSON: status, products[], count i przyjmuje opcjonalnie ad_group_id.

• templates/products/main_view.php

  • Dodana sekcja nad tabela produktow:
    • "Produkty do sprawdzenia (0 wyswietlen w ostatnich 30 dniach)".
  • Sekcja pojawia sie dla wybranego klient + kampania.
  • Lista odswieza sie przy zmianie klienta/kampanii/grupy oraz po zaladowaniu strony.

Gdzie to jest wykorzystywane

• /products
  • pomocnicza lista produktow potencjalnie nieistniejacych / wymagajacych weryfikacji (0 wyswietlen w 30 dni dla wybranej kampanii).

2026-02-20 - Ustawienia CRON: poprawka licznika klientow + usuniecie "Krok 1/Krok 2"

Zmienione pliki

• autoload/controls/class.Users.php

  • Licznik Klienci z Google Ads ID liczy teraz klientow z:
    • COALESCE(active, 0) = 1,
    • TRIM(COALESCE(google_ads_customer_id, '')) <> ''.
  • Analogicznie poprawione filtry dla klientow Merchant i zapytan pomocniczych (wg active).
  • Harmonogram krokow (Krok 1, Krok 2) w danych dashboardu CRON jest pusty.

• templates/users/settings.php

  • Usunieta sekcja wizualna harmonogramu krokow CRON (Krok 1 / Krok 2).
  • Usunieta obsluga renderowania tej sekcji w JS odswiezajacym status CRON.

Gdzie to jest wykorzystywane

• /settings?settings_tab=cron
  • licznik klientow z Google Ads ID pokazuje poprawna wartosc na podstawie aktywnych klientow (active = 1),
  • brak sekcji "Krok 1 / Krok 2".

2026-02-20 - /products czyta bezposrednio z products_aggregate

Zmienione pliki

• autoload/factory/class.Products.php
  • Zapytania dla listy produktow i licznikow zostaly przepiete z products_temp na products_aggregate:
    • get_products(),
    • get_roas_bounds(),
    • get_records_total_products(),
    • get_product_full_context().
  • Metryki all-time sa liczone z pol:
    • impressions_all_time, clicks_all_time, cost_all_time, conversions_all_time, conversion_value_all_time.
  • Metryki 30d sa czytane z:
    • impressions_30, clicks_30.

Gdzie to jest wykorzystywane

• /products
  • tabela i liczniki nie zaleza juz od products_temp; biora dane bezposrednio z products_aggregate.

2026-02-20 - custom_label_4 tylko z tabeli products

Ustalenie

• Etykieta custom_label_4 jest czytana i zapisywana z tabeli products.
• Agregaty (products_aggregate) nie sa zrodlem dla pola custom_label_4.

2026-02-20 - Usuniecie funkcjonalnosci bestseller_min_roas

Zmienione pliki

• templates/products/main_view.php

  • Usuniety filtr UI: pole Bestseller min ROAS (#bestseller_min_roas).
  • Usuniety frontendowy loader wartosci progu (load_client_bestseller_min_roas).
  • Usuniete wywolania loadera przy zmianie klienta i przy inicjalizacji strony.
  • Usuniety zapis AJAX progu klienta na blur (/products/save_client_bestseller_min_roas/).

• autoload/controls/class.Products.php

  • Usuniete endpointy:
    • get_client_bestseller_min_roas()
    • save_client_bestseller_min_roas()

• autoload/factory/class.Products.php

  • Usuniete metody dostepu do progu ROAS klienta:
    • get_client_bestseller_min_roas( $client_id )
    • save_client_bestseller_min_roas( $client_id, $min_roas )

• autoload/controls/class.Cron.php

  • W rebuild_products_temp_for_client() usunieta logika automatycznej zmiany custom_label_4 oparta o prog bestseller_min_roas.
  • Funkcja pozostaje jako krok diagnostyczny zwracajacy liczbe scope z products_aggregate.

Efekt

• Aplikacja nie odczytuje, nie zapisuje i nie wykorzystuje juz bestseller_min_roas w UI, endpointach ani w CRON.
• Automatyczne oznaczanie custom_label_4 = bestseller na podstawie tego progu zostalo wycofane.