Zum Inhalt

Hives-App-Referenz

Die Hives-App ist die größte App in Bifolk (~6.900 Zeilen) und verwaltet die Kerndomäne der Imkerei: Bienenstöcke, Königinnen, Kontrollen, Ernten, Honig-Rückverfolgbarkeit und Imkereiarbeiten.

Übersicht

Speicherort: app/hives/

Zweck: Kerndomäne Imkerei

URL-Namespace: hives:

Wichtige Modelle: Hive, BreedingHive, Queen, HiveInspection, HarvestRecord, HoneyBatch, HoneyBucket, HoneyJar, HivePhoto, HealthStatusChange, BeekeepingOperation (abstrakt), HiveFeeding, HiveTreatment, HiveMaintenance, HiveCombine, QueenReplacement, OperationPhoto


Dateistruktur

hives/
├── models.py              # 20 Modelle (Basis + Arbeiten + Statusverfolgung)
├── mixins.py              # 7 lokale Mixins + 4 re-exportiert aus home.mixins
├── urls.py                # 69 URL-Patterns
├── signals.py             # 9 Signal-Handler
├── signals_status.py      # 4 Signal-Handler (Glas- + Kontroll-Status)
├── views/                 # Views-Paket (9 Module, 3.883 LOC)
│   ├── __init__.py        # Re-Exports aller Views
│   ├── hive_views.py      # Bienenstock-CRUD, Transfer, Labels (770 LOC)
│   ├── queen_views.py     # Königinnenverwaltung, Abstammung (779 LOC)
│   ├── inspection_views.py # Kontroll-CRUD + Liste (284 LOC)
│   ├── harvest_views.py   # Ernteeinträge + Neuzuweisung (327 LOC)
│   ├── batch_views.py     # Chargen-/Eimer-/Glas-Verwaltung (723 LOC)
│   ├── combine_views.py   # Völkervereinigung-CRUD (264 LOC)
│   ├── photo_views.py     # Foto-CRUD (92 LOC)
│   └── operations_views.py # Fütterung/Behandlung/Wartung + PWA-API (444 LOC)
├── forms/                 # Formulare-Paket (9 Dateien, 46 Formularklassen)
│   ├── __init__.py        # Re-Exports aller Formulare
│   ├── base_forms.py      # BaseFilterForm, BaseOperationForm
│   ├── hive_forms.py      # Bienenstock-, Kontroll- und Transfer-Formulare
│   ├── queen_forms.py     # Königinnen-CRUD- und Zuweisungs-Formulare
│   ├── harvest_forms.py   # Ernte- und Neuzuweisungs-Formulare
│   ├── batch_forms.py     # Chargen-/Eimer-/Glas-Formulare
│   ├── combine_forms.py   # Völkervereinigung-Formulare
│   ├── filter_forms.py    # Alle Filter-/Berichts-Formulare
│   └── operation_forms.py # Fütterungs-, Behandlungs-, Wartungs-Formulare
├── services/
│   ├── __init__.py        # Re-Exports
│   ├── batch_service.py   # HoneyBatchService, Nummerierung
│   ├── forecast_service.py # HoneyForecastService
│   ├── geocoding_service.py # Reverse Geocoding via Nominatim
│   ├── qrcode_service.py  # QR-Code-Generierung für Labels
│   ├── query_service.py   # Häufige Abfragemuster
│   └── hive_visualization_service.py # HiveVisualizationService
├── templatetags/
│   ├── hive_tags.py       # can_edit, can_delete, is_breeding_hive Filter + render_hive_structure Tag
│   └── geocoding_tags.py  # get_address, location_with_address Tags
└── templates/hives/       # Templates für alle Views

Modelle

Siehe Datenbankmodelle - Hives-App für vollständige Feldreferenz.

Hive

Haupt-Bienenstockverfolgung mit Standort, Gesundheitsstatus und GPS-Koordinaten. Bienenstocktyp (Stil) kommt von ConfigurableChoice (hive_type-Kategorie).

BreedingHive

