|
|
@@ -0,0 +1,164 @@
|
|
|
+# 调度配置功能需求
|
|
|
+
|
|
|
+> 状态：需求梳理初稿，2026-10-19；2026-10-21 根据测试服抓包补充发布/删除接口，关闭 Q-03、Q-09、Q-11；确定调度模式定义表与高级修改范围，关闭 Q-01、Q-12、Q-13、Q-14。本文记录重构后的目标能力和待确认的产品口径；实现方式写入 technical-design 和 ui-design。现状与问题见 [current-state.md](current-state.md)。
|
|
|
+
|
|
|
+## 1. 目标与范围
|
|
|
+
|
|
|
+重构“调度配置”模块，使其成为**云端 TOU 调度模版的完整管理工具**，并替代外部“配置编辑器”：
|
|
|
+
|
|
|
+1. 查看模版列表与详情（生产服、测试服）；
|
|
|
+2. 在测试服新增、编辑模版（发布、删除放到后续迭代）；
|
|
|
+3. 导出模版（生产服、测试服）；
|
|
|
+4. 生产服模版与指定测试服模版对比，显示差异。
|
|
|
+
|
|
|
+**范围内**：仅通过 FWH 云平台（hes-gateway）接口管理模版。
|
|
|
+
|
|
|
+**范围外**：
|
|
|
+
|
|
|
+- 不直接通过 MQTT 向设备下发或读取调度（355/357 协议），后续也不考虑绕过 FWH Server；wiki《ScriptingForSchedulingConfiguration》是 FWH Server 与设备之间的协议，仅作设计参考，字段格式不照搬；
|
|
|
+- 不再兼容外部“配置编辑器”的 JSON 格式；
|
|
|
+- 生产服不提供任何写操作；
|
|
|
+- AI/MCP 对接放到第二阶段（见第 5 节）。
|
|
|
+
|
|
|
+## 2. 功能需求
|
|
|
+
|
|
|
+### FR-01 菜单与环境
|
|
|
+
|
|
|
+- 主菜单“调度配置”，生产服与测试服使用**独立子菜单**。
|
|
|
+- 每个页面只操作所属环境，页面上明确标出环境；一个环境不可用（未配置、登录失败）时不影响另一个环境。
|
|
|
+
|
|
|
+| 能力 | 生产服 | 测试服 |
|
|
|
+| --- | :---: | :---: |
|
|
|
+| 列表 / 详情 | ✓ | ✓ |
|
|
|
+| 导出 | ✓ | ✓ |
|
|
|
+| 新增 / 编辑 | — | ✓ |
|
|
|
+| 发布 / 删除（后续迭代） | — | ✓ |
|
|
|
+| 对比（生产 ↔ 测试） | ✓ | 待定（见 Q-06） |
|
|
|
+
|
|
|
+### FR-02 模版列表
|
|
|
+
|
|
|
+- 分页列表，支持按模版类型、发布状态、关键字过滤。
|
|
|
+- 增加国家、地区过滤（云端接口已支持 `countryId`、`provinceId`），选项来自 `selectCitesList`。
|
|
|
+- 列表至少显示：ID、类型、国家、地区、DER 计划、电力公司、资费套餐、电价类型、发布状态、更新时间。
|
|
|
+
|
|
|
+### FR-03 模版详情
|
|
|
+
|
|
|
+- 展示模版主体信息和全部策略。策略按**季节 × 日类型**组织，工作日与周末/节假日按 `ccociateSn` 配对，不按季节名合并。
|
|
|
+- 每个时段显示：时间段、峰平谷、调度类型（由优先级按第 3 节“解析规则”识别）、设置了的扩展参数；可查看该时段的原始字段。
|
|
|
+- 策略级电价（购电/卖电）按峰平谷显示。
|
|
|
+- 提供 24 小时时间轴等直观视图（具体形式在 ui-design 中确定）。
|
|
|
+- **容错**：数据不符合规则（时段未覆盖整天、配对缺失、未知 `dayType`、无法识别的优先级组合等）时仍应展示，并标出具体问题，不能让整个详情渲染失败。
|
|
|
+
|
|
|
+### FR-04 新增与编辑（仅测试服）
|
|
|
+
|
|
|
+- 支持新建空白模版、编辑已有模版；“基于已有模版复制新建”的范围见 Q-02。
|
|
|
+- **不提供原始字段的直接编辑**。编辑以“选择”为主：
|
|
|
+ - 模版主体：国家/地区下拉、电价类型等枚举选项；
|
|
|
+ - 策略：选择月份、日类型（每天 / 工作日 + 周末节假日），系统自动生成 `ccociateType`、`ccociateSn`、`dayType`、`dayName`；
|
|
|
+ - 时段：编辑时间段与峰平谷，选择调度模式（A～H、强制充电、强制放电等），系统按调度模式定义表写入对应的**标准** `solarPriority`/`loadPriority` 及参数（见第 3 节“写入规则”）。
|
|
|
+- 在模式选择之外提供**高级修改**：除优先级外，时段的其他参数（功率上限/固定功率、SOC、`gcaoMax`、`heatEnable`、`rampTime`、`offGrid`、`solarCutoff`、`powerOffApower` 等）都可以修改，也可以清空为“未设置”。
|
|
|
+- **优先级不开放自定义输入**，只能通过选择调度模式确定，或设置为空（不下发优先级）。设为空时 `solarPriority` 和 `loadPriority` 同时写为空字符串 `""`，不允许只有一个为空。
|
|
|
+- **模式参数约束**：部分模式对参数有约束（见第 3 节扩展模式参数表），分两种：
|
|
|
+ - **固定**：值由模式决定，界面只读，不能修改也不能清空（如 Zero Import 的 `gridFeedMax`）；
|
|
|
+ - **必填**：选择模式时填入默认值，用户可以改数值，但不能清空；必填参数为空时禁止保存。
|
|
|
+ - 优先级对所有模式都相当于“固定”。高级修改中，除优先级和当前模式的固定参数外，其他参数都可以修改或清空。
|
|
|
+- **切换模式**：切换调度模式时，替换优先级，清除原模式的固定/必填参数（新模式也需要的除外）并填入新模式的固定值和默认值；其他高级参数保留。切换前提示将被清除的参数。
|
|
|
+- **保持原值**：编辑已有模版时，用户没有改动的内容保存时必须原样写回，包括非标准的优先级数值（如 `9,9,9`）和其他字段，不做规范化。优先级只在用户对该时段重新选择调度模式（或设为空）时才被替换。保存前的确认弹窗只列出用户实际改动的内容。
|
|
|
+- 保存前校验，校验不通过时禁止保存并定位到具体问题：
|
|
|
+ - 每个策略的时段 00:00→24:00 首尾衔接，无空档、无重叠，格式 `HH:mm`；
|
|
|
+ - 工作日与周末/节假日必须成对，`ccociateSn` 正确；
|
|
|
+ - 月份在各策略间不重叠且覆盖全年（是否强制覆盖全年见 Q-04）；
|
|
|
+ - 数值在合法范围内（功率 kW 精度 0.1，SOC 0～100，`rampTime` 0～300 等）；
|
|
|
+ - 写入时 `sourceType` 只能为 0（系统模版）。
|
|
|
+- 保存前显示确认弹窗，列出本次写入的内容或与原版本的差异；保存后重新读取详情，确认云端结果与提交内容一致。
|
|
|
+
|
|
|
+### FR-05 发布与删除（仅测试服，后续迭代）
|
|
|
+
|
|
|
+- 本期不实现，后续迭代再加。
|
|
|
+- 云端接口已确认：`setStatusIotTouTemplate`，`status=2` 发布、`status=1` 删除（软删除，从列表消失），见 [protocol-observations.md](protocol-observations.md) 第 2 节。
|
|
|
+- 云端没有取消发布的功能（目前只能改数据库），本工具也不提供。
|
|
|
+- 实现时：操作前显示确认弹窗，删除需二次确认。
|
|
|
+
|
|
|
+### FR-06 导出（生产服、测试服）
|
|
|
+
|
|
|
+- 导出单个模版。格式不再沿用外部配置编辑器，具体格式见 Q-05。
|
|
|
+- 文件名包含电力公司简称、DER 计划、模版名称、环境和时间戳。
|
|
|
+
|
|
|
+### FR-07 对比（生产服 ↔ 测试服）
|
|
|
+
|
|
|
+- 在生产服模版上选择一个测试服模版（按 ID 或通过列表搜索）进行对比。
|
|
|
+- 对比覆盖三层：模版主体字段、策略（季节、月份、日类型、电价）、时段（时间段、峰平谷、调度类型、全部参数）。
|
|
|
+- 差异分为：新增、删除、修改；修改项同时显示两边的值。可只看差异，也可显示全部。
|
|
|
+- 策略和时段的对齐规则（按季节名 + 日类型，或按月份 + 日类型；时间段切分不同时如何对比）在技术设计中确定。
|
|
|
+- 两边都只读取，不修改任何一方。
|
|
|
+
|
|
|
+## 3. 共同需求
|
|
|
+
|
|
|
+- **调度模式定义表**：统一定义基础工作模式 A～H（以及强制充电、强制放电等），每个模式包含名称、语义说明、`solarPriority`/`loadPriority` 写入值和必需参数。定义表需可扩展，新增模式只修改这一处；也可以加入使用非标准数值的特殊模式（如 `9,9,9` 的 Zero Import），加入后即可在编辑时选择。详情、编辑、对比、导出共用此表；与 357 日志解析（`parseScheduling.ts`）的关系在技术设计中确定。
|
|
|
+- **解析规则（只用于展示、对比、导出等读取场景）**：优先级每位取值 0～9，`0` 表示不涉及；非 0 值只看相对大小（越大优先级越高，相同表示按比例/功率分配），不要求是 1/2/3。因此 `9,9,9`、`2,5,1` 等任意数值都应显示出正确的调度逻辑。归不到已定义模式的组合显示为“自定义”并给出语义说明，不报错。优先级为空时显示为“未设置优先级”。
|
|
|
+- 解析时先把每组优先级做**稠密排名归一化**：`0` 保持为 `0`，非 0 值按从小到大依次映射为 1、2、3，相同值映射为同一个数。例如 `9,9,9` → `1,1,1`，`2,5,1` → `2,3,1`，`0,5,9` → `0,1,2`。然后用归一化后的结果去匹配 A～H。**特殊模式（如 Zero Import）不参与归一化**，按原始数值精确匹配；例如 `5,5,5` 归一化后是 `1,1,1`，不会被识别为 Zero Import，而是“自定义”。
|
|
|
+
|
|
|
+**调度模式定义表（初版，2026-10-21 确认）**
|
|
|
+
|
|
|
+优先级顺序：光伏 `[市电, 负载, aPower]`，负载 `[市电, 光伏, aPower]`。
|
|
|
+
|
|
|
+| 模式 | 名称 | 光伏优先级 | 负载优先级 | 语义 |
|
|
|
+| --- | --- | --- | --- | --- |
|
|
|
+| A | Excess solar export to grid（光伏余电馈网） | `1,2,0` | `1,3,2` | 光伏优先供载，剩余馈网；不足由 aPower 补，再不足由市电补；aPower 不充电 |
|
|
|
+| B | aPower standby（电池待机） | `1,2,0` | `1,2,0` | 光伏优先供载，剩余馈网；不足由市电补；aPower 不充不放 |
|
|
|
+| C | Excess solar charge aPower（光伏余电充电） | `1,3,2` | `1,2,0` | 光伏优先供载，剩余给 aPower 充电，再剩余馈网；不足由市电补；aPower 不放电 |
|
|
|
+| D | Self-consumption（自发自用） | `1,3,2` | `1,3,2` | 光伏优先供载，剩余充电，再剩余馈网；不足由 aPower 补，再不足由市电补 |
|
|
|
+| E/G | aPower charge from solar / grid（优先充电） | `1,2,3` | `1,2,0` | 光伏优先给 aPower 充电，剩余供载，再剩余馈网；不足由市电补；aPower 不放电。用户在 PCS 设置中使能电网充电时表现为 G |
|
|
|
+| F/H | aPower supply home / export to grid（优先供载） | `1,2,0` | `1,2,3` | aPower 优先供载，光伏馈网；不足由光伏补，再不足由市电补；aPower 不充电。用户在 PCS 设置中使能电池馈网时表现为 H |
|
|
|
+| — | 未设置优先级 | `""` | `""` | 两个优先级同时为空字符串 |
|
|
|
+| 强制充电 | aPower charge from grid / Backup only（强制充电 / 仅备电） | `""` | `""` | 电网不限充电，aPower 以固定功率充电并保持满电 |
|
|
|
+| 强制放电 | aPower forced discharge（强制放电） | `""` | `""` | 不限 aPower 馈网，aPower 以固定功率放电至预留 SOC |
|
|
|
+| Zero Import | Zero Import（零取电，特殊模式） | `9,9,9` | `9,9,9` | 时段内尽量不从电网取电，由 aPower 放电供载，馈网限制在极小值；按原始值精确匹配，不归一化 |
|
|
|
+
|
|
|
+写入时使用表中的数值。语义说明参考 wiki《ScriptingForSchedulingConfiguration》的常用优先级组合，界面文案在 ui-design 中确定。E/G、F/H 在模版中各是一个模式，不拆分：E 变成 G、F 变成 H 取决于模版之外用户的 PCS 设置（电网充电使能、电池馈网使能），模版无法也不需要区分，界面统一显示为 E/G、F/H；扩展模式（强制充电/仅备电、强制放电、Zero Import）已确认加入，参数见下方扩展模式参数表。
|
|
|
+
|
|
|
+> **补充信息（仅用于理解 Zero Import，不作为需求）**：Zero Import 来自澳洲 GloBird 的 ZEROHERO 套餐（参考模版 4477）。套餐条款：晚高峰（当地时间 18:00–21:00，每天）每小时从电网取电少于 0.03 kWh 即视为“Zero”；另有 ZEROCHARGE 功能，按 28 天账单周期每天限 50 kWh（属于套餐规则，由普通时段参数实现，不是调度模式）。
|
|
|
+
|
|
|
+**扩展模式的参数（2026-10-21 确认）**
|
|
|
+
|
|
|
+选择模式时填入下表的值：“固定”参数只读；“必填”参数可以修改但不能清空；“初始值”参数可以在高级修改中调整或清空。
|
|
|
+
|
|
|
+| 模式 | 参数（单位 kW，按单台 aPower） | 来源 |
|
|
|
+| --- | --- | --- |
|
|
|
+| 强制充电 | 固定：优先级 `""`/`""`；必填：`chargePower=8`（单台最大充电功率）、`gridChargeMax=-1`（默认不限） | wiki《常规调度配置·仅备电》（原文 8000 W）、`tou-template.md` |
|
|
|
+| 强制放电 | 固定：优先级 `""`/`""`；必填：`dischargePower=10`（单台最大放电功率）、`gridDischargeMax=-1`（默认不限） | wiki《常规调度配置·强制aPower放电》（原文 10000 W） |
|
|
|
+| Zero Import | 固定：优先级 `9,9,9`/`9,9,9`、`gridDischargeMax=0.1`、`gridFeedMax=0.1`；必填：`dischargePower=10`；初始值：`gridMax=0`、`gcaoMax=0`、`heatEnable=1` | `service/test/tou/main.go` 测试数据（云端 `dispatchId=9`） |
|
|
|
+
|
|
|
+识别顺序（解析时）：
|
|
|
+
|
|
|
+1. 按原始值精确匹配特殊模式（Zero Import：`9,9,9`/`9,9,9`）；
|
|
|
+2. 两个优先级都为空时：只设置了 `chargePower` → 强制充电；只设置了 `dischargePower` → 强制放电；两者都没设置 → 未设置优先级；两者都设置了 → 自定义并标出异常；
|
|
|
+3. 归一化后匹配 A～H；
|
|
|
+4. 都不匹配 → 自定义（只有一个优先级为空也归为自定义并标出异常）。
|
|
|
+
|
|
|
+“设置了”指字段有值且不为 `-1`（未设置的哨兵值）。Zero Import 只按优先级识别；如果已有数据的固定参数与定义不一致（如 `gridFeedMax` 不是 0.1），仍识别为 Zero Import，但标出不一致，且在用户未改动该时段时原样保留。识别结果只看优先级和上述字段，A～H 时段上额外设置的功率参数作为高级参数显示，不改变模式。
|
|
|
+
|
|
|
+- **写入规则**：用户新设置的优先级只能取自调度模式定义表，或者为空；不允许手工输入其他数值，避免下层应用无法识别。已有的非标准数值在用户没有改动时原样保留（见 FR-04“保持原值”）。
|
|
|
+- 前后端使用统一的模版类型定义，生产服与测试服共用同一套结构和代码，通过环境参数区分。
|
|
|
+- 云端字段拼写问题（`derSchdule`、`eletic*`、`ccociate*`、`mookRunCount`）在界面上显示规范名称；是否在 DTO 层映射由技术设计决定。
|
|
|
+- 模版主体中的 `priority`、`env`、`mookRunCount` 目前很少使用，不做语义解释：编辑时原样保留，允许按原始值填写，不做枚举或位域拆解。
|
|
|
+- 写操作记录操作人、环境、模版 ID 和提交内容，便于追溯（存储方式见 Q-07）。
|
|
|
+
|
|
|
+## 4. 待确认事项
|
|
|
+
|
|
|
+已关闭：Q-03（发布/删除接口已确认，功能放到后续迭代，见 FR-05）、Q-09（`priority`/`env`/`mookRunCount` 原样保留，见第 3 节）、Q-11（优先级为空时两者都写空字符串，见 FR-04）、Q-12（E/G、F/H 不拆分，由用户 PCS 设置决定，见调度模式定义表）、Q-01（高级修改：除优先级外全部参数可改，见 FR-04）、Q-13（扩展模式的优先级和参数，见模式参数表）、Q-14（强制充放电的 `gridChargeMax`/`gridDischargeMax` 为必填，预设 -1，可修改）。
|
|
|
+
|
|
|
+| 编号 | 问题 | 影响 |
|
|
|
+| --- | --- | --- |
|
|
|
+| Q-02 | 是否支持“复制已有模版新建”，是否允许以生产服模版为蓝本在测试服新建 | FR-04、FR-07 |
|
|
|
+| Q-04 | 月份是否必须覆盖全年；一个模版最多几组策略 | FR-04 校验 |
|
|
|
+| Q-05 | 导出格式：云端原始 JSON、规范化 JSON、xlsx，还是多选 | FR-06 |
|
|
|
+| Q-06 | 测试服页面是否也提供对比入口（反向对比） | FR-01、FR-07 |
|
|
|
+| Q-07 | 写操作记录是否入库，是否需要在工具内保留历史版本 | 共同需求 |
|
|
|
+| Q-08 | API 模版（1）和用户推荐（2）是否保留在列表中供查看和过滤（写入已限定为系统模版 0） | FR-02、FR-04 |
|
|
|
+| Q-10 | 权限：编辑和发布是否全部开放，是否需要区分角色 | FR-04、FR-05 |
|
|
|
+
|
|
|
+## 5. 第二阶段（暂不实现）
|
|
|
+
|
|
|
+- 模块接入 MCP，让 AI 完成模版编辑，复用本阶段的统一类型、校验规则和调度模式识别。
|
|
|
+- 现有 MCP 工具 `service_tou_template_*` 在第二阶段改为调用重构后的服务层。
|
Jerry Liang