From 4d7ea28a61d11a868a7fc5bae0006f6af84c2399 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Tue, 1 Sep 2026 15:18:18 +0800 Subject: [PATCH] feat(firstleg): capture container number at pickup --- .../firstleg/dto/TruckAppointmentDtos.java | 2 +- .../mapper/TruckAppointmentMapper.java | 1 + .../TruckAppointmentRepository.java | 2 +- .../service/TruckAppointmentService.java | 7 +- .../openapi/truck-appointments-v1.yaml | 9 +- ...ruckAppointmentControllerContractTest.java | 2 +- .../TruckAppointmentMapperContractTest.java | 3 + .../service/TruckAppointmentServiceTest.java | 205 ++++++++++++++++-- 8 files changed, 202 insertions(+), 29 deletions(-) diff --git a/firstleg/src/main/java/com/baiyue/firstleg/dto/TruckAppointmentDtos.java b/firstleg/src/main/java/com/baiyue/firstleg/dto/TruckAppointmentDtos.java index 43e6ae875..62782b7ba 100644 --- a/firstleg/src/main/java/com/baiyue/firstleg/dto/TruckAppointmentDtos.java +++ b/firstleg/src/main/java/com/baiyue/firstleg/dto/TruckAppointmentDtos.java @@ -3,6 +3,6 @@ import jakarta.validation.constraints.*; import java.math.BigDecimal; import jav public final class TruckAppointmentDtos { private TruckAppointmentDtos(){} public record Query(@Size(max=64) String keyword, com.baiyue.firstleg.domain.TruckAppointmentStatus status, @Positive Long containerBookingId, @Min(1) long page, @Min(1) @Max(200) long size){ public Query{if(page==0)page=1;if(size==0)size=20;} } public record SaveRequest(@Positive Long outboundOrderId,@NotNull @Positive Long oceanBookingId,@NotNull @Positive Long containerBookingId,@Positive Long loadingPlanId,@Positive Long warehouseId,@NotNull @Positive Long carrierId,@Size(max=128) String carrierName,@Size(max=128) String billOfLadingNo,@Size(max=64) String fleetContact,@Size(max=32) String fleetPhone,@Size(max=64) String driverName,@Size(max=32) String driverPhone,@Size(max=32) String driverIdCard,@Size(max=32) String vehicleNo,@Size(max=128) String storeName,@Size(max=64) String storeContact,@Size(max=32) String storePhone,@Size(max=255) String storeAddress,@Size(max=64) String storeCity,@Size(max=16) String storeZipcode,@PositiveOrZero Integer packageCount,@DecimalMin("0") BigDecimal grossWeightKg,@DecimalMin("0") BigDecimal volumeCbm,@PositiveOrZero Integer palletCount,@Size(max=255) String poNo,@NotNull LocalDateTime plannedLoadingAt,@PositiveOrZero Integer transitMinutes,@DecimalMin("0") BigDecimal payableAmount,@Pattern(regexp="RMB|USD") String currency,@Size(max=1000) String remark,@NotNull @PositiveOrZero Integer expectedVersion){} - public record ActionRequest(@NotNull @PositiveOrZero Integer expectedVersion,@Size(max=500) String reason){} + public record ActionRequest(@NotNull @PositiveOrZero Integer expectedVersion,@Size(max=500) String reason,@Size(max=32) String containerNo){} public record AttachmentRequest(@NotNull @Positive Long fileId,@NotBlank @Pattern(regexp="DISPATCH_ORDER|DRIVER_DOCUMENT|VEHICLE_DOCUMENT|OTHER") String attachmentType,@Size(max=255) String fileName,@Size(max=128) String fileHash){ } } diff --git a/firstleg/src/main/java/com/baiyue/firstleg/mapper/TruckAppointmentMapper.java b/firstleg/src/main/java/com/baiyue/firstleg/mapper/TruckAppointmentMapper.java index b2139d8f5..68757f92d 100644 --- a/firstleg/src/main/java/com/baiyue/firstleg/mapper/TruckAppointmentMapper.java +++ b/firstleg/src/main/java/com/baiyue/firstleg/mapper/TruckAppointmentMapper.java @@ -6,6 +6,7 @@ import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.baomidou.myba @Select("") Page page(Page p,@Param("q") Query q); @Update("UPDATE fl_truck_appointment SET status=#{toStatus}, actual_arrived_warehouse_at=CASE WHEN #{toStatus}='ARRIVED_WAREHOUSE' THEN CURRENT_TIMESTAMP(3) ELSE actual_arrived_warehouse_at END, actual_loading_at=CASE WHEN #{toStatus}='LOADING' THEN CURRENT_TIMESTAMP(3) ELSE actual_loading_at END, actual_departed_at=CASE WHEN #{toStatus}='DEPARTED' THEN CURRENT_TIMESTAMP(3) ELSE actual_departed_at END, revision=revision+1, version=version+1, updated_at=CURRENT_TIMESTAMP(3) WHERE id=#{id} AND status=#{fromStatus} AND version=#{version}") int transition(@Param("id") long id,@Param("fromStatus") String from,@Param("toStatus") String to,@Param("version") int version); @Update("UPDATE fl_truck_appointment SET status='DISPATCHED',bill_of_lading_no=#{billOfLadingNo},revision=revision+1,version=version+1,updated_at=CURRENT_TIMESTAMP(3) WHERE id=#{id} AND status=#{fromStatus} AND version=#{version}") int dispatch(@Param("id") long id,@Param("fromStatus") String fromStatus,@Param("billOfLadingNo") String billOfLadingNo,@Param("version") int version); + @Update("UPDATE fl_container_booking SET container_no=#{containerNo},updated_by=#{operatorId},updated_by_name=#{operatorName},updated_at=CURRENT_TIMESTAMP(3),version=version+1 WHERE id=#{containerBookingId} AND record_status='ACTIVE' AND container_no IS NULL") int bindContainerNoForPickup(@Param("containerBookingId") long containerBookingId,@Param("containerNo") String containerNo,@Param("operatorId") long operatorId,@Param("operatorName") String operatorName); @Update("UPDATE fl_truck_appointment SET status='COMPLETED',actual_loading_at=COALESCE(actual_loading_at,CURRENT_TIMESTAMP(3)),revision=revision+1,version=version+1,updated_at=CURRENT_TIMESTAMP(3) WHERE id=#{id} AND status=#{fromStatus} AND version=#{version}") int completeLoadingFromPda(@Param("id") long id,@Param("fromStatus") String fromStatus,@Param("version") int version); @Update("UPDATE fl_truck_appointment SET planned_loading_at=#{at}, revision=revision+1, version=version+1, status='RESCHEDULED', remark=#{reason}, updated_at=CURRENT_TIMESTAMP(3) WHERE id=#{id} AND version=#{version}") int reschedule(@Param("id") long id,@Param("at") java.time.LocalDateTime at,@Param("reason") String reason,@Param("version") int version); @Update("UPDATE fl_truck_appointment SET outbound_order_id=#{e.outboundOrderId},ocean_booking_id=#{e.oceanBookingId},container_booking_id=#{e.containerBookingId},loading_plan_id=#{e.loadingPlanId},warehouse_id=#{e.warehouseId},carrier_id=#{e.carrierId},carrier_name=#{e.carrierName},bill_of_lading_no=#{e.billOfLadingNo},fleet_contact=#{e.fleetContact},fleet_phone=#{e.fleetPhone},driver_name=#{e.driverName},driver_phone=#{e.driverPhone},driver_id_card=#{e.driverIdCard},vehicle_no=#{e.vehicleNo},store_name=#{e.storeName},store_contact=#{e.storeContact},store_phone=#{e.storePhone},store_address=#{e.storeAddress},store_city=#{e.storeCity},store_zipcode=#{e.storeZipcode},package_count=#{e.packageCount},gross_weight_kg=#{e.grossWeightKg},volume_cbm=#{e.volumeCbm},pallet_count=#{e.palletCount},po_no=#{e.poNo},planned_loading_at=#{e.plannedLoadingAt},transit_minutes=#{e.transitMinutes},payable_amount=#{e.payableAmount},currency=#{e.currency},remark=#{e.remark},version=version+1,revision=revision+1,updated_at=CURRENT_TIMESTAMP(3) WHERE id=#{e.id} AND version=#{version}") int updateEdit(@Param("e") TruckAppointmentEntity e,@Param("version") int version); diff --git a/firstleg/src/main/java/com/baiyue/firstleg/repository/TruckAppointmentRepository.java b/firstleg/src/main/java/com/baiyue/firstleg/repository/TruckAppointmentRepository.java index 4bbcce2df..a1ce74211 100644 --- a/firstleg/src/main/java/com/baiyue/firstleg/repository/TruckAppointmentRepository.java +++ b/firstleg/src/main/java/com/baiyue/firstleg/repository/TruckAppointmentRepository.java @@ -1,7 +1,7 @@ package com.baiyue.firstleg.repository; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baiyue.common.core.api.PageResult; import com.baiyue.firstleg.dto.TruckAppointmentDtos.Query; import com.baiyue.firstleg.entity.*; import com.baiyue.firstleg.mapper.*; import jakarta.annotation.Resource; import org.springframework.stereotype.Repository; @Repository public class TruckAppointmentRepository { @Resource TruckAppointmentMapper mapper; @Resource TruckAppointmentHistoryMapper history; @Resource TruckAppointmentAttachmentMapper attachments; @Resource TruckAppointmentOperationMapper operations; - public PageResult page(Query q){return PageResult.from(mapper.page(new Page<>(q.page(),q.size()),q));} public TruckAppointmentEntity find(long id){return mapper.selectById(id);} public void insert(TruckAppointmentEntity e){mapper.insert(e);} public int transition(long id,String from,String to,int v){return mapper.transition(id,from,to,v);} public int dispatch(long id,String from,String billOfLadingNo,int v){return mapper.dispatch(id,from,billOfLadingNo,v);} public int reschedule(long id,java.time.LocalDateTime at,String reason,int v){return mapper.reschedule(id,at,reason,v);} public void history(TruckAppointmentHistoryEntity e){history.insert(e);} public void operation(TruckAppointmentOperationEntity e){operations.insert(e);} public void attachment(TruckAppointmentAttachmentEntity e){attachments.insert(e);} + public PageResult page(Query q){return PageResult.from(mapper.page(new Page<>(q.page(),q.size()),q));} public TruckAppointmentEntity find(long id){return mapper.selectById(id);} public void insert(TruckAppointmentEntity e){mapper.insert(e);} public int transition(long id,String from,String to,int v){return mapper.transition(id,from,to,v);} public int dispatch(long id,String from,String billOfLadingNo,int v){return mapper.dispatch(id,from,billOfLadingNo,v);} public int bindContainerNoForPickup(long containerBookingId,String containerNo,long operatorId,String operatorName){return mapper.bindContainerNoForPickup(containerBookingId,containerNo,operatorId,operatorName);} public int reschedule(long id,java.time.LocalDateTime at,String reason,int v){return mapper.reschedule(id,at,reason,v);} public void history(TruckAppointmentHistoryEntity e){history.insert(e);} public void operation(TruckAppointmentOperationEntity e){operations.insert(e);} public void attachment(TruckAppointmentAttachmentEntity e){attachments.insert(e);} public boolean claimOperation(long operationId,long appointmentId,String action,String key,String hash){return operations.claim(operationId,appointmentId,action,key,hash)==1;} public TruckAppointmentOperationEntity operation(String key){return operations.find(key);} public int completeOperation(long appointmentId,String action,String key,String response){return operations.complete(appointmentId,action,key,response);} public int updateEdit(TruckAppointmentEntity e,int v){return mapper.updateEdit(e,v);} public java.util.List histories(long id){return history.selectList(new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper().eq(TruckAppointmentHistoryEntity::getAppointmentId,id).orderByAsc(TruckAppointmentHistoryEntity::getCreatedAt));} public java.util.List attachments(long id){return attachments.selectList(new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper().eq(TruckAppointmentAttachmentEntity::getAppointmentId,id).orderByAsc(TruckAppointmentAttachmentEntity::getUploadedAt));} public int deleteAttachment(long appointmentId,long attachmentId){return attachments.delete(new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper().eq(TruckAppointmentAttachmentEntity::getAppointmentId,appointmentId).eq(TruckAppointmentAttachmentEntity::getId,attachmentId));} public TruckAppointmentEntity firstActiveForUpdate(long containerBookingId){return mapper.firstActiveForUpdate(containerBookingId);} public java.util.List activeForUpdate(long containerBookingId){return mapper.activeForUpdate(containerBookingId);} public int completeLoadingFromPda(long id,String fromStatus,int version){return mapper.completeLoadingFromPda(id,fromStatus,version);} diff --git a/firstleg/src/main/java/com/baiyue/firstleg/service/TruckAppointmentService.java b/firstleg/src/main/java/com/baiyue/firstleg/service/TruckAppointmentService.java index bd2fe0d6f..a3cb9b9e4 100644 --- a/firstleg/src/main/java/com/baiyue/firstleg/service/TruckAppointmentService.java +++ b/firstleg/src/main/java/com/baiyue/firstleg/service/TruckAppointmentService.java @@ -54,8 +54,8 @@ public class TruckAppointmentService { @Transactional public void deleteAttachment(long id,long attachmentId){required(id);if(repo.deleteAttachment(id,attachmentId)!=1)throw new BizException(ResultCode.NOT_FOUND,"附件引用不存在");} @Transactional public TruckAppointmentEntity create(long uid,String name,SaveRequest r){if(r.expectedVersion()==null||r.expectedVersion()!=0)throw bad("新增 expectedVersion 必须为0");validateRequired(r);TruckAppointmentEntity active=repo.firstActiveForUpdate(r.containerBookingId());if(active!=null)throw existingAppointmentConflict(active);AssociationContext links=validateAssociations(r);var carrier=suppliers.trucking(r.carrierId(),r.carrierName());TruckAppointmentEntity e=new TruckAppointmentEntity();e.setId(IdWorker.getId());e.setAppointmentNo(documentNumbers.next("TA"));e.setStatus(TruckAppointmentStatus.DRAFT);e.setRevision(0);e.setVersion(0);e.setCreatedAt(LocalDateTime.now());e.setUpdatedAt(e.getCreatedAt());copy(e,r,links,carrier.name());try{repo.insert(e);}catch(DuplicateKeyException exception){if(exception.getMessage()!=null&&exception.getMessage().contains("uk_truck_active_container"))throw existingAppointmentConflict(repo.firstActiveForUpdate(r.containerBookingId()));throw exception;}record(e,null,e.getStatus().name(),"CREATE",null,uid,name);return enrich(e);} @Transactional public TruckAppointmentEntity edit(long id,long uid,String name,SaveRequest r){validateRequired(r);TruckAppointmentEntity e=required(id);checkVersion(e,r.expectedVersion());if(!(e.getStatus()==TruckAppointmentStatus.DRAFT||e.getStatus()==TruckAppointmentStatus.PENDING_DISPATCH||e.getStatus()==TruckAppointmentStatus.RESCHEDULED))throw conflict("当前状态不可编辑");AssociationContext links=validateAssociations(r);var carrier=suppliers.trucking(r.carrierId(),r.carrierName());copy(e,r,links,carrier.name());if(repo.updateEdit(e,r.expectedVersion())!=1)throw conflict("版本已变化，请刷新后重试");record(e,e.getStatus().name(),e.getStatus().name(),"EDIT",null,uid,name);return required(id);} - @Transactional public TruckAppointmentEntity action(long id,String action,ActionRequest r,String idem,String clientHash,long uid,String name){String requestHash=hash(action,id,r);verifyClientHash(clientHash,requestHash);TruckAppointmentEntity replay=claimOrReplay(id,action,idem,requestHash);if(replay!=null)return replay;TruckAppointmentEntity e=required(id); checkVersion(e,r.expectedVersion()); if("RESCHEDULE".equals(action))throw conflict("改约请使用专用接口"); TruckAppointmentStatus from=e.getStatus(),to=next(from,action); String dispatchBill="DISPATCH".equals(action)?requireDispatchReady(e):null; int changed="DISPATCH".equals(action)?repo.dispatch(id,from.name(),dispatchBill,e.getVersion()):repo.transition(id,from.name(),to.name(),e.getVersion()); if(changed!=1)throw conflict("状态或版本已变化，请刷新后重试"); TruckAppointmentEntity after=required(id);record(after,from.name(),to.name(),action,r.reason(),uid,name);return completeOperation(id,action,idem,after);} - @Transactional public TruckAppointmentEntity reschedule(long id,LocalDateTime at,ActionRequest r,String idem,String clientHash,long uid,String name){String action="RESCHEDULE";String requestHash=hash(action,id,new ReschedulePayload(at,r));verifyClientHash(clientHash,requestHash);TruckAppointmentEntity replay=claimOrReplay(id,action,idem,requestHash);if(replay!=null)return replay;TruckAppointmentEntity e=required(id);checkVersion(e,r.expectedVersion()); if(e.getStatus()==TruckAppointmentStatus.COMPLETED||e.getStatus()==TruckAppointmentStatus.CANCELLED)throw conflict("当前状态不可改约"); String from=e.getStatus().name(); if(repo.reschedule(id,at,r.reason(),e.getVersion())!=1)throw conflict("状态或版本已变化，请刷新后重试");TruckAppointmentEntity after=required(id);record(after,from,"RESCHEDULED",action,r.reason(),uid,name);return completeOperation(id,action,idem,after);} + @Transactional public TruckAppointmentEntity action(long id,String action,ActionRequest r,String idem,String clientHash,long uid,String name){String requestHash=hash(action,id,r);verifyClientHash(clientHash,requestHash);TruckAppointmentEntity replay=claimOrReplay(id,action,idem,requestHash);if(replay!=null)return replay;TruckAppointmentEntity e=required(id);checkVersion(e,r.expectedVersion());if("RESCHEDULE".equals(action))throw conflict("改约请使用专用接口");if(!"PICKUP".equals(action)&&StringUtils.hasText(r.containerNo()))throw bad("containerNo仅PICKUP动作可填写");TruckAppointmentStatus from=e.getStatus(),to=next(from,action);String dispatchBill="DISPATCH".equals(action)?requireDispatchReady(e):null;if("PICKUP".equals(action))bindContainerNoForPickup(e,r.containerNo(),uid,name);int changed="DISPATCH".equals(action)?repo.dispatch(id,from.name(),dispatchBill,e.getVersion()):repo.transition(id,from.name(),to.name(),e.getVersion());if(changed!=1)throw conflict("状态或版本已变化，请刷新后重试");TruckAppointmentEntity after=required(id);record(after,from.name(),to.name(),action,r.reason(),uid,name);return completeOperation(id,action,idem,after);} + @Transactional public TruckAppointmentEntity reschedule(long id,LocalDateTime at,ActionRequest r,String idem,String clientHash,long uid,String name){if(StringUtils.hasText(r.containerNo()))throw bad("containerNo仅PICKUP动作可填写");String action="RESCHEDULE";String requestHash=hash(action,id,new ReschedulePayload(at,r));verifyClientHash(clientHash,requestHash);TruckAppointmentEntity replay=claimOrReplay(id,action,idem,requestHash);if(replay!=null)return replay;TruckAppointmentEntity e=required(id);checkVersion(e,r.expectedVersion()); if(e.getStatus()==TruckAppointmentStatus.COMPLETED||e.getStatus()==TruckAppointmentStatus.CANCELLED)throw conflict("当前状态不可改约"); String from=e.getStatus().name(); if(repo.reschedule(id,at,r.reason(),e.getVersion())!=1)throw conflict("状态或版本已变化，请刷新后重试");TruckAppointmentEntity after=required(id);record(after,from,"RESCHEDULED",action,r.reason(),uid,name);return completeOperation(id,action,idem,after);} @Transactional(propagation=Propagation.REQUIRES_NEW) public void completeLoadingFromPda(long containerBookingId,long taskId,long uid,String name){java.util.List active=repo.activeForUpdate(containerBookingId);if(active.isEmpty())return;if(active.size()!=1)throw conflict("同一柜次存在多条有效拖车预约，跳过自动完成");TruckAppointmentEntity appointment=active.get(0);String from=appointment.getStatus().name();if(repo.completeLoadingFromPda(appointment.getId(),from,appointment.getVersion())!=1)throw conflict("拖车预约已被并发修改，跳过自动完成");TruckAppointmentEntity after=required(appointment.getId());record(after,from,TruckAppointmentStatus.COMPLETED.name(),"PDA_COMPLETE_LOADING","PDA task "+taskId+" 确认装柜完成",uid,name);} private AssociationContext validateAssociations(SaveRequest r){ OceanBookingEntity booking=oceanBookings.find(r.oceanBookingId()); @@ -70,7 +70,6 @@ public class TruckAppointmentService { long containerId=container.getId(); boolean allocated=oceanBookings.allocations(booking.getId()).stream().anyMatch(a->Objects.equals(a.getContainerBookingId(),containerId)); if(!allocated)throw bad("containerBookingId未分配至该订舱"); - Iso6346ContainerNumber.require(container.getContainerNo()); oceanBookingDocuments.requireActiveValidDocument(booking); if(r.loadingPlanId()!=null){LoadingPlanEntity plan=loadingPlans.planByBooking(container.getId());if(plan==null||!Objects.equals(r.loadingPlanId(),plan.getId()))throw bad("loadingPlanId与柜次当前装柜计划不一致");} return new AssociationContext(booking,container,warehouseId,billOfLadingNo); @@ -95,12 +94,12 @@ public class TruckAppointmentService { String bill=releasedBookingBill(booking,trim(appointment.getBillOfLadingNo())); ContainerBookingEntity container=containers.find(appointment.getContainerBookingId()); if(container==null||!"ACTIVE".equals(container.getRecordStatus())||!Objects.equals(container.getOceanBookingId(),booking.getId()))throw conflict("关联柜次已失效或不属于当前订舱"); - Iso6346ContainerNumber.require(container.getContainerNo()); boolean allocated=oceanBookings.allocations(booking.getId()).stream().anyMatch(a->Objects.equals(a.getContainerBookingId(),container.getId())); if(!allocated)throw conflict("关联柜次未分配至当前订舱"); oceanBookingDocuments.requireActiveValidDocument(booking); return bill; } + private void bindContainerNoForPickup(TruckAppointmentEntity appointment,String requested,long operatorId,String operatorName){if(appointment.getContainerBookingId()==null)throw conflict("拖车预约缺少柜次关联");ContainerBookingEntity container=containers.findActiveForUpdate(appointment.getContainerBookingId());if(container==null||!Objects.equals(container.getOceanBookingId(),appointment.getOceanBookingId()))throw conflict("关联柜次已失效或不属于当前订舱");String existing=trim(container.getContainerNo());String supplied=trim(requested);if(StringUtils.hasText(existing)){String normalizedExisting=Iso6346ContainerNumber.require(existing);if(StringUtils.hasText(supplied)&&!normalizedExisting.equals(Iso6346ContainerNumber.require(supplied)))throw conflict("PICKUP提交的真实集装箱号与柜次已有号码不一致，请通过预装纠错修改");return;}if(!StringUtils.hasText(supplied))return;String normalized=Iso6346ContainerNumber.require(supplied);if(containers.containerNoExists(normalized,container.getId()))throw conflict("真实集装箱号已被其他柜次使用");try{if(repo.bindContainerNoForPickup(container.getId(),normalized,operatorId,operatorName)!=1)throw conflict("柜次真实集装箱号已被并发修改，请刷新后重试");}catch(DuplicateKeyException exception){throw conflict("真实集装箱号已被其他柜次使用");}} private static String releasedBookingBill(OceanBookingEntity booking,String requested){String authoritative=trim(booking.getBillOfLadingNo());if(!StringUtils.hasText(authoritative))throw conflict("关联已放舱订舱缺少提单号");if(StringUtils.hasText(requested)&&!authoritative.equals(requested))throw bad("billOfLadingNo与关联订舱不一致");return authoritative;} private static String attachmentType(String value){String normalized=trim(value);if(!ATTACHMENT_TYPES.contains(normalized))throw bad("不支持的拖车附件类型");return normalized;} private static String currency(String value){if(!StringUtils.hasText(value))return "RMB";String normalized=value.trim();if(!CURRENCIES.contains(normalized))throw bad("currency仅支持RMB或USD");return normalized;} diff --git a/firstleg/src/main/resources/openapi/truck-appointments-v1.yaml b/firstleg/src/main/resources/openapi/truck-appointments-v1.yaml index 57c9df103..e2e7d03a1 100644 --- a/firstleg/src/main/resources/openapi/truck-appointments-v1.yaml +++ b/firstleg/src/main/resources/openapi/truck-appointments-v1.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: Truck Appointment API version: 1.3.0 - description: Every truck appointment must select one RELEASED ocean booking and one ACTIVE real-numbered container already allocated to that booking. The bill-of-lading number is frozen from the booking, and the booking must own at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file under OCEAN_BOOKING_DOCUMENT. Booking and bill files are not owned by truck appointments. After a PDA loading transaction commits, the server best-effort completes the unique active appointment explicitly linked to that container in an isolated transaction; absence, duplicates or concurrent truck edits never roll back loading completion. + description: Every truck appointment must select one RELEASED ocean booking and its allocated ACTIVE internal container identity. A real ISO 6346 container number is not required for create, edit, submit or dispatch. PICKUP may omit it and still advances normally; when supplied, PICKUP atomically records it if still missing or reuses the existing valid number. The bill-of-lading number is frozen from the booking, and the booking must own at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file under OCEAN_BOOKING_DOCUMENT. Booking and bill files are not owned by truck appointments. After a PDA loading transaction commits, the server best-effort completes the unique active appointment explicitly linked to that container in an isolated transaction; absence, duplicates or concurrent truck edits never roll back loading completion. paths: /api/platform/v1/truck-appointments: get: @@ -20,7 +20,7 @@ paths: properties: records: {type: array, items: {$ref: '#/components/schemas/DetailStableReferences'}} post: - summary: Create a truck appointment for a released booking and its allocated real container + summary: Create a truck appointment for a released booking and its allocated internal container description: If the real container already has a non-terminal appointment, the server returns A0409 with the existing appointment number and instructs the operator to continue editing. This duplicate guard runs before booking-document validation; the database unique key provides the same response for concurrent creates. requestBody: required: true @@ -53,7 +53,7 @@ paths: - {$ref: '#/components/parameters/RequestHash'} post: summary: Apply an idempotent appointment lifecycle action - description: ARRIVE, LOAD and DEPART persist their actual event timestamps atomically with the status transition. + description: PICKUP accepts optional containerNo. Omitting it never blocks the transition to PICKUP_IN_PROGRESS; when supplied, the server atomically records it on the linked internal container if missing. An existing valid ISO 6346 number may be omitted or resubmitted unchanged; a different value is rejected and must use the preload correction flow. Other actions reject containerNo. ARRIVE, LOAD and DEPART persist their actual event timestamps atomically with the status transition. requestBody: required: true content: @@ -176,13 +176,14 @@ components: properties: expectedVersion: {type: integer, minimum: 0} reason: {type: string, maxLength: 500} + containerNo: {type: string, maxLength: 32, nullable: true, description: Optional and only valid for PICKUP. Omission does not block PICKUP; when supplied it is normalized and validated as unique ISO 6346 before being written atomically. A different value from an existing number is rejected and must use preload correction.} SaveRequest: type: object required: [oceanBookingId, containerBookingId, carrierId, plannedLoadingAt, expectedVersion] properties: outboundOrderId: {type: integer, format: int64, minimum: 1, nullable: true} oceanBookingId: {type: integer, format: int64, minimum: 1, description: Required RELEASED booking; must own an active BOOKING_CONFIRMATION or BILL_OF_LADING file.} - containerBookingId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE container already allocated to oceanBookingId and carrying a valid unique ISO 6346 container number.} + containerBookingId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE internal container already allocated to oceanBookingId. Its real ISO 6346 number may remain empty until PICKUP.} loadingPlanId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional loading-plan association. It may be supplied only with containerBookingId and must be that container's current plan.} warehouseId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional warehouse scope. Linked booking/container warehouse facts must agree; when omitted the linked fact is frozen if available.} carrierId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE Warehouse supplier ID validated as TRUCKING.} diff --git a/firstleg/src/test/java/com/baiyue/firstleg/controller/TruckAppointmentControllerContractTest.java b/firstleg/src/test/java/com/baiyue/firstleg/controller/TruckAppointmentControllerContractTest.java index 4ffcde1c2..37153971b 100644 --- a/firstleg/src/test/java/com/baiyue/firstleg/controller/TruckAppointmentControllerContractTest.java +++ b/firstleg/src/test/java/com/baiyue/firstleg/controller/TruckAppointmentControllerContractTest.java @@ -31,7 +31,7 @@ class TruckAppointmentControllerContractTest { } @Test void openApiDocumentsLifecycleIdempotencyAndActualTimes() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/{id}/{action}:","/api/platform/v1/truck-appointments/{id}/reschedule:","name: Idempotency-Key","required: true","actual event timestamps");} @Test void openApiDocumentsActionableDuplicateCreateConflict() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("A0409","existing appointment number","continue editing","before booking-document validation","database unique key");} - @Test void openApiRequiresReleasedBookingAndAllocatedRealContainerWithoutCustomerScope() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("required: [oceanBookingId, containerBookingId, carrierId, plannedLoadingAt, expectedVersion]","RELEASED ocean booking","ACTIVE real-numbered container","OCEAN_BOOKING_DOCUMENT","valid unique ISO 6346 container number","schema: {$ref: '#/components/schemas/DetailEnvelope'}","required: [code, message, data, timestamp]","allOf: [{$ref: '#/components/schemas/DetailStableReferences'}]","nullable: true").doesNotContain("customerId", "customerName", "Filter by customer");} + @Test void openApiRequiresReleasedBookingAndAllocatedInternalContainerWithoutCustomerScope() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("required: [oceanBookingId, containerBookingId, carrierId, plannedLoadingAt, expectedVersion]","RELEASED ocean booking","allocated ACTIVE internal container identity","real ISO 6346 container number is not required for create, edit, submit or dispatch","PICKUP may omit it and still advances normally","Omitting it never blocks the transition to PICKUP_IN_PROGRESS","must use the preload correction flow","Other actions reject containerNo","OCEAN_BOOKING_DOCUMENT","schema: {$ref: '#/components/schemas/DetailEnvelope'}","required: [code, message, data, timestamp]","allOf: [{$ref: '#/components/schemas/DetailStableReferences'}]","nullable: true").doesNotContain("customerId", "customerName", "Filter by customer");} @Test void openApiKeepsOnlyNonBookingTruckAttachments() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("AttachmentRequest:","required: [fileId, attachmentType]","required: [attachmentType, file]","TRUCK_APPOINTMENT_ATTACHMENT","Deletes the appointment reference only","DetailStableReferences:","oceanBookingNo:","shippingCompanyName:","bookingAgentName:","cabinetNo:","billOfLadingNo:").doesNotContain("enum: [BILL_OF_LADING, DISPATCH_ORDER");} @Test void openApiExposesOnlyPayableWithFixedCurrencies() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("payableAmount:","enum: [RMB, USD]","default: RMB").doesNotContain("receivableAmount");} @Test void methodsHavePlatformPermissionsAndAuthenticatedScope() { diff --git a/firstleg/src/test/java/com/baiyue/firstleg/repository/TruckAppointmentMapperContractTest.java b/firstleg/src/test/java/com/baiyue/firstleg/repository/TruckAppointmentMapperContractTest.java index d373d1acb..3c979281c 100644 --- a/firstleg/src/test/java/com/baiyue/firstleg/repository/TruckAppointmentMapperContractTest.java +++ b/firstleg/src/test/java/com/baiyue/firstleg/repository/TruckAppointmentMapperContractTest.java @@ -20,6 +20,9 @@ class TruckAppointmentMapperContractTest { assertThat(transition).contains("status=#{toStatus}", "status=#{fromStatus}", "version=#{version}", "revision=revision+1", "version=version+1"); String dispatch = TruckAppointmentMapper.class.getMethod("dispatch", long.class, String.class, String.class, int.class).getAnnotation(Update.class).value()[0]; assertThat(dispatch).contains("status='DISPATCHED'", "bill_of_lading_no=#{billOfLadingNo}", "status=#{fromStatus}", "version=#{version}", "revision=revision+1"); + String pickupContainer = TruckAppointmentMapper.class.getMethod("bindContainerNoForPickup", long.class, String.class, long.class, String.class).getAnnotation(Update.class).value()[0]; + assertThat(pickupContainer).contains("UPDATE fl_container_booking", "container_no=#{containerNo}", + "id=#{containerBookingId}", "record_status='ACTIVE'", "container_no IS NULL", "version=version+1"); String active = TruckAppointmentMapper.class.getMethod("activeForUpdate", long.class).getAnnotation(Select.class).value()[0]; assertThat(active).contains("container_booking_id=#{containerBookingId}", "FOR UPDATE") .contains("'COMPLETED','CANCELLED','EXCEPTION'"); diff --git a/firstleg/src/test/java/com/baiyue/firstleg/service/TruckAppointmentServiceTest.java b/firstleg/src/test/java/com/baiyue/firstleg/service/TruckAppointmentServiceTest.java index b55a1d46c..aa8cd7066 100644 --- a/firstleg/src/test/java/com/baiyue/firstleg/service/TruckAppointmentServiceTest.java +++ b/firstleg/src/test/java/com/baiyue/firstleg/service/TruckAppointmentServiceTest.java @@ -25,6 +25,7 @@ import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.mockito.ArgumentCaptor; import org.mockito.InjectMocks; +import org.mockito.InOrder; import org.mockito.Mock; import org.mockito.MockitoAnnotations; import org.mockito.Spy; @@ -272,15 +273,21 @@ class TruckAppointmentServiceTest { verify(repository, never()).insert(any()); } - @Test void createRejectsContainerWithoutRealIsoNumberAndMissingBookingDocument() { + @Test void createAcceptsAllocatedInternalContainerWithoutRealNumber() { SaveRequest request = validRequest(); ContainerBookingEntity missingNo = realContainer(); missingNo.setContainerNo(null); when(containers.find(88L)).thenReturn(missingNo); - assertThatThrownBy(() -> service.create(7L, "admin", request)) - .isInstanceOf(BizException.class).hasMessageContaining("集装箱号"); - verify(repository, never()).insert(any()); - when(containers.find(88L)).thenReturn(realContainer()); + service.create(7L, "admin", request); + + verify(repository).insert(any(TruckAppointmentEntity.class)); + verify(oceanBookingDocuments).requireActiveValidDocument(any(OceanBookingEntity.class)); + } + + @Test void createStillRequiresBookingDocumentBeforeRealNumberIsAssigned() { + SaveRequest request = validRequest(); + ContainerBookingEntity missingNo = realContainer(); missingNo.setContainerNo(null); + when(containers.find(88L)).thenReturn(missingNo); doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT, "订舱缺少有效订舱确认或提单文件")) .when(oceanBookingDocuments).requireActiveValidDocument(any()); @@ -385,7 +392,7 @@ class TruckAppointmentServiceTest { when(repository.transition(1L, "DRAFT", "PENDING_DISPATCH", 0)).thenReturn(1); when(repository.completeOperation(eq(1L), eq("SUBMIT"), eq("idem-1"), anyString())).thenReturn(1); - var result = service.action(1L, "SUBMIT", new ActionRequest(0, "提交"), "idem-1", null, 7L, "admin"); + var result = service.action(1L, "SUBMIT", new ActionRequest(0, "提交", null), "idem-1", null, 7L, "admin"); assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.PENDING_DISPATCH); assertThat(result.getVersion()).isEqualTo(1); @@ -399,12 +406,12 @@ class TruckAppointmentServiceTest { TruckAppointmentEntity completed = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1); TruckAppointmentOperationEntity operation = new TruckAppointmentOperationEntity(); operation.setAppointmentId(1L); operation.setAction("SUBMIT"); operation.setIdempotencyKey("idem-1"); - String hash = requestHash("SUBMIT", 1L, new ActionRequest(0, "提交")); + String hash = requestHash("SUBMIT", 1L, new ActionRequest(0, "提交", null)); operation.setRequestHash(hash); operation.setResponseSnapshot(objectMapper.writeValueAsString(completed)); when(repository.claimOperation(anyLong(), eq(1L), eq("SUBMIT"), eq("idem-1"), eq(hash))).thenReturn(false); when(repository.operation("idem-1")).thenReturn(operation); - var replay = service.action(1L, "SUBMIT", new ActionRequest(0, "提交"), "idem-1", hash, 7L, "admin"); + var replay = service.action(1L, "SUBMIT", new ActionRequest(0, "提交", null), "idem-1", hash, 7L, "admin"); assertThat(replay.getStatus()).isEqualTo(TruckAppointmentStatus.PENDING_DISPATCH); verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt()); @@ -412,7 +419,7 @@ class TruckAppointmentServiceTest { } @Test void concurrentSameKeyBeforeFirstCompletionReturnsRetryableConflictWithoutDrift() throws Exception { - var request = new ActionRequest(0, "并发提交"); + var request = new ActionRequest(0, "并发提交", null); String hash = requestHash("SUBMIT", 1L, request); TruckAppointmentOperationEntity processing = new TruckAppointmentOperationEntity(); processing.setAppointmentId(1L); processing.setAction("SUBMIT"); @@ -437,7 +444,7 @@ class TruckAppointmentServiceTest { .thenReturn(false); when(repository.operation("reused-key")).thenReturn(existing); - assertThatThrownBy(() -> service.action(1L, "SUBMIT", new ActionRequest(0, "载荷A"), + assertThatThrownBy(() -> service.action(1L, "SUBMIT", new ActionRequest(0, "载荷A", null), "reused-key", null, 7L, "admin")) .isInstanceOf(BizException.class).hasMessageContaining("不同请求"); @@ -453,7 +460,7 @@ class TruckAppointmentServiceTest { when(repository.claimOperation(anyLong(), eq(1L), eq("DISPATCH"), eq("dispatch-no-bill"), anyString())).thenReturn(true); when(repository.find(1L)).thenReturn(missingBill); - assertThatThrownBy(() -> service.action(1L, "DISPATCH", new ActionRequest(1, null), + assertThatThrownBy(() -> service.action(1L, "DISPATCH", new ActionRequest(1, null, null), "dispatch-no-bill", null, 7L, "admin")) .isInstanceOf(BizException.class).hasMessageContaining("提单号"); @@ -465,26 +472,28 @@ class TruckAppointmentServiceTest { doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,"订舱缺少有效订舱确认或提单文件")) .when(oceanBookingDocuments).requireActiveValidDocument(any()); - assertThatThrownBy(() -> service.action(1L, "DISPATCH", new ActionRequest(1, null), + assertThatThrownBy(() -> service.action(1L, "DISPATCH", new ActionRequest(1, null, null), "dispatch-no-file", null, 7L, "admin")) .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件"); verify(repository, never()).dispatch(anyLong(), anyString(), anyString(), anyInt()); } - @Test void dispatchFreezesReleasedBookingBillAndTransitionsOnceWithActiveAttachment() { + @Test void dispatchFreezesReleasedBookingBillWithoutRequiringRealContainerNumber() { TruckAppointmentEntity before = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1); before.setOceanBookingId(99L); before.setContainerBookingId(88L); before.setBillOfLadingNo(null); TruckAppointmentEntity after = entity(TruckAppointmentStatus.DISPATCHED, 2); after.setOceanBookingId(99L); after.setContainerBookingId(88L); after.setBillOfLadingNo("BL-BOOKING-1"); OceanBookingEntity booking = new OceanBookingEntity(); booking.setId(99L); booking.setStatus("RELEASED"); booking.setBillOfLadingNo("BL-BOOKING-1"); + ContainerBookingEntity internalContainer = realContainer(); internalContainer.setContainerNo(null); when(repository.claimOperation(anyLong(), eq(1L), eq("DISPATCH"), eq("dispatch-ok"), anyString())).thenReturn(true); when(repository.find(1L)).thenReturn(before, after); when(oceanBookings.find(99L)).thenReturn(booking); + when(containers.find(88L)).thenReturn(internalContainer); when(repository.dispatch(1L, "PENDING_DISPATCH", "BL-BOOKING-1", 1)).thenReturn(1); when(repository.completeOperation(eq(1L), eq("DISPATCH"), eq("dispatch-ok"), anyString())).thenReturn(1); - TruckAppointmentEntity result = service.action(1L, "DISPATCH", new ActionRequest(1, null), + TruckAppointmentEntity result = service.action(1L, "DISPATCH", new ActionRequest(1, null, null), "dispatch-ok", null, 7L, "admin"); assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.DISPATCHED); @@ -494,8 +503,168 @@ class TruckAppointmentServiceTest { verify(repository).history(any(TruckAppointmentHistoryEntity.class)); } + @Test void pickupWithoutContainerNumberStillAdvancesWithoutBinding() { + TruckAppointmentEntity before = entity(TruckAppointmentStatus.DISPATCHED, 2); + before.setOceanBookingId(99L); before.setContainerBookingId(88L); + TruckAppointmentEntity after = entity(TruckAppointmentStatus.PICKUP_IN_PROGRESS, 3); + after.setOceanBookingId(99L); after.setContainerBookingId(88L); + ContainerBookingEntity container = realContainer(); container.setContainerNo(null); + when(repository.find(1L)).thenReturn(before, after); + when(repository.claimOperation(anyLong(), eq(1L), eq("PICKUP"), eq("pickup-without-number"), anyString())).thenReturn(true); + when(containers.findActiveForUpdate(88L)).thenReturn(container); + when(repository.transition(1L, "DISPATCHED", "PICKUP_IN_PROGRESS", 2)).thenReturn(1); + when(repository.completeOperation(eq(1L), eq("PICKUP"), eq("pickup-without-number"), anyString())).thenReturn(1); + + TruckAppointmentEntity result = service.action(1L, "PICKUP", new ActionRequest(2, "提柜", null), + "pickup-without-number", null, 7L, "admin"); + + assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.PICKUP_IN_PROGRESS); + verify(repository, never()).bindContainerNoForPickup(anyLong(), anyString(), anyLong(), anyString()); + verify(repository).transition(1L, "DISPATCHED", "PICKUP_IN_PROGRESS", 2); + verify(repository).history(any(TruckAppointmentHistoryEntity.class)); + } + + @Test void pickupRejectsSuppliedInvalidContainerNumberWithoutDrift() { + TruckAppointmentEntity before = entity(TruckAppointmentStatus.DISPATCHED, 2); + before.setOceanBookingId(99L); before.setContainerBookingId(88L); + ContainerBookingEntity container = realContainer(); container.setContainerNo(null); + when(repository.find(1L)).thenReturn(before); + when(repository.claimOperation(anyLong(), eq(1L), eq("PICKUP"), eq("pickup-invalid"), anyString())).thenReturn(true); + when(containers.findActiveForUpdate(88L)).thenReturn(container); + + assertThatThrownBy(() -> service.action(1L, "PICKUP", new ActionRequest(2, "提柜", "MSCU6639871"), + "pickup-invalid", null, 7L, "admin")) + .isInstanceOf(BizException.class).hasMessageContaining("ISO 6346"); + + verify(repository, never()).bindContainerNoForPickup(anyLong(), anyString(), anyLong(), anyString()); + verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt()); + verify(repository, never()).history(any()); + } + + @Test void pickupNormalizesAndAtomicallyBindsContainerNumberBeforeTransition() { + TruckAppointmentEntity before = entity(TruckAppointmentStatus.DISPATCHED, 2); + before.setOceanBookingId(99L); before.setContainerBookingId(88L); + TruckAppointmentEntity after = entity(TruckAppointmentStatus.PICKUP_IN_PROGRESS, 3); + after.setOceanBookingId(99L); after.setContainerBookingId(88L); + ContainerBookingEntity container = realContainer(); container.setContainerNo(null); + when(repository.find(1L)).thenReturn(before, after); + when(repository.claimOperation(anyLong(), eq(1L), eq("PICKUP"), eq("pickup-bind"), anyString())).thenReturn(true); + when(containers.findActiveForUpdate(88L)).thenReturn(container); + when(containers.containerNoExists("MSCU6639870", 88L)).thenReturn(false); + when(repository.bindContainerNoForPickup(88L, "MSCU6639870", 7L, "admin")).thenReturn(1); + when(repository.transition(1L, "DISPATCHED", "PICKUP_IN_PROGRESS", 2)).thenReturn(1); + when(repository.completeOperation(eq(1L), eq("PICKUP"), eq("pickup-bind"), anyString())).thenReturn(1); + + TruckAppointmentEntity result = service.action(1L, "PICKUP", + new ActionRequest(2, "司机已提柜", " ms cu 663987 0 "), "pickup-bind", null, 7L, "admin"); + + assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.PICKUP_IN_PROGRESS); + InOrder writes = inOrder(repository); + writes.verify(repository).bindContainerNoForPickup(88L, "MSCU6639870", 7L, "admin"); + writes.verify(repository).transition(1L, "DISPATCHED", "PICKUP_IN_PROGRESS", 2); + writes.verify(repository).history(any(TruckAppointmentHistoryEntity.class)); + } + + @Test void pickupReusesExistingValidContainerNumberWithoutRewritingIt() { + TruckAppointmentEntity before = entity(TruckAppointmentStatus.DISPATCHED, 2); + before.setOceanBookingId(99L); before.setContainerBookingId(88L); + TruckAppointmentEntity after = entity(TruckAppointmentStatus.PICKUP_IN_PROGRESS, 3); + after.setOceanBookingId(99L); after.setContainerBookingId(88L); + when(repository.find(1L)).thenReturn(before, after); + when(repository.claimOperation(anyLong(), eq(1L), eq("PICKUP"), eq("pickup-reuse"), anyString())).thenReturn(true); + when(containers.findActiveForUpdate(88L)).thenReturn(realContainer()); + when(repository.transition(1L, "DISPATCHED", "PICKUP_IN_PROGRESS", 2)).thenReturn(1); + when(repository.completeOperation(eq(1L), eq("PICKUP"), eq("pickup-reuse"), anyString())).thenReturn(1); + + service.action(1L, "PICKUP", new ActionRequest(2, "复用已有柜号", null), + "pickup-reuse", null, 7L, "admin"); + + verify(repository, never()).bindContainerNoForPickup(anyLong(), anyString(), anyLong(), anyString()); + verify(repository).transition(1L, "DISPATCHED", "PICKUP_IN_PROGRESS", 2); + } + + @Test void pickupIdempotentReplayDoesNotLockOrRewriteContainerAndChangedNumberConflicts() throws Exception { + ActionRequest request = new ActionRequest(2, "提柜", "MSCU6639870"); + TruckAppointmentEntity completed = entity(TruckAppointmentStatus.PICKUP_IN_PROGRESS, 3); + completed.setOceanBookingId(99L); completed.setContainerBookingId(88L); + TruckAppointmentOperationEntity operation = new TruckAppointmentOperationEntity(); + operation.setAppointmentId(1L); operation.setAction("PICKUP"); operation.setIdempotencyKey("pickup-replay"); + operation.setRequestHash(requestHash("PICKUP", 1L, request)); + operation.setResponseSnapshot(objectMapper.writeValueAsString(completed)); + when(repository.claimOperation(anyLong(), eq(1L), eq("PICKUP"), eq("pickup-replay"), anyString())) + .thenReturn(false); + when(repository.operation("pickup-replay")).thenReturn(operation); + + TruckAppointmentEntity replay = service.action(1L, "PICKUP", request, + "pickup-replay", operation.getRequestHash(), 7L, "admin"); + assertThat(replay.getStatus()).isEqualTo(TruckAppointmentStatus.PICKUP_IN_PROGRESS); + assertThatThrownBy(() -> service.action(1L, "PICKUP", + new ActionRequest(2, "提柜", "TSTU1503306"), "pickup-replay", null, 7L, "admin")) + .isInstanceOf(BizException.class).hasMessageContaining("不同请求"); + + verify(containers, never()).findActiveForUpdate(anyLong()); + verify(repository, never()).bindContainerNoForPickup(anyLong(), anyString(), anyLong(), anyString()); + verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt()); + } + + @Test void pickupRejectsMismatchedOrDuplicateContainerNumberBeforeStatusDrift() { + TruckAppointmentEntity before = entity(TruckAppointmentStatus.DISPATCHED, 2); + before.setOceanBookingId(99L); before.setContainerBookingId(88L); + when(repository.find(1L)).thenReturn(before); + when(repository.claimOperation(anyLong(), eq(1L), eq("PICKUP"), anyString(), anyString())).thenReturn(true); + when(containers.findActiveForUpdate(88L)).thenReturn(realContainer()); + + assertThatThrownBy(() -> service.action(1L, "PICKUP", + new ActionRequest(2, "错误柜号", "TSTU1503306"), "pickup-mismatch", null, 7L, "admin")) + .isInstanceOf(BizException.class).hasMessageContaining("不一致").hasMessageContaining("预装纠错"); + + ContainerBookingEntity unnumbered = realContainer(); unnumbered.setContainerNo(null); + when(containers.findActiveForUpdate(88L)).thenReturn(unnumbered); + when(containers.containerNoExists("TSTU1503306", 88L)).thenReturn(true); + assertThatThrownBy(() -> service.action(1L, "PICKUP", + new ActionRequest(2, "重复柜号", "TSTU1503306"), "pickup-duplicate", null, 7L, "admin")) + .isInstanceOf(BizException.class).hasMessageContaining("其他柜次使用"); + + verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt()); + verify(repository, never()).history(any()); + } + + @Test void concurrentPickupContainerNumberCollisionRollsBackBeforeStatusTransition() { + TruckAppointmentEntity before = entity(TruckAppointmentStatus.DISPATCHED, 2); + before.setOceanBookingId(99L); before.setContainerBookingId(88L); + ContainerBookingEntity container = realContainer(); container.setContainerNo(null); + when(repository.find(1L)).thenReturn(before); + when(repository.claimOperation(anyLong(), eq(1L), eq("PICKUP"), eq("pickup-concurrent"), anyString())).thenReturn(true); + when(containers.findActiveForUpdate(88L)).thenReturn(container); + when(containers.containerNoExists("MSCU6639870", 88L)).thenReturn(false); + doThrow(new DuplicateKeyException("uk_container_booking_container_no")) + .when(repository).bindContainerNoForPickup(88L, "MSCU6639870", 7L, "admin"); + + assertThatThrownBy(() -> service.action(1L, "PICKUP", + new ActionRequest(2, "并发提柜", "MSCU6639870"), "pickup-concurrent", null, 7L, "admin")) + .isInstanceOf(BizException.class).hasMessageContaining("其他柜次使用"); + + verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt()); + verify(repository, never()).history(any()); + verify(repository, never()).completeOperation(anyLong(), anyString(), anyString(), anyString()); + } + + @Test void nonPickupActionsRejectContainerNumberWithoutWritingIt() { + TruckAppointmentEntity before = entity(TruckAppointmentStatus.DRAFT, 0); + when(repository.find(1L)).thenReturn(before); + when(repository.claimOperation(anyLong(), eq(1L), eq("SUBMIT"), eq("submit-with-container"), anyString())).thenReturn(true); + + assertThatThrownBy(() -> service.action(1L, "SUBMIT", + new ActionRequest(0, "错误携带柜号", "MSCU6639870"), "submit-with-container", null, 7L, "admin")) + .isInstanceOf(BizException.class).hasMessageContaining("仅PICKUP动作"); + + verify(repository, never()).bindContainerNoForPickup(anyLong(), anyString(), anyLong(), anyString()); + verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt()); + verify(repository, never()).history(any()); + } + @Test void actionRejectsMissingKeyAndMismatchedClientHash() { - var request = new ActionRequest(0, "提交"); + var request = new ActionRequest(0, "提交", null); assertThatThrownBy(() -> service.action(1L, "SUBMIT", request, null, null, 7L, "admin")) .isInstanceOf(BizException.class).hasMessageContaining("Idempotency-Key"); assertThatThrownBy(() -> service.action(1L, "SUBMIT", request, "idem-1", "wrong", 7L, "admin")) @@ -507,11 +676,11 @@ class TruckAppointmentServiceTest { TruckAppointmentEntity e = entity(TruckAppointmentStatus.DRAFT, 0); when(repository.find(1L)).thenReturn(e); when(repository.claimOperation(anyLong(), eq(1L), eq("RESCHEDULE"), eq("idem-action"), anyString())).thenReturn(true); - assertThatThrownBy(() -> service.action(1L, "RESCHEDULE", new ActionRequest(0, null), "idem-action", null, 7L, "admin")) + assertThatThrownBy(() -> service.action(1L, "RESCHEDULE", new ActionRequest(0, null, null), "idem-action", null, 7L, "admin")) .isInstanceOf(BizException.class).hasMessageContaining("专用接口"); e.setStatus(TruckAppointmentStatus.COMPLETED); when(repository.claimOperation(anyLong(), eq(1L), eq("RESCHEDULE"), eq("idem-reschedule"), anyString())).thenReturn(true); - assertThatThrownBy(() -> service.reschedule(1L, LocalDateTime.now(), new ActionRequest(0, "改约"), "idem-reschedule", null, 7L, "admin")) + assertThatThrownBy(() -> service.reschedule(1L, LocalDateTime.now(), new ActionRequest(0, "改约", null), "idem-reschedule", null, 7L, "admin")) .isInstanceOf(BizException.class).hasMessageContaining("不可改约"); verify(repository, never()).reschedule(anyLong(), any(), anyString(), anyInt()); } @@ -524,7 +693,7 @@ class TruckAppointmentServiceTest { when(repository.reschedule(eq(1L), any(), eq("改约"), eq(2))).thenReturn(1); when(repository.completeOperation(eq(1L), eq("RESCHEDULE"), eq("idem-reschedule"), anyString())).thenReturn(1); var at = LocalDateTime.of(2026, 8, 12, 10, 0); - var result = service.reschedule(1L, at, new ActionRequest(2, "改约"), "idem-reschedule", null, 7L, "admin"); + var result = service.reschedule(1L, at, new ActionRequest(2, "改约", null), "idem-reschedule", null, 7L, "admin"); assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.RESCHEDULED); assertThat(result.getVersion()).isEqualTo(3); ArgumentCaptor history = ArgumentCaptor.forClass(TruckAppointmentHistoryEntity.class);