Услуги по документации проектов на 1С-Битрикс

Документация проектов на 1С-Битрикс

Разработчик уволился. Новый открывает init.php на 2000 строк, видит 47 обработчиков событий через AddEventHandler, цепочку агентов в b_agent и кастомный модуль без единого комментария. На «вникание» уходит месяц. Документация этот месяц превращает в три дня — и мы создаём её для проектов на 1С-Битрикс: от архитектурных схем до пошаговых инструкций для контент-менеджера.

Цена отсутствия документации

Конкретные ситуации, которые видим на каждом втором проекте:

• Обновление ядра — разработчик запускает bitrix/tools/upgrade.php, обновление перезаписывает модифицированные файлы в /bitrix/components/bitrix/. Никто не знает, какие компоненты были изменены. Сайт сломался, откат — из бекапа, даунтайм — 4 часа
• Обмен с 1С — агент обмена CCatalogImport::PreGenerateXML падает с ошибкой. Почему настроен нестандартно? Кто менял маппинг свойств? Без документации — реверс-инжиниринг на полдня
• Новый подрядчик — команда получает проект, видит 12 highload-блоков без описания назначения, кастомные таблицы b_custom_order_log и b_product_sync_history. Что хранят? Как связаны с инфоблоками? Ответ — нигде
• Рост команды — каждый новый разработчик три недели ходит за «тем, кто знает» вместо того, чтобы открыть документацию и работать

Техническая документация

Для разработчиков и DevOps — внутреннее устройство проекта:

Архитектура:

• Используемые модули Битрикс (sale, catalog, iblock, main, кастомные)
• Путь запроса: HTTP → nginx → urlrewrite.php → компонент → шаблон → ответ
• Серверная инфраструктура: конфигурация, топология, балансировка

Структура данных — самая критичная часть:

• Инфоблоки: типы (IBlock::TYPE_ID), разделы, свойства (PROPERTY_CODE), связи между инфоблоками через свойство типа «Привязка к элементам»
• Highload-блоки: таблица b_hlblock_entity, назначение каждого блока, структура полей, пользовательские поля (UF_*), индексы
• Кастомные таблицы в БД — зачем создавались, DDL, связи с b_iblock_element, b_sale_order и другими штатными таблицами
• Торговый каталог: типы цен (b_catalog_group), склады (b_catalog_store), правила корзины (b_sale_discount)

Кастомные разработки:

• Компоненты в /local/components/ — назначение, class.php, входные параметры (.parameters.php), шаблоны, зависимости
• Модули в /local/modules/ — API, события, установочные скрипты
• Обработчики событий — список всех AddEventHandler/registerEventHandler с описанием: какое событие, что делает, критичность
• Агенты (b_agent) — расписание, функционал, какие нельзя останавливать (обмен с 1С, рассылки, очистка корзин)
• Изменённые файлы ядра — полный список. При обновлении bitrix/ эти файлы будут перезаписаны

Интеграции:

• Обмен с 1С: настройки модуля catalog → «Обмен с 1С», формат CommerceML, расписание CCatalogImport, маппинг свойств, подводные камни (кодировки, таймауты, размер import.xml)
• Платёжные системы: обработчики в sale.handlers, режимы работы (тест/бой), URL для callback
• Службы доставки: профили в sale.delivery, алгоритмы расчёта, API-ключи
• CRM, маркетплейсы, внешние API: эндпоинты, механизмы аутентификации, частота синхронизации

Пользовательские инструкции

Для контент-менеджеров и администраторов:

Руководство контент-менеджера:

• Управление каталогом: создание элементов инфоблока, заполнение свойств, работа с разделами. Какие поля обязательны, какие влияют на отображение на сайте
• Изображения: допустимые размеры (авторесайз настроен или нет?), форматы, процесс загрузки в DETAIL_PICTURE и PROPERTY_GALLERY
• Акции и скидки — как настроить правило корзины в «Маркетинг» → «Правила работы с корзиной», не сломав ценообразование. Проверка через тестовый заказ

Руководство администратора:

• Пользователи: группы (b_group), права доступа к модулям и инфоблокам
• Обработка заказов: статусы (b_sale_status), оплата, возвраты
• Бекап через «Настройки» → «Резервное копирование» — с оговоркой, что для больших проектов штатный бекап не справляется

Формат:

• Пошагово с нумерацией
• Скриншоты с аннотациями — стрелки, выделения, подписи
• FAQ из реальных вопросов, собранных при обучении
• Видеоинструкции для нетривиальных операций (по запросу)

API-документация

Для проектов с кастомным REST API:

• Все эндпоинты: метод, URL, назначение, параметры (обязательные/опциональные), формат ответа
• Аутентификация: механизм получения токена, TTL, обновление
• Rate limiting: лимиты, HTTP-коды при превышении
• Примеры — рабочие cURL-команды, не теоретические

Инструменты: Swagger/OpenAPI для интерактивной документации, Postman Collection для тестирования.

Архитектурные схемы

Одна схема заменяет 10 страниц текста:

• Инфраструктура — серверы, сети, балансировщик, БД (master-slave?), Redis, CDN. Физическая и логическая топология
• Компоненты — модули Битрикс, кастомные компоненты в /local/, внешние сервисы, связи
• ER-диаграмма — таблицы b_iblock_element, b_sale_order, highload-блоки, кастомные таблицы. Поля, связи, индексы. Особенно критично для кастомных таблиц, которых нет в документации Битрикс
• Потоки данных — как информация движется между Битрикс, 1С, маркетплейсами, CRM, платёжными системами
• Карта сайта — что инфоблок, что статическая страница, что кастомный раздел на компоненте

Форматы: Draw.io, Mermaid (версионируется в Git), PlantUML.

Регламенты эксплуатации

Деплой:

• Пошаговая инструкция для staging и production
• Чек-лист после деплоя: проверка главной, каталога, чекаута, обмена с 1С
• Процедура отката — какой symlink переключить, какой бекап БД восстановить

Бекапы:

• Расписание: БД, upload/, конфигурации
• Где хранятся и сколько
• Процедура восстановления — проверенная, не теоретическая
• Тестовое восстановление раз в месяц

Обновление ядра:

• Staging → тестирование → production. Строго в таком порядке
• Проверка совместимости кастомных компонентов и изменённых файлов ядра
• bitrix/updates/ — что было обновлено

Инциденты:

• Классификация: сайт недоступен / ошибки 500 / сломался обмен с 1С / тормозит
• Контактные лица и зоны ответственности
• Шаблоны действий для каждого типа

Сроки

Документацию размещаем в Confluence, GitBook, Notion или Wiki — с разграничением доступа. Обновляем при каждом значимом изменении, потому что устаревшая документация хуже, чем её отсутствие — она создаёт ложную уверенность.