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
@@ -4658,3 +4658,17 @@ CREATE TABLE IF NOT EXISTS ll_document_sequence (
  PRIMARY KEY (sequence_key),
  CONSTRAINT chk_ll_document_sequence_value CHECK (current_value > 0)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='业务单据每日独立原子流水';
+
+CREATE TABLE IF NOT EXISTS ll_fleet_resource_photo (
+  resource_kind VARCHAR(16) NOT NULL COMMENT '档案类型：车辆或司机',
+  resource_id BIGINT NOT NULL COMMENT '车辆或司机档案标识',
+  record_version BIGINT NOT NULL COMMENT '照片版本，从一递增',
+  file_id BIGINT NOT NULL COMMENT '文件服务照片标识',
+  file_name VARCHAR(512) NOT NULL COMMENT '照片原始文件名',
+  content_type VARCHAR(64) NOT NULL COMMENT '照片媒体类型',
+  size_bytes BIGINT NOT NULL COMMENT '照片字节数',
+  created_by VARCHAR(64) NOT NULL COMMENT '上传操作人标识',
+  created_at DATETIME(3) NOT NULL COMMENT '上传时间（UTC）',
+  PRIMARY KEY (resource_kind, resource_id, record_version),
+  UNIQUE KEY uk_fleet_resource_photo_file (resource_kind, resource_id, file_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='车辆及司机档案照片版本记录';
@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
  title: 排车装车资料（Admin/PDA共用）
  version: 1.0.0
-  description: LOADING阶段即可同步上传并保存五个整车照片框；照片齐全不会提前发车。装车确认时资料已齐则直接进入DELIVERING，否则进入AFTER_LOADING，最后一次绑定自动生成派送并进入DELIVERING。触发推进的装车确认或照片绑定与派送同事务，失败保留先前已保存资料。复用车队照片记录，技术槽位仅表示照片1至5，不代表驾驶证审核或真实签收。PDA每次核验Token冻结仓，平台list只读、edit写；原键仅原操作者恢复。
+  description: LOADING阶段即可同步上传并保存五个整车照片框；照片齐全不会提前发车。装车确认时资料已齐则直接进入DELIVERING，否则进入AFTER_LOADING，最后一次绑定自动生成派送并进入DELIVERING。触发推进的装车确认或照片绑定与派送同事务，失败保留先前已保存资料。复用车队照片记录，技术槽位沿用原文件归属，按顺序对应司机驾驶证、车牌照片、装车完成、封车照片、BOL司机签字；每类1至5张，允许追加或指定replaceFileId精确替换，不代表驾驶证审核或真实签收。PDA每次核验Token冻结仓，平台list只读、edit写；原键仅原操作者恢复。
 security:
 - bearerAuth: []
 paths:
@@ -375,7 +375,7 @@ components:
          - DELIVERED
        complete:
          type: boolean
-          description: 五个固定框各有一张已保存照片
+          description: 五类各至少一张已保存照片，不能用总张数代替类别齐全
    BindPhoto:
      type: object
      required:
@@ -392,3 +392,8 @@ components:
          maxLength: 128
        fileId:
          type: string
+        replaceFileId:
+          type: string
+          nullable: true
+          pattern: "^[1-9][0-9]*$"
+          description: 待替换的当前同类文件ID；省略时装车照片追加，每类最多5张，油耗沿单张替换。
@@ -240,3 +240,8 @@ components:
          maxLength: 128
        fileId:
          type: string
+        replaceFileId:
+          type: string
+          nullable: true
+          pattern: "^[1-9][0-9]*$"
+          description: 待替换的当前同类文件ID；省略时装车照片追加，每类最多5张，油耗沿单张替换。
@@ -175,6 +175,12 @@ components:
        recordVersion: { type: string, pattern: "^(0|[1-9][0-9]*)$" }
        idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
        fileId: { type: string, pattern: "^[1-9][0-9]*$" }
+        replaceFileId:
+          type: string
+          nullable: true
+          pattern: "^[1-9][0-9]*$"
+          description: 待替换的当前同类文件ID；省略时装车照片追加，每类最多5张，油耗沿单张替换。
+
    Vehicle:
      type: object
      x-java-record: OutsourcedBusinessModels.Vehicle
@@ -500,6 +500,12 @@ components:
        fileId:
          type: "string"
          pattern: "^[1-9][0-9]*$"
+        replaceFileId:
+          type: string
+          nullable: true
+          pattern: "^[1-9][0-9]*$"
+          description: 待替换的当前同类文件ID；省略时装车照片追加，每类最多5张，油耗沿单张替换。
+
    Gate:
      type: "object"
      x-java-record: "OwnedBusinessModels.Gate"
@@ -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]*$'}