# 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) |