@besales/mcp 0.1.0 → 0.12.0

package/dist/resources/docs/files-and-uploads.md

@@ -0,0 +1,295 @@
+# 17. Файлы и медиа: StoredFile + FileSection
+
+> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/17-files-and-uploads.md` — копия для MCP doc-bridge (v1.5 Increment 6b). Синкать при изменении оригинала.
+>
+> ⚠️ **MCP-контекст:** это доменная справка, написанная для людей/админ-UI. В MCP-сессии ты выполняешь те же операции **через besales_* tools**, а не через UI (drag-n-drop, клики в админке). Где текст ниже говорит «клиент/админ делает X через UI» — это «что должно получиться»; механику бери из tool (напр. загрузка файла → `besales_file_upload_request`; документ в knowledge → `besales_knowledge_document_upload`; сайт → `besales_knowledge_website_add`) + из workflow-ресурсов. Внутренние ссылки `[NN-name.md]` — относительные пути исходной доки, через MCP НЕ резолвятся: ищи `besales://docs/<slug>` или concept-resource.
+
+## 1. Назначение
+
+В Animaly есть единое хранилище файлов на уровне workspace — `StoredFile`. Сюда загружаются:
+- Картинки/PDF/видео для инструмента `send_pic`.
+- Приветственные медиа агента (`AgentBehavior.greetingFileId`).
+- Аватары `TelegramPersonalAccount`.
+- Картинки для `WarmupImage`.
+- Медиа в `MessageConfig.attachments[]` follow-up.
+- Чанки QA-ответов с медиа (`QaAnswerChunk.storedFileId`).
+- Медиа-блоки в `Template` кампаний.
+
+Файлы группируются в разделы (`FileSection`) — это удобство для админа в UI.
+
+## 2. Архитектура
+
+```
+Workspace
+├── FileSection[]              # Разделы (например: «Прайсы», «Сертификаты», «Warmup-мемы»)
+│   └── StoredFile[]           # Файлы в разделе
+└── StoredFile[]               # Файлы без раздела (sectionId=null)
+```
+
+Все ссылки на файлы в системе — через `StoredFile.id` (uuid).
+
+## 3. JSON-схема `StoredFile`
+
+```json
+{
+  "id": "uuid",
+  "name": "Прайс-лист 2026",
+  "originalFilename": "price-list-2026.pdf",
+  "mimeType": "application/pdf",
+  "fileType": "DOCUMENT",
+  "storageType": "s3",
+  "url": "s3://animaly/files/<workspaceId>/price-list-2026.pdf",
+  "size": 245678,
+  "workspaceId": "<workspaceId>",
+  "sectionId": "<FileSection.id>",
+  "source": "USER_UPLOAD"
+}
+```
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `name` | string | Имя, заданное при загрузке (для UI). Уникален в `(workspaceId, name)`. |
+| `originalFilename` | string | Реальное имя файла при загрузке. |
+| `mimeType` | string | `application/pdf`, `image/jpeg`, `video/mp4` и т.п. |
+| `fileType` | enum `StoredFileType` | `IMAGE` / `DOCUMENT` / `VIDEO` / `AUDIO` / `VOICE` / `VIDEO_NOTE` / `OTHER`. |
+| `storageType` | string (`local` / `s3`) | Где физически хранится. В проде — `s3`. |
+| `url` | string | Путь/URL к файлу. |
+| `size` | int | Размер в байтах. |
+| `sectionId` | uuid / null | ID `FileSection` (или null — без раздела). |
+| `source` | enum `StoredFileSource` | Категория для UI-фильтра. См. ниже. |
+
+## 4. `StoredFileSource` — откуда взялся файл
+
+| Значение | Когда выставляется |
+|---|---|
+| `USER_UPLOAD` | Загружен админом вручную через UI (default). |
+| `CHAT_MEDIA` | Получен от пользователя в диалоге (картинка/видео/документ от клиента). |
+| `TELEGRAM_AVATAR` | Скачанный аватар Telegram-аккаунта (для UI отображения). |
+| `WARMUP_IMAGE` | Картинка для warmup-сценариев. |
+| `AGENT_GREETING` | Приветственное медиа агента (`AgentBehavior.greetingFileId`). |
+| `CAMPAIGN` | Медиа из шаблона кампании. |
+| `CRM_IMPORT` | Файл, импортированный из CRM (например, документ к сделке). |
+| `OTHER` | Прочее. |
+
+AI-сервис должен задавать корректный `source` при загрузке — это влияет на фильтрацию в админке.
+
+## 5. JSON-схема `FileSection`
+
+```json
+{
+  "id": "uuid",
+  "name": "Прайсы и каталоги",
+  "workspaceId": "<workspaceId>"
+}
+```
+
+`name` уникален в `(workspaceId)`. Раздел — это просто группировка для UI; не влияет на логику работы.
+
+## 6. Использование `StoredFile` в системе
+
+### 6.1. `send_pic` (builtin tool)
+
+```
+LLM решает отправить файл → вызывает send_pic("price-list-2026", "delivery-info") или send_pic(["url-1", "url-2"])
+```
+
+`send_pic` принимает:
+- **Имя файла** (`StoredFile.name` без расширения) — система найдёт по имени в workspace.
+- **URL** — отправит напрямую без сохранения.
+- **Массив** имён/URL — отправит все по очереди.
+
+См. [`03-tools-catalog.md`](03-tools-catalog.md), раздел 2.12.
+
+### 6.2. Приветственное медиа
+
+```json
+{
+  "AgentBehavior": {
+    "botGreeting": "Здравствуйте! Я Анна, помогу с заказом.",
+    "greetingFileId": "<StoredFile.id>",
+    "greetingButtons": [...]
+  }
+}
+```
+
+Файл (картинка / видео / аудио) отправляется вместе с текстом приветствия. `source` рекомендуется `AGENT_GREETING`.
+
+### 6.3. Медиа в follow-up
+
+```json
+{
+  "MessageConfig": {
+    "type": "media",
+    "attachments": [
+      { "storedFileId": "<StoredFile.id>", "caption": "Прайс на этот месяц" }
+    ]
+  }
+}
+```
+
+До 4 вложений в одном шаге. Caption ≤ 1024 символов.
+
+### 6.4. Медиа-блоки в кампаниях
+
+```json
+{
+  "Template.blocks": [
+    { "type": "media", "storedFileId": "<StoredFile.id>", "caption": "..." }
+  ]
+}
+```
+
+См. [`09-campaigns.md`](09-campaigns.md), раздел 3.2.
+
+### 6.5. QA-ответы с медиа
+
+```json
+{
+  "QaAnswerChunk": {
+    "orderIndex": 0,
+    "text": null,
+    "storedFileId": "<StoredFile.id>",
+    "buttons": []
+  }
+}
+```
+
+QA может отдать медиа без текста (только картинку/документ) или текст + медиа в разных чанках. См. [`07-knowledge-base.md`](07-knowledge-base.md), раздел 6.
+
+### 6.6. Warmup
+
+```json
+{
+  "WarmupImage": {
+    "warmupSettingsId": "<warmupSettingsId>",
+    "storedFileId": "<StoredFile.id>"
+  }
+}
+```
+
+См. [`16-warmup-telegram-personal.md`](16-warmup-telegram-personal.md), раздел 7.
+
+## 7. Лимиты и платформенные ограничения
+
+| Платформа | Image | Video | Document | Audio | Caption |
+|---|---|---|---|---|---|
+| Telegram Bot | ≤ 10 MB | ≤ 50 MB | ≤ 50 MB | ≤ 50 MB | ≤ 1024 |
+| Telegram Personal | ≤ 2 GB | ≤ 2 GB | ≤ 2 GB | ≤ 2 GB | ≤ 1024 |
+| Wazzup (WhatsApp) | ≤ 5 MB | ≤ 16 MB | ≤ 100 MB | ≤ 16 MB | ≤ 1024 |
+| Avito | ≤ 10 MB | ✗ | ✗ | ✗ | — |
+| Instagram | ≤ 8 MB | ≤ 100 MB | ✗ | ≤ 8 MB | ≤ 1000 |
+| VK | ≤ 50 MB | ≤ 200 MB | ≤ 200 MB | ≤ 200 MB | — |
+| Web Widget | ≤ 25 MB | ≤ 100 MB | ≤ 100 MB | ≤ 25 MB | — |
+| SMS | ✗ | ✗ | ✗ | ✗ | — |
+
+(Лимиты могут отличаться в реальном времени — указаны типовые значения провайдеров.)
+
+## 8. Inline-пример: organize files for e-commerce bot
+
+```json
+{
+  "fileSections": [
+    { "name": "Прайсы и каталоги" },
+    { "name": "Сертификаты" },
+    { "name": "Welcome-медиа" },
+    { "name": "Карта проезда" }
+  ],
+  "storedFiles": [
+    {
+      "name": "Прайс-лист 2026",
+      "originalFilename": "price-list-2026.pdf",
+      "mimeType": "application/pdf",
+      "fileType": "DOCUMENT",
+      "sectionId": "<id-Прайсы>",
+      "source": "USER_UPLOAD"
+    },
+    {
+      "name": "Каталог товаров (PDF)",
+      "originalFilename": "catalog.pdf",
+      "mimeType": "application/pdf",
+      "fileType": "DOCUMENT",
+      "sectionId": "<id-Прайсы>",
+      "source": "USER_UPLOAD"
+    },
+    {
+      "name": "Welcome video",
+      "originalFilename": "welcome.mp4",
+      "mimeType": "video/mp4",
+      "fileType": "VIDEO",
+      "sectionId": "<id-Welcome>",
+      "source": "AGENT_GREETING"
+    },
+    {
+      "name": "Карта офиса",
+      "originalFilename": "office-map.jpg",
+      "mimeType": "image/jpeg",
+      "fileType": "IMAGE",
+      "sectionId": "<id-Карта>",
+      "source": "USER_UPLOAD"
+    }
+  ]
+}
+```
+
+В `AgentBehavior`:
+```json
+{ "greetingFileId": "<id-Welcome video>" }
+```
+
+В `baseSystemPrompt` агента:
+```
+Если клиент спрашивает прайс-лист — отправляй его инструментом send_pic("Прайс-лист 2026").
+Если клиент спрашивает, как добраться — send_pic("Карта офиса").
+Если клиент просит каталог — send_pic("Каталог товаров (PDF)").
+```
+
+## 9. Что должен сделать клиент в админке
+
+AI-сервис не загружает файлы сам — только описывает структуру. Клиенту нужно:
+
+1. Открыть `Files` (раздел в навигации админки).
+2. Создать `FileSection` (например, «Прайсы»).
+3. Загрузить файлы через UI (drag-n-drop или file picker).
+4. Указать `name` (как агент будет ссылаться) и `description` (опционально).
+5. Получить `StoredFile.id` или `name` и подставить в:
+   - `AgentBehavior.greetingFileId`
+   - `MessageConfig.attachments[].storedFileId`
+   - `Template.blocks[].storedFileId`
+   - `WarmupImage.storedFileId`
+   - `QaAnswerChunk.storedFileId`
+
+## 10. Граничные случаи и валидация
+
+| Правило | Что AI-сервису помнить |
+|---|---|
+| `name` уникален в `(workspaceId)` | Не назначать два файла с именем «Прайс». |
+| `send_pic` ищет по `name` | AI должен использовать тот же `name`, что админ ввёл при загрузке. Чувствителен к точному совпадению. |
+| `mimeType` определяет, как платформа отрендерит | PDF в Telegram пойдёт как document, в Wazzup-WhatsApp — тоже document, на Avito — не пройдёт. |
+| `source=CHAT_MEDIA` файлы | Растут быстро (от пользователей). Имеют свою retention-политику. AI-сервис не должен ссылаться. |
+| `storageType=local` для прода | Не использовать — только для dev. В проде S3. |
+| Удаление `FileSection` | `sectionId` файлов внутри становится `null`, файлы остаются. |
+| Удаление `StoredFile` | Каскадно удалит ссылки в `AgentBehavior.greetingFile`, `WarmupImage`, `QaAnswerChunk`. |
+| Слишком большой файл (>50 MB) | Многие платформы не примут. Для PDF — рекомендовать сжатие. |
+| `send_pic` с массивом >5 файлов | Платформы могут флаговать как спам. Реалистичный лимит — 1–3 за один вызов. |
+| Voice (Telegram OPUS) vs Audio | `VOICE` и `AUDIO` — разные `fileType`. Голосовые (`VOICE`) авто-транскрибируются через Whisper; аудиофайлы (`AUDIO`) — нет (применяется `audioHandlingBehavior`). См. [`10-agent-behavior.md`](10-agent-behavior.md) §9. |
+
+## 11. Что AI-сервис должен спросить у клиента
+
+При сценариях с медиа:
+
+1. «Какие документы/картинки вы хотите, чтобы агент мог отправлять?» (для `send_pic`).
+2. «Нужно ли приветственное видео/картинка вместе с приветствием?» (для `greetingFileId`).
+3. «Есть ли уже подготовленные прайсы / каталоги / сертификаты?» — указать `StoredFile.name` для использования в промпте.
+4. Для warmup: «Загрузите 5–10 нейтральных картинок (мемы, природа) — они нужны для естественной активности warmup-аккаунтов».
+
+## 12. Связь с другими подсистемами
+
+| Подсистема | Связь |
+|---|---|
+| **Инструменты** ([`03-tools-catalog.md`](03-tools-catalog.md)) | `send_pic` — единственный инструмент, который работает с файлами на чтение. |
+| **Поведение** ([`10-agent-behavior.md`](10-agent-behavior.md)) | `greetingFileId` — приветственное медиа. |
+| **Follow-up** ([`08-follow-up.md`](08-follow-up.md)) | `MessageConfig.attachments[].storedFileId`. |
+| **Кампании** ([`09-campaigns.md`](09-campaigns.md)) | `Template.blocks[type=media].storedFileId`. |
+| **База знаний** ([`07-knowledge-base.md`](07-knowledge-base.md)) | `QaAnswerChunk.storedFileId` — медиа в QA-ответах. |
+| **Warmup** ([`16-warmup-telegram-personal.md`](16-warmup-telegram-personal.md)) | `WarmupImage.storedFileId`. |
+| **Платформы** ([`11-platforms.md`](11-platforms.md)) | Каждая платформа имеет свои лимиты по типам и размерам. |