ArchMapДокументация

Описать каналы брокера

Примечание

Каналы брокера сообщений (топики, очереди, exchange) и поля их сообщений описываются в разделе Каналы на странице брокера. Правки в разделе сохраняются, когда вы уходите из поля.

Описать канал вручную#

Чтобы описать канал, выполните следующие действия:

  1. На странице брокера в разделе Каналы нажмите + Канал и выберите Вручную. Появится новый канал.
  2. Введите имя канала так же, как оно записано в коде (например, orders.events), и коротко опишите его назначение.
  3. Укажите вид канала (например, topic в Kafka, queue или exchange в RabbitMQ).
  4. Если нужно, заполните параметры доставки:
    • ключ партиционирования;
    • гарантию доставки (например, at-least-once);
    • срок хранения сообщений (например, 7d).
  5. Нажмите + Поле и опишите поле сообщения: имя, тип, обязательность и смысл значения.
  6. Повторите предыдущий шаг для остальных полей.

Примечание

Если у брокера каналы разбиты на группы (vhost в RabbitMQ, namespace в Pulsar), укажите группу канала. У Kafka такого уровня нет, поэтому для неё оставьте поле пустым.

Примечание

Строку Кто публикует / кто потребляет у канала ArchMap строит сам по пометкам публикует: и потребляет: в шагах схем логики (см. Сослаться на таблицы, каналы и параметры).

Описать каналы с помощью ИИ-агента#

Бета-версия

Документирование с помощью ИИ-агента пока работает в режиме бета-версии. Перед применением проверьте, что предлагает агент, а после применения при необходимости поправьте результат вручную.

Примечание

У брокера нет своего репозитория. Каналы объявлены в коде сервисов, которые публикуют и потребляют сообщения, поэтому агента нужно запустить в репозитории каждого такого сервиса. В каждом репозитории агент описывает только те каналы, которые видит его код.

Примечание

Агент ищет каналы в константах и конфигах, вызовах публикации и подписки, схемах событий (например, Avro или Protobuf) и конфигах развёртывания. Поля сообщений он берёт из классов событий и схем. К самому брокеру агент не подключается.

Примечание

Перед запуском агента добавьте на схему все брокеры, с которыми работает код репозитория. Агент получает в промпте список брокеров проекта и раскладывает каналы только по ним.

Чтобы описать каналы брокера с помощью агента, выполните следующие действия:

  1. На странице брокера в разделе Каналы нажмите + Канал и выберите Через ИИ-агента. Откроется окно Описать каналы с помощью ИИ-агента.

  2. Нажмите кнопку Скопировать промпт.

  3. Запустите агента в папке репозитория одного из сервисов, который работает с брокером. Вставьте промпт и отправьте. Агент сложит файлы в папку archmap-docs/ репозитория.

  4. Добавьте файлы из папки archmap-docs/ в окно одним из способов:

    • перетащите файлы в поле справа;
    • нажмите Загрузить файлы… и выберите файлы;
    • нажмите + вставить из буфера и вставьте текст файла.

    Под полем появится проверка. В ней видно, какие каналы будут записаны и сколько в каждом полей.

  5. Нажмите кнопку Применить. Окно закроется, а каналы появятся в разделе Каналы.

  6. Повторите шаги 2–5 в репозиториях остальных сервисов, которые публикуют в брокер или читают из него.

Примечание

Файлы из разных репозиториев дополняют друг друга. Новые каналы и поля добавляются к уже описанным, и ничего не задваивается. Если репозитории по-разному указывают параметры доставки канала (например, срок хранения), в ArchMap останется значение, описанное раньше, а проверка покажет расхождение в списке Проверьте:.

Примечание

Каждый файл агента относится к одному брокеру, и его адрес агент пишет первой строкой файла (например, # archmap-node: Маркетплейс «Ярмарка» / Kafka). Если сервис работает с несколькими брокерами, агент сделает отдельный файл для каждого. Каналы из файла без такой строки попадут к брокеру, со страницы которого открыто окно.

Примечание

Каналы, которые уже указаны в поле Канал у связей схемы, промпт передаёт агенту, и агент описывает каждый из них, если находит его в коде. Если такого канала нет ни в файлах, ни у брокера, проверка покажет это в списке Проверьте:. Обычно это значит, что в коде канал называется иначе, чем в связи. Тогда исправьте имя канала у связи (см. Изменить или удалить связь).

Примечание

Параметры доставки (ключ партиционирования, гарантию доставки, срок хранения) агент заполняет, только если они заданы в коде или конфигах. Если их не видно, поля останутся пустыми.

Примечание

По умолчанию то, что уже описано, не меняется, и агент только добавляет недостающее. Чтобы новые описания заменили старые, перед применением установите флажок Перезаписывать заполненное. Удалений нет ни при какой настройке.

Примечание

Кто публикует в канал и кто его читает, в этом окне не описывается. Это задают пометки публикует: и потребляет: в схемах логики, поэтому каналы удобнее описать до схем логики. Тогда агент, описывая логику, сошлётся на уже известные имена каналов (см. Документировать систему с помощью ИИ-агента).

Примечание

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

Примечание

Описать каналы может и агент, подключённый по MCP. Попросите его об этом своими словами (например, «Опиши каналы Kafka в проекте «Ярмарка» по этому репозиторию»). Агент покажет план и после вашего подтверждения запишет каналы в проект (см. Подключить своего агента через MCP-сервер).