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

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

Проект на Бітрікс без документації — це фортеця, яку наступний розробник штурмуватиме кілька тижнів. Особливо болісно: нестандартні компоненти з перевантаженими параметрами, модулі з недокументованими залежностями, кастомні таблиці БД без схеми, агенти з неочевидним розкладом. Документування Бітрікс-проекту — це не написання текстів, це інженерна робота з вилучення та структурування знань із коду.

Що документувати в першу чергу

Не все однаково важливо. Пріоритети:

Критичне (без цього не можна працювати з проектом):

• Структура інфоблоків: ID, типи властивостей, прив'язки
• Кастомні таблиці БД: схема, призначення, зв'язки
• Нестандартні компоненти та їхні параметри
• Інтеграції: що з чим пов'язано, які токени використовуються
• Процеси розгортання та конфігурації

Важливе (потрібно для розвитку):

• Бізнес-логіка кастомних модулів
• Алгоритми нетривіальних розрахунків (ціни, знижки)
• Точки розширення: події, обробники

Корисне (добре мати):

• Опис стандартного функціоналу Бітрікс, який налаштовувався
• Причини нестандартних рішень («чому зроблено саме так»)

Документування інфоблоків

Інфоблоки — серце Бітрікс-проекту. Типова проблема: ID інфоблоку 17 — що це? Рішення: автоматична генерація документації з метаданих БД.

// Скрипт генерації документації за інфоблоками
$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";
    // ...
}

Результат: Markdown-файли з таблицями властивостей, які можна зберігати в git-репозиторії та оновлювати скриптом.

Приклад документа для інфоблоку:

## Каталог товарів (ID: 5, CODE: catalog)

**Тип:** catalog | **Сайт:** s1

### Властивості

| Код | Назва | Тип | Особливості |
|---|---|---|---|
| VENDOR_CODE | Артикул | S (рядок) | Обов'язкове, унікальне |
| BRAND | Бренд | E (прив'язка) | → Інфоблок ID 8 (Бренди) |
| WEIGHT | Вага (г) | N (число) | Для розрахунку доставки |
| IMAGES | Додаткові фото | F (файл) | Multiple |

Документування кастомної БД

Для кастомних таблиць — ERD-діаграма + текстовий опис. Мінімум:

## Таблиця `booking_slots`

**Призначення:** Часові слоти для запису на послуги. Створюється модулем `local.booking`.

| Поле | Тип | Опис |
|---|---|---|
| ID | INT AUTO_INCREMENT | PK |
| SPECIALIST_ID | INT | FK → b_user.ID |
| SERVICE_ID | INT | FK → b_iblock_element.ID (ІБ 12) |
| DATE_FROM | DATETIME | Початок слоту |
| DATE_TO | DATETIME | Кінець слоту |
| STATUS | ENUM('free','booked','blocked') | Поточний статус |
| BOOKING_ID | INT NULL | FK → bookings.ID при STATUS=booked |

**Індекси:** `(SPECIALIST_ID, DATE_FROM)`, `(STATUS)`
**Створюється:** При встановленні модуля в `local/modules/local.booking/install/db/mysql/install.sql`

Документування компонентів

Для кастомних компонентів — файл component.ru.php з описом параметрів (стандарт Бітрікс), плюс окремий Markdown із прикладами використання:

## Компонент `local:catalog.filter.extended`

**Шлях:** `/local/components/local/catalog.filter.extended/`
**Призначення:** Розширений фільтр каталогу з підтримкою діапазонів і множинного вибору.

### Параметри

| Параметр | Тип | За замовчуванням | Опис |
|---|---|---|---|
| IBLOCK_ID | int | — | ID інфоблоку каталогу (обов'язково) |
| PRICE_TYPES | array | [1] | ID типів цін для фільтра |
| USE_RANGE | bool | true | Увімкнути фільтр за діапазоном цін |
| AJAX_MODE | bool | true | Оновлення без перезавантаження сторінки |

### Приклад підключення
```php
<?$APPLICATION->IncludeComponent('local:catalog.filter.extended', '', [
    'IBLOCK_ID' => 5,
    'PRICE_TYPES' => [1, 2],
    'USE_RANGE' => true,
]);?>

Відомі обмеження

• Не працює з торговими пропозиціями (SKU) — лише основні товари

### Документування інтеграцій

Карта інтеграцій — обов'язковий документ для проекту із зовнішніми системами:

```markdown
## Карта інтеграцій

### Битрікс24 CRM ↔ Сайт
- **Тип:** REST API + вебхуки
- **Напрямок:** двосторонній
- **Що синхронізується:** ліди з форм → Б24, статуси замовлень Б24 → сайт
- **Токени:** у `/bitrix/.settings_extra.php`, змінна `B24_WEBHOOK_URL`
- **Розклад:** кожні 15 хвилин (агент `\Integration\B24Agent::sync()`)
- **Логи:** `/local/logs/b24_integration.log`

### 1С:Підприємство ↔ Сайт
- **Тип:** CommerceML 2.0 (стандартний обмін Бітрікс)
- **Напрямок:** товари та залишки з 1С, замовлення в 1С
- **Розклад:** кожні 2 години (налаштування в `/bitrix/admin/1c_exchange.php`)
- **Проблеми:** при > 10 000 товарів обмін займає > 30 хв, налаштовано split по файлах

Інструменти та формати

Markdown + Git — основний формат. Документація живе поряд із кодом у /docs/ репозиторію, оновлюється разом зі змінами.

Confluence/Notion — для документації, доступної менеджерам і клієнтам без доступу до git.

PHPDoc у коді — обов'язково для кастомних модулів і компонентів. Стандарт Бітрікс вимагає PHPDoc на методи класів.

Діаграми — PlantUML або Mermaid для ERD і схем взаємодії, можна рендерити прямо в Markdown-документах.

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

Документація без процесу оновлення швидко застаріває. Обов'язкові правила:

• Зміна інфоблоку → оновлення Markdown-файлу інфоблоку в тому ж PR
• Додавання кастомної таблиці → додавання її опису в /docs/database/
• Додавання інтеграції → оновлення карти інтеграцій
• Деплой → запуск скрипту автогенерації актуальних схем

Етапи роботи з документування

Загалом: 2–4 тижні для проекту середнього масштабу.