# WaterAllocationModel **Repository Path**: s100177/WaterAllocationModel ## Basic Information - **Project Name**: WaterAllocationModel - **Description**: 调水模型接口初步设计文档 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-07-04 - **Last Updated**: 2025-07-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README @[TOC](调水接口说明 ### 接口说明 ### 一、 月调水模型water-allocation-opt（损失最小）   优化思路：给定各个区域的损失率和输水保证区间，怎么让输水损失最小，且满足输水的保证区间，如果给定的输水保证区间无法满足，则允许一定的偏差； | 请求类型 | 接口路径 | 描述 | | ---- | ----------------------- | ------------------------ | | POST | `/water-allocation-opt` | 提交带有水量损失率和供水保障率的水量调度分配请求 | ##### 请求体字段说明： | 字段名 | 类型 | 描述 | 示例 | | ------------------- | --- | ------------------------------------- | -------------- | | `year_total` | 整数 | 年总水量（单位：万立方米） | 10000 | | `allocation_method` | 字符串 | 水量分配方法（`"proportional"` 或 `"custom"`） | "proportional" | | `district_demands` | 对象 | 各区县的水量需求和属性 | 见下方字段详情 | ##### district_demands对象字段说明： | 字段名 | 类型 | 描述 | 示例 | | ----------------------- | -- | --------------------------- | ---------------- | | `demands` | 对象 | 区县的月需求量（键为“YYYY-MM”格式） | `"2025-11": 0.3` | | `water_loss_rate` | 浮动 | 区县的输水损失率（小数表示，例如：0.05表示5%） | 0.05 | | `supply_guarantee_rate` | 浮动 | 区县的供水保障率（小数表示，例如：0.95表示95%） | 0.95 | ##### 示例请求体： ```json { "year_total": 10000, "allocation_method": "proportional", "district_demands": { "高村": { "demands": { "2025-11": 0.3, "2025-12": 0.4, "2026-01": 0.4, "2026-02": 0.3, "2026-03": 0.3, "2026-04": 0.3, "2026-05": 0.3, "2026-06": 0.2 }, "water_loss_rate": 0.05, "supply_guarantee_rate": 0.95 }, "其他区县": { "demands": { "2025-11": 0.5, "2025-12": 0.6, "2026-01": 0.6, "2026-02": 0.5, "2026-03": 0.5, "2026-04": 0.5, "2026-05": 0.5, "2026-06": 0.4 }, "water_loss_rate": 0.05, "supply_guarantee_rate": 0.95 } } } ``` ##### 示例响应： 为使这个 JSON 响应更适合作为 API 接口返回值，建议加入以下信息： 1. **状态码（status）**：标识请求是否成功； 2. **消息（message）**：提供描述性信息，便于前端或调用方理解； 3. **数据体（data）**：原始的区县占比数据； 4. （可选）**时间戳、版本、请求 ID** 等元信息。 --- ### ✅ 响应示例： ```json { "status": 200, "message": "数据获取成功", "data": { "高村": { "2025-11": 0.3, "2025-12": 0.4, "2026-01": 0.4, "2026-02": 0.3, "2026-03": 0.3, "2026-04": 0.3, "2026-05": 0.3, "2026-06": 0.2 }, "其他区县": { "2025-11": 0.5, "2025-12": 0.6, "2026-01": 0.6, "2026-02": 0.5, "2026-03": 0.5, "2026-04": 0.5, "2026-05": 0.5, "2026-06": 0.4 } } } ``` --- ### 状态码解释： | 状态码 | 含义 | 适用场景示例 | | --- | ------- | ------------- | | 200 | 成功 | 正常返回数据 | | 400 | 请求参数错误 | 缺少区县名或时间范围等 | | 404 | 数据未找到 | 查询的时间段内无数据 | | 500 | 服务器内部错误 | 后端处理异常或数据库故障等 | ### 二、 月调水模型 water-allocation-ruler (基于规则) | 请求类型 | 接口路径 | 描述 | | ---- | ------------------------- | ------------------------ | | POST | `/water-allocation-ruler` | 提交不带水量损失率和供水保障率的水量调度分配请求 | ##### 请求体字段说明： | 字段名 | 类型 | 描述 | 示例 | | ------------------- | --- | ------------------------------------- | -------------- | | `year_total` | 整数 | 年总水量（单位：万立方米） | 10000 | | `district_demands` | 对象 | 各区县的水量需求 | 见下方字段详情 | ##### district_demands 对象字段说明： | 字段名 | 类型 | 描述 | 示例 | | --------- | -- | ---------------------- | ---------------- | | `demands` | 对象 | 区县的月需求量（键为“YYYY-MM”格式） | `"2025-11": 0.3` | | `supply_guarantee_rate` | 浮动 | 区县的供水保障率（小数表示，例如：0.95表示95%） | 0.95 | ##### 示例请求体： ```json { "year_total": 10000, "allocation_method": "proportional", "district_demands": { "高村": { "demands": { "2025-11": 0.3, "2025-12": 0.4, "2026-01": 0.4, "2026-02": 0.3, "2026-03": 0.3, "2026-04": 0.3, "2026-05": 0.3, "2026-06": 0.2 }, "supply_guarantee_rate": 0.95 }, "其他区县": { "demands": { "2025-11": 0.5, "2025-12": 0.6, "2026-01": 0.6, "2026-02": 0.5, "2026-03": 0.5, "2026-04": 0.5, "2026-05": 0.5, "2026-06": 0.4 }, "supply_guarantee_rate": 0.95 } } } ``` ##### 示例响应： --- ### **响应格式** ```json { "status": 200, "message": "各区县月度占比数据获取成功", "data": { "regions": [ { "name": "高村", "monthly_proportions": { "2025-11": 0.3, "2025-12": 0.4, "2026-01": 0.4, "2026-02": 0.3, "2026-03": 0.3, "2026-04": 0.3, "2026-05": 0.3, "2026-06": 0.2 } }, { "name": "其他区县", "monthly_proportions": { "2025-11": 0.5, "2025-12": 0.6, "2026-01": 0.6, "2026-02": 0.5, "2026-03": 0.5, "2026-04": 0.5, "2026-05": 0.5, "2026-06": 0.4 } } ] }, "timestamp": "2025-06-30T14:10:00+08:00" } ``` --- ### 说明： | 字段 | 原因与好处 | | ------------------------------------ | ------------------------------- | | `"status"` | 标准 HTTP 语义或自定义业务状态码，利于调用方判断请求结果 | | `"message"` | 提供语义信息，便于日志记录和调试 | #### 请求/响应说明： * **`water-allocation-opt`**：此接口用于提交带有水量损失率和供水保障率的请求，适用于需要考虑损失和保障的分配方法。 * **`water-allocation-ruler`**：此接口用于提交不带水量损失率和供水保障率的请求，适用于只基于需求进行分配的情况。 ### 三、 月调水模型water-allocation-order(基于规则，带优先级排序) | 请求类型 | 接口路径 | 描述 | | ---- | ------------------------- | ----------------- | | POST | `/water-allocation-ruler` | 提交带优先级排序的水量调度分配请求 | ##### 请求体字段说明： | 字段名 | 类型 | 描述 | 示例 | | ------------------- | --- | ------------------------------------- | ---------------------- | | `year_total` | 整数 | 年总水量（单位：万立方米） | 10000 | | `district_demands` | 对象 | 各区县的水量需求和优先级信息 | 见下方字段详情 | | `district_priority` | 对象 | 区县的优先级，值越小优先级越高 | `{"高村": 1, "其他区县": 2}` | ##### `district_demands` 对象字段说明： | 字段名 | 类型 | 描述 | 示例 | | ----------------------- | -- | --------------------------- | ---------------- | | `demands` | 对象 | 区县的月需求量（键为“YYYY-MM”格式） | `"2025-11": 0.3` | | `supply_guarantee_rate` | 浮动 | 区县的供水保障率（小数表示，例如：0.95表示95%） | 0.95 | ##### 示例请求体： ```json { "year_total": 10000, "allocation_method": "proportional", "district_priority": { "高村": 1, "其他区县": 2 }, "district_demands": { "高村": { "demands": { "2025-11": 0.3, "2025-12": 0.4, "2026-01": 0.4, "2026-02": 0.3, "2026-03": 0.3, "2026-04": 0.3, "2026-05": 0.3, "2026-06": 0.2 }, "supply_guarantee_rate": 0.95 }, "其他区县": { "demands": { "2025-11": 0.5, "2025-12": 0.6, "2026-01": 0.6, "2026-02": 0.5, "2026-03": 0.5, "2026-04": 0.5, "2026-05": 0.5, "2026-06": 0.4 }, "supply_guarantee_rate": 0.95 } } } ``` ##### 示例响应： ```json { "status": 200, "message": "数据获取成功", "data": { "高村": { "2025-11": 0.3, "2025-12": 0.4, "2026-01": 0.4, "2026-02": 0.3, "2026-03": 0.3, "2026-04": 0.3, "2026-05": 0.3, "2026-06": 0.2 }, "其他区县": { "2025-11": 0.5, "2025-12": 0.6, "2026-01": 0.6, "2026-02": 0.5, "2026-03": 0.5, "2026-04": 0.5, "2026-05": 0.5, "2026-06": 0.4 } } } ``` #### 请求/响应说明： * **`district_priority`**: 该字段是新增加的，用于表示区域的优先级。值越小，优先级越高。例如，`"高村": 1` 表示 `高村` 区的优先级比 `"其他区县": 2` 高，`高村` 将首先获得水量分配。 * **`district_demands`**: 与原先一致，用于提供各区县的月度水量需求。 #### 逻辑说明： * 根据 `district_priority` 提供的优先级，系统将按优先级顺序处理各区县的水量分配。 * 系统首先会处理优先级最小的区县（即值为1的区县），然后依此类推处理优先级较高的区县。 * 如果总水量不足以满足所有区县的需求，优先级较高的区县将优先获得水量分配。 * `district_demands`: 若指定了供水保证率，则优先级最高，先满足有供水保证率的，其他的再按顺序分配； ### 四、 日调水接口设计 (按日调水分配) #### 1. 接口概述 该接口用于调水操作，输出未来一个月每天的每个闸站的过闸流量和闸前水位时序。 #### 2. 接口路径与请求方法 | 请求类型 | 接口路径 | 描述 | | ---- | ------------------------- | --------------- | | POST | `/daily-water-regulation` | 提交按日调水请求并获取调水结果 | #### 3. 请求体字段说明 | 字段名 | 类型 | 描述 | 示例 | | -------------------- | -- | ----------------------------- | ------------------------------ | | `total_water_supply` | 整数 | 每月的总供水量（单位：万立方米） | 10000 | | `initial_conditions` | 对象 | 每个闸站的初始水位和流量 | 见下方字段详情 | | `planned_discharge` | 对象 | 未来一段时间每天的计划分水量 | 见下方字段详情 | | `gate_constraints` | 对象 | 每个闸站的过闸流量和水位约束 | 见下方字段详情 | | `time_period` | 数组 | 未来一个月的每天时间段，日期格式为`YYYY-MM-DD` | `["2025-11-01", "2025-11-02"]` | ##### `initial_conditions` 对象字段说明： | 字段名 | 类型 | 描述 | 示例 | | ------------- | -- | ------------------- | ---- | | `water_level` | 浮动 | 每个闸站的初始水位（单位：米） | 15.0 | | `flow_rate` | 浮动 | 每个闸站的初始流量（单位：立方米/秒） | 25.0 | ##### `planned_discharge` 对象字段说明： | 字段名 | 类型 | 描述 | 示例 | | ----------- | -- | -------------------- | ---------------------------------------- | | `discharge` | 对象 | 每个闸站未来一段时间的计划分水量（每天） | `{"2025-11-01": 200, "2025-11-02": 250}` | ##### `gate_constraints` 对象字段说明： | 字段名 | 类型 | 描述 | 示例 | | ------------- | -- | --------------------- | ---- | | `flow_limit` | 浮动 | 每个闸站的过闸流量约束（单位：立方米/秒） | 300 | | `level_limit` | 浮动 | 每个闸站的水位约束（单位：米） | 20.0 | #### 4. 示例请求体 ```json { "total_water_supply": 10000, "initial_conditions": { "闸站A": { "water_level": 15.0, "flow_rate": 25.0 }, "闸站B": { "water_level": 12.0, "flow_rate": 30.0 } }, "planned_discharge": { "闸站A": { "2025-11-01": 200, "2025-11-02": 250 }, "闸站B": { "2025-11-01": 300, "2025-11-02": 350 } }, "gate_constraints": { "闸站A": { "flow_limit": 300, "level_limit": 20.0 }, "闸站B": { "flow_limit": 350, "level_limit": 18.0 } }, "time_period": ["2025-11-01", "2025-11-02"] } ``` #### 5. 示例响应 ```json { "status": 200, "message": "闸站日调度数据获取成功", "data": { "stations": [ { "name": "闸站A", "daily_records": { "2025-11-01": { "discharge_flow": 200, "water_level": 15.5 }, "2025-11-02": { "discharge_flow": 250, "water_level": 16.0 } } }, { "name": "闸站B", "daily_records": { "2025-11-01": { "discharge_flow": 300, "water_level": 13.5 }, "2025-11-02": { "discharge_flow": 350, "water_level": 14.0 } } } ] }, "timestamp": "2025-06-30T14:30:00+08:00" } ``` #### 6. 请求/响应说明 * **`total_water_supply`**: 提供每月的总供水量（单位：万立方米），用于整体水量分配。 * **`initial_conditions`**: 包含每个闸站的初始水位和流量，供调水算法根据初始状态进行水量分配。 * **`planned_discharge`**: 包括每个闸站的计划分水量（每日）。此数据决定了未来几天内每个闸站所需的水量。 * **`gate_constraints`**: 每个闸站的过闸流量和水位约束，用于确保调水操作在物理限制内。 * **`time_period`**: 未来一段时间的每天，格式为`YYYY-MM-DD`，用于规定水量调度的时间范围。 #### 7. 逻辑说明 1. **水量分配**: 根据用户提供的每月总供水量和每天的计划分水量，系统需根据闸站的初始状态和约束条件，计算出每个闸站在每一天的过闸流量和水位。 2. **流量与水位计算**: 系统应根据初始水位和流量，结合每天的分水量计算水位变化。同时，确保每个闸站的过闸流量不超过流量约束，且水位不超过设定的水位上限。 3. **约束验证**: 如果某一时刻的流量或水位超出约束，系统应该提示错误。