文档
06 开发(跨仓)01_技术总览

DEV-X-01-007 跨项目公共能力收敛实施计划

保留多仓与new-api底座,统一React、Go、PostgreSQL、Redis,由Platform统一身份鉴权、可用模型与图片视频费用预估展示,并与Media共同管理系统资源

本文承接架构深度复盘,以已有系统为基础统一跨产品接入,保留独立业务仓、服务边界和产品工作流。具体实施建议为 Proposed;下列用户已明确的约束不再作为待确认选项。

1. 已明确的架构约束

  1. 保留多仓开发和独立部署,不合并整个系统的仓库。
  2. 技术栈统一为 React + Go + PostgreSQL + Redis。 新实现与产品后续重制按此目标执行。
  3. Platform 保留基于 new-api 的现有底座。 继续在当前分叉中增量开发,不另造登录中心、钱包、计费或模型转发核心。
  4. Platform 提供统一登录与鉴权,供各应用服务接入。 覆盖用户、会话、产品准入、员工操作及服务调用;产品对象权限由所属产品复核。
  5. Platform 与 Media 配合完成系统资源管理。 Platform 决定身份、归属、访问资格、权益和额度政策;Media 管资源实体、供应事实、文件版本、实际存储用量、引用与生命周期。
  6. 各产品保留业务数据、页面和工作流。 公共 SDK 负责调用和协议消费,不接管所有产品业务。
  7. 旧 Node/Python 服务无需兼容。 不新增对应后端 SDK 或兼容桥;Commerce 和 Agent 所需 Go 改造在相应产品工作中安排,不成为其他服务统一接入的前置条件。
  8. 各产品从 Platform 获取全部适用模型的可用目录;费用预估仅在图片/视频生成时展示。 模型可用性、参数契约和计价依据由 Platform 提供,产品不硬编码另一份模型清单或价格算法。文本模型正常调用和计费,本次不新增文本费用预估展示或为此新增文本预估接口。
  9. Creative是所有平台共用的画布和Agent基座。 Studio重制在Creative仓中推进,不代表Creative等于Studio;基座承接的任务、模型准入、消费和项目引用保持真实业务产品。具体边界见DEV-X-01-008。

上述边界与 ADR-0005中的 new-api 分叉方向衔接。该 ADR 冻结的是旧 Core/Edge/Contracts 方案,不意味着需要合并现有产品仓。现有 Accepted ADR 正文保持不变,具体冲突通过具名增量处理。

2. 当前基础应直接复用

能力已有证据本次处理
Platform 身份已有全局会话、identity、产品凭据、产品角色和 Admin 动作校验统一消费和错误语义,补具体接入/范围缺口,不重建账户中心
模型与费用预估已有产品运行模型目录、公开价格计算和媒体消费预览统一接入有效目录和图片/视频消费预览;核实媒体参数及团队付费覆盖,不扩展文本预估展示
Platform 执行已有 EXA、内部 relay、任务查询及非流式文本原请求恢复客户端复用;验证实际授权恢复,核实媒体首回执丢失后的定位保证,只补确认缺失部分
Platform 账务已有钱包、计费结算、订单及权益实现保持唯一权威;产品移除重复实现,不把账务算法搬入公共包
Media 资产已有统一 assets、原件、预留/用量、去重、引用、读租约及删除保护接入现行协议,完善产品映射和联调;不重新开发一套对象存储服务
运营已有 Platform Admin、动作权限、商业管理及部分投影共用身份和管理接口;补员工范围及产品领域接入
共享基座与产品Creative 已有 Go/React 基座,Studio在其中推进重制;Drama已有独立Go实现按实际业务产品接入,复用画布/Agent能力,保留产品流程和对象权限

以上是审计时点事实,不等于所有能力均已完成生产联调。证据附件记录版本和验证限制:Platform 文本恢复路由已观察到存在,实际制品来源仍须核对;Media 的当前实现与历史 File Owner/旧网关不能按相似仓名混用。

2.1 统一技术栈的实际差距

