Project to GitHub

2026-06-24 08:33:23 +02:00
commit ecd89a68f8
121 changed files with 6481 additions and 0 deletions
@@ -0,0 +1,51 @@
+# REST-API
+
+Basisroute: `/api`
+
+Die genaue Endpoint-, Request- und Response-Dokumentation steht im Development in der Swagger UI unter `/swagger`.
+
+## Schüler
+
+- `GET /students?skip=0&take=100`
+- `GET /students/{id}`
+- `GET /students/by-card/{nr}`
+- `GET /students/search?name=`
+- `POST /students`
+- `PUT /students/{id}`
+- `DELETE /students/{id}`
+
+## Bücher
+
+- `GET /books?availableOnly=&skip=0&take=100`
+- `GET /books/{id}`
+- `GET /books/by-number/{nr}`
+- `GET /books/search?title=`
+- `GET /books/search?author=`
+- `GET /books/search?subject=`
+- `POST /books`
+- `PUT /books/{id}`
+- `DELETE /books/{id}`
+
+Buch- und Schülersuche werden datenbankseitig gefiltert.
+
+## Ausleihe
+
+- `POST /loans/verify` prüft Schüler, Buch und Verfügbarkeit ohne Datenänderung.
+- `POST /loans` prüft erneut und legt die Ausleihe transaktional an.
+
+## Rückgabe
+
+- `GET /returns/verify/{nr}` liefert die aktive Ausleihe und den Überfälligkeitsstatus.
+- `POST /returns` schließt die aktive Ausleihe transaktional ab.
+
+## Reports
+
+- `GET /reports`
+- `GET /reports/active-loans?skip=0&take=100`
+- `GET /reports/active-students?skip=0&take=100`
+- `GET /reports/overdue?skip=0&take=100`
+- `GET /reports/statistics`
+
+`GET /reports` liefert die ersten 100 Einträge je Liste plus vollständige Statistiken.
+
+Fehler verwenden `application/problem+json` mit `status`, `title`, `detail` und `instance`.
@@ -0,0 +1,50 @@
+# Architektur
+
+Die Anwendung trennt Hosts, UI, API, Verträge und Datenbankzugriff strikt.
+
+```text
+Bsevita.Library.Maui -> Bsevita.Library.Ui -> Bsevita.Library.Models
+Bsevita.Library.Web  -> Bsevita.Library.Ui -> Bsevita.Library.Models
+
+Bsevita.Library.Api  -> Bsevita.Library.Models
+Bsevita.Library.Api  -> EF Core -> SQL Server LocalDB
+```
+
+## Projekte
+
+- `Bsevita.Library.Models`: gemeinsame Request-/Response-Modelle, keine Datenbankabhängigkeit.
+- `Bsevita.Library.Ui`: Razor Class Library mit Seiten, Layouts, Komponenten und API-Clients.
+- `Bsevita.Library.Web`: Browser-Host für die UI; registriert `HttpClient` zur lokalen API.
+- `Bsevita.Library.Maui`: nativer Host für dieselbe UI; löst die API-Adresse je Plattform auf.
+- `Bsevita.Library.Api`: Controller, Services, EF Core und zentrale Fehlerbehandlung.
+- `Bsevita.Library.Api.Tests`: API-Workflowtests mit Testdatenbank.
+
+## Datenfluss
+
+1. UI-Seiten rufen typed API-Clients aus `Bsevita.Library.Ui.Services` auf.
+2. API-Clients senden HTTP-Requests an `/api/...` und lesen JSON oder ProblemDetails.
+3. Controller delegieren an Services; Fachlogik liegt nicht im Controller.
+4. Services verwenden `LibraryDbContext` und mappen Entities auf Models.
+5. SQL Server speichert das Database-First-Schema aus `database/create_database.sql`.
+
+## Datenbank
+
+`database/create_database.sql` ist die Schema-Quelle. Der generierte EF-Code liegt unter `src/Bsevita.Library.Api/Data/Generated` und wird nicht für Fachlogik erweitert.
+
+Wichtige Regeln liegen zusätzlich in der Datenbank:
+
+- `UX_Students_CardNumber`: eindeutige Ausweisnummern.
+- `UX_Books_BookNumber`: eindeutige Buchnummern.
+- `UX_Loans_ActiveBook`: höchstens eine aktive Ausleihe pro Buch.
+
+## Transaktionen und Fehler
+
+Ausleihe, Rückgabe und Löschoperationen laufen in serialisierbaren Transaktionen, wenn eine relationale Datenbank verwendet wird. Vor dem Schreiben wird der aktuelle Zustand erneut geprüft.
+
+Fachfehler werden zentral in `application/problem+json` übersetzt. Die UI zeigt diese Fehler über die gemeinsamen API-Clients an.
+
+## Grenzen
+
+- Die UI referenziert weder `Bsevita.Library.Api` noch `LibraryDbContext`.
+- API-Verträge sind nicht die EF-Entities.
+- Löschen deaktiviert Schüler und Bücher, damit historische Ausleihen erhalten bleiben.