v1.0.165: app_utils.js + detailed comments (Opus analysis) in classify/grouping/connection

deploy/db/connection.py

@@ -1,11 +1,22 @@
-"""Database connection — psycopg2 connection pool."""
+"""
+Database connection — psycopg2 connection pool.
+
+Архитектурное решение (Opus):
+- ThreadedConnectionPool(minconn=1, maxconn=10) — оптимально для ThreadingMixIn HTTP-сервера.
+  Каждый HTTP-запрос в отдельном потоке получает своё соединение из пула.
+- RealDictCursor для query() — возвращает dict с lowercase ключами (консистентно с Python API).
+- execute()/execute_returning() — для INSERT/UPDATE/DELETE с автокоммитом и откатом при ошибке.
+- Пул создаётся лениво (при первом запросе) через get_pool().
+"""
 import os
 import psycopg2
 import psycopg2.pool
 import psycopg2.extras
 
+# Глобальный пул соединений (singleton)
 _pool = None
 
+# Параметры подключения из переменных окружения (systemd Environment)
 DB_CONFIG = {
     "host": os.getenv("DB_HOST", "127.0.0.1"),
     "port": int(os.getenv("DB_PORT", "5432")),
@@ -16,6 +27,7 @@ DB_CONFIG = {
 
 
 def get_pool():
+    """Возвращает глобальный пул соединений. Создаёт при первом вызове."""
     global _pool
     if _pool is None:
         _pool = psycopg2.pool.ThreadedConnectionPool(
@@ -25,7 +37,10 @@ def get_pool():
 
 
 def query(sql, params=None):
-    """SELECT → list of dicts (lowercase keys)."""
+    """
+    SELECT → list[dict] с lowercase ключами.
+    Используется всеми db/*.py модулями для чтения данных.
+    """
     pool = get_pool()
     conn = pool.getconn()
     try:
@@ -38,7 +53,10 @@ def query(sql, params=None):
 
 
 def execute(sql, params=None):
-    """INSERT/UPDATE/DELETE → rowcount."""
+    """
+    INSERT/UPDATE/DELETE → количество затронутых строк.
+    Автокоммит. При ошибке — rollback и проброс исключения.
+    """
     pool = get_pool()
     conn = pool.getconn()
     try:
@@ -54,7 +72,10 @@ def execute(sql, params=None):
 
 
 def execute_returning(sql, params=None):
-    """INSERT/UPDATE/DELETE with RETURNING → first row dict."""
+    """
+    INSERT/UPDATE/DELETE с RETURNING → dict первой строки.
+    Используется для insert с автогенерацией UUID (gen_random_uuid()).
+    """
     pool = get_pool()
     conn = pool.getconn()
     try: