> ## Documentation Index
> Fetch the complete documentation index at: https://mavrodi.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Життєвий цикл Доручення: статуси, дії та ваша роль

> Розберіться в кожному статусі Доручення — від DRAFT до RECEIVED, хто може діяти на кожному етапі та як працювати зі суперечками й ручним створенням Доручень.

Доручення — основна транзакційна одиниця в InviteBot. Воно повʼязує Інтент одного учасника (його пропозицію надати допомогу) з Запитом іншого учасника (його проханням отримати допомогу) та спрямовує відправника переказати певну суму отримувачу. Як Наставник, ви берете участь у критичних точках ухвалення рішень: розглядаєте нові Доручення перед надсиланням учаснику, можете відхиляти проблемні та контролюєте розвʼязання проблем.

<Note>
  Більшість Доручень система створює автоматично через заплановані завдання, зіставляючи сумісні Інтенти й Запити. Доручення також можна створювати вручну. В обох випадках діє той самий життєвий цикл.
</Note>

## Повний життєвий цикл

Доручення проходять визначену послідовність статусів. У кожного статусу є конкретні дійові особи, а дії запускають переходи.

```
DRAFT → NEW → ACCEPTED → PAID → RECEIVED
                              ↘ DISPUTE → RECEIVED
                                        ↘ CANCELED
         ↓          ↓
      REJECTED   REFUSED
DRAFT → CANCELED
```

## Статуси Доручення

### DRAFT

Доручення створене, але ще не активоване. Це відбувається, коли Наставник створює Доручення вручну командою `/order_add`.

**Хто може діяти:** Наставник, який створив Доручення.

**Доступні дії:**

* Перевести в NEW (активувати Доручення й надіслати в чергу розгляду)
* Скасувати (→ CANCELED, припиняє Доручення)

На цьому етапі Доручення не видно учаснику. Використовуйте цей крок, щоб перевірити деталі перед активацією.

***

### NEW

Доручення активне й чекає, поки Наставник тримача Інтенту розгляне його та надішле своєму учаснику.

**Хто може діяти:** Наставник тримача Інтенту.

**Доступні дії:**

* Прийняти й надіслати учаснику (→ ACCEPTED)
* Відхилити (→ REJECTED)

Це найважливіша точка рішення в життєвому циклі. Тут ви переконуєтеся, що Доручення підходить вашому учаснику, перш ніж доручати йому переказ.

***

### ACCEPTED

Доручення надіслано учаснику (відправнику). Учасник бачить реквізити отримувача, і очікується, що він зробить переказ.

**Хто може діяти:** учасник (відправник); Наставник.

**Доступні дії:**

| Дійова особа | Дія                    | Результат  |
| ------------ | ---------------------- | ---------- |
| Учасник      | Підтвердити переказ    | → PAID     |
| Учасник      | Відмовитися виконувати | → REFUSED  |
| Наставник    | Відхилити              | → REJECTED |
| Наставник    | Відкликати             | → REFUSED  |

<Note>
  Які реквізити побачить учасник, залежить від того, чи є Запит системним, і чи верифікований учасник. Неверифікованим учасникам при першому переказі показуються спеціальні верифікаційні реквізити. Після верифікації вони бачать стандартні чи системні реквізити залежно від типу запиту.
</Note>

***

### PAID

Учасник підтвердив, що відправив переказ. Отримувачу тепер потрібно підтвердити надходження.

**Хто може діяти:** отримувач; адміністратори.

**Доступні дії:**

| Дійова особа | Дія                                        | Результат                                                                               |
| ------------ | ------------------------------------------ | --------------------------------------------------------------------------------------- |
| Отримувач    | Підтвердити надходження                    | → RECEIVED                                                                              |
| Отримувач    | Повідомити про неотримання                 | → DISPUTE                                                                               |
| Адмін        | Підтвердити надходження від імені учасника | → RECEIVED                                                                              |
| Адмін        | Скасувати Доручення                        | → REFUSED (також скасовує повʼязаний Інтент та інші відкриті Доручення за цим Інтентом) |

***

### RECEIVED

Отримувач підтвердив, що кошти надійшли. Це успішний фінальний статус.

**Хто може діяти:** подальші дії не потрібні.

**Що відбувається:** оновлюються баланси повʼязаних Інтентів і Запитів, усі сторони отримують сповіщення, обробляються застосовні винагороди MAVRO.

***

### REFUSED

Учасник відмовився виконати Доручення, або Наставник його відкликав. Це фінальний статус.

**Часті причини:**

* Учасник не може вчасно зробити переказ
* Технічні проблеми зі способом оплати
* Некоректні реквізити
* Особисті обставини

**Що відбувається:** система шукає заміщувального учасника для того самого Запиту. Сума Доручення повертається в пул зіставлення.

