数据时效与时间字段
调用方应读取响应时间字段，不能用请求时间代替数据时间。
数据时效
| 数据 | 更新频率或版本 | 使用说明 |
|---|---|---|
| 政策材料 | 约每 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，不能只比较篮子日期与请求日期。