Merge pull request #732 from it-at-m/601-überarbeitung-vitepress-doku

601 überarbeitung vitepress doku
it-at-m · Jan 22, 2025 · 368c6da · 368c6da
2 parents 45d1437 + 79249e2
commit 368c6da
Show file tree

Hide file tree

Showing 30 changed files with 529 additions and 265 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -1,9 +1,10 @@
 import {withMermaid} from "vitepress-plugin-mermaid"
 
 const PATH_TECHNIK = '/technik/';
-const PATH_CODING_CONVENTIONS = PATH_TECHNIK + 'coding_conventions/';
+const PATH_ECOSYSTEM = PATH_TECHNIK + 'ecosystem/';
+const PATH_NAMING_CONVENTIONS = PATH_TECHNIK + 'naming_conventions/';
 const PATH_ADR = PATH_TECHNIK + 'adr/';
-const PATH_GUIDES = PATH_TECHNIK + '/guides/';
+const PATH_GUIDES = PATH_TECHNIK + 'guides/';
 const PATH_SERVICES = '/services/';
 const PATH_SYSSPEC = PATH_TECHNIK + "systemspecification/";
 
@@ -19,45 +20,31 @@ export default withMermaid({
         nav: [
             {text: 'About', link: '/about/'},
             {text: 'Services', link: '/services/'},
-            {text: 'Technik', link: PATH_TECHNIK}
+            {text: 'Technik', link: `${PATH_TECHNIK}get_started`}
         ],
 
+        docFooter: {
+            prev: 'Vorherige Seite',
+            next: 'Nächste Seite'
+        },
+
         outline: {
             label: "Auf dieser Seite"
         },
 
         sidebar: {
             [PATH_TECHNIK]: [
-                {text: 'Tools & Frameworks', link: `${PATH_TECHNIK}`},
                 {
                     text: 'Getting Started', link: `${PATH_TECHNIK}get_started/`
                 },
-                {text: 'Entwicklungsumgebung', link: `${PATH_TECHNIK}development/`},
                 {
-                    text: 'Guides', link: `${PATH_GUIDES}`, collapsed: true, items: [
-                        {text: 'API-Client generieren', link: `${PATH_GUIDES}how-to-create-client-from-open-api-json.md`},
-                        {text: 'Tips und Tricks', link: `${PATH_GUIDES}tips-and-tricks.md`},
+                    text: 'Ecosystem', link: `${PATH_ECOSYSTEM}`, collapsed: true, items: [
+                        {text: 'Tools & Frameworks', link: `${PATH_ECOSYSTEM}toolsAndFrameworks`},
+                        {text: 'Workflows', link: `${PATH_ECOSYSTEM}workflows`}
                     ]
                 },
                 {
-                    text: 'Coding Conventions', link: `${PATH_CODING_CONVENTIONS}`, collapsed: true, items: [
-                        {text: 'Naming Convention - Testing', link: `${PATH_CODING_CONVENTIONS}tests_naming`},
-                        {text: 'Naming Convention - Database', link: `${PATH_CODING_CONVENTIONS}db_naming`}
-                    ]
-                },
-                {
-                    text: "Systemspezifikation",
-                    link: `${PATH_SYSSPEC}`,
-                    collapsed: true,
-                    items: [
-                        {
-                            text: "Sicherheit",
-                            link: `${PATH_SYSSPEC}security`,
-                        },
-                    ],
-                },
-                {
-                    text: 'Adr', link: `${PATH_ADR}`, collapsed: true, items: [
+                    text: 'Designentscheidungen', link: `${PATH_ADR}`, collapsed: true, items: [
                         {text: 'Renovate - ignoriere lombok', link: `${PATH_ADR}adr001-renovate-ignore-lombok`},
                         {
                             text: 'Verbesserung Einstiegsfreundlichkeit',
@@ -72,27 +59,55 @@ export default withMermaid({
                             link: `${PATH_ADR}adr-always-full-keycloak-migration`
                         },
                         {
-                            text: 'Auslagern von Authority Strings',
+                            text: 'Auslagern von Authoritystrings',
                             link: `${PATH_ADR}adr-auslagerung-authority-strings`
                         },
                         {
                             text: 'Frontend-Refarch-Template',
                             link: `${PATH_ADR}adr-frontend-template`
                         }
                     ]
+                },
+                {
+                    text: 'Naming Conventions', link: `${PATH_NAMING_CONVENTIONS}`, collapsed: true, items: [
+                        {text: 'Flyway', link: `${PATH_NAMING_CONVENTIONS}flyway`},
+                        {text: 'Tests', link: `${PATH_NAMING_CONVENTIONS}testing`},
+                        {text: 'Workflows', link: `${PATH_NAMING_CONVENTIONS}workflows`}
+                    ]
+                },
+                {
+                    text: 'Guides', link: `${PATH_GUIDES}`, collapsed: true, items: [
+                        {
+                            text: 'API-Client generieren',
+                            link: `${PATH_GUIDES}how-to-create-client-from-open-api-json.md`
+                        },
+                        {text: 'Datenbankzugriff', link: `${PATH_GUIDES}db-access.md`},
+                        {text: 'Neuer Microservice', link: `${PATH_GUIDES}new-service.md`}
+                    ]
+                },
+                {
+                    text: "Systemspezifikation",
+                    link: `${PATH_SYSSPEC}`,
+                    collapsed: true,
+                    items: [
+                        {
+                            text: "Sicherheit",
+                            link: `${PATH_SYSSPEC}security`,
+                        },
+                    ],
                 }
             ],
             [PATH_SERVICES]: [
+                {text: 'Admin-Service', link: `${PATH_SERVICES}admin-service/`},
+                {text: 'Auth-Service', link: `${PATH_SERVICES}auth-service/`},
+                {text: 'Basisdaten-Service', link: `${PATH_SERVICES}basisdaten-service/`},
                 {text: 'Briefwahl-Service', link: `${PATH_SERVICES}briefwahl-service/`},
-                {text: 'Infomanagement-Service', link: `${PATH_SERVICES}infomanagement-service/`},
                 {text: 'EAI-Service', link: `${PATH_SERVICES}eai-service/`},
-                {text: 'Basisdaten-Service', link: `${PATH_SERVICES}basisdaten-service/`},
-                {text: 'Monitoring-Service', link: `${PATH_SERVICES}monitoring-service/`},
-                {text: 'Wahlvorstand-Service', link: `${PATH_SERVICES}wahlvorstand-service/`},
                 {text: 'Ergebnismeldung-Service', link: `${PATH_SERVICES}ergebnismeldung-service/`},
-                {text: 'Auth-Service', link: `${PATH_SERVICES}auth-service/`},
+                {text: 'Infomanagement-Service', link: `${PATH_SERVICES}infomanagement-service/`},
+                {text: 'Monitoring-Service', link: `${PATH_SERVICES}monitoring-service/`},
                 {text: 'Vorfälle und Vorkommnisse-Service', link: `${PATH_SERVICES}vorfaelleundvorkommnisse-service/`},
-                {text: 'Admin-Service', link: `${PATH_SERVICES}admin-service/`},
+                {text: 'Wahlvorstand-Service', link: `${PATH_SERVICES}wahlvorstand-service/`},
             ],
         },
 
@@ -101,7 +116,34 @@ export default withMermaid({
         ],
 
         search: {
-            provider: 'local'
+            provider: 'local',
+            options: {
+                locales: {
+                    root: {
+                        translations: {
+                            button: {
+                                buttonText: 'Suche',
+                                buttonAriaLabel: 'Suche'
+                            },
+                            modal: {
+                                displayDetails: 'Anzeigen',
+                                resetButtonTitle: 'Ersetzen',
+                                backButtonTitle: 'Schließen',
+                                noResultsText: 'Keine Ergebnisse',
+                                footer: {
+                                    selectText: 'Auswählen',
+                                    selectKeyAriaLabel: 'Eingeben',
+                                    navigateText: 'Navigieren',
+                                    navigateUpKeyAriaLabel: 'Oben',
+                                    navigateDownKeyAriaLabel: 'Unten',
+                                    closeText: 'Schließen',
+                                    closeKeyAriaLabel: 'Esc'
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         }
     },
     mermaidPlugin: {

diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,3 @@
+:root {
+    --vp-code-copy-copied-text-content: 'In Zwischenablage kopiert!'
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -1,15 +1,16 @@
 // .vitepress/theme/index.ts
 import type {Theme} from "vitepress";
 import DefaultTheme from "vitepress/theme";
+import './custom.css'
 
 import status from "../components/adr/status.vue";
 import statusOverview from "../components/adr/status/overview.vue";
 
 export default {
-  extends: DefaultTheme,
-  enhanceApp({ app }) {
-    // register your custom global components
-    app.component("adrStatus", status);
-    app.component("statusOverview", statusOverview);
-  },
+    extends: DefaultTheme,
+    enhanceApp({app}) {
+        // register your custom global components
+        app.component("adrStatus", status);
+        app.component("statusOverview", statusOverview);
+    },
 } satisfies Theme;
diff --git a/docs/src/about/index.md b/docs/src/about/index.md
@@ -19,6 +19,4 @@ dass das Gremium zu jederzeit ausreichend besetzt ist.
 Während der Stimmauszählung, und der damit verbundenen Erstellung der Niederschrift, unterstützt das System den Wahlvorstand bei der korrekten Erfassung der Daten.
 Dazu gibt es zahlreiche Regeln und Konsistenzprüfungen, die dem Wahlvorstand Feedback geben, ob die erfassten Daten korrekt sind.
 
-Das Wahlamt kann über das System den Wahlbezirken wichtige Informationen zukommen lassen.
-
-🚧 Eine detaillierte Beschreibung aller [Funktionen](/services/) folgt im Laufe der Veröffentlichung.
+Das Wahlamt kann über das System den Wahlbezirken wichtige Informationen zukommen lassen.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -6,13 +6,9 @@ hero:
   name: "Wahllokalsystem"
   text: "Datenerfassung am Wahltag"
   tagline: Beschreibung der Funktionalität und Technik
+  actions:
+    - text: Getting started
+      link: /technik/get_started
 
-features:
-  - title: Feature A
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature B
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature C
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
 ---
 
diff --git a/docs/src/services/auth-service/index.md b/docs/src/services/auth-service/index.md
@@ -73,7 +73,7 @@ sequenceDiagram
 
 ### Login
 
-Damit ein Benutzer sind anmelden darf müssen zum einen die Logindaten entsprechend LDAP korrekt sein.
+Damit ein Benutzer sich anmelden darf, müssen zum einen die Logindaten entsprechend LDAP korrekt sein.
 Des Weiteren müssen folgende Regeln beachtet werden:
 1. Ist der Nutzer gesperrt?
 1. Falls der Nutzer gesperrt ist, muss die Sperre abgelaufen sein
@@ -101,23 +101,23 @@ Die Benutzer die zuvor für den Wahltermin vorhanden waren werden gelöscht.
 
 Alle Konfigurationsparameter beginnen mit dem Prefix `service.config`
 
-| Name                                             | Beschreibung                                                                                       | Default                  |
-|--------------------------------------------------|----------------------------------------------------------------------------------------------------|--------------------------|
-| crypto.encryptionPrefix                          | String vor dem verschlüssten Wert. Auf diese Weise sind verschlüsselte Werte erkennbar             | ENCRYPTED:               |
-| crypto.key                                       | Schlüssel zum ver- und entschlüsseln                                                               |                          |
-| falscheLoginZeitstrafe                           | Zeit in Minuten für eine Sperrung                                                                  | 10                       |
-| maxLoginAttempts                                 | Maximale Anzahl an Fehlersuchen bis der Account gesperrt wird.                                     | 5                        |
-| clients.infomanagement.basepath                  | URL zum Infomanagement-Service                                                                     | `http://localhost:39146` |
-| clients.infomanagement.configkey.welcomeMessage  | Schlüssel für Konfiguration der Willkommensnachricht                                               | WILLKOMMENSTEXT          |
-| clients.infomanagement.configkey.fruehesterLogin | Schlüssel für Konfiguration des frühesten Zeitpunktes für Login                                    | FRUEHESTE_LOGIN_UHRZEIT  |
-| clients.infomanagement.configkey.spaetesterLogin | Schlüssel für Konfiguration des spätesten Zeitpunktes für Login                                    | SPAETESTE_LOGIN_UHRZEIT  |
-| clients.infomanagement.dateformat                | Format des Datums wie es vom Infomanagement-Service kommt                                          | dd.MM.yyyy HH:mm         |
-| serviceauth.welcomemessage.default               | Standartd Willkommensnachricht falls die definierte Willkommensnachricht nicht geladen werden kann | Willkommen zur Wahl!     |
-| ldap.userDn                                      | Username zur Authentifizierung am LDAP-Server                                                      |                          |
-| ldap.userDnPassword                              | Passwort zur Authentifizierung am LDAP-Server                                                      |                          |
-| ldap.contextSource                               | Url zum LDAP-Server, z.B. `ldaps://my-ldap-server.de:636`                                          |                          |
-| ldap.userSearchBase                              | Basispfad für Suche, z.b. `o=myOrg,c=de`                                                           | ou=people                |
-| ldap.userSearchFilter                            | Filter für Suche, z.B. `(uid={0})`                                                                 | `uid={0}`                |
-| oauth2.clients.wahllokalgui.id                   | ID des Client der Wahllokal-Anwendung                                                              | wahllokalgui             |
-| oauth2.clients.admingui.id                       | ID des Client der Admintool-Anwendung                                                              | admingui                 |
-| oauth2.jwk.rsa.init.seed                         | Seed für RSA-Schlüsselpaar. Gleiche Seeds sorgen für gleiche Ergebnisse                            |                          |
+| Name                                             | Beschreibung                                                                                      | Default                  |
+|--------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------|
+| crypto.encryptionPrefix                          | String vor dem verschlüssten Wert. Auf diese Weise sind verschlüsselte Werte erkennbar            | ENCRYPTED:               |
+| crypto.key                                       | Schlüssel zum ver- und entschlüsseln                                                              |                          |
+| falscheLoginZeitstrafe                           | Zeit in Minuten für eine Sperrung                                                                 | 10                       |
+| maxLoginAttempts                                 | Maximale Anzahl an Fehlersuchen bis der Account gesperrt wird.                                    | 5                        |
+| clients.infomanagement.basepath                  | URL zum Infomanagement-Service                                                                    | `http://localhost:39146` |
+| clients.infomanagement.configkey.welcomeMessage  | Schlüssel für Konfiguration der Willkommensnachricht                                              | WILLKOMMENSTEXT          |
+| clients.infomanagement.configkey.fruehesterLogin | Schlüssel für Konfiguration des frühesten Zeitpunktes für Login                                   | FRUEHESTE_LOGIN_UHRZEIT  |
+| clients.infomanagement.configkey.spaetesterLogin | Schlüssel für Konfiguration des spätesten Zeitpunktes für Login                                   | SPAETESTE_LOGIN_UHRZEIT  |
+| clients.infomanagement.dateformat                | Format des Datums wie es vom Infomanagement-Service kommt                                         | dd.MM.yyyy HH:mm         |
+| serviceauth.welcomemessage.default               | Standard Willkommensnachricht falls die definierte Willkommensnachricht nicht geladen werden kann | Willkommen zur Wahl!     |
+| ldap.userDn                                      | Username zur Authentifizierung am LDAP-Server                                                     |                          |
+| ldap.userDnPassword                              | Passwort zur Authentifizierung am LDAP-Server                                                     |                          |
+| ldap.contextSource                               | Url zum LDAP-Server, z.B. `ldaps://my-ldap-server.de:636`                                         |                          |
+| ldap.userSearchBase                              | Basispfad für Suche, z.b. `o=myOrg,c=de`                                                          | ou=people                |
+| ldap.userSearchFilter                            | Filter für Suche, z.B. `(uid={0})`                                                                | `uid={0}`                |
+| oauth2.clients.wahllokalgui.id                   | ID des Client der Wahllokal-Anwendung                                                             | wahllokalgui             |
+| oauth2.clients.admingui.id                       | ID des Client der Admintool-Anwendung                                                             | admingui                 |
+| oauth2.jwk.rsa.init.seed                         | Seed für RSA-Schlüsselpaar. Gleiche Seeds sorgen für gleiche Ergebnisse                           |                          |
diff --git a/docs/src/services/basisdaten-service/index.md b/docs/src/services/basisdaten-service/index.md
@@ -42,7 +42,7 @@ classDiagram
 
 ## Handbuch
 
-In dem Service werden Handbücher verwaltet. Je Wahl und Wahlbezirkart kann ein Handbuch hinterlegt werden.
+In dem Service werden Handbücher verwaltet. Je Wahl und Wahlbezirksart kann ein Handbuch hinterlegt werden.
 
 Bei dem Handbuch soll es sich um ein PDF-Dokument handeln. 
 

diff --git a/docs/src/services/ergebnismeldung-service/index.md b/docs/src/services/ergebnismeldung-service/index.md
@@ -21,8 +21,8 @@ Folgende Services werden benötigt:
 ### Abrufen von A-Werten (Wahlberechtigte)
 Die Methode `getAWerte()` liefert die A-Werte für eine bestimmte Wahlbezirk-ID.
 Die A-Werte repräsentieren die Anzahl der Wahl- bzw. Stimmberechtigten in einem Wahlbezirk.
-Sie teilen sich auf in die Anzahl an Wahlberechtigten die keinen Wahlschein erhalten haben (A1)
-und in die Anzahl an Wahlberechtigten die einen Wahlschein erhalten haben und deshalb einen W-Vermerk im 
+Sie teilen sich auf in die Anzahl an Wahlberechtigten, die keinen Wahlschein erhalten haben (A1)
+und in die Anzahl an Wahlberechtigten, die einen Wahlschein erhalten haben und deshalb einen W-Vermerk im 
 Wählerverzeichnis besitzen (A2).
 
 - Wenn über die EAI im externen Wahlsystem Daten gefunden werden, dann werden diese im lokalen Repository gespeichert
@@ -37,7 +37,7 @@ Die Methode initialisiereAWerte() initialisiert die Wahlberechtigten (A-Werte) f
 
 - Für jede Wahlbezirk-ID in der Liste wird über die EAI im externen Wahlsystem nach A-Werten gesucht. Bei Erfolg werden
 diese im lokalen Repository gespeichert.
-- Bei Nichterfolg, wird geprüft ob im lokalen Repository wenigstens 'alte' A-Werte existieren.
+- Bei Nichterfolg wird geprüft, ob im lokalen Repository wenigstens 'alte' A-Werte existieren.
 - Falls weder im externen Wahlsystem noch im lokalen Repository A-Werte gefunden werden
   liefert der Service einen Fehler.