From a732a5afc4c77063945595368a1f9f225a510247 Mon Sep 17 00:00:00 2001 From: stephan Date: Thu, 15 Jan 2026 09:09:59 +0100 Subject: [PATCH] docs: add consumer audience split and external deps --- CHANGELOG.md | 5 +++ README.md | 40 +++++++++++-------- docs/ARCHITECTURE.md | 20 ++++++++++ docs/CONFIGURATION.md | 31 ++++++++++++++ docs/DEPLOYMENT.md | 30 ++++++++++++++ docs/DEVELOPMENT.md | 29 ++++++++++++++ docs/FAQ.md | 5 +++ docs/FOR_USERS.md | 37 +++++++++++++++++ docs/GETTING_STARTED.md | 11 +++++ docs/TROUBLESHOOTING.md | 5 +++ docs/USAGE.md | 14 +++++++ project-management/PROJECT_STATUS.md | 7 ++++ .../requirements/epics/EPIC_000012.md | 2 + .../requirements/stories/US_000041.md | 16 ++++++++ .../requirements/stories/US_000042.md | 19 +++++++++ .../requirements/tasks/TASK_000045.md | 19 +++++++++ .../requirements/tasks/TASK_000046.md | 17 ++++++++ .../requirements/tasks/TASK_000047.md | 18 +++++++++ .../requirements/tasks/TASK_000048.md | 18 +++++++++ 19 files changed, 327 insertions(+), 16 deletions(-) create mode 100644 docs/FOR_USERS.md create mode 100644 project-management/requirements/stories/US_000041.md create mode 100644 project-management/requirements/stories/US_000042.md create mode 100644 project-management/requirements/tasks/TASK_000045.md create mode 100644 project-management/requirements/tasks/TASK_000046.md create mode 100644 project-management/requirements/tasks/TASK_000047.md create mode 100644 project-management/requirements/tasks/TASK_000048.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e75ba48..c74a644 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,11 @@ By: Codex (GPT-5) | 15.01.2026 | 📝 Req | ID: US_000039 Doku-Audit abgeschlossen (Header-Versionen konsolidiert, Update-Docs korrigiert). By: Codex (GPT-5) | | 15.01.2026 | 🏗️ Planning | ID: EPIC_000012 und US_000040 sowie TASK_000043-TASK_000044 fuer Doku-Overhaul angelegt. By: Codex (GPT-5) | | 15.01.2026 | 📝 Req | ID: US_000040 Doku-Overhaul umgesetzt (neue Struktur, README, Archivierung). By: Codex (GPT-5) | +| 15.01.2026 | 📝 Req | ID: Externe Service-Links (Update/OIDC) in Doku ergaenzt. By: Codex (GPT-5) | +| 15.01.2026 | 🏗️ Planning | ID: US_000041/TASK_000045 Einbindung externer Services dokumentieren. By: Codex (GPT-5) | +| 15.01.2026 | 📝 Req | ID: US_000041 Einbindungsschritte fuer Update- und OIDC-Service dokumentiert. By: Codex (GPT-5) | +| 15.01.2026 | 🏗️ Planning | ID: US_000042/TASK_000046-TASK_000048 Consumer-Doku und Audience-Split ergaenzen. By: Codex (GPT-5) | +| 15.01.2026 | 📝 Req | ID: US_000042 Consumer-Doku, Audience-Split, External Dependencies und Power-User-Ergaenzungen umgesetzt. By: Codex (GPT-5) | --- ## Legende diff --git a/README.md b/README.md index 26df92a..30cd245 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,16 @@ By: Codex (GPT-5) ## Kurzbeschreibung Safe Kiddo Daemon ist ein lokaler Systemdienst, der Benutzerkonten auf Linux-Systemen sperrt/entsperrt, Sitzungen beendet und optional einen Shutdown ausloest. Der Dienst bietet eine REST-API und eine Web-UI fuer die Fernsteuerung. Ein Legacy-CLI-Script (`sk.sh`) bleibt als Fallback erhalten. -## Zielgruppe -- Einsteiger: moechten den Dienst schnell installieren und erste Aktionen ausfuehren. -- Admins/Operatoren: konfigurieren Auth, OIDC und Update-Mechanik. -- Entwickler: verstehen Architektur, Module und Erweiterungspunkte. +## Fuer wen ist das Projekt? +1. Endnutzer (Consumers): Nutzen die Web-Oberflaeche ohne technische Details. +2. Technische Einsteiger: Installieren und starten den Dienst. +3. Power-User: Konfigurieren, automatisieren und betreiben den Dienst. +4. Entwickler/Professionals: Verstehen Architektur, Interna und Erweiterungspunkte. + +## Was es NICHT ist +- Kein Cloud-Service und keine zentrale Benutzerverwaltung. +- Kein Ersatz fuer Mobile-Device-Management (MDM). +- Kein plattformuebergreifendes Kontrollen-System; Fokus ist Linux und lokale Accounts. ## Hauptfunktionen - Sperren/Entsperren lokaler Nutzerkonten inkl. Session-Management und optionalem Shutdown. @@ -19,9 +25,6 @@ Safe Kiddo Daemon ist ein lokaler Systemdienst, der Benutzerkonten auf Linux-Sys - Update-Client-Integration (Enrollment, Manifest, Apply, Rollback, Logs). - Dry-Run-Modus zum sicheren Testen. -## Badges -Derzeit keine offiziellen Badges, da im Repository keine CI, Coverage, Release oder Docker-Pipeline definiert ist. - ## Quickstart (5 Minuten) ```bash # 1) Repo holen @@ -43,15 +46,20 @@ curl -s -X POST -H "Content-Type: application/json" \ ``` Danach die Web-UI unter `http://localhost/` oeffnen und anmelden. -## Dokumentation -- Einstieg und erster Lauf: `docs/GETTING_STARTED.md` -- Nutzung (API, Web-UI, CLI): `docs/USAGE.md` -- Konfiguration (ENV-Variablen): `docs/CONFIGURATION.md` -- Architektur und Module: `docs/ARCHITECTURE.md` -- Entwicklung: `docs/DEVELOPMENT.md` -- Deployment & Betrieb: `docs/DEPLOYMENT.md` -- FAQ: `docs/FAQ.md` -- Troubleshooting: `docs/TROUBLESHOOTING.md` +## Dokumentation nach Zielgruppe +- Endnutzer (Consumers): `docs/FOR_USERS.md` +- Technische Einsteiger: `docs/GETTING_STARTED.md` +- Power-User: `docs/USAGE.md` und `docs/CONFIGURATION.md` +- Entwickler/Professionals: `docs/ARCHITECTURE.md`, `docs/DEVELOPMENT.md`, `docs/DEPLOYMENT.md` +- Gemeinsame Referenz: `docs/FAQ.md`, `docs/TROUBLESHOOTING.md` + +## Externe Services +- Update-Service (intern): https://git.wlkns.org/stephan/update-webservice +- OIDC-Service (intern): https://git.wlkns.org/stephan/oicd +Einbindung und Konfiguration: `docs/DEPLOYMENT.md` und `docs/CONFIGURATION.md`. + +## Badges +Derzeit keine offiziellen Badges, da im Repository keine CI, Coverage, Release oder Docker-Pipeline definiert ist. ## Hinweise - Abweichung von der Zielstruktur: Die OpenAPI-Spezifikation des Update-Services bleibt unter `docs/architecture/openapi.yaml` und `docs/architecture/openapi/` erhalten. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0ea974f..cea6bbc 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -10,6 +10,22 @@ Safe Kiddo Daemon ist ein FastAPI-basierter Service, der lokale Systemkonten ver - Systemaktionen via sudo/usermod/pkill/shutdown - Update-Client-Integration (externes Update-Service-Backend) +## Externe Abhaengigkeiten +- Update-Service (intern): https://git.wlkns.org/stephan/update-webservice +- OIDC-Service (intern): https://git.wlkns.org/stephan/oicd + +## Integrationspunkte +### Update-Service +Die Update-Integration nutzt v1-Endpunkte des Update-Services: +- `POST /v1/enroll` (Enrollment fuer Langzeit-Token) +- `GET /v1/projects/{project_id}/manifest` +- `POST /v1/projects/{project_id}/status` +Der Langzeit-Token wird lokal in `SKD_UPDATE_TOKEN_FILE` gespeichert und fuer Manifest/Status als Bearer-Token verwendet. + +### OIDC-Service +OIDC nutzt Discovery unter `/.well-known/openid-configuration` basierend auf `SKD_OIDC_ISSUER`. +Der Login-Flow tauscht einen Code gegen ein ID-Token (RS256) und validiert es gegen JWKS. + ## Module und Verantwortlichkeiten - `backend/app.py`: API-Routing, Web-UI-Endpunkte, Update-Endpunkte. - `backend/auth.py`: PAM-Login, JWT-Handling, Auth-Guards, Allowlists. @@ -57,3 +73,7 @@ Safe Kiddo Daemon ist ein FastAPI-basierter Service, der lokale Systemkonten ver ## Spezifikationen - Update-Service OpenAPI: `docs/architecture/openapi.yaml` und `docs/architecture/openapi/`. + +## Weitere Dokumente +- Entwicklung: `docs/DEVELOPMENT.md` +- Deployment: `docs/DEPLOYMENT.md` diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index e6b17ab..7d6ccbf 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -23,6 +23,26 @@ OIDC ist optional und zusaetzlich zu PAM. - `SKD_OIDC_SCOPES` (default `openid profile email`) - `SKD_SESSION_COOKIE_SECURE` (default `false`): Setze `true` fuer HTTPS. - `SKD_OIDC_STATE_COOKIE_NAME` (default `skd_oidc_state`) +Referenz: OIDC-Service (intern) https://git.wlkns.org/stephan/oicd + +### OIDC-Einbindung (Kurz) +1. Issuer setzen (muss der externen URL des IdP entsprechen): + - `SKD_OIDC_ISSUER=https://auth.example.org` +2. Client registrieren (DCR), falls der IdP es erlaubt: +```bash +export SKD_OIDC_ISSUER="https://auth.example.org" +export SKD_OIDC_REDIRECT_URI="https://kiddo.example.org/login/oidc/callback" +export OIDC_INITIAL_ACCESS_TOKEN="example-token" +./scripts/register_oidc_client.sh +``` +3. Client-Credentials in `/etc/skd/env` setzen: +``` +SKD_OIDC_CLIENT_ID=example-client-id +SKD_OIDC_CLIENT_SECRET=example-client-secret +SKD_OIDC_REDIRECT_URI=https://kiddo.example.org/login/oidc/callback +SKD_SESSION_COOKIE_SECURE=true +``` +Hinweis: OIDC ist aktiv, sobald Issuer, Client-ID und Secret gesetzt sind. ## Session/Benutzerverwaltung - `SKD_SESSION_COOKIE_NAME` (default `skd_session`) @@ -49,6 +69,17 @@ OIDC ist optional und zusaetzlich zu PAM. ## Dry-Run - `SKD_DRY_RUN` (default `false`): Keine echten System-Aktionen, nur Logging. +## Tuning und Betrieb (Power-User) +- `SKD_TOKEN_TTL_SECONDS`: kuerzere Tokens reduzieren Risiko, laengere Tokens reduzieren Login-Haeufigkeit. +- `SKD_DEFAULT_COUNTDOWN`: steuert Nutzerwarnung vor Sperre/Shutdown. +- `SKD_NOTIFY_TIMEOUT`: Dauer der Desktop-Benachrichtigung. +- `SKD_SESSION_COOKIE_SECURE=true`: zwingend bei HTTPS, sonst Login-Cookies unsicher. + ## Hinweise - `scripts/install.sh` erstellt `/etc/skd/env` und setzt Default-Werte fuer PAM/Allowed-User. - Aenderungen in `/etc/skd/env` erfordern einen Service-Restart (`sudo systemctl restart skd.service`). + +## Weitere Dokumente +- Nutzung/Automation: `docs/USAGE.md` +- Deployment: `docs/DEPLOYMENT.md` +- Architektur: `docs/ARCHITECTURE.md` diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index c2d189b..afef550 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -54,6 +54,31 @@ Wichtige ENV-Variablen: - `SKD_UPDATE_TOKEN` oder `SKD_UPDATE_TOKEN_FILE` Voraussetzungen auf dem Host: - `curl`, `tar`, `sha256sum`, `python3`, `systemctl` +Referenz: Update-Service (intern) https://git.wlkns.org/stephan/update-webservice + +### Update-Service einbinden +1. Service-URL und Projekt setzen: +``` +SKD_UPDATE_SERVICE_URL=https://update.wlkns.org +SKD_UPDATE_PROJECT_ID=safe-kiddo-control +``` +2. Enrollment-Token besorgen (vom Update-Service-Admin) und einen Langzeit-Token erzeugen: + - Option A: Ueber lokale API +```bash +curl -X POST -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"enroll_token\":\"example-enroll-token\"}" \ + http://localhost/update/enroll +``` + - Option B: Direkter Enrollment-Client +```bash +./scripts/manual_enroll.py --url "https://update.wlkns.org" --project "safe-kiddo-control" --token "example-enroll-token" +``` +3. Token-Datei pruefen: +``` +sudo cat /var/lib/skd/update_token +``` +Hinweis: Der Update-Check ist erst moeglich, wenn der Langzeit-Token gespeichert wurde. Enrollment-Tools: - `scripts/manual_enroll.py`: Enrollment direkt gegen den Update-Service, schreibt Token in `SKD_UPDATE_TOKEN_FILE`. @@ -66,3 +91,8 @@ Lokale Status/Logs: ## Backup/Restore - Bei Apply wird `/opt/sk` nach `/opt/sk_backup_1.2.3_1700000000` verschoben (Beispiel). - Rollback nutzt das letzte Backup (`/opt/sk_backup_*`). + +## Weitere Dokumente +- Konfiguration: `docs/CONFIGURATION.md` +- Nutzung: `docs/USAGE.md` +- Troubleshooting: `docs/TROUBLESHOOTING.md` diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index e5f2792..13a416b 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -42,3 +42,32 @@ Aktuell keine CI/CD-Pipeline im Repository definiert. ## Legacy/Interna - `SKD_UPDATE_URL` und `SKD_UPDATE_STATUS_URL` sind in `backend/settings.py` noch vorhanden, werden aber im aktuellen Code nicht genutzt. + +## Externe Abhaengigkeiten (mit Quelle und Zweck) +### Python-Libraries (requirements.txt) +- FastAPI: https://fastapi.tiangolo.com/ (Web-API und Routing) +- Uvicorn: https://www.uvicorn.org/ (ASGI-Server) +- Pydantic: https://docs.pydantic.dev/ (Datenmodelle und Validierung) +- Jinja2: https://jinja.palletsprojects.com/ (HTML-Templates) +- PyJWT: https://pyjwt.readthedocs.io/ (JWT-Erstellung und -Validierung) +- python-pam: https://pypi.org/project/python-pam/ (PAM-Authentifizierung) +- httpx: https://www.python-httpx.org/ (HTTP-Client fuer Update/OIDC) +- cryptography: https://cryptography.io/ (Krypto-Abhaengigkeit fuer JWT) +- PyYAML (optional): https://pyyaml.org/ (YAML-Parsing in `scripts/deploy.sh`) + +### System-Tools +- systemd: https://www.freedesktop.org/software/systemd/man/systemd.html (Service-Management) +- Linux-PAM: https://www.linux-pam.org/ (System-Authentifizierung) +- usermod/pkill/shutdown: https://man7.org/linux/man-pages/ (Account- und Session-Management) +- curl/tar/sha256sum/rsync/git/ssh: https://man7.org/linux/man-pages/ (Install/Update/Deploy) +- jq (optional): https://stedolan.github.io/jq/ (JSON-Parsing in Beispielen) +- notify-send: https://developer.gnome.org/libnotify/ (Desktop-Benachrichtigungen) +- paplay/aplay: https://www.freedesktop.org/wiki/Software/PulseAudio/ und https://alsa-project.org/ (Sound) + +### Externe Services +- Update-Service (intern): https://git.wlkns.org/stephan/update-webservice (Manifest/Status/Enrollment) +- OIDC-Service (intern): https://git.wlkns.org/stephan/oicd (Login via OIDC) + +## Weitere Dokumente +- Architektur: `docs/ARCHITECTURE.md` +- Deployment: `docs/DEPLOYMENT.md` diff --git a/docs/FAQ.md b/docs/FAQ.md index 38aa5dc..5f0977a 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -19,3 +19,8 @@ Nein, im Repository ist kein Docker-Setup enthalten. ## Wo liegen Logs? - systemd: `journalctl -u skd.service` - Update-Status/Logs: siehe `SKD_UPDATE_STATUS_FILE` und `SKD_UPDATE_LOG_FILE`. + +## Weitere Dokumente +- Einstieg: `docs/GETTING_STARTED.md` +- Nutzung: `docs/USAGE.md` +- Troubleshooting: `docs/TROUBLESHOOTING.md` diff --git a/docs/FOR_USERS.md b/docs/FOR_USERS.md new file mode 100644 index 0000000..8ef4579 --- /dev/null +++ b/docs/FOR_USERS.md @@ -0,0 +1,37 @@ +ID: DOC_000017 | Version: 0.2.1 | Status: Draft +By: Codex (GPT-5) + +# Fuer Nutzerinnen und Nutzer + +## Worum geht es? +Safe Kiddo Daemon hilft dabei, lokale Benutzerkonten auf einem Familien- oder Schulgeraet zu sperren und wieder freizugeben. Ziel ist, klare Nutzungszeiten durchzusetzen und sicherzustellen, dass nach einer Sperrung keine Sitzung offen bleibt. + +## Welche Probleme loest es? +- Ein Konto soll zu bestimmten Zeiten nicht nutzbar sein. +- Offene Sitzungen sollen beendet werden, wenn ein Konto gesperrt wird. +- Eltern/Betreuende wollen den Zustand zentral sehen und verwalten. + +## Typische Anwendungsfaelle +- Abendliche Nutzungszeit endet, der Account wird gesperrt. +- Bei Verstoessen gegen Regeln wird ein Konto kurzzeitig deaktiviert. +- Eine Sitzung bleibt offen und muss beendet werden. + +## Wie wird es bedient? +Die Bedienung erfolgt ueber eine einfache Web-Oberflaeche im lokalen Netzwerk. +Dort kann eine berechtigte Person: +- Konten sperren oder freigeben. +- Den aktuellen Status sehen. + +## Grenzen und Sicherheit +- Die Sperrung betrifft nur lokale Konten auf dem Geraet. +- Wenn kein berechtigter Zugang vorhanden ist, kann die Web-Oberflaeche nicht genutzt werden. +- Das System kann den Rechner im Bedarfsfall herunterfahren, um offene Sitzungen zu beenden. + +## Was tun, wenn etwas schiefgeht? +- Wenn die Web-Oberflaeche nicht erreichbar ist, die betreuende Person informieren. +- Wenn das Konto unerwartet gesperrt wurde, nicht weiter experimentieren, sondern nachfragen. +- Bei wiederholten Problemen soll der Betreiber die technische Fehlerbehebung pruefen. + +## Weitere Informationen (fuer Betreiber) +- Einstieg: `docs/GETTING_STARTED.md` +- Hilfe bei Problemen: `docs/TROUBLESHOOTING.md` diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 1b25697..2094f39 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -46,3 +46,14 @@ Hinweis: `jq` ist optional; ohne jq das Token manuell aus der JSON-Antwort lesen - Konfiguration anpassen: `docs/CONFIGURATION.md` - API und Web-UI nutzen: `docs/USAGE.md` - Deployment und Updates: `docs/DEPLOYMENT.md` + +## Typische Einsteigerfehler +- Service startet, aber Port 80 ist bereits belegt (loese den Konflikt oder nutze einen anderen Port). +- Login scheitert, weil `SKD_AUTH_ALLOWED_USERS`/`SKD_AUTH_ALLOWED_GROUPS` den Nutzer nicht erlauben. +- OIDC wird erwartet, ist aber nicht aktiv (Issuer/Client-ID/Secret fehlen). +- Token wird nicht gesendet (fehlender `Authorization: Bearer` Header). + +## Weitere Dokumente +- Endnutzer-Sicht: `docs/FOR_USERS.md` +- FAQ: `docs/FAQ.md` +- Troubleshooting: `docs/TROUBLESHOOTING.md` diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 55dbd2f..30a6f3d 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -35,3 +35,8 @@ By: Codex (GPT-5) ## Rollback meldet "no backup found" - Es existiert kein `/opt/sk_backup_*` vom vorherigen Update. - Rollback erst nach mindestens einem erfolgreichen Update moeglich. + +## Weitere Dokumente +- Einstieg: `docs/GETTING_STARTED.md` +- Konfiguration: `docs/CONFIGURATION.md` +- Deployment: `docs/DEPLOYMENT.md` diff --git a/docs/USAGE.md b/docs/USAGE.md index 706c2df..1bf0b7d 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -24,6 +24,15 @@ Login ist nur fuer erlaubte Nutzer moeglich (siehe `SKD_AUTH_ALLOWED_USERS` und - Login per PAM oder OIDC (wenn konfiguriert). - Aktionen: Benutzer sperren/entsperren, Update-Status, Update-Check, Apply/Rollback. +## Automatisierung (Power-User) +Die API kann in Skripten oder Zeitplaenen genutzt werden, z.B. fuer regelmaessige Sperrungen. + +Beispiel (cron, taeglich 21:00 sperren): +```bash +0 21 * * * curl -s -X POST -H "Authorization: Bearer $TOKEN" http://localhost/users/child1/disable +``` +Hinweis: Token sicher speichern (z.B. Root-Only Datei) und regelmaessig rotieren. + ## API-Endpunkte (Auszug) ### Health und Identitaet - `GET /health` (ohne Auth) @@ -66,6 +75,11 @@ curl -X POST -H "Authorization: Bearer $token" http://localhost/update/check ``` Hinweis: Ohne gespeichertes Update-Token liefert der Check einen Fehler. +## Weitere Dokumente +- Konfiguration: `docs/CONFIGURATION.md` +- Deployment: `docs/DEPLOYMENT.md` +- Troubleshooting: `docs/TROUBLESHOOTING.md` + ## CLI-Fallback (sk.sh) Das Legacy-Script arbeitet direkt auf dem Host und benoetigt Root-Rechte. diff --git a/project-management/PROJECT_STATUS.md b/project-management/PROJECT_STATUS.md index 30ee44f..6796d68 100644 --- a/project-management/PROJECT_STATUS.md +++ b/project-management/PROJECT_STATUS.md @@ -20,6 +20,7 @@ Sicheres, remote steuerbares System zum Sperren/Entsperren lokaler Nutzerkonten. | 28.12.2025 | 🏗️ Planning | Anforderungen als Epics und Stories dokumentiert. | | 15.01.2026 | 📝 Req | Doku und ENV-Beispiele an Code-Stand angepasst. | | 15.01.2026 | 📝 Req | Doku-Overhaul mit neuer Struktur und Archivierung. | +| 15.01.2026 | 📝 Req | Externe Service-Links in der Doku ergaenzt. | ## Epic-Backlog (Uebersicht) ### EPIC_000001: Legacy CLI Account Control (sk.sh) @@ -127,6 +128,12 @@ Sicheres, remote steuerbares System zum Sperren/Entsperren lokaler Nutzerkonten. - [x] US_000040: Doku-Struktur und Inhalte erstellen - [x] TASK_000043: Neue Doku-Dateien erstellen und verlinken - [x] TASK_000044: Altdoku archivieren +- [x] US_000041: Einbindung externer Services dokumentieren +- [x] TASK_000045: Einbindung externer Services dokumentieren +- [x] US_000042: Consumer-Perspektive und Audience-Split ergaenzen +- [x] TASK_000046: Consumer-Doku erstellen (FOR_USERS.md) +- [x] TASK_000047: README und Audience-Split anpassen +- [x] TASK_000048: External Dependencies und Audience-Ergaenzungen ## Offene Risiken / Abhaengigkeiten - Betrieb erfordert Root/sudo und lokale System-Tools (notify-send, sound player, uvicorn). diff --git a/project-management/requirements/epics/EPIC_000012.md b/project-management/requirements/epics/EPIC_000012.md index 5566aa9..417ecfc 100644 --- a/project-management/requirements/epics/EPIC_000012.md +++ b/project-management/requirements/epics/EPIC_000012.md @@ -40,3 +40,5 @@ Code und den Skripten orientiert. ## Zugeordnete User Stories - US_000040: Doku-Struktur und Inhalte erstellen +- US_000041: Einbindung externer Services dokumentieren +- US_000042: Consumer-Perspektive und Audience-Split ergaenzen diff --git a/project-management/requirements/stories/US_000041.md b/project-management/requirements/stories/US_000041.md new file mode 100644 index 0000000..9d42a7d --- /dev/null +++ b/project-management/requirements/stories/US_000041.md @@ -0,0 +1,16 @@ +ID: US_000041 | Version: 0.2.1 | Status: Done +By: Codex (GPT-5) + +# US_000041: Einbindung externer Services dokumentieren + +Als Operator moechte ich klare Schritte zur Einbindung des Update- und OIDC-Services, +damit die Schnittstellen korrekt konfiguriert und betrieben werden koennen. + +## Akzeptanzkriterien +- Given die Update- und OIDC-Services sind bekannt +- When die Doku gelesen wird +- Then sind Einbindungsschritte beschrieben (ENV, Enrollment, OIDC-Setup) +- And die Quellen der Services sind verlinkt + +## Task-Platzhalter +- TASK_000045: Einbindungsschritte in Doku ergaenzen diff --git a/project-management/requirements/stories/US_000042.md b/project-management/requirements/stories/US_000042.md new file mode 100644 index 0000000..23a35e7 --- /dev/null +++ b/project-management/requirements/stories/US_000042.md @@ -0,0 +1,19 @@ +ID: US_000042 | Version: 0.2.1 | Status: Done +By: Codex (GPT-5) + +# US_000042: Consumer-Perspektive und Audience-Split ergaenzen + +Als Produktteam moechten wir eine klare Trennung der Zielgruppen, +damit Endnutzer, Einsteiger, Power-User und Entwickler passende Einstiege haben. + +## Akzeptanzkriterien +- Given die Zielgruppen sind definiert +- When die Doku erstellt wird +- Then existiert eine Consumer-Doku ohne technische Inhalte +- And README benennt alle Zielgruppen und gruppiert die Links +- And External Dependencies sind mit offiziellen Links und Begruendung dokumentiert + +## Task-Platzhalter +- TASK_000046: Consumer-Doku erstellen (FOR_USERS.md) +- TASK_000047: README und Audience-spezifische Links/Sections anpassen +- TASK_000048: External Dependencies und Power-User/Beginner-Ergaenzungen einpflegen diff --git a/project-management/requirements/tasks/TASK_000045.md b/project-management/requirements/tasks/TASK_000045.md new file mode 100644 index 0000000..a430a65 --- /dev/null +++ b/project-management/requirements/tasks/TASK_000045.md @@ -0,0 +1,19 @@ +ID: TASK_000045 | Version: 0.2.1 | Status: Done +By: Codex (GPT-5) + +# TASK_000045: Einbindung externer Services dokumentieren + +## Outcome +Die Doku erklaert die Einbindung von Update-Service und OIDC-Service mit konkreten Schritten. + +## Story-Bezug +US_000041 + +## Beschreibung +- Update-Service: ENV, Enrollment-Optionen, Token-Handling. +- OIDC-Service: Issuer, DCR-Registration, Redirect-URI, ENV-Keys. +- Links zu den internen Repos. + +## Definition of Done (DoD) +- Doku ergaenzt in CONFIGURATION/DEPLOYMENT/ARCHITECTURE. +- Links zu Update- und OIDC-Service vorhanden. diff --git a/project-management/requirements/tasks/TASK_000046.md b/project-management/requirements/tasks/TASK_000046.md new file mode 100644 index 0000000..5f0c2b5 --- /dev/null +++ b/project-management/requirements/tasks/TASK_000046.md @@ -0,0 +1,17 @@ +ID: TASK_000046 | Version: 0.2.1 | Status: Done +By: Codex (GPT-5) + +# TASK_000046: Consumer-Doku erstellen (FOR_USERS.md) + +## Outcome +Endnutzer erhalten eine nicht-technische Anleitung zur Nutzung und Fehlerbehandlung. + +## Story-Bezug +US_000042 + +## Beschreibung +- FOR_USERS.md erstellen. +- Keine technischen Begriffe, keine Installation, kein Code. + +## Definition of Done (DoD) +- Consumer-Doku vorhanden und klar abgegrenzt. diff --git a/project-management/requirements/tasks/TASK_000047.md b/project-management/requirements/tasks/TASK_000047.md new file mode 100644 index 0000000..2b4b71b --- /dev/null +++ b/project-management/requirements/tasks/TASK_000047.md @@ -0,0 +1,18 @@ +ID: TASK_000047 | Version: 0.2.1 | Status: Done +By: Codex (GPT-5) + +# TASK_000047: README und Audience-Split anpassen + +## Outcome +README nennt Zielgruppen, grenzt das Projekt ab und verlinkt Doku je Zielgruppe. + +## Story-Bezug +US_000042 + +## Beschreibung +- Audience-Split explizit nennen. +- "Was es NICHT ist" ergaenzen. +- Links nach Zielgruppe gruppieren. + +## Definition of Done (DoD) +- README erfuellt erweiterte Anforderungen. diff --git a/project-management/requirements/tasks/TASK_000048.md b/project-management/requirements/tasks/TASK_000048.md new file mode 100644 index 0000000..4c1fede --- /dev/null +++ b/project-management/requirements/tasks/TASK_000048.md @@ -0,0 +1,18 @@ +ID: TASK_000048 | Version: 0.2.1 | Status: Done +By: Codex (GPT-5) + +# TASK_000048: External Dependencies und Audience-Ergaenzungen + +## Outcome +External Dependencies sind dokumentiert, Beginner-Fehler und Power-User-Use-Cases ergaenzt. + +## Story-Bezug +US_000042 + +## Beschreibung +- External Dependencies mit offiziellen Links + Begruendung dokumentieren. +- GETTING_STARTED (Beginner mistakes) ergaenzen. +- USAGE/CONFIGURATION (Power-User Automation/Performance) ergaenzen. + +## Definition of Done (DoD) +- Doku erfuellt Consumer/Beginner/Power-User/Developer Split.