NOCR - Система мониторинга Telegram-каналов

Микросервисная система на базе Telegram Bot для мониторинга и уведомлений о текстовых совпадениях в открытых каналах и чатах.

📋 Обзор проекта

Это родительский проект, содержащий все сервисы как git submodules. Каждый сервис является отдельным репозиторием, что обеспечивает независимую разработку и версионирование.

Архитектура сервисов

Система состоит из 4 основных микросервисов, взаимодействующих через RabbitMQ:

1. telegram-listener

Назначение: Сканирование открытых Telegram-каналов и чатов

• Подписка на каналы через Telegram MTProto API
• Публикация событий о новых и отредактированных сообщениях в message bus
• Хранение сессий пользователей

2. text-matcher

Назначение: Сопоставление сообщений с пользовательскими подписками

• Обработка событий от telegram-listener
• Проверка совпадений по регулярным выражениям и ключевым словам
• Хранение истории совпадений в БД (MariaDB)
• Публикация событий о найденных совпадениях

3. telegram-client

Назначение: Клиентский интерфейс бота для взаимодействия с пользователями

• Прием команд от пользователей через Telegram Bot API
• Управление подписками на каналы
• Отправка уведомлений о найденных совпадениях
• Интеграция с users и text-matcher через REST API

4. users

Назначение: Управление пользователями и их настройками

• CRUD операции для пользователей
• Хранение предпочтений и подписок
• REST API для других сервисов

---

🚀 Быстрый старт

Вариант 1: Docker Compose (рекомендуется)

# 1. Создайте файл с секретами
cp .nocr.env.example .nocr.env

# 2. Заполните ваши Telegram API ключи в .nocr.env
#    - API ID и Hash: https://my.telegram.org/apps
#    - Bot Token: @BotFather в Telegram

# 3. Запустите все сервисы
docker-compose up

Проверка работоспособности:

• Telegram Listener: http://localhost:5040/health
• Text Matcher: http://localhost:5041/health
• Users: http://localhost:5042/health
• Telegram Client: http://localhost:5050/health
• RabbitMQ UI: http://localhost:15672 (admin/admin)

Вариант 2: Локальная разработка (VS Code)

# 1. Запустите инфраструктуру (RabbitMQ + базы данных)
docker-compose up nocr-rabbitmq nocr-text-matcher-db nocr-users-db -d

# 2. Создайте конфигурационные файлы для каждого сервиса
cd telegram-listener/src/Nocr.TelegramListener.Host
cp appsettings.Development.json.example appsettings.Development.json
# Повторите для всех сервисов

# 3. Заполните ваши секреты в appsettings.Development.json

# 4. Запустите сервисы через VS Code (F5)

📖 Подробная документация: См. CONFIGURATION.md

---

🏗️ Архитектура взаимодействия

┌──────────────────┐         ┌───────────────┐         ┌──────────────────┐
│ Telegram Channel │────────▶│   Listener    │────────▶│   Text Matcher   │
│   (MTProto API)  │         │  (Scan msgs)  │         │  (Match rules)   │
└──────────────────┘         └───────┬───────┘         └────────┬─────────┘
                                     │                           │
                                     │                           │
                                     │      RabbitMQ             │
                                     │    Message Bus            │
                                     │                           │
                                     ▼                           ▼
                             ┌───────────────┐         ┌──────────────────┐
                             │ Event Topics  │         │   Telegram Bot   │
                             │  & Queues     │◀────────│     Client       │
                             └───────────────┘         │ (Notifications)  │
                                                        └──────────────────┘
                                                                 │
                                                                 ▼
                                                        ┌──────────────────┐
                                                        │   Users Service  │
                                                        │ (User Management)│
                                                        └──────────────────┘

Паттерн взаимодействия:

• Event-driven: Асинхронная обработка через RabbitMQ
• REST API: Синхронные запросы между telegram-client и другими сервисами
• Clean Architecture: Разделение на слои Host/AppServices/Core/Persistence

📖 Подробная диаграмма: См. architecture.md

---

🔧 Технологический стек

