# api-tutorial

**Repository Path**: s100177/api-tutorial

## Basic Information

- **Project Name**: api-tutorial
- **Description**: 接口资料
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-24
- **Last Updated**: 2025-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### **一、水泵过流曲线参数率定模型 - 接口培训文档**

-----

#### **1、 业务背景：为何要进行水泵过流曲线率定？（使用场景）**

  在泵站的日常运营中，水泵的实际性能会随着时间的推移而发生变化。尽管设备出厂时都附带一条标准的“扬程-流量（H-Q）”性能曲线，但在实际运行中，由于以下因素，水泵的特性曲线会逐渐偏离初始状态：

  * **物理损耗**：叶轮的磨损、腐蚀或泵体内的结垢。
  * **运行影响**：长期存在的汽蚀现象对叶轮造成损伤。
  * **机械老化**：轴承磨损导致间隙增大，或密封圈老化失效。

  这些因素将直接导致水泵的扬-程能力下降、运行效率降低。如果调度、控制和能耗分析系统仍依赖于出厂时那条理想化的曲线，将会产生越来越大的误差，最终导致：

  * **调度决策失准**：无法实现最优化的开机组合，造成能源浪费。
  * **能耗分析偏差**：错误的能耗计算会误导节能改造的决策。
  * **运维成本增加**：无法准确评估水泵健康状况，可能导致非预期的故障。

  因此，**定期根据泵站的实测运行数据，对水泵的H-Q曲线进行重新率定（校准），是实现泵站精细化管理和节能降耗的关键环节。**

-----

#### **2、 技术核心：模型是如何工作的？（模型原理）**

  本接口的核心原理是利用数学方法，根据您提供的实测数据，自动拟合出一条最能反映当前水泵性能的H-Q曲线。

1.  **核心思想**：
    我们认为，水泵的扬程（H）与流量（Q）之间存在一个稳定的函数关系。这个关系通常可以通过一个多项式函数来近似描述：
    $$H = a_0 + a_1 Q + a_2 Q^2 + \dots + a_n Q^n$$
    我们的任务就是找到一组最合适的系数 $(a_0, a_1, a_2, \dots, a_n)$。

2.  **拟合算法**：**最小二乘法 (Least Squares Method)**
    这是实现曲线拟合的经典算法。它的目标是寻找到一组系数，使得模型根据这些系数计算出的预测扬程 $(\hat{H})$ 与您提供的实测扬程 $(H)$ 之间的总误差（具体来说是误差的平方和）最小。
    其数学目标函数为：
    $$\min \sum_{i=1}^{m} (H_i - \hat{H}_i)^2$$
    其中：

      * $H_i$ 是第 $i$ 个数据点的**实测扬程**。
      * $\hat{H}_i$ 是将第 $i$ 个数据点的**实测流量** $Q_i$ 代入拟合函数后计算出的**模型预测扬程**。

3.  **接口封装**：
    您无需关心复杂的数学计算过程。**本接口已将数据处理、模型求解和结果生成完全自动化**。您只需要按照规定的格式准备数据并调用接口，即可获得精准的拟合结果。

-----

#### **3、 实践操作：如何调用接口？（API 使用指南）**

##### **步骤 1：准备数据文件**

  首先，您需要将实测的“流量-扬程”数据整理到一个文件中。

  * **文件格式**：推荐使用 **CSV (逗号分隔值)** 格式，这是最通用和结构清晰的格式。
  * **文件内容**：文件必须包含至少两列数据，一列为流量，一列为扬程。**列名必须是 `flow_rate` 和 `pump_head`**。

**CSV 文件示例 (`pump_data.csv`)**:

```csv
flow_rate,pump_head
3.5,25.2
3.8,24.8
4.0,24.5
4.2,23.9
4.5,23.1
4.8,22.0
```

**注意**：

  * 确保使用英文字符，且列名完全匹配。
  * 数据点越多、覆盖的流量范围越广，拟合结果越准确。建议至少提供5个有效数据点。

