feat: improve docs

volychev · web-flow · commit 89b7471f3ae0 · 2026-05-15T12:32:21.000+03:00
diff --git a/README.md b/README.md
@@ -1,96 +1,104 @@
 # telemetry-api
 ![Python](https://img.shields.io/badge/Python-ffffff?logo=python&style=for-the-badge&color=ffffff&logoColor=3776AB) ![FastAPI](https://img.shields.io/badge/FastAPI-ffffff?logo=fastapi&style=for-the-badge&color=ffffff&logoColor=009688) ![PostgreSQL](https://img.shields.io/badge/PostgreSQL-ffffff?logo=postgresql&style=for-the-badge&color=ffffff&logoColor=4169E1) ![Redis](https://img.shields.io/badge/Redis-ffffff?logo=redis&style=for-the-badge&color=ffffff&logoColor=DC382D) ![Celery](https://img.shields.io/badge/Celery-ffffff?logo=celery&style=for-the-badge&color=ffffff&logoColor=37814A) ![Locust](https://img.shields.io/badge/Locust-ffffff?style=for-the-badge&color=ffffff) ![Docker](https://img.shields.io/badge/Docker-ffffff?logo=docker&style=for-the-badge&color=ffffff&logoColor=2496ED)
 
-> **telemetry-api** - сервис для сбора, хранения и аналитики телеметрии с устройств с функционалом фоновых вычислений и привязкой к пользователям. Сервис реализован на Python и представляет собой REST Api, написанную с использованием фреймворка FastAPI. Хранение данных в PostgreSQL, фоновые вычисления при помощи Celery, кэширование и backend для фоновых вычислений — Redis.
+**telemetry-api** — асинхронный REST API сервис для сбора, хранения и анализа телеметрии с устройств. Включает в себя механизмы фоновых вычислений, кэширования, валидацию данных и систему управления пользователями.
 
-#### [Техническое задание](task.md)
+* #### [Техническое задание](task.md)
+
+Основная логика разделена на два сценария. Синхронный эндпоинт используется для быстрой обработки небольших данных. Для тяжелых аналитик реализован запуск фоновой задачи через **Celery + Redis**, что позволяет не блокировать основной пул потоков HTTP-запросов. Результаты задач кэшируются с пагинацией.
 
 ## Структура проекта:
-```
+```text
 .
-├── .github                          # CI/CD для удалённого тестирования
-│   └── workflows
-│       └── ci.yml
+├── .github                          # CI/CD для автоматического тестирования
+│   └── workflows
+│       └── ci.yml
 ├── telemetry_api                    
-│   ├── api/v1                       # Основные роутеры 
-│   │   ├── __init__.py              # Инициализация FastAPI и подключение роутеров
-│   │   ├── analytics.py
-│   │   ├── devices.py
-│   │   └── users.py
-│   ├── database                     # Инициализация БД исходя из режима
-│   │   ├── database.py
-│   │   └── models.py                # Модели БД
-│   ├── schemas                      # Pydantic модели для сериализации и десериализации входных и выходных данных
-│   │   ├── analytics.py
-│   │   ├── devices.py
-│   │   └── users.py
-│   ├── worker                       
-│   │   ├── celery_app.py            # Конфигурация Celery
-│   │   └── tasks
-│   │       └── device_analytics.py  # Такси для фоновых вычислений аналитики
-│   ├── config.py                    # Конфиг, основанный на переменных окружения
-│   └── main.py                      # Инициализация БД, моделей и запуск сервиса
-├── tests                            # Тестирование основных роутеров и эндпоинтов
-│   ├── conftest.py                  # Настройка и инициализация фикстур
+│   ├── api/v1                       # Основные роутеры 1-й версии API
+│   │   ├── __init__.py              # Инициализация приложения и подключение роутеров
+│   │   ├── analytics.py
+│   │   ├── devices.py
+│   │   └── users.py
+│   ├── database                     # Конфигурация подключения к БД
+│   │   ├── database.py
+│   │   └── models.py                # ORM-модели SQLAlchemy
+│   ├── schemas                      # Pydantic-модели (валидация, сериализация/десериализация)
+│   │   ├── analytics.py
+│   │   ├── devices.py
+│   │   └── users.py
+│   ├── worker                       
+│   │   ├── celery_app.py            # Конфигурация брокера и бэкенда Celery
+│   │   └── tasks
+│   │       └── device_analytics.py  # Таски для фоновых вычислений аналитики
+│   ├── config.py                    # Валидация переменных окружения (pydantic-settings)
+│   └── main.py                      # Точка входа
+├── tests                            # Интеграционные и юнит-тесты (Pytest)
+│   ├── conftest.py                  # Асинхронные фикстуры и настройка тестовой БД
 │   ├── test_analytics.py
 │   ├── test_devices.py
 │   └── test_users.py
-├── docker-compose.yml               # Развёртывания БД, Redis, Celery-worker и сервиса
+├── locustfile.py                    # Сценарии нагрузочного тестирования (Locust)
+├── pyproject.toml                   # Конфигурация проекта (Poetry)
+├── poetry.lock
+├── .env.example                     # Шаблон переменных окружения
 ├── Dockerfile
-├── .env.example                     # Шаблонный файл переменных окружения
+├── docker-compose.yml               # Оркестрация (API, PostgreSQL, Redis, Celery-worker)     
+├── pytest.ini                       # Конфигурация тестирования
+├── setup.cfg                        # Конфигурация шаблонного проекта
 ├── .gitignore
-├── locustfile.py                    # Реализация нагрузочного тестирования через locust
-├── poetry.lock
 ├── .pre-commit-config.yaml
-├── pyproject.toml                   # Настройка проекта и библиотек
-├── pytest.ini                       
 ├── README.md                        # Описание проекта
-├── setup.cfg
-└── task.md                          # Техническое задание
+└── task.md                          # Техническое задание 
 ```
 
-## Endpoints:
-Базовый префикс API: `/api`
-Текущая версия: `/v1`
+## Endpoints
+
+> *Полная спецификация, схемы и примеры данных доступны локально по адресу:* `http://localhost:{PORT}/docs` *(Swagger UI).*
+
+Базовый префикс API: `/api` ; Текущая версия: `/v1`
+
+### Пользователи (`Users`)
 
 * `POST`: `/api/v1/users/` — Создание нового пользователя
 * `GET`: `/api/v1/users/{user_id}` — Получение пользователя по id
-* `PATCH`: `/api/v1/users/{user_id}` — Частичное обновление данных пользователя
+* `PATCH`: `/api/v1/users/{user_id}` — Частичное обновление данных пользователя (с валидацией уникальности)
 * `DELETE`: `/api/v1/users/{user_id}` — Удаление пользователя
 * `GET`: `/api/v1/users/` — Получение списка пользователей с пагинацией
-<br>
 
-* `POST`: `/api/v1/devices/` — Создание нового устройства (с возможностью привязки к пользователю)
+### Устройства (`Devices`)
+
+* `POST`: `/api/v1/devices/` — Создание нового устройства (с возможностью привязки к `user_id`)
 * `GET`: `/api/v1/devices/{device_id}` — Получение устройства по id
 * `PATCH`: `/api/v1/devices/{device_id}` — Частичное обновление данных устройства (включая смену владельца)
 * `DELETE`: `/api/v1/devices/{device_id}` — Удаление устройства
 * `GET`: `/api/v1/devices/` — Получение списка устройств с пагинацией
-<br>
+
+### Аналитика (`Analytics`)
 
 * `POST`: `/api/v1/analytics/{device_id}/data` — Добавление одного измерения для конкретного устройства
-* `GET`: `/api/v1/analytics/` — Получение агрегированной аналитики по устройству или пользователю (с возможностью фильтрации по времени и пагинацией)
-* `POST`: `/api/v1/analytics/generate` — Запуск фоновой задачи через Celery для генерации аналитики асинхронно
-* `GET`: `/api/v1/analytics/tasks/{task_id}` — Получение статуса или готового (пагинированного) результата фоновой задачи генерации аналитики
-<br>
+* `GET`: `/api/v1/analytics/` — Получение агрегированной аналитики (min, max, count, sum, median) по устройству или пользователю (с фильтрацией по времени и пагинацией)
+* `POST`: `/api/v1/analytics/generate` — Запуск фоновой задачи через Celery для асинхронной генерации аналитики
+* `GET`: `/api/v1/analytics/tasks/{task_id}` — Получение статуса или готового результата (с пагинацией) фоновой задачи
 
-* `GET`: `/docs/` — Подробная документация с описанием нетривиальных функций и примерами данных
+## Требования
 
-## Требования:
 * Python 3.13.11+
 * Poetry
 * Docker & Docker Compose
 * PostgreSQL
 * Redis
 * Celery
 
-## Использование:
-Необходимо указать переменные окружения в `.env` [*(Шаблон)*](.env.example):
+## Развертывание и использование
+
+1. Склонируйте репозиторий и укажите переменные окружения в файле `.env` на основе шаблона *[(.env.example)](https://www.google.com/search?q=.env.example)*:
+
 ```env
 # Common
-DEBUG=True                    # Режим отладки. Используется SQLite 
-HOST=0.0.0.0              
+DEBUG=True                    # Режим отладки (Используется in-memory SQLite) 
+HOST=0.0.0.0                  
 PORT=8000
-CELERY_RESULT_EXPIRES=43200   # Таймаут, после которого удаляется результат выполнения таски Celery
+CELERY_RESULT_EXPIRES=43200   # Время жизни результатов тасок Celery в Redis (в секундах)
 
 # PostgreSQL
 POSTGRES_USER=
@@ -105,7 +113,8 @@ REDIS_PORT=
 REDIS_DB=
 ```
 
-Развёртывание при помощи `docker-compose`:
-```
+2. Запустите проект при помощи `docker-compose`:
+
+```bash
 docker compose up -d --build
 ```
