Dokument popisuje konkrétní požadavky na kvalitu dodaného kódu služby Sdíleného informačního systému TA ČR (dále jen SISTA). Věnuje se způsobu verzování, testování, nasazování a dalším konkrétním detailům vývoje služeb v rámci SISTA. Mnohá z těchto pravidel jsou v oboru zcela běžná a jsou na SISTA nezávislá, narozdíl od Pravidel architektury SISTA, která jsou naopak velmi "SISTA specific" a dozvíte se v nich jak vaši službu zakomponovat do celkové architektury SISTA.

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.

"Pravidla vývoje" manifest dále rozvíjí a konkretizují pro potřeby vývoje služeb v rámci SISTA a formují mantinely spolupráce mezi TA ČR a dodavateli i dodavateli mezi sebou.

Important

Je vhodné se se zastřešujícím manifestem 12factor seznámit.

Konkrétní implementační detaily (jak se připojím k DB, kam mám umístit Swagger dokumentaci, jak deklaruji témata své asynchronní komunikace, …​) popisuje živý dokument [HOWTO Platform].

2. Vývoj

2.1. Analýza požadavků

Jakýmkoli vývojovým pracem musí předcházet analýza potřebných požadavků. Dev a ops týmy jsou zodpovědné za identifikaci požadavků – na úrovni byznysových, technických, datových i běhových / operačních.

Součástí identifikace požadavků je analýza potřebných datových entit a typů. Každá používaná datová entita musí mít příslušný záznam v datovém slovníku, viz [MT039].

Kde je to vhodné, má být součástí požadavků definice potřebných datových kontrol (validací).

2.2. Základní požadavky na vývoj

Pro vývoji služeb SISTA platí následující základní požadavky:

  1. Dev tým musí vyvíjet danou službu tak, aby v kontejnerovém prostředí umožňovala:

    • běh ve více instancích – horizontální škálování,

    • napojení na více vstupních bodů ostatních služeb (př. sdílená databáze) a zotavení z jejich výpadků,

    • využití schémat vysoké dostupnosti,

    • automatizovaný restart, zotavení z mimořádných situací.

  2. Sdíleným verzovacím systém pro všechny služby SISTA je git hostovaný v prostředí Gitlab:

    • Dev tým musí vyvíjet proti tomuto repozitáři.

    • Ops tým je zodpovědný za správu repozitáře.

    • Jmenné konvence a další požadavky štábní kultury pro repozitáře jsou uvedeny níže, viz Repozitáře.

  3. Dev tým je zodpovědný za implementaci API služby takovým způsobem, aby ostatní součásti SISTA mohly se službou interagovat:

    • API musí být dokumentované pomocí formátu OpenAPI, podrobněji viz [HOWTO Platform]

    • API musí být verzované, a to expresivním způsobem pomocí URL, nestačí spoléhat jen na HTTP hlavičky.

    • API musí být zpětně kompatibilní na úrovni end-pointů a datového modelu – „je možné pouze přidávat, nikoli měnit nebo ubírat“:

      • V nezbytných případech mohou být zpětně nekompatibilní změny implementovány po výslovně dohodnuté výjimce TA ČR a všech dotčených dev a ops týmů.

      • Dev tým by měl využít všech dostupných možností, aby taková změna nebyla nutná.

      • Příslušné části API musejí být v dokumentaci označeny jako deprecated a po stanovenou dobu musí být jejich volání ošetřeno alertem v monitoringu a upozorněním klienta, že používá zastaralou verzi API.

      • Dev tým musí upozornit ops tým, případně jiné zainteresované osoby (garanta tématu, vlastníka služby), pokud potřebné rozhraní ostatních služeb neodpovídá dokumentaci.

      • Návrh, úpravy a přebírání datových struktur se řídí požadavky data governance, viz [MT039].

      • Dev tým se chová zodpovědně a využívá definičních schémat – JSON Schema, příp. XML Schema.

  4. Dev tým je slušný na výstupních programových rozhraních (primárně API a fronta asynchronních zpráv, sekundárně export dat). Dev tým nedůvěřuje vstupům od uživatele (sekundárně dávkovému importu dat), ale důvěřuje ostatním TRSům.

  5. Dev tým musí službu implementovat jako docker image. Podrobněji viz Pravidla nasazování.

  6. Dev tým zodpovídá za implementaci rozhraní pro kontejnerizaci, případně další rozhraní pro kontrolu běhu a zdraví služby viz Pravidla nasazování. Předpokládá-li použití služby těsnou integraci s další službou (např. IdM / RO), je dev tým zodpovědný za spolupráci s touto.

  7. Kde je to vhodné, má se využít parametrizace volání API.

  8. Pokud jsou použité (i tranzitivní) závislosti na knihovnách 3. stran, je dev tým povinen deklarovat přesnou verzi potřebných knihoven.

  9. Dev tým je ve spolupráci s ops týmem zodpovědný za dodržování požadavků na bezpečnost při vývoji i  nasazování viz Pravidla nasazování, Řízení přístupu a tajemství – Secrets management, Testování a Bezpečnost.

  10. Dev tým je zodpovědný za dodržování názvosloví dle ustálené terminologie.

  11. Dev tým je zodpovědný za využití existujících sdílených / průřezových služeb:

    • IdM / Rejstřík,

    • notis,

    • workflow,

    • rule-engine,

    • codetables – včetně verzování, viz dokumentaci,

    • FiSto,

    • forms,

    • fulltext,

    • …​ atp.

  12. Dev a ops tým jsou zodpovědné za určení chování služby v případě nutnosti implementace multi-operací (systémová nebo uživatelská akce, závislá na více než jedné službě). Oba týmy musí – ve spolupráci s dalšími dotčenými týmy – popsat, implementovat a otestovat žádoucí chování všech zúčastněných služeb.

  13. Dev tým je zodpovědný za integraci služeb 3. stran (př.: veřejný zdroj informací mimo SISTA, SMS brána apod.) tak, aby jejich nedostupnost nezpůsobila selhání služby a celé SISTy.

    • Pokud služba vyžaduje synchronní volání, dev tým zvolí vhodný postup, aby se nedostupnost služby nepropagovala dále do systému.

    • Dev tým by navrhne, jak informovat o nedostupnosti požadované funkcionality (př.: HTTP kód, hlavička atd.).

    • Co lze vyřešit frontou požadavků, nechť vyřeší fronta (toto téma detailněji rozebírají Pravidla architektury v otázce synchronní a asynchronní komunikace).

  14. Dev tým je ve spolupráci s ops týmem zodpovědný za implementaci rozumných reakčních lhůt a timeoutů pro komunikaci mezi službami. Lhůty musí jít nakonfigurovat.

    • Pro hodnoty lhůt uvažujme o desítkách sekund až malých jednotkách minut.

    • Co lze, nechť se řeší asynchronním zpracováním požadavků, při němž je možné příchozí volání odbavit zařazením do fronty („technické zpracování“) a následně informovat volající stranu o vyřízení požadavku („byznysové zpracování“).

  15. Pokud služba nabízí déletrvající spojení se stranou uživatele pomocí protokolu WebSockets, měl by dev tým předejít předčasnému zavření každého takto ustanoveného spojení zasíláním řídicích ping rámců. Spojení je automaticky přerušeno 60 s od poslední aktivity (vč. pingu). Ping tedy musí být posílán v dostatečně rozumném předstihu tohoto intervalu (50 s).

