历史 · oceanway-infrastructure 实施计划
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
仓库：Oceanway-AI/oceanway-infrastructure。业务负责人和最终验收人：用户本人；本会话统筹，Infrastructure 模块承担环境与组合验证责任。遵循统一实施流程和本地协调，先形成工作包、依赖、Owned Paths 与验收，不以 GitHub 为必需开工入口。
目标与当前基线
Infrastructure 负责环境声明、IaC、DNS/TLS、网络、Workload Identity、Secret 引用、数据基础设施配置、可观测、发布/回滚、灾备和跨仓 Evidence Manifest。应用仓提供不可变制品与运行契约，Infrastructure 不复制应用业务源码，不修改业务事实。
设计源码已移交既有 Oceanway-design。品牌、token、共享组件、平台视觉规范和组件实验室均归 Design；Infrastructure 只承担其制品托管、环境、发布和工程治理。既有提取历史保留，但不继续在 Infrastructure 开发 design-system/。
已记录受控 API Admission 的真实 HTTPS JWKS、RS256 JWT、loopback HTTP 与临时 PostgreSQL 联调。B1 身份/网络包有 1,215 个静态矩阵和隔离 K3s 的 22 条前置对照、3 允许/19 拒绝证据；数据库包有 PostgreSQL 休眠角色权限验证。它们不是正式 B1 运行环境、业务角色激活或最终 Evidence Manifest。Contracts 0.3.0 已发布，运行时消费者与 P5 接收仍是独立门禁。固定历史证据见 B1 交付控制页。
本轮先盘点并统一需求、技术设计和原型，不改变集群、凭据、服务器、数据库角色或生产流量，也不重跑已有部署任务。
需求确定
| 需求面 | 需要确认的内容 | 首轮交付 |
|---|---|---|
| 环境与服务 | 本地/测试/生产、域名、进程、依赖、资源和数据分类 | 服务与环境矩阵；现状、目标、缺口分别标记 |
| 身份与网络 | 调用者/接收者、Principal、Audience/Scope、端口、允许/拒绝方向 | 身份与网络矩阵、Secret 引用需求；不写明文值 |
| 数据基础设施 | Owner/Migrator/运行/Retention 角色、存储生命周期、备份恢复 | 最小权限和恢复需求；业务 SQL 由应用 Owner 提供 |
| 制品与发布 | Commit、构建来源、镜像摘要、SBOM/签名、migration、健康与回滚 | 运行输入清单和发布/切流步骤 |
| 可观测与故障 | 各路径健康、容量/SLO、失败分类、告警、排空与恢复 | 场景表、指标语义、Runbook 目录 |
| 本地治理与联调 | 模块责任、工作树、证据生成、依赖固定和独立审查 | 本地协作与证据要求；远端 CI 是后续证据渠道 |
每项需求写明系统边界、验收方法和前置输入。所有模块业务负责人同为用户；Core、Admin、Edge、Gateway 等名称表示接口提供责任，不能因同一负责人而消除身份、数据或工作区隔离。
技术设计与无 UI 原型
Infrastructure 无独立客户 UI 要求。首轮用可阅读的拓扑、时序和配置 fixture 代替运维后台页面，用户能检查允许路径、禁止路径、发布顺序、失败结果和恢复动作即可。需要实际运维查询/操作页面时由 Admin 承担产品设计，本仓提供运行契约与证据。
| 原型 | 必须覆盖 | 验收点 |
|---|---|---|
| 环境/进程拓扑 | Core API、Operations Worker、Admin BFF、Edge、网关与数据依赖 | 每条边有方向、身份、端口、环境和开放状态 |
| 身份/请求时序 | Exchange/Query/Observation、过期、撤销、跨身份重放 | 合成状态与真实 runtime 差距显式可见 |
| 配置 fixture | 镜像/包摘要占位、Secret Reference、网络和角色映射 | 只含演示/非秘密值；未接收字段标待确认，不冒充生产配置 |
| 发布/回滚演练稿 | migration、发布、启用、暂停 Claim、排空、回滚 | 停止条件、在途责任、失败恢复和证据各自明确 |
| 故障与证据样板 | 网络/数据库不可用、响应丢失、旧 Lease、审计失败 | Expected/Observed/未验证区分；无真实运行时不填 pass |
原型阶段可进行文本/静态 fixture 检查，不启动服务或连接目标环境。用户确认需求与设计后，才将原型拆成运行配置、脚本和集成工作。
工具接口与 API 文档
本仓后台工作是 IaC、配置、CLI、校验器和联调编排，无需求时不新增 HTTP API 或业务数据库。
| 接口类型 | 设计内容 | 规范责任 |
|---|---|---|
| 应用运行输入 | 进程、listener/route、健康/排空、环境字段、资源、Secret Reference、迁移输入 | 应用提供真实运行契约，Infrastructure 映射环境，不猜测端口或字段 |
| 身份与网络配置 | 精确调用方向、授权、DNS/TLS、CNI 与数据出口 | Infrastructure 配置环境；跨仓身份语义来自 Contracts |
| 发布/验证 CLI | 参数、输入输出、退出码、dry-run、超时、清理和回滚 | 本仓维护；危险动作与只读检查分离 |
| Evidence / Telemetry | 版本、来源摘要、场景、结果、限制、脱敏与保留 | 业务事件来自 Contracts；环境与交付记录由 Infrastructure 拥有 |
工具/API 文档必须包含前置输入、调用示例、成功与拒绝示例、错误/退出码、版本、可重复性、清理失败处理和证据范围。Docs 解释调用与维护流程，Contracts 固定跨仓 Service/Event schema；本仓不复制 DTO 或手写第二套错误标准。
分阶段实施
| 阶段 | 交付物 | 退出条件 |
|---|---|---|
| 需求确定 | 服务/环境/身份/数据/故障/发布需求矩阵 | 用户确认范围、现状缺口与验收方法 |
| 技术设计 | 边界、部署拓扑、凭据生命周期、网络/角色策略、发布与恢复方案 | 与应用运行输入、Contracts 和唯一 Writer 一致 |
| 原型 | 拓扑/时序、配置 fixture、演练与证据样板 | 用户能逐场景审查；本轮到此收口 |
| 后台/工具 API 设计 | CLI/配置 schema、运行接口映射、校验与失败行为 | 真实应用输入已固定；无未确认开放路径 |
| API 与运行文档 | 接口/配置说明、版本错误示例、操作及回滚手册 | 与固定制品一致，可生成检查项 |
| 实现与联调 | 环境配置、脚本、真实隔离验证、组合测试 | 所有上游接收完成，场景与证据对应 |
| 验收与发布 | 独立审查、用户验收、目标环境证据、不可变 Manifest | 高风险项完成所需专业复核，发布和切流分别获准 |
后续运行实现保留既有顺序：B1 身份/网络 → 数据库能力与角色 → Core Worker/Admin Query 运行路径 → Metrics/Runbook → 故障注入与 B1 Manifest；随后才进入 B2 执行终局、Text Gateway canary、正式 Asset 与产品逐命令切换。首轮需求/设计/原型可横向并行，不能据此提前启动正式 Writer。
运行门禁与验收
- Customer、Workforce 与 Workload 凭据不可互换；应用没有平台管理员权限。
- Admin 不直连数据库/网关，Surface 不直连 Gateway，Gateway 无 Core 客户业务表权限。
- 数据库只放行应用 Owner 已定义的 View/Primitive/列能力；接口缺失时保留关闭，不能以 Owner 或全表授权补齐。
- Secret 只存受控引用；目标环境映射、轮换/撤销与 reload 必须由真实消费者证明。
- 固定 Contracts、应用 Commit/Workflow/Image Digest、migration、环境和场景结果；合成 probe、单元测试、隔离组合与生产证据分层记录。
- 验证重复/冲突、跨租户拒绝、响应丢失、旧 Lease、Shadow/Cutover/Rollback、日志脱敏和恢复；缺少运行时不能以健康占位响应验收。
部署、migration 和流量/角色启用分别记录。回滚先停止新流量或 Claim，明确在途 Operation 责任，再恢复已验证制品；已写业务事实由业务 Owner 前向恢复，Infrastructure 不删除 Ledger/Event/Asset/Provider Task。详见验收、发布与回滚。