eship/setup/USERS_COLLECTION_SETUP.md

# Users Collection Setup & Permissions

Diese Anleitung erklärt, wie du die `users` Collection in Appwrite einrichtest und die richtigen Permissions setzt.

## Problem: 401 Unauthorized

Wenn du beim Erstellen eines User-Dokuments einen **401 Unauthorized** Fehler bekommst, bedeutet das, dass die Permissions der Collection nicht richtig gesetzt sind.

## Lösung: Collection erstellen und Permissions setzen

### Schritt 1: Collection-ID ermitteln oder erstellen

#### Option A: Collection bereits vorhanden

Prüfe, ob die Collection bereits existiert:

```bash
cd Server
appwrite login
appwrite databases list-collections --database-id eship-db
```

Suche nach einer Collection mit dem Namen "users" oder einer ID, die du verwenden möchtest.

#### Option B: Collection erstellen

Falls die Collection nicht existiert, erstelle sie:

```bash
appwrite databases create-collection \
  --database-id eship-db \
  --collection-id users \
  --name "Users"
```

**Wichtig**: Notiere dir die `$id` der erstellten Collection. Falls die Collection-ID nicht "users" ist, musst du sie in der `.env` Datei setzen:

```
VITE_APPWRITE_USERS_COLLECTION_ID=<deine-collection-id>
```

### Schritt 2: Attribute hinzufügen

Die Collection braucht ein `user_name` Feld (String):

```bash
appwrite databases create-string-attribute \
  --database-id eship-db \
  --collection-id users \
  --key user_name \
  --size 255 \
  --required true
```

**Wichtig**: Warte, bis das Attribute erstellt wurde (Status: "available"). Das kann einige Sekunden dauern.

### Schritt 3: Permissions setzen

Das ist der wichtigste Schritt! Die Collection muss erlauben, dass:
- Authentifizierte User Dokumente lesen können
- Authentifizierte User Dokumente erstellen können (für ihr eigenes Dokument)

#### Über die Appwrite-Konsole (empfohlen)

1. Öffne die Appwrite-Konsole: `https://appwrite.webklar.com`
2. Gehe zu: **Databases** → **eship-db** → **users** Collection
3. Klicke auf **Settings** → **Permissions**
4. Füge folgende Permissions hinzu:

**Create Permission:**
- Role: `users`
- Erlaube: **create**

**Read Permission:**
- Role: `users`
- Erlaube: **read**

**Update Permission (optional, falls du Updates brauchst):**
- Role: `users`
- Erlaube: **update**

**Delete Permission (optional):**
- Role: `users`
- Erlaube: **delete**

#### Über die CLI

```bash
# Create Permission
appwrite databases create-collection-create-rule \
  --database-id eship-db \
  --collection-id users \
  --role users

# Read Permission
appwrite databases create-collection-read-rule \
  --database-id eship-db \
  --collection-id users \
  --role users

# Optional: Update Permission
appwrite databases create-collection-update-rule \
  --database-id eship-db \
  --collection-id users \
  --role users

# Optional: Delete Permission
appwrite databases create-collection-delete-rule \
  --database-id eship-db \
  --collection-id users \
  --role users
```

**Hinweis**: Die CLI-Befehle können je nach Appwrite-Version variieren. Wenn sie nicht funktionieren, verwende die Web-Konsole.

### Schritt 4: Document-ID-Permissions

Da wir die Auth-User-ID als Document-ID verwenden, muss Appwrite erlauben, dass User ihre eigene Document-ID verwenden können.

In der Appwrite-Konsole:
1. Gehe zu: **Databases** → **eship-db** → **users** → **Settings**
2. Stelle sicher, dass **"Allow users to specify their own document IDs"** aktiviert ist
   - Oder setze: **"Document ID Generation"** auf **"User provided"**

### Schritt 5: Überprüfung

Nach dem Setup sollte:
- ✅ Ein eingeloggter User Dokumente lesen können
- ✅ Ein eingeloggter User sein eigenes Dokument erstellen können (mit seiner Auth-User-ID als Document-ID)

## Häufige Probleme

### Problem: "Collection not found"

**Lösung**: Prüfe, ob die Collection-ID korrekt ist:
```bash
appwrite databases list-collections --database-id eship-db
```
Stelle sicher, dass `VITE_APPWRITE_USERS_COLLECTION_ID` in der `.env` die richtige ID enthält.

### Problem: "Attribute not found"

**Lösung**: Prüfe, ob das `user_name` Attribute existiert:
```bash
appwrite databases list-attributes \
  --database-id eship-db \
  --collection-id users
```

### Problem: "Permission denied"

**Lösung**: Stelle sicher, dass die Permissions für die Rolle `users` gesetzt sind. In der Appwrite-Konsole:
- Gehe zu **Settings** → **Permissions**
- Prüfe, ob `create` und `read` für `users` aktiviert sind

## Alternative: Restriktivere Permissions (sicherer)

Falls du sicherer sein möchtest, dass User nur ihr eigenes Dokument lesen/erstellen können:

1. In der Appwrite-Konsole: Gehe zu **Settings** → **Permissions**
2. Verwende **Custom Permissions** mit Filtern:
   - Read: `$userId = request.auth.userId`
   - Create: `$userId = request.auth.userId`
   - Update: `$userId = request.auth.userId`

Dies stellt sicher, dass User nur Zugriff auf ihr eigenes Dokument haben.

## Nächste Schritte

Nach dem Setup:
1. Lade die Web-App neu
2. Logge dich ein
3. Du solltest den Welcome-Screen sehen
4. Beim Klick auf "Jetzt starten" sollte das User-Dokument erstellt werden (kein 401-Fehler mehr)