Послуги з документації проектів на 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 — з розмежуванням доступу. Оновлюємо при кожній значній зміні, бо застаріла документація гірша за її відсутність — вона створює хибну впевненість.