# Руководство по работе с заказами с дедлайнами

## Введение

Система мониторинга заказов с дедлайнами предназначена для отслеживания заказов, у которых установлена дата окончания (дедлайн) в CRM Remonline. Это позволяет своевременно получать уведомления о приближающихся и просроченных заказах, а также отслеживать статистику выполнения заказов в срок.

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

1. **Просмотр заказов с дедлайнами**
   - Отображение списка всех заказов с установленной датой окончания
   - Фильтрация по типу заказов: все, просроченные, предстоящие
   - Цветовая индикация просроченных и срочных заказов

2. **Автоматическое оповещение о дедлайнах**
   - Регулярная проверка статуса заказов (каждые 30 минут)
   - Отправка уведомлений на устройства Яндекс Алиса при просрочке заказа
   - Отправка уведомлений, когда до дедлайна остается менее 60 минут
   
3. **Интеграция с внешними системами**
   - API для получения данных о заказах с дедлайнами в формате JSON
   - Возможность интеграции с другими системами мониторинга

## Как пользоваться

### Просмотр заказов с дедлайнами

1. Нажмите на кнопку "Заказы с дедлайнами" на главной странице
2. Используйте фильтры для отображения нужных заказов:
   - "Все заказы" - показать все заказы с дедлайнами
   - "Просроченные" - показать только просроченные заказы
   - "Предстоящие" - показать заказы, срок которых еще не истек

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

1. Перейдите в раздел "Управление автоматическими задачами"
2. Нажмите "Настроить задачу" напротив "Мониторинг заказов с дедлайнами"
3. Подтвердите настройку cron-задачи

### Тестирование уведомлений

1. Нажмите на кнопку "Тест оповещений о дедлайнах" на главной странице
2. Заполните форму тестирования:
   - Выберите устройство для отправки уведомления
   - Выберите тип уведомления (просроченный или срочный заказ)
   - Укажите тестовые данные заказа
3. Нажмите "Отправить тестовое уведомление"

## Описание API

Для получения данных о заказах с дедлайнами в формате JSON используйте следующий URL:

```
https://ваш-домен.ru/show_orders_with_deadline.php?format=json
```

Дополнительные параметры:
- `filter=all` - все заказы (по умолчанию)
- `filter=overdue` - только просроченные заказы
- `filter=upcoming` - только предстоящие заказы

Пример ответа:
```json
{
  "success": true,
  "message": "Найдено заказов с датой окончания: 5",
  "orders": [
    {
      "id": 12345,
      "number": "A-123",
      "client": "Иванов Иван",
      "device": "iPhone 13",
      "status": "В работе",
      "created_at": 1684123456789,
      "deadline_timestamp": 1684234567890,
      "deadline_formatted": "16.05.2023 15:42",
      "minutes_to_deadline": 120,
      "is_overdue": false,
      "engineer_name": "Чугунов Сергей",
      "engineer_id": 157324,
      "engineer_location": "Горького2"
    },
    // ...
  ],
  "timestamp": 1684123456,
  "count": 5
}
```

## Техническая информация

### Расположение файлов

- `show_orders_with_deadline.php` - основной файл для просмотра заказов с дедлайнами
- `cron_jobs/check_deadline_orders.php` - скрипт для автоматической проверки дедлайнов
- `test_deadline_notifications.php` - страница для тестирования оповещений
- `setup_deadline_cron.php` - скрипт для настройки автоматической задачи

### Логирование

Все действия по проверке заказов с дедлайнами фиксируются в следующих журналах:
- `/logs/deadline_check.log` - основной журнал проверки дедлайнов
- `/logs/cron_deadline_check.log` - журнал выполнения cron-задачи
- `/logs/test_deadline_notifications.log` - журнал тестирования оповещений

## Рекомендации

1. **Корректно указывайте даты окончания** - убедитесь, что в Remonline для заказа установлен правильный срок выполнения (поле "Дата окончания" или "estimated_done_at")
2. **Проверяйте назначенных инженеров** - уведомления о дедлайнах отправляются на устройства, соответствующие локации назначенного инженера
3. **Регулярно проверяйте журналы** - для диагностики проблем с отправкой уведомлений

## Техническая информация по обработке временных меток

Система обрабатывает две возможные метки времени для определения дедлайна заказа:

1. `estimated_done_at` - поле с приоритетом, содержит временную метку в миллисекундах
2. `deadline_timestamp` - используется, если estimated_done_at отсутствует

Обе метки времени ожидаются в формате миллисекунд (UNIX timestamp * 1000) и конвертируются в секунды при необходимости для совместимости с PHP-функциями обработки дат.

### Пример кода обработки

```php
// Преобразуем миллисекунды в секунды для корректной работы с датами
$estimated_done_at = $order->estimated_done_at / 1000;
```

### Тестирование обработки дедлайнов

Для проверки правильности обработки временных меток вы можете использовать скрипт `test_deadline_processing.php`, который показывает результат преобразований и вычислений для тестового заказа.