Backend архитектура

Backend построен на Django 5.1 с Django REST Framework.

Структура проекта

backend/
├── api/                    # Основной Django проект
│   ├── settings.py         # Настройки
│   ├── urls.py             # URL маршрутизация
│   ├── celery.py           # Celery конфигурация
│   └── tests/              # Тесты
├── app_documents/          # Приложение документов
│   ├── models.py           # Модели
│   ├── views/              # Views (API endpoints)
│   ├── serializers.py      # Serializers
│   ├── services/           # Бизнес-логика
│   └── tasks/              # Celery задачи
├── app_users/              # Пользователи
├── app_ai_agents/          # ИИ агенты
│   ├── models.py           # Настройки агентов
│   ├── views.py            # API классификации
│   ├── service.py          # Сервис агентов
│   └── dify_client.py      # Клиент Dify API
└── app_global_settings/    # Глобальные настройки

Django Apps

app_documents

Основное приложение для работы с документами.

Модели:

• DocumentType - типы документов
• DocumentField - поля для каждого типа
• Request - запрос на обработку
• Task - задача обработки
• Document - загруженный документ
• OcrResult - результат OCR
• OcrResultField - извлечённые поля

Views:

• RequestCreateView - загрузка файлов
• RequestDetailView - получение результатов

app_ai_agents

Интеграция с ИИ провайдерами.

Модели:

• DifyApp - приложение Dify
• n8nApp - приложение n8n
• AiAgentSettings - настройки агента

Сервисы:

• AiAgentService - унифицированный сервис для работы с ИИ
• DifyClient - HTTP клиент для Dify API

app_users

Управление пользователями.

Модели:

• User - расширенная модель пользователя

REST API Endpoints

Documents

Method	Endpoint	Описание
POST	/documents/api/v1/request/	Создать запрос на обработку
GET	/documents/api/v1/request/{id}/	Получить статус и результаты

AI Agents

Method	Endpoint	Описание
POST	/ai_agents/api/v1/classify/	Классифицировать документ
POST	/ai_agents/api/v1/extract/	Извлечь данные

Auth

Method	Endpoint	Описание
POST	/api/token/	Получить JWT токен
POST	/api/token/refresh/	Обновить токен

Celery Tasks

Цепочка обработки

chain(
    extract_ocr_data_task.s(task_id, filename),    # 1. OCR
    classify_document_task.s(),                      # 2. Классификация
    dify_field_extraction.s(),                       # 3. Извлечение полей
    combine_and_save_results_task.s(task_id, request_id)  # 4. Сохранение
)

Задачи

Задача	Описание
extract_ocr_data_task	Отправка в OCR сервис
classify_document_task	Классификация через Dify/n8n
dify_field_extraction	Извлечение полей
combine_and_save_results_task	Сохранение результатов в БД

Сервисы

RequestProcessService

Создаёт запрос и запускает цепочку обработки:

class RequestProcessService:
    def create_processing_request(self, files_list):
        # 1. Создать Request
        # 2. Для каждого файла создать Document и Task
        # 3. Запустить Celery chain
        # 4. Вернуть request_id

AiAgentService

Унифицированный интерфейс для ИИ провайдеров:

class AiAgentService:
    def classify(self, ocr_draft: str) -> dict:
        # Определить провайдера (Dify/n8n)
        # Вызвать соответствующий API

    def extract_structured(self, ocr_draft: str) -> dict:
        # Извлечь структурированные данные

Тестирование

# Все тесты
docker compose exec api uv run -- pytest .

# Конкретный файл
docker compose exec api uv run -- pytest api/tests/test_api.py

# Конкретный тест
docker compose exec api uv run -- pytest . -k "test_name"

Структура тестов

api/tests/
├── conftest.py      # Конфигурация pytest
├── factories.py     # Factory Boy фабрики
├── fixtures.py      # Pytest fixtures
└── test_api.py      # API тесты