Z WeWebu do Reactu: návod na migráciu

Návod na migráciu z WeWebu do Reactu

Najprv pochopte export

Export z WeWebu obsahuje runtime, ktorý číta routy, JSON stránok, kolekcie, premenné, workflowy, pluginy, sekcie a vygenerované elementy. Má inú štruktúru než bežná ručne napísaná aplikácia vo Vue.

Prepis každého súboru do JSX môže zachovať rovnaký generický stav, roztrúsenú biznis logiku a štruktúru vytvorenú nástrojom. Pomocou exportu najprv zdokumentujte, čo produkt robí. Potom toto správanie postavte v Reacte s jasnými modulmi pre routing, dáta, formuláre a biznis pravidlá.

Ako konkrétny príklad v návode používame sprout-weweb, no postup sme navrhli tak, aby fungoval pri väčšine migrácií z WeWebu.

Čo obsahuje export z WeWebu

Aplikácia sprout-weweb skladá stránky za behu. Väčšina jej správania je uložená v konfigurácii, nie v komponentoch rout.

Najlepšie to vidno tu:

• src/_front/router.js skladá routy z window.wwg_designInfo vrátane metadát stránok, práce s jazykmi, kontroly prihlásenia a dynamických importov.
• src/wwLib/services/wwWebsiteData.js načítava JSON stránok a do stavu runtimu vkladá stránky, sekcie, kolekcie, premenné, vzorce, workflowy a komponenty z knižnice.
• src/pinia/variables.js funguje ako generický systém premenných: pre premenné webu, pluginov a komponentov, query parametre aj ukladanie do local storage.
• src/_common/helpers/code/workflows.js je generický engine na workflowy. Vykonáva akcie ako navigáciu, zmenu premenných, načítanie kolekcií, podmienené vetvenie, popupy a volania pluginov.
• src/wwLib/services/wwCollection.js schováva načítavanie dát za konfiguráciu kolekcií a adaptéry pluginov namiesto bežnej typovanej API vrstvy.

Export teda vyzerá skôr takto:

flowchart LR
    wewebConfig[WeWebConfig]
    routerRuntime[RouteRuntime]
    pageData[PageJSON]
    variableRuntime[VariableRuntime]
    workflowRuntime[WorkflowRuntime]
    pluginAdapters[PluginAdapters]
    renderedApp[RenderedApp]

    wewebConfig --> routerRuntime
    wewebConfig --> pageData
    wewebConfig --> pluginAdapters
    pageData --> variableRuntime
    pageData --> workflowRuntime
    pluginAdapters --> workflowRuntime
    routerRuntime --> renderedApp
    variableRuntime --> renderedApp
    workflowRuntime --> renderedApp

Pred písaním náhrady v Reacte prejdite túto konfiguráciu, aby ste pochopili fungovanie aplikácie.

Cieľ migrácie

Zdokumentujte správanie aplikácie, rozdeľte ho podľa funkcií a zodpovedností a postavte ho v moduloch, ktoré tím dokáže udržiavať. Kopírovaním runtimu do iného frameworku by ste si ponechali veľkú časť pôvodnej zložitosti.

Príklad Sprout: čo sa z neho naučiť

Sprout je na migráciu dobrý príklad. Jasne ukazuje rozdiel medzi tým, ako sa aplikácia správa, a tým, ako to technicky rieši WeWeb.

FUNCTIONALITY-ANALYSIS.md opisuje produkt s 30 stránkami v niekoľkých doménach:

• autentifikácia
• portál pre rodiny
• administrácia
• reporty
• predaj
• kalendár a plánovanie
• prepínanie organizácie a lokality

Pre migráciu má tento súpis domén oveľa väčšiu hodnotu ako vygenerovaný strom komponentov.

Najdôležitejšie správanie, ktoré sa v príklade opakuje:

