Wiki

Kontakty.md

@@ -0,0 +1,69 @@
+# Kontakty a CRM
+
+## Model Contact
+
+`App\Models\Contact` – tabulka `contacts`
+
+| Sloupec | Typ | Popis |
+|---------|-----|-------|
+| `id` | bigint | PK |
+| `team_id` | bigint | Příslušnost k týmu |
+| `email` | string | E-mail (unikátní per team) |
+| `name` | string | Celé jméno |
+| `phone` | string | Telefon |
+| `source` | string | Zdroj (`web`, `eshop`, `import`...) |
+| `user_id` | string | ID zákazníka v externím systému |
+| `tags` | json | Pole tagů |
+| `flags` | json | Slovník příznaků (user_id, kampaně...) |
+| `traits` | json | Vlastnosti kontaktu |
+| `meta` | json | Libovolná metadata |
+| `identify_token` | string | Token pro identifikaci z emailového odkazu |
+| `last_activity_at` | timestamp | Poslední aktivita |
+| `email_opt_out_at` | timestamp | Datum odhlášení z emailů |
+| `internal` | boolean | Interní kontakt (nezapočítává se do statistik) |
+| `smartemailing_id` | int | ID v SmartEmailing |
+| `vario_ids` | json | ID záznamu v Vario ERP |
+
+## Identifikace (IdentityLinker)
+
+`App\Services\Tracking\IdentityLinker` zajišťuje propojení anonymního `visitor_id` s `Contact`:
+
+```
+visitor_id ──► visitor_identities ──► contact_id
+```
+
+### Metody
+
+- **`identify($teamId, $data)`** – párování podle emailu; vytvoří kontakt pokud neexistuje; backfilluje `contact_id` ke starším eventům
+- **`identifyByToken($teamId, $data)`** – párování přes `ftclid` (click token z emailové kampaně); dohledá `EmailCampaignSend` → `Contact`
+- **`contactIdForVisitor($teamId, $visitorId)`** – rychlý lookup mapping
+
+## Segmenty
+
+`Segment` sdružuje kontakty do skupiny. Každý segment má:
+- **`FunnelColumn`** – sloupce (stavy), ve kterých se kontakt nachází (Kanban-style)
+- **`FunnelRule`** – pravidla pro přechod mezi sloupci
+- **`FunnelState`** – aktuální stav konkrétního kontaktu v segmentu
+
+## Tagy
+
+Kontakty lze tagovat. Tagy jsou uloženy jako JSON pole. Přidávání tagů probíhá přes:
+- `SetTagDriver` (akce automace)
+- `SmartEmailingAddTagDriver` (sync do SmartEmailing)
+- Automaticky při kliknutí na kampaňový email (`email_campaign:{id}`)
+
+## Import kontaktů
+
+- **CSV import** – `ContactsImportCsv` Livewire + `JsonContactImporter`
+- **Vario sync** – `VarioSyncContacts` command / `SyncVarioContactsJob`
+- **SmartEmailing webhook** – `SmartEmailingWebhookController`
+
+## Firmy (Company)
+
+Kontakty mohou být přiřazeny k firmám (`Company` model). Firmy se synchronizují z Vario ERP přes `VarioSyncCompanies`.
+
+## Odhlášení z emailů
+
+- `email_opt_out_at` – globální odhlášení
+- `EmailCategoryUnsubscribe` – odhlášení z konkrétní kategorie emailů
+- Unsubscribe link vede na `UnsubscribeController` nebo `EmailUnsubscribeController` (TOR-friendly doména)