docs(plans): 添加 gui/gui_app.py 拆分实施计划
This commit is contained in:
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 回滚。
|
||||
Reference in new issue
Block a user