• súkromný alebo verejný prístup na úrovni rout
• presmerovania podľa roly na admin stránkach
• inicializácia stránky z query parametrov
• inicializačné workflowy na úrovni aplikácie
• načítavanie dát cez kolekcie
• detaily zobrazené v popupoch
• inicializácia kalendára a dátumov
• nákupný košík a transakcie
• prepínanie kontextu organizácie/lokality

Toto musíte zachovať.

Presný layout a štruktúru elementov, ktoré vygeneroval WeWeb, sa väčšinou zachovávať neoplatí.

Oddeľte požiadavky produktu od vygenerovaného kódu

Každý koncept z WeWebu zaraďte do jednej z dvoch kategórií.

Produktové požiadavky

Tieto musia migráciu prežiť:

• biznis entity
• používateľské roly a pravidlá prístupu
• routy a používateľské scenáre
• dátové závislosti
• odosielanie formulárov a validačné pravidlá
• stavy, ktoré používateľ vidí
• vedľajšie efekty ako presmerovania, notifikácie, nahrávanie súborov alebo podpisovanie zásad

Implementačné artefakty WeWebu

Tieto by v pôvodnej podobe zvyčajne prežiť nemali:

• generické grafy workflowov
• generický register premenných
• ID kolekcií ako abstrakcia vo frontende
• vygenerované sekcie ako dlhodobé hranice komponentov
• JSON stránok ako trvalý model skladania UI
• konvencie runtimu viazané na konkrétne pluginy tam, kde by stačila jednoduchšia servisná vrstva

Ako čítať aplikáciu vo WeWebe pred prestavbou

Export používajte ako mapu správania.

1. Začnite súpisom stránok

V Sproute je FUNCTIONALITY-ANALYSIS.md už sám osebe dobrý zoznam stránok. Ak taký dokument nemáte, zostavte ho z dát stránok.

Pri každej stránke si zapíšte:

• routu
• model prístupu
• účel
• hlavné akcie používateľa
• dôležité formuláre
• workflowy spúšťané pri načítaní alebo odoslaní
• z akých dát stránka čerpá
• kam stránka ďalej naviguje

Tak získate prehľad o celom rozsahu produktu.

2. Nájdite vzory, ktoré sa v aplikácii opakujú

V Sproute sú opakujúce sa vzory dôležitejšie ako jednorazové detaily stránok.

Príklady:

• vynucovanie admin oprávnení na viacerých stránkach
• inicializácia z query parametrov pri reportoch a obnove hesla
• presmerovacie stránky pri zmene organizácie a lokality
• spoločná navigácia/sidebar
• popupy, ktoré zobrazia detail bez opustenia stránky

Pre tieto opakujúce sa postupy vytvorte spoločné React komponenty a funkcie.

3. Vystopujte vstupné body runtimu

V Sproute sú vstupné body runtimu dôležitejšie ako jednotlivé vygenerované komponenty.

Začnite týmito súbormi:

• src/_front/router.js
• src/wwLib/services/wwWebsiteData.js
• src/_common/helpers/data/index.js
• src/_common/helpers/code/workflows.js
• src/wwLib/services/wwCollection.js
• src/pinia/variables.js

Spolu vysvetľujú:

• kedy sa resetuje stav stránky
• kedy sa kontroluje prihlásenie
• kedy sa inicializujú premenné
• kedy bežia workflowy
• kedy sa načítavajú kolekcie
• kedy prebieha navigácia

Tieto súbory ukazujú, kedy aplikácia spúšťa jednotlivé časti logiky.

4. Premeňte koncepty runtimu na mapu domén

Skôr než napíšete prvý riadok v Reacte, opíšte systém jazykom domény.

Napríklad:

• z „kolekcie 476bb250-...“ by mali byť „dáta aktuálnych organizácií“ alebo „zoznam transakcií rodiny“
• z „workflowu 14ae93a6-...“ by mal byť „guard na admin prístup“
• z „query premennej“ by mal byť „stav filtra, ktorý vlastní URL“
• z „akcie na otvorenie popupu“ by malo byť „zobrazenie detailu v modale“

