提交

lastleg-service/AGENTS.md

@@ -39,7 +39,7 @@
 
 - 四期在本服务内只进入尾程订单、入仓计划/PDA 入仓、换标、产品与箱唛快照、库存、海外采购和本土卡车；本土散板新增实现也归本服务的独立稳定子域。
 - `dispatch/`、`delivery/`、出库单、PDA 出库拣货、派送和其他库存离仓能力虽然已存在于服务代码或表结构中，但不属于当前四期开发与验收范围，不得因代码已存在而自动纳入。
-- 历史 `dispatch/` 写操作、PDA 出库和 `delivery/` Controller 默认不注册；只有后续阶段明确启用 `lastleg.future-outbound-api.enabled=true` 才可恢复。平台排车列表与详情是独立只读入口，仅由海外配置 `lastleg.dispatch-query-api.enabled=true` 启用，不得借此开放预排、编辑、取消、PDA 出库或派送。四期平台库存 Controller 不映射 allocate、unallocate、pick、ship。
+- 历史排车编辑/取消/出库、PDA 出库和 `delivery/` Controller 默认不注册；只有后续阶段明确启用 `lastleg.future-outbound-api.enabled=true` 才可恢复。平台排车列表与详情由 `lastleg.dispatch-query-api.enabled=true` 独立启用；入库单智能排车候选和预排创建由 `lastleg.smart-dispatch-api.enabled=true` 独立启用。四个排车平台入口均不接收 `customerId`，服务端从尾程库排车/入仓数据解析唯一客户范围，检测到多客户时拒绝请求；预排只能创建待出库排车并锁定托盘，不得借此开放编辑、取消、depart、PDA 出库或派送。四期平台库存 Controller 不映射 allocate、unallocate、pick、ship。
 - 海外仓库、库位、实物托盘和资源锁归 `warehouse-overseas-service/`；浏览器 API 统一经 `gateway-overseas/`，本服务不得复制仓储资源主数据或另建公网认证入口。
 
 ## 数据库表索引与注释约束

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchController.java

@@ -4,7 +4,6 @@ import com.baiyue.common.core.api.ApiResponse;
 import com.baiyue.common.security.AuthenticatedUser;
 import com.baiyue.lastleg.dispatch.dto.DispatchRequests;
 import com.baiyue.lastleg.dispatch.dto.DispatchResponse;
-import com.baiyue.lastleg.dispatch.model.DispatchPalletCandidate;
 import com.baiyue.lastleg.dispatch.pda.dto.DispatchPdaRequests;
 import com.baiyue.lastleg.dispatch.pda.dto.DispatchPdaResponses;
 import com.baiyue.lastleg.dispatch.pda.service.DispatchPdaWorkflowService;
@@ -18,7 +17,6 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.http.HttpStatus;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.web.bind.annotation.DeleteMapping;
-import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.PutMapping;
@@ -28,8 +26,6 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.server.ResponseStatusException;
 
-import java.util.List;
-
 @RestController
 @ConditionalOnProperty(name = "lastleg.future-outbound-api.enabled", havingValue = "true")
 @RequestMapping("/api/platform/v1/last-leg/dispatches")
