# Модуль Импорта Telegram (Telegram Import Module) — Knot Messager

Модуль предназначен для бесшовного переноса истории переписки из Telegram (HTML Export) в защищенную среду Knot Messager. Основной упор сделан на сохранение контекста, вложений и связей между пользователями через систему мэппинга.

---

## 🏗 Архитектура Процесса

Импорт реализован как двухфазная операция для обеспечения максимальной точности данных и стабильности сервера:

### Фаза 1: Предварительный Анализ (Pre-Analysis)
На этом этапе система:
1.  **Extracts Names**: Сканирует ZIP-архив и вытаскивает список всех отправителей (`from_name`).
2.  **Validates Consistency**: Проверяет целостность HTML-файлов и наличие папок с медиа.
3.  **Analyzes Policies**: Сравнивает контент из Telegram с [SystemSettings](file:///e:/GIT/forkmessager/backend/src/Shared/Knot.Shared.Kernel/Configuration/ISettingsService.cs#13-17) вашего узла (разрешены ли медиа, голосовые, опросы).
4.  **Returns Conflicts**: Выдает фронтенду список флагов (например, `Media.Blocked`), чтобы предупредить пользователя о потере данных из-за политик сервера.

### Фаза 2: Фоновое Исполнение (Background Execution)
После получения подтверждения и мэппинга имен:
1.  **Job Queuing**: Создается задача импорта, возвращается `JobId`.
2.  **Worker Processing**: Система в фоновом потоке ([TelegramImportWorker](file:///e:/GIT/forkmessager/backend/src/Modules/TelegramImport/Infrastructure/Background/TelegramImportWorker.cs#21-98)) начинает парсинг и сохранение сообщений порциями (chunking), чтобы не перегружать RAM.
3.  **Real-time Progress**: Статус задачи обновляется в [ImportJobStore](file:///e:/GIT/forkmessager/backend/src/Modules/TelegramImport/Infrastructure/Background/ImportJobStore.cs#31-38), что позволяет фронтенду отображать прогресс-бар (0-100%).

---

## 👥 Мэппинг Пользователей (User Mapping)

Одной из ключевых функций модуля является возможность передать `Dictionary<string, Guid> Ranking`.
*   **Имя из Telegram**: Строка (например, "Ivan_HR").
*   **Knot UserId**: UUID существующего контакта в модуле [Relations](file:///e:/GIT/forkmessager/backend/src/Modules/Relations/Infrastructure/Persistence/RelationsDbContext.cs#17-22).
*   **Результат**: При импорте все сообщения от "Ivan_HR" будут автоматически привязаны к вашему реальному контакту с его аватаром и настройками.

---

## 🔌 API Эндпоинты

*   `POST /api/import/analyze` — Загрузка ZIP, возврат списка имен и конфликтов политик.
*   `POST /api/import/execute` — Принятие мэппинга и запуск фоновой задачи. Мгновенно возвращает `JobId`.
*   `GET /api/import/status/{jobId}` — Опрос состояния фонового процесса.

---

## 🛡 Безопасность и Лимиты

1.  **Temporary Storage**: Загруженные архивы хранятся в зашифрованном виде в временной папке и автоматически удаляются сразу после завершения (или сбоя) импорта.
2.  **Policy Enforcement**: Если администратор узла запретил хранение медиафайлов, парсер автоматически проигнорирует вложения в Telegram, импортируя только текст. Это предотвращает обход политик сервера через импорт.
3.  **In-Memory Isolation**: Парсинг HTML (`AngleSharp`) вынесен в изолированный сервис [TelegramHtmlParser](file:///e:/GIT/forkmessager/backend/src/Modules/TelegramImport/Infrastructure/Parser/TelegramHtmlParser.cs#18-22), что гарантирует отсутствие побочных эффектов.

---

> [!TIP]
> Для разработчиков: Модуль готов к горизонтальному масштабированию. Если задач на импорт станет слишком много, [TelegramImportWorker](file:///e:/GIT/forkmessager/backend/src/Modules/TelegramImport/Infrastructure/Background/TelegramImportWorker.cs#21-98) может быть легко вынесен в отдельный микросервис с очередью (например, RabbitMQ).
