---
title: 数据时效与时间字段
description: 如何根据响应字段判断材料、数据版本和交易数据的时效与完整性。
pageClass: gendangzou-doc
---

# 数据时效与时间字段

调用方应读取响应时间字段，不能用请求时间代替数据时间。

## 数据时效

| 数据 | 更新频率或版本 | 使用说明 |
| --- | --- | --- |
| 政策材料 | 约每 5 分钟检查新材料 | 以返回材料及时间字段为准 |
| 权威媒体材料 | 约每 5 分钟检查新材料 | 以返回材料及时间字段为准 |
| 连续实时流 | 滚动时间窗口 | 以 `signal_ready_at` 为准 |
| 公司身份与生命周期 | 约每小时更新 | 以返回状态和来源为准 |
| 板块目录 | 已发布数据版本 | 读取实际 `snapshot_id`、`as_of` |
| 三类板块信号 | 已发布数据版本 | 三类信号分别读取 |
| 公司板块映射 | 已发布数据版本 | 使用同一 `snapshot_id` 比较 |
| ETF 产品与官方篮子 | 已发布数据版本 | 读取 `basket_date` 与新鲜度状态 |
| ETF 板块映射 | 已发布数据版本 | 读取篮子与映射的时间口径 |
| 历史热度序列 | 已发布数据版本 | 以实际返回日期为准 |

上述频率不保证每次请求都有新增结果，也不保证材料发布后 5 分钟内即可查询。
请根据响应时间字段和 `quality.status` 判断结果是否满足使用要求。

## 实时窗口

`signal.realtime.*` 使用 `1h`、`6h`、`24h` 或 `3d` 滚动窗口，以
`signal_ready_at` 判断材料是否在窗口内。响应同时返回当前窗口与前一个等长窗口，
用于比较板块关注变化。该时间口径独立于 `snapshot_id`、`as_of` 和
`published_at`；完整数据版本发布不会重置实时窗口。

## 材料时间

| 字段 | 含义 |
| --- | --- |
| `business_date` | 查询使用的北京时间自然日 |
| `material_date` | 来源标注的材料发布日期 |
| `first_seen_at` | 系统首次发现材料的时间 |
| `signal_ready_at` | 正文、观点分析和当前板块映射全部完成的时间 |

省略材料接口的 `date` 参数时，服务使用当前北京时间日期。

## 版本时间

| 字段 | 含义 |
| --- | --- |
| `snapshot_id` | 完整数据版本标识 |
| `as_of` | 版本对应的业务日期 |
| `published_at` | 版本完成发布的时间 |
| `publication_mode` | `published` 为正式发布，`derived` 为从完整历史运行恢复 |

接口返回的数据版本可能早于请求自然日。例如完整版本尚未发布时，查询仍返回最近一个
可用版本，调用方应展示实际 `as_of`。

### 资料完整性

`data_status=complete` 表示该版本的关联数据可查询，不代表已处理所有已发现资料。
读取 `quality.status` 判断处理完整性，完整响应和 `detail=compact` 都保留该字段：

| 字段 | 含义 |
| --- | --- |
| `quality.status` | `complete`：检查通过；`degraded`：存在积压或失败环节；`unknown`：未测量 |
| `quality.cutoff_at` | 本次完整性检查覆盖的材料发现截止时间 |
| `quality.checked_at` | 实际检查时间 |
| `quality.pending_jobs` | 截止时间前尚未完成的正文或分析任务数，包含历史积压 |
| `quality.daily_pending_jobs` | 当期材料尚未完成的任务数 |
| `quality.dead_jobs` | 截止时间前重试耗尽的任务数 |
| `quality.reasons` | 降级原因代码，如 `material_backlog`、`company_facts` |

任务数不是去重后的材料篇数。历史版本缺少 `quality` 时，不应推断为资料齐全。
`degraded` 版本可以读取，但其结果只能描述已处理数据，不能视为当期全部信息。

## 交易时间

| 字段 | 含义 |
| --- | --- |
| `market_trade_date` | 资金维度实际使用的交易日 |
| `market_age_days` | 该交易日距离版本业务日期的自然日数 |
| `market_mapping_reaggregated` | 是否使用当前板块映射重新聚合已有交易数据 |

`market_status`：

- `fresh`：使用新的收盘交易数据。
- `carried_forward`：休市或无新行情，沿用最近交易日结果。
- `reaggregated`：沿用最近交易数据，并按当前板块映射重新聚合。
- `unavailable`：没有可用资金结果。

休市期间不能把沿用结果表述为当日发生的新资金变化。

## ETF 篮子时间

| 字段 | 含义 |
| --- | --- |
| `basket_date` | 交易所 PCF 对应的业务日期 |
| `basket_checked_as_of` | 最近一次核验交易所目录的日期 |
| `basket_age_days` | 篮子业务日期距版本业务日期的自然日数 |
| `source_fetched_at` | PCF 正文实际获取时间；复用未变化篮子时可早于当前版本 |

`basket_freshness_status`：

- `refreshed`：本轮重新获取并解析 PCF。
- `verified_unchanged`：本轮已核验，交易所篮子日期未变化。
- `carried_forward`：来源异常，降级沿用既有篮子。
- `unknown`：无法确认新鲜度。

判断 ETF 数据是否可用时，应同时读取 `basket_date`、`basket_checked_as_of` 和
`basket_freshness_status`，不能只比较篮子日期与请求日期。