历史档案文档总体与平台实施计划
历史 · 跨仓依赖矩阵
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
运行跨仓依赖采用版本化契约、受控服务调用和不可变制品。文档/原型协调可以在本机交换路径、文件和测试报告，见本机协调；这不授权运行代码跨仓导入源码、复制 DTO 或跨库写入。设计草稿可先评审，正式消费再固定版本。
依赖类型
| 类型 | 合法载体 | 版本要求 | 示例 |
|---|---|---|---|
| Contract | oceanway-contracts Package、OpenAPI、JSON Schema、事件 Schema | 固定版本或制品摘要 | Core 与 Gateway 共同使用 Attempt Contract |
| Runtime | HTTPS/内部 RPC/队列事件，带 Workload 身份与 Audience | 接口主版本固定 | API Edge 调用 Core Admission |
| Artifact | Image Digest、SBOM、签名、Migration Bundle、证据文件 | 不可变 Digest | Infrastructure 部署 Core 镜像 |
| Documentation | 计划、决定、原型、报告，正式记录引用 Release/Commit | 本地草稿标版本，正式证据固定来源 | 本机工作台引用各仓原型 |
| Design | Design 的规范、组件、token 与包 | 原型标来源；正式消费固定已发布版本 | 产品采用 Design 组件 |
仓库依赖矩阵
| 仓库 | 允许依赖 | 主要输出 | 不允许依赖 |
|---|---|---|---|
| Site | Public Read API、公开目录契约 | 公共品牌 Surface | Customer Session、Core DB、Gateway |
| Developer Center（历史） | 无新增运行时依赖 | 迁移来源与归档证据 | 新功能、独立部署、客户或公开内容双写 |
| Console | Public Catalog/Pricing/Docs Contract、Customer BFF Contract | 公开 Developer Surface 与客户控制体验 | Core/Gateway DB、Workforce Session |
| Studio | Product Contract、Asset/Run/Canvas 引用 | Studio 私有聚合与命令 | Developer 私有控制面、Provider Credential |
| Drama | Product/Asset/Run/Agent Contract | Drama 私有聚合 | 共享钱包或 Asset 第二事实源 |
| Commerce | Product/Asset/Run/MCP Contract | Commerce 私有聚合 | 共享钱包或 Channel Secret 第二事实源 |
| Admin | Workforce Query/Command Contract | BFF/UI 与 Host-only Session | Operations DB、客户 Session、直接改表 |
| Contracts | 无运行仓源码依赖 | 版本化 Schema 与生成制品 | 领域实现和环境 Secret |
| Core | Contracts、Gateway Service Contract | 共享领域事实、事件、私有 Query | 产品仓源码、Provider 私有协议 |
| API Edge | Public/Internal API Contract、Core Runtime | 公网协议终止与低敏 Observation | 业务持久化、Gateway、Provider |
| Text Gateway | Gateway Contract、Provider API | 文本执行与不可变 Evidence | 客户、售价、钱包、正式 Asset |
| Media Gateway | Gateway Contract、Provider API | 媒体执行与不可变 Evidence | 客户、售价、钱包、产品 Run |
| Design | 接受的品牌来源与组件许可证 | 品牌/token/UI/组件实验室及规范 | 产品 Session、钱包、业务事实 |
| Docs | Contracts Release、Design 规范与发布元数据 | 文档站与实施说明 | 运行数据库和客户数据 |
| Infrastructure | 各仓不可变发布制品 | 环境、网络、部署与证据 | 应用源码耦合、明文 Secret 入库 |
产品与 Admin 可消费 Design 已发布的固定制品；当前共享包尚未发布，原型引用不能标为正式包接入。
当前关键依赖
图中的 Infrastructure 箭头表示部署不可变制品，不表示 Infrastructure 成为应用代码依赖；Docs 箭头表示引用固定制品，不表示读取运行时数据库。
Contract 变更门禁
一次跨仓协议变更必须按下列顺序：
- Owner 在架构或 ADR 中说明语义与不变量。
- Contracts 增加新版本、Canonical Golden、JSON Schema 与负向夹具。
- 发布唯一制品，并证明 Registry 与 Release 内容一致。
- 生产者兼容新版本但不切换唯一 Writer。
- 消费者固定依赖并通过 Contract Test。
- Infrastructure 完成目标环境与身份授权。
- 在同一门禁切换生产者版本或流量。
- 观察完成后才下线旧版本。
严格对象增加字段同样可能是不兼容变化，不能因为字段是 Optional 就自动使用 minor 版本。
禁止边
- Surface、产品或 Admin 仓导入 Core 源码或直连 Core 数据库。
- Core 导入 Console、Studio、Drama、Commerce 或 Admin 源码。
- API Edge 或产品仓绕过 Core 调用 Text/Media Gateway。
- Gateway 读取客户、Wallet、Developer Access、产品 Run 或正式 Asset 表。
- 任一仓通过 Git submodule、本地父目录、分支 URL 或复制粘贴维持协议同步。
- Infrastructure 通过 SQL 修复业务事实，或保存可以直接使用的明文 Secret。
发现非法依赖时先停止新能力接入，明确 Owner 与迁移路径；不能用“临时兼容层”把第二事实源永久化。