Spezialisierter Bienenstock für Königinnenzucht (Multi-Table-Inheritance von Hive). Wird mit gelbem "Zucht"-Badge in der einheitlichen Bienenstockliste angezeigt. Kann nicht für Völkerteilungen verwendet werden.

NucleusHive

Ablegerstock-Klassifizierung für Ableger und neue Völker (Multi-Table-Inheritance von Hive). Wird mit grünem "Ableger"-Badge in der einheitlichen Bienenstockliste angezeigt. Keine spezielle Funktionalität über die Klassifizierung hinaus.

Queen

Königinnenverfolgung mit Abstammung (selbstreferenzierendes mother_queen), Rasse, Markierungsfarbe, Herkunft und optionaler Zuchtdatensatz-Verknüpfung. Die Markierungsfarbe folgt dem internationalen Imkerei-Standard mit festen Optionen (Weiß, Gelb, Rot, Grün, Blau, Unmarkiert). Unterstützt 5-Generationen-Ahnenverfolgung und Abstammungsgraph-Visualisierung.

HiveInspection

Kontrolldatensätze mit Wabenzahlen, Königinnen-/Eisichtung, Temperament, Krankheits-/Schädlingsbeobachtungen, Gewicht, Zargenzahl und optionalen Gesundheitsstatus-Updates für Bienenstock und Königin.

Imkereiarbeiten

Abstrakte Basis (BeekeepingOperation) mit gemeinsamen Feldern: organization, created_by, assigned_to, scheduled/completed dates, status, priority, cost, notes.

Konkrete Arbeitstypen:

  • HiveFeeding — Futtertyp, Menge, Verhältnis, optionale Inventarartikel-Verknüpfung
  • HiveTreatment — Behandlungstyp, Produkt, Dosierung, Datum, Wirksamkeit
  • HiveMaintenance — Wartungstyp, Beschreibung, verwendete Teile
  • HiveCombine — Primär-/Sekundär-Bienenstock, übertragene Waben, entfernte Königin, Methode
  • QueenReplacement — Alte/neue Königin, Methode, Grund, Annahme-Verfolgung

Honig-Rückverfolgbarkeitskette

HarvestRecord → HoneyBatch (Charge) → HoneyBucket → HoneyJar
  • HarvestRecord — Ernte pro Bienenstock mit Gewicht, Waben, Honigtyp
  • HoneyBatch (Charge) — Gruppiert Ernten nach Org/Jahr/Honigtyp. Kennung: {YEAR}-{TYPE}
  • HoneyBucket — Aus Charge befüllt, verfolgt Gewicht und Feuchtigkeit. Nummer: {CHARGE}-B{SEQ}
  • HoneyJar — Einzelnes Glas aus Eimer. Nummer: {BUCKET}-J{SEQ}

Views

Gesamt: 56 Views (44 klassenbasiert + 12 funktionsbasiert) in 9 Modulen

Bienenstockverwaltung (hive_views.py)

View Zweck
HiveListView Einheitliche Liste (Produktion + Zucht + Ableger), Filter (Org/Suche/Typ/Gesundheit/Aktiv), Kartenvisualisierung für Bienenstöcke mit GPS-Koordinaten
HiveDetailView Polymorphes Detail (Hive, BreedingHive oder NucleusHive), Gewichtstrends, Ernteprognose, Mini-Diagramme (6 Monate), Königinnen-Gesundheitsverlauf, Zuchtdaten
HiveCreateView Einheitliches Erstellen mit Produktions-/Zucht-/Ableger-Radio-Auswahl
HiveUpdateView Polymorphes Aktualisieren, unterstützt Umwandlung zwischen Produktions-, Zucht- und Ableger-Bienenstocktypen
HiveDeleteView Polymorphes Löschen
UserHiveListView Bienenstöcke eines bestimmten Benutzers
HiveLabelView Druckbares Etikett mit QR-Code zur Bienenstockidentifikation
hive_transfer Bienenstock (und Königin falls vorhanden) zwischen Organisationen übertragen (Admin/Eigentümer erforderlich)

