Annas Rechnungsmanager

Buchhaltungs- und Rechnungsverwaltungssystem für Steuerberater und Buchhalter mit Mandantenverwaltung.

Features

• Mandantenverwaltung — Mehrere Unternehmen verwalten, archivieren und wiederherstellen
• Rechnungen — Erstellen, versenden, bezahlen, als PDF exportieren (§14 UStG konform)
• Kundenverwaltung — Kundenstammdaten pro Mandant
• Steuerberichte — USt-Voranmeldung, monatliche & quartalsweise Auswertungen
• Benutzerverwaltung — Mehrere Benutzer mit Rollen (USER / ADMIN)
• Audit-Log — Protokollierung aller relevanten Aktionen mit Benutzer und IP
• Archiv — Archivierte Mandanten mit vollständiger Historie einsehbar
• Papierkorb — Gelöschte Rechnungen wiederherstellbar

Tech Stack

• React Router v7 (Framework Mode, SSR) + TypeScript
• MariaDB via Prisma ORM
• Cookie-Session-Auth (bcryptjs)
• Tailwind CSS v4 + shadcn/ui
• @react-pdf/renderer für PDF-Generierung
• Docker für Datenbank und Deployment

---

Lokale Entwicklung

Voraussetzungen

• Node.js 22+
• Docker + Docker Compose

Installation

npm install

Umgebungsvariablen

.env im Projektstamm anlegen:

DATABASE_URL="mysql://annas_user:annas_password@localhost:3306/annas_rechnungen"
AUTH_SECRET="dein-zufaelliger-geheimer-string"

Datenbank einrichten

npx prisma migrate deploy   # Migrationen ausführen
npm run db:seed             # Demo-Daten einspielen (optional)

Dev-Server starten

npm run dev

Startet den Vite-Dev-Server auf http://localhost:5173.

---

Deployment

Erstes Deployment

1. Image bauen:

docker build -t annasrechnungsmanager:latest .

2. Secrets setzen (Shell-Exports oder .env-Datei):

export AUTH_SECRET="langer-zufaelliger-string"
export ADMIN_PASSWORD="sicheres-startpasswort"   # nur beim ersten Start

3. Stack starten:

docker compose up -d

Beim ersten Start mit gesetztem ADMIN_PASSWORD:

• Prisma-Migrationen werden automatisch ausgeführt
• Admin-Benutzer (username: admin) wird angelegt oder aktualisiert

4. ADMIN_PASSWORD entfernen (nach erfolgreichem Login und eigenem Passwort setzen).

Die App läuft auf http://localhost:3000.

Folge-Deployments

docker build -t annasrechnungsmanager:latest .
docker compose up -d --no-deps app

Migrationen werden beim Start automatisch angewendet. ADMIN_PASSWORD ist nicht erneut nötig.

---

CI/CD (Gitea Actions)

Die Pipeline liegt in .gitea/workflows/build.yml und baut/pusht bei jedem Push auf main ein Docker-Image.

Voraussetzungen

• Secret REGISTRY_TOKEN ist im Repository gesetzt
• Der Token hat Berechtigung zum Push in die Gitea Container Registry
• Der Registry-Host ist vom Runner aus erreichbar

Aktuelle Registry-Konfiguration

Die Pipeline nutzt aktuell:

• REGISTRY=git.henryathome.home64.de
• Image-Name aus ${{ gitea.repository }}
• Tags: kurzer Commit-SHA + latest (auf Default-Branch)

Häufiger Fehler: i/o timeout beim Push

Fehlerbild (vereinfacht):

failed to push ... Head "https://.../v2/.../blobs/...": dial tcp ...:443: i/o timeout

Typische Ursache:

• Die Registry-Adresse ist intern (z. B. *.svc.cluster.local) und vom CI-Runner nicht erreichbar.

Lösung:

• In .gitea/workflows/build.yml einen extern erreichbaren Host bei REGISTRY eintragen.
• Sicherstellen, dass DNS, Firewall und Portfreigaben vom Runner zur Registry passen.
• Prüfen, ob HTTPS korrekt terminiert ist (Zertifikat/Reverse Proxy), da Buildx standardmäßig per HTTPS pusht.

---

Admin-Benutzer & Recovery

Admin-Passwort setzen (im laufenden Container)

docker exec -e ADMIN_PASSWORD=neuespasswort annas_app node scripts/setup-admin.js

Erstellt oder aktualisiert den Benutzer admin (idempotent). Mindestens 8 Zeichen.

Passwort eines beliebigen Benutzers zurücksetzen

docker exec -it annas_app node scripts/reset-password.js --username anna --password neuespasswort

Zeigt alle vorhandenen Benutzer an, wenn der angegebene Username nicht existiert.

Passwort im laufenden Betrieb ändern

Jeder eingeloggte Benutzer kann sein Passwort über das Schlüssel-Icon in der Topbar ändern (/settings/password).

---

Benutzerverwaltung (Admin)

Erreichbar über den Admin-Button in der Topbar (nur für Benutzer mit Rolle ADMIN).

• Benutzer anlegen, bearbeiten, löschen
• Rollen vergeben: USER oder ADMIN
• Audit-Log einsehen (Aktion, Benutzer, IP-Adresse, Zeitstempel)

Login ist möglich mit Benutzername oder E-Mail-Adresse.

---

Scripts

Befehl	Beschreibung
npm run dev	Dev-Server starten
npm run build	Produktions-Build
npm run start	Produktions-Server starten
npm run typecheck	TypeScript prüfen
npm run db:migrate	Prisma Migrationen ausführen (Dev)
npm run db:seed	Demo-Daten einspielen
npm run db:studio	Prisma Studio öffnen
npm run setup-admin	Admin-Benutzer anlegen / Passwort setzen
npm run reset-password	Passwort eines Benutzers zurücksetzen

Beispiele (Entwicklung):

# Admin-Passwort setzen
ADMIN_PASSWORD=geheim npm run setup-admin

# Passwort zurücksetzen
npm run reset-password -- --username anna --password neuespasswort

---

Projektstruktur

app/
  components/         UI-Komponenten (ui/, layout/, company/, invoice/)
  lib/                Hilfsfunktionen (prisma, tax, utils, invoice-number, logger)
  routes/             Route-Dateien (React Router v7, file-based)
    admin.*           Admin-Bereich (Benutzerverwaltung, Audit-Log)
    api.*             REST-API-Routen (resource routes)
    settings.*        Benutzereinstellungen (Passwort ändern)
    archiv.tsx        Archiv-Übersicht (archivierte Mandanten)
  session.server.ts   Auth (Login via Username/E-Mail, Logout, Session)
  types/              Gemeinsame TypeScript-Typen
scripts/
  setup-admin.ts      Admin-Benutzer anlegen / Passwort setzen
  reset-password.ts   Recovery: Passwort eines Benutzers zurücksetzen
prisma/
  schema.prisma       Datenbankschema
  migrations/         Migrationsverlauf
  seed.ts             Demo-Daten

---

Rechnungs-Compliance (§14 UStG)

Alle PDFs enthalten die gesetzlich vorgeschriebenen Pflichtangaben:

• Name & Anschrift Rechnungssteller und -empfänger
• Steuernummer / USt-IdNr. des Ausstellers
• Rechnungsdatum & fortlaufende Rechnungsnummer
• Leistungsdatum / Lieferdatum
• Leistungsbeschreibung
• Nettobetrag, USt-Satz, USt-Betrag, Bruttobetrag