auto_control/doc/DEVELOPMENT.md

# 开发手册（DEVELOPMENT）

面向本项目开发者：开发流程、git 工作流、环境说明、技术红线、本地开发、常见开发任务。

---

## 1. 开发流程与 git 工作流

### 1.1 分支策略

| 分支 | 用途 |
|------|------|
| `dev` | **开发分支**，所有新功能/修复都在这里开发 |
| `main` | **生产分支**（主分支），只放已确认的稳定版本 |

生产环境 = 部署机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（python-app 容器运行 `web_server.py`）。

### 1.2 git 操作铁律（重要）

**所有 git 操作都必须先经项目负责人明确确认后才能执行**，包括但不限于：

- `commit` / `push`（**即使 push 到 dev 也要确认**）
- `merge`（dev → main）
- `revert` / `checkout` / `reset` / `branch -D` 等

**标准流程：**

```
1. 在 dev 分支开发、本地测试
2. 完成改动 → 把改动清单 + 建议 commit 信息 列给负责人
3. 负责人确认 → 才能 commit + push dev
4. 需要发布 → 负责人确认后再合并到 main
5. 部署生产 → 负责人明确指示后才 pull 到 220
```

> 不允许"开发完顺手就 commit/push"。即使是一次性小改动，也要先确认。

---

## 2. 环境说明

| 环境 | 位置 | 说明 |
|------|------|------|
| 开发机 | 本机（192.168.20.57） | `.venv` + 本地运行 `web_server.py` |
| 生产机 | 部署机 220 的 `auto_control` | python-app 容器，`network_mode: host` |
| STF 服务 | ~~`192.168.20.220:7100`~~ | 已停用（2026-08-18 `docker stop stf`，代码已摘除依赖） |
| adb 容器 | 220 上 `adb`（host 网络 5037） | USB 设备远程 adb server；网络设备补连用 |
| 设备 | Tailscale `100.100.10.x:5555` | Xiaomi 舰队，本机 `100.100.10.2` 在 tailnet 内 |
| uiautodev | 本机 `20242` | 元素抓取服务（web_server 自动拉起） |

### 2.1 adb key（关键）

- 本机 `~/.android/adbkey` 沿用历史 key（原取自 STF adb 容器，全部设备都信任）
- **不要随意更换 key**——设备会变 unauthorized 连不上
- 旧 key 备份在 `~/.android/adbkey.local.bak`
- 生产环境的容器也需要用这把 key（部署时处理）

### 2.2 设备连接方式

- 设备 serial 是 `IP:5555`（Tailscale 地址），**直连**优先（只 connect、绝不 disconnect）
- USB 设备（serial 无冒号）：插本机走本地 adb；插 220 走远程 adb server（`USB_ADB_HOST:5037`）
- 本机已在 tailnet 内，直连可靠且快（<1s）
- 设备加入/退出平台：工具 → 设备池管理（SQLite 清单，自动连接 + 型号采集）

---

## 3. 技术红线（开发限制）—— 违反会打断共享 adb transport，需人工恢复

这些是踩过坑后总结的，**任何修改都不能引入**。违反任何一条都会导致设备连接被全部重建（历史原因：STF provider 共享同一 adb transport，摘除 STF 后仍保留此约束）：

1. **绝不 `adb kill-server`**
   - 会断开所有设备的 adb transport，全部设备连接被重建，运行中任务中断
   - 见 `core/adb_helper.py`

2. **绝不对 `IP:5555` 设备 `adb disconnect`**
   - 该地址的 adb transport 是共享的（历史与 STF provider 共用），disconnect 会断掉全部相关连接
   - 直连模式下 `release()` 不 disconnect
   - 见 `core/device_worker.py` `STFDevice.release()`

3. **空闲设备扫描不主动 connect/disconnect**
   - IP:5555 的 transport 由多方共享（历史与 STF provider 共用），外部 connect/disconnect 会扰动共享连接
   - `_ForegroundScanner._scan_free` 对空闲设备直接返回"空闲"，不碰 adb
   - 见 `core/task_manager.py`

4. **adb key 保持历史 key 不变**（见 2.1，设备信任该 key）

5. **直连优先，不引入第三方桥接**（见 2.2）

### 3.1 其他开发限制

- **`web_server.py` 以 `debug=False` 运行，不热重载**：改 `core/`、`tasks/`、`templates/`、`static/` 后必须重启 web_server（前端 HTML 改完强刷浏览器）
- **任务参数放各自 `tasks/<app>/task.py` 顶部，不放 `config.py`**
- **生产环境（220）默认只读**：任何写操作（改文件/重启容器/部署）都必须先经负责人确认
- **数据库是 SQLite**（`data/users.db`，WAL 模式）：运行时数据不提交 git
- **前端 JS 在 `static/admin/monitor.js`**（已从 HTML 拆分），HTML 里用 `<script src>` 引用
- **监控页/大列表已加分页**：100 台设备也只渲染 10 行/页，不要移除分页逻辑
- **任务批量触发已错峰**（`_START_STAGGER_SEC`）：避免大量设备同时启动造成 adb 连接风暴，不要移除

