FDS2610/Steuerkram
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs: README verschlankt, docs/-Verzeichnis mit Unterseiten je Bereich

Browse source
This commit is contained in:
fds2610-bot 2026-04-12 19:20:15 +02:00
parent 4f9d51ff05
commit efdca6fbc3
10 changed files with 583 additions and 372 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
CLAUDE.md
View file

@ -42,8 +42,10 @@ $this->assertNotEmpty($wert, 'Beschreibung');
| Datei | Wann aktualisieren | | Datei | Wann aktualisieren |
|---|---| |---|---|
| `Changes.md` | Bei jedem Feature, Bugfix oder strukturellen Änderung (nicht bei reinen Test- oder Doku-Commits) | | `Changes.md` | Bei jedem Feature, Bugfix oder strukturellen Änderung (nicht bei reinen Test- oder Doku-Commits) |
| `README.md` | Wenn sich der Funktionsumfang, Tech Stack oder die Installationsanleitung ändert | | `README.md` | Wenn sich der Funktionsumfang oder der Tech Stack grundlegend ändert |
| `BERICHTE.md` | Bei jeder Änderung an `EuerCalculator.php` oder `UstvaCalculator.php` (Zuordnungsregeln, neue Kennzahlen, geänderte Bedingungen) | | `docs/funktionen.md` | Wenn ein neues Feature hinzukommt oder ein bestehendes wesentlich geändert wird |
| `docs/berechnungslogik.md` | Bei jeder Änderung an `EuerCalculator.php` oder `UstvaCalculator.php` (Zuordnungsregeln, neue Kennzahlen, geänderte Bedingungen) |
| `docs/anlagevermögen.md` | Bei Änderungen am Anlagevermögens-Workflow oder den Asset-Modellen |
## Datenbankmigrationen ## Datenbankmigrationen

405
README.md
View file