2.3. Požadavky na vývoj FE

Základní koncepty pro vývoj FE jsou:

  1. FE má architekturu založenou na minifrontendech:

    • minifrontendem se rozumí samostatná jednostránková webová aplikace (SPA), která obsluhuje jednu funkční doménu a zastává roli FE pro jednu ucelenou službu (skupinu mikroslužeb),

    • minifrontend může obsahovat a poskytovat komponenty, které je možné začleňovat do jiných aplikací pomocí dynamického nahrávání;

  2. pro implementaci se používá React;

  3. použití komponent napříč minifrontendy je dynamické v době běhu – pro dynamické sdílení komponent se využívá webpack module federation;

  4. k propagaci kontextu do jednotlivých komponent se používají props, případně v kombinaci s použitím eventů v rámci browseru;

  5. je k dispozici knihovna komponent, která implementuje design systém DISTA a kterou sdílejí jednotlivými minifrontendy formou statického linkování v době překladu;

  6. dev tým respektuje požadavky na UX, resp. uživatelské rozhraní dle pravidel design systému DISTA.

2.3.1. Zdrojové kódy DISTA

Knihovna komponent je dostupná z repozitáře DISTA UI.

Vývojářská dokumentace je v souboru DEVS (AsciiDoc).

Ukázky použití knihovny jsou v adresáři examples/ui-library-playground/.

2.3.2. l10n, i18n

Všechny služby SISTA musí být schopné pracovat ve vícejazykovém protředí. Základní požadované jazyky jsou čeština a angličtina, další budou součástí pozdějšího rozvoje.

  • Dev tým implementuje prvky uživatelského rozhraní, textových informací pro uživatele (např. šablony notifikací, generovaných dokumentů atp.) i chybových hlášek tak, aby změna jazyka služby byla možná dynamicky a uživatelsky, za běhu.

  • Pro implementaci internacionalizace se používá služba správa textů

  • Ukázková implementace lokalizace je v kostře aplikace create-fe-app, resp. sdílené knihovně FE Commons (původně byla lokalizace napojena na službu Localazy, správa textů je s ní kompatibilní)

2.3.3. Existující komponenty

V průběhu vývoje SISTA již byly vytvořeny federované komponenty (krom primárních DISTA komponent), které musí dev týmy použít / integrovat v situacích, kdy je to vhodné. Existující komponenty vznikly v rámci:

2.4. Poskytovatelé, multitenantnost

Součástí SISTA kontextů (viz Pravidla architektury) by měl být poskytovatel – přestože TA ČR je provozovatelem a primárním poskytovatelem pro většinu běhových prostředí, služby musí být připraveny na možnost, že poskytovatelem rozdělovaných prostředků je jiný subjekt (př.: Ministerstvo životního prostředí, Úřad vlády ap.)

Praktický dopad tohoto požadavku se týká především rolí a přístupových oprávnění pro jednotlivé uživatele. Je nepřípustné, aby data služeb držená pro jednoho poskytovatele (př. MŽP) byla přístupná uživatelům jiného poskytovatele (př. MV). Výjimkou z tohoto pravidla jsou uživatelé TA ČR, kteří z titulu provozovatele mají / mohou mít v patřičných rolích přístup i k datům jiných poskytovatelů.

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.

2.5. Testování

Testování je nedílnou součástí vývoje každé služby a musí probíhat po celou dobu vývoje. Vhodná podoba závisí na povaze služby, zvolené technologii a konkrétních požadavcích ops týmu.

Podrobné pokyny k oblasti testování definují [Pravidla testování], ale rámcově platí následující:

  1. Dev tým je zodpovídá za přípravu automatizovaných testů. Ops tým musí mít přístup k výsledkům (reportům) těchto testů.

    • Cílem je nalezení rovnováhy mezi unit, integračními a dalšími typy testů (end–to–end).

    • Kde je to účelné, dev tým by měly automatizovat i další typy testů.

    • Testovací transakce mají být rozlišitelné od provozních informací.

    • Unit testy by se měly automaticky spouštět v rámci pipeline – minimálně v hlavní větvi, ideálně na všech komitech.

Note
Poznámka

Po nasazení prostředí GitLab se předpokládá automatizace v rámci pipeline, včetně reportingu.

  1. Dev a ops týmy zodpovídají za přípravu a provádění ručního testování při jednotlivých nasazeních.

    • Dev tým je zodpovědný za přípravu testovacích plánů. Doporučujeme jejich přírůstkovou tvorbu v průběhu celého vývoje služby a průběžné konzultace s garantem tématu. Doporučená šablona pro testovací plány je k dispozici v rámci SISTA Test Management, viz níže.

    • Garant tématu a ops tým jsou zodpovědní za jejich upřesnění / schválení testovacích plánů, pokud je to v dané situaci potřebné.

    • Oba týmy jsou zodpovědné za reporting provedených testů.

    • Dev tým je zodpovědný za odpovídající reakci na nalezené mimořádné situace a chyby.

    • Pro případy, kdy test není možné provést v uživatelském rozhraní, je dev tým zodpovědný za přípravu testovacího plánu alternativním způsobem (např. testplán ručního testu přes API).

    • Reporting provedených testů je součástí akceptačního řízení jednotlivých služeb a slouží i jako podklad pro _sanity check dodaného díla.

    • Akceptační testování se provádí proti STAGING prostředí.

  2. Dev a ops týmy zodpovídají za identifikaci a implementaci vhodné podoby integračních testů mezi vlastní službou a dalšími službami SISTA.

Important
Doporučení

  • Pokrytí unit testy by mělo být rozumné.

  • Doporučujeme využití uživatelsky přívětivých nástrojů např. Insomnia.

  • Pro automatizované testy doporučujeme využití metody Property-Based Testing.

  • Pro byznys služby se doporučuje zavedení end–to–end testů dle návrhu v [MT065].

2.6. Dokumentace

„Živá“ dokumentace je zásadní, aby celý systém fungoval, dokázal se zotavit z mimořádných situací a mohl se rozvíjet.

Podrobná pravidla definují [Pravidla dokumentace], ale rámcově očekávejte:

  1. Dev tým zodpovídá za počáteční dokumentaci služby, který vyvíjí.

  2. Dev tým je ve spolupráci s ops týmem zodpovědný za průběžnou aktualizaci dokumentace. Nejdůležitější ve vztahu k ostatním částem systému jsou:

    • dokumentace API, kontraktů, použitých datových typů a jejich formátů,

    • použité formální validace, nejlépe ve standardizované podobě (XSD, JSON Schema),

    • změny verzí,

    • administračních postupů při správě služby.

  3. Dev tým zodpovídá za uložení veškeré vývojové dokumentace do gitu.

  4. Dev a ops tým zodpovídají za aktuálnost uživatelské dokumentace dané služby SISTA.

Important
Doporučení

  • Doporučujeme do gitu ukládat dokumentaci i k ostatním předpisům (konfigurace, infrastructure-as-code); bez osobních údajů a tajemství.

  • Důrazně doporučujeme využití dokumentace generované ze zdrojových kódů, viz [Pravidla dokumentace].

  • Uživatelská dokumentace všech částí se nachází na jednom místě a dev a ops týmy jednotlivých služeb musí udržovat aktuální „svoji“ část.

