---
name: google-ads-client-report
description: Workflow for generating, reviewing, validating, and uploading monthly Google Ads client HTML reports in this repository. Use when the user asks for `raport-klienta`, `analiza-klienta` with a domain and month, a monthly client report, regenerating a report, adding report recommendations, checking Semstorm/SEO sections, or uploading a report to adspro.projectpro.pl.
---

# Google Ads Client Report

## Core Rule

Pisz po polsku. Prowadź użytkownika etapami: pobranie danych, uzupełnienie rekomendacji, akceptacja, generowanie HTML, akceptacja uploadu, wysyłka.

Nigdy nie wysyłaj raportu na serwer bez jasnej zgody użytkownika po wygenerowaniu HTML.

## Start

Dla prośby w stylu:

```text
raport-klienta aruba.rzeszow.pl 04-2026
analiza-klienta aruba.rzeszow.pl 04-2026
```

uruchom:

```powershell
python gads.py raport-klienta aruba.rzeszow.pl 04-2026
```

Formaty miesiąca mogą być `MM-YYYY`, `MM.YYYY` albo `YYYY-MM`. Do dalszych komend używaj `YYYY-MM`.

Jeżeli użytkownik napisze tylko `raport-klienta`, uruchom:

```powershell
python gads.py raport-klienta
```

Pokaż pełną listę klientów i poproś o numer. Po wyborze klienta i miesiąca uruchom:

```powershell
python gads.py raport-klienta --client-number <numer-klienta> --month <YYYY-MM>
```

## Recommendations

Pierwsza komenda tworzy dane i plik rekomendacji:

```text
scripts/reports/output/<domena>_<YYYY-MM>.json
scripts/reports/output/<domena>_<YYYY-MM>_recommendations.json
```

Odczytaj oba pliki. Uzupełnij `recommendations` konkretnymi wnioskami:

- pisz z perspektywy osoby prowadzącej konto;
- pisz decyzyjnie: co robimy, zostawiamy, ograniczamy, kontrolujemy;
- nie pisz do klienta, że "warto sprawdzić" albo "należy przeanalizować";
- używaj poprawnych polskich znaków;
- nie usuwaj kontekstu liczbowego z pliku.

Pokaż użytkownikowi krótką tabelę wniosków i zapytaj o akceptację.

## Required Data Validation

Przed wygenerowaniem albo wysłaniem raportu sprawdź plik:

```text
scripts/reports/output/<domena>_<YYYY-MM>.json
```

Wymagane kontrole:

- `semstorm.current` ma istnieć. Semstorm powinien być zawsze pobrany, gdy `.env` zawiera `SEMSTORM_LOGIN` i `SEMSTORM_PASSWORD`. Jeśli brakuje danych, nie wysyłaj raportu; napisz, czego brakuje.
- Jeśli klient ma `sales_history_sheet` w `config/clients.toml`, sekcja e-commerce i historia sprzedaży mają pochodzić z Google Sheet, nie z GA4.
- Jeśli klient ma `seo_works_history_sheet`, raport ma zawierać `seo_activities`.
- Jeśli klient ma `seo_links_history_sheet`, raport ma zawierać `seo_links` z liczbą większą od 0, jeżeli arkusz zawiera dane dla miesiąca.
- Sprawdź wygenerowany HTML pod kątem sekcji: `SEO — Widoczność (Semstorm)`, `SEO — Pozostałe działania`, `SEO — Pozyskane linki`.

Pomocne komendy:

```powershell
$json = Get-Content -Raw "scripts\reports\output\<domena>_<YYYY-MM>.json" | ConvertFrom-Json
$json.semstorm.current
$json.seo_activities
$json.seo_links.Count
Select-String -Path "scripts\reports\output\<domena>\<YYYY-MM>\index.html" -Pattern "Semstorm|Pozostałe działania|Pozyskane linki"
```

## Generate HTML

Po akceptacji rekomendacji uruchom:

```powershell
python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-recommendations TAK
```

Jeżeli potrzebna jest nazwa klienta w raporcie:

```powershell
python gads.py raport-klienta --client <domena> --month <YYYY-MM> --client-name "<Nazwa>" --confirm-recommendations TAK
```

Po wygenerowaniu pokaż ścieżkę:

```text
scripts/reports/output/<domena>/<YYYY-MM>/index.html
```

Zapytaj osobno, czy wysłać raport na serwer.

## Upload

Po zgodzie użytkownika uruchom komendę z oboma potwierdzeniami, żeby narzędzie nie zatrzymało się ponownie na etapie rekomendacji:

```powershell
python gads.py raport-klienta --client <domena> --month <YYYY-MM> --client-name "<Nazwa>" --confirm-recommendations TAK --confirm-upload TAK
```

Jeśli nazwa klienta nie jest potrzebna, można pominąć `--client-name`.

Po wysyłce podaj URL:

```text
https://adspro.projectpro.pl/raporty/<slug>/<YYYY-MM>/
```

## If Data Is Missing

Nie wysyłaj raportu, jeżeli brakuje wymaganych sekcji. Najpierw popraw pobieranie danych albo konfigurację:

- Semstorm: sprawdź `.env`, `SEMSTORM_LOGIN`, `SEMSTORM_PASSWORD`, `SEMSTORM_API_BASE`, ewentualnie uruchom `python scripts/reports/fetch_semstorm_data.py --domain <domena> --month <YYYY-MM>`.
- SEO works/linki: sprawdź `config/clients.toml` i pola `seo_works_history_sheet`, `seo_links_history_sheet`.
- Po poprawce uruchom ponownie generowanie HTML i walidację przed uploadem.