Document market temperature roadmap

README.md

@@ -60,9 +60,14 @@ crypto-atr-signal
 ├── requirements.txt
 ├── VERSION
 ├── CHANGELOG.md
+├── ROADMAP.md
 └── README.md
 ```
 
+## 升级路线
+
+后续版本规划与指标口径见 [ROADMAP.md](ROADMAP.md)。当前下一目标为 `v1.4.0`“市场温度”，当前运行版本仍为 `v1.3.1`。
+
 ## 获取与更新项目
 
 推荐使用 SSH 克隆。Gitea 的 SSH 服务使用 `2222` 端口：

ROADMAP.md

@@ -0,0 +1,130 @@
+# Crypto ATR Signal Roadmap
+
+当前稳定版本：`v1.3.1`
+
+路线图用于记录已讨论但尚未实现的功能。版本号只在功能完成、验证并发布后更新。
+
+## v1.4.0 - 市场温度
+
+目标：增加一个只读的市场环境页面，帮助交易者判断当前适合何种风险和交易方式，不提供做多或做空信号。
+
+### 页面与入口
+
+- 新增 FastAPI 路由 `/insight`。
+- 新增 `templates/insight.html`。
+- 首页增加“市场温度”入口，现有首页、市场筛选和信号表保持不变。
+- 默认分析 `BTCUSDT`，支持 `BTCUSDT`、`ETHUSDT`、`SOLUSDT` 切换。
+- 分析周期保持 `4H`，只读取现有 SQLite 数据，不修改扫描逻辑。
+
+### 配置
+
+```env
+INSIGHT_ENABLED=true
+INSIGHT_SYMBOLS=BTCUSDT,ETHUSDT,SOLUSDT
+INSIGHT_DEFAULT_SYMBOL=BTCUSDT
+INSIGHT_STALE_HOURS=8
+```
+
+不动态获取“市值前十”。这样可以避免稳定币、无合约资产和市值名单变化带来的额外 API 依赖。
+
+### 单品种指标
+
+每个品种从 `klines` 表读取最多最近 100 个非空 ATR 样本，计算：
+
+- 当前 ATR。
+- 最近 30 根有效 ATR 均值。
+- 当前 ATR / 30 根均值。
+- 当前 ATR 在最近最多 100 根有效 ATR 中的百分位排名。
+- 最近 10 根 ATR 趋势。
+- ATR / 当前收盘价百分比，用于跨币种比较相对波动。
+- 最新已收盘 K 线时间、有效样本数量和数据是否过期。
+
+数据不足 100 根时必须显示“样本不足”和实际样本数，不得把不足 100 根的结果标为“100 根百分位”。
+
+### 百分位口径
+
+只使用 `atr14 IS NOT NULL` 的记录：
+
+```text
+百分位 = 小于当前 ATR 的样本数 / 有效样本总数 * 100
+```
+
+相同值可按中位排名处理。页面应展示整数百分位，并保留内部原始值用于判断。
+
+### ATR 趋势口径
+
+对最近 10 个有效 ATR 按时间顺序做线性回归。将拟合总变化量除以 10 根 ATR 均值：
+
+- 大于 `+5%`：上升。
+- 小于 `-5%`：下降。
+- 其余：震荡。
+
+不只比较第一根和最后一根，避免单根异常值主导结论。
+
+### 波动状态
+
+- ATR 百分位 `< 20`：低波动压缩。
+- `20 <= ATR 百分位 < 70`：正常波动。
+- `70 <= ATR 百分位 < 90`：高波动。
+- ATR 百分位 `>= 90`：极端波动。
+
+页面中文解释必须强调：ATR 衡量波动强弱，不预测价格上涨或下跌。
+
+### 市场温度总览
+
+总览结合以下数据，而不是只看 ATR：
+
+- BTC、ETH、SOL 的 ATR 百分位与 ATR 趋势。
+- 三个品种最近 24 小时价格涨跌，按 6 根 4H 已收盘 K 线计算。
+- Crypto 市场最近 24 小时上涨品种比例，作为市场广度。
+- SOL 相对 BTC 的 24 小时表现，作为风险偏好辅助指标。
+
+输出状态限定为：
+
+- `稳定偏多`：价格整体上涨，波动处于低至正常区间。
+- `亢奋`：价格整体上涨，波动处于高或极端区间。
+- `恐慌`：价格整体下跌，波动处于高或极端区间。
+- `低波动压缩`：价格横盘且波动处于低位。
+- `分化`：主要品种方向或市场广度明显不一致。
+- `中性`：不满足以上明确条件。
+
+具体评分阈值在实现时写成纯函数并增加测试，页面同时展示组成指标，避免只给不可解释的单一结论。
+
+### 交易者提示
+
+页面输出风险与策略环境提示，例如：
+
+```text
+当前处于高波动上升阶段。信号仍可观察，但建议降低仓位，避免使用过窄止损。
+```
+
+提示只用于仓位、止损和策略环境管理，不构成买卖建议。
+
+### 验收标准
+
+- `/insight` 不请求外部 API。
+- 不修改 `scanner.py` 的 K 线扫描、ATR 或信号逻辑。
+- BTC、ETH、SOL 可通过 `.env` 增减，不需要修改模板。
+- 样本不足、ATR 为空、品种不存在和数据过期均有明确中文状态。
+- 百分位、趋势、24 小时涨跌和市场广度使用自动化测试验证。
+- 桌面与移动页面无内容重叠，入口不破坏现有首页布局。
+
+## v1.4.1 - 验证与稳定
+
+- 根据实际运行数据校准市场温度阈值，不改变指标定义。
+- 增加 `/insight` 查询耗时记录和轻量缓存。
+- 补充数据缺失、休市、品种下架和异常 ATR 的边界测试。
+- 根据客户反馈优化中文解释与风险提示。
+- 验证 Discord、Cron、健康检查与市场温度页面长期并行运行。
+
+## v1.5.0 - 候选方向
+
+以下只作为候选，不提前承诺：
+
+- Discord 推送中增加一行市场温度摘要。
+- 市场温度历史变化图。
+- `1H`、`4H`、`1D` 多周期环境对照。
+- 市场温度历史回测与策略表现关联分析。
+- Telegram、Bybit 或 OKX 扩展。
+
+是否进入 v1.5.0 取决于 v1.4.x 的实际使用价值和客户反馈。