Документування 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 місяці. Залиште заявку на сайті — ми оцінимо ваш проєкт.