Разработка модуля RetailCRM с AI-ассистентом

Скопировать ссылку на статью

Скопировано

Содержание

1. Что описывает статья
   • Перед началом
2. Создание frontend-проекта через CLI
   • Пример запуска
   • Полезные флаги
   • Повторный запуск init
3. Подготовка проекта для AI-ассистента
   • AGENTS.md
   • MCP-ресурсы
   • Project-level skills
4. Работа с AI-ассистентом
   • Что указать в задаче
   • Практический рабочий процесс
   • Минимальная рабочая проверка страницы
   • Что фиксировать в задаче
   • Примеры постановки задач
5. Разработка виджетов и страниц
   • Виджеты на существующих страницах CRM
   • Собственные страницы модуля
   • Навигация и query string
6. Проверка и публикация
   • Проверка до отправки в Маркетплейс
   • Проверка после публикации
7. Ограничения и контроль качества

1. Что описывает статья

AI-ассистент может ускорить разработку модуля RetailCRM: подготовить стартовую структуру проекта, помочь выбрать target или паттерн страницы, подключить публичные компоненты Embed UI, связать frontend/UI-часть с backend-частью, добавить локализацию и выполнить базовые проверки. Чтобы результат был предсказуемым, ассистент должен опираться на источники проекта: документацию RetailCRM, документацию @retailcrm/embed-ui, локальный AGENTS.md, MCP-ресурсы и профили компонентов.

Главная практическая польза AI в такой задаче - не только генерация Vue-кода. Ассистент помогает быстрее пройти по контрактам платформы: сопоставить extensionrc.json, endpoint runner, target или page code, доступные contexts, компоненты Embed UI и проверки перед публикацией. Поэтому задачу лучше формулировать не как «сделай страницу», а как разработку небольшого сценария с явной цепочкой проверки.

Статья описывает практический рабочий процесс разработки модуля RetailCRM с AI-ассистентом. В текущей редакции основной фокус сделан на frontend/UI-части модуля: страницах, виджетах, endpoint runner, Embed UI, Host API и проверке в CRM. Backend-часть, подключение, активация, права API и публикация остаются обязательной частью разработки модуля и будут расширяться по мере подготовки рекомендаций по backend-части. Для общих требований, подключения, активации и публикации используйте профильные статьи раздела «Публикация модуля в Маркетплейсе».

Перед началом

Перед разработкой необходимо определить:

• какие задачи должен решать модуль;
• как модуль подключается и активируется в CRM;
• какие API-методы, права и backend-ендпоинты понадобятся модулю;
• какие данные frontend/UI-часть получает от backend-части через host.httpCall();
• нужна ли модулю отдельная страница внутри CRM или достаточно виджета в существующем интерфейсе;
• какие targets, pages, contexts и actions используются во frontend/UI-части;
• как модуль будет проверяться в тестовом или партнерском CRM-аккаунте;
• какие локали поддерживаются в пользовательском интерфейсе.

Для модулей с frontend/UI-частью действуют общие требования к модулям и дополнительные требования к интерфейсу внутри CRM. Например, frontend/UI-часть должна использовать публичные пакеты платформы, выполнять обмен с backend-частью через host.httpCall(), а тексты интерфейса должны быть подготовлены для ru-RU, en-GB и es-ES.

Host API - это публичный frontend-интерфейс, который CRM предоставляет модулю во время работы внутри CRM. Через объект host frontend/UI-часть модуля вызывает backend-часть, управляет переходами и изменяет query string страницы.

Важно!

AI-ассистент не заменяет проверку разработчика. Он может сгенерировать рабочий код, но итоговое соответствие требованиям Маркетплейса, API, дизайна и сценариям пользователя необходимо проверять вручную.

2. Создание frontend-проекта через CLI

Для подготовки frontend/UI-части модуля используется пакет @retailcrm/embed-ui. CLI можно запускать через npx.

Команда init создает или дополняет проект frontend/UI-части расширения. Она может:

• добавить package.json, если его еще нет;
• добавить зависимости @retailcrm/embed-ui*, vue, pinia, vue-i18n и dev-зависимости для Vite, TypeScript и ESLint;
• создать tsconfig.json, vite.config.ts, eslint.config.js, env.d.ts;
• создать или дополнить .gitignore;
• создать стартовые файлы endpoint worker, страницы настроек, виджета заказа и i18n-сообщений;
• добавить extensionrc.json и скрипт публикации;
• создать или дополнить AGENTS.md;
• добавить MCP-настройки, если они не отключены флагами;
• добавить project-level skills, если они не отключены флагами;
• инициализировать Git-репозиторий, если включен --git или это выбрано в интерактивном режиме.

