# 【接口新增·管理后台】车管「微信通知模板」5 接口上线(模板 CRUD + 渲染预览)

> 服务:hl-fleet-service / hl-order-service-v3 / hl-common-core ｜ 分支:dev-v3 ｜ PR:#4157 #4158 ｜ 工单:#4156
> 已部署测试服 + 9443 真 token API 实测全通过(含真实订单跨服务渲染回填,2026-06-21)

## ⚠️ 关键说明

1. **用途**:车管控制台「派单 Step3 弹窗」用的可复用微信通知文案模板 —— 模板增删改查 + 渲染预览。
2. **本期不含自动发送**:只做模板管理 + 把模板渲染成文本,**车管渲染后手动复制粘贴**到微信发给司机。真实自动发送(企微/通知中心)留后续「派单 Step3」,本期不做。
3. 路径前缀 `/admin/fleet/message-templates`,需 admin 登录(网关 `/admin/fleet/**` 已覆盖,无新增路由)。
4. 模板类型 `templateType` 4 值:`hold_notify`(排车待确认)/ `trip_pack`(行程包)/ `cancel_notify`(取消通知)/ `change_notify`(变更通知);**同一类型至多 1 条默认模板**(置默认自动清同类型旧默认)。

## 1. 模板列表

`GET /admin/fleet/message-templates`

| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
| templateType | query | 否 | 按类型筛(不传返全部) |

出参(按 sortOrder 升序):

```json
{"code":200,"message":"成功","data":[{
  "id":"2068551732970831873","templateName":"排车待确认-标准","templateType":"hold_notify",
  "bodyTemplate":"您好{{driver.name}}，订单{{order.no}}…","variablesHelp":null,
  "isDefault":true,"sortOrder":1,"createTime":"2026-06-21 12:28:59"}]}
```

## 2. 新增模板

`POST /admin/fleet/message-templates`

入参:

```json
{"templateName":"排车待确认-标准","templateType":"hold_notify",
 "bodyTemplate":"您好{{driver.name}}，订单{{order.no}}已派车{{vehicle.plate}}，今天{{system.today}}。",
 "variablesHelp":null,"isDefault":true,"sortOrder":1}
```

出参:`{"code":200,"data":{"id":"…","templateName":"…","createTime":"…"}}`(返完整对象,前端取 `data.id`)。`isDefault=true` 时自动把同类型其它模板默认标记清 0。

## 3. 编辑模板

`PUT /admin/fleet/message-templates/{templateId}`,入参同新增。出参 `{"code":200,"message":"成功"}`。模板不存在返 **600801**。

## 4. 渲染预览 ★(派单 Step3 弹窗用)

`POST /admin/fleet/message-templates/{templateId}/render`

入参(orderId/vehicleId/driverId 均雪花、均可缺失):

```bash
curl -k -X POST "https://api.test.1814.love:9443/admin/fleet/message-templates/{id}/render" \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"orderId":2068240585604407298,"vehicleId":12345,"driverId":67890}'
```

出参(真实订单实测):

```json
{"code":200,"data":{
  "renderedBody":"订单HL20260620155236293客户张伟人数1出发2026-06-24天数3",
  "variablesUsed":["order.no","order.customer","order.headcount","order.startDate","order.days"]}}
```

- `renderedBody`:模板正文里 `{{xxx}}` 占位符替换后的最终文本(车管复制此文本去微信发)。
- `variablesUsed`:本次实际引用到的白名单变量 key 列表。
- 白名单内变量值缺失(车/司机/订单查不到)→ 替换空串不报错;**白名单外占位符 → 600800**。
- `order.*` 取真实订单(经 order-v3),`driver.*`/`vehicle.*` 取 fleet 档案,`system.today` 取服务端当天。

## 5. 删除模板(软删)

`DELETE /admin/fleet/message-templates/{templateId}`。软删(不影响已发记录)。**默认模板禁删 → 600803**(须先把另一条同类型设为默认再删本条)。

## 错误码

| code | message |
|---|---|
| 600800 | 模板变量缺失(模板引用了白名单外的变量) |
| 600801 | 模板不存在 |
| 600803 | 默认模板不可删除 |

## 17 变量白名单(render 可用)

| 分组 | 变量 key |
|---|---|
| driver | `driver.name`、`driver.phone`(脱敏) |
| vehicle | `vehicle.plate`、`vehicle.model`、`vehicle.seats` |
| order | `order.no`、`order.customer`、`order.headcount`、`order.startDate`、`order.endDate`、`order.days`、`order.pickupAt`、`order.dropoffAt`、`order.tripTheme` |
| itinerary | `itinerary.url`、`itinerary.expireAt` |
| system | `system.today` |

> 注:`order.pickupAt` / `order.dropoffAt` / `order.tripTheme` / `itinerary.*` 本期数据源未就绪,render 暂返空串(待行程包/接送站数据补齐)。

## 前端动作(车管控制台)

1. 「模板管理」页对接列表/新增/编辑/删除 4 接口;模板编辑器「插入变量」菜单数据源 = 出参 `variablesHelp` 字段(JSON,缺省可回退上方白名单)。
2. 派单 Step3 弹窗:选模板 → 调 render 预览 → 展示 `renderedBody` → 车管复制粘贴到微信发司机(本期无后端自动发送)。
3. 删除默认模板会被 600803 拦,前端提示「请先把其它同类型模板设为默认再删」。