Экспорт наставников и импорт в поток обучения#

Функциональность позволяет выгрузить список наставников (mentor events) из одного потока обучения (mentor flow) в CSV-файл и массово привязать их к другому потоку обучения.

Типичный сценарий — перенос состава наставников с прошлого запуска на новый без ручного добавления каждого наставника в админке.

Схема работы#

Админка
  │
  ├─► 1. Экспорт наставников потока обучения
  │      POST /exporter/v1/mentor_event_export
  │      (terra-student-registration-exporter)
  │      │
  │      └─► CSV-файл в хранилище → ссылка на скачивание
  │
  ├─► 2. (Опционально) Редактирование CSV
  │      — заменить mentor_flow_id на ID нового потока
  │      — или передать mentor_flow_id при импорте
  │
  └─► 3. Импорт наставников в поток обучения
         POST /mentor/v2/create_mentor_event_csv
         (admin / terra-mentor-service)
         │
         └─► Создание mentor events для каждой строки CSV

Шаг	Сервис	Действие
1	`terra-student-registration-exporter`	Получает все mentor events потока, формирует CSV, загружает в хранилище
2	Администратор	Скачивает CSV, при необходимости меняет `mentor_flow_id`
3	`admin` → `terra-mentor-service`	Парсит CSV и создаёт mentor events (привязки наставников к потоку)

Формат CSV#

Разделитель полей — точка с запятой (;). Первая строка — заголовок.

Колонка	Тип	Описание	Обязательное
`mentor_level_uuid`	UUID	UUID уровня наставника	✅
`mentor_flow_id`	int64	ID потока обучения	✅
`mentor_uuid`	UUID	UUID пользователя-наставника	✅
`event_type_id`	int32	Тип события наставника (см. MentorEventType)	✅
`event_max_students`	int32	Лимит студентов на наставника	❌
`chat_link`	string	Ссылка на чат наставника	❌

Пример файла:

mentor_level_uuid;mentor_flow_id;mentor_uuid;event_type_id;event_max_students;chat_link
8a87d1a5-5bce-4361-a2e6-8b5517c81210;12;8a87d1a5-5bce-4361-a2e6-8b5517c81213;1;10;https://t.me/example
8a87d1a5-5bce-4361-a2e6-8b5517c81211;12;8a87d1a5-5bce-4361-a2e6-8b5517c81214;2;;

Значения event_type_id:

Код	Тип
`1`	Офлайн
`2`	Онлайн
`3`	Офлайн + онлайн

1. Экспорт наставников#

Выгружает все mentor events указанного потока обучения в CSV.

Ручка: POST /exporter/v1/mentor_event_export

Среда	URL
🧪 Dev	`https://gateway.devterra.ru/admin/exporter/v1/mentor_event_export`
🚀 Prod	`https://mobile-api.terraprod.ru/admin/exporter/v1/mentor_event_export`

Авторизация#

Требуется авторизация admin + TOTP.

Пример тела запроса#

{
  "mentorFlowID": 12
}

Поле	Тип	Описание	Обяз.	Пример
`mentorFlowID`	int64	ID потока обучения, из которого выгружаются наставники	✅	`12`

Пример тела ответа#

{
  "url": "https://terra-photo.fra1.cdn.digitaloceanspaces.com/uploads/mentor_events_12.csv"
}

Поле	Тип	Описание	Обяз.
`url`	string	Ссылка на скачивание CSV из хранилища	✅

Поведение#

Сервис запрашивает все mentor events потока постранично (по 500 записей).
Формирует CSV с заголовком и строками данных.
Имя файла: mentor_events_{mentorFlowID}.csv.
Если у наставника не задан лимит студентов или ссылка на чат, соответствующие поля в CSV будут пустыми.

Доступы#

У администратора должно быть право MENTOR_FLOW + READ в локации потока обучения.

2. Импорт наставников в поток обучения#

Массово создаёт mentor events (привязки наставников) из CSV-файла.

Ручка: POST /mentor/v2/create_mentor_event_csv

Среда	URL
🧪 Dev	`https://gateway.devterra.ru/admin/mentor/v2/create_mentor_event_csv`
🚀 Prod	`https://mobile-api.terraprod.ru/admin/mentor/v2/create_mentor_event_csv`

Авторизация#

Требуется авторизация admin + TOTP.

Формат запроса#

multipart/form-data:

Поле	Тип	Описание	Обяз.
`file`	file	CSV-файл в формате, описанном выше	✅
`mentor_flow_id`	int	ID целевого потока обучения. Если передан — переопределяет `mentor_flow_id` во всех строках CSV	❌

Пример запроса#

POST /admin/mentor/v2/create_mentor_event_csv
Content-Type: multipart/form-data

file=mentors.csv
mentor_flow_id=42

Если передан mentor_flow_id, редактировать колонку mentor_flow_id в CSV не обязательно — удобно при переносе наставников из одного потока в другой.

Пример тела ответа#

{
  "createdMentors": [
    "8a87d1a5-5bce-4361-a2e6-8b5517c81213"
  ],
  "notCreatedMentors": [
    "8a87d1a5-5bce-4361-a2e6-8b5517c81214"
  ]
}

Поле	Тип	Описание
`createdMentors`	[]string	UUID наставников, успешно привязанных к потоку
`notCreatedMentors`	[]string	UUID наставников, для которых создание не удалось

Поведение#

CSV должен содержать заголовок и хотя бы одну строку данных.
Заголовки проверяются на соответствие ожидаемому набору колонок (порядок не важен).
Каждая строка валидируется: UUID, числовые поля, обязательные значения.
Создание mentor events выполняется параллельно (до 5 одновременных запросов).
Для каждого успешно созданного наставника назначается роль MENTOR и обновляется анкета (worksheet).
Ошибка на одной строке не отменяет обработку остальных — результат возвращается списками createdMentors / notCreatedMentors.

Доступы#

Для каждой строки CSV проверяется право MENTOR_EVENT + CREATE в локации целевого потока обучения.

Типовой сценарий: перенос наставников на новый запуск#

Создать новый поток обучения через create_mentor_flow — получить flowID (например, 42).
Экспортировать наставников из старого потока (mentorFlowID: 12).
Скачать CSV по ссылке из ответа.
Импортировать файл в новый поток, передав mentor_flow_id=42.
Проверить результат: список созданных и не созданных наставников в ответе, затем fetch_mentor_event для потока 42.

Ошибки#

Экспорт#

Ситуация	HTTP	Причина
Нет доступа к потоку	403	Нет `MENTOR_FLOW` + `READ`
Поток не найден	4xx/5xx	Неверный `mentorFlowID`

Импорт#

Ситуация	HTTP	Причина
Файл не загружен	400	Отсутствует поле `file`
Неверный формат CSV	400	Ошибка парсинга, неверные заголовки, пустой файл
Ошибка валидации строки	400	Невалидный UUID, число или обязательное поле (в ответе указан номер строки)
Нет доступа	403	Нет `MENTOR_EVENT` + `CREATE`
Частичный успех	200	Часть UUID в `notCreatedMentors` (дубликат, наставник уже привязан и т.п.)

Связанные ручки#

Ручка	Назначение
create_mentor_event	Привязать одного наставника вручную
`POST /mentor/v2/create_mentor_events`	Массовая привязка через JSON (без CSV)
fetch_mentor_event	Просмотр списка наставников потока
create_mentor_flow	Создание нового потока обучения