FranklinWH-Toolbox/service/cmd/mcp/.kiro/skills/tou-template-scheduling/SKILL.md

---

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"
}

• 字段按真实类型传值：数值字段传数字（不是字符串），字符串字段传字符串。可选的数值字段未设置时直接省略该 key（不要传空串 ""，也不要传 null）。
• template.templateId：创建模板时不需要此字段（省略）；更新模板时必须带此字段并填入模板 ID（数值）。读取（detail/list 返回）时该字段必定存在。
• template.sourceType：必填（数值）。当前仅允许写入系统模板 0（1API模板 / 2用户推荐 暂不支持写入，save 会拒绝）。

1. template（模板主体 · FwhTestTouTemplateInfo）

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

2. strategyList[]（策略 · FwhTestTouTemplateStrategy）

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

字段	类型	含义 / 取值
ccociateType	number	关联类型：1每天 2工作日 3周末/节假日（与 dayType/dayName 配套，见下方「日类型配套逻辑」）
ccociateSn	string	关联序号：每天为""；工作日与其配对的周末/节假日共用同一序号(从 "0" 递增)
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 周末/节假日=Weekends,Holidays（与 dayType 对应）
dayType	number	日类型编码：1工作日 2周末/节假日 3每天（可读名见 dayName）

日类型配套逻辑（ccociateType / ccociateSn / dayType / dayName）

这四个字段必须成套填写，用于表示策略的「日类型」及工作日与周末/节假日的配对关系：

日类型	ccociateType	ccociateSn	dayType	dayName
每天	1	""	3	Every day
工作日	2	序号(从 "0" 递增)	1	Weekdays
周末或节假日	3	同组工作日的序号	2	Weekends,Holidays

• 每天是独立策略，无需配对，ccociateSn 恒为空串 ""。
• 工作日(2) 与 周末/节假日(3) 成对出现，通过相同的 ccociateSn 关联为同一组。
• ccociateSn 是从 "0" 开始的序号字符串：第一对「工作日+周末/节假日」用 "0"，第二对用 "1"，以此类推（每新增一对 +1）。
• 因此，用「每天」时只有 1 条策略；用「工作日/周末」时至少成对出现 2 条策略（一条 type=2、一条 type=3，共用同一 ccociateSn）。

策略级电价字段（可选）：以下字段描述该策略各时段的电价，类型为数值（number）；未设置时直接省略该 key（不要传 "" 或 null）。

字段	类型	含义
eleticRatePeak	number	峰时购电电价
eleticRateShoulder	number	平时购电电价
eleticRateValley	number	谷时购电电价
eleticRateSharp	number	尖峰购电电价
eleticRateSuperOffPeak	number	超低谷购电电价
eleticRateGridFee	number	电网附加费
eleticSellPeak	number	峰时卖电（上网）电价
eleticSellShoulder	number	平时卖电（上网）电价
eleticSellValley	number	谷时卖电（上网）电价
eleticSellSharp	number	尖峰卖电（上网）电价
eleticSellSuperOffPeak	number	超低谷卖电（上网）电价

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

同一策略内的所有时段必须铺满一整天：每个 endHourTime 等于下一段的 startHourTime，第一段是 00:00，最后一段是 24:00。数值字段传数字（waveType、solarCutoff 每段必填；功率/SOC/使能等为可选）；可选数值字段未设置时直接省略该 key（不要传 "" 或 null）。字符串字段（时间、名称、优先级、powerOffApower）传字符串。

字段	类型	含义 / 取值
startHourTime	string	开始时间，格式HH:mm，如 06:30
endHourTime	string	结束时间，格式HH:mm；需与下一段 startHourTime 衔接，所有时段覆盖一整天
waveType	number(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	number(kW,0.1,可选)	电池最大允许馈网功率；可选，默认0 不能馈网；0不可馈网，-1不限制
gridChargeMax	number(kW,0.1,可选)	电网允许最大充电功率；可选，默认0 不允许；0不允许，-1不限制
chargePower	number(kW,0.1,可选)	固定电池充电功率，按单台功率计算；可选，默认-1 未设置
dischargePower	number(kW,0.1,可选)	固定电池放电功率，按单台功率计算；可选，默认-1 未设置
chargeMax	number(kW,0.1,可选)	电池最大允许充电功率，按单台功率计算；-1无限制，默认 -1
dischargeMax	number(kW,0.1,可选)	电池最大允许放电功率，按单台功率计算；-1无限制，默认 -1
gcaoMax	number(kW,0.1,可选)	GCAO(grid charge after an outage)：停电后补电至预留 SOC 的单台市电取电功率；可选；0不允许，-1不限制；默认未设置(-3)；使能后未设值则为 5kw*N(用 -2 标识)
gridFeedMax	number(kW,0.1,可选)	电网允许最大馈网功率；可选，默认-2；0不允许，-1不限制，-2未设置
gridMax	number(kW,0.1,可选)	电网允许最大取电功率；可选，默认-1 不限制；0不允许，-1不限制
minDischargeSoc	number(%,整数,可选)	放电截止 SOC；达到此 SOC 后电池不放电，可选，默认0%；若 reserved_soc 大于此值则以 reserved_soc 为准
maxChargeSoc	number(%,整数,可选)	充电截止 SOC；可选，默认100%
heatEnable	number(可选)	充电加热使能：0未设置(默认) 1不使能 2使能
powerOffApower	string	主动关闭 APower；可选，0不控制(默认) 1关机 2开机(预留)
rampTime	number(秒,可选)	爬坡时间，0~300；默认 0，BB套餐默认 300
offGrid	number(可选)	主动断开市电继电器：0不控制(默认) 1断开 2闭合(预留)
solarCutoff	number(必填)	主动断开光伏继电器：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 单段示例

未设置的可选功率/SOC 字段直接省略（下例只保留有值字段）：

{
  "startHourTime": "00:00",
  "endHourTime": "11:00",
  "waveType": 1,
  "name": "mid-peak",
  "briefDescribe": "Self-consumption",
  "solarPriority": "1,3,2",
  "loadPriority": "1,3,2",
  "solarCutoff": 0,
  "powerOffApower": ""
}

带部分功率设置的示例段（有值传数字，其余省略）：

{
  "startHourTime": "18:00",
  "endHourTime": "21:00",
  "waveType": 2,
  "name": "on-peak",
  "briefDescribe": "Zero Import",
  "solarPriority": "9,9,9",
  "loadPriority": "9,9,9",
  "gridDischargeMax": 0.1,
  "gridFeedMax": 0.1,
  "dischargePower": 10,
  "gridMax": 0,
  "gcaoMax": 0,
  "heatEnable": 1,
  "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 满放）。

---

规则

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

---

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

1. service_tou_template_cites { "country_id": 3 } → 选出 provinceId。
2. 构建一个策略（「每天」类型：ccociateType:1、ccociateSn:""、dayType:3、dayName:"Every day"），用策略 D（solarPriority:"1,3,2"，loadPriority:"1,3,2"）铺一整天单一时段，或拆成 off/mid/on-peak 多个时段。若需区分工作日与周末/节假日，则改用成对策略（见「日类型配套逻辑」）。
3. service_tou_template_save { "env":"test", "payload": "<json>" } → 记下返回的 templateId。
4. service_tou_template_detail { "env":"test", "id": <templateId> } 确认结果。