218 lines
9.3 KiB
Markdown
218 lines
9.3 KiB
Markdown
# 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, затем удалите папку вручную.
|