4. Datový model (entity)

Ověřený fakt — zdrojová data z adresáře base44/entities/. Celkem 28 entit.

Kompletní seznam: ActivityLog, AppointmentStatus, AvailabilityBlock, Booking, CalendarEvent, CalendarSettings, Client, ClientCategory, ClientCredit, ClientPackage, CreditTransaction, DemoUser, Invoice, LegalDocument, NotificationLog, NotificationSettings, OtpCode, PaymentLog, PaymentSettings, Room, RoomCategory, Service, ServiceCategory, ServicePackage, SystemSettings, Therapist, TherapistService, Voucher.

Změny v exportu z 19. 8. 2026 (viz git diff var/source): počet entit se nezměnil, ale 15 entit bylo rozšířeno o účetní vrstvu. Hlavní témata:

• Doklady a export do Pohody — Invoice má nyní typy dokladů (document_type), fáze účetního toku (accounting_phase), příznaky export_to_pohoda, tax_document_flag, event_id a stavy exportu (pohoda_export_status, pohoda_external_id, pohoda_export_error). Stejná exportní pole mají i PaymentLog a CreditTransaction.
• Pojišťovny — nový stav no_show_insurance u Booking/CalendarEvent, příznak is_insurance na Service a ClientCategory, stornopoplatek v SystemSettings.insurance_cancellation_fee.
• Platba na recepci — nové způsoby platby cashdesk_cash, cashdesk_card, voucher, insurance a rozlišení document_source (NEO / POKLADNA).
• Prodej mimo rezervaci — purchase_id propojuje samostatný nákup (kredit, balíček, voucher) s dokladem napříč Invoice, PaymentLog, CreditTransaction, ClientPackage, Voucher.
• Číslo klienta — Client.client_number (sekvenční, slouží jako variabilní symbol), čítač v SystemSettings.client_number_seed.
• SMS a telefonie — SMS šablony a klíč k SmsManageru v NotificationSettings, konfigurace ústředny OptimCall v SystemSettings.
• Role finance — nová role v DemoUser.

Hlavní entity

CalendarEvent

Centrální entita systému. Reprezentuje termín, blokaci nebo dovolenou v kalendáři.

Pole	Typ	Povinné	Popis
event_type	enum	ano	appointment / blockage / vacation
therapist_id	string	ano	ID primárního terapeuta
therapist_ids	array[string]	ne	IDs všech terapeutů (párová terapie)
room_id	string	ne	ID místnosti
client_id	string	ne	ID klienta (jen appointment)
booking_id	string	ne	ID rezervace (pokud vznikla z portálu)
is_online_booking	boolean	ne	Rezervováno klientem přes portál
date	date	ano	Datum události
start_time	string	ano	HH:MM
end_time	string	ano	HH:MM
all_day	boolean	ne	Celodenní událost
color	string	ne	Vlastní barva (přepíše barvu terapeuta)
service_type	string	ne	Název výkonu
status	enum	ne	reserved, confirmed, completed, excused, no_show_paid, no_show_unpaid, no_show_insurance, cancelled, auto_cancelled_unpaid, cancelled_late
payment_status	enum	ne	unpaid, pending, paid, refunded, partially_refunded
payment_method	enum	ne	credit, card, cash, transfer, demo, gateway, voucher, cashdesk_cash, cashdesk_card, insurance
payment_due_date	string	ne	Termín pro úhradu (ISO datetime)
internal_payment_id	string	ne	Interní ID platby pro spárování (číslo transakce, VS) — vyplní se při platbě na místě
notes	string	ne	Interní poznámka (jen tým NEO)
client_notes	string	ne	Poznámka od klienta z rezervace
is_recurring	boolean	ne	Opakující se událost
recurrence_rule	string	ne	weekly, biweekly, monthly
ms_outlook_event_id	string	ne	ID události v MS Outlook (sync)
document_source	enum	ne	NEO / POKLADNA — kdo vystavuje doklad k úhradě
invoice_id	string	ne	Zpětná vazba na vystavený doklad
refund_amount	number	ne	Vrácená částka při stornu s vratkou
credit_note_id	string	ne	ID vystaveného dobropisu

