# v0.20 自选币种历史研究

入口：策略研究台 → 自选币种历史研究，或 `/research/history`。原 BTC / ETH / SOL 冻结研究页及其稳健性验证保持原有范围。

## 使用流程

1. 登录后，在当前工作区「币种管理」添加并验证币种。
2. 选择币种、4 小时 / 日线、Binance / OKX，以及 UTC 日期区间。截止日期当天不包含在内，最长 1095 天。
3. 获取历史数据。交易对元数据在所选来源单独核验；只采集该来源的 USDT 现货已收盘 K 线。分页失败、取消、权限撤销、币种移除或无效响应时，不生成不完整快照。
4. 查看质量报告，再点击「运行回测」。至少需要 290 根连续 K 线，其中 260 根用于预热，剩余至少 30 根用于回测。日线应选择较长区间。
5. 下载快照、完整研究结果及交易明细。快照只在当前页面内存中，关闭或刷新前请下载。重新导入快照可在相同规则及成本下复现结果。

## 数据口径

- Binance 使用 `api/v3/klines`，每页最多 300 根，按 startTime 向前推进；OKX 使用 `api/v5/market/history-candles`，每页最多 100 根，按 after 向前追溯。OKX 日线使用 `1Dutc`，只接受 confirm=1。
- 全部时间为 UTC。范围采用 `[start,end)`。价格、成交量、周期对齐、收盘确认、来源、交易对与分页进度逐页检查。
- 不同来源不混接。不会用备用交易所数据填补所选来源缺口，不生成合成 K 线，不前向填充价格，不把零成交量删除后继续计算。
- 区间内缺口、末端缺失、零成交量、历史不足时阻止回测。开头缺失会明确提示；若剩余数据连续且足够，可仅回测实际取得区间，先使用其前 260 根预热，不宣称覆盖原请求的全部日期。
- OKX 元数据若提供有效 `listTime` 则展示；Binance 此处使用的元数据不提供上市时间，保留未知。最早取得的 K 线不能用于推定全球首发、上市或代币创建日期。
- 当前币种注册要求可验证现货交易对，未覆盖已退市币种，存在幸存者偏差。不同交易所的标的历史、交易状态和数据可用范围可能不同。

## 回测与复现

沿用 `research-0.2.0` 的 C01 / C02 / C06 固定规则，以及 C06 去量能、持有 40%、持有 100% 三个对照；数值参数及成交模型没有修改。新研究区间以实际数据为准，不套用旧冻结快照的固定开始日期。

初始资金 10,000 USDT；策略每次入场使用权益的 40%，无杠杆、不做空；收盘决策、下一根开盘参考成交，两侧计手续费和不利滑点。止损优先处理同根双触及，期末扣费结算。历史可见、固定规则回溯，不是盲测样本外证明。尚未把新增快照接入滚动寻优验证。

快照格式 `trendlab-history-v1`，数据处理版本 `history-0.20.0`，包含交易对元数据、请求区间、逐页请求 URL、采集时间、响应摘要、归一化 K 线与 SHA-256。哈希按递归键排序的 JSON 内容计算（排除根层 sha256 字段）；同一份文件的排版或键顺序不影响校验。再次采集可能产生新版本，不覆盖原下载文件。

导入最多 4 MiB、100 页、6570 根；拒绝未知字段、错误哈希、不完整分页链、来源混用及重复 K 线。导入文件重新执行质量门禁。SHA-256 是完整性检查，不是交易所签名；他人可重算文件哈希，不能据此证明来源真实。页面区分本次联网采集与本地导入。

完整研究 JSON 同时包含快照、成本、规则版本、质量统计、全部净值点和交易。回测结果由浏览器计算；不会创建统一信号、执行通知或改变模拟账户。自选历史快照不保存到 D1，因此不进入工作区数据库备份。

## 数据读取 API

两个接口均需要独立 API 密钥的 `events:read` 权限，浏览器对应 `/api/console/` 路径；控制台现有四种成员角色可读取。API 密钥固定工作区，不接受覆盖租户的字段或请求头。读取前及上游响应后重新校验成员 / 密钥和币种归属。

| 接口 | 参数 |
|---|---|
| `GET /api/v1/research/history/market` | asset、venue |
| `GET /api/v1/research/history/page` | asset、venue、horizon、start、end、cursor |

venue 为 `Binance` 或 `OKX`；horizon 为 `4h` 或 `1d`。start / end / cursor 为 UTC 毫秒整数字符串；start / end 必须为 UTC 00:00，cursor 按周期对齐。Binance 首次 cursor=start，OKX 首次 cursor=end，后续必须使用返回的 nextCursor。nextCursor=null 表示当前分页结束；遇到短页仍可能需要下一页确认，不自行提前截断。重复参数、任意 URL、limit、owner 等额外字段一律拒绝。

返回页包括 request、url、fetchedAt、responseHash、candles、nextCursor。采集器最终核对所有页的标的、来源、周期、范围及游标链。每请求最多一次上游调用，10 秒超时、512 KiB 响应上限，不跟随重定向。

同工作区两个接口合计每分钟最多 30 次，控制台 / 多密钥共享此桶；另受原有每身份 / 密钥 60 次限频。页面请求开始间隔至少 2.1 秒，逐页读取，无后台预取。HTTP 429 / 418 及 OKX 50011 会停止本次采集，响应携带 Retry-After，用户稍后重新开始。历史读取不计入 manual_evaluations / scheduled_scans；其限频不是上游全局 IP 限流保障。

## 升级、回退与验收

无新增 SQL 迁移、权限名称或信号 Schema；数据库备份仍为 29 表。运行器继续使用 v0.19 批量协议，不需为历史研究升级。兼容清单 `release-v020.json`；回退 v0.19 后历史研究页面和接口不可用，下载的快照仍保留在用户手中。

自动化验证覆盖分页方向、来源验证、收盘与异常数据、缺口和不足、哈希篡改、取消与失败、成本和复现、租户隔离、权限撤销与限频。隔离测试使用明确标记的合成数据；真实行情采集验收与这些测试单独记录。上游不可用时不以测试数据替代。此功能不代表已完成生产 72 小时运行、真实通知、恢复或回退演练。

官方协议参考：

- [Binance 现货 K 线协议](https://github.com/binance/binance-spot-api-docs/blob/master/rest-api.md#klinecandlestick-data)
- [Binance 公开行情入口](https://github.com/binance/binance-spot-api-docs/blob/master/faqs/market_data_only.md)
- [OKX API 文档：历史 K 线与交易产品信息](https://www.okx.com/docs-v5/en/)

### 本次验证记录（2026-10-04）

187 项 Node 测试、19 项 Python 测试、100 项隔离 Worker HTTP 检查及 TypeScript 检查通过。新增 13 项历史研究测试覆盖异常行情、采集取消、分页链、篡改和精确复现；HTTP 检查覆盖实际编译产物的授权、限频和数据读取。

真实联网检查从 Binance 取得 DOGE / USDT 的 365 根日线（2025-10-04 00:00 至 2026-10-04 00:00 UTC，不含末端），无缺口、无零成交量，六组模型完成计算。前 260 根预热，实际回测为剩余 105 根，不将整个采集区间算作收益期。OKX 在此环境未返回有效 JSON，记录为不可用，未用合成数据替代或声称实源验收通过。

可用 `node --experimental-strip-types scripts/verify-history-live.mts` 重做真实来源检查；报告位于 `work/v020-live-history-verification.json`，联网条件和新数据会影响后续结果。