negodiy/crm.clientright.ru

Files

Fedor 01c4fe80b5 chore: snapshot current working tree changes

Save all currently accumulated repository changes as a backup snapshot for Gitea so no local work is lost.

2026-03-26 14:19:01 +03:00

38 KiB

Raw Blame History

📘 МОДУЛЬ DocTemplate - ПОЛНЫЙ МАНУАЛ

Версия: 1.0
Дата: 2026-01-22
Статус: План реализации

📋 СОДЕРЖАНИЕ

Обзор модуля
Архитектура
Структура модуля
База данных
Процесс работы
Интерфейс пользователя
Технические детали
Интеграция с PDFMaker
План реализации

🎯 ОБЗОР МОДУЛЯ

Назначение

Модуль DocTemplate предназначен для генерации документов (DOCX) из шаблонов Nextcloud с автоматическим заполнением переменных данными из модулей CRM.

Основные возможности

✅ Создание и редактирование шаблонов документов
✅ Автоматическое заполнение переменных данными из CRM
✅ Поддержка связанных модулей
✅ Интеграция с OnlyOffice для редактирования
✅ Сохранение готовых документов в S3
✅ Двухпанельный редактор (переменные + OnlyOffice)

Аналогия

Модуль аналогичен PDFMaker, но работает с DOCX файлами вместо PDF и использует шаблоны из Nextcloud.

🏗️ АРХИТЕКТУРА

Общая схема

┌─────────────────────────────────────────────────────────────┐
│                    NEXTCLOUD                                │
│  /Templates/                                                │
│    ├── pretenziya.docx          ← ФИЗИЧЕСКИЕ ФАЙЛЫ          │
│    ├── iskovoe_zayavlenie.docx                              │
│    └── soglashenie.docx                                     │
└─────────────────────────────────────────────────────────────┘
                          ▲
                          │ WebDAV (скачивание/загрузка)
                          │
┌─────────────────────────────────────────────────────────────┐
│              CRM MODULE DocTemplate                         │
│                                                             │
│  База данных:                                               │
│  ┌─────────────────────────────────────┐                   │
│  │ vtiger_doctemplate                 │                   │
│  │   - templateid                      │                   │
│  │   - templatename: "Претензия"      │                   │
│  │   - filename: "pretenziya.docx"     │ ← Ссылка          │
│  │   - module: "Project"              │                   │
│  │   - mapping: {                      │                   │
│  │       "CLIENT_NAME": "$PROJECT_..." │                   │
│  │     }                               │                   │
│  └─────────────────────────────────────┘                   │
│                                                             │
│  Процесс генерации:                                         │
│  1. Получить метаданные из БД                               │
│  2. Скачать шаблон из Nextcloud                             │
│  3. Получить данные записи (CRMEntity)                      │
│  4. Заполнить переменные по маппингу                        │
│  5. Сохранить в S3                                          │
│  6. Открыть в OnlyOffice                                    │
└─────────────────────────────────────────────────────────────┘

Разделение ответственности

Nextcloud: Хранение физических файлов шаблонов (DOCX)
CRM: Метаданные, маппинг переменных, логика генерации
S3: Хранение готовых документов
OnlyOffice: Редактирование шаблонов и готовых документов

📁 СТРУКТУРА МОДУЛЯ

modules/DocTemplate/
├── DocTemplate.php                    # Основной класс модуля
├── schema.xml                         # Схема БД (таблицы)
├── language/                          # Языковые файлы
│   └── ru_ru.lang.php
├── models/                            # Модели
│   ├── Module.php                     # Модель модуля
│   ├── Record.php                     # Модель записи
│   ├── Template.php                   # Модель шаблона
│   ├── TemplateGenerator.php          # Генератор документов
│   ├── VariableProcessor.php          # Обработчик переменных
│   ├── VariableExtractor.php          # Извлечение переменных из DOCX
│   └── FieldMapper.php                # Маппер полей
├── views/                             # Представления
│   ├── List.php                       # Список шаблонов
│   ├── Detail.php                     # Детальный вид шаблона
│   ├── Edit.php                       # Редактирование шаблона (двухпанельный)
│   └── Create.php                     # Создание шаблона
├── actions/                           # Действия
│   ├── GenerateDocument.php           # Генерация документа
│   ├── ListTemplates.php              # Список шаблонов для модуля
│   ├── ExtractVariables.php           # Извлечение переменных из DOCX
│   ├── SaveMapping.php                # Сохранение маппинга
│   ├── GetModuleFields.php            # Получение списка полей модуля
│   ├── SaveTemplateContent.php        # Сохранение содержимого шаблона
│   └── OnlyOfficeCallback.php         # Callback от OnlyOffice
├── resources/                         # Ресурсы
│   ├── DocTemplate.js                 # JS для UI
│   ├── DocTemplate.css                # Стили
│   └── images/                        # Иконки
└── helpers/                           # Вспомогательные классы
    └── NextcloudClient.php            # Клиент Nextcloud (WebDAV)

