docs: 完善项目文档和使用说明

- 更新README.md，补充GUI特性说明和参数配置文档
- 新增使用说明目录，包含完整的操作手册和界面截图
- 优化generate_template.py，支持自定义模板输出路径
- 改进GUI界面布局，优化文件上传和模板导出功能
- 添加系统参数配置说明（电压、功率因数等）

README.md

@@ -4,15 +4,15 @@
 
 ## 🌟 主要功能
 
-- 🖥️ **交互式 Web 界面**：基于 NiceGUI 开发，支持文件上传、实时日志、方案对比和可视化。
+- 🖥️ **原生桌面体验**：支持 Native 模式运行，提供类似本地应用的流畅体验（基于 NiceGUI & PyWebview）。
 - 🌊 **多种布局生成**：内置模拟数据生成器，支持规则网格和随机分布布局。
 - 🔌 **先进设计算法**：
   - **MST (Minimum Spanning Tree)**：无容量约束基准方案。
   - **Capacitated Sweep (Base)**：基础扇区扫描分组。
   - **Rotational Sweep**：全局最优起始角度旋转扫描优化。
   - **Esau-Williams**：经典启发式算法，在距离与容量间寻找最优平衡。
+- ⚙️ **灵活参数配置**：支持通过 Excel 自定义系统电压、功率因数及详细电缆规格。
 - 📊 **智能方案对比**：自动运行三大场景（标准方案、含可选电缆方案、限制最大截面方案）并对比结果。
-- 📋 **数据校验与保障**：严格校验输入数据的有序性及电缆配置规则。
 - 📁 **多格式导出**：
   - 自动生成 CAD 图纸 (`.dxf`)，按电缆规格分层并着色。
   - 导出详细的 Excel 对比报告及单方案电缆清册。
@@ -23,19 +23,24 @@
 本项目使用 `uv` 或 `pip` 管理环境。推荐安装依赖：
 
 ```bash
-pip install numpy pandas matplotlib scikit-learn scipy networkx ezdxf nicegui openpyxl
+pip install numpy pandas matplotlib scikit-learn scipy networkx ezdxf nicegui openpyxl pywebview
 ```
+*注：`pywebview` 用于支持原生窗口模式。*
 
 ## 🚀 使用方法
 
 ### 1. 启动图形化界面 (推荐)
 
-运行以下命令启动 Web 界面，程序将自动在浏览器中打开：
+运行以下命令启动应用，程序将自动弹出独立窗口：
 
 ```bash
 python gui.py
 ```
-*注：程序默认监听 8080 端口，若被占用将自动尝试后续可用端口。*
+
+**GUI 特性：**
+- **模板导出**：点击界面上的 "导出 Excel 模板" 按钮可获取标准输入格式文件。
+- **参数概览**：上传文件后自动解析并显示系统参数及电缆规格。
+- **交互式分析**：点击结果表格中的行，可实时查看对应方案的拓扑图。
 
 ### 2. 命令行模式
 
@@ -45,7 +50,7 @@ python main.py --excel your_data.xlsx
 
 ## 📝 输入数据规范 (Excel)
 
-为了确保计算结果的准确性，输入 Excel 文件应包含以下两个 Sheet：
+为了确保计算结果的准确性，输入 Excel 文件应包含以下 Sheet（推荐使用 GUI 导出模板）：
 
 ### 1. Coordinates (坐标)
 | Type | ID | X | Y | Power | PlatformHeight |
@@ -61,6 +66,14 @@ python main.py --excel your_data.xlsx
   - `Optional` 列标记为 'Y' 的电缆最多只能有一条。
   - 若存在可选电缆，它必须是列表中截面最大的一条。
 
+### 3. Parameters (参数) [可选]
+可自定义系统级参数，若不提供则使用默认值。
+
+| Parameter | Value | 说明 |
+|-----------|-------|------|
+| Voltage (kV) | 66 | 系统电压，支持 `Voltage` 或 `System Voltage`。若 key 包含 `kV` 则自动 *1000。 |
+| Power Factor | 0.95 | 功率因数 (0-1)。 |
+
 ## 📈 场景说明 (Scenarios)
 
 1.  **Scenario 1 (Standard)**：仅使用非可选（标准）电缆进行优化。

generate_template.py

@@ -1,7 +1,7 @@
 import pandas as pd
 import numpy as np
 
-def create_template():
+def create_template(output_file='windfarm_template.xlsx'):
     # Create sample data similar to the internal generator
     data = []
     
@@ -58,7 +58,6 @@ def create_template():
     df_params = pd.DataFrame(param_data)
     
     # Save to Excel
