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

deploy/services/grouping.py

@@ -1,4 +1,13 @@
-"""Grouping service — match classified documents into contract groups."""
+"""
+Grouping service — match classified documents into contract groups.
+
+Архитектурное решение (Opus, Q4 + Q6):
+- Двухпроходный гибрид: LLM извлекает строки (classify.py), Python нормализует и группирует.
+- Нормализация номеров: uppercase + только буквы/цифры.
+  "МЭС-123-2024" == "МЭС 123/2024" после нормализации.
+- Группировка на бэкенде (не на фронте): Python regex/unicode надёжнее JS.
+- apply_groups(): создаёт contracts + supplements с авто-порядком по дате.
+"""
 import re
 from db import documents as db_docs
 from db import contracts as db_contracts
@@ -6,14 +15,29 @@ from db import supplements as db_supplements
 
 
 def normalize_number(num):
-    """Normalize contract number for matching: uppercase, only letters/digits."""
+    """
+    Нормализация номера договора для сравнения.
+    Убирает всё кроме букв и цифр, приводит к uppercase.
+    Пример: "МЭС-123-2024" → "МЭС1232024", "МЭС 123/2024" → "МЭС1232024".
+    """
     if not num:
         return ""
     return re.sub(r"[^A-Z0-9А-Я]", "", num.upper())
 
 
 def group_documents(batch_id):
-    """Group classified documents by contract. Returns list of groups."""
+    """
+    Сгруппировать классифицированные документы по контрактам.
+
+    Алгоритм:
+    1. Отделить contract от supplement/specification
+    2. Каждый contract → якорь группы
+    3. Для каждого supplement: найти contract по parent_number (нормализованный)
+    4. Несматченные → группа "__unresolved__"
+    5. Внутри группы сортировка по doc_date
+
+    Возвращает {ok, groups: [{contract_number, counterparty, documents: [...]}], total_docs}.
+    """
     docs = db_docs.list_by_batch(batch_id)
     classified = [d for d in docs if d.get("classify_status") == "classified"]
 
@@ -72,7 +96,17 @@ def group_documents(batch_id):
 
 
 def apply_groups(batch_id, groups_data):
-    """Apply confirmed groups: create contracts + supplements."""
+    """
+    Применить подтверждённые группы: создать contracts + supplements.
+
+    Вызывается из POST /api/apply-groups.
+    Для каждой группы (кроме __unresolved__):
+    1. Создать запись в contracts (number, client)
+    2. Для каждого документа создать supplement (type='initial' для первого, 'additional' для остальных)
+    3. Порядок supplements соответствует порядку документов в группе (сортировка по дате уже сделана)
+
+    Возвращает {ok, created: количество созданных supplements}.
+    """
     created = 0
     for g in groups_data:
         contract_number = g.get("contract_number", "")