feat(设备): 电量显示（大屏 + 监控页）+ 低电量 webhook 告警
需求：大屏和监控页都要能看到每台设备的电量，并且"低于多少电量就发通知"。
数据从哪来：`adb -s <serial> shell dumpsys battery`（**只读**，实测 0.2~0.35s/台，
11 台并发一轮 0.44s）。设备只要在 `adb devices` 里就说明 transport 现成，
**不需要 connect**——所以连空闲设备也能查。这是本模块敢每轮扫全量的前提，
也是这条只读路径与"空闲设备不主动 connect"红线（DEVELOPMENT.md §2 #3）的边界，
已写进文档免得后人误加 connect。
- core/device_battery.py（新）：后台 daemon 线程 `device-battery`（照 device_discovery
的 init_app/shutdown 模式），默认 60s 一轮，采「设备池 ∩ 在线」（与 list_ready 同口径，
adb 可见但不归平台管的设备不上屏也不告警）。
· 结果**只放内存**（不落库 → 不建表、不动备份覆盖清单），离线设备保留最后读数；
· 读失败不清缓存：list_devices 失败时若照清会把整份缓存抹掉、大屏全体变「—」；
· 配置存 `app_meta.device_battery`（照 step_defaults：出厂值 + 白名单 + 范围钳制 +
只落与出厂值不同的字段），改阈值不用重启（线程每轮重读配置）。
- 告警：事件 `device.battery.low` / `device.battery.recovered`（默认关，去通知页勾订阅）。
**按档位做状态沿**（0 正常 / 1 低 / 2 严重）：掉档才报、严重再报一次、恢复报一次；
迟滞 +5% 避免在阈值上下反复告警；同档位每 6h 重复提醒一次。
"充电中"看的是 `status:` 行（2/5），**不是"插着电"**——所以"插着却没充电"
（劣质线/温控/满电停充 status:4）仍会告警，那正是最该知道的情况（实测 fleet 里
就有一台 8% 插着 AC 但 `Max charging current: 0`）。
- GET /api/status 每台设备多一个 `battery`：`{level,charging,at,tier}`。
**tier 由后端算好**，前端只按它上色——阈值只在「工具 → 设备发现 → 电量监控」一处定义，
免得 JS 里再判一遍、两边不一致。
- 前端：大屏卡片型号行右侧加电量徽标（绿/黄/红 + ⚡ 充电中，离线置灰），
`cardHtml`/`renderGrid` 增量更新/脏检查白名单三处都改了（漏一处就不刷新）；
监控页设备表新增可排序的「电量」列（空表 colspan 11 顺带对齐了）。
- 接口：GET/POST /api/devices/battery[/settings] + POST /scan（需设备权限，
与 /api/devices/discovery/* 同权限档）。
自测：单元 30 项（解析真机输出/档位/状态机/钳制，含 scale=255、无 status 行、
垃圾输出等边界）、集成 27 项（临时库自建设备池：缓存/通知/离线保留/删设备清理/
配置往返/阈值改动即时生效）、真实 11 台设备一轮 0.44s 全读到、API 端到端
（登录/权限/钳制/越界/REST 往返/页面 DOM）、两份前端各自语法检查 + 渲染用例。
This commit is contained in:
+11
-1
@@ -169,6 +169,9 @@
|
||||
| POST | `/api/devices/discovery/ignore` | D | 忽略待连接设备 |
|
||||
| POST | `/api/devices/discovery/reconnect` | D | 立即重连指定断联设备 |
|
||||
| POST | `/api/devices/discovery/settings` | D | 保存发现配置 |
|
||||
| GET | `/api/devices/battery` | D | 电量采集器状态 + 生效配置（`{settings, scanning, last_scan:[时间,成功,目标数], cached}`） |
|
||||
| POST | `/api/devices/battery/settings` | D | 保存电量监控配置（越界钳制，返回钳制后的生效值） |
|
||||
| POST | `/api/devices/battery/scan` | D | 立即采集一次（后台执行；上一轮没跑完返回 409） |
|
||||
|
||||
### 2.6 apks（`web/apks_api.py`）
|
||||
|
||||
@@ -321,12 +324,19 @@
|
||||
"serial": "192.168.20.206:5555", "model": "22120RN86C", "device_name": "", "present": true, "ready": true,
|
||||
"worker_status": "running", "task_job": "测试抖音评论", "attempt": 1, "max_attempts": 1,
|
||||
"current_action": "点击搜索", "progress": {"done": 5, "total": 0, "unit": "操作", "elapsed": 42},
|
||||
"foreground_app": "抖音", "last_error": "", "last_warning": "", "end_time": 0
|
||||
"foreground_app": "抖音", "last_error": "", "last_warning": "", "end_time": 0,
|
||||
"battery": {"level": 85, "charging": true, "at": 1700000000.0, "tier": 0}
|
||||
}]}
|
||||
```
|
||||
|
||||
`worker_status`：`idle` / `connecting` / `running` / `done` / `error` / `released` / `failed`。
|
||||
|
||||
`battery`：**后台线程采的缓存值**（默认 60s 一轮，`dumpsys battery` 只读），没采到时为 `null`。
|
||||
`tier` 是**告警档位**（`0` 正常 / `1` 低电量 / `2` 严重），由后端按配置阈值算好——
|
||||
前端只按 `tier` 上色，**不在 JS 里重算阈值**（阈值只在「工具 → 设备发现 → 电量监控」一处定义）。
|
||||
设备离线时保留最后一次读数（`at` 是采集时刻），页面置灰显示。详见 [NOTIFY.md](NOTIFY.md) §3 的
|
||||
`device.battery.low`。
|
||||
|
||||
### GET /api/summary
|
||||
|
||||
```json
|
||||
|
||||
+9
-6
@@ -26,6 +26,7 @@
|
||||
┌───────────────────────────▼──────────────────────────────────────────┐
|
||||
│ 领域层 task_manager（调度） device_worker（执行） device_pool（池） │
|
||||
│ system_backup（备份） apk_manager（应用） device_discovery │
|
||||
│ device_battery（电量采集 + 低电量告警） │
|
||||
└───────────────────────────┬──────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────▼──────────────────────────────────────────┐
|
||||
@@ -79,7 +80,7 @@
|
||||
|------|------|---------|
|
||||
| **B** | `:28-58` | `Flask(__name__)`；会话密钥（`.env` 的 `WEB_SECRET_KEY`，缺失则随机生成并 warning）；`TEMPLATES_AUTO_RELOAD=True`；**数据库目标由 `core/db_config` 装配**（`.env` 的 `DEPLOY_ENV`/`DB_*` → URI + 引擎参数），配置错直接 `SystemExit(2)`；`LoginManager` + `login_view="auth.login"` |
|
||||
| **C** | `:60-67` | **恢复任务消费** `consume_pending_restore()`。SQLite 时代它必须在 engine 首次打开 `users.db` **之前**（Windows 无法替换被持有的文件）；改用 MySQL 后这一步的语义会变成"启动期事务替换"，见 §7 |
|
||||
| **D** | `:69-88` | `init_db(app)`（建表 → 补列 → 版本账本 → 唯一索引 → 默认管理员 → 旧 JSON 迁移）→ `notifier.init_app`（通知 dispatcher/sender 线程）与 `step_log.init_app`（步骤明细写线程）→ **恢复任务消费** `consume_pending_restore()` → **库环境标签校验 + 启动横幅**（`db_config.verify_deployment_label/print_banner`，不符拒绝启动）；`device_pool.init_app`（**起一次性线程**，3s 后采集型号）；`device_discovery.init_app`（**起常驻扫描线程**）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)` |
|
||||
| **D** | `:69-88` | `init_db(app)`（建表 → 补列 → 版本账本 → 唯一索引 → 默认管理员 → 旧 JSON 迁移）→ `notifier.init_app`（通知 dispatcher/sender 线程）与 `step_log.init_app`（步骤明细写线程）→ **恢复任务消费** `consume_pending_restore()` → **库环境标签校验 + 启动横幅**（`db_config.verify_deployment_label/print_banner`，不符拒绝启动）；`device_pool.init_app`（**起一次性线程**，3s 后采集型号）；`device_discovery.init_app`（**起常驻扫描线程**）；`device_battery.init_app`（**起常驻电量采集线程**）；`TaskManager(app=app)`（APScheduler + 看门狗 + 从库加载分组/任务 + 重注册 cron）；`ApkManager(app=app)` |
|
||||
|
||||
### 2.3 阶段 E~G：蓝图、巡检调度器、真正启动
|
||||
|
||||
@@ -87,7 +88,7 @@
|
||||
|------|------|---------|
|
||||
| **E** | `:64-67` | `context.init(...)`；`register_blueprints(app)`（10 个蓝图）；`agent_api.set_app(app)`（供后台线程推 app context） |
|
||||
| **F** | 同上附近 | **第二个独立 APScheduler**：`CronTrigger(hour=3, minute=47)` 挂经验库巡检、`hour=4, minute=13` 挂步骤明细清理（`_purge_step_log`，自建 app context）；失败仅 warning |
|
||||
| **G** | `__main__` | `_ensure_uiauto_running()`（拉起 uiautodev:20242，写 `data/uiauto.pid`，`atexit` 清理）→ `_preconnect_pool_devices()`（后台并发 connect 池内网络设备）→ `_purge_step_log_async()`（后台清理超期步骤明细）→ `_run_server()`（候选端口依次 bind：`0.0.0.0:18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；退出时 `notifier.shutdown()` + `step_log.shutdown()` + `mgr.shutdown()` + `device_discovery.shutdown()` + 停 uiautodev |
|
||||
| **G** | `__main__` | `_ensure_uiauto_running()`（拉起 uiautodev:20242，写 `data/uiauto.pid`，`atexit` 清理）→ `_preconnect_pool_devices()`（后台并发 connect 池内网络设备）→ `_purge_step_log_async()`（后台清理超期步骤明细）→ `_run_server()`（候选端口依次 bind：`0.0.0.0:18050` → `127.0.0.1:18050` → `127.0.0.1:18051..18055`）；退出时 `notifier.shutdown()` + `step_log.shutdown()` + `mgr.shutdown()` + `device_discovery.shutdown()` + `device_battery.shutdown()` + 停 uiautodev |
|
||||
|
||||
> ⚠️ **阶段 A~F 在 import 期就会起线程/调度器**，只有 uiautodev 拉起与预连接在 `__main__` 分支。以 WSGI 方式 import 本模块会得到"半个启动"的进程——本地调试请直接 `python web_server.py`。
|
||||
|
||||
@@ -105,6 +106,7 @@
|
||||
| `worker-watchdog` | `start_watchdog()` | `running/connecting` 心跳超时 → 标 `error` | 30s 检查 / 120s 阈值 |
|
||||
| `device-discovery` | `device_discovery.init_app` | 网段扫描 + 断联重连 | 首轮延迟 15s，之后 interval（默认 60s） |
|
||||
| `_refresh_models_bg` | `device_pool.init_app` | 启动后采集全部在线设备型号 | 一次性（3s 后） |
|
||||
| `device-battery` | `device_battery.init_app` | 采设备电量（`dumpsys battery` 只读）+ 低电量告警 | 首轮延迟 20s，之后 interval（默认 60s） |
|
||||
| `BaseWorker` × N | `TaskManager._run_with_retry` | 单设备任务执行 | 任务期 |
|
||||
| `_run_with_retry` × N | 同上 | 单设备重试循环 | 任务期 |
|
||||
| `fg-scan-once` | `_ForegroundScanner.scan_once` | 前台 App 扫描 | 手动触发，`Event` 防重入 |
|
||||
@@ -127,6 +129,7 @@
|
||||
| `_engine_lock` | `core/ocr.py` | OCR 引擎懒加载 + 推理串行 | 推理 0.2~0.5s，锁开销可忽略 |
|
||||
| `_scan_lock` / `_stop_event` | `core/device_discovery.py` | 定时/手动扫描互斥 | `acquire(blocking=False)` |
|
||||
| `_status_cache_lock` | `core/task_manager.py` | 状态缓存（TTL 5s） | 避免 `/api/status` 每次都查库 + adb |
|
||||
| `device_battery._lock` | `core/device_battery.py` | 电量缓存 `_cache` + 告警档位 `_tiers` | 采集线程 / `/api/status` / 告警状态机共用 |
|
||||
|
||||
**无锁部分**：`device_pool` 与 `models` 不持显式锁，依赖"每次操作独立 app context" + 数据库自身的并发控制（MySQL 下是 InnoDB 行锁 + READ COMMITTED，回退 SQLite 时是 WAL + `busy_timeout=5000`）。
|
||||
|
||||
@@ -267,7 +270,7 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
|
||||
|
||||
### 6.1 单页应用
|
||||
|
||||
- 主页面 `templates/admin/monitor.html`：一个内联 `<style>` + 7 个 Tab 面板 + 7 个模态框容器 + 11 个 `<script src>`
|
||||
- 主页面 `templates/admin/monitor.html`：一个内联 `<style>` + 7 个 Tab 面板 + 10 个模态框容器 + 15 个 `<script src>`
|
||||
- 独立页面：`login.html`（登录）、`wall.html`（监控大屏，**完全自包含**，自带 CSS/JS，不加载 `static/admin/*.js`）
|
||||
- 服务端内联页：`GET /locate`（设备端定位大字页，免登录）
|
||||
- 响应头强制 `no-store`，避免后台改版后浏览器拿旧页面
|
||||
@@ -282,7 +285,7 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
|
||||
| 用户 | `users` | `admin` | — |
|
||||
| 工具 | `tools` | `admin` | `clipboard` / `adb` / `ts` / `apks` / `appver` / `devapps` / `devpool` / `groups` |
|
||||
| AI 控制台 | `agent` | `admin` | — |
|
||||
| 系统 | `system` | `admin` | `backup` 数据备份 / `restore` 导入恢复 |
|
||||
| 系统 | `system` | `admin` | `backup` 数据备份 / `restore` 导入恢复 / `notify` 通知 Webhook |
|
||||
|
||||
子分栏会记住上次选中位置（`_activeSubs`）；`devpool` 子分栏自带 10s 轮询，切走即停。
|
||||
|
||||
@@ -293,10 +296,10 @@ connecting ──获取设备──▶ u2 连接 ──▶ running ──▶ set
|
||||
| `base.js` | esc / CSRF / 权限 / API 封装 / Toast / Tab 与子分栏切换 / 模态框 / 常量表 | 所有模块的公共底座 |
|
||||
| `markdown.js` | 轻量 Markdown 渲染（`renderMarkdown`） | 无 CDN 依赖；**先转义再套标记** |
|
||||
| `list.js` | 统一列表组件：搜索 + 分页 + 排序 | 状态注册表 `_LIST_PAGERS`；`setListPager` **不重置**页码/搜索/排序（避免轮询刷新打断用户） |
|
||||
| `monitor.js` | 监控页：设备表、批量操作、异常汇总、任务概况卡片（含覆盖设备 chip） | 5s 轮询 + 脏检查（签名不变不重渲染） |
|
||||
| `monitor.js` | 监控页：设备表（含**电量列**，按 `battery.tier` 上色）、批量操作、异常汇总、任务概况卡片（含覆盖设备 chip） | 5s 轮询 + 脏检查（签名不变不重渲染） |
|
||||
| `editor.js` | 步骤编辑器（拖拽 / 参数表单 / 条件分支 / 元素抓取 / 测试此步骤）+ `saveTask` | 最大的前端文件；`_stepEditor` 单例 |
|
||||
| `tasks.js` | 任务 Tab：任务 CRUD / 调度解析 / 运行窗口 + 自定义动作 | |
|
||||
| `tools.js` | 工具 Tab：剪贴板、adb 终端、Tailscale、设备池、自动发现、远程看屏 | |
|
||||
| `tools.js` | 工具 Tab：剪贴板、adb 终端、Tailscale、设备池、自动发现、远程看屏、**电量监控配置**（阈值/间隔/立即采集） | 电量表单只回填一次，10s 轮询不冲掉用户正在输的值 |
|
||||
| `apps.js` | 应用管理：APK 上传/安装/删除、设备已装应用 | |
|
||||
| `admin.js` | 分组、日志、用户 + **全局初始化入口**（末尾 `initCsrf(); loadMe(); showTab('monitor')`） | |
|
||||
| `agent.js` | AI 控制台·聊天：会话、SSE 流、Markdown / 推理链 / token 渲染、实时画面、经验库 / 动作库 | |
|
||||
|
||||
@@ -278,6 +278,7 @@ UTF-8 等价于字节序）。
|
||||
| `deployment_claimed_at` | 标签写入时间 | 同上 |
|
||||
| `notify_webhooks` | **通知 / Webhook 全部配置**（JSON：`{version, settings, webhooks[]}`，见 [NOTIFY.md](NOTIFY.md) §4）。**不建表**——新增/删除 webhook 都只改这一个键 | 系统 → 通知 页 |
|
||||
| `step_defaults` | **步骤默认值**（JSON：`{步骤类型: {字段: 值}}`，见 [TASK_DEV.md](TASK_DEV.md) §3.1）。新建步骤时预填用。**只存与出厂值不同的字段**，这样以后调出厂默认能跟着走 | 任务 → 动作配置 页 |
|
||||
| `device_battery` | **电量监控配置**（JSON：`{enabled, low, critical, skip_charging, interval}`，见 [NOTIFY.md](NOTIFY.md) §3.1）。**只存与出厂值不同的字段**（出厂：`low=20 critical=10 skip_charging=true interval=60`）。**电量本身不落库**——只放采集线程的内存缓存（重启重新采一轮），所以没有对应表、不动备份覆盖清单 | 工具 → 设备发现 → 电量监控 |
|
||||
|
||||
> ⚠️ `agent_api_key` 是**明文存储**，导出备份的 zip 里也含它——备份预览会固定给出"含敏感信息"告警。
|
||||
> **同理 `notify_webhooks` 里的 webhook URL 本身就是凭据**（企业微信 `?key=`、钉钉 `?access_token=`、
|
||||
|
||||
@@ -54,6 +54,7 @@
|
||||
| 1 | **绝不 `adb kill-server`** | 会断掉所有设备的 adb transport，运行中任务全废 | `core/adb_helper.py` 只 connect 不 kill；Web 层硬拦截 `kill-server`/`disconnect` 字符串 |
|
||||
| 2 | **绝不对 `IP:5555` 设备 `adb disconnect`** | 该地址的 adb transport 是共享的 | `adb_disconnect` **全项目零调用方**；`STFDevice.release()` 空实现 |
|
||||
| 3 | **空闲设备扫描不主动 connect/disconnect** | 避免扰动共享连接 | 前台扫描对空闲设备直接返回"空闲"；设备发现用 socket 探测 |
|
||||
| 3b | （3 的边界）**只读 `adb -s <serial> shell …` 是允许的**，它不建立/断开 transport | 设备已在 `adb devices` 里就说明 transport 现成，读一下不扰动任何人 | 电量采集 `core/device_battery.py` 就是这么读**包括空闲设备在内**的全部在线设备（`dumpsys battery`，实测 0.2~0.35s/台）；**别"顺手"给它加 connect** |
|
||||
| 4 | **adb key 保持历史 key 不变** | 设备信任该 key，换 key 全部 `unauthorized` | 部署沿用 `~/.android/adbkey` |
|
||||
| 5 | **生产（220）默认只读** | 生产事故成本高 | 任何写操作（pull/重启/改文件）都需负责人确认 |
|
||||
| 6 | **新增持久化表必须进备份覆盖清单** | 漏登记 = 等于没备份 | `SUMMARY_TABLES` 已由模型元数据自动派生（加了 ORM 表就进清单）；**手工要做的只有补 `TABLE_LABELS` 中文标签**，详见 [DEPLOY.md](DEPLOY.md) §5.2 |
|
||||
|
||||
+26
-1
@@ -54,7 +54,7 @@ daemon 线程。所以：
|
||||
| 业务 | `task.selector.invalid`（选择器连续 10 次未命中——"任务成功但什么都没做"的隐蔽故障） |
|
||||
| 业务·任务自己发 | `task.notify.custom`（步骤「发通知」）/ `task.patrol.hit`（任务「公共巡检」命中）——**标题正文由任务自己写**，见下 |
|
||||
| Worker | `worker.connected` · `.attempt.done` · `.attempt.error`（单次尝试级，噪音大，默认没人勾） |
|
||||
| 设备 | `device.online` · `.offline` · `.discovered` · `.claimed` · `device.heartbeat_timeout` |
|
||||
| 设备 | `device.online` · `.offline` · `.discovered` · `.claimed` · `device.heartbeat_timeout` · `device.battery.low` · `.battery.recovered` |
|
||||
| 安装 | `apk.install.started` · `.finished` |
|
||||
| 系统 | `system.backup.exported` · `.imported` · `.restored` · `.restore_failed` · `service.started` · `.stopping` · `user.login` |
|
||||
| AI | `ai.audit.finished` · `.failed` · `.skipped` |
|
||||
@@ -106,6 +106,31 @@ daemon 线程。所以：
|
||||
- 谁能收到仍然只看 webhook 的**事件订阅**：想让某个群收任务自定义消息，就在那条
|
||||
webhook 上勾 `task.notify.custom` / `task.patrol.hit`。
|
||||
|
||||
### 3.1 设备电量告警（`device.battery.low` / `.battery.recovered`）
|
||||
|
||||
采集与判定都在 `core/device_battery.py`（后台线程 `device-battery`，默认 60s 一轮，
|
||||
`adb -s <serial> shell dumpsys battery` **只读**查询）。阈值配置在
|
||||
**「工具 → 设备发现 → 电量监控」**，存在 `app_meta.device_battery`（见 [DATA_MODEL.md](DATA_MODEL.md) §5）。
|
||||
|
||||
阈值语义（**这是唯一判定处，前端只读后端算好的 `tier` 上色**）：
|
||||
|
||||
| 档位 | 条件 | 通知 |
|
||||
|---|---|---|
|
||||
| `0` 正常 | `电量 >= 低电量阈值 + 5`（迟滞）或 充电中 | 从低/严重回到 0 → 发 `device.battery.recovered` |
|
||||
| `1` 低 | `严重阈值 < 电量 <= 低电量阈值` | **掉到这一档才发** `device.battery.low`（`warning`） |
|
||||
| `2` 严重 | `电量 <= 严重阈值` | 掉到这一档再发一次（`error`），阈值字段是严重阈值 |
|
||||
|
||||
- **迟滞 +5**：回升要到 `低电量阈值 + 5` 才算恢复。没有它，电量在阈值上下浮动
|
||||
（充电器接触不良）会反复告警。
|
||||
- **"充电中"看的是 `status:` 行**（`2` 充电中 / `5` 已充满），不是"插着电"。
|
||||
所以**"插着却没充电"**（劣质线、温控停充、满电停充 `status:4`）**仍然会告警**——
|
||||
那正是最该让人知道的情况。想连充电中一起报，把「充电中不告警」勾掉即可。
|
||||
- **重复提醒**：同一档位持续不恢复时，每 **6 小时**再提醒一次（`core/device_battery.RE_NOTIFY_S`）。
|
||||
- 只对**「设备池 ∩ 在线」**的设备告警：adb 里能看到但不归平台管的设备不吵人。
|
||||
- 一周内改了阈值**不用重启**：采集线程每轮重读配置，档位下一轮就按新阈值算。
|
||||
|
||||
排查：`logs/core.log` 搜 `core.battery`（每轮一行「电量采集完成: N/M 台」）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 配置
|
||||
|
||||
Reference in New Issue
Block a user