README_new_arch.md + _smoke_new_arch.py：端到端新架构运行文档与三层冒烟（service/view/e2e 共 54 项断言）

2026-06-16 17:53:46 +08:00
parent e993a184bd
commit afe9eaff2c
2 changed files with 426 additions and 0 deletions
--- a/README_new_arch.md
+++ b/README_new_arch.md
@ -0,0 +1,83 @@
+# 端到端模块化新架构（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. 三层冒烟（推荐先跑）
+
+```cmd
+cd D:\111\office\ZHLduijie\1.WQ\WQ_GUI
+python _smoke_new_arch.py
+```
+
+预期输出 `汇总：54/54 通过`。
+
+### 2. 启动路由主窗口
+
+```cmd
+cd D:\111\office\ZHLduijie\1.WQ\WQ_GUI
+python -m src.new.main_router
+```
+
+或：
+
+```cmd
+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`  | 🚧 占位待迁移       |