---

## 4. 本地开发手册

### 4.1 首次安装

```bash
# 用 Python 3.12 建 venv（README 推荐版本）
/opt/homebrew/bin/python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt

# macOS：adb 用系统自带的（bin/adb/adb 是被 gitignore 的符号链接）
ln -sf /opt/homebrew/bin/adb bin/adb/adb

# 确认 adb key（必须是 STF 容器的 key，否则设备连不上）
ls -la ~/.android/adbkey
```

### 4.2 启动

```bash
.venv/bin/python web_server.py
# 访问 http://localhost:18050/  账号 admin/admin123
```

启动日志看到以下即成功：
```
[INFO] [core.worker] 心跳看门狗已启动
[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
[INFO] [web] 启动服务: http://localhost:18050/
```

### 4.3 测试

- **后端逻辑**：直接 `.venv/bin/python -c "..."` 调用（如 `tasks/`、`core/` 的函数）
- **前端 UI**：Playwright（系统 `python3` 已装），脚本示例见下
- **浏览器冒烟**：切 6 个 tab、开任务编辑器，确认无 JS 错误

```python
# Playwright 冒烟示例（python3 运行）
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    b = p.chromium.launch(headless=True)
    pg = b.new_page()
    pg.goto("http://127.0.0.1:18050/login")
    pg.fill("input[name=username]", "admin")
    pg.fill("input[name=password]", "admin123")
    pg.click("input[type=submit], button[type=submit]")
    pg.wait_for_load_state("networkidle")
    # ... 检查各 tab、编辑器
    b.close()
```

### 4.4 常用调试

- **看日志**：`logs/` 下 `core.log` / `task.log` / `web.log` / `action.log`（10MB 滚动，保留 5 份）
- **看设备/任务状态**：浏览器监控页，或 `GET /api/status`、`GET /api/health`
- **清理 STF 残留占用**：前端监控页"强制释放占用"（或 `.env` 配 `AUTO_RELEASE_STALE_OCCUPY=true` 启动自动清理）
- **打包项目**：`python scripts/pack.py`

---

## 5. 常见开发任务

### 5.1 新增 App 任务

参照 `tasks/douyin/` 结构，详见 **[doc/TASK_DEV.md](TASK_DEV.md)**（6 步模板）。

```
tasks/<app>/
  __init__.py     # from . import task
  task.py         # DEFAULT_PARAMS + Worker + @register_task
  actions/        # 专属操作（可选）
```

### 5.2 新增专属操作

在 `tasks/<app>/actions/` 建 `.py`，继承 `BaseAction` + `@register_action(ACTIONS)`，在 `__init__.py` import。

### 5.3 修改前端

| 文件 | 内容 |
|------|------|
| `templates/admin/monitor.html` | HTML 结构 + CSS + `<script src>` 引用 |
| `static/admin/monitor.js` | 全部前端 JS |

改完**强刷浏览器**（Cmd/Ctrl+Shift+R），必要时重启 web_server。

### 5.4 新增 API

在 `web_server.py` 加 Flask 路由，更新 **[doc/API.md](API.md)**。

### 5.5 新增数据库字段/表

- 模型改 `core/models.py`，首次建表用 `create_all()`
- **已有数据的老库**：在 `core/models.py` 的 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）

---

## 6. 发布流程

详见 **[doc/DEPLOY.md](DEPLOY.md)**。摘要：

1. dev 开发测试完成
2. 负责人确认 → 合并到 main
3. 负责人确认 → 生产 220 `git pull`
4. 重启 python-app 容器生效

**发布前检查**：生产容器 adb key、依赖、数据库迁移。

---

## 7. 文档索引

| 文档 | 内容 |
|------|------|
| [README](../README.md) | 项目总览、快速上手 |
| **[DEVELOPMENT.md](DEVELOPMENT.md)** | 本文档：流程/准则/限制/手册 |
| [TASK_DEV.md](TASK_DEV.md) | 任务开发指南（新增 App 任务模板） |
| [ARCHITECTURE.md](ARCHITECTURE.md) | 架构详解（分层、数据流、设计决策） |
| [API.md](API.md) | 全部 HTTP 接口说明 |
| [DEPLOY.md](DEPLOY.md) | 部署指南（环境、生产、故障排查） |