调研 Go 重构的初步不可更改约束

背景

当前项目为 Java/Spring Boot 实现的 AI API 网关（bella-openapi），承载 150M+ 日调用量。在推进 Go 重构之前，需要先以文档形式明确"哪些外部协议、可观察行为、治理/计费/观测口径，以及执行链路中的内在约定，在 Go 版本中都不能改变"，为后续方案设计和验收提供清晰的硬边界。

诉求

完成一份"现状契约与不变量盘点"文档（已有初稿 docs/design/refactor2go-task1-contract-inventory.md），覆盖以下盘点范围：

Runtime 能力点

• /v1/chat/completions、/v1/messages、/v1/responses
• /v1/audio/*（TTS、Realtime ASR、Flash ASR、OpenAI Transcriptions、Async Transcription、Speaker）
• /v1/embeddings、/v1/images/*、/v1/ocr/*、/v1/videos
• /v1/web/*、/v1/document/*
• /v1/models、/v1/meta/*、/v1/route、/v1/log、/v1/metrics

管理类能力

• /v1/apikey/*、/v1/space/*、/v1/userInfo/*、/console/*

横向公共语义

• 鉴权与入口约束
• 请求上下文与特殊 Header（X-BELLA-* 系列）
• 错误归一（@EndpointAPI vs @BellaAPI 两套出口）
• 路由 / Direct / Mock / Private 模式
• 治理 / 限流 / 配额
• 观测 / 日志 / 收口
• 用量 / 计费
• Queue / Worker 执行语义

P0 回归验证基线（见文档第 6 章）：C-001 ~ C-010 共 10 个核心验证场景，覆盖鉴权、请求上下文、Chat/Messages/Responses 流式非流式、Realtime WebSocket、路由模式、Queue/Worker、用量计费观测。

预期影响

• 输出一份"不变量清单"，作为 Go 重构方案设计的硬边界与验收依据
• 明确哪些内容属于需要兼容的外部协议，哪些属于可自由重构的内部实现，避免范围蔓延或遗漏
• 为双栈对比测试（Java vs Go）提供协议级断言基准，而不是只检查调用是否成功
• 为团队对齐重构范围、分阶段交付和 P0 验收提供统一参考

证据

初稿文档已存在：docs/design/refactor2go-task1-contract-inventory.md

该文档目前已覆盖：

• 3.1～3.18 各能力点的"对外协议"与"不能改变的行为"两级盘点结构
• 第 4 章横向公共语义总结（鉴权、Header、错误、路由、治理、观测、计费、Queue）
• 第 6 章 P0 回归验证基线（C-001～C-010）及验证方式（历史回放、双栈对比、协议级断言、横向专项抽查）

相关链接

• 初稿文档：docs/design/refactor2go-task1-contract-inventory.md

Start with docs/design/refactor2go-task1-contract-inventory.md and compare its draft sections with the current Java/Spring Boot gateway behavior. Review the listed runtime, management, and cross-cutting capabilities, then verify scenarios C-001 through C-010 using the stated replay, dual-stack, and protocol-assertion methods. Done means the document clearly separates immutable external contracts from implementation details and records the P0 invariants.