Ak nový kód v Reacte stále hovorí jazykom ID z WeWebu a generických typov akcií, architektúra je pôvodnému systému stále príliš blízko.

Ako preložiť koncepty WeWebu do konceptov Reactu

Podľa tohto mapovania môžete rozhodnúť, kam jednotlivé časti patria.

Koncept vo WeWebe	Čo znamená	Cieľ v Reacte
Stránka	Routa alebo obrazovka, ktorú vidí používateľ	Modul routy plus feature modul
Sekcia	Znovupoužiteľný kus layoutu alebo obsahu	Layout komponent alebo doménový komponent
Element	UI primitívum alebo widget	Primitívum dizajn systému alebo feature komponent
Workflow	Implicitný graf udalostí a stavov	Explicitná logika routy, servisná logika, handler mutácie alebo handler UI udalosti
Kolekcia	Zdroj dát alebo dopyt	Typovaná API funkcia plus dopyt na serverový stav
Premenná	Kontajner na rôzne druhy stavu	Stav v URL, stav formulára, lokálny UI stav, uložená preferencia alebo stav session
Plugin	Adaptér na integráciu alebo runtime	Servisný klient, wrapper SDK alebo infraštruktúrny modul
Vzorec	Odvodená logika alebo výraz	Utilita v TypeScripte, selektor, formátovač alebo doménové pravidlo

Na tomto mapovaní záleží. Bráni tomu, aby ste namiesto aplikácie znova naprogramovali WeWeb.

Cieľová architektúra v Reacte

Každému modulu určite zodpovednosť. Táto štruktúra môže poslúžiť ako východisko.

src/
  app/
    router/
    providers/
    layouts/
    guards/
  features/
    auth/
    families/
    students/
    activities/
    reports/
    commerce/
    settings/
  entities/
    user/
    organization/
    class/
    transaction/
  shared/
    ui/
    forms/
    api/
    lib/
    config/
    types/
  pages/
    login/
    dashboard/
    admin-families/
    family-profile/
    reports-financial/

Názvy priečinkov si môžete upraviť, ale rozdelenie zodpovedností by malo zostať rovnaké.

Aplikačná vrstva

Zodpovedá za:

• routing
• providery
• základný layout (shell)
• hranicu autentifikácie
• globálne spracovanie chýb
• bootstrap aplikácie

Sem patrí ochrana súkromných rout a providery, ktoré používa celá aplikácia.

Feature vrstva

Zodpovedá za:

• doménové workflowy
• loadery a akcie rout
• query hooky
• mutácie
• obrazovky pre ohraničenú oblasť

V Sproute to znamená samostatné feature moduly pre autentifikáciu, reporty, aktivity, predaj a správu rodín.

Zdieľaná vrstva

Zodpovedá za:

• API klientov
• spoločné UI
• abstrakcie formulárov
• utility na schémy
• formátovanie a generické pomocné funkcie

Biznis logiku konkrétnych funkcií nechajte mimo zdieľaných modulov.

Vrstva entít

Zodpovedá za:

• základné biznis typy
• znovupoužiteľné selektory
• malé doménové utility

Použite ju, keď viacero feature modulov stojí na tom istom základnom objektovom modeli.

Odporúčané technické voľby

Pri väčšine migrácií fungujú dobre tieto predvolené voľby:

• React Router na moduly rout a routing, ktorý pracuje s dátami
• TanStack Query na serverový stav a životný cyklus mutácií
• React Hook Form plus Zod na stav formulárov a validáciu
• typovaná vrstva API klienta pre Xano alebo backend, ktorý ho nahradí
• minimalistické riešenie klientského stavu, len pre naozaj lokálny stav alebo stav shellu aplikácie
• knižnica komponentov alebo interný dizajn systém na UI primitíva

