历史 · 交付路线图与决策记录

历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。

OceanWay 不应同时重写所有产品。本路线图同时描述“当前核心链路门禁”和“长期产品能力工作流”，两者不能混为同一条发布时间线：当前工程必须按固定门禁接通最小文本链路；身份、产品与企业能力可以并行设计，但不能越过核心门禁提前建立第二套 Run、账本、资产或模型事实源。

本页继续维护跨产品的长期能力路线和架构决策；已经正式拆出的多仓工作包、仓库依赖和发布证据规范见仓库实施计划。两者的固定关键路径必须一致，仓库页不得自行改变本页的不变量。

当前能力与目标差距

“当前实现基础”包含仓库候选和明确标注的受控验收结果，不等于生产环境、真实上游或商业运营已经正式验收。

当前实施位置：受控准入已验收

• Contracts 0.2.0 已由提交 ce323954 固定发布。
• Core 提交 f9e55b6 的独立 CI Run 33777925718 与 API Edge 提交 f97cf5f 的独立 CI Run 33774539995 均已通过。
• Infrastructure 提交 e72e5f3 固定了 gate 源提交 9cc3c9c，正式证据为 evidence/controlled-admission-e2e-9cc3c9c49b16-f9e55b6e56e4-f97cf5f27027.json。
• 该跨服务证据验证的是固定 Contracts Release、真实 HTTPS JWKS/RS256 Workload JWT、Edge/Core Socket HTTP 与独立 PostgreSQL 下的受控准入：默认关闭、202/reserved、并发同请求收敛、幂等冲突、主要信任边界拒绝、Trace/持久化关联与 Secret 不进入响应或服务日志。事务回滚和更多领域拒绝分支由 Core 自身 PostgreSQL 集成测试覆盖。

当前工程阶段正式进入 Outbox Publisher（Core 组件名为 Dispatcher）与 Ops Explorer。其设计已由 ADR-030 和运维事件与读模型冻结，代码、固定 Contracts Release 与跨进程验收仍待实施。公网继续保持 PUBLIC_ADMISSION_MODE=disabled；Gateway 模型输出、Outbox 正式发布、Metering 和 Settlement 均未完成，因此该验收不能解释为端到端执行链或公开 API 已上线。

当前核心链路的固定实施顺序

该顺序与下一阶段保持一致，是当前实现的发布门禁，不是建议列表：

Media Gateway 正式执行、图片/视频产品迁移、Canvas Runtime、完整 Agent/MCP、Drama、Commerce 与 FDE 均在最小文本链路通过后复用同一骨架扩展。现有 Media Gateway 实现基础可以并行整理，但不能让媒体执行先于 Text Gateway canary 进入 Core，也不能据此绕过 Metering/Settlement 门禁。

并行产品能力工作流

以下 W0–W7 描述长期产品与平台能力的依赖，不替代上面的当前核心实施顺序。某项工作可以并行完成需求、契约或迁移盘点；一旦涉及生产 Writer、客户费用、正式 Run 或 Asset，就必须等待对应核心门禁通过。

管理员与运维不是 W8，也不是业务功能全部完成后再补的大屏。ID、错误、审计和读模型从 W0 开始；独立 Admin Surface 在 W1 建立；统一 Run 后完成只读诊断；告警、Incident 和写命令再按证据逐步开放。

W0：冻结核心契约

在新增组织表和新工作台前完成：

• 统一术语与 ID 规则；
• 冻结 requestId、traceId、correlationId、operationId 和领域稳定 ID 的不同语义；
• Organization、Workspace、共享 Project 外壳；
• Resource Envelope、Revision 与 Relation；
• Run 状态机、Step、Attempt、RunAdmissionManifest 与每次 Attempt 的 AttemptExecutionManifest；
• Gateway Deployment、Execution Route、不可变 ProviderUsageEvidence / ProviderCostEvidence 与 source ref，以及 Metering 独占的规范 MeterEvent / ProviderCostFact；
• OceanWay Execution Attempt ↔ AttemptRouteBinding ↔ GatewayRouteSnapshot ↔ Provider Evidence 契约；同一 Attempt 不换路，Operational Observation 只引用 Binding/Evidence，不生成 Fact 或驱动结算；Provider Task、Supply、Credential Version 和可选 Callback Receipt 保持网关内部私有；
• 统一 Error Envelope、提交确定性、Gateway Diagnostic Observation 和 Telemetry 脱敏契约；
• 冻结 Public API Edge 的 22/43 字符 DeveloperCredential Grammar、强制幂等、apiVersion="v1"、验证快照、工作负载身份，以及 flat 成功/nested 错误契约；
• Billing Account、Meter Event、预算和账本边界；
• 领域事件信封、版本和幂等规则；
• Append-time Delivery Set、Applied Receipt、无标量连续游标的 Projection Progress、Operational Observation 与 Workforce Query Grant 边界；
• 权限 Scope、数据分类、MCP 风险级别；
• ADR 模板和架构 Owner。
• Admin Query 与 Admin Command 边界、Audit 和危险动作职责分离。

