dashboard widgets

2026-08-03 13:10:41 +02:00
parent 2a3d75c85e
commit bbc2236c0d
14 changed files with 1196 additions and 141 deletions
@@ -29,6 +29,7 @@ React aplikaci ze slozky `dist/public`.
 | Vystupy kroku a predvalidace      | hotovo | podminka se umi zeptat, co vratil predchozi krok      |
 | Kanaly WhatsApp, FB, Instagram    | hotovo | vcetne vzorovych automatizaci na prijem               |
 | Firmy a prava                     | hotovo | tri pohledy, uzivatel muze byt ve vic firmach         |
+| Nastavitelny dashboard            | hotovo | widgety, sirky a poradi, ulozene za uzivatele a firmu |
 | Sprava clenstvi z portalu         | chybi  | memberships jdou zmenit jen v kodu                    |
 | Bugs a wishes                     | chybi  | vyvojarska agenda, samostatna evidence vedle ticketu  |
 | Beh automatizaci                  | chybi  | ulozeny strom se nevykonava, neni runtime             |
@@ -43,6 +43,8 @@ image jen `dist`, takze staci jedna slozka.
 | `src/data/people.ts`        | resitele ticketu - oddeleni od uzivatelu portalu         |
 | `src/data/tenants.ts`       | firmy, ktere portal pouzivaji                            |
 | `src/data/access.ts`        | kdo co vidi - jedno misto pro cely portal                |
+| `src/data/widgets.ts`       | katalog widgetu prehledu                                 |
+| `src/data/dashboardLayouts.ts` | rozlozeni dashboardu za dvojici uzivatel a firma      |
 | `src/data/incidentStore.ts` | incidenty vcetne zmen a udalosti                         |
 | `src/data/automationStore.ts` | automatizace, strom akci, tokeny webhooku              |
 | `src/data/connectors.ts`    | katalog konektoru, jejich spousteču a akci               |
@@ -23,6 +23,10 @@ Vyzaduji `Authorization: Bearer <token>`:
 | GET    | `/api/auth/me`                                      |
 | POST   | `/api/auth/logout`                                  |
 | GET    | `/api/dashboard/access`                             |
+| GET    | `/api/dashboard/widgets`                            |
+| GET    | `/api/dashboard/layout`                             |
+| PUT    | `/api/dashboard/layout`                             |
+| DELETE | `/api/dashboard/layout`                             |
 | GET    | `/api/dashboard/summary`                            |
 | GET    | `/api/dashboard/people`                             |
 | GET    | `/api/dashboard/tickets`                            |
