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