fix(firstleg): remove booking document prerequisites from release and trucking

firstleg/docs/business-index.md

@@ -58,7 +58,7 @@
 | 目的港码头拖车与还空预警 | `terminaldrayage/controller/PlatformTerminalDrayageController.java`、`service/TerminalDrayageService.java`、`mapper/TerminalDrayageMapper.java`；货柜实际到港后引用 Warehouse `ACTIVE/TRUCKING/OVERSEAS` 海外车队供应商，依次选择车队、预约提柜、确认实际提柜，海外仓卸柜或全部直送目的仓实际卸货完成后确认还柜；服务端按卸柜完成时间加 72 小时返回报空预警，实际提柜和还柜通过现有 `CarrierScheduleQueryService` 推进 `PICKED_UP/EMPTY_RETURNED`，不复制船节点或车队主档。契约 `src/main/resources/openapi/terminal-drayage-v1.yaml`，基线 `src/main/resources/db/phase3-terminal-drayage-schema.sql` 邮件由 `terminaldrayage/service/TerminalDrayageMailService.java` 入队，`TerminalDrayageMailDispatcher.java` 顺序投递，模板与 SMTP 配置见 `docs/terminal-drayage-mail.md`；首次选队不发信，换队事务内生成取消与请求两封邮件。 |
 | 船节点交接事件 | `portschedule/service/CarrierScheduleNodeOutboxService.java`；实际节点落库后按 `containerBookingId` 柜级发布 `FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED` V1，信封固定使用 `tenantId=0` 平台技术范围且 Payload 不携带客户，复用 `LoadingCompletedOutboxRepository`/Relay 直投 Lastleg `/internal/lastleg/events`；消费见 `../lastleg-service/src/main/java/com/baiyue/lastleg/shipping/service/ContainerShippingNodeConsumer.java`，ACK/重试按 `../../docs/统一认证与服务通信契约.md` |
 | Firstleg 业务单据编号 | `service/FirstlegDocumentNumberGenerator.java`；前缀与生成规则见 `../../../docs/业务单据编号契约.md`，柜次及实物标签规则保持不变 |
-| 订舱级拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java` 的 `/candidates`、`service/TruckAppointmentService.java`、`repository/TruckAppointmentRepository.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；拖车契约 `src/main/resources/openapi/truck-appointments-v1.yaml`。预约只绑定 `RELEASED` 订舱，候选排除缺提单/有效订舱文件或已有非终态预约的订舱；API 不含客户、柜次、装柜计划或真实柜号，每订舱最多一张有效预约，已有完成单不得重建收费；PDA 完成不推进拖车状态，全部要求货柜确认国内离仓后由 `TruckAppointmentCompletionService` 自动完成并经 `TruckAppointmentFeeService` 发布应付 |
+| 订舱级拖车与整柜出仓调度 | `controller/PlatformTruckAppointmentController.java` 的 `/candidates`、`service/TruckAppointmentService.java`、`repository/TruckAppointmentRepository.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java`；拖车契约 `src/main/resources/openapi/truck-appointments-v1.yaml`。预约只绑定 `RELEASED` 订舱，候选排除缺提单号或已有非终态预约的订舱；创建及派车不要求订舱文件；API 不含客户、柜次、装柜计划或真实柜号，每订舱最多一张有效预约，已有完成单不得重建收费；PDA 完成不推进拖车状态，全部要求货柜确认国内离仓后由 `TruckAppointmentCompletionService` 自动完成并经 `TruckAppointmentFeeService` 发布应付 |
 | 整柜出口报关 | `customs/container/controller/PlatformContainerCustomsController.java`、`customs/container/controller/MerchantContainerCustomsController.java`、`customs/container/service/ContainerCustomsService.java`、`customs/container/mapper/ContainerCustomsMapper.java`；装柜完成后按柜收集退税资料，多对多覆盖入仓码，开始报关冻结，完成文件逐资料一对一回传，全买单柜由平台确认并通过导出中心取明细；正式申报批次与海关结果在同一模块独立记录，不改报关四态、PDA 或船期事实；契约 `src/main/resources/openapi/customs-v1.yaml`，基线 `src/main/resources/db/phase3-container-customs-schema.sql`；消费者为 Admin `../../apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue` 和 Client `../../apps/client-web/src/modules/first-leg/components/CustomsDocumentsDialog.vue` |
 | 买单订单明细导出 Provider | `customs/container/controller/LoadingListBuyDeclarationExportController.java`、`service/LoadingListBuyDeclarationExportService.java`；只为 File 导出中心提供 `LOADING_LIST_BUY_DECLARATION_ITEMS` 的已完成装柜实际买单行，不在 Firstleg 生成文件 |
 | 跨模型桥接 | `loading/bridge/controller/PlatformLoadingModelBridgeController.java` |
