Pojęcia

Czym w rzeczywistości są Sesja, wiersz materiału dowodowego i Łańcuch audytu, w możliwie najmniejszej liczbie słów. Wystarczy przeczytać to raz, a referencja API stanie się zrozumiała.

Organizacja

Tenant najwyższego poziomu. Jedna organizacja odpowiada jednemu kontu klienta. Każdy inny zasób (sesje, materiał dowodowy, zdarzenia audytu, użytkownicy) jest przypisany do organizacji poprzez bezpieczeństwo na poziomie wiersza w bazowych tabelach Postgres. Błąd w kodzie aplikacji nie może przekroczyć granicy tenanta — baza danych odrzuci zapytanie.

Organizacja posiada: członków (użytkowników z dostępem opartym na rolach), branding (logo / kolory / stopkę PDF), subskrypcję rozliczeniową, opcjonalne dane podmiotu prawnego KYB, opcjonalną konfigurację SSO oraz politykę retencji.

Członek, Rola, Uprawnienie

A Członkostwo to powiązanie między Użytkownikiem a Organizacją. Użytkownik może posiadać członkostwa w wielu organizacjach i przełączać się między nimi (aktywna organizacja jest przenoszona jako claim w JWT).

Każda organizacja przy tworzeniu inicjuje cztery role systemowe:

org_admin — pełna kontrola. Rozliczenia, członkowie, branding, retencja.
inspector — może prowadzić inspekcje, zbierać materiał dowodowy, podpisywać raporty.
observer — dostęp tylko do odczytu do sesji i danych audytu.
auditor — dostęp tylko do odczytu oraz uprawnienie do weryfikacji łańcucha.

Administratorzy organizacji mogą tworzyć role niestandardowe, komponując katalog uprawnień. Uprawnienia są sprawdzane po slugu na warstwie widoku i weryfikowane krzyżowo przez RLS na warstwie bazy danych.

Sesja

Jedna inspekcja. Jednostka rozliczeniowa (płatność za każdą zamkniętą sesję) oraz jednostka materiału dowodowego (łańcuch audytu jest tworzony per sesja, a nie per organizacja).

Sesja posiada: operatora (członka Państwa zespołu, który ją rozpoczął), jednego lub więcej uczestników (użytkownika terenowego oraz opcjonalnych obserwatorów), stan zgody, opcjonalną pozycję GPS, opcjonalne notatki, łańcuch audytu oraz — po zamknięciu — tokeny znaczników czasu zakotwiczone w TSA.

Uczestnik

Jedna osoba w sesji. Na sesję przypada jeden operator i co najmniej jeden użytkownik terenowy; obsługiwani są opcjonalni dodatkowi obserwatorzy. Użytkownicy terenowi dołączają za pośrednictwem jednorazowego podpisanego URL (bez konieczności posiadania konta); operatorzy i obserwatorzy są członkami organizacji.

Materiał dowodowy

Element zebranego dowodu podczas sesji. Rodzaje:

snapshot — zdjęcie z kamery użytkownika terenowego.
annotation — rysunek nałożony na zrzut lub tablicę.
whiteboard — płótno Excalidraw w sesji wyeksportowane jako PNG + stan.
clip — krótki fragment wideo.
document — przesłany plik (wykorzystywany przez warstwę czatu do podpisu PDF).

Każdy wiersz materiału dowodowego posiada SHA-256 swojej zawartości binarnej, przechowywany w łańcuchu audytu. Manipulacja plikiem po fakcie powoduje niepowodzenie weryfikacji.

Łańcuch audytu

Kryptograficzny kręgosłup. Każde zdarzenie w sesji — utworzenie sesji, udzielenie zgody, zapis GPS, zebranie materiału dowodowego, adnotacja, zapis tablicy, podpis, zakończenie sesji — emituje wiersz AuditEvent z:

{
  "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>"
}

Pierwsze zdarzenie używa prev_hash = "0" * 64 (genesis). Każde kolejne zdarzenie używa hasha poprzedniego zdarzenia jako prev_hash i inkrementuje sequence o 1. Blokada advisory Postgres serializuje zapisy per sesja; trigger append-only blokuje UPDATE i DELETE na tabeli.

TimestampToken (kotwica TSA)

Na koniec sesji (oraz przy wyzwolonym przez operatora „stamp now”) bieżąca głowica łańcucha jest przesyłana do trzech niezależnych urzędów znaczników czasu:

YodaLedger — kotwica na blockchainie Tezos. Finalizacja ~15-20 minut. Asynchroniczna; otrzymujemy callback po potwierdzeniu bloku.
FreeTSA — znacznik czasu RFC 3161. Synchroniczny; token zwracany natychmiast. Wymienny na płatny QTSP (DataSure) w celu zgodności z eIDAS Art. 42.
OpenTimestamps — kotwica na Bitcoinie za pośrednictwem protokołu kalendarza OpenTimestamps. Asynchroniczna; ścieżka aktualizacji działa na przemiataniu Celery.

Trzy urzędy to celowy zabieg — jeśli którykolwiek z TSA zniknie, pozostałe dwa wciąż zakotwiczają łańcuch. Audytor może zweryfikować względem dowolnego z nich niezależnie, korzystając z publicznych eksploratorów bloków / endpointów weryfikacyjnych.

Podpis (SES / AES / QES)

Trzy poziomy eIDAS, wszystkie na tym samym PDF-ie raportu audytowego:

SES (Simple Electronic Signature) — oparty na łańcuchu audytu, bez certyfikatu podpisu. Odpowiedni do rejestrów wewnętrznych.
AES (Advanced Electronic Signature) — certyfikat podpisu powiązany z tożsamością, zakotwiczony PAdES B-T. Odpowiedni do większości umów B2B.
QES (Qualified Electronic Signature) — najwyższy poziom eIDAS, prawny odpowiednik podpisu odręcznego w całej UE. Uwarunkowany weryfikacją KYB organizacji wystawiającej.

Kampania (opcjonalnie)

Logiczne grupowanie sesji do raportowania wsadowego — „szkody motoryzacyjne Q2 2026” lub „wady przy odbiorze obiektu A”. Sesje nie wymagają kampanii; jest to udogodnienie raportowe.

Webhook

Zarejestrowany przez klienta URL, który otrzymuje POST-y zdarzeń podpisane HMAC. Typy zdarzeń: session.created, session.completed, participant.joined, participant.left, evidence.added, recording.ready, audit.anchored, signature.completed, oraz webhook.test do weryfikacji dostarczenia.

Podpis: nagłówek w stylu Stripe t=...,v1=... z HMAC-SHA256 nad <timestamp>.<body>. Helper SDK constructEvent() weryfikuje w stałym czasie z 5-minutową tolerancją odchylenia zegara.