mirror of
https://github.com/shy3130/tick-stock-panel.git
synced 2026-11-02 10:26:13 +00:00
shy3130
f20772d7b7
二开闭环补齐三块: 数据进得来 (写入)、事件推得出 (SSE)、契约有人守 (快照+CI)。
- write:ext scope (第六档): POST /api/ext-data/{id}/ingest 对 Token 开放,
复用管理端同一校验/落盘/视图刷新路径; 结构配置/上传/拉取仍不开放,
外部只能写行数据, 不能改写表结构
- SSE 短期票据 (V2 收尾): POST /api/events/ticket 换 60s 一次性票据 →
GET /api/events?ticket=… 订阅事件流; 票据只继承 Token scope 不放大权限;
进程内事件总线 (services/events.py, 慢消费者丢旧保新), 告警落盘点已挂
(alert_store.append/append_many → bus), 事件按 scope 过滤双向验证
- 契约守护: test_openapi_contract.py 冻结 tier=a 开放面 (61 端点),
增删须显式更新快照; 新增 ci.yml (后端全量测试 + 前端构建) 把契约
变化拦在 PR 上
- examples/open-api: 四个零依赖可运行示例 (行情/写入/回测/事件流) + README
- 菜单设置架构标注: 每页核心/扩展徽标 + 悬停原因 + 图例 (按 open-platform-plan
§2 依赖方向分类, 核心 8 页/扩展 11 页); 顺带补上 MenuSettings 缺失的 模拟盘
- 测试: 网关 write矩阵/票据语义 + 票据生命周期/总线/SSE帧/告警联动 + 契约快照,
全量 2408 passed / 102s; 线上实测: ingest 200 / 票据一次性 / SSE hello+
alert 推送 / scope 过滤双向 / 契约 61 路径
47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
# 开放接口示例 (Open API Examples)
|
|
|
|
外部程序接入 tick-stock-panel 核心能力的可运行最小示例 — 纯 Python 标准库, 零第三方依赖。
|
|
|
|
## 准备
|
|
|
|
1. 启动面板 (或桌面客户端), 进入 **设置 → 开放接口**, 新建 Token 并勾选所需 scope:
|
|
|
|
| 脚本 | 所需 scope |
|
|
| :--- | :--- |
|
|
| `01_pull_market.py` | `read:market` |
|
|
| `02_write_ext_data.py` | `write:ext` + `read:ext` |
|
|
| `03_run_backtest.py` | `read:analysis` + `run:backtest` |
|
|
| `04_events_stream.py` | 任意 (票据继承 scope) |
|
|
|
|
2. 设置环境变量后运行:
|
|
|
|
```bash
|
|
export TSP_BASE=http://127.0.0.1:3018 # 面板实际地址
|
|
export TSP_TOKEN=tsp_xxxx # 创建 Token 时只显示一次, 立即保存
|
|
|
|
python 01_pull_market.py
|
|
```
|
|
|
|
## 脚本说明
|
|
|
|
| 脚本 | 演示能力 |
|
|
| :--- | :--- |
|
|
| `01_pull_market.py` | 标的搜索 (拼音可用) / 日K / 市场总览 |
|
|
| `02_write_ext_data.py` | 程序化写入扩展表行数据 + 读回验证 (数据同台分析闭环) |
|
|
| `03_run_backtest.py` | 策略清单 / 信号回测触发与结果读取 |
|
|
| `04_events_stream.py` | SSE 短期票据 + 事件流 (告警推送) |
|
|
|
|
## 通用约定
|
|
|
|
- 认证: `Authorization: Bearer tsp_...` 头; 与面板密码会话并行, 互不影响
|
|
- 限流: 每 Token 默认 120 次/分钟, 响应头 `X-RateLimit-Remaining` 实时可见, 超限 429 + `Retry-After`
|
|
- 错误语义: 401 Token 无效或已吊销 / 403 scope 不足或端点未开放 / 429 超限
|
|
- 机器可读契约: `GET /api/openapi.json?tier=a` — 可直接导入 Postman / 生成客户端
|
|
- 完整文档: [docs/features.md → 开放接口](../../docs/features.md#-开放接口open-api--tier-a)
|
|
|
|
## 注意
|
|
|
|
- `write:ext` 只能向**已配置好的**扩展表写行数据; 表结构 (字段/模式/拉取) 属管理面, Token 不可触及
|
|
- 写入的数据会进入策略信号 / 因子 / 回测的数据面, 谨慎授予该 scope
|
|
- SSE 票据一次性且 60 秒过期, 断线重连需重新 `POST /api/events/ticket`
|