WQ_GUI/ARCHITECTURE.md

WQ_GUI 水质遥感分析系统 — 架构文档

生成日期：2026-06-30 | 分支：Mega2.2 | 步骤数：13

---

一、项目总览

src/
├── gui/
│   ├── water_quality_gui.py          # V1 入口
│   ├── water_quality_gui_v2.py       # V2 入口（当前主力）
│   ├── styles.py                      # 全局样式 ModernStylesheet
│   ├── core/
│   │   ├── panel_registry.py          # 步骤注册表
│   │   ├── panel_factory.py           # 惰性加载面板工厂
│   │   ├── pipeline_executor.py       # 流水线调度
│   │   ├── event_bus.py               # 全局事件总线
│   │   ├── worker_thread.py           # 工作线程
│   │   ├── dependency_subscriber.py   # 步骤间依赖自动注入
│   │   └── workspace_initializer.py   # 工作区初始化
│   ├── panels/
│   │   ├── _step_path_resolver.py     # 路径解析（文件系统扫描）
│   │   ├── step1_panel.py ~ step13_report_panel.py  # 13个步骤面板
│   │   └── ...
│   └── components/
│       ├── custom_widgets.py          # FileSelectWidget / DirSelectWidget
│       ├── data_models.py             # PandasTableModel
│       └── chart_dialogs.py           # InteractiveViewerDialog 等
├── core/                              # 后端处理引擎
│   ├── handlers/                      # 步骤处理器（14个）
│   ├── steps/                         # 步骤算法实现
│   ├── algorithms/                    # 核心算法
│   └── pipeline/                      # 流水线调度器
├── postprocessing/                    # 后处理（可视化、地图、报告）
└── new/                               # 新架构（部分迁移中）

---

二、核心架构机制

2.1 事件总线 (EventBus)

全局单例 global_event_bus，解耦面板之间及面板与调度器的通信：

事件名	发布者	订阅者	用途
RequestRunSingleStep	各面板 run_btn	PipelineExecutor	单步执行
OutputUpdated	面板输出变化时	依赖订阅者	自动传播输出路径
PipelineStarted/Finished/Stopped	PipelineExecutor	全局	流水线生命周期
StepCompleted	WorkerThread	日志/UI	单步完成通知
LogMessage	各处	LogManager	日志写入
ProgressUpdate	WorkerThread	进度条	进度更新
NavigateToTab	各处	QTabWidget	标签切换
WorkspaceChanged	WorkspaceManager	全局面板	工作目录变更

2.2 面板工厂 (PanelFactory)

惰性加载机制：启动时仅创建占位 Tab，首次切换到某 Tab 时才实例化对应 Panel。

核心方法：

• get_panel(step_id) → 返回面板实例（已缓存则直接返回）
• _ensure_loaded(tab_index) → 实例化、包装 QScrollArea、替换占位 Tab
• _replay_state_to_panel(panel) → 新加载的面板回放上游已产生的输出状态

2.3 依赖注入系统

PANEL_REGISTRY 中每个步骤定义 dependencies：

dependencies = {
    'target_attr': ('upstream_step_id', 'output_type', 'source_attr')
}

DependencySubscriber 监听 OutputUpdated 事件，自动将上游输出路径填入下游面板的对应输入控件。

_step_path_resolver.py 则通过文件系统扫描 + 目录映射表实现回退路径发现。

2.4 执行流程

用户点击 "独立运行步骤"
  → Panel._on_run_single_clicked()
    → EventBus.publish('RequestRunSingleStep', {step_name, config})
      → PipelineExecutor._on_request_run_single_step()
        → WorkerThread(QThread) 启动
          → PipelineScheduler.run_step(step_key, config)
            → BaseStepHandler.execute(ctx, config)
              → 实际算法逻辑

---

三、13 个步骤详解

模块一：影像预处理（Steps 1-3）

---

Step 1 — 水域掩膜生成

