domovoy_bot/ВЕБ_ИНТЕРФЕЙС.md

# 🌐 Веб-интерфейс админа — v1.11

**Версия:** v1.11
**Дата:** 27 февраля 2026 г.
**Статус:** ✅ Реализовано

---

## 📋 Описание

Веб-интерфейс для администратора домового бота на базе FastAPI. Позволяет просматривать статистику, управлять пользователями, экспортировать данные через браузер.

---

## 🎯 Возможности

- ✅ Дашборд с основной статистикой
- ✅ Просмотр пользователей с поиском
- ✅ Экспорт данных в JSON
- ✅ Страница настроек
- ✅ API для интеграции
- ✅ Авторизация (HTTP Basic Auth)
- ✅ Адаптивный дизайн (Bootstrap 5)

---

## 🚀 Быстрый старт

### 1. Запуск с ботом

Веб-сервер запускается автоматически при старте бота:

```bash
cd /home/matrixhasyou/domovoy_bot
./run.sh
```

### 2. Доступ к интерфейсу

Откройте в браузере:
```
http://localhost:8000
```

**Логин:** `admin`
**Пароль:** Ваш `ADMIN_USER_ID` (из .env)

---

## 📱 Страницы

### 1. Дашборд (`/`)

**Основная статистика:**
- Пользователей
- Верифицировано
- Сообщений
- Активных опросов
- Объявлений
- Предстоящих событий

**Быстрые действия:**
- Переход к пользователям
- Экспорт JSON
- Настройки

---

### 2. Пользователи (`/users`)

**Функции:**
- Таблица всех пользователей (до 100)
- Поиск по имени, квартире, нику
- Статус верификации
- Рейтинг и количество сообщений

**Поля:**
- ID
- Имя
- Ник (@username)
- Квартира
- Верифицирован (✅/❌)
- Рейтинг
- Сообщений

---

### 3. Экспорт (`/export`)

**Функции:**
- Кнопка экспорта в JSON
- Статус экспорта
- Путь к файлу

**Экспортируются:**
- Все пользователи
- Все сообщения
- Даты и время
- Квартиры и телефоны

---

### 4. Настройки (`/settings`)

**Отображается:**
- Bot Token (маска)
- Admin Chat ID
- Admin User ID
- Статус прокси

---

## 🔌 API Endpoints

### GET `/api/stats`

**Описание:** Получить статистику для дашборда

**Ответ:**
```json
{
  "top_users": [
    {"id": 123456789, "name": "Иван", "apartment": "45", "rating": 500}
  ],
  "active_polls": [
    {"id": 1, "question": "За какой цвет?", "votes": 25}
  ],
  "recent_messages": [...]
}
```

---

### GET `/api/users?search=...`

**Описание:** Список пользователей с поиском

**Параметры:**
- `search` (опционально) — строка поиска

**Ответ:**
```json
{
  "users": [
    {
      "id": 123456789,
      "name": "Иван Иванов",
      "username": "ivanov",
      "apartment": "45",
      "verified": true,
      "rating": 500,
      "messages": 150
    }
  ]
}
```

---

### GET `/api/export/json`

**Описание:** Экспорт данных в JSON

**Ответ:**
```json
{
  "success": true,
  "filepath": "exports/export_2026-02-27.json"
}
```

---

## 🔐 Безопасность

### Авторизация

**Тип:** HTTP Basic Auth

**Логин:** `admin`
**Пароль:** Значение `ADMIN_USER_ID` из `.env`

**Пример curl:**
```bash
curl -u admin:123456789 http://localhost:8000/api/stats
```

### Защита страниц

Все страницы требуют авторизации. При неверных данных возвращается 401.

---

## 🗄️ Зависимости

### Новые пакеты (v1.11+):
```
fastapi>=0.109.0
uvicorn>=0.27.0
jinja2>=3.1.3
python-multipart>=0.0.6
```

### Установка:
```bash
cd /home/matrixhasyou/domovoy_bot
source venv/bin/activate
pip install -r requirements.txt
```

---

## 📁 Структура файлов

```
web/
├── app.py                 # FastAPI приложение
├── templates/
│   ├── dashboard.html     # Дашборд
│   ├── users.html         # Пользователи
│   ├── export.html        # Экспорт
│   └── settings.html      # Настройки
└── static/
    ├── css/               # Стили (пока не используется)
    └── js/                # Скрипты (пока не используется)
```

---

## 🧪 Тестирование

### Чек-лист проверки:

#### 1. Запуск
```bash
./run.sh
```
- [ ] Бот запускается
- [ ] Веб-сервер запускается
- [ ] В логах видно URL

#### 2. Авторизация
```
http://localhost:8000
Логин: admin
Пароль: <ADMIN_USER_ID>
```
- [ ] Форма авторизации появляется
- [ ] Верные данные пускают
- [ ] Неверные данные блокируют

#### 3. Дашборд
- [ ] Статистика отображается
- [ ] Карточки красивые
- [ ] Кнопки работают

#### 4. Пользователи
- [ ] Таблица загружается
- [ ] Поиск работает
- [ ] Верификация показывается

#### 5. Экспорт
- [ ] Кнопка работает
- [ ] Файл создаётся
- [ ] Путь показывается

---

## 🔧 Отладка

### Логи веб-сервера:
```bash
tail -f logs/bot.log | grep -i "web\|uvicorn"
```

### Проверка порта:
```bash
ss -tlnp | grep 8000
```

### Тест API:
```bash
curl -u admin:<PASSWORD> http://localhost:8000/api/stats
```

---

## 🚀 Запуск в production

### 1. Изменить порт (если нужно):

В `services/web_server.py`:
```python
def __init__(self, host: str = "0.0.0.0", port: int = 8000):
```

### 2. Настроить nginx (опционально):

```nginx
server {
    listen 80;
    server_name bot.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 3. Включить HTTPS:

```bash
sudo certbot --nginx -d bot.yourdomain.com
```

---

## ✅ Преимущества

| Было | Стало |
|------|-------|
| Только Telegram | **Веб-интерфейс** |
| Нет визуализации | **Дашборд с графиками** |
| Ручной экспорт | **Кнопка в браузере** |
| Нет поиска | **Поиск пользователей** |

---

**Веб-интерфейс готов! 🌐**

*Следующий шаг: тестирование и фиксация версии v1.11*