96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
|
---
|
|||
|
|
title: "Kanshō – Backend und API"
|
|||
|
|
version: "0.1"
|
|||
|
|
status: "Arbeitsstand"
|
|||
|
|
date: "2026-08-19"
|
|||
|
|
product_family: "Jinkendo"
|
|||
|
|
document_role: "Technical Chapter / Backend / API"
|
|||
|
|
parent_document: "technische_zielarchitektur.md"
|
|||
|
|
---
|
|||
|
|
# Kanshō – Backend und API
|
|||
|
|
|
|||
|
|
Kanonisches Home für FastAPI-Struktur, Router-Schnitt und API-Vertrag. Mitai-Referenz: `.claude/rules/ARCHITECTURE.md` §1, `backend/main.py`, `backend/routers/`.
|
|||
|
|
|
|||
|
|
## 1. Prinzipien
|
|||
|
|
|
|||
|
|
Herkunft: Mitai-Architekturregeln, als Rahmen übernommen.
|
|||
|
|
|
|||
|
|
### 1.1 Ein Modul = ein Router
|
|||
|
|
|
|||
|
|
Jedes fachliche Modul besitzt genau eine Router-Datei unter `backend/routers/`. Endpoints liegen nicht in `main.py` außer Health/Status.
|
|||
|
|
|
|||
|
|
Neue Module = neue Datei, Registrierung via `app.include_router(..., prefix="/api")`.
|
|||
|
|
|
|||
|
|
Rahmen-Module (erste erwartbare Dateien, keine vollständige Liste):
|
|||
|
|
|
|||
|
|
- `auth`
|
|||
|
|
- `profiles`
|
|||
|
|
- später: Dialog, Memory, Journal-Handoff, Gateway-Audit-Metadaten, Admin-Diagnose
|
|||
|
|
|
|||
|
|
Domänenrouter für Mitai-Tracking werden nicht angelegt.
|
|||
|
|
|
|||
|
|
### 1.2 API-First
|
|||
|
|
|
|||
|
|
Jede vom UI benötigte Funktion ist zuerst ein Endpoint. Das Frontend spricht ausschließlich diese API (Mitai: `utils/api.js`). Keine fachliche Berechnung, kein Context-Building und kein Privacy-Demasking im Browser.
|
|||
|
|
|
|||
|
|
### 1.3 Fehlerformat
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
HTTPException → {"detail": "menschenlesbare Meldung"}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Keine parallelen Formate (`error`, `success: false`). Herkunft: Mitai.
|
|||
|
|
|
|||
|
|
### 1.4 Auth an der Grenze
|
|||
|
|
|
|||
|
|
Geschützte Routen nutzen `Depends(require_auth)` bzw. `require_admin`. Ressourcenfilter immer über Session-`profile_id`. Siehe `auth_identity_and_roles.md`.
|
|||
|
|
|
|||
|
|
## 2. Schichten im Backend
|
|||
|
|
|
|||
|
|
Bevorzugte innere Trennung, analog Mitai plus Kanshō-spezifische Gateway-Schicht:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
routers/ HTTP, Validierung, Auth-Depends
|
|||
|
|
services/ fachliche Orchestrierung (später)
|
|||
|
|
privacy_gateway/ Minimierung, Pseudonymisierung, Egress, Validation
|
|||
|
|
data/ PostgreSQL-Zugriff
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**Status: bevorzugte Richtung** für Ordnernamen. Kein Zwang, Mitai-Dateibaum 1:1 zu klonen, wenn die Trennlinie Router / Gateway / Persistenz klar bleibt.
|
|||
|
|
|
|||
|
|
Privacy Gateway darf nicht umgangen werden, indem ein Router den Provider direkt aufruft. KI-Ausführung nur über die Prompt-Engine (`platform_extensibility.md`), Callback = Gateway.
|
|||
|
|
|
|||
|
|
## 3. Versionierung
|
|||
|
|
|
|||
|
|
Mitai führt `backend/version.py` mit `APP_VERSION` und `MODULE_VERSIONS`.
|
|||
|
|
|
|||
|
|
**Status: bevorzugte Richtung** – gleiches Muster für Kanshō, sobald Code existiert. Semantic Versioning.
|
|||
|
|
|
|||
|
|
## 4. Health und Betrieb
|
|||
|
|
|
|||
|
|
Ein ungeschützter oder schwach geschützter Status-Endpoint für Deploy-Healthchecks analog Mitai `/api/auth/status` bzw. Health nach Container-Start.
|
|||
|
|
|
|||
|
|
Konkreter Pfad: offen, Muster übernommen.
|
|||
|
|
|
|||
|
|
## 5. Entscheidungsstand
|
|||
|
|
|
|||
|
|
| Thema | Stand | Status |
|
|||
|
|
|---|---|---|
|
|||
|
|
| FastAPI + ein Router je Modul | ja | entschieden |
|
|||
|
|
| API-First, keine Business-Logik im Frontend | ja | entschieden |
|
|||
|
|
| Fehlerkörper `{detail}` | ja | entschieden |
|
|||
|
|
| Direktaufruf externer LLMs aus Routern | verboten | entschieden |
|
|||
|
|
| OpenAPI als dokumentierter Vertrag | später | offen |
|
|||
|
|
| Interne service-Schicht vs. fette Router | service-Schicht | bevorzugte Richtung |
|
|||
|
|
|
|||
|
|
## 6. Offene Fragen
|
|||
|
|
|
|||
|
|
1. Internes API für mindnet/Kairo: synchron REST vs. Events? → `integrations_technical.md`
|
|||
|
|
2. Idempotenz-Keys für Offline-Sync-Queue? → `memory_storage_and_offline.md`
|
|||
|
|
3. Rate Limits außer Auth: welche Dialog-Endpoints?
|
|||
|
|
|
|||
|
|
## 7. Querverweise
|
|||
|
|
|
|||
|
|
- Technisch: `auth_identity_and_roles.md`, `privacy_gateway.md`, `runtime_and_deploy.md`
|
|||
|
|
- Mitai: `ARCHITECTURE.md` §1, `INTERNAL_API_REFERENCE.md`
|