Booking

Rezervace — vzniká při objednání klientem nebo přes portál.

Pole	Typ	Popis
client_id	string	Klient (povinné)
therapist_id	string	Terapeut (povinné)
room_id	string	Místnost
availability_block_id	string	Blok dostupnosti, z něhož rezervace vznikla
event_id	string	Propojení na CalendarEvent
date, start_time, end_time	string	Kdy (date povinné)
service_type	string	Výkon
status	enum	reserved, confirmed, completed, excused, no_show_paid, no_show_unpaid, no_show_insurance, cancelled, auto_cancelled_unpaid, cancelled_late
payment_status	enum	unpaid, pending, paid, refunded, partially_refunded
payment_due_date	string	Splatnost (vypočítána při vytvoření)
payment_method	enum	credit, card, cash, transfer, demo, gateway, voucher, cashdesk_cash, cashdesk_card, insurance
cancellation_reason	string	Důvod storna
refund_amount	number	Vrácená částka
client_notes	string	Poznámky od klienta
is_online_booking	boolean	Portálová rezervace
notification_sent	boolean	Zda byla odeslána notifikace
document_source	enum	NEO / POKLADNA
invoice_id	string	Zpětná vazba na vystavený doklad

AvailabilityBlock

Kapacitní blok terapeuta — definuje kdy a kde může terapeut pracovat.

Pole	Typ	Popis
therapist_id	string	Terapeut
room_id	string	Místnost
date	date	Datum (nebo start recurring)
start_time, end_time	string	HH:MM
slot_duration_minutes	number	Délka slotu (default 50 min)
service_types	array	Povolené výkony (prázdné = vše)
is_recurring	boolean	Opakující se blok
recurrence_pattern	enum	daily, weekly, biweekly, monthly
recurrence_days	string	JSON array dnů ["monday","tuesday"]
recurrence_start_date	date	Začátek opakování
recurrence_end_date	date	Konec opakování (null = neomezené)
is_public	boolean	Viditelné pro klienty v portálu

Client

Evidence klientů. Obsahuje on-boarding a digitální souhlasy (VOP, GDPR, marketing, dotazníky), digitální podpis a nově číslo klienta.

Pole	Typ	Popis
client_number	number	Lidsky čitelné sekvenční ID klienta — používá se jako variabilní symbol při párování plateb
first_name, last_name	string	Jméno, příjmení (povinné)
email, phone	string	Kontakty
address	string	Adresa (ulice, město, PSČ)
date_of_birth	date	Datum narození
segment	enum	standard, vip, child, couple
category_ids	array	Přiřazené kategorie
notes	string	Poznámky
is_active	boolean	Aktivní/archivovaný
is_profile_complete	boolean	Dokončený onboarding (údaje + podpis VOP)
vop_accepted	boolean	Souhlas s VOP
vop_accepted_at	string	Čas souhlasu s VOP (ISO datetime)
vop_version	string	Verze VOP, se kterou klient souhlasil
gdpr_consent_accepted	boolean	Souhlas GDPR (povinný)
gdpr_consent_at	string	Čas souhlasu GDPR
marketing_consent_accepted	boolean	Souhlas se zasíláním novinek (volitelný)
marketing_consent_at	string	Čas marketingového souhlasu
survey_consent_accepted	boolean	Souhlas s dotazníky spokojenosti (volitelný)
survey_consent_at	string	Čas souhlasu s dotazníky
signature_data	string	SVG/PNG podpis (base64 / data URL)
signature_at	string	Čas podpisu (ISO datetime)
signature_verified_by_otp	boolean	Podpis ověřen OTP kódem

Service

Výkony nabízené klinikou. Segmentace, viditelnost v online portálu, režim pojišťovny a prodej voucherů.

