SKILL.md · Signals Dance Docs

SKILL.md

Uložte jako dance/SKILL.md (vstupní soubor skillu, včetně úvodního YAML bloku mezi ---). Soubor je kvůli délce rozdělený do dvou bloků – spojte je za sebe bez úprav.

---

name: dance

description: Práce s datovým modelem Signals Dance (GA4 export → BigQuery přes Dataform, vrstvy L1/L2/L3). Použij vždy, když uživatel chce cokoliv spočítat, vysvětlit nebo upravit nad Dance daty – analýzy návštěvnosti, zdrojů, bounce rate, transakcí, produktů, stránek nebo funnelů nad tabulkami L3_dance / L2_dance_vw / L1_dance, úpravy includes/config.js (nová GA4 property, event parametry, konverzní eventy, měny, timezone, AB test, user stitching), vysvětlení jak se počítá L1_model_base, privacy Cookies vs. Anonymous, session_source atribuce, checkpoint/recalc, backfill nebo dataform compile. Trigger i na slova dance, L1_model_base, L2_sessions, L2_events, L3_acquisition_traffic, dataset_id, unique_session_id, session_channel_grouping, reporting_transaction_revenue, config.js, SPECIFIKA PROJEKTU – a obecně na jakoukoliv práci v repu pojmenovaném *-dance, i když uživatel slovo „Dance" nepoužije.

---

# Signals Dance – práce s modelem a daty

Dance je Dataform projekt, který z GA4 BigQuery exportu (`events_*`) staví tři vrstvy:

|---|---|---|---|

| **L1** | `L1_dance`, `L1_dance_vw` | 1 řádek = GA4 event, obohacený o session atribuci, privacy, pivotnuté parametry | jen debugging nápočtu, atypické dotazy, které L2/L3 nepokryjí |

Každý klient Signals má vlastní kopii repa (`<klient>-dance`) s jiným GCP projektem, jinými `dataset_id`, měnami a někdy jinou sadou modulů. **Nikdy nepředpokládej, co v repu je – vždy si to nejdřív ověř** (krok 1 níže)
`<klient>-dance`) s jiným GCP projektem, jinými `dataset_id`, měnami a někdy jinou sadou modulů. **Nikdy nepředpokládej, co v repu je – vždy si to nejdřív ověř** (krok 1 níže).

## 1. Než začneš: zjisti kontext repa (vždy, ~1 minuta)

1. **GCP projekt** = `defaultDatabase` v `dataform.json`. Všechny tabulky jsou `` `<projekt>.<dataset>.<tabulka>` ``, např. `` `signalscz-dance.L3_dance.L3_acquisition_traffic` ``.

2. **GA4 property** = `ga4.events[]` v `includes/config.js` → pole `schema` je `dataset_id` (např. `analytics_243381983`), `currency` je lokální měna dat. Mapování `dataset_id → domain` je v `dataset_id_to_domain.sql_case`.

3. **Reporting měna** = `reporting_currency` v config.js (typicky `'CZK'`). Sloupce `reporting_*` jsou přepočtené do ní.

4. **Které moduly klient má** = `ls definitions/` + příslušné `enabled` flagy v config.js. Core je jen `definitions/core/`. Vše ostatní (`ab_testing/`, `L3_attribution/`, `shoptet/`, `core/L1_identity/`, `core/L1_gads/`, `core/L2_gads/`) je **volitelné a zdaleka ne každý klient to má** – viz sekce 5.

5. Pokud máš přístup do BigQuery, ověř existenci tabulek přes `INFORMATION_SCHEMA.TABLES` daného datasetu místo hádání. Před drahým dotazem udělej dry run (`bq query --dry_run`) – L1/L2 tabulky jsou velké.

Pokud uživatel nemá repo (jen BigQuery), zjisti projekt a dataset_id z `INFORMATION_SCHEMA` nebo se zeptej – a pracuj jen s částí „Analýzy".

## 2. Rozcestník

| Uživatel chce… | Otevři |

|---|---|

| spočítat metriku, udělat report, napsat SQL nad Dance daty | [references/analyzy.md](references/analyzy.md) → pak katalog [references/tabulky-L3.md](references/tabulky-L3.md), případně [references/tabulky-L2-L1.md](references/tabulky-L2-L1.md) |

| pochopit, proč číslo vyšlo tak, jak vyšlo (atribuce, privacy, duplicity, chybějící den) | [references/architektura.md](references/architektura.md) |

| přidat GA4 property, event parametr, user property, konverzní event, měnu, timezone, custom sloupec, CMP event | [references/config.md](references/config.md) |

