Unternehmensdokumentation

Unternehmensdokumentation

Die interne Anleitungssammlung (SOPs, Checklisten, Wissensartikel, Gesprächsleitfäden) liegt im Monorepo unter apps/mentor-docs und wird als Astro Starlight-Site auf Cloudflare Pages veröffentlicht.

Öffentliche Site (aktuell):

nextra-documentation-mentor.pages.dev

(Domain kann nach dem Pages-Deploy aus dem Monorepo auf das Projekt mentor-docs umziehen.)

Der WhatsApp/Discord-Assistent liest dieselben Markdown/MDX-Quellen über die Internal-API (/api/internal/agent/knowledge), nicht über die öffentliche Pages-URL.

Deploy und Storage-URLs

Der Monorepo-Workflow baut die Starlight-Site in GitHub Actions und lädt nur dist/ per wrangler pages deploy hoch. Dabei setzt CI:

PUBLIC_STORAGE_URL=https://mentor-docs.${{ vars.S3_ENDPOINT }}

(z. B. https://mentor-docs.nbg1.your-objectstorage.com — virtual-host, analog zur Web-App).

Cloudflare-Pages-Umgebungsvariablen greifen bei diesem Deploy nicht (kein CF-Build).

Einmalig im Cloudflare Dashboard erledigen:

1. Pages-Projekt mentor-docs (bzw. nextra-documentation-mentor) öffnen → Settings → Builds → Git-Integration zum alten Repo Disconnect — Deployments nur noch über das Monorepo.
2. Falls dort noch PUBLIC_STORAGE_URL steht: auf https://mentor-docs.nbg1.your-objectstorage.com ändern (ohne trailing slash) oder entfernen — path-style (https://nbg1.your-objectstorage.com/mentor-docs) ist falsch und wirkungslos für Wrangler-Deploys.

Dateien hochladen

PDFs, Bilder und andere Dateien für die Dokumentation werden weiterhin von Administratoren in dieser App verwaltet:

1. Gehen Sie zu Admin → Dokumente
2. Wählen Sie den passenden Bucket und Ordner
3. Laden Sie die Datei hoch

Die hochgeladenen Dateien liegen auf Hetzner Object Storage und können in der Starlight-Doku per URL verlinkt werden.

Ordnerstruktur einrichten

Jeder registrierte Bucket hat eine eigene Ordnerstruktur. Sie wird als versteckte Config-Datei .dokumente-structure.json am Bucket-Root gespeichert (S3-Key ohne führenden Schrägstrich). Die Datei erscheint nicht in der Dateiliste der Admin-UI.

Beispielinhalt:

{
  "version": 1,
  "prefixes": [
    "blog/",
    "listings/",
    "listings/hero/"
  ]
}

Regeln für Ordner-Prefixes:

• Nur Kleinbuchstaben, Ziffern, _, -, /
• Muss mit / enden (z. B. bilder/, nicht bilder)
• Kein ..
• Max. 512 Zeichen pro Prefix, max. 200 Einträge

Empfohlen: Über die Admin-UI

Manuelles Anlegen der JSON-Datei ist nicht nötig. Beim ersten Ordner schreibt die App die Config automatisch in den gewählten Bucket:

1. Ziel-Bucket oben rechts wählen (z. B. „Bilder“)
2. Tab Ordner öffnen
3. Neuer Ordner klicken und Prefix eingeben (z. B. blog/)
4. Speichern

Danach erscheinen die Ordner im Tab Upload unter Zielordner.

Verhalten pro Bucket

Situation	Ergebnis
Standard-Bucket „Dokumente“, keine Config-Datei	Vordefinierte Default-Struktur (anleitungen/, …)
Anderer Bucket, keine Config-Datei, aber Dateien im Bucket	Ordner werden aus den S3-Objekt-Keys abgeleitet (z. B. listings/123/image.jpg → listings/, listings/123/)
Config-Datei vorhanden	Vereinigung aus Config-Einträgen und abgeleiteten Prefixes

Die Datei .dokumente-structure.json ist im Hetzner-Dashboard oft nicht sichtbar (Key beginnt mit .). Sie wird erst beim Anlegen eines Ordners über die Admin-UI geschrieben.

Ordner vs. echte S3-Ordner

Die Config definiert nur die erlaubten Upload-Ziele in der UI. S3 hat keine echten Verzeichnisse — erst beim Upload einer Datei (z. B. blog/mein-bild.png) entsteht das Objekt mit diesem Key-Prefix. Umbenennen und Löschen im Tab Ordner aktualisiert die Config-Datei und die Objekte im Bucket.

Alternative: API oder S3-CLI

API (als Admin, bucketId = Slug aus D1, nicht der Hetzner-Bucket-Name):

PUT /api/admin/dokumente/structure
Content-Type: application/json

{
  "prefixes": ["blog/", "listings/"],
  "bucketId": "bilder"
}

Manuell in Hetzner Object Storage: JSON mit Key .dokumente-structure.json in den richtigen Bucket hochladen (storage_buckets.bucket in D1).