Dateien nach "/" hochladen

19_technische_architektur.md

@@ -0,0 +1,85 @@
+# Prompt 19 – Technische Architektur
+
+Bezug: alle fachlichen Ergebnisse 01-18. Erste Technikentscheidung, Basis für Prompt 20-22.
+
+## 0. Techstack-Entscheidung (Nutzer)
+- Backend: **Python, FastAPI**
+- Datenbank: **PostgreSQL**
+- Frontend: **Responsive Web-App/PWA** zuerst, native App (iOS/Android) als mögliche spätere Ergänzung
+- Hosting: **normaler Linux-Server/VPS**, noch kein konkreter Anbieter — Architektur muss anbieterunabhängig/portabel sein; Docker dabei optional, keine Pflicht (siehe 9.)
+- Deployment-Regel (Merkregel): ab hier nur Code/Konfigurationsdateien erzeugen, keine lokale Installation/Ausführung, Ziel ist externer Host.
+
+## 1. Frontend
+- Responsive PWA (Progressive Web App): eine Codebasis für PC, Tablet, Smartphone.
+- PWA-Eigenschaften nutzen: Installierbarkeit auf Homescreen, Kamera-Zugriff für QR-/Barcode-Scan (Karte 10) via Browser-API (`getUserMedia`), Service Worker für Kurzzeit-Netzausfall-Pufferung (Prompt 17).
+- Framework-Wahl offen für Umsetzungsphase (z. B. React/Vue), hier nur Architekturebene: Single-Page-App, spricht ausschließlich mit Backend über die API (Prompt 21).
+- Native App (Roadmap) würde später dieselbe API nutzen, keine Backend-Änderung nötig — Grund, warum API-first-Ansatz (siehe 3.) architektonisch wichtig ist.
+
+## 2. Backend
+- Python, FastAPI (asynchron, automatische OpenAPI-Doku passt zu Prompt 21).
+- Schichtenmodell: API-Layer (FastAPI Routen) → Service-/Domänenlogik-Layer (Statusmaschinen Kontrolle/Fehlbestand/Mindermenge, Prompt 02-04) → Datenzugriffs-Layer (ORM, z. B. SQLAlchemy) → PostgreSQL.
+- Domänenlogik zentral gekapselt (z. B. eigenes Modul „Fehlbestand-Statusmaschine"), damit die zentrale Leitplanke „Mindermenge ≠ erledigt" (reihenfolge.md) an genau einer Stelle im Code durchgesetzt wird, nicht verstreut in mehreren Endpunkten.
+- Authentifizierung (Karte 09): eigenes Auth-Modul, Passwort-Hashing (z. B. bcrypt/argon2), Session/Token-basiert (JWT oder Server-Session, Detail Prompt 21).
+
+## 3. API-first-Prinzip
+- Backend bietet ausschließlich eine dokumentierte REST-API (Prompt 21), kein serverseitiges HTML-Rendering.
+- Vorteil: Web-PWA und später native App sind austauschbare Clients derselben API, kein Doppelaufwand bei Geschäftslogik.
+
+## 4. Datenbank
+- PostgreSQL, passend zum stark strukturierten, relationalen Datenmodell (Prompt 06): klare Entitäten, Fremdschlüssel, Historie/Audit-Anforderungen (Prompt 13) profitieren von ACID-Transaktionen.
+- Migrationswerkzeug vorgesehen (z. B. Alembic) für versionierte Schemaänderungen, wichtig bei Vorlagen-Versionierung (Prompt 08) und künftigen Erweiterungen (Medikamente, Lager, Prüfungen).
+
+## 5. Rollen/Rechte technisch
+- Rollenmodell (Prompt 05) als Middleware/Dependency in FastAPI: jede Route deklariert benötigte Rolle(n)/Rechte, zentrale Prüfung statt verstreuter if-Abfragen.
+- Zuständigkeits-Zuordnung (Karte 04) als Datenbank-gestützte Prüfung (n:m Benutzer↔Standort/Objekt), nicht hart codiert.
+
+## 6. Historie/Auditierung technisch
+- Eigene Tabelle(n) für Historieneinträge (Prompt 13), Append-only durch Anwendungslogik erzwungen (kein UPDATE/DELETE-Recht auf Historie-Tabellen für die Anwendung, nur INSERT).
+- Serverseitige Zeitstempel (`now()` in der Datenbank oder Server-Uhrzeit im Backend, nie Client-Wert).
+
+## 7. Benachrichtigungen
+- E-Mail bei neuem Fehlbestand (Karte 05): asynchroner Versand (z. B. Hintergrundtask in FastAPI oder einfache Queue), damit Kontroll-Workflow nicht durch E-Mail-Versand blockiert wird.
+- Kein Push in V1 (Karte 05) – kein zusätzlicher Dienst (Push-Server) nötig.
+
+## 8. Offline-Unterstützung (Prompt 17)
+- Kurzzeit-Pufferung im Frontend (Service Worker/lokaler Speicher im Browser), Übertragung an Backend bei wiederhergestellter Verbindung – rein clientseitiges Konzept, keine Backend-Sonderlogik nötig außer normalen, idempotenten API-Aufrufen.
+
+## 9. Deployment-Architektur (anbieterunabhängig)
+- Docker ist keine Priorität (Nutzerentscheidung) – Deployment stattdessen direkt auf dem Linux-Server/VPS: Backend als Python-Prozess (z. B. Uvicorn hinter systemd-Service), PostgreSQL als regulär installierter Dienst auf demselben oder separatem Server, Reverse-Proxy (z. B. nginx) für HTTPS/Routing.
+- Statische PWA-Dateien vom Reverse-Proxy oder vom Backend selbst ausgeliefert – Detailentscheidung bei Umsetzung.
+- Docker bleibt als spätere Option offen (z. B. falls Hosting-Umgebung es verlangt), ist aber kein Architekturzwang mehr.
+- Wichtig (Merkregel): in dieser Konversation werden nur Code-/Konfigurationsdateien erzeugt, kein lokaler Serverstart, keine lokale DB-Installation – Zielsystem ist der externe Host.
+
+## 10. Modularität für zukünftige Erweiterungen
+- Neue Domänen (Medikamente, Lager, Prüfungen, weitere Ressourcentypen, Karte 11/Prompt 15/24) werden als zusätzliche Service-/Router-Module ergänzt, ohne Kernmodule (Kontrolle/Fehlbestand/Mindermenge) anzufassen — direkte Umsetzung des Designziels aus Prompt 06.
+
+## 11. Hardware-Anforderungen
+
+### Endgeräte (Mitarbeiter/Verantwortliche)
+- Tablet/Smartphone mit Kamera (Barcode-Scan Code128 per Kamera, Prompt 17/Karte 10) – kein Spezialgerät, handelsübliches Gerät mit aktuellem Browser reicht (PWA-Ansatz).
+- PC/Notebook für Dashboard/Administration – normaler Browser reicht, keine Installation nötig.
+
+### Server (extern, Zielsystem)
+- Linux-VPS, Größe skaliert mit Nutzerzahl; für V1/kleine-mittlere Organisation grobe Hausnummer 2 vCPU/4GB RAM, konkret erst bei Umsetzung/Lasttest zu verifizieren.
+- PostgreSQL auf demselben oder separatem Server.
+- Kein Docker-Zwang (siehe 9.), Backend läuft direkt als Python-Prozess (Uvicorn/systemd).
+
+### Sonstiges
+- Label-Drucker für QR-/Barcode-Labels (Karte 10, Roadmap Prompt 24) – Anforderung an Druckqualität/Kontrast dort bereits vermerkt.
+- Kein USB-Handscanner nötig (Entscheidung Karte 10: Kamera-Scan statt Hardware-Scanner).
+
+### Satelliten-Server (Karte 13, Erweiterung)
+- Kleiner lokaler Rechner/Mini-PC vor Ort (Einsatzort/Wache), betreibt dieselbe Software wie der Hauptserver (identisches Backend+DB-Schema), keine reduzierte Sonderversion.
+- Muss vor Trennung mit den relevanten Stammdaten (Materialstamm, Vorlagen der betroffenen Objekte) bestückt sein – Vorbereitung Teil der Auslagerung, Detail offen (siehe Karte 13).
+- Anforderung eher gering (lokales Mehrbenutzer-Team, kein großer Lastfall) – z. B. Mini-PC/NUC-Klasse ausreichend, konkrete Spezifikation bei Umsetzung.
+
+## 12. Mehrserver-Architektur: Hauptserver + Satelliten (Karte 13)
+Ergänzung zur reinen Ein-Server-Architektur (Punkt 9): Neben dem zentralen Hauptserver können **Satelliten-Server** betrieben werden – vollwertige Klone derselben Anwendung, temporär vom Hauptserver getrennt einsetzbar (Details fachlich in [[17_mobile_offline]] Punkt 7, [[13_satelliten_server]]).
+
+- **Objekt-Zuordnung als Kernmechanismus:** jedes Objekt trägt ein Feld „aktuell zuständiger Server" (Hauptserver oder eine bestimmte Satelliten-ID). Nur der zuständige Server nimmt Schreiboperationen für dieses Objekt an – der jeweils andere lehnt sie ab bzw. zeigt es nicht als bearbeitbar.
+- **Eindeutige IDs von Anfang an:** damit am Satelliten neu erzeugte Datensätze (Kontrollen, Fehlbestände, Nachfüllungen, Historie) beim Zusammenführen nicht mit Hauptserver-IDs kollidieren, werden global eindeutige IDs verwendet (z. B. UUID statt fortlaufender Integer-Primärschlüssel für sync-relevante Tabellen) – Abweichung vom reinen `SERIAL`-Schema aus Prompt 20 für genau diese Tabellen, bei Umsetzung zu berücksichtigen.
+- **Synchronisation:** bei wiederhergestellter Verbindung überträgt der Satellit alle neu entstandenen Datensätze an den Hauptserver (einfacher Append-Vorgang, kein Merge/Konfliktlösung nötig, da Objekt-Zuordnung Überschneidungen strukturell ausschließt), danach wird die Objekt-Zuordnung wieder auf den Hauptserver zurückgesetzt.
+- **Kein Zeitlimit:** Architektur darf keine Annahme über maximale Trennungsdauer treffen (Nutzervorgabe) – Synchronisationslogik muss auch nach Tagen/unbestimmter Zeit funktionieren.
+
+## Referenzen
+Bezug: alle Ergebnisse 01-18, [[13_satelliten_server]]