hl-api-changelog/changelogs-v2/2026-09/26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md

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

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8371	取消派单：改期残留行单行取消，evidenceFileIds 改为按组累计	admin	wx(GIT)	修改接口	deployed	verified	verified	mmg	25d0469ccf12fc0fb2e359a8111e4acd133e6803	v2.1	2026-09-26	PR #8380 已合并 dev-v3（commit c2bc5c3d4），测试服 hl-fleet-service 已部署该 commit（本单不改 order-v3），已在测试服完成 6 步全链路真实网关调用验证：残留行单行取消（不再命中 605027）、非残留组取消保持原逻辑、批量重提窗内行、需求确认成功。前端接入本次不需要自行判断「该行是否残留」——后端已在服务端自动判定并豁免日期门；唯一需要适配的是 CancelRespVO.evidenceFileIds 语义变化，见下文「六.6」。 前端 2026-09-26 已交付（hl-admin 25d0469c）：isCanceledAssignmentResponse 认 canceled/exception 两态（通用入口取消在途残留行不再误报失败）；残留清理入口注释与 cancelAssignment JSDoc 按本单订正（605710 透 message、evidenceFileIds 累计语义禁拼接——三调用点实证零消费响应值）；sync-log 挂起项「DELETE 过去日期放行待确认」销项。	2026-09-26	dev-v3

取消派单：改期残留行单行取消，evidenceFileIds 改为按组累计

存放目录: 二期(v3) → changelogs-v2/2026-09/

服务: hl-fleet-service PR: #8380 Issue: #8371 日期: 2026-09-26 影响范围: 管理后台车务派单「取消派车」弹窗与取消成功后的凭证展示

---

⚠️ 关键变化

DELETE /admin/fleet/assignments/{assignmentId} 取消派车接口两处行为改动（路径、方法、入参字段不变）：

1. 改期残留行单行取消（AssignmentController.java:464-481、AssignmentService.java:5308-5419）：订单改期后，落在「该行 requirementId 所指当前用车需求日期窗口」之外的旧逐日派车行（称「改期残留行」），调用本接口取消时现改为只取消这一行，不再连带同派车组内其他行。同时豁免 605027（已出发禁止整组取消）、605047（行程已结束只读）、605028（生效日不在派单服务日期范围内）三道日期门；effectiveDate 恒为今天，入参 cutoffDate 对残留行不生效。非残留行（含全程行）行为不变，仍按派车组整组处理。
   • 残留行判定依赖实时查询 order-v3 侧的用车需求日期窗（orderQueryFacade.getFleetDetailContextStrict），查询失败时整笔取消 fail-closed，一行都不取消，返回新错误码 605710「订单服务不可用：{0}」。
2. CancelRespVO.evidenceFileIds 语义变更（CancelRespVO.java:35）：改前是本次请求入参携带的凭证 ID 原样返回；改后是该派车组自创建以来累计的全部取消凭证 ID（追加式只增不丢，旧的在前新的在后），本次未传凭证时返回空数组，不代表没有历史凭证——历史凭证不会因为本次没传就消失。

另有一个非接口改动：夜间自动完结定时任务（AssignmentCompleteJob → AssignmentService.listScheduleCompletableBefore）现在会跳过判定为改期残留行的 assigned 状态派车，不再把它们自动置 completed；残留行会一直停在原状态，直到车务手工调用本接口取消。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	取消派单	DELETE	/admin/fleet/assignments/{assignmentId}	行为变更（出参字段语义变更，字段本身不变）	改期残留行单行取消并豁免三道日期门；evidenceFileIds 改为按组累计

---

三、接口详情

1. 取消派单 DELETE /admin/fleet/assignments/{assignmentId}

VO: CancelReqVO → CancelRespVO

使用场景

管理后台车务派单管理页面，对某一行派车点击「取消」调用本接口，按条件释放该行占用的车辆/司机资源。目标行若被判定为「改期残留行」（服务日期落在当前用车需求日期窗之外），只取消这一行，不影响同派车组内窗口以内的其它日期行；否则仍按整组处理。

入参字段表

字段	位置	类型	必填	约束	说明
assignmentId	Path	Long	是	派单须存在，否则 605009	待取消的派单行 ID
cancelReason	Body	String	是	@NotBlank	取消原因
driverNotified	Body	Boolean	是	@NotNull	是否已告知司机（人工存证，true/false 均可取消）
notifyNote	Body	String	否	-	告知方式/摘要备注
cutoffDate	Body	LocalDate	否	服务端仅接受当天，空值按当天处理	取消生效日；改期残留行本参数不生效，effectiveDate 恒为今天
evidenceFileIds	Body	Array<Long>	否	@Size 最多 20 个	本次新增的取消凭证文件 ID
confirmWithoutEvidence	Body	Boolean	否	-	无凭证时的二次确认标记
requestId	Body	String	是	@NotBlank，最长 64	幂等请求 ID

