certain/ios/UEBERGABE.md

# Übergabe: iOS-App für Certain

**Für den nächsten Agenten.** Diese Datei ersetzt die Unterhaltung, in der die
App geplant wurde. Sie enthält alles, was du brauchst, ohne sie gelesen zu
haben: was entschieden ist, was fertig ist, was als Nächstes dran ist, und was
ich über das Backend herausgefunden habe. Lies sie ganz, bevor du anfängst —
die Abschnitte „Was das Backend vorgibt" und „Fallen" ersparen dir Tage.

Stand: 20.10.2026, Commit `6b86a6b`. Alles committet und gepusht.

---

## 1. Worum es geht

Certain ist ein Haushaltsbuch: FastAPI-Backend (`backend/`) plus
React-Weboberfläche (`web/`), die das Backend mit ausliefert. Dazu kommt eine
native iOS-App in `ios/`, die sich über eine eingegebene Server-Adresse (wie
`budget.scarriffle.com`) an dasselbe Backend hängt.

**Ziel: alles, was die Weboberfläche kann.** Budget, Buchungen, Konten, Abos,
Dashboard, Arbeitsliste, Kategorien, Tags, Einstellungen, Bankabruf und der
volle CSV-Import.

### Die wichtigste Rahmenbedingung

Auf der Maschine, auf der der Code entsteht, **gibt es kein Xcode**. Der Swift-
Code wird blind geschrieben und nie übersetzt. Der Nutzer legt das Projekt an,
übersetzt und meldet die Fehler zurück.

Daraus folgt die Arbeitsweise: **kleine Stufen, jede für sich übersetzbar.**
Nicht zehntausend Zeilen schreiben und dann einen Berg Fehlermeldungen
hinterlassen. Nach jeder Stufe übersetzt der Nutzer.

---

## 2. Entscheidungen des Nutzers

Alle schon gefallen. **Nicht erneut fragen.**

| Frage | Festgelegt |
|---|---|
| Backend erweitern | Ja, kleine Ergänzungen — jede einzeln vorlegen, bevor du sie schreibst |
| CSV-Import | **Voll, wie im Web** (trotz Abraten; steht deshalb als letzte Stufe) |
| Zusätzlicher Umfang | Arbeitsliste/Eingang, Kategorien und Tags, Einstellungen, Bankabruf anstossen |
| Dashboard | Feste iOS-Ansicht, kein Raster |
| iOS-Mindestversion | **iOS 26** |
| Ablieferung | Flache Ordner unter `ios/`, der Nutzer legt das Xcode-Projekt an |
| Anmeldung | App-Token (im Backend ergänzt, siehe unten) |
| Erweiterungen | Teilen-Menü für Dateien, Kurzbefehle/Siri |
| Sprachen | Deutsch **und** Englisch |
| iPad | Richtig mitgedacht, zweispaltig |
| Offline | Zuletzt Geladenes mit „Stand von …" |

**Der Nutzer will jede Entscheidung selbst treffen.** Wenn eine Frage auftaucht,
die den Zuschnitt ändert: fragen, nicht annehmen.

---

## 3. Was das Backend vorgibt

Die Befunde aus einer gründlichen Durchsicht. Sie bestimmen den ganzen Entwurf.

### Anmeldung

Die Web-API kennt **ausschliesslich ein Sitzungs-Cookie** (`get_current_user`
in `backend/app/deps.py`). Kein Bearer, kein Token im Body. Die Sitzung liegt
serverseitig in der Tabelle `sessions` (kein JWT), hält 30 Tage und
**verlängert sich nicht**.

Anmeldung ist ein **Formular**, kein JSON: `POST /api/auth/login` mit
`application/x-www-form-urlencoded`, Feldern `username` und `password`
(`OAuth2PasswordRequestForm`). JSON gibt 422.

Zwei-Faktor: Login antwortet `{"status": "2fa_required"}` und setzt ein
Pending-Cookie mit **10 Minuten** Laufzeit. Dann
`POST /api/auth/2fa/verify` mit `{"code": "...", "recovery": false}`. Nach
**fünf** Fehlversuchen ist die Zwischensitzung verbraucht.

