增加大模型

README.md

@@ -2,43 +2,69 @@
 
 仓库：[Binance_Altcoin_Monitor](https://git.bz121.com/dekun/Binance_Altcoin_Monitor.git)
 
-按 **北京时间 08:00** 切日，统计 U 本位永续合约成交额 Top30；每日 **08:10** 通过企业微信推送昨日完整周期数据；Web 展示昨日快照与今日实时累计。
+按 **北京时间 08:00** 切日，统计 U 本位永续合约成交额 Top30；每日 **08:10** 企业微信仅推送 **三日 Top30 交集** 币种（列表排版，非宽表格）；Web 数据统计页可预览同款推送内容。
+
+> **Linux 生产部署（/opt、Docker、PM2、虚拟环境、SOCKS5 代理、大模型）请参阅 [DEPLOY.md](./DEPLOY.md)**
 
-> **Linux 生产部署（/opt、Docker、PM2、SOCKS5 代理）请参阅 [DEPLOY.md](./DEPLOY.md)**
 ## 功能
 
 - 成交额排名 Top30（USDT 计价）
 - 高亮标记（不改变排名）：成交额 ≥ 1000万 USDT、|涨跌幅| ≥ 5%
-- 昨日周期：`[D-1 08:00, D 08:00)`
-- 今日周期：`[D 08:00, 当前)`，每 **4 小时**后台刷新 + 页脚手动刷新；K线/周期数据服务端 SQLite + 浏览器缓存
-- 数据统计：连续三日 Top30 交集（涨跌幅不限）
-- 大模型解读（`gemma4:e4b`）：每日 **08:05** 对三日交集逐币解读（每币 3 分钟），启动自动一轮；需配置 `LLM_API_KEY`
+- 昨日 / 前日周期：按 08:00 切日固化快照
+- 今日周期：`[D 08:00, 当前)`，后台每 **4 小时**自动刷新 + 页脚 **手动刷新**
+- 日 K + 成交量迷你图，点击 **全屏**查看；K 线优先读服务端 SQLite，浏览器 `localStorage` 缓存约 1 小时
+- 资金费率当前值 + 历史迷你曲线
+- **数据统计**：连续三日均为成交额 Top30 的 **交集**（涨跌幅 **不限**）
+- **大模型解读**（`gemma4:e4b`）：对三日交集币种生成日 K 图 + 数据简析；每日 **08:05** 自动排队，每币间隔 **3 分钟**；服务启动后自动跑一轮（可关）；需在 `.env` 配置 `LLM_API_KEY`
 
 ## 环境要求
 
-- Python 3.10+
-- 可访问 `fapi.binance.com`
-- 企业微信群机器人 Webhook（可选，用于推送）
+- Python 3.10+（**推荐项目内虚拟环境 `.venv`**，PM2 生产亦使用 `.venv`）
+- 可访问 `fapi.binance.com`（国内服务器可配 SOCKS5，见 [DEPLOY.md](./DEPLOY.md)）
+- 企业微信群机器人 Webhook（可选，用于 08:10 推送）
+- 大模型网关（可选）：默认 `http://op.bz121.com`，OpenAI 兼容 `/v1/chat/completions`
 
 ## 快速开始
 
-```bash
+### Windows / 本机开发
+
+```powershell
 # 1. 进入项目目录
 cd 币安排名
 
-# 2. 安装依赖
+# 2. 创建并激活虚拟环境（依赖必须装进 venv，勿只装系统 Python）
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+
+# 3. 安装依赖（含 matplotlib，用于服务端生成日 K 图供大模型）
+pip install -U pip
 pip install -r backend/requirements.txt
 
-# 3. 配置环境变量
+# 4. 配置环境变量
 copy .env.example .env
-# 编辑 .env，填入 WECOM_WEBHOOK_URL
+# 编辑 .env：WECOM_WEBHOOK_URL、LLM_API_KEY 等
 
-# 4. 启动服务（需保持进程常驻）
+# 5. 启动（需保持进程常驻）
 python run.py
 ```
 
+### Linux 本机（与生产一致）
+
+```bash
+cd /path/to/Binance_Altcoin_Monitor
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -r backend/requirements.txt
+cp .env.example .env
+nano .env
+.venv/bin/python run.py
+```
+
 浏览器打开：http://127.0.0.1:21450
 
+> **生产环境**请用 [DEPLOY.md](./DEPLOY.md) 中的 Docker 或 PM2 脚本；PM2 使用 `.venv/bin/python`，更新代码后需执行 `.venv/bin/pip install -r backend/requirements.txt` 再重启。
+
 ## 配置说明（.env）
 
 | 变量 | 说明 | 默认 |
@@ -47,22 +73,39 @@ python run.py
 | `TOP_N` | 排名数量 | 30 |
 | `VOLUME_THRESHOLD` | 高亮成交额阈值 (USDT) | 10000000 |
 | `CHANGE_THRESHOLD` | 高亮涨跌幅阈值 (%) | 5 |
-| `REFRESH_MINUTES` | 今日数据刷新间隔 | 5 |
-| `HOST` / `PORT` | 服务监听 | 127.0.0.1:21450 |
+| `REFRESH_MINUTES` | 今日自动刷新间隔（分钟）；`240` = 每 4 小时 | 240 |
+| `HOST` / `PORT` | 服务监听 | 0.0.0.0:21450 |
 | `PROXY_ENABLED` | 是否启用 SOCKS5 代理 | false |
 | `PROXY_URL` | 代理地址 | socks5h://192.168.8.4:1081 |
 | `PROXY_FOR` | 代理范围 binance/wecom/all | binance |
 | `MAX_CONCURRENCY` | 币安 K 线并发数（过大易 418 封禁） | 3 |
 | `CANDIDATE_POOL` | 预筛候选合约数（按 24h 成交额） | 150 |
 | `CHART_KLINE_LIMIT` | 日 K 存储/展示根数 | 300 |
-| `CHART_CACHE_MINUTES` | 本地日 K 视为新鲜的时间（分钟内不请求币安） | 60 |
+| `CHART_CACHE_MINUTES` | 服务端日 K 视为新鲜的时间（分钟内不请求币安） | 60 |
+| `LLM_BASE_URL` | 大模型网关根地址 | http://op.bz121.com |
+| `LLM_API_KEY` | Bearer 密钥（`sk-...`，勿提交 git） | 空 |
+| `LLM_MODEL` | 模型 ID，须与网关一致 | gemma4:e4b |
+| `LLM_SYMBOL_INTERVAL_SEC` | 批量解读时每币间隔（秒） | 180 |
+| `LLM_AUTO_ON_STARTUP` | 启动后是否自动跑一轮三日交集解读 | true |
+
+完整示例见仓库根目录 [`.env.example`](./.env.example)。
+
 ## API
 
 | 方法 | 路径 | 说明 |
 |------|------|------|
+| GET | `/api/today/top30` | 今日周期 Top30 |
 | GET | `/api/yesterday/top30` | 昨日周期 Top30 |
-| GET | `/api/today/top30` | 今日周期 Top30（缓存） |
-| POST | `/api/push/test` | 手动测试企业微信推送 |
+| GET | `/api/daybefore/top30` | 前日周期 Top30 |
+| GET | `/api/stats/three-day` | 三日 Top30 交集统计 |
+| GET | `/api/chart/{symbol}/daily` | 日 K JSON（SQLite 优先） |
+| GET | `/api/chart/{symbol}/daily.png` | 日 K PNG（大模型/预览） |
+| GET | `/api/funding/{symbol}/history` | 资金费率历史 |
+| GET | `/api/llm/status` | 解读任务状态 |
+| GET | `/api/llm/interpretations` | 最近一批解读结果 |
+| POST | `/api/llm/interpret/run` | 手动启动三日交集解读队列 |
+| GET | `/api/push/preview` | 预览企微推送（三日交集） |
+| POST | `/api/push/test` | 手动测试企业微信推送（仅交集币种） |
 | POST | `/api/refresh/today` | 立即刷新今日数据 |
 | POST | `/api/refresh/yesterday` | 重新计算昨日快照 |
 
@@ -70,11 +113,21 @@ python run.py
 
 | 时间 (北京时间) | 任务 |
 |-----------------|------|
-| 08:00 | 固化昨日周期数据到 SQLite |
-| 08:10 | 企业微信推送昨日 Top30 |
-| 每 N 分钟 | 刷新今日周期（N = REFRESH_MINUTES） |
+| 08:00 | 固化昨日、前日周期快照到 SQLite |
+| 08:05 | 大模型解读「三日 Top30 交集」各币种（需 `LLM_API_KEY`） |
+| 08:10 | 企业微信推送三日 Top30 交集（列表排版） |
+| 每 4 小时（整点 0/4/8/12/16/20） | 刷新今日周期（由 `REFRESH_MINUTES=240` 控制） |
 
-进程重启后：若已过 08:10 且当日尚未推送成功，会自动补推一次。
+进程重启后：若已过 08:10 且当日尚未推送成功，会自动补推；若已配置 `LLM_API_KEY` 且 `LLM_AUTO_ON_STARTUP=true`，会在后台自动启动一轮解读。
+
+## Web 界面
+
+| 页签 | 说明 |
+|------|------|
+| 今日 / 昨日 / 前日 | Top30 表、日 K、资金费率；支持排序与 CSV 导出 |
+| 数据统计 | 三日交集列表 + 大模型解读区；可「开始解读」「刷新解读」 |
+
+今日数据 **不会** 在浏览器里每 60 秒轮询；请依赖 4 小时后台任务或页脚 **「立即刷新今日」**。
 
 ## Windows 常驻运行
 
@@ -93,17 +146,32 @@ curl -X POST http://127.0.0.1:21450/api/push/test
 
 ## 数据说明
 
-- 使用币安合约 `1h` K 线按时间戳聚合 USDT 成交额（第 7 字段）
+- 昨日 / 前日：按 08:00 切日，用 `1h` K 线聚合成交额
+- 今日：默认 `TODAY_DATA_MODE=ticker24h`（单次 API，滚动 24h 口径）
 - 涨跌幅 = (周期末价 - 周期开盘价) / 开盘价 × 100%
-- 今日末价优先使用实时 ticker 价格
+- 日 K：最多 300 根存 `daily_klines`；浏览器 `localStorage` 缓存周期表约 4 小时、K 线约 1 小时
+
+## 依赖说明
+
+所有 Python 包（含 `matplotlib`、`fastapi`、`httpx` 等）写在 [`backend/requirements.txt`](./backend/requirements.txt)：
+
+| 部署方式 | 安装位置 |
+|----------|----------|
+| 本机 / PM2 | 项目目录 **`.venv`**（`pip install -r backend/requirements.txt`） |
+| Docker | 镜像构建时 `pip install`（见 `Dockerfile`） |
+
+**不要**只装到系统 Python：PM2 的 `ecosystem.config.cjs` 指定解释器为 `.venv/bin/python`，系统环境缺包会导致 `No module named matplotlib` 等错误。
 
 ## 目录结构
 
 ```
 币安排名/
-├── backend/app/     # 后端逻辑
-├── web/             # 前端静态页
-├── data/            # SQLite（自动创建）
-├── run.py           # 启动入口
-└── .env             # 本地配置（勿提交）
+├── backend/app/       # 后端逻辑（含 llm_service、chart_image）
+├── backend/requirements.txt
+├── web/               # 前端静态页
+├── data/monitor.db    # SQLite（自动创建）
+├── .venv/             # 虚拟环境（本地/PM2，勿提交）
+├── deploy/            # 一键部署脚本
+├── run.py             # 启动入口
+└── .env               # 本地配置（勿提交）
 ```