##### **步骤 2：发起 API 请求**

  通过向指定的URL发送HTTP POST请求来调用模型服务。

  * **接口地址 (Endpoint)**： `http://localhost:80/pumpoverflowed/predict`
  * **请求方法 (Method)**： `POST`
  * **请求头 (Headers)**： `Content-Type: multipart/form-data` (因为需要上传文件)
  * **请求体 (Body)**： 请求体需要包含一个 `files` 字段，其值为一个JSON数组，描述您要上传的文件。

**请求体 JSON 结构**:

```json
{
    "files": [
        {
            "name": "file",  // 属性名，固定为 "file"
            "filename": "pump_data.csv" // 您准备的数据文件名
        }
    ]
}
```

##### **步骤 3：解析返回结果**

  接口会返回一个JSON对象，您需要根据 `code` 字段判断请求是否成功。

  * **调用成功**:
    当 `code` 字段为 `200` 时，表示模型计算成功。
    **成功返回示例**:

    ```json
    {
        "code": 200,
        "data": {
            "model_id": "bfa8e6a1-c3a7-4bde-9a2c-7f8d9e0a1b3c",
            "Ret": "H = -0.857*Q^2 + 1.234*Q + 28.5"
        },
        "message": "success"
    }
    ```

    **字段说明**:

      * `model_id`: 本次成功计算生成的唯一算法ID，可用于追踪和记录。
      * `Ret`: **(核心结果)** 拟合出的H-Q曲线函数表达式。您可以将此公式更新到您的业务系统中，用于后续的调度和能耗分析。

  * **调用失败**:
    当 `code` 字段为 `400` 时，表示请求处理失败。
    **失败返回示例**:

    ```json
    {
        "code": 400,
        "data": null,
        "message": "Server error: Input file must contain 'flow_rate' and 'pump_head' columns."
    }
    ```

    **字段说明**:

      * `message`: 描述了具体的失败原因，例如：文件格式错误、缺少必要的列、服务器内部错误等。请根据此信息检查您的输入数据和请求。

-----

#### **4、 附录：Python 调用示例**

  以下是一个使用 Python `requests` 库调用本接口的完整代码示例。

```python
import requests
import json

# 接口信息
api_url = "http://localhost:80/pumpoverflowed/predict"

# 待上传的数据文件路径
file_path = "pump_data.csv"
file_name = "pump_data.csv"

# 准备请求体中的文件部分
# 'file' 是后端接收文件的字段名，需要与接口定义一致
# (file_name, open(file_path, 'rb'), 'text/csv') 是一个元组，
# 分别表示：文件名、文件对象、文件类型
files_to_upload = {
    'file': (file_name, open(file_path, 'rb'), 'text/csv')
}

try:
    # 发起POST请求
    response = requests.post(api_url, files=files_to_upload)

    # 检查HTTP响应状态码
    response.raise_for_status()  # 如果状态码不是200，将引发HTTPError异常

    # 解析返回的JSON数据
    result = response.json()

    # 打印结果
    print("API Response:")
    print(json.dumps(result, indent=4, ensure_ascii=False))

    # 根据返回的code字段进行业务处理
    if result.get("code") == 200:
        print("\n--- [SUCCESS] ---")
        model_id = result["data"]["model_id"]
        formula = result["data"]["Ret"]
        print(f"模型ID (Model ID): {model_id}")
        print(f"拟合公式 (Fitted Formula): {formula}")
    else:
        print("\n--- [FAILED] ---")
        error_message = result.get("message", "Unknown error")
        print(f"错误信息 (Error Message): {error_message}")

except requests.exceptions.RequestException as e:
    print(f"\n请求API时发生网络或HTTP错误: {e}")
except Exception as e:
    print(f"\n处理过程中发生未知错误: {e}")

```





### **二、水轮机过流曲线参数率定模型 - 接口培训文档**


-----

