Техническое описание решения

Архитектура

API построен на основе Django REST Framework (DRF) -- библиотеки для создания REST API в Django. Структура API организована по модульному принципу:

• Каждое приложение системы имеет свой набор эндпоинтов
• Сериализаторы преобразуют данные моделей в JSON и обратно
• ViewSets обрабатывают HTTP-запросы и возвращают ответы
• Роутер автоматически регистрирует все эндпоинты

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

API использует два уровня доступа:

1. Доступ к документации

Просмотр документации API (Swagger UI, ReDoc, OpenAPI схема) доступен только:

• Авторизованным пользователям системы
• Пользователям с типом "employee" (сотрудники)

Для доступа к документации используется сессионная аутентификация (пользователь должен быть залогинен в системе).

2. Доступ к данным API

Для получения реальных данных через API требуется токен-аутентификация. Каждый токен:

• Генерируется автоматически при создании
• Хранится в зашифрованном виде в базе данных
• Показывается только один раз при создании
• Может быть привязан к конкретному пользователю
• Может иметь срок действия
• Может быть деактивирован администратором

Токен передается в заголовке запроса:

Authorization: Token <ваш-токен>

Важно: Документация показывает все доступные эндпоинты и примеры, но для получения реальных данных в базе данных необходимо использовать токен с соответствующими разрешениями.

Система прав доступа

Права доступа реализованы на двух уровнях:

1. Уровень токена (Token-level permissions)

Для каждого токена можно настроить:

• Доступные модели -- список разделов системы, к которым токен имеет доступ
• Разрешенные методы -- для каждой модели можно указать, какие операции разрешены:
• GET -- просмотр данных
• POST -- создание новых записей
• PUT -- полное обновление записи
• PATCH -- частичное обновление записи
• DELETE -- удаление записей

Если для модели не указаны конкретные методы, разрешаются все методы.

2. Уровень объекта (Object-level permissions)

Проверка прав на уровне отдельных записей выполняется через систему правил (rules), которая интегрирована с основными правами доступа системы. Это означает, что даже если токен имеет доступ к модели, он может не иметь доступа к конкретным записям в зависимости от настроек прав пользователя, связанного с токеном.

Обработка ошибок

Все ошибки возвращаются в едином формате:

{
  "error": "Тип ошибки",
  "details": {
    "message": "Подробное описание ошибки",
    "field_name": ["Список ошибок для поля"]
  }
}

Основные типы ошибок:

• AuthenticationFailed -- неверный или отсутствующий токен
• PermissionDenied -- недостаточно прав для выполнения операции
• ValidationError -- ошибки валидации данных
• NotFound -- запрашиваемый объект не найден
• Internal server error -- внутренняя ошибка сервера

Ограничение частоты запросов (Throttling)

Для защиты от злоупотреблений установлены ограничения на частоту запросов:

• Аутентифицированные пользователи -- до 1000 запросов в час
• Неаутентифицированные пользователи -- до 100 запросов в час

При превышении лимита возвращается ошибка с кодом 429 (Too Many Requests).

Пагинация

По умолчанию все списки разбиваются на страницы по 20 записей. В ответе приходят:

• count -- общее количество записей
• next -- URL следующей страницы (или null, если страниц больше нет)
• previous -- URL предыдущей страницы (или null, если это первая страница)
• results -- массив записей текущей страницы

Можно изменить размер страницы через параметр page_size (максимум обычно ограничен настройками).

Фильтрация

Фильтрация доступна через параметры URL. Например:

GET /api/v1/tasks/?executor=1&completed=false&duedate__gte=2024-01-01T00:00:00Z

Доступные операторы фильтрации:

• exact -- точное совпадение
• icontains -- содержит (без учета регистра)
• gte -- больше или равно
• lte -- меньше или равно
• range -- диапазон значений
• isnull -- проверка на NULL

Поиск

Поиск выполняется через параметр search. Система ищет по полям, указанным в настройках каждого эндпоинта. Например:

GET /api/v1/users/?search=Иванов

Сортировка

Сортировка выполняется через параметр ordering. Можно сортировать по нескольким полям, используя запятую. Минус перед именем поля означает сортировку по убыванию. Например:

GET /api/v1/tasks/?ordering=-created_at,title

Мягкое удаление (Soft Delete)

Некоторые модели поддерживают мягкое удаление -- запись не удаляется физически, а помечается как удаленная. Для таких моделей:

• По умолчанию удаленные записи не возвращаются
• Для получения удаленных записей используйте параметр include_deleted=true
• Удаленные записи можно восстановить через специальный эндпоинт

Иерархические структуры (MPTT)

