商城与支付模块

商城功能以系统表单和服务端 Commerce Provider 组成，而不是把业务流程写死在单个 Vue 页面中。产品、商品图片、购物车、订单和付款状态都保存在管理数据库；前端表单、DataGrid、Action Code 与后端支付 API 共同完成操作。

支付边界

PayPal、微信支付和信用卡都必须通过服务端 Provider 创建订单、验证回调并更新订单状态。浏览器只能发起支付和跳转，不能决定“已付款”。支付 Provider 的密钥应放在 User Secrets、受保护 secrets 文件或环境变量，绝不能保存在表单 JSON、客户端 Action Code 或 `appsettings.json` 的版本库内容中。

支付 webhook 必须使用支付服务商提供的签名/事件验证，并可重复处理：同一事件多次投递时只能把订单推进到正确状态一次。反向代理部署时应正确配置公开 base URL 和 forwarded headers，否则回调 URL、许可证 origin 与支付返回地址可能不一致。

商品图片与共享媒体

商品、公开下载资料和模块文件应调用 `IMediaService`，owner 使用稳定的模块命名空间（例如 `commerce`）。业务记录保存后用 `ReplaceReferencesAsync` 建立引用；这样删除媒体时可以检测仍被商品使用的资产。请参阅 [共享媒体服务](SHARED_MEDIA_SERVICE.zh-CN.md)。

维护原则

1. 表单结构由系统表单定义和 Designer 管理，CommerceSystemForms 的语义同步不会覆盖管理员的无关编辑。

2. 数据库结构使用模块 migration，不能依赖启动时临时建表。

3. 新 API 统一返回 `PlatformErrorResponse`，前端以 toast 显示可翻译错误。

4. 订单金额、库存、付款结果和退款决策必须在服务器端重新计算和校验。

English edition: COMMERCE.md.