Архитектура¶

Общая схема¶

┌─────────────────────┐
│   React Frontend    │
│  (Vite + Ant Design)│
└─────────┬───────────┘
          │ HTTP / WebSocket
          ▼
┌─────────────────────┐
│   Traefik (Proxy)   │
│  TLS, маршрутизация │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────────────────────────────────┐
│              FastAPI Backend                    │
│                                                 │
│  ┌──────────┐  ┌────────────┐  ┌──────────────┐ │
│  │ API Layer│  │  Services  │  │  ML Layer    │ │
│  │ (Routers)│→ │  (Facade)  │→ │ (Processors) │ │
│  └──────────┘  └────────────┘  └──────┬───────┘ │
│                                       │         │
│  ┌──────────┐  ┌────────────┐         │         │
│  │ Domain   │  │  Schemas   │         │         │
│  │ (Builder)│  │ (Pydantic) │         │         │
│  └──────────┘  └────────────┘         │         │
└───────────────────────────────────────┼─────────┘
                                        │
                    ┌───────────────────┼──────────────┐
                    ▼                   ▼              ▼
              ┌──────────┐      ┌──────────┐    ┌──────────┐
              │ OpenAI   │      │  Qdrant  │    │  Redis   │
              │ API      │      │ (Vectors)│    │ (Cache)  │
              └──────────┘      └──────────┘    └──────────┘

Описание слоёв¶

API Layer (`backend/src/api/routers_v1/`)¶

Точка входа для всех HTTP- и WebSocket-запросов. Содержит два роутера:

**chat_router.py** — основные эндпоинты: чат, управление задачами, редактирование, подсказки.
**auth_router.py** — генерация JWT-токенов.

Middleware-компоненты:

AuthMiddleware — проверка JWT/API-Key/IP-whitelist;
RequestBodyLogger — логирование тел запросов (с фильтрацией больших payload);
RequestTimingMiddleware — замер латентности эндпоинтов;
CORSMiddleware — управление CORS-политикой.

Services Layer (`backend/src/services/`)¶

Фасад между API и ML-слоем:

Сервис	Назначение
`openai_client.py`	Основной фасад: оркестрация ML-операций (генерация, редактирование, классификация)
`jobs_service.py`	Управление жизненным циклом фоновых задач (запуск, прогресс, результат)
`doc_chat_service.py`	Чат с AI-агентом в контексте текущего документа (TZAgent)
`progress.py`	Отслеживание прогресса задач (Redis-backed или in-memory)
`spec_update.py`	Инкрементальное обновление документа при изменении параметров
`suggest_cache.py`	Кэширование подсказок ОКПД2 с rate-limiting (60 запросов/мин)

ML Layer (`backend/src/ml/`)¶

Подробное описание — в разделе ML-слой.

Domain Layer (`backend/src/domain/`)¶

Бизнес-логика формирования документа:

Модуль	Назначение
`spec_builder.py`	Сборка спецификации из компонентов (главы, характеристики, ОКПД2)
`spec_service.py`	Валидация и финальная сборка документа
`chapters_utils.py`	Извлечение, сравнение, нормализация глав
`spec_merge_utils.py`	Слияние обновлений в существующую спецификацию

Schemas Layer (`backend/src/schemas/`)¶

Pydantic-модели данных, используемые на всех уровнях приложения.

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

Главы документа¶

class BaseChapter:
    kind: ChapterKind        # tech | text
    chapter_name: str

class TechChapter(BaseChapter):
    """Техническая глава с характеристиками продукции."""
    item_name: str            # наименование товара/услуги
    okpd2: str                # код ОКПД2
    qty: int                  # количество
    date: str                 # срок поставки
    address: str              # адрес поставки
    main_chars: list[Characteristic]   # основные характеристики
    dop_chars: list[Characteristic]    # дополнительные характеристики
    services: list[...]       # сопутствующие услуги

class SimpleChapter(BaseChapter):
    """Текстовая глава (описание, требования и т.д.)."""
    body: str
    specification: Optional[Specification]

Характеристики¶

class Characteristic:
    name: str                 # наименование характеристики
    value: str | list[str]    # значение (текст или варианты для таблицы)

Спецификация¶

class SpecificationItem:
    item_name: str
    type: str
    quantity: int
    price: float
    currency: str
    address: str
    delivery_deadline: str

class Specification:
    items: list[SpecificationItem]
    total_price: float

Редактирование¶

class EditCellAction:
    action_type: EditActionType   # add | remove | update | rename
    content: str
    description: str

class TableResponse:
    result: str | list[Characteristic]
    type: str                     # explanation | modification

Обновления¶

class UpdateByChangesRequest:
    changes: dict              # deep diff изменений
    content: dict              # текущее содержимое
    product_type: str
    history: list[dict]        # история изменений

class UpdateByChangesResponse:
    updated_chapters: list[BaseChapter]
    updated_characteristics: list[Characteristic]
    error: Optional[str]

Хранилища данных¶

Хранилище	Данные	TTL
Redis	Прогресс задач (JSON)	2 часа
	Результаты задач	2 часа
	Кэш подсказок ОКПД2	15 минут
	Дедупликация активных задач	30 секунд
Qdrant	Векторы ОКПД2 (text-embedding-3-large)	—
	Коллекции: `okpd2` (dev), `okpd2_prod` (prod)	—
In-Memory	Fallback при отсутствии Redis	—

Note

Система не использует реляционную СУБД. Состояние хранится в Redis (эфемерные данные) и Qdrant (векторные индексы).