hl-api-changelog/changelogs-v2/2026-09/16_7443_派车行补团期ID-看板按团筛选-修改接口-管理后台.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	7443	派车行补团期 ID + 看板按团筛选	admin	wx(GIT)	修改接口	deployed	verified	verified	mmg	23f6ac2fb76260ce620ed2f6b3cbe8638b21caf0		2026-09-16	后端交付。新增 fleet_assignment.group_batch_id 列及 order_main.group_batch_id 在 Feign 契约中的透出；看板订单列表接口新增可选筛选参数 groupBatchId。前端需在看板列表筛选控件增加团期下拉框。；前端 hl-admin 23f6ac2f 已实现：派单看板筛选条加团期远程搜索下拉(候选取 /fleet/group-dispatch/pending-batches),groupBatchId 雪花串仅列表接口透传,spec +5,checkpoint 全绿。	2026-09-16	dev-v3

fleet/order-v3: 派车行补团期 ID + 看板按团筛选

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

服务: hl-fleet-service (端口 8082)、hl-order-service-v3 (端口 8083) PR: #7792 Issue: #7443 PR-A 日期: 2026-09-16 影响范围: 看板订单列表新增可选团期精确筛选参数；派车行新增团期 ID 列（存量行为 NULL）

---

关键变化

1. 派车行数据结构扩展：fleet_assignment 表新增 group_batch_id 列，记录该派车行创建时所属的团期 ID（快照语义，后续换团不回溯刷新）。存量派车行与车务手工建立的行该列为 NULL。
2. 看板列表新增筛选参数：GET /admin/fleet/board/orders 支持按 groupBatchId 精确筛选，返回指定团期在该派车行上的派车记录（含已退团户的历史行）。
3. Feign 契约扩展：OrderDetailForFleetDTO 新增 groupBatchId 字段透出订单的团期信息，供 fleet 侧建立派车行时记录快照。

---

一、背景

#7060 推进了子订单流程，但派车行在建立时未捕存团期身份，导致车务团期级别的查询、排期、对账无法从派车行维度精确溯源。本次补上派车行的团期 ID 快照，同时在看板列表提供团期级别的筛选入口，方便车务按团期查看派车状态。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	看板列表	GET	/admin/fleet/board/orders	修改	新增可选筛选参数 groupBatchId（运营团期精确筛选）
2	订单详情（Feign 契约）	GET	/internal/order/{id}/detail-for-fleet	修改	响应 DTO 新增字段 groupBatchId

---

三、接口详情

1. 看板列表 GET /admin/fleet/board/orders

VO: BoardOrderPageReqVO → BoardOrderPageRespVO

使用场景

派单看板列表查询。新增团期筛选参数 groupBatchId 后，可按运营团期精确查询该团的全部派车行（含已退团户的历史记录）。与现有 teamNo（人读团号，模糊匹配）区别在于本字段是团期主键、做等值匹配且只认派车行建立时的快照。

入参字段表

字段	位置	类型	必填	约束	说明
groupBatchId	Query	Long	否	-	运营团期 ID 精确筛选（团期车务；存量行与手工建行为空不匹配）
teamNo	Query	String	否	≤32 字符	团号模糊搜索（仅真实团号，不匹配订单号）
pageNo	Query	Integer	否	≥1，默认 1	分页页码
pageSize	Query	Integer	否	1-100，默认 20	每页条数

出参字段表

字段	类型	说明
total	Long	符合条件的记录总数
records	List	分页结果集
records[].orderId	Long	订单 ID
records[].orderNo	String	订单号
records[].teamNo	String	团号（当前真实值）
records[].groupBatchId	Long	团期 ID（派车行快照，可能为 NULL）
records[].customerName	String	客户名（脱敏）
records[].productName	String	产品名
records[].consultantName	String	定制师名

请求示例

GET /admin/fleet/board/orders?groupBatchId=1934567890123456800&pageNo=1&pageSize=20

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "total": 5,
    "records": [
      {
        "orderId": 1934567890123456789,
        "orderNo": "26-0503",
        "teamNo": "26-7218",
        "groupBatchId": 1934567890123456800,
        "customerName": "赵先生",
        "productName": "额吉的故乡 v9",
        "consultantName": "苏日娜"
      }
    ]
  },
  "success": true
}

