API、数据与基础设施

OceanWay 首期可以保持模块化单体，但接口、数据和运行边界必须按可独立演进的领域设计。本章定义各产品与共享内核如何通信、谁能写哪些数据、长任务如何可靠执行，以及故障后如何恢复和对账。

运行拓扑

公共站、公开开发者中心、产品 Web 和 Public API Edge 早期可以复用同一代码仓库与共享领域模块；网页 Host 也可以暂由同一 Web 部署按 Host 分流。Public API Edge 必须从第一阶段起成为独立部署单元、认证边界和限流边界，不能与网页请求共享进程入口：ai.oceanway.tech 只提供公开只读内容，登录后 Developer Control 位于 console.oceanway.tech/ai，api.oceanway.tech/v1 只接受机器凭据。它们不能依赖浏览器跨域访问内部服务或数据库。

接口分层

Product BFF 适合聚合页面数据；公共 API 适合稳定的程序调用；领域模块之间使用明确 Service Contract，不能通过“知道表名”集成。

客户 Webhook 是 OceanWay 向客户系统发布的公开事件，使用 Environment 下 Webhook Endpoint 自己的 WebhookSigningSecretVersion。Provider Callback 是未来可选的 Media Gateway 内部能力，不是独立平台服务；启用时必须使用不同入口、Provider Callback Secret、Schema 和处理身份，不能复用客户 Webhook、DeveloperCredential 或 ProviderCredentialVersion。

开发者入口与控制面

开发者产品固定使用三个相互隔离的入口：

Developer Access Domain 统一拥有 Developer App → Environment → Service Account → DeveloperCredential。Service Account 唯一归属 Environment，DeveloperCredential 唯一归属 Service Account；Console BFF 调用该领域的 Query/Command，不能直接写表或另建资源副本。

console.oceanway.tech/ai 的用量查询固定为 API Surface 视图。充值、购买、订阅、发票和跨产品消费总览调用 Console 的统一 Commerce/Billing 契约；Developer BFF 只能读取授权摘要或生成受控跳转，不能直接写钱包、订单或账本。

Playground 位于 console.oceanway.tech/ai。浏览器使用 Customer Session 调用同源 Developer BFF；BFF 从 Developer Access Domain 取得目标 App、Environment 和 Service Account 的 Access Snapshot，并向 Authorization/Policy Token Issuer 申请短期、单用途的内部执行委托，再进入与 Public API 相同的 Run、计量和计费链路。BFF 不能自行签发 Grant。Playground 不读取、恢复或向浏览器注入长期 DeveloperCredential，api.oceanway.tech 也不因此接受 Customer Session。

请求上下文

所有写请求必须显式携带或从受信凭据解析：

requestId
traceId
correlationId
operationId
actorPrincipalId
executionPrincipalId
authenticationType / authenticationRef
callerWorkloadPrincipalId?
organizationId
workspaceId
projectId?
billingAccountId?
idempotencyKey
expectedRevision?
clientVersion?

服务端按入口分别使用 Customer Session、DeveloperCredential、Playground Execution Grant 或 Workload Credential，并结合 Membership 与资源所有权验证这些值，不能信任浏览器自行声明 Organization、Service Account 或付款方。正式 API 的 Actor 和执行主体都是 Service Account；Playground 的 Actor 是 Customer User、执行主体是目标 Service Account；内部 Workload Principal 只描述当前服务 Hop，不覆盖业务 Actor。

requestId 对应一次入口或服务请求，traceId 对应一次分布式调用链，correlationId 连接跨队列、轮询、回调和补偿的长期流程，operationId 固定一次可能产生副作用的逻辑操作。异步消费者和未来 Provider Callback 通常创建新 Trace，并通过 Span Link、Correlation 和稳定领域 ID 关联原流程；不能把数小时任务伪装成一个持续不结束的同步 Span。