***

### REJECTED

Наставник відхилив Доручення. Це фінальний статус.

**Часті причини:**

* В учасника недостатньо коштів
* Учасник не готовий робити переказ
* Інтент уже повністю підтверджений
* Учасник недоступний або заблокував бота
* Допомогу ще не отримано (очікуються попередні надходження)

***

### CANCELED

Доручення скасовано. Зазвичай це відбувається зі статусу DRAFT або коли адміністратор втручається в активне Доручення.

***

### DISPUTE

Отримувач повідомив, що не отримав переказ, попри підтвердження оплати відправником. Цей статус вимагає розгляду.

**Хто може діяти:** адміністратори; Наставники можуть допомагати зі збором доказів.

**Доступні дії (лише адмін):**

| Дія                                          | Результат                                                                 |
| -------------------------------------------- | ------------------------------------------------------------------------- |
| Підтвердити надходження від імені отримувача | → RECEIVED                                                                |
| Скасувати Доручення                          | → REFUSED (також скасовує повʼязаний Інтент та відкриті Доручення за ним) |

***

## Матриця статусів і дій

| Статус   | Створювач Доручення (Наставник) | Наставник Інтенту             | Учасник (відправник)            | Отримувач                       | Адмін                  |
| -------- | ------------------------------- | ----------------------------- | ------------------------------- | ------------------------------- | ---------------------- |
| DRAFT    | Перевести в NEW, Скасувати      | —                             | —                               | —                               | Будь-яка               |
| NEW      | —                               | Прийняти/Надіслати, Відхилити | —                               | —                               | Будь-яка               |
| ACCEPTED | —                               | Відхилити, Відкликати         | Підтвердити оплату, Відмовитися | —                               | Будь-яка               |
| PAID     | —                               | —                             | —                               | Підтвердити, Відкрити суперечку | Підтвердити, Скасувати |
| DISPUTE  | —                               | —                             | —                               | —                               | Підтвердити, Скасувати |
| RECEIVED | —                               | —                             | —                               | —                               | Будь-яка               |
| REFUSED  | —                               | —                             | —                               | —                               | Будь-яка               |
| REJECTED | —                               | —                             | —                               | —                               | Будь-яка               |
| CANCELED | —                               | —                             | —                               | —                               | Будь-яка               |

## Створення Доручення вручну

Якщо потрібно створити Доручення поза автоматичним зіставленням — наприклад, щоб повʼязати конкретний Інтент із конкретним Запитом — скористайтеся командою `/order_add`:

```text theme={null}
/order_add_A123_G456_1000
```

Де:

* `A123` — ID Запиту (Ask)
* `G456` — ID Інтенту
* `1000` — сума

Доручення створюється в статусі DRAFT. Перевірте його та активуйте, перевівши в NEW.

<Warning>
  Ручні Доручення оминають автоматичну логіку зіставлення. Перед активацією переконайтеся, що Запит та Інтент сумісні (одна валюта, відповідні суми). Невірні ручні Доручення викликають плутанину в обох учасників.
</Warning>

Доручення, створені системою або з її участю, можна переглянути командою:

```text theme={null}
/system_orders
```

## Робота зі суперечками

Коли Доручення переходить у DISPUTE, ваша роль — зібрати докази й ескалувати до адміністратора.

<Steps>
  <Step title="Звʼяжіться з відправником">
    Звʼяжіться з учасником, який підтвердив оплату. Попросіть скриншот або запис про транзакцію, що підтверджують переказ.
  </Step>

  <Step title="Перевірте реквізити">
    Переконайтеся, що відправник використав правильний номер картки, телефону або адресу гаманця. Помилки тут — часте явище.
  </Step>

  <Step title="Звʼяжіться з отримувачем">
    Попросіть отримувача ще раз перевірити рахунки. Перекази іноді затримуються банками.
  </Step>

  <Step title="Ескалуйте адміністратору">
    Якщо докази очевидні або ситуація не вирішується на вашому рівні, використайте `/admin`, щоб звʼязатися з адміністратором. Передайте ID Доручення та зібрані скриншоти.
  </Step>
</Steps>

<Note>
  Самостійно розвʼязати DISPUTE не можна — лише адміністратори можуть позначити його як RECEIVED або скасувати. Ваше завдання — розслідувати та представити факти.
</Note>

## Автоматичне створення Доручень

Система регулярно зіставляє відкриті Інтенти з очікуваними Запитами та створює Доручення за розкладом. Це відбувається без ручного втручання, коли:

* У пулі зіставлення є валідний активний Інтент
* Є очікуваний схвалений вами Запит на допомогу
* Суми й валюти сумісні

При створенні автоматичного Доручення з учасником вашої структури вам надходить сповіщення, і Доручення потрапляє в чергу розгляду зі статусом NEW.