Написать схему логики операции или воркера

Примечание

Схема логики — блок-схема в нотации Mermaid, которая по шагам описывает одну операцию сервиса или один воркер. Вид Операция описывает обработчик запроса или сценарий клиента, а вид Воркер описывает фоновую задачу. Как схемы выглядят у читателя, описано в Просмотреть логику операции или воркера.

Примечание

С чего начать, зависит от размера сервиса:

• небольшой сервис описывайте сразу, вручную (см. Создать схему вручную) или с помощью ИИ-агента (см. Описать логику с помощью ИИ-агента);
• в крупном сервисе (например, в монолите с сотнями эндпоинтов) сначала составьте список операций (см. Составить список операций). По списку видно, какие операции ещё не описаны, и описывать их можно по одной.

Примечание

Пример схемы:

flowchart TD
    A["Принять состав корзины и адрес"] --> B{"Позиций не больше лимита?<br>зависит от: MAX_ITEMS_PER_ORDER"}
    B -- Нет --> E["422: слишком много позиций"]
    B -- Да --> C["Сохранить заказ со статусом «новый»<br>пишет: orders, order_items"]
    C --> D["Опубликовать событие «заказ создан»<br>публикует: orders.events"]
    D --> F["201: номер заказа"]

Примечание

Эндпоинт связывает схему со спецификацией OpenAPI сервиса: читатель найдёт схему по эндпоинту, а в разделе Логика эндпоинт виден рядом с названием схемы (см. Добавить спецификацию OpenAPI сервиса).

Примечание

Имя схемы должно быть уникальным в пределах объекта.

Примечание

Чтобы удалить схему, в режиме правки нажмите Удалить схему внизу окна и подтвердите удаление. Кнопка Отмена выходит из правки без сохранения.

Примечание

Переписать схему можно и силами агента. Для этого в меню Изменить выберите Через ИИ-агента (см. Получить схемы логики от агента).

Примечание

Пометка в тексте шага связывает схему с фактами: таблицей базы данных, каналом брокера или параметром конфигурации. По пометкам читатель видит строку Обращения под схемой, а на страницах базы данных, брокера и сервиса видно, какие схемы к ним обращаются.

Примечание

Несколько имён перечисляются через запятую: пишет: orders, order_items. Если шаг и читает, и пишет таблицу, используйте слитный маркер читает/пишет: orders.

Примечание

Если таблица или канал с таким именем есть в нескольких базах данных или брокерах, укажите объект перед именем через косую черту: пишет: БД заказов / orders. Параметр ищется только у самого сервиса, поэтому для зависит от: объект не указывается.

Примечание

Имя в пометке должно совпадать с таблицей, каналом или параметром, описанными в проекте (см. Описать структуру базы данных, Описать каналы брокера, Описать конфигурацию сервиса). Пометка, для которой факт не найден, попадает в Рекомендации (см. Разобрать рекомендации к схеме). Если двоеточие стоит в обычном тексте (например, «зависит от: нагрузки»), уберите его.

Примечание

Список нужен крупному сервису с десятками и сотнями операций, потому что все их за один заход агент не опишет. Агент соберёт список по коду, а ArchMap создаст по каждой операции пустую схему-заглушку. Для небольшого сервиса этот шаг не нужен.

Примечание

Операции из списка агент может описывать частями (см. Описать логику с помощью ИИ-агента) или по одной (см. Описать операцию из списка).

Примечание

Список ничего не удаляет и не перезаписывает. Схема, которая уже описана, остаётся как есть. Схема, которой агент не нашёл в коде, попадает в группу Есть в документации, но не найдено в коде. Если она действительно устарела, удалите её вручную.

Примечание

Список можно собирать повторно: новых заглушек появится ровно столько, сколько в коде появилось новых операций.

Примечание

Агент читает код сервиса и рисует схему на каждую операцию и каждый воркер. Если структура баз данных, каналы и конфигурация уже описаны, агент сам поставит в шагах пометки с их именами (см. Документировать систему с помощью ИИ-агента).

Примечание

Если список операций уже составлен, агент берёт работу из него и заполняет заглушки. Когда операций много, агент описывает их частями, и каждый следующий запуск окна продолжает с операций, которые ещё не описаны.

Примечание

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

Примечание

В режиме По одной схеме кнопка Добавить ещё применяет схему и оставляет окно открытым для следующей операции.

Примечание

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

Примечание

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

Примечание

Операцию из списка можно описать и вручную. Для этого в меню Описать выберите Вручную и напишите схему так же, как при создании (см. Создать схему вручную).