progcode/editorial/reviews/2018-12-draft.md

Декабрь 2018 — тройное ревью и выпускной gate «Рефакторинг Bitrix без большого переписывания»

Статус: принят в публикационный слой 31 июля 2026 года. Пакет П11 сохраняет стабильные slug, дату и автора базового архива:

• editorial-2018-12-practice-legacy-refactoring;
• editorial-2018-12-mechanism-legacy-refactoring;
• editorial-2018-12-field-legacy-refactoring.

Созданы только:

• web/scripts/upgrade-2018-12.mjs;
• web/public/assets/editorial/2018/bitrix-legacy-safe-seam-2018.svg;
• web/public/assets/editorial/2018/bitrix-mixed-responsibility-2018.svg;
• web/public/assets/editorial/2018/bitrix-legacy-replacement-rollback-2018.svg;
• этот файл.

Сам П11 не меняет web/data/articles.json: публикационный слой подключает его отдельным registry только по slug. В рабочем дереве могут находиться независимые изменения других партий. Дата ревью: 31 июля 2026 года.

Проход 1. Факты и техника — пройдено

Утверждение или фрагмент	Первичный источник	Проверенная граница
CModule::IncludeModule('iblock') возвращает булев результат подключения модуля	CModule::IncludeModule	Во всех примерах это явная проверка перед использованием legacy API; она не выдаётся за настройку прав или окружения
CIBlockElement::GetList возвращает выборку по фильтру и допускает выбор полей ID, IBLOCK_ID, CODE	CIBlockElement::GetList	Повторная выборка проверяет один элемент по ID, а не все ссылки каталога или импорт
CIBlockElement::Update возвращает true/false; текст ошибки доступен через LAST_ERROR	CIBlockElement::Update	В примерах передаётся только CODE или NAME; ни один текст не обещает атомарность с HTML, кешем или интеграцией
Обработчик OnBeforeIBlockElementUpdate запускается до обновления и может изменить поля либо отменить действие	OnBeforeIBlockElementUpdate	Статьи требуют проверить зарегистрированные обработчики на конкретном контуре, а не объявляют результат Update окончательным состоянием всего сайта
CUtil::translit принимает язык и параметры регистра, замен и длины	CUtil::translit	Параметры приведены как учебные. Уникальность, старые URL и SEO-правила оставлены за пределами примера
Исключение прекращает обычный путь функции до обработчика формы	PHP Manual — Exceptions	Исключение используется только для разделения ошибки входа/Bitrix API и сообщения формы; оно не названо транзакцией нескольких систем

• Проверены три разных вопроса: защищённый шов одного Update; причина опасного смешения формы, инфоблока и следующего эффекта; контролируемая замена одного legacy-участка с отдельным откатом маршрута и данных.
• PHP-фрагменты написаны в синтаксисе, доступном PHP 7.2. Они являются учебными и воспроизводимыми при наличии Bitrix-окружения, но не выдаются за выполненные в этом workspace: здесь нет ядра Bitrix, test-only данных и доступа к конкретному проекту.
• Удалён не относящийся к тексту источник filter_var; в финальном списке остались только источники, на которые опирается соответствующий материал.
• Массив PROPERTY_VALUES в примеры не добавлен: документация Update требует полного набора свойств при его передаче, а пакет намеренно демонстрирует изменение одного поля.
• Модуль экспортирует ровно три ревизии без файлового ввода-вывода. CLI печатает только JSON при --print-revisions, поэтому импорт скрипта безопасен для будущей интеграции.

Проход 2. Редактура и голос М1 — пройдено

Ревизия	Симптом и цена в первых двух абзацах	Один главный вопрос	Артефакт и ограничение
Практика	После правки карточка теряет привычный URL; цена — 404 и неясный след для шаблона/выгрузки	Как вынести защищённый шов вокруг изменения CODE	ProductCodeWriter, таблица контракта и повторная выборка; не обещаются уникальность, SEO и безопасность всех связей
Механизм	Форма показывает ошибку после уже выполненной записи; цена — повтор побочного эффекта и потеря причины	Почему смешение POST, API, HTML и интеграции опасно	Упрощённый save.php, отделённая функция записи и таблица следов; не заявляется транзакция между системами
Поле	Вызовы формирования CODE разбросаны; цена — сломанный URL и риск затереть чужое изменение откатом	Как заменить один legacy-участок с проверкой и откатом	Снимок до изменения, явный маршрут writer и сравнение после записи; один элемент не выдаётся за миграцию импорта

• Автоматический аудит зафиксировал основной объём: 8 837, 9 492 и 9 445 знаков. Все значения находятся в диапазоне 5 000–15 000; тема П11 также выдерживает плановые 7–9 тыс. близко к середине диапазона без искусственного наполнения.
• В каждой статье есть не менее пяти смысловых h2, таблица с thead и scope, собственный рисунок с содержательными alt/figcaption, код, упорядоченный маршрут, ограничения и точный заголовок <h2>Проверяемые источники</h2>.
• Тон сохранён для М1 / 2018: короткая цепочка «симптом → причина → проверка → действие», локальные PHP/Bitrix-термины, осторожные выводы. Нет SLO, Kubernetes, feature flags, продуктовых метрик, обещаний «переписать всё» и выдуманных результатов запуска.
• Мобильный проход нашёл слишком мелкие подписи в исходных SVG. Подписи были сокращены до действий и увеличены; развёрнутое объяснение осталось в figcaption, где оно читается без масштабирования схемы.

Проход 3. Визуал и выпуск — пройдено после исправления подписей

• bitrix-legacy-safe-seam-2018.svg объясняет границу формы, writer, Update(CODE) и повторной выборки; шаблон и интеграция явно остаются снаружи.
• bitrix-mixed-responsibility-2018.svg показывает четыре разных следа save.php и то, что поздний сбой не отменяет раннюю запись автоматически.
• bitrix-legacy-replacement-rollback-2018.svg разделяет откат маршрута и восстановление поля, поэтому диаграмма не предлагает опасное автоматическое перезаписывание данных.
• SVG открыты в браузере на ширине 1 280px и 375px: у всех трёх есть title, desc, role="img", корректный viewBox и нет горизонтального переполнения. Дополнительно отрендерены в PNG на ширине 375px; после исправления видны заголовки, действия и предупреждение, без обрезанных строк.
• У всех рисунков валидный XML, нет JavaScript, внешних ресурсов и растровых вложений.

Выполненные проверки

node --check web/scripts/upgrade-2018-12.mjs
node --input-type=module -e "import('./web/scripts/upgrade-2018-12.mjs') ..."
cd web && npm run audit:draft -- scripts/upgrade-2018-12.mjs
xmllint --noout web/public/assets/editorial/2018/bitrix-legacy-safe-seam-2018.svg \
  web/public/assets/editorial/2018/bitrix-mixed-responsibility-2018.svg \
  web/public/assets/editorial/2018/bitrix-legacy-replacement-rollback-2018.svg

После интеграции основной редактор повторно выполнил strict audit: все три slug прошли требования к структуре, визуалу, таблицам, коду, источникам и объёму 8 837 / 9 492 / 9 445 знаков тела. npm run build завершился с кодом 0 и сгенерировал 374 статические страницы.

Выпусковой вердикт: принят к публикации. articles.json не менялся; registry накладывает только редакционные поля по стабильному slug.