Без дополнительных флагов init выбирает стандартный набор пакетов, создает стартовые файлы, добавляет инструкции для AI-ассистента, project-level skills и MCP-настройки для пакетов, которым они нужны. Установка зависимостей запускается автоматически после изменения package.json. Project-level конфиги конкретных AI-клиентов, например .codex/config.toml, создаются только при явном указании --mcp-client-configs.

Пример запуска

Для первого запуска удобно использовать интерактивную настройку проекта:

npx -y @retailcrm/embed-ui init ./src --interactive --package-manager npm --mcp-client-configs codex --git --verbose

В этом примере:

• init ./src создает frontend/UI-часть в каталоге ./src;
• --interactive открывает пошаговый режим настройки, где можно выбрать, какие части проекта создавать и какие пакеты подключать;
• --package-manager npm явно выбирает npm;
• --mcp-client-configs codex создает project-level конфигурацию MCP для Codex CLI;
• --git инициализирует Git-репозиторий, если каталог еще не является репозиторием;
• --verbose выводит подробную сводку изменений.

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

После успешного выполнения команды в проекте должны появиться инструкции для AI-ассистента (AGENTS.md), MCP-конфигурация (.mcp.json) и, если выбран Codex CLI, project-level конфигурация .codex/config.toml. Если skills не отключены, также создается каталог .agents/skills/*. Дополнительно команда устанавливает зависимости, если установка не отключена флагом --no-install.

Для проверки созданного проекта выполните:

npm run build
npm run eslint

Полезные флаги

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

npx @retailcrm/embed-ui init --help

Для нового проекта обычно стоит оставить стандартный набор действий CLI: он создает конфиги, стартовые файлы, инструкции, skills и MCP-настройки. Дополнительные флаги полезны, когда нужно заранее посмотреть изменения, ограничить область генерации или обновить только управляемые части существующего проекта.

Флаги можно комбинировать, но они не взаимозаменяемы: каждый включает, отключает или обновляет конкретную часть проекта.

Проверить действия CLI перед записью файлов

Настроить способ запуска

Выбрать каталог и окружение

Управлять зависимостями

Ограничить генерацию файлов и настроек

Настроить AI-контекст

Принудительно обновить управляемые части

Исправить зависимости

Для установки или принудительного обновления skills в уже существующем проекте можно использовать отдельную команду:

npx @retailcrm/embed-ui init-skills
npx @retailcrm/embed-ui init-skills --force

Повторный запуск init

init можно запускать повторно в существующем проекте. CLI не дублирует управляемые секции и записи и не перезаписывает существующие файлы без явных force-флагов.

Перед обновлением существующего проекта удобно сначала посмотреть план изменений:

npx @retailcrm/embed-ui init ./web --dry-run --verbose

Чтобы обновить управляемые инструкции и MCP-настройки без перегенерации стартовых файлов, конфигов сборки, каталогов и без установки зависимостей, используйте:

npx @retailcrm/embed-ui init ./web --force-agents --force-mcp --no-install --no-template --no-configs --no-dirs

Примечание

Если проект уже содержит src, для нового frontend-каталога расширения удобнее выбрать отдельный путь, например ./web. CLI не перезаписывает существующие файлы без явного разрешения.

3. Подготовка проекта для AI-ассистента

Проект должен содержать правила и машинно-читаемые источники, по которым AI-ассистент принимает решения. Для этого используются AGENTS.md, MCP-ресурсы и, когда они доступны в проекте, project-level skills.

AGENTS.md

AGENTS.md - это файл инструкций для AI-ассистентов в проекте. В нем фиксируются правила работы с публичными API пакетов, порядок чтения документации, ограничения на импорты и проверочные шаги.

CLI @retailcrm/embed-ui init создает или дополняет AGENTS.md, если не указан флаг --no-agents. Для v1-components также доступна отдельная команда:

npx @retailcrm/embed-ui-v1-components init-agents

Если нужно добавить только секции инструкций для v1-contexts и v1-endpoint, используйте отдельные команды:

npx @retailcrm/embed-ui-v1-contexts init-agents
npx @retailcrm/embed-ui-v1-endpoint init-agents

Если секция пакета в AGENTS.md уже есть, обычный запуск не дублирует ее. Чтобы обновить существующую управляемую секцию через package-level команду init-agents, добавьте --force.

Если проект создается через @retailcrm/embed-ui init без флага --no-agents, CLI добавляет в AGENTS.md инструкции по выбранным пакетам. Если файл создается вручную или дополняется в существующем проекте, проверьте, что в нем есть правила для frontend/UI-части:

• импортировать UI-компоненты из @retailcrm/embed-ui-v1-components/remote;
• импортировать icons и assets из @retailcrm/embed-ui-v1-components/assets/...;
• не импортировать из dist/* и внутренних путей пакета;
• не использовать @retailcrm/embed-ui-v1-components/host в обычном frontend-коде модуля, если задача не относится к host-runtime;
• читать профили компонентов перед использованием сложных компонентов;
• использовать @retailcrm/embed-ui-v1-endpoint/remote и runner: "worker" для новых модулей со страницами;
• использовать публичный Host API для навигации и query string.

Полезный AGENTS.md должен описывать не только предпочтения по стилю, но и условия, при которых ассистент обязан остановиться и явно назвать неопределенность. Например: если target, context, action, route или API компонента не подтверждены документацией, профилем или MCP-ресурсом, их нельзя придумывать по аналогии; если источник данных не определен, тестовые данные допустимы только как временный слой для интерфейсной проверки.

MCP-ресурсы

MCP-ресурсы - это справочник для AI-ассистента внутри проекта. Через них ассистент получает структурированные сведения о targets, contexts, actions и custom contexts, чтобы не придумывать контракты RetailCRM по названию страницы или компонента.

Например, перед созданием виджета ассистент может проверить, существует ли target order/card:common.after, где он отображается и какие данные доступны в этой точке.

Пакеты v1-contexts и v1-endpoint предоставляют MCP stdio-серверы для таких справочных данных. Это избавляет от ручного поиска по node_modules и помогает ассистенту опираться на актуальные профили пакетов.

При выборе пакетов v1-contexts и v1-endpoint CLI добавляет или дополняет корневой .mcp.json, если MCP-настройки не отключены флагом --no-mcp. В файле используется ключ mcpServers, а управляемые записи называются:

• retailcrm-embed-ui-v1-contexts;
• retailcrm-embed-ui-v1-endpoint.

Пример корневого .mcp.json:

{
  "mcpServers": {
    "retailcrm-embed-ui-v1-contexts": {
      "command": "${CLAUDE_PROJECT_DIR:-.}/node_modules/.bin/embed-ui-v1-contexts-mcp"
    },
    "retailcrm-embed-ui-v1-endpoint": {
      "command": "${CLAUDE_PROJECT_DIR:-.}/node_modules/.bin/embed-ui-v1-endpoint-mcp"
    }
  }
}

Корневой .mcp.json рассчитан на project scope Claude Code и использует ${CLAUDE_PROJECT_DIR:-.}, чтобы MCP-серверы запускались из текущего проекта. Codex CLI этот файл напрямую не использует: для Codex нужен project-level конфиг .codex/config.toml. Project-level конфиги конкретных AI-клиентов создаются только при явном указании --mcp-client-configs.

Для Codex CLI при флаге --mcp-client-configs codex создается .codex/config.toml, например:

[mcp_servers.retailcrm-embed-ui-v1-contexts]
command = "./node_modules/.bin/embed-ui-v1-contexts-mcp"

[mcp_servers.retailcrm-embed-ui-v1-endpoint]
command = "./node_modules/.bin/embed-ui-v1-endpoint-mcp"

Project-level конфиг Codex CLI (.codex/config.toml) не создается по умолчанию. Чтобы CLI добавил MCP-серверы в конфиг Codex, укажите --mcp-client-configs codex.

Если проект уже создан, но конфиг Codex не добавлен, его можно создать отдельно:

npx @retailcrm/embed-ui-v1-contexts init-config . --mcp-client-configs codex
npx @retailcrm/embed-ui-v1-endpoint init-config . --mcp-client-configs codex

CLI не выполняет codex mcp add на user-level. Он добавляет project-level секции в .codex/config.toml, потому что в разных проектах могут использоваться разные версии @retailcrm/embed-ui*. После генерации конфигурации проект нужно открыть или перезапустить в Codex и доверить проекту, если Codex запросит подтверждение.

Основные resources:

• embed-ui-v1-endpoint://targets;
• embed-ui-v1-endpoint://targets/<encoded-target>;
• embed-ui-v1-contexts://contexts;
• embed-ui-v1-contexts://contexts/<encoded-context>;
• embed-ui-v1-contexts://actions;
• embed-ui-v1-contexts://actions/<encoded-scope>;
• embed-ui-v1-contexts://custom-contexts;
• embed-ui-v1-contexts://custom-contexts/<encoded-entity>.

После обновления пакетов MCP-конфигурацию можно переинициализировать. Пакетные команды init-config принимают путь к проекту вторым позиционным аргументом; в примере ниже используется текущий каталог:

npx @retailcrm/embed-ui-v1-contexts init-config . --force --mcp-client-configs codex
npx @retailcrm/embed-ui-v1-endpoint init-config . --force --mcp-client-configs codex

Без --force команды не дублируют уже существующие управляемые записи. С --force обновляются только записи retailcrm-embed-ui-v1-contexts и retailcrm-embed-ui-v1-endpoint; остальные MCP-серверы и пользовательские настройки соседних конфигов сохраняются.

После этого перезапустите AI-клиент или переподключите MCP-серверы. Иначе текущая сессия может продолжить использовать уже запущенный MCP-процесс и profiles, загруженные до обновления пакетов.

Если после перезапуска AI-клиента resources по-прежнему выглядят устаревшими или в системе осталось несколько MCP-процессов, в Linux/macOS можно завершить запущенные процессы Embed UI MCP и затем снова открыть проект в AI-клиенте:

pkill -f 'embed-ui-v1-(contexts|endpoint)-mcp'

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

Примечание

В Codex команда /mcp показывает список MCP tools, а серверы Embed UI публикуют MCP resources. Поэтому строки No MCP tools available, Tools: (none) и Auth: Unsupported сами по себе не означают ошибку настройки. Работоспособность таких серверов проверяется чтением resources: targets, contexts, actions и custom contexts. После обновления пакетов новые данные появляются в resources и документации, например в profiles для endpoint targets, а не обязательно в списке MCP tools.

Project-level skills

Project-level skills - это локальные инструкции для AI-ассистента по отдельным типам задач. AGENTS.md задает общие правила проекта, MCP-ресурсы дают справочные данные о targets, contexts и actions, а skills описывают порядок работы: какие источники прочитать, какие решения проверить и какие ограничения учесть перед изменением UI, contexts или endpoint. Эти файлы не входят в runtime модуля и не меняют поведение приложения.

При обычном init CLI создает project-level skills в каталоге .agents/skills/*/SKILL.md, если установка не отключена флагом --no-skills. Чтобы проверить план изменений и установить отсутствующие skills в существующем проекте, используйте:

npx @retailcrm/embed-ui init-skills --dry-run
npx @retailcrm/embed-ui init-skills

Команда init-skills устанавливает только project-level skills: она не меняет package.json, стартовые шаблоны, AGENTS.md и MCP-конфиги. Если skill уже установлен, обычный запуск не перезаписывает файл.

Для принудительного обновления уже установленных управляемых skills используйте:

npx @retailcrm/embed-ui init-skills --force

Чтобы подтянуть обновленную версию skill после обновления пакетов Embed UI, используйте init-skills --force. В рамках init тот же сценарий можно выполнить флагом --force-skills или общим --force.

Skills также можно установить через init, ограничив команду только установкой project-level skills:

npx @retailcrm/embed-ui init --skills-only

Skills создаются в корне проекта в .agents/skills/*. Если команда запускается не из корня проекта, укажите корень явно через --cwd <path>.

Для отдельных пакетов используйте пакетные команды:

npx @retailcrm/embed-ui-v1-components init-skills
npx @retailcrm/embed-ui-v1-contexts init-skills
npx @retailcrm/embed-ui-v1-endpoint init-skills

Если нужно обновить уже существующий skill через пакетную команду, добавьте --force. Флаг --force-skills используется только в общей команде @retailcrm/embed-ui init.

Для пакетов v1-components, v1-contexts и v1-endpoint доступны следующие project-level skills:

• embed-ui-v1-components-ui - для разработки UI на @retailcrm/embed-ui-v1-components: выбор паттерна страницы, чтение component/page profiles, правила стилизации, формы, таблицы, pagination, widget UI и разбор дизайн-замечаний;
• embed-ui-v1-contexts-usage - для работы с contexts, actions, custom contexts, custom fields и custom dictionaries: проверка доступности context в target, выбор public import, различение readonly и writable полей, fallback на YAML profiles при недоступном MCP;
• embed-ui-v1-endpoint-runtime - для endpoint wiring: страницы, виджеты, runners, targets, menu hierarchy, page descriptors, publishing payload, Host API и проверка страницы в CRM host.

AI-ассистент использует skills по name и description, когда задача совпадает с их областью применения. В задаче также можно сослаться на skill явно, например: «используй embed-ui-v1-endpoint-runtime перед правкой endpoint runner» или «используй embed-ui-v1-contexts-usage перед работой с actions». После установки или обновления skills перезапустите AI-сессию, чтобы клиент перечитал проектный контекст.

Если skills в проекте еще не установлены или были отключены флагом --no-skills, их можно добавить позже командами из этого раздела. До этого основной контекст для AI-ассистента остается в AGENTS.md, MCP-ресурсах и профилях компонентов.

4. Работа с AI-ассистентом

Ниже описан практический прием работы с AI-ассистентом. Это не отдельное требование платформы, а способ снизить риск ошибок при агентской разработке.

Что указать в задаче

В задаче для AI-ассистента необходимо указать не только желаемый результат, но и границы, в которых этот результат должен быть реализован. Для модуля с frontend/UI-частью это особенно важно: ассистент должен выбрать подходящую точку встраивания (target) или тип страницы, использовать публичные API Embed UI, собрать интерфейс из стандартных компонентов и не придумывать платформенные контракты по аналогии.

Хорошая постановка задачи содержит:

• пользовательский сценарий, который должен поддерживать модуль;
• тип интерфейса: виджет в точке встраивания (target), собственная страница, модальное окно или боковая панель;
• данные, которые должны прийти из CRM, backend-части модуля или временного тестового набора;
• действия пользователя, которые должны менять данные;
• состояния интерфейса: загрузка, пустой список, ошибка, нет прав;
• требования к локализации.

Перед реализацией попросите ассистента:

• прочитать AGENTS.md;
• прочитать документацию RetailCRM по модулям, собственным страницам, точкам встраивания и навигации;
• прочитать README и AI-документацию установленных пакетов @retailcrm/embed-ui*;
• проверить MCP-ресурсы, если они настроены;
• выбрать точку встраивания (target) или паттерн страницы;
• перечислить профили компонентов и страниц, которые понадобятся;
• указать, какие правила стилизации из документации Embed UI относятся к задаче;
• явно отделить подтвержденные источниками решения от проектных допущений.

Для интерфейса лучше задавать не формулировку «сделай как в CRM», а конкретный стандартный ориентир: «используй паттерн страницы со списком из профилей Embed UI», «для формы используй UiField и подходящие элементы управления», «для виджета в точке встраивания (target) оставь компактный встроенный интерфейс». Если задача затрагивает отступы, типографику, классы или CSS-переменные, ассистент должен свериться с node_modules/@retailcrm/embed-ui-v1-components/docs/STYLING.md и профилями компонентов.

Если нужного правила нет в документации Embed UI, профиле компонента или STYLING.md, это не должно становиться догадкой ассистента. Такое решение необходимо записать в задаче как проектное уточнение, чтобы при ревью было понятно, где заканчивается стандарт Embed UI и начинается решение конкретного модуля.

Практический рабочий процесс

Сначала попросите ассистента собрать короткий технический план без изменения файлов. В плане должны быть указаны:

• выбранный тип интерфейса: виджет в точке встраивания (target) или собственная страница;
• код страницы (page code) или точка встраивания (target);
• доступные контексты (contexts) и действия (actions);
• список компонентов Embed UI и профилей, которые нужно прочитать;
• изменения в extensionrc.json и в endpoint runner;
• проверки, которые должны подтвердить результат.

Удобно проверять работу как одну связку: дескриптор в extensionrc.json, соответствующий runner в коде endpoint, Vue-компонент, сборка, линтер, публикация в тестовой CRM и фактическое открытие URL страницы или отображение виджета в точке встраивания (target). Если в этой цепочке нет явного соответствия хотя бы в одном месте, AI-ассистент может сгенерировать корректный TypeScript, но нерабочий модуль.

После этого переходите к реализации небольшими шагами. Для AI-ассистента это важнее, чем большой запрос «сделай весь модуль»: чем меньше шаг, тем проще проверить, что ассистент не перепутал формат дескриптора, код страницы (page code), точку встраивания (target) или API компонента.

Минимальная рабочая проверка страницы

Для новой страницы сначала соберите минимальную рабочую версию и проверьте, что она открывается в CRM:

• добавить дескриптор страницы в конфигурацию модуля;
• зарегистрировать тот же код страницы (page code) в endpoint runner;
• создать минимальный Vue-компонент без сложной бизнес-логики;
• выполнить npm run build и npm run eslint;
• опубликовать или зарегистрировать модуль в тестовой CRM;
• открыть страницу по /modules/<moduleCode>/<pageCode>.

Только после этого стоит добавлять таблицу, фильтры, запросы к backend-части и сложные состояния. Такой порядок помогает рано поймать ошибки формата pages, отсутствующего menu, несовпадения кода страницы (page code) и runner или проблемы с entrypoint.

Что фиксировать в задаче

MCP-ресурсы и профили компонентов отвечают на вопрос «что технически доступно». Они не определяют бизнес-смысл модуля. Поэтому в задаче для AI-ассистента отдельно фиксируйте:

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

Если ассистент предлагает решение без прямого подтверждения в источниках, попросите его сначала перечислить такие предположения в ответе. Это поможет при проверке отделить правила платформы от решений, принятых только для конкретной задачи.

Демонстрационные данные лучше отделять от продуктовой логики с самого начала. Если для проверки интерфейса нужны временные записи, храните их отдельно от API-слоя, помечайте их как mock или fixture и заранее фиксируйте, какие места должны быть заменены реальными backend-вызовами через host.httpCall().

Примеры постановки задач

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

План без изменения файлов

Нужно добавить в модуль страницу с кодом order-review-requests.
Сначала прочитай AGENTS.md, документацию проекта по модулям, страницам, точкам встраивания и навигации,
а также README и AI-документацию установленных пакетов @retailcrm/embed-ui*.
Если доступны MCP-ресурсы, проверь нужные точки встраивания, контексты и профили endpoint.
Файлы пока не меняй. Верни короткий план: что нужно изменить в extensionrc.json,
endpoint runner, Vue-компонентах и локалях, какие источники подтверждают решения
и какие проверки нужно выполнить после реализации.

Минимальная страница

По утвержденному плану реализуй минимальную страницу order-review-requests:
дескриптор в extensionrc.json, регистрацию кода страницы в endpoint runner,
Vue-компонент без сложной бизнес-логики и локали ru-RU, en-GB, es-ES.
Используй только публичные точки входа Embed UI и стандартные компоненты.
После изменений выполни npm run build и npm run eslint.
В ответе перечисли измененные файлы, выполненные проверки и места,
которые требуют ручной проверки в тестовой CRM.

Виджет в точке встраивания

Нужно добавить компактный виджет в точку встраивания order/card:common.after.
Перед изменением файлов проверь по документации или MCP-ресурсам,
что точка встраивания существует, где она отображается и какие данные или действия доступны.
Если данных недостаточно, остановись и перечисли вопросы.
Если все подтверждено, реализуй минимальный виджет на публичных компонентах Embed UI,
зарегистрируй точку встраивания в extensionrc.json и endpoint runner, затем выполни npm run build и npm run eslint.

Самопроверка реализации

Проверь текущую реализацию frontend/UI-части модуля перед регистрацией в тестовой CRM.
Сверь extensionrc.json, endpoint runner, коды страниц, точки встраивания, значения runner,
entrypoint и stylesheet, локали и публичные импорты Embed UI. Выполни доступные локальные проверки.
В ответе раздели результат на: подтверждено по файлам, проверено командами,
требует проверки в CRM, допущения или риски.

5. Разработка виджетов и страниц

Модуль с frontend/UI-частью может регистрировать интерфейс двух типов: виджеты в существующих разделах CRM и собственные страницы внутри CRM.

Для новых модулей с frontend/UI-частью рекомендуется использовать @retailcrm/embed-ui-v1-endpoint/remote. В дескрипторе frontend/UI-части для такого сценария необходимо указывать:

{
  "runner": "worker"
}

Устаревший сценарий runner: "iframe" не рекомендуется использовать для новых модулей.

Виджеты на существующих страницах CRM

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

Подробный список точек встраивания (targets) и доступных в них данных описан в статье «Точки встраивания JS-модулей». Здесь достаточно зафиксировать практическое правило для агентской разработки: точку встраивания нельзя выбирать по догадке из названия страницы. Укажите ее в задаче сами или попросите AI-ассистента свериться со справочником.

Для подключения виджета в конфигурации модуля указывается точка встраивания (target), а в endpoint runner регистрируется компонент, который должен отрисоваться в этом месте интерфейса. Например, order/card:common.after означает конкретную область карточки заказа.

В разных точках встраивания доступны разные контексты (contexts), пользовательские контексты (custom contexts) и действия (actions). Перед генерацией кода попросите ассистента проверить, какие данные доступны в выбранной точке встраивания, и не использовать контексты или действия, которые не подтверждены справочником, профилем точки встраивания или MCP-ресурсом.

Если MCP настроен, ассистент может прочитать список точек встраивания и профиль нужной точки перед генерацией кода. Например, для order/card:common.after он должен обратиться к MCP-ресурсам:

embed-ui-v1-endpoint://targets
embed-ui-v1-endpoint://targets/order%2Fcard%3Acommon.after

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

Собственные страницы модуля

Собственные страницы подходят, если модулю нужен отдельный экран внутри CRM: список сущностей, карточка, настройки или сложная форма. Для страниц используется конфигурация pages, код endpoint и адрес вида:

/modules/<moduleCode>/<pageCode>

Для страницы, которая должна открываться в CRM и добавляться в навигацию, используйте объектную форму pages с настройками меню:

{
  "pages": [
    {
      "code": "order-review-requests",
      "menu": "activity_main_menu",
      "menuItemOrdering": 15,
      "menuItemTitle": {
        "ru": "Проверка заказов",
        "en": "Order reviews",
        "es": "Revisiones"
      },
      "pageHelpLink": null
    }
  ]
}

Коды разделов навигации для поля menu и доступные пункты меню приведены в справочнике навигации JS API. Используйте этот справочник, чтобы выбрать раздел CRM, в котором должен отображаться пункт собственной страницы модуля.

В коде endpoint тот же код страницы должен быть связан с Vue-компонентом:

import {
  definePageRunner,
  runEndpoint,
} from '@retailcrm/embed-ui-v1-endpoint/remote'

import OrderReviewRequestsPage from './pages/OrderReviewRequestsPage.vue'

const pageRunner = definePageRunner({
  'order-review-requests': definePageRunner(OrderReviewRequestsPage),
})

runEndpoint(pageRunner)

Примечание

Короткая запись страницы строкой задает только код страницы (page code) и не описывает пункт меню. Если страницу нужно открыть в CRM через навигацию, используйте объектную форму с настройками меню. В окружениях, где API ожидает объект ConfigurationPage, строковая запись может быть отклонена при публикации; объект только с code может пройти регистрацию, но не создать пункт меню для открытия страницы.

Для списков сущностей используйте паттерн страницы со списком: UiPageHeader, фильтры над таблицей, UiTable, UiTableColumn, UiTableFooterSection, UiTableFooterButton. Состояние поиска, фильтров, сортировки и пагинации рекомендуется хранить в query string, если для страницы используется маршрутизация.

Навигация и query string

Для навигации и query string используйте публичный Host API. Имя маршрута для goTo() берите из справочника проекта или host/manifest конкретного модуля:

import { useHost } from '@retailcrm/embed-ui'

const host = useHost()

host.goTo('crm_orders')
host.replaceQuery({ status: 'new' }, { preserveExisting: true })
host.pushQuery({ page: 2 }, { preserveExisting: true })

Для генерации URL по имени Symfony-маршрута используется useRouter().value.generate(...). Перед использованием useRouter() необходимо инициализировать контекст settings, потому что useRouter() строит маршруты на основе settings.system.routing.

Для переходов внутри CRM используйте Host API. Если нужно сформировать ссылку по имени маршрута, используйте useRouter().value.generate(...). Не собирайте URL страниц CRM вручную.

6. Проверка и публикация

Проверку после изменений удобно разделить на локальные команды, проверку конфигурации и проверку в CRM. В агентском рабочем процессе локальные команды и статическую проверку файлов можно поручить AI-ассистенту. Регистрацию модуля в тестовой CRM, публикацию и runtime-проверку выполняет разработчик или ассистент, если у него есть необходимые доступы и явно указана соответствующая команда.

После изменений во frontend/UI-части попросите ассистента выполнить базовые проверки проекта и показать результат:

npm run build
npm run eslint

Перед публикацией попросите ассистента проверить согласованность extensionrc.json, endpoint worker и build-артефактов. Это можно проверить по файлам проекта без доступа к CRM:

• targets из extensionrc.json зарегистрированы в defineWidgetRunner;
• pages из extensionrc.json зарегистрированы в definePageRunner;
• для frontend/UI-части указан runner: "worker";
• для собственных страниц используется объектная форма pages;
• для страницы, которая должна открываться в CRM, задан menu-конфиг;
• entrypoint указывает на JS-файл endpoint;
• stylesheet указан, если frontend/UI-часть публикует CSS.

Пример дескриптора frontend/UI-части:

{
  "code": "retailcrm-extension-frontend",
  "version": "1.0.0",
  "targets": [
    "order/card:common.after"
  ],
  "pages": [
    {
      "code": "order-review-requests",
      "menu": "activity_main_menu",
      "menuItemOrdering": 15,
      "menuItemTitle": {
        "ru": "Проверка заказов",
        "en": "Order reviews",
        "es": "Revisiones"
      },
      "pageHelpLink": null
    }
  ],
  "entrypoint": "extension.js",
  "runner": "worker",
  "stylesheet": "extension.css"
}

Проверка до отправки в Маркетплейс

До отправки модуля в Маркетплейс можно проверить frontend/UI-часть в тестовом или партнерском CRM-аккаунте. Для этого модуль нужно зарегистрировать в аккаунте через API так же, как при подключении: методом POST /api/v5/integration-modules/{code}/edit. Порядок регистрации описан в разделе «Шаг 3. Регистрация модуля» статьи «Как происходит подключение и активация модуля в системе».

Если модуль содержит frontend/UI-часть, при регистрации должны быть согласованы параметры uuid, entrypoint, runner, targets, pages и stylesheet. В API v5 они передаются внутри integrationModule[integrations][embedJs]. Для актуального сценария с v1-endpoint и собственными страницами используйте runner: "worker". Если модуль публикует собственные страницы, после регистрации они открываются внутри CRM по адресу:

/modules/<moduleCode>/<pageCode>

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

В тестовой CRM проверьте:

• виджет отображается в нужном target;
• страница открывается по адресу /modules/<moduleCode>/<pageCode>;
• пункт меню появился в ожидаемом разделе, если страница должна быть доступна из навигации;
• тексты отображаются на поддерживаемых локалях;
• запросы frontend/UI-части к backend-части выполняются через разрешенный механизм;
• ошибки выводятся пользователю понятным текстом.

Проверка после публикации

После публикации и установки модуля из Маркетплейса повторите runtime-проверки в тестовой CRM: отображение виджетов, открытие собственных страниц, пункт меню, локализацию, запросы frontend/UI-части к backend-части и обработку ошибок. Такая проверка подтверждает, что поведение модуля совпадает не только с локальной сборкой и регистрацией через API, но и с опубликованными данными из карточки модуля в Маркетплейсе.

7. Ограничения и контроль качества

AI-ассистент может ошибаться в деталях интерфейса, если в доступных источниках нет точного правила. По результатам проверки работы с Embed UI особенно важно контролировать:

• не использует ли ассистент нативные button, input, select, table, a, когда есть компонент Embed UI;
• нет ли импортов из @retailcrm/embed-ui-v1-components/dist или внутренних путей пакета;
• не используется ли @retailcrm/embed-ui-v1-components/host в обычном frontend-коде модуля;
• не стилизуются ли внутренние .ui-v1-* классы без подтвержденного правила из профиля или STYLING.md;
• не задан ли произвольный font-family, например Arial или Inter, вместо наследования стилей host/компонентов;
• совпадают ли отступы, размеры, line-height, font-weight и состояния с профилем компонента и STYLING.md;
• есть ли локали ru-RU, en-GB, es-ES;
• синхронизированы ли extensionrc.json, endpoint runner и фактические страницы/виджеты.