mondaySyncService
mondaySyncService
- mondaySyncService
- CreateSyncRequest(workersFile, clientsFile, requiresApproval, kind) ⇒
Promise.<ApiResult> - ApproveSyncRequest(id) ⇒
Promise.<ApiResult> - CancelSyncRequest(id) ⇒
Promise.<ApiResult> - RecomputeSyncRequest(id) ⇒
Promise.<ApiResult> - GetSyncRequests(page, rowsPerPage, sortBy, descending, kind) ⇒
Promise.<ApiResult> - GetSyncRequest(id) ⇒
Promise.<ApiResult> - GetSyncRequestStatus(id) ⇒
Promise.<ApiResult> - ResolveConflict(requestId, changeId, winner) ⇒
Promise.<ApiResult> - UnresolveConflict(requestId, changeId) ⇒
Promise.<ApiResult> - ResolveAllConflicts(requestId, winner, propertyName) ⇒
Promise.<ApiResult> - ResolveDuplicate(requestId, entityType, businessEntityId, chosenMondayItemId) ⇒
Promise.<ApiResult> - ResolveAssignment(requestId, clientMondayItemId, chosenWorkerDieId) ⇒
Promise.<ApiResult> - ResolveMatchedAmbiguous(requestId, entityType, mondayItemId, chosenDieId) ⇒
Promise.<ApiResult> - DownloadSyncFile(requestId, type) ⇒
Promise.<Blob> - RetryChange(requestId, changeId) ⇒
Promise.<ApiResult> - RetryAllErrors(requestId) ⇒
Promise.<ApiResult> - ApplyPending(requestId) ⇒
Promise.<ApiResult> - GetMondayQuota() ⇒
Promise.<ApiResult> - RetriggerDistribution(id) ⇒
Promise.<ApiResult> - GetStaleDiff(id) ⇒
Promise.<ApiResult> - GetSyncRequestChanges(id, params) ⇒
Promise.<ApiResult> - GetSyncRequestChangesGrouped(id, params) ⇒
Promise.<ApiResult> - SkipChanges(id, changeIds) ⇒
Promise.<ApiResult> - UnskipChanges(id, changeIds) ⇒
Promise.<ApiResult> - GetErrorsSummary(id) ⇒
Promise.<ApiResult> - RetryErrorGroup(id, normalizedMessage) ⇒
Promise.<ApiResult> - GetConflictsSummary(id) ⇒
Promise.<ApiResult> - GetUnresolvedInsuranceCompanies(id) ⇒
Promise.<ApiResult> - GetEntityHistory(params) ⇒
Promise.<ApiResult>
- CreateSyncRequest(workersFile, clientsFile, requiresApproval, kind) ⇒
CreateSyncRequest(workersFile, clientsFile, requiresApproval, kind) ⇒ Promise.<ApiResult>
Создаёт новый sync-запрос на основе загруженных xlsx-файлов из Monday
Принимаемые параметры
| Param | Type | Default | Description |
|---|---|---|---|
| workersFile | File | xlsx-файл с сотрудниками | |
| clientsFile | File | xlsx-файл с клиентами | |
| requiresApproval | boolean | false | Требовать подтверждения перед фазой применения |
| kind | string | "Sync" | Тип потока: "Import" или "Sync" |
Возвращаемые данные
Returns: Promise.<ApiResult> - Созданный sync-запрос
INFO
Ожидает два xlsx-файла (сотрудники и клиенты), отправленных как multipart/form-data POST.
TIP
Передайте requiresApproval=true для сценария bootstrap-импорта с предпросмотром и подтверждением: после read-only фазы сопоставления запрос будет остановлен в статусе PreviewReady, а фаза применения выполнится только после вызова ApproveSyncRequest.
ApproveSyncRequest(id) ⇒ Promise.<ApiResult>
Подтверждает sync-запрос в статусе PreviewReady — переводит его обратно в Syncing, чтобы фоновый обработчик выполнил реальную bootstrap-загрузку
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Подтверждение операции
WARNING
404 — если запрос с таким id не найден; 409 — если статус не PreviewReady.
CancelSyncRequest(id) ⇒ Promise.<ApiResult>
Отменяет sync-запрос, ещё находящийся в статусе PreviewPending, PreviewReady или NoChanges — помечает его Cancelled и сбрасывает загруженные xlsx-байты
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Подтверждение операции
WARNING
404 — если запрос не найден; 409 — если статус не допускает отмену (например, Syncing/Synced).
RecomputeSyncRequest(id) ⇒ Promise.<ApiResult>
Пересчитывает sync-запрос: сбрасывает построенную модель и снапшоты и возвращает запрос в PreviewPending, чтобы фоновый обработчик заново построил предпросмотр на актуальных данных CRM
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Подтверждение операции
INFO
Применяется к статусу Stale (применение было заблокировано, так как данные CRM изменились после построения модели) или к PreviewReady (оператор хочет обновить предпросмотр). Требует, чтобы исходные xlsx-файлы ещё хранились.
WARNING
404 — если запрос не найден; 409 — если статус не Stale/PreviewReady или исходные файлы недоступны.
GetSyncRequests(page, rowsPerPage, sortBy, descending, kind) ⇒ Promise.<ApiResult>
Получает список sync-запросов с пагинацией
Принимаемые параметры
| Param | Type | Default | Description |
|---|---|---|---|
| page | number | Номер страницы | |
| rowsPerPage | number | Количество записей на странице | |
| sortBy | string | Поле сортировки | |
| descending | boolean | true | Сортировать по убыванию |
| kind | string | Тип потока: "Import" или "Sync" |
Возвращаемые данные
Returns: Promise.<ApiResult> - Список sync-запросов с пагинацией
INFO
Если sortBy не указан, сортировка по умолчанию — от новых к старым (newest-first).
TIP
Передайте kind ("Import" | "Sync"), чтобы получить запросы только этого потока (две отдельные таблицы).
GetSyncRequest(id) ⇒ Promise.<ApiResult>
Получает один sync-запрос с полным списком изменений
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Данные sync-запроса со списком изменений
GetSyncRequestStatus(id) ⇒ Promise.<ApiResult>
Получает облегчённый статус и агрегированные счётчики для опроса со страницы деталей
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Статус и агрегированные счётчики sync-запроса
INFO
Без отчёта предпросмотра и без списка изменений — только статус и счётчики.
Оценка расстояний (bootstrap-импорт)
Оценка дистанций считается асинхронно в core.businesslogic. Прогресс и итог приходят в полях этого статуса: estimateStage (0 — нет, 1 — считается, 2 — готово, 3 — ошибка), estimateStageCurrent / estimateStageTotal (счётчик для степпера), а по завершении — estimatedDistancePairs / estimatedDistanceCacheHits / estimatedDistanceGoogleApiCalls и distanceEstimateReliable.
ResolveConflict(requestId, changeId, winner) ⇒ Promise.<ApiResult>
Разрешает один конфликтующее изменение, выбирая выигравшую сторону
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
| changeId | number | ID изменения |
| winner | SyncSideDto | Выигравшая сторона. См. SyncSideDto |
Возвращаемые данные
Returns: Promise.<ApiResult> - Обновлённое изменение
UnresolveConflict(requestId, changeId) ⇒ Promise.<ApiResult>
Отменяет ранее разрешённый конфликт — возвращает строку в статус Conflict
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
| changeId | number | ID изменения |
Возвращаемые данные
Returns: Promise.<ApiResult> - Обновлённое изменение
ResolveAllConflicts(requestId, winner, propertyName) ⇒ Promise.<ApiResult>
Разрешает все ещё конфликтующие изменения в рамках запроса с одной и той же выигравшей стороной
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
| winner | SyncSideDto | Выигравшая сторона. См. SyncSideDto |
| propertyName | string | Имя свойства — ограничить разрешение конфликтами только этого свойства (опционально) |
Возвращаемые данные
Returns: Promise.<ApiResult> - Подтверждение операции
TIP
Передайте propertyName, чтобы разрешить только конфликты по одному свойству (например, все конфликты по Status). Без propertyName поведение прежнее — разрешаются все конфликты запроса.
ResolveDuplicate(requestId, entityType, businessEntityId, chosenMondayItemId) ⇒ Promise.<ApiResult>
Для неоднозначного дубликата (несколько Monday-строк → одна запись Business) выбирает выигравшую Monday-строку
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
| entityType | string | Тип сущности: "Worker" или "Client" |
| businessEntityId | number | ID записи в Business (DAF), к которой относится группа дубликатов |
| chosenMondayItemId | string | ID выигравшей Monday-строки |
Возвращаемые данные
Returns: Promise.<ApiResult> - Обновлённые данные sync-запроса со списком изменений
INFO
Выбор запоминается для будущих импортов (выбор по умолчанию) и сразу отражается в текущем предпросмотре.
ResolveAssignment(requestId, clientMondayItemId, chosenWorkerDieId) ⇒ Promise.<ApiResult>
Для неоднозначного назначения (Fee клиента совпала с несколькими работниками по имени) выбирает работника
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
| clientMondayItemId | string | ID Monday-элемента клиента |
| chosenWorkerDieId | number | DieId выбранного работника |
Возвращаемые данные
Returns: Promise.<ApiResult> - Обновлённые данные sync-запроса со списком изменений
INFO
Выбор запоминается по Monday-элементу клиента и применяется на этапе apply.
ResolveMatchedAmbiguous(requestId, entityType, mondayItemId, chosenDieId) ⇒ Promise.<ApiResult>
Для неоднозначного матча (одна Monday-строка совпала с несколькими записями CRM) выбирает запись CRM
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
| entityType | string | Тип сущности: "Worker" или "Client" |
| mondayItemId | string | ID Monday-элемента |
| chosenDieId | number | DieId выбранной записи CRM |
Возвращаемые данные
Returns: Promise.<ApiResult> - Обновлённые данные sync-запроса со списком изменений
INFO
Выбор сохраняется в каноническом маппинге Monday↔CRM и применяется на этапе apply.
DownloadSyncFile(requestId, type) ⇒ Promise.<Blob>
Скачивает исходный загруженный xlsx-файл как Blob
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
| type | string | Тип файла: "workers" или "clients" |
Возвращаемые данные
Returns: Promise.<Blob> - Содержимое xlsx-файла
RetryChange(requestId, changeId) ⇒ Promise.<ApiResult>
Повторяет одно изменение, находящееся в статусе Error
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
| changeId | number | ID изменения |
Возвращаемые данные
Returns: Promise.<ApiResult> - Обновлённое изменение
INFO
Возвращает обновлённую строку изменения.
RetryAllErrors(requestId) ⇒ Promise.<ApiResult>
Запускает фоновый повтор всех изменений в статусе Error.
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Подтверждение запуска повтора
INFO
Не ждёт завершения — переводит запрос в статус Retrying и возвращается. Фактическая работа выполняется фоновым обработчиком; прогресс отслеживается через GetSyncRequestStatus (поля retryStage / retryStageCurrent / retryStageTotal).
ApplyPending(requestId) ⇒ Promise.<ApiResult>
Применяет оставшиеся «в очереди» (InPending) изменения частично синхронизированного запроса — незаполненные строки, не применённые из-за прерванного/частичного прохода apply.
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| requestId | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Подтверждение запуска применения
:::note Не ждёт завершения — переводит запрос в статус Retrying и возвращается. Фактическая работа выполняется фоновым обработчиком; прогресс отслеживается через GetSyncRequestStatus (поля retryStage / retryStageCurrent / retryStageTotal). :::
GetMondayQuota() ⇒ Promise.<ApiResult>
Получает текущее потребление дневной квоты Monday API
Возвращаемые данные
Returns: Promise.<ApiResult> - Счётчики квоты. См. MondayQuotaDto
INFO
Квота сбрасывается в полночь UTC. Когда remaining исчерпан, фаза применения откладывается, а запрос переходит в статус WaitingForApiLimit.
RetriggerDistribution(id) ⇒ Promise.<ApiResult>
Повторно запускает дистрибуцию (расчёт расстояний клиент↔сотрудник) для уже применённого sync-запроса
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Подтверждение операции
WARNING
404 — если запрос не найден; 409 — если статус запроса не допускает повторную дистрибуцию.
GetStaleDiff(id) ⇒ Promise.<ApiResult>
Получает diff между данными, на которых была построена модель, и актуальным состоянием CRM — объясняет, почему запрос стал Stale
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Diff устаревших данных. См. StaleDiffDto
INFO
Возвращает счётчики и списки изменившихся сотрудников и клиентов; truncated=true означает, что списки обрезаны и содержат не все изменившиеся записи.
WARNING
404 — если запрос не найден; 409 — если запрос не находится в статусе Stale.
GetSyncRequestChanges(id, params) ⇒ Promise.<ApiResult>
Получает страницу изменений sync-запроса с серверной пагинацией и фильтрами
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
| params | GetSyncChangesRequestDto | Пагинация и фильтры. См. GetSyncChangesRequestDto |
Возвращаемые данные
Returns: Promise.<ApiResult> - Страница изменений. См. SyncChangeListPageDto
TIP
Используйте вместо GetSyncRequest, когда изменений много: фильтры по статусу, стороне-источнику, типу сущности, свойству и поисковой строке выполняются на сервере.
GetSyncRequestChangesGrouped(id, params) ⇒ Promise.<ApiResult>
Получает изменения sync-запроса, сгруппированные по сущности (одна запись страницы = одна сущность со вложенными изменениями), с серверной пагинацией и фильтрами
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
| params | GetSyncChangesRequestDto | Пагинация и фильтры. См. GetSyncChangesRequestDto |
Возвращаемые данные
Returns: Promise.<ApiResult> - Сгруппированная по сущностям страница изменений
SkipChanges(id, changeIds) ⇒ Promise.<ApiResult>
Помечает изменения как пропущенные — они исключаются из фазы применения
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
| changeIds | Array.<number> | ID изменений, которые нужно пропустить |
Возвращаемые данные
Returns: Promise.<ApiResult> - Результат по каждому изменению. См. SkipChangesResultDto
INFO
Ответ содержит результат по каждому переданному id: какие изменения пропущены, а какие не тронуты и почему.
UnskipChanges(id, changeIds) ⇒ Promise.<ApiResult>
Снимает пометку «пропущено» с изменений — они снова участвуют в фазе применения
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
| changeIds | Array.<number> | ID изменений, с которых нужно снять пропуск |
Возвращаемые данные
Returns: Promise.<ApiResult> - Результат по каждому изменению. См. SkipChangesResultDto
INFO
Ответ содержит результат по каждому переданному id.
GetErrorsSummary(id) ⇒ Promise.<ApiResult>
Получает сводку ошибок sync-запроса, сгруппированных по нормализованному сообщению
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Группы ошибок. См. SyncErrorsSummaryDto
INFO
Каждая группа содержит исходное сообщение, нормализованный ключ группировки, количество изменений, их id и несколько примеров затронутых сущностей.
RetryErrorGroup(id, normalizedMessage) ⇒ Promise.<ApiResult>
Повторяет все изменения одной группы ошибок (с одинаковым нормализованным сообщением)
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
| normalizedMessage | string | Нормализованное сообщение — ключ группы из GetErrorsSummary |
Возвращаемые данные
Returns: Promise.<ApiResult> - Счётчики результатов повтора
WARNING
404 — если запрос не найден или группа с таким нормализованным сообщением отсутствует.
GetConflictsSummary(id) ⇒ Promise.<ApiResult>
Получает сводку ещё конфликтующих изменений, сгруппированных по имени свойства
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Счётчики конфликтов по свойствам. См. ConflictPropertySummaryDto
TIP
Используйте вместе с ResolveAllConflicts(requestId, winner, propertyName), чтобы разрешать конфликты целыми группами по свойству.
GetUnresolvedInsuranceCompanies(id) ⇒ Promise.<ApiResult>
Получает названия страховых компаний из Monday, которые не удалось сопоставить со страховыми компаниями CRM
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| id | number | ID sync-запроса |
Возвращаемые данные
Returns: Promise.<ApiResult> - Несопоставленные названия со счётчиками. См. UnresolvedInsuranceCompanyDto
TIP
Создайте алиас через mondayInsuranceAliasService.UpsertInsuranceAlias, чтобы такие названия разрешались автоматически в будущих запросах.
GetEntityHistory(params) ⇒ Promise.<ApiResult>
Получает историю синхронизаций одной сущности (сотрудника или клиента) по всем sync-запросам
Принимаемые параметры
| Param | Type | Description |
|---|---|---|
| params | GetSyncEntityHistoryRequestDto | Тип сущности, идентификатор и пагинация. См. GetSyncEntityHistoryRequestDto |
Возвращаемые данные
Returns: Promise.<ApiResult> - Страница истории изменений сущности. См. SyncEntityHistoryPageDto
INFO
Идентифицируйте сущность через businessEntityId или mondayItemId — достаточно одного из них.