Pri každej voľbe knižníc zachovajte oddelené zodpovednosti.

Čo v Reacte znova nevytvárať

Tieto vzory z WeWebu v Reacte znova nestavajte:

1. Obrovský generický store na premenné

src/pinia/variables.js mieša:

• query parametre
• local storage
• premenné webu
• premenné pluginov
• premenné komponentov
• meniteľné objekty a polia

V Reacte to rozdeľte podľa toho, komu čo patrí:

• stav v URL patrí do routera alebo search parametrov
• serverový stav patrí do cache dopytov a mutácií
• stav formulára patrí do knižnice na formuláre
• lokálny UI stav patrí do komponentov
• trvalé preferencie patria do malej abstrakcie na ukladanie
• stav session a prihlásenia patrí do auth modulu

V jednom globálnom store by zostali tieto rozdielne druhy stavu zmiešané.

2. Interpreter workflowov

src/_common/helpers/code/workflows.js vám pomôže pochopiť správanie aplikácie, no ako cieľová architektúra sa nehodí.

Tento súbor dnes rieši:

• riadenie toku (control flow)
• navigáciu
• načítavanie dát
• zmeny stavu
• nahrávanie súborov
• popupy
• volania pluginov
• zmenu jazyka
• logovanie

V Reacte tieto zodpovednosti presuňte do explicitných modulov. Z ich názvov má byť jasný biznis zámer.

Namiesto tohto:

• „spusti workflow 14ae93a6-...“

Chcete toto:

• requireAdminAccess()
• initializeFinancialReportFiltersFromUrl()
• switchOrganizationAndRedirectHome()
• submitClassCreationForm()

3. Abstrakcia kolekcií ako hlavný dátový model

src/wwLib/services/wwCollection.js je abstrakcia navrhnutá pre runtime. Dáta načítava cez adaptéry pluginov a väzby v konfigurácii.

V no-code runtime je to v poriadku. Dlhodobý frontend v Reacte by ste však takto navrhovať nemali.

Vaša aplikácia v Reacte by mala uprednostňovať:

• typované funkcie na požiadavky
• loadery rout tam, kde dávajú zmysel
• query hooky so stabilnými kľúčmi
• mutácie s jasnými pravidlami invalidácie
• doménové názvy namiesto ID kolekcií

Ako správne prestavať prácu s dátami

Aplikácia vo WeWebe často stiera hranicu medzi serverovým a klientským stavom. Nová aplikácia v Reacte by ich mala jasne oddeliť.

Serverový stav

Sem patrí:

• aktuálny používateľ
• organizácie a lokality
• rodiny
• aktivity
• reporty
• transakcie
• detaily kurzov
• obsah zásad

O načítanie, cachovanie, invalidáciu a opätovné načítanie serverového stavu sa má starať nástroj určený na serverový stav.

V Sproute sa kolekcie dnes načítavajú pri inicializácii runtimu a počas behu workflowov. V Reacte z toho majú byť loadery rout alebo query hooky blízko feature modulu, ktorý dáta používa.

Klientský stav

Sem patrí:

• otvorený modal
• vybraná záložka
• aktuálny režim zobrazenia kalendára
• optimistický stav rozpracovaných zmien
• dočasné filtre, ktoré nemá zmysel ukladať do URL

Predvolene ho držte lokálne.

Stav v URL

Sprout na viacerých miestach inicializuje stránky z query parametrov:

• obnova hesla
• rozsahy dátumov v reportoch
• režim zobrazenia
• duplikovanie
• filtre pre embed

To jasne naznačuje, že aj v novej aplikácii tieto hodnoty patria do URL.

Neschovávajte ich do storu.

Trvalé preferencie

Ak má hodnota prežiť navigáciu alebo novú session, uzavrite túto logiku do malého modulu:

• téma
• vybraná organizácia
• vybraná lokalita
• naposledy použitý režim zobrazenia

