feuerwehr-schadensmeldung/README.md

21 KiB

Feuerwehr Schadensmeldung

Fault management for technical equipment of a German fire brigade. Members report defects on devices (radios, breathing apparatus, vehicles, ...), the responsible unit tracks and resolves them, and a public dashboard in the equipment room shows everything that is currently broken.

The application consists of:

  • a Go backend with Gin, Gorm and swaggo API docs (backend)
  • a React + TypeScript frontend built with Vite (frontend)

The user interface is German; code and documentation are English.

Features

  • OIDC login with automatic user creation. Roles are derived from OIDC groups/emails on every login, the identity provider is the single source of truth for role management.
  • Faults with title, description, device, location, priority and status (open, in_progress, resolved), filtering, full-text search and history.
  • Assignees: while a fault is in progress, users (or yourself via "Mir zuweisen") can be assigned to it in the edit dialog. They stay visible on the resolved fault and are removed when it is set back to open. Only users who logged in at least once can be assigned. Users assigned by someone else are notified, see Notifications below.
  • Updates: while a fault is in progress, users post short progress messages ("Ersatzteil bestellt", "Wartet auf Werkstatt") in a chat-like thread in the edit and detail dialogs (GET/POST /api/v1/faults/{id}/updates). The thread stays readable after the fault is resolved.
  • Responsibilities ("Verantwortlichkeiten", called fault types in the API), seeded with IUK, Gerätewart and Atemschutz. Each can be restricted to OIDC groups, see below.
  • Locations (vehicles, rooms, ...) selectable from a dropdown, managed in the admin UI.
  • Reparaturschein: an A4 PDF for an external repair service with the device (name, manufacturer, type, serial and inventory number, barcode and, from MP-Feuer, production year and date in service), the fault details, a free text and fields for the repair service to fill in. Created from an open fault and opened in a new browser tab (POST /api/v1/faults/{id}/repair-order).
  • Public dashboards (kiosk mode) registered once by an admin with a short registration code: show all open faults, report new faults, resolve faults and browse the history without a personal login.
  • AI assistant and summaries via any OpenAI compatible API such as Ollama or OpenWebUI (optional), see AI integration below.
  • Per user default filter for the overview (fault type, location, priority, status), set in the settings.
  • Personal API tokens for integrations, Swagger UI at /api/docs/index.html.
  • Light/dark mode, responsive layout, installable PWA: starts offline from the cached app shell, shortcuts for "Neue Meldung" and "Historie", and a notice when a new version is available (public dashboards update automatically).
  • URL routing: every view has its own address, filters and page are kept in the query string, so links can be shared and the back button works:
    Path Content
    / open faults, e.g. /?prioritaet=high&standort=3&seite=2
    /meldungen/neu new fault dialog, ?barcode=ag002 prefills the barcode (e.g. for QR codes on devices)
    /meldungen/<id> a single fault, linked from the notification mails
    /historie resolved faults, same filter parameters
    /assistent AI assistant (only if the AI integration is enabled)
    /einstellungen settings
    /admin/<tab> verantwortlichkeiten, standorte, dashboards, benutzer, branding, ki

Roles

Role Granted by Permissions
admin OIDC_ADMIN_GROUPS or OIDC_ADMIN_EMAILS everything, incl. fault types, locations, dashboards, users, branding, deleting faults
user any other authenticated user (optionally restricted by OIDC_USER_GROUPS) report, edit, resolve and reopen faults

The role is re-evaluated on every login, so removing a user from the admin group in the identity provider downgrades them on their next login. There is no manual role assignment in the application. If OIDC_USER_GROUPS is set, users that are neither in one of these groups nor admins are rejected at login.

Responsibilities and OIDC groups