Offene Pflichten sperren **jeden** Endpunkt mit `403` und einem
maschinenlesbaren `detail`: `password_change_required` oder
`mfa_setup_required`. Erreichbar bleiben nur `/health`, `/version`,
`/auth/me`, `/auth/logout`, `/auth/login`, `/auth/change-password`, `/auth/2fa`.

### Alles hängt unter `/api`

`GET /api/version` → `{"name": "Certain Finance", ...}`. Das ist die
Serverprüfung. **Wichtig:** Jeder unbekannte Pfad ausserhalb `/api` liefert mit
Status 200 die Weboberfläche aus — nur `/api/version` kann einen fremden Server
sicher ausschliessen.

### Fehlerformat

`{"detail": "..."}` — aber bei 422 ist `detail` eine **Liste** von
Pydantic-Meldungen statt einer Zeichenkette. `Netzwerk/APIFehler.swift` fängt
beides ab; wer das übersieht, verliert bei jedem Eingabefehler die Meldung.

Statuscodes: 401 nicht angemeldet, 403 verboten oder Pflicht offen, 404 auch
für fremde IDs (bewusst, Mandanten-Isolation), **409 heisst „nachfragen"** und
lässt sich oft mit `trotzdem=true` wiederholen, 400/422 ungültig.

### Beträge

**Alles sind Cent-Ganzzahlen.** Nirgends Fliesskomma (einzige Ausnahme:
`QuickBookingIn.amount`). Drei Felder an einer Buchung:
- `amount_cents` — in der **Kontowährung**
- `amount_eur_cents` — beim Speichern **eingefrorener** EUR-Wert
- `amount_base_cents` — bei jedem Lesen in die Hauptwährung umgerechnet

Der Client rechnet **nichts** davon selbst. Kontosalden, Budget-Soll/Ist,
Vertrags-Monatswerte, Dashboard-Zahlen kommen alle fertig. Der Client
formatiert nur — und rechnet Prozente und „Rest", die es in der API nicht gibt.

Achtung: `*_base_cents` kann still auf den nativen Wert zurückfallen, wenn kein
Wechselkurs vorliegt. Die `ohne_kurs`-Listen in den Antworten sagen, wann das
passiert. Wer sie nicht anzeigt, zeigt stillschweigend falsche Summen.

### Zeitstempel — die Falle, die mich Zeit gekostet hat

`created_at` und Konsorten kommen als `2026-10-20T14:18:15.780705` — **ohne
Zeitzone, mit sechs Stellen Mikrosekunden**. Beide Standard-ISO8601-Leser von
Foundation scheitern daran, weil sie eine Zone verlangen. `Modelle/Zeitangaben.swift`
hat deshalb einen dritten Leser. Tagesdaten (`date`, `opening_date`) sind
dagegen reine `"2026-07-14"`. Zwei getrennte Typen statt einer
Decoder-Strategie — das ist Absicht, siehe Kommentar dort.

### Zwei Dinge, die fachlich im Frontend sitzen

Die App muss sie nachbauen, das Backend hilft nicht:

1. **Was ein Übertrag ist.** Entweder `type == "transfer"` **oder** die Buchung
   steht in `GET /api/transactions/links`. Es gibt zwei Mechanismen
   nebeneinander: ein Übertrag am Stück (eine Buchung mit `to_account_id`) und
   die Verknüpfungs-Schicht `TransferLink` (zwei getrennte Buchungen, wie die
   Bank sie liefert; keine davon wird verändert). Das Zusammenfassen beider
   Beine zu **einer** Anzeigezeile macht heute nur der Browser
   (`web/src/pages/Transactions.jsx`, Suche nach `paarZu`).
2. **Welche Verträge in `aus_vertraegen_cents` stecken.** Das Backend liefert
   nur die Summe; welche Abos dahinterstehen, ermittelt das Frontend selbst aus
   `/subscriptions` nach `category_id`.

### Buchungsliste ohne Suche

`GET /api/transactions` kennt nur `account_id`, `category_id`, `uncategorized`,
`type`, `date_from`, `date_to`, `limit` (Standard **5000**), `offset`. **Keine**
Volltextsuche, kein Tag-Filter, keine wählbare Sortierung. Die Weboberfläche
lädt alles und filtert im Browser. Auf dem Telefon ist das spürbar — daher
Backend-Ergänzung B unten.

### Was nicht in die App kommt

