---
schema: "hl-changelog/v2"
ticket: "7440"
title: "团期车务派单只读入口——看板三端点 + 内部读接口 + GROUP_FLEET 双团会话"
consumer: "admin"
author: "wx(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: "2026-09-11"
status_note: ""
updated_at: "2026-09-11"
base: "dev-v3"
---

# fleet/order-v3/user: 团期车务派单只读入口

**服务**: hl-fleet-service / hl-order-service-v3 / hl-user-service  
**PR**: #7506  
**Issue**: #7440

---

## ⚠️ 关键变化

本单仅含只读入口，不含配车写入、不含派单进度回写（配车写入与派单进度回写在后续工单）。

---

## 一、背景

本单新增3个admin只读端点供fleet读取团期需求主数据(order-v3)与服务日，以及2个/internal/端点供fleet内部调用。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 待配车团期清单 | GET | `/admin/fleet/group-dispatch/pending-batches` | 新增 | 管理后台车务页首屏清单 |
| 2 | 团期配车总览 | GET | `/admin/fleet/group-dispatch/batches/{groupBatchId}/overview` | 新增 | 单团详情页派车总览 |
| 3 | 资源排班 | GET | `/admin/fleet/group-dispatch/resource-schedule` | 新增 | 派单编辑时查资源占用 |
| 4 | 打开团期配车会话 | POST | `/admin/message/chat/open-group-fleet` | 新增 | 车务↔团期管理员团级会话 |
| *内部* | 待配车候选分页 | POST | `/v3/internal/group-batch/vehicle-dispatch-candidates` | 新增 | 服务间接口，前端无需对接 |
| *内部* | 单团用车覆盖 | GET | `/v3/internal/group-batch/{groupBatchId}/vehicle-coverage` | 新增 | 服务间接口，前端无需对接 |

---

## 三、接口详情

### 1. 待配车团期清单 `GET /admin/fleet/group-dispatch/pending-batches`

**VO**: `GroupDispatchPendingBatchPageReqVO → Result<PageResult<GroupDispatchPendingBatchRespVO>>`

#### 使用场景

管理后台车务-团期配车页面的首屏清单。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| departDateFrom | Query | LocalDate | ❌ | - | 出发日下界 |
| departDateTo | Query | LocalDate | ❌ | - | 出发日上界 |
| keyword | Query | String | ❌ | ≤50字符 | 团号/团名 |
| dispatchProgress | Query | String | ❌ | NOT_STARTED/PARTIAL/FULL | 进度过滤 |
| page | Query | Integer | ❌ | ≥1 | 页码(默认1) |
| pageSize | Query | Integer | ❌ | 1-100 | 每页条数(默认20) |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| groupBatchId | Long | 团期ID |
| batchNo | String | 团号 |
| batchName | String | 团名 |
| departDate | LocalDate | 出团日 |
| dispatchProgress | String | 配车进度 |
| unreadCount | Integer | 车务未读数 |

#### 请求示例

```json
{
  "departDateFrom": "2026-09-01",
  "departDateTo": "2026-09-30",
  "page": 1,
  "pageSize": 20
}
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "total": 15,
    "records": [
      {
        "groupBatchId": 1934567890123456789,
        "batchNo": "GB-26-0912-01",
        "batchName": "额吉的故乡 9/12 团",
        "departDate": "2026-09-12",
        "dispatchProgress": "PARTIAL",
        "unreadCount": 3
      }
    ]
  },
  "success": true
}
```

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

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

#### 错误响应

```json
{
  "code": 600013,
  "message": "排班查询参数非法: departDateFrom 不能晚于 departDateTo",
  "success": false
}
```

```json
{
  "code": 600012,
  "message": "团期配车基线不可达，请稍后重试",
  "success": false
}
```

