aiform_prod/TEST_ATTACH_DOCUMENT.md

# 📎 Тестирование привязки документов к проекту/заявке

## Эндпоинт
```
POST https://crm.clientright.ru/api/n8n/documents/attach
```

## 📋 Входные данные

### Обязательные поля:
- `contact_id` - ID контакта
- `project_id` - ID проекта
- `file_url` - URL файла в S3
- `file_name` - Имя файла

### Опциональные поля:
- `ticket_id` - ID заявки (если указан → привязываем к заявке)
- `file_type` - Описание документа (например: "flight_delay_boarding_or_ticket")

---

## 🧪 Тест 1: Привязка к проекту

```bash
curl -X POST "https://crm.clientright.ru/api/n8n/documents/attach" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "320096",
    "project_id": "396874",
    "file_url": "https://s3.twcstorage.ru/f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c/clientright/test/test_document.pdf",
    "file_name": "boarding_pass.pdf",
    "file_type": "flight_delay_boarding_or_ticket"
  }'
```

**Ожидаемый результат:**
```json
{
  "success": true,
  "result": {
    "document_id": "15x396940",
    "document_numeric_id": "396940",
    "attached_to": "project",
    "attached_to_id": "396874",
    "file_name": "boarding_pass.pdf",
    "file_type": "flight_delay_boarding_or_ticket",
    "s3_bucket": "f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c",
    "s3_key": "clientright/test/test_document.pdf",
    "file_size": 12345,
    "message": "Документ создан с правильными S3 метаданными и привязан к проекту"
  }
}
```

---

## 🧪 Тест 2: Привязка к заявке (HelpDesk)

```bash
curl -X POST "https://crm.clientright.ru/api/n8n/documents/attach" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "320096",
    "project_id": "396874",
    "ticket_id": "396935",
    "file_url": "https://s3.twcstorage.ru/f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c/clientright/test/test_document.pdf",
    "file_name": "flight_delay_confirmation.pdf",
    "file_type": "flight_delay_confirmation"
  }'
```

**Ожидаемый результат:**
```json
{
  "success": true,
  "result": {
    "document_id": "15x396941",
    "document_numeric_id": "396941",
    "attached_to": "ticket",
    "attached_to_id": "396935",
    "file_name": "flight_delay_confirmation.pdf",
    "file_type": "flight_delay_confirmation",
    "s3_bucket": "f9825c87-4e3558f6-f9b6-405c-ad3d-d1535c49b61c",
    "s3_key": "clientright/test/test_document.pdf",
    "file_size": 12345,
    "message": "Документ создан с правильными S3 метаданными и привязан к проекту"
  }
}
```

---

## 📊 Логика работы

1. **Если `ticket_id` НЕ указан:**
   - Документ создается в vTiger CRM (модуль Documents)
   - Привязывается к **Project** (проекту)
   - `attached_to = "project"`

2. **Если `ticket_id` указан:**
   - Документ создается в vTiger CRM (модуль Documents)
   - Привязывается к **HelpDesk** (заявке)
   - `attached_to = "ticket"`

3. **S3 метаданные:**
   - Автоматически обновляются в базе vTiger
   - `filelocationtype = 'E'` (External URL)
   - Сохраняются `s3_bucket`, `s3_key`, `file_size`

---

## 🔍 Где смотреть логи

### Backend логи:
```bash
docker-compose logs -f backend | grep "Attaching document"
```

### CRM логи:
```bash
tail -f /var/www/fastuser/data/www/crm.clientright.ru/logs/upload_documents.log
```

---

## ✅ Готово!

Эндпоинт готов к интеграции в n8n workflow!