# Data flow — periaatetaso

> Tila: DRAFT — kevyt suunnitteludokumentti, muokataan tarpeen mukaan.
> Ei ADR. Ei normatiivinen. Kuvaa periaatteen, ei implementaatiota.
>
> Lähde: [docs/design-rationale.md](../docs/design-rationale.md) — erityisesti periaatteet 1 (commit-status), 3 (konfiguraatio repossa), 5 (raportit MinIO:ssa) ja 7 (cross-repo traceability).

## Tarkoitus

Selventää **kuka omistaa mitä datan** ja **miten se liikkuu** consumer → provider → Gitea -ketjussa.

**Ydinperiaate:** Branch-päätös on consumerin vastuulla. Provider on branch-agnostinen — se saa polun config-tiedostoon ja suorittaa sen määrittämän pipelinen. Consumer valitsee kumman jobin ja minkä pipeline-as-conf -tiedoston ajetaan; engine lukee vain sen mitä `with:` välittää.

---

## Roolit ja tiedostot

| Rooli | Tiedosto(t) | Mitä tietää / mitä tekee |
|-------|-------------|--------------------------|
| **Consumer** | `ci.yml` | Trigger, branch (`if:`), valitsee pipeline-as-conf -tiedoston ja kontit, kutsuu engineä `uses:` |
| **Consumer** | `*-conf.yaml` (pipeline-as-conf) | Projektin data: mitä pipeline ajaa (ekosysteemi, test-flow, docker jne.) — versioitu repossa |
| **Provider** | `ci-engine.yml` | Gitea workflow (`.gitea/workflows/`); `workflow_call` only; pipeline-määrittely |
| **Provider** | jaettu suorituskoodi | Uudelleenkäytettävä logiikka — **ei** Gitea workflow; engine kutsuu steppien sisällä |
| **Gitea org** | secrets | Tokenit, salasanat — ei koskaan repoon; `secrets: inherit` |
| **Gitea org** | variables (kapea poikkeus) | Org-laajuiset infra-endpointit (esim. `MINIO_BASE_URL`, `GITEA_SERVER_URL`) — valinnainen shortcut |

### Secrets vs. variables vs. conf

Kolmitasoinen jako — helppo sääntö kehittäjälle:

| Tyyppi | Missä | Esimerkkejä |
|--------|-------|-------------|
| **Secrets** | Gitea org secrets | `GITEA_TOKEN`, `SONAR_TOKEN`, `DEPLOY_TOKEN` |
| **Projektidata** | Consumer `*-conf.yaml` | `build.ecosystem`, `docker.imageName`, `sonarqube.*`, `test-flow`, `deployment.*` |
| **Org-infra** | Gitea org variables (valinnainen) | `MINIO_BASE_URL`, `GITEA_SERVER_URL` — sama kaikille, harvoin muuttuu |

1. Salainen? → org secret
2. Projektin asia? → conf-tiedosto (periaate 3)
3. Koko orgin sama infra-endpoint? → org variable, vain jos et halua toistaa sitä jokaisessa confissa

Org variables on **kapea poikkeus** infra-endpointeille — ei korvike conf-tiedostolle. Projektikohtaiset arvot (docker-nimi, test-flow, Sonar projectKey) kuuluvat aina confiin.

### Pipeline vs. jaettu suorituskoodi

Kaksi eri artefaktityyppiä provider-puolella:

```
Provider (gitea-ci-library)
├── .gitea/workflows/ci-engine.yml   ← pipeline (Gitea workflow, consumer kutsuu uses:)
└── jaettu suorituskoodi             ← uudelleenkäytettävä logiikka (EI .gitea/workflows/:ssa)

Consumer (mikropalvelu)
├── .gitea/workflows/ci.yml          ← ohut kutsuja (Gitea workflow)
└── ci-feature.yaml                  ← data (ei suoritettavaa koodia)
```

- **Pipeline-tiedosto** (`ci-engine.yml`) on Gitean workflow — sen täytyy olla `.gitea/workflows/`:ssa, jotta `uses:` löytää sen.
- **Jaettu suorituskoodi** on providerin omistamaa logiikkaa (status-raportointi, raporttien julkaisu, dispatch jne.). Consumer ei kopioi sitä — korjaus provider-repoon, kaikki consumerit hyötyvät `@v1`:stä.
- **Toteutus** (kieli, tiedostomuoto, sijainti repossa) ei kuulu tähän dokumenttiin.

### Binding: consumer → provider

Ei dynaamista löytämistä — consumer kovakoodaa `uses:`-polun:

```
org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
```

