docs: #9192 已安排团人数/特殊诉求变更拒绝说明

2026-10-23 10:09:55 +08:00
@@ -0,0 +1,72 @@
+---
+schema: "hl-changelog/v2"
+ticket: "9192"
+title: "已安排团人数/特殊诉求变更改为显式拒绝（同步失败原因补充类别）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "已合并 dev-v3（PR #9204，squash e5e6fe212），已部署测试服任务 7e46904c，双实例 8187/8087 均 is UP；真账号 wx 经网关 GET 派车工作台列表 HTTP 200 / code 200，39 团全部返回。本次只改来源同步落库的拒绝条件与 reason 文案：内部同步接口外层错误码仍为 603050，管理后台调用的查询接口入参/出参零变化；hl-ui 无需改代码。"
+updated_at: "2026-10-23"
+base: "dev-v3"
+---
+
+# 已安排团人数/特殊诉求变更改为显式拒绝（管理后台告知）
+
+> 面向：管理后台前端（hl-ui）
+> 日期：2026-10-23 ｜ 后端：hl-fleet-service（二期 dev-v3）
+> 结论：**管理后台查询接口零变化、前端无需改代码**；来源同步在「已安排团 + 人数/特殊诉求变化」时会恢复为显式失败，失败原因会说明是哪一类变更。
+
+## 一、背景
+
+派车工作台用「需求已变」徽标提示调度重排车。该徽标只覆盖「车型提示 / 建议辆数 / 接送趟日期」三样；订单侧改人数或特殊诉求，不在标记范围内。
+
+此前的行为是：已安排过车的团收到这类变更时，后端会把新值静默落库、不置任何标记，调度看不到徽标，可能按原车派出。本单把这类变更恢复为显式拒绝，避免静默改数。
+
+## 二、变更点
+
+| 项 | 内容 |
+|---|---|
+| 影响层 | 来源同步落库（内部链路，非管理后台查询接口） |
+| 触发变化 | 已安排团 + 需求行人数 / 特殊诉求变更时，由「静默落库」改为「显式失败」 |
+| 失败原因 | `团已安排过车：本版本不支持已安排团的人数、特殊诉求等内容变更，请先撤回派车行后再同步` |
+| 管理后台接口 | 入参、成功响应、分页结构逐字未变；团详情等查询接口不会因此新增 500 |
+| 前端动作 | 不需要改代码；本告知用于让前端/支持人员知道同步失败的新原因 |
+
+## 三、触发条件
+
+同时满足以下条件时，来源同步落库失败：
+
+1. 该团已经安排过车（存在未撤下的派车行）；
+2. 订单侧同步过来的需求行，人数（headcount）或特殊诉求（specialTags）发生变化；
+3. 这两类字段不属于「需求已变」徽标覆盖的车型 / 辆数 / 接送日期三样。
+
+未安排过车的团不受影响：人数、特殊诉求照旧落库，不置标记。
+
+## 四、错误表现
+
+| 项 | 值 |
+|---|---|
+| 内部同步外层错误码 | `603050`（DISPATCH_SOURCE_SNAPSHOT_INVALID，未变） |
+| reason / message | `团已安排过车：本版本不支持已安排团的人数、特殊诉求等内容变更，请先撤回派车行后再同步` |
+| 管理后台可见性 | 团详情的顺手同步是异步执行并吞异常的，不会把这条 message 直接返回给页面；管理后台不新增错误分支 |
+| 处置建议 | 调度先撤回该团派车行，再重新同步；不要把它当成系统故障 |
+
+内部常量 `REJECT_ARRANGED` 的文案同步更新；前端不应依赖内部常量名。
+
+## 五、不影响范围
+
+- 管理后台查询接口的请求参数、成功响应字段、分页结构：逐字未变。
+- 车型 / 辆数 / 接送日期变更：仍放行，仍置「需求已变」。
+- 未安排团：人数 / 特殊诉求仍照常落库，不置标记。
+- 不新增表、不新增列、不改 Flyway、不涉及金额。
+
+## 六、测试环境已验证
+
+2026-10-23 已部署 dev-v3（提交 e5e6fe212）到测试服，双实例 8187/8087 均 is UP；真实账号 wx 登录后经网关 GET 派车工作台列表 HTTP 200 / code 200，39 团全部返回。真 MySQL 事务用例覆盖：已安排团人数变更、特殊诉求变更均拒绝且库中原值不变；未安排团两类变更均落库且不置标记。