Система автоматического создания сделок "Работы за предыдущий месяц"

Описание

Система автоматически создает сделки в воронке "Работы за предыдущий месяц" на основе учета времени по проектам. Сделки создаются в первый день каждого месяца для всех проектов, где было затрачено время в предыдущем месяце.

Все затраченное время в задаче за период целиком засчитывается роли исполнителя задачи (RESPONSIBLE_ID).

Функциональность

Основные возможности:

• ✅ Автоматическое создание сделок в первый день месяца
• ✅ Учет времени с разбивкой по ролям (программист, дизайнер и т.д.)
• ✅ Время задачи засчитывается исполнителю задачи
• ✅ Округление времени (меньше часа = 1 час)
• ✅ Автоматический расчет стоимости по тарифам
• ✅ Проверка на дубликаты сделок
• ✅ Уведомления о создании сделок
• ✅ Подробное логирование всех операций
• ✅ Автоматическая генерация документов (отчеты, счета, акты)

Поля создаваемой сделки:

• Название - название проекта
• Стадия - первая стадия "проекты"
• Сумма - автоматический расчет по тарифам
• Дата завершения - до 6 числа текущего месяца
• Дата начала - первое число месяца (рабочий день)
• Клиент - из исходной компании
• Компания - из исходной компании
• Ответственный - ответственный из исходной компании (ASSIGNED_BY_ID), если не задан - администратор
• Комментарий - разбивка времени по ролям

Структура файлов

project-handler/
├── index.php                    # Основной скрипт
├── class.php                    # Класс ProjectCheck
├── DealCreator.php              # Класс для создания сделок
├── DocumentGenerator.php        # Класс для генерации документов через Bitrix24 (устаревший)
├── ExternalDocumentGenerator.php # Класс для генерации документов через внешние библиотеки (Excel, PDF, CSV)
├── UF_CRM_FieldChecker.php      # Класс для работы с UF полями
├── config.php                   # Конфигурация системы
├── set.php                      # Настройки подключения
├── docs/                        # Документация
│   ├── README.md                # Основная документация
│   ├── QuickStart.md            # Быстрый старт
│   ├── DocumentGeneration_README.md # Документация по генерации документов
│   ├── UF_CRM_Fields_README.md  # Документация по UF полям
│   └── EXTERNAL_GENERATOR_MIGRATION.md # Миграция на внешние библиотеки
├── external_libraries/          # Внешние библиотеки (PhpSpreadsheet, TCPDF)
├── generated_documents/          # Сгенерированные документы
├── logs/                        # Логи системы
└── test_*.php                   # Тестовые скрипты

Настройка

1. Конфигурация тарифов (config.php)

Система использует индивидуальные тарифы для каждой компании через UF_CRM поля:

// Базовая ставка по умолчанию (руб/час)
define('DEFAULT_HOURLY_RATE', 1000);

// Индивидуальные тарифы в UF_CRM полях компании:
// UF_CRM_FRONTEND_RATE - ставка Front-end разработчика
// UF_CRM_BACKEND_RATE - ставка Back-end разработчика  
// UF_CRM_DESIGNER_RATE - ставка Дизайнера
// UF_CRM_PM_RATE - ставка Проект-менеджера
// UF_CRM_CONTENT_MANAGER_RATE - ставка Контент-менеджера

2. Настройки округления времени

define('MIN_HOUR_ROUNDING', 1); // Минимальное округление до часа
define('ROUNDING_THRESHOLD', 0.1); // Порог для округления (10 минут)

3. Настройки генерации документов

// ID шаблонов документов в Bitrix24 (создайте в CRM -> Настройки -> Шаблоны документов)
define('REPORT_TEMPLATE_ID', 0); // ID шаблона Excel отчета
define('INVOICE_TEMPLATE_ID', 0); // ID шаблона счета
define('ACT_TEMPLATE_ID', 0); // ID шаблона акта

// Настройки договоров по умолчанию
define('DEFAULT_CONTRACT_NUMBER', '№ ТЕХНОРЕСУРС/23');
define('DEFAULT_CONTRACT_DATE', '12.12.23');
define('DEFAULT_APPENDIX_NUMBER', '№ 3');
define('DEFAULT_APPENDIX_DATE', '16.05.24');

4. Настройки уведомлений

define('NOTIFY_ON_DEAL_CREATION', true); // Включить уведомления
define('NOTIFY_USERS', [1]); // ID пользователей для уведомлений

Использование

Автоматический режим

Система работает автоматически при запуске index.php в первый день месяца:

php index.php

Тестирование

Для тестирования функциональности используйте:

php test_deal_creation.php

Тестовый скрипт покажет:

• Данные о времени по проекту
• Разбивку по ролям с тарифами
• Общую стоимость
• Возможность создания тестовой сделки

