Gateway 对外契约文档缺失与示例漂移风险：导致第三方接入成本高且文实易不符

[pionxe]

Problem Description

• 当前 Gateway 的对外契约信息分散在实现代码与多份文档中，第三方接入方需要反复查源码才能确认请求、响应、错误与兼容边界。
• API 示例主要依赖手工维护，代码结构体变更后文档可能未同步，存在“文实不符”风险。
• 缺少统一的错误字典与字段废弃策略，第三方难以稳定编写 try-catch 与升级策略。

Current Defects

docs 层（缺少分层契约）

• 缺少“第三方接入协作指南”与“RPC 参考/错误字典/兼容性规范”的明确分工。
• 影响：内部与外部读者混用同一信息源，阅读路径长，接入效率低。

API 示例维护方式（手工更新）

• docs/reference/gateway-rpc-api.md 示例此前无法从 Go 结构体自动生成。
• 影响：internal/gateway/protocol/*.go 变更后，示例可能滞后且 CI 无法阻断。

错误处理与兼容策略（缺少统一文档）

• 错误码、HTTP 状态码与 JSON-RPC code 的映射规则未形成统一可查文档。
• 字段废弃缺少明确窗口和节奏，升级期行为不可预测。

Expected Changes

文档分层补齐

• 新增 docs/guides/gateway-integration-guide.md，仅面向第三方接入流程与排障。
• 新增 docs/reference/gateway-rpc-api.md，采用 XGO 风格固定模板描述每个方法。
• 新增 docs/reference/gateway-error-catalog.md，表格化对比 gateway_code / HTTP / JSON-RPC，并给出 Reasoning。
• 新增 docs/reference/gateway-compatibility.md，定义稳定/实验边界与字段优雅废弃流程（含 v1.2 Deprecated、v1.4 Removed 示例）。

示例自动生成与一致性校验

• 新增脚本 scripts/generate_gateway_rpc_examples/main.go，基于 Go 结构体自动生成 API JSON 示例并回填文档标记区块。
• 在 Makefile 增加：
  • docs-gateway
  • docs-gateway-check
• 在 CI（.github/workflows/ci.yml）增加 make docs-gateway-check，未同步文档时直接失败。

可发现性与协作入口

• 在 README.md 文档导航补齐 Gateway 相关文档入口，并把 make docs-gateway-check 纳入本地自检步骤。

Acceptance Criteria

• gateway.run 与 gateway.bindStream 的双向交互（ACK、事件回流、终态判断、取消路径）在 API 文档中有完整描述。
• 错误字典中每个稳定错误码都具备：HTTP 状态码、JSON-RPC code、gateway_code、Reasoning、客户端处理建议。
• 兼容性文档明确字段废弃流程与版本窗口，并包含可执行示例（v1.2/v1.4）。
• 执行 go run ./scripts/generate_gateway_rpc_examples 可稳定更新示例区块，重复执行无额外 diff。
• CI 能在文档未同步时阻断合并。

Related Files

• docs/guides/gateway-integration-guide.md
• docs/reference/gateway-rpc-api.md
• docs/reference/gateway-error-catalog.md
• docs/reference/gateway-compatibility.md
• scripts/generate_gateway_rpc_examples/main.go
• Makefile
• .github/workflows/ci.yml
• README.md
• internal/gateway/protocol/jsonrpc.go
• internal/gateway/errors.go
• internal/gateway/network_server.go

Assumption:

• 本轮以中文文档为主，不引入 SDK 与外部示例仓库。