From 0df7d1d731ae116a6ed5872cb3ef846784f944fe Mon Sep 17 00:00:00 2001 From: Delphington <89201997+Delphington@users.noreply.github.com> Date: Wed, 14 May 2025 13:32:24 +0300 Subject: [PATCH] feat: update --- README.md | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 177 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 83780d7..e52dc3c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,4 @@ -![Build](https://github.com/central-university-dev/backend-academy-2025-spring-template/actions/workflows/build.yaml/badge.svg) - -# Link Tracker +# 📌 Link Tracker ---- @@ -8,9 +6,7 @@ ---- - - -Проект сделан в рамках курса Академия Бэкенда. +## 📝 Описание проекта Приложение для отслеживания обновлений контента по ссылкам. При появлении новых событий отправляется уведомление в Telegram. @@ -21,6 +17,180 @@ * Bot * Scrapper -Для работы требуется БД `PostgreSQL`. Присутствует опциональная зависимость на `Kafka`. +Для работы требуется БД `PostgreSQL`, `Redis`, `Kafka`. Для дополнительной справки: [HELP.md](./HELP.md) + +--- + +## 🤖 Бот + +### 📌 Функционал + +Бот поддерживает следующие команды: + +- [**`/help`**]() — список всех доступных команд. +- [**`/start`**]() — регистрация пользователя. +- [**`/stop`**]() — удаление всех данных о чате (ID чата, отслеживаемые ссылки и т. д.). +- [**`/track`**]() — добавление ссылки для отслеживания +- [**`/untrack`**]() — удаление ссылки из списка отслеживаемых. +- [**`/list`**]() — получение списка всех отслеживаемых ссылок. +- [**`/tag`**]() — для просмотра всех тегов (/tag) и ссылок под конкретным тегом (/tag < tag >) + +### 🔄 Взаимодействие со Scrapper + +Бот общается со Scrapper API через: +- [**`ChatClient`**]() — регистрация и удаление чатов. +- [**`LinkClient`**]() — управление ссылками (добавление, удаление, получение списка). +- [**`TagClient`**]() — для получения списка тегов и ссылок по тегу. + +Scrapper API работает по OpenAPI-контракту. В случае ошибок ошибки логируются, корректную обработку ошибок и пересылку сообщений в чат выполняет [`ErrorHandler`](). + +### 📩 Получение обновлений + +- Бот получает обновления о ссылках через [`UpdateController`]() по HTTP либо через [`KafkaUpdateListener`]() по Kafka. +- Scrapper отправляет данные по OpenAPI-контракту. +- Обновления рассылаются чатам через [`UpdateService`](). + +### 📜 Дополнительно + +- Бот поддерживает встроенное [**меню команд**]() в Telegram. + +### 🧠 Кеширование + +Бот кеширует ответы для следующих команд: +- /tag +- /tag +- /list + +🔄 Кеш автоматически сбрасывается в следующих случаях: +- При добавлении или удалении ссылки (/track, /untrack) +- При удалении чата (/stop) + +При вызове команд бот сначала проверяет наличие ответа в кеше. Если данные найдены — используется кеш. В противном случае происходит обращение к Scrapper API, и результат сохраняется в кеш. + +--- + +## 🗂️ Scrapper + +### 📌 Функционал + +Scrapper обрабатывает запросы от бота: +- **Работа с чатами** через [`ChatController`](). +- **Работа с ссылками** через [`LinkController`](). +- **Работа с тегами** через [`TagController`](). + +Все контроллеры работают по OpenAPI-контракту. + +### 🔄 Получение обновлений + +- [**`UpdateScheduler`**](). +- **📡 Источники данных:** + - GitHub — через [`GitHubClient`]() + - Stack Overflow — через [`StackOverflowClient`]() +- **⚙️ Обработка полученных данных** + 1. Запрос обновлений + - Для каждого URL запрашивается обновление через API + 2. Фильтрация обновлений + - Определяются подписанные пользователи (чаты), которые отслеживают данный URL. + - Для каждого пользователя применяется его список фильтров: + 1. Ключевые фильтры — фильтрация по ключевым словам (issue, commit и т.д). + 2. Анти-фильтры по пользователям — если указано user=username, то обновления от этого пользователя игнорируются. + 3. Парсинг ответа + - Полученный JSON-ответ анализируется, извлекаются значения, соответствующие фильтрам. + 4. Проверка актуальности + - Обновление считается релевантным, если оно произошло после последнего запуска шедулера. + 5. Формирование уведомлений + - Отобранные обновления, соответствующие фильтрам, отправляются пользователям либо через HTTP, либо через Kafka. +- **⚙️ Обработка батчей и многопоточность** + - Ссылки на обновления запрашиваются партиями (batch) заданного размера. Каждый батч делится между потоками. Количество потоков настраивается через конфигурацию. + +## 📦 Хранение данных + +Для хранения данных используются **четыре основные таблицы** и **три вспомогательные таблицы** для связи. + +### 📌 Основные таблицы + +- `chats` — таблица чатов. +- `links` — таблица ссылок. +- `tags` — таблица тегов. +- `filters` — таблица фильтров. + +### 🔗 Связующие таблицы + +Связи между чатами, ссылками, тегами и фильтрами реализованы через **промежуточные таблицы**: + +- `chat_links` — связь между чатами и ссылками. +- `chat_link_tags` — связь между ссылками и тегами в контексте чата. +- `chat_link_filters` — связь между ссылками и фильтрами в контексте чата. + +💡 **Один чат может отслеживать несколько ссылок, а одна ссылка может быть отслеживаемой несколькими чатами.** +📌 **Каждая ссылка может иметь несколько тегов и фильтров в рамках одного чата.** + +### 🛠 Способы работы с базой данных: + +- **SQL** (`JdbcTemplate`, `SqlRepository`). +- **ORM** (`Hibernate`, `OrmRepository`). + Оба репозитория (`SqlRepository` и `OrmRepository`) наследуются от `DbRepository` и работают одинаково. + Выбор зависит от **настроек** (`database.access-type`). + +---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + +## 🚀 Запуск проекта + +### 🔄 Клонирование репозитория + +```bash + +``` + +### 🏗️ Сборка + +```bash + +``` + +### ▶️ Запуск + +#### 1️⃣ Запуск базы + +```bash + +``` + +#### 2️⃣ Запуск миграции + +```bash + +``` + +#### 3️⃣ Запуск redis + +```bash + +``` + +#### 4️⃣ Запуск zookeeper + +```bash + +``` + +#### 5️⃣ Запуск kafka + +```bash + +``` + +#### 6️⃣ Запуск скраппер + +```bash + +``` + +#### 7️⃣ Запуск бота + +```bash + +``` +