# 05 - Dashboard, builder automatizaci a simulace

## Stranky portalu

```
/dashboard                  prehled: dlazdice, graf za 14 dni, posledni tickety a incidenty
/dashboard/automatizace     seznam a zalozeni nove
/dashboard/automatizace/:id builder: strom akci
/dashboard/konektory        katalog sluzeb, jejich spousteču a akci
/dashboard/tickety          seznam, filtry, prehled vytizeni tymu
/dashboard/tickety/:id      detail ticketu: prubeh a log, resitel, zakaznik
/dashboard/incidenty        prehled incidentu
/dashboard/nastaveni        udaje o uctu
```

V postrannim menu je pod Nastavenim tlacitko **Simulace**.

## Zivy dashboard

Portal drzi jedno SSE spojeni pro celou aplikaci. Zajistuje ho
`EventStreamProvider` v `web/src/components/dashboard/`.

- Stav spojeni ukazuje `LiveIndicator` v horni liste. Uzivatel musi poznat,
  ze data nejsou ziva.
- Prichozi udalosti ukazuje `EventToasts` jako bubliny vpravo dole.
- Data se obnovuji sama. `useApiQuery` ma volitelny `refetchOn` se seznamem typu
  udalosti, po kterych se ma dotaz zopakovat. Vice udalosti tesne po sobe se
  slouci do jednoho nacteni - debounce 150 ms je **spolecny pro vsechny
  hooky**, takze jedna udalost je jedna vlna requestu, ne pet v peti chvilich.

Pri vypadku se stream znovu pripojuje s exponencialne rostoucim odstupem
az do 15 sekund, aby pri vypadku serveru neubijel provoz. Na 401 a 403 se
pripojovat prestane: token vyprsel a klient vyvola `auth:expired`, po kterem
se portal odhlasi a Login rekne, ze prihlaseni vyprselo.

### Obnova neodmontuje stranku

`useApiQuery` vraci `loading` jen **do prvnich dat**, potom uz `refreshing`.
`DataState` pri `refreshing` nechava deti vykreslene a jen ukaze, ze bezi
obnova. Prvni verze prepnula `loading` pri kazde udalosti ze streamu a
`DataState` vykreslil spinner misto obsahu - pri behu automatizace se stranka
nekolikrat za sekundu odmontovala a namontovala, vcetne ztraty kurzoru
v rozepsanem poli.

```ts
useApiQuery<T>(path, { refetchOn?, body?, enabled?, patchOn? })
  -> { data, loading, refreshing, error, total, reload }
```

Dotazy sdili cache modulu a deduplikaci bezicich requestu (klic je firma,
cesta a telo), takze dve komponenty se stejnym dotazem se ptaji jednou.
`patchOn` opravi data v cache primo z udalosti: `lib/ticketEvents.ts` bere
`payload.ticket` z `ticket.updated` a vymeni radek v seznamu bez dotazu.

### Ciselniky jsou v klientskem skladu

Lide, skupiny, typy ticketu, sluzby, konektory a pristup se nectou stranka po
strance, ale ze skladu `lib/collections.tsx`: `useCollection(key)`,
`useAccess()`, `useCollectionSelector`. Kolekce se nacte pri prvnim pouziti,
vymaze se pri prepnuti firmy a odhlaseni a **opravuje se z udalosti entit**
(`person.updated` a podobne): zaznam z payloadu se vlozi nebo smaze, a kdyz
payload zaznam nenese, nacte se ta jedna kolekce znovu.

Rozhodnuti majitele produktu je stredni cesta: ciselniky do skladu, **tickety,
behy a statistiky zustavaji dotazy na server** se strankovanim. Jsou velke,
meni se porad a strop viditelnosti pocita server - klientska kopie by je
ukazovala jinak nez prehled vytizeni.

Filtry seznamu ticketu jsou v URL. Nalez jde poslat kolegovi a tlacitko zpet
vrati predchozi filtr; driv byl filtr stav stranky a po obnoveni zmizel.

## Simulace provozu

Modalni okno se otevre tlacitkem Simulace. Umoznuje:

- zalozit ticket z vybraneho kanalu vcetne celeho logu, ktery k nemu vede,
  a s prepinacem, jestli se zakaznik v CRM dohleda nebo ne,
- vyvolat incident s vlastnim popisem, sluzbou a zavaznosti,
- vyresit prvni nevyrizeny ticket nebo bezici incident,
- spustit automatizaci uspesne nebo s chybou.

Kazda akce opravdu meni data na serveru, takze se projevi i v seznamech
a v souhrnu, ne jen v bublinach.

## Strom akci

Automatizace se sklada z **spoustece** a **kroku**. Krok je bud akce nad
konektorem, nebo podminka se dvema vetvemi - proto je to strom, ne seznam.

```ts
interface AutomationFlow {
  trigger: {
    connectorId: string;
    operationId: string;
    fields: TriggerField[];   // vstupni parametry
    webhookToken?: string;    // generuje vyhradne server
  } | null;
  steps: FlowStep[];
}

type FlowStep =
  | { id: string; kind: 'action'; connectorId: string; operationId: string }
  | { id: string; kind: 'condition'; fieldId: string; operator: string;
      value?: string; yes: FlowStep[]; no: FlowStep[] };
```

Podminka odkazuje na `field.id`, ne na nazev. Prejmenovani parametru proto
existujici podminky nerozbije.

Misto vlozeni urcuje `FlowPath` v `web/src/lib/flow.ts`: prazdne pole je hlavni
sekvence, `[{ stepId, branch }]` je vetev konkretni podminky.

## Odkud se berou vstupni parametry

Jsou dva druhy spousteču a lisi se tim, kdo urcuje jejich parametry.

**Parametry deklaruje uzivatel** (webhook, formular). V katalogu maji
`customPayload: true`. V builderu se pridavaji rucne: nazev, typ (text, cislo,
ano-ne, datum) a povinnost.

**Parametry urcuje sluzba** (e-mail, WhatsApp, hlasova linka, ticket). V katalogu
je nese `providedFields`. Builder je ukazuje jen ke cteni a server je pri ulozeni
stromu vzdy dosadi z katalogu, jeste pred validaci. Podrobnosti a duvody jsou
v [06-tickety.md](06-tickety.md), sekce "Parametry od sluzby".

U spoustece typu webhook vygeneruje server pri ulozeni adresu
`POST <verejna-adresa>/webhook/<token>`.

Podminky pak porovnavaji hodnotu parametru, napriklad `score >= 15`. Nabidka
operatoru se ridi typem, na cislo nejde pustit "obsahuje". Tabulka operatoru je
na obou stranach - `src/data/conditions.ts` a `web/src/lib/flow.ts`. Server je
autorita, kopie na klientovi existuje jen proto, aby UI nenabidlo nesmysl.
**Pri zmene upravit obe.**

Dokud spoustec nema zadny parametr, nejde pridat podminka - nebylo by podle ceho
se rozhodovat. Dialog to vysvetli.

## Sirka karet pri zanoreni

Vetve ANO a NE jsou vedle sebe jen tehdy, kdyz je na to v dane karte misto.
Rozhoduje **sirka karty, ne sirka okna** - pouzivaji se container queries
(`@container` a `@2xl:grid-cols-2` v `FlowCanvas.tsx`).

Karty jsou rozdelene po druhu kroku: `flow/ActionCard.tsx`,
`ConditionCard.tsx`, `ForeachCard.tsx`, `StepControls.tsx`, spolecne typy
v `canvasTypes.ts`. `FlowCanvas.tsx` uz jen sklada. Karty jsou v `memo`,
callbacky se predavaji podle ID kroku a `collectScopes` je memoizovane -
u stromu o padesati krocich byl driv kazdy stisk klavesy v poli prekreslenim
vseho.

Odchod z rozepsaneho stromu hlida `lib/useUnsavedChanges.ts`.

