Разработчику: спецификация и артикулы на лету

Эта статья — для разработчиков, которым нужно программно влиять на спецификацию: менять позиции, цены и артикулы «на лету», в том числе для PDF и Excel. Весь код размещайте внутри обработчика PP_ready (см. «Основы кастомизации»).

Как устроена спецификация

Спецификация собирается в единую структуру-контекст. Её формирует движок при каждом пересчёте, и одну и ту же структуру используют все три вывода: визуальная спецификация на сцене, PDF и Excel. Значит, изменив данные один раз, вы измените их везде.

Ключевые части контекста (ctx):

• ctx.all[type] — все собранные позиции по типам (module, wall — корпус/материал, butts — кромка, facade, facade_glass, handle, item — фурнитура/аксессуары и др.);
• ctx.sum[type][sum_key] — агрегированные позиции: одинаковые позиции с одним sum_key объединяются. Именно ctx.sum рендерится в интерфейсе, PDF и Excel;
• ctx.sum_arr — плоский список тех же позиций;
• ctx.total_price — итоговая стоимость (уже со скидкой проекта).

Поля типичной позиции: name, code (артикул), price, total_count, total_price, price_type (тип расчёта), размеры (width, height, thickness, size_x/y/z), материал (material_code, mat_code), и sum_key — ключ группировки.

Хуки спецификации

Вклинивание делается через слоты pp.events.cabinet.* (именно cabinet, не global):

Хук	Сигнатура	Когда	Для чего
get_specs_start	(ctx)	до сбора позиций	подготовка; вернёте false — сбор отменится
before_create_spec_item	(type, obj, ctx)	перед добавлением позиции	вернёте false — позиция пропускается (скрыть из расчёта)
after_create_spec_item	(type, obj, ctx, spec)	позиция собрана, но ещё не добавлена	изменить spec.code, spec.price, spec.sum_key на лету
before_apply_specs_aggr	(ctx)	перед расчётом количеств/цен	подменить функции агрегации, переписать ctx.sum
get_specs_end	(ctx)	спецификация готова	финальная правка ctx.sum и ctx.total_price

Важно. Как только задан хотя бы один из этих хуков, движок отключает авто-вариантный раскрой материалов — чтобы он не конфликтовал с вашей логикой. Это ожидаемое поведение.

Пример: скрыть позицию из спецификации

document.addEventListener('PP_ready', function (e) {
    const pp = e.detail.pp;
    pp.events.cabinet.before_create_spec_item = function (type, obj, ctx) {
        // не выводить кромку в спецификацию
        if (type === 'butts') return false;
    };
});

Пример: задать свою цену позиции

pp.events.cabinet.after_create_spec_item = function (type, obj, ctx, spec) {
    if (type === 'facade' && spec.size_x > 600) {
        spec.price = 1500; // своя цена за крупный фасад
    }
};

Как изменения попадают в выводы

• Интерфейс на сцене — спецификация перечитывает ctx.sum при пересчёте цены, так что правки видны сразу.
• PDF — генерируется библиотекой pdfmake: код берёт ctx.sum[...] и ctx.total_price и формирует документ pdfmake (docDefinition — таблицы и тексты). Чтобы изменить содержимое PDF (цены, артикулы, состав позиций), правьте данные спецификации через хуки выше — этого достаточно в большинстве случаев. Менять саму вёрстку PDF (стили, колонки, порядок) — это уже правка docDefinition в формате pdfmake, и её не сделать только из custom.js без вмешательства в код сцены.
• Excel — так же читает ctx.sum и total_price; правки данных через хуки отражаются и в выгрузке.

Вывод для практики. «Модификация спецификации визуально и в PDF» в 99% случаев = изменение данных позиций через after_create_spec_item / get_specs_end. Тогда правки автоматически появятся и на экране, и в PDF, и в Excel — без дублирования логики.

Артикул позиции

Артикул — это поле code позиции (у материалов также mat_code, variant_code). Через артикул позиция связывается с прайс-листом, когда выбран способ цены «по артикулу».

Группировка одинаковых позиций определяется полем sum_key — это, по сути, «ключ уникальной комбинации». Стандартно он собирается из параметров позиции (для модуля — из id/типа/кода, для фасада — из id/материала/типа фрезеровки и т. д.). Изменив sum_key в after_create_spec_item, вы управляете тем, что считать одной позицией, а что — разными.

Это и есть основа сценария «цена за уникальную комбинацию параметров»: например, развести корпуса по комбинации «модуль + размер + цвет», задав им разный code и sum_key. Полный практический разбор — в статье «Артикул из комбинации параметров».

Коротко

Спецификация — это контекст ctx с агрегированными позициями ctx.sum[type][sum_key], который читают интерфейс, PDF (pdfmake) и Excel. Вклинивание — через pp.events.cabinet: before_create_spec_item (скрыть позицию), after_create_spec_item (изменить code/price/sum_key), get_specs_end (финальная правка). Чтобы поменять содержимое PDF/Excel, меняйте данные позиций через хуки — вёрстку PDF задаёт pdfmake в коде сцены.