交付路线图与决策记录

OceanWay 不应同时重写所有产品。实施顺序必须先冻结跨平台契约，再把现有 OceanWay Studio、模型/API 和统一计费接入共享边界，最后让漫剧、电商与 FDE 使用同一底座。

当前能力与目标差距

“当前实现基础”只代表仓库已有候选，不等于生产环境、真实上游和商业运营已经正式验收。

依赖顺序

管理员与运维不是 Phase 8，也不是业务功能全部完成后再补的大屏。ID、错误、审计和读模型从 Phase 0 开始；独立 Admin Surface 在 Phase 1 建立；统一 Run 后完成只读诊断；告警、Incident 和写命令再按证据逐步开放。

Phase 0：冻结核心契约

在新增组织表和新工作台前完成：

• 统一术语与 ID 规则；
• 冻结 requestId、traceId、correlationId、operationId 和领域稳定 ID 的不同语义；
• Organization、Workspace、共享 Project 外壳；
• Resource Envelope、Revision 与 Relation；
• Run 状态机、Step、Attempt、Execution Manifest；
• Gateway Deployment、Execution Route、Usage/Provider Cost Fact；
• OceanWay Execution Attempt ↔ gatewayTaskId ↔ Observation/Usage/Cost 契约；Provider Task、Supply、Credential Version 和可选 Callback Receipt 保持网关内部私有；
• 统一 Error Envelope、提交确定性、Gateway Diagnostic Observation 和 Telemetry 脱敏契约；
• Billing Account、Meter Event、预算和账本边界；
• 领域事件信封、版本和幂等规则；
• 权限 Scope、数据分类、MCP 风险级别；
• ADR 模板和架构 Owner。
• Admin Query 与 Admin Command 边界、Audit 和危险动作职责分离。

退出门禁：核心实体、状态机和不变量经产品、研发、财务与安全共同确认；不得由单个页面实现反向决定平台契约。

Phase 1：统一身份与控制面

• 为现有用户创建个人空间、默认 Workspace 和 Billing Account。
• 引入 Enterprise Organization、Membership、Invitation、Workspace 与 Project。
• 建立统一应用启动器和组织/Workspace/Project 上下文。
• 建立 console.oceanway.tech 客户控制层 Surface，作为应用、上下文、购买、治理和 FDE 私有交付的统一大厅。
• 在 Console 中建立可切换的 Developer 专业空间，复用全局组织上下文但使用独立的开发者任务导航。
• 所有新 API 解析统一 Request Context。
• 资产、任务和钱包页面始终展示所有者、付款方和产物归属。
• 保留当前客户站点登录能力，将 Console 接入同一 Customer Identity，并确定集中 IdP 的演进方案。
• 将 oceanway-vozeb 固定为 OceanWay Studio 基座，停止新增归属 OceanWay Studio Host 的开发者产品能力。
• 将现有 /admin 作为迁移基座映射到 admin.oceanway.tech，建立独立 Workforce Client、Audience 与 Host-only Session。
• 企业客户管理员继续使用客户身份和 Organization 权限，不能换取内部后台 Session。

退出门禁：同一用户可在个人空间与两个企业组织间切换；任何列表、深链接、Run 和账本均无跨组织泄漏。

Phase 2：计费账户与开发者身份

• 把现有“用户积分账户”泛化为 Billing Account。
• 现有个人余额、权益、订单和流水映射到个人 Billing Account。
• 增加 Workspace/Project/Member/Product/Agent/API 预算。
• 引入 Developer App、Environment 和 Service Account。
• 个人用户自动创建 Personal Space、默认 Developer App、development Environment 与受限 Service Account；所有 Key 都作为 Credential 挂在该资源链上。
• 将公开模型、文档、价格、状态和更新日志迁到 ai.oceanway.tech；将 Apps、Environment、Service Account、Credential、Playground、API 用量、请求日志与 Webhook 迁到 console.oceanway.tech/ai；将机器调用迁到 api.oceanway.tech/v1。
• 在 console.oceanway.tech 完成统一购买中心、订阅授权和产品内升级回跳。

退出门禁：网页与 API 使用同一付款账户但不同认证方式；企业余额不足不会改扣个人余额；成员离职不破坏企业生产 Key。

Phase 3：资源图与统一执行

