docs(changelog): 车管微信通知模板 5 接口上线(模板 CRUD + 渲染预览, #4156/#4157/#4158)

changelogs-v2/2026-06/21_车管微信通知模板-5接口上线-模板CRUD加渲染预览-管理后台.md

@@ -0,0 +1,101 @@
+# 【接口新增·管理后台】车管「微信通知模板」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 拦,前端提示「请先把其它同类型模板设为默认再删」。