Kontrollverwaltung (inspection_views.py)

View Zweck
InspectionListView Kontrollenliste mit Sortierung und Filtern (Org/Bienenstock/Zeitraum/Königin gesehen/Gesundheitsstatus)
InspectionCreateView Kontrolle erstellen, Bienenstock/Datum über URL-Parameter vorauswählen, unterstützt "Speichern & Nächste erstellen"
InspectionDetailView Details anzeigen
InspectionUpdateView Kontrolle aktualisieren
InspectionDeleteView Kontrolle löschen

Ernteverwaltung (harvest_views.py)

View Zweck
HarvestListView Liste mit Filtern (Org/Bienenstock/Honigtyp/Zeitraum), Tabellenaktionen
HarvestCreateView Ernte mit Mehrfach-Bienenstock-Auswahl erstellen, Bienenstock über URL-Parameter vorauswählen
HarvestDetailView Erntedetails und zugehörige Bienenstöcke anzeigen
HarvestUpdateView Ernte aktualisieren
HarvestDeleteView Ernte löschen
harvest_reassign Ernte einer anderen Charge zuweisen (Rückverfolgbarkeit bleibt erhalten)

Königinnenverwaltung (queen_views.py)

View Zweck
QueenListView Liste mit Filtern (Org/Bienenstock/Rasse/Farbe/Herkunft/Aktiv/Zugewiesen/Datum), Statistiken
QueenDetailView Details + Abstammung (3-Generationen-Vorfahren, Töchter), Berechtigungen
QueenCreateView Königin erstellen (erfordert Erstellungsberechtigung in der Organisation)
QueenUpdateView Königin aktualisieren
QueenDeleteView Königin löschen (verhindert Löschung bei aktiven Verbindungen)
queen_transfer Königin (und zugeordneten Bienenstock) zu anderer Organisation übertragen
queen_assign Nicht zugewiesene Königin einem weisellosen Bienenstock zuweisen
queen_replace Aktuelle Königin des Bienenstocks durch eine andere ersetzen

Königinnen-Abstammung (queen_views.py)

View Zweck
QueenLineageView Vorfahren einzelner Königin (5 Generationen) + Töchter + Abstammungstiefe
QueenLineageOverview Alle Königinnen mit Abstammungsstatistiken, Filter (Org/Herkunft/Mutter vorhanden/Markierungsfarbe)
queen_lineage_graph Interaktives Netzwerk-Graph-Template zur Abstammungsvisualisierung
queen_lineage_graph_data JSON-API-Endpunkt: Knoten + Kanten für vis.js-Graph (farbcodiert nach Markierungsfarbe)

Völkervereinigung (combine_views.py)

View Zweck
CombineListView Liste der Vereinigungen mit Filtern (Org/Bienenstock/Status/Priorität/Methode/Zeitraum)
CombineDetailView Vereinigungsdetails mit Benutzerberechtigungen anzeigen
CombineCreateView Völkervereinigung erstellen
CombineUpdateView Vereinigung aktualisieren
CombineDeleteView Vereinigung löschen

Bienenstockfotos (photo_views.py)

View Zweck
HivePhotoCreateView Foto zu einem Bienenstock hochladen
HivePhotoUpdateView Fotobeschriftung und Primärstatus bearbeiten
HivePhotoDeleteView Foto löschen

Honig-Chargen-System (batch_views.py)

View Zweck
BatchListView Chargen mit Filtern (Suche/Honigtyp/Status/Zeitraum), sortierbare Spalten
BucketListView Alle Eimer über Chargen hinweg mit Filtern (Honigtyp/Status/Zeitraum)
BatchDetailView Chargen-Zusammenfassung, Erntequellen, Eimer mit Tabellenaktionen
BucketDetailView Eimer-Informationen, paginierte Gläser, Auslastungsstatistiken
JarListView Gläser mit Filtern (Status/Honigtyp), Zusammenfassungsstatistiken
BucketLabelView Druckbares Etikett mit QR-Code zur Eimeridentifikation
bucket_create Eimer aus einer Charge mit Inventar-Eimer-Auswahl erstellen
bucket_create_select_batch Eimer mit Chargenauswahl erstellen (wenn Charge nicht vorausgewählt)
bucket_return_to_inventory Leeren Eimer ins Lagerinventar zurückgeben
jar_create Glas/Gläser aus einem Eimer erstellen mit Inventar-Glas-Auswahl und Mengenangabe
jar_bulk_create Weiterleitung zu jar_create (veraltet)

