# Форматы CSV

## Обязательные колонки

Поддерживаются заголовки на английском и русском языке. Не смешивайте языки в одном файле.

### Английский формат (рекомендуется)

| Колонка            | Описание                                           |
| ------------------ | -------------------------------------------------- |
| `thread_id`        | Уникальный идентификатор треда                     |
| `timestamp`        | Время сообщения (ISO 8601 или `DD.MM.YY HH:MM:SS`) |
| `participant_role` | Роль автора: `client`, `bot`, `support`, `system`  |
| `message_text`     | Текст сообщения                                    |

### Русский формат

| Колонка         | Описание                                           |
| --------------- | -------------------------------------------------- |
| `ID треда`      | Уникальный идентификатор треда                     |
| `Дата доставки` | Время сообщения (`DD.MM.YY HH:MM:SS`)              |
| `Автор`         | Роль автора: `Клиент`, `Бот`, `Саппорт`, `Система` |
| `Текст`         | Текст сообщения                                    |

## Необязательные колонки

| Колонка (EN)       | Колонка (RU)   | Описание                                                          |
| ------------------ | -------------- | ----------------------------------------------------------------- |
| `message_id`       | `ID сообщения` | Внешний ID сообщения (генерируется автоматически, если не указан) |
| `participant_id`   | —              | Идентификатор участника                                           |
| `participant_name` | —              | Отображаемое имя участника                                        |
| `channel`          | —              | Канал-источник                                                    |
| `metadata`         | —              | Дополнительные метаданные (JSON)                                  |

{% hint style="info" %}
Колонка `message_id` необязательна. Если не указана, ID генерируется автоматически в формате `{thread_id}-{порядковый_номер}`.
{% endhint %}

## Маппинг ролей

| Значение в CSV (без учёта регистра) | Роль в системе |
| ----------------------------------- | -------------- |
| `client`, `клиент`                  | `client`       |
| `bot`, `бот`                        | `bot`          |
| `support`, `саппорт`, `оператор`    | `support`      |
| `system`, `система`                 | `system`       |

Неизвестные значения интерпретируются как `client`.

## Форматы дат

| Формат         | Пример                                           |
| -------------- | ------------------------------------------------ |
| ISO 8601       | `2024-01-15T10:00:00` или `2024-01-15T10:00:00Z` |
| Русский формат | `30.11.25 10:00:15` (DD.MM.YY HH:MM:SS)          |
| Без секунд     | `30.11.25 10:00` (DD.MM.YY HH:MM)                |

Допускается использование разных форматов дат в пределах одного файла.

## Разделители

* `,` (запятая) — предпочтительный
* `;` (точка с запятой) — определяется автоматически

## Примеры файлов

<details>

<summary>Минимальный английский формат (без message_id)</summary>

```csv
thread_id;timestamp;participant_role;message_text
thread_001;2024-01-15T10:00:00;client;Hello
thread_001;2024-01-15T10:00:30;bot;Hi there
thread_001;2024-01-15T10:01:00;client;I have a question
thread_002;2024-01-15T11:00:00;client;Another conversation
```

</details>

<details>

<summary>Минимальный русский формат (без ID сообщения)</summary>

```csv
ID треда;Дата доставки;Автор;Текст
259876036;28.11.25 12:29;лия;Здравствуйте! На связи робот-помощник Лия
259876036;28.11.25 12:29;клиент;Какие задания доступны для детей бесплатно
259876036;28.11.25 12:30;лия;Переключаю вас на оператора
259876036;28.11.25 12:31;оператор;Здравствуйте! Отвечаю на ваш вопрос
```

</details>

<details>

<summary>Полный английский формат (с message_id)</summary>

```csv
thread_id,message_id,timestamp,participant_id,participant_role,message_text
thread_001,msg_001,2024-01-15T10:00:00,user_123,client,Hello
thread_001,msg_002,2024-01-15T10:00:30,bot_1,bot,Hi there
thread_001,msg_003,2024-01-15T10:01:00,user_123,client,Question here
```

</details>

<details>

<summary>Полный русский формат (с ID сообщения)</summary>

```csv
ID сообщения;ID треда;Дата доставки;Автор;Текст
msg_001;thread_123;30.11.25 10:00:15;Клиент;Здравствуйте
msg_002;thread_123;30.11.25 10:00:45;Бот;Добрый день
msg_003;thread_123;30.11.25 10:01:20;Клиент;У меня вопрос
```

</details>

## Обработка сообщений

1. **Группировка** — сообщения группируются по `thread_id`
2. **Сортировка** — внутри каждого треда сортируются по `timestamp`
3. **Нумерация** — порядковые номера присваиваются автоматически (1, 2, 3, ...)
4. **ID сообщений** — генерируются автоматически, если не указаны: `{thread_id}-{номер}`

## Правила валидации

**Допустимо:**

* Пустой `message_text` (например, для сообщений с фото)
* Отсутствие `message_id` (сгенерируется автоматически)
* Смешанные форматы дат в одном файле

**Недопустимо:**

* Отсутствие `thread_id`
* Отсутствие `timestamp`
* Отсутствие `participant_role` / `Автор`
* Невалидный формат даты
* Отсутствие строки заголовков
* Отсутствие обязательных колонок

{% hint style="warning" %}
Невалидные строки пропускаются с предупреждением. Убедитесь, что файл сохранён в кодировке **UTF-8**.
{% endhint %}