Organization Directory API

Описание проекта

Organization Directory API — это REST API-приложение, предназначенное для ведения справочника организаций, зданий и видов деятельности (активностей). Приложение реализовано на базе FastAPI и SQLAlchemy с использованием асинхронного взаимодействия. Оно поддерживает фильтрацию организаций по названию, виду деятельности, а также обеспечивает поиск по координатам (радиус и bounding box).

Основное назначение приложения — давать быстрый доступ к справочнику организаций, с информацией о зданиях и видах деятельности, а также предоставлять удобные методы поиска.

Технологии

• Python 3.12+
• FastAPI: создание REST API
• Pydantic: схемы и валидация данных
• SQLAlchemy + Alembic: работа с БД и управление миграциями
• AsyncIO: асинхронная обработка запросов
• Docker: контейнеризация приложения
• HTTPX / requests: обращение к сторонним API (геолокация через Nominatim API)

Текущий функционал приложения

1. Справочник Организаций:
   • Поля:
     • Название
     • Набор телефонных номеров
     • Здание (одно из существующих)
     • Список видов деятельности (может быть несколько)
2. Справочник Зданий:
   • Поля:
     • Адрес
     • Географические координаты (широта, долгота)
   • Автоматическое определение координат по адресу через Nominatim API (пример: г. Москва, ул. Ленина, 1)
3. Справочник Видов Деятельности:
   • Поля:
     • Название
     • Возможна древовидная структура (вкладывание)
   • Ограничение вывода на глубину 3 уровня
4. Стек: FastAPI + Pydantic + SQLAlchemy + Alembic. Ответы от API — в формате JSON.

Поддерживаемые методы API

• Список всех зданий: GET /buildings/
• Получение информации о здании: GET /buildings/{building_id}
• Создание нового здания: POST /buildings/ (опционально, координаты определяются по адресу)
• Список всех видов деятельности (с ограничением вложенности 3 уровня): GET /activities/
• Получение конкретного вида деятельности: GET /activities/{activity_id}
• Создание нового вида деятельности: POST /activities/
• Список всех организаций (с фильтрацией по названию, виду деятельности, зданию): GET /organizations/
• Список всех организаций, находящихся в конкретном здании (через параметр building_id либо отдельный эндпоинт /organizations/by-building/)
• Список всех организаций, которые относятся к указанному виду деятельности (через параметр activity_id либо /organizations/by-activity/, включая вложенные)
• Поиск организаций по координатам (радиус) или названию города: GET /organizations/search
• Получение информации об организации: GET /organizations/{organization_id}
• Создание новой организации: POST /organizations/

Быстрый старт

1. Клонируйте репозиторий:

   git clone https://github.com/melixz/organization-directory-api.git

2. Создайте файл .env (при необходимости) или используйте переменные окружения. Пример:

   DATABASE_URL=postgresql+asyncpg://username:password@db:5432/your_db

3. Соберите и запустите приложение с помощью Docker и Makefile:

   make

4. Приложение станет доступно по адресу http://127.0.0.1:8000 или тому, что указано в вашем docker-compose.

Makefile команды

• make — собирает приложение (build + up + migrate + seed)
• make build — собирает Docker-образ
• make up — поднимает контейнеры (приложение, БД и т.д.)
• make down — останавливает и удаляет контейнеры
• make migrate — запускает alembic миграции
• make seed — заполняет базу тестовыми данными
• make logs — показывает логи контейнера приложения
• make reset — полностью пересобирает проект (down -v + build + up + migrate + seed)

Схема моделей

Ниже примеры основных ручек:

Buildings

• GET /buildings/ — список всех зданий
• GET /buildings/{building_id} — детали одного здания
• POST /buildings/ — создание здания (адрес + координаты через Nominatim)

Activities

• GET /activities/ — список всех видов деятельности (3 уровня вложенности)
• GET /activities/{activity_id} — детали конкретного вида деятельности
• POST /activities/ — создание нового вида деятельности с указанием parent_id

Organizations

• GET /organizations/ — список всех организаций с фильтрацией по name, activity_id, building_id
• GET /organizations/search — поиск организаций по городу (city), радиусу (base_lat, base_lon, radius_km) или прямоугольной области (min_lat, max_lat, min_lon, max_lon)
• GET /organizations/{organization_id} — детали одной организации
• POST /organizations/ — создание новой организации (название, телефоны, building_id, activity_ids)

Преимущества

• Асинхронный подход (FastAPI + Async SQLAlchemy) обеспечивает высокую производительность.
• Гибкая фильтрация — можно получить организации по названию, виду деятельности, зданию и координатам.
• Docker — развертывание приложения на любой машине одной командой.
• Alembic — удобное управление миграциями БД.
• Nominatim API — автоматическое определение координат по адресу здания.

Ссылки

• FastAPI Documentation
• SQLAlchemy Documentation
• Alembic Documentation
• Nominatim API
• Docker Documentation