From 68627376f17a6b3774ee723090246846c803d118 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 5 Jul 2026 20:52:22 +0800 Subject: [PATCH] docs(fleet): expand api handoff examples --- ...务菜单全接口验收与前端契约收口-管理后台.md | 1564 ++++++++++++++++- 1 file changed, 1559 insertions(+), 5 deletions(-) diff --git a/changelogs-v2/2026-07/25_4756_车务菜单全接口验收与前端契约收口-管理后台.md b/changelogs-v2/2026-07/25_4756_车务菜单全接口验收与前端契约收口-管理后台.md index 96a8f45..a4fac82 100644 --- a/changelogs-v2/2026-07/25_4756_车务菜单全接口验收与前端契约收口-管理后台.md +++ b/changelogs-v2/2026-07/25_4756_车务菜单全接口验收与前端契约收口-管理后台.md @@ -1,7 +1,7 @@ # 【前端对接·管理后台】车务菜单全接口验收与契约收口 > **Issue**: [wx/HL#4756](https://git.1814.love:8443/wx/HL/issues/4756) -> **PR**: [wx/HL#4757](https://git.1814.love:8443/wx/HL/pulls/4757), [wx/HL#4758](https://git.1814.love:8443/wx/HL/pulls/4758) +> **PR**: [wx/HL#4757](https://git.1814.love:8443/wx/HL/pulls/4757), [wx/HL#4758](https://git.1814.love:8443/wx/HL/pulls/4758), [wx/HL#4759](https://git.1814.love:8443/wx/HL/pulls/4759) > **服务**: hl-fleet-service + hl-order-service-v3 > **日期**: 2026-07-05 > **影响范围**: 管理后台车务管理全菜单 @@ -53,11 +53,1565 @@ --- -## 4. 验证证据 +## 4. 统一调用约定 -- 菜单级真实 API：`23/23` 通过，订单 `HL20260705203149299`，覆盖 76 个后台端点。 -- 全链路真实 API：`31/31` 通过，订单 `HL20260705203226195`。 -- 多订单并发：`10/10` 通过，真实创建 3 个订单，仅 1 单派单成功，其余按 `605001` 冲突返回。 +### 4.1 Header + +管理后台车务接口统一走测试域名： + +```http +Authorization: Bearer +Content-Type: application/json +``` + +角色边界： + +- `admin/VEHICLE_MANAGER`：允许访问 `/admin/fleet/**`。 +- `wx/CUSTOMIZER`：访问 `/admin/fleet/**` 返回 `403`，前端应提示切换车务角色。 +- `/app/h5/**`：公开 H5 入口，不走车务角色 guard，但需要 `token` 参数。 + +### 4.2 成功响应包 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": {} +} +``` + +### 4.3 失败响应包 + +```json +{ + "code": 605020, + "message": "当前派单状态不允许此操作", + "success": false, + "data": null +} +``` + +> 说明：下面示例来自本次测试服真实 API 回归结构，手机号、token、部分 ID 做了脱敏或占位。前端处理长整型 ID 时建议按字符串保存，避免 JS 精度问题。 + +--- + +## 5. 订单前置：新建订单、出行人、大交通、用车需求 + +车务矩阵/看板的数据不是 mock，也不是手工造 fleet 数据；前置链路必须从 wx 定制师订单开始。 + +### 5.1 新建订单 + +```http +POST /v3/admin/order +``` + +请求： + +```json +{ + "productId": 2056938821550747650, + "tierSeq": 1, + "departureDate": "2026-07-18", + "customerName": "API测试车务", + "customerPhone": "199****0001", + "adultCount": 2, + "childCount": 0, + "youngChildCount": 0, + "babyCount": 0, + "roomCount": 1, + "customerRemark": "fleet full api regression with transport", + "tags": ["API_TEST_FLEET_FULL"] +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "orderId": "2073749536638992386", + "orderNo": "HL20260705204312543" + } +} +``` + +### 5.2 补全出行人 + +```http +PUT /v3/admin/order/{orderId}/traveler-info +``` + +请求： + +```json +{ + "travelers": [ + { + "name": "接口测试甲", + "gender": "1", + "birthday": "1988-01-02", + "idType": "ID_CARD", + "idNo": "11010119880102****", + "nationality": "中国", + "race": "汉族", + "phone": "199****0002", + "emergencyContact": "接口测试联络", + "emergencyPhone": "199****0003", + "roomGroupNo": 1 + } + ], + "emergencyContactName": "接口测试联络", + "emergencyContactPhone": "199****0004", + "customerRemark": "fleet full regression traveler completed with transport" +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "createdCount": 2, + "pendingCount": 0, + "allCompleted": true + } +} +``` + +### 5.3 写入到达/返程大交通 + +```http +POST /v3/admin/order/{orderId}/transport-plan/batch +``` + +请求： + +```json +{ + "plans": [ + { + "direction": "ARRIVAL", + "transportType": "FLIGHT", + "transportNo": "CAFULL", + "carrier": "中国国际航空", + "departStation": "北京首都T3", + "arriveStation": "海拉尔东山机场", + "departTime": "2026-07-18T08:00:00", + "arriveTime": "2026-07-18T10:30:00", + "travelerIds": ["2073749539415625730", "2073749539419820033"], + "pickupRequired": true, + "pickupRemark": "T3 出口举牌接机", + "remark": "fleet full arrival transport" + }, + { + "direction": "DEPARTURE", + "transportType": "TRAIN", + "transportNo": "KFULL", + "carrier": "中国铁路", + "departStation": "海拉尔站", + "arriveStation": "北京站", + "departTime": "2026-07-20T18:00:00", + "arriveTime": "2026-07-21T08:30:00", + "travelerIds": ["2073749539415625730", "2073749539419820033"], + "pickupRequired": true, + "pickupRemark": "送站到候车厅", + "remark": "fleet full departure transport" + } + ] +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "deletedCount": 0, + "createdCount": 2, + "plans": [ + { + "id": "2073749541168844802", + "orderId": "2073749536638992386", + "direction": "ARRIVAL", + "transportType": "FLIGHT", + "transportNo": "CAFULL", + "travelers": [ + { "id": "2073749539415625730", "name": "接口测试甲", "travelerType": "ADULT" } + ] + } + ] + } +} +``` + +### 5.4 提交用车需求 + +```http +PUT /v3/admin/order/{orderId}/vehicle-requirement +``` + +请求： + +```json +{ + "fleet": [ + { "vehicleType": "SUV", "seats": 5, "count": 1 } + ], + "remark": "fleet full api regression with transport", + "specialTags": ["API_TEST_FLEET_FULL", "HAS_TRANSPORT"] +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "requirementId": "2073749544025161730", + "status": "PENDING", + "version": 1, + "vehicleTypeSummary": "SUV×1" + } +} +``` + +--- + +## 6. 派单看板与矩阵派单 + +### 6.1 看板 summary + +```http +GET /admin/fleet/board/summary +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "pendingCount": 14, + "pendingUrgentCount": 0, + "todayDepartCount": 3, + "idleVehicleCount": 8, + "idleDriverCount": 7, + "holdingTimeoutCount": 0, + "statusCounts": { + "unassigned": 14, + "holding": 0, + "assigned": 2, + "completed": 1, + "canceled": 0 + } + } +} +``` + +前端注意：使用 `pendingUrgentCount`、`holdingTimeoutCount`，不要读旧字段。 + +### 6.2 看板订单列表 + +```http +GET /admin/fleet/board/orders?page=1&pageSize=20&keyword=HL20260705204312543&statuses=assigned&statuses=completed&variant=list +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "records": [ + { + "id": "2073749536638992386", + "orderNo": "HL20260705204312543", + "customerName": "API测试车务", + "headcount": 2, + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "assignmentStatus": "assigned", + "vehicleTypeSummary": "SUV×1", + "transport": { + "batches": [ + { "transportNo": "CAFULL", "station": "海拉尔东山机场", "travelerNames": ["接口测试甲"] }, + { "transportNo": "KFULL", "station": "海拉尔站", "travelerNames": ["接口测试甲"] } + ] + } + } + ], + "total": 1, + "page": 1, + "pageSize": 20 + } +} +``` + +### 6.3 看板详情与时间线 + +```http +GET /admin/fleet/board/orders/{orderId} +GET /admin/fleet/board/orders/{orderId}/timeline +``` + +详情响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2073749536638992386", + "orderNo": "HL20260705204312543", + "customerName": "API测试车务", + "headcount": 2, + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "transport": { + "batches": [ + { "transportNo": "CAFULL", "time": "2026-07-18T10:30:00", "station": "海拉尔东山机场" }, + { "transportNo": "KFULL", "time": "2026-07-20T18:00:00", "station": "海拉尔站" } + ] + }, + "progressSteps": [], + "operationLog": [], + "currentAssignment": { + "id": "2073749544096460802", + "assignmentStatus": "assigned", + "vehicleId": "2073749553340706818", + "driverId": "2073749552489267202" + }, + "relatedDetailReady": true + } +} +``` + +时间线响应： + +```json +{ + "code": 200, + "success": true, + "data": [ + { "eventType": "requirement_created", "eventTime": "2026-07-05T20:43:12", "content": "用车需求已提交" }, + { "eventType": "assigned", "eventTime": "2026-07-05T20:43:18", "content": "已确认派车" } + ] +} +``` + +### 6.4 矩阵 grid、未派、当天订单 + +```http +GET /admin/fleet/matrix/grid?year=2026&month=7&typeKeys=suv&fleets=own&season=active +GET /admin/fleet/matrix/unassigned-orders?year=2026&month=7&typeKeys=suv +GET /admin/fleet/matrix/day-orders?date=2026-07-18 +``` + +grid 响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "year": 2026, + "month": 7, + "daysInMonth": 31, + "weekendDays": [4, 5, 11, 12, 18, 19, 25, 26], + "vehicles": [ + { + "vehicleId": "2073749553340706818", + "plate": "蒙A-69665", + "fleet": "own", + "driverName": "API师傅69665", + "days": [ + { "date": "2026-07-18", "status": "assigned", "orderNo": "HL20260705204312543" } + ] + } + ], + "statusCounts": { + "totalAssignments": 84, + "unassignedAssignments": 82, + "assignedAssignments": 2, + "totalOrders": 83, + "unassignedOrders": 81, + "partialOrders": 0, + "assignedOrders": 2 + }, + "unassignedWindowCount": 14 + } +} +``` + +未派/当天订单记录至少关注： + +```json +{ + "orderNo": "HL20260705204312543", + "orderNumericId": "2073749536638992386", + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "headcount": 2, + "vehicleTypeSummary": "SUV×1" +} +``` + +--- + +## 7. 派单操作接口 + +### 7.1 预校验 + +```http +POST /admin/fleet/assignments/precheck +``` + +请求： + +```json +{ + "vehicleId": "2073749553340706818", + "driverId": "2073749552489267202", + "orderId": "2073749536638992386", + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "headcount": 2, + "pickupAt": "hailar", + "dropoffAt": "hailar" +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "conflict": false, + "conflicts": [], + "warnings": [] + } +} +``` + +### 7.2 创建派单 + +```http +POST /admin/fleet/assignments +``` + +请求： + +```json +{ + "vehicleId": "2073749553340706818", + "driverId": "2073749552489267202", + "orderId": "2073749536638992386", + "orderNo": "HL20260705204312543", + "requirementId": "2073749544025161730", + "fleetItemIndex": 0, + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "headcount": 2, + "pickupAt": "hailar", + "dropoffAt": "hailar", + "holdMode": 1, + "fromEntry": "from-matrix", + "strictSeats": true, + "skipCityJunctionException": false, + "requestId": "front-assign-20260705-001" +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2073749544096460802", + "assignmentStatus": "holding", + "holdSentAt": "2026-07-05T20:43:18", + "sideEffects": { + "vehicleStatusUpdated": "busy", + "driverStatusUpdated": "busy", + "reconPrepRowsCreated": 0, + "reconPrepMarkedCanceled": null + } + } +} +``` + +`holdMode`： + +- `1`：先占位/待司机确认，后续调 confirm。 +- `0`：直接派定，返回 `assignmentStatus=assigned` 和 `confirmedAt`。 + +### 7.3 确认、取消、撤销取消、提前完结 + +```http +POST /admin/fleet/assignments/{assignmentId}/confirm +DELETE /admin/fleet/assignments/{assignmentId} +POST /admin/fleet/assignments/{assignmentId}/restore-cancel +POST /admin/fleet/assignments/{assignmentId}/early-complete +``` + +确认请求： + +```json +{ "driverReplyNote": "接口测试确认接单" } +``` + +确认响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2073749544096460802", + "assignmentStatus": "assigned", + "confirmedAt": "2026-07-05T20:43:20", + "itineraryUrl": "https://web.test.1814.love:9443/fleet/itinerary/", + "sideEffects": { + "vehicleStatusUpdated": "busy", + "driverStatusUpdated": "busy", + "reconPrepRowsCreated": 0 + } + } +} +``` + +取消请求： + +```json +{ + "cancelReason": "客户取消", + "driverNotified": true, + "notifyNote": "已电话通知司机", + "cutoffDate": "2026-07-18" +} +``` + +提前完结请求： + +```json +{ + "completeReason": "行程提前结束", + "cutoffDate": "2026-07-18" +} +``` + +关键错误： + +```json +{ + "code": 605020, + "message": "当前派单状态不允许此操作", + "success": false +} +``` + +```json +{ + "code": 605021, + "message": "当前状态不可提前完结", + "success": false +} +``` + +```json +{ + "code": 605001, + "message": "派单冲突：该车日期段已派", + "success": false +} +``` + +--- + +## 8. H5 行程单响应结构 + +```http +GET /app/h5/itinerary/{token} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "orderId": "HL20260705204312543", + "theme": "呼籁旅行", + "dateRange": "2026-07-18 至 2026-07-20", + "days": 3, + "headcount": 2, + "customer": "API测试车务", + "contactName": "接口测试联络", + "contactPhone": "199****0004", + "route": "海拉尔", + "transport": { + "arrive": { + "transportNo": "CAFULL", + "time": "2026-07-18T10:30:00", + "station": "海拉尔东山机场", + "remark": "fleet full arrival transport" + }, + "depart": { + "transportNo": "KFULL", + "time": "2026-07-20T18:00:00", + "station": "海拉尔站", + "remark": "fleet full departure transport" + }, + "batches": [ + { + "travelerNames": ["接口测试甲", "接口测试乙"], + "transportNo": "CAFULL", + "time": "2026-07-18T10:30:00", + "station": "海拉尔东山机场" + } + ], + "note": "" + }, + "vehicle": { + "plate": "蒙A-69665", + "model": "SUV", + "seats": 5 + }, + "driver": { + "name": "API师傅69665", + "phoneMasked": "199****9999" + }, + "daily": [], + "subsidy": { + "meal": null, + "lodging": null, + "garage": null, + "note": null + }, + "expireAt": "2026-07-27T23:59:59+08:00" + } +} +``` + +前端注意：大交通要从 `transport.arrive`、`transport.depart` 和 `transport.batches` 取，不能只读旧的单字段。 + +--- + +## 9. 司机档案与车辆档案 + +### 9.1 新增/编辑司机 + +```http +POST /admin/fleet/drivers +PUT /admin/fleet/drivers/{driverId} +``` + +请求： + +```json +{ + "name": "API师傅69665", + "phone": "199****9999", + "idCard": "11010119800101****", + "gender": "1", + "nation": "汉族", + "years": 8, + "driverStatus": "idle", + "season": "active", + "preferredTypeKey": "suv", + "preferredModel": "SUV", + "vehicleSource": "company", + "settlementMode": "fleet_leader", + "license": { + "no": "L6966520260705", + "type": "C1", + "expire": "2035-12-31", + "issuedBy": "测试交管" + }, + "insurance": { "type": "none" }, + "tags": ["API_TEST_FLEET_FULL"], + "attachments": [] +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2073749552489267202", + "name": "API师傅69665", + "phone": "199****9999", + "driverStatus": "idle", + "season": "active", + "settlementMode": "fleet_leader", + "license": { "no": "L6966520260705", "type": "C1", "expire": "2035-12-31" }, + "insurance": { "type": "none" }, + "tags": ["API_TEST_FLEET_FULL"] + } +} +``` + +`settlementMode` 只允许： + +| 值 | 展示 | +|----|------| +| `direct` | 直接结算 | +| `fleet_leader` | 车队长结算 | + +非法值响应： + +```json +{ + "code": 100001, + "message": "参数非法: 司机结算方式非法，取值来自字典 driver_settlement_mode「直接结算」「车队长结算」，值=bad_mode", + "success": false +} +``` + +### 9.2 司机分页、下拉、常驻车、拉黑/解封 + +```http +GET /admin/fleet/drivers/page?page=1&pageSize=10&keyword=API&season=active&driverStatus=idle&tagName=API_TEST_MENU_DRIVER +GET /admin/fleet/drivers/options?keyword=199&limit=50 +PUT /admin/fleet/drivers/{driverId}/resident-vehicle +POST /admin/fleet/drivers/{driverId}/blacklist +POST /admin/fleet/drivers/{driverId}/unban +``` + +常驻车请求： + +```json +{ "vehicleId": "2073749553340706818" } +``` + +拉黑请求： + +```json +{ "blacklistReason": "菜单验收拉黑" } +``` + +重复快速提交可能返回： + +```json +{ + "code": 100502, + "message": "拉黑处理中，请勿重复提交", + "success": false +} +``` + +### 9.3 新增/编辑车辆 + +```http +POST /admin/fleet/vehicles +PUT /admin/fleet/vehicles/{vehicleId} +``` + +请求： + +```json +{ + "plate": "蒙A-69665", + "vehicleModelId": "2064991856994758657", + "fleet": "own", + "ownerType": "company", + "primaryDriverId": "2073749552489267202", + "vehicleStatus": "idle", + "vin": "LSVAPI475169665", + "regDate": "2024-01-01", + "inspectDue": "2030-12-31", + "insureDue": "2030-12-31", + "regCertUsage": "营运租赁", + "regCertNo": "REG69665", + "regCertOwner": "呼籁测试", + "attachments": [] +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2073749553340706818", + "plate": "蒙A-69665", + "vehicleModelId": "2064991856994758657", + "typeKey": "suv", + "fleet": "own", + "ownerType": "company", + "vehicleStatus": "idle", + "primaryDriverName": "API师傅69665", + "primaryDriverLicenseType": "C1" + } +} +``` + +前端限制： + +- 新增/编辑不能人工提交 `vehicleStatus=busy`。 +- 个人自带车不能手动停用/启用。 +- 常驻司机冲突：车辆侧返回 `605022`，司机侧返回 `605023`。 + +busy 错误响应： + +```json +{ + "code": 600112, + "message": "车辆占用态只能在空闲与维保间人工切换，在用(busy)由系统派单写入", + "success": false +} +``` + +### 9.4 导入/模板下载 + +```http +GET /admin/fleet/drivers/import/template +POST /admin/fleet/drivers/import +GET /admin/fleet/vehicles/import/template +POST /admin/fleet/vehicles/import +``` + +导入为 `multipart/form-data`： + +```http +file=@drivers.csv; type=text/csv +``` + +司机导入响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "totalRows": 1, + "insertedCount": 1, + "renewedCount": 0, + "warnedCount": 0, + "errorCount": 0 + } +} +``` + +错误后缀： + +```json +{ + "code": 100001, + "message": "参数非法: 不支持的文件类型，仅支持 .xlsx / .xls / .csv", + "success": false +} +``` + +--- + +## 10. 车型管理库 + +### 10.1 车型树与分页 + +```http +GET /admin/fleet/vehicle-types +GET /admin/fleet/vehicle-types/list +GET /admin/fleet/vehicle-types/page?page=1&pageSize=5&typeKey=suv +GET /admin/fleet/vehicle-types/models/page?page=1&pageSize=5&modelName=丰田 +``` + +车型树响应： + +```json +{ + "code": 200, + "success": true, + "data": [ + { + "id": "2064991856000000001", + "typeKey": "suv", + "typeName": "SUV系列", + "sortOrder": 1, + "models": [ + { + "id": "2064991856994758657", + "modelName": "丰田普拉多", + "seats": 5, + "basePrice": "800.00", + "alias": "普拉多" + } + ] + } + ] +} +``` + +前端注意：大类和车型型号主键都读 `id`，不要读旧 `typeId`。 + +### 10.2 大类/型号 CRUD + +```http +POST /admin/fleet/vehicle-types +PUT /admin/fleet/vehicle-types/{typeId} +POST /admin/fleet/vehicle-types/{typeId}/models +PUT /admin/fleet/vehicle-types/models/{modelId} +DELETE /admin/fleet/vehicle-types/models/{modelId} +DELETE /admin/fleet/vehicle-types/{typeId} +``` + +新增大类请求： + +```json +{ + "typeKey": "api4756", + "typeName": "API测试大类", + "sortOrder": 999, + "icon": "Car", + "description": "issue4756 api regression" +} +``` + +新增型号请求： + +```json +{ + "modelName": "API测试车型", + "seats": 6, + "basePrice": 123.45, + "alias": "API4756", + "sortOrder": 1 +} +``` + +删除有子型号的大类： + +```json +{ + "code": 600104, + "message": "大类下存在型号，不能删除", + "success": false +} +``` + +--- + +## 11. 价格日历 + +### 11.1 查询总览和车型月历 + +```http +GET /admin/fleet/pricing-calendar/overview?startDate=2026-07-18&endDate=2026-07-20 +GET /admin/fleet/pricing-calendar/{vehicleModelId}?year=2026&month=7 +``` + +总览响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "globalMinPrice": "777.00", + "globalMaxPrice": "888.00", + "holidays": [], + "types": [ + { + "typeKey": "suv", + "typeName": "SUV系列", + "models": [ + { "vehicleModelId": "2064991856994758657", "modelName": "丰田普拉多", "minPrice": "777.00", "maxPrice": "888.00" } + ] + } + ] + } +} +``` + +月历响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "year": 2026, + "month": 7, + "vehicleModelId": "2064991856994758657", + "modelName": "丰田普拉多", + "prices": [ + { + "date": "2026-07-18", + "dayPrice": "777.00", + "status": "AVAILABLE", + "remark": "菜单验收多车型" + } + ] + } +} +``` + +### 11.2 单车型设价、状态、批量设价、删除 + +```http +PUT /admin/fleet/pricing-calendar/{vehicleModelId} +PUT /admin/fleet/pricing-calendar/{vehicleModelId}/status +PUT /admin/fleet/pricing-calendar/batch-set +DELETE /admin/fleet/pricing-calendar/{vehicleModelId}?startDate=2026-07-18&endDate=2026-07-20 +``` + +单车型 ABS 请求： + +```json +{ + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "adjustMode": "ABS", + "dayPrice": 888, + "status": "AVAILABLE", + "remark": "菜单验收 ABS" +} +``` + +DELTA 周末请求： + +```json +{ + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "adjustMode": "DELTA", + "adjustValue": -10, + "weekendOnly": true, + "status": "AVAILABLE", + "remark": "菜单验收 DELTA" +} +``` + +批量设价请求： + +```json +{ + "vehicleModelIds": ["2064991856994758657"], + "startDate": "2026-07-18", + "endDate": "2026-07-20", + "adjustMode": "ABS", + "dayPrice": 777, + "status": "AVAILABLE", + "excludeDates": ["2026-07-20"], + "remark": "菜单验收多车型" +} +``` + +成功响应： + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +互斥错误： + +```json +{ + "code": 400, + "message": "工作日/周末/节假日筛选不可同时启用", + "success": false +} +``` + +日期范围错误： + +```json +{ + "code": 600501, + "message": "日期范围非法：开始日期不能晚于结束日期", + "success": false +} +``` + +前端注意：`batch-set` 幂等窗口 300 秒，同一批完全相同入参快速重复提交会返回 `100502`。 + +--- + +## 12. 待审核与司机自助录入 H5 + +### 12.1 生成录入 token + +```http +POST /admin/fleet/h5/token +``` + +新招请求： + +```json +{ + "mode": "new", + "name": "自助师傅", + "phone": "199****9992", + "expireDays": 2 +} +``` + +续签请求： + +```json +{ + "mode": "renew", + "targetDriverId": "2073749552489267202", + "expireDays": 2 +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "pendingId": "2073749600606318594", + "token": "", + "url": "https://web.test.1814.love:9443/fleet/driver-onboard?token=", + "shortUrl": "https://t.cn/xxxx", + "expireAt": "2026-07-07T20:43:30", + "qrCodeUrl": "https://..." + } +} +``` + +### 12.2 H5 初始化、上传、提交 + +```http +GET /app/h5/driver-onboard/init?token= +POST /app/h5/driver-onboard/upload +POST /app/h5/driver-onboard/submit/new +POST /app/h5/driver-onboard/submit/renew +``` + +init 响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "mode": "new", + "tokenValid": true, + "tokenState": "editable", + "stepConfig": {}, + "expireAt": "2026-07-07T20:43:30" + } +} +``` + +upload 为 `multipart/form-data`： + +```http +token= +groupKey=fleet-menu-test +file=@photo.png +``` + +upload 响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "url": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/fleet-menu-test/2026/07/05/xxx.png" + } +} +``` + +新招提交请求： + +```json +{ + "token": "", + "name": "自助师傅", + "phone": "199****9992", + "gender": "1", + "nation": "汉族", + "drivingYears": 7, + "idCard": "11010119800101****", + "idCardFrontUrl": "https://.../front.png", + "idCardBackUrl": "https://.../back.png", + "licenseNo": "LH54756", + "licenseClass": "C1", + "licenseExpire": "2035-12-31", + "licenseFrontUrl": "https://.../license-front.png", + "licenseBackUrl": "https://.../license-back.png", + "hasOwnVehicle": true, + "vehicle": { + "plate": "蒙E-4756", + "model": "菜单自带车", + "vin": "LSVH500000004756", + "seats": 5, + "fleet": "own", + "annualInspectDate": "2030-12-31", + "regDate": "2024-01-01", + "insureDue": "2030-12-31", + "regCertUsage": "营运租赁", + "regCertNo": "REGH54756", + "regCertOwner": "自助师傅", + "regFrontUrl": "https://.../reg-front.png", + "regBackUrl": "https://.../reg-back.png", + "exteriorUrls": ["https://.../car-out.png"], + "interiorUrls": ["https://.../car-in.png"], + "insuranceUrls": ["https://.../insurance.png"], + "inspectionUrls": ["https://.../inspection.png"], + "operationLicenseUrls": ["https://.../operation-license.png"] + }, + "preferredCategory": "suv", + "preferredModel": "菜单自带车", + "vehicleSource": "own", + "vehicleNotes": "菜单级验收", + "emergency": { + "name": "自助联络", + "phone": "199****9993", + "relation": "同事" + }, + "portraitUrl": "https://.../portrait.png", + "healthCertUrls": ["https://.../health.png"] +} +``` + +提交响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "pendingId": "2073749372209688577", + "estimatedReviewHours": 24 + } +} +``` + +前端注意：`regCertUsage` 为营运类时，`operationLicenseUrls` 必须上传；否则审核通过会返回 `600406`。 + +### 12.3 待审核列表、详情、通过、驳回 + +```http +GET /admin/fleet/drivers/pending?page=1&pageSize=10&mode=new&reviewStatus=pending +GET /admin/fleet/drivers/pending/{pendingId} +POST /admin/fleet/drivers/pending/{pendingId}/approve +POST /admin/fleet/drivers/pending/{pendingId}/reject +``` + +详情响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2073749372209688577", + "mode": "new", + "reviewStatus": "pending", + "name": "自助师傅", + "phone": "199****9992", + "idCard": "11010119800101****", + "photos": [], + "vehicle": { + "plate": "蒙E-4756", + "hasOwnVehicle": true + } + } +} +``` + +前端注意：详情响应主键字段是 `id`，路径变量仍然是 `pendingId`。 + +通过请求： + +```json +{ + "approveReason": "菜单验收通过", + "ownVehicle": { + "vehicleModelId": "2064991856994758657", + "fleet": "own", + "plate": "蒙E-4756", + "ownerType": "personal", + "vin": "LSVH5APP00004756" + } +} +``` + +通过响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "driverId": "2073749397010608129", + "vehicleId": "2073749397039968257" + } +} +``` + +驳回请求： + +```json +{ "rejectReason": "证件照片不清晰" } +``` + +驳回原因为空： + +```json +{ + "code": 400, + "message": "驳回原因不能为空", + "success": false +} +``` + +重复审核： + +```json +{ + "code": 600400, + "message": "该记录已处理（已通过或已驳回），不可重复审核", + "success": false +} +``` + +--- + +## 13. 车队对账 + +### 13.1 查询车费、保险、对账期 + +```http +GET /admin/fleet/reconciliation/cars?periodStart=2026-07-01&periodEnd=2026-07-31&fleets=own +GET /admin/fleet/reconciliation/insurance?periodStart=2026-07-01&periodEnd=2026-07-31 +GET /admin/fleet/reconciliation/periods?fromMonth=2026-01 +GET /admin/fleet/reconciliation/export/cars?periodStart=2026-07-01&periodEnd=2026-07-31&fleets=own +``` + +车费响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "records": [ + { + "fleet": "own", + "fleetName": "自有车队", + "assignmentCount": 1, + "estimated": "888.00", + "payableEstimated": "888.00", + "actualAmount": "123.45", + "diff": "-764.55" + } + ], + "total": 1 + } +} +``` + +### 13.2 录入实付、关账、重开、补偿 + +```http +PUT /admin/fleet/reconciliation/actual +POST /admin/fleet/reconciliation/close +POST /admin/fleet/reconciliation/reopen +GET /admin/fleet/reconciliation/pending-compensations?page=1&pageSize=5&status=PENDING +POST /admin/fleet/reconciliation/pending-compensations/{id}/resolve +``` + +录入实付请求： + +```json +{ + "periodStart": "2026-07-01", + "periodEnd": "2026-07-31", + "fleet": "own", + "actualAmount": 123.45, + "note": "菜单验收录入" +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2026-07-own", + "estimated": "888.00", + "payableEstimated": "888.00", + "actualAmount": "123.45", + "diff": "-764.55" + } +} +``` + +负数错误： + +```json +{ + "code": 605608, + "message": "实际金额必须大于等于0", + "success": false +} +``` + +非自然月关账： + +```json +{ + "code": 605605, + "message": "仅支持按自然月关账，自定义区间为只读分析", + "success": false +} +``` + +非超管重开： + +```json +{ + "code": 403001, + "message": "无权限，仅超级管理员可重开账", + "success": false +} +``` + +--- + +## 14. 车管模板 + +```http +GET /admin/fleet/message-templates +GET /admin/fleet/message-templates?templateType=hold_notify +POST /admin/fleet/message-templates +POST /admin/fleet/message-templates/{templateId}/render +PUT /admin/fleet/message-templates/{templateId} +DELETE /admin/fleet/message-templates/{templateId} +``` + +新增请求： + +```json +{ + "templateName": "API派车通知", + "templateType": "hold_notify", + "bodyTemplate": "您好 {{driver.name}}，订单 {{order.no}} 已派车，车牌 {{vehicle.plate}}", + "variablesHelp": "{\"driver.name\":\"司机姓名\"}", + "isDefault": false, + "sortOrder": 99 +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2073749573041356801", + "templateName": "API派车通知", + "templateType": "hold_notify", + "bodyTemplate": "您好 {{driver.name}}，订单 {{order.no}} 已派车，车牌 {{vehicle.plate}}", + "isDefault": false, + "sortOrder": 99 + } +} +``` + +渲染请求： + +```json +{ + "orderNo": "HL20260705204312543", + "driverName": "API师傅", + "vehiclePlate": "蒙A-69665" +} +``` + +渲染响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "renderedBody": "您好 API师傅，订单 HL20260705204312543 已派车，车牌 蒙A-69665", + "variablesUsed": ["driver.name", "order.no", "vehicle.plate"] + } +} +``` + +变量缺失： + +```json +{ + "code": 600800, + "message": "模板变量缺失", + "success": false +} +``` + +--- + +## 15. 前端错误码与按钮状态处理 + +| code | 场景 | 前端处理 | +|------|------|----------| +| `403` | 定制师访问车务后台 | 提示切换到车务角色，不重试。 | +| `401` | 未登录访问后台 | 跳登录或刷新登录态。 | +| `100001` / `400` | 参数校验失败 | 展示后端 message，定位表单字段。 | +| `100502` | 幂等保护/快速连点 | 保持按钮 loading/disabled，不当作系统故障。 | +| `600112` | 人工设置车辆 busy | 前端禁止 busy 选项；busy 只由派单占用写入。 | +| `600208` | 非黑名单司机解封 | 展示业务态提示，刷新司机状态。 | +| `600400` | 待审记录重复审核 | 刷新待审列表/详情。 | +| `600406` | 自带车审核缺要件 | 提示补车型、车队、车牌或营运证。 | +| `600501` | 价格日期范围非法 | 检查开始/结束日期。 | +| `605001` | 车辆/司机派单冲突 | 展示冲突，刷新矩阵占用。 | +| `605020` | 非 holding 确认或终态取消 | 刷新派单详情，不重复提交。 | +| `605021` | 终态重复提前完结 | 刷新派单详情。 | +| `605022` | 车辆常驻司机被占用 | 前端提示先解绑原车辆。 | +| `605023` | 司机绑定目标车被占用 | 前端提示更换车辆或解除占用。 | +| `605605` | 非自然月关账 | 禁止自定义区间关账，只读分析即可。 | +| `605608` | 实付金额负数 | 表单限制 `actualAmount >= 0`。 | +| `605609` | 关账补偿不存在 | 刷新补偿列表。 | + +--- + +## 16. 验证证据 + +- 菜单级真实 API：`23/23` 通过，订单 `HL20260705204251138`，覆盖 76 个后台端点。 +- 全链路真实 API：`31/31` 通过，订单 `HL20260705204312543`。 +- 多订单并发：`10/10` 通过，真实创建 3 个订单 `HL20260705204330462`、`HL20260705204332693`、`HL20260705204334918`，仅 1 单派单成功，其余按 `605001` 冲突返回。 - 本地后端验证： - `mvn -pl hl-fleet-service -am "-Dtest=AssignmentServiceTest,FleetAdminRoleGuardInterceptorTest" -DfailIfNoTests=false test` 通过，69 tests。 - `mvn -pl hl-fleet-service spotless:check` 通过。