name: tou-template-scheduling

description: 编写、校验并保存 FranklinWH 的 TOU（分时电价）调度模板，用于 EMS 调度配置。当用户需要构建、编辑、理解或上传 TOU 电价模板时使用——包括时段策略、光伏/负载优先级、充放电功率限制、省/市选择等。涵盖 updateOrSaveIotTouTemplate 请求体以及 MCP 工具 service_toutemplate*。

FranklinWH TOU 调度模板

用于构建并保存 EMS 调度（TOU）模板。一个模板 = 基础信息 + 一个或多个「季节/日类型」策略；每个策略 = 覆盖一整天的时段列表。它对应云端 updateOrSaveIotTouTemplate 接口和设备侧 355/357 调度协议。

参考资料（完整协议与字段语义）： /home/jerry-remote/web/FranklinWH-Wiki/client/docs/Software/ScriptingForSchedulingConfiguration.md

字段权威定义（Go DTO）：service/dto/fwhTestTouTemplateDTO.go

MCP 工具

所有工具都接受可选参数 env：pro（生产）或 test（测试）。

工具	用途	env 默认值
`service_tou_template_list`	查询模板列表（按类型/状态/关键字筛选）	`pro`
`service_tou_template_detail`	按`id` 查询单个模板详情	`pro`
`service_tou_template_save`	新增/更新模板，返回 templateId【写操作】	`test`（当前仅支持）
`service_tou_template_cites`	查询某国家下的省/市列表	`test`（当前仅支持）

save 与 cites 目前仅支持 test。读操作默认走 pro，需要读测试环境时传 env:"test"。

典型流程：cites（拿 countryId/provinceId）→ 构建 payload → save → detail 校验。

请求体结构（`service_tou_template_save` 的 `payload`）

顶层结构（FwhTestUpdateOrSaveTouTemplatePayload）：

{
  "template": {
    /* 模板主体，见下表 */
  },
  "strategyList": [
    {
      /* 策略，见下表 */
    }
  ],
  "lang": "ZH_CN"
}

所有字段都是 JSON 字符串。数值型字段以「字符串形式的数字」传递；未设置的字段传空串 ""（不要传 null）。
template.templateId：创建模板时不需要此字段（省略）；更新模板时必须带此字段并填入模板 ID。读取（detail/list 返回）时该字段必定存在。
template.sourceType：必填。当前仅允许写入系统模板 "0"（1API模板 / 2用户推荐暂不支持写入，save 会拒绝）。

1. `template`（模板主体 · `FwhTestTouTemplateInfo`）

字段	类型	含义 / 取值
`countryId`	string(数值)	国家 ID
`provinceId`	string(数值)	州/省 ID
`derSchdule`	string	DER 调度配置
`eleCompanyFullName`	string	电力公司全称
`electricCompany`	string	电力公司（简称）
`gridType`	string	电网类型 / 套餐类型
`electricityType`	string(数值)	电价类型：`1`分时电价 `2`阶梯电价 `3`固定电价 `4`分时&阶梯电价 `5`BB套餐 `6`Peak Demand
`name`	string	模板/策略表名称
`mookRunCount`	string(数值)	模式执行次数(loop)：`0`不限次数 `1`执行一次
`priority`	string(数值)	模式优先级，默认`0`；`0` 最低，数字越大优先级越高
`env`	string(数值·位域)	模式使用条件，默认`0`；bit0~1 光伏；bit2~3 馈网；bit4~5 电网充电
`templateId`	string(数值)	模板 ID。创建时不需要（省略此字段）；更新时必须带上并填 ID。读取（detail/list）返回时该字段必定存在
`sourceType`	string(数值·必填)	模板类型。必填，当前仅允许 `0`系统模板（`1`API模板 `2`用户推荐暂不支持写入）

2. `strategyList[]`（策略 · `FwhTestTouTemplateStrategy`）

一个策略 = 一组「季节/日类型」+ 覆盖一整天的时段列表。

字段	类型	含义 / 取值
`ccociateType`	string(数值)	关联类型编码，如`1`
`ccociateSn`	string	关联设备 SN（无则空串）
`detailVoList`	array	时段明细表，所有时段必须覆盖一整天（见下表）
`seasonName`	string	季节名，用于标识策略范围，可自定义，如`summer`、`All months`
`month`	string	逗号分隔的月份，如`1,2,3,4,5,6,7,8,9,10,11,12`
`dayName`	string	日期类型可读名称，如`Every day`、`Weekdays`（与 `dayType` 对应）
`dayType`	string(数值)	日期类型编码：`1`工作日 `2`节假日 `3`每天（可读名见 `dayName`）

3. `detailVoList[]`（时段明细 · `FwhTestTouTemplateDetailVo`）

同一策略内的所有时段必须铺满一整天：每个 endHourTime 等于下一段的 startHourTime，第一段是 00:00，最后一段是 24:00。值均为字符串，"" 表示未设置（勿传 null）。

字段	类型	含义 / 取值
`startHourTime`	string	开始时间，格式`HH:mm`，如 `06:30`
`endHourTime`	string	结束时间，格式`HH:mm`；需与下一段 `startHourTime` 衔接，所有时段覆盖一整天
`waveType`	string(数值·flag)	峰平谷定义：`0`谷/off-peak `1`平/mid-peak `2`峰/on-peak `3`尖峰/super-on-peak `4`低谷/super-off-peak
`name`	string	时段名，一般为`supper-off-peak`、`off-peak`、`mid-peak`、`on-peak`、`supper-on-peak` 等
`briefDescribe`	string	时段描述，如`Self-consumption`
`solarPriority`	string	光伏供电优先级，格式 `"市电,负载,FHP"`，如 `"1,3,2"`；优先级 `0/1/2/3`，可相同(表示按比例/功率分配)，`0`=不涉及，数字越大优先级越高
`loadPriority`	string	负载取电优先级，格式 `"市电,光伏,FHP"`，如 `"1,3,2"`；优先级 `0/1/2/3`，可相同(按比例/功率分配)，`0`=不使用此源，数字越大优先级越高
`gridDischargeMax`	string(kW,0.1)	电池最大允许馈网功率；可选，默认`0` 不能馈网；`0`不可馈网，`-1`不限制
`gridChargeMax`	string(kW,0.1)	电网允许最大充电功率；可选，默认`0` 不允许；`0`不允许，`-1`不限制
`chargePower`	string(kW,0.1)	固定电池充电功率，按单台功率计算；可选，默认`-1` 未设置
`dischargePower`	string(kW,0.1)	固定电池放电功率，按单台功率计算；可选，默认`-1` 未设置
`chargeMax`	string(kW,0.1)	电池最大允许充电功率，按单台功率计算；`-1`无限制，默认 `-1`
`dischargeMax`	string(kW,0.1)	电池最大允许放电功率，按单台功率计算；`-1`无限制，默认 `-1`
`gcaoMax`	string(kW,0.1)	GCAO(grid charge after an outage)：停电后补电至预留 SOC 的单台市电取电功率；可选；`0`不允许，`-1`不限制；默认未设置(`-3`)；使能后未设值则为 `5kw*N`(用 `-2` 标识)
`gridFeedMax`	string(kW,0.1)	电网允许最大馈网功率；可选，默认`-2`；`0`不允许，`-1`不限制，`-2`未设置
`gridMax`	string(kW,0.1)	电网允许最大取电功率；可选，默认`-1` 不限制；`0`不允许，`-1`不限制
`minDischargeSoc`	string(%,整数)	放电截止 SOC；达到此 SOC 后电池不放电，可选，默认`0%`；若 `reserved_soc` 大于此值则以 `reserved_soc` 为准
`maxChargeSoc`	string(%,整数)	充电截止 SOC；可选，默认`100%`
`heatEnable`	string(数值)	充电加热使能：`0`未设置(默认) `1`不使能 `2`使能
`powerOffApower`	string(数值)	主动关闭 APower；可选，`0`不控制(默认) `1`关机 `2`开机(预留)
`rampTime`	string(秒)	爬坡时间，`0~300`；默认 `0`，BB套餐默认 `300`
`offGrid`	string(数值)	主动断开市电继电器：`0`不控制(默认) `1`断开 `2`闭合(预留)
`solarCutoff`	string(数值)	主动断开光伏继电器：`0`不控制(默认) `1`断开 `2`闭合(预留)

要点：

solarPriority / loadPriority 是 3 值字符串，顺序 [市电, 负载或光伏, FHP/aPower]；0=不参与，数字越大优先级越高，相同非 0 值=按比例分配。
功率字段单位 kW、精度 0.1，按单台 aPower 计（总功率 = 值 × 台数 N）：gridChargeMax、gridDischargeMax、gridFeedMax、gridMax、chargePower、dischargePower、chargeMax、dischargeMax、gcaoMax。常见哨兵值：-1不限制、0不允许/不可、-2未设置(仅 gridFeedMax/gcaoMax)、-3未设置(仅 gcaoMax)。

