Skip to content

README.ru.md

Latest commit

 

History

History
215 lines (151 loc) · 14.1 KB

README.ru.md

File metadata and controls

215 lines (151 loc) · 14.1 KB

Team Communication Analytics Bot (RU)

Backend‑бот для аналитики командных чатов Telegram. Он:

  • принимает обновления из Telegram по webhook,
  • сохраняет сообщения, правки, реплаи и упоминания в PostgreSQL,
  • строит нити обсуждений и детерминированные процессные сигналы (open loops, нерешённые обсуждения, нет владельца, нет дедлайна, медленные ответы на упоминания),
  • по расписанию собирает дневные/недельные отчёты и прогоняет их через LLM‑пайплайн (аналитик → верификатор → финализатор),
  • отправляет отчёты только владельцу в личные сообщения и ведёт аудит‑логи.

Все функциональные и архитектурные детали описаны в specs/001-team-communication-analytics/.

1. Основной функционал

  • Ингест Telegram по webhook
    FastAPI‑приложение принимает POST‑запросы от Telegram на /webhook/telegram, нормализует JSON и сохраняет события (сообщения, правки, упоминания) в PostgreSQL.

  • Детерминированная аналитика
    На основе сохранённых данных считаются:

    • open loops – вопросы/задачи без ответа дольше порога;
    • нерешённые обсуждения – длинные нити без явного решения;
    • нет владельца – task‑подобные нити, где не выделен ответственный человек;
    • нет дедлайна – задачи с владельцем, но без ожидаемой даты;
    • медленные ответы на упоминания – когда упомянутого человека ждут дольше порога;
    • базовая тематическая разметка нитей по ключевым словам (release, incident и т.п.).

  • Факт‑ориентированные отчёты с LLM

    • Сначала строится список фактов и сигналов (process_signals) за период.
    • LLM‑аналитик собирает черновой структурированный отчёт (JSON).
    • LLM‑верификатор сверяет каждое утверждение с фактами и может отклонить черновик.
    • LLM‑финализатор формирует финальный текст только из подтверждённых утверждений.
    • Если что‑то идёт не так (нет фактов, неподдержанные утверждения, недоступен LLM) – отчёт не отправляется, статус отчёта и llm_runs отражают причину.

  • Приватная рассылка и аудит

    • Отчёты отправляются только whitelisted Telegram user ID владельца в личные сообщения.
    • В группах/каналах отчёты никогда не публикуются.
    • Все ключевые действия (ингест, аналитика, отчёты, LLM‑ошибки, retention) логируются в audit_logs.

  • Расписание и удержание данных

    • Celery beat планирует ежедневные/еженедельные отчёты и задачи по очистке старых данных.
    • Сервис ретенции удаляет/анонимизирует старые raw‑сообщения и правки по настраиваемым порогам, сохраняя агрегаты (сигналы, отчёты).
    • Есть health‑эндпоинты и структурированные логи для мониторинга и безопасных рестартов.

Система следует «конституции» (.specify/memory/constitution.md), которая жёстко требует детерминизма, идемпотентности и проверяемости фактов. LLM никогда не является источником фактов.

2. Архитектура (вкратце)

Стек

  • Python 3.10+, FastAPI (API и webhook), aiogram (Telegram‑бот), SQLAlchemy + Alembic (PostgreSQL), Celery + Redis (очереди и расписание), Pydantic Settings, HTTPX (LLM).

Сервисы в Docker Compose

  • api – FastAPI + Uvicorn, эндпоинты /webhook/telegram, /health/live, /health/ready, опциональные админ‑эндпоинты.
  • worker – Celery worker, выполняет задачи аналитики, отчётов, ретенции.
  • beat – Celery beat, планирует задачи.
  • db – PostgreSQL (единственный источник истины).
  • redis – брокер задач и временное хранилище (locks/idempotency), не используется как источник истины.

Структура кода (секции)

  • src/app/ – конфиг, DI‑контейнер, FastAPI‑приложение, логирование, health.
  • src/api/ – HTTP‑роуты (webhook, admin), зависимости.
  • src/telegram_bot/ – aiogram‑бот, роутинг обновлений, DTO для Telegram JSON.
  • src/db/ – модели БД, enums, репозитории, Alembic‑миграции.
  • src/analytics/ – логика построения нитей и модулей аналитики (правила).
  • src/services/ – сервисы домена: ingestion, threading, analytics, reporting, retention.
  • src/llm/ – клиент LLM, pydantic‑схемы, стадии analyst/verifier/finalizer.
  • src/reporting/ – сборка отчётов, доставка через Telegram, аудит.
  • src/workers/ – Celery app, задачи по аналитике, отчётам, обслуживанию.
  • src/security/ – whitelist владельцев, помощники по приватности и редактированию логов.
  • tests/ – unit, integration, contract‑тесты.

3. Быстрый запуск (локально)

Подробности см. в specs/001-team-communication-analytics/quickstart.md. Здесь – краткая версия.

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

  • Установлены Docker и Docker Compose.
  • Есть Telegram‑бот (BotFather) и его токен.
  • Есть ключ OpenAI‑совместимого LLM (в dev можно заменить моком через monkeypatch).

3.2 Настройка .env

