docs(plans): 添加 gui/gui_app.py 拆分实施计划

This commit is contained in:
Your Name committed 2026-05-30 13:26:42 +08:00
1 parent 26f9e5a553
commit 8dace383ec
1 file changed
+462
@@ -0,0 +1,462 @@
# 拆分 gui/gui_app.py 实施计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 把 `gui/gui_app.py`(5476 行)中内聚的 `main()` 闭包逐段抽到 `gui/components/*` 子模块,主文件持续瘦身,GUI 行为不变。
**Architecture:** 每个候选段抽到独立模块,改造为顶层函数,通过显式参数(回调 + 必要的 widgets/Vars/路径)接收依赖。每抽完一段独立 commit + push。
**Tech Stack:** Python 3.10+, tkinter / ttkbootstrap, pytest
**Spec:** `docs/superpowers/specs/2026-05-30-split-gui-app-design.md`
---
## 抽取顺序
按 spec 优先级:P1 → P2 → P3 → P4 → P5 → P6。每个任务独立可停。
P1 包括两个紧耦合段(`open_wifi_adb_dialog` 845 行 + `open_scan_dialog` 200 行)。
---
## Task 1: 抽 `open_scan_dialog` 到 `components/wifi_adb_scan_dialog.py`
**Files:**
- Create: `gui/components/wifi_adb_scan_dialog.py`
- Modify: `gui/gui_app.py:539-742` (删除原闭包) + 改 `gui/gui_app.py:1088-1093`(`open_scan_dialog` 调用点)
**理由先抽这个:** `open_scan_dialog` 已经是显式参数形式,不依赖 `main()` 任何捕获变量,迁移最简单。先做它能熟悉抽取流程,降 ~200 行。
- [ ] **Step 1: 读完整段确认依赖**
```bash
# 看 539-742 完整段
```
确认 `open_scan_dialog` 仅依赖参数 `parent, adb_exe_local, ip_var, on_line_local, refresh_cb` 和模块级 import(`tk`, `ttk`, `discover_adb_devices`, `get_local_subnet`, `pick_best_match`, `verify_adb_target` 等)。
- [ ] **Step 2: 创建新模块**
写 `gui/components/wifi_adb_scan_dialog.py`,把 539-742 的整段函数原样复制为 `open_scan_dialog`,加 `from __future__ import annotations` 与所有需要的 import。
- [ ] **Step 3: 修改 `gui_app.py`,替换调用点**
在 `gui_app.py` 顶部 import 新模块:
```python
from gui.components.wifi_adb_scan_dialog import open_scan_dialog
```
删除 539-742 的原 `def open_scan_dialog(...)` 定义。
- [ ] **Step 4: 验证语法**
```bash
python -m py_compile gui/gui_app.py gui/components/wifi_adb_scan_dialog.py
```
Expected: 无输出(成功)
- [ ] **Step 5: 跑测试**
```bash
pytest -x
```
Expected: 全部 PASS
- [ ] **Step 6: 行数核对 + commit**
```bash
wc -l gui/gui_app.py
git status --short
git add gui/gui_app.py gui/components/wifi_adb_scan_dialog.py
git commit -m "refactor(gui): 抽 open_scan_dialog 到 components/wifi_adb_scan_dialog (5476 → <new>)"
git push
```
---
## Task 2: 抽 `open_wifi_adb_dialog` 到 `components/wifi_adb_dialog.py`
**Files:**
- Create: `gui/components/wifi_adb_dialog.py`
- Modify: `gui/gui_app.py:743-1111` (删除原闭包,改 `wifi_adb_btn` 的 command)
**依赖分析(已完成):**
模块级(已 import,直接用):
- `list_adb_devices`, `enable_wifi_adb`, `connect_wifi_adb`, `disconnect_wifi_adb`, `auto_connect_wifi_adb`, `get_device_ip`, `get_connected_wifi_devices`(from `gui.gui_core`)
- `set_last_wifi_target`, `get_last_wifi_target`, `clear_last_wifi_target`(from `gui.gui_core_pkg`)
- `verify_adb_target`, `query_device_model`(from `gui.gui_core_pkg.wifi_adb_scan`)
`main()` 局部(必须传):
- `root: tk.Misc`(父窗口,用于 `tk.Toplevel(root)`)
- `adb_exe: str`
- `on_line: Callable[[str], None]`
- `refresh_devices: Callable[[], None]`
- `open_scan_dialog`(Task 1 完成后已为顶层函数,直接 import)
自递归(三处 `dialog.destroy(); open_wifi_adb_dialog()`):
改造为传入自己的引用 —— 用一个内部函数 `_reopen()` 闭包捕获参数,或参数化 `parent`/`adb_exe` 后直接再调用顶层函数。**采用方案 B:把 `open_wifi_adb_dialog` 改成顶层函数,签名带所有依赖,自递归直接调用自己。**
- [ ] **Step 1: 创建新模块骨架**
```python
# gui/components/wifi_adb_dialog.py
from __future__ import annotations
import re
import threading
import tkinter as tk
from tkinter import ttk
from tkinter.constants import LEFT, W, X
from typing import Callable
from gui.gui_core import (
auto_connect_wifi_adb,
connect_wifi_adb,
disconnect_wifi_adb,
enable_wifi_adb,
get_connected_wifi_devices,
get_device_ip,
list_adb_devices,
)
from gui.gui_core_pkg import (
clear_last_wifi_target,
get_last_wifi_target,
set_last_wifi_target,
)
from gui.gui_core_pkg.wifi_adb_scan import query_device_model
from gui.components.wifi_adb_scan_dialog import open_scan_dialog
def open_wifi_adb_dialog(
root: tk.Misc,
*,
adb_exe: str,
on_line: Callable[[str], None],
refresh_devices: Callable[[], None],
) -> None:
"""打开 WiFi ADB 设置对话框。
从 gui_app.main 抽出,显式接收依赖。
"""
# ... (Step 2 复制原 743-1111 函数体,把对外部名字的引用替换为参数)
```
- [ ] **Step 2: 复制函数体并替换闭包变量引用**
把 `gui_app.py:743-1111`(从 `def open_wifi_adb_dialog():` 内 body 开始,到 `info_label.pack(...)` 结束)整段复制进新函数体,缩进调整 4 → 4(已经一致,只是去掉外层 `def main()` 这一层)。
把三处自递归改为带参数的:
```python
# 原: open_wifi_adb_dialog()
# 改: open_wifi_adb_dialog(root, adb_exe=adb_exe, on_line=on_line, refresh_devices=refresh_devices)
```
把对 `open_scan_dialog` 的引用保留为 module-import 形式:
```python
# 原:
# command=lambda: open_scan_dialog(dialog, adb_exe, ip_var, on_line, refresh_device_lists)
# 不变(因为已 import 顶层 open_scan_dialog)
```
注意 `toggle_maximize`、`refresh_device_lists` 是嵌套闭包,保持原样不抽 —— 它们捕获的是对话框内 widgets,只在对话框内用。
- [ ] **Step 3: 改 `gui_app.py`,删原闭包,改按钮 command**
在 `gui_app.py` 顶部加:
```python
from gui.components.wifi_adb_dialog import open_wifi_adb_dialog as _open_wifi_adb_dialog
```
删除 743-1111 的原嵌套 `def open_wifi_adb_dialog():` 整段。
把 1113 行的按钮 command 改为:
```python
wifi_adb_btn = ttk.Button(
top,
text="WiFi ADB",
command=lambda: _open_wifi_adb_dialog(
root,
adb_exe=adb_exe,
on_line=on_line,
refresh_devices=refresh_devices,
),
)
```
- [ ] **Step 4: 验证语法**
```bash
python -m py_compile gui/gui_app.py gui/components/wifi_adb_dialog.py
```
Expected: 无输出
- [ ] **Step 5: 跑测试**
```bash
pytest -x
```
Expected: 全部 PASS
- [ ] **Step 6: 行数核对 + commit**
```bash
wc -l gui/gui_app.py
git status --short
git add gui/gui_app.py gui/components/wifi_adb_dialog.py
git commit -m "refactor(gui): 抽 open_wifi_adb_dialog 到 components/wifi_adb_dialog (<old> → <new>)"
git push
```
---
## Task 3: 评估 P2(`load_config_to_ui` + `save_ui_to_config`)
P2 在 spec 里被标记为高风险(100+ Var)。只有 Task 1+2 完成且测试稳定时才做。
- [ ] **Step 1: 数 Var 数量**
```bash
grep -nE "^\s+[a-zA-Z_]+_var = " gui/gui_app.py | wc -l
```
如果数量 ≥ 50,跳过 Task 3,直接进 Task 4。
如果 < 50,继续。
- [ ] **Step 2: 如果继续,设计 dataclass 聚合 Var**
读 2748-3402 列出所有用到的 Var,定义:
```python
# gui/components/config_io.py
@dataclass
class ConfigVars:
y_var: tk.IntVar
needswitch_var: tk.BooleanVar
# ... 全部
```
抽出函数:
```python
def load_config_to_ui(vars_: ConfigVars, *, on_line: Callable[[str], None]) -> None: ...
def save_ui_to_config(vars_: ConfigVars, *, on_line: Callable[[str], None]) -> None: ...
```
实施步骤参考 Task 2 的 Step 1-6。
如果改动量过大或测试卡住,**回滚并跳过 P2**。
---
## Task 4: 抽 `refresh_reservations` 到 `components/reservations_view.py`
**Files:**
- Create: `gui/components/reservations_view.py`
- Modify: `gui/gui_app.py:4530-4805` (删原闭包),改调用点
- [ ] **Step 1: 列出依赖**
读 4530-4805,记录捕获的 widgets(主要是 `reservations_tree: ttk.Treeview`)、状态变量、回调。
- [ ] **Step 2: 创建模块,函数签名**
```python
# gui/components/reservations_view.py
from __future__ import annotations
import tkinter as tk
from tkinter import ttk
from typing import Callable
def refresh_reservations(
tree: ttk.Treeview,
*,
on_line: Callable[[str], None] = lambda _msg: None,
) -> None:
"""刷新预约 Tab 的 Treeview。"""
# body 来自原 4530-4805
```
依赖里如果有路径(`get_logs_dir` 之类)直接 import,不需要传参。
- [ ] **Step 3: 修改 `gui_app.py`**
```python
from gui.components.reservations_view import refresh_reservations as _refresh_reservations_impl
# 原 def refresh_reservations(): ... 改为:
def refresh_reservations():
_refresh_reservations_impl(reservations_tree, on_line=on_line)
```
保留薄包装 `def refresh_reservations()`,因为 `auto_refresh_reservations` 等地方仍以闭包形式调用它。
- [ ] **Step 4: 验证 + 测试 + commit**
```bash
python -m py_compile gui/gui_app.py gui/components/reservations_view.py
pytest -x
wc -l gui/gui_app.py
git add gui/gui_app.py gui/components/reservations_view.py
git commit -m "refactor(gui): 抽 refresh_reservations 到 components/reservations_view (<old> → <new>)"
git push
```
---
## Task 5: 抽 `refresh_high_value_rooms` 到 `components/high_value_view.py`
**Files:**
- Create: `gui/components/high_value_view.py`
- Modify: `gui/gui_app.py:4805-5085`
- [ ] **Step 1: 列出依赖**
读 4805-5085,记录捕获的 widgets(主要是 `high_value_rooms_tree: ttk.Treeview`)、状态变量、回调。
- [ ] **Step 2: 创建模块,函数签名**
```python
# gui/components/high_value_view.py
from __future__ import annotations
import tkinter as tk
from tkinter import ttk
from typing import Callable
def refresh_high_value_rooms(
tree: ttk.Treeview,
*,
on_line: Callable[[str], None] = lambda _msg: None,
) -> None:
"""刷新高价值房间 Tab 的 Treeview。"""
# body 来自原 4805-5085
```
依赖里如果有路径(`get_logs_dir` 之类)直接 import,不需要传参。
- [ ] **Step 3: 修改 `gui_app.py`**
```python
from gui.components.high_value_view import refresh_high_value_rooms as _refresh_high_value_rooms_impl
# 原 def refresh_high_value_rooms(): ... 改为薄包装:
def refresh_high_value_rooms():
_refresh_high_value_rooms_impl(high_value_rooms_tree, on_line=on_line)
```
- [ ] **Step 4: 验证 + 测试 + commit**
```bash
python -m py_compile gui/gui_app.py gui/components/high_value_view.py
pytest -x
wc -l gui/gui_app.py
git add gui/gui_app.py gui/components/high_value_view.py
git commit -m "refactor(gui): 抽 refresh_high_value_rooms 到 components/high_value_view (<old> → <new>)"
git push
```
---
## Task 6: 抽 `do_screenshot` + `_bind_screenshot_button` 到 `components/screenshot_action.py`
**Files:**
- Create: `gui/components/screenshot_action.py`
- Modify: `gui/gui_app.py:3402-3651`
- [ ] **Step 1: 列出依赖**
读 3402-3651。`do_screenshot` 依赖:`adb_exe`、状态 Label、图片预览刷新回调、ADB 截图工具函数。
- [ ] **Step 2-4: 抽出,签名:**
```python
def do_screenshot(
*,
adb_exe: str,
on_line: Callable[[str], None],
on_done: Callable[[str], None], # 截图保存路径
status_label: ttk.Label | None = None,
) -> None:
...
def bind_screenshot_button(
btn: ttk.Button,
*,
adb_exe: str,
on_line: Callable[[str], None],
on_done: Callable[[str], None],
status_label: ttk.Label | None = None,
) -> None:
btn.configure(command=lambda: do_screenshot(
adb_exe=adb_exe, on_line=on_line, on_done=on_done, status_label=status_label
))
```
调用点同 Task 4。
commit msg: `refactor(gui): 抽 do_screenshot 到 components/screenshot_action (<old> → <new>)`
---
## Task 7: 抽 `refresh_actions_log` + 搜索栏 到 `components/actions_log_view.py`
**Files:**
- Create: `gui/components/actions_log_view.py`
- Modify: `gui/gui_app.py:4845-5070`
- [ ] **Step 1: 列出依赖**
读 4845-5070。包含:`configure_actions_log_colors`、`refresh_actions_log`、几个搜索方法 `search_in_actions_log`/`search_next_in_actions`/`search_prev_in_actions`/`clear_search_in_actions`/`on_actions_search_entry_key`。
- [ ] **Step 2-4: 设计**
设计成 1 个 `setup_actions_log_view(text_widget, search_entry, ...)` 一次性绑定所有,或者保留几个独立函数都接收 `text_widget` 参数。优先后者(更小步)。
签名:
```python
def configure_actions_log_colors(text_widget: tk.Text) -> None: ...
def refresh_actions_log(text_widget: tk.Text, *, on_line: Callable[[str], None]) -> None: ...
def search_in_actions_log(text_widget: tk.Text, search_entry: ttk.Entry, *, direction: int = 1) -> None: ...
```
`gui_app.py` 里保留薄包装让原闭包调用模式不变。
commit msg: `refactor(gui): 抽 actions_log 视图相关到 components/actions_log_view (<old> → <new>)`
---
## Task 8: 评估停止条件 + 收尾
- [ ] **Step 1: 检查停止条件**
```bash
wc -l gui/gui_app.py
```
满足以下任一即停:
1. ≤ 3000 行
2. 行数下降 < 50
3. 下一段需传 ≥ 50 个独立依赖
- [ ] **Step 2: 如果停止,写收尾说明**
如果停止,在 `docs/superpowers/specs/2026-05-30-split-gui-app-design.md` 末尾追加 `## Outcome` 段:列出实际抽出的模块、行数变化、未做的项。
```bash
git add docs/superpowers/specs/2026-05-30-split-gui-app-design.md
git commit -m "docs(specs): 补充 gui_app 拆分实际成果"
git push
```
- [ ] **Step 3: 报告**
总结输出给用户:
- 起始行数:5476
- 当前行数:`<X>`
- 抽出的模块列表
- pytest 状态
- 是否还有未抽的候选(可作为下一轮)
---
## 关键约束(每个 Task 都要遵守)
1. **AGENTS.md**:每个 Task 都要 commit + push,只 stage 本任务实际改的文件,不混入用户已有改动。
2. **不改行为**:抽取是纯重构,不修 bug、不优化性能、不删功能。
3. **失败回滚**:若 pytest 失败且修复需改 ≥ 2 个非目标文件,`git reset --hard HEAD~1`(本任务的 commit 还没 push),回到上一 Task 报告问题。
4. **每个 Task 验证后再开下一个**:不批量做。
5. **手工 smoke 推迟到批次末尾**:本计划的 pytest 不覆盖 GUI 交互(项目测试有意写得轻),抽取属纯重构,逻辑保持一致。每个 Task 完成后,在 Task 8 的收尾报告里提示用户:「请启动 GUI 跑一遍受影响功能(WiFi 对话框 / 预约 Tab / 高价值房间 / 截图按钮 / 操作日志 Tab),确认无回归。」用户 smoke 后若发现问题,定位到具体 Task 的 commit 回滚。