@@ -38,28 +34,6 @@ public class DispatchController {
     @Resource private DispatchService service;
     @Resource private DispatchPdaWorkflowService pdaWorkflow;
 
-    @GetMapping("/candidates")
-    @Operation(summary = "List unlocked planned or received pallets for intelligent pre-dispatch")
-    public ApiResponse<List<DispatchPalletCandidate>> candidates(
-        @AuthenticationPrincipal AuthenticatedUser user,
-        @RequestParam(required = false) String customerId,
-        @RequestParam(required = false) String orderNo,
-        @RequestParam(required = false) String fbaWarehouseCode,
-        @RequestParam(required = false) String sourceStage) {
-        return ApiResponse.success(service.candidates(scope(user, customerId), orderNo, fbaWarehouseCode, sourceStage));
-    }
-
-    @PostMapping("/pre-arrange")
-    @Operation(summary = "Create a pending-departure dispatch and lock all selected pallets")
-    public ApiResponse<DispatchResponse> preArrange(
-        @AuthenticationPrincipal AuthenticatedUser user,
-        @RequestParam(required = false) String customerId,
-        @Valid @RequestBody DispatchRequests.PreArrange request) {
-        String scopedTenant = scope(user, customerId);
-        String operatorId = user.userId() == null ? user.username() : String.valueOf(user.userId());
-        return ApiResponse.success(service.preArrange(scopedTenant, operatorId, request));
-    }
-
     @PutMapping("/{dispatchNo}")
     @Operation(summary = "Edit vehicle, driver, appointment, route and departure data")
     public ApiResponse<DispatchResponse> update(

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchQueryController.java

@@ -6,12 +6,14 @@ import com.baiyue.common.security.AuthenticatedUser;
 import com.baiyue.lastleg.dispatch.dto.DispatchRequests;
 import com.baiyue.lastleg.dispatch.dto.DispatchResponse;
 import com.baiyue.lastleg.dispatch.service.DispatchService;
+import com.baiyue.lastleg.security.OverseasPermissions;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import jakarta.validation.Valid;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 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.PathVariable;
@@ -27,21 +29,23 @@ public class DispatchQueryController {
     @Resource private DispatchService service;
 
     @GetMapping
+    @PreAuthorize("hasAuthority('" + OverseasPermissions.INBOUND_ORDER_LIST + "')")
     @Operation(summary = "Page dispatch orders")
     public ApiResponse<PageResult<DispatchResponse>> page(
         @AuthenticationPrincipal AuthenticatedUser user,
         @Valid DispatchRequests.Query query) {
         requirePlatform(user);
-        return ApiResponse.success(service.page(null, query));
+        return ApiResponse.success(service.page(service.resolveSingleCustomerScope(), query));
     }
 
     @GetMapping("/{dispatchNo}")
+    @PreAuthorize("hasAuthority('" + OverseasPermissions.INBOUND_ORDER_LIST + "')")
     @Operation(summary = "Get dispatch details and all pallet destinations")
     public ApiResponse<DispatchResponse> detail(
         @AuthenticationPrincipal AuthenticatedUser user,
         @PathVariable String dispatchNo) {
         requirePlatform(user);
-        return ApiResponse.success(service.detail(null, dispatchNo));
+        return ApiResponse.success(service.detail(service.resolveSingleCustomerScope(), dispatchNo));
     }
 
     private void requirePlatform(AuthenticatedUser user) {

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/SmartDispatchController.java

@@ -0,0 +1,70 @@
+package com.baiyue.lastleg.dispatch.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.dispatch.dto.DispatchRequests;
+import com.baiyue.lastleg.dispatch.dto.DispatchResponse;
+import com.baiyue.lastleg.dispatch.model.DispatchPalletCandidate;
+import com.baiyue.lastleg.dispatch.service.DispatchService;
+import com.baiyue.lastleg.security.OverseasPermissions;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+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.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+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.server.ResponseStatusException;
+
+import java.util.List;
+
+@RestController
+@ConditionalOnProperty(name = "lastleg.smart-dispatch-api.enabled", havingValue = "true")
+@RequestMapping("/api/platform/v1/last-leg/dispatches")
+@Tag(name = "Tail-leg smart dispatch")
+public class SmartDispatchController {
+    @Resource private DispatchService service;
+
+    @GetMapping("/candidates")
+    @PreAuthorize("hasAuthority('" + OverseasPermissions.INBOUND_ORDER_LIST + "')")
+    @Operation(summary = "List unlocked planned or received pallets for intelligent pre-dispatch",
+        description = "Required authority: " + OverseasPermissions.INBOUND_ORDER_LIST)
+    public ApiResponse<List<DispatchPalletCandidate>> candidates(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(required = false) String orderNo,
+        @RequestParam(required = false) String fbaWarehouseCode,
+        @RequestParam(required = false) String sourceStage) {
+        requirePlatform(user);
+        return ApiResponse.success(service.candidates(service.resolveSingleCustomerScope(), orderNo,
+            fbaWarehouseCode, sourceStage));
+    }
+
+    @PostMapping("/pre-arrange")
+    @PreAuthorize("hasAuthority('" + OverseasPermissions.INBOUND_ORDER_EDIT + "')")
+    @Operation(summary = "Create a pending-departure dispatch and lock all selected pallets",
+        description = "Required authority: " + OverseasPermissions.INBOUND_ORDER_EDIT)
+    public ApiResponse<DispatchResponse> preArrange(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @Valid @RequestBody DispatchRequests.PreArrange request) {
+        requirePlatform(user);
+        String scopedCustomer = service.resolveSingleCustomerScope();
+        String operatorId = user.userId() == null ? user.username() : String.valueOf(user.userId());
+        return ApiResponse.success(service.preArrange(scopedCustomer, operatorId, request));
+    }
+
+    private void requirePlatform(AuthenticatedUser user) {
+        if (user == null || user.tenantId() == null) {
+            throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
+        }
+        if (!"PLATFORM".equals(user.appCode()) || user.tenantId() != 0L) {
+            throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Platform application required");
+        }
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchCandidateMapper.java

@@ -9,6 +9,12 @@ import java.util.List;
 
 @Mapper
 public interface DispatchCandidateMapper {
+    @Select("SELECT customer_id FROM (" +
+        "SELECT customer_id FROM ll_inbound_plan UNION SELECT customer_id FROM ll_dispatch_order" +
+        ") dispatch_customers WHERE customer_id IS NOT NULL AND customer_id != '' " +
+        "ORDER BY customer_id LIMIT 2")
+    List<String> findCustomerScopes();
+
     @Select("<script>" +
         "SELECT p.plan_id AS planId,p.id AS planPalletId,p.warehouse_pallet_id AS warehousePalletId," +
         "MIN(l.order_id) AS orderId,MIN(o.overseas_warehouse_id) AS overseasWarehouseId,MIN(o.overseas_warehouse_name) AS overseasWarehouseName,MIN(o.order_no) AS orderNo," +

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchOrderMapper.java

@@ -11,9 +11,6 @@ public interface DispatchOrderMapper extends BaseMapper<DispatchOrder> {
     @Select("SELECT * FROM ll_dispatch_order WHERE customer_id=#{customerId} AND dispatch_no=#{dispatchNo} LIMIT 1")
     DispatchOrder findByDispatchNo(@Param("customerId") String customerId, @Param("dispatchNo") String dispatchNo);
 
-    @Select("SELECT * FROM ll_dispatch_order WHERE dispatch_no=#{dispatchNo} LIMIT 1")
-    DispatchOrder findAnyByDispatchNo(@Param("dispatchNo") String dispatchNo);
-
     @Select("SELECT * FROM ll_dispatch_order WHERE customer_id=#{customerId} AND id=#{id} LIMIT 1 FOR UPDATE")
     DispatchOrder lockById(@Param("customerId") String customerId, @Param("id") Long id);
 }

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

@@ -41,16 +41,30 @@ public class DispatchService {
     @Resource private DispatchPalletLockMapper locks;
     @Resource private DispatchCandidateMapper candidates;
 
+    public String resolveSingleCustomerScope() {
+        List<String> customerIds = candidates.findCustomerScopes();
+        if (customerIds.size() > 1) {
+            throw new ResponseStatusException(HttpStatus.CONFLICT,
+                "Dispatch APIs require exactly one customer in the current deployment");
+        }
+        return customerIds.isEmpty() ? null : customerIds.get(0);
+    }
+
     public List<DispatchPalletCandidate> candidates(String customerId, String orderNo,
                                                      String fbaWarehouseCode, String sourceStage) {
         if (StringUtils.hasText(sourceStage) && !Set.of("PLAN", "RECEIVED").contains(sourceStage)) {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "sourceStage must be PLAN or RECEIVED");
         }
+        if (!StringUtils.hasText(customerId)) return List.of();
         return candidates.available(customerId, trimToNull(orderNo), trimToNull(fbaWarehouseCode), trimToNull(sourceStage));
     }
 
     @Transactional
     public DispatchResponse preArrange(String customerId, String operatorId, DispatchRequests.PreArrange request) {
+        if (!StringUtils.hasText(customerId)) {
+            throw new ResponseStatusException(HttpStatus.CONFLICT,
+                "No customer business data is available for dispatch");
+        }
         List<Long> palletIds = request.planPalletIds().stream().filter(Objects::nonNull).distinct().sorted().toList();
         if (palletIds.isEmpty() || palletIds.size() != request.planPalletIds().size()) {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Plan pallet IDs must be unique and non-empty");
@@ -149,8 +163,11 @@ public class DispatchService {
     }
 
     public PageResult<DispatchResponse> page(String customerId, DispatchRequests.Query query) {
+        if (!StringUtils.hasText(customerId)) {
+            return new PageResult<>(List.of(), query.page(), query.size(), 0, 0);
+        }
         Page<DispatchOrder> page = orders.selectPage(new Page<>(query.page(), query.size()),
-            new LambdaQueryWrapper<DispatchOrder>().eq(StringUtils.hasText(customerId), DispatchOrder::getCustomerId, customerId)
+            new LambdaQueryWrapper<DispatchOrder>().eq(DispatchOrder::getCustomerId, customerId)
                 .like(StringUtils.hasText(query.dispatchNo()), DispatchOrder::getDispatchNo, query.dispatchNo())
                 .like(StringUtils.hasText(query.vehiclePlate()), DispatchOrder::getVehiclePlate, query.vehiclePlate())
                 .eq(StringUtils.hasText(query.status()), DispatchOrder::getStatus, query.status())
@@ -216,9 +233,10 @@ public class DispatchService {
     }
 
     private DispatchOrder find(String customerId, String dispatchNo) {
-        DispatchOrder dispatch = StringUtils.hasText(customerId)
-            ? orders.findByDispatchNo(customerId, dispatchNo)
-            : orders.findAnyByDispatchNo(dispatchNo);
+        if (!StringUtils.hasText(customerId)) {
+            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Dispatch order not found");
+        }
+        DispatchOrder dispatch = orders.findByDispatchNo(customerId, dispatchNo);
         if (dispatch == null) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Dispatch order not found");
         return dispatch;
     }

lastleg-service/src/main/resources/application.yml

@@ -34,6 +34,12 @@ spring:
     password: ${LASTLEG_DB_PASSWORD:123456}
 management.endpoints.web.exposure.include: health,info,prometheus
 
+lastleg:
+  dispatch-query-api:
+    enabled: ${LASTLEG_DISPATCH_QUERY_API_ENABLED:true}
+  smart-dispatch-api:
+    enabled: ${LASTLEG_SMART_DISPATCH_API_ENABLED:true}
+
 baiyue:
   clients:
     domestic-warehouse:

lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml

@@ -3,6 +3,55 @@ info:
   title: Lastleg Overseas Business API
   version: 1.0.0
 paths:
+  /api/platform/v1/last-leg/dispatches:
+    get:
+      summary: 分页查询排车单
+      description: 权限 platform:overseas-warehouse:inbound-order:list；服务端仅在当前部署恰好存在一个客户范围时查询，前端不传 customerId。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
+        - { name: dispatchNo, in: query, schema: { type: string } }
+        - { name: vehiclePlate, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { type: string } }
+        - { name: fbaAppointmentNo, in: query, schema: { type: string } }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的排车单分页，records 元素为 DispatchResponse }
+        '409': { description: 当前部署检测到多个客户范围，拒绝跨客户查询 }
+  /api/platform/v1/last-leg/dispatches/{dispatchNo}:
+    get:
+      summary: 查询排车单详情
+      description: 权限 platform:overseas-warehouse:inbound-order:list；服务端解析唯一客户范围，前端不传 customerId。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: dispatchNo, in: path, required: true, schema: { type: string } }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的 DispatchResponse }
+        '404': { description: 排车单不存在 }
+        '409': { description: 当前部署检测到多个客户范围 }
+  /api/platform/v1/last-leg/dispatches/candidates:
+    get:
+      summary: 查询智能排车候选托盘
+      description: 权限 platform:overseas-warehouse:inbound-order:list；服务端解析唯一客户范围，仅返回尚未被有效排车锁定的计划或已实收托盘，前端不传 customerId。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: orderNo, in: query, schema: { type: string } }
+        - { name: fbaWarehouseCode, in: query, schema: { type: string } }
+        - { name: sourceStage, in: query, schema: { type: string, enum: [PLAN, RECEIVED] } }
+      responses:
+        '200':
+          description: 统一 ApiResponse 包装的候选托盘数组
+          content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/SmartDispatchCandidate' } } } }
+  /api/platform/v1/last-leg/dispatches/pre-arrange:
+    post:
+      summary: 创建智能预排车单
+      description: 权限 platform:overseas-warehouse:inbound-order:edit；服务端解析唯一客户范围，锁定同一海外仓的所选托盘并创建 PENDING_DEPARTURE 排车单，前端不传 customerId；不开放编辑、取消、depart、PDA 出库或派送。
+      security: [{ bearerAuth: [] }]
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/SmartDispatchPreArrange' } } }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的预排车详情, content: { application/json: { schema: { $ref: '#/components/schemas/DispatchResponse' } } } }
   /api/platform/v1/last-leg/overseas-procurements:
     get:
       summary: 分页查询海外采购订单
@@ -212,6 +261,81 @@ paths:
       responses: { '200': { description: 统一 ApiResponse 包装的换标单详情 }, '409': { description: 非法状态迁移或关联尾程单缺失 } }
 components:
   schemas:
+    SmartDispatchCandidate:
+      type: object
+      properties:
+        planId: { type: string }
+        planPalletId: { type: string }
+        warehousePalletId: { type: string, nullable: true }
+        orderId: { type: string }
+        overseasWarehouseId: { type: string }
+        overseasWarehouseName: { type: string }
+        orderNo: { type: string }
+        orderRefs: { type: string }
+        inboundCode: { type: string }
+        palletNo: { type: string }
+        destinationWarehouseId: { type: string }
+        destinationWarehouseCode: { type: string }
+        destinationWarehouseName: { type: string }
+        fbaWarehouseCode: { type: string }
+        packageCount: { type: integer }
+        volumeCbm: { type: number }
+        sourceStage: { type: string, enum: [PLAN, RECEIVED] }
+    SmartDispatchPreArrange:
+      type: object
+      required: [planPalletIds]
+      properties:
+        planPalletIds: { type: array, minItems: 1, maxItems: 500, uniqueItems: true, items: { type: string } }
+        route: { type: string, nullable: true, maxLength: 255 }
+        fbaAppointmentNo: { type: string, nullable: true, maxLength: 64 }
+        fbaAppointmentStatus: { type: string, nullable: true, maxLength: 32, default: PENDING }
+        vehicleAppointmentStatus: { type: string, nullable: true, maxLength: 32, default: PENDING }
+    DispatchResponse:
+      type: object
+      properties:
+        id: { type: string }
+        dispatchNo: { type: string }
+        vehiclePlate: { type: string, nullable: true }
+        driverName: { type: string, nullable: true }
+        driverPhone: { type: string, nullable: true }
+        carrierName: { type: string, nullable: true }
+        orderNos: { type: string }
+        route: { type: string, nullable: true }
+        overseasWarehouseId: { type: string }
+        overseasWarehouseName: { type: string }
+        departAt: { type: string, format: date-time, nullable: true }
+        fbaAppointmentNo: { type: string, nullable: true }
+        fbaAppointmentStatus: { type: string }
+        vehicleAppointmentStatus: { type: string }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true }
+        status: { type: string, description: 预排新建固定为 PENDING_DEPARTURE；查询可返回历史排车状态 }
+        itemCount: { type: integer }
+        palletCount: { type: integer }
+        packageCount: { type: integer }
+        pickedPackageCount: { type: integer }
+        shippedPackageCount: { type: integer }
+        remainingPackageCount: { type: integer }
+        partialCompletionReason: { type: string, nullable: true }
+        createdAt: { type: string, format: date-time }
+        items: { type: array, items: { $ref: '#/components/schemas/DispatchItem' } }
+    DispatchItem:
+      type: object
+      properties:
+        id: { type: string }
+        planPalletId: { type: string }
+        warehousePalletId: { type: string, nullable: true }
+        palletNo: { type: string }
+        overseasWarehouseId: { type: string }
+        overseasWarehouseName: { type: string }
+        orderNo: { type: string }
+        orderRefs: { type: string }
+        inboundCode: { type: string }
+        destinationWarehouseCode: { type: string }
+        destinationWarehouseName: { type: string }
+        fbaWarehouseCode: { type: string }
+        packageCount: { type: integer }
+        volumeCbm: { type: number }
+        sourceStage: { type: string, enum: [PLAN, RECEIVED] }
     RelabelStatus: { type: string, enum: [PENDING_PROCESSING, PROCESSING, COMPLETED, REJECTED, CANCELLED] }
     RelabelCreate:
       type: object

lastleg-service/src/test/java/com/baiyue/lastleg/controller/Phase4BrowserApiBoundaryTest.java

@@ -3,6 +3,7 @@ package com.baiyue.lastleg.controller;
 import com.baiyue.lastleg.delivery.controller.DeliveryTransferController;
 import com.baiyue.lastleg.dispatch.controller.DispatchController;
 import com.baiyue.lastleg.dispatch.controller.DispatchQueryController;
+import com.baiyue.lastleg.dispatch.controller.SmartDispatchController;
 import com.baiyue.lastleg.dispatch.pda.controller.DispatchPdaController;
 import com.baiyue.lastleg.inboundplan.pda.controller.InboundPalletAssignmentController;
 import com.baiyue.lastleg.inboundplan.pda.controller.InboundPdaController;
@@ -11,10 +12,13 @@ import org.junit.jupiter.api.Test;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
 
 import java.util.Arrays;
 import java.util.Set;
 import java.util.stream.Collectors;
+import java.nio.file.Files;
+import java.nio.file.Path;
 
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -53,6 +57,30 @@ class Phase4BrowserApiBoundaryTest {
                 .contains(annotation.annotationType().getSimpleName())));
     }
 
+    @Test
+    void dispatchQueryIsEnabledByDefaultWithoutEnablingOutboundCommands() throws Exception {
+        String yaml = Files.readString(Path.of("src/main/resources/application.yml"));
+        assertTrue(yaml.contains("enabled: ${LASTLEG_DISPATCH_QUERY_API_ENABLED:true}"));
+        assertTrue(yaml.contains("enabled: ${LASTLEG_SMART_DISPATCH_API_ENABLED:true}"));
+        assertFalse(yaml.contains("future-outbound-api:"));
+    }
+
+    @Test
+    void smartDispatchIsIndependentlyEnabledWithOnlyCandidateAndPreArrangeEndpoints() {
+        ConditionalOnProperty condition = SmartDispatchController.class.getAnnotation(ConditionalOnProperty.class);
+        assertTrue(condition != null);
+        assertTrue(Arrays.asList(condition.name()).contains("lastleg.smart-dispatch-api.enabled"));
+        assertFalse(condition.matchIfMissing());
+        assertTrue(Arrays.stream(SmartDispatchController.class.getDeclaredMethods())
+            .filter(method -> method.isAnnotationPresent(GetMapping.class)).count() == 1);
+        assertTrue(Arrays.stream(SmartDispatchController.class.getDeclaredMethods())
+            .filter(method -> method.isAnnotationPresent(PostMapping.class)).count() == 1);
+        assertFalse(Arrays.stream(SmartDispatchController.class.getDeclaredMethods())
+            .flatMap(method -> Arrays.stream(method.getAnnotations()))
+            .anyMatch(annotation -> Set.of("PutMapping", "DeleteMapping", "PatchMapping")
+                .contains(annotation.annotationType().getSimpleName())));
+    }
+
     @Test
     void platformInventoryCommandsDoNotMapOutboundAllocationPickingOrShipping() {
         Set<String> paths = Arrays.stream(InventoryCommandController.class.getDeclaredMethods())

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/SmartDispatchOpenApiContractTest.java

@@ -0,0 +1,28 @@
+package com.baiyue.lastleg.dispatch;
+
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class SmartDispatchOpenApiContractTest {
+    @Test
+    void contractDocumentsOnlyCandidateAndPreArrangeSmartDispatchWrites() throws Exception {
+        String yaml;
+        try (var input = getClass().getResourceAsStream("/openapi/overseas-business-v1.yaml")) {
+            yaml = new String(input.readAllBytes(), StandardCharsets.UTF_8);
+        }
+        assertTrue(yaml.contains("/api/platform/v1/last-leg/dispatches/candidates:"));
+        assertTrue(yaml.contains("/api/platform/v1/last-leg/dispatches/pre-arrange:"));
+        assertTrue(yaml.contains("platform:overseas-warehouse:inbound-order:list"));
+        assertTrue(yaml.contains("platform:overseas-warehouse:inbound-order:edit"));
+        assertTrue(yaml.contains("SmartDispatchPreArrange"));
+        assertTrue(yaml.contains("SmartDispatchCandidate"));
+        String dispatchContract = yaml.substring(0,
+            yaml.indexOf("/api/platform/v1/last-leg/overseas-procurements:"));
+        assertFalse(dispatchContract.contains("name: customerId"));
+        assertFalse(yaml.contains("/api/platform/v1/last-leg/dispatches/{dispatchNo}/depart:"));
+    }
+}

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/controller/DispatchQueryControllerTest.java

@@ -4,12 +4,14 @@ import com.baiyue.common.core.api.PageResult;
 import com.baiyue.common.security.AuthenticatedUser;
 import com.baiyue.lastleg.dispatch.dto.DispatchRequests;
 import com.baiyue.lastleg.dispatch.service.DispatchService;
+import com.baiyue.lastleg.security.OverseasPermissions;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.Mock;
 import org.mockito.junit.jupiter.MockitoExtension;
 import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.server.ResponseStatusException;
 
 import java.util.List;
@@ -32,13 +34,14 @@ class DispatchQueryControllerTest {
     }
 
     @Test
-    void platformPageQueriesAllCustomersWithoutCustomerId() {
+    void platformPageUsesServerResolvedSingleCustomerWithoutCustomerId() {
         DispatchRequests.Query query = new DispatchRequests.Query(1, 20, null, null, null, null);
-        when(service.page(null, query)).thenReturn(new PageResult<>(List.of(), 1, 20, 0, 0));
+        when(service.resolveSingleCustomerScope()).thenReturn("100");
+        when(service.page("100", query)).thenReturn(new PageResult<>(List.of(), 1, 20, 0, 0));
 
         var response = controller.page(platform(), query);
 
-        verify(service).page(null, query);
+        verify(service).page("100", query);
         assertThat(response.code()).isEqualTo("200");
         assertThat(response.data().records()).isEmpty();
         assertThatThrownBy(() -> controller.page(null, query))
@@ -47,6 +50,19 @@ class DispatchQueryControllerTest {
                 ((ResponseStatusException) error).getStatusCode().value()).isEqualTo(401));
     }
 
+    @Test
+    void listAndDetailReuseInboundOrderListAuthority() throws Exception {
+        PreAuthorize page = DispatchQueryController.class
+            .getMethod("page", AuthenticatedUser.class, DispatchRequests.Query.class)
+            .getAnnotation(PreAuthorize.class);
+        PreAuthorize detail = DispatchQueryController.class
+            .getMethod("detail", AuthenticatedUser.class, String.class)
+            .getAnnotation(PreAuthorize.class);
+
+        assertThat(page.value()).contains(OverseasPermissions.INBOUND_ORDER_LIST);
+        assertThat(detail.value()).contains(OverseasPermissions.INBOUND_ORDER_LIST);
+    }
+
     private static AuthenticatedUser platform() {
         return new AuthenticatedUser(7L, 0L, 0L, 8L, "operator", "PLATFORM", "WEB", Set.of());
     }

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/controller/SmartDispatchControllerTest.java

@@ -0,0 +1,71 @@
+package com.baiyue.lastleg.dispatch.controller;
+
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.dispatch.dto.DispatchRequests;
+import com.baiyue.lastleg.dispatch.service.DispatchService;
+import com.baiyue.lastleg.security.OverseasPermissions;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.util.List;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class SmartDispatchControllerTest {
+    @Mock DispatchService service;
+    private SmartDispatchController controller;
+
+    @BeforeEach
+    void setUp() {
+        controller = new SmartDispatchController();
+        ReflectionTestUtils.setField(controller, "service", service);
+    }
+
+    @Test
+    void candidatesResolveSingleCustomerScopeWithoutRequestParameter() {
+        when(service.resolveSingleCustomerScope()).thenReturn("100");
+        when(service.candidates("100", "LMO-1", "ONT8", "PLAN")).thenReturn(List.of());
+
+        controller.candidates(platform(), "LMO-1", "ONT8", "PLAN");
+
+        verify(service).candidates("100", "LMO-1", "ONT8", "PLAN");
+    }
+
+    @Test
+    void preArrangeResolvesSingleCustomerAndAuthenticatedOperator() {
+        DispatchRequests.PreArrange request = new DispatchRequests.PreArrange(
+            List.of(10L, 11L), "ONT8 -> LAX9", "APT-1", "SUCCESS", "PENDING");
+        when(service.resolveSingleCustomerScope()).thenReturn("100");
+
+        controller.preArrange(platform(), request);
+
+        verify(service).preArrange("100", "7", request);
+    }
+
+    @Test
+    void endpointsReuseInboundOrderListAndEditAuthorities() throws Exception {
+        PreAuthorize candidates = SmartDispatchController.class
+            .getMethod("candidates", AuthenticatedUser.class, String.class, String.class, String.class)
+            .getAnnotation(PreAuthorize.class);
+        PreAuthorize preArrange = SmartDispatchController.class
+            .getMethod("preArrange", AuthenticatedUser.class, DispatchRequests.PreArrange.class)
+            .getAnnotation(PreAuthorize.class);
+
+        assertThat(candidates.value()).contains(OverseasPermissions.INBOUND_ORDER_LIST);
+        assertThat(preArrange.value()).contains(OverseasPermissions.INBOUND_ORDER_EDIT);
+    }
+
+    private static AuthenticatedUser platform() {
+        return new AuthenticatedUser(7L, 0L, 0L, 8L, "operator", "PLATFORM", "WEB",
+            Set.of(OverseasPermissions.INBOUND_ORDER_LIST, OverseasPermissions.INBOUND_ORDER_EDIT));
+    }
+}

lastleg-service/src/test/java/com/baiyue/lastleg/dispatch/service/DispatchServiceTest.java

@@ -86,6 +86,28 @@ class DispatchServiceTest {
         verify(candidates, never()).available(any(), any(), any(), any());
     }
 
+    @Test
+    void resolvesOnlyCustomerScopeAndRejectsMultipleCustomers() {
+        when(candidates.findCustomerScopes()).thenReturn(List.of("100"));
+        assertEquals("100", service.resolveSingleCustomerScope());
+
+        when(candidates.findCustomerScopes()).thenReturn(List.of("100", "200"));
+        ResponseStatusException exception = assertThrows(ResponseStatusException.class,
+            () -> service.resolveSingleCustomerScope());
+        assertEquals(409, exception.getStatusCode().value());
+    }
+
+    @Test
+    void emptyCustomerScopeProducesEmptyCandidatesAndRejectsPreArrange() {
+        assertEquals(List.of(), service.candidates(null, null, null, null));
+        verify(candidates, never()).available(any(), any(), any(), any());
+
+        ResponseStatusException exception = assertThrows(ResponseStatusException.class,
+            () -> service.preArrange(null, "7",
+                new DispatchRequests.PreArrange(List.of(10L), null, null, null, null)));
+        assertEquals(409, exception.getStatusCode().value());
+    }
+
     @Test
     void editCannotBypassPdaManagedDispatchStatus() {
         DispatchOrder dispatch = new DispatchOrder();
@@ -105,14 +127,14 @@ class DispatchServiceTest {
     }
 
     @Test
-    void platformDetailFindsDispatchGloballyAndLoadsItemsWithRecordCustomer() {
+    void detailUsesResolvedCustomerScopeAndLoadsItems() {
         DispatchOrder dispatch = new DispatchOrder();
         dispatch.setId(1L);
         dispatch.setCustomerId("200");
         dispatch.setDispatchNo("PC1");
-        when(orders.findAnyByDispatchNo("PC1")).thenReturn(dispatch);
+        when(orders.findByDispatchNo("200", "PC1")).thenReturn(dispatch);
 
-        service.detail(null, "PC1");
+        service.detail("200", "PC1");
 
         verify(items).findByDispatchOrder("200", 1L);
     }