Wiresphere Docs

Wszystko, co potrzebne do pracy z Wiresphere — podzielone według grupy odbiorców: użytkownicy końcowi (system administracyjny), DevOps i architekci (platforma, eksploatacja, koncepcje) oraz deweloperzy (SDK, CLI, API).

Dostęp i logowanie

Aby zalogować się do systemu administracyjnego:

• Proszę otworzyć adres URL panelu administracyjnego w przeglądarce (np. https://domena-firmy.pl/admin/login)
• Proszę wprowadzić nazwę użytkownika i hasło z wiadomości powitalnej — należy zwrócić uwagę na wielkość liter
• Ikona oka pozwala wyświetlić hasło; opcja „Zapamiętaj logowanie" zapamiętuje sesję
• Nie pamiętają Państwo hasła? Opcja „Zresetuj hasło" pod przyciskiem logowania umożliwia otrzymanie linku resetującego

Pulpit

Pulpit zapewnia przegląd wyników firmy i pomaga śledzić najważniejsze wskaźniki. Większość widżetów można za pomocą listy rozwijanej przełączać między okresami tygodniowymi, miesięcznymi lub rocznymi.

Przegląd procesów

Przegląd procesów pokazuje wszystkie transakcje i ich status. Procesy można filtrować (sortowanie, typ, kanał, okres), analizować i zarządzać nimi.

• Tabela: numer transakcji, klient, data, kwota (netto), status płatności, kanał, numer typu i typ (oferta, faktura, zamówienie)
• Status płatności: zapłacone (zielony) · oczekuje na płatność (żółty) · w toku (pomarańczowy) · termin/przeterminowane (czerwony)
• Akcje: „+ Dodanie transakcji", „Eksportuj zaznaczenie" oraz „Zastosuj filtry"

Szczegóły procesu

Kliknięcie procesu w widoku przeglądowym otwiera widok szczegółowy ze wszystkimi informacjami o przebiegu procesu.

• Dane klienta i płatności: imię i nazwisko, numer klienta, e-mail; status faktury i metoda płatności (np. NFC Payment)
• Adresy: adres rozliczeniowy i dostawy można dostosować za pomocą ikony edycji
• Tabela pozycji: numer artykułu, nazwa, ilość, cena jednostkowa, VAT, waga całkowita, cena całkowita
• Podsumowanie ceny: suma częściowa, rabat, koszty wysyłki, VAT, suma całkowita
• Akcje: dodanie pozycji, anulowanie zaznaczenia, wydruk kodu QR, usunięcie procesu, zapis

Zarządzanie produktami

Przegląd produktów (menu „Gospodarka towarowa" → „Przegląd produktów") zawiera listę wszystkich produktów wraz z numerem artykułu, ceną netto, stanem magazynowym i statusem.

Tworzenie i edycja produktów

Nowe produkty tworzy się za pomocą opcji „+ Dodanie produktu" (nazwa artykułu, numer artykułu, kategoria, cena, stan magazynowy → Zapisz). Istniejące produkty edytuje się za pomocą ikony ołówka w wierszu tabeli.

Progi cenowe

W zakładce „Ceny progowe" widoku szczegółowego produktu określa się dla każdego progu minimalną ilość i cenę; przycisk „+ dodanie" pozwala dodać kolejne progi.

Sprzedaż dodatkowa (add-on)

Sprzedaż dodatkową (akcesoria, ulepszenia, gwarancje) można przypisać bezpośrednio do produktu głównego — jest ona automatycznie proponowana przy składaniu zamówienia, co zwiększa wartość koszyka i wspiera cross-selling.

Eksport / import produktów

Eksport: wszystkie dane produktów (nazwa, numer artykułu, ceny, stan magazynowy, kategorie) jako plik XLS lub CSV — do analiz, edycji zewnętrznej lub dokumentacji.

Import: zmienione lub nowe dane produktów w formacie XLS/CSV. System rozpoznaje istniejące produkty po numerze artykułu i aktualizuje zmienione informacje; nowe produkty są dodawane bez nadpisywania istniejących.

Kategorie

W sekcji „Kategorie" produkty dzieli się na grupy — ułatwia to zarządzanie asortymentem i jego odnajdywanie.

• Nazwa: zrozumiała i jednoznaczna
• Slug: przyjazna dla adresów URL wersja nazwy (małe litery, bez znaków specjalnych ani spacji) — istotna dla linków i SEO
• Właściwości filtrów i nawigacja: uzupełniane automatycznie przez system po zapisaniu
• Zapisywanie / usuwanie: operacje usuwania są dla bezpieczeństwa dodatkowo potwierdzane

CRM: kontakty i organizacje

Moduł CRM zarządza centralnie osobami kontaktowymi i organizacjami — dostępny w zakładce „CRM" w nawigacji głównej.

• Tworzenie kontaktu: „+ Dodanie kontaktu" → wybór osoby lub organizacji → wprowadzenie danych → opcjonalne przypisanie osoby do organizacji → Zapisz
• Edycja: ikona ołówka obok wpisu — tam też dostępne jest dodawanie i usuwanie (uwaga: usunięcie jest nieodwracalne)
• Wyszukiwanie i filtrowanie: za pomocą paska wyszukiwania po nazwie, adresie e-mail i innych kryteriach

Eksport / import kontaktów

Eksport: wszystkie kontakty jako plik XLS lub CSV — do dalszego przetwarzania, archiwizacji lub analizy.

Import: zmienione lub nowe dane kontaktowe w formacie XLS/CSV. Zmienione dane są rozpoznawane automatycznie, a istniejące wpisy aktualizowane — bez duplikowania rekordów. Idealne rozwiązanie do regularnej pielęgnacji danych i łączenia danych z różnych źródeł.

Aktywacja / dezaktywacja kont

W sekcji CRM → Osoby → Edytuj osobę znajduje się przełącznik „Konto jest dezaktywowane" — przydatny przy zmianie działu, nieobecności lub odejściu pracownika.

Gdy przełącznik jest aktywny, dana osoba nie może się już zalogować; po jego dezaktywacji odzyskuje standardowy dostęp. Zmiany należy potwierdzić przyciskiem „Zapisz". Dezaktywacja nie usuwa żadnych danych — konto można w każdej chwili ponownie aktywować.

Ustawienia

Ikona koła zębatego w prawym górnym rogu prowadzi do centralnej konfiguracji — po lewej stronie podzielonej na Sklep (metody płatności, wtyczki, waluty), Użytkownicy (role i uprawnienia), Stawki podatkowe oraz Jednostki.

Czym jest Wiresphere?

Wiresphere to modularny Runtime dla oprogramowania klasy enterprise. Aplikacje nie są budowane raz i następnie utrzymywane, lecz komponowane w czasie działania (runtime) z wymiennych modułów. Ekosystem składa się z czterech elementów: Runtime ładuje, izoluje i orkiestruje moduły. Module SDK określa, w jaki sposób buduje się moduły — contract-first, type-safe, wersjonowane. Enterprise SDK rozszerza go o Private Functions bez obowiązku publikacji oraz o SSO, polityki (policies) i integrację z audytem. Marketplace odpowiada za odkrywanie (discovery), licencjonowanie i automatyczne aktualizacje zweryfikowanych modułów.

Rdzeń jest Open Source i działa w chmurze UE lub na własnej infrastrukturze. Nie ma tu licencji ani udziału w GMV — płaci się wyłącznie za infrastrukturę.

Kluczowe koncepcje

Moduł

Podstawowa jednostka Wiresphere. Moduł zamyka funkcjonalność biznesową (np. checkout, integrację z magazynem, konfigurator) w izolowanym zakresie (scope) z jawnie typizowanym kontraktem (contract). To, czego nie ma w kontrakcie, nie istnieje dla innych modułów.

Zakres (Scope)

Przestrzeń izolacji modułu. Zakresy ograniczają dostęp i skutki błędów: moduł nie może uzyskać dostępu do stanu innego modułu, a błąd pozostaje we własnym zakresie. Zakresy są celowo małe — na tyle małe, by mógł je w pełni ogarnąć nawet agent kodujący (coding agent) o ograniczonym kontekście.

Kontrakt (Contract)

Typizowany, semantycznie wersjonowany interfejs modułu. Kontrakty są wymuszane na poziomie Service Brokera: przyjmuje on zapytania modułów przez HTTP i waliduje je przed przetworzeniem — niekompatybilne wywołania są odrzucane, a nie wykrywane dopiero w produkcji.

Kompozycja

Stan aplikacji: które moduły w jakiej wersji są aktywne i jak są ze sobą połączone. Kompozycje są zmieniane w czasie działania — moduły można ładować, zastępować, dezaktywować — bez ponownego wdrożenia (redeploy).

Słownik pojęć

Opcje wdrożenia

• Wiresphere Cloud (UE): wstępnie skonfigurowana, automatycznie skalowana infrastruktura. Wdrożenie jednym kliknięciem w Wiresphere Cloud — start bezpłatny.
• Self-hosting: otwartoźródłowy Runtime działa na własnej infrastrukturze — on-prem lub w wybranej przez Państwa chmurze. Pełny zakres funkcji, pełna suwerenność danych.
• Hybrydowo: Runtime on-prem, połączenie z Marketplace dla modułów i aktualizacji przez kontrolowane kanały.

Niezależnie od sposobu wdrożenia kod źródłowy i dane pozostają w Państwa rękach — platforma została zaprojektowana tak, by umożliwić łatwe odejście (exit-fähig by design).

Kompozycja na żywo

Moduły są wdrażane do działającej aplikacji, zastępowane lub dezaktywowane — bez przestojów i bez okien serwisowych. Przed każdą zmianą Runtime sprawdza kompatybilność kontraktów docelowej kompozycji; niekompatybilne zmiany są odrzucane, zanim zaczną obowiązywać.

Przebieg zmiany

• Nowa wersja modułu jest ładowana i inicjalizowana we własnym zakresie
• Runtime podłącza kontrakty i atomowo przekierowuje wywołania na nową wersję
• Stara wersja jest wyładowywana; w razie błędów uruchamiany jest automatyczny rollback dla danego modułu

Izolowane zakresy

Każdy moduł działa we własnym zakresie o zdefiniowanych granicach. Ogranicza to promień rażenia (blast radius) błędów, zapobiega ukrytym powiązaniom i sprawia, że moduły można niezależnie rozwijać, testować i utrzymywać — również za pomocą agentów kodujących, których kontekst nigdy nie wystarczyłby dla monolitu.

Aktualizacje i wycofywanie zmian

Moduły otrzymują aktualizacje przez wersjonowane kanały z Marketplace. Przed ich wdrożeniem Runtime sprawdza kompatybilność semantyczną z aktywną kompozycją. Każdą aktualizację można wycofać (rollback) dla pojedynczego modułu — błędna aktualizacja nie wymaga przywracania całej aplikacji.

Frontendy

Frontendy są oddzielone od modułów i korzystają z tych samych kontraktów — niezależnie od tego, czy to web, aplikacja, backoffice B2B, czy sprzęt kioskowy bez kontekstu przeglądarki. Stos frontendowy można dowolnie wybrać; zmiana nie wymaga migracji backendu.

Kanały i Checkout Handler

Wiresphere działa w oparciu o kanały (channels): samodzielne kanały, przez które składane są zlecenia i zamówienia. Dostępne kanały to E-Commerce, Kiosk, Kasa, Live Chat i AI Chat. Wszystkie kanały zasilają te same moduły — logika zamówień istnieje tylko raz.

Role i uprawnienia

Każdy kanał podlega własnej koncepcji ról i uprawnień. Uprawnienia są przyznawane osobno dla każdego kanału — agent czatu, kasjer i asystent AI działają z różnymi uprawnieniami, bez globalnych zezwoleń.

Checkout Handler

Elastyczne Checkout Handlery określają, jak przebiega proces zamówienia w danym kanale. To samo zamówienie może więc, w zależności od kanału, przejść zupełnie inną ścieżkę:

Konsola administracyjna

Konsola administracyjna jest centrum operacyjnym aplikacji Wiresphere. Pokazuje aktywną kompozycję — wszystkie moduły, wersje, kanały aktualizacji i połączenia kontraktów — oraz rejestruje każdą zmianę.

• Przegląd kompozycji: które moduły działają w jakiej wersji, od kiedy i z jakiego źródła
• Dziennik zmian: kto, kiedy i który moduł wdrożył, zaktualizował lub wycofał
• Środowiska: oddzielne kompozycje dla produkcji, stagingu i developmentu

Zarządzanie modułami

• Instalacja: wybór modułu z Marketplace, potwierdzenie licencji, wybór docelowej kompozycji — kontrola kompatybilności przebiega automatycznie
• Aktualizacja: określenie kanału aktualizacji dla każdego modułu (stable/beta); aktualizacje trafiają automatycznie lub po ręcznym zatwierdzeniu
• Wycofanie (rollback): każdą wersję modułu można osobno przywrócić do poprzedniego stanu
• Dezaktywacja: moduły można usunąć z kompozycji bez ich odinstalowywania

Użytkownicy i uprawnienia

Dostęp do konsoli administracyjnej jest oparty na rolach. Typowe role: Owner (wszystko, łącznie z rozliczeniami), Operator (zmiana kompozycji, zatwierdzanie aktualizacji), Auditor (dostęp tylko do odczytu kompozycji i dzienników). Zmiany w kompozycjach produkcyjnych mogą wymagać zatwierdzenia przez dwie osoby (zasada czterech oczu).

Eksploatacja i monitoring

• Stan każdego zakresu: kondycja (health), obciążenie i błędy są rejestrowane dla każdego modułu — awarie można bezpośrednio przypisać do ich źródła
• Audyt i zgodność: stan kompozycji i historię zmian można w każdej chwili wyeksportować (istotne dla dowodów zgodności z NIS2)
• Kontrola wdrożenia: region UE lub on-prem; dane nie opuszczają wybranej jurysdykcji

Quickstart

Uruchomienie lokalnego Runtime, wygenerowanie szkieletu modułu, komponowanie — bez rejestracji:

# Uruchom lokalny Runtime
npx wiresphere dev

# Wygeneruj szkielet modułu (TypeScript, contract-first)
npx wiresphere create module my-checkout

# Skomponuj moduł w działającej aplikacji — bez przebudowy (rebuild)
npx wiresphere compose add ./my-checkout

Dev-Runtime działa domyślnie pod adresem localhost:4200 i pokazuje aktywną kompozycję wraz ze wszystkimi załadowanymi modułami i ich wersjami kontraktów.

Module SDK

Moduły buduje się w TypeScript na bazie SDK. Kontrakt stanowi rdzeń — określa, co moduł oferuje, a co konsumuje:

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 i wersjonowanie

Kontrakty są wersjonowane semantycznie. Runtime automatycznie akceptuje aktualizacje minor i patch (kompatybilne wstecznie); aktualizacje major wymagają jawnej zmiany kompozycji. Niekompatybilności są wychwytywane na poziomie Service Brokera (walidacja każdego zapytania HTTP względem wersjonowanego kontraktu) oraz w momencie kompozycji — nigdy dopiero w produkcji.

CLI

REST API

Oprócz SDK i CLI Wiresphere udostępnia wielodostępne (multi-tenant) REST API. Pełne odniesienie endpointów wraz ze wszystkimi schematami request/response dostępne jest jako osobna strona:

Otwórz pełne odniesienie API 

Uwierzytelnianie

API wykorzystuje uwierzytelnianie oparte na tokenach (Bearer JWT). Tokeny są uzyskiwane przez POST /api/v1/auth/token-auth z parametrami username i password i są ważne przez 24 godziny. Wygasły lub nieprawidłowy token skutkuje odpowiedzią 409 Conflict.

Authorization: Bearer <token-dostępu>

Koncepcja tenant

API jest wielodostępne (multi-tenant): niemal każde zapytanie musi identyfikować kontekst sklepu poprzez nagłówek tenant-id — bez niego zapytania są odrzucane. Wyjątek: uwierzytelnianie jako użytkownik administracyjny (w takim wypadku nagłówka nie należy wysyłać).

tenant-id: moj-sklep-id

Paginacja, filtrowanie i sortowanie

Wszystkie endpointy listujące obsługują jednolite parametry zapytania:

# Prosty filtr (wyszukiwanie podciągu)
f=fieldName::value

# Wiele wartości (połączonych przez OR)
f=fieldName::val1~~val2

# Wykluczenie (prefiks --)
f=fieldName::--excludedValue

# Filtr zakresu dat (ISO 8601)
f=min_createdAt::2024-01-01T00:00:00.000Z

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

Grupy endpointów

Poradnik: komponowanie sklepu

Sklep headless powstaje z czterech modułów katalogowych — bez własnego programowania:

• checkout — koszyk, płatność, realizacja zamówienia (fulfillment)
• lager-interface — stany magazynowe i dostępność z gospodarki towarowej
• subscription-management — opcjonalnie dla subskrypcji i płatności cyklicznych
• Dowolnie wybrany frontend — web, aplikacja lub kiosk, podłączony przez te same kontrakty

Własne wymagania (np. logikę cenową) dodaje się jako osobny moduł — reszta kompozycji pozostaje nietknięta.

Poradnik: publikowanie modułu

• Rozwijanie: budowa modułu na bazie SDK, walidacja lokalna za pomocą wiresphere dev i wiresphere test
• Zgłoszenie: wiresphere publish — kontrola typów oraz przegląd kompatybilności i jakości odbywają się w ramach procesu certyfikacji
• Dystrybucja: licencjonowanie i automatyczne aktualizacje przejmuje Marketplace — z uczciwym udziałem w przychodach (revenue share)

Szczegóły dotyczące programu partnerskiego i certyfikacji: Deweloperzy → Opublikuj moduł.