Imkereiarbeiten (operations_views.py)

Jeder Arbeitstyp (Fütterung, Behandlung, Wartung) hat 6 Views:

  • ListView -- Gefilterte Liste mit Paginierung und Sortierung
  • DetailView -- Vollständige Details mit Fotos
  • CreateView -- Standard-Erstellungsformular
  • UpdateView -- Bearbeitungsformular
  • DeleteView -- Löschen mit Bestätigung
  • QuickCreateView -- AJAX-Erstellung für Schnelleingabe (gibt JSON zurück)

Alle Arbeits-Views verwenden gemeinsame Mixins (OperationListMixin, OperationCreateMixin usw.) für einheitliches Verhalten.

PWA-Offline-API (operations_views.py)

View Zweck
get_hives_for_offline JSON-API: vereinfachte Bienenstockliste (ID, Name) für Offline-PWA-Caching (max. 100 Bienenstöcke)

Formulare

Speicherort: app/hives/forms/ (9 Dateien, 46 Formularklassen)

Die Formulare sind in spezialisierte Module aufgeteilt, um die Wartbarkeit zu verbessern.

Basis-Formulare (base_forms.py)

Formular Typ Zweck
BaseFilterForm Form Basisklasse für Listenfilter mit Organisations- und Datumsbereichsfeldern
BaseOperationForm ModelForm Basisklasse für Arbeitsformulare (Fütterung, Behandlung, Wartung) mit Bienenstockfilterung

Bienenstock- und Kontroll-Formulare (hive_forms.py)

Formular Typ Zweck
HiveForm ModelForm Bienenstock erstellen mit Produktions-/Zucht-Auswahl und dynamischen Stiloptionen
HiveUpdateForm ModelForm Bienenstock aktualisieren (Organisation kann nach Erstellung nicht geändert werden)
BreedingHiveForm ModelForm Zuchtstock erstellen (erweitert HiveForm)
BreedingHiveUpdateForm ModelForm Zuchtstock aktualisieren (erweitert HiveUpdateForm)
HiveTransferForm Form Bienenstock zwischen Organisationen übertragen (Admin/Eigentümer in beiden erforderlich)
HiveInspectionForm ModelForm Bienenstockkontrolle mit Temperament, Gesundheitsstatus und Beobachtungsfeldern erfassen
HiveInspectionUpdateForm ModelForm Bestehende Kontrolle aktualisieren (Bienenstock kann nicht geändert werden)
InspectionListFilterForm Form Kontrollen nach Organisation, Bienenstock, Zeitraum und Gesundheitsstatus filtern

Königinnen-Formulare (queen_forms.py)

Formular Typ Zweck
QueenForm ModelForm Königin mit Organisation, optionalem Bienenstock und optionaler Mutterkönigin erstellen
QueenUpdateForm ModelForm Königin aktualisieren (Organisation kann nicht geändert werden, Aktivstatus hinzugefügt)
QueenTransferForm Form Königin (und ihren Bienenstock) zu einer anderen Organisation übertragen
QueenAssignForm Form Nicht zugewiesene Königin einem weisellosen Bienenstock zuweisen
QueenReplaceForm Form Aktuelle Königin eines Bienenstocks durch eine andere ersetzen

Ernte-Formulare (harvest_forms.py)

Formular Typ Zweck
HarvestForm ModelForm Erntedatensatz mit Mehrfach-Bienenstock-Auswahl erstellen oder bearbeiten
HarvestReassignForm Form Ernte einer anderen Charge zuweisen

