298 lines
8.2 KiB
Markdown
298 lines
8.2 KiB
Markdown
# 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 |
|