windfarm/IFLOW.md

# 海上风电场集电线路设计优化系统 - 项目上下文

## 项目概述

这是一个用于设计和优化海上风电场集电系统拓扑的综合工具，专为海上能源业务开发部电气专业设计。该系统通过多种先进的拓扑优化算法（MST、旋转扫描法、Esau-Williams等），根据风机坐标、功率以及海缆规格，自动生成投资成本最低、损耗最优的设计方案。

### 核心功能
- 🖥️ **图形化界面**：基于 NiceGUI 的现代化桌面应用，支持原生窗口模式
- 🌊 **多种布局生成**：支持规则网格和随机分布布局的模拟数据生成
- 🔌 **多算法优化**：
  - MST (Minimum Spanning Tree)：无容量约束基准方案
  - Capacitated Sweep (Base)：基础扇区扫描分组
  - Rotational Sweep：全局最优起始角度旋转扫描优化
  - Esau-Williams：经典启发式算法，在距离与容量间寻找最优平衡
- ⚙️ **灵活参数配置**：通过 Excel 自定义系统电压、功率因数、电价及电缆规格
- 📊 **智能方案对比**：自动运行三大场景（标准方案、含可选电缆方案、限制最大截面方案）
- 📁 **多格式导出**：CAD图纸(.dxf)、Excel报告、压缩包

### 技术栈
- **语言**：Python 3.12+
- **GUI框架**：NiceGUI 3.4.1 + PyWebview 6.1
- **核心库**：
  - numpy 2.4.0：数值计算
  - pandas 2.3.3：数据处理
  - matplotlib 3.10.8：可视化
  - scikit-learn 1.8.0：聚类算法
  - networkx 3.6.1：图算法
  - ezdxf 1.4.3：CAD导出
  - scipy 1.16.3：科学计算

## 项目结构

```
D:\code\windfarm\
├── main.py                 # 核心算法和业务逻辑（1388行）
├── gui.py                  # NiceGUI图形界面（1067行）
├── esau_williams.py        # Esau-Williams算法实现（242行）
├── generate_template.py    # Excel模板生成器
├── make_version.py         # 版本号自动生成脚本
├── pyproject.toml          # 项目依赖配置
├── Makefile                # 构建脚本
├── 使用说明/               # 中文操作手册和截图
├── build/                  # 构建输出目录
└── dist/                   # 打包输出目录
```

## 构建和运行

### 环境配置
项目使用 `uv` 作为包管理器，也支持 `pip`：

```bash
# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -r requirements.txt  # 如果有requirements.txt
# 或手动安装依赖
pip install numpy pandas matplotlib scikit-learn scipy networkx ezdxf nicegui openpyxl pywebview
```

### 运行方式

#### 1. 图形化界面（推荐）
```bash
python gui.py
```
启动后，程序将弹出独立窗口，提供完整的交互式界面。

#### 2. 命令行模式
```bash
python main.py --excel your_data.xlsx
```

### 构建可执行文件

使用 Makefile 进行构建：

```bash
# 构建exe文件（自动生成版本号）
make build

# 重新构建（先清理再构建）
make rebuild

# 清理构建文件
make clean

# 查看帮助
make help
```

构建过程：
1. 运行 `make_version.py` 生成版本号
2. 使用 `nicegui-pack` 打包为单文件exe
3. 重命名输出文件包含版本号

构建输出位于 `dist/` 目录，文件名格式：`海上风电场集电线路设计优化系统_{VERSION}.exe`

## 输入数据规范

### Excel文件格式
输入Excel文件应包含以下三个Sheet：

#### 1. Coordinates（坐标数据）- 必需
| Type | ID | X | Y | Power | PlatformHeight |
|------|----|---|---|-------|----------------|
| Substation | Sub1 | 4000 | -800 | 0 | 0 |
| Turbine | 1 | 0 | 0 | 8.0 | 25 |

- **Type**: `Substation` 或 `Turbine`
- **X/Y**: 投影坐标（米），建议使用高斯投影坐标
- **Power**: 功率（MW），升压站填0
- **PlatformHeight**: 塔筒/平台高度（米）

#### 2. Cables（电缆规格）- 必需
| CrossSection | Capacity | Resistance | Cost | Optional |
|--------------|----------|------------|------|----------|
| 35 | 150 | 0.524 | 80 | |
| 400 | 580 | 0.0470 | 600 | Y |

- **CrossSection**: 导体截面（mm²）
- **Capacity**: 额定载流量（A），需考虑降容系数
- **Resistance**: 交流电阻（Ω/km）
- **Cost**: 综合单价（元/m）
- **Optional**: 可选标记（Y表示可选大截面电缆）

