Add media image handling and related endpoints

- Introduced `MediaImage` entity to manage images for markdown in instructions and news. - Updated `IAppDbContext` and `AppDbContext` to include `MediaImages` DbSet. - Implemented `DeleteMediaImageFilesAsync` method in `FactoryResetCommandHandler` to remove media images during factory reset. - Added new API endpoints for uploading and retrieving media images, enhancing markdown support. - Updated frontend components to utilize the new `MarkdownEditor` for image uploads in instructions and news. - Enhanced documentation to reflect the new media handling features and API specifications.
2026-07-30 04:05:01 +03:00
parent cc7e2a7f8f
commit c2ed3240bd
37 changed files with 2052 additions and 63 deletions
@@ -127,6 +127,25 @@ status, createdAt }`. `expiresAt` всегда `null` (лимиты по сро
 чтобы публичная страница не падала. Вкладки — обычный CRUD без статуса черновик/опубликовано, как
 у `NewsPostDto`.

+## Media — картинки для markdown
+
+| Метод | Путь                       | Роль      | Тело запроса                    | Тело ответа     |
+| ----- | -------------------------- | --------- | ------------------------------- | ---------------- |
+| POST  | `/api/admin/media/images`  | admin     | `multipart/form-data`: `file`   | `MediaImageDto`  |
+| GET   | `/api/media/images/{id}`   | аноним    | —                                | тело картинки (`Content-Type` как при загрузке) |
+
+Картинки вставляются админом в markdown инструкций и новостей. `MediaImageDto`:
+`{ id, fileName, contentType, sizeBytes }` — ссылку клиент строит сам: `/api/media/images/{id}`.
+
+Отдача **анонимная**: markdown рендерится обычным `<img>`, который не шлёт `Authorization` (в отличие
+от вложений тикетов, которые клиент качает как blob). Защита — непрозрачный `Guid` в ссылке; в
+картинках инструкций/новостей персональных данных нет. Ответ помечен
+`Cache-Control: public, max-age=31536000, immutable` — содержимое по `Id` неизменно (перезалив даёт новый `Id`).
+
+Ограничения загрузки — как у вложений тикетов: ≤5 МБ, `image/jpeg|png|webp|gif`. SVG не поддерживается
+осознанно: картинка открывается по прямой ссылке, а SVG — документ со скриптами. Отдельного экрана
+управления медиа нет; файлы лежат в том же `IFileStorage` (volume) и стираются при factory reset.
+
 ## News — лента новостей

 | Метод  | Путь                    | Роль  | Тело запроса            | Тело ответа |
@@ -69,7 +69,8 @@ PnvPanel — backend на **ASP.NET Core (.NET 10)** по принципам **C
  организованы по фичам (`Auth/Login/`, `Configs/Create/`, `Admin/Nodes/`, ...).
 - **Ports (интерфейсы)**: `IAppDbContext`, `IXuiPanelGateway`, `ICurrentUser`, `IIdentityService`,
  `ISecretProtector`, `IRealtimeNotifier`, `ITelegramNotifier`, `IRoleService`, `IFileStorage`
-  (вложения тикетов поддержки — диск в контейнере, см. `Infrastructure/Storage/DiskFileStorage`).
+  (вложения тикетов поддержки и картинки для markdown — диск в контейнере, см.
+  `Infrastructure/Storage/DiskFileStorage`).
 - **Validators**: FluentValidation на команды, где есть что проверять помимо типов (не на все — см.
  [backend-conventions.md](backend-conventions.md)).
 - **DTO**: плоские `record`, конвертация из сущностей — статический метод `FromDomain(...)` на самом
@@ -98,8 +99,9 @@ PnvPanel — backend на **ASP.NET Core (.NET 10)** по принципам **C
 - **Secrets**: `DataProtectionSecretProtector : ISecretProtector` (шифрование паролей нод at-rest,
  ASP.NET Core Data Protection, key-ring на томе `dp_keys`).
 - **Telegram**: `TelegramNotifier : ITelegramNotifier` — отправка DM-уведомлений через `ITelegramBotClient`.
- **Storage**: `DiskFileStorage : IFileStorage` — вложения тикетов поддержки, файлы на диске под
-  GUID-именем (`FileStorage:RootPath`, том `ticket_uploads` в docker-compose, как `dp_keys`).
+- **Storage**: `DiskFileStorage : IFileStorage` — вложения тикетов поддержки и картинки для markdown
+  (`MediaImage`), файлы на диске под GUID-именем (`FileStorage:RootPath`, том `ticket_uploads` в
+  docker-compose, как `dp_keys`).

 > **SignalR-пуш физически лежит в `PnvPanel.Api/Hubs/`, не в `Infrastructure`.**
 > `SignalRRealtimeNotifier : IRealtimeNotifier` нужен `IHubContext<PanelHub>`, а сам `PanelHub`
@@ -30,6 +30,7 @@ VpnConfig ─*─ TrafficSample    (история трафика; пишетс
 AuditLog                       (append-only журнал действий; ссылается на ActorId/TargetId)
 ClientApp                       (каталог приложений-клиентов; группируется по OperatingSystem)
 NewsPost                        (лента новостей; публикуется админом, видна всем аутентифицированным пользователям)
+MediaImage                      (картинка для markdown инструкций/новостей; диск-хранилище, отдаётся анонимно по Id)
 AppUser
  └─0..*─ SupportTicket          (баг-репорт/предложение либо заявка на продление)
              └─1───*─ TicketComment   (переписка; первое сообщение = описание/обоснование)
@@ -836,6 +837,25 @@ docker-compose) — первая в проекте функциональнос
 Отдаётся авторизованным эндпоинтом (`GET /api/support/attachments/{id}`, проверка владения тикетом
 или роли admin), не статикой — вложения могут быть чувствительными.

+### MediaImage — картинка для markdown
+Картинка, загруженная админом для вставки в markdown инструкций/новостей
+(`POST /api/admin/media/images`). То же диск-хранилище (`IFileStorage`), те же ограничения, что и у
+вложений тикетов (`image/jpeg|png|webp|gif`, ≤5 МБ), но, в отличие от них, **отдаётся анонимно** по
+непрозрачному `Id`: markdown рендерится обычным `<img>`, который не шлёт `Authorization`.
+
+| Поле             | Тип              | Заметки                                                         |
+| ---------------- | ---------------- | ------------------------------------------------------------------ |
+| `Id`             | `Guid`           | PK; он же — ссылка `/api/media/images/{id}` в markdown              |
+| `FileName`       | `string`         | Оригинальное имя — для `alt` и отображения, не участвует в пути на диске |
+| `StoredFileName` | `string`         | Серверное GUID-имя на диске                                         |
+| `ContentType`    | `string`         | SVG не допускается (документ со скриптами, а ссылка публичная)      |
+| `SizeBytes`      | `long`           |                                                                     |
+| `UploadedBy`     | `Guid`           | Админ-загрузчик (для расследования, отдельного экрана управления нет) |
+| `CreatedAt`      | `DateTimeOffset` |                                                                     |
+
+Связи с инструкцией/новостью нет — картинка живёт только как ссылка внутри markdown-текста, поэтому
+удаление вкладки/новости файл не трогает; всё медиа стирается при factory reset.
+
 ## Value Objects

 - **NodeCredentials** (`Nodes/NodeCredentials.cs`) — `Username` + `ProtectedPassword` (шифротекст,
@@ -23,7 +23,7 @@ SPA на **React 19 + Vite + TypeScript**. Общается с бэком по R
 | Формы             | react-hook-form + zod                                         |
 | Realtime          | @microsoft/signalr                                             |
 | QR-коды           | qrcode.react (рендерит QR из готовой строки на клиенте)       |
-| Markdown          | react-markdown + remark-gfm (лента новостей; без rehype-raw — сырой HTML не рендерится) |
+| Markdown          | react-markdown + remark-gfm (новости, инструкции; без rehype-raw — сырой HTML не рендерится) |
 | Типы API          | openapi-typescript (`pnpm gen:api`) — генерирует `schema.gen.ts` для сверки; фичи импортируют руками написанный `shared/api/types.ts` |
 | i18n              | react-i18next (RU + EN)                                       |
 | Линт              | oxlint (не ESLint)                                             |
@@ -100,6 +100,12 @@ frontend/
  рендерится через `react-markdown` + `remark-gfm`), пагинация (`GET /api/news`), живое обновление
  по SignalR (`newsPublished`, широковещательно всем). Админка (`/admin/news`): CRUD, обычный
  `<textarea>` с переключателем предпросмотра Markdown вместо WYSIWYG-редактора.
+- **Markdown-редактор админки** (`features/admin/media/MarkdownEditor.tsx`) — общий для новостей и
+  инструкций (интро + вкладки): текст, предпросмотр и загрузка картинок (кнопка, вставка из буфера,
+  drag&drop). Файл уходит в `POST /api/admin/media/images`, а в текст на позицию курсора
+  вставляется `![имя](/api/media/images/{id})`; картинка отдаётся анонимно, поэтому подмена
+  компонента `img` в `react-markdown` не нужна. Оформление отрендеренного markdown —
+  общий `MARKDOWN_CLASSES` (`shared/lib/markdown.ts`), он же ограничивает картинки по ширине.
 - **Настройки** (`/settings`): смена пароля, привязка/отвязка Telegram (`TelegramLinkCard`),
  удаление аккаунта с подтверждением (`DeleteAccountSection`).
 - **Админка** (`/admin/*`): вкладки — обзор (карточки статистики, без графиков), запросы активации,