Инструкция: настройка КП из новой шахматки (CRM4DEV-651)

Назначение

Инструкция описывает, как настроить формирование коммерческого предложения (КП) из новой шахматки в 1С CRM.

Функциональность должна позволять:

  • открыть HTML-предпросмотр КП по выбранной квартире/объекту;
  • сохранить КП в PDF;
  • сформировать ссылку на КП для отправки в мессенджер или по почте;
  • использовать HTML-макет и JSON-структуру автотекстов по аналогии с CRM4DEV-1126.

Связанные задачи:

  • CRM4DEV-651 - инфа о квартире из шахматки.
  • CRM4DEV-1126 - КП по подборке: API создания ссылки, HTML и PDF.

Итоговое решение

Документ КП при просмотре/печати из шахматки создавать не нужно.

Для автотекстов не нужно расширять владельцев до объекта недвижимости как полноценного владельца печатной формы. Лучше использовать отдельный контекст формирования КП из шахматки: выбранные объекты, застройщик, текущая дата, изображения, а для отправки - оффер и ссылка.

Для отправки в мессенджер/почту нужно создавать/обновлять оффер по механике CRM4DEV-1126 и передавать пользователю share_url.

Что должно быть в конфигурации

Предопределенный вид печатной формы

Должен быть создан предопределенный элемент:

УПДК_ВидыПечатныхФорм.ШахматкаОписаниеОбъектаНедвижимости

Назначение:

  • хранит HTML-макет;
  • хранит JSON-структуру автотекстов;
  • позволяет обновлять макет из режима предприятия через кнопку Стандартный шаблон или через обработку заполнения.

Группа автотекстов

Должна быть создана группа:

УПДК_ШаблоныАвтотекстаПечатныхФорм.ОбъектыНедвижимости

Назначение:

  • родительский контейнер для автотекстов, используемых при формировании HTML-страницы КП из шахматки;
  • автотексты должны заполнять JSON для макета.

Обработка заполнения

Для автоматического заполнения предопределенных элементов используется обработка:

ЗаполнитьВидПечатнойФормыАвтотексты.epf

Как применять:

  • при обновлении до нужного релиза обработка должна запускаться автоматически;
  • для ручной проверки можно запустить обработку вручную;
  • после изменения макета можно повторно запустить обработку или нажать кнопку Стандартный шаблон в предопределенном виде печатной формы.

Файлы из пакета

К задаче прикладывается архив:

CRM4DEV-651_KP_from_chessboard.zip

Основной файл для загрузки в 1С:

kp_chessboard_template.html

Остальные файлы пакета:

ФайлНазначение
kp_chessboard_template.htmlОсновной HTML-макет для 1С.
kp_chessboard_autotext.jsonJSON-структура, которую заполняют автотексты.
kp_chessboard_mapping.mdМаппинг полей, правила заполнения, нюансы PDF.
kp_chessboard_1c_adapter.bslПример точек подключения в 1С. Это не готовый модуль для вставки без адаптации.
kp_chessboard_acceptance_tests.csvПриемочные проверки.
kp_chessboard_example_preview.htmlПример результата после подстановки JSON.

Настройка HTML-макета

  1. Открыть в 1С предопределенный вид печатной формы:

УПДК_ВидыПечатныхФорм.ШахматкаОписаниеОбъектаНедвижимости

  1. Заменить текущий HTML-макет на содержимое файла:

kp_chessboard_template.html

  1. Если используется обработка заполнения, повторно запустить:

ЗаполнитьВидПечатнойФормыАвтотексты.epf

  1. Альтернативно нажать кнопку Стандартный шаблон на форме предопределенного вида печатной формы.

  2. Проверить, что в макете остался маркер:

__KP_DATA_JSON__

Этот маркер должен быть заменен 1С на сериализованный JSON перед открытием HTML.

JSON-контракт макета

Минимальная структура данных:

{
  "selection": {
    "title": "Коммерческое предложение",
    "subtitle": "От застройщика «[КПЗастройщикНаименование]»",
    "date": "[КПТекущаяДата]",
    "count": "[КПКоличествоОбъектовПодборки]"
  },
  "objects": [
    {
      "title": "Квартира · [КППлощадьОбщая] м²",
      "subtitle": "[КППодборкаПодзаголовок1]",
      "price": "[КПЦена]",
      "pricePerM2": "[КПЦенаЗаМ2] руб./м²",
      "planImg": "[КППланКвартирыBase64]",
      "params": [
        { "k": "Площадь", "v": "[КППлощадьОбщая] м²" },
        { "k": "Этаж", "v": "[КПЭтаж]" },
        { "k": "Жилая", "v": "[КППлощадьЖилая]" },
        { "k": "Кухня", "v": "[КПКухня]" },
        { "k": "С/у", "v": "[КПСанузел]" },
        { "k": "Отделка", "v": "[КПОтделка]" },
        { "k": "Сторона света", "v": "[КПСторонаСвета]" },
        { "k": "Срок сдачи", "v": "[КПСрокСдачи]" }
      ],
      "description": "[КПОписание]"
    }
  ],
  "titlePage": {
    "renderImg": "[КПРендерЖКBase64]",
    "renderCaption": "Рендер жилого комплекса",
    "blocks": [
      { "title": "[КПЗаголовокБлока1]", "text": "[КПТекстБлока1]" }
    ],
    "footerLeft": "© 4DEV · Макет подборки",
    "footerRight": "Поддержка печати: Ctrl+P / «Сохранить как PDF»"
  }
}

Важно: поле manager в HTML/JSON не передается и не отображается.

Источники данных

ПолеОткуда брать
selection.titleСтатично Коммерческое предложение или автотекст заголовка.
selection.subtitleЗастройщик выбранного объекта: От застройщика «...».
selection.dateТекущая дата формирования.
selection.countКоличество объектов в подборке/выборке.
objects[]Выбранные объекты недвижимости из шахматки.
objects[].planImgГотовая картинка планировки: URL или Data URI.
titlePage.renderImgГотовая картинка рендера ЖК: URL или Data URI.
titlePage.blocks[]Описание ЖК/преимуществ. Для разных ЖК - несколько блоков.

Изображения: планировка и рендер ЖК

Поля objects[].planImg и titlePage.renderImg должны содержать готовый src для HTML:

  • data:image/png;base64,...
  • data:image/jpeg;base64,...
  • data:image/bmp;base64,...
  • data:image/webp;base64,...
  • либо абсолютный URL, доступный браузеру и сервису PDF.

Нельзя передавать:

  • только UID файла;
  • служебные поля planImg_uid, planImg_type;
  • локальный путь Windows;
  • ссылку, недоступную сервису HTML-to-PDF.

Если titlePage.renderImg пустой, обновленный макет не выводит блок рендера ЖК и не занимает под него место. Если нет ни рендера, ни описания ЖК, весь нижний блок удаляется из HTML.

Настройка PDF

Для сохранения PDF должна быть заполнена константа:

ЭкспортВPDFАдресОбработчика

Если константа не заполнена, кнопка Сохранить в PDF должна быть неактивна.

По комментариям к задаче использовался сервис:

htmltopdf.4dev.app/render-pdf

Адрес нужно указывать актуальный для окружения.

Имя файла PDF

При сохранении PDF 1С должна принудительно добавлять расширение .pdf, если его нет.

Пример:

Апрель, ГП 1.1, Секция 1, кв. №30

должно сохраняться как:

Апрель, ГП 1.1, Секция 1, кв. №30.pdf

Иначе файл может сохраняться без расширения и некорректно открываться пользователем.

Отдача PDF в браузер

Если PDF открывается напрямую из папки сервиса, но не открывается в браузере, проблема не в HTML-макете, а в отдаче PDF через HTTP.

