wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

docs: 2026-09-16 交接两笔接口变更（#7767 + #7443 PR-A）
changelog-filename-gate / validate (push) Failing after 1s
详情

浏览代码 
- #7767：团车户与免车团户可终止行程，新增错误码 584132，修改 584100 适用范围
- #7443 PR-A：派车行补团期 ID 列，看板按团期 ID 精确筛选

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
这个提交包含在：
API Changelog Bot
2026-09-16 12:41:10 +08:00
共同撰写人 Claude Haiku 4.5
父节点 6c78b879a4
当前提交 151bfff016
共修改 2 个文件，包含 664 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-09/16_7443_派车行补团期ID-看板按团筛选-修改接口-管理后台.md
+311
查看文件
@@ -0,0 +1,311 @@
---
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
changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md
+353
查看文件
@@ -0,0 +1,353 @@
---
schema: "hl-changelog/v2"
ticket: "7767"
title: "团车户与免车团户可终止行程，终止车费投影认可团车与整团免车"
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: "仅后端交付。新增错误码 584132 与修改的 584100 文案在源码与 API-SPEC 已核对；测试服验证见工单 #7767 验收评论。前端需补错误码 584132 的提示文案映射，误将两码混用则会给出不恰当的稍后重试建议。"
updated_at: "2026-09-16"
base: "dev-v3"
---
# order-v3: 团车户与免车团户可终止行程
> **存放目录**: changelogs-v2/{YYYY-MM}/（管理后台，二期 order-v3）
>
> **服务**: hl-order-service-v3 (端口 8083)
> **PR**: #7789
> **Issue**: #7767
> **日期**: 2026-09-16
> **影响范围**: 终止行程接口新增错误码 584132；错误码 584100 文案修改，收窄适用场景
---
## 关键变化
1. **原本终止行程对团级配车户（GROUP_VEHICLE）和整团免车户恒返 584100**——该两类户现已可成功终止。
2. **新增错误码 584132**：用于"用车需求未完成"场景，与 584100"车费暂时不可用"语义分开。前端**必须区别对待**两个错误码：
- `584132` → "等车务配车完成后再试"（需催车务处理）
- `584100` → "暂时不可用，请稍后重试"（快照异常，应自己好转）
---
## 一、背景
#7441 新增了团级正式用车需求声明的端点，其后 #7445 给定制师逐户所报的用车需求引入"就绪状态"检查（DAILY_V3 契约版本）。此前团车户与免车户因为 assignment_contract_version 判据不满足而永久卡死在 584100 错误，无法终止。本次放行这两类户，同时将终止失败分成两个语义明确的错误码。
---
## 二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 终止行程·退款预览 | POST | `/v3/admin/order/{orderId}/terminate-refund/preview` | 修改 | 新增错误码 584132；修改 584100 文案与适用范围 |
| 2 | 终止行程 | POST | `/v3/admin/order/{orderId}/terminate` | 修改 | 新增错误码 584132；修改 584100 文案与适用范围 |
---
## 三、接口详情
### 1. 终止行程·退款预览 `POST /v3/admin/order/{orderId}/terminate-refund/preview`
**VO**: `(路径参数 → OrderTerminateRefundPreviewRespVO)`
#### 使用场景
出行中点击"终止行程"时的前置预览，展示本单若干今日已用、剩余天数、应退金额等。预览过程不做任何写入，失败也不影响后续正式终止接口调用。
#### 入参字段表
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| orderId | Path | Long | 是 | - | 订单 ID |
#### 出参字段表
| 字段 | 类型 | 说明 |
|------|------|------|
| orderId | Long | 订单 ID |
| orderNo | String | 订单号 |
| usedDays | Integer | 已用天数（截至今日） |
| remainingDays | Integer | 剩余天数（今日之后） |
| refundAmount | BigDecimal | 应退总金额（含车费、房费等） |
| vehicleFeeRefund | BigDecimal | 车费应退（拆分显示，供前端按业务决策） |
| houseFeeRefund | BigDecimal | 房费应退 |
#### 请求示例
```json
GET /v3/admin/order/1934567890123456789/terminate-refund/preview
```
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"data": {
"orderId": 1934567890123456789,
"orderNo": "26-0503",
"usedDays": 2,
"remainingDays": 4,
"refundAmount": "8000.00",
"vehicleFeeRefund": "3200.00",
"houseFeeRefund": "4800.00"
},
"success": true
}
```
#### 空数据 / 降级响应
本接口无空数据场景（订单存在即可预览）。
#### 错误响应
```json
{
"code": 584100,
"message": "车务车辆总车费暂时不可用，请稍后重试",
"success": false,
"data": null
}
```
```json
{
"code": 584132,
"message": "用车需求未完成，暂不能终止行程，请等车务配车完成后再试",
"success": false,
"data": null
}
```
#### 错误响应
```json
{
"code": 581001,
"message": "订单不存在",
"success": false,
"data": null
}
```
```json
{
"code": 583301,
"message": "订单状态不允许此操作",
"success": false,
"data": null
}
```
#### 业务边界
- **鉴权**: 需 admin 权限，团期户与散客户均支持
- **状态机**: 仅 TRAVELLING/TRANSFER 状态订单可预览，其他状态拒绝（401）
- **幂等**: 无写入，重复调用返回一致结果
- **零副作用**: 预览失败不作用任何表与缓存，安全重试
- **旧数据兼容**: refundAmount 等字段在快照 JSON 损毁时可能为 null，前端需判空
---
### 2. 终止行程 `POST /v3/admin/order/{orderId}/terminate`
**VO**: `OrderTerminateTripReqVO → OrderTerminateTripRespVO`
#### 使用场景
出行中因特殊原因（天气、医疗等）提前终止订单，订单进入 COMPLETED 状态。结算与房车资源释放在终止之后由结算流程异步处理。
#### 入参字段表
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| orderId | Path | Long | 是 | - | 订单 ID |
| cancelReason | Body | String | 是 | ≤500 字符 | 终止原因（运营内部备注） |
| endDayNumber | Body | Integer | 是 | 1 ≤ dayNumber ≤ 行程天数 | 终止日在行程中的序号（Day 1、Day 2 等） |
| vehicles | Body | List | 否 | - | 旧客户端兼容字段，新客户端可不传 |
#### 出参字段表
| 字段 | 类型 | 说明 |
|------|------|------|
| orderId | Long | 订单 ID |
| orderNo | String | 订单号 |
| status | String | 订单状态（转移为 COMPLETED） |
| terminateRefundRecord | Object | 退款记录快照 |
| terminateRefundRecord.refundAmount | BigDecimal | 实退总金额 |
| terminateRefundRecord.createdAt | LocalDateTime | 记录时刻 |
#### 请求示例
```json
{
"cancelReason": "客户身体不适，需提前返程",
"endDayNumber": 3
}
```
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"data": {
"orderId": 1934567890123456789,
"orderNo": "26-0503",
"status": "COMPLETED",
"terminateRefundRecord": {
"refundAmount": "8000.00",
"createdAt": "2026-09-16T14:30:00"
}
},
"success": true
}
```
#### 空数据 / 降级响应
本接口无空数据场景。
#### 错误响应
```json
{
"code": 584132,
"message": "用车需求未完成，暂不能终止行程，请等车务配车完成后再试",
"success": false,
"data": null
}
```
```json
{
"code": 584100,
"message": "车务车辆总车费暂时不可用，请稍后重试",
"success": false,
"data": null
}
```
#### 业务边界
- **鉴权**: 需 admin 权限
- **状态机**: 仅 TRAVELLING 状态可终止
- **幂等**: 同一订单同一 endDayNumber 重复终止返 581049（已终止）
- **团车户与免车户放行**: 现已支持，按 DAILY_V3 规则正常处理
---
## 四、契约约束与正确调用方式
| 场景 | 做法 |
|------|------|
| 出行中 Day 3 终止 | 先预览、再提交，endDayNumber=3 |
| 重复终止（幂等） | 同一订单同 endDayNumber 重复 POST，返 200 或 581049 |
| 错误码 584132 | "等车务配车完成"，需催车务处理 |
| 错误码 584100 | "暂时不可用"，稍后重试 |
---
## 五、数据库行为
| 操作 | order_main.order_status | order_terminate_refund | 房车资源释放 |
|------|---------------------------|---------------------------|------------|
| 终止成功 | TRAVELLING → COMPLETED | INSERT 一行 | 异步触发 |
| 终止失败 | 无变更 | 无新增 | 无 |
---
## 六、边界行为
- **未登录** → 401
- **无权限** → 403
- **订单不存在** → 404
- **状态非 TRAVELLING** → 583301
- **结束日越界** → 581047
- **车费快照异常** → 584100
- **用车需求未配车** → 584132
---
## 六.5、枚举
### 订单状态 (status 字段)
**所属字段**: OrderTerminateTripRespVO.status | **类型**: String
| 值 | 中文 | 说明 |
|----|------|------|
| TRAVELLING | 出行中 | 使用终止接口前的状态 |
| COMPLETED | 已完成 | 终止成功后的状态 |
---
## 六.6、修改前后对比
### 错误码对比
| 错误码 | 改前 | 改后 |
|--------|------|------|
| 584100 | 对所有车费投影缺失的户统一返回 | 收窄为仅覆盖 DAILY_V3 契约版本但快照未就绪的户 |
| 584132 | 不存在 | 新增，覆盖非 DAILY_V3 且未配车的户 |
---
## 六.7、影响评估
- **是否破坏向后兼容**: 是（团车户和免车户原本失败，现已成功）
- **前端是否必须同步上线**: 是（需处理新错误码 584132）
- **前端 workaround 清理点**: 删除硬编码的"团车户无法终止"逻辑
---
## 七、不影响范围
- **仅影响**: 管理后台出行中订单的终止功能
- **零影响**:
- C 端应用
- 其他状态订单的操作
- 房费结算
- 用车需求声明等其他模块
---
## 八、测试环境已验证
```
POST /v3/admin/order/{id}/terminate-refund/preview → 200 ✓
POST /v3/admin/order/{id}/terminate (GROUP_VEHICLE) → 200 ✓
POST /v3/admin/order/{id}/terminate (免车户) → 200 ✓
```
---
## 十、相关文档
- Issue: [#7767](https://git.1814.love:8443/wx/HL/issues/7767)
- PR: [#7789](https://git.1814.love:8443/wx/HL/pulls/7789)
- Merge commit: [42dea4c36](https://git.1814.love:8443/wx/HL/commit/42dea4c36)
## 关联 / 联系人
### 链接
- **Issue**: [#7767](https://git.1814.love:8443/wx/HL/issues/7767)
- **PR**: [#7789](https://git.1814.love:8443/wx/HL/pulls/7789)
- **Merge commit**: [42dea4c36](https://git.1814.love:8443/wx/HL/commit/42dea4c36)
### 联系人
- **后端负责人**: @wx