历史 · 基于 new-api 的平台拆分分析
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
当前实施基线：从官方源码重新开始。 用户已明确放弃旧项目代码作为新版本实现基础。旧代码与补丁不自动移植；需求、业务经验和已确认设计仍可参考。新工作目录为
/Users/wangzihao/Projects/OceanWay/platform/oceanway-platform，分支codex/newapi-foundation，基于官方提交385d2dfd10d821b25c8a6766bd16eea248cb1652。已建立与上游代码树一致的工作区，尚未修改应用代码或连接生产数据。
日期：2026-09-11。用户已明确新方向：以最新版 new-api 的后台为项目基础，前端可以全部重做；建设 Console、Developer，并通过 Site 进入 Studio、Drama、Commerce 等子站。Developer 已确认是公开模型、文档、教程门户，登录后的管理全部放 Console。本文完成代码结构分析与拆分建议，尚未执行应用重构、数据库迁移或生产切换。
1. 结论与版本证据
把官方 new-api 后台作为共享账号、API Key、额度、订阅、模型接入和调用任务的实现基础。Console、Developer、Studio、Drama、Commerce 和管理员界面按产品需求重新建设，通过 API 使用共享能力，不以旧 OceanWay 代码为实现依赖。new-api 前端只用于核对功能与接口调用，不作为组件、路由、框架或布局约束。先拆清后台模块与接口，再按需要拆运行进程，不给每个子站复制一份账户、额度和计费数据库。
本轮已实际 fetch 官方 upstream，并以固定提交读取后端与前端源代码；本地工作目录未切换、未合并。
| 基线 | 核验结果 | 用途 |
|---|---|---|
| 官方 main | 385d2dfd10d821b25c8a6766bd16eea248cb1652，提交时间 2026-09-11 23:15:29 +08:00 | 本文所有“新版已有”结论的固定代码来源 |
| 官方最新取得的 tag | v1.0.0-rc.37 指向上述 main 提交 | 候选开发基线；tag 不等于已验证生产版本 |
| GitHub latest Release API | 查询返回 v1.0.0-rc.36，发布时间 2026-09-08；标签提交 ea7cb0ba4e0f82e2bfa5e55752eb68bdf902f71b | 区分 Release 对象与最新代码；名称含 rc，API 当时 prerelease=false，不据此宣称稳定 |
| 旧 Text Gateway / uumi 来源 | 1689474114dc9797753396b6cf03f9a357172df8，检查时工作目录干净 | 历史对照，不作为新版本代码基线；未据此推断线上部署版本 |
源码：固定 main、rc.36 Release。
历史核对：旧本地与固定上游树比较有 2,936 个文件变化。upstream/main..HEAD 有 5 个本地独有提交，但其中 b8f27fe28 涉及大范围文件导入。用户已选择从官方源码重新开始，旧提交不加入新分支，也不再安排逐补丁迁移；视频供应 SKU、图片分辨率计价等仅作为需求是否仍需满足的参考。
2. 源代码实际由哪些部分组成
后端仍沿用 Router → Controller → Service → Model 的 Go / Gin / GORM 结构。固定提交的 go.mod 声明 Go 1.25.1。前端为 web/src/features 与 web/src/routes，使用 React、Rsbuild、TanStack Router；本地旧代码的 web/default、web/classic 路径不能直接套用。
| 模块 | 已核验的代码入口 | 新平台建议归属 | 需要补齐或验证 |
|---|---|---|---|
| 登录与会话 | service/auth_session.go、model/user_session.go、middleware/auth_origin.go、router/api-router.go | 一套共享身份后端；Console 提供账户与安全管理 | 多子站登录交接、登出／撤销传播、原产品账号映射 |
| Key 与调用授权 | router/api-router.go 中 /api/token，router/relay-router.go 中 TokenAuth | 共享后端；Console 开发区展示 | API Key 与用户会话区别；组织／项目授权不得用用户分组直接替代 |
| 额度与结算 | model/quota_reserve.go、service/billing_session.go、service/funding_source.go | 共享后端唯一维护额度；Console 展示消费和支付 | 跨产品计费归属、持久结算幂等、故障恢复 |
| 订阅与购买 | router/api-router.go 中 /api/subscription、/api/user/topup/* 及支付回调 | Console + 共享后端 | Studio 积分、套餐和余额迁移映射；既有支付回调不能直接改路由 |
| 客户模型目录 | web/src/features/pricing、model-pricing，/api/pricing、/api/user/models、/v1/models | Developer；Site 可以引用公开信息 | 匿名价格与客户可用模型区分；不暴露供应商凭据和内部配置 |
| 文本调用 | router/relay-router.go、relay/、relaykit/ | new-api 原有接入／供应执行模块 | 保留流式协议、错误语义、用量与请求关联 |
| 异步任务与结果 | router/task-router.go、router/task-plugin-protocol-router.go、model/task_plugin.go、service/task_polling.go、service/task_billing.go | 共享任务接入；媒体网关继续执行供应商任务 | 自研网关协议适配、重复提交、超时未知、取消、结果归档 |
| 日志与用量 | /api/log/self、/api/log/self/stat、/api/usage/token；管理员日志有独立授权 | Console 查看客户调用与账户汇总；Admin 查看运维审计 | 产品任务 ID、调用 ID、费用记录间关联；数据筛选必须由后端授权 |
| 管理员运营 | router/channel-router.go、router/authz-router.go、service/authz；channels/users/task-plugins/system-settings 等前端功能 | 现有 Admin 产品或受保护运营界面 | 避免将运营模型、渠道、任务插件配置搬进客户界面 |
3. 子站及页面拆分
Site 是公开入口，不承担用户余额或模型执行。用户也应能直接访问各子站；跳转到子站本身不代表完成统一登录。
| 产品 | 页面和功能 | 后台复用与功能参考来源 | 产品特有部分 |
|---|---|---|---|
| OceanWay Site | 品牌、产品入口、案例、方案、联系 | 已确认品牌与内容需求；new-api 公开模型／价格仅作数据来源 | 独立重新建设商业展示与内容 |
| OceanWay Console | 账户资料、安全、会话、钱包、充值、订阅、消费总览、Key、Playground、调用日志、产品入口 | features/profile、security、wallet、subscriptions、keys、playground、usage-logs 和 dashboard 客户部分 | 产品入口、后续组织／工作空间管理；登录后的管理统一在此 |
| OceanWay Developer | 公开模型目录、文档、教程、服务状态 | pricing、model-pricing、现有 Docs / Developer Center 内容 | 使用能力时进入 Console 对应位置；不维护私有 Key 或账单管理 |
| OceanWay Studio | 对话创作、Agent、画布、素材、短剧等 | 旧 Studio 的需求和业务经验；后台从新基础接入 | 重新实现创作会话、画布状态、资源关系、产品执行步骤 |
| OceanWay Drama | 分集、剧本、共享角色场景、分镜、视频段、正式结果选择 | 已有 Drama V2 需求 | 重新实现产品，不继承旧短剧代码结构 |
| OceanWay Commerce | 商品图／视频工具、批量任务、商品与品牌素材 | 已确认 Commerce 需求 | 新页面和真实业务接口；不以旧 mock 代码作为产品基线 |
| OceanWay Admin | 用户、渠道、模型供应、计费配置、任务插件、运维日志 | new-api 后台运营能力 + 已确认 Admin 需求 | 新管理界面及后续跨产品运营视图 |
Developer 的公开门户边界已由用户确认。旧文档“Developer Center 待归档、不再开发”不能继续作为本轮产品前提；旧内容可作需求参考，但新实现从官方后台能力与新前端设计开始，仓库名称和域名不在本轮自动重命名。
新版 /models 页面有 Admin 角色检查，属于运营模型配置。客户目录应复用 pricing / 可用模型数据。usage-logs、dashboard 等混合角色功能需要连同接口授权一起拆分，不能只复制页面再隐藏菜单。管理员模型路由证据。
表中的 web/src/features 路径用于定位已有功能与接口，不表示要复制前端实现。所有产品前端按已确认 OceanWay 设计与实际需求重新建设，技术栈和导航不受上游前端限制。旧产品源代码不作为新版本依赖。
前后端拆分的交付对象是接口能力：逐页面建立用户动作、调用端点、鉴权、字段、分页、错误与状态的映射；上游接口合适则直接使用，只有需要聚合或隔离适配差异时才增加 BFF。界面变化本身不要求再实现一套账户或计费逻辑。
4. 建议的运行结构
该图是建议结构：共享后台与文本 Relay 首期可以是同一个 Go 服务的模块，不引入一次通过 HTTP 再调用另一份 uumi 的重复文本代理。只有媒体请求经适配器调用独立媒体网关。
Console / Developer 按独立产品界面建设，可以共享新平台组件和 API 客户端；不要求沿用 new-api 的前端项目或技术栈。Studio / Drama / Commerce 依据需求重新选择和实现前端。后端数据库归服务所有；各产品只写自己的业务数据，不直接修改 new-api 用户、Token 或额度表。
原 TypeScript Core / Contracts / API Edge / 产品实现退出新版本代码基线，相关业务规则仅作为需求和验收参考。新版本不依赖旧仓源码、发布包或数据库迁移脚本。旧目录和 Git 历史原地保留，未删除文件或中断其他任务；生产数据的后续处理与代码重启分开制定。
此前保留自研媒体网关的供应服务定位继续作为外部接入边界；这不代表导入旧 OceanWay 平台代码。若要改变该外部服务本身的范围，需另明确，当前不重写或停用已有媒体服务。
5. 统一登录和调用身份
新版已具备访问令牌、持久登录 Session、刷新及撤销接口，也有刷新／退出的 Origin 校验。但这些不是开箱即用的任意多域名 SSO。会话实现、Origin 校验。
建议先验证中央登录与子站服务端会话交接：登录返回仅接受已登记的子站地址，子站 BFF 获取可验证的用户身份；若需跨站兑换，新增短期单次授权码接口并绑定目标子站。该接口是待开发能力，不冒充 new-api 已有 OAuth 授权服务器。不要把供应商密钥、全局管理 Token 或长期用户 Key 放进跳转 URL。
开发者直接调用使用自己的 API Key；Studio 等产品使用用户会话与服务端委托调用。new-api 已有 /pg 用户会话调用路径，可作为适配参考，但不能据此认定所有媒体任务协议都接受同样身份。应逐入口核对，并确保最终归属同一用户账户；账户余额只在共享后台扣一次。
用户分组、管理角色与模型权限不能自动等价为组织、工作空间、项目协作。先列出 Drama / Studio 所需权限，用受限扩展补齐，避免把完整企业 IAM 作为所有页面的先决条件。
6. 媒体网关的接入切片
新版提供 POST /v1/tasks/:key、任务查询和 artifact 访问，并有插件协议映射及持久轮询机制。协议路由、轮询实现。
首个适配切片选择现有媒体网关的一种视频任务，逐项映射：
- 输入与能力参数、估价、用户账户和产品任务关联。
- 平台任务 ID、网关任务 ID、提交幂等；提交响应丢失时先查原请求，不能直接再次收费生成。
- 排队／执行／成功／失败与未知状态；new-api 查询媒体网关，媒体网关管理供应商内部状态。
- 结果 URL／artifact、实际用量、差额结算和失败退款。
- 重复查询、重复回调、取消请求、Worker 接管；取消不是已验证的通用任务端点，需要另核协议。
平台任务表示客户可追踪的调用，网关任务表示供应商执行。二者通过 ID 关联；避免双方都独立重试同一次供应商提交。产品层另外保留“某个分镜采用哪个结果”等创作语义。
7. 并发与一致性：已有能力和验证边界
新版 TryReserveUserQuota / TryReserveTokenQuota 包含 Redis Lua 余额检查与扣减，数据库路径使用带余额条件的更新，不需要照搬旧 Core 每次累计历史账本的查询模式。已有测试覆盖无 Redis、缓存预扣、持久化失败补偿等场景。这些是可复用的并发基础，本文没有运行上游测试或压测，不能据此承诺吞吐或所有故障下账务正确。预扣源码、对应测试。
需要优先验证的具体窗口：
- Redis 预扣、数据库持久化和批量队列是分步处理；批量未落库时发生 Redis 故障／回源，需要验证整体余额不被重新放大，不能把单条 Lua 的原子性当成整个账务事务原子性。
WalletFunding.Refund明确是非幂等增量，不能盲目重试。要支持产品服务重试命令，需要以稳定业务操作 ID 建立持久去重和恢复记录。RefundTaskQuota/RecalculateTaskQuota先调整额度、后写回任务额度标记；轮询虽然使用状态 CAS，但不代表费用调整与任务标记在同一事务。崩溃、回写失败需要专门恢复策略。- 文本长连接、任务受理速率和轮询／回调写入分别测量；多实例需约束数据库连接总量和轮询领取方式。
证据：资金来源、任务结算。以上为静态检查发现的验证点，尚不是故障复现报告。
8. 本机实施顺序
| 工作包 | 具体工作 | 可验收成果 |
|---|---|---|
| N0 干净源码基线 | 从官方固定提交创建独立开发分支；新树与官方树一致，不导入旧补丁；开发使用隔离数据 | 已建立 platform/oceanway-platform / codex/newapi-foundation；应用运行验证待做 |
| N1 产品与模块边界 | 按 OceanWay 需求设计 Console / Developer、Site 入口和 Admin；从 new-api 后台映射接口，旧前端仅作功能参考 | 页面→API→模块→数据的映射表及关键原型 |
| N2 Console / Developer 首个接入 | 在隔离环境复用身份、Key、目录、钱包和日志；验证子站登录交接 | 两站共用一个账户，客户不能访问管理员数据 |
| N3 双入口调用 | 一条开发者文本流、一条 Studio 视频任务走同一共享计费基础 | 同用户余额正确，调用／任务／费用可关联，失败可追踪 |
| N4 产品扩展 | 基于新后台逐步建设 Studio、Drama V2 和 Commerce；新增资产／项目能力 | 每个产品至少一个真实业务闭环，旧实现不作为依赖 |
| N5 恢复与容量 | 多账户和热点账户、长连接、故障恢复、旧账户迁移演练 | 指定硬件及配置下的容量报告、账务核对、恢复和回退步骤 |
N1 的产品需求、设计与原型继续落实用户原定优先级；N2/N3 的接口可行性验证可反向修正设计。两条产品线都是目标，不因先做某个验证切片而取消其他产品。
新版本从官方干净分支开发和验证，不合并旧项目补丁。后续更新官方源码使用明确的版本与变更审查；既有发布规范仍适用于实际生产部署。本轮没有更改生产或执行应用迁移。
9. 对旧计划的影响
- 原“new-api 仅保留私有文本供应能力，账户／钱包全部迁往另一套 Core”的拆分假设，改为以本页的新方向重新评估。
- 原 Developer Center 归档安排重新评估；不自动把历史目录改名为用户所说的 Developer 新项目。
- B0–B6、Core / Edge / Contracts 的旧开发依赖是旧方案基线，不能未经映射直接作为新架构开工条件。
- 保留已确认创作需求、Drama V2 产品规则、Commerce 需求与设计规范作为输入；旧代码退出新版本实现，不继续安排代码移植。
- 每个产品不一定对应一个新后端或一套数据库；首先按页面、模块和数据所有者拆分。
10. 验证范围与下一步
已完成：官方 refs 获取；固定提交的路由、核心鉴权／预算／任务文件、前端功能目录与代表性页面权限检查；本地定制提交与目录差异核对；产品 README / Drama V2 基线对照。
未完成：全量源码审计、生产版本核对、干净基线启动、接口运行测试、性能测试和新产品实现。逐补丁迁移已退出本轮计划。源码显示已有能力不代表当前 uumi 生产环境已经运行该版本。
首个应落地的设计成果是 N1 的页面与接口映射，随后以 N3 证明复用方案实际可行。上游 docs/openapi/api.json 与 docs/openapi/relay.json 可作为文档起点，但需与本页核对到的路由和实际接入版本对齐。