SystemConfig-App-Referenz¶

Die SystemConfig-App bietet datenbankgestützte konfigurierbare Dropdown-Auswahloptionen für Formulare, die es Administratoren ermöglichen, Optionen ohne Codeänderungen anzupassen. Auswahloptionen sind organisationsspezifisch und umfassen Hilfsfunktionen, Login-Validierung, Template-Filter und Löschschutz.

Übersicht¶

Speicherort: app/systemconfig/

Zweck: Konfigurierbare Dropdown-Auswahloptionen mit Hilfsfunktionen und Login-Validierung

URL-Namespace: /system/

Wichtige Modelle: ChoiceCategory, ConfigurableChoice

Verwendet von: Hives (Beutensysteme, Honigtypen, Arbeitstypen), Breeding (Methoden, Status), Warehouse (Artikeltypen, Einheiten, Zahlungsmethoden), Organizations (Einstellungsformular)

Dateistruktur¶

systemconfig/
├── models.py              # 2 Modelle (ChoiceCategory, ConfigurableChoice)
├── views.py               # 6 View-Klassen + 1 Berechtigungs-Mixin
├── forms.py               # ConfigurableChoiceForm
├── urls.py                # 6 URL-Patterns
├── utils.py               # 8 Hilfsfunktionen für Formulare/Views
├── services.py            # Login-Validierungsservice
├── signals.py             # 1 Signal-Handler (user_logged_in)
├── apps.py                # AppConfig mit post_migrate Auto-Kategorie-Erstellung
├── admin.py               # Admin mit Inline-Bearbeitung + Massen-Löschschutz
├── templatetags/
│   └── choice_filters.py  # 2 Template-Filter (get_choice_display, translate)
├── management/commands/
│   └── load_default_categories.py  # CLI zum Laden von Standardkategorien + Optionen
├── tests/                 # Modell-, View-, Signal- und Service-Tests
└── templates/systemconfig/
    ├── category_list.html
    ├── choice_list.html
    ├── choice_form.html
    └── choice_confirm_delete.html

Modelle¶

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

ChoiceCategory¶

Repräsentiert eine konfigurierbare Kategorie (z.B. "Beutensystem", "Honigtyp").

Felder: name, code (eindeutiger Slug), description, order, is_active, created_at, updated_at

27 Standardkategorien (automatisch erstellt via post_migrate-Signal in apps.py): honey_type, hive_style, health_status, queen_origin, temperament, inspection_status, drone_presence, operation_status, operation_priority, feed_type, treatment_type, treatment_effectiveness, breeding_method, breeding_status, breeding_quality, combine_method, split_type, split_status, queen_replacement_method, queen_replacement_reason, maintenance_type, unit_type, equipment_type, supply_type, product_type, payment_method, transaction_type

Hinweis: queen_marking_color ist nicht mehr konfigurierbar; Sie verwendet einen festen Satz von Optionen (Weiß, Gelb, Rot, Grün, Blau, Unmarkiert) nach dem internationalen Imkerei-Standard.

ConfigurableChoice¶

Einzelne Auswahloptionen innerhalb einer Kategorie, die zu einer bestimmten Organisation gehören.

Felder: category (FK), organization (FK, nullable), label, value (auto-slug aus label, nicht editierbar), description, order, is_active, is_default, brood_chamber_weight_kg, honey_chamber_weight_kg, honeycomb_weight_kg, created_at, updated_at

Einschränkung: Unique (category, value, organization)

Wichtige Methoden: - can_be_deleted() -- Prüft alle umgekehrten FK-Beziehungen mit on_delete=PROTECT; gibt (bool, blocking_objects_list) zurück - delete() -- Überschrieben, um can_be_deleted() zuerst aufzurufen; löst ValidationError aus, wenn referenziert

Save-Hook: Generiert automatisch value-Slug aus label mit Eindeutigkeitsprüfung. Wenn is_default=True, wird das Standard-Flag von anderen Optionen in derselben Kategorie/Organisation entfernt.

Organisationsspezifische Auswahloptionen¶

Alle Optionen gehören zu einer bestimmten Organisation. Das Feld organization ist für Nicht-Staff-Benutzer erforderlich.

Bei der Abfrage von Optionen für ein Formular verwenden Sie die Hilfsfunktionen, die die Organisationsfilterung übernehmen:

from systemconfig.utils import populate_choice_field

# In der __init__-Methode eines Formulars:
populate_choice_field(
    self, 'feed_type', 'feed_type',
    organization=current_org
)

Views¶

OrganizationManagerOrStaffMixin¶

Berechtigungskontroll-Mixin, das Zugriff auf Staff, Org-Inhaber und Org-Admins beschränkt. Enthält user_can_edit_choice() für optionsbezogene Berechtigungsprüfungen.

CRUD-Views¶

View	Zweck
CategoryListView	Aktive Kategorien mit Optionszählung pro Organisation auflisten
ChoiceListView	Optionen für eine Kategorie mit Sortierung auflisten (SortableListMixin)
ChoiceCreateView	Neue Option erstellen mit Kategorie aus URL
ChoiceUpdateView	Option aktualisieren mit optionsbezogener Berechtigungsprüfung
ChoiceDeleteView	Option löschen; zeigt blockierende Objekte wenn referenziert
LoadDefaultCategoriesView	Nur POST; lädt Standardkategorien und -optionen

