diff --git a/changelogs-v2/2026-06/21_车管微信通知模板-5接口上线-模板CRUD加渲染预览-管理后台.md b/changelogs-v2/2026-06/21_车管微信通知模板-5接口上线-模板CRUD加渲染预览-管理后台.md new file mode 100644 index 0000000..987dda3 --- /dev/null +++ b/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 " -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 拦,前端提示「请先把其它同类型模板设为默认再删」。