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

py_service/app/config.py

@@ -1,3 +1,12 @@
+"""
+Конфигурация service portal (Pydantic Settings).
+
+Читает из .env:
+  - DATABASE_URL: PostgreSQL URL
+  - SECRET_KEY: ключ сессий
+  - SESSION_TTL: время жизни сессии (сек)
+  - DOCS_DIR/UPLOADS_DIR: пути к документам
+"""
 import os
 from pathlib import Path
 from pydantic_settings import BaseSettings

py_service/app/main.py

@@ -1,3 +1,13 @@
+"""
+Главный модуль service portal FastAPI-приложения.
+
+Портал для управления:
+  - Сотрудниками (owner/engineer/technician)
+  - Клиентами и объектами
+  - Задачами и инцидентами
+  - Настройками бота и базой знаний
+  - Документами и отчётами
+"""
 import os
 import asyncio
 from contextlib import asynccontextmanager

py_service/app/models/models.py

@@ -1,3 +1,13 @@
+"""
+ORM-модели для service portal (SQLAlchemy 2.0).
+
+Основные таблицы:
+  - users: сотрудники (owner/engineer/technician)
+  - customers: клиенты
+  - objects: объекты обслуживания
+  - tasks/ incidents: задачи и инциденты
+  - blog/cases/ideas: контент
+"""
 from datetime import datetime
 from sqlalchemy import (
     Column, Integer, String, Boolean, Text, DateTime, Numeric, Date, BigInteger, SmallInteger, JSON, ForeignKey, CheckConstraint

py_service/app/routers/service_pages.py

@@ -1293,6 +1293,7 @@ BOT_SERVICE_URL = "http://127.0.0.1:8002"
 
 
 async def _proxy(method: str, path: str, body=None):
+    """Прокси запросов от service portal к max_bot API."""
     async with httpx.AsyncClient() as client:
         if body is not None:
             resp = await client.request(method, f"{BOT_SERVICE_URL}{path}", json=body)
@@ -1431,11 +1432,13 @@ async def proxy_bot_conversation_logs(conv_id: int, user: dict = Depends(get_cur
 
 @router.delete("/api/bot/conversations/{conv_id}")
 async def proxy_delete_conversation(conv_id: int, request: Request, user: dict = Depends(require_role("owner"))):
+    """Удаление диалога (каскадно: сообщения + логи). Доступно только owner."""
     return await _proxy("DELETE", f"/api/bot/conversations/{conv_id}")
 
 
 @router.delete("/api/bot/users/{user_id}")
 async def proxy_delete_bot_user(user_id: int, request: Request, user: dict = Depends(require_role("owner"))):
+    """Удаление пользователя бота (каскадно: диалоги + сообщения + логи). Заявки остаются. Доступно только owner."""
     return await _proxy("DELETE", f"/api/bot/users/{user_id}")