@@ -79,7 +79,7 @@
 - 客户箱规配置必须恰好保持四档且默认算法在四行一致；`ADD` 以实测尺寸为基准对三个维度分别增加命中箱规的尺寸值，`MULTIPLY` 使用当前客户唯一默认计费规则，并由服务端按规则中的规格档位选择系数。测量行必须保存实际尺寸、选用规则和算法快照，页面不得自行重算后覆盖服务端结果；计价使用用户确认的重量/体积选择值并纳入幂等请求哈希。
 - 报关、订舱和拖车引用的供应商必须通过 `WarehouseSupplierSnapshotService` 按 ID 向 Warehouse 校验：报关使用 `CUSTOMS`，订舱使用 `BOOKING`（不区分国内/国外 scope），国内拖车使用 `TRUCKING + truckingScope=DOMESTIC`，清关提柜/目的港码头拖车使用 `TRUCKING + truckingScope=OVERSEAS`；供应商必须为 `ACTIVE`。请求中的名称只能作为一致性提示，持久化名称必须来自 Warehouse 快照，禁止用自由文本绕过 ID、类别或启用状态校验。修改任一供应商引用 DTO、OpenAPI 或内部客户端时，必须同步检查三条业务链、Warehouse `supplier-v1.yaml`、数据库快照字段和对应契约测试。
 - Order 渠道变更门禁必须检查装柜或后续状态、PDA task、预装、分柜及同柜组兼容性；任何不确定结果均失败关闭。`ORDER_DECLARATION_UPDATED_V1` 消费必须校验订单号/入仓码归属，永久保留 `eventId + payload hash` 幂等历史并按版本单调更新申报投影；不得覆盖仓库实测、箱码、测量审核或已确认费用。
-- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合，放舱后除预计到港外的运输、预报货量、三方和柜型需求只读；预计到港允许通过 `/estimated-arrival` 按编辑权限、版本与幂等键单独维护，保留前后审计快照且不得清空或早于预计开船，不改实际到港或计划到仓；三项实际货量允许通过 `OceanBookingService.updateActualCargo` 按编辑权限、版本、幂等键和原因补录并保存前后审计快照。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
+- 订舱状态固定为 `DRAFT → RELEASED`：草稿允许资料不完整并可替换或删除，放舱时校验完整持久化聚合但不要求订舱附件，放舱后除预计到港外的运输、预报货量、三方和柜型需求只读；预计到港允许通过 `/estimated-arrival` 按编辑权限、版本与幂等键单独维护，保留前后审计快照且不得清空或早于预计开船，不改实际到港或计划到仓；三项实际货量允许通过 `OceanBookingService.updateActualCargo` 按编辑权限、版本、幂等键和原因补录并保存前后审计快照。创建草稿和放舱都只维护订舱聚合、三类参与方及柜型需求，不创建真实 `containerNo`、货柜行或分配关系；真实货柜只在后续提柜关联时占用已放舱柜型需求。
 - 订舱柜型需求至少一项、最多 20 项，数量必须为正整数，容量和限重必须匹配平台柜型规格。起运仓必须是启用的国内中转仓；物流渠道必须来自该仓当前 ACTIVE 价格版本，服务端保存渠道名称快照，渠道失效时失败关闭。预计到港草稿可留空，放舱前必填且不得早于预计开船时间；关联柜次时带入柜级到港来源，供日历和默认到仓日期解析使用。
 - 订舱号遵循 `../../../docs/业务单据编号契约.md`；不得以实体 ID 拼接生成。提单号在订舱主表全局唯一，柜次表只保存快照；真实集装箱号只在同一订舱内唯一，不同提单允许复用。放舱不要求真实柜号，也不得为满足放舱校验伪造柜号。
 - 订舱列表 `containerCount` 固定为该订舱全部柜型需求 `quantity` 之和，与真实柜关联/解除无关；关联候选只返回 `RELEASED`、剩余数量大于 0 且 `warehouseId + channelCode + containerType` 精确匹配的需求，由服务端集合查询 ACTIVE 分配量。前端不得扇出详情计算或用已关联柜数覆盖该字段，最终关联命令仍须重验目标货柜可修改性。

firstleg/src/main/java/com/baiyue/firstleg/dto/TruckAppointmentDtos.java

