总体架构
系统组成、边界原则、典型请求链路与数据归属
架构图
服务清单
| 服务 | 技术栈 | 职责 | 维护方式 |
|---|---|---|---|
oceanway-platform | Go；Console、Admin 前端为 React | 账号、全局登录与权限、积分钱包、价格、订单与支付、模型 API 中转与计费、使用记录 | 从最新 new-api 硬分叉，删掉不需要的部分，此后自主维护，不再跟随上游 |
oceanway-studio | Next.js 全栈 + PostgreSQL | Studio、Drama、Commerce 三个子站的业务与各自的产品管理页；一个应用，按子域名分流 | 基于 VOZEB-PRO 的仓库，AGPL-3.0；Drama、Commerce 原仓库迁移完成后归档 |
oceanway-site | 前端站点 | 品牌官网与产品入口 | 独立仓库 |
uumi（仓库 oceanway-text-gateway） | Go，new-api | 文本模型网关：服务现有模型对接客户，同时作为平台的文本上游 | 照常跟随 new-api 上游，不为 OceanWay 改代码 |
oceanway-media-gateway | Go | 视频模型供应：渠道适配、任务调度、结果交付 | 独立仓库，有独立的供应管理后台 |
三条边界原则
- 平台是账号、权限和钱的唯一持有者。 用户、会话、角色、积分余额、价格、订单和使用记录只存在平台数据库里。产品不存余额、不自建账号。
- 产品只做自己的业务。 作品、项目、素材、任务状态等业务数据存在产品工程自己的数据库里。产品要扣费，只能调用平台。
- 网关只做模型供应。 供应商、渠道、供应成本由 uumi 和媒体网关各自维护。网关不知道 OceanWay 的终端用户是谁，也不管客户售价。
这里的网关边界指 OceanWay 新平台的上游链路；uumi 自己的既有企业账号、价格和账务独立保留。图片与音频的供应入口尚待确认，建议使用 uumi，见模型中转的能力覆盖；它们同样必须经过平台鉴权和唯一钱包。
三条典型链路
一、开发者通过 API 调用文本模型
- 开发者用自己的 API Key 请求平台的模型 API（OpenAI、Claude、Gemini 格式均可）。
- 平台校验 Key，按该客户的价格方案预扣积分。
- 平台用自己在 uumi 的服务 Key，把请求转给 uumi；uumi 再转给供应商。
- 响应原样返回给开发者。平台从响应里读取实际用量，按客户价格结算，多退少补，并写一条使用记录，来源产品为“API”。
二、Studio 用户生成一个视频
- 用户已在任一 OceanWay 产品登录，Studio 通过主域名下的共享 Cookie 识别出同一个用户。
- Studio 后端以“产品服务凭据 + 用户身份”调用平台的视频接口。具体凭据形式见身份与权限。
- 平台预扣积分，把任务交给媒体网关；任务完成后按实际结果结算，使用记录的来源产品为“Studio”。
- Studio 只保存作品和任务的业务数据，不保存余额。
三、产品的非模型扣费
有些收费不对应一次模型调用，例如 Commerce 的批量导出、Studio 的视频合成。产品后端调用平台的内部扣费接口：先预留，完成后结算，失败则释放。每次请求带幂等键，重复提交只扣一次。
用户在 Console 里能看到上面三种扣费的全部记录，并按产品筛选。
域名与登录
所有产品部署在同一个主域名的不同子域名下。用户在任一产品登录后，平台在主域名下写入会话 Cookie，其他产品自动识别同一用户，无需再次登录。
登录状态和权限分开校验：登录了不代表有管理权限。权限分平台角色（如员工、财务）和产品角色（如 studio:admin），详见身份与权限。
数据归属
| 数据 | 归属 |
|---|---|
| 用户、会话、角色与权限 | 平台 |
| 积分余额、充值、订单、价格方案、使用记录 | 平台 |
| API Key | 平台 |
| 作品、项目、素材、产品内任务状态、产品内容治理 | 产品工程 oceanway-studio 的数据库，三个子站的数据按产品分开存放 |
| 渠道、供应商凭据、供应成本、网关侧账目 | uumi、媒体网关各自的数据库 |
平台客户任务、产品创作任务和网关供应任务分别持有，通过持久关联恢复；文件上传、长期素材、供应结果的归属与授权见共用任务与媒体。平台不建立通用创作 Project 或资产数据库。