**降级链路**：600013 由本端点自身入参校验抛出（`page<1`/`pageSize`不在1-100/出发日区间倒挂/keyword超50字符/`dispatchProgress`枚举非法，五种情形共用同一个码）。600012 是本端点对外唯一的「上游不可达」码——内部经 Feign 调用 order-v3 团期用车候选口（`POST /v3/internal/group-batch/vehicle-dispatch-candidates`），该内部接口对同一批入参约束会独立抛 `809401 查询参数非法`（`GroupBatchVehicleReadErrorCode.java:38`），但本端点已先行校验挡在前面（不会把非法参数带给 Feign），且 `fetchCandidatesOrFail`（`GroupDispatchQueryService.java:314-336`）对 Feign 返回的任何非成功 Result（含 809401）一律失败关闭转成 600012——调用方看不到 809401 原始码。

#### 业务边界

- 进度是fleet内存过滤，故先分页再过滤，单页可能少于pageSize
- unreadCount软依赖，user-service不可达时退0

---

### 2. 团期配车总览 `GET /admin/fleet/group-dispatch/batches/{groupBatchId}/overview`

**VO**: `Long → Result<GroupDispatchOverviewRespVO>`

#### 使用场景

单团详情页的派车总览。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| groupBatchId | Path | Long | ✅ | - | 团期ID |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| groupBatchId | Long | 团期ID |
| serviceDates | List<LocalDate> | 权威服务日 |
| days | List | 逐日派车状态 |
| transferPendingTotal | Integer | 全团接送机未配计数 |
| conversationKey | String | 会话键 |

#### 请求示例

```json
GET /admin/fleet/group-dispatch/batches/1934567890123456789/overview
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "groupBatchId": 1934567890123456789,
    "serviceDates": ["2026-09-12", "2026-09-13", "2026-09-14"],
    "days": [
      {"serviceDate": "2026-09-12", "dispatched": true}
    ],
    "transferPendingTotal": 3,
    "conversationKey": "GROUP_FLEET:1934567890123456789"
  },
  "success": true
}
```

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

无。

#### 错误响应

```json
{
  "code": 600012,
  "message": "团期配车基线不可达，请稍后重试",
  "success": false
}
```

**降级链路（🔴 本端点对外只有 600012 这一个码）**：内部经 Feign 调用 order-v3 单团用车覆盖口（`GET /v3/internal/group-batch/{groupBatchId}/vehicle-coverage`），团期不存在或已软删时该内部接口会抛 `809400 团期不存在`（`GroupBatchVehicleReadErrorCode.java:28`）；但 `fetchCoverageOrFail`（`GroupDispatchQueryService.java:526-537`）把 Feign 返回的任何非成功 Result（含 809400）一律失败关闭转成 600012——本端点**不透出 809400**，调用方只会看到 600012，不要按「overview 会返 809400」处理。

#### 业务边界

- serviceDates是权威口径，fleet不得自己铺行程日

---

### 3. 资源排班 `GET /admin/fleet/group-dispatch/resource-schedule`

**VO**: `ResourceScheduleListReqVO → Result<List<ResourceScheduleRespVO>>`

#### 使用场景

派单编辑时查询车/司机的排班占用。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| resourceType | Query | String | ✅ | VEHICLE/DRIVER | 资源维度 |
| resourceIds | Query | List<Long> | ✅ | 1-50个 | 资源ID集合 |
| dateFrom | Query | LocalDate | ✅ | - | 起始日 |
| dateTo | Query | LocalDate | ✅ | ≤31天 | 结束日 |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| resourceType | String | 资源维度 |
| resourceId | Long | 资源ID |
| resourceLabel | String | 车牌/司机名 |
| days | List | 排班日历 |

#### 请求示例

```json
GET /admin/fleet/group-dispatch/resource-schedule?resourceType=VEHICLE&resourceIds=1&dateFrom=2026-09-12&dateTo=2026-09-30
```

#### 响应示例

```json
{
  "code": 200,
  "data": [
    {
      "resourceType": "VEHICLE",
      "resourceId": 1,
      "resourceLabel": "蒙A12345",
      "days": []
    }
  ],
  "success": true
}
```

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

返回空days列表。

#### 错误响应

```json
{
  "code": 600014,
  "message": "不支持的资源类型: BOAT",
  "success": false
}
```

```json
{
  "code": 600013,
  "message": "排班查询参数非法: 查询跨度不能超过 31 天",
  "success": false
}
```

