# AGENTS.md — KSB Düren / Bewegungszentrum (test_projekt)

Projektwissen für KI-Agenten. Ergänzt die Always-Rule in `.cursor/rules/projekt-konventionen.mdc`.

## Überblick

Symfony-Anwendung für den **Kreissportbund Düren**: Schwimmcontainer-Terminbuchung,
Bewegungszentrum-Kurse, Event Center (Bewegung am Ehrentag), Kursleiter-Portal,
Container-/Pool-Monitoring, Outlook-/E-Mail-Integration und Inspektionssystem.

- Sprache im Code/UI/Doku: **Deutsch** (User-facing Texte, Commit-Messages, Doku).
- Betriebssystem der Entwicklungsumgebung: **Windows / PowerShell**.
- Produktions-URL: `https://dp-smartsolutions.de/ksbdueren/public`

## Tech-Stack

- **PHP ≥ 8.1**, **Symfony 6.4** (Console, Form, Twig, Messenger, Security, Mailer, HttpClient).
- **Doctrine ORM 3** + Migrations.
- **MySQL/MariaDB** (Haupt-DB via `DATABASE_URL`).
- Twig + Bootstrap; teils CDN (FontAwesome, Bootstrap), teils `public/`-Assets.
- **InfluxDB** für Container-Messwerte (Bayrol/Dulcopool).
- **Microsoft Graph** (Outlook-Kalender, OAuth), **Google API** (Kalender), **IMAP** (E-Mail-Inbox).
- **Dompdf** (PDF/Zertifikate), **Symfony Messenger** (Hintergrund-Jobs).

## Hauptmodule / Domains

| Modul | Routen (Beispiele) | Controller / Services |
|-------|-------------------|------------------------|
| **Terminbuchung Schwimmkurse** | `/appointments/…`, `/public/booking/…` | `PublicBookingController`, `AppointmentController`, `Admin\AdminAppointmentsController` |
| **Kursbuchung Bewegungszentrum** | `/booking/courses/…` | `CourseBookingController`, `Admin\CourseBookingAdminController`, `Admin\CourseAdminController` |
| **Event Center** | `/booking/event-center/…`, `/admin/event-center/…` | `EventCenterBookingController`, `Admin\EventCenterAdminController`, `EventCenterOutlookService` |
| **Kursleiter-Portal** | `/instructor/…` | `InstructorPortalController`, `Admin\InstructorAdminController` |
| **Warteliste** | Admin-Warteliste | `WaitingListController`, `Admin\AdminWaitingListController` |
| **Container / SwimMonitor** | `/device/bayrol`, `/device/dulcopool` | `DeviceControlController`, `ContainerController`, `InfluxDBService` |
| **Inspektion** | Public/API Inspektion | `Public\InspectionController`, `Api\ContainerInspectionController` |
| **E-Mail-Templates** | `/appointments/admin/email-templates/` (nur Termine) | `Admin\EmailTemplatesController` |
| | `/admin/event-center/email-templates/` (Event Center + Kursbuchung) | `Admin\EventCenterEmailTemplateController` |
| **Outlook / Kalender** | `/admin/outlook/…` | `Admin\OutlookController`, `OutlookCalendarService`, `UniversalCalendarService` |
| **E-Mail-Inbox (IMAP)** | Admin Inbox | `Admin\EmailInboxController`, `EmailSyncService` |

## Verzeichnisstruktur (`src/`)

- `Command/` — Konsolen-Commands (Outlook-Sync, Event-Center-Wartung, …)
- `Controller/` — Web/API (`Admin/`, `Api/`, `Public/`, Root)
- `Entity/` — Doctrine-Entities
- `Repository/` — Doctrine-Repositories
- `Service/` — Geschäftslogik (Outlook, E-Mail, PDF, Influx, …)
- `Message/` + `MessageHandler/` — Symfony Messenger
- `Form/`, `Twig/`, `Security/`, `EventListener/`

Templates unter `templates/` (z. B. `appointment/`, `course_booking/`, `event_center/`, `admin/`, `instructor/`).

## Wichtige Env-Variablen

| Variable | Zweck |
|----------|--------|
| `DATABASE_URL` | Haupt-Datenbank |
| `APP_URL` | Basis-URL (`https://dp-smartsolutions.de/ksbdueren/public`) |
| `MAILER_DSN`, `ADMIN_EMAIL` | E-Mail-Versand |
| `MICROSOFT_CLIENT_ID/SECRET/TENANT_ID/REDIRECT_URI` | Outlook-Kalender OAuth |
| `MICROSOFT_OAUTH_*` | E-Mail-IMAP OAuth |
| `OUTLOOK_SYNC_ENABLED` | Outlook-Sync ein/aus |
| `EVENT_CENTER_OUTLOOK_EMAIL` | Event-Center-Outlook-Mailbox |
| `WEBIO_PUBLIC_URL`, `WEBIO_DULCOPOOL_PUBLIC_URL` | Bayrol/Dulcopool iframe-URLs |
| `INFLUXDB_*` | Container-Messdaten |
| `MESSENGER_TRANSPORT_DSN` | Async-Jobs |

