WebApp Frontend Modules & System Components Specification

Dokumentová metadata 🗓️ Datum vytvoření / aktualizace: 2026-09-29 👤 Autor / Architekt: @Jules / Platform Engineering Team 🏷️ Stav: Schváleno (Living Reference Document) 🔗 Vazba na backlog: User Story #27 (CAD Product Studio & Multi-Publishing), User Story #17 (Model Management & Catalog), User Story #16 (SignalR Pipeline), User Story #14 (Web 3D Inspector & Configurator)

1. Přehled Klientské Architektury (Frontend Architecture Overview)

Front-end aplikace COVEROQ CAD Platform je postaven na moderním TypeScriptu, Three.js (WebGL 3D engine) a reaktivním stavovém úložišti Store<AppState> (webapp/src/core/store.ts). V souladu s pravidly Clean Architecture v2 a rozhraním ISP (Interface Segregation Principle) má každá webová stránka vyhrazený orchestrátor v webapp/src/pages/.

Přehled WebApp Stránek

Cesta / URL	Název Stránky	Orchestrátor Soubor	Klíčové Komponenty & Služby	Popis & Funkcionalita
`/studio`	CAD Product Studio	`studio_page.ts`	`PartsFilmstripComponent` `LcsSnapController` `ViewerFacade` `PublishingModalComponent`	Parametrické sestavy, skeletové konstrukce, spodní filmový pás dílů, drag-and-drop osazování na kotevní osy (LCS), One-Click export do Medusa E-Shopu.
`/inspector`	Model Inspector	`inspector_page.ts`	`InspectorParameterControls` `InspectorViewportControls` `OrderService` `ViewerFacade`	3D vizualizace jednotlivých parametrů a dílů, posuvníky rozměrů, přepočet geometrie v reálném čase přes CAD worker.
`/models`	Správa Modelů	`models_page.ts`	`ModelUploaderComponent` `CadModelService` `ThumbnailSnapshotService`	Drag-and-drop nahrávání `.FCStd` souborů, inspekce struktury workerem, automatické vygenerování WebGL 3D náhledu a správa katalogu.
`/logs`	Vývojářské Logy	`logs_page.ts`	`TelemetryService` `LogTerminalComponent`	Reálný čas Serilog stream přes SignalR TelemetryHub (`/hubs/telemetry`), filtry zdrojů/úrovní a interaktivní terminálová konzole.

2. Podrobný Popis Modulů WebApp

2.1 CAD Product Studio (`/studio` - `studio_page.ts`)

Parametrické Sestavy & Skelety: Umožňuje uživatelům upravovat rozměry master skeletu (ModelType.Skeleton) a okamžitě přepočítávat kotevní body (Local Coordinate System - LCS).
Spodní Filmový Pás Dílů (PartsFilmstripComponent): Ukazuje zobrazení dostupných CAD dílů (type === 'PART') s náhledy, filtrem a stavovou kostrou načítání.
Drag-and-Drop LCS Osazování (LcsSnapController): Přetažení dílu z filmového pásu do 3D viewportu s magnetickým přichytáváním k najbližším LCS kotevním bodům.
One-Click Publikování do E-Shopu: Tlačítko pro spuštění dialogu publikace do Medusa.js e-shopu pomocí PublishAssemblyToMedusaCommand s možností přímého exportu do XLSX ceníku.

2.2 Model Inspector (`/inspector` - `inspector_page.ts`)

Vizualizace Dílů v 3D: Renderování vygenerovaného GLB síťového modelu s dynamickým nastavením materiálů a stínů.
Ovládání Parametrů (InspectorParameterControls): Generuje formulářové prvky s posuvníky (range slider) a číselnými vstupy pro parametrickou tabulku Vars s debouncováním 300ms a tlačítkem obnovení výchozích hodnot.
Ovládací Prvky Viewportu (InspectorViewportControls): Tlačítka pro přepínání drátěného modelu (Wireframe), zaostření kamery (Fit Viewport) a zobrazení rozměrové krabice ($X \times Y \times Z\text{ mm}$).

2.3 Správa Modelů (`/models` - `models_page.ts`)

Drag-and-Drop CAD Uploader (ModelUploaderComponent): Nahrávání .FCStd souborů z počítače uživatele přímo do worker inspekčního endpointu (POST /api/models/inspect).
Snímkování 3D Náhledů (ThumbnailSnapshotService): Po schválení inspekce se v renderovacím offscreen plátně vygeneruje úsporný WebP 3D náhled a pošle v ConfirmModelImportCommand do backendu.
Katalog Šablon: Seznam všech registrovaných šablon a dílů v databázi s typovým odznakem ([Skelet] / [Díl]).

2.4 Vývojářské Logy & Observabilita (`/logs` - `logs_page.ts`)