В корне репозитория создайте .env и укажите как минимум:

  • BOT_TOKEN – токен Telegram‑бота.
  • POSTGRES_DSN – строка подключения к PostgreSQL (должна совпадать с тем, что использует контейнер).
  • REDIS_URL – URL Redis.
  • LLM_API_KEY – ключ к LLM.
  • OWNER_TELEGRAM_USER_ID – ваш Telegram user id (кому отправлять отчёты).

Опционально:

  • OPEN_LOOP_THRESHOLD_HOURS – часы до «open loop» (по умолчанию 24).
  • SLOW_RESPONSE_THRESHOLD_HOURS – часы до «медленного ответа на упоминание» (по умолчанию 4).
  • RETENTION_DAYS – срок хранения raw‑сообщений (по умолчанию 180).

3.3 Запуск Docker Compose

Из корня репозитория:

docker compose up --build

Запустятся сервисы api, worker, beat, db, redis.
Если миграции не применяются автоматически – войдите в контейнер api и выполните:

alembic upgrade head

3.4 Настройка webhook Telegram

  1. Пробросьте api наружу (ngrok http 8000 или свой домен).
  2. Вызовите setWebhook у Bot API, передав:
    • URL: https://<публичный-хост>/webhook/telegram
    • secret token, если вы задали TELEGRAM_WEBHOOK_SECRET.

3.5 Тестовый чат и сценарии

  1. Создайте test‑группу/супергруппу в Telegram.
  2. Добавьте туда бота, дайте права читать сообщения.
  3. Отправьте разные сообщения:
    • обычные, ответы, длинную ветку обсуждения;
    • task‑подобные сообщения с/без владельца и дедлайна;
    • сообщения с @mention и большим лагом до ответа;
    • продублируйте какое‑то обновление (для проверки идемпотентности).

Проверьте по логам api/worker, что ошибок нет, и данные попадают в БД.

3.6 Получение отчётов

  • Ожидайте срабатывания Celery beat (дневной/недельный отчёт), либо в dev вручную вызовите build_report_task и последующие LLM‑задачи.
  • Убедитесь, что:
    • отчёт приходит только вам в личный чат;
    • в отчёте отражены ваши тестовые сценарии (open loops, нерешённые нити, нет владельца/дедлайна, медленные ответы);
    • в саму группу отчёт не отправляется.

3.7 Проверка идемпотентности и ретенции

  • повторно отправьте одно и то же Telegram‑обновление – не должно появиться дубликатов сообщений/сигналов/отчётов;
  • уменьшите временно пороги ретенции, запустите задачу ретенции и проверьте, что старые raw‑данные очистились, а агрегаты остались консистентными.

4. Конфигурация (основные параметры)

Конфигурация описана в src/app/config.py (Pydantic Settings). Кратко:

  • Подключения:
    • DATABASE_URL / POSTGRES_DSN – PostgreSQL;
    • REDIS_URL – Redis;
    • TELEGRAM_BOT_TOKEN / BOT_TOKEN – токен бота;
    • TELEGRAM_WEBHOOK_SECRET – опциональный секрет webhook’а;
    • LLM_API_KEY – ключ к LLM.
  • Владелец:
    • OWNER_TELEGRAM_USER_IDS – список Telegram user id владельцев, которые могут получать отчёты.
  • Пороги по умолчанию:
    • OPEN_LOOP_THRESHOLD_HOURS – открытые петли;
    • SLOW_RESPONSE_THRESHOLD_HOURS – медленные ответы на упоминания;
    • RETENTION_DAYS – хранение raw‑сообщений.
  • HTTP‑клиент:
    • таймауты и лимиты соединений для LLM/Telegram HTTP‑запросов.

Пер‑владельческие настройки (пороги, ретенция, часовой пояс и т.д.) задаются через строки в таблице owner_settings.

5. Разработка и тестирование

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

pytest
  • tests/unit/ – юнит‑тесты правил аналитики, построения нитей, LLM‑верификатора, приоритизации сигналов и т.п.
  • tests/integration/ – интеграционные тесты webhook‑ингеста, аналитического пайплайна, отчётов, LLM‑пайплайна, расписаний, ретенции, идемпотентности, health‑эндпоинтов.
  • tests/contract/ – контрактные тесты Telegram JSON и LLM JSON‑схем.

5.2 Разработка

  • Все внешние вызовы имеют таймауты и retries с backoff.
  • Задачи Celery спроектированы как идемпотентные (safe retries).
  • Для разработки LLM можно подменить LLMClient моком (см. tests/integration/test_llm_pipeline.py).

6. Безопасность и приватность

  • Секреты (токены, пароли БД и т.п.) хранятся только в окружении/секрет‑менеджере и не закоммичены.
  • Отчёты доставляются только в личные чаты владельцев; в группах ничего не публикуется.
  • Логи структурированы и стараются не содержать полный текст сообщений, где это не обязательно; имеются помощники для редактирования/маскировки (см. src/security/privacy.py).
  • Retention реализован в коде и может настраиваться покомпонентно (raw‑сообщения vs агрегаты).

Подробнее о нефункциональных требованиях, гарантиях и принципах см.:

  • specs/001-team-communication-analytics/spec.md
  • .specify/memory/constitution.md

7. Англоязычная документация

Полная англоязычная версия README и инструкций расположена в файле README.md в корне репозитория.