Felix KemmlerandClaude Sonnet 5
598dfcd38a
Docker-Images bauen und veröffentlichen / build (, omsorgCore/Dockerfile, omsorgcore) (push) Successful in 3s
Docker-Images bauen und veröffentlichen / build (, omsorgWeb/Dockerfile, omsorgweb) (push) Failing after 4s
Docker-Images bauen und veröffentlichen / build (VITE_OMSORG_CORE_URL=${{ vars.OMSORG_CORE_PUBLIC_URL }}, omsorgapp/Dockerfile, omsorgapp) (push) Successful in 3s
- omsorgapp: drop Electron, run as a plain Vite/React browser app; refresh token moves to an HttpOnly cookie (omsorgCore), CORS added for the new browser origin, document download/preview switched to Blob-based browser APIs. - Add Dockerfiles for omsorgCore, omsorgapp, and omsorgWeb, a docker-compose.yml wiring Postgres/MySQL/all three apps together, and a Gitea Actions workflow that builds and pushes images to the repo's container registry on push to main and on version tags. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
63 lines
4.3 KiB
Markdown
63 lines
4.3 KiB
Markdown
# Anleitung — omsorgcore-client-ts
|
|
|
|
Generierter TypeScript-Client für die `omsorgCore`-API, erzeugt mit [openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator) aus der Swagger/OpenAPI-JSON des Backends. **Kein eigenständiges Extra mehr:** Alle handgeschriebenen Wrapper unter `src/api/*Api.js` (`employeesApi.js`, `facilitiesApi.js`, `usersApi.js`, ...) importieren ihre `*Api`-Klasse aus diesem Paket (`import ... from "omsorgcore-client-ts"`) und reichen dessen typisierte Requests/Responses direkt durch — dieser Client ist damit Teil des echten Datenpfads von `omsorgapp` gegen `omsorgCore`, nicht nur eine zusätzliche Bibliothek für Skripte/Typprüfung.
|
|
|
|
`README.md` in diesem Ordner wird bei jeder Generierung automatisch neu geschrieben (Standard-Output von openapi-generator, dokumentiert die generierten API-Methoden) — diese Datei hier nicht, sie bleibt stabil.
|
|
|
|
## Voraussetzungen
|
|
|
|
- Node.js + npx (bereits für den Rest von `omsorgapp` vorhanden)
|
|
- Java (wird von `openapi-generator-cli` intern benötigt, kein separates Setup nötig, sofern `java` im `PATH` ist)
|
|
- `omsorgCore` muss lokal im **Development-Modus** laufen, da Swagger nur dort aktiv ist (siehe `omsorgCore/CLAUDE.md`, Abschnitt "Session-Killswitch" o.ä. — Swagger ist an `app.Environment.IsDevelopment()` gebunden)
|
|
|
|
## API lokal starten (für die Generierung)
|
|
|
|
```bash
|
|
cd omsorgCore
|
|
ASPNETCORE_ENVIRONMENT=Development dotnet run --project src/OmsorgCore.Api
|
|
# → Swagger-JSON unter http://localhost:5245/swagger/v1/swagger.json
|
|
```
|
|
|
|
## Client neu generieren
|
|
|
|
```bash
|
|
cd omsorgapp/api-client-ts
|
|
npm run generate
|
|
# entspricht: ./generate.sh
|
|
```
|
|
|
|
Nimmt die Backend-URL aus `OMSORG_CORE_URL` (Default `http://localhost:5245`, dieselbe Konvention wie `src/api/config.js`). Überschreibt `src/`, `README.md`, `package.json`, `.gitignore`, `tsconfig*.json` mit dem aktuellen generierten Stand — danach `git diff` prüfen, bevor committet wird (eigene Anpassungen an `package.json`, z. B. das `generate`-Script, ggf. erneut eintragen, siehe unten).
|
|
|
|
## Bauen
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
Erzeugt `dist/` (CommonJS + ESM, siehe `tsconfig.json`/`tsconfig.esm.json`). `dist/` und `node_modules/` sind `.gitignore`'t — nur der generierte Quellcode unter `src/` wird eingecheckt.
|
|
|
|
## Verwendung (Beispiel)
|
|
|
|
```ts
|
|
import { Configuration, AuthApi } from "./dist"; // oder "omsorgcore-client-ts" nach npm-Link/Publish
|
|
|
|
const config = new Configuration({ basePath: process.env.OMSORG_CORE_URL || "http://localhost:5245" });
|
|
const authApi = new AuthApi(config);
|
|
|
|
const loginResponse = await authApi.apiAuthLoginPost({
|
|
loginRequest: { username: "admin", password: "abersicher" },
|
|
});
|
|
console.log(loginResponse.accessToken);
|
|
```
|
|
|
|
Jeder Controller aus `omsorgCore` hat eine eigene `*Api`-Klasse (`AuthApi`, `EmployeesApi`, `FacilitiesApi`, `ContractsApi`, `OrdersApi`, `RolesApi`, `UsersApi`, `ValueListsApi`, `AuditLogApi`, `AdminSessionsApi`, `AdminEmailApi`, `HealthApi`), Methodennamen sind aus den Routen abgeleitet (z. B. `apiEmployeesGet`, `apiEmployeesIdPut`) — siehe `src/apis/index.ts` bzw. das generierte `README.md` für die vollständige Liste.
|
|
|
|
## Verbindlich: nach jeder Backend-Änderung neu generieren
|
|
|
|
Sobald sich Controller/DTOs in `omsorgCore.Api/Contracts` ändern (neue Endpunkte, neue/umbenannte/entfernte Felder in Requests/Responses), **muss** dieser Client noch im selben Change neu generiert (`npm run generate`), neu gebaut (`npm run build`) und der Diff mitcommittet werden.
|
|
|
|
**Das ist kein Nice-to-have, sondern verhindert einen stillen, fehlerfreien Datenverlust:** Ein veralteter generierter Client wirft **keinen Fehler**, wenn er ein Feld nicht kennt — er lässt es beim (De-)Serialisieren einfach weg. Ein Request/eine Response, die dieses Feld enthält, sieht aus der UI heraus wie ein Erfolg aus, das Feld kommt aber nie beim Backend an bzw. nie in der Antwort zurück. Konkret passiert (2026-08-08, Facility-Website): `Website` wurde im Backend ergänzt, Speichern in `omsorgapp` meldete Erfolg, aber der Wert wurde nie persistiert, weil `omsorgcore-client-ts` zum Zeitpunkt der Änderung noch aus der alten Swagger-JSON generiert war.
|
|
|
|
Nach `npm run generate` immer `git diff package.json` prüfen — der Generator überschreibt die Datei komplett, das eigene `generate`-Script (`"generate": "./generate.sh"`) muss danach erneut eingetragen werden, sonst fehlt es beim nächsten Lauf.
|