Implement extension request and gift functionalities in billing system

- Added new endpoints for creating and managing extension requests, allowing users to request billing period extensions. - Implemented admin approval processes for extension requests via Telegram, including inline buttons for approval and rejection. - Introduced a gifting feature for admins to grant additional billing days directly to users without a request. - Updated the support ticket model to accommodate extension requests and their associated properties. - Enhanced the Telegram notifier to inform admins of new extension requests and notify users of approval or rejection. - Updated frontend components to support the new extension request and gifting functionalities, including user interfaces for managing these features. - Revised API documentation to reflect the new endpoints and their usage in the billing context.
2026-07-19 05:30:11 +03:00
parent e088e302e9
commit 24cee9bb78
46 changed files with 2541 additions and 78 deletions
@@ -174,18 +174,20 @@ status, createdAt }`. `expiresAt` всегда `null` (лимиты по сро
 | GET   | `/api/support/tickets/{id}`                | —                                                                              | `TicketDetailDto` (404, если не свой) |
 | POST  | `/api/support/tickets/bug-reports`        | multipart: `message` + `files[]` (до 5, изображения до 5 МБ)                | `TicketDetailDto` |
 | POST  | `/api/support/tickets/role-requests`      | `{ existingRoleId? \| (newRoleName, newRoleMaxConfigs, newRoleMaxIpLimit), justification }` | `TicketDetailDto` |
+| POST  | `/api/support/tickets/extension-requests` | `{ requestedDays, justification }`                                            | `TicketDetailDto` (`403 Billing.NotEnabled`, если роль не billing; `409 Support.ExtensionRequestAlreadyPending`) |
 | POST  | `/api/support/tickets/{id}/comments`      | multipart: `body` + `files[]`                                                | `TicketCommentDto` |
 | POST  | `/api/support/tickets/{id}/reopen`        | —                                                                              | `204 No Content` (только владелец, только из `Resolved`) |
 | GET   | `/api/support/attachments/{id}`           | —                                                                              | бинарный поток с `Content-Type` вложения |

 `TicketSummaryDto`: `{ id, userId, userName, type, status, createdAt, lastActivityAt }` — один DTO для
 своего и админского списков. `TicketDetailDto` добавляет `requestedRoleId, requestedRoleName,
-proposedRoleName, proposedMaxConfigs, proposedMaxIpLimit, comments: TicketCommentDto[]`.
+proposedRoleName, proposedMaxConfigs, proposedMaxIpLimit, requestedDays, comments: TicketCommentDto[]`.
 `TicketCommentDto`: `{ id, authorId, authorName, body, createdAt, attachments: TicketAttachmentDto[] }`.

 Ровно одна из двух заявок на роль: либо `existingRoleId` (роль `admin` запрещена — `403
 Support.CannotRequestAdminRole`), либо все три поля новой роли. Заявка при существующем открытом
-запросе на роль → `409 Support.RoleRequestAlreadyPending`. `POST …/comments` на `Closed`-тикете →
+запросе на роль → `409 Support.RoleRequestAlreadyPending`; аналогично для продления →
+`409 Support.ExtensionRequestAlreadyPending`. `POST …/comments` на `Closed`-тикете →
 `409 Support.TicketClosed`. Вложения отдаются не статикой — `<img src>` не может передать
 `Authorization`-заголовок, фронт качает их как `Blob` через `fetch` и рендерит `Object URL`.