Nemiešajte to s biznis entitami.

Ako prestavať routing a navigáciu

src/_front/router.js patrí v exporte Sproutu medzi najužitočnejšie súbory. Ukazuje, ako aplikácia dnes o routingu premýšľa.

Prezradí, že:

• routy sa generujú z window.wwg_designInfo
• prihlásenie sa kontroluje pri vstupe na routu
• moduly stránok sa importujú dynamicky
• dáta stránky sa načítajú pred vykreslením
• jazyk a hash sú súčasťou routingu

V Reacte urobte routing explicitný.

Odporúčaný model routingu

Pre stabilné biznis routy postavte moduly rout:

• /login
• /signup
• /home
• /admin/families
• /admin/families/:familyOrganizationId
• /activity-calendar
• /financial-reports
• /class-detail/:classId

Každý modul routy by mal zodpovedať za:

• požiadavky na prístup na úrovni routy
• parsovanie parametrov routy
• logiku loadera, ak treba dáta ešte pred vykreslením
• podľa potreby vlastný error boundary na úrovni routy

Kontrola prihlásenia a oprávnení

V Sproute je logika prihlásenia a oprávnení rozdelená medzi metadáta rout, stav auth pluginu a workflowy.

V Reacte ju spojte do jedného systému prístupu:

• auth provider alebo hranica session
• model oprávnení
• route guard alebo kontrola v loaderi

Dobré pravidlo:

• autentifikácia rozhoduje, či používateľ smie vstúpiť do súkromnej časti
• autorizácia rozhoduje, ku ktorým oblastiam aplikácie má prístup
• kód feature modulov by nemal stále znova vymýšľať logiku presmerovaní

Presmerovacie stránky

Sprout pri zmene organizácie a lokality používa špeciálne presmerovacie stránky.

V Reacte z nich môžu byť explicitné handlery mutácií alebo príkazov:

• aktualizovať aktívnu organizáciu
• invalidovať závislé dopyty
• presmerovať na cieľovú úvodnú stránku

Samostatnú prechodovú routu si môžete nechať, ak zlepšuje UX. Malo by to však byť vedomé produktové rozhodnutie, nie vedľajší produkt starého runtimu.

Ako prestavať autentifikáciu

V príklade Sprout je autentifikácia roztrúsená na týchto miestach:

• kontroly rout v router.js
• stav auth pluginu pre Xano
• workflowy na úrovni aplikácie, napríklad odhlásenie pri neplatnom účte
• inicializácia organizácie a lokality

V no-code runtime je to bežné. V kóde to ideálne nie je.

Lepšia hranica autentifikácie v Reacte

Vytvorte jeden auth modul, ktorý zodpovedá za:

• získanie session
• stratégiu ukladania tokenu
• načítanie aktuálneho používateľa pri štarte
• spracovanie neplatnej session
• presmerovania pri chýbajúcom oprávnení
• vyhodnotenie rolí a oprávnení

Navonok by mal ponúkať explicitné koncepty:

• isAuthenticated
• currentUser
• permissions
• activeOrganization
• activeLocation

Nenúťte feature moduly vedieť, ako fungujú tokeny alebo stav pluginu.

Prihlásenie s viacerými kontextmi riešte čisto

Sprout pracuje s organizáciami aj lokalitami. Pri kontrole prístupu preto treba okrem prihlásenia zohľadniť aj vybranú organizáciu a lokalitu.

Pravdepodobne budete potrebovať:

• kontext session
• kontext organizácie
• kontext lokality
• maticu oprávnení odvodenú od používateľa a kontextu

Vymodelujte to explicitne v typoch a selektoroch v TypeScripte.

Formuláre postavte nanovo, neprekladajte ich

Formuláre vo WeWebe často skrývajú logiku v premenných, workflowoch a stave komponentov. To neznamená, že to má robiť aj verzia v Reacte.

