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 /zh/docs/web/commerce.md (or send Accept: text/markdown).

电商

工作区商品与订单，单向推进的生命周期。

询问本指南

初学者演练

先决条件：阅读下面的两个初学者指南，完成 Web 本地设置，并在编辑器的根目录中打开此 monorepo。网页设置属于apps/web/.env.local； Next.js不读取根.env。默认fake模式下的/dashboard是无数据库演示； /auth 需要迁移数据库。

简而言之：工作区是一个团队的单独用户、数据和设置。服务器是可信后端；让提供商密钥远离浏览器和电话代码。迁移是创建或更新表的版本化数据库更改。人工智能模型是回答的引擎；型号目录是服务器上可用型号 ID 和价格的列表。提供商是一种外部服务，例如人工智能、电子邮件或计费服务。权利是允许工作区使用某项功能的授权。 Webhook 是一个服务发送到另一个服务的 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 界面为活动工作区管理商品目录和订单。商品包含名称、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 才能写入——每个动作通过 requireWorkspaceManager 解析会话与工作区。createCommerceOrderAction 验证订单行（1–9999 的整数数量，重复商品自动合并），限制行项只能是已上架商品，在服务端重新计算总价，并让订单保持单一货币。

被追踪的库存在创建订单时扣减、取消时回补；库存字段为空表示不追踪。创建订单与每次状态变更都会发出 commerce.order_created 和 commerce.order_status_changed webhook 以及审计行。

验证与排障

验证 admin 以下的 member 无法创建商品或移动订单，反向与横向转换被拒绝，已支付订单不可取消。确认总价来自服务端——绝不信任客户端提交的金额——并确认取消后库存会回补。

电商