feat(open-api): 0.3.2 开放能力版 — API Token 网关 + Tier A 契约 + 版本清单

- Token 域模块: tsp_ 前缀 + SHA-256 哈希存储 (0600), 明文仅创建时返回一次,
  吊销立即生效, last_used_at 节流落盘 (≥60s)
- Bearer 网关中间件 (与密码会话并行): 五档 scope 校验 (read:market/read:ext/
  read:analysis/run:backtest/paper:trade) + 滑动窗口限流 (默认 120/min,
  OPEN_API_RATE_LIMIT_PER_MIN 可调) + X-RateLimit 响应头; 管理接口永不对 Token 开放
- GET /api/openapi.json?tier=a 契约视图: 按网关规则表过滤 OpenAPI 规范 (58 路径),
  规则表即唯一契约源
- 设置 → 开放接口: Token 管理 UI (创建表单/scope 说明/明文一次性展示/吊销)
- 设置 → 系统设置 检查更新: 静态链接升级为真实版本对比 (GitHub API 优先,
  latest.json 清单兜底), 发现新版本给下载入口
- release.yml 新增 manifest job: Release 附 latest.json (版本/三平台下载地址/sha256),
  支持分批发布按实际资产生成
- 版本 0.3.1 → 0.3.2 (后端 __init__/pyproject + 前端 package.json)
- docs: features.md 开放接口章节; open-platform-plan.md V1/V2 标记已实现
- 测试: test_api_gateway.py 8 项 (域模块/scope 映射/E2E 401-403-200 矩阵/
  429+Retry-After/吊销即拒), 全量 2394 通过

docs/features.md

@@ -228,3 +228,47 @@ APScheduler 默认 15:35 CST 自动:拉日 K → 重算 enriched 表 → 跑监
 ### 令牌桶限流
 
 适配各档位 rpm / batch 限制,批量合并 + 增量拉取,避免触发数据源限流。
+
+## 🌐 开放接口(Open API · Tier A)
+
+外部程序(自己的看板/脚本/量化服务)无需面板密码,凭 **API Token** 直接调用核心只读与任务接口 —— 这是「核心能力开放」的第一层出口。总体设计与后续 Tier 见 [open-platform-plan.md](./open-platform-plan.md)。
+
+### Token 管理
+
+**设置 → 开放接口**: 新建 Token(名称 + 权限勾选),明文 `tsp_` 前缀只显示一次;可随时吊销,吊销立即生效。服务端只存 SHA-256 哈希(`data/user_data/api_tokens.json`,权限 0600)。
+
+### 五个权限(scope)
+
+| scope | 能力 |
+| :--- | :--- |
+| `read:market` | 标的搜索 / 日K / 分时 / 指数 / 市场快照 (默认勾选) |
+| `read:ext` | 扩展表 rows / values / schema 查询 |
+| `read:analysis` | 策略清单与结果 / 回测报告 / 市场环境 / 告警 |
+| `run:backtest` | 提交回测 / 选股 / 因子检验任务 |
+| `paper:trade` | 模拟盘读取与下单/撤单 (最高敏感) |
+
+管理接口(数据同步 / 扩展表写入 / 设置)**永不开放给 Token**;数据同步等写操作只能通过面板密码会话进行。
+
+### 调用方式
+
+```bash
+curl -H "Authorization: Bearer tsp_xxxx" \
+  "http://localhost:8398/api/kline/daily?symbol=600519.SH&start_date=2026-01-01"
+```
+
+- **认证通道与面板密码并行**: 带 `Authorization: Bearer` 走 Token 网关(scope 校验 + 限流),不带则走原有密码会话 —— 面板与外部调用互不影响;
+- **限流**: 每 Token 默认 120 次/分钟(滑动窗口,`OPEN_API_RATE_LIMIT_PER_MIN` 环境变量可调 1–10000),响应带 `X-RateLimit-Remaining` / `X-RateLimit-Limit` 头,超限返回 429 + `Retry-After`;
+- **错误语义**: 401 Token 无效或已吊销 / 403 权限不足或该接口未开放 / 429 超限;
+- **CORS 全开**(自托管场景),浏览器直连亦可。
+
+### 契约文档(机器可读)
+
+```bash
+curl "http://localhost:8398/api/openapi.json?tier=a"
+```
+
+返回按网关规则表过滤后的 OpenAPI 3 规范(`x-tier: a`)—— 哪些路径对外开放、需要什么 scope,**规则表是唯一契约源**,生成代码 / Postman 导入即用。
+
+### 桌面客户端版本清单
+
+发布流水线会在每个 Release 附带 `latest.json`(版本号、三平台下载地址、sha256),设置 → 系统设置 → 检查更新即基于它(优先 GitHub API)提示新版本。

docs/open-platform-plan.md

@@ -1,6 +1,6 @@
 # 核心能力开放与插件化改造设计方案
 
-> 状态: 设计稿（未实现）。本文档定义「核心域 / 扩展域」边界、对外 API 的认证与契约形态、以及分期改造路线。
+> 状态: V1/V2 已实现（0.3.2）—— Token + scope 网关 + 限流、五个 scope 全量 Tier A、`/api/openapi.json?tier=a` 契约视图、设置页 Token 管理（「设置 → 开放接口」）。V3+（钩子契约、SSE 票据、模拟盘拆分）仍为设计。使用说明见 [features.md → 开放接口](./features.md#-开放接口open-api--tier-a)。
 > 遵循 [CONTRIBUTING.md](../CONTRIBUTING.md) 的数据口径、插件化与测试矩阵要求; 扩展机制现状见 [secondary-development.md](./secondary-development.md)。
 
 ## 1. 目标与非目标
@@ -162,14 +162,14 @@
 
 ### V1 开门（Token + 护栏 + 最小契约）— 建议立即
 
-- Token 存储/创建/吊销 + 设置页管理 UI（「系统 → API Token」）。
-- 中间件: Bearer 识别 → scope 校验 → 限流 → CORS 配置。
-- Tier A 标注: 先覆盖 `read:market` + `read:ext` 两组（行情与扩展数据, 风险最低、二开最先用）。
-- 测试矩阵: 认证（无/错/过期 Token 401、scope 不足 403）、限流 429、CORS 头。
+- ✅ Token 存储/创建/吊销 + 设置页管理 UI（「设置 → 开放接口」，`services/api_tokens.py`）。
+- ✅ 中间件: Bearer 识别 → scope 校验 → 限流（`services/api_gateway.py`，CORS 原本已全开）。
+- ✅ Tier A: 直接覆盖全部五个 scope（`api_gateway._RULES` 规则表）。
+- ✅ 测试矩阵: `backend/tests/test_api_gateway.py`（401/403/429/吊销即拒/前缀混淆防护）。
 
 ### V2 契约化 + 示例仓库
 
-- Tier A 扩到策略/回测/监控事件/模拟盘; `?tier=a` OpenAPI 视图。
+- ✅ Tier A 已含策略/回测/监控事件/模拟盘; `GET /api/openapi.json?tier=a` 契约视图（规则表单源）。
 - 组织下建 `api-examples` 示例仓库: 「拉行情 → 跑策略 → 取结果 → 模拟盘跟单」三个可运行脚本 + README。
 - SSE 短期票据（query token）方案落地。