-    output_file = 'windfarm_template.xlsx'
     with pd.ExcelWriter(output_file) as writer:
         df.to_excel(writer, sheet_name='Coordinates', index=False)
         df_cables.to_excel(writer, sheet_name='Cables', index=False)

gui.py

@@ -230,6 +230,7 @@ def index():
 
             # 更新文件显示区域
             if refs["current_file_container"]:
+                # refs["current_file_container"].set_visibility(True)
                 refs["current_file_container"].clear()
                 with refs["current_file_container"]:
                     with ui.row().classes(
@@ -846,16 +847,23 @@ def index():
     with ui.row().classes("w-full p-4 gap-4"):
         with ui.card().classes("w-full p-4 shadow-md"):
             ui.label("配置面板").classes("text-xl font-semibold mb-4 border-b pb-2")
-            with ui.row(align_items='center').classes('w-full'):
+            
+            # 使用 items-stretch 确保所有子元素高度一致
+            with ui.row().classes('w-full items-stretch gap-4'):
+                # 1. 导出模板按钮
                 async def export_template():
                     from generate_template import create_template
                     import shutil
                     async def save_template(path):
-                        # 生成模板到当前目录
+                        # 生成模板到系统临时目录
-                        create_template()
+                        temp_template = os.path.join(state["temp_dir"], "coordinates_template.xlsx")
-                        source = "coordinates.xlsx"
+                        create_template(temp_template)
-                        if os.path.exists(source):
+                        if os.path.exists(temp_template):
-                            shutil.copy2(source, path)
+                            shutil.copy2(temp_template, path)
+                            try:
+                                os.remove(temp_template)
+                            except:
+                                pass
                         else:
                             raise FileNotFoundError("无法生成模板文件")
 
@@ -866,40 +874,29 @@ def index():
                     )
 
                 ui.button("导出 Excel 模板", on_click=export_template).classes(
-                    "  w-1/4"
+                    "flex-1 py-4"
                 ).props("icon=file_download outline color=primary")
 
-                # async def test_save_dialog():
+                # 2. 上传文件区域 (垂直堆叠 Label 和 Upload 组件)
-                #     async def dummy_callback(path):
+                with ui.column().classes('flex-1 gap-0 justify-between'):
-                #         # 仅作为测试，实际不写入文件，只弹出通知
-                #         ui.notify(f"测试成功！选定路径: {path}", type="info")
-
-                #     await save_file_with_dialog(
-                #         "test_save_dialog.txt", dummy_callback, "Text Files (*.txt)"
-                #     )
-
-                # ui.button("测试对话框", on_click=test_save_dialog).classes(
-                #     "w-full mb-4"
-                # ).props("icon=bug_report outline color=orange")
-                with ui.column().classes('w-1/4'):
-                    ui.label("1. 上传坐标文件 (.xlsx)").classes("font-medium")
-
                     # 使用 .no-list CSS 隐藏 Quasar 默认列表，完全自定义文件显示
                     refs["upload_widget"] = ui.upload(
                         label="选择Excel文件", on_upload=handle_upload, auto_upload=True
-                    ).classes("w-full mb-2 no-list")
+                    ).classes("w-full no-list h-full").props('flat bordered color=primary')
                     
                     # 自定义文件显示容器
-                    refs["current_file_container"] = ui.column().classes("w-full mb-4")
+                    refs["current_file_container"] = ui.column().classes("w-full")
-                    with refs["current_file_container"]:
+                    # 初始状态不显示任何内容，直到选择文件后才显示
-                        ui.label("未选择文件").classes("text-xs text-gray-500 italic ml-1")
+                    # with refs["current_file_container"]:
+                    #     ui.label("未选择文件").classes("text-xs text-gray-500 italic ml-1")
 
+                # 3. 运行按钮
                 refs["run_btn"] = (
                     ui.button(
                         "运行方案对比",
                         on_click=run_analysis,
                     )
-                    .classes("w-1/4 py-4")
+                    .classes("flex-1 py-4")
                     .props("icon=play_arrow color=secondary")
                 )
 

使用说明/使用说明.md

