# BTC 短线看板 · 程序路由地图

> 用途：让 **AI / 后续修改者** 一眼看懂本目录所有文件的作用、数据流、接口与配置，
> **改代码前请先读本文件**，不要重复翻阅全部源码。
> 主程序入口索引见 `btc_data_web.py` 顶部注释。

---

## 一、总体架构（一句话）

```
采集器(Python, systemd/ cron)
   ↓ 写入
MariaDB  btc_data 库 (各 tick/bar/信号表)
   ↓ 读取
btc_data_web.py  (Python2, BaseHTTPServer, 端口 9511)
   ├── 后端: 几十个 JSON API + 内嵌前端 HTML 页面
   └── 前端: 单文件内嵌 HTML/JS(CSS+JS 均在 HTML_PAGE 字符串里)
   ↓ 写入/读取
btc_notify_events / btc_alert_events / btc_uiprefs.json / *.config.json
   ↓ 推送
ntfy (手机 App, 内网 127.0.0.1:2587)
```

平台只一人使用，所有 UI 设置/告警配置均存 **服务端**（多端访问一致），
只有「交易登录口令」不走服务端、仅本地缓存。

---

## 二、核心文件职责

### 1. Web 主服务
| 文件 | 职责 |
|---|---|
| `btc_data_web.py` | **主文件**。Python2 + BaseHTTPServer，端口 9511。内含：后端全部 JSON API + 整个前端页面（HTML/CSS/JS 都写在本文件 `HTML_PAGE = u"""..."""` 字符串里）。 |
| `btc_data_web.pyc` | 编译缓存（自动生成）。 |

> ⚠️ 改前端一定要知道：页面 JS 在 Python2 三引号字符串里，
> 不能写反斜杠换行 `\n`（会变真换行）、不能写 `\uXXXX`（会变 unicode）。
> 需要换行用 `String.fromCharCode(10)`；改完用 `node --check` 校验提取出的 JS。

### 2. 事件 / 告警引擎
| 文件 | 职责 |
|---|---|
| `btc_events.py` | **事件引擎**（阈值监测）。`get_state()` 返回 7 个风险指标的阈值接近度快照；`compute()` 每分钟推进并落库。 |
| `btc_notify.py` | **重要事件留痕**。表 `btc_notify_events`；`push()` 落库 + 去重 + ntfy 推送；`get_list()` 分页查询（只看 `ae.*` 新告警引擎事件）。 |
| `alert_engine/` | **新告警引擎**（Python3，独立子包）。见下方「告警引擎」章节。 |

### 3. 信号 / 策略 / 分析
| 文件 | 职责 |
|---|---|
| `btc_intent.py` | 主力意图（多空意图、置信度、解释）。 |
| `btc_signal.py` / `btc_strategy.py` | 5m 信号 + 策略回测/绩效。 |
| `btc_engine_1m.py` | 1 分钟引擎。 |
| `btc_cycle_score.py` | 周期评分。 |
| `btc_reversal.py` | 反转（二反转/止损/超时）事件与 `btc_reversal` 表读写。 |
| `btc_plan_log.py` | 交易计划日志（plan_log）。 |
| `btc_touch_risk_new.py` | 触摸风险（关键位/风险提示）。 |
| `btc_epi.py` | 情绪/EPI。 |
| `advice_rules.py` | 建议规则（advice）。 |
| `binance_trade.py` | **交易模块**（币安合约，登录/下单/持仓/风控上限）。 |

### 4. 采集器（写库）
| 文件 | 采集内容 | 对应表 |
|---|---|---|
| `btc_collector.py` | 5 分钟 K 线 | `btc_5m` |
| `btc_1m_collector.py` | 1 分钟 K 线 | `btc_1m` |
| `btc_oi_tick.py` | 持仓量 tick | `btc_oi_tick` |
| `btc_taker_tick.py` | 主动成交 tick | `btc_taker_tick` |
| `btc_depth_tick.py` | 盘口深度 tick | `btc_depth_tick` |
| `btc_depth_pro.py` | 深度专业版（主动买卖/墙） | 深度相关表 |
| `btc_liq_tick.py` | 强平 tick | 强平表 |
| `btc_macro_collector.py` | 宏观指标 | 宏观表 |
| `btc_vol_probe.py` | 波动率探测 | 波动相关表 |

### 5. 告警引擎 `alert_engine/`（Python3）
| 文件 | 职责 |
|---|---|
| `run.py` | CLI 入口。`python3 -m alert_engine.run [--library/--once/--dryrun/--run/--profile/--export-rules]`。`--run` 增量轮询产出事件并落库+通知。 |
| `rules.py` | **规则库种子** `build_library()`：17 条规则（背离/持仓/资金流/结构/拥挤/波动/盘口/强平 9 族），`library_report()` 体检。 |
| `rules_config.py` | 规则元数据 `RULES_META`（中文名/说明）+ 运行配置读写；`export_library()` 导出 `rules_library.json`。 |
| `rules_library.json` | 前端「告警设置」读取的规则清单（`--export-rules` 生成）。 |
| `rules_config.json` | 每条规则启用开关（前端「告警设置」保存到这里）。 |
| `engine.py` | 引擎编排：事实→物化→求值→状态机→AlertEvent；`Engine.process()`/`replay()`。 |
| `state.py` | **状态机** IDLE/ARMED/FIRING/COOLED/RESOLVED（决定性关卡：触发=ARMED->FIRING，解除=FIRING/COOLED->RESOLVED）。 |
| `event.py` | AlertEvent/Contributing/Trigger 等对外契约 + 幂等指纹。 |
| `eval.py` / `dsl.py` / `operators.py` | 条件求值 / DSL 解析 / 算子。 |
| `materializer.py` | 事实物化（把原始行物化成槽族 price/bar/flow/cvd/oi/…）。 |
| `persist.py` | 事件落库：`btc_alert_events`（结构化 JSON）+ `btc_notify_events`（人类可见）；`alert_to_notify()` 生成告警详情。 |
| `profile.py` / `stats.py` | 阈值画像 / 统计。 |
| `db.py` / `datadict.py` | 数据源连接 / 数据字典配置。 |
| `runtime_state.json` | 引擎 watermark + 状态（冷启动种子/增量）。 |

