consumer project käyttöönotossa tulleitea muutoksia (#12)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #12
2026-06-16 04:48:05 +03:00
parent f7b2353eb9
commit 14a411e340
10 changed files with 830 additions and 627 deletions
@@ -1,8 +1,6 @@
 # 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)

 ---

@@ -13,130 +11,89 @@

 **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
+- Näkee job-statukset automaattisesti: spinner (käynnissä), checkmark (ok), risti (feilasi)
+- Testijobit näyttävät statuksen linkillä: "unit-tests Link to Bats reports", "acc-tests Link to Cucumber reports"
+- Klikkaamalla testistatusta kehittäjä pääsee suoraan HTML-raporttiin git-pagesissa
+- Docker-build näyttää linkin konttirekisteriin

 **Poikkeukset:**
 - Statusviesti puuttuu (workflow kaatui ennen raportointia) → commitissa näkyy timeout/error
- Useampi workflow samalle commitille → statukset erottuvat `key`-arvolla
+- Useampi workflow samalle commitille → statukset erottuvat `context`-avaimella

 ---

 ## UC2: Kehittäjä lukee testiraportteja selaimessa

 **Actor:** Kehittäjä
-**Precondition:** Build on valmistunut, raportit pushattu Minioon
+**Precondition:** Build on valmistunut, raportit julkaistu git-pagesiin

 **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
+- Kehittäjä klikkaa commitin status-kuvaketta (esim. "unit-tests")
+- Selain avautuu suoraan HTML-raporttiin git-pagesissa
+- Bats-raportissa näkyy: testitulokset, code coverage
+- Cucumber-raportissa näkyy: mitkä testit menivät läpi, mitkä epäonnistuivat, stack tracet

 **Poikkeukset:**
- Raporttia ei ole (testit skipattiin, workflow kaatui ennen pushausta) → 404
- OIDC-sessio vanhentunut → uudelleenohjaus kirjautumiseen
+- Raporttia ei ole (testit skipattiin, workflow kaatui ennen julkaisua) → 404

 ---

-## 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
+## UC3: 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
+- Kehittäjä avaa kaksi buildia Gitean Actions-näkymässä eri välilehtiin
 - Voi verrata Cucumber-tuloksia: "build #42 vs #41 — mikä testi meni rikki?"

-**Poikkeukset:**
- Vanha build siivottu → ei näy indeksissä
+---
+
+## UC4: Kehittäjä jäljittää kontin koko ketjun commitista (tuleva)
+
+**Actor:** Kehittäjä
+**Precondition:** Mikropalvelun commitista on ajettu deployment ja klusteritestit
+
+**Main success:**
+- Kehittäjä avaa mikropalvelun commitin
+- Näkee statusviestit: "Build OK", "Deployed to staging", "Integration tests OK"
+- Klikkaamalla statusta siirtyy toisen repon committiin
+- Koko ketju on navigoitavissa edestakaisin commit-statuslinkkien kautta
+
+---
+
+## UC5: Kehittäjä näkee deployatun version ympäristössä (tuleva)
+
+**Actor:** Kehittäjä
+**Precondition:** Deployment on suoritettu
+
+**Main success:**
+- Avaa Helm-repon commitin
+- Näkee suoraan mikä konttiversio on deployattu
+- Voi verrata mikropalvelun uusimpaan commitiin — onko ympäristö ajan tasalla?
+
+---
+
+## UC6: Kehittäjä saa Gitea 1.27+ Summary-näkymän raporttilinkeistä (tuleva)
+
+**Actor:** Kehittäjä
+**Precondition:** Gitea 1.27+ ja päivitetty runner
+
+**Main success:**
+- Avaa workflow'n Gitea Actionsissa
+- "Report Summary" -jobin Summary-välilehdellä näkyy taulukko linkeillä kaikkiin raportteihin
+- Yhdellä silmäyksellä näkee mitä testejä ajettiin ja pääsee klikkaamalla raportteihin

 ---

 ## 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) |
+|---|---|
+| Raportit selailtavissa HTML:nä | git-pages static hosting |
+| Linkki commitista suoraan raporttiin | Commit-status API:n `target_url` |
+| Raporttien pysyvyys | git-pages retention sidecar |
+| Virheiden propagointi | Gitea Actions `needs`-ketju |
+| Pipeline-pysäytys virhetilanteessa | `needs` automaattinen skip |
+| Exit-koodi ainoa totuus | ADR 0008 |
+| Statusraportointi vain raporttilinkeille | ADR 0007 |