Skip to content

Задача 006: Единый контракт конверта (Redis и API)

Приоритет: Средний Статус: Запланировано Категория: Ядро / Архитектура

🎯 Цель

Стандартизировать обмен данными между ботом и внешними системами (Redis Streams, REST API, Webhooks). Каждое сообщение должно рассматриваться как «Конверт» (Envelope), содержащий системные метаданные и бизнес-нагрузку.

🛠 Единая структура

Система примет симметричную структуру для всех каналов связи:

1. Структура (JSON)

{
  "meta": {
    "type": "event.type",
    "user_id": 12345,
    "__next_scene__": "target_feature",
    "trace_id": "uuid-string"
  },
  "payload": {
    "data_field_1": "value",
    "data_field_2": 42
  }
}

2. Маппинг HTTP/API

Для REST-ответов BaseApiClient будет отвечать за сборку этого конверта: - Meta: Извлекается из кастомных HTTP-заголовков (например, X-Bot-*) И/ИЛИ поля meta в теле JSON. - Payload: Основные данные из тела ответа.

3. Маппинг Redis Stream

BotRedisDispatcher будет ожидать такую же структуру JSON в сообщении стрима.

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

  • Полная симметрия: Логика переключения сцен или идентификации пользователей идентична как для фоновых задач, так и для прямых вызовов API.
  • Упрощенные Оркестраторы: Оркестраторы получают предварительно распарсенный Конверт и им не нужно знать источник данных.
  • Масштабируемость: Новые системные поля (например, подсказки для кэширования или теги аналитики) могут быть добавлены в meta без поломки логики фич.

✅ Определение готовности

  • Реализован EnvelopeDTO в codex_bot.base.
  • BaseApiClient поддерживает сборку конверта из заголовков и тела.
  • BotRedisDispatcher поддерживает диспетчеризацию на основе конвертов.