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

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

⚠️ 关键说明

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

1. 模板列表

GET /admin/fleet/message-templates

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

出参(按 sortOrder 升序):

{"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

入参:

{"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 均雪花、均可缺失):

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}'

出参(真实订单实测):

{"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 暂返空串(待行程包/接送站数据补齐)。

前端动作(车管控制台)

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

4.8 KiB 原始文件 Blame 文件历史 Unescape Escape