tmdx 3.0.0__tar.gz

tmdx-3.0.0/.gitattributes

@@ -0,0 +1,6 @@
+# Windows 批处理脚本必须用 CRLF 行尾。
+# LF 行尾的 .bat 在含多行 if (...) 块时可能被 cmd 解析异常。
+# 另外 scripts/verify-token/verify-token.bat 必须保持纯 ASCII
+# （cmd 解析含 GBK 中文的批处理会字节错位，实测复现），
+# 中文提示一律放在同目录的 verify_token.py 里输出。
+*.bat text eol=crlf

tmdx-3.0.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # 项目核心场景是读取 Windows 通达信安装目录下的 .day 文件，
+        # 路径分隔符 / GBK 文件名 / tzdata 时区行为在 Windows 上与 Linux 不同，
+        # 故补充 Windows 矩阵覆盖这些平台特有路径。
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      # 纯 Python 包（pyproject 已移除 force-include），无需 Node / 前端产物。
+      - run: pip install -e ".[dev]"
+      - run: pip install -r requirements-dev.txt
+      - run: python -m pytest tests/unit/ -v --tb=short --cov src/easy_tdx --cov-fail-under=60
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      # 同 test job：纯 Python 包，无需 Node。
+      - run: pip install -e ".[dev,web]"
+      - run: mypy src/
+
+  # 前端构建检查。web-ui 此前只有本地 vue-tsc，CI 不覆盖，
+  # 类型错误 / 破坏性 import 只有发布后用户才发觉（v1.17.9 的
+  # 65409694% 离谱数值 bug 即前端无回归守卫的典型后果）。
+  # 与 Python 版本无关，故独立 job，避免在 test matrix 里跑 6 遍。
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web-ui/package-lock.json
+      - run: npm ci
+        working-directory: web-ui
+      - run: npm run build
+        working-directory: web-ui
+      # Playwright E2E（mock 模式）：serve 托管刚构建的 dist，行情全部来自
+      # EASY_TDX_E2E_MOCK=1 合成数据，不连真实通达信服务器、不受交易时段限制。
+      # 需要 Python 侧 tmdx[web]（webServer 用系统 python 启动 serve）。
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[web]"
+      - run: npx playwright install --with-deps chromium
+        working-directory: web-ui
+      - run: npm run test:e2e
+        working-directory: web-ui
+        env:
+          EASY_TDX_PYTHON: python

tmdx-3.0.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      # 纯 Python wheel：pyproject.toml 已移除 hatchling force-include，
+      # 不再需要 Node / 前端产物，干净 checkout 即可构建（不会出现
+      # FileNotFoundError 硬崩）。前端 UI 走 Docker / EXE（release.yml）分发。
+      - run: pip install build
+
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # sigstore provenance 签名认证。OIDC 服务（GitHub Actions → sigstore）
+          # 偶发 503 overflow 故障时会让整个 publish 失败，故暂时关闭；
+          # 待服务稳定后再改回 true。上传本身用 OIDC trusted publishing，无需 API token。
+          attestations: false

tmdx-3.0.0/.github/workflows/release.yml

