270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
# Konzeptdokument — CheckPoint Ehrenamt App
|
||
|
||
> Interne Orga-App für das Vor-Ort-Team Prävention der AIDS-Hilfe.
|
||
> Ersetzt schrittweise die WhatsApp/Signal-Zettelwirtschaft.
|
||
> Stand: Konzeptphase (vor dem ersten Code).
|
||
|
||
---
|
||
|
||
## 1 · Ziel & Kernidee
|
||
|
||
Eine schlanke, mobile-first Web-App, mit der das Ehrenamtsteam seine Einsätze
|
||
organisiert, ohne auf WhatsApp/Signal angewiesen zu sein.
|
||
|
||
**Das Herzstück ist die Terminabstimmung und Dienstverteilung** — wer macht wann
|
||
was. Alles andere (Chat, Dokumente) ordnet sich diesem Zweck unter.
|
||
|
||
**Leitprinzip:** Lesbarkeit und Orientierung vor Funktionsfülle. Die App muss für
|
||
17 Ehrenamtliche im Alltag spürbar einfacher sein als eine WhatsApp-Umfrage.
|
||
|
||
**Übergang:** Ziel ist, WhatsApp/Signal als Orga-Werkzeug komplett zu ersetzen.
|
||
In der Anfangszeit darf parallel weiter dort kommuniziert werden — die App muss
|
||
aber eigenständig funktionieren und darf wichtige Infos nicht „verlieren", nur
|
||
weil jemand noch nicht umgestiegen ist.
|
||
|
||
---
|
||
|
||
## 2 · Nutzer & Rollen
|
||
|
||
| Rolle | Wer | Rechte |
|
||
|---|---|---|
|
||
| **Admin** | Koordination (du) | Legt Planungszeiträume und Termine an, baut den Dienstplan, vergibt Logins, gibt Dokumente/Fotos frei, postet Ankündigungen, verwaltet das Team. |
|
||
| **Ehrenamtliche:r** | die 17 Teammitglieder | Meldet Verfügbarkeit, sieht den eigenen Dienstplan, übernimmt freie Dienste, lädt Dokumente/Fotos hoch (Freigabe nötig), chattet im Team-Kanal. |
|
||
|
||
Für v1 reichen genau diese zwei Rollen. Weitere Abstufungen (z. B. „Co-Admin")
|
||
sind möglich, aber nicht nötig — siehe Future Log.
|
||
|
||
---
|
||
|
||
## 3 · Mandantenfähigkeit (von Tag 1)
|
||
|
||
Die App wird **von Anfang an mandantenfähig** gebaut (Entscheidung A1): mehrere
|
||
Teams parallel, je eigenes Corporate Design und eigene, sauber getrennte Inhalte.
|
||
|
||
**Konsequenzen fürs Datenmodell:**
|
||
- Es gibt eine zentrale Einheit **`team`** (= Mandant).
|
||
- **Jeder** Datensatz (Nutzer, Termin, Dienst, Dokument, Nachricht, …) hängt an
|
||
genau einem `team`.
|
||
- Kein Datensatz ist über Teamgrenzen hinweg sichtbar.
|
||
- Das Corporate Design (Farben, Logo, Schrift) wird **pro Team** über
|
||
CSS-Variablen-Tokens gesetzt. Das bestehende CheckPoint-CD ist der erste Mandant.
|
||
|
||
Das CheckPoint-Team ist also der erste von perspektivisch mehreren Teams. Diese
|
||
Trennung wird im ersten Datenmodell verankert, damit später kein Umbau nötig ist.
|
||
|
||
---
|
||
|
||
## 4 · Technischer Rahmen (feste Vorgaben)
|
||
|
||
| Bereich | Entscheidung |
|
||
|---|---|
|
||
| Backend | **Flask** (Python) |
|
||
| Templating | **Jinja2**, server-gerendertes HTML |
|
||
| Architektur | klassische Multi-Page-App (server-rendered) |
|
||
| CSS | **selbst gebaut**, kein CSS-Framework (Basis: vorhandenes Token-System) |
|
||
| JavaScript | **so wenig wie möglich, nur Vanilla**, kein JS-Framework |
|
||
| Hosting | **eigener VPS in der EU** |
|
||
| Plattform | mobile-first Web-App, **kein App Store**, „zum Homescreen hinzufügen" möglich |
|
||
|
||
**Chat-Sonderfall (Variante 2):** Alles ist server-gerendert und JS-frei —
|
||
**außer** der Chat holt sich neue Nachrichten per kleinem `fetch`-Polling im
|
||
Hintergrund (wenige Zeilen Vanilla-JS). So fühlt sich der Chat lebendig an, ohne
|
||
WebSockets oder Framework. Polls, „Übernehmen", Formulare und die Terminübersicht
|
||
laufen komplett ohne JavaScript als normale Formular-Abschicke.
|
||
|
||
---
|
||
|
||
## 5 · Auth & Onboarding
|
||
|
||
- **Logins werden ausschließlich vom Admin vergeben.** Keine Selbstregistrierung.
|
||
- **v1:** Nutzername + Passwort, vom Admin angelegt.
|
||
- Passwörter werden gehasht gespeichert (nie im Klartext).
|
||
- Neue Ehrenamtliche bekommen ihre Zugangsdaten vom Admin und können sich danach
|
||
einloggen.
|
||
- **Future Log:** E-Mail + Einmal-Code (Magic Link) als komfortablere Alternative —
|
||
Entscheidung dazu trifft das Team später gemeinsam.
|
||
|
||
---
|
||
|
||
## 6 · Datenmodell — Entscheidungen
|
||
|
||
Konzeptionelle Sicht (keine Implementierungsdetails). Jede Einheit gehört zu
|
||
einem `team`.
|
||
|
||
- **team** — der Mandant. Trägt das Corporate Design (Tokens, Logo) und bündelt alle Inhalte.
|
||
- **user** — Ehrenamtliche:r oder Admin. Feld `rolle`, Login-Daten, Anzeigename, optionales **Profilbild** und optionale freiwillige Angaben.
|
||
- **planungszeitraum** — ein Block von mindestens 2 Monaten. Status: *in Planung* (Verfügbarkeit wird gesammelt) → *veröffentlicht* (Plan steht).
|
||
- **einsatz** (Termin/Dienst) — gehört zu einem Planungszeitraum. Hat Datum, Uhrzeit, Ort/Art (z. B. Tour Altstadt, Party, Sonderveranstaltung). Braucht **2 Hauptplätze + 1 Springerplatz**.
|
||
- **verfuegbarkeit** — Rückmeldung einer Person zu einem Einsatz: *kann / kann nicht*.
|
||
- **zuteilung** — verbindet `user` mit `einsatz` und einem Platztyp (*Haupt* oder *Springer*) und Status (*zugeteilt / abgesagt / übernommen*).
|
||
- **dokument** — Datei (Dokument oder Bild) mit Titel, Uploader, Status (*wartet auf Freigabe / freigegeben / abgelehnt*) und Ablage (*aktuell / Archiv*).
|
||
- **kanal** — Chat-Kanal (für v1 zwei feste pro Team: *Ankündigungen*, *Team*).
|
||
- **nachricht** — Textnachricht in einem Kanal, mit Autor und Zeitstempel.
|
||
|
||
---
|
||
|
||
## 7 · Kernflows
|
||
|
||
### 7.1 Planungszyklus (Admin)
|
||
|
||
1. Admin legt einen **Planungszeitraum** an (mind. 2 Monate).
|
||
2. Admin trägt die relevanten **Einsätze** ein: regelmäßige **Freitags-Touren**
|
||
(Alt-/Neustadt), **Samstags-Einsätze** (oft Partys) und kuratierte
|
||
**Sonderveranstaltungen**. Die Termine sind nicht fix vorgegeben — der Admin
|
||
wählt sie pro Zeitraum aus.
|
||
3. Der Zeitraum geht in den Status *in Planung* → Verfügbarkeitsabfrage startet.
|
||
|
||
### 7.2 Verfügbarkeit melden (Ehrenamtliche)
|
||
|
||
- Jede:r sieht die Liste der Einsätze des aktuellen Zeitraums und meldet pro Datum
|
||
**kann / kann nicht**.
|
||
- Änderung der Verfügbarkeit ist möglich, **solange der Zeitraum *in Planung* ist**.
|
||
Nach Veröffentlichung läuft alles über Absage/Übernahme (siehe 7.4).
|
||
|
||
### 7.3 Dienstplan bauen (Admin)
|
||
|
||
- Pro Einsatz: **2 Hauptpersonen + 1 Springer**.
|
||
- Der Admin verteilt **manuell** und sieht dabei pro Person Hilfsinfos: wie oft
|
||
schon eingeteilt, wann zuletzt im Einsatz — damit niemand zu oft hintereinander
|
||
dran ist und die Last fair bleibt.
|
||
- Wenn sich für einen Einsatz **zu wenige** verfügbar gemeldet haben, zeigt die App
|
||
ihn als **unterbesetzt** an, damit der Admin nachsteuern kann.
|
||
- Ist der Plan fertig, **veröffentlicht** der Admin den Zeitraum. Ab jetzt sehen
|
||
alle ihren persönlichen Dienstplan.
|
||
|
||
> **Bewusste Entscheidung für v1:** Die Zuteilung ist manuell (Admin entscheidet),
|
||
> die App unterstützt nur mit Anzeige. Automatische Fairness-Verteilung ist Future Log.
|
||
|
||
### 7.4 Absage & Übernahme
|
||
|
||
- Sagt eine **Hauptperson** ab, **rückt der Springer automatisch nach**. Der Einsatz
|
||
bleibt voll besetzt.
|
||
- Der dadurch frei werdende **Springerplatz** wird **offen zum „Übernehmen"** — wer
|
||
zuerst klickt, bekommt ihn.
|
||
- Sagt auch der Springer ab (oder es gibt keinen), wird der offene Platz für alle
|
||
zur Übernahme angeboten.
|
||
- Der Self-Service-„Übernehmen"-Button dient **ausschließlich dem Nachrücken** bei
|
||
Ausfall — nicht der Erstverteilung.
|
||
|
||
### 7.7 Profil
|
||
|
||
- Bewusst **minimal** in v1.
|
||
- Jede:r kann ein **Profilbild** hochladen und **freiwillig** ein paar Angaben zu
|
||
sich machen. Welche Felder das genau sind, wird noch festgelegt (siehe offene
|
||
Notiz unten) — nichts davon ist Pflicht.
|
||
- Login-/Passwort-Verwaltung kann hier später andocken.
|
||
|
||
### 7.5 Chat
|
||
|
||
- **Zwei feste Kanäle pro Team:**
|
||
- **Ankündigungen / Orga** — nur der **Admin** postet, alle lesen (z. B. Hinweis
|
||
auf neues Protokoll, wichtige Orga-Infos).
|
||
- **Team** — alle posten frei und reden untereinander.
|
||
- **Nur Text** (keine Bilder/Dateien im Chat — die laufen über die Dokumentenablage).
|
||
- Neue Nachrichten erscheinen per Hintergrund-Polling (Variante 2).
|
||
- **Future Log:** 1:1-Direktnachrichten.
|
||
|
||
### 7.6 Dokumente & Fotos
|
||
|
||
- **Inhalte:** Protokolle (PDF/Word) und **Bilder** (z. B. Tour-Fotos). Alles andere
|
||
bleibt bei WhatsApp.
|
||
- **Upload durch alle**, aber mit **Freigabe-Pflicht**:
|
||
1. User lädt hoch (mit kurzem Pflicht-Titel „was ist das") → Status *wartet auf Freigabe*, sichtbar nur für Admin und den Uploader.
|
||
2. Admin sieht eine **„Freigaben"-Ansicht** → **Freigeben** oder **Ablehnen** (optional kurzer Grund).
|
||
3. Erst nach Freigabe erscheint das Dokument in der allgemeinen Liste.
|
||
- **Admin-Uploads** gehen direkt durch (keine Selbst-Freigabe).
|
||
- **Ablage:** eine einfache Liste, geteilt in **Aktuell** und **Archiv**. Verschieben
|
||
ins Archiv macht der Admin manuell.
|
||
- **Inhaltsregel (Foto-Schutz):** Hochgeladene Fotos nur **ohne erkennbare Dritte**
|
||
bzw. nur mit deren Einverständnis. Der Freigabe-Schritt sichert das zusätzlich ab.
|
||
|
||
---
|
||
|
||
## 8 · Benachrichtigungen
|
||
|
||
- **v1: nur in-App** — z. B. „du hast einen neuen Dienst", „neuer offener Dienst",
|
||
„neue Nachricht". Dezent, nicht nervig.
|
||
- **Push und/oder E-Mail: Future Log.** Push ist ohne App Store eingeschränkt
|
||
(v. a. iPhone) und würde v1 überladen.
|
||
|
||
---
|
||
|
||
## 9 · Design & Corporate Design
|
||
|
||
- Mobile-first, App-Breite ca. 360–460px, viel Weißraum, klare Karten, runde
|
||
Aktionsflächen, Bottom-Navigation (**Start, Termine, Team, Profil**).
|
||
- Türkis als Hauptfarbe (Orientierung/Bestätigung), Rot sparsam (dringend,
|
||
Vertretung gesucht). Schrift: DM Sans.
|
||
- **Pro Team austauschbar** über CSS-Tokens — das CheckPoint-CD ist der erste
|
||
Mandant; weitere Teams bekommen ihre eigenen Tokens/Logos.
|
||
- Das vorhandene Mockup ist eine **erste Designidee**, keine verbindliche Vorlage.
|
||
Das finale Designsystem wird in Phase 1, Schritt 3 ausgearbeitet.
|
||
|
||
---
|
||
|
||
## 10 · Edge Cases & Regeln
|
||
|
||
- **Einsatz unterbesetzt:** zu wenige Verfügbare → sichtbarer *unterbesetzt*-Status für den Admin.
|
||
- **Springer fällt auch aus:** Platz wird für alle offen.
|
||
- **Verfügbarkeit nachträglich ändern:** nur solange *in Planung*; danach über Absage/Übernahme.
|
||
- **Memes/Unpassendes:** durch Freigabe-Pflicht abgefangen.
|
||
- **Übergangszeit:** App funktioniert eigenständig, auch wenn noch nicht alle umgestiegen sind.
|
||
|
||
---
|
||
|
||
## 11 · Datenschutz
|
||
|
||
- **Hosting auf eigenem VPS in der EU.**
|
||
- **Keine Klient:innendaten** in der App — es geht ausschließlich um die interne
|
||
Team-Orga.
|
||
- **Datensparsamkeit:** nur, was für die Orga nötig ist (Name, Login, Verfügbarkeit,
|
||
Zuteilung).
|
||
- Passwörter gehasht. Inhalte streng pro Team getrennt.
|
||
- Foto-Inhaltsregel (siehe 7.6) wegen des sensiblen AIDS-Hilfe-Kontexts.
|
||
|
||
> Hinweis: Für den realen Betrieb empfiehlt sich später eine knappe
|
||
> Datenschutzerklärung / ein Verarbeitungsverzeichnis in Abstimmung mit der
|
||
> AIDS-Hilfe. Das ist kein Entwicklungsthema, aber fürs Konzept vermerkt.
|
||
|
||
---
|
||
|
||
## 12 · Bewusst raus aus v1 (Out of Scope)
|
||
|
||
- Keine öffentlichen Seiten (rein internes Tool).
|
||
- Keine Klient:innendaten.
|
||
- Keine Bezahlfunktion.
|
||
- Kein Kalender-Sync (die Terminübersicht ist eine Liste, kein Kalender).
|
||
- Keine Bilder/Dateien im Chat.
|
||
- Keine automatische Dienstverteilung.
|
||
|
||
---
|
||
|
||
## 13 · Future Log (spätere Versionen)
|
||
|
||
- **1:1-Direktnachrichten** im Chat.
|
||
- **Push-Benachrichtigungen** und/oder **E-Mail-Benachrichtigungen**.
|
||
- **E-Mail + Einmal-Code (Magic Link)** als Login-Alternative.
|
||
- **Automatische Fairness-Verteilung** der Dienste (Vorschläge statt nur Anzeige).
|
||
- Weitere Rollen (z. B. Co-Admin).
|
||
- Laptop-Spiegelung des Setups / Desktop-Fallback über LAN (Entwicklungsumgebung).
|
||
|
||
---
|
||
|
||
## 14 · Geklärte Restpunkte
|
||
|
||
Alle zuvor offenen Punkte sind entschieden:
|
||
|
||
1. **Bottom-Nav:** zweiter Punkt heißt **„Termine"** (Liste der Einsätze), nicht „Kalender". ✔
|
||
2. **Fairness-Anzeige:** App zeigt pro Person *Anzahl Einsätze* und *letzter Einsatz*; Verteilung bleibt manuell. ✔
|
||
3. **Dokument-Dateitypen:** PDF, Word und Bilder (JPG/PNG) — ausreichend. ✔
|
||
4. **Profil:** minimal in v1 — Profilbild + optionale freiwillige Angaben (siehe 7.7). ✔
|
||
|
||
**Eine verbleibende Notiz (kein Blocker):** Welche freiwilligen Profil-Felder genau
|
||
angeboten werden, überlegst du dir noch. Lässt sich jederzeit ergänzen, ohne das
|
||
Konzept zu verändern.
|
||
|
||
---
|
||
|
||
**Damit ist das Konzept fix.** Nächste Schritte: **Schritt 3 (Designsystem)** und
|
||
danach **Schritt 4 (die drei Projektdateien: CLAUDE.md, TASKS.md,
|
||
Stakeholder-Dokument)**. Erst danach öffnest du VS Code.
|