Formulare¶

ConfigurableChoiceForm¶

Felder: label, description, order, is_active, is_default, brood_chamber_weight_kg, honey_chamber_weight_kg, honeycomb_weight_kg, organization

Bedingte Felder: Zargengewicht-Felder (Brut, Honig, Wabe) werden ausgeblendet, wenn die Kategorie nicht hive_style ist.

Dynamisches Organisationsfeld:

Superuser: Erforderlich, können jede Organisation auswählen
Org-Inhaber/Admins (mehrere Orgs): Erforderliches Dropdown der verwalteten Organisationen
Org-Inhaber/Admins (einzelne Org): Versteckt, automatisch auf verwaltete Organisation gesetzt

Validierung: clean_organization() stellt sicher, dass der Benutzer die Inhaber/Admin-Rolle für die ausgewählte Organisation hat.

URL-Patterns¶

system/                                  -> CategoryListView (systemconfig-home)
system/load-defaults/                    -> LoadDefaultCategoriesView (systemconfig-load-defaults)
system/<slug:category_code>/             -> ChoiceListView (systemconfig-choice-list)
system/<slug:category_code>/new/         -> ChoiceCreateView (systemconfig-choice-create)
system/choice/<int:pk>/edit/             -> ChoiceUpdateView (systemconfig-choice-update)
system/choice/<int:pk>/delete/           -> ChoiceDeleteView (systemconfig-choice-delete)

Hilfsfunktionen¶

Das Modul utils.py bietet Hilfsfunktionen für Formulare und Views:

Funktion	Zweck
`get_queryset_for_category()`	QuerySet von Optionen für ModelChoiceField
`get_default_choice()`	Standardoption für eine Kategorie abrufen
`get_choice_value()`	Slug-Wert anhand des Primärschlüssels abrufen
`get_choice_by_value()`	Rückwärtssuche: Option nach Kategorie und Wert finden
`validate_choice_value()`	Prüfen, ob ein Wert in einer Kategorie existiert
`category_exists()`	Prüfen, ob eine aktive Kategorie existiert
`get_choices_for_category()`	Tupel-Liste für ChoiceField mit Warnungen bei leeren Kategorien
`populate_choice_field()`	Feld-Optionen setzen und Konfigurationslink zum Hilfetext hinzufügen
`get_config_link_help_text()`	HTML-Link zur Konfigurationsseite generieren
`add_config_link_help_text()`	Konfigurationslink an den Hilfetext eines Feldes anhängen

Verwendung in Formularen¶

from systemconfig.utils import populate_choice_field

class MyForm(forms.ModelForm):
    def __init__(self, *args, **kwargs):
        organization = kwargs.pop('organization', None)
        super().__init__(*args, **kwargs)

        # Feld mit Optionen befüllen und Konfigurationslink hinzufügen
        populate_choice_field(
            self, 'unit', 'unit_type',
            organization=organization,
            include_blank=True,
            blank_label=_('Select unit')
        )

Services¶

Bei der Benutzeranmeldung prüft das System alle aktiven Kategorien auf fehlende Konfiguration:

validate_system_categories_for_user(user) -- Prüft Organisationen, in denen der Benutzer Inhaber/Admin ist
Erstellt Systembenachrichtigungen für unkonfigurierte Kategorien
Verwendet 24-Stunden-Deduplizierung, um wiederholte Benachrichtigungen zu vermeiden

Signals¶

handle_user_logged_in¶

Auslöser: user_logged_in-Signal
Aktion: Ruft validate_system_categories_for_user() auf
Fehlerbehandlung: Alle Ausnahmen werden abgefangen und protokolliert; blockiert niemals die Anmeldung

Template-Tags¶

Zwei Template-Filter in templatetags/choice_filters.py:

Filter	Verwendung	Zweck
`get_choice_display`	`{{ value\\|get_choice_display:"category_code" }}`	Anzeigename für einen gespeicherten Wert nachschlagen
`translate`	`{{ category.name\\|translate }}`	Django-Übersetzung auf Datenbankstrings anwenden

Management-Befehle¶

load_default_categories¶

Standardkategorien und Beispieloptionen laden:

python manage.py load_default_categories

Delegiert an den Beispieldaten-Service. Kann sicher mehrfach ausgeführt werden (verwendet get_or_create).

Wann ConfigurableChoice verwenden¶

ConfigurableChoice verwenden wenn:

Optionen benutzerdefinierbar sein sollten
Organisationen unterschiedliche Optionen benötigen
Die Liste der Optionen im Laufe der Zeit wachsen kann
Keine Code-Logik von spezifischen Werten abhängt

Hardcodierte Auswahloptionen verwenden wenn:

Optionen fest sind (z.B. ja/nein, Statuswerte)
Code basierend auf Werten verzweigt
Nur 2-3 Optionen existieren
Performance kritisch ist (vermeidet zusätzliche Abfragen)

Siehe auch¶

Datenbankmodelle - SystemConfig
Administratorhandbuch - Systemkonfiguration
Hives-App-Referenz - Verwendet konfigurierbare Auswahloptionen für Bienenstocktypen