退出门禁：核心实体、状态机和不变量经产品、研发、财务与安全共同确认；不得由单个页面实现反向决定平台契约。

W1：统一身份与控制面

• 为现有用户创建个人空间、默认 Workspace 和 Billing Account。
• 引入 Enterprise Organization、Membership、Invitation、Workspace 与 Project。
• 建立统一应用启动器和组织/Workspace/Project 上下文。
• 建立 console.oceanway.tech 客户控制层 Surface，作为应用、上下文、购买、治理和 FDE 私有交付的统一大厅。
• 在 Console 中建立可切换的 Developer 专业空间，复用全局组织上下文但使用独立的开发者任务导航。
• 所有新 API 解析统一 Request Context。
• 资产、任务和钱包页面始终展示所有者、付款方和产物归属。
• 保留当前客户站点登录能力，将 Console 接入同一 Customer Identity，并确定集中 IdP 的演进方案。
• 将 oceanway-vozeb 固定为 OceanWay Studio 基座，停止新增归属 OceanWay Studio Host 的开发者产品能力。
• 将现有 /admin 作为迁移基座映射到 admin.oceanway.tech，建立独立 Workforce Client、Audience 与 Host-only Session。
• 企业客户管理员继续使用客户身份和 Organization 权限，不能换取内部后台 Session。

退出门禁：同一用户可在个人空间与两个企业组织间切换；任何列表、深链接、Run 和账本均无跨组织泄漏。

W2：计费账户与开发者身份

• 把现有“用户积分账户”泛化为 Billing Account。
• 现有个人余额、权益、订单和流水映射到个人 Billing Account。
• 增加 Workspace/Project/Member/Product/Agent/API 预算。
• 引入 Developer App、Environment 和 Service Account。
• 个人用户自动创建 Personal Space、默认 Developer App、development Environment 与受限 Service Account；所有 Key 都作为 Credential 挂在该资源链上。
• 首个 API Edge 受控准入已按固定契约验收：POST /v1/responses 的 Raw Secret 只到 Edge，Edge 从 Core 读取请求级验证快照并本地 constant-time 校验，随后以 apiVersion="v1" 和短期 Workload JWT 调用 Core；Credential ID 是不可变版本身份，轮换创建新 ID 并撤销旧 ID。在真实执行和结算闭环前不开放公网。
• 将公开模型、文档、价格、状态和更新日志迁到 ai.oceanway.tech；将 Apps、Environment、Service Account、Credential、Playground、API 用量、请求日志与 Webhook 迁到 console.oceanway.tech/ai；将机器调用迁到 api.oceanway.tech/v1。
• 在 console.oceanway.tech 完成统一购买中心、订阅授权和产品内升级回跳。

退出门禁：网页与 API 使用同一付款账户但不同认证方式；企业余额不足不会改扣个人余额；成员离职不破坏企业生产 Key。

W3：资源图与统一执行

