Developer Center 与 Console AI 信息架构

OceanWay Developer 使用“公开 Center + Console 专业空间 + 独立 API Edge”三段式架构：

Developer 仍是一个完整逻辑产品与领域，但不再建立第二套登录后客户后台。Console 提供客户身份、上下文、治理和商业外壳；Developer Access Domain 提供专业资源命令；Public API Edge 提供机器运行入口。

总体旅程

从公开内容进入登录后能力时，Center 只生成到 Console 的受信链接。登录、组织选择、App 选择、Credential 管理和 API 调试均发生在 Console；正式程序调用只发生在 API Edge。

公开 Developer Center

导航

ai.oceanway.tech
├── 首页
├── 模型
│   ├── 能力
│   ├── Family / Variant
│   ├── 协议与参数
│   └── 生命周期与公开费率
├── 文档
│   ├── 快速开始
│   ├── API Reference
│   ├── SDK
│   ├── 幂等与错误
│   └── 异步 Run 与 Webhook
├── 价格
├── 状态
└── 更新、弃用与迁移公告

Center 的所有内容无需登录。它可以提供“进入控制台”按钮，但不因 Cookie 呈现客户名称、余额、最近 App 或个性化模型授权，也不提供账户菜单。

首页

首页回答 OceanWay 提供什么、如何调用、生产接入为什么可靠：

• 主要动作是“查看模型”“阅读快速开始”和“进入控制台”；
• API 示例基础地址固定为 https://api.oceanway.tech/v1；
• “进入控制台”指向 console.oceanway.tech/ai，必要时由 Console 发起登录；
• 首页不把 Provider 数量、Channel、Supply 或网关拓扑包装为客户能力。

模型

目录只读取发布到 api Surface 且允许公开发现的 Model Offering Revision。模型按“能力 → Family → Variant”组织，每个详情至少包含：

• 稳定公开模型 ID、Family、Variant 与生命周期；
• 输入输出模态、协议、参数 Schema、同步/流式/异步能力；
• 限制、区域、数据政策和迁移建议；
• 公开列表价、计量单位和价格生效时间；
• 文档、状态和 Console Playground 的链接。

公开目录不展示客户合同价、余额或个性化授权。点击“在 Playground 中试用”跳转 Console 并携带公开 Offering ID 作为选择提示；Console 必须重新鉴权。

文档

文档只描述 OceanWay 公共契约。示例使用公开模型 ID、api.oceanway.tech/v1 和不可用的占位 Secret。UUMI/new-api、Media Gateway、Provider Adapter 与服务间 Workload Identity 只属于内部文档。

价格

价格页展示 OceanWay 列表价、计量单位和公开适用条件。购买路径为：

ai.oceanway.tech/pricing
→ console.oceanway.tech 选择付款主体
→ 购买、企业审批或合同流程
→ 返回 console.oceanway.tech/ai 的原 App/Environment

合同价、钱包余额、订单、账单、发票和授信不进入公开 Center。

状态

状态页公开客户可理解的 API 产品、能力和区域状态以及已确认 Incident。Provider、Supply 和 Credential 故障映射为 OceanWay 服务影响；内部健康列表不能直接作为公开状态页面。

Console AI 专业空间

导航

console.oceanway.tech/ai
├── 总览
├── Apps
│   └── App
│       └── Environment
│           ├── Service Accounts
│           ├── Credentials
│           ├── Limits / Budgets
│           └── Webhooks
├── Playground
├── API Usage
├── API Runs / Logs
└── Developer Security / Audit

Console 全局顶栏继续提供 Organization、Workspace、Project、应用切换器、通知和账户入口。AI 空间内部导航只解决 API 接入任务，不重复钱包、成员、发票或全平台任务中心。

总览

AI 总览聚合当前上下文中的 App、Environment、Credential 风险、最近 API Run、API 用量、Webhook 投递和服务状态。它读取权限感知投影，不成为新的资源或账务事实源。

Apps 与四层资源

Apps 页面是以下层级的专业管理界面：

Developer App
└── Environment
    └── Service Account
        └── Credential

所有创建、修改、停用、轮换和撤销操作都由 Console AI BFF 提交给 Developer Access Domain。BFF 不直接写数据库，不保存可逆 Secret，也不根据前端状态自行判断权限。

Playground

Playground 用于验证 Public API 契约，不是 Canvas 的替代品，也不能要求用户把长期 API Key 粘贴进浏览器。

运行流程：

1. 浏览器以 Console Host-only Customer Session 向 Console AI BFF 提交测试输入。
2. BFF 解析当前 User、Organization/Personal Space、App、Environment、目标 Service Account 与允许的 Offering，并从 Developer Access Domain 取得 Access Snapshot。
3. BFF 向 Authorization/Policy Token Issuer 申请短期、受限的 Playground Execution Grant；BFF 与 Developer Access Domain 均不自行签发。
4. BFF 以服务端请求调用 api.oceanway.tech/v1，API Edge 校验 Grant Audience 和约束。
5. BFF 将标准流或结果脱敏转发给浏览器；Run、Meter 和 Billing 记录来源为 Playground。

