feat(fleet): query vehicle delivery and reassignment history

2026-10-03 10:10:55 +08:00
parent d93185e750
commit 30559fd4eb
8 changed files with 420 additions and 0 deletions
@@ -0,0 +1,105 @@
+openapi: 3.0.3
+info:
+  title: 车辆履约与更换历史
+  version: 1.0.0
+  description: >-
+    平台按稳定车辆ID读取Lastleg本库履约事实，不按当前车牌文本反查，不修改单据或历史。
+    计划中的派送归当前分配车辆；实际发车后按不可变DEPART历史中的车辆身份归属。
+    关联排车和派送时同时匹配客户归属，不返回财务、附件、联系人或内部数据库主键。
+    更换记录依据相邻车次版本的ASSIGN快照，首次分配和资源未变化的操作不算更换。
+    旧车和新车均能读取同一更换事实；仅换司机也保留。返回历史车牌/姓名，不用当前主档覆盖。
+    不生成原型示例记录；没有正式车次关联的旧派送不通过车牌猜测归属。
+security: [{bearerAuth: []}]
+paths:
+  /api/platform/v1/last-leg/fleet/vehicles/{vehicleId}/deliveries:
+    parameters:
+      - {$ref: '#/components/parameters/Vehicle'}
+      - {$ref: '#/components/parameters/Page'}
+      - {$ref: '#/components/parameters/Size'}
+    get:
+      summary: 当前车辆关联派送记录
+      description: '同时要求 platform:overseas-master-data:vehicle:list 与 platform:overseas-warehouse:delivery:list。按派送创建时间、内部排序键倒序分页；排序键不返回。'
+      responses:
+        '200':
+          description: '统一ApiResponse，成功code为200，data为分页；车辆不存在返回业务404语义。'
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    allOf:
+                      - {$ref: '#/components/schemas/Page'}
+                      - type: object
+                        properties:
+                          records: {type: array, items: {$ref: '#/components/schemas/Delivery'}}
+  /api/platform/v1/last-leg/fleet/vehicles/{vehicleId}/assignment-history:
+    parameters:
+      - {$ref: '#/components/parameters/Vehicle'}
+      - {$ref: '#/components/parameters/Page'}
+      - {$ref: '#/components/parameters/Size'}
+    get:
+      summary: 当前车辆相关的换车与换司机事实
+      description: '同时要求 platform:overseas-master-data:vehicle:list 与 platform:fleet:trip:list。按事件时间、历史排序键倒序分页，一行一个变更事件；关联排车使用该事件快照，不使用当前关联覆盖历史。'
+      responses:
+        '200':
+          description: '统一ApiResponse，data为分页。历史记录只含稳定业务编号及更换事实，不公开整份客户快照或操作人内部ID。'
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    allOf:
+                      - {$ref: '#/components/schemas/Page'}
+                      - type: object
+                        properties:
+                          records: {type: array, items: {$ref: '#/components/schemas/Change'}}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
+  parameters:
+    Vehicle: {name: vehicleId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    Page: {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
+    Size: {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 10}}
+  schemas:
+    Page:
+      type: object
+      required: [records, page, size, total, pages]
+      properties:
+        page: {type: integer, minimum: 1}
+        size: {type: integer, minimum: 1, maximum: 100}
+        total: {type: integer, format: int64, minimum: 0}
+        pages: {type: integer, format: int64, minimum: 0}
+    Delivery:
+      type: object
+      required: [deliveryNo, dispatchNo, tripNo, status, relationship]
+      properties:
+        deliveryNo: {type: string}
+        dispatchNo: {type: string}
+        tripNo: {type: string}
+        bolNo: {type: string, nullable: true}
+        customerName: {type: string, nullable: true}
+        destinationType: {type: string}
+        destinationWarehouseCode: {type: string, nullable: true}
+        destinationWarehouseName: {type: string, nullable: true}
+        deliveryAddress: {type: string, nullable: true}
+        plannedDeliveryAt: {type: string, nullable: true, description: 服务端作业时区的本地日期时间}
+        status: {type: string}
+        relationship: {type: string, enum: [PLANNED, DEPARTED]}
+    Change:
+      type: object
+      required: [tripNo, recordVersion, occurredAt, relationship, dispatchNos]
+      properties:
+        tripNo: {type: string}
+        recordVersion: {type: string, pattern: '^[0-9]+$', description: 车次版本字符串，与车次号组成事件标识}
+        occurredAt: {type: string, format: date-time}
+        reason: {type: string, nullable: true}
+        previousVehiclePlate: {type: string, nullable: true}
+        vehiclePlate: {type: string, nullable: true}
+        previousDriverName: {type: string, nullable: true}
+        driverName: {type: string, nullable: true}
+        relationship: {type: string, enum: [REPLACED_OUT, REPLACED_IN, DRIVER_CHANGED]}
+        dispatchNos: {type: array, items: {type: string}}