JiriUhlir
c25e826766
Provozovatel portalu: firma s priznakem portalOperator (jen jedna, zapnuti odebere ostatnim) a novymi poli contactEmail, contactPhone, website vedle ico, dic, adresy a pravni formy. Verejny GET /api/public/brand vraci jeji udaje a web je bere pres useBrand() na kontaktu, v paticce, O nas, prihlaseni i v titulku; brand.ts je jen zaloha. Poptavka z webu zaklada u provozovatele ticket kanalu form: predmet "Poptavka: tema", telo JSON s poli formulare, tag Poptavka plus tema, zakaznik z formulare, poznamka v logu. Bez provozovatele se jen zaloguje. Prilohy ticketu: formular az 3 soubory po 5 MB, ticket az 10; nahrani, seznam, stazeni a smazani (pravo ticket.comment, strop viditelnosti, poznamky v logu, audit). Soubor jde v JSON jako Base64 a lezi v beznem ulozisti, bez nove zavislosti; strop tela jen na techto cestach. Vlastni widget s kreslenim Graf umi i pocet ticketu se seskupenim jako kolac (PieChart.tsx, ciste SVG, osm barev z tokenu, zbytek jako ostatni). OpenAPI rozdelene na mensi soubory (102 cest, 28 schemat overeno shodnych), 28 novych testu (135 celkem), dokumentace aktualizovana.
16 KiB
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 |
| Poptavka z webu jako ticket | hotovo | POST /api/contact zaklada ticket provozovateli portalu |
| Prilohy ticketu | hotovo | 5 MB na soubor, 10 na ticket, z webu i z portalu |
| Udaje provozovatele na webu | hotovo | GET /api/public/brand, brand.ts je jen zaloha |
| 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/, 12 souboru a 130 testu: prava, tickety, prilohy, kontakt, 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:
| 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, rozbor kapacity
v 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. Reference, tym i cisla jsou vymyslene
a pred ostrym pouzitim se musi nahradit. Kontaktni a fakturacni udaje bere web
z firmy oznacene jako provozovatel portalu (GET /api/public/brand),
web/src/config/brand.ts je jen staticka zaloha pro pripad, ze provozovatel
neni nastaven. Viz 22-znacka-a-design.md.
Prilohy ticketu lezi v obecnem ulozisti jako base64 uvnitr zaznamu. V rezimu
file kazda zmena prepise cely attachment.json, pro jednotky MB to staci,
blob uloziste (S3 nebo bytea) je dalsi krok. Viz 14-databaze.md.
Poptavka z webu vznikne jako ticket provozovatele, ale nikdo se o ni nedozvi e-mailem: upozorneni na novou poptavku zatim chybi, resitel ji vidi az v portalu.
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, prilohy, kontakt, executor, cteni tela a health; routy nastaveni a runtime fronty cekaji |
| deset souboru nad 500 radku | tri na webu z duvodu, sedm na serveru ceka na deleni pri nejblizsi praci v nich; seznam v 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.
Za rozmysleni stoji evidence bugs a wishes. Zamerne to nejsou tickety, duvod je v 06-tickety.md.
Datove modely a prava z 09-navrh-rozsireni.md jsou hotove, popis stavu je v 17-nastaveni-a-prava.md. Navrh k rozhodnuti zustava 10-runtime-a-kapacita.md pro frontu, beh kroku a rozpocet na 150 klientu, a 16-monetizace.md pro cenu za krok.
Dokumentace
| Soubor | O cem |
|---|---|
| 00-pro-programatory.md | rozcestnik a duvody rozhodnuti |
| 02-appfactory-proxy.md | beh za reverse proxy, ROOT_PATH, health |
| 03-architektura-a-mapa-kodu.md | kde co je |
| 04-api.md | endpointy a to, co ze Swaggeru neni videt |
| 05-dashboard-a-builder.md | editor automatizaci |
| 06-tickety.md | model ticketu a log prubehu |
| 07-firmy-a-prava.md | firmy, pohledy, kdo co vidi |
| 08-dashboard-widgety.md | nastavitelny prehled |
| 09-navrh-rozsireni.md | puvodni navrh rozsireni |
| 10-runtime-a-kapacita.md | navrh: fronta, beh kroku, kapacita |
| 11-skripty-konektoru.md | vykonna cast sluzeb |
| 12-sluzby-a-konektory.md | sluzba, konektor, viditelnost |
| 13-transformace-dat.md | pole na pole a JSON na JSON |
| 14-databaze.md | tri rezimy uloziste, migrace, sifrovani |
| 15-rejstrik-funkci.md | k cemu je jaka funkce a komponenta |
| 16-monetizace.md | navrh: cena za krok a balicky |
| 17-nastaveni-a-prava.md | prava, typy, akce, widgety, prepnuti uctu |
| 18-ticketovaci-system.md | udalosti, externi ID, statistiky, pohledy |
| 19-kapacita-200-firem.md | zmereno, co zvladne soucasny stav |
| 20-fronta-a-runtime.md | fronta, worker, spoustece, ochrana proti smycce |
| 21-realne-sluzby.md | napojeni na bezici aplikace a e-mail |
| 22-znacka-a-design.md | znacka WorkNuke, tokeny, prvky |
| 23-jazyky.md | prepinani jazyku a slovniky |
| 24-mcp-konektory.md | MCP servery firmy jako kroky |
| 25-navrh-pristupny-portal.md | navrh: prehled, formulare, hledani, viditelnost |
| 99-zmeny.md | zaznam zmen, nejnovejsi nahore |