100 lines
5.1 KiB
Markdown
100 lines
5.1 KiB
Markdown
# SPA cutover feature flag (`USE_SPA_UI`)
|
|
|
|
## Formål
|
|
`USE_SPA_UI` styrer om host/player UI routes serverer Angular SPA shell eller legacy Django templates.
|
|
|
|
## Miljø-toggle (uden kodeændring)
|
|
Sæt env var pr. miljø:
|
|
|
|
- `USE_SPA_UI=true` -> `/lobby/ui/host` og `/lobby/ui/player` returnerer SPA shell
|
|
- `USE_SPA_UI=false` (default) -> legacy template-flow bruges uændret
|
|
|
|
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`.
|
|
- Kør gameplay smoke på legacy routes (`/lobby/ui/host` + `/lobby/ui/player`).
|
|
2. **Smoke-gate før aktivering (skal være grøn)**
|
|
- Cutover route sanity = PASS for både OFF og ON checks.
|
|
- Full gameplay round (join/start/round/scoreboard) = PASS.
|
|
- Next-round/final leaderboard sanity = PASS.
|
|
- Ingen nye blocker-regressioner i host/player kerneflow.
|
|
3. **Kontrolleret aktivering i staging**
|
|
- Sæt `USE_SPA_UI=true` i staging miljøet.
|
|
- Kør smoke-flow igen med SPA-route-verifikation.
|
|
4. **Post-cutover dokumentation**
|
|
- Log evidens med commit/head SHA, UTC timestamp og gate-status.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
## React fallback trigger-kriterier (kun delivery-blocking)
|
|
Formål: React fallback må kun bruges som kortvarig leverings-sikring, når release ellers er blokeret.
|
|
|
|
### Hvornår fallback er tilladt
|
|
Alle punkter skal være opfyldt:
|
|
1. **Delivery-blocking fejl i Angular SPA**
|
|
- Host/player kerneflow kan ikke leveres i release-vinduet (fx login/join/start/round/scoreboard stopper).
|
|
2. **Ingen hurtig Angular-fix inden for release-vinduet**
|
|
- Teamet har vurderet at patch + verificering ikke kan nås sikkert i tide.
|
|
3. **Rollback alene løser ikke leveringsbehovet**
|
|
- `USE_SPA_UI=false` (legacy) er enten utilstrækkelig for den konkrete leverance eller allerede verificeret som ikke tilstrækkelig.
|
|
4. **Beslutning er eksplicit logget**
|
|
- Trigger, impact, UTC-tid, ansvarlig, issue/incident-reference og plan for tilbagevenden til Angular er dokumenteret i release/smoke artifact.
|
|
|
|
### Scope-limits for fallback
|
|
- Fallback omfatter kun **delivery-blocking host/player-paths**.
|
|
- Ingen nye features, UX-forbedringer eller ikke-kritiske ændringer må bundtes ind i fallback.
|
|
- Fallback er **midlertidig** og gælder kun for aktiv incident/release-vindue.
|
|
- Når blocker er fjernet, skal miljøet tilbage på standard cutover-spor (Angular + `USE_SPA_UI` styring).
|
|
|
|
### Ikke tilladt
|
|
- Proaktiv fallback "for en sikkerheds skyld" uden aktiv blocker.
|
|
- Brug af fallback til at omgå normale kvalitetsgates eller testkrav.
|
|
- Langvarig drift i fallback-mode uden dokumenteret blocker og opfølgningsplan.
|
|
|
|
## Verifikation
|
|
- Flag OFF: `UiScreenTests.test_legacy_templates_are_used_when_spa_flag_is_off`
|
|
- Flag ON (host): `UiScreenTests.test_host_screen_can_render_angular_shell_when_feature_flag_enabled`
|
|
- Flag ON (host deep-link): `UiScreenTests.test_host_screen_deeplink_preserves_spa_path_when_feature_flag_enabled`
|
|
- Flag ON (player): `UiScreenTests.test_player_screen_can_render_angular_shell_when_feature_flag_enabled`
|
|
- Smoke-checkliste for cutover paths: `docs/STAGING_GAMEPLAY_SMOKE_ARTIFACT.md` + `docs/UI_SMOKE.md`
|
|
|
|
|
|
## MVP audio policy guardrail (telefon-klient)
|
|
- Telefon-/player-klienten må ikke starte lydafspilning lokalt i MVP (`primary-device only`).
|
|
- Policy er bundet til capability-flaget `frontend.capabilities.client_has_no_audio_output=true` i `shared/i18n/lobby.json`.
|
|
- Brugeradvarsel i player UI leveres via i18n key: `frontend.ui.player.audio_policy_notice`.
|
|
- Acceptance-spec er dækket i Angular tests (`player-shell.component.spec.ts`), inkl. at init-path ikke kalder original media `play`.
|