60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
|
# Implementation Guide – DirektVermittlungDe (FastAPI)
|
|||
|
|
|
|||
|
|
This guide explains how this codebase implements the architectural decisions
|
|||
|
|
and API specification of DirektVermittlungDe.
|
|||
|
|
|
|||
|
|
## 1. Architecture Mapping
|
|||
|
|
|
|||
|
|
- **Belegorientierung**: `Document` is the central aggregate.
|
|||
|
|
- Domain models in `app/domain/models.py`
|
|||
|
|
- ORM model in `app/adapters/orm.py::Document`
|
|||
|
|
- **Interaction Threads**: `Thread` and `Message` map to interaction threads and their logs.
|
|||
|
|
- Cursor-based pagination implemented in `app/service/threads_service.py::list_messages`
|
|||
|
|
- The `created_at` timestamp is used as the pagination cursor.
|
|||
|
|
|
|||
|
|
- **Routing Engine**:
|
|||
|
|
- Implemented as an adapter in `app/adapters/routing.py`
|
|||
|
|
- Operates solely on `DocumentMetadata` (plaintext) as required by the split-payload model.
|
|||
|
|
|
|||
|
|
- **Asynchronous Exports**:
|
|||
|
|
- `POST /exports` → `start_export()` in `app/service/exports_service.py`
|
|||
|
|
- Returns `202 Accepted` with `jobId` and uses a job registry (`app/adapters/jobs.py`)
|
|||
|
|
- In a production system this would publish to Redis / RabbitMQ and be processed by workers.
|
|||
|
|
|
|||
|
|
## 2. Security
|
|||
|
|
|
|||
|
|
- **Auth**:
|
|||
|
|
- OAuth2 / JWT is abstracted in `app/adapters/auth.py`.
|
|||
|
|
- In this reference implementation, we parse unverified claims; in production, validate via JWKS.
|
|||
|
|
|
|||
|
|
- **Data Protection**:
|
|||
|
|
- Encrypted payloads are treated as opaque strings and stored via `app/adapters/storage.py`.
|
|||
|
|
- Only routing metadata is stored in PostgreSQL for server-side logic.
|
|||
|
|
|
|||
|
|
- **Retention**:
|
|||
|
|
- Each `Document` gets a `retention_date`, set to a grace period in the future.
|
|||
|
|
- Implement a periodic cleanup job that deletes rows where `retention_date < NOW()`.
|
|||
|
|
|
|||
|
|
## 3. Performance / Hybrid Concurrency
|
|||
|
|
|
|||
|
|
- All endpoints are `async def` and rely on the async SQLAlchemy engine.
|
|||
|
|
- CPU-heavy operations (PDF merge, crypto) must not be run inside the event loop.
|
|||
|
|
- To extend this, create a `ProcessPoolExecutor` in `workers/` and call via `loop.run_in_executor`.
|
|||
|
|
|
|||
|
|
## 4. Extending the System
|
|||
|
|
|
|||
|
|
- **Real Routing Rules**:
|
|||
|
|
- Add a `routing_rules` table and adapt `app/adapters/routing.py` to query it.
|
|||
|
|
- **Real Export Workers**:
|
|||
|
|
- Replace `jobs.py` with a Redis-backed queue and a worker process in `workers/exports_worker.py`.
|
|||
|
|
- **Authority Integration**:
|
|||
|
|
- Call the authority’s eAkte ingress API from the worker, using authority-specific keys.
|
|||
|
|
|
|||
|
|
## 5. Definition of Done Checklist
|
|||
|
|
|
|||
|
|
Before going to production:
|
|||
|
|
|
|||
|
|
- Load-test `POST /documents` and `GET /threads/{id}/messages`.
|
|||
|
|
- Verify that logs never contain Aktenzeichen or other PII.
|
|||
|
|
- Verify that retention cleanup jobs work correctly on staging data.
|