# 云端 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 | 可选数值字段“省略”与“传空串”在云端是否等价 | 写入格式 |