#### **1、 业务背景：为何要进行水轮机参数率定？（使用场景）**

  水轮机是水电站的核心能量转换设备，其运行性能直接关系到整个电站的发电效率和经济效益。水轮机过流曲线和参数率定模型，本质上是用于精确描述水轮机在不同流量、水头等工作条件下性能特性的数学模型。

  在实际工程中，建立并持续校准该模型至关重要，主要原因如下：

  * [cite_start]**性能评估与优化**：精确的模型是水轮机优化设计和运行管理的基础。通过率定后的曲线，可以准确评估机组在当前工况下的出力和效率，指导最优调度。
  * **状态偏离监控**：随着运行时间的增长，水轮机因磨损、气蚀等原因，实际性能会偏离出厂设计值。定期率定可以量化这种偏离，为设备检修和维护提供数据支持。
  * **发电量预测**：在进行发电计划或电力市场交易时，准确的出力曲线是预测未来发电量的关键，直接影响经济决策。

  本模型接口旨在通过自动化建模，帮助您快速、准确地获取符合机组当前实际状况的性能曲线。

-----

#### **2、 技术核心：模型是如何工作的？（模型原理）**

  本接口的核心是利用实测运行数据，通过算法拟合出水轮机出力、工作水头和流量之间的数学关系。

1.  **核心思想**：
    模型的根本任务是找到一个函数，用以描述水轮机出力（Power）与工作水头（Head）、流量（Flow）之间的关系。这个函数通常是一个多元多项式。

2.  **拟合算法**：**最小二乘法 (Least Squares Method)**

      * **定义**：这是一种在回归分析中广泛应用的数学优化技术，其目标是通过最小化误差的平方和来寻找数据的最佳函数匹配。
      * **目标**：算法的目标是找到一组模型参数（即多项式系数），使得模型根据这些参数计算出的预测值与实际观测值之间的总体差异最小。
      * **目标函数**：算法致力于最小化以下目标函数 $S$：
        $$S = \sum_{i=1}^{n} (y_i - \hat{y}_i)^2$$
        其中：
          * $y_i$ 是第 $i$ 组数据的**实际观测值**（例如，实测的水轮机出力）。
          * $\hat{y}_i$ 是将第 $i$ 组工况数据（例如，水头和流量）代入拟合函数后得到的**模型预测值**。
      * **参数求解**：通过对目标函数 $S$ 中的每一个未知参数求偏导数，并令其等于零，可以构建一个方程组。解这个方程组，就能得到最优的参数值。

3.  **接口封装**：

   您无需进行任何复杂的数学推导和求解。本接口服务将上述数据处理、模型拟合、参数求解的过程完全自动化。您只需提供标准格式的运行数据，即可通过接口调用获得最终的拟合公式。

-----

#### **3、 实践操作：如何调用接口？（API 使用指南）**

##### **步骤 1：准备数据文件**

  首先，您需要将水轮机的实测运行数据整理到一个文件中。

  * **文件格式**：推荐使用 **CSV (逗号分隔值)** 格式。
  * **文件内容**：文件必须包含以下四列，**列名必须与下表中的 "Key" 完全匹配**。

| Key | 说明 | 数据类型 | 单位 |
| :--- | :--- | :--- | :--- |
| `updam_water_level` | 坝前水位 | Float | m |
| `downdam_water_level` | 坝后水位 | Float | m |
| `flow` | 过水轮机流量 | Float | m³/s |
| `power` | 水轮机出力 | Float | Kw |

**CSV 文件示例 (`turbine_data.csv`)**:

```csv
updam_water_level,downdam_water_level,flow,power
125.5,75.2,85.6,35200.5
125.6,75.3,88.1,36150.0
125.4,75.1,90.5,37000.8
125.8,75.5,82.3,34800.2
```

**注意**：模型会自动根据 `updam_water_level` 和 `downdam_water_level` 计算工作水头。请确保数据点充足且能覆盖机组常见运行区间。

##### **步骤 2：发起 API 请求**

  通过向指定的URL发送HTTP `POST`请求来调用模型服务。

  * **接口地址 (Endpoint)**： `http://localhost:80/turbineoverflowed/predict`
  * **请求方法 (Method)**： `POST`
  * **请求头 (Headers)**： `Content-Type: multipart/form-data`
  * **请求体 (Body)**： 请求体需包含一个 `files` 字段，其值为一个JSON数组，用于描述上传的文件。

**请求体 JSON 结构**:

```json
{
    "files": [
        {
            "name": "file",
            "filename": "turbine_data.csv"
        }
    ]
}
```

