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

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchAggregateService.java

@@ -33,6 +33,7 @@ import static com.baiyue.lastleg.dispatch.port.DispatchContracts.*;
 @Service
 public class DispatchAggregateService implements DispatchExecutionPort,DispatchAppointmentAmendmentPort {
     private static final org.slf4j.Logger LOG=org.slf4j.LoggerFactory.getLogger(DispatchAggregateService.class);
+    @jakarta.annotation.Resource private DispatchMasterPhotoService masterPhotos;
     @jakarta.annotation.Resource private DispatchNumberGenerator numbers;
     @jakarta.annotation.Resource private DispatchAppointmentAllocations appointments;
     @jakarta.annotation.Resource private DispatchPhysicalClaimService physicalClaims;
@@ -310,7 +311,7 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         row.setDispatchReviewJson(write(pending(0))); row.setLoadingReviewJson(write(pending(0)));
         var photos=request.driver()==null || request.driver().evidence()==null?List.<Long>of():request.driver().evidence().photoFileIds();
         if(!photos.isEmpty())verifyEvidence(id,com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER_PHOTO,photos);
-        Resources resources=resources(shell,photos,null); row.setResourcesJson(write(resources));
+        Resources resources=masterPhotos.populate(id,actor.operatorId(),resources(shell,photos,null)); row.setResourcesJson(write(resources));
         row.setVehiclePlate(resources.vehicle()==null ? null : resources.vehicle().plate());
         row.setPlannedDepartureAt(utc(request.plannedDepartureAt())); row.setEstimatedArrivalAt(utc(request.estimatedArrivalAt()));
         row.setItemCount(0); row.setPalletCount(0); row.setPackageCount(0); row.setPickedPackageCount(0); row.setShippedPackageCount(0);
@@ -443,7 +444,7 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
         if(vehiclePhotos!=null && !vehiclePhotos.isEmpty())verifyEvidence(row.getId(),com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.VEHICLE,vehiclePhotos);
         var actual=fleet.dispatchResources(number,fleetVehicle(request.vehicle()),updatedFleetDriver(request.driver(),read(row.getResourcesJson(),Resources.class)));
         DispatchDestinationAppointments.validate(request.maintenance(),reviewAppointments(row));
-        var savedResources=resources(actual,photos,request.maintenance());
+        var savedResources=masterPhotos.populate(row.getId(),actor.operatorId(),resources(actual,photos,request.maintenance()));
         // 主档引用只能由车队解析产生；补传照片必须核验本车归属后才允许保存。
         var savedDriver=savedResources.driver();
         if(savedDriver!=null && savedDriver.evidence()!=null)for(var id:savedDriver.evidence().fileIds()) {
@@ -794,21 +795,22 @@ public class DispatchAggregateService implements DispatchExecutionPort,DispatchA
             new FleetExecutionModels.DispatchDriver(d.mode().name(),d.driverId(),d.name(),d.phone(),e.licenseNo(),e.licenseExpiresOn(),e.fileIds(),e.expectedTaskEndAt()));
         if(!Objects.equals(hashes.source(r),hashes.source(resources(actual,e.photoFileIds(),r.maintenance()))))throw conflict("车辆或司机主档已变化，请重新保存并提交审核");
     }
-    /** 三类均须含至少一张当前有效图片；保存草稿不调用此送审/通过门禁。 */
+    /** 车辆和司机须有有效图片，驾驶证接受与档案一致的PDF或图片。 */
     private void verifyReviewPhotos(DispatchAggregate row,Resources resources) {
         var driver=resources.driver();var proof=driver.evidence();
         requireReviewPhoto(row,com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.VEHICLE,resources.vehicle().evidenceFileIds(),"车辆图片");
         requireReviewPhoto(row,com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER_PHOTO,proof.photoFileIds(),"司机照片");
         requireReviewPhoto(row,com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER,proof.fileIds(),"驾驶证照片");
     }
-    /** 文件存在、归属及有效性由原文件提供者复验，PDF不能充当照片。 */
+    /** 文件存在、归属及有效性由原提供者复验，PDF仅可作为驾驶证。 */
     private void requireReviewPhoto(DispatchAggregate row,com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind kind,List<Long> ids,String label) {
         if(ids==null || ids.isEmpty() || ids.size()>20 || ids.stream().anyMatch(id->id==null || id<=0) || ids.stream().distinct().count()!=ids.size())throw bad("请上传至少一张有效"+label);
         boolean image=false;
         for(var id:ids) {
             var master=masterEvidenceDriverId(row,kind,id);
             var file=master==null?evidence.metadata(row.getId(),kind,id):driverEvidenceMetadata(fleet.dispatchDriverLicense(master,id).metadata(),id);
-            if(file!=null && ("image/jpeg".equals(file.contentType()) || "image/png".equals(file.contentType())))image=true;
+            if(file!=null && ("image/jpeg".equals(file.contentType()) || "image/png".equals(file.contentType())
+                || kind==com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway.Kind.DRIVER && "application/pdf".equals(file.contentType())))image=true;
         }
         if(!image)throw bad("请上传至少一张有效"+label);
     }

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchMasterPhotoService.java