@@ -0,0 +1,94 @@
+name: Release EXE
+
+# 打 tag 时构建 Windows 单 EXE 并发布到 GitHub Release。
+# 与 publish.yml（PyPI）并行独立：即使 PyPI 发布失败，EXE 仍可发布，
+# 提高发布韧性。Phase 1 产物未签名，老人首次运行会被 SmartScreen 拦截，
+# 需手动"更多信息 → 仍要运行"——Phase 2 引入代码签名后解决。
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write  # softprops/action-gh-release 创建 Release 需要
+
+jobs:
+  build-windows:
+    name: Build Windows EXE
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web-ui/package-lock.json
+
+      # 构建前端 → web-ui/dist/。必须在 pip install 前：easy_tdx.spec 要把
+      # web-ui/dist 收进 EXE 的 easy_tdx/web/dist/，缺失则打出的 EXE 没有 UI。
+      - name: Build frontend
+        run: |
+          npm ci
+          npm run build
+        working-directory: web-ui
+
+      # 安装后端（含 [web,packaging] extras：fastapi/uvicorn + pystray/Pillow）
+      - name: Install Python deps
+        run: |
+          pip install -e ".[web,packaging]"
+          pip install pyinstaller
+
+      - name: Build EXE
+        run: pyinstaller easy_tdx.spec --noconfirm
+
+      # 重命名为带版本号的文件名，方便老人下载时识别
+      - name: Rename EXE with version
+        shell: bash
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          mv dist/tmdx.exe "dist/tmdx-${VERSION}-windows.exe"
+          ls -lh dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: tmdx-windows-exe
+          path: dist/tmdx-*-windows.exe
+          if-no-files-found: error
+
+  release:
+    name: Publish GitHub Release
+    needs: build-windows
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: tmdx-windows-exe
+          path: dist
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/tmdx-*-windows.exe
+          generate_release_notes: true
+          body: |
+            ## 下载使用
+
+            1. 下载下方 `tmdx-*-windows.exe`（约 80-150MB）
+            2. 双击运行
+            3. 浏览器会自动打开回测界面（地址 `http://localhost:8000`）
+
+            ## ⚠️ SmartScreen 提示
+
+            本版本未做代码签名，首次运行 Windows 会弹出"已保护你的电脑"：
+
+            1. 点击 **更多信息**
+            2. 点击 **仍要运行**
+
+            Phase 2 将引入代码签名消除此提示。

tmdx-3.0.0/.gitignore

@@ -0,0 +1,47 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg
+.venv/
+venv/
+.omc/
+.claude/
+.playwright-mcp/
+docs/_build/
+FK/
+
+# 测试覆盖率与运行时产物
+.coverage
+signals.json
+
+# 本地独立脚本（不属于 easy_tdx 库，依赖外部 unified_config / sqlalchemy）
+src/easy_tdx/exchange_margin.py
+
+# 本地文件，不递交到 GitHub
+CLAUDE.md
+
+# 本机包管理缓存（沙箱环境下避开 AppData 路径，落在项目内）
+.npm-cache/
+.uv-cache/
+
+# 代码审计报告（本地产物，不入库）
+audit-report-*.html
+
+*.log
+.workbuddy/
+# Playwright E2E 运行产物（trace/截图/视频）与临时配置目录
+web-ui/e2e/.results/
+web-ui/test-results/
+web-ui/playwright-report/
+
+# ZCode agent 会话目录（本地，不入库）
+.zcode/
+
+# PyPI token 本地暂存（scripts/verify-token 用）—— token 一旦入库即等于泄漏
+scripts/verify-token/token.txt

tmdx-3.0.0/.readthedocs.yaml

@@ -0,0 +1,18 @@
+# .readthedocs.yaml
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: docs/requirements.txt

tmdx-3.0.0/API_QUICKSTART.md

