feat: Поддержка batch-обработки документов и умного парсинга S3 путей

Изменения в /api/n8n/documents/attach: ✅ Принимает массив документов (не одиночный объект) ✅ Умная обработка S3 путей: - /bucket/path → https://s3.twcstorage.ru/bucket/path - bucket/path → https://s3.twcstorage.ru/bucket/path - https://... → без изменений ✅ Поддержка обоих форматов полей: - file / file_url - filename / file_name ✅ Batch-обработка с детальной статистикой ✅ Возвращает результаты для каждого документа отдельно ✅ Логирование успешных и неуспешных операций Формат ответа: { total_processed: N, successful: M, failed: K, results: [...], errors: [...] } Тесты: - TEST_REAL_DATA.sh - тест с реальными данными из n8n - TEST_QUICK.sh - быстрые тесты Документация обновлена с примерами batch-обработки
2025-11-02 19:21:02 +03:00
parent e27280e675
commit efb0cd6f05
4 changed files with 318 additions and 104 deletions
--- a/DOCUMENT_ATTACH_API.md
+++ b/DOCUMENT_ATTACH_API.md
@@ -12,21 +12,47 @@ POST https://crm.clientright.ru/api/n8n/documents/attach

 ---

-## 📋 Параметры запроса
+## 📋 Формат входных данных

-### Обязательные:
-| Параметр | Тип | Описание | Пример |
-|----------|-----|----------|--------|
-| `contact_id` | string | ID контакта в vTiger | `"320096"` |
-| `project_id` | string | ID проекта (полиса) в vTiger | `"396874"` |
-| `file_url` | string | Полный URL файла в S3 | `"https://s3.twcstorage.ru/..."` |
-| `file_name` | string | Имя файла | `"boarding_pass.pdf"` |
+**Тип:** JSON массив документов

-### Опциональные:
-| Параметр | Тип | Описание | Пример |
-|----------|-----|----------|--------|
-| `ticket_id` | string | ID заявки в HelpDesk<br/>**Если указан → привязка к заявке**<br/>**Если не указан → привязка к проекту** | `"396935"` |
-| `file_type` | string | Описание типа документа | `"flight_delay_boarding_or_ticket"` |
+```json
+[
+  {
+    "claim_id": "CLM-2025-11-02-WNRZZZ",
+    "event_type": "delay_flight",
+    "contact_id": "320096",
+    "project_id": "396868",
+    "ticket_id": "396936",
+    "filename": "boarding_pass.pdf",
+    "file_type": "flight_delay_boarding_or_ticket",
+    "file": "/bucket/path/to/file.pdf"
+  }
+]
+```
+
+### Поля документа:
+
+| Параметр | Тип | Обязательно | Описание | Пример |
+|----------|-----|-------------|----------|--------|
+| `contact_id` | string | ✅ Да | ID контакта в vTiger | `"320096"` |
+| `project_id` | string | ✅ Да | ID проекта (полиса) в vTiger | `"396874"` |
+| `file` или `file_url` | string | ✅ Да | Путь к файлу в S3 (с/без хоста) | `"/bucket/path/file.pdf"` |
+| `filename` или `file_name` | string | ✅ Да | Имя файла | `"boarding_pass.pdf"` |
+| `ticket_id` | string | ⚠️ Опц. | ID заявки<br/>**Если указан → HelpDesk**<br/>**Если НЕ указан → Project** | `"396935"` |
+| `file_type` | string | ⚠️ Опц. | Тип документа | `"flight_delay_boarding_or_ticket"` |
+| `claim_id` | string | ⚠️ Опц. | ID заявки (для логирования) | `"CLM-2025-11-02-..."` |
+| `event_type` | string | ⚠️ Опц. | Тип события (для логирования) | `"delay_flight"` |
+
+### 🔧 Умная обработка путей:
+
+Эндпоинт автоматически определяет формат пути и добавляет хост S3 если нужно:
+
+| Входной формат | Обработка | Результат |
+|----------------|-----------|-----------|
+| `/bucket/path/file.pdf` | ➕ Добавляем хост | `https://s3.twcstorage.ru/bucket/path/file.pdf` |
+| `bucket/path/file.pdf` | ➕ Добавляем `/` и хост | `https://s3.twcstorage.ru/bucket/path/file.pdf` |
+| `https://s3.twcstorage.ru/...` | ✅ Уже полный URL | `https://s3.twcstorage.ru/...` |

 ---

@@ -58,76 +84,137 @@ POST https://crm.clientright.ru/api/n8n/documents/attach

 ## 📤 Примеры запросов

