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

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	修改接口	pending	pending	pending					后端已在最新 dev-v3 基线上完成源码与全量测试验证，PR、测试部署和网关实测尚待完成；前端尚未领取，owner/ref 保持为空。	2026-07-26	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 派车逐日车费、只读总价与核单实时接口

关键变化

1. 仅在 HOLD 排车的最终确认阶段，每个车辆组必须显式选择“发送短信”或“不发送短信”，没有默认值。
2. 选择发送时，确认事务只落可靠发送意图；短信异步发送失败不会回滚已完成的派车确认。
3. 短信只发给该车辆组当前师傅，包含订单摘要、接送摘要和签名行程短链，不包含客户手机号。
4. 选择不发送时只完成派车确认，不创建行程短信事件。
5. 多车订单逐车独立选择、独立投递、独立查询状态和受控重试。
6. 已派定后的订单人数基线复核只能沿用原选择，不允许借复核修改选择或重复发送。
7. 直接派车流程不受影响；#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。
• Fleet：mvn -pl hl-fleet-service -am clean verify 与 spotless:check 通过。
• User：mvn -pl hl-user-service -am verify 通过。
• frontend_status：pending；真实领取后再迁移为 claimed 并填写 frontend_owner。