Merge pull request #778 from it-at-m/742-in-doku-das-anlegen-eines-fr…

…ontend-projekt-beschreiben

742 in doku das anlegen eines frontend projekt beschreiben

docs/.vitepress/config.mts

@@ -7,6 +7,7 @@ const PATH_ADR = PATH_TECHNIK + 'adr/';
 const PATH_NAMING_CONVENTIONS = PATH_TECHNIK + 'naming_conventions/';
 const PATH_GUIDES = PATH_TECHNIK + 'guides/';
 const PATH_API_CLIENT_GENERATION = PATH_GUIDES + 'api-client-generation/'
+const PATH_MICROSERVICE_GENERATION = PATH_GUIDES + 'new-microservice/'
 const PATH_SYSSPEC = PATH_TECHNIK + "systemspecification/";
 
 // https://vitepress.dev/reference/site-config
@@ -89,7 +90,16 @@ export default withMermaid({
                             },
                         ]},
                         {text: 'Datenbankzugriff', link: `${PATH_GUIDES}db-access.md`},
-                        {text: 'Neuer Microservice', link: `${PATH_GUIDES}new-service.md`}
+                        {text: 'Microservice anlegen', link: `${PATH_MICROSERVICE_GENERATION}`, collapsed: true, items: [
+                            {
+                                text: "Neuer Microservice Backend",
+                                link: `${PATH_MICROSERVICE_GENERATION}new-service-backend.md`
+                            },
+                            {
+                                text: "Neues Frontend-Projekt",
+                                link: `${PATH_MICROSERVICE_GENERATION}new-service-frontend.md`
+                            }
+                        ]}
                     ]
                 },
                 {

docs/src/technik/guides/new-microservice/index.md

@@ -0,0 +1,27 @@
+# Erstellung eines neue Microservices
+
+Wenn ein neuer Microservice angelegt wird, sind dabei einige Themen zu beachten. 
+
+## Update der Tests
+
+Im Projekt haben wir für das Naming unserer Tests [Konventionen](/technik/naming_conventions/testing) aufgestellt. Die bereitgestellten Tests der 
+[Refarch-Templates](https://github.com/it-at-m/refarch-templates/), welches im Projekt eingesetzt wird, müssen 
+entsprechend angepasst werden.
+
+## Workflows einrichten
+
+Im Repo gibt es diverse [Workflows](/technik/ecosystem/workflows). Die Workflows eines bestehenden Services sind zu
+kopieren und die Trigger anzupassen.
+
+> [!IMPORTANT]
+> Beim Kopieren ist das [Namensschema](/technik/naming_conventions/workflows) zu beachten. Außerdem muss zwingend für 
+> ein Frontend-Projekt ein Frontend-Workflow und für einen Backend-Service ein Backend-Workflow dupliziert werden!
+
+## Individuelle Anpassungen 
+
+Einige Einstellungen sind davon abhängig, ob es sich um einen Frontend oder Backend-Service handelt. Die folgenden 
+Guides sollen dabei unterstützen:
+
+1. Guide zur Erstellung eines [neuen Backend-Services](/technik/guides/new-microservice/new-service-backend.md)
+2. Guide zur Erstellung eines [neuen Frontend-Projekts](/technik/guides/new-microservice/new-service-frontend.md)
+

docs/src/technik/guides/new-service.md → docs/src/technik/guides/new-microservice/new-service-backend.md

@@ -1,18 +1,17 @@
-# Erstellung eines neue Microservices
+# Backend-Microservice
 
-Wenn ein neuer Microservice angelegt wird, sind dabei folgende Themen zu beachten.
+Um einen neuen Backend-Service anzulegen sind zuvor die [allgemeinen Infos](/technik/guides/new-microservice/index.md) 
+zum Einrichten eines neuen Services zu beachten.
 
-## Backend-Microservice
-
-### Maven-Projekt anlegen
+## Maven-Projekt anlegen
 
 Für den neuen Service wird ein Ordner parallel zu den anderen Services angelegt. Dabei ist auf das Namensschema zu achten:
 `wls-<Domain>-service`
 
 In dem Ordner wird das Maven-Projekt eingerichtet. Dazu aus den [RefArch-Templates](https://github.com/it-at-m/refarch-templates/tree/main/refarch-backend/)
 die Dateien des jeweiligen Unterordners in den erstellten Projektordner kopieren.
 
-#### Pflege der Dependencies und Plugins
+### Pflege der Dependencies und Plugins
 
 Einen Überblick über die verwendeten Dependencies und Plugins geben die vorhandenen Services. Der Broadcast-Service ist
 ein Service, der auf keine andere Services zugreift. Der Basisdaten-Service ist ein Service der auf andere Services
@@ -21,18 +20,7 @@ zugreift. Dementsprechend verwenden die Services unterschiedliche Plugins.
 Da das RefArch-Template auf ein allgemeines Szenario abzielt, ist mit zusätzlichen Schritten zu rechnen, um den Service
 funktionsfähig zu bekommen.
 
-#### Update der Tests
-
-Im Projekt haben wir für das Naming unserer Tests [Konventionen](/technik/naming_conventions/testing) aufgestellt. Die bereitgestellten Tests des Templates
-müssen entsprechend angepasst werden.
-
-### Workflows einrichten
-
-Im Repo gibt es diverse [Workflows](/technik/ecosystem/workflows). Die Workflows eines bestehenden Services sind zu
-kopieren und die Trigger anzupassen.
-
-> [!IMPORTANT]
-> Beim Kopieren ist das [Namensschema](/technik/naming_conventions/workflows) zu beachten.
+## Workflow Templates
 
 ::: code-group
 ```yml {1,8-9,18} [wls-&lt;domain&gt;-service_push-dev.yml]
@@ -74,7 +62,7 @@ jobs:
 ``` 
 :::
 
-### Datenbank einrichten
+## Datenbank einrichten
 
 Jeder Service hat einen eigenen Benutzer für die Datenbank. Diese sind im File `stack/oracle-database/add-user-on-startup.sql` hinterlegt. Die Zugriffs-URL ist für alle Services gleich:
 `jdbc:oracle:thin:@//localhost:1521/XEPDB1`
@@ -88,7 +76,7 @@ Beispiel für `wls-broadcast-service`:
 - Benutzername: `wls_broadcast_service`
 - Passwort: `secret`
 
-### Routing im Gateway einrichten
+## Routing im Gateway einrichten
 
 Damit das Frontend mit dem Service kommunizieren kann, ist im Gateway eine neue Route einzurichten. Das Routing erfolgt mit
 dem Servicenamen.
@@ -97,14 +85,10 @@ Beispiel:
 
 Anfragen die an den Broadcast-Service gehen sollen beginnen im Path mit `/api/broadcast-service/`.
 
-### Pflege der Rechte im Auth-Service
+## Pflege der Rechte im Auth-Service
 
 Die Pflege der Rechte erfolgt in dem Auth-Service über Flyway-Files. Über `insert`-Statements werden die Rechte ergänzt
 und die Zuordnung zu den Rollen vorgenommen.
 
 > [!NOTE]
-> Die Pflege der Rollen und Rechte erfolgt immer über neue, noch nicht im Default-Branch enthaltene, Flyway-Skripte.
-
-## Frontend-Microservice
-
-🚧 -> https://github.com/it-at-m/Wahllokalsystem/issues/742
+> Die Pflege der Rollen und Rechte erfolgt immer über neue, noch nicht im Default-Branch enthaltene, Flyway-Skripte.

docs/src/technik/guides/new-microservice/new-service-frontend.md

@@ -0,0 +1,88 @@
+# Frontend-Projekt
+
+Um ein neues Frontend-Projekt anzulegen sind zuvor die [allgemeinen Infos](/technik/guides/new-microservice/index.md) 
+zum Einrichten eines neuen Services zu beachten.
+
+## Referenzarchitektur-Template klonen
+Um ein neues Frontend-Projekt anzulegen, wird das entsprechende Frontend-Template der 
+[Referenzarchitektur](https://github.com/it-at-m/refarch-templates/tree/main/refarch-frontend) benötigt. Da wir einen 
+neuen Frontend-Service brauchen, ist nur der Ordner `refarch-frontend` des Templates relevant.
+
+Der einfachste Weg, diesen in das WLS-Projekt zu integrieren, ist es, das Refarch-Repository zu klonen und anschließend
+den `refarch-frontend`-Ordner zu kopieren und lokal im Projekt einzufügen. Dafür wird der Ordner umbenannt, weil er
+dem Namensschema `wls-gui-<frontend-name>` entsprechen sollte.
+
+::: details Beispiel
+Zum Beispiel heißt der Ordner `wls-gui-wahllokalsystem` für das Wahllokalsystem und könnte `wls-gui-admintool` für das 
+Admintool bezeichnet werden.
+:::
+
+## Workflow Templates
+
+::: code-group
+```yml {1,8-9,18} [wls-gui-&lt;frontend-name&gt;_push-dev.yml]
+name: build push dev gui <frontend-name>
+
+on:
+  push:
+    branches:
+      - dev
+    paths:
+      - 'wls-gui-<frontend-name>/**'
+      - '.github/workflows/wls-gui-<frontend-name>_push-dev.yml'
+
+jobs:
+  build-github-container-image:
+    permissions:
+      packages: write
+    uses:
+      ./.github/workflows/callable-create-github-container-image-frontend.yml
+    with:
+      service: 'wls-gui-<frontend-name>'
+```
+
+```yml {1,6-7,14} [wls-gui-&lt;frontend-name&gt;_pull-request.yml]
+name: verify pull request gui <frontend-name>
+
+on:
+  pull_request:
+    paths:
+      - 'wls-gui-<frontend-name>/**'
+      - '.github/workflows/wls-gui-<frontend-name>_pull-request.yml'
+
+jobs:
+  verify-pull-request:
+    uses:
+      ./.github/workflows/callable-run-npm-build.yml
+    with:
+      package-dir: 'wls-gui-<frontend-name>'
+``` 
+:::
+
+## Routing im Gateway einrichten
+
+Damit der Port und die URL für das neue Frontend-Projekt korrekt verknüpft wird, muss das 
+[`application-routes.yml`-File](https://github.com/it-at-m/Wahllokalsystem/blob/dev/stack/gateway_config/application-routes.yml) 
+entsprechend angepasst werden:
+
+```yaml
+spring:
+  cloud:
+    gateway:
+      routes:
+        # ... 
+        - id: gui-<frontend-name> // [!code focus:4]
+          uri: http://kubernetes.docker.internal:<PORT>/
+          predicates:
+            - Path=/<frontend-name>/**
+```
+
+> [!IMPORTANT]
+> Es wird immer die erste Route verwendet, welche die Bedingungen (predicates) erfüllt. Nur `Path=/**` wäre auf alle Pfade 
+> anwendbar, weshalb alle Routen, die danach noch kommen, nicht mehr berücksichtigt werden. Daher muss eine Route mit 
+> dem Pfad `Path=/**` immer an letzter Stelle stehen.
+
+## Ungenutzte Refarch-Elemente entfernen
+
+Damit der Code sauber und übersichtlich bleibt, sollten die Elemente des Refarch-Templates, die nicht für das Projekt
+benötigt werden, wie zum Beispiel [Mucatar](https://github.com/it-at-m/Wahllokalsystem/pull/661/files) entfernt werden.