2.7. Chyby a výjimky

Pro účely zobrazování chyb v UI a logování zachycených chybových stavů jinými službami musí dev tým implementovat chybovou strukturu, kterou při nastalém stavu předá volajícímu (UI, službě).

{
  "errorId": "doporučené unikátní ID chyby, které TRS zaloguje",
  "serviceId": "povinné unikátní ID služby, která chybu vyvolala",
  "message": "povinný text chyby",
  "localizedMessage": { // volitelné lokalizované texty
    "en": "text of the error",
    "cs": "text chyby hezky"
   },
   // … jakákoliv další proprietární data, která TRS chce zalogovat …
   // … porušení validačních pravidel, header info volajícího, className, URI, …
}

Povinná pole jsou:

  • serviceId – identifikátor služby, která chybu vyvolala,

  • message – chybová hláška: stručná informace o příčině chyby; je třeba počítat s tím, že tento text uživatel uvidí v UI.

Doporučená pole jsou:

  • errorId – jednoznačný identifikátor chyby pro možnost dohledání vzniku ve zdrojovém kódu,

  • localizedMessage – lokalizovaný text chybové hlášky (zdroj chyby nemusí mít přístup k HTTP hlavičce uživatelova prohlížeče).

Ostatní pole jsou volitelná, TRS do nich může vložit jakoukoli informaci, kterou považuje za důležitou pro pozdější referenci.

Služba by měla vynaložit přiměřené úsilí aby byl message lokalizovaný, ale vzhledem k tomu, že služba nemusí mít správné informace o konečném jazyce, ve kterém se zpráva zobrazí, je vhodné aby doplnila i možné varianty hlášek v různých jazycích.

2.8. Fulltextové vyhledávání

Součástí SISTA je fulltextový vyhledávač, který indexuje datové entity, v nichž se předpokládá uživatelské vyhledávání.

Podrobný popis služby, její použití a začlenění vlastních datových entit do indexování popisuje dokumentace služby v repozitáři fulltext.

2.9. Bezpečnost

V oblasti bezpečnosti platí následující základní pravidla:

  1. Všichni členové dev týmu jsou povinni dodržovat pravidla bezpečnosti dle aktuální verze doporučení organizace OWASP Top 10.

  2. Security-by-Design: Výchozí nastavení komunikace každé vyvíjené služby by měla být restriktivní typu „deny, allow“, tj. implicitní omezení přístupu, udělení přístupu teprve po ověření A&A volající komponenty. V odůvodněných případech může být přístup obrácený – taková situace musí být nejprve konzultována s TA ČR.

  3. Proces vývoje musí minimalizovat riziko útoku typu supply-chain-attack, tj. zavlečení chyby a/nebo zranitelnosti použitím např. knihovny třetí strany. Použití knihoven, frameworků a/nebo služeb třetích stran musí být zdokumentováno. Výběr knihoven by se měl řídit pravidly kap. 4. Použité knihovny bezpečnostního doporučení NÚKIB, viz [NUKIB].

  4. Odhalené zranitelnosti knihoven / frameworků / služeb třetích stran musí být opraveny co možná nejdříve, případně musí dev tým navrhnout jiná opatření, která zneužití zranitelnosti minimalizují.

  5. Služba nesmí umožnit získání jakýchkoli citlivých dat (např. osobní údaje, rozpočet projektu apod.) volající komponentě či přímo koncovému uživateli bez ověření A&A. služba smí bez A&A umožnit zveřejnit pouze předem definovaná data.

  6. Dodavatel musí podniknout přiměřené kroky, aby zabránil úniku informací potenciálně citlivé nebo kompromitační povahy – osobní údaje, kryptografické klíče, credentials apod.

  7. TA ČR poskytuje oficiální repozitář artefaktů (docker registry a NPM repository), sestavování vývojových artefaktů musí probíhat proti tomuto repozitáři. Dev týmy vznesou požadavek na umístění a / nebo aktualizaci daného artefaktu v oficiálním repozitáři TA ČR, za jeho správu je zodpovědný ops tým.

  8. Dev a ops týmy jsou zodpovědné za implementaci vhodných kryptografických prostředků a nástrojů pro jejich správu všude tam, kde je to možné, viz pravidla kap. 6. Kryptografické prostředky bezpečnostního doporučení NÚKIB [NUKIB].

3. Zdrojové kódy, git, automatizace

Zdrojové kódy služeb, knihoven, nástrojů a šablon SISTA jsou spravovány v repozitářích Gitlabu, které jsou organizovány do grupy https://git.tacr.cz/sista.

Preferovaným lidským jazykem všech zdrojových kódů (proměnné, třídy, funkce / metody, …) je angličtina. U komentářů se angličtina nevyžaduje, přednost má srozumitelnost komentáře, viz též [Pravidla dokumentace].

3.1. Repozitáře

Pro názvy a URL repozitářů platí následující pravidla:

  1. URL slug repozitáře je vázán na název repozitáře. Z tohoto vyplývají následující skutečnosti:

  2. Názvová část služby, knihovny, či nástroje (níže v <>) se skládá z jednoho až tří slov a měla by odpovídat názvu této služby, který se běžně používá v rámci SISTA.

Následují standardizované názvy repozitářů:

Název repozitáře repo-slug

SISTA service – <služba>

git.tacr.cz/sista/services/sluzba

SISTA library – <knihovna>

git.tacr.cz/sista/libraries/knihovna

SISTA service – <dlouhý název služby>

git.tacr.cz/sista/services/dlouhy-nazev-sluzby

SISTA tool – <název nástroje>

git.tacr.cz/sista/tools/nazev-nastroje

SISTA template – <název šablony>

git.tacr.cz/sista/templates/nazev-sablony

  1. V rámci SISTA se počítá také s tvorbou repozitářů, jejichž typ je v SISTA ojedinělý, a tudíž nemají (a nepředpokládáme, že budou mít) standardizovaný název:

    • "SISTA <název>" → sista-<nazev>

  2. Tvorba názvu repozitáře probíhá za spolupráce dev a ops týmu.

  3. Při tvorbě názvu prioritizujeme následující pravidla:

    1. popisnost: název repozitáře by měl co nejlépe vystihnout, co je obsahem repozitáře;

    2. nezaměnitelnost: název repozitáře by neměl být lehce zaměnitelný s ostatními repozitáři, ani by neměl tvořit pochybnosti, která část obsahu je v kterém z repozitářů (př.: „Služba evidence“, „Služba evidence2“ a „Služba evidence financí“ jsou nesprávné názvy, existují-li zároveň);

    3. čitelnost: název by měl být nejen obsahově výstižný, ale i čitelný a vyslovitelný;

    4. budoucnost: název by měl být tvořen tak, aby výše zmíněné splňoval co nejlépe i do budoucnosti;

    5. stručnost: kratší názvy jsou obecně lepší (při zachování požadavků ↑).

  4. Zvolený jazyk, framework ani jiná technologie (vč. dodavatele) se do názvu repozitáře nepromítají.

  5. Funkcionality, které jsou na url repozitářů navázány, implementujeme tak, aby v případě změny názvu repozitáře bylo možné jednoduše přenést tuto úpravu do kódu, který s ním pracuje.

Important

