v1.8.3: добавлены docstrings и комментарии по AGENTS.md ко всем ключевым файлам

max_bot/app/max_api.py

@@ -1,3 +1,11 @@
+"""
+API-клиент для MAX Platform (Мой Мир / VK).
+
+Основные методы:
+  - send_message: отправка сообщений (с логированием outgoing BotMessage)
+  - subscribe_webhook: регистрация webhook-а
+  - answer_callback: ответ на callback-кнопки
+"""
 import logging
 import httpx
 from typing import Optional
@@ -9,6 +17,7 @@ TEST_USER_THRESHOLD = 999999000
 
 
 class MaxAPI:
+    """Клиент MAX Platform API с поддержкой mock-реплик для тестов."""
     def __init__(self):
         self.base_url = settings.max_api_base
         self.token = settings.max_token
@@ -65,6 +74,7 @@ class MaxAPI:
         notify: bool = True,
         conversation_id: int = None,
     ) -> dict:
+        """Отправка сообщения. Если conversation_id — сохраняет outgoing BotMessage."""
         if user_id >= TEST_USER_THRESHOLD:
             logger.info(f"MOCK send_message to test user {user_id}: {text[:50]}")
             self.mock_replies.append(text)