DataExchange-App-Referenz¶

Die DataExchange-App bietet Funktionen zur Datensicherung und -wiederherstellung von Organisationsdaten, Import/Export mit Medienunterstützung, Versionskompatibilitätsprüfung und das Laden von Beispieldaten für Demos und Tests.

Übersicht¶

Speicherort: app/dataexchange/

Zweck: Organisationsdaten-Backup/Wiederherstellung, Beispieldaten-Import

Wichtige Modelle: ExportJob, ImportJob

Abhängigkeiten: Alle anderen Apps (exportiert/importiert alle Organisationsdaten), notifications (Abschluss-Benachrichtigungen)

Dateistruktur¶

dataexchange/
├── models.py              # ExportJob, ImportJob
├── views/                 # Views-Paket (2 Module)
│   ├── __init__.py        # Re-exportiert alle 10 Views
│   ├── export_views.py    # 4 Views (Liste, Erstellen, Download, Löschen)
│   └── import_views.py    # 6 Views (Liste, Upload, Vorschau, Detail, Löschen, Beispieldaten)
├── urls.py                # 10 URL-Patterns
├── permissions.py         # 2 Berechtigungs-Mixins
├── validators.py          # Import-Datei-Validierung
├── compatibility.py       # Versionskompatibilität und Migration
├── mappings.py            # Modell-Zuordnungen und Feldkonfigurationen
├── admin.py               # Django-Admin-Konfiguration
├── services/
│   ├── export_service.py  # Export-Generierung
│   ├── import_service.py  # Import-Ausführung
│   ├── image_utils.py     # Bild-Handling
│   ├── rename_utils.py    # Feld-Umbenennung
│   └── sample_data_service.py # Beispieldaten
├── exporters/
│   ├── base.py            # DataExporter-Basisklasse
│   └── model_exporters.py # 27 modellspezifische Exporter
└── management/commands/
    └── generate_sample_export.py

Modelle¶

ExportJob¶

Verfolgt Export-Operationen zur Datensicherung von Organisationsdaten.

Statusverlauf: pending → processing → completed / failed

Feld	Typ	Beschreibung
organization	FK(Organization)	Zu exportierende Organisation
created_by	FK(User)	Benutzer, der den Export gestartet hat
status	CharField	pending, processing, completed, failed
file_path	CharField	Pfad zur generierten Export-Datei
include_media	BooleanField	Ob Mediendateien einbezogen werden (Standard: True)
total_records	IntegerField	Anzahl der exportierten Datensätze
file_size	BigIntegerField	Dateigröße in Bytes
error_message	TextField	Fehlerdetails bei fehlgeschlagenem Export
created_at	DateTimeField	Erstellungszeitpunkt des Jobs
completed_at	DateTimeField	Abschlusszeitpunkt des Jobs

Indexe: (organization, created_at), (status)

ImportJob¶

Verfolgt Import-Operationen zur Wiederherstellung von Organisationsdaten.

Statusverlauf: pending → validating → processing → completed / failed

Feld	Typ	Beschreibung
organization	FK(Organization)	Zielorganisation für den Import
imported_by	FK(User)	Benutzer, der den Import gestartet hat
status	CharField	pending, validating, processing, completed, failed
file_path	CharField	Pfad zur hochgeladenen Import-Datei
import_type	CharField	full, merge (Standard) oder partial
summary	JSONField	Zusammenfassung der Import-Ergebnisse
error_message	TextField	Fehlerdetails bei fehlgeschlagenem Import
created_at	DateTimeField	Erstellungszeitpunkt des Jobs
completed_at	DateTimeField	Abschlusszeitpunkt des Jobs

Indexe: (organization, created_at), (status)

Views¶

Export-Views¶

View	Typ	Zweck
ExportListView	ListView	Exporte für Organisation auflisten, paginiert 20, sortierbare Spalten
ExportCreateView	View	Export-Formular anzeigen (GET), Export erstellen und generieren (POST)
ExportDownloadView	View	Abgeschlossenen Export als JSON-Datei herunterladen
export_delete_view	Funktion	Export-Job und zugehörige Datei löschen (POST, nur Besitzer/Admin)

Import-Views¶

View	Typ	Zweck
ImportListView	ListView	Importe für Organisation auflisten, paginiert 20, sortierbare Spalten
ImportUploadView	View	Upload-Formular anzeigen (GET), Datei validieren und Import-Job erstellen (POST)
ImportPreviewView	View	Import-Vorschau mit Validierungsergebnissen (GET), Import ausführen (POST)
ImportDetailView	View	Import-Details und Zusammenfassung anzeigen
import_delete_view	Funktion	Import-Job und zugehörige Datei löschen (nur Besitzer/Admin)

