docs: stage browser alias + UX backlog (P0–P2)

2026-07-23 13:20:34 +03:00
parent 6a9daffec7
commit eeba89d823
6 changed files with 233 additions and 0 deletions
@@ -0,0 +1,68 @@
+# Stage UI в Cursor Browser
+
+Chromium / Cursor IDE Browser часто **не резолвят** `*.eventhub.local` (mDNS), даже если Windows/`nslookup` через OpenWRT уже видят stage.
+
+Для агентов и ручного просмотра stage используем **локальный alias + HTTP-прокси**.
+
+## URL
+
+| Открывать в браузере | Upstream |
+|----------------------|----------|
+| `http://ui.stage.eventhub.test:8787` | `https://ui.stage.eventhub.local` → `195.208.119.190` |
+
+## Одноразовая настройка hosts
+
+В `C:\Windows\System32\drivers\etc\hosts` (или WSL `/etc/hosts` не помогает Cursor на Windows):
+
+```text
+127.0.0.1 ui.stage.eventhub.test
+```
+
+## Прокси
+
+Скрипт в репозитории: [`scripts/stage-browser-alias-proxy.mjs`](scripts/stage-browser-alias-proxy.mjs)
+
+Копия для быстрого старта агента: `~/.cursor/eventhub/stage-browser-alias-proxy.mjs` (если есть — можно любой из двух).
+
+**Важно:** процесс должен слушать на **Windows** `127.0.0.1:8787` (Node из Windows). Прокси только в WSL Cursor с Windows часто не достучится.
+
+```powershell
+Start-Process -FilePath "C:\Program Files\nodejs\node.exe" `
+  -ArgumentList "$env:USERPROFILE\.cursor\eventhub\stage-browser-alias-proxy.mjs" `
+  -WindowStyle Hidden
+```
+
+Или из Spec (если скрипт уже скопирован в `~/.cursor/eventhub/`):
+
+```powershell
+# из корня EventHubSpec
+Start-Process -FilePath "C:\Program Files\nodejs\node.exe" `
+  -ArgumentList (Resolve-Path ".\scripts\stage-browser-alias-proxy.mjs") `
+  -WindowStyle Hidden
+```
+
+Проверка: открыть `http://ui.stage.eventhub.test:8787/login`.
+
+Переменные окружения (опционально):
+
+| Env | Default |
+|-----|---------|
+| `ALIAS_LISTEN_HOST` | `127.0.0.1` |
+| `ALIAS_LISTEN_PORT` | `8787` |
+| `STAGE_IP` | `195.208.119.190` |
+| `STAGE_UI_HOST` | `ui.stage.eventhub.local` |
+| `ALIAS_HOST` | `ui.stage.eventhub.test` |
+
+## Auth
+
+Same-origin через прокси: `/v1/login`, `/v1/register`, logout — как на настоящем stage.
+
+- Smoke: `~/.cursor/secrets/eventhub-stage.env` (`SMOKE_USER_*`).
+- IFT e2e: только `~/.cursor/secrets/eventhub-ift.env` (не подмешивать stage).
+- Прокси **не** подставляет пользователя: только Host/SNI rewrite на Traefik.
+
+## Что не делать
+
+- Не ждать, что Cursor Browser сам пойдёт на `https://ui.stage.eventhub.local`.
+- Не поднимать прокси только в WSL, если агентский браузер на Windows.
+- Не коммитить пароли/токены из smoke env.