# AZA Desktop – Entwicklungs-Setup auf neuem PC

Stand: 2026-03-23

---

## 1. Voraussetzungen installieren

### 1.1 Python 3.12.x

**Empfohlen: Python 3.12.10** (aktuell getestet und verwendet).

- Download: https://www.python.org/downloads/release/python-31210/
- **Windows installer (64-bit)** wählen
- Bei Installation: **"Add Python to PATH"** aktivieren
- **"Install for all users"** empfohlen

> **Warum 3.12?** Das Projekt verwendet aktuell Python 3.12.10. PyInstaller 6.13.0 und alle Abhängigkeiten sind damit getestet. Python 3.13 ist noch nicht validiert. Python 3.11 würde vermutlich funktionieren, ist aber nicht aktuell getestet.

### 1.2 ffmpeg

Wird für Audio-/Diktat-Funktionen benötigt.

```powershell
winget install Gyan.FFmpeg
```

Alternativ: https://www.gyan.dev/ffmpeg/builds/ (full build) und manuell zum PATH hinzufügen.

**Prüfen:**
```powershell
ffmpeg -version
```

### 1.3 Inno Setup 6 (nur für Installer-Build)

- Download: https://jrsoftware.org/isdl.php
- Standard-Installation durchführen
- Wird nur benötigt, wenn der Windows-Installer gebaut werden soll
- `build_installer.ps1` kann Inno Setup auch automatisch nachinstallieren

### 1.4 Cursor IDE

- Download: https://cursor.sh
- Nach Installation den Projektordner öffnen

---

## 2. Projekt einrichten

### 2.1 Projektordner entpacken/kopieren

Den gesamten Projektordner (z. B. `backup 24.2.26`) an einen beliebigen Ort kopieren. Beispiel:

```
C:\Users\<USERNAME>\Documents\AZA\backup 24.2.26\
```

### 2.2 Virtuelle Umgebung erstellen

```powershell
cd "C:\Users\<USERNAME>\Documents\AZA\backup 24.2.26"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

> Falls die Aktivierung fehlschlägt (ExecutionPolicy):
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
> ```

### 2.3 Abhängigkeiten installieren

```powershell
pip install -r requirements-dev.txt
```

**Wichtig:** `numpy` MUSS Version < 2.4 sein (aktuell 2.2.5). NumPy 2.4.x bricht den PyInstaller-Build mit `ModuleNotFoundError: No module named 'numpy._core._exceptions'`.

### 2.4 Konfigurationsdateien vorbereiten

#### `.env` (Backend-Secrets)

```powershell
Copy-Item .env.example .env
```

Dann `.env` bearbeiten und echte Werte eintragen:
- `STRIPE_SECRET_KEY` – Stripe Test-/Live-Key
- `STRIPE_WEBHOOK_SECRET` – Stripe Webhook-Secret
- `MEDWORK_API_TOKEN` / `MEDWORK_API_TOKENS` – Backend-API-Token

#### `config\aza_runtime.env` (OpenAI-Key)

```powershell
# Falls Ordner nicht existiert:
New-Item -ItemType Directory -Force -Path config
```

