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

Описать структуру базы данных

Примечание

Структура базы данных состоит из таблиц и колонок и описывается в разделе Структура на странице базы данных. Правки в разделе сохраняются, когда вы уходите из поля.

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

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

  1. На странице базы данных в разделе Структура нажмите + Таблица и выберите Вручную. Появится новая таблица.
  2. Введите имя таблицы и коротко опишите её назначение.
  3. Если у базы есть разделы (например, схемы в PostgreSQL), укажите раздел таблицы.
  4. Нажмите + Колонка и заполните колонку:
    • имя и тип;
    • флажки ключ (первичный ключ) и обяз. (значение обязательно);
    • в списке Ссылается на колонку, на которую ссылается внешний ключ;
    • смысл значения.
  5. Повторите предыдущий шаг для остальных колонок.

Примечание

Кнопки удаления таблицы и колонки находятся справа от их строк. Связи между таблицами по внешним ключам показывает ER-диаграмма (кнопка Показать диаграмму в разделе Структура).

Примечание

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

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

Бета-версия

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

Примечание

Агент описывает все базы данных, с которыми работает код репозитория, в том числе чужие. Он читает миграции и ORM-модели, а если их нет, восстанавливает таблицы и колонки по SQL-запросам в коде. К самой базе агент не подключается.

Примечание

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

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

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

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

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

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

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

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

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

  6. Если с базой работают и другие сервисы, повторите шаги 2–5 в их репозиториях.

Примечание

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

Примечание

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

Примечание

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

Примечание

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

Примечание

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

Примечание

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

Примечание

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