generated from knso/webklar-preview-template
JUSNandClaude Opus 5
96936caf0b
Beschreibt App, Webseite und Worker, die Bezahlung, die Schutzmechanismen und die Befehle. Alle Angaben aus dem Code eingesammelt, nicht aus dem Gedaechtnis. Enthaelt bewusst einen Abschnitt 'Fallen, die schon zugeschnappt sind' — die teuersten Fehler dieses Projekts waren nicht schwer zu beheben, sondern schwer zu BEMERKEN (Formular 6 Wochen tot, Schluessel zweimal ungueltig, Demo konnte nur Deutsch). Ueber CLAUDE.md eingebunden, damit der Ueberblick in jeder Sitzung mitkommt. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
216 lines
8.8 KiB
Markdown
216 lines
8.8 KiB
Markdown
# BehördenKlar — Überblick für Claude
|
|
|
|
> Stand: 23.09.2026. Diese Datei beschreibt, **was es gibt**.
|
|
> Für Release-Stand und offene Aufgaben siehe die Projekt-Erinnerung.
|
|
> Für Arbeitsregeln siehe `AGENTS.md` (Expo-Docs vor Code lesen!).
|
|
|
|
## Worum es geht
|
|
|
|
BehördenKlar macht **schwierige Post verständlich**: Brief fotografieren →
|
|
Klartext in einfacher Sprache (Niveau A2/B1) → Frist erkennen → richtig reagieren.
|
|
|
|
Nicht nur Ämter, sondern auch **Versicherung, Vermieter, Bank, Inkasso**. Die
|
|
Positionierung wurde am 19.09. bewusst verbreitert — weg vom „Hartz-IV"-Bild,
|
|
aber ohne die Spezialisierung aufzugeben (das ist der einzige Vorteil gegenüber
|
|
DeepL/ChatGPT).
|
|
|
|
**Zielgruppe:** Menschen, denen Amtsdeutsch schwerfällt — Muttersprachler mit
|
|
Leseschwierigkeiten ebenso wie Zugewanderte. Seit der Verbreiterung auch
|
|
Selbständige.
|
|
|
|
**Betreiber:** Webklar GbR (Justin Klein, Kenso Grimm), Kleinunternehmer § 19 UStG
|
|
— **keine Umsatzsteuer ausweisen!**
|
|
|
|
---
|
|
|
|
## Die drei Teile
|
|
|
|
| Teil | Was | Wo |
|
|
|---|---|---|
|
|
| **App** | Vollprodukt, iOS zuerst | `src/`, Expo SDK 57 |
|
|
| **Webseite** | Landingpages, Demo, Ratgeber, Bezahlung | `webseite/` → Cloudflare Pages |
|
|
| **Worker** | Proxy zur KI, Bezahlung, Limits | `proxy/` → Cloudflare Workers |
|
|
|
|
Der Worker steht dazwischen, damit **kein API-Schlüssel je auf ein Gerät kommt**.
|
|
|
|
---
|
|
|
|
## App (`src/`)
|
|
|
|
### Bildschirme
|
|
| Datei | Zweck |
|
|
|---|---|
|
|
| `FristenScreen` | Start — Briefe nach **Dringlichkeit**, nicht nach Datum. Countdown-Karte für die nächste Frist |
|
|
| `ScanScreen` | Foto oder PDF aufnehmen, verkleinern, hochladen |
|
|
| `AnalyseScreen` | Ergebnis: Kernaussage, Erklärung, Ampel, To-do-Liste, Fachbegriffe |
|
|
| `AntwortScreen` | Antwort-Assistent in 3 Schritten, Ausgabe als PDF oder zum Teilen |
|
|
| `ArchivScreen` | Alle Briefe, verschlüsselt |
|
|
| `GlossarScreen` | Amts-Wörterbuch, funktioniert **offline** |
|
|
| `EinstellungenScreen` | App-Sperre, Auto-Löschen, Aktions-Code |
|
|
| `ConsentScreen` | Einwilligung vor dem ersten Scan (Art. 9 DSGVO) |
|
|
|
|
Navigation: untere Leiste **Fristen · Scannen (FAB) · Archiv**.
|
|
|
|
### Funktionen
|
|
- **Ampel:** rot ≤ 7 Tage, gelb ≤ 21, sonst grün (`utils/ampel.ts`)
|
|
- **27 Zielsprachen** (`types.ts` → `SPRACHEN`), nach Größe der Sprachgemeinschaft
|
|
in Deutschland sortiert. Mit `rtl`-Flag für Arabisch, Farsi, Urdu, Paschtu —
|
|
ohne das wurden diese Schriften falsch linksbündig dargestellt.
|
|
**Der deutsche Fachbegriff bleibt deutsch**, nur seine Erklärung wird übersetzt
|
|
(man muss ihn im Brief wiederfinden).
|
|
- **Verschlüsseltes Archiv:** AES-256-GCM, Schlüssel im SecureStore (`krypto.ts`)
|
|
- **App-Sperre:** Face ID / Geräte-Code, plus Sichtschutz im App-Umschalter
|
|
- **Auto-Löschen** nach 30 oder 90 Tagen (`aufbewahrung.ts`)
|
|
- **Kalender + Erinnerungen** für Fristen (`kalender.ts`, `erinnerungen.ts`)
|
|
- **Vorlesen** über die Gerätestimme — fehlt sie für eine Sprache, passiert nichts
|
|
(abgefangen, kein Absturz)
|
|
- **3 Gratis-Analysen** (`GRATIS_ANALYSEN` in `storage.ts`), mit Aktions-Code
|
|
`FRUEHSTART` sind es 5
|
|
- **Kein Konto, kein Login.** Bewusste Entscheidung.
|
|
|
|
### Modelle
|
|
| Zweck | Modell |
|
|
|---|---|
|
|
| Brief-Analyse (Vision) | `claude-sonnet-5` |
|
|
| Übersetzung, Antwort-Entwürfe | `claude-haiku-4-5` |
|
|
|
|
Getrennt, weil die Analyse Qualität braucht und der Rest nicht — spart etwa
|
|
60 % der Kosten pro Brief.
|
|
|
|
---
|
|
|
|
## Webseite (`webseite/`)
|
|
|
|
- **28 Sprachen** (Deutsch + 27). **Nicht von Hand pflegen** — siehe Generator unten.
|
|
- **`/demo`** — 2 Gratis-Analysen im Browser, ohne Konto. Mit **Sprachauswahl**:
|
|
die Erklärung kommt in der gewählten Sprache.
|
|
- **Bezahlung** auf Startseite, Demo-Seite und **allen 27 Sprachseiten**
|
|
- **13 Ratgeber** unter `/ratgeber/` — Jobcenter, Finanzamt, Ausländerbehörde,
|
|
Widerspruch, Nebenkosten, Versicherung, Inkasso, Bußgeld, Kündigung u. a.
|
|
Jeder mit FAQ-Schema und Musterbrief.
|
|
- **4 Rechtsseiten:** AGB, Widerruf, Impressum, Datenschutz (alle `noindex`)
|
|
- **Warteliste** über Brevo (Double-Opt-in)
|
|
|
|
### Sprachseiten-Generator — WICHTIG
|
|
```bash
|
|
node tools/sprachseiten/build.js
|
|
```
|
|
Erzeugt **alle 27 Sprachseiten** aus `vorlage.html` + `texte.js`, pflegt hreflang
|
|
und Sprachwähler in der handgemachten `index.html` nach und schreibt die
|
|
`sitemap.xml`.
|
|
|
|
**Einzelne Sprachdateien niemals direkt bearbeiten** — sie werden überschrieben.
|
|
Änderungen gehören in `vorlage.html` (Aufbau) oder `texte.js` (Texte).
|
|
|
|
> Die Übersetzungen stammen von Claude. Bei Tigrinya, Somali, Paschtu und
|
|
> Kurdisch sollte vor größerer Werbung jemand mit Muttersprache gegenlesen.
|
|
|
|
---
|
|
|
|
## Worker (`proxy/src/index.ts`)
|
|
|
|
| Route | Zweck |
|
|
|---|---|
|
|
| `/` | App-Proxy zur Anthropic-API (Modell-Whitelist, Tageslimits) |
|
|
| `/demo` | Web-Demo — Turnstile, Gratis-Kontingent, **Zielsprache**, Guthaben |
|
|
| `/kaufen` | Stripe-Bezahlseite erzeugen |
|
|
| `/kauf-status` | Nach Rückkehr: Zahlung prüfen, Guthaben freischalten |
|
|
| `/stripe-webhook` | Sicherungsnetz + Wiederherstellungs-Mail |
|
|
|
|
### Bezahlung (LIVE, echtes Geld)
|
|
- **Guthaben statt Abo:** 5 Analysen 2,99 € · 15 Analysen 6,99 €
|
|
- **Ohne Konto:** Guthaben liegt server-seitig in KV (`wallet:<id>`), der Browser
|
|
bekommt einen **signierten Nachweis** (HMAC). Die Zahl im Browser ist nur
|
|
Anzeige — gerechnet wird auf dem Server.
|
|
- **Wiederherstellung** per E-Mail-Link (`?wallet=…`) — wirkt wie ein Gutscheincode
|
|
- **Pflicht-Häkchen** = Widerrufsverzicht nach § 356 Abs. 5 BGB
|
|
- **Kartenzahlung fest vorgegeben** (`payment_method_types[0]=card`). Schaltet
|
|
Stripe Link ab — das zeigte eine englische Ansicht mit winzigem
|
|
„Pay without Link", eine Sackgasse für die Zielgruppe.
|
|
⚠️ Solange das gesetzt ist, erscheinen **keine** weiteren Methoden. Wer PayPal
|
|
will: erst im Dashboard freischalten, **dann** hier ergänzen — sonst scheitert
|
|
der Kauf komplett.
|
|
- **Bezahlseite in der Nutzersprache** über `locale`. Nur Sprachen aus
|
|
`STRIPE_SPRACHEN` werden geschickt; ein unbekannter Wert lässt Stripe die
|
|
Session mit 400 ablehnen.
|
|
|
|
### Schutz vor Missbrauch
|
|
| Schutz | Wert |
|
|
|---|---|
|
|
| Turnstile | Sitekey `0x4AAAAAAESi2p41B915R4hW` (an die Domain gebunden!) |
|
|
| App: pro Gerät / pro IP | 20 / 100 pro Tag |
|
|
| Demo: Gesamtbudget / pro IP | 100 / 8 pro Tag |
|
|
| Origin-Prüfung | nur `behoerdenklar.de` darf kaufen |
|
|
|
|
### Secrets (`npx wrangler secret put …`)
|
|
`ANTHROPIC_API_KEY` · `STRIPE_SECRET_KEY` (`rk_live_`, eingeschränkt) ·
|
|
`STRIPE_WEBHOOK_SECRET` · `TOKEN_SIGNING_SECRET` · `TURNSTILE_SECRET_KEY` ·
|
|
`BREVO_API_KEY`
|
|
|
|
**Niemals in den Chat oder in Dateien.** Ist zweimal passiert, beide Male musste
|
|
rotiert werden.
|
|
|
|
---
|
|
|
|
## Befehle
|
|
|
|
```bash
|
|
npm run pruefung # Gesundheits-Check — nach JEDEM Deploy
|
|
npm test # 35 Tests
|
|
npx tsc --noEmit # Typen
|
|
node tools/sprachseiten/build.js # Sprachseiten neu bauen
|
|
```
|
|
|
|
**Deploy:**
|
|
```bash
|
|
cd proxy && npx wrangler deploy # Worker
|
|
cd proxy && npx wrangler pages deploy ../webseite --project-name behoerdenklar --commit-dirty=true # Webseite
|
|
```
|
|
|
|
**Committen ist nicht veröffentlichen** — nur Deployen macht live. Das wurde
|
|
schon einmal verwechselt, die Google-Verifizierung lag wochenlang nur im Git.
|
|
|
|
**Nach jedem Commit auf beide Remotes pushen:**
|
|
`git push origin main && git push gitea main`
|
|
|
|
### `npm run pruefung`
|
|
Prüft in ~30 Sekunden zehn Bereiche — jeder war schon einmal **still** kaputt:
|
|
abgeschnittene Zeilen `[...]`, Warteliste-Formular, JSON-LD, tote Dateiverweise,
|
|
Preis-IDs, Sitemap-Adressen, Kauf, Webhook-Secret, KI-Schlüssel, Turnstile.
|
|
|
|
Hintergrund: Das Warteliste-Formular war **sechs Wochen** kaputt, ohne dass
|
|
etwas Alarm geschlagen hätte.
|
|
|
|
---
|
|
|
|
## Fallen, die schon zugeschnappt sind
|
|
|
|
- **Ein Werkzeug kürzte Zeilen auf 200 Zeichen** und hängte `[...]` an. Traf die
|
|
Brevo-Formular-Adresse → Anmeldungen gingen ins Leere. `npm run pruefung`
|
|
findet das.
|
|
- **Turnstile ist an die Domain gebunden.** Nach dem Domain-Umzug blockierte das
|
|
alte Widget die Demo.
|
|
- **Der Anthropic-Schlüssel wurde zweimal ohne Zutun ungültig.** Die App war
|
|
tagelang kaputt, bevor es auffiel.
|
|
- **Die Web-Demo konnte lange nur Deutsch** — während 27 Sprachseiten
|
|
Übersetzung versprachen. Immer prüfen, ob das Produkt hält, was die Seite sagt.
|
|
- **expo-image-picker meldet standardmäßig `RECORD_AUDIO` an.** Abgeschaltet über
|
|
`microphonePermission: false`; die App nimmt nur Fotos auf.
|
|
|
|
---
|
|
|
|
## Rechtliches
|
|
|
|
AGB, Widerrufsbelehrung, Datenschutz und Impressum sind **live** und auf Webklar
|
|
GbR ausgestellt. Sie sind **Entwürfe von Claude** — eine anwaltliche oder
|
|
IHK-Prüfung steht aus.
|
|
|
|
**Kleinunternehmer § 19 UStG:** nirgends „inkl. USt." schreiben. Die Steuernummer
|
|
gehört nicht ins öffentliche Impressum.
|
|
|
|
Der Wiederherstellungs-Link wirkt wie ein Gutscheincode — wer ihn hat, nutzt das
|
|
Guthaben. Steht so in den AGB.
|
|
|
|
**Keine Rechtsberatung.** Steht in jedem Ratgeber, in der App und in den AGB —
|
|
das muss so bleiben.
|