🗄️ БАЗА ДАННЫХ

Таблица: `vtiger_doctemplate`

Основная таблица для хранения шаблонов:

CREATE TABLE `vtiger_doctemplate` (
  `templateid` int(11) NOT NULL AUTO_INCREMENT,
  `templatename` varchar(255) NOT NULL,           -- "Претензия"
  `filename` varchar(255) NOT NULL,               -- "pretenziya.docx"
  `module` varchar(100) NOT NULL,                  -- "Project"
  `description` text,                              -- Описание шаблона
  `mapping` longtext,                               -- JSON маппинг переменных
  `nextcloud_path` varchar(255) DEFAULT '/Templates/',  -- Путь в Nextcloud
  `is_active` tinyint(1) DEFAULT '1',
  `owner` int(11) NOT NULL,
  `createdtime` datetime NOT NULL,
  `modifiedtime` datetime NOT NULL,
  `deleted` tinyint(1) DEFAULT '0',
  PRIMARY KEY (`templateid`)
) ENGINE=InnoDB;

Пример записи:

{
  "templateid": 1,
  "templatename": "Претензия",
  "filename": "pretenziya.docx",
  "module": "Project",
  "description": "Шаблон претензии для проектов",
  "mapping": {
    "CLIENT_NAME": "$PROJECT_PROJECTNAME$",
    "DATE": "$PROJECT_CREATEDTIME$",
    "AMOUNT": "$PROJECT_CF_1885$",
    "CONTACT_NAME": "$CONTACTS_LASTNAME$"
  },
  "nextcloud_path": "/Templates/"
}

Таблица: `vtiger_doctemplate_seq`

Счетчик для генерации ID:

CREATE TABLE `vtiger_doctemplate_seq` (
  `id` int(11) NOT NULL DEFAULT '1'
) ENGINE=InnoDB;

Таблица: `vtiger_doctemplate_settings`

Настройки шаблона:

CREATE TABLE `vtiger_doctemplate_settings` (
  `templateid` int(11) NOT NULL,
  `output_folder` varchar(255),              -- Папка для сохранения готовых документов
  `file_naming` varchar(255),                -- Правило именования файлов
  `auto_open` tinyint(1) DEFAULT '1',        -- Автоматически открывать после генерации
  `owner` int(11) NOT NULL,
  `sharingtype` char(7) DEFAULT 'public',
  PRIMARY KEY (`templateid`)
) ENGINE=InnoDB;

🔄 ПРОЦЕСС РАБОТЫ

1. Создание шаблона

Сценарий A: Создание пустого шаблона

1. Пользователь создает запись шаблона в CRM
   - Название: "Претензия"
   - Модуль: Project
   - Имя файла: pretenziya.docx
   
2. CRM создает пустой DOCX через PHPWord
   
3. CRM загружает файл в Nextcloud /Templates/
   
4. Открывается редактор (двухпанельный интерфейс)

Сценарий B: Загрузка существующего файла

1. Пользователь загружает DOCX файл через интерфейс CRM
   
2. CRM загружает файл в Nextcloud /Templates/
   
3. CRM создает запись в БД
   
4. CRM автоматически находит переменные в документе
   
5. Показывается форма настройки маппинга

2. Редактирование шаблона

Двухпанельный интерфейс:

┌─────────────────────────────────────────────────────────┐
│  Редактирование: Претензия            [💾 Сохранить]   │
├──────────────┬──────────────────────────────────────────┤
│              │                                          │
│ ПЕРЕМЕННЫЕ   │  ONLYOFFICE РЕДАКТОР                     │
│              │  ┌────────────────────────────────────┐ │
│ [🔍 Поиск]   │  │                                    │ │
│              │  │  ПРЕТЕНЗИЯ                        │ │
│ Прямые поля: │  │                                    │ │
│ • projectname│  │  От: {CLIENT_NAME}                 │ │
│ • createdtime│  │  Дата: {DATE}                      │ │
│ • cf_1885    │  │                                    │ │
│              │  │  Сумма: {AMOUNT}                   │ │
│ Связанные:   │  │                                    │ │
│ • Contacts   │  │                                    │ │
│   - lastname │  └────────────────────────────────────┘ │
│              │                                          │
│ Функции:     │                                          │
│ • formatDate │                                          │
│              │                                          │
└──────────────┴──────────────────────────────────────────┘

Как работает:

Левая панель: Список полей модуля (через PDFMaker_Fields_Model)
Правая панель: OnlyOffice редактор в iframe
Клик по переменной: Копируется в буфер обмена → вставить в документ (Ctrl+V)
Сохранение: Документ сохраняется в Nextcloud → CRM находит переменные → настройка маппинга

3. Настройка маппинга

После сохранения шаблона CRM автоматически:

Скачивает DOCX из Nextcloud
Парсит через PHPWord
Находит все переменные {VAR_NAME}
Показывает форму настройки:

┌─────────────────────────────────────────────────────────┐
│  Настройка маппинга для "Претензия"                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Найдены переменные:                                    │
│                                                         │
│  Переменная      →  Поле модуля                         │
│  ┌─────────────┐    ┌──────────────────────────────┐  │
│  │ CLIENT_NAME │ →  │ $PROJECT_PROJECTNAME$        │  │
│  │ DATE        │ →  │ $PROJECT_CREATEDTIME$        │  │
│  │ AMOUNT      │ →  │ $PROJECT_CF_1885$            │  │
│  └─────────────┘    └──────────────────────────────┘  │
│                                                         │
│  [+ Добавить переменную]                                │
│                                                         │
│  [💾 Сохранить маппинг]                                 │
│                                                         │
└─────────────────────────────────────────────────────────┘

4. Генерация документа

Процесс:

1. Пользователь в детальном виде записи (Project, HelpDesk, etc.)
   нажимает кнопку "Создать из шаблона"
   
2. Показывается список шаблонов для модуля
   
3. Пользователь выбирает шаблон
   
4. CRM выполняет:
   a. Получает метаданные шаблона из БД
   b. Скачивает шаблон из Nextcloud (WebDAV)
   c. Получает данные записи через CRMEntity
   d. Заполняет переменные по маппингу
   e. Сохраняет готовый документ в S3
   f. Открывает документ в OnlyOffice

Алгоритм генерации:

// Псевдокод
function generate($module, $recordId, $templateId) {
    // 1. Получить шаблон
    $template = getTemplate($templateId);
    
    // 2. Скачать из Nextcloud
    $docxContent = downloadFromNextcloud($template->filename);
    
    // 3. Получить данные записи (как PDFMaker)
    $focus = CRMEntity::getInstance($module);
    $focus->retrieve_entity_info($recordId, $module);
    
    // 4. Построить переменные из маппинга
    $variables = buildVariables($template->mapping, $focus, $module);
    
    // 5. Заменить переменные в DOCX
    $filledContent = replaceVariables($docxContent, $variables);
    
    // 6. Сохранить в S3
    $filePath = saveToS3($filledContent, $module, $recordId);
    
    // 7. Вернуть URL для OnlyOffice
    return getOnlyOfficeUrl($filePath);
}

🎨 ИНТЕРФЕЙС ПОЛЬЗОВАТЕЛЯ

1. Список шаблонов (List View)

┌─────────────────────────────────────────────────────────┐
│  Шаблоны документов                    [+ Создать]      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Название        │ Модуль    │ Файл              │ Действия│
│  ─────────────────────────────────────────────────────  │
│  Претензия       │ Project   │ pretenziya.docx   │ [✏️][👁️]│
│  Исковое заявл. │ Project   │ isk.docx          │ [✏️][👁️]│
│  Соглашение      │ Contacts  │ soglashenie.docx  │ [✏️][👁️]│
│                                                         │
└─────────────────────────────────────────────────────────┘

2. Детальный вид шаблона