Pole	Typ	Popis
name	string	Název výkonu (povinné)
description	string	Popis služby
service_category_id	string	ID kategorie služby
duration_minutes	number	Délka trvání (povinné)
is_online	boolean	Online sezení (videohovor)
is_insurance	boolean	Výkon hradí pojišťovna — klient se neúčtuje, přeskočí se fáze platby; platí stornopoplatek
requires_room	boolean	Vyžaduje místnost
allow_multiple_therapists	boolean	Párová terapie
price	number	Cena v Kč (bez DPH)
vat_rate	enum	0, 12, 21 (%)
vat_exempt_reason	string	Důvod osvobození od DPH (§ zákona)
pohoda_code	string	Kód výkonu pro export do Pohody
color, icon	string	Barva (hex) a ikona (lucide-react)
is_active	boolean	Aktivní služba
online_booking_enabled	boolean	Zobrazovat v online portálu (false = jen interní/admin)
voucher_enabled	boolean	Lze na výkon vystavit dárkový voucher
allowed_client_category_ids	array[string]	Kategorie klientů, které smí službu vidět/rezervovat (prázdné = všichni)
notes	string	Interní poznámky

Therapist

Evidence terapeutů — přístup do terapeutského portálu, napojení MS kalendáře a profilová data (medailonek).

Pole	Typ	Popis
name	string	Jméno (povinné)
email, phone	string	Kontakty
color	string	Barva v kalendáři (hex, povinné)
specializations	array[string]	Specializace
working_hours	object	Ordinační doba per den {monday: {start, end, enabled}, ...}
is_active	boolean	Aktivní terapeut
title_before, title_after	string	Tituly před/za jménem
address	string	Adresa ordinace
bio	string	Medailonek / biografie
profile_photo_url	string	URL fotografie
profile_web_url	string	URL zdrojové webové stránky medailonku
profile_xml_feed_url	string	URL XML feedu pro synchronizaci medailonku
profile_last_synced_at	string	Poslední synchronizace profilu
online_meeting_url	string	Odkaz na online schůzku (Teams, Zoom, Meet) do pozvánek
microsoft_calendar_email	string	MS / Office 365 e-mail pro napojení kalendáře
microsoft_calendar_id	string	ID MS kalendáře (po propojení)
microsoft_calendar_connected	boolean	Je MS kalendář propojen?
microsoft_calendar_connected_at	string	Čas propojení MS kalendáře
portal_access_enabled	boolean	Přístup do terapeutského portálu
portal_user_email	string	E-mail účtu pro přihlášení do portálu (OTP)
portal_can_override_capacity	boolean	Smí v portálu rezervovat online výkony i mimo naplánovanou online kapacitu

Room

Místnosti kliniky.

Pole	Typ	Popis
name	string	Název
color	string	Barva v kalendáři
capacity	number	Kapacita (0 = neomezená, 1 = ordinace)

Invoice

Doklady. Podstatně rozšířeno — z prosté faktury se stala evidence účetních událostí pro export do Pohody.

Pole	Typ	Popis
invoice_number	string	Číslo dokladu (generuje SystemSettings.invoice_number_seed)
invoice_token	string	Token pro veřejný odkaz na doklad (/invoice?token=…)
date_issued	date	Datum vystavení (= DUZP pro peněžní tok)
date_of_service	date	Datum uskutečnění plnění (datum terapie)
service_name, service_id	string	Výkon (text + FK pro dohledání pohoda_code)
amount, vat_rate, vat_amount, total_amount	number	Částky (záporné = dobropis / vratka)
document_type	enum	tax_invoice, advance_invoice, non_tax_confirmation, credit_note, penalty, cashdesk_receipt, no_doc, revenue, marketing_expense, refund, credit_transfer
status	enum	issued, cancelled, credit_note, penalty, no_doc
accounting_phase	enum	payment_receipt (doklad k přijaté platbě) / realization (vznik výnosu) — odvozuje se, nezadává
accounting_source	enum	reservation / standalone_purchase — odvozuje se při exportu
product_type	enum	service, package, credit, voucher
document_source	enum	NEO (exportuje se) / POKLADNA (doklad vznikl mimo NEO)
tax_document_flag	boolean	Jde o daňový doklad? (false u nedaňových potvrzení, záloh, stopy čerpání)
export_to_pohoda	boolean	Má se doklad exportovat do Pohody
event_id	string	UUID účetní události pro korelaci a deduplikaci exportu
purchase_id	string	Vazba na samostatný nákup
variable_symbol	string	VS (číslo dokladu + ID klienta)
original_document_ref	string	Číslo původního dokladu u dobropisu
credit_transaction_id, client_package_id, voucher_id	string	Stopa čerpání kreditu / balíčku / voucheru
source_payment_id	string	Zdrojová platba (PaymentLog), ze které doklad vznikl
cashdesk_document_number	string	Číslo dokladu z pokladního systému (jen POKLADNA)
transaction_reference	string	Reference terminálové transakce / brány
centre_id, currency	string	Středisko a měna pro účetní mapping
pohoda_export_status	enum	pending, exported, failed, skipped
pohoda_exported_at, pohoda_external_id, pohoda_export_error	string	Výsledek exportu do Pohody

