WQ_GUI/README_new_arch.md

端到端模块化新架构（src/new/）

目录结构

src/new/
├── __init__.py
├── core/
│   ├── __init__.py
│   └── base_view.py          # 基础通讯接口（继承 QWidget + dispatch_execute）
├── services/                 # 独立后端大脑
│   ├── __init__.py
│   ├── step1_service.py      # Step 1 真实服务（execute_step1）
│   └── placeholder_service.py # step2-step13 占位服务
├── views/                    # 独立前端皮囊
│   ├── __init__.py
│   ├── step1_view.py         # Step 1 真实视图（继承 BaseView）
│   └── placeholder_view.py   # step2-step13 占位视图
└── main_router.py            # 路由与调度壳（QMainWindow + QThread）

端到端调用链

Step1View._on_run_clicked  (绿色按钮)
   │  self.dispatch_execute("step1", self.get_config())
   ▼
BaseView.dispatch_execute   (沿父链上溯)
   │  ancestor.run_single_step(step_id, config)
   ▼
MainRouter.run_single_step  (查 ROUTES 表 → 注入 work_dir)
   │  TaskWorker(service_func, config).start()
   ▼
services.step1_service.execute_step1(config)
   │  调 WaterMaskStep.run(...) → 包装成 dict 返回
   ▼
MainRouter._on_step_done  (按 status 写日志)

运行验证

1. 三层冒烟（推荐先跑）

cd D:\111\office\ZHLduijie\1.WQ\WQ_GUI
python _smoke_new_arch.py

预期输出 汇总：54/54 通过。

2. 启动路由主窗口

cd D:\111\office\ZHLduijie\1.WQ\WQ_GUI
python -m src.new.main_router

或：

python src\new\main_router.py

启动后：

• 左侧 QListWidget 显示 13 个 step（step1 真实，其余占位）
• 点击 执行 Step 1: 水域掩膜 → 绿色按钮 → dispatch_execute
• 底部 QTextEdit 实时打印 [Router] / [Service] 日志

关键设计原则

1. view 零业务：src/new/views/*.py 绝不 import 任何 src/core/、src/services/
2. service 零 PyQt：src/new/services/*.py 不 import 任何 PyQt、不读写全局
3. 唯一跨界通道：BaseView.dispatch_execute 把 (step_id, config) 推给主窗口
4. 后台执行不阻塞 UI：TaskWorker(QThread) 子线程跑 service
5. 错误兜底：service 任何异常都被 TaskWorker 捕获并转成 {status: "error", ...}

当前状态

step	view	service	状态
step1	Step1View 真实	execute_step1 真实	✅ 已迁移
step2-13	PlaceholderView	execute_placeholder	🚧 占位待迁移