Initiale README: Sinn, Zweck, Funktionen und API-Zugang der Bauakte

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 20:39:54 +02:00
commit 03932a48ea
1 changed files with 173 additions and 0 deletions
@@ -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:** <https://bauakte.vlnsachsen.de> (Aufruf je Akte über einen individuellen Zugangscode)
+- **API:** <https://api.flurneuordnung-sachsen.de/v2> (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**.