From 6b062e68fddb27a728f82b6659b927bc36207e6f Mon Sep 17 00:00:00 2001 From: NikitaKu Date: Thu, 2 Jul 2026 20:28:44 +0000 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=B3=D1=80=D1=83=D0=B7=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B=20=D0=B2=20=C2=AB?= =?UTF-8?q?/=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 217 +++++++++++++++++++++++++++++++++++++++++++++++ requirements.txt | 5 ++ start.sh | 50 +++++++++++ 3 files changed, 272 insertions(+) create mode 100644 README.md create mode 100644 requirements.txt create mode 100644 start.sh diff --git a/README.md b/README.md new file mode 100644 index 0000000..ef75e22 --- /dev/null +++ b/README.md @@ -0,0 +1,217 @@ +# 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, затем удалите папку вручную. diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..d3f02f8 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +fastapi>=0.115.0 +uvicorn[standard]>=0.34.0 +bcrypt>=4.0.0 +python-multipart>=0.0.20 +pydantic[email]>=2.11.0 diff --git a/start.sh b/start.sh new file mode 100644 index 0000000..8d7da27 --- /dev/null +++ b/start.sh @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +cd "$ROOT" + +PYTHON="${PYTHON:-python3}" +VENV="$ROOT/.venv" +PORT="${PORT:-8000}" + +echo "==> ROBO-OPS: сборка и запуск" +echo " Каталог: $ROOT" + +if ! command -v "$PYTHON" >/dev/null 2>&1; then + if command -v python >/dev/null 2>&1; then + PYTHON=python + else + echo "Ошибка: Python 3 не найден. Установите Python 3.10+" + exit 1 + fi +fi + +echo "==> Python: $($PYTHON --version)" + +if [ ! -d "$VENV" ]; then + echo "==> Создание виртуального окружения..." + "$PYTHON" -m venv "$VENV" +fi + +# shellcheck disable=SC1091 +source "$VENV/bin/activate" 2>/dev/null || source "$VENV/Scripts/activate" + +echo "==> Установка зависимостей..." +python -m pip install --upgrade pip -q +python -m pip install -r requirements.txt -q + +mkdir -p "$ROOT/data" + +export ROBO_OPS_VIA_START_SH=1 +export DATABASE_PATH="${DATABASE_PATH:-$ROOT/data/robo_ops.db}" +export EXTERNAL_API_KEY="${EXTERNAL_API_KEY:-robo-ops-external-demo-key-2026}" + +echo "" +echo "==> Сервер запущен: http://localhost:$PORT" +echo " Регистрация: http://localhost:$PORT/register" +echo " API docs: http://localhost:$PORT/docs" +echo " Остановка: Ctrl+C" +echo "" + +exec python -m uvicorn app.main:app --host 0.0.0.0 --port "$PORT" --reload