company-tool/INSTALL.md

# Installation

Diese Anleitung beschreibt die Installation einer lokalen Company-Tool-Instanz
mit PostgreSQL und Backend. Sie ist so aufgebaut, dass sie später als Grundlage
für Installationen bei Organisationen verwendet werden kann.

## Voraussetzungen

Für eine lokale Installation werden benötigt:

- PostgreSQL 16 oder neuer
- Rust/Cargo
- Node.js 24 oder neuer, für Webfrontend und Kommunikationstests

Optional:

- Docker oder Podman, wenn PostgreSQL als Container laufen soll

## PostgreSQL per Docker Compose

Im Projekt liegt eine vorbereitete PostgreSQL-Konfiguration.

```bash
docker compose up -d postgres
```

Die Standardwerte sind:

- Host: `localhost`
- Port: `5432`
- Datenbank: `companytool`
- Benutzer: `companytool`
- Passwort: `companytool`

Danach `.env` anlegen:

```bash
cp .env.example .env
```

Verbindung prüfen:

```bash
psql "postgres://companytool:companytool@localhost:5432/companytool" -c "select 1;"
```

## PostgreSQL manuell anlegen

Falls PostgreSQL bereits auf einem Server installiert ist, kann die Datenbank
manuell angelegt werden.

Als PostgreSQL-Admin ausführen:

```sql
create user companytool with password 'companytool';
create database companytool owner companytool;
```

Empfohlene produktive Anpassungen:

- eigenes starkes Passwort verwenden
- Datenbank nur aus dem internen Netz erreichbar machen
- PostgreSQL-Backups einrichten
- Zugriff über Firewall einschränken

Beispiel mit sicherem Passwort:

```sql
create user companytool with password '<sicheres-passwort>';
create database companytool owner companytool;
```

Dann `.env` anpassen:

```env
DATABASE_URL=postgres://companytool:<sicheres-passwort>@localhost:5432/companytool
BACKEND_BIND=127.0.0.1:8080
VITE_WS_URL=ws://localhost:8080/ws
```

## Backend starten

```bash
cargo run -p companytool-backend
```

Beim Start führt das Backend aktuell die Basistabelle für den Testdatensatz
automatisch aus und legt bei Bedarf einen ersten Datensatz an. Die SQLx-
Migrationen unter `backend/migrations/` werden beim Backend-Start automatisch
ausgeführt.

Health-Check:

```bash
curl http://127.0.0.1:8080/health
```

Erwartete Antwort:

```json
{"status":"ok"}
```

## Verschlüsselte Kommunikation testen

Backend in einem Terminal starten:

```bash
cargo run -p companytool-backend
```

In einem zweiten Terminal:

```bash
node scripts/communication-test.mjs
```

Der Test prüft:

- zwei echte WebSocket-Clients
- `hello`/`hello_ack`-Handshake
- eigener AES-256-GCM-Session-Key pro Client
- verschlüsselter Snapshot vom Backend
- verschlüsselte `subscribe`- und `ping`-Nachrichten
- verschlüsseltes `pong`-Event an beide Clients
- keine fachlichen Klartextmarker in den Rohframes

Erwartetes Ergebnis:

```text
client-a handshake, encrypted snapshot and subscribe ok
client-b handshake, encrypted snapshot and subscribe ok
encrypted multi-client communication test ok
```

## Onboarding-API testen

Mit laufendem Backend:

```bash
node scripts/api-onboarding-test.mjs http://127.0.0.1:8080
```

Der Test legt eine Organization-Registrierung an, lädt Liste und Detail,
schaltet die Organization frei, testet den Login mit Initialpasswort, speichert
Firmendaten, prüft Rechte-Negativfälle, lädt einen weiteren User ein und prüft
die Rechteänderung.

## Schema-Migration testen

Mit laufendem Backend und PostgreSQL:

```bash
node scripts/schema-migration-test.mjs http://127.0.0.1:8080
```

Der Test legt eine Firma an, führt die Mandantenschema-Provisionierung erneut
aus und prüft, dass Nummernkreise, Rollen und spätere Tabellen wie
Kommunikation weiterhin funktionieren. Dadurch werden idempotente
Mandantenmigrationen früh erkannt.

## Live-Events testen

Mit laufendem Backend und PostgreSQL kann der Kommunikationstest zusätzlich
eine fachliche Änderung über die REST-API auslösen:

```bash
node scripts/communication-test.mjs ws://127.0.0.1:8080/ws http://127.0.0.1:8080
```

Der Test prüft dann neben Handshake, Verschlüsselung und Ping/Pong auch, dass
eine neu angelegte Aktivität als verschlüsseltes `record_changed`-Event bei
zwei verbundenen Clients ankommt.

## Standardcheck

Der Standardcheck bündelt die schnellen Prüfungen ohne laufendes Backend:

```bash
bash scripts/standard-check.sh
```

Enthalten sind:

- Rust-Formatprüfung
- `cargo check --workspace`
- Headless-Unit-Tests des Desktopclients
- Syntaxprüfung der Node-Testskripte
- Webfrontend-Build inklusive Vue/TypeScript-Prüfung

## Lokale Testdaten anlegen

Mit laufendem Backend kann ein reproduzierbarer Entwicklungsdatensatz erzeugt
werden:

```bash
node scripts/dev-seed.mjs http://127.0.0.1:8080
```

