For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ru/docs/web/commerce.md (or send Accept: text/markdown).
Коммерция
Товары и заказы workspace на однонаправленном жизненном цикле.
Прохождение для начинающих
Предварительные требования: прочтите два приведенных ниже руководства для начинающих, завершите локальную веб-настройку и откройте этот монорепозиторий в корневой папке вашего редактора. Веб-настройки принадлежат apps/web/.env.local; Next.js не читает корень .env. /dashboard в поддельном режиме по умолчанию представляет собой демонстрацию без базы данных; /auth требуется перенесенная база данных.
Вкратце: рабочее пространство — это отдельные пользователи, данные и настройки одной команды. Сервер является доверенным сервером; не допускайте попадания ключей провайдера в код браузера и телефона. Миграция — это изменение версии базы данных, при котором создаются или обновляются таблицы. Модель ИИ — это механизм, который отвечает; Каталог моделей — это список доступных идентификаторов моделей и цен на сервере. Поставщик — это внешняя служба, такая как служба искусственного интеллекта, электронной почты или службы выставления счетов. Право — это грант, который позволяет рабочей области использовать функцию. Вебхук — это сообщение, которое одна служба отправляет на URL другой службы.
1. В качестве владельца или администратора рабочей области откройте /commerce и используйте форму продукта, чтобы создать черновик с именем, валютой, целочисленной ценой за единицу товара и дополнительным отслеживаемым запасом (для USD 1299 означает 12,99 долларов США).
2. Активируйте его и создайте локальный тестовый заказ; подтвердите, что сервер вычисляет общую сумму и сохраняет снимок продукта.
3. Не подключайте реального поставщика платежей и не взимайте плату с реального покупателя. Если заказ не может быть выполнен, проверьте доступный запас и документированное состояние заказа, прежде чем повторять попытку.
Для пользовательского кода начните с предоставленного prompts/README.md и скопируйте ближайшее приглашение: prompts/new-app-screen.md для экрана приложения или prompts/new-landing-page.md для общедоступной страницы. Для работы с сервером, базой данных или провайдером дайте своему агенту кодирования задание из этого руководства и попросите его прочитать AGENTS.md, .ai/PROJECT_CONTEXT.md и соответствующие зеркала .ai/; проверьте точные исходные файлы, указанные здесь; список файлов и проверки перед редактированием; сохранять права собственности на рабочую область и секреты, доступные только серверу; и покажу вам разницу. Сообщите ему желаемое поведение, поля ввода и вывода, разрешенные роли, ожидаемые успехи и ошибки, а также тестовую учетную запись, поставщика или устройство. Используйте выборочные значения; никогда не вставляйте настоящий секрет.
Управляйте продуктами и запасами
/commerce обеспечивает управление владельцами/администраторами продуктов рабочей области. Состояния продукта: черновик/активный/в архиве; в ценах используются второстепенные денежные единицы, а запасы дополнительно отслеживаются. Общая персистентность находится в packages/db.
Это модуль создания продукта. Сюда не входит покупка этого комплекта, доставка исходного репозитория или выполнение лицензии продавца.
Следите за жизненным циклом заказа
Заказы ожидают ожидания → оплачены → выполнены, с возможностью отмены/пополнения запасов и возврата средств. Сервер вычисляет итоговые суммы и сохраняет снимки названия продукта/цены за единицу товара, поэтому изменения в продукте не перезаписывают исторические заказы. События commerce.order_* поддерживают нисходящую интеграцию.
Подключите реальный поток оплаты продукта сознательно. Смена состояния администратора сама по себе не подтверждает взимание комиссии или возмещение поставщиком платежей.
Тестовый набор и переходы между состояниями
Проверьте недостаточный запас, одновременные заказы, подделку цен клиента, недействительные обратные переходы, пополнение запасов при отмене, поведение возврата и доступ к нескольким рабочим пространствам.
Настройка и конфигурация
Поверхность /commerce управляет каталогом товаров и заказами активного workspace. Товары несут название, slug, цену в целых центах, трёхбуквенную валюту, опциональный URL изображения и опциональный учёт остатков; заказы хранят позиции в commerce_order_item с суммами, вычисленными на сервере.
Статус заказа движется только вперёд — pending → paid → fulfilled, с отменой до оплаты и возвратом после. evaluateOrderStatusChange отклоняет недопустимые, неизменённые или запрещённые переходы, поэтому отменённый или возвращённый заказ никогда не откроется заново.
/commerce owner/admin console
src/commerce.ts money math + lifecycle
src/commerce-actions.ts owner/admin mutations
commerce_product/order/order_itemРабочий процесс внедрения
Пишут только owner и admin — каждое действие разрешает сессию и workspace через requireWorkspaceManager. createCommerceOrderAction проверяет позиции (целые количества 1–9999, дубликаты товаров суммируются), ограничивает позиции активными товарами, пересчитывает суммы на сервере и держит заказ в одной валюте.
Отслеживаемый остаток уменьшается при создании заказа и пополняется при отмене; пустое поле остатка означает неотслеживаемый. Создание заказа и каждое изменение статуса испускают вебхуки commerce.order_created и commerce.order_status_changed плюс строки аудита.
Проверка и устранение неполадок
Проверьте, что участник ниже admin не может создавать товары или двигать заказы, что обратные и боковые переходы отклоняются, и что оплаченный заказ нельзя отменить. Убедитесь, что суммы приходят с сервера — никогда не доверяйте сумме от клиента — и что остаток возвращается после отмены.