工程源码能力需要核实或改动的内容
PlatformGo/GORM 已支持 PostgreSQL;已有 Redis 会话/撤销缓存、限流及配额预占等机制核实实际主库、独立日志库和 Redis 启用状态;按目标配置/迁移,不更换 new-api 或 GORM
CreativeGo/GORM 支持 PostgreSQL 和 SQLite;已有 Redis 协调、实时消息及租约核实目标部署和存量;产品侧 PostgreSQL/Redis 接线可复用,中央接入仍须替换
Drama当前 Go/PostgreSQL 实现可延续Redis 只承担适合的缓存、限流或协调,不为技术栈一致强制迁移全部任务状态
Commerce当前源码为 Python + SQLite,未见 PostgreSQL/Redis 接线在后续产品重构中实现 Go/PostgreSQL/Redis;不开发旧 Python 兼容层

源码依据:Platform 数据库选择、Redis 配额协调、Creative 数据库入口、Commerce 任务存储。源码支持和部署模板不能证明现网已启用;本轮没有读取生产数据库连接凭据或业务数据。

PostgreSQL 承载持久业务事实、任务/回执、账务和资源元数据,各服务独立拥有其数据范围、迁移与凭据。Redis 用于缓存、限流、会话相关状态、实时通知和已采用的协调机制;Platform 已有配额预占路径,不能笼统描述为“Redis 只是可随时丢弃的缓存”。需要复用并验证其失效、重启及与持久账衔接的协议。统一技术栈不等于共用业务表,也不要求所有服务共享 Redis key 空间。

3. 多仓结构与公共代码边界

oceanway-platform        new-api分叉:统一身份/鉴权、模型执行、资金权益、资源政策
当前有效 Media 提供方    供应适配、资产文件、存储用量、引用与生命周期
oceanway-creative        跨产品画布与Agent基座;承接Studio重制并供其他产品复用
oceanway-drama-rebuild   Drama 的 React/Go 产品实现
oceanway-commerce        原仓内完成后续 React/Go 重构
现有运营工程             统一工作台及受控管理入口
oceanway-docs            唯一架构、需求、决策与验收文档来源
公共包发布位置           Go客户端与确有复用的React组件,不新增在线业务权威

本批固定由提供方维护独立Go模块:oceanway-platform/platformclient,模块路径为github.com/Oceanway-AI/oceanway-platform/platformclient。它与new-api根模块分开,不把平台数据库、账务实现和服务启动依赖带入消费方。材料接入由同一客户端通过Platform代理完成。原候选oceanway-shared不作为本批新建仓库;业务仓不搬迁,公共包不启动新的在线服务。模块发布、消费者固定版本和实际接入验收分别记录,未发布tag不能视为已可远程安装。

公共包应统一的内容留在提供方或产品的内容
Go 请求基础超时/取消、错误、请求关联、凭据允许集、有界重试服务配置和授权真相由提供方掌握,不自动透传所有凭据
Go Platform 客户端身份、可用模型与参数、图片/视频生成前费用预估、EXA、提交/查询/释放、权益及具名管理命令身份签发、计价/计费、退款和权限判定留在 Platform
Go 资源客户端经 Platform 的材料控制、上传、稳定引用、binding、读取与容量查询实际原件、用量、租约与物删留在 Media
浏览器客户端/React 组件公开类型、账号状态、模型参数、素材上传/选择与通用状态展示;Creative维护共享画布/Agent交互能力产品页面、画布宿主适配、分镜/商品领域流程、对象权限及结果采用规则留在产品
可证明重复的可靠性小模块回执、outbox、租约等相同机制和测试样例产品任务表、状态机和数据库事务不集中到公共库

Creative已有的画布和Agent作为跨产品基座建设,不能要求各产品分别重写。Platform公共客户端不承担完整Agent引擎、通用工作流、统一ORM或全产品UI框架;基座版本、宿主适配与产品业务边界在Creative实施范围内落地,共享部署或模块复用方式另行定稿。

正式 OpenAPI/事件协议与行为保证继续由 Platform、Media 等提供方维护。公共包的生成物标明来源版本,消费者固定不可变版本及 lockfile;手写的错误、恢复和凭据策略与生成代码分开。跨仓联调可用本地 workspace,但发布候选须在干净环境按固定依赖构建,不靠绝对路径 replace 或直接跟随公共仓 HEAD。

4. Platform 统一登录与鉴权

