drk-blutspende-orte/docs/overview.md

Overview – what the app does

The app is a single window: a DRK-red header bar, two tabs, and a colour-coded status bar at the bottom (grey = neutral, green = success, orange = warning, red = error; transient messages fade back to neutral after ~8 s). The window title shows the total entry count, and the window remembers its size and position between sessions (data/window.json). The UI font is enlarged for readability (UI_FONT_SIZE).

Tab 1 – "Neuer Eintrag" (new entry)

Workflow: build up a queue of entries, let them geocode in the background, then save the whole batch at once.

1. Entry form – date (a calendar picker, ttkbootstrap.DateEntry, pre-filled with today; typed input is accepted in JJJJ-MM-TT or TT.MM.JJJJ and validated – an invalid date is rejected with a dialog), city (autocomplete combobox), postal code (optional). Pressing Return in any field, or the + Hinzufügen button, adds the row to the queue. The PLZ field only accepts digits.
2. Queue table – shows date, city, PLZ, and a live coordinate column that updates from ⏳ wird gesucht… to either lat / lon or ⚠ nicht gefunden as the background geocoder works through the queue.
   • Select a row and press Delete, use the "Auswahl entfernen" button, or click the ✕ cell.
   • Right-click a row for Löschen / Koordinaten erneut suchen.
3. Action bar
   • Alle speichern – appends every queued row to orte.csv. If any row looks like a duplicate (same date + city + PLZ), a modal lists them and asks whether to save anyway.
   • Warteschlange leeren – discards the queue (asks for confirmation).
   • Karte öffnen – regenerates karte.html and opens it in the browser.

Tab 2 – "Einträge verwalten" (manage entries)

A table view of everything in orte.csv.

• Columns: Datum, Ort, PLZ, and Karte – a status column showing ✓ when the row has coordinates or a red fehlt when it doesn't (the whole row is red too). The raw lat/lon numbers live in the edit dialog, not this table.
• Search box – live filter across date, city, and PLZ (substring match).
• Sortable columns – click a header to sort; clicking again reverses. The active column shows a ▲/▼ arrow. Default sort is by date, newest first. Sorting by Karte groups the rows without coordinates together.
• "Nur ohne Koordinaten" toggle – filters to entries that have no coordinates yet. The hint line always shows the total count, plus how many are missing coordinates.
• Edit – double-click a row (or Bearbeiten) opens a modal dialog to change date (calendar picker, validated) / city / PLZ. Two ways to fix coordinates: a "Koordinaten automatisch neu suchen" toggle re-runs geocoding after saving, or the Breitengrad / Längengrad fields let you type them in by hand (both empty = no map marker).
• Right-click → Koordinaten suchen – runs geocoding for that one row (handy for rows that failed the first time).
• Delete – Löschen removes the selected row(s) after a confirmation dialog. This is irreversible, but a timestamped copy of the file is written to data/backups/ before every change (see data-model.md).
• Karte öffnen – same as on Tab 1.

The map (karte.html)

Generated by generate_map():

• Base layer: OpenStreetMap standard tiles (MAP_TILES) – no API key. Initial view centred on [49.0, 9.0], zoom 8 (roughly Baden-Württemberg); the view auto-fits to the markers when there is more than one.
• One CircleMarker per unique (city, lat, lon) group. Radius scales linearly with the visit count for that location (5 + count / max_count * 20 px), colour is DRK red (#CC0000).
• Popup shows the city and the visit count; tooltip shows the city.
• Rows with missing/blank coordinates are silently excluded.
• If there are no usable coordinates at all, a dialog says so (and the status bar shows a warning).

The generated HTML pulls Leaflet, jQuery and Bootstrap from CDNs, and the map tiles from tile.openstreetmap.org, so the map needs an internet connection to render even though the data is local. To change the look, set MAP_TILES near the top of app.py to another no-key provider Folium knows ("OpenStreetMap", "CartoDB positron" now needs a key, or a custom folium.TileLayer URL such as OSM Germany / OSM France).

Geocoding behaviour

geocode_city(city, postal_code) tries a series of queries in order and returns the first hit:

1. "<PLZ> <city>, Germany" (only if a PLZ was given)
2. "<city>, Baden-Württemberg, Germany"
3. "<city>, Hessen, Germany"
4. "<city>, Germany"

The regional bias is the GEOCODE_REGIONS constant (Baden-Württemberg, Hessen) near the top of app.py. Results are rounded to five decimal places. Nominatim's usage policy (max 1 req/s, identifying user_agent) is respected by a manual time.sleep(1) in the worker loop.

If the geocoding service is unreachable (no internet), entries still save – without coordinates – and after a few consecutive failures a one-time dialog explains that the coordinates can be added later via Bearbeiten. The worker thread logs failures to data/app.log and keeps running.