# System- & Architekturplanung

**Django Abrechnungssystem für Therapie- und Sozialdienste**

> Diese Datei ist die Transkription der ursprünglichen Spezifikation
> (`Architektur_Planung_Abrechnungssystem.pdf`) nach Markdown. Verfeinerungen und
> Umsetzungsentscheidungen siehe [`UMSETZUNGSPLAN.md`](./UMSETZUNGSPLAN.md).

## 1. Projektübersicht & Zielsetzung

Das zu entwickelnde System ist eine webbasierte Abrechnungs- und Verwaltungssoftware
(basierend auf dem Django-Framework) für ein Unternehmen im therapeutischen oder
sozialen Sektor. Es verwaltet Auftraggeber, Therapeuten, Teilnehmer sowie die
erbrachten Leistungen und generiert daraus monatliche E-Rechnungen.

**Kernziel:** Komfortable, automatisierte Abrechnung bei gleichzeitiger rechtlicher
Absicherung des Softwareentwicklers. Dies wird durch das „On-the-fly"-Generatorkonzept
erreicht, bei dem keine fertigen Rechnungsdokumente dauerhaft in der Datenbank
gespeichert werden.

## 2. Rechtliche Rahmenbedingungen

- **E-Rechnungspflicht (ab 2025):** B2B-Rechnungen in Deutschland erfordern ein
  maschinenlesbares Format. Das System nutzt das **ZUGFeRD-Format** (PDF-Dokument mit
  eingebetteter XML-Datei nach EN 16931).
- **GoBD & Revisionssicherheit:** Um die Haftung des Entwicklers bezüglich der
  Manipulationssicherheit von Rechnungsdokumenten zu minimieren, fungiert die Software
  als Konvertierungswerkzeug. Die finale revisionssichere Ablage der exportierten PDFs
  obliegt dem Nutzer.
- **Lückenlose Nummernkreise:** Zur Erfüllung der buchhalterischen Pflichten führt das
  System ein Metadaten-Journal (`InvoiceLog`), welches die Vergabe fortlaufender
  Rechnungsnummern und Stornierungen dokumentiert.

## 3. Systemarchitektur & Datenmodell

Das Datenmodell ist so strukturiert, dass es die dreidimensionale Beziehung zwischen
Auftraggebern (Rechnungsempfänger), Teilnehmern (Patienten/Klienten) und Therapeuten
(Leistungserbringer) abbildet.

| Entität (Model)   | Beschreibung & Funktion |
|-------------------|-------------------------|
| **Auftraggeber**  | Bezahler der Leistungen (Ämter, Firmen, Privatzahler). Besitzt Stammdaten und empfängt die ZUGFeRD-Rechnungen. |
| **Teilnehmer**    | Die Person, die die Dienstleistung in Anspruch nimmt. Ist fest einem Auftraggeber zugeordnet. |
| **Therapeut**     | Der Leistungserbringer (z.B. mit Namenskürzel). Basis für die Leistungsstatistiken. |
| **TherapySession**| Das „Logbuch" der erbrachten Leistungen. Speichert Datum, Stundenanzahl und Stundensatz der jeweiligen Therapieeinheit. Verknüpft Therapeut und Teilnehmer. |
| **InvoiceLog**    | Das Rechnungsjournal. Speichert keine Dokumente, sondern nur Metadaten: Rechnungsnummer, Datum, Auftraggeber, Gesamtbetrag und den Status (GÜLTIG/STORNIERT). |

## 4. Kernprozesse

### 4.1 Leistungserfassung (Dateneingabe)

Um den Flaschenhals der manuellen Dateneingabe aus Papierlisten zu beseitigen, nutzt
das System Django `ModelFormSets`. Dies ermöglicht eine tabellarische Bulk-Eingabe
(ähnlich Excel), bei der eine Verwaltungskraft mehrere Therapie-Sitzungen für einen
Therapeuten und Monat in einer einzigen Maske erfassen und speichern kann.

### 4.2 Rechnungslegung (On-the-fly Generierung)

Der monatliche Abrechnungsprozess verläuft wie folgt:

- Das System filtert alle nicht abgerechneten `TherapySession`-Einträge eines
  Auftraggebers.
- Es zieht die nächste freie Rechnungsnummer und erstellt einen Eintrag im
  `InvoiceLog`.
- Die Leistungen werden mit dieser Rechnungsnummer verknüpft (Feld `abgerechnet_mit`).
- Der ZUGFeRD-Generator baut die XML-Struktur auf und bettet sie in ein via WeasyPrint
  generiertes PDF ein.
- Das Dokument wird direkt dem Nutzer als Download ausgeliefert oder per E-Mail
  versendet, **ohne** als Datei auf dem Server verbleiben zu müssen.

### 4.3 Storno- und Korrektur-Workflow

Sollte eine Rechnung fehlerhaft sein (z.B. vergessene Stunden):

- Die bestehende Rechnung wird im System auf „STORNIERT" gesetzt.
- Ein Storno-Beleg mit neuer, eigener Belegnummer wird generiert.
- Die zugehörigen `TherapySession`-Einträge werden wieder freigegeben (Status „nicht
  abgerechnet").
- Nach Korrektur der Leistungsdaten wird eine neue, reguläre Rechnung mit der nächsten
  fortlaufenden Nummer generiert.

## 5. Controlling & Statistiken

Das System beinhaltet ein Dashboard für Management und Steuerberater. Die Aggregation
der Daten erfolgt dynamisch über das Django ORM auf Basis der erbrachten Leistungen
(`TherapySession`). So wird eine dreidimensionale Auswertung (Umsatz & Stunden)
realisiert, ohne auf persistente Rechnungsdokumente zurückgreifen zu müssen:

- **Nach Auftraggeber:** Identifikation der größten Umsatzbringer (z.B. spezifische
  Ämter).
- **Nach Teilnehmer:** Übersicht der erbrachten Stunden pro Klient.
- **Nach Therapeut:** Leistungskontrolle und Grundlage für interne Provisionen/
  Gehaltsabrechnungen.

## 6. Technologiestack

- **Backend:** Python / Django
- **Datenbank:** PostgreSQL (empfohlen) oder SQLite (für Entwicklung)
- **PDF-Generierung:** WeasyPrint (HTML/CSS zu PDF)
- **E-Rechnung:** factur-x / python-zugferd (für die XML-Struktur)
- **Frontend:** Django Templates, optional django-crispy-forms / django-tables2