Add full application: receipt scanning, auth, billing, and account deletion

Brings the working codebase (Next.js app, auth system, Stripe billing, Docker/deploy config, tests, docs) into version control on top of the placeholder initial commit, and adds account self-deletion (Danger Zone in Settings, password + typed-email confirmation, cascading DB cleanup, Stripe cancellation) per GDPR right-to-erasure. Excludes local build caches, node_modules, and internal agent scratch files; .gitignore hardened to keep those out going forward. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-19 20:59:04 +02:00
parent 650a74da97
commit 84b9987c49
415 changed files with 96619 additions and 0 deletions
--- a/receipt_scanner_to_excel_blueprint.md
+++ b/receipt_scanner_to_excel_blueprint.md
@@ -0,0 +1,244 @@
+# 🧾 Receipt Scanner to Excel: Vollständiger Micro-App Masterplan & Technische Architektur-Spezifikation
+
+**Erstellt / Aktualisiert:** 14. August 2026  
+**Status:** Validierte Tentacle-Opportunity (High Demand / Zero Title Moat)  
+**Datenbasis:** Original Google Keyword Planner & Apple Search Ads Validierung  
+**Ziel-Märkte:** Global (US Storefront Priorität #1, DE Storefront Priorität #2, ES/MX Priorität #3)  
+**Kernversprechen:** *„Foto machen → Daten stimmen → Excel ist fertig.“*  
+
+---
+
+## 📌 1. Executive Summary & Die Tentacle-Chance
+
+Mega-Apps wie *CamScanner*, *Adobe Scan*, *QuickBooks* und *Expensify* generieren monatlich Millionenumsätze, sind jedoch für den schnellen Alltagseinsatz **überladen, teuer ($15–$35/Monat)** und erfordern langwierige Registrierungen.
+
+Nutzer (Freelancer, Handwerker, Selbstständige, Außendienstler) suchen im App Store und bei Google gezielt nach einer **einzigen simplen Funktion**:  
+👉 **„Receipt Scanner to Excel“** (Kassenbon fotografieren $\rightarrow$ Beträge/MwSt. extrahieren $\rightarrow$ 1-Klick Excel/CSV Export).
+
+### 🔍 App Store SERP & Validierung
+- **Opportunity Score:** `84–99/100 🔥` (Globaler Durchschnitt)
+- **Titel-Besetzung Top 5:** **0 von 5** Apps in fast allen Stores nutzen das Exact-Match-Keyword im App-Titel.
+- **Wettbewerbslage:** Große Scanner-Apps ranken nur über generische Store-Autorität, nicht über ASO-Fokus.
+
+---
+
+## 🎯 2. Reale Google Keyword Planner Daten & Metriken (DE, US, ES/MX)
+
+### A. 🇩🇪 Deutschland / DACH-Markt (Google Keyword Planner)
+
+#### Top-Volumen Keywords (100 – 1.000 Suchen / Monat)
+| Keyword | Suchvolumen / Mo. | Wettbewerb | CPC (Gebot oben) | CPC (Gebot Spitzenwert) | Trend / Signal |
+| :--- | :---: | :---: | :---: | :---: | :--- |
+| **`belege scannen`** | 100 – 1.000 | Hoch | 2,03 € | 5,77 € | Stabiler B2B Core-Traffic |
+| **`belege scanner`** | 100 – 1.000 | Hoch | 1,83 € | 6,23 € | Hohe Kaufintention |
+| **`kassenbon scanner`** | 100 – 1.000 | Hoch | 1,01 € | 4,25 € | Kernbegriff für Kassenbons |
+| **`belege digitalisieren`** | 100 – 1.000 | Hoch | 1,78 € | 6,40 € | Vorbereitende Buchhaltung |
+| **`kassenbon scanner app kostenlos`** | 100 – 1.000 | Mittel | 0,80 € | 3,07 € | **🔥 +900 % Trend (Explodierend)** |
+| **`belege scannen und verwalten kostenlos`** | 100 – 1.000 | Hoch | 1,16 € | 2,82 € | Starker App-Suchbegriff |
+| **`belegscanner`** | 100 – 1.000 | Hoch | 1,02 € | 3,94 € | Single-Word Keyword |
+| **`scanner für belege`** | 100 – 1.000 | Hoch | 2,03 € | 5,77 € | Hardware/Software Switch |
+| **`app kassenbon scannen`** | 100 – 1.000 | Mittel | 1,37 € | 4,63 € | Mobile Intent |
+| **`scanner für rechnungen`** | 100 – 1.000 | Hoch | 1,23 € | 7,96 € | B2B Rechnungsverarbeitung |
+| **`datev scannen`** | 100 – 1.000 | Hoch | 1,06 € | 3,55 € | DATEV-Schnittstellen Intent |
+| **`kontieren der belege`** | 100 – 1.000 | Gering | 0,89 € | 3,22 € | Buchhaltungs-Nische |
+
+#### High-CPC & Exact-Match Nischen (10 – 100 Suchen / Monat)
+| Keyword | Suchvolumen / Mo. | Wettbewerb | CPC Min | CPC Max (Spitze) | Relevanz für Landingpage |
+| :--- | :---: | :---: | :---: | :---: | :--- |
+| **`kassenbon scannen excel`** | 10 – 100 | **Gering** | — | — | **🎯 Exact Match Goldnische (0 Moat!)** |
+| **`wiso mein büro belege scannen`** | 10 – 100 | Mittel | 2,26 € | **35,74 € 🔥** | Extrem kaufkräftige Selbstständige |
+| **`eingangsrechnungen digitalisieren`** | 10 – 100 | Mittel | 7,36 € | **18,26 €** | B2B Rechnungsimport |
+| **`lieferscheine scannen und archivieren`**| 10 – 100 | Hoch | 3,12 € | **12,14 €** | Handwerker & Logistik |
+| **`digitale belegerfassung`** | 10 – 100 | Hoch | 3,38 € | **11,96 €** | Kanzleien & Buchhalter |
+| **`buchhaltung digitale belege`** | 10 – 100 | Hoch | 1,99 € | **11,74 €** | Steuerberatung |
+| **`belege fotografieren app`** | 10 – 100 | Mittel | 3,95 € | 7,50 € | Mobile-First Intent |
+| **`rechnung scanner app`** | 10 – 100 | Mittel | 2,19 € | 8,65 € | App Store / Play Store Traffic |
+| **`tankbelege scannen`** | 10 – 100 | Mittel | 0,80 € | 3,86 € | Reisekosten & Fuhrpark |
+| **`quittungen scannen app`** | 10 – 100 | Hoch | 1,58 € | 5,08 € | Quittungs-Erfassung |
+
+---
+
+### B. 🇺🇸 US & Globaler Markt (Google Keyword Planner Englisch)
+
+#### High-Volume Keywords (1.000 – 10.000 Suchen / Monat)
+| Keyword | Suchvolumen / Mo. | Wettbewerb | CPC Min | CPC Max (Spitze) | Trend |
+| :--- | :---: | :---: | :---: | :---: | :--- |
+| **`receipt scanner`** | 1.000 – 10.000 | Hoch | 1,48 € | 9,43 € | Globaler Core-Suchbegriff |
+| **`receipt tracker`** | 1.000 – 10.000 | Mittel | 4,24 € | **25,94 €** | Expense Tracking |
+| **`receipt scanner app`** | 1.000 – 10.000 | Mittel | 1,79 € | 9,72 € | Mobile App Store Traffic |
+| **`best receipt scanner app`** | 1.000 – 10.000 | Mittel | 1,73 € | 9,26 € | High-Intent Vergleichssuche |
+| **`receipt apps`** | 1.000 – 10.000 | Mittel | 1,98 € | 12,79 € | Generische App-Suche |
+| **`ocr receipt scanner`** | 1.000 – 10.000 | **Gering** | 2,36 € | **11,91 €** | **🔥 +900 % Trend (AI OCR)** |
+| **`best app for receipt scanning`** | 1.000 – 10.000 | Mittel | 1,73 € | 9,26 € | Review-Traffic |
+| **`scan a receipt app`** | 1.000 – 10.000 | Mittel | 1,79 € | 9,72 € | Action-Intent |
+
+#### High-Value B2B & Software Keywords (100 – 1.000 Suchen / Monat)
+| Keyword | Suchvolumen / Mo. | Wettbewerb | CPC Min | CPC Max (Spitze) | Bemerkung |
+| :--- | :---: | :---: | :---: | :---: | :--- |
+| **`receipt tracking software`** | 100 – 1.000 | Gering | 9,63 € | **65,15 € 🔥** | Maximaler B2B-Kaufwert |
+| **`expensify receipt scanning`** | 100 – 1.000 | Gering | 0,60 € | **63,91 € 🔥** | **+900 % Trend (Konkurrenten-Alternative)** |
+| **`track expenses for small business`** | 100 – 1.000 | Mittel | 9,18 € | **48,01 €** | SMB Finance Intent |
+| **`best small business expense tracker`** | 100 – 1.000 | Mittel | 9,42 € | **41,97 €** | KMU Zielgruppe |
+| **`receipt tracker for business`** | 100 – 1.000 | Mittel | 8,45 € | **36,11 €** | B2B Spesen |
+| **`receipt scanning software`** | 100 – 1.000 | Mittel | 3,86 € | **23,64 €** | Desktop & Web SaaS |
+| **`invoice scanner`** | 100 – 1.000 | Mittel | 4,78 € | **23,53 €** | Rechnungsverarbeitung |
+| **`receipt scanner that categorizes`** | 100 – 1.000 | Hoch | 2,13 € | 9,22 € | **🔥 +900 % Trend (Auto-Kategorisierung)** |
+| **`ai receipt scanner`** | 100 – 1.000 | Mittel | 2,02 € | 13,89 € | KI-Positionierung |
+
+---
+
+## 📱 3. Fertiges ASO-Metadaten-Set (App Store & Play Store)
+
+### 🇺🇸 US & International Storefront (Englisch)
+- **App Title (29/30 Zeichen):** `Receipt Scanner to Excel: XLSX`
+- **Subtitle (30/30 Zeichen):** `Quick Scan Receipts & Invoices`
+- **Keywords Field (99/100 Zeichen):** `receipts,expense,tracker,invoice,export,tax,mileage,belege,buchhaltung,spesen,csv,ocr,accounting,sheet`
+- **Promotional Text (170 Zeichen):**
+  > Instant 1-tap receipt and invoice scanner with automatic Excel (.xlsx) & CSV export. No complicated setup, no expensive cloud subscriptions. Just scan & export.
+
+---
+
+### 🇩🇪 Deutscher Storefront (Lokalisiert)
+- **App Title (29/30 Zeichen):** `Beleg Scanner zu Excel: XLSX`
+- **Subtitle (29/30 Zeichen):** `Quittungen & Rechnungen Scan`
+- **Keywords Field (98/100 Zeichen):** `belege,quittung,ausgaben,buchhaltung,steuer,rechnung,spesen,finanzen,csv,tabelle,scanner,ocr,kassenbon`
+- **Promotional Text (168 Zeichen):**
+  > Kassenbons & Rechnungen mit 1 Klick scannen und direkt als fertige Excel-Tabelle (.xlsx) oder CSV teilen. Ideal für Steuerberater, Selbstständige und Spesenabrechnungen.
+
+---
+
+## 💰 4. Unit Economics & Margen-Kalkulation
+
+| Posten | Kennzahl / Kosten |
+| :--- | :--- |
+| **Input-Kosten (DeepSeek V4 Flash pro 1M):** | $\approx \$0.0679$ |
+| **Output-Kosten (DeepSeek V4 Flash pro 1M):** | $\approx \$0.1680$ |
+| **API-Kosten pro gescanntem Beleg:** | $\approx \$0.00015 - \$0.0008$ (< 0,1 Cent) |
+| **API-Kosten für 100 Belege (Monat):** | $\approx \$0.015 - \$0.08$ (**1,5 bis 8 Cent**) |
+| **Abo-Umsatz pro Nutzer:** | **4,99 € / Woche** oder **39,99 € / Jahr** |
+| **Lifetime-Option:** | **59,99 € Einmalkauf** (ca. 48,99 € Reingewinn nach Store-Fee) |
+| **Bruttomarge:** | **> 84% Reingewinn (> 98% Deckungsbeitrag)** |
+
+---
+
+## 💳 5. Monetarisierungs- & Paywall-Strategie
+
+| Modell | Preis | Konditionen / Vorteile | Trigger & Psychologie |
+| :--- | :--- | :--- | :--- |
+| **Free-Tier** | **0,00 €** | 5 kostenlose Scans pro Monat | Sofortiger Test ohne Reibung. |
+| **Weekly Pro** | **4,99 € / Woche** | 3 Tage kostenlos testen | Standard-Trigger beim 6. Scan oder beim Export. |
+| **Annual Pro** | **39,99 € / Jahr** | Entspricht 0,77 €/Woche (**70 % Ersparnis**) | Als `Bester Wert` optisch hervorgehoben. |
+| **Lifetime Lizenz** | **59,99 € Einmalkauf** | Einmal zahlen, lebenslang nutzen | Perfekt für deutsche Freelancer & Handwerker mit Abo-Aversion. |
+
+---
+
+## 🏗️ 6. Systemarchitektur & Robuster Server-Stack
+
+```mermaid
+flowchart TB
+    subgraph Clients ["1. Clients & Frontend"]
+        Web["Web-App / Landingpage (Next.js 15 / React)"]
+        Mobile["iOS & Android App (Capacitor.js)"]
+    end
+
+    subgraph Backend ["2. Backend Processing Layer (Node.js Server)"]
+        UploadAPI["Upload Route (/api/scan)"]
+        SharpEngine["sharp Engine (Drehen, Kontrast, Kompression)"]
+        PreCheck["SHA-256 Hash & Duplikat-Check"]
+        AISDK["Vercel AI SDK (generateObject + Zod)"]
+        ResolutionEngine["Receipt Resolution Agent"]
+        ExcelEngine["Excel Engine (exceljs)"]
+    end
+
+    subgraph Storage ["3. Daten & Services"]
+        Postgres[(PostgreSQL via Neon / Supabase + Drizzle)]
+        R2Storage["Cloudflare R2 / S3 (Beleg-Bilder)"]
+        LLM["DeepSeek V4 Flash / Vision Fallback"]
+        Stripe["Stripe Billing & Apple IAP"]
+        Discord["Discord Sales Webhook Bot"]
+    end
+
+    Web --> UploadAPI
+    Mobile --> UploadAPI
+    UploadAPI --> SharpEngine
+    SharpEngine --> R2Storage
+    SharpEngine --> PreCheck
+    PreCheck <--> Postgres
+    PreCheck --> AISDK
+    AISDK <--> LLM
+    AISDK --> ResolutionEngine
+    ResolutionEngine <--> Postgres
+    ResolutionEngine --> ExcelEngine
+    Stripe --> Discord
+```
+
+---
+
+## ⚡ 7. Die 5-stufige Beleg-Pipeline
+
+1. **Upload & SHA-256 Hash:** Sofortiger Hash-Abgleich gegen PostgreSQL (Duplikat-Prävention).
+2. **Bildoptimierung (`sharp`):** Auto-Rotate, Kontrast-Boost für Thermopapier, Skalierung auf max. 1600 px.
+3. **Strukturierte Extraktion mit Confidence-Scores:** Zod-Schema mit Confidence pro Feld, `taxBreakdown` und `lineItems`.
+4. **Deterministische Plausibilitätsprüfung:** Netto + MwSt = Brutto, Summe(Positionen) = Brutto.
+5. **Receipt Resolution Agent:** Schlägt Händler-Kategorisierungen vor und fragt nur bei unklaren Feldern nach (*„Datum 14.08.2026? [Ja] [Ändern]“*).
+
+---
+
+## 🗄️ 8. Zod Schema & PostgreSQL Schema
+
+### Zod Extraktions-Schema (`src/lib/schema/receipt.ts`)
+
+```typescript
+import { z } from 'zod';
+
+export const ReceiptExtractionSchema = z.object({
+  merchant: z.object({
+    name: z.string().describe("Name des Händlers"),
+    address: z.string().nullable(),
+    taxId: z.string().nullable(),
+    confidence: z.number().min(0).max(1),
+  }),
+  date: z.object({
+    isoDate: z.string().describe("Belegdatum YYYY-MM-DD"),
+    time: z.string().nullable(),
+    confidence: z.number().min(0).max(1),
+  }),
+  documentType: z.enum(["KASSENBON", "RECHNUNG", "TANKBELEG", "BEWIRTUNGSBELEG", "PARKTICKET", "SONSTIGES"]),
+  receiptNumber: z.string().nullable(),
+  currency: z.string().default("EUR"),
+  totalAmount: z.object({
+    value: z.number().describe("Bruttobetrag"),
+    confidence: z.number().min(0).max(1),
+  }),
+  netAmount: z.number().nullable(),
+  taxBreakdown: z.array(z.object({
+    ratePercent: z.number(),
+    taxAmount: z.number(),
+    netAmount: z.number().nullable(),
+  })),
+  lineItems: z.array(z.object({
+    description: z.string(),
+    quantity: z.number().default(1),
+    price: z.number(),
+    taxRate: z.number().nullable(),
+  })),
+  suggestedCategory: z.enum(["Bewirtung", "Reisekosten & Hotel", "Tanken & KFZ", "Bürobedarf & IT", "Verpflegungsmehraufwand", "Material & Einkauf", "Sonstiges"]),
+  validation: z.object({
+    isMathValid: z.boolean(),
+    isDuplicateSuspected: z.boolean().default(false),
+    needsUserReview: z.boolean(),
+    reviewField: z.enum(["none", "date", "totalAmount", "taxBreakdown", "merchant"]).default("none"),
+    reviewReason: z.string().nullable(),
+  })
+});
+
+export type ReceiptData = z.infer<typeof ReceiptExtractionSchema>;
+```
+
+---
+
+## 📊 9. Excel- & CSV-Export Spezifikation
+
+* **Tabellenblatt 1 („Belegübersicht“):** Lfd. Nr., Belegdatum, Händler, Kategorie, Belegnummer, Netto, MwSt 7%, MwSt 19%, Brutto, Status mit formatierten Währungen und `=SUMME()` Formeln.
+* **Tabellenblatt 2 („Einzelpositionen Detail“):** Alle Einzelartikel jedes Belegs.
+* **DATEV-kompatible CSV:** UTF-8 mit BOM, Semikolon-getrennt.