##### **步骤 3：解析返回结果**

  接口将返回一个JSON对象，通过 `code` 字段判断请求的成功与否。

  * **调用成功**:
    `code` 为 `200` 表示模型计算成功。
    **成功返回示例**:

    ```json
    {
        "code": 200,
        "data": {
            "model_id": "cfa9f7b2-d4b8-4cff-9d3d-8g9e1f0b2c4d",
            "Ret": "Power = -0.15*H*Q^2 + 450.5*H*Q - 250.3"
        },
        "message": "success"
    }
    ```

    **字段说明**:

      * `model_id`: 本次计算生成的唯一算法ID，可用于结果追溯。
      * `Ret`: **(核心结果)** 拟合出的水轮机出力（Power）、水头（H）、流量（Q）之间的关系表达式。您可以将此公式集成到您的业务系统中。

  * **调用失败**:
    `code` 为 `400` 表示请求处理失败。
    **失败返回示例**:

    ```json
    {
        "code": 400,
        "data": null,
        "message": "Missing property: Input file is missing the required 'flow' column."
    }
    ```

    **字段说明**:

      * `message`: 描述了具体的失败原因（如文件属性缺失、服务器错误等），请根据此信息排查问题。

-----

#### **4、 附录：Python 调用示例**

  以下是一个使用 Python `requests` 库调用本接口的完整代码示例。

```python
import requests
import json

# API接口地址
api_url = "http://localhost:80/turbineoverflowed/predict"

# 准备好的数据文件路径
file_path = "turbine_data.csv"
file_name = "turbine_data.csv"

# 构造 multipart/form-data 请求
# 'file' 是后端定义好的接收文件的字段名
files_to_upload = {
    'file': (file_name, open(file_path, 'rb'), 'text/csv')
}

try:
    # 发起POST请求，上传文件
    response = requests.post(api_url, files=files_to_upload)

    # 检查HTTP响应码是否为2xx（成功）
    response.raise_for_status()

    # 解析返回的JSON结果
    result = response.json()

    # 美化输出
    print("API Response:")
    print(json.dumps(result, indent=4, ensure_ascii=False))

    # 根据业务码(code)判断并处理结果
    if result.get("code") == 200:
        print("\n--- [SUCCESS] ---")
        model_id = result["data"]["model_id"]
        formula = result["data"]["Ret"]
        print(f"模型ID (Model ID): {model_id}")
        print(f"拟合公式 (Fitted Formula): {formula}")
    else:
        print("\n--- [FAILED] ---")
        error_message = result.get("message", "An unknown error occurred.")
        print(f"错误信息 (Error Message): {error_message}")

except requests.exceptions.RequestException as e:
    print(f"\nAPI request failed due to a network or HTTP error: {e}")
except Exception as e:
    print(f"\nAn unexpected error occurred: {e}")

```


### **三、水闸过流曲线参数率定模型 - 接口培训文档**

-----

#### **1、 业务背景：为何要进行水闸参数率定？（使用场景）**

  节制闸是水利工程中关键的挡水和泄水建筑物，其核心功能是通过启闭闸门来精确调节上游水位和下泄流量 。为了给工程运行人员提供可靠的闸门操作指导，必须依赖准确的过流曲线。

  然而，理论公式往往无法完全反映现场的复杂情况。参数率定的必要性在于：

  * **现场条件复杂**：水闸的实际过流能力受到其具体结构参数（如闸门宽度、流道形状）、水流特性（如流速、摩擦）以及环境因素（如河道泥沙沉积）的综合影响。
  * **提升运营精度**：通过利用长期的现场观测数据（水位、流量）来率定（校准）实际的过流公式，可以生成一条真正符合当前工程状况的过流曲线，从而实现精细化、智能化的调度。

  本模型接口旨在通过自动化分析，将复杂的率定过程简化为一次API调用，为您提供精准可靠的闸门操作依据。

-----

#### **2、 技术核心：模型是如何工作的？（模型原理）**

  本接口内部封装了完整的水力学分析与数学拟合流程，将复杂的率定过程自动化。其核心技术步骤如下：

