133 lines
4.6 KiB
Markdown
133 lines
4.6 KiB
Markdown
---
|
|
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.
|