@ -1,396 +1,61 @@
# Steuerkram # Steuerkram
Self-hosted Buchhaltungs- und Steueranwendung für deutsche Freiberufler und Kleinunternehmer. Entwickelt als datensouveräne Alternative zu SaaS-Diensten. Self-hosted Buchhaltungs- und Steueranwendung für deutsche Freiberufler und Kleinunternehmer. Entwickelt als datensouveräne Alternative zu SaaS-Diensten – mit Unterstützung von [Claude Code](https://claude.ai/code).
![PHP](https://img.shields.io/badge/PHP-777BB4?logo=php&logoColor=white)
![MariaDB](https://img.shields.io/badge/MariaDB-003545?logo=mariadb&logoColor=white)
![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
---
## Funktionsumfang ## Funktionsumfang
- **Kontenrahmen SKR03** – DATEV-konformer SKR03 mit 157 Systemkonten (Klassen 0, 1, 2, 4, 8); zugeschnitten auf EÜR-Buchhalter ohne Bilanzierung (CRUD) | Bereich | Beschreibung |
- **Belegverwaltung** – Upload von PDF, PNG, TIFF und ZUGFeRD-XML; SHA-256 Integritätsprüfung; automatischer Weißrand-Zuschnitt bei JPEG/PNG via GD
- **Buchungen** – EÜR-Buchungsmodell (Einnahme/Ausgabe) mit Kategorie- und Zahlungskonto; GoBD-konforme Trigger verhindern nachträgliche Manipulation
- **Kundenverwaltung** – CRUD
- **Ausgangsrechnungen** – DIN 5008 Layout, PDF-Export via mPDF
- **UStVA** – Kennzahlen-Berechnung aus Buchungen, ELSTER XML-Export
- **EÜR** – Jahresauswertung mit PDF-Export
- **Einstellungen** – Firmendaten, Logo, ELSTER-Steuernummer
- **Benutzerverwaltung** – Benutzer anlegen, bearbeiten, deaktivieren und löschen; session-basierte Authentifizierung mit 24 h Timeout
## Tech Stack
Dieses Projekt wurden mit Unterstützung von [Claude Code](https://claude.ai/code) entwickelt.
![PHP](https://img.shields.io/badge/PHP-777BB4?logo=php&logoColor=white)
![HTML](https://img.shields.io/badge/HTML-E34F26?logo=html5&logoColor=white)
![CSS](https://img.shields.io/badge/CSS-1572B6?logo=css3&logoColor=white)
![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?logo=javascript&logoColor=black)
| Schicht | Technologie |
|---|---| |---|---|
| Webserver | Apache 2.4 | | **Kontenrahmen SKR03** | DATEV-konform, 157 Konten, mit UStVA-Kennzahlen und EÜR-Zeilennummern |
| Backend | PHP 8.3 (MVC, kein Framework) | | **Belegverwaltung** | PDF, PNG, TIFF, ZUGFeRD-XML; SHA-256 Integritätsprüfung; optionale KI-Kontierung |
| Datenbank | MariaDB 11 | | **Buchungen** | EÜR-Modell (Einnahme/Ausgabe); GoBD-konforme Trigger; Stornobuchungen; Journal |
| PDF-Generierung | mPDF 8.x | | **Anlagevermögen** | Anlagenspiegel; automatische Anlagen-Nummerierung; Buchungsworkflow mit Asset-Verknüpfung |
| Frontend | HTML, CSS, JavaScript (keine Bibliotheken) | | **Ausgangsrechnungen** | DIN 5008, PDF-Export via mPDF |
| Deployment | Docker / Docker Compose | | **UStVA** | Kennzahlen-Berechnung, ELSTER XML-Export, Drill-down |
| **EÜR** | Jahresauswertung, PDF-Export, Drill-down |
| **Kundenverwaltung** | CRUD |
| **Einstellungen** | Firmendaten, Logo, ELSTER-Steuernummer, Nummernkreise |
| **Benutzerverwaltung** | Mehrbenutzer, Session-Auth mit 24 h Timeout |
## Voraussetzungen ---
- [Docker](https://docs.docker.com/get-docker/) ≥ 24 ## Schnellstart
- [Docker Compose](https://docs.docker.com/compose/install/) ≥ 2.20 (in neueren Docker-Versionen enthalten)
- Git
## Installation
### Automatische Installation
Das Script `install.sh` übernimmt die gesamte Installation: es erkennt die Linux-Distribution, installiert git, curl und Docker, klont das Repository in das gewünschte Verzeichnis und legt die `.env`-Datei an.
Das Script muss **vor** dem Klonen des Repositories heruntergeladen werden – es erledigt das Klonen selbst:
```bash ```bash
curl -fsSL https://codeberg.org/fds2610/Steuerkram/raw/branch/main/install.sh -o install.sh curl -fsSL https://codeberg.org/fds2610/Steuerkram/raw/branch/main/install.sh -o install.sh
sudo bash install.sh sudo bash install.sh
``` cd /opt/Steuerkram
> Das Script muss als root ausgeführt werden, da es Pakete installiert und ggf. den Docker-Dienst aktiviert. Mit `sudo bash install.sh` funktioniert das ohne dauerhaft als root angemeldet zu sein.
Nach der Installation die `.env`-Datei im gewählten Installationsverzeichnis anpassen (siehe Hinweis am Ende des Scripts) und anschließend die Container starten:
```bash
cd /opt/Steuerkram # oder das gewählte Verzeichnis
docker compose up -d docker compose up -d
``` ```
--- Anwendung aufrufen: `http://localhost:8080`
### Manuelle Installation
#### 1. Repository klonen
```bash
git clone <repository-url> steuerkram
cd steuerkram
```
#### 2. Konfiguration anpassen
Kopiere `.env.example` nach `.env` und passe die Werte an:
```bash
cp .env.example .env
```
```dotenv
DB_PASS=sicheres-passwort # Datenbankpasswort – in docker-compose.yml spiegeln
APP_SECRET=zufaelliger-string # Zufälligen langen String eintragen (für Sessions)
```
Außerdem in `docker-compose.yml` das `MARIADB_PASSWORD` im `db`-Service auf denselben Wert wie `DB_PASS` setzen.
#### 3. Container starten
```bash
docker compose up -d
```
Beim ersten Start werden automatisch:
- die Datenbank initialisiert (`migrations/001_initial_schema.sql`)
- der SKR03-Kontenrahmen eingespielt (`migrations/002_seed_skr03.sql`)
- das Docker-Image mit PHP-Abhängigkeiten (mPDF) gebaut
#### 4. Anwendung aufrufen
```
http://localhost:8080
```
Beim ersten Aufruf erscheint die **Ersteinrichtung**: dort den ersten Benutzer-Account anlegen. Danach ist die Anwendung passwortgeschützt.
Weitere Benutzer können nach dem Login unter **Benutzer** in der Seitenleiste verwaltet werden.
#### 5. KI-Beleganalyse einrichten (optional)
Die KI-gestützte Belegerkennung ist standardmäßig deaktiviert. Sie kann unter **Einstellungen → KI-Kontierungsvorschlag** aktiviert werden, sobald ein LLM erreichbar ist.
**Option A – Lokales Ollama** (kein API-Schlüssel nötig, aber hoher Ressourcenbedarf):
```bash
ollama pull mistral # oder llama3.2 etc.
```
In `.env` ist keine weitere Konfiguration nötig – die App erkennt Ollama auf `localhost:11434` automatisch. Modell und URL können optional überschrieben werden:
```dotenv
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=mistral
```
**Option B – Remote-API** (OpenAI-kompatibel, z. B. OpenAI, OpenRouter, LM Studio):
```dotenv
LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini
```
> **Hinweis:** Die Ergebnisqualität hängt stark vom gewählten Modell ab. Tests mit `mistral` (lokal via Ollama) lieferten bisher mäßige Ergebnisse.
#### 6. Firmendaten hinterlegen
Nach dem ersten Login unter **Einstellungen** Firmendaten, Logo und ELSTER-Steuernummer eintragen. Diese Angaben erscheinen auf Ausgangsrechnungen und im EÜR-Export.
## Port ändern
Der Standard-Port ist `8080`. Um ihn zu ändern, passe in `docker-compose.yml` die `ports`-Zeile an:
```yaml
ports:
- "9090:80" # Beispiel: Port 9090 auf dem Host
```
## Upload-Limit anpassen
Die maximale Dateigröße für Beleganhänge ist auf **20 MB** voreingestellt (`php/uploads.ini`). Um das Limit zu ändern, die Werte in dieser Datei anpassen und den Container neu bauen:
```ini
upload_max_filesize = 20M
post_max_size = 20M
```
```bash
docker compose up -d --build
```
## Belege automatisch aus Nextcloud importieren
Belege können automatisch aus einem Nextcloud-Ordner via WebDAV importiert werden. Das CLI-Skript `scripts/nextcloud-import.php` liest alle unterstützten Dateien (PDF, JPEG, PNG, TIFF, XML) aus dem konfigurierten Ordner, legt sie als Belege an und verschiebt sie anschließend in einen Erledigte-Ordner (oder löscht sie, wenn kein Ziel-Ordner konfiguriert ist).
### Konfiguration
Die Zugangsdaten werden in der Steuerkram-UI gepflegt: **Einstellungen → Nextcloud-Belegimport**.
Empfehlung: Ein Nextcloud-App-Passwort verwenden (Nextcloud → Einstellungen → Sicherheit → App-Passwörter).
### Manueller Aufruf
```bash
docker compose exec web php scripts/nextcloud-import.php
```
### Automatisch per Cron (auf dem Host)
```cron
*/15 * * * * docker compose -f /opt/steuerkram/docker-compose.yml exec -T web \
php scripts/nextcloud-import.php >> /var/log/steuerkram-import.log 2>&1
```
Das Skript gibt beim Start eine Zusammenfassung aus (importiert / übersprungen / Fehler) und beendet sich mit Exit-Code 1 bei Fehlern.
## Datenpersistenz
| Pfad | Inhalt |
|---|---|
| `./data/mariadb/` | MariaDB-Datenbankdateien |
| Docker Volume `uploads` | Hochgeladene Belege |
Beide Pfade liegen außerhalb des Containers und bleiben bei `docker compose down` erhalten.
## Systemd-Service einrichten
Damit Steuerkram automatisch beim Systemstart startet und als Dienst verwaltet werden kann, liegt im Repository die Datei `steuerkram.service`.
#### 1. Service-Datei installieren
```bash
sudo cp steuerkram.service /etc/systemd/system/steuerkram.service
```
Die Datei setzt `WorkingDirectory=/opt/Steuerkram` voraus. Falls das Repository in ein anderes Verzeichnis geklont wurde, den Pfad in der Service-Datei anpassen:
```bash
sudo nano /etc/systemd/system/steuerkram.service
# WorkingDirectory= auf das tatsächliche Installationsverzeichnis setzen
```
#### 2. Service aktivieren und starten
```bash
sudo systemctl daemon-reload
sudo systemctl enable steuerkram # automatisch beim Systemstart
sudo systemctl start steuerkram
```
#### 3. Status prüfen
```bash
sudo systemctl status steuerkram
journalctl -u steuerkram -f # Live-Log inkl. Migrations-Ausgabe
```
#### Wichtige Service-Befehle
| Befehl | Wirkung |
|---|---|
| `sudo systemctl start steuerkram` | Container starten |
| `sudo systemctl stop steuerkram` | Container stoppen |
| `sudo systemctl restart steuerkram` | Neustart (z.B. nach Update) |
| `sudo systemctl status steuerkram` | Aktueller Status |
## Backup
```bash
bash scripts/backup.sh
```
Das Skript erstellt ein Dump der Datenbank sowie ein Archiv der Uploads im Verzeichnis `backups/`.
## Update
Seit dem 11.04.2026 bin ich mit meiner Software für mich selber produktiv. Ab diesem Zeitpunkt sollten keine breaking changes mehr vorkommen.
Datenbankmigrationen werden **automatisch** beim nächsten Container-Start eingespielt – kein manueller Eingriff nötig. Das Script `scripts/migrate.php` prüft beim Start, welche Migrations-Dateien noch nicht angewendet wurden, und führt sie der Reihe nach aus.
### Vollständige Update-Anleitung
Die folgenden Schritte sichern einen vollständigen und sicheren Update-Ablauf. Alle Befehle im Steuerkram-Verzeichnis ausführen.
#### Schritt 1 – Datenbank sichern
Vor jedem Update ein Backup erstellen:
```bash
bash scripts/backup.sh
```
Das Backup landet in `backups/`. Alternativ manuell:
```bash
docker compose exec db mariadb-dump -u steuerkram -psteuerkram steuerkram \
> ~/steuerkram_backup_$(date +%Y%m%d_%H%M).sql
```
#### Schritt 2 – Aktuellen Code holen
```bash
git pull
```
Prüfen, ob neue Migrations-Dateien enthalten sind:
```bash
git log --oneline -5
```
#### Schritt 3 – Container neu bauen und starten
```bash
docker compose up -d --build
```
Dieser Befehl baut das PHP-Image neu (falls sich `Dockerfile` oder `composer.json` geändert haben) und startet alle Container. Der Web-Container führt beim Start automatisch `scripts/migrate.php` aus.
#### Schritt 4 – Migrationen prüfen
```bash
docker compose logs web | grep migrate
```
Erwartete Ausgabe bei erfolgreicher Migration:
```
[migrate] Starte Migrations-Prüfung...
[migrate] Führe aus: NNN_beschreibung.sql
[migrate] N Migration(en) erfolgreich angewendet.
```
Oder wenn alles bereits aktuell ist:
```
[migrate] Datenbank ist aktuell – keine Migrationen notwendig.
```
Falls die Ausgabe einen Fehler enthält, das Backup aus Schritt 1 einspielen:
```bash
docker compose exec -T db mariadb -u steuerkram -psteuerkram steuerkram \
< ~/steuerkram_backup_YYYYMMDD_HHMM.sql
```
#### Schritt 5 – Anwendung prüfen
```bash
docker compose ps # alle Container müssen "running" sein
docker compose logs web # keine PHP-Fehler oder Exceptions
```
Anschließend im Browser unter `http://localhost:8080` (oder dem konfigurierten Port) einloggen und stichprobenartig Belege und Buchungen prüfen.
--- ---
#### Ohne Systemd-Service (Kurzform) ## Dokumentation
```bash | Dokument | Inhalt |
bash scripts/backup.sh |---|---|
git pull | [Installation](docs/installation.md) | Docker-Setup, Systemd-Service, Port, Upload-Limit |
docker compose up -d --build | [Konfiguration](docs/konfiguration.md) | Firmendaten, Nummernkreise, KI-Beleganalyse, Nextcloud-Import |
docker compose logs web | grep migrate | [Funktionen](docs/funktionen.md) | Alle Features im Detail |
``` | [Anlagevermögen](docs/anlagevermögen.md) | Anlagenspiegel, Buchungsworkflow, Nummernkreis |
| [Update & Backup](docs/update-backup.md) | Update-Anleitung, Backup, Datenpersistenz |
| [Automatisierung](docs/automatisierung.md) | Automatisierungsagent, Ideenagent, Support |
| [Berechnungslogik](docs/berechnungslogik.md) | UStVA-Kennzahlen und EÜR-Zuordnungsregeln |
| [Kontenrahmen](docs/kontenrahmen.md) | Vollständige SKR03-Kontenliste |
#### Mit Systemd-Service (Kurzform) ---
```bash
bash scripts/backup.sh
git pull
docker compose build
sudo systemctl restart steuerkram
journalctl -u steuerkram | grep migrate
```
## GoBD-Hinweise ## GoBD-Hinweise
- Gebuchte Sätze können nicht geändert oder gelöscht werden (MariaDB `BEFORE UPDATE/DELETE` Trigger). - Gebuchte Sätze können nicht geändert oder gelöscht werden (MariaDB `BEFORE UPDATE/DELETE` Trigger).
- Korrekturen erfolgen ausschließlich über Stornobuchungen. - Korrekturen erfolgen ausschließlich über Stornobuchungen.
- Jeder hochgeladene Beleg erhält einen SHA-256 Hash zur Integritätsprüfung. - Jeder hochgeladene Beleg erhält einen SHA-256 Hash zur Integritätsprüfung.
## Kontenrahmen SKR03
Der enthaltene Kontenrahmen basiert auf dem DATEV SKR03 2026, zugeschnitten auf EÜR-Buchhalter (IST-Versteuerung). Alle Konten sind mit geprüften UStVA-Kennzahlen (ELSTER) und EÜR-Zeilennummern (Anlage EÜR 2024) hinterlegt.
Vollständige Dokumentation: [`Kontenrahmen.md`](Kontenrahmen.md)
## Berechnungslogik UStVA und EÜR
Detaillierte Informationen darüber, welche Buchungsattribute und Konten in welche Positionen der UStVA (ELSTER-Kennzahlen) bzw. der EÜR einfließen, sind in [`BERICHTE.md`](BERICHTE.md) dokumentiert.
## Support
Issues können im [Codeberg-Repo](https://codeberg.org/fds2610/Steuerkram/issues) gemeldet werden. Mit dem Label **`automate`** werden sie automatisch verarbeitet.
### Automatisierter Agent
Ein stündlich per Cron gestarteter Agent (Claude CLI) verarbeitet Issues mit dem Label `automate` nacheinander – mit Lockfile-Schutz gegen Parallelläufe. Mehrere offene Tickets werden in einer Sitzung sequenziell abgearbeitet.
#### Ablauf je Ticket
1. Issue-Body und alle Kommentare laden (inkl. Diskussionsergebnisse früherer Rückfragen)
2. Relevante Codebase-Dateien lesen
3. **Klarheitscheck**: Sind die Anforderungen eindeutig? Falls nicht → Rückfragen als Kommentar posten, `automate`-Label entfernen, warten
4. Analyse mit Claude Opus (Ursache, Lösungsplan, Risiken)
5. Lösung implementieren
6. Tests ausführen (`php tests/run.php`), Fehler beheben
7. Commit & Push: `Fix #NR: Kurzbeschreibung`
8. Kommentar mit Zusammenfassung im Issue posten
9. Labels aktualisieren, Issue offen lassen
#### Label-Ausgänge
| Ergebnis | `automate` | gesetztes Label |
|---|---|---|
| Erfolgreich umgesetzt | entfernt | `testing` |
| Unklar / Rückfrage offen | entfernt | *(keins)* |
| Zu riskant / abgelehnt | entfernt | `abgelehnt` |
## Lizenz
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
Dieses Projekt steht unter der MIT-Lizenz – siehe [LICENSE.md](LICENSE.md) für Details.

69
docs/anlagevermögen.md Normal file
View file

@ -0,0 +1,69 @@
# Anlagevermögen
## Überblick
Der Bereich **Betriebsvermögen → Anlagevermögen** führt einen Anlagenspiegel für abnutzbare Wirtschaftsgüter. Jedes Wirtschaftsgut ist mit einem Anlagevermögenskonto des SKR03 verknüpft und erhält eine eindeutige Anlagen-Nummer.
---
## Anlagen-Nummernkreis
Anlagen-Nummern werden automatisch im Format `{Präfix}-{Jahr}-{laufende Nummer}` vergeben, z.B. `ANL-2026-0001`.
Der Präfix ist unter **Einstellungen → Nummernkreise → Anlagen-Präfix** konfigurierbar (Standard: `ANL`).
---
## Anlagenspiegel
Die Liste unter **Anlagevermögen** zeigt alle erfassten Wirtschaftsgüter mit folgenden Spalten:
| Spalte | Beschreibung |
|---|---|
| Nr. | Anlagen-Nummer (automatisch vergeben) |
| Anschaffungsdatum | Datum der Anschaffung |
| Anlageart | Verknüpftes SKR03-Anlagevermögenskonto |
| Wirtschaftsgut | Bezeichnung |
| Anschaffungskosten | Nettobetrag der Anschaffung |
| Zugänge | Nachträgliche Anschaffungskosten |
| Abgänge | Wertminderungen durch Verkauf/Abgang |
| Abschreibungen | AfA des laufenden Wirtschaftsjahres |
Über das Bleistift-Symbol gelangt man zur Bearbeitungsmaske, über das Papierkorb-Symbol kann ein Wirtschaftsgut gelöscht werden (nur wenn keine Buchungen verknüpft sind).
---
## Buchungsworkflow
Wird beim Erfassen einer Buchung ein **Anlagevermögenskonto** als Kategorie gewählt, öffnet sich automatisch ein Dialog:
**Option 1 – Neues Wirtschaftsgut anlegen**
Das System legt automatisch ein neues Anlagegut an:
- Bezeichnung ← Buchungstext
- Anschaffungsdatum ← Buchungsdatum
- Anschaffungskosten ← Nettobetrag
**Option 2 – Bestehendes Wirtschaftsgut auswählen**
Es wird die Liste der Wirtschaftsgüter angezeigt, die mit dem gewählten Anlagevermögenskonto verknüpft sind. Nach der Auswahl wird die Buchung mit dem vorhandenen Anlagegut verknüpft.
In beiden Fällen wird die `asset_id` in der Buchungszeile gespeichert.
---
## Anzeige in Buchungstabellen
In allen Buchungsübersichten (Beleg-Detail, Journal, UStVA-Drill-down, EÜR-Drill-down) erscheint eine **Anlage**-Spalte. Sie zeigt die Anlagen-Nummer als direkten Link zur Bearbeitungsmaske des Wirtschaftsguts. Falls für ein älteres Wirtschaftsgut keine Anlagen-Nummer hinterlegt ist, wird stattdessen die Bezeichnung angezeigt.
---
## Anlagen-Stammdaten bearbeiten
Folgende Felder können nachträglich angepasst werden:
- Bezeichnung
- Anlageart (SKR03-Konto)
- Anschaffungsdatum und -kosten
- Zugänge und Abgänge
- Abschreibung laufendes Jahr
- Nutzungsdauer (in Jahren)
- Notizen

50
docs/automatisierung.md Normal file
View file

@ -0,0 +1,50 @@
# Automatisierung & Support
## Automatisierungsagent
Issues mit dem Label **`automate`** im [Codeberg-Repo](https://codeberg.org/fds2610/Steuerkram/issues) werden automatisch durch einen stündlich per Cron gestarteten Agenten (Claude CLI) verarbeitet. Mehrere offene Tickets werden in einer Sitzung sequenziell abgearbeitet. Ein Lockfile verhindert parallele Läufe.
### Ablauf je Ticket
1. Issue-Body und alle Kommentare laden (inkl. Diskussionsergebnisse früherer Rückfragen)
2. Relevante Codebase-Dateien lesen
3. **Klarheitscheck**: Sind die Anforderungen eindeutig? Falls nicht → Rückfragen als Kommentar posten, `automate`-Label entfernen, warten
4. Analyse (Ursache, Lösungsplan, Risiken)
5. Lösung implementieren
6. Tests ausführen (`php tests/run.php`), Fehler beheben
7. Commit & Push: `Fix #NR: Kurzbeschreibung`
8. Kommentar mit Zusammenfassung im Issue posten
9. Labels aktualisieren, Issue offen lassen
### Label-Ausgänge
| Ergebnis | `automate` | gesetztes Label |
|---|---|---|
| Erfolgreich umgesetzt | entfernt | `testing` |
| Unklar / Rückfrage offen | entfernt | *(keins)* |
| Zu riskant / abgelehnt | entfernt | `abgelehnt` |
### Manuell starten
```bash
/home/fds/projects/Steuerkram/.claude/automate-run.sh
```
---
## Ideenagent
Ein separater Agent sammelt und bewertet Ideen zur Weiterentwicklung. Er läuft ebenfalls per Cron.
```bash
/home/fds/projects/Steuerkram/.claude/ideenagent-run.sh
```
---
## Support
Issues können im [Codeberg-Repo](https://codeberg.org/fds2610/Steuerkram/issues) gemeldet werden.
- Mit dem Label **`automate`** werden sie automatisch verarbeitet (siehe oben).
- Ohne Label landen sie in der normalen Issue-Queue.

0
BERICHTE.md → docs/berechnungslogik.md
View file

91
docs/funktionen.md Normal file
View file

@ -0,0 +1,91 @@
# Funktionen
## Kontenrahmen SKR03
DATEV-konformer SKR03 2026 mit 157 Systemkonten (Klassen 0, 1, 2, 4, 8), zugeschnitten auf EÜR-Buchhalter ohne Bilanzierungspflicht. Alle Konten sind mit geprüften UStVA-Kennzahlen (ELSTER) und EÜR-Zeilennummern hinterlegt.
Vollständige Kontenliste: [kontenrahmen.md](kontenrahmen.md)
---
## Belegverwaltung
- Upload von PDF, PNG, JPEG, TIFF und ZUGFeRD-XML
- SHA-256 Integritätsprüfung je Datei
- Automatischer Weißrand-Zuschnitt bei JPEG/PNG via GD
- KI-gestützter Kontierungsvorschlag (optional, siehe [konfiguration.md](konfiguration.md))
- Nextcloud-Import via WebDAV (optional)
- Belege können nicht gelöscht werden, solange Buchungen darauf verweisen (GoBD)
---
## Buchungen
EÜR-Buchungsmodell (Einnahme/Ausgabe) mit Kategorie- und Zahlungskonto.
- **Steuerarten** für Auslandsumsätze: Inland, steuerfreie ig. Lieferung (Kz 41), steuerfreie Ausfuhr (Kz 44), ig. Erwerb 19 % (Kz 89/91), ig. Erwerb 7 % (Kz 93/94)
- **Bewirtungsausgaben**: automatischer Split 70 %/30 % bei Konten 4650, 4651, 4652
- **Eigenanteil** (30 %) bei Telefon/Internet (Konto 4940): optional zubuchbar
- **Stornobuchungen**: GoBD-konforme Gegenbuchung statt Löschung
- **GoBD-Schutz**: MariaDB `BEFORE UPDATE/DELETE`-Trigger verhindern nachträgliche Manipulation gebuchter Sätze
- **Journal**: gefilterte Übersicht aller Buchungen mit CSV-Export
---
## Anlagevermögen
Anlagenspiegel für abnutzbare Wirtschaftsgüter – siehe [anlagevermögen.md](anlagevermögen.md).
---
## Kundenverwaltung
CRUD für Kundenstammdaten. Kunden werden beim Erstellen von Ausgangsrechnungen ausgewählt.
---
## Ausgangsrechnungen
- DIN 5008-konformes Layout
- PDF-Export via mPDF
- Automatische Rechnungsnummer (konfiguriertes Präfix + Jahrgang + laufende Nummer)
- Direkte Verknüpfung mit Belegverwaltung
---
## UStVA (Umsatzsteuervoranmeldung)
- Monatliche Kennzahlen-Berechnung aus Buchungen (Kz 81, 83, 86, 84, 35, 41, 44, 61, 62, 67, 66, 69)
- ELSTER XML-Export
- Drill-down: Klick auf eine Kennzahl zeigt alle zugehörigen Buchungszeilen
Zuordnungsregeln: [berechnungslogik.md](berechnungslogik.md)
---
## EÜR (Einnahmen-Überschuss-Rechnung)
- Jahresauswertung: Einnahmen, Ausgaben, Gewinn je Kategorie-Konto
- Nicht abzugsfähige Betriebsausgaben (§ 4 Abs. 5 EStG, EÜR-Zeile 51) in separatem Abschnitt
- PDF-Export
- Drill-down: Klick auf ein Konto zeigt alle zugehörigen Buchungszeilen
Zuordnungsregeln: [berechnungslogik.md](berechnungslogik.md)
---
## Einstellungen
- Firmendaten und Logo (erscheinen auf Rechnungen und im EÜR/UStVA-Export)
- ELSTER-Steuernummer
- Nummernkreis-Präfixe für Belege, Rechnungen und Anlagen
- KI-Kontierungsvorschlag (Ollama oder OpenAI-kompatible API)
- Nextcloud-Belegimport (WebDAV-Zugangsdaten)
---
## Benutzerverwaltung
- Benutzer anlegen, bearbeiten, deaktivieren und löschen
- Session-basierte Authentifizierung mit 24 h Timeout
- Erste Benutzeranlage über Ersteinrichtungs-Dialog beim ersten Aufruf

140
docs/installation.md Normal file
View file

@ -0,0 +1,140 @@
# Installation
## Voraussetzungen
- [Docker](https://docs.docker.com/get-docker/) ≥ 24
- [Docker Compose](https://docs.docker.com/compose/install/) ≥ 2.20 (in neueren Docker-Versionen enthalten)
- Git
---
## Automatische Installation
Das Script `install.sh` übernimmt die gesamte Installation: es erkennt die Linux-Distribution, installiert git, curl und Docker, klont das Repository in das gewünschte Verzeichnis und legt die `.env`-Datei an.
Das Script muss **vor** dem Klonen des Repositories heruntergeladen werden – es erledigt das Klonen selbst:
```bash
curl -fsSL https://codeberg.org/fds2610/Steuerkram/raw/branch/main/install.sh -o install.sh
sudo bash install.sh
```
> Das Script muss als root ausgeführt werden, da es Pakete installiert und ggf. den Docker-Dienst aktiviert.
Nach der Installation die `.env`-Datei im gewählten Installationsverzeichnis anpassen und die Container starten:
```bash
cd /opt/Steuerkram # oder das gewählte Verzeichnis
docker compose up -d
```
---
## Manuelle Installation
### 1. Repository klonen
```bash
git clone <repository-url> steuerkram
cd steuerkram
```
### 2. Konfiguration anpassen
```bash
cp .env.example .env
```
```dotenv
DB_PASS=sicheres-passwort # Datenbankpasswort – in docker-compose.yml spiegeln
APP_SECRET=zufaelliger-string # Zufälligen langen String eintragen (für Sessions)
```
Außerdem in `docker-compose.yml` das `MARIADB_PASSWORD` im `db`-Service auf denselben Wert wie `DB_PASS` setzen.
### 3. Container starten
```bash
docker compose up -d
```
Beim ersten Start werden automatisch:
- die Datenbank initialisiert
- der SKR03-Kontenrahmen eingespielt
- das Docker-Image mit PHP-Abhängigkeiten (mPDF) gebaut
### 4. Anwendung aufrufen
```
http://localhost:8080
```
Beim ersten Aufruf erscheint die **Ersteinrichtung**: dort den ersten Benutzer-Account anlegen. Danach ist die Anwendung passwortgeschützt.
---
## Port ändern
Der Standard-Port ist `8080`. Um ihn zu ändern, die `ports`-Zeile in `docker-compose.yml` anpassen:
```yaml
ports:
- "9090:80" # Beispiel: Port 9090 auf dem Host
```
---
## Upload-Limit anpassen
Die maximale Dateigröße für Beleganhänge ist auf **20 MB** voreingestellt (`php/uploads.ini`). Um das Limit zu ändern:
```ini
upload_max_filesize = 20M
post_max_size = 20M
```
```bash
docker compose up -d --build
```
---
## Systemd-Service einrichten
Damit Steuerkram automatisch beim Systemstart startet, liegt im Repository die Datei `steuerkram.service`.
### 1. Service-Datei installieren
```bash
sudo cp steuerkram.service /etc/systemd/system/steuerkram.service
```
Die Datei setzt `WorkingDirectory=/opt/Steuerkram` voraus. Falls das Repository woanders liegt, den Pfad anpassen:
```bash
sudo nano /etc/systemd/system/steuerkram.service
```
### 2. Service aktivieren und starten
```bash
sudo systemctl daemon-reload
sudo systemctl enable steuerkram
sudo systemctl start steuerkram
```
### 3. Status prüfen
```bash
sudo systemctl status steuerkram
journalctl -u steuerkram -f # Live-Log inkl. Migrations-Ausgabe
```
### Wichtige Befehle
| Befehl | Wirkung |
|---|---|
| `sudo systemctl start steuerkram` | Container starten |
| `sudo systemctl stop steuerkram` | Container stoppen |
| `sudo systemctl restart steuerkram` | Neustart (z.B. nach Update) |
| `sudo systemctl status steuerkram` | Aktueller Status |

88
docs/konfiguration.md Normal file
View file

@ -0,0 +1,88 @@
# Konfiguration
## Firmendaten hinterlegen
Nach dem ersten Login unter **Einstellungen** Firmendaten, Logo und ELSTER-Steuernummer eintragen. Diese Angaben erscheinen auf Ausgangsrechnungen und im EÜR/UStVA-Export.
---
## Nummernkreise
Unter **Einstellungen → Nummernkreise** können Präfixe für die automatisch vergebenen Nummern konfiguriert werden:
| Nummernkreis | Standard | Beispiel |
|---|---|---|
| Belege | `BLG` | `BLG-2026-0001` |
| Ausgangsrechnungen | `RE` | `RE-2026-0001` |
| Anlagen | `ANL` | `ANL-2026-0001` |
Das Format ist immer `{Präfix}-{Jahr}-{laufende Nummer}`. Die laufende Nummer wird automatisch hochgezählt und kann nicht zurückgesetzt werden (GoBD).
---
## KI-Beleganalyse einrichten
Die KI-gestützte Belegerkennung ist standardmäßig deaktiviert. Sie kann unter **Einstellungen → KI-Kontierungsvorschlag** aktiviert werden, sobald ein LLM erreichbar ist.
### Option A – Lokales Ollama
Kein API-Schlüssel nötig, aber hoher Ressourcenbedarf:
```bash
ollama pull mistral # oder llama3.2 etc.
```
In `.env` ist keine weitere Konfiguration nötig – die App erkennt Ollama auf `localhost:11434` automatisch. Modell und URL können optional überschrieben werden:
```dotenv
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=mistral
```
### Option B – Remote-API (OpenAI-kompatibel)
z.B. OpenAI, OpenRouter, LM Studio:
```dotenv
LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini
```
> **Hinweis:** Die Ergebnisqualität hängt stark vom gewählten Modell ab. Tests mit `mistral` (lokal via Ollama) lieferten bisher mäßige Ergebnisse.
---
## Nextcloud-Import einrichten
Belege können automatisch aus einem Nextcloud-Ordner via WebDAV importiert werden. Das CLI-Skript `scripts/nextcloud-import.php` liest alle unterstützten Dateien (PDF, JPEG, PNG, TIFF, XML) aus dem konfigurierten Ordner, legt sie als Belege an und verschiebt sie anschließend in einen Erledigte-Ordner.
### Zugangsdaten konfigurieren
Die Zugangsdaten werden in der Steuerkram-UI gepflegt: **Einstellungen → Nextcloud-Belegimport**.
Empfehlung: Ein Nextcloud-App-Passwort verwenden (Nextcloud → Einstellungen → Sicherheit → App-Passwörter).
### Manueller Aufruf
```bash
docker compose exec web php scripts/nextcloud-import.php
```
### Automatisch per Cron
Cron-Eintrag auf dem Host anlegen (`crontab -e`):
```cron
*/15 * * * * docker compose -f /opt/Steuerkram/docker-compose.yml exec -T web \
php scripts/nextcloud-import.php >> /var/log/steuerkram-import.log 2>&1
```
> Das `-T`-Flag ist bei Cron zwingend erforderlich – ohne TTY schlägt `docker compose exec` sonst still fehl.
Damit `docker compose exec` ohne `sudo` funktioniert, muss der User in der Docker-Gruppe sein:
```bash
sudo usermod -aG docker $USER
# Danach neu einloggen
```

0
Kontenrahmen.md → docs/kontenrahmen.md
View file

106
docs/update-backup.md Normal file
View file

@ -0,0 +1,106 @@
# Update & Backup
## Backup
```bash
bash scripts/backup.sh
```
Das Skript erstellt einen Dump der Datenbank sowie ein Archiv der Uploads im Verzeichnis `backups/`. Die Rotation erfolgt nach folgendem Schema:
- 7 Tages-Backups
- 4 Wochen-Backups
- 12 Monats-Backups
Ein `flock`-Lock verhindert parallele Läufe bei Verzögerungen.
### Manuelles Backup
```bash
docker compose exec db mariadb-dump -u steuerkram -psteuerkram steuerkram \
> ~/steuerkram_backup_$(date +%Y%m%d_%H%M).sql
```
---
## Datenpersistenz
| Pfad | Inhalt |
|---|---|
| `./data/mariadb/` | MariaDB-Datenbankdateien |
| Docker Volume `uploads` | Hochgeladene Belege |
Beide Pfade liegen außerhalb des Containers und bleiben bei `docker compose down` erhalten.
---
## Update
Datenbankmigrationen werden **automatisch** beim nächsten Container-Start eingespielt. Das Script `scripts/migrate.php` prüft beim Start, welche Migrations-Dateien noch nicht angewendet wurden, und führt sie der Reihe nach aus.
### Vollständige Update-Anleitung
#### Schritt 1 – Datenbank sichern
```bash
bash scripts/backup.sh
```
#### Schritt 2 – Aktuellen Code holen
```bash
git pull
```
#### Schritt 3 – Container neu bauen und starten
```bash
docker compose up -d --build
```
Dieser Befehl baut das PHP-Image neu (falls sich `Dockerfile` oder `composer.json` geändert haben) und startet alle Container. Der Web-Container führt beim Start automatisch `scripts/migrate.php` aus.
#### Schritt 4 – Migrationen prüfen
```bash
docker compose logs web | grep migrate
```
Erwartete Ausgabe:
```
[migrate] Starte Migrations-Prüfung...
[migrate] Führe aus: NNN_beschreibung.sql
[migrate] N Migration(en) erfolgreich angewendet.
```
Falls ein Fehler auftritt, das Backup aus Schritt 1 einspielen:
```bash
docker compose exec -T db mariadb -u steuerkram -psteuerkram steuerkram \
< ~/steuerkram_backup_YYYYMMDD_HHMM.sql
```
#### Schritt 5 – Anwendung prüfen
```bash
docker compose ps # alle Container müssen "running" sein
docker compose logs web # keine PHP-Fehler oder Exceptions
```
---
### Kurzform ohne Systemd
```bash
bash scripts/backup.sh && git pull && docker compose up -d --build
docker compose logs web | grep migrate
```
### Kurzform mit Systemd
```bash
bash scripts/backup.sh && git pull && docker compose build
sudo systemctl restart steuerkram
journalctl -u steuerkram | grep migrate
```