Beispieldaten¶

View	Typ	Zweck
SampleDataImportView	View	Beispieldaten-Formular anzeigen (GET), Beispieldaten importieren (POST)

Der Beispieldaten-Import unterstützt zwei Modi: minimal (Basisdaten) und comprehensive (vollständiger Datensatz mit optionalen Fotos und Transaktionen).

Berechtigungen¶

Speicherort: app/dataexchange/permissions.py

Mixin	Erforderliche Rolle	Details
CanExportOrganizationDataMixin	Besitzer oder Admin	Erfordert aktive Organisation
CanImportOrganizationDataMixin	Besitzer oder Admin (oder Superuser)	Superuser umgehen die Organisationsmitgliedschaftsprüfung

Beide Mixins ermitteln die Organisation über die get_organization()-Methode der View oder über die current_organization der Middleware. Sie lösen PermissionDenied aus, wenn der Benutzer nicht über die erforderliche Rolle verfügt.

Exporter¶

Speicherort: app/dataexchange/exporters/

DataExporter-Basisklasse¶

Die DataExporter-Basisklasse bietet gemeinsame Serialisierungsfunktionalität für alle Modell-Exporter:

Automatische Feld-Serialisierung: ForeignKey zu PK, ManyToMany zu Liste von PKs, File/Image zu Base64, Date/DateTime zu ISO-Format, JSONField direkt übernommen
export() gibt eine Liste serialisierter Dictionaries für alle Datensätze im Queryset zurück
get_queryset() muss in Unterklassen überschrieben werden, um nach Organisation zu filtern

Modell-Exporter¶

27 modellspezifische Exporter sind definiert, die jeweils DataExporter mit organisationsbezogenen Querysets erweitern. Sie werden in EXPORT_ORDER aufgelistet, um die referenzielle Integrität beim Import sicherzustellen:

Gruppe	Exportierte Modelle
Organisation	Organization, OrganizationSettings, OrganizationMembership
Konfiguration	ChoiceCategory, ConfigurableChoice
Lager	WarehouseLocation, InventoryItem
Bienenstöcke	Hive, BreedingHive, Queen, HivePhoto, HiveInspection
Honig	HarvestRecord, HoneyBatch, HoneyBucket, HoneyJar
Zucht	QueenBreeding, ColonySplit
Operationen	HiveFeeding, HiveTreatment, HiveMaintenance, HiveCombine, QueenReplacement
Verkauf	ProductSale, ProductSaleItem, InventoryTransaction
Medien	OperationPhoto (verwendet GenericForeignKey mit ContentType-Filterung)

Validatoren¶

Speicherort: app/dataexchange/validators.py

Die ImportValidator-Klasse führt eine mehrstufige Validierung der hochgeladenen Import-Dateien durch:

Dateigrößenprüfung -- maximal 500 MB
Dateiendungsprüfung -- muss .json sein
JSON-Parsing -- validiert gültiges JSON-Format
Strukturvalidierung -- prüft auf erforderliche Felder: export_version, export_date, organization_id, data, metadata
Versionskompatibilität -- prüft gegen minimale/maximale unterstützte Versionen
Prüfsummenverifizierung -- validiert die Integrität, falls eine Prüfsumme vorhanden ist
Modellvalidierung -- stellt sicher, dass Organisationsdaten vorhanden sind, zählt Datensätze
Konflikterkennung -- warnt, wenn die Organisation bereits vorhandene Daten enthält

Die ValidationResult-Klasse enthält den Validierungsstatus mit Fehlern, Warnungen und Informationsdaten.

Die Komfortfunktion validate_import_file(file, organization) erstellt einen Validator und gibt das Ergebnis zurück.

Kompatibilität¶

Speicherort: app/dataexchange/compatibility.py

Behandelt die Versionskompatibilitätsprüfung und Datenmigration zwischen verschiedenen Export-Formatversionen.

Aktuelle Version: 2.0.0

Minimal unterstützte Version: 1.0.0

Versionskompatibilität¶

Die VersionCompatibility-Klasse prüft, ob eine Export-Version im unterstützten Bereich liegt, und bestimmt, ob eine Migration erforderlich ist.

Datenmigration¶

Die DataMigrator-Klasse wendet sequenzielle Migrationen entlang des Versionspfads an.

Migration v1.0.0 auf v2.0.0:

Entfernt veraltete Modelle: Activity, FeedingRecord, TreatmentRecord, ActivityPhoto
Benennt Queen-Felder um: current_hive zu hive, mother zu mother_queen
Entfernt Queen-Feld: father

Schema-Validierung¶

Die SchemaValidator-Klasse validiert die Struktur von Export-Daten und stellt sicher, dass alle erforderlichen Wurzelfelder vorhanden sind und die Datentypen korrekt sind.

Zuordnungen¶

Speicherort: app/dataexchange/mappings.py

Definiert die Konfiguration, wie jedes Modell während Export- und Import-Operationen behandelt wird.

FieldMapping¶

Feldweise Konfiguration einschließlich:

Ob in Export/Import einbezogen werden soll
Pflichtfeld-Kennzeichnung für Import
Standardwerte
Transformationsfunktionen für Import und Export

ModelMapping¶

Modellweise Konfiguration einschließlich:

dependencies -- Modelle, die vor diesem importiert werden müssen
unique_fields -- Felder zur Identifizierung bestehender Datensätze beim Zusammenführen
auto_fields -- Felder, die beim Import übersprungen werden (z.B. id, created_at)
file_fields -- Felder mit Dateien/Bildern (benötigen Base64-Dekodierung)
fk_fields -- Fremdschlüssel-Zuordnungen (Feldname zu zugehörigem Modellnamen)

27 Modell-Zuordnungen sind in MODEL_MAPPINGS definiert und decken alle exportierten Modelle ab.

EXPORT_ORDER und IMPORT_ORDER definieren die abhängigkeitsgerechte Verarbeitungsreihenfolge.

Hilfsfunktionen: get_model_mapping(), get_dependencies(), get_unique_fields(), get_fk_fields(), should_skip_field_on_import(), get_file_fields(), validate_import_order()

Import-Typen¶

Typ	Verhalten
full	Vorhandene Organisationsdaten löschen, alles importieren
merge	Vorhandene Daten behalten, importierte Daten hinzufügen (Standard)
partial	Selektiver Import bestimmter Modelle

URL-Patterns¶

dataexchange/exports/                       --> ExportListView (export-list)
dataexchange/exports/create/                --> ExportCreateView (export-create)
dataexchange/exports/<int:pk>/download/     --> ExportDownloadView (export-download)
dataexchange/exports/<int:pk>/delete/       --> export_delete_view (export-delete)
dataexchange/imports/                       --> ImportListView (import-list)
dataexchange/imports/upload/                --> ImportUploadView (import-upload)
dataexchange/imports/<int:pk>/preview/      --> ImportPreviewView (import-preview)
dataexchange/imports/<int:pk>/              --> ImportDetailView (import-detail)
dataexchange/imports/<int:pk>/delete/       --> import_delete_view (import-delete)
dataexchange/sample-data/                   --> SampleDataImportView (sample-data-import)

Admin-Oberfläche¶

Speicherort: app/dataexchange/admin.py

Beide Modelle sind mit vollständiger Admin-Konfiguration registriert:

ExportJobAdmin -- Listenanzeige mit Organisation, Status, Datensätze, Dateigröße. Filter nach Status, Medieneinbeziehung, Datum. Gruppierte Fieldsets für Basisinformationen, Optionen, Ergebnisse und Zeitstempel.
ImportJobAdmin -- Listenanzeige mit Organisation, Status, Import-Typ. Filter nach Status, Import-Typ, Datum. Gruppierte Fieldsets für Basisinformationen, Datei, Ergebnisse und Zeitstempel.

Signale¶

Die DataExchange-App hat keine eigenen Signal-Handler. Der Abschluss von Export und Import löst Benachrichtigungen über Signal-Handler in der Notifications-App (notifications/signals.py) aus.

Wenn ein ExportJob oder ImportJob mit dem Status completed oder failed gespeichert wird, wird automatisch eine Benachrichtigung für den Benutzer erstellt, der die Operation gestartet hat.

Services (Zusammenfassung)¶

Services behandeln die Kerngeschäftslogik und werden in der Services-Dokumentation (Chunk 2) im Detail dokumentiert.

Service	Wichtige Funktionen
Export-Service	`create_export()`, `generate_export_file()`, `cleanup_old_exports()`
Import-Service	`create_import_job()`, `execute_import()`
Beispieldaten-Service	`import_sample_data()` (Modi: minimal, comprehensive)

Siehe auch¶

Notifications-App-Referenz - Export-/Import-Abschluss-Benachrichtigungen