开发者平台迁移计划

本计划将当前开发者 MVP 迁移到正式架构：ai.oceanway.tech 只保留公开 Developer Center，所有登录后开发者能力迁入 console.oceanway.tech/ai，api.oceanway.tech/v1 作为不接受 Customer Session 的机器入口。开发者资源采用 App → Environment → Service Account → DeveloperCredential；所有请求进入统一 Run/Attempt；文本和媒体分别进入同级私有网关池。

迁移目标

完成迁移不以“新页面已出现”为标准，而以身份、执行、账务、网关和资产事实已经收口为标准。

当前基线

目标基线

迁移完成后必须同时成立：

1. 匿名用户可在 ai.oceanway.tech 查看模型、文档、价格和状态。
2. ai.oceanway.tech 不读取客户私有状态；登录用户只在 console.oceanway.tech/ai 管理 App、Playground、Credential、API-only Usage、Logs 和 Webhook。
3. 个人用户自动拥有 Personal Space 和默认 App 链路；企业 App 归 Organization。
4. 机器流量只进入 api.oceanway.tech/v1，API Edge 明确拒绝 Customer Session。
5. 每次调用都有 Service Account；Playground 以 Customer User 为 Actor，通过短期 Grant 委托目标 Service Account 执行。所有调用同时固定 Offering Revision、Run、Attempt、价格快照和 Billing Account。
6. Text Gateway 与 Media Gateway 同级且私有；OceanWay 不再直接管理媒体 Provider Credential。
7. 异步状态、结果登记、结算和对账由持久事实驱动，不由 HTTP 成功码猜测。
8. Console 提供全平台总览、钱包、购买、订阅、账单和组织治理。
9. Developer Access Domain 是 App、Environment、Service Account 和 Credential 的唯一 Command Owner。
10. Playground 由 Console BFF 使用短期受限授权调用 API，浏览器不接触长期 Developer Key。

迁移原则

• 先建新事实源，再切读写。 不通过页面改名掩盖旧数据所有权。
• 先影子验证，再单写切换。 可以比较只读结果，不能让同一业务请求同时提交两个网关。
• 一个 Attempt 只属于一条执行路径。 已提交任务不从旧网关搬到新网关。
• 旧任务原路终结。 切换只影响新建 Run；历史任务继续由原执行器查询到终态。
• 账务优先可解释。 不确定事实进入待对账，禁止为追求成功率重复生成或猜测退款。
• 公开 ID 保持稳定。 Provider、Channel 和 Gateway 的变化不能迫使客户修改公开模型 ID。
• 客户 Secret 不迁入网关。 Developer Credential 始终终止于 OceanWay Edge。
• 四层资源只有一个写入口。 Center 无客户命令，Console BFF 与 API Edge 均不得直接写 Developer Access 存储。
• Session 与执行凭据分离。 Customer Session 只用于 Console，Public API 只接受正确 Audience 的机器凭据或短期受限 Grant。
• Playground 不使用长期 Key。 Console BFF 代表已授权用户服务端执行，浏览器不持有 Developer Credential。
• 迁移开关按 Offering/Environment 生效。 禁止依赖随机进程状态或不可审计的全局开关。

数据映射

若现有 Secret 无法安全迁移，采用明确的重新签发流程，不通过长期保存可逆密文换取无感迁移。迁移完成后删除“再次查看 Secret”的产品能力。

工作流依赖

Host / API contract
        ↓
Tenant + App identity ──────┐
        ↓                   │
Model Offering Revision    │
        ↓                   │
Run / Attempt / Billing ←──┘
        ↓
Text Gateway contract + Media Gateway contract
        ↓
Async query / Output / Webhook
        ↓
Public Center + Console AI read models
        ↓
Traffic cutover and old path retirement

Center 与 Console AI 的视觉开发可以并行，但 Apps、Keys、Usage、Logs 和 Playground 不得先写一套临时客户端数据模型，也不得绕过 Developer Access Domain。

阶段 M0：冻结契约与观测

交付：

• 冻结 Public Center、Console AI 和 Public API Edge 三个入口的职责；
• 冻结 Developer Access Domain 的唯一 Command Owner 边界；
• 定义 Public API、Run 状态、错误、幂等和 Webhook Schema；
• 定义 Customer Session、Developer Credential、Playground Grant 和 Workload Credential 的 Audience，并固定 Grant 由 Authorization/Policy Token Issuer 签发；
• 建立当前 /v1、渠道、任务、结算和 Key 的数量与一致性基线；
• 为旧执行路径补齐 requestId/operationId/traceId 关联；
• 禁止新增绕过 Surface、Run 或统一计费的新直连入口。

退出门禁：能够回答每个现有 API 请求由谁发起、调用了哪个逻辑模型、走哪条旧路径、是否扣费以及是否存在未终结任务。

回滚：本阶段只增加契约和观测，不改变流量。

阶段 M1：Public Center、Console AI 与 Host 分离

交付：

