hyprcrd/support-relay/README.md

# Support-Relay — Setup

Nimmt anonyme Support-Anfragen per Web-Formular entgegen, legt sie in
einer lokalen SQLite-DB ab, versendet Bestätigungs- und Antwort-Mails
per SMTP. Hyprcrd zieht sich die Tickets und antwortet durch diesen
Relay hindurch. **Single-user** — ein Admin, ein API-Key.

## Lokal testen mit Docker (einfachster Weg)

```sh
cd support-relay
docker compose up -d --build
```

Danach `http://localhost:8090/` im Browser öffnen → Setup-Wizard. Kein
Host-Setup nötig. Die DB und der master-key landen im lokalen
`./data/`-Ordner und überleben `docker compose down`.

Zum Rücksetzen (neuer API-Key, leere DB):

```sh
rm -f data/support.db data/support.db-* data/master.key
docker compose restart
```

Stoppen: `docker compose down`.

---

## Was du für Production brauchst

- Eine Subdomain, z.B. `support.oumta.de`
- PHP ≥ 8.1 mit `pdo_sqlite` und `openssl`
- Apache mit `mod_rewrite` (oder nginx mit äquivalentem Rewrite)
- Einen SMTP-Zugang (Mailserver, Mailtrap, Office365, was auch immer)

---

## 1. Upload

Den kompletten Ordner `support-relay/` als Document-Root der Subdomain
hochladen. Die Struktur sollte am Host so aussehen:

```
support.oumta.de/
├── index.php
├── .htaccess
├── inc/
├── ui/
└── data/          ← muss vom Webserver schreibbar sein!
```

**`data/` schreibbar machen** (SSH):

```sh
chmod 755 data
```

Der Webserver legt dort `support.db` und `master.key` an. `master.key`
kriegt automatisch `chmod 600`.

---

## 2. Erster Aufruf → Setup-Wizard

`https://support.oumta.de/` im Browser öffnen. Wenn `data/` schreibbar
ist, erscheint automatisch der Setup-Wizard. Ausfüllen:

| Feld | Was eintragen |
|---|---|
| **Display name** | `Oumta Support` (wird Absendername, Subject-Präfix, Footer) |
| **Issue-prefix** | `OUMTA` (Tickets heißen dann `OUMTA-1`, `OUMTA-2`, …) |
| **Host** | z.B. `smtp.office365.com` / `smtp.mailtrap.io` / eigener Mailserver |
| **Port** | `587` (STARTTLS — Standard) |
| **Encryption** | `STARTTLS (587)` lassen, außer dein Server will was anderes |
| **Username** | SMTP-User |
| **Password** | SMTP-Passwort (wird verschlüsselt abgelegt) |
| **From address** | z.B. `support@oumta.de` |
| **From name** | `Oumta Support` |

**Speichern** drücken. Die nächste Seite zeigt einen langen **API-Key**.
Kopieren und sicher aufheben — wird **exakt einmal** angezeigt.

Nach dem Setup ist diese Seite nicht mehr erreichbar. Stattdessen zeigt
`/` jetzt das öffentliche Support-Formular.

---

## 3. Hyprcrd verbinden

In hyprcrd:

1. Zwei Buckets anlegen (falls noch nicht vorhanden):
   - **Support Inbox** — hier landen eingehende Tickets als Karten
   - **Support KB** — hier liegen deine wiederverwendbaren Antwort-Bausteine
2. Settings (Zahnrad) öffnen → Tab **support**
3. Eintragen:
   - **Relay URL**: `https://support.oumta.de`
   - **API key**: der gerade kopierte Key
   - **Inbox bucket**: `Support Inbox`
   - **KB bucket**: `Support KB`
4. **Save** → **Test connection** → muss grün zurückkommen
   (`OK — relay says "Oumta Support"`)

---

## 4. Smoke-Test

**a) Ticket einreichen**

In einem Inkognito-Tab `https://support.oumta.de/` öffnen, eine
Testanfrage absenden. Erwartung:

- Grüner Banner: `Received. Your issue id is OUMTA-1.`
- Bestätigungsmail im Posteingang

**b) Ticket in hyprcrd**

Oben rechts den **Support**-Button im Header klicken → Overlay auf.
Auf den Reload-Knopf (↻) klicken, dann erscheint das Ticket in der
Liste. Im "Support Inbox"-Bucket liegt eine Karte mit derselben Info.

**c) Antworten**

Ticket anklicken → ins Textfeld tippen → **Send reply**. Erwartung:

- Status wechselt auf `answered`
- Mail landet im Posteingang des Absenders

**d) Fragment speichern**

Nach dem Tippen **Save as fragment** → Titel vergeben → die Antwort
taucht im KB-Bucket als Karte auf und wird ab sofort im Suchfeld
über dem Composer gefunden.

---

## 5. Normaler Betrieb

- **Neue Tickets sehen**: Support-Overlay in hyprcrd. Pollt automatisch
  bei jedem Sync-Tick; manueller Pull per ↻-Knopf.
- **Antworten**: aus dem Composer heraus, SMTP läuft über den Relay.
- **Status setzen**: `open` → `answered` (automatisch bei Reply) →
  `closed` (manuell per Button).
- **User antwortet auf eine Mail**: er muss seine **Issue-ID**
  (`OUMTA-n`) erneut ins Formular eintragen. Dann wird die Nachricht
  an das bestehende Ticket gehängt (nur wenn die Email matcht, sonst
  wird daraus ein neues Ticket).

---

## Troubleshooting

**Setup-Wizard kommt nicht**
`data/` ist nicht schreibbar. → `chmod 755 data/` (oder 775) und neu
laden.

**"Test connection" schlägt fehl**
Relay-URL falsch (Trailing-Slash ist OK, aber HTTPS muss stimmen) oder
API-Key nicht exakt übernommen.

**Confirmation-Mail kommt nicht**
SMTP-Creds falsch oder Port blockiert. Direkt vom Host testen:

```sh
php -r '
  require "inc/bootstrap.php"; require "inc/SmtpClient.php";
  $c = supportRelaySmtpConfig(Database::connect(), $MASTER_KEY);
  $r = (new SmtpClient($c))->send("du@example.com", $c["from_name"], $c["from"],
    "ping", ["Subject" => "SMTP ping"]);
  print_r($r);
'
```

Der `log`-Array zeigt die SMTP-Konversation.

**Alles kaputt, von vorn anfangen**
`data/support.db` und `data/master.key` löschen. Nächster Aufruf
startet wieder im Setup-Wizard — der API-Key ändert sich dann,
musst du in hyprcrd neu eintragen.

---

## Dateien

| Pfad | Zweck |
|---|---|
| `index.php` | Entry-Point + Routing |
| `inc/bootstrap.php` | DB-Schema, Settings, Helpers |
| `inc/SmtpClient.php` | Minimaler SMTP-Client |
| `inc/routes/*.php` | Public / Setup / Hyprcrd-API |
| `ui/*.php` | Form, Setup-Wizard, Status-Seite |
| `ui/style.css` | Styling |
| `data/support.db` | SQLite DB (tickets, replies, settings) |
| `data/master.key` | Verschlüsselt SMTP-Passwort (chmod 600) |

Gute Nacht 🌙