Chargen-, Eimer- und Glas-Formulare (batch_forms.py)

Formular Typ Zweck
BatchCreateForm Form Charge aus ausgewählten Ernten erstellen (gleicher Honigtyp erforderlich)
BucketCreateForm ModelForm Eimer aus einer Charge mit Gewichts- und Feuchtigkeitsvalidierung erstellen
BucketCreateWithBatchSelectionForm ModelForm Eimer mit Chargen-Auswahlliste erstellen
JarCreateForm Form Glas/Gläser aus einem Eimer erstellen mit Inventar-Glas-Auswahl, Menge und Notizen

Völkervereinigung-Formulare (combine_forms.py)

Formular Typ Zweck
HiveCombineForm ModelForm Völkervereinigung mit Methodenauswahl erstellen oder aktualisieren
HiveCombineFilterForm Form Vereinigungsliste nach Organisation, Bienenstock, Status, Priorität und Methode filtern

Arbeits-Formulare (operation_forms.py)

Jeder Arbeitstyp (Fütterung, Behandlung, Wartung) hat drei Formulare:

Formular Typ Zweck
HiveFeedingForm ModelForm Fütterungsdatensätze mit Futtertyp und Inventarartikel erstellen/aktualisieren
FeedingQuickCreateForm ModelForm Minimalformular für AJAX-Schnellerstellung von Fütterungen
HiveTreatmentForm ModelForm Behandlungsdatensätze mit Behandlungstyp und Wirksamkeit erstellen/aktualisieren
TreatmentQuickCreateForm ModelForm Minimalformular für AJAX-Schnellerstellung von Behandlungen
HiveMaintenanceForm ModelForm Wartungsdatensätze mit Wartungstyp erstellen/aktualisieren
MaintenanceQuickCreateForm ModelForm Minimalformular für AJAX-Schnellerstellung von Wartungen

Filter- und Berichts-Formulare (filter_forms.py)

Formular Zweck
HarvestReportFilterForm Ernteberichte nach Zeitraum und Bienenstockauswahl filtern
HealthChangesReportFilterForm Gesundheitsänderungen mit Mehrfach-Bienenstock-Vergleich filtern
HiveMetricsFilterForm Metriken-Dashboard nach Zeitraum und Bienenstöcken filtern
HiveListFilterForm Bienenstockliste nach Typ, Stil, Gesundheitsstatus und Aktivstatus filtern
QueenListFilterForm Königinnen nach Rasse, Markierungsfarbe, Herkunft und mehr filtern
HarvestListFilterForm Ernten nach Organisation, Bienenstock, Honigtyp und Datum filtern
QueenLineageFilterForm Abstammungsübersicht nach Herkunft und Markierungsfarbe filtern
FeedingListFilterForm Fütterungsdatensätze nach Typ, Status und Priorität filtern
TreatmentListFilterForm Behandlungsdatensätze nach Typ, Wirksamkeit und Status filtern
MaintenanceListFilterForm Wartungsdatensätze nach Typ, Status und Priorität filtern
BatchFilterForm Chargen nach Honigtyp, Status und Zeitraum filtern
JarFilterForm Gläser nach Status, Honigtyp und Eimer filtern
BucketFilterForm Eimer nach Honigtyp, Status und Zeitraum filtern

View-Mixins

Speicherort: app/hives/mixins.py

Vier Berechtigungs- und Filter-Mixins werden aus home.mixins re-exportiert, um Abwärtskompatibilität zu gewährleisten. Sieben Mixins sind lokal für arbeitsspezifische Muster definiert.

Re-exportiert aus home.mixins

Mixin Zweck
OrgCreatePermissionMixin Prüft user_can_create() für organisationsbasierte Erstellungsberechtigungen
EditPermissionMixin Prüft user_can_edit() für objektbasierte Bearbeitungsberechtigungen
DeletePermissionMixin Prüft user_can_delete() für objektbasierte Löschberechtigungen
OrgFilterMixin Filtert QuerySet nach zugänglichen Organisationen des Benutzers

