CRM4DEV-1534: Техническая инструкция по настройке КП-подборки

Назначение

Инструкция описывает техническую настройку КП-подборки из новой шахматки недвижимости 2.0.

Связанная задача: CRM4DEV-1534.

Связанные реализации:

• CRM4DEV-651 - базовый HTML/PDF макет КП из новой шахматки;
• CRM4DEV-1126 - механизм оффера и ссылки share_url.

Основные артефакты

Актуальный пакет: CRM4DEV-selection-commercial-offer.zip.

Ключевые файлы:

• kp_selection_template.html - основной HTML template печатной формы КП-подборки;
• kp_selection_autotext.json - структура JSON/автотекстов;
• kp_selection_mapping.md - маппинг данных;
• kp_selection_1c_adapter.bsl - пример серверной логики 1С;
• kp_selection_filters_v8_proxy.html - HTML-блок фильтров для формы 1С через v8-proxy;
• kp_selection_filters_v8_proxy_contract.md - контракт методов фильтров;
• kp_selection_acceptance_tests.csv - приемочные проверки.

Что загружать как template

В вид печатной формы нужно вставлять содержимое файла:

kp_selection_template.html

Не использовать как основной template:

• kp_selection_example_preview.html - пример с уже вставленным тестовым JSON;
• kp_selection_example_data.json - тестовые данные;
• commercial_offer_form_mockup.html - визуальный макет формы, не печатный шаблон;
• kp_selection_filters_v8_proxy.html - блок фильтров формы, не печатная форма.

Кодировка

Template должен храниться и загружаться в UTF-8.

Контрольный признак нормальной кодировки:

Коммерческое предложение
Описание жилых комплексов
Изображение не загружено
Основные параметры

Если в template видны строки вида РљРѕРјРј..., файл загружен или сохранен в неверной кодировке. Такой template нельзя использовать.

Формат JSON для template

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

{
  "selection": {
    "title": "Коммерческое предложение",
    "subtitle": "От застройщика «ПАРТНЕР-СТРОЙ СЗ АО»",
    "date": "30.06.2026",
    "count": 5
  },
  "objects": [
    {
      "title": "Квартира · 38,3 м²",
      "subtitle": "Маяк Курган, ГП 6, Парадная 1, кв. №13",
      "price": "3 830 000",
      "pricePerM2": "100 000 руб./м²",
      "planImg": "data:image/png;base64,...",
      "params": [
        { "k": "Площадь", "v": "38,3 м²" },
        { "k": "Этаж", "v": "2" }
      ],
      "description": "Краткое описание объекта"
    }
  ],
  "titlePage": {
    "renderImg": "data:image/png;base64,...",
    "renderCaption": "Рендер жилого комплекса",
    "blocks": [
      {
        "title": "ЖК Маяк",
        "text": "Описание жилого комплекса"
      }
    ],
    "footerLeft": "© 4DEV · Макет подборки",
    "footerRight": "Поддержка печати: Ctrl+P / Сохранить как PDF"
  }
}

Описание ЖК

Основной ожидаемый формат:

"titlePage": {
  "blocks": [
    { "title": "ЖК Маяк", "text": "Описание ЖК" }
  ]
}

Template также поддерживает fallback-поля:

• titlePage.description;
• titlePage.text;
• complexes[];
• residentialComplexes[];
• complexBlocks[];
• complexDescription;
• residentialComplexDescription;
• objects[].complexDescription;
• objects[].complexText.

Если описание не передано ни в одном поле, в PDF будет диагностический блок:

Описание ЖК не передано в JSON. Нужно заполнить titlePage.blocks[] или titlePage.description.

Это не ошибка template. Это означает, что 1С не передала описание ЖК.

Рендер ЖК и изображения

Для изображений передавать готовый src:

• data:image/png;base64,...; или
• полный URL, доступный сервису PDF.

Поля:

• objects[].planImg - планировка объекта;
• titlePage.renderImg - рендер ЖК.

Если изображение не передано, template выводит Изображение не загружено.

Правила пагинации PDF

Текущий template настроен под A4.

Ожидаемая раскладка:

Техническая логика template:

• объекты группируются по 3 в .object-page;
• страницы с 3 объектами получают класс is-full-page;
• последняя страница с 1 или 2 объектами получает with-title-page items-N;
• секция описания получает items-N, чтобы растягивать блок описания на остаток страницы;
• если последняя страница заполнена 3 объектами, описание ЖК переносится на новую страницу.

Автотексты

Должен быть настроен автотекст количества объектов подборки.

Логика:

Если КоммерческоеПредложение = Неопределено Тогда
    Результат = 1;
Иначе
    Результат = КоммерческоеПредложение.ОбъектыНедвижимости.Количество();
КонецЕсли;

Проверить, что имя табличной части в базе действительно ОбъектыНедвижимости. Если имя отличается, код нужно адаптировать.

Настройка печатной формы в 1С

1. Открыть настройки видов печатных форм.
2. Найти или создать вид печатной формы для КП-подборки из новой шахматки.
3. Вставить HTML из kp_selection_template.html.
4. Проверить, что файл вставлен в UTF-8, без РљРѕ....
5. Привязать шаблон автотекстов к нужному владельцу/документу КоммерческоеПредложение.
6. Проверить автотексты по объектам и описанию ЖК.
7. Сохранить настройки.

Настройка фильтров формы через v8-proxy

Файл kp_selection_filters_v8_proxy.html является отдельным блоком для формы, не печатным template.

HTML ожидает вызов:

window.v8proxy.call(methodName, payload)

Методы 1С, которые должны быть реализованы:

• KPSelectionFilters_Init;
• KPSelectionFilters_GetDefaultsFromChessboard;
• KPSelectionFilters_PreviewSelection;
• KPSelectionFilters_ApplyFilters;
• KPSelectionFilters_AddObject;
• KPSelectionFilters_ClearFilters;
• KPSelectionFilters_ReportClientError.

Основная логика:

• PreviewSelection только показывает найденные объекты;
• ApplyFilters добавляет найденные объекты в табличную часть КП;
• AddObject добавляет один объект;
• дубли по одному объекту недвижимости не добавлять;
• очистка фильтров не должна очищать табличную часть объектов.

PDF-сервис

Требования:

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

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

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

1. Сформировать КП на 1 объект.
2. Сформировать КП на 2 объекта.
3. Сформировать КП на 3 объекта.
4. Сформировать КП на 4 объекта.
5. Сформировать КП на 5 объектов.
6. Сформировать КП на 6 объектов.
7. Проверить количество страниц и раскладку.
8. Проверить, что описание ЖК отображается.
9. Проверить PDF из браузера.
10. Проверить PDF из папки сервиса.
11. Проверить, что кодировка русских подписей не сломана.
12. Проверить отправку/формирование share_url.

Типовые дефекты и диагностика

Актуальный контроль template

Последняя проверка template:

3 объекта -> 2 страницы
4 объекта -> 2 страницы
5 объектов -> 2 страницы
6 объектов -> 3 страницы

Кодировка проверена:

{
  "proper": true,
  "mojibake": false
}

CRM4DEV-selection-commercial-offer.zip