@@ -0,0 +1,163 @@
+# 海上风电场集电线路设计优化软件 - 操作手册
+
+**文档版本：** v1.0  
+**适用对象：** 海上能源业务开发部 - 电气专业组  
+**编制日期：** 2026年1月5日
+
+---
+
+## 1. 软件概述
+
+本软件专为海上风电场内集电系统（35kV/66kV/110kV）设计，旨在通过多种先进的拓扑优化算法（如Esau-Williams、MST、旋转扫描法），辅助电气工程师快速完成集电线路的路径规划与经济性比选。
+
+软件能够根据风机坐标、海缆载流量及造价数据，自动计算并生成线损最小、投资最优的接线方案，并支持一键导出 CAD 图纸和海缆长度。
+
+---
+
+## 2. 准备工作：输入数据编制
+
+软件通过读取 Excel 文件获取设计输入条件。为了确保计算准确，请严格按照以下格式准备数据。
+
+### 2.1 获取标准模板
+启动软件后，点击左侧配置面板顶部的 **“导出 Excel 模板”** 按钮，保存 `coordinates.xlsx` 文件。建议在此模板基础上进行修改。
+
+![图示：软件主界面左侧配置面板，高亮“导出 Excel 模板”按钮](导出模板按钮截图.png)
+
+### 2.2 数据表详解
+
+输入文件通常包含三个 Sheet（工作表）：
+![图示：输入数据表](输入数据表.png)
+#### (1) Coordinates (坐标数据) - **[必须]**
+录入升压站和所有风机的位置及参数。
+*   **Type**: 填写 `Substation` (升压站) 或 `Turbine` (风机)。
+*   **ID**: 设备编号（如 Sub1, 01, 02...）。
+*   **X / Y**: 投影坐标（单位：米）。建议使用高斯投影坐标 (X, Y)，以保证距离计算准确。
+*   **Power**: 设备功率（单位：MW）。升压站填 0。
+*   **PlatformHeight**: 塔筒/升压站平台高度（单位：米），用于计算海缆爬升段长度。
+
+<!-- ![图示：Excel中Coordinates工作表的填写范例](占位符-坐标数据表截图) -->
+
+#### (2) Cables (电缆规格) - **[必须]**
+录入本项目拟采用的海缆截面库。
+*   **Section**: 导体截面 (mm²)。
+*   **Capacity**: 额定载流量 (A)。**注意：** 需填入考虑降容系数后的实际允许载流量。
+*   **Resistance**: 交流电阻 (Ω/km)。
+*   **Cost**: 综合单价 (元/m)。包含本体及敷设费用。
+*   **Optional**: 可选标记。
+    *   填 `Y`: 表示该型号为“可选大截面电缆”（例如仅在特定大负荷回路使用）。
+    *   *规则：* 列表中必须按截面**从小到大**排序。
+
+#### (3) Parameters (系统参数) - **[必须]**
+定义系统级电气参数。
+*   **Voltage**: 集电系统标称电压（如 66 或 35），单位 kV。
+*   **Power Factor**: 系统功率因数（如 0.95）。
+
+---
+
+## 3. 算法与优化策略介绍
+
+本软件内置了四种不同机制的拓扑优化算法，分别适用于不同的工程场景。在点击“运行”后，系统会并发执行所有算法，模型自动筛选最优解。
+
+### 3.1 最小生成树算法 (MST Method)
+*   **原理**：基于图论中的 Kruskal 或 Prim 算法，寻找连接所有风机且总路径长度最短的树状结构。此算法**不考虑电缆载流量限制**。
+*   **作用**：仅作为理论上的“距离基准”参考。它展示了如果导线无限粗、电流无限制情况下的最短布线可能。在实际工程中通常不可行，但可用于评估其他方案的距离效率。
+
+### 3.2 基础扇区扫描法 (Capacitated Sweep - Base)
+*   **原理**：以升压站为中心，将平面划分为若干个扇区。算法按顺时针方向扫描风机，一旦累积功率达到当前最大电缆的承载上限，就进行“切分”，形成一个独立的集电回路。
+*   **特点**：计算速度极快，拓扑结构简单清晰，类似于人工排布的辐射状接线。
+*   **局限**：对起始扫描角度敏感，可能因为恰好在某个位置切分而导致该回路包含距离很远的风机。
+
+### 3.3 旋转扫描优化法 (Rotational Sweep)
+*   **原理**：这是对“基础扇区扫描法”的增强版。它会自动尝试 0° 到 360° 之间的所有可能的起始扫描角度。
+*   **优势**：通过旋转扫描角度，可以有效避免因特定方位角切分不当造成的“长尾巴”连线，通常能比基础扫描法节省 3%~8% 的线缆成本。这是最接近人工精细化排布的自动化算法。
+
+### 3.4 Esau-Williams 启发式算法 (Esau-Williams Heuristic)
+*   **原理**：经典的约束最小生成树（CMST）算法。它从“所有风机都直连升压站”的初始状态开始，迭代计算“将两台风机互联并断开其中一条回升压站连线”所能带来的成本节省（Trade-off）。在满足载流量约束的前提下，优先执行节省最大的互联操作。
+*   **优势**：能够跳出辐射状的思维定式，自动发现树状、多分叉等复杂但更经济的拓扑结构。在风机分布不规则、离岸距离较远或电缆造价极高的情况下，往往能得到比扫描法更优的结果。
+
+---
+
+## 4. 操作流程
+
+### 步骤一：启动软件
+双击运行程序，等待主界面加载完成。界面分为上侧“操作区”和下侧“结果展示区”。
+
+### 步骤二：上传数据
+在上侧“配置面板”中，点击 **“选择Excel文件”** 区域（或点击云朵图标），选择编制好的项目 Excel 文件。
+
+上传成功后：
+1.  文件名右侧会出现绿色对勾。
+2.  右侧信息面板会自动解析并显示**系统参数**（电压、功率因数）和**电缆规格列表**，请务必核对这些数据是否正确。
+
+![图示：文件上传成功后的状态，以及右侧参数预览面板](数据加载成功截图.png)
+
+### 步骤三：运行计算
+点击左侧下方的大型按钮 **“运行方案对比”**。
+
+软件将自动执行以下计算任务：
+1.  **多场景分析**：
+    *   *Scenario 1 (标准)*：仅使用标准电缆库进行优化。
+    *   *Scenario 2 (含可选)*：尝试引入更大截面的可选电缆，评估是否能减少回路数。
+    *   *Scenario 3 (限制)*：模拟最大截面电缆缺货情况下的次优方案。
+2.  **多算法寻优**：对每个场景同时运行 MST、基础扫描、旋转扫描、Esau-Williams 等多种算法。
+
+*注意：计算过程中下方黑色日志窗口会实时滚动显示计算进度，通常耗时 10-60 秒，取决于风机数量。*
+
+![图示：正在计算时的进度条和日志窗口](计算过程截图.png)
+
+### 步骤四：查看与比选
+计算完成后，系统会自动筛选出**综合造价最低**的推荐方案，并在界面上展示。
+
+1.  **结果列表**：
+    右侧中部的表格列出了所有计算出的可行方案。
+    *   `Cost (万元)`：总投资估算。
+    *   `Loss (kW)`：全场集电线路总线损。
+    *   **操作**：点击表格中的任意一行，下方的拓扑图会自动切换到该方案。
+
+2.  **拓扑可视化**：
+    右侧下方的绘图区展示集电线路走向。
+    *   不同颜色的线条代表不同截面的海缆。
+    *   图例会标明线型对应的截面。
+    *   升压站显示为红色方块，风机为圆点。
+
+![图示：结果对比表格和拓扑图联动展示](结果比选交互截图.png)
+
+---
+
+## 5. 成果导出
+
+比选确定最终方案后，可以使用底部的 **“导出与下载”** 功能区生成设计文件。
+
+### 5.1 导出 CAD 图纸 (.dxf)
+*   **导出推荐方案**：直接点击 **“导出推荐方案 DXF”**。
+*   **导出特定方案**：在表格中选中任意一行，点击 **“导出选中方案 DXF”**。
+
+生成的 DXF 文件特点：
+*   **分层管理**：不同截面的电缆位于不同图层（Layer），方便在 AutoCAD 中通过图层过滤器批量修改线型或颜色。
+*   **地理坐标**：图纸保留了 Excel 中的原始坐标系，可直接通过“原点粘贴”功能合并到项目总图中。
+
+![图示：导出的DXF图纸在CAD中打开的效果](CAD图纸效果示例.png)
+
+### 5.2 导出 Excel 报告
+点击 **“下载 Excel 对比表”**，将生成一份包含详细工程数据的 Excel 文件，内容包括：
+*   **Summary**: 所有方案的经济技术指标汇总。
+*   **Details**: 推荐方案的每一条海缆连接明细（起点、终点、长度、型号、负载率）。
+
+### 5.3 批量归档
+点击 **“导出全部方案 DXF (ZIP)”**，可将所有计算产生的方案图纸和报表打包下载，便于项目归档。
+
+---
+
+## 6. 常见问题 (FAQ)
+
+**Q: 为什么上传文件后提示“电缆数据校验失败”？**
+A: 请检查 `Cables` 表。电缆必须严格按照**截面从小到大**排列，且载流量也必须随截面增加而增加。如果定义了 `Optional` 电缆，它必须是列表中截面最大的一条。
+
+**Q: 计算出的方案有的回路负载率过高怎么办？**
+A: 软件算法以不超过额定载流量为约束条件（默认允许 100% 满载）。在实际工程中，建议在 `Cables` 表录入载流量时，预先乘以 0.95 或其他安全系数，留出裕度。
+
+**Q: 图纸导出后，在 CAD 里看不到东西？**
+A: 请双击鼠标滚轮（Zoom Extents）全屏显示。由于风机坐标通常是大地坐标（数值很大），如果 CAD 当前视口在 (0,0) 附近，可能会找不到图形。
+
+---
+**技术支持：** 海上能源业务开发部 - 数字化小组