API 契约
TradingCopilot 的 HTTP API 以 /api 为根路径。除健康检查、初始化、登录和部分原生协议端点外，受保护路由都需要 Bearer token。
http
Authorization: Bearer <jwt>OpenAPI 文件是机器可读事实来源；本文是部署使用者和贡献者的实用索引，用于理解接口边界、认证方式、资源分组和排障方向。
请求形态
JSON:API 约定
| 约定 | 说明 |
|---|---|
data.type | kebab-case 复数资源名 |
id | 始终是字符串 |
attributes | 业务字段，使用 camelCase |
relationships | 关联关系 |
errors | [{ code, message, detail?, field? }] |
| 分页 | page[limit] 和 page[cursor] |
游标是不透明值。客户端必须原样透传，不得解析、自增或自行构造。
公开接口
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /health | 健康检查 |
GET | /auth/bootstrap-required | 判断是否需要管理员初始化 |
POST | /auth/bootstrap | 首次创建管理员 |
POST | /auth/login | 登录并获取 token |
接口分组
| 领域 | 常见路径 | 使用者关心点 |
|---|---|---|
| Dashboard | /dashboard | 系统状态、运行时诊断 |
| Logs | /logs, /logs/files | 排障、审计、噪声过滤 |
| Settings | /settings/* | 环境、密钥、代理、应用设置 |
| AI | /ai/providers, /ai/roles | 模型提供商、模型同步、角色能力 |
| Research Teams | /research-teams/* | 团队、团队角色、默认角色重置 |
| Market | /market/* | 标的、报价、历史数据、自选列表 |
| Messages | /message-subscriptions/*, /ingested-messages/* | 订阅、过滤器、采集消息 |
| Meetings | /meetings/* | 会议 CRUD、事件、引用、复盘、SSE |
| Wake Plans | /wake-plans/* | 唤醒计划、暂停、恢复、触发、取消 |
| Paper Trading | /paper/* | 账户、风控、订单、成交、持仓、绩效 |
认证和错误
受保护接口没有 token 或 token 无效时，应返回认证错误。业务错误应包含稳定 code 和人类可读 message，必要时包含 field。
客户端排障建议：
- 先确认 HTTP 状态码。
- 再看 JSON:API
errors。 - 对照日志中的
event、group、status。 - 最后检查对应领域配置。
SSE 和静态资源
会议事件流使用原生 SSE：
text
GET /api/meetings/{meetingId}/streamSSE 流和静态前端资源保持原生协议，不包装为 JSON:API。生产反向代理应避免过短的读超时导致事件流中断。
消息领域规则
- 消息订阅资源与提供方无关。
- Telegram 和 RSS/Atom 是 provider 值，不是独立路由模型。
sourceMessageId始终是字符串。- 启用订阅必须绑定至少一个研究团队。
- RSS/Atom 订阅要求公开 URL，v1 不支持 feed 认证。
变更检查清单
修改 API 时同步：
- OpenAPI 契约。
- 生成的 Go 服务端接口。
- 生成的前端 TypeScript 类型。
- API 契约文档。
- 对应领域测试和前端调用。