出参字段表

字段	类型	说明
data.assignmentStatus	String	取消后落库状态：来源行是 unassigned 落 canceled；来源行是 assigned/holding（在途）落 exception（与通用取消 #6152 同口径，非残留身份特有）
data.assignmentGroupId	String(Long)	派车组 ID；历史行无该字段时回退 assignmentId
data.assignmentSlotId	String(Long)	稳定车辆槽位 ID（历史字段）
data.effectiveDate	LocalDate	实际取消生效日；改期残留行恒为今天
data.evidenceFileIds	String(Long)[]	本次改动：该派车组自创建以来累计的全部取消凭证 ID（追加式只增不丢，旧在前新在后）；本次未传凭证时为空数组，不代表没有历史凭证
data.confirmedWithoutEvidence	Boolean	无凭证时是否已二次确认
data.sideEffects.vehicleStatusUpdated	String	车辆状态更新结果（idle/busy/maint；不涉及车为 null）
data.sideEffects.driverStatusUpdated	String	司机状态更新结果（busy/idle；不涉及司机为 null）
data.sideEffects.reconPrepRowsCreated	Integer	对账预备单创建条数（M1 降级可能为 null 或 0）
data.sideEffects.reconPrepMarkedCanceled	Integer	对账预备单标记取消条数（M1 降级恒 0）

请求示例

测试服网关实测原文，目标行为改期残留行，服务日期已过去。

{
  "cancelReason": "8371-verify-residue-delete",
  "driverNotified": true,
  "notifyNote": "8371-verify-residue-delete",
  "confirmWithoutEvidence": true,
  "requestId": "8371-verify-delete-1"
}

响应示例

测试服网关实测原文。取消前该行处于 assigned，故落库为 exception 而非 canceled；reconPrepRowsCreated 实测返回 null，前端勿据它做判断。

{
  "code": 200,
  "message": "成功",
  "data": {
    "assignmentStatus": "exception",
    "assignmentGroupId": "362105579390504961",
    "assignmentSlotId": "362105579390504961",
    "effectiveDate": "2026-09-26",
    "evidenceFileIds": [],
    "confirmedWithoutEvidence": true,
    "sideEffects": {
      "vehicleStatusUpdated": "busy",
      "driverStatusUpdated": "busy",
      "reconPrepRowsCreated": null,
      "reconPrepMarkedCanceled": 0
    }
  },
  "success": true
}

空数据 / 降级响应

本端点是单条写操作，无空数据态。目标行判定改期残留行失败（依赖的 order-v3 查询不可达）时，不返回部分结果、不猜测是否残留，一行都不取消，直接走错误响应（见下方 605710）。

{ "code": 605710, "message": "订单服务不可用：取改期残留判定所需的用车需求日期窗失败", "success": false }

错误响应

{ "code": 605009, "message": "派单不存在", "success": false }

{ "code": 605026, "message": "未上传取消凭证，请二次确认后再取消", "success": false }

{ "code": 605027, "message": "行程已出发，不能整组取消，请使用修改派单", "success": false }

其它错误码：400（cancelReason/driverNotified/requestId 请求校验）/ 605020「当前派单状态不允许此操作」/ 605028「生效日期不在派单服务日期范围内」/ 605047「行程已结束，派车信息只读，不能修改或改派」（AssignmentService.java:5410 assertTripMutable）。605027/605047/605028 三码仅在目标行判定为非改期残留行时才可能命中；判定为改期残留行时豁免这三码，改走单行取消分支。

业务边界

