Dokument popisuje základní pravidla architektury Sdíleného informačního systému TA ČR (dále jen SISTA). Dozvíte se z něj, jakým způsobem vaši službu či komponentu navrhnout, aby byla v souladu s architekturou SISTA a aby mohla být bez problémů integrována do celého systému. Ve většině případů nezabíhá dokument do implementačních detailů, ty jsou popsány v samostatných dokumentech věnovaných pravidlům vývoje, pravidlům platformy či pravidlům dokumentace.
1. Úvod
Záměrem TA ČR je vybudovat a provozovat SISTA jako cloud native systém. Takový systém má být odolný, snadno kontrolovatelný, robustní a nezávislý na konkrétních dodavatelích technologií. Obecná pravidla pro vývoj takového systému shrnuje manifest 12factor.
V průběhu řešení projektu „Sdílený informační systém TA ČR“ očekáváme spolupráci architektů dodavatelů (DEV) s OPS týmem při konzultacích/úpravách týkající se právě stavby SISTA.
1.1. Okolnosti SISTA
Obrázek níže ukazuje základní pohled na celkový rámec SISTA. Zainteresované strany představují jednotlivé skupiny uživatelů, Sdílený informační Systém TA ČR je samotný systém, IS v perimetru SISTA jsou okolní systémy, s nimiž SISTA interaguje (interní TA ČR i externí), Dodavatelé projektu SISTA jsou subjekty spolupracující na vzniku SISTA a Definice procesů, pravidel a komponent projektu SISTA představuje soubor principů a nástrojů, jimiž se vývoj SISTA řídí.
1.2. Architektonické pravidlo "nula"
Komunikujte. Součástí ekosystému SISTA jsou chaty a schůzky, a to jak pro řešení provozních problémů, tak i pro konzultace a společné řešení architektonických otázek. Nejen těch s "globálním SISTA přesahem", ale i konkrétních problémů na konkrétních minitenderech.
Pokud máte pochybnosti, obraťte se na garanta vašeho minitendru a ten zjistí, kam vás nasměrovat.
2. Přehled architektury
Mikroservisy – architektonický styl [1], který strukturuje aplikaci na kolekci služeb tak, že jsou:
-
Snadno udržovatelné a testovatelné,
-
navzájem v maximální míře nezávislé,
-
nezávisle nasaditelné,
-
organizované podle business funkčností,
-
každá z nich v péči jednoho týmu.
Z nejrůznějších důvodů (např. organizace projektu v kontextu státních zakázek) se na SISTA nepodaří plně aplikovat všechny principy mikroservisní architektury. Cílová architektura SISTA tedy konverguje k architektuře mikroslužeb, ale nevynucuje fragmentaci; služby SISTA jsou komponovány jako „mikrolity“ a zodpovídají za celou funkční oblast (podání přihlášky, správa expertů, …) nikoliv za dílčí funkci.
Služba nemusí (ale může) být rozdělena na skupinu mikroslužeb. Volba architektury je na dodavateli.
Pro služby SISTA se vžilo označení TRS, což původně znamenalo "služba TŘetí Strany", ale naznačuje to fakt, že typický SISTA TRS je shlukem více služeb.
2.1. Shrnutí
V podstatě všechny služby SISTA jsou webové aplikace a tedy jsou rozděleny na backend a frontend část. Backend bude vaše běžná Node Express, Java Spring Boot či Kotlin Micronaut aplikace, a frontend bude React aplikace servírovaná pomocí Nginx, která s backendem komunikuje přes REST API.
@startuml Architektura left to right direction actor User as "Uživatel" User --> [Frontend] Frontend --> [Backend]: AJAX / Fetch (JSON) database "Postgres" as Postgres database "Redis" as Redis Backend <--> Postgres : SQL Dotazy Backend <--> Redis : Čtení / Zápis Cache @enduml
Je snaha, aby byly jednotlivé TRSy maximálně izolované a nezávislé. TRS obvykle zajišťuje nějaký výřez z širší oblasti business logiky a omezuje komunikaci především na tzv. „průřezové služby“. To jsou univerzální služby, zajišťující znovupoužitelné funkce (notifikace, řízení úkolů, …), ale nevyhneme se ani komunikaci mezi „business službami“, tedy službami, které zajišťují specifickou agendu TA ČR.
@startuml BackendKomunikace left to right direction [Backend] <--> [TRS A]: REST [Backend] --> [TRS A]: Messaging [Backend] <--> [TRS B]: REST [Backend] --> [TRS B]: Messaging [Backend] <--> [TRS C]: REST [Backend] --> [TRS D]: Messaging [Jiný TRS] --> [Backend]: REST [TRS A] --> [TRS C]: Messaging @enduml
Používáme dva způsoby komunikace mezi službami:
-
Synchronous REST API volání - pro požadavky, které vyžadují okamžitou odpověď (např. dotaz na data) - tedy obvykle čtení
-
Asynchronous Messaging - pro požadavky, které nevyžadují okamžitou odpověď (např. notifikace, spuštění workflow, …) - tedy obvykle zápis
Oba komunikační kanály zajišťuje framework Dapr.
Služba pro správu expertů zajišťuje proces registrace zájemce, tvorbu jeho profilu, jeho schválení, uzavření smlouvy, interní hodnocení kvality práce experta apod. Tato služba má svůj backend (Kotlin Micronaut) a frontend (React), komunikuje s několika průřezovými službami (notifikace, rejstřík, workflow, …).
Mimo jiné služba vystavuje API pro objednání činnosti experta, které mohou provolat jiné služby SISTA (například požadavek na vyhodnocení, zda je "podnik v obtížích"). Samotný proces přidělení experta je relativně komplikovaný, zahrnuje výběr, oslovení, zasmluvnění, formální objednávku, proplácení odměny apod. To všechno je ale TRSům skryto a z jejich pohledu poskytuje služba jednoduché API "Dej mi vhodného experta".
2.2. Platforma SISTA
V úvodu do achitektury nelze opomenout Platformu SISTA, která zajištuje nezbytné zázemí pro provoz TRSů a poskytuje jim potřebné nástroje (Postgres, Redis, Dapr, Kubernetes, …). Kromě toho sem patří Gitlab (CI/CD), katalog služeb (Backstage) a další podpůrné nástroje.
3. Klíčové koncepty
V této kapitole podrobněji zmapujeme některé okolnosti, které je třeba mít na paměti při návrhu a vývoji služeb SISTA.
3.1. Backend
Váš backend bude služba dodaná formou zaslání zdrojových kódů do Gitlab repozitáře TA ČR, kde se pomocí CI/CD pipeline sestaví a následně nasadí do prostředí platformy SISTA. Zjednodušeně lze říci, že úlohou dodavatele je:
-
dodat zdrojové kódy
-
dodat Dockerfile s exponovaným komunikačním portem
-
dodat deployment descriptor pro Platformu (tj. jak má být služba nasazena a provozována, zda potřebuje Redis, Postgres, …)
Podrobnější informace najdete v dokumentu Pravidla vývoje, ale zde zmíníme alespoň klíčový požadavek: vaše služba musí být schopna běžet paralelně ve více replikách (instancích) (nebo, skutečně není jiná možnost, deklarovat v deployment descriptoru, že to neumí).
3.2. Frontend
Pro tvorbu uživatelského rozhraní se používá architektura minifrontendů, tedy menších, samostatných SPA aplikací, které jsou na sobě navzájem nezávislé a zajišťují UI pro svoji "mateřskou" službu. Detailnější pokyny opět naleznete v dokumentu Pravidla vývoje, ale zde je několik klíčových bodů:
-
služba musí být postavena v TypeScriptu a Reactu
-
služba musí využívat komponenty a styly z knihovny Dista, Dista Storybook
-
rámec UI musí být postaven s využitím nástrojů knihovny FE Commons
3.2.1. Federované komponenty
Někdy je potřeba, aby služba kromě svého REST API poskytnula ostatním TRSům i vizuální UI komponenty, které zajistí nějaký komplexní use-case na frontendu. Typickým příkladem je třeba formulářová služba, která kromě backendu pro validaci a obecně zpracování formulářových dat poskytuje i komponentu pro vykreslení formuláře.
Takové komponenty se nazývají federované komponenty (viz webpack module federation) a v principu se jedná o:
-
package s potřebnými TS typy, která je uveřejněna v interním SISTA NPM registru
-
React komponenty, které jsou sestaveny odděleně od vašeho hlavního UI a jsou vystavené ke stažení pomocí uvedené package
Klientská aplikace je pak využívá jako běžné React komponenty, které jsou ale načítány až „za běhu“ z vaší služby v prohlížeči.
complaints3.3. Platforma
Platforma zajišťuje technické řešení poskytující běh služeb. Stará se o repozitáře, pipelines, deployment, správu prostředí, infrastrukturu, IAM management, zabezpečení komunikačních kanálů mezi službami, jejich vzájemnou viditelnost, monitoring atd. Pro platformu opět existuje podrobnější popis, ale uveďme alespoň:
-
Platforma funguje „as a service“ pro vývojové týmy dodavatelů.
-
Její údržbu a rozvoj zajišťuje Ops tým TA ČR.
-
Dodavatelé mohou přispívat do platformy, jak nápady, tak i přímo kódem.
-
Platforma by měla zajistit, že není výrazně složitější vytvořit novou službu než začlenit nový kód do služby již existující. Je třeba zajistit, aby zvolené řešení nebylo řízené pouze náročností úpravy ale bylo i správné z hlediska architektury.
-
Jednotlivé Docker kontejnery běží na bázi Linux s tím, že jejich orchestraci zajišťuje Kubernetes provozovaný v Google Cloud Platform.
-
Vývoj všech služeb včetně dokumentace probíhá v git repozitářích TA ČR na Gitlabu.
-
Jednotlivé služby by měly v maximální míře obsahovat pouze business logiku.
-
Ops tým může být v procesech a postupech DevOps označován jako „platformní tým“. Tento tým je možné kontaktovat na adrese [email protected].
3.4. Hlavní entity SISTA
Nevyhnutelně přijdete do styku s několika důležitými entitami, které sice zajišťují existující TRSy, ale bude je využívat i váš datový model:
- Osoba (person)
-
Fyzická osoba (obvykle je uživatelem SISTA), která může mít jeden či více profilů. Služba:
rejstrik. - Profil
-
Profil je pohled na osobu v nějaké konkrétní roli. Například "řešitel", "expert", "zaměstnanec poskytovatele". Osoba může mít více profilů současně a ke každému typu profilu se pak vztahuje zásadně jiná agenda. Vaše služba bude vždy pracovat s uživatelským profilem, nikoliv s osobou jako takovou. Služba:
idmarejstrik.
- Projekt
-
Projekt je smyslem existence TA ČR. Obvykle je to výzkumný záměr, na jehož realizaci TA ČR poskytuje finanční prostředky a dohlíží na jeho řádné plnění. Základní záznam o projektu je uložen ve službě
project-skeleton, datová věta projektu je rozdělen do více entit (jak vypadal ve fázi podání přihlášky, jak v okamžiku podpisu smlouvy, …) a tyto detailní entity jsou uloženy ve služběrejstrik - Poskytovatel (provider)
-
Poskytovatel je organizace, která zajišťuje financování a řízení projektů, obvykle je to TA ČR, ale v budoucnu mohou být i jiní poskytovatelé. Služba:
rejstrik. - Program
-
Program je strukturovaná kategorie projektů, kterou definuje poskytovatel. Programy mohou mít své podprogramy a v rámci programů se vyhlašují soutěže. Služba:
programs. - Soutěž (výzva, call-for-proposal)
-
Soutěž je konkrétní výzva k podání projektových návrhů v rámci určitého programu. Záznam o soutěži obsahuje množství metadat a parametrů, které bývá potřeba zohlednit. Služba:
call-for-proposal. - Rezort (department)
-
Programy a soutěže jsou vždy vyhlašovány v rámci určitého rezortu (ministerstva či jiné státní instituce). Správa projektů je služba, kterou poskytovatel rezortů poskytuje. Služba:
rejstrik. - Organizace
-
Organizací se myslí právnická osoba, která může být žadatelem o projekt, účastníkem projektu, dodavatelem služeb apod. Služba:
rejstrik.
3.5. SISTA URN
Komunikace mezi jednotlivými službami SISTA vyžaduje jednoznačnou identifikaci datových objektů (entit). K tomu účelu se definuje identifikátor SISTA dle standardu Uniform Resource Name (viz [URN]) podle následujících pravidel:
-
identifikátor sestává ze 3 řetězců dle schématu:
"urn" ":" NID ":" NSS, části odděluje znak dvojtečka (:), -
1. část představuje pevný řetězec
urn, -
2. část
NIDspojuje pevný řetězecsista:a identifikátor typu objektu, -
3. část
NSSje jednoznačný identifikátor objektu daného typu.
NID typicky představuje buď definovaný typ objektu (sista:profiles) nebo namespace dané služby (sista:need). Jeho přidělení je stanoveno dohodou vývojových týmů jednotlivých služeb. Aktuální identifikátory jsou uvedeny v konfiguračním souboru resolvers.yml služby URN resolver.
Přidělení NSS je plně v kompetenci primárního zdroje, je pouze nutné dodržet povolené znaky dle standardu [URN] (pro případnou podkategorizaci se doporučuje použití oddělovače :). Pro definici NSS preferujeme název (objektu, služby) v množném čísle.
Příklady identifikátoru SISTA:
-
urn:sista:profiles:d4RFsag21, -
urn:sista:services:rejstrik -
urn:sista:departments:d:mzp, -
urn:sista:projects:123, -
urn:sista:need:D3990620-CD2F-4A14-8E8B-DE98B40C42D7, -
urn:sista:files:rdy9RMGbj65D0lBv7NgoKOgPKOkJZ31X2Qe8xaoA/4826939563156/a6dd3748d92ebd67314c702349cdd0ae/pokusXX.pdf.
Konzumenti identifikátoru SISTA by s měli s částí NSS pracovat pouze jako s identifikačním řetězcem a neměli by ji parsovat, validovat, tokenizovat atd. Primární zdroj smí do části NSS ukládat dodatečné informace (typ projektu, typ profilu), ale na klientské straně se nepředpokládá jejich zpracovávání.
Pokud je potřeba Sista URN zobrazit na UI, slouží k tomu komponenta <SistaChip …/>, která pomocí služby urn-resolver zjistí název, popis, odkaz na detail apod.
Při práci s cizími URN je víc než vhodné pečlivě zkontrolovat překlepy, např. urn:sista:provider:tacr vs. urn:sista:providers:tacr. Lze využít např. konfiguraci urn-resolveru.
3.5.1. Příklad využití SISTA URN
Například služba vazbátor využívá jednoznačná URN pro evidenci vztahů (vazeb) mezi entitami. Profil patří osobě, profil je zaměstanec poskytovatele, … vazbátor je ale připraven pojmout i vztahy entit, které zatím neexistují.
Vždy, když je zapotřebí poskytnout obecnou funkcionalitu, která se může vztahovat k libovolné SISTA entitě, je SISTA URN vhodnou volbou.
3.6. SISTA kontext
Při vyjádření širšího kontextu vašich entity využívejte koncept „SISTA kontext“, což je pole (list, array) více SISTA URN. Tímto způsobem deklarujete, k čemu všemu se vaše entita vztahuje. Kontext skoro vždy obsahuje poskytovatele (urn:sista:provider:tacr), obvykle také URN resortu (urn:sista:department) a případně projektu. SISTA kontext je např. nutný pro spuštění workflow, zadání úkolu, tisk šablony apod. a mimo jiné z něj vyplývají oprávnění uživatele (viz níže).
|
Pro uložení a následné hledání pokud možno využijte aktuální možnosti PostgreSQL (gin index). |
3.6.1. Jak služby využívají SISTA kontext
Mechanismus "SISTA kontext" je využíván především v průřezových službách, které jsou často velmi obecné a musí umět pracovat i s entitami, které v době jejich vzniku neexistovaly. Například služba na správu úkolů u každého úkolu eviduje jeho SISTA kontext, což umožňuje úkoly snadno filtrovat na uživatelském rozhraní: dej mi všechny úkoly, které se vztahují k tomu projektu / profilu / rezortu …
3.7. Workflow a úkoly
Procesy SISTA jsou řízeny službou workflow. V podstatě je to obecný stavový stroj, který umí řídit průběh procesu na základě definovaných stavů a přechodů mezi nimi. Definice procesů se vytváří pomocí XML dokumentu administračním rozhraní služby. Stavy (uzly) jsou různého druhu: úkol pro uživatele, čekání na událost, automatické rozhodnutí, rozdělení procesu, …
Každý uzel nebo přechod mezi uzly lze skriptovat pomocí jazyka Groovy a služba poskytuje řadu vestavěných funkcí (volání API jiných TRSů, zjišťování rolí, vazeb, dat, zasílání notifikací, …), které skriptování usnadňují.
Definice workflow si může vynutit, že se při spuštění procesu musí předat nějaký SISTA kontext (viz výše - projekt, profil, poskytovatel, …). Tím je zajištěno, že mají workflow skripty potřebné informace pro rozhodování - jedná se o projekt v rezortu X, jeho rozpočet přesahuje Y, je po termínu pro podání stížnosti, apod.
Velmi časté je, že workflow vytváří úkoly pro uživatele SISTA. Úkoly jsou spravovány službou sprava-ukolu. Každý úkol obsahuje stejný SISTA kontext jako workflow, které ho vytvořilo, plus URN procesu a definice, ke kterým patří. Úkol také obsahuje "UI URL" (nebo někdy task URL), což je adresa stránky v SISTA, kde může uživatel úkol vyřídit.
Pro zobrazení úkolů a stavu procesu slouží sada federovaných komponent.
Optimální průběh tedy je:
-
vznikne nová entita, kterou je potřeba zpracovat (např. stížnost)
-
spustí se workflow proces pro zpracování této entity, přičemž se mu předá SISTA kontext (profil stěžovatele, projekt, poskytovatel, …)
-
workflow vytvoří úkol pro příslušného uživatele (např. prověření stížnosti)
-
uživatel vybírá možné řešení úkolu (např. vrátit k doplnění)
-
workflow vytváří další úkol, tentokrát pro uchazeče (doplň dle pokynů)
-
atd.
Služba workflow také umožňuje, aby existovaly různé varianty definice procesu, což se obvykle uplatní při řešení odchylek pro jednotlivé soutěže či rezorty. V nadhledu se stále jedná o stejný proces, ale detaily jeho průběhu se mohou lišit.
Více viz: workflow a workflow-ui
3.7.1. Podprocesy
Jednou z užitečných vlastností workflow je možnost spouštět podprocesy. To znamená, že v rámci jednoho procesu můžete spustit další proces, počkat na jeho dokončení a získat výsledek. Tímto způsobem lze vytvářet složité procesy z jednodušších stavebních bloků ("atomických workflow"). Je vhodné takto procesy strukturovat, už z toho důvodu, že varianty procesu pro jednotlivé rezorty či soutěže se mohou realizovat jen v izolovaných podprocesech a hlavní linie procesu zůstane stejná.
3.7.2. Superflows
Existují tři významné workflow procesy, které byste měli do vašich architektonických úvah zahrnout. Jsou to:
-
sf.program - řízení životního cyklu programu
-
sf.cfp - řízení životního cyklu soutěže
-
sf.project - řízení životního cyklu projektu
Smyslem těchto "superflows" je ještě více izolovat jednotlivé business služby od sebe navzájem. Pokud má po službě A následovat služba B (po "jednání" přichází "smlouvy"), je nevhodné aby služba A spouštěla službu B a stejně tak je nevhodné, aby služba B pozorovala dění ve službě A a spustila se sama. Tuto "orchestraci procesů" zajištují právě superflows. Je to superflow kdo ve vhodnout chvíli spustí "hlavní workflow" vaší služby, nebo pošle Dapr zprávu, která vaši službu probudí.
Superflow projektu ještě úzce spolupracuje se službou project-skeleton a zajišťuje jednak změny stavu projektů, jednak poslouchá změny vyvolané jinými službami a reaguje na ně.
3.8. Rule engine
Aby bylo možné přidat variantu procesu bez nutnosti zasahovat do služby ke které se vztahuje (např. dlouho po odevzdání služby na stížnosti se zjistí, že ministerstvo vnitra požaduje jiný proces), nesmí o variantě workflow rozhodovat business služba (stížnosti), ale rozhodnuté provádí další průřezová služba - tzv. rule engine. Jedná se o velice jednouchý rozhodovací stroj, který na základě zaslaného SISTA kontextu rozhodne (opět pomocí Groovy skriptu), co má být výsledkem rozhodnutí.
Výsledek rozhodnuté je vždy buď string, nebo pole stringů. Interpretace této hodnoty je pak na volající službě, například tedy takto:
-
startuje se proces workflow (např. "expert_order") s kontextem: Ministerstvo vnitra, program XYZ, soutěž 123, projekt 1245678
-
workflow tento kontext předá do rule enginu a spustí rulebook: workflow:expert_order
-
rule engine vyhodnotí pravidla a vrátí string "mv"
-
workflow tento string interpretuje jako variantu procesu a spustí příslušnou definici procesu: "expert_order, varianta mv"
Rule engine mimo jiné rozhoduje a správné variantě tiskové šablony, správně variantě formuláře apod.
Více viz rule-engine
3.9. Formuláře
Formuláře jsou pochopitelně to hlavní co budete na frontendu tvořit. Je potřeba rozlišit dva druhy formuláře:
-
pevný, technický formulář (přihlášení, registrace, vyplnění nějakého pevně strukturovaného a neměnného záznamu, administrační rozhraní, konfigurační rozhraní, …)
-
tvárný, úřední, business formulář (přihláška projektu, stížnost, …)
"Pevné" a "technické" formuláře vytvoříte běžným způsobem v Reactu; s využitím komponent z Dista knihovny a dalších běžných nástrojů.
Pro "business" formuláře využijete službu forms, ve které pomocí JSON dokumentu nadefinujete strukturu formuláře, validační pravidla, transformační funkce, závislosti mezi poli atd. Služba forms pak poskytuje API pro založení instance formuláře, jeho vyplnění a odevzdání. Formulářová služba také poskytuje federovanou React komponentu, která umí formulář vykreslit na základě jeho definice a zajistí jeho vyplnění.
Obslužné scripty se píší v JavaScriptu a můžou být oddělené v npm repository, což umožňuje jejich opětovné využití mezi různými formuláři. Typický průběh je:
-
TRS založí instanci formuláře z připravené definice
-
do svého UI vloží odpovídající federovanou komponentu s identifikací instance
-
formulářová služba zajistí vyplnění a validaci
-
po odevzdání informuje TRS o hotovém formuláři
-
TRS si stáhne vyplněná data formulářové služby
Jednodušší formuláře (doplňte datum, …) lze deklarativně vložit přímo do definice workflow a související agendu včetně zobrazení zajistí workflow. Tento postup se ovšem z UX důvodů nehodí pro větší či déletrvající formuláře, ty by měly mít vlastní obrazovku, ke které je možné se dostat i mimo úkoly workflow (byť jen pro čtení, pokud není entita ve vhodném stavu).
Více viz: definice a komponenty
3.10. Identita uživatele
Váš TRS bude potřebovat vědět, kdo volá jeho API endpointy. Existují dva možné scénáře.
- Volá vás jiný TRS
-
V takovém případě najdete v HTTP hlavičce příchozí komunikace hlavičku
dapr-api-tokena její hodnota se musí shodovat s hodnotou proměnné prostředíDAPR_APP_API_TOKEN, se kterou byl váš TRS spuštěn (viz: Pravidla platformy resp. HOWTO platform). TRSy si navzájem důvěřují, v tomto případě není třeba ověřovat žádná oprávnění, akci lze provést (pokud dává smysl v rámci business logiky vašeho TRSu). - Volá vás uživatel SISTA
-
V takovém případě najdete v HTTP hlavičce příchozí komunikace hlavičku
authorizations hodnotou ve formátuBearer IDM_TOKEN. Token vydává služba idm a na jejím endpointu/api/v1/auth2/sista-infose dozvíte detailní informace o přihlášeném uživateli. Důležitá je především položkaactiveProfile.
Na uživatelském rozhraní využijete knihovnu @sista/idm-client a pomocí const { loggedAccount, authToken } = useContext(IdmClientContext); získáte stejné informace o uživateli, včetně jeho aktuálního tokenu, který pak použijete pro volání vašeho backendu.
3.10.1. Oprávnění uživatele
Nyní již znáte profileId uživatele, který vás volá. Typicky se snaží zobrazit nebo upravit nějaká data. Nyní je nutné zjistit kontext této operace: k jakému projektu se úkon vztahuje, k jakému providerovi, jakému departmentu, … apod. cokoliv, co může být pro oprávnění relevantní, včetně vašich priprietárních entit. S takto sestaveným SISTA kontextem se obrátíte na službu vazbátor, která je schopna na základě rolí uživatele a jeho vztahů k entitám v kontextu rozhodnout, jakou množinu oprávnění má. Oprávnění totiž vznikají na základě vztahu profilu a nějaké entity: jsem řešitel projektu, tedy mám na projekt vazbu X, ze které plynou oprávnění Y a Z.
Oprávnění jsou ad-hoc stringy, popsané v konfiguračním souboru služby vazbátor a můžete si je libovolně přidávat (my-trs:edit-all, my-trs:drop-database, …).
Existuje ještě jeden zdroj oprávnění a to jsou workflow úkoly. V definici workflow je možné nakonfigurovat, že po dobu existence nějakého úkolu má mít jeho řešitel (assignee) nějakou dočasnou roli (tj. vazbu na entitu z kontextu workflow procesu). Z této dočasné vazby pak mohou plynout dočasná oprávnění. I tato oprávnění vám poskytne vazbátor ve výše popsaném volání. Lze tedy snadno dosáhnout toho, že uživatel může něco udělat pouze pokud má přiřazený odpovídající úkol.
3.11. Vztah poskytovatele a SISTA
Služby SISTA musí počítat s možností provozu pro více poskytovatelů (= poskytovatelů prostředků pro výzkum, vývoj a inovace), tzv. „multitenantnost“. Hlavním poskytovatelem SISTA je zároveň provozovatel = TAČR. Jednotlivé služby přesto musejí umožňovat běh v režimu jiného poskytovatele.
Prakticky má tento požadavek dopad především na práva a/nebo přístupy uživatelů SISTA do dat každé služby, včetně průřezových. Přehledně jsou požadavky na práci s rolemi a z nich plynoucími přístupy a oprávněními shrnuty v samostatném dokumentu Přístupy a oprávnění v kontextu poskytovatele-profilu-role.
Nejsnazším způsobem jak multitenatnosti dosáhnout, je využívat existující koncepty - pracuji s obecným SISTA kontextem, z něj plynou permissions uživatele atd.
4. Data, komunikace a konzistence
V odůvodněných případech umí platforma zajistit různá datová úložiště, preferovaná ale jsou PostgreSQL databáze a Redis cache. Vyvarujte se praktik, které vaší službě znemožní horizontální škálování, jako je ukládání stavových dat do lokálního souborového systému nebo do paměti aplikace.
Dále existuje několik "SISTA specifických datových služeb", které byste měli využít:
-
významná sdílená data ukládejte do rejstříku,
-
číselníky patří do codetables,
-
binární přílohy do fista,
-
tiskové šablony do print-template,
-
lokalizační texty do sprava-textu,
|
|
Osobní údaje (resp. údaje, které se přímo vztahují k osobě přihlášeného profilu) ukládejte v rejstříku, aby bylo možné centrálně zajistit jejich výmaz (GDPR). Ve své službě ukládejte pouze profileId (či profile URN), nikoliv jméno, kontaktní údaje apod. |
4.1. Komunikace mezi službami
Zásadním tématem je komunikace mezi jednotlivými službami SISTA a zajištění konzistence dat v rámci distribuovaného systému. Platí zde některá obecná pravidla:
-
Veškerá komunikace v rámci služeb SISTA se odehrává v kódování UTF-8.
-
Všechna data se ukládají v kódování UTF-8.
-
Všechny časové údaje zahrnují i časovou zónu.
-
Všechny služby by měly přednostně využívat primární zdroje datových entit a nevytvářet jejich kopie, pokud to není pro fungování služby nutné. Pokud kopie existovat musí, je třeba zajistit jejich dlouhodobou konzistenci. Viz doporučení v kap. 2.5. Přístup k datům v [MT039] a terminologii tam stanovenou.
-
Pokud je volání drahé nebo velmi časté, měla by volající strana implementovat kešování. Obecný interval vypršení keše je 5 minut, pokud cílová služba nedokumentuje jinou hodnotu.
A také je potřeba rozhodnout, zda použít synchronní, nebo asynchronní komunikaci.
4.1.1. Synchronní komunikace
Synchronní komunikaci (= REST API call) použijete nejčastěji pro čtení. Ať už při zpracování uživatelského požadavku, nebo při interních výpočtech vaší služby. Pro volání je vhodné využít OpenAPI specifikaci, kterou má každá služba povinně zveřejněnou v Backstage (Katalog služeb). Volání jako takové zprostředkuje Dapr, který může zajistit retry policy, tracing apod. Z pohledu vaší služby se jedná o běžné HTTP volání.
4.1.2. Asynchronní komunikace
Pro zápis je vhodnější asynchronní komunikace, opět pomocí Dapr (zde je nutné využít Dapr klientskou knihovnu). Vaše služba publikuje zprávu do Topic, který je napojen na frontu zpráv (Subscription) cílové služby. Pro odesílání Dapr zpráv je vhodné zřídit ve své službě "transactional outbox", který zajistí, že zpráva bude odeslána pouze v případě, že je vaše transakce úspěšná. Pokud pošlete zprávu přímo a následně vaše transakce selže, dojde k nekonzistenci dat.
Tento způsob komunikace má některé vrozené vlastnosti a z nich plynoucí požadavky.
-
Volající služba by měla předpokládat, že zpráva dojde k adresátovi a tedy že systém bude "eventuálně konzistentní".
-
Zpráva může být doručena vícekrát (at least once delivery).
-
Přijímající TRS musí zaručit idempotentní zpracování zprávy, za tímto účelem se očekává, že ID vznikajícího záznamu přidělí volající služba.
-
Služby musí povinně informovat o provedených změnách stavu (př. aktualizace údajů, přesun workflow do kroku XY) nebo změnách doménových entit.
-
Služby publikují zprávy do Topic a konzumují ze Subscription. Jedno nebo více Subscription může být připojeno na jeden Topic.
-
Pro každý Topic je přípustný jeden datový typ zprávy. Definování Topic_ů a _Subscription je deklarativně v gesci dev týmů, ops je zajišťuje.
-
Fronta zpráv je agnostická a obsahu jednotlivých zpráv nemá rozumět (schéma dumb pipes, smart end-points).
-
Formát zpráv je JSON a/nebo binární data.
-
Pořadí zpráv v Subscription je totožné jako pořadí zpráv v Topic.
-
Pokud jedna ze služeb neběží, druhou to přímo neovlivní. Zprávy se drží v messaging službě nezávisle na samotných službách.
Pokud je vaše služba příjemcem zpráv, Dapr zajistí, že bude zpráva vaší službě doručena jako synchronní REST volání vašeho endpointu. Která témata chcete poslouchat, sdělíte platformě při startu vaší služby na endpointu /dapr/subscribe, kde vrátíte seznam témat a instrukce, kam se mají doručovat.
|
|
Díky tomu, že Dapr mění asynchronní zprávy na synchronní REST volání, je struktura asynchronní zprávy obvykle dohledatelná v OpenApi popisu cílové služby. |
Jaká témata posloucháte, zmiňte v dokumentaci, zvlášť pokud je to API určené k aktivnímu volání vašich metod.
5. Služby SISTA
V tuto chvíli již v rámci SISTA běží desítky služeb. Některé zajišťují části agendy TA ČR a nikdy s nimi nepřijdete do styku, jiné ale zajišťují užitečné (či povinné) funkce, které využije i vaše služba. Rozlišujeme dva druhy služeb.
- Průřezové služby
-
Jako průřezové služby označujeme ty, které poskytují funkce využitelné napříč více byznysovými službami. Typickým příkladem je identity management, notifikace, správa vazeb, rejstřík, formulářová služba apod. S těmito službami se v tomto dokumentu seznámíme podrobněji.
- Business služby
-
Byznysové služby jsou ty, které zajišťují konkrétní části agendy TA ČR. Typickým příkladem je služba pro podání návrhu projektu, formální kontrolu, hodnocení nezávislým expertem apod. Těmito službami se zde zabývat nebudeme.
V následujícím seznamu najdete přehled nejdůležitějších průřezových služeb SISTA. U některých služeb neuvádíme odkaz na API, protože se neočekává, že by je vaše služba přímo volala (např. menu, urn-resolver apod.).
5.1. idm
Služba zajišťuje přihlašování a správu uživatelských účtů. Použití je popsáno výše.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/idm/-/blob/master/docs/HOWTO.adoc |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/idmapi/definition#/TRS/sistaInfo |
5.2. rejstrik
Rejstřík slouží k ukládání libovolných dat o hlavních entitách: project, profil, organization (a pár dalších). Proprietární data o entitách vaší služby ukládejte ve svém PostgreSQL, ale data, která jsou "společná" (např. tedy hlavní parametry projektu) ukládejte do rejstříku.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/rejstrik/-/blob/master/docs/HOWTO.adoc?ref_type=heads |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/rejstrikapi/definition |
5.3. project-skeleton
Služba udržuje "hlavičková data" o projektech. Kdykoliv potřebujete získat libovolný seznam projektů (patří do soutěže, patří organizaci, jsou v nějakém stavu apod.), použijte tuto službu. Dále služba uchovává informace o stavu a podstavu projektu a odkazy na detaily projektu v rejstříku.
5.4. vazbator
Vazbátor je zdrojem dat o vztazích mezi entitami. Libovolná entita, kterou lze označit pomocí Sista URN, může mít (měla by mít) ve vazbátoru informace o svém vztahu k jiným entitám. Povolené vazby (role) se definují v konfiguračním souboru.
U vazeb mezi profilem a libovolnou entitou lze navíc definovat oprávnění (permissions), která z vazby plynou. Vazbátor tedy slouží jako zdroj informací o oprávněních profilu v nějakém kontextu. Vztahy mezi vašimi proprietárními entitami sem ukládat nemusíte, využijte běžné mechanizmy relační databáze.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/vazbator/-/blob/master/docs/HOWTO.adoc?ref_type=heads |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/vazbatorapi/definition |
5.5. notis
Notis slouží k odesílání notifikací uživateli. Notifikace se odesílají "na profil", konkrétní komunikační kanál (email, sms, push notifikace) určí Notis na základě uživatelských preferencí. Notis má také metody na přímé zaslání zprávy na konkrétní kanál, ale ty byste obvykle neměli na nic potřebovat. Notifikace lze snadno posílat i z Groovy skriptů workflow.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/notis/-/blob/master/docs/HOWTO.adoc?ref_type=heads |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/notis_api/definition |
5.6. forms
Formulářová služba slouží k vytváření, ukládání a vyplňování formulářů. Formuláře jsou definovány pomocí JSON schémat, která určují jak strukturu dat, tak i vzhled formuláře. Je detailněji popsána výše.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/forms/-/tree/devel/docs?ref_type=heads |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/formsapi/definition |
5.7. codetables
Správa číselníku. Drobné "enums" z vašich zdrojových kódu zde být nemusí, ale všechny sdílené číselníky, nebo číselníky, které si bude TA ČR v čase upravovat, by měli být zde. Služba podporuje verzování ke konkrétnímu datu a vícejazyčnost.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/codetables/-/blob/devel/docs/HOWTO.adoc?ref_type=heads |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/codetablesapi/definition |
5.8. fisto
Služba na správu binárních příloh. Soubory ukládá do "kategorií" (složek) a označuje je SISTA kontextem. Disponuje sdílenými komponentami pro výpis či upload souborů z UI. Možné kategorie a přístup k nim jsou řízeny konfiguračním souborem. Fyzicky jsou soubory ukládány do Google Cloud Storage.
5.9. print-template
Služba zajišťuje správu a verzování tiskových šablon (Asciidoc + Mustache) a také zprostředkuje samotný tisk do PDF. Výsledný PDF soubor je uložen do Fista do dočasné kategorie a pokud má mít dlouhodobé trvání, musíte ho v rámci Fista přesunout do své vlastní kategorie.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/print-template/-/blob/master/docs/HOWTO.adoc?ref_type=heads |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/printtemplateapi/definition |
5.10. sprava-textu
Jednoduchá služba pro správu lokalizačních textů. Myšlenkově vychází z produktu "Localazy", ale je integrována do fe-commons a podporuje varianty překladů dle kontextu.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/sprava-textu/-/blob/master/docs/HOWTO.adoc?ref_type=heads |
5.11. fulltext
Libovolný typ entity lze zaregistrovat do služby fulltext, která se pak postará o indexaci a vyhledávání. Vlastnosti vaší entity, resp. způsob jak z ní vyrobit indexovatelný dokumenta se definije Groovy skriptem v konfiguraci fulltextu.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/fulltext/-/blob/master/docs/HOWTO.adoc?ref_type=heads |
5.12. urn-resolver
Urn-resolver slouží především jako backend pro <SistaChip/> a zajišťuje překlad SISTA URN na standardizovaný datový popis entity. Vašem významnější entity by zde měly být nakonfigurovány, aby se SistaChip korektně vyhodnocoval (např. na seznamu úkolů apod.).
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/urn-resolver/-/blob/master/backend/docs/HOWTO.adoc?ref_type=heads |
5.13. menu
Sdílená UI komponenta, zajišťující vykreslení levého menu. Vaši službu bude potřeba do menu přidat.
Repo |
|
|---|---|
HOWTO |
(není) |
5.14. workflow
Služba pro řízení procesů. Je detailněji popsána výše.
5.15. rule-engine
Služba, která umí na zaslaný SISTA kontext odpovědět rozhodnutím. Využívá se pro určení správné varianty workflow, tiskové šablony, formuláře apod.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/rule-engine/-/blob/master/docs/HOWTO.adoc?ref_type=heads |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/ruleengineapi |
5.16. sprava-ukolu
Slouží pro evidenci úkolů uživatelů, bez ohledu na typ profilu. Pomocí úkolů se řídí činnost uchazečů, expertů, referentů. Nejčastěji úkoly vytváří automaticky proces workflow, ale je možné vytvářet ad-hoc úkoly i pomocí API.
Repo |
|
|---|---|
HOWTO |
https://git.tacr.cz/sista/services/sprava-ukolu/-/tree/master/docs?ref_type=heads |
Api |
https://docs.sista.tacr.cz/katalog-sluzeb/catalog/default/api/spravaukoluapi/definition |
Příloha A: Odkazy a zdroje
A.1. Hlavní
- Rozcestník k dokumentaci SISTA
- Katalog služeb
- Katalog služeb - REST APIs
- Zdrojové kódy TRSů SISTA
- Pravidla vývoje
- Pravidla platformy
- HOWTO Platform - implementační detaily
-
https://docs.google.com/document/u/2/d/1lXL-0xQ0f06DD3iv8K1H9rVn_lByRyoJiQt1Icsw_8M/edit
- Pravidla dokumentace
A.2. Externí
- 12Factor
- URN
- Transactional outbox pattern
-
https://microservices.io/patterns/data/transactional-outbox.html
- Dapr
Příloha B: Checklist architektury
Následující checklist berte pouze jako mentální pomůcku, která vám usnadní obsáhnout celou šíři architektonických pravidel SISTA. Nejedná se vyčerpávající či závazný přehled požadavů. Závazný je vždy backlog a zadání minitendru.
-
❏ Vaše služba je v Git repozitáři TA ČR, pipeline ji dokáží sestavit, otestovat a nasadit do SISTA prostředí.
-
❏ Vaše služba je schopná běhu ve více replikách
-
❏ Frontend je React/TypeScript aplikace využívající Dista a FE Commons.
-
❏ Sdílené vizuální prvky jsou vystavené jako federované komponenty.
-
❏ Pro identifikaci cizích entit používáte SISTA URN.
-
❏ Pro popis širšího kontextu vašich záznamů používáte koncept "SISTA kontext".
-
❏ Pro čtení dat z cizích služeb využíváte synchronní komunikaci přes "synchronní Dapr"
-
❏ Drahá či častá volání cizích REST API využívají cache.
-
❏ Pro zápis dat do cizích služeb a "broadcast" využíváte asynchronní komunikaci přes "asynchronní Dapr"
-
❏ Pro odesílání Dapr Pub/Sub zpráv používáte transakční outbox.
-
❏ Endpointy na které jsou doručovány Dapr Pub/Sub zprávy implementují idempotenci.
-
❏ Používáte správně existující průřezové služby:
-
přehled a stav projektů - project-skeleton
-
přihlášený uživatel a jeho aktivní profil - idm
-
na UI z IdmClientContext,
-
na backendu dotazem na Bearer token do idm
-
-
oprávnění a vazby uživatele (resp. vazby čehokoliv) - vazbátor
-
detailní informace o projektu - rejstřík
-
informace o soutěži - call-for-proposals
-
procesy a úkoly - workflow
-
notifikace - notis
-
binární soubory - fisto
-
tisky - print-template
-
formuláře pro sběr business dat - forms
-
Sista URN vizualizujete pomocí komponenty SistaChip
-
-
❏ Existuje dokumentace služby (HOWTO adoc, …), popis v Backstage a OpenAPI specifikace