Lokale Mixins

Mixin Zweck
OperationCreateMixin Gemeinsames CreateView-Muster: Formular-kwargs, Transaktionsbehandlung, Erfolgsmeldung
OperationUpdateMixin Gemeinsames UpdateView-Muster: Formular-kwargs, Erfolgsmeldung
OperationListMixin Gemeinsames ListView-Muster für Arbeiten: QuerySet-Filterung, Sortierung, Paginierung
OperationDetailMixin Gemeinsames DetailView-Muster: Berechtigungsprüfung, Foto-Kontext-Laden
OperationDeleteMixin Gemeinsames DeleteView-Muster: Erfolgsmeldungsbehandlung
OperationQuickCreateMixin AJAX-Schnellerstellungsmuster: JSON-Antwort mit Transaktionsbehandlung
PolymorphicHiveMixin Versucht erst BreedingHive, dann Fallback auf Hive (für Multi-Table-Inheritance)

Signale

Signal Auslöser Aktion
track_hive_health_before_save pre_save auf Hive Speichert vorherigen health_status
track_health_status_change post_save auf Hive Erstellt HealthStatusChange-Eintrag
auto_create_batch_for_harvest post_save auf HarvestRecord Erstellt automatisch Charge (wenn aktiviert)

Services

HoneyBatchService (services/batch_service.py)

  • create_batch_from_harvests() — Atomare Chargenerstellung aus mehreren Ernten
  • create_batch_from_single_harvest() — Convenience-Wrapper
  • reassign_harvest_to_batch() — Ernte zwischen Chargen verschieben
  • create_bucket_from_batch() — Eimer mit Auto-Nummerierung erstellen
  • create_jar_from_bucket() — Glas mit Inventar-Glas-Verfolgung und Auto-Gewichtsberechnung erstellen
  • get_batch_summary() — Gibt Dict mit allen Chargenstatistiken zurück

HoneyForecastService (services/forecast_service.py)

  • forecast_season_outcome() — Analysiert Gewichtszunahme April-Juli, projiziert Ernte
  • Lineare Regression für Gewichtstrends
  • Konfidenzniveaus (niedrig/mittel/hoch)
  • Historischer Durchschnittsvergleich

HiveVisualizationService (services/hive_visualization_service.py)

  • get_hive_structure(hive) — Abfrage der neuesten Durchsichten für Brutzargen- und Honigzargenanzahl
  • Gibt Strukturdaten zurück (Brutzargen, Honigzargen, Ständer, Datum der letzten Aktualisierung)
  • Brutzargen- und Honigzargenanzahlen werden unabhängig abgefragt (können von verschiedenen Durchsichtdaten stammen)
  • Wird vom Template-Tag render_hive_structure verwendet, um eine Regalansicht auf der Bienenstock-Detailseite anzuzeigen

Template-Tags

Speicherort: app/hives/templatetags/hive_tags.py

Filter Verwendung
can_edit {% if hive\|can_edit:user %}
can_delete {% if hive\|can_delete:user %}
render_hive_structure {% render_hive_structure hive %} (Inclusion-Tag)
make_range {% for i in count\|make_range %}

URL-Patterns

69 URL-Patterns für:

  • Bienenstock-CRUD + Transfer (8 Patterns)
  • Kontrollen (5 Patterns)
  • Ernten + Neuzuweisung (6 Patterns)
  • Königinnen + Abstammung (10 Patterns)
  • Königin zuweisen/ersetzen (2 Patterns)
  • Bienenstockfotos (3 Patterns)
  • Honig-Chargen (2 Patterns)
  • Eimer (6 Patterns)
  • Gläser (3 Patterns)
  • Fütterungsarbeiten (6 Patterns)
  • Behandlungsarbeiten (6 Patterns)
  • Völkervereinigungen (5 Patterns)
  • Wartungsarbeiten (6 Patterns)
  • PWA-Offline-API (1 Pattern)

Siehe auch