PaymentLog

Záznamy o platbách — rozšířeno o kanál platby a exportní stopu.

Pole	Typ	Popis
client_id, booking_id, calendar_event_id	string	Vazby
amount	number	Částka v Kč
payment_method	enum	credit, package, card, cash, transfer, demo, gateway, voucher, cashdesk_cash, cashdesk_card, insurance
payment_channel	enum	online, bank_transfer, credit, package, voucher, cashdesk_cash, cashdesk_card
status	enum	pending, paid, failed, refunded
date	date	Datum termínu (= datum uskutečnění plnění)
gateway_transaction_id	string	ID transakce platební brány
internal_payment_id	string	Interní ID platby při platbě na místě
document_source	enum	NEO / POKLADNA
export_to_pohoda	boolean	Má se platba exportovat do Pohody
purchase_id	string	Samostatný nákup (kredit / balíček / voucher bez rezervace)
variable_symbol, transaction_reference, cashdesk_document_number	string	Párovací identifikátory
invoice_id	string	Zpětná vazba na doklad
event_id	string	UUID účetní události
accounting_event_type	string	payment_receipt, refund, cashdesk_receipt, settlement, insurance_fee …
accounting_source	enum	reservation / standalone_purchase
service_id, currency	string	FK výkonu a měna
pohoda_export_status, pohoda_external_id, pohoda_export_error	—	Stav exportu do Pohody

CreditTransaction

Pohyby na kreditním účtu. Nově slouží zároveň jako typ účetní události a nese zálohové účetnictví.

Pole	Typ	Popis
client_id, booking_id	string	Vazby
type	enum	topup, payment, refund, adjustment, transfer_out, transfer_in
amount	number	Částka
related_client_id, related_client_name	string	Druhý klient u převodu kreditu
document_id	string	Doklad, pod kterým bylo vrácení provedeno
purchase_id	string	Samostatný nákup (dobití kreditu)
topup_confirmation_number	string	Číslo nedaňového potvrzení o přijetí platby
variable_symbol, transaction_reference	string	Párovací identifikátory
date_of_service	date	Datum přijetí zálohy (pro zálohové účetnictví v Pohodě)
accounting_source	enum	reservation / standalone_purchase
event_id, currency	string	UUID účetní události, měna
export_to_pohoda	boolean	Exportovat jako přijatou zálohu (true jen pro nová dobití)
pohoda_export_status, pohoda_external_id, pohoda_export_error	—	Stav exportu do Pohody

Voucher

Dárkový voucher na konkrétní službu, uplatnitelný přes QR/URL. Rozšířeno o prodej (kupující, cena, doklad).

