Initial commit
This commit is contained in:
297
backup 24.2.26 - Kopie (61)/DEV_SETUP_ON_NEW_PC.md
Normal file
297
backup 24.2.26 - Kopie (61)/DEV_SETUP_ON_NEW_PC.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# 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
Block a user