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

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

- <code>editorial-2018-12-practice-legacy-refactoring</code>;
- <code>editorial-2018-12-mechanism-legacy-refactoring</code>;
- <code>editorial-2018-12-field-legacy-refactoring</code>.

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

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

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

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

| Утверждение или фрагмент | Первичный источник | Проверенная граница |
| --- | --- | --- |
| <code>CModule::IncludeModule('iblock')</code> возвращает булев результат подключения модуля | [CModule::IncludeModule](https://dev.1c-bitrix.ru/api_help/main/reference/cmodule/includemodule.php) | Во всех примерах это явная проверка перед использованием legacy API; она не выдаётся за настройку прав или окружения |
| <code>CIBlockElement::GetList</code> возвращает выборку по фильтру и допускает выбор полей <code>ID</code>, <code>IBLOCK_ID</code>, <code>CODE</code> | [CIBlockElement::GetList](https://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/getlist.php) | Повторная выборка проверяет один элемент по ID, а не все ссылки каталога или импорт |
| <code>CIBlockElement::Update</code> возвращает <code>true</code>/<code>false</code>; текст ошибки доступен через <code>LAST_ERROR</code> | [CIBlockElement::Update](https://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/update.php?print=Y) | В примерах передаётся только <code>CODE</code> или <code>NAME</code>; ни один текст не обещает атомарность с HTML, кешем или интеграцией |
| Обработчик <code>OnBeforeIBlockElementUpdate</code> запускается до обновления и может изменить поля либо отменить действие | [OnBeforeIBlockElementUpdate](https://dev.1c-bitrix.ru/api_help/iblock/events/onbeforeiblockelementupdate.php) | Статьи требуют проверить зарегистрированные обработчики на конкретном контуре, а не объявляют результат <code>Update</code> окончательным состоянием всего сайта |
| <code>CUtil::translit</code> принимает язык и параметры регистра, замен и длины | [CUtil::translit](https://dev.1c-bitrix.ru/api_help/main/reference/cutil/translit.php) | Параметры приведены как учебные. Уникальность, старые URL и SEO-правила оставлены за пределами примера |
| Исключение прекращает обычный путь функции до обработчика формы | [PHP Manual — Exceptions](https://www.php.net/exceptions) | Исключение используется только для разделения ошибки входа/Bitrix API и сообщения формы; оно не названо транзакцией нескольких систем |

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

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

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

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

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

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

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

```text
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 знаков тела. <code>npm run build</code>
завершился с кодом 0 и сгенерировал 374 статические страницы.

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