• ai.oceanway.tech 只保留公开模型、文档、价格、状态和进入 Console 的链接；
• 在 console.oceanway.tech/ai 建立登录后专业空间和可信回跳；
• 将旧 /keys、/usage 等私有页面迁移或重定向到 Console AI，Center 不再建立账户菜单；
• 建立 api.oceanway.tech 独立入口、证书、CORS/Origin、WAF、速率和日志边界；
• Center 示例、SDK 配置和 Console Playground 全部指向正式 API Host；
• 为旧 Host /v1 建立可观测的兼容策略，禁止无期限双入口。

退出门禁：Center 匿名浏览不读取 Session；私有页面只在 Console；生产 Key 只在 API Host 被接受；跨站登录和可信 returnUrl 回归通过。

回滚：旧私有 URL 可以继续重定向到 Console，不恢复 Center 私有页面；API 流量只能切回上一份已验证的独立 API Edge 部署，不能回到客户网页进程，Host、Audience 与限流边界始终保持。

阶段 M2：应用与服务身份

交付：

• 建立 Personal Space、Organization/Membership、Developer App、Environment、Service Account 和 Credential；
• 将 Developer Access Domain 建成四层资源唯一 Command Owner，Console AI BFF 只调用领域接口；
• 为个人用户幂等创建默认 App 链路；
• 新 Credential 只保存 Hash，并支持创建、轮换、到期和撤销；
• 建立 Developer Admin、Security Admin、Billing Admin 和审计权限；
• 将现有 Key 映射到默认链路或要求重新签发。

退出门禁：每个新 API 请求都能解析到唯一 App/Environment/Service Account/Owner；四层资源无旁路写入；停用父资源立即阻断子 Key；企业成员离职不删除生产身份。

回滚：资源表和旧 Key 映射保留；若新鉴权异常，可以在受控窗口回到旧验证器，但不得重新开放 Secret 回显。

阶段 M3：Model Offering 与统一执行

交付：

• 将 Logical Model 升级为 Offering + immutable Revision；
• 固定 web/api/internal Surface、Family/Variant、协议、生命周期、区域、数据政策和 Rate Card；
• 建立 Run、Step、Execution Attempt、Execution Manifest、Gateway Binding 和 Output；
• Quote/Reservation 在调用网关前完成；
• 同步调用也经过 Run/Attempt，不再由 Route Handler 直接承载业务规则；
• API Usage Read Model 从 Run、Meter 和 Ledger 投影生成。
• Console AI 的 Apps、Usage 和 Logs 读取统一投影；Center 不读取客户投影。

退出门禁：任一请求都可以从客户 requestId/runId 追溯到身份、Offering Revision、Attempt、预占和最终账务；浏览器不再收到 Channel/upstreamModel。

回滚：Offering 别名可以重新指向上一有效 Revision；已创建 Run 始终使用原冻结 Revision，不能回写更改。

阶段 M4：Text Gateway 收敛

交付：

• 将 UUMI/new-api 登记为 Text Gateway Pool 的 Deployment；
• 冻结服务间鉴权、Invocation ID、标准错误、Usage 和 Cost Fact 契约；
• 迁移文本、Embedding、Rerank 和流式调用；
• OceanWay 管理公开 Offering 和零售价，Text Gateway 管理物理 Channel 与 Provider Credential；
• 移除浏览器和 Developer 控制面中的物理渠道信息。

退出门禁：文本流式、断流、Usage、幂等和结算测试通过；网关不可用时不会静默切到 Media Pool 或直连 Provider。

回滚：按 Offering Revision 将新 Run 指回上一 Text Deployment；已开始的流式 Attempt 不切换。

阶段 M5：Media Gateway 接入

交付：

• 冻结 OceanWay ↔ Media Gateway 的 Workload Principal、短期 Workload Credential 和创建/查询/结果契约；
• 在 OceanWay 保存 executionAttemptId ↔ gatewayDeploymentId ↔ gatewayTaskId；
• Media Gateway 保存 Task、Provider Attempt、Supply、Credential Version、路由快照、Poll/Reconcile 和 Cost Fact；
• 先灰度同步图片，再异步图片，最后视频；
• 建立结果暂存、校验、OceanWay AssetVersion 登记和清理；
• 将 202 Accepted 改为保持预占，终态后再结算或释放。

退出门禁：进程重启、网络超时、重复请求、重复 Poll、结果下载失败和提交不确定场景均不会重复 Provider 提交或重复扣费。

回滚：仅把尚未创建的新 Run 路由回旧媒体路径；旧路径和新路径各自完成已有任务，禁止把运行中 Task 迁移或双写。

阶段 M6：Console AI、Playground 与异步产品面

交付：

• Public API 提供 Run 查询、结果读取和取消意图；
• Console AI 上线 Apps、Environment、Service Account、Credentials、API-only Usage、Logs 和 Webhook；
• Playground 通过 Console BFF 使用短期、受限的 Execution Grant，长期 Key 不进入浏览器；
• API Edge 对 Customer Session、错误 Audience 和越权 Grant 在创建 Run 前拒绝；
• 客户 Webhook 使用 Outbox、签名、幂等投递和重放；
• Console 汇总全平台 Run、Asset、钱包、购买、订阅、账单和组织治理；
• Center 到 Console 的开始使用/购买路径以及 Console 内返回 AI 空间的路径保留可信意图和 App/Environment 上下文。