• .NET 8 - Фреймворк для всех сервисов
• ASP.NET Core - Web API
• Entity Framework Core - ORM для MariaDB
• WTelegramClient - MTProto API для telegram-listener
• Telegram.Bot - Bot API для telegram-client
• Rebus - Message bus поверх RabbitMQ
• MariaDB - Базы данных для text-matcher и users
• RabbitMQ - Брокер сообщений
• Docker & Docker Compose - Контейнеризация
• Drone CI - CI/CD на Kubernetes

---

📦 CI/CD Pipeline

Проект использует Drone CI с 5 специализированными пайплайнами:

1. 🧪 Feature Validation

Триггер: Push в ветки feature/*, fix/*, issues/* Длительность: ~3-5 минут

• Сборка всех сервисов
• Запуск тестов с Testcontainers
• Быстрая обратная связь перед PR

2. ✅ Main Validation

Триггер: Push в ветку main Длительность: ~3-5 минут

• Валидация после мерджа в main
• Гарантия стабильности основной ветки

3. 📝 Contracts-Only Publish

Триггер: Tag с сообщением contracts_only:<service> Длительность: ~2 минуты

• Публикация NuGet-пакетов контрактов
• Без сборки Docker-образов

git commit -m "contracts_only:telegram_listener - Add MessageEdited event"
git tag v1.2.4-contracts && git push origin v1.2.4-contracts

4. 🚀 Full Release

Триггер: Tag без специальных маркеров Длительность: ~8-10 минут

1. Публикация всех контрактов (параллельно)
2. Сборка Docker-образов с Kaniko (параллельно)
3. Деплой в Kubernetes (для тегов v*)

git tag v1.3.0 && git push origin v1.3.0

5. ⚡ Deploy-Only

Триггер: Tag с сообщением deploy_only: Длительность: ~1 минута

• Деплой существующих образов без пересборки
• Откат к предыдущей версии

git commit --allow-empty -m "deploy_only: Rollback to v1.2.9"
git tag v1.2.9-deploy && git push origin v1.2.9-deploy

📖 Полная документация CI/CD: См. _deploy/README.md

---

🛠️ Команды разработки

Сборка

# Сборка конкретного сервиса
cd telegram-listener && dotnet build

# Сборка всех сервисов
dotnet build telegram-listener/Nocr.TelegramListener.sln
dotnet build telegram-client/Nocr.TelegramClient.sln
dotnet build text-matcher/Nocr.TextMatcher.sln
dotnet build users/Nocr.Users.sln

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

# Запуск тестов (text-matcher)
cd text-matcher && dotnet test

Миграции БД

# Добавить новую миграцию
cd text-matcher
./src/Nocr.TextMatcher.Migrator/AddMigration.sh MyMigrationName

cd users
./src/Nocr.Users.Migrator/AddMigration.sh MyMigrationName

# Применение миграций автоматически при запуске через docker-compose

Работа с субмодулями

# Инициализация субмодулей после клонирования
git submodule update --init --recursive

# Обновление всех субмодулей до последних коммитов
git submodule update --remote --merge

# Автокоммит изменений в субмодулях (скрипт)
./commit-submodules.sh "Update submodules"

---

📊 Порты сервисов

При запуске через Docker Compose:

Сервис	Порт	Health Check
telegram-listener	5040	http://localhost:5040/health
text-matcher	5041	http://localhost:5041/health
users	5042	http://localhost:5042/health
telegram-client	5050	http://localhost:5050/health
RabbitMQ AMQP	5672	-
RabbitMQ Management	15672	http://localhost:15672
MariaDB (text-matcher)	3316	-
MariaDB (users)	3326	-

---

🔐 Конфигурация

Приоритет источников конфигурации

1. appsettings.json (базовые настройки)
2. appsettings.{Environment}.json (Development/DockerCompose/Production)
3. User Secrets (только для Development)
4. Environment Variables ⬆️ НАИВЫСШИЙ ПРИОРИТЕТ

Важные правила

• ❌ Никогда не коммитьте секреты в git
• ✅ Используйте файлы .example как шаблоны
• ✅ Environment Variables переопределяют все остальное
• ✅ Docker Compose использует .nocr.env (gitignored)
• ✅ Kubernetes использует Secrets

Режим отладки

Для вывода маскированных значений конфигурации:

export NOCR_DEBUG_MODE=true

📖 Полное руководство: См. CONFIGURATION.md

---

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

• CONFIGURATION.md - Подробное руководство по конфигурации
• _deploy/README.md - CI/CD пайплайны и деплой
• architecture.md - Архитектурная диаграмма
• CLAUDE.md - Инструкции для Claude Code AI

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

• telegram-listener/README.md
• telegram-client/README.md
• text-matcher/README.md
• users/README.md

---

🤝 Рабочий процесс разработки

Создание новой функции

# 1. Создайте feature-ветку
git checkout -b feature/add-filter

# 2. Работайте в субмодуле
cd telegram-listener
git checkout -b feature/add-filter
# Внесите изменения...
git commit -m "Add new filter"
git push origin feature/add-filter

# 3. Обновите родительский проект
cd ..
git add telegram-listener
git commit -m "Update telegram-listener: Add new filter"
git push origin feature/add-filter

# 4. Создайте PR и дождитесь прохождения CI

Релиз новой версии

# 1. Убедитесь, что все изменения в main
git checkout main && git pull

# 2. Создайте тег
git tag v1.4.0 -m "Release v1.4.0: New features"
git push origin v1.4.0

# 3. Drone автоматически:
#    - Опубликует NuGet-пакеты
#    - Соберет Docker-образы
#    - Задеплоит в Kubernetes (для v* тегов)

---

🐛 Troubleshooting

Сервис не подключается к RabbitMQ

# 1. Проверьте, что RabbitMQ запущен
docker-compose ps nocr-rabbitmq

# 2. Включите режим отладки
export NOCR_DEBUG_MODE=true

# 3. Проверьте ConnectionString в логах
# Для Docker: должно быть nocr-rabbitmq:5672, НЕ localhost:5672

Ошибка подключения к базе данных

# 1. Проверьте статус БД
docker-compose ps nocr-text-matcher-db

# 2. Подождите прохождения healthcheck (10-30 сек при первом запуске)

# 3. Проверьте порт в connection string:
#    - Docker: nocr-text-matcher-db:3306
#    - Local: localhost:3316

Pipeline падает на тестах

# 1. Проверьте, что Testcontainers может подключиться к Docker
#    В pipeline должна быть переменная DOCKER_HOST

# 2. Запустите тесты локально
cd text-matcher
dotnet test

# 3. Проверьте логи в Drone UI

---

📈 Мониторинг

Проверка здоровья сервисов

# Локально
curl http://localhost:5040/health  # telegram-listener
curl http://localhost:5041/health  # text-matcher
curl http://localhost:5042/health  # users
curl http://localhost:5050/health  # telegram-client

# В Kubernetes (из deploy pod)
cd _deploy/scripts
./health-check.sh

Просмотр логов

# Docker Compose
docker-compose logs -f telegram-listener
docker-compose logs -f text-matcher

# Kubernetes
kubectl logs -f deployment/telegram-listener -n nocr
kubectl logs -f deployment/text-matcher -n nocr

---

📝 История изменений (15-16 октября 2025)

Основные улучшения

• ✨ Новый CI/CD: 5 специализированных пайплайнов Drone
• 🔧 Исправления .drone.yml: Корректная обработка YAML с многострочными командами
• 📦 Contracts-only пайплайн: Быстрая публикация контрактов без пересборки образов
• 🚀 Deploy-only пайплайн: Быстрый откат и деплой существующих образов
• 🔄 MessageEdited события: Отдельная обработка отредактированных сообщений
• 📝 Автокоммит субмодулей: Скрипт для упрощения работы с субмодулями
• ⚡ Оптимизации: Shared NuGet cache, параллельная сборка, Kaniko caching

Исправленные проблемы

• 🐛 Исправлен парсинг YAML в .drone.yml (строка 126)
• 🐛 Корректная обработка ${DRONE_COMMIT_SHA:0:7} в командах
• 🐛 Правильные отступы в многострочных bash-скриптах
• 🐛 Зависимости между этапами pipeline

---

📄 Лицензия

[Укажите лицензию вашего проекта]

👥 Авторы

[Укажите авторов проекта]

---

Дополнительные ссылки:

• Drone CI
• Gitea Repository