diff --git a/changelogs-v2/2026-07/28_5305_逐日方案重提与完成闭环不变量-修改接口-管理后台.md b/changelogs-v2/2026-07/28_5305_逐日方案重提与完成闭环不变量-修改接口-管理后台.md new file mode 100644 index 0000000..762b153 --- /dev/null +++ b/changelogs-v2/2026-07/28_5305_逐日方案重提与完成闭环不变量-修改接口-管理后台.md @@ -0,0 +1,79 @@ +--- +schema: "hl-changelog/v2" +ticket: "5305" +title: "逐日方案重提与完成闭环不变量" +consumer: "admin" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "仅修正既有逐日派车保存与需求完成事务语义;接口路径、方法、请求响应字段和前端交互均不变" +updated_at: "2026-07-28" +base: "dev-v3" +--- + +# Fleet:逐日方案重提与完成闭环不变量 + +> **服务**:`hl-fleet-service` +> **Issue**:#5305 +> **影响页面**:管理后台车务管理 → 逐日逐车派车方案保存 +> **兼容性**:接口路径、方法、请求/响应字段、错误码和数据库结构不变,仅修正既有事务语义 + +## 问题与目标 + +逐日派车支持重复提交最终方案。旧实现存在五类边界:全程不用车或没有实际创建命令时会绕过最终订单基线;留车/直派模式变化可能被误判为无变化;混合方案中的历史已完结切片可能因旧冻结标记缺失阻断需求完成;仅修改逐日价格原因不会落库;同槽索引的旧取消版本可能抢占当前稳定槽位。 + +本次后端统一修复上述重提、冻结和完成闭环,不新增前端参数或返回字段。 + +## 变更接口(既有语义修正) + +### `POST /admin/fleet/assignments/batch` + +请求和响应形状不变: + +1. 包含 `dailyPlan` 的保存会在资源锁内完成写入后、冻结最终方案和生成需求完成 Outbox 前,再次读取当前订单详情、行程和 active 用车需求;日期、人数、行程或需求版本漂移时整批事务回滚。 +2. 即使全部 `dailyPlan[].used=false`,或本次没有实际创建车辆/司机派单,也执行同一最终基线门禁。 +3. 重提时同时比较目标 `holdMode`、派单状态、车辆、司机、接机参与、逐日价格和逐日价格调整原因: + - `holding → direct` 会按直派目标重新落地; + - `assigned → hold` 会按留车目标重新落地; + - 原因新增、修改和在不再偏离日历价时清空不再被忽略;偏离日历价时原因必填规则保持不变。 +4. 历史 `completed` 逐日切片即使来自旧数据、没有 `dispatchPlanFinalized=1`,在同一矩阵已有显式冻结切片时也按不可变的已完成权威日处理;不修改其业务状态,也不会把纯旧版未冻结拓扑误认成新最终方案。 +5. 同一 `fleetItemIndex` 同时存在旧 `canceled` 版本和当前在途/非取消版本时,稳定槽位优先沿用当前版本,避免重写命中历史槽位。 + +所有失败仍沿用现有错误响应结构;事务失败不产生需求完成事件。 + +## 前端处理 + +无需修改前端代码: + +- 继续提交现有 `dailyPlan`、`holdMode` 和逐日价格原因; +- 基线漂移时继续展示后端现有失败提示并刷新后重试; +- 不需要新增字段、状态分支或页面组件。 + +因此 `frontend_status=not_required`。 + +## 不影响范围 + +- 不修改 Controller、VO/DTO/BO、Feign 或 shared Java 契约。 +- 不修改数据库字段、迁移、Long ID 字符串和手机号脱敏规则。 +- 不改变已完成/已取消业务状态,不放宽历史、完结或关账只读门禁。 +- 不修改 `hl-ui` 仓库。 + +## 验证证据 + +- 后端 PR `[wx/HL#5306](https://git.1814.love:8443/wx/HL/pulls/5306)` 已 squash 合并至 `dev-v3`,合并提交 ``594d932db``。 +- `hl-fleet-service` 已滚动部署测试环境,8087/8187 双实例健康。 +- 定向 `AssignmentServiceTest,FleetAssignmentMapperTest`:328 tests,0 failures,0 errors,0 skipped。 +- Fleet reactor verify:2480 tests,0 failures,0 errors,1 skipped;Spotless 628 Java files clean。 +- 独立 Reviewer 无未解决 P0–P1。 +- 真实测试网关通过登录和车务矩阵只读查询确认部署后网关、认证及 Fleet 服务链路正常;本次内部事务修正没有可安全构造的写侧正例,核心五类边界由定向测试覆盖,探针不产生业务写入。 +- 网关证据:`D:/work2/HL-v3/.tmp/5305-gateway.json`,SHA-256 ``4698b3b8b1765715f6dc823664b3d24df2e977d26e6e19da08b5e298c6b6b0f6``。 +- 契约审查:`not_required`;当前 diff 无 Controller、请求响应模型、Feign 或 shared Java 变化。 + +当前状态:后端已部署、网关兼容探针已通过,前端无需改造。 + +关联:#5305。