1.  **步骤一：流态自动判别 (Automatic Flow Regime Identification)**
    闸门在不同开度和上下游水位条件下，其过闸水流形态是不同的。模型首先会根据您输入的数据，自动判别每个数据点所属的流态。主要流态包括：

      * **孔流 (Hole Flow)** 与 **堰流 (Weir Flow)**：根据闸门开度 `e` 和闸前水头 `H` 的相对关系（如 $\frac{e}{H}$）进行判断。
      * **自由出流 (Free Flow)** 与 **淹没出流 (Submerged Flow)**：根据下游水位是否对过流能力产生影响来判断。
        最终，水流会被精确分类为自由孔流、淹没孔流、自由堰流、淹没堰流四种情况之一 。

2.  **步骤二：流量系数反算 (Discharge Coefficient Back-calculation)**
    每一种流态都对应一个经典的水力学过流公式 [cite: 21]。例如：

      * **自由孔流**：$Q = M_1 e B_g \sqrt{2gH}$ 
      * **自由堰流**：$Q = M_2 B_g \sqrt{2gH^{3/2}}$
        在这些公式中，$M$ 代表综合流量系数，它综合了淹没、侧收缩等多种复杂因素。模型会根据判别的流态，选用对应的公式，并利用您提供的实测流量数据反算出每个数据点的实际综合流量系数 $M$。

3.  **步骤三：关系拟合与公式生成 (Relationship Fitting and Formula Generation)**
    反算出的流量系数$M$并非一个常数，它会随着闸门开度、水位等条件变化。模型的最后一步，也是最关键的一步，是采用**最小二乘法 (Least Squares Method)** ，通过最小化误差的平方和，来拟合出综合流量系数与其他主要参数（如开度、水头）之间的函数关系。最终，模型会将这个函数关系与基础物理公式结合，生成一个统一、精准且适用于您工程实际的过流曲线表达式。

**接口封装优势**：您无需关心上述复杂的流态判别和分步计算。您只需提供原始的监测数据，接口将自动完成所有分析，并直接返回最终的、可直接使用的率定后公式。

-----

#### **3、 实践操作：如何调用接口？（API 使用指南）**

##### **步骤 1：准备数据文件**

  您需要将水闸的实测运行数据整理到一个文件中。

  * **文件格式**：推荐使用 **CSV (逗号分隔值)** 格式。
  * **文件内容**：文件必须包含以下五列，**列名必须与下表中的 "Key" 完全匹配** 。

| Key | 说明 | 数据类型 | 单位 |
| :--- | :--- | :--- | :--- |
| `upstream_water_level` | 闸前水位 | Float | m |
| `downstream_water_level` | 闸后水位 | Float | m |
| `flow_rate` | 过闸流量 | Float | m³/s |
| `gate_opening` | 闸门开度 | Float | m |
| `gate_width` | 闸门过水宽度 | Float | m |

**CSV 文件示例 (`sluice_gate_data.csv`)**:

```csv
upstream_water_level,downstream_water_level,flow_rate,gate_opening,gate_width
8.52,3.15,150.5,1.5,20
8.55,3.18,180.2,1.8,20
8.60,3.20,250.8,2.0,20
8.62,3.21,280.1,2.2,20
```

##### **步骤 2：发起 API 请求**

  通过向指定的URL发送HTTP `POST`请求来调用模型服务。

  * **接口地址 (Endpoint)**： `http://localhost:80/gateoverflowed/predict`
  * **请求方法 (Method)**： `POST`
  * **请求头 (Headers)**： `Content-Type: multipart/form-data`
  * **请求体 (Body)**： 请求体需包含一个 `files` 字段，其值为一个JSON数组，用于描述上传的文件。

**请求体 JSON 结构**:

```json
{
    "files": [
        {
            "name": "file",
            "filename": "sluice_gate_data.csv"
        }
    ]
}
```

