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

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

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

Наличие документации сокращает время адаптации нового разработчика в три раза — с трёх недель до одной. Без неё каждый второй проект сталкивается с даунтаймом при обновлении ядра или сбоях обмена с 1С. Более 10 лет опыта разработки на Битрикс и 50+ задокументированных проектов — это наш стандарт. Получите консультацию по вашему проекту: мы оценим объём работ за один день.

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

Конкретные ситуации, которые видим на каждом втором проекте:

• Обновление ядра — разработчик запускает 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 (согласно стандарту REST API) и 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С / тормозит
• Контактные лица и зоны ответственности
• Шаблоны действий для каждого типа

Что входит в работу

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

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

Сроки

Закажите документацию под ключ. Свяжитесь с нами — мы оценим ваш проект за один день. Устаревшая документация хуже её отсутствия: она создаёт ложную уверенность. Обновляем при каждом существенном изменении, чтобы информация оставалась точной.