OPORA — Projects UI flow (specifikace obrazovek)

• Projekty jsou kanonická entita: návrh -> výpočet a kontroly -> dokumenty -> předání a provoz.
• “Kalkulátor” není samostatná stránka; je to režim editace projektu (/edit).
• Specifikace pokrývá routy:
• /app/projects
• /app/projects/new
• /app/projects/[projectId]
• /app/projects/[projectId]/edit
• /app/projects/[projectId]/results
• /app/projects/[projectId]/documents
• /app/projects/[projectId]/operations
• /app/projects/[projectId]/details
• navazující odborné posouzení /app/projects/[projectId]/technical-review

• Všechny projektové routy jsou pod /app/* (session + org kontext jsou povinné).
• Projektový workspace má stálou navigaci Přehled / Návrh / Výsledky / Dokumenty / Provoz. Na úzké ploše se navigace vodorovně posouvá a aktivní položka se udržuje viditelná.
• Údaje projektu jsou podstránka Přehledu, odborné posouzení navazuje na Výsledky. Nevytvářejí další hlavní záložky.
• Aktuální výpočet ani uzavřené kontroly samy o sobě neznamenají schválení k provozu; předání a uvolnění patří do Provozu.
• Server je zdroj pravdy pro vynucení přístupu:
• RBAC: requirePermission(...)
• Subscription/plan: requirePlanEntitlement(...)
• UI affordance nikdy nenahrazuje guardy:
• Zakázaná akce je viditelná jako disabled s vysvětlením, nebo skrytá dle významu.
• Přímý vstup na nepovolenou route musí skončit na /app/access-denied, /app/subscription-required nebo /app/upgrade-required.
• Konzistentní stavy:
• Loading: skeletony pro header + hlavní obsah.
• Empty: vysvětlení + jasný další krok.
• Error: lidsky čitelné hlášení + retry a/nebo návratová akce.

Účel

• Primární vstupní bod do workflow projektu.
• Umožnit rychlé “najít -> otevřít -> pokračovat”.

Layout

• Header: Projekty + aktivní organizace + count badge.
• Akce vpravo:
• Nový projekt (jen s create_project).
• Nad inboxem nejsou dashboardové metrické karty.
• Horní část stránky má být co nejkratší:
• saved views
• stručný stav pohledu
• filtry
• Saved views jsou kompaktní chips s počtem:
• Všechny
• Moje rozpracované
• Čeká na přepočet
• Bez otevřených kontrol
• Nástroje listu:
• Search: název / interní ID.
• Filtry: status, přítomnost výsledku, aktuálnost výsledku, poslední aktivita.
• Řazení: updatedAt desc (default), createdAt desc, name.
• Stav pohledu je jen jeden krátký textový strip, ne dvě duplicitní informační vrstvy.
• Obsah:
• Od šířky obsahu seznamu 1050 px tabulka; pod touto šířkou karty se stejnými údaji a akcemi.
• Sloupce: projekt, stav, aktivita, akce.
• Řádek projektu používá kompaktní scan-friendly hierarchii:
• projekt: název, interní ID, stručný kontext sestavy
• stav: lifecycle, result-state, krátké shrnutí problémů a připravenosti
• aktivita: hlavní čas a poslední výpočet
• akce: jedna hlavní volba podle stavu projektu; ostatní dostupné cíle Detail, Výsledky a Návrh jsou sekundární
• List má působit jako pracovní inbox, ne jako pasivní report.

Akce v řádku

• Detail -> /app/projects/[projectId]
• Návrh -> /edit (zkratka v řádku pro uživatele s edit_project)
• Výsledky -> /results (když výsledky nejsou, otevře “zatím nespočítáno” stav)
• Dokumenty a exporty se otevírají v projektu na /documents; řádek seznamu přímo negeneruje soubory.

Stavy

• Loading:
• Skeleton filtru a 8-12 skeleton řádků.
• Empty (bez projektů):
• Text je krátký a akční, ne explainer o celé doméně.
• CTA:
• s create_project: Vytvořit první projekt
• bez create_project: “Požádejte administrátora o oprávnění”.
• Empty (bez výsledků filtru):
• “Žádné projekty neodpovídají filtrům” + reset pohledu.
• Error:
• “Nepodařilo se načíst projekty” + Zkusit znovu.
• Pagination:
• Seznam zobrazuje rozsah a celkový počet projektů s ovládáním stránek.

RBAC a plan

• Viditelnost Nový projekt: create_project.
• Viditelnost zkratky Návrh v seznamu: edit_project. Samotná route poskytuje čtenářům souhrn uložených parametrů bez editace.
• Samotný list je read-safe pro Viewer role (pokud má přístup do app kontextu).

Účel

• Minimalizovat time-to-first-calculation.

Layout

• Krátký formulář:
• Povinné: název projektu.
• Volitelné: vstupní presety.
• Volitelné startovní nastavení je ve výchozím stavu zavřené. Uživatel nesmí před vytvořením prvního projektu procházet technická pole, pokud je sám neotevře.
• Route s ?onboarding=1 zobrazuje třetí krok společného onboardingu a používá CTA Vytvořit první projekt.

Startovní presety

• Create flow nabízí preset Typ zakázky, který nastaví startovní technické a obchodní hodnoty draftu.
• Volba presetu je řešená jako kompaktní ikonový switch o 3 volbách, ne jako textový select.
• Preset se používá jen při založení draftu; po otevření editoru jsou v projektu uložené už konkrétní vstupy, ne jen odkaz na preset.
• Výchozí presety:
• Rodinný dům
• orientačně: pronájem 2,4 Kč / m2 / den, montáž 62 Kč / m2, demontáž 38 Kč / m2
• kratší zakázka, vyšší jednotkové sazby, nižší doprava a dokumentace
• Bytový dům
• orientačně: pronájem 1,9 Kč / m2 / den, montáž 52 Kč / m2, demontáž 32 Kč / m2
• střed trhu a hlavní výchozí preset pro nové projekty
• Průmyslový objekt
• orientačně: pronájem 1,6 Kč / m2 / den, montáž 48 Kč / m2, demontáž 30 Kč / m2
• delší a větší zakázka, nižší denní sazba, ale vyšší logistika a dokumentace
• Uživatel může po založení draftu všechny tyto hodnoty měnit v editoru projektu.

Akce

• Vytvořit projekt -> redirect na /app/projects/[projectId]/edit.
• Zrušit -> zpět na /app/projects.

Stavy

• Loading:
• Skeleton formuláře.
• Validation error:
• Inline chyby po polích + zachovat hodnoty.
• Action error:
• Globální message “Projekt se nepodařilo vytvořit” + retry.

RBAC a plan

• Route i submit vyžadují create_project.
• Bez oprávnění: redirect na /app/access-denied.

Účel

• Orientace v aktuálním stavu projektu a jeden doporučený další krok.

Layout

• Společná navigace projektu a kompaktní identita se stavem výpočtu.
• Doporučený krok má jednu dominantní akci podle stavu:
• chybějící nebo neaktuální výpočet -> otevřít Návrh; čtenář pokračuje na Výsledky
• otevřené kontroly -> /results?section=warnings
• rozpracovaný dostupný provozní workflow -> /operations
• jinak -> /documents
• Zbývající úkoly poskytují přímé odkazy na další práci.
• Údaje zakázky uvádějí zákazníka, místo, konstrukci, výsledek a provozní způsobilost; odkaz Údaje projektu vede na /details.
• Přehled používá krátké nadpisy a stručná fakta, bez opakování celého výsledku.

Stavy a přístup

• Chybějící a neaktuální výpočet mají odlišný stav a doporučený krok.
• Požadavek pro loading/error: skeleton obsahu; srozumitelná chyba s opakováním nebo návratem na seznam.
• Čtení vyžaduje view_results; akce na úpravu respektují edit_project.

Účel

• Úprava vstupů a spuštění výpočtu v iterativní smyčce.

Layout

• /edit zůstává ve společném app shellu a projektovém workspace.
• Návrh nabízí Konstrukce (Visual Builder), Podmínky (řízený formulář) a panel Kontroly; vedle nich je stav uložení a odkaz na Údaje projektu.
• Výchozí vstup otevírá Konstrukci. Explicitní editorSurface=form a cílené formulářové opravy otevírají Podmínky; vypnutý Builder používá formulář.
• Builder je vložený do pracovního prostoru Konstrukce; jeho otevření neznamená automatický přechod do fullscreen dialogu.
• Následující pravidla formuláře se vztahují na Podmínky, nikoli na plátno Builderu.
• Editor vyplňuje zbývající výšku dashboardu a vlastní scroll má pouze pracovní obsah.
• Nad formulářem je stručné vyhledání pole nebo sekce, ne obecný explainer panel.
• Formulář pracuje s aktivní sekcí; přehled sekcí nabízí název a stav. Sekce zákazníka a nabídky je dostupná samostatně v Údajích projektu.
• Od šířky pracovní plochy 1080 px je navigace sekcí v levém railu širokém přibližně 248 px a akce Kontroly / Uložit / hlavní akce jsou v horním chrome.
• Pod 1080 px se rail skryje a spodní dock obsahuje přesně Sekce / Kontroly / Uložit / hlavní akce; poslední pole nesmí překrývat.
• Běžná hlavní akce Návrhu je Uložit a spočítat; při chybě se mění na opravu, otevření kontrol nebo opakování uložení/výpočtu podle aktuálního problému.
• Aktuální workspace nevyžaduje potvrzení každé formulářové sekce před výpočtem. Podmínkou zůstávají platné vstupy, kompatibilita a povinné kontroly Builderu, oprávnění a úspěšné uložení odpovídající verze návrhu.
• Pro přechod z návrhu k přípravě montáže zůstává nutná explicitní kontrola všech sekcí. Samostatná akce v hlavičce sekce uloží její potvrzení; zákaznickou část potvrzuje uživatel v Údajích projektu. Změna příslušných vstupů potvrzení zneplatní. Výpočet sám sekce nepotvrzuje.
• Sdílená prezentace podporuje také režim s potvrzováním sekcí (Potvrdit část a pokračovat, Pokračovat); tento režim není zapnutý v aktuálním workspace.
• V Údajích projektu je hlavní akce Uložit údaje.
• Rozbalený přehled sekcí se otevře jako přístupný panel, zavře se po výběru a na mobilu nezabere celý viewport.
• Detailní vizuální a interakční pravidla určuje ../01-architecture/project-editor-design-standard.md.
• Pokud editor otevřel remediation flow z výsledků nebo blokace:
• zobrazit issue navigator se seznamem otevřených problémů
• automaticky otevřít správnou sekci formuláře
• odscrollovat na cílové pole nebo sekci
• problémové pole dočasně zvýraznit
• Detailní status surface se zobrazuje jen když je potřeba:
• neuložené změny
• validační problémy
• chybějící nebo stale výsledek
• save failure nebo conflict
• Navigace sekcí je stručná a stavová:
• žlutá = Ke kontrole
• modrá = Rozpracováno
• červená = K opravě
• zelená = Hotovo
• každá sekce je rychlý skok bez doprovodného obecného explainer textu
• Form sekce nemají dlouhé permanentní popisné odstavce; povolená je jedna krátká věta, pokud zpřesňuje účel sekce.
• Každé pole může nabídnout on-demand help přes info tooltip vedle labelu místo trvale viditelného helper textu.
• V sekci obchodu je dostupný kompaktní ikonový switch pro přepnutí presetu:
• přepíše pouze komerční baseline pole podle typu zakázky
• nesmí měnit geometrii, zatížení, kotvení ani bezpečnostní nastavení
• změna se chová jako běžná editace formuláře a vstupuje do autosave i stale-results logiky

Stavy

• Loading:
• Skeleton formuláře a skeleton vieweru.
• Validation error:
• Inline chyby po polích, zachovat rozpracované vstupy.
• Calculation error:
• Doménová chyba čitelně v kontextu formuláře + možnost okamžité opravy.
• Remediation mode:
• Pokud uživatel přišel z /results přes akci Opravit v editoru, editor musí udržet kontext problému:
• banner s názvem problému a doporučením
• CTA zpět na výsledky
• možnost přejít na další otevřený problém bez ručního hledání
• Save error:
• “Uložení selhalo” + retry, bez ztráty dat.
• Happy path:
• minimum persistentního copy
• informace jsou předané přes issue counts, stručné status labels a lehké surface
• delší text patří jen do remediation, validation a failure stavů
• otevření další sekce používá plynulou výškovou animaci a synchronizovaný scroll bez prudkého skoku
• reduced-motion režim zůstává plně funkční

RBAC a plan

• Vstup na /edit: view_results. Bez edit_project se vykreslí uložené parametry pouze pro čtení, bez mutačních ovládacích prvků.
• Uložit: edit_project.
• Uložit a spočítat: edit_project pro uložení a run_calculation pro výpočet; povinné validační a technické podmínky se ověřují samostatně.
• Bez oprávnění je tlačítko disabled s důvodem (RBAC affordance).

Účel

• Kanonické místo pro souhrn výpočtu, kusovník, cenu a kontroly. Dokumenty a exporty mají vlastní route /documents.

Layout

• Společný workspace obsahuje navigaci projektu, identitu projektu a stav výpočtu.
• Vnitřní sekce Výsledků:
• Souhrn (výchozí)
• Kusovník a cena (section=bom, zkráceně Kusovník)
• Kontroly (section=warnings)
• Odkaz na Dokumenty přechází na /documents. Starý /results?section=exports se přesměruje na tuto route se zachováním ostatních parametrů.
• Vnitřní záložky musí být umístěné pod projektovým headerem, před obsahem aktivní sekce.
• Tabs jsou vizuálně kompaktní:
• krátký label
• count/status badge
• bez vysvětlujícího odstavce pod každým tabem
• s výrazným oddělením od obsahu pod nimi
• Globální stavové bannery pod tabs jsou vyhrazené jen pro skutečně page-level stavy, typicky stale result.
• Comparison po přepočtu nepatří jako permanentní globální banner nad celou results route; patří primárně do sekce Kontroly.
• Souhrn je defaultní sekce a obsahuje:
• krátký hero s identitou projektu a jednou časovou kotvou
• horní rental-first obchodní panel
• samostatný kontrolní panel projektu
• minimum persistentního copy
• detailní informace jen on-demand
• V Souhrnu platí progressive disclosure:
• běžný stav ukazuje jen jednu vrstvu identity, jednu vrstvu obchodního výstupu a jednu vrstvu health signálů
• detail (Klient a zakázka, Použití a prostředí, Technický přehled) je rozbalovací; normové odkazy jsou v Kontrolách
• názvy a copy detailních bloků mají být krátké a scan-friendly
• stejná informace se nesmí opakovat ve dvou sousedních blocích Souhrnu
• příklad: snapshot state nepatří současně do hero, obchodního panelu i health panelu
• příklad: kontakt nebo platnost nepatří současně do horní nabídky i do detailního klientského bloku
• V Souhrnu platí rental-first komerční model:
• hlavní zákaznická nabídka je pronájem
• copy musí být jednoznačné: jde o cenu pro zákazníka za pronájem sestavy na definované období
• prodejní varianta není standardní paralelní headline v results UI
• Každá blokace nebo warning, který má jednoznačnou vazbu do editoru, musí mít akci Opravit v editoru.
• Remediation affordance:
• Preferovaný target je konkrétní pole (editorTarget)
• Fallback target je konkrétní sekce editoru
• CTA vede na /app/projects/[projectId]/edit s kontextem problému, ne jen na obecný editor
• Požadavek pro hierarchii sekce Kontroly:
• stručný stav otevřených problémů
• volitelné porovnání po přepočtu
• hlavní karty s dostupnou nápravou
• Actionable warning card má být human-first:
• horní badge vrstva = status, severity, high-level oblast
• hlavní headline = název problému
• pod headline = summary
• spodní bloky = Co udělat teď a Kde to upravit
• issueId a raw field path jsou až sekundární auditní metadata

Stavy

• Loading:
• Skeleton page headeru, tabs a aktivní sekce.
• Empty (zatím nespočítáno):
• Srozumitelný stav bez výpočtu a dostupná akce podle oprávnění.
• Error:
• “Výsledky se nepodařilo načíst” + retry.
• Po návratu z editoru po opravě:
• systém musí umožnit uživateli rychle porovnat, které blokace zmizely, které se změnily a které zůstávají

Copy a hierarchy pravidlo:

• results shell je read-mode, ne report page
• stale a comparison bannery mají být stručné a akční
• comparison signal nesmí konkurovat hlavním actionable warning cards
• dense technické moduly (Kusovník, Cena, export historie, auditní detail) mohou být tvrdší a techničtější než zbytek stránky
• každá horní summary vrstva má mít vlastní roli:
• header = identita + čas
• obchodní výstup = nabídka
• kontrola projektu = health
• další kroky = akce
• klient a zakázka = kontext
• pokud dva sousední bloky říkají stejnou věc různými slovy, jeden z nich se odstraní nebo přepíše
• Další kroky nesmí v happy path opakovat cenu nebo klientská metadata; mají vést k akci

RBAC

• Přístup ke čtení výsledků: view_results.
• Opravy vstupů vyžadují edit_project; další akce mají vlastní serverové guardy.

• Samostatná hlavní záložka obsahuje nabídku pro zákazníka, interní podklady a historii souborů. Nezobrazuje vnitřní záložky Souhrn/Kusovník/Kontroly.
• Exportní workspace používá výpočet projektu; nedostupný nebo starší nekompatibilní výsledek zobrazí odpovídající náhradní stav.
• Připojené řízené dokumenty se zobrazují uživatelům s view_documents i bez výpočtu. create_document_draft zpřístupňuje přidání podkladu s vazbou na projekt a návratem do jeho Dokumentů.
• Nahrání podkladu vytváří pracovní revizi; odborná kontrola a vydání jsou samostatné kroky. Detail a revize dokumentu se otevírají pod /app/documents/[documentId].
• CSV snapshot může být dostupný i pro neaktuální výsledek. PDF/XLSX používají asynchronní exportní úlohy s historií stavů a artefaktů.
• Detailní exportní model určuje export-jobs-and-artifacts-standard.md.

RBAC a subscription gating

• Projektová route vyžaduje view_results; čtení připojených dokumentů navíc view_documents.
• CSV export vyžaduje export_results.
• Pokročilé PDF/XLSX exporty vyžadují export_results, aktivní předplatné a entitlement advanced_exports.
• Dostupnost konkrétního dokumentu nebo oficiálního výstupu závisí i na jeho vlastních kontrolách a schválení. Aktuální snapshot sám o sobě nezaručuje povolení exportu.
• Požadavek pro affordance: chybějící oprávnění vysvětlit, chybějící plán propojit s billingem, neaktuální podklady propojit s opravou a přepočtem. Serverové vynucení platí i při přímém requestu.

• Podstránka Přehledu sdílí editor a ukládání projektu, ale zobrazuje údaje zákazníka a nabídky. Otevírá se z Přehledu i Návrhu.
• Hlavní navigace označuje Přehled; návratová akce vede zpět do Návrhu.
• Čtení vyžaduje view_results. Bez edit_project se zobrazí pouze uložené údaje, bez možnosti změn.

• Samostatná hlavní záložka vede provozní workflow včetně předání a uvolnění k použití.
• Čtení vyžaduje view_results; zápisy podléhají oprávnění a podmínkám konkrétní akce.
• Při nedostupnosti provozních dat se způsobilost nepovažuje za potvrzenou.
• Detailní stavový a přístupový kontrakt určuje scaffold-operational-workflow.md; odborné posouzení návrhu navazuje samostatně přes /technical-review.

• Happy path:
• /app/projects -> /app/projects/new -> /app/projects/[projectId]/edit -> /app/projects/[projectId]/results -> /app/projects/[projectId]/documents -> /app/projects/[projectId]/operations
• Iterace:
• /results -> /edit -> /results
• Remediation loop:
• /results -> Opravit v editoru -> fokus na problémové pole/sekci -> oprava a ověření vstupů -> Uložit a spočítat -> /results
• Přehled (/app/projects/[projectId]) je stabilní vstup s doporučeným krokem. Staré odkazy ?section=documents a ?section=customer přesměruje na /documents a /details; ostatní podporované staré sekce mapuje na Výsledky nebo Návrh.

| Akce / obrazovka | Viewer | Engineer | Admin/Owner | | --- | --- | --- | --- | | Otevřít list projektů | Ano | Ano | Ano | | Vytvořit nový projekt | Ne | Ano (create_project) | Ano | | Otevřít overview | Ano | Ano | Ano | | Otevřít Návrh / Údaje projektu | Ano, pouze čtení (view_results) | Ano, úpravy s edit_project | Ano | | Uložit změny | Ne | Ano (edit_project) | Ano | | Spustit výpočet | Ne | Ano (run_calculation) | Ano | | Zobrazit výsledky | Ano (view_results) | Ano | Ano | | Exportovat CSV (základní) | Ne | Ano (export_results) | Ano (export_results) | | Exportovat PDF/XLSX (pokročilé) | Ne | Podmíněně (export_results + advanced_exports) | Podmíněně (export_results + advanced_exports) |

Aktuální pořadí hlavních položek v AppSidebar:

1. 1.Přehled (/app/dashboard)
2. 2.Projekty (/app/projects)
3. 3.Dokumenty (/app/documents, podle canViewDocuments)
4. 4.Sklad (/app/warehouse, podle canViewWarehouse)

• Ve spodní části jsou Centrum nápovědy (/centrum-napovedy) a Nastavení (/app/settings). Blueprints nejsou položkou aktuálního sidebaru.
• Bez uložené volby se sidebar na projektových trasách automaticky sbalí při šířce viewportu 768–1199 px. Explicitní volba sbalení/rozbalení se ukládá a má přednost.
• Viditelnost položky sama neuděluje přístup; rozhodují serverové guardy cílové route.
• Centrum nápovědy publikuje tento dokument jako článek flow-projektu. Odkazy a popis hlavních pracovních kroků musí zůstat v souladu s projektovým workspace.