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

max_bot/app/models.py

@@ -1,3 +1,20 @@
+"""
+ORM-модели для PostgreSQL (SQLAlchemy 2.0).
+
+Таблицы:
+  - bot_settings: настройки бота (ключ-значение)
+  - bot_features: фичи бота (вкл/выкл)
+  - bot_categories: категории базы знаний
+  - bot_knowledge_base: карточки базы знаний
+  - bot_users: пользователи бота (контакты, согласие)
+  - bot_conversations: диалоги (state machine)
+  - bot_messages: сообщения (incoming/outgoing)
+  - bot_tickets: заявки
+  - bot_ticket_messages: сообщения заявок
+  - bot_processing_logs: логи обработки
+  - bot_ticket_statuses: история смены статусов заявок
+  - bot_unknown_questions: неизвестные вопросы (автогенерация KB)
+"""
 from __future__ import annotations
 import datetime
 from sqlalchemy import Column, Integer, BigInteger, String, Text, Boolean, DateTime, ForeignKey, ARRAY
@@ -53,6 +70,7 @@ class BotKnowledgeBase(Base):
 
 
 class BotUser(Base):
+    """Пользователь бота: профиль, контакты, согласие на обработку ПД."""
     __tablename__ = "bot_users"
     id = Column(BigInteger, primary_key=True)
     first_name = Column(String(255), nullable=True)