# Автоматизований check-call — специфікація процесу

Файли: `checkcall-bpmn.svg` (основний процес), `checkcall-exception-subprocess.svg` (розгорнутий підпроцес «Обробка винятків»), `checkcall.bpmn` (BPMN 2.0 XML із drill-down у підпроцес), `checkcall-exception.bpmn` (колаборація підпроцесу з message flows до перевізника й клієнта), `checkcall_bpmn_generator.py` (генератор усіх чотирьох файлів з однієї моделі).

## Пули та лейни

| Лейн | Роль | Автономність |
|---|---|---|
| Оркестратор трекінгу (система) | таймери, збір позиції, геозони, оновлення TMS і сповіщення клієнта | автопілот у межах правил |
| AI check-call агент | голосовий дзвінок водієві, SMS/email fallback, парсинг відповіді | автопілот із логуванням кожної взаємодії |
| Диспетчер (людина) | підпроцес обробки винятку, рішення, ескалація причини | human-in-the-loop |

## Тригери основного процесу

| Тригер | Тип події | Хід |
|---|---|---|
| Вантаж призначено перевізнику | start event | активація плану трекінгу: геозони pickup/delivery, вікна, частота контактів |
| Інтервал моніторингу | timer (15 хв; 2 хв при ELD) | запит позиції з ELD / GPS / застосунку водія |
| Геозона: прибуття або виїзд | message event | авто check-in/check-out, timestamp, сповіщення зацікавлених сторін |
| Тиша трекінгу > 30 хв | data-driven | голосовий check-call до водія |
| Очікування 15 хв після SMS | timer | друга спроба, далі вихід у підпроцес обробки винятку |

## Шлюзи основного процесу

- `Дані актуальні?` — якщо позиція свіжа, дзвінка немає; дзвінок використовується лише для відновлення трекінгу.
- `Відхилення від плану?` — порівняння фактичної позиції з очікуваним темпом за вікнами завантаження та доставки.
- `Водій відповів?` — каскад каналів: дзвінок → SMS/email → очікування → друга спроба → підпроцес.
- `Виявлено виняток?` — вихід у підпроцес «Обробка винятку».

## Підпроцес «Обробка винятку»

Старт: подія `Виняток зареєстровано`. Перша задача — класифікація за типом, джерелом і впливом на SLA, далі XOR-шлюз `Тип винятку?` розводить сім гілок.

| Тип винятку | Як детектується | Хід у підпроцесі |
|---|---|---|
| Пропущене вікно pickup або delivery | appointment-час проти фактичного ETA | перепризначити appointment зі складом або отримувачем → оновити вікно доставки та ETA у TMS |
| Втрата трекінгу, водій недоступний | тиша трекінгу + дві невдалі спроби контакту | дзвінок перевізнику для відновлення зв'язку → пошук заміни або процедура lost load |
| Поломка, ДТП, потреба в recovery | відповідь водія або нульовий рух поза зоною | залучити roadside assistance, оцінити стан вантажу → організувати recovery truck і перевантаження |
| Затримка в дорозі: HOS, трафік, погода | відставання від очікуваного темпу | перерахувати ETA з урахуванням HOS і трафіку → проактивно повідомити клієнта |
| Detention, простій, lumper | геозона-івент без виїзду понад норму | запустити таймери detention і простою → погодити accessorial charge із клієнтом |
| Розбіжність документів, OS&D | POD/BOL не збігаються або пошкодження | запросити фото BOL, POD і опис розбіжності → відкрити OS&D claim, повідомити страховика |
| Комплаєнс перевізника | прострочена ліцензія, страховка, ознаки double-brokering | заблокувати вантаж, вимагати документи → перевірити ознаки double-brokering у профілі |

Далі гілки зливаються: `Задокументувати причину, тег винятку й рішення в TMS` → шлюз `Ризик SLA?` (за потреби узгодження компенсації та нового SLA) → шлюз `Рейс можна продовжити?`.

Виходи підпроцесу:
- `Виняток закрито, моніторинг триває` — звичайна кінцева подія; на верхньому рівні повертає процес у таймер моніторингу.
- `Рейс неможливо продовжити` — error end event; на верхньому рівні його ловить гранична подія помилки на підпроцесі та веде до кінцевої події `Рейс закрито з винятком`.

Граничні події на підпроцесі:
- **Помилка** (переривальна) — рейс закривається з винятком.
- **Таймер `Не вирішено за 60 хв`** (непереривальна) — паралельна ескалація керівнику зміни, підпроцес продовжує роботу.

