Koncepty

Čím ve skutečnosti jsou Relace, řádek Důkazu a Auditní řetězec, v co nejméně slovech. Přečtěte si to jednou a referenční příručka API vám bude dávat smysl.

Organizace

Nejvyšší tenant. Jedna org odpovídá jednomu zákaznickému účtu. Každý další zdroj (relace, důkazy, auditní události, uživatelé) je vázán na Org přes zabezpečení na úrovni řádku v podkladových Postgres tabulkách. Chyba v aplikačním kódu nemůže překročit hranice tenanta — databáze dotaz odmítne.

Org má: členy (uživatele s přístupem podle rolí), branding (logo / barvy / patička PDF), fakturační předplatné, volitelná KYB data právnické osoby, volitelnou konfiguraci SSO a retenční politiku.

Člen, Role, Oprávnění

Členství je propojení mezi Uživatelem a Org. Uživatel může mít členství ve více org a přepínat mezi nimi (aktivní org se veze jako JWT claim).

Každá Org při vytvoření nasadí čtyři systémové role:

• org_admin — plná kontrola. Fakturace, členové, branding, retence.
• inspector — může provádět inspekce, zachytávat důkazy, podepisovat protokoly.
• observer — přístup pouze pro čtení k relacím + auditním datům.
• auditor — přístup pouze pro čtení plus oprávnění ověřit řetězec.

Administrátoři Org mohou vytvářet vlastní role skládáním z katalogu oprávnění. Oprávnění jsou kontrolována podle slugu ve view vrstvě + křížově ověřena přes RLS v DB vrstvě.

Relace

Jedna inspekce. Jednotka fakturace (platíte za uzavřenou relaci) a jednotka důkazu (auditní řetězec je na relaci, ne na org).

Relace má: operátora (člena vašeho týmu, který ji zahájil), jednoho nebo více účastníků (uživatele v terénu plus volitelné pozorovatele), stav souhlasu, volitelnou GPS pozici, volitelné poznámky, auditní řetězec a — po uzavření — časová razítka ukotvená u TSA.

Účastník

Jedna osoba v relaci. Na relaci je jeden operátor a alespoň jeden uživatel v terénu; volitelní další pozorovatelé jsou podporováni. Uživatelé v terénu se připojují přes jednorázovou podepsanou URL (bez nutnosti účtu); operátoři + pozorovatelé jsou členové Org.

Důkazy

Kus zachyceného důkazu během relace. Druhy:

• snapshot — statická fotografie z kamery uživatele v terénu.
• annotation — kresba překrytá přes snímek nebo tabuli.
• whiteboard — Excalidraw plátno v relaci exportované jako PNG + stav.
• clip — krátký videosegment.
• document — nahraný soubor (používaný chat vrstvou pro PDF k podpisu).

Každý řádek Důkazu má SHA-256 svého binárního obsahu, uložený v auditním řetězci. Manipulace se souborem dodatečně selže při ověření.

Auditní řetězec

Kryptografická páteř. Každá událost v relaci — vytvoření relace, udělení souhlasu, záznam GPS, zachycení důkazu, anotace, uložení tabule, podpis, ukončení relace — emituje řádek AuditEvent s:

{
  "session": "<uuid>",
  "sequence": N,
  "occurred_at": "<iso8601>",
  "kind": "evidence.snapshot_added",
  "actor": { "user": <id|null>, "participant": <id|null> },
  "payload": { /* event-specific */ },
  "prev_hash": "<sha256 of previous event>",
  "hash": "<sha256 of canonical_json of this event>"
}

První událost používá prev_hash = "0" * 64 (genesis). Každá následující událost používá hash předchozí události jako prev_hash a inkrementuje sequence o 1. Postgres advisory lock serializuje zápisy na relaci; append-only trigger blokuje UPDATE + DELETE na tabulce.

TimestampToken (ukotvení TSA)

Na konci relace (a při operátorem spuštěném „stamp now“) je aktuální hlava řetězce odeslána třem nezávislým časovým autoritám:

• YodaLedger — Ukotvení do blockchainu Tezos. Finalita ~15–20 minut. Asynchronní; při potvrzení bloku dostaneme callback.
• FreeTSA — Časové razítko RFC 3161. Synchronní; token vrácen okamžitě. Zaměnitelné za placený QTSP (DataSure) pro soulad s eIDAS Art. 42.
• OpenTimestamps — Ukotvení do Bitcoinu přes kalendářní protokol OpenTimestamps. Asynchronní; upgrade cesta běží na Celery sweepu.

Tři jsou záměrem — pokud jakákoli jedna TSA zmizí, zbylé dvě řetězec stále ukotvují. Auditor může ověřit proti kterékoli z nich nezávisle pomocí veřejných block explorerů / ověřovacích endpointů.

Podpis (SES / AES / QES)

Tři úrovně eIDAS, všechny na stejném PDF auditního protokolu:

• SES (Simple Electronic Signature) — podpořené auditním řetězcem, bez podpisového certifikátu. Vhodné pro interní záznamy.
• AES (Advanced Electronic Signature) — podpisový certifikát vázaný na identitu, ukotvený PAdES B-T. Vhodné pro většinu B2B smluv.
• QES (Qualified Electronic Signature) — nejvyšší úroveň eIDAS, právní ekvivalent vlastnoručního podpisu napříč EU. Odemyká se po ověření KYB vydávající organizace.

Kampaň (volitelné)

Logické seskupení relací pro dávkové reportování — „Q2 2026 pojistné události vozidel“ nebo „Vady předání lokality A“. Relace kampaň nevyžadují; je to pouze pomůcka pro reportování.

Webhook

Zákazníkem zaregistrovaná URL, která přijímá HMAC-podepsané POSTy událostí. Typy událostí: session.created, session.completed, participant.joined, participant.left, evidence.added, recording.ready, audit.anchored, signature.completed, plus webhook.test pro ověření doručení.

Podpis: hlavička ve stylu Stripe t=...,v1=... s HMAC-SHA256 nad <timestamp>.<body>. Pomocník constructEvent() z SDK ověřuje v konstantním čase s 5minutovou tolerancí odchylky hodin.