**触发条件**：600014 仅在 `resourceType` 不是 `VEHICLE`/`DRIVER` 时抛出（示例中 `BOAT` 为非法值占位）。600013 覆盖：`resourceIds` 为空 / 超 50 个、`dateFrom`/`dateTo` 为空、日期倒置、跨度超 31 天，五种情形共用同一个码。本端点只读本域两张业务表，不经 Feign 调用 order-v3，故与 809400/809401 无关。

#### 业务边界

- 不分页，规模由参数上限封死
- 返回顺序必须与入参顺序相同

---

### 4. 打开团期配车会话 `POST /admin/message/chat/open-group-fleet`

**VO**: `ChatOpenGroupFleetReqVO → Result<ChatOpenFullRespVO>`

#### 使用场景

派单看板打开团期的车务↔团期管理员会话。

#### 入参字段表

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| groupBatchId | Body | Long | ✅ | - | 团期ID |

#### 出参字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| conversationKey | String | 会话键 |
| conversationId | Long | 会话ID |
| currentSide | String | GROUP_ADMIN / VEHICLE_TEAM |

#### 请求示例

```json
{
  "groupBatchId": 1934567890123456789
}
```

#### 响应示例

```json
{
  "code": 200,
  "data": {
    "conversationKey": "GROUP_FLEET:1934567890123456789",
    "conversationId": 1934567890123456789,
    "currentSide": "GROUP_ADMIN"
  },
  "success": true
}
```

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

无。

#### 错误响应

```json
{
  "code": 281018,
  "message": "无权访问该团期配车会话",
  "success": false
}
```

```json
{
  "code": 281019,
  "message": "团期不存在、已结算或已取消，无法发起配车会话",
  "success": false
}
```

**分工**：281018 = 有登录态但当前角色既非 `VEHICLE_MANAGER`（车务侧）也不持 `group-batch:demand:confirm`（团期管理员侧，超管天然通过）——准入完全按 token 当前角色判，与是否为会话成员无关（`TeamChatAuthorizationService.java:158-169`）。281019 = 团期本身不可联系（不存在/已软删/已结算/已取消），前置条件与 `GROUP_HOUSE` 用的 281017 同源（`TeamChatModule.java:75`）。**281019 只卡 open（本端点）/ send，`messages`/`read` 仍放行**（`requirePrecondition` 参数为 false，见 `ChatMessageController.java` 的 `/{conversationKey}/messages`）——终态团期的历史会话仍可审计读取，前端不要因为拿到过 281019 就连历史消息一起屏蔽。

281016「缺少团期上下文」（`ChatErrorCode.java:76`）存在但正常路径触发不到：`groupBatchId` 由请求体 VO 的 `@NotNull` + Controller 的 `@Valid` 先挡成 100001，281016 只在 internal / 单测直调 Service 时才会真抛（见 `ChatManager.java:444-446` 注释），前端按正常表单提交不会遇到它。

#### 业务边界

- 双团队会话
- 前置：团期活跃

---

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

| 场景 | 结果 |
|------|------|
| 分页越界 | 返600013 |
| 日期倒置 | 返600013 |
| 关键词超长 | 返600013 |

---

## 五、数据库行为

本单仅含查询接口，无写操作。

---

## 六、边界行为

- 未登录 → 401
- 团期不存在 → 600012

---

## 六.5、枚举

### dispatchProgress

| 值 | 中文 |
|----|------|
| NOT_STARTED | 未启动 |
| PARTIAL | 部分完成 |
| FULL | 已完成 |

---

## 六.6、修改前后对比

N/A

---

## 六.7、影响评估

- **是否破坏向后兼容**: 否
- **前端是否必须同步上线**: 否

---

## 六.8、菜单与权限