Das Skript nutzt den Dev-Bootstrap, legt eine Firma, einen Admin-Zugang,
Skonto, Kunde, Lieferant, Artikel und Aktivität an und gibt die Zugangsdaten
als JSON aus. Der Endpunkt ist nur im Entwicklungsbetrieb vorgesehen.

## Kommunikation ohne PostgreSQL testen

Falls PostgreSQL noch nicht eingerichtet ist, kann nur die
Kommunikationsschicht getestet werden.

Terminal 1:

```bash
COMMUNICATION_TEST_MODE=1 cargo run -p companytool-backend
```

Terminal 2:

```bash
node scripts/communication-test.mjs
```

Dieser Modus ist nur für Entwicklung und Tests gedacht.

## Webfrontend starten

```bash
cd web-frontend
npm install
npm run dev
```

Standard-URL:

```text
http://localhost:5175/
```

Im Entwicklungsbetrieb leitet Vite `/api` und `/ws` standardmäßig an
`http://127.0.0.1:8080` weiter. Wenn das Backend auf einem anderen Port läuft,
wird die Zieladresse so gesetzt:

```bash
VITE_BACKEND_ORIGIN=http://127.0.0.1:18084 npm run dev
```

### Lokalen Testzugang ohne E-Mail anlegen

Im Entwicklungsbuild ist auf der Login-Seite ein Dev-Bootstrap verfügbar. Damit
wird eine lokale Testfirma mit erstem User angelegt. Das Initialpasswort wird
direkt in der Oberfläche angezeigt, weil auf Entwicklungsrechnern kein
E-Mail-Versand vorausgesetzt wird.

Alternativ per API:

```bash
curl -s -X POST http://127.0.0.1:8080/api/v1/dev/bootstrap-local \
  -H 'Content-Type: application/json' \
  -d '{"organization_name":"Lokale Testfirma","email":"admin@example.test"}'
```

Produktiv ist dieser Endpunkt nicht vorgesehen. Er ist nur im Debug-Build oder
mit `COMPANYTOOL_DEV_MODE=1` aktiv.

## Desktopclient starten

Der native Client liest seine Server-Konfiguration aus:

```text
desktop-client/companytool-client.toml
```

Minimaler Inhalt:

```toml
[server]
api_base_url = "http://localhost:8080"
ws_url = "ws://localhost:8080/ws"
```

API- und WebSocket-URL können überschrieben werden:

```bash
cargo run -p companytool-desktop-client -- --api-url http://127.0.0.1:8080 --ws-url ws://127.0.0.1:8080/ws
```

Oder mit expliziter Config-Datei:

```bash
cargo run -p companytool-desktop-client -- --config /pfad/companytool-client.toml
```

Alternativ per Umgebungsvariablen:

```bash
COMPANYTOOL_CLIENT_CONFIG=/pfad/companytool-client.toml cargo run -p companytool-desktop-client
COMPANYTOOL_API_BASE_URL=http://127.0.0.1:8080 cargo run -p companytool-desktop-client
COMPANYTOOL_WS_URL=ws://127.0.0.1:8080/ws cargo run -p companytool-desktop-client
```

Start mit Standardkonfiguration:

```bash
cargo run -p companytool-desktop-client
```

## Nativen Client testen

Der native Client hat Headless-Tests. Dabei wird kein Fenster geöffnet.

### Kommunikation

Backend starten:

```bash
COMMUNICATION_TEST_MODE=1 cargo run -p companytool-backend
```

Test ausführen:

```bash
cargo run -p companytool-desktop-client -- --communication-test
```

Optional gegen eine andere WebSocket-URL oder Config-Datei:

```bash
cargo run -p companytool-desktop-client -- --communication-test --ws-url ws://127.0.0.1:18081/ws
cargo run -p companytool-desktop-client -- --communication-test --config /pfad/companytool-client.toml
```

Erwartetes Ergebnis:

```text
native client communication test ok
```

### Registrierung

Für den Registrierungstest muss das Backend mit PostgreSQL laufen:

```bash
cargo run -p companytool-backend
```

Test ausführen:

```bash
cargo run -p companytool-desktop-client -- --registration-test --api-url http://127.0.0.1:8080
```

Optional können Firmenname und E-Mail gesetzt werden:

```bash
cargo run -p companytool-desktop-client -- --registration-test --api-url http://127.0.0.1:8080 --organization-name "Beispiel GmbH" --email admin@example.org
```

Erwartetes Ergebnis:

```text
native client registration test ok
```

## Hinweise für Organisations-Installationen

Für Installationen bei Organisationen gelten zusätzlich:

- produktiv nur HTTPS/WSS verwenden
- PostgreSQL-Passwort individuell vergeben
- `.env` nicht an Dritte weitergeben
- regelmäßige Datenbank-Backups einrichten
- Zugriff auf PostgreSQL nicht öffentlich freigeben
- Backend hinter Reverse Proxy betreiben
- Zertifikate für lokale oder öffentliche Nutzung sauber einrichten
- spätere Versionen werden genau eine Organisation pro lokaler Installation
  unterstützen

## Fehlerbehebung

PostgreSQL nicht erreichbar:

```bash
pg_isready -h localhost -p 5432
```

Backend kann Datenbank nicht öffnen:

- `DATABASE_URL` in `.env` prüfen
- PostgreSQL-Dienst prüfen
- Benutzer, Passwort und Datenbanknamen prüfen

Port bereits belegt:

```bash
BACKEND_BIND=127.0.0.1:18080 cargo run -p companytool-backend
node scripts/communication-test.mjs ws://127.0.0.1:18080/ws
```