# 01 - Prehled a stav ## Co aplikace je Web a klientsky portal IT firmy. Verejna cast prodava sluzbu, cast za prihlasenim ukazuje klientovi stav jeho automatizaci, ticketu a incidentu. Vse je jedna aplikace v jednom containeru. Express obsluhuje API i zbuildovanou React aplikaci ze slozky `dist/public`. ## Stav | Oblast | Stav | Poznamka | | ------------------------------- | -------- | ------------------------------------------------------- | | Verejny web | hotovo | homepage, sluzby, o nas, kontakt, 404 | | Prihlaseni | hotovo | JWT, demo ucty | | Dashboard | hotovo | prehled, tickety, incidenty, automatizace, nastaveni | | Zivy dashboard pres SSE | hotovo | zmeny se projevi bez obnoveni stranky | | Katalog sluzeb | hotovo | 34 sluzeb, 7 kategorii vcetne Obecne | | Builder automatizaci | hotovo | strom akci, vetveni podminkou | | Webhook s registrovanou adresou | hotovo | token generuje server, verejny endpoint validuje data | | Tickety na konkretni lidi | hotovo | resitel je clen firmy, filtr moje, prehled vytizeni | | Prijem udalosti do ticketu | hotovo | webhook na firmu, externi ID unikatni za firmu | | Udalosti na ticketu | hotovo | dalsi zprava se navesi na tentyz ticket | | Statistiky resitelu | hotovo | odbaveno, mediany casu, vracene, fronta | | Pohledy tabulka a dlazdice | hotovo | tickety i lide | | Stranka Lide a detail osoby | hotovo | sprava clenu firmy, vykon a co ma u sebe | | Log ticketu ve strome | hotovo | vcetne toho, co ktera sluzba vratila | | Kanaly do ticketu | hotovo | WhatsApp, e-mail, hlas a formular jako spoustece | | Parametry od sluzby | hotovo | katalog je deklaruje, server je dosazuje pri ulozeni | | Nastaveni poli akci | castecne | ticket, e-mail a WhatsApp ano, ostatni jen napoveda | | Obsah ticketu a sablony | hotovo | `{{parametr}}` ze spoustece do poli akce | | 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 | | Skripty konektoru | hotovo | manifest, kontrola parametru, hot reload, iDoklad | | Napojeni na realne sluzby | hotovo | 13 sluzeb ma bezici aplikaci, udaje a overeni | | Odesilani souboru ze skriptu | hotovo | `ctx.http.postForm`, obsah jako Base64 | | OpenAI pod vlastnim klicem | hotovo | dotaz, soubor, prepis zvuku, seznam modelu | | Konektory za firmu | hotovo | pristupove udaje v konektoru, overeni napojeni | | Pojistka proti padu portalu | hotovo | pad shodi jen svoji cast a sam zalozi incident | | MCP servery firmy | hotovo | obecna sluzba a MCP EasyWebu vcetne klice zarizeni | | Transformace dat | hotovo | pravidla i sablona JSON, kroky si predavaji struktury | | Prace nad celym modelem | hotovo | ukazka tela, cesty v sablonach, smycka nad seznamem | | Vlastni skripty firmy | hotovo | prevod dat v JS, v logu vstup i vystup | | Sprava clenstvi z portalu | hotovo | firmy a role v Nastaveni, lide a pozvanky v Lidech | | Role a prava jako data | hotovo | 26 prav v katalogu, vlastni role za firmu | | Zalozky a limity za firmu | hotovo | navigace chodi ze serveru, ne z kodu klienta | | Osoby a skupiny resitelu | hotovo | resitel je clenstvi uctu, ticket jde i na skupinu | | Prevzeti ticketu ze skupiny | hotovo | kdo ma cas, si praci vezme sam | | Pozvanky do firmy | hotovo | odkaz s kodem, heslo si nastavi pozvany | | Typy ticketu a vlastni pole | hotovo | typ rozhoduje, ktere akce se na ticketu ukazou | | Vydefinovane akce na ticketu | hotovo | vazba na typ nebo tag, telo je operace, strom, skript | | Vlastni widgety | hotovo | vcetne zdroje z konektoru a vykonu resitelu | | Telo akce jako strom | hotovo | tentyz editor jako automatizace | | Audit a prepnuti na jiny ucet | hotovo | prepnuti je vychozi jen pro cteni, vse v auditu | | Bugs a wishes | chybi | vyvojarska agenda, samostatna evidence vedle ticketu | | Beh automatizaci | hotovo | fronta, worker, opakovani, ochrana proti smycce | | Prijem udalosti do fronty | hotovo | webhook odpovi 202, praci dela worker | | Pravidelne dotazovani sluzeb | hotovo | planovac pro postu a zpravy, perioda u spoustece | | Upozorneni na pridelenou praci | hotovo | cislo u zalozky a hlaska v portalu | | Incident z chyby | hotovo | popis pro klienta, podrobnosti pro admina | | Uloziste konektoru | hotovo | Postgres, nebo JSON soubor. Udaje vzdy sifrovane | | Uloziste pro zbytek | hotovo | tickety, automatizace, incidenty, rozlozeni, entity | | Monetizace a cena za krok | navrh | popis v 16-monetizace.md, neni naprogramovane | | Helpdesk pro zadavatele | hotovo | pozadavek vidi zadavatel i resitel, kazdy ze sve strany | | Odesilani e-mailu pres SMTP | hotovo | konektor se schrankou firmy, HTML telo s promennymi | | Odesilani e-mailu z formulare | chybi | poptavka se zatim jen loguje | | Jeden rezim uloziste | hotovo | `initStores` rozhoduje pro vsechna uloziste naraz | | Zapisy serazene za sebou | hotovo | `withMirror` radi zapisy tehoz zaznamu, audit se oreza | | Worker jako pool | hotovo | ctyri behy naraz nezavisle, tlukot, opakovani jen kdyz ma smysl | | Prava za firmu u kazde route | hotovo | firmy, uzivatele, konektory, automatizace, akce ticketu | | Udalosti za firmu | hotovo | stream filtruje, entity hlasi vznik, zmenu a smazani | | Strankovani ticketu a behu | hotovo | `limit`, `offset`, `X-Total-Count` | | Klientsky sklad ciselniku | hotovo | lide, skupiny, typy, sluzby, konektory, pristup | | Formularova vrstva | hotovo | `ui/form`, `useSubmit`, `options`, jedna sada trid | | Firma z registru ARES | hotovo | IC nebo nazev, statutari jako ucty, jen spravce platformy | | Sdilene typy `src/shared` | hotovo | web je re-exportuje pres `@shared/*`, nic nekopiruje | | Struktura podle zasad | hotovo | `index.ts` a `app.ts`, routy a data po slozkach, `connectors/` | | Lint a formatovani v repu | hotovo | eslint a prettier, `npm run lint` cisty bez vyjimek | | Prisny TypeScript | hotovo | `noUncheckedIndexedAccess` v obou tsconfig, zadne `!` | | Testy | castecne | vitest v `tests/`, 8 souboru a 105 testu: prava, tickety, executor, sit, health | ## Znama omezeni Data prezijou restart, ale ne redeploy, kdyz neni databaze. Rezim se pozna v portalu i v `/health/ready` a rozhoduje o nem jedno misto, viz [14-databaze.md](14-databaze.md): | Rezim | Kdy | Nasledek | | ---------- | ------------------------------------------------- | ---------------------------- | | `postgres` | je `DATABASE_URL`, migrace prosly a je cim sifrovat | data se neztraci | | `file` | neni databaze, je `DATA_DIR` | prezije restart, ne redeploy | | `memory` | neni ani `DATA_DIR` | ztrati se pri restartu | Rezim je jeden pro vsechna uloziste vcetne konektoru. Driv se mohlo stat, ze konektory jely z databaze a tickety ze souboru. Beh automatizaci jde pres frontu a worker: webhook odpovi 202 a strom se vykona na pozadi, pri chybe se opakuje jen to, co muze pominout. Fronta je ale **v pameti jednoho procesu**: vic instanci by si vzalo tentyz beh, nad Postgresem to chce `SKIP LOCKED`. Popis je v [20-fronta-a-runtime.md](20-fronta-a-runtime.md), rozbor kapacity v [19-kapacita-200-firem.md](19-kapacita-200-firem.md). Limity requestu (prihlaseni, kontakt, pozvanky) jsou v pameti jedne instance, stejne jako stream. Pri vice instancich by kazda pocitala zvlast. Obsah verejneho webu je ukazkovy. Nazev firmy, reference, tym i cisla jsou vymyslene a pred ostrym pouzitim se musi nahradit. Firemni udaje jsou na jednom miste v `web/src/config/brand.ts`. Zivy stream drzi seznam posluchacu v pameti jedne instance. Pri vice instancich by ho musel nahradit sdileny kanal, napriklad Redis pub/sub. Log ticketu uz plni skutecny beh: kazdy krok stromu se do nej zapise vcetne toho, co sluzba vratila. Ukazkova sada ticketu ma log psany rucne, aby bylo co ukazat i na prazdne instanci. ### Znamy stav proti zasadam Projekt se ridi `D:\GitHubRepository\CLAUDE.md`. Kde se od nej lisi, je to zamer nebo odlozena prace, ne opomenuti: | Odchylka | Proc a co s tim | | ------------------------------------------ | ------------------------------------------------------------------------------- | | jeden `package.json` pro server i web | mala aplikace v jednom containeru; workspaces az bude mit kazda strana vlastni build | | logovani `console.*` s prefixem modulu | strukturovany logger (`pino`) zatim neni potreba, prefix `[modul]` staci k dohledani | | zadny soubor CI | lint, typecheck a testy se spousti rucne se svolenim (pravidlo 2) | | testy jen na cast logiky | pokryta prava, tickety, executor, cteni tela a health; routy nastaveni a runtime fronty cekaji | | ctyri soubory nad 500 radku | `AutomationDetail`, `TicketDetail`, `MappingEditor`, `catalog/ticket.ts`; duvod v [03-architektura-a-mapa-kodu.md](03-architektura-a-mapa-kodu.md) | ## Dalsi krok Runtime je hotovy: fronta, worker jako pool, opakovani jen u chyb, ktere mohou pominout, incident z koncove chyby. Dalsi krok je **vic instanci**, tedy vyber z fronty nad Postgresem se `SKIP LOCKED`, sdileny kanal pro stream a sdileny citac limitu requestu. Vedle toho zbyva prevest na `inputs` i ostatni konektory. Podrobnosti v [05-dashboard-a-builder.md](05-dashboard-a-builder.md). Za rozmysleni stoji evidence bugs a wishes. Zamerne to nejsou tickety, duvod je v [06-tickety.md](06-tickety.md). Datove modely a prava z [09-navrh-rozsireni.md](09-navrh-rozsireni.md) jsou hotove, popis stavu je v [17-nastaveni-a-prava.md](17-nastaveni-a-prava.md). Navrh k rozhodnuti zustava [10-runtime-a-kapacita.md](10-runtime-a-kapacita.md) pro frontu, beh kroku a rozpocet na 150 klientu, a [16-monetizace.md](16-monetizace.md) pro cenu za krok. ## Dokumentace | Soubor | O cem | | ---------------------------------------------------------------- | ----------------------------------------------- | | [00-pro-programatory.md](00-pro-programatory.md) | rozcestnik a duvody rozhodnuti | | [02-appfactory-proxy.md](02-appfactory-proxy.md) | beh za reverse proxy, ROOT_PATH, health | | [03-architektura-a-mapa-kodu.md](03-architektura-a-mapa-kodu.md) | kde co je | | [04-api.md](04-api.md) | endpointy a to, co ze Swaggeru neni videt | | [05-dashboard-a-builder.md](05-dashboard-a-builder.md) | editor automatizaci | | [06-tickety.md](06-tickety.md) | model ticketu a log prubehu | | [07-firmy-a-prava.md](07-firmy-a-prava.md) | firmy, pohledy, kdo co vidi | | [08-dashboard-widgety.md](08-dashboard-widgety.md) | nastavitelny prehled | | [09-navrh-rozsireni.md](09-navrh-rozsireni.md) | puvodni navrh rozsireni | | [10-runtime-a-kapacita.md](10-runtime-a-kapacita.md) | **navrh**: fronta, beh kroku, kapacita | | [11-skripty-konektoru.md](11-skripty-konektoru.md) | vykonna cast sluzeb | | [12-sluzby-a-konektory.md](12-sluzby-a-konektory.md) | sluzba, konektor, viditelnost | | [13-transformace-dat.md](13-transformace-dat.md) | pole na pole a JSON na JSON | | [14-databaze.md](14-databaze.md) | tri rezimy uloziste, migrace, sifrovani | | [15-rejstrik-funkci.md](15-rejstrik-funkci.md) | k cemu je jaka funkce a komponenta | | [16-monetizace.md](16-monetizace.md) | **navrh**: cena za krok a balicky | | [17-nastaveni-a-prava.md](17-nastaveni-a-prava.md) | prava, typy, akce, widgety, prepnuti uctu | | [18-ticketovaci-system.md](18-ticketovaci-system.md) | udalosti, externi ID, statistiky, pohledy | | [19-kapacita-200-firem.md](19-kapacita-200-firem.md) | zmereno, co zvladne soucasny stav | | [20-fronta-a-runtime.md](20-fronta-a-runtime.md) | fronta, worker, spoustece, ochrana proti smycce | | [21-realne-sluzby.md](21-realne-sluzby.md) | napojeni na bezici aplikace a e-mail | | [22-znacka-a-design.md](22-znacka-a-design.md) | znacka WorkNuke, tokeny, prvky | | [23-jazyky.md](23-jazyky.md) | prepinani jazyku a slovniky | | [24-mcp-konektory.md](24-mcp-konektory.md) | MCP servery firmy jako kroky | | [25-navrh-pristupny-portal.md](25-navrh-pristupny-portal.md) | **navrh**: prehled, formulare, hledani, viditelnost | | [99-zmeny.md](99-zmeny.md) | zaznam zmen, nejnovejsi nahore |