Добавлены новые методы для получения статистики постов пользователей, информации о последних постах и количестве банов. Обновлены запросы в репозиториях для сортировки пользователей по дате бана. Исправлены вызовы функций форматирования сообщений для администраторов. Обновлены тесты для проверки новых функциональностей.

2026-02-28 21:30:08 +03:00
parent e2a6944ed8
commit 694cf1c106
18 changed files with 1296 additions and 144 deletions
--- a/.cursor/implementation-plan-features.md
+++ b/.cursor/implementation-plan-features.md
@@ -0,0 +1,428 @@
+# План реализации фич Telegram Helper Bot
+
+> Документ создан: 28 февраля 2025  
+> Ветка: `dev-*`  
+> Статус: План утверждён
+
+---
+
+## Обзор фич
+
+1. **Пагинация заблокированных пользователей** — сортировка по дате бана, единая логика текста и кнопок
+2. **Обогащение сообщений пользователей админам** — данные о пользователе при обращении в поддержку
+3. **Причина бана «Последний пост»** — замена «Спам» на «Последний пост» при быстром бане из поста
+4. **Похожие посты за 24ч** — проверка на дубликаты через RAG (threshold >0.9)
+5. **Авто-публикация/отклонение по RAG** — задел на будущее (>0.8 publish, <0.4 decline)
+6. **ML Scoring Статистика** — восстановить полный вывод (модель, примеры, device) вместо fallback (API URL, статус)
+
+---
+
+## Решения по уточняющим вопросам
+
+| Вопрос | Решение |
+|--------|---------|
+| Пагинация | Единый источник данных, единый `items_per_page` |
+| message_id при forward | Осознанный workaround (n+1). При переходе на send — использовать `returned_message.message_id` |
+| RAG similar | Новый endpoint в RAG. Нужна **отдельная коллекция** для submitted-постов (не позитив/негатив) |
+| Скор для авто-решений | Только `rag_score` |
+| Ветки | `dev-*` |
+
+---
+
+## Проверка: message_id при forward
+
+**Telegram Bot API:** `forwardMessage` возвращает объект `Message` — это **новое** сообщение в целевом чате со своим `message_id`. Telegram присваивает `message_id` в целевом чате — он не обязан быть `n+1` от исходного.
+
+Если всё работает — возможно, бот единственный отправитель в `group_for_message`, и id часто идут подряд. Рекомендация: при переходе на `send_message` обязательно сохранять `message_id` из возвращаемого объекта.
+
+---
+
+## RAG: коллекция для похожих постов
+
+- **Позитив/негатив** — примеры для скоринга модерации
+- **Похожие посты** — сравнение с другими submitted-постами за 24ч
+
+Endpoint `/similar` должен искать по **отдельной коллекции submitted-постов** (с `created_at`), а не по позитиву/негативу. Нужно:
+- Новая коллекция в RAG (например, `posts_submitted`) с полями: `text`, `vector`, `created_at`, `post_id`
+- Endpoint `POST /similar`: `{"text": "...", "threshold": 0.9, "hours": 24}` → список похожих постов
+- При каждом suggest — добавлять пост в эту коллекцию (или вызывать endpoint RAG для индексации)
+
+---
+
+## Пошаговый план реализации
+
+### Этап 0: Подготовка
+
+| Шаг | Действие |
+|-----|----------|
+| 0.1 | Создать ветку `dev-N` (N — следующий номер) от `main` |
+| 0.2 | Убедиться, что локально проходит `make code-quality` (или `isort`, `black`, `flake8`, `pytest`) |
+
+---
+
+### Этап 1: Пагинация заблокированных пользователей
+
+| Шаг | Действие |
+|-----|----------|
+| 1.1 | В `BlacklistRepository`: добавить `ORDER BY created_at DESC` в `get_all_users` и `get_all_users_no_limit` |
+| 1.2 | Ввести единый `items_per_page = 9` в `create_keyboard_with_pagination` и во всех местах пагинации |
+| 1.3 | Создать единую функцию `get_banned_users_data(page, items_per_page)` в `AdminService` или `helper_func`, возвращающую `(message_text, buttons_list)` для заданной страницы |
+| 1.4 | Обновить `get_banned_users_list` и `get_banned_users_buttons` — использовать общий источник и пагинацию |
+| 1.5 | Обновить `admin_handlers.get_banned_users` и `callback_handlers.change_page` — вызывать единую функцию с `page` |
+| 1.6 | Прогнать тесты `test_keyboards_and_filters`, `test_callback_handlers`, `test_admin_handlers` |
+
+**Затронутые файлы:**
+- `database/repositories/blacklist_repository.py`
+- `helper_bot/keyboards/keyboards.py`
+- `helper_bot/utils/helper_func.py`
+- `helper_bot/handlers/admin/services.py`
+- `helper_bot/handlers/admin/admin_handlers.py`
+- `helper_bot/handlers/callback/callback_handlers.py`
+
+---
+
+### Этап 2: Обогащение сообщений пользователей админам
+
+| Шаг | Действие |
+|-----|----------|
+| 2.1 | Добавить в `AsyncBotDB`/репозитории методы: `get_posts_count_by_author`, `get_last_post_by_author`, `get_ban_history_count`, `get_last_ban_info`, `get_user_date_added` |
+| 2.2 | Добавить в `BlacklistHistoryRepository` методы для истории банов (количество, последний бан) |
+| 2.3 | В `UserService` или отдельном сервисе: метод `format_user_message_for_admins(user_id, message_text)` — собирает текст с данными пользователя |
+| 2.4 | В `resend_message_in_group_for_message`: заменить `forward` на `send_message` с обогащённым текстом (имя, ник, id, посты, последний пост, баны, дата регистрации) |
+| 2.5 | Сохранять `message_id` из результата `send_message` в `user_messages` (вместо `message.message_id + 1`) |
+| 2.6 | Проверить, что `get_user_by_message_id` по-прежнему возвращает `user_id` для ответа админа |
+| 2.7 | Обновить/добавить тесты для `resend_message_in_group_for_message` и `AdminReplyService` |
+
+**Данные для обогащения:**
+- Количество постов от пользователя
+- Последний пост пользователя (текст)
+- Количество банов
+- Дата и причина последнего бана (если был)
+- Дата создания пользователя в БД (первый контакт с ботом)
+- Имя, ник, id пользователя (обязательно при send вместо forward)
+
+**Шаблон итогового сообщения для админов:**
+
+```text
+👤 От: Иван Петров (@ivan_petrov) | ID: 123456789
+
+📊 Постов в базе: 5
+📝 Последний пост: "Привет, хочу поделиться мыслями о..."
+📅 В боте с: 15.01.2025
+
+🚫 Банов: 2
+   Последний: 20.02.2025, причина «Спам», истёк 27.02.2025
+
+---
+**Сообщение пользователя:**
+
+**Почему удалили мой пост?**
+```
+
+**Правила форматирования:**
+- Секции «Банов: 0» и «Последний: …» — показывать только если были баны
+- «Последний пост» — обрезать до ~80 символов + «…» если длиннее; если постов нет — «Нет постов»
+- Даты в формате `DD.MM.YYYY` или `DD.MM.YYYY HH:MM` для разбана
+- Разделитель `---` перед текстом сообщения пользователя
+
+**Для тестов:** использовать этот шаблон как эталон; проверять наличие всех секций, порядок полей, экранирование HTML в имени/нике/тексте.
+
+**Затронутые файлы:**
+- `database/async_db.py`
+- `database/repositories/post_repository.py`
+- `database/repositories/blacklist_history_repository.py`
+- `database/repositories/user_repository.py`
+- `helper_bot/handlers/private/private_handlers.py`
+- `helper_bot/handlers/private/services.py`
+- `helper_bot/handlers/group/services.py`
+
+---
+
+### Этап 3: Причина бана «Последний пост»
+
+| Шаг | Действие |
+|-----|----------|
+| 3.1 | В `callback/services.py` в `ban_user_from_post`: заменить `message_for_user="Спам"` на `message_for_user="Последний пост"` |
+| 3.2 | Обновить тесты, где ожидается «Спам» |
+
+**Затронутые файлы:**
+- `helper_bot/handlers/callback/services.py`
+- `tests/test_callback_services.py` (если есть)
+
+---
+
+### Этап 4: Похожие посты (RAG + бот)
+
+**Разделение работ:**
+- **RAG сервис** — промпт в `.cursor/prompt-stage-4-similar-posts.md`
+- **Подключение в боте** — ниже, раздел 4.2
+
+#### 4.0. Текущая архитектура RAG сервиса
+
+**Путь:** `/Users/andrejkatyhin/Work/PycharmProjects/rag-service`
+
+| Компонент | Описание |
+|-----------|----------|
+| **VectorStore** (`app/storage/vector_store.py`) | In-memory хранилище векторов. `_positive_vectors` / `_negative_vectors` — для модерации. Персистентность: `positive_embeddings.npy`, `negative_embeddings.npy` или `vectors.npz`. Косинусное сходство через `np.dot` для нормализованных векторов. |
+| **RAGService** (`app/services/rag_service.py`) | Модель `sentence-transformers/all-MiniLM-L12-v2` (384 dim). `get_embedding(text)`, `calculate_score(text)`, `add_positive_example`, `add_negative_example`. |
+| **API** (`app/api/routes.py`) | `POST /api/v1/score`, `POST /api/v1/examples/positive`, `POST /api/v1/examples/negative`, `GET /api/v1/stats`, `POST /api/v1/warmup`, `GET/PUT /api/v1/scoring/params`. |
+| **Config** (`app/config.py`) | `RAG_VECTORS_PATH`, `RAG_MAX_EXAMPLES`, `vector_dim=384`. |
+
+**Важно:** Позитив/негатив — отдельные коллекции без `created_at`. Для похожих постов нужна **третья** коллекция с временными метками.
+
+---
+
+#### 4.1. Работы в RAG сервисе
+
+##### 4.1.1. Расширить VectorStore
+
+**Файл:** `app/storage/vector_store.py`
+
+Добавить третью коллекцию для submitted-постов:
+
+```python
+# Новые атрибуты (аналогично _positive_vectors)
+self._submitted_vectors: list = []
+self._submitted_hashes: list = []
+self._submitted_created_at: list = []   # Unix timestamps
+self._submitted_post_ids: list = []    # post_id из бота
+self._submitted_texts: list = []       # текст поста (для возврата в similar)
+self._submitted_rag_scores: list = []  # rag_score на момент добавления
+```
+
+**Новые методы:**
+
+| Метод | Описание |
+|-------|----------|
+| `add_submitted(vector, text_hash, created_at, post_id=None, text="", rag_score=None)` | Добавить пост в коллекцию submitted. FIFO при превышении `max_submitted` (новый лимит, например 5000). |
+| `find_similar_submitted(vector, threshold, hours)` | Возвращает: `List[dict]` с полями `similarity`, `created_at`, `post_id`, `text`, `rag_score`. Фильтрует по `created_at >= now - hours*3600`. Сравнивает с `_submitted_vectors` через `np.dot`. Возвращает только те, где similarity >= threshold. |
+
+**Персистентность:** Добавить в `save_to_disk` / `_load_from_disk` сохранение submitted-коллекции. Файл `submitted_embeddings.npz` с полями: `vectors`, `hashes`, `created_at`, `post_ids`, `texts`, `rag_scores`.
+
+**Конфиг:** Добавить `RAG_MAX_SUBMITTED` (default 5000), `RAG_SUBMITTED_PATH` (путь к файлу submitted).
+
+##### 4.1.2. Расширить RAGService
+
+**Файл:** `app/services/rag_service.py`
+
+| Метод | Описание |
+|-------|----------|
+| `add_submitted_post(text, post_id=None, rag_score=None)` | Очистить текст, получить embedding, `add_submitted` в vector_store. Сохраняет `text` и `rag_score` для возврата в similar. Вызывается при каждом suggest (бот передаёт rag_score из скоринга). |
+| `find_similar_posts(text, threshold=0.9, hours=24)` | Получить embedding, вызвать `vector_store.find_similar_submitted`. Вернуть список похожих с полями: `similarity`, `created_at`, `post_id`, `text`, `rag_score`. |
+
+##### 4.1.3. Добавить API endpoint
+
+**Файл:** `app/api/routes.py`
+
+**POST /api/v1/similar**
+
+Возвращает: количество похожих постов, текст каждого, similarity (косинусное сходство), присвоенный rag_score на момент добавления.
+
+```python
+# Request
+class SimilarRequest(BaseModel):
+    text: str = Field(..., min_length=1)
+    threshold: float = Field(default=0.9, ge=0.0, le=1.0)
+    hours: int = Field(default=24, ge=1, le=168)  # 1ч–7дней
+
+# Response
+class SimilarPostItem(BaseModel):
+    similarity: float      # косинусное сходство (0.0–1.0)
+    created_at: int        # Unix timestamp
+    post_id: Optional[int] = None
+    text: str              # текст похожего поста
+    rag_score: Optional[float] = None  # rag_score на момент добавления
+
+class SimilarResponse(BaseModel):
+    similar_count: int
+    similar_posts: List[SimilarPostItem]
+```
+
+**POST /api/v1/submitted**
+
+```python
+# Request
+class SubmittedRequest(BaseModel):
+    text: str = Field(..., min_length=1)
+    post_id: Optional[int] = None
+    rag_score: Optional[float] = None  # для возврата в similar
+
+# Response
+class SubmittedResponse(BaseModel):
+    success: bool
+    message: str
+    submitted_count: int
+```
+
+**Примечание:** `POST /submitted` вызывается ботом при каждом suggest (после сохранения поста в БД). `POST /similar` вызывается ботом **перед** отправкой в группу модерации — чтобы проверить, есть ли похожие посты за последние сутки.
+
+##### 4.1.4. Схемы и исключения
+
+**Файл:** `app/schemas.py` — добавить `SimilarRequest`, `SimilarResponse`, `SimilarPostItem`, `SubmittedRequest`, `SubmittedResponse`.
+
+**Файл:** `app/exceptions.py` — при необходимости добавить `SubmittedStoreError` (если коллекция пуста и т.п.).
+
+##### 4.1.5. Автоочистка submitted (опционально)
+
+В `autosave_loop` или отдельно: периодически удалять из `_submitted_*` записи старше N часов (например, 48), чтобы не раздувать память.
+
+---
+
+#### 4.2. Подключение в Telegram Helper Bot
+
+> RAG сервис реализуется отдельно (промпт: `.cursor/prompt-stage-4-similar-posts.md`). Ниже — интеграция в бота.
+
+##### 4.2.1. RagApiClient (`helper_bot/services/scoring/rag_client.py`)
+
+Добавить методы:
+
+- `find_similar_posts(text, threshold=0.9, hours=24)` — POST на `{api_url}/similar`, body `{"text": text, "threshold": threshold, "hours": hours}`. Вернуть `SimilarResponse` (или dataclass/dict) или `None` при ошибке.
+- `add_submitted_post(text, post_id=None, rag_score=None)` — POST на `{api_url}/submitted`, body `{"text": text, "post_id": post_id, "rag_score": rag_score}`. При ошибке — логировать, не падать.
+
+Оба метода проверяют `self._enabled` и не делают запросы, если RAG отключён.
+
+##### 4.2.2. PostService (`helper_bot/handlers/private/services.py`)
+
+В `_process_post_background` и `_process_media_group_background`:
+
+**Порядок вызовов:**
+1. Получить скоры (`_get_scores_with_error_handling`) — уже есть `rag_score`.
+2. **Перед** отправкой: вызвать `find_similar_posts(original_raw_text, 0.9, 24)`. Если RAG недоступен или ошибка — не падать, пропустить.
+3. Если `similar_count > 0`: добавить в `post_text` строку `\n\n⚠️ Похожий пост за последние 24ч (совпадение {max_similarity:.0%})`.
+4. Отправить пост в группу модерации.
+5. Сохранить в БД.
+6. **После** успешной отправки: вызвать `add_submitted_post(original_raw_text, sent_message.message_id, rag_score)` — в фоне. `rag_score` из шага 1.
+
+**Важно:** Проверка similar — **до** добавления текущего поста в submitted.
+
+##### 4.2.3. Доступ к RagApiClient
+
+`RagApiClient` создаётся через `ScoringManager` или `BaseDependencyFactory`. PostService должен иметь доступ к `rag_client` (или `scoring_manager`). При необходимости добавить методы в `ScoringManager` как прокси к RAG.
+
+##### 4.2.4. Обработка ошибок
+
+При недоступности RAG — не падать, не добавлять предупреждение и не индексировать.
+
+---
+
+#### 4.3. Порядок вызовов в боте
+
+```text
+1. Пользователь отправляет пост
+2. PostService._process_post_background:
+   a) Получить скоры (rag_score, confidence, ...)
+   b) find_similar_posts(text, 0.9, 24) — есть ли похожие? (возвращает count, text, similarity, rag_score)
+   c) Если да — добавить предупреждение в post_text
+   d) Отправить пост в группу модерации
+   e) Сохранить в БД (add_post)
+   f) add_submitted_post(text, message_id, rag_score) — индексировать в RAG
+```
+
+**Важно:** Проверка similar делается **до** добавления текущего поста в submitted, иначе пост будет похож сам на себя.
+
+---
+
+#### 4.4. Затронутые файлы
+
+| Репозиторий | Файлы |
+|-------------|-------|
+| **rag-service** | `app/storage/vector_store.py`, `app/services/rag_service.py`, `app/api/routes.py`, `app/schemas.py`, `app/config.py`, `app/main.py` (описание в docs) |
+| **telegram-helper-bot** | `helper_bot/services/scoring/rag_client.py`, `helper_bot/handlers/private/services.py` |
+
+---
+
+### Этап 5: Авто-публикация/отклонение (задел на будущее)
+
+| Шаг | Действие |
+|-----|----------|
+| 5.1 | В `PostService._process_post_background`: после получения `rag_score` проверять пороги |
+| 5.2 | Если `rag_score >= 0.8`: не показывать кнопки модерации, сразу публиковать (или вызывать логику publish) |
+| 5.3 | Если `rag_score <= 0.4`: сразу отклонять (decline) |
+| 5.4 | Добавить флаги в `.env` (например, `AUTO_PUBLISH_ENABLED`, `AUTO_DECLINE_ENABLED`) — по умолчанию `false` |
+| 5.5 | Реализацию оформить как выключенную по умолчанию; включение — через конфиг |
+
+**Затронутые файлы:**
+- `helper_bot/handlers/private/services.py`
+- `helper_bot/config/` или `.env`
+
+---
+
+### Этап 5.5: ML Scoring Статистика — восстановить полный вывод
+
+**Проблема:** Раньше «📊 ML Статистика» показывала детали (модель, device, кол-во примеров, размерность). Теперь только API URL и статус.
+
+**Причина:** Бот использует fallback (`get_stats_sync`) когда `RagApiClient.get_stats()` возвращает пустой результат. Это происходит при:
+- 401/403 (ошибка авторизации)
+- таймауте или ошибке соединения
+- неверном формате ответа от API
+
+**Задачи:**
+
+| Шаг | Действие |
+|-----|----------|
+| 5.5.1 | Проверить, что RAG API `GET /stats` доступен с бота (сеть, CORS, API key). |
+| 5.5.2 | Убедиться, что `RagApiClient.get_stats()` передаёт заголовок `X-API-Key` и корректно обрабатывает 200. |
+| 5.5.3 | Проверить контракт ответа: RAG возвращает `model_name`, `model_loaded`, `device`, `vector_store` (positive_count, negative_count, total_count, vector_dim, max_examples). |
+| 5.5.4 | При ошибке API — логировать причину (status, body) и при необходимости улучшить fallback-сообщение (например, «API недоступен: …»). |
+| 5.5.5 | Добавить тесты для `get_ml_stats` с моком API (успешный ответ и fallback). |
+
+**Затронутые файлы:**
+- `helper_bot/handlers/admin/admin_handlers.py` (get_ml_stats)
+- `helper_bot/services/scoring/rag_client.py` (get_stats, get_stats_sync)
+- `helper_bot/services/scoring/scoring_manager.py` (get_stats)
+
+---
+
+### Этап 6: Тесты и качество кода
+
+| Шаг | Действие |
+|-----|----------|
+| 6.1 | Прогнать все тесты: `pytest tests/ -v` |
+| 6.2 | `make code-quality` (или `isort`, `black`, `flake8`) |
+| 6.3 | При необходимости обновить моки и фикстуры |
+
+---
+
+### Этап 7: Release Notes и деплой
+
+| Шаг | Действие |
+|-----|----------|
+| 7.1 | Создать `docs/RELEASE_NOTES_DEV-N.md` по шаблону из `.cursor/rules/release-notes-template.md` |
+| 7.2 | Коммиты в формате: `feat:`, `fix:`, `refactor:` |
+| 7.3 | Push в `dev-N` → CI (тесты, code quality) |
+| 7.4 | Создать/обновить PR в `main` |
+| 7.5 | После мержа — деплой по `deploy.yml` (если настроен в prod) |
+
+---
+
+## Зависимости между этапами
+
+```
+Этап 0 → Этап 1, 2, 3 (можно параллельно)
+Этап 1, 2, 3 → Этап 6
+Этап 4 зависит от RAG (отдельный сервис)
+Этап 5 можно делать после 4 или независимо
+Этап 5.5 — независимо (можно параллельно с 1–3)
+```
+
+---
+
+## Рекомендуемый порядок реализации
+
+1. Этап 0 — подготовка
+2. Этапы 1, 2, 3 — независимо, можно в любом порядке
+3. Этап 4 — после готовности RAG
+4. Этап 5 — после 4 или параллельно с 1–3
+5. Этап 5.5 — разобраться с ML Scoring Статистикой (можно параллельно)
+6. Этап 6 — перед PR
+7. Этап 7 — после ревью и мержа
+
+---
+
+## Ссылки на документацию проекта
+
+- `.cursor/rules/my-custom-rule.mdc` — общие правила
+- `.cursor/rules/architecture.md` — архитектура
+- `.cursor/rules/handlers-patterns.md` — паттерны handlers
+- `.cursor/rules/release-notes-template.md` — шаблон Release Notes
+- `prod/.cursor/rules/my-custom-rule.mdc` — CI/CD, ветки, деплой