feat: add help version notices and user errors

bot.py

@@ -1,8 +1,11 @@
 import asyncio
+import html
 import io
 import logging
 import os
+import re
 from contextlib import asynccontextmanager, nullcontext
+from pathlib import Path
 
 import aiohttp
 from aiogram import Bot, Dispatcher, F, Router
@@ -12,10 +15,23 @@ from aiogram.filters import CommandStart
 from aiogram.types import Message
 
 from apinex_client import APINEX_STT_URL, classify_intent, extract_tone_from_images, extract_transcript, generate_posts, transcribe_audio
-from user_store import get_tone_of_voice, init_db, save_tone_of_voice
+from help_message import HELP_RICH_HTML, rich_to_plain
+from user_store import (
+    get_deploy_notice_version,
+    get_tone_of_voice,
+    init_db,
+    save_tone_of_voice,
+    set_deploy_notice_version,
+)
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
+VERSION = Path(__file__).with_name("VERSION").read_text(encoding="utf-8").strip()
+BOT_ENV = os.getenv("BOT_ENV", "test").strip().lower()
+DEPLOY_ENV = os.getenv("DEPLOY_ENV", "production").strip().lower()
+DEV_CHAT_ID = os.getenv("DEV_CHAT_ID", "").strip()
+HELP_COMMANDS = {"help", "помощь"}
+_deploy_notice_lock = asyncio.Lock()
 
 router = Router()
 MAX_AUDIO_BYTES = 20 * 1024 * 1024
@@ -24,6 +40,13 @@ TYPING_REFRESH_SECONDS = 4
 MEDIA_GROUP_COLLECT_SECONDS = 0.8
 _media_groups: dict[tuple[int, str], dict[str, object]] = {}
 _media_groups_lock = asyncio.Lock()
+_deploy_notice_sent = False
+_deploy_notice_lock = asyncio.Lock()
+
+
+def _read_version() -> str:
+    version_path = Path(__file__).with_name("VERSION")
+    return version_path.read_text(encoding="utf-8").strip()
 
 
 def split_text(text: str, limit: int = 4000) -> list[str]:
@@ -40,14 +63,89 @@ def split_text(text: str, limit: int = 4000) -> list[str]:
     return chunks
 
 
+async def report_error(message: Message, stage: str, exc: Exception) -> None:
+    detail = str(exc).strip()
+    detail = re.sub(r"(?i)(?:sk-[A-Za-z0-9_-]{12,}|[0-9]{8,}:[A-Za-z0-9_-]{20,})", "[секрет скрыт]", detail)
+    detail = re.sub(r"https?://\S+", "[внешний сервис]", detail)
+    detail = detail or "нет подробностей"
+    try:
+        await message.answer(f"❌ Не получилось: {stage}.\nПричина: <code>{html.escape(detail[:240])}</code>", parse_mode="HTML")
+    except Exception as send_exc:
+        logger.error("Unable to report processing error: %s", type(send_exc).__name__)
+    logger.error("User operation failed at %s (%s): %s", stage, type(exc).__name__, detail[:240])
+
+
+async def notify_development_deploy(bot: Bot) -> None:
+    if DEPLOY_ENV != "development":
+        return
+    chat_id = os.getenv("DEV_CHAT_ID", "").strip()
+    if not chat_id:
+        logger.warning("DEV_CHAT_ID is missing; no version notice will be sent")
+        return
+    async with _deploy_notice_lock:
+        previous = await asyncio.to_thread(get_deploy_notice_version)
+        if previous == VERSION:
+            return
+        try:
+            await asyncio.wait_for(
+                bot.send_message(chat_id=int(chat_id), text=f"🚀 Бот обновлён\nВерсия: {VERSION}"),
+                timeout=8,
+            )
+        except Exception as exc:
+            logger.error("Development deploy notice failed (%s): %s", type(exc).__name__, str(exc)[:160])
+            return
+        await asyncio.to_thread(set_deploy_notice_version, VERSION)
+        logger.info("Development deploy notice sent: version=%s", VERSION)
+
+
+async def send_rich_help(message: Message) -> bool:
+    bot = message.bot
+    payload = {"chat_id": message.chat.id, "rich_message": {"html": HELP_RICH_HTML}}
+    if message.message_thread_id is not None:
+        payload["message_thread_id"] = message.message_thread_id
+    url = bot.session.api.api_url(token=bot.token, method="sendRichMessage")
+    timeout = aiohttp.ClientTimeout(total=15)
+    try:
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.post(
+                url, json=payload,
+                headers={"User-Agent": "Mozilla/5.0 (compatible; SocialPostWriterBot/1.0)"},
+            ) as response:
+                data = await response.json(content_type=None)
+                if response.status == 200 and data.get("ok"):
+                    return True
+                logger.warning("Rich help rejected with HTTP %s", response.status)
+                return False
+    except Exception as exc:
+        logger.warning("Rich help delivery error (%s): %s", type(exc).__name__, str(exc)[:160])
+        return False
+
+
+
 @router.message(CommandStart())
 async def start(message: Message) -> None:
+    await notify_development_deploy(message.bot)
     await message.answer(
         "Я помогаю писать посты для соцсетей. Пришли скриншот своих постов, чтобы настроить стиль, "
-        "или попроси написать пост, например: «Придумай пост про запуск нового продукта»."
+        "или попроси написать пост, например: «Придумай пост про запуск нового продукта». "
+        "Подробная инструкция — /help."
     )
 
 