- **Bankkonten verbinden.** Die Bank leitet fest auf
  `{base_url}/bank/rueckkehr` zurück, registriert bei Enable Banking. Abrufen,
  Salden holen und Konten zuordnen läuft nativ — nur das Herstellen nicht.
- **Postfach einrichten** (IMAP-Zugangsdaten) und **Sicherung/Wiederherstellung**
  (ersetzt die ganze Datenbank). Gehört an den Rechner.
- **Benutzerverwaltung** (`/users`, `/policy`) — Administration, weggelassen,
  solange der Nutzer nicht widerspricht.
- **Belege als Anhang gibt es nicht.** Im Datenmodell existiert nichts
  dergleichen. `POST /api/documents/preview` ist eine Einbahnstrasse: Bild rein,
  erkannter Text und Buchungsvorschläge raus, die Datei wird nicht gespeichert.

---

## 4. Backend-Ergänzungen

Vier geplant. **A ist fertig**, B bis D stehen aus. Jede einzeln dem Nutzer
vorlegen, bevor du sie schreibst.

### A — App-Token ✅ (Commit `8a7545b`)

`TokenScope` hat neben `quick_add` jetzt `app`. `get_current_user` akzeptiert
den Header `X-Certain-Token`, wenn die Marke diese Reichweite hat. Kein
Migrationsschritt nötig — `_enum()` legt Enums ohne DB-Bedingung ab.

Die Prüfung sitzt in `_session_user` (`backend/app/deps.py`), **nicht** in
`get_current_user` — damit auch `enforce_account_state` die Marke sieht und
eine App nicht an der Passwortwechsel-Pflicht vorbeikommt.

Zwei Dinge, die die Tests festhalten (`backend/tests/test_app_marke.py`,
7 Stück):
- Eine `quick_add`-Marke ist **nicht** still zum Vollzugang geworden. Sie gilt
  weiter nur an den drei `/quick`-Endpunkten.
- Eine App-Marke darf **keine weitere ausstellen** (`require_cookie_session` an
  `POST /api/inbox/tokens`). Sonst stellte ein Dieb sich Ersatzschlüssel aus
  und das Widerrufen liefe ins Leere.

### B — Suche und Tag-Filter auf `/transactions` (offen)

Drei Query-Parameter: `q` (Volltext über `payee`, `description`, `notes`),
`tag_id`, `subscription_id`. Muster für den Tag-Filter steht schon da: der
`uncategorized`-Zweig in `backend/app/routers/transactions.py` arbeitet mit
genau so einer Unterabfrage.

Nötig für Stufe 2 — ohne das lädt das Telefon für jede Ansicht bis zu 5000
Zeilen.

### C — `GET /budget/template` liefert `modus` und `zuschlag_cents` (offen)

Beide fehlen heute in der Antwort (`backend/app/routers/budgets.py`), obwohl
das Modell sie führt und `PUT` sie zurückgibt. Ohne sie kann die App die
Vorlage weder richtig anzeigen noch bearbeiten. Nötig für Stufe 3.

### D — Zwei Kopier-Lücken im Budget (offen)

`copy_template_to_month` und `template_from_month` in
`backend/app/services/budget.py` übernehmen nur `planned_cents`. Ein
„berechneter" Eintrag fällt beim Kopieren still auf „fest" zurück. Das ist ein
**bestehender Fehler**, kein App-Thema — aber die App macht ihn sichtbar, weil
sie beide Richtungen anbietet. Nötig für Stufe 3.

---

## 5. Was fertig ist — Stufe 1 ✅ (Commit `6b86a6b`)

21 Swift-Dateien, rund 2600 Zeilen, in `ios/`:

| Ordner | Inhalt |
|---|---|
| `App/` | `CertainApp` (Einstieg), `AppZustand` (zentraler Zustand), `RootAnsicht` (Navigation) |
| `Netzwerk/` | `CertainClient` (Actor um URLSession), `Endpunkte`, `APIFehler`, `Ablage` (Voreinstellungen + Schlüsselbund), `Zwischenspeicher` (offline), `Lader` |
| `Modelle/` | `Grundmodelle` (Benutzer, Marke, Einstellungen, Serverkennung), `Konto`, `Zeitangaben` |
| `Bausteine/` | `Geldbetrag`, `Darstellung` (Farben, Symbolzuordnung, Plakette), `Zustandsansichten` |
| `Anmeldung/` | Server-Adresse, Anmeldung, zweiter Faktor, Passwortwechsel |
| `Konten/` | `KontenListe` — die erste Fachansicht |
| `Einstellungen/` | Platzhalter: zeigt den Zugang und lässt abmelden |
| `Texte/` | `de.lproj` und `en.lproj`, zeilengleich |
| `Tests/` | `GrundlagenTests` — reine Logik, Swift Testing |

