历史 · oceanway-media-gateway 实施计划
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
仓库：Oceanway-AI/oceanway-media-gateway。当前仓库提供独立方案文档，尚不能据此认定服务代码或运行链路已经实现；正式 Core 接入排在 Text Gateway 最小链路之后。
目标结果与当前基线
目标 Media Gateway 是图片/视频 Provider 直连的单一服务边界。Task/Attempt Registry、Dispatcher、Adapter、Poller、Reconciler、结果处理与可选 Callback 都是同一服务内模块，不继续拆仓。
它与 Text Gateway 同级，不经过 new-api 级联，也不承担 OceanWay Developer Platform 或客户控制面的任何职责。
现有 README/产品/API/开发计划中仍含客户用户、API Key、模型广场等旧设计，与本页私有 Gateway 目标存在冲突。首轮逐项登记保留、改写、移出或废弃；本页没有声称这些旧文档已经修改，也不将计划中的模块视为现成实现。
明确不提供
- 本地客户用户、Customer Group、Customer Session 或 DeveloperCredential；
- 客户 API Key、模型广场、Surface Offering、用户售价、订阅或钱包；
- OceanWay 产品 Run、规范 MeterEvent/ProviderCostFact、正式 Asset 或产品项目；
- 面向浏览器的 Provider Secret、Channel/Supply 和原始 Payload；
- 绕过 Core 的 Studio、Drama、Commerce 或 API Edge 接口。
本轮全流程：先收敛需求、私有服务设计与原型
Owner：本人，负责旧方案取舍、需求、设计、原型、后台 API、文档与验收；当前入口为本机工作台，完整产物按实施工作流组织。首轮以可验证方案为目标，不照旧计划直接建设客户用户和 Key 系统。
消费者需求与待决策项
| 场景 | 首轮需求输出 | 待决定项 |
|---|---|---|
| Core 发起图片或视频 Attempt | 输入能力、长任务反馈、结果和失败含义 | 首个图片/视频 Provider，首批能力，同步/异步对 Core 的表达 |
| Execution 处理在途/取消/未知任务 | 提交、查询、Callback 与取消的用户可见时序 | 各 Provider 是否有真实取消/幂等/查询保证，不以通用接口名称代替保证 |
| Metering/Asset 消费 | Usage/Cost Evidence、结果 Ref、多结果关系 | 证据缺失语义、结果访问时效、抓取/存储责任和生命周期 |
| 运维与迁移 | 健康、排队、容量、在途任务处理 | 旧方案哪些功能保留/移出/废弃，是否需要独立私有运维 UI |
把参考文档中的“计划能力”与当前代码/运行证据分开。Studio/Drama 等产品先向 Core 提需求，不直接成为网关客户；先确定最小媒体闭环，再扩展首尾帧、多结果及长视频。
服务、数据、状态与权限设计
画 Core→Task/Attempt Registry→Dispatcher/Adapter→Poller/Callback/Reconciler→Evidence/结果引用的时序和状态机。列每个模块的读写事实、锁/CAS、重放键、终态来源、提交未知和取消竞态；Poller 与 Callback 不能拥有独立终局。
设计中同时明确输入素材授权、Provider Credential Version、签名 URL 生命周期、结果完整性和过期行为。原始 Payload/媒体不进入事件或普通日志；正式 Asset 由 Core 登记。Workload 调用、Evidence 读取、结果读取和私有运维分别列权限，尚无批准配置时保留待定值。
错误矩阵区分能力不支持、输入不合法、明确未提交、未知提交、上游处理中、确定失败、结果不可取和内部冲突；Usage/Cost 不得用零值表示未知。此处是设计清单，不声明状态名已经成为正式 wire enum。
无付费原型与首轮验收
构造 Provider stub 与合成素材元数据，运行异步任务时序：正常完成、提交响应丢失、重复 Poll、Callback 乱序、取消与完成竞争、多结果及结果过期。原型输出调用/状态日志、消费者结果、Evidence 与不透明 Ref 的关系；不保存生产素材或签名 URL。
首轮交付状态图、能力矩阵、错误/权限表、可运行 fixture 和旧设计取舍表。验证一个 Attempt/冻结路由的规则及状态可解释性；只有源文档或原型不算已有 Dispatcher/Adapter/存储实现。若选择做运维 UI，再依据已确认职责制作只读任务诊断原型，避免重复 Admin 的客户控制面。
接口能力清单与文档方案
| 能力条目 | 文档设计范围 |
|---|---|
| Attempt 提交/状态/重放 | Core 内部 Gateway API，列确定性、幂等坐标、任务版本和结果引用 |
| 查询/取消/Callback | 按 Provider 能力明确支持/不支持；方法/路径和认证由实际设计登记，不提前承诺 |
| Binding/Availability/Evidence 读取与验证 | 固定引用、摘要、权限、缺失状态、Usage 与 Cost 分离 |
| 素材及结果授权读 | Ref、到期/撤销、失败语义和读取责任；不暴露存储内部键 |
| 运维/健康 | 最小范围与权限先设计，不能沿用旧客户管理 API 作为目标 |
本人维护媒体仓的 HTTP OpenAPI、adapter 能力矩阵、字段/错误说明和版本化示例；跨仓 Schema 只消费固定 Contracts 及其生成 JSON Schema。接口条目必须标 Owner、实现状态、API/包/Provider 版本、身份/权限、状态码、错误、分页/幂等适用性及成功/未知/失败示例。现有 PUBLIC_API.md/ADMIN_API.md 先作为待对齐来源，不将其中旧路径直接发布为新平台承诺。
后台实现切片与验证
- 冻结需求取舍和无付费原型，再建立最小服务/配置/数据库/测试骨架；不先实现旧客户控制面。
- 固定契约资格后实现 Workload 边界、Attempt/Dispatch Slot/Binding 和 Task 状态持久化。
- 只实现首个 Provider Adapter，组合 Dispatcher/Poller/Reconciler；Callback/取消按能力矩阵选择，不能伪造支持。
- 接入 Evidence、结果处理和受权读取；多结果不丢弃，正式 Asset 留给 Core。
- 真实数据库/独立进程验证租约、CAS、重复请求、乱序 Callback、取消竞态及重启恢复；stub 用于可重复故障，不代替真实 Provider 能力证据。
- Text 最小链路与计量账务终局条件齐备后，按已确认范围做媒体 canary；登记固定镜像、版本、在途任务和唯一 Writer。回滚恢复服务版本而不伪造或删除已发生的 Provider 事实。
需求、设计和本机 fixture 现在即可推进；生产固定包消费、真实付费调用和环境发布分别记录完成条件，不从首轮原型验收推导上线。
仓库里程碑
- MEDIA-1 代码与数据盘点：冻结现有模块、Provider Adapter、Task 状态、数据库、对象存储、Secret 与部署来源。
- MEDIA-2 私有服务边界：删除/关闭本地用户、客户 Key、模型市场和用户价格；只接受 Workload Identity。
- MEDIA-3 统一 Gateway Contract：实现与 Text Gateway 同级的 Attempt、Dispatch Slot、Binding、Route、Availability 与错误语义。
- MEDIA-4 Provider Adapter：为每个 Provider 明确提交确定性、幂等、查询、取消、Callback 和结果获取能力。
- MEDIA-5 Evidence 与结果引用：保存不可变 Usage/Cost Evidence、Provider Task/Result Ref 和安全媒体获取边界。
- MEDIA-6 首个媒体 Canary：在 B5 接入一个图片或视频路径，再扩展多结果、首尾帧和长任务能力。
内部状态机原则
- 一个 Core Attempt 只对应一个冻结的 Gateway Invocation/Task/Route。
- Poller、Callback 和 Reconciler 竞争时使用同一版本/CAS 规则，不能各自产生不同终态。
- Unknown Submission 保留原 Task 并查询；只有可证明无 Provider Side Effect 才能 Terminal Reject。
- Provider 返回多份成功结果时全部保留；正式 Asset 由 Core Asset 模块登记。
- 上游临时错误不写确定性 Conflict Fact；确定性 Repository/摘要冲突按 Gateway Owner Contract 隔离。
验收与切换
- 每个 Adapter 都有提交响应丢失、重复 Poll、Callback 乱序、取消竞态、凭据轮换和结果重复的测试。
- 原始媒体和签名 URL 不进入事件/普通日志；跨服务只使用不透明 Ref 与短期授权读取。
- Usage 与 Cost Evidence 分离，缺失/不可得/不适用状态显式表达，不用零值代替。
- 迁移期只有一个 Provider Task Writer；旧 Worktree/部署在 Remote、镜像和在途任务可恢复前不清理。
- Media 接入不能提前于 Metering/Billing 终局，也不能复用文本 Canary 的验收声明。
详细拓扑与授权读链见调度、执行与模型网关池。