suro/aza
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
aza/AzA march 2026/DEV_SETUP_ON_NEW_PC.md

298 lines
8.2 KiB
Markdown
Raw Permalink Normal View History

update
2026-03-25 22:03:39 +01:00
# 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 |
Reference in New Issue Copy Permalink