@@ -0,0 +1,99 @@
+# 08 - Widgety na prehledu
+
+## Kde se to nastavuje
+
+`/dashboard`, tlacitko **Upravit dashboard** vpravo nahore. V rezimu uprav
+dostane kazdy widget listu s ovladanim:
+
+- vyber sirky (tretina, polovina, cela sirka),
+- sipky vlevo a vpravo pro poradi,
+- kos pro odebrani.
+
+K tomu **Pridat widget** s nabidkou toho, co jeste na dashboardu neni,
+**Vychozi** pro vraceni do puvodniho stavu a **Ulozit** nebo **Zrusit**.
+
+Dokud se neklikne na Ulozit, nic se neuklada. Zrusit vrati puvodni rozlozeni.
+
+## Ulozeni je za dvojici uzivatel a firma
+
+Ne za uzivatele. Clovek ve dvou firmach chce v kazde videt neco jineho
+a smichat mu to dohromady by bylo horsi nez zadne nastaveni.
+
+Klic je `${userId}:${tenantId}`, uloziste je `src/data/dashboardLayouts.ts`.
+Kdo si dashboard jeste neupravil, dostane vychozi rozlozeni a `custom: false`.
+
+## Katalog widgetu
+
+`src/data/widgets.ts`, stejny princip jako katalog konektoru: server je zdroj
+pravdy o tom, co jde na dashboard polozit.
+
+```ts
+interface WidgetDefinition {
+  id: string;
+  name: string;
+  description: string;
+  kind: 'stat' | 'chart' | 'ticketList' | 'incidentList' | 'workload';
+  sizes: WidgetSize[];      // ktere sirky ma smysl nabizet
+  defaultSize: WidgetSize;
+  metric?: ...;             // jen u `stat`: ktere cislo ze souhrnu
+}
+```
+
+`sizes` neni kosmetika. Graf v tretine sloupce se necte, proto tam tretinu
+nenabizime vubec, misto abychom cekali, ze si to uzivatel rozmysli.
+
+`kind` rika klientovi, kterou komponentu vykreslit. Novy druh znamena i novou
+komponentu na webu, proto jich je zamerne malo a jsou obecne. Novy **statisticky**
+widget je naopak jen zaznam v katalogu, zadny kod navic.
+
+## Data si nacita prehled, ne widgety
+
+Widget dostane data v propsu. Kdyby si je nacital sam, deset dlazdic by znamenalo
+deset stejnych dotazu na server.
+
+Prehled drzi ctyri dotazy (souhrn, tickety, incidenty, vytizeni) a rozdava je
+vsem widgetum. Dlazdice, ktera zadna data nepotrebuje, o nich proste nevi.
+
+## Mrizka
+
+Sest sloupcu, sirky mapuji na `col-span`: tretina 2, polovina 3, cela 6.
+Na uzkem displeji zabira vsechno celou sirku.
+
+Pouzivaji se **container queries** (`@container` a `@2xl:`), ne `sm:` a `lg:`.
+Duvod je stejny jako u stromu automatizaci, viz
+[05-dashboard-a-builder.md](05-dashboard-a-builder.md), sekce o sirce karet.
+
+## Validace
+
+Server overuje ulozene rozlozeni proti katalogu:
+
+| Situace                             | Vysledek |
+| ----------------------------------- | -------- |
+| neznamy widget                      | 400      |
+| sirka, kterou widget nepodporuje    | 400      |
+| duplicitni ID instance              | 400      |
+| vic nez 12 widgetu                  | 400      |
+
+Neulozit je tady spravne. Klient by dostal zpatky neco, co neumi vykreslit.
+
+Widget, ktery mezitim z katalogu zmizel, se v prehledu ukaze jako cervena karta
+s jeho ID. Nesmi tise vypadnout z rozlozeni.
+
+## Jak pridat widget
+
+1. Zaznam do `widgets` v `src/data/widgets.ts`.
+2. Kdyz je to `stat`, pridat i metriku do `metricMeta` v `WidgetCard.tsx`
+   a pole do souhrnu, pokud tam jeste neni.
+3. Kdyz je to novy `kind`, dopsat vetev do `WidgetCard.tsx`.
+
+Nabidka i rozlozeni ho vezmou automaticky.
+
+## Co chybi
+
+| Chybi                      | Poznamka                                          |
+| -------------------------- | ------------------------------------------------- |
+| Drag and drop              | poradi se meni sipkami, stejne jako ve strome     |
+| Nastaveni jednotlivych widgetu | napr. kolik radku ukazat, za jake obdobi     |
+| Vlastni metriky            | katalog je pevny, nejde si nadefinovat vlastni    |
+| Sdilene rozlozeni pro firmu| kazdy si upravuje jen to svoje                    |
+| Databaze                   | rozlozeni je v pameti, restart je vrati na vychozi |
@@ -114,6 +114,22 @@ se nikde nevolal. Popis v [07-firmy-a-prava.md](07-firmy-a-prava.md).
  `access.ts`, protoze zavisi na tom, ktera firma pozadavek zajima.
 - Demo ucty pokryvaji vsechny tri situace vcetne cloveka ve dvou firmach.

+### Nastavitelny dashboard
+
+Prehled byl pevne dany. Ted si ho kazdy sklada sam, popis
+v [08-dashboard-widgety.md](08-dashboard-widgety.md).
+
+- Katalog widgetu na serveru vcetne toho, ktere sirky ktery widget unese.
+  Graf v tretine sloupce se necte, proto se tam ani nenabizi.
+- Rezim uprav na `/dashboard`: pridani z nabidky, vyber sirky, poradi sipkami,
+  odebrani. Ulozi se az tlacitkem, Zrusit vrati puvodni stav.
+- Rozlozeni se uklada za **dvojici uzivatel a firma**, ne jen za uzivatele.
+- Data nacita prehled a rozdava je widgetum. Deset dlazdic tak neznamena
+  deset stejnych dotazu.
+- Server rozlozeni overuje proti katalogu. Neznamy widget nebo nepodporovana
+  sirka se neulozi, widget zmizely z katalogu se v prehledu ukaze jako chyba,
+  ne ze tise zmizi.
+
 ### Zapsano jako otevrene rozhodnuti

 Vsechny automatizace se stejnym spoustecem se spusti. Doporucene rozdeleni na to