csbot-prototype/documentation/01-prehled-a-stav.md

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 !
Nastaveni prezije nasazeni	hotovo	seed/records.json do prazdneho uloziste, npm run seed:export
Testy	castecne	vitest v tests/, 15 souboru a 149 testu: prava, tickety, prilohy, kontakt, executor, sit, health, seed, export

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.

Nasazeni jede v rezimu file bez svazku, takze redeploy maze data. Nastaveni (firmy, ucty, role, typy, akce, widgety, rozlozeni, automatizace) to prezije pres seed/records.json v repu: pri startu se nasype do prazdneho uloziste a obnovuje se prikazem npm run seed:export. Je to nahrada, ne reseni: provozni data (tickety, incidenty, audit) se ztraceji dal, konektory se musi zadat znovu (jejich klic se meni s nasazenim), zmena v portalu bez exportu se pri dalsim nasazeni ztrati a soubor nese hashe hesel, takze repozitar musi zustat soukromy. Reseni je DATABASE_URL nebo DATA_DIR na svazku. Viz 14-databaze.md.

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