| Vaihe | Mitä tapahtuu |
|-------|---------------|
| 1 | Push consumer-repoon → Gitea lukee consumerin `ci.yml` |
| 2 | `if:` valitsee jobin |
| 3 | `uses:` → Gitea hakee provider-reposta `ci-engine.yml` annetulla `@ref`:llä |
| 4 | Provider vaatii `on: workflow_call` |
| 5 | `with:` → providerin `inputs`; checkout = **consumer-repo** (lähdekoodi + config-file) |
| 6 | Engine tuo provider-artefaktit runnerille tagilla `@v1` |

**`@ref`:** `@v1` (tag providerin main-haarassa). Pinnaa engine-version — consumer ei seuraa providerin kehityshaaraa.

### Dogfood-erikoistapaus

`gitea-ci-library` sisältää sekä consumer- että provider-tiedostot samassa repossa. **Roolit eivät muutu** — vain fyysinen sijainti on poikkeuksellinen.

**Dogfood-sääntö:** Consumerin `ci.yml` viittaa provideriin **samalla `uses:`-polulla** kuin mikä tahansa ulkoinen mikropalvelu. Ei suhteellista polkua (`./.gitea/workflows/...`).

```
Ulkoinen mikropalvelu (puhdas consumer)     gitea-ci-library (dogfood)
┌──────────────────────────────┐            ┌──────────────────────────────┐
│ ci.yml                       │            │ ci.yml            ← consumer │
│ ci-feature.yaml              │            │ ci-feature.yaml   ← consumer │
│ ci-main.yaml                 │            │ ci-main.yaml      ← consumer │
│                              │            │ ci-engine.yml     ← provider │
│ uses: org/gitea-ci-library/  │            │ uses: org/gitea-ci-library/  │
│   .../ci-engine.yml@v1       │            │   .../ci-engine.yml@v1       │
└──────────────────────────────┘            │ suorituskoodi     ← provider │
                                            └──────────────────────────────┘
```

Ulkoinen mikropalvelu on puhdas consumer (vain `ci.yml` + conf-tiedostot). Provider tulee `uses:`-viittauksella kirjastosta — dogfood mukaan lukien.

---

## Kuusi data-virtaa

```
1. CONSUMER → PROVIDER (push)
   Consumer tietää branchin → valitsee jobin + config-file + kontit.
   Provider vastaanottaa, ei tulkitse branchia.

   ci.yml ──with: config-file + kontti-imaget──► ci-engine.yml

2. PROVIDER SISÄINEN
   Engine lukee config-file-polun → rakentaa steppigraafin → ajaa stepit.
   Mitä pipelinea ajetaan johtuu conf-tiedostosta, ei branch-tiedosta providerissa.

3. PROVIDER → GITEA (commit-status)
   Jokainen steppi raportoi tilansa commitille (Gitea REST API).
   Uniikki key per vaihe (periaate 1).

4. GITEA → CONSUMER (feedback loop)
   Consumerin commitille kertyy statuksia jokaisesta stepistä.
   Kehittäjä näkee suoraan commitilta: mitä ajettiin, menikö läpi.
   url-kenttä linkittää raportteihin / buildiin.

5. PROVIDER → MinIO → GITEA (raportit)
   Steppi generoi raportin → julkaisu MinIO:hon
   → deterministinen URL → URL liitetään commit-statusviestiin
   (periaate 5).

6. CROSS-REPO KETJU
   Mikropalvelu-commit (root) → dispatch → toinen repo → status takaisin root-committiin.
   root-build kulkee inputs-parametrina koko ketjun läpi (periaate 7).
```

---

## Silmukka

```
Consumer pushaa koodia
       │
       ├── feature-branch → ci.yml valitsee feature-jobin
       │                      with: config-file: ci-feature.yaml + kontit
       │
       └── main-branch     → ci.yml valitsee main-jobin
                              with: config-file: ci-main.yaml + kontit
       │
       ▼  uses:
┌──────────────────────────────────────────────┐
│  ci-engine.yml (provider, branch-agnostinen) │
│  Lukee config-file → steppigraafi → stepit  │
│                                              │
│  config-file → steppigraafi → stepit ajetaan │
│       │            │            │            │
│       └────────────┴────────────┘            │
│                    │                         │
│                    ▼                         │
│         jokainen steppi → status commitille  │
│                    │                         │
│         (raportit) → MinIO → url statusiin   │
└──────────────────┬───────────────────────────┘
                   │ POST /api/v1/repos/.../statuses/{sha}
                   ▼
┌──────────────────────────────────────────────┐
│  Gitea commit                                │
│  ├── ci/start        ✓                       │
│  ├── ci/unit-test    ✓  (url → raportti)    │
│  ├── ci/code-coverage ✓                      │
│  └── ci/end          ✓                       │
└──────────────────────────────────────────────┘
```

