docs(universal-features): comprehensive update with all collections and blocks

- Add Production API endpoints for frontend integration
- Add Newsletter API documentation with Double Opt-In flow
- Add FAQs, Team, Services, Timelines, Workflows collections
- Add FAQ, Team, Services blocks documentation
- Update all URLs to production (cms.c2sgmbh.de)
- Add Block overview table
- Add Tenant-IDs reference
- Update file structure overview
- Add changelog entries for v1.1 and v1.2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Martin Porwoll 2025-12-18 16:10:31 +00:00
parent d5afc43f9d
commit 6d40d81a44

View file

@ -1,8 +1,59 @@
# Universal Features - Dokumentation # Universal Features - Dokumentation
*Letzte Aktualisierung: 18. Dezember 2025*
## Übersicht ## Übersicht
Die Universal Features erweitern das Payload CMS um wiederverwendbare Collections und Blocks für Blog, News, Testimonials, Newsletter und Prozess-Darstellungen. Alle Features sind Multi-Tenant-fähig. Die Universal Features erweitern das Payload CMS um wiederverwendbare Collections und Blocks für Blog, News, Testimonials, Newsletter, FAQ, Team und Prozess-Darstellungen. Alle Features sind Multi-Tenant-fähig.
**Wichtig:** Frontends verwenden die **Production-API** (cms.c2sgmbh.de).
---
## API-Endpoints für Frontend
### Collections
| Collection | Endpoint | Beschreibung |
|------------|----------|--------------|
| Posts | `GET /api/posts` | Blog, News, Presse |
| Testimonials | `GET /api/testimonials` | Kundenbewertungen |
| FAQs | `GET /api/faqs` | FAQ-Einträge |
| Team | `GET /api/team` | Team-Mitglieder |
| Services | `GET /api/services` | Leistungen |
| Timelines | `GET /api/timelines` | Chronologische Events |
| Workflows | `GET /api/workflows` | Prozess-Darstellungen |
### Beispiel: Posts laden
```typescript
// Featured Blog-Posts für Tenant C2S laden
const posts = await fetch(
'https://cms.c2sgmbh.de/api/posts?where[tenant][equals]=4&where[type][equals]=blog&where[isFeatured][equals]=true&locale=de&limit=6'
).then(r => r.json())
```
### Newsletter API
| Endpoint | Methode | Beschreibung |
|----------|---------|--------------|
| `/api/newsletter/subscribe` | POST | Newsletter-Anmeldung |
| `/api/newsletter/confirm` | GET/POST | Double Opt-In Bestätigung |
| `/api/newsletter/unsubscribe` | GET/POST | Abmeldung |
```typescript
// Newsletter-Anmeldung
const response = await fetch('https://cms.c2sgmbh.de/api/newsletter/subscribe', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'user@example.com',
firstName: 'Max',
tenantId: 4,
source: 'footer'
})
})
```
--- ---
@ -31,7 +82,7 @@ Die Posts Collection dient zur Verwaltung von Blog-Artikeln, News, Pressemitteil
| `author` | Text | Autorname | Nein | | `author` | Text | Autorname | Nein |
| `status` | Select | draft/published/archived | Nein | | `status` | Select | draft/published/archived | Nein |
| `publishedAt` | Date | Veröffentlichungsdatum | Nein | | `publishedAt` | Date | Veröffentlichungsdatum | Nein |
| `seo` | Group | SEO-Einstellungen | Nein | | `meta` | Group | SEO-Einstellungen | Nein |
#### Post-Typen #### Post-Typen
@ -40,11 +91,6 @@ Die Posts Collection dient zur Verwaltung von Blog-Artikeln, News, Pressemitteil
- `press` - Pressemitteilung - `press` - Pressemitteilung
- `announcement` - Ankündigung - `announcement` - Ankündigung
#### Access Control
- **Read:** Öffentlich für veröffentlichte Beiträge des eigenen Tenants
- **Create/Update/Delete:** Nur authentifizierte Benutzer
--- ---
### 2. Testimonials Collection ### 2. Testimonials Collection
@ -71,11 +117,6 @@ Kundenstimmen und Bewertungen für Referenz-Seiten.
| `isActive` | Checkbox | Sichtbarkeit | Nein | | `isActive` | Checkbox | Sichtbarkeit | Nein |
| `order` | Number | Sortierung | Nein | | `order` | Number | Sortierung | Nein |
#### Access Control
- **Read:** Öffentlich für aktive Testimonials des eigenen Tenants
- **Create/Update/Delete:** Nur authentifizierte Benutzer
--- ---
### 3. Newsletter Subscribers Collection ### 3. Newsletter Subscribers Collection
@ -84,7 +125,7 @@ Kundenstimmen und Bewertungen für Referenz-Seiten.
**Slug:** `newsletter-subscribers` **Slug:** `newsletter-subscribers`
**Admin-Gruppe:** Marketing **Admin-Gruppe:** Marketing
DSGVO-konforme Speicherung von Newsletter-Anmeldungen mit Double Opt-In Support. DSGVO-konforme Speicherung von Newsletter-Anmeldungen mit Double Opt-In.
#### Felder #### Felder
@ -103,6 +144,14 @@ DSGVO-konforme Speicherung von Newsletter-Anmeldungen mit Double Opt-In Support.
| `ipAddress` | Text | IP-Adresse (DSGVO) | Nein | | `ipAddress` | Text | IP-Adresse (DSGVO) | Nein |
| `userAgent` | Text | Browser-Info | Nein | | `userAgent` | Text | Browser-Info | Nein |
#### Double Opt-In Flow
1. User meldet sich an → Status: `pending`, Token generiert
2. E-Mail mit Bestätigungs-Link wird automatisch gesendet
3. User klickt Link → Status: `confirmed`
4. Willkommens-E-Mail wird gesendet
5. Abmeldung jederzeit über Link möglich
#### Status-Werte #### Status-Werte
- `pending` - Ausstehend (Double Opt-In) - `pending` - Ausstehend (Double Opt-In)
@ -110,29 +159,124 @@ DSGVO-konforme Speicherung von Newsletter-Anmeldungen mit Double Opt-In Support.
- `unsubscribed` - Abgemeldet - `unsubscribed` - Abgemeldet
- `bounced` - E-Mail nicht zustellbar - `bounced` - E-Mail nicht zustellbar
#### Interessen-Optionen ---
- `general` - Allgemeine Updates ### 4. FAQs Collection
- `blog` - Blog-Artikel
- `products` - Produkt-News
- `offers` - Angebote & Aktionen
- `events` - Events
#### Access Control **Pfad:** `src/collections/FAQs.ts`
**Slug:** `faqs`
**Admin-Gruppe:** Content
- **Read:** Nur authentifizierte Benutzer (Datenschutz!) Häufig gestellte Fragen mit Kategorisierung.
- **Create:** Öffentlich (für Anmeldungen)
- **Update/Delete:** Nur authentifizierte Benutzer
#### Automatische Hooks #### Felder
Bei der Erstellung wird automatisch: | Feld | Typ | Beschreibung | Pflicht |
- `subscribedAt` auf aktuelles Datum gesetzt |------|-----|--------------|---------|
- `confirmationToken` generiert (UUID) | `question` | Text | Frage | Ja |
| `answer` | RichText | Antwort | Ja |
| `category` | Text | Kategorie | Nein |
| `order` | Number | Sortierung | Nein |
| `isActive` | Checkbox | Sichtbarkeit | Nein |
Bei Status-Änderungen: ---
- `confirmedAt` wird gesetzt bei Wechsel zu "confirmed"
- `unsubscribedAt` wird gesetzt bei Wechsel zu "unsubscribed" ### 5. Team Collection
**Pfad:** `src/collections/Team.ts`
**Slug:** `team`
**Admin-Gruppe:** Content
Team-Mitglieder und Mitarbeiter.
#### Felder
| Feld | Typ | Beschreibung | Pflicht |
|------|-----|--------------|---------|
| `name` | Text | Name | Ja |
| `role` | Text | Position/Rolle | Nein |
| `image` | Upload | Portrait-Foto | Nein |
| `bio` | Textarea | Kurzbiografie | Nein |
| `email` | Email | E-Mail-Adresse | Nein |
| `phone` | Text | Telefon | Nein |
| `socialLinks` | Array | Social Media Links | Nein |
| `order` | Number | Sortierung | Nein |
| `isActive` | Checkbox | Sichtbarkeit | Nein |
---
### 6. Services Collection
**Pfad:** `src/collections/Services.ts`
**Slug:** `services`
**Admin-Gruppe:** Content
Leistungen und Dienstleistungen.
#### Felder
| Feld | Typ | Beschreibung | Pflicht |
|------|-----|--------------|---------|
| `title` | Text | Leistungsname | Ja |
| `slug` | Text | URL-Pfad | Ja |
| `excerpt` | Textarea | Kurzbeschreibung | Nein |
| `content` | RichText | Detailbeschreibung | Nein |
| `icon` | Text | Icon-Name | Nein |
| `image` | Upload | Bild | Nein |
| `category` | Relationship | Service-Kategorie | Nein |
| `order` | Number | Sortierung | Nein |
---
### 7. Timelines Collection
**Pfad:** `src/collections/Timelines.ts`
**Slug:** `timelines`
**Admin-Gruppe:** Content
Chronologische Events für Geschichte, Meilensteine, Releases.
#### API
```typescript
// Timeline laden
fetch('https://cms.c2sgmbh.de/api/timelines?tenant=4&slug=company-history&locale=de')
```
#### Timeline-Typen
- `history` - Unternehmensgeschichte
- `milestones` - Projektmeilensteine
- `releases` - Produkt-Releases
- `career` - Karriere/Lebenslauf
- `events` - Ereignisse
- `process` - Prozess/Ablauf
---
### 8. Workflows Collection
**Pfad:** `src/collections/Workflows.ts`
**Slug:** `workflows`
**Admin-Gruppe:** Content
Komplexe Prozesse mit Phasen, Abhängigkeiten und Status-Tracking.
#### API
```typescript
// Workflow laden
fetch('https://cms.c2sgmbh.de/api/workflows?tenant=4&type=project&locale=de')
```
#### Workflow-Typen
- `project` - Projektabläufe
- `business` - Geschäftsprozesse
- `approval` - Genehmigungs-Workflows
- `onboarding` - Mitarbeiter-/Kundeneinführung
- `support` - Support/Service-Prozesse
- `development` - Entwicklungsprozesse
--- ---
@ -140,6 +284,19 @@ Bei Status-Änderungen:
Alle Blocks können in der Pages Collection verwendet werden. Alle Blocks können in der Pages Collection verwendet werden.
### Block-Übersicht
| Block | Slug | Beschreibung |
|-------|------|--------------|
| Posts List | `posts-list-block` | Blog/News-Liste |
| Testimonials | `testimonials-block` | Kundenstimmen |
| Newsletter | `newsletter-block` | Anmeldeformular |
| Process Steps | `process-steps-block` | Prozess-Schritte |
| Timeline | `timeline-block` | Chronologie |
| FAQ | `faq-block` | FAQ-Akkordeon |
| Team | `team-block` | Team-Mitglieder |
| Services | `services-block` | Leistungen |
### 1. Posts List Block ### 1. Posts List Block
**Slug:** `posts-list-block` **Slug:** `posts-list-block`
@ -164,8 +321,6 @@ Zeigt eine Liste von Blog-Artikeln, News oder anderen Post-Typen an.
| `showCategory` | Checkbox | true | Kategorie anzeigen | | `showCategory` | Checkbox | true | Kategorie anzeigen |
| `showPagination` | Checkbox | false | Pagination | | `showPagination` | Checkbox | false | Pagination |
| `showReadMore` | Checkbox | true | "Alle anzeigen" Link | | `showReadMore` | Checkbox | true | "Alle anzeigen" Link |
| `readMoreLabel` | Text | "Alle Beiträge anzeigen" | Link-Text |
| `readMoreLink` | Text | /blog | Ziel-URL |
| `backgroundColor` | Select | white | Hintergrundfarbe | | `backgroundColor` | Select | white | Hintergrundfarbe |
#### Layout-Optionen #### Layout-Optionen
@ -184,25 +339,6 @@ Zeigt eine Liste von Blog-Artikeln, News oder anderen Post-Typen an.
Zeigt Kundenstimmen aus der Testimonials Collection. Zeigt Kundenstimmen aus der Testimonials Collection.
#### Konfigurationsoptionen
| Option | Typ | Standard | Beschreibung |
|--------|-----|----------|--------------|
| `title` | Text | "Das sagen unsere Kunden" | Überschrift |
| `subtitle` | Text | - | Untertitel |
| `layout` | Select | slider | Darstellung |
| `columns` | Select | 3 | Spalten (bei Grid) |
| `displayMode` | Select | all | Auswahl-Modus |
| `selectedTestimonials` | Relationship | - | Handverlesene Auswahl |
| `limit` | Number | 6 | Max. Anzahl |
| `showRating` | Checkbox | true | Sterne anzeigen |
| `showImage` | Checkbox | true | Foto anzeigen |
| `showCompany` | Checkbox | true | Unternehmen anzeigen |
| `showSource` | Checkbox | false | Quelle anzeigen |
| `autoplay` | Checkbox | true | Auto-Wechsel (Slider) |
| `autoplaySpeed` | Number | 5000 | Wechselintervall (ms) |
| `backgroundColor` | Select | light | Hintergrundfarbe |
#### Layout-Optionen #### Layout-Optionen
- `slider` - Karussell - `slider` - Karussell
@ -219,27 +355,6 @@ Zeigt Kundenstimmen aus der Testimonials Collection.
Anmeldeformular für Newsletter mit DSGVO-Hinweis. Anmeldeformular für Newsletter mit DSGVO-Hinweis.
#### Konfigurationsoptionen
| Option | Typ | Standard | Beschreibung |
|--------|-----|----------|--------------|
| `title` | Text | "Newsletter abonnieren" | Überschrift |
| `subtitle` | Textarea | Standard-Text | Beschreibung |
| `layout` | Select | inline | Formular-Layout |
| `image` | Upload | - | Bild (bei with-image) |
| `imagePosition` | Select | left | Bildposition |
| `collectName` | Checkbox | false | Name abfragen |
| `showInterests` | Checkbox | false | Interessen anzeigen |
| `availableInterests` | Select (hasMany) | - | Verfügbare Interessen |
| `buttonText` | Text | "Anmelden" | Button-Text |
| `placeholderEmail` | Text | "Ihre E-Mail-Adresse" | Placeholder |
| `successMessage` | Textarea | Standard-Text | Erfolgsmeldung |
| `errorMessage` | Text | Standard-Text | Fehlermeldung |
| `privacyText` | Textarea | Standard-Text | Datenschutz-Hinweis |
| `privacyLink` | Text | /datenschutz | Link zur DSE |
| `source` | Text | website | Tracking-Quelle |
| `backgroundColor` | Select | accent | Hintergrundfarbe |
#### Layout-Optionen #### Layout-Optionen
- `inline` - Eingabe + Button nebeneinander - `inline` - Eingabe + Button nebeneinander
@ -250,85 +365,54 @@ Anmeldeformular für Newsletter mit DSGVO-Hinweis.
--- ---
### 4. Process Steps Block ### 4. FAQ Block
**Slug:** `process-steps-block` **Slug:** `faq-block`
Zeigt Prozess-Schritte / "So funktioniert es" Darstellungen. FAQ-Akkordeon mit Schema.org Markup.
#### Konfigurationsoptionen #### Konfigurationsoptionen
| Option | Typ | Standard | Beschreibung | | Option | Typ | Beschreibung |
|--------|-----|----------|--------------| |--------|-----|--------------|
| `title` | Text | "So funktioniert es" | Überschrift | | `title` | Text | Überschrift |
| `subtitle` | Text | - | Untertitel | | `subtitle` | Text | Untertitel |
| `layout` | Select | horizontal | Darstellung | | `displayMode` | Select | all / selected / byCategory |
| `showNumbers` | Checkbox | true | Schritt-Nummern | | `selectedFaqs` | Relationship | Handverlesene FAQs |
| `showIcons` | Checkbox | true | Icons anzeigen | | `filterCategory` | Text | Kategorie-Filter |
| `steps` | Array | - | Schritte (2-10) | | `layout` | Select | accordion / list / grid |
| `cta.show` | Checkbox | false | CTA anzeigen | | `expandFirst` | Checkbox | Erste FAQ offen |
| `cta.label` | Text | "Jetzt starten" | Button-Text | | `showSchema` | Checkbox | JSON-LD generieren |
| `cta.href` | Text | - | Button-Link |
| `cta.variant` | Select | default | Button-Stil |
| `backgroundColor` | Select | white | Hintergrundfarbe |
#### Schritte-Felder
- `title` - Schritt-Titel (Pflicht)
- `description` - Beschreibung
- `icon` - Emoji oder Icon-Name
- `image` - Optionales Bild
#### Layout-Optionen
- `horizontal` - Nebeneinander
- `vertical` - Untereinander
- `alternating` - Zickzack
- `connected` - Mit Verbindungslinien
- `timeline` - Timeline-Stil
--- ---
### 5. Timeline Block ### 5. Team Block
**Slug:** `timeline-block` **Slug:** `team-block`
Chronologische Darstellung von Ereignissen (z.B. Firmengeschichte). Team-Mitglieder aus der Team Collection.
#### Konfigurationsoptionen
| Option | Typ | Standard | Beschreibung |
|--------|-----|----------|--------------|
| `title` | Text | - | Überschrift |
| `subtitle` | Text | - | Untertitel |
| `layout` | Select | vertical | Darstellung |
| `showConnector` | Checkbox | true | Verbindungslinie |
| `markerStyle` | Select | dot | Marker-Stil |
| `items` | Array | - | Einträge |
| `backgroundColor` | Select | white | Hintergrundfarbe |
#### Einträge-Felder
- `year` - Jahr/Datum
- `title` - Titel (Pflicht)
- `description` - Beschreibung
- `icon` - Emoji oder Icon
- `image` - Optionales Bild
- `link.label` - Link-Text
- `link.href` - Link-URL
#### Layout-Optionen #### Layout-Optionen
- `vertical` - Standard vertikal - `grid` - Karten im Grid
- `alternating` - Links/Rechts wechselnd - `list` - Listenansicht
- `horizontal` - Horizontale Zeitleiste - `carousel` - Karussell
- `compact` - Kompakt
#### Marker-Stile ---
- `dot` - Punkt ### 6. Services Block
- `number` - Nummer
- `icon` - Icon **Slug:** `services-block`
- `date` - Jahr/Datum
Leistungen aus der Services Collection.
#### Layout-Optionen
- `grid` - Karten im Grid
- `list` - Listenansicht mit Details
- `icons` - Icon-Grid
- `tabs` - Tab-Navigation
--- ---
@ -344,6 +428,11 @@ multiTenantPlugin({
posts: {}, posts: {},
testimonials: {}, testimonials: {},
'newsletter-subscribers': {}, 'newsletter-subscribers': {},
faqs: {},
team: {},
services: {},
timelines: {},
workflows: {},
// ... weitere Collections // ... weitere Collections
}, },
}) })
@ -351,10 +440,18 @@ multiTenantPlugin({
### Tenant-Zuordnung ### Tenant-Zuordnung
Jedes Dokument enthält ein `tenant`-Feld, das auf die Tenants-Collection verweist. Die Access-Control-Funktionen in `src/lib/tenantAccess.ts` sorgen für die Isolation: Jedes Dokument enthält ein `tenant`-Feld. Die Access-Control sorgt für Isolation:
- **Authentifizierte Admins:** Sehen alle Dokumente - **Authentifizierte Admins:** Sehen alle Dokumente
- **Anonyme Requests:** Nur Dokumente des Tenants, der zur Domain passt - **Anonyme Requests:** Nur Dokumente des passenden Tenants
### Tenant-IDs
| ID | Name | Slug |
|----|------|------|
| 1 | porwoll.de | porwoll |
| 4 | Complex Care Solutions GmbH | c2s |
| 5 | Gunshin | gunshin |
--- ---
@ -363,38 +460,83 @@ Jedes Dokument enthält ein `tenant`-Feld, das auf die Tenants-Collection verwei
``` ```
src/ src/
├── collections/ ├── collections/
│ ├── Posts.ts # Blog/News Collection │ ├── Posts.ts
│ ├── Testimonials.ts # Kundenstimmen │ ├── Categories.ts
│ └── NewsletterSubscribers.ts # Newsletter-Anmeldungen │ ├── Testimonials.ts
│ ├── NewsletterSubscribers.ts
│ ├── FAQs.ts
│ ├── Team.ts
│ ├── Services.ts
│ ├── ServiceCategories.ts
│ ├── Timelines.ts
│ └── Workflows.ts
├── blocks/ ├── blocks/
│ ├── PostsListBlock.ts # Blog/News-Liste │ ├── PostsListBlock.ts
│ ├── TestimonialsBlock.ts # Testimonials-Anzeige │ ├── TestimonialsBlock.ts
│ ├── NewsletterBlock.ts # Newsletter-Formular │ ├── NewsletterBlock.ts
│ ├── ProcessStepsBlock.ts # Prozess-Schritte │ ├── ProcessStepsBlock.ts
│ ├── TimelineBlock.ts # Timeline │ ├── TimelineBlock.ts
│ └── index.ts # Block-Exports │ ├── FAQBlock.ts
│ ├── TeamBlock.ts
│ ├── ServicesBlock.ts
│ └── index.ts
├── lib/ ├── lib/
│ └── tenantAccess.ts # Access-Control-Funktionen │ ├── tenantAccess.ts
└── payload.config.ts # Haupt-Konfiguration │ └── email/
│ ├── newsletter-service.ts
│ └── newsletter-templates.ts
├── hooks/
│ └── sendNewsletterConfirmation.ts
└── app/(payload)/api/newsletter/
├── subscribe/route.ts
├── confirm/route.ts
└── unsubscribe/route.ts
``` ```
--- ---
## Datenbank-Tabellen ## URLs
| Tabelle | Beschreibung | ### Production (für Frontends)
|---------|--------------|
| `posts` | Blog/News-Beiträge | | Resource | URL |
| `posts_rels` | Kategorien-Beziehungen | |----------|-----|
| `testimonials` | Kundenstimmen | | Posts API | https://cms.c2sgmbh.de/api/posts |
| `newsletter_subscribers` | Newsletter-Anmeldungen | | Testimonials API | https://cms.c2sgmbh.de/api/testimonials |
| `newsletter_subscribers_interests` | Interessen (hasMany) | | FAQs API | https://cms.c2sgmbh.de/api/faqs |
| `pages_rels` | Block-Relationships | | Team API | https://cms.c2sgmbh.de/api/team |
| Services API | https://cms.c2sgmbh.de/api/services |
| Timelines API | https://cms.c2sgmbh.de/api/timelines |
| Workflows API | https://cms.c2sgmbh.de/api/workflows |
| Newsletter Subscribe | https://cms.c2sgmbh.de/api/newsletter/subscribe |
### Development
| Resource | URL |
|----------|-----|
| API Base | https://pl.porwoll.tech/api |
| Admin Panel | https://pl.porwoll.tech/admin |
--- ---
## Changelog ## Changelog
### Version 1.2 (18.12.2025)
- Dokumentation auf Production-URLs aktualisiert
- API-Endpoints für Frontend hinzugefügt
- Newsletter Double Opt-In Flow dokumentiert
- Timelines und Workflows Collections hinzugefügt
- FAQ, Team, Services Blocks dokumentiert
### Version 1.1 (14.12.2025)
- Timelines Collection für chronologische Darstellungen
- Workflows Collection für Prozesse
- FAQs Collection mit Kategorisierung
- Team Collection mit Social Links
- Services Collection mit Kategorien
### Version 1.0 (30.11.2025) ### Version 1.0 (30.11.2025)
- Posts Collection um `type`, `isFeatured`, `excerpt` erweitert - Posts Collection um `type`, `isFeatured`, `excerpt` erweitert
@ -402,4 +544,7 @@ src/
- NewsletterSubscribers Collection erstellt (DSGVO-konform) - NewsletterSubscribers Collection erstellt (DSGVO-konform)
- 5 neue Blocks für Pages implementiert - 5 neue Blocks für Pages implementiert
- Multi-Tenant Integration für alle Collections - Multi-Tenant Integration für alle Collections
- Migration `20251130_135459` erstellt und angewendet
---
*Letzte Aktualisierung: 18. Dezember 2025*