---
schema: "hl-changelog/v2"
ticket: "7443"
title: "派车行补团期 ID + 看板按团筛选"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: "2026-09-16"
status_note: "后端交付。新增 fleet_assignment.group_batch_id 列及 order_main.group_batch_id 在 Feign 契约中的透出；看板订单列表接口新增可选筛选参数 groupBatchId。前端需在看板列表筛选控件增加团期下拉框。"
updated_at: "2026-09-16"
base: "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 | 定制师名 |

#### 请求示例

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

#### 响应示例

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

#### 空数据 / 降级响应

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

#### 错误响应

```json
{
  "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 | 产品名 |

#### 请求示例

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

#### 响应示例

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

#### 空数据 / 降级响应

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

#### 错误响应

```json
{
  "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](https://git.1814.love:8443/wx/HL/issues/7443)
- PR: [#7792](https://git.1814.love:8443/wx/HL/pulls/7792)
- Merge commit: [ac07acd4b](https://git.1814.love:8443/wx/HL/commit/ac07acd4b)

## 关联 / 联系人

### 链接

- **Issue**: [#7443](https://git.1814.love:8443/wx/HL/issues/7443)
- **PR**: [#7792](https://git.1814.love:8443/wx/HL/pulls/7792)
- **Merge commit**: [ac07acd4b](https://git.1814.love:8443/wx/HL/commit/ac07acd4b)

### 联系人

- **后端负责人**: @wx