feat: PWA update strategy with hashed assets and cache control

Move frontend sources to frontend/, build content-hashed assets at deploy,
network-first SW for shell/JS, immutable cache for /assets/, version.json
update banner, and Cache-Control middleware. Docs in docs/PWA-STRATEGY.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Frank Schwenk
2026-07-08 08:51:12 +02:00
parent bff14167c9
commit 7cec3030c1
29 changed files with 779 additions and 61 deletions
+56
View File
@@ -0,0 +1,56 @@
# PWA Update-Strategie
Wiederverwendbare Strategie für Fränkys PWAs — damit Nutzer:innen **ohne Cache leeren** immer die aktuelle Version sehen.
> Gitea-Wiki: manuell anlegen unter [PWA-Update-Strategie](https://gitea.schwenk.online/froxxxy/takeyourmeds/wiki/_pages) (MCP-Token hatte keine Wiki-Schreibrechte).
## Warum?
- Viele Nutzer:innen wissen nicht, was „Cache leeren" bedeutet (besonders auf dem Handy / als installierte PWA).
- Service Worker können alte Dateien **monatelang** vorhalten — ein Deploy reicht nicht.
- Ziel: Updates **sichtbar und kontrolliert** (Banner + Reload), nicht stilles Veralten.
## Drei Ebenen (Tiers)
### Tier 1 — Service Worker & Client
| Element | Strategie |
|---------|-----------|
| `sw.js` | Nicht vom SW intercepten; Server: `Cache-Control: no-cache` |
| `index.html` | Network-first |
| Unversioniertes JS/CSS | Network-first |
| Cache-Name | Pro Build: `tym-v{version}-{buildHash}` |
| `version.json` | Network-only im SW; Client-Check beim Start/Focus |
| Update-Banner | `buildHash``meta app-build` → „Aktualisieren" |
### Tier 2 — Server & Lifecycle
| Element | Maßnahme |
|---------|----------|
| HTTP-Header | `server/static_cache.py` Middleware |
| Focus | `registration.update()` + `version.json` Check |
| `controllerchange` | Einmalig `location.reload()` |
### Tier 3 — Build
| Element | Maßnahme |
|---------|----------|
| Quellen | `frontend/` |
| Output | `public/assets/*.{hash}.js/css` |
| Build | `python tools/build_frontend.py` (läuft im Dockerfile) |
| Gehashte Assets | `Cache-Control: immutable` |
## Deploy-Checkliste
- [ ] Version in `pyproject.toml` bumpen (optional)
- [ ] `python tools/build_frontend.py` (Docker macht das automatisch)
- [ ] `docker compose up -d --build`
- [ ] Inkognito: `sw.js` neue CACHE-Konstante, `version.json` neuer `buildHash`
- [ ] Alte PWA-Installation: Update-Banner nach App-Öffnung
## Anti-Patterns
- Cache-first für unversioniertes `app.js`
- `sw.js` im Precache
- Stub-Endpoints für fehlende APIs
- „Cache leeren" als einziger Fix in der Doku