Stabilize staff concurrency and premium emoji; enable verified Drone deployment
Some checks failed
continuous-integration/drone/push Build is failing
Some checks failed
continuous-integration/drone/push Build is failing
This commit is contained in:
@@ -1,244 +1,52 @@
|
||||
# Система управления кастомными эмодзи
|
||||
# Премиум-эмодзи в чате и рассылках
|
||||
|
||||
## Обзор
|
||||
Поддержка добавлена для общего чата, личных диалогов, рассылок в личные сообщения, каналы и группы. Сохраняются ID выбранных премиум-эмодзи, оформление текста и подписи к медиа. Новые миграции и переменные окружения для этой функции не требуются.
|
||||
|
||||
Система позволяет администраторам регистрировать премиум эмодзи и использовать их в сообщениях бота. Когда админ отправляет эмодзи боту:
|
||||
## Использование
|
||||
|
||||
1. Бот получает `emoji_id` от Telegram API
|
||||
2. Сохраняет эмодзи в таблице `emoji_mappings`
|
||||
3. При отправке сообщений в чаты бот автоматически использует `emoji_id` вместо текста эмодзи
|
||||
1. Выберите премиум-эмодзи в панели Telegram и отправьте сообщение в режиме чата либо создания рассылки.
|
||||
2. Для подписи к фото, видео или документу добавьте эмодзи прямо в подпись.
|
||||
3. Бот сохраняет выбранный вариант эмодзи, включая случаи, когда у нескольких премиум-вариантов одинаковый обычный символ.
|
||||
|
||||
Это обеспечивает, что эмодзи будут выглядеть точно так же, как их отправил админ, даже если это премиум эмодзи.
|
||||
Имя отправителя добавляется с сохранением оформления сообщения. Если заголовок не помещается вместе с текстом или подписью в лимит Telegram, бот отправляет заголовок отдельно и копирует исходное сообщение целиком.
|
||||
|
||||
## Команды администратора
|
||||
Условия Telegram: новые сообщения с custom emoji могут отправлять боты с дополнительным именем пользователя, приобретённым через Fragment. Также они разрешены в сообщениях бота в личных чатах, группах и супергруппах, если **владелец бота** имеет активную подписку Telegram Premium. Исключение по подписке владельца в документации не распространяется на каналы. Эти условия задаёт Telegram; флаг внутри приложения их не меняет. [Официальная документация](https://core.telegram.org/bots/api#formatting-options).
|
||||
|
||||
### 1. Добавить новый эмодзи
|
||||
Отправка обычного Unicode-символа передаёт обычный эмодзи. Премиум-вариант определяется полем `custom_emoji_id`, которое Telegram присылает вместе с выбранным эмодзи. Предварительная регистрация в каталоге для чата и рассылки не требуется.
|
||||
|
||||
```
|
||||
/add_emoji
|
||||
```
|
||||
## Каталог администратора
|
||||
|
||||
Процесс:
|
||||
1. Админ запускает команду `/add_emoji`
|
||||
2. Бот просит отправить эмодзи
|
||||
3. Админ отправляет эмодзи (например, 🎲)
|
||||
4. Бот просит описание (для чего используется)
|
||||
5. Админ отправляет描述 (например, "Для лотереи")
|
||||
6. Бот сохраняет в БД и подтверждает
|
||||
- `/add_emoji` — сохранить один премиум-эмодзи и описание для шаблонов.
|
||||
- `/my_emojis` — показать свои записи.
|
||||
- `/all_emojis` — показать общий каталог.
|
||||
- `/delete_emoji` — удалить свою запись. Главный администратор также может удалять записи других сотрудников.
|
||||
|
||||
### 2. Просмотр своих эмодзи
|
||||
Команда добавления принимает настоящий `custom_emoji` из Telegram. Описание ограничено 255 символами. Связь записи с администратором хранится через внутренний ID пользователя в БД; интерфейс принимает Telegram ID. Повторная регистрация даёт понятный ответ без повреждения сессии БД.
|
||||
|
||||
```
|
||||
/my_emojis
|
||||
```
|
||||
## Реализация
|
||||
|
||||
Показывает все эмодзи, добавленные этим админом:
|
||||
- Сам эмодзи
|
||||
- Описание
|
||||
- ID (первые 30 символов)
|
||||
- Дату добавления
|
||||
`src/utils/telegram_messages.py` содержит общий путь передачи сообщений:
|
||||
|
||||
### 3. Просмотр всех эмодзи в системе
|
||||
- без заголовка используется `copyMessage`, сохраняющий исходное сообщение;
|
||||
- при добавлении имени передаются исходные `entities` / `caption_entities` с поправкой позиции на длину заголовка в UTF-16;
|
||||
- `parse_mode=None` предотвращает повторный разбор пользовательского текста;
|
||||
- длинные сообщения копируются без обрезания текста или разрыва эмодзи.
|
||||
|
||||
```
|
||||
/all_emojis
|
||||
```
|
||||
Общий чат, P2P и оба вида рассылок используют этот путь. Ошибка оформления сообщения, включая недопустимый custom emoji, учитывается как ошибка доставки и не блокирует получателя для следующих рассылок.
|
||||
|
||||
Показывает все эмодзи всех админов с информацией об администраторе
|
||||
|
||||
### 4. Удалить эмодзи
|
||||
|
||||
```
|
||||
/delete_emoji
|
||||
```
|
||||
|
||||
Админ может удалить только свои эмодзи. Процесс:
|
||||
1. Вызвать команду
|
||||
2. Выбрать эмодзи из список (кнопки)
|
||||
3. Бот удалит из БД
|
||||
|
||||
## Использование в коде
|
||||
|
||||
### Простой способ - прямое использование эмодзи
|
||||
Для программно создаваемого шаблона из обычного текста доступен HTML-рендер каталога:
|
||||
|
||||
```python
|
||||
from aiogram.types import Message
|
||||
|
||||
async def handler(message: Message):
|
||||
await message.answer(
|
||||
text="🎲 Добро пожаловать на лотерею! 🏆",
|
||||
parse_mode="HTML"
|
||||
)
|
||||
```
|
||||
|
||||
### С обработкой эмодзи
|
||||
|
||||
```python
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from src.core.emoji_message_helper import get_emoji_aware_text
|
||||
from aiogram.types import Message
|
||||
|
||||
async def handler(message: Message, session: AsyncSession):
|
||||
# Текст с эмодзи
|
||||
original_text = "🎲 Выиграли! 🏆"
|
||||
|
||||
# Обработаны текст (эмодзи заменены на ID для корректного отображения)
|
||||
processed_text = await get_emoji_aware_text(session, original_text)
|
||||
|
||||
await message.answer(processed_text, parse_mode="HTML")
|
||||
html = await get_emoji_aware_text(session, "🎲 Розыгрыш начался!")
|
||||
await bot.send_message(chat_id, html, parse_mode="HTML")
|
||||
```
|
||||
|
||||
### Работа с EmojiMessageHelper
|
||||
Вход этого помощника — обычный текст. Он экранирует HTML и добавляет настоящие `<tg-emoji emoji-id="...">...</tg-emoji>`. Входящие пользовательские сообщения сохраняют собственные entities и не проходят через каталог замен.
|
||||
|
||||
```python
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from src.core.emoji_message_helper import EmojiMessageHelper
|
||||
## Проверка
|
||||
|
||||
async def handler(message: Message, session: AsyncSession):
|
||||
helper = EmojiMessageHelper(session)
|
||||
|
||||
# Обработка перед отправкой
|
||||
text = "🎲 Лотерея начинается! 💎"
|
||||
processed = await helper.process_text_before_send(text)
|
||||
|
||||
await message.answer(processed, parse_mode="HTML")
|
||||
```
|
||||
`tests/test_premium_emoji.py` проверяет ID и UTF-16-позиции нескольких эмодзи, вложенное оформление, подписи к шести типам медиа, предельную длину текста/подписей, P2P-доставку, копирование рассылок, ошибки Telegram и настоящий маршрут регистрации эмодзи. Ответы Telegram в тестах подменены; права конкретного рабочего бота и отображение в клиенте Telegram нужно проверить после установки релиза.
|
||||
|
||||
## Структура БД
|
||||
|
||||
### Таблица `emoji_mappings`
|
||||
|
||||
| Колонка | Тип | Описание |
|
||||
|---------|-----|---------|
|
||||
| `id` | Integer | Primary Key |
|
||||
| `emoji_text` | String(10) | Сам эмодзи (например, 🎲) |
|
||||
| `emoji_id` | String(255) | telegram_emoji_id от API (уникален) |
|
||||
| `admin_id` | Integer | FK на user (администратор) |
|
||||
| `description` | String(255) | Описание назначения эмодзи |
|
||||
| `created_at` | DateTime | Дата добавления |
|
||||
| `last_used_at` | DateTime | Последнее использование |
|
||||
|
||||
### Уникальные ограничения
|
||||
|
||||
- `emoji_id` — уникален во всей системе
|
||||
- `(emoji_text, admin_id)` — один админ не может добавить один эмодзи дважды
|
||||
|
||||
## API сервиса EmojiMappingService
|
||||
|
||||
### Регистрация эмодзи
|
||||
|
||||
```python
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from src.core.emoji_mapping_service import EmojiMappingService
|
||||
|
||||
async with async_session_maker() as session:
|
||||
service = EmojiMappingService(session)
|
||||
|
||||
emoji = await service.register_emoji(
|
||||
emoji_text="🎲",
|
||||
emoji_id="telegram_emoji_id_here",
|
||||
admin_id=12345,
|
||||
description="Для лотереи"
|
||||
)
|
||||
```
|
||||
|
||||
### Получение эмодзи
|
||||
|
||||
```python
|
||||
# По тексту
|
||||
emoji = await service.get_emoji_by_text("🎲")
|
||||
|
||||
# По emoji_id
|
||||
emoji = await service.get_emoji_by_id("telegram_emoji_id")
|
||||
|
||||
# Все эмодзи админа
|
||||
emojis = await service.get_all_emoji_by_admin(admin_id=12345)
|
||||
|
||||
# Все эмодзи
|
||||
all_emojis = await service.get_all_emojis()
|
||||
```
|
||||
|
||||
### Замена эмодзи в тексте
|
||||
|
||||
```python
|
||||
# Текст → с заменой эмодзи на ID
|
||||
processed = await service.replace_emojis_in_text(
|
||||
"🎲 Выиграли! 🏆"
|
||||
)
|
||||
|
||||
# Обратно - ID → эмодзи
|
||||
original = await service.restore_emojis_in_text(processed)
|
||||
```
|
||||
|
||||
### Получить словарь маппинга
|
||||
|
||||
```python
|
||||
# {emoji_text: emoji_id}
|
||||
mapping = await service.get_emoji_mapping_dict()
|
||||
# {'🎲': 'telegram_emoji_id_1', '🏆': 'telegram_emoji_id_2', ...}
|
||||
```
|
||||
|
||||
## Примеры использования в разных рутерах
|
||||
|
||||
### В регистрации
|
||||
|
||||
```python
|
||||
async def registration_complete(message: Message, session: AsyncSession):
|
||||
text = "✅ Регистрация завершена! 🎉"
|
||||
text = await get_emoji_aware_text(session, text)
|
||||
await message.answer(text, parse_mode="HTML")
|
||||
```
|
||||
|
||||
### В админ-панели
|
||||
|
||||
```python
|
||||
async def lottery_created(callback: CallbackQuery, session: AsyncSession):
|
||||
text = "🎰 Новый розыгрыш создан! 🏆"
|
||||
text = await get_emoji_aware_text(session, text)
|
||||
await callback.message.edit_text(text, parse_mode="HTML")
|
||||
```
|
||||
|
||||
### В чатовой рассылке
|
||||
|
||||
```python
|
||||
async def broadcast_message(message: Message, session: AsyncSession):
|
||||
text = f"📢 Сообщение от админа: {message.text}\n\n💎 Удачи!"
|
||||
text = await get_emoji_aware_text(session, text)
|
||||
|
||||
for user_id in target_users:
|
||||
await bot.send_message(user_id, text, parse_mode="HTML")
|
||||
```
|
||||
|
||||
## Важные моменты
|
||||
|
||||
1. **Parse Mode**: Всегда используйте `parse_mode="HTML"` при работе с эмодзи
|
||||
2. **Кеширование ID**: Система не кеширует, каждый раз обращается к БД. Для оптимизации можно добавить кеширование
|
||||
3. **Лог использования**: `last_used_at` обновляется автоматически при замене в тексте
|
||||
4. **Удаление**: Удаленный эмодзи больше не будет заменяться в новых сообщениях
|
||||
5. **Конфликты**: Если два админа добавляют один эмодзи - они сохранятся отдельно (разные admin_id)
|
||||
|
||||
## Миграция
|
||||
|
||||
Таблица создана миграцией:
|
||||
```
|
||||
migrations/versions/20260307_0100_add_emoji_mappings.py
|
||||
```
|
||||
|
||||
Применить миграцию:
|
||||
```bash
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
## Trouble Shooting
|
||||
|
||||
### Эмодзи не отображается корректно
|
||||
- Проверьте что используете `parse_mode="HTML"`
|
||||
- Убедитесь что эмодзи зарегистрирован с помощью `/my_emojis`
|
||||
|
||||
### Ошибка "Can't parse entities"
|
||||
- Это означает что есть конфликт форматирования
|
||||
- Убедитесь что используете HTML теги (`<b>`, `<i>`, и т.д.), а не Markdown (`**`, `__`)
|
||||
|
||||
### Эмодзи не заменяется
|
||||
- Проверьте что был зарегистрирован с помощью `/add_emoji`
|
||||
- Убедитесь что используете функцию `get_emoji_aware_text()` перед отправкой
|
||||
Итоговый прогон 13 сентября 2026: PostgreSQL — 61 тест прошёл; SQLite — 60 прошли, один тест миграций пропущен. Ruff, compileall и проверка отслеживаемых секретов прошли. Изменения подготовлены локально; установки этой версии на рабочий сервер в рамках проверки не было.
|
||||
|
||||
Reference in New Issue
Block a user