统一登录面向用户入口;内部 worker、Media 和服务间调用使用各自服务身份,不要求内部服务另建登录页面。每个应用服务注册可识别的调用主体和允许能力;受用户委托的调用同时保留真实用户/团队,不用一枚 root key 冒充所有人。

层次Platform 负责接入方负责
用户登录/会话登录、会话有效性、退出/封禁与撤销事实消费统一身份、处理失效;不另存一套账户密码或独立会话权威
产品准入用户/团队可使用哪些产品及能力在产品入口和敏感动作消费准入结论
服务身份产品/服务主体、凭据、允许动作与撤销保护自身凭据,限定目标服务,不转发到未知 origin
员工操作员工角色、产品范围、动作范围与受限委托列表/详情/导出/批量/命令统一验范围,记录真实操作者
产品对象权限提供可信身份及团队事实项目、作品、画布等 owner/member 与预期版本由所属产品复核

登录成功不等于项目 owner。已有全局 operations 查询适用于全局管理员,但可选 product 筛选不能作为“仅某产品运营”的权限边界;产品级员工访问必须在服务端限定允许范围。

4.1 保留现有凭据语义

凭据/能力实际用途禁止混用
用户会话当前用户及会话有效性不能代替服务身份、员工范围或产品对象权限
产品/服务凭据哪个服务调用、允许哪些动作不能任意指定用户扣费或充当管理员
EXA已授权执行与原任务关联不是模型请求幂等键,也不代表取消/退款事实
当前 mat1产品→Platform 的材料委托,关联用户、产品、key、会话版本与期限当前不含单文件/action/purpose 范围,不可直接给 Media 作控制面鉴权
Platform→Media 授权服务间资产控制请求不直接透传用户 Cookie 或 mat1
Media 数据能力当前为指定资源的临时读取;后续上传能力按正式合同另行启用不能扩大为控制面权限或永久文件身份

沿用提供方已有签发和校验机制补齐客户端,不平行设计一套 JWT/SSO。确有新增员工委托或服务范围要求时,在 Platform 现有授权模型中增加正式契约。凭据失效后的原单查询、释放和结算遵循提供方策略,不能通过保存用户 Cookie 或签发永久票据绕开撤销。

4.2 可用模型与图片/视频费用预估展示

每个产品通过自己的 Go 服务接入 Platform,浏览器不持有产品密钥。Platform 返回该产品及当前主体可用的模型、调用状态、支持协议、有效价格版本和参数规格;目录覆盖该产品适用的文本、图片、视频等模型。费用预估展示仅用于图片/视频,相关输入或参数变化后重新获取预估;文本不新增费用预估展示。公开展示目录不替代运行时可用目录,目录可见也不代替生成时的实时权限/额度校验。

已有接口源码已具备的语义本次如何使用
GET /api/platform/v1/products/:product/models会话 + model:invoke 产品凭据;核对产品,过滤发布范围、调用状态和有效价格各产品统一读取,不自己维护另一份模型表
POST /api/platform/v1/public/price-estimate按 model_name、expected_version、usage 和价格引擎计算积分;版本变化返回409;适用于有 usage schema 的价格作为已有计价能力保留;不因此增加文本展示任务,也不能代替产品权限、余额或完整生成请求检查
POST /api/platform/v1/products/:product/media/consumption-preview会话 + 产品凭据;从媒体规格/用量预算及付费偏好推导标准积分、钱包支出、权益分配和是否允许图片/视频优先复用,联调真实参数与权益;该预览复用分配器后回滚,不保留资金冻结、不调用模型

源码依据:产品模型过滤、价格估算、媒体消费预览。这些是当前源码能力,本轮没有调用收费接口,也未证明线上授权内预览已经通过。

客户端须区分计费的 usage_schema 和生成参数的 media_generation_profile,它们不是同一份表单协议。模型可用性、支持参数和计价规则来自 Platform;产品只补充自身业务约束。

