# 多方法水文设计计算工具 Python 版

## 启动

外发测试优先使用安装器：

```text
http://49.233.123.54
```

测试人员在下载页点击 `下载安装器`，运行 `HydrologySetup.exe` 后，会安装到当前 Windows 用户目录，并创建桌面快捷方式 `水文计算软件`。后续发布新版时，用户继续从桌面图标启动即可自动更新。

备用压缩包解压后，双击：

```powershell
START_WINDOWS.bat
```

测试包内置 `hydrology_launcher.exe`，正常情况下测试人员不需要安装 Python。

开发调试时可在当前目录运行：

```powershell
python launcher.py
```

程序使用 Python 标准库 `tkinter`，不依赖第三方包。

`launcher.py` 会先检查云端版本，有新版本时下载、校验 SHA256、备份当前文件并替换，再启动 `run_app.py`。开发调试时仍可直接运行 `python run_app.py`。

## 联网登录开发模式

当前已接入在线授权登录 MVP。开发环境先启动本地授权服务器：

```powershell
python -m pip install -r server\requirements.txt
python server\run_dev_server.py
```

默认测试账号：

- 手机号：`13800138000`
- 密码：`Hydro@2026`

授权服务器地址写在 `version.json`，当前正式测试地址为 `http://49.233.123.54`。更换服务器时只修改 `auth.server_url`，不要在各模块中重复写地址。

客户端启动后会先做在线授权心跳；正式上线版本将 `auth.required=true` 且 `offline_grace_days=0`，确保禁用账号或撤销会话后不能继续离线绕过。

云端后台地址为 `http://49.233.123.54/admin`。后台账号仅管理员使用，可查看用户、设备、登录会话和版本信息，并可修改账号套餐、到期日、最大设备数、新密码，或启用/禁用账号。

## 发布更新

发布客户端更新时，先修改代码和 `version.json` 版本号，再打包：

```powershell
python -m PyInstaller --onefile --noconsole --clean --noconfirm --name hydrology_launcher --hidden-import ctypes --hidden-import csv --hidden-import dataclasses --hidden-import getpass --hidden-import html --hidden-import html.parser --hidden-import platform --hidden-import socket --hidden-import tkinter --hidden-import tkinter.ttk --hidden-import tkinter.scrolledtext --hidden-import tkinter.filedialog --hidden-import tkinter.messagebox --hidden-import uuid --hidden-import webbrowser --hidden-import xml.etree.ElementTree --hidden-import xml.sax.saxutils launcher.py
Copy-Item .\dist\hydrology_launcher.exe .\hydrology_launcher.exe -Force
python tools\build_client_package.py
```

脚本默认输出到 `D:\workspace`，生成核心运行包 `hydrology_client_<版本>.zip`、可选资料包 `hydrology_reference_<版本>.zip`、完整离线包 `hydrology_client_offline_<版本>.zip` 和轻量更新包 `hydrology_update_<版本>.zip`。在线首装只下载核心运行包；资料和验收材料按需提供，完整离线包仅用于无网络项目现场。云端 `set-version` 的 `download-url` 与 `sha256` 必须指向带版本号的更新包，不能指向可被 CDN 长缓存覆盖的 `latest` 文件。测试者继续双击 `START_WINDOWS.bat` 即可在关闭软件后获取更新。

重新生成正式安装器时执行：

```powershell
python -m PyInstaller --noconfirm HydrologySetup.spec
Copy-Item .\dist\HydrologySetup.exe D:\workspace\HydrologySetup.exe -Force
```

安装器自身不再嵌入客户端压缩包，而是下载带版本号的核心运行包；后续更新通过云端 `/api/app/version` 指向带版本号的轻量更新包完成。安装器逻辑变化或发布新核心版本时，需要重新生成并上传 `HydrologySetup.exe`。

## 已包含方法

- 铁一院两所法
- 中小河流经验公式法
- 水文面积比拟法
- 双对数内插法
- 洪水合成法
- 地区经验公式法
- 瞬时单位线法
- 推理公式法
- 水库调洪演算（等水面Modified Puls法）
- 曼宁公式水位
- 能量方程水位
- 多断面能量方程法（HEC标准步法）
- 堰流公式水位
- 波浪高度与风壅水位
- 桥孔最小净长度
- 河道演变计算
- 壅水高度及长度
- 冲刷计算

## 相比原 VBA 的修正

- 不再依赖 `.xlsm` 宏工程，避免工作簿内没有 VBA 模块导致按钮失效。
- 铁一院法改为结构化输出，不存在 Excel 列错位问题。
- 铁一院法不再用 `H24_5` 代替 `H24_2`；缺少 `H24_2` 时不计算 `Q2` 并给出提示。
- 铁一院法的 `A1/A2/n/beta1` 都是用户输入，不再只是说明中“可调”。
- 地区经验法取消 8-20 行限制，计算核心可处理任意条数据。
- 地区经验法必须显式选择分区，不会在下拉框缺失时默认第 1 分区。
- 地区经验法会校验 `F<...`、`F>...`、`a<F<b` 形式的适用面积范围。
- 地区经验法第 63 分区 `0.1%` 系数已由原误录 `92.22×10^-3` 修正为 `2.22×10^-3`，程序内部 `K=0.00222`。
- 水文面积比拟法计算 n 值时会处理回归分母为 0 的情况。
- 中小河流法把 `Kp` 是否参与雨量修正做成显式选项。
- 瞬时单位线法按项目雨型分区和流域面积自动选择综合雨型主雨峰：`F<100km2` 取 1h，`100<=F<=300km2` 取 3h，`300<F<=1000km2` 取 6h。
- 瞬时单位线法输入 `Ptc均值 + Cv + Cs/Cv`，按内置 P-III 公式自动计算 7 个频率的 `Kp` 和 `Ptc`。
- `资料` 菜单可打开内置的 `皮尔逊Ⅲ型曲线模比系数计算.xls`，并可查看 P-III 公式说明。

## 验证

```powershell
python -m py_compile run_app.py hydrology_app\__init__.py hydrology_app\core.py hydrology_app\reservoir_routing.py hydrology_app\gui.py
python -m unittest discover tests
```

当前已通过 134 个自动化测试。