@@ -3,7 +3,8 @@ 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 oceanBookingId, @Min(1) long page, @Min(1) @Max(200) long size){ public Query{if(page==0)page=1;if(size==0)size=20;} }
  public record CandidateQuery(@Size(max=64) String keyword,@Min(1) long page,@Min(1) @Max(200) long size){public CandidateQuery{if(page==0)page=1;if(size==0)size=20;}}
- public record Candidate(Long oceanBookingId,String oceanBookingNo,String billOfLadingNo,Long warehouseId,String warehouseName,String channelCode,String channelName,Boolean bookingDocumentReady){}
+ /** 已放舱订舱候选，预约不依赖订舱附件。 */
+ public record Candidate(Long oceanBookingId,String oceanBookingNo,String billOfLadingNo,Long warehouseId,String warehouseName,String channelCode,String channelName){}
  public record SaveRequest(@Positive Long outboundOrderId,@NotNull @Positive Long oceanBookingId,@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") @Digits(integer=16,fraction=2) BigDecimal payableAmount,@Pattern(regexp="RMB") 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 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){ }

firstleg/src/main/java/com/baiyue/firstleg/mapper/TruckAppointmentMapper.java

@@ -1,15 +1,14 @@
 package com.baiyue.firstleg.mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baiyue.firstleg.dto.TruckAppointmentDtos.*; import com.baiyue.firstleg.entity.TruckAppointmentEntity; import org.apache.ibatis.annotations.*;
 @Mapper public interface TruckAppointmentMapper extends BaseMapper<TruckAppointmentEntity>{
+ /** 查询已放舱且有提单号的可预约订舱，不依赖附件。 */
  @Select("""
   <script>
   SELECT o.id oceanBookingId,o.booking_no oceanBookingNo,o.bill_of_lading_no billOfLadingNo,
          o.warehouse_id warehouseId,o.warehouse_name warehouseName,o.channel_code channelCode,
-         o.channel_name channelName,TRUE bookingDocumentReady
+         o.channel_name channelName
     FROM fl_ocean_booking o
-   WHERE EXISTS (SELECT 1 FROM fl_ocean_booking_document d WHERE d.ocean_booking_id=o.id
-                  AND d.valid=1 AND d.document_type IN ('BOOKING_CONFIRMATION','BILL_OF_LADING'))
-     AND o.status='RELEASED' AND o.bill_of_lading_no IS NOT NULL AND o.bill_of_lading_no&lt;&gt;''
+   WHERE o.status='RELEASED' AND o.bill_of_lading_no IS NOT NULL AND o.bill_of_lading_no&lt;&gt;''
      AND NOT EXISTS (SELECT 1 FROM fl_truck_appointment t WHERE t.ocean_booking_id=o.id
                       AND t.status NOT IN ('CANCELLED','EXCEPTION'))
      AND (#{q.keyword} IS NULL OR o.booking_no LIKE CONCAT('%',#{q.keyword},'%')

firstleg/src/main/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingService.java

@@ -51,7 +51,6 @@ public class OceanBookingService {
     @Resource private WarehouseMasterDataClient warehouses;
     @Resource private WarehousePartnerClient partners;
     @Resource private FirstlegDocumentNumberGenerator documentNumbers;
-    @Resource private OceanBookingDocumentService documents;
     @Resource private com.baiyue.firstleg.service.IamCustomerSnapshotService customers;
     @Value("${baiyue.security.internal-service-token:}") private String internalToken;
     @Value("${baiyue.warehouse.public-tenant-id:0}") private long publicWarehouseTenantId;
@@ -194,6 +193,7 @@ public class OceanBookingService {
         complete(null, operatorId, action, key, new Detail(before, List.of(), List.of(), List.of(), List.of()));
     }
 
+    /** 校验完整订舱资料后放舱，不以附件上传作为前置条件。 */
     @Transactional public Detail release(long id, long operatorId, String name, String key, ReleaseRequest request) {
         String action = "RELEASE";
         Detail replay = claimOrReplay(id, operatorId, action, key, hash(action, id, request));
@@ -202,7 +202,6 @@ public class OceanBookingService {
         requireStatus(before, OceanBookingStatus.DRAFT);
         validateRelease(before, repository.parties(id), repository.requirements(id));
         validateMasterData(before);
-        documents.requireActiveValidDocument(before);
         if (repository.transition(id, OceanBookingStatus.DRAFT.name(), OceanBookingStatus.RELEASED.name(),
             request.expectedVersion(), operatorId, name) != 1) throw concurrent();
         OceanBookingEntity after = required(id);

firstleg/src/main/java/com/baiyue/firstleg/service/TruckAppointmentService.java

@@ -9,7 +9,6 @@ import com.baiyue.firstleg.dto.TruckAppointmentDtos.*;
 import com.baiyue.firstleg.entity.*;
 import com.baiyue.firstleg.oceanbooking.entity.OceanBookingEntity;
 import com.baiyue.firstleg.oceanbooking.repository.OceanBookingRepository;
-import com.baiyue.firstleg.oceanbooking.service.OceanBookingDocumentService;
 import com.baiyue.firstleg.repository.TruckAppointmentRepository;
 import com.baiyue.firstleg.client.TruckAppointmentFileClient;
 import jakarta.annotation.Resource;
@@ -36,7 +35,6 @@ public class TruckAppointmentService {
  @Resource TruckAppointmentRepository repo;
  @Resource TruckAppointmentCompletionService completion;
  @Resource OceanBookingRepository oceanBookings;
- @Resource OceanBookingDocumentService oceanBookingDocuments;
  @Resource TruckAppointmentFileClient files;
  @Resource WarehouseSupplierSnapshotService suppliers;
  @Resource FirstlegDocumentNumberGenerator documentNumbers;
@@ -64,13 +62,13 @@ public class TruckAppointmentService {
   return completeOperation(id,action,idem,enrich(required(id)));
  }
  @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);completion.lockBooking(e.getOceanBookingId());checkVersion(e,r.expectedVersion()); if(e.getStatus()==TruckAppointmentStatus.COMPLETED||e.getStatus()==TruckAppointmentStatus.CANCELLED)throw conflict("当前状态不可改约"); TruckAppointmentEntity active=repo.firstActiveForUpdate(e.getOceanBookingId());if(active!=null&&!Objects.equals(active.getId(),e.getId()))throw existingAppointmentConflict(active);String from=e.getStatus().name(); if(repo.reschedule(id,at,r.reason(),e.getVersion())!=1)throw conflict("状态或版本已变化，请刷新后重试");TruckAppointmentEntity after=enrich(required(id));record(after,from,"RESCHEDULED",action,r.reason(),uid,name);completion.completeForBooking(e.getOceanBookingId());return completeOperation(id,action,idem,enrich(required(id)));}
+ /** 从已放舱订舱校验仓库和提单号，附件不作为预约条件。 */
  private AssociationContext validateAssociations(SaveRequest r){
   OceanBookingEntity booking=oceanBookings.find(r.oceanBookingId());
   if(booking==null)throw new BizException(ResultCode.NOT_FOUND,"关联订舱不存在");
   if(!"RELEASED".equals(booking.getStatus()))throw conflict("拖车预约只能选择已放舱订舱");
   Long warehouseId=mergeWarehouse(r.warehouseId(),booking.getWarehouseId(),"订舱");
   String billOfLadingNo=releasedBookingBill(booking,trim(r.billOfLadingNo()));
-  oceanBookingDocuments.requireActiveValidDocument(booking);
   return new AssociationContext(booking,warehouseId,billOfLadingNo);
  }
  private static void validateRequired(SaveRequest r){if(r.oceanBookingId()==null||r.oceanBookingId()<=0)throw bad("oceanBookingId不能为空");if(r.carrierId()==null||r.carrierId()<=0)throw bad("carrierId不能为空");if(r.plannedLoadingAt()==null)throw bad("plannedLoadingAt不能为空");if(r.expectedVersion()==null||r.expectedVersion()<0)throw bad("expectedVersion不合法");if(r.payableAmount()!=null&&(r.payableAmount().signum()<0||r.payableAmount().scale()>2))throw bad("拖车费必须为非负数且最多两位小数");}
@@ -85,13 +83,13 @@ public class TruckAppointmentService {
  private static void verifyClientHash(String clientHash,String serverHash){if(StringUtils.hasText(clientHash)&&!serverHash.equalsIgnoreCase(clientHash.trim()))throw bad("X-Request-Hash与请求内容不一致");}
  private static void validateKey(String key){if(!StringUtils.hasText(key)||key.trim().length()>128)throw bad("Idempotency-Key不能为空且不能超过128个字符");}
  private record ReschedulePayload(LocalDateTime plannedLoadingAt,ActionRequest request){}
+ /** 派车时复核订舱放舱状态及提单号，不要求订舱附件。 */
  private String requireDispatchReady(TruckAppointmentEntity appointment){
   if(appointment.getOceanBookingId()==null)throw conflict("拖车预约缺少订舱关联");
   OceanBookingEntity booking=oceanBookings.find(appointment.getOceanBookingId());
   if(booking==null)throw new BizException(ResultCode.NOT_FOUND,"关联订舱不存在");
   if(!"RELEASED".equals(booking.getStatus()))throw conflict("关联订舱尚未放舱");
   String bill=releasedBookingBill(booking,trim(appointment.getBillOfLadingNo()));
-  oceanBookingDocuments.requireActiveValidDocument(booking);
   return bill;
  }
  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;}

firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: Ocean Booking API
   version: 2.2.0
-  description: Booking-owned files use File businessType OCEAN_BOOKING_DOCUMENT and businessId=oceanBookingId. Release requires at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file. Released transport and declared cargo snapshots and file links are read-only. Manual actual cargo may be supplemented with version, idempotency and audit reason.
+  description: Booking-owned files use File businessType OCEAN_BOOKING_DOCUMENT and businessId=oceanBookingId. 放舱不要求上传订舱确认文件或提单文件。 Released transport and declared cargo snapshots and file links are read-only. Manual actual cargo may be supplemented with version, idempotency and audit reason.
 paths:
   /api/platform/v1/ocean-bookings:
     get:
@@ -48,7 +48,7 @@ paths:
   /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
     post:
       summary: Validate and permanently release a DRAFT
-      description: Release validates the persisted aggregate plus at least one active booking-owned BOOKING_CONFIRMATION or BILL_OF_LADING file. The customer is optional; a supplied customer must remain ACTIVE. Null denotes no single customer snapshot, never public access. It never requires or creates a real container number.
+      description: 放舱校验已保存的订舱业务资料，不以订舱确认文件或提单文件作为前置条件。 The customer is optional; a supplied customer must remain ACTIVE. Null denotes no single customer snapshot, never public access. It never requires or creates a real container number.
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReleaseRequest'}}}}
       responses: {'200': {description: RELEASED detail}}

firstleg/src/main/resources/openapi/truck-appointments-v1.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: Truck Appointment API
   version: 2.0.0
-  description: A truck appointment belongs to one RELEASED ocean booking, independently of when or how that booking's internal containers are linked. Each booking may have at most one non-terminal appointment. The bill-of-lading number and warehouse are frozen from the booking, which must own at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file. Container identities and real container numbers remain in the container/loading modules and are not part of this API. PDA loading completion alone does not complete the appointment. All required containers must be allocated and confirmed departed from the domestic warehouse. Completion atomically creates approved ON_ACCOUNT container payable fees allocated by loaded volume and publishes their immutable snapshots through the existing Finance Outbox. Create, edit, submit and reschedule also recheck departure facts, covering late appointments. Zero amounts create no fee. Cancelled and exception appointments are excluded. RMB is the only appointment currency and maps to CNY in Finance.
+  description: A truck appointment belongs to one RELEASED ocean booking, independently of when or how that booking's internal containers are linked. Each booking may have at most one non-terminal appointment. The bill-of-lading number and warehouse are frozen from the booking. 预约创建及派车不要求订舱附件。 Container identities and real container numbers remain in the container/loading modules and are not part of this API. PDA loading completion alone does not complete the appointment. All required containers must be allocated and confirmed departed from the domestic warehouse. Completion atomically creates approved ON_ACCOUNT container payable fees allocated by loaded volume and publishes their immutable snapshots through the existing Finance Outbox. Create, edit, submit and reschedule also recheck departure facts, covering late appointments. Zero amounts create no fee. Cancelled and exception appointments are excluded. RMB is the only appointment currency and maps to CNY in Finance.
 paths:
   /api/platform/v1/truck-appointments:
     get:
@@ -33,7 +33,7 @@ paths:
   /api/platform/v1/truck-appointments/candidates:
     get:
       summary: Query authoritative create-time ocean-booking candidates
-      description: Requires platform:firstleg:truck-appointment:list. Returns one row per RELEASED booking with a bill of lading and an active booking-owned confirmation or bill file, excluding bookings that already have an active or completed truck appointment. Container allocation and loading status do not affect eligibility. Edit pages display their current booking from appointment detail rather than injecting it into this create-only result.
+      description: Requires platform:firstleg:truck-appointment:list. Returns one row per RELEASED booking with a bill of lading number, excluding bookings that already have an active or completed truck appointment. Container allocation and loading status do not affect eligibility. Edit pages display their current booking from appointment detail rather than injecting it into this create-only result.
       parameters:
         - {name: keyword, in: query, required: false, schema: {type: string, maxLength: 64}, description: Matches booking number or bill of lading}
         - {name: page, in: query, required: false, schema: {type: integer, format: int64, minimum: 1, default: 1}}
@@ -168,7 +168,7 @@ components:
         timestamp: {type: string, format: date-time}
     Candidate:
       type: object
-      required: [oceanBookingId, oceanBookingNo, warehouseId, bookingDocumentReady]
+      required: [oceanBookingId, oceanBookingNo, warehouseId]
       properties:
         oceanBookingId: {type: integer, format: int64}
         oceanBookingNo: {type: string}
@@ -177,7 +177,7 @@ components:
         warehouseName: {type: string, nullable: true}
         channelCode: {type: string, nullable: true}
         channelName: {type: string, nullable: true}
-        bookingDocumentReady: {type: boolean, enum: [true]}
+
     DetailEnvelope:
       type: object
       required: [code, message, data, timestamp]
@@ -221,7 +221,7 @@ components:
       required: [oceanBookingId, 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 have a bill of lading and own an active BOOKING_CONFIRMATION or BILL_OF_LADING file.}
+        oceanBookingId: {type: integer, format: int64, minimum: 1, description: Required RELEASED booking; must have a bill of lading number. 订舱附件不作为前置条件。}
         warehouseId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional consistency hint. The persisted warehouse is frozen from the selected booking.}
         carrierId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE Warehouse supplier ID validated as TRUCKING with truckingScope DOMESTIC (国内拖车).}
         carrierName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; the persisted snapshot comes from Warehouse supplier master data.}

firstleg/src/test/java/com/baiyue/firstleg/controller/TruckAppointmentControllerContractTest.java

@@ -30,7 +30,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","database booking-level unique key");}
- @Test void openApiPublishesBookingLevelCandidateContract() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/candidates:","Paged booking candidates","bookingDocumentReady","Container allocation and loading status do not affect eligibility").doesNotContain("requirementId:","containerBookingId:","loadingPlanId:");}
+ @Test void openApiPublishesBookingLevelCandidateContract() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("/api/platform/v1/truck-appointments/candidates:","Paged booking candidates","Container allocation and loading status do not affect eligibility").doesNotContain("requirementId:","containerBookingId:","loadingPlanId:");}
  @Test void openApiRequiresReleasedBookingWithoutContainerWriteProtocol() throws Exception {String s=new ClassPathResource("openapi/truck-appointments-v1.yaml").getContentAsString(StandardCharsets.UTF_8);assertThat(s).contains("required: [oceanBookingId, carrierId, plannedLoadingAt, expectedVersion]","RELEASED ocean booking","PICKUP does not accept or write a container number","schema: {$ref: '#/components/schemas/DetailEnvelope'}").doesNotContain("containerBookingId:","loadingPlanId:","containerNo:","customerId", "customerName");}
  @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:","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]","default: RMB").doesNotContain("receivableAmount");}

firstleg/src/test/java/com/baiyue/firstleg/oceanbooking/service/OceanBookingServiceTest.java

@@ -118,7 +118,7 @@ class OceanBookingServiceTest {
         assertThat(result.oceanBooking().getStatus()).isEqualTo("RELEASED");
         assertThat(result.oceanBooking().getCustomerId()).isNull();
         assertThat(result.oceanBooking().getCustomerName()).isNull();
-        verify(documents).requireActiveValidDocument(stored.get());
+        verifyNoInteractions(documents);
         verify(customers, times(initialCustomer ? 1 : 0)).active(anyLong(), any());
     }
 
@@ -188,21 +188,22 @@ class OceanBookingServiceTest {
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
     }
 
+    /** 无订舱附件时仍可按完整业务资料放舱。 */
     @Test
-    void rejectsReleaseWithoutActiveBookingOwnedFileWithoutStateDrift() {
+    void releasesWithoutBookingFiles() {
         stubMasterData();
         OceanBookingEntity draft = completeBooking("DRAFT", 3);
-        when(repository.find(1L)).thenReturn(draft);
+        when(repository.find(1L)).thenReturn(draft, completeBooking("RELEASED", 4));
         when(repository.parties(1L)).thenReturn(parties());
         when(repository.requirements(1L)).thenReturn(List.of(requirement()));
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
-            "订舱缺少有效订舱确认或提单文件"))
-            .when(documents).requireActiveValidDocument(draft);
+        when(repository.documents(1L)).thenReturn(List.of());
+        when(repository.transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin")).thenReturn(1);
 
-        assertThatThrownBy(() -> service.release(1L, 9L, "admin", "release-no-file",
-            new ReleaseRequest(3, "确认")))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
-        verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt(), anyLong(), anyString());
+        Detail result = service.release(1L, 9L, "admin", "release-no-file", new ReleaseRequest(3, "确认"));
+        assertThat(result.oceanBooking().getStatus()).isEqualTo("RELEASED");
+        assertThat(result.documents()).isEmpty();
+        verifyNoInteractions(documents);
+        verify(repository).transition(1L, "DRAFT", "RELEASED", 3, 9L, "admin");
     }
 
     @Test

firstleg/src/test/java/com/baiyue/firstleg/repository/TruckAppointmentMapperContractTest.java

@@ -10,6 +10,7 @@ import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
 
 class TruckAppointmentMapperContractTest {
+    /** 候选不依赖附件，仍保留提单号、状态、唯一预约和乐观锁条件。 */
     @Test void mapsToPhase3TableAndUsesOptimisticGuards() throws Exception {
         assertThat(TruckAppointmentEntity.class.getAnnotation(TableName.class).value()).isEqualTo("fl_truck_appointment");
         String page = TruckAppointmentMapper.class.getMethod("page", com.baomidou.mybatisplus.extension.plugins.pagination.Page.class, com.baiyue.firstleg.dto.TruckAppointmentDtos.Query.class).getAnnotation(Select.class).value()[0];
@@ -18,9 +19,10 @@ class TruckAppointmentMapperContractTest {
             .doesNotContain("fl_container_booking", "cabinet_no", "container_no");
         assertThat(page).doesNotContain("customer_id", "customerId", "customer_name");
         String candidates = TruckAppointmentMapper.class.getMethod("candidates", com.baomidou.mybatisplus.extension.plugins.pagination.Page.class, com.baiyue.firstleg.dto.TruckAppointmentDtos.CandidateQuery.class).getAnnotation(Select.class).value()[0];
-        assertThat(candidates).contains("FROM fl_ocean_booking o", "o.status='RELEASED'", "d.valid=1",
-            "'BOOKING_CONFIRMATION','BILL_OF_LADING'", "t.ocean_booking_id=o.id",
-            "t.status NOT IN ('CANCELLED','EXCEPTION')", "bookingDocumentReady");
+        assertThat(candidates).contains("FROM fl_ocean_booking o", "o.status='RELEASED'",
+            "o.bill_of_lading_no IS NOT NULL", "o.bill_of_lading_no<>''", "t.ocean_booking_id=o.id",
+            "t.status NOT IN ('CANCELLED','EXCEPTION')");
+        assertThat(candidates).doesNotContain("fl_ocean_booking_document", "bookingDocumentReady");
         assertThat(candidates).doesNotContain("fl_ocean_booking_container_allocation", "fl_container_booking",
             "loadingPlanId", "containerBookingId", "cabinetNo", "containerNo");
         String transition = TruckAppointmentMapper.class.getMethod("transition", long.class, String.class, String.class, int.class).getAnnotation(Update.class).value()[0];

firstleg/src/test/java/com/baiyue/firstleg/service/TruckAppointmentServiceTest.java

@@ -84,7 +84,7 @@ class TruckAppointmentServiceTest {
     }
 
     @Test void createCandidatesDelegateOneBoundedAuthoritativeQuery() {
-        Candidate candidate = new Candidate(99L, "OB-1", "BL-1", 18L, "义乌仓", "SEA-US", "美西", true);
+        Candidate candidate = new Candidate(99L, "OB-1", "BL-1", 18L, "义乌仓", "SEA-US", "美西");
         when(repository.candidates(any())).thenReturn(new PageResult<>(List.of(candidate), 1, 20, 1, 1));
 
         PageResult<Candidate> result = service.candidates(new CandidateQuery(" OB-1 ", 1, 20));
@@ -170,7 +170,8 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).insert(any());
     }
 
-    @Test void createFreezesBookingBillAndRequiresBookingOwnedDocument() {
+    /** 无附件订舱可创建预约，提单号仍取订舱冻结值。 */
+    @Test void createFreezesBookingBillWithoutRequiringBookingDocument() {
         SaveRequest request = validRequest();
 
         service.create(7L, "admin", request);
@@ -178,7 +179,7 @@ class TruckAppointmentServiceTest {
         ArgumentCaptor<TruckAppointmentEntity> entity = ArgumentCaptor.forClass(TruckAppointmentEntity.class);
         verify(repository).insert(entity.capture());
         assertThat(entity.getValue().getBillOfLadingNo()).isEqualTo("BL-BOOKING-1");
-        verify(oceanBookingDocuments).requireActiveValidDocument(any(OceanBookingEntity.class));
+        verifyNoInteractions(oceanBookingDocuments);
         verifyNoInteractions(files);
     }
 
@@ -307,14 +308,14 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).insert(any());
     }
 
-    @Test void createStillRequiresBookingDocumentWithoutAnyContainerAssociation() {
+    /** 没有附件或货柜关联时，完整已放舱订舱仍可预约。 */
+    @Test void createAllowsBookingWithoutDocumentsOrContainerAssociation() {
         SaveRequest request = validRequest();
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,
-            "订舱缺少有效订舱确认或提单文件"))
-            .when(oceanBookingDocuments).requireActiveValidDocument(any());
-        assertThatThrownBy(() -> service.create(7L, "admin", request))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
-        verify(repository, never()).insert(any());
+        TruckAppointmentEntity result = service.create(7L, "admin", request);
+        assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.DRAFT);
+        assertThat(result.getContainerBookingId()).isNull();
+        verify(repository).insert(any());
+        verifyNoInteractions(oceanBookingDocuments);
     }
 
     @Test void editCanSwitchToAnotherUnoccupiedReleasedBooking() {
@@ -407,7 +408,8 @@ class TruckAppointmentServiceTest {
         verify(repository, never()).history(any());
     }
 
-    @Test void dispatchRequiresBookingBillAndActiveBookingOwnedDocument() {
+    /** 取消附件要求后，派车仍必须具备提单号。 */
+    @Test void dispatchRequiresBookingBill() {
         TruckAppointmentEntity missingBill = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
         missingBill.setOceanBookingId(99L); missingBill.setContainerBookingId(88L);
         OceanBookingEntity bookingWithoutBill = releasedBooking(); bookingWithoutBill.setBillOfLadingNo(null);
@@ -419,21 +421,11 @@ class TruckAppointmentServiceTest {
             "dispatch-no-bill", null, 7L, "admin"))
             .isInstanceOf(BizException.class).hasMessageContaining("提单号");
 
-        TruckAppointmentEntity missingAttachment = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
-        missingAttachment.setOceanBookingId(99L); missingAttachment.setContainerBookingId(88L); missingAttachment.setBillOfLadingNo("BL-BOOKING-1");
-        when(oceanBookings.find(99L)).thenReturn(releasedBooking());
-        when(repository.claimOperation(anyLong(), eq(1L), eq("DISPATCH"), eq("dispatch-no-file"), anyString())).thenReturn(true);
-        when(repository.find(1L)).thenReturn(missingAttachment);
-        doThrow(new BizException(com.baiyue.common.core.api.ResultCode.CONFLICT,"订舱缺少有效订舱确认或提单文件"))
-            .when(oceanBookingDocuments).requireActiveValidDocument(any());
-
-        assertThatThrownBy(() -> service.action(1L, "DISPATCH", new ActionRequest(1, null),
-            "dispatch-no-file", null, 7L, "admin"))
-            .isInstanceOf(BizException.class).hasMessageContaining("有效订舱确认或提单文件");
         verify(repository, never()).dispatch(anyLong(), anyString(), anyString(), anyInt());
     }
 
-    @Test void dispatchFreezesReleasedBookingBillWithoutRequiringRealContainerNumber() {
+    /** 无附件、无真实柜号时可派车，但仍冻结已放舱订舱的提单号并记历史。 */
+    @Test void dispatchFreezesReleasedBookingBillWithoutRequiringDocumentsOrRealContainerNumber() {
         TruckAppointmentEntity before = entity(TruckAppointmentStatus.PENDING_DISPATCH, 1);
         before.setOceanBookingId(99L); before.setContainerBookingId(88L); before.setBillOfLadingNo(null);
         TruckAppointmentEntity after = entity(TruckAppointmentStatus.DISPATCHED, 2);
@@ -452,6 +444,7 @@ class TruckAppointmentServiceTest {
         assertThat(result.getStatus()).isEqualTo(TruckAppointmentStatus.DISPATCHED);
         assertThat(result.getBillOfLadingNo()).isEqualTo("BL-BOOKING-1");
         verify(repository).dispatch(1L, "PENDING_DISPATCH", "BL-BOOKING-1", 1);
+        verifyNoInteractions(oceanBookingDocuments);
         verify(repository, never()).transition(anyLong(), anyString(), anyString(), anyInt());
         verify(repository).history(any(TruckAppointmentHistoryEntity.class));
     }