Všechny dev týmy musí dodržovat metodiku Conventional Commits s rozšířením typu commitů o:

  • feat – změna přidává novou funkčnost,

  • fix – změna opravuje chyb,

  • chore – změna nemění chování / funkčnost (způsob sestavení, formátování kódu, refaktoring, …),

  • docs – úprava dokumentace,

  • test – přidání testů (testy mohou být přidány i v rámci feat a fix),

  • (více viz v [MT065]).

3.2. Větve

U většiny repozitářů se používají následující dvě větve:

  • master – hlavní větev, do které se mergují hotové změny, které jsou připravené pro nasazení do produkčního prostředí,

  • devel – vývojová větev, do které se mergují pracovní změny, které ještě nejsou připravené pro nasazení do produkčního prostředí, ale jsou připravené pro testování a další vývoj.

Poměrně obvyké je, že se devel větev automaticky nasazuje na vývojové prostředí.

Je povolené vytvářet další branche, například pro vývoj konkrétní funkčnosti a nasazovat na vývojové prostředí ty. Tyto branche by měly být pojmenované srozumitelně a měly by být po dokončení práce (tj. merge do devel či master smazané).

3.3. Verzování a upgradování, release notes

3.3.1. Automatické verzování služeb

Většina služeb je verzována automaticky při mergi do master větve. To znamená, že při každém mergi do master větve se automaticky vytvoří nový tag s verzí, ve které je automaticky zvýšená MAJOR verze.

image 2026 05 12 14 14 16 491

V takovém případě je také obvyklé, že se konkrétní MAJOR verze (tj. git tag) nasazuje na STAG nebo PROD prostředí.

3.3.2. Verzování knihoven

Pro verzování sdíleného kódu (především FE knihovny a federované komponenty) platí:

  • používejte sémantické verzování - MAJOR.MINOR.PATCH, viz semver.org,

  • změna verze MINOR nebo PATCH má odpovídat změně, která umožňuje aktualizaci závislostí bez zásahu do byznys služeb, jež daný kód využívají,

  • změna verze MAJOR může vést k nutnosti aktualizovat podle závislostí v Katalogu služeb i konkrétní byznysové služby, což musí posoudit jejich dodavatel.

Pro FE služby je v rámci platformy (gitlabu) k dispozici nástroj renovatebot pro automatickou tvorbu PR s upgrady závislostí, který řeší upgrady knihoven komponent a knihoven třetích stran. V dohledné době bude jeho nasazení na všechny FE služby povinné. Nasazení a konfiguraci zajištuje ops tým. Renovatebot spoléhá na správné semantické verzování.

