В этом документе вы узнаете, что Модуль интеграций записывает о каждом изменении настроек интеграций, как он определяет автора, как секреты остаются вне истории и как сделать так, чтобы изменения из вашего кода записывались с правильным автором.

Воркфлоу модуля записывают изменение в том же запуске, который его вносит. У каждой записи есть тип, он хранится в change_type:

В таблице истории и в разделе История изменений на странице интеграции каждая запись показана под заголовком, а не под названием из фильтра. В заголовке указано число полей записи, например Задано 3 поля для created, Изменено 3 поля для updated и Удалено 3 поля для deleted. Запись без полей называется Изменены настройки, а удаление без полей Настройки удалены. Для enabled и disabled остаются Интеграция включена и Интеграция выключена.

Сохранение без изменений и включение уже включённой интеграции записей не оставляют. Проверки соединения тоже не записываются, потому что настроек они не меняют. Вместо этого на каждую проверку модуль отправляет событие integration.tested.

Каждое изменённое поле попадает в запись со своим идентификатором, ключом метки и значениями до и после изменения. Изменение собственного title интеграции записывается как поле @title.

---

Автор хранится в записи в полях actor_type и actor_id. Это субъект, которого Medusa аутентифицировала для запроса, например user или api-key. Вместе с ними модуль сохраняет actor_label, email пользователя или название ключа API на момент изменения, поэтому запись остаётся подписанной и после удаления пользователя или ключа. Ещё в записи хранятся IP-адрес, клиент и ID запроса.

API-роуты Admin модуля передают всё это в воркфлоу сами. Если ваш код запускает воркфлоу без actor, модуль записывает изменение с типом автора system. Изменение, сделанное ключом API, сохраняет actor_type со значением api-key, ID ключа в actor_id и название ключа в actor_label. Medusa Admin показывает автором Система любого автора, который не пользователь, то есть и тип system, и ключи API.

Если ваш код меняет настройки от имени пользователя Admin, например в вашем собственном API-роуте Admin, передайте аутентифицированного автора в actor:

src/api/admin/my-integration/sandbox/route.ts
1import type { AuthenticatedMedusaRequest, MedusaResponse } from "@medusajs/framework/http"
2import { upsertIntegrationWorkflow } from "@gorgo/medusa-integration"
3
4export async function POST(req: AuthenticatedMedusaRequest, res: MedusaResponse) {
5  const { result } = await upsertIntegrationWorkflow(req.scope).run({
6    input: {
7      provider_id: "int_my",
8      values: { sandbox: false },
9      actor: {
10        type: req.auth_context.actor_type,
11        id: req.auth_context.actor_id,
12        ip: req.ip,
13        user_agent: req.get("user-agent"),
14        request_id: req.requestId,
15      },
16    },
17  })
18
19  res.json({ provider_id: result.provider_id })
20}

Чтобы назвать автора, достаточно type и id, потому что email пользователя или название ключа модуль найдёт сам. ip, user_agent и request_id заполняют блок Метаданные изменения в Admin. Роут возвращает только provider_id, потому что result содержит сохранённую запись вместе с зашифрованными секретами.

---

Значения параметров с пометкой secret в историю не попадают. Для секретного параметра запись хранит только действие со значением, то есть set, replaced или removed. При удалении интеграции сохранённые секреты записываются как removed без расшифровки.

Если параметр стал секретным уже после того, как его изменения попали в историю, роуты чтения модуля возвращают его прежние значения как hidden, а Admin показывает Значение скрыто.

---

Модуль ограничивает размер записи, чтобы большой параметр типа json не раздувал историю:

• Значение длиннее 512 символов, строка или JSON структурированного значения, сохраняется сокращённым и с пометкой о сокращении. Admin показывает его с пометкой (сокращено).
• Запись хранит не больше 100 полей параметров. Поле @title изменённого названия учитывается сверх этого.
• Поля параметров одной записи занимают не больше 16 КБ. Поле, которое уже не помещается, сохраняет идентификатор и метку, но теряет значения. Когда лимит исчерпан, остальные поля в запись не попадают.

---

История хранится в модели данных IntegrationChange. Она не связана с моделью Integration, поэтому записи переживают интеграцию, которую описывают, в том числе её удаление. Модуль хранит их бессрочно и сам не удаляет.

Запись создаётся в том же воркфлоу, что и изменение. Если следующий шаг воркфлоу падает и воркфлоу откатывается, модуль всегда удаляет запись. Прежнее состояние восстанавливает только setIntegrationEnabledWorkflow, поэтому включение или выключение откатывается вместе со своей записью. Сохранение и удаление не откатываются, так что после неудачного следующего шага сохранённые или удалённые настройки остаются в силе без записи в истории. Если саму запись создать не удалось, изменение всё равно применяется, а модуль пишет предупреждение в лог.

Шаги каждого воркфлоу перечислены на странице Воркфлоу Модуля интеграций.

---

Историю можно получить любым из способов:

• в Medusa Admin, подробнее в руководстве Просмотр истории изменений в Medusa Admin;
• через роуты /admin/integrations/changes, подробнее в справочнике API-роуты Admin;
• через сервис модуля, подробнее в справочнике Сервис Модуля интеграций.