commit 03932a48ea77be837beb7b65dd9b11baeaa98d8c Author: Erik Date: Sun Jun 14 20:39:54 2026 +0200 Initiale README: Sinn, Zweck, Funktionen und API-Zugang der Bauakte Co-Authored-By: Claude Opus 4.8 (1M context) diff --git a/README.md b/README.md new file mode 100644 index 0000000..8791c43 --- /dev/null +++ b/README.md @@ -0,0 +1,173 @@ +# Bauakte + +Die **digitale Bauakte** des VLN Managers — ein webbasiertes Dokumentenmanagement, das +Projektbeteiligten gesicherten Zugriff auf Bauunterlagen, Pläne und Fotos je Maßnahme bzw. +Verfahren gibt. + +- **Web:** (Aufruf je Akte über einen individuellen Zugangscode) +- **API:** (siehe [API-Zugang](#api-zugang)) + +--- + +## Sinn und Zweck + +In einem Flurneuordnungs- bzw. Baumaßnahmen-Verfahren entstehen über die gesamte Laufzeit +Pläne, Gutachten, Verträge, Stellungnahmen und Fotos. Diese Unterlagen müssen für sehr +unterschiedliche Beteiligte verfügbar sein — den Verband, die Teilnehmergemeinschaften (TG) +sowie externe Firmen und Behörden — ohne dass dabei jeder alles sehen oder verändern darf. + +Die Bauakte bündelt diese Unterlagen je Maßnahme an einem Ort und stellt sicher, dass + +- alle Beteiligten **denselben, aktuellen Stand** sehen, +- jeder nur **die für ihn freigegebenen** Inhalte erreicht, +- Beiträge von außen **kontrolliert** in die Akte gelangen (Freigabe-Workflow), +- Geodaten und Baustellenfotos **direkt im Browser** sichtbar werden — ohne Spezialsoftware. + +Damit ersetzt die Bauakte verstreute E-Mail-Anhänge, Netzlaufwerke und manuelle +Dateiweitergabe durch eine nachvollziehbare, rollenbasierte Ablage. + +--- + +## Funktionen + +### Dateiverwaltung & Vorschau +- Strukturierte Ablage in einem **Ordnerbaum** je Akte; Anlegen, Umbenennen und Löschen von + Ordnern und Dateien (für berechtigte Nutzer). +- **Vorschau im Browser** für PDF und Bilder. +- **Geo-Vorschau** für gängige Geodaten-Formate (u. a. DXF/DWG, GeoTIFF, GeoJSON, KML, GPX, + GPKG) — einzeln oder mehrere Dateien gemeinsam als Karte mit Übernahme von Farben und Stilen + aus der Datei. +- **Download** einzelner Dateien sowie **ZIP-Export** ganzer Ordner. + +### Upload mit Freigabe-Workflow +- Mehrfach-Upload per Drag-and-Drop. +- Beiträge von Beteiligten, die nicht zum Verband gehören, landen zunächst in einer + **Freigabe-Warteschlange** und werden erst nach Prüfung durch die verantwortliche Person in + der Akte sichtbar. So bleibt der Aktenbestand kuratiert. + +### Baustellenfotos +- Aufnahme bzw. Upload von **georeferenzierten Baustellenfotos** (Standort aus Live-GPS oder aus + den Bilddaten), die anschließend verortet auf der Karte erscheinen. + +### Verteiler & externer Portalzugang +- Je Akte lassen sich **Verteiler** (Kontakte mit Anrede und Funktion) pflegen. +- Externe Beteiligte erhalten über **zeitlich befristete, passwortgeschützte Zugangslinks** + Zugriff auf ausgewählte Ordner — ohne eigenes Benutzerkonto. +- **Verteilerlisten** gruppieren Kontakte und benachrichtigen sie automatisch per E-Mail, wenn + neue Unterlagen hochgeladen werden. + +### Träger öffentlicher Belange (TÖB) +- Eigener Upload-Modus für **TÖB-Stellungnahmen**, die automatisch in einer geordneten + Ordnerstruktur abgelegt werden. +- Ermittlung der **räumlich zuständigen Träger** anhand des Verfahrensgebiets (und ergänzend der + Foto-Standorte). + +### Cloud-Synchronisation +- Eine Akte kann optional mit einem Cloud-Ordner gespiegelt werden, sodass Unterlagen auch über + die gewohnte Dateiablage bearbeitet werden können. Änderungen werden in **beide Richtungen** + abgeglichen. + +--- + +## Zugriff & Rollen + +Der Zugriff ist rollenbasiert; sichtbar ist jeweils nur, was der jeweiligen Rolle zusteht: + +| Rolle | Zugang | Upload | +|-------|--------|--------| +| **Verband** | alle Akten, volle Bearbeitung | direkt in die Ablage | +| **Teilnehmergemeinschaft (TG)** | nur die eigenen Akten | über den Freigabe-Workflow | +| **Externe (Firma/Behörde)** | nur freigegebene Ordner per Zugangslink | nur falls ausdrücklich erlaubt | + +--- + +## API-Zugang + +Die Bauakte ist Teil des VLN Managers und über dessen **v2-REST-API** ansprechbar. Damit lassen +sich Akten, Ordner, Dateien und Fotos programmatisch lesen und befüllen — z. B. aus den +Office-Add-ins oder eigenen Werkzeugen. + +- **Basis-URL:** `https://api.flurneuordnung-sachsen.de/v2` +- **Spezifikation (OpenAPI 3.0):** `GET /v2/openapi` +- **Status:** `GET /v2/health` + +### Authentifizierung + +Geschützte Endpunkte erwarten eines der folgenden Verfahren: + +| Schema | Ort | Wert | +|--------|-----|------| +| `X-API-Key` | Header | API-Key | +| `X-UserAuth` | Header | persönliches Zugriffs-Token | +| `userauth` | Query-Parameter | persönliches Zugriffs-Token | + +- **Login:** `POST /v2/person/login` mit `{ "mail": "…", "password": "…" }` → liefert das + persönliche Token. +- Das eigene Token kann zusätzlich über `GET /v2/config/client` abgerufen werden. + +Die Sichtbarkeit der Akten richtet sich nach dem angemeldeten Nutzer: Der Verband sieht alle +Akten, andere Rollen nur ihre eigenen. + +### Bauakten lesen *(read-only)* + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `GET` | `/bauakten` | Sichtbare Bauakten auflisten | +| `GET` | `/bauakten/{id}` | Detail einer Akte (mit zugehörigen Maßnahmen) | +| `GET` | `/bauakten/{id}/folders` | Ordnerbaum der Akte | +| `GET` | `/bauakten/{id}/files` | Dateien eines Ordners (paginiert) | +| `GET` | `/bauakten/{id}/inbox` | Offene Einträge der Freigabe-Warteschlange | +| `GET` | `/bauakten/{id}/verteiler` | Verteiler-Kontakte und -Listen | +| `GET` | `/bauakten/{id}/toeb-relevant` | Räumlich zuständige TÖB-Stellen | + +### Dateien hoch- und herunterladen + +Das Hoch- und Herunterladen läuft über die generische Dateiverwaltung der API: + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `POST` | `/dateisystem/file/upload` | Datei(en) hochladen (`multipart/form-data`) | +| `GET` | `/dateisystem/file/{uuid}/download` | Datei streamen (`?redirect=1` → 302) | +| `POST` | `/dateisystem/file/{uuid}/rename` | Umbenennen | +| `DELETE` | `/dateisystem/file/{uuid}` | Datei löschen | + +### Baustellenfotos + +Georeferenzierte Fotos je Akte; abgesichert über den jeweiligen Zugangscode der Akte: + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `GET` | `/maps/bauakte?code=…` | Kopfdaten der Akte (Name, Status) | +| `GET` | `/maps/bauakte-fotos?code=…` | Fotos als GeoJSON-FeatureCollection | +| `GET` | `/maps/bauakte-foto/{id}?code=…&size=thumb\|full` | Bilddatei ausliefern | +| `POST` | `/maps/bauakte-foto` | Foto hochladen (`multipart`, optional `lat`/`lon`/`heading`) | + +### Beispiel + +```bash +# 1) Anmelden und Token merken +TOKEN=$(curl -s https://api.flurneuordnung-sachsen.de/v2/person/login \ + -H 'Content-Type: application/json' \ + -d '{"mail":"name@vlnsachsen.de","password":"…"}' \ + | jq -r '.data.userauth') + +# 2) Sichtbare Bauakten auflisten +curl -s https://api.flurneuordnung-sachsen.de/v2/bauakten \ + -H "X-UserAuth: $TOKEN" + +# 3) Ordnerbaum einer Akte abrufen +curl -s https://api.flurneuordnung-sachsen.de/v2/bauakten/{id}/folders \ + -H "X-UserAuth: $TOKEN" +``` + +**Antwort-Konventionen:** Nutzdaten stecken meist in einer Hülle `{ "data": … }`; Fehler werden +nach RFC 7807 als `application/problem+json` zurückgegeben. + +--- + +## Verwandte Module + +Die Bauakte arbeitet mit weiteren Modulen des VLN Managers zusammen — u. a. mit den **Maßnahmen** +(jede Akte ist mit Maßnahmen verknüpft), dem **Web-GIS** (Verfahrensgebiete, Foto-Verortung), +den **Servicetermin-Werkzeugen** und der **Cloud-Ablage**. Für die Ablage aus Microsoft Office +heraus existieren passende **Word-, Excel- und Outlook-Add-ins**.