更新工作目录子文件夹的序号

docs/项目交接文档.md

@@ -0,0 +1,175 @@
+# 水质参数反演分析系统 — 项目交接文档
+
+> 文档用途：帮助新负责人快速理解仓库结构、运行方式、核心逻辑与维护要点。  
+> 适用仓库：本地工程 **fengzhuang-ui2V3**（水质 GUI + 反演流水线）。
+
+---
+
+## 1. 项目概述
+
+本系统为 **基于遥感影像与机器学习的水质反演桌面应用**：水域掩膜、耀斑检测与去除、CSV/光谱处理、监督与非经验建模、采样与预测、空间制图与报告生成。  
+
+- **图形界面**：PyQt5，主入口 `src/gui/water_quality_gui.py`。  
+- **业务编排**：GUI 使用 `src/core/water_quality_inversion_pipeline_GUI.py` 中的 `WaterQualityInversionPipeline`；命令行/无 GUI 场景可参考 `src/core/water_quality_inversion_pipeline.py`（子目录命名已与 GUI 管线对齐，但 **不含** 步骤 5.5 / 6.5 / 6.75 等扩展目录的完整定义，以 GUI 管线为准）。  
+- **打包**：PyInstaller，`scripts/water_quality_gui_file.spec`，单文件 exe，`console=False`。
+
+---
+
+## 2. 目录结构（精简）
+
+```
+项目根/
+├── src/
+│   ├── gui/                    # PyQt5 主界面、步骤面板、工作线程
+│   ├── core/                   # 反演流水线、去耀斑、建模、预测、非经验反演
+│   ├── preprocessing/          # 光谱预处理、水质数据加工
+│   ├── postprocessing/         # 制图、可视化、Word 报告、航迹等
+│   ├── visualization/        # 可视化包初始化（具体实现多在 postprocessing）
+│   └── utils/                  # 水域提取、指数、采样、工具函数
+├── data/                       # 图标、公式子数据等静态资源
+├── scripts/                    # PyInstaller spec、构建产物常出现在 scripts/build|dist
+├── docs/                       # 说明文档（含本文）
+├── requirements*.txt         # pip/conda 依赖清单
+├── README.md / README-conda.md # 安装与 conda 说明
+└── README_SAMPLING_MAP.md      # 采样地图相关说明（若仍写旧目录名，需与下文「工作目录」对照更新）
+```
+
+---
+
+## 3. 运行方式
+
+### 3.1 开发运行 GUI
+
+在项目根目录（或已将 `src` 加入 `PYTHONPATH`）下：
+
+```bash
+python src/gui/water_quality_gui.py
+```
+
+依赖见 `requirements.txt`；地理栈（GDAL/rasterio 等）建议在 **Conda** 环境按 `README-conda.md` / `requirements-conda.txt` 安装。
+
+### 3.2 打包 Windows exe
+
+在已激活的构建环境中执行（路径按本机调整）：
+
+```bash
+pyinstaller scripts/water_quality_gui_file.spec
+```
+
+产物一般为 `scripts/dist/water_quality_gui.exe`（以 spec 中 `name` 为准）。spec 中已收集 rasterio 动态库、conda `Library/bin` 下 DLL、`data/icons` 等。
+
+### 3.3 多进程说明（Windows / 打包）
+
+- 若使用 **sklearn `GridSearchCV(n_jobs=-1)`** 等并行，joblib 会起子进程；**冻结 exe 时可能出现控制台窗口闪烁**。缓解思路：线程后端 `parallel_backend("threading")`、或 `n_jobs=1`、或模型内部 `n_jobs` 并行（需改 `modeling_batch.py`，交接时按需评估）。  
+- 入口脚本建议在 `if __name__ == "__main__":` 内、启动 GUI 前调用 `multiprocessing.freeze_support()`，以符合 PyInstaller + multiprocessing 规范（是否已加请以当前 `water_quality_gui.py` 为准）。
+
+---
+
+## 4. GUI 与流水线步骤对应关系
+
+界面上的「步骤」通过 `WorkerThread.run_single_step` 映射到管线方法（配置键名与面板一致，如 `step6`、`step5_5`）：
+
+| 配置键 / 逻辑步骤 | 管线方法名 |
+|-------------------|------------|
+| step1 | `step1_generate_water_mask` |
+| step2 | `step2_find_glint_area` |
+| step3 | `step3_remove_glint` |
+| step4 | `step4_process_csv` |
+| step5 | `step5_extract_training_spectra` |
+| step5_5 | `step5_5_calculate_water_quality_indices` |
+| step6 | `step6_train_models` |
+| step6_5 | `step6_5_non_empirical_modeling` |
+| step6_75 | `step6_75_custom_regression` |
+| step7 | `step7_generate_sampling_points` |
+| step8 | `step8_predict_water_quality` |
+| step8_5 | `step8_5_predict_with_non_empirical_models` |
+| step8_75 | `step8_75_predict_with_custom_regression` |
+| step9 | `step9_generate_distribution_map` |
+
+单步运行时会注入 `skip_dependency_check=True`，便于独立调试；全流程运行仍应保证输入/前置步骤产物存在。
+
+---
+
+## 5. 工作目录（work_dir）子文件夹命名
+
+所有中间结果默认写在用户选择的 **工作目录** 下。当前代码中约定如下（**若磁盘上仍为旧文件夹名，需手动改名或重新跑流程**）：
+
+| 子目录名 | 含义 |
+|----------|------|
+| `1_water_mask` | 水域掩膜 |
+| `2_glint` | 耀斑相关 |
+| `3_deglint` | 去耀斑影像 |
+| `4_processed_data` | 处理后数据 |
+| `5_training_spectra` | 训练光谱等 |
+| `6_water_quality_indices` | 水质指数（原 `5_5_water_quality_indices`） |
+| `7_models` | 监督学习模型（原 `6_models`） |
+| `8_non_empirical_models` | 非经验模型（原 `6_5_non_empirical_models`） |
+| `9_custom_regression` | 自定义回归结果（原 `6_75_custom_regression`） |
+| `10_sampling` | 采样点/光谱（原 `7_sampling`） |
+| `11_12_13_predictions` | 预测 CSV 等（原 `8_predictions`） |
+| `14_visualization` | 图表、分布图、预览等（原 `9_visualization`） |
+| `reports` | 报告输出（原 `10_reports`） |
+
+**定义位置**：`water_quality_inversion_pipeline_GUI.py` 构造函数中对 `self.*_dir` 的赋值；GUI 中大量路径拼接需与此一致（如 `14_visualization`、`7_models`）。
+
+---
+
+## 6. 核心模块说明
+
+| 模块路径 | 职责 |
+|----------|------|
+| `src/gui/water_quality_gui.py` | 主窗口、各步骤面板、线程 Worker、图像查看、配置收集与单步/全流程触发 |
+| `src/core/water_quality_inversion_pipeline_GUI.py` | GUI 用流水线：步骤实现、目录管理、与可视化/报告类协作 |
+| `src/core/water_quality_inversion_pipeline.py` | 无扩展步骤目录时的管线实现，供脚本或非 GUI 参考 |
+| `src/core/modeling/modeling_batch.py` | 批量训练、`GridSearchCV`、模型落盘（joblib） |
+| `src/core/prediction/inference_batch.py` | 批量预测与模型加载 |
+| `src/core/glint_removal/*.py` | Goodman、Hedley、Kutser、SUGAR 等去耀斑算法 |
+| `src/postprocessing/visualization_reports.py` | 水质可视化封装（输出目录常指向 `14_visualization`） |
+| `src/postprocessing/report_word.py` | Word 报告；默认从 `work_dir/14_visualization` 等读图 |
+| `src/postprocessing/map.py` | 分布图、插值相关（内含开发者本地示例路径，勿当生产配置） |
+
+---
+
+## 7. 依赖与环境
+
+- **Python**：3.8+（README 声明；实际环境以 `requirements-py310.txt` 等为准）。  
+- **关键库**：PyQt5、numpy、pandas、scipy、scikit-learn、joblib、matplotlib、rasterio/geopandas（视功能启用）、opencv-python、Pillow 等。  
+- **Conda**： GDAL 等二进制依赖推荐用 conda-forge，见 `README-conda.md`。
+
+---
+
+## 8. 维护与排错提示
+
+1. **资源路径（打包后图标不显示）**：冻结运行时勿依赖 `Path(__file__)` 指向源码树；应使用 `sys._MEIPASS` 或项目内统一的 `get_icon_path()` 类逻辑。  
+2. **tqdm / 无控制台**：打包 GUI 时若 `sys.stdout` 为 `None`，tqdm 可能报错；`Goodman.py` 等处已对 frozen GUI 做了 `disable` 处理，新增进度条时注意同样处理。  
+3. **配置与 YAML**：全流程配置由 GUI 各面板 `get_config()` 汇总；改字段名需同步管线 `**config['stepX']` 形参。  
+4. **文档滞后**：`README_SAMPLING_MAP.md` 等若仍出现 `9_visualization` 等旧目录名，应以本文第 5 节为准或更新该文档。
+
+---
+
+## 9. 交接检查清单
+
+- [ ] 已能在本机用 `python src/gui/water_quality_gui.py` 启动 GUI 并完成一次最小流程（或关键单步）。  
+- [ ] 已确认 Conda/pip 环境与 `README-conda.md`、`requirements.txt` 一致。  
+- [ ] 已阅读 `scripts/water_quality_gui_file.spec`，知悉打包入口与 `datas` 列表。  
+- [ ] 已知悉 `work_dir` 子目录当前命名，并能区分「配置键 step6」与「文件夹 `7_models`」。  
+- [ ] 已记录客户/内部使用的 **工作目录样例** 与 **典型输入数据格式**（CSV 列、影像格式）。  
+- [ ] Git 远程、发布分支、Issue/需求跟踪方式已交接。  
+- [ ] 许可证与第三方库合规（MIT 与 README 声明等）已确认。
+
+---
+
+## 10. 文档修订记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-04-09 | 初版：目录结构、步骤映射、工作目录新命名、打包与多进程注意事项 |
+
+---
+
+**联系人（请交接时填写）**  
+
+| 角色 | 姓名 | 联系方式 |
+|------|------|----------|
+| 移交人 | | |
+| 接收人 | | |