# ROBO-OPS — личный кабинет оператора робота

Веб-приложение для управления роботами и ведения профиля оператора.  
Стек: **Python, FastAPI, SQLite, HTML, CSS, JavaScript**.

---

## Запуск приложения

**Единственный способ запуска — скрипт `start.sh`.**

Другие команды (`python run.py`, `uvicorn`, `python -m http.server` и т.п.) **не поддерживаются** — приложение откажется стартовать без переменной окружения, которую выставляет только `start.sh`.

### Требования

- Python 3.10 или новее
- Bash (Linux, macOS, Git Bash или WSL на Windows)

### Первый запуск

```bash
cd путь/к/ПРАКТИКА
chmod +x start.sh    # один раз, если скрипт не исполняемый
./start.sh
```

### Что делает `start.sh`

1. Определяет каталог проекта
2. Создаёт виртуальное окружение `.venv` (если его нет) и устанавливает зависимости из `requirements.txt`
3. Создаёт папку `data/` и файл базы SQLite (если их нет)
4. Запускает сервер FastAPI на порту **8000**

> **Для проверяющего:** в архив сдаётся только исходный код (16 файлов). Папки `.venv`, `data/` и `__pycache__/` **не нужны** — они создаются автоматически при первом запуске `./start.sh`.

### После запуска

| Адрес | Назначение |
|-------|------------|
| http://localhost:8000 | Главная (панель роботов) |
| http://localhost:8000/register | Регистрация |
| http://localhost:8000/login | Вход |
| http://localhost:8000/docs | Документация API (Swagger) |

Остановка сервера: **Ctrl+C** в терминале.

### Переменные окружения (необязательно)

| Переменная | По умолчанию | Описание |
|------------|--------------|----------|
| `PORT` | `8000` | Порт сервера |
| `EXTERNAL_API_KEY` | `robo-ops-external-demo-key-2026` | Ключ для внешнего API |
| `DATABASE_PATH` | `./data/robo_ops.db` | Путь к файлу БД |

Пример:

```bash
PORT=9000 ./start.sh
```

---

## Принцип работы приложения

### Общая схема

```
Браузер (HTML/CSS/JS)
        │
        ▼  HTTP + cookie-сессия
   FastAPI (app/main.py)
        │
        ▼
   SQLite (data/robo_ops.db)
        ▲
        │  X-API-Key
   Внешние приложения
```

Фронтенд — статические страницы в папке `static/`.  
Бэкенд — REST API на FastAPI.  
Данные хранятся в SQLite.

### Регистрация и авторизация

1. Пользователь регистрируется на `/register` (email + пароль от 6 символов).
2. Пароль хешируется через **bcrypt** и сохраняется в таблице `users`.
3. При регистрации или входе создаётся **сессия** в таблице `sessions`.
4. В браузер отправляется HttpOnly-cookie `robo_ops_session` (срок — 24 часа).
5. Токен сессии в БД хранится в виде SHA-256 хеша, не в открытом виде.

Без активной сессии доступ к главной странице и API закрыт — браузер перенаправляется на `/login`.

### Личный кабинет

В профиле оператора хранятся и редактируются:

- электронная почта (только чтение после регистрации)
- имя, фамилия, отчество
- возраст
- номер телефона
- **рейтинг** и **баллы** (обновляются также через внешнее API)

На странице профиля отображаются **активные сессии** текущего пользователя.

### Панель управления роботами

У каждого пользователя — свой набор из 4 роботов (настройки в таблице `robot_settings`).

При изменении параметров (режим, скорость, чувствительность, аварийная остановка, ночной режим):

- пересчитываются характеристики робота (скорость, температура, статус, датчики);
- данные сохраняются в SQLite через API;
- при переходе между страницами настройки не теряются.

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

| Мера | Реализация |
|------|------------|
| Пароли | bcrypt-хеширование |
| Сессии | HttpOnly cookie, хеш токена в БД, срок жизни 24 ч |
| Внешний API | Заголовок `X-API-Key` |
| Валидация | Pydantic-схемы для всех входных данных |
| SQL | Параметризованные запросы |

---

## API

### Для веб-приложения (нужна cookie-сессия)

| Метод | Путь | Описание |
|-------|------|----------|
| POST | `/api/auth/register` | Регистрация |
| POST | `/api/auth/login` | Вход |
| POST | `/api/auth/logout` | Выход |
| GET | `/api/auth/me` | Текущий пользователь |
| GET/PUT | `/api/profile` | Профиль |
| GET | `/api/sessions` | Активные сессии |
| GET/PUT | `/api/robots` | Настройки роботов |

### Для внешних приложений (заголовок `X-API-Key`)

| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/api/external/users` | Список пользователей |
| GET | `/api/external/users/{id}` | Пользователь по ID |
| GET | `/api/external/users/by-email/{email}` | Пользователь по email |
| GET | `/api/external/sessions` | Активные сессии |
| POST | `/api/external/data` | Запись данных |
| GET | `/api/external/data` | Чтение записей |

Пример записи баллов из внешней системы:

```bash
curl -X POST http://localhost:8000/api/external/data \
  -H "X-API-Key: robo-ops-external-demo-key-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 1,
    "source_app": "mission-tracker",
    "data_key": "mission_complete",
    "data_value": {"points": 50, "rating": 4.5}
  }'
```

Поля `points` и `rating` в `data_value` автоматически обновляют профиль пользователя.

---

## Структура проекта

```
ПРАКТИКА/
├── start.sh              ← единственная точка запуска
├── README.md             ← эта инструкция
├── requirements.txt      ← зависимости Python
├── app/
│   ├── __init__.py
│   ├── main.py           ← FastAPI, маршруты, API
│   ├── database.py       ← SQLite, модели данных
│   ├── security.py       ← bcrypt, токены сессий
│   ├── schemas.py        ← валидация запросов
│   └── config.py         ← настройки
└── static/
    ├── index.html        ← главная страница
    ├── login.html        ← вход
    ├── register.html     ← регистрация
    ├── css/styles.css    ← стили
    └── js/               ← api.js, app.js, auth.js
```

После первого запуска `./start.sh` рядом появятся служебные каталоги (их не нужно сдавать):

- `.venv/` — виртуальное окружение Python
- `data/` — файл базы `robo_ops.db`

---

## Типичные проблемы

**«Приложение запускается только через ./start.sh»**  
Вы запустили сервер в обход скрипта. Используйте `./start.sh`.

**На Windows не работает `./start.sh`**  
Запускайте через **Git Bash** или **WSL**, не через обычный PowerShell.

**Порт 8000 занят**  
```bash
PORT=9000 ./start.sh
```

**Нет Python**  
Установите Python 3.10+ с https://python.org и повторите `./start.sh`.

**Перед отправкой архива**  
Не включайте папки `.venv`, `data/` и `__pycache__/`. Если `.venv` не удаляется (файлы заняты процессом Python), закройте терминалы и IDE, затем удалите папку вручную.