Každý dôležitý formulár má byť explicitný

Pri každom formulári definujte:

• schému
• zdroj predvolených hodnôt
• kontrakt pre odoslanie
• validačné pravidlá
• čo sa stane pri úspechu
• spracovanie chýb
• optimistické správanie alebo správanie počas načítania

Príklady zo Sproutu:

• prihlásenie
• registrácia
• obnova hesla
• úprava profilu rodiny
• vytvorenie kurzu
• filtre reportov
• akcie v košíku a pri pokladni

Odporúčaný vzor pre formuláre

Pri každom formulári:

1. predvolené hodnoty odvoďte z loadera routy, query parametrov alebo načítaného serverového stavu
2. validujte cez schému
3. odosielajte cez typovanú mutáciu
4. cache aktualizujte zámerne
5. podľa definovaných pravidiel pre úspech presmerujte alebo zobrazte notifikáciu

Je to oveľa prehľadnejšie ako graf workflowu, ktorý mení generické premenné a potom podmienene prepne stránku.

Ako prestavať skladbu UI a dizajn systém

Vygenerované sekcie pomôžu pochopiť vzory v layoute. Ako dlhodobé hranice komponentov sa však hodia len zriedka.

V Sproute sa opakujú napríklad tieto sekcie:

• navigácia v sidebare
• indikátory načítania
• branding
• hlavičky
• kontajnery modálnych okien

Z nich by mali byť premyslené komponenty dizajn systému alebo shellu aplikácie.

Lepšia hierarchia UI

Použite tri úrovne:

1. Základné UI komponenty (primitíva)

Príklady:

• tlačidlá
• vstupné polia
• selecty
• modaly
• tabuľky
• štítky

2. Komponenty shellu aplikácie

Príklady:

• sidebar
• horná navigácia
• kontajner stránky
• layout pre prihlásených
• hlavička sekcie

3. Feature komponenty

Príklady:

• panel so zoznamom rodín
• karta profilu študenta
• lišta s rozsahom dátumov pre report
• tabuľka s prehľadom transakcií
• panel s rozvrhom kurzu

Vďaka tejto hierarchii budú komponenty odrážať produkt, nie no-code nástroj.

Ako preložiť workflowy do explicitnej logiky

Pomocou každého workflowu zistite, aké správanie potrebujete vytvoriť znova.

Pri každom workflowe sa opýtajte:

• je to logika pri vstupe na routu?
• je to koordinácia medzi funkciami?
• je to spracovanie UI udalosti?
• je to len odvodený stav?
• je to vedľajší efekt, ktorý spustila mutácia?

Potom ho presuňte na správne miesto.

Vzory prekladu workflowov

Vzor 1: presmerovania pri autentifikácii

Dnešná podoba vo WeWebe:

• metadáta routy plus vetva workflowu plus akcia na zmenu stránky

Podoba v Reacte:

• route guard alebo loader
• centrálny helper na presmerovanie pri autentifikácii
• hranica layoutu, ktorá pozná oprávnenia

Vzor 2: inicializácia z query parametrov

Dnešná podoba vo WeWebe:

• query premenná plus workflow before-collection-fetch

Podoba v Reacte:

• search parametre parsujte v route alebo vo feature hooku
• normalizujte ich do typovaného stavu filtrov
• odovzdajte ich do query kľúčov alebo predvolených hodnôt formulára

Vzor 3: detail v popupe

Dnešná podoba vo WeWebe:

• načítať kolekciu, potom otvoriť popup

Podoba v Reacte:

• ID vybranej entity v URL alebo v lokálnom stave
• dopyt na dáta detailu
• modálny komponent s explicitnými props a stavmi načítania

Vzor 4: presmerovacie stránky

Dnešná podoba vo WeWebe:

• vstup na stránku, spustenie workflowu, presmerovanie inam

Podoba v Reacte:

• explicitný command handler alebo prechodová routa s úzkym účelom

