Specifikace požadavků¶

---

Minimální požadavky¶

• Implementace datových pump
  • Aplikace musí obsahovat datové pumpy pro minimálně dva různé ALM nástroje, a to dle následujícího pořadí priorit:
    1. Jira + Git
    2. GitHub
    3. Redmine + GitLab
    4. Další ALM nástroje
  • Pokud pumpa potřebuje stáhnout repozitář lokálně, po dokončení dolování by se měl smazat.
  • Pumpa pro GitHub může být realizována spuštěním pumpy pro Git s následným doplněním potřebných dat.
  • Pumpy by měly umožňovat zakomponovat různé project_instance (Redmine, GitLab) do již vydolovaného projektu
    • Tím se rozšíří sada lidí a identit (buďto se identity přiřadí k již existujícím lidem z vydolovaného project_instance, nebo se vytvoří nové)
    • Dále to umožní propojení mezi ticketama a commity.
    • Při přidávání nové instance projektu je nutné identifikovat propojující dotazy a propojit je se stávajícími daty.
      • Nutné projet všechny commit messages již uložených instancí -> nutné udělat manuálně zpětně
      • Při spojování 4 ALM dohromady, u přidávání posledního se projdou commit messages všech 3 předchozích
    • např. Git nepodporuje zmiňování commitů mezi sebou, GitHub ano.
  • Kvalitní implementace pump pro snadné rozšíření o další ALM nástroje.
    • Vysoká úroveň abstrakce + využití rozhraní.
  • Všechny části kódu musí být zdokumentovány (ekvivalent JavaDoc) v anglickém jazyce.

• Mapování dat do systému SPADe
  • Data budou přenášena do databáze SPADe na základě definice poskytnuté zadavatelem.
    • Tabulky databáze není možné jakkoliv upravovat.
  • Systém musí umět řešit možné kolize mapování sloupců mezi různými ALM nástroji.
    • U nástrojů jako Git a GitHub může docházet k rozdílům v interpretaci tagů a release, přičemž ve SPADe ne každý tag nutně znamená release.
    • V těchto případech se použijí defaultní hodnoty dle uvážení vývojového týmu.
  • Systém bude umožňovat sloučení více identit uživatele do jednoho člověka.

• Grafické uživatelské rozhraní (GUI)
  • GUI umožní uživateli specifikovat repozitář a další parametry pro dolování dat z ALM nástrojů.
  • Autentizace a autorizace pro dolování soukromých projektů (přihlašovací formulář nebo API klíč).
    • Údaje budou patřičně zabezpečeny.
  • Uživatel bude průběžně informován o stavu dolování dat, GUI nesmí "zamrznout".
    • V ideálním případě by se měl zobrazit zbývající čas těžení (zatím není zcela jasné, jak se určí).
  • Při probíhajícím těžení se zakáže pumpování dalšího projektu, tj. pumpy nemusí umět pracovat paralelně, pouze sekvenčně.
  • GUI bude napsáno v angličtině.
  • Před těžením se GUI zeptá, jestli bude těžit nový projekt nebo jestli bude přidávat data do existujícího projektu
    • Implementace přes CheckBox (chci/nechci přidávat do exitujícího) + SelectBox (když chci, do jakého konkrétně)

• Další požadavky na GUI (nepovinné)
  • Uživatel bude mít možnost přepnout jazyk do češtiny.
  • V GUI bude možné zadat frontu repozitářů k sekvenčnímu dolování.
  • Při zadání URL root se zobrazí všechny projekty, které lze těžit.
    • Např. když url/projects obsahuje projekty url/projects/aswi2024 a url/projects/aswi2025, GUI nabídne těžení aswi2024 a aswi2025

• Pseudonymizace citlivých údajů
  • Aplikace bude umožňovat uložení citlivých údajů do databáze pod pseudonimizovaným názvem podle přepisovací tabulky.
  • Mezi citlivé údaje patří:
    • Název projektu
    • Popisky ticketů
    • Autoři
    • Commit messages
    • Názvy artefaktů
    • Obsah artefaktů (pouze plaintext, ne PDF/Word)
  • Aplikace na vyžádání vygeneruje přepisovací tabulku, která mapuje pseudonymizované texty na skutečné.
    • Tabulka bude ve formátu XML nebo JSON.
    • Podle této tabulky bude možné převést pseudonymizovaná data zpět do jejich původní podoby
    • Dotahování nových dat musí s tabulkou také umět pracovat (např. přidání nového uživatele)
  • Na konci těžícího procesu si uživatel bude moci vybrat, jestli data (a které konkrétně) chce pseudonimizovat
  • Pro analýzy anti-patternů je u artefaktů důležité uchovat informaci o počtu znaků.
    • V databázi není možné nahradit celý plaintext jedním číslem značící počet znaků.
    • Místo konkrétního plaintextu může být do databáze uložen stejně dlouhý dummy text (Lorem Ipsum).
    • Nutné důkladněji promyslet, současná databáze na pseudonimizaci obsahu artefaktů není stavěná.