### Wie die Anmeldung abläuft

1. Nutzer gibt die Adresse ein → `GET /api/version` prüft, ob dort Certain läuft.
2. Nutzer meldet sich an → normales Cookie, inklusive 2FA und
   Pflicht-Passwortwechsel.
3. **Noch in derselben Sitzung** legt die App über `POST /api/inbox/tokens` mit
   `scope: "app"` eine Marke an und legt den Klartext in den **Schlüsselbund**.
4. Danach trägt nur noch der Header. Das Cookie wird weggeworfen
   (`vergissCookies()`).

Kein Passwort auf dem Gerät, kein Ablauf nach 30 Tagen, einzeln widerrufbar.

### Was geprüft ist

Jedes Modellfeld wurde gegen **echte Antworten eines laufenden Backends**
verglichen (`/api/version`, `/api/auth/me`, `/api/accounts`, `/api/settings`,
`/api/inbox/tokens`). Alle Namen stimmen. **Mach das bei jeder weiteren Stufe
genauso** — das ist die einzige Prüfung, die beim blinden Schreiben wirklich
etwas fängt. Wie: Ein kleines Python-Skript mit `TestClient` gegen eine
Wegwerf-Datenbank, Felder flach ausgeben, mit den `CodingKeys` vergleichen.
(Das Passwort der Dev-Datenbank unter `backend/data/app.db` ist unbekannt —
nicht raten, eine frische Testdatenbank nehmen.)

### Was nicht geprüft ist

**Ob es übersetzt.** Der Nutzer hatte Stufe 1 beim Schreiben dieser Datei noch
nicht gebaut. Rechne damit, dass seine erste Rückmeldung Fehlermeldungen sind —
das ist eingeplant und kein Rückschlag.

---

## 6. Was als Nächstes dran ist

**Stufe 2 — Lesen.** Dashboard (feste Ansicht: Kontostände, Budget-Fortschritt,
letzte Buchungen, Einnahmen/Ausgaben), Budget-Monatsansicht, Buchungsliste,
Abo-Liste. Dazu Backend-Ergänzungen **B** und **C**.

**Stufe 3 — Schreiben.** Buchungen anlegen und ändern, Budget bearbeiten
(Monat und Vorlage, beide Betriebsarten `fest`/`berechnet`), Abos verwalten
samt Logo, Konten bearbeiten. Dazu Backend-Ergänzung **D**.

**Stufe 4 — Arbeitsliste.** Eingang mit Buchen, Verwerfen, Kategorie zuordnen,
Übertragsvorschlägen und Dubletten. Fachlich der Teil, der am besten aufs
Telefon gehört: eine Zeile, eine Entscheidung.

**Stufe 5 — Nebenräume.** Kategorien, Tags, Schlagwörter, Einstellungen,
Bankabruf anstossen. Hier gehört auch das **Einrichten** des zweiten Faktors
hin — bisher verweist die App dafür in den Browser.

**Stufe 6 — Erweiterungen.** Teilen-Menü und Kurzbefehle. Brauchen eigene Ziele
im Xcode-Projekt, eine **App-Gruppe** und eine **geteilte
Schlüsselbund-Gruppe**; `Netzwerk/Ablage.swift` hat dafür schon die beiden
Konstanten `gruppe` und `schluesselbundGruppe` (stehen auf `nil`). Für die
Kurzbefehle ist `POST /api/quick/booking` fertig: Header-Marke, idempotent über
`external_id`, fertig formulierte Antwort-Meldung.

**Stufe 7 — Import, voll.** Erkennen, Rohansicht, Spaltenzuordnung,
Formateinstellungen, Zeilenfilter, editierbare Prüfansicht, Saldo-Abgleich,
Vorlagen, Verlauf mit Rücknahme.

