|
1 | 1 | # telemetry-api |
2 | 2 |        |
| 3 | + |
| 4 | +> **telemetry-api** - сервис для сбора, хранения и аналитики телеметрии с устройств с функционалом фоновых вычислений и привязкой к пользователям. Сервис реализован на Python и представляет собой REST Api, написанную с использованием фреймворка FastAPI. Хранение данных в PostgreSQL, фоновые вычисления при помощи Celery, кэширование и backend для фоновых вычислений — Redis. |
| 5 | +
|
| 6 | +#### [Техническое задание](task.md) |
| 7 | + |
| 8 | +## Структура проекта: |
| 9 | +``` |
| 10 | +. |
| 11 | +├── .github # CI/CD для удалённого тестирования |
| 12 | +│ └── workflows |
| 13 | +│ └── ci.yml |
| 14 | +├── telemetry_api |
| 15 | +│ ├── api # Основные роутеры |
| 16 | +│ │ ├── __init__.py # Инициализация FastAPI и подключение роутеров |
| 17 | +│ │ ├── analytics.py |
| 18 | +│ │ ├── devices.py |
| 19 | +│ │ └── users.py |
| 20 | +│ ├── database # Инициализация БД исходя из режима |
| 21 | +│ │ ├── database.py |
| 22 | +│ │ └── models.py # Модели БД |
| 23 | +│ ├── schemas # Pydantic модели для сериализации и десериализации входных и выходных данных |
| 24 | +│ │ ├── analytics.py |
| 25 | +│ │ ├── devices.py |
| 26 | +│ │ └── users.py |
| 27 | +│ ├── worker |
| 28 | +│ │ ├── celery_app.py # Конфигурация Celery |
| 29 | +│ │ └── tasks |
| 30 | +│ │ └── device_analytics.py # Такси для фоновых вычислений аналитики |
| 31 | +│ ├── config.py # Конфиг, основанный на переменных окружения |
| 32 | +│ └── main.py # Инициализация БД, моделей и запуск сервиса |
| 33 | +├── tests # Тестирование основных роутеров и эндпоинтов |
| 34 | +│ ├── conftest.py # Настройка и инициализация фикстур |
| 35 | +│ ├── test_analytics.py |
| 36 | +│ ├── test_devices.py |
| 37 | +│ └── test_users.py |
| 38 | +├── docker-compose.yml # Развёртывания БД, Redis, Celery-worker и сервиса |
| 39 | +├── Dockerfile |
| 40 | +├── .env.example # Шаблонный файл переменных окружения |
| 41 | +├── .gitignore |
| 42 | +├── locustfile.py # Реализация нагрузочного тестирования через locust |
| 43 | +├── poetry.lock |
| 44 | +├── .pre-commit-config.yaml |
| 45 | +├── pyproject.toml # Настройка проекта и библиотек |
| 46 | +├── pytest.ini |
| 47 | +├── README.md # Описание проекта |
| 48 | +├── setup.cfg |
| 49 | +└── task.md # Техническое задание |
| 50 | +``` |
| 51 | + |
| 52 | +## Endpoints: |
| 53 | +* `POST`: `/users/` — Создание нового пользователя |
| 54 | +* `GET`: `/users/{user_id}` — Получение пользователя по id |
| 55 | +* `PATCH`: `/users/{user_id}` — Частичное обновление данных пользователя |
| 56 | +* `DELETE`: `/users/{user_id}` — Удаление пользователя |
| 57 | +* `GET`: `/users/` — Получение списка пользователей с пагинацией |
| 58 | +<br> |
| 59 | + |
| 60 | +* `POST`: `/devices/` — Создание нового устройства (с возможностью привязки к пользователю) |
| 61 | +* `GET`: `/devices/{device_id}` — Получение устройства по id |
| 62 | +* `PATCH`: `/devices/{device_id}` — Частичное обновление данных устройства (включая смену владельца) |
| 63 | +* `DELETE`: `/devices/{device_id}` — Удаление устройства |
| 64 | +* `GET`: `/devices/` — Получение списка устройств с пагинацией |
| 65 | +<br> |
| 66 | + |
| 67 | +* `POST`: `/analytics/{device_id}/data` — Добавление одного измерения для конкретного устройства |
| 68 | +* `GET`: `/analytics/` — Получение агрегированной аналитики по устройству или пользователю (с возможностью фильтрации по времени и пагинацией) |
| 69 | +* `POST`: `/analytics/generate` — Запуск фоновой задачи через Celery для генерации аналитики асинхронно |
| 70 | +* `GET`: `/analytics/tasks/{task_id}` — Получение статуса или готового (пагинированного) результата фоновой задачи генерации аналитики |
| 71 | +<br> |
| 72 | + |
| 73 | +* `GET`: `/docs/` — Подробная документация с описанием нетривиальных функций и примерами данных |
| 74 | + |
| 75 | +## Требования: |
| 76 | +* Python 3.13.11+ |
| 77 | +* Poetry |
| 78 | +* Docker & Docker Compose |
| 79 | +* PostgreSQL |
| 80 | +* Redis |
| 81 | +* Celery |
| 82 | + |
3 | 83 | ## Использование: |
| 84 | +Необходимо указать переменные окружения в `.env` [*(Шаблон)*](.env.example): |
| 85 | +```env |
| 86 | +# Common |
| 87 | +DEBUG=True # Режим отладки. Используется SQLite |
| 88 | +HOST=0.0.0.0 |
| 89 | +PORT=8000 |
| 90 | +CELERY_RESULT_EXPIRES=43200 # Таймаут, после которого удаляется результат выполнения таски Celery |
| 91 | +
|
| 92 | +# PostgreSQL |
| 93 | +POSTGRES_USER= |
| 94 | +POSTGRES_PASSWORD= |
| 95 | +POSTGRES_HOST= |
| 96 | +POSTGRES_PORT= |
| 97 | +POSTGRES_DB= |
| 98 | +
|
| 99 | +# Redis |
| 100 | +REDIS_HOST= |
| 101 | +REDIS_PORT= |
| 102 | +REDIS_DB= |
| 103 | +``` |
| 104 | + |
| 105 | +Развёртывание при помощи `docker-compose`: |
4 | 106 | ``` |
5 | 107 | docker compose up -d --build |
6 | 108 | ``` |
7 | | - |
8 | | -## Описание системы: |
9 | | -К реализации предлагается система учета и анализа данных, поступающих с условного устройства. Полученные данные привязываются к временной метке и устройству, с которого пришли данные, и сохраняются в БД. Набор данных используется для дальнейшего анализа. |
10 | | - |
11 | | -## Требования к системе: |
12 | | - |
13 | | -### Функциональные: |
14 | | -- В системе реализован сбор статистики с устройства по его идентификатору |
15 | | -- формат получаемой статистики - {“x”: float, “y”: float, “z”:float} |
16 | | -- В системе реализован анализ собранной статистики с устройства за определенный период и за все время |
17 | | -- Результатами анализа являются числовые характеристики величины: |
18 | | - - минимальное значение |
19 | | - - максимальное значение |
20 | | - - количество |
21 | | - - сумма |
22 | | - - медиана |
23 | | -- Система поддерживает добавление пользователей устройств* |
24 | | -- В системе реализован функционал получения анализа показаний устройств по идентификатору пользователя*: |
25 | | - - агрегированные результаты для всех устройств |
26 | | - - для каждого устройства отдельно |
27 | | - |
28 | | -### Нефункциональные: |
29 | | -- архитектура REST |
30 | | -- фреймворк реализации сервиса FastApi |
31 | | -- собранные данные хранятся в БД на выбор разработчика |
32 | | -- аналитика показателей происходит в асинхронном режиме при помощи фреймворка Celery* |
33 | | -- Реализовано нагрузочное тестирование через инструмент locust* |
34 | | -- Сервис и его окружение разворачивается средствами docker + docker-compose |
35 | | - |
36 | | -## Примечания: |
37 | | -- Пункты отмеченные "\*" необязательны к выполнению |
|
0 commit comments