## Обмін повідомленнями з контрагентами

Колаборація `checkcall-exception.bpmn` додає два зовнішні учасники (black-box participants): `Перевізник, водій, склад` і `Клієнт (вантажовідправник)`. Взаємодія з ними виражена message flows, а не sequence flows: це зовнішні учасники, чиї внутрішні процеси нам не належать.

| Message flow | Напрям | Задача-джерело або приймач | Канал реалізації |
|---|---|---|---|
| Новий слот appointment | до перевізника й складу | Перепризначити appointment | email або портал appointment |
| Запис зв'язку з водієм | до перевізника | Дзвінок перевізнику | голосовий дзвінок диспетчера або AI-агента |
| Наряд roadside і recovery | до перевізника | Залучити roadside assistance | телефон із письмовим підтвердженням |
| Запит фото BOL і POD | до перевізника й водія | Запросити фото документів | SMS або застосунок водія з посиланням на завантаження |
| Фото BOL, POD, коментар водія | від перевізника | Запросити фото документів | вхідне повідомлення з вкладеннями, автоприкріплення до вантажу |
| Запит ліцензії та страховки | до перевізника | Заблокувати вантаж, вимагати документи | email із дедлайном, блокування в TMS до отримання |
| Нове вікно доставки та ETA | до клієнта | Оновити вікно доставки та ETA у TMS | автосповіщення з порталу або EDI 214 |
| Повідомлення про затримку | до клієнта | Проактивно повідомити клієнта | email або портал, до звернення клієнта |
| Погодження accessorial | до клієнта | Погодити accessorial charge | email із таймерами detention як підтвердженням |
| Повідомлення про OS&D claim | до клієнта | Відкрити OS&D claim | email плюс запис claim у TMS |
| Пропозиція компенсації та SLA | до клієнта | Узгодити компенсацію та новий SLA | email або портал, фіксація погодження в TMS |

Правила моделювання: message flow завжди перетинає межу пулу й завершується на межі чорної скриньки, а не на прив'язаній задачі контрагента. Відсутня відповідь не блокує послідовність усередині підпроцесу — очікування та ескалація живуть на граничних подіях основного процесу.

## KPI процесу

| Метрика | Призначення |
|---|---|
| Частка вантажів без жодного ручного дзвінка | основний показник автоматизації |
| Answer rate голосового агента, % | якість каналу |
| Час від тиші трекінгу до відновленої позиції | ефективність fallback-каскаду |
| Частка ескалацій із реальним винятком | точність правил (низька = шум) |
| Розподіл винятків за сімома типами | де саме процес ламається найчастіше |
| Частка винятків, вирішених у межах 60 хв | навантаження на граничний таймер і керівника зміни |
| Середній час відповіді перевізника на запит документів | якість каналу до перевізника |
| Частка клієнтських повідомлень, надісланих до звернення клієнта | проактивність комунікації |
| Кількість активних контактів на диспетчера за день | базова лінія 80–120 при 40 активних вантажах |

## Джерела логіки

- [FleetWorks: Check-Call Automation for Freight Brokers](https://www.fleetworks.ai/resources/check-call-automation) — точки контакту, каскад каналів, перелік критеріїв ескалації (пропущене вікно, недоступний водій, поломка, затримка, неочікувана відповідь).
- [GoFast Freight: How to Automate Check Calls](https://www.gofastfreight.com/blog/how-to-automate-check-calls-freight-brokerage) — рівні автоматизації, exception-only логіка, базові обсяги дзвінків.
- [Descartes MacroPoint OpsForce](https://macropoint.com/features/agentic-ai-opsforce/) — дзвінок при втраті трекінгу, окремий агент для підтвердження геозон-подій.
- [Tai TMS Track & Trace Agent](https://tai-software.com/tai-tms-introduces-ai-track-trace-agent-making-check-calls-a-thing-of-the-past/) — правила частоти дзвінків, автозапис результату та перехід статусу в `Delivered`.
- [Vektor TMS LiveVision](https://vektortms.com/brokers/live-vision) — геозон-тригери `arrived`, `departed`, `approaching`, `late`, оновлення GPS кожні 2 хв.

---

**Дизайн-концепція, не підключений сервіс.** Ця модель описує, як міг би працювати автоматизований check-call; жодного реального AI-дзвінка, TMS-інтеграції чи SMS-шлюзу в демо-версії сайту Trans-Atlas не підключено.