Pole	Typ	Popis
code	string	Unikátní kód (pro QR / URL) — povinné
service_id	string	ID služby, na kterou je voucher určen — povinné
service_name	string	Snapshot názvu služby (zobrazení bez join)
status	enum	active, redeemed, expired, cancelled
valid_until	date	Platnost do (null = bez expirace)
buyer_client_id, buyer_client_name	string	Kupující (volitelné — voucher lze vystavit i bez kupce)
price, vat_rate	number	Prodejní cena a sazba DPH (snapshot dle služby)
payment_method	enum	demo, gateway, cash, card, credit, transfer, campaign (kampaň = bez dokladu, marketingový náklad)
internal_payment_id	string	Reference platby pro spárování
purchase_id, invoice_id, invoice_number	string	Vazba na prodejní doklad
purchase_date	date	Datum prodeje
export_to_pohoda	boolean	Exportovat prodej do Pohody
redeemed_by_client_id	string	Klient, který voucher uplatnil
redeemed_by_client_name	string	Jméno klienta (snapshot)
booking_id	string	Rezervace vzniklá uplatněním
redeemed_at	string	Čas uplatnění (ISO datetime)
note	string	Interní poznámka (komu darován apod.)

LegalDocument

Verzované právní dokumenty (VOP, GDPR) pro on-boarding.

Pole	Typ	Popis
key	string	Klíč dokumentu: vop, gdpr — povinné
title	string	Zobrazovaný název — povinné
content	string	Text (Markdown / prostý text) — povinné
version	string	Verze (např. 1.0, 2025-01) — povinné
effective_from	date	Platnost od
is_active	boolean	Aktivní verze

Podpůrné entity

Entita	Účel
ClientCredit	Kreditní účet klienta (zůstatek)
ClientPackage	Zakoupený balíček sezení klienta — nově i prodejní snapshot (price/vat_rate/vat_amount/total_amount, invoice_id, purchase_id, export_to_pohoda)
ServicePackage	Definice balíčků (10+1 terapií, cena, platnost); nově vat_rate, vat_exempt_reason, requires_first_visit (viditelný až po první realizované terapii) a allowed_client_category_ids
TherapistService	Vazba terapeut–služba: kdo službu nabízí, denní/týdenní limity, vlastní cena
ClientCategory	Barevné kategorie (skupiny) klientů; is_insurance = skupina pojišťovny
RoomCategory	Kategorie místností
ServiceCategory	Kategorie výkonů
AppointmentStatus	Konfigurovatelné stavy termínů
CalendarSettings	Provozní hodiny, granularita slotů
NotificationSettings	Šablony e-mailů a SMS (SmsManager: sms_enabled, sms_provider, sms_api_key); nové události: vratka/dobropis, storno poplatek pojišťovny, výzva k onboardingu, přeposlání video odkazu, přesun termínu
NotificationLog	Deduplication log odeslaných notifikací
ActivityLog	Auditní log všech akcí
OtpCode	Jednorázové kódy pro přihlášení klientů, terapeutů i personálu
SystemSettings	Globální nastavení: odesílatel, testovací režim, čítače (invoice_number_seed, client_number_seed), insurance_cancellation_fee, konfigurace Pohody (pohoda_export_enabled, pohoda_api_url, pohoda_auth_token, pohoda_test_mode, pohoda_new_rules_enabled) a telefonie (telephony_*, OptimCall)
PaymentSettings	Storno lhůty, splatnost, min. hodiny před termínem
DemoUser	Demo účty pro přepínání rolí: admin, admin-klientske, klientske, finance

Vztahy mezi entitami

Client ──────────────── Booking ─────── CalendarEvent
  │                        │                  │
  ├── ClientCredit         │              Therapist ── TherapistService ── Service
  │     └── CreditTransaction              Room                             │
  │                        │                                            Voucher
  ├── ClientPackage ── ServicePackage
  │
  ├── ClientCategory
  │
  └── LegalDocument (VOP/GDPR — souhlasy uložené na Client)

CalendarEvent ──── PaymentLog ──── Invoice ──── (export) ──── Pohoda
                       │              │
                   CreditTransaction ─┘

Účetní osa: PaymentLog, CreditTransaction a Invoice sdílejí event_id (UUID účetní události), purchase_id (samostatný nákup) a exportní pole pohoda_*. Doklad tedy lze dohledat od platby i od čerpání kreditu a export do Pohody je deduplikovaný přes event_id.

Poznámka: Base44 NoSQL databáze nevynucuje referenční integritu — vztahy jsou udržovány pouze na aplikační úrovni pomocí ID referencí.