122 lines
3.2 KiB
Markdown
122 lines
3.2 KiB
Markdown
# Design Document
|
|
|
|
## Overview
|
|
|
|
Das Email-Sortierer System besteht aus drei Hauptkomponenten:
|
|
1. Frontend: Vanilla JavaScript Multi-Step-Formular
|
|
2. Backend: Express.js Server mit API-Endpunkten
|
|
3. Datenbank: Appwrite Collections für Produkte, Fragen, Submissions, Antworten und Orders
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser (HTML/JS)
|
|
↓ HTTP
|
|
Express Server
|
|
↓ API Calls
|
|
Appwrite Database
|
|
|
|
Express Server
|
|
↓ Webhook
|
|
Stripe Payment
|
|
```
|
|
|
|
## Components and Interfaces
|
|
|
|
### Frontend (public/index.html)
|
|
- Multi-step form renderer
|
|
- State management für Antworten
|
|
- API calls zu Backend
|
|
|
|
### Backend (server/index.mjs)
|
|
- GET /api/questions - Lädt Fragen aus Appwrite
|
|
- POST /api/submissions - Speichert Kundenantworten
|
|
- POST /api/checkout - Erstellt Stripe Checkout Session
|
|
- POST /stripe/webhook - Empfängt Stripe Events
|
|
|
|
### Bootstrap Script (server/bootstrap-appwrite.mjs)
|
|
- Erstellt Appwrite Database und Collections
|
|
- Erstellt alle Attribute/Spalten
|
|
- Seeded Produkt und 13 Fragen
|
|
|
|
## Data Models
|
|
|
|
### Products Collection
|
|
- slug: string
|
|
- title: string
|
|
- description: string
|
|
- priceCents: integer
|
|
- currency: string
|
|
- isActive: boolean
|
|
|
|
### Questions Collection
|
|
- productId: string
|
|
- key: string
|
|
- label: string
|
|
- helpText: string (optional)
|
|
- type: string (text, email, select, multiselect, textarea)
|
|
- required: boolean
|
|
- step: integer
|
|
- order: integer
|
|
- optionsJson: string (optional)
|
|
- isActive: boolean
|
|
|
|
### Submissions Collection
|
|
- productId: string
|
|
- status: string (draft, paid)
|
|
- customerEmail: email (optional)
|
|
- customerName: string (optional)
|
|
- utmJson: string (optional)
|
|
- finalSummaryJson: string
|
|
- priceCents: integer
|
|
- currency: string
|
|
|
|
### Answers Collection
|
|
- submissionId: string
|
|
- answersJson: string
|
|
|
|
### Orders Collection
|
|
- submissionId: string
|
|
- orderDataJson: string
|
|
|
|
## Correctness Properties
|
|
|
|
*Properties sind formale Aussagen über das Systemverhalten, die über alle gültigen Eingaben gelten.*
|
|
|
|
**Property 1: Question Loading**
|
|
*For any* active product, when questions are requested, all active questions for that product should be returned ordered by step and order.
|
|
**Validates: Requirements 1.1, 2.4**
|
|
|
|
**Property 2: Submission Creation**
|
|
*For any* valid answers object, when a submission is created, the system should store the submission and return a valid submissionId.
|
|
**Validates: Requirements 2.2, 2.3**
|
|
|
|
**Property 3: Payment Flow**
|
|
*For any* valid submissionId, when checkout is initiated, the system should create a Stripe session and return a checkout URL.
|
|
**Validates: Requirements 3.1, 3.2**
|
|
|
|
**Property 4: Webhook Validation**
|
|
*For any* Stripe webhook event, when the signature is invalid, the system should reject the request with 400 status.
|
|
**Validates: Requirements 3.4**
|
|
|
|
## Error Handling
|
|
|
|
- Fehlende Umgebungsvariablen → Server exit mit Fehler
|
|
- Ungültige Webhook-Signatur → 400 Bad Request
|
|
- Fehlende submissionId → 400 Bad Request
|
|
- Appwrite Fehler → Console error + graceful handling
|
|
|
|
## Testing Strategy
|
|
|
|
**Unit Tests:**
|
|
- API endpoint responses
|
|
- Data validation
|
|
- Error handling
|
|
|
|
**Property-Based Tests:**
|
|
- Question ordering across random datasets
|
|
- Submission creation with various answer formats
|
|
- Webhook signature validation
|
|
|
|
Minimum 100 Iterationen pro Property Test.
|