DiveLogix360 API – Gesamtübersicht UC00¶
Stand: 12.08.2026 16:55 Branch: main Status: Aktiv
| Datum, Uhrzeit | Version | Änderung | Autor |
|---|---|---|---|
| 12.08.2026 16:55 | 2.1 | Historische UC00-Blockverträge in die Nachweisebene verschoben | Codex |
| 09.08.2026 15:43 | 2.0 | Übersicht auf den kanonischen UC00-OpenAPI- und Testvertrag umgestellt und historische Blockstände eingeordnet | Codex |
| 01.08.2026 14:55 | 1.0 | Kopfbereich vereinheitlicht | David Mittig |
| 01.08.2026 11:12 | 1.0 | Kopfbereich ergänzt | David Mittig |
Scope: UC00 – Tenant-Onboarding und Schulverwaltung
Basis-URL:https://api.divelogix360.ch/v1als Platzhalter bis zur produktiven DNS-Freigabe
Verbindliche Quelle: openapi-uc00.yaml
Testgrundlage: UC00-API-Testvertrag
1. Quellenstatus¶
| Artefakt | Status | Bedeutung |
|---|---|---|
| openapi-uc00.yaml | Verbindlich | Kanonischer OpenAPI-3.1-Vertrag für UC00 |
| UC00-API-Testvertrag | Verbindlich | 61 stabile Testfall-IDs und Abnahmeziele |
../evidence/historical/api/uc00/openapi-block1-auth.yaml bis openapi-block4-onboarding.yaml |
Historisch | Frühere Arbeitsstände; nicht mehr als Implementierungsquelle verwenden |
Bei Widersprüchen gilt zuerst die UC00-Spezifikation als Fachquelle. Die OpenAPI-Datei ist der verbindliche Schnittstellenvertrag; das Prisma-Schema ist gemäss ADR-009 die technische Wahrheit der Anwendungsmodelle.
2. Funktionsgruppen¶
| Gruppe | Inhalt |
|---|---|
| Authentifizierung | Normalisierter Login, Zwei-Faktor-Authentifizierung, Wiederherstellungscode, Sitzungsrotation und Logout |
| Sicherer Erstzugang | Einladungsprüfung, Passwort- und TOTP-Einrichtung, einmalige Ausgabe von Wiederherstellungscodes |
| Tenant-Vorbereitung | Minimale Tenant-Anlage ohne Benutzer oder Einladung, Vertragspartei und kontrollierte Statusübergänge |
| Vertragsabschluss | Elektronischer Sieben-Tage-Token sowie externer PDF-Upload mit Quarantäne und getrennter Prüfung |
| Einladungen | Tenant-Admin erst nach akzeptiertem Vertrag; Mitarbeiter tenantisoliert; globale E-Mail-Eindeutigkeit |
| Schulprofil und Onboarding | Getrenntes operatives Profil sowie genau vier persistente Schritte: school_profile, contact_details, first_employee, confirmation |
| Offboarding und Export | Sofortige operative Sperrung, 30 Tage Exportzugang, operative Löschung spätestens nach 90 Tagen und backendvermittelter Download |
Der Vertrag umfasst 33 Operationen auf 30 Pfaden. Jede Operation besitzt eine eindeutige operationId und mindestens eine x-test-cases-Zuordnung.
3. Rollen und Zugriff¶
| Rolle | UC00-Zugriff |
|---|---|
superadmin |
Tenant-Vorbereitung, Vertragsverwaltung, Admin-Einladung, Zwei-Faktor-Reset und Offboarding |
tenant_admin |
Eigenes Schulprofil, eigenes Onboarding, Mitarbeitereinladung und Export des eigenen Tenants |
employee |
In UC00 kein administrativer Schreibzugriff |
| Öffentlich | Ausschliesslich tokengebundene Vertrags- und Einladungsabläufe sowie Authentifizierung |
Jeder geschützte Zugriff folgt Rollen-, Tenant- und Ressourcenprüfung mit Standardverweigerung. PostgreSQL Row-Level Security (RLS, zeilenbasierte Zugriffskontrolle) bildet eine zusätzliche Schutzschicht; sie ersetzt keine Anwendungsberechtigung.
4. Token- und Zeitregeln¶
| Nachweis | Verbindliche Regel |
|---|---|
| Access-Token | Kurzlebig; konkrete Laufzeit zentral konfiguriert |
| Refresh-Token | Opaque, gehasht gespeichert und bei Verwendung rotiert |
| Zwei-Faktor-Challenge | Kurzlebig und nur für den begonnenen Login verwendbar |
| Vertragstoken | Gehasht, einmalig, sieben Kalendertage gültig; Neuanforderung widerruft offene Alt-Token |
| Tenant-Admin-Einladung | Gehasht, einmalig, 72 Stunden gültig; erneuter Versand ersetzt die offene Einladung |
| Exportdownload | Zeitbegrenzt, tenantisoliert und ausschliesslich backendvermittelt |
Tokenwerte, Passwörter, TOTP-Geheimnisse, Wiederherstellungscodes und Vertragsdokumente werden weder protokolliert noch als vertraulicher Inhalt per E-Mail versandt.
5. Fehlervertrag¶
Fehler enthalten mindestens einen maschinenlesbaren code, eine verständliche message, den HTTP-Status und eine request_id. Pflichtfehler sind unter anderem:
| Code | HTTP-Status | Bedeutung |
|---|---|---|
email_already_in_use |
409 | Normalisierte E-Mail-Adresse ist global belegt |
contract_not_accepted |
409 | Tenant-Admin-Einladung ist vor gültigem Vertrag gesperrt |
contract_party_incomplete |
409 | Rechtliche Vertragspartei ist für den Abschluss unvollständig |
invalid_or_expired_token |
400 oder 410 gemäss Operation | Token ist ungültig, widerrufen, verwendet oder abgelaufen |
forbidden |
403 | Rolle oder Zugriffskontext ist unzulässig |
not_found |
404 | Ressource ist nicht verfügbar; fremde Existenzdetails werden nicht offengelegt |
Die vollständigen Antwortschemas und operationsbezogenen Statuscodes stehen in openapi-uc00.yaml.
6. Automatische Strukturprüfung¶
Im Backend-Verzeichnis prüft folgender Befehl den Vertrag:
npm run openapi:uc00:validate
Die Prüfung umfasst OpenAPI-Version, interne Verweise, Pflichtoperationen, eindeutige Operation-IDs, 61 lückenlose Testfall-IDs, das exakte Vier-Schritt-Onboarding, Pflichtfehlercodes und die historische Kennzeichnung der früheren API-Blöcke. Sie ersetzt noch keine Unit-, Integrations-, Ende-zu-Ende- oder Sicherheitstests gegen die Implementierung.