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

# Grace access

> Временный ограниченный доступ после истечения подписки или исчерпания трафика

## Обзор

Grace access — временный урезанный доступ для подписок, которые только что перешли в `expired` (закончился срок) или `limited` (закончился трафик). Человек не остаётся полностью без связи и успевает продлиться, а не уходит к конкуренту в тот же вечер.

Подсистема появилась в `v3.65.0` и была упрощена в `v3.66.0`.

<Note>
  Биллинг остаётся источником истины. Grace — это **временный оверлей в Remnawave** и отдельная запись сессии. Подсистема никогда не меняет даты и статус подписки в биллинге и никогда не обнуляет использованный трафик.
</Note>

## Как это работает

<Steps>
  <Step title="Обнаружение">
    Фоновый цикл ищет подписки, недавно перешедшие в `expired` или `limited`. Глубина поиска назад по времени — `GRACE_ACCESS_CANDIDATE_LOOKBACK_MINUTES`.
  </Step>

  <Step title="Проверка права на grace">
    Подписка должна подходить по типу (см. [Кому выдаётся](#кому-выдаётся)) и не иметь уже открытой сессии.
  </Step>

  <Step title="Наложение оверлея">
    В панели пользователю выставляется сквад grace и квота `GRACE_ACCESS_TRAFFIC_GB`. Прежнее состояние сохраняется в версионированном снимке.
  </Step>

  <Step title="Окно доступа">
    Сессия живёт `GRACE_ACCESS_DURATION_HOURS` часов. Всё это время пользователь может продлиться обычным способом.
  </Step>

  <Step title="Восстановление">
    По оплате, по истечении окна или по отзыву панельное состояние возвращается из снимка методом compare-and-set — чужие изменения, сделанные администратором вручную, не затираются.
  </Step>
</Steps>

## Режимы работы

`GRACE_ACCESS_MODE` принимает четыре значения:

| Режим     | Что делает                                                                                      |
| --------- | ----------------------------------------------------------------------------------------------- |
| `false`   | Выключено. Ничего не пишется и не выдаётся                                                      |
| `observe` | Только журнал: кандидаты фиксируются, но доступ не выдаётся. Режим для обкатки на живом трафике |
| `true`    | Рабочий режим: доступ выдаётся                                                                  |
| `drain`   | Новые сессии не открываются, уже открытые доживают до конца окна и корректно восстанавливаются  |

<Tip>
  Порядок безопасного включения: `observe` → посмотреть в логах, сколько подписок попадает в кандидаты → `true`. Выключать лучше через `drain`, а не сразу в `false`: так открытые сессии не останутся с оверлеем в панели.
</Tip>

## Кому выдаётся

При `GRACE_ACCESS_MODE=true` доступ получают **обычные платные несуточные** подписки. Остальные категории включаются отдельно:

| Переменная                   | Категория              | По умолчанию |
| ---------------------------- | ---------------------- | ------------ |
| `GRACE_ACCESS_TRIAL_ENABLED` | Триальные подписки     | `false`      |
| `GRACE_ACCESS_DAILY_ENABLED` | Суточные тарифы        | `false`      |
| `GRACE_ACCESS_FREE_ENABLED`  | Бесплатные (0₽) тарифы | `false`      |

<Warning>
  Суточные тарифы и триалы по умолчанию выключены намеренно: у них срок истекает штатно и часто, поэтому grace для них превращается в постоянную бесплатную выдачу.
</Warning>

## Настройка

```env theme={null}
# false | observe | true | drain
GRACE_ACCESS_MODE=false

# Длительность окна и квота трафика на это время
GRACE_ACCESS_DURATION_HOURS=72
GRACE_ACCESS_TRAFFIC_GB=1

# Сквады, в которые уводятся подписки на время grace
GRACE_ACCESS_EXPIRED_SQUAD_UUID=
GRACE_ACCESS_LIMITED_SQUAD_UUID=

# Дополнительные категории подписок
GRACE_ACCESS_TRIAL_ENABLED=false
GRACE_ACCESS_DAILY_ENABLED=false
GRACE_ACCESS_FREE_ENABLED=false

# Фоновая сверка сессий
GRACE_ACCESS_RECONCILE_INTERVAL_SECONDS=60
GRACE_ACCESS_RECONCILE_BATCH_SIZE=200
GRACE_ACCESS_CANDIDATE_LOOKBACK_MINUTES=30
```

### Сквады

Заведите в Remnawave отдельные сквады под grace и укажите их UUID:

* `GRACE_ACCESS_EXPIRED_SQUAD_UUID` — для подписок, у которых закончился срок;
* `GRACE_ACCESS_LIMITED_SQUAD_UUID` — для подписок, у которых закончился трафик.

Разделение позволяет дать этим двум группам разные ноды или разную политику — например, увести истёкших на медленный сквад, а «упёршихся в трафик» оставить на прежних нодах с урезанной квотой.

<Note>
  Если UUID не задан, подписки этой категории grace не получают — сквад для оверлея обязателен.
</Note>

## Жизненный цикл сессии

| Состояние   | Значение                                                                    |
| ----------- | --------------------------------------------------------------------------- |
| `pending`   | Оверлей ещё не применён в панели (панель недоступна или не приняла переход) |
| `active`    | Оверлей применён, идёт окно доступа                                         |
| `restoring` | Идёт возврат прежнего панельного состояния                                  |
| `completed` | Сессия закрыта                                                              |

Причина закрытия фиксируется отдельно:

| Причина    | Когда                                         |
| ---------- | --------------------------------------------- |
| `paid`     | Пользователь продлился — самый желанный исход |
| `timeout`  | Окно закончилось                              |
| `drained`  | Режим переведён в `drain`                     |
| `conflict` | Панельное состояние разошлось со снимком      |
| `revoked`  | Доступ отозван вручную                        |

## Ограничения

<AccordionGroup>
  <Accordion title="Grace не продлевает подписку">
    Даты и статус подписки в биллинге не меняются. Пользователь всё это время формально остаётся без активной подписки — grace только даёт временный канал связи.
  </Accordion>

  <Accordion title="Использованный трафик не обнуляется">
    Квота `GRACE_ACCESS_TRAFFIC_GB` — это то, что реально доступно во время окна, а не сброс счётчика подписки.
  </Accordion>

  <Accordion title="Панель может не принять переход сразу">
    Если Remnawave недоступна, сессия остаётся в `pending` и будет доведена фоновой сверкой. Сверка идёт раз в `GRACE_ACCESS_RECONCILE_INTERVAL_SECONDS` секунд батчами по `GRACE_ACCESS_RECONCILE_BATCH_SIZE`.
  </Accordion>
</AccordionGroup>

## Связанные разделы

<CardGroup cols={2}>
  <Card title="Подписки" icon="repeat" href="/bot/subscriptions">
    Статусы подписок и жизненный цикл
  </Card>

  <Card title="Remnawave" icon="server" href="/integrations/remnawave">
    Сквады, синхронизация и панельная идентичность
  </Card>
</CardGroup>