Некоторые модели имеют иерархическую структуру (например, категории, организационная структура). Для таких моделей в ответе автоматически добавляются поля:

• parent -- идентификатор родительского элемента
• parent_name -- название родительского элемента
• children -- список идентификаторов дочерних элементов
• level -- уровень вложенности
• tree_id, lft, rght -- технические поля для работы с деревом

Файлы и изображения

При работе с файлами и изображениями:

• В ответе автоматически добавляется поле {field_name}_url с полным URL файла
• При загрузке файлов можно указать ограничения на размер и тип файла
• Файлы загружаются через стандартный механизм multipart/form-data

Кэширование

Для повышения производительности используется кэширование:

• Результаты проверки токенов кэшируются на 1 час
• Результаты проверки прав на объекты кэшируются на 5 минут
• Невалидные токены кэшируются на 5 минут для предотвращения повторных проверок

Документация

Доступна интерактивная документация в нескольких форматах. Важно: Просмотр документации доступен только авторизованным пользователям с типом "employee" (сотрудники).

Главная страница API

По адресу /api/ доступна главная страница API, которая предоставляет удобный доступ ко всем версиям API и их документации.

Доступ:

• Только для авторизованных пользователей с типом employee
• Требуется вход в систему через веб-интерфейс
• Также доступна через пункт меню "API" в разделе настроек (/settings/)

На главной странице отображаются:

• API Эндпоинты — прямой доступ к списку всех доступных эндпоинтов API
• OpenAPI Схема — машинно-читаемая схема API в формате JSON/YAML
• Swagger UI — интерактивный интерфейс для тестирования API
• ReDoc — альтернативный интерфейс документации

Примечание: Документация показывает все эндпоинты, структуру данных и примеры запросов, но для получения реальных данных необходимо использовать токен API с соответствующими разрешениями.

Форматы документации

1. Swagger UI — /api/v1/schema/swagger-ui/ — интерактивный интерфейс для тестирования API
2. Доступ: только для авторизованных сотрудников
3. Позволяет просматривать все эндпоинты и примеры
4. Для выполнения запросов с реальными данными требуется токен
5. ReDoc — /api/v1/schema/redoc/ — альтернативный интерфейс документации
6. Доступ: только для авторизованных сотрудников
7. Удобен для чтения и поиска информации
8. OpenAPI схема — /api/v1/schema/ — машинно-читаемая схема API в формате JSON/YAML
9. Доступ: только для авторизованных сотрудников
10. Можно использовать для генерации клиентских библиотек

Эндпоинты

Все эндпоинты доступны по базовому URL /api/v1/. Основные группы эндпоинтов:

Пользователи

• GET /api/v1/users/ -- список пользователей
• GET /api/v1/users/{id}/ -- информация о пользователе
• GET /api/v1/groups/ -- список групп

Финансы

• GET /api/v1/finance/charges/ -- начисления
• GET /api/v1/finance/salaries/ -- зарплаты
• GET /api/v1/finance/contracts/ -- договоры
• GET /api/v1/finance/invoices/ -- счета
• И другие...

Проекты

• GET /api/v1/projects/ -- список проектов
• GET /api/v1/projects/{id}/ -- информация о проекте
• GET /api/v1/projects/milestones/ -- этапы проектов
• И другие...

Задачи

• GET /api/v1/tasks/ -- список задач
• POST /api/v1/tasks/ -- создание задачи
• GET /api/v1/tasks/{id}/ -- информация о задаче
• PATCH /api/v1/tasks/{id}/ -- обновление задачи
• DELETE /api/v1/tasks/{id}/ -- удаление задачи
• И другие...

Сервис-деск

• GET /api/v1/servicedesk/requests/ -- список заявок
• GET /api/v1/servicedesk/statuses/ -- статусы заявок
• GET /api/v1/servicedesk/types/ -- типы заявок
• И другие...

CRM

• GET /api/v1/crm/products/ -- продукты
• GET /api/v1/crm/deals/ -- сделки
• GET /api/v1/crm/contacts/ -- контакты
• И другие...

Совещания

• GET /api/v1/meetings/ -- список совещаний
• GET /api/v1/meetings/types/ -- типы совещаний
• И другие...

Клиенты

• GET /api/v1/clients/ -- список клиентов
• GET /api/v1/clients/types/ -- типы клиентов
• И другие...

База знаний

• GET /api/v1/kb/pages/ -- страницы базы знаний
• GET /api/v1/kb/categories/ -- категории
• GET /api/v1/kb/courses/ -- курсы
• И другие...

Полный список всех эндпоинтов доступен в интерактивной документации.