Admins can assign OIDC groups to a responsibility under Admin → Verantwortlichkeiten.

  • No groups: the history of this responsibility is visible to everyone, no mails are sent.
  • With groups: resolved faults of this responsibility are only visible to members of one of the groups and to admins. Open faults stay visible to everyone.
  • Notification: when a new fault is reported for a responsibility with groups, every member is notified (except the reporter), see Notifications below.

Group memberships are taken from the OIDC claims and stored on every login. Users who never logged in are unknown to the application and therefore receive no mails; a membership change in the identity provider takes effect on the user's next login.

Public dashboards show the history of unrestricted responsibilities. The history of restricted ones has to be enabled per dashboard under Admin → Dashboards → Bearbeiten.

Notifications

Users are notified about new faults of their responsibilities and about faults assigned to them by someone else. Under Einstellungen → Benachrichtigungen every user chooses per notification type which transports to use; all are enabled by default.

  • E-Mail requires the SMTP_* settings.
  • Push (Web Push) works without external services. The user enables it per device under Push-Geräte; clicking a notification opens the fault. On iPhone/iPad the app has to be added to the home screen first. Browsers only offer push on HTTPS (or localhost) and the service worker is only active in production builds, so test it with yarn build && yarn preview instead of yarn dev. A VAPID key pair is generated on first use and stored in the database, so all replicas share it. Set VAPID_PUBLIC_KEY/VAPID_PRIVATE_KEY to provide your own; changing the keys invalidates all existing push subscriptions.

MP-Feuer hand-over

If a MP-Feuer database is configured (MPFEUER_DB_*), logged-in users can tick "An MP-Feuer übergeben" when finishing a fault. The fault's barcode is looked up in <PREFIX>_STAMM.<PREFIX>_BARCODE_NR and <PREFIX>_BARCODE_NR2 of all prefixes (GAS, GEL, GFU, GHR, GMP, GSL, GSO, KLD); exactly one device must match. The dialog shows the device before the user confirms. A new row is then inserted into <PREFIX>_MANGEL:

Column Value
_ID new GUID of the defect
_INDEX device GUID (<PREFIX>_STAMM.<PREFIX>_ID)
_MANGEL_ZEIT, _CREATED_TS creation time of the fault
_MANGEL_ERFASSER name of the reporter
_MANGEL_ERFASSER_HDZ, _CREATED_HDZ MPFEUER_HANDZEICHEN (default SM)
_MANGEL_ERLAEUTERUNG fault title
_MANGEL_LANG description (MP-Feuer limits it to 50 characters)
_MANGEL_PRIORITAET 1 for priority "Hoch"
_INFOTEXT details without an own column (report number, low/medium priority, resolver name, Maßnahme); reporter and description only when they do not fit their column
_UPDATED_TS time the fault was finished
_UPDATED_HDZ, _MANGEL_HDZ the user's "MP-Feuer Handzeichen" (settings), falls back to MPFEUER_HANDZEICHEN
_MANGEL_OK 1, the defect is recorded as done
_MANGEL_STATUS Erledigt
_MANGEL_TERMIN date the fault was finished

All other columns keep their defaults. MP-Feuer's timestamp triggers would overwrite the CREATED_/UPDATED_ columns with the current MP-Feuer user, so the insert runs in MP-Feuer's transfer mode (SYS_SET_TRANSFER_MODE) for its own session. Texts are truncated to the column lengths. The hand-over happens before the fault is resolved: if it fails, the fault stays open and the error is shown. The created reference is stored on the fault and shown in the history.

When a barcode is entered or scanned while reporting a fault (app and public dashboard), it is looked up in MP-Feuer and empty fields are prefilled: Gerät from the device name (or manufacturer and type), number and call sign, and Standort from the mapping below.

Standort mapping

Under Admin → Standorte → MP-Feuer zuordnen admins search MP-Feuer and map entities to a Standort. Each entity can only be mapped to one Standort:

Kind Source in MP-Feuer Matches a device when
Fahrzeug / Zuteilung vehicles (FZG_STAMM) and assignment targets used by devices _ZUTEIL_KEY equals the entity GUID
Standort-Text distinct _STANDORT values of devices and vehicles _STANDORT equals the text (case-insensitive)
Abteilung ABT_STAMM _ABT_INDEX equals the department GUID

The most specific mapping wins (Zuteilung, then Standort-Text, then Abteilung); inactive Standorte are ignored. Without a mapping, a Standort whose name equals the assignment name or location text is used.

To verify a configuration without writing anything, run the dry run, which inserts and rolls back:

cd backend && MPFEUER_DRYRUN=1 go test ./internal/mpfeuer/ -run DryRun -v

Public dashboards

  1. An admin opens Admin → Dashboards and creates a dashboard (e.g. "Tablet Fahrzeughalle").
  2. A short registration code (e.g. K7QF-2M9X) is shown once. It is valid for 24 hours and can be redeemed exactly once.
  3. On the dashboard device, open /dashboard and enter the code (case and dash are ignored). The device receives the real secret (db_...) in exchange, which is stored in the browser's local storage and sent as X-Dashboard-Token header. Wrong codes are rate limited.
  4. The dashboard refreshes automatically every 30 seconds. People reporting or resolving a fault on the dashboard enter their name, which is stored with the fault.

Admins can disable a dashboard, rotate its secret or delete it; the device loses access immediately. Only a SHA-256 hash of the secret is stored in the database.

MCP server

The user features are available to AI assistants as a Model Context Protocol server (streamable HTTP, stateless) at /api/v1/mcp. It is enabled whenever OIDC is configured.

  • Authentication: the backend is its own OAuth 2.1 authorization server for MCP clients (dynamic client registration, authorization code grant with PKCE S256, refresh tokens) and signs the user in at the configured OpenID provider. MCP clients need no client at the identity provider; the existing OIDC_REDIRECT_URL callback is reused, so nothing else has to be registered there.
    1. An unauthenticated request gets 401 with a pointer to /api/v1/mcp-metadata (RFC 9728), which names this server (/api/v1/oauth) as authorization server (RFC 8414 metadata is served below /api/v1/oauth/.well-known/ and at /.well-known/; the Helm ingress forwards these via ingress.wellKnownPaths).
    2. The client registers itself at /api/v1/oauth/register and sends the user to /api/v1/oauth/authorize. The user first confirms the client, then signs in at the OIDC provider. Role and groups are mapped exactly like for a browser login (OIDC_ADMIN_GROUPS, OIDC_USER_GROUPS).
    3. The client exchanges the code at /api/v1/oauth/token for an access token (default 1 hour) and a refresh token (default 30 days), both issued by this server and stored hashed in the database. Deleting a user revokes their tokens.
  • Configuration: set APP_URL so the metadata contains the public URL. Optional lifetimes: MCP_OAUTH_AUTH_CODE_TTL_SECONDS (300), MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS (3600), MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS (2592000).
  • Tools: get_me, get_my_groups, get_catalog, list_users, get_fault_summary, list_open_faults, list_fault_history, get_fault, list_fault_updates, add_fault_update, report_fault, update_fault, resolve_fault, reopen_fault, lookup_mp_feuer_device, create_repair_order (PDF), update_preferences. Admin features (deleting faults, administration) are not exposed.
  • Tools call the regular REST API in-process as the signed-in user, so visibility rules, notifications and the MP-Feuer hand-over behave exactly like in the web app. MCP tokens are not accepted by the REST API itself.

AI integration

The application can use any OpenAI compatible API; /chat/completions and /models are appended to the configured API URL. An admin configures it under Admin → KI: API URL, optional API key and model. "Verbindung testen & Modelle laden" lists the available models. Examples for the API URL:

Server API URL API key
Ollama http://ollama:11434/v1 not needed
OpenWebUI https://openwebui.example.org/api Settings → Account
OpenAI https://api.openai.com/v1 required

