# Migrationen & Data-Seeds

Kairo trennt **Schema-Migrationen** (einmalig) von **Data-Seeds** (idempotent, bei Änderung erneut ausführbar).

## Schema-Migrationen

| | |
|---|---|
| **Pfad** | `backend/migrations/NNN_beschreibung.sql` |
| **Tracking** | Tabelle `schema_migrations` |
| **Ausführung** | Beim Backend-Start (`run_migrations.py`), überspringbar via `SKIP_DB_MIGRATE=1` |
| **Regel** | Jede Datei wird **genau einmal** angewendet. Änderungen → neue nummerierte Datei. |

### Aktuelle Schema-Migrationen

| Nr. | Datei | AP | Inhalt |
|-----|-------|-----|--------|
| 001 | `001_init_core.sql` | AP0.1 | `kairo_app_meta` |
| 002 | `002_auth_identity_tenant_actor.sql` | AP0.2 | User, Tenant, Actor, Session, `audit_log` |
| 003 | `003_data_seeds_tracking.sql` | AP0.2+ | `data_seeds` |
| 004 | `004_capabilities_registry.sql` | AP0.3 | `capabilities`, `role_capability_grants` |
| 005 | `005_prompt_feature_config_registry.sql` | AP0.4 | Feature/Prompt/Placeholder/Config |
| 006 | `006_initiatives_actions.sql` | AP0.5 | `initiatives`, `actions`, `action_assignments` |

Aktuelle Schema-Version: **`006`** (`backend/version.py` → `DB_SCHEMA_VERSION`).

## Data-Seeds

| | |
|---|---|
| **Pfad** | `backend/seeds/seed_NNN_beschreibung.sql` oder `.py` |
| **Tracking** | Tabelle `data_seeds` (Name + SHA256-Checksum) |
| **Ausführung** | Nach Schema-Migrationen (`run_seeds.py`), überspringbar via `SKIP_SEEDS=1` |
| **Regel** | Seed läuft erneut, wenn die Datei **geändert** wurde (Checksum abweicht) oder `--force` gesetzt ist. |

### Umgebungsfilter

Dateien mit **`.dev.`** im Namen (z. B. `seed_001_…​.dev.sql`) laufen **nicht in Production** (`ENVIRONMENT=production`).

### Seeds manuell ausführen

```bash
docker compose -f docker-compose.dev-env.yml exec backend python run_seeds.py
docker compose -f docker-compose.dev-env.yml exec backend python run_seeds.py --only seed_001_cleanup_pytest_artifacts --force
```

## Aktuelle Seeds

| Seed | Typ | Zweck |
|------|-----|--------|
| `seed_001_cleanup_pytest_artifacts` | SQL (dev) | Entfernt pytest/CI-User (`*@example.com`), verwaiste Test-Tenants; löscht zuerst Initiatives (AP0.5 FK) |
| `seed_002_bootstrap_admin` | Python | Legt Systemadmin aus `KAIRO_BOOTSTRAP_*` an, wenn noch kein User existiert |
| `seed_003_ensure_dev_admin` | Python (dev) | Entfernt fremde Dev-User, stellt `lars@stommer.com` als Portal-Admin sicher (jeder Start) |
| `seed_004_dogfooding_kairo_jinkendo` | Python (dev) | Deprecated — Dogfooding-Visualisierung, **nicht** Produkt; nur Nicht-Prod |

Dev-Seeds (`.dev.*` im Dateinamen) laufen **nicht in Production** (`ENVIRONMENT=production`) und werden in Dev **bei jedem Backend-Start** erneut ausgeführt.

### Prod-taugliche Seeds (laufen auch auf main)

| Seed | Verhalten Prod |
|------|----------------|
| `seed_002_bootstrap_admin` | Legt Admin **nur** an, wenn DB leer **und** `KAIRO_BOOTSTRAP_*` in `.env` gesetzt |

### Code-Registry (kein Data-Seed — identisch Dev/Prod)

Beim Backend-Start (`entrypoint.sh`, überspringbar via `SKIP_REGISTRY_SYNC=1`):

- `sync_rights_registry.py` — Capabilities
- `sync_prompt_feature_config.py` — Features/Prompts
- `sync_entity_field_registry.py` — Archetypen + Felddefinitionen aus `entity_archetypes/registry.py`

Zusätzlich im Code (Deploy-Artifact, keine DB-Seed-Datei): `method_profiles/registry.py`, `steering/methods/registrations/*`, Starter-Kits in `archetype_starter_kit.py`.

## Neuen Seed anlegen

1. Datei `backend/seeds/seed_NNN_kurzname.sql` oder `.py` anlegen (Python: `def run() -> None:`).
2. SQL idempotent halten (`DELETE … WHERE …`, `INSERT … ON CONFLICT`, etc.).
3. Nur Dev/CI: `.dev.sql` / `.dev.py` Suffix verwenden.
4. Nach Deploy prüfen: `python run_seeds.py` — bei geänderter Datei wird der Seed automatisch erneut ausgeführt.

## Tests & CI

- pytest setzt `SKIP_SEEDS=1` beim App-Import; Cleanup läuft über Fixture + nach CI-pytest.
- Geteilte Dev-DB wird nach jedem Test-Lauf bereinigt (`run_seeds.py --only seed_001_cleanup_pytest_artifacts --force`).