• 建立 Resource Registry、AssetVersion、Relation 与权限感知索引。
• 为现有媒体、创作资产、Canvas 与生成记录补充 Workspace 所有权和稳定 Revision。
• 将现有 Agent/生成任务映射到统一 Run、Step、Attempt 与 RunOutput。
• 引入 RunAdmissionManifest、AttemptExecutionManifest、AttemptRouteBinding、GatewayRouteSnapshot、Transactional Outbox，以及 Request/Trace/Correlation/Operation 与领域 ID 协同关联。
• 先完成 PostgreSQL Outbox Dispatcher、Append-time Delivery Set、Applied Receipt、版本化 Operations Read Model、低敏 Observation Intake 和只读 Run Explorer；首期不引入外部 Broker，不用全局标量 Position 假装连续水位。
• 先按固定核心门禁完成 Metering/Settlement 与 Text Gateway canary，再登记首个正式 Asset；只有该链路通过后，才接入独立 oceanway-media-gateway，通过不透明 gatewayTaskId 验证提交幂等、原任务查询、冻结 Credential Version、未知状态对账和结果获取。其 Registry、Poller/Reconciler 与未来可选 Callback 均为网关内部模块。
• 建立开发者异步查询、正式 Asset 登记，以及 202/queued 保持预占的闭环；终态按具结算资格的 canonical MeterEvent 计算目标净额，只有 BillingFinalizationDecision 封闭完整 Attempt×Charge Dimension 集合后才结算或释放，ProviderCostFact 不单独触发客户扣款。
• 泛化现有 projectHandoff 为跨产品 Handoff。
• 全局任务中心读取统一 Run 投影。
• 建立只读 Operational Read Model、全局 ID 检索、Run Explorer、Error Fingerprint，以及 Text/Media Pool 独立健康视图。

退出门禁：先证明一次 API 文本 canary 可以从输入版本、模型部署、Run、费用到输出 Asset 完整还原；随后启用媒体时复用同一门禁，证明网页或 API 媒体生成在重放和重试下不会重复扣费或创建结果。

W4：Canvas、Agent 与 MCP 组合

• 从 OceanWay Studio 的无限画布工具中明确抽取共享 Canvas Runtime 契约。
• 建立 Agent、Agent Revision、Deployment 与“运行/查看定义”分离权限。
• 建设 MCP Connector、Connection、Credential、Tool Version、Tool Grant 与 Gateway。
• 建立 Context Package 和显式 Return Binding。
• 为外部发布、调价、删除和财务操作增加审批 Step。
• 允许 OceanWay Agent 以最小权限调用模型和 MCP。

退出门禁：Canvas/Agent 分享不泄露 Secret；撤销 MCP Connection 后新 Run 立即失败；高风险外部写操作可审批、幂等和审计。

W5：漫剧与电商接入

• 漫剧保留 Episode、Scene、Shot、Review 与 Composition 私有聚合。
• 电商保留 Product、SKU、Campaign 与 ChannelPublication 私有聚合。
• 两者只通过 Asset、Canvas Binding、Agent Run、MCP 和 Billing 使用共享内核。
• 建立“在 Canvas 打开”“发送回产品”“发布前审批”和全局任务回跳。
• 明确现有 /drama 向独立漫剧工作台入口的迁移路径；正式名称、Host 和首期部署方式另行确认。

退出门禁：至少完成一条漫剧端到端链路和一条商品内容到渠道草稿链路，刷新、失败、重试、撤权和费用均可验证。

W6：企业与 FDE

• 企业 SSO、SCIM、Managed Identity 与条件访问。
• 企业席位、授信、合同额度、发票和高级预算。
• 数据外发策略、DLP、数据驻留和客户审计出口。
• FDE Engagement、Delivery Workspace、Milestone、Deliverable 与 Acceptance。
• 落实 FDE 双界面：oceanway.tech/fde 与 /cases 负责公开展示，Console 负责授权后的私有交付；console.oceanway.tech/delivery 仅为首期建议路径，最终路由由 FDE 详细设计确认。
• 限时支持访问、交付移交和项目结束清理。
• CaseStudyRelease 的客户批准、脱敏、指标口径与撤回。

退出门禁：企业成员入职/离职、FDE 工程师临时访问、客户生产移交和公开案例发布均完成演练。

W7：开放生态

在内核运行稳定后再考虑：

• OceanWay MCP Server；
• SDK、CLI、Webhook 与事件订阅；
• Agent、Canvas Template 和 Connector 生态；
• 合作伙伴能力包；
• 市场交易与收益分成。

开放市场不是首期目标。没有版本、权限、计量、审核和下架机制前，不应把 Agent 或 MCP 做成公开市场。

横向管理员与运维交付线

这条交付线与业务 Phase 并行推进。完整对象、页面和门禁见管理员平台与运维控制面。

数据演进原则

项目尚未正式上线时，优先直接采用新表和新所有权模型，不为未发布历史写复杂兼容层。需要保留的开发/候选数据按显式映射处理：

