Správa stavu (klient + výpočetní flow)

Tento dokument popisuje strategii správy stavu pro Next.js App Router aplikaci OPORA se zaměřením na správnost, determinismus a multi-tenant bezpečnost.

Principy

Server je zdroj pravdy pro perzistentní stav (Projekty, výsledky, membership, billing).
Klientský stav je dočasný a scoped na aktuální stránku/session (editace formulářů, UI přepínače).
Projects-first: uživatel edituje Projekt a spouští výpočty jako součást projektového workflow.

Kategorie stavu

1) Session a org kontext

Session zajišťuje auth provider a konzumuje ji /app/*.
Aktivní org kontext se vybírá a perzistuje (server-controlled) a je nutný pro navigaci v aplikaci.

2) Stav editace Projektu

Editace probíhá na /app/projects/[projectId]/edit.
Klientský stav reprezentuje “draft edits” dokud uživatel nezměny neuloží (save) nebo nespustí výpočet.

3) Stav výpočtu

Výpočet je deterministická transformace normalizovaných vstupů → výsledek.
UI by mělo výpočet modelovat jako:
in-flight (pending)
success (výsledek dostupný)
domain error (validace/constraint selhání)
unexpected error (infrastrukturní selhání)

Doporučený workflow model

Create: /app/projects/new vytvoří draft Projekt se vstupy vyplněnými při založení:
projectName
building.widthMeters, building.heightMeters, building.levels
scaffoldSystem.name, scaffoldSystem.frameWidthMeters, scaffoldSystem.bayLengthMeters, scaffoldSystem.levelHeightMeters
Edit: /app/projects/[projectId]/edit aktualizuje vstupy Projektu.
Calculate: explicitní akce spustí engine a perzistuje CalculationResult.
Review/Export: /app/projects/[projectId]/results zobrazí výsledky a gateuje exporty.

Concurrency a verzování (policy guidance)

Vyhnout se tichým přepisům vstupů Projektu.
Preferovat explicitní verzování nebo revision countery pro souběžné editace:
“last write wins” je přijatelné jen pro single-user workflow
multi-user org by měla minimálně podporovat conflict detection

Cache a revalidation (App Router)

Kde to jde, používat server-rendered čtení pro kanonický stav.
Po úspěšných zápisech invalidovat/revalidovat projektové stránky, aby UI zůstalo konzistentní.
Necachovat tenant-senzitivní odpovědi do sdílených cache, pokud nejsou explicitně scoped.

Observability (stavové přechody)

Zachytávat strukturované eventy pro:

project created
project updated
calculation executed (inputs hash + engine version)
export attempted (allowed/denied + reason)