wx/hl-api-changelog

派生 0

文件

T

API Changelog Bot和Claude Opus 5 e4fc9d1a90

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog): 补 09-17 两份的 target_release，解开 pre-push 门禁

推送被拦：E_FRONTEND_STATE「verified 必须填写 target_release」
(scripts/validate-changelog-frontmatter.mjs:325-327)。

这两处不是本次改出来的，昨天就空着。门禁只看本次推送的变更集，
所以碰到哪个文件哪个文件才暴露 —— 实测全仓 frontend_status=verified 的
182 个文件 target_release 全是空的，属潜伏的不一致，不是这两份特有。
本次只修我动过的这两个，没有顺手去改另外 180 个。

取值不猜：当前惯例是 target_release = "hl-ui@" + frontend_ref 前 8 位
(2026-08-23 ~ 2026-09-13 连续 6 例；旧惯例 v2.1 在 9 月只剩 2 例)，
填进去的只是复述文件里已记着的那个前端提交，不是对发布号的新声明。

⚠️ 记一句给后来人：validate-changelog-frontmatter.mjs --files <单个文件> 过了
不等于能推 —— 它只校验你点名的那些，而门禁校验的是本次推送的全部变更文件。
贴校验结果时要连「校验了几个对象」一起贴。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-18 08:06:47 +08:00

11 KiB

原始文件 Blame 文件历史

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	7442	团级确认态 + 需求已发车务回写	admin	wx(GIT)	新增接口	deployed	verified	verified	mmg	b84a5d6bcab491b3ecc71b811762946af35cec09	hl-ui@b84a5d6b	2026-09-17	后端交付。新增 fleet 确认整团配车端点 + order-v3 内部回写端点，支持异步回写正式用车需求状态。前端需在团期配车页增加确认按钮。前端已交付(2026-09-17):配车总览抽屉并行拉总览+order-v3 用车需求,需求 CONFIRMED 且有乘车分组出「确认整团配车」(免车空分组/DRAFT 不出,DISPATCHED 显已确认 tag),remark≤200 空白剥离;幂等与 602005-602009 透 message;api spec 2+抽屉 spec 4 全过,checkpoint 全量绿。	2026-09-17	dev-v3

fleet/order-v3: 团级确认态 + 需求已发车务回写

存放目录: changelogs-v2/{YYYY-MM}/（管理后台，二期 fleet + order-v3）

服务: hl-fleet-service (端口 8082)、hl-order-service-v3 (端口 8083)
PR: #7862
Issue: #7442 PR-B
日期: 2026-09-17
影响范围: 新增团期配车确认接口；新增需求状态异步回写链路

关键变化

新增确认接口：fleet 侧新增 POST /admin/fleet/group-dispatch/batches/{groupBatchId}/confirm，车务在配车计划提交并通过后，可调用本端点把整团配车定稿，转入「已确认」态。
异步回写链路：确认成功后，fleet 侧登记一条 Outbox 意图，经 Outbox 异步投递调用 order-v3 内部端点 POST /v3/internal/group-batch/{groupBatchId}/vehicle-requirement/dispatched，把正式用车需求从 CONFIRMED 推进到 DISPATCHED。
新增错误码：602007（无可确认行）/ 602008（覆盖不完整）用于确认端点的校验失败。
部署顺序：order-v3 先部署，fleet 后部署（后端实现细节）。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	确认整团配车	POST	`/admin/fleet/group-dispatch/batches/{groupBatchId}/confirm`	新增	车务确认配车方案落定
2	回写需求已发车务	POST	`/v3/internal/group-batch/{groupBatchId}/vehicle-requirement/dispatched`	新增	[内部接口] fleet 确认后异步回写需求状态

三、接口详情

1. 确认整团配车 `POST /admin/fleet/group-dispatch/batches/{groupBatchId}/confirm`

VO: GroupDispatchConfirmReqVO → GroupDispatchConfirmRespVO

使用场景

车务在看板完成团期配车计划提交后（配车行已过验证、状态为「已派车」），调用本端点把整团配车定稿、转为「已确认」态。确认成功后会异步推进正式用车需求的状态流转（CONFIRMED → DISPATCHED）；需求页需自行刷新以获取最新状态。