统一错误响应保留现有 { code, data, msg } 外壳，并增加机器可处理的稳定错误码、errorId、requestId 和可选字段级错误。内部 Provider 原始 Secret、账号、渠道、堆栈和重试策略不得进入公开响应。内部错误同时记录发生层级、阶段、提交确定性、重试与补偿语义，详细契约见管理员平台与运维控制面。

公共 API 规则

• URL 使用明确版本或兼容版本策略；
• 列表使用有界分页、稳定排序和游标；
• 创建接口接受幂等键并绑定请求指纹；
• 修改资源使用 expectedRevision 或 ETag，防止覆盖并发编辑；
• 长任务返回稳定 runId，通过查询、SSE 或 Webhook 获取状态；
• 媒体读取返回短期签名 URL 或鉴权流，不返回长期对象存储地址；
• 删除返回引用阻塞和影响摘要，不能偷换成归档；
• Deprecated 接口提供迁移文档、观测窗口和停止新调用时间；
• Webhook 使用签名、时间戳、事件 ID、重放保护和幂等消费。

DeveloperCredential 只在 api.oceanway.tech/v1 的 Public API Edge 鉴权，不能转发给私有网关或模型供应商。公开模型 ID 解析到 Model Offering，内部渠道细节保持私有。

长任务协议

规则：

• 创建和查询上游任务是不同动作，轮询超时不能再次调用创建接口；
• Worker 使用租约和幂等 Attempt，实例重启后可以接管；
• 上游状态未知时进入明确的未知/待对账状态，不自动重复外部副作用；
• 重试次数、间隔、超时和并发只能来自供应商契约、管理员配置或已有资源保护策略；
• 用户关闭页面不会取消服务端 Run；
• SSE 只是状态投影，断线重放不能重新执行任务；
• 取消必须区分“尚未执行”“上游已接受”“副作用已发生”。

媒体长任务的详细组件与状态边界见调度、执行与模型网关池。Media Gateway 以持久 Task/Provider Attempt 和 Poller/Reconciler 为基础；未来启用 Callback 时，内部 Handler 必须先持久化去重收据再形成 Observation。任何 Observation 都不能直接完成 OceanWay Run、登记正式 Asset 或写入用户账本。

数据所有权

即使这些表位于同一个 PostgreSQL Schema，模块也只能通过自己的 Repository 写入。数据库外键、唯一约束和事务保证领域内不变量；跨领域流程使用服务调用、Saga/补偿和事件。

存储职责

PostgreSQL

保存身份、所有权、领域状态、版本元数据、任务、账本、权限、审计索引和 Outbox。在线请求使用按租户、实体、状态、时间窗与分页的定向查询，不读取整表后在 Node.js 筛选。

对象存储

保存图片、视频、音频、文档和导出包。业务只保存稳定 storageKey；读取、下载、外部模型输入和 MCP 传输分别签发短期 URL。删除前检查 Asset Graph 与所有产品引用。

Cache

只缓存可再生的公共配置、目录或派生读模型。Membership、预算、Secret 状态和高风险审批不能依赖长时间缓存。写后读一致性要求明确的页面必须绕过或刷新缓存。

Search

索引资源标题、标签、授权摘要和必要内容。命中结果后再次执行租户和资源权限校验；索引删除滞后不能导致越权读取。

Analytics

保存脱敏、聚合的产品、质量、成本和业务指标，不作为钱包、权限或产品状态事实源。FDE 与案例指标需要保留来源和计算口径。

Secret Store

按用途保存加密 Secret 与轮换状态，不参与普通搜索、备份导出或业务 JSON 快照。DeveloperCredential 只在创建时返回一次 Secret，此后仅保存 Public API Edge 校验所需 Hash；WebhookSigningSecretVersion、MCPConnectionSecret 与 ProviderCredentialVersion 分别由 Developer Access、MCP 和私有 Gateway 的受控 Secret Store 托管。它们不能共享命名空间、Audience、加密材料或读取权限。