完整 detailVoList 单段示例

{
  "startHourTime": "00:00",
  "endHourTime": "11:00",
  "waveType": "1",
  "name": "mid-peak",
  "briefDescribe": "Self-consumption",
  "solarPriority": "1,3,2",
  "loadPriority": "1,3,2",
  "gridChargeMax": "",
  "gridDischargeMax": "",
  "gridFeedMax": "",
  "gridMax": "",
  "chargePower": "",
  "dischargePower": "",
  "chargeMax": "",
  "dischargeMax": "",
  "gcaoMax": "",
  "minDischargeSoc": "",
  "maxChargeSoc": "",
  "heatEnable": "",
  "rampTime": "",
  "offGrid": "",
  "solarCutoff": "0",
  "powerOffApower": ""
}

selectCitesList 返回结构（`service_tou_template_cites`）

FwhTestCitesListData：countryList / provinceList / cityList 三个数组。各项字段（注意此接口返回中 id 为数值，非字符串）：

结构	字段
`FwhTestCountryInfo`	`id`(int), `nameEn`, `nameZh`, `latitude`, `longitude`
`FwhTestProvinceInfo`	`id`(int), `nameEn`, `nameZh`, `latitude`, `longitude`, `cityList[]`
`FwhTestCityInfo`	`id`(int), `nameEn`, `nameZh`, `latitude`, `longitude`

优先级 → 调度策略速查

常见 solarPriority/loadPriority 组合及其含义（来自 templateTable.vue）：

光伏优先级	负载优先级	策略
`1,2,0`	`1,3,2`	A
`1,2,0`	`1,2,0`	B —— 电池不参与调度（光伏优先供载，剩余馈网，市电补充）
`1,3,2`	`1,2,0`	C —— 光伏剩余充电（光伏优先供载，剩余给电池充电，电池不放电）
`1,3,2`	`1,3,2`	D —— 自发自用（标准，最常用）
`1,2,3`	`1,2,0`	E/G —— 光伏优先充电
`1,2,0`	`1,2,3`	F/H —— 电池优先供载

标准模板（来自 wiki《常规调度配置》）：

自发自用：solarPriority:"1,3,2"，loadPriority:"1,3,2"，describe "Self-consumption"。
仅备电：gridChargeMax:"-1"（不限充），chargePower:"8"（约 8kW 满充），describe "Emergency backup"。
强制放电/馈网收益：gridDischargeMax:"-1"（不限馈网），dischargePower:"10"（约 10kW 满放）。

规则

时间覆盖：每个策略的 detailVoList 必须覆盖 00:00→24:00，无空档、无重叠；endHourTime == 下一段 startHourTime；时间格式 HH:mm。
未设置传 ""：明细字段绝不传 null，用空串；数字也以字符串形式传。
功率单位是 kW（步进 0.1），按单台 aPower 计。不要对这些模板字段套用设备侧的 W 或 5kw*N/-2 约定。
优先级是 3 值字符串 "a,b,c"，顺序为 [市电, 负载/光伏, aPower]。
新增 vs 更新：template.templateId 留空为新增；填入 ID 为更新。
写操作走 test：service_tou_template_save 仅支持 env:"test"。保存前先与用户确认（会修改服务器数据）。保存后用 service_tou_template_detail（带 env:"test"）校验。
执行写操作前，需要和用户确认最终写入或更新的信息，确认后才能调用 service_tou_template_save 创建或更新
不确定某国家的 provinceId 时，先调用 service_tou_template_cites 传 country_id。

示例流程：构建一个标准自发自用模板

service_tou_template_cites { "country_id": 3 } → 选出 provinceId。
构建一个策略（dayType 3 = 每天），用策略 D（solarPriority:"1,3,2"，loadPriority:"1,3,2"）铺一整天单一时段，或拆成 off/mid/on-peak 多个时段。
service_tou_template_save { "env":"test", "payload": "<json>" } → 记下返回的 templateId。
service_tou_template_detail { "env":"test", "id": <templateId> } 确认结果。

SKILL.md 17 KB История Директен файл

FranklinWH TOU 调度模板

MCP 工具

请求体结构（service_tou_template_save 的 payload）

1. template（模板主体 · FwhTestTouTemplateInfo）

2. strategyList[]（策略 · FwhTestTouTemplateStrategy）

3. detailVoList[]（时段明细 · FwhTestTouTemplateDetailVo）