negodiy/crm.clientright.ru
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2bb56342f4ff602907b2e59c06eb8a8006fdfebc
crm.clientright.ru/modules/OnlyOfficeTemplates/DESCRIPTION.md
Fedor 2bb56342f4 Add OnlyOfficeTemplates module
2026-02-16 09:27:19 +03:00

14 KiB
Raw Blame History

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 или внешний конфиг; модуль портативный.