Duvod: kazde zanoreni pulí dostupnou sirku. S beznym `lg:grid-cols-2` vypadal
strom na sirokem monitoru dobre v prvni urovni a ve treti uz mel karty siroke
par desitek pixelu, takze se popisy lamaly po jednom slove. Container query se
od urcite hloubky sama prepne na vetve pod sebou.

Ze stejneho duvodu se v uzke karte skryva popis akce (`hidden @xs:block`),
zmensuje ikona a ovladaci tlacitka se skladaji do sloupce. Nazev kroku
a nastaveni poli zustavaji vzdy videt - to je to podstatne.

**Pri uprave stromu nepouzivat `sm:` / `lg:` na veci uvnitr karet.** Reaguji
na okno a v zanoreni lzou.

## Co je v kterem kroku videt

Krok vidi parametry spoustece **plus vystupy vsech kroku pred nim**. Akce muze
v katalogu deklarovat `outputFields`, napriklad "Dohledat firmu" vraci
`customerKnown` a `companyName`. Podminka i sablona se na ne muzou odkazat.

Vetev podminky nepridava nic do sekvence za podminkou, protoze nemusela
probehnout. Vypocet je v `src/data/flowScope.ts`, kopie pro UI ve `flow.ts`.

Odkaz na parametr, ktery ve strome vubec neni, je **chyba 400**. Odkaz na
parametr, ktery vznika az v pozdejsim kroku (typicky po presunuti kroku), je
**nedodelek** - ulozi se a rekne se, ze podminku staci posunout niz.

## Nastaveni kroku

Akce muze mit nastavitelna pole (`inputs` v katalogu). Vyplnuji se primo na karte
kroku ve strome. Hodnota je sablona, `{{nazev}}` se nahradi parametrem spoustece,
takze jde rict "do obsahu ticketu dej text zpravy z WhatsApp".

Pod poli je nabidka parametru, kliknuti vlozi odkaz na pozici kurzoru.

Zatim to maji ticket, e-mail a WhatsApp. Ostatni akce maji jen `fields`, coz je
pouha napoveda - builder u nich napise, ze je zatim nejde nastavit. Cilovy stav
je prevest vsechny.

Podrobnosti vcetne toho, proc se odkazuje jmenem a ne ID, jsou
v [06-tickety.md](06-tickety.md), sekce "Sablony".

## Validace

Rozlisuji se dve veci:

**Chyby** vraci 400 a neulozi se: neexistujici konektor nebo operace, operace
spatneho druhu, podminka na neexistujici parametr, operator nesedici na typ,
duplicitni nebo nevalidni nazev parametru, nastaveni pole, ktere akce nema.

**Nedodelky** se ulozi, jen brani zapnuti: chybi spoustec, zadny krok, webhook
bez adresy, podminka bez hodnoty, nevyplnene povinne pole akce, sablona
odkazujici na parametr, ktery uz neexistuje. Vraci se v poli `issues` a builder
je vypise. Rozdelana prace se nikdy nezahazuje.

## Pridani konektoru

1. Pridat zaznam do katalogu v `src/data/services.ts` vcetne `triggers`
   a `actions`. ID operace musi byt v ramci sluzby unikatni,
   `checkOperationIds()` duplicitu pri nacteni zaloguje - druha by tise
   prekryla prvni.
2. Pokud pouziva novou ikonu, doplnit klic do `web/src/lib/connectorIcons.ts`.
   Musi existovat v `lucide-react`.
3. Pokud patri do nove kategorie, doplnit ji do `connectorCategories` a do typu
   `ConnectorCategory` na obou stranach.
4. Pokud spoustec predava vlastni data, deklarovat je v `providedFields`. ID
   parametru musi zustat stabilni, odkazuji se na ne podminky v ulozenych stromech.

Builder i katalog ji vezmou automaticky.

## Co chybi