##### **步骤 3：解析返回结果**

  接口将返回一个JSON对象，通过 `code` 字段判断请求的成功与否。

  * **调用成功**:
    `code` 为 `200` 表示模型计算成功。
    **成功返回示例**:

    ```json
    {
        "code": 200,
        "data": {
            "model_id": "eac1f9d4-f6a0-4cff-8e5f-0a1b3d5e2c7f",
            "Ret": "Q = (0.65 - 0.05 * (O/H)) * O * W * sqrt(2*g*H)"
        },
        "message": "success"
    }
    ```

    **字段说明**:

      * `model_id`: 本次计算生成的唯一算法ID，可用于结果追溯。
      * `Ret`: **(核心结果)** 拟合出的适用于该水闸的过流曲线表达式。公式中的变量（如Q, O, H, W）分别对应流量、开度、水头和宽度。

  * **调用失败**:
    `code` 为 `400` 表示请求处理失败。
    **失败返回示例**:

    ```json
    {
        "code": 400,
        "data": null,
        "message": "Missing property: Input file is missing the required 'gate_opening' column."
    }
    ```

    **字段说明**:

      * `message`: 描述了具体的失败原因（如文件属性缺失、数据列不全等），请根据此信息排查问题。

-----

#### **4、 附录：Python 调用示例**

  以下是一个使用 Python `requests` 库调用本接口的完整代码示例。

```python
import requests
import json

# API接口地址
api_url = "http://localhost:80/gateoverflowed/predict"

# 准备好的数据文件路径
file_path = "sluice_gate_data.csv"
file_name = "sluice_gate_data.csv"

# 构造 multipart/form-data 请求
# 'file' 是后端定义好的接收文件的字段名
files_to_upload = {
    'file': (file_name, open(file_path, 'rb'), 'text/csv')
}

try:
    # 发起POST请求，上传文件
    response = requests.post(api_url, files=files_to_upload)

    # 检查HTTP响应码是否为2xx（成功）
    response.raise_for_status()

    # 解析返回的JSON结果
    result = response.json()

    # 美化输出
    print("API Response:")
    print(json.dumps(result, indent=4, ensure_ascii=False))

    # 根据业务码(code)判断并处理结果
    if result.get("code") == 200:
        print("\n--- [SUCCESS] ---")
        model_id = result["data"]["model_id"]
        formula = result["data"]["Ret"]
        print(f"模型ID (Model ID): {model_id}")
        print(f"拟合公式 (Fitted Formula): {formula}")
    else:
        print("\n--- [FAILED] ---")
        error_message = result.get("message", "An unknown error occurred.")
        print(f"错误信息 (Error Message): {error_message}")

except requests.exceptions.RequestException as e:
    print(f"\nAPI request failed due to a network or HTTP error: {e}")
except Exception as e:
    print(f"\nAn unexpected error occurred: {e}")
```




### **四、堰坝过流曲线参数率定模型 - 接口培训文档**


-----

#### **1、 业务背景：为何要进行堰坝参数率定？（使用场景）**

  堰坝是水利工程中用于调节水流、蓄水或防洪的关键水流控制结构。准确描述其在不同水头（水位差）下的过流能力，对于洪水管理、水资源优化分配等领域具有至关重要的应用价值。

  过流曲线描述了不同水位条件下，流经堰坝的流量与水位的关系。然而，理论公式计算出的流量往往与实际情况存在偏差，因为理论模型难以完全涵盖现场所有复杂因素。为了在实际工程中能够精确评估和预测堰坝的过流能力，必须通过参数率定方法，利用现场实测的水文数据对模型参数进行优化和校准。

  本模型接口尤其适用于带有闸门的堰坝（Gated Weir），通过自动化建模，帮助您快速获得一个最贴近工程实际的过流曲线表达式。

-----


#### **2、 技术核心：模型是如何工作的？（模型原理）**

  本接口内部封装了完整的水力学分析与数学拟合流程，将复杂的率定过程自动化。其核心是模拟水力学专家的分析过程：首先根据工况判断水流形态，然后选择对应的物理公式进行计算，最后通过数据拟合得到一个统一的、适用于您工程实际的经验公式。

其核心技术步骤如下：

##### **步骤一：流态自动判别 (Automatic Flow Regime Identification)**

模型接收到您的数据（包含闸门开度$e$、闸前水头$H$、下游水深$hs$等）后，会对每一个数据点进行独立的流态判别。