每次图片/视频生成的预估展示要求:

  1. 根据产品、当前用户/团队付费上下文、模型、输入规模及具体生成参数计算;相同参数在各产品按同一政策得到一致结果,产品不复制费率或换算算法。
  2. 展示预计积分、预计钱包支出/权益扣减及必要的计算假设;如果某项不适用,按正式接口明确表达,不能把未知当零。
  3. 媒体实际时长等计费用量未知时,使用明确的预计用量或区间,不将估算展示成保证结算额;只有服务端能实际执行预算约束时才显示保证上限。价格规则和用量事实分开,最终费用由 Platform 按实际执行与结算契约确定。
  4. 价格版本变化、模型/输入/参数/付费主体变化后重新预估;提交生成时再校验。现有409应触发刷新提示,不以缓存旧报价静默接受新费用。当前预估不能被描述为已承诺锁价或已预占资金。
  5. 预估接口本身不触发生成或收费;真正的预算占用和结算仍沿现有执行/账务链。预估时余额可用不保证提交时仍足够。
  6. 逐项核实图片/视频模型价格类型、生成规格及团队 payer 的覆盖;确认缺口后在现有引擎补正式合同。不把文本请求估算纳入本次新增范围,不重建引擎或恢复已退役的报价路由;现有文本计费及后台价格计算能力保留。

5. Platform 与 Media 的完整资源分工

“完整资源管理”包含资源的准入、创建、归属、使用、计量、引用、读取、释放与删除闭环。产品不各自实现桶管理、容量算法或另一份正式原件。

能力Platform 的职责Media 的职责产品的职责
身份与归属可信用户/团队、产品主体、服务权限及访问资格校验受托主体并保护资产隔离提供业务对象归属并验证对象 ACL
权益/额度商品及既有权益、有效额度政策、付费主体依据政策执行存储准入并记录实际用量展示统一结果,不另算待遇
模型与媒体资源全部适用模型/参数目录、图片/视频生成前费用预估、执行授权、零售费用与结算供应任务、媒体产物及供应侧事实消费目录,图片/视频展示预估,保存业务任务、原操作身份与结果采用
上传/归档授权、归属及政策传递创建上传会话、预留、实际对象校验、封存、版本与用量使用公共接口,保存稳定引用
列表/读取用户与员工访问范围、统一查询入口资产元数据、受限读取能力、读取租约按业务权限展示和读取
跨产品引用身份/团队资格及产品访问边界同一资产版本的 pending/active binding 与引用保护持久保存对象引用并确认/释放
删除/回收删除资格、保留政策及审计关联检查全部引用/租约/保留责任,执行物删与重试删除业务对象不直接删除底层原件
运营管理员工范围、资源政策、审计及聚合查询提供用量、引用、回收和处理状态通过领域命令处理产品对象,不允许跨库直写

业务模型需要明确区分操作人、个人/团队 owner、payer、product、asset/version、业务绑定与政策版本;字段名称和新增合同由提供方开发文档定稿。团队执行时冻结付费账户、素材归属和容量池,恢复不随当前团队切换而改归属,不静默退回个人扣费。当前 EXA 不能未经核实就被当作完整团队付费合同。

5.1 复用现有存储链

本次先正确接入已经存在的 Media assets。当前读取是约 24 小时的 Media 能力 URL,经 Media 处理 GET/HEAD/Range 并转流对象存储;读租约参与删除保护。该实现不等于现网已采用短期 TOS 直签。

稳定 asset/version/file 身份与临时 URL 分开;同一资产可被多个获准产品引用,但共享素材不扩大项目权限。先取得 pending binding,产品事务保存引用及确认待办,再确认绑定;解绑、事务失败与过期 pending 都有持久恢复/回收出口。最后一个业务引用解除也不必立即物删,仍须检查读取租约等责任。

直传、分片、CDN 与桶重新分区按实际性能或成本需求单列,不作为本次统一接入的先决条件。如果后续采用直传,必须同时落实字节预留与实际上传限制、临时对象和封存版本隔离、完成校验、过期分片回收,不能只发一个预签名 URL。

容量政策继续由 Platform 定稿,Media 负责实际 used/reserved 和准入。当前 20 GiB 算法与新运营 1 GB 目标的单位、叠加、团队池和存量超额语义须按对应商业工作包处理;SDK 不硬编码新默认,也不因技术栈统一自动降低已购待遇或删除原件。

