# v0.45 持续历史数据与来源档案

模型：`versioned-market-data-v1`；规则：`market-data-0.45.0`。入口：`/research/data`。

## 使用流程

1. 在币种管理中添加或启用币种，再创建 Binance 或 OKX 的 USDT 现货数据流，选择日线或4h、60–1095天历史区间、最低估算日均成交额。默认暂停，不需要交易密钥。
2. 填写操作理由后启用。每次“推进一页 / 完成归档”处理元数据、一页K线或最终归档；刷新页面只读取状态。后台运行器或本站采集工具也只推进显式启用的数据流。
3. 等待版本归档，检查缺口、零成交量、交易状态、流动性与修订。缺口不会被填平，来源不会混合。低质量版本可留档，但不能用于本版的服务端数据绑定。
4. 下载各币种“研究快照”，在多策略组合研究页导入、计算并保存研究归档。在服务端任务页选择该归档，勾选显式绑定匹配的数据版本，创建任务。绑定要求每个研究币种一个不同的、同来源的健康日线版本，快照哈希完全匹配。未绑定任务保留原来源状态。
5. 下载“完整数据版本”和“原始来源证据”以离线复算；增量版本还需要原父版本。数据库、原始响应和快照对象分别备份。

创建、启停和配置修改需要researcher及以上角色。创建者可管理自己的数据流，管理员可管理工作区数据流；原对象恢复核验仅限管理员。条件修改中断未完成周期，下一版完整重采；已归档版本保留原配置和原哈希。

## 上游和时间口径

| 来源 | 元数据 | 历史K线 | 分页 |
| --- | --- | --- | --- |
| Binance | `https://data-api.binance.vision/api/v3/exchangeInfo` | `/api/v3/klines`，`1d` / `4h` | 每页最多300条，按开盘时间向前 |
| OKX | `https://www.okx.com/api/v5/public/instruments` | `/api/v5/market/history-candles`，`1Dutc` / `4H` | 每页最多100条，按时间向后 |

只采集已收盘且超过1.5秒确认余量的周期，OKX同时要求`confirm=1`。范围使用UTC、左闭右开；滚动结束时间取当前最近完整周期。4h完整版本可以含当日已收盘K线；供旧研究协议使用的兼容快照裁剪到完整UTC日。兼容快照中的分页响应哈希对应派生标准化块，不是上游原始HTTP响应；实际来源响应哈希在版本清单和来源证据中。

每轮回查最近七天重叠数据，至少每周重采完整历史窗口，以发现较早修订。增量合并会移除回查区间中已消失的K线，记录新增、修订与缺失；父版本保持不变。完整重采缺失父对象时允许生成新版本，但标记修订比较不可用；增量缺失父对象时停止，须恢复原对象或显式完整重采。

元数据保留交易对可用状态。上市时间仅采用来源明确提供的字段；无字段时为null，不用首根K线推断上市日期，也不杜撰下市时间。停止交易、无交易对、HTTP异常与限流分别可追溯。