### Cross-repo ketju (periaate 7)

```
Mikropalvelu (root-commit abc123)
       │
       ├── build + deploy ──dispatch──► Helm-repo (commit def456)
       │                                      │
       │                                      ├── status → oma commit
       │                                      └── status → root abc123
       │
       └── test-flow ──dispatch──► Testi-repo (commit ghi789)
                                          │
                                          ├── status → oma commit
                                          ├── status → root abc123
                                          └── status → Helm def456

root-build (abc123) kulkee workflow_dispatch inputs -parametrina koko ketjun läpi.
```

---

## Omistajuus

| Mitä | Omistaja | Miten liikkuu |
|------|----------|---------------|
| Branch-päätös | Consumer | `ci.yml` `if:` |
| Mitä pipelinea ajetaan | Consumer | Valittu pipeline-as-conf -tiedosto |
| Pipeline-runko (steppigraafi) | Provider | Engine rakentaa confista |
| Kontit (maven, dind…) | Consumer | `with:` → provider `inputs` |
| Projektidata (ecosystem, test-flow…) | Consumer | pipeline-as-conf repossa |
| Moottori + jaettu suorituskoodi | Provider | `ci-engine.yml` + provider-logiikka |
| Tokenit, salasanat | Gitea org | secrets — `secrets: inherit` |
| Org-laajuiset infra-endpointit | Gitea org | variables (valinnainen poikkeus) |

---

## Consumer-sopimus

`ci.yml` on **mahdollisimman lyhyt**:

- Kaksi jobia (feature / main) tai vastaava `if:`-jaottelu
- Sama engine, eri `config-file` per job
- Kontit consumerin `with:`:ssa — provider ei sisällä image-versioita
- `secrets: inherit`

```yaml
# Esimerkki — kovakoodattu provider-polku (provider main-haarassa, tag @v1)

jobs:
  feature:
    if: gitea.ref != 'refs/heads/main'
    uses: org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
    secrets: inherit
    with:
      config-file: ci-feature.yaml
      maven-image: ...

  main:
    if: gitea.ref == 'refs/heads/main'
    uses: org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
    secrets: inherit
    with:
      config-file: ci-main.yaml
      maven-image: ...
      dind-image: ...
```

---

## Provider-sopimus

- Vain `workflow_call` — ei omaa triggeriä
- Pakollinen input: `config-file` (polku repossa)
- Valinnaiset: kontti-imaget consumerilta
- Ei branch-ehtoja provider-tiedostossa — consumer on jo päättänyt mitä ajetaan conf-valinnalla
- Lukee consumer-datan (lähdekoodi + config-file) ja tuo provider-artefaktit runnerille
- Lukee conf → suorittaa → raportoi

### Mitä engine EI tiedä

- Onko kyseessä feature vai main — consumer on jo valinnut conf-tiedoston
- Mitä komentoja ajetaan — ne tulevat conf-tiedostosta
- Mitä kontteja on käytössä — consumer kertoo `with:`:ssa

Engine on branch-agnostinen suorittaja. Consumer omistaa päätökset ja datan.

---

## Esimerkki: gitea-ci-library (dogfood)

Tämä projekti on sekä provider että consumer. Roolit pysyvät samoina kuin ulkoisella mikropalvelulla — **sama `uses:`-viittaus** (`@v1`), ei suhteellista polkua. Consumer-sopimuksen esimerkki pätee sellaisenaan.

| Rooli | Tiedosto | Mitä tekee |
|-------|----------|------------|
| Consumer | `ci.yml` | Tietää branchin, valitsee jobin ja conf-tiedoston, syöttää kontit |
| Consumer | `ci-feature.yaml`, `ci-main.yaml` | Pipeline-as-conf — projektin data per pipeline-tyyppi |
| Provider | `ci-engine.yml` | Pipeline-määrittely; lukee config-file:n, rakentaa steppigraafin, ajaa, raportoi |
| Provider | jaettu suorituskoodi | Status, raportit, dispatch — toteutus avoin |

---

## Mitä tämä EI ota kantaa

- Moottorin toteutuskieli ja -muoto (bash, TypeScript, Python, Go — erillinen päätös)
- Nykyiset skriptitiedostot ja niiden rajapinnat (mahdollinen redesign)
- Raporttien julkaisumekanismi (miten MinIO:hon — toteutus avoin)
- Provider-artefaktien toimitus runnerille (checkout, bundle, inline — toteutus myöhemmin)
- Main-skeletonin yksityiskohdat (build, deploy, test-flow)
- Conf-tiedoston skeema / kentät (→ `config-model.md`)
- Cross-repon workflow-tiedostojen sisältö