feat(cutover): harden SPA asset cache busting and rollback playbook (#188)

docs/ISSUE-188-SPA-CUTOVER-HARDENING-ARTIFACT.md

@@ -0,0 +1,47 @@
+# Issue #188 Artifact — SPA cutover hardening (asset versioning + rollback)
+
+## Scope
+Acceptance for `[READY][SPA][P11] Cutover hardening`:
+1. Dokumenteret strategi for cache-busting/versionering af SPA assets i Django staticfiles/reverse proxy setup.
+2. Konfigurerbar rollback-procedure for `USE_SPA_UI` (trin-for-trin, target <10 min).
+3. Smoke-artefakt for både SPA on/off i samme release-vindue.
+4. Ingen gameplay-ændringer.
+
+## 1) Asset versioning/cache-busting strategi
+Implementeret i SPA shell render-path:
+
+- Konfiguration i `partyhub/settings.py`:
+  - `WPP_SPA_ASSET_BASE` (eksisterende)
+  - `WPP_SPA_ASSET_VERSION` (ny)
+- `lobby/ui_views.py` injicerer `spa_asset_version` til template-context.
+- `lobby/templates/lobby/spa_shell.html` appender `?v={{ spa_asset_version }}` på:
+  - `styles.css`
+  - `main.js`
+
+Effekt:
+- Ny release-version (fx SHA/tag) kan tvinge cache-miss i browser/proxy uden ændring af route.
+- Rollback kan pege på tidligere stabil version-token med samme mekanisme.
+
+## 2) Rollback playbook (`USE_SPA_UI`) — target <10 min
+Dokumenteret i `docs/spa-cutover-flag.md`:
+
+1. Sæt `USE_SPA_UI=false`.
+2. Sæt `WPP_SPA_ASSET_VERSION` til sidste stabile release-token.
+3. Deploy/reload app-processer.
+4. Verificér legacy routes (`/lobby/ui/host` + `/lobby/ui/player`).
+5. Kør hurtig smoke sanity.
+6. Log trigger/timestamp/resultat i smoke artifact.
+
+## 3) Smoke artifact for SPA OFF/ON i samme release-vindue
+Dokumenteret i:
+- `docs/UI_SMOKE.md` (sektion: "Samme release-vindue: SPA OFF + ON verifikation")
+- `docs/STAGING_GAMEPLAY_SMOKE_ARTIFACT.md` (template udvidet med release-window check + `WPP_SPA_ASSET_VERSION`)
+
+Krav:
+- OFF-pass (legacy) og ON-pass (SPA) køres i samme deploy/release-vindue.
+- Begge passes logges i samme artifact med UTC timestamps og version-token.
+
+## Non-goals bekræftet
+- Ingen gameplay-regler ændret.
+- Ingen API-kontrakter ændret.
+- Ingen UX-redesign; kun drift/cutover-hardening.

docs/STAGING_GAMEPLAY_SMOKE_ARTIFACT.md

@@ -23,11 +23,14 @@ Formål: levere et lille, ensartet evidensformat for release-nær gameplay-smoke
 - Active category/questions present: <yes/no>
 - Participants: host + <N> players
 - `USE_SPA_UI`: <on/off>
+- `WPP_SPA_ASSET_VERSION`: <release-token/sha>
 - UI route used:
   - OFF (legacy): `/lobby/ui/host` + `/lobby/ui/player`
   - ON (SPA shell): `/lobby/ui/host/<spa-path>` + `/lobby/ui/player`
 
 #### Checks (PASS/FAIL)
+0. Same release-window verification
+   - OFF + ON smoke kørt i samme release-vindue: <pass/fail>
 1. Cutover route sanity
    - Flag OFF serves legacy UI templates: <pass/fail>
    - Flag ON serves SPA shell on expected path(s): <pass/fail>

docs/UI_SMOKE.md

@@ -27,6 +27,18 @@
 - Next-round/final leaderboard sanity er PASS.
 - Ingen nye blocker-regressioner i host/player kerneflow.
 
+## Samme release-vindue: SPA OFF + ON verifikation
+Kør begge checks i samme release-vindue (samme deploy/artifact version):
+
+1. **OFF-pass (legacy)**
+   - `USE_SPA_UI=false`
+   - Verificér legacy routes + fuld runde.
+2. **ON-pass (SPA)**
+   - `USE_SPA_UI=true`
+   - Behold samme release artifact og kun toggl flag/version-token ved behov.
+   - Verificér SPA shell routes + fuld runde.
+3. Dokumentér begge pass i samme smoke-artifact med UTC timestamps og `WPP_SPA_ASSET_VERSION`.
+
 ## Rollback check points
 Skift straks tilbage til `USE_SPA_UI=false` hvis en gate fejler:
 1. Verificér legacy routes (`/lobby/ui/host` + `/lobby/ui/player`) fungerer igen.

docs/spa-cutover-flag.md

@@ -12,6 +12,22 @@ Sæt env var pr. miljø:
 Backward compatibility under cutover:
 - Hvis `USE_SPA_UI` ikke er sat, bruges `WPP_SPA_ENABLED` som fallback.
 
+## Static asset versioning/cache-busting (hardening)
+Formål: sikre at browser/proxy/CDN hurtigt henter ny SPA bundle i release-vinduet uden at kræve hard refresh.
+
+- `WPP_SPA_ASSET_BASE` peger fortsat på build-output (`/static/frontend/angular/browser`).
+- `WPP_SPA_ASSET_VERSION` injiceres i SPA shell URLs som query-param (`?v=<version>`).
+- Anbefalet værdi for `WPP_SPA_ASSET_VERSION`: release-tag eller kort commit SHA.
+- Ved rollback sættes `WPP_SPA_ASSET_VERSION` til den tidligere kendte stabile release-værdi.
+
+Eksempel (staging/prod env):
+
+```env
+USE_SPA_UI=true
+WPP_SPA_ASSET_BASE=/static/frontend/angular/browser
+WPP_SPA_ASSET_VERSION=rel-2026-03-01-bb82357
+```
+
 ## Staging rollout-checkliste (`USE_SPA_UI`)
 1. **Baseline (flag OFF)**
    - Bekræft at staging kører med `USE_SPA_UI=false`.
@@ -27,15 +43,21 @@ Backward compatibility under cutover:
 4. **Post-cutover dokumentation**
    - Log evidens med commit/head SHA, UTC timestamp og gate-status.
 
-## Rollback-checkpoints (staging)
+## Rollback playbook (`USE_SPA_UI`) — mål: <10 min
 Rollback til legacy (`USE_SPA_UI=false`) udføres straks hvis et checkpoint fejler:
 - Forkert route/shell for valgt flag i cutover route sanity.
 - Gameplay smoke kan ikke gennemføres til scoreboard/final leaderboard.
 - Kritisk regression i host/player flow under smoke.
 
-Efter rollback:
-- Bekræft legacy routes virker igen (`/lobby/ui/host` + `/lobby/ui/player`).
-- Log rollback-trigger + repro + blocker-link i smoke artifact.
+Trin-for-trin:
+1. Sæt `USE_SPA_UI=false` i deploy-env.
+2. Sæt `WPP_SPA_ASSET_VERSION` til sidste stabile release-token.
+3. Deploy/reload app-processer.
+4. Verificér legacy routes: `/lobby/ui/host` + `/lobby/ui/player`.
+5. Kør hurtig smoke sanity (join/start/scoreboard path).
+6. Log UTC tid, trigger, release-token og resultat i smoke artifact.
+
+Target: rollback + sanity-verifikation inden for 10 minutter.
 
 ## Verifikation
 - Flag OFF: `UiScreenTests.test_legacy_templates_are_used_when_spa_flag_is_off`