diff --git a/changelogs-v2/2026-07/33_4797_车务派车协议价快照与对账取价口径-管理后台.md b/changelogs-v2/2026-07/33_4797_车务派车协议价快照与对账取价口径-管理后台.md new file mode 100644 index 0000000..35d4c76 --- /dev/null +++ b/changelogs-v2/2026-07/33_4797_车务派车协议价快照与对账取价口径-管理后台.md @@ -0,0 +1,106 @@ +# 33 · 车务派车协议价快照与对账取价口径(Issue #4797) + +日期:2026-07-06 +影响端:管理后台车务模块 +后端版本:`dev-v3` 已合并/部署后的 fleet 接口 + +## 变更结论 + +派车时新增/明确 `protocolPrice` 协议价日单价快照,单位:元/车天。前端在派车弹窗有明确协议价时传入;不传时后端会按所选车辆车型 + 用车开始日从价格日历兜底。保存后写入 `fleet_assignment.protocol_price`,后续看板、矩阵、当天订单和内部查询均回显该快照。 + +对账 prep 生成时优先使用派单快照;历史派单快照为空时才回退价格日历。快照为空且价格日历也缺价时,仍返回 `605607`。 + +## 1. 创建派单 + +`POST /admin/fleet/assignments` + +请求新增/明确字段: + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `protocolPrice` | string | 否 | 协议价日单价,元/车天,金额字符串。不能小于 0。| + +请求示例: + +```json +{ + "orderId": "1934567890123456789", + "orderNo": "26-0503", + "requirementId": "1934567890123456790", + "fleetItemIndex": 0, + "vehicleId": "1934567890123456701", + "driverId": "1934567890123456702", + "startDate": "2026-05-06", + "endDate": "2026-05-11", + "pickupAt": "hailar", + "dropoffAt": "hailar", + "headcount": 6, + "protocolPrice": "1300.00", + "holdMode": 1, + "fromEntry": "from-board", + "skipCityJunctionException": false, + "strictSeats": false, + "requestId": "fleet-assign-20260706-001" +} +``` + +响应示例: + +```json +{ + "code": 200, + "data": { + "id": "2073746962003144705", + "assignmentStatus": "holding", + "protocolPrice": "1300.00", + "holdSentAt": "2026-05-04T09:00:00+08:00" + }, + "message": "已锁定排车(holding),待司机回执" +} +``` + +## 2. 回显接口 + +以下接口都会回显 `protocolPrice`: + +| 接口 | 字段路径 | +|---|---| +| `GET /admin/fleet/board/orders/{orderId}` | `data.currentAssignment.protocolPrice` | +| `GET /admin/fleet/matrix/grid` | `data.vehicles[].assignments[].protocolPrice` | +| `GET /admin/fleet/matrix/day-orders` | `data[].assignments[].protocolPrice` | +| `GET /internal/fleet/assignment-by-order` | `data.currentAssignment.protocolPrice`、`data.history[].protocolPrice` | + +矩阵示例: + +```json +{ + "id": "2073746962003144705", + "orderId": "1934567890123456789", + "customerName": "张先生一家", + "headcountLabel": "2大1小", + "startDay": 6, + "endDay": 11, + "vehicleCategory": "suv", + "categoryLabel": "SUV", + "requiredSource": "order_product", + "assignmentStatus": "assigned", + "protocolPrice": "1300.00", + "productName": "草原沙漠精华6日" +} +``` + +## 3. 对账口径 + +对账接口本身不新增字段,但 `GET /admin/fleet/reconciliation/cars` 中的金额已经按 prep 快照聚合。 + +取价优先级: + +1. `fleet_assignment.protocol_price` +2. 历史空快照回退 `fleet_pricing_calendar.day_price` +3. 两者都没有时,生成 prep 抛 `605607` + +前端注意: + +- 展示历史派单时,直接展示接口返回的 `protocolPrice`,不要用当前价格日历覆盖。 +- `protocolPrice=null` 是合法历史/缺价状态,不代表接口失败。 +- 负数协议价会走参数校验失败,前端输入框应限制为非负金额。