generated from coulomb/repo-seed
init: documentation and prototypes
This commit is contained in:
290
docs/251201-architektur-direktVermittlungDe.txt
Normal file
290
docs/251201-architektur-direktVermittlungDe.txt
Normal file
@@ -0,0 +1,290 @@
|
||||
DvdArchitektur
|
||||
|
||||
Architektur Dokument für Direkt Vermittlung Deutschland
|
||||
|
||||
# Direkt Vermittlung Deutschland Architektur
|
||||
|
||||
## 1. Functional Requirements
|
||||
|
||||
**Description: Core features and user stories**
|
||||
|
||||
### 1.1 Kernfunktionen (auf Beleg fokussiert)
|
||||
|
||||
**FR-1 – Schreiben erfassen (Document Intake)**
|
||||
|
||||
* Bürger:innen können ein behördliches Schreiben als PDF hochladen oder via Kamera erfassen.
|
||||
* Alternativ: Eingabe eines eindeutigen Merkmals (z. B. Aktenzeichen/Kassenzeichen + Behörde).
|
||||
* Das System erzeugt einen **DocumentEnvelope** inkl. Metadaten (Aktenzeichen, Belegart, Datum, Absenderbehörde).
|
||||
|
||||
**FR-2 – Automatisches Routing zur zuständigen Stelle**
|
||||
|
||||
* Die Plattform verfügt über eine **Routing-Engine**, die anhand von Metadaten & Konfiguration
|
||||
|
||||
* die zuständige Behörde / Organisationseinheit
|
||||
* und idealerweise den zuständigen Sachbearbeiter ermittelt.
|
||||
* Fallback-Regeln (z. B. Standard-Team, Zentrale) greifen, wenn keine eindeutige Zuordnung möglich ist.
|
||||
|
||||
**FR-3 – Interaktionsstart zum Schreiben (Interaction Thread)**
|
||||
|
||||
* Bürger:innen können zu einem bestimmten Schreiben:
|
||||
|
||||
* eine Rückfrage stellen (Textnachricht),
|
||||
* einen Rückruf anfragen,
|
||||
* einen Direktanruf starten (sofern verfügbar),
|
||||
* einen Terminwunsch äußern.
|
||||
* Für jede solche Interaktion wird ein **InteractionThread** zum **DocumentEnvelope** angelegt.
|
||||
|
||||
**FR-4 – Kommunikation & Dokumentaustausch**
|
||||
|
||||
* Bürger und Behörde können in einem Thread:
|
||||
|
||||
* Nachrichten austauschen,
|
||||
* ergänzende Belege hochladen (z. B. Nachweise, Antworten),
|
||||
* interne Notizen (behördenintern, nicht für Bürger sichtbar) anlegen.
|
||||
* Alle Aktivitäten werden chronologisch protokolliert.
|
||||
|
||||
**FR-5 – Call-/Rückruf-/Termin-Orchestrierung**
|
||||
|
||||
* Das System unterstützt:
|
||||
|
||||
* Weitervermittlung bei eingehenden Anrufen anhand eines Merkmals,
|
||||
* Anlegen & Verwalten von Rückrufanforderungen,
|
||||
* optionale Terminvereinbarung (Kalenderintegration der Behörde).
|
||||
|
||||
**FR-6 – Temporäre Vorhaltung & persönliche Ablage**
|
||||
|
||||
* Standard: Daten (Schreiben, Threads, Dateien) werden nur bis zur Erledigung + definierter Inaktivitätsfrist gehalten und dann gelöscht.
|
||||
* Bürger und Behörde können optional eine **verlängerte Aufbewahrung** (persönliche Ablage) buchen/aktivieren.
|
||||
|
||||
**FR-7 – Datenexport an Behördensysteme**
|
||||
|
||||
* Behörden können Daten eines Vorgangs (Schreiben, Metadaten, Interaktionshistorie, Anhänge)
|
||||
|
||||
* in ihre eAkte / Fachverfahren exportieren (pull oder push).
|
||||
* Der Export ist konfigurierbar (welche Daten, welches Format).
|
||||
|
||||
---
|
||||
|
||||
### 1.2 User Stories (Beispiele)
|
||||
|
||||
* *Als Bürger* möchte ich ein behördliches Schreiben scannen oder hochladen können,
|
||||
damit ich ohne manuelle Zuständigkeitsrecherche direkt den richtigen Ansprechpartner erreiche.
|
||||
|
||||
* *Als Sachbearbeiterin* möchte ich alle offenen Vorgänge zu den Schreiben meiner Behörde in einer Liste sehen,
|
||||
damit ich Rückfragen gezielt bearbeiten und priorisieren kann.
|
||||
|
||||
* *Als Behördenadministrator* möchte ich Routingregeln konfigurieren (z. B. nach Aktenzeichenbereichen),
|
||||
damit Anfragen automatisiert der richtigen Organisationseinheit zugeordnet werden.
|
||||
|
||||
* *Als Bürger* möchte ich optional eine längerfristige digitale Ablage wichtiger Schreiben und Klärungsverläufe,
|
||||
damit ich später auf diese Informationen zugreifen kann.
|
||||
|
||||
**Why It Matters:**
|
||||
Diese Functional Requirements definieren klar, **was** DVD tut:
|
||||
|
||||
* Sie trennen sauber zwischen “Beleg”, “Interaktion” und “Routing” → gute Grundlage für REST-/API-Design.
|
||||
* Sie machen DVD bewusst **beleggesteuert** (nicht generische Kommunikation) und ermöglichen spätere Erweiterungen (z. B. KI-Extraktion, andere Kanäle), ohne das Kernmodell zu brechen.
|
||||
|
||||
---
|
||||
|
||||
## 2. Non-Functional Requirements
|
||||
|
||||
**Description: Performance, security, usability SLAs**
|
||||
|
||||
### 2.1 Performance & Skalierung
|
||||
|
||||
* **NFR-1:** 95. Perzentil der Antwortzeiten für Kernoperationen (Thread öffnen, Nachricht senden, Routing) < 300 ms bei normaler Last.
|
||||
* **NFR-2:** System unterstützt mindestens **10k gleichzeitige Sessions** (Behörden + Bürger) pro Region.
|
||||
* **NFR-3:** Routingentscheidungen werden in < 500 ms getroffen (inkl. Lookups).
|
||||
|
||||
### 2.2 Sicherheit & Datenschutz
|
||||
|
||||
* **NFR-4:** Vollständige **DSGVO-Konformität**, inkl.
|
||||
|
||||
* Recht auf Auskunft, Löschung, Berichtigung,
|
||||
* dokumentierte Retentions-Policies,
|
||||
* Privacy-by-Design & by-Default.
|
||||
* **NFR-5:** End-to-End-Verschlüsselung in Transport (TLS 1.2+) und Verschlüsselung sensibler Daten im Ruhezustand (z. B. Aktenzeichen, PDF-Dokumente).
|
||||
* **NFR-6:** Zugriff nur auf Basis rollenspezifischer Berechtigungen (least privilege, mandantensicher).
|
||||
|
||||
### 2.3 Verfügbarkeit & Resilienz
|
||||
|
||||
* **NFR-7:** Zielverfügbarkeit: ≥ 99,5 % im Jahresmittel.
|
||||
* **NFR-8:** Disaster-Recovery-Konzept mit RPO ≤ 15 min, RTO ≤ 4 h.
|
||||
|
||||
### 2.4 Usability
|
||||
|
||||
* **NFR-9:** Bürgeroberfläche barrierearm nach WCAG 2.1 AA-Orientierung.
|
||||
* **NFR-10:** Max. 3 Schritte vom Start bis zur gestellten Anfrage.
|
||||
|
||||
**Why:**
|
||||
Diese NFRs treiben Architekturentscheidungen:
|
||||
|
||||
* Asynchrone Verarbeitung, Caching & horizontale Skalierung werden notwendig.
|
||||
* Strikte IAM- & Verschlüsselungsschichten sind Pflicht in GovTech-Umgebungen.
|
||||
* Klare SLAs verhindern, dass “Prototyping-Architektur” im Produktivbetrieb kollabiert.
|
||||
|
||||
---
|
||||
|
||||
## 3. Business Context
|
||||
|
||||
**Description: Use cases, target audience, integrations**
|
||||
|
||||
### 3.1 Use Cases (Business-Sicht)
|
||||
|
||||
* Reduktion der durchschnittlichen **Telefonzeit pro Klärung** (z. B. von 30 auf 10 Minuten).
|
||||
* Entlastung von Telefonzentralen, Bündelung der Klärung direkt bei den Fachbereichen.
|
||||
* Schaffung eines digitalen Rückkanals zu behördlichen Schreiben, der nachvollziehbar und sicher ist.
|
||||
|
||||
### 3.2 Zielgruppen
|
||||
|
||||
* **Primäre Business-Kunden:**
|
||||
|
||||
* Kommunalverwaltungen, Gerichtskassen, Amtsgerichte, Landesbehörden, Finanzämter.
|
||||
* **Endnutzer:innen:**
|
||||
|
||||
* Bürger:innen (Privatpersonen, Unternehmen) mit Bescheiden / Schreiben.
|
||||
* **Sekundäre Stakeholder:**
|
||||
|
||||
* Kommunale/regionale IT-Dienstleister, Fachverfahrenshersteller.
|
||||
|
||||
### 3.3 Integrationskontext
|
||||
|
||||
* eAkte-Systeme der Behörden (unterstützt durch generische Exporte und custom Adapter).
|
||||
* Identity-Provider (z. B. BundID, eID, SAML/OIDC-basierte Behörden-Singlesignon).
|
||||
* TK-Anlagen / Callcenter-Software (für Direktvermittlung, Rückruflisten).
|
||||
* Optional: Dokumentenmanagement / Archivsysteme.
|
||||
|
||||
**Why:**
|
||||
Der Business-Kontext sorgt dafür, dass du die “Nomen” des Systems (DocumentEnvelope, InteractionThread, AuthorityUnit) passend zu realen Strukturen modellierst. Er verhindert, dass du eine “abstrakte Messaging-Plattform” baust, statt eines **belegzentrierten GovTech-Dienstes**.
|
||||
|
||||
---
|
||||
|
||||
## 4. Technical Constraints
|
||||
|
||||
**Description: Existing systems, tech stack, and standards**
|
||||
|
||||
*(Hier formuliere ich bewusst Vorschläge, die du später bestätigen/ändern kannst.)*
|
||||
|
||||
### 4.1 Architekturparadigmen
|
||||
|
||||
* **TC-1:** Service-orientierte / modularisierte Architektur mit klaren Bounded Contexts:
|
||||
|
||||
* Citizen & Channels,
|
||||
* Document & Interaction,
|
||||
* Routing & Org,
|
||||
* Integration & Export.
|
||||
* **TC-2:** Stateless APIs im Frontend-Layer, Session-Handling via Token (JWT/OAuth2), um horizontale Skalierung zu ermöglichen.
|
||||
|
||||
### 4.2 Tech Stack (Vorschlag / Beispiel)
|
||||
|
||||
* **Backend:** z. B. Java (Spring Boot) oder Go (stark in Gov-Umfeldern verbreitet), Node.js denkbar – Standard: REST-APIs, optional GraphQL.
|
||||
* **Datenbank:** Relationale DB (PostgreSQL) für Kernobjekte; Blob-Storage (z. B. S3-kompatibel) für PDF-Dokumente.
|
||||
* **Caching:** Redis für Sessions, Routing-Cache und häufige Lookups.
|
||||
* **Messaging:** Optionale Message-Bus/Queue (z. B. Kafka/RabbitMQ) für Export-Jobs, Notifications.
|
||||
|
||||
### 4.3 Standards & Schnittstellen
|
||||
|
||||
* **TC-3:** REST/JSON-APIs als Primärschnittstelle; sprechende Ressourcen (z. B. `/documents`, `/threads`, `/exports`).
|
||||
* **TC-4:** HTTPS/TLS verpflichtend, HSTS aktiviert.
|
||||
* **TC-5:** OpenAPI-Spezifikation für alle externen APIs (für Behörden & Integrationspartner).
|
||||
|
||||
**Why:**
|
||||
Diese Constraints helfen, früh falsche Technologieentscheidungen auszuschließen und das System **von Anfang an auf Skalierbarkeit & Interoperabilität** auszurichten. OpenAPI-First erleichtert LLM-gestützte Codegenerierung und Mock-APIs.
|
||||
|
||||
---
|
||||
|
||||
## 5. Stakeholder Feedback
|
||||
|
||||
**Description: Early input from consumers (e.g., devs using the API)**
|
||||
|
||||
### 5.1 Stakeholder-Gruppen für Feedback
|
||||
|
||||
* **Behörden-Fachseite:** Sachbearbeiter:innen und Fachbereichsleitungen
|
||||
|
||||
* Fokus: Usability, Prozesslogik, Zuständigkeitsmodell.
|
||||
* **Behörden-IT:** Architekt:innen, Admins, Datenschutzbeauftragte
|
||||
|
||||
* Fokus: Integrationsfähigkeit, Sicherheit, Betriebsmodell.
|
||||
* **Bürgerperspektive:** Pilot-Testgruppen
|
||||
|
||||
* Fokus: Verständlichkeit, Barrierefreiheit, Friktion beim Einstieg (Schreiben hochladen, Merkmal finden etc.).
|
||||
|
||||
### 5.2 Feedback-Mechanismen
|
||||
|
||||
* Interaktive Mock-UIs / klickbare Prototypen (z. B. Figma) zur frühen Usability-Validierung.
|
||||
* **Mock-APIs** (z. B. via Postman, Insomnia oder Swagger-UI) zur API-Validierung mit Behördensystemen.
|
||||
* Kurze Surveys oder Interviews (z. B. „Was ist für Sie das größte Problem bei Rückfragen zu Schreiben?“).
|
||||
|
||||
### 5.3 Iterationsschleifen
|
||||
|
||||
* Frühzeitige “Pilot-Phase” mit einer kleinen Behörde/Abteilung, bevor generisch ausgebaut wird.
|
||||
* Veränderungswünsche in **Versionierte API-Designs** überführen (z. B. v1 → v1.1), kein “API-Chaos”.
|
||||
|
||||
**Why:**
|
||||
Stakeholder-Feedback verhindert, dass du an den eigentlichen Bedürfnissen vorbeientwickelst (z. B. zu komplizierte Ablaufsteuerung). Es ist essentiell für **cleanes, *wirklich* extensibles Design**, insbesondere, weil Behörden-IT traditionell komplexe und gewachsene Umfelder hat.
|
||||
|
||||
---
|
||||
|
||||
## 6. Existing Assets
|
||||
|
||||
**Description: Legacy docs, wireframes, or code snippets**
|
||||
|
||||
Im Moment sind das bei DVD überwiegend **noch zu definierende** Assets – aber hier ist, was du konkret sammeln/erstellen solltest (und wie es der Architektur hilft):
|
||||
|
||||
### 6.1 Fachliche Assets
|
||||
|
||||
* Beispiel-Briefe aus verschiedenen Behörden (gerichtliche Schreiben, Gebührenbescheide, Steuerbescheide etc.)
|
||||
|
||||
* inkl. Struktur der Aktenzeichen/Kassenzeichen (Masken, Beispiele).
|
||||
* Prozessbeschreibungen, wie Rückfragen heute laufen (IST-Prozess) – z. B. BPMN oder einfache Swimlane-Diagramme.
|
||||
|
||||
### 6.2 Modell- & Design-Assets
|
||||
|
||||
* Erste **Domänenmodelle / UML-Klassendiagramme** für:
|
||||
|
||||
* `DocumentEnvelope`, `InteractionThread`, `RoutingRule`, `AuthorityUnit`, `User`.
|
||||
* Wireframes/Mockups für:
|
||||
|
||||
* Bürger-Oberfläche (Schreiben hochladen, Anfrage stellen),
|
||||
* Sachbearbeiter-Oberfläche (Postkorb, Vorgänge, Antworten).
|
||||
|
||||
### 6.3 Technische Assets
|
||||
|
||||
* Beispiel-JSON-Payloads für zentrale API-Objekte, z. B.:
|
||||
|
||||
```json
|
||||
{
|
||||
"documentId": "doc-123",
|
||||
"organisationId": "court-xyz",
|
||||
"caseNumber": "12 C 345/25",
|
||||
"documentType": "PaymentNotice",
|
||||
"issuedAt": "2025-12-01",
|
||||
"citizenHint": "Bitte geben Sie dieses Aktenzeichen bei Rückfragen an."
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"threadId": "thr-789",
|
||||
"documentId": "doc-123",
|
||||
"messages": [
|
||||
{
|
||||
"messageId": "msg-1",
|
||||
"from": "citizen",
|
||||
"content": "Ich habe eine Frage zur Zahlungsfrist.",
|
||||
"createdAt": "2025-12-02T09:15:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Why:**
|
||||
Diese Assets sind Gold für:
|
||||
|
||||
* spätere LLM-Unterstützung (z. B. “Generiere Routing-Regeln basierend auf diesen Beispielbriefen”),
|
||||
* Reduktion von Missverständnissen bei Domainmodell & API-Design,
|
||||
* schnellere Implementierung, weil Entwickler konkrete Fälle sehen.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user