历史 · oceanway-docs 实施计划
重构前档案，仅供追溯，不作为新版本执行指令
历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。
仓库：Oceanway-AI/oceanway-docs。站点：docs.oceanway.site。业务负责人和最终验收人：用户本人；本会话统筹，Docs 模块承担内容与站点责任。按本地协调先形成可审查工作包，不以创建 GitHub Issue 作为开工条件。
目标与已有基础
Docs 帮助读者理解 OceanWay 的产品使用、平台边界、接口调用、开发接入和运行维护，并能区分已提供能力与未来计划。它是文档站与实施记录，不是运行配置、客户数据库或第二套项目管理系统。
已有独立 Git、Next.js/Fumadocs、搜索 Route Handler、镜像构建和自动发布流水线。既有架构、实施、进度和运行手册是盘点输入；目录完整不等于内容已反映最新实现。本轮补计划、校正权属并设计原型，不触发部署。品牌、token、组件和详细平台设计规范由 Design 维护，Docs 保存架构关系、引用和消费者接入说明。
需求确定
先完成下表的读者任务与内容清单，每项标注本轮必需、后续或不做，并由用户确认首批范围。
| 读者/任务 | 应获得的结果 | 首批需要确定 |
|---|---|---|
| 产品使用者 | 找到对应平台的操作流程和能力限制 | 平台入口、术语、快速开始、常见问题 |
| API 开发者 | 从授权和请求示例走到结果、错误与排查 | Public API、SDK 示例、版本、模型可用范围 |
| 产品/BFF 实现者 | 知道页面数据从哪里来、调用谁、如何处理状态 | 产品 BFF、Core 依赖、请求关联和失败反馈 |
| 服务实现者 | 找到内部服务、事件和固定契约版本 | Workload 身份、操作/事件、幂等与兼容性 |
| 本地统筹与运行维护 | 对照需求、设计、原型、实现和证据判断下一步 | 实施计划、决策记录、Runbook、验收索引 |
需求交付包括文档清单、内容缺口、读者路径、权属矩阵、信息公开范围与可检验验收项。内部接口说明必须先分类可公开内容和受控资料；公开站点不放 Secret、内部接入凭据或客户正文。
信息架构与页面设计
| 内容分区 | 内容责任 | 与其他事实源的关系 |
|---|---|---|
| 产品与快速开始 | 使用任务、能力说明、限制、示例路径 | 与各产品已接收需求及实际能力对应 |
| Architecture | 领域边界、调用关系、不变量、ADR | 解释系统，引用 Contracts 与 Design，不重写契约或设计标准 |
| API Reference | 公开 API、产品 BFF、内部服务与事件、版本与错误 | 规范来自固定 Contracts；Docs 负责可读说明和导航 |
| Implementation | 总体和各平台分阶段计划、依赖、验收 | 关联本地工作包与已确认决策 |
| Operations | 环境说明、发布/回滚、排障与证据索引 | 引用 Infrastructure 固定制品和应用运行契约 |
| Progress | 已确认、已实现、已验证与待完成的差异 | 验收记录更新状态，不能只靠 PR 标题推断上线 |
设计交付包含导航树、内容模板、搜索/版本提示、响应式版式和权限分类。保留 Fumadocs 的阅读、目录与搜索能力；不为统一视觉替换成熟文档框架。
原型与第一轮验收
首轮制作可本地查看的文档导航和页面样板，覆盖“选平台 → 快速开始 → 接口详情 → 失败排查”和“找实施计划 → 查看依赖 → 阅读验收证据”两条路径。接口名称及数据尚未冻结时明确标记示例，不伪造已可调用的 endpoint。
原型至少包含文档首页、平台目录、API 详情、错误/版本说明、搜索结果、空结果、失效链接提示、窄屏导航和浅深主题。用户确认信息层次、术语、主路径及可读性后，才安排 API 文档生成和站点改造。此阶段只完成样板，不运行实际产品请求。
API 文档信息架构
| API 文档类别 | 必须说明 | 边界 |
|---|---|---|
| 公开 API | Host/版本、开发者授权、操作、请求/响应、分页、幂等、流式/异步、错误与限制 | 面向开发者；是否开放与是否有规范分别标记 |
| 各产品 BFF | 对应平台和页面、Session、输入输出、状态转换、Core 映射与失败反馈 | 不把 BFF 写成通用 Public API；不创建第二业务 Writer |
| 内部 Service API | 调用者/接收者、Workload/Audience/Scope、路由/方法、超时、重试、幂等和错误 | 可公开描述不等于可公开访问；环境地址和凭据不进入示例 |
| Event / Observation | Producer/Consumer、schema 版本、字段、关联标识、顺序/重复/重放、确认与兼容 | 与同步请求接口分开；不承诺规范之外的投递语义 |
| 版本与迁移 | Contracts 版本/摘要、服务接收版本、兼容矩阵、变更/弃用和迁移步骤 | 区分草案、已发布、消费者已接收、当前部署 |
| 错误与完整示例 | 成功、校验失败、未授权/无权限、冲突、限流、上游失败、异步处理中及未知状态 | 错误码来自规范；示例脱敏且可校验，不编造服务支持 |
每个接口页使用统一模板：用途与所属平台、实现状态、来源版本/摘要、调用边界、输入/输出、成功与错误示例、相关时序、兼容限制、验证证据和相关页面。可复用的 OpenAPI/JSON Schema/事件结构只在 oceanway-contracts 维护；Docs 从固定版本生成或引用，不维护第二套 DTO、错误枚举或 schema。
BFF 仅属于单仓实现时，由该产品保存自己的接口定义；一旦成为跨仓共享对象，先进入 Contracts。Docs 都负责解释，并清楚注明规范来源。尚未落地的 API 只进入设计样板，不标记可用。
后台、工具接口与实现阶段
Docs 没有额外业务后台需求。继续使用已有内容构建、搜索 Route Handler 与站点流水线；只有确认的阅读体验确实需要时才扩展站点能力。契约导入、示例校验、链接检查、版本索引属于构建工具，优先脚本或现有流程，不另建文档业务数据库或管理 API。
| 阶段 | 交付物 | 进入下一阶段的条件 |
|---|---|---|
| 需求确定 | 读者任务、范围、文档清单、公开/受控分类 | 用户确认首批内容和验收项 |
| 产品设计 | 信息架构、模板、导航、搜索和版本体验 | 与各平台需求、Design 和 Contracts 权属一致 |
| 交互原型 | 主阅读路径、接口详情、错误/空态与窄屏样板 | 用户确认页面与内容组织；本轮到此收口 |
| 后台/工具 API 设计 | 现有站点接口清单、契约导入与校验输入输出 | 需求成立；不增加无必要的服务 |
| API 文档 | 固定来源的 API/Event Reference、示例和迁移说明 | 对应规范已固定，示例可验证，公开分类通过 |
| 实现与联调 | 文档内容、生成/校验工具、站点改造 | 定向检查、链接/搜索和本地浏览器流程通过 |
| 验收与发布 | 用户验收、构建和发布证据、回滚记录 | 有准确制品、发布范围和授权；不由原型验收推导部署许可 |
后续实现依次补齐站点信息架构、固定契约导入、版本/示例校验、搜索可用性、Runbook 与状态检查。原有服务发布链不因本轮文档改动而重建。
验收、维护与回滚
文档实现需检查 MDX、UTF-8、代码围栏、JSON、内部链接、导航和路由；涉及站点代码时再运行相应类型、构建、依赖和浏览器检查。验证桌面与 390/430px、搜索和新增关键路由，区分样板验收、代码验证与线上检查。
需求/设计改变先更新对应决策和来源；接口变更由规范 Owner 固定版本后更新说明；仓库验收后同步实施、Progress 和证据索引。当前工作可记录在本地协调表，GitHub 用于需要的外部审查或发布归档。
现有 main 发布链会更新 la-vps2；后续发布必须对准获准范围和不可变镜像。失败恢复上一已验证 Image Digest，不在服务器手工改内容。发布规则见验收、发布与回滚，本轮执行范围见统一实施流程。