- **菜单挂载**（`V20260910_006__add_group_batch_fleet_dispatch_menu.sql`）：在既有「车务管理」（`path=/fleet`）节点下新增二级目录「团期配车」（`menu_type=D`，`path=/fleet/group-dispatch`，`icon=Van`，`sort_order=46`），其下唯一三级菜单同名「团期配车」（`menu_type=M`，`path=component=/fleet/group-dispatch`）；菜单可见性（`sys_role_menu`）授予 `SUPER_ADMIN` / `ADMIN` / `VEHICLE_MANAGER` 三个角色。
- **权限标识**（`V20260910_007__add_group_batch_fleet_permission.sql`）：新增权限码 `fleet:group-dispatch:view`（`resource_type=FLEET_GROUP_DISPATCH`，`action=VIEW`），覆盖本单三个只读端点（待配车团期清单/团期配车总览/资源排班）；三级菜单的 `permission_code` 字段（V20260910_006 第66行）写的也是这同一个码。`admin_role_permission` 授权 `VEHICLE_MANAGER` / `ADMIN` / `SUPER_ADMIN`；团期管理员侧不在此授权范围内（他们看配车进度走团期管理页，不进车务页面）。

---

## 七、不影响范围

- 房务、C端、既有会话

---

## 八、测试环境已验证

**环境与提交**：测试服部署 `hl-fleet-service` / `hl-order-service-v3` @ `861ebff0c`，`hl-user-service` @ `30761683e`（与前两者不同提交号是部署窗口内 dev-v3 尖端继续前移所致；已核实中间那 5 个提交对 `hl-user-service`/`hl-fleet-service` 零文件改动，且改动集中在 `hl-common-feign`，与本单改的 `hl-common-core`/`dto/fleet` 零重叠，契约不受影响）。

**网关实测（6 个端点，每条两轮不同角色）**：

| 端点 | 角色 | 结果 |
|---|---|---|
| `GET /admin/fleet/group-dispatch/pending-batches`<br>`GET /admin/fleet/group-dispatch/batches/{id}/overview`<br>`GET /admin/fleet/group-dispatch/resource-schedule` | `VEHICLE_MANAGER` | **200**，返回真实数据 |
| 同上三个 | `ROOM_MANAGER` / `ADMIN` | **403**「无权限访问车务管理，请切换到车务角色」 |
| `POST /v3/internal/group-batch/vehicle-dispatch-candidates`<br>`GET /v3/internal/group-batch/{id}/vehicle-coverage` | 任意（含带 token） | **403**「接口不可访问」——网关 `JwtAuthFilter` 按 `/v3/internal/**` 路径前缀在鉴权之前就拦掉，与 token/角色无关，外部不可达（符合预期，这两个是服务间接口） |
| `POST /admin/message/chat/open-group-fleet` | `VEHICLE_MANAGER` | **200**，两次调用 `isNew` 分别为 `true`/`false`（首开建会话、二次找回同一条，幂等生效） |

🔴 **`ADMIN` 角色拿到的是 403，不是 200**——fleet 三个只读端点的访问控制是 #5626 的粗粒度角色门禁（仅放行 `VEHICLE_MANAGER` / `SUPER_ADMIN`），**不看权限码** `fleet:group-dispatch:view`（六.8 节新增的那个）。前端如果按「持有该权限码就能调」设计菜单可见性之外的接口调用逻辑，`ADMIN` 角色会在实调时翻车——必须同时满足角色门禁。

```
GET /admin/fleet/group-dispatch/pending-batches → 200 ✓（VEHICLE_MANAGER）
```

---

## 九、相关历史 PR

| PR | Issue | 说明 |
|----|-------|------|
| #7506 | #7440 | 本单 |

---

## 十、相关文档

- Issue: [#7440](https://git.1814.love:8443/wx/HL/issues/7440)
- PR: [#7506](https://git.1814.love:8443/wx/HL/pulls/7506)
- Commit: [861ebff0c](https://git.1814.love:8443/wx/HL/commit/861ebff0c)

## 关联 / 联系人

### 链接

- **Issue**: [#7440](https://git.1814.love:8443/wx/HL/issues/7440)
- **PR**: [#7506](https://git.1814.love:8443/wx/HL/pulls/7506)
- **Merge commit**: [861ebff0c](https://git.1814.love:8443/wx/HL/commit/861ebff0c)

### 联系人

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