Загрузить файлы в «/»
This commit is contained in:
217
README.md
Normal file
217
README.md
Normal file
@@ -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, затем удалите папку вручную.
|
||||
5
requirements.txt
Normal file
5
requirements.txt
Normal file
@@ -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
|
||||
50
start.sh
Normal file
50
start.sh
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user