入参字段表

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	是	-	团期主订单 ID
requirementId	Body	Long	是	-	本次确认所依据的正式团级用车需求 ID（字符串序列化）
requirementVersion	Body	Integer	是	-	本次确认所依据的需求版本号
remark	Body	String	否	≤200 字符	确认备注（仅留痕，不写入配车行）

出参字段表

字段	类型	说明
groupBatchId	String	团期主订单 ID（字符串序列化）
confirmedCount	Integer	本次由「已派车」转为「已确认」的配车行数
alreadyConfirmedCount	Integer	确认前已是「已确认」的配车行数
requirementId	String	本次确认所依据的正式需求 ID（字符串序列化）
requirementVersion	Integer	本次确认所依据的需求版本
planVersion	Long	当前团期计划版本（确认不改计划，不递增）
requirementAdvanceIntent	String	已登记的需求回写意图方向，恒为 CONFIRMED_TO_DISPATCHED
coverage	Object	按乘车分组的覆盖明细
legacyGroupRowCount	Integer	无分组键的历史派车行数（不计入任何组的覆盖）

请求示例

POST /admin/fleet/group-dispatch/batches/1934567890123456800/confirm
{
  "requirementId": 5501,
  "requirementVersion": 3,
  "remark": "与地接确认车辆无误"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "1934567890123456800",
    "confirmedCount": 8,
    "alreadyConfirmedCount": 0,
    "requirementId": "5501",
    "requirementVersion": 3,
    "planVersion": 7,
    "requirementAdvanceIntent": "CONFIRMED_TO_DISPATCHED",
    "coverage": {
      "totalGroups": 2,
      "coveredGroups": 2,
      "incompleteGroups": []
    },
    "legacyGroupRowCount": 0
  },
  "success": true
}

空数据 / 降级响应

N/A（团期无可确认行时返 602007 错误）。

错误响应

{
  "code": 602008,
  "message": "配车尚未覆盖完整, 不能确认: 乘车分组 A 缺失 2026-05-08",
  "data": null,
  "success": false
}

可能的错误码：

602005 - 用车需求已更新，请刷新后重新配车
602006 - 正式用车需求当前状态不允许配车
602007 - 本团没有可确认的配车行，请先提交配车计划
602008 - 配车尚未覆盖完整，不能确认
602009 - 无法取得本团的权威乘车分组清单
600008 - 并发修改
600009 - 基线不可用

业务边界

鉴权: 需 fleet:group-dispatch:write 权限
幂等性: 重复确认返 confirmedCount=0、alreadyConfirmedCount=N（属幂等成功），HTTP 200 不是错误
防重提交: 本端点无防重时间窗，连点多次都是幂等成功形态
异步回写: 响应成功仅代表意图已登记，需求状态的实际推进可能稍后才发生；需求列表页需自行刷新
并发处理: 同团的并发调用由服务端串行化处理

2. 回写需求已发车务 `POST /v3/internal/group-batch/{groupBatchId}/vehicle-requirement/dispatched`

⚠️ [内部接口，不对前端开放] fleet 侧异步回写链路调用，通过 Feign 投递。

VO: GroupBatchVehicleRequirementDispatchedReqDTO → GroupBatchVehicleRequirementDispatchedRespDTO

使用场景

fleet 侧确认配车后，通过 Outbox 异步机制调用本端点，把正式用车需求从 CONFIRMED 推进到 DISPATCHED 状态。该端点不对前端暴露，仅供内部服务间通信。

入参字段表

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	是	-	团期主订单 ID
requirementId	Body	Long	是	-	车务确认所依据的正式需求 ID（字符串序列化）
requirementVersion	Body	Integer	是	-	车务确认所依据的需求版本
sourceRefNo	Body	String	否	-	幂等追溯号（fleet Outbox 记录 ID，用于日志对账）

出参字段表

字段	类型	说明
applied	Boolean	本次是否真的推进了需求状态
discardReason	String	applied=false 时的原因常量
requirementStatus	String	回写后提供方当前的需求状态
requirementVersion	Integer	回写后提供方当前的需求版本

请求示例

