312 行
9.2 KiB
Markdown
312 行
9.2 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7443"
|
||
title: "派车行补团期 ID + 看板按团筛选"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "23f6ac2fb76260ce620ed2f6b3cbe8638b21caf0"
|
||
target_release: ""
|
||
verified_at: "2026-09-16"
|
||
status_note: "后端交付。新增 fleet_assignment.group_batch_id 列及 order_main.group_batch_id 在 Feign 契约中的透出；看板订单列表接口新增可选筛选参数 groupBatchId。前端需在看板列表筛选控件增加团期下拉框。；前端 hl-admin 23f6ac2f 已实现：派单看板筛选条加团期远程搜索下拉(候选取 /fleet/group-dispatch/pending-batches),groupBatchId 雪花串仅列表接口透传,spec +5,checkpoint 全绿。"
|
||
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
|