API 与 protobuf 演进策略
SyncTV 当前按全新项目处理协议演进，不承诺对未发布或未稳定接口做反向兼容。项目内自有 protobuf 可以规整字段顺序、序号和消息结构，不需要为历史草案保留 reserved。
但以下文件不是 SyncTV 自有协议，不应修改：
synctv-proto/proto/buf/validate/validate.proto- 其他第三方 vendored proto 或生成工具依赖文件
| 协议 | 主要文件或入口 | 适用场景 |
|---|---|---|
| HTTP/OpenAPI | synctv-api/src/http/*，/api-docs/openapi.json | Web、移动端、第三方 SDK |
| gRPC | synctv-proto/proto/client.proto、admin.proto、provider proto | 强类型客户端、内部服务、调试 |
| Realtime WebSocket | ClientMessage、ServerMessage | 房间聊天、播放、WebRTC 和资源观察 |
| management gRPC | management proto 和 CLI | 运维控制面，不面向普通客户端 |
| 变更类型 | 当前策略 |
|---|---|
| 新增业务能力 | 优先补清晰消息、字段、错误和权限语义 |
| 字段命名不清晰 | 可以重命名并重新生成，但必须更新所有调用方 |
| 字段序号混乱 | 自有 proto 可以重新编号，不保留 reserved |
| 删除未使用字段 | 可以删除，补测试确认没有代码引用 |
| 第三方 proto | 不修改，除非升级该依赖来源并有明确记录 |
| 错误码 | 保持区间语义清晰，避免同一场景多套码 |
修改 protobuf 的检查清单
Section titled “修改 protobuf 的检查清单”- 确认要改的是 SyncTV 自有 proto，不是第三方 vendored proto。
- 调整
.proto字段、序号、注释和 service RPC。 - 重新生成 Rust 代码。
- 更新 HTTP/gRPC/Realtime 实现和测试。
- 更新 gRPC 调试、Realtime API 或 SDK 与 API 示例。
- 如影响客户端行为，更新 客户端集成指南 和 错误参考。
- 运行 proto、API 和文档检查。
修改 HTTP API 的检查清单
Section titled “修改 HTTP API 的检查清单”- 明确认证、权限、限流、body size 和错误分类。
- 更新 handler、OpenAPI annotations 和测试。
- 启动
openapifeature，确认 Swagger UI 和 JSON 可生成。 - 更新示例、错误处理和客户端文档。
- 如果是房间内状态，判断是否也要发 Realtime 事件或资源观察失效。
Realtime 变更
Section titled “Realtime 变更”Realtime 变更要特别注意：
ClientMessage和ServerMessage的oneof字段要能被客户端清晰分发。- 新增资源观察类型时，需要定义版本来源、payload、触发事件和 delivery mode 行为。
- 断线重连语义必须明确：哪些状态要重建，哪些版本可复用。
- 不要把大列表或大二进制内容直接塞进频繁广播消息。
文档同步要求
Section titled “文档同步要求”| 改动 | 必改文档 |
|---|---|
| 登录、2FA、OAuth2、token | 客户端集成、安全模型、错误参考 |
| 房间、权限、成员 | 房间权限、用户指南、常见任务 |
| 播放、Provider、proxy | 播放与代理模型、Provider 配方 |
| Realtime 消息 | Realtime API、SDK 与 API 示例 |
| 配置字段 | 配置总索引、完整配置示例、专题配置页 |
| 运维行为 | 观测、排障、容量规划或密钥轮换 |