@@ -0,0 +1,66 @@
+package com.baiyue.lastleg.dispatch.service;
+
+import com.baiyue.lastleg.dispatch.gateway.DispatchEvidenceGateway;
+import com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.Kind;
+import com.baiyue.lastleg.fleet.photo.port.FleetResourcePhotoPort;
+import org.springframework.stereotype.Service;
+import org.springframework.web.multipart.MultipartFile;
+import java.io.*;
+import java.nio.file.Files;
+import java.util.List;
+import static com.baiyue.lastleg.dispatch.port.DispatchContracts.*;
+import static com.baiyue.lastleg.dispatch.port.DispatchTypes.ResourceMode.MASTER;
+
+/** 档案照片只在缺少本车照片时带入，复制为本车证据以冻结历史与文件权限。 */
+@Service
+public class DispatchMasterPhotoService {
+    private final FleetResourcePhotoPort photos;
+    private final DispatchEvidenceGateway evidence;
+    /** 只读主档并通过本车文件网关创建证据。 */
+    public DispatchMasterPhotoService(FleetResourcePhotoPort photos,DispatchEvidenceGateway evidence) {
+        this.photos=photos; this.evidence=evidence;
+    }
+    /** 保存前补入已有档案照片；临时资源和已有当趟照片保持原样。 */
+    public Resources populate(long dispatchId,String operator,Resources value) {
+        var v=value.vehicle(); var d=value.driver();
+        if(v!=null && v.mode()==MASTER && v.vehicleId()!=null) {
+            var ids=populate(dispatchId,operator,Kind.VEHICLE,v.vehicleId(),v.evidenceFileIds());
+            v=new VehicleSnapshot(v.mode(),v.vehicleId(),v.plate(),v.carrierName(),v.vehicleStatus(),v.capacity(),ids);
+        }
+        if(d!=null && d.mode()==MASTER && d.driverId()!=null && d.evidence()!=null) {
+            var e=d.evidence();
+            var ids=populate(dispatchId,operator,Kind.DRIVER,d.driverId(),e.photoFileIds());
+            d=new DriverSnapshot(d.mode(),d.driverId(),d.name(),d.phone(),new DriverEvidence(e.licenseNo(),e.licenseExpiresOn(),e.fileIds(),e.expectedTaskEndAt(),ids,e.masterLicenseFileId()));
+        }
+        return new Resources(v,d,value.maintenance());
+    }
+    /** 只复制已经由档案服务确认的图片，上传失败使业务事务整体失败。 */
+    public List<Long> populate(long dispatchId,String operator,Kind kind,long resourceId,List<Long> existing) {
+        if(existing!=null && !existing.isEmpty())return List.copyOf(existing);
+        var current=photos.current(kind,resourceId);
+        if(current.photo()==null)return List.of();
+        var source=photos.download(kind,resourceId,Long.parseLong(current.photo().fileId()));
+        var file=new SnapshotFile(source.metadata().fileName(),source.metadata().contentType(),source.content());
+        var copied=evidence.upload(dispatchId,kind==Kind.VEHICLE?DispatchEvidenceGateway.Kind.VEHICLE:DispatchEvidenceGateway.Kind.DRIVER_PHOTO,operator,file);
+        return List.of(copied.fileId());
+    }
+    /** 只供服务间复制已核验图片，不接受任意磁盘路径。 */
+    private record SnapshotFile(String filename,String contentType,byte[] bytes) implements MultipartFile {
+        /** 上传部件固定使用文件字段。 */
+        @Override public String getName() { return "file"; }
+        /** 保留已核验主档文件名。 */
+        @Override public String getOriginalFilename() { return filename; }
+        /** 沿用已核验图片类型。 */
+        @Override public String getContentType() { return contentType; }
+        /** 拒绝空图片。 */
+        @Override public boolean isEmpty() { return bytes.length==0; }
+        /** 使用实际读取的字节长度。 */
+        @Override public long getSize() { return bytes.length; }
+        /** 返回本次复制的图片内容。 */
+        @Override public byte[] getBytes() { return bytes; }
+        /** 提供上传流，不读取磁盘文件。 */
+        @Override public InputStream getInputStream() { return new ByteArrayInputStream(bytes); }
+        /** 实现文件上传协议要求的输出方法。 */
+        @Override public void transferTo(File dest) throws IOException { Files.write(dest.toPath(),bytes); }
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/transport/TransportTaskService.java

@@ -36,6 +36,7 @@ public class TransportTaskService {
     private final TripOperationsEvidenceGateway files;
     private final ObjectMapper json;
     @jakarta.annotation.Resource private TransportReviewPhotos reviewPhotos;
+    @jakarta.annotation.Resource private com.baiyue.lastleg.dispatch.service.DispatchMasterPhotoService masterPhotos;
     /** 复用已有资格、占用、原单及凭证能力。 */
     public TransportTaskService(DispatchAggregateRepository roots,TransportTaskRepository links,TransportTaskProjection projection,
         FleetTripRepository tripRepo,FleetTripService trips,FleetPickupService pickups,FleetPickupRepository pickupFacts,
@@ -119,6 +120,20 @@ public class TransportTaskService {
             if(!Objects.equals(trip.getRecordVersion(),request.recordVersion()) || request.dispatchRecordVersion()==null
                 || !Objects.equals(row.getRecordVersion(),request.dispatchRecordVersion()))throw conflict("排车或审核信息已变化，请刷新后重试");
             if(!"PLANNED".equals(trip.getStatus()) || pickups.tasks(trip.getTripNo()).stream().anyMatch(task->!"ASSIGNED".equals(task.status())))throw conflict("已取货的任务不能更换资源照片");
+            // 主档照片缺省带入本车；显式本趟照片仍由原归属校验复核。
+            var supplied=request.reviewPhotos();
+            var vehiclePhotos=masterPhotos.populate(row.getId(),operator,com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.Kind.VEHICLE,
+                request.vehicleId(),supplied==null?List.of():supplied.vehicleFileIds());
+            var driverPhotos=masterPhotos.populate(row.getId(),operator,com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.Kind.DRIVER,
+                request.driverId(),supplied==null?List.of():supplied.driverPhotoFileIds());
+            var license=request.masterLicenseFileId();
+            if(license==null && (supplied==null || supplied.licenseFileIds().isEmpty())) {
+                var driver=drivers.detail(request.driverId(),null);
+                if(driver.licenseFileId()!=null)license=Long.valueOf(driver.licenseFileId());
+            }
+            request=new TransportTaskModels.Assign(request.recordVersion(),request.vehicleId(),request.driverId(),request.reason(),
+                request.dispatchRecordVersion(),new com.baiyue.lastleg.dispatch.port.DispatchContracts.ReviewAttachments(
+                    vehiclePhotos,driverPhotos,supplied==null?List.of():supplied.licenseFileIds()),license);
             photos=reviewPhotos.validate(row,trip,request);
         }
         trips.assign(trip.getTripNo(),operator,new FleetTripModels.Assign(request.recordVersion(),request.vehicleId(),request.driverId(),request.reason()));

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/outsourcedbusiness/model/OutsourcedBusinessModels.java

@@ -27,7 +27,10 @@ public final class OutsourcedBusinessModels {
         /** 固定外配入口不接收浏览器作用域或其他协议字段。 */
         @JsonAnySetter public void unsupported(String field,Object value){throw unsupportedField(field);}
     }
-    public record BindPhoto(@NotBlank String recordVersion,@NotBlank @Size(min=8,max=128) String idempotencyKey,@NotBlank String fileId) {
+    public record BindPhoto(@NotBlank String recordVersion,@NotBlank @Size(min=8,max=128) String idempotencyKey,@NotBlank String fileId,
+        @Pattern(regexp="[1-9][0-9]*") String replaceFileId) {
+        /** 未指定替换目标时追加装车照片。 */
+        public BindPhoto(String recordVersion,String idempotencyKey,String fileId) { this(recordVersion,idempotencyKey,fileId,null); }
         /** 绑定只接受原版本、原键和File编号，不能提交车辆归属。 */
         @JsonAnySetter public void unsupported(String field,Object value){throw unsupportedField(field);}
     }

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/outsourcedbusiness/service/OutsourcedBusinessService.java

@@ -53,7 +53,7 @@ public class OutsourcedBusinessService {
     /** 原File编号由共享绑定事务校验，不创建第二份附件或写原主单。 */
     public Detail bind(OwnedBusinessModels.Actor actor,String number,PhotoSlot slot,BindPhoto request) {
         if(request==null)throw bad("照片绑定请求缺失");
-        return detail(photos.bind(actor,number,slot(slot),new OwnedBusinessModels.BindPhoto(request.recordVersion(),request.idempotencyKey(),request.fileId()),SCOPE));
+        return detail(photos.bind(actor,number,slot(slot),new OwnedBusinessModels.BindPhoto(request.recordVersion(),request.idempotencyKey(),request.fileId(),request.replaceFileId()),SCOPE));
     }
     /** 当前或历史引用读取始终限定原车、照片框和外配权限。 */
     public OwnedBusinessPhotoService.Download content(OwnedBusinessModels.Actor actor,String number,PhotoSlot slot,long fileId,Long revision) {

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/model/OwnedBusinessModels.java

@@ -34,7 +34,11 @@ public final class OwnedBusinessModels {
         @NotBlank @Size(min=8,max=128) String idempotencyKey,@NotNull @Valid Operations operations,
         @Size(max=1000) String reason) {}
     public record BindPhoto(@NotBlank String recordVersion,
-        @NotBlank @Size(min=8,max=128) String idempotencyKey,@NotBlank String fileId) {}
+        @NotBlank @Size(min=8,max=128) String idempotencyKey,@NotBlank String fileId,
+        @Pattern(regexp="[1-9][0-9]*") String replaceFileId) {
+        /** 未指定替换目标时追加装车照片。 */
+        public BindPhoto(String recordVersion,String idempotencyKey,String fileId) { this(recordVersion,idempotencyKey,fileId,null); }
+    }
     public record Gate(boolean allowed,String blockReason) {}
     public record Actions(Gate edit,Gate upload) {}
     public record Origin(String warehouseId,String warehouseCode,String warehouseName) {}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/port/DispatchLoadingPhotoPort.java

@@ -8,7 +8,11 @@ import org.springframework.web.multipart.MultipartFile;
 public interface DispatchLoadingPhotoPort {
     enum Slot { LOADING_SCENE, LOADING_LIST, PRE_DEPARTURE_CHECK, DRIVER_LICENSE, RECEIPT }
     record Photo(Slot slot,String category,String fileId,String fileName,String contentType,String sizeBytes,String uploadedAt,String savedAt) {}
-    record BindPhoto(@NotBlank String recordVersion,@NotBlank @Size(min=8,max=128) String idempotencyKey,@NotBlank String fileId) {}
+    record BindPhoto(@NotBlank String recordVersion,@NotBlank @Size(min=8,max=128) String idempotencyKey,@NotBlank String fileId,
+        @Pattern(regexp="[1-9][0-9]*") String replaceFileId) {
+        /** 未指定替换目标时追加照片，每类最多五张。 */
+        public BindPhoto(String recordVersion,String idempotencyKey,String fileId) { this(recordVersion,idempotencyKey,fileId,null); }
+    }
     record State(String recordVersion,List<Photo> photos) {}
     record Documents(String dispatchNo,String recordVersion,String dispatchRecordVersion,String stage,boolean editable,boolean complete,List<Photo> photos) {}
     record Download(Photo photo,byte[] content) {}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/service/DispatchLoadingPhotoAdapter.java

@@ -77,9 +77,9 @@ public class DispatchLoadingPhotoAdapter implements DispatchLoadingPhotoPort {
         seed.setCreatedBy(operator);seed.setUpdatedBy(operator);seed.setCreatedAt(codec.utc(Instant.now()));seed.setUpdatedAt(seed.getCreatedAt());
         var row=repository.lock(seed);
         if(row==null || row.getRecordVersion()==null || row.getRecordVersion()!=version)throw conflict("装车资料已被其他操作更新，请刷新后核对");
-        var photos=new EnumMap<PhotoSlot,OwnedBusinessModels.Photo>(PhotoSlot.class);for(var p:projection.photos(row))photos.put(p.slot(),p);
-        photos.put(originalSlot,new OwnedBusinessModels.Photo(originalSlot,originalSlot.category(),verified.fileId(),verified.fileName(),verified.contentType(),verified.sizeBytes(),verified.uploadedAt(),Instant.now().toString()));
-        row.setPhotosJson(codec.write(List.copyOf(photos.values())));row.setRecordVersion(Math.addExact(version,1));row.setUpdatedBy(operator);row.setUpdatedAt(codec.utc(Instant.now()));
+        var saved=new OwnedBusinessModels.Photo(originalSlot,originalSlot.category(),verified.fileId(),verified.fileName(),verified.contentType(),verified.sizeBytes(),verified.uploadedAt(),Instant.now().toString());
+        var photos=OwnedBusinessPhotoBindings.bind(projection.photos(row),saved,request.replaceFileId());
+        row.setPhotosJson(codec.write(photos));row.setRecordVersion(Math.addExact(version,1));row.setUpdatedBy(operator);row.setUpdatedAt(codec.utc(Instant.now()));
         if(repository.update(row,version)!=1)throw conflict("装车资料版本竞争失败");
         var history=new OwnedBusinessRows.History();history.setId(IdWorker.getId());history.setDispatchId(id);history.setRecordVersion(row.getRecordVersion());
         history.setAction("BIND_LOADING_DOCUMENT");history.setOperatorId(operator);history.setReason("保存装车照片 "+(slot.ordinal()+1));history.setOccurredAt(row.getUpdatedAt());
@@ -104,6 +104,7 @@ public class DispatchLoadingPhotoAdapter implements DispatchLoadingPhotoPort {
     private void validate(Slot slot,BindPhoto request) {
         slot(slot);if(request==null)throw bad("照片绑定请求缺失");codec.key(request.idempotencyKey());codec.version(request.recordVersion());
         if(codec.version(request.fileId())<=0)throw bad("文件编号无效");
+        if(request.replaceFileId()!=null && codec.version(request.replaceFileId())<=0)throw bad("待替换文件编号无效");
     }
     /** 账本只消费可信操作者；平台/PDA权限在排车入口复核。 */
     private OwnedBusinessModels.Actor operator(String operator){return new OwnedBusinessModels.Actor(operator,operator,Set.of());}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/service/OwnedBusinessPhotoBindings.java

@@ -0,0 +1,33 @@
+package com.baiyue.lastleg.fleet.ownedbusiness.service;
+
+import com.baiyue.lastleg.fleet.ownedbusiness.model.OwnedBusinessModels.Photo;
+import java.util.ArrayList;
+import java.util.List;
+import static com.baiyue.lastleg.fleet.ownedbusiness.service.OwnedBusinessSupport.*;
+
+/** 照片按文件追加或精确替换，禁止按类别压缩而丢失其他已保存图片。 */
+final class OwnedBusinessPhotoBindings {
+    /** 工具类仅提供照片引用合并。 */
+    private OwnedBusinessPhotoBindings() {}
+    /** 装车每类最多五张；油耗仍为单张，替换目标必须在当前同类引用中。 */
+    static List<Photo> bind(List<Photo> existing,Photo photo,String replaceFileId) {
+        var result=new ArrayList<>(existing);
+        // 油耗沿原单张替换协议，不能因装车改多图而改变其他入口的保存行为。
+        if(replaceFileId==null && "FUEL".equals(photo.category()))
+            replaceFileId=existing.stream().filter(p->p.slot()==photo.slot()).map(Photo::fileId).findFirst().orElse(null);
+        if(replaceFileId!=null) {
+            int index=-1;
+            for(int i=0;i<result.size();i++)if(result.get(i).slot()==photo.slot() && result.get(i).fileId().equals(replaceFileId))index=i;
+            if(index<0)throw conflict("待替换照片已变化，请刷新后核对");
+            result.remove(index);
+            if(result.stream().anyMatch(p->p.fileId().equals(photo.fileId())))throw bad("照片已绑定，不能重复保存");
+            result.add(index,photo);
+        } else {
+            if(result.stream().anyMatch(p->p.fileId().equals(photo.fileId())))throw bad("照片已绑定，不能重复保存");
+            int limit="LOADING".equals(photo.category())?5:1;
+            if(result.stream().filter(p->p.slot()==photo.slot()).count()>=limit)throw conflict("该类照片最多"+limit+"张，请替换已有照片");
+            result.add(photo);
+        }
+        return List.copyOf(result);
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/ownedbusiness/service/OwnedBusinessRecordService.java

@@ -69,20 +69,20 @@ public class OwnedBusinessRecordService {
         var row=lock(source,actor);old=commands.existing(source.getId(),request.idempotencyKey(),actor);
         if(old!=null){commands.same(old,"BIND_PHOTO",version,identity);return result(old);}
         requireVersion(row,version);
-        var photos=new EnumMap<PhotoSlot,Photo>(PhotoSlot.class);for(var p:projection.photos(row))photos.put(p.slot(),p);
-        photos.put(slot,new Photo(slot,slot.category(),verified.fileId(),verified.fileName(),verified.contentType(),
-            verified.sizeBytes(),verified.uploadedAt(),Instant.now().toString()));
-        row.setPhotosJson(codec.write(List.copyOf(photos.values())));
+        var saved=new Photo(slot,slot.category(),verified.fileId(),verified.fileName(),verified.contentType(),
+            verified.sizeBytes(),verified.uploadedAt(),Instant.now().toString());
+        var photos=OwnedBusinessPhotoBindings.bind(projection.photos(row),saved,request.replaceFileId());
+        row.setPhotosJson(codec.write(photos));
         return commit(source,row,actor,version,"BIND_PHOTO",request.idempotencyKey(),identity,photoReason(slot),scope);
     }
     /** 操作记录使用准确中文槽位，不向用户展示内部枚举。 */
     private String photoReason(PhotoSlot slot) {
         return switch(slot) {
-            case LOADING_SCENE -> "保存装车现场照片";
-            case LOADING_LIST -> "保存装车清单照片";
-            case PRE_DEPARTURE_CHECK -> "保存出车前检查照片";
-            case DRIVER_LICENSE -> "保存驾驶证附件照片";
-            case RECEIPT -> "保存签收凭证照片";
+            case LOADING_SCENE -> "保存司机驾驶证照片";
+            case LOADING_LIST -> "保存车牌照片";
+            case PRE_DEPARTURE_CHECK -> "保存装车完成照片";
+            case DRIVER_LICENSE -> "保存封车照片";
+            case RECEIPT -> "保存BOL司机签字照片";
             case FUEL_START -> "保存起始油耗表盘照片";
             case FUEL_END -> "保存结束油耗表盘照片";
         };

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/photo/FleetResourcePhotoGateway.java

@@ -0,0 +1,14 @@
+package com.baiyue.lastleg.fleet.photo;
+
+import org.springframework.web.multipart.MultipartFile;
+import static com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.*;
+
+/** File按平台、档案类型、资源身份及文件身份隔离照片。 */
+public interface FleetResourcePhotoGateway {
+    /** 上传平台所属的档案照片。 */
+    Photo upload(Kind kind, long id, String operator, MultipartFile file);
+    /** 核验档案类型、资源身份和文件身份。 */
+    Photo metadata(Kind kind, long id, long file);
+    /** 读取已核验归属的图片内容。 */
+    byte[] download(Kind kind, long id, long file);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/photo/FleetResourcePhotoMapper.java

@@ -0,0 +1,17 @@
+package com.baiyue.lastleg.fleet.photo;
+
+import org.apache.ibatis.annotations.*;
+
+/** 仅操作档案照片版本表；资源有效性通过所属领域服务核验。 */
+@Mapper
+public interface FleetResourcePhotoMapper {
+    /** 读取同一档案的最大照片版本。 */
+    @Select("SELECT * FROM ll_fleet_resource_photo WHERE resource_kind=#{kind} AND resource_id=#{id} ORDER BY record_version DESC LIMIT 1")
+    FleetResourcePhotoModels.Stored current(@Param("kind") String kind, @Param("id") long id);
+    /** 按档案与文件复合身份查询历史引用。 */
+    @Select("SELECT * FROM ll_fleet_resource_photo WHERE resource_kind=#{kind} AND resource_id=#{id} AND file_id=#{file} LIMIT 1")
+    FleetResourcePhotoModels.Stored file(@Param("kind") String kind, @Param("id") long id, @Param("file") long file);
+    /** 追加不可变照片版本，数据库拒绝重复资源版本。 */
+    @Insert("INSERT INTO ll_fleet_resource_photo(resource_kind,resource_id,record_version,file_id,file_name,content_type,size_bytes,created_by,created_at) VALUES(#{resourceKind},#{resourceId},#{recordVersion},#{fileId},#{fileName},#{contentType},#{sizeBytes},#{createdBy},#{createdAt})")
+    int insert(FleetResourcePhotoModels.Stored row);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/photo/FleetResourcePhotoModels.java

@@ -0,0 +1,15 @@
+package com.baiyue.lastleg.fleet.photo;
+
+import java.time.LocalDateTime;
+
+/** 档案照片独立版本化，历史图片不覆盖且不改变驾驶证审核结论。 */
+public final class FleetResourcePhotoModels {
+    /** 仅承载照片接口与持久化数据。 */
+    private FleetResourcePhotoModels() { }
+    public enum Kind { VEHICLE, DRIVER }
+    public record Photo(String fileId, String fileName, String contentType, long sizeBytes) { }
+    public record Detail(long recordVersion, Photo photo) { }
+    public record Stored(String resourceKind, long resourceId, long recordVersion, long fileId,
+                         String fileName, String contentType, long sizeBytes, String createdBy, LocalDateTime createdAt) { }
+    public record Download(Photo metadata, byte[] content) { }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/photo/FleetResourcePhotoRepository.java

@@ -0,0 +1,18 @@
+package com.baiyue.lastleg.fleet.photo;
+
+import org.springframework.stereotype.Repository;
+import static com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.*;
+
+/** 同一资源版本唯一，阻止并发替换静默覆盖。 */
+@Repository
+public class FleetResourcePhotoRepository {
+    private final FleetResourcePhotoMapper mapper;
+    /** 注入唯一照片Mapper。 */
+    public FleetResourcePhotoRepository(FleetResourcePhotoMapper mapper) { this.mapper = mapper; }
+    /** 读取指定档案的最新照片版本。 */
+    public Stored current(Kind kind, long id) { return mapper.current(kind.name(), id); }
+    /** 按档案及文件身份读取不可变历史引用。 */
+    public Stored file(Kind kind, long id, long file) { return mapper.file(kind.name(), id, file); }
+    /** 追加新版本，唯一键负责并发冲突保护。 */
+    public void append(Stored row) { if (mapper.insert(row) != 1) throw new IllegalStateException("档案照片未保存"); }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/photo/FleetResourcePhotoService.java

@@ -0,0 +1,63 @@
+package com.baiyue.lastleg.fleet.photo;
+
+import com.baiyue.lastleg.fleet.driver.DriverService;
+import com.baiyue.lastleg.masterdata.vehicle.application.port.out.VehicleRepository;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.multipart.MultipartFile;
+import org.springframework.web.server.ResponseStatusException;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import static com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.*;
+
+/** 管理可重复用于排车的车辆及司机照片，排车另存当趟不可变副本。 */
+@Service
+public class FleetResourcePhotoService implements com.baiyue.lastleg.fleet.photo.port.FleetResourcePhotoPort {
+    private final FleetResourcePhotoRepository repository;
+    private final FleetResourcePhotoGateway files;
+    private final VehicleRepository vehicles;
+    private final DriverService drivers;
+    /** 通过资源领域入口确认身份，所有照片版本经Repository保存。 */
+    public FleetResourcePhotoService(FleetResourcePhotoRepository repository, FleetResourcePhotoGateway files,
+                                     VehicleRepository vehicles, DriverService drivers) {
+        this.repository=repository; this.files=files; this.vehicles=vehicles; this.drivers=drivers;
+    }
+    /** 先确认资源存在，空照片是明确的可补齐状态。 */
+    public Detail current(Kind kind, long id) {
+        requireResource(kind,id);
+        var row=repository.current(kind,id);
+        return row==null ? new Detail(0,null) : new Detail(row.recordVersion(),photo(row));
+    }
+    /** 版本随照片独立递增；失败保留旧照片及历史。 */
+    @Transactional
+    public Detail upload(Kind kind,long id,long version,String operator,MultipartFile file) {
+        var current=current(kind,id);
+        if(version!=current.recordVersion())throw conflict();
+        var saved=files.upload(kind,id,operator,file);
+        try {
+            repository.append(new Stored(kind.name(),id,version+1,Long.parseLong(saved.fileId()),saved.fileName(),
+                saved.contentType(),saved.sizeBytes(),operator,LocalDateTime.now(ZoneOffset.UTC)));
+        } catch(DuplicateKeyException error) { throw conflict(); }
+        return new Detail(version+1,saved);
+    }
+    /** 只允许读取本档案已关联的当前或历史图片。 */
+    public Download download(Kind kind,long id,long file) {
+        requireResource(kind,id);
+        if(repository.file(kind,id,file)==null)throw new ResponseStatusException(HttpStatus.NOT_FOUND,"档案照片不存在");
+        var metadata=files.metadata(kind,id,file);
+        var bytes=files.download(kind,id,file);
+        if(bytes.length!=metadata.sizeBytes())throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE,"档案照片内容不完整");
+        return new Download(metadata,bytes);
+    }
+    /** 车辆及司机身份必须真实存在，不能按自由文本上传。 */
+    private void requireResource(Kind kind,long id) {
+        if(id<=0)throw new ResponseStatusException(HttpStatus.BAD_REQUEST,"档案身份无效");
+        if(kind==Kind.VEHICLE)vehicles.findById(id).orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND,"车辆档案不存在")); else drivers.detail(id,null);
+    }
+    /** 转换为不暴露持久化信息的文件元数据。 */
+    private static Photo photo(Stored row) { return new Photo(Long.toString(row.fileId()),row.fileName(),row.contentType(),row.sizeBytes()); }
+    /** 冲突要求重读当前照片，不自动覆盖他人的修改。 */
+    private static ResponseStatusException conflict() { return new ResponseStatusException(HttpStatus.CONFLICT,"档案照片已变化，请重新读取后上传"); }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/photo/HttpFleetResourcePhotoGateway.java

@@ -0,0 +1,83 @@
+package com.baiyue.lastleg.fleet.photo;
+
+import static com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.*;
+
+import com.baiyue.lastleg.config.LastlegRestClientFactory;
+import com.baiyue.lastleg.config.LastlegRestClientProperties;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.core.io.ByteArrayResource;
+import org.springframework.http.*;
+import org.springframework.http.client.MultipartBodyBuilder;
+import org.springframework.stereotype.Component;
+import org.springframework.web.client.RestClient;
+import org.springframework.web.multipart.MultipartFile;
+import org.springframework.web.server.ResponseStatusException;
+import java.io.IOException;
+import java.util.Objects;
+import java.util.Set;
+
+@Component
+public class HttpFleetResourcePhotoGateway implements FleetResourcePhotoGateway {
+    private static final String PATH = "/internal/file/v1/business-files/0/{type}/{record}";
+    private static final long MAX_SIZE = 10L * 1024 * 1024;
+    private final RestClient client;
+    private final String token;
+    /** 使用统一内部服务客户端与File通信。 */
+    public HttpFleetResourcePhotoGateway(RestClient.Builder builder, LastlegRestClientFactory factory, LastlegRestClientProperties properties,
+            @Value("${baiyue.clients.file.url:http://127.0.0.1:9205}") String baseUrl,
+            @Value("${baiyue.security.internal-service-token:}") String token) {
+        client = factory.build(builder, baseUrl, properties.getCustomerVisitFile()); this.token = token;
+    }
+    /** 只接受非空图片，通过内部File上传并校验归属。 */
+    @Override public Photo upload(Kind kind, long recordId, String operatorId, MultipartFile file) {
+        if (file == null || file.isEmpty() || file.getSize() > MAX_SIZE || !image(file.getContentType())) throw bad("档案照片须为非空 JPG 或 PNG，最大 10MiB");
+        var body = new MultipartBodyBuilder();
+        try { body.part("file", new ByteArrayResource(file.getBytes()) {
+            @Override public String getFilename() { return file.getOriginalFilename(); }
+        }).contentType(MediaType.parseMediaType(file.getContentType())); }
+        catch (IOException error) { throw bad("无法读取档案照片"); }
+        var result = client.post().uri(PATH, type(kind), recordId).header("X-Internal-Service-Token", token).header("X-Operator-Id", operatorId)
+            .contentType(MediaType.MULTIPART_FORM_DATA).body(body.build()).retrieve()
+            .onStatus(HttpStatusCode::isError, (request, response) -> { throw unavailable(response.getStatusCode()); }).body(Envelope.class);
+        return verified(result, kind, recordId, null);
+    }
+    /** 逐文件核验平台及当前档案复合归属。 */
+    @Override public Photo metadata(Kind kind, long recordId, long fileId) {
+        return verified(client.get().uri(PATH + "/{file}", type(kind), recordId, fileId).header("X-Internal-Service-Token", token).retrieve()
+            .onStatus(HttpStatusCode::isError, (request, response) -> { throw unavailable(response.getStatusCode()); }).body(Envelope.class), kind, recordId, fileId);
+    }
+    /** 按原档案身份读取图片，不返回匿名URL。 */
+    @Override public byte[] download(Kind kind, long recordId, long fileId) {
+        var response = client.get().uri(PATH + "/{file}/content", type(kind), recordId, fileId).header("X-Internal-Service-Token", token).retrieve()
+            .onStatus(HttpStatusCode::isError, (request, result) -> { throw unavailable(result.getStatusCode()); }).toEntity(byte[].class);
+        return imageContent(response);
+    }
+    /** 拒绝错误正文、空文件和超过上限的内容。 */
+    static byte[] imageContent(ResponseEntity<byte[]> response) {
+        byte[] content = response.getBody();
+        if (content == null || content.length == 0 || content.length > MAX_SIZE
+            || !image(Objects.toString(response.getHeaders().getContentType(), ""))) throw unavailable(HttpStatus.SERVICE_UNAVAILABLE);
+        return content;
+    }
+    /** 验证File返回的身份、类型及字节数。 */
+    static Photo verified(Envelope result, Kind kind, long recordId, Long fileId) {
+        if (result == null || !"200".equals(result.code())) throw unavailable(HttpStatus.SERVICE_UNAVAILABLE);
+        var data = result.data();
+        if (data == null || data.fileId() == null || data.fileId() <= 0 || !Objects.equals(data.tenantId(), 0L)
+            || !type(kind).equals(data.businessType()) || !Long.toString(recordId).equals(data.businessId())
+            || (fileId != null && !fileId.equals(data.fileId())) || data.fileName() == null || data.fileName().isBlank()
+            || !image(data.contentType()) || data.sizeBytes() == null || data.sizeBytes() <= 0 || data.sizeBytes() > MAX_SIZE)
+            throw bad("文件不属于当前资源档案或不是有效照片");
+        return new Photo(data.fileId().toString(), data.fileName(), data.contentType(), data.sizeBytes());
+    }
+    /** 档案类型不可由调用方拼接任意文件业务类别。 */
+    private static String type(Kind kind) { return kind == Kind.VEHICLE ? "FLEET_VEHICLE_PHOTO" : "FLEET_DRIVER_PHOTO"; }
+    /** 车辆和司机本人照片仅允许JPG及PNG。 */
+    private static boolean image(String type) { return Set.of("image/jpeg", "image/png").contains(Objects.toString(type, "")); }
+    /** 返回可修正的附件业务错误。 */
+    private static ResponseStatusException bad(String message) { return new ResponseStatusException(HttpStatus.BAD_REQUEST, message); }
+    /** 外部失败保留诊断，不伪装为成功。 */
+    private static ResponseStatusException unavailable(HttpStatusCode status) { return new ResponseStatusException(status.is4xxClientError() ? HttpStatus.BAD_REQUEST : HttpStatus.SERVICE_UNAVAILABLE, "档案照片不可用或归属校验失败"); }
+    record Envelope(String code, Metadata data) { }
+    record Metadata(Long fileId, Long tenantId, String businessType, String businessId, String fileName, String contentType, Long sizeBytes) { }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/photo/PlatformFleetResourcePhotoController.java

@@ -0,0 +1,46 @@
+package com.baiyue.lastleg.fleet.photo;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import jakarta.validation.constraints.Min;
+import org.springframework.http.*;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+import java.nio.charset.StandardCharsets;
+import static com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.*;
+
+/** 复用车辆编辑、司机上传及各自列表权限，不扩大跨档案访问域。 */
+@RestController
+@Validated
+@RequestMapping("/api/platform/v1/last-leg/fleet/resource-photos/{kind}/{id}")
+public class PlatformFleetResourcePhotoController {
+    private final FleetResourcePhotoService service;
+    /** 注入档案照片应用服务。 */
+    public PlatformFleetResourcePhotoController(FleetResourcePhotoService service) { this.service=service; }
+    /** 列表权限读取档案照片及版本。 */
+    @GetMapping
+    @PreAuthorize("hasAuthority('platform:overseas-master-data:' + #kind.name().toLowerCase() + ':list')")
+    public ApiResponse<Detail> current(@PathVariable Kind kind,@PathVariable @Min(1) long id) {
+        return ApiResponse.success(service.current(kind,id));
+    }
+    /** 按资源类型校验上传权限并提交当前版本。 */
+    @PostMapping(consumes=MediaType.MULTIPART_FORM_DATA_VALUE)
+    @PreAuthorize("(#kind.name() == 'VEHICLE' and hasAuthority('platform:overseas-master-data:vehicle:edit')) or (#kind.name() == 'DRIVER' and hasAuthority('platform:overseas-master-data:driver:upload'))")
+    public ApiResponse<Detail> upload(@PathVariable Kind kind,@PathVariable @Min(1) long id,
+            @RequestParam @Min(0) long recordVersion,@RequestPart("file") MultipartFile file,
+            @AuthenticationPrincipal AuthenticatedUser user) {
+        return ApiResponse.success(service.upload(kind,id,recordVersion,user.userId().toString(),file));
+    }
+    /** 原档案读取权限包含其已关联的历史图片。 */
+    @GetMapping("/{fileId}/content")
+    @PreAuthorize("hasAuthority('platform:overseas-master-data:' + #kind.name().toLowerCase() + ':list')")
+    public ResponseEntity<byte[]> download(@PathVariable Kind kind,@PathVariable @Min(1) long id,@PathVariable @Min(1) long fileId) {
+        var file=service.download(kind,id,fileId);
+        return ResponseEntity.ok().cacheControl(CacheControl.noStore()).header("X-Content-Type-Options","nosniff")
+            .header(HttpHeaders.CONTENT_DISPOSITION,ContentDisposition.attachment().filename(file.metadata().fileName(),StandardCharsets.UTF_8).build().toString())
+            .contentType(MediaType.parseMediaType(file.metadata().contentType())).body(file.content());
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/fleet/photo/port/FleetResourcePhotoPort.java

@@ -0,0 +1,11 @@
+package com.baiyue.lastleg.fleet.photo.port;
+
+import com.baiyue.lastleg.fleet.photo.FleetResourcePhotoModels.*;
+
+/** 排车仅通过此只读应用端口获取档案照片，不访问照片持久化或改写档案。 */
+public interface FleetResourcePhotoPort {
+    /** 返回当前档案照片及其独立版本，缺失时photo为空。 */
+    Detail current(Kind kind,long id);
+    /** 读取已经关联本档案的图片并复验平台文件归属。 */
+    Download download(Kind kind,long id,long file);
+}