v0.1 - макет интерфейса, аутентификация через логин, аккаунт админа, создание партии в 2 этапа, базовые настройки профиля и группы, переключение между группами, статистика

README.md

@@ -20,7 +20,23 @@ docker-compose.yml
 
 ## Локальная разработка
 
-Бэкенд и фронт запускаются раздельно; Vite проксирует `/api` на бэкенд.
+### Единый лаунчер (`run.ps1` / `run.sh`)
+
+После разовой настройки (ниже) dev и test запускаются **одной командой** — что именно,
+решает `APP_ENV` в корневом `.env`:
+
+```powershell
+.\run.ps1        # Windows   (Linux / macOS / Git Bash:  ./run.sh)
+```
+
+| `APP_ENV` в `.env` | что делает лаунчер |
+|---|---|
+| `development` | `uvicorn --reload` (бэк) + `vite` (фронт) нативно, в двух окнах |
+| `test` | `docker compose` прод-клон на :8080 (со сборкой образа) |
+| `production` | не запускает — прод деплоится отдельно (см. «Git и деплой») |
+
+Разовая настройка перед первым запуском — поднять venv бэка и зависимости фронта
+(после неё повседневный цикл — просто `.\run.ps1`). Vite проксирует `/api` на бэкенд.
 
 ### 1) Бэкенд
 
@@ -91,32 +107,37 @@ FastAPI отдаёт собранный SPA и API с одного origin. Ми
 только через Telegram), но на своей машине — для проверки прод-сборки до выката на Pi.
 Изолированные тома и порт **8080** (не конфликтует с dev-uvicorn на :8000).
 
+Проще всего — через лаунчер: поставить `APP_ENV=test` в `.env` и запустить `.\run.ps1`.
+Вручную (тот же эффект):
 ```bash
-cp .env.test.example .env.test       # заполнить при необходимости
-docker compose --env-file .env.test -f docker-compose.test.yml up -d --build
+docker compose -f docker-compose.test.yml up -d --build
 # открыть http://localhost:8080  (Swagger: /api/docs)
 docker compose -f docker-compose.test.yml down -v   # остановить и стереть тестовые данные
 ```
 
-- Окружение принудительно `production` (клон Pi), но `COOKIE_SECURE=false` (локально HTTP).
+- Окружение `test` (прод-клон), но `COOKIE_SECURE=false` (локально по HTTP).
+- Читает **тот же `.env`**, что dev/prod (отдельного `.env.test` больше нет); внутри
+  контейнера `APP_ENV` форсится в `test` (см. `docker-compose.test.yml`).
 - Данные — на отдельных томах `db-data-test` / `uploads-data-test` (не пересекаются с dev и Pi).
 - Вход: **админ-панель** (`/admin/login`) работает сразу по логину/паролю; вход **игроков** —
   только через Telegram (нужен бот + публичный HTTPS/туннель на `localhost:8080`).
-- Если пароль/секрет содержит `$`, для docker compose экранируйте его как `$$`
-  (для dev-uvicorn экранирование не нужно — pydantic читает `$` дословно).
+- **Не используйте `$` в секретах.** Единый `.env` читают и pydantic (dev — `$` дословно),
+  и docker compose (test/prod — `$` = подстановка переменной). Чтобы значение совпадало
+  везде, в `SECRET_KEY`/`ADMIN_PASSWORD` не должно быть `$`. Удобно генерировать так:
+  `python -c "import secrets;print(secrets.token_urlsafe(48))"` (даёт только `[A-Za-z0-9_-]`).
 
 ## Аутентификация
 
 Методы входа зависят от окружения (`APP_ENV`):
 
-| | dev | prod |
+| | dev | test / prod |
 |---|---|---|
 | Telegram Login Widget | ✓ | ✓ (единственный) |
 | Вход по нику (stub) | ✓ | ✗ (физически отсутствует) |
 
 - **Stub-вход (по нику)** — только для разработки. Его код **физически не попадает в прод:**
   файлы `backend/app/auth/dev_stub.py` и `backend/app/routers/dev_auth.py` исключены из
-  Docker-образа (`.dockerignore`), роутер подключается лишь при `APP_ENV != production`
+  Docker-образа (`.dockerignore`), роутер подключается лишь при `APP_ENV=development`
   (`app/main.py`), а на фронте dev-блок вырезается из прод-сборки (`import.meta.env.DEV`).
 - **Telegram:** сервер проверяет подпись виджета (HMAC по `TELEGRAM_BOT_TOKEN`).
   `GET /api/auth/config` отдаёт доступные методы и `telegram_bot_username` для виджета.
