diff --git a/docs/anleitungen/FRONTEND.md b/docs/anleitungen/FRONTEND.md new file mode 100644 index 0000000..45657aa --- /dev/null +++ b/docs/anleitungen/FRONTEND.md @@ -0,0 +1,329 @@ +# Frontend-Entwicklung - Payload CMS Multi-Tenant + +> **Server:** sv-frontend (LXC 704) - 10.10.181.104 +> **Backend API:** https://pl.c2sgmbh.de/api + +## Übersicht + +Das Frontend wird als separates Next.js-Projekt entwickelt und nutzt Payload CMS als Headless CMS über die REST-API. + +--- + +## API-Dokumentation + +| Ressource | URL | +|-----------|-----| +| **Swagger UI** | https://pl.c2sgmbh.de/api/docs | +| **OpenAPI JSON** | https://pl.c2sgmbh.de/api/openapi.json | +| **REST API Base** | https://pl.c2sgmbh.de/api | + +--- + +## Offene Frontend-Tasks + +### Hohe Priorität + +- [ ] **Block-Komponenten entwickeln** + - [ ] Hero Block + - [ ] Text Block + - [ ] Image Text Block + - [ ] Card Grid Block + - [ ] Quote Block + - [ ] CTA Block + - [ ] Contact Form Block + - [ ] Video Block + - [ ] Divider Block + - [ ] Timeline Block + - [ ] Posts List Block + - [ ] Testimonials Block + - [ ] Newsletter Block + - [ ] Process Steps Block + +- [ ] **Newsletter-Anmelde-Formular** + - API: `POST /api/newsletter/subscribe` + - Double Opt-In Flow bereits im Backend implementiert + - Felder: email, firstName (optional), tenantId, source + +- [ ] **Cookie-Banner implementieren** + - Cookie Configurations aus API laden + - Consent-Logs an Backend senden + - DSGVO-konform mit Opt-In + +### Mittlere Priorität + +- [ ] **Multi-Tenant Routing** + - Domain-basierte Tenant-Erkennung + - Locale-Routing (`/[locale]/...`) + - Unterstützte Locales: `de` (default), `en` + +- [ ] **SEO-Integration** + - Meta-Tags aus Pages/Posts + - Structured Data (JSON-LD) + - Sitemap: https://pl.c2sgmbh.de/sitemap.xml + +- [ ] **Suche implementieren** + - API: `GET /api/search?q=...&locale=de` + - Auto-Complete: `GET /api/search/suggestions?q=...` + - Rate-Limit: 30 Requests/Minute + +### Tenant-spezifische Features + +#### porwoll.de +- [ ] Immobilien-Listing +- [ ] Objektsuche mit Filtern +- [ ] Kontaktformular mit Objekt-Referenz + +#### complexcaresolutions.de (C2S) +- [ ] Team-Übersicht +- [ ] Leistungs-Seiten +- [ ] Karriere-Seite mit Stellenangeboten + +#### gunshin.de (Fotografin-Portfolio) +- [ ] Portfolio-Galerie + - API: `GET /api/portfolios?where[tenant][equals]=5` + - Kategorien: `GET /api/portfolio-categories` +- [ ] Projekt-Detailseiten mit Lightbox +- [ ] Referenzen-Slider + +#### zweitmein.ng +- [ ] Produkt-Übersicht (falls E-Commerce) +- [ ] FAQ-Sektion +- [ ] Preistabellen + +--- + +## API-Endpoints + +### Collections + +| Collection | Endpoint | Beschreibung | +|------------|----------|--------------| +| Pages | `GET /api/pages` | Seiten mit Blocks | +| Posts | `GET /api/posts` | Blog, News, Presse | +| Categories | `GET /api/categories` | Post-Kategorien | +| Testimonials | `GET /api/testimonials` | Kundenbewertungen | +| Team | `GET /api/team` | Team-Mitglieder | +| Services | `GET /api/services` | Leistungen | +| FAQs | `GET /api/faqs` | FAQ-Einträge | +| Portfolios | `GET /api/portfolios` | Portfolio-Projekte | +| Media | `GET /api/media` | Medien/Bilder | + +### Globals + +| Global | Endpoint | Beschreibung | +|--------|----------|--------------| +| Site Settings | `GET /api/globals/site-settings` | Logo, Name, SEO | +| Navigation | `GET /api/globals/navigation` | Menü-Struktur | +| SEO Settings | `GET /api/globals/seo-settings` | Default SEO | + +### Spezielle Endpoints + +| Endpoint | Methode | Beschreibung | +|----------|---------|--------------| +| `/api/search` | GET | Volltextsuche | +| `/api/search/suggestions` | GET | Auto-Complete | +| `/api/newsletter/subscribe` | POST | Newsletter-Anmeldung | + +--- + +## Tenant-Filterung + +Alle Collection-Anfragen sollten nach Tenant gefiltert werden: + +```typescript +// Beispiel: Posts für Tenant "c2s" (ID: 4) +fetch('https://pl.c2sgmbh.de/api/posts?where[tenant][equals]=4&locale=de') + +// Beispiel: Pages für Tenant "gunshin" (ID: 5) +fetch('https://pl.c2sgmbh.de/api/pages?where[tenant][equals]=5&locale=de') +``` + +### Tenant-IDs + +| ID | Name | Slug | Domain | +|----|------|------|--------| +| 1 | porwoll.de | porwoll | porwoll.de | +| 4 | Complex Care Solutions GmbH | c2s | complexcaresolutions.de | +| 5 | Gunshin | gunshin | gunshin.de | + +--- + +## Bild-Optimierung + +Media-Objekte enthalten mehrere Größen: + +```typescript +interface Media { + url: string // Original + sizes: { + thumbnail: { url, width, height } // 150x150 + small: { url, width, height } // 300x300 + medium: { url, width, height } // 600x600 + large: { url, width, height } // 1200x1200 + xlarge: { url, width, height } // 1920x1920 + '2k': { url, width, height } // 2560x2560 + og: { url, width, height } // 1200x630 (Social) + // + AVIF-Varianten + thumbnail_avif: { url, width, height } + small_avif: { url, width, height } + // ... + } + focalX?: number // Fokuspunkt X (0-100) + focalY?: number // Fokuspunkt Y (0-100) +} +``` + +--- + +## Lokalisierung + +Unterstützte Locales: `de` (default), `en` + +```typescript +// Deutsch (default) +fetch('https://pl.c2sgmbh.de/api/posts?locale=de') + +// Englisch +fetch('https://pl.c2sgmbh.de/api/posts?locale=en') + +// Fallback: Wenn EN nicht vorhanden, wird DE zurückgegeben +``` + +--- + +## Newsletter-Integration + +### Anmeldung + +```typescript +const response = await fetch('https://pl.c2sgmbh.de/api/newsletter/subscribe', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + email: 'user@example.com', + firstName: 'Max', // optional + tenantId: 4, // Pflicht + source: 'footer' // optional: Herkunft + }) +}) + +// Response: { success: true, message: '...' } +``` + +### Flow +1. User gibt E-Mail ein → `POST /api/newsletter/subscribe` +2. Backend sendet Double Opt-In E-Mail +3. User klickt Bestätigungs-Link +4. Backend sendet Willkommens-E-Mail +5. User kann sich über Link in E-Mails abmelden + +--- + +## Cookie-Consent + +### Konfiguration laden + +```typescript +const config = await fetch('https://pl.c2sgmbh.de/api/cookie-configurations?where[tenant][equals]=4') +``` + +### Consent loggen + +```typescript +await fetch('https://pl.c2sgmbh.de/api/consent-logs', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + tenant: 4, + consentGiven: true, + categories: ['necessary', 'analytics'], + ipAddress: '...', // Optional, für DSGVO + userAgent: navigator.userAgent + }) +}) +``` + +--- + +## Kontaktformular + +Formular-Submissions werden über die Forms-Collection verarbeitet: + +```typescript +await fetch('https://pl.c2sgmbh.de/api/form-submissions', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + form: 1, // Form-ID + submissionData: [ + { field: 'name', value: 'Max Mustermann' }, + { field: 'email', value: 'max@example.com' }, + { field: 'message', value: 'Ihre Nachricht...' } + ] + }) +}) +``` + +--- + +## Authentifizierung (optional) + +Falls User-Authentifizierung benötigt wird: + +```typescript +// Login +const { token, user } = await fetch('https://pl.c2sgmbh.de/api/users/login', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ email, password }) +}).then(r => r.json()) + +// Authentifizierte Requests +fetch('https://pl.c2sgmbh.de/api/...', { + headers: { 'Authorization': `JWT ${token}` } +}) +``` + +--- + +## Entwicklungshinweise + +### TypeScript-Typen + +Die Payload-Typen können aus dem Backend exportiert werden: + +```bash +# Auf dem Payload-Server +pnpm payload generate:types + +# Datei: src/payload-types.ts +``` + +Diese Datei kann ins Frontend-Projekt kopiert werden für typsichere API-Calls. + +### Rate-Limits + +| Endpoint | Limit | +|----------|-------| +| Öffentliche API | 60/min | +| Suche | 30/min | +| Newsletter | 5/10min | +| Formulare | 5/10min | + +### Caching + +- API-Responses werden serverseitig gecacht (Redis) +- TTL: 60 Sekunden für Suche +- Cache wird bei Content-Änderungen invalidiert + +--- + +## Ressourcen + +- **Payload CMS Docs:** https://payloadcms.com/docs +- **API-Dokumentation:** https://pl.c2sgmbh.de/api/docs +- **Backend-Repository:** https://github.com/c2s-admin/cms.c2sgmbh.git + +--- + +*Erstellt: 11.12.2025* diff --git a/docs/anleitungen/TODO.md b/docs/anleitungen/TODO.md index 4d2672c..8949167 100644 --- a/docs/anleitungen/TODO.md +++ b/docs/anleitungen/TODO.md @@ -1,12 +1,55 @@ # To-Do-Liste - Payload CMS Multi-Tenant Projekt +> **Server:** sv-payload (LXC 700) - 10.10.181.100 +> **Frontend-Tasks:** Siehe `FRONTEND.md` (sv-frontend, LXC 704) + +--- + +## Zusammenfassung: Offene Tasks (Payload-Server) + +### Hohe Priorität +| Status | Task | Bereich | +|--------|------|---------| +| [ ] | Rate-Limits auf Redis migrieren | Performance | +| [ ] | SMTP-Credentials in `.env` konfigurieren | E-Mail | + +### Mittlere Priorität +| Status | Task | Bereich | +|--------|------|---------| +| [ ] | Media-Backup zu S3/MinIO | Backup | +| [ ] | CDN-Integration (Cloudflare) | Caching | +| [ ] | Connection Pooling (PgBouncer) | Datenbank | +| [ ] | CI/CD Pipeline erweitern (Lint/Test/Build) | DevOps | +| [ ] | Staging-Deployment | DevOps | +| [ ] | Memory-Problem lösen (Swap) | Infrastruktur | +| [ ] | PM2 Cluster Mode testen | Infrastruktur | + +### Niedrige Priorität +| Status | Task | Bereich | +|--------|------|---------| +| [ ] | Monitoring: Sentry, Prometheus, Grafana | Monitoring | +| [ ] | AuditLogs Retention (90 Tage Cron) | Data Retention | +| [ ] | Email-Log Cleanup Cron | Data Retention | +| [ ] | Dashboard-Widget für Email-Status | Admin UX | +| [ ] | TypeScript Strict Mode | Tech Debt | +| [ ] | Unit Tests für Access Control | Testing | +| [ ] | E2E Tests für kritische Flows | Testing | + +### Dokumentation +| Status | Task | +|--------|------| +| [ ] | DEPLOYMENT.md erstellen | +| [ ] | ~~FRONTEND_INTEGRATION.md~~ → Siehe `FRONTEND.md` | + +--- + ## Legende - [ ] Offen - [x] Erledigt - [~] In Bearbeitung - [!] Hohe Priorität -- [?] Klärungsbedarf +- [→] Ausgelagert (siehe FRONTEND.md) --- @@ -103,10 +146,11 @@ - [x] API-Endpoints: subscribe, confirm, unsubscribe - [x] Automatischer E-Mail-Versand via Hook -- [ ] **[!] Frontend-Komponenten entwickeln** - - React/Next.js Komponenten für alle Blocks - - Newsletter-Anmelde-Formular - - Cookie-Banner implementieren +- [→] **Frontend-Komponenten entwickeln** → Siehe `FRONTEND.md` + - ~~React/Next.js Komponenten für alle Blocks~~ + - ~~Newsletter-Anmelde-Formular~~ + - ~~Cookie-Banner implementieren~~ + - *Entwicklung auf sv-frontend (LXC 704)* ### Mittlere Priorität @@ -423,15 +467,18 @@ ## Phase 5: Tenant-spezifische Features +> **Hinweis:** Backend-Collections hier, Frontend-Komponenten in `FRONTEND.md` + ### porwoll.de -- [ ] Immobilien-Collection (falls benötigt) -- [ ] Objektsuche -- [ ] Kontaktformular mit Objekt-Referenz +- [ ] Immobilien-Collection (falls benötigt) *(Backend)* +- [→] Objektsuche *(Frontend)* +- [→] Kontaktformular mit Objekt-Referenz *(Frontend)* ### complexcaresolutions.de (C2S) -- [ ] Team-Collection -- [ ] Leistungs-Übersicht -- [ ] Karriere-Seite mit Stellenangeboten +- [x] Team-Collection *(bereits vorhanden)* +- [x] Services-Collection *(bereits vorhanden)* +- [→] Leistungs-Übersicht *(Frontend)* +- [→] Karriere-Seite mit Stellenangeboten *(Frontend)* ### gunshin.de / Fotografin-Portfolio - [x] Portfolio-Categories Collection (Erledigt: 06.12.2025) @@ -444,13 +491,13 @@ - [x] Projekt-Details (Kunde, Ort, Datum, Ausrüstung) - [x] Status (draft/published/archived) - [x] isFeatured, SEO-Felder -- [ ] Projekt-Galerie Frontend -- [ ] Referenzen-Slider +- [→] Projekt-Galerie Frontend *(Frontend)* +- [→] Referenzen-Slider *(Frontend)* ### zweitmein.ng -- [ ] Produkt-Collection (falls E-Commerce) -- [ ] FAQ-Collection -- [ ] Preistabellen +- [ ] Produkt-Collection (falls E-Commerce) *(Backend)* +- [x] FAQ-Collection *(bereits vorhanden)* +- [→] Preistabellen *(Frontend)* --- @@ -479,8 +526,8 @@ - [x] ANALYTICS_IMPLEMENTATION_GUIDE.md (Umami & Google Ads) - [x] Techstack_Dokumentation_12_2025.md (Infrastruktur & Deployment) - [x] SECURITY.md (Sicherheitsrichtlinien) (Erledigt: 08.12.2025) +- [x] FRONTEND.md (Frontend-Entwicklung für sv-frontend) (Erledigt: 11.12.2025) - [ ] DEPLOYMENT.md (Deployment-Prozess) -- [ ] FRONTEND_INTEGRATION.md (Next.js Guide) --- @@ -520,8 +567,9 @@ 3. ~~**[HOCH]** Full-Text-Search aktivieren (USE_FTS=true)~~ ✅ Erledigt 4. **[HOCH]** Rate-Limits auf Redis migrieren (In-Memory-Fallback funktioniert) 5. ~~**[MITTEL]** CI/CD Pipeline mit GitHub Actions~~ ✅ security.yml erstellt -6. **[MITTEL]** Frontend-Entwicklung starten -7. **[NIEDRIG]** Admin UX Verbesserungen +6. ~~**[MITTEL]** Frontend-Entwicklung starten~~ → sv-frontend (siehe FRONTEND.md) +7. **[MITTEL]** Media-Backup zu S3 einrichten +8. **[NIEDRIG]** Monitoring (Sentry/Prometheus) ---