The settings are stored in the database; the API key is never sent back to the browser. Each feature below can be switched off on its own. "Denkmodus deaktivieren" sends "reasoning_effort": "none" (understood by Ollama's /v1 API), "think": false and adds /no_think (Qwen3) to the system prompt, which makes reasoning models like Gemma 4 or Qwen3 answer much faster; leading thinking blocks (<think>…</think>, Gemma 4's <|channel>thought…<channel|>) are always removed from answers. Strict servers like OpenAI may reject these parameters, so only enable it for Ollama or OpenWebUI. When enabled:

  • KI-Assistent (/assistent, POST /api/v1/ai/chat): a chat about the faults. The model gets the read-only tools of the MCP server (get_catalog, list_open_faults, list_fault_history, get_fault, ...), which call the REST API in-process as the signed-in user, so it sees exactly what the user may see. It cannot report, change or resolve faults; tool calls for anything else are refused. The model should support function calling. The conversation is kept in the browser tab only.
  • KI-Zusammenfassung: a situation report of all open faults on the overview (POST /api/v1/ai/summary) and a summary of a single fault in its dialog (POST /api/v1/ai/faults/{id}/summary). Summaries are only created on request.
  • Abschlussvermerk: when closing a fault, "Mit KI aus den Updates erstellen" drafts the note "Was wurde gemacht?" from the fault and its updates; text already typed is used as draft (POST /api/v1/ai/faults/{id}/resolution-note). The suggestion stays editable and nothing is saved until the user resolves the fault.

Answers are streamed to the browser as server-sent events (Accept: text/event-stream, see backend/api/airoutes), so text appears while the model writes; without that header the endpoints answer with JSON. Tool results are compacted (no colors, empty fields or seconds) and the system prompt only contains the date, so local servers like Ollama can reuse their prompt cache between requests. A reverse proxy must not buffer these responses; the backend sends X-Accel-Buffering: no, which nginx and ingress-nginx respect.

Fault data (titles, descriptions, names of reporters and assignees) is sent to the configured AI server (and, for OpenWebUI, to the model provider configured there).

Backend structure