Grant 至少绑定 App、Environment、Customer User Actor、目标 Service Account、Offering/操作、有效期、使用约束和审计身份。Service Account 是唯一 API 执行主体；Grant 只是委托证据，不新增 Playground Principal。它不具备资源管理权限，不进入 URL、本地存储或客户端日志，也不能替代长期 Developer Credential。

Credentials

完整 Secret 只在创建或轮换响应中出现一次。Console 页面之后只展示前缀、尾号、状态、到期时间、最后使用、Service Account 和安全策略。Console 顶层安全页可以展示相同元数据并发起紧急撤销，但不能创建或回显 Secret。

API Usage 与 Logs

AI 空间只展示 api 和 playground 来源：

• Usage 以 App、Environment、Service Account、Credential、Offering 和时间聚合 Meter/Billing；
• Logs 以请求和 Run 为中心展示状态、延迟、标准错误、公开参数摘要与关联 ID；
• 两者都不混入 Canvas、漫剧、电商等网页产品消费；
• Console 顶层账务和任务中心可以跨产品聚合相同事实；
• Provider Cost、Channel、Supply 和内部错误只进入 Workforce Admin。

Webhook

Webhook Endpoint 归属 Environment。Console AI 管理 Endpoint、事件订阅、签名 Secret Version、投递状态、失败与重放。签名 Secret 一次显示且不复用 Developer Credential；重放原事件不能创建新业务 Run 或重复结算。

页面与命令所有权

Developer Access Domain 是 App、Environment、Service Account、Credential 的唯一 Command Owner。Console AI 是任务入口而非数据 Owner；Developer Center 没有客户写操作；API Edge 只消费已发布的 Access Snapshot 和 Credential 校验结果。

跨站上下文

Center 到 Console 的链接只携带不敏感提示：

offeringId?
docPath?
intent = open_app | playground | create_credential | purchase
returnUrl

登录后上下文由 Console 服务端解析。链接不得携带 Credential、Secret、权限快照、余额或内部 Route。returnUrl 只接受 OceanWay 受信 Origin。

Console 到客户服务端没有自动 Secret 传递。用户必须在一次性创建界面安全保存 Credential，并遵循服务端环境变量或 Secret Manager 的接入说明。

Session 与安全

• Developer Center 不需要 Customer Session，也不读取父域 Cookie；
• Console 使用 Customer Audience 的 Host-only Session；
• API Edge 不接受 Customer Session 或浏览器 Cookie；
• Playground 由 Console BFF 使用短期受限授权调用 API Edge；
• Developer Credential 面向客户服务器，不应嵌入浏览器、移动端包或公开仓库；
• Admin 使用独立 Workforce Identity，不能复用 Console Session；
• Text/Media Gateway 只接受内部 Workload Principal 使用的短期 Workload Credential。

页面状态与故障隔离

• Center 不可用不应影响 Console 或已有 API 调用；
• Console UI 不可用不应中断已有 Credential 的 API 调用；
• Public API 故障不应阻断 Console 的组织、钱包和其他产品管理；
• 公开内容局部失败时展示数据时间与模块状态，不退回登录页面；
• Console AI 读模型延迟时标注新鲜度，不能把缓存估算当成账单终态；
• Gateway 故障只展示 OceanWay 标准状态和错误，不泄漏内部拓扑。

当前实现基线

当前项目已经具备 Developer Host 路由、首页、模型、个人 Key、用量、Surface 和 /v1 代理。但模型页面目前需要登录，Key/用量位于 ai Portal；缺 Apps、Environment、Service Account、Playground、Logs 和 Webhook；用量混合 Web/API；父域 Cookie 是共享登录候选；/v1 未限制到独立 API Host。

目标状态

目标完成后，ai.oceanway.tech 完全公开且无客户控制面；所有开发者私有工作都位于 console.oceanway.tech/ai；机器流量只进入不接受 Customer Session 的 api.oceanway.tech/v1；四层资源命令只由 Developer Access Domain 执行。

实施阶段

验收标准

1. 未登录可以访问 Center 的模型、文档、价格、状态，响应不读取客户私有状态。
2. ai.oceanway.tech 不存在 Apps、Keys、Usage、Logs、Webhook 或账户管理的 Canonical 页面。
3. 所有私有 Developer 链接进入 console.oceanway.tech/ai，登录后返回原可信意图。
4. Playground 浏览器请求和存储中没有长期 Developer Key；API Edge 只看到受限 Grant。
5. App、Environment、Service Account、Credential 的写操作均经过 Developer Access Domain。
6. AI Usage/Logs 不混入网页产品；Console 顶层可以汇总全平台事实。
7. api.oceanway.tech/v1 不接受 Customer Session、父域 Cookie 或 HTML 登录跳转。
8. Center、Console 和客户响应不含 Provider、Channel、Supply、上游模型/任务 ID 或私有网关地址。

延伸阅读

• OceanWay 开发者平台
• 应用、服务身份与凭据
• 公共 API 执行架构
• 开发者平台迁移计划
• 统一客户控制台