Нужно проверить:

  • файл отдается только после полного завершения записи и закрытия потока;
  • URL открывается после фактической готовности файла;
  • Content-Type: application/pdf;
  • Content-Length совпадает с реальным размером файла;
  • HTTP-ответ содержит бинарный PDF, а не HTML/JSON/текст ошибки;
  • PDF не читается как строка и не проходит через текстовую кодировку;
  • имя файла с кириллицей корректно кодируется в URL/заголовках;
  • при необходимости файл отдается через безопасный идентификатор, а не через сырое имя файла.

Поведение кнопок в шахматке

Кнопка КП / предпросмотр

  1. Пользователь выбирает объект в шахматке.
  2. 1С формирует JSON по выбранному объекту.
  3. 1С подставляет JSON в kp_chessboard_template.html вместо __KP_DATA_JSON__.
  4. Открывается HTML-предпросмотр.
  5. Документ КП не создается.

Сохранить в PDF

  1. 1С формирует HTML так же, как для предпросмотра.
  2. HTML передается в сервис HTML-to-PDF.
  3. PDF сохраняется с расширением .pdf.
  4. PDF должен открываться в браузере и из файловой системы.

Иконки мессенджеров/почты

  1. Создать/обновить оффер по механике CRM4DEV-1126.
  2. Получить token и share_url.
  3. Передать в канал отправки именно ссылку на КП.
  4. Если интеграции с мессенджером нет, минимальное поведение - показать/скопировать ссылку пользователю. Не нужно показывать, что сообщение отправлено, если фактической отправки не было.

Ограничения и бизнес-правила

  • Одно КП не должно объединять объекты разных застройщиков без отдельно согласованного бизнес-правила.
  • Если объект недоступен текущему пользователю, КП не формируется.
  • Если нет планировки, карточка формируется с заглушкой изображения.
  • Если нет рендера ЖК, блок рендера скрывается.
  • Если нет описания ЖК и рендера, нижний блок описания ЖК скрывается полностью.

Проверка после настройки

Минимальные проверки:

  1. Сформировать КП по одной квартире.
  2. Проверить, что шапка содержит: заголовок, застройщика, дату, количество объектов.
  3. Проверить, что поля manager/Агент/Менеджер не отображаются.
  4. Проверить, что цена в PDF прижата вправо в верхней строке карточки.
  5. Проверить, что площадь/название квартиры остаются слева.
  6. Проверить, что рендер ЖК отображается, если titlePage.renderImg заполнен.
  7. Проверить, что пустой рендер ЖК не создает пустую вторую страницу.
  8. Сохранить PDF и убедиться, что файл имеет расширение .pdf.
  9. Открыть PDF через браузер.
  10. Открыть тот же PDF из папки сервиса и сравнить размер файла.
  11. Проверить сценарий с несколькими объектами одного застройщика.
  12. Проверить запрет или отдельное бизнес-правило для объектов разных застройщиков.

Приемочные критерии

Функциональность считается настроенной, если:

  • HTML открывается из шахматки без создания документа КП;
  • PDF формируется без принудительного переноса блока описания ЖК на второй лист;
  • цена в карточке объекта прижата вправо;
  • шапка визуально акцентирована и не содержит менеджера/агента;
  • рендер ЖК отображается при заполненном titlePage.renderImg;
  • пустой рендер не занимает место;
  • PDF сохраняется с расширением .pdf;
  • PDF открывается через браузер;
  • ссылка для мессенджера/почты формируется через оффер и share_url.

Что делать при изменении макета

  1. Обновить kp_chessboard_template.html.
  2. Загрузить новый HTML в УПДК_ВидыПечатныхФорм.ШахматкаОписаниеОбъектаНедвижимости.
  3. Нажать Стандартный шаблон или запустить ЗаполнитьВидПечатнойФормыАвтотексты.epf.
  4. Проверить HTML-предпросмотр.
  5. Проверить PDF.
  6. Проверить, что автотексты изображений не возвращают помеченные на удаление файлы и поддерживают нужные форматы Data URI.

Ссылки

  • Нет меток