6. 请求、执行与恢复的共同标准

  • 调用协议:沿现有 HTTP/JSON、OpenAPI 与具名事件,统一超时、取消、错误、关联 ID 和凭据边界。无实际需求不增设网关、消息总线或协议转换层。
  • 收费执行:产品先保存命令、冻结输入、原请求身份和授权关联;授权未可靠保存时不派发。相同命令不同内容冲突,网络未知先查询原请求,不能自动换身份再次收费。
  • 恢复保证:复用已有文本原单恢复并做授权内联调;媒体首回执丢失后的定位保证单独核实。若供应方没有幂等或查询能力,保留 unknown,不虚构 exactly-once。
  • 结果采用:供应成功、费用结算、文件归档、业务采用分别记录。归档失败只补存;迟到结果按版本及用户采用规则处理,不覆盖新编辑或复活删除对象。
  • 持久收尾:领域状态、回执和必要 outbox 同事务保存,网络调用放事务外;消费去重记录、本域效果及后续待办同事务提交。EXA release、引用确认/释放和项目投影可在失败重启后继续。
  • 工作进程:沿已有任务模型加固租约和并发边界;过期 worker 不可回写,外部副作用仍依赖持久操作身份及接收方幂等。Redis 租约本身不能撤销已经发出的请求。

Drama 已发现的事务内 release、终态释放缺持久重试、取消后原任务收敛问题应直接在本域修复。公共包可提取已证明重复的机制,但不先统一所有产品任务表和工作流。正常任务、恢复、归档的并发预算与大文件内存问题按实际缺口验证处理。

7. 运营与产品重制的关系

运营复用 Platform 身份和已有 Admin/商业接口,各产品提供受限管理查询与领域命令。员工范围和用户消费授权分开;命令带真实操作者、目标范围、原因、原命令身份、预期版本和审计关联。经营投影只读,不能通过重放报表再次发奖、补钱或授予资格。

完整运营功能继续由 PLAT-02-040及其工作包管理,开发边界见 PLAT-04-013。本次提供其统一身份、资源与产品接入基础;新增商品/促销/奖励等功能不打包计为“公共模块抽离”。

Studio/Drama 的既有重制继续在各自仓推进;Commerce 后续按统一栈改造。Go Agent 的具体实现由产品行为与实际复用需求决定,不先要求另造一套公共 Agent 平台。用户明确的无旧 Node/Python 兼容保持有效,迁移时不增加长期旧语言桥接。

8. 本次收敛的可执行清单

用户已授权开始执行,最新优先级为先完成Platform公共接入能力,解除各重构项目阻塞,再推进运营界面。提供方具体代码、契约、客户端和隔离验证任务见PLAT-04-014。可执行配置与调用边界见Go服务统一接入指南。执行授权不代表所有能力、团队主体或线上制品已通过;按具名交付分别记录。

8.1 先分清复用、封装与缺口

分类交付完成依据
已有能力复用固定 Platform/new-api、实际 Media、各产品源码与契约/制品基线;核实 PostgreSQL/Redis 实际配置源码支持、已部署和授权内验收分开标记
公共代码封装统一身份、可用模型、图片/视频费用预估、执行、材料、错误和凭据客户端;抽确有重复的 React 能力Creative/Drama 消费同一发布版本;独立构建,不复制源码
已证实产品缺口Creative 中央身份/执行/素材替换;Drama 持久收尾、统一素材及对象权限接线原有产品行为保留,正向与越权/断连/重启路径通过
已证实提供方差距新 Studio/Drama 项目投影及硬编码路径的正式映射完整身份、项目版本、成员/删除语义可核对,不仅新增产品字符串
待核实合同缺口媒体原请求定位、图片/视频团队费用预估、团队付费/素材归属、跨产品员工委托先验证现有保证,再补具名增量;不把未知自动计成重建
多仓集成固定包版本、提供方行为样例、受影响消费者验证和发布顺序各仓独立上线,协议变更可追溯,无跨域数据库依赖

Platform/new-api 的内部路由、ORM、账务和供应适配按现有结构增量修改。除目标 PostgreSQL 切换确实需要的数据迁移外,不因公共包抽离重构其全部数据库或目录。Media 已有文件、配额、引用实现同样优先复用。