企业数据从启用 Organization 后直接写入新模型。任何回填都需要数量、金额、资源哈希、引用和权限核对；账本不得通过“复制最终余额”替代原始可追溯分录。

架构决策记录

每个 ADR 后续应补充背景、候选方案、选择理由、影响、回滚条件和批准人。表中仍标记“本文建议”的事项不能被实现团队当作已经授权的产品决定。

OW-ADR-027 的仓库职责、现有仓库处置、版本化契约、历史保留和 Cutover/Rollback 门禁见 Polyrepo 仓库拓扑与迁移治理。

OW-ADR-028 的首发契约、模块边界、事务范围、禁止双写规则与下一阶段固定顺序——API Edge → Outbox/Ops Explorer → Metering/Settlement → Text Gateway canary → Asset → Console/Studio cutover——见 Contracts First 与 Core 准入纵切。

OW-ADR-029 的 Credential Grammar、不可变 Credential ID 轮换、本地 Digest 验证、短期 Workload JWT、V1 幂等/Fingerprint、publicModelId 解析、Run Input、flat 202/reserved、nested 稳定错误和非公网门禁见 API Edge 受控准入与信任边界。该门禁已经通过，当前工程阶段是 Outbox Publisher 与 Ops Explorer；分布式限流、完整链路追踪与公网压力测试在公开切流前完成，不作为当前受控基线的已完成功能。

OW-ADR-030 的 Owner、PostgreSQL-first Delivery、Append-time Delivery Set、Lease Fencing、Applied Receipt、无标量连续游标的 Projection Rebuild、run.created@2.0、best-effort Observation、Core Authorization Grant 与 Audit fail-closed 边界见 Outbox Dispatcher 与运维读模型。它是已采用的实施文档，不是已经完成的运行能力。

OW-ADR-031 的 Run/Attempt 内容身份、Dispatch Slot、不可逆 Execution Closure、Settlement Input、三组 Validation Bundle、Billing 本地原子终局、严格经济身份和迟到补结边界见 执行、计量与账务终局协议。它是后续 Metering/Settlement 阶段的正式目标契约，不改变当前仍停留在 Outbox/Ops 实施阶段的事实。

当前门禁与后续待决策

当前 Outbox/Ops 门禁没有等待产品 P0 决策。以下边界已经冻结，不再作为开放问题：

• Project 是共享业务目标外壳，完整剧集、商品、Canvas 等内容仍由产品私有聚合拥有，并通过 Binding 关联；
• 每个 Personal Space 或 Organization 只有一个 Billing Account；Workspace、Project、成员、Agent 和 Service Account 使用预算约束，企业合同额度进入同一账户的资金或权益来源，不允许执行中切换付款账户；
• Provider 提交状态使用显式 not_submitted / submitted / provider_accepted / unknown 等事实；unknown 保留原任务并进入查询/诊断或 Incident，不翻译为失败、成功、零费用或未定义的 Reconciliation Case；
• 用户取消意图与 Provider 已取消是不同事实。Media Gateway 首期不以 Cancel 为进入门禁；只有 Adapter 声明并能返回可验证结果时，后续才按 Capability 暴露 Provider Cancel。Callback 同样是后续按需能力。

下列选择只需在对应产品或治理能力进入实现前确认，不得阻塞当前 Outbox/Ops → Metering/Settlement → Text Gateway canary 顺序：

1. 用户端长期使用“积分”还是引入多币种/额度展示；会计账本与产品余额如何命名。
2. 跨 Workspace 支持授权引用、复制、转让中的哪些能力，首期默认是什么。
3. Prompt、Knowledge、Agent Memory 是否作为 Asset 类型，还是独立资源域。
4. MCP 写工具的审批默认值和企业可配置范围。
5. 用户注销、企业法定留存、账本不可变与 Legal Hold 的优先规则。

新产品接入前还需确认：

• 漫剧独立入口和现有 /drama 的迁移方式；
• Console 首期在应用大厅与购买中心之外，同步上线资产总览、任务中心和企业成员管理中的哪些模块；
• 旧 ai.oceanway.tech/v1、OceanWay Studio Host /v1 与开发者页面的关闭方式及兼容窗口；
• API 媒体结果是否默认登记 Asset；
• 模型下线时已发布 Agent/Canvas 的替代策略；
• FDE 交付 IP、Agent、Prompt 和 Connector 的标准合同口径；
• 公共案例审批、指标证明和撤回机制。