| Chybi                        | Poznamka                                                  |
| ---------------------------- | --------------------------------------------------------- |
| `inputs` u zbylych konektoru | zatim ticket, kanaly, CRM a AI, ostatni maji jen `fields` |
| Drag and drop                | presouvani je zatim tlacitky nahoru a dolu                |
| Strankovani v portalu        | server `limit` a `offset` umi, seznam ticketu si zatim bere vse |

## Co je videt v kterem kroku

Krok vidi parametry spoustece a vystupy kroku pred nim. **Vystupy z vetvi
podminky plati i za podminkou**, jen jako nepovinne - probehla prece jen jedna
vetev.

Diky tomu jde poskladat bezny postup, kde hodnotu dava jednou jedna vetev
a jednou druha:

```
Najit kontakt (podle ICO)
podminka: nenalezeno?
  ano -> Najit kontakt (podle e-mailu)
         podminka: porad nenalezeno?
           ano -> Zalozit kontakt
Vlastni skript: partnerId = prvni vyplnene z ICO / mailu / zalozeni
```

Odkaz se jmenem kroku je jednoznacny (`{{st_ico.contactId}}`), takze dva kroky
se stejne pojmenovanym vystupem si neprekazi. Hole jmeno (`{{contactId}}`)
znamena ten posledni vystup, ktery probehl.

## Prace nad celym modelem

Odesilatel neposila ploche telo. Objednavka ze Shoptetu ma zanoreni, ceny
v podobjektech a seznam polozek - a to je bezny pripad, ne vyjimka.

### Ukazka tela

U spoustece s vlastnimi daty (webhook, formular) se vlepi **telo z realneho
volani**. Server z nej odvodi model, tedy seznam cest i s typy
(`src/data/model.ts`), a ten se v krocich nabizi ke kliknuti.

Neni to kontrakt: telo se nezahodi, kdyz se od ukazky lisi. Je to napoveda pro
cloveka - prave ta u modelu o padesati cestach chybela.

Tlacitko **Doplnit parametry pro podminky** z hodnot v ukazce udela deklarovane
parametry. Podminka se totiz pta na parametr, ne na cestu.

### Odkaz muze byt cesta

| Odkaz                          | Co vrati                        |
| ------------------------------ | ------------------------------- |
| `{{callSid}}`                  | deklarovany parametr, jako driv |
| `{{data.order.code}}`          | hodnotu z prijateho tela        |
| `{{data.order.items[0].name}}` | prvni polozku seznamu           |
| `{{st_faktura.invoiceId}}`     | vystup kroku `st_faktura`       |
| `{{item.amount}}`              | polozku uvnitr smycky           |

Overuje se jen **prvni cast** odkazu. Zbytek je cesta a tu predem overit nejde -
co presne prijde v tele, vime az pri behu. Diky tomu ploche odkazy funguji dal
presne jako driv.

### Pro kazdou polozku

Krok `foreach` projde seznam a za kazdou polozku vykona vnoreny podstrom.

```
Pro kazdou polozku: data.order.items
  +- CRM: upsert produktu   kod {{item.code}}, nazev {{item.name}}
```

Uvnitr je `{{item}}` a `{{index}}`. Po skonceni je
`{{st_loop.results}}` seznam vysledku, kde kazdy zaznam nese `index`,
**celou puvodni polozku** a vystupy kroku:

```json
[{ "index": 0, "item": { "code": "PROD-001", "amount": 2 }, "crmItemId": "42" }]
```

Proc i puvodni polozka: radek objednavky potrebuje jak ID z CRM, tak mnozstvi
z puvodnich dat. Kdyby se neslo obe, muselo by se to znovu parovat podle kodu.

Na tenhle seznam pak jde poslat krok Transformace s prevodem **Za kazdou
polozku seznamu** a poskladat z nej radky objednavky jednim volanim.

**Strop 200 polozek.** Vic uz neni automatizace, ale zatez, kterou nikdo
necekal. Beh se zastavi a rekne to, misto aby seznam tise usekl.

Kdyz na ceste neni seznam, krok selze a v hlasce stoji, co tam misto nej je.