diff --git a/technical-documentation_de.md b/technical-documentation_de.md new file mode 100644 index 0000000..f646c61 --- /dev/null +++ b/technical-documentation_de.md @@ -0,0 +1,63 @@ +# Technische Dokumentation + +## Abhängigkeiten +Folgende Voraussetzungen sind für den Betrieb der Anwendung sicherzustellen: +* Postgresql und initiales Setup + * Ein postgresql Server bzw. lokaler Dienst muss verfügbar sein (nicht Bestandteil der Applikation) + * Die in den Einstellungen hinterlegte Datenbank muss angelegt sein (Django Migrationen erzeugen keine neuen Datenbanken) + * Änderungen an den Tabellen und Modellen dürfen ausschließlich über Django Migrationen vorgenommen werden (`python manage.py makemigrations` + `python manage.py migrate`) + * Das initiale Setup Kommando muss vor der ersten Benutzung ausgeführt werden (`python manage.py setup`) +* Python >3.10 + * Konova basiert auf Django in seiner (möglichst) aktuellen Version (derzeit Django 5.x) + * Aus diesem Grund wird Python >3.10 empfohlen (vgl. jeweils [aktuelles Dockerfile](https://git.naturschutz.rlp.de/SGD-Nord/konova/src/branch/Docker/Dockerfile#L1)) +* pip + * Alle Paketabhängigkeiten der `requirements.txt` müssen mit `pip` installiert sein (`pip install -r requirements.txt`) +* Redis und celery + * `konova` verwendet Subprozesse, um zeit- und rechenintensive Arbeiten in den Hintergrund zu verlagern. Diese `tasks` werden in einer lokalen redis Datenbank abgelegt, aus welcher die Subprozesse diese entnehmen und abarbeiten. Daher ist eine lokale redis Serverinstanz notwendig. [Diese wird im Docker Container mitinstalliert](https://git.naturschutz.rlp.de/SGD-Nord/konova/src/branch/Docker/Dockerfile#L8). + * Die Brokerkonfiguration in [`celery.py`](https://git.naturschutz.rlp.de/SGD-Nord/konova/src/branch/Docker/konova/celery.py#L20) muss auf diese redis Instanz verweisen (normalerweise Default Einstellung ausreichend) + * Subprozesse müssen gestartet werden (`celery -A konova worker -l INFO`). Wird bei der Ausführung des Docker Containers [automatisch gestartet](https://git.naturschutz.rlp.de/SGD-Nord/konova/src/branch/Docker/docker-entrypoint.sh#L5) + * Weitere Informationen zu celery finden sich [hier](https://docs.celeryq.dev/en/stable/userguide/workers.html#starting-the-worker) +* Codelisten + * Alle in `konova` verwendeten auswählbaren Codes (Biotope, Behörden, ...) werden von der öffentlichen Codelisten API des Naturschutzes entnommen (bspw. https://codelisten.naturschutz.rlp.de/repository/referenzliste/903) + * Codes werden durch das entsprechende Kommando aktualisiert (`python manage.py update_codelist`) + * Diese Aktualisierung sollte regelmäßig, z.B. mittels cron, durchgeführt werden +* Flurstücksverschneidung + * Einträge mit vorhandener Geometrie werden mit amtlichen Flurstücken verschnitten, um die überlagerten Flurstücke zu ermitteln + * Die Webanwendung `schneider` bietet eine entsprechende Schnittstelle zur Ver**schneidung** von Geometrien + * Mehr Infos zu `schneider` finden sich [hier](https://git.naturschutz.rlp.de/SGD-Nord/schneider/wiki) +* E-Mail Versand + * Ein SMTP Server muss vorhanden sein, um Mails verschicken zu können + * Die zugehörigen Einstellungen [müssen hinterlegt werden ](https://git.naturschutz.rlp.de/SGD-Nord/konova/src/branch/Docker/konova/sub_settings/django_settings.py#L233-L238) + +## API +Eine Spezifikation zur API des KSP kann [hier](https://git.naturschutz.rlp.de/SGD-Nord/konova/wiki/api_de) gefunden werden. + + +## Neuigkeiten (ServerMessages) +Neuigkeiten können zur Startseite des KSP hinzugefügt werden, sodass sie von jedem Nutzer wahrgenommen werden können. Diese Nachricht werden über das DjangoModel `ServerMessages` realisiert und können im django admin backend angelegt, bearbeitet oder gelöscht werden. +Folgende Attribute stellen das Verhalten einer `ServerMessage` ein: +* is_active + * De-/Aktiviert die Sichtbarkeit der Nachricht (False = Nachricht wird grundsätzlich nicht angezeigt; alternative zum Löschen des Eintrags, bspw. um Korrekturen vorzunehmen, bevor wieder aktiviert wird) +* publish_on + * Der Zeitstempel ab wann die Nachricht angezeigt werden soll (z.B. zu einem fixen Termin in der Zukunft) +* unpublish_on (optional) + * Der Zeitstempel ab wann die Nachricht **nicht** länger angezeigt werden soll + * Falls kein Enddatum angegeben ist, wird die Nachricht dauerhaft sichtbar sein +* importance + * Entscheidet über das genutzte Farbschema der Nachricht + * standard --> Normal, kein besonderes Styling + * info --> Infomeldung, leichtes Blau + * warning --> Warnung, leichtes Rot + +## Gelöschte Einträge wiederherstellen +Alle Hauptdatentypen (EIV, KOM, EMA, OEK) können durch einen Administrator wiederhergestellt werden, wenn sie durch einen Nutzer gelöscht worden sind. Wenn ein Nutzer einen Eintrag löscht, wird dieser [lediglich als gelöscht markiert](https://git.naturschutz.rlp.de/SGD-Nord/konova/src/branch/Docker/konova/models/object.py#L86-L90) und ist somit nicht mehr für den Nutzer zugänglich. + +Solche "gelöschten" Einträge können über das django admin backend wiederhergestellt werden: +1. Datensatz per checkbox markieren +1. Aus Aktionsliste `Restore deleted data` auswählen +1. Aktion ausführen + + +## Fehler +Falls Fehler (z.B. Bugs o.ä.) auf dem deployten System auftreten (und damit bspw. einen Server error 500 auslösen), wird eine Mail an die [`ADMINS`](https://git.naturschutz.rlp.de/SGD-Nord/konova/src/branch/Docker/konova/sub_settings/django_settings.py#L36-L38) verschickt, welche detaillierte Infos über die Ursache, den Zeitpunkt, den ausführenden Nutzer, usw. enthält. +Mehr Infos dazu finden sich [hier](https://docs.djangoproject.com/en/5.0/howto/error-reporting/#email-reports). \ No newline at end of file