项目	详情
面板文件	src/gui/panels/step1_panel.py
面板类	Step1Panel(QWidget)
后端处理器	src/core/handlers/step1_water_mask.py — Step1WaterMaskHandler
后端算法	src/core/steps/water_mask_step.py — WaterMaskStep
UI 输入	mask_file(FileSelectWidget) / NDWI 阈值模式：ndwi_threshold(QLineEdit, 0.0-1.0), img_file(FileSelectWidget)
UI 输出	output_file(FileSelectWidget, mode=save), run_btn
上游依赖	无
产出类型	reference_img, water_mask
关键方法	init_ui() → update_ui_state() 切换掩膜/NDWI 策略；get_config() 返回 {mask_path, use_ndwi, ndwi_threshold, img_path, output_path}
目录映射	→ 1_water_mask

Step 2 — 耀斑检测

项目	详情
面板文件	src/gui/panels/step2_panel.py
面板类	Step2Panel(QWidget)
后端处理器	src/core/handlers/step2_glint_detection.py — Step2GlintDetectionHandler
后端算法	src/core/steps/glint_detection_step.py — GlintDetectionStep
UI 输入	img_file(FileSelectWidget), water_mask_file(FileSelectWidget)
UI 参数	glint_wave(QDoubleSpinBox, 300-1000nm), method(QComboBox: Otsu/Z-Score/百分位数/IQR/自适应/多波段综合), max_area(QSpinBox), buffer_size(QSpinBox)
UI 输出	output_file(FileSelectWidget, mode=save), run_btn
上游依赖	img_file ← step1.reference_img; water_mask_file ← step1.water_mask
产出类型	glint_mask
目录映射	→ 2_Glint_Detection

Step 3 — 去耀斑

项目	详情
面板文件	src/gui/panels/step3_panel.py
面板类	Step3Panel(QWidget)
后端处理器	src/core/handlers/step3_glint_removal.py — Step3GlintRemovalHandler
后端算法	src/core/steps/glint_removal_step.py — GlintRemovalStep
UI 输入	img_file(FileSelectWidget), water_mask_file(FileSelectWidget)
UI 参数	method(QComboBox: Goodman/Kutser/Hedley/SUGAR), 4 个 StackedWidget 参数页 + interpolate_zeros(QCheckBox), interp_method(QComboBox)
UI 输出	output_file(FileSelectWidget), run_btn
上游依赖	img_file ← step1.reference_img; water_mask_file ← step1.water_mask
产出类型	deglint_image
特殊机制	img_file.textChanged → 自动调用 _update_band_ranges() 检测波段范围；method.currentIndexChanged → 切换参数 StackedWidget 页面
目录映射	→ 3_deglint

---

模块二：特征工程与数据（Steps 4-7）

---

Step 4 — 采样点布局与交互式探索

项目	详情
面板文件	src/gui/panels/step4_sampling_panel.py
面板类	Step4SamplingPanel(QWidget)
后端处理器	src/core/handlers/step4_sampling.py — Step4SamplingHandler
UI 输入	deglint_img_file(FileSelectWidget), water_mask_file(FileSelectWidget)
UI 参数	interval(QSpinBox, 10-500px), sample_radius(QSpinBox, 1-50px), chunk_size(QSpinBox, 100-10000px), use_adaptive_sampling(QCheckBox)
UI 输出	output_file(FileSelectWidget), refresh_btn, run_btn
可视化	Matplotlib 嵌入：FigureCanvasQTAgg + 隐藏 NavigationToolbar2QT，左右分栏（散点图 + 光谱曲线），自定义工具栏按钮
交互	_on_hover() 鼠标变小手 + 悬停标注；_on_click() 点击高亮 + 光谱绘制 + 再次点击取消选中；三按钮互斥：👆 点选探针 / ✋ 拖拽漫游 / 🔍 框选放大
上游依赖	deglint_img_file ← step3.deglint_image; water_mask_file ← step1.water_mask
产出类型	sampling_points
特殊机制	_status_timer (5000ms) 自动检测 CSV 并重渲染；draw_idle() 防 UI 卡死；rcParams 中文字体双重保障
目录映射	→ 4_sampling