Vzor 5: inicializácia kalendára

Dnešná podoba vo WeWebe:

• workflow pri načítaní nastaví premenné dátumov a stav zobrazenia

Podoba v Reacte:

• loader routy pre potrebné dáta
• počiatočný stav odvodený z URL alebo z predvolených hodnôt
• feature hook, ktorý koordinuje rozsah dátumov a filtre

Kam patrí ktorý typ logiky

Každý workflow či premennú, na ktorú narazíte, zaraďte podľa tejto tabuľky.

Ak logika	Patrí sem
riadi prístup na stránku	route guard alebo loader routy
načítava dáta zo servera	query hook alebo loader routy
mení dáta na serveri	handler mutácie alebo feature služba
riadi filtre v URL	parser search parametrov plus synchronizácia s URL
ovplyvňuje len jeden komponent	lokálny stav komponentu
predstavuje zdieľané doménové správanie	feature služba alebo doménová utilita
otvára alebo zatvára overlaye	lokálny UI stav alebo správca modálov na úrovni shellu
upravuje načítané dáta na zobrazenie	selektor alebo čistá utilita

Migrujte po jednotlivých funkciách

Nemigrujte vrstvu po vrstve: najprv JSON stránok, potom sekcie, potom elementy, potom workflowy. Vznikne vám tak aplikácia v Reacte, ktorá zrkadlí no-code runtime.

Presúvajte radšej celé funkcie.

Dobré poradie pre reálny projekt

1. Shell aplikácie a autentifikácia

Postavte:

• router
• hranicu autentifikácie
• layouty
• bootstrap session
• kontroly oprávnení

Na tom budú stáť všetky ďalšie časti.

2. Jedna typická funkcia v súkromnej časti

Vyberte časť aplikácie, ktorá ide naozaj do hĺbky, napríklad:

• profil rodiny
• detail kurzu
• kalendár aktivít

Tu si naozaj overíte, či vaše vzory pre routing, dáta, formuláre a UI fungujú.

3. Jedna admin časť

Vyberte napríklad:

• správu rodín v administrácii
• finančné reporty
• posudzovanie žiadostí o zrušenie

Overíte si tak hranice oprávnení a zložitejšie workflowy.

4. Spoločné systémy pre celú aplikáciu

Keď sa vzory osvedčia, vytiahnite do spoločných častí:

• vzory pre tabuľky
• vzory pre modaly
• lišty s filtrami
• stavebné bloky formulárov
• konvencie pre query kľúče

5. Predaj a okrajové scenáre

Potom sa pustite do:

• košíka
• transakcií
• interakcií podobných pokladni
• embed scenárov
• prepínania organizácie/lokality

Pri tomto poradí budete architektúru prerábať menej.

Ako na Xano a externé integrácie

Sprout používa Xano cez pluginy WeWebu. Pri migrácii by sa z Xano mala stať explicitná hranica integrácie s backendom.

Uprednostňujte:

• typovaných API klientov
• schémy požiadaviek a odpovedí
• centrálnu správu auth hlavičiek
• úzke servisné moduly pre každú funkčnú oblasť

Vyhnite sa:

• abstrakciám v tvare pluginov, ktoré presakujú do kódu feature modulov
• generickým helperom typu „spusti akciu na backende“ na každom kroku

Ak neskôr Xano vymeníte, feature moduly by ste nemali musieť celé prepisovať.

Antivzory, ktoré migrácii uškodia

Antivzor 1: ID z WeWebu v logike aplikácie

Namiesto nič nehovoriacich ID kolekcií a workflowov používajte názvy, ktoré opisujú dáta a správanie.

Antivzor 2: no-code runtime postavený v Reacte

Ak nakoniec máte:

• generické registre akcií
• obrovský engine, ktorý vykonáva flowy podľa konfigurácie
• jeden univerzálny register stavu
• dynamické vykresľovanie všetkého

