From 2c98874fc8b4def6094262421b90c6d188f0bea4 Mon Sep 17 00:00:00 2001 From: patrick Date: Tue, 8 Sep 2026 10:47:30 +0200 Subject: [PATCH] docs: README.md angelegt (Funktionsumfang, Techstack, lokale Entwicklung) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FOUND-012 (Dokumentationsgerüst) war laut Backlog-Abgleich offen - kein README im Projektwurzelverzeichnis. Fasst zusammen, was MABEA kann (Digitale Akte, Kontrolle, Fehlbestandsmanagement, Warehouse, Wartung, Dokumente, Suche, Dashboard, PWA/Offline, ...), Techstack und wie man Backend/Frontend lokal startet. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01CVgbozhYmuEhiEJHffRXCV --- README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..27f9f5f --- /dev/null +++ b/README.md @@ -0,0 +1,67 @@ +# MABEA — Digitales Materialmanagement Rettungsdienst/KatS + +Ersetzt papierbasierte Materiallisten (Excel-Rucksacklisten) im Rettungsdienst/Katastrophenschutz durch eine digitale Soll/Ist-Kontrolle mit Rollen, Historie und Eskalation. Fachlich vor Technik entstanden — Konzeptphase in `ergebnisse/`, laufender Fortschritt gegen echten Code-Stand in `arbeitskacheln/00_index.md`. + +## Funktionsumfang + +- **Digitale Akte** je Objekt (Rucksack, Fahrzeug, Gerät, Anhänger) — aggregiert Beladung, Kontrollen, Mängel, Dokumente, Wartung, Historie an einer Stelle +- **Soll/Ist-Kontrolle** mit Beladungsvorlagen, individuellen Abweichungen, Fach-Zuordnung, QR-/Barcode-Scan zum Objekt- und Positions-Lookup +- **Fehlbestandsmanagement**: Entstehung, Nachfüllung (auch sofort während der Kontrolle), Mindermengen-Genehmigung mit Historie +- **Zentrale Einsatzbereitschafts-Engine** — begründete Ampel (bereit/eingeschränkt/unbekannt/nicht bereit) aus Fehlbeständen, Mängeln, Prüf-/Wartungsfristen, Fahrzeug-HU/UVV +- **Mängel-Ticketsystem** mit Priorität und Status +- **Wartung**: Wartungspläne, Intervalle, Wartungsaufträge je Objekttyp +- **Warehouse**: Lagerort-Hierarchie, Lagerplätze, Bestand, Materialbewegungen +- **Beladungsplanung** per Klick-Zuordnung (kein Drag&Drop — touch-tauglich) +- **Personal & Qualifikationen**: Einheiten-Hierarchie, Qualifikationstypen/-nachweise, "wer darf dieses Fahrzeug fahren" +- **Ausgabe/Rückgabe** personenbezogener Materialien/Leihgeräte +- **Dokumentenverwaltung**: Upload mit fester Kategorie (Prüfprotokoll/Wartungsbericht/Bedienungsanleitung/Rechnung/Zulassungsdokument), SHA-256-Duplikat-Erkennung, Online-Ansicht im Browser, typbasierte Zugriffsrechte (Rechnungen nur für Verantwortliche) +- **Globale Suche** (Strg/⌘+K) über Objektnamen/-codes und geführte Materialien, per PostgreSQL-Trigram-Index +- **Benachrichtigung & Eskalation** bei lange offenen Fehlbeständen +- **Zuständigkeiten** flexibel Standorten/Objekten zuweisbar (kein starres zentral/dezentral) +- **Verantwortlichen-Dashboard** — frei anordenbares und größenveränderbares Kachel-Raster, Status-Monitor-Modus für Wandbildschirme +- **PWA mit Offline-Queue** — Kontroll-Eingaben werden bei fehlender Verbindung lokal gepuffert und automatisch nachgereicht +- **Granulares Rechte-System** zusätzlich zu den vier Basisrollen (Mitarbeiter/Materialverantwortlicher/Leitungsverantwortlicher/Administration) +- **Dark Mode**, Command Palette, zentrale Statuskomponenten + +Vollständiger, gegen den Code abgeglichener Stand je Einzelfunktion: [`arbeitskacheln/00_index.md`](arbeitskacheln/00_index.md). Nutzer-Anleitung: [`docs/BENUTZERHANDBUCH.md`](docs/BENUTZERHANDBUCH.md). + +## Techstack + +- **Backend**: Python/FastAPI, SQLAlchemy (async), Alembic-Migrationen, PostgreSQL, JWT-Auth, `slowapi` Rate-Limiting +- **Frontend**: React 18 + Vite + TypeScript, PWA (`vite-plugin-pwa`), Tailwind CSS v4, handgebaute shadcn/ui-artige Primitives, `react-grid-layout` fürs Dashboard +- **Tests**: pytest (Backend, gegen echte Postgres-Testdatenbank) + Vitest/Testing Library (Frontend-Unit-Tests) + Playwright (Frontend-E2E, aktuell nicht in CI) +- **Hosting**: eigener Linux-Server, nginx + systemd, kein Docker-Zwang + +## Projektstruktur + +``` +backend/ FastAPI-App (app/api/v1/endpoints, app/models, app/services, app/schemas) +backend/alembic/ Migrationen, fortlaufend nummeriert +backend/tests/ pytest-Suite +frontend/ React-PWA (src/pages, src/components, src/styles/global/*) +frontend/e2e/ Playwright-Tests (gemockte API) +arbeitskacheln/ Backlog (Epics/Kacheln, Status-Spalte = Code-Abgleich) +ergebnisse/ Fachkonzept-Ergebnisse aus der Klärungsphase +docs/ Nutzer-Doku +``` + +## Entwicklung + +Backend: +```bash +cd backend +python3 -m venv .venv && .venv/bin/pip install -e ".[dev]" +.venv/bin/alembic upgrade head +.venv/bin/uvicorn app.main:app --reload +``` + +Frontend: +```bash +cd frontend +npm install +npm run dev # Dev-Server +npm run test # Vitest Unit-Tests +npm run build # Typecheck + Produktions-Build +``` + +Beide Teile brauchen eine lokale `.env`/PostgreSQL-Instanz — siehe `backend/example.env`.