> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # Коммерция Товары и заказы 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/`; проверьте точные исходные файлы, указанные здесь; список файлов и проверки перед редактированием; сохранять права собственности на рабочую область и секреты, доступные только серверу; и покажу вам разницу. Сообщите ему желаемое поведение, поля ввода и вывода, разрешенные роли, ожидаемые успехи и ошибки, а также тестовую учетную запись, поставщика или устройство. Используйте выборочные значения; никогда не вставляйте настоящий секрет. [Прежде чем начать](https://supastack.dev/ru/docs/web/before-you-start.md) [Основные сведения о терминале](https://supastack.dev/ru/docs/web/terminal-basics.md) [Локальная веб-настройка](https://supastack.dev/ru/docs/web/ship-in-5-minutes.md) [Подсказки агента и память проекта](https://supastack.dev/ru/docs/web/agents.md) ## Управляйте продуктами и запасами `/commerce` обеспечивает управление владельцами/администраторами продуктов рабочей области. Состояния продукта: черновик/активный/в архиве; в ценах используются второстепенные денежные единицы, а запасы дополнительно отслеживаются. Общая персистентность находится в `packages/db`. Это модуль создания продукта. Сюда не входит покупка этого комплекта, доставка исходного репозитория или выполнение лицензии продавца. ## Следите за жизненным циклом заказа Заказы ожидают ожидания → оплачены → выполнены, с возможностью отмены/пополнения запасов и возврата средств. Сервер вычисляет итоговые суммы и сохраняет снимки названия продукта/цены за единицу товара, поэтому изменения в продукте не перезаписывают исторические заказы. События `commerce.order_*` поддерживают нисходящую интеграцию. Подключите реальный поток оплаты продукта сознательно. Смена состояния администратора сама по себе не подтверждает взимание комиссии или возмещение поставщиком платежей. ## Тестовый набор и переходы между состояниями Проверьте недостаточный запас, одновременные заказы, подделку цен клиента, недействительные обратные переходы, пополнение запасов при отмене, поведение возврата и доступ к нескольким рабочим пространствам. [События исходящей торговли](https://supastack.dev/ru/docs/web/project-structure.md) [Блок сетки товаров](https://supastack.dev/ru/docs/web/project-structure.md) [Блок таблицы записей](https://supastack.dev/ru/docs/web/project-structure.md) ## Настройка и конфигурация Поверхность /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 не может создавать товары или двигать заказы, что обратные и боковые переходы отклоняются, и что оплаченный заказ нельзя отменить. Убедитесь, что суммы приходят с сервера — никогда не доверяйте сумме от клиента — и что остаток возвращается после отмены. ## Вперёд [Маркетинговые страницы](https://supastack.dev/ru/docs/web/marketing-site.md)