-### 1️⃣ Привязка к проекту (без заявки)
-
-Используется когда файл относится к полису в целом, но еще нет конкретной заявки.
+### 1️⃣ Один документ к заявке (реальный пример)

 ```bash
 curl -X POST "https://crm.clientright.ru/api/n8n/documents/attach" \
  -H "Content-Type: application/json" \
-  -d '{
+  -d '[
+  {
+    "claim_id": "CLM-2025-11-02-WNRZZZ",
+    "event_type": "delay_flight",
    "contact_id": "320096",
-    "project_id": "396874",
-    "file_url": "https://s3.twcstorage.ru/f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c/clientright/test/policy_scan.pdf",
-    "file_name": "policy_E1000-302538529.pdf",
-    "file_type": "Скан полиса ERV"
-  }'
+    "project_id": "396868",
+    "ticket_id": "396936",
+    "filename": "flight_delay_boarding_or_ticket.pdf",
+    "file_type": "flight_delay_boarding_or_ticket",
+    "file": "/f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c/crm2/CRM_Active_Files/Documents/HelpDesk/ЗАЯВКА_827_396936/flight_delay_boarding_or_ticket.pdf"
+  }
+]'
 ```

 **Ответ:**
 ```json
 {
  "success": true,
-  "result": {
-    "document_id": "15x396940",
-    "document_numeric_id": "396940",
-    "attached_to": "project",        // ✅ Привязан к проекту
-    "attached_to_id": "396874",
-    "file_name": "policy_E1000-302538529.pdf",
-    "file_type": "Скан полиса ERV",
-    "s3_bucket": "f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c",
-    "s3_key": "clientright/test/policy_scan.pdf",
-    "file_size": 125840,
-    "message": "Документ создан с правильными S3 метаданными и привязан к проекту"
-  }
+  "total_processed": 1,
+  "successful": 1,
+  "failed": 0,
+  "results": [
+    {
+      "document_id": "15x396941",
+      "document_numeric_id": "396941",
+      "attached_to": "ticket",
+      "attached_to_id": "396936",
+      "file_name": "flight_delay_boarding_or_ticket.pdf",
+      "file_type": "flight_delay_boarding_or_ticket",
+      "s3_bucket": "f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c",
+      "s3_key": "crm2/CRM_Active_Files/Documents/HelpDesk/ЗАЯВКА_827_396936/flight_delay_boarding_or_ticket.pdf",
+      "file_size": 85320,
+      "message": "Документ создан с правильными S3 метаданными и привязан к проекту"
+    }
+  ],
+  "errors": null
 }
 ```

 ---

-### 2️⃣ Привязка к заявке (HelpDesk)
-
-Используется когда файл относится к конкретной заявке (страховому случаю).
+### 2️⃣ Несколько документов за раз (batch)

 ```bash
 curl -X POST "https://crm.clientright.ru/api/n8n/documents/attach" \
  -H "Content-Type: application/json" \
-  -d '{
+  -d '[
+  {
    "contact_id": "320096",
-    "project_id": "396874",
-    "ticket_id": "396935",          // ✅ Указан ticket_id
-    "file_url": "https://s3.twcstorage.ru/f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c/clientright/test/boarding_pass.pdf",
-    "file_name": "boarding_pass_20251102.pdf",
-    "file_type": "flight_delay_boarding_or_ticket"
-  }'
+    "project_id": "396868",
+    "ticket_id": "396936",
+    "filename": "boarding_pass.pdf",
+    "file_type": "flight_delay_boarding_or_ticket",
+    "file": "/bucket/path/boarding_pass.pdf"
+  },
+  {
+    "contact_id": "320096",
+    "project_id": "396868",
+    "ticket_id": "396936",
+    "filename": "delay_confirmation.pdf",
+    "file_type": "flight_delay_confirmation",
+    "file": "/bucket/path/delay_confirmation.pdf"
+  }
+]'
 ```

 **Ответ:**
 ```json
 {
  "success": true,
-  "result": {
-    "document_id": "15x396941",
-    "document_numeric_id": "396941",
-    "attached_to": "ticket",         // ✅ Привязан к заявке
-    "attached_to_id": "396935",
-    "file_name": "boarding_pass_20251102.pdf",
-    "file_type": "flight_delay_boarding_or_ticket",
-    "s3_bucket": "f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c",
-    "s3_key": "clientright/test/boarding_pass.pdf",
-    "file_size": 85320,
-    "message": "Документ создан с правильными S3 метаданными и привязан к проекту"
+  "total_processed": 2,
+  "successful": 2,
+  "failed": 0,
+  "results": [
+    {
+      "document_id": "15x396941",
+      "attached_to": "ticket",
+      "file_name": "boarding_pass.pdf",
+      "...": "..."
+    },
+    {
+      "document_id": "15x396942",
+      "attached_to": "ticket",
+      "file_name": "delay_confirmation.pdf",
+      "...": "..."
+    }
+  ],
+  "errors": null
+}
+```
+
+---
+
+### 3️⃣ Привязка к проекту (без ticket_id)
+
+```bash
+curl -X POST "https://crm.clientright.ru/api/n8n/documents/attach" \
+  -H "Content-Type: application/json" \
+  -d '[
+  {
+    "contact_id": "320096",
+    "project_id": "396874",
+    "filename": "policy_scan.pdf",
+    "file_type": "Скан полиса ERV",
+    "file": "https://s3.twcstorage.ru/bucket/path/policy.pdf"
  }
+]'
+```
+
+**Ответ:**
+```json
+{
+  "success": true,
+  "total_processed": 1,
+  "successful": 1,
+  "failed": 0,
+  "results": [
+    {
+      "document_id": "15x396940",
+      "attached_to": "project",
+      "attached_to_id": "396874",
+      "file_name": "policy_scan.pdf",
+      "...": "..."
+    }
+  ],
+  "errors": null
 }
 ```