退出门禁：用户可从 Center 模型发现进入 Console，完成“创建 App → Playground → 创建 Key → API 调用 → 查询 Run/Logs → 查看 API 用量”，同时在 Console 查看统一付款与全平台总览；浏览器全程没有长期 Key。

回滚：客户 Webhook 和聚合读模型可以暂停；Run、账务和 Asset 事实源不可回滚到页面本地状态。

阶段 M7：收口与删除旧路径

满足全部门禁后：

• 关闭 Developer Center、Console、Canvas 和 Marketing Host 上的生产 /v1；
• 删除 ai.oceanway.tech 上的登录后 Apps、Keys、Usage、Logs、Webhook 和账户管理路由；
• 删除 Key 再次回显和直接 User-owned Key 的写路径；
• 删除 OceanWay 内媒体 Provider Credential、直连 Adapter 和渠道级媒体路由；
• 删除由渠道目录自动公开 Model Offering 的逻辑；
• 将旧用量页改为 API Read Model，网页消费只在 Console/对应产品展示；
• 保留法定账务、Run、Audit、历史 Offering Revision 和旧任务查询证据。

删除前必须证明没有活跃旧任务、旧 Credential 流量、未对账 Reservation 或仍被引用的媒体结果。物理删除配置不能同时删除审计和账务事实。

流量切换策略

切换维度按以下优先级逐层放大：

内部测试 Environment
→ OceanWay 测试 Service Account
→ 指定个人/企业 canary Environment
→ 单个 Offering Revision
→ 单一能力/区域
→ 全量新 Run

每一步比较成功率、终态延迟、重复提交、Usage 完整性、预占龄期、结算差异、Asset 导入成功率和标准错误分布。Canary 只决定新 Run 的路径；不能在同一 Attempt 内同时请求旧链路与新链路。

回滚不变量

• 回滚只改变未来 Run 的 Route，不修改已冻结 Execution Manifest；
• 已获得 gatewayTaskId 或上游可能产生副作用的 Attempt 留在原网关恢复；
• 回滚不能删除 Meter、Cost Fact、Reservation、Ledger、Output 或 Audit；
• 未知提交先对账，不以“回滚”为名再次提交；
• 公开模型 ID 不变，必要时发布新的 Offering Revision；
• DeveloperCredential、Customer Session、Playground Execution Grant 和 Gateway Workload Credential 不互换。

迁移观测面

迁移仪表至少按旧/新执行路径、Gateway Pool、Deployment、Offering Revision 和 Environment 展示：

• 请求量、成功率、状态停留时间和终态延迟；
• 幂等命中、冲突和疑似重复 Provider 提交；
• Reservation 数量、预占龄期、结算/释放/退款和待对账；
• Usage/Cost Fact 缺失与价格快照差异；
• Gateway Task 未观测、Poll 延迟和 Reconciler 积压；
• 结果暂存、Asset 导入、哈希/格式校验和清理失败；
• Credential 鉴权、Scope 拒绝、异常 IP 与轮换覆盖率。

Telemetry 只作为诊断投影。切流和账务处置必须调用领域命令，不能直接修改仪表后的数据库字段。

总体验收

1. ai.oceanway.tech 只承担公开 Developer Center，console.oceanway.tech/ai 承担全部登录后开发者能力，api.oceanway.tech/v1 是唯一机器入口。
2. 公开模型、文档、价格和状态无需登录且不读取客户私有状态；Center 不存在私有控制面。
3. 个人默认空间与默认 App 链路可幂等创建；企业 App 在成员离职后仍归 Organization。
4. 所有四层资源命令由 Developer Access Domain 执行；Credential 均归属 Service Account，Secret 只显示一次且无法从存储恢复。
5. 所有 API 调用经过 Offering Revision、Run、Attempt、Quote/Reserve 和统一 Billing Account。
6. API Usage 可按 App/Environment/Service Account/Credential 查询，Console 可汇总全平台用量和钱包。
7. Text 只走 UUMI/new-api Text Pool，图片/视频只走 Media Gateway；两池私有、同级、不级联。
8. 异步媒体在断线、重启、重复 Poll 和提交不确定时不重复生成、不提前结算。
9. 客户和浏览器无法获得 Provider、Channel、Supply、Credential Version、上游模型或任务 ID。
10. 旧任务均已终结或有明确保留 Owner，旧入口、旧 Credential 写路径和媒体直连删除后无生产流量。
11. API Edge 拒绝 Customer Session；Playground 通过 BFF 的短期受限 Grant 执行，浏览器不持有长期 Developer Key。

延伸阅读

• Developer Center 与 Console AI 信息架构
• 应用、服务身份与凭据
• 公共 API 执行架构
• 调度、执行与模型网关池
• 统一客户控制台