postavili ste starý problém nanovo, len v inom frameworku.

Antivzor 3: zachované vygenerované hranice komponentov

Vygenerované sekcie nie sú automaticky dobré hranice komponentov.

Berte ich ako vodítko, nie ako finálnu štruktúru.

Antivzor 4: dáta entít zmiešané so stavom UI

Zvyčajne sa to stane, keď tím prenesie logiku postavenú na premenných príliš doslovne.

Doménové dáta, stav routy a stav UI držte oddelene.

Antivzor 5: migrácia len ako zhoda funkcií pri testovaní

Na zhode so starou aplikáciou záleží, ale sama osebe nestačí.

Potrebujete aj:

• aspoň rovnakú udržiavateľnosť
• aspoň rovnakú pozorovateľnosť (observability)
• lepšiu typovú bezpečnosť
• lepšiu testovateľnosť

Inak sa vám náklady na migráciu nevrátia.

Praktická architektúra pre aplikáciu typu Sprout

Keby som prestavoval Sprout, cielil by som na niečo takéto:

flowchart TD
    browser[Browser]
    router[ReactRouter]
    authBoundary[AuthBoundary]
    layouts[AppLayouts]
    features[FeatureModules]
    queryLayer[ServerStateLayer]
    apiLayer[TypedAPILayer]
    xano[XanoBackend]

    browser --> router
    router --> authBoundary
    authBoundary --> layouts
    layouts --> features
    features --> queryLayer
    queryLayer --> apiLayer
    apiLayer --> xano

Pravidlá, ktoré k tomu patria:

• loadery rout riešia prístup a inicializáciu, ktorá patrí k route
• TanStack Query spravuje načítané entity a invalidáciu cache
• feature moduly majú na starosti mutácie a biznis workflowy
• formuláre si držia vlastné schémy a postup odoslania
• stav shellu zostáva mimo biznis entít
• zdieľané UI primitíva sú oddelené od feature widgetov

Produkčné základy, ktoré by nová aplikácia mala mať

Jasné hranice

Každý by mal vedieť, kam dať:

• logiku routingu
• auth logiku
• načítavanie dát
• logiku formulárov
• koordináciu medzi modulmi funkcií
• UI primitíva

Typované kontrakty

Nová aplikácia by mala mať typované kontrakty pre:

• API požiadavky
• API odpovede
• parametre rout
• search parametre
• doménové entity
• schémy formulárov

Pozorovateľné správanie

Mali by ste vedieť sledovať:

• neúspešné dopyty
• neúspešné mutácie
• prechody medzi stavmi prihlásenia
• zlyhania navigácie
• dôležité biznis udalosti

Testovateľné doménové toky

Kritické cesty by sa mali dať otestovať bez emulovania workflow enginu:

• prihlásenie
• presmerovania podľa oprávnení
• vytvorenie kurzu
• filtrovanie reportov
• zmeny v košíku
• prepínanie organizácie

Disciplína v dizajn systéme

Používajte spoločné komponenty namiesto samostatnej verzie pre každú stránku.

Otázky na kontrolu migrácie

Pri každom kúsku logiky z WeWebu sa opýtajte:

1. aké správanie z pohľadu používateľa tým vzniká?
2. aké biznis pravidlo sa za tým skrýva?
3. kto by mal toto pravidlo vlastniť v bežnej aplikácii v Reacte?
4. viem toto pravidlo naprogramovať bez toho, aby som znova vytvoril runtime WeWebu?

Ak na poslednú otázku odpoviete nie, ste stále príliš blízko starej architektúre.

Výsledok porovnajte s pôvodnou aplikáciou

Pomocou exportu z WeWebu zistite, ako sa produkt správa, od akých dát závisí a aké pravidlá a postupy používa. Postavte ich v Reacte. Potom overte, či je nový kód prehľadný, testovateľný a zrozumiteľný tímu, ktorý ho bude udržiavať.