project-handler — автоматизация ежемесячных сделок «Работы за месяц» в Битрикс24

Backend-модуль для Битрикс24, который каждый месяц сам формирует сделки на оплату выполненных работ: собирает затраченное время по проектам, разбивает его по ролям, считает стоимость по индивидуальным тарифам клиента и генерирует комплект документов (отчёт, счёт, акт).

---

Проблема

В агентстве расчёт с клиентами за месяц вёлся руками:

• время по проектам живёт в задачах Битрикс24, а деньги — в сделках; переносить часы в сделку приходилось вручную;
• в задачах время логируют все участники, а платить нужно по роли исполнителя задачи — при ручном переносе легко зачесть часы не той роли и не по тому тарифу;
• каждый клиент имеет свои ставки по ролям (frontend, backend, дизайнер, PM, контент-менеджер), и держать это в голове при расчёте нереально;
• при повторном запуске скрипта создавались дубликаты сделок и дублировались документы;
• отчёт для клиента, счёт и акт собирались отдельно — с расхождениями в суммах и формулировках.

Итог: часы терялись, суммы приходилось перепроверять, а закрытие месяца занимало день ручной работы.

Что делает система

Этап	Реализация
Найти клиентов к расчёту	Выборка компаний по наличию привязки к проекту; флаг UF_CRM_NOTIFY_DATE закрывает клиента на текущий месяц от повторного прогона
Собрать время	Часы по задачам проекта за предыдущий месяц
Определить роль	Должность / UF-поле пользователя → роль (mapPositionToRole, mapUserFieldToRole)
Зачесть часы	Всё время задачи за период засчитывается роли исполнителя задачи (RESPONSIBLE_ID)
Округлить	Меньше часа → 1 час; порог округления настраивается (MIN_HOUR_ROUNDING, ROUNDING_THRESHOLD)
Посчитать стоимость	Тариф роли из UF_CRM-полей компании, фолбэк — базовая ставка (DEFAULT_HOURLY_RATE)
Защититься от дублей	Проверка существующих сделок за период (CHECK_DUPLICATES, DUPLICATE_CHECK_DAYS)
Создать сделку	Сделка в воронке «Работы за предыдущий месяц»: название = проект, клиент/компания из исходной, ответственный = ответственный компании, комментарий = разбивка времени по ролям
Создать задачу	Задача на ответственном сделки с дедлайном и данными проекта
Уведомить	Уведомление о создании сделки ответственным из NOTIFY_USERS, ссылки на документы в таймлайне сделки
Сгенерировать документы	Отчёт / счёт / акт — автоматически при создании сделки

Жизненный цикл сделки в воронке: Проекты → Проверка → Отправка клиенту отчёта/счёта → Контроль оплаты → Оплата произведена (+ Провалена / Анализ причины).

Генерация документов

Два взаимозаменяемых генератора (переключаются в config.php):

• DocumentGenerator — документы через встроенный генератор документов Битрикс24: шаблоны отчёта/счёта/акта настраиваются в интерфейсе (REPORT_TEMPLATE_ID, INVOICE_TEMPLATE_ID, ACT_TEMPLATE_ID), документы хранятся в облаке и сразу доступны в карточке сделки. Внешних зависимостей нет.
• ExternalDocumentGenerator — серверная генерация: Excel-отчёт через PhpSpreadsheet, PDF через TCPDF, CSV как резервный вариант (EXTERNAL_EXCEL_GENERATION, EXTERNAL_PDF_GENERATION, EXTERNAL_CSV_GENERATION); результат складывается в generated_documents/ и получает ссылку в таймлайне сделки.

Данные в документы передаются из одного источника: позиции по ролям (кол-во часов, цена, сумма), задачи с датой и исполнителем, реквизиты договора и приложения. Поэтому отчёт, счёт и акт сходятся между собой по суммам и формулировкам.

Оба генератора работают по принципу «настраиваемо + с повторами»: таймауты, число попыток и паузы между ними задаются параметрами (*_RETRY_ATTEMPTS, *_RETRY_DELAY, *_TIMEOUT).

Архитектура

index.php                      # точка входа: обход компаний, запуск расчёта
class.php                      # ProjectCheck: выборка компаний/проектов, задачи
DealCreator.php                # ядро: время по ролям, тарифы, сделки, задача, уведомления
DocumentGenerator.php          # документы через генератор документов Битрикс24
ExternalDocumentGenerator.php  # документы через PhpSpreadsheet / TCPDF / CSV
UF_CRM_FieldChecker.php        # проверка и работа с пользовательскими полями CRM
config.php                     # вся конфигурация: тарифы, стадии, документы, логи, ретраи
set.php                        # подключение (вебхук Битрикс24)
docs/                          # подробная документация
generated_documents/           # сгенерированные отчёты
test_*.php                     # тестовые скрипты по каждому узлу системы

Ключевые решения:

• Тарифы в UF-полях компании, а не в коде — у каждой компании свои ставки по ролям (UF_CRM_FRONTEND_RATE, UF_CRM_BACKEND_RATE, UF_CRM_DESIGNER_RATE, UF_CRM_PM_RATE, UF_CRM_CONTENT_MANAGER_RATE), при отсутствии — базовая ставка.
• Безопасность повторного запуска — анти-дубли и флаг уведомления делают прогон идемпотентным: повторный запуск не создаёт вторую сделку за месяц.
• Отказоустойчивость к лимитам API — настраиваемые задержки между вызовами и батчами (API_DELAY_BETWEEN_CALLS, API_DELAY_BETWEEN_BATCHES), повторы при ошибках (API_MAX_RETRIES, API_RETRY_DELAY), таймаут запроса.
• Наблюдаемость — уровни логирования (LOG_LEVEL), отдельные переключатели для логирования создания сделок и расчёта времени, журнал ошибок.
• Вся конфигурация в одном файле — стадии воронки, округление, даты закрытия, документы, уведомления.

Результат

• Закрытие месяца перестало быть ручной работой: сделки на всех клиентов создаются одним прогоном php index.php.
• Стоимость считается по роли исполнителя задачи и тарифам конкретного клиента — расхождения между отчётом, счётом и актом убраны.
• Дубликаты сделок и повторные документы исключены.
• Логика покрыта тестовыми скриптами по каждому узлу: создание сделок, расчёт ролей и времени, проверка дублей, UF-поля, форматы данных, генерация документов.

Стек

PHP 7.4+ · Bitrix24 REST API (webhooks) · PhpSpreadsheet · TCPDF · воронки и UF-поля CRM

Быстрый старт

1. Скопировать модуль в структуру портала Битрикс24 (рядом должны быть ../logger/class.php и ../require/usualClass.php).
2. Указать вебхук в set.php.
3. Настроить config.php: ID воронки и стадий, тарифы и UF-поля, ID шаблонов документов, уведомления.
4. Проверить на тестовых сценариях:

   php test_deal_creation.php
   php test_duplicate_check.php
   php test_deal_80_document_generation.php

5. Запускать по расписанию в начале месяца: php index.php.

Подробности — в docs/README.md, docs/QuickStart.md, docs/DocumentGeneration_README.md, docs/UF_CRM_Fields_README.md.