Pro potřeby tvorby release notes si dodavatel může u ops týmu vyžádat vypnutí automatického verzování a tagovat verze master větve ručně. Pro verzování byznysových služeb platí požadavek verzování tagem při mergování do hlavní větve. Verzování je navázáno na dokumentaci release notes v Gitlabu – při vytvořené nové verze (tagu) je dodavatel povinen vyplnit příslušný text dle následujícího postupu:

  1. zamergovat pracovní verzi do master větve,

  2. vytvořit tag verze (v$#.X.Y, kde $# je rostoucí sekvence celých čísel, X.Y jsou minor čísla verze pro patche a hotfixy),

  3. vytvořit changelog / release notes dokument daného repozitáře (Deploy → Releases → New release)

  4. vybrat příslušnou verzi (tag)

  5. vyplnit název + release notes (text podporuje formátování pomocí MarkDown, může obsahovat odkaz na větve, commity atd.)

Note
Poznámka

  • Release notes se píší v češtině.

  • Tehdy, kdy to dává smysl – tedy při publikování verze, která obsahuje významné změny proti již dříve vydaným verzím, a do produkčního prostředí.

  • Takové změny, zejména zpětně nekompatibilní změny je nutné výrazně označit (použijte formátování / nadpisy).

  • Pokud má repozitář historicky nastavené automatické verzování při mergi do master větve, lze požádat ops tým, aby tuto funkci vypnul.

Pro vydávání patchů a hotfixů se používá následující postup:

  1. otagovat ručně v$\#.0.0 (př. v95.0.0), pokud není v master větvi,

  2. vytvořit branch s názvem v$\#.X (pro př. v95 to bude v95.1, tag a branch se nesmí jmenovat stejně),

  3. branch nastavit protected + jen merge (musí nastavit někdo z ops týmu),

  4. založit jiný branch s fixem (př. v95-hot-fix-XYZ),

  5. vytvořit merge request do v$\#.X,

  6. master větev dostane nový tag (zvedá se jen patch verze).

Další informace jsou k nalezení v [MT065].

3.4. Automatizace: CI

  • Pro potřeby CI / CD musí být definovaná větev pro kontinuální nasazování (obvykle devel)

  • Kde je to možné, má být jako součást pipeline zařazena statická analýza kódu. Vzorové nastavení pro vývoj FE je součástí skeletonu aplikace, pro vývoj BE je doporučené držet se obvyklých standardů dané technologie.

  • Ve zdrojových kódech nesmějí být natvrdo zahrnuté konstanty prostředí (př.: IP adresy, konfigurační hodnoty).

  • CI / CD dev týmu musí být plně automatizovaná.

  • Pro každý kontejner musí existovat deklarativní popis služeb.

  • Pokud je to potřeba, musí být součástí spuštění CI / CD příprava dat pro automatizované testy (např. v pre-build fázi).

  • Dev tým by měl implementovat doporučení kap. 5. Kontinuální integrace bezpečnostního doporučení NÚKIB, viz [NUKIB].

Important
Doporučení

  • Doporučujeme používat existující nástroje, např. Bamboo, CircleCI, CodePipeline apod.

  • Nasazení služeb by mělo probíhat do čistého prostředí. Pouze v odůvodněných případech (hot-fix kritické chyby) může nasazení proběhnout přímo do produkčního prostředí.

3.5. Automatizace: CD

Pro kontinuální nasazování (CD) se používá nástroj ArgoCD. K CD je přistupováno:

  • Na úrovni definice konkrétního clusteru na konkrétním prostředí v grupě environments lze v souboru <nazev-prostredi>/<nazev-clusteru>/services.yaml anotovat konkrétní službu využívající CD stylem

<nazev-sluzby>:
    git_ref: <nazev-sledovane-vetve>

  • Při takto nastavené anotaci se po každém commitu (v případě devel větví) nebo merge requestu do master větve služba automaticky sestaví, otestuje a nasadí na příslušný cluster na příslušném prostředí.

  • V zájmu optimalizace prostředků produkční image nemá obsahovat komponenty, které nejsou pro běh aplikace potřeba (binárky, knihovny, skripty, …). Pokud si dev tým není jist správným postupem buildu, kontaktuje ops tým.

  • Pro STAG nebo PROD se využívá nasazování konkrétní verze (tagu)

<nazev-sluzby>:
    git_ref: <tag>

4. Provoz

4.1. Prostředí

Celý komplex služeb SISTA se spouští v tzv. "clusteru" - virtuálním prostředí, které poskytuje potřebné zdroje pro běh služeb a zajišťuje jejich vzájemnou komunikaci. Provozní prostředí se nachází v Google Cloud Platform (GCP) a je spravováno ops týmem TA ČR.

Těchto prostředí je možné mít více, každé může mít odlišnou konfiguraci, dle potřeby a účelu. Aktuálně jsou v provozu následujícím prostředí:

  • PROD - produkční prostředí, určené pro koncové uživatele SISTA, které musí být stabilní a dostupné 24/7;

  • STAG - stagingové prostředí, určené pro testování a akceptaci nových verzí služeb před nasazením do produkce, které by mělo být co nejpodobnější produkčnímu prostředí;

  • fnx-dev - vývojové prostředí, určené pro vývoj a ladění služeb, které může být méně stabilní (název je důsledkem faktu, že v ranných obdobích vývoje měl každý dodavatel vlastní cluster)

  • linksoft-test - testovací prostředí, určené pro zátěžové testování

Provoz clusteru je relativně nákladný, bylo by dobré vystačit si již existujícími prostředími.

4.2. Resolving služeb a komponent

Pro lokalizaci služeb a dynamicky nahrávaných komponent platí jmenná konvence:

  • interní URL uvnitř klastru se nastavuje proměnnou ${VAR}_INTERNAL_ROOT,

  • externí URL se nastavuje proměnnou ${VAR}_PUBLIC_ROOT,

  • přičemž výchozí hodnoty pro služby jsou:

    • pro interní URL http://app.${service},

    • pro externí relativní URL /${service},

    • kde ${service} odpovídá jmennému prostoru služby v klastru;

    • příklad:

IDM_INTERNAL_ROOT = http://app.idm
IDM_PUBLIC_ROOT = http://dev-cluster.sista.tacr.cz/idm

Více viz HOWTO platform.

4.3. Škálovatelnost a repliky služby

Služba (TRS) by měla umožňovat běh ve více instancích / replikách - měla by být škálovatelná. Ve skutečně odůvodněných případech lze od tohoto požadavku ustoupit, obecně ale počítejte s během ve více replikách.

Pokud je služba škálovatelná, nasazení probíhá tak, že nastartuje nová verze a jakmile začne odpovídat na readiness probe, přepne se veškerý síťový provoz na novou verzi, stará verze je odpojena a pak dojde k jejímu ukončení. Do databáze je v jednu chvíli připojena jak stará, tak nová služba.

Pokud je služba neškálovatelná, nasazení probíhá vždy tak, že nejdříve je původní verze ukončena a teprve pak se nastartuje nová. Výpadek je delší o dobu startu služby.

Pokud služba běží ve více replikách, znamená to, že v případě asynchronních zpráv přijde půlka zpráv jedné replice a půlka zpráv druhé. Vzhledem k at-least-once sémantice se může stát, že přijde ta samá zpráva oběma replikám. Pořadí zpráv je zachováno pouze v rámci sady zpráv doručené každé z replik.

Podobně i u synchronních requestů, půlka může přijít jedné replice a druhá půlka druhé. Retry mechanismus tak může způsobit, že ten samý request dorazí jak jedné, tak druhé replice.

Migrace databáze probíhá simultánně s během původní repliky (která v té době stále odbavuje requesty) - je třeba s tím počítat (běžně nenasazujeme nové verze za ostrého provozu a je úplně ok říct, že starší verze bude chvíli padat - když to nic nerozbije a pak se to dá samo do pořádku. Pokud jsou repliky zakázané, tak se nejdříve původní verze služby ukončí a uživatel / volající služba dostává chybu o nedostupnosti - výsledek je tedy stejný).

Pozor na to, že se původní služba může v průběhu nasazování nové verze restartovat a začne probíhat i starší migrace.

Migrace databaze probíhá při nasazení ve více replikách zároveň. Je třeba řešit zámek migrace nebo něco podobného, aby nedocházelo k race condition nebo dokonce k deadlocku.

Nelze zaručit, že velmi malá část requestů neproběhne na staré a nové verzi zároveň (retry mechanismus).

Tip

Lze doporučit některé postupy a praktiky:

Služba nesmí držet lokální stav (in-memory session). Jakýkoliv stav musí být v externí cache (Redis) nebo v DB, jinak load balancer při přepnutí replik způsobí nekonzistenci.

Migrace DB schématu musí být vždy zpětně kompatibilní.

Využívejte idempotenci — opakování požadavku nemusí být chybou, např. pokus o smazání již smazaného záznamu není status 400, ale 200 - OK.

U asynchronních zpráv lze také některé problémy vyřešit s vědomím toho, že Dapr bude odmítnutou zprávu opakovat. Pokud k vám dorazí dvě zprávy, jedna na založení rodičovského záznamu a jedna na založení podřízeného záznamu a zpráva o podřízeném záznamu se vyhodnotí dřív než zpráva o rodiči, pak lze správným HTTP statusem docílit toho, že se zpráva bude opakovat, a napodruhé už projde, protože rodič bude mezitím založen.

Zde je přehled HTTP statusů a jejich významu pro opakování zprávy.

Pochopitelně je mnoho souvisejících problémů možné vyřešit správně navrženým API s vhodnými atomickými metodami.

A další častou praktikou je, že primární klíč přiděluje volající klient, nikoliv server. Opakovaný "create" tedy nevytvoří nový záznam. UUID, nebo na SISTA používané Nano ID, je vhodným kandidátem.

4.4. Pravidla nasazování

Při nasazování služeb SISTA platí následující základní pravidla:

  1. Dev tým zodpovídá za nasazování služby. Ops tým pak za přípravu a údržbu prostředí, do něhož nasazování probíhá.

  2. Dev týmy jsou společně zodpovědné za návrat k předchozí verzi služby, pokud je to z jakýchkoli důvodů nutné.

  3. Ops tým je zodpovědný za určení minimálních požadavků na kontejnerizaci. Dev tým je zodpovědný za dodržení požadavků na docker image:

    • Schopnost běžet ve více instancích najednou (horizontální škálování, bezvýpadkové nasazení, hot-swap apod.),

    • podpora pro non-root běh,

    • konfigurační soubory, certifikáty, tajemství ad. citlivé informace se do image musí předat zvenku,

    • rozlišení stavových a bezstavových komponent,

    • každá komponenta implementuje sémanticky správné kontrolní API.

  4. Dev a ops tým jsou zodpovědné za správné nastavení zdrojů jednotlivým kontejnerům.

  5. Ops tým zodpovídá za integraci s ostatními službami. Dev tým za přípravu a implementaci integračních testů podle povahy integrace.

4.5. Provisioning prostředí

Při provozování prostředí platí následující základní pravidla:

  1. Dev tým musí zajistit takové vlastnosti vyvíjené služby, aby její spouštění, provoz a zastavení bylo možné realizovat prostředky infrastracture-as-code (např. Terraform, CloudFormation apod.).

  2. Pravidla pro provisioning jsou zodpovědností dev týmu, dodavatel ve spolupráci s TA ČR musí zajistit, aby se tato pravidla automaticky projevila v příslušném prostředí; pokud je to nutné, mohou být definována další pravidla (např. ověření pravidel ops týmem v STAGING prostředí).

  3. Všechna pravidla, konfigurace a související údaje (s výjimkou tajemství) musí být uložena v gitu a patřičně verzována. Ops tým k nim musí mít přístup.

  4. Dev tým musí zveřejnit všechny artefakty, které se účastní produkčního provozu, ve sdíleném oficiálním repozitáři TA ČR. Za ideální se považuje stav, kdy je možné všechny potřebné artefakty sestavit ze zdrojových kódů svého druhu.

  5. Kde je to nutné, dodavatel musí ve spolupráci s TA ČR zajistit, příp. revidovat pravidla škálování (např. automatické operátory), schéma distribuce událostí (např. notifikace, alerty), kvóty a limity (např. CPU, RAM, budget alert) atd.

  6. Komunikační a eskalační schéma využívá tři kanály:

    1. Google Chat Kubernetizace SISTA (dodavatel hlásí ops týmu, kteří vývojáři mají mít do chatu přístup),

    2. generickou e-mailovou adresu [email protected],

    3. issue tracker v Gitlabu – na každý zjištěný incident má vzniknout nové issue s popisem problému, issue může založit kdokoli z kteréhokoli týmu,

    4. také je možné ve sdíleném kalendáři vidět, kdo z ops týmu má daný den službu a kontaktovat ho přímo,

    5. dále existují další pomocné kanály v prostředí Google Chat (např. Programování SISTA) – ops tým na žádost dodavatele přidá vývojáře do toho či dalších existujících kanálů.

  7. Dev tým by měl vhodným návrhem minimalizovat rizika, tvořená potenciálními chybami členů ops týmu (robustnost).

  8. Dev tým by měl ve spolupráci s ops týmem definovat vhodnou strategii vytváření snapshotů a záloh podle potřeb vyvíjené služby a dle vyžadované dostupnosti atp.

  9. Dev tým má navrhovat změny uspořádání prostředí, pokud se např. opakovaně ukáže nevhodnost používaných postupů ve vztahu k dané službě.

  10. Pro sledování požadavků (trasování) se využije zpracování synchronní komunikace prostřednictvím Dapr sidecar. Všechny služby musejí v deployment.yaml mít veškeré URL cizích služeb, pokud je volají napřímo.

4.6. Monitoring

Pro monitoring služeb platí následující základní pravidla:

  1. Dev tým je zodpovědný za to, že jím vyvíjená služba korektně reportuje svůj stav, definované metriky a/nebo incidenty (bezpečnostní, výkonové ad.) do sdíleného dashboardu service desku.

  2. Dev tým je zodpovědný za to, že zaznamenání incidentů obsahuje údaje, potřebné k řešení incidentu a/nebo nalezení příčiny nestandardní situace viz Logování výše.

  3. Dev tým je zodpovědný za včasné reakce na zaznamenané incidenty dle jejich závažnosti a ve lhůtách stanovených smluvními vztahy.

  4. Dev i ops tým musí mít přístup k logům produkčního prostředí.

  5. Dev a ops týmy jsou zodpovědné za vhodné nastavení sledování metrik, příp. jejich napojení do sdíleného dashboardu service desku. Použité metriky by měly být kombinací alespoň dvou typů (podle typu služby může být vhodná kombinace různá):

    • základní metriky na HW úrovni – CPU, využitá RAM, provoz na síťovém rozhraní apod.

    • Kubernetes metriky týkající se jednotlivých podů,

    • metriky operačního systému – load, volná paměť, velikost swapu apod.,

    • aplikační metriky – vlastní implementace, standardizované metriky JVM – počet vláken, činnost GC, otevřené sockety apod.

  6. Dev tým musí implementovat příslušné aplikační metriky, jsou-li dohodnuty. Pokud jsou určeny hladiny závažnosti incidentů (např. překročení dané metriky v pásmech), musí dev tým zajistit publikaci incidentů do sdíleného dashboardu service desku viz výše Logování.

  7. Kde je to nutné, dev tým musí TA ČR poskytnout součinnost při řešení nestandardních situací ohledně výkonu a stability.

4.7. Přenos dat mezi prostředími

Pro vývoj, ladění a řešení problémů může být potřeba přenášet data mezi běhovými prostředími (nejspíš mezi PRODUCTION a STAGING).

Important
Doporučení

  • Kde je to možné a z hlediska byznysové funkce služby vhodné, měly by být potřebné popisy a/nebo definice součástí repozitáře se zdrojovými kódy.

  • Pokud služba využívá popisy a/nebo definice, uložené mimo repozitář se zdrojovými kódy, měl by dev tým zvážit implementaci nástroje pro přenos dat s následujícími vlastnostmi:

    • filtrování dat k přenosu (např. pouze data konkrétního resortu, časově omezená apod.),

    • přenos vč. potřebných vazeb mezi datovými entitami,

    • možnost anonymizace vybraných údajů (osobní údaje, finanční částky, projektová data atp.).

  • Doporučuje se textový výměnný formát (typu SQL, CSV nebo JSON), který umožní další případné úpravy standardními nástroji pro zpracování dat.

  • V rámci vývoje SISTA vznikl nástroj krmič (configurer), jehož využití se preferuje. Popis použití se nachází v dokumentaci, k použití je nutné znát API klíč příslušného TRSu v daném běhovém prostředí.

4.8. Logování

Logování normálního i mimořádného průběhu akcí a sběr telemetrie služeb je základním předpokladem úspěšného řešení problémů v provozu SISTA. Zde se předpokládá, že samotný proces logování probíhá dle doporučených postupů daných zvolenou technologií, programovacím jazykem a/nebo použitým frameworkem. Správu logů zajišťuje platforma Google Cloud.

Pro logování platí následující základní pravidla:

  1. Dev tým musí implementovat následující pravidla logování:

    • Úrovně logování (severity) kopírují [GCP], pPro potřeby SISTA se používá 5 úrovní:

      • DEBUG – detailní úroveň logování, která nemůže být trvale zapnutá z výkonových či finančních důvodů; př. = detailní transakční metadata, trasovací údaje,

      • INFO – detailní úroveň logování, která může být trvale zapnutá; př. = provozní informace o transakcích,

      • WARNING – chyby, z nichž je možné se zotavit bez zásahu operátora; př. = chybná uživatelská data,

      • ERROR – chyby, z nichž není možné se zotavit bez zásahu operátora; potenciální zdroj automatizovaného alertu; př. = chybějící konfigurace,

      • CRITICAL – chyby, které mohou způsobit výpadek části nebo celého systémy SISTA; př. = neběžící kriticky důležitá komponenta systému,

    • Technická metadata dle struktury níže.

  2. Úroveň logování musí být možné řídit (výchozí nastavení = INFO, na požadavek lze zvýšit na DEBUG) proměnnou prostředí LOG_LEVEL. Úroveň logování se načítá při startu. Pro produkční prostředí je doporučená výchozí hodnota INFO, pro vývojové / testovací prostředí hodnota DEBUG.

  3. Dev tým loguje strukturovaně dle doporučení [GCP] ve formátu JSON. Názvy polí musí obsahovat (bez použití prefixu logging.googleapis.com/):

    • request ID požadavku – best effort, tj. tam, kde je možné requestId / transactionId získat / použít, jej aplikace má zalogovat,

    • namespace = systémová identifikace služby – povinný,

    • síťová identifikace původce clientIP – best effort, viz níže,

    • timestamp - časová značka ve formátu ISO 8601 v jednotné časové zóně:

      • dev tým by neměl spoléhat na vlastnosti logovací infrastruktury, ale měl by zaznamenávat skutečný čas události v okamžiku zachycení,

      • upřesnění vyžadovaného formátu: YYYY-MM-DDThh:mm:ss.ssZ;

    • severity dle definice výše - povinná,

    • message - vlastní obsah logu = popis zaznamenané akce či události v angličtině (minimálně message, příp. cokoliv dalšího, co daný dodavatel potřebuje),

    • traceId = identifikátor, který umožní trasovat požadavky napříč aplikacemi, viz níže,

    • spanId = identifikátor konkrétního volání, viz níže,

    • isAudit - nepovinný, viz níže,

    • errorId - nepovinné, viz [Chyby a výjimky].

Pole Kde ho vzít

clientIP

Pokud službu volá jiný TRS, nebo volání prochází přes proxy server(y), může aplikace použíta nejstarší (= nejvíce vpravo) hodnotu adresy (for =) z HTTP hlavičky Forwarded, příp. X-Forwarded-For, viz [XFF].

traceId

Hodnota převzatá z HTTP hlavičky traceparent, viz níže

spanId

Hodnota převzatá z HTTP hlavičky traceparent (= parent-id), viz níže

  1. Dev tým zodpovídá za to, že záznamy v logu nikdy nebudou obsahovat:

    • osobní údaje jiné než určené k logování (bezvýznamový identifikátor, displayName apod.),

    • tajemství či připojovací řetězce, hesla či tokeny atd.,

    • příliš dat, která by mohla zahltit log.

  2. Auditní logy se označují atributem isAudit. Pro obsah auditních logů platí stejná pravidla jako výše (povinné vlastnosti, nepovolené údaje). Příznak auditního logu je možné kombinovat s úrovní logování pod úrovní DEBUG (platforma je může ignorovat – „auditní log? ⇒ LOG_LEVEL INFO a výše“).

  3. Dev tým je zodpovědný za smysluplné přiřazení úrovně logů k událostem v reálném světě; uživatelská chyba na vstupu neodpovídá úrovni ERROR v PRODUCTION prostředí..

  4. Dev tým je zodpovědný za přiměřenou četnost výskytu logovacích záznamů, aby nedošlo k zahlcení logu.

  5. Pokud záznam loguje interní strukturu (př. = stack trace zachycené výjimky), strukturované informace musejí být sbalené v datové struktuře jednoho záznamu a to ve formátu JSON.

  6. Trasování průchodu aplikací (volání TRSů mezi sebou) pomocí identifikátoru traceId musí být možné vypnout / zapnout nastavením proměnné prostředí TRACING. Povolené hodnoty jsou (case insensitive) ON, 1, TRUE, AUTO s významem ‚trasování zapnuto‘, OFF, 0, FALSE s významem ‚trasování vypnuto‘.

  7. Pro trasování průchodu a další telemetrii se používá standard W3C Trace Context, viz [TRCTX], konkrétně údaje předávané v HTTP hlavičce traceparent. Aplikace musí převzít hodnotu parametru trace-id, pokud je ve volání dostupná, a použít ji při logování dle požadavků výše. Při případném volání dalšího TRSu musí aplikace použít hodnotu trace-id ve vlastní hlavičce traceparent, aby bylo možné další požadavky dotrasovat.

  8. V případě, že přišel požadavek bez hlavičky traceparent, nebo aplikace iniciuje komunikaci s jiným TRSem, musí aplikace identifikátor trace-id vytvořit dle pravidel [TRCTX]. Pokud aplikace komunikuje s jiným TRSem, musí pro dané volání vytvořit vlastní spanId a uložit je do pole parent-id v hlavičce traceparent.

4.9. Zálohování a disaster recovery

Při zálohování platí následující základní pravidla:

  1. Dev tým je zodpovědný za určení, co je nutné zálohovat a jak. Pozor: pokud zálohy obsahují osobní data (i v binární podobě), vztahují se i na ně požadavky GDPR.

  2. Dev a ops tým jsou společně zodpovědné za aktivní zálohování PRODUCTION prostředí a zajištění bezpečnosti a souvisejících požadavků na záložní soubory.

  3. Způsob zálohování: pokud to lze, doporučujeme využít vlastní zálohovací mechanismus dané technologie. V cloudu doporučujeme využít mechanismus snapshotů a jejich pravidelné rotace. Dev a ops tým jsou zodpovědné za určení schématu takových záloh.

  4. Dev tým musí definovat postup obnovení ze záloh. Pokud se pro jednotlivé použité součásti služby postup liší, musí být zdokumentován postup pro každou součást zvlášť.

  5. Pokud obnovení ze záloh vyžaduje zadání některých parametrů (př.: název databáze, URL apod.), musí být všechny tyto parametry zdokumentovány a vysvětleny.

Important
Doporučení

  • Ops tým by měl mít možnost na základě např. crash alertu dočasně vypnout rotaci záloh, aby potenciálně poškozené soubory nezničily použitelné zálohy.

  • Anonymizovaná data pro automatizované testy doporučujeme zálohovat odděleně.

  • Ops tým by měl zajistit nezávislou zálohu gitu a obdobných repozitářů, příp. další vhodné zdroje záloh.

4.10. Řízení přístupu a tajemství – Secrets management

Řízení přístupu k jednotlivým službám smí být umožněno pouze oprávněným uživatelům a/nebo správcům a autorizovaným ostatním službám SISTA.

Pro řízení přístupu platí následující základní pravidla:

  1. Dev tým je zodpovědný za implementaci zajištění, aby uživatelé bez A&A a/nebo službu a služby bez autorizace nemohly neoprávněným způsobem přistupovat k datům. Ops tým je zodpovědný za spolupráci při výběru a definici vhodného způsobu takového zajištění.

  2. Osobní data smějí být uložena pouze v IdM / RO. Dev tým je zodpovědný za implementaci vhodných postupů pro minimalizaci rizika úniku těchto citlivých údajů prostřednictvím dané služby.

  3. Dev tým je zodpovědný za uložení certifikátů, hesel a tajemství v chráněném úložišti GCP Secret Manager. Ve spolupráci s ops jsou oba týmy zodpovědné za zajištění, že se tyto citlivé údaje mimo chráněné úložiště nenacházejí.

  4. Dev tým dokumentuje, jaká tajemství jsou potřebná k provozu služby a jakým způsobem se získávají (př. = předání přes environmentální proměnné atp.). Způsob získávání tajemství je popsán v návodu [HOWTO Platform] v sekci Popis souborů platformy (deployment.yaml) a v sekci Secrets management.

5. Release notes dokumentu

Verze: 1.5.
Datum vydání: 26. 5. 2026.
Autor: Tomáš Zvěřina, David Ondřich (fnx.io), [email protected].
Poznámka k verzi: Reorganizace

Detailní popis změn:

  • Verze předložená k akceptačnímu řízení MT026.

  • Další popis bude doplněn k další verzi.

  • Aktualizovaná verze, zahrnující doporučení minitendru pro data governance (MT039).

  • Aktualizovaná verze, zahrnující doporučení minitendru pro tvorbu frontendu (MT032).

  • Doplněná chybová struktura.

  • Opravy, sdílené výjimky, logování, verzování FE.

  • Doplněné požadavky na logování, trasování, secrets mgmt.

  • Doplnění dle výstupů release managementu (MT065).

  • Zestručnění a revize pravidel dle aktuálního stavu projektu.

  • Upřesnění terminologie, přesun repozitářů do Gitlabu, sanity check.

  • Upřesnění mikroservisní architektury, popis release notes / changelogu, přesun šablon dokumentace, fulltext.

  • Upřesnění terminologie, přesun repozitářů do Gitlabu, sanity check.

  • Doplnění požadavků na multitenantnost.

  • Reorganizace, odstranění zastaralých sekcí, lepší defince "scope" dokumentu

Termíny a definice

A&A

Autentizace a autorizace.

API

Programové aplikační rozhraní; zde synonymum pro REST API.

Artefakt

Vývojový artefakt = hotový výstup nebo pracovní mezičlánek, zpravidla binární, výsledek strojového zpracování lidsky čitelného předpisu (zdrojových kódů, konfigurace); př. docker image.

CI/CD

Continous Integration / Continous Delivery = způsob průběžné kompilace, testování a nasazení po změnách uložených do verzovacího systému.

Datová položka

Záznam v datovém slovníku, popisující reálně používanou datovou entitu a/nebo strukturu, viz analytickou zprávu [MT039].

Datový slovník

Data Dictionary, souborný přehled popisu reprezentace a správného použití definovaných datových entit, viz analytickou zprávu [MT039].

(Obecný, jednoduchý, složený) datový typ, technická položka

Metodologie data governance definuje několik datových typů: obecný datový typ, jednoduchý datový typ, složený datový typ; smyslem je umožnit kompozici datových typů do potřebných struktur, odrážejících reálné potřeby. Technické položky představují typ atributů, které nemají vztah k reálným datovým entitám, ale mohou být důležité např. pro filtrování, parametrizaci apod. Všechny typy jsou definované v kap. 2.1.2. Datový slovník analytické zprávy [MT039].

DevOps

Složenina anglických výrazů Development a Operations. Je to přístup k vývoji software, který zdůrazňuje komunikaci, spolupráci a integraci mezi vývojářem a odborníky na informační technologie z provozu.

Dev tým

Tým vývojářů, inženýrů, testerů a dalších potřebných rolí dodavatele.

Etalon

Referenční definici datové entity, viz analytickou zprávu [MT039].

FE

Frontend, minifrontend; uživatelské rozhraní, viz analytickou zprávu [MT032].

Git

Doporučený distribuovaný verzovací systém; též repozitář.

IdM / RO

Identity Management / rejstřík osob; jednak ze základních služeb SISTA.

Image, kontejner

V tomto dokumentu synonymum pro docker image = zabalená aplikace (nebo její část), připravená k nasazení v cloudu.

Ops tým

Tým vývojářů, správců, testerů a poučených uživatelů TA ČR.

Slovník pojmů

Business Glossary, souborný přehled pojmů používaných v jednotlivých procesech pro datové entity, viz analytickou zprávu [MT039].

SPA

Single Page Application; samostatná jednostránková webová aplikace.

UI

Uživatelské rozhraní; v tomto dokumentu se tím rozumí uživatelské rozhraní pro koncové uživatele SISTA, není-li jmenovitě určeno jinak.

UX

User experience, proces návrhu produktu; v tomto dokumentu se tím myslí informační architektura, návrh průchodů uživatele SISTou a grafický a aplikační design.

Odkazy a zdroje

Vnitřní předpisy a dokumenty
Internetové zdroje

Rejstřík

Příloha A: Checklist služby SISTA

V tomto přehledu najdete základní body, které byste měli ve vaší službě zohlednit. Nejedná se o přehled vyčerpávající, závazné zadání vždy stanovuje minitender a jeho backlog.

A.1. Vývoj a architektura

  • ❏ Frontend je React/TypeScript aplikace využívající Dista a FE Commons, která vizuálně odpovídá návrhu ve Figma/Balsamiqu.

  • ❏ Sdílené vizuální prvky jsou vystavené jako federované komponenty.

  • ❏ Pro identifikaci cizích entit se používá SISTA URN a pro jejich vizualizaci komponenta SistaChip.

  • ❏ Pro popis širšího kontextu záznamů se používá koncept "SISTA kontext".

  • ❏ Pro čtení dat z cizích služeb se využívá synchronní komunikace 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 se využívá asynchronní komunikace přes asynchronní Dapr.

  • ❏ Pro odesílání Dapr Pub/Sub zpráv se používá transakční outbox.

  • ❏ Endpointy, na které jsou doručovány Dapr Pub/Sub zprávy, implementují idempotenci.

  • ❏ Služba je implementována do kontextu superflows, správně komunikuje s okolními TRSy a nastavuje příslušné stavy projektu (stav, podstav, příp. flag).

  • ❏ Definice workflow odpovídají procesům v modelu Archimate v dokumentaci SISTA.

  • ❏ Zdrojové kódy jsou komentované na úrovni tříd a metod.

  • ❏ Ve službě Správa textů jsou doplněny všechny textace ke klíčům využitým ve službě.

  • ❏ Správně se používají existující průřezové služby:

    • Přehled a stav projektů – project-skeleton

    • Přihlášený uživatel a jeho aktivní profil – idm

    • Oprávnění a vazby uživatele/entit – 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

    • …​ a využívají se také federované UI komponenty, které služby poskytují ve svých (*-ui) repozitářích

A.2. Dokumentace a katalogy

  • ❏ Existuje technická dokumentace služby (HOWTO adoc, popis v Backstage) obsahující seznam všech konfiguračních souborů a komplexní příklady konfigurace.

  • ❏ Existuje uživatelská dokumentace podle aktuální kostry (obsahuje soupis rolí, oprávnění a přehled funkcionalit).

  • ❏ Existují Release Notes – každá master verze služby má krátký popis změn.

  • ❏ Aplikace má v Katalogu služeb správně vyplněné odkazy (Links) a vazby na ostatní služby (Relations).

  • ❏ Publikovaná API jsou dostupná z Katalogu služeb, mají OpenAPI specifikaci a soubor api.yml má vyplněné popisy (descriptions).

  • ❏ Etalony jsou zaneseny v datovém katalogu; analytické oddělení potvrdilo jejich formální správnost a naplnění požadavků data governance.

A.3. Testování a bezpečnost

  • ❏ Existují testovací scénáře pro funkční testy od dodavatele služby.

  • ❏ Existují testovací scénáře pro akceptační testování vytvořené garantem služby (včetně ověření funkčnosti pro jiné poskytovatele).

  • ❏ Existují API testy vytvořené dodavatelem, které pokrývají všechny klíčové API všech služeb daného TRSu.

  • ❏ Pokud je to pro službu relevantní, existují výsledky odolnosti vůči očekávanému reálnému a nadhodnocenému provozu.

  • ❏ Služba byla prověřena vůči bezpečnostním hrozbám a nebyla nalezena žádná závažná zranitelnost.

A.4. Provoz a deployment

  • ❏ Služba je v Git repozitáři TA ČR, pipeline ji dokáží sestavit, otestovat a nasadit do SISTA prostředí.

  • ❏ Služba je spustitelná a stabilně běží na požadovaném clusteru, minimálně v prostředí STAG.

  • ❏ Služba je připravena na běh a škálování ve více replikách.

  • ❏ Konfigurační parametry deploymentu jsou uloženy mimo zdrojové kódy.

  • ❏ Služba loguje ve formátu JSON dle pravidel vývoje.