Логирование

Все операции записываются в лог-файлы:

• logs/akvilon_check.log - основной лог
• logs/deal_creation_test.log - лог тестирования

Примеры записей в логе:

{
    "type": "deal_creation",
    "status": "success",
    "original_deal_id": 123,
    "new_deal_id": 456,
    "project_id": 789,
    "project_name": "Название проекта",
    "total_hours": 15.5,
    "total_cost": 31000,
    "message": "Сделка успешно создана"
}

API методы

DealCreator::getProjectTimeData($projectId)

Получает данные о времени по проекту за предыдущий месяц.

Возвращает:

[
    'total_hours' => 15.5,
    'total_cost' => 31000,
    'roles_time' => [
        'Front-end разработчик' => [
            'hours' => 8,
            'minutes' => 30,
            'decimal_hours' => 8.5
        ],
        'Back-end разработчик #2' => [
            'hours' => 7,
            'minutes' => 0,
            'decimal_hours' => 7.0
        ]
        // ... другие роли исполнителей
    ]
]

DealCreator::createMonthlyWorkDeal($company, $projectTimeData)

Создает сделку "Работы за предыдущий месяц" с автоматической генерацией документов.

Параметры:

• $company - данные компании с привязанным проектом
• $projectTimeData - данные о времени по проекту

Возвращает:

[
    'status' => 'success',
    'deal_id' => 456,
    'message' => 'Сделка успешно создана'
]

DocumentGenerator::generateDocumentsForDeal($dealId, $company, $projectTimeData, $projectId)

Генерирует документы (отчет, счет, акт) для сделки через Bitrix24 Document Generator.

Параметры:

• $dealId - ID созданной сделки
• $company - данные компании
• $projectTimeData - данные о времени по проекту
• $projectId - ID проекта

Возвращает:

[
    'status' => 'success',
    'documents' => [
        'report' => ['id' => 789, 'name' => 'Отчет по задачам'],
        'invoice' => ['id' => 790, 'name' => 'Счет на оплату'],
        'act' => ['id' => 791, 'name' => 'Акт выполненных работ']
    ]
]

Требования

• PHP 7.4+
• Доступ к Bitrix24 API
• Настроенный webhook для Bitrix24

Безопасность

• Проверка на дубликаты сделок
• Валидация входных данных
• Обработка ошибок API
• Логирование всех операций

Мониторинг

Система отправляет уведомления в Bitrix24 при:

• Успешном создании сделки
• Ошибках при создании
• Пропуске создания (нет времени)

Расширение функциональности

Добавление новых ролей

1. Добавьте UF_CRM поле для тарифа роли в компаниях
2. Обновите функцию getRoleRateField() в config.php
3. Обновите логику определения ролей в mapPositionToRole() в DealCreator.php

Изменение тарифов

1. Индивидуальные тарифы: Заполните UF_CRM поля в карточке компании
2. Общий тариф: Измените DEFAULT_HOURLY_RATE в config.php

Настройка уведомлений

Измените NOTIFY_USERS в config.php для добавления получателей уведомлений

Настройка генерации документов

1. Создайте шаблоны документов в Bitrix24 (CRM → Настройки → Шаблоны документов)
2. Укажите ID шаблонов в config.php:
   • REPORT_TEMPLATE_ID - для Excel отчета
   • INVOICE_TEMPLATE_ID - для счета
   • ACT_TEMPLATE_ID - для акта

Устранение неполадок

Сделка не создается

1. Проверьте логи на наличие ошибок
2. Убедитесь, что есть затраченное время в предыдущем месяце
3. Проверьте настройки webhook

Неправильный расчет стоимости

1. Проверьте тарифы в config.php
2. Убедитесь, что роли правильно определяются

Дубликаты сделок

1. Проверьте настройку CHECK_DUPLICATES
2. Убедитесь, что фильтр по датам работает корректно

Дополнительные возможности

Веб-интерфейс для UF полей

Система включает веб-интерфейс для управления пользовательскими полями:

• Главная страница: index_fields.php
• Проверка полей: web_check_fields.php

Тестирование

• Основное тестирование: test_deal_creation.php
• Тест ролей: test_combined_roles.php
• Проверка UF полей: check_uf_crm_company_fields.php

Поддержка

При возникновении проблем:

1. Проверьте логи в папке logs/
2. Запустите тестовый скрипт для диагностики
3. Проверьте настройки в config.php
4. Используйте веб-интерфейс для проверки UF полей
5. Обратитесь к документации в папке docs/

Связанная документация

• Быстрый старт - пошаговая настройка системы
• Генерация документов - настройка шаблонов документов
• UF поля CRM - работа с пользовательскими полями