┌─────────────────────────────────────────────────────────┐
│  Претензия                          [Редактировать] [×]│
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Модуль: Project                                        │
│  Файл: pretenziya.docx                                  │
│  Путь: /Templates/                                      │
│                                                         │
│  [📝 Редактировать содержимое]                           │
│     → Откроет двухпанельный редактор                    │
│                                                         │
│  ────────────────────────────────────────────────────  │
│                                                         │
│  Маппинг переменных:                                    │
│  ┌──────────────────────────────────────────────────┐ │
│  │ CLIENT_NAME → $PROJECT_PROJECTNAME$              │ │
│  │ DATE → $PROJECT_CREATEDTIME$                     │ │
│  │ AMOUNT → $PROJECT_CF_1885$                       │ │
│  └──────────────────────────────────────────────────┘ │
│                                                         │
│  [+ Добавить переменную]                                │
│                                                         │
│  [💾 Сохранить]                                        │
│                                                         │
└─────────────────────────────────────────────────────────┘

3. Кнопка в модулях CRM

В детальном виде модулей (Project, HelpDesk, Contacts) добавляется кнопка:

[📄 Создать из шаблона]

При клике открывается диалог выбора шаблона.

🔧 ТЕХНИЧЕСКИЕ ДЕТАЛИ

1. Формат переменных

В шаблоне DOCX:

Пользователь пишет переменные в формате:

{CLIENT_NAME}
{DATE}
{AMOUNT}

В маппинге CRM:

Используется формат PDFMaker:

{
  "CLIENT_NAME": "$PROJECT_PROJECTNAME$",
  "DATE": "$PROJECT_CREATEDTIME$",
  "AMOUNT": "$PROJECT_CF_1885$"
}

Преимущества формата PDFMaker:

Префикс модуля (PROJECT_) позволяет различать поля
Поддержка связанных модулей ( $CONTACTS_LASTNAME$ )
Единый формат с существующей системой

2. Получение данных записи

Используется подход PDFMaker:

// Создать экземпляр модуля
$focus = CRMEntity::getInstance($module);

// Очистить поля
foreach ($focus->column_fields as $cf_key => $cf_value) {
    $focus->column_fields[$cf_key] = '';
}

// Получить данные записи
$focus->retrieve_entity_info($recordId, $module);
$focus->id = $recordId;

// Все поля доступны через:
$focus->column_fields['fieldname']

Преимущества:

Работает со всеми модулями
Учитывает кастомные поля
Автоматическое форматирование значений

3. Обработка переменных

Прямые поля модуля:

// Маппинг: "CLIENT_NAME" => "$PROJECT_PROJECTNAME$"
// Извлечение: PROJECT_PROJECTNAME → module=PROJECT, field=projectname
$value = $focus->column_fields['projectname'];

Связанные модули:

// Маппинг: "CONTACT_NAME" => "$CONTACTS_LASTNAME$"
// Извлечение: CONTACTS_LASTNAME → module=CONTACTS, field=lastname
$value = getRelatedFieldValue($recordId, 'Contacts', 'lastname');

Вычисляемые поля:

// Маппинг: "FULL_DATE" => {"type": "function", "function": "formatDate", "params": ["createdtime", "d.m.Y"]}
$value = formatDate($focus->column_fields['createdtime'], 'd.m.Y');

4. Замена переменных в DOCX

Для DOCX файлов используется PHPWord:

function replaceDocxVariables($docxContent, $variables) {
    // Сохранить во временный файл
    $tempFile = tempnam(sys_get_temp_dir(), 'template_') . '.docx';
    file_put_contents($tempFile, $docxContent);
    
    // Загрузить через PHPWord
    $phpWord = \PhpOffice\PhpWord\IOFactory::load($tempFile);
    
    // Заменить переменные во всех секциях
    foreach ($phpWord->getSections() as $section) {
        foreach ($section->getElements() as $element) {
            if ($element instanceof \PhpOffice\PhpWord\Element\Text) {
                $text = $element->getText();
                $text = replaceVariables($text, $variables);
                $element->setText($text);
            }
        }
    }
    
    // Сохранить результат
    $writer = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'Word2007');
    $outputFile = tempnam(sys_get_temp_dir(), 'output_') . '.docx';
    $writer->save($outputFile);
    
    $result = file_get_contents($outputFile);
    
    // Удалить временные файлы
    unlink($tempFile);
    unlink($outputFile);
    
    return $result;
}

5. Интеграция с Nextcloud

Скачивание шаблона:

function downloadFromNextcloud($filename, $path = '/Templates/') {
    $nextcloudUrl = 'https://office.clientright.ru:8443';
    $username = 'admin';
    $password = 'office';
    
    $webdavUrl = $nextcloudUrl . '/remote.php/dav/files/' . 
                 $username . $path . $filename;
    
    $ch = curl_init($webdavUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    
    $content = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        throw new Exception("Шаблон не найден: {$filename}");
    }
    
    return $content;
}

Загрузка шаблона:

function uploadToNextcloud($localFile, $filename, $path = '/Templates/') {
    $nextcloudUrl = 'https://office.clientright.ru:8443';
    $username = 'admin';
    $password = 'office';
    
    $webdavUrl = $nextcloudUrl . '/remote.php/dav/files/' . 
                 $username . $path . $filename;
    
    $ch = curl_init($webdavUrl);
    curl_setopt($ch, CURLOPT_PUT, true);
    curl_setopt($ch, CURLOPT_INFILE, fopen($localFile, 'r'));
    curl_setopt($ch, CURLOPT_INFILESIZE, filesize($localFile));
    curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    
    curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 201 && $httpCode !== 204) {
        throw new Exception("Ошибка загрузки в Nextcloud");
    }
}

🔗 ИНТЕГРАЦИЯ С PDFMAKER

Что используем из PDFMaker:

Формат переменных: $MODULE_FIELDNAME$
Получение данных: CRMEntity::getInstance() + retrieve_entity_info()
Список полей: PDFMaker_Fields_Model::getSelectModuleFields()
Обработка типов полей: PDFMaker_PDFContentUtils_Model::getUITypeName()

Преимущества:

✅ Переиспользование проверенной логики
✅ Единый формат с существующей системой
✅ Поддержка связанных модулей из коробки
✅ Автоматическое форматирование полей

📋 ПЛАН РЕАЛИЗАЦИИ

Этап 1: Базовая структура модуля

Задачи:

Создать структуру папок modules/DocTemplate/
Создать DocTemplate.php (основной класс)
Создать schema.xml с таблицами БД
Создать базовые модели (Module.php, Record.php, Template.php)
Зарегистрировать модуль в системе

Файлы:

modules/DocTemplate/DocTemplate.php
modules/DocTemplate/schema.xml
modules/DocTemplate/models/Module.php
modules/DocTemplate/models/Record.php
modules/DocTemplate/models/Template.php

Этап 2: Интеграция с Nextcloud

Задачи:

Создать helpers/NextcloudClient.php (WebDAV клиент)
Реализовать скачивание шаблонов
Реализовать загрузку шаблонов
Реализовать проверку существования файлов

Файлы:

modules/DocTemplate/helpers/NextcloudClient.php

Этап 3: Генератор документов

Задачи:

Создать models/TemplateGenerator.php
Интегрировать с PDFMaker (получение данных через CRMEntity)
Реализовать обработку переменных
Реализовать замену переменных в DOCX через PHPWord
Реализовать сохранение в S3

Файлы:

modules/DocTemplate/models/TemplateGenerator.php
modules/DocTemplate/models/VariableProcessor.php

Этап 4: Извлечение переменных

Задачи:

Создать models/VariableExtractor.php
Реализовать парсинг DOCX через PHPWord
Реализовать поиск переменных {VAR_NAME}
Интегрировать с процессом сохранения шаблона

Файлы:

modules/DocTemplate/models/VariableExtractor.php

Этап 5: UI - Список и детальный вид

Задачи:

Создать views/List.php (список шаблонов)
Создать views/Detail.php (детальный вид)
Создать views/Create.php (создание шаблона)
Добавить языковые файлы

Файлы:

modules/DocTemplate/views/List.php
modules/DocTemplate/views/Detail.php
modules/DocTemplate/views/Create.php
modules/DocTemplate/language/ru_ru.lang.php

Этап 6: UI - Двухпанельный редактор

Задачи:

Создать views/Edit.php (двухпанельный интерфейс)
Создать resources/DocTemplate.js (JS для редактора)
Создать resources/DocTemplate.css (стили)
Интегрировать OnlyOffice в iframe
Реализовать вставку переменных (копирование в буфер)

Файлы:

modules/DocTemplate/views/Edit.php
modules/DocTemplate/resources/DocTemplate.js
modules/DocTemplate/resources/DocTemplate.css

Этап 7: Actions (API endpoints)

Задачи:

Создать actions/GenerateDocument.php
Создать actions/ListTemplates.php
Создать actions/ExtractVariables.php
Создать actions/SaveMapping.php
Создать actions/GetModuleFields.php
Создать actions/SaveTemplateContent.php

Файлы:

modules/DocTemplate/actions/GenerateDocument.php
modules/DocTemplate/actions/ListTemplates.php
modules/DocTemplate/actions/ExtractVariables.php
modules/DocTemplate/actions/SaveMapping.php
modules/DocTemplate/actions/GetModuleFields.php
modules/DocTemplate/actions/SaveTemplateContent.php

Этап 8: Интеграция с модулями CRM

Задачи:

Добавить кнопку "Создать из шаблона" в модули (Project, HelpDesk, Contacts)
Создать JavaScript для диалога выбора шаблона
Реализовать генерацию документа из детального вида

Файлы:

modules/DocTemplate/DocTemplate.php (метод addCustomLinks())
modules/DocTemplate/resources/DocTemplate.js (функция showTemplateDialog())

Этап 9: Тестирование

Задачи:

Тестирование создания шаблонов
Тестирование редактирования шаблонов
Тестирование генерации документов
Тестирование на разных модулях
Проверка производительности
Обработка ошибок

🔑 КЛЮЧЕВЫЕ КОМПОНЕНТЫ

1. DocTemplate_TemplateGenerator_Model

Назначение: Генерация документов из шаблонов

Основные методы:

generate($module, $recordId, $templateId) - основная функция генерации
downloadFromNextcloud($filename, $path) - скачивание шаблона
buildVariables($mapping, $focus, $module) - построение переменных
replaceVariables($content, $variables) - замена переменных
saveToS3($content, $module, $recordId, $template) - сохранение в S3

2. DocTemplate_VariableProcessor_Model

Назначение: Обработка переменных из маппинга

Основные методы:

process($config, $focus, $module) - обработка переменной
getFieldValue($fieldConfig, $focus, $module) - получение значения поля
getRelatedFieldValue($recordId, $relatedModule, $fieldName) - связанные модули
callFunction($functionName, $params, $focus, $module) - вызов функций

3. DocTemplate_VariableExtractor_Model

Назначение: Извлечение переменных из DOCX

Основные методы:

extractVariables($docxContent) - извлечение всех переменных
extractTextFromElement($element) - извлечение текста из элемента PHPWord

4. DocTemplate_NextcloudClient_Helper

Назначение: Работа с Nextcloud через WebDAV

Основные методы:

download($filename, $path) - скачивание файла
upload($localFile, $filename, $path) - загрузка файла
exists($filename, $path) - проверка существования
listFiles($path) - список файлов в папке

📊 ФОРМАТ МАППИНГА

JSON в поле `mapping`:

{
  "CLIENT_NAME": "$PROJECT_PROJECTNAME$",
  "DATE": "$PROJECT_CREATEDTIME$",
  "AMOUNT": "$PROJECT_CF_1885$",
  "CONTACT_NAME": "$CONTACTS_LASTNAME$",
  "FULL_DATE": {
    "type": "function",
    "function": "formatDate",
    "params": ["createdtime", "d.m.Y"]
  },
  "COMPANY_NAME": {
    "type": "constant",
    "value": "ООО \"Клиент Право\""
  }
}

🎯 ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ

Пример 1: Создание шаблона претензии

Создать запись шаблона в CRM:
- Название: "Претензия"
- Модуль: Project
- Файл: pretenziya.docx

Открыть редактор, написать:

ПРЕТЕНЗИЯ

Кому: УК "Жилищник"
От: {CLIENT_NAME}

Дата: {DATE}

Текст: {CLAIM_TEXT}

Сумма: {AMOUNT} рублей

Сохранить → CRM находит переменные
Настроить маппинг:
- CLIENT_NAME → PROJECT_PROJECTNAME
- DATE → PROJECT_CREATEDTIME
- CLAIM_TEXT → PROJECT_DESCRIPTION
- AMOUNT → PROJECT_CF_1885
Готово!

Пример 2: Генерация документа

Открыть проект в CRM (recordId=400264)
Нажать "Создать из шаблона"
Выбрать шаблон "Претензия"
CRM:
- Скачивает pretenziya.docx из Nextcloud
- Получает данные проекта 400264
- Заполняет переменные:
  - {CLIENT_NAME} → "Проект_1"
  - {DATE} → "15.01.2025"
  - {AMOUNT} → "400000"
