diff --git a/changelogs-v2/2026-09/16_7443_派车行补团期ID-看板按团筛选-修改接口-管理后台.md b/changelogs-v2/2026-09/16_7443_派车行补团期ID-看板按团筛选-修改接口-管理后台.md new file mode 100644 index 00000000..24ce770a --- /dev/null +++ b/changelogs-v2/2026-09/16_7443_派车行补团期ID-看板按团筛选-修改接口-管理后台.md @@ -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 diff --git a/changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md b/changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md new file mode 100644 index 00000000..aa9d64e3 --- /dev/null +++ b/changelogs-v2/2026-09/16_7767_团车户与免车团户可终止行程-修改接口-管理后台.md @@ -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