feat(lastleg): reuse fleet photos and support multiple loading images

2026-10-26 17:12:36 +08:00
parent 5ad599bd66
commit 5eabfa395b
45 changed files with 961 additions and 35 deletions
@@ -0,0 +1,82 @@
+openapi: 3.0.3
+info:
+  title: 车辆与司机档案照片
+  version: 1.0.0
+  description: >-
+    档案照片使用独立版本并保留历史。车辆读取沿vehicle:list、上传沿vehicle:edit；
+    司机读取沿driver:list、上传沿driver:upload，均位于platform:overseas-master-data权限域。
+    只接受非空JPG/PNG，最大10MiB。排车保存时仅对缺失的车辆/司机照片复制当趟附件；
+    后续更换档案照片不覆盖已有排车照片，不创建临时外配主档，不改变驾驶证审核。
+    驾驶证仍走既有license接口；排车审核与主档统一接受PDF/JPG/PNG。
+security:
+  - bearerAuth: []
+paths:
+  /api/platform/v1/last-leg/fleet/resource-photos/{kind}/{id}:
+    parameters:
+      - {$ref: '#/components/parameters/Kind'}
+      - {$ref: '#/components/parameters/Id'}
+    get:
+      summary: 读取当前档案照片，未上传时版本为0且photo为空
+      responses:
+        '200': {$ref: '#/components/responses/Detail'}
+        '403': {description: 缺少该类档案list权限}
+    post:
+      summary: 上传或替换档案照片，照片版本冲突时不覆盖
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [recordVersion, file]
+              properties:
+                recordVersion: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
+                file: {type: string, format: binary}
+      responses:
+        '200': {$ref: '#/components/responses/Detail'}
+        '403': {description: 缺少车辆edit或司机upload权限}
+  /api/platform/v1/last-leg/fleet/resource-photos/{kind}/{id}/{fileId}/content:
+    parameters:
+      - {$ref: '#/components/parameters/Kind'}
+      - {$ref: '#/components/parameters/Id'}
+      - {name: fileId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+    get:
+      summary: 读取本档案已关联的当前或历史图片，no-store且无匿名URL
+      responses:
+        '200':
+          description: 图片内容；业务错误为统一JSON响应，不可当成图片
+          content:
+            image/jpeg: {schema: {type: string, format: binary}}
+            image/png: {schema: {type: string, format: binary}}
+        '403': {description: 缺少该类档案list权限}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
+  parameters:
+    Kind: {name: kind, in: path, required: true, schema: {type: string, enum: [VEHICLE, DRIVER]}}
+    Id: {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+  responses:
+    Detail:
+      description: 业务成功code为200；版本冲突或归属无效通过业务错误返回
+      content:
+        application/json:
+          schema:
+            type: object
+            required: [code, data]
+            properties:
+              code: {type: string}
+              message: {type: string}
+              data:
+                type: object
+                required: [recordVersion, photo]
+                properties:
+                  recordVersion: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
+                  photo:
+                    type: object
+                    nullable: true
+                    required: [fileId, fileName, contentType, sizeBytes]
+                    properties:
+                      fileId: {type: string, pattern: '^[1-9][0-9]*$'}
+                      fileName: {type: string}
+                      contentType: {type: string, enum: [image/jpeg, image/png]}
+                      sizeBytes: {type: string, pattern: '^[1-9][0-9]*$'}