Serilog Streaming přes SignalR: Živý odběr událostí ze serverového hubu /hubs/telemetry s automatickou rekonakcí.
Filtrování & Vyhledávání: Přepínání filtrů dle zdrojů (ALL, API, WORKER, CAD, WEB, ORCHESTRATOR) a úrovní logů (INFO, WARN, ERROR, FATAL, DEBUG).
Vizualizér DAG Kauzality (TraceGitGraphVisualizer): Zobrazení stromu distribuovaného vykonávání úloh ve stylu multibranch Git grafu s indikací latence (elapsedMs) a detekcí závodních podmínek (race conditions).

3. One-Click Multi-Publishing Pipeline (Medusa.js + CAD DB + Google Drive)

Pipeline zajišťuje bezpečné, atomické a plně automatizované publikování parametrických CAD modelů z vývojového/administrátorského prostředí do produkčního e-commerce ekosystému.

 +-----------------------------------------------------------------------------------+
 |                    ONE-CLICK MULTI-PUBLISHING PIPELINE                            |
 +-----------------------------------------------------------------------------------+
 |                                                                                   |
 |  [ KROK 1 ] Registrace v CAD DB (Coveroq.Cad.Api & Infrastructure)                |
 |   ├── Zápis záznamu do tabulek `ModelTemplates` & `ParameterDefinitions`          |
 |   ├── Uložení souborů a náhledů do `/storage/models/`                             |
 |   └── Zápis předdefinovaných produktových variant                                 |
 |                                                                                   |
 |  [ KROK 2 ] Medusa Admin API Creation                                             |
 |   ├── Vytvoření produktu přes `POST /admin/products`                              |
 |   ├── Založení produktových variant s příslušnými SKU a cenami                    |
 |   └── Mapování CAD Metadata ID do Medusa Product Metadata                         |
 |                                                                                   |
 |  [ KROK 3 ] Cache Pre-generation                                                  |
 |   ├── Předehřátí/Pre-rendering GLB 3D modelů pro standardní varianty              |
 |   ├── Uložení GLB assetů do distribuované cache                                   |
 |   └── Aktivace příznaku `IsActive = True`                                         |
 |                                                                                   |
 +-----------------------------------------------------------------------------------+

Krok 1: Upload na Google Drive (Cloud Storage Sync)

Pipeline vytvoří vyhrazenou složku v Google Workspace Drive (/Coveroq_CAD_Library/{model_key}/) pro archivační účely.

Krok 2: Registrace v CAD DB na Hetzneru (Relational CAD Registry)

Zápis metadat a struktury modelu do produkční databáze PostgreSQL / SQLite na Hetzner VPS.

Krok 3: Medusa Admin API Product & Variant Creation (E-Commerce Sync)

Volání POST /admin/products v Medusa.js API pro vytvoření konfigurovatelného produktu a jeho variant.

Krok 4: Cache Pre-generation (Instant Preview Warm-up)

Asynchronní pre-rendering GLB modelů pro výchozí varianty na CAD workeru.

4. Transakční Rollback a Saga Pattern (Transactional Rollback Strategy)

Jelikož publikování distribuuje data mezi tři nezávislé systémy, je implementován vzor Saga Orchestrator s kompenzačními transakcemi.

Fáze Selhání	Neúplný Stav	Kompenzační Akce (Rollback)	Výsledný Stav
Krok 1 (Google Drive)	Částečně nahrané soubory na Drive.	Smazání vytvořené složky `folder_id` via Google Drive API.	`FAILED_ROLLED_BACK`
Krok 2 (CAD DB)	Soubory na Drive, selhání zápisu do DB.	1. Smazání složky z Google Drive. 2. Provedení `DB.rollback()` v CAD DB.	`FAILED_ROLLED_BACK`
Krok 3 (Medusa API)	Soubory na Drive, záznam v CAD DB, selhání Medusa API.	1. Volání `DELETE /admin/products/{id}` v Medusa API. 2. Soft-delete CAD DB záznamu. 3. Smazání složky na Google Drive.	`FAILED_ROLLED_BACK`
Krok 4 (Cache Pre-gen)	Všechna data zapsána, selhal pre-rendering.	Nekritické selhání: Publikování se nerollbackuje. Stav bude `PUBLISHED_WITH_CACHE_WARNING`.	`PUBLISHED_WITH_WARNING`

5. Autentizace a Správa Klíčů (Authentication & Security Specification)

Google Workspace Service Account: Uložen v /etc/coveroq/keys/google_service_account.json nebo přes GOOGLE_SERVICE_ACCOUNT_JSON_B64.
Medusa Admin API Token: Konfigurován přes MEDUSA_ADMIN_API_TOKEN v prostředí serveru.
WebApp Admin Token (adminToken): Token pro administrátorské operace v WebApp a na stránech chráněných pomocí auth-wall.js je uložen v localStorage pod klíčem adminToken.

6. Verifikace a Kvalita (Build & QA Verification)

uv run python -m mkdocs build
dotnet build backend-dotnet/Coveroq.Cad.slnx
dotnet test backend-dotnet/Coveroq.Cad.slnx
npm run test