- Сохраняет готовый документ в S3
- Открывает в OnlyOffice

⚠️ ОГРАНИЧЕНИЯ И ЗАМЕЧАНИЯ

PHPWord работает только с DOCX
- Для XLSX и PPTX используется простая замена текста
- Сложное форматирование может не сохраниться
Переменные должны быть в тексте
- Не работают в заголовках/колонтитулах (ограничение PHPWord)
- Не работают в таблицах (частично)
Размер шаблона
- Большие шаблоны (>10MB) могут загружаться медленно
OnlyOffice API
- Прямая вставка переменных через API требует настройки OnlyOffice Document Server
- Начальная реализация использует копирование в буфер обмена

🚀 ГОТОВНОСТЬ К РЕАЛИЗАЦИИ

Все компоненты спроектированы:

✅ Архитектура определена
✅ Структура модуля спроектирована
✅ База данных спроектирована
✅ UI/UX продуман
✅ Интеграция с PDFMaker определена
✅ Процессы описаны

Следующий шаг: Начать реализацию с Этапа 1 (базовая структура модуля)

📚 ССЫЛКИ НА ДОПОЛНИТЕЛЬНЫЕ ДОКУМЕНТЫ

Модуль готов к реализации! 🎉

38 KiB Raw Blame History Unescape Escape

📘 МОДУЛЬ DocTemplate - ПОЛНЫЙ МАНУАЛ

📋 СОДЕРЖАНИЕ

🎯 ОБЗОР МОДУЛЯ

Назначение

Основные возможности

Аналогия

🏗️ АРХИТЕКТУРА

Общая схема

Разделение ответственности

📁 СТРУКТУРА МОДУЛЯ

🗄️ БАЗА ДАННЫХ

Таблица: vtiger_doctemplate

Таблица: vtiger_doctemplate_seq

Таблица: vtiger_doctemplate_settings

🔄 ПРОЦЕСС РАБОТЫ

1. Создание шаблона

Сценарий A: Создание пустого шаблона

Сценарий B: Загрузка существующего файла

2. Редактирование шаблона

Двухпанельный интерфейс:

3. Настройка маппинга

4. Генерация документа

Процесс:

Алгоритм генерации:

🎨 ИНТЕРФЕЙС ПОЛЬЗОВАТЕЛЯ

1. Список шаблонов (List View)

2. Детальный вид шаблона

3. Кнопка в модулях CRM

🔧 ТЕХНИЧЕСКИЕ ДЕТАЛИ

1. Формат переменных

В шаблоне DOCX:

В маппинге CRM:

2. Получение данных записи

3. Обработка переменных

Прямые поля модуля:

Связанные модули:

Вычисляемые поля:

4. Замена переменных в DOCX

5. Интеграция с Nextcloud

Скачивание шаблона:

Загрузка шаблона:

🔗 ИНТЕГРАЦИЯ С PDFMAKER

Что используем из PDFMaker:

Преимущества:

📋 ПЛАН РЕАЛИЗАЦИИ

Этап 1: Базовая структура модуля

Этап 2: Интеграция с Nextcloud

Этап 3: Генератор документов

Этап 4: Извлечение переменных

Этап 5: UI - Список и детальный вид

Этап 6: UI - Двухпанельный редактор

Этап 7: Actions (API endpoints)

Этап 8: Интеграция с модулями CRM

Этап 9: Тестирование

🔑 КЛЮЧЕВЫЕ КОМПОНЕНТЫ

1. DocTemplate_TemplateGenerator_Model

2. DocTemplate_VariableProcessor_Model

3. DocTemplate_VariableExtractor_Model

4. DocTemplate_NextcloudClient_Helper

📊 ФОРМАТ МАППИНГА

JSON в поле mapping:

🎯 ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ

Пример 1: Создание шаблона претензии

Пример 2: Генерация документа

⚠️ ОГРАНИЧЕНИЯ И ЗАМЕЧАНИЯ

🚀 ГОТОВНОСТЬ К РЕАЛИЗАЦИИ

📚 ССЫЛКИ НА ДОПОЛНИТЕЛЬНЫЕ ДОКУМЕНТЫ

38 KiB

Raw Blame History

Таблица: `vtiger_doctemplate`

Таблица: `vtiger_doctemplate_seq`

Таблица: `vtiger_doctemplate_settings`

JSON в поле `mapping`: