调度配置功能需求

状态：需求梳理初稿，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。

1. 目标与范围

重构“调度配置”模块，使其成为云端 TOU 调度模版的完整管理工具，并替代外部“配置编辑器”：

查看模版列表与详情（生产服、测试服）；
在测试服新增、编辑模版（发布、删除放到后续迭代）；
导出模版（生产服、测试服）；
生产服模版与指定测试服模版对比，显示差异。

范围内：仅通过 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 第 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`）

识别顺序（解析时）：

按原始值精确匹配特殊模式（Zero Import：9,9,9/9,9,9）；
两个优先级都为空时：只设置了 chargePower → 强制充电；只设置了 dischargePower → 强制放电；两者都没设置 → 未设置优先级；两者都设置了 → 自定义并标出异常；
归一化后匹配 A～H；
都不匹配 → 自定义（只有一个优先级为空也归为自定义并标出异常）。

“设置了”指字段有值且不为 -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_* 在第二阶段改为调用重构后的服务层。

requirements.md 16 KB Permanentný odkaz História Raw