API Changelog Bot 42a6367528 docs: update fleet API handoff examples

2026-07-06 12:16:45 +08:00

51 KiB

原始文件 Blame 文件历史

【前端对接·管理后台】车务菜单全接口验收与契约收口

Issue: wx/HL#4756
PR: wx/HL#4757, wx/HL#4758, wx/HL#4759 追加验证: 2026-07-06 独立账号 fleet_mgr_4760/VEHICLE_MANAGER、designer_4760/CUSTOMIZER 服务: hl-fleet-service + hl-order-service-v3
日期: 2026-07-05
影响范围: 管理后台车务管理全菜单

1. 结论

测试服已完成真实 API 回归：车务菜单级 23/23 通过，覆盖后台端点 76 个。
2026-07-06 追加独立账号回归：读接口/只读场景 32/32 通过；写接口探针 22/22 通过，覆盖派单预检、创建、确认、取消、司机险任务、车队对账实付保存/清空、模板渲染/错误分支。
补充全链路回归 31/31 通过，多订单并发回归 10/10 通过。
已修复派单重复确认返回 100000 的问题，现在返回业务码 605020 当前派单状态不允许此操作。
/admin/fleet/** 已按当前登录角色拦截：车务角色可访问，定制师角色会返回 403。

2. 前端必须处理

场景	前端处理
当前角色	车务菜单只能由 `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`=直接结算，`fleet_leader`=车队长结算。不要再传旧值 `captain`。
待审核详情 ID	`GET /admin/fleet/drivers/pending/{pendingId}` 响应主键字段是 `id`，不是 `pendingId`；路径变量仍叫 `pendingId`。
派单重复确认	`POST /admin/fleet/assignments/{assignmentId}/confirm` 只允许 `holding -> assigned`；非 `holding` 返回 `605020`。
取消重复操作	终态派单再次取消也返回 `605020`。
快速连点	多个写接口有幂等保护，会返回 `100502`，前端按钮需要 loading/disabled。不要把 `100502` 当系统故障。
价格日历多车型批量设价	`PUT /admin/fleet/pricing-calendar/batch-set` 幂等窗口是 300 秒，同一批完全相同入参会返回 `100502`。
价格日历删除	`DELETE /admin/fleet/pricing-calendar/{vehicleModelId}` 使用 query 参数 `startDate`、`endDate`，不要放 body。
车型树字段	`GET /admin/fleet/vehicle-types` 大类和车型主键都读 `id`；不要读旧的 `typeId`。
看板 summary	使用 `pendingUrgentCount`、`holdingTimeoutCount`；不要自造旧字段。
车辆 busy	车辆新增/编辑不能人工写 `vehicleStatus=busy`，返回 `600112`；busy 只能由派单占用反算。
常驻司机冲突	车辆指定常驻司机时，司机已被别车占用返回 `605022`；司机侧改绑目标车已被占用返回 `605023`。
自带车审核	H5 自带车 `regCertUsage` 为营运类时必须带 `operationLicenseUrls`。

3. 本次确认的菜单覆盖

菜单	关键接口
车务工作台	`/admin/profile/dashboard?period=today`
派单看板	`/admin/fleet/board/summary`, `/orders`, `/orders/{orderId}`, `/timeline`, `/expiry`, `/assignments/**`
矩阵派单	`/admin/fleet/matrix/grid`, `/unassigned-orders`, `/day-orders`
车队对账	`/admin/fleet/reconciliation/cars`, `/insurance`, `/periods`, `/actual`, `/close`, `/reopen`, `/pending-compensations/**`, `/export/cars`
价格日历	`/admin/fleet/pricing-calendar/overview`, `/{vehicleModelId}`, `/{vehicleModelId}/status`, `/batch-set`
车辆档案	`/admin/fleet/vehicles/page`, `/{vehicleId}`, `/{vehicleId}/disable`, `/{vehicleId}/enable`, `/import`, `/import/template`
车型管理库	`/admin/fleet/vehicle-types`, `/list`, `/page`, `/models/page`, `/{typeId}`, `/{typeId}/models`, `/models/{modelId}`
司机档案	`/admin/fleet/drivers/page`, `/options`, `/{driverId}`, `/{driverId}/resident-vehicle`, `/{driverId}/blacklist`, `/{driverId}/unban`, `/batch-season-renew`, `/import`, `/import/template`
待审核/自助录入	`/admin/fleet/drivers/pending/`, `/admin/fleet/h5/token`, `/h5/tokens/`, `/app/h5/driver-onboard/**`
车管模板	`/admin/fleet/message-templates/**`

4. 统一调用约定

4.1 Header

管理后台车务接口统一走测试域名：

Authorization: Bearer <admin-token>
Content-Type: application/json

角色边界：

fleet_mgr_4760/VEHICLE_MANAGER：允许访问 /admin/fleet/**。
designer_4760/CUSTOMIZER：访问 /admin/fleet/** 返回 403，前端应提示切换车务角色。
/app/h5/**：公开 H5 入口，不走车务角色 guard，但需要 token 参数。

4.2 成功响应包

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {}
}

4.3 失败响应包

{
  "code": 605020,
  "message": "当前派单状态不允许此操作",
  "success": false,
  "data": null
}

说明：下面示例来自本次测试服真实 API 回归结构，手机号、token、部分 ID 做了脱敏或占位。前端处理长整型 ID 时建议按字符串保存，避免 JS 精度问题。

4.4 分页与全量接口约定

公共分页对象 page/pageSize 的上限仍为 100，车务模块不绕过公共上限。
页面列表、弹窗选择、远程搜索列表继续调用分页接口，前端分页选项不要超过 100。
下拉、筛选、树形选择等“需要全量选项”的场景不要用 pageSize=200/1000 拉分页接口，应改用对应的非分页轻量端点。
当前可用非分页端点：

GET /admin/fleet/vehicle-types
GET /admin/fleet/vehicle-types/list
GET /admin/fleet/drivers/options?keyword=王&limit=20
GET /admin/fleet/message-templates
GET /admin/fleet/reconciliation/periods?fromMonth=2026-01

场景	正确接口	不要这么调
车辆列表页/车辆档案分页	`GET /admin/fleet/vehicles/page?page=1&pageSize=24`	不要 `pageSize>100`
派单弹窗选择车辆	`GET /admin/fleet/vehicles/page?page=1&pageSize=10&vehicleStatus=idle`	不要用一个下拉一次拉全部车辆
车型大类筛选下拉	`GET /admin/fleet/vehicle-types/list`	不要 `/vehicle-types/page?pageSize=1000`
大类+型号树选择	`GET /admin/fleet/vehicle-types`	不要按每个大类再批量扫 `/models/page`
司机远程搜索下拉	`GET /admin/fleet/drivers/options?keyword=王&limit=20`	不要 `/drivers/page?pageSize=1000`
车管模板列表	`GET /admin/fleet/message-templates`	该接口本身不分页，不要拼 page/pageSize
车队对账主数据	`GET /admin/fleet/reconciliation/cars` / `insurance`	主数据不分页，不要自己从车辆/司机分页接口拼 mock

如果后续前端出现新的“确实需要全量车辆选项”的页面，不要扩大 /vehicles/page 上限；先提需求补一个窄字段的车辆 options 接口，限定字段和筛选条件。

4.5 车务工作台

车务首页入口仍走用户服务的角色分发接口；当前登录角色必须是 VEHICLE_MANAGER：

GET /admin/profile/dashboard?period=today

响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "pendingArrangeVehicle": 3,
    "upcomingTrips": [
      {
        "orderId": "70123456789",
        "assignmentId": "80123456789",
        "orderNo": "HL202607010001",
        "productName": "呼伦贝尔 6 日",
        "customerName": "张先生",
        "departureDate": "2026-07-10",
        "endDate": "2026-07-15",
        "headcount": 4,
        "status": "unassigned_urgent",
        "statusLabel": "待派",
        "urgentBadge": "T-1"
      }
    ]
  }
}

字段口径：

字段	说明
`pendingArrangeVehicle`	来源 fleet 派单看板 `pendingCount`，即当前待派单数，含紧急待派。
`upcomingTrips`	来源 fleet 派单看板列表，近 7 天游程，最多 5 条。
`status`	车务派单态：`unassigned`、`unassigned_urgent`、`holding`、`holding_urgent`、`assigned`。
`orderId` / `assignmentId`	长整型按字符串处理，前端不要转 JS Number。

这不是分页不足问题；工作台不应从 /admin/fleet/vehicles/page 或旧 DashboardStats 拼数据，也不应使用本地 useFleetStore mock。

5. 订单前置：新建订单、出行人、大交通、用车需求

车务矩阵/看板的数据不是 mock，也不是手工造 fleet 数据；前置链路必须从 wx 定制师订单开始。

5.1 新建订单

POST /v3/admin/order

请求：

{
  "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"]
}

响应：

{
  "code": 200,
  "success": true,
  "data": {
    "orderId": "2073749536638992386",
    "orderNo": "HL20260705204312543"
  }
}

5.2 补全出行人

PUT /v3/admin/order/{orderId}/traveler-info

请求：

{
  "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"
}

响应：

{
  "code": 200,
  "success": true,
  "data": {
    "createdCount": 2,
    "pendingCount": 0,
    "allCompleted": true
  }
}

5.3 写入到达/返程大交通

POST /v3/admin/order/{orderId}/transport-plan/batch

请求：

{
  "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"
    }
  ]
}

响应：

{
  "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 提交用车需求

PUT /v3/admin/order/{orderId}/vehicle-requirement

请求：

{
  "fleet": [
    { "vehicleType": "SUV", "seats": 5, "count": 1 }
  ],
  "remark": "fleet full api regression with transport",
  "specialTags": ["API_TEST_FLEET_FULL", "HAS_TRANSPORT"]
}

响应：

{
  "code": 200,
  "success": true,
  "data": {
    "requirementId": "2073749544025161730",
    "status": "PENDING",
    "version": 1,
    "vehicleTypeSummary": "SUV×1"
  }
}

6. 派单看板与矩阵派单

6.1 看板 summary

GET /admin/fleet/board/summary

响应：

{
  "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 看板订单列表

GET /admin/fleet/board/orders?page=1&pageSize=20&keyword=HL20260705204312543&statuses=assigned&statuses=completed&variant=list

响应：

{
  "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 看板详情与时间线

GET /admin/fleet/board/orders/{orderId}
GET /admin/fleet/board/orders/{orderId}/timeline

详情响应：

{
  "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
  }
}

时间线响应：

{
  "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、未派、当天订单

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 响应：

{
  "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
  }
}

未派/当天订单记录至少关注：

{
  "orderNo": "HL20260705204312543",
  "orderNumericId": "2073749536638992386",
  "startDate": "2026-07-18",
  "endDate": "2026-07-20",
  "headcount": 2,
  "vehicleTypeSummary": "SUV×1"
}

7. 派单操作接口

7.1 预校验

POST /admin/fleet/assignments/precheck

请求：

{
  "vehicleId": "2073749553340706818",
  "driverId": "2073749552489267202",
  "orderId": "2073749536638992386",
  "startDate": "2026-07-18",
  "endDate": "2026-07-20",
  "headcount": 2,
  "pickupAt": "hailar",
  "dropoffAt": "hailar"
}

响应：

{
  "code": 200,
  "success": true,
  "data": {
    "conflict": false,
    "conflicts": [],
    "warnings": []
  }
}

7.2 创建派单

POST /admin/fleet/assignments

请求：

{
  "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"
}

响应：

{
  "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 确认、取消、撤销取消、提前完结

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

确认请求：

{ "driverReplyNote": "接口测试确认接单" }

确认响应：

{
  "code": 200,
  "success": true,
  "data": {
    "id": "2073749544096460802",
    "assignmentStatus": "assigned",
    "confirmedAt": "2026-07-05T20:43:20",
    "itineraryUrl": "https://web.test.1814.love:9443/fleet/itinerary/<token>",
    "sideEffects": {
      "vehicleStatusUpdated": "busy",
      "driverStatusUpdated": "busy",
      "reconPrepRowsCreated": 0
    }
  }
}

取消请求：

{
  "cancelReason": "客户取消",
  "driverNotified": true,
  "notifyNote": "已电话通知司机",
  "cutoffDate": "2026-07-18"
}

提前完结请求：

{
  "completeReason": "行程提前结束",
  "cutoffDate": "2026-07-18"
}

关键错误：

{
  "code": 605020,
  "message": "当前派单状态不允许此操作",
  "success": false
}

{
  "code": 605021,
  "message": "当前状态不可提前完结",
  "success": false
}

{
  "code": 605001,
  "message": "派单冲突：该车日期段已派",
  "success": false
}

8. H5 行程单响应结构

GET /app/h5/itinerary/{token}

响应：

{
  "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 新增/编辑司机

POST /admin/fleet/drivers
PUT /admin/fleet/drivers/{driverId}

请求：

{
  "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": []
}

响应：

{
  "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`	车队长结算

当前字典库真实值是 fleet_leader。captain 是旧草稿值，后端不会按该值入库，前端新增/编辑/导入都不要再传。

非法值响应：

{
  "code": 100001,
  "message": "参数非法: 司机结算方式非法，取值来自字典 driver_settlement_mode「直接结算」「车队长结算」，值=bad_mode",
  "success": false
}

9.2 司机分页、下拉、常驻车、拉黑/解封

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

常驻车请求：

{ "vehicleId": "2073749553340706818" }

拉黑请求：

{ "blacklistReason": "菜单验收拉黑" }

重复快速提交可能返回：

{
  "code": 100502,
  "message": "拉黑处理中，请勿重复提交",
  "success": false
}

9.3 新增/编辑车辆

POST /admin/fleet/vehicles
PUT /admin/fleet/vehicles/{vehicleId}

请求：

{
  "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": []
}

响应：

{
  "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 错误响应：

{
  "code": 600112,
  "message": "车辆占用态只能在空闲与维保间人工切换，在用(busy)由系统派单写入",
  "success": false
}

9.4 导入/模板下载

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：

file=@drivers.csv; type=text/csv

司机导入响应：

{
  "code": 200,
  "success": true,
  "data": {
    "totalRows": 1,
    "insertedCount": 1,
    "renewedCount": 0,
    "warnedCount": 0,
    "errorCount": 0
  }
}

错误后缀：

{
  "code": 100001,
  "message": "参数非法: 不支持的文件类型，仅支持 .xlsx / .xls / .csv",
  "success": false
}

10. 车型管理库

10.1 车型树与分页

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=丰田

车型树响应：

{
  "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

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}

新增大类请求：

{
  "typeKey": "api4756",
  "typeName": "API测试大类",
  "sortOrder": 999,
  "icon": "Car",
  "description": "issue4756 api regression"
}

新增型号请求：

{
  "modelName": "API测试车型",
  "seats": 6,
  "basePrice": 123.45,
  "alias": "API4756",
  "sortOrder": 1
}

删除有子型号的大类：

{
  "code": 600104,
  "message": "大类下存在型号，不能删除",
  "success": false
}

11. 价格日历

11.1 查询总览和车型月历

GET /admin/fleet/pricing-calendar/overview?startDate=2026-07-18&endDate=2026-07-20
GET /admin/fleet/pricing-calendar/{vehicleModelId}?year=2026&month=7

总览响应：

{
  "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" }
        ]
      }
    ]
  }
}

月历响应：

{
  "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 单车型设价、状态、批量设价、删除

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 请求：

{
  "startDate": "2026-07-18",
  "endDate": "2026-07-20",
  "adjustMode": "ABS",
  "dayPrice": 888,
  "status": "AVAILABLE",
  "remark": "菜单验收 ABS"
}

DELTA 周末请求：

{
  "startDate": "2026-07-18",
  "endDate": "2026-07-20",
  "adjustMode": "DELTA",
  "adjustValue": -10,
  "weekendOnly": true,
  "status": "AVAILABLE",
  "remark": "菜单验收 DELTA"
}

批量设价请求：

{
  "vehicleModelIds": ["2064991856994758657"],
  "startDate": "2026-07-18",
  "endDate": "2026-07-20",
  "adjustMode": "ABS",
  "dayPrice": 777,
  "status": "AVAILABLE",
  "excludeDates": ["2026-07-20"],
  "remark": "菜单验收多车型"
}

成功响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": null
}

互斥错误：

{
  "code": 400,
  "message": "工作日/周末/节假日筛选不可同时启用",
  "success": false
}

日期范围错误：

{
  "code": 600501,
  "message": "日期范围非法：开始日期不能晚于结束日期",
  "success": false
}

前端注意：batch-set 幂等窗口 300 秒，同一批完全相同入参快速重复提交会返回 100502。

12. 待审核与司机自助录入 H5

12.1 生成录入 token

POST /admin/fleet/h5/token

新招请求：

{
  "mode": "new",
  "name": "自助师傅",
  "phone": "199****9992",
  "expireDays": 2
}

续签请求：

{
  "mode": "renew",
  "targetDriverId": "2073749552489267202",
  "expireDays": 2
}

响应：

{
  "code": 200,
  "success": true,
  "data": {
    "pendingId": "2073749600606318594",
    "token": "<h5-token>",
    "url": "https://web.test.1814.love:9443/fleet/driver-onboard?token=<h5-token>",
    "shortUrl": "https://t.cn/xxxx",
    "expireAt": "2026-07-07T20:43:30",
    "qrCodeUrl": "https://..."
  }
}

12.2 H5 初始化、上传、提交

GET /app/h5/driver-onboard/init?token=<h5-token>
POST /app/h5/driver-onboard/upload
POST /app/h5/driver-onboard/submit/new
POST /app/h5/driver-onboard/submit/renew

init 响应：

{
  "code": 200,
  "success": true,
  "data": {
    "mode": "new",
    "tokenValid": true,
    "tokenState": "editable",
    "stepConfig": {},
    "expireAt": "2026-07-07T20:43:30"
  }
}

upload 为 multipart/form-data：

token=<h5-token>
groupKey=fleet-menu-test
file=@photo.png

upload 响应：

{
  "code": 200,
  "success": true,
  "data": {
    "url": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/fleet-menu-test/2026/07/05/xxx.png"
  }
}

新招提交请求：

{
  "token": "<h5-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"]
}

提交响应：

{
  "code": 200,
  "success": true,
  "data": {
    "pendingId": "2073749372209688577",
    "estimatedReviewHours": 24
  }
}

前端注意：regCertUsage 为营运类时，operationLicenseUrls 必须上传；否则审核通过会返回 600406。

12.3 待审核列表、详情、通过、驳回

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

详情响应：

{
  "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。

通过请求：

{
  "approveReason": "菜单验收通过",
  "ownVehicle": {
    "vehicleModelId": "2064991856994758657",
    "fleet": "own",
    "plate": "蒙E-4756",
    "ownerType": "personal",
    "vin": "LSVH5APP00004756"
  }
}

通过响应：

{
  "code": 200,
  "success": true,
  "data": {
    "driverId": "2073749397010608129",
    "vehicleId": "2073749397039968257"
  }
}

驳回请求：

{ "rejectReason": "证件照片不清晰" }

驳回原因为空：

{
  "code": 400,
  "message": "驳回原因不能为空",
  "success": false
}

重复审核：

{
  "code": 600400,
  "message": "该记录已处理（已通过或已驳回），不可重复审核",
  "success": false
}

13. 车队对账

前端当前若仍用本地 useFleetStore / mock 计算车队对账，需要切到本节接口；后端主数据不是分页接口，返回结构也不是旧的 records/total。

13.1 查询车费、保险、对账期

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

车费响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "periodLabel": "2026-07",
    "periodStart": "2026-07-01",
    "periodEnd": "2026-07-31",
    "fleets": [
      {
        "fleet": "own",
        "fleetName": "自有车队",
        "orderCount": 3,
        "estimatedTotal": "27000.00",
        "payableTotal": "27000.00",
        "actualTotal": "26000.00",
        "settleMode": "OWN_COST",
        "diff": "-1000.00",
        "closed": false,
        "vehicles": [
          {
            "vehicleId": "2064991856994758657",
            "plate": "蒙A-88888",
            "modelName": "丰田汉兰达",
            "seats": 7,
            "orderCount": 3,
            "days": 18,
            "avgPerDay": "1500.00",
            "amount": "27000.00",
            "payableAmount": "27000.00"
          }
        ]
      }
    ],
    "grandTotal": {
      "estimated": "27000.00",
      "payable": "27000.00",
      "actual": "26000.00",
      "diff": "-1000.00",
      "totalDays": 18,
      "totalOrderCount": 3
    }
  }
}

字段口径：

字段	说明
`fleets[].orderCount`	车队内订单数，后端已按 `orderNo` 去重
`fleets[].estimatedTotal`	对客报价合计，利润分析用
`fleets[].payableTotal`	对车队应付合计，车队成本基准
`fleets[].actualTotal`	车务/财务手工录入实付，未录为 `null`
`fleets[].diff`	`actualTotal - payableTotal`，未录实付为 `null`
`fleets[].closed`	整月关账状态；非自然月查询恒为 `false`
`vehicles[].days`	车天，来自 active prep 行数
`vehicles[].avgPerDay`	`payableAmount / days`
`grandTotal.totalOrderCount`	全车队订单数，后端跨车队全局去重，前端不要用明细求和

保险响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "periodLabel": "2026-07",
    "grandTotal": "250.00",
    "fleets": [
      {
        "fleet": "own",
        "sourceSubtotals": {
          "manual": "120.00",
          "baoyou": "130.00"
        },
        "typeCounts": {
          "annual": 1,
          "perTrip": 1,
          "none": 0
        },
        "drivers": [
          {
            "driverId": "188800000000000001",
            "name": "王师傅",
            "phone": "138****1234",
            "insuranceType": "annual",
            "insuranceSource": "MANUAL",
            "billingMethod": "年保险按日摊销",
            "annualPremium": "3650.00",
            "perDayRate": null,
            "totalPremium": null,
            "orderCount": 2,
            "days": 12,
            "insuranceAmount": "120.00"
          },
          {
            "driverId": "188800000000000002",
            "name": "李师傅",
            "phone": "139****5678",
            "insuranceType": "",
            "insuranceSource": "BAOYOU",
            "billingMethod": "保游网实际出单",
            "annualPremium": null,
            "perDayRate": null,
            "totalPremium": "130.00",
            "orderCount": 1,
            "days": 3,
            "insuranceAmount": "130.00"
          }
        ]
      }
    ]
  }
}

保险字段口径：

字段	说明
`insuranceSource`	分组主键，取 `MANUAL/BAOYOU/NONE`；不要用 `insuranceType` 分组
`insuranceType`	司机配置类型，`annual/perTrip/none`；保游实际出单行可能为空字符串
`sourceSubtotals.manual`	手填年保费/行程险摊销小计
`sourceSubtotals.baoyou`	保游实际出单摊销小计
`typeCounts`	车队内司机保险类型计数
`grandTotal`	全车队保险成本合计，不含 `NONE`

对账期响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    {
      "label": "2026-07",
      "periodStart": "2026-07-01",
      "periodEnd": "2026-07-31",
      "closed": false,
      "reopened": false
    }
  ]
}

13.2 录入实付、关账、重开、补偿

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

录入实付请求：

{
  "periodStart": "2026-07-01",
  "periodEnd": "2026-07-31",
  "fleet": "own",
  "actualAmount": "26000.00",
  "note": "菜单验收录入"
}

响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "id": "2073749573041356801",
    "diff": "-1000.00",
    "payableEstimated": "27000.00",
    "estimated": "27000.00"
  }
}

清空实付：actualAmount 传 null 或省略，后端软删该 (periodStart, fleet) 实付行，响应中 diff 返 null。

补偿列表响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "page": 1,
    "pageSize": 5,
    "total": 1,
    "records": [
      {
        "compId": "2073749573041356802",
        "assignmentId": "2073749573041356803",
        "orderId": "2073749536638992386",
        "periodLabel": "2026-07",
        "opType": "TRUNCATE",
        "serviceDateFrom": "2026-07-20",
        "reason": "提前完结截断触及已关账期 2026-07",
        "status": "PENDING",
        "createTime": "2026-07-06T10:00:00",
        "resolvedAt": null,
        "resolvedBy": null,
        "resolveRemark": null
      }
    ]
  }
}

处置补偿请求：

{
  "remark": "已线下补对账，差额计入 2026-08 调整"
}

处置补偿响应：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "compId": "2073749573041356802",
    "status": "RESOLVED",
    "resolvedAt": "2026-07-06T10:30:00",
    "resolvedBy": "1001"
  }
}

负数错误：

{
  "code": 605608,
  "message": "实际金额必须大于等于0",
  "success": false
}

非自然月关账：

{
  "code": 605605,
  "message": "仅支持按自然月关账，自定义区间为只读分析",
  "success": false
}

非超管重开：

{
  "code": 403001,
  "message": "无权限，仅超级管理员可重开账",
  "success": false
}

14. 车管模板

模板列表是非分页接口；前端页面不要传 page/pageSize。测试服如果返回空数组，表示当前库没有配置模板，不是分页问题。

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}

新增请求：

{
  "templateName": "API派车通知",
  "templateType": "hold_notify",
  "bodyTemplate": "您好 {{driver.name}}，订单 {{order.no}} 已派车，车牌 {{vehicle.plate}}",
  "variablesHelp": "{\"driver.name\":\"司机姓名\"}",
  "isDefault": false,
  "sortOrder": 99
}

响应：

{
  "code": 200,
  "success": true,
  "data": {
    "id": "2073749573041356801",
    "templateName": "API派车通知",
    "templateType": "hold_notify",
    "bodyTemplate": "您好 {{driver.name}}，订单 {{order.no}} 已派车，车牌 {{vehicle.plate}}",
    "isDefault": false,
    "sortOrder": 99
  }
}

渲染请求：

{
  "orderId": "2073749536638992386",
  "driverId": "2073749573041356803",
  "vehicleId": "2073749573041356804"
}

渲染响应：

{
  "code": 200,
  "success": true,
  "data": {
    "renderedBody": "您好 API师傅，订单  已派车，车牌 蒙A-69665",
    "variablesUsed": ["driver.name", "order.no", "vehicle.plate"]
  }
}

说明：当前 driver.*、vehicle.* 可按 ID 渲染；order.* / itinerary.* 本期仍走占位端口，缺值会替换为空串，不报错。前端不要传 orderNo/driverName/vehiclePlate，这些不是该接口入参字段。

变量缺失：

{
  "code": 600800,
  "message": "模板变量缺失",
  "success": false
}

14.5 2026-07-06 独立账号写接口实测样本

本节是测试服真实返回，用于前端逐字段对齐。账号：fleet_mgr_4760/VEHICLE_MANAGER。测试派单已取消回滚，产生的司机险待处理任务已标记 IGNORED，不会污染待处理列表。

14.5.1 派单预检、创建、确认、取消

预检请求：

{
  "orderId": "2070756230887890945",
  "vehicleId": "2067084363580760065",
  "driverId": "2065272150960357378",
  "startDate": "2026-07-06",
  "endDate": "2026-07-08",
  "pickupAt": "hailar",
  "dropoffAt": "hailar",
  "headcount": 2
}

预检响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "conflict": false,
    "conflicts": [],
    "warnings": []
  }
}

创建 holding 请求：

{
  "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"
}

创建响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": "2070756257240694786",
    "assignmentStatus": "holding",
    "holdSentAt": "2026-07-06T...",
    "confirmedAt": null,
    "sideEffects": null
  }
}