官方接口说明：[Binance行情接口](https://developers.binance.com/en/docs/catalog/core-trading-spot-trading/api/rest-api/market)、[Binance公开行情域名](https://github.com/binance/binance-spot-api-docs/blob/master/faqs/market_data_only.md)、[OKX API](https://www.okx.com/docs-v5/en/)。公开访问不代表获得商业再分发许可，商业服务上线前应核实适用条款。

## 证据和质量

版本清单冻结`config`、`configHash`、父版本及其清单哈希、区间、分页游标、URL、采集时间、HTTP状态、原始UTF-8响应体SHA256及大小。响应体指fetch解码后的HTTP实体，不是TLS报文或压缩前的线缆字节；有效UTF-8的BOM保留。原始响应按内容哈希存入私有对象存储，标准化快照按工作区与版本存储。

数据版本含排序K线、标准化哈希、兼容研究快照、缺口及修订。质量标记包括首尾缺口、零成交量和近30日估算日均成交额。估算额为`收盘价 × 基础币成交量`累加后除以天数，不代表精确成交额或可成交深度。可研究要求至少290根、完整连续、无零成交量且达到配置阈值；本版显式任务绑定另要求日线、同来源和所有币种精确匹配。

`capture=server_http_response`描述本站实际采集过程；`sourceAuthenticityVerified=false`明确它没有交易所签名。自带哈希可以检查文件一致性，单独导出文件不能证明它来自可信服务器；应结合受信部署、访问控制与审计记录。数据采集和绑定不会自动提升模型准入或生成交易信号。

## 接口与后台推进

统一前缀为控制台`/api/console`或独立认证`/api/v1`。独立API使用`Authorization: Bearer …`；控制台会话不能代替独立API密钥。工作区选择和权限规则沿用现有接口。

| 方法与相对路径 | 用途 | 独立API权限 |
| --- | --- | --- |
| `GET /research/data` | 数据流及版本列表 | `data:read` |
| `GET /research/data/detail?id=…` | 固定版本清单 | `data:read` |
| `GET /research/data/download?id=…` | 完整数据版本 | `data:read` |
| `POST /research/data/export`，`{"id":"版本UUID"}` | 原始响应证据 | `data:read` |
| `POST /research/data/tick`，`{}` | 推进一条到期启用流的一个阶段 | `data:run` |
| `POST /research/data/streams` | 创建暂停流 | 仅控制台 |
| `POST /research/data/control` | 启停、重采或修改条件 | 仅控制台 |
| `POST /research/data/run` | 手动推进指定流 | 仅控制台 |
| `POST /research/data/repair` | 恢复后核验原对象 | 仅管理员控制台 |

请求严格校验，tick不接受价格、蜡烛、来源URL或owner覆盖。`data:run`不授予数据下载、研究计算、通知或交易权限。Python运行器支持`--lane data`，密钥从环境变量读取，具体参数见`trendlab-shadow-runner.py --help`。每次tick最多推进一个阶段，首次历史采集需要多次调用。

本站MCP通过`POST /mcp`暴露`trendlab_data_status`及`trendlab_collect_data`，参数仅可选`workspaceId`。采集工具要求平台核验的调用者身份、工作区成员资格与researcher及以上角色；独立OIDC模式不开放此MCP入口，可使用独立API运行器。工具不会启用暂停流。声明MCP能力不代表已安装连接或创建云端任务；云端任务建立、实际执行、上游成功与持久化回读应分别验收。

## 并发、容量与故障

每工作区最多40条流、200个版本；一条流的币种/来源/周期组合唯一。每工作区同一时间一个60秒租约，单周期24小时期限、最多70页、80次来源记录，累计五次失败结束本周期。上游按来源全站每分钟最多20次调用，429/418或OKX限流共享退避。创建者被撤销、角色降级或账户失效会阻断后续提交；操作中暂停、改配置或租约失效不会发布部分结果。

每响应512KiB、标准化快照4MiB；每工作区清单总量3MiB，其中预留8KiB终止记录；引用对象总量64MiB。容量限制按数据库引用计数，不能视为对象存储物理用量硬上限；取消或失去租约后可能留下孤立对象，需要运维核对清理。原始证据JSON导出上限8MiB，超过时使用管理员对象备份。达到版本或存储容量后需管理员处理，不自动删除研究引用。采集不计研究评估用量，仍有上述资源限制。

## 复算、备份与回退

Node22.13或以上，在项目根目录执行（输出文件必须尚不存在）：

```bash
node --experimental-strip-types scripts/reproduce-data.mts \
  --capture source-proof.json --snapshot data-version.json \
  --out reproduction.json
```

有父版本的增量或修订比较追加`--parent parent-data-version.json`。工具核验原始响应、URL游标相关记录、冻结配置、父版本、标准化数据和完整快照哈希，重新生成一致的数据版本；它不提供独立的服务器来源认证。

新增`market_data_streams`、`market_data_versions`、`research_data_bindings`三张业务表；共享来源退避表`market_data_limits`为运行态，不进入备份。总计53业务表、25迁移、33便携恢复文件；v0.44.1的31文件冻结于`/integration/v0441/`。

恢复演练核验配置、版本身份、对象索引和研究绑定，不把数据库元数据验证称为原始行情数值复算。恢复副本暂停所有数据流、清除租约、将未完成版本标为中断，对象标记待恢复。管理员须将原始响应与快照按原对象路径恢复，调用repair验证原内容哈希，再显式启用；repair不能上传任意替换价格。已绑定研究任务沿用固定版本，未恢复的对象不被当作可用数据。

使用`/integration/release-v045.json`检查回退兼容性，禁止直接回退到不支持新模型的版本。该文件中的sourceCommit/savedVersionId是待填写的发布来源槽位；真实部署来源以原生发布返回记录为准，不伪造已发布标识。

验证记录见`/research/verification-v045.json`。隔离测试使用合成上游响应；真实交易所连通、云端无人值守持续运行、浏览器点击和正式商业上线验收分别列为未完成项，不能以本地通过代替。