Wiresphere Docs

Všetko, čo potrebujete na prácu s Wiresphere — rozdelené podľa cieľových skupín: koncoví používatelia (administračný systém), DevOps a architekti (platforma, prevádzka, koncepty) a vývojári (SDK, CLI, API).

Prístup a prihlásenie

Prihlásenie do administračného systému:

• Otvorte URL adresu administračného panela v prehliadači (napr. https://domena-firmy.pl/admin/login)
• Zadajte používateľské meno a heslo z uvítacej správy — dbajte na veľké a malé písmená
• Ikona oka umožňuje zobraziť heslo; možnosť „Zapamätať prihlásenie" si zapamätá reláciu
• Nepamätáte si heslo? Možnosť „Obnoviť heslo" pod prihlasovacím tlačidlom umožňuje získať resetovací odkaz

Dashboard

Dashboard poskytuje prehľad výsledkov firmy a pomáha sledovať najdôležitejšie ukazovatele. Väčšinu widgetov je možné pomocou rozbaľovacieho zoznamu prepínať medzi týždenným, mesačným alebo ročným obdobím.

Prehľad procesov

Prehľad procesov zobrazuje všetky transakcie a ich stav. Procesy je možné filtrovať (triedenie, typ, kanál, obdobie), analyzovať a spravovať.

• Tabuľka: číslo transakcie, zákazník, dátum, suma (netto), stav platby, kanál, číslo typu a typ (ponuka, faktúra, objednávka)
• Stav platby: zaplatené (zelená) · čaká na platbu (žltá) · prebieha (oranžová) · splatnosť/po splatnosti (červená)
• Akcie: „+ Pridať transakciu", „Exportovať výber" a „Použiť filtre"

Detaily procesu

Kliknutím na proces v prehľadovom zobrazení sa otvorí detailné zobrazenie so všetkými informáciami o priebehu procesu.

• Údaje o zákazníkovi a platbe: meno a priezvisko, číslo zákazníka, e-mail; stav faktúry a platobná metóda (napr. NFC Payment)
• Adresy: fakturačnú a dodaciu adresu je možné upraviť pomocou ikony úprav
• Tabuľka položiek: číslo artikla, názov, množstvo, jednotková cena, DPH, celková hmotnosť, celková cena
• Cenový súhrn: medzisúčet, zľava, náklady na dopravu, DPH, celková suma
• Akcie: pridanie položky, stornovanie výberu, tlač QR kódu, odstránenie procesu, uloženie

Správa produktov

Prehľad produktov (menu „Tovarové hospodárstvo" → „Prehľad produktov") obsahuje zoznam všetkých produktov vrátane čísla artikla, ceny netto, skladovej zásoby a stavu.

Vytváranie a úprava produktov

Nové produkty sa vytvárajú pomocou možnosti „+ Pridať produkt" (názov artikla, číslo artikla, kategória, cena, skladová zásoba → Uložiť). Existujúce produkty sa upravujú pomocou ikony ceruzky v riadku tabuľky.

Cenové prahy

Na karte „Prahové ceny" detailného zobrazenia produktu sa pre každý prah určuje minimálne množstvo a cena; tlačidlo „+ pridať" umožňuje pridať ďalšie prahy.

Doplnkový predaj (add-on)

Doplnkový predaj (príslušenstvo, vylepšenia, záruky) je možné priradiť priamo k hlavnému produktu — pri zadávaní objednávky sa automaticky ponúka, čo zvyšuje hodnotu košíka a podporuje cross-selling.

Export / import produktov

Export: všetky údaje o produktoch (názov, číslo artikla, ceny, skladová zásoba, kategórie) ako súbor XLS alebo CSV — na analýzy, externú úpravu alebo dokumentáciu.

Import: zmenené alebo nové údaje o produktoch vo formáte XLS/CSV. Systém rozpozná existujúce produkty podľa čísla artikla a aktualizuje zmenené informácie; nové produkty sa pridávajú bez prepísania existujúcich.

Kategórie

V sekcii „Kategórie" sa produkty rozdeľujú do skupín — uľahčuje to správu sortimentu a jeho vyhľadávanie.

• Názov: zrozumiteľný a jednoznačný
• Slug: verzia názvu priateľská k URL adresám (malé písmená, bez špeciálnych znakov a medzier) — dôležitá pre odkazy a SEO
• Vlastnosti filtrov a navigácia: po uložení ich systém dopĺňa automaticky
• Ukladanie / odstraňovanie: operácie odstránenia sa z bezpečnostných dôvodov dodatočne potvrdzujú

CRM: kontakty a organizácie

Modul CRM centrálne spravuje kontaktné osoby a organizácie — dostupný na karte „CRM" v hlavnej navigácii.

• Vytvorenie kontaktu: „+ Pridať kontakt" → výber osoby alebo organizácie → zadanie údajov → voliteľné priradenie osoby k organizácii → Uložiť
• Úprava: ikona ceruzky vedľa záznamu — tam je dostupné aj pridávanie a odstraňovanie (pozor: odstránenie je nevratné)
• Vyhľadávanie a filtrovanie: pomocou vyhľadávacieho panela podľa názvu, e-mailovej adresy a ďalších kritérií

Export / import kontaktov

Export: všetky kontakty ako súbor XLS alebo CSV — na ďalšie spracovanie, archiváciu alebo analýzu.

Import: zmenené alebo nové kontaktné údaje vo formáte XLS/CSV. Zmenené údaje sa rozpoznávajú automaticky a existujúce záznamy sa aktualizujú — bez duplikovania záznamov. Ideálne riešenie pre pravidelnú údržbu údajov a spájanie údajov z rôznych zdrojov.

Aktivácia / deaktivácia účtov

V sekcii CRM → Osoby → Upraviť osobu sa nachádza prepínač „Účet je deaktivovaný" — užitočný pri zmene oddelenia, neprítomnosti alebo odchode zamestnanca.

Keď je prepínač aktívny, daná osoba sa už nemôže prihlásiť; po jeho deaktivácii opäť získa štandardný prístup. Zmeny je potrebné potvrdiť tlačidlom „Uložiť". Deaktivácia neodstraňuje žiadne údaje — účet je možné kedykoľvek znova aktivovať.

Nastavenia

Ikona ozubeného kolieska vpravo hore vedie k centrálnej konfigurácii — vľavo rozdelenej na Obchod (platobné metódy, pluginy, meny), Používatelia (roly a oprávnenia), Daňové sadzby a Jednotky.

Čo je Wiresphere?

Wiresphere je modulárny Runtime pre softvér triedy enterprise. Aplikácie sa nebudujú raz a následne len neudržiavajú, ale komponujú sa za behu (runtime) z vymeniteľných modulov. Ekosystém sa skladá zo štyroch prvkov: Runtime načítava, izoluje a orchestruje moduly. Module SDK určuje, ako sa moduly budujú — contract-first, type-safe, verziované. Enterprise SDK ho rozširuje o Private Functions bez povinnosti publikovania a o SSO, politiky (policies) a integráciu s auditom. Marketplace zabezpečuje objavovanie (discovery), licencovanie a automatické aktualizácie overených modulov.

Jadro je Open Source a beží v EÚ cloude alebo na vlastnej infraštruktúre. Nie sú tu žiadne licencie ani podiel z GMV — platí sa výlučne za infraštruktúru.

Kľúčové koncepty

Modul

Základná jednotka Wiresphere. Modul uzatvára biznis funkcionalitu (napr. checkout, integráciu so skladom, konfigurátor) v izolovanom rozsahu (scope) s explicitne typovaným kontraktom (contract). Čo nie je v kontrakte, pre ostatné moduly neexistuje.

Rozsah (Scope)

Priestor izolácie modulu. Rozsahy obmedzujú prístup a dôsledky chýb: modul nemôže pristupovať k stavu iného modulu a chyba zostáva vo vlastnom rozsahu. Rozsahy sú zámerne malé — dosť malé na to, aby ich dokázal plne obsiahnuť aj kódovací agent (coding agent) s obmedzeným kontextom.

Kontrakt (Contract)

Typované, sémanticky verziované rozhranie modulu. Kontrakty sú vynucované na úrovni Service Brokera: prijíma požiadavky modulov cez HTTP a validuje ich pred spracovaním — nekompatibilné volania sú odmietnuté, nie odhalené až v produkcii.

Kompozícia

Stav aplikácie: ktoré moduly sú v akej verzii aktívne a ako sú navzájom prepojené. Kompozície sa menia za behu — moduly je možné načítavať, nahrádzať, deaktivovať — bez opätovného nasadenia (redeploy).

Slovník pojmov

Možnosti nasadenia

• Wiresphere Cloud (EÚ): vopred nakonfigurovaná, automaticky škálovaná infraštruktúra. Nasadenie jedným kliknutím vo Wiresphere Cloud — štart zadarmo.
• Self-hosting: open-source Runtime beží na vlastnej infraštruktúre — on-prem alebo vo Vami zvolenom cloude. Plný rozsah funkcií, plná dátová suverenita.
• Hybridne: Runtime on-prem, pripojenie k Marketplace pre moduly a aktualizácie cez kontrolované kanály.

Bez ohľadu na spôsob nasadenia zostáva zdrojový kód a dáta vo Vašich rukách — platforma je navrhnutá tak, aby umožňovala jednoduchý odchod (exit-fähig by design).

Živá kompozícia

Moduly sa nasadzujú do bežiacej aplikácie, nahrádzajú alebo deaktivujú — bez výpadkov a bez servisných okien. Pred každou zmenou Runtime kontroluje kompatibilitu kontraktov cieľovej kompozície; nekompatibilné zmeny sú odmietnuté skôr, ako nadobudnú platnosť.

Priebeh zmeny

• Nová verzia modulu sa načíta a inicializuje vo vlastnom rozsahu
• Runtime pripája kontrakty a atomicky presmerúva volania na novú verziu
• Stará verzia sa odstráni z pamäte; v prípade chýb sa spustí automatický rollback pre daný modul

Izolované rozsahy

Každý modul beží vo vlastnom rozsahu s definovanými hranicami. To obmedzuje dosah (blast radius) chýb, zabraňuje skrytým väzbám a umožňuje moduly nezávisle vyvíjať, testovať a udržiavať — aj pomocou kódovacích agentov, ktorých kontext by pre monolit nikdy nestačil.

Aktualizácie a vrátenie zmien

Moduly dostávajú aktualizácie cez verziované kanály z Marketplace. Pred ich nasadením Runtime kontroluje sémantickú kompatibilitu s aktívnou kompozíciou. Každú aktualizáciu je možné vrátiť (rollback) pre jednotlivý modul — chybná aktualizácia nevyžaduje obnovu celej aplikácie.

Frontendy

Frontendy sú oddelené od modulov a využívajú rovnaké kontrakty — bez ohľadu na to, či ide o web, aplikáciu, B2B backoffice alebo kioskový hardvér bez kontextu prehliadača. Frontendový stack je možné ľubovoľne zvoliť; zmena nevyžaduje migráciu backendu.

Kanály a Checkout Handler

Wiresphere funguje na základe kanálov (channels): samostatných kanálov, cez ktoré sa zadávajú zákazky a objednávky. Dostupné kanály sú E-Commerce, Kiosk, Pokladňa, Live Chat a AI Chat. Všetky kanály napájajú tie isté moduly — logika objednávok existuje len raz.

Roly a oprávnenia

Každý kanál podlieha vlastnému konceptu rolí a oprávnení. Oprávnenia sa udeľujú samostatne pre každý kanál — chatový agent, pokladník a AI asistent pracujú s rôznymi oprávneniami, bez globálnych povolení.

Checkout Handler

Flexibilné Checkout Handlery určujú, ako prebieha proces objednávky v danom kanáli. Tá istá objednávka tak môže v závislosti od kanála prejsť úplne inou cestou:

Administračná konzola

Administračná konzola je operačným centrom aplikácie Wiresphere. Zobrazuje aktívnu kompozíciu — všetky moduly, verzie, aktualizačné kanály a prepojenia kontraktov — a zaznamenáva každú zmenu.

• Prehľad kompozície: ktoré moduly bežia v akej verzii, odkedy a z akého zdroja
• Denník zmien: kto, kedy a ktorý modul nasadil, aktualizoval alebo vrátil späť
• Prostredia: oddelené kompozície pre produkciu, staging a development

Správa modulov

• Inštalácia: výber modulu z Marketplace, potvrdenie licencie, výber cieľovej kompozície — kontrola kompatibility prebieha automaticky
• Aktualizácia: určenie aktualizačného kanála pre každý modul (stable/beta); aktualizácie prichádzajú automaticky alebo po manuálnom schválení
• Vrátenie (rollback): každú verziu modulu je možné samostatne vrátiť do predchádzajúceho stavu
• Deaktivácia: moduly je možné odstrániť z kompozície bez ich odinštalovania

Používatelia a oprávnenia

Prístup k administračnej konzole je založený na rolách. Typické roly: Owner (všetko vrátane fakturácie), Operator (zmena kompozície, schvaľovanie aktualizácií), Auditor (prístup len na čítanie kompozícií a denníkov). Zmeny v produkčných kompozíciách môžu vyžadovať schválenie dvoma osobami (princíp štyroch očí).

Prevádzka a monitoring

• Stav každého rozsahu: kondícia (health), zaťaženie a chyby sa zaznamenávajú pre každý modul — výpadky je možné priamo priradiť k ich zdroju
• Audit a súlad: stav kompozície a históriu zmien je možné kedykoľvek exportovať (dôležité pre preukázanie súladu s NIS2)
• Kontrola nasadenia: región EÚ alebo on-prem; dáta neopúšťajú zvolenú jurisdikciu

Quickstart

Spustenie lokálneho Runtime, vygenerovanie kostry modulu, komponovanie — bez registrácie:

# Spustite lokálny Runtime
npx wiresphere dev

# Vygenerujte kostru modulu (TypeScript, contract-first)
npx wiresphere create module my-checkout

# Skomponujte modul do bežiacej aplikácie — bez opätovného buildu (rebuild)
npx wiresphere compose add ./my-checkout

Dev-Runtime beží predvolene na adrese localhost:4200 a zobrazuje aktívnu kompozíciu vrátane všetkých načítaných modulov a ich verzií kontraktov.

Module SDK

Moduly sa budujú v TypeScripte na základe SDK. Kontrakt tvorí jadro — určuje, čo modul ponúka a čo konzumuje:

import { defineModule } from "@wiresphere/sdk";
import { CartContract, PaymentContract } from "./contracts";

export default defineModule({
  name: "checkout",
  version: "1.4.2",
  contracts: { cart: CartContract, payment: PaymentContract },
  scope: { isolation: "strict" },
  setup({ runtime, config }) {
    runtime.expose("checkout.session", createSession(config));
  },
});

Runtime API

Kontrakty a verzionovanie

Kontrakty sú verziované sémanticky. Runtime automaticky akceptuje aktualizácie minor a patch (spätne kompatibilné); aktualizácie major vyžadujú explicitnú zmenu kompozície. Nekompatibility sa zachytávajú na úrovni Service Brokera (validácia každej HTTP požiadavky voči verziovanému kontraktu) a v momente kompozície — nikdy až v produkcii.

CLI

REST API

Okrem SDK a CLI poskytuje Wiresphere multi-tenant REST API. Kompletná referencia endpointov vrátane všetkých schém request/response je k dispozícii ako samostatná stránka:

Otvoriť kompletnú referenciu API 

Autentifikácia

API využíva autentifikáciu založenú na tokenoch (Bearer JWT). Tokeny sa získavajú cez POST /api/v1/auth/token-auth s parametrami username a password a sú platné 24 hodín. Expirovaný alebo neplatný token vedie k odpovedi 409 Conflict.

Authorization: Bearer <pristupovy-token>

Koncept tenant

API je multi-tenant: takmer každá požiadavka musí identifikovať kontext obchodu cez hlavičku tenant-id — bez nej sú požiadavky odmietnuté. Výnimka: autentifikácia ako administrátorský používateľ (v takom prípade sa hlavička nesmie posielať).

tenant-id: moj-obchod-id

Stránkovanie, filtrovanie a triedenie

Všetky endpointy vracajúce zoznamy podporujú jednotné parametre dopytu:

# Jednoduchý filter (vyhľadávanie podreťazca)
f=fieldName::value

# Viacero hodnôt (spojených cez OR)
f=fieldName::val1~~val2

# Vylúčenie (prefix --)
f=fieldName::--excludedValue

# Filter rozsahu dátumov (ISO 8601)
f=min_createdAt::2024-01-01T00:00:00.000Z

# Triedenie
o=createdAt::DESC,name::ASC

Skupiny endpointov

Návod: komponovanie obchodu

Headless obchod vzniká zo štyroch katalógových modulov — bez vlastného programovania:

• checkout — košík, platba, vybavenie objednávky (fulfillment)
• lager-interface — skladové zásoby a dostupnosť z tovarového hospodárstva
• subscription-management — voliteľne pre predplatné a opakované platby
• Ľubovoľne zvolený frontend — web, aplikácia alebo kiosk, pripojený cez tie isté kontrakty

Vlastné požiadavky (napr. cenovú logiku) sa pridávajú ako samostatný modul — zvyšok kompozície zostáva nedotknutý.

Návod: publikovanie modulu

• Vývoj: budovanie modulu na základe SDK, lokálna validácia pomocou wiresphere dev a wiresphere test
• Odoslanie: wiresphere publish — kontrola typov a preskúmanie kompatibility a kvality prebiehajú v rámci certifikačného procesu
• Distribúcia: licencovanie a automatické aktualizácie preberá Marketplace — s férovým podielom na výnosoch (revenue share)

Podrobnosti o partnerskom programe a certifikácii: Vývojári → Publikovať modul.