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/api_docs.md
+++ b/docs/api_docs.md
@@ -0,0 +1,175 @@
+Here is the **API Documentation & Implementation Guide** for DirektVermittlungDe (DVD). This document focuses on the **practical implementation scenarios** derived from the architectural requirements and the OpenAPI specification designed in the previous step.
+
+-----
+
+# API Documentation: Core Scenarios & Implementation Guide
+
+**Version:** 1.0
+**Target Audience:** Frontend Developers (Citizen App), Backend Integrators (Authority Systems)
+**Base URL:** `https://api.direktvermittlung.de/v1`
+
+## Overview
+
+[cite_start]This API enables the "Direct Vermittlung" workflow: receiving documents, routing them to the correct authority, and facilitating direct communication[cite: 1, 4]. [cite_start]It is designed to be **stateless** [cite: 40][cite_start], **secure** (E2E encryption) [cite: 23][cite_start], and **scalable** (10k+ sessions)[cite: 20].
+
+-----
+
+## 0\. Authentication
+
+[cite_start]All endpoints require a valid OAuth2 Bearer Token[cite: 40].
+
+  * **Citizens** use `citizen:write` scope (via BundID/eID).
+  * **Officials** use `official:read`/`official:write` scopes (via Authority SSO).
+
+-----
+
+## Scenario 1: The "Digital Intake" (Document Submission)
+
+[cite_start]**User Story:** A citizen scans a tax assessment letter to find the right contact person without manual searching[cite: 1, 13].
+
+### Implementation Logic
+
+1.  [cite_start]**Metadata Separation:** The client must extract non-sensitive routing data (Authority Name, Reference Number) as plaintext metadata[cite: 2, 4].
+2.  [cite_start]**Encryption:** The actual PDF content (`encryptedPayload`) is encrypted on the client side before upload to meet NFR-5 (E2E Encryption)[cite: 23].
+3.  [cite_start]**Routing:** The backend Routing Engine uses the plaintext metadata to assign the `DocumentEnvelope` to the correct unit[cite: 4].
+
+### API Request: `POST /documents`
+
+```json
+{
+  "metadata": {
+    "authorityId": "Finanzamt-München-I",
+    "referenceNumber": "123/456/789", 
+    "docType": "NOTICE",
+    "issuedAt": "2025-10-25T00:00:00Z"
+  },
+  "encryptedPayload": "BASE64_ENCRYPTED_BLOB_..." 
+}
+```
+
+### Success Response (`201 Created`)
+
+```json
+{
+  "id": "doc-882291",
+  "status": "ROUTED",
+  "assignedUnit": "Steuerfestsetzung-Team-B" 
+}
+```
+
+> [cite_start]**Note:** The `assignedUnit` confirms that the Routing Engine successfully mapped the request in \< 500ms[cite: 20].
+
+-----
+
+## Scenario 2: Starting a Clarification Thread
+
+[cite_start]**User Story:** The citizen has a question about the document and wants to start a chat or request a callback[cite: 5, 6].
+
+### Implementation Logic
+
+1.  [cite_start]**Context:** The thread is explicitly linked to the `documentId` (`doc-882291`), creating a "Subject-Context" binding[cite: 6].
+2.  [cite_start]**Type Selection:** The user selects the channel: `TEXT_CHAT`, `CALLBACK_REQUEST`, or `APPOINTMENT`[cite: 5].
+
+### API Request: `POST /documents/doc-882291/threads`
+
+```json
+{
+  "type": "CALLBACK_REQUEST",
+  "initialMessage": "I do not understand the calculation on page 2. Please call me.",
+  "preferredTimeSlot": "2025-10-28T14:00:00Z"
+}
+```
+
+### Success Response (`201 Created`)
+
+```json
+{
+  "threadId": "th-9912",
+  "status": "PENDING_OFFICIAL",
+  "estimatedWaitTime": "4h"
+}
+```
+
+-----
+
+## Scenario 3: Real-time Communication & History
+
+[cite_start]**User Story:** An official replies to the inquiry, and the citizen views the chat history[cite: 7].
+
+### Implementation Logic
+
+1.  [cite_start]**Performance:** To support fast loading (NFR-1 \< 300ms)[cite: 19], we use **Cursor-based pagination** for messages.
+2.  **Polling/Updates:** The frontend polls this endpoint (or uses a WebSocket subscription, if extended) to show new messages.
+
+### API Request: `GET /threads/th-9912/messages`
+
+*Query Parameters:* `?limit=20&before=2025-10-27T10:00:00Z`
+
+### Success Response (`200 OK`)
+
+```json
+{
+  "data": [
+    {
+      "id": "msg-552",
+      "senderRole": "OFFICIAL",
+      "content": "encrypted_content_string...", 
+      "timestamp": "2025-10-27T09:45:00Z"
+    },
+    {
+      "id": "msg-551",
+      "senderRole": "CITIZEN",
+      "content": "encrypted_content_string...",
+      "timestamp": "2025-10-27T09:30:00Z"
+    }
+  ],
+  "paging": {
+    "nextCursor": "2025-10-27T09:30:00Z"
+  }
+}
+```
+
+-----
+
+## Scenario 4: Data Export (Authority Integration)
+
+[cite_start]**User Story:** The issue is resolved, and the authority imports the chat history and document into their eAkte system[cite: 11, 35].
+
+### Implementation Logic
+
+1.  [cite_start]**Asynchronous Processing:** Since exports can be large (PDFs + Chat Logs), the API returns immediately with a `jobId`[cite: 28, 43].
+2.  [cite_start]**Format:** The export format is configurable (e.g., PDF summary of chat + original attachments)[cite: 12].
+
+### API Request: `POST /exports`
+
+```json
+{
+  "caseId": "doc-882291",
+  "targetSystem": "eAkte-Standard-V2",
+  "includeAttachments": true
+}
+```
+
+### Success Response (`202 Accepted`)
+
+```json
+{
+  "jobId": "job-5512",
+  "status": "QUEUED",
+  "statusUrl": "/exports/job-5512"
+}
+```
+
+-----
+
+## Error Handling Standards
+
+[cite_start]To ensure clarity for developers[cite: 16], the API uses standard HTTP codes:
+
+  * `400 Bad Request`: Validation failed (e.g., missing Aktenzeichen).
+  * `404 Not Found`: Document or Thread ID does not exist.
+  * [cite_start]`429 Too Many Requests`: Rate limit exceeded (NFR protection)[cite: 19].
+  * `503 Service Unavailable`: Maintenance or backend overload.
+
+
+xxx