Lokale Overrides in `.env.local`. **Keine Secrets in Git committen.**

## Deployment & Infrastruktur

- Server: `webserver` / `142.132.206.12`
- Apache-Proxy für WebIO-Geräte:
  - `bayrol.dp-smartsolutions.de` → `192.168.55.6:8787`
  - `dulcopool.dp-smartsolutions.de` → `192.168.55.5:8787`
- Beispiel-Configs: `config/apache/*.conf.example`
- SSL-Erneuerung: **`SSL_CERTBOT_ERNEUERUNG.md`** (Let's Encrypt / Certbot)

Nach Deploy auf dem Server typisch:

```bash
php bin/console cache:clear
# Messenger-Worker ggf. neu starten — siehe START_MESSENGER_WORKER.md
```

## E-Mail-Template-Typen (Trennung beachten!)

In `EmailTemplate` gibt es drei Gruppen — **nicht vermischen**:

- **`APPOINTMENT_TYPES`** → nur `/appointments/admin/email-templates/` (Schwimmkurse/Termine)
- **`EVENT_CENTER_TYPES`** → `/admin/event-center/email-templates/` (Event Center + Kursbuchung BZ)

Konstanten in `src/Entity/EmailTemplate.php`.

## Event Center / Bewegung am Ehrentag

- Kursart `birthday` → Label **„Bewegung am Ehrentag“** (nicht „Kindergeburtstag“ in der UI).
- Buchungsflow: Kursart → Paket (1.5) → Dauer → Termin → Daten → Bestätigung.
- Workshops können **mehrere Zeitslots** (`bookableTimeSlots`) mit optionaler Kapazität pro Slot haben.
- Outlook-Sync: Token-Refresh in `OutlookCalendarService::refreshAccessToken()`; manueller Sync pro Buchung im Admin.

## Kursleiter-Portal

- Route: `/instructor/dashboard`
- Zeigt zukünftige **und** vergangene Event-Termine (für Abrechnungs-Gegencheck).
- Event-Anmeldung nur bei Status `gebucht` (bezahlt).

## Konventionen & Gotchas

- **Minimale Diffs** — nur anfassen, was die Aufgabe verlangt.
- Keine narrativen Code-Kommentare; PHPDoc nur für nicht-offensichtliche Logik.
- Nach Template-/PHP-Änderungen: `php bin/console lint:twig` / Syntax prüfen; `cache:clear` auf dem Server.
- **Zwei Microsoft-OAuth-Integrationen** (Kalender vs. E-Mail) — unterschiedliche Env-Variablen!
- `EmailTemplatesController` filtert per **Allowlist** `APPOINTMENT_TYPES` — Event-Center-Templates gehören nicht auf die Termin-Seite.
- Apache/Certbot: Zuerst **nur HTTP** (`:80`), dann `certbot --apache`; ProxyPass im `:443`-Block nicht vergessen.
- Viele thematische `.md`-Dateien liegen noch im **Projektroot** (historisch); zentrale Aufgabenliste ab jetzt in `docs/TODO.md`.

## Dokumentations-Struktur (`docs/`)

- `docs/TODO.md` — zentrale, lebende Aufgabenliste. **Zu Beginn lesen, am Ende fortschreiben.**
- `docs/journal/<YYYY-MM-DD>.md` — chronologisches Arbeits-Log (was/warum/Dateien).
- `docs/ARBEITSPAKETE.md` — Feature-/Status-Übersicht (optional, bei größeren Paketen).

Weitere Detail-Doku im Projektroot (Auswahl):

| Datei | Thema |
|-------|--------|
| `SSL_CERTBOT_ERNEUERUNG.md` | SSL-Zertifikate (Certbot) |
| `EVENT_CENTER_EMAIL_WORKFLOW.md` | Event-Center-E-Mails |
| `MICROSOFT_OUTLOOK_ADMIN_SETUP.md` | Outlook-Admin |
| `START_MESSENGER_WORKER.md` | Messenger-Worker |
| `DEPLOYMENT_CHECKLIST.md` | Deployment |
| `INSPECTION_SYSTEM.md` | Inspektionssystem |

## Tests

Verzeichnis `tests/` vorhanden; PHPUnit-Setup je nach Umgebung prüfen. Vor produktiven DB-Änderungen immer Backup / `--dry-run` bei Commands.