Step 5 — 数据清洗

项目	详情
面板文件	src/gui/panels/step5_clean_panel.py
面板类	Step5CleanPanel(QWidget)
后端处理器	src/core/handlers/step5_process_csv.py — Step5ProcessCsvHandler
UI 输入	csv_file(FileSelectWidget)
UI 参数	preview_rows_spin(QSpinBox), preview_table(QTableView + PandasTableModel), preview_status_label(QLabel)
UI 输出	output_file(FileSelectWidget, mode=save), run_btn
上游依赖	无（独立输入源）
产出类型	processed_data
目录映射	→ 5_Data_Cleaning

Step 6 — 光谱特征提取

项目	详情
面板文件	src/gui/panels/step6_feature_panel.py
面板类	Step6FeaturePanel(QWidget)
后端处理器	src/core/handlers/step6_extract_spectra.py — Step6ExtractSpectraHandler
UI 输入	deglint_img_file(FileSelectWidget), csv_file(FileSelectWidget), water_mask_file(FileSelectWidget), glint_mask_file(FileSelectWidget)
UI 参数	radius(QSpinBox, 1-50px), source_epsg(QSpinBox, default 4326)
UI 输出	output_file(FileSelectWidget), run_btn
上游依赖	deglint_img_file ← step3; csv_file ← step5; water_mask_file ← step1; glint_mask_file ← step2
产出类型	output_file
目录映射	→ 6_Spectral_Feature_Extraction

Step 7 — 水质指数计算

项目	详情
面板文件	src/gui/panels/step7_inversion_panel.py
面板类	Step7InversionPanel(QWidget)
后端处理器	src/core/handlers/step7_calc_indices.py — Step7CalcIndicesHandler
UI 输入	formula_file(FileSelectWidget, 只读), training_data_widget(FileSelectWidget)
UI 参数	category_combo(QComboBox 按类别筛选), formula_list(NoScrollPassListWidget, checkable), 选择按钮：全选/清空/比值/浓度/重载
UI 输出	output_file(FileSelectWidget), run_btn
上游依赖	training_data_widget ← step6_feature.output_file
产出类型	training_spectra_indices
特殊机制	_load_formulas_from_csv() 从内置公式库加载；_update_formula_count() 统计选中数
目录映射	→ 7_Water_Quality_Indices

---

模块三：模型训练与反演（Steps 8-10）

---

Step 8 — 机器学习建模

项目	详情
面板文件	src/gui/panels/step8_ml_train_panel.py
面板类	Step8MlTrainPanel(QWidget)
后端处理器	src/core/handlers/step8_ml_train.py — Step8MlTrainHandler
后端算法	src/core/steps/modeling_step.py — ModelingStep
UI 输入	training_csv_file(FileSelectWidget)
UI 参数	feature_start(QComboBox), cv_folds(QSpinBox 2-10), 预处理 11 项 CheckBox(None/MMS/SS/SNV/MA/SG/MSC/D1/D2/DT/CT), 模型 15 项 CheckBox(LR/Ridge/Lasso/ElasticNet/PLS/DT/RF/ExtraTrees/XGBoost/LightGBM/CatBoost/GBDT/AdaBoost/SVR/KNN/MLP), 数据划分 3 项 CheckBox(SPXY/KS/Random)
UI 输出	output_path(FileSelectWidget, 目录模式), run_btn
上游依赖	training_csv_file ← step7_index.training_spectra_indices
产出类型	output_path
目录映射	→ 8_Supervised_Model_Training

Step 9 — 机器学习预测

