changelog-filename-gate / validate (push) Successful in 1s

详情

修改原因：管理后台已经完成最终确认逐车短信选择、真实状态查询和失败受控重试，需要同步前端消费进度与可追溯提交。

修改内容：将 #5263 从 pending 经 claimed 合法迁移为 implemented，登记 hl-ui-pi 与前端提交 138136e5，清理误填的 verified_at，并注明尚未发布和真实页面联调。

实际验证：前端定向 7 个 Vitest 文件 62 项通过，verify:changed 全量通过；changelog 46 项测试、path alias 校验和 git diff --check 通过。

Changelog: changelogs-v2/2026-07/26_5263_最终确认按车选择发送行程短信-修改接口-管理后台.md

2026-07-27 00:27:09 +08:00

7.6 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base, generated

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base	generated
hl-changelog/v2	5263	最终确认按车选择发送行程短信	admin	修改接口	deployed	verified	implemented	hl-ui-pi	mmg/hl-ui@138136e50c			前端已在 138136e5 接入 HOLD 最终确认逐车短信必选、权威状态查询和 FAILED 受控重试；定向 7 个文件 62 项及 verify:changed 全量验证通过。尚未发布或完成真实页面联调。	2026-07-27	dev-v3	2026-07-26T17:33:00+08:00

最终确认按车选择发送行程短信

关联

Issue: wx/HL#5263
Changelog PR: wx/hl-api-changelog#41
服务：hl-fleet-service、hl-user-service
前端仓库：mmg/hl-ui（本文仅交接，不代表已修改前端）
前置车费契约：#5262 派车逐日车费、只读总价与核单实时接口

关键变化

仅在 HOLD 排车的最终确认阶段，每个车辆组必须显式选择“发送短信”或“不发送短信”，没有默认值。
选择发送时，确认事务只落可靠发送意图；短信异步发送失败不会回滚已完成的派车确认。
短信只发给该车辆组当前师傅，包含订单摘要、接送摘要和签名行程短链，不包含客户手机号。
选择不发送时只完成派车确认，不创建行程短信事件。
多车订单逐车独立选择、独立投递、独立查询状态和受控重试。
已派定后的订单人数基线复核只能沿用原选择，不允许借复核修改选择或重复发送。
直接派车流程不受影响；#5262 已废弃的手工车辆总价入参仍然禁止提交。

变更接口

方法	路径	变化
`POST`	`/admin/fleet/assignments/:assignmentId/confirm`	请求新增必填 `sendItinerarySms`；响应新增短信选择、事件与状态
`GET`	`/admin/fleet/assignments/:assignmentId/itinerary-sms`	新增单车/车辆组短信审计状态查询
`POST`	`/admin/fleet/assignments/:assignmentId/itinerary-sms/retry`	新增明确失败后的车务受控重试

最终确认

`POST /admin/fleet/assignments/:assignmentId/confirm`

请求字段

字段	类型	必填	说明
`sendItinerarySms`	`Boolean`	是	`true` 发送；`false` 不发送；省略或 `null` 返回参数错误
`requestId`	`String`	是	最长 64 字符的幂等请求标识
`vehicleFeeTotal`	`Decimal`	否	历史兼容字段；非空即拒绝，最终总车费继续由 #5262 逐日车费只读合计
`vehicleFeeAdjustmentReason`	`String`	否	历史兼容字段；非空即拒绝

请求示例：

{
  "sendItinerarySms": true,
  "requestId": "fleet-final-confirm-26-8411-car-1"
}

新增响应字段

字段	类型	说明
`sendItinerarySms`	`Boolean`	本车辆组最终确认时保存的选择
`itinerarySmsEventId`	`String/null`	可靠短信事件 ID；不发送时为空
`itinerarySmsStatus`	`String`	首次确认返回 `PENDING` 或 `NOT_SENT`；已派定复核回显真实状态

短信状态

`GET /admin/fleet/assignments/:assignmentId/itinerary-sms`

响应 data：