@@ -0,0 +1,254 @@
+# tmdx API 快速试用指南
+
+服务已在本地启动：**http://127.0.0.1:8000**
+在线调试（Swagger UI，可直接点）：**http://127.0.0.1:8000/docs**
+
+> 所有路由挂在 `/api/v1` 前缀下。
+> 当前为非交易时段，**今日分时（09:30 开盘后才有）现在为空**；
+> 想立刻看到数据请用历史日期参数，例如 `date=20260814`（该日各市场均返回 240 行）。
+>
+> **板块异动检测（第 8、9 节）新增「快照记录器」主线**：服务启动时后台常驻循环，每 15s 拉一次**全量**板块列表并缓存 `change_pct` 时序（环形缓冲，默认 3 分钟 = 12 点窗口）。
+> 交易时段（09:30–15:00 工作日）内，`board-pullup` 优先读这条快照序列算板块涨速（全量不截断 → **水下拉升也能报警**）；非交易时段或快照为空时自动回退到「板块列表 + 批量分时」路径。
+> 可用第 9 节 `/screen/board-snapshot/status` 确认记录器是否在采、已采点数。
+
+---
+
+## 1. 批量分时（本项目新增）`GET /api/v1/minute/batch`
+连接池并发直连通达信，N 只耗时约为逐只串行的 `1/pool_size`。
+
+- `codes`：逗号分隔。**可纯代码（按前缀自动识别市场）** 或显式 `市场:代码`
+  - `600000`→SH、`000001`/`300750`→SZ、`880550`→SH 板块指数、`830799`/`920002`→BJ
+  - 非法代码（非 6 位）→ HTTP 400 清晰提示
+- `date`：可选 `YYYYMMDD`，省略=今日分时
+- `pool_size` / `max_concurrency`：并发池大小（默认 6 / 8）
+
+```bash
+# 历史批量（自动识别 4 个市场）
+curl "http://127.0.0.1:8000/api/v1/minute/batch?codes=600000,000001,880550,300750,920002&date=20260814"
+
+# 今日批量（开盘后才有数据）
+curl "http://127.0.0.1:8000/api/v1/minute/batch?codes=600000,000001,880550"
+
+# 混合显式指定市场
+curl "http://127.0.0.1:8000/api/v1/minute/batch?codes=SH:600000,SZ:000001"
+```
+返回：`{ "data": { "<code>": [ {datetime, price, vol}, ... ] } }`，失败的 code 对应空列表。
+
+## 2. 单只今日分时 `GET /api/v1/minute`
+```bash
+curl "http://127.0.0.1:8000/api/v1/minute?market=SH&code=600000"
+```
+
+## 3. 单只历史分时 `GET /api/v1/minute/history`
+```bash
+curl "http://127.0.0.1:8000/api/v1/minute/history?market=SH&code=600000&date=20260814"
+```
+
+## 4. 涨速排行（真·涨速 SPEED_PCT）`GET /api/v1/mac/quote-list`
+```bash
+# 主板涨速前 5（排除科创/创业/北交/ST）
+curl "http://127.0.0.1:8000/api/v1/mac/quote-list?sort_type=SPEED_PCT&category=A&exclude=KC,CY,BJ,ST&count=5"
+
+# 全市场涨速前 20
+curl "http://127.0.0.1:8000/api/v1/mac/quote-list?sort_type=SPEED_PCT&count=20"
+```
+> 单看涨速排序前几名常混入「深跌反弹 / 无量脉冲」假阳性，建议组合：
+> `change_pct>0`(本地算) + `vol_ratio>=1.5` + `amount` 阈值 + `exclude`，
+> 或先用本接口取候选池 → 批量拉分钟 → 用 `detect_minute_pullup` 算斜率+R²+量能。
+
+## 5. K 线（支持复权）`GET /api/v1/bars`
+```bash
+curl "http://127.0.0.1:8000/api/v1/bars?market=SH&code=600000&category=DAY&count=100"
+# category: MIN_1/MIN_5/DAY/WEEK/MONTH ...  adjust: NONE/QFQ(默认)/HFQ
+```
+
+## 6. 昨日板块排行 `GET /api/v1/board-mac/change-ranking`
+```bash
+curl "http://127.0.0.1:8000/api/v1/board-mac/change-ranking?target_date=20260814&days=1&count=5"
+```
+
+---
+
+### 7. 盘中拉升扫描（一步到位）`GET /api/v1/screen/pullup`
+把「涨速候选池 → 批量拉分钟 → 斜率+R²+量能判定」串成一步，看盘页直接轮询即可。
+
+- `window`：**分钟级别（3 或 5 最常用）**，取最近 N 分钟判定
+- `candidates`：涨速候选池大小（取涨速前 N 只）
+- `min_speed_pct`：候选池涨速下限过滤（可选，单位 %/分钟）
+- `date`：省略=**今日分时（盘中实时）**；传 `YYYYMMDD` 测历史
+- `only_alerts`：默认 true，只返回命中 `is_pullup`/`is_rising_alert` 的标的
+- 阈值：`slope_pct_thresh`/`r2_thresh`/`vol_spike_thresh`/`peak_slope_thresh`/`pullback_tol_pct`/`jump_ratio_thresh`
+
+```bash
+# 盘中实时（最简：5 分钟级，只返回报警标的）
+curl "http://127.0.0.1:8000/api/v1/screen/pullup?window=5"
+
+# 3 分钟级别 + 涨速前 20 候选 + 看全部（不只报警）
+curl "http://127.0.0.1:8000/api/v1/screen/pullup?window=3&candidates=20&only_alerts=false"
+
+# 历史回测验证（非交易时段今日分时空，用历史日）
+curl "http://127.0.0.1:8000/api/v1/screen/pullup?window=5&candidates=10&date=20260814&only_alerts=false"
+```
+返回列：`code/name/speed_pct/slope/slope_pct/window_pct/r2/vol_spike/peak_slope_pct/peak_r2/pullback_from_peak_pct/jump_full/jump_rise/is_pullup/is_rising_alert/reason`，按 `peak_slope_pct` 降序。
+
+### 8. 板块/概念拉升扫描（一步到位）`GET /api/v1/screen/board-pullup`
+逻辑同 `screen/pullup`，但针对**板块/概念指数**。默认扫**概念(GN)**。
+
+**新版数据路径（快照记录器主线）**：交易时段内优先读后台每 15s 采集的**全量**板块 `change_pct` 时序，对每只板块用最近 `window` 分钟算板块涨速（= change_pct 序列斜率，%/min，天然绕开协议 `rise_speed` 永远为 0 的盲区），**全量不截断** → 水下翻红拉升的板块也能报警。非交易时段或快照为空时自动回退「板块列表 + 批量分时」路径。
+
+- `board_type`：板块类型，`GN`=概念(默认) / `HY`=行业 / `ALL`=全部
+- `window`：**判定窗口（分钟级），默认 3**（=12 个采集点 @ 15s）。`window=1` 更快更噪，`window=5` 更稳更慢
+- `candidates`：回退路径下扫描板块数（取当日涨幅前 N 只板块作候选）
+- `min_change_pct`：候选板块当日涨幅下限过滤（可选，%）
+- `date`：省略=今日分时（盘中实时，走快照路径）；传 `YYYYMMDD` 测历史（走回退路径）
+- `only_alerts`：默认 true，只返回命中报警的板块
+- 阈值参数同 `screen/pullup`
+
+```bash
+# 概念板块实时（默认 GN，3 分钟级，只报警）—— 水下拉升也能抓
+curl "http://127.0.0.1:8000/api/v1/screen/board-pullup?board_type=GN&window=3"
+
+# 看全部候选（不只报警）
+curl "http://127.0.0.1:8000/api/v1/screen/board-pullup?board_type=GN&window=3&only_alerts=false"
+
+# 行业板块 + 3 分钟级 + 看全部候选
+curl "http://127.0.0.1:8000/api/v1/screen/board-pullup?board_type=HY&window=3&candidates=20&only_alerts=false"
+
+# 历史回测（概念，20260814）
+curl "http://127.0.0.1:8000/api/v1/screen/board-pullup?board_type=GN&window=3&candidates=20&date=20260814&only_alerts=false"
+```
+返回列：在个股版基础上增加 `rise_speed`/`change_pct`（板块列表快照字段）。
+> 注：板块列表 `rise_speed` 字段实测恒为 0，候选排序统一按 `change_pct`（当日涨幅），实时/历史均稳定。
+> 注：本端点阈值**默认按板块标定**（slope/peak=0.03、r2=0.4、pullback=1.5、jump=1.5），比个股端点松约 10 倍——板块指数不可能像个股那样 5 分钟拉 2.5%。个股端点仍是原默认（0.5/0.7/1.5…）。
+> 注：**板块检测默认不要求量能**（快照路径无量能字段、回退路径 `require_vol=false`，两条路径口径一致），量能不参与决策；如需重新启用量能门槛传 `require_vol=true`。个股 `/screen/pullup` 仍保留"带量"硬门槛。
+> 注：`only_alerts` 默认 true（只返报警），想看全部候选加 `only_alerts=false`。极个别板块因子TDX多主机数据覆盖差异可能取不到分时（非接口bug）。
+
+---
+
+### 9. 板块快照记录器调试 `GET /api/v1/screen/board-snapshot/status` & `/board-series`
+配合第 8 节的快照记录器主线使用，便于确认采集状态与排查空数据。
+
+```bash
+# 记录器运行状态：是否 running、采集间隔、各类型已采板块数/总点数
+curl "http://127.0.0.1:8000/api/v1/screen/board-snapshot/status"
+
+# 某板块的 change_pct 时序（调试用，code 换成关心的板块代码）
+curl "http://127.0.0.1:8000/api/v1/screen/board-series?board_type=GN&code=880520"
+```
+- `status` 返回示例：`{"running": true, "interval_sec": 15, "board_counts": {"GN": 269, "HY": 124, "DQ": ...}, "last_update": 1692...}`
+  - 非交易时段 `running` 仍为真，但 `board_counts` 为空（按设计不采集，不是 bug）。
+- `board-series` 返回该板块按时间排列的 `{ts, change_pct}` 序列；无数据时返回空 `data:[]`（不报错）。
+
+---
+
+### 10. 实时分时 SSE 推送 `GET /api/v1/minute/sse`
+
+把「前端每次现场拉 TDX」改为「后台采集器按默认 5s（且可被连接的 `interval` 参数动态拉低）拉并集存内存，SSE 只推增量」。
+与 `/minute/batch` 对称，但无前端等待、带宽极小、支持前端动态增删。
+
+```bash
+# 基本用法（混传个股+板块/概念指数；前端用 EventSource 长连，curl 用 -N 看流）
+curl -N "http://127.0.0.1:8000/api/v1/minute/sse?codes=600000,000001,880520"
+
+# 单连接 codes 上限（默认 150，超出请分批/重连）
+curl -N "http://127.0.0.1:8000/api/v1/minute/sse?codes=600000,880520&max_per_conn=150"
+```
+
+- 事件流：`snapshot`（首连全量分时）→ 每轮 `tick`（按「当日分钟序号 `idx`」推送新增点；**正在形成的分钟 bar 价量变化也会补推**，故盘中持续有增量，不只在整分钟切换时）或 `heartbeat`（无更新保活）。
+- 动态增删：前端改集合后**重连**并带新 `codes`（旧连接自动退订），标准 `EventSource` 原生支持，无需 POST 控制通道。
+- 兼容个股 / 板块指数 / 概念指数（`880xxx`/`881xxx` 协议层自动识别为 SH）；**不展开成分股**——传什么推什么。
+- 后台 `MinuteBroadcastHub` 每次采集用**临时连接池**（与 `/minute/batch` 同款，默认 16 并发、上限 24）现场拉「所有连接订阅并集」存内存；
+  多连接共享采集、各自独立游标，互不干扰；并集全局上限 500。
+- 演示页：项目根 `sse_demo.html`，浏览器打开输入 codes 即可实时看分时/涨速，改集合点按钮即重连。
+
+> 注：非交易时段也会拉取当日收盘分时（静态），演示与盘中逻辑一致；盘中自动变实时更新。
+
+---
+
+### 11. 异动拉升 SSE 推送（个股 + 板块）`GET /api/v1/screen/sse/pullup` & `/screen/sse/board-pullup`
+
+把「前端轮询 `screen/pullup`/`board-pullup`」升级为**后台持续扫描 + 增量事件推送**。新增内容（snapshot 全量 / alert 新触发 / 失败 heartbeat）与分时 SSE（snapshot / tick / heartbeat）同构，下游消费逻辑一致。
+
+| 接口 | 默认扫描频率 | 检测数据源 |
+|---|---|---|
+| `GET /api/v1/screen/sse/pullup`（个股） | `interval=10`s | 每轮现拉涨速前 N 候选股批量分时、逐只算 |
+| `GET /api/v1/screen/sse/board-pullup`（板块/概念） | `interval=15`s | 默认读后台快照记录器（15s 一刷，零成本） |
+
+> **频率关键差异**：个股端点每轮都**现拉现算**，`interval` 直接决定新鲜度（可设 3–60s）；板块端点默认读「快照记录器」（每 15s 采一次的全量板块 `change_pct` 时序），底层粒度固定 15s，**把 SSE `interval` 调更低只会重复推同一份快照**——建议保持 15s。仅当 `use_snapshot=false`（历史回放/刚启动/强制实时）才走现拉回退路径，那时 `interval` 才控制新鲜度。
+
+**事件流（每轮 push）**
+- `snapshot`：当前命中标的**全集**，前端整体替换展示。
+  `{"ts": <epoch>, "interval": <int>, "data": [ {记录}, ... ]}`
+- `alert`：仅**状态翻转**（非异动→异动）的新触发标的才推，自动去重防刷屏；**首次连接只建基线、不补历史 alert**。
+  `{"ts": <epoch>, "data": {单条记录}}`
+- `history`：**仅当 `receive_all_at_first=true` 且为首次事件**时推一条：今日已存储的全部 alert 历史（按 `code` 去重、每标保留最新记录）。
+  `{"ts": <epoch>, "count": <int>, "data": [ {记录含 stored_at}, ... ]}`
+  - 所有 SSE 连接实际推送出去的 `alert` 都会**同步存入服务端内存日报**（跨连接共享）；
+  - 数据**次日 09:00 自动过期清空**（对齐交易日开盘前）；
+  - 传 `receive_all_at_first=true` 重连/换设备时即可拿到「今天到目前为止所有触发过异动的标的」。
+- `heartbeat`：仅**单轮扫描异常**时发 `{"ts":.., "kind":"scan_failed", "error":"...", "note":"本轮…失败，下轮自动重试（连接未断开）"}`。正常轮不发 heartbeat，连接持续不断。
+
+> 下游**必须按 `event:` 字段路由**（用 `addEventListener('snapshot'/'alert'/'heartbeat')`），用 `EventSource.onmessage` 会静默丢增量。
+>
+> **避免 N 分钟内重复提示**：`alert` 事件已按「状态翻转」去重（持续报警期间每轮不再重推）；但若个股/板块在阈值边缘反复横跳（滑动窗口导致 `is_pullup`/`is_rising_alert` 退→进），会再次触发。可传 `alert_cooldown`（秒，如 300=5 分钟）抑制冷却期内同标的重触发。最佳实践：**通知只消费 `alert` 事件、`snapshot` 仅用于列表展示**，且前端再叠加一个按 `code` 的本地冷却字典最稳。
+> 注：早期版本 `alert` 事件因 `prev_hit` 在更新 `active_since` 之后才快照，导致 `alert` 永不触发（实际只有 `snapshot` 每轮推送）——该 bug 已修复，现在 `alert` 仅在状态翻转时正确推送。
+
+```bash
+# 个股异动 SSE（盘中实时，默认 10s 扫一次）
+curl -N "http://127.0.0.1:8000/api/v1/screen/sse/pullup?window=5"
+
+# 个股异动 SSE，3 分钟级 + 5s 高频
+curl -N "http://127.0.0.1:8000/api/v1/screen/sse/pullup?window=3&interval=5"
+
+# 板块/概念异动 SSE（默认 GN 概念，15s，读快照）
+curl -N "http://127.0.0.1:8000/api/v1/screen/sse/board-pullup?board_type=GN&window=3"
+
+# 收盘/联调用 mock 模拟数据（不连真实行情）
+curl -N "http://127.0.0.1:8000/api/v1/screen/sse/pullup?mock=true"
+curl -N "http://127.0.0.1:8000/api/v1/screen/sse/board-pullup?mock=true"
+
+# 抑制闪烁重触发：同一标的 5 分钟内只提示一次（alert_cooldown 单位秒）
+curl -N "http://127.0.0.1:8000/api/v1/screen/sse/pullup?window=5&alert_cooldown=300"
+
+# 开局补全：首连推 history 事件（今日已存储的全量 alert 历史），后续只发增量
+curl -N "http://127.0.0.1:8000/api/v1/screen/sse/pullup?receive_all_at_first=true"
+curl -N "http://127.0.0.1:8000/api/v1/screen/sse/board-pullup?receive_all_at_first=true"
+
+# 查看 alert 日报存储状态（过期时间/事件数/去重标的数）
+curl "http://127.0.0.1:8000/api/v1/screen/alert-store/status"
+```
+
+**记录字段（两种端点通用）**
+
+| 字段 | 含义 |
+|---|---|
+| `code` / `name` | 代码 / 名称 |
+| `slope` / `slope_pct` | 绝对斜率(元/分钟) / **相对涨速**(%/分钟)，驱动 `is_pullup` |
+| `window_pct` | 窗口累计涨幅 % |
+| `r2` | 价格回归**拟合优度**（越高越「线性陡峭」，排除一笔脉冲后走平） |
+| `vol_spike` | 量能脉冲 = 近窗均量/基准均量（个股端点要求 >1.5 才算带量） |
+| `peak_idx` | 窗口内最高价位置 |
+| `peak_slope_pct` / `peak_r2` | 峰值段涨速(%/分钟) / 拟合优度，驱动 `is_rising_alert` |
+| `pullback_from_peak_pct` | 距峰值回撤 %（负=已回落） |
+| `jump_full` / `jump_rise` | 单步脉冲护栏（单分钟涨幅占整体比例，识别「一笔脉冲」假拉升） |
+| `is_pullup` | 持续强势：斜率+R²+量能三者同时达标，此刻仍在持续陡峭拉升 |
+| `is_rising_alert` | 正在猛拉/刚拉完报警：窗口内出现过陡峭线性段且回撤可控，**更早更宽容** |
+| `reason` | `is_pullup` 未达标说明（如「量能未放大」）；达标则「满足全部条件」 |
+| `started_at` / `started_at_ts` | SSE 层附加：本连接**首次**命中时间（用于显示「已拉升 N 秒」） |
+
+**板块记录额外字段**：`change_pct`（板块涨跌幅）、`rise_speed`/`speed_per_min`（板块涨速 %/分钟）。板块端点默认 `require_vol=false`——板块分时无量能字段、量能噪声大，**量能不参与判定**，`reason` 不会报「量能未放大」。
+
+**判定逻辑意义**：`is_pullup`=真金白银在推（持续涨 + 线性 + 放量）；`is_rising_alert`=只要在窗口内出现过一段陡峭线性拉升、且之后回撤 ≤ `pullback_tol_pct` 就报警，比 `is_pullup` 更早触发，适合「正在猛拉的那几秒就提醒」。二者可同时真（持续拉升中），也可仅 `is_rising_alert` 真（拉过一波后小幅回落）。
+
+> 板块端点阈值默认按板块量级标定得更宽松：涨速 `0.03`%/min、`r2` 下限 `0.4`、回撤容忍 `1.5`%、`jump=1.5`，比个股端点（0.5/0.7/1.5/0.9）松约 10 倍——板块指数不可能像个股那样 5 分钟拉 2.5%。
+> 别名 `/screen/pullup/stream`、`/screen/board-pullup/stream` 同上。演示页见项目根 `pullup_sse_demo.html`。
+
+---
+
+## 启动 / 停止
+```bash
+# 启动（需要 tmdx[web]，已装在系统 Python 3.12）
+python -m easy_tdx.cli serve --host 127.0.0.1 --port 8000 --no-open-browser
+# 等价：tmdx serve
+```
+当前实例由后台任务托管，Ctrl+C 或结束进程即可停止；如需重启按上面命令即可。