> 解除机制：`state.py` 中所有规则默认 `auto_resolve=True`，
> 条件不再成立后经 COOLED 冷却期自动产出 `RESOLVED` 事件，
> `persist._notify_resolve()` 把对应告警原地改为「已解除」(`ae.ok.<severity>`)，
> 并追加「解除时间」。**17 条规则均有解除机制**。

---

## 三、主要 API 路由（`btc_data_web.py`）

| 路由 | 方法 | 说明 |
|---|---|---|
| `/` | GET | 渲染整页（HTML_PAGE，注入 `__PREFS_JSON__` 服务端 UI 偏好）。 |
| `/api/health` | GET | 全模块 API/引擎状态快照（6 采集器新鲜度 + 事件引擎 + 告警引擎 + 交易 API）。 |
| `/api/risk_state` | GET | 事件引擎阈值监测 7 指标快照。 |
| `/api/notify_list` | GET | 重要事件分页（`page`/`size`，只看 `ae.*`）。 |
| `/api/notify_push` | POST | 落一条事件（前端兜底，旧引擎已下线基本不再用）。 |
| `/api/alert_prefs` | GET/POST | 读取/保存告警规则启用配置（`rules_config.json`）。 |
| `/api/uiprefs` | GET/POST | **UI 偏好服务端持久化**（`btc_uiprefs.json`，折叠/排序/抽屉等全走这里）。 |
| `/api/config` / `/api/config_reset` | POST | 其它配置读写/重置。 |
| `/api/intent` / `/api/plan` / `/api/plan_log` | GET | 主力意图 / 计划 / 计划日志。 |
| `/api/level_state` | GET | 关键位状态。 |
| `/api/reversal_state` / `/api/reversal_events` | GET | 反转状态 / 反转事件。 |
| `/api/trade/status` `/api/positions` `/api/position` `/api/trade/log` | GET | 交易状态/持仓/日志（需登录态）。 |
| `/api/login` `/api/logout` `/api/trade/preview` `/api/trade/order` | POST | 交易登录/登出/预览/下单。 |

---

## 四、关键数据表（MariaDB `btc_data`）

| 表 | 说明 |
|---|---|
| `btc_5m` / `btc_1m` | 5m / 1m K 线。 |
| `btc_oi_tick` / `btc_taker_tick` / `btc_depth_tick` | OI / 主动成交 / 盘口 tick（秒级）。 |
| `btc_notify_events` | 重要事件/告警留痕（`ae.*` 为首页展示项）。 |
| `btc_alert_events` | 告警引擎结构化事件（完整 AlertEvent JSON）。 |
| `btc_reversal` | 反转事件。 |
| 其它信号/策略绩效表 | `signal_calib*`、`strategy_perf*`、`plan_log` 等。 |

---

## 五、配置文件一览

| 文件 | 说明 | 谁写 |
|---|---|---|
| `btc_config.json` | 主配置。 | 后端/手工 |
| `btc_uiprefs.json` | **UI 偏好**（折叠/模块排序/通知开关/抽屉指标等，多端同步）。 | `/api/uiprefs` |
| `btc_alert_prefs.json` | 告警偏好（历史遗留，可能 deprecated）。 | 旧逻辑 |
| `alert_engine/rules_config.json` | 告警规则启用开关。 | `/api/alert_prefs` |
| `alert_engine/rules_library.json` | 规则清单（名称/级别/方向/族/冷却/是否可评估）。 | `--export-rules` |
| `.binance_trade.json` | 交易 API key/secret（权限敏感，单文件保管）。 | `set_trade_pass.py` |
| `btc_nginx.conf` | Nginx 反代/HTTPS 配置。 | 手工 |
| `*.service` | systemd 服务（采集器/看板/告警 timer）。 | systemd |

---

## 六、部署 / 运行要点

- 看板服务：`systemctl restart btc-data-web.service`（端口 9511）。
- 采集器：`btc-oi-tick.service`、`btc-taker-tick.service` 等，各自 systemd 管理。
- 告警引擎：`btc-alert-engine.timer` 定时触发 `python3 -m alert_engine.run --run`。
- 手机推送：ntfy 内网 `http://127.0.0.1:2587`，外网经 `http://8-217-166-251.sslip.io:2586`。
- 前端 JS 校验：提取 `<script>…</script>` 后 `node --check`。
- 大量 `*.bak.*` / `apply_*.sh` / `patch_*.py` / `*.log` 为历史补丁/备份/日志，**修改请聚焦本表所列核心文件**。

---

## 七、改动前必读（给 AI 的检查清单）

1. 先读本文件认领目标文件职责。
2. 前端改动在 `btc_data_web.py` 的 `HTML_PAGE` 字符串里，注意 JS 反斜杠/unicode 坑。
3. 告警规则改动在 `alert_engine/rules.py`（规则定义）+ `rules_config.py`（中文元数据）+ `persist.py`（下拉详情/通知）。
4. UI 偏好持久化统一走 `prefSet()` → `POST /api/uiprefs`（服务端 `btc_uiprefs.json`），**不要**新增只存 localStorage 的配置。
5. 改完：`node --check` 校验 JS，重启 `btc-data-web.service`，`journalctl -u btc-data-web.service` 看无 traceback，再 `curl` 关键 API 复验。