空数据 / 降级响应

{
  "code": 200,
  "data": {
    "total": 0,
    "records": []
  },
  "success": true
}

错误响应

{
  "code": 403,
  "message": "权限不足",
  "success": false,
  "data": null
}

业务边界

• 鉴权: 需 admin 权限
• 筛选逻辑: groupBatchId 与 teamNo 可同时传入
• 存量数据: 上线前建立的派车行 groupBatchId 为 NULL，等值筛选一律落选
• 已退团户: 历史派车行被保留，按快照 groupBatchId 筛选时会命中已退团户的记录

---

2. 订单详情（Feign 契约内部接口） GET /internal/order/{id}/detail-for-fleet

VO: (路径参数 → OrderDetailForFleetDTO)

使用场景

fleet 侧派单看板详情步骤 1 调用，拉取当前订单摘要、行程、用车需求等只读快照。本次扩展增加 groupBatchId 字段，供 fleet 侧在建立派车行时记录团期身份快照。

入参字段表

字段	位置	类型	必填	约束	说明
id	Path	Long	是	-	订单 ID

出参字段表

字段	类型	说明
orderId	Long	订单 ID
orderNo	String	订单号
teamNo	String	团号（当前真实值）
groupBatchId	Long	团期 ID（可空，普通订单为 NULL）
customerName	String	客户名（脱敏）
headcount	Integer	出行人数
productName	String	产品名

请求示例

GET /internal/order/1934567890123456789/detail-for-fleet

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": 1934567890123456789,
    "orderNo": "26-0503",
    "teamNo": "26-7218",
    "groupBatchId": 1934567890123456800,
    "customerName": "赵先生",
    "headcount": 2,
    "productName": "额吉的故乡 v9"
  },
  "success": true
}

空数据 / 降级响应

N/A（订单存在即返回数据）。

错误响应

{
  "code": 404,
  "message": "订单不存在",
  "success": false,
  "data": null
}

业务边界

• 鉴权: 内部 Feign 调用
• groupBatchId 语义: 团期主键，普通（非团）订单为 NULL；子订单继承主单的值
• 退团后: groupBatchId 不回溯刷新，保持建单时的快照

---

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

场景	做法
按团期查看派车历史	传 groupBatchId 参数到看板列表
创建派车行时捕存团期	调 Feign 契约拿到 groupBatchId，回写入派车行
订单换团后看板显示	teamNo 显示当前实时值；groupBatchId 显示快照值（不变）

---

五、数据库行为

操作	fleet_assignment.group_batch_id
创建派车行（新订单）	取自 OrderDetailForFleetDTO.groupBatchId
订单换团	不变（建立时的快照）
存量派车行	NULL

---

六、边界行为

• 团期不存在 → 看板查询返 0 条记录
• groupBatchId 为 NULL → 等值筛选不匹配
• 权限不足 → 403
• 订单不存在 → 404

---

六.6、修改前后对比

字段对比

字段	改前	改后
BoardOrderPageReqVO.groupBatchId	不存在	新增，可选，等值筛选
fleet_assignment.group_batch_id	不存在	新增，快照值
OrderDetailForFleetDTO.groupBatchId	不存在	新增

---

六.7、影响评估

• 是否破坏向后兼容: 否（均为新增可选字段）
• 前端是否必须同步上线: 是（需增加团期筛选控件）
• 前端 workaround 清理点: 无

---

七、不影响范围

• 仅影响: 派单看板列表的筛选维度
• 零影响:
  • 派车行创建流程
  • 订单详情页
  • 换团逻辑
  • 其他看板模块

---

八、测试环境已验证

GET /admin/fleet/board/orders → 200 ✓
GET /admin/fleet/board/orders?groupBatchId=1934567890123456800 → 200 ✓
GET /internal/order/1934567890123456789/detail-for-fleet → 200 ✓

---

十、相关文档

• Issue: #7443
• PR: #7792
• Merge commit: ac07acd4b

关联 / 联系人

链接

• Issue: #7443
• PR: #7792
• Merge commit: ac07acd4b

联系人

• 后端负责人: @wx