feat(lastleg): connect appointment followups and fleet intake

2026-10-09 22:04:49 +08:00
parent 1202cafadf
commit 0d75e311d0
54 changed files with 2315 additions and 25 deletions
@@ -6710,6 +6710,8 @@ INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id,
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107280,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107281,0,'PLATFORM','BUTTON',5107280,'platform:appointment:delete','删除预约',NULL,'DELETE',741,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107281,0,CURRENT_TIMESTAMP(3));
+INSERT INTO iam_permission (id, tenant_id, app_code, permission_type, parent_id, permission_code, permission_name, route_path, http_method, sort_no, status, built_in, created_at, updated_at, deleted) VALUES (5107282,0,'PLATFORM','BUTTON',5107280,'platform:appointment:followup','记录预约跟进',NULL,'POST',742,'ACTIVE',1,CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(3),0);
+INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107282,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107010,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107011,0,CURRENT_TIMESTAMP(3));
 INSERT INTO iam_role_permission (role_id, permission_id, tenant_id, created_at) VALUES (4000001,5107012,0,CURRENT_TIMESTAMP(3));
@@ -1479,6 +1479,30 @@ CREATE TABLE ll_order (
  KEY idx_ll_order_container_progress (source_container_booking_id,estimated_warehouse_at,created_at,id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='尾程订单主表';

+CREATE TABLE ll_appointment_followup (
+  id BIGINT NOT NULL COMMENT '预约筹划跟进记录ID',
+  source_key VARCHAR(160) NOT NULL COMMENT '稳定ORDER或BOOKING来源键，不因实收转换而变化',
+  customer_id VARCHAR(128) NOT NULL COMMENT '服务端核实的来源客户',
+  source_order_id BIGINT NULL COMMENT '已形成的真实尾程货源ID，尚未生成时为空',
+  stage VARCHAR(32) NOT NULL COMMENT '跟进对象：DRAYAGE_CONTACT/TERMINAL_APPOINTMENT/WAREHOUSE_RECEIVING/FBA_RECEIVING',
+  version INT NOT NULL COMMENT '同一货源及跟进对象的记录版本',
+  contacted_party VARCHAR(200) NULL COMMENT '本次联系对象，不替代承运主档',
+  result VARCHAR(1000) NOT NULL COMMENT '本次反馈事实，不自动确认预约或推进实物作业',
+  next_action VARCHAR(500) NULL COMMENT '下一步安排',
+  followup_date DATE NULL COMMENT '按业务地点当地日期记录的下次跟进日',
+  operator_id VARCHAR(128) NOT NULL COMMENT '登录平台操作者ID',
+  operator_name VARCHAR(200) NULL COMMENT '操作人姓名快照',
+  command_key VARCHAR(64) NOT NULL COMMENT '持久幂等键',
+  request_hash CHAR(64) NOT NULL COMMENT '含操作者身份的请求SHA256摘要',
+  created_at DATETIME(3) NOT NULL COMMENT 'UTC记录时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_appointment_followup_version (source_key,stage,version),
+  UNIQUE KEY uk_appointment_followup_command (source_key,stage,command_key),
+  KEY idx_appointment_followup_date (followup_date,source_order_id),
+  CONSTRAINT fk_appointment_followup_order FOREIGN KEY (source_order_id) REFERENCES ll_order(id),
+  CONSTRAINT chk_appointment_followup_stage CHECK (stage IN ('DRAYAGE_CONTACT','TERMINAL_APPOINTMENT','WAREHOUSE_RECEIVING','FBA_RECEIVING'))
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='真实在途货源的预约筹划联系记录，追加留痕';
+
 CREATE TABLE ll_order_command_record (
  id bigint NOT NULL COMMENT '尾程订单命令幂等记录ID',
  customer_id varchar(128) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '客户数据隔离键',
@@ -3601,4 +3625,4 @@ CREATE TABLE ll_return_carton_count_session (
  UNIQUE KEY uk_ll_return_count_session_receipt(receipt_id)
 ) ENGINE=InnoDB COMMENT='退货箱内清点单人单任务持久会话';

-SELECT 'PASS' AS initialization_status, 'OVERSEAS' AS region, 160 AS initialized_tables;
+SELECT 'PASS' AS initialization_status, 'OVERSEAS' AS region, 161 AS initialized_tables;
@@ -20,6 +20,7 @@ INSERT INTO iam_permission
 VALUES
  (5107280,0,'PLATFORM','MENU',0,'platform:appointment:list','预约列表','/appointment-calendar','GET',740,'ACTIVE',1,0),
  (5107281,0,'PLATFORM','BUTTON',5107280,'platform:appointment:delete','删除预约',NULL,'DELETE',741,'ACTIVE',1,0),
+  (5107282,0,'PLATFORM','BUTTON',5107280,'platform:appointment:followup','记录预约跟进',NULL,'POST',742,'ACTIVE',1,0),
  (5107000,0,'PLATFORM','MENU',0,'platform:overseas-warehouse:last-mile-order:list','海外尾程订单','/overseas-warehouse/last-mile-orders','GET',700,'ACTIVE',1,0),
  (5107001,0,'PLATFORM','BUTTON',5107000,'platform:overseas-warehouse:last-mile-order:edit','编辑海外尾程订单',NULL,'PUT',701,'ACTIVE',1,0),
  (5107002,0,'PLATFORM','BUTTON',5107000,'platform:overseas-warehouse:last-mile-order:export','导出海外尾程订单',NULL,'GET',702,'ACTIVE',1,0),
@@ -11,7 +11,7 @@

 业务包相对 `src/main/java/com/baiyue/lastleg/`；`src/`、`docs/`、`scripts/`、`../` 相对服务目录。裸类名在指定包内检索。

-拼车需求池：`fleet/trip/FleetCapacityOfferService.java`、`fleet/business/FleetPoolOrderBridge.java`；流程见 `../../docs/海外仓业务/内部拼车需求池首版开发契约.md`。
+拼车接货与车次准备：`fleet/trip/`、`fleet/business/`；合同`fleet-preparation-v1.yaml`，流程见 `../../docs/海外仓业务/内部拼车需求池首版开发契约.md`。

 事件重试：`controller/EventOperationsController.java`，内部 `/internal/lastleg/event-operations/{entryId}` 查询、`/retry` 写入；仅卸柜、派送、暂扣、资金及费用事件，以 `EVENT_OPERATIONS_TOKEN` 保护。原事件不可改，DEAD→PENDING 与 `event_delivery_retry_audit` 同事务；脚本 `scripts/event-outbox-operations.mjs`。

@@ -36,7 +36,7 @@
 | 入仓计划分页、柜级预览、转换与详情 | `inboundplan/controller/InboundPlanController.java` |
 | 自动生成托盘、资源生成失败与重试 | `inboundplan/service/ContainerInboundPlanConversionCoordinator.java` 的 `convertManualAndAutoMaterialize`；详细规则定向查 `docs/business-index.md` 的“人工计划自动生成托盘与资源重试” |
 | 托盘分配算法 | `inboundplan/service/PalletAllocator.java` |
-| 跨客户同仓预约、日历、增删改查 | `InboundPlanController.java` |
+| 跨客户同仓预约、日历 | `InboundPlanController.java`；在途/外接货跟进与覆盖见`appointmentplanning/` |
 | PDA 入仓、柜号签收、实收、上架与完成 | `inboundplan/pda/controller/ReceivingContainerController.java` → `inboundplan/pda/service/ReceivingContainerService.java`；门禁与状态定向查 `docs/business-index.md` 的“PDA 入仓、实收、上架与完成” |
 | PDA 卸柜照片上传、归属校验与预览 | `ReceivingContainerController.java` |
 | PDA 国内装柜照片对照 | `ReceivingContainerController.java` |
@@ -0,0 +1,37 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import lombok.Data;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+/** Read-only loaded cargo, independent of inbound-plan materialization. */
+@Data
+public class AppointmentCargo {
+    private String sourceKey;
+    private Long orderId;
+    private String customerId;
+    private String customerName;
+    private String inboundCode;
+    private String containerBookingId;
+    private String containerNo;
+    private String originWarehouseId;
+    private String originWarehouseCode;
+    private String originWarehouseName;
+    private String destinationWarehouseCode;
+    private Integer packages;
+    private Integer receivedPackages;
+    private Integer shippedPackages;
+    private Integer sourcePalletCount;
+    private BigDecimal volumeCbm;
+    private LocalDateTime estimatedArrivalAt;
+    private LocalDateTime estimatedWarehouseAt;
+    private Integer orderVersion;
+    private String standardNode;
+    private Long shippingVersion;
+    private LocalDateTime shippingObservedAt;
+    private String shippingProvider;
+    private boolean hasInboundPlan;
+    private boolean hasActiveAppointment;
+    private boolean detained;
+    private boolean mixedDestinations;
+}
@@ -0,0 +1,45 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import java.util.List;
+
+@Mapper
+public interface AppointmentCargoMapper {
+    String FILTER = """
+        FROM ll_order o JOIN ll_container_shipping_gate g ON g.container_booking_id=o.source_container_booking_id
+        WHERE o.order_type='FIRST_LEG' AND o.destination_type='FBA' AND g.node_sequence &gt;=40
+        AND o.current_status NOT IN ('CANCELLED','COMPLETED')
+        AND o.overseas_warehouse_id IN
+        <foreach collection='origins' item='id' open='(' separator=',' close=')'>#{id}</foreach>
+        AND o.fba_warehouse_code IN
+        <foreach collection='destinations' item='code' open='(' separator=',' close=')'>#{code}</foreach>
+        <if test='warehouseId != null'>AND o.overseas_warehouse_id=#{warehouseId}</if>
+        <if test='destination != null'>AND o.fba_warehouse_code=#{destination}</if>
+        <if test='keyword != null'>AND (o.inbound_code LIKE CONCAT('%',#{keyword},'%') OR o.container_no LIKE CONCAT('%',#{keyword},'%') OR o.customer_name LIKE CONCAT('%',#{keyword},'%'))</if>
+        """;
+
+    @Select("<script>SELECT COUNT(*) " + FILTER + "</script>")
+    long count(@Param("origins") List<String> origins, @Param("destinations") List<String> destinations,
+               @Param("warehouseId") String warehouseId, @Param("destination") String destination, @Param("keyword") String keyword);
+
+    @Select("<script>" + """
+        SELECT CONCAT('ORDER:',o.id) AS source_key,o.id AS order_id,o.customer_id,o.customer_name,o.inbound_code,
+          o.source_container_booking_id AS container_booking_id,o.container_no,
+          o.overseas_warehouse_id AS origin_warehouse_id,o.overseas_warehouse_code AS origin_warehouse_code,
+          o.overseas_warehouse_name AS origin_warehouse_name,o.fba_warehouse_code AS destination_warehouse_code,
+          o.package_count AS packages,o.received_package_count AS received_packages,o.shipped_package_count AS shipped_packages,
+          o.pallet_count AS source_pallet_count,o.volume_cbm,o.estimated_arrival_at,o.estimated_warehouse_at,
+          o.version AS order_version,g.standard_node,g.aggregate_version AS shipping_version,
+          g.observed_at AS shipping_observed_at,g.provider_code AS shipping_provider,o.detained,
+          EXISTS(SELECT 1 FROM ll_inbound_plan p WHERE p.source_order_id=o.id AND p.customer_id=o.customer_id) AS has_inbound_plan,
+          EXISTS(SELECT 1 FROM ll_inbound_fba_appointment_item i JOIN ll_inbound_fba_appointment a ON a.id=i.appointment_id
+            WHERE i.order_id=o.id AND i.customer_id=o.customer_id AND a.appointment_status NOT IN ('CANCELLED','FAILED')) AS has_active_appointment,
+          EXISTS(SELECT 1 FROM ll_order_detail d WHERE d.order_id=o.id AND d.customer_id=o.customer_id
+            AND d.destination_warehouse_code IS NOT NULL AND d.destination_warehouse_code&lt;&gt;o.fba_warehouse_code) AS mixed_destinations
+        """ + FILTER + " ORDER BY o.created_at DESC,o.id DESC LIMIT #{size} OFFSET #{offset}</script>")
+    List<AppointmentCargo> page(@Param("origins") List<String> origins, @Param("destinations") List<String> destinations,
+                               @Param("warehouseId") String warehouseId, @Param("destination") String destination,
+                               @Param("keyword") String keyword, @Param("size") int size, @Param("offset") long offset);
+}
@@ -0,0 +1,57 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baiyue.common.core.api.PageResult;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.web.server.ResponseStatusException;
+import java.util.List;
+import java.util.Set;
+
+@Service
+public class AppointmentCargoService {
+    private final AppointmentCargoMapper mapper;
+    private final AppointmentWarehouseClient warehouses;
+    private final String token;
+
+    public AppointmentCargoService(AppointmentCargoMapper mapper, AppointmentWarehouseClient warehouses,
+                                   @Value("${baiyue.security.internal-service-token:}") String token) {
+        this.mapper = mapper; this.warehouses = warehouses; this.token = token;
+    }
+
+    public PageResult<AppointmentCargo> page(int page, int size, String warehouseId, String destination, String keyword) {
+        if (page < 1 || size < 1 || size > 100) throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "每页数量必须为1至100");
+        if (keyword != null && keyword.length() > 128) throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "搜索词过长");
+        var scope = scope();
+        var origins = scope.origins();
+        var destinations = scope.destinations();
+        warehouseId = clean(warehouseId); destination = clean(destination); keyword = clean(keyword);
+        if (warehouseId != null && !origins.contains(warehouseId) || destination != null && !destinations.contains(destination)) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "请选择已启用的美国接仓点及FBA目的仓");
+        }
+        if (origins.isEmpty() || destinations.isEmpty()) return new PageResult<>(List.of(), page, size, 0, 0);
+        long total = mapper.count(origins, destinations, warehouseId, destination, keyword);
+        var rows = mapper.page(origins, destinations, warehouseId, destination, keyword, size, (long) (page - 1) * size);
+        return new PageResult<>(rows, page, size, total, (total + size - 1) / size);
+    }
+
+    private record Scope(List<String> origins, List<String> destinations) { }
+    private Scope scope() {
+        final List<AppointmentWarehouseClient.Warehouse> catalog;
+        try {
+            var result = warehouses.catalog(token);
+            if (result == null || !result.successful() || result.data() == null) throw new IllegalStateException();
+            catalog = result.data();
+        } catch (RuntimeException error) {
+            throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "仓库目录暂不可用，无法核实美国货物范围", error);
+        }
+        var us = catalog.stream().filter(w -> w != null && w.id() != null && w.id() > 0 && "US".equals(w.countryCode())).toList();
+        var origins = us.stream().filter(w -> Set.of("OVERSEAS", "OVERSEAS_PARTNER").contains(w.warehouseType() == null ? "" : w.warehouseType()))
+            .map(w -> w.id().toString()).distinct().toList();
+        var destinations = us.stream().filter(w -> "FBA".equals(w.warehouseType()) && clean(w.warehouseCode()) != null)
+            .map(AppointmentWarehouseClient.Warehouse::warehouseCode).distinct().toList();
+        return new Scope(origins, destinations);
+    }
+
+    private static String clean(String value) { return value == null || value.isBlank() ? null : value.trim(); }
+}
@@ -0,0 +1,37 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import java.time.LocalDateTime;
+import java.util.List;
+
+@Mapper
+public interface AppointmentCoverageMapper {
+    record OrderRef(String customerId, Long orderId) { }
+    record Source(Long orderId, String customerId, String destinationType, String fbaWarehouseCode,
+                  Integer packages, Integer version, LocalDateTime updatedAt, boolean shipmentReferencesMissing) { }
+    record Fact(Long orderId, String customerId, String appointmentNo, String status,
+                LocalDateTime appointmentAt, LocalDateTime appointmentEndAt, LocalDateTime updatedAt,
+                Long lineId, Integer packages, String warehouseCode) { }
+
+    @Select({"<script>SELECT o.id AS orderId,o.customer_id AS customerId,o.destination_type AS destinationType,",
+        "o.fba_warehouse_code AS fbaWarehouseCode,o.package_count AS packages,o.version,o.updated_at AS updatedAt, ",
+        "(NOT EXISTS(SELECT 1 FROM ll_order_detail d WHERE d.order_id=o.id AND d.customer_id=o.customer_id) OR ",
+        "EXISTS(SELECT 1 FROM ll_order_detail d WHERE d.order_id=o.id AND d.customer_id=o.customer_id ",
+        "AND (d.shipment_no IS NULL OR TRIM(d.shipment_no)='') AND (d.fba_tracking_no IS NULL OR TRIM(d.fba_tracking_no)=''))) AS shipmentReferencesMissing ",
+        "FROM ll_order o WHERE <foreach collection='sources' item='s' open='(' separator=' OR ' close=')'>",
+        "(o.id=#{s.orderId} AND o.customer_id=#{s.customerId})</foreach></script>"})
+    List<Source> sources(@Param("sources") List<OrderRef> sources);
+
+    @Select({"<script>SELECT i.order_id AS orderId,i.customer_id AS customerId,a.appointment_no AS appointmentNo,",
+        "a.appointment_status AS status,a.appointment_at AS appointmentAt,a.appointment_end_at AS appointmentEndAt,",
+        "a.updated_at AS updatedAt,i.line_id AS lineId,l.required_package_count AS packages,l.fba_warehouse_code AS warehouseCode ",
+        "FROM ll_inbound_fba_appointment_item i JOIN ll_inbound_fba_appointment a ON a.id=i.appointment_id ",
+        "JOIN ll_inbound_plan_line l ON l.id=i.line_id AND l.plan_id=i.plan_id AND l.order_id=i.order_id AND l.customer_id=i.customer_id ",
+        "WHERE a.appointment_status NOT IN ('FAILED','CANCELLED') AND ",
+        "<foreach collection='sources' item='s' open='(' separator=' OR ' close=')'>",
+        "(i.order_id=#{s.orderId} AND i.customer_id=#{s.customerId})</foreach>",
+        " ORDER BY a.appointment_at,a.id,i.id</script>"})
+    List<Fact> appointments(@Param("sources") List<OrderRef> sources);
+}
@@ -0,0 +1,101 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import org.springframework.stereotype.Service;
+import java.time.LocalDateTime;
+import java.util.*;
+import java.util.stream.Collectors;
+
+/** Shared read projection. Callers authorize the customer/source before invoking; never confirms bookings. */
+@Service
+public class AppointmentCoverageService {
+    public record SourceRef(String customerId, String sourceKey, String destinationKey) { }
+    public record Appointment(String appointmentNo, String confirmationNo, String status,
+                              LocalDateTime confirmedAt, LocalDateTime confirmedEndAt, String timezone) { }
+    public record Coverage(String customerId, String sourceKey, String destinationKey, String status,
+                           List<Appointment> appointments, List<String> missingFields,
+                           String sourceVersion, boolean changeReviewRequired) { }
+    private final AppointmentCoverageMapper mapper;
+    private final AppointmentExternalSourceGateway external;
+    public AppointmentCoverageService(AppointmentCoverageMapper mapper, AppointmentExternalSourceGateway external) {
+        this.mapper=mapper; this.external=external;
+    }
+
+    public List<Coverage> query(List<SourceRef> input) {
+        if (input==null || input.isEmpty()) return List.of();
+        if (input.size()>100 || input.stream().anyMatch(s -> s==null || blank(s.customerId()) || blank(s.sourceKey()) || blank(s.destinationKey()))) {
+            throw new IllegalArgumentException("每次最多核对100个完整的预约来源");
+        }
+        var requested=input.stream().distinct().toList();
+        var externalRefs=requested.stream().filter(s -> s.sourceKey().startsWith("BOOKING:"))
+            .map(s -> new AppointmentExternalSourceGateway.SourceRef(s.customerId(),s.sourceKey().substring(8))).toList();
+        var bookings=externalRefs.isEmpty() ? List.<AppointmentExternalSourceGateway.Source>of() : external.resolve(externalRefs);
+        var bookingMap=bookings.stream().collect(Collectors.toMap(s -> key(s.customerId(),"BOOKING:"+s.bookingNo()),s -> s));
+        var refs=new LinkedHashMap<SourceRef,AppointmentCoverageMapper.OrderRef>();
+        for (var source:requested) {
+            if (source.sourceKey().startsWith("ORDER:")) {
+                try {
+                    long id=Long.parseLong(source.sourceKey().substring(6));
+                    if (id>0) refs.put(source,new AppointmentCoverageMapper.OrderRef(source.customerId(),id));
+                } catch (NumberFormatException ignored) { /* Invalid source is returned explicitly below. */ }
+            } else if (source.sourceKey().startsWith("BOOKING:")) {
+                var booking=bookingMap.get(key(source.customerId(),source.sourceKey()));
+                if (booking!=null && booking.orderId()!=null && Objects.equals(source.destinationKey(),booking.destinationKey())) {
+                    refs.put(source,new AppointmentCoverageMapper.OrderRef(source.customerId(),booking.orderId()));
+                }
+            }
+        }
+        var unique=refs.values().stream().distinct().toList();
+        if (unique.size()!=refs.size()) throw new IllegalArgumentException("同一货物存在重复来源，请保留原外接登记来源后再核对");
+        var orders=unique.isEmpty() ? List.<AppointmentCoverageMapper.Source>of() : mapper.sources(unique);
+        var orderMap=orders.stream().collect(Collectors.toMap(s -> new AppointmentCoverageMapper.OrderRef(s.customerId(),s.orderId()),s -> s));
+        var facts=unique.isEmpty() ? List.<AppointmentCoverageMapper.Fact>of() : mapper.appointments(unique);
+        var byOrder=facts.stream().collect(Collectors.groupingBy(f -> new AppointmentCoverageMapper.OrderRef(f.customerId(),f.orderId())));
+        var output=new ArrayList<Coverage>();
+        for (var source:requested) {
+            var booking=bookingMap.get(key(source.customerId(),source.sourceKey()));
+            if (booking!=null && !source.destinationKey().equals(booking.destinationKey())) {
+                output.add(empty(source,"DESTINATION_MISMATCH","DESTINATION",version(booking.recordVersion()),true)); continue;
+            }
+            if (booking!=null && !Set.of("CONFIRMED","RECEIVED","BOUND").contains(booking.bookingStatus()==null ? "" : booking.bookingStatus())) {
+                output.add(empty(source,"SOURCE_NOT_READY","CARRIER_CONFIRMATION",version(booking.recordVersion()),false)); continue;
+            }
+            var order=orderMap.get(refs.get(source));
+            if (order==null) {
+                output.add(empty(source,booking==null ? "SOURCE_NOT_FOUND" : "SOURCE_NOT_MATERIALIZED","REAL_CARGO_MATERIALS",booking==null ? null : version(booking.recordVersion()),false)); continue;
+            }
+            if (!"FBA".equals(order.destinationType()) || !source.destinationKey().equals("FBA:"+order.fbaWarehouseCode())) {
+                output.add(empty(source,"DESTINATION_MISMATCH","DESTINATION",version(order.version()),true)); continue;
+            }
+            var relevant=byOrder.getOrDefault(refs.get(source),List.of());
+            var distinct=new LinkedHashMap<String,Appointment>();
+            var seen=new HashSet<Long>(); long confirmed=0, covered=0; boolean invalid=false, changed=false;
+            for (var fact:relevant) {
+                if (!Objects.equals(order.fbaWarehouseCode(),fact.warehouseCode()) || fact.packages()==null || fact.packages()<=0 || !seen.add(fact.lineId())) { invalid=true; continue; }
+                covered+=fact.packages();
+                if ("SUCCESS".equals(fact.status()) && fact.appointmentAt()!=null) confirmed+=fact.packages();
+                boolean success="SUCCESS".equals(fact.status());
+                distinct.putIfAbsent(fact.appointmentNo(),new Appointment(fact.appointmentNo(),success ? fact.appointmentNo() : null,fact.status(),success ? fact.appointmentAt() : null,success ? fact.appointmentEndAt() : null,null));
+                changed|=order.updatedAt()==null || fact.updatedAt()==null || order.updatedAt().isAfter(fact.updatedAt());
+            }
+            var missing=new ArrayList<String>();
+            String status;
+            if (invalid || order.packages()==null || order.packages()<=0 || covered>order.packages()) { status="REVIEW_REQUIRED"; missing.add("CARGO_QUANTITY_REVIEW"); }
+            else if (covered==0) { status="UNASSIGNED"; missing.add("RECEIVING_APPOINTMENT"); }
+            else if (covered<order.packages()) { status="PARTIAL"; missing.add("UNCOVERED_CARGO"); }
+            else if (confirmed<order.packages()) { status="PENDING"; missing.add("RECEIVING_CONFIRMATION"); }
+            else { status="CONFIRMED"; }
+            if (confirmed>0) missing.add("APPOINTMENT_TIMEZONE_UNVERIFIED");
+            if (order.shipmentReferencesMissing()) missing.add("FBA_SHIPMENT_REFERENCES");
+            if (changed) missing.add("SOURCE_CHANGED_REVIEW");
+            output.add(new Coverage(source.customerId(),source.sourceKey(),source.destinationKey(),status,List.copyOf(distinct.values()),List.copyOf(missing),
+                (booking==null ? "" : "BOOKING:"+version(booking.recordVersion())+"/")+"ORDER:"+version(order.version()),changed || invalid));
+        }
+        return List.copyOf(output);
+    }
+    private static Coverage empty(SourceRef s,String status,String missing,String version,boolean review) {
+        return new Coverage(s.customerId(),s.sourceKey(),s.destinationKey(),status,List.of(),List.of(missing),version,review);
+    }
+    private static String key(String customerId,String sourceKey) { return customerId+"\n"+sourceKey; }
+    private static String version(Number version) { return version==null ? null : version.toString(); }
+    private static boolean blank(String value) { return value==null || value.isBlank(); }
+}
@@ -0,0 +1,11 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import java.util.List;
+
+/** Implemented by the external-booking owner; planning must not query Fleet's persistence directly. */
+public interface AppointmentExternalSourceGateway {
+    record SourceRef(String customerId, String bookingNo) { }
+    record Source(String customerId, String bookingNo, String tripNo, String bookingStatus,
+                  String warehouseId, String destinationKey, Long orderId, Integer packageCount, Long recordVersion) { }
+    List<Source> resolve(List<SourceRef> sources);
+}
@@ -0,0 +1,28 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+
+@Data
+@TableName("ll_appointment_followup")
+public class AppointmentFollowup {
+    @TableId(type = IdType.INPUT) private Long id;
+    private Long sourceOrderId;
+    private String sourceKey;
+    private String customerId;
+    private String stage;
+    private Integer version;
+    private String contactedParty;
+    private String result;
+    private String nextAction;
+    private LocalDate followupDate;
+    private String operatorId;
+    private String operatorName;
+    private String commandKey;
+    private String requestHash;
+    private LocalDateTime createdAt;
+}
@@ -0,0 +1,19 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import java.util.List;
+
+@Mapper
+public interface AppointmentFollowupMapper extends BaseMapper<AppointmentFollowup> {
+    @Select("SELECT * FROM ll_appointment_followup WHERE source_key=#{sourceKey} AND customer_id=#{customerId} AND stage=#{stage} AND command_key=#{key}")
+    AppointmentFollowup command(@Param("sourceKey") String sourceKey, @Param("customerId") String customerId, @Param("stage") String stage, @Param("key") String key);
+    @Select("SELECT COALESCE(MAX(version),0) FROM ll_appointment_followup WHERE source_key=#{sourceKey} AND customer_id=#{customerId} AND stage=#{stage}")
+    int version(@Param("sourceKey") String sourceKey, @Param("customerId") String customerId, @Param("stage") String stage);
+    @Select("SELECT * FROM ll_appointment_followup WHERE source_key=#{sourceKey} AND customer_id=#{customerId} ORDER BY created_at DESC,id DESC LIMIT #{size} OFFSET #{offset}")
+    List<AppointmentFollowup> page(@Param("sourceKey") String sourceKey, @Param("customerId") String customerId, @Param("size") int size, @Param("offset") long offset);
+    @Select("SELECT COUNT(*) FROM ll_appointment_followup WHERE source_key=#{sourceKey} AND customer_id=#{customerId}")
+    long count(@Param("sourceKey") String sourceKey, @Param("customerId") String customerId);
+}
@@ -0,0 +1,83 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import com.baiyue.common.core.api.PageResult;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.validation.constraints.*;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.server.ResponseStatusException;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.HexFormat;
+import java.nio.charset.StandardCharsets;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.time.Instant;
+import java.util.Set;
+
+@Service
+public class AppointmentFollowupService {
+    private final AppointmentSourceService sources;
+    private final AppointmentFollowupMapper mapper;
+    private final ObjectMapper json;
+    public AppointmentFollowupService(AppointmentSourceService sources, AppointmentFollowupMapper mapper, ObjectMapper json) {
+        this.sources = sources; this.mapper = mapper; this.json = json;
+    }
+    public record Save(@NotBlank @Size(max=32) String stage, @Min(0) int expectedVersion,
+                       @NotBlank @Size(max=64) String idempotencyKey,
+                       @Size(max=200) String contactedParty, @NotBlank @Size(max=1000) String result,
+                       @Size(max=500) String nextAction, LocalDate followupDate) { }
+    public record Record(String stage, int version, String contactedParty, String result, String nextAction,
+                         LocalDate followupDate, String operatorName, Instant createdAt) { }
+    public record History(PageResult<Record> history, java.util.Map<String,Integer> versions) { }
+    private static final Set<String> STAGES = Set.of("DRAYAGE_CONTACT", "TERMINAL_APPOINTMENT", "WAREHOUSE_RECEIVING", "FBA_RECEIVING");
+
+    public History history(String sourceKey, String customerId, int page, int size) {
+        if (page<1 || size<1 || size>100) throw new ResponseStatusException(HttpStatus.BAD_REQUEST,"分页参数无效");
+        long total = mapper.count(sourceKey,customerId);
+        if (total == 0) sources.resolve(sourceKey,customerId,null);
+        var records = mapper.page(sourceKey,customerId,size,(long)(page-1)*size).stream().map(AppointmentFollowupService::view).toList();
+        var versions = new java.util.LinkedHashMap<String,Integer>();
+        STAGES.stream().sorted().forEach(stage -> versions.put(stage, mapper.version(sourceKey,customerId,stage)));
+        return new History(new PageResult<>(records,page,size,total,(total+size-1)/size),versions);
+    }
+
+    @Transactional(isolation = org.springframework.transaction.annotation.Isolation.READ_COMMITTED)
+    public Record save(String sourceKey, String customerId, Save request, String operatorId, String operatorName) {
+        if (!STAGES.contains(request.stage())) throw new ResponseStatusException(HttpStatus.BAD_REQUEST,"请选择有效跟进事项");
+        if (request.followupDate()!=null && (request.nextAction()==null || request.nextAction().isBlank())) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST,"设置跟进日期时请填写下一步安排");
+        }
+        final String hash;
+        try { hash = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest((customerId+"\n"+operatorId+"\n"+json.writeValueAsString(request)).getBytes(StandardCharsets.UTF_8))); }
+        catch (JsonProcessingException | NoSuchAlgorithmException error) { throw new IllegalStateException("无法保存跟进请求",error); }
+        var existing = mapper.command(sourceKey,customerId,request.stage(),request.idempotencyKey());
+        if (existing!=null) {
+            if (!hash.equals(existing.getRequestHash())) throw new ResponseStatusException(HttpStatus.CONFLICT,"重复请求内容不一致，请核对跟进记录");
+            return view(existing);
+        }
+        var source = sources.resolve(sourceKey,customerId,null);
+        if (!source.canFollowup()) throw new ResponseStatusException(HttpStatus.CONFLICT,"当前来源仅可查看，请先核对承运状态");
+        if (mapper.version(sourceKey,customerId,request.stage())!=request.expectedVersion()) throw new ResponseStatusException(HttpStatus.CONFLICT,"跟进记录已更新，请重新读取后提交");
+        var value = new AppointmentFollowup(); value.setId(IdWorker.getId()); value.setSourceOrderId(source.orderId()); value.setSourceKey(source.sourceKey()); value.setCustomerId(source.customerId());
+        value.setStage(request.stage()); value.setVersion(request.expectedVersion()+1); value.setContactedParty(clean(request.contactedParty()));
+        value.setResult(request.result().trim()); value.setNextAction(clean(request.nextAction())); value.setFollowupDate(request.followupDate());
+        value.setOperatorId(operatorId); value.setOperatorName(clean(operatorName)); value.setCommandKey(request.idempotencyKey());
+        value.setRequestHash(hash); value.setCreatedAt(LocalDateTime.now(ZoneOffset.UTC));
+        try { mapper.insert(value); }
+        catch (org.springframework.dao.DuplicateKeyException conflict) {
+            var raced = mapper.command(sourceKey,customerId,request.stage(),request.idempotencyKey());
+            if (raced!=null && hash.equals(raced.getRequestHash())) return view(raced);
+            throw new ResponseStatusException(HttpStatus.CONFLICT,"跟进记录已更新或请求内容冲突，请重新读取",conflict);
+        }
+        return view(value);
+    }
+    private static String clean(String value) { return value==null || value.isBlank() ? null : value.trim(); }
+    private static Record view(AppointmentFollowup row) {
+        return new Record(row.getStage(),row.getVersion(),row.getContactedParty(),row.getResult(),row.getNextAction(),row.getFollowupDate(),row.getOperatorName(),row.getCreatedAt().toInstant(ZoneOffset.UTC));
+    }
+}
@@ -0,0 +1,70 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.security.AuthenticatedUser;
+import org.springframework.http.HttpStatus;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestBody;
+import jakarta.validation.Valid;
+import org.springframework.web.server.ResponseStatusException;
+
+@RestController
+@RequestMapping("/api/platform/v1/last-leg/appointment-planning")
+public class AppointmentPlanningController {
+    private final AppointmentCargoService service;
+    private final AppointmentFollowupService followups;
+    private final AppointmentSourceService sources;
+    private final AppointmentCoverageService coverage;
+    public AppointmentPlanningController(AppointmentCargoService service, AppointmentFollowupService followups,
+                                         AppointmentSourceService sources, AppointmentCoverageService coverage) {
+        this.service = service; this.followups = followups; this.sources = sources; this.coverage = coverage;
+    }
+    public record Resolved(AppointmentSourceService.Source source, AppointmentCoverageService.Coverage coverage) { }
+
+    @GetMapping("/sources/resolve")
+    @PreAuthorize("hasAuthority('platform:appointment:list') and hasAuthority('platform:overseas-warehouse:last-mile-order:list')")
+    public ApiResponse<Resolved> resolve(@AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam String sourceKey, @RequestParam String customerId, @RequestParam(required=false) String destinationKey) {
+        requirePlatform(user);
+        var source = sources.resolve(sourceKey,customerId,destinationKey);
+        var result = coverage.query(java.util.List.of(new AppointmentCoverageService.SourceRef(source.customerId(),source.sourceKey(),source.destinationKey())));
+        return ApiResponse.success(new Resolved(source,result.get(0)));
+    }
+
+    @GetMapping("/cargo")
+    @PreAuthorize("hasAuthority('platform:appointment:list') and hasAuthority('platform:overseas-warehouse:last-mile-order:list')")
+    public ApiResponse<PageResult<AppointmentCargo>> cargo(@AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(defaultValue = "1") int page, @RequestParam(defaultValue = "20") int size,
+        @RequestParam(required = false) String warehouseId, @RequestParam(required = false) String destination,
+        @RequestParam(required = false) String keyword) {
+        requirePlatform(user);
+        return ApiResponse.success(service.page(page, size, warehouseId, destination, keyword));
+    }
+
+    @GetMapping("/sources/{sourceKey}/follow-ups")
+    @PreAuthorize("hasAuthority('platform:appointment:list') and hasAuthority('platform:overseas-warehouse:last-mile-order:list')")
+    public ApiResponse<AppointmentFollowupService.History> history(@AuthenticationPrincipal AuthenticatedUser user,
+        @PathVariable String sourceKey, @RequestParam String customerId, @RequestParam(defaultValue="1") int page, @RequestParam(defaultValue="20") int size) {
+        requirePlatform(user); return ApiResponse.success(followups.history(sourceKey,customerId,page,size));
+    }
+
+    @PostMapping("/sources/{sourceKey}/follow-ups")
+    @PreAuthorize("hasAuthority('platform:appointment:list') and hasAuthority('platform:overseas-warehouse:last-mile-order:list') and hasAuthority('platform:appointment:followup')")
+    public ApiResponse<AppointmentFollowupService.Record> followup(@AuthenticationPrincipal AuthenticatedUser user,
+        @PathVariable String sourceKey, @RequestParam String customerId, @Valid @RequestBody AppointmentFollowupService.Save request) {
+        requirePlatform(user);
+        return ApiResponse.success(followups.save(sourceKey,customerId,request,user.userId().toString(),user.displayName()==null ? user.username() : user.displayName()));
+    }
+    private static void requirePlatform(AuthenticatedUser user) {
+        if (user == null || user.userId()==null) throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
+        if (!"PLATFORM".equals(user.appCode()) || !Long.valueOf(0).equals(user.tenantId())) throw new ResponseStatusException(HttpStatus.FORBIDDEN);
+    }
+}
@@ -0,0 +1,83 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import java.time.Instant;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+
+/** Stage-specific planning rules. Planning never creates stock, vehicles or carrier confirmations. */
+public final class AppointmentPlanningPolicy {
+    private AppointmentPlanningPolicy() { }
+
+    public record Cargo(String sourceKey, String customerId, String originWarehouseId,
+                        String destinationKey, String originCountry, String destinationCountry,
+                        Integer packages, Instant readyFrom, Instant readyTo,
+                        boolean eligibleForPlanning, String blockReason) { }
+    public record Group(String originWarehouseId, String destinationKey, long packages,
+                        int sourceCount, int customerCount, Instant readyFrom, Instant readyTo,
+                        boolean readinessIncomplete) { }
+    public record Forecast(String sourceKey, String sourceVersion, Instant eta, Instant readyAt) { }
+    public record Impact(String sourceKey, String reason, Instant previousEta, Instant latestEta,
+                         Instant confirmedAt, boolean reviewRequired) { }
+
+    public static Group group(List<Cargo> cargo) {
+        if (cargo == null || cargo.isEmpty()) throw new IllegalArgumentException("请选择需要安排的真实货物");
+        if (cargo.size() > 500) throw new IllegalArgumentException("每批最多选择500条来源货物");
+        Set<String> sources = new HashSet<>();
+        Set<String> customers = new HashSet<>();
+        String origin = null, destination = null;
+        long packages = 0;
+        Instant from = null, to = null;
+        boolean incomplete = false;
+        for (Cargo row : cargo) {
+            if (row == null || blank(row.sourceKey()) || blank(row.customerId())) {
+                throw new IllegalArgumentException("货物缺少稳定来源或客户归属");
+            }
+            if (!sources.add(row.sourceKey())) throw new IllegalArgumentException("同一来源货物不能重复选择");
+            if (!row.eligibleForPlanning()) throw new IllegalArgumentException(
+                blank(row.blockReason()) ? "所选货物暂不具备筹划资格" : row.blockReason());
+            if (!"US".equals(row.originCountry()) || !"US".equals(row.destinationCountry())) {
+                throw new IllegalArgumentException("请选择已确认美国起运点及目的地的货物");
+            }
+            if (blank(row.originWarehouseId()) || blank(row.destinationKey())) {
+                throw new IllegalArgumentException("货物缺少实际接仓点或目的地");
+            }
+            if (origin == null) { origin = row.originWarehouseId(); destination = row.destinationKey(); }
+            if (!origin.equals(row.originWarehouseId()) || !destination.equals(row.destinationKey())) {
+                throw new IllegalArgumentException("同批货物必须具有相同实际起运仓和目的地");
+            }
+            if (row.packages() == null || row.packages() <= 0) throw new IllegalArgumentException("货物箱数待核实，不能填默认数量");
+            packages = Math.addExact(packages, row.packages().longValue());
+            customers.add(row.customerId());
+            if (row.readyFrom() == null || row.readyTo() == null) incomplete = true;
+            if (row.readyFrom() != null && row.readyTo() != null && row.readyTo().isBefore(row.readyFrom())) {
+                throw new IllegalArgumentException("货物预计备妥窗口无效");
+            }
+            if (row.readyFrom() != null && (from == null || row.readyFrom().isAfter(from))) from = row.readyFrom();
+            if (row.readyTo() != null && (to == null || row.readyTo().isBefore(to))) to = row.readyTo();
+        }
+        if (from != null && to != null && to.isBefore(from)) throw new IllegalArgumentException("所选货物预计备妥窗口不相容，请分别安排");
+        return new Group(origin, destination, packages, sources.size(), customers.size(), from, to, incomplete);
+    }
+
+    /** A new forecast only requests review; it never changes an externally confirmed appointment. */
+    public static Impact compare(Forecast acknowledged, Forecast latest, Instant confirmedAt) {
+        if (acknowledged == null || latest == null || blank(latest.sourceKey())
+            || !Objects.equals(acknowledged.sourceKey(), latest.sourceKey())) {
+            throw new IllegalArgumentException("只能比较同一真实货源的预测");
+        }
+        boolean changed = !Objects.equals(acknowledged.eta(), latest.eta())
+            || !Objects.equals(acknowledged.readyAt(), latest.readyAt());
+        String reason = "UNCHANGED";
+        if (changed) {
+            reason = latest.eta() == null ? "FORECAST_MISSING" : "FORECAST_CHANGED";
+            if (confirmedAt != null && latest.readyAt() != null && latest.readyAt().isAfter(confirmedAt)) {
+                reason = "READINESS_AFTER_APPOINTMENT";
+            }
+        }
+        return new Impact(latest.sourceKey(), reason, acknowledged.eta(), latest.eta(), confirmedAt, changed);
+    }
+
+    private static boolean blank(String value) { return value == null || value.isBlank(); }
+}
@@ -0,0 +1,86 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baiyue.lastleg.mapper.LastlegOrderMapper;
+import com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.web.server.ResponseStatusException;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+
+@Service
+public class AppointmentSourceService {
+    public record Source(String sourceKey, String customerId, Long orderId, String inboundCode, String bookingNo,
+                         String containerNo, String originWarehouseId, String originWarehouseName,
+                         String destinationKey, String destinationWarehouseCode, Integer packages,
+                         String sourceVersion, boolean canFollowup, List<String> blockReasons) { }
+    private final LastlegOrderMapper orders;
+    private final ContainerShippingGateMapper shipping;
+    private final AppointmentExternalSourceGateway external;
+    private final AppointmentWarehouseClient warehouses;
+    private final String token;
+    public AppointmentSourceService(LastlegOrderMapper orders, ContainerShippingGateMapper shipping,
+                                    AppointmentExternalSourceGateway external, AppointmentWarehouseClient warehouses,
+                                    @Value("${baiyue.security.internal-service-token:}") String token) {
+        this.orders=orders; this.shipping=shipping; this.external=external; this.warehouses=warehouses; this.token=token;
+    }
+    public Source resolve(String sourceKey,String customerId,String destinationKey) {
+        if (blank(sourceKey) || sourceKey.length()>160 || blank(customerId) || customerId.length()>128) throw bad("请选择完整的真实货源");
+        com.baiyue.lastleg.entity.LastlegOrder order=null;
+        String bookingNo=null,origin,destination,version;
+        Integer packages;
+        boolean followup=true;
+        List<String> reasons=List.of();
+        if (sourceKey.startsWith("ORDER:")) {
+            long id;
+            try { id=Long.parseLong(sourceKey.substring(6)); if (id<=0 || !sourceKey.equals("ORDER:"+id)) throw new NumberFormatException(); }
+            catch (NumberFormatException error) { throw bad("货源标识无效"); }
+            order=orders.selectById(id);
+            if (order==null || !customerId.equals(order.getCustomerId())) throw missing();
+            if (!"FIRST_LEG".equals(order.getOrderType())) throw bad("请从原外接登记继续跟进，避免重复建立货源");
+            var gate=order.getSourceContainerBookingId()==null ? null : shipping.selectById(order.getSourceContainerBookingId());
+            if (gate==null || gate.getNodeSequence()==null || gate.getNodeSequence()<40) throw bad("货物尚无已开船或后续实际船节点");
+            origin=order.getOverseasWarehouseId(); destination="FBA:"+order.getFbaWarehouseCode();
+            if (!"FBA".equals(order.getDestinationType())) throw bad("当前货源不是FBA送仓货物");
+            packages=order.getPackageCount(); version=order.getVersion()==null ? null : "ORDER:"+order.getVersion();
+        } else if (sourceKey.startsWith("BOOKING:")) {
+            bookingNo=sourceKey.substring(8);
+            if (blank(bookingNo)) throw bad("外接登记号不能为空");
+            var matches=external.resolve(List.of(new AppointmentExternalSourceGateway.SourceRef(customerId,bookingNo)));
+            if (matches.size()!=1) throw missing();
+            var source=matches.get(0);
+            if (!Objects.equals(source.customerId(),customerId) || !Objects.equals(source.bookingNo(),bookingNo)) throw missing();
+            origin=source.warehouseId(); destination=source.destinationKey(); packages=source.packageCount();
+            version=source.recordVersion()==null ? null : "BOOKING:"+source.recordVersion();
+            followup=Set.of("CONFIRMED","RECEIVED","BOUND").contains(source.bookingStatus()==null ? "" : source.bookingStatus());
+            if (!followup) reasons=List.of("当前登记尚未确认承运或已取消，仅可查看跟进记录");
+            if (source.orderId()!=null) {
+                order=orders.selectById(source.orderId());
+                if (order==null || !customerId.equals(order.getCustomerId())) throw missing();
+                if (!Objects.equals(order.getOverseasWarehouseId(),origin)) throw bad("来货的接仓点与原登记不一致，请先核对");
+                if (!"FBA".equals(order.getDestinationType()) || !Objects.equals(destination,"FBA:"+order.getFbaWarehouseCode())) throw bad("来货目的仓与原登记不一致，请先核对");
+                packages=order.getPackageCount();
+            }
+        } else throw bad("不支持的货源类型");
+        if (order!=null && Set.of("CANCELLED","COMPLETED").contains(order.getCurrentStatus()==null ? "" : order.getCurrentStatus())) {
+            followup=false; reasons=List.of("该货物已取消或完成，仅可查看跟进记录");
+        }
+        if (!blank(destinationKey) && !Objects.equals(destination,destinationKey)) throw bad("目的地已变化，请返回原业务重新核对");
+        if (destination==null || !destination.startsWith("FBA:")) throw bad("当前仅支持FBA收货跟进来源");
+        var catalog=catalog(); final String originId=origin; final String code=destination.substring(4);
+        var warehouse=catalog.stream().filter(w -> w.id()!=null && w.id().toString().equals(originId) && "US".equals(w.countryCode())
+            && Set.of("OVERSEAS","OVERSEAS_PARTNER").contains(w.warehouseType()==null ? "" : w.warehouseType())).findFirst().orElseThrow(() -> bad("接仓点不在启用的美国仓目录中"));
+        if (catalog.stream().noneMatch(w -> "FBA".equals(w.warehouseType()) && "US".equals(w.countryCode()) && code.equals(w.warehouseCode()))) throw bad("目的仓不在启用的美国FBA目录中");
+        return new Source(sourceKey,customerId,order==null ? null : order.getId(),order==null ? null : order.getInboundCode(),bookingNo,
+            order==null ? null : order.getContainerNo(),origin,warehouse.warehouseName(),destination,code,packages,version,followup,reasons);
+    }
+    private List<AppointmentWarehouseClient.Warehouse> catalog() {
+        try { var result=warehouses.catalog(token); if (result==null || !result.successful() || result.data()==null) throw new IllegalStateException(); return result.data().stream().filter(Objects::nonNull).toList(); }
+        catch (RuntimeException error) { throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE,"仓库目录暂不可用，请稍后重新核对",error); }
+    }
+    private static boolean blank(String value) { return value==null || value.isBlank(); }
+    private static ResponseStatusException bad(String message) { return new ResponseStatusException(HttpStatus.BAD_REQUEST,message); }
+    private static ResponseStatusException missing() { return new ResponseStatusException(HttpStatus.NOT_FOUND,"未找到当前客户的货物来源"); }
+}
@@ -0,0 +1,42 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import java.time.DateTimeException;
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.time.ZoneId;
+import java.time.ZoneOffset;
+import java.util.List;
+
+/** Resolves a location's appointment window without using the operator's system time zone. */
+public final class AppointmentTimePolicy {
+    private AppointmentTimePolicy() { }
+
+    public record Window(Instant start, Instant end, String timezone) { }
+
+    public static Window resolve(LocalDateTime start, LocalDateTime end, String timezone,
+                                 ZoneOffset startOffset, ZoneOffset endOffset) {
+        if (start == null) throw new IllegalArgumentException("请填写预约开始时间");
+        if (timezone == null || timezone.isBlank()) throw new IllegalArgumentException("请先补齐预约地点时区");
+        final ZoneId zone;
+        try { zone = ZoneId.of(timezone); }
+        catch (DateTimeException error) { throw new IllegalArgumentException("预约地点时区无效", error); }
+        if (zone instanceof ZoneOffset) throw new IllegalArgumentException("预约地点需要地区时区，不能仅填写固定时差");
+        Instant first = instant(start, zone, startOffset);
+        Instant last = end == null ? null : instant(end, zone, endOffset);
+        if (end == null && endOffset != null) throw new IllegalArgumentException("未填写结束时间，不能指定结束时差");
+        if (last != null && !last.isAfter(first)) throw new IllegalArgumentException("预约结束时间必须晚于开始时间");
+        return new Window(first, last, zone.getId());
+    }
+
+    private static Instant instant(LocalDateTime value, ZoneId zone, ZoneOffset selected) {
+        List<ZoneOffset> offsets = zone.getRules().getValidOffsets(value);
+        if (offsets.isEmpty()) throw new IllegalArgumentException("该当地时间因夏令时切换不存在，请重新选择");
+        if (selected == null && offsets.size() > 1) {
+            throw new IllegalArgumentException("该当地时间在夏令时切换期间出现两次，请明确时差");
+        }
+        if (selected != null && !offsets.contains(selected)) {
+            throw new IllegalArgumentException("所选时差与预约地点及日期不符");
+        }
+        return value.toInstant(selected == null ? offsets.get(0) : selected);
+    }
+}
@@ -0,0 +1,14 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baiyue.common.core.api.ApiResponse;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestHeader;
+import java.util.List;
+
+@FeignClient(name = "warehouse-service", contextId = "appointmentWarehouseClient", url = "${baiyue.clients.domestic-warehouse.url:}")
+public interface AppointmentWarehouseClient {
+    @GetMapping("/internal/warehouses/order-catalog")
+    ApiResponse<List<Warehouse>> catalog(@RequestHeader("X-Internal-Service-Token") String token);
+    record Warehouse(Long id, String warehouseCode, String warehouseName, String warehouseType, String countryCode) { }
+}
@@ -0,0 +1,58 @@
+package com.baiyue.lastleg.dispatch.fleet;
+
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.lastleg.dispatch.dto.DispatchRequests;
+import com.baiyue.lastleg.dispatch.service.DispatchService;
+import com.baiyue.lastleg.fleet.trip.FleetBookingIncomingGateway;
+import com.baiyue.lastleg.fleet.trip.FleetDispatchGateway;
+import com.baiyue.lastleg.fleet.trip.FleetDispatchPlanningGateway;
+import org.springframework.context.annotation.Lazy;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.server.ResponseStatusException;
+import org.springframework.http.HttpStatus;
+import java.util.*;
+
+@Component
+@Transactional(propagation=Propagation.MANDATORY)
+public class FleetDispatchPlanningAdapter implements FleetDispatchPlanningGateway {
+    private final FleetDispatchPlanningMapper mapper;
+    private final DispatchService dispatches;
+    private final FleetDispatchGateway cargo;
+    public FleetDispatchPlanningAdapter(FleetDispatchPlanningMapper mapper,@Lazy DispatchService dispatches,FleetDispatchGateway cargo) {
+        this.mapper=mapper;this.dispatches=dispatches;this.cargo=cargo;
+    }
+    public PageResult<Candidate> candidates(String tripNo,String warehouseId,String keyword,int page,int size) {
+        var result=mapper.candidates(new com.baomidou.mybatisplus.extension.plugins.pagination.Page<>(page,size),tripNo,warehouseId,keyword);
+        return new PageResult<>(result.getRecords(),result.getCurrent(),result.getSize(),result.getTotal(),result.getPages());
+    }
+    public String resolveIncoming(String customerId,FleetBookingIncomingGateway.Evidence receipt,String operator) {
+        if(receipt==null||receipt.inboundCode()==null||!"READY_FOR_DISPATCH".equals(receipt.status())||receipt.pallets().isEmpty())
+            throw conflict("请先完成真实收货和实收核对");
+        var existing=mapper.sourceDispatches(customerId,receipt.inboundCode());
+        if(existing.size()>1)throw conflict("本次来货已有多张排车安排，请调度核查："+String.join("、",existing));
+        String number;
+        if(existing.isEmpty()) {
+            var ids=mapper.receivedPlanPallets(customerId,receipt.inboundCode());
+            if(ids.isEmpty())throw conflict("实收来源没有可用于排车的真实托盘");
+            number=dispatches.preArrange(customerId,operator,new DispatchRequests.PreArrange(ids,null,null,null,null)).dispatchNo();
+        } else number=existing.get(0);
+        validateIncomingDispatch(number,customerId,receipt);
+        return number;
+    }
+    public void validateIncomingDispatch(String number,String customerId,FleetBookingIncomingGateway.Evidence receipt) {
+        var snapshot=cargo.lockForPlanning(number);
+        if(!customerId.equals(snapshot.customerId())||!receipt.warehouseId().equals(snapshot.warehouseId()))throw conflict("排车客户或起运仓与来货不一致");
+        var expected=new TreeMap<String,Integer>();
+        for(var p:receipt.pallets())expected.merge(p.warehousePalletId(),p.packages(),Math::addExact);
+        var selected=new TreeMap<String,Integer>();
+        for(var item:cargo.sourceCargo(number)) {
+            if(!Objects.equals(receipt.inboundCode(),item.inboundCode())||!Objects.equals(receipt.destinationKey(),item.destinationKey())||item.warehousePalletId()==null)
+                throw conflict("候选排车包含其他来源或目的地，请调度核查 "+number);
+            selected.merge(item.warehousePalletId(),item.packages(),Math::addExact);
+        }
+        if(!expected.equals(selected))throw conflict("候选排车未完整覆盖本票全部实收货物，请调度核查 "+number);
+    }
+    private static ResponseStatusException conflict(String message){return new ResponseStatusException(HttpStatus.CONFLICT,message);}
+}
@@ -0,0 +1,30 @@
+package com.baiyue.lastleg.dispatch.fleet;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baiyue.lastleg.fleet.trip.FleetDispatchPlanningGateway;
+import org.apache.ibatis.annotations.*;
+import java.util.List;
+
+@Mapper
+public interface FleetDispatchPlanningMapper {
+    @Select({"<script>SELECT d.dispatch_no,d.customer_id,d.overseas_warehouse_id AS warehouse_id,d.package_count,d.route",
+        "FROM ll_dispatch_order d WHERE d.overseas_warehouse_id=#{warehouseId} AND d.status='PENDING_DEPARTURE'",
+        "AND d.package_count>0 AND COALESCE(d.picked_package_count,0)=0 AND COALESCE(d.shipped_package_count,0)=0",
+        "AND NOT EXISTS(SELECT 1 FROM ll_fleet_trip_dispatch b WHERE b.dispatch_id=d.id)",
+        "AND NOT EXISTS(SELECT 1 FROM ll_dispatch_item di JOIN ll_fleet_external_booking eb ON eb.incoming_no=di.inbound_code",
+        "WHERE di.dispatch_order_id=d.id AND (eb.trip_no!=#{tripNo} OR eb.status!='RECEIVED'))",
+        "AND NOT EXISTS(SELECT 1 FROM ll_dispatch_pda_task t WHERE t.dispatch_order_id=d.id AND t.status!='PDA_PENDING')",
+        "AND NOT EXISTS(SELECT 1 FROM ll_outbound_order o WHERE o.dispatch_order_id=d.id AND o.status!='WAIT_OUTBOUND')",
+        "<if test='keyword != null and keyword != &quot;&quot;'>AND (d.dispatch_no LIKE CONCAT('%',#{keyword},'%') OR d.route LIKE CONCAT('%',#{keyword},'%'))</if>",
+        "ORDER BY d.updated_at DESC,d.id DESC</script>"})
+    IPage<FleetDispatchPlanningGateway.Candidate> candidates(IPage<?> page,@Param("tripNo") String tripNo,@Param("warehouseId") String warehouseId,@Param("keyword") String keyword);
+
+    @Select("SELECT DISTINCT d.dispatch_no FROM ll_dispatch_order d JOIN ll_dispatch_item i ON i.dispatch_order_id=d.id AND i.customer_id=d.customer_id " +
+        "WHERE d.customer_id=#{customerId} AND i.inbound_code=#{inboundCode} AND d.status!='CANCELLED' ORDER BY d.dispatch_no")
+    List<String> sourceDispatches(@Param("customerId") String customerId,@Param("inboundCode") String inboundCode);
+
+    @Select("SELECT DISTINCT p.id FROM ll_inbound_plan_pallet p JOIN ll_inbound_plan ip ON ip.id=p.plan_id " +
+        "JOIN ll_inbound_plan_pallet_allocation a ON a.pallet_id=p.id JOIN ll_inbound_plan_line l ON l.id=a.line_id " +
+        "WHERE ip.customer_id=#{customerId} AND l.inbound_code=#{inboundCode} AND p.warehouse_pallet_id IS NOT NULL ORDER BY p.id")
+    List<Long> receivedPlanPallets(@Param("customerId") String customerId,@Param("inboundCode") String inboundCode);
+}
@@ -0,0 +1,17 @@
+package com.baiyue.lastleg.fleet.business;
+
+import com.baiyue.lastleg.appointmentplanning.AppointmentExternalSourceGateway;
+import org.springframework.stereotype.Component;
+import java.util.List;
+
+/** Appointment resolves aliases through Fleet's read boundary, never by copying cargo. */
+@Component
+public class FleetAppointmentSourceAdapter implements AppointmentExternalSourceGateway {
+    private final FleetPoolSourceResolver sources;
+    public FleetAppointmentSourceAdapter(FleetPoolSourceResolver sources){this.sources=sources;}
+    @Override
+    public List<Source> resolve(List<SourceRef> refs) {
+        return sources.resolve(refs.stream().map(r->new FleetPoolSourceResolver.SourceRef(r.customerId(),r.bookingNo())).toList())
+            .stream().map(s->new Source(s.customerId(),s.bookingNo(),s.tripNo(),s.bookingStatus(),s.warehouseId(),s.destinationKey(),s.lastlegOrderId(),s.packageCount(),s.recordVersion())).toList();
+    }
+}
@@ -39,6 +39,13 @@ public class FleetPoolOrderBridge {
        this.links=links;this.loose=loose;this.looseHistory=looseHistory;this.trucks=trucks;
        this.truckHistory=truckHistory;this.numbers=numbers;this.json=json;this.deliveryEvidence=deliveryEvidence;
    }
