init: documentation and prototypes

2025-12-01 22:01:19 +01:00
parent e936fb41fa
commit 45d60fc1a9
51 changed files with 2476 additions and 1 deletions
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -0,0 +1,189 @@
+openapi: 3.1.0
+info:
+  title: DirektVermittlungDe API
+  version: 1.0.0
+  description: |
+    API for efficient communication between citizens and authorities.
+    Key features: Document Intake, Auto-Routing, Interaction Threads.
+    [cite: 1, 3]
+
+servers:
+  - url: https://api.direktvermittlung.de/v1
+    description: Production Server
+
+components:
+  securitySchemes:
+    OAuth2:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://id.bund.de/auth
+          tokenUrl: https://api.direktvermittlung.de/oauth/token
+          scopes:
+            citizen:write: "Submit documents and inquiries"
+            official:read: "View assigned cases"
+            official:write: "Respond to inquiries"
+
+  schemas:
+    DocumentEnvelope:
+      type: object
+      required: [metadata]
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+        metadata:
+          [cite_start]description: Plaintext metadata required for the Routing Engine[cite: 8].
+          type: object
+          required: [authorityId, docType]
+          properties:
+            authorityId:
+              type: string
+              example: "Finanzamt-München-I"
+            referenceNumber:
+              type: string
+              [cite_start]description: Aktenzeichen/Kassenzeichen [cite: 3]
+            docType:
+              type: string
+              enum: [NOTICE, COURT_ORDER, GENERAL_INQUIRY]
+            issuedAt:
+              type: string
+              format: date-time
+        encryptedPayload:
+          type: string
+          format: base64
+          [cite_start]description: E2E Encrypted PDF content or scan[cite: 27].
+        status:
+          type: string
+          enum: [RECEIVED, ROUTED, ASSIGNED, CLOSED]
+          readOnly: true
+
+    InteractionThread:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        documentId:
+          type: string
+          format: uuid
+        type:
+          type: string
+          [cite_start]enum: [TEXT_CHAT, CALLBACK_REQUEST, APPOINTMENT] [cite: 10]
+        status:
+          type: string
+          enum: [OPEN, PENDING_OFFICIAL, PENDING_CITIZEN, RESOLVED]
+
+    Message:
+      type: object
+      properties:
+        id:
+          type: string
+        senderRole:
+          type: string
+          enum: [CITIZEN, OFFICIAL]
+        content:
+          type: string
+          description: Encrypted message content.
+        timestamp:
+          type: string
+          format: date-time
+
+paths:
+  /documents:
+    post:
+      summary: Upload a new document (FR-1)
+      description: Creates a DocumentEnvelope. [cite_start]The Routing Engine will process the metadata asynchronously[cite: 8].
+      security:
+        - OAuth2: [citizen:write]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DocumentEnvelope'
+      responses:
+        '201':
+          description: Document Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentEnvelope'
+
+  /documents/{id}/threads:
+    post:
+      summary: Start an interaction (FR-3)
+      [cite_start]description: Initiate a callback request, text inquiry, or appointment[cite: 10].
+      security:
+        - OAuth2: [citizen:write]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [type]
+              properties:
+                type:
+                  type: string
+                  enum: [TEXT_CHAT, CALLBACK_REQUEST, APPOINTMENT]
+                initialMessage:
+                  type: string
+      responses:
+        '201':
+          description: Thread Started
+
+  /threads/{threadId}/messages:
+    get:
+      summary: Get message history (FR-4)
+      description: Uses cursor-based pagination for chat history.
+      parameters:
+        - name: threadId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+        - name: before
+          in: query
+          schema:
+            type: string
+            format: date-time
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Message'
+
+  /exports:
+    post:
+      summary: Export data to authority system (FR-7)
+      [cite_start]description: Triggers an async export job to the eAkte[cite: 16].
+      security:
+        - OAuth2: [official:read]
+      responses:
+        '202':
+          description: Export Accepted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  jobId:
+                    type: string
+                  status:
+                    type: string
+                    example: "QUEUED"