内部运维上线前还需由组织与安全负责人确定：

• Workforce IdP、生产访问网络和设备策略；
• 值班 Owner、Incident Severity、升级与客户沟通责任；
• Telemetry 后端、采样、保留、数据区域和 Legal Hold 策略；
• 生产路由、敏感调试和财务处置的审批矩阵。

非功能目标

可用性、延迟、吞吐、租户公平性、RPO、RTO、数据驻留和成本告警必须在真实容量与合同级别确定，不能用无依据常数代替设计。首轮至少建立以下可测指标：

• 登录与组织切换成功率；
• 权限拒绝正确率与跨租户测试覆盖；
• Run 创建、排队、成功、取消和未知状态比例；
• Provider 成功率、延迟、费用与故障切换；
• Text/Media Pool 独立 SLO、Alert 和 Incident 时间线完整性；
• Reservation 未结算时长和对账积压；
• Asset 落盘、引用完整性和删除阻塞；
• MCP 调用、审批、失败与外部副作用；
• Workspace/Project/产品维度成本；
• Outbox、Gateway Observation、Telemetry 与运维读模型摄取新鲜度；
• 备份恢复与凭据撤销演练结果。

架构验收场景

发布一个阶段前至少覆盖：

1. 个人用户加入企业后，个人与企业资产、钱包和 MCP 完全隔离。
2. 企业成员只访问一个 Workspace，并受 Project 预算限制。
3. Service Account 通过 API 生成媒体，登记 Asset 并在 Canvas 继续编辑。
4. OceanWay Studio 的 /canvas 只返回候选 AssetVersion / CanvasRevision，由漫剧领域确认写入 Shot；失败不会覆盖原版本。
5. 电商 Agent 调用 MCP 创建渠道草稿，发布动作需要审批。
6. 成员离职后 Session、Run Token、个人 Connection 立即失效，企业资产和生产 Service Account 保留。
7. 上游超时、重复轮询或未来重复回调、Worker 重启和用户刷新不重复扣费或外部发布。
8. FDE 客户只在 Console 访问获授权的私有 Engagement；交付物经授权、脱敏并创建独立 CaseStudyRelease 后才能进入公共案例。
9. 客户提供一个 Public Request ID，值班人员可以在授权范围内还原 Run、Gateway、Asset 与 Billing 链，无法观测处明确显示未知。
10. Provider 提交状态未知时不能盲目重试；保留同一任务并执行查询/结果恢复，账务只有满足 late_settlement_dimension | billing_finalization_run 契约时才进入正式 Reconciliation Case。
11. 未获得 JIT Grant 的客服不能查看客户 Prompt、媒体、Secret 或执行生产命令。
12. 一个 Pool 或 Provider 故障不会把整个 OceanWay 标成不可用，恢复后能够扫描受影响任务、资产、账务和 Webhook。
13. API Edge 只在请求生命周期持有 Raw Developer Secret，通过 Core 验证快照本地校验；Core、日志、Trace、错误和业务记录均不能恢复完整 Key。Credential 轮换创建新不可变 ID 并撤销旧 ID，旧 ID 不能通过原地修改验证材料重新启用。

非目标

现阶段不做：

• 为了“未来扩展”立即拆成大量微服务；
• 用一个万能 JSON 表承载所有产品；
• 允许产品直接读写其他领域数据库；
• 把每个预算做成独立钱包；
• 让网页、API 与内部模型共享未过滤列表；
• 自动跨组织复制资产或切换付款方；
• 在没有审批和治理前开放 Agent/MCP 市场；
• 为未上线旧数据建立长期兼容层。
• 让企业客户管理员进入 OceanWay 内部 Admin Host；
• 让控制面直连 Gateway 数据库、直接改 Ledger 或用 Logs/Trace 推断业务终态；
• 在关联、确定性、幂等、权限和审计尚未完成前建设通用“一键修复”。

文档治理

• 架构总览记录稳定原则，实施细节进入对应领域文档。
• 任何 P0 决策改变后同步 ADR、数据模型、API 和验收场景。
• 当前实现与目标态分开描述，候选测试不能写成生产事实。
• 发生重复架构争议时，先补充 ADR，再写代码。
• 每个新产品接入时补充自己的聚合根、共享引用、Run、账务和删除矩阵。