@@ -203,6 +205,8 @@ Support.CannotRequestAdminRole`), либо все три поля новой р
 | POST  | `/api/admin/support/tickets/{id}/close`           | —                                    | `204 No Content` (любой тип, финал) |
 | POST  | `/api/admin/support/tickets/{id}/approve`         | —                                    | `204 No Content` (только `RoleRequest`/`Open`; создаёt/назначает роль) |
 | POST  | `/api/admin/support/tickets/{id}/reject`          | `{ reason? }`                        | `204 No Content` (только `RoleRequest`; `reason` уходит комментарием) |
+| POST  | `/api/admin/support/tickets/{id}/approve-extension` | —                                  | `204 No Content` (только `ExtensionRequest`/`Open`; продлевает `BillingPaidUntil` на `RequestedDays`) |
+| POST  | `/api/admin/support/tickets/{id}/reject-extension`  | `{ reason? }`                       | `204 No Content` (только `ExtensionRequest`; `reason` уходит комментарием) |

 Обработать **собственный** тикет админу можно (в т.ч. одобрить свою же заявку на роль) — resolve/close/
 reject/approve владением тикета не ограничены. Единственное реальное ограничение — `approve` вернёт
@@ -272,14 +276,16 @@ approve/reject над `ActivationRequest`.

 | Метод | Путь                                       | Роль  | Тело запроса              | Тело ответа |
 | ----- | -------------------------------------------- | ----- | ---------------------------- | ------------- |
-| GET   | `/api/admin/billing/settings`                | admin | —                             | `BillingSettingsDto { requisitesText, graceDays }` |
-| PUT   | `/api/admin/billing/settings`                | admin | `{ requisitesText, graceDays }` | `BillingSettingsDto` |
+| GET   | `/api/admin/billing/settings`                | admin | —                             | `BillingSettingsDto { requisitesText, graceDays, defaultBillingEnabledForNewRoles }` |
+| PUT   | `/api/admin/billing/settings`                | admin | `{ requisitesText, graceDays, defaultBillingEnabledForNewRoles }` | `BillingSettingsDto` |
 | GET   | `/api/admin/billing/requests`                | admin | query: `status?, page=1, pageSize=20` | `PagedList<AdminPaymentRequestDto>` (включает `userName`) |
 | POST  | `/api/admin/billing/requests/{id}/confirm`   | admin | —                             | `204 No Content` (продлевает `BillingPaidUntil`, возвращает приостановленные конфиги в `Active`) |
 | POST  | `/api/admin/billing/requests/{id}/reject`    | admin | `{ reason? }`                 | `204 No Content` |
+| POST  | `/api/admin/billing/gift`                    | admin | `{ userId, days }`            | `204 No Content` (продлевает `BillingPaidUntil` на `days` от `max(текущий, сейчас)`, возвращает приостановленные конфиги, шлёт Telegram-уведомление пользователю; `403 Billing.NotEnabled`, если роль пользователя не billing) |

 То же подтверждение/отклонение доступно **из Telegram, не заходя на сайт** — инлайн-кнопки на
 уведомлении о заявке (`pay:approve:{id}`/`pay:reject:{id}`, см. [telegram-bot.md](telegram-bot.md)).
+Гифт — только на сайте, в боте не решается.

 ## Admin — Nodes

@@ -434,7 +434,11 @@ Singleton (как `PricingSettings`) — реквизиты для оплаты

 `GET/POST /api/billing/*` — пользователь (статус, создание/отмена заявки, «я оплатил», отправка
 реквизитов в свой Telegram). `GET/PUT/POST /api/admin/billing/*` — админ (настройки, список заявок,
-подтверждение/отклонение), только `admin`.
+подтверждение/отклонение, `POST /gift` — выдать N дней конкретному пользователю без заявки), только
+`admin`. Продление PaidUntil попадает в панель тремя путями — подтверждённая `PaymentRequest`,
+одобренная `SupportTicket(ExtensionRequest)` и прямой гифт от админа — все три используют один и тот
+же `BillingConfigResumer` (см. Application/Billing), различается только вычисление `newPaidUntil`
+(месяцы для оплаты, дни для продления/гифта) и триггер (пользователь vs админ).

 ### ActivationRequest — запрос активации
 Пользователь просит активацию у админа; админ одобряет/отклоняет на сайте или в Telegram.
@@ -480,33 +484,44 @@ Singleton (как `PricingSettings`) — реквизиты для оплаты
 После `Consumed`/`Expired` — не переиспользуется.

 ### SupportTicket — обращение в поддержку
-Два вида: `BugReport` (свободная форма, с вложениями) и `RoleRequest` (запрос существующей роли —
-кроме `admin` — либо параметров новой). Текст/обоснование не хранится отдельным полем — это первое
-сообщение в переписке (`TicketComment`), созданное вместе с тикетом в одной операции.
+Три вида: `BugReport` (свободная форма, с вложениями), `RoleRequest` (запрос существующей роли —
+кроме `admin` — либо параметров новой) и `ExtensionRequest` (продление оплаченного периода на N
+дней — только для billing-ролей, см. Billing выше). Текст/обоснование не хранится отдельным полем —
+это первое сообщение в переписке (`TicketComment`), созданное вместе с тикетом в одной операции.

 | Поле                | Тип               | Заметки                                                        |
 | ------------------- | ----------------- | ---------------------------------------------------------------- |
 | `Id`                | `Guid`            | PK                                                                |
 | `UserId`            | `Guid`            | FK → AppUser (автор)                                              |
-| `Type`              | `TicketType`      | `BugReport` / `RoleRequest`                                      |
+| `Type`              | `TicketType`      | `BugReport` / `RoleRequest` / `ExtensionRequest`                 |
 | `Status`            | `TicketStatus`    | `Open` / `Resolved` / `Closed`                                   |
 | `RequestedRoleId`   | `Guid?`           | Заполнено для `RoleRequest` при выборе существующей роли         |
 | `ProposedRoleName`  | `string?`         | Заполнено для `RoleRequest` при запросе новой роли                |
 | `ProposedMaxConfigs`| `int?`            | Параметры новой роли (см. `AppRole.MaxConfigs`)                   |
 | `ProposedMaxIpLimit`| `int?`            | Параметры новой роли (см. `AppRole.MaxIpLimit`)                   |
+| `RequestedDays`     | `int?`            | Заполнено для `ExtensionRequest` — сколько дней просит пользователь (1–365) |
 | `CreatedAt`         | `DateTimeOffset`  |                                                                    |

 Инварианты и переходы (`backend/src/PnvPanel.Domain/Support/SupportTicket.cs`): `RequestedRoleId`
 и `Proposed*` никогда не заполнены одновременно — гарантируется отдельными фабриками
-(`CreateRoleRequestForExistingRole`/`CreateRoleRequestForNewRole`), а не runtime-проверкой.
+(`CreateRoleRequestForExistingRole`/`CreateRoleRequestForNewRole`), а не runtime-проверкой. Аналогично
+`RequestedDays` заполняется только фабрикой `CreateExtensionRequest`.
 - `Resolve()` — только из `Open`. Для `RoleRequest` одобрение — оркестрация в Application
  (`ApproveRoleRequestCommandHandler`): при новой роли сначала `IRoleService.CreateRoleAsync`, затем
-  в любом случае `ChangeUserRoleAsync` пользователю, и только потом `ticket.Resolve()`.
- `Close()` — из `Open` или `Resolved`, **финал** (обратного пути нет). Для `RoleRequest` — отклонение.
+  в любом случае `ChangeUserRoleAsync` пользователю, и только потом `ticket.Resolve()`. Для
+  `ExtensionRequest` — `ApproveExtensionRequestCommandHandler` продлевает `AppUser.BillingPaidUntil`
+  на `RequestedDays` (от `max(текущий, сейчас)`, как и у `PaymentRequest`) и возвращает в `Active`
+  конфиги, приостановленные за неуплату (`BillingConfigResumer`, тот же helper, что и у подтверждения
+  оплаты и гифт-дней от админа).
+- `Close()` — из `Open` или `Resolved`, **финал** (обратного пути нет). Для `RoleRequest`/
+  `ExtensionRequest` — отклонение.
 - `Reopen()` — только из `Resolved` (владелец тикета); `Closed` не переоткрывается.
 - Одновременно не более одной **открытой** заявки на роль (`Type == RoleRequest && Status == Open`)
+  и отдельно не более одной открытой заявки на продление (`Type == ExtensionRequest && Status == Open`)
  на пользователя — проверяется в Application, аналогично `ActivationRequest.AlreadyPending`.
  Баг-репорты такого ограничения не имеют.
+- Создать `ExtensionRequest` может только пользователь с billing-ролью
+  (`CurrentUserProfile.BillingEnabled`) — иначе `Billing.NotEnabled`.
 - Доступ — только активированному пользователю (`IRequiresActivation`, как и у конфигов/новостей);
  админские действия (resolve/close/approve/reject) идут по отдельным `/api/admin/support/*` с
  ролевой проверкой, без завязки на активацию.
@@ -572,7 +587,7 @@ enum TelegramLoginStatus { Pending, Approved, Rejected, Expired, Consumed }
 enum ActivationStatus { Pending, Approved, Rejected }
 enum AuditSource { Web, Telegram, System }
 enum OsPlatform { IOS, Android, Windows, MacOS, Linux }
-enum TicketType { BugReport, RoleRequest }
+enum TicketType { BugReport, RoleRequest, ExtensionRequest }
 enum TicketStatus { Open, Resolved, Closed }
 ```

@@ -604,6 +619,10 @@ enum TicketStatus { Open, Resolved, Closed }
 | `AddTicketCommentCommandHandler`   | Realtime `ticketUpdated` владельцу, только если комментирует не он сам     |
 | `ApproveRoleRequestCommandHandler` | Создаёт роль (если новая) + назначает пользователю; `AuditLog` (`RoleRequestApproved`); Telegram-DM владельцу |
 | `RejectRoleRequestCommandHandler`  | `AuditLog` (`RoleRequestRejected`); Telegram-DM владельцу                  |
+| `CreateExtensionRequestTicketCommandHandler` | Realtime `ticketCreated` группе `admins`; Telegram админам — инлайн-кнопки «Одобрить/Отклонить» |
+| `ApproveExtensionRequestCommandHandler` | Продлевает `BillingPaidUntil`, возвращает приостановленные конфиги; `AuditLog` (`ExtensionRequestApproved`); Telegram-DM владельцу |
+| `RejectExtensionRequestCommandHandler` | `AuditLog` (`ExtensionRequestRejected`); Telegram-DM владельцу              |
+| `GrantBillingGiftCommandHandler`   | Админ дарит N дней (`/admin/billing/gift`) — та же логика продления/возврата конфигов, что и у заявок; `AuditLog` (`BillingGiftGranted`); Telegram-DM владельцу |
 | `ResolveTicketCommandHandler` / `CloseTicketCommandHandler` | `AuditLog` (`TicketResolved`/`TicketClosed`); realtime `ticketUpdated` владельцу |

 SignalR-события и группы — см. [architecture.md](architecture.md#realtime-signalr) и
@@ -197,6 +197,18 @@ Telegram  ──updates──►  TelegramBotHostedService → PnvBotUpdateHandl
 4. Пользователю (если Telegram привязан) — DM «✅ Ваша заявка на роль одобрена.» / «❌ Ваша заявка на
   роль отклонена.».

+**Заявка на продление** (`ExtensionRequest`, только для billing-ролей) — тот же паттерн, что и заявка
+на роль, инлайн-кнопки с префиксом `erq:`:
+1. `CreateExtensionRequestTicketCommandHandler` вызывает
+   `ITelegramNotifier.NotifyAdminsExtensionRequestCreatedAsync(ticketId, userName, requestedDays, justification, ct)`.
+2. Кнопки **«✅ Одобрить» / «❌ Отклонить»** (callback `erq:approve:{id}`/`erq:reject:{id}`).
+3. Нажатие → `TrySetAdminCurrentUserAsync` → `ApproveExtensionRequestCommand`/`RejectExtensionRequestCommand`
+   (те же команды, что `POST /api/admin/support/tickets/{id}/approve-extension|reject-extension`).
+   Одобрение продлевает `AppUser.BillingPaidUntil` на `RequestedDays` и возвращает приостановленные
+   конфиги в `Active` (`BillingConfigResumer`).
+4. Пользователю — DM «✅ Заявка на продление одобрена. Доступ продлён до {дата}.» / «❌ Ваша заявка на
+   продление отклонена.».
+
 ## Флоу 7 — Оплата подписки (биллинг)

 Только для ролей с `AppRole.BillingEnabled` (см. [domain-model.md](domain-model.md#billing--подписка-по-сроку)).
@@ -221,6 +233,10 @@ Telegram  ──updates──►  TelegramBotHostedService → PnvBotUpdateHandl
 оплаты и уведомление о приостановке конфигов при просрочке — оба через `NotifyUserAsync`, без
 инлайн-кнопок.

+**Гифт от админа** (`POST /api/admin/billing/gift`, только на сайте — в боте не решается) — админ
+выдаёт пользователю N дней напрямую, без заявки. Пользователю (если Telegram привязан) — DM
+«🎁 Вам подарено N дн. подписки! Доступ продлён до {дата}.».
+
 **Статус оплаты по кнопке**: для пользователей с billing-ролью (`AppRole.BillingEnabled`) в главном
 меню бота появляется «💳 Статус оплаты» (`menu:billing`, либо команда `/billing`) — показывает дату,
 до которой оплачено, и остаток в человекочитаемом виде: дни, если их ≥ 1 (`N дн.`), иначе часы и
@@ -246,6 +262,7 @@ Telegram  ──updates──►  TelegramBotHostedService → PnvBotUpdateHandl
 | «✅ Активировать»/«❌ Отклонить» | (admin) решение по конкретному запросу активации           | админ по env       |
 | `/requests`                | (admin) список ожидающих запросов активации (до 10)              | админ по env       |
 | «✅ Одобрить»/«❌ Отклонить» (`rrq:*`) | (admin) решение по заявке на роль — создаёт/назначает роль | админ по env |
+| «✅ Одобрить»/«❌ Отклонить» (`erq:*`) | (admin) решение по заявке на продление — продлевает `BillingPaidUntil` | админ по env |
 | «✅ Подтвердить»/«❌ Отклонить» (`pay:*`) | (admin) решение по заявке на оплату — продлевает `BillingPaidUntil` | админ по env |
 | «🌐 Открыть на сайте»      | Ссылка на баг-репорт на сайте (только если задан `Telegram__PublicSiteUrl`) | админ по env |