项目	详情
面板文件	src/gui/panels/step9_ml_predict_panel.py
面板类	Step9MlPredictPanel(QWidget)
后端处理器	src/core/handlers/step9_ml_predict.py — Step9MlPredictHandler
后端算法	src/core/steps/prediction_step.py — PredictionStep
UI 输入	sampling_csv_file(FileSelectWidget), models_dir_file(FileSelectWidget, 目录)
UI 参数	模型来源：use_trained_model/use_external_model(QRadioButton), 外部模型 model_list(QListWidget, checkable), metric(QComboBox: R²/RMSE/MAE), prediction_column(QLineEdit)
UI 输出	output_file(FileSelectWidget, 目录), run_btn
上游依赖	models_dir_file ← step8_ml_train.output_path
产出类型	output_file
目录映射	→ 9_ML_Prediction

Step 10 — 水色指数反演

项目	详情
面板文件	src/gui/panels/step10_watercolor_panel.py
面板类	Step10WatercolorPanel(QWidget)
后端处理器	src/core/handlers/step10_qaa_inversion.py — Step10QaaInversionHandler
后端算法	src/core/algorithms/waterindex_inversion.py — WaterIndexCsvProcessor
UI 输入	formula_file(FileSelectWidget, 只读), sampling_csv_file(FileSelectWidget)
UI 参数	category_combo(QComboBox 按水质类别筛选), formula_list(NoScrollPassListWidget, checkable), 全选/清空/比值/浓度按钮
UI 输出	output_dir(FileSelectWidget, 目录), progress_bar(QProgressBar), progress_label(QLabel), run_btn
上游依赖	sampling_csv_file ← step4_sampling.sampling_points
产出类型	output_dir
特殊机制	内嵌 WaterIndexWorker(QThread) 后台处理 CSV
目录映射	→ 10_WaterIndex_CSV

---

模块四：制图与成果汇编（Steps 11-13）

---

Step 11 — 专题图生成

项目	详情
面板文件	src/gui/panels/step11_map_panel.py
面板类	Step11MapPanel(QWidget)
后端处理器	src/core/handlers/step11_concentration.py — Step11ConcentrationHandler
后端算法	CSV 模式: src/core/steps/mapping_step.py — MappingStep.generate_distribution_map()；GeoTIFF 模式: src/postprocessing/map.py — ContentMapper.visualize_raster()
UI 输入	render_mode_combo(QComboBox: CSV插值/GeoTIFF栅格), batch_mode_combo(QComboBox: 单个文件/文件夹批量), prediction_csv_file(FileSelectWidget), geotiff_file(FileSelectWidget), boundary_file(FileSelectWidget: *.shp)
UI 参数	resolution(QDoubleSpinBox, 1-1000), input_crs/output_crs(QLineEdit, EPSG:32651), show_points(QCheckBox), use_diffusion(QCheckBox)
UI 输出	output_dir(FileSelectWidget), progress_bar(QProgressBar), run_button
上游依赖	prediction_csv_dir_edit ← step9; geotiff_dir_edit ← step10; boundary_file ← step1.water_mask
特殊机制	两个后台线程：Step11MapBatchThread(CSV) / Step11GeoTIFFBatchThread(GeoTIFF)
目录映射	→ 14_visualization

Step 12 — 可视化

项目	详情
面板文件	src/gui/panels/step12_viz_panel.py
面板类	Step12VizPanel(QWidget)
后端算法	src/postprocessing/visualization_reports.py — WaterQualityVisualization; src/core/visualization/scatter_plot.py; src/postprocessing/point_map.py — SamplingPointMap
UI 输入	work_dir_edit(QLineEdit), img_dir_edit(QLineEdit)
UI 参数	6 个 QCheckBox: gen_scatter(模型评估散点图), gen_spectrum(光谱曲线), gen_boxplots(统计图), gen_mask_glint(掩膜缩略图), gen_sampling_map(采样点地图), gen_distribution_map(空间分布图)
UI 输出	gen_all_btn(QPushButton), scan_btn(QPushButton), ImageCategoryTree(QTreeWidget), ImageViewerWidget(带缩放/平移/保存), 筛选: view_mode_cb + chart_filter_cb
上游依赖	无（文件系统自动扫描）
产出类型	多种图表 PNG
特殊机制	VisualizationWorkerThread(QThread) 后台批量生成；ImageCategoryTree 三视图模式（按水质参数/图表类型/物理文件夹）

