Добавить документацию по управлению пользователями (MANAGE_USERS.md)

backend/MANAGE_USERS.md

@@ -0,0 +1,163 @@
+# Управление пользователями панели
+
+Публичная регистрация в панели **закрыта** — это сделано из соображений
+безопасности, чтобы никто посторонний не мог зайти и создавать себе VPS
+через ваш Proxmox.
+
+Все учётные записи создаёт администратор одним из способов:
+
+1. **Через CLI внутри контейнера backend** (рекомендуемый способ).
+2. **Через эндпоинт `/admin/users` POST** (уже залогинившись как админ).
+3. **Через UI → Admin → Users → «Создать»** (если добавите такую кнопку
+   в `frontend/src/pages/AdminUsers.jsx`).
+
+Документ описывает первый способ — CLI.
+
+---
+
+## 1. Базовый вызов
+
+```bash
+docker compose exec backend python -m app.manage_users <команда> [аргументы]
+```
+
+> `app.manage_users` уже лежит в репозитории (`backend/app/manage_users.py`)
+> и автоматически попадает в образ backend — отдельно класть его в Dockerfile
+> не нужно.
+
+### Все команды
+
+```text
+list                                          — список всех пользователей
+create <email> <password> [admin|client]      — создать пользователя
+activate <email>                              — включить (is_active=True)
+deactivate <email>                            — выключить (is_active=False)
+set-role <email> <admin|client>               — сменить роль
+reset-password <email> <new_password>         — сменить пароль
+delete <email>                                — удалить пользователя
+```
+
+Если пароль не указан в аргументах — CLI безопасно спросит его
+интерактивно через `getpass` (символы не отображаются в терминале).
+
+---
+
+## 2. Типовые сценарии
+
+### 2.1. Первый запуск панели — создать админа
+
+> Самый первый пользователь создаётся **не через CLI**, а через bootstrap:
+> при пустой БД endpoint `POST /auth/register` остаётся открытым и создаёт
+> админа. Если вы только что подняли панель — зайдите на страницу
+> `/register`, заполните форму один раз и получите admin-аккаунт.
+> Сразу после этого вход через `/register` закрывается навсегда.
+
+```bash
+# Способ через CLI (если вы предпочитаете не использовать /register):
+docker compose exec backend python -m app.manage_users \
+    create admin@example.com 'StrongP@ssw0rd!' admin
+```
+
+### 2.2. Создать обычного клиента
+
+```bash
+docker compose exec backend python -m app.manage_users \
+    create ivan@example.com 'TempP@ss123' client
+```
+
+Клиент сразу сможет войти (`is_active=True` по умолчанию) и видеть
+доступные шаблоны VPS.
+
+### 2.3. Временно отключить пользователя
+
+```bash
+docker compose exec backend python -m app.manage_users deactivate ivan@example.com
+# Пользователь не сможет войти, его VPS остаются.
+
+docker compose exec backend python -m app.manage_users activate ivan@example.com
+# Вернуть доступ.
+```
+
+### 2.4. Сделать пользователя админом (или наоборот)
+
+```bash
+docker compose exec backend python -m app.manage_users set-role ivan@example.com admin
+```
+
+> ⚠️ CLI не даст понизить **единственного** активного администратора —
+> сначала создайте/назначьте другого admin.
+
+### 2.5. Сбросить пароль
+
+```bash
+docker compose exec backend python -m app.manage_users \
+    reset-password ivan@example.com 'NewP@ssw0rd'
+# или интерактивно (пароль не светится в истории):
+docker compose exec backend python -m app.manage_users reset-password ivan@example.com
+```
+
+### 2.6. Удалить пользователя
+
+```bash
+docker compose exec backend python -m app.manage_users delete ivan@example.com
+```
+
+> Это удалит запись пользователя из БД. **Его VPS в Proxmox останутся** —
+> панель их создаёт через API, и они живут независимо. Если хотите удалить
+> и VPS — сделайте это через UI Proxmox или дашборд панели до удаления
+> пользователя.
+
+### 2.7. Посмотреть всех пользователей
+
+```bash
+docker compose exec backend python -m app.manage_users list
+```
+
+Вывод:
+
+```text
+  ID  EMAIL                             ROLE    ACTIVE  CREATED_AT
+------------------------------------------------------------------------------
+   3  ivan@example.com                  client  да      2026-08-10 12:34
+   2  petr@example.com                  client  нет     2026-08-10 11:02
+   1  admin@example.com                 admin   да      2026-08-09 22:11
+```
+
+---
+
+## 3. Защитные ограничения CLI
+
+Скрипт намеренно блокирует опасные операции:
+
+- **Нельзя удалить или понизить единственного активного admin** — защита
+  от случайной потери единственного администратора. Если вам кажется,
+  что это окей — сделайте это через прямой SQL-запрос к БД
+  (`docker compose exec db psql ...`), приняв на себя ответственность.
+- **Пароль должен быть не короче 6 символов** (как и в UI).
+- **Email нормализуется** (lowercase + trim), чтобы `User@Example.com`
+  и `user@example.com` не оказались разными пользователями.
+
+---
+
+## 4. Локальный запуск без Docker
+
+Если вы разрабатываете панель вне Docker и используете SQLite из `config.py`:
+
+```bash
+cd backend
+python -m app.manage_users create admin@example.com password admin
+```
+
+Скрипт читает `DATABASE_URL` из окружения или `.env` (`backend/.env`),
+так что работает и в dev-режиме, и в проде.
+
+---
+
+## 5. Если что-то пошло не так
+
+| Симптом | Причина | Решение |
+|---|---|---|
+| `ModuleNotFoundError: No module named 'app'` | запускаете не из `backend/` | добавьте `cd backend` либо укажите `PYTHONPATH=/app:$PYTHONPATH` |
+| `OperationalError: connection refused` | БД ещё не стартовала | подождите, пока `docker compose ps` покажет `db` healthy |
+| `❌ Пользователь уже существует` | дубль email | проверьте `list` — возможно, регистрировались раньше |
+| `❌ Нельзя понизить единственного администратора` | защита CLI | создайте второго admin, затем понизьте первого |