# 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)

```bash
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

```bash
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

```bash
sudo systemctl enable --now redis-server
```

---

## 3 · Projekt klonen & venv anlegen

```bash
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

```bash
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

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

---

## 6 · Server starten (Entwicklung)

```bash
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)

```bash
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

```bash
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

```bash
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