Nebenkostenabrechnungssystem

Automatisiertes System für Nebenkosten- und Hausgeldabrechnungen für ein 12-Parteien-Haus.

Repository & Deployment

• Git: ssh://git@git.braun-bonn.de:2222/cfbraun/vermietung2.git
• Registry: git.braun-bonn.de:2222/cfbraun/vermietung2
• CI/CD: Forgejo Actions (self-hosted in Kubernetes)
• Production: https://vermietung.braun-bonn.de (Kubernetes cluster "minerva")

Features

• Automatischer HBCI-Transaktionsabruf
• KI-basierte Transaktionskategorisierung
• Kostenverteilung nach verschiedenen Schlüsseln
• PDF-Generierung für Abrechnungen
• Brunata/Techem Integration
• Webbasierte Verwaltungsoberfläche

Technologie-Stack

Backend

• FastAPI (Python 3.11+)
• PostgreSQL mit SQLAlchemy
• Celery für asynchrone Verarbeitung
• Redis als Message Broker

Frontend

• SvelteKit mit TypeScript
• TailwindCSS
• Tolgee für i18n
• Chart.js für Visualisierungen

Installation

Mit Docker (empfohlen)

# Starte alle Services
docker-compose up -d

# Backend läuft auf http://localhost:8000
# Frontend läuft auf http://localhost:5173

Lokale Entwicklung

Backend Setup

# Erstelle virtuelles Environment mit uv
uv venv
source .venv/bin/activate

# Installiere Abhängigkeiten
uv pip install -r backend/requirements.txt

# Starte PostgreSQL und Redis (z.B. mit Docker)
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:15
docker run -d -p 6379:6379 redis:7

# Starte Backend
cd backend
uvicorn app.main:app --reload

Frontend Setup

cd frontend
npm install
npm run dev

Projektstruktur

vermietung2/
├── backend/
│   ├── app/
│   │   ├── api/          # API Endpoints
│   │   ├── core/         # Konfiguration
│   │   ├── db/           # Datenbank-Setup
│   │   ├── models/       # SQLAlchemy Models
│   │   ├── schemas/      # Pydantic Schemas
│   │   └── services/     # Business Logic
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── lib/          # Shared Libraries
│   │   ├── routes/       # SvelteKit Routes
│   │   └── components/   # UI Components
│   └── package.json
└── docker-compose.yml

API Dokumentation

Die API-Dokumentation ist verfügbar unter:

• http://localhost:8000/docs (Swagger UI)
• http://localhost:8000/redoc (ReDoc)

Entwicklung

Datenbank-Migrationen

cd backend
alembic init alembic
alembic revision --autogenerate -m "Initial migration"
alembic upgrade head

Testing

Das Projekt verfügt über umfassende Unit-, Integrations- und E2E-Tests.

Tests ausführen

# Alle Tests ausführen
make test

# Backend Tests mit Coverage
make test-backend
cd backend && pytest --cov=app --cov-report=html

# Frontend Tests mit Coverage  
make test-frontend
cd frontend && npm run test:coverage

# Integration Tests
make test-integration

# Tests mit Docker
docker-compose -f docker-compose.test.yml up

Test-Coverage

# Coverage-Reports generieren
make coverage

# Reports ansehen:
# Backend: backend/htmlcov/index.html
# Frontend: frontend/coverage/index.html

Continuous Integration

Das Projekt nutzt Forgejo Actions für CI/CD:

• Automatische Tests bei Push/PR
• Docker Build und Push zu Forgejo Registry
• Automatisches Deployment zu Kubernetes
• Staging (develop branch) und Production (main branch)

Pre-commit Hooks

# Pre-commit hooks installieren
pip install pre-commit
pre-commit install

# Manuell ausführen
pre-commit run --all-files

Umgebungsvariablen

Erstelle eine .env Datei im Backend-Verzeichnis:

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost/nebenkosten
SECRET_KEY=your-secret-key-change-in-production
REDIS_URL=redis://localhost:6379/0

# HBCI Konfiguration (optional)
HBCI_BANK_CODE=12345678
HBCI_USER_ID=username
HBCI_PIN=encrypted_pin
HBCI_URL=https://banking.example.com

Deployment

Kubernetes Deployment

# Deploy to production
task deploy:production

# Deploy to staging  
task deploy:staging

# Manual deployment
task k8s:deploy

# Check deployment status
task k8s:status

Forgejo Actions

Push to branches triggers automatic deployment:

• main → Production (vermietung namespace)
• develop → Staging (vermietung-staging namespace)

See .forgejo/README.md for CI/CD setup details.

Lizenz

Proprietär - Alle Rechte vorbehalten