POST /v3/internal/group-batch/1934567890123456800/vehicle-requirement/dispatched
{
  "requirementId": "5501",
  "requirementVersion": 3,
  "sourceRefNo": "880123"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "applied": true,
    "discardReason": null,
    "requirementStatus": "DISPATCHED",
    "requirementVersion": 3
  },
  "success": true
}

空数据 / 降级响应

applied=false 时无新状态变化，仍返 200（幂等重放或需求已变版）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "applied": false,
    "discardReason": "IDENTITY_MISMATCH",
    "requirementStatus": "CONFIRMED",
    "requirementVersion": 4
  },
  "success": true
}

错误响应

真正的故障（DB 不可用、CAS 并发冲突）仍以异常形式返回失败 Result，由 Outbox 退避重试：

{
  "code": 500,
  "message": "数据库异常",
  "success": false,
  "data": null
}

业务边界

一律返 200: 本端点由 Outbox 重试链路驱动，任何判定结论都再投无用，故用 applied+discardReason 标记
幂等性: 重投同一条 sourceRefNo，结果保持一致
丢弃原因:
- IDENTITY_MISMATCH - 需求身份不一致
- REQUIREMENT_NOT_FOUND - 该团无活跃需求
- ALREADY_DISPATCHED - 需求已是完成态
- STATUS_INVALID - 需求状态不允许推进

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

场景	做法
车务确认配车	调 POST /admin/fleet/group-dispatch/batches/{id}/confirm，返回 confirmedCount
处理重复确认	confirmedCount=0 且 HTTP=200 为幂等成功
等待需求更新	需求列表页需自行刷新

五、数据库行为

操作	数据库影响
确认配车	fleet_group_dispatch.dispatch_status → CONFIRMED
Outbox 异步回写成功	order_group_vehicle_requirement.status → DISPATCHED

六、边界行为

无可确认行 → 602007（fail-closed）
覆盖不完整 → 602008（fail-closed）
需求版本不匹配 → 602005（fail-closed）
并发确认 → 第二个调用见 confirmedCount=0（幂等成功）
投递到达时需求已变 → applied=false + IDENTITY_MISMATCH

六.5 枚举

需求回写的丢弃原因:

IDENTITY_MISMATCH - 需求 ID/版本不符
REQUIREMENT_NOT_FOUND - 团无活跃需求
ALREADY_DISPATCHED - 需求已是完成态
STATUS_INVALID - 需求状态不允许推进

六.6 修改前后对比

端点	改前	改后
/admin/fleet/.../confirm	无	新增 POST
/v3/internal/group-batch/.../dispatched	无	新增 POST

六.7 影响评估

向后兼容: 是（新增端点）
前端同步: 是（需加确认按钮）
清理点: 无

七、不影响范围

仅影响: 团期配车确认流程、需求状态转移
零影响: 配车提交流程、其他需求转移路径、派单列表、看板显示

八、测试环境已验证

POST /admin/fleet/group-dispatch/batches/xxx/confirm → 200 ✓
POST /v3/internal/group-batch/xxx/dispatched → 200 ✓
重复确认 confirmedCount=0 ✓
异步回写已发送 ✓

十、相关文档

Issue: #7442
PR: #7862
Merge: a37bd669f

关联 / 联系人

链接

Issue: #7442
PR: #7862

联系人

后端: @wx

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

fleet/order-v3: 团级确认态 + 需求已发车务回写

关键变化

二、变更接口清单

三、接口详情

1. 确认整团配车 POST /admin/fleet/group-dispatch/batches/{groupBatchId}/confirm

使用场景

入参字段表

出参字段表

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 回写需求已发车务 POST /v3/internal/group-batch/{groupBatchId}/vehicle-requirement/dispatched

使用场景

入参字段表

出参字段表

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

六.5 枚举

六.6 修改前后对比

六.7 影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

链接

联系人

11 KiB

原始文件 Blame 文件历史

1. 确认整团配车 `POST /admin/fleet/group-dispatch/batches/{groupBatchId}/confirm`

2. 回写需求已发车务 `POST /v3/internal/group-batch/{groupBatchId}/vehicle-requirement/dispatched`