+async def help_command(message: Message) -> None:
+    try:
+        rich_sent = await send_rich_help(message)
+    except Exception as exc:
+        rich_sent = False
+        logger.warning("Rich help send failed (%s): %s", type(exc).__name__, str(exc)[:180])
+        if DEPLOY_ENV == "development":
+            await report_error(message, "отправка Rich Message помощи", exc)
+    if not rich_sent:
+        if DEPLOY_ENV == "development":
+            await report_error(message, "отправка Rich Message помощи", RuntimeError("sendRichMessage returned false"))
+        await message.answer(rich_to_plain(HELP_RICH_HTML))
+
+
 async def _send_three_posts(message: Message, posts: list[str]) -> None:
     for post in posts:
         await message.answer(post)
@@ -91,6 +189,9 @@ async def _classify_and_respond(message: Message, text: str, show_typing: bool =
     try:
         async with (typing_status(message.bot, message.chat.id) if show_typing else nullcontext()):
             intent = await classify_intent(text, original_post or None)
+            if intent["intent"] == "help":
+                await help_command(message)
+                return
             if intent["intent"] == "other":
                 await message.answer("Я помогаю только писать и редактировать посты для социальных сетей.")
                 return
@@ -106,12 +207,8 @@ async def _classify_and_respond(message: Message, text: str, show_typing: bool =
                 tone = await asyncio.to_thread(get_tone_of_voice, message.from_user.id)
                 posts = await generate_posts(intent, tone)
             await _send_three_posts(message, posts)
-    except (aiohttp.ClientError, asyncio.TimeoutError, RuntimeError, ValueError) as exc:
-        logger.warning("Post request failed: %s", type(exc).__name__)
-        await message.answer("Не получилось подготовить посты. Попробуй ещё раз позже.")
-    except Exception:
-        logger.exception("Unexpected post generation error")
-        await message.answer("Произошла ошибка при подготовке постов.")
+    except Exception as exc:
+        await report_error(message, "классификация или генерация поста", exc)
 
 
 async def _download_message_image(message: Message, bot: Bot) -> tuple[bytes, str] | None:
@@ -202,6 +299,7 @@ async def _finish_media_group(key: tuple[int, str]) -> None:
 
 
 async def _handle_image_message(message: Message, bot: Bot) -> None:
+    await notify_development_deploy(bot)
     try:
         if message.media_group_id:
             messages = await _collect_media_group(message, bot)
@@ -211,12 +309,8 @@ async def _handle_image_message(message: Message, bot: Bot) -> None:
             messages = [message]
         async with typing_status(bot, message.chat.id):
             await _process_image_group(messages, bot)
-    except (aiohttp.ClientError, asyncio.TimeoutError, RuntimeError, ValueError) as exc:
-        logger.warning("Tone of voice update failed: %s", type(exc).__name__)
-        await message.answer("Не получилось прочитать скриншот. Попробуй отправить его ещё раз.")
-    except Exception:
-        logger.exception("Unexpected image tone extraction error")
-        await message.answer("Произошла ошибка при чтении скриншота.")
+    except Exception as exc:
+        await report_error(message, "чтение скриншота или обновление ToV", exc)
 
 
 @router.message(F.photo | (F.document & F.document.mime_type.startswith("image/")))
@@ -253,19 +347,28 @@ async def _process_voice(message: Message, bot: Bot) -> None:
 
 @router.message(F.voice | F.audio)
 async def transcribe_voice(message: Message, bot: Bot) -> None:
+    await notify_development_deploy(bot)
     try:
         async with typing_status(bot, message.chat.id):
             await _process_voice(message, bot)
-    except (aiohttp.ClientError, asyncio.TimeoutError, RuntimeError, ValueError) as exc:
-        logger.warning("Voice post request failed: %s", type(exc).__name__)
-        await message.answer("Не удалось обработать голосовое. Попробуй ещё раз или напиши текстом.")
-    except Exception:
-        logger.exception("Unexpected voice post processing failure")
-        await message.answer("Произошла ошибка при обработке голосового.")
+    except Exception as exc:
+        await report_error(message, "обработка голосового и генерация", exc)
+
+
+@router.message(F.text & F.text.startswith("/"))
+async def handle_command_text(message: Message) -> None:
+    command = (message.text or "").strip().split(maxsplit=1)[0].split("@", 1)[0].casefold()
+    if command == "/help":
+        await help_command(message)
+    elif command == "/start":
+        await start(message)
+    else:
+        await message.answer("Неизвестная команда. Используй /help.")
 
 
 @router.message(F.text & ~F.text.startswith("/"))
 async def handle_text(message: Message) -> None:
+    await notify_development_deploy(message.bot)
     if message.text:
         await _classify_and_respond(message, message.text)
 
@@ -279,6 +382,7 @@ async def main() -> None:
     test_env = os.environ.get("BOT_ENV", "test").strip().lower() == "test"
     session = AiohttpSession(api=TEST) if test_env else None
     bot = Bot(token=token, session=session)
+    await notify_development_deploy(bot)
     dp = Dispatcher()
     dp.include_router(router)