• 改期残留行判定（AssignmentDailyPlanFacts.isRescheduleResidue，经 AssignmentService.resolveCancelResidueWindow/isCancelResidueRow 调用）：仅逐日行（非全程行）参与判定；判定要在加锁前实时查询 order-v3 侧当前用车需求的日期窗，查询失败直接抛 605710，不对残留身份做任何假设，不取消任何行。
• 单行取消：残留行确认后，只取消这一行；同派车组内落在窗口以内的其它日期行不受影响、不校验、不触发状态机。
• 整组取消：非残留行维持原逻辑——取消会按派车组整体处理（resolveEffectiveGroupRows 圈定的全部可取消行），605027/605047/605028 三道日期门原样校验，effectiveDate 仍取 cutoffDate（默认今天，只接受今天）。
• 落库状态并非恒为 canceled：来源行状态是 unassigned 时落 canceled；是 assigned/holding（在途）时落 exception（#6152 既有分流规则，不因残留身份而不同）。
• 凭证累积：命中残留分支时同组会分多次调用逐行取消，若整组替换式返回本次入参会丢掉前几次的凭证；因此 evidenceFileIds 统一改为按组读取累计清单（assignmentEvidenceService.listCancellationFileIds(groupId)），前端应直接以响应值为准，不要自行拼接历史值。
• 操作日志：仅命中残留分支时，assignmentOperationLog 的 CANCEL_REQUESTED 记录 detailJson 会带 "scope":"RESIDUE_ROW"；非残留（整组）分支不写这个键（不是写 "GROUP"，而是完全没有该字段）。可通过 GET /admin/fleet/board/orders/{orderId} 的 operationLog[].detailJson 读取核对。
• 司机通知：driverNotified=false 仍允许取消，仅作人工存证，后端不代为通知。
• 幂等性：requestId 走 @Idempotent，10 秒窗口内重复提交被拦截（提示「派单取消处理中，请勿重复提交」）。

---

四、契约约束与正确调用方式

残留行判定是服务端自动完成的，前端不需要预判

前端调用取消接口时无需先判断目标行是否为「改期残留行」——服务端在处理请求时会自动查询、自动分流。前端只需按现有交互正常收集 cancelReason/driverNotified/requestId 等必填参数发起请求：

• 命中残留行分支时，响应正常返回 200，effectiveDate 恒为今天，同派车组内其它行不受影响；前端无需额外处理。
• 判定依赖的 order-v3 查询失败时，返回 605710，此时一整行都没有取消，前端应按普通失败提示处理并允许重试，不需要区分"是不是残留行"。

evidenceFileIds 的正确使用方式

本次请求携带凭证时，CancelRespVO.evidenceFileIds 返回该派车组截至本次累计的全部取消凭证 ID，旧在前新在后（而不是本次请求入参那几个；AssignmentService.java:5526-5527）。前端展示「该派车组已上传哪些取消凭证」时，应直接使用响应值整体覆盖式渲染，不要再把它与本地缓存的历史值做拼接，否则会出现重复 ID。

若本次请求未携带任何凭证（evidenceFileIds 为空、以 confirmWithoutEvidence=true 放行 605026），响应的 evidenceFileIds 为空数组——这不代表该派车组没有历史凭证，只是本次响应未重新拉取累计列表（hasEvidence 为 false 分支不会调用 listCancellationFileIds）。因此前端不要用空数组覆盖已展示的历史凭证；需要展示累计凭证时，以最近一次携带凭证的取消响应为准。

---

五、数据库行为

• fleet_assignment：目标行 assignment_status 更新——来源行是 unassigned 写 canceled，是 assigned/holding（在途）写 exception（#6152 既有分流规则，不因是否残留行而不同）；updated_by 显式落取消操作人。无表结构变更、无新增列。
• fleet_assignment_evidence：hasEvidence=true 时追加新行（assignmentEvidenceService.appendCancellationEvidenceValidated），不删除、不覆盖已有记录。
• fleet_assignment_operation_log：追加一条 CANCEL_REQUESTED 记录；detail_json 命中残留行分支时带 "scope":"RESIDUE_ROW"，非残留（整组）分支不写 scope 键（不是写 "GROUP"）。hasEvidence=true 时另追加一条 CANCEL_EVIDENCE_RECORDED 记录。
• 无新增表、无新增列：改期残留行的判定结果本身不落库，每次取消请求都会重新实时查询 order-v3。

---

六、边界行为

• 未登录 → 401（网关拦截）。
• 派单不存在 → 605009。
• 状态不允许（如已取消、已完结） → 605020。
• order-v3 不可达 → 605710 fail-closed，一行都不取消，不对残留身份做任何猜测。
• 无凭证未二次确认 → 605026。
• 非残留行已出发 → 605027；非残留行程已结束 → 605047；非残留行生效日不在服务日期范围内 → 605028——这三码只在非残留分支可能命中，残留行分支豁免。

---

六.6、修改前后对比

行为对比

行为	改前	改后
取消改期残留行	按整组处理，605027/605047/605028 三道日期门正常校验，同组内已出发的其它行会导致整组取消被拒	新增单行分支：只取消该行本身，豁免三道日期门，effectiveDate 固定今天；同组其它行不受影响
order-v3 查询失败时的处理	不涉及（改前无此依赖）	新增 fail-closed：605710，一行都不取消
夜间自动完结	残留行与其它行一样，到期后被 AssignmentCompleteJob 自动置 completed	残留行被跳过，停留在原状态直到车务手工调用本接口取消

出参字段对比

字段	改前	改后
evidenceFileIds	本次请求入参携带的凭证 ID 原样返回	语义变更：该派车组自创建以来累计的全部取消凭证 ID（hasEvidence=true 时返回累计列表，为 false 时返回空数组）

---

六.7、影响评估

• 是否破坏向后兼容：否。改期残留行的单行取消是新增的判定分支，非残留行（含全程行）的整组取消逻辑、三道日期门校验逐字不变。evidenceFileIds 字段名、类型（Array<Long>/序列化为字符串数组）均未变，只是同一个字段返回的内容集合变了。
• 前端是否必须同步上线：否。前端不做任何改动，取消接口对非残留行的调用行为与改前完全一致；对残留行的调用会自动享受到"不再报 605027/605047/605028"的效果，不需要前端识别或适配。唯一需要前端注意的：如果前端此前把 evidenceFileIds 当作"本次上传的文件"做本地拼接展示，接入后应改为直接使用响应值整体替换，否则会展示出重复的凭证 ID。
• 覆盖边界：本次改动不影响 POST /admin/fleet/assignments/batch、POST /admin/fleet/assignments/requirements/{requirementId}/confirm 等相邻写口自身的契约，只是这些写口在残留行被移出组后不再对该组报改前的连带错误（100001/605055），详见「八、测试环境已验证」步骤 4/6 的实测记录。

---

七、不影响范围

• 仅影响：DELETE /admin/fleet/assignments/{assignmentId} 对改期残留行的判定分支，以及 evidenceFileIds 的取值口径。
• 零影响：
  • 非残留行（含全程行）的整组取消规则，三道日期门校验逐字不变。
  • 派车创建、批量重提、需求确认等其它写口自身的入参/出参契约。
  • 车辆/司机占用释放的条件判断逻辑（sideEffects 字段结构不变）。
  • #6152 既定的取消状态分流规则（unassigned→canceled，assigned/holding→exception）。

---

八、测试环境已验证

部署：PR #8380 已合并 dev-v3（c2bc5c3d4），测试服 hl-fleet-service 已部署该 commit；本单不改 order-v3。

以下 6 步为同一夹具的全链路真实网关调用（夹具：orderId=2103714435619303425，改期后需求窗 2026-10-02~10-04，派车组 3 行，其中 2026-09-20 一行落在窗外）：

1. 改前状态：GET /admin/fleet/board/orders/{orderId} 确认三行初始状态均为 assigned。
2. DELETE 残留行：对 2026-09-20 这一行发起取消，改前同一请求体命中 605027（拒绝整组取消）；改后单行取消直接成功，返回 assignmentStatus="exception"（该行取消前是 assigned，按 #6152 分流落 exception）、evidenceFileIds=[]。
3. 复读验证：窗内两行逐字段（vehicleId/driverId/assignmentPrice/priceSource/assignmentStatus 等）与改前基线完全一致，未受影响；操作日志新增一条 detailJson 含 "scope":"RESIDUE_ROW" 的记录。
4. 批量重提窗内行：POST /admin/fleet/assignments/batch 提交窗内两行，改前同一请求体命中 100001（"已过去或已完结，不能修改逐日派车配置"）；改后不再报错（残留行已单独取消，不再纳入本次提交的校验范围）。
5. 取新 generation：复读 dispatchPlanGeneration 供确认步骤使用。
6. 需求确认：POST /admin/fleet/assignments/requirements/{requirementId}/confirm 成功，改前基线在此步命中 605055（"派车方案已变化，请刷新后重试"），改后成功确认。

全链路（DELETE 残留行 → 批量重提窗内行 → 需求确认）打通，改前基线记录的三处拒绝（605027/100001/605055）在改后代码下不再复现。

---

十、相关文档

• 关联 Issue: wx/HL#8371
• 关联 PR: wx/HL#8380
• 上游工单: #5935（改期残留清理，见 20_5935_改期残留清理用现有读写口即可-前端缺陷-管理后台.md 内 9 处订正指针）

关联 / 联系人

链接

• Issue: #8371
• PR: #8380
• Merge commit: c2bc5c3d4

联系人

• 后端负责人: @wx
• 前端负责人: @mmg