Wiki

Kosiky.md

@@ -0,0 +1,76 @@
+# Košíky (FunnelCart)
+
+## Model
+
+`App\Models\FunnelCart` – tabulka `funnel_carts`
+
+| Sloupec | Typ | Popis |
+|---------|-----|-------|
+| `id` | bigint | PK |
+| `team_id` | bigint | Příslušnost k týmu |
+| `tracking_site_id` | bigint | Příslušný web/eshop |
+| `visitor_id` | string | ID anonymního návštěvníka |
+| `contact_id` | bigint | Propojený kontakt (nullable) |
+| `status` | string | `open` / `empty` / `converted` / `expired` |
+| `items` | json | Pole položek košíku |
+| `currency` | string | ISO kód měny |
+| `total_no_tax` | decimal | Celková suma bez DPH |
+| `shipping_fee_no_tax` | decimal | Cena dopravy bez DPH |
+| `cod_fee_no_tax` | decimal | Poplatek za dobírku bez DPH |
+| `shipping_label` | string | Název dopravce |
+| `first_seen_at` | timestamp | Kdy košík vznikl |
+| `last_seen_at` | timestamp | Poslední aktivita |
+| `completed_at` | timestamp | Kdy byl dokončen |
+| `is_completed` | boolean | Flag dokončení |
+| `is_expired` | boolean | Flag expirování |
+
+## Formát položky košíku (`items[]`)
+
+```json
+{
+  "code": "PROD-001",
+  "name": "Název produktu",
+  "qty": 2,
+  "unit_no_tax": 99.00,
+  "total_no_tax": 198.00,
+  "url": "https://eshop.cz/produkt",
+  "package": {}
+}
+```
+
+## Stavy košíku
+
+```
+open      – košík má položky, zákazník nakupuje
+empty     – košík byl vyprázdněn
+converted – objednávka dokončena
+expired   – košík expiroval (job ExpireFunnelCarts)
+```
+
+## Browser tracking (collect.js)
+
+Košíky z prohlížeče jdou přes dva endpointy:
+
+- **`POST /api/cart`** – `CartController` – upsert košíku (event `cart_upsert`)
+- **`POST /api/cart/complete`** – `CartCompleteController` – dokončení (event `cart_completed`)
+
+Deduplikace přes `external_event_id` ve formátu `cart:{id}:cart_upsert:{hash}` kde hash je SHA1 z obsahu (kódy produktů, množství, ceny, měna).
+
+## Server-to-server (eshop API)
+
+Viz samostatná stránka [Integrace Eshop API](Integrace-Eshop-API).
+
+- **`POST /api/eshop/cart`** – `EshopCartController` – párování podle emailu
+- **`POST /api/eshop/order`** – `EshopOrderController` – dokončení podle emailu
+
+## Expirování košíků
+
+Job `ExpireFunnelCartsJob` (command `ExpireFunnelCarts`) pravidelně označuje staré otevřené košíky jako `expired`.
+
+## Statistiky
+
+Denní statistiky košíků se agregují do:
+- `campaign_cart_daily_stats` – košíky per kampaň
+- `product_group_cart_daily_stats` – košíky per produktová skupina
+
+Rebuild přes command `RebuildCampaignCartDailyStats` / `RebuildProductGroupCartDailyStats`.