In `config\aza_runtime.env` den OpenAI-Key eintragen:
```
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

#### `backend_url.txt`

Enthält die Backend-URL. Für lokale Entwicklung:
```
http://127.0.0.1:8000
```

#### `backend_token.txt`

Muss den gleichen Token enthalten wie `MEDWORK_API_TOKEN` in `.env`.

#### `license_url.txt`

Enthält die License-Server-URL. Für lokale Entwicklung:
```
http://127.0.0.1:9000
```

---

## 3. Pfade in Build-Dateien anpassen

### 3.1 `aza_desktop.spec`

In Zeile 6 den `project_root`-Pfad anpassen:

```python
project_root = Path(r"C:\Users\<USERNAME>\Documents\AZA\backup 24.2.26")
```

### 3.2 `build_exe.ps1`

In Zeile 1 den Pfad anpassen:

```powershell
$projectRoot = "C:\Users\<USERNAME>\Documents\AZA\backup 24.2.26"
```

### 3.3 `build_installer.ps1`

In Zeile 1 den Pfad anpassen:

```powershell
$projectRoot = "C:\Users\<USERNAME>\Documents\AZA\backup 24.2.26"
```

### 3.4 `installer\aza_installer.iss`

In Zeile 7 und anderen Stellen die Pfade anpassen:

```
#define MyAppSourceDir "C:\Users\<USERNAME>\Documents\AZA\backup 24.2.26\dist\aza_desktop"
```

Sowie die Pfade für `OutputDir` und `SetupIconFile`.

> **Tipp:** Suche in allen `.ps1`, `.spec` und `.iss` Dateien nach dem alten Pfad `C:\Users\surov\Documents\AZA\backup 24.2.26` und ersetze ihn.

---

## 4. Entwicklung starten

### 4.1 Self-Check ausführen

```powershell
.\check_dev_environment.ps1
```

Alle Punkte sollten PASS zeigen.

### 4.2 App im Development-Modus starten

```powershell
.\start_dev.ps1
```

Oder manuell:

```powershell
.\.venv\Scripts\Activate.ps1
python basis14.py
```

### 4.3 Nur Backend starten

```powershell
.\.venv\Scripts\Activate.ps1
python -c "import uvicorn; uvicorn.run('backend_main:app', host='127.0.0.1', port=8000)"
```

---

## 5. Build erstellen

### 5.1 EXE-Build (PyInstaller)

```powershell
.\build_exe.ps1
```

Oder manuell:

```powershell
.\.venv\Scripts\Activate.ps1
pyinstaller aza_desktop.spec --noconfirm
```

Ergebnis: `dist\aza_desktop\aza_desktop.exe`

### 5.2 Installer-Build (Inno Setup)

**Voraussetzung:** EXE-Build muss zuerst erfolgreich sein.

```powershell
.\build_installer.ps1
```

Ergebnis: `dist\installer\aza_desktop_setup.exe`

---

## 6. Bekannte Stolpersteine

| Problem | Ursache | Lösung |
|---------|---------|--------|
| `ModuleNotFoundError: numpy._core._exceptions` | numpy >= 2.4 inkompatibel mit PyInstaller 6.13.0 | `pip install "numpy==2.2.5"` |
| PowerShell `&&` Operator unbekannt | PS 5.x kennt `&&` nicht | Befehle mit `;` trennen oder separate Aufrufe |
| Inno Setup nicht gefunden | Nicht installiert | `build_installer.ps1` installiert automatisch |
| `ffmpeg` nicht gefunden | Nicht im PATH | `winget install Gyan.FFmpeg` oder manuell installieren |
| Linter-Warnungen (bcrypt, pyotp etc.) | Optionale Pakete / C-Extensions | Harmlos, ignorierbar |
| `.env` fehlt | Nicht mit exportiert (Secrets!) | `.env.example` kopieren und Werte eintragen |

---

## 7. Projektstruktur (Übersicht)

```
backup 24.2.26/
├── basis14.py              # Haupt-Desktop-App (Tkinter GUI)
├── backend_main.py         # FastAPI-Backend
├── aza_*.py                # Modulare Mixins und Hilfsmodule
├── apps/diktat/            # Diktat-/Audio-Sub-App
├── services/               # Backend-Services (Events, News, LLM)
├── installer/              # Inno Setup Script
├── deploy/                 # Server-Deployment-Dateien
├── security/               # Security-Handover-Docs
├── legal/                  # Rechtliche Dokumente
├── data/                   # Seed-Daten
├── tools/                  # Dev-Tools
├── web/                    # Web-Frontend (MVP)
├── billing/                # Billing-Docs
├── workforce_planner/      # Workforce-Planner-Modul
├── aza_desktop.spec        # PyInstaller Build-Spec
├── build_exe.ps1           # EXE-Build-Script
├── build_installer.ps1     # Installer-Build-Script
├── start_dev.ps1           # Dev-Start-Script
├── check_dev_environment.ps1  # Environment-Self-Check
├── requirements-dev.txt    # Gepinnte Abhängigkeiten
├── .env.example            # Env-Template (ohne Secrets)
├── project_status.json     # Projektstatus
├── project_todos.json      # Offene Aufgaben
├── project_roadmap.json    # Roadmap
├── project_plan.json       # Projektplan
├── handover.md             # Handover-Dokument
├── project_handover.md     # Projekt-Handover
├── logo.ico / logo.png     # App-Icon
└── config/aza_runtime.env  # OpenAI-Key (lokal, nicht exportiert)
```

---

## 8. Secrets – was NICHT im Export enthalten ist

| Datei | Inhalt | Aktion auf neuem PC |
|-------|--------|---------------------|
| `.env` | Stripe-Keys, API-Tokens | Aus `.env.example` erzeugen, echte Werte eintragen |
| `config/aza_runtime.env` | OpenAI API Key | Manuell eintragen |
| `backend_token.txt` | Backend-Auth-Token | Muss zum Token in `.env` passen |
| `deploy/.env` | Produktions-Secrets | Nur für Server-Deployment relevant |

---

## 9. Audio-/Diktat-Abhängigkeiten im Detail

| Komponente | Typ | Paket | Hinweise |
|-----------|------|-------|----------|
| sounddevice | Python-Paket | `pip install sounddevice` | Nutzt PortAudio (in Paket enthalten) |
| soundfile | Python-Paket | `pip install soundfile` | Nutzt libsndfile (in Paket enthalten) |
| numpy | Python-Paket | `pip install "numpy==2.2.5"` | **MUSS < 2.4** für PyInstaller |
| lameenc | Python-Paket | `pip install lameenc` | MP3-Encoding |
| pygame | Python-Paket | `pip install pygame` | Audio-Playback |
| ffmpeg | System-Tool | `winget install Gyan.FFmpeg` | Nicht Python, sondern extern im PATH |
| pynput | Python-Paket | `pip install pynput` | Keyboard-Hotkeys für Diktat |