历史 · oceanway-commerce 实施计划
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
仓库：Oceanway-AI/oceanway-commerce。来源仓库已从 OceanWay-Commerce-Workspace 重命名并保留历史；正式产品 Host 尚待确认。
目标结果与当前基线
Commerce 的长期目标包含 Product、SKU、Campaign、内容方案、渠道发布草稿和商品业务工作流。现有实现是 React/Vite 电商 AI 工具 MVP：八个编号工具、任务运行器、结果比较与编辑/导出；身份和生成主要通过可替换 mock 适配器演示，部分业务数据使用本地 IndexedDB。该演示不代表共享身份、执行、资产、钱包或 MCP 已接通。
目标商品、SKU、Campaign 与 ChannelPublication 是本仓私有聚合；Core 只提供 Asset、Run、Agent、MCP Connection/Grant、Model Offering 和 Billing。首轮保留用户已选定的八工具优先界面，不因长期架构而恢复被隐藏的项目、素材、模板、品牌、活动和批量导航；是否启用这些模块须重新确认。
依赖与输出
| 类型 | 内容 |
|---|---|
| 上游 | Customer/Tenant、Project、Asset、Run/Agent、MCP、Model Offering、Billing Contract |
| 外部系统 | 渠道连接通过 MCP Connection/Vault/Tool Grant，不在 Commerce 保存明文 Secret |
| 写回 | AI 结果先成为候选 Asset/Copy；设置商品主图、更新 SKU 或发布渠道由 Commerce 命令决定 |
| 输出 | Commerce 聚合事件、渠道副作用记录、审批与费用证据 |
目标仓库里程碑（按确认范围逐步进入）
- COMMERCE-1 领域盘点：冻结 Product/SKU/Campaign/Publication Owner 与现有数据来源。
- COMMERCE-2 独立 Surface：接入 Customer Session、Tenant 上下文、CI、部署和 Host。
- COMMERCE-3 Asset 与内容链：商品素材、候选图文和版本通过稳定 Asset Reference 管理。
- COMMERCE-4 统一执行：内容生成使用 Core Run/Billing，结果按显式命令写回商品聚合。
- COMMERCE-5 MCP 与审批：渠道连接、工具授权、发布草稿、人工审批和幂等外部副作用。
- COMMERCE-6 生产验收：完成商品素材到渠道草稿的撤权、失败、重试、费用和回滚演练。
真实接入门禁与验收
- 生成链等待 B3/B5；外部渠道写操作等待 MCP、Vault、Tool Grant 和审批门禁。
- 撤销 Connection 后新 Run/发布立即失败，历史审计仍保留但不泄露 Secret。
- 同一发布 Operation 重放不会重复创建外部商品、Campaign 或渠道内容。
- AI 结果不自动覆盖 Product/SKU；所有写回都展示目标、差异、Actor 与付款方。
- 回滚不撤销已经成功的外部副作用；必要补偿必须通过渠道语义和受控命令执行。
产品定义见电商工作台与模型、Agent 与 MCP。
本轮需求、设计与原型
按统一实施流程和本地协调推进，产品、设计、商品数据和接口责任均由项目负责人承担。已有八工具基线为：AI 一键抠图、一键去白底、视频生成器、AI 编辑、产品美化、产品布景、AI 背景、AI 拍摄清单。
| 用户与任务 | 本轮要确定的结果 | 待确认的边界 |
|---|---|---|
| 小商家、电商运营 | 从商品参考图得到可用主图、场景图或短视频 | 首期重点工具、素材来源、输出格式/尺寸、单任务与批量优先级 |
| 商品内容设计人员 | 比较候选、保留品牌与主体、继续编辑或导出 | 哪些参数必须可见、参考图/模型选择方式、失败后如何继续 |
| 品牌/渠道负责人 | 后续把候选绑定商品或渠道 | Product/SKU/Campaign 是否进入本期，首期止于文件导出还是渠道草稿 |
本轮建议以“选工具 → 上传参考 → 选择真实支持模型/参数 → 提交 → 比较结果 → 导出/继续编辑”为第一条原型旅程，由负责人确认一项图片工具作为后续真实接入样板。第二条使用视频工具验证不同媒体参数与长任务状态；不能因 mock 返回图片就认为视频链已完成。渠道发布、数据回流和订阅保留后续候选，不自动纳入首版。
信息架构与原型页面
| 页面/区域 | 设计交付 | 必须覆盖的状态 |
|---|---|---|
| 八工具首页与左导航 | 保留八项顺序、桌面 4×2 入口和手机可读布局 | 选择、窄屏、工具未接通、不支持当前身份 |
| 工具任务运行器 | 上传、参考、模型、参数、预计影响与提交 | 空、加载模型、无可用模型、参数不支持、上传失败、重复提交防护 |
| 任务与结果 | 状态、多个候选、前后比较、继续编辑、下载 | 运行、成功、部分成功、失败、状态未知、恢复与不可用结果 |
| 单图片编辑器 | 复用既有图层、撤销和导出，不默认另造工作流 | 未保存、恢复、导出失败；手机浏览/任务/预览与桌面精细编辑分开 |
| 后续商品/批量/渠道 | 只做依赖和页面去向图，确认后再展开 | 无来源数据、未连接、无授权、未确认发布范围 |
先以现有浅色交易型界面、紧凑控制和较大工具名称为消费基线，列出其与统一 Ocean Foundation 的 token/组件差异供确认，不未经评审强换主题或组件库。交付桌面、390/430px 与键盘原型；浅深主题的支持范围明确标注，不因跨平台统一假定已有深色模式。
API 能力与真实数据 Owner
| 能力 | 当前实现 / 目标 Owner | 开发边界 |
|---|---|---|
| 登录和用户上下文 | 本地 MockAuth；有未完整接通的 API 适配 | 目标使用已批准的 Customer Identity，会话/Token 不在产品自建 |
| 模型和任务 | mock 注册表与任务；已有客户端 API 假设 | 重新映射到固定 Core Model Offering/Run Contract，旧 /v1/models、/v1/jobs 文档不等于平台已发布契约 |
| 上传、素材、设计与结果 | 现有 IndexedDB/本地 Blob、页面模型 | 先盘点所有权与迁移；正式文件进入共享 Asset，产品设计聚合按服务端范围保存 |
| Product/SKU/Campaign 绑定 | 长期业务模型，首期是否开发待确认 | Commerce 私有领域服务，AI 结果默认候选，不自动覆盖正式商品信息 |
| 用量与费用 | mock 演示不构成真实账务 | Core Billing 为目标；平台积分与广告费等第三方资金分开 |
| 外部渠道/发布 | 未接入 | MCP Connection/Vault/Tool Grant 与 Commerce 发布命令，凭据不进入前端 |
需求阶段同步建立“工具 → 输入素材 → 能力与参数 → 任务 → 结果 → 导出”文档表，设计时补客户端所需字段与 Owner 缺口。正式 API 文档必须覆盖上传授权、能力约束、任务状态、结果格式、失败/未知/重试、幂等、防重复扣费与权限；模型返回的能力决定可选参数，不能写固定供应商能力假设。旧 API-CONTRACT.md 作为适配来源核对，不直接升格为跨平台规范。
分阶段交付与依赖
- 需求：核定八工具首期范围、选定一条图片和一条视频旅程、明确商品管理/批量/渠道是否后续；记录所有 mock 与本地数据事实。
- 设计与原型：复用现有首页和运行器，补真实状态、参数差异、移动端与编辑导出交互；同步完成 API 需求草案，未接通功能明确演示。
- 最小纵向开发：先将一项工具接入真实身份、上传、Core 模型/Run/Asset 与费用链，验证服务端恢复后再扩到其他工具；不先铺开全部领域后台。
- 验收扩展：实际输入/输出/下载、失败与恢复、引用和用量一致后接批量/商品绑定；MCP 渠道写入等待独立需求、授权、幂等与审批设计，不能因为生成可用自动发布。