timemaster/backend

TimeMaster – agent-01-auth

Backend: Python 3.12 · FastAPI · SQLAlchemy (async) · PostgreSQL · Redis
Laufend nativ auf dem Server (kein Docker in Phase 1).

---

Voraussetzungen (Ubuntu 22.04 / 24.04)

sudo apt update && sudo apt install -y \
  python3.12 python3.12-venv python3.12-dev \
  postgresql postgresql-contrib \
  redis-server nginx git build-essential libpq-dev

---

1 · PostgreSQL einrichten

sudo systemctl enable --now postgresql

sudo -u postgres psql <<SQL
CREATE ROLE timemaster LOGIN PASSWORD 'ein_sicheres_passwort';
CREATE DATABASE timemaster_db OWNER timemaster;
GRANT ALL PRIVILEGES ON DATABASE timemaster_db TO timemaster;
SQL

---

2 · Redis starten

sudo systemctl enable --now redis-server

---

3 · Projekt klonen & venv anlegen

sudo mkdir -p /opt/timemaster
sudo chown $USER:$USER /opt/timemaster
git clone https://github.com/dein-repo/timemaster.git /opt/timemaster

cd /opt/timemaster/backend
python3.12 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

---

4 · Umgebungsvariablen setzen

cp .env.example .env
nano .env   # Werte anpassen: DATABASE_URL, SECRET_KEY, RESEND_API_KEY usw.

Wichtige Felder:

SECRET_KEY=<min. 32 zufällige Zeichen>
DATABASE_URL=postgresql+asyncpg://timemaster:passwort@localhost:5432/timemaster_db
FRONTEND_URL=https://deine-domain.de

---

5 · Datenbank-Migration ausführen

cd /opt/timemaster/backend
source venv/bin/activate
alembic upgrade head

---

6 · Server starten (Entwicklung)

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

API-Docs (nur dev): http://localhost:8000/docs

---

7 · Systemd-Service einrichten (Produktion)

sudo cp /opt/timemaster/timemaster.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now timemaster
sudo systemctl status timemaster

---

8 · Nginx einrichten

sudo cp /opt/timemaster/nginx.conf /etc/nginx/sites-available/timemaster
sudo ln -s /etc/nginx/sites-available/timemaster /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# SSL via Let's Encrypt
sudo certbot --nginx -d deine-domain.de

---

9 · Tests ausführen

cd /opt/timemaster/backend
source venv/bin/activate
pip install aiosqlite  # nur für Tests (SQLite in-memory)
pytest -v

---

API-Übersicht (agent-01)

Method	Endpoint	Beschreibung
POST	/api/v1/auth/register	Firma + Admin anlegen
POST	/api/v1/auth/login	Login → JWT + Refresh Token
POST	/api/v1/auth/refresh	Access Token erneuern
POST	/api/v1/auth/logout	Session beenden
GET	/api/v1/auth/me	Aktueller Nutzer
POST	/api/v1/auth/password-reset	Reset-Link anfordern
POST	/api/v1/auth/password-reset/confirm	Passwort neu setzen
POST	/api/v1/auth/invite/accept	Einladung annehmen
GET	/api/v1/users/	Alle Nutzer (Admin/HR)
POST	/api/v1/users/invite	Nutzer einladen
GET	/api/v1/users/me	Eigenes Profil
GET	/api/v1/users/{id}	Nutzer abrufen
PATCH	/api/v1/users/{id}	Nutzer bearbeiten
POST	/api/v1/users/{id}/deactivate	Deaktivieren
POST	/api/v1/users/{id}/reactivate	Reaktivieren
POST	/api/v1/users/{id}/kiosk-pin	Kiosk-PIN setzen
GET	/api/v1/companies/me	Firmenprofil
PATCH	/api/v1/companies/me	Firmenprofil bearbeiten
GET	/api/v1/companies/me/departments	Abteilungen
POST	/api/v1/companies/me/departments	Abteilung anlegen
PATCH	/api/v1/companies/me/departments/{id}	Abteilung bearbeiten
DELETE	/api/v1/companies/me/departments/{id}	Abteilung löschen

---

Dateistruktur

backend/
├── app/
│   ├── main.py              ← FastAPI App
│   ├── core/
│   │   ├── config.py        ← Settings (.env)
│   │   ├── database.py      ← AsyncEngine + get_db
│   │   ├── security.py      ← JWT, Hashing, Tokens
│   │   └── dependencies.py  ← get_current_user, require_role
│   ├── models/              ← SQLAlchemy ORM
│   ├── schemas/             ← Pydantic v2
│   ├── routers/             ← API-Endpunkte
│   └── services/            ← Business-Logik
├── migrations/              ← Alembic
├── tests/                   ← pytest
├── alembic.ini
├── pytest.ini
└── requirements.txt

---

Nächste Schritte (Sprint 2)

• agent-02-zeiterfassung: Stempeluhr, Zeit-Einträge, ArbZG-Prüfung
• agent-03-abwesenheit: Urlaubsanträge, Genehmigungsflow, Kalender