字段	类型	说明
`assignmentId`	`String`	派单 ID
`assignmentGroupId`	`String`	跨服务日车辆组 ID
`assignmentSlotId`	`String`	稳定车辆槽位 ID
`sendItinerarySms`	`Boolean/null`	未最终确认或历史数据时为 `null`
`status`	`String`	`NOT_APPLICABLE` / `NOT_SENT` / `PENDING` / `SENT` / `FAILED` / `CANCELED`
`eventId`	`String/null`	可靠短信事件 ID
`retryCount`	`Integer`	已发生的失败重试次数
`canRetry`	`Boolean`	当前是否允许受控重试
`sentAt`	`LocalDateTime/null`	供应商确认的真实发送时间
`lastError`	`String/null`	已脱敏的最近失败或待对账原因

前端以 status 为权威，不得仅凭最终确认接口成功就显示“短信已发送”。

受控重试

`POST /admin/fleet/assignments/:assignmentId/itinerary-sms/retry`

请求：

{
  "reason": "短信通道配置已恢复，车务确认重发",
  "requestId": "retry-sms-26-8411-car-1"
}

规则：

仅 FAILED 且 canRetry=true 时展示并调用重试。
SENT、PENDING、待供应商对账、CANCELED、未选择发送时禁止重试。
重试复用原事件与供应商幂等键，不新建并行短信事件。
司机或车辆组身份已变化时，旧事件收敛为 CANCELED，不得发给旧师傅。

短信与隐私约束

短信模板参数固定为：

参数	内容
`summary`	脱敏订单摘要
`transfer`	接送摘要
`code`	签名行程短链

短信正文及模板参数不得包含客户手机号。真实联系人信息仅在既有签名行程 H5 中按授权展示。

页面展示矩阵

区域/状态	数据源	展示	空态/禁用	颜色	守恒规则
最终确认车辆卡片	本地待提交选择	“发送短信”/“不发送短信”二选一	未选择时禁止确认并提示必选	发送蓝色，不发送中性灰	每个车辆组恰好一个选择
确认后状态	`GET .../itinerary-sms.status`	待发送/已发送/发送失败/已取消/未发送	历史数据为“不适用”	待发送蓝、已发送绿、失败红、取消灰、未发送中性灰	不以确认成功冒充发送成功
失败操作	`canRetry`	“重试短信”	`canRetry=false` 时隐藏或禁用	可重试橙色	同一事件串行重试
多车订单	每个 `assignmentGroupId`	每车独立选择与状态	不做订单级统一默认	各卡片独立	一车选择不得覆盖另一车

前端处理清单

最终确认页按车辆组渲染无默认值的短信二选一。
未完成选择时不提交确认请求，并展示明确校验提示。
确认请求始终显式提交 sendItinerarySms，不再依赖后端默认值。
确认后通过状态接口展示真实投递状态。
仅在 FAILED && canRetry=true 时允许填写原因并调用重试。
已派定复核回显原选择并保持只读，不提供改选入口。
短信状态按展示矩阵处理空态、颜色及多车独立性。
确认和复核请求继续不提交 #5262 已废弃的手工总车费字段。

验证证据

OpenAPI/oasdiff：not_configured；已完成 Controller/VO 源码比对和接口测试回退证据。
消费者契约：not_required；未修改 internal Feign 或共享 Java DTO。
代码与测试：PR wx/HL#5270 已合入 dev-v3，merge commit 为 f0a96c10124c3188e60e1291e7f28d768af50e3a；mvn -pl hl-user-service,hl-fleet-service -am test、mvn -pl hl-fleet-service spotless:check、mvn -pl hl-fleet-service -am verify 均通过。
测试部署：hl-user-service 与 hl-fleet-service 已从合并后的 dev-v3 完成双实例滚动部署并通过健康检查。
网关：显式“不发送”业务验收 11/11 通过；合并后只读复验 3/3 通过，最终状态为 assigned + NOT_SENT，无短信事件且不可重试。
frontend_status：pending；真实领取后再迁移为 claimed 并填写 frontend_owner。

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