aloitus dokumentaatio

2026-06-08 06:04:49 +03:00
parent 92479ebb9c
commit 66e1c98a8c
9 changed files with 1547 additions and 0 deletions
@@ -0,0 +1,142 @@
+# Vaatimukset — Gitea Actions CI -kirjasto
+
+> Funktionaaliset vaatimukset käyttäjän näkökulmasta. Muoto: käyttötapaukset (use cases).
+>
+> Linkittyy: [design-rationale.md](design-rationale.md), [architecture.md](architecture.md), [report-hosting.md](report-hosting.md)
+
+---
+
+## UC1: Kehittäjä näkee commitin build-statuksen
+
+**Actor:** Kehittäjä
+**Precondition:** Workflow on käynnissä tai päättynyt
+
+**Main success:**
+- Kehittäjä avaa commitin Giteassa
+- Näkee statusviestit: "Building...", "Unit tests OK", "Docker build OK", "Docker pushed"
+- Jokainen statusviesti on klikattavissa → vie buildin sivuun tai raporttiin
+- Epäonnistunut steppi näkyy punaisella — kehittäjä klikkaa ja näkee mikä meni vikaan
+
+**Poikkeukset:**
+- Statusviesti puuttuu (workflow kaatui ennen raportointia) → commitissa näkyy timeout/error
+- Useampi workflow samalle commitille → statukset erottuvat `key`-arvolla
+
+---
+
+## UC2: Kehittäjä lukee testiraportteja selaimessa
+
+**Actor:** Kehittäjä
+**Precondition:** Build on valmistunut, raportit pushattu Minioon
+
+**Main success:**
+- Kehittäjä klikkaa commitin statusviestin URL:ää ("Unit tests OK" → URL)
+- Selain avautuu, OIDC-kirjautuminen (Gitea-tunnuksilla)
+- Cucumber-raportti renderöityy HTML:nä selaimessa
+- Raportissa näkyy: mitkä testit menivät läpi, mitkä epäonnistuivat, stack tracet
+- Yläreunassa linkki "← Back to build" → palaa buildin raportti-indeksiin
+
+**Poikkeukset:**
+- Raporttia ei ole (testit skipattiin, workflow kaatui ennen pushausta) → 404
+- OIDC-sessio vanhentunut → uudelleenohjaus kirjautumiseen
+
+---
+
+## UC3: Kehittäjä selaa projektin build-historiaa
+
+**Actor:** Kehittäjä
+**Precondition:** Projektilla on vähintään yksi build
+
+**Main success:**
+- Kehittäjä menee `{MINIO_BASE}/{repo_slug}/index.html`
+- Näkee listan kaikista buildeista aikajärjestyksessä (uusin ensin)
+- Jokaisella buildilla: commitin 8-merkkinen hash, päivämäärä, branch, status (✅/❌)
+- Klikkaa buildia → siirtyy `{commit_short}/index.html` — buildin raporttilistaukseen
+- Buildin sivulla: lista kaikista raporteista (Cucumber, JaCoCo, Maven Site) linkkeinä
+- "← Back to builds" → palaa projektin build-indeksiin
+
+**Poikkeukset:**
+- Projekti poistettu / siivottu retention policyn mukaan → 404
+- Indeksitiedosto puuttuu (ensimmäinen build kesken) → 404, generoituu seuraavalla pushauksella
+
+---
+
+## UC4: Kehittäjä jäljittää kontin koko ketjun commitista
+
+**Actor:** Kehittäjä
+**Precondition:** Mikropalvelun commitista on ajettu vähintään deployment
+
+**Main success:**
+- Kehittäjä avaa mikropalvelun commitin abc123
+- Näkee statusviestit: "Build OK", "Deployed to staging → def456", "Integration tests OK → ghi789"
+- Klikkaa "Deployed to staging → def456" → siirtyy Helm-repon committiin def456
+- Helm-repon commitissa näkyy: "from abc123", "tested v1.2.3", "tested abc123"
+- Klikkaa "tested abc123" → palaa mikropalvelun committiin
+- Koko ketju on navigoitavissa edestakaisin commit-statuslinkkien kautta
+
+**Poikkeukset:**
+- Välivaiheen commit siivottu → statusviesti jää, mutta linkki vie 404:ään
+- Deploytty versio ei vastaa odotettua → statusviestissä näkyy ristiriita
+
+---
+
+## UC5: Kehittäjä näkee deployatun version ympäristössä
+
+**Actor:** Kehittäjä
+**Precondition:** Deployment on suoritettu, Helm-repon commit tehty
+
+**Main success:**
+- Kehittäjä avaa Helm-repon commitin def456
+- Näkee: "container.version = 1.2.3", "Deployed by abc123"
+- Tietää heti mikä konttiversio on missäkin ympäristössä
+- Voi verrata mikropalvelun uusimpaan commitin — onko ympäristö ajan tasalla?
+
+**Poikkeukset:**
+- `doNotDowngrade` esti deploymentin → statusviesti "Skipped: newer version already deployed"
+
+---
+
+## UC6: Testi-insinööri näkee mitä konttia testattiin
+
+**Actor:** Testi-insinööri
+**Precondition:** Integraatio- tai e2e-testit on ajettu
+
+**Main success:**
+- Avaa testi-repon commitin ghi789
+- Näkee: "Tested v1.2.3" (mikä kontti), "Tested abc123" (mikä mikropalvelun commit)
+- Klikkaa testiraporttiin → näkee tulokset
+- Näkee myös mitkä tagit olivat käytössä (`@smoke and not @slow`)
+- Voi todentaa että testattiin oikeaa versiota
+
+**Poikkeukset:**
+- Version check epäonnistui (haluttu versio ei ollut ympäristössä) → status: "Version mismatch"
+- Testit keskeytyivät timeoutiin → status: timeout, osittaiset tulokset raportissa
+
+---
+
+## UC7: Kehittäjä vertailee kahden buildin raportteja
+
+**Actor:** Kehittäjä
+**Precondition:** Projektilla on vähintään kaksi buildia
+
+**Main success:**
+- Kehittäjä avaa projektin build-indeksin `{MINIO_BASE}/{repo}/index.html`
+- Näkee viimeisimmät buildit vierekkäin
+- Avaa kaksi buildia eri välilehtiin
+- Voi verrata Cucumber-tuloksia: "build #42 vs #41 — mikä testi meni rikki?"
+
+**Poikkeukset:**
+- Vanha build siivottu → ei näy indeksissä
+
+---
+
+## Ei-toiminnalliset vaatimukset
+
+| Vaatimus | Toteutus |
+|----------|----------|
+| Raportit selailtavissa HTML:nä | MinIO static web hosting |
+| Linkki commitista suoraan raporttiin | Statusviestin `url`-kenttä |
+| Build-indeksi per projekti | Generoitu `index.html` Minioon |
+| Navigaatio raporttien välillä | "Back to build" / "Back to builds" — linkit indeksisivuilla |
+| Cross-repo-navigaatio | Statusviestit linkittävät repoja ristiin |
+| Raporttien pysyvyys | ConfigMap-pohjainen retention policy |
+| Autentikointi | OIDC (Traefik middleware, Gitea OAuth2) |