Документирование 1С-Битрикс: инфоблоки, БД, интеграции, компоненты

Вы получаете проект на 1С-Битрикс с сотнями инфоблоков, десятками интеграций и кастомными компонентами — и ни одного документа. Первый день уходит на reverse engineering: ID 17 — каталог товаров, ID 23 — складские остатки. Без документации любое изменение — риск простоев. Мы документируем проект под ключ: от аудита до автогенерации схем. Опыт 10 лет в Битрикс-разработке, гарантия актуальности. Результат — полная карта проекта, готовая для передачи. Сокращаем время адаптации с недель до дней, снижаем затраты на поддержку на 50%.

Почему документирование — не роскошь, а необходимость?

В проектах без документации каждое обновление — лотерея. Инфоблоки переименовывают без пересчёта привязок, интеграции ломаются из-за смены токенов, новые разработчики тратят недели на изучение кода. Документирование окупается за 2–3 месяца за счёт ускорения типовых задач: правка шаблона вместо часа занимает 15 минут, а поиск ошибки — с дня до часа.

Как документировать инфоблоки?

Инфоблоки — сердце проекта. Документация начинается с автоматического извлечения метаданных. Скрипт на основе ORM собирает ID, коды, свойства и генерирует Markdown-файлы. Пример:

// Скрипт генерации документации по инфоблокам
$iblocks = \Bitrix\Iblock\IblockTable::getList([
    'select' => ['ID', 'NAME', 'CODE', 'IBLOCK_TYPE_ID', 'DESCRIPTION'],
    'order' => ['IBLOCK_TYPE_ID' => 'ASC', 'NAME' => 'ASC'],
])->fetchAll();

foreach ($iblocks as $iblock) {
    $props = \Bitrix\Iblock\PropertyTable::getList([
        'filter' => ['IBLOCK_ID' => $iblock['ID']],
        'select' => ['ID', 'NAME', 'CODE', 'PROPERTY_TYPE', 'USER_TYPE', 'LINK_IBLOCK_ID'],
        'order' => ['SORT' => 'ASC'],
    ])->fetchAll();

    // Генерируем Markdown-страницу для инфоблока
    echo "## {$iblock['NAME']} (ID: {$iblock['ID']}, CODE: {$iblock['CODE']})\n";
    // ...
}

Результат: таблицы свойств в git-репозитории, обновляемые при деплое. Пример документа для инфоблока:

Для каталогов от 10 000 товаров добавляем индексы по IBLOCK_ELEMENT.IBLOCK_ID и IBLOCK_ELEMENT_PROPERTY.VALUE — без документации такую оптимизацию легко пропустить.

Что входит в документирование интеграций?

Интеграции — точка отказа. Карта интеграций включает:

• Битрикс24 CRM ↔ Сайт: REST API + вебхуки, двустороннее, лиды из форм → B24, статусы заказов B24 → сайт. Токены в /bitrix/.settings_extra.php, переменная B24_WEBHOOK_URL. Обновление каждые 15 минут (агент \Integration\B24Agent::sync()). Логи: /local/logs/b24_integration.log.
• 1С:Предприятие ↔ Сайт: CommerceML 2.0, товары и остатки из 1С, заказы в 1С. Регламент — каждые 2 часа. При более 10 000 товаров обмен занимает свыше 30 минут — настроен split по файлам.

Для каждой интеграции указываем тип, направление, расположение токенов, расписание и логи. Подробнее — в документации Битрикс.

Документирование кастомной БД

Для кастомных таблиц — ERD-диаграмма и текстовое описание. Пример:

Индексы: (SPECIALIST_ID, DATE_FROM), (STATUS). Создаётся модулем local.booking в install/db/mysql/install.sql.

Как документировать компоненты?

Для кастомных компонентов — файл component.php с описанием параметров и отдельный Markdown с примерами:

<?$APPLICATION->IncludeComponent('local:catalog.filter.extended', '', [
    'IBLOCK_ID' => 5,
    'PRICE_TYPES' => [1, 2],
    'USE_RANGE' => true,
]);?>

Параметры компонента:

Известные ограничения: не работает с SKU.

Как мы документируем проект за 5 шагов

1. Аудит — инвентаризация инфоблоков, таблиц, модулей, интеграций. Выявляем недокументированные участки.
2. Автогенерация схем — скрипты извлекают структуру из БД и формируют Markdown.
3. Написание документов — описываем инфоблоки, интеграции, компоненты, БД. Добавляем примеры и ограничения.
4. Диаграммы — ERD и схемы взаимодействия в PlantUML или Mermaid.
5. Настройка процесса — правила обновления, шаблоны PR, автогенерация при деплое.

Актуализация документации

Документация без процесса обновления стареет. Правила:

• Изменение инфоблока → обновление файла инфоблока в том же PR.
• Добавление таблицы → описание в /docs/database/.
• Новая интеграция → обновление карты.
• Деплой → запуск автогенерации схем.

Этапы работы и сроки

Суммарно: 2–4 недели для проекта среднего масштаба. Получите консультацию — свяжитесь с нами, и мы подготовим индивидуальный план. Экономия времени на поддержке окупит документирование за 2–3 месяца. Оставьте заявку на сайте — мы оценим ваш проект.