| přidat / ukončit AB test, zapnout user stitching, řešit atribuci, Shoptet, Google Ads | [references/moduly-volitelne.md](references/moduly-volitelne.md) |

| upravit nebo napsat nový `.sqlx` model | [references/architektura.md](references/architektura.md) (checkpoint pattern, tagy, konvence) + skill `dataform`, pokud je k dispozici |

| backfill, přepočet historie, intraday | [references/architektura.md](references/architektura.md) → sekce Checkpoint a backfill |

## 3. Zlatá pravidla analý
## 3. Zlatá pravidla analýz

Tohle jsou věci, na kterých se v Dance nejčastěji dělají chyby. Detail a příklady SQL jsou v `references/analyzy.md`.

1. **L3 → L2_vw → L1_vw, v tomto pořadí.** L3 je levné, konzistentní s reporty a už řeší dedup transakcí, přepočet měn i anonymní atribuci. Do L2 jdi, jen když L3 nemá potřebnou dimenzi; do L1 jen pro debugging. Raw GA4 `events_*` nepoužívej vůbec, pokud nejde o ověření nápočtu L1.

2. **Vždy filtruj `event_date`** (partition sloupec všech L1–L3 tabulek) a typicky i `dataset_id`. Bez toho skenuješ celou historii.

3. **Privacy = dvě různé populace.** `Cookies` = uživatel s consentem, máme `user_pseudo_id`, `unique_session_id`, plnou session atribuci. `Anonymous` = bez consentu, **žádná identita uživatele ani session** – „session" je odhad přes `session_start` (page_view s externím referrerem), user_count pro Anonymous neexistuje. Čísla vždy vykazuj rozpadnutá po `privacy`, nebo výslovně řekni, že je sčítáš.

4. **Tržby: `transaction_revenue` je v lokální měně datasetu, `reporting_transaction_revenue` v reporting měně.** Pro součty přes více datasetů/měn použij vždy `reporting_*` (může být NULL, když chybí kurz – hlídej `COUNTIF(reporting_x IS NULL)`).

5. **`session_count` není aditivní přes dimenze, které nejsou vlastností session.** V `L3_engagement_events` (per event_name), `L3_pages_performance` (per stránka) nebo `L3_cookies_engagement_pages` (per page_path) je jedna session ve víc řádcích. Celkový počet sessions ber z `L3_acquisition_traffic` nebo `L3_bounce_rate_daily`.

6. **Poslední ~3 dny se denně přepočítávají** (checkpoint pattern) a při intraday běhu i dnešek. Včerejšek není finální; pro srovnání období ber uzavřené dny.

7. **Transakce dedupuj přes `transaction_id`**, `"(not set)"` vyřaď. `L3_monetization_transactions` už je deduplikovaná (1 řádek = transakce) – pro počet objednávek a AOV jdi tam.

8. **Zdroj/medium/kampaň**: v `L3_acquisition_traffic` jsou lowercase, jinde ne – při joinech použij `LOWER()`. Channel grouping (`session_channel_grouping`) je jen v L1/L2; L3 ho nemá, dopočítej z source/medium (logika je v `includes/snippets.js`).

9. Výsledek analýzy vždy doprovoď: která tabulka, které privacy, jaké období, v jaké měně, a co je odhad (Anonymous). Uživatel často neví, že GA4 UI a Dance se liší právě v Anonymous.

## 4. Zlatá pravidla úprav modelu

1. **Konfigurace před SQL.** Naprostá většina klientských úprav (nová property, parametr, konverze, měna, timezone, AB test, identity) je změna v `includes/config.js` nebo `includes/ab_tests_config.js`, ne v `.sqlx`. Model je napsaný tak, aby se SQLX nemuselo sahat – SQL se generuje z configu.

2. **Nejdřív přečti, co v repu reálně je.** Každé klientské repo je kopie template s vlastními úpravami – ověř aktuální stav configu, modulů a bloků `SPECIFIKA PROJEKTU`, než navrhneš změnu.

3. **`no_edit_zone_start` … `no_edit_zone_end`** v config.js je sdílená logika (backfill, dedup GA4 shardů, UNION properties). Neupravuj, pokud to uživatel výslovně nechce a nerozumí důsledkům.

4. **Klientské odchylky patří do bloku `SPECIFIKA PROJEKTU`** na začátku každého souboru. Když měníš chování pro klienta, zapiš tam co a proč – tam se to hledá při dalším nasazení.

