Mache die Akte zum Sammler und binde Paperless sowie E-Mail an.
Deploy Development / deploy (push) Successful in 22s

Erfassen liegt in Dialogen, Vorgaenge erscheinen als Kacheln in der Akte, und Quellen lassen Dokumente und IMAP-Nachrichten verknuepfen.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-10-16 22:29:41 +02:00
1 parent 332be8376e
commit b03f571cd8
16 files changed
+1040 -149

No files matched your search

+1
View File
@@ -702,6 +702,7 @@ def post_external(body: ExternalIn, principal: Principal = Depends(get_principal
body.dates.document_on,
body.dates.sent_on,
body.dates.received_on,
body.detail.model_dump(exclude_none=True) if body.detail else None,
)
return _created(f"/api/v1/elements/{element['id']}", {"id": str(element["id"]), "title": element["title"]})
+21 -1
View File
@@ -144,14 +144,34 @@ class DatesIn(APIModel):
received_on: date | None = None
class ExternalDetail(APIModel):
correspondent: str | None = Field(default=None, max_length=200)
message_from: str | None = Field(default=None, max_length=200)
open_url: str | None = Field(default=None, max_length=500, pattern=r"^https?://")
class ExternalIn(APIModel):
title: str = Field(min_length=1, max_length=200)
source: Literal["paperless", "url"]
source: Literal["paperless", "url", "imap"]
external_id: str = Field(min_length=1, max_length=200)
context: ContextIn
placement: ContextIn | None = None
chapter_id: UUID | None = None
dates: DatesIn = DatesIn()
detail: ExternalDetail | None = None
class ConnectorIn(APIModel):
kind: Literal["paperless", "imap"]
name: str = Field(min_length=1, max_length=120)
base_url: str | None = None
token: str | None = None
host: str | None = None
port: int | None = Field(default=None, ge=1, le=65535)
username: str | None = None
password: str | None = None
mailbox: str | None = Field(default=None, max_length=200)
security: Literal["ssl", "starttls"] | None = None
class DeleteElementIn(APIModel):
+104
View File
@@ -0,0 +1,104 @@
"""Connector administration and live Paperless / IMAP lookup."""
from __future__ import annotations
from uuid import UUID
from fastapi import APIRouter, Depends
from psycopg import Connection
from app.access.policy import Ctx
from app.api.deps import Principal, get_conn, get_principal
from app.api.routes import _created, _ctx_model
from app.api.schemas import ConnectorIn, ExternalIn
from app.core.errors import unprocessable
from app.ops import create_external
from app.sources import (
clean_base_url,
delete_connector,
imap_messages,
list_connectors,
paperless_documents,
probe,
save_connector,
)
router = APIRouter()
@router.get("/api/v1/connectors")
def get_connectors(principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return {"items": list_connectors(conn, principal.account_id)}
@router.post("/api/v1/connectors", status_code=201)
def post_connector(body: ConnectorIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
name, settings, secret = _connector_parts(body)
row = save_connector(conn, principal.account_id, body.kind, name, settings, secret)
return row
@router.delete("/api/v1/connectors/{connector_id}", status_code=204)
def remove_connector(connector_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
delete_connector(conn, principal.account_id, connector_id)
@router.post("/api/v1/connectors/{connector_id}/probe")
def probe_connector(connector_id: UUID, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return probe(conn, principal.account_id, connector_id)
@router.get("/api/v1/sources/paperless/documents")
def search_paperless(q: str = "", principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
return {"items": paperless_documents(conn, principal.account_id, q.strip())}
@router.get("/api/v1/sources/imap/messages")
def search_mail(
connector_id: UUID,
q: str = "",
principal: Principal = Depends(get_principal),
conn: Connection = Depends(get_conn),
):
return {"items": imap_messages(conn, principal.account_id, connector_id, q.strip())}
@router.post("/api/v1/sources/link", status_code=201)
def link_source(body: ExternalIn, principal: Principal = Depends(get_principal), conn: Connection = Depends(get_conn)):
if body.source not in {"paperless", "imap"}:
raise unprocessable("Verknüpft werden Paperless-Dokumente und E-Mails.")
element = create_external(
conn,
principal.account_id,
principal.scope_id,
body.title,
body.source,
body.external_id,
Ctx(body.context.kind, body.context.id),
_ctx_model(body.placement),
body.chapter_id,
body.dates.document_on,
body.dates.sent_on,
body.dates.received_on,
body.detail.model_dump(exclude_none=True) if body.detail else None,
)
return _created(f"/api/v1/elements/{element['id']}", {"id": str(element["id"]), "title": element["title"]})
def _connector_parts(body: ConnectorIn) -> tuple[str, dict, str]:
if body.kind == "paperless":
if not body.base_url or not body.token or len(body.token.strip()) < 8:
raise unprocessable("Paperless braucht eine Adresse und einen API-Schlüssel.")
return body.name.strip(), {"base_url": clean_base_url(body.base_url)}, body.token.strip()
if not body.host or not body.username or not body.password:
raise unprocessable("Ein E-Mail-Konto braucht Server, Benutzername und Passwort.")
host = body.host.strip()
if " " in host or len(host) > 200:
raise unprocessable("Der Mailserver ist ungültig.")
return body.name.strip(), {
"host": host,
"port": body.port or 993,
"username": body.username.strip(),
"mailbox": (body.mailbox or "INBOX").strip() or "INBOX",
"security": body.security or "ssl",
}, body.password
+2
View File
@@ -10,6 +10,7 @@ from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from app.api.routes import router
from app.api.sources import router as sources_router
from app.core.errors import Problem, problem_response
from app.core.settings import get_settings
from app.db.pool import open_pool
@@ -113,6 +114,7 @@ def create_app() -> FastAPI:
)
app.include_router(router)
app.include_router(sources_router)
return app
+3 -3
View File
@@ -526,13 +526,13 @@ def add_annotation(conn, actor: UUID, binding_id: UUID, body: str, context: Ctx
return row
def create_external(conn, actor: UUID, scope_id: UUID, title: str, source: str, external_id: str, context: Ctx, placement: Ctx | None, chapter_id: UUID | None, document_on, sent_on, received_on) -> dict:
def create_external(conn, actor: UUID, scope_id: UUID, title: str, source: str, external_id: str, context: Ctx, placement: Ctx | None, chapter_id: UUID | None, document_on, sent_on, received_on, detail: dict | None = None) -> dict:
target, rights_context = _placement(context, placement)
require_container_edit(conn, actor, target, rights_context)
element = _new_element(conn, actor, scope_id, title, "external_ref")
conn.execute(
"INSERT INTO external_references (element_id, source, external_id) VALUES (%s, %s, %s)",
(element["id"], source, external_id.strip()),
"INSERT INTO external_references (element_id, source, external_id, detail) VALUES (%s, %s, %s, %s)",
(element["id"], source, external_id.strip()[:200], Json(detail or {})),
)
binding = insert_binding(conn, element["id"], target.kind, target.id, chapter_id, actor)
record_dates(conn, actor, scope_id, element["id"], rights_context or target, document_on, sent_on, received_on)
+6 -2
View File
@@ -104,11 +104,15 @@ def _element_body(conn, element: dict) -> dict:
}
elif element["kind"] == "external_ref":
ref = conn.execute(
"SELECT source, external_id FROM external_references WHERE element_id = %s",
"SELECT source, external_id, detail FROM external_references WHERE element_id = %s",
(element["id"],),
).fetchone()
if ref is not None:
payload["external"] = {"source": ref["source"], "external_id": ref["external_id"]}
payload["external"] = {
"source": ref["source"],
"external_id": ref["external_id"],
"detail": ref["detail"] or {},
}
return payload
+236
View File
@@ -0,0 +1,236 @@
"""Paperless and IMAP connectors. Secrets stay on the server."""
from __future__ import annotations
import imaplib
import json
import ssl
from email.header import decode_header
from email.parser import BytesParser
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode, urlparse
from urllib.request import Request, urlopen
from uuid import UUID
from psycopg.types.json import Json
from app.core.errors import not_found, unprocessable
def save_connector(conn, owner_id: UUID, kind: str, name: str, settings: dict, secret: str) -> dict:
if kind == "paperless":
existing = conn.execute(
"SELECT id FROM connectors WHERE owner_id = %s AND kind = 'paperless'",
(owner_id,),
).fetchone()
if existing:
row = conn.execute(
"""
UPDATE connectors
SET name = %s, settings = %s, secret = %s
WHERE id = %s
RETURNING id, kind, name, settings, created_at
""",
(name, Json(settings), secret, existing["id"]),
).fetchone()
return _public(row)
row = conn.execute(
"""
INSERT INTO connectors (owner_id, kind, name, settings, secret)
VALUES (%s, %s, %s, %s, %s)
RETURNING id, kind, name, settings, created_at
""",
(owner_id, kind, name, Json(settings), secret),
).fetchone()
return _public(row)
def list_connectors(conn, owner_id: UUID) -> list[dict]:
rows = conn.execute(
"""
SELECT id, kind, name, settings, created_at
FROM connectors WHERE owner_id = %s
ORDER BY kind, name
""",
(owner_id,),
).fetchall()
return [_public(row) for row in rows]
def delete_connector(conn, owner_id: UUID, connector_id: UUID) -> None:
row = conn.execute(
"DELETE FROM connectors WHERE id = %s AND owner_id = %s RETURNING id",
(connector_id, owner_id),
).fetchone()
if row is None:
raise not_found()
def probe(conn, owner_id: UUID, connector_id: UUID) -> dict:
row = _owned(conn, owner_id, connector_id)
if row["kind"] == "paperless":
count = _paperless_count(row["settings"]["base_url"], row["secret"])
return {"ok": True, "detail": f"Paperless antwortet. {count} Dokumente sichtbar."}
_imap_login(row["settings"], row["secret"])
return {"ok": True, "detail": "Das Postfach ist erreichbar."}
def paperless_documents(conn, owner_id: UUID, query: str) -> list[dict]:
row = conn.execute(
"""
SELECT settings, secret FROM connectors
WHERE owner_id = %s AND kind = 'paperless'
ORDER BY created_at DESC LIMIT 1
""",
(owner_id,),
).fetchone()
if row is None:
raise unprocessable("Paperless ist noch nicht verbunden. Lege die Quelle unter Quellen an.")
base = row["settings"]["base_url"].rstrip("/")
payload = _paperless_get(base, row["secret"], "/api/documents/", {"query": query, "page_size": "20"})
items = []
for doc in payload.get("results") or []:
created = str(doc.get("created") or "")[:10]
title = (doc.get("title") or doc.get("original_file_name") or f"Dokument {doc.get('id')}").strip()
items.append(
{
"id": str(doc.get("id")),
"title": title[:200],
"document_on": created if len(created) == 10 else None,
"correspondent": _correspondent(doc),
"open_url": f"{base}/documents/{doc.get('id')}/",
}
)
return items
def imap_messages(conn, owner_id: UUID, connector_id: UUID, query: str) -> list[dict]:
row = _owned(conn, owner_id, connector_id)
if row["kind"] != "imap":
raise unprocessable("Das ist kein E-Mail-Konto.")
return _imap_list(row["settings"], row["secret"], query)
def _owned(conn, owner_id: UUID, connector_id: UUID) -> dict:
row = conn.execute(
"SELECT id, kind, name, settings, secret FROM connectors WHERE id = %s AND owner_id = %s",
(connector_id, owner_id),
).fetchone()
if row is None:
raise not_found()
return row
def _public(row) -> dict:
return {
"id": str(row["id"]),
"kind": row["kind"],
"name": row["name"],
"settings": row["settings"],
"created_at": row["created_at"].strftime("%Y-%m-%dT%H:%M:%SZ"),
}
def clean_base_url(value: str) -> str:
raw = value.strip()
parsed = urlparse(raw)
if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.username or parsed.password:
raise unprocessable("Die Paperless-Adresse muss mit http:// oder https:// beginnen.")
if len(raw) > 300:
raise unprocessable("Die Paperless-Adresse ist zu lang.")
return raw.rstrip("/")
def _paperless_count(base: str, token: str) -> int:
payload = _paperless_get(base, token, "/api/documents/", {"page_size": "1"})
return int(payload.get("count") or 0)
def _paperless_get(base: str, token: str, path: str, params: dict) -> dict:
url = f"{base}{path}?{urlencode(params)}"
request = Request(url, headers={"Authorization": f"Token {token}", "Accept": "application/json"})
try:
with urlopen(request, timeout=12) as response:
return json.loads(response.read().decode("utf-8"))
except HTTPError as exc:
if exc.code in {401, 403}:
raise unprocessable("Paperless hat den Schlüssel abgelehnt.") from exc
raise unprocessable("Paperless hat die Anfrage nicht beantwortet.") from exc
except (URLError, TimeoutError, json.JSONDecodeError) as exc:
raise unprocessable("Paperless ist nicht erreichbar.") from exc
def _correspondent(doc: dict) -> str | None:
value = doc.get("correspondent_name") or doc.get("correspondent")
if isinstance(value, str) and value.strip():
return value.strip()[:200]
return None
def _imap_login(settings: dict, secret: str) -> imaplib.IMAP4:
host = settings["host"]
port = int(settings["port"])
security = settings.get("security") or "ssl"
try:
if security == "starttls":
client = imaplib.IMAP4(host, port, timeout=12)
client.starttls(ssl.create_default_context())
else:
client = imaplib.IMAP4_SSL(host, port, ssl_context=ssl.create_default_context(), timeout=12)
client.login(settings["username"], secret)
return client
except imaplib.IMAP4.error as exc:
raise unprocessable("Das Postfach hat die Anmeldung abgelehnt.") from exc
except (OSError, TimeoutError) as exc:
raise unprocessable("Das Postfach ist nicht erreichbar.") from exc
def _imap_list(settings: dict, secret: str, query: str) -> list[dict]:
client = _imap_login(settings, secret)
try:
mailbox = settings.get("mailbox") or "INBOX"
status, _ = client.select(mailbox, readonly=True)
if status != "OK":
raise unprocessable("Das Postfach enthält dieses Fach nicht.")
status, data = client.search(None, "ALL")
if status != "OK" or not data or not data[0]:
return []
ids = data[0].split()[-25:]
needle = query.strip().lower()
items = []
for mid in reversed(ids):
status, fetched = client.fetch(mid, "(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE MESSAGE-ID)])")
if status != "OK" or not fetched or not isinstance(fetched[0], tuple):
continue
header = BytesParser().parsebytes(fetched[0][1])
subject = _decode(header.get("Subject")) or "(ohne Betreff)"
sender = _decode(header.get("From"))
if needle and needle not in subject.lower() and needle not in sender.lower():
continue
message_id = (header.get("Message-ID") or f"uid:{mid.decode()}").strip()
items.append(
{
"id": message_id[:200],
"title": subject[:200],
"message_from": sender[:200],
"date": _decode(header.get("Date"))[:80],
}
)
return items
finally:
try:
client.logout()
except imaplib.IMAP4.error:
pass
def _decode(value: str | None) -> str:
if not value:
return ""
parts = []
for text, encoding in decode_header(value):
if isinstance(text, bytes):
parts.append(text.decode(encoding or "utf-8", errors="replace"))
else:
parts.append(text)
return "".join(parts).strip()
@@ -0,0 +1,19 @@
ALTER TABLE external_references DROP CONSTRAINT external_references_source;
ALTER TABLE external_references
ADD CONSTRAINT external_references_source CHECK (source IN ('paperless', 'url', 'imap'));
ALTER TABLE external_references
ADD COLUMN detail jsonb NOT NULL DEFAULT '{}'::jsonb;
CREATE TABLE connectors (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
owner_id uuid NOT NULL REFERENCES auth_accounts (id),
kind text NOT NULL,
name text NOT NULL,
settings jsonb NOT NULL,
secret text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
CONSTRAINT connectors_kind CHECK (kind IN ('paperless', 'imap')),
CONSTRAINT connectors_name_len CHECK (char_length(name) BETWEEN 1 AND 120)
);
CREATE INDEX connectors_owner ON connectors (owner_id, kind);