.. orghandbookapi documentation master file, created by
   sphinx-quickstart on Tue Oct 21 23:07:47 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

orghandbookapi documentation
============================

.. toctree::
   :maxdepth: 4
   :caption: Содержание:

   orghandbookapi

org-handbook-api
================

REST API справочника организаций

**Ссылки:**
- `Документация API <https://alexeev-prog.github.io/org-handbook-api/>`_
- `Исходный код <https://github.com/alexeev-prog/org-handbook-api>`_
- `Лицензия <https://github.com/alexeev-prog/org-handbook-api/blob/main/LICENSE>`_

.. image:: https://raw.githubusercontent.com/alexeev-prog/org-handbook-api/refs/heads/main/docs/pallet-0.png

Org-Handbook-API - это асинхронный RESTful API для управления справочником организаций с расширенными возможностями поиска и геолокации.

Основные возможности:

- Полный CRUD для организаций, зданий и видов деятельности
- Древовидная структура видов деятельности с ограничением вложенности
- Геопространственный поиск организаций
- Аутентификация через статичный API-ключ
- Автоматическая документация Swagger/Redoc

Технологический стек:

+------------------+-----------------------------------+
| Компонент       | Технологии                       |
+==================+===================================+
| Фреймворк       | FastAPI, Pydantic, SQLAlchemy 2.0|
+------------------+-----------------------------------+
| База данных     | PostgreSQL + SQLAlchemy Async    |
+------------------+-----------------------------------+
| Миграции        | Alembic                          |
+------------------+-----------------------------------+
| Контейнеризация | Docker, Docker Compose           |
+------------------+-----------------------------------+
| CI/CD           | GitHub Actions                   |
+------------------+-----------------------------------+
| Документация    | Sphinx, Swagger UI               |
+------------------+-----------------------------------+
| Code Quality    | Ruff, Mypy, Pytest               |
+------------------+-----------------------------------+

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

Предварительные требования:

- Docker & Docker Compose
- Git

Установка и запуск:

1. Клонирование репозитория

   .. code-block:: bash

      git clone https://github.com/alexeev-prog/org-handbook-api.git
      cd org-handbook-api

2. Запуск приложения

   .. code-block:: bash

      docker-compose up --build -d

3. Проверка работоспособности

   .. code-block:: bash

      curl -H "X-API-Key: secret-static-api-key" http://localhost:8000/health

4. Документация API доступна по адресу: http://localhost:8000/docs

Модели данных
-------------

Организация (Organization)

.. code-block:: json

   {
       "id": 1,
       "legal_name": "ООО Рога и Копыта",
       "building_id": 1,
       "building": {
           "id": 1,
           "address": "г. Москва, ул. Ленина 1",
           "latitude": 55.7558,
           "longitude": 37.6173
       },
       "phonenumbers": [
           {"id": 1, "phone_number": "2-222-222"},
           {"id": 2, "phone_number": "3-333-333"}
       ],
       "activities": [
           {"id": 1, "name": "Молочная продукция"},
           {"id": 2, "name": "Мясная продукция"}
       ]
   }

Здание (Building)

.. code-block:: json

   {
       "id": 1,
       "address": "г. Москва, ул. Ленина 1, офис 3",
       "latitude": 55.7558,
       "longitude": 37.6173
   }

Деятельность (Activity) - древовидная структура

.. code-block:: json

   {
       "id": 1,
       "name": "Еда",
       "parent_id": null,
       "level": 0,
       "children": [
           {
               "id": 2,
               "name": "Мясная продукция",
               "parent_id": 1,
               "level": 1
           }
       ]
   }

API маршруты
------------

Основные CRUD операции

Организации
~~~~~~~~~~~

+----------+------------------------------------+----------------------------+
| Метод    | Endpoint                           | Описание                   |
+==========+====================================+============================+
| GET      | /api/v1/organizations/             | Список организаций         |
+----------+------------------------------------+----------------------------+
| GET      | /api/v1/organizations/{id}         | Организация по ID          |
+----------+------------------------------------+----------------------------+
| POST     | /api/v1/organizations/             | Создание организации       |
+----------+------------------------------------+----------------------------+
| PUT      | /api/v1/organizations/{id}         | Обновление организации     |
+----------+------------------------------------+----------------------------+
| DELETE   | /api/v1/organizations/{id}         | Удаление организации       |
+----------+------------------------------------+----------------------------+