5. **Po každé změně configu zkompiluj** (`npx @dataform/cli compile`, nebo `dataform compile`, nebo Dataform workspace v GCP). `identity.validate()` a `ab_testing.validate()` shodí compile s českou hláškou, když je config nekonzistentní (např. parametr chybí v pivotu) – to je záměr, čti hlášku.

6. **Přidání parametru/property do pivotu mění schéma `L1_model_base`.** Historie sloupec nemá, dokud se neudělá backfill (`--vars=backfill_date=YYYY-MM-DD --tags=L1_backfill` den po dni) nebo full refresh. Řekni to uživateli dopředu, včetně dopadu na náklady.

7. **Buď chirurgický.** Každé klientské repo se od template liší; neopravuj „cizí" věci, které nesouvisí s úkolem, jen je zmiň. Zachovej styl (komentáře česky, uppercase SQL keywords v L1, `GROUP BY ALL`).

8. Neexistuje sdílený npm balíček – moduly se mezi repy kopírují jako celek. Když kopíruješ modul, projdi jeho onboarding checklist (AB testing ho má v `definitions/ab_testing/docs/ab_testing_metodika.md`).

## 5. Volitelné moduly – jak poznat, že klient je má

| Modul | Poznávací znamení | Co dává |

|---|---|---|

| **User stitching (identity graph)** | `definitions/core/L1_identity/`, `config.identity.enabled = true`, tabulka `L1_dance.L1_customer_map` | `master_customer_id`, `is_stitched` ve `*_vw` views; cross-device pohled na zákazníka |

| **AB testování** | `definitions/ab_testing/`, `includes/ab_tests_config.js`, `config.ab_testing.enabled`, dataset `ab_testing` | `L3_ab_evaluation` (integrita), `L3_ab_metric_evaluation` (verdikt vítěze), user-level statistika |

| **Atribuce** | `definitions/L3_attribution/`, dataset `L3_attribution` | first/last/linear/position/time-decay + Shapley modely nad cestami sessions |

| **Shoptet** | `definitions/shoptet/`, `includes/shoptet_config.js`, dataset `shoptet` | objednávky, položky, kupóny, marže z CSV exportů Shoptetu |

| **Google Ads vrstva** | `definitions/core/L1_gads/`, `L2_gads/`, `includes/gads_config.js` | reportingová vrstva nad Google Ads transferem (pozor: v template má placeholder účty `XXXXXXXXXX`) |

(pokračování souboru

SKILL.md⁠

)

| **Cost monitoring** | `definitions/L1_monitoring/`, dataset `cost_monitoring` | náklady BigQuery jobů per tabulka/den |

| **Anomálie** | `definitions/core/L3_dance/L3_anomalies.sqlx` | **DEMO se syntetickými daty** – nikdy nepoužívej k reálné analýze, pokud klient nemá produkční verzi |

Podrobný popis, konfigurace a analytické pokyny: [references/moduly-volitelne.md](references/moduly-volitelne.md). Když modul v repu není, řekni to uživateli a nenabízej dotazy nad neexistujícími tabulkami.

Jádro core (má každý klient): `L1_model_base`, `L1_user_sources`, `L1_exchange_rates`, `L1_gads_gclid_clicks` (+ `L1_gads_campaigns/adgroups`), L2 sessions/events/items + views, L2_anonym_* (anonymní atribuce transakcí), všechny `L3_dance` tabulky mimo `L3_anomalies`.

## 6. Reference

- [references/architektura.md](references/architektura.md) – jak vzniká L1_model_base (privacy, session atribuce, Cookies vs. Anonymous větev, gclid/srsltid přepis), checkpoint & recalc tabulka, intraday, backfill, tagy, konvence sloupců.

- [references/config.md](references/config.md) – anatomie `includes/config.js` blok po bloku, návody: nová GA4 property, nový parametr, konverze per dataset, měna, timezone, custom sloupce, CMP.

- [references/tabulky-L3.md](references/tabulky-L3.md) – katalog L3 tabulek: grain, metriky, zdroj, omezení, ukázkové dotazy.

- [references/tabulky-L2-L1.md](references/tabulky-L2-L1.md) – L2 sessions/events/items a jejich `_vw`, klíčové sloupce L1_model_base_vw, kdy sáhnout níž.

- [references/analyzy.md](references/analyzy.md) – recepty: otázka → tabulka → SQL, časté chyby, kontrola konzistence, práce s náklady.

- [references/moduly-volitelne.md](references/moduly-volitelne.md) – identity, AB testing, atribuce, Shoptet, Google Ads, monitoring.