suro/aza

Fork 0

Files

suro 22397f1d28 update

2026-04-19 20:41:37 +02:00

8.2 KiB

Raw Blame History

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.

winget install Gyan.FFmpeg

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

Prüfen:

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

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

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

2.3 Abhängigkeiten installieren

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)

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)

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

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

3.2 `build_exe.ps1`

In Zeile 1 den Pfad anpassen:

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

3.3 `build_installer.ps1`

In Zeile 1 den Pfad anpassen:

$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

.\check_dev_environment.ps1

Alle Punkte sollten PASS zeigen.

4.2 App im Development-Modus starten

.\start_dev.ps1

Oder manuell:

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

4.3 Nur Backend starten

.\.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)

.\build_exe.ps1

Oder manuell:

.\.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.

.\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

8.2 KiB Raw Blame History Unescape Escape