1.  **判别孔流或堰流** ：

      * 模型计算闸门开度与闸前水头的比值 $e/H$。
      * 对于宽顶堰，若 $e/H <= 0.65$，则为闸孔出流；若 $e/H > 0.65$，则为堰流。
      * 对于实用堰，若 $e/H <= 0.75$，则为闸孔出流；若 $e/H > 0.75$，则为堰流。

2.  **判别自由出流或淹没出流** ：

      * 模型根据下游水位判断其是否对上游过流能力产生影响。
      * 例如对于宽顶堰，若下游水深与闸前水头的比值 $hs/H0 > 0.8$，则为淹没出流；反之为自由出流。

##### **步骤二：匹配公式并反算流量系数 (Formula Matching and Coefficient Calculation)**

根据步骤一判别的流态，模型会自动为该数据点匹配对应的水力学物理公式，并利用您提供的实测流量$Q$，反算出该工况下的综合流量系数$M$。

  * 若为**自由孔流**，则匹配公式：
    $$Q = M_1 e B_g \sqrt{2gH}$$
    并求解出 $M_1$。
  * 若为**自由堰流**，则匹配公式：
    $$Q = M_2 B_g \sqrt{2gH^{\frac{3}{2}}}$$
    并求解出 $M_2$。
  * 若为**淹没孔流**，则匹配公式：
    $$Q = M_3 e B_g \sqrt{2g(H - h_s)}$$
    并求解出 $M_3$。
  * 若为**淹没堰流**，则匹配公式：
    $$Q = M_4 B_g H \sqrt{2g(H - h_s)}$$
    并求解出 $M_4$。

对所有数据点重复此过程后，模型会得到一组与每个工况一一对应的流量系数值 $M$。

##### **步骤三：关系拟合与公式生成 (Relationship Fitting and Formula Generation)**

反算出的流量系数$M$并非一个恒定值，它会随工况（如$e/H$等）变化。模型的最后一步，是采用**最小二乘法 (Least Squares Method)** ，通过最小化误差的平方和 ，找到一个最佳的函数关系 $M = f(e, H, ...)$ 来描述流量系数的变化规律。

最终，模型将这个拟合出的函数$f(e, H, ...)$ 代入基础物理公式，从而生成一个统一、精准且适用于您工程实际的过流曲线表达式，并作为结果返回。
```mermaid
graph TD
    A["开始: 接收数据文件"] --> B{"处理下一条实测数据"};
    B --> C{"计算 e/H 比值"};
    C --> D{"判断是孔流还是堰流"};
    D -- "孔流" --> E["流态: 孔流"];
    D -- "堰流" --> F["流态: 堰流"];
    E --> G{"判断下游淹没条件"};
    F --> G;
    G --> I{"判断是自由流还是淹没流"};
    I -- "自由" --> J["选择自由流公式类型"];
    I -- "淹没" --> K["选择淹没流公式类型"];
    J --> L["匹配对应的水力学公式"];
    K --> L;
    L --> M["反算出流量系数 M"];
    M --> N{"所有数据点都已处理?"};
    N -- "否" --> B;
    N -- "是" --> O["收集所有流量系数值"];
    O --> P["拟合流量系数函数"];
    P --> Q["生成最终过流曲线表达式"];
    Q --> R["结束: 返回拟合公式"];

    subgraph "步骤一：流态判别"
        C
        D
        E
        F
        G
        I
    end

    subgraph "步骤二：系数反算"
        J
        K
        L
        M
    end
    
    subgraph "步骤三：拟合生成"
        O
        P
        Q
    end
```

**接口封装优势**：您无需关心复杂的流态判别和分步计算。您只需提供原始的监测数据，接口将自动完成所有分析，并直接返回最终的、可直接使用的率定后公式。

-----

#### **3、 实践操作：如何调用接口？（API 使用指南）**

##### **步骤 1：准备数据文件**

您需要将堰坝的实测运行数据整理到一个文件中。

  * **文件格式**：推荐使用 **CSV (逗号分隔值)** 格式。
  * **文件内容**：文件必须包含以下五列，**列名必须与下表中的 "Key" 完全匹配**。

| Key | 说明 | 数据类型 | 单位 |
| :--- | :--- | :--- | :--- |
| `upstream_water_level` | 闸前水位 | Float | m |
| `downstream_water_level` | 闸后水位 | Float | m |
| `flow_rate` | 过闸流量 | Float | m³/s |
| `gate_opening` | 闸门开度 | Float | m |
| `gate_width` | 闸门过水宽度 | Float | m |