Step 13 — 报告生成

项目	详情
面板文件	src/gui/panels/step13_report_panel.py
面板类	Step13ReportPanel(QWidget)
后端算法	src/postprocessing/report_word.py — WaterQualityReportGenerator + ReportGenerationConfig
UI 输入	work_dir_edit(QLineEdit, 只读), output_dir_edit(QLineEdit + 浏览)
UI 参数	report_title_edit(QLineEdit), enable_ai_cb(QCheckBox), AI 设置按钮 → AISettingsDialog
UI 输出	progress_label(QLabel), progress_bar(QProgressBar), generate_btn(QPushButton)
上游依赖	无（但需要 main_window 在构造时注入）
产出类型	Word 报告 (.docx)
特殊机制	ReportWorkerThread(QThread) 后台生成；AI 分析可选（需配置 API Key）
目录映射	→ reports

---

四、步骤间数据流转图

Step1 水域掩膜 ─── img_file ───────────────┬──► Step2 耀斑检测 ── glint_mask ──► Step6
       │                                    │
       ├── water_mask ──────────────────────┼──► Step3 去耀斑 ─── deglint ────► Step4
       │                                    │        │                           │
       │                                    │        └───────────────────────────┤
       │                                    │                                    │
       │                                    ├──► Step4 采样 ←────────────────────┘
       │                                    ├──► Step6 特征提取
       │                                    ├──► Step11 专题图 ───► Step12
       │                                    └──► Step12 可视化      Step13
       │
       └──► Step11 专题图(边界)

Step4 采样 ── sampling_csv ──► Step10 水色指数 ── output_dir ──► Step11(GeoTIFF)

Step5 清洗 ── csv ──► Step6 特征提取 ── output ──► Step7 指数计算
                                                       │
                                                       ▼
                                              Step8 机器学习建模
                                                       │
                                                       ▼
                                              Step9 机器学习预测
                                                       │
                                                       ▼
                                              Step11 专题图(CSV)

---

五、自定义组件

5.1 文件选择控件

FileSelectWidget (src/gui/components/custom_widgets.py)

模式	行为
mode="open"	QFileDialog.getOpenFileName() — 选择已存在文件
mode="save"	QFileDialog.getSaveFileName() — 选择保存路径
mode="dir"	QFileDialog.getExistingDirectory() — 选择目录

关键方法：get_path(), set_path(path), set_read_only(bool), line_edit.textChanged 信号

5.2 路径解析器

_step_path_resolver.py — 所有 13 个 Panel 统一通过 from src.gui.panels._step_path_resolver import ... 导入

函数	用途
resolve_subdir(work_dir, subdir_key)	步骤名 → 实际子目录路径
scan_work_dir_for_input(work_dir, output_type)	文件系统扫描发现上游输出
resolve_step_widget(main_window, step_key, widget_attr)	通过 panel_factory 定位上游控件
get_step_output_path(main_window, step_key, work_dir, widget_attr, fallback_key)	获取上游输出路径（含回退）

5.3 全局样式

ModernStylesheet (src/gui/styles.py) — 提供 get_button_stylesheet('normal'|'primary')

---

六、关键设计模式

