protocol-observations.md 4.7 KB
云端 TOU 模版接口实测记录
状态：2026-10-21，基于测试服后台网页操作抓包（
TOU模版.test.franklinwh.com.har，含登录 token，不入库）。本文只记录观察到的事实；结论被设计采纳后写入 technical-design。
1. 抓包范围
操作顺序：查询省/州 → 新建模版 → 列表 → 查看详情 → 打开编辑（未保存）→ 发布 → 删除。
| # | 接口 | 方法 / 格式 | 用途 |
|---|---|---|---|
| 0 | /hes-gateway/manage/selectCitesList?countryId=2&type=1&lang=ZH_CN |
GET | 查询美国的省/州 |
| 28 | /hes-gateway/manage/updateOrSaveIotTouTemplate |
POST JSON | 新建，返回 result: 4576（模版 ID） |
| 29/34/37 | /hes-gateway/manage/selectIotTouTemplateList |
POST form | 列表 |
| 30/32 | /hes-gateway/manage/getIotTouTemplateDetailById |
POST form id=4576&lang=ZH_CN |
详情（两次返回完全相同） |
| 33 | /hes-gateway/manage/setStatusIotTouTemplate |
POST form templateId=4576&status=2&lang=ZH_CN |
发布 |
| 36 | /hes-gateway/manage/setStatusIotTouTemplate |
POST form templateId=4576&status=1&lang=ZH_CN |
删除 |
未覆盖：编辑后保存（更新）。
2. 状态接口 setStatusIotTouTemplate
- 发布和删除共用一个接口，只是
status不同：2发布，1删除。响应{"code":200,"result":null}。 - 删除是软删除：之后列表总数从 1126 降到 1125，模版不再出现在列表中。
status取值：0未发布、1已删除、2已发布。没有取消发布的操作（目前只能改数据库）。- 发布后
updateTime不变（列表中仍为03:02:33）。
3. 新建：网页提交的内容与云端存储的差异
网页提交的请求体与 fwhTestTouTemplateDTO.go / tou-template.md 的约定有出入，云端会做规范化：
| 字段 | 网页提交 | 详情读回 | 说明 |
|---|---|---|---|
| 未设置的可选数值（功率、SOC 等） | "" |
null |
空串可接受；我们的 DTO 用省略，两种都应可行（省略方式待验证） |
solarCutoff |
"" |
0 |
空串被存为 0 |
name（时段名） |
"" |
"mid-peak" |
云端按 waveType 自动生成 |
powerOffApower |
"" |
"" |
原样 |
template.mookRunCount |
"0"（字符串） |
0 |
|
template.priority / env |
"" |
null |
|
template.sourceType |
未提交 | 0 |
默认系统模版 |
dayName |
All day / Workday / Holidays |
Every day / Weekdays / Weekends,Holidays |
云端按 dayType 改写，提交什么不重要 |
ccociateSn |
数字 2、4 |
字符串 "2"、"4" |
不要求从 "0" 连续递增，只要求同组相同 |
| 策略顺序 | JanToJun, JulToSep×2, OctToDec×2 | JanToJun, OctToDec×2, JulToSep×2 | 读回顺序与提交不同，按 id 也不是提交顺序 |
4. 详情中云端生成或只读的字段
写入 DTO 没有、由云端生成的字段：
- 模版：
id、templateId（等于id）、gatewayId、templateFromType、eletricCompanyId（本例 10100，按电力公司生成或匹配）、sdcpCompanyFlag、status、countryZh/En、provinceZh/En、workMode（本例 1）、updateTime、displayFlag、templateType、ptoDate、nbtType、classification、remark、tariffName、templateName、installerTpl、solarChargeMin。 - 策略：
id、templateId、fromType。 - 时段：
id、strategyId、useModeFlag（本例 0）、dispatchId（本例 6，优先级为1,3,2/1,3,2，云端似乎按优先级匹配了自己的调度模式表）、dispatch、buyRate、sellRate。 - 顶层另有
bbDefaultVo（本例null）。
5. 待补充验证
| 编号 | 验证内容 | 影响 |
|---|---|---|
| V-01 | 编辑后保存的请求体：网页是否回传策略/时段 id，是否回传第 4 节中的只读字段 |
更新语义、保持原值 |
| V-02 | 更新后策略/时段 id 是否变化（整体删除重建还是按 id 更新） |
对比对齐、操作记录 |
| V-03 | 对已有 remark、displayFlag、tariffName 等非空的模版，更新时不传这些字段，是否会被清空 |
保持原值 |
| V-04 | dispatchId 的完整取值表。已知：6=D（1,3,2/1,3,2），3=E/G（1,2,3/1,2,0），9=Zero Import（9,9,9），见 service/test/tou/main.go；抓包中网页新建时未提交 dispatchId，读回为 6，说明云端按优先级自动匹配；完整取值表和未匹配时的取值待确认 |
调度模式定义表 |
| V-05 | 对已发布模版执行更新后，status 是否保持 2 |
编辑流程 |
| V-06 | 可选数值字段“省略”与“传空串”在云端是否等价 | 写入格式 |