335 lines
12 KiB
Markdown
335 lines
12 KiB
Markdown
> **Achtung! work in progress** – es kann zu BREAKING CHANGES kommen. Ich ändere diese Phase der schnellen Änderungen erst, wenn ich mit meiner Software selber produktiv gehe.
|
||
|
||
# Steuerkram
|
||
|
||
Self-hosted Buchhaltungs- und Steueranwendung für deutsche Freiberufler und Kleinunternehmer. Entwickelt als datensouveräne Alternative zu SaaS-Diensten.
|
||
|
||
## Funktionsumfang
|
||
|
||
- **Kontenrahmen SKR03** – DATEV-konformer SKR03 mit 157 Systemkonten (Klassen 0, 1, 2, 4, 8); zugeschnitten auf EÜR-Buchhalter ohne Bilanzierung (CRUD)
|
||
- **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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
| Schicht | Technologie |
|
||
|---|---|
|
||
| Webserver | Apache 2.4 |
|
||
| Backend | PHP 8.3 (MVC, kein Framework) |
|
||
| Datenbank | MariaDB 11 |
|
||
| PDF-Generierung | mPDF 8.x |
|
||
| Frontend | HTML, CSS, JavaScript (keine Bibliotheken) |
|
||
| Deployment | Docker / Docker Compose |
|
||
|
||
## 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
|
||
|
||
## 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
|
||
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. 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
|
||
```
|
||
|
||
---
|
||
|
||
### 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
|
||
|
||
Umgebungsvariablen in der `.env`-Datei:
|
||
|
||
```env
|
||
NEXTCLOUD_URL=https://cloud.example.com
|
||
NEXTCLOUD_USER=meinbenutzername
|
||
NEXTCLOUD_PASS=mein-app-passwort
|
||
NEXTCLOUD_FOLDER=/Belege/Import # Ordner in Nextcloud, der überwacht wird
|
||
NEXTCLOUD_DONE=/Belege/Importiert # Ziel nach Import (leer lassen = Datei löschen)
|
||
```
|
||
|
||
**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
|
||
|
||
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.
|
||
|
||
#### Ohne Systemd-Service (manuell)
|
||
|
||
```bash
|
||
git pull
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Der Web-Container führt `scripts/migrate.php` automatisch beim Start aus. Die Ausgabe ist im Container-Log sichtbar:
|
||
|
||
```bash
|
||
docker compose logs web
|
||
```
|
||
|
||
#### Mit Systemd-Service
|
||
|
||
```bash
|
||
git pull
|
||
docker compose build
|
||
sudo systemctl restart steuerkram
|
||
```
|
||
|
||
Migrations-Ausgabe im Journal:
|
||
|
||
```bash
|
||
journalctl -u steuerkram -f
|
||
```
|
||
|
||
## GoBD-Hinweise
|
||
|
||
- Gebuchte Sätze können nicht geändert oder gelöscht werden (MariaDB `BEFORE UPDATE/DELETE` Trigger).
|
||
- Korrekturen erfolgen ausschließlich über Stornobuchungen.
|
||
- 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
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
|
||
Dieses Projekt steht unter der MIT-Lizenz – siehe [LICENSE.md](LICENSE.md) für Details.
|