• 建立 Resource Registry、AssetVersion、Relation 与权限感知索引。
• 为现有媒体、创作资产、Canvas 与生成记录补充 Workspace 所有权和稳定 Revision。
• 将现有 Agent/生成任务映射到统一 Run、Step、Attempt 与 RunOutput。
• 引入 Execution Manifest、Transactional Outbox，以及 Request/Trace/Correlation/Operation 与领域 ID 协同关联。
• 接入独立 oceanway-media-gateway，通过不透明 gatewayTaskId 验证提交幂等、原任务查询、冻结 Credential Version、未知状态对账和结果获取；其 Registry、Poller/Reconciler 与未来可选 Callback 均为网关内部模块。
• 建立开发者异步查询、正式 Asset 登记，以及 202/queued 保持预占、终态成功结算、失败释放的闭环。
• 泛化现有 projectHandoff 为跨产品 Handoff。
• 全局任务中心读取统一 Run 投影。
• 建立只读 Operational Read Model、全局 ID 检索、Run Explorer、Error Fingerprint，以及 Text/Media Pool 独立健康视图。

退出门禁：一次网页或 API 媒体生成可以从输入版本、模型部署、Run、费用到输出 Asset 完整还原；重放和重试不会重复扣费或创建结果。

Phase 4：Canvas、Agent 与 MCP 组合

• 从 OceanWay Studio 的无限画布工具中明确抽取共享 Canvas Runtime 契约。
• 建立 Agent、Agent Revision、Deployment 与“运行/查看定义”分离权限。
• 建设 MCP Connector、Connection、Credential、Tool Version、Tool Grant 与 Gateway。
• 建立 Context Package 和显式 Return Binding。
• 为外部发布、调价、删除和财务操作增加审批 Step。
• 允许 OceanWay Agent 以最小权限调用模型和 MCP。

退出门禁：Canvas/Agent 分享不泄露 Secret；撤销 MCP Connection 后新 Run 立即失败；高风险外部写操作可审批、幂等和审计。

Phase 5：漫剧与电商接入

• 漫剧保留 Episode、Scene、Shot、Review 与 Composition 私有聚合。
• 电商保留 Product、SKU、Campaign 与 ChannelPublication 私有聚合。
• 两者只通过 Asset、Canvas Binding、Agent Run、MCP 和 Billing 使用共享内核。
• 建立“在 Canvas 打开”“发送回产品”“发布前审批”和全局任务回跳。
• 明确现有 /drama 向独立漫剧工作台入口的迁移路径；正式名称、Host 和首期部署方式另行确认。

退出门禁：至少完成一条漫剧端到端链路和一条商品内容到渠道草稿链路，刷新、失败、重试、撤权和费用均可验证。

Phase 6：企业与 FDE

• 企业 SSO、SCIM、Managed Identity 与条件访问。
• 企业席位、授信、合同额度、发票和高级预算。
• 数据外发策略、DLP、数据驻留和客户审计出口。
• FDE Engagement、Delivery Workspace、Milestone、Deliverable 与 Acceptance。
• 落实 FDE 双界面：oceanway.tech/fde 与 /cases 负责公开展示，Console 负责授权后的私有交付。
• 限时支持访问、交付移交和项目结束清理。
• CaseStudyRelease 的客户批准、脱敏、指标口径与撤回。

退出门禁：企业成员入职/离职、FDE 工程师临时访问、客户生产移交和公开案例发布均完成演练。

Phase 7：开放生态

在内核运行稳定后再考虑：

• OceanWay MCP Server；
• SDK、CLI、Webhook 与事件订阅；
• Agent、Canvas Template 和 Connector 生态；
• 合作伙伴能力包；
• 市场交易与收益分成。

开放市场不是首期目标。没有版本、权限、计量、审核和下架机制前，不应把 Agent 或 MCP 做成公开市场。

横向管理员与运维交付线

这条交付线与业务 Phase 并行推进。完整对象、页面和门禁见管理员平台与运维控制面。

数据演进原则

项目尚未正式上线时，优先直接采用新表和新所有权模型，不为未发布历史写复杂兼容层。需要保留的开发/候选数据按显式映射处理：

企业数据从启用 Organization 后直接写入新模型。任何回填都需要数量、金额、资源哈希、引用和权限核对；账本不得通过“复制最终余额”替代原始可追溯分录。

架构决策记录

每个 ADR 后续应补充背景、候选方案、选择理由、影响、回滚条件和批准人。表中的“本文建议”不能被实现团队当作已经授权的产品决定。

P0 待决策

进入数据库设计前优先确认：

1. 是否正式接受“共享 Project 外壳 + 产品私有聚合”。
2. Workspace 是否永远使用所属 Organization 的 Billing Account，还是允许企业合同指定其他付款方。
3. 用户端长期使用“积分”还是引入多币种/额度展示；会计账本与产品余额如何命名。
4. 跨 Workspace 支持授权引用、复制、转让中的哪些能力，首期默认是什么。
5. Prompt、Knowledge、Agent Memory 是否作为 Asset 类型，还是独立资源域。
6. Run 未知上游状态、超时、取消、补偿与人工对账的正式状态机。
7. MCP 写工具的审批默认值和企业可配置范围。
8. 用户注销、企业法定留存、账本不可变与 Legal Hold 的优先规则。
9. Media Gateway 首期是否只提供创建、查询和结果读取，还是同步交付按 Provider 能力声明的 Cancel；Provider Callback 保持后续按需启用。