• Uživatelsky mapovaná data
  • Uživatel bude mít možnost změnit defaultní mapování údajů v MySQL databázi.
  • Místo dolování všech dat projektu z ALM si bude moci uživatel zvolit libovolnou podmnožinu sloupců k dolování (např. pouze commity, commity + issues, main branch).
    • GUI by mělo obsahovat několik scénářů, podle kterých by uživatel mohl chtít dolovat data.
  • Uživatel bude moci specifikovat časové období, ze kterého chce data dolovat.
    • Uživatel bude moci zvolit časové rozmezí na úrovni dnů, hodin a minut.
    • Den bude povinný, hodiny a minuty nebudou povinné.
    • Validní formáty:
      • Od 19.2.2025 do 11.3.2025
      • Od 19.2.2025 15:35 do 11.3.2025 10:40
    • Pokud uživatel specifikuje pouze dny a v ALM bude několik záznamů k dolování, dolovat se bude vždy od nejstaršího záznamu (počátek) až po nejnovější záznam (konec).
  • Další rozšíření bude umožňovat dolování dat od posledního data pumpování a od konkrétního milníku (např. release).

• CICD nasazení
  • Pumpy by měly být snadno nasaditelné s využitím CICD na GitLab.
  • Měla by být možnost připojení na vlastní reálnou databázi, nebo na databázi běžící v Dockeru.
    • Na tuto reálnou databázi se následně mohou napojit i jiné nastroje

Mimofunkční požadavky¶

• Architektura projektu
  • Datové pumpy a GUI budou navrženy tak, aby je bylo možné implementovat nezávisle na sobě.
    • Mezi pumpami a GUI bude využito API.
    • Technologie pro backend a frontend jsou volitelné, přičemž po domluvě se použije SpringBoot pro backend a React pro frontend.
  • Systém musí používat databázi MySQL.
  • Pro snadnou přenositelnost projektu je vhodné využít kontejnerizaci (Docker nebo Podman).
    • Cílové prostředí není specifikováno.
    • Možnosti nasazení zahrnují lokální spuštění nebo server na CIV.
  • Projekt se bude skládat z následujících částí:
    

• Testování
  • Testování bude primárně zaměřeno na funkčnost datových pump a GUI bude testováno pouze okrajově.
  • Zatím není blíže specifikováno, co a jak konkrétně bude třeba testovat.
  • Druhy testů:
    • Jednotkové
    • End-to-End
    • Integrační
• Kód bude testován staticky přes CICD pipeline na GitLab

• Dokumentace
  • Nedílnou součástí projektu je dokumentace, která bude zahrnovat následující dokumenty:
    1. Programátorská dokumentace (popis kódu, architektura, možnosti rozšíření)
    2. Instalační manuál včetně nastavení prostředí (Docker, MySQL)
    3. Uživatelský manuál (popis práce s pumpami, vysvětlení GUI)
    4. Use case návody (konkrétní scénáře použití aplikace)
    5. README na repozitáři GitLab (základní informace o projektu)
  • Všechny zmíněné dokumenty budou psány v anglickém jazyce, protože se jedná o školní projekt s využitím na mezinárodní úrovni.

• Optimalizace rychlosti těžení
  • V kódu by měla být snaha optimalizovat rychlost těžení.
  • Na datové pumpy nejsou kladeny konkrétní požadavky na maximální dobu těžení.
    • Hlavně z toho důvodu, že velikost a složitost dolovaných dat může být libovolná.

Use cases (TODO)¶

• UC1 Dolování dat z konkrétního ALM nástroje
  • Na základě uživatelovo definice se provede dolování dat z vybraného ALM nástroje (např. Git, Jira, GitHub).
• UC2 Hard delete
  • Smaže projekt z databáze včetně všech jeho náležitostí (veškerá data a metadata spojená s projektem budou trvale odstraněna).
• UC3 Soft delete
  • Smaže projekt z databáze s uchováním některých metadat (např. URL), která mohou sloužit pro případnou obnovu projektu.
• UC4 Opětovné těžení smazaného projektu (platí pouze pro soft delete)
  • Tato možnost je dostupná pouze pro soft delete. Pokud byl projekt smazán pouze částečně, bude možné opětovně provést dolování dat a obnovit projekt s jeho aktuálními údaji.
• UC5 Nahrání změn v projektu
  • Aktualizuje stávající záznamy v databázi podle nových dat.
  • Bude provedena aktualizace existujících záznamů a zároveň se přidají nové záznamy a odstraní se ty, které již neexistují.
• UC6 Uživatelské mapování
  • Uživatel si bude moci přes GUI zvolit, jak mapovat nejednoznačné sloupce do SPADe databáze (tag se může namapovat na tag/release)
• UC7 Pseudonimizace dat
  • Jaká políčka podporují pseudonimizaci, jak se vytváří přepisovací tabulka, jak je to zapojené do GUI, ...

---

Autor: Štěpán Faragula
Datum: 1.4.2025
Stav: aktualizováno podle poslední schůzky se zadavatelem