Документирование проекта на 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 недели для проекта среднего масштаба.