# CRM Extensions - Полная документация

## 📋 Обзор изменений

Этот документ содержит полное описание всех изменений, внесенных в CRM систему для интеграции с WhatsApp, Telegram, Nextcloud и AI Drawer.

## 🗂️ Структура проекта

```
crm_extensions/
├── README.md                          # Эта документация
├── .env                               # Конфигурация (секретные данные)
├── nextcloud_api.php                  # API для Nextcloud интеграции
├── file_storage/                      # Файловое хранилище
│   ├── NextcloudClient.php           # Класс для работы с Nextcloud
│   ├── api/
│   │   └── prepare_edit.php         # API для подготовки файлов к редактированию
│   └── n8n_migration_clean.sh        # Скрипт для n8n миграции
└── logs/                              # Логи системы
```

## 🔧 Основные компоненты

### 1. AI Drawer (Умный ассистент)

**Файлы:**
- `/layouts/v7/resources/css/ai-drawer.css` - Стили
- `/layouts/v7/resources/js/ai-drawer-simple.js` - Основная логика
- `/ai_drawer_improvements.js` - Улучшения

**Подключение в Header.tpl:**
```smarty
{* AI Drawer - подключение внешних файлов только для авторизованных пользователей *}
{if $CURRENT_USER_MODEL}
<link rel="stylesheet" href="layouts/v7/resources/css/ai-drawer.css?v=2.1">
<script src="layouts/v7/resources/js/ai-drawer-simple.js?v=2.8"></script>
<script src="ai_drawer_improvements.js"></script>
{/if}
```

**Инициализация:**
```javascript
// В конце ai-drawer-simple.js
document.addEventListener('DOMContentLoaded', function() {
    console.log('AI Drawer: DOM loaded, initializing...');
    window.aiDrawer = new AIDrawer();
    console.log('AI Drawer: Initialized successfully');
});
```

### 2. Nextcloud Editor (Редактирование документов)

**Файлы:**
- `/layouts/v7/lib/nextcloud-editor.js` - JavaScript функция
- `/crm_extensions/nextcloud_api.php` - API endpoint
- `/crm_extensions/file_storage/NextcloudClient.php` - Класс для работы с Nextcloud

**Подключение в Header.tpl:**
```smarty
<!-- Подключаем функцию редактирования в Nextcloud -->
<script src="{vresource_url('layouts/v7/lib/nextcloud-editor.js')}"></script>
```

**Использование в шаблонах:**
```smarty
<a href="javascript:void(0)" onclick="editInNextcloud({$RECORD_ID}, '{$DOCUMENT_RECORD_MODEL->get('filename')|escape:'javascript'}')">
    <i title="Редактировать в Nextcloud" class="fa fa-cloud" style="color: #007cba;"></i>
</a>
```

### 3. WhatsApp Integration

**Файлы:**
- `/include/utils/WhatsApp.php` - Отправка сообщений
- `/wappi.php` - Webhook для входящих сообщений

**Основные изменения:**

1. **Отправка файлов (WhatsApp.php):**
```php
// Проверка вложений
$result = $adb->pquery("
    SELECT a.attachmentsid, a.path, a.storedname, n.filename, n.filelocationtype, n.s3_key
    FROM vtiger_seattachmentsrel sar
    JOIN vtiger_attachments a ON sar.attachmentsid = a.attachmentsid
    JOIN vtiger_notes n ON a.attachmentsid = n.notesid
    WHERE sar.crmid = ? AND n.filestatus = 1
", array($recordId));
```

2. **Входящие сообщения (wappi.php):**
```php
// Приоритет контактов над организациями
$result = $adb->pquery("
    SELECT p.crmid, p.setype
    FROM vtiger_pbxmanager_phonelookup p
    WHERE p.phonenumber = ?
    ORDER BY CASE WHEN p.setype = 'Contacts' THEN 1 ELSE 2 END, p.crmid DESC
    LIMIT 1
", array($phone));

// Использование caption для файлов
if (isset($data['messages']['caption']) && !empty($data['messages']['caption'])) {
    $message = $data['messages']['caption'];
}
```

### 4. Telegram Integration

**Файлы:**
- `/include/utils/Telegram.php` - Отправка сообщений
- `/telegram.php` - Webhook для входящих сообщений

**Основные изменения:**

1. **Отправка файлов (Telegram.php):**
```php
// Скачивание файла из S3 во временный файл
$tempFile = tempnam(sys_get_temp_dir(), 'telegram_file_');
file_put_contents($tempFile, $fileContent);

// Отправка через curl_file_create
$postData['document'] = new CURLFile($tempFile, $mimeType, $filename);
```

2. **Входящие сообщения (telegram.php):**
```php
// Поиск по tgid в поле phone
$result = $adb->pquery("
    SELECT cd.contactid
    FROM vtiger_contactdetails cd
    WHERE cd.phone = ? AND cd.contactid IN (
        SELECT crmid FROM vtiger_crmentity WHERE setype = 'Contacts'
    )
    LIMIT 1
", array($tgid));
```

### 5. Управление комментариями

**Файлы:**
- `/layouts/v7/modules/Vtiger/Comment.tpl` - Шаблон комментария
- `/layouts/v7/modules/Vtiger/RecentComments.tpl` - Виджет комментариев
- `/layouts/v7/modules/Vtiger/resources/Detail.js` - JavaScript логика
- `/modules/ModComments/views/DeleteAjax.php` - Серверная обработка

**Особенности:**
- Кнопка удаления видна всем пользователям
- Разная логика для виджета (перезагрузка) и полного списка (анимация)
- Подтверждение удаления через confirm()

### 6. Управление документами

**Файлы:**
- `/layouts/v7/modules/Documents/DocumentsRelatedList.tpl` - Список документов
- `/layouts/v7/modules/Vtiger/DocumentsSummaryWidgetContents.tpl` - Виджет документов
- `/layouts/v7/modules/Documents/DetailViewActions.tpl` - Детальный просмотр
- `/modules/Documents/views/DeleteAjax.php` - Серверная обработка

**Кнопки:**
- **Редактировать** - редактирование в CRM
- **Отвязать** - отвязка от контакта
- **Удалить** - полное удаление документа
- **Просмотр** - предварительный просмотр
- **Скачать** - скачивание файла
- **Nextcloud** - редактирование в Nextcloud

## 🔐 Конфигурация

### .env файл
```bash
# S3 Storage (TWC Storage)
S3_ACCESS_KEY=your_access_key
S3_SECRET_KEY=your_secret_key
S3_ENDPOINT=https://s3.twcstorage.ru
S3_BUCKET=your_bucket_name

# Nextcloud
NEXTCLOUD_URL=https://office.clientright.ru
NEXTCLOUD_USERNAME=admin
NEXTCLOUD_PASSWORD=your_password

# WhatsApp API
WAPPI_API_KEY=your_wappi_key
WAPPI_API_URL=https://wappi.pro/api

# Telegram Bot
TELEGRAM_BOT_TOKEN=your_bot_token
```

## 📝 Логирование

**Файлы логов:**
- `wa_outbound.log` - Исходящие WhatsApp сообщения
- `wa_inbound.log` - Входящие WhatsApp сообщения
- `tg_outbound.log` - Исходящие Telegram сообщения
- `debug.log` - Общие отладочные сообщения
- `n8n_migration_clean.log` - Логи миграции n8n

## 🚀 Развертывание

### 1. Копирование файлов
```bash
# Основные файлы уже на месте
cp crm_extensions/nextcloud_api.php /var/www/fastuser/data/www/crm.clientright.ru/crm_extensions/
cp layouts/v7/lib/nextcloud-editor.js /var/www/fastuser/data/www/crm.clientright.ru/layouts/v7/lib/
```

### 2. Настройка прав
```bash
chmod 755 /var/www/fastuser/data/www/crm.clientright.ru/crm_extensions/file_storage/n8n_migration_clean.sh
chmod 644 /var/www/fastuser/data/www/crm.clientright.ru/crm_extensions/.env
```

### 3. Проверка работы
1. Откройте CRM в браузере
2. Проверьте консоль на ошибки (F12)
3. Убедитесь, что AI Drawer появляется в правом нижнем углу
4. Протестируйте кнопки документов и комментариев

## 🔧 Устранение неполадок

### AI Drawer не появляется
1. Проверьте консоль браузера на ошибки
2. Убедитесь, что пользователь авторизован
3. Проверьте загрузку файлов CSS и JS

### Nextcloud не работает
1. Проверьте доступность `nextcloud_api.php`
2. Убедитесь в правильности учетных данных в .env
3. Проверьте логи ошибок PHP

### WhatsApp/Telegram не отправляют файлы
1. Проверьте права доступа к S3
2. Убедитесь в правильности API ключей
3. Проверьте логи отправки

## 📞 Поддержка

При возникновении проблем:
1. Проверьте логи в соответствующих файлах
2. Убедитесь в правильности конфигурации .env
3. Проверьте права доступа к файлам
4. Обратитесь к разработчику с описанием проблемы

---

**Дата создания:** 24 сентября 2025  
**Версия:** 1.0  
**Статус:** Производственная среда