+    @Transactional(readOnly=true)
+    public Map<Long,String> fulfillmentStages(List<Long> bookingIds) {
+        if(bookingIds.isEmpty())return Map.of();
+        var result=new HashMap<Long,String>();
+        for(var link:links.bookings(bookingIds))result.put(link.getBookingId(),link.getFulfillmentStage());
+        return Map.copyOf(result);
+    }
    @Transactional(propagation=Propagation.MANDATORY)
    public BusinessOrderRef confirm(ConfirmedBooking in,String operator) {
        validate(in);
@@ -7,6 +7,15 @@ import java.util.List;

@Mapper
 public interface FleetPoolOrderMapper extends BaseMapper<FleetPoolOrderLink> {
+    @Select({"<script>SELECT b.customer_id,b.booking_no,b.trip_no,b.status AS booking_status,",
+        "t.warehouse_id,b.destination_key,b.destination_label,b.incoming_no,",
+        "l.lastleg_order_id,l.business_order_no,l.fulfillment_stage,b.record_version,",
+        "b.cargo_json,b.expected_pallet_count,b.estimated_arrival_at",
+        "FROM ll_fleet_external_booking b JOIN ll_fleet_trip t ON t.id=b.trip_id",
+        "LEFT JOIN ll_fleet_pool_order_link l ON l.booking_id=b.id AND l.customer_id=b.customer_id",
+        "WHERE b.offer_id IS NOT NULL AND <foreach collection='sources' item='s' open='(' separator=' OR ' close=')'>",
+        "(b.customer_id=#{s.customerId} AND b.booking_no=#{s.bookingNo})</foreach></script>"})
+    List<FleetPoolSourceResolver.SourceRow> resolveSources(@Param("sources") List<FleetPoolSourceResolver.SourceRef> sources);
    @Select("SELECT * FROM ll_fleet_pool_order_link WHERE booking_id=#{id} FOR UPDATE")
    FleetPoolOrderLink lockBooking(long id);
    @Select("SELECT * FROM ll_fleet_pool_order_link WHERE booking_no=#{no} FOR UPDATE")
@@ -0,0 +1,37 @@
+package com.baiyue.lastleg.fleet.business;
+
+import java.util.List;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+/** Internal read boundary for appointment planning; caller must authorize every customer/source. */
+@Service
+public class FleetPoolSourceResolver {
+    public record SourceRef(String customerId, String bookingNo) { }
+    public record Source(String customerId, String bookingNo, String tripNo, String bookingStatus,
+        String warehouseId, String destinationKey, String destinationLabel, String incomingNo,
+        Long lastlegOrderId, String businessOrderNo, String fulfillmentStage, Long recordVersion, Integer packageCount, Integer expectedPalletCount, java.time.LocalDateTime estimatedArrivalAt) { }
+    public record SourceRow(String customerId, String bookingNo, String tripNo, String bookingStatus,
+        String warehouseId, String destinationKey, String destinationLabel, String incomingNo,
+        Long lastlegOrderId, String businessOrderNo, String fulfillmentStage, Long recordVersion,
+        String cargoJson, Integer expectedPalletCount, java.time.LocalDateTime estimatedArrivalAt) { }
+    private final com.fasterxml.jackson.databind.ObjectMapper json;
+    private final FleetPoolOrderMapper links;
+    public FleetPoolSourceResolver(FleetPoolOrderMapper links,com.fasterxml.jackson.databind.ObjectMapper json) { this.links = links; this.json=json; }
+
+    @Transactional(readOnly = true)
+    public List<Source> resolve(List<SourceRef> sources) {
+        if (sources == null || sources.isEmpty()) return List.of();
+        if (sources.size() > 100 || sources.stream().anyMatch(s -> s == null || s.customerId() == null || s.customerId().isBlank() || s.bookingNo() == null || s.bookingNo().isBlank()))
+            throw new IllegalArgumentException("来源须包含客户及登记业务号，每次最多100条");
+        return links.resolveSources(sources.stream().distinct().toList()).stream().map(row -> {
+            Integer packages;
+            try {
+                var value=json.readTree(row.cargoJson()).get("packageCount");
+                if(value==null||value.isNull()) packages=null;
+                else { if(!value.isIntegralNumber()||!value.canConvertToInt())throw new IllegalStateException("预报箱数格式无效"); packages=value.intValue(); }
+            } catch(java.io.IOException e){throw new IllegalStateException("货物预报读取失败",e);}
+            return new Source(row.customerId(),row.bookingNo(),row.tripNo(),row.bookingStatus(),row.warehouseId(),row.destinationKey(),row.destinationLabel(),row.incomingNo(),row.lastlegOrderId(),row.businessOrderNo(),row.fulfillmentStage(),row.recordVersion(),packages,row.expectedPalletCount(),row.estimatedArrivalAt());
+        }).toList();
+    }
+}
@@ -11,6 +11,8 @@ public interface FleetBookingIncomingGateway {
    record Pallet(String warehousePalletId,String palletNo,int packages,BigDecimal weightKg,BigDecimal volumeCbm) { }
    record Evidence(String incomingNo,String inboundCode,String warehouseId,String destinationKey,String status,
        String receiptHash,List<Pallet> pallets,int receivedPackages) { }
+    record Source(String customerId,String incomingNo) { }
+    java.util.Map<Source,String> statuses(List<Source> sources);
    Evidence create(String operator, Incoming incoming);
    Evidence inspect(String customerId,String incomingNo,boolean lock);
    Evidence confirm(String customerId,String incomingNo,String operator,String key);
@@ -35,12 +35,17 @@ public class FleetBookingService {
    private final FleetBookingQuoteContext quoteContext;
    private final FleetQuoteCandidateService quotes;
    @jakarta.annotation.Resource private FleetPoolOrderBridge poolOrders;
+    @jakarta.annotation.Resource private FleetDispatchPlanningGateway planning;
+    @jakarta.annotation.Resource private FleetCapacityOfferCommandMapper commands;
    public FleetBookingService(FleetTripMapper trips,FleetBookingMapper bookings,FleetBookingReservations reservations,
        FleetTripService history,FleetTripExecutionService execution,FleetCustomerDirectory customers,ObjectMapper json,FleetBookingIncomingGateway incoming,
        FleetBookingQuoteContext quoteContext,FleetQuoteCandidateService quotes){
        this.trips=trips;this.bookings=bookings;this.reservations=reservations;this.history=history;this.execution=execution;this.customers=customers;this.json=json;this.incoming=incoming;
        this.quoteContext=quoteContext;this.quotes=quotes;
    }
+    public java.util.Map<FleetBookingIncomingGateway.Source,String> incomingStatuses(java.util.List<FleetBookingEntity> rows) {
+        return incoming.statuses(rows.stream().filter(r->r.getIncomingNo()!=null).map(r->new FleetBookingIncomingGateway.Source(r.getCustomerId(),r.getIncomingNo())).distinct().toList());
+    }
    @Transactional(readOnly=true,isolation=org.springframework.transaction.annotation.Isolation.REPEATABLE_READ)
    public FleetBookingModels.ListResult list(String tripNo){var trip=trip(tripNo,false);return new FleetBookingModels.ListResult(trip.getRecordVersion(),reservations.responses(trip.getId()));}
    @Transactional(readOnly=true,isolation=org.springframework.transaction.annotation.Isolation.REPEATABLE_READ)
@@ -125,9 +130,12 @@ public class FleetBookingService {
        requireTrip(trip,request.tripRecordVersion());requireVersion(row,request.recordVersion());
        if(!"CONFIRMED".equals(row.getStatus())||row.getIncomingNo()!=null)throw conflict("仅已确认且尚未登记来货的预订允许此操作");
        customers.required(Long.parseLong(row.getCustomerId()));
-        var arrival=request.estimatedArrivalAt()==null?trip.getPlannedDepartureAt().toInstant(ZoneOffset.UTC).minusSeconds(7200):request.estimatedArrivalAt();
+        var arrival=request.estimatedArrivalAt()!=null?request.estimatedArrivalAt():row.getEstimatedArrivalAt()==null?null:row.getEstimatedArrivalAt().toInstant(ZoneOffset.UTC);
+        if(arrival==null)throw conflict("请确认预计到仓时间，不自动推算到仓安排");
+        if(arrival.isAfter(trip.getPlannedDepartureAt().toInstant(ZoneOffset.UTC)))throw conflict("预计到仓不得晚于计划发车时间");
+        var instructions=trim(request.deliveryInstructions())!=null?request.deliveryInstructions():reservations.cargo(row).remark();
        var evidence=incoming.create(operator,new FleetBookingIncomingGateway.Incoming(row.getCustomerId(),trip.getWarehouseId().toString(),trip.getWarehouseName(),row.getBookingNo(),reservations.cargo(row),
-            LocalDateTime.ofInstant(arrival,java.time.ZoneId.systemDefault()),request.deliveryInstructions(),request.privateAddress(),request.postalCode(),request.recipientName(),request.recipientPhone()));
+            LocalDateTime.ofInstant(arrival,java.time.ZoneId.systemDefault()),instructions,request.privateAddress(),request.postalCode(),request.recipientName(),request.recipientPhone()));
        requireEvidence(trip,row,evidence);
        row.setIncomingNo(evidence.incomingNo());row.setIncomingKey(request.idempotencyKey());row.setIncomingHash(hash);
        save(trip,row,operator,"BOOKING_INCOMING","登记外接来货 "+evidence.incomingNo());return result(trip,row,false);
@@ -169,12 +177,48 @@ public class FleetBookingService {
        if(Objects.equals(row.getBindingKey(),request.idempotencyKey())){if(!hash.equals(row.getBindingHash()))throw conflict("关联发运请求内容不一致");return result(trip,row,true);}
        requireTrip(trip,request.tripRecordVersion());requireVersion(row,request.recordVersion());
        if(!"RECEIVED".equals(row.getStatus()))throw conflict("请先确认外接实收货量和运费");
+        if(row.getOfferId()!=null) {
+            var accepted=reservations.receipt(row);
+            var evidence=incoming.inspect(row.getCustomerId(),row.getIncomingNo(),true);requireEvidence(trip,row,evidence);
+            if(accepted==null||!Objects.equals(accepted.source().receiptHash(),evidence.receiptHash()))throw conflict("实收来源已变化，请重新核对");
+            planning.validateIncomingDispatch(request.dispatchNo(),row.getCustomerId(),evidence);
+        }
        row.setBindingKey(request.idempotencyKey());row.setBindingHash(hash);bookings.updateById(row);
        var linked=history.bindDispatch(tripNo,operator,new FleetTripModels.BindingCommand(request.tripRecordVersion(),request.dispatchNo(),"关联外接预订 "+bookingNo));
        var result=booking(trip,bookingNo);
        if(!"BOUND".equals(result.getStatus())||!Objects.equals(result.getDispatchNo(),request.dispatchNo().trim()))throw conflict("所选排车未包含此外接来货单的实际货物");
        return new FleetBookingModels.Result(linked.trip().recordVersion(),reservations.response(result),false);
    }
+    @Transactional
+    public FleetBookingModels.Result arrangeDispatch(String tripNo,String bookingNo,String operator,FleetBookingModels.Command request) {
+        var trip=trip(tripNo,true);String hash=hash(request);
+        var previous=commands.find(trip.getId(),operator,"BOOKING_ARRANGE",bookingNo,request.idempotencyKey());
+        if(previous!=null) {
+            if(!hash.equals(previous.getRequestHash()))throw conflict("排入本车请求内容不一致");
+            try {var saved=json.readValue(previous.getResultJson(),FleetBookingModels.Result.class);return new FleetBookingModels.Result(saved.tripRecordVersion(),saved.booking(),true);}
+            catch(java.io.IOException e){throw new IllegalStateException("原排入结果读取失败",e);}
+        }
+        String resourceBlock=execution.currentVehicleBlockReason(trip,true);var row=booking(trip,bookingNo);
+        requireTrip(trip,request.tripRecordVersion());requireVersion(row,request.recordVersion());
+        if(!"RECEIVED".equals(row.getStatus()))throw conflict("请先确认全部实收货量和运费");
+        var accepted=reservations.receipt(row);
+        var evidence=incoming.inspect(row.getCustomerId(),row.getIncomingNo(),true);requireEvidence(trip,row,evidence);
+        if(accepted==null||!Objects.equals(accepted.source().receiptHash(),evidence.receiptHash()))throw conflict("实收来源已变化，请重新核对");
+        if(resourceBlock!=null)throw conflict(resourceBlock);
+        var plan=execution.capacityPlan(tripNo);
+        if(!plan.planValid()||plan.blockReason()!=null)throw conflict("本车计划容量待核对，暂不能排入");
+        reservations.segments(trip,plan.capacityPlan(),row.getId(),row);
+        String dispatchNo=planning.resolveIncoming(row.getCustomerId(),evidence,operator);
+        var linked=history.bindDispatch(tripNo,operator,new FleetTripModels.BindingCommand(trip.getRecordVersion(),dispatchNo,"实收核对后排入本车 "+bookingNo));
+        row=booking(trip,bookingNo);
+        if(!"BOUND".equals(row.getStatus())||!Objects.equals(row.getDispatchNo(),dispatchNo))throw conflict("未完整关联本票实收来源");
+        row.setBindingKey(request.idempotencyKey());row.setBindingHash(hash);bookings.updateById(row);
+        var result=new FleetBookingModels.Result(linked.trip().recordVersion(),reservations.response(row),false);
+        var command=new FleetCapacityOfferCommand();command.setId(IdWorker.getId());command.setTripId(trip.getId());command.setOperatorId(operator);
+        command.setAction("BOOKING_ARRANGE");command.setScopeNo(bookingNo);command.setIdempotencyKey(request.idempotencyKey());command.setRequestHash(hash);
+        command.setResultJson(write(result));command.setCreatedAt(now());commands.insert(command);
+        return result;
+    }
    private static void requireEvidence(FleetTripEntity trip,FleetBookingEntity row,FleetBookingIncomingGateway.Evidence evidence){
        if(evidence==null||evidence.incomingNo()==null||!Objects.equals(trip.getWarehouseId().toString(),evidence.warehouseId())||!Objects.equals(row.getDestinationKey(),evidence.destinationKey()))throw conflict("来货单仓库或目的地与外接承运约定不一致");
        if(row.getIncomingNo()!=null&&!Objects.equals(row.getIncomingNo(),evidence.incomingNo()))throw conflict("来货单引用不一致");
@@ -21,7 +21,7 @@ public final class FleetCapacityOfferModels {
    }
    public record InquiryQuery(@Min(1) Integer page,@Min(1) @Max(100) Integer size,
        @Size(max=128) String keyword,@Size(max=64) String offerNo,@Size(max=32) String status,
-        @Pattern(regexp="MINE|ALL") String scope) {
+        @Pattern(regexp="MINE|ALL|TODO") String scope) {
        public InquiryQuery {page=page==null?1:page;size=size==null?20:size;scope=scope==null?"MINE":scope;}
    }
    public record Write(@NotBlank @Size(max=64) String tripNo,@NotNull @Min(0) Long tripRecordVersion,
@@ -50,12 +50,15 @@ public final class FleetCapacityOfferModels {
        String contactName,String contactPhone,String remark,List<Destination> destinations,List<Segment> segments,
        boolean capacityKnown,boolean canCreateInquiry,boolean canConfirm,String blockReason,Actions actions) { }
    public record InquiryActions(boolean canEdit,boolean canConfirm,boolean canCancel,String blockReason) { }
+    public record Progress(String stage,String label,String reservation,String owner,String primaryAction,
+        String message,List<String> missingFields) { }
    public record Inquiry(String bookingNo,String offerNo,String tripNo,String status,long recordVersion,
        long offerRecordVersion,long tripRecordVersion,String salesOwnerUserId,String customerId,String customerCode,
        String customerName,String businessType,String deliveryMode,Instant estimatedArrivalAt,Integer expectedPalletCount,
        FleetBookingModels.Cargo cargo,String destinationLabel,BigDecimal agreedAmount,
        FleetQuoteCandidateModels.SourceSnapshot quoteSource,String businessOrderNo,String incomingNo,String dispatchNo,
-        Instant updatedAt,InquiryActions actions) { }
+        Instant updatedAt,InquiryActions actions,Progress progress,com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService.Coverage appointmentCoverage) { }
+    public record Fulfillment(FleetBookingModels.Response booking,FleetBookingModels.IncomingPreview preview,Instant plannedDepartureAt) { }
    public record Detail(Offer offer,PageResult<Inquiry> inquiries) { }
    public record OfferResult(Offer offer,boolean replayed) { }
    public record InquiryResult(Inquiry inquiry,Offer offer,boolean replayed) { }
@@ -37,6 +37,7 @@ public class FleetCapacityOfferService {
    private final FleetPoolOrderBridge orders;
    private final ObjectMapper json;
    private final Clock clock;
+    @jakarta.annotation.Resource private com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService appointmentCoverage;
    @Autowired
    public FleetCapacityOfferService(FleetCapacityOfferMapper offers,FleetCapacityOfferCommandMapper commands,
        FleetTripMapper trips,FleetBookingMapper bookings,FleetBookingService bookingService,FleetBookingReservations reservations,
@@ -67,23 +68,52 @@ public class FleetCapacityOfferService {
    }
    @Transactional(readOnly=true,isolation=Isolation.REPEATABLE_READ)
    public PageResult<FleetCapacityOfferModels.Inquiry> inquiries(FleetCapacityOfferModels.InquiryQuery query){
-        readPermission();if("ALL".equals(query.scope())&&!manage())throw forbidden();
+        readPermission();if(!"MINE".equals(query.scope())&&!manage())throw forbidden();
        var filter=new LambdaQueryWrapper<FleetBookingEntity>().isNotNull(FleetBookingEntity::getOfferId);
-        if(!"ALL".equals(query.scope()))filter.eq(FleetBookingEntity::getSalesOwnerUserId,operator());
+        if("MINE".equals(query.scope()))filter.eq(FleetBookingEntity::getSalesOwnerUserId,operator());
        if(query.offerNo()!=null){var row=offer(query.offerNo(),false);requireVisible(row);filter.eq(FleetBookingEntity::getOfferId,row.getId());}
        if(nonblank(query.status()))filter.eq(FleetBookingEntity::getStatus,query.status());
-        if(nonblank(query.keyword()))filter.and(q->q.like(FleetBookingEntity::getBookingNo,query.keyword()).or().like(FleetBookingEntity::getCustomerName,query.keyword()).or().like(FleetBookingEntity::getCustomerCode,query.keyword()));
+        if(nonblank(query.keyword()))filter.and(q->q.like(FleetBookingEntity::getBookingNo,query.keyword()).or().like(FleetBookingEntity::getCustomerName,query.keyword()).or().like(FleetBookingEntity::getCustomerCode,query.keyword()).or().like(FleetBookingEntity::getTripNo,query.keyword()));
+        boolean todo="TODO".equals(query.scope());
+        if(todo)filter.in(FleetBookingEntity::getStatus,"DRAFT","CONFIRMED","RECEIVED");
        filter.orderByDesc(FleetBookingEntity::getUpdatedAt,FleetBookingEntity::getId);
-        var result=bookings.selectPage(new com.baomidou.mybatisplus.extension.plugins.pagination.Page<>(query.page(),query.size()),filter);
+        var result=bookings.selectPage(new com.baomidou.mybatisplus.extension.plugins.pagination.Page<>(todo?1:query.page(),todo?100:query.size()),filter);
+        if(todo&&result.getTotal()>100)throw bad("待办实时核对最多100条，请按客户或登记号缩小范围");
+        var incomingStatuses=bookingService.incomingStatuses(result.getRecords());
+        var coverage=coverageByBooking(result.getRecords());
+        var stages=orders.fulfillmentStages(result.getRecords().stream().map(FleetBookingEntity::getId).toList());
        var numbers=orders.businessOrderNumbers(result.getRecords().stream().map(FleetBookingEntity::getId).toList());
        var projections=new HashMap<Long,FleetCapacityOfferModels.Offer>();
-        var values=result.getRecords().stream().map(row->inquiry(row,numbers.get(row.getId()),projections.computeIfAbsent(row.getOfferId(),key->{var offer=offers.selectById(key);return project(offer,trip(offer.getTripNo(),false));}))).toList();
+        var values=result.getRecords().stream().map(row->inquiry(row,numbers.get(row.getId()),projections.computeIfAbsent(row.getOfferId(),key->{var offer=offers.selectById(key);return project(offer,trip(offer.getTripNo(),false));}),incomingStatuses.get(new FleetBookingIncomingGateway.Source(row.getCustomerId(),row.getIncomingNo())),stages.get(row.getId()),coverage.get(row.getBookingNo()))).filter(v->!todo||"调度".equals(v.progress().owner())).toList();
+        if(todo)return page(values,query.page(),query.size());
        return new PageResult<>(values,result.getCurrent(),result.getSize(),result.getTotal(),result.getPages());
    }
    @Transactional(readOnly=true,isolation=Isolation.REPEATABLE_READ)
    public FleetCapacityOfferModels.Inquiry inquiry(String number){
        readPermission();var row=inquiryRow(number);own(row);return inquiry(row,orders.businessOrderNumbers(List.of(row.getId())).get(row.getId()));
    }
+    @Transactional(readOnly=true,isolation=Isolation.REPEATABLE_READ)
+    public FleetCapacityOfferModels.Fulfillment fulfillment(String number) {
+        readPermission();var row=inquiryRow(number);own(row);
+        var trip=trip(row.getTripNo(),false);
+        return new FleetCapacityOfferModels.Fulfillment(reservations.response(row),
+            bookingService.incoming(row.getTripNo(),number),instant(trip.getPlannedDepartureAt()));
+    }
+    @Transactional
+    public FleetBookingModels.Result arrangeIncoming(String number,FleetBookingModels.StartIncoming request) {
+        requireManage();var row=inquiryRow(number);
+        return bookingService.startIncoming(row.getTripNo(),number,operator(),request);
+    }
+    @Transactional
+    public FleetBookingModels.Result acceptReceipt(String number,FleetBookingModels.AcceptReceipt request) {
+        requireManage();var row=inquiryRow(number);
+        return bookingService.acceptReceipt(row.getTripNo(),number,operator(),request);
+    }
+    @Transactional
+    public FleetBookingModels.Result arrangeDispatch(String number,FleetBookingModels.Command request) {
+        requireManage();var row=inquiryRow(number);
+        return bookingService.arrangeDispatch(row.getTripNo(),number,operator(),request);
+    }
    @Transactional(readOnly=true)
    public List<FleetCapacityOfferModels.CustomerOption> customerOptions(String keyword){
        writePermission("inquiry-create");
@@ -165,6 +195,16 @@ public class FleetCapacityOfferService {
        var result=inquiryResult(row,booking);saveCommand(trip,"INQUIRY_EDIT",number,request.idempotencyKey(),request,result);return result;
    }
    @Transactional
+    public FleetCapacityOfferModels.InquiryResult saveAndConfirm(String number,FleetCapacityOfferModels.InquiryWrite request) {
+        requireManage();var initial=inquiryRow(number);var trip=trip(initial.getTripNo(),true);
+        var replay=replay(trip,"SAVE_CONFIRM",number,request.idempotencyKey(),request,FleetCapacityOfferModels.InquiryResult.class);
+        if(replay!=null)return replayed(replay);
+        var saved=updateInquiry(number,request);
+        var result=confirm(number,new FleetCapacityOfferModels.InquiryCommand(saved.offer().tripRecordVersion(),saved.offer().recordVersion(),saved.inquiry().recordVersion(),request.idempotencyKey(),"核对资料并确认承运"));
+        saveCommand(trip,"SAVE_CONFIRM",number,request.idempotencyKey(),request,result);
+        return result;
+    }
+    @Transactional
    public FleetCapacityOfferModels.InquiryResult confirm(String number,FleetCapacityOfferModels.InquiryCommand request){
        requireManage();var initial=inquiryRow(number);var trip=trip(initial.getTripNo(),true);
        String vehicleBlock=execution.currentVehicleBlockReason(trip,true);var row=offers.lock(offers.selectById(initial.getOfferId()).getOfferNo());var booking=bookings.lock(trip.getId(),number);
@@ -172,7 +212,10 @@ public class FleetCapacityOfferService {
        versions(trip,row,request.tripRecordVersion(),request.offerRecordVersion());requireInquiryOpen(row,trip);
        if(vehicleBlock!=null)throw conflict(vehicleBlock);
        var offer=project(row,trip);if(!offer.canConfirm())throw conflict(offer.blockReason());
-        var cargo=reservations.cargo(booking);FleetBookingService.requireCompleteCargo(cargo);
+        var cargo=reservations.cargo(booking);
+        var missing=FleetInquiryProgress.missing(booking,cargo,offer);
+        if(!missing.isEmpty())throw conflict("确认前还需："+String.join("、",missing));
+        FleetBookingService.requireCompleteCargo(cargo);
        if(!nonblank(cargo.contactName())||!nonblank(cargo.contactPhone())||!nonblank(cargo.cargoName()))throw conflict("成交前请补齐货名和联系信息");
        if("US_TRUCK".equals(booking.getBusinessType())&&(booking.getExpectedPalletCount()==null||booking.getExpectedPalletCount()<1))throw conflict("本土卡车成交前请填写预计实托数，不能用托位替代");
        if(booking.getEstimatedArrivalAt()==null||booking.getEstimatedArrivalAt().isAfter(row.getCutoffAt()))throw conflict("请填写不晚于交货截止的预计到仓时间");
@@ -197,18 +240,32 @@ public class FleetCapacityOfferService {
        var result=inquiryResult(row,bookings.lock(trip.getId(),number));saveCommand(trip,"CANCEL",number,request.idempotencyKey(),request,result);return result;
    }

+    private Map<String,com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService.Coverage> coverageByBooking(List<FleetBookingEntity> rows) {
+        var refs=rows.stream().filter(r->r.getDestinationKey()!=null&&r.getDestinationKey().startsWith("FBA:"))
+            .map(r->new com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService.SourceRef(r.getCustomerId(),"BOOKING:"+r.getBookingNo(),r.getDestinationKey())).toList();
+        var result=new HashMap<String,com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService.Coverage>();
+        if(refs.isEmpty())return result;
+        for(var c:appointmentCoverage.query(refs))result.put(c.sourceKey().substring("BOOKING:".length()),c);
+        return result;
+    }
    private FleetCapacityOfferModels.InquiryResult inquiryResult(FleetCapacityOfferEntity row,FleetBookingEntity booking){
        return new FleetCapacityOfferModels.InquiryResult(inquiry(booking,orders.businessOrderNumbers(List.of(booking.getId())).get(booking.getId())),project(row,trip(row.getTripNo(),false)),false);
    }
    private FleetCapacityOfferModels.InquiryResult replayed(FleetCapacityOfferModels.InquiryResult value){return new FleetCapacityOfferModels.InquiryResult(value.inquiry(),value.offer(),true);}
    private FleetCapacityOfferModels.Inquiry inquiry(FleetBookingEntity booking,String businessNo){
-        var row=offers.selectById(booking.getOfferId());return inquiry(booking,businessNo,project(row,trip(booking.getTripNo(),false)));
+        var row=offers.selectById(booking.getOfferId());return inquiry(booking,businessNo,project(row,trip(booking.getTripNo(),false)),bookingService.incomingStatuses(List.of(booking)).get(new FleetBookingIncomingGateway.Source(booking.getCustomerId(),booking.getIncomingNo())),orders.fulfillmentStages(List.of(booking.getId())).get(booking.getId()),coverageByBooking(List.of(booking)).get(booking.getBookingNo()));
    }
-    private FleetCapacityOfferModels.Inquiry inquiry(FleetBookingEntity booking,String businessNo,FleetCapacityOfferModels.Offer offer){
+    private FleetCapacityOfferModels.Inquiry inquiry(FleetBookingEntity booking,String businessNo,FleetCapacityOfferModels.Offer offer,String incomingStatus,String fulfillmentStage,com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService.Coverage coverage){
        boolean owned=manage()||Objects.equals(operator(),booking.getSalesOwnerUserId());boolean draft="DRAFT".equals(booking.getStatus());
        boolean canCancel=owned&&(draft||manage()&&"CONFIRMED".equals(booking.getStatus())&&booking.getIncomingNo()==null);
+        var cargo=reservations.cargo(booking);
+        var missing=FleetInquiryProgress.missing(booking,cargo,offer);
+        String block=draft?FleetInquiryProgress.capacityBlock(cargo,offer):null;
+        boolean canEdit=owned&&draft&&offer.canCreateInquiry()&&(manage()||has(LIST)&&has(LIST.replace(":list",":inquiry-edit")));
+        boolean canConfirm=manage()&&draft&&offer.canConfirm()&&missing.isEmpty()&&block==null;
        return new FleetCapacityOfferModels.Inquiry(booking.getBookingNo(),offer.offerNo(),booking.getTripNo(),booking.getStatus(),booking.getRecordVersion(),offer.recordVersion(),offer.tripRecordVersion(),booking.getSalesOwnerUserId(),booking.getCustomerId(),booking.getCustomerCode(),booking.getCustomerName(),booking.getBusinessType(),booking.getDeliveryMode(),instant(booking.getEstimatedArrivalAt()),booking.getExpectedPalletCount(),reservations.cargo(booking),booking.getDestinationLabel(),booking.getAgreedAmount(),reservations.quoteSource(booking),businessNo,booking.getIncomingNo(),booking.getDispatchNo(),instant(booking.getUpdatedAt()),
-            new FleetCapacityOfferModels.InquiryActions(owned&&draft&&offer.canCreateInquiry()&&(manage()||has(LIST)&&has(LIST.replace(":list",":inquiry-edit"))),manage()&&draft&&offer.canConfirm(),canCancel&&(manage()||has(LIST)&&has(LIST.replace(":list",":inquiry-cancel"))),offer.blockReason()));
+            new FleetCapacityOfferModels.InquiryActions(canEdit,canConfirm,canCancel&&(manage()||has(LIST)&&has(LIST.replace(":list",":inquiry-cancel"))),block),
+            FleetInquiryProgress.project(booking,missing,block,canEdit,canConfirm,incomingStatus,fulfillmentStage),coverage);
    }
    private FleetCapacityOfferModels.Offer project(FleetCapacityOfferEntity row,FleetTripEntity trip){
        String block=openBlock(row,trip,clock.instant());var planning=execution.capacityPlan(trip.getTripNo());
@@ -0,0 +1,11 @@
+package com.baiyue.lastleg.fleet.trip;
+
+import com.baiyue.common.core.api.PageResult;
+
+/** Dispatch owns candidate eligibility and creation; fleet orchestrates the trip transaction. */
+public interface FleetDispatchPlanningGateway {
+    record Candidate(String dispatchNo,String customerId,String warehouseId,int packageCount,String route) { }
+    PageResult<Candidate> candidates(String tripNo,String warehouseId,String keyword,int page,int size);
+    void validateIncomingDispatch(String dispatchNo,String customerId,FleetBookingIncomingGateway.Evidence receipt);
+    String resolveIncoming(String customerId,FleetBookingIncomingGateway.Evidence receipt,String operator);
+}
@@ -0,0 +1,72 @@
+package com.baiyue.lastleg.fleet.trip;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
+
+/** Derived handling guidance, never a second writable booking state machine. */
+final class FleetInquiryProgress {
+    private FleetInquiryProgress() { }
+
+    static List<String> missing(FleetBookingEntity booking, FleetBookingModels.Cargo cargo,
+                                FleetCapacityOfferModels.Offer offer) {
+        var fields = new ArrayList<String>();
+        if (cargo.packageCount() == null || cargo.packageCount() < 1) fields.add("预计箱数");
+        if (cargo.palletSpaces() == null || cargo.palletSpaces() < 1) fields.add("占用标准托位");
+        if (!positive(cargo.weightKg())) fields.add("预计重量");
+        if (!positive(cargo.volumeCbm())) fields.add("预计体积");
+        if ("US_TRUCK".equals(booking.getBusinessType()) &&
+            (booking.getExpectedPalletCount() == null || booking.getExpectedPalletCount() < 1)) fields.add("预计实托数");
+        if (cargo.unitPrice() == null || cargo.unitPrice().signum() < 0) fields.add("约定价格");
+        if (!List.of("CNY", "USD").contains(cargo.currency() == null ? "" : cargo.currency())) fields.add("币种（CNY或USD）");
+        if (blank(cargo.cargoName())) fields.add("货物名称");
+        if (blank(cargo.contactName())) fields.add("联系人");
+        if (blank(cargo.contactPhone())) fields.add("联系方式");
+        if (booking.getEstimatedArrivalAt() == null) fields.add("预计到仓时间");
+        else if (booking.getEstimatedArrivalAt().toInstant(java.time.ZoneOffset.UTC).isAfter(offer.cutoffAt())) fields.add("预计到仓时间（不得晚于最晚送仓）");
+        return List.copyOf(fields);
+    }
+
+    static String capacityBlock(FleetBookingModels.Cargo cargo, FleetCapacityOfferModels.Offer offer) {
+        if (!offer.canConfirm()) return offer.blockReason();
+        var destination = offer.destinations().stream().filter(d -> d.destinationKey().equals(cargo.destinationKey())).findFirst();
+        if (destination.isEmpty()) return "卸货站已变化，请调度核对路线";
+        var remaining = destination.get().remaining();
+        if (remaining == null) return "余位待调度核对";
+        if (cargo.palletSpaces() != null && cargo.palletSpaces() > remaining.palletSpaces()
+            || cargo.weightKg() != null && cargo.weightKg().compareTo(remaining.weightKg()) > 0
+            || cargo.volumeCbm() != null && cargo.volumeCbm().compareTo(remaining.volumeCbm()) > 0)
+            return "本票预报超过所选目的地余位，请调度核对";
+        return null;
+    }
+
+    static FleetCapacityOfferModels.Progress project(FleetBookingEntity booking, List<String> missing,
+                                                     String block, boolean canEdit, boolean canConfirm, String incomingStatus, String fulfillmentStage) {
+        if ("IN_TRANSIT".equals(fulfillmentStage)) return progress("IN_TRANSIT", "已发车", "运输中", "派送", "VIEW", "按实际派送进度跟进", List.of());
+        if ("COMPLETED".equals(fulfillmentStage)) return progress("COMPLETED", "已完成", "运输已完成", "无待办", "VIEW", "实际货物已全部签收", List.of());
+        return switch (booking.getStatus()) {
+            case "DRAFT" -> {
+                if (!canEdit && !canConfirm && block != null)
+                    yield progress("BLOCKED", "登记暂不可处理", "尚未保位", "调度", "VIEW", block, missing);
+                if (!missing.isEmpty()) yield progress("NEEDS_DETAILS", "待补资料", "尚未保位", "销售", canEdit ? "EDIT" : "VIEW", "确认前还需：" + String.join("、", missing), missing);
+                if (block != null) yield progress("RECHECK", "待调度核对", "尚未保位", "调度", "VIEW", block, missing);
+                yield progress("AWAITING_CONFIRMATION", "待调度确认", "尚未保位", "调度", canConfirm ? "CONFIRM" : "VIEW", "保存后调度可见，确认承运成功后才保位", missing);
+            }
+            case "CONFIRMED" -> booking.getIncomingNo() == null
+                ? progress("AWAITING_INCOMING", "尚未安排来货", "已保留货位", "调度", "INCOMING", "确定来货安排后再生成来货单", List.of())
+                : incomingStatus != null && List.of("WAIT_CUSTOMER_CONFIRMATION","READY_FOR_DISPATCH").contains(incomingStatus)
+                    ? progress("AWAITING_RECEIPT_CHECK", "实收完成待核量", "已保留货位", "调度", "RECEIPT", "核对预报与实收差异、容量及约定运费", List.of())
+                    : progress("RECEIVING", "已安排来货", "已保留货位", "仓库", "VIEW", incomingStatus == null ? "收货进度暂不可确认，请打开本票进度核对" : "等待仓库实际收货，销售跟进客户送仓", List.of());
+            case "RECEIVED" -> progress("READY_TO_BIND", "实收已核对", "已保留货位", "调度", "BIND", "确认排入原车次，仍需后续审核和实际作业", List.of());
+            case "BOUND" -> progress("BOUND", "已排入本车", "已转为本车货物", "审核 / 仓库", "VIEW", "排入不等于已装车或发车，请查看关联排车作业", List.of());
+            default -> progress("CANCELLED", "已取消", "未保留货位", "无待办", "VIEW", "原登记保留供追溯", List.of());
+        };
+    }
+
+    private static FleetCapacityOfferModels.Progress progress(String stage, String label, String reservation,
+        String owner, String action, String message, List<String> missing) {
+        return new FleetCapacityOfferModels.Progress(stage, label, reservation, owner, action, message, missing);
+    }
+    private static boolean blank(String value) { return value == null || value.isBlank(); }
+    private static boolean positive(BigDecimal value) { return value != null && value.signum() > 0; }
+}
@@ -0,0 +1,81 @@
+package com.baiyue.lastleg.fleet.trip;
+
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.*;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.server.ResponseStatusException;
+import org.springframework.security.core.context.SecurityContextHolder;
+import java.util.*;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+
+/** Shared by dispatch and appointment consumers; all business writes commit together. */
+@Service
+public class FleetTripPreparationService {
+    public record Prepare(@Size(max=64) String tripNo,@Min(0) Long recordVersion,
+        @Valid FleetTripModels.Create plan,@Positive Long vehicleId,@Positive Long driverId,
+        @NotEmpty @Size(max=100) List<@NotBlank @Size(max=64) String> dispatchNos,
+        @NotBlank @Size(min=8,max=128) String idempotencyKey) { }
+    private final FleetTripService service;
+    private final FleetTripMapper trips;
+    private final FleetCapacityOfferCommandMapper commands;
+    private final ObjectMapper json;
+    public FleetTripPreparationService(FleetTripService service,FleetTripMapper trips,FleetCapacityOfferCommandMapper commands,ObjectMapper json) {
+        this.service=service;this.trips=trips;this.commands=commands;this.json=json;
+    }
+    @Transactional
+    public FleetTripModels.Detail prepare(String operator,Prepare request) {
+        boolean create=request.tripNo()==null||request.tripNo().isBlank();
+        if(create) { permission("platform:fleet:trip:create");permission("platform:fleet:trip:assign"); }
+        permission("platform:fleet:trip:edit");
+        if(new HashSet<>(request.dispatchNos()).size()!=request.dispatchNos().size())throw conflict("排车单不能重复选择");
+        if(create && (request.plan()==null||request.vehicleId()==null||request.driverId()==null))throw conflict("新建车次请填写计划、车辆和司机");
+        if(!create && (request.plan()!=null||request.vehicleId()!=null||request.driverId()!=null||request.recordVersion()==null))throw conflict("加入已有车次请提交车次版本，不重复修改资源或计划");
+        var initial=create?trips.findCreated(operator,request.idempotencyKey()):trips.findByNo(request.tripNo());
+        if(!create&&initial==null)throw conflict("所选车次不存在");
+        String payload=write(request);
+        if(initial!=null) {
+            var locked=trips.lockByNo(initial.getTripNo());
+            var previous=commands.find(locked.getId(),operator,"PREPARE_TRIP",locked.getTripNo(),request.idempotencyKey());
+            if(previous!=null) {
+                if(!Objects.equals(previous.getRequestHash(),hash(payload)))throw conflict("同一安排请求不能更换内容");
+                try{return json.readValue(previous.getResultJson(),FleetTripModels.Detail.class);}catch(Exception e){throw new IllegalStateException(e);}
+            }
+            if(create)throw conflict("该新建请求已被其他操作使用，请核对原车次");
+        }
+        FleetTripModels.Detail detail;
+        if(create) {
+            var p=request.plan();
+            detail=service.create(operator,new FleetTripModels.Create(p.warehouseId(),p.plannedDepartureAt(),p.expectedDriverEndAt(),p.stops(),p.remark(),request.idempotencyKey()));
+            // Concurrent same-key create may have committed while waiting for its unique constraint.
+            var locked=trips.lockByNo(detail.trip().tripNo());
+            var previous=commands.find(locked.getId(),operator,"PREPARE_TRIP",locked.getTripNo(),request.idempotencyKey());
+            if(previous!=null) {
+                if(!Objects.equals(previous.getRequestHash(),hash(payload)))throw conflict("同一安排请求不能更换内容");
+                try{return json.readValue(previous.getResultJson(),FleetTripModels.Detail.class);}catch(Exception e){throw new IllegalStateException(e);}
+            }
+            detail=service.assign(detail.trip().tripNo(),operator,new FleetTripModels.Assign(detail.trip().recordVersion(),request.vehicleId(),request.driverId(),"安排车次时分配资源"));
+        } else {
+            detail=service.detail(request.tripNo());
+            if(detail.trip().recordVersion()!=request.recordVersion())throw conflict("车次已变化，请重新核对");
+        }
+        for(String number:request.dispatchNos().stream().sorted().toList())
+            detail=service.bindDispatch(detail.trip().tripNo(),operator,new FleetTripModels.BindingCommand(detail.trip().recordVersion(),number,"勾选待运货物安排车次"));
+        var row=trips.findByNo(detail.trip().tripNo());
+        var command=new FleetCapacityOfferCommand();command.setId(IdWorker.getId());command.setTripId(row.getId());command.setOperatorId(operator);
+        command.setAction("PREPARE_TRIP");command.setScopeNo(row.getTripNo());command.setIdempotencyKey(request.idempotencyKey());command.setRequestHash(hash(payload));
+        command.setResultJson(write(detail));command.setCreatedAt(LocalDateTime.now(ZoneOffset.UTC));commands.insert(command);
+        return detail;
+    }
+    private static void permission(String name) {
+        var auth=SecurityContextHolder.getContext().getAuthentication();
+        if(auth==null||auth.getAuthorities().stream().noneMatch(a->name.equals(a.getAuthority())))throw new ResponseStatusException(HttpStatus.FORBIDDEN,"缺少安排车次所需权限");
+    }
+    private String write(Object value){try{return json.writeValueAsString(value);}catch(Exception e){throw new IllegalStateException(e);}}
+    private static String hash(String value){try{return HexFormat.of().formatHex(java.security.MessageDigest.getInstance("SHA-256").digest(value.getBytes(java.nio.charset.StandardCharsets.UTF_8)));}catch(Exception e){throw new IllegalStateException(e);}}
+    private static ResponseStatusException conflict(String message){return new ResponseStatusException(HttpStatus.CONFLICT,message);}
+}
@@ -190,6 +190,15 @@ public class FleetTripService {
        return detail(trip);
    }

+    @jakarta.annotation.Resource private FleetDispatchPlanningGateway planning;
+    @Transactional(readOnly=true,isolation=org.springframework.transaction.annotation.Isolation.REPEATABLE_READ)
+    public com.baiyue.common.core.api.PageResult<FleetDispatchPlanningGateway.Candidate> dispatchCandidates(String tripNo,String keyword,int page,int size) {
+        var trip=trips.findByNo(tripNo);
+        if(trip==null)throw new org.springframework.web.server.ResponseStatusException(org.springframework.http.HttpStatus.NOT_FOUND,"车次不存在");
+        if(!"PLANNED".equals(trip.getStatus()))throw conflict("仅计划中的车次可以添加待运货物");
+        return planning.candidates(tripNo,trip.getWarehouseId().toString(),keyword,page,size);
+    }
+
    @Transactional
    public FleetTripModels.Detail bindDispatch(String tripNo, String operator, FleetTripModels.BindingCommand request) {
        var trip = planned(tripNo, request.recordVersion());
@@ -45,4 +45,16 @@ public class PlatformFleetCapacityOfferController {
    public ApiResponse<List<FleetCapacityOfferModels.CustomerOption>> customers(@RequestParam(required=false) String keyword){return ApiResponse.success(service.customerOptions(keyword));}
    @GetMapping("/{offerNo}/quote-candidates") @PreAuthorize("hasAuthority('platform:fleet:quote:list') and hasAnyAuthority('platform:fleet:capacity-offer:list','platform:fleet:capacity-offer:manage')")
    public ApiResponse<PageResult<FleetQuoteCandidateModels.SourceSnapshot>> quoteCandidates(@PathVariable String offerNo,@Valid FleetBookingModels.QuoteCandidatesQuery query){return ApiResponse.success(service.quoteCandidates(offerNo,query));}
+    @GetMapping("/inquiries/{bookingNo}/fulfillment") @PreAuthorize("hasAnyAuthority('platform:fleet:capacity-offer:list','platform:fleet:capacity-offer:manage')")
+    public ApiResponse<FleetCapacityOfferModels.Fulfillment> fulfillment(@PathVariable String bookingNo){return ApiResponse.success(service.fulfillment(bookingNo));}
+    @PostMapping("/inquiries/{bookingNo}/incoming") @PreAuthorize("hasAuthority('platform:fleet:capacity-offer:manage') and hasAuthority('platform:fleet:trip:booking-edit')")
+    public ApiResponse<FleetBookingModels.Result> incoming(@PathVariable String bookingNo,@Valid @RequestBody FleetBookingModels.StartIncoming request){return ApiResponse.success(service.arrangeIncoming(bookingNo,request));}
+    @PostMapping("/inquiries/{bookingNo}/receipt-confirmation") @PreAuthorize("hasAuthority('platform:fleet:capacity-offer:manage') and hasAuthority('platform:fleet:trip:booking-confirm')")
+    public ApiResponse<FleetBookingModels.Result> receipt(@PathVariable String bookingNo,@Valid @RequestBody FleetBookingModels.AcceptReceipt request){return ApiResponse.success(service.acceptReceipt(bookingNo,request));}
+    @PostMapping("/inquiries/{bookingNo}/arrange-dispatch") @PreAuthorize("hasAuthority('platform:fleet:capacity-offer:manage') and hasAuthority('platform:fleet:trip:booking-edit') and hasAuthority('platform:fleet:trip:edit') and hasAuthority('platform:overseas-warehouse:inbound-order:smart-dispatch')")
+    public ApiResponse<FleetBookingModels.Result> arrange(@PathVariable String bookingNo,@Valid @RequestBody FleetBookingModels.Command request){return ApiResponse.success(service.arrangeDispatch(bookingNo,request));}
+
+    @PostMapping("/inquiries/{bookingNo}/save-and-confirm") @PreAuthorize("hasAuthority('platform:fleet:capacity-offer:manage')")
+    public ApiResponse<FleetCapacityOfferModels.InquiryResult> saveAndConfirm(@PathVariable String bookingNo,@Valid @RequestBody FleetCapacityOfferModels.InquiryWrite request){return ApiResponse.success(service.saveAndConfirm(bookingNo,request));}
+
 }
@@ -17,6 +17,13 @@ import org.springframework.web.server.ResponseStatusException;
@Validated
@RequestMapping("/api/platform/v1/last-leg/fleet/trips")
 public class PlatformFleetTripController {
+    @jakarta.annotation.Resource private FleetTripPreparationService preparation;
+    @PostMapping("/prepare")
+    @PreAuthorize("hasAuthority('platform:fleet:trip:edit')")
+    public ApiResponse<FleetTripModels.Detail> prepare(@AuthenticationPrincipal AuthenticatedUser user,
+        @Valid @RequestBody FleetTripPreparationService.Prepare request) {
+        return ApiResponse.success(preparation.prepare(operator(user),request));
+    }
    private final FleetTripService service;
    private final FleetTripExecutionService execution;
    private final FleetTripCompletionService completion;
@@ -50,6 +57,13 @@ public class PlatformFleetTripController {
    public ApiResponse<FleetTripModels.Detail> cancel(@AuthenticationPrincipal AuthenticatedUser user, @PathVariable String tripNo, @Valid @RequestBody FleetTripModels.Cancel request) {
        return ApiResponse.success(service.cancel(tripNo, operator(user), request));
    }
+    @GetMapping("/{tripNo}/dispatch-candidates")
+    @PreAuthorize("hasAuthority('platform:fleet:trip:list')")
+    public ApiResponse<PageResult<FleetDispatchPlanningGateway.Candidate>> dispatchCandidates(@PathVariable String tripNo,
+        @RequestParam(required=false) String keyword,@RequestParam(defaultValue="1") @Min(1) int page,
+        @RequestParam(defaultValue="20") @Min(1) @Max(100) int size) {
+        return ApiResponse.success(service.dispatchCandidates(tripNo,keyword,page,size));
+    }
    @PostMapping("/{tripNo}/dispatches/bind")
    @PreAuthorize("hasAuthority('platform:fleet:trip:edit')")
    public ApiResponse<FleetTripModels.Detail> bind(@AuthenticationPrincipal AuthenticatedUser user, @PathVariable String tripNo,
@@ -24,6 +24,16 @@ public class FleetIncomingAdapter implements FleetBookingIncomingGateway {
    private final ObjectMapper json;
    public FleetIncomingAdapter(WarehouseTransferService service,WarehouseTransferOrderMapper orders,ObjectMapper json){this.service=service;this.orders=orders;this.json=json;}
    @Override @Transactional(propagation=Propagation.MANDATORY)
+    public Map<Source,String> statuses(List<Source> sources) {
+        if(sources.isEmpty())return Map.of();
+        if(sources.size()>100)throw conflict("每次最多读取100条来货进度");
+        var query=new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper<com.baiyue.lastleg.transfer.entity.WarehouseTransferOrder>();
+        query.and(q->{for(var source:sources)q.or(c->c.eq(com.baiyue.lastleg.transfer.entity.WarehouseTransferOrder::getCustomerId,source.customerId()).eq(com.baiyue.lastleg.transfer.entity.WarehouseTransferOrder::getTransferNo,source.incomingNo()));});
+        var result=new HashMap<Source,String>();
+        for(var row:orders.selectList(query))result.put(new Source(row.getCustomerId(),row.getTransferNo()),row.getStatus());
+        return Map.copyOf(result);
+    }
+    @Override @Transactional(propagation=Propagation.MANDATORY)
    public Evidence create(String operator,Incoming input){
        boolean fba=input.cargo().destinationKey().startsWith("FBA:");
        String code=fba?input.cargo().destinationKey().substring(4):null;
@@ -1624,6 +1624,30 @@ CREATE TABLE IF NOT EXISTS ll_pda_inventory_move (
  KEY idx_ll_pda_inventory_move_pallet(overseas_warehouse_id,pallet_id,created_at)
 ) ENGINE=InnoDB COMMENT='海外PDA同仓整托移库记录';

+CREATE TABLE IF NOT EXISTS ll_appointment_followup (
+  id BIGINT NOT NULL COMMENT '预约筹划跟进记录ID',
+  source_key VARCHAR(160) NOT NULL COMMENT '稳定ORDER或BOOKING来源键，不因实收转换而变化',
+  customer_id VARCHAR(128) NOT NULL COMMENT '服务端核实的来源客户',
+  source_order_id BIGINT NULL COMMENT '已形成的真实尾程货源ID，尚未生成时为空',
+  stage VARCHAR(32) NOT NULL COMMENT '跟进对象：DRAYAGE_CONTACT/TERMINAL_APPOINTMENT/WAREHOUSE_RECEIVING/FBA_RECEIVING',
+  version INT NOT NULL COMMENT '同一货源及跟进对象的记录版本',
+  contacted_party VARCHAR(200) NULL COMMENT '本次联系对象，不替代承运主档',
+  result VARCHAR(1000) NOT NULL COMMENT '本次反馈事实，不自动确认预约或推进实物作业',
+  next_action VARCHAR(500) NULL COMMENT '下一步安排',
+  followup_date DATE NULL COMMENT '按业务地点当地日期记录的下次跟进日',
+  operator_id VARCHAR(128) NOT NULL COMMENT '登录平台操作者ID',
+  operator_name VARCHAR(200) NULL COMMENT '操作人姓名快照',
+  command_key VARCHAR(64) NOT NULL COMMENT '持久幂等键',
+  request_hash CHAR(64) NOT NULL COMMENT '含操作者身份的请求SHA256摘要',
+  created_at DATETIME(3) NOT NULL COMMENT 'UTC记录时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_appointment_followup_version (source_key,stage,version),
+  UNIQUE KEY uk_appointment_followup_command (source_key,stage,command_key),
+  KEY idx_appointment_followup_date (followup_date,source_order_id),
+  CONSTRAINT fk_appointment_followup_order FOREIGN KEY (source_order_id) REFERENCES ll_order(id),
+  CONSTRAINT chk_appointment_followup_stage CHECK (stage IN ('DRAYAGE_CONTACT','TERMINAL_APPOINTMENT','WAREHOUSE_RECEIVING','FBA_RECEIVING'))
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='真实在途货源的预约筹划联系记录，追加留痕';
+
 CREATE TABLE IF NOT EXISTS ll_inbound_fba_appointment (
  id BIGINT NOT NULL COMMENT '主键ID',
  appointment_no VARCHAR(64) NOT NULL COMMENT '预约单号',
@@ -0,0 +1,230 @@
+openapi: 3.0.3
+info:
+  title: 美国预约筹划货源
+  version: 1.0.0
+  description: 读取真实已开船头程货物，不要求预先创建入仓计划，不生成库存、车次或对外确认。
+security:
+  - bearerAuth: []
+paths:
+  /api/platform/v1/last-leg/appointment-planning/cargo:
+    get:
+      operationId: appointmentPlanningCargo
+      summary: 分页读取美国FBA筹划货源
+      description: >-
+        仅平台身份；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
+        从公共仓库目录核对美国接仓点与美国FBA目的仓；目录失败返回错误，不冒充空结果。
+        当前读取FIRST_LEG货物与已确认开船或更晚的实际船节点，未建计划可见；已有计划不重复计数。
+        预计时间来自尾程订单保存的来源快照，不代表实时船司ETA；shippingObservedAt仅是实际节点观察时间。
+        sourcePalletCount是头程预报托数，不是海外实测托位。其他货源由后续正式合同接入，不能从本接口推断已支持。
+      parameters:
+        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
+        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
+        - {name: warehouseId, in: query, schema: {type: string}, description: 美国接仓点主档ID，仅用于关联}
+        - {name: destination, in: query, schema: {type: string}, description: 美国FBA仓编码}
+        - {name: keyword, in: query, schema: {type: string, maxLength: 128}, description: 入仓码、柜号或客户名称}
+      responses:
+        '200':
+          description: 业务响应，必须核对code
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data:
+                    type: object
+                    properties:
+                      records: {type: array, items: {$ref: '#/components/schemas/Cargo'}}
+                      page: {type: integer}
+                      size: {type: integer}
+                      total: {type: integer}
+                      pages: {type: integer}
+        '400': {description: 查询参数或美国范围无效}
+        '403': {description: 无来源读取权限或非平台身份}
+        '503': {description: 仓库目录暂不可用，不能证明美国货源范围}
+  /api/platform/v1/last-leg/appointment-planning/sources/resolve:
+    get:
+      operationId: resolveAppointmentPlanningSource
+      summary: 核对深链来源并读取预约覆盖
+      description: >-
+        仅平台；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
+        依据真实客户、货源与美国仓目录核对来源，URL参数不能授予预约资格。
+        ORDER仅接受已开船头程FBA货；BOOKING保留原登记身份，确认承运后尚未生成入仓单也能跟进。
+        此查询不建单、不确认预约。当前覆盖读取已有FBA预约，尚未生成货物时返回SOURCE_NOT_MATERIALIZED。
+      parameters:
+        - {name: sourceKey, in: query, required: true, schema: {type: string, maxLength: 160}, description: 'ORDER:<内部关联ID>或BOOKING:<登记号>，非用户展示编号'}
+        - {name: customerId, in: query, required: true, schema: {type: string, maxLength: 128}}
+        - {name: destinationKey, in: query, schema: {type: string}, description: 'FBA:<仓编码>，传入后必须与真实来源一致'}
+      responses:
+        '200':
+          description: code=200时data包含已核实来源和预约覆盖
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data:
+                    type: object
+                    properties:
+                      source: {$ref: '#/components/schemas/PlanningSource'}
+                      coverage: {$ref: '#/components/schemas/Coverage'}
+        '400': {description: 非美国FBA来源、尚未开船或目的地变化}
+        '403': {description: 无读取权限或非平台身份}
+        '404': {description: 客户与来源不匹配或来源不存在}
+        '503': {description: 仓库目录不可用}
+  /api/platform/v1/last-leg/appointment-planning/sources/{sourceKey}/follow-ups:
+    parameters:
+      - {name: sourceKey, in: path, required: true, schema: {type: string, maxLength: 160}, description: 'ORDER或BOOKING稳定来源键，路径须URL编码'}
+      - {name: customerId, in: query, required: true, schema: {type: string, maxLength: 128}}
+    get:
+      summary: 分页读取分事项跟进历史与最新版本
+      description: 仅平台；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。已有跟进历史在货物完成后仍可读取。
+      parameters:
+        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
+        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
+      responses:
+        '200':
+          description: code=200时data含history分页和按stage排列的versions；createdAt为UTC时间点，followupDate为业务地点当地日期。
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data:
+                    type: object
+                    properties:
+                      history:
+                        type: object
+                        properties:
+                          records: {type: array, items: {$ref: '#/components/schemas/FollowupRecord'}}
+                          page: {type: integer}
+                          size: {type: integer}
+                          total: {type: integer}
+                          pages: {type: integer}
+                      versions: {type: object, additionalProperties: {type: integer, minimum: 0}, description: 四个事项各自的最新版本}
+        '403': {description: 无读取权限或非平台身份}
+        '404': {description: 无历史且来源不具备美国筹划资格}
+    post:
+      summary: 追加人工联系结果与下次跟进
+      description: >-
+        仅平台；除读取权限外要求platform:appointment:followup。
+        跟进人来自登录主体，不接受客户端操作者ID。核实来源后按stage版本追加，以持久化唯一约束防止并发覆盖；幂等键持久化，同键同操作者同内容返回原记录，异内容拒绝。
+        不要求已创建入仓计划、外部预约号或司机，不更新正式预约、库存和车次。设置followupDate时nextAction必填。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [stage, expectedVersion, idempotencyKey, result]
+              properties:
+                stage: {type: string, enum: [DRAYAGE_CONTACT, TERMINAL_APPOINTMENT, WAREHOUSE_RECEIVING, FBA_RECEIVING]}
+                expectedVersion: {type: integer, minimum: 0, description: 初次为0，后续取history.versions中对应事项版本}
+                idempotencyKey: {type: string, maxLength: 64}
+                contactedParty: {type: string, maxLength: 200, nullable: true}
+                result: {type: string, minLength: 1, maxLength: 1000}
+                nextAction: {type: string, maxLength: 500, nullable: true}
+                followupDate: {type: string, format: date, nullable: true}
+      responses:
+        '200':
+          description: data为原记录或新增记录
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  message: {type: string}
+                  data: {$ref: '#/components/schemas/FollowupRecord'}
+        '400': {description: 无效事项或缺少下一步安排}
+        '403': {description: 无写权限或非平台身份}
+        '404': {description: 来源不存在或不可筹划}
+        '409': {description: 版本冲突或同键异内容}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
+  schemas:
+    FollowupRecord:
+      type: object
+      properties:
+        stage: {type: string, enum: [DRAYAGE_CONTACT, TERMINAL_APPOINTMENT, WAREHOUSE_RECEIVING, FBA_RECEIVING]}
+        version: {type: integer, minimum: 1}
+        contactedParty: {type: string, nullable: true}
+        result: {type: string}
+        nextAction: {type: string, nullable: true}
+        followupDate: {type: string, format: date, nullable: true}
+        operatorName: {type: string, nullable: true}
+        createdAt: {type: string, format: date-time, description: UTC时间点}
+    PlanningSource:
+      type: object
+      properties:
+        sourceKey: {type: string}
+        customerId: {type: string}
+        orderId: {type: string, nullable: true}
+        inboundCode: {type: string, nullable: true}
+        bookingNo: {type: string, nullable: true}
+        containerNo: {type: string, nullable: true}
+        originWarehouseId: {type: string}
+        originWarehouseName: {type: string}
+        destinationKey: {type: string}
+        destinationWarehouseCode: {type: string}
+        packages: {type: integer, nullable: true, description: 未知数量保持空值，不能替换为0}
+        sourceVersion: {type: string, nullable: true}
+        canFollowup: {type: boolean}
+        blockReasons: {type: array, items: {type: string}}
+    Coverage:
+      type: object
+      properties:
+        customerId: {type: string}
+        sourceKey: {type: string}
+        destinationKey: {type: string}
+        status: {type: string, enum: [SOURCE_NOT_FOUND, SOURCE_NOT_MATERIALIZED, SOURCE_NOT_READY, DESTINATION_MISMATCH, UNASSIGNED, PARTIAL, PENDING, CONFIRMED, REVIEW_REQUIRED]}
+        sourceVersion: {type: string, nullable: true}
+        changeReviewRequired: {type: boolean}
+        missingFields: {type: array, items: {type: string}, description: 缺项或待核实原因代码，客户端需显示业务文案}
+        appointments:
+          type: array
+          items:
+            type: object
+            properties:
+              appointmentNo: {type: string}
+              confirmationNo: {type: string, nullable: true}
+              status: {type: string}
+              confirmedAt: {type: string, nullable: true}
+              confirmedEndAt: {type: string, nullable: true}
+              timezone: {type: string, nullable: true, description: 旧预约未记录时区时为空并返回缺项，不能按浏览器时区推定}
+    Cargo:
+      type: object
+      properties:
+        sourceKey: {type: string, description: 稳定ORDER来源键，不因生成入仓计划而变化；非展示编号}
+        orderId: {type: string}
+        customerId: {type: string}
+        customerName: {type: string, nullable: true}
+        inboundCode: {type: string, nullable: true}
+        containerBookingId: {type: string}
+        containerNo: {type: string, nullable: true}
+        originWarehouseId: {type: string}
+        originWarehouseCode: {type: string}
+        originWarehouseName: {type: string}
+        destinationWarehouseCode: {type: string}
+        packages: {type: integer, nullable: true}
+        receivedPackages: {type: integer, nullable: true}
+        shippedPackages: {type: integer, nullable: true}
+        sourcePalletCount: {type: integer, nullable: true}
+        volumeCbm: {type: number, nullable: true}
+        estimatedArrivalAt: {type: string, nullable: true, description: 来源预计到港快照，保留原业务当地时间；不得按浏览器时区转换}
+        estimatedWarehouseAt: {type: string, nullable: true, description: 已保存预计到仓，不因本查询改变}
+        orderVersion: {type: integer}
+        standardNode: {type: string}
+        shippingVersion: {type: string, nullable: true}
+        shippingObservedAt: {type: string, nullable: true}
+        shippingProvider: {type: string, nullable: true}
+        hasInboundPlan: {type: boolean}
+        hasActiveAppointment: {type: boolean}
+        detained: {type: boolean}
+        mixedDestinations: {type: boolean, description: 存在其他目的地明细时，不能按整票默认为同仓货物}
@@ -376,7 +376,7 @@ paths:
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries:
    get:
      summary: 分页查询本人或获准的全部意向
-      description: 权限：platform:fleet:capacity-offer:list 或 platform:fleet:capacity-offer:manage。ALL只允许manage；销售负责人由登录身份过滤，历史不依赖发布仍OPEN。
+      description: 权限：platform:fleet:capacity-offer:list 或 platform:fleet:capacity-offer:manage。ALL和TODO只允许manage；TODO按服务端负责角色筛选调度待办，基础候选超过100条要求按客户或登记号缩小范围，过滤后精确分页，不按当前页伪造总数；销售负责人由登录身份过滤，历史不依赖发布仍OPEN。
      responses:
        '200':
          description: 统一业务响应；code=200成功，冲突或资格拒绝不得当成功
@@ -440,6 +440,7 @@ paths:
          enum:
          - MINE
          - ALL
+          - TODO
          default: MINE
  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}:
    get:
@@ -985,8 +986,41 @@ components:
        actions:
          $ref: '#/components/schemas/OfferActions'
    Inquiry:
+      description: 登记返回服务端资料缺项与处理进度；canConfirm同时核对本票完整性和目的地三维余位，最终写命令仍复验。
      type: object
      properties:
+        appointmentCoverage:
+          type: object
+          nullable: true
+          description: FBA来源通过AppointmentCoverageService按客户和BOOKING稳定来源批量读取；无订单保留待形成货件资料，私人目的地为null。不把保位当收货预约，不推算未知时区。
+          properties:
+            status: {type: string}
+            sourceVersion: {type: string, nullable: true}
+            changeReviewRequired: {type: boolean}
+            missingFields: {type: array, items: {type: string}}
+            appointments:
+              type: array
+              items:
+                type: object
+                properties:
+                  appointmentNo: {type: string}
+                  confirmationNo: {type: string, nullable: true}
+                  status: {type: string}
+                  confirmedAt: {type: string, nullable: true}
+                  confirmedEndAt: {type: string, nullable: true}
+                  timezone: {type: string, nullable: true}
+        progress:
+          type: object
+          description: 只读派生处理提示，不是可写状态；负责人及动作按资料完整性、承运/来货/实收事实返回；保存不保位。
+          required: [stage, label, reservation, owner, primaryAction, message, missingFields]
+          properties:
+            stage: {type: string}
+            label: {type: string}
+            reservation: {type: string}
+            owner: {type: string}
+            primaryAction: {type: string, enum: [VIEW, EDIT, CONFIRM, INCOMING, RECEIPT, BIND]}
+            message: {type: string}
+            missingFields: {type: array, items: {type: string}}
        bookingNo:
          type: string
        offerNo:
@@ -0,0 +1,103 @@
+openapi: 3.0.3
+info:
+  title: 共用车次准备与拼车连续处理
+  version: 1.0.0
+security:
+  - bearerAuth: []
+paths:
+  /api/platform/v1/last-leg/fleet/trips/prepare:
+    post:
+      summary: 原子新建或加入车次并关联所选排车单
+      description: '权限：platform:fleet:trip:edit；新建另需platform:fleet:trip:create和platform:fleet:trip:assign。新建、资源分配和全部关联在同一事务，失败回滚；幂等键同载荷重放原结果，异载荷拒绝。同仓、未执行、未绑定其他车次；不确认容量、不审批、不发车。'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/Prepare'}
+      responses:
+        '200': {description: '统一ApiResponse，data为FleetTripModels.Detail；code=200才成功'}
+  /api/platform/v1/last-leg/fleet/trips/{tripNo}/dispatch-candidates:
+    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/TripNo'}]
+    get:
+      summary: 本仓未关联且未开始执行的排车候选
+      description: '权限：platform:fleet:trip:list。数据库筛选后分页，绑定时重新锁定校验。候选不代表预约、装载或审核已完成。'
+      parameters:
+        - {name: keyword, in: query, schema: {type: string}}
+        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
+        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
+      responses:
+        '200': {description: '统一分页data：records含dispatchNo、customerId、warehouseId、packageCount、route及total/page/size/pages；内部身份不作为用户业务编号'}
+  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/save-and-confirm:
+    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
+    post:
+      summary: 同窗补齐登记资料并原子确认承运
+      description: '权限：platform:fleet:capacity-offer:manage。复用InquiryWrite，更新资料、创建唯一商业订单及占位同事务；任何阶段失败全部回滚，不把保存当成交。同键同载荷返回原结果。'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: './fleet-capacity-offers-v1.yaml#/components/schemas/InquiryWrite'}
+      responses:
+        '200': {description: '统一ApiResponse，data为InquiryResult'}
+  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/fulfillment:
+    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
+    get:
+      summary: 从原登记查看本票履约进度
+      description: '权限：platform:fleet:capacity-offer:list或platform:fleet:capacity-offer:manage。销售仅本人；返回本票booking、preview及plannedDepartureAt，不返回整车司机或他人货物。preview含tripRecordVersion、recordVersion、incoming，未安排时incoming为null。'
+      responses:
+        '200': {description: '统一ApiResponse，data为Fulfillment'}
+  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/incoming:
+    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
+    post:
+      summary: 从原登记明确安排来货
+      description: '权限：platform:fleet:capacity-offer:manage和platform:fleet:trip:booking-edit。复用版本及幂等门禁，未填时间时沿用登记预计到仓，仍缺失则拒绝，不自动减两小时猜测。承运确认不自动调用此命令。'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: './fleet-trips-v1.yaml#/components/schemas/BookingIncoming'}
+      responses:
+        '200': {$ref: './fleet-trips-v1.yaml#/components/responses/BookingResult'}
+  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/receipt-confirmation:
+    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
+    post:
+      summary: 原登记核对真实实收与约定运费
+      description: '权限：platform:fleet:capacity-offer:manage和platform:fleet:trip:booking-confirm。沿实际receiptHash/托盘和三维容量校验；不以预报覆盖实收。'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: './fleet-trips-v1.yaml#/components/schemas/BookingAcceptReceipt'}
+      responses:
+        '200': {$ref: './fleet-trips-v1.yaml#/components/responses/BookingResult'}
+  /api/platform/v1/last-leg/fleet/capacity-offers/inquiries/{bookingNo}/arrange-dispatch:
+    parameters: [{$ref: './fleet-trips-v1.yaml#/components/parameters/BookingNo'}]
+    post:
+      summary: 实收后复用或生成排车并原子排入本车
+      description: '权限：platform:fleet:capacity-offer:manage、platform:fleet:trip:booking-edit、platform:fleet:trip:edit和platform:overseas-warehouse:inbound-order:smart-dispatch。锁原车次和本票来货，先校验实收快照、车辆、有效容量；来源有多张排车或不完整时拒绝，不另建。无排车时复用真实预排命令；任何校验或绑定失败整体回滚。同键重放不重复建单。成功将预留替换为BOUND，旧计划失效待核对，仍需审核和现场作业。'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: './fleet-trips-v1.yaml#/components/schemas/BookingCommand'}
+      responses:
+        '200': {$ref: './fleet-trips-v1.yaml#/components/responses/BookingResult'}
+components:
+  securitySchemes:
+    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
+  schemas:
+    Prepare:
+      type: object
+      required: [dispatchNos, idempotencyKey]
+      properties:
+        tripNo: {type: string, nullable: true, maxLength: 64}
+        recordVersion: {type: integer, format: int64, nullable: true, minimum: 0}
+        plan:
+          allOf:
+            - {$ref: './fleet-trips-v1.yaml#/components/schemas/Create'}
+          nullable: true
+          description: 仅新建提交，实际创建幂等键使用外层idempotencyKey。
+        vehicleId: {type: string, nullable: true}
+        driverId: {type: string, nullable: true}
+        dispatchNos: {type: array, minItems: 1, maxItems: 100, uniqueItems: true, items: {type: string, maxLength: 64}}
+        idempotencyKey: {type: string, minLength: 8, maxLength: 128}
@@ -0,0 +1,45 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.session.Configuration;
+import org.apache.ibatis.session.SqlSessionFactoryBuilder;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.Test;
+import java.util.List;
+import java.util.UUID;
+import static org.junit.jupiter.api.Assertions.*;
+
+class AppointmentCargoMapperTest {
+    @Test void unplannedSailedCargoIsVisibleAndCreatingPlansDoesNotDuplicateTheSource() throws Exception {
+        var ds = new JdbcDataSource(); ds.setURL("jdbc:h2:mem:appointment-"+ UUID.randomUUID()+";MODE=MySQL;DB_CLOSE_DELAY=-1");
+        try (var c=ds.getConnection(); var s=c.createStatement()) {
+            s.execute("CREATE TABLE ll_order(id BIGINT,customer_id VARCHAR,customer_name VARCHAR,inbound_code VARCHAR,source_container_booking_id VARCHAR,container_no VARCHAR,overseas_warehouse_id VARCHAR,overseas_warehouse_code VARCHAR,overseas_warehouse_name VARCHAR,fba_warehouse_code VARCHAR,package_count INT,received_package_count INT,shipped_package_count INT,pallet_count INT,volume_cbm DECIMAL,estimated_arrival_at TIMESTAMP,estimated_warehouse_at TIMESTAMP,version INT,detained BOOLEAN,order_type VARCHAR,destination_type VARCHAR,current_status VARCHAR,created_at TIMESTAMP)");
+            s.execute("CREATE TABLE ll_container_shipping_gate(container_booking_id VARCHAR,node_sequence INT,standard_node VARCHAR,aggregate_version BIGINT,observed_at TIMESTAMP,provider_code VARCHAR)");
+            s.execute("CREATE TABLE ll_inbound_plan(id BIGINT,source_order_id BIGINT,customer_id VARCHAR)");
+            s.execute("CREATE TABLE ll_inbound_fba_appointment_item(order_id BIGINT,customer_id VARCHAR,appointment_id BIGINT)");
+            s.execute("CREATE TABLE ll_inbound_fba_appointment(id BIGINT,appointment_status VARCHAR)");
+            s.execute("CREATE TABLE ll_order_detail(order_id BIGINT,customer_id VARCHAR,destination_warehouse_code VARCHAR)");
+            s.execute("INSERT INTO ll_order(id,customer_id,inbound_code,source_container_booking_id,overseas_warehouse_id,fba_warehouse_code,package_count,order_type,destination_type,current_status,created_at) VALUES(1,'A','IN-A','C1','100','ONT8',10,'FIRST_LEG','FBA','WAIT_INBOUND',CURRENT_TIMESTAMP),(2,'B','IN-B','C2','100','ONT8',8,'FIRST_LEG','FBA','WAIT_INBOUND',CURRENT_TIMESTAMP)");
+            s.execute("INSERT INTO ll_container_shipping_gate(container_booking_id,node_sequence) VALUES('C1',40),('C2',30)");
+        }
+        var config=new Configuration(new Environment("test",new JdbcTransactionFactory(),ds));
+        config.setMapUnderscoreToCamelCase(true); config.addMapper(AppointmentCargoMapper.class);
+        try (var session=new SqlSessionFactoryBuilder().build(config).openSession(true)) {
+            var mapper=session.getMapper(AppointmentCargoMapper.class);
+            assertEquals(1,mapper.count(List.of("100"),List.of("ONT8"),null,null,null));
+            var first=mapper.page(List.of("100"),List.of("ONT8"),null,null,null,20,0);
+            assertEquals("ORDER:1",first.get(0).getSourceKey()); assertFalse(first.get(0).isHasInboundPlan());
+            try (var s=session.getConnection().createStatement()) {
+                s.execute("INSERT INTO ll_inbound_plan VALUES(11,1,'A'),(12,1,'A')");
+                s.execute("INSERT INTO ll_inbound_fba_appointment VALUES(20,'SUCCESS')");
+                s.execute("INSERT INTO ll_inbound_fba_appointment_item VALUES(1,'A',20)");
+            }
+            session.clearCache();
+            var after=mapper.page(List.of("100"),List.of("ONT8"),null,null,null,20,0);
+            assertEquals(1,after.size()); assertTrue(after.get(0).isHasInboundPlan()); assertTrue(after.get(0).isHasActiveAppointment());
+            assertEquals(10,after.get(0).getPackages()); assertEquals(1,mapper.count(List.of("100"),List.of("ONT8"),null,null,null));
+            assertEquals(0,mapper.count(List.of("200"),List.of("ONT8"),null,null,null));
+        }
+    }
+}
@@ -0,0 +1,44 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baiyue.common.core.api.ApiResponse;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.server.ResponseStatusException;
+import java.util.List;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+class AppointmentCargoServiceTest {
+    @Test void authenticUsDirectoryScopesTheDatabaseQueryAndPreservesServerPagination() {
+        var mapper = mock(AppointmentCargoMapper.class);
+        var warehouses = mock(AppointmentWarehouseClient.class);
+        when(warehouses.catalog("token")).thenReturn(ApiResponse.success(List.of(
+            new AppointmentWarehouseClient.Warehouse(1L,"US-WH","美国仓","OVERSEAS","US"),
+            new AppointmentWarehouseClient.Warehouse(2L,"CA-WH","加拿大仓","OVERSEAS","CA"),
+            new AppointmentWarehouseClient.Warehouse(3L,"ONT8","ONT8","FBA","US"),
+            new AppointmentWarehouseClient.Warehouse(4L,"YYZ1","YYZ1","FBA","CA"))));
+        var row = new AppointmentCargo(); row.setOrderId(99L); row.setSourceKey("ORDER:99"); row.setHasInboundPlan(false);
+        when(mapper.count(List.of("1"),List.of("ONT8"),null,null,"WT")).thenReturn(21L);
+        when(mapper.page(List.of("1"),List.of("ONT8"),null,null,"WT",20,20)).thenReturn(List.of(row));
+        var result = new AppointmentCargoService(mapper,warehouses,"token").page(2,20,null,null," WT ");
+        assertEquals(21,result.total()); assertEquals(2,result.pages()); assertEquals(1,result.records().size());
+        assertFalse(result.records().get(0).isHasInboundPlan());
+        verify(warehouses,times(1)).catalog("token");
+    }
+
+    @Test void directoryFailureIsNotReportedAsAnEmptyAmericanCargoList() {
+        var mapper = mock(AppointmentCargoMapper.class); var warehouses = mock(AppointmentWarehouseClient.class);
+        when(warehouses.catalog("token")).thenThrow(new IllegalStateException("offline"));
+        var error = assertThrows(ResponseStatusException.class, () -> new AppointmentCargoService(mapper,warehouses,"token").page(1,20,null,null,null));
+        assertEquals(503,error.getStatusCode().value()); verifyNoInteractions(mapper);
+    }
+
+    @Test void invalidPaginationAndNonUsFiltersNeverQueryCargo() {
+        var mapper = mock(AppointmentCargoMapper.class); var warehouses = mock(AppointmentWarehouseClient.class);
+        var service = new AppointmentCargoService(mapper,warehouses,"token");
+        assertThrows(ResponseStatusException.class, () -> service.page(0,20,null,null,null));
+        verifyNoInteractions(warehouses);
+        when(warehouses.catalog("token")).thenReturn(ApiResponse.success(List.of()));
+        assertThrows(ResponseStatusException.class, () -> service.page(1,20,"unknown",null,null));
+        verifyNoInteractions(mapper);
+    }
+}
@@ -0,0 +1,41 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.session.Configuration;
+import org.apache.ibatis.session.SqlSessionFactoryBuilder;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.Test;
+import java.util.List;
+import java.util.UUID;
+import static org.junit.jupiter.api.Assertions.*;
+
+class AppointmentCoverageMapperTest {
+    @Test void readsOnlyMatchingCustomerAndPlanLinesAndExcludesCancelledAppointments() throws Exception {
+        var ds=new JdbcDataSource(); ds.setURL("jdbc:h2:mem:coverage-"+UUID.randomUUID()+";MODE=MySQL;DB_CLOSE_DELAY=-1");
+        try (var c=ds.getConnection();var s=c.createStatement()) {
+            s.execute("CREATE TABLE ll_order(id BIGINT,customer_id VARCHAR(128),destination_type VARCHAR(32),fba_warehouse_code VARCHAR(128),package_count INT,version INT,updated_at TIMESTAMP)");
+            s.execute("CREATE TABLE ll_order_detail(order_id BIGINT,customer_id VARCHAR(128),shipment_no VARCHAR(128),fba_tracking_no VARCHAR(128))");
+            s.execute("CREATE TABLE ll_inbound_plan_line(id BIGINT,plan_id BIGINT,order_id BIGINT,customer_id VARCHAR(128),required_package_count INT,fba_warehouse_code VARCHAR(128))");
+            s.execute("CREATE TABLE ll_inbound_fba_appointment(id BIGINT,appointment_no VARCHAR(128),appointment_status VARCHAR(32),appointment_at TIMESTAMP,appointment_end_at TIMESTAMP,updated_at TIMESTAMP)");
+            s.execute("CREATE TABLE ll_inbound_fba_appointment_item(id BIGINT,appointment_id BIGINT,order_id BIGINT,customer_id VARCHAR(128),line_id BIGINT,plan_id BIGINT)");
+            s.execute("INSERT INTO ll_order VALUES(1,'A','FBA','ONT8',20,1,CURRENT_TIMESTAMP),(2,'B','FBA','ONT8',8,1,CURRENT_TIMESTAMP)");
+            s.execute("INSERT INTO ll_order_detail VALUES(1,'A','SHIP-A',NULL),(2,'B',NULL,NULL)");
+            s.execute("INSERT INTO ll_inbound_plan_line VALUES(10,100,1,'A',20,'ONT8'),(20,200,2,'B',8,'ONT8')");
+            s.execute("INSERT INTO ll_inbound_fba_appointment VALUES(1000,'APP-1','SUCCESS',CURRENT_TIMESTAMP,NULL,CURRENT_TIMESTAMP),(2000,'CANCELLED-1','CANCELLED',CURRENT_TIMESTAMP,NULL,CURRENT_TIMESTAMP)");
+            s.execute("INSERT INTO ll_inbound_fba_appointment_item VALUES(1,1000,1,'A',10,100),(2,1000,2,'B',20,200),(3,2000,1,'A',10,100),(4,1000,1,'A',20,200)");
+        }
+        var config=new Configuration(new Environment("test",new JdbcTransactionFactory(),ds));
+        config.setMapUnderscoreToCamelCase(true); config.addMapper(AppointmentCoverageMapper.class);
+        try (var session=new SqlSessionFactoryBuilder().build(config).openSession(true)) {
+            var mapper=session.getMapper(AppointmentCoverageMapper.class);
+            var refs=List.of(new AppointmentCoverageMapper.OrderRef("A",1L));
+            var source=mapper.sources(refs).get(0); assertFalse(source.shipmentReferencesMissing()); assertEquals(20,source.packages());
+            var facts=mapper.appointments(refs); assertEquals(1,facts.size()); assertEquals("APP-1",facts.get(0).appointmentNo()); assertEquals(20,facts.get(0).packages());
+            assertTrue(mapper.sources(List.of(new AppointmentCoverageMapper.OrderRef("B",1L))).isEmpty());
+            assertTrue(mapper.sources(List.of(new AppointmentCoverageMapper.OrderRef("B",2L))).get(0).shipmentReferencesMissing());
+            try (var s=session.getConnection().createStatement()) { s.execute("INSERT INTO ll_order_detail VALUES(1,'A','  ',NULL)"); }
+            session.clearCache(); assertTrue(mapper.sources(refs).get(0).shipmentReferencesMissing());
+        }
+    }
+}
@@ -0,0 +1,65 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import org.junit.jupiter.api.Test;
+import java.time.LocalDateTime;
+import java.util.List;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+class AppointmentCoverageServiceTest {
+    private static final LocalDateTime BEFORE=LocalDateTime.of(2026,10,9,1,0), AFTER=BEFORE.plusHours(1);
+    private static AppointmentCoverageMapper.Source order() {
+        return new AppointmentCoverageMapper.Source(1L,"A","FBA","ONT8",20,2,BEFORE,false);
+    }
+    private static AppointmentCoverageMapper.Fact fact(long line,int packages,String status) {
+        return new AppointmentCoverageMapper.Fact(1L,"A","FBA-CONFIRM-1",status,AFTER.plusDays(1),null,AFTER,line,packages,"ONT8");
+    }
+    @Test void completeQuantitySharesOneAppointmentButDoesNotInventItsTimezone() {
+        var mapper=mock(AppointmentCoverageMapper.class); var gateway=mock(AppointmentExternalSourceGateway.class);
+        when(mapper.sources(anyList())).thenReturn(List.of(order()));
+        when(mapper.appointments(anyList())).thenReturn(List.of(fact(10,10,"SUCCESS"),fact(11,10,"SUCCESS")));
+        var result=new AppointmentCoverageService(mapper,gateway).query(List.of(new AppointmentCoverageService.SourceRef("A","ORDER:1","FBA:ONT8"))).get(0);
+        assertEquals("CONFIRMED",result.status()); assertEquals(1,result.appointments().size());
+        assertNull(result.appointments().get(0).timezone()); assertTrue(result.missingFields().contains("APPOINTMENT_TIMEZONE_UNVERIFIED"));
+        assertFalse(result.changeReviewRequired()); verifyNoInteractions(gateway);
+    }
+    @Test void partialPendingAndDuplicateClaimsNeverAppearAsCompleteCoverage() {
+        var mapper=mock(AppointmentCoverageMapper.class); when(mapper.sources(anyList())).thenReturn(List.of(order()));
+        var service=new AppointmentCoverageService(mapper,mock(AppointmentExternalSourceGateway.class));
+        var refs=List.of(new AppointmentCoverageService.SourceRef("A","ORDER:1","FBA:ONT8"));
+        when(mapper.appointments(anyList())).thenReturn(List.of(fact(10,10,"SUCCESS")));
+        assertEquals("PARTIAL",service.query(refs).get(0).status());
+        when(mapper.appointments(anyList())).thenReturn(List.of(fact(10,20,"PENDING")));
+        assertEquals("PENDING",service.query(refs).get(0).status());
+        when(mapper.appointments(anyList())).thenReturn(List.of(fact(10,10,"SUCCESS"),fact(10,10,"SUCCESS")));
+        assertEquals("REVIEW_REQUIRED",service.query(refs).get(0).status());
+    }
+    @Test void externalBookingKeepsItsIdentityBeforeAndAfterRealCargoExists() {
+        var mapper=mock(AppointmentCoverageMapper.class); var gateway=mock(AppointmentExternalSourceGateway.class);
+        var refs=List.of(new AppointmentCoverageService.SourceRef("A","BOOKING:B-1","FBA:ONT8"));
+        var service=new AppointmentCoverageService(mapper,gateway);
+        when(gateway.resolve(anyList())).thenReturn(List.of(new AppointmentExternalSourceGateway.Source("A","B-1","TR-1","CONFIRMED","100","FBA:ONT8",null,20,1L)));
+        assertEquals("SOURCE_NOT_MATERIALIZED",service.query(refs).get(0).status()); verifyNoInteractions(mapper);
+        when(gateway.resolve(anyList())).thenReturn(List.of(new AppointmentExternalSourceGateway.Source("A","B-1","TR-1","BOUND","100","FBA:ONT8",1L,20,2L)));
+        when(mapper.sources(anyList())).thenReturn(List.of(order())); when(mapper.appointments(anyList())).thenReturn(List.of(fact(10,20,"SUCCESS")));
+        var result=service.query(refs).get(0); assertEquals("BOOKING:B-1",result.sourceKey()); assertEquals("CONFIRMED",result.status());
+        assertThrows(IllegalArgumentException.class, () -> service.query(List.of(refs.get(0),new AppointmentCoverageService.SourceRef("A","ORDER:1","FBA:ONT8"))));
+    }
+    @Test void anotherCustomerAndChangedDestinationCannotBorrowAppointmentCoverage() {
+        var mapper=mock(AppointmentCoverageMapper.class); var gateway=mock(AppointmentExternalSourceGateway.class);
+        when(mapper.sources(anyList())).thenReturn(List.of(order())); when(mapper.appointments(anyList())).thenReturn(List.of(fact(10,20,"SUCCESS")));
+        var service=new AppointmentCoverageService(mapper,gateway);
+        assertEquals("SOURCE_NOT_FOUND",service.query(List.of(new AppointmentCoverageService.SourceRef("B","ORDER:1","FBA:ONT8"))).get(0).status());
+        assertEquals("DESTINATION_MISMATCH",service.query(List.of(new AppointmentCoverageService.SourceRef("A","ORDER:1","FBA:LAX9"))).get(0).status());
+    }
+    @Test void changedSourcesAndMissingShipmentReferencesAreExplicitWithoutChangingConfirmedTime() {
+        var mapper=mock(AppointmentCoverageMapper.class);
+        when(mapper.sources(anyList())).thenReturn(List.of(new AppointmentCoverageMapper.Source(1L,"A","FBA","ONT8",20,3,AFTER.plusHours(1),true)));
+        when(mapper.appointments(anyList())).thenReturn(List.of(fact(10,20,"SUCCESS")));
+        var result=new AppointmentCoverageService(mapper,mock(AppointmentExternalSourceGateway.class)).query(List.of(new AppointmentCoverageService.SourceRef("A","ORDER:1","FBA:ONT8"))).get(0);
+        assertTrue(result.changeReviewRequired()); assertTrue(result.missingFields().containsAll(List.of("SOURCE_CHANGED_REVIEW","FBA_SHIPMENT_REFERENCES")));
+        assertEquals(AFTER.plusDays(1),result.appointments().get(0).confirmedAt());
+        verify(mapper,times(1)).sources(anyList()); verify(mapper,times(1)).appointments(anyList()); verifyNoMoreInteractions(mapper);
+    }
+}
@@ -0,0 +1,45 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.MybatisSqlSessionFactoryBuilder;
+import org.apache.ibatis.mapping.Environment;
+import org.apache.ibatis.transaction.jdbc.JdbcTransactionFactory;
+import org.h2.jdbcx.JdbcDataSource;
+import org.junit.jupiter.api.Test;
+import java.nio.charset.StandardCharsets;
+import java.time.LocalDateTime;
+import java.util.UUID;
+import static org.junit.jupiter.api.Assertions.*;
+
+class AppointmentFollowupPersistenceTest {
+    @Test void baselineAndMapperPersistSeparateStagesAndEnforceCommandAndVersionUniqueness() throws Exception {
+        String sql;
+        try (var input=getClass().getResourceAsStream("/db/lastleg.sql")) {
+            assertNotNull(input); var baseline=new String(input.readAllBytes(),StandardCharsets.UTF_8);
+            int start=baseline.indexOf("CREATE TABLE IF NOT EXISTS ll_appointment_followup (");
+            assertTrue(start>=0); sql=baseline.substring(start,baseline.indexOf(';',start)+1);
+        }
+        var ds=new JdbcDataSource(); ds.setURL("jdbc:h2:mem:followup-"+ UUID.randomUUID()+";MODE=MySQL;DB_CLOSE_DELAY=-1");
+        try (var c=ds.getConnection();var s=c.createStatement()) {
+            s.execute("CREATE TABLE ll_order(id BIGINT PRIMARY KEY)"); s.execute("INSERT INTO ll_order VALUES(1)"); s.execute(sql);
+        }
+        var config=new MybatisConfiguration(); config.setEnvironment(new Environment("test",new JdbcTransactionFactory(),ds));
+        config.setMapUnderscoreToCamelCase(true); config.addMapper(AppointmentFollowupMapper.class);
+        try (var session=new MybatisSqlSessionFactoryBuilder().build(config).openSession(true)) {
+            var mapper=session.getMapper(AppointmentFollowupMapper.class);
+            var first=record(11L,"DRAYAGE_CONTACT",1,"key-a"); mapper.insert(first);
+            mapper.insert(record(12L,"FBA_RECEIVING",1,"key-a"));
+            assertEquals(1,mapper.version("ORDER:1","A","DRAYAGE_CONTACT")); assertEquals(1,mapper.version("ORDER:1","A","FBA_RECEIVING"));
+            assertEquals(2,mapper.count("ORDER:1","A")); assertEquals("联系结果",mapper.command("ORDER:1","A","DRAYAGE_CONTACT","key-a").getResult());
+            assertEquals(1,mapper.page("ORDER:1","A",1,0).size());
+            assertThrows(RuntimeException.class, () -> mapper.insert(record(13L,"DRAYAGE_CONTACT",2,"key-a")));
+            assertThrows(RuntimeException.class, () -> mapper.insert(record(14L,"DRAYAGE_CONTACT",1,"key-b")));
+            assertEquals(2,mapper.count("ORDER:1","A"));
+        }
+    }
+    private static AppointmentFollowup record(long id,String stage,int version,String key) {
+        var row=new AppointmentFollowup(); row.setId(id); row.setSourceOrderId(1L); row.setSourceKey("ORDER:1"); row.setCustomerId("A"); row.setStage(stage); row.setVersion(version);
+        row.setResult("联系结果"); row.setOperatorId("operator"); row.setCommandKey(key); row.setRequestHash("a".repeat(64));
+        row.setCreatedAt(LocalDateTime.of(2026,10,9,12,0)); return row;
+    }
+}
@@ -0,0 +1,59 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.server.ResponseStatusException;
+import java.time.LocalDate;
+import java.util.HashMap;
+import java.util.List;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+class AppointmentFollowupServiceTest {
+    @Test void contactsBeforePlanningAreAppendOnlyAndOldCommandsReplayTheirOriginalResult() {
+        var cargo=mock(AppointmentSourceService.class); var mapper=mock(AppointmentFollowupMapper.class);
+        var saved=new HashMap<String,AppointmentFollowup>(); var version=new int[]{0};
+        when(cargo.resolve("ORDER:1","A",null)).thenReturn(new AppointmentSourceService.Source("ORDER:1","A",1L,"IN-A",null,"C1","100","美国仓","FBA:ONT8","ONT8",10,"ORDER:0",true,List.of()));
+        when(mapper.command(eq("ORDER:1"),eq("A"),eq("DRAYAGE_CONTACT"),anyString())).thenAnswer(call -> saved.get(call.getArgument(3)));
+        when(mapper.version("ORDER:1","A","DRAYAGE_CONTACT")).thenAnswer(call -> version[0]);
+        when(mapper.insert(any(AppointmentFollowup.class))).thenAnswer(call -> {
+            AppointmentFollowup row=call.getArgument(0); saved.put(row.getCommandKey(),row); version[0]=row.getVersion(); return 1;
+        });
+        var service=new AppointmentFollowupService(cargo,mapper,new ObjectMapper().findAndRegisterModules());
+        var first=new AppointmentFollowupService.Save("DRAYAGE_CONTACT",0,"first","车队A","已联系，等待回复","明日再联系", LocalDate.of(2026,10,15));
+        var result=service.save("ORDER:1","A",first,"operator","运营甲");
+        service.save("ORDER:1","A",new AppointmentFollowupService.Save("DRAYAGE_CONTACT",1,"second","车队A","尚未给出正式时段",null,null),"operator","运营甲");
+        var replay=service.save("ORDER:1","A",first,"operator","运营甲");
+        assertEquals(result,replay); assertEquals(1,replay.version()); assertEquals(2,saved.size());
+        assertEquals("运营甲",result.operatorName()); assertEquals("已联系，等待回复",result.result());
+        verify(mapper,times(2)).insert(any(AppointmentFollowup.class));
+        verify(cargo,times(2)).resolve("ORDER:1","A",null);
+        var conflict=assertThrows(ResponseStatusException.class, () -> service.save("ORDER:1","A",
+            new AppointmentFollowupService.Save("DRAYAGE_CONTACT",0,"first",null,"不同结果",null,null),"operator","运营甲"));
+        assertEquals(409,conflict.getStatusCode().value());
+        assertThrows(ResponseStatusException.class, () -> service.save("ORDER:1","A",first,"another-operator","运营乙"));
+        assertThrows(ResponseStatusException.class, () -> service.save("ORDER:1","A",
+            new AppointmentFollowupService.Save("DRAYAGE_CONTACT",0,"stale",null,"并发旧版本",null,null),"operator","运营甲"));
+        assertEquals(2,saved.size());
+    }
+
+    @Test void followupDateRequiresAnActionAndInvalidStagesDoNotWrite() {
+        var cargo=mock(AppointmentSourceService.class); var mapper=mock(AppointmentFollowupMapper.class);
+        var service=new AppointmentFollowupService(cargo,mapper,new ObjectMapper());
+        assertThrows(ResponseStatusException.class, () -> service.save("ORDER:1","A",
+            new AppointmentFollowupService.Save("FBA_RECEIVING",0,"key",null,"等待材料",null,LocalDate.of(2026,10,15)),"operator","运营"));
+        assertThrows(ResponseStatusException.class, () -> service.save("ORDER:1","A",
+            new AppointmentFollowupService.Save("CONFIRM_ALL",0,"key",null,"不能混用",null,null),"operator","运营"));
+        verifyNoInteractions(cargo,mapper);
+    }
+
+    @Test void existingHistoryRemainsReadableWhenTheCargoHasLeftTheActivePlanningList() {
+        var cargo=mock(AppointmentSourceService.class); var mapper=mock(AppointmentFollowupMapper.class);
+        when(mapper.count("ORDER:1","A")).thenReturn(21L); when(mapper.page("ORDER:1","A",20,20)).thenReturn(List.of());
+        var service=new AppointmentFollowupService(cargo,mapper,new ObjectMapper());
+        var history=service.history("ORDER:1","A",2,20);
+        assertEquals(21,history.history().total()); assertEquals(2,history.history().pages());
+        verifyNoInteractions(cargo);
+    }
+}
@@ -0,0 +1,56 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baiyue.common.security.AuthenticatedUser;
+import org.junit.jupiter.api.Test;
+import org.springframework.context.annotation.*;
+import org.springframework.security.access.AccessDeniedException;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.web.server.ResponseStatusException;
+import java.util.List;
+import java.util.Set;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+class AppointmentPlanningAuthorizationTest {
+    private static final String LIST="platform:appointment:list", CARGO="platform:overseas-warehouse:last-mile-order:list", WRITE="platform:appointment:followup";
+    @Test void readRequiresBothSourcePermissionsAndCannotWrite() {
+        try (var context=new AnnotationConfigApplicationContext(Config.class)) {
+            var controller=context.getBean(AppointmentPlanningController.class);
+            var user=user(0L,"PLATFORM");
+            for (String permission:List.of(LIST,CARGO)) {
+                login(permission);
+                assertThrows(AccessDeniedException.class,() -> controller.cargo(user,1,20,null,null,null));
+                assertThrows(AccessDeniedException.class,() -> controller.history(user,"ORDER:1","A",1,20));
+            }
+            login(LIST,CARGO);
+            controller.cargo(user,1,20,null,null,null);
+            verify(context.getBean(AppointmentCargoService.class)).page(1,20,null,null,null);
+            assertThrows(AccessDeniedException.class,() -> controller.followup(user,"ORDER:1","A",null));
+            verifyNoInteractions(context.getBean(AppointmentFollowupService.class));
+        } finally { SecurityContextHolder.clearContext(); }
+    }
+    @Test void permissionDoesNotAllowClientIdentityAndOperatorComesFromLogin() {
+        try (var context=new AnnotationConfigApplicationContext(Config.class)) {
+            var controller=context.getBean(AppointmentPlanningController.class);
+            login(LIST,CARGO,WRITE);
+            var request=new AppointmentFollowupService.Save("FBA_RECEIVING",0,"key",null,"已联系",null,null);
+            assertThrows(ResponseStatusException.class,() -> controller.followup(user(1L,"CLIENT"),"BOOKING:B-1","A",request));
+            assertThrows(ResponseStatusException.class,() -> controller.cargo(null,1,20,null,null,null));
+            controller.followup(user(0L,"PLATFORM"),"BOOKING:B-1","A",request);
+            verify(context.getBean(AppointmentFollowupService.class)).save("BOOKING:B-1","A",request,"7","operator");
+        } finally { SecurityContextHolder.clearContext(); }
+    }
+    private static AuthenticatedUser user(Long customer,String app) { return new AuthenticatedUser(7L,customer,0L,8L,"operator",app,"WEB",Set.of()); }
+    private static void login(String... permissions) { SecurityContextHolder.getContext().setAuthentication(new UsernamePasswordAuthenticationToken("operator","unused",java.util.Arrays.stream(permissions).map(SimpleGrantedAuthority::new).toList())); }
+    @Configuration @EnableMethodSecurity
+    static class Config {
+        @Bean AppointmentCargoService cargo() { return mock(AppointmentCargoService.class); }
+        @Bean AppointmentFollowupService followups() { return mock(AppointmentFollowupService.class); }
+        @Bean AppointmentSourceService source() { return mock(AppointmentSourceService.class); }
+        @Bean AppointmentCoverageService coverage() { return mock(AppointmentCoverageService.class); }
+        @Bean AppointmentPlanningController controller(AppointmentCargoService cargo,AppointmentFollowupService followups,AppointmentSourceService source,AppointmentCoverageService coverage) { return new AppointmentPlanningController(cargo,followups,source,coverage); }
+    }
+}
@@ -0,0 +1,86 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import org.junit.jupiter.api.Test;
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.util.List;
+import static org.junit.jupiter.api.Assertions.*;
+
+class AppointmentPlanningPolicyTest {
+    private static Instant at(int hour) { return Instant.parse("2026-10-15T" + String.format("%02d", hour) + ":00:00Z"); }
+    private static AppointmentPlanningPolicy.Cargo cargo(String source, String customer, String origin, String destination,
+                                                        Integer packages, Instant from, Instant to) {
+        return new AppointmentPlanningPolicy.Cargo(source, customer, origin, destination, "US", "US", packages, from, to, true, null);
+    }
+
+    @Test void twoCustomersCanPlanOneDestinationWithoutAPlanNumberDriverOrExternalConfirmation() {
+        var result = AppointmentPlanningPolicy.group(List.of(
+            cargo("ORDER:1", "A", "WH-1", "FBA:ONT8", 10, at(1), at(5)),
+            cargo("BOOKING:B-1", "B", "WH-1", "FBA:ONT8", 8, at(3), at(8))));
+        assertEquals(18, result.packages()); assertEquals(2, result.customerCount());
+        assertEquals(at(3), result.readyFrom()); assertEquals(at(5), result.readyTo());
+        assertFalse(result.readinessIncomplete());
+    }
+
+    @Test void unknownReadinessIsPreservedInsteadOfInventingAnArrivalOffset() {
+        var result = AppointmentPlanningPolicy.group(List.of(cargo("ORDER:1", "A", "WH-1", "FBA:ONT8", 10, null, null)));
+        assertTrue(result.readinessIncomplete()); assertNull(result.readyFrom()); assertNull(result.readyTo());
+    }
+
+    @Test void differentOriginsDestinationsAndDisjointWindowsAreNotSilentlyMerged() {
+        var first = cargo("ORDER:1", "A", "WH-1", "FBA:ONT8", 10, at(1), at(3));
+        assertThrows(IllegalArgumentException.class, () -> AppointmentPlanningPolicy.group(List.of(first,
+            cargo("ORDER:2", "B", "WH-2", "FBA:ONT8", 8, at(1), at(3)))));
+        assertThrows(IllegalArgumentException.class, () -> AppointmentPlanningPolicy.group(List.of(first,
+            cargo("ORDER:2", "B", "WH-1", "FBA:LAX9", 8, at(1), at(3)))));
+        assertThrows(IllegalArgumentException.class, () -> AppointmentPlanningPolicy.group(List.of(first,
+            cargo("ORDER:2", "B", "WH-1", "FBA:ONT8", 8, at(5), at(8)))));
+    }
+
+    @Test void sourceIdentityMustNotBeCountedAgainAfterMaterialization() {
+        var first = cargo("BOOKING:B-1", "A", "WH-1", "FBA:ONT8", 10, null, null);
+        assertThrows(IllegalArgumentException.class, () -> AppointmentPlanningPolicy.group(List.of(first, first)));
+        assertThrows(IllegalArgumentException.class, () -> AppointmentPlanningPolicy.group(List.of(
+            cargo("ORDER:1", "A", "WH-1", "FBA:ONT8", null, null, null))));
+    }
+
+    @Test void nonUsAndBlockedSourcesCannotBeTreatedAsEligibleAmericanCargo() {
+        assertThrows(IllegalArgumentException.class, () -> AppointmentPlanningPolicy.group(List.of(
+            new AppointmentPlanningPolicy.Cargo("ORDER:1", "A", "WH-1", "FBA:YYZ", "US", "CA", 1, null, null, true, null))));
+        var error = assertThrows(IllegalArgumentException.class, () -> AppointmentPlanningPolicy.group(List.of(
+            new AppointmentPlanningPolicy.Cargo("ORDER:1", "A", "WH-1", "FBA:ONT8", "US", "US", 1, null, null, false, "货物已被有效安排占用"))));
+        assertEquals("货物已被有效安排占用", error.getMessage());
+    }
+
+    @Test void changedReadinessIdentifiesImpactWithoutOverwritingTheConfirmedTime() {
+        var before = new AppointmentPlanningPolicy.Forecast("ORDER:1", "1", at(1), at(3));
+        var after = new AppointmentPlanningPolicy.Forecast("ORDER:1", "2", at(4), at(8));
+        var impact = AppointmentPlanningPolicy.compare(before, after, at(6));
+        assertTrue(impact.reviewRequired()); assertEquals("READINESS_AFTER_APPOINTMENT", impact.reason());
+        assertEquals(at(6), impact.confirmedAt()); assertEquals(at(1), impact.previousEta()); assertEquals(at(4), impact.latestEta());
+        assertFalse(AppointmentPlanningPolicy.compare(after, after, at(6)).reviewRequired());
+    }
+
+    @Test void lostForecastNeedsReviewAndUnrelatedSourcesCannotBeCompared() {
+        var before = new AppointmentPlanningPolicy.Forecast("ORDER:1", "1", at(1), at(3));
+        assertEquals("FORECAST_MISSING", AppointmentPlanningPolicy.compare(before,
+            new AppointmentPlanningPolicy.Forecast("ORDER:1", "2", null, null), at(6)).reason());
+        assertThrows(IllegalArgumentException.class, () -> AppointmentPlanningPolicy.compare(before,
+            new AppointmentPlanningPolicy.Forecast("ORDER:2", "2", at(2), at(3)), at(6)));
+    }
+
+    @Test void losAngelesTimesResolveToTheLocationZoneAndKeepAnUnknownEndUnknown() {
+        var result = AppointmentTimePolicy.resolve(LocalDateTime.parse("2026-10-15T09:00:00"), null, "America/Los_Angeles", null, null);
+        assertEquals(Instant.parse("2026-10-15T16:00:00Z"), result.start()); assertNull(result.end());
+        assertThrows(IllegalArgumentException.class, () -> AppointmentTimePolicy.resolve(LocalDateTime.parse("2026-10-15T09:00:00"), null, null, null, null));
+    }
+
+    @Test void daylightSavingGapIsRejectedAndOverlapRequiresAnExplicitValidOffset() {
+        assertThrows(IllegalArgumentException.class, () -> AppointmentTimePolicy.resolve(LocalDateTime.parse("2026-03-08T02:30:00"), null, "America/Los_Angeles", null, null));
+        var overlap = LocalDateTime.parse("2026-11-01T01:30:00");
+        assertThrows(IllegalArgumentException.class, () -> AppointmentTimePolicy.resolve(overlap, null, "America/Los_Angeles", null, null));
+        assertEquals(Instant.parse("2026-11-01T09:30:00Z"), AppointmentTimePolicy.resolve(overlap, null, "America/Los_Angeles", ZoneOffset.ofHours(-8), null).start());
+        assertThrows(IllegalArgumentException.class, () -> AppointmentTimePolicy.resolve(overlap, null, "America/Los_Angeles", ZoneOffset.ofHours(8), null));
+    }
+}
@@ -0,0 +1,40 @@
+package com.baiyue.lastleg.appointmentplanning;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.lastleg.entity.LastlegOrder;
+import com.baiyue.lastleg.mapper.LastlegOrderMapper;
+import com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.server.ResponseStatusException;
+import java.util.List;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+class AppointmentSourceServiceTest {
+    @Test void confirmedExternalBookingCanBeFollowedWithoutCreatingAnOrderAndKeepsItsKeyAfterMaterialization() {
+        var orders=mock(LastlegOrderMapper.class); var gateway=mock(AppointmentExternalSourceGateway.class); var warehouse=mock(AppointmentWarehouseClient.class);
+        when(warehouse.catalog("token")).thenReturn(ApiResponse.success(List.of(
+            new AppointmentWarehouseClient.Warehouse(100L,"US-WH","美国仓","OVERSEAS","US"),
+            new AppointmentWarehouseClient.Warehouse(200L,"ONT8","ONT8","FBA","US"))));
+        var service=new AppointmentSourceService(orders,mock(ContainerShippingGateMapper.class),gateway,warehouse,"token");
+        when(gateway.resolve(anyList())).thenReturn(List.of(new AppointmentExternalSourceGateway.Source("A","B-1","TR-1","CONFIRMED","100","FBA:ONT8",null,null,1L)));
+        var source=service.resolve("BOOKING:B-1","A","FBA:ONT8"); assertTrue(source.canFollowup()); assertNull(source.orderId()); assertNull(source.packages()); verifyNoInteractions(orders);
+        var order=new LastlegOrder(); order.setId(1L); order.setCustomerId("A"); order.setOverseasWarehouseId("100"); order.setPackageCount(12); order.setInboundCode("IN-A"); order.setDestinationType("FBA"); order.setFbaWarehouseCode("ONT8");
+        when(orders.selectById(1L)).thenReturn(order);
+        when(gateway.resolve(anyList())).thenReturn(List.of(new AppointmentExternalSourceGateway.Source("A","B-1","TR-1","RECEIVED","100","FBA:ONT8",1L,10,2L)));
+        var received=service.resolve("BOOKING:B-1","A","FBA:ONT8"); assertEquals("BOOKING:B-1",received.sourceKey()); assertEquals(12,received.packages()); assertEquals("IN-A",received.inboundCode());
+        assertThrows(ResponseStatusException.class, () -> service.resolve("BOOKING:B-1","A","FBA:LAX9"));
+        assertThrows(ResponseStatusException.class, () -> service.resolve("BOOKING:B-1","OTHER","FBA:ONT8"));
+        order.setCurrentStatus("CANCELLED"); assertFalse(service.resolve("BOOKING:B-1","A","FBA:ONT8").canFollowup());
+        order.setFbaWarehouseCode("LAX9"); assertThrows(ResponseStatusException.class, () -> service.resolve("BOOKING:B-1","A","FBA:ONT8"));
+    }
+    @Test void draftBookingCannotBePresentedAsConfirmedCarrierCapacity() {
+        var gateway=mock(AppointmentExternalSourceGateway.class); var warehouse=mock(AppointmentWarehouseClient.class);
+        when(warehouse.catalog("token")).thenReturn(ApiResponse.success(List.of(
+            new AppointmentWarehouseClient.Warehouse(100L,"US-WH","美国仓","OVERSEAS","US"),new AppointmentWarehouseClient.Warehouse(200L,"ONT8","ONT8","FBA","US"))));
+        when(gateway.resolve(anyList())).thenReturn(List.of(new AppointmentExternalSourceGateway.Source("A","B-1","TR-1","DRAFT","100","FBA:ONT8",null,null,0L)));
+        var source=new AppointmentSourceService(mock(LastlegOrderMapper.class),mock(ContainerShippingGateMapper.class),gateway,warehouse,"token").resolve("BOOKING:B-1","A","FBA:ONT8");
+        assertFalse(source.canFollowup()); assertFalse(source.blockReasons().isEmpty());
+    }
+}
@@ -0,0 +1,32 @@
+package com.baiyue.lastleg.dispatch.fleet;
+
+import com.baiyue.lastleg.dispatch.service.DispatchService;
+import com.baiyue.lastleg.fleet.trip.*;
+import org.junit.jupiter.api.Test;
+import java.math.BigDecimal;
+import java.util.List;
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+class FleetDispatchPlanningAdapterTest {
+    private final FleetDispatchPlanningMapper mapper=mock(FleetDispatchPlanningMapper.class);
+    private final DispatchService service=mock(DispatchService.class);
+    private final FleetDispatchGateway gateway=mock(FleetDispatchGateway.class);
+    private final FleetDispatchPlanningAdapter adapter=new FleetDispatchPlanningAdapter(mapper,service,gateway);
+    private FleetBookingIncomingGateway.Evidence receipt(){return new FleetBookingIncomingGateway.Evidence("WT-1","IN-1","92","FBA:ACY2","READY_FOR_DISPATCH","hash",List.of(new FleetBookingIncomingGateway.Pallet("1","P-1",10,BigDecimal.TEN,BigDecimal.ONE)),10);}
+    @Test void refusesAmbiguousSourcesWithoutCreatingAnotherDispatch() {
+        when(mapper.sourceDispatches("9","IN-1")).thenReturn(List.of("DS-1","DS-2"));
+        assertThatThrownBy(()->adapter.resolveIncoming("9",receipt(),"1")).hasMessageContaining("多张排车");
+        verifyNoInteractions(service);
+    }
+    @Test void reusesOnlyAnExactExistingShipment() {
+        when(mapper.sourceDispatches("9","IN-1")).thenReturn(List.of("DS-1"));
+        when(gateway.lockForPlanning("DS-1")).thenReturn(new FleetDispatchGateway.Snapshot(1,"DS-1","9","92",10));
+        when(gateway.sourceCargo("DS-1")).thenReturn(List.of(new FleetDispatchGateway.SourceCargo("IN-1","1","P-1",10,"FBA:ACY2")));
+        assertThat(adapter.resolveIncoming("9",receipt(),"1")).isEqualTo("DS-1");verifyNoInteractions(service);
+        when(gateway.sourceCargo("DS-1")).thenReturn(List.of(new FleetDispatchGateway.SourceCargo("IN-1","1","P-1",9,"FBA:ACY2")));
+        assertThatThrownBy(()->adapter.resolveIncoming("9",receipt(),"1")).hasMessageContaining("全部实收");
+        when(gateway.sourceCargo("DS-1")).thenReturn(List.of(new FleetDispatchGateway.SourceCargo("IN-other","1","P-1",10,"FBA:ACY2")));
+        assertThatThrownBy(()->adapter.resolveIncoming("9",receipt(),"1")).hasMessageContaining("其他来源");
+    }
+}
@@ -0,0 +1,51 @@
+package com.baiyue.lastleg.dispatch.fleet;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean;
+import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
+import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baiyue.lastleg.fleet.business.*;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.mybatis.spring.SqlSessionTemplate;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.datasource.DriverManagerDataSource;
+import java.util.List;
+import java.util.UUID;
+import static org.assertj.core.api.Assertions.*;
+
+class FleetPlanningReadPersistenceTest {
+    @Test void candidatesPaginateOnlyEligibleSameWarehouseUnboundCargoAndSourcesPreserveUnknowns() throws Exception {
+        var ds=new DriverManagerDataSource("jdbc:h2:mem:"+UUID.randomUUID()+";MODE=MySQL;DB_CLOSE_DELAY=-1","sa","");
+        var jdbc=new JdbcTemplate(ds);
+        jdbc.execute("CREATE TABLE ll_dispatch_order(id BIGINT PRIMARY KEY,dispatch_no VARCHAR(64),customer_id VARCHAR(64),overseas_warehouse_id VARCHAR(64),package_count INT,status VARCHAR(32),picked_package_count INT,shipped_package_count INT,updated_at TIMESTAMP,route VARCHAR(500))");
+        jdbc.execute("CREATE TABLE ll_dispatch_item(dispatch_order_id BIGINT,customer_id VARCHAR(64),inbound_code VARCHAR(64))");
+        jdbc.execute("CREATE TABLE ll_fleet_trip_dispatch(dispatch_id BIGINT)");
+        jdbc.execute("CREATE TABLE ll_dispatch_pda_task(dispatch_order_id BIGINT,status VARCHAR(32))");
+        jdbc.execute("CREATE TABLE ll_outbound_order(dispatch_order_id BIGINT,status VARCHAR(32))");
+        jdbc.execute("CREATE TABLE ll_fleet_trip(id BIGINT PRIMARY KEY,warehouse_id BIGINT)");
+        jdbc.execute("CREATE TABLE ll_fleet_external_booking(id BIGINT,trip_id BIGINT,customer_id VARCHAR(64),booking_no VARCHAR(64),trip_no VARCHAR(64),status VARCHAR(32),offer_id BIGINT,destination_key VARCHAR(160),destination_label VARCHAR(100),incoming_no VARCHAR(64),record_version BIGINT,cargo_json VARCHAR(2000),expected_pallet_count INT,estimated_arrival_at TIMESTAMP)");
+        jdbc.execute("CREATE TABLE ll_fleet_pool_order_link(booking_id BIGINT,customer_id VARCHAR(64),lastleg_order_id BIGINT,business_order_no VARCHAR(64),fulfillment_stage VARCHAR(32))");
+        for(int i=1;i<=6;i++)jdbc.update("INSERT INTO ll_dispatch_order(id,dispatch_no,customer_id,overseas_warehouse_id,package_count,status,picked_package_count,shipped_package_count,updated_at) VALUES(?,?,?,'92',10,'PENDING_DEPARTURE',0,0,CURRENT_TIMESTAMP)",i,"DS-"+i,"9");
+        jdbc.update("INSERT INTO ll_fleet_trip_dispatch VALUES(2)");
+        jdbc.update("UPDATE ll_dispatch_order SET overseas_warehouse_id='93' WHERE id=3");
+        jdbc.update("INSERT INTO ll_dispatch_pda_task VALUES(4,'PICKING')");
+        jdbc.update("INSERT INTO ll_dispatch_item VALUES(5,'9','IN-5'),(6,'9','IN-6')");
+        jdbc.update("INSERT INTO ll_fleet_trip VALUES(1,92)");
+        jdbc.update("INSERT INTO ll_fleet_external_booking(id,trip_id,customer_id,booking_no,trip_no,status,offer_id,destination_key,destination_label,incoming_no,record_version,cargo_json) VALUES(5,1,'9','FB-5','TR-OTHER','RECEIVED',1,'FBA:ACY2','ACY2','IN-5',1,'{\"packageCount\":null}'),(6,1,'9','FB-6','TR-1','RECEIVED',1,'FBA:ACY2','ACY2','IN-6',2,'{\"packageCount\":10}')");
+        var configuration=new MybatisConfiguration();configuration.addMapper(FleetDispatchPlanningMapper.class);configuration.addMapper(FleetPoolOrderMapper.class);
+        var interceptor=new MybatisPlusInterceptor();interceptor.addInnerInterceptor(new PaginationInnerInterceptor(com.baomidou.mybatisplus.annotation.DbType.H2));configuration.addInterceptor(interceptor);
+        var factory=new MybatisSqlSessionFactoryBean();factory.setDataSource(ds);factory.setConfiguration(configuration);
+        var session=new SqlSessionTemplate(factory.getObject());var mapper=session.getMapper(FleetDispatchPlanningMapper.class);
+        var page=mapper.candidates(new Page<>(1,1),"TR-1","92",null);
+        assertThat(page.getTotal()).isEqualTo(2);assertThat(page.getRecords()).hasSize(1);
+        assertThat(mapper.candidates(new Page<>(1,100),"TR-1","92","DS-1").getRecords()).extracting(r->r.dispatchNo()).containsExactly("DS-1");
+        var resolver=new FleetPoolSourceResolver(session.getMapper(FleetPoolOrderMapper.class),new ObjectMapper());
+        var sources=resolver.resolve(List.of(new FleetPoolSourceResolver.SourceRef("9","FB-5"),new FleetPoolSourceResolver.SourceRef("9","FB-6"),new FleetPoolSourceResolver.SourceRef("OTHER","FB-6")));
+        assertThat(sources).hasSize(2);
+        assertThat(sources.stream().filter(s->s.bookingNo().equals("FB-5")).findFirst().orElseThrow().packageCount()).isNull();
+        assertThat(sources.stream().filter(s->s.bookingNo().equals("FB-6")).findFirst().orElseThrow().packageCount()).isEqualTo(10);
+        assertThat(sources).allMatch(s->s.lastlegOrderId()==null&&s.expectedPalletCount()==null);
+    }
+}
@@ -0,0 +1,47 @@
+package com.baiyue.lastleg.fleet.trip;
+
+import com.baiyue.lastleg.fleet.domain.TripCapacityPolicy;
+import org.junit.jupiter.api.Test;
+import java.math.BigDecimal;
+import java.time.*;
+import java.util.List;
+import static org.assertj.core.api.Assertions.*;
+
+class FleetInquiryProgressTest {
+    private final Instant cutoff=Instant.parse("2026-10-20T10:00:00Z");
+    private FleetCapacityOfferModels.Offer offer() {
+        return new FleetCapacityOfferModels.Offer("FO-1","TR-1","OPEN",1,1,"1","仓库",cutoff,cutoff,null,null,null,
+            List.of(new FleetCapacityOfferModels.Destination("FBA:ACY2","ACY2",1,new TripCapacityPolicy.Load(4,new BigDecimal("1000"),new BigDecimal("10")))),List.of(),true,true,true,null,null);
+    }
+    private FleetBookingModels.Cargo cargo(Integer spaces) {
+        return new FleetBookingModels.Cargo("FBA:ACY2","货物",1,spaces,new BigDecimal("100"),BigDecimal.ONE,"PALLET",BigDecimal.ZERO,"USD","客户联系人","联系信息",null);
+    }
+    private FleetBookingEntity booking(String status) {
+        var row=new FleetBookingEntity();row.setStatus(status);row.setBusinessType("LOCAL_LOOSEBOARD");row.setEstimatedArrivalAt(LocalDateTime.ofInstant(cutoff.minusSeconds(60),ZoneOffset.UTC));return row;
+    }
+    @Test void unknownQuantityIsMissingAndTruckNeedsPhysicalPalletCount() {
+        var row=booking("DRAFT");row.setBusinessType("US_TRUCK");
+        assertThat(FleetInquiryProgress.missing(row,cargo(null),offer())).containsExactly("占用标准托位","预计实托数");
+        row.setExpectedPalletCount(1);
+        assertThat(FleetInquiryProgress.missing(row,cargo(1),offer())).isEmpty();
+    }
+    @Test void capacityIsCheckedAgainstThisDestinationAndThisShipment() {
+        assertThat(FleetInquiryProgress.capacityBlock(cargo(5),offer())).contains("超过");
+        assertThat(FleetInquiryProgress.capacityBlock(cargo(4),offer())).isNull();
+    }
+    @Test void expiryDoesNotTellSalesToEditAnUnsavableDraft() {
+        var p=FleetInquiryProgress.project(booking("DRAFT"),List.of("预计重量"),"已截止",false,false,null,null);
+        assertThat(p.primaryAction()).isEqualTo("VIEW");assertThat(p.reservation()).isEqualTo("尚未保位");
+    }
+    @Test void receivingIsNotDispatchWorkUntilActualMeasurementCompletes() {
+        var row=booking("CONFIRMED");row.setIncomingNo("WT-1");
+        var waiting=FleetInquiryProgress.project(row,List.of(),null,false,false,"WAIT_PDA_RECEIVING",null);
+        assertThat(waiting.owner()).isEqualTo("仓库");assertThat(waiting.primaryAction()).isEqualTo("VIEW");
+        var received=FleetInquiryProgress.project(row,List.of(),null,false,false,"WAIT_CUSTOMER_CONFIRMATION",null);
+        assertThat(received.owner()).isEqualTo("调度");assertThat(received.primaryAction()).isEqualTo("RECEIPT");
+    }
+    @Test void bindingIsNotDepartureAndOnlyActualFulfillmentAdvancesTracking() {
+        assertThat(FleetInquiryProgress.project(booking("BOUND"),List.of(),null,false,false,null,"PENDING_DISPATCH").label()).isEqualTo("已排入本车");
+        assertThat(FleetInquiryProgress.project(booking("BOUND"),List.of(),null,false,false,null,"IN_TRANSIT").label()).isEqualTo("已发车");
+    }
+}
@@ -13,11 +13,15 @@ import static org.assertj.core.api.Assertions.*;
 class FleetTripApiContractTest {
    @Test void allTripOperationsHaveOpenApiAndRealPermissions() throws Exception {
        Map<String, Object> document = new Yaml().load(Files.readString(Path.of("src/main/resources/openapi/fleet-trips-v1.yaml")));
-        Map<?, ?> paths = (Map<?, ?>) document.get("paths");
+        Map<String, Object> preparation = new Yaml().load(Files.readString(Path.of("src/main/resources/openapi/fleet-preparation-v1.yaml")));
+        Map<String, Object> pool = new Yaml().load(Files.readString(Path.of("src/main/resources/openapi/fleet-capacity-offers-v1.yaml")));
+        var paths = new java.util.HashMap<Object,Object>();
+        for(var spec:java.util.List.of(document,preparation,pool))paths.putAll((Map<?,?>)spec.get("paths"));
        String module = Files.readString(Path.of("../iam/src/main/resources/db/lastleg-permissions.sql"));
+        module += Files.readString(Path.of("../iam/src/main/resources/db/fleet-capacity-offer-permissions.sql"));
        String deployed = Files.readString(Path.of("../deploy/sql/头程数据库统一增量-MySQL8.sql"));
        int count = 0;
-        for (var controller : java.util.List.of(PlatformFleetTripController.class, PlatformFleetBookingController.class)) {
+        for (var controller : java.util.List.of(PlatformFleetTripController.class, PlatformFleetBookingController.class, PlatformFleetCapacityOfferController.class)) {
        String base = controller.getAnnotation(RequestMapping.class).value()[0];
        for (var method : controller.getDeclaredMethods()) {
            String verb = null; String[] suffix = null;
@@ -42,8 +46,10 @@ class FleetTripApiContractTest {
            count++;
        }
        }
-        assertThat(count).isEqualTo(29);
+        assertThat(count).isEqualTo(52);
        verifyRefs(document, document);
+        verifyRefs(preparation, preparation);
+        verifyRefs(pool, pool);
    }

    @Test void schemasMatchAndUseUniqueResourceClaimsAndVersionedHistory() throws Exception {
@@ -68,7 +74,7 @@ class FleetTripApiContractTest {
                if(!reference.startsWith("#/")) {
                    String[] parts=reference.split("#",2);
                    assertThat(parts).hasSize(2);
-                    assertThat(parts[0]).isEqualTo("fleet-quote-candidates-v1.yaml");
+                    assertThat(Path.of(parts[0]).getFileName().toString()).isIn("fleet-quote-candidates-v1.yaml","fleet-trips-v1.yaml","fleet-capacity-offers-v1.yaml");
                    try { value=new Yaml().load(Files.readString(Path.of("src/main/resources/openapi",parts[0]))); }
                    catch(java.io.IOException error) { throw new java.io.UncheckedIOException(error); }
                    pointer="#"+parts[1];
@@ -36,6 +36,7 @@ class FleetTripAuthorizationTest {
            assertThatThrownBy(() -> controller.cancel(null, "TR-TEST", null)).isInstanceOf(AccessDeniedException.class);
            assertThatThrownBy(() -> controller.plan(null, "TR-TEST", null)).isInstanceOf(AccessDeniedException.class);
            assertThatThrownBy(() -> controller.bind(null, "TR-TEST", null)).isInstanceOf(AccessDeniedException.class);
+            assertThatThrownBy(() -> controller.prepare(null,null)).isInstanceOf(AccessDeniedException.class);
            assertThatThrownBy(() -> controller.unbind(null, "TR-TEST", null)).isInstanceOf(AccessDeniedException.class);
            assertThatThrownBy(() -> controller.confirmLoading(null, "TR-TEST", null)).isInstanceOf(AccessDeniedException.class);
            assertThatThrownBy(() -> controller.reviewDispatch(null, "TR-TEST", "DP-1", null)).isInstanceOf(AccessDeniedException.class);
@@ -55,8 +56,25 @@ class FleetTripAuthorizationTest {
            verifyNoMoreInteractions(service);
        } finally { SecurityContextHolder.clearContext(); }
    }
+    @Test void poolReadDoesNotGrantIncomingReceiptOrDispatchCommands() {
+        try(var context=new AnnotationConfigApplicationContext(Config.class)) {
+            SecurityContextHolder.getContext().setAuthentication(new UsernamePasswordAuthenticationToken("sales","unused",List.of(new SimpleGrantedAuthority(FleetCapacityOfferService.LIST))));
+            var pool=context.getBean(PlatformFleetCapacityOfferController.class);
+            pool.fulfillment("FB-1");verify(context.getBean(FleetCapacityOfferService.class)).fulfillment("FB-1");
+            assertThatThrownBy(()->pool.incoming("FB-1",null)).isInstanceOf(AccessDeniedException.class);
+            assertThatThrownBy(()->pool.receipt("FB-1",null)).isInstanceOf(AccessDeniedException.class);
+            assertThatThrownBy(()->pool.arrange("FB-1",null)).isInstanceOf(AccessDeniedException.class);
+            assertThatThrownBy(()->pool.saveAndConfirm("FB-1",null)).isInstanceOf(AccessDeniedException.class);
+        } finally {SecurityContextHolder.clearContext();}
+    }
    @Configuration @EnableMethodSecurity
    static class Config {
+        @Bean FleetCapacityOfferCommandMapper commands() { return mock(FleetCapacityOfferCommandMapper.class); }
+        @Bean FleetDispatchPlanningGateway planning() { return mock(FleetDispatchPlanningGateway.class); }
+        @Bean FleetTripPreparationService preparation() { return mock(FleetTripPreparationService.class); }
+        @Bean com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService appointmentCoverage() { return mock(com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService.class); }
+        @Bean FleetCapacityOfferService capacityOffers() { return mock(FleetCapacityOfferService.class); }
+        @Bean PlatformFleetCapacityOfferController poolController(FleetCapacityOfferService service) { return new PlatformFleetCapacityOfferController(service); }
        @Bean com.baiyue.lastleg.fleet.business.FleetPoolOrderBridge poolOrders() { return mock(com.baiyue.lastleg.fleet.business.FleetPoolOrderBridge.class); }
        @Bean FleetBookingService bookingService() { return mock(FleetBookingService.class); }
        @Bean com.baiyue.lastleg.fleet.customer.FleetCustomerDirectory customers() { return mock(com.baiyue.lastleg.fleet.customer.FleetCustomerDirectory.class); }
@@ -56,6 +56,8 @@ import static org.mockito.Mockito.*;
 class FleetTripPersistenceTest {
    private JdbcTemplate jdbc;
    private FleetTripService service;
+    private FleetTripPreparationService preparation;
+    private FleetDispatchPlanningGateway planning;
    private DriverService drivers;
    private VehicleRepository vehicles;
    private VehicleApplicationService vehicleService;
@@ -141,6 +143,9 @@ class FleetTripPersistenceTest {
            transactional(workflow, DispatchPdaWorkflowService.class), session.getMapper(DeliveryOperationMapper.class)), DispatchFleetAdapter.class);
        service = transactional(new FleetTripService(session.getMapper(FleetTripMapper.class), resources, session.getMapper(FleetTripHistoryMapper.class), vehicles, drivers, directory, json,
            bindingMapper, dispatchGateway, reservations), FleetTripService.class);
+        preparation = transactional(new FleetTripPreparationService(service,session.getMapper(FleetTripMapper.class),session.getMapper(FleetCapacityOfferCommandMapper.class),json),FleetTripPreparationService.class);
+        planning=mock(FleetDispatchPlanningGateway.class);
+        ReflectionTestUtils.setField(service,"planning",planning);
        execution = transactional(new FleetTripExecutionService(session.getMapper(FleetTripMapper.class), bindingMapper, resources, dispatchGateway, service, drivers, vehicles, json, reservations), FleetTripExecutionService.class);
        var customerDirectory = mock(com.baiyue.lastleg.fleet.customer.FleetCustomerDirectory.class);
        when(customerDirectory.required(anyLong())).thenAnswer(call -> new com.baiyue.lastleg.fleet.customer.FleetCustomerDirectory.Customer(
@@ -150,11 +155,47 @@ class FleetTripPersistenceTest {
        quoteCandidates=mock(com.baiyue.lastleg.fleet.quote.FleetQuoteCandidateService.class);
        bookingService = transactional(new FleetBookingService(session.getMapper(FleetTripMapper.class), bookingMapper, reservations, service, execution, customerDirectory, json, incoming, quoteContext, quoteCandidates), FleetBookingService.class);
        ReflectionTestUtils.setField(bookingService,"poolOrders",poolOrders);
+        ReflectionTestUtils.setField(bookingService,"planning",planning);
+        ReflectionTestUtils.setField(bookingService,"commands",session.getMapper(FleetCapacityOfferCommandMapper.class));
        capacityOffers=transactional(new FleetCapacityOfferService(session.getMapper(FleetCapacityOfferMapper.class),session.getMapper(FleetCapacityOfferCommandMapper.class),
            session.getMapper(FleetTripMapper.class),bookingMapper,bookingService,reservations,execution,customerDirectory,poolOrders,json),FleetCapacityOfferService.class);
+        ReflectionTestUtils.setField(capacityOffers,"appointmentCoverage",mock(com.baiyue.lastleg.appointmentplanning.AppointmentCoverageService.class));
        completion = transactional(new FleetTripCompletionService(session.getMapper(FleetTripMapper.class), bindingMapper, resources, dispatchGateway, service, vehicles, vehicleService, json), FleetTripCompletionService.class);
    }

+    @Test void preparationRollsBackNewTripAndResourcesIfAnyBindingFailsThenReplaysSuccess() {
+        SecurityContextHolder.getContext().setAuthentication(new UsernamePasswordAuthenticationToken("1","unused",List.of("platform:fleet:trip:create","platform:fleet:trip:assign","platform:fleet:trip:edit").stream().map(SimpleGrantedAuthority::new).toList()));
+        long vehicle=vehicle(true), driver=driver(true);dispatch(21,"A","92");dispatch(22,"B","93");
+        var request=new FleetTripPreparationService.Prepare(null,null,createRequest("prepare-atomic"),vehicle,driver,List.of("DP-21","DP-22"),"prepare-atomic");
+        assertThatThrownBy(()->preparation.prepare("1",request)).hasMessageContaining("同一起运仓");
+        assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM ll_fleet_trip",Integer.class)).isZero();
+        assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM ll_fleet_trip_dispatch",Integer.class)).isZero();
+        assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM ll_fleet_resource_assignment",Integer.class)).isZero();
+        jdbc.update("UPDATE ll_dispatch_order SET overseas_warehouse_id='92' WHERE id=22");
+        jdbc.update("UPDATE ll_dispatch_pda_task SET warehouse_id='92' WHERE dispatch_order_id=22");
+        var saved=preparation.prepare("1",request);
+        assertThat(saved.dispatches()).hasSize(2);
+        assertThat(preparation.prepare("1",request)).isEqualTo(saved);
+        assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM ll_fleet_trip",Integer.class)).isEqualTo(1);
+        assertThatThrownBy(()->preparation.prepare("1",new FleetTripPreparationService.Prepare(null,null,request.plan(),vehicle,driver,List.of("DP-21"),request.idempotencyKey()))).hasMessageContaining("不能更换内容");
+    }
+
+    @Test void sameWindowSaveAndConfirmIsAtomicAndReplaysOriginalResult() {
+        var offer=publishedOffer();var draft=capacityOffers.createInquiry(offer.offerNo(),poolDraft(offer,2,"prepare-register"));
+        var input=poolDraft(draft.offer(),2,"same-window-confirm");
+        var update=new FleetCapacityOfferModels.InquiryWrite(input.tripRecordVersion(),input.offerRecordVersion(),draft.inquiry().recordVersion(),input.customerId(),input.businessType(),input.deliveryMode(),input.estimatedArrivalAt(),input.expectedPalletCount(),input.cargo(),input.quoteRef(),input.idempotencyKey());
+        doThrow(new IllegalStateException("bridge failed")).when(poolOrders).confirm(any(),anyString());
+        assertThatThrownBy(()->capacityOffers.saveAndConfirm(draft.inquiry().bookingNo(),update)).hasMessageContaining("bridge failed");
+        assertThat(capacityOffers.inquiry(draft.inquiry().bookingNo()).recordVersion()).isEqualTo(draft.inquiry().recordVersion());
+        assertThat(capacityOffers.inquiry(draft.inquiry().bookingNo()).status()).isEqualTo("DRAFT");
+        reset(poolOrders);
+        var confirmed=capacityOffers.saveAndConfirm(draft.inquiry().bookingNo(),update);
+        assertThat(confirmed.inquiry().status()).isEqualTo("CONFIRMED");
+        assertThat(confirmed.inquiry().progress().reservation()).isEqualTo("已保留货位");
+        assertThat(capacityOffers.saveAndConfirm(draft.inquiry().bookingNo(),update).replayed()).isTrue();
+        verify(poolOrders,times(1)).confirm(any(),anyString());
+    }
+
    @Test void poolSalesAreIsolatedByUserIdAndCannotConfirmOrReadAllInquiries() {
        var offer=publishedOffer();poolLogin(101,false);
        var first=capacityOffers.createInquiry(offer.offerNo(),poolDraft(offer,2,"owner-first"));
@@ -443,7 +484,8 @@ class FleetTripPersistenceTest {
        } finally { executor.shutdownNow(); }
    }

-    @Test void externalReceiptChangesReservationOnlyAfterExplicitActualQuantityAndPriceConfirmation() {
+    @org.junit.jupiter.params.ParameterizedTest @org.junit.jupiter.params.provider.ValueSource(booleans={false,true})
+    void externalReceiptChangesReservationOnlyAfterExplicitActualQuantityAndPriceConfirmation(boolean automatic) {
        var source=enableQuote();
        String number=readyTrip();var basis=execution.capacityPlan(number);
        execution.confirmCapacityPlan(number,"1",new FleetExecutionModels.Confirm(basis.recordVersion(),basis.manifestHash(),List.of(measurement()),"计划"));
@@ -451,7 +493,7 @@ class FleetTripPersistenceTest {
        var confirmed=bookingService.confirm(number,draft.booking().bookingNo(),"1",new FleetBookingModels.Command(draft.tripRecordVersion(),0L,"receipt-reserve",null));
        var awaiting=new FleetBookingIncomingGateway.Evidence("WT-EXT","WT-EXT","92","FBA:ONT8","WAIT_PDA_RECEIVING","empty",List.of(),0);
        when(incoming.create(eq("1"),any())).thenReturn(awaiting);
-        var request=new FleetBookingModels.StartIncoming(confirmed.tripRecordVersion(),confirmed.booking().recordVersion(),null,null,null,null,null,null,"incoming-start");
+        var request=new FleetBookingModels.StartIncoming(confirmed.tripRecordVersion(),confirmed.booking().recordVersion(),departure.minusSeconds(120),null,null,null,null,null,"incoming-start");
        var started=bookingService.startIncoming(number,draft.booking().bookingNo(),"1",request);
        assertThat(bookingService.startIncoming(number,draft.booking().bookingNo(),"1",request).replayed()).isTrue();
        verify(incoming,times(1)).create(eq("1"),any());
@@ -473,11 +515,20 @@ class FleetTripPersistenceTest {
        assertThat(execution.capacityPlan(number).availableSegments().get(0).remaining().palletSpaces()).isEqualTo(28);
        dispatch(13,"9","92");
        jdbc.update("INSERT INTO ll_dispatch_item(id,dispatch_order_id,customer_id,warehouse_pallet_id,pallet_no,package_count,source_stage,destination_warehouse_code,overseas_warehouse_id,inbound_code) VALUES(3013,13,'9',902,'PALLET-902',22,'RECEIVED','ONT8','92','WT-EXT')");
-        var linked=bookingService.bindDispatch(number,draft.booking().bookingNo(),"1",new FleetBookingModels.BindDispatch(accepted.tripRecordVersion(),accepted.booking().recordVersion(),"DP-13","link-external"));
+        when(incoming.inspect("9","WT-EXT",true)).thenReturn(new FleetBookingIncomingGateway.Evidence(actual.incomingNo(),actual.inboundCode(),actual.warehouseId(),actual.destinationKey(),"READY_FOR_DISPATCH",actual.receiptHash(),actual.pallets(),actual.receivedPackages()));
+        when(planning.resolveIncoming(eq("9"),any(),eq("1"))).thenReturn("DP-13");
+        var arrange=new FleetBookingModels.Command(accepted.tripRecordVersion(),accepted.booking().recordVersion(),"auto-link-external",null);
+        var linked=automatic?bookingService.arrangeDispatch(number,draft.booking().bookingNo(),"1",arrange):bookingService.bindDispatch(number,draft.booking().bookingNo(),"1",new FleetBookingModels.BindDispatch(accepted.tripRecordVersion(),accepted.booking().recordVersion(),"DP-13","link-external"));
+        if(automatic){assertThat(bookingService.arrangeDispatch(number,draft.booking().bookingNo(),"1",arrange).replayed()).isTrue();verify(planning,times(1)).resolveIncoming(eq("9"),any(),eq("1"));}
        assertThat(linked.booking().status()).isEqualTo("BOUND");assertThat(linked.booking().dispatchNo()).isEqualTo("DP-13");
        assertThat(execution.capacityPlan(number).planValid()).isFalse();
        assertThat(service.detail(number).dispatches()).hasSize(3);
-        service.unbindDispatch(number,"1",new FleetTripModels.BindingCommand(linked.tripRecordVersion(),"DP-13","撤销未开工关联"));
+        var recheck=execution.capacityPlan(number);
+        var planned=execution.confirmCapacityPlan(number,"1",new FleetExecutionModels.Confirm(recheck.recordVersion(),recheck.manifestHash(),List.of(measurement(),new FleetExecutionModels.Measurement("902",1,new BigDecimal("150"),new BigDecimal("1.5"),1)),"关联实收后核对"));
+        assertThat(planned.capacityPlan().segments().get(0).occupied().palletSpaces()).isEqualTo(2);
+        assertThat(planned.availableSegments().get(0).remaining().palletSpaces()).isEqualTo(28);
+        if(automatic){var replay=bookingService.arrangeDispatch(number,draft.booking().bookingNo(),"1",arrange);assertThat(replay.tripRecordVersion()).isEqualTo(linked.tripRecordVersion());assertThat(replay.booking()).isEqualTo(linked.booking());}
+        service.unbindDispatch(number,"1",new FleetTripModels.BindingCommand(planned.recordVersion(),"DP-13","撤销未开工关联"));
        assertThat(bookingService.list(number).records().get(0).status()).isEqualTo("RECEIVED");
        assertThat(bookingService.list(number).records().get(0).dispatchNo()).isNull();
    }