From 8dace383ecc60fe7f57fe63f7fc984e29dadf2a7 Mon Sep 17 00:00:00 2001 From: Your Name Date: Sat, 30 May 2026 13:26:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(plans):=20=E6=B7=BB=E5=8A=A0=20gui/gui=5Fa?= =?UTF-8?q?pp.py=20=E6=8B=86=E5=88=86=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../plans/2026-05-30-split-gui-app.md | 462 ++++++++++++++++++ 1 file changed, 462 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-30-split-gui-app.md diff --git a/docs/superpowers/plans/2026-05-30-split-gui-app.md b/docs/superpowers/plans/2026-05-30-split-gui-app.md new file mode 100644 index 0000000..e1491aa --- /dev/null +++ b/docs/superpowers/plans/2026-05-30-split-gui-app.md @@ -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 → )" +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 ( → )" +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 ( → )" +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 ( → )" +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 ( → )` + +--- + +## 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 ( → )` + +--- + +## 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 +- 当前行数:`` +- 抽出的模块列表 +- 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 回滚。