新产品接入前还需确认：

• 漫剧独立入口和现有 /drama 的迁移方式；
• Console 首期在应用大厅与购买中心之外，同步上线资产总览、任务中心和企业成员管理中的哪些模块；
• 旧 ai.oceanway.tech/v1、OceanWay Studio Host /v1 与开发者页面的关闭方式及兼容窗口；
• API 媒体结果是否默认登记 Asset；
• 模型下线时已发布 Agent/Canvas 的替代策略；
• FDE 交付 IP、Agent、Prompt 和 Connector 的标准合同口径；
• 公共案例审批、指标证明和撤回机制。

内部运维上线前还需由组织与安全负责人确定：

• Workforce IdP、生产访问网络和设备策略；
• 值班 Owner、Incident Severity、升级与客户沟通责任；
• Telemetry 后端、采样、保留、数据区域和 Legal Hold 策略；
• 生产路由、敏感调试和财务处置的审批矩阵。

非功能目标

可用性、延迟、吞吐、租户公平性、RPO、RTO、数据驻留和成本告警必须在真实容量与合同级别确定，不能用无依据常数代替设计。首轮至少建立以下可测指标：

• 登录与组织切换成功率；
• 权限拒绝正确率与跨租户测试覆盖；
• Run 创建、排队、成功、取消和未知状态比例；
• Provider 成功率、延迟、费用与故障切换；
• Text/Media Pool 独立 SLO、Alert 和 Incident 时间线完整性；
• Reservation 未结算时长和对账积压；
• Asset 落盘、引用完整性和删除阻塞；
• MCP 调用、审批、失败与外部副作用；
• Workspace/Project/产品维度成本；
• Outbox、Gateway Observation、Telemetry 与运维读模型摄取新鲜度；
• 备份恢复与凭据撤销演练结果。

架构验收场景

发布一个阶段前至少覆盖：

1. 个人用户加入企业后，个人与企业资产、钱包和 MCP 完全隔离。
2. 企业成员只访问一个 Workspace，并受 Project 预算限制。
3. Service Account 通过 API 生成媒体，登记 Asset 并在 Canvas 继续编辑。
4. OceanWay Studio 的 /canvas 只返回候选 AssetVersion / CanvasRevision，由漫剧领域确认写入 Shot；失败不会覆盖原版本。
5. 电商 Agent 调用 MCP 创建渠道草稿，发布动作需要审批。
6. 成员离职后 Session、Run Token、个人 Connection 立即失效，企业资产和生产 Service Account 保留。
7. 上游超时、重复轮询或未来重复回调、Worker 重启和用户刷新不重复扣费或外部发布。
8. FDE 客户只在 Console 访问获授权的私有 Engagement；交付物经授权、脱敏并创建独立 CaseStudyRelease 后才能进入公共案例。
9. 客户提供一个 Public Request ID，值班人员可以在授权范围内还原 Run、Gateway、Asset 与 Billing 链，无法观测处明确显示未知。
10. Provider 提交状态未知时不能盲目重试；原任务查询、结果恢复和账务处置进入 Reconciliation Case。
11. 未获得 JIT Grant 的客服不能查看客户 Prompt、媒体、Secret 或执行生产命令。
12. 一个 Pool 或 Provider 故障不会把整个 OceanWay 标成不可用，恢复后能够扫描受影响任务、资产、账务和 Webhook。

非目标

现阶段不做：

• 为了“未来扩展”立即拆成大量微服务；
• 用一个万能 JSON 表承载所有产品；
• 允许产品直接读写其他领域数据库；
• 把每个预算做成独立钱包；
• 让网页、API 与内部模型共享未过滤列表；
• 自动跨组织复制资产或切换付款方；
• 在没有审批和治理前开放 Agent/MCP 市场；
• 为未上线旧数据建立长期兼容层。
• 让企业客户管理员进入 OceanWay 内部 Admin Host；
• 让控制面直连 Gateway 数据库、直接改 Ledger 或用 Logs/Trace 推断业务终态；
• 在关联、确定性、幂等、权限和审计尚未完成前建设通用“一键修复”。

文档治理

• 架构总览记录稳定原则，实施细节进入对应领域文档。
• 任何 P0 决策改变后同步 ADR、数据模型、API 和验收场景。
• 当前实现与目标态分开描述，候选测试不能写成生产事实。
• 发生重复架构争议时，先补充 ADR，再写代码。
• 每个新产品接入时补充自己的聚合根、共享引用、Run、账务和删除矩阵。