Search-App-Referenz¶
Die Search-App bietet eine einheitliche Suchoberfläche über alle Entitätstypen in der Bifolk-Anwendung. Sie verwendet ein Adapter-Muster, um Bienenstöcke, Königinnen, Honigchargen, Inventargegenstände, Zuchtaufzeichnungen und mehr über eine einzige Suchleiste zu durchsuchen.
Übersicht¶
Speicherort: app/search/
Zweck: Globale entitätsübergreifende Suche mit Live-Modal-Suche und erweiterter Filterung
Wichtige Modelle: Keine (verwendet Modelle anderer Apps über Suchadapter)
Abhängigkeiten: hives, breeding, warehouse, organizations
Dateistruktur¶
search/
├── apps.py # AppConfig
├── forms.py # GlobalSearchForm, AdvancedSearchForm
├── views.py # SearchResultsView, search_api
├── urls.py # 2 URL-Muster
├── services/
│ ├── __init__.py
│ ├── search_service.py # GlobalSearchService, PaginatedSearchResult
│ └── adapters/
│ ├── __init__.py # Re-Exports aller Adapter
│ ├── base.py # BaseSearchAdapter, SearchResult
│ ├── hive_adapters.py # 7 Adapter (Hive, Queen, HoneyBatch, HoneyBucket, HoneyJar, HiveInspection, HarvestRecord)
│ ├── warehouse_adapters.py # 3 Adapter (InventoryItem, ProductSale, WarehouseLocation)
│ └── breeding_adapters.py # 2 Adapter (QueenBreeding, ColonySplit)
├── templates/search/
│ ├── search_results.html # Ganzseitige Suchergebnisse mit Filtern
│ └── _search_modal.html # Globales Such-Modal (im Basis-Template eingebunden)
└── tests/
├── __init__.py
├── test_search_service.py # Service-Layer-Tests
├── test_adapters.py # Adapter-Tests
└── test_views.py # View-Tests
Views¶
SearchResultsView¶
Ganzseitige Suchergebnisansicht mit erweiterter Filterung.
- Speicherort:
app/search/views.py:16 - Typ: Klassenbasiert (TemplateView)
- Authentifizierung: Erforderlich (LoginRequiredMixin)
- Template:
search/search_results.html - URL:
/search/(Name:search:results)
Anzeigemodi:
| Modus | Bedingung | Verhalten |
|---|---|---|
| Gruppiert | Keine Filter aktiv | Ergebnisse nach Entitätstyp gruppiert, 20 pro Typ |
| Flach | Filter aktiv (Entitätstyp, Organisation, Datumsbereich) | Flache paginierte Liste, 20 pro Seite |
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
q |
String | Suchbegriff (mindestens 2 Zeichen) |
entity_types |
Liste | Zu filternde Entitätstypen |
organization |
Integer | Organisations-ID zum Filtern |
date_from |
Datum | Startdatum-Filter (ISO-Format) |
date_to |
Datum | Enddatum-Filter (ISO-Format) |
page |
Integer | Seitennummer für die flache Paginierung |
Die erweiterte Suchseite zeigt den Organisationsfilter immer an, unabhängig von der aktuellen seitenweiten Organisationsauswahl. Dies ermöglicht es Benutzern, über alle ihre Organisationen hinweg zu suchen.
search_api(request)¶
JSON-API-Endpunkt für Live-Suchergebnisse, verwendet vom Such-Modal.
- Speicherort:
app/search/views.py:153 - Typ: Funktionsbasierter View
- Authentifizierung: Erforderlich (@login_required)
- URL:
/search/api/(Name:search:api)
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
q |
String | Suchbegriff (mindestens 2 Zeichen) |
types |
String | Kommagetrennte Entitätstypen (optional) |
Antwortformat:
{
"results": {
"hive": [
{
"entity_type": "hive",
"entity_type_display": "Hive",
"id": 1,
"display_name": "Garden Hive",
"url": "/hives/1/",
"subtitle": "My Organization",
"context": "good",
"organization_name": "My Organization"
}
]
},
"total_count": 1,
"error": null
}
Formulare¶
GlobalSearchForm¶
- Speicherort:
app/search/forms.py:7 - Felder:
q(CharField, min_length=2, max_length=200) - Zweck: Einfache Sucheingabe im Such-Modal
AdvancedSearchForm¶
- Speicherort:
app/search/forms.py:24 - Zweck: Erweitertes Suchformular mit Filteroptionen
Felder:
| Feld | Typ | Beschreibung |
|---|---|---|
q |
CharField | Suchanfrage (min. 2, max. 200 Zeichen) |
entity_types |
MultipleChoiceField | Entitätstyp-Kontrollkästchen (dynamische Auswahl) |
organization |
ChoiceField | Organisations-Dropdown (dynamisch, ausgeblendet bei nur einer Organisation) |
date_from |
DateField | Startdatum-Filter |
date_to |
DateField | Enddatum-Filter |
Konstruktor-Parameter:
| Parameter | Zweck |
|---|---|
user |
Organisations-Auswahlmöglichkeiten aus Benutzermitgliedschaften befüllen |
current_organization |
Wenn gesetzt, wird das Organisationsfeld ausgeblendet |
entity_type_choices |
Liste von (Wert, Bezeichnung)-Tupeln für Entitätstypen |
Validierung: Stellt sicher, dass date_from vor date_to liegt, wenn beide angegeben sind.
Dienste¶
GlobalSearchService¶
Speicherort: app/search/services/search_service.py:41
Koordiniert die Suche über alle registrierten Suchadapter. Verwaltet 12 Adapter und aggregiert die Ergebnisse.
Konfiguration:
| Eigenschaft | Wert |
|---|---|
MIN_QUERY_LENGTH |
2 |
ADAPTERS |
12 registrierte Adapter (siehe Adapter-Register unten) |
Methoden:
| Methode | Zweck | Rückgabe |
|---|---|---|
search(search_term, user, ...) |
Suche gruppiert nach Entitätstyp | dict[str, list[SearchResult]] |
search_flat(search_term, user, ...) |
Suche als flache Liste | list[SearchResult] |
search_paginated(search_term, user, ..., page, per_page) |
Suche mit Paginierung | PaginatedSearchResult |
get_available_entity_types() |
Alle Entitätstypen mit Anzeigenamen auflisten | list[dict] |
get_entity_type_choices() |
Entitätstypen als Formular-Auswahl | list[tuple[str, str]] |
Alle Suchmethoden akzeptieren diese gemeinsamen Parameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
search_term |
str | Suchanfrage (mindestens 2 Zeichen) |
user |
User | Der anfragende Benutzer |
request |
HttpRequest (optional) | Für aktuellen Organisationskontext |
entity_types |
list[str] (optional) | Nach Entitätstypen filtern |
date_from |
date (optional) | Startdatum-Filter |
date_to |
date (optional) | Enddatum-Filter |
organization_id |
int (optional) | Nach bestimmter Organisation filtern |
PaginatedSearchResult¶
Speicherort: app/search/services/search_service.py:27
Dataclass für paginierte Suchergebnisse.
Felder:
| Feld | Typ | Beschreibung |
|---|---|---|
results |
list[SearchResult] | Ergebnisse der aktuellen Seite |
total_count |
int | Gesamtergebnisse über alle Seiten |
page |
int | Aktuelle Seitennummer |
per_page |
int | Ergebnisse pro Seite |
total_pages |
int | Gesamtanzahl der Seiten |
has_next |
bool | Ob eine nächste Seite existiert |
has_previous |
bool | Ob eine vorherige Seite existiert |
Suchadapter¶
Die Search-App verwendet ein Adapter-Muster, bei dem jeder Adapter für die Suche eines einzelnen Modelltyps verantwortlich ist und standardisierte SearchResult-Objekte zurückgibt.
BaseSearchAdapter¶
Speicherort: app/search/services/adapters/base.py:56
Abstrakte Basisklasse, die alle Suchadapter erweitern müssen.
Erforderliche Überschreibungen:
| Methode | Zweck |
|---|---|
get_model() |
Zu durchsuchende Modellklasse zurückgeben |
get_entity_type_display() |
Übersetzten Anzeigenamen zurückgeben |
get_search_q(search_term) |
Q-Objekt für Suchfilterung zurückgeben |
result_to_search_result(obj) |
Modellinstanz in SearchResult konvertieren |
Optionale Überschreibungen:
| Methode | Zweck |
|---|---|
get_base_queryset(user, request) |
Benutzerdefinierte Organisationsfilterung (Standard: select_related('organization') + filter_by_user_organizations) |
apply_organization_filter(queryset, organization_id) |
Benutzerdefinierter Organisationsfilter (Standard: organization_id=organization_id) |
apply_date_filter(queryset, date_from, date_to) |
Benutzerdefinierte Datumsfilterung (Standard: verwendet primary_date_field) |
Eigenschaften:
| Eigenschaft | Standard | Zweck |
|---|---|---|
entity_type |
'' |
Interner Bezeichner (z.B. 'hive') |
default_limit |
10 |
Maximale Ergebnisse pro Suche |
primary_date_field |
'created_at' |
Feld für Datumsbereichsfilterung |
SearchResult¶
Speicherort: app/search/services/adapters/base.py:18
Standardisierte Dataclass für Suchergebnisse.
Felder:
| Feld | Typ | Standard | Beschreibung |
|---|---|---|---|
entity_type |
str | (erforderlich) | Interner Typbezeichner |
entity_type_display |
str | (erforderlich) | Übersetzter Anzeigename |
id |
int | (erforderlich) | Primärschlüssel der gefundenen Entität |
display_name |
str | (erforderlich) | Hauptanzeigetext |
url |
str | (erforderlich) | URL zur Entitätsdetailansicht |
subtitle |
str | '' |
Sekundärer Text (Standort, Status) |
context |
str | '' |
Statusindikator (good, warning usw.) |
organization_name |
str | '' |
Organisationsname |
Adapter-Register¶
Alle 12 registrierten Adapter, nach Quell-App organisiert:
Bienenstock-Adapter (services/adapters/hive_adapters.py):
| Adapter | Entitätstyp | Standard-Limit | Datumsfeld | Durchsuchbare Felder |
|---|---|---|---|---|
HiveSearchAdapter |
hive |
10 | installation_date |
name, display_name, notes |
QueenSearchAdapter |
queen |
10 | created_at |
breed, identification_number, breeder_name, notes |
HoneyBatchSearchAdapter |
honey_batch |
5 | created_date |
charge_identifier, notes |
HoneyBucketSearchAdapter |
honey_bucket |
5 | created_at |
bucket_number, notes |
HoneyJarSearchAdapter |
honey_jar |
5 | created_at |
jar_number, notes |
HiveInspectionSearchAdapter |
hive_inspection |
5 | inspection_date |
notes, disease_notes, pest_notes |
HarvestRecordSearchAdapter |
harvest_record |
5 | harvest_date |
notes |
Lager-Adapter (services/adapters/warehouse_adapters.py):
| Adapter | Entitätstyp | Standard-Limit | Datumsfeld | Durchsuchbare Felder |
|---|---|---|---|---|
InventoryItemSearchAdapter |
inventory_item |
10 | created_at |
name, item_type, description |
ProductSaleSearchAdapter |
product_sale |
5 | sale_date |
customer_name, notes |
WarehouseLocationSearchAdapter |
warehouse_location |
5 | created_at |
name, description |
Zucht-Adapter (services/adapters/breeding_adapters.py):
| Adapter | Entitätstyp | Standard-Limit | Datumsfeld | Durchsuchbare Felder |
|---|---|---|---|---|
QueenBreedingSearchAdapter |
queen_breeding |
5 | breeding_date |
breed_line, notes, drone_source |
ColonySplitSearchAdapter |
colony_split |
5 | split_date |
notes |
Benutzerdefinierte Organisationsfilterung¶
Einige Adapter überschreiben get_base_queryset und apply_organization_filter, da ihre Modelle kein direktes organization-Feld haben:
| Adapter | Organisationspfad |
|---|---|
HoneyBucketSearchAdapter |
batch__organization |
HoneyJarSearchAdapter |
bucket__batch__organization |
HiveInspectionSearchAdapter |
hive__organization |
HarvestRecordSearchAdapter |
organization (direkt, mit Prefetch von Hives) |
Templates¶
search_results.html¶
Ganzseitiges Suchergebnis-Template. Beinhaltet:
- Sucheingabe mit Absende-Schaltfläche
- Einklappbares Filterpanel (Entitätstyp-Kontrollkästchen, Organisations-Dropdown, Datumsbereich)
- Alle auswählen / Alle abwählen-Schaltflächen für Entitätstyp-Kontrollkästchen
- Gruppierte Ergebnisansicht (Karten nach Entitätstyp mit Symbol pro Typ)
- Flache Ergebnisansicht mit Paginierung
- Status-Badges mit farbcodierten Kontexten (good/warning/critical)
- Leerzustand und Mindestzeichenlängen-Meldungen
_search_modal.html¶
Globales Such-Modal, das im Basis-Template eingebunden ist. Funktionen:
- Große Sucheingabe mit Tastaturhinweis (Esc zum Schließen)
- Lade-Spinner
- Leerzustand und Keine-Ergebnisse-Meldungen
- Dynamischer Ergebniscontainer (über JavaScript und die Such-API befüllt)
- Tastaturnavigationshinweise (Pfeiltasten, Enter)
- Link zur erweiterten Suchseite
URL-Konfiguration¶
| URL | View | Name |
|---|---|---|
/search/ |
SearchResultsView |
search:results |
/search/api/ |
search_api |
search:api |
Wichtige Funktionen¶
- Einheitliche Suche: Suche über 12 Entitätstypen mit einer einzigen Eingabe
- Adapter-Muster: Jeder Modelltyp hat seinen eigenen Adapter für angepasstes Suchverhalten
- Live-Such-Modal: Echtzeit-Suchergebnisse über JSON-API während der Eingabe
- Erweiterte Filterung: Filtern nach Entitätstyp, Organisation und Datumsbereich
- Zwei Anzeigemodi: Gruppiert nach Entitätstyp (ohne Filter) oder flache paginierte Liste (mit Filtern)
- Organisationsbewusst: Ergebnisse gefiltert nach den zugänglichen Organisationen des Benutzers
- Organisationsübergreifende Suche: Erweiterte Suche ignoriert die seitenweite Organisationsauswahl und durchsucht alle Organisationen des Benutzers
- Mindestabfragelänge: Erfordert mindestens 2 Zeichen, um zu breite Suchen zu vermeiden
- Tastaturnavigation: Modal unterstützt Pfeiltastennavigation und Enter zum Öffnen
Siehe auch¶
- Hives-App - Bienenstock-, Königinnen-, Chargen- und Durchsicht-Modelle, die von dieser App durchsucht werden
- Warehouse-App - Inventar-, Verkaufs- und Standort-Modelle, die von dieser App durchsucht werden
- Breeding-App - Königinnenzucht- und Ableger-Modelle, die von dieser App durchsucht werden
- Organizations-App - Organisationsfilterung, die von allen Adaptern verwendet wird