模式	位置	说明
惰性加载	PanelFactory	Tab 切换时才实例化 Panel，降低启动时间
事件总线	EventBus	Panel ↔ PipelineExecutor 解耦通信
依赖注入	DependencySubscriber + PANEL_REGISTRY	上游输出自动填入下游输入
文件系统回退	_step_path_resolver	当依赖注入失败时，扫描实际文件系统
独立运行	每个 Panel 的 run_btn	不依赖全流水线，可单独执行
后台线程	WorkerThread / 各 Panel 内嵌 QThread	长时间计算不阻塞 GUI
交互模式	Step4 三按钮互斥	点选探针 / 拖拽漫游 / 框选放大

---

七、文件清单

前端面板（13 个）

文件	类	Step ID
step1_panel.py	Step1Panel	step1
step2_panel.py	Step2Panel	step2
step3_panel.py	Step3Panel	step3
step4_sampling_panel.py	Step4SamplingPanel	step4_sampling
step5_clean_panel.py	Step5CleanPanel	step5_clean
step6_feature_panel.py	Step6FeaturePanel	step6_feature
step7_inversion_panel.py	Step7InversionPanel	step7_index
step8_ml_train_panel.py	Step8MlTrainPanel	step8_ml_train
step9_ml_predict_panel.py	Step9MlPredictPanel	step9_ml_predict
step10_watercolor_panel.py	Step10WatercolorPanel	step10_watercolor
step11_map_panel.py	Step11MapPanel	step11_map
step12_viz_panel.py	Step12VizPanel	step12_viz
step13_report_panel.py	Step13ReportPanel	step13_report

后端核心（14 个 Handler）

文件	类	Step Key
handlers/step1_water_mask.py	Step1WaterMaskHandler	step1
handlers/step2_glint_detection.py	Step2GlintDetectionHandler	step2
handlers/step3_glint_removal.py	Step3GlintRemovalHandler	step3
handlers/step4_sampling.py	Step4SamplingHandler	step4_sampling
handlers/step5_process_csv.py	Step5ProcessCsvHandler	step5_clean
handlers/step6_extract_spectra.py	Step6ExtractSpectraHandler	step6_feature
handlers/step7_calc_indices.py	Step7CalcIndicesHandler	step7_index
handlers/step8_ml_train.py	Step8MlTrainHandler	step8_ml_train
handlers/step9_ml_predict.py	Step9MlPredictHandler	step9_ml_predict
handlers/step10_qaa_inversion.py	Step10QaaInversionHandler	step10_qaa_inversion
handlers/step11_concentration.py	Step11ConcentrationHandler	step11_concentration
handlers/step12_kriging.py	Step12KrigingHandler	step12_kriging
handlers/step13_visualization.py	Step13VisualizationHandler	step13_visualization
handlers/step14_report.py	Step14ReportHandler	step14_report

注：Handler 注册有 14 个（step1-14），对应 Panel 有 13 个（step1-13）。Step12 的 Handler 处理克里金插值，Step13 的 Handler 处理可视化，Step14 的 Handler 处理报告。

---

八、审计修复记录（2026-06-30）

本轮已修复的全部问题：

#	严重度	文件	问题	修复
1	🔴	step11_map_panel.py:652	mapper 在 import 之前引用	移动 import 至引用上方
2	🟡	step12_viz_panel.py:1719	get_panel('step1_mask') key 不存在	改为 'step1'
3	🟡	step3_panel.py:384	currentData() 返回 None	改为 currentText()
4	🟡	step5_clean_panel.py:228/253	PandasTableModel 从 v1 入口导入	改为 src.gui.components.data_models
5	🟡	step3_panel.py:271	InteractiveViewerDialog 同上	改为 src.gui.components.chart_dialogs
6	🟢	step7_inversion_panel.py:9	import csv 未使用	移除
7	🟢	step5_clean_panel.py:167	死方法 _add_row_with_fixed_label	标注废弃
8	🟢	全部 12 个 Panel	_step_path_resolver 导入风格不一致	统一为 from src.gui.panels._step_path_resolver import ...，移除 _HERE/sys.path hack