backend/
├── main.go                 entry point and swagger annotations
├── database/               gorm connection, models, default seed data, legacy migrations
├── docs/                   generated swagger docs (swag init --parseInternal)
├── internal/
│   ├── auth/               OIDC (go-oidc + PKCE), sessions, role mapping, middleware
│   ├── faults/             fault listing, creation, resolution (shared by user and dashboard API)
│   ├── dto/                API request/response types
│   ├── repairorder/        "Reparaturschein" PDF (go-pdf/fpdf)
│   ├── ai/                 OpenAI compatible client (Ollama, OpenWebUI, ...) and settings
│   └── appsettings/        branding
└── api/
    ├── webserver.go, routes.go
    ├── apiutil/            shared handler helpers
    ├── authroutes/         /api/v1/auth/*
    ├── catalogroutes/      /api/v1/catalog (locations and fault types)
    ├── faultroutes/        /api/v1/faults/*
    ├── meroutes/           /api/v1/me/* (API tokens)
    ├── adminroutes/        /api/v1/admin/*
    ├── mcproutes/          /api/v1/mcp (MCP server, tools call the REST API in-process)
    ├── airoutes/           /api/v1/ai/* (chat and summaries using the read-only MCP tools)
    ├── dashboardroutes/    /api/v1/dashboard/* (public dashboards)
    ├── generalroutes/      health checks
    └── staticroutes/       serves frontend/dist if present

Sessions are stored server side (only the SHA-256 hash of the cookie value is persisted), as is the short-lived OIDC login state, so multiple backend replicas work without sticky sessions.

Requirements

  • Go 1.27
  • Node.js 22+
  • Yarn 1.x

Local setup

cp backend/.env.example backend/.env   # then adjust the OIDC settings
cd backend && go run .                 # http://localhost:8080
cd frontend && yarn install && yarn dev  # http://localhost:5173

The Vite dev server proxies /api/* to http://localhost:8080 (override with VITE_API_PROXY_TARGET). Register http://localhost:5173/api/v1/auth/callback as redirect URI at your identity provider (or set OIDC_REDIRECT_URL).

Configuration

All configuration is done via environment variables (a .env file in backend/ is loaded automatically).

Variable Default Description
DB_DRIVER sqlite sqlite, mysql, postgres or mssql
DB_NAME ./database.db database name or sqlite file
DB_HOST, DB_PORT, DB_USER, DB_PASSWORD connection for mysql/postgres/mssql
DB_SSLMODE, DB_TIMEZONE disable, Local postgres only
DB_ENCRYPT, DB_TRUST_SERVER_CERTIFICATE disable, true mssql only
EXECUTE_MIGRATIONS true run auto migrations and seed defaults on startup
OIDC_ISSUER_URL, OIDC_CLIENT_ID required for login
OIDC_CLIENT_SECRET client secret (confidential clients)
OIDC_REDIRECT_URL derived from request callback URL, /api/v1/auth/callback
OIDC_EXTRA_SCOPES additional scopes, e.g. groups
OIDC_GROUPS_CLAIM groups claim containing the group list
OIDC_ADMIN_GROUPS comma separated groups granting admin (exact match)
OIDC_ADMIN_EMAILS comma separated emails granting admin
OIDC_USER_GROUPS if set, only these groups (and admins) may log in
SESSION_LIFETIME_HOURS 12 session lifetime
COOKIE_SECURE false set true when served via HTTPS
TRUSTED_PROXIES none comma separated proxy CIDRs for client IP detection
PORT 8080 listen port
SMTP_HOST SMTP server, mails are disabled if empty
SMTP_PORT 587 (465 for tls) SMTP port
SMTP_SECURITY starttls starttls, tls (implicit TLS) or none
SMTP_USERNAME, SMTP_PASSWORD SMTP login (PLAIN auth)
SMTP_FROM SMTP_USERNAME sender, e.g. Schadensmeldung <noreply@example.org>
WEBPUSH_ENABLED true set false to disable push notifications
VAPID_SUBJECT SMTP_FROM address or APP_URL contact (mailto: or https: URL) sent to push services
VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY generated VAPID key pair for Web Push
MPFEUER_DB_HOST MP-Feuer SQL Server, hand-over is disabled if empty
MPFEUER_DB_PORT 1433 SQL Server port
MPFEUER_DB_NAME mpfeuer database name
MPFEUER_DB_USER, MPFEUER_DB_PASSWORD SQL login
MPFEUER_DB_ENCRYPT, MPFEUER_DB_TRUST_SERVER_CERTIFICATE disable, true connection encryption
MPFEUER_DB_SCHEMA dbo schema of the MP-Feuer tables
MPFEUER_PREFIXES GAS,GEL,GFU,GHR,GMP,GSL,GSO,KLD device table prefixes searched for barcodes
MPFEUER_HANDZEICHEN SM Handzeichen of this application in MP-Feuer
APP_URL public URL used for links in mails, e.g. https://schaden.example.org
FRONTEND_DIST_DIR ../frontend/dist serve a built frontend from the backend

Groups are read from both the ID token and the userinfo endpoint. The resolved groups are logged on every login, which helps to find the exact values for OIDC_ADMIN_GROUPS.

Development

cd backend && go test ./...          # unit and API integration tests (sqlite)
cd backend && swag init --parseInternal   # regenerate swagger docs after changing annotations
cd frontend && yarn typecheck && yarn build

Deployment

  • Dockerfile.backend builds the backend binary into a scratch image.
  • Dockerfile.frontend builds the SPA and serves it with nginx (container/nginx.conf).
  • The Helm chart in helm deploys both, routes /api to the backend via ingress and optionally deploys MariaDB.