From 42a6367528c5b9e72f770aa0490cd19740fad066 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 6 Jul 2026 12:16:45 +0800 Subject: [PATCH] docs: update fleet API handoff examples --- ...¦åŠ¡èœå•å…¨æŽ¥å£éªŒæ”¶ä¸Žå‰ç«¯å¥‘约收å£-管ç†åŽå°.md | 358 +++++++++++++++++- ...¸æœºé™©è‡ªåŠ¨æŠ•é€€ä¿é—­çŽ¯ä¸Žä¿é™©èœå•å¥‘约-管ç†åŽå°.md | 6 +- 2 files changed, 354 insertions(+), 10 deletions(-) diff --git a/changelogs-v2/2026-07/25_4756_车务èœå•å…¨æŽ¥å£éªŒæ”¶ä¸Žå‰ç«¯å¥‘约收å£-管ç†åŽå°.md b/changelogs-v2/2026-07/25_4756_车务èœå•å…¨æŽ¥å£éªŒæ”¶ä¸Žå‰ç«¯å¥‘约收å£-管ç†åŽå°.md index cf03a5c..b125733 100644 --- a/changelogs-v2/2026-07/25_4756_车务èœå•å…¨æŽ¥å£éªŒæ”¶ä¸Žå‰ç«¯å¥‘约收å£-管ç†åŽå°.md +++ b/changelogs-v2/2026-07/25_4756_车务èœå•å…¨æŽ¥å£éªŒæ”¶ä¸Žå‰ç«¯å¥‘约收å£-管ç†åŽå°.md @@ -2,6 +2,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), [wx/HL#4759](https://git.1814.love:8443/wx/HL/pulls/4759) +> **追加验è¯**: 2026-07-06 ç‹¬ç«‹è´¦å· `fleet_mgr_4760/VEHICLE_MANAGER`ã€`designer_4760/CUSTOMIZER` > **æœåŠ¡**: hl-fleet-service + hl-order-service-v3 > **日期**: 2026-07-05 > **å½±å“范围**: 管ç†åŽå°è½¦åŠ¡ç®¡ç†å…¨èœå• @@ -11,6 +12,7 @@ ## 1. 结论 - 测试æœå·²å®ŒæˆçœŸå®ž API 回归：车务èœå•çº§ `23/23` 通过，覆盖åŽå°ç«¯ç‚¹ `76` 个。 +- 2026-07-06 追加独立账å·å›žå½’：读接å£/åªè¯»åœºæ™¯ `32/32` 通过；写接å£æŽ¢é’ˆ `22/22` 通过，覆盖派å•é¢„检ã€åˆ›å»ºã€ç¡®è®¤ã€å–消ã€å¸æœºé™©ä»»åŠ¡ã€è½¦é˜Ÿå¯¹è´¦å®žä»˜ä¿å­˜/清空ã€æ¨¡æ¿æ¸²æŸ“/错误分支。 - 补充全链路回归 `31/31` 通过，多订å•å¹¶å‘回归 `10/10` 通过。 - 已修å¤æ´¾å•é‡å¤ç¡®è®¤è¿”回 `100000` çš„é—®é¢˜ï¼ŒçŽ°åœ¨è¿”å›žä¸šåŠ¡ç  `605020 当å‰æ´¾å•çŠ¶æ€ä¸å…许此æ“作`。 - `/admin/fleet/**` 已按当å‰ç™»å½•è§’色拦截：车务角色å¯è®¿é—®ï¼Œå®šåˆ¶å¸ˆè§’色会返回 `403`。 @@ -21,9 +23,9 @@ | 场景 | å‰ç«¯å¤„ç† | |------|----------| -| 当å‰è§’色 | 车务èœå•åªèƒ½ç”± `VEHICLE_MANAGER` 或 `SUPER_ADMIN` 访问；`wx/CUSTOMIZER` 访问 `/admin/fleet/**` 返回 `403`，æ示切æ¢è½¦åŠ¡è§’色。 | +| 当å‰è§’色 | 车务èœå•åªèƒ½ç”± `VEHICLE_MANAGER` 或 `SUPER_ADMIN` 访问；`CUSTOMIZER` 访问 `/admin/fleet/**` 返回 `403`，æ示切æ¢è½¦åŠ¡è§’色。测试æœä½¿ç”¨ç‹¬ç«‹è´¦å· `fleet_mgr_4760` / `designer_4760` 验è¯ï¼Œä¸å†ç”¨ `admin` / `wx` 当业务账å·ã€‚ | | è½¦åŠ¡å·¥ä½œå° | `GET /admin/profile/dashboard?period=today` 在 `VEHICLE_MANAGER` 角色下由 user-service ä»£ç† fleet 真实看æ¿æ•°æ®ï¼›ä¸è¦å†è¯»æ—§è®¢å•ç»Ÿè®¡æˆ–本地 mock。 | -| å¸æœºç»“ç®—æ–¹å¼ | å¸æœºæ–°å¢ž/编辑/导入使用字典 `driver_settlement_mode`：`direct`=直接结算，`captain`=车队长结算。 | +| å¸æœºç»“ç®—æ–¹å¼ | å¸æœºæ–°å¢ž/编辑/导入使用字典 `driver_settlement_mode`：`direct`=直接结算，`fleet_leader`=车队长结算。ä¸è¦å†ä¼ æ—§å€¼ `captain`。 | | 待审核详情 ID | `GET /admin/fleet/drivers/pending/{pendingId}` å“应主键字段是 `id`，ä¸æ˜¯ `pendingId`；路径å˜é‡ä»å« `pendingId`。 | | æ´¾å•é‡å¤ç¡®è®¤ | `POST /admin/fleet/assignments/{assignmentId}/confirm` åªå…许 `holding -> assigned`ï¼›éž `holding` 返回 `605020`。 | | å–消é‡å¤æ“作 | 终æ€æ´¾å•å†æ¬¡å–消也返回 `605020`。 | @@ -68,8 +70,8 @@ Content-Type: application/json 角色边界： -- `admin/VEHICLE_MANAGER`：å…许访问 `/admin/fleet/**`。 -- `wx/CUSTOMIZER`：访问 `/admin/fleet/**` 返回 `403`，å‰ç«¯åº”æ示切æ¢è½¦åŠ¡è§’色。 +- `fleet_mgr_4760/VEHICLE_MANAGER`：å…许访问 `/admin/fleet/**`。 +- `designer_4760/CUSTOMIZER`：访问 `/admin/fleet/**` 返回 `403`，å‰ç«¯åº”æ示切æ¢è½¦åŠ¡è§’色。 - `/app/h5/**`：公开 H5 å…¥å£ï¼Œä¸èµ°è½¦åŠ¡è§’色 guardï¼Œä½†éœ€è¦ `token` å‚数。 ### 4.2 æˆåŠŸå“应包 @@ -813,7 +815,7 @@ PUT /admin/fleet/drivers/{driverId} "preferredTypeKey": "suv", "preferredModel": "SUV", "vehicleSource": "company", - "settlementMode": "captain", + "settlementMode": "fleet_leader", "license": { "no": "L6966520260705", "type": "C1", @@ -838,7 +840,7 @@ PUT /admin/fleet/drivers/{driverId} "phone": "199****9999", "driverStatus": "idle", "season": "active", - "settlementMode": "captain", + "settlementMode": "fleet_leader", "license": { "no": "L6966520260705", "type": "C1", "expire": "2035-12-31" }, "insurance": { "type": "none" }, "tags": ["API_TEST_FLEET_FULL"] @@ -851,7 +853,9 @@ PUT /admin/fleet/drivers/{driverId} | 值 | 展示 | |----|------| | `direct` | 直接结算 | -| `captain` | 车队长结算 | +| `fleet_leader` | 车队长结算 | + +> 当å‰å­—典库真实值是 `fleet_leader`。`captain` 是旧è‰ç¨¿å€¼ï¼ŒåŽç«¯ä¸ä¼šæŒ‰è¯¥å€¼å…¥åº“，å‰ç«¯æ–°å¢ž/编辑/导入都ä¸è¦å†ä¼ ã€‚ éžæ³•å€¼å“应： @@ -1850,6 +1854,341 @@ DELETE /admin/fleet/message-templates/{templateId} --- +## 14.5 2026-07-06 独立账å·å†™æŽ¥å£å®žæµ‹æ ·æœ¬ + +本节是测试æœçœŸå®žè¿”回，用于å‰ç«¯é€å­—段对é½ã€‚è´¦å·ï¼š`fleet_mgr_4760/VEHICLE_MANAGER`。测试派å•å·²å–消回滚，产生的å¸æœºé™©å¾…处ç†ä»»åŠ¡å·²æ ‡è®° `IGNORED`，ä¸ä¼šæ±¡æŸ“待处ç†åˆ—表。 + +### 14.5.1 æ´¾å•é¢„检ã€åˆ›å»ºã€ç¡®è®¤ã€å–消 + +预检请求： + +```json +{ + "orderId": "2070756230887890945", + "vehicleId": "2067084363580760065", + "driverId": "2065272150960357378", + "startDate": "2026-07-06", + "endDate": "2026-07-08", + "pickupAt": "hailar", + "dropoffAt": "hailar", + "headcount": 2 +} +``` + +预检å“应： + +```json +{ + "code": 200, + "message": "æˆåŠŸ", + "data": { + "conflict": false, + "conflicts": [], + "warnings": [] + } +} +``` + +创建 holding 请求： + +```json +{ + "orderId": "2070756230887890945", + "vehicleId": "2067084363580760065", + "driverId": "2065272150960357378", + "startDate": "2026-07-06", + "endDate": "2026-07-08", + "headcount": 2, + "holdMode": 1, + "fromEntry": "api-test-4760", + "strictSeats": false, + "skipCityJunctionException": false, + "requestId": "api-test-4760-9ap9s565" +} +``` + +创建å“应： + +```json +{ + "code": 200, + "message": "æˆåŠŸ", + "data": { + "id": "2070756257240694786", + "assignmentStatus": "holding", + "holdSentAt": "2026-07-06T...", + "confirmedAt": null, + "sideEffects": null + } +} +``` + +确认请求： + +```json +{ + "driverReplyNote": "API测试4760：å¸æœºå·²ç¡®è®¤ï¼Œç¡®è®¤åŽç«‹å³å–消回滚" +} +``` + +确认å“应： + +```json +{ + "code": 200, + "message": "æˆåŠŸ", + "data": { + "assignmentStatus": "assigned", + "confirmedAt": "2026-07-06T...", + "itineraryUrl": "https://web.test.1814.love:9443/fleet/itinerary/...", + "sideEffects": { + "vehicleStatusUpdated": "busy", + "driverStatusUpdated": "busy", + "reconPrepRowsCreated": 0, + "reconPrepMarkedCanceled": null + } + } +} +``` + +å–消请求： + +```json +{ + "cancelReason": "API测试4760：确认写接å£åŽç«‹å³å–消释放，ä¸ä½œä¸ºçœŸå®žç”¨è½¦", + "driverNotified": true, + "notifyNote": "API自动化回滚，未实际通知å¸æœº", + "cutoffDate": "2026-07-06" +} +``` + +å–消å“应： + +```json +{ + "code": 200, + "message": "æˆåŠŸ", + "data": { + "assignmentStatus": "canceled", + "sideEffects": { + "vehicleStatusUpdated": "idle", + "driverStatusUpdated": "idle", + "reconPrepRowsCreated": null, + "reconPrepMarkedCanceled": 0 + } + } +} +``` + +å–消åŽè®¢å•è¯¦æƒ…： + +```json +{ + "code": 200, + "data": { + "id": "2070756230887890945", + "currentAssignment": null, + "transport": { + "arrive": null, + "depart": null, + "batches": [] + } + } +} +``` + +å‰ç«¯æ³¨æ„：无大交通时 `transport` ä»è¿”回稳定结构，ä¸è¦å› ä¸º `batches=[]` 就认为接å£ç¼ºå­—段；有大交通的真实样本会返回 `arrive/depart/batches`。 + +### 14.5.2 å¸æœºé™©ä»»åŠ¡åŠ¨ä½œ + +确认派å•åŽï¼Œå¸æœºä¸º `perTrip`ï¼Œè‡ªåŠ¨ç”Ÿæˆ 3 æ¡æŠ•ä¿ä»»åŠ¡ï¼š + +```http +GET /admin/fleet/insurance/tasks?page=1&pageSize=20&assignmentId=2070756257240694786 +``` + +å“应摘è¦ï¼š + +```json +{ + "code": 200, + "data": { + "page": 1, + "pageSize": 20, + "total": 3, + "records": [ + { + "taskType": "PURCHASE", + "taskStatus": "PENDING", + "source": "BAOYOU", + "errorCode": "540005", + "errorMessage": "ä¿é™©è®¡åˆ’ä¸å­˜åœ¨", + "suggestedAction": "请核对å¸æœºæ¡£æ¡ˆã€ä¿é™©è®¡åˆ’å’Œä¿å¸è¿”回信æ¯åŽé‡è¯•ï¼›çº¿ä¸‹å¤„ç†å¿…须填写真实ä¿è´¹ã€ä¿å•å·å’Œå‡­è¯", + "serviceDate": "2026-07-06", + "retryCount": 0 + } + ] + } +} +``` + +线下完æˆç¼ºå‡­è¯è¯·æ±‚： + +```json +{ + "policyNo": "API-TEST-NO-PROOF", + "premiumAmount": "1.00", + "proofUrls": [], + "remark": "API测试缺凭è¯æ ¡éªŒ" +} +``` + +å“应： + +```json +{ + "code": 400, + "message": "线下凭è¯ä¸èƒ½ä¸ºç©º", + "success": false +} +``` + +忽略测试任务请求： + +```json +{ + "remark": "API测试4760回滚派å•äº§ç”Ÿï¼ŒéžçœŸå®žç”¨è½¦ä»»åŠ¡ï¼Œå·²ç¡®è®¤å¿½ç•¥" +} +``` + +å“应： + +```json +{ + "code": 200, + "data": { + "taskStatus": "IGNORED", + "taskStatusLabel": "已忽略" + } +} +``` + +清ç†åŽå¾…处ç†ç¡®è®¤ï¼š + +```http +GET /admin/fleet/insurance/tasks?page=1&pageSize=20&assignmentId=2070756257240694786&pendingOnly=true +``` + +```json +{ + "code": 200, + "data": { + "page": 1, + "pageSize": 20, + "total": 0, + "records": [] + } +} +``` + +### 14.5.3 车队对账实际金é¢ä¿å­˜ä¸Žæ¸…空 + +录入请求： + +```json +{ + "periodStart": "2026-07-01", + "periodEnd": "2026-07-31", + "fleet": "own", + "actualAmount": "1.23", + "note": "API测试4760：写接å£æŽ¢é’ˆï¼ŒéšåŽæ¸…空" +} +``` + +录入å“应： + +```json +{ + "code": 200, + "data": { + "id": "2073981751427821569", + "diff": "-12878.67", + "payableEstimated": "12879.90", + "estimated": "12879.90" + } +} +``` + +清空请求： + +```json +{ + "periodStart": "2026-07-01", + "periodEnd": "2026-07-31", + "fleet": "own", + "actualAmount": null, + "note": "API测试4760：清空写接å£æŽ¢é’ˆ" +} +``` + +清空å“应： + +```json +{ + "code": 200, + "data": { + "id": "2073981751427821569", + "diff": null, + "payableEstimated": "12879.90", + "estimated": "12879.90" + } +} +``` + +负数错误： + +```json +{ + "code": 605608, + "message": "实际金é¢å¿…须大于等于0", + "success": false +} +``` + +### 14.5.4 模æ¿æ¸²æŸ“ + +渲染请求： + +```json +{ + "orderId": "2070756230887890945", + "vehicleId": "2067084363580760065", + "driverId": "2065272150960357378" +} +``` + +å“应字段： + +```json +{ + "code": 200, + "data": { + "renderedBody": "渲染åŽçš„正文", + "variablesUsed": [ + "order.no", + "order.startDate", + "order.endDate", + "order.customer", + "order.headcount", + "vehicle.plate", + "vehicle.model" + ] + } +} +``` + +--- + ## 15. å‰ç«¯é”™è¯¯ç ä¸ŽæŒ‰é’®çŠ¶æ€å¤„ç† | code | 场景 | å‰ç«¯å¤„ç† | @@ -1879,6 +2218,11 @@ DELETE /admin/fleet/message-templates/{templateId} - èœå•çº§çœŸå®ž API：`23/23` é€šè¿‡ï¼Œè®¢å• `HL20260705204251138`，覆盖 76 个åŽå°ç«¯ç‚¹ã€‚ - 全链路真实 API：`31/31` é€šè¿‡ï¼Œè®¢å• `HL20260705204312543`。 - 多订å•å¹¶å‘：`10/10` 通过，真实创建 3 ä¸ªè®¢å• `HL20260705204330462`ã€`HL20260705204332693`ã€`HL20260705204334918`，仅 1 å•æ´¾å•æˆåŠŸï¼Œå…¶ä½™æŒ‰ `605001` 冲çªè¿”回。 +- 2026-07-06 独立账å·è¯»æŽ¥å£å›žå½’：`32/32` 通过，报告 `HL-v3/.tmp/4760_independent_api_report.md`。覆盖工作å°ã€è§’色 403ã€æ´¾å•çœ‹æ¿ã€çŸ©é˜µã€è½¦è¾†/车型ã€å¸æœºã€ä»·æ ¼æ—¥åŽ†ã€è½¦ç®¡æ¨¡æ¿ã€è½¦é˜Ÿå¯¹è´¦ã€ä¿é™©ä»»åŠ¡ã€çœŸå®žå¤§äº¤é€šæ ·æœ¬ã€‚ +- 2026-07-06 独立账å·å†™æŽ¥å£æŽ¢é’ˆï¼š`22/22` 通过，报告 `HL-v3/.tmp/4760_write_api_report.md`。覆盖 `precheck/create/confirm/cancel`ã€å¸æœºé™©ä»»åŠ¡ç”Ÿæˆå’Œå¿½ç•¥ã€`offline-done` 缺凭è¯æ ¡éªŒã€å¯¹è´¦å®žä»˜ä¿å­˜/清空ã€æ¨¡æ¿æ¸²æŸ“å’Œéžæ³•å˜é‡ã€‚ - 本地åŽç«¯éªŒè¯ï¼š - `mvn -pl hl-fleet-service -am "-Dtest=AssignmentServiceTest,FleetAdminRoleGuardInterceptorTest" -DfailIfNoTests=false test` 通过，69 tests。 + - `mvn -pl hl-fleet-service -am "-Dtest=DriverSettlementModeDictResolverTest,DriverControllerTest,DriverImportServiceTest,DriverServiceTest,DriverCrudIntegrationTest,FleetInsuranceTaskServiceTest,AssignmentControllerTest" -DfailIfNoTests=false test` 通过，221 tests。 + - `mvn -pl hl-fleet-service -am -DskipTests compile` 通过。 + - `git diff --check` 通过，无空白错误。 - `mvn -pl hl-fleet-service spotless:check` 通过。 diff --git a/changelogs-v2/2026-07/26_4760_车务å¸æœºé™©è‡ªåŠ¨æŠ•é€€ä¿é—­çŽ¯ä¸Žä¿é™©èœå•å¥‘约-管ç†åŽå°.md b/changelogs-v2/2026-07/26_4760_车务å¸æœºé™©è‡ªåŠ¨æŠ•é€€ä¿é—­çŽ¯ä¸Žä¿é™©èœå•å¥‘约-管ç†åŽå°.md index 4375193..529164f 100644 --- a/changelogs-v2/2026-07/26_4760_车务å¸æœºé™©è‡ªåŠ¨æŠ•é€€ä¿é—­çŽ¯ä¸Žä¿é™©èœå•å¥‘约-管ç†åŽå°.md +++ b/changelogs-v2/2026-07/26_4760_车务å¸æœºé™©è‡ªåŠ¨æŠ•é€€ä¿é—­çŽ¯ä¸Žä¿é™©èœå•å¥‘约-管ç†åŽå°.md @@ -23,8 +23,8 @@ | 角色 | 行为 | |------|------| -| `admin` / 车务角色 | å¯è®¿é—® `/admin/fleet/insurance/**`，å¯æŸ¥çœ‹ä»»åŠ¡ã€é‡è¯•ã€æ ‡è®°çº¿ä¸‹å®Œæˆã€å¿½ç•¥ | -| `wx` / 定制师 | ä¸åº”展示车务ä¿é™©èœå•ï¼›è‹¥è®¿é—® `/admin/fleet/**` 按角色守å«è¿”回 `403` | +| `VEHICLE_MANAGER` / 车务角色 | å¯è®¿é—® `/admin/fleet/insurance/**`，å¯æŸ¥çœ‹ä»»åŠ¡ã€é‡è¯•ã€æ ‡è®°çº¿ä¸‹å®Œæˆã€å¿½ç•¥ã€‚测试æœç‹¬ç«‹è´¦å·ï¼š`fleet_mgr_4760` | +| `CUSTOMIZER` / 定制师 | ä¸åº”展示车务ä¿é™©èœå•ï¼›è‹¥è®¿é—® `/admin/fleet/**` 按角色守å«è¿”回 `403`。测试æœç‹¬ç«‹è´¦å·ï¼š`designer_4760` | å‰ç«¯ä¸è¦å¤ç”¨è®¢å•ä¿é™©é¡µé¢çš„æ•°æ®æºã€‚车务ä¿é™©èœå•åªè°ƒæœ¬æ–‡ä»¶æŽ¥å£ã€‚ @@ -236,7 +236,7 @@ POST /admin/fleet/insurance/tasks/{taskId}/offline-done - `policyNo` 为空：å‚数校验失败。 - `premiumAmount` 为空或负数：å‚数校验失败。 -- `proofUrls` 为空数组或ä¸ä¼ ï¼šè¿”回 `100001` / å‚数校验失败。 +- `proofUrls` 为空数组或ä¸ä¼ ï¼šè¿”回 `code=400`，`message=线下凭è¯ä¸èƒ½ä¸ºç©º`。 ---