@@ -127,29 +148,41 @@ docker compose -f docker-compose.test.yml down -v   # остановить и с
 3. В `.env`: `TELEGRAM_BOT_TOKEN=...`, `TELEGRAM_BOT_USERNAME=...` (без `@`).
 4. Домену нужен HTTPS (например, Cloudflare Tunnel) — виджет не работает по голому HTTP.
 
-Админ-вход (секретная панель, логин+пароль) — отдельный механизм, доступен в обоих окружениях.
+Админ-вход (секретная панель, логин+пароль) — отдельный механизм, доступен во всех окружениях.
 
 ## Окружения (dev / test / prod)
 
-Один и тот же код; контур выбирается тем, **чем и с каким `.env` запускаешь**:
+Один и тот же код; контур задаёт `APP_ENV` в **едином** `.env` (его читает лаунчер):
 
 | | dev | test (прод-клон локально) | prod (Pi) |
 |---|---|---|---|
-| Запуск | `uvicorn --reload` + `vite` | `docker compose -f docker-compose.test.yml` | `docker compose` |
-| Env-файл | `.env` (корень) | `.env.test` (корень) | `.env` (корень, на Pi) |
-| `APP_ENV` | `development` | `production` (форсится) | `production` (форсится) |
+| Запуск | `.\run.ps1` → `uvicorn --reload` + `vite` | `.\run.ps1` → `docker compose -f docker-compose.test.yml` | `docker compose up -d` |
+| `APP_ENV` | `development` | `test` (форсится в compose) | `production` (форсится в compose) |
+| Env-файл | единый `.env` | единый `.env` | единый `.env` (на Pi) |
 | Раздача SPA | Vite (HMR), :5173 | FastAPI, :8080 | FastAPI, :8000 |
 | База данных | `backend/data/dev/…` | том `db-data-test` (`/data`) | том `db-data` (`/data`) |
 | Вход игроков | Telegram + ник (stub) | только Telegram | только Telegram |
 
-- **Структура БД одна** (общие миграции Alembic), **файлы разные** — путь выбирается по
-  `APP_ENV` (`DEV_DATABASE_URL` / `PROD_DATABASE_URL`). Данные дева — в `backend/data/dev/`
-  (в образ **не попадают**: `data/` в `.dockerignore`).
-- **В Docker идёт только прод-код:** контейнер принудительно `APP_ENV=production`, dev-вход
-  (stub) физически исключён из образа. `test` — это тот же прод-образ, просто локально.
-- **`.env` один на машину**, в корне (рядом с `.env.example`). `test` использует свой
-  `.env.test` (чтобы крутить прод-клон рядом с dev, не мешая ему). Реальные `.env`/`.env.test`
-  хранятся только локально; рядом лежат шаблоны `*.example`.
+- **Один `.env` на машину** в корне (рядом с `.env.example`). `APP_ENV` в нём решает, что
+  запустит лаунчер (`development`/`test`); прод-контейнер это значение **игнорирует** и всегда
+  `production`. Отдельного `.env.test` больше нет.
+- **Структура БД одна** (общие миграции Alembic), **файлы разные**: dev → `DEV_DATABASE_URL`
+  (`backend/data/dev/`), test и prod → `PROD_DATABASE_URL` (том `/data`; у test и prod это
+  РАЗНЫЕ тома). Данные дева в образ **не попадают** (`data/` в `.dockerignore`).
+- **В Docker идёт только прод-код:** dev-вход (stub) и тесты физически исключены из образа
+  (`.dockerignore`); `test` — тот же образ, что и прод, просто локально и с `APP_ENV=test`.
+
+## Git и деплой
+
+- Ветка **`dev`** — рабочая: весь код, лаунчер, тесты. Повседневная разработка и `test` здесь.
+- Ветка **`main`** — релиз прода: готовое промоутишь из `dev` через `merge dev→main`. Файлы во
+  всех ветках одинаковы (окружение задаёт `.env`/compose, а не ветка) → merge безболезненный;
+  чистоту прод-образа обеспечивает `.dockerignore`, а не разные наборы файлов.
+- **Деплой на Pi:** `git pull` ветки `main` → `docker compose up -d --build`.
+- **Чистая выгрузка в папку без git** (опц.): `scripts/export-prod.sh <dir> main` (через
+  `git archive` + `export-ignore` — в папку идёт ровно прод-набор, без лаунчера/тестов/dev-входа).
+
+Секреты (`.env`) и данные (`data/`, `*.db`) в git не идут — см. `.gitignore`.
 
 ## Дополнения и фракции