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

max_bot/app/handlers/consent.py

@@ -1,3 +1,11 @@
+"""
+Обработчик согласия на обработку персональных данных.
+
+Управляет жизненным циклом согласия:
+  - запрос согласия → да/нет
+  - отзыв согласия (consent_revoked_date)
+  - повторное согласие после отказа
+"""
 import datetime
 import re
 import logging
@@ -12,6 +20,12 @@ logger = logging.getLogger(__name__)
 
 
 def _matches_any(text: str, words: list) -> bool:
+    """
+    Проверяет, содержит ли текст хотя бы одно из указанных слов.
+
+    Использует split для точного совпадения коротких слов (≤3 символов)
+    и подстроку для длинных (>3 символов).
+    """
     text_words = set(text.split())
     for w in words:
         if w in text_words:
@@ -22,6 +36,7 @@ def _matches_any(text: str, words: list) -> bool:
 
 
 async def handle_consent_callback(user_id: int, conv_id: int, callback_id: str) -> None:
+    """Маршрутизация callback-кнопок согласия (да/нет)."""
     if callback_id == "consent_yes":
         await handle_consent_yes(user_id, conv_id)
     elif callback_id == "consent_no":
@@ -29,6 +44,7 @@ async def handle_consent_callback(user_id: int, conv_id: int, callback_id: str)
 
 
 async def handle_consent_response(user_id: int, conv_id: int, text: str) -> None:
+    """Обработка текстового ответа на запрос согласия (да/нет/другое)."""
     text_lower = text.strip().lower()
     consent_words = ["да", "даю", "согласен", "согласна", "yes", "ok", "хорошо", "даю согласие"]
     refuse_words = ["нет", "не даю", "отказ", "no", "не согласен", "не согласна"]
@@ -48,6 +64,7 @@ async def handle_consent_response(user_id: int, conv_id: int, text: str) -> None
 
 
 async def handle_consent_yes(user_id: int, conv_id: int) -> None:
+    """Обработка согласия: устанавливает consent_given=True, переводит в awaiting_contact."""
     async with async_session() as db:
         result = await db.execute(select(BotUser).where(BotUser.id == user_id))
         user = result.scalar_one_or_none()
@@ -78,6 +95,7 @@ async def handle_consent_yes(user_id: int, conv_id: int) -> None:
 
 
 async def handle_consent_no(user_id: int, conv_id: int) -> None:
+    """Обработка отказа: устанавливает consent_refused, показывает контакты."""
     async with async_session() as db:
         result = await db.execute(
             select(BotConversation).where(BotConversation.id == conv_id)
@@ -106,6 +124,7 @@ async def handle_consent_no(user_id: int, conv_id: int) -> None:
 
 
 async def handle_refused_again(user_id: int, conv_id: int, text: str) -> None:
+    """Повторная обработка после отказа: позволяет дать согласие или показывает контакты."""
     text_lower = text.strip().lower()
     consent_words = ["да", "даю", "согласен", "согласна", "yes", "ok", "хорошо", "даю согласие", "передумал", "согласен дать"]
     refuse_words = ["нет", "не даю", "не хочу", "отказ", "отмена", "no", "cancel", "я отказался"]
@@ -145,6 +164,7 @@ async def handle_refused_again(user_id: int, conv_id: int, text: str) -> None:
 
 
 async def handle_revoke_consent(user_id: int, conv_id: int) -> None:
+    """Отзыв согласия: устанавливает consent_given=False, consent_revoked_date=now."""
     async with async_session() as db:
         user = await db.get(BotUser, user_id)
         if user and user.consent_given: