# OnlyOfficeTemplates — подробное описание модуля ## Назначение Модуль **OnlyOfficeTemplates** для ClientRight CRM (Vtiger-based) предназначен для: - создания и хранения DOCX-шаблонов документов в S3; - редактирования шаблонов в веб-интерфейсе через OnlyOffice Document Editor (по аналогии с PDFMaker: слева метаданные, справа редактор); - генерации документов по шаблону с подстановкой полей записи и связанных модулей (плейсхолдеры `{{field}}`, `{{ModuleName__field}}`); - выдачи результата в формате **PDF** (через OnlyOffice Conversion API) или **DOCX**; - скачивания сгенерированного файла или сохранения в модуль «Документы» CRM. Модуль портативный: конфигурация через переменные окружения или внешний конфиг, без жёсткой привязки к окружению. --- ## Возможности ### Хранение шаблонов - Шаблоны хранятся в **S3-совместимом хранилище** по пути: `{OOT_S3_PREFIX}/templates/{template_id}/{имя_файла}.docx` (по умолчанию `OOT_S3_PREFIX` = `crm2/OnlyOfficeTemplates`). - Метаданные — в таблице БД `vtiger_oot_templates`: id, name, module, s3_key, file_name, owner, created_at. ### Редактирование шаблонов (как в PDFMaker) - **Список шаблонов** (Инструменты → Шаблоны документов): таблица с именем (ссылка на редактирование), модулем, файлом, датой создания. - **Добавить шаблон:** создаётся черновик, открывается экран редактирования: - **Слева:** форма — название шаблона, выбор модуля CRM, кнопки «Сохранить» / «Отмена». - **Справа:** OnlyOffice Document Editor в iframe; документ загружается с нашего сервера (экшен GetDocument), при сохранении/закрытии OnlyOffice Document Server отправляет файл на callback, мы сохраняем его в S3 и обновляем запись в БД. - **Загрузить файл:** альтернативный способ — форма с полями «Название», «Модуль» и выбором DOCX-файла; отправка в экшен UploadTemplate (загрузка в S3 и запись в БД). - Редактирование существующего шаблона: по клику на имя в списке открывается тот же экран с подставленными метаданными и документом из S3. ### Генерация документов по шаблону - На **карточке записи** (любой entity-модуль) в боковой панели отображается виджет OnlyOfficeTemplates: - выбор шаблона (по текущему модулю записи); - выбор формата: PDF или DOCX; - кнопки «Скачать» и «Сохранить в Документы». - Подстановка в шаблоне: - поля текущей записи: `{{fieldname}}`; - поля связанных модулей: `{{ModuleName__fieldname}}` (например `{{Account__accountname}}`). - Реализация: загрузка DOCX из S3, подстановка плейсхолдеров (PHPWord), при необходимости конвертация в PDF через OnlyOffice Conversion API, затем отдача файла или сохранение в Документы (в т.ч. в S3). --- ## Требования - **PHP:** расширения zip, xml, curl (или allow_url_fopen для Conversion API). - **Composer:** пакеты `phpoffice/phpword`, `aws/aws-sdk-php` (как правило, уже в корне проекта). - **S3:** доступ к S3-совместимому хранилищу (ключ, секрет, endpoint, bucket). - **OnlyOffice (опционально):** - **Conversion API** — для выдачи PDF (URL в `OOT_ONLYOFFICE_CONVERT_URL` / `ONLYOFFICE_CONVERT_URL`). - **Document Server** — для экрана редактирования шаблона (URL в `ONLYOFFICE_DOCUMENT_SERVER` / `OOT_ONLYOFFICE_DOCUMENT_SERVER`). Document Server должен иметь доступ по HTTP(S) к CRM (загрузка документа и callback). --- ## Установка 1. Скопировать в целевую CRM: - `modules/OnlyOfficeTemplates/` (все файлы); - `layouts/v7/modules/OnlyOfficeTemplates/` (все шаблоны и ресурсы). 2. Настроить конфигурацию (см. ниже). 3. Выполнить установку БД и виджетов: - **Рекомендуется:** из корня CRM выполнить `php modules/OnlyOfficeTemplates/install.php` или открыть в браузере соответствующий URL с правами администратора. - Альтернатива: упаковать модуль в zip с `manifest.xml` и импортировать через Module Manager. 4. При необходимости перегенерировать кэш меню (например `parent_tabdata.php`), чтобы пункт «Шаблоны документов» отображался в разделе «Инструменты». --- ## Конфигурация Модуль читает настройки в следующем порядке. ### 1. Внешний конфиг Если существует файл `crm_extensions/file_storage/config.php` и в нём возвращается массив с ключом `s3`, используются данные S3 оттуда. Имя бакета берётся из `s3['bucket']`, при отсутствии — из `bucket`, `s3_bucket` в корне массива или из переменной окружения `S3_BUCKET`. ### 2. Переменные окружения Поддерживаются два способа загрузки переменных: - **EnvLoader** (если есть `crm_extensions/shared/EnvLoader.php`): загружается файл `crm_extensions/.env`. Переменные попадают в `$_ENV` и в массив EnvLoader (модуль читает их через вспомогательную функцию, а не только через `getenv()`). - **getenv()** — если переменные заданы в окружении веб-сервера. Используемые переменные: | Переменная | Описание | |------------|----------| | `S3_ACCESS_KEY` | Ключ доступа S3 | | `S3_SECRET_KEY` | Секретный ключ S3 | | `S3_ENDPOINT` | URL эндпоинта S3 (напр. `https://s3.twcstorage.ru`) | | `S3_BUCKET` | Имя бакета S3 | | `S3_REGION` | Регион (по умолчанию `ru-1`) | | `OOT_S3_PREFIX` | Префикс папки модуля в S3 (по умолчанию `crm2/OnlyOfficeTemplates`) | | `OOT_ONLYOFFICE_CONVERT_URL` | URL OnlyOffice Conversion API (для PDF) | | `ONLYOFFICE_CONVERT_URL` | То же, альтернативное имя | | `OOT_ONLYOFFICE_DOCUMENT_SERVER` | URL OnlyOffice Document Server (для редактора шаблонов) | | `ONLYOFFICE_DOCUMENT_SERVER` | То же, альтернативное имя | | `OOT_DOCUMENT_SECRET` | Секрет для подписи URL документа (рекомендуется в продакшене) | | `OOT_DOCUMENTS_S3_PREFIX` | Префикс в S3 для файлов, сохраняемых в Документы (по умолчанию `crm2/CRM_Active_Files/Documents`) | Без Conversion API генерация PDF недоступна (только DOCX). Без Document Server экран редактирования с OnlyOffice недоступен, но остаётся загрузка готового DOCX через «Загрузить файл». --- ## Структура файлов модуля - **config.php** — загрузка конфигурации (внешний конфиг + .env), функция `OnlyOfficeTemplates_getConfig()` и вспомогательная `OnlyOfficeTemplates_env()` для чтения переменных из .env/EnvLoader. - **OnlyOfficeTemplates.php** — обработчик vtlib (установка/удаление таблиц, добавление/удаление виджета на карточках). - **schema.xml** — описание таблиц `vtiger_oot_templates`, `vtiger_oot_templates_seq`. - **models/OnlyOfficeTemplates_Model.php** — список шаблонов по модулю, получение шаблона по id, конфиг. - **resources/S3Helper.php** — работа с S3 (ключи шаблонов/temp, загрузка/скачивание). - **resources/MergeService.php** — подстановка плейсхолдеров в DOCX (PHPWord). - **resources/ConvertService.php** — конвертация DOCX → PDF через OnlyOffice Conversion API. - **actions/Install.php** — установка через браузер. - **actions/UploadTemplate.php** — загрузка DOCX (POST: name, module_name, file) и сохранение в S3 и БД. - **actions/CreateDraft.php** — создание черновика шаблона и редирект на экран редактирования. - **actions/SaveMetadata.php** — сохранение имени и модуля шаблона, редирект на Edit или List. - **actions/GetDocument.php** — отдача DOCX для OnlyOffice Document Server (из S3 или пустой документ); опциональная проверка токена (OOT_DOCUMENT_SECRET). - **actions/OnlyOfficeCallback.php** — приём callback от OnlyOffice Document Server при сохранении документа, скачивание файла по переданному URL и сохранение в S3, обновление записи в `vtiger_oot_templates`. - **actions/CreateFromTemplate.php** — генерация документа по шаблону (merge → опционально PDF → скачать или сохранить в Документы). - **views/List.php**, **views/Edit.php**, **views/AddTemplate.php**, **views/GetTemplateActions.php** — представления списка, редактирования (форма + OnlyOffice), загрузки файла и виджета на карточке. - **layouts/v7/modules/OnlyOfficeTemplates/** — шаблоны Smarty (List.tpl, Edit.tpl, AddTemplate.tpl, GetTemplateActions.tpl). - **languages/** — языковые строки (ru_ru, en_us). --- ## База данных - **vtiger_oot_templates:** id, name, module, s3_key, file_name, owner, created_at (и при необходимости settings в формате JSON). - **vtiger_oot_templates_seq:** служебная таблица для генерации id при необходимости. Регистрация модуля в меню: запись в `vtiger_tab` (например parent Tools), в `vtiger_parenttabrel`, в `vtiger_profile2tab` для прав доступа. Пункт меню кэшируется в `parent_tabdata.php` — при отсутствии пункта может потребоваться перегенерация кэша. --- ## Безопасность - **GetDocument:** вызывается OnlyOffice Document Server без сессии пользователя. При заданном `OOT_DOCUMENT_SECRET` в URL документа добавляется подпись (HMAC), проверяемая в GetDocument; без секрета доступ по ссылке возможен для любого, кто знает template_id. - **OnlyOfficeCallback:** вызывается только Document Server; проверка прав пользователя не выполняется, идентификация по ключу документа (template id). В продакшене целесообразно ограничить доступ к callback по сети (например, только с хоста Document Server). - **UploadTemplate:** требуется право редактирования настроек (`Settings`, `Edit`) или иная выбранная при интеграции проверка. --- ## Версии и совместимость - Модуль разработан для CRM на базе Vtiger (ClientRight), интерфейс v7. - Зависимости: PHP 7.x+, PHPWord, AWS SDK для PHP, S3-совместимое хранилище; OnlyOffice — опционально. --- ## Краткое описание для репозитория (Gitea) **OnlyOfficeTemplates** — модуль ClientRight CRM для создания и хранения DOCX-шаблонов в S3, редактирования их в OnlyOffice Document Editor (интерфейс как в PDFMaker: слева метаданные, справа редактор с сохранением в S3 по callback), генерации документов по шаблону с подстановкой полей записи и связанных модулей, выдачи в PDF (через OnlyOffice Conversion API) или DOCX и сохранения в Документы. Конфигурация через .env или внешний конфиг; модуль портативный.