### Zum Umfang, ehrlich

Die Weboberfläche hat rund 8900 Zeilen JSX. Nativ wird das nicht weniger.
Stufen 2 bis 6 zusammen sind grob drei bis vier Wochen, Stufe 7 nochmal zwei
bis drei.

Stufe 7 steht bewusst am Ende. Alles davor ist für sich nutzbar. Der Ablauf
hat **keinen Server-Zustand** zwischen den Schritten: Die Datei wird bei jedem
Schritt neu hochgeladen, und beim Buchen gehen die Vorschauzeilen unverändert
zurück an den Server. Eine editierbare Prüftabelle mit 300 Zeilen und neun
Spaltenzuordnungen ist auf Telefonbreite ein Entwurfsproblem, kein
Übersetzungsproblem. Das Backend selbst sagt dazu in
`backend/app/routers/quick.py`: *„Ein Auszug hat schnell hunderte Zeilen; die
am Telefon durchzusehen wäre keine Erleichterung."* Der Nutzer kennt diesen
Einwand und will den vollen Import trotzdem.

---

## 7. Fallen und Arbeitsweise

### Beim Übersetzen am ehesten verdächtig

Nach abnehmender Wahrscheinlichkeit:

1. **`@testable import Certain`** in `Tests/GrundlagenTests.swift` muss auf den
   Namen des App-Ziels zeigen.
2. **`Lader` ist eine generische `@Observable`-Klasse** — die ungewöhnlichste
   Konstruktion im Code. Wird bisher nur in `KontenListe` benutzt.
3. **Nebenläufigkeit:** `AppZustand` ist `@MainActor`, `CertainClient` ein
   Actor. An den Übergängen kann es unter strikter Prüfung Warnungen setzen.
4. **`Tab` und `.tabViewStyle(.sidebarAdaptable)`** setzen iOS 18 voraus — bei
   iOS 26 als Mindestversion kein Problem.
5. Die Tests nutzen **Swift Testing** (`import Testing`, `@Test`, `#expect`),
   nicht XCTest.

### Schreibende Aufrufe mit Query statt Körper

Leicht zu übersehen, das Backend macht es an mehreren Stellen:
`PUT /budget/template/category/{id}`, `PUT /budget/{label}/category/{id}`,
`PUT /settings/{key}`, `POST /subscriptions/{id}/preis`.

### Konventionen des Projekts

- **Alles auf Deutsch**: Code-Kommentare, Bezeichner, Testnamen, Commit-
  Meldungen, Oberflächentexte. Testnamen sind deutsche Aussagesätze,
  ASCII-transliteriert (`test_app_marke_darf_lesen_und_schreiben`).
- **Commits**: `typ: Wirkung für den Nutzer`, auf Deutsch, eine Wirkung je
  Commit. Fertige Arbeit wird committet und gepusht, ohne Rückfrage.
- **Kommentare erklären das Warum**, nicht das Was — und zwar das, was der Code
  nicht zeigen kann. Das ganze Projekt ist so geschrieben; halte es durch.
- **Tests**: `cd backend && ./.venv/Scripts/python.exe -m pytest tests/ -q`
  (Python 3.12 im venv; das System-Python kann nicht bauen). Dauert rund zwei
  Minuten — im Hintergrund laufen lassen.
- **Vorbekannt rot**, nicht von dir verursacht:
  `test_mail_import.py::test_von_hand_weitergeleitete_mail_wird_am_betreff_erkannt`
  und `test_migrations.py::test_batch_migration_keeps_dependent_rows` (der
  scheitert an einem Umgebungsproblem, `WinError 10106` in einem Subprozess).
  Erwartung nach jedem Lauf: genau diese zwei, sonst nichts.
- **Heredocs in Bash scheitern** an den deutschen Anführungszeichen („ ").
  Für Dateien mit solchen Zeichen das Write-Werkzeug nehmen, nicht `cat <<EOF`.

### Offene Punkte, die der Nutzer bestimmt

- Name, Bundle-ID und Signierung — er legt das Projekt an.
- Ob die Benutzerverwaltung doch mit hinein soll.
- Ob eine neu vergebene App-Marke am Rechner bestätigt werden muss, bevor sie
  gilt. Sicherer, aber umständlich beim Einrichten eines neuen Geräts.