股指期货贴水价差监控

解决的问题

做股指期货贴水分析的人大多经历过同样的麻烦：合约日线来自 akshare，指数日线来自另一套接口，两边格式不一致、日期对不齐，拼到一张图上还得自己算基差、剩余天数和年化升贴水率。更麻烦的是数据源静默返回空值或延迟数据，图表上看不出异常，结论却已经错了。这个技能把这套流程固化成脚本：给出品种和区间，拿回对齐好的数据文件和看板。

核心能力

• 双数据源交叉验证：主源为 akshare，兜底源是新浪财经 HTTP 接口，直接用标准库 urllib 请求。两源逐交易日比对收盘价，偏差超阈值即告警，主源缺失时由另一源补齐。
• 自动推算在交易合约：按中金所挂牌规则（当月、下月、随后两个季月），由 scripts/contracts.py 生成合约代码与到期日（合约月份第三个星期五）。品种到挂钩指数的映射为 IF→沪深300、IH→上证50、IC→中证500、IM→中证1000。
• 衍生指标计算：基差 = 期货收盘价 − 挂钩指数收盘价；年化升贴水率按剩余天数折算；所有价格统一 round(x, 2)。
• 两份交付物：futures_source.csv 合并全部标的源数据（非交易日保留行，价格前向填充），futures_dashboard.html 为交互式 Plotly 看板。

工作流

1. 解析品种（1~2 个）与分析区间，默认今年以来至当日；若指定两个标的做价差则记录下来，否则取最近两合约。
2. 运行 scripts/fetch_data.py 产出 raw_futures.json，校验每个标的至少有 2 个交易日收盘价。
3. 运行 scripts/build_dashboard.py 产出 CSV 与 HTML。
4. 通过 present_files 同时交付两个文件，文字结论只基于真实数据。

看板分两个板块：板块一叠加展示一个品种全部在交易合约及挂钩指数的价格走势，下方表格列出当日各合约的基差、年化升贴水率与剩余天数；板块二可用下拉框任选标的 A / B 绘制价差曲线，支持悬停参考线与区间涨跌幅模式。

适用边界

数据严格限定在两个已配置数据源内，明确禁止用 WebSearch 或网页文章取价。两源都拿不到数据时会显式告知标的缺失，不用估算值填充。看板数据截止于 raw_futures.json 的生成时间，不含实时行情。所有输出都是历史与当日数据的可视化和测算，不构成投资建议。