PDOC-COMMERCE-01-001 Commerce
电商 AI 工具子站的定位、现状与迁移计划
Commerce 面向电商运营、商品摄影和内容制作人员。用户进入后直接选择一个 AI 工具，上传商品素材，拿到可以投放的图片或视频，不需要先建项目或理解平台架构。
首期八个工具
| 编号 | 工具 | 标识 |
|---|---|---|
| 1 | 去除背景 | remove-background |
| 2 | 去除白底 | remove-white-background |
| 3 | 商品视频生成 | video-generator |
| 4 | AI 编辑 | edit-with-ai |
| 5 | 商品美化 | product-beautifier |
| 6 | 商品场景图 | product-staging |
| 7 | AI 背景 | ai-background |
| 8 | 拍摄清单 | shooting-list |
每个工具使用相同的任务生命周期：queued（排队）、running（运行）、succeeded（成功）、failed（失败）、cancelled（取消）、unknown（执行待确认）。可选模型由后端按工具动态返回，同一工具可以有多个模型。代码里还定义了重新上色、扩图、智能阴影等工具，首期不开放。
API模式中的网络异常或创建响应丢失不能直接判为失败。恢复保留原业务任务、请求指纹和原调用身份，只查询、核对或保存原任务结果；排队、运行或unknown状态禁止以“重试”创建新的生成请求，后台也不重新派发已经进入发送阶段的任务。同一业务身份携带不同正文或参数时返回409。原任务进入明确终态后，用户主动重新生成视为新的业务意图并使用新的业务身份。
设计原则
- 打开即选择工具，一级界面不出现次要工作流。
- 八个工具在左侧工具栏和主区保持一致的编号、名称和顺序。
- 用真实商品视觉展示能力，不用抽象图标代替结果。
- 桌面端高效操作，移动端可浏览、上传、运行和导出。
现状
oceanway-commerce 保留Vite + React前端与显式mock模式。2026-10-10新增API模式，项目、设计、上传及任务通过Studio内的 /api/commerce BFF持久化，复用同一PostgreSQL/File业务事务与可靠outbox，不另建Commerce生产后端。任务保存实际Studio source task编号；后台恢复保留Commerce凭据和归属。产品活动页与任务页显示原调用及同步状态，Platform Admin/Console按产品原调用编号联查同一业务尝试。仓库内的 PRODUCT.md、API-CONTRACT.md 保留既有产品原则，当前增量的实跑范围与未接供给见平台product-business-events专项。
当前API模式的模型目录和生成仍复用Studio现有逻辑模型与图片/视频任务入口；共享BFF和业务事件接线不表示模型执行或账务已经切换到Platform。sourceCallIds保存服务端核验的原Studio任务编号，尚无真实平台模型操作时operationIds保持空，不能用本地消费预留编号代替。页面的recordSync区分本地未接入、待同步和已交付；mock模式明确未接入平台，其IndexedDB不承担API模式的后台可靠队列。当前同源配置、显式账号绑定和运行参数见仓库 API-CONTRACT.md。
迁移计划
按路线图第 4 阶段迁入 oceanway-studio，成为 Commerce 子站：
- 前端迁入
src/products/commerce/。 - 继续使用Studio内共享BFF实现任务提交、状态查询、结果存储和导出，复用产品任务运行与对象存储；保持Commerce产品scope和授权，不另建独立生产后端。
- 按产品总述中的三件事接入平台；模型列表来自平台的模型目录。
- 迁移完成后，
oceanway-commerce仓库归档。
待定事项
Commerce按全域记录与产品运营 PL-021/T-13/AC-16保留本域使用/生成/消费与专属套餐、活动运营。商品/活动的规则、发布、购买/参与和权益由Platform统一持有，Console/Admin可查看同一事实；产品通过自身作用域接口管理和查询，不新增支付或权益账。具体创作工具与运营闭环仍按分项实现验收。
- 八个工具中，首期哪些做成真实闭环。
- 批量处理是否首期支持。
- Commerce 子站的正式子域名。