Skip to content

8. Doporučený migrační plán

K odhadům: tento dokument neuvádí hodiny ani týdny. Pracnost je popsána jen kvalitativně — nízká / střední / vysoká — jako vodítko, kde leží těžiště práce. Konkrétní ocenění a harmonogram stanovuje dodavatel.

Stupnice: nízká = mechanická nebo přímočará práce · střední = běžná implementace s vlastní business logikou · vysoká = netriviální doména, hodně hraničních stavů nebo integrace na cizí systém.

Cíl migrace

Přechod z Base44 platformy na vlastní stack:

  • Frontend: React SPA (zachovat stávající kód, nahradit Base44 SDK)
  • Backend: Vlastní API server (PHP / Node.js / Go — dle preference)
  • Databáze: PostgreSQL nebo MySQL

Fáze migrace

Fáze 1 — Příprava a datový model · pracnost střední

Ověřený fakt — datový model je plně zdokumentován v entity JSONC souborech.

  1. Navrhnout SQL schéma na základě base44/entities/*.jsonc
  2. Definovat vztahy a indexy (foreign keys, date indexy pro kalendář)
  3. Nastavit vývojové prostředí (DB, API server)
  4. Napsat export/import skript pro migraci dat z Base44 (JSON export → SQL INSERT)

Klíčové tabulky: calendar_events, bookings, clients, therapists, therapist_services, rooms, availability_blocks, services, payment_logs, credit_transactions, client_packages, notification_logs, activity_logs, otp_codes, system_settings, vouchers, legal_documents

Pozn. k exportu z 19. 8. 2026: datový model má 28 entit. Nezapomenout na nové/rozšířené oblasti:

  • vouchers, legal_documents (nové entity)
  • souhlasy a podpis na clients (vop_*, gdpr_*, marketing_*, survey_*, signature_*, is_profile_complete) a client_number jako variabilní symbol
  • segmentace na services (online_booking_enabled, allowed_client_category_ids, voucher_enabled, is_insurance)
  • portál a MS kalendář na therapists (portal_access_enabled, portal_user_email, microsoft_calendar_*, portal_can_override_capacity)
  • stav paid byl z status odebrán — platba jen přes payment_status

Změna logiky (export 19. 8. 2026) — účetní osa navíc: invoices, payment_logs a credit_transactions už nejsou prosté logy, ale evidence účetních událostí. Schéma musí od začátku počítat s:

  • event_id (UUID účetní události) jako idempotenčním klíčem napříč třemi tabulkami — unikátní index
  • purchase_id pro nákupy mimo rezervaci (kredit, balíček, voucher)
  • typologií dokladů (document_type, accounting_phase, document_source, tax_document_flag)
  • stavem exportu (pohoda_export_status, pohoda_external_id, pohoda_export_error)
  • client_number sekvencí a invoice_number sekvencí — v SQL řešit sekvencí/FOR UPDATE, ne čítačem v tabulce nastavení jako v Base44

Fáze 2 — API backend · pracnost vysoká

Napsat vlastní REST API pokrývající veškeré operace. Priority:

Blok A — Kritická cesta (kalendář + rezervace) · vysoká:

  • GET/POST/PUT/DELETE /calendar-events
  • GET /availability-blocks + výpočet volných slotů
  • POST /bookings (vytvoření + business logika splatnosti)
  • POST /bookings/:id/cancel (storno logika s refundem)

Blok B — Klientský portál · střední:

  • POST /auth/otp/request + POST /auth/otp/verify
  • GET /client/bookings
  • POST /client/bookings/:id/pay (kredit, balíček)
  • POST /client/onboarding (uložení souhlasů + podpisu, potvrzovací e-mail s PDF VOP)
  • GET/POST /vouchers + POST /vouchers/:code/redeem (serverová validace — viz R14)

Blok C — Podpůrné operace · nízká (objemově velké, ale mechanické):

  • CRUD /clients, /therapists, /therapist-services, /rooms, /services
  • CRUD /legal-documents (VOP/GDPR, verzování)
  • GET/POST /payment-logs
  • POST /notifications/send (wrapper nad Resend + SmsManager — port existující logiky ze sendNotification)
  • GET /activity-logs

Blok D — Účetnictví a doklady · vysoká:

Změna logiky: účetní vrstva už není „nová část k návrhu" — v exportu existuje hotová (base44/shared/*, 1 142 řádků, plus 8 účetních funkcí). Jde tedy o port, ale objemově jde o největší přírůstek celého exportu.

  • Generování dokladů — daňový doklad, zálohová faktura, nedaňové potvrzení, dobropis, storno poplatek, pokladní doklad (shared/documentGeneration.ts)
  • Vznik výnosu při realizaci služby (shared/serviceRevenue.ts) — v Base44 spouštěno automatem na status = completed
  • Storno poplatky a vratky (shared/cancellationAccounting.ts, processRefund — 4 způsoby vratky: kredit, balíček, hotovost, brána)
  • POST /purchases/:id/document — doklad k nákupu balíčku/voucheru/kreditu
  • GET /public/invoice?token=… — veřejný výdej dokladu podle tokenu
  • Export do Pohody — dataPack XML, dávky, deduplikace přes event_id, zpracování responsePack, doplnit retry pro failed (viz R18)

Blok E — Automatizace a integrace · vysoká:

  • Cron job pro reminderDispatcher (každých 5 minut nebo nahradit queue)
  • Doménové události nahrazující Base44 automaty: completed → výnos, cancelled_late → storno poplatek, nový klient → client_number
  • POST /outlook/sync (MS Graph API)
  • Portál terapeuta — OTP přihlášení přes portal_user_email, vlastní kalendář a měsíční CSV export výkonů
  • Přihlášení personálu (OTP) + serverová kontrola oprávnění podle rolí admin, admin-klientske, klientske, finance (v Base44 běží jen na frontendu — viz R19)
  • Telefonie OptimCall — jediná integrace, která v exportu není implementovaná (webhook příchozích hovorů)

Fáze 3 — Frontend refaktoring · pracnost nízká

Cíl: nahradit base44.entities.* a base44.functions.invoke() voláním vlastního API.

Strategie — API abstrakce layer:

Místo přímé výměny každého SDK volání doporučujeme vytvořit API klient modul:

// src/api/client.js (nový)
export const api = {
  calendarEvents: {
    list: (params) => fetch('/api/calendar-events?' + new URLSearchParams(params)),
    create: (data) => fetch('/api/calendar-events', { method: 'POST', body: JSON.stringify(data) }),
    // ...
  },
  bookings: { ... },
  // ...
};

Pak nahradit base44.entities.X.list() za api.X.list() — mechanická záměna, která lze z velké části automatizovat grepem.

Postup po stránkách (pořadí dle priority):

  1. Calendar.jsx + komponenty calendar/ (21 komponent vč. RefundDialog, PaymentMethodDialog) — nejkritičtější
  2. Clients.jsx + ClientDetail.jsx
  3. Klientský portál (ClientPortal.jsx a sub-komponenty)
  4. AvailabilityManagement.jsx
  5. Nastavení stránky (nízká priorita)

Fáze 4 — Autentizace · pracnost střední

Nahradit Base44 session management a doplnit serverovou autorizaci:

  • Implementovat JWT nebo session-cookie auth
  • Aktualizovat AuthContext.jsx — zachovat interface (isLoadingAuth, authError, atd.)
  • Nastavit middleware/guards pro chráněné routy
  • Tři nezávislé OTP toky (klient, terapeut, personál) — v Base44 všechny v clientAuth
  • Přenést kontrolu rolí z frontendu na server (dnes jen permissions.js)

Fáze 5 — Testování a cutover · pracnost střední až vysoká

  1. Paralelní provoz: nový systém v staging, Base44 v produkci
  2. Migrace dat z Base44 do nové DB
  3. Automatizovaná testovací sada (unit, integrační API, webhooky, cron, E2E)
  4. Smoke testy všech kritických flow:
  5. Admin vytváří termín v kalendáři
  6. Klient se přihlásí OTP a zarezervuje termín
  7. Klient zaplatí kreditem
  8. Admin stornuje termín s vrácením
  9. Připomínky se odešlou ve správný čas
  10. Cutover — přepnutí DNS / deployment

Co ponechat beze změny

Ověřený fakt — tyto části přecházejí bez úprav:

Oblast Zdůvodnění
Tailwind CSS + shadcn/ui komponenty Žádná Base44 závislost
Logika výpočtu volných slotů Čistý JavaScript v CalendarUtils.js
ICS generátor Čistá TypeScript funkce
OTP flow logika Přenositelná, jen změna DB layer
Storno logika (cancel_booking) Přenositelná business logika
E-mailové šablony + Resend volání Přímé fetch, jen přemístit do backendu
React Query cache strategie Žádná Base44 závislost
Routing struktura Standardní react-router-dom

Co přepsat od základu

Oblast Zdůvodnění
Admin přihlášení Base44-specific, nutná nová implementace
AuthContext.jsx Závisí na Base44 session
base44Client.js Nutno nahradit vlastním API klientem
@base44/vite-plugin Odstranit z vite.config.js

Rozpad backendu podle oblastí

Členění backendové práce na samostatně ocenitelné položky. Pracnost je relativní v rámci tohoto projektu, ne absolutní měřítko.

Oblast Pracnost
Analýza frontendu, API kontrakt, mapování Base44 → cílový framework střední
Kostra aplikace, DB, migrace, seed střední
Kompatibilní API vrstva (entities.*, functions.invoke) střední
Auth (admin, klient OTP, terapeut OTP, personál OTP, role) vysoká
CRUD/master data nízká (objemově velké)
Kalendář, dostupnost, konflikty, kapacity vysoká
Rezervace, storno, refund vysoká
Platby, kredity, balíčky, vouchery, platební brána vysoká
Notifikace (e-mail/SMS, reminder, logy) nízká
Fakturace a účetní doklady vysoká
Export do Pohody vysoká
Outlook sync střední
Telefonní integrace (OptimSys/OptimCall) střední — v exportu neexistuje, píše se od nuly
Testy a stabilizace (unit, API, webhook, cron, E2E) vysoká

Položky, které se snadno podcení:

  • Testování jako samostatný rozpočet — ne jen smoke testy před cutoverem, ale psaná automatizovaná sada (unit + integrační + E2E).
  • Tři OTP toky — klient, terapeut i personál, každý s vlastními pravidly.
  • Fakturace jako plnohodnotný port existující logiky, ne nová věc od nuly.
  • Webhooky platební brány s idempotencí — netriviální položka.

Rozsah kódu k portování (ověřená fakta z exportu)

Referenční čísla z exportu z 19. 8. 2026, var/source/base44/:

Ukazatel Hodnota
Počet entit (entities/*.jsonc) 28
Backendové funkce (functions/) 18
Řádků kódu ve functions/ 4 874
Řádků kódu ve shared/ (účetní vrstva) 1 142
Celkem backendové logiky 6 016 řádků

Pozn.: starší export obsahoval 10 funkcí a 2 901 řádků. Objem backendové logiky se mezi exporty přibližně zdvojnásobil — kdo pracuje se starším exportem, má před sebou zhruba poloviční kódovou základnu.

Dopad exportu z 19. 8. 2026 na rozsah

Změna logiky: to, co bylo dosud vedeno jako „bude se řešit až v našem backendu" (Pohoda, SMS), je nyní hotové v Base44 — z pohledu migrace to ale znamená další kód k portování, ne úsporu. Ubyl návrh, přibyla implementace.

Oblast Dopad na rozsah
Účetní vrstva (shared/*, 8 nových funkcí) + největší jednotlivá položka; doklady, výnosy, storno poplatky, vratky
Export do Pohody (dataPack XML, dedup, responsePack) + port + ověření proti reálnému mServeru, plus retry, které v exportu chybí
SMS (SmsManager) ≈ malá položka, přímé volání API — ale už není „nová integrace od nuly"
Přihlášení personálu + serverová autorizace rolí + třetí OTP tok a přesun oprávnění z frontendu na server
Vratky a dobropisy (4 způsoby vratky) + položka, kterou dřívější rozvahy vůbec neobsahovaly
Pojišťovny (stav, stornopoplatek, veřejná úhrada /storno) + nový business tok
Portál terapeuta (kalendář, rezervace, CSV export) + podstatně větší než původní „správa vlastních kapacit"
Telefonie OptimCall ≈ beze změny, stále k implementaci od nuly

Odvozeno — oblasti závislé na účetnictví (fakturace, platby/kredity, testy) narostly nejvíc; oblasti na účetnictví nezávislé (kostra, CRUD, kalendář) zůstávají beze změny.

Souhrn pracnosti po fázích

Fáze Pracnost Poznámka
Datový model + export dat střední účetní osa, sekvence, idempotence přes event_id
API backend (vč. auth) vysoká těžiště celého projektu — účetní vrstva, Pohoda, vratky, tři OTP toky
Frontend refaktoring nízká výměna SDK za API klient je mechanická
Testování + cutover střední až vysoká vč. automatizované sady; účetní toky je nutné testovat důkladně

Co rozsah nezahrnuje: telefonii OptimCall, migraci a backfill historických dat do nových účetních polí (viz O26) a ověřovací kolo s účetní nad zálohovým režimem kreditu (viz O24).