943 lines
32 KiB
Markdown
943 lines
32 KiB
Markdown
# HMS Licht & Ton – System Architecture
|
||
|
||
> **Projekt:** hms-licht-ton (ID 30)
|
||
> **Datum:** 2026-07-08
|
||
> **Status:** Draft – Ready for Review
|
||
> **Autor:** Solution Architect (A0 Orchestrator)
|
||
|
||
---
|
||
|
||
## 1. Architektur-Überblick
|
||
|
||
### 1.1 System-Komponenten
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Coolify (Docker) │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │
|
||
│ │ Nuxt 3 SSR │ │ FastAPI │ │ PostgreSQL │ │
|
||
│ │ (Frontend) │ │ (Backend) │ │ (equipment_cache│ │
|
||
│ │ Port 3000 │ │ Port 8000 │ │ rental_requests)│ │
|
||
│ └──────┬───────┘ └──────┬──────┘ └────────┬─────────┘ │
|
||
│ │ │ │ │
|
||
│ │ /api/* │ SQLAlchemy │ │
|
||
│ └────────────────►│ │ │
|
||
│ │ ┌───────────┐ │ │
|
||
│ │ │ Redis │ │ │
|
||
│ │ │ (cache, │ │ │
|
||
│ │ │ rate-lim)│ │ │
|
||
│ │ └─────┬─────┘ │ │
|
||
│ │ │ │ │
|
||
│ ┌───────────────────────┴────────┴─────────┴──────┐ │
|
||
│ │ Traefik (TLS, Routing) │ │
|
||
│ │ hms.media-on.de → Nuxt 3000 │ │
|
||
│ │ hms.media-on.de/api → FastAPI 8000 │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
│
|
||
│ HTTPS
|
||
▼
|
||
┌─────────────────┐
|
||
│ Rentman API │
|
||
│ api.rentman.net│
|
||
│ (Bearer Token) │
|
||
└─────────────────┘
|
||
```
|
||
|
||
### 1.2 Container-Topologie
|
||
|
||
| Container | Image | Port | Abhängigkeiten |
|
||
|-----------|-------|------|----------------|
|
||
| `hms-frontend` | Node 20 + Nuxt 3 | 3000 | `hms-backend` |
|
||
| `hms-backend` | Python 3.12 + FastAPI | 8000 | `hms-postgres`, `hms-redis` |
|
||
| `hms-postgres` | PostgreSQL 16 | 5432 | – |
|
||
| `hms-redis` | Redis 7 | 6379 | – |
|
||
|
||
Traefik (Coolify-eigen) routet:
|
||
- `hms.media-on.de/*` → `hms-frontend:3000`
|
||
- `hms.media-on.de/api/*` → `hms-backend:8000`
|
||
|
||
---
|
||
|
||
## 2. Frontend-Architektur (Nuxt 3)
|
||
|
||
### 2.1 Rendering-Strategie
|
||
|
||
| Route | Modus | Begründung |
|
||
|-------|-------|------------|
|
||
| `/` (Home) | SSG (`nuxt generate`) | Statischer Content, SEO/SSR nicht nötig (noindex) |
|
||
| `/referenzen` | SSG | Statische Bilder, keine API nötig |
|
||
| `/mietkatalog` | SSR (`server`) | Dynamische Equipment-Daten vom Backend |
|
||
| `/mietkatalog/:id` | SSR | Equipment-Detail vom Backend |
|
||
| `/warenkorb` | CSR | Reine Client-State (localStorage) |
|
||
| `/mietanfrage` | CSR | Formular mit Client-State (Warenkorb) |
|
||
| `/kontakt` | SSG | Statisches Formular, API-Call bei Submit |
|
||
| `/admin` | CSR | Auth-basiert, keine Public-SSR nötig |
|
||
| `/impressum` | SSG | Statischer Content |
|
||
| `/datenschutz` | SSG | Statischer Content |
|
||
| `/agb-vermietung` | SSG | Statischer Content |
|
||
|
||
**Konfiguration:** `nuxt.config.ts` mit `routeRules`:
|
||
```typescript
|
||
export default defineNuxtConfig({
|
||
routeRules: {
|
||
'/': { prerender: true },
|
||
'/referenzen': { prerender: true },
|
||
'/mietkatalog': { ssr: true },
|
||
'/mietkatalog/**': { ssr: true },
|
||
'/warenkorb': { ssr: false },
|
||
'/mietanfrage': { ssr: false },
|
||
'/kontakt': { prerender: true },
|
||
'/admin': { ssr: false },
|
||
'/impressum': { prerender: true },
|
||
'/datenschutz': { prerender: true },
|
||
'/agb-vermietung': { prerender: true },
|
||
}
|
||
})
|
||
```
|
||
|
||
### 2.2 Verzeichnisstruktur
|
||
|
||
```
|
||
frontend/
|
||
├── nuxt.config.ts
|
||
├── tailwind.config.ts
|
||
├── package.json
|
||
├── tsconfig.json
|
||
├── app.vue
|
||
├── assets/
|
||
│ ├── css/
|
||
│ │ └── main.css (Design Tokens, Tailwind imports)
|
||
│ └── img/
|
||
│ ├── logo.svg
|
||
│ ├── hero-bg.jpg
|
||
│ └── ref/ (Referenz-Bilder ref1-9.jpg)
|
||
├── components/
|
||
│ ├── HmsLogo.vue
|
||
│ ├── SpeakerIcon.vue
|
||
│ ├── AppHeader.vue
|
||
│ ├── AppFooter.vue
|
||
│ ├── ServiceCard.vue
|
||
│ ├── EquipmentCard.vue
|
||
│ ├── LoadingSkeleton.vue
|
||
│ ├── EmptyState.vue
|
||
│ ├── ErrorState.vue
|
||
│ ├── LegalContentPage.vue
|
||
│ ├── Lightbox.vue
|
||
│ └── CartDrawer.vue
|
||
├── composables/
|
||
│ ├── useEquipment.ts (API fetch + caching)
|
||
│ ├── useCart.ts (Pinia store wrapper)
|
||
│ └── useApi.ts (Base API client)
|
||
├── layouts/
|
||
│ └── default.vue (Header + Footer + slot)
|
||
├── pages/
|
||
│ ├── index.vue (Home)
|
||
│ ├── referenzen.vue
|
||
│ ├── mietkatalog/
|
||
│ │ ├── index.vue
|
||
│ │ └── [id].vue
|
||
│ ├── warenkorb.vue
|
||
│ ├── mietanfrage.vue
|
||
│ ├── kontakt.vue
|
||
│ ├── admin.vue
|
||
│ ├── impressum.vue
|
||
│ ├── datenschutz.vue
|
||
│ ├── agb-vermietung.vue
|
||
│ └── [...slug].vue (404 catch-all)
|
||
├── stores/
|
||
│ └── cart.ts (Pinia store, localStorage persist)
|
||
├── plugins/
|
||
│ └── pinia-persist.client.ts
|
||
├── public/
|
||
│ └── robots.txt
|
||
└── server/
|
||
└── middleware/
|
||
└── headers.ts (noindex headers)
|
||
```
|
||
|
||
### 2.3 State Management
|
||
|
||
| State | Lösung | Persistenz |
|
||
|-------|--------|------------|
|
||
| Warenkorb (Artikel + Mengen) | Pinia store `cart.ts` | localStorage (client-side) |
|
||
| UI-State (mobile menu, lightbox) | Component-local `ref()` | keine |
|
||
| Equipment-Daten | Nuxt `useFetch` / `useAsyncData` | Nuxt payload cache (SSR) |
|
||
| Admin-Auth | JWT in HttpOnly Cookie | Cookie (24h) |
|
||
|
||
### 2.4 Design Token System
|
||
|
||
Implementiert als CSS Custom Properties in `assets/css/main.css` und Tailwind-Config:
|
||
|
||
```css
|
||
:root {
|
||
/* A0 Dark Theme */
|
||
--bg: #131313;
|
||
--panel: #1a1a1a;
|
||
--surface: #212121;
|
||
--row: #272727;
|
||
--card: #2d2d2d;
|
||
--border: #444444a8;
|
||
--secondary: #656565;
|
||
--primary: #737a81;
|
||
--text: #ffffff;
|
||
--text-muted: #d4d4d4;
|
||
|
||
/* Orange Akzent */
|
||
--color-accent: #EC6925;
|
||
--color-accent-hover: #d4581a;
|
||
--color-accent-light: rgba(236, 105, 37, 0.08);
|
||
--color-accent-border: rgba(236, 105, 37, 0.25);
|
||
|
||
/* Status */
|
||
--color-success: #4ade80;
|
||
--color-error: #f87171;
|
||
--color-warning: #fbbf24;
|
||
--color-info: #60a5fa;
|
||
|
||
/* Radius */
|
||
--radius-sm: 2px;
|
||
--radius-md: 3px;
|
||
--radius-lg: 4px;
|
||
|
||
/* Transitions */
|
||
--transition-fast: 150ms ease;
|
||
--transition-base: 250ms ease;
|
||
--transition-slow: 400ms ease;
|
||
}
|
||
```
|
||
|
||
Tailwind-Config extend mit denselben Werten als utility classes.
|
||
|
||
---
|
||
|
||
## 3. Backend-Architektur (FastAPI)
|
||
|
||
### 3.1 Verzeichnisstruktur
|
||
|
||
```
|
||
backend/
|
||
├── main.py (FastAPI app, CORS, routers)
|
||
├── config.py (Pydantic Settings, env vars)
|
||
├── database.py (SQLAlchemy engine, session)
|
||
├── models/
|
||
│ ├── __init__.py
|
||
│ ├── equipment.py (EquipmentCache model)
|
||
│ ├── rental_request.py (RentalRequest + RentalRequestItem)
|
||
│ ├── contact.py (Contact model)
|
||
│ ├── admin_user.py (AdminUser model)
|
||
│ └── sync_log.py (SyncLog model)
|
||
├── schemas/
|
||
│ ├── __init__.py
|
||
│ ├── equipment.py (Pydantic schemas)
|
||
│ ├── rental_request.py
|
||
│ ├── contact.py
|
||
│ ├── auth.py
|
||
│ └── sync.py
|
||
├── routers/
|
||
│ ├── __init__.py
|
||
│ ├── equipment.py (GET /equipment, GET /equipment/{id})
|
||
│ ├── rental_requests.py (POST /rental-requests)
|
||
│ ├── contact.py (POST /contact)
|
||
│ ├── auth.py (POST /admin/login, GET /admin/me)
|
||
│ ├── admin.py (POST /admin/sync, GET /admin/sync-status)
|
||
│ └── health.py (GET /health)
|
||
├── services/
|
||
│ ├── rentman_import.py (Equipment-Import pipeline)
|
||
│ ├── rentman_request.py (Mietanfrage pipeline)
|
||
│ ├── email_service.py (SMTP email send)
|
||
│ └── auth_service.py (JWT create/verify)
|
||
├── cache.py (Redis client, cache helpers)
|
||
├── requirements.txt
|
||
├── Dockerfile
|
||
├── alembic.ini
|
||
└── migrations/
|
||
└── versions/
|
||
```
|
||
|
||
### 3.2 API-Design
|
||
|
||
Alle Endpunkte unter Prefix `/api`.
|
||
|
||
#### Equipment Endpoints
|
||
|
||
| Method | Path | Beschreibung | Query Params | Response |
|
||
|--------|------|--------------|--------------|----------|
|
||
| GET | `/api/equipment` | Equipment-Liste | `search`, `category`, `sort` (name_asc, name_desc), `page`, `page_size` | `200` PaginatedResponse<EquipmentItem> |
|
||
| GET | `/api/equipment/{id}` | Equipment-Detail | – | `200` EquipmentDetail / `404` |
|
||
| GET | `/api/equipment/categories` | Alle Kategorien | – | `200` string[] |
|
||
|
||
**PaginatedResponse Schema:**
|
||
```json
|
||
{
|
||
"items": [...],
|
||
"total": 500,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"total_pages": 25
|
||
}
|
||
```
|
||
|
||
**EquipmentItem Schema:**
|
||
```json
|
||
{
|
||
"id": 123,
|
||
"rentman_id": "456",
|
||
"name": "L-Acoustics K2",
|
||
"number": "K2-001",
|
||
"category": "Lautsprecher",
|
||
"description": "Line Array Element",
|
||
"image_url": "/img/equipment/k2-001.jpg",
|
||
"rental_price": null,
|
||
"available": true
|
||
}
|
||
```
|
||
|
||
**EquipmentDetail Schema (erweitert):**
|
||
```json
|
||
{
|
||
"id": 123,
|
||
"rentman_id": "456",
|
||
"name": "L-Acoustics K2",
|
||
"number": "K2-001",
|
||
"category": "Lautsprecher",
|
||
"description": "Full description...",
|
||
"specifications": {"weight": 56, "power": 750, ...},
|
||
"images": ["url1", "url2"],
|
||
"rental_price": null,
|
||
"available": true,
|
||
"brand": "L-Acoustics"
|
||
}
|
||
```
|
||
|
||
#### Rental Request Endpoints
|
||
|
||
| Method | Path | Beschreibung | Body | Response |
|
||
|--------|------|--------------|------|----------|
|
||
| POST | `/api/rental-requests` | Mietanfrage erstellen | RentalRequestCreate | `201` {reference_number} / `422` |
|
||
|
||
**RentalRequestCreate Schema:**
|
||
```json
|
||
{
|
||
"event_name": "Sommerfest 2026",
|
||
"date_start": "2026-08-15",
|
||
"date_end": "2026-08-16",
|
||
"location": "München",
|
||
"person_count": 100,
|
||
"contact_name": "Max Mustermann",
|
||
"contact_company": "Firma GmbH",
|
||
"contact_email": "max@example.com",
|
||
"contact_phone": "+49 170 1234567",
|
||
"contact_street": "Hauptstr. 1",
|
||
"contact_postalcode": "80000",
|
||
"contact_city": "München",
|
||
"message": "Brauchen PA für Open-Air",
|
||
"items": [
|
||
{"equipment_id": 123, "quantity": 2},
|
||
{"equipment_id": 456, "quantity": 4}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### Contact Endpoint
|
||
|
||
| Method | Path | Beschreibung | Body | Response |
|
||
|--------|------|--------------|------|----------|
|
||
| POST | `/api/contact` | Kontaktformular | ContactCreate | `200` {success: true} / `422` |
|
||
|
||
**ContactCreate Schema:**
|
||
```json
|
||
{
|
||
"name": "Max Mustermann",
|
||
"email": "max@example.com",
|
||
"phone": "+49 170 1234567",
|
||
"message": "Anfrage bezüglich...",
|
||
"privacy_consent": true
|
||
}
|
||
```
|
||
|
||
#### Admin/Auth Endpoints
|
||
|
||
| Method | Path | Beschreibung | Auth | Response |
|
||
|--------|------|--------------|------|----------|
|
||
| POST | `/api/admin/login` | Admin-Login | – | `200` {token} / `401` |
|
||
| GET | `/api/admin/me` | Aktueller Admin | JWT | `200` {username} / `401` |
|
||
| POST | `/api/admin/sync` | Sync triggern | JWT | `200` {sync_id} / `401` |
|
||
| GET | `/api/admin/sync-status` | Sync-Status | JWT | `200` SyncStatus |
|
||
| GET | `/api/admin/sync-log` | Sync-Log (paginiert) | JWT | `200` SyncLog[] |
|
||
|
||
#### Health Endpoint
|
||
|
||
| Method | Path | Response |
|
||
|--------|------|----------|
|
||
| GET | `/api/health` | `200` {status: "ok", db: "connected", redis: "connected"} |
|
||
|
||
---
|
||
|
||
## 4. Datenbank-Schema (PostgreSQL)
|
||
|
||
### 4.1 Tabellen
|
||
|
||
```sql
|
||
-- Equipment Cache (aus Rentman importiert)
|
||
CREATE TABLE equipment_cache (
|
||
id SERIAL PRIMARY KEY,
|
||
rentman_id VARCHAR(64) UNIQUE NOT NULL,
|
||
name VARCHAR(255) NOT NULL,
|
||
number VARCHAR(64),
|
||
category VARCHAR(128),
|
||
subcategory VARCHAR(128),
|
||
description TEXT,
|
||
specifications JSONB,
|
||
images JSONB,
|
||
rental_price DECIMAL(10, 2),
|
||
brand VARCHAR(128),
|
||
available BOOLEAN DEFAULT true,
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
updated_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_equipment_category ON equipment_cache(category);
|
||
CREATE INDEX idx_equipment_name ON equipment_cache(name);
|
||
CREATE INDEX idx_equipment_number ON equipment_cache(number);
|
||
|
||
-- Rental Requests (Mietanfragen)
|
||
CREATE TABLE rental_requests (
|
||
id SERIAL PRIMARY KEY,
|
||
reference_number VARCHAR(32) UNIQUE NOT NULL,
|
||
event_name VARCHAR(255) NOT NULL,
|
||
date_start DATE NOT NULL,
|
||
date_end DATE NOT NULL,
|
||
location VARCHAR(255),
|
||
person_count INTEGER,
|
||
contact_name VARCHAR(255) NOT NULL,
|
||
contact_company VARCHAR(255),
|
||
contact_email VARCHAR(255) NOT NULL,
|
||
contact_phone VARCHAR(64),
|
||
contact_street VARCHAR(255),
|
||
contact_postalcode VARCHAR(16),
|
||
contact_city VARCHAR(128),
|
||
message TEXT,
|
||
status VARCHAR(32) DEFAULT 'pending',
|
||
rentman_request_id VARCHAR(64),
|
||
rentman_sync_status VARCHAR(32) DEFAULT 'pending',
|
||
rentman_sync_error TEXT,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_rental_status ON rental_requests(status);
|
||
|
||
-- Rental Request Items
|
||
CREATE TABLE rental_request_items (
|
||
id SERIAL PRIMARY KEY,
|
||
rental_request_id INTEGER REFERENCES rental_requests(id) ON DELETE CASCADE,
|
||
equipment_id INTEGER REFERENCES equipment_cache(id),
|
||
equipment_name VARCHAR(255),
|
||
rentman_equipment_id VARCHAR(64),
|
||
quantity INTEGER NOT NULL DEFAULT 1,
|
||
unit_price DECIMAL(10, 2),
|
||
rentman_sync_status VARCHAR(32) DEFAULT 'pending'
|
||
);
|
||
|
||
CREATE INDEX idx_rental_items_request ON rental_request_items(rental_request_id);
|
||
|
||
-- Contacts (Kontaktformular)
|
||
CREATE TABLE contacts (
|
||
id SERIAL PRIMARY KEY,
|
||
name VARCHAR(255) NOT NULL,
|
||
email VARCHAR(255) NOT NULL,
|
||
phone VARCHAR(64),
|
||
message TEXT NOT NULL,
|
||
privacy_consent BOOLEAN NOT NULL,
|
||
email_sent BOOLEAN DEFAULT false,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- Admin Users
|
||
CREATE TABLE admin_users (
|
||
id SERIAL PRIMARY KEY,
|
||
username VARCHAR(64) UNIQUE NOT NULL,
|
||
password_hash VARCHAR(255) NOT NULL,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- Sync Log
|
||
CREATE TABLE sync_log (
|
||
id SERIAL PRIMARY KEY,
|
||
sync_type VARCHAR(32) NOT NULL DEFAULT 'equipment',
|
||
status VARCHAR(32) NOT NULL,
|
||
items_processed INTEGER DEFAULT 0,
|
||
items_failed INTEGER DEFAULT 0,
|
||
error_message TEXT,
|
||
started_at TIMESTAMP DEFAULT NOW(),
|
||
completed_at TIMESTAMP
|
||
);
|
||
|
||
CREATE INDEX idx_sync_log_started ON sync_log(started_at DESC);
|
||
```
|
||
|
||
### 4.2 Redis Usage
|
||
|
||
| Key Pattern | TTL | Zweck |
|
||
|-------------|-----|-------|
|
||
| `equipment:list:{hash}` | 3600s (1h) | Cached equipment list responses |
|
||
| `equipment:detail:{id}` | 3600s (1h) | Cached equipment detail |
|
||
| `equipment:categories` | 3600s (1h) | Cached category list |
|
||
| `rate:contact:{ip}` | 60s | Rate limit contact form (5/min) |
|
||
| `rate:rental:{ip}` | 60s | Rate limit rental requests (5/min) |
|
||
| `rate:login:{ip}` | 60s | Rate limit admin login (5/min) |
|
||
|
||
---
|
||
|
||
## 5. Rentman-Integration
|
||
|
||
### 5.1 Equipment-Import Pipeline
|
||
|
||
```
|
||
[Trigger: Cron 6h ODER Admin POST /api/admin/sync]
|
||
│
|
||
▼
|
||
[1] sync_log Eintrag: status='running', started_at=NOW()
|
||
│
|
||
▼
|
||
[2] RentmanAPI GET /equipment?limit=100&offset=0
|
||
│ ┌─────────────────────────────────┐
|
||
│ │ Loop: solange data nicht leer │
|
||
│ │ - Parse response │
|
||
│ │ - Upsert in equipment_cache │
|
||
│ │ - offset += 100 │
|
||
│ │ - Nächste Seite │
|
||
│ └─────────────────────────────────┘
|
||
│
|
||
▼
|
||
[3] Redis Cache invalidieren (equipment:*)
|
||
│
|
||
▼
|
||
[4] sync_log Update: status='completed', items_processed=N, completed_at=NOW()
|
||
│
|
||
▼
|
||
[5] Fertig. Frontend liest aus PostgreSQL + Redis Cache.
|
||
```
|
||
|
||
**Fehlerbehandlung:**
|
||
- API nicht erreichbar → sync_log status='failed', error_message, bestehende Daten bleiben
|
||
- Partial failure (Seite 3/10) → bereits importierte Seiten bleiben, Fehler geloggt, Retry nur für fehlgeschlagene
|
||
- Retry-Mechanismus: exponential backoff, max 3 retries pro Seite
|
||
|
||
### 5.2 Mietanfrage Pipeline
|
||
|
||
```
|
||
[POST /api/rental-requests]
|
||
│
|
||
▼
|
||
[1] Validierung (Pydantic): Event-Daten, Kontakt-Daten, Items
|
||
│
|
||
▼
|
||
[2] rental_requests Eintrag in DB (status='pending', reference_number generiert)
|
||
│
|
||
▼
|
||
[3] rental_request_items in DB speichern
|
||
│
|
||
▼
|
||
[4] RentmanAPI POST /projectrequests
|
||
│ → rentman_project_request_id erhalten
|
||
│ → rental_requests.rentman_request_id aktualisieren
|
||
│
|
||
▼
|
||
[5] Für jedes Item: RentmanAPI POST /projectrequests/{id}/projectrequestequipment
|
||
│ → rental_request_items.rentman_sync_status='success' / 'failed'
|
||
│
|
||
▼
|
||
[6] Bestätigungs-E-Mail an Kunde (reference_number + Item-Liste)
|
||
│
|
||
▼
|
||
[7] Response 201 an Frontend: {reference_number: "HMS-2026-00123"}
|
||
```
|
||
|
||
**Fehlerbehandlung:**
|
||
- POST /projectrequests schlägt fehl → status='failed', Rentman-Sync-Retry-Queue, User sieht trotzdem Success ('Anfrage eingegangen, wird verarbeitet')
|
||
- Equipment-POST schlägt fehl → item-level retry, Admin-Benachrichtigung
|
||
- SMTP nicht erreichbar → E-Mail in Retry-Queue, Admin-Benachrichtigung
|
||
|
||
### 5.3 Rentman API Mapping
|
||
|
||
**Import (GET /equipment → equipment_cache):**
|
||
|
||
| Rentman Feld | DB Feld | Anmerkung |
|
||
|--------------|---------|-----------|
|
||
| `id` | `rentman_id` | String, unique |
|
||
| `name` | `name` | – |
|
||
| `number` / `code` | `number` | Artikelnummer |
|
||
| `equipment_group.name` | `category` | Kategorie |
|
||
| `description` | `description` | – |
|
||
| `specifications` | `specifications` | JSONB |
|
||
| `images` / `files` | `images` | JSONB array of URLs |
|
||
| `rental_price` | `rental_price` | Decimal, nullable |
|
||
| `brand` | `brand` | – |
|
||
|
||
**Anfrage (POST /projectrequests):**
|
||
|
||
| Frontend Feld | Rentman Feld |
|
||
|---------------|-------------|
|
||
| `event_name` | `name` |
|
||
| `date_start` + `T08:00:00+02:00` | `planperiod_start` |
|
||
| `date_end` + `T02:00:00+02:00` | `planperiod_end` |
|
||
| `date_start` + `T18:00:00+02:00` | `usageperiod_start` |
|
||
| `date_end` + `T23:59:00+02:00` | `usageperiod_end` |
|
||
| `contact_company` oder `contact_name` | `contact_name` |
|
||
| `contact_name` (split) | `contact_person_first_name` / `contact_person_lastname` |
|
||
| `contact_email` | `contact_person_email` |
|
||
| `location` | `location_name` |
|
||
| `contact_street` | `location_mailing_street` |
|
||
| `contact_postalcode` | `location_mailing_postalcode` |
|
||
| `contact_city` | `location_mailing_city` |
|
||
| `message` | `remark` |
|
||
|
||
**Equipment POST (POST /projectrequests/{id}/projectrequestequipment):**
|
||
|
||
| Frontend Feld | Rentman Feld |
|
||
|---------------|-------------|
|
||
| `equipment_name` | `name` |
|
||
| `quantity` | `quantity` / `quantity_total` |
|
||
| `unit_price` (oder 0) | `unit_price` |
|
||
| `/equipment/{rentman_id}` | `linked_equipment` |
|
||
|
||
---
|
||
|
||
## 6. Security-Konzept
|
||
|
||
### 6.1 Authentifizierung
|
||
|
||
| Bereich | Methode |
|
||
|---------|---------|
|
||
| Admin-Login | JWT (python-jose), HttpOnly Cookie, 24h Expiry |
|
||
| Public API | Keine Auth nötig (Equipment GET, Contact POST, Rental POST) |
|
||
| Admin API | JWT required (sync, sync-status, sync-log) |
|
||
|
||
**JWT Implementation:**
|
||
- Algorithm: HS256
|
||
- Secret: `JWT_SECRET` env var
|
||
- Payload: `{sub: username, exp: timestamp}`
|
||
- Cookie: `hms_admin_token`, HttpOnly, Secure, SameSite=Strict
|
||
|
||
### 6.2 Rate Limiting
|
||
|
||
| Endpoint | Limit | Window |
|
||
|----------|-------|--------|
|
||
| `POST /api/contact` | 5 requests | 60s per IP |
|
||
| `POST /api/rental-requests` | 5 requests | 60s per IP |
|
||
| `POST /api/admin/login` | 5 requests | 60s per IP |
|
||
|
||
Implementiert via Redis (INCR + EXPIRE).
|
||
|
||
### 6.3 Input Validation
|
||
|
||
- **Backend:** Pydantic schemas (stricter than DB constraints)
|
||
- Email: EmailStr validator
|
||
- Strings: min/max length, strip whitespace
|
||
- Dates: date format, date_start ≤ date_end
|
||
- Numbers: positive integers
|
||
- Boolean: privacy_consent must be True
|
||
|
||
- **Frontend:** Client-side validation (Vue reactive) vor Submit
|
||
- Gleiche Regeln wie Backend
|
||
- Inline Fehler-Meldungen (aria-invalid, aria-describedby)
|
||
|
||
### 6.4 CORS
|
||
|
||
```python
|
||
# FastAPI CORS
|
||
app.add_middleware(
|
||
CORSMiddleware,
|
||
allow_origins=["https://hms.media-on.de"],
|
||
allow_methods=["GET", "POST"],
|
||
allow_headers=["*"],
|
||
allow_credentials=True, # für Admin-Cookie
|
||
)
|
||
```
|
||
|
||
### 6.5 Secrets Management
|
||
|
||
| Secret | Environment Variable | Usage |
|
||
|--------|---------------------|-------|
|
||
| Rentman API Token | `RENTMAN_API_TOKEN` | Backend Service |
|
||
| JWT Secret | `JWT_SECRET` | Auth Service |
|
||
| Database URL | `DATABASE_URL` | SQLAlchemy |
|
||
| Redis URL | `REDIS_URL` | Redis client |
|
||
| SMTP Host | `SMTP_HOST` | Email Service |
|
||
| SMTP Port | `SMTP_PORT` | Email Service |
|
||
| SMTP User | `SMTP_USER` | Email Service |
|
||
| SMTP Password | `SMTP_PASSWORD` | Email Service |
|
||
| SMTP From | `SMTP_FROM` | Email Service |
|
||
|
||
Alle via Coolify Environment Variables. Nie im Frontend, nie im Git.
|
||
|
||
---
|
||
|
||
## 7. Deployment-Architektur
|
||
|
||
### 7.1 Docker Compose
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
services:
|
||
frontend:
|
||
build: ./frontend
|
||
ports:
|
||
- "3000:3000"
|
||
environment:
|
||
- NUXT_PUBLIC_API_BASE=https://hms.media-on.de/api
|
||
depends_on:
|
||
- backend
|
||
restart: unless-stopped
|
||
|
||
backend:
|
||
build: ./backend
|
||
ports:
|
||
- "8000:8000"
|
||
environment:
|
||
- DATABASE_URL=postgresql+asyncpg://hms:${DB_PASSWORD}@postgres:5432/hms
|
||
- REDIS_URL=redis://redis:6379/0
|
||
- RENTMAN_API_TOKEN=${RENTMAN_API_TOKEN}
|
||
- JWT_SECRET=${JWT_SECRET}
|
||
- SMTP_HOST=${SMTP_HOST}
|
||
- SMTP_PORT=${SMTP_PORT}
|
||
- SMTP_USER=${SMTP_USER}
|
||
- SMTP_PASSWORD=${SMTP_PASSWORD}
|
||
- SMTP_FROM=${SMTP_FROM}
|
||
depends_on:
|
||
- postgres
|
||
- redis
|
||
restart: unless-stopped
|
||
|
||
postgres:
|
||
image: postgres:16-alpine
|
||
volumes:
|
||
- postgres_data:/var/lib/postgresql/data
|
||
environment:
|
||
- POSTGRES_DB=hms
|
||
- POSTGRES_USER=hms
|
||
- POSTGRES_PASSWORD=${DB_PASSWORD}
|
||
restart: unless-stopped
|
||
|
||
redis:
|
||
image: redis:7-alpine
|
||
volumes:
|
||
- redis_data:/data
|
||
restart: unless-stopped
|
||
|
||
volumes:
|
||
postgres_data:
|
||
redis_data:
|
||
```
|
||
|
||
### 7.2 Coolify Deployment
|
||
|
||
- **Platform:** Coolify auf coolify-01 (46.225.91.159)
|
||
- **Domain:** hms.media-on.de
|
||
- **TLS:** Let's Encrypt via Traefik (Coolify automatisch)
|
||
- **Resource Limits:**
|
||
- Frontend: 512MB RAM, 0.5 CPU
|
||
- Backend: 512MB RAM, 0.5 CPU
|
||
- PostgreSQL: 1GB RAM, 1 CPU
|
||
- Redis: 256MB RAM
|
||
|
||
### 7.3 Environments
|
||
|
||
| Environment | Domain | Zweck |
|
||
|-----------|-------|------|
|
||
| Dev | dev.hms.media-on.de | Entwicklung, Testing |
|
||
| Staging | staging.hms.media-on.de | Pre-Production Verification |
|
||
| Prod | hms.media-on.de | Live |
|
||
|
||
### 7.4 CI/CD Pipeline (Forgejo Actions)
|
||
|
||
```
|
||
[Push to main]
|
||
→ [Build Frontend: npm ci && npm run build]
|
||
→ [Build Backend: pip install && pytest]
|
||
→ [Build Docker Images]
|
||
→ [Deploy to Coolify via API]
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Test-Strategie
|
||
|
||
### 8.1 Frontend Tests
|
||
|
||
| Typ | Tool | Scope | Coverage Target |
|
||
|-----|------|-------|----------------|
|
||
| Unit | Vitest | Composables, Stores, Utils | 80% |
|
||
| Component | Vitest + Vue Test Utils | Component rendering, props, emits | 80% |
|
||
| E2E | Playwright | Page flows, forms, navigation | Critical paths |
|
||
|
||
**Critical E2E Paths:**
|
||
1. Home → Mietkatalog → Equipment Detail → Add to Cart → Warenkorb → Mietanfrage → Submit
|
||
2. Home → Kontakt → Form submit → Success
|
||
3. Admin Login → Sync trigger → Status update
|
||
4. Referenzen → Filter → Lightbox
|
||
5. 404 page on invalid route
|
||
|
||
### 8.2 Backend Tests
|
||
|
||
| Typ | Tool | Scope | Coverage Target |
|
||
|-----|------|-------|----------------|
|
||
| Unit | Pytest | Services, Validators, Helpers | 80% |
|
||
| Integration | Pytest + TestClient | API endpoints, DB | 80% |
|
||
| E2E | Pytest | Rentman mock → full pipeline | Critical paths |
|
||
|
||
**Critical Backend Tests:**
|
||
1. Equipment import (mocked Rentman API, paginated)
|
||
2. Rental request submission (mocked Rentman, email mock)
|
||
3. Contact form submission (email mock)
|
||
4. Admin login (valid/invalid credentials)
|
||
5. Rate limiting (6th request blocked)
|
||
6. Equipment search/filter/pagination
|
||
|
||
### 8.3 Test Infrastructure
|
||
|
||
- **Frontend:** Vitest config in `frontend/vitest.config.ts`, Playwright config in `frontend/playwright.config.ts`
|
||
- **Backend:** Pytest config in `backend/pytest.ini`, conftest.py with fixtures
|
||
- **Mocking:** Rentman API mocked via `unittest.mock` / `responses` library
|
||
- **Test DB:** SQLite in-memory oder test PostgreSQL instance
|
||
|
||
---
|
||
|
||
## 9. E-Mail-Service
|
||
|
||
### 9.1 Templates
|
||
|
||
- **Kontaktformular:** HTML + Text template, Reply-To = sender email, To = info@hms-licht-ton.de
|
||
- **Mietanfrage-Bestätigung:** HTML + Text template, To = customer email, enthält reference_number + item list
|
||
|
||
### 9.2 Implementierung
|
||
|
||
```python
|
||
# services/email_service.py
|
||
import aiosmtplib
|
||
from email.mime.text import MIMEText
|
||
from email.mime.multipart import MIMEMultipart
|
||
|
||
class EmailService:
|
||
async def send_contact_email(self, contact: ContactCreate) -> bool:
|
||
# Build MIME message
|
||
# Send via aiosmtplib (async)
|
||
# On failure: enqueue in retry queue
|
||
...
|
||
|
||
async def send_rental_confirmation(self, request: RentalRequest, items: list) -> bool:
|
||
# Build confirmation email with reference_number
|
||
# Send via aiosmtplib
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Architecture Decision Records (ADRs)
|
||
|
||
### ADR-001: Nuxt 3 als Frontend Framework
|
||
- **Status:** Accepted
|
||
- **Entscheidung:** Nuxt 3 (Vue 3 + Tailwind CSS) für Frontend
|
||
- **Begründung:** SSR/SSG Support für SEO (trotz noindex, für KI-Crawler), Vue 3 Composition API, Mobile-First, große Community
|
||
- **Alternativen:** Next.js (React), Astro, plain Vue 3 SPA
|
||
- **Nachteile:** Build-Komplexität durch SSR/SSG-Mischung
|
||
|
||
### ADR-002: FastAPI als Backend Framework
|
||
- **Status:** Accepted
|
||
- **Entscheidung:** FastAPI (Python, async) für Backend API
|
||
- **Begründung:** Rentman Python-Client bereits vorhanden, async für API-Calls, automatische OpenAPI-Doku, Pydantic Validation
|
||
- **Alternativen:** Django REST, Express.js, Go
|
||
- **Nachteile:** Python ecosystem Abhängigkeiten (SQLAlchemy, etc.)
|
||
|
||
### ADR-003: PostgreSQL + Redis
|
||
- **Status:** Accepted
|
||
- **Entscheidung:** PostgreSQL als Primary DB, Redis als Cache + Rate Limiter
|
||
- **Begründung:** PostgreSQL für ACID (rental_requests), JSONB für flexible specs; Redis für Caching + Rate Limiting
|
||
- **Alternativen:** SQLite (zu einfach), MongoDB (overkill)
|
||
|
||
### ADR-004: localStorage für Warenkorb (keine Session-Backend)
|
||
- **Status:** Accepted
|
||
- **Entscheidung:** Client-side localStorage für Warenkorb, kein Backend-Session
|
||
- **Begründung:** Keine User-Auth nötig, keine Server-Session-Storage, persistiert über Reloads, einfach zu implementieren
|
||
- **Alternativen:** Server-side session (Redis), Cookie-based cart
|
||
- **Risiko:** localStorage limit ~5MB, aber Warenkorb-Items sind klein (IDs + quantities)
|
||
|
||
### ADR-005: noindex/nofollow + JSON-LD
|
||
- **Status:** Accepted
|
||
- **Entscheidung:** Alle Seiten noindex/nofollow/noarchive/nosnippet, aber JSON-LD LocalBusiness auf Home
|
||
- **Begründung:** User möchte keine öffentliche Indexierung, aber KI-Crawler sollen strukturierte Daten erkennen
|
||
- **Alternativen:** Vollständige Indexierung (abgelehnt), keine Meta-Tags (zu wenig Info für KI)
|
||
|
||
### ADR-006: SSG für statische Seiten, SSR für Mietkatalog
|
||
- **Status:** Accepted
|
||
- **Entscheidung:** Statische Seiten (Home, Referenzen, Legal) als SSG, Mietkatalog als SSR
|
||
- **Begründung:** Statische Seiten schnell + cached, Mietkatalog braucht aktuelle Equipment-Daten vom Backend
|
||
- **Alternativen:** Alles SSR (zu langsam für statische Seiten), Alles SSG (Mietkatalog nicht aktuell)
|
||
|
||
### ADR-007: JWT HttpOnly Cookie für Admin-Auth
|
||
- **Status:** Accepted
|
||
- **Entscheidung:** JWT in HttpOnly Cookie (nicht localStorage), 24h Expiry
|
||
- **Begründung:** HttpOnly schützt vor XSS, SameSite=Strict vor CSRF, 24h Balance zwischen Security und Usability
|
||
- **Alternativen:** Session in Redis (mehr Complexity), Basic Auth (zu simpel)
|
||
|
||
### ADR-008: Cron-basierter Equipment-Sync (6h) + manueller Trigger
|
||
- **Status:** Accepted
|
||
- **Entscheidung:** Equipment-Sync alle 6h via Cron + manuelle Admin-Trigger
|
||
- **Begründung:** Equipment ändert sich nicht stündlich, 6h ist aktuell genug, manueller Trigger für Ad-hoc Updates
|
||
- **Alternativen:** Webhook von Rentman (nicht verfügbar), Real-time (overkill)
|
||
|
||
---
|
||
|
||
## 11. Non-Functional Requirements
|
||
|
||
### 11.1 Performance
|
||
- Page Load < 2s auf 3G (Lighthouse Mobile Score >= 90)
|
||
- API Response < 500ms für Equipment-Liste (Redis cached)
|
||
- Images: WebP/AVIF, lazy-loading, responsive sizes
|
||
- Frontend Bundle < 200KB gzipped
|
||
|
||
### 11.2 Availability
|
||
- Uptime target: 99.5% (kleines Unternehmen, nicht kritisch)
|
||
- Health check: GET /api/health (Docker restart if unhealthy)
|
||
- Graceful degradation: Equipment aus Cache anzeigen wenn Backend down
|
||
|
||
### 11.3 Scalability
|
||
- Single-tenant, moderate traffic expected
|
||
- Redis Cache handles read load
|
||
- PostgreSQL handles write load (rental requests)
|
||
- Horizontal scaling: post-MVP (mehrere Frontend Container)
|
||
|
||
---
|
||
|
||
## 12. Risiken
|
||
|
||
| Risiko | Wahrscheinlichkeit | Impact | Mitigation |
|
||
|--------|-------------------|--------|------------|
|
||
| Rentman API Felder unklar | Hoch | Mittel | GET /equipment/{id} testen, flexible JSONB-Spalten |
|
||
| Rentman API Rate Limits | Niedrig | Mittel | Paginated import, 6h interval, caching |
|
||
| SMTP nicht erreichbar | Niedrig | Niedrig | Retry-Queue, Admin-Notification |
|
||
| Logo SVG nicht verfügbar | Mittel | Niedrig | Fallback-Text 'HMS Licht & Ton' |
|
||
| Referenz-Bilder fehlen | Mittel | Niedrig | Placeholder images, Unsplash fallback |
|
||
| localStorage Limit | Niedrig | Niedrig | Nur IDs + quantities, max ~1000 items |
|
||
|
||
---
|
||
|
||
## 13. Offene Fragen
|
||
|
||
1. Rentman Equipment-Felder: Welche Felder sind im `equipment`-Objekt verfügbar? → GET /equipment/{id} testen
|
||
2. Equipment-Kategorien: Wie strukturiert? Flaches Feld oder nested object? → API testen
|
||
3. AGB-Texte: Vom User als Text/Markdown bereitstellen?
|
||
4. Referenz-Bilder: 9 Dateien vom User bereitstellen?
|
||
5. SMTP-Zugangsdaten: Welcher Server?
|
||
6. USt-IdNr: Für Impressum benötigt?
|
||
7. Mietpreise: Anzeigen oder 'auf Anfrage'?
|
||
|
||
---
|
||
|
||
## 14. Handoff Summary
|
||
|
||
- **architecture status:** COMPLETE – Alle Komponenten, API-Endpunkte, DB-Schema, Security, Deployment dokumentiert
|
||
- **8 ADRs** mit Begründung und Alternativen
|
||
- **6-8 Tasks** im task_graph.json mit Test-Specs und Abhängigkeiten
|
||
- **ready for review:** YES – Qualitätssicherung durch quality_reviewer empfohlen |