Rozpracováno

Čtecí API

API neservíruje rejstřík, ale to, co se z něj odvodilo: projekci a vyhledávací index nad ní. Pro konzumenty je jen ke čtení — zapisuje se jen rozhodnutí ve frontě kontroly a komentář k aplikaci. Pilotní čtecí API pod /api/ existuje; verzovaný kontrakt /v1 zatím ne.

Položka fáze

1.11 čtecí API pro řízení, pohledávky a věřitele — rozpracováno

Závisí na

1.5 — projekci, kterou API servíruje (rozpracováno)

Existuje dnes

/api/explore/search, export.csv, dashboard, pivot a claim/{id} nad indexem pohledávek; /api/news (nová řízení a pohledávky v období); /api/review (fronta kontroly); /api/feedback (komentáře)

Zdrojový dokument

/api/explore/claim-source/{id} vrátí PDF, ze kterého byla citace přečtena, jen u věřitele-právnické osoby a jen se zapnutým EXPLORE_CLAIM_SOURCE_ENABLED; výchozí stav je vypnuto

Přístup

jen pojmenovaný uživatel s rolí reader (HTTP Basic, nebo Keycloak tam, kde ho nasazení zapne)

Zápisy

rozhodnutí ve frontě kontroly (/api/review, role reviewer a approver) a komentář k aplikaci (/api/feedback), který se dat pohledávek nedotkne

Neexistuje

/v1/proceedings, /v1/claims, /v1/creditors ani ostatní navržené endpointy pod /v1

Stav

rozpracováno; stupeň rolloutu dnes řídí jen poller, čtecí endpointy hlídá přihlášení

Provenience v odpovědi, ne v poznámce pod čarou

Pohledávka se v odpovědi vrací spolu s odkazem na dokument, stranou, citací a skóre spolehlivosti, ze kterých pochází. Odpověď, která proveniencí ušetří, není zjednodušení téhož produktu — je to jiný produkt.

Verzované endpointy pod /v1 zatím neexistují. Dnešní /api/explore sdílí jeden kanonický dotaz pro vyhledávání, export, přehled i kontingenční tabulku, takže tatáž adresa znamená všude tytéž pohledávky; chyby vrací v obálce problem+json se stabilním typem a neplatný filtr je 422 se seznamem všech chybných parametrů.

%% title: Jak API čte a kudy se zapisuje
%% caption: Dnešní cesty pod /api, jen pro přihlášené. Čtení jde přes /api/explore z indexu pohledávek, který se staví z projekce, a každá pohledávka v odpovědi nese dokument, stránku a confidence. Do dat o pohledávkách se zapisuje jen rozhodnutí kontrolora přes /api/review: uloží se do append-only logu rozhodnutí a projekce ho přehraje při další přestavbě. Verzované endpointy /v1 zatím neexistují.
sequenceDiagram
  participant K as Klient
  participant A as API /api
  participant I as Index pohledávek
  participant P as Projekce
  participant Q as Fronta kontroly
  participant L as Log rozhodnutí
  K->>A: GET /api/explore/search
  A->>I: dotaz
  I-->>A: pohledávky + dokument, stránka, confidence
  A-->>K: odpověď s proveniencí
  K->>A: POST /api/review/… rozhodnutí
  A->>Q: rozhodnutí
  Q->>L: typovaná událost (kdo, kdy, co)
  L-->>P: přehrání při přestavbě projekce
  P-->>I: přestavba indexu

Otevírá se až na konci, ne na začátku

Rollout má stupně: příjem dat, projekce, teprve pak zveřejnění. Poller běží od stupně ingest výš. Navržené API /v1 má servírovat až ve stupni expose, po ověření konzistence; dnešní pilotní /api/explore na stupeň rolloutu nehledí — přístup k němu omezuje přihlášení s rolí reader.

Důvod je prostý: chyba v projekci se má najít v době, kdy projekci ještě nikdo nečte.

Co API nebude dělat

Nebude cestou k republikaci dat. Přístup je autentizovaný a omezený rolí: bajty dokumentů dostane kontrolor přes /api/review/documents, čtenář jen přes zapnutý claim-source a jen u věřitele-právnické osoby.

Nebude ani zapisovacím rozhraním do projekce. Zapisuje rejstřík; systém ho čte.

Kde to v repozitáři žije

• src/progresus_isir/api/routers/explore.py — vyhledávání, export CSV, přehled a kontingenční tabulka
• src/progresus_isir/api/routers/claim_detail.py — detail pohledávky a zdrojová stránka za přepínačem
• src/progresus_isir/api/routers/news.py — nová řízení a pohledávky v období
• docs/API.md — co existuje, navržený kontrakt /v1, chybová obálka a autentizace
• docs/runbooks/feed-rollout.md — stupně rolloutu a podmínky pro zveřejnění

Souvisí

Zpět na sekci Roadmapa