8.2 按责任并行,不按重建平台分工

  1. Platform owner:已有身份与鉴权对外契约、产品/服务范围、必要执行及资源政策增量;不复制已有底层。
  2. Media owner:现行 assets/供应合同、产品映射、实际用量/引用与资源状态;明确真实端点与版本。
  3. 公共包 owner:提供方合同的客户端、错误和凭据策略、生成物、固定版本与消费样例。
  4. 产品 owner:本仓中央接入、对象权限、任务与资源绑定、相应业务回归;Commerce 未来批次独立记录。
  5. 运营 owner:接统一身份、员工范围、资源视图和产品管理接口;新增商业功能沿原工作包。

先固定契约与现有能力,随后公共包与产品接线并行,再验证完整登录/鉴权/执行/资源旅程并按仓发布。共享资金逻辑、正式契约和服务启动迁移由提供方 owner 集成,避免多个任务各加一套实现。

8.3 工程量口径纠正

此前 v0.4 的 250~450 人日不得用于本次排期。 该数字把全产品重构、公共 Agent 引擎、完整商业新增功能和全局退役打包,且未逐项核减现有 new-api/Media 实现;它不是本次技术栈统一和公共接入的预算。由该数字推算的工程月与日历工期同样撤回。

新的估算只按三类真实增量核算:已实现能力的客户端整理;各消费方接线与必要迁移;经过验证确实缺失的服务端合同与实现。每项列当前函数/接口、可复用实现、必要修改、验证和 owner,剔除其他产品/运营工作包已计入的内容。

new-api 已支持 PostgreSQL、Platform/Creative 已有 Redis 接线、统一素材能力已经存在,应明确扣除重复建设工作;实际数据库迁移规模、跨域员工委托及媒体失联恢复等未知量仍要核实。完成这张差距清单前,不用一个更小但同样缺乏依据的人日数字替代旧估算。

9. 验收与迁移边界

验证面本次接入必须证明
技术栈目标环境的 React/Go/PostgreSQL/Redis 版本、实际启用、连接与迁移可核对;源码支持不冒充运行完成
登录与鉴权会话失效、服务凭据撤销、两用户/团队/产品、员工不同范围、直接对象和批量/导出访问均按边界处理
模型与预估可用目录覆盖全部适用模型;图片/视频验证参数/主体变化重估、价格409、未知用量和权益/钱包拆分;预估不产生执行或收费,不新增文本预估展示
执行原命令、授权及请求身份可关联;断连/重复/重启不盲目重派收费请求,不以本地取消推断供应退款
资源上传/归档→稳定版本→引用→读取→解绑→回收完整;重复引用、容量预留、读租约及失败恢复符合权威政策
归属actor、owner、payer、团队容量池不随当前会话/团队切换而改变;不越权共享私有素材
账务调用现有 Platform 权威;产品和 SDK 不另算余额、费用、退款或权益待遇
Redis已有缓存/限流/配额协调及租约的失效和重启按实际合同验证,不以统一栈重写未理解的关键路径
发布独立仓/服务/模块版本与实际制品对应;提供方扩展→包发布→消费者升级→旧契约退役可分步执行

接入测试完成不代表产品全部功能或运营全部商业功能完成;每个工作包分别验收。本次也不能以单个演示请求成功代替上述接入质量标准。

旧数据和原件按具体产品批次确定保留、映射与接收方;没有删除生产数据的隐含授权。切换前停旧系统接新请求,完成排空或按可信原身份交接,核对后切唯一入口;禁止双权威写入。支付/供应迟到回调的责任交给 Go 接收方或明确终结后再撤销旧入口。此类交接不要求维护旧 Node/Python 服务兼容层。

10. 文档和实施状态

本页记录用户已明确的边界与实施路线;用户已授权执行,当前以Platform公共接入为先。具体实现方案仍按任务评审,完成与未完成以07过程记录中的真实代码/测试/制品证据为准;本页不代表生产变更已发布。各项目入口引用同一文档,不复制公共规则正文。

服务接口和具体差距放提供方开发文档,产品接入与语言/数据库重构放本产品工作包;实际进度、测试与制品证据放 07_过程记录。运营已有功能范围继续由其原 PRD/工作包管理,不因本次架构纠偏被取消,也不全部并入本次预算。

On this page