Послуги з документації проектів на 1С-Бітрікс

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

Розробник звільнився. Новий відкриває init.php на 2000 рядків — бачить 47 обробників подій через AddEventHandler, ланцюжок агентів у b_agent і кастомний модуль без жодного коментаря. На вникання йде місяць. Документація цей місяць перетворює на три дні. Ми створюємо документацію 1С-Бітрікс для проєктів будь-якої складності: від архітектурних схем до покрокових інструкцій для контент-менеджера.

Наявність документації скорочує час адаптації нового розробника втричі — з трьох тижнів до одного. Проєкт без неї вимагає в 3 рази більше часу на введення новачка; даунтайми при оновленні ядра трапляються на 60% частіше. Понад 10 років досвіду розробки на Бітрікс і 50+ задокументованих проєктів — це наш стандарт. Економія на онбордингу одного розробника може сягати 90 000 грн — саме стільки коштує місяць простою без документації. Зв’яжіться з нами для оцінки вашого проєкту за один день.

Чому документація критична?

Конкретні ситуації, які бачимо на кожному другому проєкті:

• Оновлення ядра — розробник запускає bitrix/tools/upgrade.php. Оновлення перезаписує модифіковані файли в /bitrix/components/bitrix/. Ніхто не знає, які компоненти були змінені. Сайт зламався. Відкат — з бекапу. Даунтайм — 4 години.
• Обмін з 1С — агент обміну CCatalogImport::PreGenerateXML падає з помилкою. Налаштування нестандартне. Хто змінював маппінг властивостей? Без документації — реверс-інжиніринг на пів дня.
• Новий підрядник — команда отримує проєкт з 12 highload-блоками без опису призначення, кастомними таблицями b_custom_order_log і b_product_sync_history. Призначення та зв’язки з інфоблоками ніде не зафіксовані. Це затягує введення нового розробника на два тижні.
• Зростання команди — кожен новий розробник три тижні ходить за «тим, хто знає», замість того щоб відкрити документацію і працювати.

Статистика наших проєктів: при наявності повної документації кількість інцидентів при оновленні модулів знижується на 50%, а середній час виправлення помилки в продакшні скорочується вдвічі.

Один із кейсів — інтернет-магазин з 500 000 товарів, обмін з 1С, три платіжні системи, інтеграція з СДЕК. Без документації новий розробник розбирався 4 тижні. Ми задокументували архітектуру даних (інфоблоки, HR-блоки, кастомні таблиці), REST API, регламенти деплою та бекапів. Після цього введення новачка зайняло 1 тиждень, а вартість підтримки зменшилася на 35% за рахунок зниження часу на налагодження. За стандартом CommerceML (описано у Вікіпедії) обмін з 1С — одна з найчастіших точок збою. Документація знімає цю проблему.

Як структурувати документацію для розробників?

Технічна документація

Для розробників і 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 сторінок тексту. Формати: Draw.io, Mermaid (версіонується в Git), PlantUML.

• Інфраструктура — сервери, мережі, балансувальник, БД (master-slave?), Redis, CDN. Фізична та логічна топологія
• Компоненти — модулі Бітрікс, кастомні компоненти в /local/, зовнішні сервіси, зв’язки
• ER-діаграма — таблиці b_iblock_element, b_sale_order, highload-блоки, кастомні таблиці. Поля, зв’язки, індекси. Особливо критично для кастомних таблиць, яких немає в документації Бітрікс
• Потоки даних — як інформація рухається між Бітрікс, 1С, маркетплейсами, CRM, платіжними системами
• Мапа сайту — що інфоблок, що статична сторінка, що кастомний розділ на компоненті

Регламенти експлуатації

Деплой:

• Покрокова інструкція для staging і production
• Чек-лист після деплою: перевірка головної, каталогу, чекауту, обміну з 1С
• Процедура відкату — який symlink переключити, який бекап БД відновити

Бекапи:

• Розклад: БД, upload/, конфігурації
• Де зберігаються і скільки
• Процедура відновлення — перевірена, не теоретична
• Тестове відновлення раз на місяць

Оновлення ядра:

• Staging → тестування → production. Строго в такому порядку
• Перевірка сумісності кастомних компонентів і змінених файлів ядра
• bitrix/updates/ — що було оновлено

Інциденти:

• Класифікація: сайт недоступний / помилки 500 / зламався обмін з 1С / гальмує
• Контактні особи та зони відповідальності
• Шаблони дій для кожного типу

Як відбувається створення документації?

1. Аналіз проєкту (1–2 дні) — вивчаємо код, БД, конфігурації, спілкуємося з командою.
2. Збір інформації (2–5 днів) — фіксуємо архітектуру, інтеграції, бізнес-процеси.
3. Написання та валідація — формуємо технічну документацію, інструкції, схеми. Кожен текст перевіряє розробник, який брав участь у проєкті.
4. Розміщення — Confluence, GitBook, Notion або Wiki з розмежуванням доступу.
5. Гарантія актуальності — оновлюємо документацію при кожній значущій зміні (новий модуль, зміна обміну, оновлення ядра).

Створення документації 1С-Бітрікс за цим алгоритмом забезпечує точність і повноту — жоден кастомний агент або змінений файл ядра не залишиться незадокументованим. Замовте попередню оцінку документації — ми проаналізуємо ваш проєкт і назвемо строки та обсяг робіт.

Що входить в роботу

Ми готуємо повний комплект документації для вашого проєкту:

• Технічна документація з описом архітектури, структури даних, кастомних розробок та інтеграцій
• Користувацькі інструкції для контент-менеджерів і адміністраторів
• API-документація у форматі Swagger/OpenAPI з Postman-колекцією
• Архітектурні схеми (інфраструктура, ER-діаграми, потоки даних)
• Регламенти експлуатації (деплой, бекапи, оновлення ядра, інциденти)
• Розміщення в Confluence, GitBook, Notion або Wiki з розмежуванням доступу
• Гарантія актуальності — оновлюємо документацію при кожній значущій зміні

Джерело: власна методологія, апробована на 50+ проєктах на 1С-Бітрікс.

Строки

Замовте документацію під ключ — зв’яжіться з нами для безкоштовної оцінки вашого проєкту за 1 день. Застаріла документація гірша за її відсутність: вона створює хибну впевненість. Ми оновлюємо матеріали при кожній суттєвій зміні, щоб інформація залишалася точною. Отримайте консультацію прямо зараз.