inital v4

2026-05-25 20:46:00 +02:00
parent fca54607cb
commit 1adec1b88f
42 changed files with 56666 additions and 0 deletions
--- a/v4/README.md
+++ b/v4/README.md
@@ -0,0 +1,167 @@
+# NotifyPulse V4 (Server + Clients)
+
+This V4 scaffold splits NotifyPulse into:
+
+- Linux-hosted server (`v4/server`) for API, Web UI, PWA, settings, command routing.
+- Windows agent (`v4/windows_client`) built as `.exe`, connected to server by WebSocket.
+- Shared command protocol with ack/event flow.
+
+V3 stays untouched in the repo root (`notifier.py`).
+
+## Architecture
+
+1. Server is the source of truth for settings, usecases, and command dispatch.
+2. Windows client registers itself and executes device-local actions:
+   - toast notifications
+   - wallpaper changes
+   - (overlay hook included, implementation placeholder)
+3. PWA/web clients connect to the server and use the same API.
+4. Updates are centralized with server-hosted update manifests:
+   - `GET /api/v4/update/manifest/windows`
+   - Client checks and reports update availability.
+
+## Quick start (Linux server)
+
+```bash
+cd v4/server
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+uvicorn app.main:app --host 0.0.0.0 --port 8080
+```
+
+Server defaults:
+
+- Web UI: `http://<server>:8080/`
+- PWA: `http://<server>:8080/pwa/`
+- Device WebSocket: `ws://<server>:8080/ws/device`
+
+## Deploy on Linux (systemd)
+
+Example target folder: `/opt/notifypulse`.
+
+1. Copy repo to server and install deps:
+
+```bash
+sudo mkdir -p /opt/notifypulse
+sudo chown -R $USER:$USER /opt/notifypulse
+cd /opt/notifypulse
+python3 -m venv v4/server/.venv
+source v4/server/.venv/bin/activate
+pip install -r v4/server/requirements.txt
+```
+
+2. Create env file:
+
+```bash
+cat > /opt/notifypulse/v4/server/.env <<'EOF'
+NP4_HOST=0.0.0.0
+NP4_PORT=8080
+NP4_API_TOKEN=replace-with-long-random-token
+NP4_DATA_DIR=/opt/notifypulse/v4_data
+EOF
+```
+
+3. Create systemd service `/etc/systemd/system/notifypulse-v4.service`:
+
+```ini
+[Unit]
+Description=NotifyPulse V4 Server
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/opt/notifypulse/v4/server
+EnvironmentFile=/opt/notifypulse/v4/server/.env
+ExecStart=/opt/notifypulse/v4/server/.venv/bin/uvicorn app.main:app --host ${NP4_HOST} --port ${NP4_PORT}
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+```
+
+4. Enable service:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now notifypulse-v4
+sudo systemctl status notifypulse-v4
+```
+
+## Optional: Nginx reverse proxy + HTTPS
+
+Minimal Nginx vhost:
+
+```nginx
+server {
+    listen 80;
+    server_name your.domain.tld;
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location /ws/device {
+        proxy_pass http://127.0.0.1:8080/ws/device;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+    }
+}
+```
+
+Then add TLS (recommended) with Certbot.
+
+## Quick start (Windows client)
+
+```powershell
+cd v4\windows_client
+py -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+$env:NP4_SERVER_URL="http://<server>:8080"
+$env:NP4_API_TOKEN="<optional token>"
+python client.py
+```
+
+## Build Windows `.exe`
+
+```powershell
+cd v4\windows_client
+build.bat
+```
+
+Output: `dist\NotifyPulseAgent-V4.exe`
+
+## Easy update model
+
+1. Publish new Windows agent builds on your server/CDN.
+2. Update the manifest in server data:
+   - `v4_data/update_manifest.json` (auto-created on first boot)
+3. Client periodically checks `GET /api/v4/update/manifest/windows`.
+4. If newer version is detected, client emits `update_available` event.
+
+You can later switch this to silent self-update (download + staged swap + restart), but this scaffold keeps it safe and transparent first.
+
+## iOS note
+
+PWA is the practical path. iOS sideloading native apps is possible but adds signing/provisioning/distribution complexity and is not "easy update" compared to PWA.
+
+## Troubleshooting
+
+- `Desktop test -> Wallpaper` does nothing:
+  - Ensure an active usecase exists.
+  - Add files under `v4_data/usecases/<usecase_id>/wallpapers/`.
+- `Desktop test -> Overlay` does nothing:
+  - Add files under `v4_data/usecases/<usecase_id>/overlay/`.
+  - Rebuild/update the Windows agent so it includes overlay support.
+- PWA wallpaper is identical for lock/home:
+  - Add at least 2 images under `v4_data/usecases/<usecase_id>/mobile/`.
+  - With only one image, both slots intentionally use that single image.