Telemetry Stores

Logs、Metrics 和 Trace 通过 OpenTelemetry-compatible Collector 进入专门后端。PostgreSQL 保存稳定运维对象、关联索引、Audit 和外部 Telemetry Reference，不长期承载全量高频日志、时序指标和 Span Payload。Telemetry 失败不能阻塞正常模型请求，也不能导致 Reservation、Usage、Ledger 或任务状态事实丢失。

事件与一致性

领域写入与 Outbox Event 在同一个数据库事务提交。事件总线按至少一次投递设计：

• Producer 固定 eventId、aggregateRevision、correlationId、可用的 operationId 和 Schema Version；
• Consumer 以 eventId 或业务幂等键去重；
• 失败消费者进入可观测重试或 Dead Letter，不阻塞原领域事务；
• 重放不能重复扣款、发布、发放权益或创建外部对象；
• Schema 变更保持向后兼容或提供版本化消费者；
• Search、通知、分析和任务摘要允许最终一致；
• 账本、所有权、权限与资源 Revision 需要强一致。

跨领域操作若包含外部副作用，使用 Saga 记录已完成 Step 和补偿状态，不使用分布式数据库事务假装外部系统可回滚。

队列与租户公平性

Scheduler 至少按以下维度做授权和公平调度：

• Organization / Billing Account；
• Product 与任务类型；
• 交互式、批量、后台和 FDE 优先级；
• 模型 Provider 容量；
• Project、Member、Agent 与 Service Account 预算；
• 已预占成本和并发；
• 企业 SLA（如有）。

限流和队列保护必须来自供应商公开约束、管理员配置或容量测试，禁止用固定重试次数和延时掩盖 Worker、租约或状态机缺陷。

Provider 路由与故障

UUMI/new-api 是 Text Gateway Pool；oceanway-media-gateway 是同级 Media Gateway Pool，并直接连接图片/视频 Provider。两个私有网关只接受 OceanWay Workload Principal 使用的短期 Workload Credential，均不承载终端用户、客户组、DeveloperCredential、公共模型目录、用户售价、钱包、订阅、产品 Run 或正式资产归属。ProviderCredentialVersion 只存在于对应私有网关。完整职责、状态机和迁移方案见调度、执行与模型网关池。

Text/Media Gateway Pools 与 MCP Gateway 隔离供应商差异：

• Logical Model Policy 声明允许的 Deployment 候选；
• Run 固定实际 Deployment、协议版本和价格快照；
• 熔断、健康状态和故障切换进入 Trace；
• 数据区域、训练政策和组织白名单优先于成功率；
• 已发生外部副作用或结果未知时禁止盲目切换 Provider 重做；
• Provider 下线不删除历史配置，只停止新请求；
• 供应商成本与 OceanWay 售价分别记录并对账。

可观测性与运维投影

可观测链使用不同标识协同，而不是复用一个万能 traceId：

Request ID
  → 当前入口与服务请求
Trace ID / Span ID
  → 当前同步或异步处理链及延迟
Correlation ID / Operation ID
  → Run、轮询、回调、恢复、补偿和外部副作用
Stable Domain IDs
  → GatewayTask、ProviderAttempt、AssetVersion、Reservation、Ledger 与 Audit

数据面边界：

• Logs：结构化服务诊断；不记录 Prompt、媒体、Secret、Authorization Header 或签名 URL。
• Metrics：延迟、成功率、队列、租约、Pool、Deployment、Provider、成本和租户公平性；标签保持低基数，禁止加入用户和请求 ID。
• Trace：服务调用、Run Step、网关与外部依赖；异步恢复和回调使用新 Trace 与 Span Link。
• Run/Gateway/Asset/Billing Fact：业务与经济事实，即使 Trace 被采样也必须可靠保存。
• Audit：主体、授权、资源、审批和特权动作的追加式不可变证据，不进入普通日志删除流程。

