FranklinWH-Toolbox/deploy/agent-assistant/skills/fwh-assistant/references/tou-template.md

TOU 调度模版：结构、字段与调度模式

一个模版 = 模版主体（template）+ 一个或多个策略（strategyList）；每个策略 = 一组月份 × 日类型 + 覆盖一整天的时段列表（detailVoList）。云端字段有拼写问题（derSchdule、eletic*、ccociate*、mookRunCount），以原样字段名读写。

• 读取：mcp__gateway__fwh__tou_template_list → mcp__gateway__fwh__tou_template_get，env=prod（生产服，默认）或 env=test（测试服）。
• 写入只在测试服，且只有配置了写工具时才能做，见 write-operations.md。
• 协议原文（设备侧语义）在 Wiki 资料库 Software/ScriptingForSchedulingConfiguration.md，只作参考。

字段字典

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。新增时省略，更新时必填
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": ""
}

调度模式识别

调度模式定义表

优先级顺序：光伏 [市电, 负载, 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 放电供载，馈网限制在极小值；按原始值精确匹配，不归一化

写入时使用表中的数值。E/G、F/H 各是一个模式：E 变 G、F 变 H 取决于模版之外用户的 PCS 设置（电网充电使能、电池馈网使能），模版中统一称 E/G、F/H。

补充信息（仅用于理解 Zero Import，不作为需求）：Zero Import 来自澳洲 GloBird 的 ZEROHERO 套餐（参考模版 4477）。套餐条款：晚高峰（当地时间 18:00–21:00，每天）每小时从电网取电少于 0.03 kWh 即视为“Zero”；另有 ZEROCHARGE 功能，按 28 天账单周期每天限 50 kWh（属于套餐规则，由普通时段参数实现，不是调度模式）。

扩展模式的参数

使用扩展模式时按下表设置：“固定”参数取表中的值不可改；“必填”参数必须有值（可调整数值）；“初始值”参数可调整或省略。

模式	参数（单位 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	云端 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 时段上额外设置的功率参数作为高级参数显示，不改变模式。

写入规则（测试服）

1. 每个策略的时段覆盖 00:00→24:00，首尾衔接、无空档、无重叠，格式 HH:mm。
2. 工作日与周末/节假日成对，ccociateSn 相同；每天类型 ccociateSn 为 ""。
3. 月份在各策略间不重叠。
4. 数值字段传数字；可选数值字段未设置时省略该 key，不传 "" 或 null。功率单位 kW（精度 0.1），按单台 aPower 计；SOC 0～100；rampTime 0～300。
5. 优先级只取调度模式定义表中的值，或两个同时为空；已有的非标准值（如 9,9,9）在用户没有要求修改该时段时原样保留。
6. template.sourceType 只能为 0（系统模版）；template.templateId 新增时省略、更新时必填。
7. 写入前向用户摘要改动并取得确认；写入后用 tou_template_get（env=test）回读核对。