Initial commit: Arbeitsorte-Logger + data-safety/robustness/input work

Existing app (single-file Tkinter/ttkbootstrap desktop tool for logging
blood-drive work assignments and mapping them) plus the first round of
improvements:

- Data safety: atomic CSV writes (tmp + fsync + os.replace), rotating
  backups in data/backups/ (startup + before every change, keep 20),
  fallback to empty/backup on missing/empty/corrupt orte.csv.
- Geocoder robustness: per-item try/except so the worker thread survives
  failures; GeocodingUnavailable + one-time "service unreachable" dialog.
- Input: DateEntry calendar picker with parse_date() validation; manual
  lat/lon fields in the edit dialog; Tab 2 highlights/filters rows without
  coordinates and adds a right-click "Koordinaten suchen".
- Logging to data/app.log; shared autocomplete helpers; config constants;
  map fit_bounds.

docs/ describes current state, architecture, data model, setup (Linux Mint),
and the full improvement roadmap. data/orte.csv is gitignored for now.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-07 18:28:28 +02:00
commit 37c9642877
11 changed files with 1809 additions and 0 deletions
+34
View File
@@ -0,0 +1,34 @@
# DRK Blutspende Arbeitsorte: Dokumentation
Developer/maintainer documentation for the **Arbeitsorte-Logger**, a small
desktop app that records blood-drive work assignments (date + city + postal
code) and plots them on an interactive map.
> Context: built as a personal tool for a single user, running locally on a
> **Linux Mint laptop**. Ease of use for a non-technical user is the primary
> design constraint. There is no server, no multi-user story, and no network
> dependency beyond geocoding and the map tiles.
## Documents
| File | Contents |
|------|----------|
| [overview.md](overview.md) | What the app does, feature by feature |
| [architecture.md](architecture.md) | Code structure, threading model, data flow |
| [data-model.md](data-model.md) | The `orte.csv` schema and how it is read/written |
| [setup.md](setup.md) | Install & run on a fresh Linux Mint machine, plus a desktop launcher |
| [improvements.md](improvements.md) | Prioritized review findings and suggested changes |
| [changelog.md](changelog.md) | What has changed, newest first |
| [dev-notes.md](dev-notes.md) | Assumptions that turned out wrong — read before editing |
## At a glance
- **Language / stack:** Python 3, Tkinter via [`ttkbootstrap`](https://ttkbootstrap.readthedocs.io/)
- **Single file:** [`app.py`](../app.py) (~760 lines)
- **Storage:** one CSV file, `data/orte.csv`
- **Map:** generated on demand as `data/karte.html` with [Folium](https://python-visualization.github.io/folium/) (Leaflet), opened in the default browser
- **Geocoding:** OpenStreetMap Nominatim via [`geopy`](https://geopy.readthedocs.io/), rate-limited to 1 request/second on a background thread
- **UI language:** German
- **Persistence:** atomic CSV writes + rotating backups in `data/backups/`; log at `data/app.log`
- **Tests:** non-GUI smoke checks only (not yet a committed `tests/` suite)
- **Version control:** git initialized 2026-09-07