**CSV 文件示例 (`weir_dam_data.csv`)**:

```csv
upstream_water_level,downstream_water_level,flow_rate,gate_opening,gate_width
12.6,9.5,85.5,1.0,30
12.8,9.6,120.2,1.2,30
13.0,9.6,205.7,1.5,30
13.1,9.7,240.9,1.8,30
```

##### **步骤 2：发起 API 请求**

&emsp;&emsp;通过向指定的URL发送HTTP `POST`请求来调用模型服务。

  * **接口地址 (Endpoint)**： `http://localhost:80/wieroverflowed/predict`
  * **请求方法 (Method)**： `POST`
  * **请求头 (Headers)**： `Content-Type: multipart/form-data`
  * **请求体 (Body)**： 请求体需包含一个 `files` 字段，其值为一个JSON数组，用于描述上传的文件。

**请求体 JSON 结构**:

```json
{
    "files": [
        {
            "name": "file",
            "filename": "weir_dam_data.csv"
        }
    ]
}
```

##### **步骤 3：解析返回结果**

&emsp;&emsp;接口将返回一个JSON对象，通过 `code` 字段判断请求的成功与否。

  * **调用成功**:
    `code` 为 `200` 表示模型计算成功。
    **成功返回示例**:

    ```json
    {
        "code": 200,
        "data": {
            "model_id": "fac2g0e5-g7b1-4dff-9f6g-1b2c4d6e3f8h",
            "Ret": "Q = (0.58 - 0.03 * O) * W * H * sqrt(2*g*(H-h))"
        },
        "message": "success"
    }
    ```

    **字段说明**:

      * `model_id`: 本次计算生成的唯一算法ID，可用于结果追溯。
      * `Ret`: **(核心结果)** 拟合出的适用于该堰坝的过流曲线表达式。公式中的变量（如Q, O, W, H, h）可分别对应流量、开度、宽度、闸前水头、闸后水深等。

  * **调用失败**:
    `code` 为 `400` 表示请求处理失败。
    **失败返回示例**:

    ```json
    {
        "code": 400,
        "data": null,
        "message": "Server error: Input file must contain 'upstream_water_level' and 'downstream_water_level' columns."
    }
    ```

    **字段说明**:

      * `message`: 描述了具体的失败原因（如文件属性缺失、数据列不全等），请根据此信息排查问题。

-----

#### **4、 附录：Python 调用示例**

&emsp;&emsp;以下是一个使用 Python `requests` 库调用本接口的完整代码示例。

```python
import requests
import json

# API接口地址
api_url = "http://localhost:80/wieroverflowed/predict"

# 准备好的数据文件路径
file_path = "weir_dam_data.csv"
file_name = "weir_dam_data.csv"

# 构造 multipart/form-data 请求
# 'file' 是后端定义好的接收文件的字段名
files_to_upload = {
    'file': (file_name, open(file_path, 'rb'), 'text/csv')
}

try:
    # 发起POST请求，上传文件
    response = requests.post(api_url, files=files_to_upload)

    # 检查HTTP响应码是否为2xx（成功）
    response.raise_for_status()

    # 解析返回的JSON结果
    result = response.json()

    # 美化输出
    print("API Response:")
    print(json.dumps(result, indent=4, ensure_ascii=False))

    # 根据业务码(code)判断并处理结果
    if result.get("code") == 200:
        print("\n--- [SUCCESS] ---")
        model_id = result["data"]["model_id"]
        formula = result["data"]["Ret"]
        print(f"模型ID (Model ID): {model_id}")
        print(f"拟合公式 (Fitted Formula): {formula}")
    else:
        print("\n--- [FAILED] ---")
        error_message = result.get("message", "An unknown error occurred.")
        print(f"错误信息 (Error Message): {error_message}")

except requests.exceptions.RequestException as e:
    print(f"\nAPI request failed due to a network or HTTP error: {e}")
except Exception as e:
    print(f"\nAn unexpected error occurred: {e}")
```