Operational Read Model 通过 Outbox 与私有网关规范化 Observation 关联这些事实，供 Admin Query 使用。它是可重建投影，不是新的事实源；数据缺失或延迟时必须显示摄取水位和“未观测”。Admin Command Gateway 只调用领域 Service，不直连数据库、Worker 或 Provider。

SLO、Alert、Incident、Run Explorer、Error Fingerprint、敏感调试和 Reconciliation 的操作员视图见管理员平台与运维控制面。

备份、恢复与灾备

需要独立保护：

• PostgreSQL 业务库与账本；
• 对象存储 Blob 与引用清单；
• Secret 加密材料与轮换记录；
• 搜索、分析和读模型的可重建策略；
• Provider、DNS、TLS、Webhook 和部署配置。

恢复演练必须验证数据库与 Blob 的引用一致性、账本总额、Run 接管、Webhook 重放、权限撤销和 Secret 可用性。RPO、RTO、多区域和数据驻留根据企业合同与真实容量确定，文档不得提前写入无依据指标。

部署演进

Stage A：模块化单体

• 各客户网页 Host（包括公开 ai.oceanway.tech 与 console.oceanway.tech/ai）和一个内部 Admin Host 早期可以由同一 Web 部署按 Host/Surface 分流；机器入口 api.oceanway.tech/v1 必须使用独立部署单元、认证与限流策略，但可复用同一仓库和领域模块；Admin 使用独立 Workforce Session；
• PostgreSQL 与对象存储共享基础设施；
• 领域模块、Repository、Outbox 和 Worker 保持清楚边界。

Stage B：容量拆分

• 公共站独立缓存与发布；
• Public API Gateway 独立限流；
• 常驻 Worker 和队列独立扩容；
• Search/Analytics 形成独立读模型。

Stage C：风险与团队拆分

• Identity、Billing、Execution、Asset、Text Gateway Pool、Media Gateway Pool 与 MCP Gateway 按各自故障域和团队边界独立演进；Media Gateway 的任务注册、Poller/Reconciler 与可选 Callback 仍属于其内部实现；
• 保持稳定 Resource ID、Service Contract、Event Envelope 和 Trace；
• 任何拆分必须有双读/校验、切流和回滚方案。

服务化的触发条件是团队边界、容量、合规、故障隔离或独立发布节奏，不是“架构看起来更先进”。

基础设施不变量

• 浏览器不直接访问数据库、内部 Worker 或供应商 Secret。
• ai.oceanway.tech 只提供公开开发者中心；登录后 Developer Control 只在 console.oceanway.tech/ai；公共机器调用只在 api.oceanway.tech/v1。
• Developer Access Domain 统一拥有 Developer App → Environment → Service Account → DeveloperCredential，其他产品和控制面只通过稳定服务契约使用。
• DeveloperCredential 与 Playground Execution Grant 在 Public API Edge 终止，私有网关只接受内部 Workload Credential。
• DeveloperCredential、WebhookSigningSecretVersion、MCPConnectionSecret、ProviderCredentialVersion 与 Workload Credential 不得混用。
• 每个领域只能直接写自己拥有的数据。
• 所有写请求有 Actor、租户上下文、幂等键和可追踪 Request ID。
• 长任务创建、查询、重试、取消和外部副作用语义分离。
• 领域事件至少一次投递，消费者必须幂等。
• 账本、权限、Revision 和资源所有权保持强一致。
• 搜索、分析和通知永远不是业务事实源。
• Logs、Metrics、Trace 和 Operational Read Model 永远不能代替 Run、Gateway、Asset、Billing 与 Audit 事实。
• 管理员查询只读授权投影；所有处置通过幂等领域命令并产生 Audit，不能直接改表。
• 任何自动故障切换都不能突破数据策略、预算或副作用安全边界。
• 备份完成不等于可恢复，必须定期演练。
• SLO、RPO、RTO、并发和超时来自合同、供应商约束与实测数据。