# MailFlow - Einrichtungsanleitung

Diese Anleitung führt dich durch die komplette Einrichtung von MailFlow.

---

## Inhaltsverzeichnis

1. [Voraussetzungen](#voraussetzungen)
2. [Appwrite einrichten](#1-appwrite-einrichten)
3. [Stripe einrichten](#2-stripe-einrichten)
4. [Google OAuth einrichten](#3-google-oauth-einrichten-gmail)
5. [Microsoft OAuth einrichten](#4-microsoft-oauth-einrichten-outlook)
6. [Mistral AI einrichten](#5-mistral-ai-einrichten)
7. [Projekt starten](#6-projekt-starten)
8. [Fehlerbehebung](#fehlerbehebung)

---

## Voraussetzungen

- Node.js 18+ installiert
- npm oder yarn
- Git

---

## 1. Appwrite einrichten

### 1.1 Account erstellen

1. Gehe zu [cloud.appwrite.io](https://cloud.appwrite.io)
2. Erstelle einen kostenlosen Account
3. Erstelle ein neues Projekt (z.B. "MailFlow")

### 1.2 API Key erstellen

1. Gehe zu **Settings** → **API Credentials**
2. Klicke auf **Create API Key**
3. Name: `MailFlow Backend`
4. Wähle **alle Berechtigungen** aus (Full Access)
5. Kopiere den API Key

### 1.3 Datenbank erstellen

1. Gehe zu **Databases**
2. Klicke auf **Create Database**
3. Name: `mailflow_db`
4. Kopiere die **Database ID**

### 1.4 Bootstrap ausführen

```bash
cd server
npm run bootstrap:v2
```

Dies erstellt automatisch alle benötigten Collections:
- `products`
- `questions`
- `submissions`
- `answers`
- `orders`
- `email_accounts`
- `email_stats`
- `subscriptions`
- `user_preferences`

### 1.5 .env konfigurieren

```env
# server/.env
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_PROJECT_ID=deine_projekt_id
APPWRITE_API_KEY=dein_api_key
APPWRITE_DATABASE_ID=mailflow_db
```

```env
# client/.env
VITE_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
VITE_APPWRITE_PROJECT_ID=deine_projekt_id
```

---

## 2. Stripe einrichten

### 2.1 Account erstellen

1. Gehe zu [dashboard.stripe.com](https://dashboard.stripe.com)
2. Erstelle einen Account
3. Wechsle in den **Test Mode** (Toggle oben rechts)

### 2.2 API Keys kopieren

1. Gehe zu **Developers** → **API keys**
2. Kopiere den **Secret key** (beginnt mit `sk_test_`)

### 2.3 Produkte erstellen

Gehe zu **Products** → **Add product**:

#### Basic Plan
- Name: `MailFlow Basic`
- Preis: `9.00 EUR` / Monat
- Kopiere die **Price ID** (beginnt mit `price_`)

#### Pro Plan
- Name: `MailFlow Pro`
- Preis: `19.00 EUR` / Monat
- Kopiere die **Price ID**

#### Business Plan
- Name: `MailFlow Business`
- Preis: `49.00 EUR` / Monat
- Kopiere die **Price ID**

### 2.4 Webhook einrichten

1. Gehe zu **Developers** → **Webhooks**
2. Klicke auf **Add endpoint**
3. URL: `https://deine-domain.de/api/subscription/webhook`
   - Für lokale Tests: Nutze [Stripe CLI](https://stripe.com/docs/stripe-cli)
4. Events auswählen:
   - `checkout.session.completed`
   - `customer.subscription.updated`
   - `customer.subscription.deleted`
   - `invoice.payment_failed`
   - `invoice.payment_succeeded`
5. Kopiere das **Signing Secret** (beginnt mit `whsec_`)

### 2.5 Lokaler Webhook-Test mit Stripe CLI

```bash
# Installieren
# Windows: scoop install stripe
# Mac: brew install stripe/stripe-cli/stripe

# Login
stripe login

# Webhook forwarden
stripe listen --forward-to localhost:3000/api/subscription/webhook
```

### 2.6 .env konfigurieren

```env
# server/.env
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_BASIC=price_...
STRIPE_PRICE_PRO=price_...
STRIPE_PRICE_BUSINESS=price_...
```

---

## 3. Google OAuth einrichten (Gmail)

### 3.1 Google Cloud Projekt erstellen

1. Gehe zu [console.cloud.google.com](https://console.cloud.google.com)
2. Erstelle ein neues Projekt (oder wähle ein bestehendes)

### 3.2 Gmail API aktivieren

1. Gehe zu **APIs & Services** → **Library**
2. Suche nach "Gmail API"
3. Klicke auf **Enable**

### 3.3 OAuth Consent Screen

1. Gehe zu **APIs & Services** → **OAuth consent screen**
2. Wähle **External**
3. Fülle aus:
   - App name: `MailFlow`
   - User support email: Deine E-Mail
   - Developer contact: Deine E-Mail
4. **Scopes** hinzufügen:
   - `https://www.googleapis.com/auth/gmail.modify`
   - `https://www.googleapis.com/auth/gmail.labels`
   - `https://www.googleapis.com/auth/userinfo.email`
5. **Test users** hinzufügen (während der Entwicklung)

### 3.4 OAuth Credentials erstellen

1. Gehe zu **APIs & Services** → **Credentials**
2. Klicke auf **Create Credentials** → **OAuth client ID**
3. Typ: **Web application**
4. Name: `MailFlow Web`
5. **Authorized redirect URIs**:
   - `http://localhost:3000/api/oauth/gmail/callback` (Entwicklung)
   - `https://deine-domain.de/api/oauth/gmail/callback` (Produktion)
6. Kopiere **Client ID** und **Client Secret**

### 3.5 .env konfigurieren

```env
# server/.env
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
GOOGLE_REDIRECT_URI=http://localhost:3000/api/oauth/gmail/callback
```

---

## 4. Microsoft OAuth einrichten (Outlook)

### 4.1 Azure App Registration

1. Gehe zu [portal.azure.com](https://portal.azure.com)
2. Suche nach "App registrations"
3. Klicke auf **New registration**
4. Name: `EmailSorter`
5. Supported account types: **Accounts in any organizational directory and personal Microsoft accounts**
6. Redirect URI: `Web` → `http://localhost:3000/api/oauth/outlook/callback`

### 4.2 Client Secret erstellen

1. Gehe zu **Certificates & secrets**
2. Klicke auf **New client secret**
3. Description: `EmailSorter Backend`
4. Expires: `24 months`
5. Kopiere den **Value** (wird nur einmal angezeigt!)

### 4.3 API Permissions

1. Gehe zu **API permissions**
2. Klicke auf **Add a permission** → **Microsoft Graph** → **Delegated permissions**
3. Füge hinzu:
   - `Mail.ReadWrite`
   - `User.Read`
   - `offline_access`
4. Klicke auf **Grant admin consent** (falls möglich)

### 4.4 .env konfigurieren

```env
# server/.env
MICROSOFT_CLIENT_ID=xxx-xxx-xxx
MICROSOFT_CLIENT_SECRET=xxx
MICROSOFT_REDIRECT_URI=http://localhost:3000/api/oauth/outlook/callback
```

---

## 5. Mistral AI einrichten

### 5.1 Account erstellen

1. Gehe zu [console.mistral.ai](https://console.mistral.ai)
2. Erstelle einen Account
3. Gehe zu **API Keys**
4. Klicke auf **Create new key**
5. Kopiere den API Key

### 5.2 .env konfigurieren

```env
# server/.env
MISTRAL_API_KEY=dein_mistral_api_key
```

---

## 6. Projekt starten

### 6.1 Dependencies installieren

```bash
# Backend
cd server
npm install

# Frontend
cd ../client
npm install
```

### 6.2 Environment Files erstellen

```bash
# Server
cp server/env.example server/.env
# Fülle die Werte aus!

# Client
cp client/env.example client/.env
# Fülle die Werte aus!
```

### 6.3 Datenbank initialisieren

```bash
cd server
npm run bootstrap:v2
```

### 6.4 Server starten

```bash
# Terminal 1 - Backend
cd server
npm run dev

# Terminal 2 - Frontend
cd client
npm run dev
```

### 6.5 Öffnen

- **Frontend**: http://localhost:5173
- **Backend API**: http://localhost:3000
- **API Docs**: http://localhost:3000

---

## Fehlerbehebung

### "APPWRITE_PROJECT_ID is not defined"

Stelle sicher, dass die `.env` Datei existiert und die Variablen gesetzt sind.

### "Invalid OAuth redirect URI"

Die Redirect URI in der OAuth-Konfiguration muss **exakt** mit der in der `.env` übereinstimmen.

### "Rate limit exceeded"

- Gmail: Max 10.000 Requests/Tag
- Outlook: Max 10.000 Requests/App/Tag

### "Mistral AI: Model not found"

Prüfe, ob der API Key gültig ist und das Guthaben ausreicht.

### "Stripe webhook signature invalid"

- Nutze das korrekte Webhook Secret (`whsec_...`)
- Bei lokalem Test: Nutze die Stripe CLI

### Microsoft OAuth: "Client credential must not be empty"

Stelle sicher, dass `MICROSOFT_CLIENT_ID` und `MICROSOFT_CLIENT_SECRET` gesetzt sind. Falls du Outlook nicht nutzen möchtest, kannst du diese leer lassen - der Server startet trotzdem.

---

## Checkliste

- [ ] Appwrite Projekt erstellt
- [ ] Appwrite API Key erstellt
- [ ] Appwrite Database erstellt
- [ ] Bootstrap ausgeführt (`npm run bootstrap:v2`)
- [ ] Stripe Account erstellt
- [ ] Stripe Produkte erstellt (Basic, Pro, Business)
- [ ] Stripe Webhook eingerichtet
- [ ] Google OAuth Credentials erstellt (optional)
- [ ] Microsoft App Registration erstellt (optional)
- [ ] Mistral AI API Key erstellt
- [ ] Alle `.env` Dateien konfiguriert
- [ ] Server startet ohne Fehler
- [ ] Frontend startet ohne Fehler

---

## Support

Bei Fragen oder Problemen:
- GitHub Issues
- support@emailsorter.de
