weirsoe-party-protocol/docs/spa-cutover-flag.md

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.

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-checkpoints (staging)

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.

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