Здания
~~~~~~

+----------+--------------------------------+------------------------+
| Метод    | Endpoint                       | Описание               |
+==========+================================+========================+
| GET      | /api/v1/buildings/             | Список зданий          |
+----------+--------------------------------+------------------------+
| GET      | /api/v1/buildings/{id}         | Здание по ID           |
+----------+--------------------------------+------------------------+
| POST     | /api/v1/buildings/             | Создание здания        |
+----------+--------------------------------+------------------------+
| PUT      | /api/v1/buildings/{id}         | Обновление здания      |
+----------+--------------------------------+------------------------+
| DELETE   | /api/v1/buildings/{id}         | Удаление здания        |
+----------+--------------------------------+------------------------+

Виды деятельности
~~~~~~~~~~~~~~~~~

+----------+------------------------------------+--------------------------------+
| Метод    | Endpoint                           | Описание                       |
+==========+====================================+================================+
| GET      | /api/v1/activity/                  | Список видов деятельности      |
+----------+------------------------------------+--------------------------------+
| GET      | /api/v1/activity/{id}              | Вид деятельности по ID         |
+----------+------------------------------------+--------------------------------+
| POST     | /api/v1/activity/                  | Создание вида деятельности     |
+----------+------------------------------------+--------------------------------+
| PUT      | /api/v1/activity/{id}              | Обновление вида деятельности   |
+----------+------------------------------------+--------------------------------+
| DELETE   | /api/v1/activity/{id}              | Удаление вида деятельности     |
+----------+------------------------------------+--------------------------------+
| GET      | /api/v1/activity/tree/{parent_id}  | Дерево видов деятельности      |
+----------+------------------------------------+--------------------------------+

Расширенный поиск организаций
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+----------+--------------------------------------------------+-----------------------------------------+
| Метод    | Endpoint                                         | Описание                                |
+==========+==================================================+=========================================+
| GET      | /api/v1/organizations/building/{building_id}    | Организации в указанном здании          |
+----------+--------------------------------------------------+-----------------------------------------+
| GET      | /api/v1/organizations/activity/{activity_id}     | Организации по виду деятельности       |
+----------+--------------------------------------------------+-----------------------------------------+
| GET      | /api/v1/organizations/search/name               | Поиск организаций по названию           |
+----------+--------------------------------------------------+-----------------------------------------+
| GET      | /api/v1/organizations/search/radius             | Геопоиск организаций в радиусе          |
+----------+--------------------------------------------------+-----------------------------------------+
| GET      | /api/v1/organizations/search/area               | Поиск в прямоугольной области           |
+----------+--------------------------------------------------+-----------------------------------------+

Аутентификация
~~~~~~~~~~~~~~

Все запросы требуют заголовок API-ключа:

.. code-block:: http

   X-API-Key: secret-static-api-key

Пример запроса:

.. code-block:: bash

   curl -H "X-API-Key: secret-static-api-key" "http://localhost:8000/api/v1/organizations/search/name?name=Рога"

Разработка
----------

Локальная установка для разработки
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Установка зависимостей

   .. code-block:: bash
 
      pip install uv
      uv sync

2. Настройка окружения

   Создайте или отредактируйте конфигурационный файл ``orghandbookapi.toml``

3. Запуск миграций базы данных

   .. code-block:: bash

      alembic upgrade head

4. Запуск сервера для разработки

   .. code-block:: bash

      uvicorn orghandbookapi.app:app --reload --host 0.0.0.0 --port 8000

Тестирование и качество кода
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Запуск тестов:

.. code-block:: bash

   pytest tests/ -v

Линтинг и форматирование:

.. code-block:: bash

   ruff check .
   ruff format .

Проверка типов:

.. code-block:: bash

   mypy orghandbookapi

Лицензия и поддержка
--------------------

Данный проект лицензирован под **GNU GPL 3**. Для коммерческого использования или вопросов по сотрудничеству напишите на `alexeev.dev@mail.ru <mailto:alexeev.dev@mail.ru>`_.

- `Документация <https://alexeev-prog.github.io/org-handbook-api>`_
- `Сообщить об ошибке <https://github.com/alexeev-prog/org-handbook-api/issues>`_
- `Предложить улучшение <https://github.com/alexeev-prog/org-handbook-api/pulls>`_

---
REST API справочника организаций

Copyright © 2025 Alexeev Bronislav.