**重要规则**：
- 电缆必须按截面从小到大排列
- `Optional` 为 'Y' 的电缆最多只能有一条
- 若存在可选电缆，它必须是列表中截面最大的一条

#### 3. Parameters（系统参数）- 必需
| Parameter | Value |
|-----------|-------|
| Voltage (kV) / 电压 (kV) | 66 |
| Power Factor / 功率因数 | 0.95 |
| Electricity Price (元/kWh) / 电价 (元/kWh) | 0.4 |

## 核心算法说明

### 1. MST（最小生成树）
- **原理**：基于 Kruskal 或 Prim 算法，寻找连接所有风机且总路径长度最短的树状结构
- **特点**：不考虑电缆载流量限制，仅作为理论距离基准参考
- **适用场景**：小规模风电场的理论分析

### 2. Capacitated Sweep（基础扇区扫描）
- **原理**：以升压站为中心，将平面划分为扇区，按顺时针扫描风机
- **特点**：计算速度快，拓扑结构简单清晰
- **局限**：对起始扫描角度敏感，可能产生"长尾巴"连线

### 3. Rotational Sweep（旋转扫描优化）
- **原理**：尝试 0° 到 360° 之间的所有起始扫描角度
- **优势**：比基础扫描法节省 3%~8% 的线缆成本
- **适用场景**：最接近人工精细化排布的自动化算法

### 4. Esau-Williams 启发式算法
- **原理**：约束最小生成树（CMST）算法，迭代计算互联操作的成本节省
- **优势**：能发现树状、多分叉等复杂但更经济的拓扑结构
- **适用场景**：风机分布不规则、离岸距离较远或电缆造价极高的情况

## 方案场景说明

系统自动运行三种场景：

1. **Scenario 1 (Standard)**：仅使用非可选（标准）电缆进行优化
2. **Scenario 2 (With Optional)**：包含标记为 'Y' 的大型电缆，适用于尝试增加单回路容量
3. **Scenario 3 (No Max)**：排除最大截面电缆，测试电缆供应受限时的最优拓扑

## 输出文件说明

- **Excel报告**：`[文件名]_result.xlsx` - 包含所有方案总览及详细连接清单
- **CAD图纸**：`design_[方案名].dxf` - 分层分色的拓扑图
- **全部方案**：`[文件名]_result.zip` - 包含所有图纸及Excel报告

## 关键常量和配置

### 电气参数
- **系统电压**：66,000 V (66kV)
- **功率因数**：0.95
- **电价**：0.4 元/kWh

### 电缆规格示例
- 最小截面：35mm² (载流量150A)
- 最大截面：400mm² (载流量580A)
- 降容系数：0.8（实际载流量 = 额定载流量 × 0.8）

### 算法参数
- 默认风机数量：30台
- 默认布局：随机分布或网格
- 默认间距：800米（网格布局）

## 开发约定

### 代码风格
- 使用中文注释和文档字符串
- 函数命名使用 snake_case
- 类名使用 PascalCase
- 常量使用 UPPER_CASE

### 版本管理
- 版本号通过 `make_version.py` 自动生成
- 版本号格式：v{major}.{minor}.{patch}
- 版本号存储在 `version.py` 文件中

### 构建约定
- 使用 `nicegui-pack` 进行打包
- 单文件模式（--onefile）
- 无窗口模式（--windowed）
- 输出文件名包含版本号

### 测试约定
- GUI测试使用 frontend-tester agent
- Python代码测试使用 python-pro agent
- 测试覆盖率要求：核心算法部分 > 80%

## 常见问题

### Q1: MST算法显示极高的成本和损耗？
**A**: 这是预期行为。MST算法不考虑载流量约束，会产生单一树状结构导致根部电缆严重过载。这仅作为理论基准参考。

### Q2: 如何在CAD图纸中找到图形？
**A**: 双击鼠标滚轮（Zoom Extents）全屏显示。风机坐标通常是大地坐标（数值很大），如果CAD当前视口在(0,0)附近，可能会找不到图形。

### Q3: 可选电缆的使用规则是什么？
**A**: 
- 可选电缆（Optional='Y'）最多只能有一条
- 必须是列表中截面最大的电缆
- 用于特定场景（如增加单回路容量）

## 技术支持

- **适用对象**：海上能源业务开发部 - 电气专业
- **技术支持**：杜孟远
- **文档版本**：v1.0
- **编制日期**：2026年1月5日

## 许可证

本项目仅供工程学习、研究和初步设计评估使用。详细计算应以专业设计院规范为准。